build(deps): bump the production-weekly group across 1 directory with 7 updates (#1354)

Bumps the production-weekly group with 7 updates in the / directory:

| Package | From | To |
| --- | --- | --- |
| [@parse/node-apn](https://github.com/parse-community/node-apn) | `8.1.1` | `8.2.0` |
| [@tanstack/react-query](https://github.com/TanStack/query/tree/HEAD/packages/react-query) | `5.105.1` | `5.105.3` |
| [@tanstack/react-virtual](https://github.com/TanStack/virtual/tree/HEAD/packages/react-virtual) | `3.14.25` | `3.14.26` |
| [jose](https://github.com/panva/jose) | `6.2.14` | `6.2.15` |
| [lucide-react](https://github.com/lucide-icons/lucide/tree/HEAD/packages/lucide-react) | `1.66.0` | `1.67.0` |
| [mmdb-lib](https://github.com/runk/mmdb-lib) | `3.0.3` | `3.0.4` |
| [otpauth](https://github.com/hectorm/otpauth) | `9.5.2` | `9.6.0` |



Updates `@parse/node-apn` from 8.1.1 to 8.2.0
- [Release notes](https://github.com/parse-community/node-apn/releases)
- [Changelog](https://github.com/parse-community/node-apn/blob/master/CHANGELOG.md)
- [Commits](https://github.com/parse-community/node-apn/compare/8.1.1...8.2.0)

Updates `@tanstack/react-query` from 5.105.1 to 5.105.3
- [Release notes](https://github.com/TanStack/query/releases)
- [Changelog](https://github.com/TanStack/query/blob/main/packages/react-query/CHANGELOG.md)
- [Commits](https://github.com/TanStack/query/commits/@tanstack/react-query@5.105.3/packages/react-query)

Updates `@tanstack/react-virtual` from 3.14.25 to 3.14.26
- [Release notes](https://github.com/TanStack/virtual/releases)
- [Changelog](https://github.com/TanStack/virtual/blob/main/packages/react-virtual/CHANGELOG.md)
- [Commits](https://github.com/TanStack/virtual/commits/@tanstack/react-virtual@3.14.26/packages/react-virtual)

Updates `jose` from 6.2.14 to 6.2.15
- [Release notes](https://github.com/panva/jose/releases)
- [Changelog](https://github.com/panva/jose/blob/main/CHANGELOG.md)
- [Commits](https://github.com/panva/jose/compare/v6.2.14...v6.2.15)

Updates `lucide-react` from 1.66.0 to 1.67.0
- [Release notes](https://github.com/lucide-icons/lucide/releases)
- [Commits](https://github.com/lucide-icons/lucide/commits/1.67.0/packages/lucide-react)

Updates `mmdb-lib` from 3.0.3 to 3.0.4
- [Release notes](https://github.com/runk/mmdb-lib/releases)
- [Commits](https://github.com/runk/mmdb-lib/compare/v3.0.3...v3.0.4)

Updates `otpauth` from 9.5.2 to 9.6.0
- [Release notes](https://github.com/hectorm/otpauth/releases)
- [Commits](https://github.com/hectorm/otpauth/compare/v9.5.2...v9.6.0)

---
updated-dependencies:
- dependency-name: "@parse/node-apn"
  dependency-version: 8.2.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: production-weekly
- dependency-name: "@tanstack/react-query"
  dependency-version: 5.105.3
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: production-weekly
- dependency-name: "@tanstack/react-virtual"
  dependency-version: 3.14.26
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: production-weekly
- dependency-name: jose
  dependency-version: 6.2.15
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: production-weekly
- dependency-name: lucide-react
  dependency-version: 1.67.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: production-weekly
- dependency-name: mmdb-lib
  dependency-version: 3.0.4
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: production-weekly
- dependency-name: otpauth
  dependency-version: 9.6.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: production-weekly
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.dockerignore

@@ -28,6 +28,12 @@ playwright/.cache
 playwright.config.ts
 vitest.config.mts
 vitest.integration.config.mts
+vitest.mutation.config.mts
+# The unit setup imports tests/ (excluded above); the image never runs it and
+# the build's type check must not see a half-present test harness.
+vitest.setup.ts
+stryker.config.mjs
+stryker.floors.json
 tests
 tests/
 e2e

.env.example

@@ -38,6 +38,13 @@
 #   echo "POSTGRES_PASSWORD=$(openssl rand -hex 32)" >> .env
 # Left commented here so that append does not create a duplicate key. Uncomment
 # and set it directly instead if you prefer to edit the file by hand.
+
+# The container runs the app as `healthlog_app_<database>_<hash>`, a database
+# role it creates on every start that reads and writes rows but cannot change
+# the schema. The
+# migrations keep the DATABASE_URL user. "off" keeps the app on that user, if
+# you manage database roles yourself (docs/self-hosting/database-role.md).
+# DB_APP_ROLE="off"
 # POSTGRES_PASSWORD="generate-with-openssl-rand-hex-32"
 
 
@@ -62,6 +69,18 @@ NODE_ENV="development"
 # internet; the session cookie crosses the wire in cleartext.
 # SESSION_COOKIE_SECURE="false"
 
+# Where this server's environment is configured: compose, truenas, coolify,
+# unraid or portainer. Only picks which instructions the admin's "Back up
+# your encryption key" step shows first; unset means compose.
+# HEALTHLOG_PLATFORM="compose"
+
+# Start-up encryption key check: enforce (default) refuses to serve when the
+# key does not open the stored data; warn only logs it and serves anyway. A
+# last resort for a refusal you are certain is false (a first start, with no
+# recorded key to reset). It disables a safety check: with a wrong key every
+# encrypted value fails and new rows are written under that key.
+# ENCRYPTION_KEY_CHECK="enforce"
+
 
 # -----------------------------------------------------------------------------
 # Required Secrets — generate with `openssl rand -hex 32`
@@ -166,6 +185,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=""
@@ -182,7 +209,10 @@ API_TOKEN_HMAC_KEY="REPLACE-WITH-OUTPUT-OF-openssl-rand-hex-32"
 #
 # Set this to "1" ONLY when every public request to HealthLog terminates
 # at Cloudflare (Tunnel, Workers, classic proxy) before it reaches your
-# origin. Deployments behind nginx, Caddy, Traefik, an AWS ALB, or any
+# origin, and the origin accepts connections from Cloudflare alone (a
+# Tunnel, or a firewall that admits only Cloudflare's address ranges): the
+# header is believed from every connection, before any other check.
+# Deployments behind nginx, Caddy, Traefik, an AWS ALB, or any
 # direct-to-Next.js exposure MUST leave this off.
 #
 # Security implications when the flag is mis-set:
@@ -204,10 +234,19 @@ API_TOKEN_HMAC_KEY="REPLACE-WITH-OUTPUT-OF-openssl-rand-hex-32"
 # Number of trusted reverse-proxy hops in front of the app. The client IP is
 # read that many entries from the right of the X-Forwarded-For chain. Set 0
 # for a directly-exposed host; 1 (the default when unset) behind a single
-# reverse proxy. X-Real-IP is read only at 1. A wrong value makes the app
+# reverse proxy. X-Real-IP is read only at 1. Forwarding headers are read only
+# from a connection whose own address is not public (loopback, private, CGNAT,
+# unique-local, link-local, reserved or multicast; the full list is in
+# docs/self-hosting/reverse-proxy.md). A wrong value makes the app
 # refuse the headers, log one warning, and share one rate-limit bucket across
 # all anonymous callers.
 # TRUST_PROXY_HOPS="1"
+# The addresses the reverse proxy connects from (comma-separated CIDRs). Set,
+# only those connections may report the client's address; unset, any private
+# address may, which behind Docker Desktop, OrbStack or docker-proxy includes
+# every caller of the published port. Same host: 127.0.0.1/32,::1/128; Docker
+# network: the proxy's subnet. See docs/self-hosting/reverse-proxy.md.
+# TRUSTED_PROXY_CIDRS=""
 # TRUST_CF_CONNECTING_IP=""
 
 
@@ -257,6 +296,33 @@ API_TOKEN_HMAC_KEY="REPLACE-WITH-OUTPUT-OF-openssl-rand-hex-32"
 # BACKUP_ENCRYPTION_KEY=""          # 64-hex-char or base64 32-byte; SEPARATE from ENCRYPTION_KEY
 # BACKUP_ENCRYPTION_PREVIOUS_KEYS="" # retired off-host keys, comma-separated, read-only during a rotation
 
+# -----------------------------------------------------------------------------
+# Database dumps (optional, on by default)
+# -----------------------------------------------------------------------------
+# The whole-database dump that rebuilds a lost server: nightly, and before
+# every update that brings migrations. Written to DB_BACKUP_DIR with a
+# manifest beside it (row counts, key fingerprints, versions); with the
+# off-host bucket above set, each nightly dump is also uploaded under
+# `database/`, sealed with BACKUP_ENCRYPTION_KEY. Local dumps are not
+# encrypted: they sit beside the database volume, in the same trust zone.
+# Restore: `docker compose run --rm db-restore latest`. See
+# docs/ops/disaster-recovery.md.
+#
+# Set "false" to stop the nightly dump.
+# DB_BACKUP_ENABLED="true"
+# Where dumps are written. The bundled compose file mounts the `backups`
+# volume here; change it only together with that mount. In a container a
+# directory that is not on a mount of its own sits in the container's layer
+# and is lost at the next update, so no dump is kept there.
+# DB_BACKUP_DIR="/var/lib/healthlog/backups"
+# Five-field cron, in Europe/Berlin time like every scheduled job.
+# DB_BACKUP_SCHEDULE="30 1 * * *"
+# Nightly dumps kept (at least 1). The last two pre-migration dumps are kept
+# besides.
+# DB_BACKUP_KEEP="7"
+# Set "false" to start an update without the dump before its migrations.
+# DB_BACKUP_BEFORE_MIGRATE="true"
+
 # -----------------------------------------------------------------------------
 # Stored backups in the database (optional)
 # -----------------------------------------------------------------------------
@@ -308,11 +374,21 @@ API_TOKEN_HMAC_KEY="REPLACE-WITH-OUTPUT-OF-openssl-rand-hex-32"
 # Auto-deploy webhook (v1.4.15 — phase C2)
 # -----------------------------------------------------------------------------
 # Coolify (or any CI) pings POST /api/internal/deploy-webhook after a deploy
-# attempt with success/failure. We verify the request via this shared secret
-# carried in the `X-Deploy-Webhook-Secret` header (timing-safe compare).
-# Generate with `openssl rand -hex 32`. Configure the SAME value in Coolify's
-# Notifications → Webhook custom-headers panel. See docs/audit/v1415-auto-deploy.md.
+# attempt with success/failure. A request authenticates with this shared
+# secret in the `X-Deploy-Webhook-Secret` header (timing-safe compare; what
+# Coolify's stock sender does, with no replay protection), or by signing:
+# `X-Deploy-Webhook-Signature: sha256=<hex>`, the HMAC-SHA256 under this
+# secret of the `X-Deploy-Webhook-Timestamp` value, a dot and the raw body,
+# the timestamp within 5 minutes. Generate with `openssl rand -hex 32`.
+# Configure the SAME value in Coolify's Notifications → Webhook
+# custom-headers panel. See docs/ops/deploy.md.
 # DEPLOY_WEBHOOK_SECRET=""
+# "true" also requires a fresh X-Deploy-Webhook-Timestamp on a secret-header
+# request; leave unset for Coolify's stock sender, which sends none.
+# DEPLOY_WEBHOOK_REQUIRE_TIMESTAMP=""
+# "true" accepts signed requests only (the setting that stops a replay);
+# leave unset for Coolify's stock sender.
+# DEPLOY_WEBHOOK_REQUIRE_SIGNATURE=""
 
 
 # -----------------------------------------------------------------------------

.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=""
@@ -257,6 +270,24 @@ API_TOKEN_HMAC_KEY="<openssl rand -hex 32>"
 # SESSION_COOKIE_SECURE="false"
 
 
+# -----------------------------------------------------------------------------
+# Platform hint for the encryption key backup step
+# -----------------------------------------------------------------------------
+# Where this server's environment lives: compose, truenas, coolify, unraid or
+# portainer. The admin's "Back up your encryption key" step opens on the
+# instructions for that platform. Unset means compose. Catalog templates set
+# it for you.
+# HEALTHLOG_PLATFORM="compose"
+
+# Start-up encryption key check: enforce (default) refuses to serve when the
+# key does not open the stored data; warn only logs it, reports it as a
+# warning on /api/health, and serves anyway. A last resort for a refusal you
+# are certain is false (a first start, with no recorded key to reset). It
+# disables a safety check: with a wrong key every encrypted value fails and
+# new rows are written under that key. Remove it once the key is confirmed.
+# ENCRYPTION_KEY_CHECK="enforce"
+
+
 # -----------------------------------------------------------------------------
 # Deploy webhook -- Coolify -> HealthLog auto-deploy feedback
 # -----------------------------------------------------------------------------
@@ -264,11 +295,17 @@ API_TOKEN_HMAC_KEY="<openssl rand -hex 32>"
 # Optional: deployment-dashboard URL (e.g. the Coolify UI) linked in
 # deploy-failure notifications. When unset the notification omits the link.
 # DEPLOY_LOGS_URL=""
-# Optional replay hardening: require a fresh X-Deploy-Webhook-Timestamp
-# header (unix seconds / ms or ISO-8601, +/- 5 minutes) on every webhook
-# call. Leave unset for Coolify's stock sender (it attaches no
-# timestamp); see docs/ops/deploy.md.
+# Optional: require an X-Deploy-Webhook-Timestamp within +/- 5 minutes on a
+# request that authenticates with the secret header. Keeps a stale capture
+# out, not a fresh forgery by someone who saw the secret. Leave unset for
+# Coolify's stock sender, which sends no timestamp.
 # DEPLOY_WEBHOOK_REQUIRE_TIMESTAMP="false"
+# Optional replay protection: accept only signed webhook calls
+# (X-Deploy-Webhook-Signature, an HMAC of the timestamp and body under the
+# secret, with a timestamp within +/- 5 minutes); the secret header alone is
+# refused. Leave unset for Coolify's stock sender, which can only send the
+# secret header; see docs/ops/deploy.md.
+# DEPLOY_WEBHOOK_REQUIRE_SIGNATURE="false"
 
 
 # -----------------------------------------------------------------------------
@@ -309,6 +346,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
@@ -331,11 +375,11 @@ API_TOKEN_HMAC_KEY="<openssl rand -hex 32>"
 # per-user BYO keys keep the pinned public-host posture either way.
 # ADMIN_AI_BASE_URL_ALLOWLIST=""
 
-# Codex (ChatGPT sign-in) model slugs. CODEX_MODEL pins one slug ahead of the
-# built-in chain; CODEX_MODEL_FALLBACK_CHAIN replaces the chain outright
-# (comma-separated, first match wins). Reach for these when the provider
-# rotates a slug and requests start failing with 503 -- without them a
-# rotation needs a new release to fix.
+# Codex (ChatGPT sign-in) model slugs. Left unset, each sign-in picks from
+# the models its account is offered (read from the provider the way the Codex
+# CLI reads it), with a built-in order as the fallback. CODEX_MODEL pins one
+# slug ahead of that; CODEX_MODEL_FALLBACK_CHAIN replaces the order outright
+# (comma-separated, first match wins) and the account's list is then not read.
 # CODEX_MODEL=""
 # CODEX_MODEL_FALLBACK_CHAIN=""
 
@@ -376,6 +420,33 @@ API_TOKEN_HMAC_KEY="<openssl rand -hex 32>"
 # key once the lifecycle rule has retired every object written under it.
 # BACKUP_ENCRYPTION_PREVIOUS_KEYS=""
 
+# -----------------------------------------------------------------------------
+# Database dumps (optional, on by default)
+# -----------------------------------------------------------------------------
+# The whole-database dump that rebuilds a lost server: nightly, and before
+# every update that brings migrations. Written to DB_BACKUP_DIR with a
+# manifest beside it (row counts, key fingerprints, versions); with the
+# off-host bucket above set, each nightly dump is also uploaded under
+# `database/`, sealed with BACKUP_ENCRYPTION_KEY. Local dumps are not
+# encrypted: they sit beside the database volume, in the same trust zone.
+# Restore: `docker compose run --rm db-restore latest`. See
+# docs/ops/disaster-recovery.md.
+#
+# Set "false" to stop the nightly dump.
+# DB_BACKUP_ENABLED="true"
+# Where dumps are written. The bundled compose file mounts the `backups`
+# volume here; change it only together with that mount. In a container a
+# directory that is not on a mount of its own sits in the container's layer
+# and is lost at the next update, so no dump is kept there.
+# DB_BACKUP_DIR="/var/lib/healthlog/backups"
+# Five-field cron, in Europe/Berlin time like every scheduled job.
+# DB_BACKUP_SCHEDULE="30 1 * * *"
+# Nightly dumps kept (at least 1). The last two pre-migration dumps are kept
+# besides.
+# DB_BACKUP_KEEP="7"
+# Set "false" to start an update without the dump before its migrations.
+# DB_BACKUP_BEFORE_MIGRATE="true"
+
 # -----------------------------------------------------------------------------
 # Stored backups in the database (optional)
 # -----------------------------------------------------------------------------
@@ -408,6 +479,16 @@ API_TOKEN_HMAC_KEY="<openssl rand -hex 32>"
 # 90 rather than repeat the default.
 # COACH_MESSAGE_RETENTION_DAYS="365"
 
+# How long deleting an account, a managed profile or "all data" stays
+# undoable, in days. Default 14, ceiling 30. The account is locked at once
+# (signed out everywhere, sign-in refused, nothing runs for it) and an admin
+# can undo the deletion from the users list until the window ends; the purge
+# job erases it then, together with its stored and off-host copies. A wipe
+# keeps a copy of the record an admin can restore for the same time. 0 erases
+# immediately, as releases before 1.46 did. The Data & Privacy page states
+# this number, so it has to reach the container.
+# ACCOUNT_DELETION_GRACE_DAYS="14"
+
 # How long the host CPU/memory samples behind the admin monitoring charts are
 # kept, in days. Default 7. Raise it for a longer trend; lower it on a host
 # where disk is the scarce resource.
@@ -432,6 +513,27 @@ 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"
+#
+# The app runs as `healthlog_app_<database>_<hash>`, a database role the
+# container creates for this database on every start: it reads and writes
+# rows but cannot alter or drop tables, own anything, or create roles. Migrations and restores still use the user in DATABASE_URL.
+# Where that user may not create roles (a managed database), the start log
+# says so and the app uses DATABASE_URL as given. Set "off" if you manage
+# the database roles yourself. See docs/self-hosting/database-role.md.
+# DB_APP_ROLE="off"
 
 
 # -----------------------------------------------------------------------------
@@ -466,21 +568,53 @@ API_TOKEN_HMAC_KEY="<openssl rand -hex 32>"
 # -----------------------------------------------------------------------------
 # Client-IP resolution -- optional (required behind Cloudflare)
 # -----------------------------------------------------------------------------
-# When the stack sits behind Cloudflare, the real visitor IP arrives in the
-# `cf-connecting-ip` header; the X-Forwarded-For chain otherwise yields the
-# Cloudflare edge IP, so the audit-log overview stores the CF datacentre
-# address and the geo lookup resolves the wrong location. Set this to "1"
-# ONLY when Cloudflare is in front -- a direct-exposed self-host must leave
-# it unset, or an attacker could forge the header. Off by default.
 # Number of trusted reverse-proxy hops in front of the app; the client IP is
 # read that many entries from the right of the X-Forwarded-For chain. 0 for a
-# directly-exposed host, 1 (the default when unset) behind a single reverse
-# proxy; X-Real-IP is read only at 1. A wrong value makes the app refuse the
-# headers, log one warning, and collapse anonymous callers into one
-# rate-limit bucket.
+# directly-exposed host (the connection's own address is used), 1 (the
+# default when unset) behind a single reverse proxy; X-Real-IP is read only
+# at 1. Forwarding headers are read only from a connection whose own address
+# is not public: loopback, private, CGNAT, unique-local, link-local, reserved
+# or multicast (the full list is in docs/self-hosting/reverse-proxy.md). A
+# wrong value makes the app refuse the headers, log one warning, and collapse
+# anonymous callers into one rate-limit bucket.
 # TRUST_PROXY_HOPS="1"
+#
+# The addresses your reverse proxy connects from, as comma-separated CIDRs
+# (IPv4 or IPv6; a bare address is one host). When set, only those
+# connections may report the client's address; every other connection is
+# its own client. When unset, any private address may, which is the old
+# behaviour and is NOT safe behind Docker Desktop, OrbStack or docker-proxy:
+# there every caller of the published port arrives from the gateway, a
+# private address, and could name its own client address. Set it whenever a
+# reverse proxy is in front:
+#   proxy on the same host (proxying to 127.0.0.1:3000): 127.0.0.1/32,::1/128
+#   proxy container on a Docker network: that network's subnet (docker
+#     network inspect <network>), e.g. 172.18.0.0/16
+#   proxy on another machine with a public address: that address, /32
+# A proxy on a public address that is not listed is not believed: every
+# request through it shares the proxy's address and one rate-limit bucket.
+# The boot log names the rule in force in one [proxy-trust] line.
+# TRUSTED_PROXY_CIDRS="127.0.0.1/32,::1/128"
+#
+# Behind Cloudflare the real visitor IP arrives in the `cf-connecting-ip`
+# header; the X-Forwarded-For chain otherwise yields the Cloudflare edge IP,
+# so the audit-log overview stores the CF datacentre address and the geo
+# lookup resolves the wrong location. "1" believes that header from EVERY
+# connection, before the checks above, so set it ONLY when the origin accepts
+# connections from Cloudflare alone (a Cloudflare Tunnel, or a firewall that
+# admits only Cloudflare's address ranges). An origin that also answers on
+# its own public address lets any caller forge the address that rate limits
+# and the audit log record. Off by default.
 # 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. 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"
+
 # -----------------------------------------------------------------------------
 # Outbound requests HealthLog makes on its own -- optional switches
 # -----------------------------------------------------------------------------
@@ -568,14 +702,28 @@ 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
-# WITHOUT AVX2 (Celeron/Atom-class NAS CPUs) it is disabled automatically and
-# those features degrade cleanly (no thumbnails; scanned PDFs read as text
-# only). Override only if auto-detection misfires:
+# On x86-64 the renderer is enabled only on CPUs with AVX2. On older chips
+# (Celeron/Atom-class NAS CPUs) it is disabled automatically and those features
+# degrade cleanly: no thumbnails, and an AI provider that cannot take PDF files
+# reads a PDF by its text layer, so a scanned PDF needs a provider that takes
+# PDFs directly (Anthropic) or photos of its pages. On arm64 the published image
+# renders on every 64-bit core, the Raspberry Pi 4 included. Only a musl
+# (Alpine) build of your own needs ARMv8.2 (LSE atomics, RCpc) and is gated the
+# same way. Override only if auto-detection misfires:
 #   off — force-disable the renderer
-#   on  — force-enable (crashes the container if the CPU truly lacks AVX2)
+#   on  — force-enable (crashes PDF processing if the CPU truly lacks them)
 # NATIVE_CANVAS="off"
 
 
@@ -593,6 +741,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/config.yml

@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
+  - name: Ideas and upvotes
+    url: https://github.com/MBombeck/HealthLog/discussions/categories/ideas?discussions_q=category%3AIdeas+sort%3Atop
+    about: Suggest an improvement or upvote the ones you want. One idea per discussion; the most-voted ones get looked at first.
   - name: Documentation
     url: https://docs.healthlog.dev
     about: Setup, configuration, and feature documentation. Most usage questions are answered here.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -6,7 +6,7 @@ body:
   - type: markdown
     attributes:
       value: |
-        Feature ideas welcome. HealthLog is a personal-health PWA — the bar for inclusion is high (privacy-first, offline-capable, self-hostable). Use this template to propose something concrete; for open-ended discussion, prefer a [Discussion](https://github.com/MBombeck/HealthLog/discussions) thread.
+        Feature ideas welcome. HealthLog is a personal-health PWA, and the bar for inclusion is high (privacy-first, offline-capable, self-hostable). Use this template to propose something concrete. For an idea you'd like others to weigh in on, or a small improvement, start it in [Ideas](https://github.com/MBombeck/HealthLog/discussions/categories/ideas) instead: people can upvote it there, and the most-voted ideas get looked at first (see #1114).
   - type: textarea
     id: problem
     attributes:

.github/ISSUE_TEMPLATE/translation.yml

@@ -1,16 +1,16 @@
 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 community-maintained locales (FR / ES / IT / PL / KO / NL / PT-BR).
 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, Dutch, and Brazilian Portuguese ship as **AI-initial, community-maintained translations** — the prose passes the locale-integrity test (full key parity, no empty values) but has not been hand-reviewed for register or regional vocabulary.
 
         This template captures concrete fixes you would like to see. Phrasing nuance, regional vocabulary (e.g. "Tú" vs "Usted"), gendered forms, and domain-specific health terms are all in scope. The maintainer applies fixes during the regular release cycle.
 
-        For wholly new locale requests (e.g. "please add Portuguese"), open a [Discussion](https://github.com/MBombeck/HealthLog/discussions) instead.
+        For wholly new locale requests (e.g. "please add Swedish"), open a [Discussion](https://github.com/MBombeck/HealthLog/discussions) instead.
   - type: dropdown
     id: locale
     attributes:
@@ -20,6 +20,9 @@ body:
         - Spanish (es)
         - Italian (it)
         - Polish (pl)
+        - Korean (ko)
+        - Dutch (nl)
+        - Brazilian Portuguese (pt-BR)
         - 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:
@@ -29,6 +64,21 @@ updates:
     schedule:
       interval: "weekly"
     open-pull-requests-limit: 3
+    ignore:
+      # The Dockerfile's `pgclient` stage carries pg_dump and pg_restore of
+      # the bundled database's major. A major bump there is part of the same
+      # migration decision as the database itself, and the runner's paths and
+      # version checks name major 18, so it arrives by hand, not as a PR. Its
+      # minor moves with the database's in docker-compose.yml
+      # (runtime-package-pins.test.ts fails while the two differ).
+      - dependency-name: "postgres"
+        update-types: ["version-update:semver-major"]
+      # The Node major in the build and runner stages is the one `engines`,
+      # `.nvmrc` and `.node-version` name, and the native modules are built
+      # against it. Moving it is a release decision, so it arrives by hand.
+      # Digest and minor updates of the pinned major still come as PRs.
+      - dependency-name: "node"
+        update-types: ["version-update:semver-major"]
   # The `docker` ecosystem above reads the Dockerfile only. The bundled
   # database lives in `docker-compose.yml`, which GitHub treats as its own
   # ecosystem, so without this block a new PostgreSQL minor release never
@@ -44,6 +94,8 @@ updates:
       # The first run of this ecosystem proposed 16.15 -> 18.6, which would
       # have handed self-hosters a database their data directory cannot be
       # read by. Minor releases still arrive as PRs; a major is a deliberate
-      # project decision with a migration guide behind it.
+      # project decision with a migration guide behind it. The ignore also
+      # keeps `db-upgrade` on 16: it exists to read Postgres 16 data, and a
+      # bump to 18 would leave it unable to start on the volume it moves.
       - dependency-name: "postgres"
         update-types: ["version-update:semver-major"]

.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@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
         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@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
         with:
           category: "/language:javascript-typescript"

.github/workflows/compose-db-upgrade.yml

@@ -0,0 +1,51 @@
+name: Compose database move
+
+# Plays the Postgres 16 -> 18 move in docker-compose.yml against real
+# containers: a v1.45 database with every migration applied, then the current
+# compose file's `db-upgrade` on its first start, a second start, a move cut
+# short, an emptied new volume and a new install. The service runs once on an
+# operator's host and has no second chance there, so every change to the
+# compose file or to the check runs it here first.
+# `scripts/compose-db-upgrade-check.sh` is the same check, runnable locally.
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - docker-compose.yml
+      - scripts/compose-db-upgrade-check.sh
+      - .github/workflows/compose-db-upgrade.yml
+  push:
+    branches: [main]
+    paths:
+      - docker-compose.yml
+      - scripts/compose-db-upgrade-check.sh
+      - .github/workflows/compose-db-upgrade.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  move:
+    name: Postgres 16 -> 18 move
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      # The check reads the v1.45 compose file from its tag.
+      - name: Fetch the v1.45.0 tag
+        run: git fetch --no-tags --depth=1 origin tag v1.45.0
+
+      - 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
+
+      - name: Move check
+        run: bash scripts/compose-db-upgrade-check.sh

.github/workflows/compose-dr-drill.yml

@@ -0,0 +1,70 @@
+name: Disaster recovery drill
+
+# Rebuilds a lost server from the nightly database dump and the keys alone,
+# against real containers: the app image built from this checkout, the
+# bundled compose file with an S3-compatible bucket outside it, the demo seed
+# plus a Guardian with a managed profile, the dump taken and uploaded by the
+# scheduled job, every volume of the stack destroyed, a new stack, the
+# restore, and the app booted on the result (health, login, an encrypted
+# note, a document, the Guardian's profile, every table's row count against
+# the manifest). Two sources: from the bucket (`db-restore latest
+# --from-bucket`, the disaster path) and from dump files copied off the host
+# (`db-restore latest`).
+# `scripts/compose-dr-drill.sh` is the same drill, runnable locally; its
+# header lists what it checks and the mutations that must turn it red.
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - docker-compose.yml
+      - Dockerfile
+      - docker-entrypoint.sh
+      - scripts/compose-dr-drill.sh
+      - scripts/dr-drill-seed.ts
+      - scripts/db-dump.mjs
+      - scripts/db-restore.mjs
+      - scripts/pending-migrations.mjs
+      - src/lib/database-backup/**
+      - src/lib/jobs/database-backup-queue.ts
+      - src/lib/jobs/reminder/backup-handlers.ts
+      - .github/workflows/compose-dr-drill.yml
+  schedule:
+    # Nightly, 02:41 UTC: off the hour, after the evening merges.
+    - cron: "41 2 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: compose-dr-drill-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  drill:
+    name: Restore a lost server from its dump (${{ matrix.source }})
+    runs-on: ubuntu-24.04
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        source: [bucket, local]
+    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
+
+      # The seed scripts run from the checkout against the drill's database.
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm db:generate
+
+      - name: Drill
+        env:
+          DRILL_SOURCE: ${{ matrix.source }}
+        run: bash scripts/compose-dr-drill.sh

.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
@@ -150,7 +150,7 @@ jobs:
       # Image is built but not pushed in that case.
       - name: Log in to GitHub Container Registry
         if: github.event_name != 'pull_request'
-        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -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-*
@@ -350,7 +350,7 @@ jobs:
           echo "IMAGE_REF=${REGISTRY}/${IMAGE_NAME,,}" >> "$GITHUB_ENV"
 
       - name: Log in to GitHub Container Registry
-        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -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:
@@ -33,13 +40,11 @@ jobs:
     name: e2e shard ${{ matrix.shard }}/3
     services:
       postgres:
-        image: postgres:16-alpine
+        image: postgres:18-alpine
         env:
           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,126 @@ 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
+      AUTH_RP_NAME: HealthLog
+      AUTH_RP_ID: localhost
+      AUTH_RP_ORIGIN: http://localhost:3000
+      SESSION_COOKIE_SECURE: "false"
+      NODE_ENV: production
+      # The WebKit specs run 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@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm db:generate
+
+      - run: pnpm db:migrate:deploy
+
+      # `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
+      # them every UI interaction waits on missing catalogs.
+      # The repository-wide Next type worker exceeds V8's ~4 GiB default
+      # old-space ceiling. Keep the larger heap scoped to this production
+      # build only; tests and the runtime retain their normal limits.
+      - run: NODE_OPTIONS=--max-old-space-size=8192 pnpm build
+
+      # Client-bundle budget gate — rides this job because it is the one
+      # place CI already has a production build on disk. Measures the first
+      # load of every page (files deduplicated by content hash) against its
+      # baseline, the p95 and max across pages, and the distinct client code
+      # (modules deduplicated by id); see the script header. Catches a
+      # statically imported message catalog, a duplicated recharts chunk, or
+      # a heavy module (Zod) pulled into a page that had none.
+      - run: pnpm bundle-check
+
+      - run: pnpm exec playwright test --shard=${{ matrix.shard }}/3
+        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-shard-${{ matrix.shard }}
+          path: playwright-report/
+          retention-days: 7
+          if-no-files-found: ignore
+
+      # The machine-readable report, for the skipped-spec check in the gate
+      # 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@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 specs, in the same image as the shards: the bottom sheet on an
+  # iPhone (`bottom-sheet.spec.ts`, project `webkit-iphone`) and the app shell
+  # on an iPad (`tablet-shell.spec.ts`, project `webkit-tablet`).
+  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:18-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
@@ -60,9 +184,13 @@ jobs:
     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,70 +201,43 @@ 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
-      # them every UI interaction waits on missing catalogs.
-      # The repository-wide Next type worker exceeds V8's ~4 GiB default
-      # old-space ceiling. Keep the larger heap scoped to this production
-      # build only; tests and the runtime retain their normal limits.
       - run: NODE_OPTIONS=--max-old-space-size=8192 pnpm build
 
-      # Client-bundle budget gate — rides this job because it is the one
-      # place CI already has a production build on disk. Catches the
-      # regressions the dead webpack-era tooling (ANALYZE=1, the old
-      # bundle-report) let through: a statically imported message catalog
-      # (~100 KB gz on every route) or a chart import bypassing the shared
-      # chart-runtime boundary (a duplicated ~92 KB gz recharts chunk).
-      - run: pnpm bundle-check
-
-      - run: pnpm exec playwright test --shard=${{ matrix.shard }}/3
+      - run: pnpm exec playwright test --project=webkit-iphone --project=webkit-tablet
         env:
           E2E_BASE_URL: http://localhost:3000
 
       - 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 }}
+          name: playwright-report-webkit
           path: playwright-report/
           retention-days: 7
           if-no-files-found: ignore
 
-      # The machine-readable report, for the skipped-spec check in the gate
-      # 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 }}
+          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 +247,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

@@ -10,20 +10,23 @@ permissions:
   contents: read
 
 jobs:
-  # The suite outgrew a single runner, then a half-suite outgrew a slow one,
-  # and then a third of it did too. Three shards of about 68 files cleared in
-  # 13 minutes on an ordinary runner, but a slow runner day ran every test at
-  # twice its usual duration and the first shard was still working through
-  # its list when the 25-minute guard cut it off: three of four pushes to main
-  # between 2026-08-31 and 2026-09-01 failed that way, with green tests logged
-  # up to the last second. Four shards keep each slice around 50 files, and
-  # the guard sits at three times the ordinary run rather than under two. A
-  # wedged test still surfaces through vitest's own 60-second budget, so the
-  # job timeout only needs to catch a container that never boots. Each shard
-  # boots its own Postgres testcontainer.
+  # Four shards of about equal duration, each running its files in parallel
+  # against one database per worker. The shards used to be four slices of
+  # equal file count, run serially: 954 s to 1 449 s, because a slice holding
+  # the sharing matrix and the backup files took half again as long as one
+  # holding small files. `--shard` now goes through the duration sequencer
+  # (`tests/durations/sequencer.ts`, timings in
+  # `tests/durations/integration.json`), and every file in a shard runs on
+  # one of three workers, each against its own clone of the migrated template
+  # (`tests/integration/worker-database.ts`). Three workers leave a core of
+  # the four-core runner to the Postgres container. The job guard stays well
+  # above an ordinary run; a wedged test still surfaces through vitest's own
+  # 60-second budget, so the guard only needs to catch a container that never
+  # boots. Each shard boots its own Postgres testcontainer and uploads its
+  # JSON report, which `scripts/test-durations.mjs` turns into the timing file.
   shard:
-    runs-on: ubuntu-latest
-    timeout-minutes: 40
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
     strategy:
       fail-fast: false
       matrix:
@@ -34,7 +37,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
@@ -48,8 +51,13 @@ jobs:
       # vitest a stray positional argument and the shard flag never applies —
       # both "shards" then run the full suite. Proven by a paired local run
       # before this workflow shipped.
-      - run: pnpm exec vitest run --config vitest.integration.config.mts --shard=${{ matrix.shard }}/4
+      - run: >-
+          pnpm exec vitest run --config vitest.integration.config.mts
+          --shard=${{ matrix.shard }}/4
+          --reporter=default --reporter=json
+          --outputFile.json=integration-report-${{ matrix.shard }}.json
         env:
+          HEALTHLOG_INTEGRATION_WORKERS: "3"
           # The integration suite boots a Postgres testcontainer and points
           # Prisma at it via DATABASE_URL set inside `tests/integration/setup.ts`.
           # These env vars satisfy code paths that read them at module load.
@@ -63,11 +71,20 @@ jobs:
           ENCRYPTION_KEY: "0000000000000000000000000000000000000000000000000000000000000000"
           SESSION_SECRET: "integration-tests"
 
+      - name: Upload the timing report
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: integration-report-${{ matrix.shard }}
+          path: integration-report-${{ matrix.shard }}.json
+          if-no-files-found: ignore
+          retention-days: 14
+
   # Branch protection requires a check named exactly "integration". This job
   # 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/mutation.yml

@@ -0,0 +1,53 @@
+name: Mutation tests
+
+# Stryker on the core libraries (stryker.config.mjs): encryption at rest,
+# medication compliance, rollups, source ranking, unit conversion and backup
+# validation. Too slow for a pull request; it runs once a night and on
+# demand, and fails when a module's score drops below its floor in
+# stryker.floors.json. The HTML report is uploaded either way.
+on:
+  schedule:
+    - cron: "23 1 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  mutation:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 120
+    name: mutation (core libraries)
+    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
+
+      - name: Run Stryker
+        run: pnpm exec stryker run --concurrency 4
+
+      # Without pipefail the step takes the exit status of `tee`, which is
+      # always 0, so a module under its floor could never fail the run.
+      - name: Check the per-module floors
+        shell: bash
+        run: |
+          set -o pipefail
+          node scripts/mutation-floors.mjs | tee -a "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload the report
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: mutation-report
+          path: reports/mutation/
+          if-no-files-found: ignore
+          retention-days: 30

.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 }}
@@ -56,7 +56,7 @@ jobs:
 
     services:
       postgres:
-        image: postgres:16-alpine
+        image: postgres:18-alpine
         env:
           POSTGRES_USER: healthlog
           POSTGRES_PASSWORD: healthlog
@@ -71,7 +71,7 @@ jobs:
 
     steps:
       - name: Log in to GHCR
-        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}

.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@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
         with:
           sarif_file: scorecard-results.sarif
           category: scorecard

.github/workflows/security.yml

@@ -15,9 +15,11 @@ permissions:
   contents: read
 
 jobs:
-  quality:
-    name: Lint, Typecheck & Test
-    runs-on: ubuntu-latest
+  # The static checks: everything in the old single quality job except the
+  # unit suite, which runs sharded below.
+  static:
+    name: Lint, Typecheck & OpenAPI
+    runs-on: ubuntu-24.04
     if: github.event_name != 'schedule'
 
     steps:
@@ -25,7 +27,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"
@@ -34,26 +36,6 @@ jobs:
 
       - run: pnpm db:generate
 
-      # The hero-geometry check in the unit suite renders the real panel in a
-      # real browser and measures the boxes. Without a browser here it caught
-      # its own launch failure and passed anyway, so from its first day until
-      # v1.38 it measured nothing on any run of this job. The browser is part
-      # of the gate now; the test refuses to skip when CI is set.
-      #
-      # Headless shell only: `chromium.launch()` resolves to
-      # chromium_headless_shell, which is what the failing runs named, and the
-      # full headed build is several times the download for nothing this job
-      # uses. The e2e job keeps `--with-deps chromium` — it drives a real app.
-      - name: Cache Playwright headless shell
-        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-        with:
-          path: ~/.cache/ms-playwright
-          key: playwright-shell-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
-          restore-keys: |
-            playwright-shell-${{ runner.os }}-
-
-      - run: pnpm exec playwright install --only-shell chromium
-
       # Blocking since v1.15.20 — the settings-split refactor that kept
       # this warn-only is long done and the tree lints clean.
       - name: ESLint
@@ -68,9 +50,6 @@ jobs:
       - name: TypeScript strict check
         run: pnpm typecheck
 
-      - name: Unit tests
-        run: pnpm test
-
       # OpenAPI spec drift gate — hard-fail (flipped from warn-only in v1.4.25).
       #
       # The Zod registry is the source of truth for the public API contract.
@@ -87,6 +66,91 @@ jobs:
           fi
           echo "::notice::OpenAPI spec in sync with Zod source schemas."
 
+  # The unit suite in three slices of about equal duration. `--shard` goes
+  # through the duration sequencer in `vitest.config.mts`, which deals files
+  # out by their measured time (`tests/durations/unit.json`) instead of by
+  # count. Each slice uploads its JSON report, which is what
+  # `scripts/test-durations.mjs` regenerates the timing file from.
+  unit:
+    runs-on: ubuntu-24.04
+    if: github.event_name != 'schedule'
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3]
+    name: unit shard ${{ matrix.shard }}/3
+
+    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
+
+      # The hero-geometry check in the unit suite renders the real panel in a
+      # real browser and measures the boxes. Without a browser here it caught
+      # its own launch failure and passed anyway, so from its first day until
+      # v1.38 it measured nothing on any run of this job. The browser is part
+      # of the gate now; the test refuses to skip when CI is set. Every slice
+      # installs it, because the sequencer decides which slice the file lands in.
+      #
+      # Headless shell only: `chromium.launch()` resolves to
+      # chromium_headless_shell, which is what the failing runs named, and the
+      # full headed build is several times the download for nothing this job
+      # uses. The e2e job keeps `--with-deps chromium` — it drives a real app.
+      - name: Cache Playwright headless shell
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-shell-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            playwright-shell-${{ runner.os }}-
+
+      - run: pnpm exec playwright install --only-shell chromium
+
+      # vitest directly, not `pnpm test --`: pnpm hands the separator through
+      # literally and the shard flag would never reach vitest.
+      - name: Unit tests
+        run: >-
+          pnpm exec vitest run --shard=${{ matrix.shard }}/3
+          --reporter=default --reporter=json
+          --outputFile.json=unit-report-${{ matrix.shard }}.json
+
+      - name: Upload the timing report
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: unit-report-${{ matrix.shard }}
+          path: unit-report-${{ matrix.shard }}.json
+          if-no-files-found: ignore
+          retention-days: 14
+
+  # Branch protection requires a check named exactly "Lint, Typecheck & Test".
+  # That used to be one job running everything in turn; it is now this one,
+  # which answers for the static checks and every unit slice, so a half-green
+  # set cannot satisfy the gate.
+  quality:
+    name: Lint, Typecheck & Test
+    runs-on: ubuntu-24.04
+    needs: [static, unit]
+    if: always() && github.event_name != 'schedule'
+    timeout-minutes: 5
+    steps:
+      - name: The static checks and every unit slice finished green
+        run: |
+          if [ "${{ needs.static.result }}" != "success" ] || [ "${{ needs.unit.result }}" != "success" ]; then
+            echo "static: ${{ needs.static.result }}, unit: ${{ needs.unit.result }}"
+            exit 1
+          fi
+
   # Not on pull requests. `pnpm audit` answers a question about the published
   # advisory database, not about the diff: the same lockfile passes on Monday
   # and fails on Tuesday because someone else published, and the branch that
@@ -100,7 +164,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 +176,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 +194,7 @@ jobs:
 
   secret-scan:
     name: Secret Scanning
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     if: github.event_name != 'schedule'
 
     steps:
@@ -145,7 +209,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:
@@ -181,12 +245,23 @@ jobs:
           rm trivy-install.sh
           trivy --version
 
-      # Blocking since v1.15.20 — a HIGH/CRITICAL finding in the built
-      # image fails the job. For a finding without an upstream fix
-      # (e.g. a base-image CVE Alpine has not patched yet), add the CVE
-      # id to a `.trivyignore` file at the repository root — Trivy reads
-      # it automatically — one CVE per line, each with a comment naming
-      # the tracking issue and the re-check condition. Never suppress a
-      # finding that has a fixed version available; bump instead.
+      # Every HIGH/CRITICAL finding in the built image, fixed or not, as a
+      # table in the job log. Reporting only: a Debian base carries
+      # advisories the distribution has not fixed yet (or marked as not
+      # worth a fix), and nothing this repository changes can remove those.
+      # The list is here so they stay visible and move to the gate below
+      # the day a fix is published.
+      - name: Trivy container scan (all findings)
+        run: trivy image --format table --severity CRITICAL,HIGH --exit-code 0 healthlog:scan
+
+      # Blocking since v1.15.20 — a HIGH/CRITICAL finding with a published
+      # fix fails the job. `--ignore-unfixed` leaves out only the findings
+      # listed above that have no fixed version yet; a fix that reaches the
+      # Debian archive, the Node image or a dependency turns this red until
+      # it is taken (rebuild, bump the base digest, or bump the package).
+      # `.trivyignore` at the repository root (Trivy reads it automatically)
+      # is for a finding with a fix that cannot reach this image, one CVE
+      # per line with a comment naming what it covers and when to remove
+      # it. Never suppress a finding whose fix applies here; take it.
       - name: Trivy container scan
-        run: trivy image --format table --severity CRITICAL,HIGH --exit-code 1 healthlog:scan
+        run: trivy image --format table --severity CRITICAL,HIGH --ignore-unfixed --exit-code 1 healthlog:scan

.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/test-nightly.yml

@@ -0,0 +1,182 @@
+name: Tests (nightly, shuffled)
+
+# Looks for what a pull request run cannot see by design.
+#
+# - Order dependence. Both suites run with files and tests in a random order
+#   (`--sequence.shuffle`), seeded from the clock and printed at the top of
+#   the log and in the job summary. A failure that does not reproduce on a
+#   pull request reproduces here with `--sequence.seed=<seed>`.
+# - New property-test inputs. Pull requests run every fast-check property
+#   with a fixed seed; this run picks a fresh one (`FC_SEED`) and five times
+#   the cases, and fast-check prints the seed and the shrunk counterexample
+#   on a failure (see tests/property/fast-check.ts).
+# - Stale shard timings. The integration reports of this run are merged into
+#   a regenerated `tests/durations/integration.json`, uploaded as an
+#   artifact for a maintainer to commit when the shards drift apart.
+#
+# Not a gate: nothing here blocks a merge. A red run is an issue to open.
+on:
+  schedule:
+    - cron: "41 2 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  unit:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    name: unit (shuffled)
+    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
+
+      - name: Cache Playwright headless shell
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-shell-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            playwright-shell-${{ runner.os }}-
+
+      - run: pnpm exec playwright install --only-shell chromium
+
+      - name: Pick the seeds
+        run: |
+          echo "TEST_SEED=$(date +%s)" >> "$GITHUB_ENV"
+          echo "FC_SEED=$(( $(date +%s%N) % 2147483647 ))" >> "$GITHUB_ENV"
+
+      - name: Unit tests, shuffled
+        shell: bash
+        env:
+          # Five times each property's own case count (tests/property/fast-check.ts).
+          FC_RUNS_FACTOR: "5"
+        run: |
+          set -o pipefail
+          echo "Order seed ${TEST_SEED}, property seed ${FC_SEED}" | tee -a "$GITHUB_STEP_SUMMARY"
+          pnpm exec vitest run --sequence.shuffle --sequence.seed="${TEST_SEED}" \
+            --reporter=default --reporter=json --outputFile.json=unit-report.json
+
+      - name: Upload the timing report
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: nightly-unit-report
+          path: unit-report.json
+          if-no-files-found: ignore
+          retention-days: 14
+
+  integration:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4]
+    name: integration shard ${{ matrix.shard }}/4 (shuffled, Postgres 16)
+    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
+
+      # One seed per run, shared by the shards through the run id, so every
+      # shard shuffles the same way and a failure names one seed to replay.
+      - name: Pick the seeds
+        run: |
+          echo "TEST_SEED=${{ github.run_id }}" >> "$GITHUB_ENV"
+          echo "FC_SEED=$(( ${{ github.run_id }} % 2147483647 ))" >> "$GITHUB_ENV"
+
+      - name: Integration tests, shuffled
+        shell: bash
+        env:
+          HEALTHLOG_INTEGRATION_WORKERS: "3"
+          # Pull requests run the suite on Postgres 18, the compose default.
+          # Installs that bring their own database may still be on 16, so the
+          # nightly run keeps that major covered without doubling every PR.
+          INTEGRATION_PG_IMAGE: "postgres:16-alpine"
+          # Four times each property's own case count; a property's timeout
+          # grows by the same factor (`propertyTimeout`).
+          FC_RUNS_FACTOR: "4"
+          # Quoted for the reason given in integration.yml.
+          API_TOKEN_HMAC_KEY: "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
+          ENCRYPTION_KEY: "0000000000000000000000000000000000000000000000000000000000000000"
+          SESSION_SECRET: "integration-tests"
+        run: |
+          set -o pipefail
+          echo "Order seed ${TEST_SEED}, property seed ${FC_SEED}" | tee -a "$GITHUB_STEP_SUMMARY"
+          pnpm exec vitest run --config vitest.integration.config.mts \
+            --shard=${{ matrix.shard }}/4 \
+            --sequence.shuffle --sequence.seed="${TEST_SEED}" \
+            --reporter=default --reporter=json \
+            --outputFile.json=integration-report-${{ matrix.shard }}.json
+
+      - name: Upload the timing report
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: nightly-integration-report-${{ matrix.shard }}
+          path: integration-report-${{ matrix.shard }}.json
+          if-no-files-found: ignore
+          retention-days: 14
+
+  # Merge the timings of this run into fresh timing files. Uploaded, not
+  # committed: the workflow has read-only access, and a maintainer decides
+  # whether the drift is worth a commit.
+  durations:
+    runs-on: ubuntu-24.04
+    needs: [unit, integration]
+    if: always()
+    timeout-minutes: 10
+    name: regenerate shard timings
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 22
+
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          pattern: nightly-*-report*
+          path: reports
+
+      - name: Regenerate
+        shell: bash
+        run: |
+          set -o pipefail
+          shopt -s nullglob
+          integration=(reports/nightly-integration-report-*/*.json)
+          unit=(reports/nightly-unit-report/*.json)
+          if [ ${#integration[@]} -gt 0 ]; then
+            node scripts/test-durations.mjs integration "${integration[@]}"
+          fi
+          if [ ${#unit[@]} -gt 0 ]; then
+            node scripts/test-durations.mjs unit "${unit[@]}"
+          fi
+          git diff --stat -- tests/durations | tee -a "$GITHUB_STEP_SUMMARY"
+
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: test-durations
+          path: tests/durations/*.json
+          retention-days: 14

.github/workflows/trivy.yml

@@ -6,7 +6,7 @@ name: Trivy Scheduled Scan
 #   - `security.yml` → `dependency-audit` runs `pnpm audit --prod` on every
 #     push to `main` and once a day, blocking on HIGH/CRITICAL.
 #   - `security.yml` → `docker-security` builds the image on a push to `main`
-#     and runs `trivy image` against it, blocking on HIGH/CRITICAL.
+#     and runs `trivy image` against it, blocking on HIGH/CRITICAL with a fix.
 #
 # Both are change-triggered, and both answer "is this change safe". Neither
 # answers "is what we shipped last week still safe", because an advisory
@@ -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@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
         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
@@ -113,7 +113,7 @@ jobs:
       # this covers `linux/amd64`. The arm64 manifest shares every
       # application layer and differs only in native binaries.
       - name: Log in to GitHub Container Registry
-        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -142,10 +142,17 @@ jobs:
           output: trivy-published-image.sarif
           severity: "CRITICAL,HIGH,MEDIUM"
           limit-severities-for-sarif: true
+          # Only findings with a published fix reach code scanning. Debian
+          # leaves many base-package advisories unfixed in stable (no-dsa,
+          # postponed), and nothing in this repository can act on those: the
+          # build's `apt-get upgrade` takes the fix the day Debian ships one,
+          # and that is when the alert should appear. Listing them all made
+          # the page a hundred-odd rows deep without one to act on.
+          ignore-unfixed: true
           exit-code: "0"
 
       - name: Upload results
-        uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
+        uses: github/codeql-action/upload-sarif@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
         with:
           sarif_file: trivy-published-image.sarif
           category: trivy-published-image
@@ -162,3 +169,6 @@ jobs:
           format: table
           severity: "CRITICAL"
           exit-code: "1"
+          # Same rule as the blocking gate in security.yml and the SARIF
+          # report above: only a finding with a published fix counts.
+          ignore-unfixed: true

.gitignore

@@ -98,3 +98,6 @@ next-env.d.ts
 # same reason in a different tool.
 /.wt-*/
 /.worktrees/
+# Mutation testing (stryker.config.mjs): reports and the sandbox copy.
+/reports/mutation
+/.stryker-tmp

.gitleaks.toml

@@ -11,6 +11,9 @@ paths = [
   # All test files contain hardcoded fake tokens / idempotency-keys.
   '''(^|/)__tests__/''',
   '''\.test\.ts$''',
+  # Golden copies of the backup file written by the parity test: synthetic
+  # fixture values, and every `…Encrypted` value already opened to its text.
+  '''^tests/integration/__golden__/''',
   # OpenAPI spec contains example tokens (`hlk_example…`) used to document the schema.
   '''^docs/api/openapi\.yaml$''',
 ]

.prettierignore

@@ -16,3 +16,26 @@ docs/api/openapi.yaml
 
 # Build-generated service worker (the PWA build emits it).
 public/sw.js
+
+# Ratchet baselines, written by the guards themselves (RATCHET_WRITE=1). The
+# writer's JSON layout is the canonical one, so a write-back never fails the
+# format check.
+src/__tests__/baselines
+
+# Benchmark results, written by scripts/bench/run.ts and committed as they
+# come out, so a re-run diffs cleanly against the last one.
+scripts/bench/results
+
+# Golden copies of the backup file and the restored account, written by the
+# parity test itself (BACKUP_PARITY_WRITE=1), so a rewrite diffs cleanly.
+tests/integration/__golden__
+
+# A release's backup file exactly as its exporter wrote it; the golden-backup
+# test checks the bytes against the manifest's SHA-256, so it is never
+# reformatted. The manifests are written by the same test.
+tests/fixtures/golden-backups/*.json
+
+# inlang writes its working files (cache, metadata, README) next to the
+# project settings when its CLI or SDK runs; only settings.json is tracked.
+project.inlang/*
+!project.inlang/settings.json

.trivyignore

@@ -3,25 +3,6 @@
 # can apply; never suppress one with a fixed version available — bump instead.
 # Each entry names what it covers and the condition to re-check / remove it.
 
-# CVE-2026-33671 (picomatch ReDoS, HIGH) — flagged only in the npm CLI's
-# OWN bundled copy that ships inside the Node base image
-# (usr/local/lib/node_modules/npm/node_modules/picomatch, v4.0.3), used at
-# image-build time by npm, not by our runtime. Our application dependency
-# tree pins picomatch >= 4.0.4 via a pnpm override, so the running app is
-# not affected and the path is not reachable at runtime. Re-check when the
-# Node base image ships an npm build whose bundled picomatch is >= 4.0.4,
-# then drop this entry.
-CVE-2026-33671
-
-# CVE-2026-48815 (sigstore certificate-OID verification, HIGH) — flagged only
-# in the npm CLI's OWN bundled copy inside the Node base image
-# (usr/local/lib/node_modules/npm/node_modules/sigstore, v3.1.0). npm uses
-# sigstore for publish provenance at image-build time only; it is not in our
-# application dependency tree at all (`pnpm why sigstore` is empty) and is
-# never reachable at runtime. Re-check when the Node base image ships an npm
-# build whose bundled sigstore is >= 4.1.1, then drop this entry.
-CVE-2026-48815
-
 # CVE-2026-85393 (node-forge RSA PKCS#1 v1.5 signature forgery, HIGH; GitHub
 # advisory GHSA-86w9-cpqp-85rv) — node-forge <= 1.4.0 arrives only through
 # @parse/node-apn, which uses it in its certificate-based credential path
@@ -31,3 +12,11 @@ CVE-2026-48815
 # entry, the matching `auditConfig.ignoreGhsas` entry in pnpm-workspace.yaml,
 # and raise the floor once node-forge 1.4.1 is out.
 CVE-2026-85393
+
+# braces <= 3.0.3 stack overflow on deeply nested patterns (CVE-2026-93687).
+# braces arrives only through micromatch -> fast-glob in development tools
+# (@next/eslint-plugin-next, @ts-morph/common, the shadcn CLI); `pnpm why
+# braces --prod` is empty and the production image does not contain it, and
+# those tools only expand patterns written in this repository. No fixed
+# release is published (latest is 3.0.3). Remove this entry once one is.
+CVE-2026-93687

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`), Dutch (`nl`), and Brazilian Portuguese (`pt-BR`) 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
 
@@ -134,16 +134,45 @@ To suggest a fix or improvement:
 3. Edit `messages/<locale>.json`. Keep the JSON valid; the i18n integrity test will flag missing or extra keys against `en.json` before CI accepts the PR.
 4. Open a PR titled `i18n(<locale>): <area>`. Describe what was unclear, awkward, or wrong in the previous wording.
 
+### Translating in the browser
+
+Every locale can be edited in [Fink](https://fink.inlang.com/?repo=MBombeck/HealthLog&project=project.inlang), inlang's browser editor, without cloning the repository. Fink reads `project.inlang/settings.json`, which points it at `messages/<locale>.json`, shows each message next to its translations, and flags strings that are missing or use other placeholders than English.
+
+1. Open the link and sign in with GitHub.
+2. Without write access to this repository, choose **Fork**. Fink asks you to install the Inlang GitHub App on your own account so it can push to your fork.
+3. Edit, then choose **Push**. Fink commits to the fork; **Open pull request** takes you to GitHub's compare page, where you submit the change against `main`.
+
+Fink writes the same nested JSON this repository uses and changes only the lines you edited. A string you add for a key the locale did not have yet goes to the end of its section instead of the position it has in `en.json`, which is harmless.
+
+What a reviewer checks on a translation pull request:
+
+- Only `messages/*.json` changed, and only the strings the description names.
+- Every `{placeholder}` of the English string is still there and spelled the same. The i18n integrity test fails the build otherwise.
+- Medical terms are the ones the language's clinical guidelines use, and the register matches the rest of the locale (`du` in German, `você` in Brazilian Portuguese).
+- Words the app or the Telegram bot matches literally stay as they are: slash commands, `taken <name>`, and the unit symbols.
+- Machine translation is fine as a first draft, but someone who reads the language has gone through every string before the pull request is opened, and the description says so.
+- No questionnaire text. The bundles hold the app's own copy around the questionnaires (titles, notes, buttons), never an item, an answer option or a stem; see the next section.
+
+To run the checks Fink shows on a local checkout: `npx @inlang/cli@3.4.4 check --project ./project.inlang`. It reads the files and changes nothing.
+
+### Questionnaire wording
+
+The PHQ-9, GAD-7, WHO-5 and SCI are not translated through the bundles, and Fink never shows them. Their text lives in code, one file per instrument and language under `src/lib/mental-health/wording/<instrument>/<locale>.ts`, because changing a word in a validated questionnaire changes what it measures. Each file declares what it is:
+
+- `validated: true` with a `source`: a published validated translation, reproduced word for word (stem, items, answer options and, for the PHQ-9, the follow-up question, in the form of address the source uses). The source names who made it, the document it was read from with its link, and the terms that allow reproducing it in software. The file's header comment names anything that differs from the printed form, such as a corrected misprint.
+- `validated: false`: no validated version exists that may be reproduced, so the file carries a translation written for HealthLog, faithful to the English and on the same scale. The app shows a note beside it that the result is orientation, offers the English original in one tap, and records on the result that it was answered in an unvalidated translation. The header comment names any validated version that was found and why it is not used (paywalled, terms that allow private study only).
+
+To propose a validated version for a language that has none, or a better source for one that does, open an issue or a pull request with the publication, a link to the PDF it can be read from, and its terms of use. A pull request replaces the language's file: the text copied exactly from the PDF, `validated: true`, and the `source` filled in. The tests in `src/lib/mental-health/__tests__/` check that every instrument has text in every language, that every validated entry names its source, and that each answer is bound to the score the instrument gives it; the spot checks in `instrument-wording.test.ts` are the place to pin a line that is easy to transcribe wrongly. A correction to HealthLog's own translation of an unvalidated entry is welcome too; it stays `validated: false`.
+
 ### 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. `sv`, `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`.
+2. Copy `messages/en.json` to `messages/<locale>.json`. Questionnaire text is not in it; the new language needs a wording file per instrument instead (see Questionnaire wording above), which step 4 makes impossible to forget.
 3. Translate. AI assistance is welcome as a starting point but the PR description should note whether it's an AI-initial pass or a fully human-reviewed one — that information drives the banner state.
-4. Add the locale to the supported list in `src/lib/i18n/locales.ts` (or wherever the registry lives — grep `SUPPORTED_LOCALES`).
-5. The Coach system prompts at `src/lib/ai/prompts/coach-prompt.ts` and `src/lib/ai/prompts/insight-generator.ts` and the doctor-report PDF strings need translation too. Include those in the same PR.
-6. Run `pnpm test -- i18n-integrity` locally before submitting.
+4. Add the locale to `locales` in `src/lib/i18n/config.ts` and to `locales` in `project.inlang/settings.json`, then run `pnpm typecheck`. Every per-locale table that still lacks the new locale fails to compile, and that list is the work: date and number formatting, the reply-language footers of the Coach and insights prompts, the outbound safety banks, the prose-grounding patterns, the no-key fallback copy and the questionnaire wording registry. Include those in the same PR.
+5. Run `pnpm test` before submitting. The i18n guards hold the new bundle to the English keys and placeholders.
 
 ### Style guide for translators
 
@@ -156,7 +185,7 @@ If you want to introduce a locale that isn't shipped (e.g. `nl`, `pt-BR`, `cs`):
 
 ### Long-term
 
-When the community grows beyond ad-hoc PRs, we'll spin up a self-hosted [Weblate](https://weblate.org/) instance. That replaces the JSON-PR workflow with a web UI but keeps every translation under our own roof — no third-party telemetry. Tracking issue: `v1.6 — Weblate self-hosted on edge-01`.
+Fink covers browser editing today. It edits the files in this repository directly and keeps no copy of the translations anywhere else. If the community outgrows it, a self-hosted [Weblate](https://weblate.org/) instance remains the fallback. Tracking issue: `v1.6 — Weblate self-hosted on edge-01`.
 
 ## Code of Conduct
 

Dockerfile

@@ -1,14 +1,35 @@
+# ── Base images ────────────────────────────────────────────
+# glibc, not musl, in every stage. The native modules the runtime loads (the
+# @napi-rs/canvas Skia renderer, @node-rs/argon2, the Prisma schema engine)
+# then run their glibc builds. The arm64 musl Skia build needs ARMv8.2 (LSE
+# atomics, RCpc loads) and dies with SIGILL on an ARMv8.0 core such as the
+# Raspberry Pi 4's Cortex-A72; the glibc arm64 build does not use those
+# instructions (#1311).
+#
+# Every Node stage, the runner included, is the official node:22-trixie-slim
+# image, pinned by its multi-arch index digest. Node security releases reach
+# that image within days of their publication, which no distribution package
+# of an older Node stream matched. The runner removes the package managers
+# the image ships; the one npm install the runtime needs happens in the
+# `prisma-cli` stage and is copied over. pg_dump and pg_restore come from the
+# official PostgreSQL image in the `pgclient` stage. The runner still checks
+# the Node module ABI and the glibc against the builder at build time, so a
+# future change to one of the stages cannot pair them wrongly.
+
 # ── Stage 1: Dependencies ──────────────────────────────────
-FROM node:22-alpine@sha256:16e22a550f3863206a3f701448c45f7912c6896a62de43add43bb9c86130c3e2 AS deps
+FROM node:22-trixie-slim@sha256:2117f713a417f3aff682ac8f5bc2ebbdf1beed51f36e67ab1e0fd3866b6d2d8f AS deps
 RUN corepack enable && corepack prepare pnpm@11.15.1 --activate
 WORKDIR /app
 
 COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+# The dependency patches pnpm-workspace.yaml names; the frozen install
+# refuses to run without them.
+COPY patches patches
 COPY scripts/prepare.mjs scripts/prepare.mjs
 RUN pnpm install --frozen-lockfile --prod=false
 
 # ── Stage 2: Build ─────────────────────────────────────────
-FROM node:22-alpine@sha256:16e22a550f3863206a3f701448c45f7912c6896a62de43add43bb9c86130c3e2 AS builder
+FROM node:22-trixie-slim@sha256:2117f713a417f3aff682ac8f5bc2ebbdf1beed51f36e67ab1e0fd3866b6d2d8f AS builder
 RUN corepack enable && corepack prepare pnpm@11.15.1 --activate
 WORKDIR /app
 
@@ -54,25 +75,171 @@ RUN NODE_OPTIONS=--max-old-space-size=8192 pnpm build
 # name; see the note there for why guessing was wrong.
 RUN node -p "require('/app/node_modules/pdfjs-dist/package.json').version" \
       > /app/.pdfjs-version
+# The Node module ABI and the glibc the native packages were installed for;
+# the runner refuses to build on an older glibc or another module ABI.
+RUN node -p "process.versions.modules + ' ' + process.report.getReport().header.glibcVersionRuntime + ' ' + process.version" \
+      > /app/.native-abi
+# The same for @napi-rs/canvas, whose native binary must match its JS loader.
+RUN node -p "require('/app/node_modules/@napi-rs/canvas/package.json').version" \
+      > /app/.canvas-version
+# Every shipped locale's message catalog is present and parses, checked
+# against the locale list in the source; the list is written out so the runner
+# stage can check the catalogs the image actually carries.
+RUN node scripts/verify-message-catalogs.mjs --dir messages \
+      --config src/lib/i18n/config.ts --write /app/.message-locales
 
-# ── Stage 3: Production runner ─────────────────────────────
-FROM node:22-alpine@sha256:16e22a550f3863206a3f701448c45f7912c6896a62de43add43bb9c86130c3e2 AS runner
+# ── Stage 3: Migration CLI ─────────────────────────────────
+# Install the migration CLI, its config dependency, and a pinned launcher for
+# the maintenance scripts already shipped in the standalone tree. This is the
+# only npm install the runtime needs; it runs here, on the runner's own base,
+# and the runner copies `/opt/prisma-cli` over, so npm never reaches the
+# runtime image.
+#
+# The `allowScripts` field is for npm 12 and later, which runs no dependency
+# install scripts unless package.json lists the package there. Three packages
+# here have one: `@prisma/engines` downloads the schema engine `migrate
+# deploy` runs, `prisma` checks its environment, and `esbuild` (under tsx)
+# checks its binary. The npm in this image still runs them without the field;
+# keeping it means a later npm major cannot drop the schema engine quietly.
+# Either way the runner asks for the engine file after the copy.
+#
+# This install belongs to npm, not pnpm, so the `overrides` block in
+# `pnpm-workspace.yaml` does not reach it: a package pinned there for the app
+# tree still arrives here at whatever version Prisma asks for. That is not
+# hypothetical. `prisma@7.8.0` resolves `@prisma/config@7.8.0`, which resolves
+# `deepmerge-ts@7.1.5`, and the image scan reported CVE-2026-40345 (HIGH,
+# stack exhaustion on recursive merges) against `/opt/prisma-cli` on a commit
+# whose dependency audit over the app tree was green. Two installs, two
+# override mechanisms, one of them set. `overrides` is npm's own mechanism and
+# `npm pkg set` writes it into the package.json that `npm init -y` just
+# created, before anything resolves.
+#
+# Measured by rebuilding this exact install both ways: without the field
+# `deepmerge-ts@7.1.5` lands, with it `8.0.1` lands and `prisma --version`
+# still reports 7.8.0. Keep the range in step with the entry in
+# `pnpm-workspace.yaml` — they are one decision applied to two package
+# managers, and a fix that lands in only one of them is the defect above.
+#
+# The same class recurred on 2026-09-02: the image scan reported
+# `@hono/node-server@1.19.11` (GHSA-frvp-7c67-39w9, CVE-2026-39406) and
+# `valibot@1.2.0` (CVE-2026-59952) under this path, both reached through
+# `prisma -> @prisma/dev`, while the app tree carried 1.19.17 and a pin the
+# npm install never reads. Rebuilding this install both ways confirms it:
+# without the two fields below npm resolves 1.19.11 and 1.2.0, with them it
+# resolves 1.19.17 and 1.4.2, and `prisma --version` still reports 7.8.0.
+FROM node:22-trixie-slim@sha256:2117f713a417f3aff682ac8f5bc2ebbdf1beed51f36e67ab1e0fd3866b6d2d8f AS prisma-cli
+RUN mkdir -p /opt/prisma-cli && \
+    cd /opt/prisma-cli && \
+    npm init -y && \
+    npm pkg set 'overrides.deepmerge-ts=^8.0.0' && \
+    npm pkg set 'overrides.mysql2=^3.22.0' && \
+    npm pkg set 'overrides.@hono/node-server=^2.1.3' && \
+    npm pkg set 'overrides.valibot=^1.4.2' && \
+    npm pkg set 'allowScripts.@prisma/engines=true' 'allowScripts.prisma=true' 'allowScripts.esbuild=true' --json && \
+    npm install --omit=dev prisma@7.10.1 @prisma/engines@7.10.1 tsx@4.23.1 dotenv@18.0.9 --no-fund --no-audit
+
+# ── Stage 4: PostgreSQL client ─────────────────────────────
+# pg_dump and pg_restore of the bundled database's major, taken from the
+# official PostgreSQL image (Debian trixie, the runner's own release; its
+# binaries are the PGDG builds) together with the libpq they link. Debian
+# trixie itself ships major 17. The PGDG apt package was the other route: it
+# brings Perl and Debian's version-picking wrapper scripts for two binaries
+# the app calls by name, and its repository drops a minor once the next one
+# is out, so a pinned package version stops installing. A digest-pinned
+# image stays buildable, and Dependabot proposes its next minor the way it
+# does for the bundled database. The libpq file is found through the loader
+# rather than by an architecture path, so the step is the same on amd64 and
+# arm64.
+FROM postgres:18.6-trixie@sha256:3a4264520e121176619f54ff867d12774bc81e95e7b84db58d63bccdb6144b81 AS pgclient
+RUN set -eu; \
+    mkdir -p /out/bin /out/lib; \
+    cp /usr/lib/postgresql/18/bin/pg_dump /usr/lib/postgresql/18/bin/pg_restore /out/bin/; \
+    LIBPQ="$(ldd /usr/lib/postgresql/18/bin/pg_dump | awk '$1 == "libpq.so.5" { print $3 }')"; \
+    [ -n "$LIBPQ" ] || { echo "ERROR: pg_dump links no libpq.so.5"; exit 1; }; \
+    cp -L "$LIBPQ" /out/lib/libpq.so.5
+
+# ── Stage 5: Production runner ─────────────────────────────
+FROM node:22-trixie-slim@sha256:2117f713a417f3aff682ac8f5bc2ebbdf1beed51f36e67ab1e0fd3866b6d2d8f AS runner
+# The package managers the base ships (npm, npx, corepack, yarn) go first.
+# Nothing at runtime installs a package, and the bundled npm carried the only
+# HIGH findings with a fix the image scan reported. Removed in a later layer,
+# their files stay in the base layer's bytes but leave the image's file
+# system, which is what runs and what the scan reads.
+#
 # `tzdata` is required so Europe/Berlin schedules (pg-boss cron, locale-aware
 # timestamp formatting) resolve to the actual offset instead of silently
-# falling back to UTC on Alpine images that ship without it.
+# falling back to UTC; the slim base ships without it. tzdata stays unpinned
+# on purpose: a zone rule change is a fix to take.
 #
-# `apk upgrade` pulls in OS-package security fixes the pinned base digest
+# `apt-get upgrade` pulls in OS-package security fixes the pinned base digest
 # has not absorbed yet (the digest pin stays for build reproducibility;
-# security patches from the Alpine repo override it deliberately —
-# CVE-2026-14456 in openssl was the first instance the container scan
-# caught between base-image rebuilds).
-RUN apk add --no-cache tzdata && apk upgrade --no-cache
+# security patches from the Debian archive override it deliberately —
+# CVE-2026-14456 in openssl was the first instance the container scan caught
+# between base-image rebuilds).
+#
+# `pg_dump` and `pg_restore` serve the nightly database dump, the
+# pre-migration dump in the entrypoint and the `db-restore` service
+# (docs/ops/disaster-recovery.md). Major 18 matches the bundled database; a
+# client dumps servers of its own major and older, so it also serves an
+# install still on its own Postgres 16. The two binaries and their libpq come
+# from the `pgclient` stage above; the Debian libraries libpq links
+# (Kerberos, LDAP, SASL) come from apt below, so the build-time upgrade and
+# the image scan see them. The copied binaries are outside dpkg: the scan
+# does not see them and `apt-get upgrade` does not patch them, so a
+# PostgreSQL client fix arrives by moving the `pgclient` pin.
+# `src/__tests__/runtime-package-pins.test.ts` holds that pin to the bundled
+# database's minor in docker-compose.yml.
+#
+# `ca-certificates` is the system trust store the OpenSSL-linked tools use
+# (the Prisma schema engine, libpq) for a TLS connection to the database.
+# `tar` and `gzip` for the GeoLite2 extraction and `sh` (dash) for the
+# entrypoint are part of the Debian base.
+RUN set -eux; \
+    rm -rf /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/corepack \
+      /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack \
+      /usr/local/bin/yarn /usr/local/bin/yarnpkg /opt/yarn-v*; \
+    sh -c '! command -v npm && ! command -v npx && ! command -v corepack && ! command -v yarn && ! command -v pnpm'; \
+    export DEBIAN_FRONTEND=noninteractive; \
+    apt-get update; \
+    apt-get upgrade -y --no-install-recommends; \
+    apt-get install -y --no-install-recommends \
+      ca-certificates tzdata libgssapi-krb5-2 libldap2 libsasl2-2; \
+    apt-get clean; \
+    rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/* /root/.npm /root/.cache
+COPY --from=pgclient /out/bin/ /usr/lib/postgresql/18/bin/
+COPY --from=pgclient /out/lib/libpq.so.5 /usr/lib/postgresql/18/lib/libpq.so.5
+RUN echo /usr/lib/postgresql/18/lib > /etc/ld.so.conf.d/postgresql-18.conf && \
+    ldconfig && \
+    ! ldd /usr/lib/postgresql/18/bin/pg_dump /usr/lib/postgresql/18/bin/pg_restore | grep -q "not found"
+ENV PATH=/usr/lib/postgresql/18/bin:$PATH
+# The builder and the runner start from the same image, so the two agree
+# today. The check stays: it fails the build the day one of them moves to
+# another base or another Node major without the other.
+COPY --from=builder /app/.native-abi /tmp/.native-abi
+RUN set -e; \
+    read -r BUILD_ABI BUILD_GLIBC BUILD_NODE < /tmp/.native-abi; \
+    rm -f /tmp/.native-abi; \
+    RUN_ABI="$(node -p process.versions.modules)"; \
+    RUN_GLIBC="$(node -p 'process.report.getReport().header.glibcVersionRuntime')"; \
+    [ "$RUN_ABI" = "$BUILD_ABI" ] || { echo "ERROR: runner Node module ABI $RUN_ABI, builder $BUILD_ABI"; exit 1; }; \
+    [ "$(printf '%s\n%s\n' "$BUILD_GLIBC" "$RUN_GLIBC" | sort -V | head -1)" = "$BUILD_GLIBC" ] || \
+      { echo "ERROR: runner glibc $RUN_GLIBC is older than the builder's $BUILD_GLIBC"; exit 1; }; \
+    echo "native ABI $RUN_ABI (builder $BUILD_NODE, runner $(node -v)); glibc $BUILD_GLIBC -> $RUN_GLIBC"
 WORKDIR /app
 
 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
@@ -88,11 +255,30 @@ ENV NEXT_PUBLIC_APP_VERSION=$NEXT_PUBLIC_APP_VERSION
 ARG NEXT_PUBLIC_APP_BUILD_SHA
 ENV NEXT_PUBLIC_APP_BUILD_SHA=$NEXT_PUBLIC_APP_BUILD_SHA
 
-RUN addgroup --system --gid 1001 nodejs && \
-    adduser --system --uid 1001 nextjs
+RUN groupadd --system --gid 1001 nodejs && \
+    useradd --system --uid 1001 --gid nodejs --create-home --home-dir /home/nextjs \
+      --shell /usr/sbin/nologin nextjs
+
+# Where the database dumps go (`DB_BACKUP_DIR`). Owned by the app user, so a
+# fresh named volume mounted here starts with that owner: Docker fills an
+# empty named volume from the image directory it covers, ownership included.
+# Without a mount the directory stays in the container's layer; the app reads
+# its mount table, sees that, and keeps no dump here (dump-core.mjs).
+RUN mkdir -p /var/lib/healthlog/backups && \
+    chown nextjs:nodejs /var/lib/healthlog/backups && \
+    chmod 700 /var/lib/healthlog/backups
 
 # Copy built assets
 COPY --from=builder /app/public ./public
+# The server reads its message catalogs from here on first use, one locale at
+# a time (src/lib/i18n/server-catalogs.ts); they are not bundled.
+COPY --from=builder /app/messages ./messages
+# A missing or broken catalog is only noticed when a page asks for that
+# locale, so check the copies in this stage against the builder's list.
+COPY --from=builder /app/.message-locales /app/scripts/verify-message-catalogs.mjs /tmp/catalog-check/
+RUN node /tmp/catalog-check/verify-message-catalogs.mjs --dir /app/messages \
+      --locales /tmp/catalog-check/.message-locales && \
+    rm -rf /tmp/catalog-check
 COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
 COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
 # Next's standalone output must carry the externalized worker dependencies.
@@ -119,35 +305,57 @@ RUN node -e "require.resolve('pg-boss'); require.resolve('pg')"
 # HOISTED to the top level there (verified: without it pdfjs logs "Cannot load
 # @napi-rs/canvas" → "Cannot polyfill DOMMatrix" → rasterize ReferenceError);
 # (2) @napi-rs/canvas's own loader then resolves its platform binary. Hoist BOTH
-# the canvas package and the musl binary package to /app/node_modules/@napi-rs
-# via symlink into the .pnpm store, and also drop the prebuilt .node into the
-# canvas dir so the loader's local-file fallback (`require('./skia.<triple>.node')`)
-# is belt-and-suspenders. Per-arch buildx installs only the matching musl triple.
+# the canvas package and the glibc (`-gnu`) binary package to
+# /app/node_modules/@napi-rs via symlink into the .pnpm store, and drop the prebuilt .node into the canvas
+# dir: the loader tries that local file (`require('./skia.<triple>.node')`)
+# before the platform package, so it decides which binary runs.
+#
+# Hoist the version the app pins, by name, exactly like pdfjs-dist below. The
+# store once held a second, older canvas that a second pdfjs-dist pulled in,
+# and this step used to take whichever `find | head -1` returned first. It
+# returned the old binary, which then sat next to the new loader: rendering
+# still worked, but `loadImage` called an `Image.decode` the old binary does
+# not have, and every preview thumbnail failed with "image.decode is not a
+# function". Name the version, and fail the build when the binary that lands
+# in the canvas dir is not that version's.
+COPY --from=builder /app/.canvas-version /tmp/.canvas-version
 RUN set -e; \
-    CANVAS_DIR="$(find /app/node_modules/.pnpm -maxdepth 4 -type d -path '*@napi-rs+canvas@*/node_modules/@napi-rs/canvas' 2>/dev/null | head -1)"; \
-    MUSL_DIR="$(find /app/node_modules/.pnpm -maxdepth 4 -type d -path '*@napi-rs+canvas-linux-*-musl@*/node_modules/@napi-rs/canvas-linux-*-musl' 2>/dev/null | head -1)"; \
-    NODE_BIN="$(find /app/node_modules/.pnpm -maxdepth 5 -name 'skia.linux-*-musl.node' 2>/dev/null | head -1)"; \
-    if [ -n "$CANVAS_DIR" ]; then \
-      mkdir -p /app/node_modules/@napi-rs; \
-      ln -sfn "$CANVAS_DIR" /app/node_modules/@napi-rs/canvas; \
-      [ -n "$MUSL_DIR" ] && ln -sfn "$MUSL_DIR" "/app/node_modules/@napi-rs/$(basename "$MUSL_DIR")"; \
-      [ -n "$NODE_BIN" ] && cp "$NODE_BIN" "$CANVAS_DIR/"; \
-      chown -R nextjs:nodejs /app/node_modules/@napi-rs; \
-      echo "canvas hoisted for pdfjs: $CANVAS_DIR (musl=$MUSL_DIR)"; \
-    else echo "WARN: @napi-rs/canvas not found; PDF rasterization will degrade to local text"; fi
+    CANVAS_VERSION="$(cat /tmp/.canvas-version)"; \
+    rm -f /tmp/.canvas-version; \
+    CANVAS_DIR="/app/node_modules/.pnpm/@napi-rs+canvas@${CANVAS_VERSION}/node_modules/@napi-rs/canvas"; \
+    GNU_DIR="$(find /app/node_modules/.pnpm -maxdepth 4 -type d -path "*@napi-rs+canvas-linux-*-gnu@${CANVAS_VERSION}/node_modules/@napi-rs/canvas-linux-*-gnu" 2>/dev/null | head -1)"; \
+    if [ ! -d "$CANVAS_DIR" ] || [ -z "$GNU_DIR" ]; then \
+      echo "ERROR: pinned @napi-rs/canvas@${CANVAS_VERSION} or its glibc binary did not reach the traced image."; \
+      echo "Present instead:"; \
+      find /app/node_modules/.pnpm -maxdepth 1 -name '@napi-rs+canvas*' 2>/dev/null; \
+      exit 1; \
+    fi; \
+    NODE_BIN="$(find "$GNU_DIR" -maxdepth 1 -name 'skia.linux-*-gnu.node' | head -1)"; \
+    [ -n "$NODE_BIN" ] || { echo "ERROR: no skia binary in $GNU_DIR"; exit 1; }; \
+    mkdir -p /app/node_modules/@napi-rs; \
+    ln -sfn "$CANVAS_DIR" /app/node_modules/@napi-rs/canvas; \
+    ln -sfn "$GNU_DIR" "/app/node_modules/@napi-rs/$(basename "$GNU_DIR")"; \
+    cp "$NODE_BIN" "$CANVAS_DIR/"; \
+    chown -R nextjs:nodejs /app/node_modules/@napi-rs; \
+    BIN_VERSION="$(node -p "require('$GNU_DIR/package.json').version")"; \
+    [ "$BIN_VERSION" = "$CANVAS_VERSION" ] || { echo "ERROR: canvas binary is $BIN_VERSION, loader is $CANVAS_VERSION"; exit 1; }; \
+    cmp -s "$NODE_BIN" "$CANVAS_DIR/$(basename "$NODE_BIN")" || { echo "ERROR: the canvas dir holds a different binary"; exit 1; }; \
+    echo "canvas hoisted for pdfjs: $CANVAS_DIR (binary $BIN_VERSION from $GNU_DIR)"
 
 # pdfjs-dist is `serverExternalPackages` (NOT bundled — the bundled copy's render
 # path breaks in the standalone image), so the server does a runtime bare
 # `import('pdfjs-dist/legacy/build/pdf.mjs')`. Node resolves that up to
 # /app/node_modules, so hoist the real pnpm-store copy to the top level too.
 #
-# Hoist the version the app pins, by name. More than one pdfjs-dist reaches the
-# store — `pdf-parse` carries its own, older copy for the text-extraction path —
-# and this step used to take whatever `find | head -1` returned first. That is
-# readdir order, so it could hoist the OLDER copy and the version named in
-# package.json would never run in the image: the renderer resolving one version
-# while every local check exercised another. Name the version and fail the build
-# when it is absent, instead of degrading to whichever copy comes back first.
+# Hoist the version the app pins, by name. More than one pdfjs-dist once reached
+# the store (a text-extraction dependency carried its own, older copy), and this
+# step used to take whatever `find | head -1` returned first. That is readdir
+# order, so it could hoist the OLDER copy and the version named in package.json
+# would never run in the image: the renderer resolving one version while every
+# local check exercised another. Name the version and fail the build when it is
+# absent, instead of degrading to whichever copy comes back first. Two copies in
+# one process also break each other (#1277); the lockfile now resolves one, and
+# `src/__tests__/single-pdfjs-guard.test.ts` keeps it that way.
 COPY --from=builder /app/.pdfjs-version /tmp/.pdfjs-version
 RUN set -e; \
     PDFJS_VERSION="$(cat /tmp/.pdfjs-version)"; \
@@ -179,57 +387,54 @@ 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. `db-dump.mjs` takes the dump before migrating, and
+# `db-restore.mjs` is the `db-restore` service; both share
+# `src/lib/database-backup/dump-core.mjs` with the app. The files are
+# root-owned, so the app user can run them but not edit them in place. The
+# directory around them stays the app user's.
 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/scripts/db-dump.mjs ./scripts/db-dump.mjs
+COPY --from=builder /app/scripts/db-restore.mjs ./scripts/db-restore.mjs
+COPY --from=builder /app/scripts/db-app-role.mjs ./scripts/db-app-role.mjs
+COPY --from=builder /app/src/lib/jobs/retired-measurement-indexes.mjs ./src/lib/jobs/retired-measurement-indexes.mjs
+COPY --from=builder /app/src/lib/database-backup/dump-core.mjs ./src/lib/database-backup/dump-core.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')"
+# The dump and restore scripts load, the client tools they run are the
+# major the bundled database runs, and the S3 client `db-restore --from-bucket`
+# loads resolves from the shared module's place in the tree.
+RUN node scripts/db-dump.mjs 2>&1 | grep -q "db-dump: usage:" && \
+    node --input-type=module -e "import { createRequire } from 'node:module'; createRequire('/app/src/lib/database-backup/dump-core.mjs').resolve('@aws-sdk/client-s3')" && \
+    node scripts/db-restore.mjs 2>&1 | grep -q "db-restore: usage:" && \
+    pg_dump --version | grep -q "(PostgreSQL) 18\." && \
+    pg_restore --version | grep -q "(PostgreSQL) 18\."
 
-# Install the migration CLI, its config dependency, and a pinned launcher for
-# the maintenance scripts already shipped in the standalone tree. The Prisma
-# config loads dotenv from /app, so expose the isolated copy there before
-# stripping npm/Corepack and their caches from the runtime surface.
-#
-# This install belongs to npm, not pnpm, so the `overrides` block in
-# `pnpm-workspace.yaml` does not reach it: a package pinned there for the app
-# tree still arrives here at whatever version Prisma asks for. That is not
-# hypothetical. `prisma@7.8.0` resolves `@prisma/config@7.8.0`, which resolves
-# `deepmerge-ts@7.1.5`, and the image scan reported CVE-2026-40345 (HIGH,
-# stack exhaustion on recursive merges) against `/opt/prisma-cli` on a commit
-# whose dependency audit over the app tree was green. Two installs, two
-# override mechanisms, one of them set. `overrides` is npm's own mechanism and
-# `npm pkg set` writes it into the package.json that `npm init -y` just
-# created, before anything resolves.
-#
-# Measured by rebuilding this exact install both ways: without the field
-# `deepmerge-ts@7.1.5` lands, with it `8.0.1` lands and `prisma --version`
-# still reports 7.8.0. Keep the range in step with the entry in
-# `pnpm-workspace.yaml` — they are one decision applied to two package
-# managers, and a fix that lands in only one of them is the defect above.
-#
-# The same class recurred on 2026-09-02: the image scan reported
-# `@hono/node-server@1.19.11` (GHSA-frvp-7c67-39w9, CVE-2026-39406) and
-# `valibot@1.2.0` (CVE-2026-59952) under this path, both reached through
-# `prisma -> @prisma/dev`, while the app tree carried 1.19.17 and a pin the
-# npm install never reads. Rebuilding this install both ways confirms it:
-# without the two fields below npm resolves 1.19.11 and 1.2.0, with them it
-# resolves 1.19.17 and 1.4.2, and `prisma --version` still reports 7.8.0.
-RUN mkdir -p /opt/prisma-cli && \
-    cd /opt/prisma-cli && \
-    npm init -y && \
-    npm pkg set 'overrides.deepmerge-ts=^8.0.0' && \
-    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 && \
-    ln -sfn /opt/prisma-cli/node_modules/.bin/tsx /usr/local/bin/healthlog-tsx && \
+# The migration CLI from the `prisma-cli` stage. The Prisma config loads
+# dotenv from /app, so expose the isolated copy there. /opt/prisma-cli is
+# root-owned: the app user can run it but not change it.
+COPY --from=prisma-cli /opt/prisma-cli /opt/prisma-cli
+RUN 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 && \
-    rm -rf /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/corepack /root/.cache/node/corepack /root/.npm && \
-    rm -f /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack /usr/local/bin/pnpm /usr/local/bin/pnpx
+    ln -sfn /opt/prisma-cli/node_modules/prisma /app/node_modules/prisma
+
+# The schema engine the entrypoint's `migrate deploy` runs is in place.
+# Look for the file before asking the CLI: a CLI that finds none downloads
+# one, which would hide the missing install script here and fail offline.
+RUN ls /opt/prisma-cli/node_modules/@prisma/engines/schema-engine-* >/dev/null && \
+    node /opt/prisma-cli/node_modules/prisma/build/index.js --version 2>&1 | \
+      grep -q "Schema Engine *: schema-engine-cli [0-9a-f]* (at "
 
 # Same proof for the intake-repair script under the launcher it is documented
 # with: its `pg` import resolves, so it reaches its own DATABASE_URL check.
@@ -252,17 +457,31 @@ RUN env -u DATABASE_URL healthlog-tsx scripts/repair-intake-anomalies.ts 2>&1 |
 # user so the runtime worker can WRITE it: a self-hoster who sets
 # MAXMIND_LICENSE_KEY on the published image has the databases fetched into
 # this directory at runtime (src/lib/geo/geolite2-fetch.ts) with no rebuild or
-# manual mount. `tar`/`gzip` for the extraction ship in the busybox base. A
+# manual mount. `tar`/`gzip` for the extraction come with the base. A
 # read-only bind mount at this path (the bring-your-own-database route) still
 # works — the runtime fetch just fails soft and the mounted files stand.
 RUN mkdir -p /opt/geolite2 && chown nextjs:nodejs /opt/geolite2
 COPY --chown=nextjs:nodejs assets/geolite2/ /opt/geolite2/
 
+# `wget` for health checks written outside the image. A compose file copied
+# from this repository up to v1.46.6 and the TrueNAS catalog app both call
+# `wget --spider` against /api/health, and their check replaces the
+# HEALTHCHECK below; the slim base has no wget, so without this every such
+# container stayed unhealthy. `scripts/wget-shim.mjs` understands the flags
+# those checks use, exits like wget, and writes nowhere but stdout. The
+# image's own HEALTHCHECK and the bundled compose file use the Node probe.
+# Root-owned: the app user can run it but not replace it.
+COPY --from=builder /app/scripts/wget-shim.mjs /usr/local/lib/healthlog/wget-shim.mjs
+RUN printf '#!/bin/sh\nexec node /usr/local/lib/healthlog/wget-shim.mjs "$@"\n' > /usr/local/bin/wget && \
+    chmod 755 /usr/local/bin/wget && \
+    wget 2>&1 | grep -q "health check shim" && \
+    ! wget --no-verbose --tries=1 --spider http://127.0.0.1:9/api/health
+
 # ISO-8601 build timestamp — /api/version returns it as `builtAt`.
 # Declared this late in the stage on purpose: the value differs on
 # every CI run, and every instruction after an ARG shares its cache
 # fate. Down here the only layers it invalidates are the cheap
-# entrypoint COPY/chmod below; the npm-install layers above stay
+# entrypoint COPY/chmod below; the layers above stay
 # cache-warm across rebuilds of the same release.
 ARG NEXT_PUBLIC_APP_BUILT_AT
 ENV NEXT_PUBLIC_APP_BUILT_AT=$NEXT_PUBLIC_APP_BUILT_AT
@@ -277,8 +496,16 @@ 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). The probe is Node's own
+# fetch: it needs nothing beyond the runtime, the same probe works on any
+# base, and no HTTP client has to be installed for one line. A non-2xx
+# answer, a refused connection and the 4 s abort all exit 1.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10m --retries=5 \
+  CMD ["node", "-e", "fetch('http://127.0.0.1:3000/api/health',{signal:AbortSignal.timeout(4000)}).then(r=>process.exit(r.ok?0:1),()=>process.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
@@ -54,13 +50,13 @@ Try the [live demo](https://demo.healthlog.dev) to see a working install — sig
 - **Clinical signals, opt-in and additive.** Validated self-checks for mental wellbeing and sleep (WHO-5, PHQ-9, GAD-7, Sleep Condition Indicator — official questionnaire wording, calm crisis-resource handling), grip strength, a 0–10 pain score, waist and body measurements, and a longevity lab panel — each added through one signal registry, so a new signal wires into charts, correlations, the coach, the FHIR map, and the API at once.
 - **Records, structured.** Allergies and family history as structured records that flow into the doctor report (reactions and notes are encrypted, the substance and condition names are not), plus lab values you key in or scan from a printed report — OCR extracts the stated values, units, and dates for you to review and confirm before anything is saved. HealthLog transcribes what a report says; it never interprets or diagnoses from it. A vaccination record keeps a lifetime immunization log, doses grouped under the disease they protect against, and prints in the doctor report.
 - **A document vault for the paper trail.** An opt-in module stores every letter, report, and scan encrypted at rest — PDFs and photos preview inline, Office and text files stay download-only, and nothing user-uploaded can ever execute in the app. One searchable timeline with type, condition, and year filters, drag-and-drop and paste-to-upload, bulk filing, undo-able delete with a 30-day grace, and per-file/per-account limits the operator tunes.
-- **Context that explains the numbers.** An opt-in environmental module folds weather, daylight, and temperature in as influence signals (winter darkness against mood, heat against blood pressure) using a home location you set, so a pattern has somewhere to point.
+- **Context that explains the numbers.** An environmental module folds weather, daylight, temperature, air quality, and pollen in as influence signals (winter darkness against mood, heat against blood pressure) using a home location you set, so a pattern has somewhere to point. It is on by default, and nothing leaves the host until someone sets that location.
 - **Your devices, one server.** Withings, WHOOP, Oura and Polar sync over OAuth2, Google Health connects Fitbit and Pixel Watch through your own Google Cloud client, Nightscout streams CGM glucose, an Apple Health `export.zip` folds your full history in, and the native iOS app streams HealthKit live. A per-metric source priority decides which reading is canonical when wearables overlap.
 - **Medication tracking that tells the truth.** Flexible schedules (weekly injections, weekday-only, intervals, PRN, cyclic), a configurable intake window per dose, and a traceable dose history where every slot reads taken, late, skipped, or missed — the same ledger the compliance rate is computed from, so the percentage can never disagree with the timeline.
 - **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, Dutch, and Brazilian Portuguese end to end.
 
 The full feature tour, integration guides, and API reference live at [docs.healthlog.dev](https://docs.healthlog.dev).
 
@@ -89,11 +85,11 @@ Verify the running version:
 curl -s http://localhost:3000/api/version   # returns version + buildSha + builtAt
 ```
 
-`SESSION_COOKIE_SECURE=false` is the one setting plain-HTTP self-hosts must set: without it the session cookie carries the `Secure` flag, the browser drops it over HTTP, and login silently fails. Leave it unset (or `true`) only when a TLS reverse proxy serves HTTPS — and then set `NEXT_PUBLIC_APP_URL` and `APP_URL` to the public URL first (see the [self-hosting guide](https://docs.healthlog.dev/self-hosting/)).
+`SESSION_COOKIE_SECURE=false` is the one setting plain-HTTP self-hosts must set: without it the session cookie carries the `Secure` flag, the browser drops it over HTTP, and login silently fails. Leave it unset (or `true`) only when a TLS reverse proxy serves HTTPS — and then set `NEXT_PUBLIC_APP_URL` and `APP_URL` to the public URL first (see the [self-hosting guide](https://docs.healthlog.dev/getting-started/self-host-in-10-minutes/)).
 
-Persistent state lives in exactly one named volume (`pgdata`, the Postgres data dir); the app container is stateless, so backing up the database backs up everything.
+Persistent state lives in the database volume (`postgres-data`) and in `backups`, which holds the nightly database dumps; the app container is stateless. An install from v1.45 or earlier moves its Postgres 16 database from `pgdata` into the new volume on the first start ([details](docs/ops/postgres-major-upgrade.md)); recovering a lost server is in [disaster-recovery.md](docs/ops/disaster-recovery.md).
 
-NAS and homelab users have ready-made paths: [Unraid Community Applications](docs/self-hosting/unraid.md) and [Portainer app templates](docs/self-hosting/portainer/README.md).
+NAS and homelab users have ready-made paths: [Unraid Community Applications](docs/self-hosting/unraid.md), [Portainer app templates](docs/self-hosting/portainer/README.md) and [TrueNAS](docs/self-hosting/truenas.md) (the Community train app is pending catalog review).
 
 ## Self-hosting
 
@@ -109,17 +105,18 @@ The App Store listing carries a small price, which exists to cover Apple's yearl
 
 ## Tech stack
 
-Next.js 16 (App Router, React Server Components), TypeScript strict, PostgreSQL 16 with Prisma, pg-boss for jobs, Tailwind CSS 4 + shadcn/ui, Recharts, WebAuthn passkeys, Vitest + Playwright, multi-stage Alpine Docker image. The OpenAPI 3.1 contract for native clients is generated from the Zod schemas at [`docs/api/openapi.yaml`](docs/api/openapi.yaml).
+Next.js 16 (App Router, React Server Components), TypeScript strict, PostgreSQL 18 with Prisma, pg-boss for jobs, Tailwind CSS 4 + shadcn/ui, Recharts, WebAuthn passkeys, Vitest + Playwright, multi-stage Docker image on the official Node 22 Debian slim base. The OpenAPI 3.1 contract for native clients is generated from the Zod schemas at [`docs/api/openapi.yaml`](docs/api/openapi.yaml).
 
 ## Documentation
 
-|                        |                                                  |
-| ---------------------- | ------------------------------------------------ |
-| User and operator docs | [docs.healthlog.dev](https://docs.healthlog.dev) |
-| Release history        | [CHANGELOG.md](CHANGELOG.md)                     |
-| API contract           | [`docs/api/openapi.yaml`](docs/api/openapi.yaml) |
-| Security policy        | [SECURITY.md](SECURITY.md)                       |
-| Contributing           | [CONTRIBUTING.md](CONTRIBUTING.md)               |
+|                        |                                                              |
+| ---------------------- | ------------------------------------------------------------ |
+| User and operator docs | [docs.healthlog.dev](https://docs.healthlog.dev)             |
+| Release history        | [CHANGELOG.md](CHANGELOG.md)                                 |
+| API contract           | [`docs/api/openapi.yaml`](docs/api/openapi.yaml)             |
+| Security policy        | [SECURITY.md](SECURITY.md)                                   |
+| Contributing           | [CONTRIBUTING.md](CONTRIBUTING.md)                           |
+| Translating            | [CONTRIBUTING.md#translations](CONTRIBUTING.md#translations) |
 
 ## Status
 
@@ -127,9 +124,13 @@ Actively developed — new releases roughly weekly, issue reports and PRs welcom
 
 ## Thanks
 
-HealthLog is built in the open and people keep making it better. Alongside
-bug reports, setup questions and the ideas that turned into features, these
-people have sent code that shipped:
+HealthLog started as something I built for myself. That it has turned into a project other people use, care about and help shape still surprises me, and I am grateful for every part of it.
+
+Thank you to everyone who sent code that shipped: [@TimonBed](https://github.com/TimonBed), [@Antiheld86](https://github.com/Antiheld86), [@BernhardBuckel](https://github.com/BernhardBuckel), [@balajiv113](https://github.com/balajiv113), [@aucun6352](https://github.com/aucun6352), [@mathewcsims](https://github.com/mathewcsims) and [@muhdusama](https://github.com/muhdusama).
+
+Thank you to everyone who opened an issue, asked a question in the discussions or wrote me an email, and especially to [@lutzkind](https://github.com/lutzkind), [@HercoGC](https://github.com/HercoGC), [@mills1975](https://github.com/mills1975), [@sreeramachandramurthy](https://github.com/sreeramachandramurthy), [@CritLoren](https://github.com/CritLoren), [@mbreitkreuz](https://github.com/mbreitkreuz), [@k-nacion](https://github.com/k-nacion), [@NebuPookins](https://github.com/NebuPookins), [@Nazza01](https://github.com/Nazza01), [@Cnote43](https://github.com/Cnote43) and [@juliaanvaneijndt](https://github.com/juliaanvaneijndt), whose reports shaped HealthLog again and again. Most of what got better in the last months started with someone describing what went wrong for them, often with a log, a screenshot and a second try when the first fix was not enough.
+
+And thank you to everyone who supported the project with a coffee or by buying the iPhone app. I don't name anyone here, but I read every message that comes with it. It pays for the servers and the Apple developer account, and it tells me that HealthLog is worth the evenings.
 
 <a href="https://github.com/MBombeck/HealthLog/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=MBombeck/HealthLog" alt="Contributors to HealthLog" />

bundle-budget.json

@@ -1,12 +1,122 @@
 {
-  "$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": 447,
-    "/insights/page": 434,
-    "/measurements/page": 433,
-    "/insights/mood/page": 447
-  },
+  "$comment": "Client-bundle budgets, enforced by scripts/check-bundle-budget.mjs --check after `pnpm build` in CI; the script header describes the method. Numbers are KB gzip. routeBaselineKbGz is the measured first load of every page (the shared rootMainFiles plus the page's client-reference chunks, each file counted once by content hash), written with --write-baselines; a page fails when it is more than routeDriftAllowanceKbGz over its baseline, and a page without a baseline fails until one is written in the same change. firstLoadP95KbGz and firstLoadMaxKbGz cap the distribution across pages. uniqueClientKbGz caps the distinct client code: every module counted once by its module id, the lazy message catalogs excluded. maxCatalogKbGz holds each catalog, maxRechartsChunks the one shared chart chunk. The summed-chunk aggregate the gate used up to v1.44.0 (3875 KB there, capped at 3900) is still printed but no longer gated: it counted a module once per chunk group it landed in, so it rose whenever a page moved code into on-demand chunks and needed a raise in most releases while no reader downloaded more. Re-based at v1.45.0 from the v1.44.0 build, measured on a local arm64 machine: 110 pages, first load p50 336, p95 437, max 451 KB; unique client code 1904 KB in 1224 modules. The five pages watched before keep their numbers within a kilobyte (/ 359, /measurements 339, /insights/mood 337, /insights 323, /settings/[section] 311), and the metric pages that no watched route covered before are gated now too (/insights/weight 339, /insights/pulse 339). Caps: p95 447 and max 461 KB (10 KB over the measurement), unique client code 1930 KB (about 25 KB, roughly two releases of new client code). A raise or a re-base is a reviewed change with the measured numbers and the reason written here; earlier re-bases are in the history of this file. v1.47.0 raised maxCatalogKbGz from 210 to 250 for the Russian catalog: Cyrillic is two bytes per letter in UTF-8, so the same key set is 1.12 MB raw against about 0.8 MB for the Latin-script locales, 240 KB gz as an emitted chunk where the largest Latin one is under 210. A reader downloads one catalog, once; nothing else in the budget moved.",
   "routeDriftAllowanceKbGz": 20,
-  "totalClientKbGz": 3749,
-  "maxRechartsChunks": 1
+  "firstLoadP95KbGz": 447,
+  "firstLoadMaxKbGz": 461,
+  "uniqueClientKbGz": 1930,
+  "maxRechartsChunks": 1,
+  "maxCatalogKbGz": 250,
+  "routeBaselineKbGz": {
+    "/_global-error/page": 133,
+    "/_not-found/page": 282,
+    "/about/page": 282,
+    "/achievements/page": 292,
+    "/admin/[section]/page": 451,
+    "/admin/page": 297,
+    "/auth/claim/page": 298,
+    "/auth/login/page": 290,
+    "/auth/register/page": 288,
+    "/c/[token]/page": 284,
+    "/checkups/page": 365,
+    "/checkups/practitioners/page": 289,
+    "/claim/[token]/page": 282,
+    "/coach/conversations/page": 294,
+    "/coach/page": 355,
+    "/coach/plans/page": 288,
+    "/confirm-access/page": 287,
+    "/custom-metrics/[id]/page": 303,
+    "/custom-metrics/[id]/values/page": 311,
+    "/cycle/page": 412,
+    "/documents/deleted/page": 291,
+    "/documents/page": 378,
+    "/enroll-mfa/page": 305,
+    "/illness/[id]/page": 447,
+    "/illness/page": 421,
+    "/insights/active-energy/page": 336,
+    "/insights/audio-events/page": 337,
+    "/insights/blood-glucose/page": 340,
+    "/insights/blood-pressure/page": 336,
+    "/insights/bmi/page": 331,
+    "/insights/body-fat/page": 336,
+    "/insights/body-temperature/page": 336,
+    "/insights/body-water/page": 336,
+    "/insights/bone-mass/page": 336,
+    "/insights/breathing-disturbances/page": 337,
+    "/insights/cardio-fitness/page": 336,
+    "/insights/cardio-recovery/page": 337,
+    "/insights/catalog/page": 317,
+    "/insights/daylight/page": 336,
+    "/insights/double-support-time/page": 336,
+    "/insights/ecg/[id]/page": 316,
+    "/insights/ecg/page": 316,
+    "/insights/environmental-audio/page": 337,
+    "/insights/falls/page": 336,
+    "/insights/fat-free-mass/page": 336,
+    "/insights/fat-mass/page": 336,
+    "/insights/flights-climbed/page": 336,
+    "/insights/grip-strength/page": 337,
+    "/insights/headphone-audio/page": 336,
+    "/insights/health-score/page": 315,
+    "/insights/hrv/page": 337,
+    "/insights/lean-body-mass/page": 336,
+    "/insights/medications/page": 338,
+    "/insights/mood/page": 337,
+    "/insights/muscle-mass/page": 337,
+    "/insights/nutrients/page": 319,
+    "/insights/oxygen/page": 337,
+    "/insights/page": 323,
+    "/insights/pain/page": 336,
+    "/insights/pulse-wave-velocity/page": 336,
+    "/insights/pulse/page": 339,
+    "/insights/recovery/page": 330,
+    "/insights/respiratory-rate/page": 336,
+    "/insights/resting-pulse/page": 337,
+    "/insights/scores/[metric]/page": 328,
+    "/insights/six-minute-walk/page": 336,
+    "/insights/skin-temperature/page": 338,
+    "/insights/sleep/page": 337,
+    "/insights/sources/page": 321,
+    "/insights/stair-ascent-speed/page": 336,
+    "/insights/stair-descent-speed/page": 336,
+    "/insights/step-length/page": 336,
+    "/insights/steps/page": 337,
+    "/insights/values/[type]/page": 350,
+    "/insights/vascular-age/page": 337,
+    "/insights/visceral-fat/page": 336,
+    "/insights/waist-to-height/page": 336,
+    "/insights/waist/page": 336,
+    "/insights/walking-asymmetry/page": 336,
+    "/insights/walking-distance/page": 336,
+    "/insights/walking-heart-rate/page": 337,
+    "/insights/walking-speed/page": 336,
+    "/insights/walking-steadiness/page": 336,
+    "/insights/weight/page": 339,
+    "/insights/workouts/[id]/page": 437,
+    "/insights/workouts/page": 437,
+    "/insights/wrist-temperature/page": 336,
+    "/invite/[token]/page": 282,
+    "/labs/[biomarkerId]/page": 327,
+    "/labs/[biomarkerId]/values/page": 335,
+    "/labs/page": 423,
+    "/measurements/page": 339,
+    "/medications/[id]/history/page": 283,
+    "/medications/[id]/page": 402,
+    "/medications/new/page": 282,
+    "/medications/page": 355,
+    "/mental-wellbeing/page": 297,
+    "/mood/page": 438,
+    "/notifications/page": 289,
+    "/onboarding/[step]/page": 445,
+    "/onboarding/handover/page": 295,
+    "/onboarding/page": 286,
+    "/page": 359,
+    "/privacy/page": 282,
+    "/profile/page": 285,
+    "/settings/[section]/page": 311,
+    "/settings/layout/[module]/page": 380,
+    "/settings/modules/[module]/page": 374,
+    "/settings/page": 282,
+    "/timeline/page": 331,
+    "/vaccinations/page": 327
+  }
 }

docker-compose.yml

@@ -1,4 +1,4 @@
-# HealthLog — two-container stack (app + Postgres 16).
+# HealthLog — two-container stack (app + Postgres 18).
 #
 # First run (clean host):
 #   cp .env.example .env
@@ -14,9 +14,13 @@
 # and login silently fails. This is the single most common self-host snag.
 # Leave it unset (or true) only when a TLS reverse proxy serves HTTPS.
 #
-# Persistent state lives in exactly one named volume (`pgdata`, Postgres'
-# data dir). The app container is stateless, so a backup of the database is
-# a backup of everything. The optional GeoLite2 databases are either baked
+# Persistent state lives in the named volume `postgres-data` (Postgres' data).
+# The app container is stateless, so a backup of the database is a backup of
+# everything. `backups` holds the database dumps the app takes every night and
+# before every migration (docs/ops/disaster-recovery.md); keep a copy of them
+# off this host, or set the off-host bucket below. `pgdata` is where Postgres 16 kept the data up to
+# v1.45; on an install that has it, `db-upgrade` moves it into Postgres 18 once
+# and then leaves it alone as the way back (docs/ops/postgres-major-upgrade.md). The optional GeoLite2 databases are either baked
 # into the image at build time or mounted read-only from the host and
 # pointed at with GEOLITE2_DIR — either way they are replaceable, not state.
 
@@ -72,6 +76,17 @@ 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:-}"
+  # The app connects as `healthlog_app_<database>_<hash>`, a role the
+  # entrypoint creates for this database that reads and writes rows but
+  # cannot change the schema; the migrations and the queue's install keep
+  # the owner above. off keeps the app on the owner (for an operator who
+  # manages database roles). See docs/self-hosting/database-role.md.
+  DB_APP_ROLE: "${DB_APP_ROLE:-}"
   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
@@ -83,8 +98,10 @@ x-healthlog-env: &healthlog_env
   TELEGRAM_WEBHOOK_SECRET: "${TELEGRAM_WEBHOOK_SECRET:-}"
   # v1.18.11 (W3) — client-IP resolution + geo lookup. Behind Cloudflare
   # the real visitor IP is in `cf-connecting-ip`; set
-  # TRUST_CF_CONNECTING_IP=1 ONLY when Cloudflare is in front (off by
-  # default — a direct-exposed host must not trust a forgeable header).
+  # TRUST_CF_CONNECTING_IP=1 ONLY when the origin accepts connections from
+  # Cloudflare alone (a Tunnel, or a firewall admitting only Cloudflare's
+  # ranges): the header is believed from every connection (off by default;
+  # see docs/self-hosting/reverse-proxy.md).
   # IP_GEO_LOOKUP_URL overrides the default ipwho.is provider (HTTPS by
   # default); IP_GEO_LOOKUP_DISABLED=1 stops all third-party IP egress.
   # IP_GEO_ALLOW_INSECURE=true permits a plain-HTTP provider URL (e.g. the
@@ -97,7 +114,14 @@ x-healthlog-env: &healthlog_env
   # collapses every anonymous caller into one rate-limit bucket. Listed here
   # so an operator value in .env reaches the container (the `environment:`
   # block is a whitelist).
+  # TRUSTED_PROXY_CIDRS names the addresses the reverse proxy connects from
+  # (comma-separated CIDRs). Set, only those connections may report a client
+  # address; unset, any private address may, which behind Docker Desktop,
+  # OrbStack or docker-proxy includes every caller of the published port.
+  # Same host: 127.0.0.1/32,::1/128. Docker network: the proxy's subnet.
+  # See docs/self-hosting/reverse-proxy.md.
   TRUST_PROXY_HOPS: "${TRUST_PROXY_HOPS:-}"
+  TRUSTED_PROXY_CIDRS: "${TRUSTED_PROXY_CIDRS:-}"
   TRUST_CF_CONNECTING_IP: "${TRUST_CF_CONNECTING_IP:-}"
   IP_GEO_LOOKUP_URL: "${IP_GEO_LOOKUP_URL:-}"
   IP_GEO_LOOKUP_DISABLED: "${IP_GEO_LOOKUP_DISABLED:-}"
@@ -132,6 +156,28 @@ x-healthlog-env: &healthlog_env
   # all = bundle web + worker in this container (default, single-host)
   # web = serve HTTP only; pair with a separate app-worker service
   HEALTHLOG_PROCESS_TYPE: "${HEALTHLOG_PROCESS_TYPE:-all}"
+  # compose | truenas | coolify | unraid | portainer. Only chooses which
+  # instructions the admin's "Back up your encryption key" step shows first.
+  HEALTHLOG_PLATFORM: "${HEALTHLOG_PLATFORM:-}"
+  # enforce (default) | warn. The start-up encryption key check refuses to
+  # serve when the key does not open the stored data; warn only logs it and
+  # serves anyway. A last resort for a refusal you are certain is false: it
+  # disables a safety check. See docs/self-hosting/getting-started.md.
+  ENCRYPTION_KEY_CHECK: "${ENCRYPTION_KEY_CHECK:-}"
+  # The whole-database dump (docs/ops/disaster-recovery.md). Nightly at
+  # DB_BACKUP_SCHEDULE (five-field cron in Europe/Berlin time, default
+  # "30 1 * * *") into DB_BACKUP_DIR (default /var/lib/healthlog/backups, the
+  # `backups` volume below), keeping DB_BACKUP_KEEP daily dumps (default 7)
+  # and the last two taken before a migration. With the off-host bucket set,
+  # each nightly dump is also uploaded under `database/`, sealed with
+  # BACKUP_ENCRYPTION_KEY. DB_BACKUP_ENABLED=false stops the nightly dump;
+  # DB_BACKUP_BEFORE_MIGRATE=false skips the dump before migrations. Change
+  # DB_BACKUP_DIR only together with the volume mount.
+  DB_BACKUP_ENABLED: "${DB_BACKUP_ENABLED:-}"
+  DB_BACKUP_DIR: "${DB_BACKUP_DIR:-}"
+  DB_BACKUP_SCHEDULE: "${DB_BACKUP_SCHEDULE:-}"
+  DB_BACKUP_KEEP: "${DB_BACKUP_KEEP:-}"
+  DB_BACKUP_BEFORE_MIGRATE: "${DB_BACKUP_BEFORE_MIGRATE:-}"
   BACKUP_ENCRYPTION_KEY: "${BACKUP_ENCRYPTION_KEY:-}"
   BACKUP_ENCRYPTION_PREVIOUS_KEYS: "${BACKUP_ENCRYPTION_PREVIOUS_KEYS:-}"
   BACKUP_S3_ENDPOINT: "${BACKUP_S3_ENDPOINT:-}"
@@ -153,6 +199,7 @@ x-healthlog-env: &healthlog_env
   # the block exists: `environment:` is a whitelist, and a value in .env that
   # is not named here never arrives.
   AUDIT_LOG_RETENTION_DAYS: "${AUDIT_LOG_RETENTION_DAYS:-}"
+  ACCOUNT_DELETION_GRACE_DAYS: "${ACCOUNT_DELETION_GRACE_DAYS:-}"
   # How long Coach conversations are kept, in days (default 365, floor 30).
   # Like the audit window this number is PUBLISHED to the user on the Data &
   # Privacy page, so an instance running 90 has to be able to say 90.
@@ -213,10 +260,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
@@ -236,6 +292,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
@@ -251,17 +312,23 @@ x-healthlog-env: &healthlog_env
   OIDC_SCOPES: "${OIDC_SCOPES:-}"
   OIDC_BUTTON_LABEL: "${OIDC_BUTTON_LABEL:-}"
   OIDC_ONLY: "${OIDC_ONLY:-}"
-  # Deploy-result webhook (optional). DEPLOY_WEBHOOK_SECRET authenticates
-  # POST /api/internal/deploy-webhook; DEPLOY_LOGS_URL is the
-  # deployment-dashboard URL (e.g. the Coolify UI) linked in
-  # deploy-failure notifications. Listed here so operator values in
-  # .env reach the container (the `environment:` block is a whitelist).
+  # Deploy-result webhook (optional). POST /api/internal/deploy-webhook
+  # authenticates either with DEPLOY_WEBHOOK_SECRET in the
+  # X-Deploy-Webhook-Secret header (what Coolify's stock sender can do; no
+  # replay protection) or with X-Deploy-Webhook-Signature: sha256=<HMAC of
+  # "<X-Deploy-Webhook-Timestamp>.<body>" under the secret>, the timestamp
+  # within 5 minutes. DEPLOY_WEBHOOK_REQUIRE_TIMESTAMP=true also requires a
+  # fresh X-Deploy-Webhook-Timestamp on a secret-header request;
+  # DEPLOY_WEBHOOK_REQUIRE_SIGNATURE=true accepts signed requests only, the
+  # one setting that stops a replay. DEPLOY_LOGS_URL is the
+  # deployment-dashboard URL (e.g. the Coolify UI) linked in deploy-failure
+  # notifications. Listed here so operator values in .env reach the
+  # container (the `environment:` block is a whitelist). See
+  # docs/ops/deploy.md.
   DEPLOY_WEBHOOK_SECRET: "${DEPLOY_WEBHOOK_SECRET:-}"
   DEPLOY_LOGS_URL: "${DEPLOY_LOGS_URL:-}"
-  # Optional replay hardening: when "true", the deploy webhook
-  # requires a fresh X-Deploy-Webhook-Timestamp header (±5 min).
-  # See docs/ops/deploy.md.
   DEPLOY_WEBHOOK_REQUIRE_TIMESTAMP: "${DEPLOY_WEBHOOK_REQUIRE_TIMESTAMP:-}"
+  DEPLOY_WEBHOOK_REQUIRE_SIGNATURE: "${DEPLOY_WEBHOOK_REQUIRE_SIGNATURE:-}"
   # TLS leaf SPKI-change alarm baseline (optional). The native client
   # pins the served TLS leaf; this is the known-good pin set the monitor
   # alarms against on a rotation. Comma-separated for the dual-pin
@@ -286,11 +353,11 @@ x-healthlog-env: &healthlog_env
   # you run a gateway this instance should trust; it widens only the admin
   # setting, never the per-user BYO-key posture.
   ADMIN_AI_BASE_URL_ALLOWLIST: "${ADMIN_AI_BASE_URL_ALLOWLIST:-}"
-  # Codex (ChatGPT sign-in) model slugs. Set CODEX_MODEL to pin one slug
-  # ahead of the built-in chain, or CODEX_MODEL_FALLBACK_CHAIN (comma-
-  # separated) to replace the chain outright. Reach for these when the
-  # provider rotates a slug and every request starts coming back 503 —
-  # without them a rotation needs a new release to fix.
+  # Codex (ChatGPT sign-in) model slugs. Unset, each sign-in picks from the
+  # models its account is offered, with a built-in order as the fallback.
+  # Set CODEX_MODEL to pin one slug ahead of that, or
+  # CODEX_MODEL_FALLBACK_CHAIN (comma-separated) to replace the order
+  # outright; the account's list is then not read.
   CODEX_MODEL: "${CODEX_MODEL:-}"
   CODEX_MODEL_FALLBACK_CHAIN: "${CODEX_MODEL_FALLBACK_CHAIN:-}"
   # Surfaces reviewed n-of-1 experiment outcomes in the Coach snapshot.
@@ -314,6 +381,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
@@ -381,6 +453,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
@@ -434,6 +513,11 @@ services:
       - "3000:3000"
     environment:
       <<: *healthlog_env
+    # The database dumps (DB_BACKUP_DIR). Without this mount the app still
+    # copies its nightly dump off-host when the bucket is set, but keeps none
+    # here and takes none before a migration; the boot log says so.
+    volumes:
+      - backups:/var/lib/healthlog/backups
     # Bring your own GeoLite2 databases. The published image only carries
     # MMDBs if the build had a MaxMind licence key, so on `:latest` the
     # offline tier is usually absent and every login IP goes to the online
@@ -443,13 +527,15 @@ services:
     # matches GEOLITE2_DIR's default (/opt/geolite2), so this works as-is
     # once uncommented. Mounting at a different container path also works,
     # just also set GEOLITE2_DIR in .env to match it.
-    # Steps: docs/self-hosting/geolite2.md.
+    # Steps: docs/self-hosting/geolite2.md. The line goes under `volumes:`
+    # above, beside the backups line:
     #
-    # volumes:
     #   - ./geolite2:/opt/geolite2:ro
     depends_on:
       db:
         condition: service_healthy
+      db-upgrade:
+        condition: service_completed_successfully
     restart: unless-stopped
     # Bounded log rotation: the default json-file driver keeps every line
     # forever, which is exactly what fills the disk on the small NAS /
@@ -459,23 +545,51 @@ services:
       options:
         max-size: "10m"
         max-file: "3"
-    # Conservative memory ceiling for a small host. HEALTHLOG_PROCESS_TYPE=all
-    # bundles the AI/rollup worker into this same process, and unbounded that
-    # workload can grow large enough under load to starve Postgres of memory
-    # on a shared host. 1g is a starting point, not a measured ceiling — raise
-    # it with APP_MEMORY_LIMIT in .env if the app gets OOM-killed under real
-    # load.
-    mem_limit: "${APP_MEMORY_LIMIT:-1g}"
+    # Memory ceiling for the app. HEALTHLOG_PROCESS_TYPE=all bundles the
+    # AI/rollup/backup worker into this same process, and unbounded that
+    # 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. 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}"
+    # On `docker stop` (a redeploy) the app stops taking requests, lets the
+    # requests in flight finish and gives running jobs up to 30 s to end
+    # before it exits. Docker's default of 10 s cut that short and left
+    # jobs marked active until their expiry, holding exclusive queues.
+    stop_grace_period: 45s
     healthcheck:
       test:
         [
-          "CMD-SHELL",
-          "wget --no-verbose --tries=1 --spider http://127.0.0.1:3000/api/health || exit 1",
+          "CMD",
+          "node",
+          "-e",
+          "fetch('http://127.0.0.1:3000/api/health',{signal:AbortSignal.timeout(4000)}).then(r=>process.exit(r.ok?0:1),()=>process.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.
+      # The probe's own 4 s abort 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.
@@ -494,24 +608,29 @@ services:
   #   environment:
   #     <<: *healthlog_env
   #     HEALTHLOG_PROCESS_TYPE: "worker"
+  #   # The worker takes the nightly database dump, so it needs the volume.
+  #   volumes:
+  #     - backups:/var/lib/healthlog/backups
   #   depends_on:
   #     db:
   #       condition: service_healthy
+  #     db-upgrade:
+  #       condition: service_completed_successfully
   #   restart: unless-stopped
   #   logging:
   #     driver: json-file
   #     options:
   #       max-size: "10m"
   #       max-file: "3"
-  #   mem_limit: "${WORKER_MEMORY_LIMIT:-1g}"
+  #   mem_limit: "${WORKER_MEMORY_LIMIT:-1536m}"
+  #   stop_grace_period: 45s
 
   db:
-    # Pinned to the concrete minor instead of the floating `16-alpine`
+    # Pinned to the concrete minor instead of the floating `18-alpine`
     # alias so a database update is always a deliberate, reviewable
-    # change (at pin time `16-alpine` resolved to this same digest, so
-    # existing deployments see no image change). Minor releases share
-    # the on-disk format — bumping this pin is safe without a dump /
-    # restore; a major-version bump (17+) is not.
+    # change. Minor releases share the on-disk format, so bumping this pin
+    # is safe without a dump / restore; a major version is not, which is
+    # what `db-upgrade` below and docs/ops/postgres-major-upgrade.md are for.
     #
     # The pin only works as long as something watches it: PostgreSQL
     # publishes minor releases with security and data-corruption fixes and
@@ -521,8 +640,23 @@ services:
     # `.github/dependabot.yml` now raises a PR for each new minor;
     # `src/__tests__/database-pin-is-watched.test.ts` keeps both halves
     # (concrete pin, active watch) from being dropped.
-    image: postgres:16.15-alpine
+    image: postgres:18.6-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
@@ -536,8 +670,12 @@ services:
       POSTGRES_USER: healthlog
       POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
       POSTGRES_DB: healthlog
+    # From 18 on, the image keeps its data under /var/lib/postgresql/18/docker
+    # and expects the volume one level up, so the next major can sit beside
+    # this one in the same volume. Mounting it at .../data, as 16 had it,
+    # makes the container refuse to start.
     volumes:
-      - pgdata:/var/lib/postgresql/data
+      - postgres-data:/var/lib/postgresql
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U healthlog"]
       interval: 5s
@@ -558,5 +696,199 @@ services:
         max-size: "10m"
         max-file: "3"
 
+  # Moves a Postgres 16 database from v1.45 or earlier into Postgres 18, once,
+  # on the first start after the update. A major version cannot read the data
+  # directory of an older one, so changing the image line alone would leave
+  # the database refusing to start.
+  #
+  # On every start it decides in a second and exits:
+  # - no `pgdata` data (a new install): nothing to do;
+  # - the database service runs Postgres 16 (after going back): nothing to
+  #   do, the live 16 volume is left alone;
+  # - 16 was used again after an earlier move: refuses, so the app does not
+  #   start on the move-day copy;
+  # - Postgres 18 already holds the database: nothing to do;
+  # - otherwise it starts Postgres 16 inside this container on the old
+  #   volume, streams a dump into the new database in one transaction,
+  #   compares the row count of every table, gathers planner statistics and
+  #   marks the old volume as moved. `app` starts only after it succeeded.
+  #   A move cut short (a restart, a full disk) leaves a "moving" marker, and
+  #   the next start empties the new database and runs it again from scratch.
+  #
+  # The old volume is read, never changed, apart from that marker file, so
+  # going back is the previous image and volume lines. If anything fails, the
+  # new database stays empty, `app` does not start, and the log says why.
+  # It costs one small image pull; a later release removes the service.
+  db-upgrade:
+    image: postgres:16.15-alpine
+    container_name: healthlog-db-upgrade
+    # Runs once per `compose up` and exits. "no" also keeps hosts such as
+    # Coolify from reporting the exited container as a failed service.
+    restart: "no"
+    security_opt:
+      - no-new-privileges:true
+    environment:
+      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+      # Read-only, only to check there is room for the copy before starting.
+      - postgres-data:/var/lib/postgresql/next:ro
+    depends_on:
+      db:
+        condition: service_healthy
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+    # `$$` is how compose spells a literal `$`.
+    entrypoint: ["/bin/sh", "-c"]
+    command:
+      - |
+        set -eu
+        set -o pipefail
+        log() { echo "db-upgrade: $$*"; }
+        OLD=/var/lib/postgresql/data
+        MARK="$$OLD/HEALTHLOG_MOVED_TO_POSTGRES_18"
+        MOVING="$$OLD/HEALTHLOG_MOVING_TO_POSTGRES_18"
+        export PGPASSWORD="$$POSTGRES_PASSWORD"
+        new() { psql -h db -U healthlog -d healthlog -v ON_ERROR_STOP=1 -Atqc "$$1"; }
+        old() { psql -h /tmp -U healthlog -d healthlog -v ON_ERROR_STOP=1 -Atqc "$$1"; }
+        empty_new() {
+          for S in $$(new "SELECT quote_ident(nspname) FROM pg_namespace WHERE nspname NOT LIKE 'pg\\_%' AND nspname <> 'information_schema'"); do
+            new "DROP SCHEMA $$S CASCADE"
+          done
+          new "CREATE SCHEMA public"
+        }
+        if [ ! -s "$$OLD/PG_VERSION" ]; then
+          log "no Postgres 16 database to move, nothing to do"
+          exit 0
+        fi
+        # The database service must be the new major. After going back to 16 the
+        # service runs on this very volume: touching it then would wipe the live data.
+        i=0
+        until NEWVER=$$(new "SHOW server_version_num" 2>/dev/null); do
+          i=$$((i + 1))
+          [ "$$i" -lt 60 ] || { log "the database service did not answer for a minute"; exit 1; }
+          sleep 1
+        done
+        if [ "$$NEWVER" -lt 180000 ]; then
+          log "the database service runs Postgres $$((NEWVER / 10000)), not 18: nothing to move, the old volume is left alone"
+          exit 0
+        fi
+        checkpoint() { pg_controldata "$$OLD" | awk -F': *' '/^Latest checkpoint location/ { print $$2 }'; }
+        USER_TABLES="FROM pg_tables WHERE schemaname NOT IN ('pg_catalog', 'information_schema')"
+        TABLES=$$(new "SELECT count(*) $$USER_TABLES")
+        if [ -e "$$MARK" ]; then
+          MOVED_ON=$$(sed -n 1p "$$MARK")
+          MOVED_CHECKPOINT=$$(sed -n 2p "$$MARK")
+          if [ -n "$$MOVED_CHECKPOINT" ] && [ "$$(checkpoint)" != "$$MOVED_CHECKPOINT" ]; then
+            log "the Postgres 16 database changed after it was moved on $$MOVED_ON: it was used again after going back to 16."
+            log "Postgres 18 still holds the state of that day, so it is not started on. To move the current 16 database,"
+            log "see docs/ops/postgres-major-upgrade.md, \"Updating again after going back\"."
+            exit 1
+          fi
+          if [ "$$TABLES" != 0 ]; then
+            log "the Postgres 16 database was moved on $$MOVED_ON, nothing to do"
+            exit 0
+          fi
+          log "the Postgres 16 database was moved on $$MOVED_ON, but the Postgres 18 database is empty now."
+          log "Not importing the old state again by itself. See docs/ops/postgres-major-upgrade.md, \"Starting over\"."
+          exit 1
+        fi
+        if [ -e "$$MOVING" ]; then
+          log "an earlier move did not finish; emptying the Postgres 18 database and starting it again"
+          empty_new
+        elif [ "$$TABLES" != 0 ]; then
+          log "the Postgres 18 database already holds data, leaving both as they are"
+          exit 0
+        fi
+        VERSION=$$(cat "$$OLD/PG_VERSION")
+        if [ "$$VERSION" != 16 ]; then
+          log "the old data directory is Postgres $$VERSION, this step moves Postgres 16 only."
+          log "See docs/ops/postgres-major-upgrade.md to move it by hand."
+          exit 1
+        fi
+        NEED=$$(du -sk "$$OLD" | cut -f1)
+        FREE=$$(df -Pk /var/lib/postgresql/next | awk 'NR == 2 { print $$4 }')
+        # Room for the copy, and for the dump the app takes before its first migration.
+        if [ "$$FREE" -le $$((NEED * 3 / 2)) ]; then
+          log "the move needs about $$((NEED * 3 / 2 / 1024)) MiB free for the new database and its first dump, the disk has $$((FREE / 1024)) MiB."
+          log "Nothing was changed. Free some space and start the stack again."
+          exit 1
+        fi
+        trap 'CODE=$$?; [ "$$CODE" = 0 ] || log "the move stopped (exit $$CODE). The old volume is untouched; the next start begins it again."' EXIT
+        date -u +%Y-%m-%dT%H:%M:%SZ > "$$MOVING"
+        log "moving the Postgres 16 database ($$((NEED / 1024)) MiB on disk) into Postgres 18"
+        su-exec postgres postgres -D "$$OLD" -c listen_addresses= -c unix_socket_directories=/tmp &
+        PID=$$!
+        i=0
+        until pg_isready -h /tmp -U healthlog -q; do
+          kill -0 "$$PID" 2>/dev/null || { log "the Postgres 16 server did not start, see the lines above"; exit 1; }
+          i=$$((i + 1))
+          [ "$$i" -lt 600 ] || { log "the Postgres 16 server did not get ready in ten minutes"; exit 1; }
+          sleep 1
+        done
+        pg_dump -h /tmp -U healthlog -Fc healthlog |
+          pg_restore -h db -U healthlog -d healthlog --no-owner --single-transaction --exit-on-error
+        COUNTED=0
+        for T in $$(old "SELECT quote_ident(schemaname) || '.' || quote_ident(tablename) $$USER_TABLES ORDER BY 1"); do
+          A=$$(old "SELECT count(*) FROM $$T")
+          B=$$(new "SELECT count(*) FROM $$T")
+          if [ "$$A" != "$$B" ]; then
+            log "table $$T has $$A rows in Postgres 16 but $$B in Postgres 18. Emptying the new database again."
+            log "Please report this with the lines above."
+            empty_new
+            exit 1
+          fi
+          COUNTED=$$((COUNTED + 1))
+        done
+        log "all $$COUNTED tables arrived with the same row counts"
+        vacuumdb -h db -U healthlog -d healthlog --analyze-in-stages --quiet
+        kill -INT "$$PID"
+        wait "$$PID" || true
+        # The marker keeps the old database's last checkpoint: a later start can tell
+        # whether 16 was used again after the move.
+        { date -u +%Y-%m-%dT%H:%M:%SZ; checkpoint; } > "$$MOVING"
+        mv "$$MOVING" "$$MARK"
+        log "done. The old volume stays as it was, as a way back; see docs/ops/postgres-major-upgrade.md"
+
+  # Restores a database dump into an EMPTY database (docs/ops/disaster-recovery.md).
+  # Never started by `docker compose up`; run it by name:
+  #
+  #   docker compose run --rm db-restore list
+  #   docker compose run --rm db-restore latest
+  #   docker compose run --rm db-restore healthlog-<time>-daily.dump
+  #   docker compose run --rm db-restore latest --from-bucket
+  #
+  # It checks the dump against its manifest and the keys in .env against the
+  # keys the dump was written with, refuses a database that already holds
+  # tables, restores in one transaction and compares every table's row count
+  # with the manifest. Start the app only after it says "Restored".
+  # `--from-bucket` downloads the dump and its manifest from the off-host bucket
+  # (`database/`, the BACKUP_S3_* variables) and opens them with
+  # BACKUP_ENCRYPTION_KEY: the restore after the host and its local dumps are
+  # gone. Files you downloaded yourself restore from a directory you mount:
+  # `docker compose run --rm -v ./restore:/restore:ro db-restore
+  # /restore/healthlog-<time>-daily.dump.enc`.
+  db-restore:
+    image: ghcr.io/mbombeck/healthlog${HEALTHLOG_IMAGE_REF:-:latest}
+    profiles: ["restore"]
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    environment:
+      <<: *healthlog_env
+    volumes:
+      - backups:/var/lib/healthlog/backups
+    depends_on:
+      db:
+        condition: service_healthy
+    entrypoint: ["node", "scripts/db-restore.mjs"]
+    command: ["list"]
+
 volumes:
+  postgres-data:
   pgdata:
+  backups:

docker-entrypoint.sh

@@ -85,11 +85,44 @@ 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
+# When migrations are pending, dump the database into DB_BACKUP_DIR first, so
+# the state before them can be restored (docs/ops/disaster-recovery.md). No
+# directory that survives the container (none writable, or the image's own
+# without the backups volume): a warning, and the boot goes on. A kept
+# directory and a failed dump: the boot stops here, before anything is
+# migrated.
+if ! node scripts/db-dump.mjs pre-migration; then
+  echo "HealthLog: ERROR — not migrating without the dump. Free disk space or fix the error above and start again." >&2
+  echo "HealthLog: to migrate without a dump this once, set DB_BACKUP_BEFORE_MIGRATE=false." >&2
+  exit 1
+fi
+# `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."
 
+# ── The app's database role ──────────────────────────────────
+# Everything above ran as the owner DATABASE_URL names. The app itself
+# connects as `healthlog_app_<database>_<hash>`, this database's own role,
+# which reads and writes rows and runs the queue but cannot change the schema (scripts/db-app-role.mjs says what it may and
+# may not do, and docs/self-hosting/database-role.md how to opt out). The
+# script hands the role's URL over on descriptor 3 only, never on stdout or
+# stderr; nothing handed over means it said why and the app stays on the
+# owner, as before. The owner's URL is replaced, not kept beside it, so it
+# does not reach the app's environment.
+app_database_url="$(node scripts/db-app-role.mjs 3>&1 1>&2)" || app_database_url=""
+if [ -n "$app_database_url" ]; then
+  DATABASE_URL="$app_database_url"
+  export DATABASE_URL
+fi
+unset app_database_url
+
 # ── Start application ────────────────────────────────────────
 echo "HealthLog: Starting application..."
 exec "$@"

docs/CONTRIBUTING-CLIENTS.md

@@ -19,7 +19,7 @@ Every JSON route answers the same shape: `{ data, error }`, with `meta` on the e
 - Refresh tokens rotate per device and are one-time-use. Reusing an old one revokes that device's whole token family, on purpose. Persist the newest pair atomically and never retry a refresh with a token that already succeeded once.
 - Bearer token scopes are fail-closed. A token minted for one purpose does not open unrelated routes, and a route that does not declare a scope refuses narrow tokens outright. Expect `403` to be a normal, recoverable answer, not an anomaly.
 - Admin surfaces are cookie-session only, by construction. A native client cannot be an admin client, whatever scopes its token carries. Do not build admin features.
-- Mutations accept an `Idempotency-Key` header. Replays answer with the original result plus `X-Idempotent-Replay`, so retrying on a dropped connection is safe. Use it for anything a user would notice twice.
+- Mutations accept an `Idempotency-Key` header. A repeat of the same key with the same body answers with the original result plus `X-Idempotent-Replay`, so retrying on a dropped connection is safe. A different body under the same key is treated as a new request, not a replay; still, give each distinct write its own key. Use it for anything a user would notice twice.
 
 ## Data semantics worth knowing before you sync
 

docs/README.md

@@ -17,9 +17,13 @@ notes, and machine-readable specs that ship alongside the source:
   encryption-key rotation, password reset and account recovery, env
   checks, TLS pinning, data repair. These are what an operator reaches
   for during an incident.
-- [`self-hosting/`](./self-hosting/) — horizontal-scaling notes
-  (`HEALTHLOG_PROCESS_TYPE=web|worker|all`) and the deploy-pipeline
-  recipe. Routine install steps stay on `docs.healthlog.dev`. Includes
+- [`self-hosting/`](./self-hosting/) — operator notes next to the code:
+  [`getting-started.md`](./self-hosting/getting-started.md) (install and
+  updates, the page the boot log points at), the TrueNAS, Unraid and
+  Portainer installs with their catalog templates, Tailscale, the reverse
+  proxy, horizontal scaling (`HEALTHLOG_PROCESS_TYPE=web|worker|all`),
+  notification channels, the environment module, document sources and
+  reproductive-health data. Includes
   [`self-hosting/mcp.md`](./self-hosting/mcp.md) — enabling the
   off-by-default MCP connector and pointing Claude.ai / ChatGPT /
   Claude Desktop at it, and [`self-hosting/sso.md`](./self-hosting/sso.md)
@@ -33,13 +37,24 @@ 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.
+  [`using/cycle-calendar-feed.md`](./using/cycle-calendar-feed.md) covers
+  subscribing to the cycle forecast from Google, Apple or Outlook.
 - [`migration/`](./migration/) — migration notes. Currently only
   v1.3 to v1.4; later releases are covered by `CHANGELOG.md` and
   <https://docs.healthlog.dev>.
-- [`integrations/`](./integrations/) — per-integration reference
-  (Withings, Fitbit, Google Health, WHOOP, Apple Health, AI providers,
-  data import).
+- [`integrations/`](./integrations/) — per-integration reference:
+  Withings, WHOOP, Fitbit, Google Health, Strava, Nightscout, Dawarich and
+  Garmin; the Apple Health, Health Connect, document and data
+  imports; AI providers; and Home Assistant with its blueprint. Oura and
+  Polar are covered on the docs site only.
 - [`adr/`](./adr/) — architecture decision records.
 - [`security/`](./security/) — threat-model notes.
 - [`diagrams/`](./diagrams/) — architecture diagrams rendered through
@@ -49,8 +64,18 @@ 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.
+- [`contributing/benchmarks.md`](./contributing/benchmarks.md) — the
+  large-account benchmark (latency and statements per request) and the
+  statement budgets on the hot routes.
+- [`contributing/testing.md`](./contributing/testing.md) — which suite a
+  test belongs in, the route test kit, the integration database, sharding,
+  property and mutation tests, and the flaky-test quarantine.
+- [`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
-README](../README.md#quick-start).
+README](../README.md#quick-start-docker-compose).

docs/api/README.md

@@ -66,7 +66,11 @@ before treating a warning as a regression.
       `health:write`), audience-bound to `/mcp` and refused on REST writes;
     - `POST /api/tokens/measurements` mints `measurements:write`, accepted by
       `POST /api/measurements` and `POST /api/measurements/batch` only, on the
-      holder's own record only;
+      holder's own record only. The readings it writes carry `source: EXTERNAL`
+      and are linked to the token; whether the HealthLog app writes them into
+      Apple Health is the token's `mirrorToAppleHealth` setting (off by
+      default, changed with `PATCH /api/tokens/{id}`), resolved onto every
+      measurement row as `appleHealthMirror`;
     - `POST /api/tokens/workouts` mints `workouts:write`, accepted by
       `POST /api/workouts/batch` only, on the holder's own record only; the
       workouts it writes carry `source: EXTERNAL`;
@@ -78,9 +82,12 @@ before treating a warning as a regression.
     v1.30.17. The path still lists (`GET`) and revokes (`DELETE /api/tokens/{id}`)
     every token above, whichever surface issued it.
 
-  - `sessionCookie` — HttpOnly `healthlog_session` cookie set by the
-    password and passkey login flows. Used by the web app and any iOS
-    client running inside a web view.
+  - `sessionCookie` — HttpOnly session cookie set by the password and
+    passkey login flows. Used by the web app and any iOS client running
+    inside a web view. It is named `__Host-healthlog_session` wherever it is
+    `Secure` (every HTTPS install), so no other host under the same domain
+    can set it; a plain-HTTP install keeps `healthlog_session`. A cookie
+    under the old name is still read and is re-issued under the new one.
 - **`components.schemas`** — DTOs for the documented routes plus the
   underlying Prisma models (e.g. `Measurement`, `Medication`,
   `MedicationIntakeEvent`, `MoodEntry`, `User`, `DashboardLayout`,

docs/api/mcp-capabilities.md

@@ -110,6 +110,14 @@ What `search` matches for the clinical records:
   reading deferred is matched on its title and details only.
 - `vaccination:<id>`: vaccine name, catalogue name, practitioner.
 
+A lab has two ids. `lab:<analyte>` is the analyte view and answers with that
+marker's latest reading. `labresult:<id>` is one reading: its value or text
+result, unit, reference range, status, date, and its own links (the report
+it was read from, the visits it is filed against). Every link to a lab result
+(from a document, a visit, a condition or a medication) uses the reading id,
+so following a report's link lands on the reading that report holds rather
+than on a later draw. Each reading in `get_labs` carries the same id.
+
 Condition and vaccination notes are never searched or returned, the same
 rule the Coach and the doctor report follow. A deleted practitioner is not
 named or matched. Query words shorter than four letters match whole words or

docs/codex-protocol-spec.md

@@ -630,9 +630,11 @@ Confirmed-rejected slugs (despite the source-tree references in the table above)
 
 Confirmed-accepted slugs on a ChatGPT Plus subscription (per `available_in_plans` in `models.json`):
 
-- `gpt-5.5` — HealthLog's default (first chain entry) as of 2026-06
-- `gpt-5.4` / `gpt-5.4-mini` / `gpt-5.2` — accepted per plan
-- `gpt-5.3-codex` — was the default (verified 2026-05-09); the backend rotated off the `-codex` line on 2026-06-02 and this slug is now only accepted intermittently, so it sits on a late chain rung
+- `gpt-5.6-terra` — HealthLog's default (first chain entry) as of 2026-10-24; the backend rejected `gpt-5.5` and everything below it that day. `gpt-5.6-luna` and `gpt-5.6-sol` are its siblings on the same line
+- `gpt-6-sol`, `gpt-6.1-sol`, `gpt-6-luna`, `gpt-6-astra` — the gpt-6 line, listed in `models.json` since 2026-09-22 (`gpt-6.1-sol` the catalog default since 2026-09-29). The catalog names `gpt-6-sol` as the upgrade of `gpt-5.6-terra` and `gpt-5.6-sol`, and `gpt-6-luna` as that of `gpt-5.6-luna`. Every gpt-6 slug lists `input_modalities: ["text", "image"]` and the same reasoning presets as the gpt-5.6 line (`low` to `max`, sol and astra also `ultra`). The presets omit `none`, as they do for `gpt-5.5`, which a live probe on 2026-10-06 showed accepts it; HealthLog sends `none` for "off" on the gpt-6 line too and learns a refusal per slug. A live check on 2026-10-24 found the account's own list (`GET /backend-api/codex/models?client_version=…`) offering `gpt-6.1-sol`, `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna` and the `gpt-5.6` line, all with `input_modalities: ["text", "image"]`. From a HealthLog container with its stored sign-in, `gpt-6.1-sol`, `gpt-6-sol` and `gpt-6-luna` each answered text and read a lab-report image correctly. `gpt-6.1-sol` refuses `reasoning.effort: "none"` and names `low` as its lowest effort, which the client learns and steps up to on the same slug; the other two accept `none`
+- `gpt-5.5` — the default from 2026-06 until 2026-10-24, kept as the last chain rung while plans differ
+
+Retired for ChatGPT sign-in (OpenAI's Codex models page): `gpt-5.2` and `gpt-5.3-codex` on 2026-05-26, `gpt-5.4` and `gpt-5.4-mini` on 2026-08-31, `gpt-5.5` on 2026-10-14 at 19:00 UTC. The backend answers each of them with 400 `model_not_found`, "The '<slug>' model is not supported when using Codex with a ChatGPT account.", which the client reads as a reason to try the next slug.
 
 The `codex-rs/tui/src/model_migration.rs` references to `gpt-5-codex` etc. are _migration prompts_ shown to existing users — they are NOT the slugs sent on the wire after migration. The wire slugs come from `models.json`. Always cross-check `models.json` (`gh api repos/openai/codex/contents/codex-rs/models-manager/models.json`) before picking a default.
 
@@ -640,23 +642,43 @@ The `codex-rs/tui/src/model_migration.rs` references to `gpt-5-codex` etc. are _
 
 The ChatGPT-Codex allow-list is rotated by OpenAI without prior notice (`gpt-5-codex` → `gpt-5.3-codex` happened over 48 h in May 2026 and bricked HealthLog twice while the v1.4.7..v1.4.13 saga unrolled). The cause: a single hard-coded slug in `CODEX_MODEL` flips invalid the moment the upstream rotates it. Operator brief, verbatim 2026-05-09: "Die Integration des Slug Drift Risiko darf halt immer überhaupt nicht sein."
 
-To eliminate that risk class, HealthLog's `CodexClient` walks an ordered chain on every fresh request series.
+To eliminate that risk class, HealthLog's `CodexClient` tries its sign-in's working slug first and otherwise walks an ordered chain built from the models the account is offered.
 
-**Chain** (top = first try; default order is the empirically-safest most-current-first ordering as of 2026-06, after the backend rotated off the `-codex` line on 2026-06-02):
+**The account's model list.** Before it walks, the client reads the list the Codex CLI reads, on the same sign-in as the responses call:
+
+```http
+GET /backend-api/codex/models?client_version=0.165.0 HTTP/1.1
+Host: chatgpt.com
+Authorization: Bearer <oauth-access-token>
+ChatGPT-Account-ID: <chatgpt_account_id>
+originator: healthlog
+```
+
+The answer is `ModelsResponse` from `codex-rs/protocol/src/openai_models.rs`: `{ "models": [ModelInfo, ...] }`, where the client reads `slug`, `visibility` (`list` / `hide` / `none`), `priority` (lower first), `input_modalities` (`text`, `image`, `audio`) and `model_specialty`. `codex-rs/codex-api/src/endpoint/models.rs` appends `client_version`; the backend leaves out models whose `minimal_client_version` is above it, so the version sent tracks a current Codex CLI release (`CODEX_MODELS_CLIENT_VERSION` in `src/lib/ai/codex-model-catalog.ts`). The read is bounded like the CLI's (5 s, `codex-rs/model-provider/src/models_endpoint.rs`) and to 4 MiB, cached per sign-in for an hour, and a failed read waits ten minutes before the next attempt. The list is a hint, never a gate: a read that fails, times out, does not parse or comes back empty leaves the static chain below, and one `ai.codex.models_unreadable` warning per sign-in reports the stretch.
+
+**Order.** `CODEX_MODEL` first when set. `CODEX_MODEL_FALLBACK_CHAIN`, when set, replaces everything after it and the list is not read. Otherwise: the default chain below kept to what the account is offered; then every other offered model in the list's `priority` order, leaving out what the list hides (`visibility` other than `list`), the specialist lines (`model_specialty`) and the `-astra` frontier tier; then the rest of the default chain, so the walk never holds fewer models than before the list existed. `supported_in_api` is not a filter: it describes API-key access, and the CLI ignores it for a ChatGPT sign-in (`ModelPreset::filter_by_auth`). A slug this sign-in was refused in the last six hours goes to the very end, even while its list still offers it. With the list's `input_modalities` for the slug in hand, the Codex vision gate reads them; without, it falls back to the model family.
+
+**Default chain** (top = first try). `gpt-5.6-terra` leads because it is the slug verified against the backend. The gpt-6 rungs follow before terra's own siblings: the catalog names `gpt-6-sol` as terra's upgrade, and the 2026-10-24 rotation retired a whole line at once, so a rotation that takes terra most likely takes `gpt-5.6-luna` and `gpt-5.6-sol` with it. `gpt-6.1-sol` (the catalog default, also on plans `gpt-6-sol` is not offered on) and `gpt-6-luna` (the lighter one) come next. `gpt-6-astra`, the frontier tier, stays out of the default:
 
 ```ts
 const DEFAULT_SLUG_FALLBACK_CHAIN = [
-  "gpt-5.5", // current default across paid tiers as of 2026-06-02
-  "gpt-5.4", // documented fallback
-  "gpt-5.4-mini", // documented lighter-weight fallback
-  "gpt-5.3-codex", // late rung — still accepted intermittently
-  "gpt-5.2", // legacy floor
+  "gpt-5.6-terra", // verified against the backend 2026-10-24
+  "gpt-6-sol", // terra's upgrade in the upstream catalog
+  "gpt-6.1-sol", // the catalog default, on every plan
+  "gpt-6-luna", // lighter gpt-6 sibling
+  "gpt-5.6-luna", // lighter sibling on terra's line
+  "gpt-5.6-sol", // heavier sibling on terra's line
+  "gpt-5.5", // previous default, kept as the last rung while plans differ
 ];
 ```
 
-The shipped constant in `src/lib/ai/codex-client.ts` is authoritative; when the upstream rotates again, that file moves first and this listing follows.
+Every default rung must be a model family the reasoning, sampling and vision gates recognise (`src/lib/ai/openai-model-family.ts`); `codex-slug-fallback.test.ts` holds the chain to that.
 
-The chain is overridable via the env var `CODEX_MODEL_FALLBACK_CHAIN` (comma-separated). The first env-var-named slug supersedes `CODEX_MODEL`; if both are set, `CODEX_MODEL` is folded into position 0 and de-duplicated.
+The shipped constant in `src/lib/ai/codex-slug-chain.ts` is authoritative; when the upstream rotates again, that file moves first and this listing follows.
+
+A fixed chain goes stale. From 2026-10-14, when GPT-5.5 retired, every model on the chain HealthLog shipped then was retired, and every Codex request answered 503 "all configured Codex slugs were rejected" until the chain was updated or `CODEX_MODEL` was set by hand. That is why the account's live list now comes first and the default chain only orders and backs it up.
+
+The chain is overridable via the env var `CODEX_MODEL_FALLBACK_CHAIN` (comma-separated), which replaces it outright; if `CODEX_MODEL` is also set, it is folded into position 0 and de-duplicated.
 
 **Trigger condition** (when to walk to the next slug):
 
@@ -670,15 +692,15 @@ The chain is overridable via the env var `CODEX_MODEL_FALLBACK_CHAIN` (comma-sep
 | `401` after refresh, `403`, `429`, `5xx`                                      | propagate (don't walk)                           |
 | `200` with SSE `response.failed.error.code === "invalid_prompt"`              | propagate (request shape is wrong, slug is fine) |
 
-**Positive cache** — when a slug is observed working (HTTP 200 with at least one `response.completed` event), record `(slug, timestamp)` in a process-local Map. On the next request, jump straight to the cached slug. TTL: 1 hour. Cache scope: per-process (no DB write).
+**Positive cache** — when a slug is observed working (HTTP 200 with at least one `response.completed` event), record `(slug, timestamp)` for that sign-in. On its next request, jump straight to the cached slug; the model list is read only when there is none or it stops working. TTL: 1 hour. Scope: per stored credential (`user:<id>` for a person's connection, `central` for the operator-shared one), process-local, no DB write, at most 1000 sign-ins held. Each entry carries a digest of the ChatGPT account id it was learned under, and a client reads it only under that account, so a credential reconnected to another account starts empty: its first request tries no slug, skips no refusal and trusts no list the old account left, in any process. The vision gate holds no account id; the connect and disconnect routes rebind or drop the entry, so in the process that handled the change it answers from the new sign-in at once, and elsewhere from that process's first request on it. Two sign-ins on different plans no longer overwrite each other's working slug.
 
-**Cache invalidation**: on first 400/404 walk, the cached entry is dropped. The next-best slug is promoted into the cache only after it succeeds.
+**Cache invalidation**: on a 400/404 walk the refused slug leaves the working slot and goes to the back of that sign-in's line for six hours. The next-best slug is promoted into the cache only after it succeeds.
 
 **All-failed case**: if every slug in the chain rejects with the walk-trigger, the client throws a structured error with `httpStatus: 503` and message `"AI provider unreachable — all configured Codex slugs were rejected"`. The route layer surfaces this to the user with "AI provider unreachable — check Settings".
 
-**Observability**: each attempted slug is recorded in the Wide-Event annotation `codex.slug.attempts: ["gpt-5.3-codex","gpt-5-codex"]` so Loki can answer "which slug carried this request" and "how often did the cache hit". Cache hits emit `codex.slug.cache: "hit" | "miss" | "expired"`.
+**Observability**: a request that builds the chain annotates `codex.models.chain` (`operator` / `live` / `static`), `codex.models.read` (`live` / `cache` / `skipped`), `codex.models.failure` (`timeout`, `network`, `auth`, `http_error`, `too_large`, `unparsable`, `empty`, or null) and `codex.models.offered` (a count). `CodexClient.getLastDiagnostics()` holds the attempted slugs, the cache state and the working slug.
 
-The implementation lives in `src/lib/ai/codex-client.ts`; the contract is unit-tested in `src/lib/ai/__tests__/codex-client.test.ts`.
+The walk lives in `src/lib/ai/codex-client.ts`, the order in `src/lib/ai/codex-slug-chain.ts`, the list read in `src/lib/ai/codex-model-catalog.ts`, the per-sign-in memory in `src/lib/ai/codex-slug-cache.ts`; the contract is unit-tested in `src/lib/ai/__tests__/codex-live-models.test.ts`, `codex-slug-chain.test.ts`, `codex-model-catalog.test.ts` and `codex-slug-fallback.test.ts`.
 
 ---
 
@@ -773,7 +795,10 @@ All paths relative to `openai/codex` repo:
 - `codex-rs/codex-api/src/rate_limits.rs` — rate-limit headers
 - `codex-rs/codex-api/src/auth.rs` — `AuthProvider` trait
 - `codex-rs/protocol/src/models.rs` — `ResponseItem`, `ContentItem`, `MessagePhase`, `ImageDetail`, etc.
-- `codex-rs/protocol/src/openai_models.rs` — `ReasoningEffort` enum
+- `codex-rs/protocol/src/openai_models.rs` — `ReasoningEffort` enum; `ModelsResponse`, `ModelInfo`, `ModelVisibility`, `InputModality`, `ModelPreset::filter_by_auth` (the `/models` wire)
+- `codex-rs/codex-api/src/endpoint/models.rs` — `ModelsClient`: `GET models?client_version=…`
+- `codex-rs/model-provider/src/models_endpoint.rs` — the 5 s model-list bound; `models_identity.rs` — the per-account cache identity
+- `codex-rs/models-manager/src/manager.rs` — priority sort, picker visibility, cache TTL
 - `codex-rs/protocol/src/config_types.rs` — `ReasoningSummary`, `Verbosity` enums
 - `codex-rs/model-provider/src/bearer_auth_provider.rs` — `Authorization` + `ChatGPT-Account-ID` headers
 - `codex-rs/model-provider/src/auth.rs` — auth-provider selection

docs/contributing/benchmarks.md

@@ -0,0 +1,119 @@
+# Benchmarks
+
+Two tools measure the server's read and write paths. Use them before and after any change to a hot path, and put both numbers in the PR.
+
+- **`scripts/bench/run.ts`** measures latency (p50, p95, max) and SQL statements per request against a seeded account of about 1.26 million measurement rows, through the production build. It is a local tool, not a CI gate: latency depends on the machine.
+- **`tests/integration/query-budget-hot-routes.test.ts`** holds a statement budget per hot route on a small fixture. Statement counts are exact on a fixed fixture, so this one is a gate: a change that adds a query per row, or a second read of something already loaded, fails it.
+
+## The large-account benchmark
+
+### 1. A throwaway Postgres with pg_stat_statements
+
+Never point the seed or the benchmark at a database that holds real data. They write under a synthetic user, and the seed's `--reset` deletes that user with everything it owns.
+
+```sh
+docker run -d --name hl-bench-db --shm-size=256m \
+  -e POSTGRES_USER=bench -e POSTGRES_PASSWORD=bench -e POSTGRES_DB=healthlog_bench \
+  -p 55432:5432 postgres:18.6-alpine \
+  postgres -c shared_preload_libraries=pg_stat_statements -c pg_stat_statements.track=top
+```
+
+The image and the two settings are the ones `docker-compose.yml` runs in production.
+
+### 2. Environment, migrations, seed
+
+```sh
+export DATABASE_URL="postgresql://bench:bench@127.0.0.1:55432/healthlog_bench?schema=public"
+export ENCRYPTION_KEYS='{"v1":"<64 hex>"}' ENCRYPTION_ACTIVE_KEY_ID=v1
+export API_TOKEN_HMAC_KEY="<64 hex>"
+
+pnpm db:migrate:deploy
+pnpm dlx tsx scripts/bench/seed-large-account.ts --reset --anchor 2026-10-22
+```
+
+Any throwaway key values work, as long as the seed, the benchmark and the server see the same ones.
+
+The seed writes ten years for one user: Apple Health dense rows (heart rate about every ten minutes, HRV, SpO2, respiratory rate, gait, audio), Withings blood pressure, pulse and scale, a weekly manual weight, three years of Oura resting heart rate and RMSSD, 90 days of Nightscout CGM, `stats:` and per-sample cumulative rows, nightly sleep stages, about 3,000 workouts, three years of mood and of three medications with their intake events. It then folds the rollup tier the way the boot backfill does and runs `ANALYZE`. It takes about 80 seconds on the Mac mini.
+
+The seed is deterministic for a given `--anchor`: values and timestamps are functions of the row index and that day. Without `--anchor` it anchors on today, which is what you want when the benchmark should see recent data.
+
+### 3. A production build
+
+```sh
+pnpm build
+```
+
+### 4. Run
+
+```sh
+pnpm dlx tsx scripts/bench/run.ts --out scripts/bench/results/<label>
+```
+
+The script boots the build once with every role, so the worker creates its queues as it does in production, drops whatever that boot scheduled, and then runs the measurement against a web-only process (`HEALTHLOG_PROCESS_TYPE=web`) under the production heap ceiling (`--max-old-space-size=792`, the value Node derives in the 1.5 GB production container). Without the worker, its polling does not land in every statement count. It prints the server's idle statement rate so the remaining background is visible.
+
+For each route it sends three warm-up requests, then twenty measured ones in each of two modes, one request at a time:
+
+- **cold**: before every request a one-row ingest marked as a manual sync evicts the user's caches, so the request rebuilds what it serves. This is a reader's first look after a sync.
+- **warm**: back to back, what a cache hit costs.
+
+The batch ingest posts 5,000 fresh heart-rate rows as ten requests of 500, the route's per-request limit, and removes them again at the end.
+
+Statements are the change in `sum(calls)` of `pg_stat_statements` over the database, read before and after each request, once no statement is in flight and the counter holds still. Fire-and-forget writes a request starts are therefore counted with it.
+
+Options: `--iterations`, `--warmup`, `--user`, `--heap-mb`, `--port`, and `--base-url` to measure a server you started yourself.
+
+The output is `<label>.json` (every number, plus the commit, Node and Postgres versions and the row count) and `<label>.md` (the table). Commit the pair when a change is meant to move a number, so the PR shows before and after.
+
+### Reading the numbers
+
+Run on a quiet machine; a parallel build or test run moves latency by tens of percent and leaves the statement counts alone. Compare statement counts across machines, latency only across runs on the same machine. A local number is only valid under the production heap ceiling, which the script sets.
+
+## Boot and idle-memory profile
+
+`scripts/bench/boot-profile.ts` profiles a production start the way production runs it: `next start` on the build, every role (web and worker), the production heap ceiling (`--max-old-space-size=792`, the heap Node derives in the 1.5 GB container), against the seeded benchmark database.
+
+```sh
+pnpm dlx tsx scripts/bench/boot-profile.ts --idle-seconds 300 --out scripts/bench/results/<label>-boot
+```
+
+It records:
+
+- the time to the first answer from `/api/health` and to the worker's `startup` line;
+- every `event_loop_stall` the process logs, with the uptime, startup phase, boot step and work in flight it names;
+- every `runtime.heap.sampled` line, and every full collection from `--trace-gc` (used heap before, live heap after);
+- a CPU profile of the start: the main thread's busy stretches over 50 ms without an idle sample, each with its self time per source module, resolved through the chunk source maps (`profile-analyze.ts`);
+- one heap snapshot after the idle wait, taken with `--heapsnapshot-signal` (after a full collection, so it is the live heap), summarised by node type, constructor, largest strings and the largest retained subtrees with a retaining path, and the number of parsed locale catalogs.
+
+The worker runs for the whole idle wait, and its boot passes fold and consolidate the seeded account (old dense readings into their `stats:` rows), roughly halving its row count. Reseed before the next request benchmark, or its numbers describe a different account.
+
+The raw `.cpuprofile` and `.heapsnapshot` go to a temporary directory and are deleted after the summary unless `--keep` is given. Only run it against the benchmark database: a snapshot holds whatever the process decrypted. `--no-snapshot` and `--no-cpu-prof` skip either part. The profiler itself costs memory, so read RSS from this run as an upper bound.
+
+### What the profile found (v1.44 runtime, October 2026)
+
+On the seeded account, idle, with the worker running and no requests (`results/v1.45.0-before-boot.md`):
+
+- **The boot stall is module evaluation.** The longest busy stretch of the main thread was 753 ms, 0.7 s into the start: the instrumentation hook importing the worker, whose five registrars pulled practically all of `src/lib` into one synchronous evaluation (`register-maintenance.ts` alone 280 ms inclusive), followed by the first `/api/health` request compiling its route. The event-loop monitor started after the key and time-zone checks, and a 250 ms tick measures a block by how late the next tick fires, so it reported less than the block or nothing. The beta's 718 ms and 671 ms stalls are this block on a slower machine.
+- **The live heap is about 165 MB, not 400.** Full collections brought the heap back to 162 to 172 MB every 15 to 20 s while idle; the used heap between them reached 190 MB. What a heap line shows above the live heap is garbage awaiting the next full collection, plus, on a server with users, the server caches (13 caches of up to 2,000 entries with stale windows of up to an hour). The beta's 400 MB plateau is therefore not a baseline the process cannot shed; it is what the heap grows to under a large limit before a collection, plus caches.
+- **What the live heap holds.** Of 172 MB: the query compiler about 50 MB (the engine object 34 MB, its WebAssembly base64 source twice at 4.4 MB, its chunk source twice at 5.6 MB); the locale catalogs about 33 MB (32 parsed catalog objects, eight locales in each of four server bundles, 14 MB, plus the eight-locale chunk source twice at 9.7 MB); module source strings over 50 KB about 44 MB in total (the catalog chunks included); compiled code 19 MB.
+
+### What changed (v1.45.0)
+
+- The event-loop monitor starts first in `register()`, and a stall line names the boot step, startup phase and work in flight (`src/lib/boot/boot-steps.ts`, one `boot.steps` line per boot with each step's duration).
+- The worker's registrars are imported one at a time after `boss.start()`, with a turn of the event loop between them.
+- The server reads a locale catalog from `messages/<locale>.json` on first use and keeps one parsed copy per process (`src/lib/i18n/server-catalogs.ts`); the seven matchers that index every locale build their index on first use.
+
+Result on the same machine (`results/v1.45.0-boot.md`): the worker graph loads in stretches of at most 246 ms instead of one of 753 ms (the longest application stretch left is the query compiler's start, 336 ms, unchanged); the live heap after five idle minutes went from 162 to 172 MB to 142 to 153 MB; two parsed catalogs (1.6 MB) instead of 32 (14.1 MB), and no catalog chunk sources.
+
+## Statement budgets in the integration suite
+
+`tests/integration/query-budget-hot-routes.test.ts` seeds a small account (four months of the main types with overlapping sources, sleep, glucose, a medication, workouts and mood), and counts the statements of one request per hot route on a cache miss: `/api/auth/me`, the dashboard summary and snapshot, the pulse series over 30, 365 and 3650 days, the day view, insights health status, correlations, and a 500-row batch ingest.
+
+The counter (`tests/integration/query-counter.ts`) wraps `pg`'s `Client.prototype.query` on the copy of `pg` the Prisma adapter loads, and settles background tasks before it closes the window.
+
+Each budget is the measured count. When a change lowers one, lower the budget in the same change. When a change has to raise one, raise it with the reason in the PR. A failure prints every statement the request sent, grouped by text, so an added loop shows up as one statement with a count next to it.
+
+Run it like any integration file:
+
+```sh
+pnpm test:integration tests/integration/query-budget-hot-routes.test.ts
+```

docs/contributing/testing.md

@@ -0,0 +1,297 @@
+# Testing
+
+How the suites are organised, which one a new test belongs in, and the tools
+that keep them fast and honest. Commands are in `CONTRIBUTING.md`; this page
+is about choosing and writing tests.
+
+## Which suite
+
+| What you are testing                                                                                                                    | Where                                       | Runs with               |
+| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ----------------------- |
+| Pure logic: statistics, time zones, cadence, parsers, unit conversion, formatting                                                       | `src/**/__tests__/*.test.ts` (unit)         | `pnpm test`             |
+| Laws of that logic over random inputs                                                                                                   | `*.property.test.ts` next to the unit tests | `pnpm test`             |
+| What a component renders for a given state                                                                                              | `src/**/__tests__/*.test.tsx` (unit)        | `pnpm test`             |
+| How a component behaves when someone types, clicks or presses keys, and what it sends                                                   | `src/**/__tests__/*.browser.test.tsx`       | `pnpm test`             |
+| A structural rule about the tree (a guard)                                                                                              | `src/__tests__/` with a stated floor        | `pnpm test`             |
+| A route: auth, scope, validation, what it stores and what it answers                                                                    | `tests/integration/routes/` with the kit    | `pnpm test:integration` |
+| Anything whose truth lives in Postgres: constraints, `where` semantics, transactions, locks, cascades, time zones in SQL, backups, jobs | `tests/integration/`                        | `pnpm test:integration` |
+| A journey through the real UI                                                                                                           | `e2e/`                                      | `pnpm e2e`              |
+
+The rule behind the table: put a behavioural test at the level where the
+risky collaborator is real. For a route that collaborator is Postgres and the
+API kit (`apiHandler`, `requireAuth`, the envelope), so a route test runs
+against both. A unit test that replaces Prisma with a mock and then asserts on
+the calls it received checks the query text, not the behaviour; it passes when
+the query is wrong and fails when it is rewritten correctly. Do not write new
+ones: `src/__tests__/test-realism-ratchet.test.ts` counts route tests that mock
+`@/lib/db` wholesale or stub `apiHandler`, and `as never` casts in tests, and
+those numbers may only fall. Mock at the process boundary you do not own instead: provider HTTP
+(`safeFetch`), APNs, SMTP, the model.
+
+## Critical journeys
+
+A few e2e journeys carry `@critical` in their test titles: signing in with a
+password and a passkey and signing out, a reading reaching the dashboard, a
+dose moving compliance, a mood entry, a lab CSV import, a questionnaire in
+German and Brazilian Portuguese, a setting that persists, a backup coming
+back, sharing a record, and the offline page. `pnpm e2e:critical` runs them.
+
+They run against the real server and a seeded Postgres. A spec file that
+carries the tag may not intercept anything under `/api`, directly or through
+a helper it imports; `src/__tests__/e2e-critical-no-api-stub-guard.test.ts`
+refuses it and keeps a floor on the number of tagged tests. Stubbing an
+unreachable third-party host that is not the journey's subject is allowed,
+with the reason next to the call.
+
+A journey that writes gets an account nobody else writes. The accounts in
+`e2e/setup/critical-fixture.ts` are seeded by global setup, one per journey
+and per Chromium project, so a journey runs at both widths without the two
+projects meeting. Reset what a previous run left with `resetCriticalAccount`
+in a `beforeEach`, and read results through the app's own routes rather than
+through the database.
+
+## The route test kit
+
+`tests/kit/` holds two modules for tests under `tests/integration/`.
+
+`factories.ts` writes typed fixtures through the application's Prisma client
+and returns the stored rows: `makeUser`, `makeAdmin`, `makeSession`,
+`makeToken`, `makeMeasurement`, `makeMedication`, `makeWorkout`, `makeGrant`.
+Overrides are the Prisma create input of that model, so the compiler checks
+every fixture field; there is no reason for `as never` in a kit test.
+Sessions and tokens are minted by the server's own `createSession` and
+`issueApiToken`, so a fixture cannot drift into a shape authentication no
+longer accepts.
+
+`call-route.ts` exports `callRoute(handler, options)`, which builds a real
+`NextRequest`, fills the `next/headers` stand-in from `auth`, calls the
+exported handler of a `route.ts` (and with it the real `apiHandler`), and
+returns `{ status, data, error, meta, body, headers }`.
+
+```ts
+import { GET } from "@/app/api/tokens/route";
+import { DELETE } from "@/app/api/tokens/[id]/route";
+
+import { callRoute } from "../../kit/call-route";
+import { makeSession, makeToken, makeUser } from "../../kit/factories";
+import { getPrismaClient, truncateAllTables } from "../setup";
+
+beforeEach(() => truncateAllTables(getPrismaClient()));
+
+it("revokes the caller's token and the token stops authenticating", async () => {
+  const owner = await makeUser();
+  const phone = await makeToken(owner);
+
+  const res = await callRoute<{ revoked: boolean }>(DELETE, {
+    method: "DELETE",
+    route: "/api/tokens/{id}",
+    params: { id: phone.tokenId },
+    auth: await makeSession(owner),
+  });
+
+  expect(res.status).toBe(200);
+  const row = await getPrismaClient().apiToken.findUniqueOrThrow({
+    where: { id: phone.tokenId },
+  });
+  expect(row.revoked).toBe(true);
+
+  const after = await callRoute(GET, {
+    method: "GET",
+    route: "/api/tokens",
+    auth: phone,
+  });
+  expect(after.status).toBe(401);
+});
+```
+
+`auth` is a `SessionFixture`, a `BearerFixture`, or `anonymous`. `route` is
+the path as the OpenAPI registry names it, with `{…}` segments filled from
+`params`.
+
+Every call is also a contract check. The status must be one the registry
+(`src/lib/openapi/routes/`) declares for that path and method, a JSON body
+must parse with the registered schema, and a key the schema does not declare
+fails the call: a client generated from the contract cannot see that field, so
+nobody promised to keep it. There is no generic answer the kit accepts on an
+operation's behalf: the scope gate's 403 `auth.scope.insufficient` is declared
+on every operation that passes the gate (`withScopeRefusal` in
+`src/lib/openapi/routes/shared.ts`), so it is checked like any other status. A
+test that calls an unregistered route on purpose passes
+`contract: { skip: "<reason>" }`.
+`tests/integration/routes/kit-contract.test.ts` proves the check can fail.
+
+Assert what a person or a client would notice: the stored row, the response,
+the next request's answer. Not the calls a mock received.
+
+The kit runs the handler, not the edge. Security headers, the public-path
+allowlist and demo mode live in `src/proxy.ts` and are tested there.
+
+### The settings round trip
+
+`tests/integration/settings-round-trip.test.ts` holds one table with an entry
+for every `User` column the backup classifies as `SETTING`
+(`USER_COLUMN_BACKUP_CLASS` in `src/lib/export/backup-plan.ts`). For each one
+it sets a non-default value through the API, reads it back through the API and
+through `/api/auth/me` where that publishes it, exports a backup, restores it
+into a fresh account and reads it back there. A new setting column without a
+table entry fails the file. A column with no write route says why in its
+entry.
+
+## Browser tests
+
+Interaction belongs in the `browser` project: `*.browser.test.tsx` files run
+in headless Chromium through Vitest's Playwright provider, as part of
+`pnpm test`. Run them alone with `pnpm test --project browser`, or one file
+with `pnpm exec vitest run --project browser <path>`. The Node projects never
+collect these files and this project collects nothing else. CI installs the
+browser it needs (`playwright install --only-shell chromium`); locally, run
+that once.
+
+Reach for it when the claim is about behaviour a markup test cannot see:
+focus, keys, an open menu, a pending state, the body a form posts, the URL a
+filter writes. A `renderToStaticMarkup` grep stays the tool for what a given
+state renders, and bottom-sheet gestures stay in `e2e/`.
+
+The helper is `tests/browser/`:
+
+- `renderWithApp(ui, { locale, user })` mounts the app's own providers: a real
+  TanStack `QueryClient` (no retries) and `I18nProvider` with the real
+  catalog. The signed-in account is seeded where `useAuth` reads it, with
+  `authUser()` defaults under `user`. The app stylesheet and the default
+  theme class are loaded, so layout, visibility and colour tokens resolve.
+- `stubFetch()` replaces `fetch` and nothing above it. Answer a route with
+  `.on(method, path, { status, data, error, meta })`, hold one with
+  `.deferred(...)` to assert a pending state, and read the parsed bodies from
+  `.calls(method, path)`. An unmatched request gets a 404 envelope and is
+  recorded. Do not mock `@tanstack/react-query` or `@/lib/api/api-fetch`.
+- `next/navigation` is aliased to a shim over the page's real `location` and
+  `history`; `url.ts` sets the starting query, records pushes and replaces,
+  and simulates Back or an edited address.
+- `pinDate(iso)` fakes `Date` only, so timers and animation frames still run.
+
+Every test gets the real `fetch`, clock, address and an empty `localStorage`
+back afterwards. Locate by role and accessible name, the way a person finds a
+control; a `Label` adds a colon to its name, so match a labelled combobox with
+`/^Type/` rather than `"Type"`.
+
+## The integration database
+
+Global setup boots one Postgres container and migrates one template database.
+Each Vitest worker clones it on its first file (`CREATE DATABASE … TEMPLATE`,
+see `tests/integration/worker-database.ts`), so files run in parallel without
+seeing each other's rows, advisory locks or queue schema. The worker count
+follows the host (half the cores, at most eight) unless
+`HEALTHLOG_INTEGRATION_WORKERS` pins it; CI uses three. To reproduce a CI runner's
+contention on a larger machine, cap the database container with
+`HEALTHLOG_INTEGRATION_PG_CPUS=2`.
+
+`truncateAllTables` empties every table the migrations created and puts back
+the rows they seed (the mood-tag and symptom catalogues), so a test starts
+from what a fresh install holds. The list is the catalogue, read from the
+template, not something to maintain. `START_EMPTY_TABLES` names the one
+seeded table a test starts without, and why. Schemas created at runtime
+(pg-boss) are dropped when the next file starts in the worker.
+
+`next/headers` and the boot compatibility probe are mocked for every file in
+`environment-setup.ts`. A file needs its own `vi.mock("next/headers")` only
+when it wants different behaviour.
+
+## Speed and sharding
+
+CI splits both suites by measured duration, not by file count: the sequencer
+in `tests/durations/sequencer.ts` reads `tests/durations/unit.json` and
+`tests/durations/integration.json` and deals files out longest first to the
+shard with the least work. A file without a measurement counts as the median.
+Regenerate a timing file from Vitest JSON reports when the shards drift apart:
+
+```sh
+pnpm exec vitest run --reporter=default --reporter=json --outputFile.json=unit.json
+node scripts/test-durations.mjs unit unit.json
+```
+
+The nightly workflow (`.github/workflows/test-nightly.yml`) uploads a file
+regenerated from CI timings, which is the better source.
+
+The unit suite is three Node projects and the `browser` project above. The
+Node ones are decided per file from its source
+(`tests/unit-projects.ts`): `guards` and `unit` share a module graph within a
+worker, `isolated` gives each file a fresh one. A file lands in `isolated` when
+it mocks, spies, stubs env or globals, fakes timers or resets modules. If a
+file needs isolation for a reason the classifier cannot see, put a
+`// vitest-isolate` comment in it.
+
+## Property tests
+
+`fast-check` properties live in `*.property.test.ts` files and take their
+parameters from `tests/property/fast-check.ts`. Pull requests run every
+property with a fixed seed, so a run is reproducible on any machine. The
+nightly run uses a fresh `FC_SEED` and multiplies every property's own case
+count by `FC_RUNS_FACTOR`; a failure prints the seed and the shrunk
+counterexample, and `FC_SEED=<seed> pnpm test <file>` replays it. A property
+whose cases are expensive states a small count and passes
+`propertyTimeout(baseMs)` as its test timeout, which grows by the same factor.
+
+Write a property when the code has a law: an inverse (encrypt and decrypt, a
+unit and its inverse, a wall clock and its instant), an invariant (a rate
+between 0 and 100, a day that contains its own instants), or an oracle small
+enough to be obviously right (a day-by-day walk of a weekly schedule). Do not
+reimplement the function under test in the property.
+
+## Mutation testing
+
+Stryker runs on the core libraries (`stryker.config.mjs`) nightly and on
+demand (`.github/workflows/mutation.yml`), not on pull requests. Each module's
+score is checked against a floor in `stryker.floors.json` by
+`node scripts/mutation-floors.mjs`. A floor sits just below the last measured
+score; raise it when a change raises the score, never lower it to make a run
+pass. The Vitest runner is patched for Vitest 5's test names
+(`patches/@stryker-mutator__vitest-runner@10.0.0.patch`); without it every
+test inside a `describe` block is filtered out of the mutant runs and almost
+every mutant survives. Locally:
+
+```sh
+pnpm exec stryker run
+node scripts/mutation-floors.mjs
+```
+
+## Flaky tests
+
+Vitest runs without retries, and stays that way: a retry that turns red into
+green hides the flake it was meant to report. e2e keeps two retries with
+`failOnFlakyTests`, so a test that needed one still fails the run.
+
+A flaky unit or integration test may be taken out of the run only through
+`tests/quarantine/quarantine.json`:
+
+```json
+{
+  "file": "tests/integration/example.test.ts",
+  "test": "outer describe > the test name",
+  "issue": "#1234",
+  "reason": "fails about one run in twenty when the queue worker is slow",
+  "added": "2026-10-22",
+  "expires": "2026-11-05"
+}
+```
+
+The test is reported as skipped with its issue while the entry is live. An
+entry expires at most 14 days after it was added; after its expiry date the
+test runs again, and `tests/quarantine/quarantine-guard.test.ts` fails until
+the entry is removed. The guard also fails on an entry that names a file or a
+test that does not exist. Fix the flake, or delete the test if it no longer
+earns its place; do not extend the date.
+
+Order dependence is looked for on purpose: the nightly workflow runs both
+suites with `--sequence.shuffle` and prints the seed. Replay a failure with
+`--sequence.shuffle --sequence.seed=<seed>`.
+
+A case resets or states what it reads: `vi.resetAllMocks()` (or
+`mockReset()`) where a case swaps in its own implementation, since
+`clearAllMocks` keeps it and a `mockResolvedValueOnce` the code never consumed
+answers the next case; a module cache dropped through its own invalidator; a
+row the case needs written by the case or its own `beforeAll`. A file that is
+one walk by design (a parity sequence, a migration's before and after, a
+dry run followed by the import and the same file again) says so in a comment
+and passes `{ shuffle: false }` to its `describe`, which keeps that block in
+order while the rest of the suite still shuffles. Wrap the whole file in one
+such block when its top-level blocks build on each other.

docs/contributing/ui-standards.md

@@ -0,0 +1,187 @@
+# 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, `pb-24` in the desktop shell, + the phone shell's bottom-nav clearance on `<main>`). The shell itself takes the window's edges (`absolute inset-0`), never `h-dvh`, and `<main>` is the one vertical scroller: the document neither scrolls nor bounces under it. 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` (`MAIN_CONTENT_WRAPPER_CLASS` in `layout/shell-metrics.ts`): `mx-auto max-w-screen-xl px-4 pt-6 pb-20 md:px-6 shell-desktop:pb-24`. 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-single-implementation.test.ts` 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)]`), or the home indicator in the desktop shell, and its wrapper clears the Coach FAB (`pb-20`, `pb-24` in the desktop shell). **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.
+
+The rail's destination list is the one part of the rail that gives up height: the logo band, the footer group and the account row stay pinned, and the list scrolls between them (`overscroll-contain`, no native scrollbar, fades at an edge with more). A mouse gets the height-stepped row density; a finger keeps the 44 px rows, and at an edge with more destinations the rail shows a scroll cue (`sidebar-nav-scroll-cue`) that a tap follows. Guard: `e2e/tablet-shell.spec.ts`.
+
+## 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/diagrams/01-data-flow.svg

@@ -81,7 +81,7 @@
     <text x="600" y="360" text-anchor="middle" fill="#6272a4" font-size="11">pre-aggregated buckets</text>
 
     <rect x="510" y="392" width="180" height="56" rx="10" fill="#44475a" stroke="#ff79c6" stroke-width="1.5" />
-    <text x="600" y="417" text-anchor="middle" font-weight="600">PostgreSQL 16</text>
+    <text x="600" y="417" text-anchor="middle" font-weight="600">PostgreSQL 18</text>
     <text x="600" y="435" text-anchor="middle" fill="#bd93f9" font-size="11">encrypted at rest</text>
   </g>
 

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

@@ -1,6 +1,6 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 620" font-family="ui-sans-serif, -apple-system, Segoe UI, Roboto, sans-serif" role="img" aria-labelledby="title desc">
   <title id="title">HealthLog self-hosting topology</title>
-  <desc id="desc">Internet traffic terminates at a reverse proxy (Caddy, Traefik or Nginx) for TLS, then reaches the Next.js app on port 3000. The app shares a Postgres 16 database with the pg-boss worker process for reminders, insights, backups and the Apple Health import. GHCR ships the multi-arch image; Coolify watches the digest and pulls; off-host S3-compatible storage is optional for backups.</desc>
+  <desc id="desc">Internet traffic terminates at a reverse proxy (Caddy, Traefik or Nginx) for TLS, then reaches the Next.js app on port 3000. The app shares a Postgres 18 database with the pg-boss worker process for reminders, insights, backups and the Apple Health import. GHCR ships the multi-arch image; Coolify watches the digest and pulls; off-host S3-compatible storage is optional for backups.</desc>
 
   <rect x="0" y="0" width="1200" height="620" fill="#282a36" />
 
@@ -47,7 +47,7 @@
   <!-- Postgres (green) -->
   <g>
     <rect x="760" y="250" width="200" height="80" rx="10" fill="#44475a" stroke="#50fa7b" stroke-width="1.5" />
-    <text x="860" y="276" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">PostgreSQL 16</text>
+    <text x="860" y="276" text-anchor="middle" fill="#f8f8f2" font-size="14" font-weight="600">PostgreSQL 18</text>
     <text x="860" y="296" text-anchor="middle" fill="#bd93f9" font-size="11">26 Prisma models</text>
     <text x="860" y="312" text-anchor="middle" fill="#6272a4" font-size="11">+ pg-boss queues</text>
   </g>

docs/diagrams/README.md

@@ -10,7 +10,7 @@ copy.
 | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `01-data-flow.svg`             | Sources (Withings, Apple Health export.zip, iPhone HealthKit, manual, Nightscout) → ingest endpoints → Measurement + MeasurementRollup → reads (rollup probe / live SQL fallback / cache) → surfaces (dashboard, insights, Coach, doctor PDF).        |
 | `02-coach-pipeline.svg`        | User question → snapshot builder → prompt assembler → provider chain (ChatGPT OAuth / OpenAI / Anthropic / local / admin-shared) → response parser → cited reply with mini-charts.                                                                    |
-| `03-self-hosting-topology.svg` | Internet → reverse proxy (TLS) → Next.js app (port 3000) ↔ pg-boss worker ↔ Postgres 16, plus GHCR image pull, optional Coolify autodeploy, optional S3 off-host backup.                                                                              |
+| `03-self-hosting-topology.svg` | Internet → reverse proxy (TLS) → Next.js app (port 3000) ↔ pg-boss worker ↔ Postgres 18, plus GHCR image pull, optional Coolify autodeploy, optional S3 off-host backup.                                                                              |
 | `04-source-priority.svg`       | Three sources for the same metric on the same day → resolver picks one canonical row per (cumulative vs point) ladder. Losing rows stay in the audit trail.                                                                                           |
 | `05-security-model.svg`        | Three concentric layers — auth perimeter (passkey + password fallback), session perimeter (HttpOnly cookie + Postgres sessions), encrypted core (AES-256-GCM versioned keys). Side rails: rate limiter, audit log, HMAC tokens, CSP/HSTS, SSRF guard. |
 

docs/integrations/ai-providers.md

@@ -216,6 +216,18 @@ JSON surfaces send the standard
 the field is detected on the first refusal and retried without it,
 so strict gateways and older local servers both work unmodified.
 
+**Azure OpenAI.** Point the gateway at the resource's v1 endpoint,
+`https://<resource>.openai.azure.com/openai/v1`, and put the
+deployment name in Model. A reasoning model (gpt-5 on, the o-series)
+takes `max_completion_tokens` and no `temperature`, the same as on
+`api.openai.com`. HealthLog sends that from the first request when the
+deployment is named after its model (`gpt-6-luna-eu`). A deployment
+with a name of its own (`prod-chat`) gets the usual `max_tokens`
+once; Azure refuses it, and the request goes out again with
+`max_completion_tokens`. HealthLog remembers that for the endpoint and
+deployment until the container restarts. Any other gateway that
+refuses `max_tokens` the same way is handled the same way.
+
 **When the gateway refuses.** OpenRouter answers a refused generation
 with HTTP 200 and the reason inside the body, so every refusal used to
 reach the provider health card as an empty reply with no status. It now
@@ -431,6 +443,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,7 +292,10 @@ Concrete consequences:
   source tag — the lowest rank — is reserved for legacy CSV/JSON
   imports that pre-date the Apple Health passthrough.
 
-Override per-user via Settings → Sources (`/settings/sources`).
+RMSSD HRV has its own ladder, **WHOOP ≻ OURA ≻ POLAR ≻ APPLE_HEALTH**,
+separate from the SDNN one.
+
+Override per-user via Settings → Source priority (`/settings/sources`).
 
 ## Failure modes
 
@@ -303,7 +314,7 @@ id for debugging.
 
 ## Garmin owners
 
-Garmin has no direct connector for a self-hosted instance. Garmin Connect writes
-to Apple Health automatically, so the import path on this page is how Garmin data
-reaches HealthLog on iOS. See [garmin.md](./garmin.md) for what comes through and
-what Garmin withholds.
+Garmin Connect writes to Apple Health automatically, so the import path on this
+page brings Garmin data in on iOS. The direct [Garmin](./garmin.md) integration
+reads more (Body Battery, stress, Garmin's sleep score) with a key from your
+own Garmin account.

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/data-import.md

@@ -57,23 +57,50 @@ arrays:
 }
 ```
 
-Each array holds at most **10 000** entries. The endpoint is rate-limited
-to **5 imports per hour per account**. Existing rows (matched on the
-type + timestamp uniqueness, or on `externalId` for mood entries) are
-skipped and counted under `skipped` in the response.
+Each array holds at most **10 000** entries and the file at most 16 MB.
+The endpoint is rate-limited to **5 imports per hour per account**.
+Existing rows (matched on the type + timestamp uniqueness, or on
+`externalId` for mood entries) are skipped and counted under `skipped` in
+the response.
+
+The app's own files go straight in: the JSON export (**Export → JSON**,
+read inside its `data` envelope) and the portable full backup. Every field
+either file writes for a reading or a mood entry comes back, apart from
+the row ids, the source (every imported row is stored as `IMPORT`) and the
+sync bookkeeping of the account the file came from. An empty field, `null`
+in the backup and `""` in the export, reads as absent, a backup's deletion
+records are skipped and counted, and a reading in a display unit (lb, °F,
+mmol/L) is converted to the stored one.
+
+A mood entry's tags and rated factors are linked by key. A full backup
+also carries the account's own tags, rated factors and tag groups, and the
+import brings them along: a tag the importing account already has is used
+as it is, and one it lacks is created (within the account's limit of 50
+custom tags and 12 groups). The account's own tag is never overwritten: when
+the file names it differently, the account's name stays and the response
+lists the key in `keptMoodTagKeys` (`keptMoodCategoryKeys` for a group).
+Moving a file between two accounts of one server works too; the tags come
+over under keys of their own. A key the account cannot resolve at all is
+dropped from that entry and named in `droppedTagKeys` or
+`droppedFactorKeys`, and the rest of the entry lands.
 
 ### Measurement entry
 
-| Field            | Required | Type   | Notes                                                                                                                                                           |
-| ---------------- | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `type`           | yes      | enum   | One of the `MeasurementType` values in the table below.                                                                                                         |
-| `value`          | yes      | number | Plausibility-checked per type; out-of-range values are rejected.                                                                                                |
-| `unit`           | yes      | string | The canonical unit for the type (see the table).                                                                                                                |
-| `measuredAt`     | yes      | string | ISO-8601 datetime, e.g. `2026-05-01T08:00:00.000Z`.                                                                                                             |
-| `source`         | no       | string | Free-text origin label. Imported rows are tagged `IMPORT` server-side regardless.                                                                               |
-| `notes`          | no       | string | Optional free text.                                                                                                                                             |
-| `glucoseContext` | no       | enum   | Only for `BLOOD_GLUCOSE`. See [Glucose context](#glucose-context).                                                                                              |
-| `externalId`     | no       | string | A source-stable id (1–120 chars). When present, a re-import upserts on `(user, type, source, externalId)` so an edit upstream is reflected rather than skipped. |
+| Field                  | Required | Type   | Notes                                                                                                                                                           |
+| ---------------------- | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`                 | yes      | enum   | One of the `MeasurementType` values in the table below.                                                                                                         |
+| `value`                | yes      | number | Plausibility-checked per type; out-of-range values are rejected.                                                                                                |
+| `unit`                 | yes      | string | The canonical unit for the type (see the table).                                                                                                                |
+| `measuredAt`           | yes      | string | ISO-8601 datetime, e.g. `2026-05-01T08:00:00.000Z`.                                                                                                             |
+| `source`               | no       | string | Free-text origin label, not stored. Imported rows are tagged `IMPORT` server-side regardless.                                                                   |
+| `notes`                | no       | string | Optional free text.                                                                                                                                             |
+| `glucoseContext`       | no       | enum   | Only for `BLOOD_GLUCOSE`. See [Glucose context](#glucose-context).                                                                                              |
+| `valueMin`             | no       | number | Lower bound of a range reading, such as an hourly heart-rate statistic. Not above `valueMax`.                                                                   |
+| `valueMax`             | no       | number | Upper bound of a range reading.                                                                                                                                 |
+| `sleepStage`           | no       | enum   | A sleep row's stage: `IN_BED`, `ASLEEP`, `AWAKE`, `CORE`, `DEEP` or `REM`.                                                                                      |
+| `rhythmClassification` | no       | enum   | The device's verdict on an ECG, a rhythm alert or a steadiness reading.                                                                                         |
+| `deviceType`           | no       | string | The writer of the reading (watch, phone), 1–32 chars.                                                                                                           |
+| `externalId`           | no       | string | A source-stable id (1–120 chars). When present, a re-import upserts on `(user, type, source, externalId)` so an edit upstream is reflected rather than skipped. |
 
 ### Glucose context
 
@@ -98,14 +125,20 @@ moment you know it.
 
 ### Mood entry
 
-| Field        | Required | Type    | Notes                                                                                                                                                     |
-| ------------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `date`       | yes      | string  | `YYYY-MM-DD`.                                                                                                                                             |
-| `mood`       | yes      | enum    | One of `SUPER_GUT`, `GUT`, `OKAY`, `SCHLECHT`, `LAUSIG`.                                                                                                  |
-| `score`      | yes      | integer | `1`–`5`.                                                                                                                                                  |
-| `tags`       | no       | string  | Comma-separated tags.                                                                                                                                     |
-| `loggedAt`   | no       | string  | ISO-8601 datetime; defaults to the start of the given `date` in the default timezone.                                                                     |
-| `externalId` | no       | string  | A source-stable id (1–120 chars). When present, a re-import upserts on `(user, source, externalId)` so an edit upstream is reflected rather than skipped. |
+| Field            | Required | Type    | Notes                                                                                                                                                     |
+| ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `date`           | yes      | string  | `YYYY-MM-DD`.                                                                                                                                             |
+| `mood`           | yes      | enum    | One of `SUPER_GUT`, `GUT`, `OKAY`, `SCHLECHT`, `LAUSIG`.                                                                                                  |
+| `score`          | yes      | integer | `1`–`5`.                                                                                                                                                  |
+| `tags`           | no       | string  | Comma-separated tags.                                                                                                                                     |
+| `note`           | no       | string  | The entry's note, up to 500 chars.                                                                                                                        |
+| `a1`–`a5`        | no       | integer | The five level-A values, `0`–`10`. Without `a1`, pleasantness is derived from `mood`.                                                                     |
+| `loggedAt`       | no       | string  | ISO-8601 datetime; defaults to the start of the given `date` in the default timezone.                                                                     |
+| `tz`             | no       | string  | The IANA zone `date` is anchored to.                                                                                                                      |
+| `factors`        | no       | array   | Rated factors, `[{ "key": "…", "rating": 1–5 }]`; replace the entry's rated links.                                                                        |
+| `structuredTags` | no       | array   | Ticked tags by key; replace the entry's tag links.                                                                                                        |
+| `context`        | no       | object  | The day context (work, contacts, leisure, an event, a note), as the backup writes it; replaces the entry's context.                                       |
+| `externalId`     | no       | string  | A source-stable id (1–120 chars). When present, a re-import upserts on `(user, source, externalId)` so an edit upstream is reflected rather than skipped. |
 
 ### `MeasurementType` values and canonical units
 
@@ -161,6 +194,7 @@ hand-authored.
 | `WALKING_ASYMMETRY`             | percent (0–100)      |
 | `WALKING_DOUBLE_SUPPORT`        | percent (0–100)      |
 | `ACTIVE_ENERGY_BURNED`          | kcal                 |
+| `BASAL_ENERGY_BURNED`           | kcal                 |
 | `ENERGY_EXPENDITURE_KJ`         | kJ                   |
 | `VO2_MAX`                       | mL/(kg·min)          |
 | `PULSE_WAVE_VELOCITY`           | m/s                  |

docs/integrations/dawarich.md

@@ -0,0 +1,7 @@
+# Dawarich integration
+
+The Dawarich guide lives on the docs site:
+<https://docs.healthlog.dev/guides/connect-dawarich/>. It covers what is read
+and what is never stored, connecting an instance, allowing one on your own
+network (`DAWARICH_PRIVATE_ORIGINS`), where the values show up, and
+disconnecting.

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
 
@@ -93,7 +103,7 @@ The Fitbit client id/secret are per-user (Settings), not env vars.
 
 If Fitbit and another source (Withings, WHOOP, Apple Health) both supply the same
 vital — resting heart rate, blood oxygen, body temperature or respiratory rate —
-the source priority ladder in **Settings → Sources** decides which one wins
+the source priority ladder in **Settings → Source priority** decides which one wins
 per metric. FITBIT is ranked in every default metric ladder; override
 per metric on that page.
 

docs/integrations/garmin.md

@@ -1,52 +1,114 @@
-# Garmin (via Apple Health or Google Health Connect)
+# Garmin
 
-**There is no direct Garmin connector for a self-hosted HealthLog instance, and
-there cannot be one.** Garmin's data-sharing program is business-partner-only:
-it is approval-gated, requires a public callback endpoint, and is not the
-"register your own app, paste a key" model the wearable integrations here rely
-on. So instead of a broken half-integration, HealthLog reads Garmin data the
-honest way — through the phone health platform your Garmin already feeds.
+HealthLog reads Garmin Connect directly through Garmin's **Personal API**: you
+create a key for your own account in Garmin Connect, paste it into HealthLog,
+and the server pulls your data every hour. Nothing is pushed by Garmin, and
+nothing is written back.
 
-## The path that works
+The Personal API is for your own data only. Each person on an instance
+creates and pastes their own key; there is no shared app and no operator
+setup.
 
-```
-Garmin device  →  Garmin Connect  →  Apple Health (iOS)  ─┐
-                                   →  Google Health Connect ├─→  HealthLog
-                                      (Android)            ─┘
-```
+## Create a key
 
-- **iOS:** Garmin Connect writes to Apple Health automatically. Import it with
-  the existing [Apple Health](./apple-health.md) path (the `export.zip` upload or
-  the native client's background sync).
-- **Android:** since Garmin Connect 5.14.1 (July 2025) the app writes to **Google
-  Health Connect**. Connect HealthLog through the existing
-  [Google Health](./google-health.md) integration.
+1. Open [Garmin Connect → Settings → Personal API](https://connect.garmin.com/app/settings/personalApiToken).
+2. Create a key and choose how long it stays valid: 30, 90, 180 days or one
+   year.
+3. Copy it right away. Garmin shows the key once.
 
-No extra code, no Garmin developer account, no approval queue — if your Garmin
-already syncs to your phone's health platform, HealthLog already reads it.
+## Connect
+
+Open **Settings → Integrations → Garmin**, paste the key, and pick the same
+validity you chose in Garmin Connect. HealthLog checks the key with Garmin
+before storing anything, so a mistyped or revoked key is refused on the spot.
+The key is stored encrypted at rest and is never shown again, logged or sent
+anywhere but Garmin.
+
+Accounts registered with Garmin's China service work too: pick **Garmin
+Connect China** as the service. The key is only ever sent to the service you
+pick.
+
+After connecting, the last 30 days arrive within a minute and the rest of your
+history follows in the background. The card says "Older history is still
+loading" until it is done.
+
+## Key expiry
+
+Garmin keys expire and cannot be extended. Garmin does not report a key's end
+date through the API, so HealthLog works it out from the validity you picked
+at connect, and replaces that estimate with Garmin's own date once the key is
+in its last day (the short-lived tokens it buys are cut off at the key's end).
+
+From seven days before the end the card says when the key expires. When it
+has expired, or you revoked it in Garmin Connect, syncing stops and the card
+asks for a new key: create one, open **Replace key** in the card's menu and
+paste it. Nothing imported is lost. If you did not pick a validity, the card
+says that it cannot warn ahead; **Key validity** in the card's menu sets it
+afterwards, together with the day you created the key, without pasting the
+key again. A key Garmin turned down is asked about again once a day, so a
+refusal that passes on its own clears without you doing anything.
 
 ## What comes through
 
-Everything Garmin shares with Apple Health / Health Connect flows in: steps,
-heart rate (including beat-to-beat variability), sleep stages (REM / deep /
-light), calories (active and total), distance, weight and body composition,
-cadence, and — partially — blood-oxygen saturation.
+| Garmin data                                                           | HealthLog type             | Unit          |
+| --------------------------------------------------------------------- | -------------------------- | ------------- |
+| Steps                                                                 | `ACTIVITY_STEPS`           | steps         |
+| Step distance                                                         | `WALKING_RUNNING_DISTANCE` | m             |
+| Floors climbed                                                        | `FLIGHTS_CLIMBED`          | flights       |
+| Active calories                                                       | `ACTIVE_ENERGY_BURNED`     | kcal          |
+| Resting heart rate                                                    | `RESTING_HEART_RATE`       | bpm           |
+| All-day average stress level                                          | `STRESS_LEVEL`             | 0–100         |
+| Body Battery (the day's high)                                         | `BODY_BATTERY`             | 0–100         |
+| Sleep stages (light, deep, REM, awake)                                | `SLEEP_DURATION` per stage | minutes       |
+| Sleep score                                                           | `SLEEP_SCORE`              | 0–100         |
+| Average overnight SpO₂                                                | `OXYGEN_SATURATION`        | %             |
+| Average overnight breathing rate                                      | `RESPIRATORY_RATE`         | breaths/min   |
+| Overnight HRV (RMSSD)                                                 | `HRV_RMSSD`                | ms            |
+| Weight, BMI, body fat, body water, muscle and bone mass, visceral fat | the body-composition types | kg, %, rating |
+| Activities                                                            | workouts                   |               |
+| Logged period days                                                    | the cycle tracker          |               |
 
-## What Garmin withholds
+Notes:
 
-These are Garmin's **proprietary** scores. Garmin does **not** share them with
-Apple Health or Health Connect, so no self-hosted integration — and no amount of
-configuration — can obtain them. They are only available inside Garmin Connect
-itself:
+- Garmin's HRV is RMSSD and lands on `HRV_RMSSD`. Garmin reports no SDNN, so
+  nothing is written to `HEART_RATE_VARIABILITY`.
+- Stress and Body Battery are Garmin's own scores and keep types of their own.
+  They are not mixed into HealthLog's computed stress score.
+- Days you did not wear the watch import nothing, not zeros.
+- Period days are only added on days you have not logged yourself; your own
+  entries are never changed. Cycles Garmin only predicts are not imported.
+- Weigh-ins are read back to the start of Garmin Connect, also from before
+  your first watch, so a scale-only account gets its whole history.
+- A night you delete in Garmin Connect, or that Garmin turns into a nap, is
+  removed here on the next sync.
+- Data Garmin does not provide for your account (a menstrual-cycle summary
+  when you track none, for example) is skipped, does not count as an error,
+  and is listed under **Details for a bug report** on the card.
+- When the same data also arrives through Apple Health or Health Connect, the
+  source order in **Settings → Sources** decides which one a chart shows.
+  Garmin ranks with the other watches.
 
-- Body Battery
-- HRV Status
-- VO₂ max
-- Training Load and Training Effect
-- Recovery Time
-- Intensity Minutes
-- Stress score
-- Running dynamics
+## What the Personal API does not carry
 
-If you rely on those specific numbers, keep the Garmin Connect app for them;
-everything else lands in HealthLog through the platform path above.
+Training Readiness, Training Status, acute training load and recovery time
+are not part of the Personal API. If you read them elsewhere, for example
+through a Home Assistant integration, push them through an ingest token: see
+[Home Assistant](./home-assistant.md#garmin-training-figures). They land as
+`TRAINING_READINESS` and `ACUTE_TRAINING_LOAD` and show on the recovery page
+beside Body Battery.
+
+## Limits
+
+- Garmin sets how many requests a key may make. HealthLog reads one resource
+  at a time and stops the hour's run at Garmin's first rate-limit answer; the
+  history backfill waits as long as Garmin asks before it goes on.
+- Disconnecting removes the key from HealthLog. It stays valid at Garmin until
+  you revoke it there.
+
+## Without a key
+
+Garmin Connect also writes to Apple Health on iOS and to Google Health Connect
+on Android, so the [Apple Health](./apple-health.md) and
+[Google Health](./google-health.md) paths keep working for anyone who prefers
+not to create a key. Body Battery, stress and Garmin's sleep score only come
+through the Personal API.

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
@@ -134,7 +305,7 @@ triggers the verification + CASA requirements above.)
 
 If Google Health and another source (Withings, WHOOP, Apple Health) both supply
 the same vital — resting heart rate, blood oxygen, respiratory rate — the source
-priority ladder in **Settings → Sources** decides which one wins
+priority ladder in **Settings → Source priority** decides which one wins
 per metric.
 
 ## Disconnect
@@ -144,7 +315,7 @@ Previously synced measurements stay in the database.
 
 ## Garmin owners
 
-Garmin has no direct connector for a self-hosted instance. Since Garmin Connect
-5.14.1 (July 2025) the app writes to Google Health Connect, so this integration
-is how Garmin data reaches HealthLog on Android. See [garmin.md](./garmin.md) for
-what comes through and what Garmin withholds.
+Since Garmin Connect 5.14.1 (July 2025) the app writes to Google Health Connect,
+so this path brings Garmin data in on Android. The direct [Garmin](./garmin.md)
+integration reads more (Body Battery, stress, Garmin's sleep score) with a key
+from your own Garmin account.

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,121 @@ 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`.
 
+## Garmin training figures
+
+The Garmin Personal API does not carry Training Readiness or the acute
+training load (see [Garmin](./garmin.md)). If Home Assistant reads them, for
+example through a Garmin Connect integration, send them through the same
+ingest token. They have types of their own and appear on the recovery page:
+
+| What the sensor reports    | `type`                | Unit expected |
+| -------------------------- | --------------------- | ------------- |
+| Garmin Training Readiness  | `TRAINING_READINESS`  | score 0–100   |
+| Garmin acute training load | `ACUTE_TRAINING_LOAD` | load, no unit |
+
+Both change about once a day. This automation pushes Training Readiness
+whenever the sensor changes, through the `healthlog_measurement` command
+above; the acute load is the same with its own sensor and type:
+
+```yaml
+automation:
+  - alias: "HealthLog: Garmin training readiness"
+    triggers:
+      - trigger: state
+        entity_id: sensor.garmin_training_readiness
+    conditions:
+      - condition: template
+        value_template: "{{ trigger.to_state.state | is_number }}"
+    actions:
+      - action: rest_command.healthlog_measurement
+        data:
+          type: TRAINING_READINESS
+          value: "{{ trigger.to_state.state | float }}"
+```
+
+## 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
@@ -171,8 +286,9 @@ tells you which rows to retry.
 ## Retries and duplicates
 
 Send an `Idempotency-Key` header with a value your automation can reproduce for
-the same reading. A retry with the same key returns the original response
-instead of writing a second row:
+the same reading. A retry with the same key and the same body returns the
+original response instead of writing a second row. A different body under the
+same key is a different reading and is written:
 
 ```yaml
 headers:

docs/integrations/strava.md

@@ -1,74 +1,6 @@
 # Strava integration
 
-HealthLog reads your Strava activities and folds them into the same workout
-history as every other source. Strava is a **workout source only** — its API is
-activity-centric and exposes no sleep, recovery, body-composition or glucose
-data, so connecting it adds runs, rides, swims and the rest to your workout
-surface and nothing else.
-
-The OAuth app is brought **per user**: each self-hoster registers their own
-Strava API application and pastes the client id/secret into Settings. Strava
-caps every newly-created app at "single-player mode" (an athlete capacity of 1)
-until you request a capacity increase — perfectly fine for a personal
-self-host, and the reason a single shared app cannot serve many operators.
-
-## What you get — and what you don't
-
-**Covered** (one `Workout` row per activity): sport type, start and end time,
-moving duration, distance, elevation gain, average and maximum heart rate (when
-the activity recorded it), and calories. Power, cadence, the "trainer"/"commute"
-flags and the activity name are kept on the row's metadata for provenance but
-are **not** surfaced as training analytics — HealthLog treats Strava as another
-workout source, not a training-load platform.
-
-**Not covered**: Strava exposes no daily metrics (steps, sleep, resting heart
-rate, weight, …). Those come from your wearable's own integration or from Apple
-Health / Google Health Connect.
-
-## Duplicate activities are collapsed automatically
-
-If you record a run on an Apple Watch **and** it also lands in Strava, the same
-run arrives twice — once via Apple Health, once via Strava. HealthLog keeps one
-canonical row per logical workout using your **source-priority ladder**: by
-default the device-native capture (Apple Watch, WHOOP, Withings) wins over the
-Strava copy, because a Strava activity is often a re-upload with lower-fidelity
-or missing heart-rate data. A run you record **only** on Strava (phone GPS)
-survives untouched. You can promote Strava above the wearables in
-**Settings → Sources** if you prefer the Strava copy.
-
-## 1. Register a Strava API application
-
-1. Sign in at <https://www.strava.com/settings/api>.
-2. Create an application. For **Authorization Callback Domain** enter the host
-   of your HealthLog instance (the domain only, no scheme or path).
-3. Copy the **Client ID** and **Client Secret**.
-
-## 2. Paste the credentials into HealthLog
-
-1. Open **Settings → Integrations** and find the **Strava** card.
-2. Paste the Client ID and Client Secret into the **API Credentials** fields and
-   save. (An operator can instead configure a shared app via the
-   `STRAVA_CLIENT_ID` / `STRAVA_CLIENT_SECRET` environment variables; per-user
-   credentials always take precedence.)
-3. Click **Connect Strava** and approve the access request. HealthLog requests
-   the `activity:read_all` scope so it can read every activity, including those
-   you marked "only me".
-
-## 3. First sync
-
-The first history import runs in the background shortly after you connect;
-afterwards an hourly poll pulls new activities. Strava rotates its refresh token
-on every refresh, and HealthLog persists the rotated token each time, so the
-connection stays healthy without you re-authorising.
-
-## Disconnecting
-
-Disconnecting revokes the grant at Strava and clears the stored tokens.
-Activities already imported stay in your history; reconnecting resumes the sync.
-
-## Related
-
-- Wearable that syncs to Strava but not directly to HealthLog? See the device's
-  own page, or ingest via [Apple Health](./apple-health.md) /
-  [Google Health Connect](./google-health.md).
-- **Garmin owners:** Garmin has no direct connector — see [garmin.md](./garmin.md).
+The Strava guide lives on the docs site:
+<https://docs.healthlog.dev/guides/connect-strava/>. It covers what Strava
+adds (workouts only), how duplicate activities from a wearable are collapsed,
+registering the Strava API application, the first sync and disconnecting.

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
@@ -38,7 +88,7 @@ arrive via the sleep series endpoint.
    needed — `user.metrics` covers weight / BP / heart-list / sleep /
    SpO₂ / body comp / temperature / VO₂ max; `user.activity` is the
    workout-equivalent stream for steps / energy / distance / floors.
-   See `WITHINGS_OAUTH_SCOPE` in `src/lib/withings/client.ts`.
+   See `WITHINGS_OAUTH_SCOPE` in `src/lib/withings/oauth.ts`.
 4. Save the application. Withings will issue a **Client ID** and a
    **Client Secret** — keep the secret out of any chat log; it grants
    read access to every linked account's full health history.
@@ -95,7 +145,7 @@ callback. The portal only owns the OAuth callback URL.
 ## 4. Link from the Settings page
 
 With the credentials saved in Settings, open
-`/settings/integrations/withings` and click **Connect Withings**. The flow:
+`/settings/integrations#withings` and click **Connect Withings**. The flow:
 
 1. The Connect button redirects to Withings' `oauth2/authorize`.
 2. The user signs in on Withings and grants the requested scopes.
@@ -131,7 +181,7 @@ import:
   when Apple Health is also linked, so the Apple Health stream wins
   for the cumulative axis. The Withings rows stay in the DB.
 
-Override per-user via Settings → Sources (`/settings/sources`).
+Override per-user via Settings → Source priority (`/settings/sources`).
 
 ## Troubleshooting
 
@@ -149,7 +199,7 @@ Override per-user via Settings → Sources (`/settings/sources`).
 ### The webhook stops firing
 
 Webhook subscriptions can lapse after a token revoke or a portal-
-side cleanup. Re-subscribe by opening `/settings/integrations/withings`
+side cleanup. Re-subscribe by opening `/settings/integrations#withings`
 and clicking **Disconnect** then **Connect Withings** again — the
 callback exchange re-runs `Notify.subscribe()` with a fresh callback
 URL.
@@ -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

@@ -1,472 +1,232 @@
-# Off-host backup & restore
+# Account copies and restore
 
-HealthLog ships with an optional daily off-host backup that ships every
-user's JSON dump, encrypted with AES-256-GCM under a SEPARATE key
-(`BACKUP_ENCRYPTION_KEY`), to any S3-compatible bucket — Cloudflare R2,
-AWS S3, Backblaze B2, MinIO, etc.
+HealthLog keeps copies of each account so that one account can be rolled back
+on this server. These copies are per account. They cannot rebuild a lost
+server: a restore writes into an account on this server, the one the copy
+belongs to, or, when that account has been erased, one you choose (see
+"Restoring an erased account"). To recover a server, you need a database dump
+and the encryption keys. That procedure is in
+[disaster-recovery.md](disaster-recovery.md).
 
-The backup runs at **02:30 Europe/Berlin** every day from the worker
-container (queue `data-backup-offhost`). Object key layout:
+## What exists
 
-```
-<bucket>/YYYY-MM-DD/user-<userId>.json.enc
-```
+| Copy                    | Where                     | When                                                           | Kept                                                                          |
+| ----------------------- | ------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| Weekly account rollback | this database             | Sundays 03:00, or **Backup now** in Admin → Backups            | one per account, replaced in place each week                                  |
+| Copy before a data wipe | this database             | right before "Delete all data" deletes anything                | until `ACCOUNT_DELETION_GRACE_DAYS` has passed, then the purge job deletes it |
+| Uploaded copy           | this database             | when an admin uploads a file in Admin → Backups                | until deleted                                                                 |
+| Off-host copy           | your S3-compatible bucket | nightly at 02:30 Europe/Berlin, one object per account per day | as long as the bucket's lifecycle rule keeps it                               |
+| Personal export         | the person's device       | Settings → Export, "Full backup"                               | wherever they keep it                                                         |
 
-## Wire format (binary)
+The weekly, pre-wipe and off-host copies carry the whole record, document
+files and ECG traces included, with the database's ciphertext inside them as
+stored. An uploaded copy holds whatever its file held. The personal
+export is portable: readable values, and documents as metadata only. It is
+meant for the person to keep and read. A restore refuses it when the file
+lists any document, because it carries no document content to put back.
 
-```
-magic   = "HLBK"           (4 bytes, ASCII)
-version = 0x04             (1 byte)
-keyIdLen, keyId            (1 byte + 12 ASCII hex: the first 12 hex digits of SHA-256(key))
-iv      = 12 random bytes  (AES-GCM nonce)
-ciphertext = N bytes       (AES-256-GCM over gzip(JSON dump), key = BACKUP_ENCRYPTION_KEY,
-                            associated data = "healthlog/offhost-backup/v4|<object key>")
-authTag = 16 bytes         (AES-GCM tag, trailing)
-```
+Two kinds of data are not in any account copy: workout GPS routes and sample
+series. Credentials, devices, share links and account grants are left out on
+purpose (see "What a restore does not touch").
 
-Version `0x04` (from v1.39.3) adds two things. The key id says which off-host
-key an object needs, so a reader holding a retired key as well finds the right
-one. The associated data is the object's own key in the bucket,
-`YYYY-MM-DD/user-<id>.json.enc`: an object copied to another account's name or
-another date does not decrypt, where before it opened as if it belonged there.
-The restore script passes the key it downloaded, so nothing changes for an
-operator.
+The JSON import in Settings → Export & import is not a restore. It adds
+measurements and mood entries, up to 16 MB and 10,000 entries per list.
 
-Four versions exist in the wild and all four restore. `0x01` encrypted the
-JSON directly and `0x02` gzipped it first; both carry the tag in FRONT of the
-ciphertext, which is what made them impossible to write a piece at a time —
-GCM only produces the tag once the last block is in, so a leading tag means the
-whole object has to exist before its first byte can be sent. `0x03` moves the tag to the end and changes nothing else: it still
-covers every ciphertext byte, and the reader still verifies it before returning
-a single byte of plaintext. Objects already in your bucket stay readable, and
-the restore script needs no flag to tell them apart.
+## The deletion grace window
 
-## Required env vars
+`ACCOUNT_DELETION_GRACE_DAYS` (14 by default, at most 30) sets how long an
+erasure waits:
 
-| Var                               | Required | Notes                                                                               |
-| --------------------------------- | -------- | ----------------------------------------------------------------------------------- |
-| `BACKUP_ENCRYPTION_KEY`           | yes      | 64 hex chars or 32-byte base64. **Different from `ENCRYPTION_KEY`.**                |
-| `BACKUP_S3_ENDPOINT`              | yes      | e.g. `https://<account>.r2.cloudflarestorage.com`                                   |
-| `BACKUP_S3_BUCKET`                | yes      |                                                                                     |
-| `BACKUP_S3_ACCESS_KEY`            | yes      |                                                                                     |
-| `BACKUP_S3_SECRET_KEY`            | yes      |                                                                                     |
-| `BACKUP_S3_REGION`                | no       | defaults to `auto` (Cloudflare R2)                                                  |
-| `BACKUP_RETENTION_DAYS`           | no       | not read by the app; the number for your bucket's lifecycle rule                    |
-| `BACKUP_ENCRYPTION_PREVIOUS_KEYS` | no       | retired off-host keys, comma-separated, read only (see "Rotating the off-host key") |
+- **Deleting an account**, or a guardian deleting a **managed profile**, locks
+  the account at once. Every session, refresh token, API token, connector and
+  share link is revoked, sign-in is refused with the date the account is
+  erased, and nothing runs for the account any more: no reminders, syncs,
+  copies, scores or AI work. The record, its stored copies and its off-host
+  objects stay as they are. **Admin → Users** shows the account with its
+  erasure date and an **Undo deletion** button. When the window ends, the
+  hourly `account-deletion-purge` job erases the account and asks the bucket to
+  delete its off-host objects.
+- **Delete all data** first stores the whole record as a copy of its own
+  (shown as "Before all data was deleted" in Admin → Backups), then empties the
+  record. An admin can restore that copy until the window ends. The off-host
+  objects from before the wipe are kept until then too.
 
-## Bucket permissions
+Database dumps are not purged per account: a deleted account stays in them
+until they age out (`DB_BACKUP_KEEP` nights on the server, and the bucket's
+lifecycle rule for `database/`). The deletion dialogs say so.
 
-The worker needs `PutObject`, `GetObject`, `ListBucket`, `DeleteObject` and
-`AbortMultipartUpload`. On Cloudflare R2 the **Object Read & Write** token
-covers all of them.
+`0` erases immediately, as releases before 1.46 did. The Data & Privacy page
+and the deletion dialogs state the configured number.
 
-`DeleteObject` is needed because the app deletes objects in two cases, and
-only those:
+## Restoring an account
 
-- **An account is deleted, or its data is wiped.** Deleting an account,
-  deleting a managed profile and "Delete all data" each write a deletion
-  request in the same transaction as the deletion. The `offhost-backup-purge` job lists the bucket, deletes every
-  `YYYY-MM-DD/user-<id>.json.enc` of that account and removes the request once
-  nothing of the account is left. It runs right after the deletion and again
-  every night at 03:40. A copy the nightly upload was writing while the account
-  was deleted is removed by the upload itself.
-- **The connection test** deletes its own `_healthcheck/<ts>.bin`.
+In **Admin → Backups**, every stored copy has **Restore**. The dialog first
+shows what the copy holds, then asks you to type `RESTORE`. The restore runs
+in the background and replaces the account's data tables: every row the copy
+holds comes back under its original id, and every row the account gained
+after the copy was taken is deleted. If the current state is worth keeping,
+press **Backup now** first.
 
-The admin wipe of every account deletes nothing in the bucket. It is you
-clearing your own host, the bucket is yours, and its copies are the way back
-from a wipe pressed by mistake. If you are handing the host on, empty the
-bucket yourself.
+_Also restore instance settings_ writes the registration, MFA, locale, module,
+notification and AI settings from the copy back for the whole server. Leave it
+clear unless those settings themselves need to go back.
 
-Earlier versions of this page said the worker never deletes an object. That
-was the design until v1.39.3, and it meant a deleted account's copies stayed
-in the bucket for as long as the lifecycle rule kept them, or forever without
-one. If the bucket refuses the delete (a credential without `DeleteObject`),
-the request stays, the job retries it every night, and **Admin → Backups →
-Off-host** shows how many deletions are outstanding and the bucket's answer.
-
-`AbortMultipartUpload` only reaches an upload the same worker started and is
-what clears the parts of a run that failed halfway. Without it, a failed
-upload leaves parts that are billed and do not show in a bucket listing.
-
-## Bucket lifecycle (required for retention)
-
-The app does not expire objects by age, and nothing in the app reads
-`BACKUP_RETENTION_DAYS`. Expiry is the storage provider's lifecycle rule, set
-to match the number you wrote there. Without one, every nightly copy of every
-account is kept forever. **Admin → Backups → Off-host** reads the bucket's
-lifecycle configuration and says so when there is none, or when the credential
-may not read it (grant `GetLifecycleConfiguration` to let it check):
-
-```
-Filter: "" (all objects)
-Action: Expire after 30 days
-```
-
-For Cloudflare R2 add this from the bucket's **Settings → Lifecycle**.
-
-## Smoke test
-
-After deploying, hit `POST /api/admin/backup/test` (admin-only). It
-performs a 1-byte PUT + GET round-trip and returns:
-
-```json
-{
-  "data": {
-    "endpoint": "https://...r2.cloudflarestorage.com",
-    "bucket": "healthlog-backups",
-    "region": "auto",
-    "putLatencyMs": 142,
-    "getLatencyMs": 38,
-    "ok": true
-  },
-  "error": null
-}
-```
-
-The credentials are never returned.
-
-## Restore
-
-Pick a key (e.g. `2026-05-08/user-clx123.json.enc`) from the bucket
-and run the restore script with the same backup credentials and
-encryption key the backup was written under — a freshly generated
-`BACKUP_ENCRYPTION_KEY` cannot decrypt any existing object:
+To restore from an **off-host object**, fetch and decrypt it from a source
+checkout with the backup variables of the server that wrote it:
 
 ```bash
-BACKUP_S3_ENDPOINT=https://...r2.cloudflarestorage.com       \
-BACKUP_S3_BUCKET=healthlog-backups                           \
-BACKUP_S3_ACCESS_KEY=...                                     \
-BACKUP_S3_SECRET_KEY=...                                     \
-BACKUP_S3_REGION=auto                                        \
-BACKUP_ENCRYPTION_KEY=<the key the backup was written under> \
-pnpm dlx tsx scripts/restore-backup.ts \
-  2026-05-08/user-clx123.json.enc \
-  /tmp/restored.json
+BACKUP_S3_ENDPOINT=... BACKUP_S3_BUCKET=... \
+BACKUP_S3_ACCESS_KEY=... BACKUP_S3_SECRET_KEY=... \
+BACKUP_ENCRYPTION_KEY=<the key the object was written under> \
+pnpm dlx tsx scripts/restore-backup.ts 2026-05-08/user-<id>.json.enc /tmp/restored.json
 ```
 
-Run this command from a source checkout with the production backup variables
-exported. The script imports the full application dependency graph, which the
-minimal production image does not expose as an operator scripting environment.
+Then upload `/tmp/restored.json` in Admin → Backups (up to 512 MB after
+compression) and restore it from its row. When the account `<id>` no longer
+exists on this server, the upload offers to put the copy into another account
+(next section).
 
-The script downloads the object, decrypts it, and writes the JSON dump
-to disk. Importing the JSON back into a HealthLog instance is left to
-the operator (use `prisma db seed` or a custom script).
+Every restore, preview and upload checks first that this server holds every
+application key the copy's content was written under, and refuses with the key
+id named if not. Nothing is changed by a refused restore.
 
-Restoring is not streamed and does not need to be. It holds the whole document,
-because the next thing anyone does with a backup is parse it as one JSON
-object, and handing back plaintext the auth tag has not yet covered would trade
-the authentication for memory. It runs on your machine rather than in the
-container, so give it room: a record of several hundred thousand measurements
-decompresses to a few hundred megabytes, and
-`NODE_OPTIONS=--max-old-space-size=2048` in front of the command is enough for
-a 445 000-measurement account.
+### Restoring an erased account
 
-### Restoring from the backups console
+Once an account has been erased (its deletion window ended and the hourly purge
+ran), its copies on this server and in the bucket are gone, but a file you kept
+still holds the record: a disaster-recovery download, an off-host object you
+fetched before it expired, or the person's own full backup. Uploading it in
+Admin → Backups is refused at first, because the account it names no longer
+exists, and the console then asks where the records should go:
 
-An admin can restore a stored snapshot from the browser instead of the shell.
-`/admin/backups` lists one row per account and per backup type: **Backup now**
-enqueues the `data-backup` pass for every account on the instance, **Download**
-decrypts one snapshot and hands back the JSON, and **Restore** opens a dialog
-that first shows what the file carries and then requires the word `RESTORE` to
-be typed before it will run. The restore targets the account the snapshot was
-taken for, never the admin running it, and it refuses a file whose declared
-owner does not match the stored row. Instance-wide settings ride along only
-when you tick _Also restore instance settings_ in the dialog; leave it clear to
-restore the account alone.
+- **A new account.** Type a username. The account is created without a
+  password or email, as an ordinary account with the user role, and nobody
+  can sign into it yet. Before handing it over, set its first password with
+  **Reset password** in Admin → Users; the person can change it, add an email
+  and enrol a passkey from their settings. The account is made before the
+  file is read, with an `admin.user.create` audit row (`outcome: "created"`),
+  and removed again when the file is refused, with an `admin.user.delete` row
+  (`reason: "backup_upload_refused"`). When that row says `outcome: "failed"`,
+  the removal did not happen and the account is left over, holding nothing:
+  delete it in Admin → Users.
+- **An existing account**, for someone who has signed up again. Pick the
+  account and type its username to confirm. The account must hold no records
+  yet: a restore replaces an account's records and does not merge them, so an
+  account with even one record of any kind a copy carries is refused, with the
+  kinds named. What signing up and the setup questions leave behind does not
+  count (the setup answers and the cycle settings): the restore replaces both
+  with the copy's. A reading or medication entered on setup's last screen is a
+  record, and the account is refused until it is deleted, because the restore
+  would delete it too. Managed profiles, accounts pending deletion and admin
+  accounts are not offered: an admin account is the operator's, its settings
+  are read under the operator's wider AI endpoint policy, and its role reaches
+  every account, so another person's record does not go into it.
 
-A stored copy this instance can no longer open — the key that wrote it dropped
-from `ENCRYPTION_KEYS` one rotation too early, or bytes that are not the ones
-written — is refused by all three buttons with `422` and
-`meta.errorCode = backup.payload.undecryptable`, before anything is read back.
+The file is then uploaded a second time, and its owner is changed to the chosen
+account as it is read. Nothing else in the file changes. The stored copy is
+then that account's copy in every respect but one: its preview, its download
+and its restore are the ordinary ones, and **Restore** on its row brings
+everything back under the chosen account. The one difference is that it is
+stored as `RETARGETED_UPLOAD_<time>` rather than `MANUAL_UPLOAD_<time>`, and its
+restore reads the file's settings as the file's author's, never as the
+operator's: an AI endpoint on a private address comes back only when this host
+grants it to ordinary accounts (`AI_PRIVATE_ORIGINS`), even if the account has
+been made an admin since. The erased account's id is not stored, not in
+the copy and not in the audit trail.
 
-### What a backup deliberately does not carry
+A copy whose own account still exists on this server can only go back into
+that account; choosing a target for it is refused. The copy does not carry
+what a restore never touches (below), so a returning person signs in fresh,
+and the links of a managed profile to its guardians do not come back: a
+restored managed profile is an ordinary account.
+
+Once stored, the copy restores like any other: a restore run later, after the
+account has gained records, replaces those too.
+
+A file goes into one account only. Its records keep the ids they had in the
+erased account, so once it has been restored into one account, restoring the
+same file into a second account would write those ids twice. The upload still
+stores the second copy, but its restore is refused with
+`backup.restore.rows_exist_elsewhere` and rolled back, and nothing changes in
+either account. To move the record to another account, delete the first
+account (or its records) before restoring into the second.
+
+### What a restore does not touch
 
-Every credential-shaped row is left out, and this is not an oversight to fix:
 API tokens, trusted devices, step-up elevations, known devices, clinician share
-links, and the account grants behind shared record access. Restoring data is
-rolling a record back to a known state. Restoring an authorization is different
-in kind, because a grant the owner revoked on Tuesday would come back alive out
-of Monday's file with nobody deciding it and neither person told.
+links and account grants are not in any copy. A restore on this server leaves
+them as they are, so shared access carries on. The reasoning per model is in
+`src/lib/export/backup-plan.ts`.
 
-What this means in practice depends on where you restore to.
+## Off-host copies
 
-**Onto the same instance.** Nothing changes. The restore replaces the account's
-data tables and does not touch grants, tokens or devices, so shared access
-carries on exactly as it was. Somebody who had read access before the restore
-still has it afterwards, now looking at the restored data.
+| Variable                          | Required | Notes                                                                 |
+| --------------------------------- | -------- | --------------------------------------------------------------------- |
+| `BACKUP_ENCRYPTION_KEY`           | yes      | 64 hex chars or 32-byte base64; not the same as `ENCRYPTION_KEY`      |
+| `BACKUP_S3_ENDPOINT`              | yes      | e.g. `https://<account>.r2.cloudflarestorage.com`                     |
+| `BACKUP_S3_BUCKET`                | yes      |                                                                       |
+| `BACKUP_S3_ACCESS_KEY`            | yes      |                                                                       |
+| `BACKUP_S3_SECRET_KEY`            | yes      |                                                                       |
+| `BACKUP_S3_REGION`                | no       | defaults to `auto` (Cloudflare R2)                                    |
+| `BACKUP_RETENTION_DAYS`           | no       | not read by the app; the number to put in the bucket's lifecycle rule |
+| `BACKUP_ENCRYPTION_PREVIOUS_KEYS` | no       | retired off-host keys, comma-separated, used for reading only         |
 
-**Onto a fresh instance.** None of it comes with the file. Nobody has access to
-anybody's record, every API token has to be reissued, every device re-trusted,
-and both people have to invite and accept again before sharing works. That is
-the fail-safe direction — access lost, never access resumed — and re-consenting
-is the right amount of ceremony for handing someone your health record a second
-time. Plan for it rather than discovering it.
+Objects are named `YYYY-MM-DD/user-<id>.json.enc`: the record as JSON,
+gzipped and sealed with AES-256-GCM under `BACKUP_ENCRYPTION_KEY`, with the
+object's own name as associated data and the key's id in the header.
 
-The full per-model reasoning lives in `src/lib/export/backup-plan.ts`, where
-every excluded model carries a written verdict and a structural test refuses to
-let a new model land without one.
+The nightly database dump goes into the same bucket, as
+`database/<host of APP_URL>/healthlog-<time>-daily.dump.enc` with its manifest
+beside it, sealed the same way. The folder keeps the dumps of instances that
+share a bucket apart. It is the copy that rebuilds a lost server
+([disaster-recovery.md](disaster-recovery.md)).
 
-## Container memory (the nightly off-host job)
+**Permissions.** The worker needs `PutObject`, `GetObject`, `ListBucket`,
+`DeleteObject` and `AbortMultipartUpload` (R2's Object Read & Write token covers
+them). It deletes only two things: the objects of an account that was erased or
+wiped, once the grace window has ended, and its own connection-test object. A
+deletion the bucket refuses is retried every night and shown in Admin →
+Backups → Off-host. The admin wipe of every account deletes nothing in the
+bucket.
 
-This is the part that bites, and it bit the nightly job a release after it bit
-the weekly one. The job runs inside the app process, so V8's heap limit is the
-app's heap limit, and a container capped at 1 GB gives Node a 524 MB old-space
-limit by default. A long-lived Next.js server is already holding a large share
-of that before the job starts.
+**Retention.** The app never expires objects by age. Set a lifecycle rule on
+the bucket that covers both the account objects and `database/` (for example,
+expire all objects after 30 days); Admin → Backups says when there is none.
 
-The uploader used to build the whole backup JSON as one string, gzipped
-that whole string, ran a whole-buffer cipher pass over the result and handed
-the finished buffer to a single `PutObject` — four full copies of the record
-alive at once. On an account of 445 000 measurements the JSON alone is 242 MB,
-and the first configured run took the container down seventeen seconds in with
-`FATAL ERROR: Reached heap limit`. Because the job shares the app process, one
-account's size restarted the instance for everybody on it.
+**Checking it works.** Admin → Backups → Off-host shows, per account, when the
+last object landed: fresh, due (one night missed), stale (two missed), never,
+or no record yet. A night that uploaded nothing for anybody fails the job with
+the bucket's own error. Accounts pending deletion are not uploaded and are not
+listed. On the 1st of each month at 04:11, a drill downloads the newest object
+of every account, decrypts it and checks its shape and keys. It restores
+nothing.
 
-It streams now. The JSON is produced a page at a time, gzip and the cipher
-consume it as it arrives, and the object goes up as a multipart upload that
-holds two 8 MB parts. What the process holds is fixed by that pipeline's shape
-rather than by the size of the record going through it: measured on the same
-445 000-measurement account under `--max-old-space-size=450`, the old path
-died and the new one finished holding tens of megabytes, writing a 9.1 MB
-object that restores to the identical record.
+**Rotating the off-host key.** Put the new key in `BACKUP_ENCRYPTION_KEY`, move
+the old one to `BACKUP_ENCRYPTION_PREVIOUS_KEYS`, restart. Remove the old key
+once the lifecycle rule has expired every object written under it.
 
-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,
-is counted in the run's `offhost_backup_oversized` meta, and the pass carries
-on with everybody else.
+## Keys a copy needs
 
-### Reading a failed run
+A copy carries the database's ciphertext as stored, so it needs the
+application keys it was written under, also after a rotation. Keep a retired
+`ENCRYPTION_KEYS` entry until no copy you may still restore needs it. **Admin →
+Encryption → Keys the backups still need** lists them, the database dumps
+included: a dump needs the key that was active when it was taken, for as long
+as it is kept on this server or in the bucket. Off-host objects also need
+`BACKUP_ENCRYPTION_KEY` (or the previous key that wrote them).
 
-A nightly run that could not upload for **anybody** now fails the pg-boss job
-instead of reporting success. This is the case wrong credentials, a missing
-bucket and an unreachable endpoint all land in, and the target's own sentence
-rides out as the failure cause — `The request signature we calculated does not
-match the signature you provided`, `The specified bucket does not exist`,
-`connect ECONNREFUSED`. Check `offhost_backup_uploaded` against
-`offhost_backup_total_users`: before this change a run where every single
-upload failed still read `ok: true`, so a bucket could stay empty while the
-jobs page looked healthy.
+## Size and memory
 
-A run where SOME account got a copy still succeeds, with the rest counted in
-`offhost_backup_failed`. Failing the whole queue over one account's object
-would re-upload everybody's on every retry.
+Writing, reading and restoring a copy streams: the record goes through a page
+at a time, documents one at a time, and a stored copy is kept as sealed pieces
+of about a megabyte. Memory does not grow with the record. Give the app
+container at least 1 GB.
 
-### Which account has no copy
+`BACKUP_MAX_STORED_MB` (default 2048) caps one account's stored copy. An account
+past it fails alone, keeps its previous copy, and is counted as
+`records_oversized`; the message names the setting.
 
-The counts above say how many accounts were uploaded, never which. An account
-whose object has failed every night for a month reads as `99 uploaded, 1
-failed` each time, which looks like weather.
-
-**Admin console → Backups → Off-host copies** answers it per account: when this
-host last put that account's encrypted copy in the bucket, how big it was, and
-how that compares with the nightly schedule. **Fresh** is inside one run,
-**due** means one run produced nothing for that account, **stale** means two
-did not, **never** means a run walked the account and no object has ever
-landed for it, and **no record yet** means no run has recorded the account at
-all. On a host without `BACKUP_S3_*` the card says off-host backup is not
-configured and stops there.
-
-The ledger starts empty on the release that adds it, so on a host that has
-been uploading nightly for months every account reads **no record yet** until
-the first run after the upgrade. That is the ledger having no history, not the
-bucket being empty — which is why it is a separate word from **never**, and
-why the row says so rather than claiming nothing has ever reached the bucket.
-
-Each verdict carries six hours of slack on top of the schedule's own 24, and
-that slack is load-bearing on two nights. The cron runs at 02:30 Europe/Berlin,
-so on the DST fall-back Sunday two consecutive runs are 25 hours apart; and the
-timestamp is when _that account's_ object landed, so on a cohort walked one
-account at a time an account reached later tonight than last night drifts by
-hours. Without the slack a healthy host would paint its whole cohort **due**
-once a year.
-
-The verdicts come from a ledger the worker writes when the object lands
-(`offhost_backup_state`), not from a listing of the bucket. Keep the worker's
-grant as documented — PutObject, GetObject, AbortMultipartUpload — and the card
-still tells the truth. A row that goes stale while the run reports success is
-that account's object being refused, and the reason is in the run's
-`offhost_backup_failures` meta.
-
-## The weekly in-database backup (`data-backup`)
-
-Separate from the off-host job above, and easy to confuse with it. A second
-pg-boss job writes one `WEEKLY_AUTO` copy per user into the database, the same
-JSON document, gzipped and then encrypted under `ENCRYPTION_KEY` /
-`ENCRYPTION_KEYS`, staying inside the instance. It is what
-`/api/admin/backups/<id>/restore` reads, and an uploaded backup file is stored
-the same way.
-
-### How a copy is stored
-
-From v1.39.2 a copy is kept as ordered pieces of about a megabyte in
-`data_backup_chunks`, with the list of pieces on its `data_backups` row. The
-writer produces the JSON a page at a time, gzips it as it goes and seals each
-megabyte of gzip output on its own with AES-256-GCM. Reading it back (restore,
-preview, download) takes the pieces one at a time. Nothing on either path holds
-the whole copy, so the size of a copy has nothing to do with the app's memory.
-Measured on an account of 2.6 million readings in the default 1 GB container,
-with the web server and the worker in one process: the backup took 87 seconds
-and stored 97 MB in 96 pieces, the preview 20 seconds, the download of the
-1.4 GB file 25 seconds, and the restore 264 seconds, which gave back every
-reading exactly. The container peaked at 567 MB and did not restart. What the
-backup, preview and download hold on top of the running app stays at a few tens
-of megabytes and does not grow with the account. A 512 MB container is too
-small for the app itself: its heap limit is 259 MB and a backup of any account,
-even one with 130 000 readings, runs it out of heap.
-
-Each piece carries, inside its encryption, which copy it belongs to, its
-position, and whether it is the last. Before a restore deletes anything, every
-piece is checked: a piece that is missing, moved, altered, taken from another
-copy, or a copy that stops short of its last piece is refused with
-`backup.payload.undecryptable`, and the account is left as it was.
-
-The write is one transaction. Until the new copy is complete the previous one
-stays in place and readable; a run that fails halfway leaves it untouched. A
-second backup of the same account started while one is running (a manual run
-during the weekly one, say) waits for the first to finish and then replaces
-its copy; neither leaves a partial copy behind.
-
-While a restore of an account's copy is queued or running, the weekly and
-manual backup leave that account's copy alone and back up everyone else. The
-run's `users_skipped_restoring` meta counts such accounts; the next run
-replaces the copy as usual. If a copy is replaced anyway while it is being
-read (a download or preview in progress when the weekly run finishes), the
-reader answers `409` with `backup_changed` and "The backup was replaced by a
-newer one while it was being read", not the undecryptable error, and a restore
-rolls back with nothing changed. Start it again to use the new copy. A
-download already sending when this happens stops partway; download again.
-
-Copies written before v1.39.2 are a single value in `data_backups.data` and
-still restore, preview and download as they did. The next weekly run replaces
-the weekly copy in the new form, and a key rotation (below) converts every
-remaining one, including uploaded copies. Until then those older copies are
-read as one value, as before, which needs the memory they needed when they were
-written.
-
-Migration 0352 cannot be undone by going back to v1.39.1. That release reads
-only the single value, so it finds a copy in pieces empty, and if it writes a
-weekly copy into a row that has pieces, the row holds both forms. v1.39.2 then
-refuses to read that row, because nothing says which of the two is current
-("This backup holds both a single stored value and pieces ..."); the next
-weekly backup replaces it. If you must go back, restore the database backup
-you took before upgrading.
-
-### The size limit
-
-The one limit left is on storage: a copy of one account may take at most
-`BACKUP_MAX_STORED_MB` megabytes (default 2048). It exists so a runaway copy
-fails with a message instead of filling the database volume, which holds the
-old and the new copy side by side while a backup runs. An account past it fails
-for that account alone, is counted in the run's `users_failed` and
-`records_oversized` meta, and keeps its previous copy; the pass carries on with
-everybody else. The message names the setting. Raise it in `.env`, recreate the
-app container, and make sure the database volume has room for two copies of
-that size.
-
-Before v1.39.2 the limit was a fifth of the app's heap, 105 MB in a 1 GB
-container, because the copy had to pass through the app as one value. An
-account with 1.75 million readings was past it, and the only way round was more
-memory. That is no longer the case: `records_oversized` means the storage limit,
-never memory.
-
-The writer deliberately reads no heap gauge. A version that did shipped in
-v1.38.6 and compared the whole process's live usage, garbage included, against
-80 % of the limit. A Next.js server that has been up for a week sits at 400 MB
-of largely collectable heap, so the weekly pass aborted every account on the
-first chunk, including one whose whole stored copy is 1.2 MB, and reported
-success while doing it. If you are on v1.38.6, a `data-backup` run that finishes
-in seconds having backed up nothing is that defect and not your record.
-
-### Key rotation
-
-Rotation reaches a stored backup's envelope and nothing inside it. The
-content of a disaster-recovery backup is the database's ciphertext, carried
-as it is stored, and a restore writes it back verbatim: a note, a document or
-a coach message inside a copy taken before a rotation still needs the key the
-rotation retired. The same holds for every copy in the off-host bucket and for
-every file an operator has downloaded. So the rule is: **keep a retired
-`ENCRYPTION_KEYS` entry until no backup you may still restore needs it.**
-**Admin → Encryption → Keys the backups still need** lists, per key id, the
-stored copies that need it with the oldest date, and when the last off-host
-copy needing it expires under the bucket's lifecycle rule. Copies written
-before v1.39.3 did not record their keys and are listed as such.
-
-Every restore, the restore preview, the admin upload and the monthly drill
-check this before anything is changed: a file whose content needs a key this
-server does not have (or an id whose key material differs) is refused with the
-key id named, and the account is left as it was.
-
-Re-encrypting the content of stored backups during rotation was considered and
-not done: it would mean decrypting, parsing, re-encrypting and re-writing every
-copy in full, and it still could not reach the off-host copies or downloaded
-files, so the rule above would be needed regardless.
-
-`scripts/rotate-encryption-key.ts` and the rotation in the admin console
-re-seal every piece under the active key, in small batches, without reading
-the backup inside. The link between a piece, its copy and its position is
-inside the encryption, so it comes through rotation unchanged.
-
-A copy still in the older single-value form (any of them, including the
-`~hlgcm1.` form v1.38.6 to v1.39.1 wrote) is not re-sealed in place, which would need the
-whole copy in memory several times over. Rotation converts it into pieces
-under the active key instead, one copy at a time, reading the stored value a
-few megabytes at a time; the copy keeps its date. The conversion of a copy is
-one transaction, so a copy that fails its check is left exactly as it was and
-counted as an error. Rotation up to v1.39.1 counted every `~hlgcm1.` copy
-as an error; run it again after updating before retiring the old key.
-
-### What a restore replaces
-
-A restore replaces the account's data tables; it does not merge into them.
-Every row the file carries is written back under its original id, and every row
-the account gained after the snapshot was taken — readings, doses, mood
-entries, documents — is deleted with the rest of the class before the file is
-read back. Restoring Monday's copy on Wednesday therefore costs the account
-everything it recorded on Tuesday. If the current state is worth keeping, take
-a fresh snapshot from the backups console before restoring the old one.
-
-## Rotating the off-host key
-
-`BACKUP_ENCRYPTION_KEY` is the key new objects are written under. To rotate
-it, set the new key there and move the old one into
-`BACKUP_ENCRYPTION_PREVIOUS_KEYS` (comma-separated if there are several), then
-restart. New objects are written under the new key; older objects stay
-readable because every version-4 object names its key and older objects are
-tried against each key in turn. Remove the old key once the lifecycle rule has
-retired every object written under it, that is `BACKUP_RETENTION_DAYS` after
-the restart.
-
-## Monthly restore drill (automatic)
-
-Since v1.16.4 a pg-boss job (`data-restore-drill`, cron `11 4 1 * *` —
-04:11 on the 1st of each month) exercises the read path end-to-end:
-fetch the most recent backup object from the bucket, decrypt it under
-the current `BACKUP_ENCRYPTION_KEY`, JSON-parse it, and sanity-check
-the payload shape. It performs **no database restore** — it validates
-the artefact, not the import path.
-
-Outcomes:
-
-- **Success** — record counts, object age, and sizes land in the
-  wide-event meta (`job.restore_drill`).
-- **Stale chain** — the newest object is older than 3 days: the nightly
-  uploader has stalled (or the lifecycle rule is too aggressive). The
-  drill pages via the worker error reporter (stderr + GlitchTip).
-- **Failure** — empty bucket, fetch error, decryption failure (wrong or
-  rotated key), malformed JSON: pages the same way. A decryption
-  failure right after a `BACKUP_ENCRYPTION_KEY` change means the new
-  key cannot read the existing objects: put the old key into
-  `BACKUP_ENCRYPTION_PREVIOUS_KEYS` (see "Rotating the off-host key").
-- **Content under a missing application key** — the object opens, but its
-  content was written under an `ENCRYPTION_KEYS` entry this server no longer
-  has, or under an id whose key material changed. The drill decrypts one value
-  per key id it finds, and pages naming the key. A restore of that object
-  would write back rows nobody can open; put the key back before restoring.
-- **Not configured** — deployments without the `BACKUP_S3_*` vars skip
-  silently (wide-event warning only).
-
-The drill lists the bucket to find the newest object, so it needs
-`ListBucket` on top of the uploader's `PutObject`, `GetObject` and
-`AbortMultipartUpload`. Cloudflare R2's **Object Read & Write** token covers
-all four.
+Both backup passes note which account they are on. An account whose last
+attempt never finished (the process died under it) is taken last on the next
+run and named in Admin → Backups, so one record too large for the container
+cannot keep everyone else from a copy.

docs/ops/blood-pressure-missing-diastolic.md

@@ -0,0 +1,60 @@
+# Blood pressure readings missing their diastolic half
+
+## What happened
+
+The iPhone app (every App Store build up to 1.0.3 and TestFlight 1.1.0)
+saves a manually entered blood pressure as two requests to
+`POST /api/measurements`: one `BLOOD_PRESSURE_SYS`, one
+`BLOOD_PRESSURE_DIA`, both carrying the same `Idempotency-Key`. Until the
+replay cache learned to compare request bodies, the server treated the second
+request as a retry of the first. It answered with the first request's cached
+`201` (header `X-Idempotent-Replay: true`) and never wrote the diastolic
+value. The app showed success, so nobody noticed.
+
+The fix makes the cache replay only a request with the same body. A different
+body under the same key now runs normally. Nothing recovers the values that
+were never sent to the database: they exist only on the person's phone, if at
+all.
+
+## Finding the affected readings
+
+Read-only. Run it against the HealthLog database (with the bundled compose
+file: `docker compose exec db psql -U healthlog healthlog`). It lists every live systolic reading that has no
+live diastolic reading for the same account at the same instant.
+
+<!-- bp-missing-diastolic:start -->
+
+```sql
+SELECT u.username,
+       m.id,
+       m.measured_at,
+       m.value AS systolic,
+       m.source
+FROM measurements m
+JOIN users u ON u.id = m.user_id
+WHERE m.type = 'BLOOD_PRESSURE_SYS'
+  AND m.deleted_at IS NULL
+  AND NOT EXISTS (
+    SELECT 1
+    FROM measurements d
+    WHERE d.user_id = m.user_id
+      AND d.measured_at = m.measured_at
+      AND d.type = 'BLOOD_PRESSURE_DIA'
+      AND d.deleted_at IS NULL
+  )
+ORDER BY u.username, m.measured_at;
+```
+
+<!-- bp-missing-diastolic:end -->
+
+Readings from the phone app carry `source = 'MANUAL'`. Rows from a synced
+source (Withings, Apple Health) that show up here are a different gap, not
+this one: those sources write both halves themselves.
+
+## What to tell users
+
+There is nothing the server can repair: the diastolic value never reached
+it. A person whose reading appears in the list can re-enter it: delete the
+incomplete reading, then add the blood pressure again with both values and
+the original date and time. From this release on, both halves are saved on
+the first try, from any app version.

docs/ops/deploy.md

@@ -13,6 +13,14 @@ Migrations land **before** the new app container takes traffic. The
 canonical command sequence on a single-instance host:
 
 ```sh
+# 0. Nothing to do by hand for the way back: when the new image brings
+#    migrations, its entrypoint first writes
+#    healthlog-<time>-pre-migration.dump into DB_BACKUP_DIR (the `backups`
+#    volume) and keeps the last two. A migration is not undone by going back
+#    to the previous image; that dump is the way back
+#    (docs/ops/disaster-recovery.md, "Going back to before a migration").
+#    Copy it off the host if the host itself is what you are worried about.
+
 # 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
@@ -27,6 +35,15 @@ docker compose run --rm app sh -c 'exit 0'
 docker compose up -d app
 ```
 
+Step 2 takes the pre-migration dump too, in the one-off container, before it
+migrates. When the backups directory is on its volume and that dump fails (a
+full disk, most often), the entrypoint stops before migrating and says so;
+free the space and run the step again, or set `DB_BACKUP_BEFORE_MIGRATE=false`
+for one start without the dump. Without the `backups` volume the directory
+is not writable, or it is the image's own and sits inside the container that
+the update replaces; either way the log carries a warning, no dump is taken,
+and the migrations run.
+
 Use `docker compose run` rather than a plain `docker run` for step 2. A
 plain `docker run` starts outside the stack's network, where `db` does not
 resolve, and the entrypoint gives up after thirty seconds with "Database
@@ -34,6 +51,191 @@ 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.
+
+### A concurrent index build that failed
+
+A migration that builds an index `CONCURRENTLY` (0477 is one) and fails
+half-way, on a constraint violation, a cancel or a killed container, leaves an
+INVALID index behind and its attempt on record as failed. Once you have mended
+the cause and run `prisma migrate resolve --rolled-back <migration>`, the next
+boot drops that INVALID index before it migrates, logs
+`dropped the invalid index …`, and the re-run builds it again. Without that
+step the re-run would find the index by name and skip it.
+
+A build that is still running looks the same, INVALID with its migration not
+yet finished. The boot therefore leaves every index alone while another
+instance is migrating (it checks Prisma's migration lock first) and never
+drops an index Postgres reports as being built, so a second container that
+starts during the first one's migration cannot cancel it.
+
+An INVALID index whose migration is already recorded applied is not touched at
+boot. The boot names it on stderr with `WARNING — index … is INVALID`; rebuild
+it with `REINDEX INDEX CONCURRENTLY "<index>";` when the database is quiet.
+
+### The app's database role
+
+The steps above run as the owner `DATABASE_URL` names: the dump, the
+migrations and, after them, the job queue's own install or migration and the
+setup of `healthlog_app_<database>_<hash>`, the role the app then connects as
+([database-role.md](../self-hosting/database-role.md)). Neither the app nor
+its queue ever runs a migration. A migration that creates a table needs
+nothing more: the setup grants the role every table it lacks before the app
+starts.
+
+The queue schema `pgboss` stays the owner's. When an update brings a newer
+pg-boss with a schema migration, the start runs it as the owner, including
+its index builds, before the app starts; on a large queue that start takes as
+long as the builds. Stop the old container (and a separate worker) before the
+new one starts, as for any update with migrations. A web container and a
+worker container that start together wait for each other on an advisory lock
+and derive the same password. Going back to 1.46 runs as the owner, as 1.46
+always did, and finds nothing in the queue schema it did not create.
+
+### v1.46.0 notes
+
+- **Postgres 18.** The compose file moves the bundled database from
+  Postgres 16 to 18. The first `docker compose up -d` with the new compose
+  file runs `db-upgrade`, which copies the database into a new
+  `postgres-data` volume, checks every table's row count, and only then lets
+  the app start; the old `pgdata` volume stays as it was, as the way back.
+  Pulling only the new image with the old compose file keeps 16, which this
+  release still runs on. Details, rollback and the steps for a database you
+  run yourself: [postgres-major-upgrade.md](postgres-major-upgrade.md).
+- Migration `0485` drops `preview_features_json` from `users`, the same
+  pattern as `0430` in v1.44.0 below: do not run the previous image beside
+  the new schema. The sequence above stops the old container first; a
+  web/worker split stops both roles before the first new container starts.
+- Migration `0487` drops four columns from `app_settings`
+  (`encryption_key_backup_confirmed_at`, `_key_id`, `_fingerprint` and
+  `_by_user_id`) after carrying the confirmation they held into the new
+  `recovery_kit_confirmations` table. The previous image reads those columns
+  on nearly every request that loads the instance settings and fails once
+  they are gone, so the same rule holds: never run it beside the new schema.
+- The other migrations create tables (`0486`, `0487`), add columns
+  (`0480`, `0482`, `0483`, `0488`, `0489`) and build two indexes: `0477`
+  concurrently on `measurements`, `0488` without `CONCURRENTLY` on `users`,
+  which is small enough that the short lock does not matter. Three touch
+  rows: `0476` links API-written measurements to their token on accounts
+  that have exactly one measurement token, and `0478`/`0479` give PDFs whose
+  preview or text read failed one more attempt. On a prod-sized copy all of
+  them together finished in under a second.
+- **Rolling back to v1.45 while accounts are pending deletion.** v1.46 keeps
+  a deleted account, a deleted managed profile and a data wipe's copy for a
+  grace window (`0488`). v1.45 knows none of that: an account pending
+  deletion can sign in again with its password and every background job runs
+  for it again, nothing ever erases it, a wipe's off-host purge held to the
+  end of its window runs at once, and v1.45's wipe deletes the copies taken
+  before earlier wipes. Before going back, list the accounts with
+  `SELECT id, username, deletion_purge_at FROM users WHERE deletion_requested_at IS NOT NULL;`
+  and either undo each deletion in the admin users list or let the purge
+  finish them first; after coming forward again, delete any that should
+  still go.
+
+### v1.45.0 notes
+
+A single-container install (`HEALTHLOG_PROCESS_TYPE=all`, the shipped
+compose file) needs no action: the sequence above applies the one migration
+and the job-queue upgrade on the first boot.
+
+- Migration `0471` adds one nullable column to `healthkit_type_syncs`. It is
+  additive and rewrites no rows.
+- The job queue library moves its own schema from version 45 to 46 (new
+  columns on its queue table, four indexes built concurrently afterwards).
+  Only a worker process runs that upgrade; a web-only process opens its
+  send-only connection without migrating and refuses a schema older than
+  its own (`pg-boss database requires migrations`), so it cannot queue
+  anything until the upgrade has run. A web/worker split therefore deploys
+  in this order: stop both roles, start the new **worker** and wait until its
+  startup log line carries `"reminder_worker": "started"`, then start the new
+  web containers.
+  The other order leaves the web containers without a queue (imports and
+  document reads answer `503 Background worker is not running`) until they
+  are restarted after the worker. An old web container left running beside
+  the upgraded schema loses its queue the next time it reconnects.
+- The shipped compose file gives the app `stop_grace_period: 45s`, so a
+  redeploy lets running jobs finish instead of cutting them off after
+  Docker's default ten seconds. A forked or older compose file should add the
+  same line to the app and worker services.
+
+### 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
@@ -74,10 +276,47 @@ roll back:
    app version reads forward-compatible-ish shapes for nearly every
    release pair shipped on the v1.4.x line.
 3. If a column-drop migration ships in the rollback target, hand-roll
-   the column back via a fresh forward migration (`pnpm prisma migrate
-dev --create-only --name vX_Y_Z_rollback_<col>`), edit the SQL,
-   commit, and re-deploy. Never `migrate resolve --rolled-back` against
-   production unless you've taken a fresh `pg_dump` first.
+   the column back via a fresh forward migration
+   (`pnpm prisma migrate dev --create-only --name vX_Y_Z_rollback_<col>`),
+   edit the SQL, commit, and re-deploy. Never `migrate resolve --rolled-back` against
+   production unless you've taken a fresh `pg_dump` first. The columns each
+   release drops are named in its notes above: for v1.46.0 that is
+   `users.preview_features_json` (`0485`) and the four
+   `app_settings.encryption_key_backup_confirmed_*` columns (`0487`); the
+   key backup confirmation then has to be given again on v1.45.
+4. Rolling back from v1.40.2 or later to v1.40.1 or earlier: an account
+   that saved the Coach lookback "Last year" reads its whole Coach
+   preference blob as defaults on the older version, metric exclusions
+   included, until the setting is saved again. Ask affected accounts to
+   pick another lookback before the rollback, or re-save their exclusions
+   after it.
+
+When the data itself has to go back to before the update, restore the
+pre-migration dump with the previous image; the steps are in
+[`disaster-recovery.md`](disaster-recovery.md#going-back-to-before-a-migration).
+
+## Catalog templates
+
+The TrueNAS catalog bot follows new image tags on its own, so a routine
+release needs nothing there. These changes do need a matching pull request to
+`truenas/apps` (`ix-dev/community/healthlog/`) in the same release cycle, and
+an update to `docs/self-hosting/unraid/healthlog.xml` and
+`docs/self-hosting/portainer/templates.json`:
+
+- a new required environment variable, or a new format or minimum for an
+  existing one (the form validates the secrets);
+- a changed listening port, health check path or health semantics, or start
+  time beyond the template's five-minute start period;
+- a required PostgreSQL major version, or an extension the stock `postgres`
+  image does not ship;
+- any other change to the compose shape: a new container, a volume the app
+  must write to, a different user.
+
+The catalog app sets `HEALTHLOG_PLATFORM=truenas`, `PORT`, `HOSTNAME`,
+`DATABASE_URL`, `ENCRYPTION_KEY`, `API_TOKEN_HMAC_KEY`, `APP_URL`,
+`NEXT_PUBLIC_APP_URL` and `SESSION_COOKIE_SECURE`; everything else reaches it
+through the form's additional environment variables. See
+`docs/self-hosting/truenas.md` for the operator side.
 
 ## Verify the served version
 
@@ -89,13 +328,31 @@ always confirm the served build after a deploy:
 ```sh
 # Asserts prod + demo serve 1.9.0, prints each target's buildSha,
 # exits non-zero on a mismatch or timeout after a bounded retry loop.
-pnpm dlx tsx scripts/assert-deploy.ts 1.9.0
+HEALTHLOG_PROD_URL=https://healthlog.example.com \
+  pnpm dlx tsx scripts/assert-deploy.ts 1.9.0
 ```
 
-Pass `--only=prod` / `--only=demo` to check a single target, or
+`HEALTHLOG_PROD_URL` is the base URL of your instance; it has no default and
+is required unless you pass `--only=demo`. Pass `--only=prod` /
+`--only=demo` to check a single target, or
 `--attempts=N --interval=ms` to widen the retry window while a slow
 pull settles.
 
+The worker loads each job's handler module on that job's first run, so a
+module the image cannot load does not stop the worker from starting. Once
+it has bound its queues, the worker loads every handler a single time in
+the background and reports each one that fails, normally within a minute
+of start. Each failure is a `job.run.failed` event at `error` with
+`reason: "handler_load_failed"` and the queue's name, and stderr also gets
+`[pg-boss] [registry] preloaded N/M job handlers; failed to load: <queues>`.
+If either shows up after a deploy, the image is broken for those queues,
+and their jobs will fail when they run. Roll back (see Rollback above)
+instead of waiting for the retries to run out:
+
+```sh
+docker compose logs --since 5m app 2>&1 | grep -E 'handler_load_failed|failed to load:'
+```
+
 ## Walk the synthetic journey
 
 The version check proves the instance serves the right build. It does not
@@ -310,29 +567,45 @@ low-friction default.
 
 ## Deploy-status webhook: replay protection
 
-`POST /api/internal/deploy-webhook` authenticates via the static
-`X-Deploy-Webhook-Secret` header. Since v1.16.4 it additionally
-enforces a freshness window: a request carrying an
-`X-Deploy-Webhook-Timestamp` header (unix seconds, unix milliseconds,
-or ISO-8601) is rejected with `401 {"status":"stale"}` when the
-timestamp lies more than **5 minutes** from server time — so a captured
-request cannot be replayed later to re-page admins or forge deploy
-outcomes in the audit log.
+`POST /api/internal/deploy-webhook` accepts two kinds of request.
 
-Two modes:
+- **Secret header.** `X-Deploy-Webhook-Secret` carries the shared secret.
+  This is what Coolify's stock notification sender can do. It does not
+  protect against a replay: anyone who captures one request holds the
+  secret and can send any request they like. An `X-Deploy-Webhook-Timestamp`
+  beside it is still checked (a stale or unparseable one is refused with
+  `401 {"status":"stale"}`), but it is covered by nothing, so treat it as a
+  staleness hint. Versions before 1.46 described it as replay protection.
+- **Signature.** `X-Deploy-Webhook-Signature: sha256=<hex>` is the
+  HMAC-SHA256, under `DEPLOY_WEBHOOK_SECRET`, of the
+  `X-Deploy-Webhook-Timestamp` value, a dot, and the exact request body. The
+  timestamp (unix seconds, unix milliseconds or ISO-8601) must lie within
+  **5 minutes** of server time. A signed request sends no secret, and a
+  captured one is useless once the window has passed.
 
-- **Default (tolerant).** Requests _without_ the header pass — Coolify's
-  stock notification sender does not attach one. A header that is
-  present but stale or unparseable is always rejected.
-- **Strict.** Set `DEPLOY_WEBHOOK_REQUIRE_TIMESTAMP=true` in the app
-  environment to make the header mandatory, closing the replay window
-  completely. Use this when the sender (or a reverse proxy in front of
-  the app) can attach the timestamp, e.g.:
+Two settings tighten this:
 
-  ```sh
-  curl -X POST https://<host>/api/internal/deploy-webhook \
-    -H "X-Deploy-Webhook-Secret: $SECRET" \
-    -H "X-Deploy-Webhook-Timestamp: $(date +%s)" \
-    -H "Content-Type: application/json" \
-    -d '{"status":"success"}'
-  ```
+- `DEPLOY_WEBHOOK_REQUIRE_TIMESTAMP=true` requires a fresh
+  `X-Deploy-Webhook-Timestamp` on a request that uses the secret header; one
+  without it is refused with `401 {"status":"stale"}`. This is what the
+  setting has always meant. It keeps an old capture out, but not someone who
+  saw the secret and sends a new request with a new timestamp.
+- `DEPLOY_WEBHOOK_REQUIRE_SIGNATURE=true` accepts signed requests only; the
+  secret header alone is refused with 401. This is the one that stops a
+  replay. Use it when the sender, or a small relay in front of the app, can
+  sign:
+
+```sh
+TS=$(date +%s)
+BODY='{"status":"success"}'
+SIG=$(printf '%s.%s' "$TS" "$BODY" \
+  | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.*= //')
+curl -X POST https://<host>/api/internal/deploy-webhook \
+  -H "X-Deploy-Webhook-Timestamp: $TS" \
+  -H "X-Deploy-Webhook-Signature: sha256=$SIG" \
+  -H "Content-Type: application/json" \
+  -d "$BODY"
+```
+
+Both may be set; a signed request satisfies both. An operator who set the
+timestamp flag before 1.46 keeps exactly the behaviour they had.

docs/ops/disaster-recovery.md

@@ -0,0 +1,240 @@
+# Disaster recovery
+
+The copy that rebuilds a lost server is the database dump. This page says
+what is dumped and where it goes, which keys a restore needs, how to restore
+onto a new server, and how the procedure is tested.
+
+## What is backed up, and where
+
+| Copy                    | When                                                                        | Where                                                                                 | Kept                            |
+| ----------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------- |
+| Nightly dump            | 01:30 Europe/Berlin, the zone every schedule runs in (`DB_BACKUP_SCHEDULE`) | `DB_BACKUP_DIR`, the `backups` volume of the bundled compose file                     | the newest 7 (`DB_BACKUP_KEEP`) |
+| Pre-migration dump      | on start, when the new image brings migrations, before them                 | the same directory                                                                    | the newest 2                    |
+| Off-host copy of a dump | right after each nightly dump, if the bucket is configured                  | your bucket, under `database/<host of APP_URL>/`, sealed with `BACKUP_ENCRYPTION_KEY` | your bucket's lifecycle rule    |
+
+A dump is `pg_dump --format=custom` of the whole database: every account,
+sign-ins, passkeys, sharing grants and managed profiles, documents, the job
+queue and the instance settings. It is two files:
+
+- `healthlog-<UTC time>-<daily|pre-migration>.dump`, the archive;
+- `healthlog-<UTC time>-<daily|pre-migration>.manifest.json` beside it: the
+  app version and build, the newest applied migration, the Postgres version,
+  the archive's size and SHA-256, the row count of every table, and the
+  fingerprints (never the values) of the keys the database needs.
+
+A dump counts as good only when both files exist under their final names. The
+archive is written as `.partial`, read back with `pg_restore --list`, and
+renamed after its manifest; a run that fails leaves nothing that looks good.
+The admin backups page shows the newest good dump, where it is, and the
+newest failed run. The start log says on every boot where dumps go, or that
+none can be kept.
+
+Local dumps are not encrypted. They sit beside the database volume, in the
+same trust zone: whoever can read one volume can read the other. The columns
+HealthLog encrypts stay encrypted inside the dump, under `ENCRYPTION_KEYS`.
+Keep a copy of the dumps off the host; the off-host bucket does that for you,
+and it seals each copy with `BACKUP_ENCRYPTION_KEY` in the envelope the
+per-account copies use.
+
+A dump holds every account that existed when it was taken, including one
+deleted since. Deleted accounts leave the dumps as they age out: after
+`DB_BACKUP_KEEP` nights on the server, and after your lifecycle rule in the
+bucket. A pre-migration dump goes once it is older than every nightly dump
+kept, except the one taken before the latest update: that one is the way back
+from it and stays until the next update writes a newer one. On an install
+that rarely updates, delete it by hand once you no longer want the way back,
+or state that exception with the retention period. Give that rule a prefix that covers `database/` too; the admin
+backups page reads the bucket's rules and says when none does, and the
+recovery readiness card calls it attention and tells the admins once. This is the
+retention period to state where you tell people that deleting their account
+deletes their data.
+
+A dump is kept on the server only when `DB_BACKUP_DIR` survives the container
+being replaced: a mounted volume or bind mount, or any writable directory when
+HealthLog does not run in a container. The image creates the default
+directory, so an install that runs it without the `backups` volume can write
+there, but the directory sits in the container's own layer and the next update
+throws it away. HealthLog reads the container's mount table to tell the two
+apart and treats such a directory, or one on a tmpfs, like one it cannot
+write: the nightly dump is uploaded off-host and nothing is kept on the
+server, and no dump is taken before migrations; with no bucket either, no
+dump is taken at all. The start log, the admin backups page and the recovery
+readiness card say so.
+
+The per-account copies (the weekly in-database copy, the nightly per-account
+objects) roll one account back on the same server. They cannot rebuild a
+server; see [`backup-restore.md`](backup-restore.md).
+
+## The keys a restore needs
+
+| Key                                                                 | Without it                                                                                                                              |
+| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `ENCRYPTION_KEYS` + `ENCRYPTION_ACTIVE_KEY_ID`, or `ENCRYPTION_KEY` | Nothing encrypted can be read. The restore refuses when the active key is missing or different. Keep every retired id still in the map. |
+| `API_TOKEN_HMAC_KEY`                                                | No data is lost, but every session, app token and share link stops working; people sign in again and re-create tokens.                  |
+| `BACKUP_ENCRYPTION_KEY` (and `BACKUP_ENCRYPTION_PREVIOUS_KEYS`)     | Off-host copies do not open.                                                                                                            |
+| `POSTGRES_PASSWORD`                                                 | Not needed: a new server can use a new one.                                                                                             |
+
+The restore compares the keys in its environment with the fingerprints in the
+manifest before it writes anything, and names each key that is missing or
+different.
+
+## Restore onto a new server
+
+1. Install Docker and take the `docker-compose.yml` of the version that wrote
+   the dump or a newer one. The manifest's `appVersion` names it; to run that
+   exact version set `HEALTHLOG_IMAGE_REF=:v<version>` in `.env`.
+2. Write `.env` with the keys from your records (see above) and a new
+   `POSTGRES_PASSWORD`.
+3. Do not run `docker compose up` yet. The app would create an empty schema,
+   and the restore only writes into a database with no tables. Start only the
+   database:
+
+   ```bash
+   docker compose up -d db
+   ```
+
+4. Restore. When the host is lost, its local dumps went with it, and the
+   copy is the one in your bucket: put the `BACKUP_S3_*` variables and
+   `BACKUP_ENCRYPTION_KEY` (with any `BACKUP_ENCRYPTION_PREVIOUS_KEYS`) in
+   `.env` as on the old server, then
+
+   ```bash
+   docker compose run --rm db-restore list --from-bucket
+   docker compose run --rm db-restore latest --from-bucket
+   ```
+
+   `latest --from-bucket` downloads the newest dump of this instance whose
+   manifest is in the bucket too, opens both with `BACKUP_ENCRYPTION_KEY`
+   and restores. Name a dump instead of `latest` to take an older one.
+   Each instance uploads under its own folder, `database/<host of APP_URL>/`,
+   so set `APP_URL` as on the old server. A bucket shared with another
+   instance holds its dumps too: `latest` refuses rather than take one of
+   those, and `list --from-bucket` marks them. To restore one on purpose
+   (after moving to a new domain, the old one), add
+   `--instance=<old host>`, or name the dump by its full key,
+   `database/<host>/healthlog-….dump.enc`.
+
+   The opened copy is a whole database, decrypted, in a scratch directory
+   beside the backups. The restore removes it when it ends, on Ctrl-C and
+   `docker compose stop` too. One left by a restore that was killed outright
+   is removed when the next restore starts, and by the nightly retention.
+
+   With the files in hand instead (copied off the host, or downloaded from
+   the bucket with your own tools: both `<name>.dump.enc` and
+   `<name>.manifest.json.enc`, or a `.dump` with its `.manifest.json`), put
+   them in a directory such as `./restore`, make them readable for the
+   container (`chmod a+r restore/*`) and name the dump:
+
+   ```bash
+   docker compose run --rm -v "$PWD/restore:/restore:ro" db-restore list /restore
+   docker compose run --rm -v "$PWD/restore:/restore:ro" db-restore \
+     /restore/healthlog-20261024T233000Z-daily.dump
+   ```
+
+   Either way it checks the archive against the manifest's SHA-256, the keys
+   against the manifest's fingerprints, and that the database is empty. Then
+   it restores in one transaction, gathers planner statistics and counts
+   every table against the manifest. A count that differs empties the
+   database again and fails. Wait for the line that starts with `Restored`.
+
+5. Start the stack and check it:
+
+   ```bash
+   docker compose up -d
+   curl -s http://localhost:3000/api/health
+   ```
+
+   Sign in. The app's own key check runs at start and refuses to serve on a
+   key that does not open the data.
+
+The restore runs as the owner `DATABASE_URL` names, and the restored tables
+belong to it. The app connects as its own role,
+`healthlog_app_<database>_<hash>`
+([database-role.md](../self-hosting/database-role.md)): the start in step 5
+grants that role the restored tables, the queue's included, before the app
+runs; the queue schema stays the owner's. A dump carries grants to the role;
+`db-restore` leaves them out (`--no-owner --no-privileges`). Restoring with `pg_restore` by hand, pass
+the same two flags, or it fails on a database without the role.
+
+When the dumps are still in the server's `backups` volume (the database
+volume was lost, the backups volume was not), step 4 is
+`docker compose run --rm db-restore latest`.
+
+`--ignore-key-mismatch` restores although the active encryption key differs.
+Use it only when that key is lost for good: everything encrypted stays
+unreadable.
+
+## Going back to before a migration
+
+The entrypoint dumps the database before it applies migrations. To return to
+that state (the previous image, the data as it was before the update):
+
+```bash
+docker compose stop app
+# Keep the current state too, in case it is wanted later.
+docker compose exec -T db pg_dump -U healthlog -Fc healthlog > healthlog-current.dump
+docker compose exec db dropdb -U healthlog healthlog
+docker compose exec db createdb -U healthlog healthlog
+docker compose run --rm db-restore list
+docker compose run --rm db-restore healthlog-<time>-pre-migration.dump
+# Set HEALTHLOG_IMAGE_REF in .env to the version you ran before the update.
+docker compose up -d
+```
+
+The dump before a migration is taken while the new image starts. If it fails
+on a directory that keeps it (a full disk, most often), the start stops before
+anything is migrated and the log names the switch: `DB_BACKUP_BEFORE_MIGRATE=false`
+starts without it, once.
+
+## Knowing the copies are there
+
+Nobody opens the backups page until the day it matters, so the server tells
+the admins instead:
+
+- The **Recovery readiness** card, on the admin overview and on Admin,
+  Backups, judges every copy in one verdict each: the database dump (fresh,
+  failed, or kept nowhere that survives the container), the weekly account
+  copies, the off-host copies, the last restore drill, whether the bucket is
+  set up, whether its lifecycle rule ever removes the dumps under
+  `database/`, and the recovery kit.
+- The **recovery kit** under Admin, Encryption lists every key a restore
+  needs (the table above), by id and fingerprint, and lets an admin check a
+  saved copy and confirm it. It is due again after any key change.
+- An hourly check sends each admin a **Backup health** notification
+  (`BACKUP_HEALTH`) when a signal on the card turns to needs attention or at
+  risk, a reminder once a day while one stays at risk, and one more when it
+  recovers. Each admin chooses the channels for it under Notifications.
+
+[Getting started](../self-hosting/getting-started.md#save-the-recovery-kit)
+walks through saving the kit.
+
+## How this is tested
+
+`scripts/compose-dr-drill.sh` plays this page against real containers: it
+builds the image, seeds several accounts (the demo account with documents
+and encrypted notes, a Guardian with a managed profile), lets the scheduled
+job take the dump and upload it to an S3-compatible bucket, destroys every
+volume of the stack (the local dumps included), and restores on a new stack
+given only the bucket and the keys
+(`docker compose run --rm db-restore latest --from-bucket`). A second run
+restores from the dump files instead (`DRILL_SOURCE=local`). Both then count
+every table against the manifest and boot the app: health, sign-in, an
+encrypted note read back, a document opened, the Guardian still seeing the
+profile. It runs in CI nightly and on every change to the
+compose file, the image or the dump and restore code
+(`.github/workflows/compose-dr-drill.yml`), and it is checked to fail on a
+wrong encryption key, a wrong off-host key, a dump that lost a table's rows
+and a target that is not empty.
+
+Test your own copies too: once, and after any change to how the server is
+run, restore last night's dump on a spare machine with the steps above.
+
+## Settings
+
+| Variable                   | Default                      | What it does                                                                                                                                |
+| -------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DB_BACKUP_ENABLED`        | on                           | `false` stops the nightly dump.                                                                                                             |
+| `DB_BACKUP_DIR`            | `/var/lib/healthlog/backups` | Where dumps are written and read. Change it only together with the volume mount.                                                            |
+| `DB_BACKUP_SCHEDULE`       | `30 1 * * *`                 | Five-field cron, Europe/Berlin time like every HealthLog schedule.                                                                          |
+| `DB_BACKUP_KEEP`           | `7`                          | Nightly dumps kept (at least 1). Up to two pre-migration dumps are kept besides, none older than the oldest nightly dump except the newest. |
+| `DB_BACKUP_BEFORE_MIGRATE` | on                           | `false` starts an update without the dump before its migrations.                                                                            |

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
@@ -103,6 +103,13 @@ under `v1` (the synthetic id assigned to the existing `ENCRYPTION_KEY`).
    a full `Columns walked` line. Both read the same registry the rotation
    walks.
 
+   A run that walked every column without an error also removes the boot
+   key check's record of each previous key id that no longer holds a single
+   value (`encryption_key_canaries`); the script prints which ids it removed
+   and, for an id that still holds values, the columns that do. With the record
+   gone, the id can later carry a different key without the start-up check
+   refusing it.
+
    A zero only means "nothing left" when the run also says it walked every
    registered column. A zero from a run that skipped columns means "never
    looked", and dropping the old key on it makes those rows permanently
@@ -130,10 +137,15 @@ under `v1` (the synthetic id assigned to the existing `ENCRYPTION_KEY`).
 > So before step 4, also check **Admin → Encryption → Keys the backups still
 > need**. It lists, per key id, the stored copies that need it with the oldest
 > date, and when the last off-host copy needing it expires under the bucket's
-> lifecycle rule. Keep the old key in `ENCRYPTION_KEYS` until it is no longer
-> listed there (the weekly copy replaces itself within a week; delete old
-> uploaded copies you no longer want, and wait out the off-host retention), or
-> accept that those copies cannot be restored. Copies written before v1.39.3
+> lifecycle rule. The database dumps are listed too: a dump is restored only
+> with the key that was active when it was taken (`db-restore` refuses
+> without it), so the old key stays listed while a nightly or pre-migration
+> dump taken under it is on this server, and until the bucket's rule for
+> `database/` has expired the off-host copies. Keep the old key in
+> `ENCRYPTION_KEYS` until it is no longer listed there (the weekly copy
+> replaces itself within a week; delete old uploaded copies you no longer
+> want, and wait out the dump and off-host retention), or accept that those
+> copies cannot be restored. Copies written before v1.39.3
 > did not record their keys and are listed as such: treat them as needing
 > every key that existed when they were written.
 >

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,275 @@
+# 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**: a database dump, as in
+  [Updates](../self-hosting/getting-started.md#updates), 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 '__Host-healthlog_session=<session>' \
+  -d '{"vacuum": true, "reindex": true}'
+```
+
+On a plain-HTTP install the cookie is named `healthlog_session`.
+
+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, as a factor such as
+1.3; `bloat_percent` in the job result, as whole percent such as 130, because a
+job fact is a whole number). 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/retired-measurement-indexes.mjs`. 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";
+```
+
+When the app connects as its restricted role
+([database-role.md](../self-hosting/database-role.md)), the job may vacuum and
+rebuild (`MAINTAIN`) but not drop: `DROP INDEX` belongs to the table's owner.
+A run then skips the drops, of retired indexes and of the invalid copy a
+failed rebuild leaves, names what it found under
+`maintenance_drops_left_for_boot` with a warning, and the next start drops
+each as the owner with `DROP INDEX CONCURRENTLY`, waiting at most five
+seconds. Until then a failed rebuild's copy holds its disk; restart the
+container, or drop it by hand as the owner with the statement above.
+
+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/postgres-major-upgrade.md

@@ -0,0 +1,168 @@
+# Moving the database to a newer Postgres major
+
+From v1.46 the compose file runs Postgres 18. Installs from v1.45 or earlier
+ran 16, and a major version cannot open the data directory of an older one,
+so the compose file carries a one-time step that moves the database across
+on the first start after the update. Nothing needs doing by hand on a stack
+that runs the project's `docker-compose.yml`.
+
+Installs that bring their own Postgres (Unraid, an existing database server)
+are not touched: HealthLog runs on 16 and 18 alike, and the move there is
+yours to schedule with the steps under [By hand](#by-hand).
+
+## What happens on the first start
+
+`db-upgrade` is a short-lived container next to `db`. It starts after the new
+Postgres 18 database is up and before the app, and it exits in a second when
+there is nothing to move. When the old `pgdata` volume holds a Postgres 16
+database and the new one is empty, it:
+
+1. checks that the database service runs Postgres 18, and that there is room
+   on the disk for a second copy and for the dump the app takes before its
+   first migration;
+2. starts Postgres 16 inside its own container on the old volume, reachable
+   only from inside that container;
+3. streams a dump into Postgres 18 in a single transaction;
+4. compares the row count of every table between the two;
+5. gathers the planner statistics, which a restore does not carry;
+6. stops Postgres 16 and leaves a marker file on the old volume.
+
+The app starts once that succeeded, applies the release's migrations and
+serves as before. On a typical personal record the whole move takes seconds;
+a database of a few gigabytes takes a few minutes. Watch it with
+`docker compose logs -f db-upgrade`.
+
+If any step fails, the new database stays empty, the app does not start, and
+the log says what happened. A move cut short by a restart or a full disk is
+run again from scratch on the next `docker compose up -d`.
+
+The old `pgdata` volume keeps the database as it was. Postgres 16 runs on it
+during the move, so it writes a checkpoint there (and recovers first after an
+unclean stop), and the marker file is added; no data in it changes. That is
+the way back.
+
+## Going back
+
+Stop the stack, put the two lines of the `db` service back the way v1.45 had
+them, and start it with the v1.45 image:
+
+```yaml
+db:
+  image: postgres:16.15-alpine
+  volumes:
+    - pgdata:/var/lib/postgresql/data
+```
+
+```bash
+docker compose down
+HEALTHLOG_IMAGE_REF=:v1.45.0 docker compose up -d
+```
+
+Anything written after the move lives only in the Postgres 18 volume.
+`db-upgrade` can stay in the file: it sees that the database service runs
+Postgres 16 and leaves that volume alone. This also holds after a move that
+stopped half-way.
+
+## Updating again after going back
+
+If you used Postgres 16 again after going back, the Postgres 18 volume holds
+the state of the day of the move, not what you wrote since. `db-upgrade`
+notices that the old database changed after the move and refuses to start on
+the old copy. To move the current 16 database, remove the old copy and the
+marker, then start again:
+
+```bash
+docker compose down
+docker volume rm <project>_postgres-data
+docker compose run --rm --entrypoint rm db-upgrade \
+  /var/lib/postgresql/data/HEALTHLOG_MOVED_TO_POSTGRES_18
+docker compose up -d
+```
+
+`docker volume ls` shows the volume's full name. Removing it deletes what was
+written on Postgres 18 before you went back; take a dump of it first if any
+of that matters.
+
+## Afterwards
+
+Keep the old volume until the new database has run for a while, then remove
+it. It is a complete copy of the database as it stood before the move, and
+nothing that happens afterwards reaches it: an account deleted, a document
+purged from the trash, or a key rotated after a leak is still there in the
+old volume, and so is everything else for anyone who can read the host's
+Docker volumes. Removing it is part of the move, not optional tidying.
+`docker volume ls` shows its full name, prefixed with the compose project:
+
+```bash
+docker volume rm <project>_pgdata
+```
+
+`db-upgrade` then finds nothing to move. A later release drops the service
+and the `pgdata` line.
+
+## Starting over
+
+When the move has run and the Postgres 18 volume is empty again (deleted by
+hand, say), `db-upgrade` refuses to import the old state a second time, since
+that would quietly bring back the database as it was on the day of the move.
+To do exactly that on purpose, remove the marker and start again:
+
+```bash
+docker compose run --rm --entrypoint rm db-upgrade \
+  /var/lib/postgresql/data/HEALTHLOG_MOVED_TO_POSTGRES_18
+docker compose up -d
+```
+
+## By hand
+
+For a Postgres you run yourself, or a compose file you have changed so much
+that the step does not fit, the move is a dump and a restore. Take the
+encryption key's copy out of its safe place first: the dump is unreadable
+without it, and this is the moment you would find out.
+
+```bash
+# 1. Stop the app so nothing writes while the dump runs (and app-worker, if
+#    you run the worker role in its own container).
+docker compose stop app
+
+# 2. Dump the database in Postgres' custom format.
+docker compose exec -T db pg_dump -U healthlog -Fc healthlog \
+  > healthlog-pg16-$(date +%F).dump
+
+# 3. Stop the old database. Its volume stays untouched.
+docker compose stop db
+```
+
+4. Point the `db` service at Postgres 18 and a fresh volume. From 18 on, the
+   image keeps its data under `/var/lib/postgresql/18/docker` and expects the
+   volume mounted one level up, at `/var/lib/postgresql`; mounted at
+   `.../data` it refuses to start with "there appears to be PostgreSQL data
+   in: /var/lib/postgresql/data".
+
+```bash
+# 5. Start the new database and restore the dump into it.
+docker compose up -d db
+docker compose exec -T db pg_restore -U healthlog -d healthlog --no-owner \
+  < healthlog-pg16-<date>.dump
+
+# 6. Gather the planner statistics. A restore brings the rows but not the
+#    statistics, and until autovacuum gets round to every table the planner
+#    guesses at their sizes, which can turn a sub-second page into one that
+#    takes many seconds.
+docker compose exec -T db vacuumdb -U healthlog -d healthlog --analyze-in-stages
+
+# 7. Start the app and confirm it.
+docker compose up -d app
+curl -s http://localhost:3000/api/version
+```
+
+The start log should say there are no pending migrations beyond the release's
+own: the dump carried the migration history with it.
+
+If you had run `CREATE EXTENSION pg_stat_statements;` for
+[query statistics](query-statistics.md), the dump carries it and the compose
+`command:` still loads the library, so nothing needs doing there.
+
+`pg_upgrade --link` is faster on a very large database, but it needs both
+majors' binaries in one container; for a personal health record the dump is
+seconds to minutes and has nothing to set up.

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.