From 9941db15497c1f10ef8d36d5d339cb9d66db5aaf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Wed, 21 Oct 2026 19:24:21 +0200
Subject: [PATCH 1/8] refactor(insights): drop the readable cached-text column

Every write has gone to insights_cached_text_encrypted since 0411, and
the boot-time free-text backfill sealed the rows written before it.
Migration 0430 drops insights_cached_text and the backfill index that
served it. A host that skipped the intervening releases loses only a
cache of model output; the next warm writes a fresh, sealed payload.

The cipher module now reads and writes the sealed column only, the
backfill job loses its insights step, and consent withdrawal, the wipe
plan, the backup plan and the session projection follow the schema.
Backups never carried the column, and restore ignores unknown account
settings; a round-trip test now proves an old backup naming the field
still restores cleanly. The access guard pins exact counts for where
the sealed name may appear. Fixtures, the demo seed and the demo
migration script seed the sealed column instead of plaintext.
---
 e2e/setup/ai-optional-fixture.ts              |  10 +-
 e2e/setup/global-setup.ts                     |   2 +-
 .../migration.sql                             |  15 ++
 prisma/schema.prisma                          |   9 +-
 scripts/migrate-demo-edge01.sh                |   4 +-
 scripts/seed-demo.ts                          |   4 +-
 .../insights-cached-text-access-guard.test.ts |  64 +++----
 .../session-user-projection-guard.test.ts     |   2 +-
 .../__tests__/route-module-gate.test.ts       |   1 -
 src/app/api/daily/digest/route.ts             |   2 +-
 src/app/api/dashboard/snapshot/route.ts       |   2 +-
 .../health-record/__tests__/route.test.ts     |   2 +-
 .../insights/generate/__tests__/route.test.ts | 159 +++++++++++-------
 src/app/api/insights/generate/route.ts        |   2 +-
 .../insights/use-insights-advisor.ts          |   4 +-
 src/lib/auth/session-user.ts                  |   4 +-
 src/lib/consent/withdrawal.ts                 |   2 +-
 src/lib/daily/digest.ts                       |   2 +-
 src/lib/daily/load-digest.ts                  |   2 +-
 .../snapshot-read-briefing-capability.test.ts |  12 +-
 .../snapshot-read-briefing-today.test.ts      |  16 +-
 src/lib/dashboard/snapshot.ts                 |   4 +-
 src/lib/data-wipe/wipe-plan.ts                |   1 -
 .../restore-backup-round-trip.test.ts         |  37 +++-
 src/lib/export/backup-plan.ts                 |   1 -
 .../__tests__/cached-text-cipher.test.ts      |  38 +----
 ...ensive-briefing-grounding-disposal.test.ts |   9 +-
 .../comprehensive-briefing-reroll.test.ts     |  11 +-
 .../comprehensive-budget-refusal.test.ts      |   2 +-
 .../comprehensive-generate-force.test.ts      |  49 ++++--
 .../comprehensive-json-retry.test.ts          |   2 +-
 .../comprehensive-outbound-repair.test.ts     |   2 +-
 .../comprehensive-plan-progress.test.ts       |   2 +-
 .../comprehensive-privacy-flip.test.ts        |  23 ++-
 .../comprehensive-timeout-honored.test.ts     |   4 +-
 .../comprehensive-warm-timeout.test.ts        |   2 +-
 src/lib/insights/briefing-failure-marker.ts   |   2 +-
 src/lib/insights/cached-text-cipher.ts        |  75 +++------
 src/lib/insights/comprehensive-generate.ts    |   2 +-
 .../free-text-encryption-backfill.test.ts     |  99 -----------
 src/lib/jobs/free-text-encryption-backfill.ts |  63 +------
 .../profile/__tests__/health-facts.test.ts    |   4 -
 tests/integration/ai-optional-actions.test.ts |   9 +-
 .../ai-optional-mixed-routes.test.ts          |  11 +-
 .../integration/briefing-cache-locale.test.ts |  11 +-
 .../consent-withdrawal-purge.test.ts          |   9 +-
 .../free-text-encryption-backfill.test.ts     |  79 +++------
 .../insights-provider-chain.test.ts           |   2 +-
 tests/integration/sharing-front-door.test.ts  |   5 +-
 49 files changed, 381 insertions(+), 497 deletions(-)
 create mode 100644 prisma/migrations/0430_drop_insights_cached_text/migration.sql

diff --git a/e2e/setup/ai-optional-fixture.ts b/e2e/setup/ai-optional-fixture.ts
index 4a417d3e1..3b930fc38 100644
--- a/e2e/setup/ai-optional-fixture.ts
+++ b/e2e/setup/ai-optional-fixture.ts
@@ -54,7 +54,7 @@ export async function resetAiOptionalAccount(): Promise<void> {
       `UPDATE users SET
          ai_provider = NULL,
          ai_base_url = NULL,
-         insights_cached_text = NULL,
+         insights_cached_text_encrypted = NULL,
          insights_cached_at = NULL,
          insights_cached_locale = NULL,
          disable_coach = false
@@ -80,16 +80,20 @@ export async function seedStoredBriefing(marker: string): Promise<void> {
     // Generated now: only text written today is served as today's read.
     briefingGeneratedAt: new Date().toISOString(),
   };
+  // Sealed the way the app writes it; there is no readable column to seed.
+  const { sealInsightsCachedText } =
+    await import("@/lib/insights/cached-text-cipher");
+  const sealed = Buffer.from(sealInsightsCachedText(JSON.stringify(insights)));
   await withAccount(async (pool, userId) => {
     await pool.query(
       `UPDATE users SET
          ai_provider = 'LOCAL',
          ai_base_url = 'http://127.0.0.1:9/v1',
-         insights_cached_text = $2,
+         insights_cached_text_encrypted = $2,
          insights_cached_at = now(),
          insights_cached_locale = 'en'
        WHERE id = $1`,
-      [userId, JSON.stringify(insights)],
+      [userId, sealed],
     );
     await pool.query(
       `INSERT INTO consent_receipts (id, user_id, kind, artefact, signed_at)
diff --git a/e2e/setup/global-setup.ts b/e2e/setup/global-setup.ts
index 3d4b74cf9..faf10ceb1 100644
--- a/e2e/setup/global-setup.ts
+++ b/e2e/setup/global-setup.ts
@@ -802,7 +802,7 @@ export default async function globalSetup(config: FullConfig): Promise<void> {
          codex_connected_at = NULL,
          codex_connection_status = 'disconnected',
          insights_cached_at = NULL,
-         insights_cached_text = NULL,
+         insights_cached_text_encrypted = NULL,
          onboarding_completed_at = EXCLUDED.onboarding_completed_at,
          onboarding_tour_completed = EXCLUDED.onboarding_tour_completed,
          module_preferences_json = EXCLUDED.module_preferences_json,
diff --git a/prisma/migrations/0430_drop_insights_cached_text/migration.sql b/prisma/migrations/0430_drop_insights_cached_text/migration.sql
new file mode 100644
index 000000000..39724eb38
--- /dev/null
+++ b/prisma/migrations/0430_drop_insights_cached_text/migration.sql
@@ -0,0 +1,15 @@
+-- Drop the readable copy of the cached AI insights payload.
+--
+-- Since 0411 every write goes to `insights_cached_text_encrypted` and leaves
+-- `insights_cached_text` NULL, and the boot-time free-text encryption backfill
+-- sealed the rows written before. Nothing reads the readable column any more.
+--
+-- A host that skipped the releases between 0411 and this one may still hold a
+-- readable payload the backfill never reached. It is a cache of model output,
+-- not a record: the next nightly or on-demand warm writes a fresh, sealed one.
+-- Dropping it is the safe direction; keeping it would leave health text in the
+-- clear on exactly the hosts that upgraded the longest way round.
+
+DROP INDEX IF EXISTS "users_insights_cached_text_backfill_idx";
+
+ALTER TABLE "users" DROP COLUMN IF EXISTS "insights_cached_text";
diff --git a/prisma/schema.prisma b/prisma/schema.prisma
index 1d79d97b1..61e9e8270 100644
--- a/prisma/schema.prisma
+++ b/prisma/schema.prisma
@@ -136,13 +136,6 @@ model User {
   useCentralCodex             Boolean   @default(false) @map("use_central_codex")
   insightsPrivacyMode         String    @default("aggregated") @map("insights_privacy_mode") // "aggregated" | "raw"
   insightsCachedAt            DateTime? @map("insights_cached_at")
-  /// @internal: legacy plaintext cache of the AI insights payload, read only
-  /// as a fallback for rows the free-text encryption backfill has not reached
-  /// yet (v1.43.7). Every write since then goes to `insightsCachedTextEncrypted`
-  /// and leaves this NULL; the backfill seals and nulls it on the old rows.
-  /// DROP this column in a later release, once the backfill reports zero
-  /// remaining rows on every instance.
-  insightsCachedText          String?   @map("insights_cached_text")
   /// v1.43.7 — the cached AI insights payload (briefing, per-domain readings,
   /// recommendations; JSON), AES-256-GCM binary layout under
   /// `INSIGHTS_CACHED_TEXT_AAD`. Read and written only through
@@ -6701,7 +6694,7 @@ model HostMetric {
 // (no prompt-tuning flow yet — that ratchet is v1.4.17).
 //
 // Privacy: server-side fills providerType + promptVersion from the
-// user's most recent cached payload (User.insightsCachedText) so the
+// user's most recent cached payload (User.insightsCachedTextEncrypted) so the
 // client can't tamper with the attribution.
 //
 // `(userId, recommendationId, recommendationText)` is the dedup key.
diff --git a/scripts/migrate-demo-edge01.sh b/scripts/migrate-demo-edge01.sh
index 228e94714..d623229f0 100755
--- a/scripts/migrate-demo-edge01.sh
+++ b/scripts/migrate-demo-edge01.sh
@@ -327,7 +327,7 @@ readonly USERS_COLS="id, username, email, password_hash, role, created_at, updat
   height_cm, date_of_birth, gender, timezone,
   codex_access_token_encrypted, codex_refresh_token_encrypted, codex_token_expires_at,
   codex_connected_at, codex_connection_status,
-  insights_privacy_mode, insights_cached_at, insights_cached_text, insights_cached_text_encrypted,
+  insights_privacy_mode, insights_cached_at, insights_cached_text_encrypted,
   insights_exclude_metrics,
   global_excluded_injection_sites,
   telegram_bot_token, telegram_chat_id, telegram_enabled,
@@ -360,7 +360,7 @@ readonly USERS_SELECT="id, username, email, password_hash,
   NULL::timestamptz AS codex_token_expires_at,
   NULL::timestamptz AS codex_connected_at,
   'disconnected' AS codex_connection_status,
-  insights_privacy_mode, insights_cached_at, insights_cached_text, insights_cached_text_encrypted,
+  insights_privacy_mode, insights_cached_at, insights_cached_text_encrypted,
   insights_exclude_metrics,
   global_excluded_injection_sites,
   NULL::text  AS telegram_bot_token,
diff --git a/scripts/seed-demo.ts b/scripts/seed-demo.ts
index aad6f50f2..2479d4cf3 100644
--- a/scripts/seed-demo.ts
+++ b/scripts/seed-demo.ts
@@ -3555,15 +3555,13 @@ async function seed() {
     await client.query(
       `UPDATE users
          SET insights_cached_text_encrypted = $2,
-             insights_cached_text = NULL,
              insights_cached_at = NOW(),
              insights_snapshot_hash = $3,
              insights_briefing_reroll_date = $4
        WHERE id = $1`,
       [
         userId,
-        // Sealed like every write since v1.43.7; the app never reads the
-        // readable column while a ciphertext is there.
+        // Sealed like every write since v1.43.7.
         Buffer.from(
           sealInsightsCachedText(JSON.stringify(comprehensiveInsight)),
         ),
diff --git a/src/__tests__/insights-cached-text-access-guard.test.ts b/src/__tests__/insights-cached-text-access-guard.test.ts
index f5cff3900..f3bd38ee4 100644
--- a/src/__tests__/insights-cached-text-access-guard.test.ts
+++ b/src/__tests__/insights-cached-text-access-guard.test.ts
@@ -1,18 +1,16 @@
 /**
  * The cached AI insights payload is read and written in one place.
  *
- * Since v1.43.7 the payload is sealed in `User.insightsCachedTextEncrypted`
- * and the readable `insightsCachedText` survives only as a fallback for rows
- * the backfill has not reached. Two columns that must move together are a
- * standing invitation to move one: a clear written as
- * `{ insightsCachedText: null }` — the shape every clear had until this
- * release — would now leave the whole sealed briefing behind, after a consent
- * withdrawal of all places. So the names are spelled in
- * `src/lib/insights/cached-text-cipher.ts`, and every other file goes through
- * its select, write, clear and open helpers.
+ * The payload is sealed in `User.insightsCachedTextEncrypted`; the readable
+ * `insightsCachedText` column it replaced was dropped in v1.44.0 (migration
+ * 0430). Every reader and writer goes through
+ * `src/lib/insights/cached-text-cipher.ts` (its select, write, clear and open
+ * helpers), so a clear cannot forget the column and a read cannot skip the
+ * decryption. The column name is spelled there and in the tables that have
+ * to name every column of the row.
  *
- * The allowlist below is the set of files with a reason to spell the legacy
- * name anyway, each stated. A file that joins it has to say why here.
+ * The readable name survives only as the snapshot builder's input field, which
+ * carries the OPENED text, never the column.
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -23,42 +21,46 @@ import { stripComments, walkSourceFiles } from "./helpers/source-files";
 
 const SRC = join(process.cwd(), "src");
 
-const ALLOWED: Readonly<Record<string, string>> = {
-  "lib/insights/cached-text-cipher.ts": "the one module that owns the columns",
-  "lib/jobs/free-text-encryption-backfill.ts":
-    "the backfill that seals the legacy column",
+const SEALED_ALLOWED: Readonly<Record<string, string>> = {
+  "lib/insights/cached-text-cipher.ts": "the one module that owns the column",
+  "lib/crypto/encrypted-columns.ts":
+    "the registry of every ciphertext-bearing column",
   "lib/export/backup-plan.ts":
     "the backup classification names every User column",
-  "lib/data-wipe/wipe-plan.ts":
-    "the wipe reset names every User column it resets, and resets both",
+  "lib/data-wipe/wipe-plan.ts": "the wipe reset names every User column",
+};
+
+const OPENED_TEXT_ALLOWED: Readonly<Record<string, string>> = {
   "lib/dashboard/snapshot.ts":
-    "the snapshot builder's input field carries the OPENED text, not the column",
+    "the snapshot builder's input field carries the opened text",
   "lib/dashboard/snapshot-read.ts":
     "fills that input field from openInsightsCachedText",
 };
 
-/** The legacy name, not its sealed sibling, outside comments. */
-const LEGACY_NAME = /\binsightsCachedText\b(?!Encrypted)/;
+const SEALED_NAME = /\binsightsCachedTextEncrypted\b/;
+/** The dropped readable name, not its sealed sibling. */
+const READABLE_NAME = /\binsightsCachedText\b(?!Encrypted)/;
 
-function filesSpellingTheLegacyName(): string[] {
+function sourceFilesMatching(pattern: RegExp): string[] {
   return walkSourceFiles(SRC, { floor: 2000 })
     .filter((f) => !f.startsWith("generated/"))
     .filter((f) => !f.includes("__tests__/") && !/\.test\.tsx?$/.test(f))
     .filter((f) =>
-      LEGACY_NAME.test(stripComments(readFileSync(join(SRC, f), "utf8"))),
-    );
+      pattern.test(stripComments(readFileSync(join(SRC, f), "utf8"))),
+    )
+    .sort();
 }
 
 describe("insights cache column access", () => {
-  const found = filesSpellingTheLegacyName();
-
-  it("is confined to the cipher module and the stated exceptions", () => {
-    const strays = found.filter((f) => !(f in ALLOWED));
-    expect(strays).toEqual([]);
+  it("spells the sealed column only in the cipher module and the stated tables", () => {
+    const found = sourceFilesMatching(SEALED_NAME);
+    expect(found.length).toBe(4);
+    expect(found).toEqual(Object.keys(SEALED_ALLOWED).sort());
   });
 
-  it("still finds every stated exception, so the matcher is live", () => {
-    expect(found.length).toBeGreaterThan(5);
-    expect([...found].sort()).toEqual(Object.keys(ALLOWED).sort());
+  it("uses the readable name only for the opened text the snapshot builder takes", () => {
+    const found = sourceFilesMatching(READABLE_NAME);
+    expect(found.length).toBe(2);
+    expect(found).toEqual(Object.keys(OPENED_TEXT_ALLOWED).sort());
   });
 });
diff --git a/src/__tests__/session-user-projection-guard.test.ts b/src/__tests__/session-user-projection-guard.test.ts
index 36a64c618..ad62e0f7d 100644
--- a/src/__tests__/session-user-projection-guard.test.ts
+++ b/src/__tests__/session-user-projection-guard.test.ts
@@ -127,7 +127,7 @@ describe("SESSION_USER_SELECT leaves out bytes and secrets", () => {
 
   it("selects no credential, secret or large cached text", () => {
     const secretShaped =
-      /Encrypted$|^passwordHash$|^totpSecret|^totpLastStep$|^telegramBotToken$|^insightsCachedText$|^environmentAqHistoryJson$/;
+      /Encrypted$|^passwordHash$|^totpSecret|^totpLastStep$|^telegramBotToken$|^environmentAqHistoryJson$/;
     const secrets = columns
       .map((c) => c.name)
       .filter((name) => secretShaped.test(name));
diff --git a/src/app/api/coach/about-me/__tests__/route-module-gate.test.ts b/src/app/api/coach/about-me/__tests__/route-module-gate.test.ts
index 94bb26256..647741d4b 100644
--- a/src/app/api/coach/about-me/__tests__/route-module-gate.test.ts
+++ b/src/app/api/coach/about-me/__tests__/route-module-gate.test.ts
@@ -226,7 +226,6 @@ describe("about-me module gate", () => {
       where: { id: "u1" },
       data: {
         insightsCachedAt: null,
-        insightsCachedText: null,
         insightsCachedTextEncrypted: null,
         insightsCachedLocale: null,
       },
diff --git a/src/app/api/daily/digest/route.ts b/src/app/api/daily/digest/route.ts
index db05d9ea8..f9b6dbfa3 100644
--- a/src/app/api/daily/digest/route.ts
+++ b/src/app/api/daily/digest/route.ts
@@ -4,7 +4,7 @@
  * The read seam for the unified daily-value system (P3). Returns the
  * `DailyDigest` DTO the Today surface, the daily push, and a future iOS widget
  * all consume — assembled by `loadDailyDigest` from ALREADY-CACHED data (the
- * nightly briefing lifted read-only from `User.insightsCachedText`, the
+ * nightly briefing lifted read-only from `User.insightsCachedTextEncrypted`, the
  * dashboard-snapshot health score / meds-today / sleep freshness) plus two
  * light deterministic reads (broken integrations, overdue Vorsorge). No
  * provider call is reachable from this path, and nothing warms on mount.
diff --git a/src/app/api/dashboard/snapshot/route.ts b/src/app/api/dashboard/snapshot/route.ts
index 8ad23d819..3079fb2e8 100644
--- a/src/app/api/dashboard/snapshot/route.ts
+++ b/src/app/api/dashboard/snapshot/route.ts
@@ -26,7 +26,7 @@
  * so a regression is attributable without re-instrumenting.
  *
  * No LLM is reachable from the builder — the daily briefing is lifted
- * read-only from `User.insightsCachedText`. The nightly
+ * read-only from `User.insightsCachedTextEncrypted`. The nightly
  * `insight-pregenerate` cron keeps that cache warm.
  */
 import { apiHandler, requireRecordAuth } from "@/lib/api-handler";
diff --git a/src/app/api/export/health-record/__tests__/route.test.ts b/src/app/api/export/health-record/__tests__/route.test.ts
index 3b61abb58..0a768cb86 100644
--- a/src/app/api/export/health-record/__tests__/route.test.ts
+++ b/src/app/api/export/health-record/__tests__/route.test.ts
@@ -206,7 +206,7 @@ beforeEach(() => {
     fullName: null,
     insurerName: null,
     insuranceNumberEncrypted: null,
-    insightsCachedText: null,
+    insightsCachedTextEncrypted: null,
   } as never);
 });
 
diff --git a/src/app/api/insights/generate/__tests__/route.test.ts b/src/app/api/insights/generate/__tests__/route.test.ts
index 8972bd996..bab35438f 100644
--- a/src/app/api/insights/generate/__tests__/route.test.ts
+++ b/src/app/api/insights/generate/__tests__/route.test.ts
@@ -44,7 +44,7 @@ vi.mock("@/lib/db", () => ({
       findUnique: vi.fn(async () => ({
         insightsPrivacyMode: "aggregated",
         insightsCachedAt: null,
-        insightsCachedText: null,
+        insightsCachedTextEncrypted: null,
         locale: "en",
       })),
       updateMany: vi.fn(async () => ({ count: 1 })),
@@ -175,7 +175,10 @@ import {
 import { annotate } from "@/lib/logging/context";
 import { buildUserPrompt } from "@/lib/ai/prompts/insight-system-prompt";
 import { AiUnavailableError } from "@/lib/ai/capabilities/refusal";
-import { openInsightsCachedText } from "@/lib/insights/cached-text-cipher";
+import {
+  openInsightsCachedText,
+  sealInsightsCachedText,
+} from "@/lib/insights/cached-text-cipher";
 
 // The cached payload is sealed at rest, so its writes need a key.
 vi.stubEnv("ENCRYPTION_KEY", "c".repeat(64));
@@ -472,7 +475,7 @@ describe("POST /api/insights/generate — cache write (v1.16.8)", () => {
     const user = {
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: null,
-      insightsCachedText: null,
+      insightsCachedTextEncrypted: null,
       locale: "en",
       unitPreference: "imperial",
       glucoseUnit: "mmol/L",
@@ -527,7 +530,7 @@ describe("POST /api/insights/generate — cache write (v1.16.8)", () => {
     vi.mocked(prisma.user.findUnique).mockResolvedValueOnce({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: null,
-      insightsCachedText: null,
+      insightsCachedTextEncrypted: null,
       insightsExcludeMetrics: ["sleep"],
       locale: "en",
       dateOfBirth: null,
@@ -564,7 +567,7 @@ describe("POST /api/insights/generate — cache write (v1.16.8)", () => {
     vi.mocked(prisma.user.findUnique).mockResolvedValueOnce({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: null,
-      insightsCachedText: null,
+      insightsCachedTextEncrypted: null,
       insightsExcludeMetrics: [],
       locale: "en",
     } as never);
@@ -596,11 +599,13 @@ describe("POST /api/insights/generate — cache write (v1.16.8)", () => {
     vi.mocked(prisma.user.findUnique).mockResolvedValueOnce({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(),
-      insightsCachedText: JSON.stringify({
-        changed: "still fresh",
-        dailyBriefing: { paragraph: "ok", keyFindings: [] },
-        briefingGeneratedAt: new Date().toISOString(),
-      }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({
+          changed: "still fresh",
+          dailyBriefing: { paragraph: "ok", keyFindings: [] },
+          briefingGeneratedAt: new Date().toISOString(),
+        }),
+      ),
       locale: "en",
     } as never);
 
@@ -636,11 +641,13 @@ describe("POST /api/insights/generate — cache write (v1.16.8)", () => {
     vi.mocked(prisma.user.findUnique).mockResolvedValueOnce({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(),
-      insightsCachedText: JSON.stringify({
-        changed: "still fresh",
-        dailyBriefing: { paragraph: "ok", keyFindings: [] },
-        briefingGeneratedAt: new Date().toISOString(),
-      }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({
+          changed: "still fresh",
+          dailyBriefing: { paragraph: "ok", keyFindings: [] },
+          briefingGeneratedAt: new Date().toISOString(),
+        }),
+      ),
       locale: "en",
     } as never);
 
@@ -673,10 +680,12 @@ describe("POST /api/insights/generate — briefingless fresh cache (v1.28.30)",
     vi.mocked(prisma.user.findUnique).mockResolvedValueOnce({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 6 * 60 * 60 * 1000),
-      insightsCachedText: JSON.stringify({
-        changed: "fresh but no briefing",
-        dailyBriefing: null,
-      }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({
+          changed: "fresh but no briefing",
+          dailyBriefing: null,
+        }),
+      ),
       insightsExcludeMetrics: [],
       locale: "en",
     } as never);
@@ -686,10 +695,12 @@ describe("POST /api/insights/generate — briefingless fresh cache (v1.28.30)",
     vi.mocked(prisma.user.findUnique).mockResolvedValueOnce({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 6 * 60 * 60 * 1000),
-      insightsCachedText: JSON.stringify({
-        dailyBriefing: { paragraph: "today", keyFindings: [] },
-        briefingGeneratedAt: new Date().toISOString(),
-      }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({
+          dailyBriefing: { paragraph: "today", keyFindings: [] },
+          briefingGeneratedAt: new Date().toISOString(),
+        }),
+      ),
       locale: "en",
     } as never);
 
@@ -770,7 +781,7 @@ describe("POST /api/insights/generate — payload-size hard downgrade (H1)", ()
       // wide shape; the retry asks for the aggregated shape.
       insightsPrivacyMode: "raw",
       insightsCachedAt: null,
-      insightsCachedText: null,
+      insightsCachedTextEncrypted: null,
       insightsExcludeMetrics: [],
       locale: "en",
     } as never);
@@ -817,7 +828,9 @@ describe("GET /api/insights/generate — read-only advisor read", () => {
     };
     vi.mocked(prisma.user.findUnique).mockResolvedValueOnce({
       insightsCachedAt: new Date(),
-      insightsCachedText: JSON.stringify(cached),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify(cached),
+      ),
       locale: "en",
     } as never);
 
@@ -842,7 +855,9 @@ describe("GET /api/insights/generate — read-only advisor read", () => {
     const stale = new Date(Date.now() - 48 * 60 * 60 * 1000);
     vi.mocked(prisma.user.findUnique).mockResolvedValueOnce({
       insightsCachedAt: stale,
-      insightsCachedText: JSON.stringify({ dailyBriefing: null }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({ dailyBriefing: null }),
+      ),
       locale: "en",
     } as never);
 
@@ -867,7 +882,9 @@ describe("GET /api/insights/generate — read-only advisor read", () => {
     const cached = { dailyBriefing: { paragraph: "Deutsch", keyFindings: [] } };
     vi.mocked(prisma.user.findUnique).mockResolvedValueOnce({
       insightsCachedAt: new Date(),
-      insightsCachedText: JSON.stringify(cached),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify(cached),
+      ),
       insightsCachedLocale: "de",
       locale: "en",
     } as never);
@@ -896,7 +913,9 @@ describe("GET /api/insights/generate — read-only advisor read", () => {
     };
     vi.mocked(prisma.user.findUnique).mockResolvedValueOnce({
       insightsCachedAt: new Date(),
-      insightsCachedText: JSON.stringify(cached),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify(cached),
+      ),
       insightsCachedLocale: "en",
       locale: "en",
     } as never);
@@ -918,10 +937,12 @@ describe("GET /api/insights/generate — read-only advisor read", () => {
     const yesterday = new Date(Date.now() - 30 * 60 * 60 * 1000);
     vi.mocked(prisma.user.findUnique).mockResolvedValueOnce({
       insightsCachedAt: new Date(Date.now() - 60_000),
-      insightsCachedText: JSON.stringify({
-        dailyBriefing: { paragraph: "Yesterday's read.", keyFindings: [] },
-        briefingGeneratedAt: yesterday.toISOString(),
-      }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({
+          dailyBriefing: { paragraph: "Yesterday's read.", keyFindings: [] },
+          briefingGeneratedAt: yesterday.toISOString(),
+        }),
+      ),
       insightsCachedLocale: "en",
       locale: "en",
       timezone: "UTC",
@@ -944,29 +965,31 @@ describe("GET /api/insights/generate — read-only advisor read", () => {
   it("serves today's signals with deltas at display precision", async () => {
     vi.mocked(prisma.user.findUnique).mockResolvedValueOnce({
       insightsCachedAt: new Date(),
-      insightsCachedText: JSON.stringify({
-        dailyBriefing: {
-          paragraph: "ok",
-          keyFindings: [],
-          signalsOfDay: [
-            {
-              sourceMetric: "sleep",
-              tone: "info",
-              headline: "Shorter night",
-              nudge: "An earlier night.",
-              delta: null,
-            },
-            {
-              sourceMetric: "pulse",
-              tone: "watch",
-              headline: "Pulse up",
-              nudge: "Rest.",
-              delta: "+33.72 bpm vs your 30-day average",
-            },
-          ],
-        },
-        briefingGeneratedAt: new Date().toISOString(),
-      }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({
+          dailyBriefing: {
+            paragraph: "ok",
+            keyFindings: [],
+            signalsOfDay: [
+              {
+                sourceMetric: "sleep",
+                tone: "info",
+                headline: "Shorter night",
+                nudge: "An earlier night.",
+                delta: null,
+              },
+              {
+                sourceMetric: "pulse",
+                tone: "watch",
+                headline: "Pulse up",
+                nudge: "Rest.",
+                delta: "+33.72 bpm vs your 30-day average",
+              },
+            ],
+          },
+          briefingGeneratedAt: new Date().toISOString(),
+        }),
+      ),
       insightsCachedLocale: "en",
       locale: "en",
       timezone: "UTC",
@@ -998,7 +1021,7 @@ describe("GET /api/insights/generate — read-only advisor read", () => {
     vi.mocked(hasUsableStatusProvider).mockResolvedValueOnce(false);
     vi.mocked(prisma.user.findUnique).mockResolvedValueOnce({
       insightsCachedAt: null,
-      insightsCachedText: null,
+      insightsCachedTextEncrypted: null,
       locale: "en",
     } as never);
 
@@ -1027,7 +1050,9 @@ describe("GET /api/insights/generate — read-only advisor read", () => {
     const cached = { dailyBriefing: { paragraph: "old", keyFindings: [] } };
     vi.mocked(prisma.user.findUnique).mockResolvedValueOnce({
       insightsCachedAt: stale,
-      insightsCachedText: JSON.stringify(cached),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify(cached),
+      ),
       locale: "en",
     } as never);
 
@@ -1054,7 +1079,9 @@ describe("GET /api/insights/generate — read-only advisor read", () => {
     const cachedAt = new Date(Date.now() - 60 * 60 * 1000);
     vi.mocked(prisma.user.findUnique).mockResolvedValueOnce({
       insightsCachedAt: cachedAt,
-      insightsCachedText: JSON.stringify({ dailyBriefing: null }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({ dailyBriefing: null }),
+      ),
       locale: "en",
     } as never);
     // Marker newer than the last successful generation (written right
@@ -1086,9 +1113,11 @@ describe("GET /api/insights/generate — read-only advisor read", () => {
     const cachedAt = new Date(Date.now() - 60 * 60 * 1000);
     vi.mocked(prisma.user.findUnique).mockResolvedValueOnce({
       insightsCachedAt: cachedAt,
-      insightsCachedText: JSON.stringify({
-        dailyBriefing: { paragraph: "held", keyFindings: [] },
-      }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({
+          dailyBriefing: { paragraph: "held", keyFindings: [] },
+        }),
+      ),
       locale: "en",
     } as never);
     vi.mocked(prisma.auditLog.findFirst).mockResolvedValueOnce({
@@ -1109,9 +1138,11 @@ describe("GET /api/insights/generate — read-only advisor read", () => {
   it("reports hasProvider: true on a normal cached read", async () => {
     vi.mocked(prisma.user.findUnique).mockResolvedValueOnce({
       insightsCachedAt: new Date(),
-      insightsCachedText: JSON.stringify({
-        dailyBriefing: { paragraph: "ok", keyFindings: [] },
-      }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({
+          dailyBriefing: { paragraph: "ok", keyFindings: [] },
+        }),
+      ),
       locale: "en",
     } as never);
 
diff --git a/src/app/api/insights/generate/route.ts b/src/app/api/insights/generate/route.ts
index f2e3c3ff9..9827cab62 100644
--- a/src/app/api/insights/generate/route.ts
+++ b/src/app/api/insights/generate/route.ts
@@ -153,7 +153,7 @@ export function resolveInsightsRateLimit(): number {
  * to mount against the POST handler, which generates inline on a cache miss
  * and blocks the page-load path on the full provider chain (up to the
  * client's 8 s abort). This read-only GET serves the cached payload from
- * `User.insightsCachedText` immediately — NEVER calling the provider — and,
+ * `User.insightsCachedTextEncrypted` immediately — NEVER calling the provider — and,
  * when the cache is stale / missing AND a provider is configured, enqueues
  * an out-of-band warm (the same `insight-pregenerate` queue the nightly
  * cron and the "prepare assessments" button use). The next read reflects
diff --git a/src/components/insights/use-insights-advisor.ts b/src/components/insights/use-insights-advisor.ts
index e19700589..9633a652e 100644
--- a/src/components/insights/use-insights-advisor.ts
+++ b/src/components/insights/use-insights-advisor.ts
@@ -26,7 +26,7 @@ import type { BriefingFailureClass } from "@/lib/insights/briefing-failure-marke
  *
  * Why a POST under a `useQuery` rather than a dedicated GET endpoint:
  * the route already cache-returns the most recent generation (24h TTL on
- * `User.insightsCachedAt` / `User.insightsCachedText`) without burning a
+ * `User.insightsCachedAt` / `User.insightsCachedTextEncrypted`) without burning a
  * rate-limit token, so a single POST-without-`force` is functionally a
  * GET-or-generate. Adding a separate GET would duplicate the cache-read
  * branch and split the audit-log surface; the reconcile report deferred
@@ -540,7 +540,7 @@ export function useInsightsAdvisorQuery(
       // re-fetches.
       queryClient.invalidateQueries({ queryKey: queryKeys.insightsRoot() });
       // v1.18.10 / v1.32.19 — the dashboard hero surfaces the briefing
-      // headline from the SNAPSHOT (server-lifted `User.insightsCachedText`),
+      // headline from the SNAPSHOT (server-lifted `User.insightsCachedTextEncrypted`),
       // and the Today hero's lead line is the SAME briefing lifted into the
       // digest — neither is this advisor cache. A regenerate rewrites that
       // server cache, so both the snapshot and the digest must refetch.
diff --git a/src/lib/auth/session-user.ts b/src/lib/auth/session-user.ts
index d54cfeccd..b665542c7 100644
--- a/src/lib/auth/session-user.ts
+++ b/src/lib/auth/session-user.ts
@@ -17,8 +17,8 @@ import type { Prisma } from "@/generated/prisma/client";
  * flags, the small preference documents). Anything else is read by the one
  * route that needs it, with its own `select`, at the moment it needs it:
  *
- *   - bytes and large text: `avatarBytes`, `insightsCachedText`,
- *     `insightsCachedTextEncrypted`, `homeLocationEncrypted`,
+ *   - bytes and large text: `avatarBytes`, `insightsCachedTextEncrypted`,
+ *     `homeLocationEncrypted`,
  *     `environmentAqHistoryJson`, `dawarichPrefsEncrypted`;
  *   - credentials and secrets: `passwordHash`, `totpSecretEncrypted`,
  *     `totpLastStep`, `telegramBotToken`, every `*Encrypted` integration and
diff --git a/src/lib/consent/withdrawal.ts b/src/lib/consent/withdrawal.ts
index 9ec245d6c..2c35c261a 100644
--- a/src/lib/consent/withdrawal.ts
+++ b/src/lib/consent/withdrawal.ts
@@ -66,7 +66,7 @@ export async function purgeRegenerableAiText(
         where: {
           id: userId,
           OR: [
-            ...INSIGHTS_CACHE_PRESENT_WHERE.OR,
+            INSIGHTS_CACHE_PRESENT_WHERE,
             { insightsCachedAt: { not: null } },
             { insightsSnapshotHash: { not: null } },
           ],
diff --git a/src/lib/daily/digest.ts b/src/lib/daily/digest.ts
index 5d837ba28..e6995062f 100644
--- a/src/lib/daily/digest.ts
+++ b/src/lib/daily/digest.ts
@@ -3,7 +3,7 @@
  *
  * A pure, deterministic composer that assembles the day's read from data that
  * ALREADY EXISTS — the nightly `insight-pregenerate` output lifted read-only
- * from `User.insightsCachedText`, the dashboard-snapshot ingredients (health
+ * from `User.insightsCachedTextEncrypted`, the dashboard-snapshot ingredients (health
  * score, meds-today, sleep last-seen), plus two light deterministic reads
  * (integration status, due Vorsorge reminders). It computes no analytics and
  * NEVER triggers an AI/provider call — the warm-on-mount ban extends here. The
diff --git a/src/lib/daily/load-digest.ts b/src/lib/daily/load-digest.ts
index a79699426..1b15616a9 100644
--- a/src/lib/daily/load-digest.ts
+++ b/src/lib/daily/load-digest.ts
@@ -6,7 +6,7 @@
  * briefing lift) rides `readDashboardSnapshotCached` — the SAME SWR cell the
  * dashboard already serves, so the digest never re-runs the snapshot builder
  * within its TTL and never reaches an AI provider (the briefing is lifted
- * read-only from `User.insightsCachedText`). Two light deterministic reads add
+ * read-only from `User.insightsCachedTextEncrypted`). Two light deterministic reads add
  * the rail's non-snapshot inputs: broken integrations and overdue Vorsorge
  * reminders. Module gating is inherited from the snapshot (already
  * module-gated at the build layer) plus the resolved module map the item
diff --git a/src/lib/dashboard/__tests__/snapshot-read-briefing-capability.test.ts b/src/lib/dashboard/__tests__/snapshot-read-briefing-capability.test.ts
index ebe57a1d8..329dd66d9 100644
--- a/src/lib/dashboard/__tests__/snapshot-read-briefing-capability.test.ts
+++ b/src/lib/dashboard/__tests__/snapshot-read-briefing-capability.test.ts
@@ -16,6 +16,10 @@ import {
   AI_AVAILABLE,
   aiUnavailable,
 } from "@/__tests__/helpers/ai-capability-fixtures";
+import { sealInsightsCachedText } from "@/lib/insights/cached-text-cipher";
+
+// The cached payload is sealed at rest, so seeding it needs a key.
+vi.stubEnv("ENCRYPTION_KEY", "c".repeat(64));
 
 const briefingBody = {
   tiles: {},
@@ -35,9 +39,11 @@ vi.mock("@/lib/db", () => ({
   prisma: {
     user: {
       findUnique: async () => ({
-        insightsCachedText: JSON.stringify({
-          briefingGeneratedAt: new Date().toISOString(),
-        }),
+        insightsCachedTextEncrypted: sealInsightsCachedText(
+          JSON.stringify({
+            briefingGeneratedAt: new Date().toISOString(),
+          }),
+        ),
       }),
     },
   },
diff --git a/src/lib/dashboard/__tests__/snapshot-read-briefing-today.test.ts b/src/lib/dashboard/__tests__/snapshot-read-briefing-today.test.ts
index 7cf124e4a..3efaf82c4 100644
--- a/src/lib/dashboard/__tests__/snapshot-read-briefing-today.test.ts
+++ b/src/lib/dashboard/__tests__/snapshot-read-briefing-today.test.ts
@@ -10,6 +10,10 @@ import {
   AI_AVAILABLE,
   aiUnavailable,
 } from "@/__tests__/helpers/ai-capability-fixtures";
+import { sealInsightsCachedText } from "@/lib/insights/cached-text-cipher";
+
+// The cached payload is sealed at rest, so seeding it needs a key.
+vi.stubEnv("ENCRYPTION_KEY", "c".repeat(64));
 
 const BRIEFING = {
   paragraph: "Your pulse is well above its usual level today.",
@@ -49,7 +53,7 @@ const buildDashboardSnapshot = vi.fn(async () => current);
 
 // The cached briefing text is read off its own row, not the session user.
 const cacheRow = vi.hoisted(() => ({
-  current: null as { insightsCachedText: string | null } | null,
+  current: null as { insightsCachedTextEncrypted: Uint8Array | null } | null,
 }));
 vi.mock("@/lib/db", () => ({
   prisma: { user: { findUnique: async () => cacheRow.current } },
@@ -80,10 +84,12 @@ const NOW = new Date("2026-10-05T19:00:00.000Z");
 
 function user(generatedAt: string | null): SessionUser {
   cacheRow.current = {
-    insightsCachedText: JSON.stringify({
-      dailyBriefing: BRIEFING,
-      ...(generatedAt ? { briefingGeneratedAt: generatedAt } : {}),
-    }),
+    insightsCachedTextEncrypted: sealInsightsCachedText(
+      JSON.stringify({
+        dailyBriefing: BRIEFING,
+        ...(generatedAt ? { briefingGeneratedAt: generatedAt } : {}),
+      }),
+    ),
   };
   return {
     id: "user-briefing-today",
diff --git a/src/lib/dashboard/snapshot.ts b/src/lib/dashboard/snapshot.ts
index 4293375c7..29541fa39 100644
--- a/src/lib/dashboard/snapshot.ts
+++ b/src/lib/dashboard/snapshot.ts
@@ -27,7 +27,7 @@
  *     inside the same fast window.
  *
  * No LLM is reachable from this builder. The briefing is lifted
- * read-only from `User.insightsCachedText`; a cache miss / stale row
+ * read-only from `User.insightsCachedTextEncrypted`; a cache miss / stale row
  * yields `briefingState: "preparing"` (with the last good briefing
  * delivered under `briefingStale: true` when one exists) and the
  * `insight-pregenerate` cron refills it — or `"no-provider"` when no
@@ -943,7 +943,7 @@ export function applyBriefingCapability(
 }
 
 /**
- * Read-only briefing lift. Parses `User.insightsCachedText`, validates
+ * Read-only briefing lift. Parses `User.insightsCachedTextEncrypted`, validates
  * the `dailyBriefing` block, and reports a four-state. NEVER calls the
  * provider chain — `hasProvider` is a credential-PRESENCE thunk (two
  * narrow reads, no decrypt, no network) evaluated only on the
diff --git a/src/lib/data-wipe/wipe-plan.ts b/src/lib/data-wipe/wipe-plan.ts
index f02b0d0e7..93347dfcc 100644
--- a/src/lib/data-wipe/wipe-plan.ts
+++ b/src/lib/data-wipe/wipe-plan.ts
@@ -400,7 +400,6 @@ export const USER_RESET = {
   // Derived AI output cached on the row
   insightsPrivacyMode: "aggregated",
   insightsCachedAt: null,
-  insightsCachedText: null,
   insightsCachedTextEncrypted: null,
   insightsCachedLocale: null,
   insightsSnapshotHash: null,
diff --git a/src/lib/export/__tests__/restore-backup-round-trip.test.ts b/src/lib/export/__tests__/restore-backup-round-trip.test.ts
index fc61a2cbe..b647ccbf4 100644
--- a/src/lib/export/__tests__/restore-backup-round-trip.test.ts
+++ b/src/lib/export/__tests__/restore-backup-round-trip.test.ts
@@ -536,6 +536,38 @@ describe("backup round trip — export, wire schema, restore", () => {
     expect(res.status).toBe(200);
   });
 
+  // Files written before v1.44.0 can name the readable insights cache the
+  // release dropped (migration 0430), at the top level or among the account
+  // settings. The column is gone, so the restore must neither fail on the name
+  // nor try to write it.
+  it("restores a file that still names the dropped readable insights cache", async () => {
+    const { payload } = await buildFullBackupPayload(
+      sourceClient() as never,
+      OWNER,
+      { purpose: "disaster-recovery" },
+    );
+    const legacy: Record<string, unknown> = {
+      ...payload,
+      insightsCachedText: JSON.stringify({ dailyBriefing: { p: "old" } }),
+      accountSettings: {
+        ...((payload.accountSettings as Record<string, unknown> | null) ?? {}),
+        insightsCachedText: JSON.stringify({ dailyBriefing: { p: "old" } }),
+      },
+    };
+
+    const { res, written } = await roundTrip({}, legacy);
+
+    expect(res.status).toBe(200);
+    for (const w of written) {
+      expect(
+        Object.keys(w.data),
+        `${w.model}.${w.op} must not write the dropped column`,
+      ).not.toContain("insightsCachedText");
+    }
+    // The rest of the file still lands.
+    expect(written.some((w) => w.model === "userHealthProfile")).toBe(true);
+  });
+
   it("writes the durable self-context back with its ciphertext intact", async () => {
     const { written } = await roundTrip();
 
@@ -785,7 +817,7 @@ describe("backup round trip — export, wire schema, restore", () => {
         (w) =>
           w.model === "user" &&
           w.op === "update" &&
-          "insightsCachedText" in w.data,
+          "insightsCachedTextEncrypted" in w.data,
       );
       expect(
         userUpdate,
@@ -794,7 +826,6 @@ describe("backup round trip — export, wire schema, restore", () => {
       // The language tag is cleared with the text: an empty slot carries
       // no language, and the next write tags it afresh.
       expect(userUpdate!.data).toEqual({
-        insightsCachedText: null,
         insightsCachedTextEncrypted: null,
         insightsCachedAt: null,
         insightsCachedLocale: null,
@@ -831,7 +862,7 @@ describe("backup round trip — export, wire schema, restore", () => {
         (w) =>
           w.model === "user" &&
           w.op === "update" &&
-          "insightsCachedText" in w.data,
+          "insightsCachedTextEncrypted" in w.data,
       );
       expect(
         userUpdate,
diff --git a/src/lib/export/backup-plan.ts b/src/lib/export/backup-plan.ts
index b3c9ddef3..1d517711b 100644
--- a/src/lib/export/backup-plan.ts
+++ b/src/lib/export/backup-plan.ts
@@ -948,7 +948,6 @@ export const USER_COLUMN_BACKUP_CLASS = {
 
   // ── Operational ───────────────────────────────────────────────────────────
   insightsCachedAt: "OPERATIONAL",
-  insightsCachedText: "OPERATIONAL",
   insightsCachedTextEncrypted: "OPERATIONAL",
   insightsCachedLocale: "OPERATIONAL",
   insightsSnapshotHash: "OPERATIONAL",
diff --git a/src/lib/insights/__tests__/cached-text-cipher.test.ts b/src/lib/insights/__tests__/cached-text-cipher.test.ts
index 8fcd71142..4aa64f6c0 100644
--- a/src/lib/insights/__tests__/cached-text-cipher.test.ts
+++ b/src/lib/insights/__tests__/cached-text-cipher.test.ts
@@ -23,50 +23,27 @@ beforeEach(() => {
 afterEach(() => vi.unstubAllEnvs());
 
 describe("cached insights payload at rest", () => {
-  it("writes ciphertext and nulls the readable column in the same write", () => {
+  it("writes ciphertext only", () => {
     const data = insightsCacheWrite(PAYLOAD);
-    expect(data.insightsCachedText).toBeNull();
+    expect(Object.keys(data)).toEqual(["insightsCachedTextEncrypted"]);
     expect(
       Buffer.from(data.insightsCachedTextEncrypted).toString("utf8"),
     ).not.toContain("Sleep held");
     expect(openInsightsCachedText(data)).toBe(PAYLOAD);
   });
 
-  it("falls back to the readable column for a row the backfill has not reached", () => {
+  it("reads a sealed value", () => {
     expect(
       openInsightsCachedText({
-        insightsCachedText: PAYLOAD,
-        insightsCachedTextEncrypted: null,
-      }),
-    ).toBe(PAYLOAD);
-  });
-
-  // This used to prefer the readable column, the one sealed column read
-  // that way. Every sealed column now reads the ciphertext first.
-  it("reads a sealed value before a readable one beside it", () => {
-    expect(
-      openInsightsCachedText({
-        insightsCachedText: "readable",
         insightsCachedTextEncrypted: sealInsightsCachedText("sealed"),
       }),
     ).toBe("sealed");
   });
 
-  it("never serves the readable value in place of a sealed one that does not open", () => {
-    const foreign = encryptBytes(Buffer.from(PAYLOAD, "utf8"), "other/v1");
-    expect(
-      openInsightsCachedText({
-        insightsCachedText: "readable",
-        insightsCachedTextEncrypted: new Uint8Array(foreign),
-      }),
-    ).toBeNull();
-  });
-
   it("does not open a value sealed for another purpose", () => {
     const foreign = encryptBytes(Buffer.from(PAYLOAD, "utf8"), "other/v1");
     expect(
       openInsightsCachedText({
-        insightsCachedText: null,
         insightsCachedTextEncrypted: new Uint8Array(foreign),
       }),
     ).toBeNull();
@@ -75,6 +52,9 @@ describe("cached insights payload at rest", () => {
   it("reads an empty row as no cache", () => {
     expect(openInsightsCachedText(null)).toBeNull();
     expect(openInsightsCachedText({ ...INSIGHTS_CACHE_CLEARED })).toBeNull();
+    expect(
+      openInsightsCachedText({ insightsCachedTextEncrypted: new Uint8Array() }),
+    ).toBeNull();
   });
 
   it("is fail-closed on write: no key, no payload", () => {
@@ -82,13 +62,11 @@ describe("cached insights payload at rest", () => {
     expect(() => insightsCacheWrite(PAYLOAD)).toThrow();
   });
 
-  it("clears and selects both columns", () => {
+  it("clears and selects the sealed column", () => {
     expect(INSIGHTS_CACHE_CLEARED).toEqual({
-      insightsCachedText: null,
       insightsCachedTextEncrypted: null,
     });
-    expect(Object.keys(INSIGHTS_CACHE_SELECT).sort()).toEqual([
-      "insightsCachedText",
+    expect(Object.keys(INSIGHTS_CACHE_SELECT)).toEqual([
       "insightsCachedTextEncrypted",
     ]);
   });
diff --git a/src/lib/insights/__tests__/comprehensive-briefing-grounding-disposal.test.ts b/src/lib/insights/__tests__/comprehensive-briefing-grounding-disposal.test.ts
index 898355e11..17c106731 100644
--- a/src/lib/insights/__tests__/comprehensive-briefing-grounding-disposal.test.ts
+++ b/src/lib/insights/__tests__/comprehensive-briefing-grounding-disposal.test.ts
@@ -92,7 +92,10 @@ vi.mock("@/lib/cache/invalidate", () => ({
 }));
 
 import { generateComprehensiveInsight } from "../comprehensive-generate";
-import { openInsightsCachedText } from "@/lib/insights/cached-text-cipher";
+import {
+  openInsightsCachedText,
+  sealInsightsCachedText,
+} from "@/lib/insights/cached-text-cipher";
 
 // The cached payload is sealed at rest, so its writes need a key.
 vi.stubEnv("ENCRYPTION_KEY", "c".repeat(64));
@@ -148,7 +151,7 @@ function cachedUser(over: Record<string, unknown> = {}) {
   return {
     insightsPrivacyMode: "aggregated",
     insightsCachedAt: null,
-    insightsCachedText: null,
+    insightsCachedTextEncrypted: null,
     insightsExcludeMetrics: [],
     // Never equal to the freshly computed hash, so a full generation runs.
     insightsSnapshotHash: null,
@@ -189,7 +192,7 @@ describe("briefing grounding — disposal", () => {
     findUnique.mockResolvedValue(
       cachedUser({
         insightsCachedAt: new Date("2026-07-15T03:00:00.000Z"),
-        insightsCachedText: PREVIOUS_PAYLOAD,
+        insightsCachedTextEncrypted: sealInsightsCachedText(PREVIOUS_PAYLOAD),
       }),
     );
     // Both passes carry the same fabricated figure: a content failure.
diff --git a/src/lib/insights/__tests__/comprehensive-briefing-reroll.test.ts b/src/lib/insights/__tests__/comprehensive-briefing-reroll.test.ts
index 417cc94f1..00ce1b374 100644
--- a/src/lib/insights/__tests__/comprehensive-briefing-reroll.test.ts
+++ b/src/lib/insights/__tests__/comprehensive-briefing-reroll.test.ts
@@ -98,7 +98,10 @@ import { hashInsightSnapshot } from "../snapshot-hash";
 import { compactSections } from "@/lib/ai/prompts/compact-sections";
 import { featuresInReaderUnits } from "../features-units";
 import { DEFAULT_UNIT_PREFERENCES } from "@/lib/measurements/display-transform";
-import { openInsightsCachedText } from "@/lib/insights/cached-text-cipher";
+import {
+  openInsightsCachedText,
+  sealInsightsCachedText,
+} from "@/lib/insights/cached-text-cipher";
 
 // The cached payload is sealed at rest, so its writes need a key.
 vi.stubEnv("ENCRYPTION_KEY", "c".repeat(64));
@@ -143,7 +146,7 @@ describe("daily-briefing re-roll on unchanged data", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 26 * 60 * 60 * 1000),
-      insightsCachedText: CACHED,
+      insightsCachedTextEncrypted: sealInsightsCachedText(CACHED),
       insightsExcludeMetrics: [],
       insightsSnapshotHash: FEATURES_HASH,
       insightsBriefingRerollDate: null, // never re-rolled today
@@ -198,7 +201,7 @@ describe("daily-briefing re-roll on unchanged data", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 26 * 60 * 60 * 1000),
-      insightsCachedText: CACHED,
+      insightsCachedTextEncrypted: sealInsightsCachedText(CACHED),
       insightsExcludeMetrics: [],
       insightsSnapshotHash: FEATURES_HASH,
       insightsBriefingRerollDate: todayKey, // already re-rolled today
@@ -214,7 +217,7 @@ describe("daily-briefing re-roll on unchanged data", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 26 * 60 * 60 * 1000),
-      insightsCachedText: CACHED,
+      insightsCachedTextEncrypted: sealInsightsCachedText(CACHED),
       insightsExcludeMetrics: [],
       insightsSnapshotHash: FEATURES_HASH,
       insightsBriefingRerollDate: null,
diff --git a/src/lib/insights/__tests__/comprehensive-budget-refusal.test.ts b/src/lib/insights/__tests__/comprehensive-budget-refusal.test.ts
index 1ab2e37d8..e2b135eb3 100644
--- a/src/lib/insights/__tests__/comprehensive-budget-refusal.test.ts
+++ b/src/lib/insights/__tests__/comprehensive-budget-refusal.test.ts
@@ -150,7 +150,7 @@ beforeEach(() => {
   findUnique.mockResolvedValue({
     insightsPrivacyMode: "aggregated",
     insightsCachedAt: null,
-    insightsCachedText: null,
+    insightsCachedTextEncrypted: null,
     insightsExcludeMetrics: [],
     insightsSnapshotHash: null,
     insightsBriefingRerollDate: null,
diff --git a/src/lib/insights/__tests__/comprehensive-generate-force.test.ts b/src/lib/insights/__tests__/comprehensive-generate-force.test.ts
index 5519de2cd..3878245df 100644
--- a/src/lib/insights/__tests__/comprehensive-generate-force.test.ts
+++ b/src/lib/insights/__tests__/comprehensive-generate-force.test.ts
@@ -96,7 +96,10 @@ import { hashInsightSnapshot } from "../snapshot-hash";
 import { compactSections } from "@/lib/ai/prompts/compact-sections";
 import { featuresInReaderUnits } from "../features-units";
 import { DEFAULT_UNIT_PREFERENCES } from "@/lib/measurements/display-transform";
-import { openInsightsCachedText } from "@/lib/insights/cached-text-cipher";
+import {
+  openInsightsCachedText,
+  sealInsightsCachedText,
+} from "@/lib/insights/cached-text-cipher";
 
 // The cached payload is sealed at rest, so its writes need a key.
 vi.stubEnv("ENCRYPTION_KEY", "c".repeat(64));
@@ -143,7 +146,7 @@ describe("generateComprehensiveInsight — the briefing capability at the wire",
   const STALE_USER = {
     insightsPrivacyMode: "aggregated",
     insightsCachedAt: null,
-    insightsCachedText: null,
+    insightsCachedTextEncrypted: null,
     insightsExcludeMetrics: [],
     insightsSnapshotHash: null,
   };
@@ -181,7 +184,7 @@ describe("generateComprehensiveInsight — the briefing capability at the wire",
     findUnique.mockResolvedValue({
       ...STALE_USER,
       insightsCachedAt: new Date(Date.now() - 60 * 60 * 1000),
-      insightsCachedText: "{}",
+      insightsCachedTextEncrypted: sealInsightsCachedText("{}"),
     });
     aiCapabilityForRecord.mockResolvedValue({
       available: false,
@@ -201,7 +204,7 @@ describe("generateComprehensiveInsight — cache short-circuit", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 21 * 60 * 60 * 1000),
-      insightsCachedText: "{}",
+      insightsCachedTextEncrypted: sealInsightsCachedText("{}"),
       insightsExcludeMetrics: [],
       insightsSnapshotHash: null,
     });
@@ -220,7 +223,7 @@ describe("generateComprehensiveInsight — cache short-circuit", () => {
       insightsPrivacyMode: "aggregated",
       // 21h old — inside the 24h TTL, so the un-forced path would cache.
       insightsCachedAt: new Date(Date.now() - 21 * 60 * 60 * 1000),
-      insightsCachedText: "{}",
+      insightsCachedTextEncrypted: sealInsightsCachedText("{}"),
       insightsExcludeMetrics: [],
       insightsSnapshotHash: null,
     });
@@ -251,7 +254,9 @@ describe("generateComprehensiveInsight — content-hash gate (v1.16.8)", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 26 * 60 * 60 * 1000),
-      insightsCachedText: JSON.stringify({ dailyBriefing: { p: "old" } }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({ dailyBriefing: { p: "old" } }),
+      ),
       insightsExcludeMetrics: [],
       insightsSnapshotHash: FEATURES_HASH,
     });
@@ -280,7 +285,9 @@ describe("generateComprehensiveInsight — content-hash gate (v1.16.8)", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 26 * 60 * 60 * 1000),
-      insightsCachedText: JSON.stringify({ dailyBriefing: { p: "old" } }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({ dailyBriefing: { p: "old" } }),
+      ),
       insightsExcludeMetrics: [],
       // Stored fingerprint from an older data state.
       insightsSnapshotHash: "0".repeat(64),
@@ -329,7 +336,9 @@ describe("generateComprehensiveInsight — content-hash gate (v1.16.8)", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 26 * 60 * 60 * 1000),
-      insightsCachedText: JSON.stringify({ dailyBriefing: { p: "old" } }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({ dailyBriefing: { p: "old" } }),
+      ),
       insightsExcludeMetrics: [],
       insightsSnapshotHash: FEATURES_HASH,
       unitPreference: "imperial",
@@ -383,7 +392,9 @@ describe("generateComprehensiveInsight — content-hash gate (v1.16.8)", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 1 * 60 * 60 * 1000),
-      insightsCachedText: JSON.stringify({ dailyBriefing: { p: "english" } }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({ dailyBriefing: { p: "english" } }),
+      ),
       insightsCachedLocale: "en",
       insightsExcludeMetrics: [],
       insightsSnapshotHash: null,
@@ -403,7 +414,9 @@ describe("generateComprehensiveInsight — content-hash gate (v1.16.8)", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 26 * 60 * 60 * 1000),
-      insightsCachedText: JSON.stringify({ dailyBriefing: { p: "old" } }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({ dailyBriefing: { p: "old" } }),
+      ),
       insightsExcludeMetrics: [],
       insightsSnapshotHash: null,
     });
@@ -436,10 +449,12 @@ describe("generateComprehensiveInsight — content-hash gate (v1.16.8)", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 26 * 60 * 60 * 1000),
-      insightsCachedText: JSON.stringify({
-        dailyBriefing: null,
-        recommendations: [],
-      }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({
+          dailyBriefing: null,
+          recommendations: [],
+        }),
+      ),
       insightsExcludeMetrics: [],
       insightsSnapshotHash: FEATURES_HASH,
     });
@@ -475,7 +490,7 @@ describe("generateComprehensiveInsight — content-hash gate (v1.16.8)", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: null,
-      insightsCachedText: null,
+      insightsCachedTextEncrypted: null,
       insightsExcludeMetrics: [],
       insightsSnapshotHash: FEATURES_HASH,
     });
@@ -522,7 +537,9 @@ describe("generateComprehensiveInsight — usage level", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 26 * 60 * 60 * 1000),
-      insightsCachedText: JSON.stringify({ dailyBriefing: { p: "old" } }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({ dailyBriefing: { p: "old" } }),
+      ),
       insightsExcludeMetrics: [],
       insightsSnapshotHash: FEATURES_HASH,
       aiUsageLevel,
diff --git a/src/lib/insights/__tests__/comprehensive-json-retry.test.ts b/src/lib/insights/__tests__/comprehensive-json-retry.test.ts
index dca1bcfe2..3a6f0e78f 100644
--- a/src/lib/insights/__tests__/comprehensive-json-retry.test.ts
+++ b/src/lib/insights/__tests__/comprehensive-json-retry.test.ts
@@ -110,7 +110,7 @@ beforeEach(() => {
   findUnique.mockResolvedValue({
     insightsPrivacyMode: "aggregated",
     insightsCachedAt: null,
-    insightsCachedText: null,
+    insightsCachedTextEncrypted: null,
     insightsExcludeMetrics: [],
     insightsSnapshotHash: null,
     insightsBriefingRerollDate: null,
diff --git a/src/lib/insights/__tests__/comprehensive-outbound-repair.test.ts b/src/lib/insights/__tests__/comprehensive-outbound-repair.test.ts
index 4d6025b50..97adb76f7 100644
--- a/src/lib/insights/__tests__/comprehensive-outbound-repair.test.ts
+++ b/src/lib/insights/__tests__/comprehensive-outbound-repair.test.ts
@@ -116,7 +116,7 @@ beforeEach(() => {
   findUnique.mockResolvedValue({
     insightsPrivacyMode: "aggregated",
     insightsCachedAt: null,
-    insightsCachedText: null,
+    insightsCachedTextEncrypted: null,
     insightsExcludeMetrics: [],
     insightsSnapshotHash: null,
     insightsBriefingRerollDate: null,
diff --git a/src/lib/insights/__tests__/comprehensive-plan-progress.test.ts b/src/lib/insights/__tests__/comprehensive-plan-progress.test.ts
index 98c1501e7..eaf83631b 100644
--- a/src/lib/insights/__tests__/comprehensive-plan-progress.test.ts
+++ b/src/lib/insights/__tests__/comprehensive-plan-progress.test.ts
@@ -114,7 +114,7 @@ beforeEach(() => {
   findUnique.mockResolvedValue({
     insightsPrivacyMode: "aggregated",
     insightsCachedAt: null,
-    insightsCachedText: null,
+    insightsCachedTextEncrypted: null,
     insightsExcludeMetrics: [],
     insightsSnapshotHash: null,
     insightsBriefingRerollDate: null,
diff --git a/src/lib/insights/__tests__/comprehensive-privacy-flip.test.ts b/src/lib/insights/__tests__/comprehensive-privacy-flip.test.ts
index 12bca2b0b..87fbb55b1 100644
--- a/src/lib/insights/__tests__/comprehensive-privacy-flip.test.ts
+++ b/src/lib/insights/__tests__/comprehensive-privacy-flip.test.ts
@@ -97,6 +97,7 @@ vi.mock("@/lib/logging/context", async (importOriginal) => {
 import { generateComprehensiveInsight } from "../comprehensive-generate";
 import { hashInsightSnapshot } from "../snapshot-hash";
 import { compactSections } from "@/lib/ai/prompts/compact-sections";
+import { sealInsightsCachedText } from "@/lib/insights/cached-text-cipher";
 
 // The cached payload is sealed at rest, so its writes need a key.
 vi.stubEnv("ENCRYPTION_KEY", "c".repeat(64));
@@ -151,7 +152,9 @@ describe("generateComprehensiveInsight — consent withdrawn in flight", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 26 * 60 * 60 * 1000),
-      insightsCachedText: JSON.stringify({ dailyBriefing: { p: "old" } }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({ dailyBriefing: { p: "old" } }),
+      ),
       insightsExcludeMetrics: [],
       insightsSnapshotHash: "0".repeat(64),
     });
@@ -191,7 +194,9 @@ describe("generateComprehensiveInsight — scope/version commit guard", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 26 * 60 * 60 * 1000),
-      insightsCachedText: JSON.stringify({ dailyBriefing: { p: "old" } }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({ dailyBriefing: { p: "old" } }),
+      ),
       insightsExcludeMetrics: [],
       insightsSnapshotHash: "0".repeat(64), // changed → full generation
     });
@@ -236,7 +241,9 @@ describe("generateComprehensiveInsight — scope/version commit guard", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 26 * 60 * 60 * 1000),
-      insightsCachedText: JSON.stringify({ dailyBriefing: { p: "old" } }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({ dailyBriefing: { p: "old" } }),
+      ),
       insightsExcludeMetrics: ["sleep"],
       insightsSnapshotHash: "0".repeat(64),
       gender: "FEMALE",
@@ -280,7 +287,9 @@ describe("generateComprehensiveInsight — scope/version commit guard", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 26 * 60 * 60 * 1000),
-      insightsCachedText: JSON.stringify({ dailyBriefing: { p: "old" } }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({ dailyBriefing: { p: "old" } }),
+      ),
       insightsExcludeMetrics: ["sleep"],
       insightsSnapshotHash: "0".repeat(64),
       gender: "FEMALE",
@@ -322,7 +331,9 @@ describe("generateComprehensiveInsight — scope/version commit guard", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 26 * 60 * 60 * 1000),
-      insightsCachedText: JSON.stringify({ dailyBriefing: { p: "old" } }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({ dailyBriefing: { p: "old" } }),
+      ),
       insightsExcludeMetrics: [],
       insightsSnapshotHash: "0".repeat(64),
     });
@@ -361,7 +372,7 @@ describe("generateComprehensiveInsight — scope/version commit guard", () => {
     findUnique.mockResolvedValue({
       insightsPrivacyMode: "aggregated",
       insightsCachedAt: new Date(Date.now() - 26 * 60 * 60 * 1000),
-      insightsCachedText: CACHED_WITH_BRIEFING,
+      insightsCachedTextEncrypted: sealInsightsCachedText(CACHED_WITH_BRIEFING),
       insightsExcludeMetrics: [],
       insightsSnapshotHash: FEATURES_HASH, // unchanged → reroll path
       insightsBriefingRerollDate: null,
diff --git a/src/lib/insights/__tests__/comprehensive-timeout-honored.test.ts b/src/lib/insights/__tests__/comprehensive-timeout-honored.test.ts
index fb77da31c..39307a17c 100644
--- a/src/lib/insights/__tests__/comprehensive-timeout-honored.test.ts
+++ b/src/lib/insights/__tests__/comprehensive-timeout-honored.test.ts
@@ -108,7 +108,7 @@ function mockUser(overrides: Record<string, unknown> = {}) {
   findUnique.mockResolvedValue({
     insightsPrivacyMode: "aggregated",
     insightsCachedAt: null,
-    insightsCachedText: null,
+    insightsCachedTextEncrypted: null,
     insightsExcludeMetrics: [],
     insightsSnapshotHash: null,
     insightsBriefingRerollDate: null,
@@ -165,7 +165,7 @@ describe("comprehensive timeout honouring", () => {
     const outcome = await generateComprehensiveInsight("u1", { locale: "de" });
 
     expect(outcome.status).toBe("failed");
-    // No cache row written → the prior `insightsCachedText` (last good) survives.
+    // No cache row written → the prior `insightsCachedTextEncrypted` (last good) survives.
     expect(userUpdate).not.toHaveBeenCalled();
     // A dated failure marker is recorded so the read path can surface a hint.
     expect(recordBriefingFailure).toHaveBeenCalledWith(
diff --git a/src/lib/insights/__tests__/comprehensive-warm-timeout.test.ts b/src/lib/insights/__tests__/comprehensive-warm-timeout.test.ts
index b1f089d00..ef7cd05ad 100644
--- a/src/lib/insights/__tests__/comprehensive-warm-timeout.test.ts
+++ b/src/lib/insights/__tests__/comprehensive-warm-timeout.test.ts
@@ -129,7 +129,7 @@ beforeEach(() => {
   findUnique.mockResolvedValue({
     insightsPrivacyMode: "aggregated",
     insightsCachedAt: null,
-    insightsCachedText: null,
+    insightsCachedTextEncrypted: null,
     insightsExcludeMetrics: [],
     insightsSnapshotHash: null,
     insightsBriefingRerollDate: null,
diff --git a/src/lib/insights/briefing-failure-marker.ts b/src/lib/insights/briefing-failure-marker.ts
index 025a3abe4..b3a62c25d 100644
--- a/src/lib/insights/briefing-failure-marker.ts
+++ b/src/lib/insights/briefing-failure-marker.ts
@@ -4,7 +4,7 @@ import { prisma } from "@/lib/db";
  * Dated failure marker for the daily-briefing generation.
  *
  * The briefing keeps its last good payload on a failed refresh: the generator
- * writes NO `User.insightsCachedText` row when a provider times out or errors,
+ * writes NO `User.insightsCachedTextEncrypted` row when a provider times out or errors,
  * so the previous briefing stays intact and the surface never blanks. What was
  * missing is a signal the READ path can use to tell the difference between "no
  * refresh was due" and "the last refresh attempt failed" — without that, a
diff --git a/src/lib/insights/cached-text-cipher.ts b/src/lib/insights/cached-text-cipher.ts
index c74cbfcb0..90d154f18 100644
--- a/src/lib/insights/cached-text-cipher.ts
+++ b/src/lib/insights/cached-text-cipher.ts
@@ -1,35 +1,30 @@
 /**
  * The cached AI insights payload, sealed at rest.
  *
- * `User.insightsCachedText` held the model's last full reading of the account
- * in the clear: the daily briefing, the per-domain status text and the
- * recommendations, every one of them a sentence about the person's health.
- * It was the last readable column of that kind on the user row. Since v1.43.7
- * the payload lives in `insightsCachedTextEncrypted` (AES-256-GCM, binary
- * layout, purpose-bound by {@link INSIGHTS_CACHED_TEXT_AAD}), and the free-text
- * encryption backfill seals the rows written before.
+ * The model's last full reading of the account (the daily briefing, the
+ * per-domain status text and the recommendations, every one of them a
+ * sentence about the person's health) lives in `insightsCachedTextEncrypted`
+ * (AES-256-GCM, binary layout, purpose-bound by
+ * {@link INSIGHTS_CACHED_TEXT_AAD}). The readable column it replaced in
+ * v1.43.7 was dropped in v1.44.0 (migration 0430).
  *
- * Every reader and writer goes through this module, which is what keeps the
- * two columns in step. A clear that nulls one column and not the other would
- * leave the briefing behind after a consent withdrawal, so the clearing value
- * is exported here and nowhere else spells the column names
+ * Every reader and writer goes through this module, so the column name is
+ * spelled here and in the classification tables only
  * (`insights-cached-text-access-guard.test.ts`).
  */
 import { Buffer } from "node:buffer";
 
 import { decryptBytes, encryptBytes } from "@/lib/crypto";
 import { INSIGHTS_CACHED_TEXT_AAD } from "@/lib/crypto/encrypted-columns";
-import { readSealedOrLegacy, warnAndDrop } from "@/lib/crypto/sealed-or-legacy";
+import { warnAndDrop } from "@/lib/crypto/sealed-or-legacy";
 
 /** The columns a reader selects to open the cache. */
 export const INSIGHTS_CACHE_SELECT = {
-  insightsCachedText: true,
   insightsCachedTextEncrypted: true,
 } as const;
 
 /** The row shape {@link openInsightsCachedText} reads. */
 export interface InsightsCacheColumns {
-  insightsCachedText?: string | null;
   insightsCachedTextEncrypted?: Uint8Array | null;
 }
 
@@ -44,47 +39,28 @@ export function sealInsightsCachedText(text: string): Uint8Array<ArrayBuffer> {
   return out;
 }
 
-/**
- * The `data` fields that store a payload: the ciphertext, and the legacy
- * readable column nulled in the same write so a row never holds both a new
- * sealed payload and an older readable one.
- */
+/** The `data` fields that store a payload. */
 export function insightsCacheWrite(text: string): {
   insightsCachedTextEncrypted: Uint8Array<ArrayBuffer>;
-  insightsCachedText: null;
 } {
-  return {
-    insightsCachedTextEncrypted: sealInsightsCachedText(text),
-    insightsCachedText: null,
-  };
+  return { insightsCachedTextEncrypted: sealInsightsCachedText(text) };
 }
 
-/** The `data` fields that empty the cache. Both columns, always. */
+/** The `data` fields that empty the cache. */
 export const INSIGHTS_CACHE_CLEARED = {
-  insightsCachedText: null,
   insightsCachedTextEncrypted: null,
 } as const;
 
-/** A `where` that finds rows holding a cached payload in either column. */
+/** A `where` that finds rows holding a cached payload. */
 export const INSIGHTS_CACHE_PRESENT_WHERE = {
-  OR: [
-    { insightsCachedText: { not: null } },
-    { insightsCachedTextEncrypted: { not: null } },
-  ],
+  insightsCachedTextEncrypted: { not: null },
 } as const;
 
+const dropUndecryptable = warnAndDrop("insights cache did not open");
+
 /**
  * The cached payload as text, or null when there is none.
  *
- * The ciphertext is read first, as every sealed column is read
- * (`readSealedOrLegacy`); the readable column only when the row holds no
- * ciphertext. A row holding both can come from a writer of the previous
- * release still running after the upgrade; its readable value may be the
- * newer one, and the free-text backfill seals it over the old ciphertext on
- * its next pass. Until then the reader serves the sealed one: an older
- * briefing for a while, never a readable value preferred over a protected
- * one.
- *
  * A sealed value that does not open reads as an empty cache with a warning on
  * the event. It is a cache: the next warm overwrites it under the active key,
  * whereas failing the read would take the dashboard down with it.
@@ -92,14 +68,13 @@ export const INSIGHTS_CACHE_PRESENT_WHERE = {
 export function openInsightsCachedText(
   row: InsightsCacheColumns | null | undefined,
 ): string | null {
-  if (!row) return null;
-  return readSealedOrLegacy({
-    sealed: row.insightsCachedTextEncrypted,
-    legacy: row.insightsCachedText,
-    open: (sealed) =>
-      decryptBytes(Buffer.from(sealed), INSIGHTS_CACHED_TEXT_AAD).toString(
-        "utf8",
-      ),
-    onUndecryptable: warnAndDrop("insights cache did not open"),
-  });
+  const sealed = row?.insightsCachedTextEncrypted;
+  if (!sealed || sealed.byteLength === 0) return null;
+  try {
+    return decryptBytes(Buffer.from(sealed), INSIGHTS_CACHED_TEXT_AAD).toString(
+      "utf8",
+    );
+  } catch (error) {
+    return dropUndecryptable(error);
+  }
 }
diff --git a/src/lib/insights/comprehensive-generate.ts b/src/lib/insights/comprehensive-generate.ts
index 3b1036474..67a612a62 100644
--- a/src/lib/insights/comprehensive-generate.ts
+++ b/src/lib/insights/comprehensive-generate.ts
@@ -1279,7 +1279,7 @@ export async function generateComprehensiveInsight(
     });
     // v1.25 — record a dated failure marker so the read path can surface a
     // discreet "couldn't refresh" hint alongside the preserved last-good
-    // briefing. No cache row is written here, so `insightsCachedText` (the
+    // briefing. No cache row is written here, so `insightsCachedTextEncrypted` (the
     // last good payload) stays intact and the surface never blanks.
     void recordBriefingFailure({
       userId,
diff --git a/src/lib/jobs/__tests__/free-text-encryption-backfill.test.ts b/src/lib/jobs/__tests__/free-text-encryption-backfill.test.ts
index 06057a5c8..5bc6abd92 100644
--- a/src/lib/jobs/__tests__/free-text-encryption-backfill.test.ts
+++ b/src/lib/jobs/__tests__/free-text-encryption-backfill.test.ts
@@ -5,10 +5,6 @@ import {
   decryptRouteGeometry,
   encryptRouteGeometry,
 } from "@/lib/workouts/route-geometry-cipher";
-import {
-  openInsightsCachedText,
-  sealInsightsCachedText,
-} from "@/lib/insights/cached-text-cipher";
 
 // ── in-memory store backing a minimal prisma mock ──────────────────────────
 interface ConversationRow {
@@ -33,14 +29,6 @@ interface PractitionerRow {
   locationEncrypted: Uint8Array | null;
   updatedAt?: Date;
 }
-interface UserRow {
-  id: string;
-  /** The row is its own owner; mirrors the other delegates' owner field. */
-  userId: string;
-  insightsCachedText: string | null;
-  insightsCachedTextEncrypted: Uint8Array | null;
-  updatedAt?: Date;
-}
 interface RouteRow {
   id: string;
   /** The owning workout's user; the real table reaches it through the join. */
@@ -54,7 +42,6 @@ const store = vi.hoisted(() => ({
   entries: [] as EntryRow[],
   practitioners: [] as PractitionerRow[],
   routes: [] as RouteRow[],
-  users: [] as UserRow[],
 }));
 
 vi.mock("@/lib/jobs/boss-instance", () => ({ getGlobalBoss: () => null }));
@@ -131,33 +118,6 @@ vi.mock("@/lib/db", () => {
     customMetricEntry: delegate(() => store.entries, ["note"]),
     practitioner: delegate(() => store.practitioners, ["phone", "location"]),
     workoutRoute: delegate(() => store.routes, ["geometry"]),
-    user: (() => {
-      const base = delegate(() => store.users, ["insightsCachedText"]);
-      return {
-        ...base,
-        // The insights cache move also guards on the readable value it read,
-        // so a warm that sealed a newer payload meanwhile is not overwritten.
-        updateMany: async (args: {
-          where: { id: string; updatedAt?: Date; insightsCachedText?: string };
-          data: Partial<UserRow>;
-        }) => {
-          const row = store.users.find((x) => x.id === args.where.id);
-          if (
-            row &&
-            args.where.insightsCachedText !== undefined &&
-            row.insightsCachedText !== args.where.insightsCachedText
-          ) {
-            return { count: 0 };
-          }
-          // Prisma stamps `@updatedAt` on every write that does not set it.
-          const data =
-            "updatedAt" in args.data
-              ? args.data
-              : { ...args.data, updatedAt: new Date() };
-          return base.updateMany({ ...args, data });
-        },
-      };
-    })(),
   };
   return {
     prisma: {
@@ -178,9 +138,6 @@ import {
 } from "@/lib/jobs/free-text-encryption-backfill";
 
 const KEY = "a".repeat(64);
-const CACHE = JSON.stringify({
-  dailyBriefing: { paragraph: "Your pressure eased after the new tablets." },
-});
 const TRACK = {
   type: "LineString",
   coordinates: [
@@ -268,21 +225,6 @@ beforeEach(() => {
     },
     { id: "r3", userId: "u2", geometry: TRACK, geometryEncrypted: null },
   ];
-  store.users = [
-    {
-      id: "u1",
-      userId: "u1",
-      insightsCachedText: CACHE,
-      insightsCachedTextEncrypted: null,
-      updatedAt: new Date("2026-03-01T07:00:00.000Z"),
-    },
-    {
-      id: "u2",
-      userId: "u2",
-      insightsCachedText: "other user",
-      insightsCachedTextEncrypted: null,
-    },
-  ];
 });
 
 afterEach(() => {
@@ -300,7 +242,6 @@ describe("runFreeTextEncryptionBackfillForUser", () => {
       routeGeometriesMigrated: 1,
       appointmentAddressesCleared: 0,
       contactAuditRowsScrubbed: 0,
-      insightsCachesMigrated: 1,
     });
 
     const c1 = store.conversations.find((r) => r.id === "c1")!;
@@ -404,52 +345,12 @@ describe("runFreeTextEncryptionBackfillForUser", () => {
       routeGeometriesMigrated: 0,
       appointmentAddressesCleared: 0,
       contactAuditRowsScrubbed: 0,
-      insightsCachesMigrated: 0,
     });
     expect(store.conversations.find((r) => r.id === "c1")!.titleEncrypted).toBe(
       sealed,
     );
   });
 
-  it("seals the cached insights payload, keeps updatedAt, and leaves another account's alone", async () => {
-    await runFreeTextEncryptionBackfillForUser("u1");
-    const u1 = store.users.find((r) => r.id === "u1")!;
-    expect(u1.insightsCachedText).toBeNull();
-    expect(u1.insightsCachedTextEncrypted).not.toBeNull();
-    // Sealed, not merely encoded: the bytes do not carry the prose.
-    expect(
-      Buffer.from(u1.insightsCachedTextEncrypted!).toString("utf8"),
-    ).not.toContain("pressure");
-    expect(openInsightsCachedText(u1)).toBe(CACHE);
-    // Profile forms use updatedAt as their concurrency token; a storage move
-    // must not invalidate an open form.
-    expect(u1.updatedAt).toEqual(new Date("2026-03-01T07:00:00.000Z"));
-    expect(store.users.find((r) => r.id === "u2")).toMatchObject({
-      insightsCachedText: "other user",
-      insightsCachedTextEncrypted: null,
-    });
-  });
-
-  it("does not overwrite a payload a warm sealed while the move was reading", async () => {
-    const newer = sealInsightsCachedText("newer");
-    const u1 = store.users.find((r) => r.id === "u1")!;
-    // The warm lands between the backfill's read and its write: the read
-    // returns the old readable value, the row then holds the newer sealed one.
-    const { prisma } = await import("@/lib/db");
-    const snapshot = { ...u1 };
-    const spy = vi.spyOn(prisma.user, "findUnique").mockImplementationOnce(((
-      _args: unknown,
-    ) => {
-      u1.insightsCachedText = null;
-      u1.insightsCachedTextEncrypted = newer;
-      return Promise.resolve(snapshot);
-    }) as never);
-    await runFreeTextEncryptionBackfillForUser("u1");
-    spy.mockRestore();
-    expect(u1.insightsCachedTextEncrypted).toBe(newer);
-    expect(openInsightsCachedText(u1)).toBe("newer");
-  });
-
   it("is fail-closed: without a key every readable row stays intact", async () => {
     vi.stubEnv("ENCRYPTION_KEY", "");
     vi.stubEnv("ENCRYPTION_KEYS", "");
diff --git a/src/lib/jobs/free-text-encryption-backfill.ts b/src/lib/jobs/free-text-encryption-backfill.ts
index 024861185..f7e7317d3 100644
--- a/src/lib/jobs/free-text-encryption-backfill.ts
+++ b/src/lib/jobs/free-text-encryption-backfill.ts
@@ -22,9 +22,9 @@
  * column holds a JSON null rather than SQL NULL has nothing to seal; it is set
  * to SQL NULL so discovery stops finding it.
  *
- * v1.43.7 adds the cached AI insights payload on the user row:
- * `User.insightsCachedText` -> `insightsCachedTextEncrypted` (the model's
- * briefing, per-domain readings and recommendations about the account).
+ * v1.43.7 sealed the cached AI insights payload on the user row the same
+ * way; v1.44.0 dropped its readable column (migration 0430), so that part of
+ * the pass is gone too.
  *
  * v1.42 (#615) added the environment module's coarse locations (home, dated
  * location periods, stored days). v1.43 dropped their readable columns
@@ -71,7 +71,6 @@ import { getGlobalBoss } from "@/lib/jobs/boss-instance";
 import { encryptToBytes } from "@/lib/ai/coach/bytes-codec";
 import { encryptNote } from "@/lib/crypto/note-cipher";
 import { encryptRouteGeometry } from "@/lib/workouts/route-geometry-cipher";
-import { sealInsightsCachedText } from "@/lib/insights/cached-text-cipher";
 
 export const FREE_TEXT_ENCRYPTION_BACKFILL_QUEUE =
   "free-text-encryption-backfill";
@@ -99,8 +98,6 @@ export interface FreeTextEncryptionBackfillSummary {
   appointmentAddressesCleared: number;
   /** v1.39.4 — edit audit rows whose old phone number / address was removed. */
   contactAuditRowsScrubbed: number;
-  /** v1.43.7 — cached AI insights payloads sealed (0 or 1 per account). */
-  insightsCachesMigrated: number;
 }
 
 /** The audit action whose older rows carried contact values. */
@@ -298,42 +295,6 @@ async function migrateRouteGeometry(id: string): Promise<boolean> {
   });
 }
 
-/**
- * Seal one account's cached AI insights payload into
- * `insightsCachedTextEncrypted` and null the readable column, atomically and
- * idempotently. The update is guarded on the readable value it read: a warm
- * that lands meanwhile writes the ciphertext and nulls the readable column, so
- * the guard misses and the newer payload is left as it is.
- */
-async function migrateInsightsCache(id: string): Promise<boolean> {
-  return prisma.$transaction(async (tx) => {
-    const fresh = await tx.user.findUnique({
-      where: { id },
-      select: { insightsCachedText: true, updatedAt: true },
-    });
-    if (!fresh || fresh.insightsCachedText === null) return false;
-    // FAIL-CLOSED: a key error throws here and rolls the tx back. A cache
-    // move is storage, not activity, so `updatedAt` is carried: the profile
-    // forms use it as their optimistic-concurrency token. Matching on it too
-    // means an edit that lands meanwhile wins; the row is retried next pass.
-    const { count } = await tx.user.updateMany({
-      where: {
-        id,
-        updatedAt: fresh.updatedAt,
-        insightsCachedText: fresh.insightsCachedText,
-      },
-      data: {
-        insightsCachedTextEncrypted: sealInsightsCachedText(
-          fresh.insightsCachedText,
-        ),
-        insightsCachedText: null,
-        updatedAt: fresh.updatedAt,
-      },
-    });
-    return count === 1;
-  });
-}
-
 /**
  * Walk one kind of row page by page, migrating each. `page` returns the ids
  * still holding a readable value; each migration clears it, so a migrated row
@@ -428,18 +389,6 @@ export async function runFreeTextEncryptionBackfillForUser(
     once,
   );
 
-  // One row at most: the cache is a single slot on the user row.
-  const insightsCachesMigrated = await drain(
-    () =>
-      prisma.user.findMany({
-        where: { id: userId, insightsCachedText: { not: null } },
-        select: { id: true },
-        take: 1,
-      }),
-    migrateInsightsCache,
-    once,
-  );
-
   // An appointment reminder's address is resolved from the practitioner when
   // it fires; the readable copy earlier releases wrote here goes.
   const appointmentAddressesCleared = (
@@ -463,7 +412,6 @@ export async function runFreeTextEncryptionBackfillForUser(
         route_geometries_migrated: routeGeometriesMigrated,
         appointment_addresses_cleared: appointmentAddressesCleared,
         contact_audit_rows_scrubbed: contactAuditRowsScrubbed,
-        insights_caches_migrated: insightsCachesMigrated,
       },
     },
   });
@@ -475,7 +423,6 @@ export async function runFreeTextEncryptionBackfillForUser(
     routeGeometriesMigrated,
     appointmentAddressesCleared,
     contactAuditRowsScrubbed,
-    insightsCachesMigrated,
   };
 }
 
@@ -530,10 +477,6 @@ export async function enqueueBootTimeFreeTextEncryptionBackfill(
         WHERE action = ${CONTACT_AUDIT_ACTION}
           AND user_id IS NOT NULL
           AND (details LIKE '%"location":%' OR details LIKE '%"phone":%')`,
-      // The 0411 partial index matches this predicate.
-      prisma.$queryRaw<{ user_id: string }[]>`
-        SELECT id AS user_id FROM users
-        WHERE insights_cached_text IS NOT NULL`,
     ]);
 
     const userIds = new Set<string>();
diff --git a/src/lib/profile/__tests__/health-facts.test.ts b/src/lib/profile/__tests__/health-facts.test.ts
index 8fb2c0a0b..2e3baf688 100644
--- a/src/lib/profile/__tests__/health-facts.test.ts
+++ b/src/lib/profile/__tests__/health-facts.test.ts
@@ -93,7 +93,6 @@ describe("encrypted health profile fact revisions", () => {
       where: { id: "user-1" },
       data: {
         insightsCachedAt: null,
-        insightsCachedText: null,
         insightsCachedTextEncrypted: null,
         insightsCachedLocale: null,
       },
@@ -133,7 +132,6 @@ describe("encrypted health profile fact revisions", () => {
       where: { id: "user-1" },
       data: {
         insightsCachedAt: null,
-        insightsCachedText: null,
         insightsCachedTextEncrypted: null,
         insightsCachedLocale: null,
       },
@@ -199,7 +197,6 @@ describe("encrypted health profile fact revisions", () => {
       where: { id: "user-1" },
       data: {
         insightsCachedAt: null,
-        insightsCachedText: null,
         insightsCachedTextEncrypted: null,
         insightsCachedLocale: null,
       },
@@ -247,7 +244,6 @@ describe("encrypted health profile fact revisions", () => {
       where: { id: "user-1" },
       data: {
         insightsCachedAt: null,
-        insightsCachedText: null,
         insightsCachedTextEncrypted: null,
         insightsCachedLocale: null,
       },
diff --git a/tests/integration/ai-optional-actions.test.ts b/tests/integration/ai-optional-actions.test.ts
index 5a29d565a..255b4467a 100644
--- a/tests/integration/ai-optional-actions.test.ts
+++ b/tests/integration/ai-optional-actions.test.ts
@@ -24,6 +24,7 @@ import {
   type StateName,
 } from "./ai-optional-fixtures";
 import { getPrismaClient } from "./setup";
+import { sealInsightsCachedText } from "@/lib/insights/cached-text-cipher";
 
 vi.mock("next/headers", async () => {
   const { cookieJar, headerJar } = await import("./mock-next-headers");
@@ -172,9 +173,11 @@ describe("insights/generate refuses by the briefing capability", () => {
       data: {
         // The read resolves (never calls) the chain, so the key must decrypt.
         aiAnthropicKeyEncrypted: encrypt("sk-ant-integration"),
-        insightsCachedText: JSON.stringify({
-          dailyBriefing: { paragraph: "Held text.", keyFindings: [] },
-        }),
+        insightsCachedTextEncrypted: sealInsightsCachedText(
+          JSON.stringify({
+            dailyBriefing: { paragraph: "Held text.", keyFindings: [] },
+          }),
+        ),
         insightsCachedAt: new Date(),
         insightsCachedLocale: "en",
       },
diff --git a/tests/integration/ai-optional-mixed-routes.test.ts b/tests/integration/ai-optional-mixed-routes.test.ts
index 4529cae12..2475a1ab5 100644
--- a/tests/integration/ai-optional-mixed-routes.test.ts
+++ b/tests/integration/ai-optional-mixed-routes.test.ts
@@ -23,6 +23,7 @@ import {
   type StateName,
 } from "./ai-optional-fixtures";
 import { getPrismaClient } from "./setup";
+import { sealInsightsCachedText } from "@/lib/insights/cached-text-cipher";
 
 vi.mock("next/headers", async () => {
   const { cookieJar, headerJar } = await import("./mock-next-headers");
@@ -94,10 +95,12 @@ async function seed(recordId: string): Promise<void> {
     where: { id: recordId },
     data: {
       // Generated now: only text written today is served as today's read.
-      insightsCachedText: JSON.stringify({
-        ...BRIEFING,
-        briefingGeneratedAt: new Date().toISOString(),
-      }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({
+          ...BRIEFING,
+          briefingGeneratedAt: new Date().toISOString(),
+        }),
+      ),
       insightsCachedAt: new Date(),
       insightsCachedLocale: "en",
     },
diff --git a/tests/integration/briefing-cache-locale.test.ts b/tests/integration/briefing-cache-locale.test.ts
index 0469710b9..8589571c3 100644
--- a/tests/integration/briefing-cache-locale.test.ts
+++ b/tests/integration/briefing-cache-locale.test.ts
@@ -13,6 +13,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { cookieJar, headerJar } from "./mock-next-headers";
 import { getPrismaClient, truncateAllTables } from "./setup";
+import { sealInsightsCachedText } from "@/lib/insights/cached-text-cipher";
 
 vi.mock("next/headers", async () => {
   const { cookieJar, headerJar } = await import("./mock-next-headers");
@@ -67,10 +68,12 @@ async function seedUserWithCachedBriefing(cachedLocale: string | null) {
       locale: "de",
       insightsCachedAt: new Date(),
       // Generated now: only text written today is served as today's read.
-      insightsCachedText: JSON.stringify({
-        dailyBriefing: BRIEFING,
-        briefingGeneratedAt: new Date().toISOString(),
-      }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({
+          dailyBriefing: BRIEFING,
+          briefingGeneratedAt: new Date().toISOString(),
+        }),
+      ),
       insightsCachedLocale: cachedLocale,
       // The briefing is shown only while its AI capability is available, so
       // the account has its own provider (presence only) and a receipt.
diff --git a/tests/integration/consent-withdrawal-purge.test.ts b/tests/integration/consent-withdrawal-purge.test.ts
index e80e75790..e18ea479c 100644
--- a/tests/integration/consent-withdrawal-purge.test.ts
+++ b/tests/integration/consent-withdrawal-purge.test.ts
@@ -20,6 +20,7 @@ import {
   purgeRegenerableAiText,
   withdrawConsent,
 } from "@/lib/consent/withdrawal";
+import { sealInsightsCachedText } from "@/lib/insights/cached-text-cipher";
 
 const BYTES = Buffer.from("ciphertext-stand-in", "utf8");
 
@@ -33,7 +34,9 @@ async function seed(username: string, kinds: string[]) {
     data: {
       username,
       email: `${username}@example.test`,
-      insightsCachedText: JSON.stringify({ briefing: "model prose" }),
+      insightsCachedTextEncrypted: sealInsightsCachedText(
+        JSON.stringify({ briefing: "model prose" }),
+      ),
       insightsCachedAt: new Date(),
       insightsSnapshotHash: "hash",
     },
@@ -153,7 +156,7 @@ async function snapshot(userId: string) {
     prisma.user.findUniqueOrThrow({
       where: { id: userId },
       select: {
-        insightsCachedText: true,
+        insightsCachedTextEncrypted: true,
         insightsCachedAt: true,
         insightsSnapshotHash: true,
       },
@@ -207,7 +210,7 @@ describe("withdrawing the analysis consent", () => {
 
     const after = await snapshot(user.id);
     expect(after.user).toEqual({
-      insightsCachedText: null,
+      insightsCachedTextEncrypted: null,
       insightsCachedAt: null,
       insightsSnapshotHash: null,
     });
diff --git a/tests/integration/free-text-encryption-backfill.test.ts b/tests/integration/free-text-encryption-backfill.test.ts
index d4743a457..beb3ef479 100644
--- a/tests/integration/free-text-encryption-backfill.test.ts
+++ b/tests/integration/free-text-encryption-backfill.test.ts
@@ -30,6 +30,7 @@ import {
   runFreeTextEncryptionBackfillForUser,
 } from "@/lib/jobs/free-text-encryption-backfill";
 import {
+  INSIGHTS_CACHE_SELECT,
   insightsCacheWrite,
   openInsightsCachedText,
 } from "@/lib/insights/cached-text-cipher";
@@ -498,73 +499,31 @@ describe("free-text encryption backfill (real Postgres)", () => {
     expect(second.sent).toEqual([]);
   });
 
-  it("seals the cached insights payload, keeps updatedAt, and converges", async () => {
+  it("has no readable insights cache left after migration 0430", async () => {
     const prisma = getPrismaClient();
-    await Promise.all([seedUser("ic-a"), seedUser("ic-b"), seedUser("ic-c")]);
-    const payload = JSON.stringify({
-      dailyBriefing: { paragraph: "Pressure eased this week." },
-    });
-    // ic-a: written by the previous release, in the clear.
+    const columns = await prisma.$queryRaw<{ column_name: string }[]>`
+      SELECT column_name FROM information_schema.columns
+      WHERE table_name = 'users' AND column_name LIKE 'insights_cached_text%'
+      ORDER BY column_name`;
+    expect(columns.map((c) => c.column_name)).toEqual([
+      "insights_cached_text_encrypted",
+    ]);
+    const indexes = await prisma.$queryRaw<{ indexname: string }[]>`
+      SELECT indexname FROM pg_indexes
+      WHERE indexname = 'users_insights_cached_text_backfill_idx'`;
+    expect(indexes).toEqual([]);
+
+    // The sealed column still round-trips through the one module.
+    await seedUser("ic-a");
     await prisma.user.update({
       where: { id: "ic-a" },
-      data: { insightsCachedText: payload },
-    });
-    // ic-b: written the current way.
-    await prisma.user.update({
-      where: { id: "ic-b" },
       data: insightsCacheWrite("current"),
     });
-    const before = await prisma.user.findUniqueOrThrow({
+    const row = await prisma.user.findUniqueOrThrow({
       where: { id: "ic-a" },
-      select: { updatedAt: true },
+      select: INSIGHTS_CACHE_SELECT,
     });
-
-    const { boss, sent } = makeCapturingBoss();
-    setGlobalBoss(boss as never);
-    const discovered = await enqueueBootTimeFreeTextEncryptionBackfill();
-    expect(discovered.error).toBeNull();
-    expect(sent.map((s) => s.userId)).toEqual(["ic-a"]);
-
-    const summary = await runFreeTextEncryptionBackfillForUser("ic-a");
-    expect(summary.insightsCachesMigrated).toBe(1);
-
-    const rowA = await prisma.user.findUniqueOrThrow({
-      where: { id: "ic-a" },
-      select: {
-        insightsCachedText: true,
-        insightsCachedTextEncrypted: true,
-        updatedAt: true,
-      },
-    });
-    expect(rowA.insightsCachedText).toBeNull();
-    expect(rowA.insightsCachedTextEncrypted).not.toBeNull();
-    expect(openInsightsCachedText(rowA)).toBe(payload);
-    expect(rowA.updatedAt).toEqual(before.updatedAt);
-
-    const rowB = await prisma.user.findUniqueOrThrow({
-      where: { id: "ic-b" },
-      select: { insightsCachedText: true, insightsCachedTextEncrypted: true },
-    });
-    expect(openInsightsCachedText(rowB)).toBe("current");
-
-    const again = await runFreeTextEncryptionBackfillForUser("ic-a");
-    expect(again.insightsCachesMigrated).toBe(0);
-    const second = makeCapturingBoss();
-    setGlobalBoss(second.boss as never);
-    await enqueueBootTimeFreeTextEncryptionBackfill();
-    expect(second.sent).toEqual([]);
-  });
-
-  it("has the partial index migration 0411 adds", async () => {
-    const indexes = await getPrismaClient().$queryRaw<
-      { indexname: string; indexdef: string }[]
-    >`
-      SELECT indexname, indexdef FROM pg_indexes
-      WHERE indexname = 'users_insights_cached_text_backfill_idx'`;
-    expect(indexes).toHaveLength(1);
-    expect(indexes[0].indexdef).toContain(
-      "WHERE (insights_cached_text IS NOT NULL)",
-    );
+    expect(openInsightsCachedText(row)).toBe("current");
   });
 
   it("has the partial indexes migration 0361 adds", async () => {
diff --git a/tests/integration/insights-provider-chain.test.ts b/tests/integration/insights-provider-chain.test.ts
index aff86654d..017d27094 100644
--- a/tests/integration/insights-provider-chain.test.ts
+++ b/tests/integration/insights-provider-chain.test.ts
@@ -288,7 +288,7 @@ describe("POST /api/insights/generate — chain fallback", () => {
     const prisma = getPrismaClient();
     await prisma.user.update({
       where: { username: "chain-user" },
-      data: { insightsCachedAt: null, insightsCachedText: null },
+      data: { insightsCachedAt: null, insightsCachedTextEncrypted: null },
     });
 
     // Second call: cache should reorder so Anthropic is the first
diff --git a/tests/integration/sharing-front-door.test.ts b/tests/integration/sharing-front-door.test.ts
index 04ebedfe0..16f1a0d28 100644
--- a/tests/integration/sharing-front-door.test.ts
+++ b/tests/integration/sharing-front-door.test.ts
@@ -33,6 +33,7 @@ import { NextRequest } from "next/server";
 
 import { cookieJar, headerJar } from "./mock-next-headers";
 import { getPrismaClient, truncateAllTables, switchSessionTo } from "./setup";
+import { sealInsightsCachedText } from "@/lib/insights/cached-text-cipher";
 
 vi.mock("next/headers", async () => {
   const { cookieJar, headerJar } = await import("./mock-next-headers");
@@ -292,7 +293,9 @@ frontDoorRead("GET /api/daily/digest", {
     await getPrismaClient().user.update({
       where: { id: userId },
       data: {
-        insightsCachedText: cachedBriefing(marker),
+        insightsCachedTextEncrypted: sealInsightsCachedText(
+          cachedBriefing(marker),
+        ),
         insightsCachedAt: new Date(),
         ...ownProvider(),
       },

From 07f9615dbaed93c234e66f0aed224ce2c574435f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Wed, 21 Oct 2026 19:36:06 +0200
Subject: [PATCH 2/8] feat(ops): name 1536 MB as the supported memory floor

The getting-started requirements now say a host needs 3 GB of RAM, 4 GB
recommended, and drop the advice to lower APP_MEMORY_LIMIT to 1g on a
2 GB host. The compose and .env example comments say the same.

At boot the app reads its cgroup memory limit (v2, then v1) and logs one
line when it is below MEMORY_FLOOR_MB. The support report adds the
container limit and a note below the floor, and Admin > System status
shows "below the supported floor" next to the existing low-heap flag.
The app keeps running either way.
---
 .env.production.example                       |  8 +-
 docker-compose.yml                            |  7 +-
 docs/self-hosting/getting-started.md          | 18 ++--
 messages/de.json                              |  1 +
 messages/en.json                              |  1 +
 messages/es.json                              |  1 +
 messages/fr.json                              |  1 +
 messages/it.json                              |  1 +
 messages/ko.json                              |  1 +
 messages/nl.json                              |  1 +
 messages/pl.json                              |  1 +
 .../api/admin/status/__tests__/route.test.ts  | 43 +++++++++-
 src/app/api/admin/status/route.ts             | 18 +++-
 src/components/admin/_shared.tsx              | 15 +++-
 .../admin/system-status-section.tsx           | 19 ++++-
 src/instrumentation.ts                        |  9 ++
 .../support/__tests__/memory-floor.test.ts    | 69 ++++++++++++++++
 .../support-report-redaction.test.ts          | 25 ++++++
 src/lib/support/heap-limit.ts                 | 82 +++++++++++++++++++
 src/lib/support/report.ts                     | 18 ++++
 20 files changed, 313 insertions(+), 26 deletions(-)
 create mode 100644 src/lib/support/__tests__/memory-floor.test.ts

diff --git a/.env.production.example b/.env.production.example
index 0428201a7..ecf31e293 100644
--- a/.env.production.example
+++ b/.env.production.example
@@ -533,9 +533,11 @@ API_TOKEN_HMAC_KEY="<openssl rand -hex 32>"
 # TRUST_CF_CONNECTING_IP="1"
 
 # Memory cap of the app container (read by docker-compose.yml, not by the app).
-# Node sizes its heap from it: 1536m (the default) gives 792 MB, 1g only 524 MB,
-# which a long-used account fills in normal operation. Lower it on a host with
-# 2 GB or less, raise it on a busy instance.
+# Node sizes its heap from it: 1536m (the default) gives 792 MB. 1536m is the
+# supported floor: below it a long-used account fills the heap in normal
+# operation, and the boot log, the support report and Admin > System status
+# say the app runs below the supported floor. The host needs 3 GB of RAM,
+# 4 GB recommended. Raise it on a busy instance; do not lower it.
 # APP_MEMORY_LIMIT="1536m"
 
 # -----------------------------------------------------------------------------
diff --git a/docker-compose.yml b/docker-compose.yml
index fb778bee4..af4954609 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -503,9 +503,10 @@ services:
     # workload can grow large enough to starve Postgres on a shared host.
     # Node sizes its heap from this limit: 1g gives a 524 MB heap, which a
     # long-used account fills in normal operation, so garbage collection
-    # stalls requests for seconds. 1536m gives 792 MB. The support report and
-    # Admin > System status flag a heap below 700 MB. On a host with 2 GB or less, lower it with
-    # APP_MEMORY_LIMIT in .env; on a busy instance, raise it.
+    # stalls requests for seconds. 1536m gives 792 MB and is the supported
+    # floor (host: 3 GB RAM, 4 GB recommended). Below it the boot log, the
+    # support report and Admin > System status say so. On a busy instance,
+    # raise it with APP_MEMORY_LIMIT in .env; do not lower it.
     mem_limit: "${APP_MEMORY_LIMIT:-1536m}"
     healthcheck:
       test:
diff --git a/docs/self-hosting/getting-started.md b/docs/self-hosting/getting-started.md
index e9ee7aa1f..0541c2333 100644
--- a/docs/self-hosting/getting-started.md
+++ b/docs/self-hosting/getting-started.md
@@ -11,14 +11,16 @@ already installed, longer if a TLS-fronted public hostname is in scope
   pulls a multi-arch image from GitHub Container Registry (linux/amd64
   - linux/arm64), so a Raspberry Pi 5 or an x86 VPS both work
     unchanged.
-- **2 GB RAM, 10 GB free disk.** The Postgres data volume grows with
-  measurement history; the Apple Health import worker can briefly
-  hold a 1.5 GB upload in `/tmp` while it parses. The app container is
-  capped at `APP_MEMORY_LIMIT`, `1536m` by default (Node then sizes its
-  heap at about 792 MB). On a 2 GB host that leaves too little for
-  Postgres and the system, so set `APP_MEMORY_LIMIT=1g` in `.env`
-  (a heap of about 524 MB); a long-used account then runs closer to
-  that heap, and the support report and Admin > System status say so.
+- **3 GB RAM (4 GB recommended), 10 GB free disk.** The Postgres data
+  volume grows with measurement history; the Apple Health import worker
+  can briefly hold a 1.5 GB upload in `/tmp` while it parses. The app
+  container is capped at `APP_MEMORY_LIMIT`, `1536m` by default (Node
+  then sizes its heap at about 792 MB), and Postgres and the system need
+  the rest. 1536 MB is the supported floor for the app container: do not
+  lower it to fit a smaller host. Below it, a long-used account or a large
+  import can fill the heap and restart the app; the app still starts, but
+  the boot log, the support report and Admin > System status say it runs
+  below the supported floor. On a busy instance, raise it.
 - **Outbound HTTPS** to `ghcr.io` (image pulls) plus whichever
   integration endpoints you plan to enable (Withings, OpenAI, etc.).
   The opt-in environmental-context module additionally reaches
diff --git a/messages/de.json b/messages/de.json
index b8afe311c..ba1ca12ef 100644
--- a/messages/de.json
+++ b/messages/de.json
@@ -7600,6 +7600,7 @@
     "heapLimitLabel": "Heap-Grenze",
     "heapLimitValue": "{mb} MB",
     "heapLimitLow": "{mb} MB, zu knapp. APP_MEMORY_LIMIT=1536m in .env setzen",
+    "memoryBelowFloor": "Container {mb} MB, unter der unterstützten Untergrenze von {floor} MB. APP_MEMORY_LIMIT={floor}m in .env setzen",
     "offlineGeoOff": "Aus",
     "offlineGeoChosen": "Online ({host})",
     "apiGlobal": "API-Endpunkte und API-Tokens erlauben.",
diff --git a/messages/en.json b/messages/en.json
index 8ec8c0e61..3a6dfe846 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -7600,6 +7600,7 @@
     "heapLimitLabel": "Heap limit",
     "heapLimitValue": "{mb} MB",
     "heapLimitLow": "{mb} MB, low. Set APP_MEMORY_LIMIT=1536m in .env",
+    "memoryBelowFloor": "Container {mb} MB, below the supported floor of {floor} MB. Set APP_MEMORY_LIMIT={floor}m in .env",
     "offlineGeoOff": "Off",
     "offlineGeoChosen": "Online ({host})",
     "apiGlobal": "Allow API endpoints and API tokens.",
diff --git a/messages/es.json b/messages/es.json
index 80928dc2d..0196a1f7b 100644
--- a/messages/es.json
+++ b/messages/es.json
@@ -7600,6 +7600,7 @@
     "heapLimitLabel": "Límite de heap",
     "heapLimitValue": "{mb} MB",
     "heapLimitLow": "{mb} MB, escaso: define APP_MEMORY_LIMIT=1536m en .env",
+    "memoryBelowFloor": "Contenedor {mb} MB, por debajo del mínimo admitido de {floor} MB: define APP_MEMORY_LIMIT={floor}m en .env",
     "offlineGeoOff": "Desactivado",
     "offlineGeoChosen": "En línea ({host})",
     "apiGlobal": "Permitir endpoints de API y tokens de API.",
diff --git a/messages/fr.json b/messages/fr.json
index 4f7058a57..d7109278c 100644
--- a/messages/fr.json
+++ b/messages/fr.json
@@ -7600,6 +7600,7 @@
     "heapLimitLabel": "Limite du tas",
     "heapLimitValue": "{mb} Mo",
     "heapLimitLow": "{mb} Mo, trop juste : définissez APP_MEMORY_LIMIT=1536m dans .env",
+    "memoryBelowFloor": "Conteneur {mb} Mo, sous le minimum pris en charge de {floor} Mo : définissez APP_MEMORY_LIMIT={floor}m dans .env",
     "offlineGeoOff": "Désactivé",
     "offlineGeoChosen": "En ligne ({host})",
     "apiGlobal": "Autoriser les points de terminaison d'API et les jetons d'API.",
diff --git a/messages/it.json b/messages/it.json
index a1dc08274..91db78f4b 100644
--- a/messages/it.json
+++ b/messages/it.json
@@ -7600,6 +7600,7 @@
     "heapLimitLabel": "Limite heap",
     "heapLimitValue": "{mb} MB",
     "heapLimitLow": "{mb} MB, poco: imposta APP_MEMORY_LIMIT=1536m in .env",
+    "memoryBelowFloor": "Container {mb} MB, sotto il minimo supportato di {floor} MB: imposta APP_MEMORY_LIMIT={floor}m in .env",
     "offlineGeoOff": "Disattivato",
     "offlineGeoChosen": "Online ({host})",
     "apiGlobal": "Consentire endpoint API e token API.",
diff --git a/messages/ko.json b/messages/ko.json
index 8712f3f1a..0708547d5 100644
--- a/messages/ko.json
+++ b/messages/ko.json
@@ -7575,6 +7575,7 @@
     "heapLimitLabel": "힙 한도",
     "heapLimitValue": "{mb} MB",
     "heapLimitLow": "{mb} MB, 부족합니다. .env에 APP_MEMORY_LIMIT=1536m을 설정하세요",
+    "memoryBelowFloor": "컨테이너 {mb} MB, 지원 최소치 {floor} MB 미만입니다. .env에 APP_MEMORY_LIMIT={floor}m을 설정하세요",
     "offlineGeoOff": "꺼짐",
     "offlineGeoChosen": "온라인 ({host})",
     "apiGlobal": "API 엔드포인트와 API 토큰을 허용해요.",
diff --git a/messages/nl.json b/messages/nl.json
index dc0c5e5f0..c5e9d9a13 100644
--- a/messages/nl.json
+++ b/messages/nl.json
@@ -7600,6 +7600,7 @@
     "heapLimitLabel": "Heaplimiet",
     "heapLimitValue": "{mb} MB",
     "heapLimitLow": "{mb} MB, laag. Stel APP_MEMORY_LIMIT=1536m in via .env",
+    "memoryBelowFloor": "Container {mb} MB, onder het ondersteunde minimum van {floor} MB. Stel APP_MEMORY_LIMIT={floor}m in via .env",
     "offlineGeoOff": "Uit",
     "offlineGeoChosen": "Online ({host})",
     "apiGlobal": "API-endpoints en API-tokens toestaan.",
diff --git a/messages/pl.json b/messages/pl.json
index 625abe2a4..6d55a5d6d 100644
--- a/messages/pl.json
+++ b/messages/pl.json
@@ -7600,6 +7600,7 @@
     "heapLimitLabel": "Limit sterty",
     "heapLimitValue": "{mb} MB",
     "heapLimitLow": "{mb} MB, za mało: ustaw APP_MEMORY_LIMIT=1536m w .env",
+    "memoryBelowFloor": "Kontener {mb} MB, poniżej obsługiwanego minimum {floor} MB: ustaw APP_MEMORY_LIMIT={floor}m w .env",
     "offlineGeoOff": "Wyłączone",
     "offlineGeoChosen": "Online ({host})",
     "apiGlobal": "Zezwól na punkty końcowe API i tokeny API.",
diff --git a/src/app/api/admin/status/__tests__/route.test.ts b/src/app/api/admin/status/__tests__/route.test.ts
index 3bf2f8165..46a6b2a86 100644
--- a/src/app/api/admin/status/__tests__/route.test.ts
+++ b/src/app/api/admin/status/__tests__/route.test.ts
@@ -44,12 +44,19 @@ vi.mock("@/lib/jobs/worker-status", () => ({
   })),
 }));
 
-const heapMock = vi.hoisted(() => ({ mb: 792 }));
+const heapMock = vi.hoisted(() => ({
+  mb: 792,
+  container: 1536 as number | null,
+}));
 vi.mock("@/lib/support/heap-limit", async () => {
   const actual = await vi.importActual<
     typeof import("@/lib/support/heap-limit")
   >("@/lib/support/heap-limit");
-  return { ...actual, heapLimitMb: () => heapMock.mb };
+  return {
+    ...actual,
+    heapLimitMb: () => heapMock.mb,
+    containerMemoryLimitMb: () => heapMock.container,
+  };
 });
 
 const geoMock = vi.hoisted(() => ({
@@ -200,12 +207,40 @@ describe("GET /api/admin/status (integration health summary)", () => {
     const low = (await (await GET()).json()) as {
       data: { memory: { heapLimitMb: number; low: boolean } };
     };
-    expect(low.data.memory).toEqual({ heapLimitMb: 524, low: true });
+    expect(low.data.memory).toMatchObject({ heapLimitMb: 524, low: true });
     heapMock.mb = 792;
     const enough = (await (await GET()).json()) as {
       data: { memory: { heapLimitMb: number; low: boolean } };
     };
-    expect(enough.data.memory).toEqual({ heapLimitMb: 792, low: false });
+    expect(enough.data.memory).toMatchObject({ heapLimitMb: 792, low: false });
+  });
+
+  it("flags a container memory limit below the supported floor", async () => {
+    type Memory = {
+      containerLimitMb: number | null;
+      floorMb: number;
+      belowFloor: boolean;
+    };
+    heapMock.container = 1024;
+    const below = (await (await GET()).json()) as { data: { memory: Memory } };
+    expect(below.data.memory).toMatchObject({
+      containerLimitMb: 1024,
+      floorMb: 1536,
+      belowFloor: true,
+    });
+    heapMock.container = 1536;
+    const atFloor = (await (await GET()).json()) as {
+      data: { memory: Memory };
+    };
+    expect(atFloor.data.memory.belowFloor).toBe(false);
+    // No limit, or none readable: nothing to flag.
+    heapMock.container = null;
+    const none = (await (await GET()).json()) as { data: { memory: Memory } };
+    expect(none.data.memory).toMatchObject({
+      containerLimitMb: null,
+      belowFloor: false,
+    });
+    heapMock.container = 1536;
   });
 
   it("reports named failing queues through failingJobs only", async () => {
diff --git a/src/app/api/admin/status/route.ts b/src/app/api/admin/status/route.ts
index a8d9968d8..0cfd3a0c4 100644
--- a/src/app/api/admin/status/route.ts
+++ b/src/app/api/admin/status/route.ts
@@ -9,7 +9,13 @@ import {
   readFailingQueues,
 } from "@/lib/jobs/job-failures";
 import { readFileSync } from "node:fs";
-import { heapLimitMb, isHeapLimitLow } from "@/lib/support/heap-limit";
+import {
+  containerMemoryLimitMb,
+  heapLimitMb,
+  isBelowMemoryFloor,
+  isHeapLimitLow,
+  MEMORY_FLOOR_MB,
+} from "@/lib/support/heap-limit";
 import {
   geoLookupMode,
   geoProviderChosen,
@@ -77,6 +83,8 @@ export const GET = apiHandler(async () => {
   // The process's heap ceiling, and whether it is the 1 GB-container size
   // that a long-used account can fill (`heap-limit.ts`).
   const heapLimit = heapLimitMb();
+  // And the container's own limit against the supported floor.
+  const containerLimit = containerMemoryLimitMb();
 
   return apiSuccess({
     version: process.env.npm_package_version || "0.1.0",
@@ -85,7 +93,13 @@ export const GET = apiHandler(async () => {
     buildTime: BUILD_TIME,
     startTime: START_TIME,
     database: "connected",
-    memory: { heapLimitMb: heapLimit, low: isHeapLimitLow(heapLimit) },
+    memory: {
+      heapLimitMb: heapLimit,
+      low: isHeapLimitLow(heapLimit),
+      containerLimitMb: containerLimit,
+      floorMb: MEMORY_FLOOR_MB,
+      belowFloor: isBelowMemoryFloor(containerLimit),
+    },
     worker: {
       running: workerStatus.running,
       startedAt: workerStatus.startedAt,
diff --git a/src/components/admin/_shared.tsx b/src/components/admin/_shared.tsx
index 69f00d639..09bd986b8 100644
--- a/src/components/admin/_shared.tsx
+++ b/src/components/admin/_shared.tsx
@@ -61,8 +61,19 @@ export interface SystemStatus {
   buildTime: string;
   startTime: string;
   database: string;
-  /** The process's heap ceiling; `low` when it is below what a long-used account needs. */
-  memory: { heapLimitMb: number; low: boolean };
+  /**
+   * The process's heap ceiling; `low` when it is below what a long-used
+   * account needs. `containerLimitMb` is the container's memory limit
+   * (`null` when there is none or it cannot be read), `belowFloor` when it is
+   * under the supported floor of `floorMb`.
+   */
+  memory: {
+    heapLimitMb: number;
+    low: boolean;
+    containerLimitMb: number | null;
+    floorMb: number;
+    belowFloor: boolean;
+  };
   worker: WorkerStatus;
   /**
    * Queues whose jobs exhausted their retries recently. `null` means the
diff --git a/src/components/admin/system-status-section.tsx b/src/components/admin/system-status-section.tsx
index 8f520e46c..c23d4c0d9 100644
--- a/src/components/admin/system-status-section.tsx
+++ b/src/components/admin/system-status-section.tsx
@@ -164,11 +164,22 @@ export function SystemStatusSection() {
               icon={MemoryStick}
               label={t("admin.heapLimitLabel")}
               value={
-                status.memory.low
-                  ? t("admin.heapLimitLow", { mb: status.memory.heapLimitMb })
-                  : t("admin.heapLimitValue", { mb: status.memory.heapLimitMb })
+                status.memory.belowFloor && status.memory.containerLimitMb
+                  ? t("admin.memoryBelowFloor", {
+                      mb: status.memory.containerLimitMb,
+                      floor: status.memory.floorMb,
+                    })
+                  : status.memory.low
+                    ? t("admin.heapLimitLow", { mb: status.memory.heapLimitMb })
+                    : t("admin.heapLimitValue", {
+                        mb: status.memory.heapLimitMb,
+                      })
+              }
+              tone={
+                status.memory.belowFloor || status.memory.low
+                  ? "warning"
+                  : undefined
               }
-              tone={status.memory.low ? "warning" : undefined}
             />
             <StatusItem
               icon={Clock}
diff --git a/src/instrumentation.ts b/src/instrumentation.ts
index fd60e80d6..01de8ed80 100644
--- a/src/instrumentation.ts
+++ b/src/instrumentation.ts
@@ -70,6 +70,15 @@ export async function register() {
       // A diagnostic must never break boot.
     }
 
+    // One line when the container's memory limit is below the supported
+    // floor. The app keeps running.
+    try {
+      const { logMemoryFloorAtBoot } = await import("@/lib/support/heap-limit");
+      logMemoryFloorAtBoot();
+    } catch {
+      // A diagnostic must never break boot.
+    }
+
     const { shouldRunWorker } = await import("@/lib/process-type");
     if (!shouldRunWorker()) {
       // Split deployment: web requests still produce queue jobs, but this
diff --git a/src/lib/support/__tests__/memory-floor.test.ts b/src/lib/support/__tests__/memory-floor.test.ts
new file mode 100644
index 000000000..417b454a3
--- /dev/null
+++ b/src/lib/support/__tests__/memory-floor.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  containerMemoryLimitMb,
+  isBelowMemoryFloor,
+  logMemoryFloorAtBoot,
+  MEMORY_FLOOR_MB,
+  parseCgroupMemoryLimit,
+} from "@/lib/support/heap-limit";
+
+const MiB = 1024 * 1024;
+
+describe("memory floor", () => {
+  it("is the compose default", () => {
+    expect(MEMORY_FLOOR_MB).toBe(1536);
+  });
+
+  it("parses cgroup limit files", () => {
+    expect(parseCgroupMemoryLimit(`${1536 * MiB}\n`)).toBe(1536);
+    expect(parseCgroupMemoryLimit(`${1024 * MiB}`)).toBe(1024);
+    expect(parseCgroupMemoryLimit("max\n")).toBeNull();
+    // cgroup v1 reports "no limit" as a huge page-aligned sentinel.
+    expect(parseCgroupMemoryLimit("9223372036854771712")).toBeNull();
+    expect(parseCgroupMemoryLimit("")).toBeNull();
+    expect(parseCgroupMemoryLimit("garbage")).toBeNull();
+    expect(parseCgroupMemoryLimit("0")).toBeNull();
+  });
+
+  it("reads cgroup v2 first, then v1, and gives null without either", () => {
+    const files: Record<string, string> = {
+      "/sys/fs/cgroup/memory/memory.limit_in_bytes": `${1024 * MiB}`,
+    };
+    const read = (path: string) => {
+      if (path in files) return files[path];
+      throw new Error("ENOENT");
+    };
+    expect(containerMemoryLimitMb(read)).toBe(1024);
+    files["/sys/fs/cgroup/memory.max"] = `${2048 * MiB}`;
+    expect(containerMemoryLimitMb(read)).toBe(2048);
+    files["/sys/fs/cgroup/memory.max"] = "max";
+    expect(containerMemoryLimitMb(read)).toBeNull();
+    expect(
+      containerMemoryLimitMb(() => {
+        throw new Error("ENOENT");
+      }),
+    ).toBeNull();
+  });
+
+  it("flags only a known limit under the floor", () => {
+    expect(isBelowMemoryFloor(1024)).toBe(true);
+    expect(isBelowMemoryFloor(1535)).toBe(true);
+    expect(isBelowMemoryFloor(1536)).toBe(false);
+    expect(isBelowMemoryFloor(4096)).toBe(false);
+    expect(isBelowMemoryFloor(null)).toBe(false);
+  });
+
+  it("logs exactly one line at boot below the floor, none otherwise", () => {
+    const warn = vi.fn();
+    expect(logMemoryFloorAtBoot(1024, warn)).toBe(1024);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][0]).toMatch(
+      /^\[boot\] The container memory limit of 1024 MB is below the supported floor of 1536 MB\./,
+    );
+    expect(warn.mock.calls[0][0]).not.toContain("\n");
+    warn.mockClear();
+    logMemoryFloorAtBoot(1536, warn);
+    logMemoryFloorAtBoot(null, warn);
+    expect(warn).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/lib/support/__tests__/support-report-redaction.test.ts b/src/lib/support/__tests__/support-report-redaction.test.ts
index 72bc7f1ea..f42c18c92 100644
--- a/src/lib/support/__tests__/support-report-redaction.test.ts
+++ b/src/lib/support/__tests__/support-report-redaction.test.ts
@@ -57,6 +57,7 @@ function seededFacts(): SupportReportFacts {
       node: "v22.11.0",
       processType: "web,worker",
       heapLimitMb: 792,
+      containerMemoryLimitMb: 1536,
       uptimeSeconds: 7260,
     },
     database: {
@@ -219,6 +220,30 @@ describe("support report redaction", () => {
     expect(enough).not.toContain("Heap limit note");
   });
 
+  it("says when the container runs below the supported memory floor", () => {
+    const facts = seededFacts();
+    const below = redactSupportText(
+      renderSupportReport({
+        ...facts,
+        build: { ...facts.build, containerMemoryLimitMb: 1024 },
+      }),
+      CONTEXT,
+    );
+    expect(below).toContain("- Container memory limit: 1024 MB");
+    expect(below).toContain(
+      "- Memory note: Below the supported floor. The container memory limit of 1024 MB is below the supported floor of 1536 MB.",
+    );
+    const atFloor = renderSupportReport(facts);
+    expect(atFloor).toContain("- Container memory limit: 1536 MB");
+    expect(atFloor).not.toContain("Memory note");
+    const unknown = renderSupportReport({
+      ...facts,
+      build: { ...facts.build, containerMemoryLimitMb: null },
+    });
+    expect(unknown).toContain("- Container memory limit: none or unreadable");
+    expect(unknown).not.toContain("Memory note");
+  });
+
   it("the seeds really are in the unredacted text", () => {
     const raw = renderSupportReport(seededFacts());
     for (const value of FORBIDDEN) expect(raw).toContain(value);
diff --git a/src/lib/support/heap-limit.ts b/src/lib/support/heap-limit.ts
index 80f0dcfc6..dcf6a512b 100644
--- a/src/lib/support/heap-limit.ts
+++ b/src/lib/support/heap-limit.ts
@@ -9,6 +9,7 @@
  * system status say so in one sentence, because the number alone ("Heap
  * limit: 524 MB") reads as a fact rather than as the cause (#1239).
  */
+import { readFileSync } from "node:fs";
 import { getHeapStatistics } from "node:v8";
 
 /** Below this, the heap is flagged. Between the 1g (524) and 1536m (792) heaps. */
@@ -38,3 +39,84 @@ export function lowHeapLimitAdvice(limitMb: number): string {
     "docker compose up -d."
   );
 }
+
+/**
+ * The smallest container memory limit HealthLog supports: the compose
+ * default. Below it the heap is too small for a long-used account and a
+ * large import, so the boot log, the support report and Admin > System
+ * status say the host runs below the supported floor. The app keeps
+ * running; the floor is advice, not a gate.
+ */
+export const MEMORY_FLOOR_MB = 1536;
+
+/**
+ * The cgroup files that hold a container's memory limit: cgroup v2 first,
+ * then v1. A v1 host without a limit reports a huge sentinel value rather
+ * than "max", so anything at or above 1 TiB counts as unlimited.
+ */
+const CGROUP_LIMIT_FILES = [
+  "/sys/fs/cgroup/memory.max",
+  "/sys/fs/cgroup/memory/memory.limit_in_bytes",
+] as const;
+const UNLIMITED_BYTES = 1024 ** 4;
+
+/** Parse one cgroup limit file's content; `null` for no limit or garbage. */
+export function parseCgroupMemoryLimit(raw: string): number | null {
+  const text = raw.trim();
+  if (text === "" || text === "max") return null;
+  if (!/^\d+$/.test(text)) return null;
+  const bytes = Number(text);
+  if (!Number.isFinite(bytes) || bytes <= 0 || bytes >= UNLIMITED_BYTES) {
+    return null;
+  }
+  return megabytes(bytes);
+}
+
+/**
+ * This process's container memory limit in megabytes, or `null` when there
+ * is none or it cannot be read (no cgroup, not Linux, unlimited).
+ */
+export function containerMemoryLimitMb(
+  read: (path: string) => string = (path) => readFileSync(path, "utf8"),
+): number | null {
+  for (const file of CGROUP_LIMIT_FILES) {
+    let raw: string;
+    try {
+      raw = read(file);
+    } catch {
+      continue;
+    }
+    return parseCgroupMemoryLimit(raw);
+  }
+  return null;
+}
+
+/** Whether a known container limit is below the supported floor. */
+export function isBelowMemoryFloor(limitMb: number | null): boolean {
+  return limitMb !== null && limitMb < MEMORY_FLOOR_MB;
+}
+
+/** The sentence the boot log and the support report use for it. */
+export function memoryFloorAdvice(limitMb: number): string {
+  return (
+    `The container memory limit of ${limitMb} MB is below the supported ` +
+    `floor of ${MEMORY_FLOOR_MB} MB. HealthLog keeps running, but a ` +
+    "long-used account or a large import can fill the heap and restart " +
+    `the app. Set APP_MEMORY_LIMIT=${MEMORY_FLOOR_MB}m or more in .env and ` +
+    "run docker compose up -d; the host needs 3 GB of RAM, 4 GB recommended."
+  );
+}
+
+/**
+ * Log one line at boot when the container runs below the floor. Never
+ * throws. Returns the limit it found, for tests.
+ */
+export function logMemoryFloorAtBoot(
+  limitMb: number | null = containerMemoryLimitMb(),
+  warn: (line: string) => void = console.warn,
+): number | null {
+  if (isBelowMemoryFloor(limitMb)) {
+    warn(`[boot] ${memoryFloorAdvice(limitMb as number)}`);
+  }
+  return limitMb;
+}
diff --git a/src/lib/support/report.ts b/src/lib/support/report.ts
index 1160b0327..d186ee20b 100644
--- a/src/lib/support/report.ts
+++ b/src/lib/support/report.ts
@@ -22,10 +22,13 @@
 import { prisma } from "@/lib/db";
 import { failureCondition } from "@/lib/jobs/failure-condition";
 import {
+  containerMemoryLimitMb,
   heapLimitMb,
+  isBelowMemoryFloor,
   isHeapLimitLow,
   lowHeapLimitAdvice,
   megabytes,
+  memoryFloorAdvice,
 } from "@/lib/support/heap-limit";
 import { shouldEmitSecureCookie } from "@/lib/auth/secure-cookie";
 import { isOidcConfigured, isOidcOnly } from "@/lib/auth/oidc";
@@ -85,6 +88,8 @@ export interface SupportReportFacts {
     node: string;
     processType: string;
     heapLimitMb: number;
+    /** The container's memory limit; `null` when there is none or it cannot be read. */
+    containerMemoryLimitMb: number | null;
     uptimeSeconds: number;
   };
   database: {
@@ -617,6 +622,7 @@ export async function collectSupportReportFacts(
       node: process.version,
       processType: getProcessType(),
       heapLimitMb: heapLimitMb(),
+      containerMemoryLimitMb: containerMemoryLimitMb(),
       uptimeSeconds: Math.round(process.uptime()),
     },
     database,
@@ -730,6 +736,18 @@ export function renderSupportReport(facts: SupportReportFacts): string {
   row("Built at", facts.build.builtAt);
   row("Node", facts.build.node);
   row("Process type", facts.build.processType);
+  row(
+    "Container memory limit",
+    facts.build.containerMemoryLimitMb === null
+      ? "none or unreadable"
+      : `${facts.build.containerMemoryLimitMb} MB`,
+  );
+  if (isBelowMemoryFloor(facts.build.containerMemoryLimitMb)) {
+    row(
+      "Memory note",
+      `Below the supported floor. ${memoryFloorAdvice(facts.build.containerMemoryLimitMb as number)}`,
+    );
+  }
   row("Heap limit", `${facts.build.heapLimitMb} MB`);
   if (isHeapLimitLow(facts.build.heapLimitMb)) {
     row("Heap limit note", lowHeapLimitAdvice(facts.build.heapLimitMb));

From d44af0646782b107f2ef02f55f0bb6373ab34346 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Wed, 21 Oct 2026 19:37:22 +0200
Subject: [PATCH 3/8] docs: publish the UI standards in docs/contributing

The binding UI rulebook (card anatomy, spacing scale, text colour,
tokens, primitive mapping, enforcement) lived outside the repository,
so a contributor could follow a code comment to a file they could not
open. It now lives at docs/contributing/ui-standards.md, every comment
that cited it points there, and the docs index and ui-guidelines.md
say which document wins when they disagree.
---
 docs/README.md                                |   6 +-
 docs/contributing/ui-standards.md             | 184 ++++++++++++++++++
 docs/ui-guidelines.md                         |   9 +-
 e2e/settings-overscroll.spec.ts               |   2 +-
 ...v137-sharing-managed-profiles-a11y.spec.ts |   2 +-
 eslint-plugins/healthlog/spacing-scale.js     |   4 +-
 .../sharing-recoverable-errors.test.tsx       |   2 +-
 src/app/achievements/page.tsx                 |   2 +-
 src/app/globals.css                           |   2 +-
 src/app/insights/workouts/[id]/page.tsx       |   2 +-
 .../charts/nutrient-daily-bar-chart.tsx       |   2 +-
 src/components/daily/today-hero.tsx           |   2 +-
 src/components/day/day-sections.tsx           |   2 +-
 .../insights/__tests__/hero-strip.test.tsx    |   2 +-
 .../sleep-stage-stacked-bar.test.tsx          |   2 +-
 .../chat-bubble-unverified-notice.test.tsx    |   2 +-
 .../insights/coach-panel/chat-bubble.tsx      |   4 +-
 src/components/insights/ecg-detail.tsx        |   2 +-
 src/components/insights/hero-strip.tsx        |   2 +-
 .../insights/insight-section-card.tsx         |   2 +-
 .../insights/intraday-pulse-chart.tsx         |   2 +-
 src/components/insights/labs-changes-card.tsx |   2 +-
 .../insights/medication-efficacy-summary.tsx  |   2 +-
 .../insights/nutrients/hydration-card.tsx     |   2 +-
 src/components/layout/auth-shell.tsx          |   2 +-
 src/components/layout/nav-model.ts            |   2 +-
 .../layout/shared-record-banner.tsx           |   2 +-
 .../medications/medication-order-editor.tsx   |   2 +-
 .../module-list/module-order-editor.tsx       |   2 +-
 .../mood/manage/tag-groups-card.tsx           |   2 +-
 .../mood/manage/tag-manager-card.tsx          |   2 +-
 src/components/onboarding/step-heading.tsx    |   2 +-
 .../managed-profile-affordances.test.tsx      |   6 +-
 .../settings/access/grant-action-error.tsx    |   2 +-
 .../settings/access/grant-invite-card.tsx     |   2 +-
 src/components/settings/access/grant-row.tsx  |   2 +-
 .../settings/access/managed-profile-card.tsx  |   8 +-
 .../access/managed-profile-create-form.tsx    |   2 +-
 .../access/managed-profile-edit-form.tsx      |   2 +-
 .../access/managed-profile-guardians.tsx      |   2 +-
 .../access/managed-profile-handover.tsx       |   2 +-
 .../settings/dashboard-layout-section.tsx     |   2 +-
 .../report-selection/report-scope-picker.tsx  |   2 +-
 .../settings/share-link-create-form.tsx       |   2 +-
 src/components/ui/query-error-row.tsx         |   2 +-
 tests/fixtures/v137/e2e-journeys.ts           |   2 +-
 46 files changed, 244 insertions(+), 55 deletions(-)
 create mode 100644 docs/contributing/ui-standards.md

diff --git a/docs/README.md b/docs/README.md
index 34465adf4..aabff21cc 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -56,7 +56,11 @@ notes, and machine-readable specs that ship alongside the source:
   — the iOS submission gate.
 - [`codex-protocol-spec.md`](./codex-protocol-spec.md) — Codex / ChatGPT
   OAuth protocol reverse-engineering notes.
-- [`ui-guidelines.md`](./ui-guidelines.md) — UI / a11y house style.
+- [`contributing/ui-standards.md`](./contributing/ui-standards.md) — the
+  binding UI standards: card anatomy, spacing, text colour, tokens and
+  which primitive to use where. Read before touching any surface.
+- [`ui-guidelines.md`](./ui-guidelines.md) — UI / a11y house style; where
+  it disagrees with the UI standards, the standards win.
 
 If you're a self-hoster looking to spin up an instance, start at
 <https://docs.healthlog.dev> or jump to the [Quick Start in the project
diff --git a/docs/contributing/ui-standards.md b/docs/contributing/ui-standards.md
new file mode 100644
index 000000000..f2c982788
--- /dev/null
+++ b/docs/contributing/ui-standards.md
@@ -0,0 +1,184 @@
+# 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 (over-scroll class, #154 lineage).** Only `AuthShell` owns the scroll container's height and bottom padding (`pb-20` wrapper + `<md` bottom-nav clearance on `<main>`). Pages/sections never add viewport-height reserves (`min-h-dvh`, `min-h-[calc(100dvh-…)]`), `h-full` chains, or bottom gutters inside the scrolling `<main>` — nested reserves stack on the shell budget and scroll past the last card. One sanctioned exception: the settings-shell grid floor (budget-derived, documented; retune it when shell paddings change). Lists that need their own scrolling use `max-h-* overflow-y-auto overscroll-contain`. Guard: `e2e/settings-overscroll.spec.ts`.
+
+- **Allowed steps:** `1 / 1.5 / 2 / 2.5 / 3 / 3.5 / 4 / 6 / 8 / 10`. `2.5` and `3.5` are allowed: the medication-card rhythm uses them docblock-sanctioned across ~78 sites and the in-between steps earn their keep in dense card interiors — reality wins over a sweep that would only churn settled surfaces. `5` (20 px) and `py-5`, `p-5` are banned in new code, swept on touch. `7` (28 px) is banned with them — it entered as the Settings/Admin `pl-7` body gutter and is gone (§13).
+- **Page frame:** exactly one authenticated container, owned by `AuthShell` (`layout/auth-shell.tsx:318`): `mx-auto max-w-screen-xl px-4 pt-6 pb-20 md:px-6`. Never re-implement it in a page; full-bleed pages opt out via a shell flag, not negative margins. Prose pages (about/privacy/legal): `mx-auto max-w-3xl px-4 py-8 md:px-6 md:py-12`.
+- **Page rhythm:** root of every page is `space-y-6`. Grouped card sections: `space-y-10` between groups, `space-y-4` inside a group (notifications/integrations pattern). Insights sub-pages join `space-y-6`.
+- **Left reading edge:** page-level text (H1, explainer, section headings) sits at the container edge. Only surfaces that paint a visible border/background may inset their content (`px-4 md:px-6`). A block without a border must not carry horizontal padding.
+- **Grids:** grids **of** cards/tiles = `gap-4`; value read-outs **inside** one card = `gap-x-3 gap-y-2`; form field grids = `gap-4`.
+- **Anchors:** `scroll-mt-28`, single token (31-to-1 in the tree already).
+
+## 3. Text colour rules
+
+The base tokens are AA-tuned in both themes (`--muted-foreground`: 5.0–6.4:1, documented in `globals.css`). The system is two tiers:
+
+- **`text-foreground` = content.** Everything the user came to read: values, chart labels the reading depends on, AI narrative bodies, consent/safety copy, and **all user-entered data** (notes, journal text, free-text fields). User data is never muted.
+- **`text-muted-foreground` = meta.** Timestamps, units, provenance, counts, placeholders, one-sentence descriptions under a heading. Heading-in-foreground + short-description-in-muted is the app-wide convention (CardDescription, PageHeader, SettingsCardHeader) — keep it; do not "fix" it to foreground.
+- **Description slots hold exactly one meta sentence, guideline ≤ 120 characters.** One sentence, one full stop, no paragraph stack. 120 characters is the guideline, not a hard cut: it is the p75 of the descriptions that already read well, and a description that needs 130 characters to stay true is fine while a two-sentence one never is. Multi-sentence explainer prose goes in the body as `<p className="text-sm">` (foreground), not into a muted description slot; if the body would not carry it either, the sentence is not needed on the surface at all and belongs in the docs. The description slot renders a single text run — it deliberately owns no vertical rhythm of its own, so a call site cannot stack paragraphs into it.
+- **One statement, one string.** A section's page subtitle and its card description must not say the same thing twice on one screen. When a section owns a single card, the subtitle carries the statement and the card header drops its description. Same rule for a field label and its field description: the label names the field, the description adds what the label cannot.
+- **FORBIDDEN: opacity modifiers on muted text.** `text-muted-foreground/70` ≈ 2.9–3.9:1 and `/80` ≈ 3.4–4.2:1 — below AA; 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)                                                                                                                                                   |
+| Date / time entry                                                                                                           | `DateField` / `TimeField` / `DateTimeField`                                                                                                                                                                                                                                                                                                                                                                 | native `type="date                                                                                                                                                                                    | time | datetime-local"` inputs (browser-locale trap, v1.25.4) |
+| Small text action inside a line (Open schedule, Select all, View all, Retry, Learn more)                                    | `InlineAction` (`ui/inline-action.tsx`) — tone `primary` / `muted` / `foreground`, size `xs` / `sm`, `asChild` for a `Link`; owns the focus ring and `pointer-coarse:min-h-11`                                                                                                                                                                                                                              | a hand-rolled underlined `<button>` / `<Link>` (`inline-action-guard.test.ts`)                                                                                                                        |
+| Mutually exclusive choice on one track (range, zoom, cards vs table, recent vs all)                                         | `Segmented` (`ui/segmented.tsx`) — no track, the chosen segment filled in primary (the chart tabs' look; a muted track with a raised segment was tried in 1.43.8 and dropped in 1.43.10 as too heavy); `mode="radio"` (default, roving focus) or `"toggle"` (view switches, form sheets), `iconOnly` for icon segments, `size="sm"` for range rows in a chart header; 44 px per segment on a coarse pointer | a row of ghost/secondary Buttons, a fifth segmented variant (`segmented.test.tsx` holds the definition to one module)                                                                                 |
+| A grade beside a reading (confidence, score gain, band, lab range flag)                                                     | `ScorePill` (`ui/score-pill.tsx`) — tone `success` / `info` / `warning` / `destructive` / `neutral`, `numeric` for figures; `CONFIDENCE_TONE` maps both confidence scales                                                                                                                                                                                                                                   | a hand-rolled `rounded-full px-2 py-0.5 text-xs bg-*/15` chip (`score-pill-guard.test.ts`); `TagChip` (neutral label) and `Badge` (connection/account state) stay what they are                       |
+| "This vital on these days vs those days" board                                                                              | `MetricCrosstab` (`insights/metric-crosstab.tsx`) — caller formats the numbers, the board owns row, neutral signed delta, confidence chip, dismissal                                                                                                                                                                                                                                                        | a fourth copy of the crosstab list                                                                                                                                                                    |
+| A trend / stat tile in a grid (KPI strip, derived tiles, their skeletons and building states)                               | `TrendTile` (`ui/trend-tile.tsx`)                                                                                                                                                                                                                                                                                                                                                                           | the hand-spelled `bg-card border-border … p-4 md:p-6` frame                                                                                                                                           |
+| A whole card that points to another page                                                                                    | `CrossLinkCard` (`insights/cross-link-card.tsx`)                                                                                                                                                                                                                                                                                                                                                            | a `Link` styled as a card                                                                                                                                                                             |
+| Picking documents from the vault                                                                                            | `DocumentPickerSheet` (`documents/document-picker-sheet.tsx`); the caller decides what a toggle means                                                                                                                                                                                                                                                                                                       | a copy of the search + list sheet                                                                                                                                                                     |
+| A field / chart / list with nothing to show                                                                                 | `EmptyState variant="plain" size="compact"` (with `action` for the next step), `ChartEmptyState` on a chart body                                                                                                                                                                                                                                                                                            | a hand-written muted paragraph (`empty-state-ratchet.test.ts` freezes each remaining site as `path: key`, and a new one fails; the frozen ones are field-level "not recorded" lines and editor hints) |
+| A number shown to a person                                                                                                  | `useFormatters()` (`fmt.number` / `integer` / `percent`), `formatBytes(bytes, locale)` from `lib/format/bytes`                                                                                                                                                                                                                                                                                              | `toFixed()`, a locale-less `toLocaleString()`, `String(a / b)` (`healthlog/no-unlocalised-decimal`)                                                                                                   |
+| Numeric range entry (0–10 self-rating, any bounded scale)                                                                   | `Slider` / `SliderField` (`ui/slider.tsx`) — `SliderField` when the scale has anchors, which is nearly always                                                                                                                                                                                                                                                                                               | a hand-rolled `input type="range"`, or an 11-button radiogroup (eleven 32 px targets overflow a 390 px viewport)                                                                                      |
+| Outbound fetch                                                                                                              | `safeFetch`                                                                                                                                                                                                                                                                                                                                                                                                 | raw `fetch(` (lint-enforced)                                                                                                                                                                          |
+| TanStack query keys                                                                                                         | `src/lib/query-keys/` factory                                                                                                                                                                                                                                                                                                                                                                               | bare arrays (lint-enforced)                                                                                                                                                                           |
+
+**What a failed read offers is decided by the primitive, never the call site.** `QueryErrorCard`, `QueryErrorRow` and `ChartErrorState` take the query's `error` (required) and branch on `readFailureKind` (`src/lib/api/read-failure.ts`). It reads `meta.errorCode` first and the status second, because every error envelope carries a code (`http.*` when the route names none): a step-up or re-proof code on a 401 is a failure with retry, not an ended session; an unknown code falls back to the status.
+
+- **Session ended** (a session code, or a 401 without a more specific one) → one sentence and a Sign in button (back to the current page). Never a silent blank.
+- **403, refused** → the surface's `refused` state if it has one, otherwise nothing. A refusal is an answer, not a failure; no retry.
+- **429, throttled** → one sentence that the read budget is spent, no retry (an immediate retry would only be refused again).
+- **anything else** → the surface's message with Retry.
+
+The `queryFn` hands the `ApiError` through untouched: no `try { … } catch { throw new Error(t(…)) }` around the fetch, the surface's sentence goes in through `message`. A call site does not inspect `error.status` around a read-failure primitive, and does not pass `error={null}`. `query-error-error-prop-guard.test.ts` enforces the prop and the untouched error at every site, `read-failure-markup-guard.test.ts` refuses hand-rolled failure markup next to a read hook. Error codes become sentences through `src/lib/i18n/translate-code.ts`, never through a `t(key) === key` probe at the call site (`translate-probe-guard.test.ts`).
+
+## 7. Enforcement
+
+Live, all at `error`: `healthlog/queryKey-factory`, `healthlog/safe-fetch-required`, `healthlog/api-fetch-required`, `healthlog/no-raw-palette-color` (palette + colour-shaped JS props + arbitrary values), `healthlog/no-dracula-utility`, `healthlog/spacing-scale` (`pt-`/`pb-` on `CardHeader`/`CardContent`, and the banned `5` step on a `bg-card` + `border` shell), `healthlog/no-raw-card-shell` (since v1.43.8: `bg-card` + `border` + `rounded-xl` on one literal under `src/components` / `src/app` outside `ui/`; the files where a shell is the point — shell primitives, the hero, popovers, the chart frame shared by chart/skeleton/error state, table frames, sign-in and first-run screens — are the rule's `allow` list in `eslint.config.mjs`, each with its reason, no inline escape), `healthlog/no-unlocalised-decimal` (since v1.43.8; reasoned `eslint-disable-next-line` only, for SVG coordinates and number-input values).
+
+Structural tests (since v1.43.8): `inline-action-guard`, `score-pill-guard`, `empty-state-ratchet`, `page-header-h1-guard`, `card-density`, `segmented` (one definition), `client-route-zod-guard` (documents and Coach ship no zod in their static client graph).
+
+Planned (until it lands, this is a review-checklist item):
+
+1. A tile-header icon-colour check (`text-muted-foreground` / `text-primary` on a glyph inside a `CardTitle` or tile-header row).
+
+**PR checklist for any UI change:** both themes checked visually · no new `dracula-*`/hex/opacity-muted · headers via a primitive · card gap untouched by slot padding · `isError` → `QueryErrorCard` or `QueryErrorRow` by surface, with `error` · mobile modal = `ResponsiveSheet` · `pnpm format` + `pnpm lint` + `pnpm typecheck` green.
+
+---
+
+## 8. Insights left reading edge — two edges, one gutter
+
+Every text run on an Insights surface starts on one of exactly two vertical lines, and card headings offset from the card line by exactly one gutter:
+
+- **Edge A — reading edge (x = 0):** the AuthShell container inner edge (`px-4 md:px-6`). All **borderless page-level blocks** start here with **no extra horizontal padding**: the sub-page `<h1>` + explainer (`SubPageShell`), and every `SectionHeading`. If a sub-page heading must track the card body instead, it uses the responsive card inset `px-4 md:px-6` — **never** a flat `px-6` (that sat 8 px right of the card body on mobile and reopened the heading-vs-body step).
+- **Edge B — card edge (x = card `px`):** every `<Card>` insets header **and** body to `px-4 md:px-6`. No card inset with a static `p-5` (banned) or a `p-4`-only/`sm:` shell — header and body share one inset so the body left edge is identical on every tile.
+- **Heading gutter (Edge B + gutter):** every card heading routes through `TileHeader`. The icon's left edge sits on Edge B; the heading **text** sits at Edge B + gutter (icon box + `gap-2` = 28 px at `size="default"`, 24 px at `size="sm"`). Compact tiles use `TileHeader size="sm"`, never a bespoke `h-4` icon row. Tile header icons are `text-foreground` (never muted, never an accent) at both sizes.
+
+Forbidden on any Insights card: a hand-rolled icon+title row, a card title centred by default, an icon box outside `TileHeader`'s h-5/h-4 vocabulary, and a horizontal inset other than `px-4 md:px-6` (or the sanctioned `p-3` dense inner tile). Verify at 390 px: every card body shares one left x; every card heading text shares a second x one gutter to the right; the `<h1>` + any `SectionHeading` sit on the container edge.
+
+## 9. One scroll floor — sub-shells never re-declare bottom-space
+
+Reinforces §2's "scroll height is shell-owned". Only `AuthShell` owns the scroll container's bottom padding and any viewport-height reserve: the `<main>` clears the mobile bottom-nav (`pb-[calc(4rem+safe-area)]`) and its wrapper clears the Coach FAB (`pb-20`). **No page, section, or sub-shell** adds a `min-h-[calc(100dvh-…)]` / `min-h-dvh` reserve or a `pb-*` bottom gutter inside the scrolling `<main>` — a nested reserve stacks on the shell budget and scrolls past the last card.
+
+A two-column sub-shell that needs a "don't jump while loading" floor derives it from **one shared source** — `SUB_SHELL_GRID_FLOOR` (`src/components/layout/shell-metrics.ts`) — applied to the **grid** (not a column), so the `1fr` content row stretches to fill without over-shooting. It never re-declares the floor per-shell (`AdminShell` drifting to a stale 12rem column reserve is exactly how this recurred). Guard: `e2e/settings-overscroll.spec.ts` covers Settings **and** Admin and measures against each element's content-box bottom, so a redundant sub-shell `pb-*` fails instead of inflating the allowed budget.
+
+## 10. Navigation — utilities live only in the user menu
+
+Settings + Notifications are **account utilities, not feature destinations**. They live ONLY in the user/avatar menu (mobile top-bar `DropdownMenu`; desktop sidebar avatar menu, with Settings additionally in the sidebar footer). The mobile "More" overflow hub carries **feature destinations only** (Measurements, Mood, Cycle, Labs, Coach, …) — never Settings or Notifications. The hub is `mobileMoreHubDestinations()` = `visibleNavDestinations` minus the primary slots (`/`, `/medications`, `/insights`); it does **not** append the utility tail. `NAV_UTILITY_DESTINATIONS` (`visibleUtilityDestinations()`) feeds the sidebar footer + user menus, not the mobile overflow. Never surface a utility in two menus reachable from the same screen.
+
+## 11. Inline action row — the PageHeader pattern
+
+A title/sentence with an adjacent action is one row, not a wrapping stack: `flex items-start justify-between gap-3`, the text `min-w-0 flex-1` (wraps internally), the action `shrink-0` (stays beside the text, never pushed to its own line). This is the canonical `PageHeader` / `TileHeader` (`right` slot) shape — reuse it (e.g. the dashboard-hero verdict + CTA) instead of a one-off `flex-wrap` row whose `gap-y-*` drops the action below on a full sentence. Keep the mobile tap-target floor (`min-h-11 sm:min-h-9`).
+
+## 12. The action row — one place, one shape
+
+A card's actions live in **one** row, and that row is the **last thing in the card**. Reference implementations: `src/components/settings/score-section.tsx`, `src/components/settings/coach-prefs-section.tsx`.
+
+- **Use `SettingsCardActions`** (`settings/_card-actions.tsx`). It owns the row: `flex flex-wrap items-center gap-2`, `justify-end` by default. Never hand-roll a `flex justify-end gap-2` div in a Settings or Admin card.
+- **Primary action:** last child of the row (rightmost), `variant` default, `size="sm"` + `min-h-11`. One per card.
+- **Secondary action:** `outline`, before the primary in the same row. Cancel/reset are secondary, never `ghost` in the same row as a primary.
+- **Destructive card-wide action:** the same row, `variant="destructive"`. Never hand-tinted (`text-destructive border-destructive/30` on an `outline` is drift).
+- **Nothing follows the action row.** Status lines, result lists, and confirmations belong **above** it; a result set large enough to need its own frame becomes its own card or a collapsible.
+- **The header `status` slot carries status, not actions** — a badge, a pill, a switch. Not a primary, not a destructive, not a filter group. Filters get a toolbar row above the content.
+- **`outline` has exactly one meaning: secondary.** A card whose only actions are deep links out (privacy, about, export) has no primary — those links stay `outline size="sm"` and the row uses `align="start"`, because a navigation row reads with the text, not against it. That is the one documented exception, and `SettingsCardActions` spells it (`align="start"`).
+
+## 13. Settings + Admin card rhythm — owned by the container
+
+- **`SettingsCard` is gap-based**, like `Card`: `flex flex-col gap-4 p-4 md:p-6`. The header→body distance comes from the container's gap. A call site never adds `mt-4` to its first body child, never `mb-4` to the header, never `space-y-4` to the card. A denser card overrides the gap on the card itself (`className="gap-2"`), exactly as `Card` does.
+- **The body starts at the card edge.** The old `pl-7` gutter (icon box + `gap-2`) is abolished: it is off-scale (§2 allows `1/1.5/2/3/4/6/8/10`), 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 Insights overview's heading, which is not an Insights component and moved out of that folder), 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 follow-up
+
+The `p-5` / `py-5` / `px-5` / `space-y-5` family is **zero** app-wide, and `healthlog/spacing-scale` runs at `error` over `src/components/**` + `src/app/**`, so the banned step cannot come back silently. `no-raw-card-shell` is live since v1.43.8 (see §7); what remains planned is the tile-header icon-colour check.
diff --git a/docs/ui-guidelines.md b/docs/ui-guidelines.md
index 4adc25d80..093a0ef35 100644
--- a/docs/ui-guidelines.md
+++ b/docs/ui-guidelines.md
@@ -1,9 +1,10 @@
 # HealthLog UI Guidelines
 
-> Single source of truth for visual & interaction patterns in the HealthLog
-> PWA. Consult this document before adding a new component, page, or
-> setting. If a pattern below doesn't fit your case, propose an addition
-> here in the same PR.
+> Visual & interaction patterns in the HealthLog PWA. The binding rules
+> for card anatomy, spacing, text colour, tokens and primitives live in
+> [`contributing/ui-standards.md`](./contributing/ui-standards.md); where
+> this document disagrees with them, the standards win. If a pattern
+> below doesn't fit your case, propose an addition in the same PR.
 
 Last updated: 2026-05-08 (v1.4 cycle)
 
diff --git a/e2e/settings-overscroll.spec.ts b/e2e/settings-overscroll.spec.ts
index 59f858dfc..28ce81634 100644
--- a/e2e/settings-overscroll.spec.ts
+++ b/e2e/settings-overscroll.spec.ts
@@ -135,7 +135,7 @@ test.describe("settings + admin vertical over-scroll guard", () => {
         expect(dims, "main-content / wrapper present").not.toBeNull();
         if (!dims) return;
 
-        // One-scroll-floor (UI-STANDARDS §9), structural half. `<main>` may
+        // One-scroll-floor (ui-standards.md §9), structural half. `<main>` may
         // only be the ONLY vertical scroll surface if it also OWNS the
         // containing block of its absolutely-positioned descendants: an
         // abspos box with no positioned ancestor resolves against the
diff --git a/e2e/v137-sharing-managed-profiles-a11y.spec.ts b/e2e/v137-sharing-managed-profiles-a11y.spec.ts
index a71afb7a8..219662de1 100644
--- a/e2e/v137-sharing-managed-profiles-a11y.spec.ts
+++ b/e2e/v137-sharing-managed-profiles-a11y.spec.ts
@@ -124,7 +124,7 @@ async function expectAnnounced(page: Page, selector: string) {
  * Copy somebody has to act on is content, not meta.
  *
  * Two halves, and both are needed. The class check is the design standard —
- * UI-STANDARDS §3 reserves `text-muted-foreground` for meta, and consent or
+ * ui-standards.md §3 reserves `text-muted-foreground` for meta, and consent or
  * safety text rendered as meta is text people skip. The ratio check is the
  * measurable one: it walks up for an opaque background and asserts the AA
  * floor for body text, so a future token change that keeps the class and
diff --git a/eslint-plugins/healthlog/spacing-scale.js b/eslint-plugins/healthlog/spacing-scale.js
index cb5f9418c..e20853455 100644
--- a/eslint-plugins/healthlog/spacing-scale.js
+++ b/eslint-plugins/healthlog/spacing-scale.js
@@ -50,7 +50,7 @@
  * `eslint-disable-next-line` with the reason — visible in review — rather
  * than a silent registry entry here.
  *
- * @see .planning/audits/2026-07-05-fable/UI-STANDARDS.md §1 + §2 + §7.
+ * @see docs/contributing/ui-standards.md §1 + §2 + §7.
  */
 
 "use strict";
@@ -181,7 +181,7 @@ const spacingScaleRule = {
       slotPadding:
         '"{{match}}" on <{{element}}> fights the gap-based Card contract — the header→body distance comes from the parent flex gap, so slot padding stacks on top of it (or is a no-op). Tune density on the Card itself instead: <Card className="gap-2 py-3 md:py-4">.',
       cardShellOffScale:
-        'Off-scale "{{match}}" on a bg-card+border shell — the scale is 1/1.5/2/3/4/6/8/10, so the `5`/`7` steps and half-steps other than 1.5 are banned (UI-STANDARDS §2) and read off next to every sibling <Card> (p-4 md:p-6). Sweep the shell to an on-scale step (`p-4 md:p-6`, or `p-3` for a dense inner tile); new surfaces should compose <Card>.',
+        'Off-scale "{{match}}" on a bg-card+border shell — the scale is 1/1.5/2/3/4/6/8/10, so the `5`/`7` steps and half-steps other than 1.5 are banned (ui-standards.md §2) and read off next to every sibling <Card> (p-4 md:p-6). Sweep the shell to an on-scale step (`p-4 md:p-6`, or `p-3` for a dense inner tile); new surfaces should compose <Card>.',
     },
   },
   create(context) {
diff --git a/src/__tests__/sharing-recoverable-errors.test.tsx b/src/__tests__/sharing-recoverable-errors.test.tsx
index 26dafe0fb..6e83546d1 100644
--- a/src/__tests__/sharing-recoverable-errors.test.tsx
+++ b/src/__tests__/sharing-recoverable-errors.test.tsx
@@ -457,7 +457,7 @@ describe("the refusal stays on screen, addressed to its own row", () => {
     const alert = /<[^>]*data-slot="grant-action-error"[^>]*>/.exec(html)?.[0];
 
     expect(alert).toBeDefined();
-    // A refusal somebody has to act on is content. UI-STANDARDS §3 reserves
+    // A refusal somebody has to act on is content. ui-standards.md §3 reserves
     // muted for meta, and a sentence nobody reads is a sentence nobody acts
     // on.
     expect(alert).toContain("text-destructive");
diff --git a/src/app/achievements/page.tsx b/src/app/achievements/page.tsx
index 55009852b..e0a5bb984 100644
--- a/src/app/achievements/page.tsx
+++ b/src/app/achievements/page.tsx
@@ -318,7 +318,7 @@ export default function AchievementsPage() {
   }
 
   // A failed load must never fall through to the zeroed summary tiles + the
-  // "none unlocked yet" empty grid (UI-STANDARDS §6). Surface an honest
+  // "none unlocked yet" empty grid (ui-standards.md §6). Surface an honest
   // retry instead.
   if (isError) {
     return (
diff --git a/src/app/globals.css b/src/app/globals.css
index 515f569a7..ef7ed6d0e 100644
--- a/src/app/globals.css
+++ b/src/app/globals.css
@@ -135,7 +135,7 @@
   /* The one sanctioned step below `text-xs` (12px). Minted so badges,
      tag chips, and tabular-nums micro-labels stop hand-rolling
      `text-[0.6875rem]` / `text-[0.65rem]` arbitrary values that drift by a
-     third of a pixel per site. UI-STANDARDS §5 pins the usage: never for
+     third of a pixel per site. ui-standards.md §5 pins the usage: never for
      muted body or meta text (the muted floor stays `text-xs`) — only for
      chips, badges, and tabular micro-labels with verified contrast. */
   --text-2xs: 0.6875rem;
diff --git a/src/app/insights/workouts/[id]/page.tsx b/src/app/insights/workouts/[id]/page.tsx
index 473db5d2e..eea3ddbec 100644
--- a/src/app/insights/workouts/[id]/page.tsx
+++ b/src/app/insights/workouts/[id]/page.tsx
@@ -98,7 +98,7 @@ export default function InsightsWorkoutDetailPage({
           <Skeleton className="h-60 w-full rounded-lg" />
         </div>
       ) : error ? (
-        // A failed query must never read as "no data" (UI-STANDARDS §6).
+        // A failed query must never read as "no data" (ui-standards.md §6).
         <QueryErrorCard error={error} onRetry={() => refetch()} />
       ) : !data ? (
         <p
diff --git a/src/components/charts/nutrient-daily-bar-chart.tsx b/src/components/charts/nutrient-daily-bar-chart.tsx
index 55dc5f1cf..902cda74e 100644
--- a/src/components/charts/nutrient-daily-bar-chart.tsx
+++ b/src/components/charts/nutrient-daily-bar-chart.tsx
@@ -29,7 +29,7 @@ import { RichChartTooltip, type RichTooltipRow } from "./chart-tooltip";
  * v1.29 — 30-day daily bar chart for the nutrients hydration / caffeine
  * cards. One bar per day (dense series — 0 for an unlogged day, summed
  * across sources), an optional thin dashed EFSA reference line, no
- * attainment colouring (UI-STANDARDS: value stays foreground, the bar +
+ * attainment colouring (ui-standards.md: value stays foreground, the bar +
  * reference line ARE the context). Registered in
  * `src/components/charts/chart-runtime.ts` — never import recharts
  * directly at the call site.
diff --git a/src/components/daily/today-hero.tsx b/src/components/daily/today-hero.tsx
index 209c3e9e2..9afeae06d 100644
--- a/src/components/daily/today-hero.tsx
+++ b/src/components/daily/today-hero.tsx
@@ -539,7 +539,7 @@ export function TodayHero({
           </div>
         )}
 
-        {/* Meta row — the hero's quiet tier (UI-STANDARDS §text: `text-xs
+        {/* Meta row — the hero's quiet tier (ui-standards.md §3: `text-xs
             text-muted-foreground` is the meta floor; never an accent, never an
             opacity modifier). Freshness note (plan §2.4) — provisional day,
             last night's sleep not yet folded in. Muted, non-blocking,
diff --git a/src/components/day/day-sections.tsx b/src/components/day/day-sections.tsx
index d41c63600..498d06e2d 100644
--- a/src/components/day/day-sections.tsx
+++ b/src/components/day/day-sections.tsx
@@ -73,7 +73,7 @@ import { useDayValueFormat } from "./use-day-value-format";
  * to look from, and the entry is where it is edited.
  */
 
-/** Section label, UI-STANDARDS §5. */
+/** Section label, ui-standards.md §5. */
 export const DAY_SECTION_LABEL =
   "text-muted-foreground text-xs font-medium tracking-wide uppercase";
 
diff --git a/src/components/insights/__tests__/hero-strip.test.tsx b/src/components/insights/__tests__/hero-strip.test.tsx
index 03a3ac366..c07126ce1 100644
--- a/src/components/insights/__tests__/hero-strip.test.tsx
+++ b/src/components/insights/__tests__/hero-strip.test.tsx
@@ -199,7 +199,7 @@ describe("<HeroStrip>", () => {
       /data-slot="insights-hero-strip-greeting"[^>]*class="([^"]*)"/,
     );
     expect(greeting).not.toBeNull();
-    // App H1 weight is bold (UI-STANDARDS §5) — never font-semibold.
+    // App H1 weight is bold (ui-standards.md §5) — never font-semibold.
     expect(greeting![1]).toContain("font-bold");
     expect(greeting![1]).not.toContain("font-semibold");
     // No off-scale arbitrary type sizes (§5) — round to the neighbouring step.
diff --git a/src/components/insights/__tests__/sleep-stage-stacked-bar.test.tsx b/src/components/insights/__tests__/sleep-stage-stacked-bar.test.tsx
index 74207d86a..843949291 100644
--- a/src/components/insights/__tests__/sleep-stage-stacked-bar.test.tsx
+++ b/src/components/insights/__tests__/sleep-stage-stacked-bar.test.tsx
@@ -65,7 +65,7 @@ describe("<SleepStageStackedBar>", () => {
     expect(html).toContain("Stage composition");
     expect(html).toContain("Last 23 nights");
     // The title routes through the canonical tile header rather than a
-    // hand-rolled title row (UI-STANDARDS §1 / §8).
+    // hand-rolled title row (ui-standards.md §1 / §8).
     expect(html).toContain('data-slot="tile-header"');
   });
 
diff --git a/src/components/insights/coach-panel/__tests__/chat-bubble-unverified-notice.test.tsx b/src/components/insights/coach-panel/__tests__/chat-bubble-unverified-notice.test.tsx
index f695129aa..cb197eb54 100644
--- a/src/components/insights/coach-panel/__tests__/chat-bubble-unverified-notice.test.tsx
+++ b/src/components/insights/coach-panel/__tests__/chat-bubble-unverified-notice.test.tsx
@@ -76,7 +76,7 @@ describe("Coach unverified-figures notice", () => {
       />,
     );
     expect(html).toContain('data-slot="coach-unverified-notice"');
-    // Muted meta treatment (UI-STANDARDS §3) — never a warning colour.
+    // Muted meta treatment (ui-standards.md §3) — never a warning colour.
     expect(html).toContain("text-muted-foreground");
   });
 
diff --git a/src/components/insights/coach-panel/chat-bubble.tsx b/src/components/insights/coach-panel/chat-bubble.tsx
index 81c6345a3..00ed2e220 100644
--- a/src/components/insights/coach-panel/chat-bubble.tsx
+++ b/src/components/insights/coach-panel/chat-bubble.tsx
@@ -520,7 +520,7 @@ function ChatBubbleImpl({
   // #781 — the persisted cancelled-turn marker (an EMPTY assistant row the
   // server writes when the client aborts mid-generation, e.g. navigating
   // away). Rendered as a quiet interrupted note — muted meta text per
-  // UI-STANDARDS §3, never an alarm colour: nothing failed, the user left —
+  // ui-standards.md §3, never an alarm colour: nothing failed, the user left —
   // plus a retry that resubmits the question that produced the turn (the
   // regenerate closure, so the resend runs through the normal send path and
   // every budget/rate gate). No provenance, feedback, copy, or token footer:
@@ -700,7 +700,7 @@ function ChatBubbleImpl({
           <p className="text-warning text-xs">{safeError}</p>
         )}
         {/* v1.32.14 — quiet grounding caveat when the guard withheld a figure.
-            Muted meta (UI-STANDARDS §3), never a warning colour — it is a
+            Muted meta (ui-standards.md §3), never a warning colour — it is a
             grounding caveat, not an error. Static single line, decorative icon,
             no interactivity. The `[…]` marks in the prose above point here. */}
         {showUnverifiedNotice && (
diff --git a/src/components/insights/ecg-detail.tsx b/src/components/insights/ecg-detail.tsx
index ff840a099..694c280fa 100644
--- a/src/components/insights/ecg-detail.tsx
+++ b/src/components/insights/ecg-detail.tsx
@@ -52,7 +52,7 @@ export function EcgDetail({ recordingId }: { recordingId: string }) {
   });
 
   if (isError) {
-    // A failed read must never read as "no data" (UI-STANDARDS §6), and the
+    // A failed read must never read as "no data" (ui-standards.md §6), and the
     // alert is content, not muted meta — it also has to be recoverable.
     return (
       <QueryErrorCard
diff --git a/src/components/insights/hero-strip.tsx b/src/components/insights/hero-strip.tsx
index 974f2b535..1ec661886 100644
--- a/src/components/insights/hero-strip.tsx
+++ b/src/components/insights/hero-strip.tsx
@@ -164,7 +164,7 @@ export function HeroStrip({
       >
         <div className="flex min-w-0 flex-1 flex-col gap-3">
           <div className="flex items-center gap-2">
-            {/* Header glyph stays in the foreground tier — UI-STANDARDS §1
+            {/* Header glyph stays in the foreground tier — ui-standards.md §1
                   reserves primary/accent for actions, not decorative header
                   icons. */}
             <Sparkles
diff --git a/src/components/insights/insight-section-card.tsx b/src/components/insights/insight-section-card.tsx
index 7f9faa3a6..bd981df59 100644
--- a/src/components/insights/insight-section-card.tsx
+++ b/src/components/insights/insight-section-card.tsx
@@ -24,7 +24,7 @@ import { cn } from "@/lib/utils";
  *
  * RSC-safe: no hooks, no browser API.
  *
- * @see .planning/audits/2026-07-05-fable/UI-STANDARDS.md §1
+ * @see docs/contributing/ui-standards.md §1
  */
 export function InsightSectionCard({
   children,
diff --git a/src/components/insights/intraday-pulse-chart.tsx b/src/components/insights/intraday-pulse-chart.tsx
index da4c1b880..dd2a4307a 100644
--- a/src/components/insights/intraday-pulse-chart.tsx
+++ b/src/components/insights/intraday-pulse-chart.tsx
@@ -71,7 +71,7 @@ const AXIS_TICKS = [0, 360, 720, 1080, 1440];
  * line discloses the coverage so the shape doesn't read as more continuous
  * than it is.
  *
- * v1.29.x — a day navigator (`TileHeader`'s `right` slot, per UI-STANDARDS
+ * v1.29.x — a day navigator (`TileHeader`'s `right` slot, per ui-standards.md
  * §11) pages the same route backward through prior days; "next" is disabled
  * at today, so the view can never step into the future. A day outside the
  * dense retention window (`DENSE_INTRADAY_RETENTION_DAYS`) reads back at the
diff --git a/src/components/insights/labs-changes-card.tsx b/src/components/insights/labs-changes-card.tsx
index a25900bd1..8ed2a69dc 100644
--- a/src/components/insights/labs-changes-card.tsx
+++ b/src/components/insights/labs-changes-card.tsx
@@ -99,7 +99,7 @@ export function LabsChangesCard({
               </div>
               {/* The delta is CONTENT — the number the row exists to report —
                   so it takes the analyte's tier, not the meta tier of the
-                  line under it (UI-STANDARDS §3). At `text-xs` muted it wore
+                  line under it (ui-standards.md §3). At `text-xs` muted it wore
                   the sub-line's typography and optically attached itself to
                   that lower line, which is what made a row centred to the
                   pixel read as bottom-aligned. `self-center` states the row's
diff --git a/src/components/insights/medication-efficacy-summary.tsx b/src/components/insights/medication-efficacy-summary.tsx
index 3b1d52ff9..773bbccc7 100644
--- a/src/components/insights/medication-efficacy-summary.tsx
+++ b/src/components/insights/medication-efficacy-summary.tsx
@@ -8,7 +8,7 @@
  * strictly association-framed, never a verdict. Each row links through to the
  * medication's Wirkung tab for the full view.
  *
- * Card anatomy per UI-STANDARDS §8: TileHeader + the inherited `px-4 md:px-6`
+ * Card anatomy per ui-standards.md §8: TileHeader + the inherited `px-4 md:px-6`
  * inset (never re-declared), foreground for content, muted for meta.
  */
 import Link from "next/link";
diff --git a/src/components/insights/nutrients/hydration-card.tsx b/src/components/insights/nutrients/hydration-card.tsx
index 5d61aa219..1f62f9fc2 100644
--- a/src/components/insights/nutrients/hydration-card.tsx
+++ b/src/components/insights/nutrients/hydration-card.tsx
@@ -22,7 +22,7 @@ const WINDOW_DAYS = 30;
  * reference-intake meta line (omitted when the profile has no sex on
  * file — the catalog's own contract), a 30-day bar chart with a dashed
  * reference line. No ring, no attainment colour — the bar chart with a
- * reference line IS the context (UI-STANDARDS: value stays foreground,
+ * reference line IS the context (ui-standards.md: value stays foreground,
  * never coloured by attainment). Display only: water arrives by sync
  * (Apple Health etc.), there is no in-app water entry here.
  */
diff --git a/src/components/layout/auth-shell.tsx b/src/components/layout/auth-shell.tsx
index c410ead0a..18cf95207 100644
--- a/src/components/layout/auth-shell.tsx
+++ b/src/components/layout/auth-shell.tsx
@@ -489,7 +489,7 @@ export function AuthShell({
               // `overflow-y-auto` never clips them: their static position sits
               // wherever the flow put them and extends the DOCUMENT's
               // scrollable overflow instead, painting a second vertical scroll
-              // surface beside `<main>` (UI-STANDARDS §9 one-scroll-floor).
+              // surface beside `<main>` (ui-standards.md §9 one-scroll-floor).
               // The class is not hypothetical and not confined to app code. A
               // Radix `<Switch>` outside a `<form>` renders a hidden
               // `position:absolute` bubble input on the first pass and drops it
diff --git a/src/components/layout/nav-model.ts b/src/components/layout/nav-model.ts
index 03c27e845..10f5cd7ff 100644
--- a/src/components/layout/nav-model.ts
+++ b/src/components/layout/nav-model.ts
@@ -274,7 +274,7 @@ export const NAV_DESTINATIONS: ReadonlyArray<NavDestination> = [
  *
  * Settings and Notifications are account utilities, not feature destinations:
  * on desktop they live in the sidebar footer + avatar menu, on mobile in the
- * top-bar user menu (UI-STANDARDS §10; the More hub carries features only).
+ * top-bar user menu (ui-standards.md §10; the More hub carries features only).
  * They used to be a second hand-curated list on each bar — the exact drift the
  * one-model contract above set out to kill, just pushed down a level. This
  * list is the single source both bars consume, so the two surfaces can no
diff --git a/src/components/layout/shared-record-banner.tsx b/src/components/layout/shared-record-banner.tsx
index de3764e52..225490f04 100644
--- a/src/components/layout/shared-record-banner.tsx
+++ b/src/components/layout/shared-record-banner.tsx
@@ -33,7 +33,7 @@ import { accountLabel } from "@/lib/sharing/account-access-view";
  * dark for the muted token at this text size, while the foreground token keeps
  * the context legible at the same contrast floor as the name.
  *
- * The row is the inline-action shape from UI-STANDARDS §11 rather than a
+ * The row is the inline-action shape from ui-standards.md §11 rather than a
  * centred wrapping stack: sentence `min-w-0 flex-1`, action `shrink-0`, so the
  * way out stays beside the sentence instead of dropping onto its own line once
  * the name is long. `<MaintainershipBanner>` is the sibling that already had an
diff --git a/src/components/medications/medication-order-editor.tsx b/src/components/medications/medication-order-editor.tsx
index 3c26dcb28..8b50ce96f 100644
--- a/src/components/medications/medication-order-editor.tsx
+++ b/src/components/medications/medication-order-editor.tsx
@@ -151,7 +151,7 @@ export function MedicationOrderEditor({
     // `relative` anchors the sr-only drag-hint paragraph: `sr-only` is
     // absolutely positioned, and without a positioned ancestor its 1px box
     // lands below the list in DOCUMENT coordinates and makes the document
-    // itself scrollable (second scrollbar — UI-STANDARDS §9 one-scroll-floor).
+    // itself scrollable (second scrollbar — ui-standards.md §9 one-scroll-floor).
     <div className="relative space-y-4" data-slot="medication-order-editor">
       {medications.length === 0 && (
         <EmptyState
diff --git a/src/components/module-list/module-order-editor.tsx b/src/components/module-list/module-order-editor.tsx
index f1d20c54c..d67a20743 100644
--- a/src/components/module-list/module-order-editor.tsx
+++ b/src/components/module-list/module-order-editor.tsx
@@ -110,7 +110,7 @@ export function ModuleOrderEditor({ items, onChange }: ModuleOrderEditorProps) {
     // `relative` anchors the sr-only drag-hint paragraph: `sr-only` is
     // absolutely positioned, and without a positioned ancestor its 1px box
     // lands below the list in DOCUMENT coordinates and makes the document
-    // itself scrollable (second scrollbar — UI-STANDARDS §9 one-scroll-floor).
+    // itself scrollable (second scrollbar — ui-standards.md §9 one-scroll-floor).
     <div className="relative space-y-2" data-slot="module-order-editor">
       <DndContext
         sensors={sensors}
diff --git a/src/components/mood/manage/tag-groups-card.tsx b/src/components/mood/manage/tag-groups-card.tsx
index ccdfac132..8874a7f59 100644
--- a/src/components/mood/manage/tag-groups-card.tsx
+++ b/src/components/mood/manage/tag-groups-card.tsx
@@ -224,7 +224,7 @@ export function TagGroupsCard({ catalog }: TagGroupsCardProps) {
     // `relative` anchors the sr-only drag-hint paragraph: `sr-only` is
     // absolutely positioned, and without a positioned ancestor its 1px box
     // lands below the list in DOCUMENT coordinates and makes the document
-    // itself scrollable (second scrollbar — UI-STANDARDS §9 one-scroll-floor).
+    // itself scrollable (second scrollbar — ui-standards.md §9 one-scroll-floor).
     <div className="relative space-y-3" data-slot="mood-tag-groups-card">
       <div className="flex items-center justify-between gap-2">
         <p className="text-muted-foreground min-w-0 text-xs">
diff --git a/src/components/mood/manage/tag-manager-card.tsx b/src/components/mood/manage/tag-manager-card.tsx
index 2bb3fa6cc..c5246873a 100644
--- a/src/components/mood/manage/tag-manager-card.tsx
+++ b/src/components/mood/manage/tag-manager-card.tsx
@@ -296,7 +296,7 @@ export function TagManagerCard({ catalog }: TagManagerCardProps) {
     // `relative` anchors the sr-only drag-hint paragraph: `sr-only` is
     // absolutely positioned, and without a positioned ancestor its 1px box
     // lands below the list in DOCUMENT coordinates and makes the document
-    // itself scrollable (second scrollbar — UI-STANDARDS §9 one-scroll-floor).
+    // itself scrollable (second scrollbar — ui-standards.md §9 one-scroll-floor).
     <div className="relative space-y-4" data-slot="mood-tag-manager-card">
       <div className="flex items-center justify-between gap-2">
         <p className="text-muted-foreground min-w-0 text-xs">
diff --git a/src/components/onboarding/step-heading.tsx b/src/components/onboarding/step-heading.tsx
index 85b4645d7..cd8b9e1c8 100644
--- a/src/components/onboarding/step-heading.tsx
+++ b/src/components/onboarding/step-heading.tsx
@@ -13,7 +13,7 @@ import { useEffect, useRef, type ReactNode } from "react";
  * put it — the heading is at the top of the column anyway.
  *
  * Semibold rather than the app-wide bold PageHeader H1: the onboarding hero
- * is the documented exception (UI-STANDARDS §5). Do not sweep to font-bold.
+ * is the documented exception (ui-standards.md §5). Do not sweep to font-bold.
  */
 export function StepHeading({
   id,
diff --git a/src/components/settings/access/__tests__/managed-profile-affordances.test.tsx b/src/components/settings/access/__tests__/managed-profile-affordances.test.tsx
index 4601462d1..a90c813e9 100644
--- a/src/components/settings/access/__tests__/managed-profile-affordances.test.tsx
+++ b/src/components/settings/access/__tests__/managed-profile-affordances.test.tsx
@@ -404,7 +404,7 @@ describe("how a field says what is wrong with it", () => {
     // Announced, because it MOUNTS with the role rather than a class being
     // swapped onto a node that was already there.
     expect(alert).toContain('role="alert"');
-    // Content, not meta. UI-STANDARDS §3, and the same reasoning
+    // Content, not meta. ui-standards.md §3, and the same reasoning
     // `grant-action-error.tsx` spells out: a refusal rendered as muted is a
     // refusal nobody reads.
     expect(alert).toContain("text-destructive");
@@ -521,7 +521,7 @@ describe("ending a managed profile", () => {
     authRef.value = { accounts: [entry()], active: null };
     const html = renderGatedSection();
     expect(html).toContain('data-slot="managed-profile-delete"');
-    // The mobile tap floor UI-STANDARDS §11 asks of an inline action.
+    // The mobile tap floor ui-standards.md §11 asks of an inline action.
     expect(html).toMatch(
       /data-slot="managed-profile-delete"[^>]*class="[^"]*min-h-11/,
     );
@@ -629,7 +629,7 @@ describe("ending a managed profile", () => {
     const html = renderGatedSection();
     expect(html).toContain('data-slot="query-error-card"');
     expect(html).toContain("Could not load who looks after this record");
-    // And the way back is reachable, which is what UI-STANDARDS §6 asks of an
+    // And the way back is reachable, which is what ui-standards.md §6 asks of an
     // error state.
     expect(html).toContain('data-slot="query-error-retry"');
   });
diff --git a/src/components/settings/access/grant-action-error.tsx b/src/components/settings/access/grant-action-error.tsx
index a398e3b5f..d0f3cef40 100644
--- a/src/components/settings/access/grant-action-error.tsx
+++ b/src/components/settings/access/grant-action-error.tsx
@@ -172,7 +172,7 @@ export function grantActionErrorKey(err: unknown, action: GrantAction): string {
  * a person who pressed a button and got nothing has already looked away, and
  * a screen reader that does not announce it is the same silence the panel had
  * before. `text-destructive` because this is content somebody has to act on —
- * UI-STANDARDS §3 reserves muted for meta, and a refusal rendered as meta is a
+ * ui-standards.md §3 reserves muted for meta, and a refusal rendered as meta is a
  * refusal nobody reads.
  *
  * `data-grant-error-for` carries the row id so a panel holding two failed rows
diff --git a/src/components/settings/access/grant-invite-card.tsx b/src/components/settings/access/grant-invite-card.tsx
index eb3544759..9ea473ed4 100644
--- a/src/components/settings/access/grant-invite-card.tsx
+++ b/src/components/settings/access/grant-invite-card.tsx
@@ -466,7 +466,7 @@ export function resolveInviteScope({
  * a button inside a label forwards its own tap to the label's control, so the
  * radio and the popover would fight for the same click (the same reason
  * `SectionOption` avoids the wrapping label). Muted, `text-xs` — the meta floor
- * per UI-STANDARDS §3.
+ * per ui-standards.md §3.
  */
 function AccessOption({
   level,
diff --git a/src/components/settings/access/grant-row.tsx b/src/components/settings/access/grant-row.tsx
index 341364cc0..d77ece921 100644
--- a/src/components/settings/access/grant-row.tsx
+++ b/src/components/settings/access/grant-row.tsx
@@ -54,7 +54,7 @@ export function GrantRowItem({
   /**
    * Something the person has to read before they act on this row, rendered in
    * the content column rather than beside the button: consent copy is content
-   * (UI-STANDARDS §3), and a sentence squeezed into the action column would
+   * (ui-standards.md §3), and a sentence squeezed into the action column would
    * wrap into a stripe nobody reads.
    */
   notice?: ReactNode;
diff --git a/src/components/settings/access/managed-profile-card.tsx b/src/components/settings/access/managed-profile-card.tsx
index 04ca733c4..050c54988 100644
--- a/src/components/settings/access/managed-profile-card.tsx
+++ b/src/components/settings/access/managed-profile-card.tsx
@@ -92,7 +92,7 @@ export function ManagedProfileCard() {
       />
       <div className="space-y-4">
         {/* Content, not meta: this is what somebody is consenting to take on,
-            and UI-STANDARDS §3 reserves muted for the incidental. */}
+            and ui-standards.md §3 reserves muted for the incidental. */}
         <p data-slot="managed-profile-explainer" className="text-sm">
           {t("recordSharing.managed.explainer")}
         </p>
@@ -159,7 +159,7 @@ function ManagedProfileRow({
       data-managed-profile-id={profile.accountId}
       className="space-y-2 py-3 first:pt-0 last:pb-0"
     >
-      {/* UI-STANDARDS §11 inline action row. */}
+      {/* ui-standards.md §11 inline action row. */}
       <div className="flex items-start justify-between gap-3">
         <div className="min-w-0 flex-1">
           {/* A person's name is user data and stays content. */}
@@ -168,7 +168,7 @@ function ManagedProfileRow({
             {t("recordSharing.lookingAfter.kindManaged")}
           </p>
         </div>
-        {/* UI-STANDARDS §11: the actions stay beside the name, never below it.
+        {/* ui-standards.md §11: the actions stay beside the name, never below it.
             Edit is offered without waiting for the roster — it changes what the
             record IS and does not depend on how many people look after it,
             unlike the deletion beside it, whose confirm copy states that
@@ -223,7 +223,7 @@ function ManagedProfileRow({
       {/* A failed roster read is not an absent roster.
           Without this branch a 500 renders exactly as a still-loading one —
           the row with no guardian panel and no delete control — and the person
-          waits for something that is never coming. UI-STANDARDS §6: a read
+          waits for something that is never coming. ui-standards.md §6: a read
           that failed says so and offers the way back. It is deliberately NOT
           the same as the 404 arm: a 404 means this account is no longer a
           Guardian of that profile, which is an answer, and the row correctly
diff --git a/src/components/settings/access/managed-profile-create-form.tsx b/src/components/settings/access/managed-profile-create-form.tsx
index 2fd4841da..a2071b566 100644
--- a/src/components/settings/access/managed-profile-create-form.tsx
+++ b/src/components/settings/access/managed-profile-create-form.tsx
@@ -321,7 +321,7 @@ export function ManagedProfileCreateForm({
  * Two nodes, never one that swaps. The form used to render a single muted
  * `<p>` whose TEXT changed from hint to error, which is wrong twice over:
  *
- *   * a refusal is content somebody has to act on, and UI-STANDARDS §3
+ *   * a refusal is content somebody has to act on, and ui-standards.md §3
  *     reserves `text-muted-foreground` for meta. The same reasoning is written
  *     out at `grant-action-error.tsx` — a refusal rendered as meta is a
  *     refusal nobody reads;
diff --git a/src/components/settings/access/managed-profile-edit-form.tsx b/src/components/settings/access/managed-profile-edit-form.tsx
index e6aed7d20..8937725ce 100644
--- a/src/components/settings/access/managed-profile-edit-form.tsx
+++ b/src/components/settings/access/managed-profile-edit-form.tsx
@@ -292,7 +292,7 @@ function ManagedProfileEditFields({
           />
         </div>
 
-        {/* Above the action row, per UI-STANDARDS §12: nothing follows it. */}
+        {/* Above the action row, per ui-standards.md §12: nothing follows it. */}
         {error && (
           <p
             role="alert"
diff --git a/src/components/settings/access/managed-profile-guardians.tsx b/src/components/settings/access/managed-profile-guardians.tsx
index b7481722c..a5ca3feec 100644
--- a/src/components/settings/access/managed-profile-guardians.tsx
+++ b/src/components/settings/access/managed-profile-guardians.tsx
@@ -151,7 +151,7 @@ export function ManagedProfileGuardians({
               data-guardian-state={guardian.state}
               className="space-y-2 py-3 first:pt-0 last:pb-0"
             >
-              {/* UI-STANDARDS §11 inline action row. */}
+              {/* ui-standards.md §11 inline action row. */}
               <div className="flex items-start justify-between gap-3">
                 <div className="min-w-0 flex-1">
                   <p className="truncate text-sm font-medium">
diff --git a/src/components/settings/access/managed-profile-handover.tsx b/src/components/settings/access/managed-profile-handover.tsx
index 1c27cbf82..2c9cf6f53 100644
--- a/src/components/settings/access/managed-profile-handover.tsx
+++ b/src/components/settings/access/managed-profile-handover.tsx
@@ -449,7 +449,7 @@ function HandoverLink({
       </p>
       <div className="flex flex-col items-center gap-4 sm:flex-row sm:items-start">
         {/* The QR quiet zone stays white in both themes: a scanner needs the
-            contrast, and UI-STANDARDS §4 names this exemption. */}
+            contrast, and ui-standards.md §4 names this exemption. */}
         {/* eslint-disable-next-line @next/next/no-img-element -- a data: URL minted client-side; nothing for the image optimiser to do */}
         <img
           src={link.qrDataUrl}
diff --git a/src/components/settings/dashboard-layout-section.tsx b/src/components/settings/dashboard-layout-section.tsx
index 51dcafd28..1c22afcf2 100644
--- a/src/components/settings/dashboard-layout-section.tsx
+++ b/src/components/settings/dashboard-layout-section.tsx
@@ -574,7 +574,7 @@ export function DashboardLayoutSection({ id }: { id: string }) {
         // then sits at its static position (below this long list) in DOCUMENT
         // coordinates and silently makes the document itself scrollable, a
         // second vertical scrollbar next to the shell-owned `<main>` scroll
-        // (UI-STANDARDS §9 one-scroll-floor; guarded by
+        // (ui-standards.md §9 one-scroll-floor; guarded by
         // e2e/settings-overscroll.spec.ts).
         <div className="relative space-y-2">
           {/* v1.4.15 — table-style header naming the two
diff --git a/src/components/settings/report-selection/report-scope-picker.tsx b/src/components/settings/report-selection/report-scope-picker.tsx
index 29825262f..11679fbb8 100644
--- a/src/components/settings/report-selection/report-scope-picker.tsx
+++ b/src/components/settings/report-selection/report-scope-picker.tsx
@@ -110,7 +110,7 @@ export function ReportScopePicker({
   return (
     <div className="space-y-3" data-testid={`report-scope-picker-${surface}`}>
       {/* The one-click way to a complete report. An inline action row
-          (UI-STANDARDS §11): the sentence wraps, the action stays beside it.
+          (ui-standards.md §11): the sentence wraps, the action stays beside it.
           It is offered, never applied — and it stays offered so a person can
           come back to the standard set after experimenting. On a phone the
           action's own label is wider than half the row, so beside it the
diff --git a/src/components/settings/share-link-create-form.tsx b/src/components/settings/share-link-create-form.tsx
index 583e26877..2bd1a8382 100644
--- a/src/components/settings/share-link-create-form.tsx
+++ b/src/components/settings/share-link-create-form.tsx
@@ -518,7 +518,7 @@ export function ShareLinkCreateForm({
               opens the record (and its shared documents). Promoted as the
               primary mobile affordance: a clinician scans it on the spot to
               open the record on their own device. Shown exactly once. The
-              white quiet-zone is the documented QR exemption (UI-STANDARDS §4)
+              white quiet-zone is the documented QR exemption (ui-standards.md §4)
               so the code stays scannable in the dark theme too. */}
           {qrDataUrl && (
             <div
diff --git a/src/components/ui/query-error-row.tsx b/src/components/ui/query-error-row.tsx
index be7637a48..59c83ab2e 100644
--- a/src/components/ui/query-error-row.tsx
+++ b/src/components/ui/query-error-row.tsx
@@ -17,7 +17,7 @@ import { cn } from "@/lib/utils";
  * geometry and pushes everything the user came for below the fold — so this
  * shape stays, promoted to a primitive instead of being copied a third time.
  *
- * Pick by surface (UI-STANDARDS §6):
+ * Pick by surface (ui-standards.md §6):
  *  - primary / list surface → `QueryErrorCard`
  *  - dense metric strip or tile where the tall card would dominate →
  *    `QueryErrorRow`
diff --git a/tests/fixtures/v137/e2e-journeys.ts b/tests/fixtures/v137/e2e-journeys.ts
index 37f4c118a..d6f688b87 100644
--- a/tests/fixtures/v137/e2e-journeys.ts
+++ b/tests/fixtures/v137/e2e-journeys.ts
@@ -56,7 +56,7 @@ export interface AccessibilityStateCase {
   readonly keyboardTarget: string | null;
   /**
    * Copy the person has to read and act on, which must render as content
-   * rather than as muted meta (UI-STANDARDS §3). `null` where the state's only
+   * rather than as muted meta (ui-standards.md §3). `null` where the state's only
    * text is a screen-reader label, which has no visual contrast to check.
    */
   readonly contrastTarget: string | null;

From b04570349306985c819b5b439779ce7f9bba05c4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Wed, 21 Oct 2026 20:14:20 +0200
Subject: [PATCH 4/8] feat(apple-health): ingest the activity rings,
 mindfulness, State of Mind and AFib burden

Six Apple Health signals leave the deferred list and ride
POST /api/measurements/batch and the export.zip import end to end:
EXERCISE_MINUTES, STAND_MINUTES and STAND_HOURS (the exercise and stand
rings), MINDFUL_MINUTES, STATE_OF_MIND_VALENCE (iOS 18 State of Mind,
-1..1) and AFIB_BURDEN (AFib History, percent of the week). The ring
types and mindful minutes are cumulative, so the daily rollup is their
sum; AFib burden is scaled strictly from Apple's fraction and a value
above 1 is refused rather than guessed at. The archive import takes
mindful minutes from the session's dates and skips idle stand hours.
Every registry carries them: units, ranges, labels in all locales,
categories, chart tokens, report catalogue (mindful minutes and the
valence fenced as sensitive), signal registry with FHIR codings, and
MCP exposure for the three ring types only.

Workout GPS tracks are now an opt-in, off by default
(PATCH /api/auth/me/workout-routes, a switch on Data & Privacy). While
it is off, the workout batch route and the export import keep every
workout and drop its track with the same per-entry status. With it on,
the import reads the referenced GPX files from the archive one bounded
member at a time, thins each to the point cap and stores it sealed.
The climb a track carries is written to Workout.elevationM at write
time, so the workout insight no longer opens the track, and the AI
egress guard now freezes the set of files that read route geometry.
---
 docs/api/openapi.yaml                         | 158 ++++++++++-
 messages/de.json                              |  13 +
 messages/en.json                              |  13 +
 messages/es.json                              |  13 +
 messages/fr.json                              |  13 +
 messages/it.json                              |  13 +
 messages/ko.json                              |  13 +
 messages/nl.json                              |  13 +
 messages/pl.json                              |  13 +
 .../migration.sql                             |  21 ++
 .../0432_store_workout_routes/migration.sql   |   6 +
 prisma/schema.prisma                          |  16 ++
 .../ai-egress-capability-guard.test.ts        |  82 ++++++
 ...doctor-report-control-gating-guard.test.ts |   4 +-
 .../me/workout-routes/__tests__/route.test.ts | 121 ++++++++
 src/app/api/auth/me/workout-routes/route.ts   | 109 +++++++
 .../workouts/__tests__/batch-create.test.ts   |  54 +++-
 src/app/api/workouts/batch/route.ts           |  29 +-
 .../measurements/measurement-list-meta.ts     |  15 +
 .../measurements/measurement-type-colors.ts   |   9 +
 .../__tests__/report-selection-panel.test.tsx |   4 +-
 src/components/settings/privacy-section.tsx   |   4 +
 .../settings/workout-routes-card.tsx          |  83 ++++++
 .../measurement-type-enum-coverage.test.ts    |  10 +-
 .../__tests__/route-import.test.ts            | 253 +++++++++++++++++
 src/lib/apple-health/archive-stream.ts        | 153 ++++++++--
 src/lib/apple-health/route-import.ts          | 266 ++++++++++++++++++
 src/lib/data-wipe/wipe-plan.ts                |   1 +
 src/lib/export/account-settings-backup.ts     |   1 +
 src/lib/export/backup-plan.ts                 |   1 +
 src/lib/insights/chart-tokens.ts              |   8 +
 src/lib/jobs/apple-health-import-worker.ts    |  38 ++-
 src/lib/jobs/workout-insight-generate.ts      |   5 -
 .../__tests__/apple-health-mapping.test.ts    |  84 +++++-
 .../import-apple-health-export.test.ts        |  66 ++++-
 src/lib/measurements/apple-health-mapping.ts  |  96 ++++++-
 src/lib/measurements/categories.ts            |  11 +
 src/lib/measurements/display-transform.ts     |   5 +
 .../import-apple-health-export.ts             |  71 +++++
 src/lib/measurements/type-label-keys.ts       |   7 +
 src/lib/measurements/unit-label.ts            |   3 +
 src/lib/measurements/unit-map.ts              |  10 +
 src/lib/measurements/value-domain.ts          |   1 +
 src/lib/modules/measurement-scope.ts          |   8 +-
 src/lib/openapi/routes/profile.ts             |  61 ++++
 src/lib/personal-records/pr-direction.ts      |  11 +
 src/lib/query-keys/workouts.ts                |   5 +
 .../__tests__/catalogue-guard.test.ts         |  10 +-
 src/lib/report-selection/catalogue.ts         |  16 ++
 .../fixtures/expected-measurement-loinc.json  |  36 +++
 src/lib/signals/registry.ts                   | 136 +++++++++
 src/lib/validations/backup.ts                 |   1 +
 src/lib/validations/measurement.ts            |  20 ++
 src/lib/validations/user-prefs.ts             |   5 +
 .../__tests__/insight-evidence.test.ts        |  72 +----
 .../workouts/__tests__/route-climb.test.ts    |  35 +++
 src/lib/workouts/insight-evidence.ts          |  34 +--
 src/lib/workouts/route-climb.ts               |  37 +++
 58 files changed, 2233 insertions(+), 163 deletions(-)
 create mode 100644 prisma/migrations/0431_apple_health_activity_mind_afib/migration.sql
 create mode 100644 prisma/migrations/0432_store_workout_routes/migration.sql
 create mode 100644 src/app/api/auth/me/workout-routes/__tests__/route.test.ts
 create mode 100644 src/app/api/auth/me/workout-routes/route.ts
 create mode 100644 src/components/settings/workout-routes-card.tsx
 create mode 100644 src/lib/apple-health/__tests__/route-import.test.ts
 create mode 100644 src/lib/apple-health/route-import.ts
 create mode 100644 src/lib/workouts/__tests__/route-climb.test.ts
 create mode 100644 src/lib/workouts/route-climb.ts

diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml
index 9b4f13c5b..b390c93b3 100644
--- a/docs/api/openapi.yaml
+++ b/docs/api/openapi.yaml
@@ -4315,6 +4315,12 @@ paths:
               - WAIST_TO_HEIGHT
               - WHO5_SCORE
               - SCI_SCORE
+              - EXERCISE_MINUTES
+              - STAND_MINUTES
+              - STAND_HOURS
+              - MINDFUL_MINUTES
+              - STATE_OF_MIND_VALENCE
+              - AFIB_BURDEN
         - in: query
           name: from
           schema:
@@ -9455,6 +9461,52 @@ paths:
                 $ref: "#/components/schemas/ErrorEnvelope"
         "422": *a4
         "429": *a5
+  /api/auth/me/workout-routes:
+    get:
+      tags:
+        - Auth
+      summary: Read the workout-route opt-in
+      description: Whether the GPS track of a workout is kept. Off by default. While it is off, `POST /api/workouts/batch` and
+        the Apple Health export import keep every workout but drop its `route`; the per-entry status is the same as with
+        the route stored. No AI path ever reads a stored track.
+      responses:
+        "200":
+          description: The current flag.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GetWorkoutRoutesEnvelope"
+        "401": *a1
+        "422": *a4
+        "429": *a5
+    patch:
+      tags:
+        - Auth
+      summary: Set the workout-route opt-in
+      description: Hard-set, idempotent, audit-logged. Rate-limited 60 / min per user; body capped at 1 KB. Turning it off
+        stops new tracks; tracks already stored stay until their workout is deleted.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/WorkoutRoutesPatchRequest"
+      responses:
+        "200":
+          description: The resolved next flag.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PatchWorkoutRoutesEnvelope"
+        "401": *a1
+        "413":
+          description: Request body exceeds 1024 bytes. Nothing was written.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorEnvelope"
+        "422": *a4
+        "429": *a5
   /api/auth/me/use-central-codex:
     get:
       tags:
@@ -25948,7 +26000,7 @@ components:
               type: number
               const: 2
             leaves:
-              maxItems: 95
+              maxItems: 101
               type: array
               items:
                 type: string
@@ -26008,7 +26060,7 @@ components:
               type: number
               const: 2
             leaves:
-              maxItems: 95
+              maxItems: 101
               type: array
               items:
                 type: string
@@ -26843,6 +26895,12 @@ components:
             - WAIST_TO_HEIGHT
             - WHO5_SCORE
             - SCI_SCORE
+            - EXERCISE_MINUTES
+            - STAND_MINUTES
+            - STAND_HOURS
+            - MINDFUL_MINUTES
+            - STATE_OF_MIND_VALENCE
+            - AFIB_BURDEN
         value:
           type: number
         measuredAt:
@@ -28524,6 +28582,12 @@ components:
             - WAIST_TO_HEIGHT
             - WHO5_SCORE
             - SCI_SCORE
+            - EXERCISE_MINUTES
+            - STAND_MINUTES
+            - STAND_HOURS
+            - MINDFUL_MINUTES
+            - STATE_OF_MIND_VALENCE
+            - AFIB_BURDEN
         biomarkerId:
           type: string
           minLength: 1
@@ -29023,7 +29087,7 @@ components:
           type: number
           const: 2
         leaves:
-          maxItems: 95
+          maxItems: 101
           type: array
           items:
             type: string
@@ -29358,6 +29422,14 @@ components:
         - labsLocalOcrEnabled
       description: Turn browser-side OCR on or off for lab-report scanning. When on, a text-only provider can still read a
         paper report because the image is transcribed on the device and only the TEXT is sent.
+    WorkoutRoutesPatchRequest:
+      type: object
+      properties:
+        storeWorkoutRoutes:
+          type: boolean
+      required:
+        - storeWorkoutRoutes
+      description: Keep or stop keeping the GPS track of new workouts. Off by default.
     UseCentralCodexPatchRequest:
       type: object
       properties:
@@ -30186,6 +30258,12 @@ components:
         - WAIST_TO_HEIGHT
         - WHO5_SCORE
         - SCI_SCORE
+        - EXERCISE_MINUTES
+        - STAND_MINUTES
+        - STAND_HOURS
+        - MINDFUL_MINUTES
+        - STATE_OF_MIND_VALENCE
+        - AFIB_BURDEN
       description: DB-stored measurement category. v1.4.23 added 7 Apple Health values (HRV, resting HR, active energy,
         flights, walking/running distance, VO2 max, body temperature).
     InsightsSettingsPutRequest:
@@ -38851,6 +38929,8 @@ components:
                   type: boolean
                 labsLocalOcrEnabled:
                   type: boolean
+                storeWorkoutRoutes:
+                  type: boolean
                 onboardingCompletedAt:
                   anyOf:
                     - type: string
@@ -38961,6 +39041,12 @@ components:
                   - WAIST_TO_HEIGHT
                   - WHO5_SCORE
                   - SCI_SCORE
+                  - EXERCISE_MINUTES
+                  - STAND_MINUTES
+                  - STAND_HOURS
+                  - MINDFUL_MINUTES
+                  - STATE_OF_MIND_VALENCE
+                  - AFIB_BURDEN
               value:
                 type: number
               valueMin:
@@ -39701,6 +39787,12 @@ components:
                             - WAIST_TO_HEIGHT
                             - WHO5_SCORE
                             - SCI_SCORE
+                            - EXERCISE_MINUTES
+                            - STAND_MINUTES
+                            - STAND_HOURS
+                            - MINDFUL_MINUTES
+                            - STATE_OF_MIND_VALENCE
+                            - AFIB_BURDEN
                         - type: "null"
                     biomarkerName:
                       anyOf:
@@ -42176,6 +42268,12 @@ components:
                   - WAIST_TO_HEIGHT
                   - WHO5_SCORE
                   - SCI_SCORE
+                  - EXERCISE_MINUTES
+                  - STAND_MINUTES
+                  - STAND_HOURS
+                  - MINDFUL_MINUTES
+                  - STATE_OF_MIND_VALENCE
+                  - AFIB_BURDEN
               dateKey:
                 type: string
                 pattern: ^\d{4}-\d{2}-\d{2}$
@@ -43354,6 +43452,12 @@ components:
                       - WAIST_TO_HEIGHT
                       - WHO5_SCORE
                       - SCI_SCORE
+                      - EXERCISE_MINUTES
+                      - STAND_MINUTES
+                      - STAND_HOURS
+                      - MINDFUL_MINUTES
+                      - STATE_OF_MIND_VALENCE
+                      - AFIB_BURDEN
                   - type: "null"
               intervalDays:
                 anyOf:
@@ -43566,6 +43670,12 @@ components:
                   - WAIST_TO_HEIGHT
                   - WHO5_SCORE
                   - SCI_SCORE
+                  - EXERCISE_MINUTES
+                  - STAND_MINUTES
+                  - STAND_HOURS
+                  - MINDFUL_MINUTES
+                  - STATE_OF_MIND_VALENCE
+                  - AFIB_BURDEN
               metricSlot:
                 type:
                   - string
@@ -55934,6 +56044,48 @@ components:
         - data
         - error
       additionalProperties: false
+    GetWorkoutRoutesEnvelope:
+      type: object
+      properties:
+        data:
+          $ref: "#/components/schemas/WorkoutRoutesResponse"
+        error:
+          type: "null"
+        meta:
+          type: object
+          properties:
+            requestId:
+              type: string
+          additionalProperties: false
+      required:
+        - data
+        - error
+      additionalProperties: false
+    WorkoutRoutesResponse:
+      type: object
+      properties:
+        storeWorkoutRoutes:
+          type: boolean
+      required:
+        - storeWorkoutRoutes
+      additionalProperties: false
+    PatchWorkoutRoutesEnvelope:
+      type: object
+      properties:
+        data:
+          $ref: "#/components/schemas/WorkoutRoutesResponse"
+        error:
+          type: "null"
+        meta:
+          type: object
+          properties:
+            requestId:
+              type: string
+          additionalProperties: false
+      required:
+        - data
+        - error
+      additionalProperties: false
     GetUseCentralCodexEnvelope:
       type: object
       properties:
diff --git a/messages/de.json b/messages/de.json
index ba1ca12ef..6b34c7498 100644
--- a/messages/de.json
+++ b/messages/de.json
@@ -911,6 +911,12 @@
     "unitRating": "Stufe",
     "typeWho5Score": "WHO-5-Wert",
     "typeSciScore": "SCI-Wert",
+    "typeExerciseMinutes": "Trainingsminuten",
+    "typeStandMinutes": "Stehminuten",
+    "typeStandHours": "Stehstunden",
+    "typeMindfulMinutes": "Achtsamkeitsminuten",
+    "typeStateOfMindValence": "Gemütszustand",
+    "typeAfibBurden": "VHF-Last",
     "durationReadAs": "Gelesen als {duration}",
     "durationHoursMinutes": "{hours} Std. {minutes} Min.",
     "durationHoursOnly": "{hours} Std.",
@@ -3565,6 +3571,7 @@
       "falls": "Stürze",
       "years": "Jahre",
       "breathingEvents": "Ereignisse",
+      "standHours": "Stunden",
       "respiratoryRate": "Atemzüge/min"
     },
     "sleep": {
@@ -7155,6 +7162,12 @@
         "profile": "Dein Profil, deine Anamnese und die Angaben für die Gesundheitsakte",
         "modules": "Einträge der Module: {list}"
       },
+      "workoutRoutes": {
+        "title": "Trainingsrouten",
+        "description": "Den GPS-Verlauf neuer Trainings aus der iPhone-App und dem Apple-Health-Export speichern.",
+        "detail": "Standardmäßig aus. Eine Route zeigt, wo du wohnst, arbeitest und trainierst, deshalb wird sie erst gespeichert, wenn du das einschaltest. Die Trainings selbst werden immer gespeichert, und keine KI-Funktion liest jemals eine Route. Ausschalten stoppt neue Routen; schon gespeicherte bleiben, bis du das Training löschst.",
+        "loadError": "Die Routen-Einstellung konnte nicht geladen werden."
+      },
       "retention": {
         "title": "Aufbewahrung",
         "description": "Wie lange zeitgebundene Datensätze vor der automatischen Bereinigung gespeichert bleiben.",
diff --git a/messages/en.json b/messages/en.json
index 3a6dfe846..60fe5c6be 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -911,6 +911,12 @@
     "unitRating": "rating",
     "typeWho5Score": "WHO-5 score",
     "typeSciScore": "SCI score",
+    "typeExerciseMinutes": "Exercise minutes",
+    "typeStandMinutes": "Standing minutes",
+    "typeStandHours": "Stand hours",
+    "typeMindfulMinutes": "Mindful minutes",
+    "typeStateOfMindValence": "State of mind",
+    "typeAfibBurden": "AFib burden",
     "durationReadAs": "Read as {duration}",
     "durationHoursMinutes": "{hours} h {minutes} min",
     "durationHoursOnly": "{hours} h",
@@ -3565,6 +3571,7 @@
       "falls": "falls",
       "years": "years",
       "breathingEvents": "events",
+      "standHours": "hours",
       "respiratoryRate": "breaths/min"
     },
     "sleep": {
@@ -7155,6 +7162,12 @@
         "profile": "Your profile, medical history and health-record details",
         "modules": "Records of each module: {list}"
       },
+      "workoutRoutes": {
+        "title": "Workout routes",
+        "description": "Keep the GPS track of new workouts from the iPhone app and the Apple Health export.",
+        "detail": "Off by default. A route shows where you live, work and train, so it is only kept once you turn this on. Workouts are kept either way, and no AI feature ever reads a route. Turning it off stops new routes; routes already kept stay until you delete the workout.",
+        "loadError": "The route setting could not be loaded."
+      },
       "retention": {
         "title": "Retention",
         "description": "How long time-bound records are kept before automatic cleanup.",
diff --git a/messages/es.json b/messages/es.json
index 0196a1f7b..fcfada1b1 100644
--- a/messages/es.json
+++ b/messages/es.json
@@ -911,6 +911,12 @@
     "unitRating": "nivel",
     "typeWho5Score": "Puntuación WHO-5",
     "typeSciScore": "Puntuación SCI",
+    "typeExerciseMinutes": "Minutos de ejercicio",
+    "typeStandMinutes": "Minutos de pie",
+    "typeStandHours": "Horas de pie",
+    "typeMindfulMinutes": "Minutos de atención plena",
+    "typeStateOfMindValence": "Estado de ánimo",
+    "typeAfibBurden": "Carga de FA",
     "durationReadAs": "Se lee como {duration}",
     "durationHoursMinutes": "{hours} h {minutes} min",
     "durationHoursOnly": "{hours} h",
@@ -3565,6 +3571,7 @@
       "falls": "caídas",
       "years": "años",
       "breathingEvents": "eventos",
+      "standHours": "horas",
       "respiratoryRate": "respiraciones/min"
     },
     "sleep": {
@@ -7155,6 +7162,12 @@
         "profile": "Tu perfil, tus antecedentes médicos y los datos del historial de salud",
         "modules": "Registros de cada módulo: {list}"
       },
+      "workoutRoutes": {
+        "title": "Rutas de entrenamiento",
+        "description": "Guardar el recorrido GPS de los entrenamientos nuevos de la app de iPhone y de la exportación de Apple Salud.",
+        "detail": "Desactivado por defecto. Una ruta muestra dónde vives, trabajas y entrenas, así que solo se guarda cuando lo activas. Los entrenamientos se guardan siempre y ninguna función de IA lee nunca una ruta. Al desactivarlo dejan de guardarse rutas nuevas; las ya guardadas se quedan hasta que borres el entrenamiento.",
+        "loadError": "No se pudo cargar el ajuste de rutas."
+      },
       "retention": {
         "title": "Retención",
         "description": "Cuánto tiempo se conservan los registros con límite temporal antes de su limpieza automática.",
diff --git a/messages/fr.json b/messages/fr.json
index d7109278c..843d5ebf6 100644
--- a/messages/fr.json
+++ b/messages/fr.json
@@ -911,6 +911,12 @@
     "unitRating": "niveau",
     "typeWho5Score": "Score WHO-5",
     "typeSciScore": "Score SCI",
+    "typeExerciseMinutes": "Minutes d’exercice",
+    "typeStandMinutes": "Minutes debout",
+    "typeStandHours": "Heures debout",
+    "typeMindfulMinutes": "Minutes de pleine conscience",
+    "typeStateOfMindValence": "État d’esprit",
+    "typeAfibBurden": "Charge de FA",
     "durationReadAs": "Compris comme {duration}",
     "durationHoursMinutes": "{hours} h {minutes} min",
     "durationHoursOnly": "{hours} h",
@@ -3565,6 +3571,7 @@
       "falls": "chutes",
       "years": "ans",
       "breathingEvents": "événements",
+      "standHours": "heures",
       "respiratoryRate": "respirations/min"
     },
     "sleep": {
@@ -7155,6 +7162,12 @@
         "profile": "Votre profil, vos antécédents médicaux et les informations du dossier de santé",
         "modules": "Données de chaque module : {list}"
       },
+      "workoutRoutes": {
+        "title": "Parcours d’entraînement",
+        "description": "Conserver le tracé GPS des nouveaux entraînements de l’app iPhone et de l’export Apple Santé.",
+        "detail": "Désactivé par défaut. Un parcours montre où vous habitez, travaillez et vous entraînez : il n’est donc conservé qu’une fois l’option activée. Les entraînements sont conservés dans tous les cas, et aucune fonction d’IA ne lit jamais un parcours. Désactiver l’option arrête les nouveaux parcours ; ceux déjà conservés restent jusqu’à la suppression de l’entraînement.",
+        "loadError": "Impossible de charger le réglage des parcours."
+      },
       "retention": {
         "title": "Conservation",
         "description": "Durée de conservation des enregistrements limités dans le temps avant le nettoyage automatique.",
diff --git a/messages/it.json b/messages/it.json
index 91db78f4b..15d737a1c 100644
--- a/messages/it.json
+++ b/messages/it.json
@@ -911,6 +911,12 @@
     "unitRating": "livello",
     "typeWho5Score": "Punteggio WHO-5",
     "typeSciScore": "Punteggio SCI",
+    "typeExerciseMinutes": "Minuti di esercizio",
+    "typeStandMinutes": "Minuti in piedi",
+    "typeStandHours": "Ore in piedi",
+    "typeMindfulMinutes": "Minuti di consapevolezza",
+    "typeStateOfMindValence": "Stato d’animo",
+    "typeAfibBurden": "Carico di FA",
     "durationReadAs": "Letto come {duration}",
     "durationHoursMinutes": "{hours} h {minutes} min",
     "durationHoursOnly": "{hours} h",
@@ -3565,6 +3571,7 @@
       "falls": "cadute",
       "years": "anni",
       "breathingEvents": "eventi",
+      "standHours": "ore",
       "respiratoryRate": "respiri/min"
     },
     "sleep": {
@@ -7155,6 +7162,12 @@
         "profile": "Il tuo profilo, l'anamnesi e i dati della cartella sanitaria",
         "modules": "Dati di ogni modulo: {list}"
       },
+      "workoutRoutes": {
+        "title": "Percorsi degli allenamenti",
+        "description": "Conserva il tracciato GPS dei nuovi allenamenti dall’app per iPhone e dall’esportazione di Apple Salute.",
+        "detail": "Disattivato di default. Un percorso mostra dove vivi, lavori e ti alleni, quindi viene conservato solo dopo averlo attivato. Gli allenamenti vengono conservati comunque e nessuna funzione IA legge mai un percorso. Disattivandolo si fermano i nuovi percorsi; quelli già conservati restano finché non elimini l’allenamento.",
+        "loadError": "Impossibile caricare l’impostazione dei percorsi."
+      },
       "retention": {
         "title": "Conservazione",
         "description": "Per quanto tempo i record a tempo vengono conservati prima della pulizia automatica.",
diff --git a/messages/ko.json b/messages/ko.json
index 0708547d5..f23096369 100644
--- a/messages/ko.json
+++ b/messages/ko.json
@@ -911,6 +911,12 @@
     "unitRating": "단계",
     "typeWho5Score": "WHO-5 점수",
     "typeSciScore": "SCI 점수",
+    "typeExerciseMinutes": "운동 시간(분)",
+    "typeStandMinutes": "서 있기 시간(분)",
+    "typeStandHours": "일어서기 시간",
+    "typeMindfulMinutes": "마음 챙기기 시간(분)",
+    "typeStateOfMindValence": "마음 상태",
+    "typeAfibBurden": "심방세동 부담",
     "durationReadAs": "{duration}(으)로 읽었어요",
     "durationHoursMinutes": "{hours}시간 {minutes}분",
     "durationHoursOnly": "{hours}시간",
@@ -3565,6 +3571,7 @@
       "falls": "회",
       "years": "세",
       "breathingEvents": "회",
+      "standHours": "시간",
       "respiratoryRate": "회/분"
     },
     "sleep": {
@@ -7155,6 +7162,12 @@
         "profile": "프로필, 병력, 건강 기록 정보",
         "modules": "모듈별 기록: {list}"
       },
+      "workoutRoutes": {
+        "title": "운동 경로",
+        "description": "iPhone 앱과 Apple 건강 내보내기에서 새 운동의 GPS 경로를 저장합니다.",
+        "detail": "기본값은 꺼짐입니다. 경로는 사는 곳, 일하는 곳, 운동하는 곳을 보여 주므로 이 설정을 켠 뒤에만 저장됩니다. 운동 기록은 항상 저장되며, 어떤 AI 기능도 경로를 읽지 않습니다. 끄면 새 경로 저장이 멈추고, 이미 저장된 경로는 운동을 삭제할 때까지 남습니다.",
+        "loadError": "경로 설정을 불러오지 못했습니다."
+      },
       "retention": {
         "title": "보관 기간",
         "description": "자동 정리 전까지 기간이 정해진 기록을 얼마나 보관하는지예요.",
diff --git a/messages/nl.json b/messages/nl.json
index c5e9d9a13..3f6fabe35 100644
--- a/messages/nl.json
+++ b/messages/nl.json
@@ -911,6 +911,12 @@
     "unitRating": "beoordeling",
     "typeWho5Score": "WHO-5-score",
     "typeSciScore": "SCI-score",
+    "typeExerciseMinutes": "Trainingsminuten",
+    "typeStandMinutes": "Staminuten",
+    "typeStandHours": "Stauren",
+    "typeMindfulMinutes": "Mindfulnessminuten",
+    "typeStateOfMindValence": "Gemoedstoestand",
+    "typeAfibBurden": "AF-belasting",
     "durationReadAs": "Gelezen als {duration}",
     "durationHoursMinutes": "{hours} u {minutes} min",
     "durationHoursOnly": "{hours} u",
@@ -3565,6 +3571,7 @@
       "falls": "valpartijen",
       "years": "jaar",
       "breathingEvents": "gebeurtenissen",
+      "standHours": "uur",
       "respiratoryRate": "ademhalingen/min"
     },
     "sleep": {
@@ -7155,6 +7162,12 @@
         "profile": "Je profiel, medische voorgeschiedenis en dossiergegevens",
         "modules": "Gegevens van elke module: {list}"
       },
+      "workoutRoutes": {
+        "title": "Trainingsroutes",
+        "description": "Het GPS-spoor van nieuwe trainingen uit de iPhone-app en de Apple Gezondheid-export bewaren.",
+        "detail": "Standaard uit. Een route laat zien waar je woont, werkt en traint, dus hij wordt pas bewaard als je dit aanzet. Trainingen worden altijd bewaard en geen enkele AI-functie leest ooit een route. Uitzetten stopt nieuwe routes; al bewaarde routes blijven tot je de training verwijdert.",
+        "loadError": "De route-instelling kon niet worden geladen."
+      },
       "retention": {
         "title": "Bewaartermijn",
         "description": "Hoe lang tijdgebonden gegevens worden bewaard voordat ze automatisch worden opgeschoond.",
diff --git a/messages/pl.json b/messages/pl.json
index 6d55a5d6d..66982c68e 100644
--- a/messages/pl.json
+++ b/messages/pl.json
@@ -911,6 +911,12 @@
     "unitRating": "poziom",
     "typeWho5Score": "Wynik WHO-5",
     "typeSciScore": "Wynik SCI",
+    "typeExerciseMinutes": "Minuty ćwiczeń",
+    "typeStandMinutes": "Minuty stania",
+    "typeStandHours": "Godziny stania",
+    "typeMindfulMinutes": "Minuty uważności",
+    "typeStateOfMindValence": "Stan umysłu",
+    "typeAfibBurden": "Obciążenie AF",
     "durationReadAs": "Odczytano jako {duration}",
     "durationHoursMinutes": "{hours} godz. {minutes} min",
     "durationHoursOnly": "{hours} godz.",
@@ -3565,6 +3571,7 @@
       "falls": "upadki",
       "years": "lata",
       "breathingEvents": "zdarzenia",
+      "standHours": "godz.",
       "respiratoryRate": "oddechów/min"
     },
     "sleep": {
@@ -7155,6 +7162,12 @@
         "profile": "Twój profil, wywiad medyczny i dane dokumentacji zdrowotnej",
         "modules": "Wpisy poszczególnych modułów: {list}"
       },
+      "workoutRoutes": {
+        "title": "Trasy treningów",
+        "description": "Zapisuj ślad GPS nowych treningów z aplikacji na iPhone’a i z eksportu Apple Zdrowie.",
+        "detail": "Domyślnie wyłączone. Trasa pokazuje, gdzie mieszkasz, pracujesz i trenujesz, więc zapisujemy ją dopiero po włączeniu. Treningi są zapisywane zawsze, a żadna funkcja AI nigdy nie odczytuje trasy. Wyłączenie zatrzymuje nowe trasy; już zapisane zostają do usunięcia treningu.",
+        "loadError": "Nie udało się wczytać ustawienia tras."
+      },
       "retention": {
         "title": "Retencja",
         "description": "Jak długo rekordy ograniczone czasowo są przechowywane przed automatycznym czyszczeniem.",
diff --git a/prisma/migrations/0431_apple_health_activity_mind_afib/migration.sql b/prisma/migrations/0431_apple_health_activity_mind_afib/migration.sql
new file mode 100644
index 000000000..d48e5661c
--- /dev/null
+++ b/prisma/migrations/0431_apple_health_activity_mind_afib/migration.sql
@@ -0,0 +1,21 @@
+-- Extend `measurement_type` with six Apple Health signals that sat in the
+-- deferred list: the exercise and stand rings, mindful minutes, the State of
+-- Mind valence, and AFib burden.
+--
+--   EXERCISE_MINUTES       <- HKQuantityTypeIdentifierAppleExerciseTime
+--   STAND_MINUTES          <- HKQuantityTypeIdentifierAppleStandTime
+--   STAND_HOURS            <- HKCategoryTypeIdentifierAppleStandHour
+--   MINDFUL_MINUTES        <- HKCategoryTypeIdentifierMindfulSession
+--   STATE_OF_MIND_VALENCE  <- HKDataTypeIdentifierStateOfMind (valence)
+--   AFIB_BURDEN            <- HKQuantityTypeIdentifierAtrialFibrillationBurden
+--
+-- Purely additive: no existing row carries any of these values. IF NOT
+-- EXISTS keeps a replay on a partially applied database harmless. Enum
+-- values cannot be dropped in PostgreSQL, so there is no down path.
+
+ALTER TYPE "measurement_type" ADD VALUE IF NOT EXISTS 'EXERCISE_MINUTES';
+ALTER TYPE "measurement_type" ADD VALUE IF NOT EXISTS 'STAND_MINUTES';
+ALTER TYPE "measurement_type" ADD VALUE IF NOT EXISTS 'STAND_HOURS';
+ALTER TYPE "measurement_type" ADD VALUE IF NOT EXISTS 'MINDFUL_MINUTES';
+ALTER TYPE "measurement_type" ADD VALUE IF NOT EXISTS 'STATE_OF_MIND_VALENCE';
+ALTER TYPE "measurement_type" ADD VALUE IF NOT EXISTS 'AFIB_BURDEN';
diff --git a/prisma/migrations/0432_store_workout_routes/migration.sql b/prisma/migrations/0432_store_workout_routes/migration.sql
new file mode 100644
index 000000000..4ce5ea98f
--- /dev/null
+++ b/prisma/migrations/0432_store_workout_routes/migration.sql
@@ -0,0 +1,6 @@
+-- A per-account opt-in for keeping workout GPS tracks. Off by default: a
+-- route shows where a person lives, works and trains, so new tracks are
+-- stored only once the person turns this on. Tracks already stored stay
+-- where they are; the setting decides what new syncs and imports keep.
+
+ALTER TABLE "users" ADD COLUMN IF NOT EXISTS "store_workout_routes" BOOLEAN NOT NULL DEFAULT false;
diff --git a/prisma/schema.prisma b/prisma/schema.prisma
index 61e9e8270..82129aac4 100644
--- a/prisma/schema.prisma
+++ b/prisma/schema.prisma
@@ -374,6 +374,12 @@ model User {
   // review screen remains the safety backstop. Default `false`; vision-capable
   // users keep the higher-accuracy native path and never pay the WASM download.
   labsLocalOcrEnabled      Boolean              @default(false) @map("labs_local_ocr_enabled")
+  /// v1.44 — keep the GPS track of a workout. OFF by default: a route is
+  /// where a person lives, works and runs, so it is stored only after they
+  /// opt in. Read by the workout batch route and the export.zip import, which
+  /// drop the track while it is off (the workout itself is always kept).
+  /// Never read by any AI path; the AI egress guard freezes the route readers.
+  storeWorkoutRoutes       Boolean              @default(false) @map("store_workout_routes")
   // v1.7.0 unit pref — global metric/imperial display preference.
   // Canonical storage stays SI; this only selects the display-time
   // transform branch (km/h vs mph, km vs mi). Null = default "metric".
@@ -1703,6 +1709,16 @@ enum MeasurementType {
   // Note the inverted direction versus PHQ-9 / GAD-7: HIGHER is better for both.
   WHO5_SCORE // score (0–100) — WHO-5 well-being percentage (raw 0–25 × 4). Opt-in. See MentalHealthAssessment.
   SCI_SCORE // score (0–32) — Sleep Condition Indicator total; higher = better sleep. Opt-in. See MentalHealthAssessment.
+  // ── v1.44 — Apple Health activity rings, mindfulness, mood and AFib burden ──
+  // All five arrive over POST /api/measurements/batch and the export.zip import.
+  // The minute and hour types are cumulative (daily SUM); AFib burden and the
+  // State of Mind valence are spot readings.
+  EXERCISE_MINUTES // minutes — HealthKit `appleExerciseTime`. The activity ring's exercise minutes; cumulative, daily SUM.
+  STAND_MINUTES // minutes — HealthKit `appleStandTime`. Minutes spent standing; cumulative, daily SUM.
+  STAND_HOURS // count — HealthKit `HKCategoryTypeIdentifierAppleStandHour`. One row per hour in which the person stood (`stood` = 1; an `idle` hour is not stored); cumulative, daily SUM gives the stand-ring hours.
+  MINDFUL_MINUTES // minutes — HealthKit `HKCategoryTypeIdentifierMindfulSession`. Session length from the sample's own dates; cumulative, daily SUM.
+  STATE_OF_MIND_VALENCE // valence (−1..1) — HealthKit `HKStateOfMind.valence` (iOS 18+). How pleasant the logged emotion or mood felt, from very unpleasant (−1) to very pleasant (1). A self-report, not a measurement.
+  AFIB_BURDEN // percent (0–100, scaled ×100 from Apple's 0..1 fraction) — HealthKit `atrialFibrillationBurden` (iOS 16+, AFib History). The share of time the watch estimated in AFib over a week. AWARENESS ONLY — never a HealthLog diagnosis.
 
   @@map("measurement_type")
 }
diff --git a/src/__tests__/ai-egress-capability-guard.test.ts b/src/__tests__/ai-egress-capability-guard.test.ts
index ed12342c5..140c21f96 100644
--- a/src/__tests__/ai-egress-capability-guard.test.ts
+++ b/src/__tests__/ai-egress-capability-guard.test.ts
@@ -288,3 +288,85 @@ describe("the status chokepoint's capability argument", () => {
     expect(withCapability.capability).toBe("statusText");
   });
 });
+
+/**
+ * Workout GPS tracks never reach a model.
+ *
+ * A route shows where a person lives, works and trains, and it is stored only
+ * after an opt-in. So the set of files that can open or write a track is
+ * frozen here, with the reason each needs it, and none of them may be a
+ * provider call site or sit in an AI module. The workout insight used to open
+ * the track to derive metres climbed; that figure is now filled into
+ * `Workout.elevationM` at write time (`route-climb.ts`), and the insight reads
+ * the column. A new reader fails the first check until someone decides, here,
+ * that it is not an AI path.
+ *
+ * Limit: the matcher looks for the cipher helpers, the sealed column and a
+ * `geometry: true` select. A read under some other spelling (a raw SQL
+ * `SELECT geometry_encrypted`, a backup dumping the model generically) would
+ * slip it. The generic backup dump and restore do carry the sealed column;
+ * they are not AI paths and hand it to no model.
+ */
+describe("workout route geometry never reaches an AI path", () => {
+  const ROUTE_READER =
+    /\breadRouteGeometry\s*\(|\bencryptRouteGeometry\s*\(|\bgeometryEncrypted\b|\bgeometry\s*:\s*true\b/;
+
+  const ROUTE_READERS: Record<string, string> = {
+    "app/api/workouts/[id]/route.ts":
+      "The workout detail read: serves the track to the person's own map.",
+    "app/api/workouts/batch/route.ts":
+      "Writes a kept track (opt-in) and derives its climb before storage.",
+    "lib/apple-health/route-import.ts":
+      "Writes a kept track from the Apple Health export (opt-in).",
+    "lib/crypto/encrypted-columns.ts":
+      "The encrypted-column registry the key rotation walks.",
+    "lib/jobs/free-text-encryption-backfill.ts":
+      "Seals legacy readable tracks in place.",
+    "lib/workouts/route-geometry-cipher.ts": "The cipher itself.",
+  };
+
+  /** Directories whose code feeds a model. */
+  const AI_AREAS = [
+    "lib/ai/",
+    "lib/insights/",
+    "lib/mcp/",
+    "app/mcp/",
+    "app/api/insights/",
+    "app/api/coach/",
+  ];
+
+  const found = sourceFiles().filter((rel) => ROUTE_READER.test(code(rel)));
+
+  it("finds route readers at all (an empty matcher is a failure, not a pass)", () => {
+    expect(found.length).toBeGreaterThanOrEqual(4);
+  });
+
+  it("every file that opens or writes a track is named, with a reason", () => {
+    expect(found.filter((rel) => !(rel in ROUTE_READERS))).toEqual([]);
+  });
+
+  it("the list carries no file that no longer touches a track", () => {
+    expect(
+      Object.keys(ROUTE_READERS).filter((rel) => !found.includes(rel)),
+    ).toEqual([]);
+  });
+
+  it("no route reader calls a provider or lives in an AI module", () => {
+    for (const rel of Object.keys(ROUTE_READERS)) {
+      expect(rel in EGRESS_SITES, `${rel} is an egress site`).toBe(false);
+      expect(EGRESS_CALL.test(code(rel)), `${rel} calls a provider`).toBe(
+        false,
+      );
+      expect(
+        AI_AREAS.some((area) => rel.startsWith(area)),
+        `${rel} sits in an AI module`,
+      ).toBe(false);
+    }
+  });
+
+  it("the workout insight job does not read the track", () => {
+    const job = code("lib/jobs/workout-insight-generate.ts");
+    expect(job).not.toMatch(/\broute\s*:/);
+    expect(job).not.toMatch(ROUTE_READER);
+  });
+});
diff --git a/src/__tests__/doctor-report-control-gating-guard.test.ts b/src/__tests__/doctor-report-control-gating-guard.test.ts
index 36a3a0765..1c06583ae 100644
--- a/src/__tests__/doctor-report-control-gating-guard.test.ts
+++ b/src/__tests__/doctor-report-control-gating-guard.test.ts
@@ -74,8 +74,8 @@ describe("report scope gating — structural guard", () => {
   it("reads a plausible catalogue", () => {
     // Sanity floor: a silently degraded catalogue would pass everything below
     // vacuously.
-    expect(ALL_LEAF_IDS.length).toBe(95);
-    expect(Object.keys(MEASUREMENT_LEAF_GROUP)).toHaveLength(77);
+    expect(ALL_LEAF_IDS.length).toBe(101);
+    expect(Object.keys(MEASUREMENT_LEAF_GROUP)).toHaveLength(83);
     expect(Object.keys(STRUCTURED_LEAF_GROUP)).toHaveLength(18);
   });
 
diff --git a/src/app/api/auth/me/workout-routes/__tests__/route.test.ts b/src/app/api/auth/me/workout-routes/__tests__/route.test.ts
new file mode 100644
index 000000000..dad36584d
--- /dev/null
+++ b/src/app/api/auth/me/workout-routes/__tests__/route.test.ts
@@ -0,0 +1,121 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * The workout-route opt-in: off by default, a hard-set PATCH, audit-logged,
+ * and a malformed body refused before anything is written.
+ */
+
+vi.mock("@/lib/db", () => ({
+  prisma: { user: { findUnique: vi.fn(), update: vi.fn() } },
+}));
+vi.mock("@/lib/auth/session", () => ({ getSession: vi.fn() }));
+vi.mock("@/lib/auth/audit", () => ({
+  auditLog: vi.fn().mockResolvedValue(undefined),
+}));
+vi.mock("@/lib/logging/transports", () => ({ emitIfSampled: vi.fn() }));
+vi.mock("@/lib/db-compat", () => ({
+  ensureDbCompatibility: vi.fn().mockResolvedValue(undefined),
+}));
+vi.mock("@/lib/rate-limit", () => ({
+  checkRateLimit: vi.fn().mockResolvedValue({
+    allowed: true,
+    remaining: 59,
+    resetAt: Date.now() + 60_000,
+  }),
+  rateLimitHeaders: () => ({}),
+}));
+vi.mock("next/headers", () => ({
+  headers: vi.fn(async () => ({ get: () => null })),
+  cookies: vi.fn(async () => ({
+    get: () => undefined,
+    set: () => {},
+    delete: () => {},
+  })),
+}));
+
+import { GET, PATCH } from "../route";
+import { prisma } from "@/lib/db";
+import { getSession } from "@/lib/auth/session";
+import { auditLog } from "@/lib/auth/audit";
+
+const SESSION_OK = {
+  session: { id: "sess-1", expiresAt: new Date(Date.now() + 3_600_000) },
+  user: { id: "user-1", username: "testuser", role: "USER" as const },
+};
+
+function mkPatch(body: unknown): Request {
+  return new Request("http://localhost/api/auth/me/workout-routes", {
+    method: "PATCH",
+    body: JSON.stringify(body),
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  vi.mocked(getSession).mockResolvedValue(SESSION_OK as never);
+  vi.mocked(prisma.user.update).mockResolvedValue({} as never);
+});
+
+describe("/api/auth/me/workout-routes", () => {
+  it("reads off when the row carries no value", async () => {
+    vi.mocked(prisma.user.findUnique).mockResolvedValue(null);
+    const res = await GET(
+      new Request("http://localhost/api/auth/me/workout-routes") as never,
+      { params: Promise.resolve({}) } as never,
+    );
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({
+      data: { storeWorkoutRoutes: false },
+    });
+  });
+
+  it("sets the flag field by field and audits the change", async () => {
+    vi.mocked(prisma.user.findUnique).mockResolvedValue({
+      storeWorkoutRoutes: false,
+    } as never);
+    const res = await PATCH(
+      mkPatch({ storeWorkoutRoutes: true }) as never,
+      {
+        params: Promise.resolve({}),
+      } as never,
+    );
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({
+      data: { storeWorkoutRoutes: true },
+    });
+    expect(prisma.user.update).toHaveBeenCalledWith({
+      where: { id: "user-1" },
+      data: { storeWorkoutRoutes: true },
+    });
+    expect(auditLog).toHaveBeenCalledWith(
+      "user.storeWorkoutRoutes.update",
+      expect.objectContaining({
+        details: { previous: false, next: true },
+      }),
+    );
+  });
+
+  it("refuses a malformed body with 422 and writes nothing", async () => {
+    const res = await PATCH(
+      mkPatch({ storeWorkoutRoutes: "yes" }) as never,
+      {
+        params: Promise.resolve({}),
+      } as never,
+    );
+    expect(res.status).toBe(422);
+    expect(prisma.user.update).not.toHaveBeenCalled();
+  });
+
+  it("refuses an unauthenticated caller", async () => {
+    vi.mocked(getSession).mockResolvedValue(null);
+    const res = await PATCH(
+      mkPatch({ storeWorkoutRoutes: true }) as never,
+      {
+        params: Promise.resolve({}),
+      } as never,
+    );
+    expect(res.status).toBe(401);
+    expect(prisma.user.update).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/app/api/auth/me/workout-routes/route.ts b/src/app/api/auth/me/workout-routes/route.ts
new file mode 100644
index 000000000..aea7aba69
--- /dev/null
+++ b/src/app/api/auth/me/workout-routes/route.ts
@@ -0,0 +1,109 @@
+/**
+ * Per-account opt-in for keeping workout GPS tracks.
+ *
+ *  GET    /api/auth/me/workout-routes  — current flag.
+ *  PATCH  /api/auth/me/workout-routes  — body `{ storeWorkoutRoutes: boolean }`.
+ *
+ * Off by default. While it is off, `POST /api/workouts/batch` and the
+ * Apple Health export import keep every workout but drop its track, so a
+ * route (where a person lives, works and trains) is stored only after the
+ * person asked for it. Turning it off later stops new tracks; tracks already
+ * stored stay until the workout or the account is deleted.
+ *
+ * Same per-user-scalar pattern as `labs-local-ocr`: 60/min rate limit, a
+ * bounded body, Zod safeParse → 422, field-by-field write, audit row, and
+ * the resolved next state in the response.
+ */
+import { apiHandler, requireAuth } from "@/lib/api-handler";
+import {
+  apiError,
+  apiSuccess,
+  getClientIp,
+  returnAllZodIssues,
+  safeJson,
+} from "@/lib/api-response";
+import { annotate } from "@/lib/logging/context";
+import { auditLog } from "@/lib/auth/audit";
+import { prisma } from "@/lib/db";
+import { checkRateLimit, rateLimitHeaders } from "@/lib/rate-limit";
+import { workoutRoutesPatchSchema } from "@/lib/validations/user-prefs";
+
+export const dynamic = "force-dynamic";
+
+const PATCH_RATE_LIMIT = 60;
+const PATCH_WINDOW_MS = 60_000;
+
+type WorkoutRoutesResponse = {
+  storeWorkoutRoutes: boolean;
+};
+
+export const GET = apiHandler(async () => {
+  const { user } = await requireAuth();
+  annotate({ action: { name: "auth.me.workoutRoutes.get" } });
+
+  const row = await prisma.user.findUnique({
+    where: { id: user.id },
+    select: { storeWorkoutRoutes: true },
+  });
+  const payload: WorkoutRoutesResponse = {
+    storeWorkoutRoutes: row?.storeWorkoutRoutes ?? false,
+  };
+  return apiSuccess(payload);
+});
+
+export const PATCH = apiHandler(async (req: Request) => {
+  const { user } = await requireAuth();
+
+  const rl = await checkRateLimit(
+    `workout-routes:patch:${user.id}`,
+    PATCH_RATE_LIMIT,
+    PATCH_WINDOW_MS,
+  );
+  if (!rl.allowed) {
+    const response = apiError("Too many requests", 429);
+    for (const [k, v] of Object.entries(rateLimitHeaders(rl))) {
+      response.headers.set(k, v);
+    }
+    return response;
+  }
+
+  const { data: body, error: jsonError } = await safeJson(req, {
+    maxBytes: 1024,
+  });
+  if (jsonError) return jsonError;
+
+  const parsed = workoutRoutesPatchSchema.safeParse(body);
+  if (!parsed.success) {
+    annotate({ action: { name: "auth.me.workoutRoutes.patch.invalid_shape" } });
+    return returnAllZodIssues(parsed.error, 422);
+  }
+
+  const next = parsed.data.storeWorkoutRoutes;
+
+  const previous = await prisma.user.findUnique({
+    where: { id: user.id },
+    select: { storeWorkoutRoutes: true },
+  });
+
+  await prisma.user.update({
+    where: { id: user.id },
+    data: { storeWorkoutRoutes: next },
+  });
+
+  await auditLog("user.storeWorkoutRoutes.update", {
+    userId: user.id,
+    ipAddress: getClientIp(req),
+    details: {
+      previous: previous?.storeWorkoutRoutes ?? false,
+      next,
+    },
+  });
+
+  annotate({
+    action: { name: "auth.me.workoutRoutes.patch" },
+    meta: { storeWorkoutRoutes: next },
+  });
+
+  const payload: WorkoutRoutesResponse = { storeWorkoutRoutes: next };
+  return apiSuccess(payload);
+});
diff --git a/src/app/api/workouts/__tests__/batch-create.test.ts b/src/app/api/workouts/__tests__/batch-create.test.ts
index 0a434f9a9..ecdc3b436 100644
--- a/src/app/api/workouts/__tests__/batch-create.test.ts
+++ b/src/app/api/workouts/__tests__/batch-create.test.ts
@@ -203,8 +203,11 @@ beforeEach(() => {
   // v1.4.43 — default to no per-user source-priority override so
   // the write-time picker walks the canonical default ladder. Tests
   // that exercise a custom ladder override this in-line.
+  // The route opt-in is on here so the route cases below exercise the
+  // write; the off case sets it explicitly.
   vi.mocked(prisma.user.findUnique).mockResolvedValue({
     sourcePriorityJson: null,
+    storeWorkoutRoutes: true,
   } as never);
 });
 
@@ -507,6 +510,55 @@ describe("POST /api/workouts/batch — per-entry status envelope", () => {
   });
 });
 
+describe("POST /api/workouts/batch — workout-route opt-in", () => {
+  const withRoute = () =>
+    validWorkout("uuid-with-route", {
+      route: {
+        geometry: {
+          type: "LineString",
+          coordinates: [
+            [11.077, 49.452],
+            [11.078, 49.453],
+          ],
+        },
+      },
+    });
+
+  it("keeps the workout and drops the track while the opt-in is off", async () => {
+    vi.mocked(prisma.user.findUnique).mockResolvedValue({
+      sourcePriorityJson: null,
+      storeWorkoutRoutes: false,
+    } as never);
+    vi.mocked(prisma.workout.createMany).mockResolvedValue({ count: 1 });
+    mockInsertReturning([
+      { id: "wkt-off", source: "APPLE_HEALTH", externalId: "uuid-with-route" },
+    ]);
+
+    const res = await POST(makeRequest({ workouts: [withRoute()] }));
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      data: { entries: Array<{ status: string }> };
+    };
+    // Same per-entry status as a stored track: the client needs no branch.
+    expect(body.data.entries[0]?.status).toBe("inserted");
+    expect(prisma.workoutRoute.createMany).not.toHaveBeenCalled();
+  });
+
+  it("drops the track when the account row carries no opt-in at all", async () => {
+    vi.mocked(prisma.user.findUnique).mockResolvedValue({
+      sourcePriorityJson: null,
+    } as never);
+    vi.mocked(prisma.workout.createMany).mockResolvedValue({ count: 1 });
+    mockInsertReturning([
+      { id: "wkt-none", source: "APPLE_HEALTH", externalId: "uuid-with-route" },
+    ]);
+
+    const res = await POST(makeRequest({ workouts: [withRoute()] }));
+    expect(res.status).toBe(200);
+    expect(prisma.workoutRoute.createMany).not.toHaveBeenCalled();
+  });
+});
+
 describe("POST /api/workouts/batch — nested route attachment", () => {
   it("creates a WorkoutRoute row for a workout that ships a route", async () => {
     vi.mocked(prisma.workout.createMany).mockResolvedValue({ count: 1 });
@@ -700,7 +752,7 @@ describe("POST /api/workouts/batch — user source-priority (v1.4.43 W9)", () =>
     expect(sourcePriorityReads).toHaveLength(1);
     expect(prisma.user.findUnique).toHaveBeenCalledWith({
       where: { id: "user-1" },
-      select: { sourcePriorityJson: true },
+      select: { sourcePriorityJson: true, storeWorkoutRoutes: true },
     });
   });
 
diff --git a/src/app/api/workouts/batch/route.ts b/src/app/api/workouts/batch/route.ts
index 37ca6dfaf..90c88cb54 100644
--- a/src/app/api/workouts/batch/route.ts
+++ b/src/app/api/workouts/batch/route.ts
@@ -66,6 +66,7 @@ import { NextRequest } from "next/server";
 
 import { prisma } from "@/lib/db";
 import { apiHandler, isScopedCredential, requireAuth } from "@/lib/api-handler";
+import { routeClimbM } from "@/lib/workouts/route-climb";
 import { annotate } from "@/lib/logging/context";
 import { auditLog } from "@/lib/auth/audit";
 import {
@@ -259,10 +260,15 @@ async function postBatch(request: NextRequest): Promise<Response> {
   // time before the read-time picker ever ran. One indexed
   // findUnique per batch — well under the cost of letting the
   // duplicate persist and carrying it forward on every read.
+  // The same read carries the route opt-in: a GPS track is kept only when
+  // the person turned `storeWorkoutRoutes` on. While it is off the workout
+  // is stored and the track dropped, with the same per-entry status, so a
+  // client cannot tell the two apart and needs no new branch.
   const userPriority = await prisma.user.findUnique({
     where: { id: user.id },
-    select: { sourcePriorityJson: true },
+    select: { sourcePriorityJson: true, storeWorkoutRoutes: true },
   });
+  const keepRoutes = userPriority?.storeWorkoutRoutes === true;
 
   // Content-Length pre-flight. The body cap exists to bound the
   // request-pipeline cost BEFORE Node has to read the full payload —
@@ -440,12 +446,13 @@ async function postBatch(request: NextRequest): Promise<Response> {
       0,
       Math.round((w.endedAt.getTime() - w.startedAt.getTime()) / 1000),
     );
-    const route = w.route
-      ? {
-          geometry: w.route.geometry as unknown,
-          sampleTimestamps: (w.route.sampleTimestamps ?? null) as unknown,
-        }
-      : null;
+    const route =
+      w.route && keepRoutes
+        ? {
+            geometry: w.route.geometry as unknown,
+            sampleTimestamps: (w.route.sampleTimestamps ?? null) as unknown,
+          }
+        : null;
     const samples = w.samples
       ? {
           samples: w.samples as unknown,
@@ -464,7 +471,9 @@ async function postBatch(request: NextRequest): Promise<Response> {
       maxHeartRate: w.maxHeartRate ?? null,
       minHeartRate: w.minHeartRate ?? null,
       stepCount: w.stepCount ?? null,
-      elevationM: w.elevationM ?? null,
+      // A kept track fills the climb when the source sent none, so the figure
+      // lives on the workout row and no reader has to open the track for it.
+      elevationM: w.elevationM ?? (route ? routeClimbM(route.geometry) : null),
       pauseDurationSec: w.pauseDurationSec ?? null,
       // `EXTERNAL` under a scoped credential, and nothing else: the guard
       // above refused any body that named a source, so nothing asserted is
@@ -908,6 +917,10 @@ async function postBatch(request: NextRequest): Promise<Response> {
       enriched: enrichedCount,
       updated: updatedCount,
       skipped: skipped.length,
+      // Tracks the body carried but the opt-in told us not to keep.
+      routes_dropped: keepRoutes
+        ? 0
+        : workouts.filter((w) => w.route != null).length,
     },
   });
 
diff --git a/src/components/measurements/measurement-list-meta.ts b/src/components/measurements/measurement-list-meta.ts
index e190c189a..5be62c111 100644
--- a/src/components/measurements/measurement-list-meta.ts
+++ b/src/components/measurements/measurement-list-meta.ts
@@ -132,6 +132,13 @@ export const MEASUREMENT_TYPE_LABEL_KEYS: Record<string, string> = {
   PAIN_NRS: "measurements.typePainNrs",
   WAIST_CIRCUMFERENCE: "measurements.typeWaistCircumference",
   WAIST_TO_HEIGHT: "measurements.typeWaistToHeight",
+  // ── v1.44 — activity rings, mindfulness, State of Mind, AFib burden ──
+  EXERCISE_MINUTES: "measurements.typeExerciseMinutes",
+  STAND_MINUTES: "measurements.typeStandMinutes",
+  STAND_HOURS: "measurements.typeStandHours",
+  MINDFUL_MINUTES: "measurements.typeMindfulMinutes",
+  STATE_OF_MIND_VALENCE: "measurements.typeStateOfMindValence",
+  AFIB_BURDEN: "measurements.typeAfibBurden",
 };
 
 export const MEASUREMENT_TYPE_ICONS: Record<string, LucideIcon> = {
@@ -267,6 +274,14 @@ export const MEASUREMENT_TYPE_ICONS: Record<string, LucideIcon> = {
   PAIN_NRS: Activity,
   WAIST_CIRCUMFERENCE: Scale,
   WAIST_TO_HEIGHT: Scale,
+  // ── v1.44 — the rings take the activity glyphs, mindful minutes the
+  // breath, the valence the score dial, AFib burden the rhythm trace.
+  EXERCISE_MINUTES: Dumbbell,
+  STAND_MINUTES: PersonStanding,
+  STAND_HOURS: PersonStanding,
+  MINDFUL_MINUTES: Wind,
+  STATE_OF_MIND_VALENCE: Gauge,
+  AFIB_BURDEN: HeartPulse,
 };
 
 // The colour map lives in its own icon-free module so a surface that only
diff --git a/src/components/measurements/measurement-type-colors.ts b/src/components/measurements/measurement-type-colors.ts
index 5f3386b6c..76a7d6803 100644
--- a/src/components/measurements/measurement-type-colors.ts
+++ b/src/components/measurements/measurement-type-colors.ts
@@ -129,4 +129,13 @@ export const MEASUREMENT_TYPE_COLORS: Record<string, string> = {
   PAIN_NRS: "bg-chart-3/10 text-chart-3 dark:bg-chart-3/20",
   WAIST_CIRCUMFERENCE: "bg-chart-4/10 text-chart-4 dark:bg-chart-4/20",
   WAIST_TO_HEIGHT: "bg-chart-4/10 text-chart-4 dark:bg-chart-4/20",
+  // ── v1.44 — the rings and mindful minutes join the activity family
+  // (chart-2), the valence the score family (chart-1), AFib burden the
+  // cardio family (chart-3).
+  EXERCISE_MINUTES: "bg-chart-2/10 text-chart-2 dark:bg-chart-2/20",
+  STAND_MINUTES: "bg-chart-2/10 text-chart-2 dark:bg-chart-2/20",
+  STAND_HOURS: "bg-chart-2/10 text-chart-2 dark:bg-chart-2/20",
+  MINDFUL_MINUTES: "bg-chart-2/10 text-chart-2 dark:bg-chart-2/20",
+  STATE_OF_MIND_VALENCE: "bg-chart-1/10 text-chart-1 dark:bg-chart-1/20",
+  AFIB_BURDEN: "bg-chart-3/10 text-chart-3 dark:bg-chart-3/20",
 };
diff --git a/src/components/settings/__tests__/report-selection-panel.test.tsx b/src/components/settings/__tests__/report-selection-panel.test.tsx
index 394ee3b19..b3c162515 100644
--- a/src/components/settings/__tests__/report-selection-panel.test.tsx
+++ b/src/components/settings/__tests__/report-selection-panel.test.tsx
@@ -194,8 +194,8 @@ describe("<HealthRecordExportPanel> — the first run", () => {
     expect(groupChip(html, "medications")).toBe("0/4");
     // ALLERGIES, ILLNESS_EPISODES, VISITS, SURGICAL_HISTORY, IMMUNIZATIONS.
     expect(groupChip(html, "history")).toBe("0/5");
-    expect(groupChip(html, "cardio")).toBe("0/14");
-    expect(groupChip(html, "activity")).toBe("0/8");
+    expect(groupChip(html, "cardio")).toBe("0/15");
+    expect(groupChip(html, "activity")).toBe("0/11");
     expect(groupChip(html, "sleepRecovery")).toBe("0/16");
     expect(groupChip(html, "mobility")).toBe("0/11");
     expect(groupChip(html, "environment")).toBe("0/4");
diff --git a/src/components/settings/privacy-section.tsx b/src/components/settings/privacy-section.tsx
index 193017392..393543b91 100644
--- a/src/components/settings/privacy-section.tsx
+++ b/src/components/settings/privacy-section.tsx
@@ -32,6 +32,7 @@ import { SettingsInfoTile } from "@/components/settings/_info-tile";
 import { SecuritySessionsCard } from "@/components/settings/security-sessions-card";
 import { SecurityActivityCard } from "@/components/settings/security-activity-card";
 import { TrustedDevicesCard } from "@/components/settings/trusted-devices-card";
+import { WorkoutRoutesCard } from "@/components/settings/workout-routes-card";
 import { useAuth } from "@/hooks/use-auth";
 import { useTranslations } from "@/lib/i18n/context";
 import { MODULE_KEYS, MODULE_REGISTRY } from "@/lib/modules/registry";
@@ -130,6 +131,9 @@ export function PrivacySection() {
         </ul>
       </SettingsCard>
 
+      {/* Workout GPS tracks: kept only on opt-in. */}
+      <WorkoutRoutesCard />
+
       {/* Retention */}
       <SettingsCard>
         <SettingsCardHeader
diff --git a/src/components/settings/workout-routes-card.tsx b/src/components/settings/workout-routes-card.tsx
new file mode 100644
index 000000000..774863eeb
--- /dev/null
+++ b/src/components/settings/workout-routes-card.tsx
@@ -0,0 +1,83 @@
+"use client";
+
+/**
+ * The workout-route opt-in on the Data & Privacy page.
+ *
+ * Off by default. A GPS track shows where a person lives, works and trains,
+ * so new tracks from the iPhone app and the Apple Health export are kept
+ * only once this is on; the workouts themselves are kept either way. No AI
+ * feature ever reads a track.
+ */
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { MapPinned } from "lucide-react";
+
+import { toastWrittenOutcome } from "@/components/outcome/outcome-toast";
+import { SettingsCardHeader } from "@/components/settings/_card-header";
+import { SettingsCard } from "@/components/settings/settings-card";
+import { QueryErrorRow } from "@/components/ui/query-error-row";
+import { Switch } from "@/components/ui/switch";
+import { apiGet, apiPatch } from "@/lib/api/api-fetch";
+import { showErrorToast } from "@/lib/errors/error-toast";
+import { useTranslations } from "@/lib/i18n/context";
+import { queryKeys } from "@/lib/query-keys";
+
+interface WorkoutRoutesPref {
+  storeWorkoutRoutes: boolean;
+}
+
+export function WorkoutRoutesCard() {
+  const { t } = useTranslations();
+  const queryClient = useQueryClient();
+  const pref = useQuery<WorkoutRoutesPref>({
+    queryKey: queryKeys.workoutRoutesPref(),
+    queryFn: () => apiGet<WorkoutRoutesPref>("/api/auth/me/workout-routes"),
+    staleTime: 60_000,
+  });
+  const update = useMutation<WorkoutRoutesPref, Error, boolean>({
+    mutationFn: (storeWorkoutRoutes) =>
+      apiPatch<WorkoutRoutesPref>("/api/auth/me/workout-routes", {
+        storeWorkoutRoutes,
+      }),
+    onSuccess: (data) => {
+      queryClient.setQueryData(queryKeys.workoutRoutesPref(), data);
+    },
+  });
+
+  return (
+    <SettingsCard data-testid="workout-routes-card">
+      <SettingsCardHeader
+        anchor="workout-routes"
+        icon={MapPinned}
+        title={t("settings.privacy.workoutRoutes.title")}
+        description={t("settings.privacy.workoutRoutes.description")}
+        status={
+          <Switch
+            checked={pref.data?.storeWorkoutRoutes ?? false}
+            disabled={pref.isLoading || pref.isError || update.isPending}
+            onCheckedChange={(checked) =>
+              update.mutate(checked, {
+                onSuccess: () =>
+                  toastWrittenOutcome("success", t("settings.saved")),
+                onError: (failure) =>
+                  showErrorToast(t("settings.savingError"), {
+                    cause: failure,
+                  }),
+              })
+            }
+            aria-label={t("settings.privacy.workoutRoutes.title")}
+          />
+        }
+      />
+      {pref.isError ? (
+        <QueryErrorRow
+          inset
+          error={pref.error}
+          onRetry={() => void pref.refetch()}
+          message={t("settings.privacy.workoutRoutes.loadError")}
+        />
+      ) : (
+        <p className="text-sm">{t("settings.privacy.workoutRoutes.detail")}</p>
+      )}
+    </SettingsCard>
+  );
+}
diff --git a/src/lib/__tests__/measurement-type-enum-coverage.test.ts b/src/lib/__tests__/measurement-type-enum-coverage.test.ts
index 99a5dc9a2..5ef5738b7 100644
--- a/src/lib/__tests__/measurement-type-enum-coverage.test.ts
+++ b/src/lib/__tests__/measurement-type-enum-coverage.test.ts
@@ -112,10 +112,18 @@ const EXPECTED_TYPES = [
   // both server-derived from a completed assessment, higher = better) ──
   "WHO5_SCORE",
   "SCI_SCORE",
+  // ── v1.44 — Apple Health activity rings, mindfulness, State of Mind and
+  // AFib burden ──
+  "EXERCISE_MINUTES",
+  "STAND_MINUTES",
+  "STAND_HOURS",
+  "MINDFUL_MINUTES",
+  "STATE_OF_MIND_VALENCE",
+  "AFIB_BURDEN",
 ] as const;
 
 describe("measurementTypeEnum coverage", () => {
-  it("exposes the 75 canonical measurement types", () => {
+  it("exposes the 83 canonical measurement types", () => {
     expect([...measurementTypeEnum.options].sort()).toEqual(
       [...EXPECTED_TYPES].sort(),
     );
diff --git a/src/lib/apple-health/__tests__/route-import.test.ts b/src/lib/apple-health/__tests__/route-import.test.ts
new file mode 100644
index 000000000..e24f33fe6
--- /dev/null
+++ b/src/lib/apple-health/__tests__/route-import.test.ts
@@ -0,0 +1,253 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+
+import { strToU8, zipSync } from "fflate";
+
+vi.mock("@/lib/workouts/route-geometry-cipher", () => ({
+  encryptRouteGeometry: (geometry: unknown) =>
+    Buffer.from(JSON.stringify(geometry)),
+}));
+
+import {
+  importAppleHealthWorkoutRoutes,
+  parseGpxTrack,
+  thinIndices,
+  trackToRoute,
+} from "../route-import";
+import { routeMemberNameFromReference } from "../archive-stream";
+import { MAX_ROUTE_POINTS } from "@/lib/validations/workout";
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const dir of dirs.splice(0))
+    rmSync(dir, { recursive: true, force: true });
+});
+
+function archive(files: Record<string, string>): string {
+  const dir = mkdtempSync(join(tmpdir(), "healthlog-route-import-"));
+  dirs.push(dir);
+  const path = join(dir, "export.zip");
+  writeFileSync(
+    path,
+    zipSync(
+      Object.fromEntries(
+        Object.entries(files).map(([name, body]) => [name, strToU8(body)]),
+      ),
+    ),
+  );
+  return path;
+}
+
+function gpx(points: Array<[number, number, number?, string?]>): string {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<gpx version="1.1" creator="Apple Health Export" xmlns="http://www.topografix.com/GPX/1/1">
+<trk><name>Route</name><trkseg>
+${points
+  .map(
+    ([lat, lon, ele, time]) =>
+      `<trkpt lon="${lon}" lat="${lat}">${ele === undefined ? "" : `<ele>${ele}</ele>`}${time ? `<time>${time}</time>` : ""}</trkpt>`,
+  )
+  .join("\n")}
+</trkseg></trk></gpx>`;
+}
+
+function fakePrisma(
+  workout: {
+    id: string;
+    elevationM: number | null;
+    route: { id: string } | null;
+  } | null,
+) {
+  return {
+    workout: {
+      findUnique: vi.fn(async () => workout),
+      update: vi.fn(async () => ({})),
+    },
+    workoutRoute: { createMany: vi.fn(async () => ({ count: 1 })) },
+  };
+}
+
+describe("routeMemberNameFromReference", () => {
+  it("maps Apple's reference path onto the archive member", () => {
+    expect(routeMemberNameFromReference("/workout-routes/route_1.gpx")).toBe(
+      "apple_health_export/workout-routes/route_1.gpx",
+    );
+  });
+
+  it("refuses anything that is not a direct route file", () => {
+    expect(
+      routeMemberNameFromReference("/workout-routes/../export.xml"),
+    ).toBeNull();
+    expect(
+      routeMemberNameFromReference("/electrocardiograms/a.csv"),
+    ).toBeNull();
+    expect(routeMemberNameFromReference("/workout-routes/a/b.gpx")).toBeNull();
+  });
+});
+
+describe("parseGpxTrack + trackToRoute", () => {
+  it("keeps altitude and time when every point carries them", async () => {
+    const track = await parseGpxTrack(
+      Readable.from([
+        gpx([
+          [50.1, 8.1, 100, "2026-05-14T06:00:00Z"],
+          [50.2, 8.2, 130, "2026-05-14T06:00:05Z"],
+        ]),
+      ]),
+    );
+    const route = trackToRoute(track);
+    expect(route?.geometry.coordinates).toEqual([
+      [8.1, 50.1, 100],
+      [8.2, 50.2, 130],
+    ]);
+    expect(route?.sampleTimestamps).toEqual([
+      { t: "2026-05-14T06:00:00.000Z" },
+      { t: "2026-05-14T06:00:05.000Z" },
+    ]);
+  });
+
+  it("drops altitude and times rather than half-filling them", async () => {
+    const route = trackToRoute(
+      await parseGpxTrack(
+        Readable.from([
+          gpx([
+            [50.1, 8.1, 100, "2026-05-14T06:00:00Z"],
+            [50.2, 8.2],
+          ]),
+        ]),
+      ),
+    );
+    expect(route?.geometry.coordinates).toEqual([
+      [8.1, 50.1],
+      [8.2, 50.2],
+    ]);
+    expect(route?.sampleTimestamps).toBeNull();
+  });
+
+  it("skips out-of-range points and refuses a track shorter than two", async () => {
+    const track = await parseGpxTrack(
+      Readable.from([
+        gpx([
+          [95, 8.1],
+          [50.2, 8.2],
+        ]),
+      ]),
+    );
+    expect(track.lat).toEqual([50.2]);
+    expect(trackToRoute(track)).toBeNull();
+  });
+
+  it("rejects malformed XML", async () => {
+    await expect(
+      parseGpxTrack(Readable.from(["<gpx><trk><trkpt lat="])),
+    ).rejects.toThrow();
+  });
+
+  it("thins evenly to the point cap and keeps both ends", () => {
+    const idx = thinIndices(MAX_ROUTE_POINTS * 3 + 7, MAX_ROUTE_POINTS);
+    expect(idx).toHaveLength(MAX_ROUTE_POINTS);
+    expect(idx[0]).toBe(0);
+    expect(idx.at(-1)).toBe(MAX_ROUTE_POINTS * 3 + 6);
+    expect(thinIndices(5, MAX_ROUTE_POINTS)).toEqual([0, 1, 2, 3, 4]);
+  });
+});
+
+describe("importAppleHealthWorkoutRoutes", () => {
+  const files = {
+    "apple_health_export/export.xml": "<HealthData/>",
+    "apple_health_export/workout-routes/route_1.gpx": gpx([
+      [50.1, 8.1, 100],
+      [50.2, 8.2, 140],
+      [50.3, 8.3, 120],
+    ]),
+    "apple_health_export/workout-routes/route_2.gpx": gpx([[50.1, 8.1]]),
+  };
+
+  it("attaches a referenced track sealed and fills the climb", async () => {
+    const prisma = fakePrisma({ id: "w1", elevationM: null, route: null });
+    const counts = await importAppleHealthWorkoutRoutes({
+      archivePath: archive(files),
+      userId: "u1",
+      references: [
+        { externalId: "ext-1", path: "/workout-routes/route_1.gpx" },
+      ],
+      prisma: prisma as never,
+    });
+    expect(counts).toEqual({
+      discovered: 1,
+      attached: 1,
+      skipped: 0,
+      failed: 0,
+    });
+    const data = (
+      prisma.workoutRoute.createMany.mock.calls[0] as unknown as [
+        { data: Array<{ workoutId: string; geometryEncrypted: Buffer }> },
+      ]
+    )[0].data[0];
+    expect(data.workoutId).toBe("w1");
+    expect(JSON.parse(data.geometryEncrypted.toString())).toMatchObject({
+      type: "LineString",
+    });
+    expect(prisma.workout.update).toHaveBeenCalledWith({
+      where: { id: "w1" },
+      data: { elevationM: 40 },
+    });
+  });
+
+  it("reads only referenced members, and leaves a stored track alone", async () => {
+    const prisma = fakePrisma({ id: "w1", elevationM: 12, route: { id: "r" } });
+    const counts = await importAppleHealthWorkoutRoutes({
+      archivePath: archive(files),
+      userId: "u1",
+      references: [
+        { externalId: "ext-1", path: "/workout-routes/route_1.gpx" },
+      ],
+      prisma: prisma as never,
+    });
+    expect(counts).toEqual({
+      discovered: 1,
+      attached: 0,
+      skipped: 1,
+      failed: 0,
+    });
+    expect(prisma.workoutRoute.createMany).not.toHaveBeenCalled();
+  });
+
+  it("counts a too-short track as failed", async () => {
+    const prisma = fakePrisma({ id: "w2", elevationM: null, route: null });
+    const counts = await importAppleHealthWorkoutRoutes({
+      archivePath: archive(files),
+      userId: "u1",
+      references: [
+        { externalId: "ext-2", path: "/workout-routes/route_2.gpx" },
+      ],
+      prisma: prisma as never,
+    });
+    expect(counts.failed).toBe(1);
+    expect(prisma.workoutRoute.createMany).not.toHaveBeenCalled();
+  });
+
+  it("fails soft on a member over the byte cap", async () => {
+    const prisma = fakePrisma({ id: "w1", elevationM: null, route: null });
+    const counts = await importAppleHealthWorkoutRoutes({
+      archivePath: archive(files),
+      userId: "u1",
+      references: [
+        { externalId: "ext-1", path: "/workout-routes/route_1.gpx" },
+      ],
+      prisma: prisma as never,
+      limits: {
+        maxMembers: 100,
+        maxRouteMembers: 10,
+        maxMemberBytes: 64,
+        maxTotalRouteBytes: 1024,
+        maxCompressionRatio: 200,
+      },
+    });
+    expect(counts.attached).toBe(0);
+    expect(counts.failed).toBe(1);
+  });
+});
diff --git a/src/lib/apple-health/archive-stream.ts b/src/lib/apple-health/archive-stream.ts
index b5718a78a..7af968af6 100644
--- a/src/lib/apple-health/archive-stream.ts
+++ b/src/lib/apple-health/archive-stream.ts
@@ -1,5 +1,6 @@
 /**
- * Bounded ZIP reader for Apple Health ECG CSV members.
+ * Bounded ZIP reader for Apple Health's auxiliary members: the ECG CSVs and
+ * the workout-route GPX files.
  *
  * ZIP entry names are treated as untrusted identifiers only: no archive member
  * is ever materialised on disk. Central-directory metadata is checked before
@@ -37,6 +38,18 @@ const CENTRAL_SIGNATURE = 0x02014b50;
 const LOCAL_SIGNATURE = 0x04034b50;
 const MAX_EOCD_SEARCH = 65_535 + 22;
 const ECG_PREFIX = "apple_health_export/electrocardiograms/";
+const ROUTE_PREFIX = "apple_health_export/workout-routes/";
+
+/**
+ * One family of auxiliary members: which names belong to it, the label its
+ * errors carry, and its own count and total-byte ceilings.
+ */
+interface MemberKind {
+  label: string;
+  matches: (name: string) => boolean;
+  maxMembers: number;
+  maxTotalBytes: number;
+}
 
 function archiveError(message: string): Error {
   return new Error(`Unsafe Apple Health archive: ${message}`);
@@ -95,19 +108,41 @@ function isUnsafeName(name: string): boolean {
   return segments.some((segment) => segment === "." || segment === "..");
 }
 
-function isEcgCsv(name: string): boolean {
+function isDirectChild(name: string, prefix: string, extension: string) {
   return (
-    name.startsWith(ECG_PREFIX) &&
-    name.length > ECG_PREFIX.length &&
-    name.toLowerCase().endsWith(".csv") &&
-    !name.slice(ECG_PREFIX.length).includes("/")
+    name.startsWith(prefix) &&
+    name.length > prefix.length &&
+    name.toLowerCase().endsWith(extension) &&
+    !name.slice(prefix.length).includes("/")
   );
 }
 
+function isEcgCsv(name: string): boolean {
+  return isDirectChild(name, ECG_PREFIX, ".csv");
+}
+
+/** A workout route as the archive names it: `workout-routes/<file>.gpx`. */
+export function isWorkoutRouteGpx(name: string): boolean {
+  return isDirectChild(name, ROUTE_PREFIX, ".gpx");
+}
+
+/**
+ * The archive member a `<FileReference path="…">` inside a `<Workout>`
+ * points at. Apple writes the path from the export root
+ * (`/workout-routes/route_….gpx`); the member carries the export folder in
+ * front. Null for anything that is not a direct route file.
+ */
+export function routeMemberNameFromReference(path: string): string | null {
+  const trimmed = path.startsWith("/") ? path.slice(1) : path;
+  const name = `apple_health_export/${trimmed}`;
+  return isWorkoutRouteGpx(name) ? name : null;
+}
+
 async function readCentralDirectory(
   handle: FileHandle,
   fileSize: number,
   limits: AppleHealthArchiveLimits,
+  kind: MemberKind,
 ): Promise<ZipEntry[]> {
   if (fileSize < 22) throw archiveError("missing ZIP directory");
 
@@ -148,7 +183,7 @@ async function readCentralDirectory(
   const entries: ZipEntry[] = [];
   const names = new Set<string>();
   let cursor = centralOffset;
-  let ecgCount = 0;
+  let kindCount = 0;
 
   for (let index = 0; index < totalEntries; index += 1) {
     const header = await readExactly(handle, 46, cursor);
@@ -177,23 +212,23 @@ async function readCentralDirectory(
     if (names.has(name)) throw archiveError("duplicate member name");
     names.add(name);
 
-    if (isEcgCsv(name)) {
-      ecgCount += 1;
-      if (ecgCount > limits.maxEcgMembers) {
-        throw archiveError("ECG member count limit exceeded");
+    if (kind.matches(name)) {
+      kindCount += 1;
+      if (kindCount > kind.maxMembers) {
+        throw archiveError(`${kind.label} member count limit exceeded`);
       }
       if ((flags & 0x1) !== 0) {
-        throw archiveError("encrypted ECG member is unsupported");
+        throw archiveError(`encrypted ${kind.label} member is unsupported`);
       }
       if (method !== 0 && method !== 8) {
-        throw archiveError("unsupported ECG compression method");
+        throw archiveError(`unsupported ${kind.label} compression method`);
       }
       if (uncompressedSize > limits.maxMemberBytes) {
-        throw archiveError("ECG member byte limit exceeded");
+        throw archiveError(`${kind.label} member byte limit exceeded`);
       }
       const ratio = uncompressedSize / Math.max(1, compressedSize);
       if (ratio > limits.maxCompressionRatio) {
-        throw archiveError("ECG compression ratio limit exceeded");
+        throw archiveError(`${kind.label} compression ratio limit exceeded`);
       }
     }
 
@@ -218,6 +253,7 @@ async function decompressEntry(
   entry: ZipEntry,
   fileSize: number,
   limits: AppleHealthArchiveLimits,
+  kind: MemberKind,
   total: { bytes: number },
 ): Promise<Buffer[]> {
   const local = await readExactly(handle, 30, entry.localHeaderOffset);
@@ -260,16 +296,16 @@ async function decompressEntry(
       const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
       memberBytes += chunk.byteLength;
       if (memberBytes > limits.maxMemberBytes) {
-        throw archiveError("actual ECG member byte limit exceeded");
+        throw archiveError(`actual ${kind.label} member byte limit exceeded`);
       }
-      if (total.bytes + memberBytes > limits.maxTotalEcgBytes) {
-        throw archiveError("total ECG byte limit exceeded");
+      if (total.bytes + memberBytes > kind.maxTotalBytes) {
+        throw archiveError(`total ${kind.label} byte limit exceeded`);
       }
       chunks.push(chunk);
     }
   } catch {
     for (const chunk of chunks) chunk.fill(0);
-    throw archiveError("ECG decompression or byte limit failure");
+    throw archiveError(`${kind.label} decompression or byte limit failure`);
   } finally {
     compressed.fill(0);
   }
@@ -279,31 +315,35 @@ async function decompressEntry(
 }
 
 /**
- * Yield only Apple Health's ECG CSV members as in-memory bounded streams.
- * The generator validates the complete central directory before yielding any
- * health data, preventing partial processing of a structurally unsafe archive.
+ * Yield the members of one kind as in-memory bounded streams, one at a time.
+ * The complete central directory is validated before any health data is
+ * yielded, so a structurally unsafe archive is never partly processed.
+ * `wanted` narrows further (a route the export's XML actually references).
  */
-export async function* streamAppleHealthEcgMembers(input: {
-  archivePath: string;
-  limits: AppleHealthArchiveLimits;
-}): AsyncGenerator<AppleHealthArchiveMember> {
-  assertPositiveLimits(input.limits);
-  const handle = await open(input.archivePath, "r");
+async function* streamMembers(
+  archivePath: string,
+  limits: AppleHealthArchiveLimits,
+  kind: MemberKind,
+  wanted: (name: string) => boolean = () => true,
+): AsyncGenerator<AppleHealthArchiveMember> {
+  assertPositiveLimits(limits);
+  const handle = await open(archivePath, "r");
   try {
     const stat = await handle.stat();
     const fileSize = Number(stat.size);
     if (!Number.isSafeInteger(fileSize)) {
       throw archiveError("archive is too large to address safely");
     }
-    const entries = await readCentralDirectory(handle, fileSize, input.limits);
+    const entries = await readCentralDirectory(handle, fileSize, limits, kind);
     const total = { bytes: 0 };
     for (const entry of entries) {
-      if (!isEcgCsv(entry.name)) continue;
+      if (!kind.matches(entry.name) || !wanted(entry.name)) continue;
       const chunks = await decompressEntry(
         handle,
         entry,
         fileSize,
-        input.limits,
+        limits,
+        kind,
         total,
       );
       yield { name: entry.name, stream: Readable.from(chunks) };
@@ -312,3 +352,54 @@ export async function* streamAppleHealthEcgMembers(input: {
     await handle.close();
   }
 }
+
+/** Yield only Apple Health's ECG CSV members as in-memory bounded streams. */
+export async function* streamAppleHealthEcgMembers(input: {
+  archivePath: string;
+  limits: AppleHealthArchiveLimits;
+}): AsyncGenerator<AppleHealthArchiveMember> {
+  yield* streamMembers(input.archivePath, input.limits, {
+    label: "ECG",
+    matches: isEcgCsv,
+    maxMembers: input.limits.maxEcgMembers,
+    maxTotalBytes: input.limits.maxTotalEcgBytes,
+  });
+}
+
+/** Ceilings for the route members; the shared ones keep their meaning. */
+export interface AppleHealthRouteArchiveLimits {
+  maxMembers: number;
+  maxRouteMembers: number;
+  maxMemberBytes: number;
+  maxTotalRouteBytes: number;
+  maxCompressionRatio: number;
+}
+
+/**
+ * Yield the workout-route GPX members `wanted` names, one bounded buffer at
+ * a time: the caller parses and drops each before the next is inflated.
+ */
+export async function* streamAppleHealthRouteMembers(input: {
+  archivePath: string;
+  limits: AppleHealthRouteArchiveLimits;
+  wanted: (name: string) => boolean;
+}): AsyncGenerator<AppleHealthArchiveMember> {
+  const { limits } = input;
+  yield* streamMembers(
+    input.archivePath,
+    {
+      maxMembers: limits.maxMembers,
+      maxEcgMembers: limits.maxRouteMembers,
+      maxMemberBytes: limits.maxMemberBytes,
+      maxTotalEcgBytes: limits.maxTotalRouteBytes,
+      maxCompressionRatio: limits.maxCompressionRatio,
+    },
+    {
+      label: "route",
+      matches: isWorkoutRouteGpx,
+      maxMembers: limits.maxRouteMembers,
+      maxTotalBytes: limits.maxTotalRouteBytes,
+    },
+    input.wanted,
+  );
+}
diff --git a/src/lib/apple-health/route-import.ts b/src/lib/apple-health/route-import.ts
new file mode 100644
index 000000000..c392d2dc0
--- /dev/null
+++ b/src/lib/apple-health/route-import.ts
@@ -0,0 +1,266 @@
+/**
+ * Workout GPS tracks from an Apple Health export, kept only on opt-in.
+ *
+ * `export.xml` names each workout's track as a `<FileReference>` to a GPX
+ * file under `workout-routes/`. The XML pass hands those references here
+ * (only when the account turned `storeWorkoutRoutes` on); this module then
+ * reads the referenced members one at a time, parses each GPX as a stream,
+ * thins it evenly to `MAX_ROUTE_POINTS`, and stores it sealed against the
+ * workout the XML pass wrote.
+ *
+ * Memory: one member is held at a time, inflated into a buffer the archive
+ * reader caps (`maxMemberBytes`), and its points are kept as flat number
+ * arrays until they are thinned. Nothing about the track goes into the job
+ * result, the logs or a wide event: only counts.
+ *
+ * A failure here never fails the import. The workouts and every measurement
+ * are already committed; a track that cannot be read is counted and skipped.
+ */
+import type { Readable } from "node:stream";
+
+import sax from "sax";
+
+import type { PrismaClient } from "@/generated/prisma/client";
+import {
+  routeMemberNameFromReference,
+  streamAppleHealthRouteMembers,
+  type AppleHealthRouteArchiveLimits,
+} from "@/lib/apple-health/archive-stream";
+import { MAX_ROUTE_POINTS } from "@/lib/validations/workout";
+import { encryptRouteGeometry } from "@/lib/workouts/route-geometry-cipher";
+import { routeClimbM } from "@/lib/workouts/route-climb";
+
+/** A workout the XML pass wrote, and the track file it referenced. */
+export interface WorkoutRouteReference {
+  /** The workout's `externalId` under `source = APPLE_HEALTH`. */
+  externalId: string;
+  /** The `<FileReference path>` as Apple wrote it. */
+  path: string;
+}
+
+export interface WorkoutRouteImportCounts {
+  /** Tracks the XML referenced that are present in the archive. */
+  discovered: number;
+  /** Tracks stored against their workout. */
+  attached: number;
+  /** Workout already had a track, or its row is gone. */
+  skipped: number;
+  /** Unreadable, too short, or over a limit. */
+  failed: number;
+}
+
+/** Per-archive ceilings for the route members. */
+export const APPLE_HEALTH_ROUTE_ARCHIVE_LIMITS: AppleHealthRouteArchiveLimits =
+  {
+    maxMembers: 100_000,
+    maxRouteMembers: 20_000,
+    // A three-hour ride at 1 Hz is a few MB of GPX; 32 MB covers a 24-hour
+    // ultra with room to spare and bounds the one buffer held at a time.
+    maxMemberBytes: 32 * 1024 * 1024,
+    maxTotalRouteBytes: 4 * 1024 * 1024 * 1024,
+    maxCompressionRatio: 200,
+  };
+
+/** The points of one track, flat: lon, lat, elevation (NaN when absent), time ms (NaN when absent). */
+interface ParsedTrack {
+  lon: number[];
+  lat: number[];
+  ele: number[];
+  time: number[];
+}
+
+/** Stream a GPX document into flat point arrays. Rejects malformed XML. */
+export async function parseGpxTrack(stream: Readable): Promise<ParsedTrack> {
+  const track: ParsedTrack = { lon: [], lat: [], ele: [], time: [] };
+  const parser = sax.parser(true, { trim: true });
+  let inPoint = false;
+  let field: "ele" | "time" | null = null;
+  let ele = Number.NaN;
+  let time = Number.NaN;
+  let lat = Number.NaN;
+  let lon = Number.NaN;
+  let failure: Error | null = null;
+
+  parser.onerror = (err) => {
+    failure = err instanceof Error ? err : new Error(String(err));
+  };
+  parser.onopentag = (node) => {
+    const name = node.name.toLowerCase();
+    if (name === "trkpt") {
+      const attrs = node.attributes as Record<string, string>;
+      lat = Number.parseFloat(attrs.lat ?? "");
+      lon = Number.parseFloat(attrs.lon ?? "");
+      ele = Number.NaN;
+      time = Number.NaN;
+      inPoint = true;
+    } else if (inPoint && (name === "ele" || name === "time")) {
+      field = name;
+    }
+  };
+  parser.ontext = (text) => {
+    if (!inPoint || field === null) return;
+    if (field === "ele") ele = Number.parseFloat(text);
+    else time = Date.parse(text);
+  };
+  parser.onclosetag = (tagName) => {
+    const name = tagName.toLowerCase();
+    if (name === "ele" || name === "time") field = null;
+    if (name !== "trkpt") return;
+    inPoint = false;
+    if (
+      !Number.isFinite(lat) ||
+      !Number.isFinite(lon) ||
+      lat < -90 ||
+      lat > 90 ||
+      lon < -180 ||
+      lon > 180
+    ) {
+      return;
+    }
+    track.lon.push(lon);
+    track.lat.push(lat);
+    track.ele.push(Number.isFinite(ele) ? ele : Number.NaN);
+    track.time.push(Number.isFinite(time) ? time : Number.NaN);
+  };
+
+  for await (const chunk of stream) {
+    parser.write(Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk);
+    if (failure) throw failure;
+  }
+  parser.close();
+  if (failure) throw failure;
+  return track;
+}
+
+/**
+ * Indices that thin `count` points evenly to at most `max`, always keeping
+ * the first and the last.
+ */
+export function thinIndices(count: number, max: number): number[] {
+  if (count <= max) return Array.from({ length: count }, (_, i) => i);
+  const out: number[] = [];
+  const step = (count - 1) / (max - 1);
+  for (let i = 0; i < max; i += 1) out.push(Math.round(i * step));
+  return out;
+}
+
+/**
+ * The stored shapes for a parsed track: a GeoJSON LineString (altitude only
+ * when every kept point has one) and, when every kept point is timed, the
+ * parallel sample list. Null for a track with fewer than two points.
+ */
+export function trackToRoute(track: ParsedTrack): {
+  geometry: { type: "LineString"; coordinates: number[][] };
+  sampleTimestamps: Array<{ t: string }> | null;
+} | null {
+  const indices = thinIndices(track.lon.length, MAX_ROUTE_POINTS);
+  if (indices.length < 2) return null;
+  const withEle = indices.every((i) => Number.isFinite(track.ele[i]));
+  const withTime = indices.every((i) => Number.isFinite(track.time[i]));
+  return {
+    geometry: {
+      type: "LineString",
+      coordinates: indices.map((i) =>
+        withEle
+          ? [track.lon[i], track.lat[i], track.ele[i]]
+          : [track.lon[i], track.lat[i]],
+      ),
+    },
+    sampleTimestamps: withTime
+      ? indices.map((i) => ({ t: new Date(track.time[i]).toISOString() }))
+      : null,
+  };
+}
+
+/**
+ * Store the referenced tracks. `references` comes from the XML pass; each
+ * names a workout the import wrote under `source = APPLE_HEALTH`.
+ */
+export async function importAppleHealthWorkoutRoutes(input: {
+  archivePath: string;
+  userId: string;
+  references: readonly WorkoutRouteReference[];
+  prisma: Pick<PrismaClient, "workout" | "workoutRoute">;
+  limits?: AppleHealthRouteArchiveLimits;
+}): Promise<WorkoutRouteImportCounts> {
+  const counts: WorkoutRouteImportCounts = {
+    discovered: 0,
+    attached: 0,
+    skipped: 0,
+    failed: 0,
+  };
+  const byMember = new Map<string, string>();
+  for (const ref of input.references) {
+    const member = routeMemberNameFromReference(ref.path);
+    if (member) byMember.set(member, ref.externalId);
+  }
+  if (byMember.size === 0) return counts;
+
+  try {
+    for await (const member of streamAppleHealthRouteMembers({
+      archivePath: input.archivePath,
+      limits: input.limits ?? APPLE_HEALTH_ROUTE_ARCHIVE_LIMITS,
+      wanted: (name) => byMember.has(name),
+    })) {
+      counts.discovered += 1;
+      const externalId = byMember.get(member.name);
+      if (!externalId) continue;
+      try {
+        const route = trackToRoute(await parseGpxTrack(member.stream));
+        if (!route) {
+          counts.failed += 1;
+          continue;
+        }
+        const workout = await input.prisma.workout.findUnique({
+          where: {
+            userId_source_externalId: {
+              userId: input.userId,
+              source: "APPLE_HEALTH",
+              externalId,
+            },
+          },
+          select: {
+            id: true,
+            elevationM: true,
+            route: { select: { id: true } },
+          },
+        });
+        if (!workout || workout.route) {
+          counts.skipped += 1;
+          continue;
+        }
+        await input.prisma.workoutRoute.createMany({
+          data: [
+            {
+              workoutId: workout.id,
+              geometryEncrypted: encryptRouteGeometry(route.geometry),
+              sampleTimestamps: route.sampleTimestamps ?? undefined,
+            },
+          ],
+          skipDuplicates: true,
+        });
+        // The climb lives on the workout row, so no reader opens the track
+        // for it (the same write-time derivation as the batch route).
+        if (workout.elevationM === null) {
+          const climb = routeClimbM(route.geometry);
+          if (climb !== null) {
+            await input.prisma.workout.update({
+              where: { id: workout.id },
+              data: { elevationM: climb },
+            });
+          }
+        }
+        counts.attached += 1;
+      } catch {
+        counts.failed += 1;
+      }
+    }
+  } catch {
+    // The archive itself is unreadable for this pass (a ZIP64 export, a
+    // limit hit in the directory). Every referenced track not yet handled
+    // counts as failed; the import stays done.
+    const handled = counts.attached + counts.skipped + counts.failed;
+    counts.failed += Math.max(0, byMember.size - handled);
+  }
+  return counts;
+}
diff --git a/src/lib/data-wipe/wipe-plan.ts b/src/lib/data-wipe/wipe-plan.ts
index 93347dfcc..da5cdb6ac 100644
--- a/src/lib/data-wipe/wipe-plan.ts
+++ b/src/lib/data-wipe/wipe-plan.ts
@@ -427,6 +427,7 @@ export const USER_RESET = {
   coachLastSeenAt: null,
   documentsAutoAiRead: false,
   labsLocalOcrEnabled: false,
+  storeWorkoutRoutes: false,
   codexAccessTokenEncrypted: null,
   codexRefreshTokenEncrypted: null,
   codexTokenExpiresAt: null,
diff --git a/src/lib/export/account-settings-backup.ts b/src/lib/export/account-settings-backup.ts
index 2585a2c11..1ac7b794b 100644
--- a/src/lib/export/account-settings-backup.ts
+++ b/src/lib/export/account-settings-backup.ts
@@ -527,6 +527,7 @@ const ACCOUNT_SETTING_CODECS: Readonly<
   coachPrefsJson: json("coachPrefsJson"),
   documentsAutoAiRead: plain("documentsAutoAiRead"),
   labsLocalOcrEnabled: plain("labsLocalOcrEnabled"),
+  storeWorkoutRoutes: plain("storeWorkoutRoutes"),
   onboardingCompletedAt: instant("onboardingCompletedAt"),
   onboardingTourCompleted: plain("onboardingTourCompleted"),
   onboardingTourProgressJson: json("onboardingTourProgressJson"),
diff --git a/src/lib/export/backup-plan.ts b/src/lib/export/backup-plan.ts
index 1d517711b..c86898c1a 100644
--- a/src/lib/export/backup-plan.ts
+++ b/src/lib/export/backup-plan.ts
@@ -1038,6 +1038,7 @@ export const USER_COLUMN_BACKUP_CLASS = {
   coachPrefsJson: "SETTING",
   documentsAutoAiRead: "SETTING",
   labsLocalOcrEnabled: "SETTING",
+  storeWorkoutRoutes: "SETTING",
   // Where the person is in the app's introductions. Without these a restored
   // account is sent through setup and the tour again, and asked to accept the
   // disclaimer it already accepted (a newer disclaimer still asks, because the
diff --git a/src/lib/insights/chart-tokens.ts b/src/lib/insights/chart-tokens.ts
index 56c0c470c..94df12acc 100644
--- a/src/lib/insights/chart-tokens.ts
+++ b/src/lib/insights/chart-tokens.ts
@@ -137,6 +137,14 @@ export const ALLOWED_CHART_TOKENS = [
   // continuous-series contract, higher = better.
   "metric:WHO5_SCORE",
   "metric:SCI_SCORE",
+  // v1.44 — Apple Health activity rings, mindfulness, State of Mind and
+  // AFib burden. Charted through the generic series renderer.
+  "metric:EXERCISE_MINUTES",
+  "metric:STAND_MINUTES",
+  "metric:STAND_HOURS",
+  "metric:MINDFUL_MINUTES",
+  "metric:STATE_OF_MIND_VALENCE",
+  "metric:AFIB_BURDEN",
   "metric:GRIP_STRENGTH",
   "metric:PAIN_NRS",
   "metric:WAIST_CIRCUMFERENCE",
diff --git a/src/lib/jobs/apple-health-import-worker.ts b/src/lib/jobs/apple-health-import-worker.ts
index f90e09300..1023cc0f8 100644
--- a/src/lib/jobs/apple-health-import-worker.ts
+++ b/src/lib/jobs/apple-health-import-worker.ts
@@ -34,6 +34,11 @@ import { streamAppleHealthEcgMembers } from "@/lib/apple-health/archive-stream";
 import { parseAppleHealthEcgCsv } from "@/lib/apple-health/ecg-csv";
 import { importAppleHealthEcg } from "@/lib/apple-health/ecg-import";
 import { extractExportXml } from "@/lib/import/unzip-export-xml";
+import { annotate } from "@/lib/logging/context";
+import {
+  importAppleHealthWorkoutRoutes,
+  type WorkoutRouteReference,
+} from "@/lib/apple-health/route-import";
 import { getGlobalBoss } from "@/lib/jobs/boss-instance";
 import { invalidateStatusInsightsForTypes } from "@/lib/insights/status-invalidation";
 import { trackBackgroundTask } from "@/lib/logging/background-tasks";
@@ -428,8 +433,11 @@ export async function handleAppleHealthImport(
     // user has no preference set.
     const userRow = await prisma.user.findUnique({
       where: { id: userId },
-      select: { timezone: true },
+      select: { timezone: true, storeWorkoutRoutes: true },
     });
+    // GPS tracks are read from the archive only when the person keeps them.
+    const keepRoutes = userRow?.storeWorkoutRoutes === true;
+    const routeReferences: WorkoutRouteReference[] = [];
     const userTimezone =
       userRow?.timezone && userRow.timezone.length > 0
         ? userRow.timezone
@@ -471,6 +479,9 @@ export async function handleAppleHealthImport(
         userId,
         userTimezone,
         prisma,
+        ...(keepRoutes
+          ? { onWorkoutRoute: (ref) => void routeReferences.push(ref) }
+          : {}),
         onProgress: async (snapshot) => {
           // The phase label here is what the polling endpoint surfaces;
           // map "parsing" / "upserting" through verbatim.
@@ -536,6 +547,31 @@ export async function handleAppleHealthImport(
       ecg.failed += Math.max(0, ecg.discovered - completed);
     }
 
+    // Workout GPS tracks, on opt-in only. Fail-soft like the ECGs: the
+    // workouts are committed, a track that cannot be read is only counted.
+    // Read one member at a time from the archive; nothing about a track
+    // reaches the result but the count.
+    if (routeReferences.length > 0) {
+      const routes = await importAppleHealthWorkoutRoutes({
+        archivePath: uploadPath,
+        userId,
+        references: routeReferences,
+        prisma,
+      });
+      result.workouts.routesAttached = routes.attached;
+      annotate({
+        action: { name: "apple_health.import.workout_routes" },
+        meta: {
+          referenced: routeReferences.length,
+          discovered: routes.discovered,
+          attached: routes.attached,
+          skipped: routes.skipped,
+          failed: routes.failed,
+        },
+      });
+      routeReferences.length = 0;
+    }
+
     // Done. Persist the terminal envelope.
     await prisma.importJob.update({
       where: { id: importJobId },
diff --git a/src/lib/jobs/workout-insight-generate.ts b/src/lib/jobs/workout-insight-generate.ts
index 839d38eef..699a68aa7 100644
--- a/src/lib/jobs/workout-insight-generate.ts
+++ b/src/lib/jobs/workout-insight-generate.ts
@@ -66,7 +66,6 @@ import {
   meetsDurationFloor,
   workoutInsightInputHash,
 } from "@/lib/workouts/insight-gates";
-import { readRouteGeometry } from "@/lib/workouts/route-geometry-cipher";
 import { getAgeFromDateOfBirth } from "@/lib/analytics/pulse-targets";
 import {
   computeZones,
@@ -272,7 +271,6 @@ export async function runWorkoutInsightGenerate(
       minHeartRate: true,
       elevationM: true,
       metadata: true,
-      route: { select: { geometry: true, geometryEncrypted: true } },
       samples: { select: { samples: true } },
     },
   });
@@ -397,9 +395,6 @@ export async function runWorkoutInsightGenerate(
       tz,
       hrSeries,
       zones,
-      // Opened in memory only to derive metres climbed; the track itself
-      // never reaches the prompt.
-      routeGeometry: row.route ? readRouteGeometry(row.route) : null,
       history,
     });
     const inputHash = workoutInsightInputHash(
diff --git a/src/lib/measurements/__tests__/apple-health-mapping.test.ts b/src/lib/measurements/__tests__/apple-health-mapping.test.ts
index fbdab574f..86afc5d32 100644
--- a/src/lib/measurements/__tests__/apple-health-mapping.test.ts
+++ b/src/lib/measurements/__tests__/apple-health-mapping.test.ts
@@ -140,6 +140,12 @@ describe("APPLE_HEALTH_TYPE_MAP", () => {
         "HKCategoryTypeIdentifierLowHeartRateEvent",
         "HKCategoryTypeIdentifierAppleWalkingSteadinessEvent",
         "HKCategoryTypeIdentifierSleepApneaEvent",
+        // v1.44 — mindfulness and the State of Mind are mental-health
+        // self-care and self-report; AFib burden is the AFib History
+        // feature the person enabled on the watch.
+        "HKCategoryTypeIdentifierMindfulSession",
+        "HKDataTypeIdentifierStateOfMind",
+        "HKQuantityTypeIdentifierAtrialFibrillationBurden",
       ].sort(),
     );
     // Audio exposure + time-in-daylight are environment / lifestyle
@@ -209,8 +215,8 @@ describe("HK_QUANTITY_TYPE_DEFERRED", () => {
   // skipped-but-known rather than unknown-and-dropped.
   it("covers the iOS-17 + iOS-18 long-tail identifiers", () => {
     const expectedLongTail = [
-      // Cardiovascular / clinical
-      "HKQuantityTypeIdentifierAtrialFibrillationBurden",
+      // Cardiovascular / clinical (AFib burden moved into the mapped set in
+      // v1.44 as AFIB_BURDEN).
       "HKQuantityTypeIdentifierPeripheralPerfusionIndex",
       // Mobility — `AppleWalkingSteadiness` moved into the mapped set in
       // v1.4.30. In v1.10.0 both remaining identifiers moved in too:
@@ -772,11 +778,85 @@ describe("dailyStatsExternalId (v1.4.30 — R-A Option A handoff lock)", () => {
         "HKQuantityTypeIdentifierTimeInDaylight",
         // v1.10.0 — hard-fall detections accumulate across the day.
         "HKQuantityTypeIdentifierNumberOfTimesFallen",
+        // v1.44 — the exercise and stand rings and mindful minutes.
+        "HKQuantityTypeIdentifierAppleExerciseTime",
+        "HKQuantityTypeIdentifierAppleStandTime",
+        "HKCategoryTypeIdentifierAppleStandHour",
+        "HKCategoryTypeIdentifierMindfulSession",
       ].sort(),
     );
   });
 });
 
+describe("v1.44 — activity rings, mindfulness, State of Mind, AFib burden", () => {
+  const sample = (hkIdentifier: string, value: number, unit: string) =>
+    mapAppleHealthEntry({
+      hkIdentifier,
+      value,
+      unit,
+      startDate: "2026-10-20T08:00:00.000Z",
+      endDate: "2026-10-20T08:30:00.000Z",
+    });
+
+  it("maps every identifier and removes it from the deferred set", () => {
+    const expected: Record<string, MeasurementType> = {
+      HKQuantityTypeIdentifierAppleExerciseTime: "EXERCISE_MINUTES",
+      HKQuantityTypeIdentifierAppleStandTime: "STAND_MINUTES",
+      HKCategoryTypeIdentifierAppleStandHour: "STAND_HOURS",
+      HKCategoryTypeIdentifierMindfulSession: "MINDFUL_MINUTES",
+      HKDataTypeIdentifierStateOfMind: "STATE_OF_MIND_VALENCE",
+      HKQuantityTypeIdentifierAtrialFibrillationBurden: "AFIB_BURDEN",
+    };
+    for (const [hk, type] of Object.entries(expected)) {
+      expect(APPLE_HEALTH_TYPE_MAP[hk]?.measurementType).toBe(type);
+      expect(HK_QUANTITY_TYPE_DEFERRED.has(hk)).toBe(false);
+      expect(hkIdentifierForType(type)).toBe(hk);
+    }
+  });
+
+  it("passes the minute and hour values through", () => {
+    expect(
+      sample("HKQuantityTypeIdentifierAppleExerciseTime", 32, "min"),
+    ).toMatchObject({ type: "EXERCISE_MINUTES", value: 32, unit: "minutes" });
+    expect(
+      sample("HKCategoryTypeIdentifierAppleStandHour", 1, "count"),
+    ).toMatchObject({ type: "STAND_HOURS", value: 1, unit: "hours" });
+    expect(
+      sample("HKCategoryTypeIdentifierMindfulSession", 10, "min"),
+    ).toMatchObject({ type: "MINDFUL_MINUTES", value: 10, unit: "minutes" });
+  });
+
+  it("stores the State of Mind valence as is", () => {
+    expect(
+      sample("HKDataTypeIdentifierStateOfMind", -0.4, "valence"),
+    ).toMatchObject({ type: "STATE_OF_MIND_VALENCE", value: -0.4 });
+  });
+
+  it("scales AFib burden strictly, so a small burden stays small", () => {
+    // 0.5 % arrives as the fraction 0.005. A client that sends 2 for 2 %
+    // is not guessed at: it lands at 200 and the range guard refuses it.
+    expect(
+      sample("HKQuantityTypeIdentifierAtrialFibrillationBurden", 0.005, "%")
+        ?.value,
+    ).toBeCloseTo(0.5, 10);
+    expect(
+      sample("HKQuantityTypeIdentifierAtrialFibrillationBurden", 2, "%")?.value,
+    ).toBe(200);
+    expect(validateMeasurementRange("AFIB_BURDEN", 200)).not.toBeNull();
+    expect(validateMeasurementRange("AFIB_BURDEN", 0.5)).toBeNull();
+  });
+
+  it("bounds every new type", () => {
+    expect(
+      validateMeasurementRange("STATE_OF_MIND_VALENCE", 1.5),
+    ).not.toBeNull();
+    expect(validateMeasurementRange("STATE_OF_MIND_VALENCE", -1)).toBeNull();
+    expect(validateMeasurementRange("STAND_HOURS", 25)).not.toBeNull();
+    expect(validateMeasurementRange("EXERCISE_MINUTES", 1441)).not.toBeNull();
+    expect(validateMeasurementRange("MINDFUL_MINUTES", 20)).toBeNull();
+  });
+});
+
 describe("HIGH_FREQUENCY_MEAN_TYPES (v1.7.0)", () => {
   it("is strictly disjoint from CUMULATIVE_HK_TYPES", () => {
     for (const type of HIGH_FREQUENCY_MEAN_TYPES) {
diff --git a/src/lib/measurements/__tests__/import-apple-health-export.test.ts b/src/lib/measurements/__tests__/import-apple-health-export.test.ts
index 1fc88cdc7..5c994f5f2 100644
--- a/src/lib/measurements/__tests__/import-apple-health-export.test.ts
+++ b/src/lib/measurements/__tests__/import-apple-health-export.test.ts
@@ -637,9 +637,18 @@ describe("hashSampleKey", () => {
     expect(a).not.toBe(b);
   });
 });
-const cumulativeMappings = Object.values(APPLE_HEALTH_TYPE_MAP).filter(
+const allCumulativeMappings = Object.values(APPLE_HEALTH_TYPE_MAP).filter(
   (mapping) => CUMULATIVE_HK_TYPES.has(mapping.measurementType),
 );
+/**
+ * The cumulative quantities, whose `<Record>` carries its reading in
+ * `value`. The two cumulative category types (stand hours, mindful
+ * sessions) read theirs from a symbolic value or the dates and have their
+ * own cases below.
+ */
+const cumulativeMappings = allCumulativeMappings.filter((mapping) =>
+  mapping.hkIdentifier.startsWith("HKQuantityTypeIdentifier"),
+);
 
 function cumulativeExportXml(
   hkIdentifier: string,
@@ -678,11 +687,60 @@ async function importCumulativeFixture(xml: string) {
 }
 
 describe("streamParseExportXml — cumulative source-day estimates", () => {
-  it("covers exactly the six cumulative HealthKit measurement types", () => {
-    expect(CUMULATIVE_HK_TYPES.size).toBe(6);
+  it("covers exactly the ten cumulative HealthKit measurement types", () => {
+    expect(CUMULATIVE_HK_TYPES.size).toBe(10);
     expect(
-      new Set(cumulativeMappings.map((mapping) => mapping.measurementType)),
+      new Set(allCumulativeMappings.map((mapping) => mapping.measurementType)),
     ).toEqual(CUMULATIVE_HK_TYPES);
+    expect(allCumulativeMappings.length - cumulativeMappings.length).toBe(2);
+  });
+
+  it("counts stood hours and never stores an idle one", async () => {
+    const hour = (
+      h: number,
+      value: string,
+    ) => `  <Record type="HKCategoryTypeIdentifierAppleStandHour"
+          startDate="2026-05-14 ${String(h).padStart(2, "0")}:00:00 +0200"
+          endDate="2026-05-14 ${String(h).padStart(2, "0")}:59:59 +0200"
+          value="${value}" sourceName="Watch" sourceVersion="1.0"/>`;
+    const { prisma, result } =
+      await importCumulativeFixture(`<?xml version="1.0"?>
+<HealthData locale="en_US">
+${hour(8, "HKCategoryValueAppleStandHourStood")}
+${hour(9, "HKCategoryValueAppleStandHourIdle")}
+${hour(10, "HKCategoryValueAppleStandHourStood")}
+${hour(11, "HKCategoryValueAppleStandHourStood")}
+</HealthData>`);
+    expect(prisma._measurements).toHaveLength(1);
+    expect(prisma._measurements[0]).toMatchObject({
+      type: "STAND_HOURS",
+      value: 3,
+      unit: "hours",
+    });
+    expect(
+      result.deferred["HKCategoryTypeIdentifierAppleStandHour::idle"],
+    ).toBe(1);
+    expect(
+      result.unknown["HKCategoryTypeIdentifierAppleStandHour::unparseable"],
+    ).toBeUndefined();
+  });
+
+  it("takes mindful minutes from the session's own dates", async () => {
+    const { prisma } = await importCumulativeFixture(`<?xml version="1.0"?>
+<HealthData locale="en_US">
+  <Record type="HKCategoryTypeIdentifierMindfulSession"
+          startDate="2026-05-14 07:00:00 +0200" endDate="2026-05-14 07:10:00 +0200"
+          sourceName="Breathe" sourceVersion="1.0"/>
+  <Record type="HKCategoryTypeIdentifierMindfulSession"
+          startDate="2026-05-14 21:00:00 +0200" endDate="2026-05-14 21:15:00 +0200"
+          value="HKCategoryValueNotApplicable" sourceName="Breathe" sourceVersion="1.0"/>
+</HealthData>`);
+    expect(prisma._measurements).toHaveLength(1);
+    expect(prisma._measurements[0]).toMatchObject({
+      type: "MINDFUL_MINUTES",
+      value: 25,
+      unit: "minutes",
+    });
   });
 
   it("stores 8,526 rather than source-blind 15,608 for overlapping iPhone and Zepp steps", async () => {
diff --git a/src/lib/measurements/apple-health-mapping.ts b/src/lib/measurements/apple-health-mapping.ts
index 60824d9c8..6e8c9cf78 100644
--- a/src/lib/measurements/apple-health-mapping.ts
+++ b/src/lib/measurements/apple-health-mapping.ts
@@ -245,6 +245,12 @@ const UNIT_FIXED_AUDIO_SPL =
   "Sound-pressure level: Apple emits `dBASPL` only, and a decibel is logarithmic — a sibling unit would need its own formula, never a factor.";
 const UNIT_FIXED_COMPOSITE_VO2 =
   "Compound rate Apple emits verbatim as `mL/(kg*min)`; the Health app exposes no other spelling and the compound has no sibling unit to convert from.";
+const UNIT_FIXED_STAND_HOUR =
+  "Stand hours are a tally of hour samples: the importer maps `Stood` to 1 and drops `Idle`, and a daily row carries the count, so no record unit can rescale it.";
+const UNIT_FIXED_VALENCE =
+  "State of Mind valence is a dimensionless −1..1 self-report; HealthKit has no unit for it and nothing to convert from.";
+const UNIT_FIXED_AFIB_FRACTION =
+  "Apple writes the percent unit but the value rides as a 0..1 fraction, scaled ×100 in `convertToDbUnit`; branching on the record unit would double-scale it.";
 const UNIT_FIXED_SLEEP_CATEGORY =
   "Sleep samples carry a symbolic category value, not a quantity: the importer derives the duration in minutes from the sample's own dates, so the record's unit attribute (empty in Apple's archive) says nothing about the reading.";
 
@@ -479,6 +485,83 @@ export const APPLE_HEALTH_TYPE_MAP: Record<string, AppleHealthMapping> = {
     aggregation: "sum",
   },
 
+  // ── v1.44 — activity rings, mindfulness, State of Mind, AFib burden ──
+  // The exercise and stand rings. Apple ships both as minute quantities;
+  // cumulative, so the daily SUM is the ring value (same posture as
+  // daylight minutes).
+  HKQuantityTypeIdentifierAppleExerciseTime: {
+    hkIdentifier: "HKQuantityTypeIdentifierAppleExerciseTime",
+    measurementType: "EXERCISE_MINUTES",
+    hkUnit: "min",
+    dbUnit: "minutes",
+    convertToDbUnit: (v) => v,
+    aggregation: "sum",
+  },
+  HKQuantityTypeIdentifierAppleStandTime: {
+    hkIdentifier: "HKQuantityTypeIdentifierAppleStandTime",
+    measurementType: "STAND_MINUTES",
+    hkUnit: "min",
+    dbUnit: "minutes",
+    convertToDbUnit: (v) => v,
+    aggregation: "sum",
+  },
+  // The stand ring's hours. A category sample per hour, `stood` (0) or
+  // `idle` (1); the wire `value` is the number of stood hours the row
+  // stands for: 1 for one stood-hour sample, the day's count on a
+  // `stats:` daily row. The archive importer turns `Stood` into 1 and
+  // skips `Idle`, so an idle hour is never a row.
+  HKCategoryTypeIdentifierAppleStandHour: {
+    hkIdentifier: "HKCategoryTypeIdentifierAppleStandHour",
+    measurementType: "STAND_HOURS",
+    hkUnit: "count",
+    unitFixedReason: UNIT_FIXED_STAND_HOUR,
+    dbUnit: "hours",
+    convertToDbUnit: (v) => v,
+    aggregation: "sum",
+  },
+  // Mindful sessions. A category sample with no quantity: the value is the
+  // session length in minutes, from the sample's own dates (the archive
+  // importer derives it; the batch client sends it), the sleep contract.
+  HKCategoryTypeIdentifierMindfulSession: {
+    hkIdentifier: "HKCategoryTypeIdentifierMindfulSession",
+    measurementType: "MINDFUL_MINUTES",
+    hkUnit: "min",
+    dbUnit: "minutes",
+    convertToDbUnit: (v) => v,
+    aggregation: "sum",
+    isPrivacySensitive: true,
+  },
+  // State of Mind (iOS 18+). The valence of a logged emotion or daily mood,
+  // −1 (very unpleasant) to 1 (very pleasant), stored as is. Labels and
+  // associations stay on the device.
+  HKDataTypeIdentifierStateOfMind: {
+    hkIdentifier: "HKDataTypeIdentifierStateOfMind",
+    measurementType: "STATE_OF_MIND_VALENCE",
+    hkUnit: "valence",
+    unitFixedReason: UNIT_FIXED_VALENCE,
+    dbUnit: "valence",
+    convertToDbUnit: (v) => v,
+    aggregation: "mean",
+    isPrivacySensitive: true,
+  },
+  // AFib burden (iOS 16+, AFib History): the weekly share of time the watch
+  // estimated in AFib. Apple ships a 0..1 fraction and the wire is pinned to
+  // it: scaled strictly ×100. `percentFromFraction` repairs shipped clients
+  // that pre-scale SpO2 and body fat; no client pre-scales this type, and a
+  // small burden is exactly where a pre-scaled value cannot be told from a
+  // fraction, so a value above 1 is refused by the range guard (it lands
+  // above 100) rather than guessed at.
+  HKQuantityTypeIdentifierAtrialFibrillationBurden: {
+    hkIdentifier: "HKQuantityTypeIdentifierAtrialFibrillationBurden",
+    measurementType: "AFIB_BURDEN",
+    hkUnit: "%",
+    unitFixedReason: UNIT_FIXED_AFIB_FRACTION,
+    dbUnit: "%",
+    convertToDbUnit: (v) => v * 100,
+    aggregation: "latest",
+    isPrivacySensitive: true,
+  },
+
   // ── v1.4.30 R-F T1.4 + T1.5 Tier-1 additions ────────────────
   // Walking steadiness — iOS 15+ Mobility daily rollup. Apple ships
   // a 0..1 fraction; HealthLog stores 0..100 percent (same convention
@@ -818,6 +901,12 @@ export const CUMULATIVE_HK_TYPES: ReadonlySet<MeasurementType> =
     // daily total is the meaningful reduction (SUM), matching the other
     // cumulative HK counts.
     "FALL_COUNT",
+    // v1.44 — the exercise and stand rings and mindful minutes are day
+    // totals of partial-day increments, like daylight minutes.
+    "EXERCISE_MINUTES",
+    "STAND_MINUTES",
+    "STAND_HOURS",
+    "MINDFUL_MINUTES",
   ]);
 
 /**
@@ -1095,9 +1184,6 @@ export const HK_QUANTITY_TYPE_DEFERRED = new Set<string>([
   // v1.10.0 — `HeartRateRecoveryOneMinute` + `AppleSleepingWristTemperature`
   // moved into the mapping table (CARDIO_RECOVERY + WRIST_TEMPERATURE).
   "HKQuantityTypeIdentifierBasalEnergyBurned",
-  "HKQuantityTypeIdentifierAppleExerciseTime", // implied by Workout rows
-  "HKQuantityTypeIdentifierAppleStandTime", // implied by Workout rows
-  "HKCategoryTypeIdentifierAppleStandHour", // implied by Workout rows
   // Running / walking form — v1.5+
   // v1.5.5 — `WalkingStepLength` + `WalkingSpeed` moved into the
   // mapping table (raw SI on the wire — metres and m/s respectively).
@@ -1152,9 +1238,6 @@ export const HK_QUANTITY_TYPE_DEFERRED = new Set<string>([
   "HKQuantityTypeIdentifierDietarySugar",
   "HKQuantityTypeIdentifierDietaryFiber",
   "HKQuantityTypeIdentifierDietarySodium",
-  // Mental-state / mindfulness — v1.5 (route to existing mood model)
-  "HKCategoryTypeIdentifierMindfulSession",
-  "HKDataTypeIdentifierStateOfMind",
   // Pregnancy bleeding — stays deferred (pregnancy-mode is a later
   // release). v1.15.0 promoted the cycle-tracking reproductive types
   // (MenstrualFlow / IntermenstrualBleeding / CervicalMucusQuality /
@@ -1183,7 +1266,6 @@ export const HK_QUANTITY_TYPE_DEFERRED = new Set<string>([
   // Cardiovascular / clinical (iOS 16+) — no HealthLog counterpart yet;
   // clinical decision-support territory, defer behind a stricter user
   // opt-in than the existing Health-share prompt.
-  "HKQuantityTypeIdentifierAtrialFibrillationBurden",
   "HKQuantityTypeIdentifierPeripheralPerfusionIndex",
   // Mobility (iOS 15+) — `AppleWalkingSteadiness` moved into the
   // mapping table in v1.4.30 (R-F T1.5). In v1.10.0 both remaining
diff --git a/src/lib/measurements/categories.ts b/src/lib/measurements/categories.ts
index 924d06d82..0bff7c895 100644
--- a/src/lib/measurements/categories.ts
+++ b/src/lib/measurements/categories.ts
@@ -219,6 +219,17 @@ export const MEASUREMENT_CATEGORIES: ReadonlyMap<
   // Waist circumference + waist-to-height are anthropometric → body cluster.
   ["WAIST_CIRCUMFERENCE", "body"],
   ["WAIST_TO_HEIGHT", "body"],
+  // ── v1.44 — Apple Health activity rings, mindfulness, mood, AFib ──
+  // The exercise and stand rings, and mindful minutes (time given to a
+  // practice, the same day-total shape), sit with the activity cluster.
+  ["EXERCISE_MINUTES", "activity"],
+  ["STAND_MINUTES", "activity"],
+  ["STAND_HOURS", "activity"],
+  ["MINDFUL_MINUTES", "activity"],
+  // The State of Mind valence is a self-report, like the WHO-5 total.
+  ["STATE_OF_MIND_VALENCE", "scores"],
+  // AFib burden joins the rhythm notifications on the cardiovascular surface.
+  ["AFIB_BURDEN", "cardiovascular"],
 ]);
 
 /**
diff --git a/src/lib/measurements/display-transform.ts b/src/lib/measurements/display-transform.ts
index ff5c371b9..03a4382cd 100644
--- a/src/lib/measurements/display-transform.ts
+++ b/src/lib/measurements/display-transform.ts
@@ -333,6 +333,11 @@ const INTEGER_DISPLAY_TYPES: ReadonlySet<string> = new Set([
   // grain for these day-cumulative counts.
   "ACTIVE_ENERGY_BURNED",
   "TIME_IN_DAYLIGHT",
+  // v1.44 — the minute rings, mindful minutes and stood hours.
+  "EXERCISE_MINUTES",
+  "STAND_MINUTES",
+  "STAND_HOURS",
+  "MINDFUL_MINUTES",
 ]);
 
 /**
diff --git a/src/lib/measurements/import-apple-health-export.ts b/src/lib/measurements/import-apple-health-export.ts
index 1e3c3bab2..d91f34fac 100644
--- a/src/lib/measurements/import-apple-health-export.ts
+++ b/src/lib/measurements/import-apple-health-export.ts
@@ -227,6 +227,8 @@ interface PreparedWorkout {
   externalId: string;
   externalSourceVersion: string | null;
   metadata: Prisma.JsonValue | null;
+  /** The `<FileReference path>` of the workout's GPS track, when it has one. */
+  routePath?: string;
 }
 
 type CumulativeSourceSubtotals = Map<string, number>;
@@ -331,13 +333,49 @@ export function hashCumulativeSourceIdentity(
  * Returns `null` for unparseable values so the caller can skip the
  * row rather than poisoning the batch.
  */
+/** Apple's symbolic `HKCategoryValueAppleStandHour` values in `export.xml`. */
+const STAND_HOUR_STOOD = "HKCategoryValueAppleStandHourStood";
+const STAND_HOUR_IDLE = "HKCategoryValueAppleStandHourIdle";
+
+/** An idle stand hour: skipped on purpose, never a row and never "unparseable". */
+export function isIdleStandHour(
+  hkIdentifier: string,
+  rawValue: string | undefined,
+): boolean {
+  return (
+    hkIdentifier === "HKCategoryTypeIdentifierAppleStandHour" &&
+    rawValue === STAND_HOUR_IDLE
+  );
+}
+
+function minutesBetween(startDate: string, endDate: string): number | null {
+  const start = new Date(startDate);
+  const end = new Date(endDate);
+  if (Number.isNaN(start.getTime()) || Number.isNaN(end.getTime())) {
+    return null;
+  }
+  return Math.max(0, (end.getTime() - start.getTime()) / 60_000);
+}
+
 export function parseRecordValue(
   hkIdentifier: string,
   rawValue: string | undefined,
   startDate: string,
   endDate: string,
 ): { value: number; sleepStage?: number } | null {
+  // Mindful sessions carry no quantity (Apple writes no `value`, or the
+  // not-applicable sentinel): the reading is the session length, minutes
+  // from the record's own dates, the same contract as sleep.
+  if (hkIdentifier === "HKCategoryTypeIdentifierMindfulSession") {
+    const minutes = minutesBetween(startDate, endDate);
+    return minutes === null ? null : { value: minutes };
+  }
   if (rawValue === undefined) return null;
+  // A stood hour is one; an idle hour is dropped by the caller before it
+  // gets here (`isIdleStandHour`), so it never becomes a row.
+  if (hkIdentifier === "HKCategoryTypeIdentifierAppleStandHour") {
+    return rawValue === STAND_HOUR_STOOD ? { value: 1 } : null;
+  }
   if (hkIdentifier === "HKCategoryTypeIdentifierSleepAnalysis") {
     const stage = SLEEP_STAGE_NAME_TO_CODEPOINT[rawValue];
     if (stage === undefined) return null;
@@ -410,6 +448,14 @@ export interface StreamParseInput {
    * `WORKOUT_FLUSH_BATCH`.
    */
   workoutBatchSize?: number;
+  /**
+   * Called once per workout whose `<WorkoutRoute>` references a GPX file,
+   * with the workout's `externalId` and the path Apple wrote. Only passed
+   * when the account keeps workout routes (`storeWorkoutRoutes`); without it
+   * the reference is not even read. The track is attached after the XML
+   * pass, from the archive (`src/lib/apple-health/route-import.ts`).
+   */
+  onWorkoutRoute?: (ref: { externalId: string; path: string }) => void;
 }
 
 /**
@@ -432,6 +478,7 @@ export async function streamParseExportXml(
     prisma,
     onProgress,
     onExportDate,
+    onWorkoutRoute,
     spotBatchSize = SPOT_FLUSH_BATCH,
     workoutBatchSize = WORKOUT_FLUSH_BATCH,
   } = input;
@@ -1210,6 +1257,13 @@ export async function streamParseExportXml(
         return;
       }
 
+      if (isIdleStandHour(hkType, attrs.value)) {
+        // An hour without standing is the absence of a stood hour. Counted
+        // so the import summary still shows the archive carried it.
+        deferred[`${hkType}::idle`] = (deferred[`${hkType}::idle`] ?? 0) + 1;
+        return;
+      }
+
       const parsedValue = parseRecordValue(
         hkType,
         attrs.value,
@@ -1449,6 +1503,17 @@ export async function streamParseExportXml(
       return;
     }
 
+    if (
+      name === "FileReference" &&
+      onWorkoutRoute &&
+      currentWorkout &&
+      typeof attrs.path === "string" &&
+      attrs.path.toLowerCase().endsWith(".gpx")
+    ) {
+      currentWorkout.routePath = attrs.path;
+      return;
+    }
+
     if (
       name === "Me" ||
       name === "ActivitySummary" ||
@@ -1486,6 +1551,12 @@ export async function streamParseExportXml(
       }
     }
     if (tagName === "Workout" && currentWorkout) {
+      if (currentWorkout.routePath && onWorkoutRoute) {
+        onWorkoutRoute({
+          externalId: currentWorkout.externalId,
+          path: currentWorkout.routePath,
+        });
+      }
       workoutBatch.push(currentWorkout);
       currentWorkout = null;
     }
diff --git a/src/lib/measurements/type-label-keys.ts b/src/lib/measurements/type-label-keys.ts
index 32da24148..46a61d0a4 100644
--- a/src/lib/measurements/type-label-keys.ts
+++ b/src/lib/measurements/type-label-keys.ts
@@ -103,6 +103,13 @@ export const MEASUREMENT_TYPE_LABEL_KEYS: Record<MeasurementType, string> = {
   // ── v1.27.9 — screening scores ──
   WHO5_SCORE: "measurements.typeWho5Score",
   SCI_SCORE: "measurements.typeSciScore",
+  // ── v1.44 — activity rings, mindfulness, State of Mind, AFib burden ──
+  EXERCISE_MINUTES: "measurements.typeExerciseMinutes",
+  STAND_MINUTES: "measurements.typeStandMinutes",
+  STAND_HOURS: "measurements.typeStandHours",
+  MINDFUL_MINUTES: "measurements.typeMindfulMinutes",
+  STATE_OF_MIND_VALENCE: "measurements.typeStateOfMindValence",
+  AFIB_BURDEN: "measurements.typeAfibBurden",
   GRIP_STRENGTH: "measurements.typeGripStrength",
   PAIN_NRS: "measurements.typePainNrs",
   WAIST_CIRCUMFERENCE: "measurements.typeWaistCircumference",
diff --git a/src/lib/measurements/unit-label.ts b/src/lib/measurements/unit-label.ts
index c6373967a..f1f6fcfa2 100644
--- a/src/lib/measurements/unit-label.ts
+++ b/src/lib/measurements/unit-label.ts
@@ -25,6 +25,7 @@ const TYPE_UNIT_LABEL_KEYS: Readonly<Record<string, string>> = {
   FALL_COUNT: "insights.units.falls",
   BREATHING_DISTURBANCES: "insights.units.breathingEvents",
   RESPIRATORY_RATE: "insights.units.respiratoryRate",
+  STAND_HOURS: "insights.units.standHours",
 };
 
 /** Word-shaped tokens that read the same whatever the type. */
@@ -52,6 +53,8 @@ const UNITLESS_UNIT_TOKENS: ReadonlySet<string> = new Set([
   "event",
   "level",
   "ratio",
+  // State of Mind valence: a bare −1..1 number.
+  "valence",
   "unknown",
 ]);
 
diff --git a/src/lib/measurements/unit-map.ts b/src/lib/measurements/unit-map.ts
index 307a7173d..71761e35c 100644
--- a/src/lib/measurements/unit-map.ts
+++ b/src/lib/measurements/unit-map.ts
@@ -156,6 +156,16 @@ const unitMap: Record<string, string> = {
   PAIN_NRS: "score",
   WAIST_CIRCUMFERENCE: "cm",
   WAIST_TO_HEIGHT: "ratio",
+  // ── v1.44 — activity rings, mindfulness, State of Mind, AFib burden ──
+  EXERCISE_MINUTES: "minutes",
+  STAND_MINUTES: "minutes",
+  // Stood hours, a whole-number tally of hours.
+  STAND_HOURS: "hours",
+  MINDFUL_MINUTES: "minutes",
+  // HealthKit's dimensionless −1..1 valence.
+  STATE_OF_MIND_VALENCE: "valence",
+  // Percent of the week after the ×100 scaling.
+  AFIB_BURDEN: "%",
 };
 
 export function getUnitForType(type: string): string {
diff --git a/src/lib/measurements/value-domain.ts b/src/lib/measurements/value-domain.ts
index 0f071e6f9..1ae492854 100644
--- a/src/lib/measurements/value-domain.ts
+++ b/src/lib/measurements/value-domain.ts
@@ -48,6 +48,7 @@ export const INTEGER_VALUED_MEASUREMENT_TYPES: ReadonlySet<string> = new Set([
   "ACTIVITY_STEPS",
   "FLIGHTS_CLIMBED",
   "FALL_COUNT",
+  "STAND_HOURS",
   "BREATHING_DISTURBANCES",
   "SLEEP_DISTURBANCE_COUNT",
   // Category events — the row carries a fixed `value = 1` (one fired event).
diff --git a/src/lib/modules/measurement-scope.ts b/src/lib/modules/measurement-scope.ts
index 2ff632964..7975be709 100644
--- a/src/lib/modules/measurement-scope.ts
+++ b/src/lib/modules/measurement-scope.ts
@@ -122,7 +122,8 @@ const METRIC_STATUS_MODULE_OWNERS: Partial<Record<MeasurementType, ModuleKey>> =
  *   - Core clinical figures every account carries: weight, pulse, blood
  *     pressure, BMI, body temperature.
  *   - Body composition: fat / lean / muscle / bone / water / visceral.
- *   - Activity volume: steps, distance, flights, active energy. Owned by no
+ *   - Activity volume: steps, distance, flights, active energy, and the
+ *     exercise and stand rings. Owned by no
  *     module — `workouts` gates workout SESSIONS, not ambient movement.
  *   - Gait and mobility, incl. the fall / walk-test / stair metrics.
  *   - Cardio-vascular readings with no module home: SpO2, respiratory rate,
@@ -162,6 +163,11 @@ export const UNSCOPED_REVIEWED_TYPES: ReadonlySet<MeasurementType> =
     "FLIGHTS_CLIMBED",
     "ACTIVE_ENERGY_BURNED",
     "ENERGY_EXPENDITURE_KJ",
+    // v1.44 — the exercise and stand rings are ambient movement like steps,
+    // not workout sessions.
+    "EXERCISE_MINUTES",
+    "STAND_MINUTES",
+    "STAND_HOURS",
     // Gait / mobility.
     "WALKING_SPEED",
     "WALKING_STEADINESS",
diff --git a/src/lib/openapi/routes/profile.ts b/src/lib/openapi/routes/profile.ts
index b2a953afa..a510c4fad 100644
--- a/src/lib/openapi/routes/profile.ts
+++ b/src/lib/openapi/routes/profile.ts
@@ -33,6 +33,7 @@ import {
   documentsAutoAiReadPatchSchema,
   injectionSitePrefsPatchSchema,
   labsLocalOcrPatchSchema,
+  workoutRoutesPatchSchema,
   unitPreferencePatchSchema,
   glucoseUnitPatchSchema,
   useCentralCodexPatchSchema,
@@ -1000,6 +1001,16 @@ const labsLocalOcrResponse = z
   .object({ labsLocalOcrEnabled: z.boolean() })
   .meta({ id: "LabsLocalOcrResponse" });
 
+const workoutRoutesPatchRequest = workoutRoutesPatchSchema.meta({
+  id: "WorkoutRoutesPatchRequest",
+  description:
+    "Keep or stop keeping the GPS track of new workouts. Off by default.",
+});
+
+const workoutRoutesResponse = z
+  .object({ storeWorkoutRoutes: z.boolean() })
+  .meta({ id: "WorkoutRoutesResponse" });
+
 const useCentralCodexPatchRequest = useCentralCodexPatchSchema.meta({
   id: "UseCentralCodexPatchRequest",
   description:
@@ -2254,6 +2265,56 @@ export const profilePaths: NonNullable<ZodOpenApiObject["paths"]> = {
       },
     },
   },
+  "/api/auth/me/workout-routes": {
+    get: {
+      tags: ["Auth"],
+      summary: "Read the workout-route opt-in",
+      description:
+        "Whether the GPS track of a workout is kept. Off by default. While it is off, `POST /api/workouts/batch` and the Apple Health export import keep every workout but drop its `route`; the per-entry status is the same as with the route stored. No AI path ever reads a stored track.",
+      responses: {
+        "200": {
+          description: "The current flag.",
+          content: {
+            "application/json": {
+              schema: dataEnvelope(
+                workoutRoutesResponse,
+                "GetWorkoutRoutesEnvelope",
+              ),
+            },
+          },
+        },
+        ...stdResponses,
+      },
+    },
+    patch: {
+      tags: ["Auth"],
+      summary: "Set the workout-route opt-in",
+      description:
+        "Hard-set, idempotent, audit-logged. Rate-limited 60 / min per user; body capped at 1 KB. Turning it off stops new tracks; tracks already stored stay until their workout is deleted.",
+      requestBody: {
+        required: true,
+        content: { "application/json": { schema: workoutRoutesPatchRequest } },
+      },
+      responses: {
+        "200": {
+          description: "The resolved next flag.",
+          content: {
+            "application/json": {
+              schema: dataEnvelope(
+                workoutRoutesResponse,
+                "PatchWorkoutRoutesEnvelope",
+              ),
+            },
+          },
+        },
+        "413": {
+          description: "Request body exceeds 1024 bytes. Nothing was written.",
+          content: { "application/json": { schema: errorEnvelope } },
+        },
+        ...stdResponses,
+      },
+    },
+  },
   "/api/auth/me/use-central-codex": {
     get: {
       tags: ["Auth"],
diff --git a/src/lib/personal-records/pr-direction.ts b/src/lib/personal-records/pr-direction.ts
index ed0340fc5..dc8ecf4ad 100644
--- a/src/lib/personal-records/pr-direction.ts
+++ b/src/lib/personal-records/pr-direction.ts
@@ -103,6 +103,12 @@ export function getPRDirection(
     case "BONE_MASS":
     case "MUSCLE_MASS":
     case "TIME_IN_DAYLIGHT":
+    // v1.44 — the activity rings: more exercise, standing and mindful
+    // minutes (and more stood hours) are the goal, as Apple frames them.
+    case "EXERCISE_MINUTES":
+    case "STAND_MINUTES":
+    case "STAND_HOURS":
+    case "MINDFUL_MINUTES":
     // v1.4.30 — walking steadiness on a 0-100 scale; Apple's own
     // Mobility section treats higher as the achievement (the
     // recovery direction from a low-steadiness window).
@@ -206,6 +212,11 @@ export function getPRDirection(
     // "personal record" for a health-notification event would be both
     // meaningless and alarming, so they explicitly have no PR direction.
     case "IRREGULAR_RHYTHM_NOTIFICATION":
+    // v1.44 — AFib burden is an awareness signal from a certified feature,
+    // and a State of Mind valence is a self-report of how a moment felt.
+    // Neither is a goal axis a record could celebrate.
+    case "AFIB_BURDEN":
+    case "STATE_OF_MIND_VALENCE":
     case "HIGH_HEART_RATE_EVENT":
     case "LOW_HEART_RATE_EVENT":
     case "WALKING_STEADINESS_EVENT":
diff --git a/src/lib/query-keys/workouts.ts b/src/lib/query-keys/workouts.ts
index de709a028..3bffcdfbc 100644
--- a/src/lib/query-keys/workouts.ts
+++ b/src/lib/query-keys/workouts.ts
@@ -22,4 +22,9 @@ export const workoutKeys = {
     sportType?: string;
   }) => ["workouts", "recent", opts] as const,
   workoutDetail: (id: string) => ["workouts", id] as const,
+  /**
+   * v1.44 — the workout-route opt-in. Its own root, so invalidating the
+   * workout caches after a sync never refetches the setting.
+   */
+  workoutRoutesPref: () => ["workout-routes-pref"] as const,
 };
diff --git a/src/lib/report-selection/__tests__/catalogue-guard.test.ts b/src/lib/report-selection/__tests__/catalogue-guard.test.ts
index 6b270286d..4e3ba4439 100644
--- a/src/lib/report-selection/__tests__/catalogue-guard.test.ts
+++ b/src/lib/report-selection/__tests__/catalogue-guard.test.ts
@@ -53,9 +53,9 @@ function resolves(key: string): boolean {
 
 describe("report selection catalogue", () => {
   it("carries every measurement type and every structured leaf", () => {
-    expect(MEASUREMENT_LEAF_IDS).toHaveLength(77);
+    expect(MEASUREMENT_LEAF_IDS).toHaveLength(83);
     expect(STRUCTURED_LEAF_IDS).toHaveLength(18);
-    expect(ALL_LEAF_IDS).toHaveLength(95);
+    expect(ALL_LEAF_IDS).toHaveLength(101);
   });
 
   it("resolves a label for every leaf", () => {
@@ -145,13 +145,17 @@ describe("template purity", () => {
     expect(unknown).toEqual([]);
   });
 
-  it("fences exactly the eight leaves the design names", () => {
+  it("fences exactly the ten leaves the design names", () => {
     expect([...SENSITIVE_LEAF_IDS].sort()).toEqual(
       [
         "ANAMNESIS",
         "CYCLE",
         "FAMILY_HISTORY",
         "GAD7_SCORE",
+        // v1.44 — mindful minutes and the State of Mind valence are
+        // mental-health self-care and self-report.
+        "MINDFUL_MINUTES",
+        "STATE_OF_MIND_VALENCE",
         "MOOD",
         "PHQ9_SCORE",
         "SCI_SCORE",
diff --git a/src/lib/report-selection/catalogue.ts b/src/lib/report-selection/catalogue.ts
index 8d622dd9f..f53f1287a 100644
--- a/src/lib/report-selection/catalogue.ts
+++ b/src/lib/report-selection/catalogue.ts
@@ -119,6 +119,7 @@ export const MEASUREMENT_LEAF_GROUP: Record<MeasurementType, ReportGroupId> = {
   IRREGULAR_RHYTHM_NOTIFICATION: "cardio",
   HIGH_HEART_RATE_EVENT: "cardio",
   LOW_HEART_RATE_EVENT: "cardio",
+  AFIB_BURDEN: "cardio",
 
   // ── body ──
   WEIGHT: "body",
@@ -161,6 +162,9 @@ export const MEASUREMENT_LEAF_GROUP: Record<MeasurementType, ReportGroupId> = {
   STRAIN_SCORE: "activity",
   DAY_STRAIN: "activity",
   WORKOUT_STRAIN: "activity",
+  EXERCISE_MINUTES: "activity",
+  STAND_MINUTES: "activity",
+  STAND_HOURS: "activity",
 
   // ── mobility & gait ──
   WALKING_SPEED: "mobility",
@@ -185,6 +189,11 @@ export const MEASUREMENT_LEAF_GROUP: Record<MeasurementType, ReportGroupId> = {
   BLOOD_GLUCOSE: "glucose",
 
   // ── fenced ──
+  // Mindful minutes and the State of Mind valence are mental-health
+  // self-care and self-report: fenced like the screening totals, so they
+  // reach a report only when the person picks them.
+  MINDFUL_MINUTES: "sensitive",
+  STATE_OF_MIND_VALENCE: "sensitive",
   PHQ9_SCORE: "sensitive",
   GAD7_SCORE: "sensitive",
   WHO5_SCORE: "sensitive",
@@ -264,6 +273,9 @@ export const LEAF_MODULE: Partial<Record<ReportLeafId, ModuleKey>> = {
   // Activity / movement series and the training-load scores.
   ACTIVITY_STEPS: "workouts",
   ACTIVE_ENERGY_BURNED: "workouts",
+  EXERCISE_MINUTES: "workouts",
+  STAND_MINUTES: "workouts",
+  STAND_HOURS: "workouts",
   ENERGY_EXPENDITURE_KJ: "workouts",
   FLIGHTS_CLIMBED: "workouts",
   WALKING_RUNNING_DISTANCE: "workouts",
@@ -309,6 +321,10 @@ export const LEAF_MODULE: Partial<Record<ReportLeafId, ModuleKey>> = {
   GAD7_SCORE: "mentalHealth",
   WHO5_SCORE: "mentalHealth",
   SCI_SCORE: "mentalHealth",
+  // The State of Mind valence and mindful minutes ride the mood module: a
+  // person who turned mood tracking off does not see them on a report.
+  STATE_OF_MIND_VALENCE: "mood",
+  MINDFUL_MINUTES: "mood",
   // Structured sections with an owning module.
   LAB_RESULTS: "labs",
   MOOD: "mood",
diff --git a/src/lib/signals/__tests__/fixtures/expected-measurement-loinc.json b/src/lib/signals/__tests__/fixtures/expected-measurement-loinc.json
index ef14ef361..905fa945d 100644
--- a/src/lib/signals/__tests__/fixtures/expected-measurement-loinc.json
+++ b/src/lib/signals/__tests__/fixtures/expected-measurement-loinc.json
@@ -262,5 +262,41 @@
     "display": "Sleep Condition Indicator total score",
     "unit": "{score}",
     "category": "survey"
+  },
+  "EXERCISE_MINUTES": {
+    "loinc": "HKQuantityTypeIdentifierAppleExerciseTime",
+    "display": "Exercise time",
+    "unit": "min",
+    "category": "activity"
+  },
+  "STAND_MINUTES": {
+    "loinc": "HKQuantityTypeIdentifierAppleStandTime",
+    "display": "Stand time",
+    "unit": "min",
+    "category": "activity"
+  },
+  "STAND_HOURS": {
+    "loinc": "HKCategoryTypeIdentifierAppleStandHour",
+    "display": "Stand hours",
+    "unit": "h",
+    "category": "activity"
+  },
+  "MINDFUL_MINUTES": {
+    "loinc": "HKCategoryTypeIdentifierMindfulSession",
+    "display": "Mindful session",
+    "unit": "min",
+    "category": "activity"
+  },
+  "STATE_OF_MIND_VALENCE": {
+    "loinc": null,
+    "display": "State of mind valence",
+    "unit": "1",
+    "category": "survey"
+  },
+  "AFIB_BURDEN": {
+    "loinc": "HKQuantityTypeIdentifierAtrialFibrillationBurden",
+    "display": "Atrial fibrillation burden",
+    "unit": "%",
+    "category": "vital-signs"
   }
 }
diff --git a/src/lib/signals/registry.ts b/src/lib/signals/registry.ts
index 2b2c8ad4f..d889362a8 100644
--- a/src/lib/signals/registry.ts
+++ b/src/lib/signals/registry.ts
@@ -1778,6 +1778,142 @@ export const SIGNALS: Record<string, SignalDefinition> = {
       mcp: false,
     },
   },
+  // ── v1.44 — Apple Health activity rings, mindfulness, State of Mind, AFib ──
+  // The three ring metrics are read through MCP like steps and daylight. The
+  // mindful minutes, the State of Mind valence and AFib burden stay off every
+  // AI-facing surface (Coach, MCP, correlations): mental-health self-reports
+  // and an AFib awareness signal are shared only where the person asks.
+  EXERCISE_MINUTES: {
+    key: "EXERCISE_MINUTES",
+    kind: "measurement",
+    source: { measurementType: "EXERCISE_MINUTES" },
+    displayName: "Exercise minutes",
+    unit: "min/day",
+    direction: "higher-better",
+    archetype: "activity-fitness",
+    // Apple's exercise ring default and the WHO weekly 150 minutes / 7.
+    normalRange: { low: 22, high: 60 },
+    surfaces: {
+      detailPage: false,
+      correlationEligible: false,
+      coachSnapshot: false,
+      mcp: true,
+    },
+    fhir: {
+      loinc: "HKQuantityTypeIdentifierAppleExerciseTime",
+      display: "Exercise time",
+      unit: "min",
+      category: "activity",
+    },
+  },
+  STAND_MINUTES: {
+    key: "STAND_MINUTES",
+    kind: "measurement",
+    source: { measurementType: "STAND_MINUTES" },
+    displayName: "Standing minutes",
+    unit: "min/day",
+    direction: "higher-better",
+    archetype: "activity-fitness",
+    surfaces: {
+      detailPage: false,
+      correlationEligible: false,
+      coachSnapshot: false,
+      mcp: true,
+    },
+    fhir: {
+      loinc: "HKQuantityTypeIdentifierAppleStandTime",
+      display: "Stand time",
+      unit: "min",
+      category: "activity",
+    },
+  },
+  STAND_HOURS: {
+    key: "STAND_HOURS",
+    kind: "measurement",
+    source: { measurementType: "STAND_HOURS" },
+    displayName: "Stand hours",
+    unit: "h/day",
+    direction: "higher-better",
+    archetype: "activity-fitness",
+    // Apple's stand-ring goal is 12 hours.
+    normalRange: { low: 12, high: 24 },
+    surfaces: {
+      detailPage: false,
+      correlationEligible: false,
+      coachSnapshot: false,
+      mcp: true,
+    },
+    fhir: {
+      loinc: "HKCategoryTypeIdentifierAppleStandHour",
+      display: "Stand hours",
+      unit: "h",
+      category: "activity",
+    },
+  },
+  MINDFUL_MINUTES: {
+    key: "MINDFUL_MINUTES",
+    kind: "measurement",
+    source: { measurementType: "MINDFUL_MINUTES" },
+    displayName: "Mindful minutes",
+    unit: "min/day",
+    direction: "higher-better",
+    archetype: "activity-fitness",
+    surfaces: {
+      detailPage: false,
+      correlationEligible: false,
+      coachSnapshot: false,
+      mcp: false,
+    },
+    fhir: {
+      loinc: "HKCategoryTypeIdentifierMindfulSession",
+      display: "Mindful session",
+      unit: "min",
+      category: "activity",
+    },
+  },
+  STATE_OF_MIND_VALENCE: {
+    key: "STATE_OF_MIND_VALENCE",
+    kind: "score",
+    source: { measurementType: "STATE_OF_MIND_VALENCE" },
+    displayName: "State of mind (valence)",
+    unit: "valence",
+    direction: "higher-better",
+    archetype: "physiological-vital",
+    surfaces: {
+      detailPage: false,
+      correlationEligible: false,
+      coachSnapshot: false,
+      mcp: false,
+    },
+    fhir: {
+      // A self-report on HealthKit's −1..1 scale; no LOINC concept.
+      loinc: null,
+      display: "State of mind valence",
+      unit: "1",
+      category: "survey",
+    },
+  },
+  AFIB_BURDEN: {
+    key: "AFIB_BURDEN",
+    kind: "measurement",
+    source: { measurementType: "AFIB_BURDEN" },
+    displayName: "AFib burden",
+    unit: "%",
+    direction: "lower-better",
+    archetype: "physiological-vital",
+    surfaces: {
+      detailPage: false,
+      correlationEligible: false,
+      coachSnapshot: false,
+      mcp: false,
+    },
+    fhir: {
+      loinc: "HKQuantityTypeIdentifierAtrialFibrillationBurden",
+      display: "Atrial fibrillation burden",
+      unit: "%",
+      category: "vital-signs",
+    },
+  },
 };
 
 /** Type guard: narrow an arbitrary string to a registered signal key. */
diff --git a/src/lib/validations/backup.ts b/src/lib/validations/backup.ts
index 957caaf9e..658568fae 100644
--- a/src/lib/validations/backup.ts
+++ b/src/lib/validations/backup.ts
@@ -2175,6 +2175,7 @@ const accountSettingsBackupSchema = z
     coachPrefsJson: z.unknown().optional(),
     documentsAutoAiRead: z.boolean().optional(),
     labsLocalOcrEnabled: z.boolean().optional(),
+    storeWorkoutRoutes: z.boolean().optional(),
     onboardingCompletedAt: isoDateTime.nullable().optional(),
     onboardingTourCompleted: z.boolean().optional(),
     onboardingTourProgressJson: z.unknown().optional(),
diff --git a/src/lib/validations/measurement.ts b/src/lib/validations/measurement.ts
index 9ac5f0ae8..7134461ac 100644
--- a/src/lib/validations/measurement.ts
+++ b/src/lib/validations/measurement.ts
@@ -145,6 +145,14 @@ export const measurementTypeEnum = z.enum([
   // percentage (raw sum × 4); SCI stores the 0–32 total.
   "WHO5_SCORE",
   "SCI_SCORE",
+  // ── v1.44 — Apple Health activity rings, mindfulness, State of Mind and
+  // AFib burden. See the enum comments in `prisma/schema.prisma`.
+  "EXERCISE_MINUTES",
+  "STAND_MINUTES",
+  "STAND_HOURS",
+  "MINDFUL_MINUTES",
+  "STATE_OF_MIND_VALENCE",
+  "AFIB_BURDEN",
 ]);
 
 /**
@@ -440,6 +448,18 @@ export const VALUE_RANGES: Record<string, { min: number; max: number }> = {
   // SCI total 0–32 — both server-derived, higher = better.
   WHO5_SCORE: { min: 0, max: 100 },
   SCI_SCORE: { min: 0, max: 32 },
+  // ── v1.44 — the minute rings and mindful minutes are bounded by the day;
+  // a row is one sample or one day's total, never more than 1440 minutes.
+  EXERCISE_MINUTES: { min: 0, max: 1440 },
+  STAND_MINUTES: { min: 0, max: 1440 },
+  MINDFUL_MINUTES: { min: 0, max: 1440 },
+  // Stood hours: 1 per hour sample, at most 24 on a day's total.
+  STAND_HOURS: { min: 0, max: 24 },
+  // State of Mind valence: HealthKit's closed −1..1 scale.
+  STATE_OF_MIND_VALENCE: { min: -1, max: 1 },
+  // AFib burden as a percent of the week, after the ×100 scaling. A client
+  // that already scaled sends 2 for 2 %, which lands at 200 and is refused.
+  AFIB_BURDEN: { min: 0, max: 100 },
   // Grip strength kg — a child can read in the single digits, an elite athlete
   // tops ~90 kg; 120 is a generous ceiling that still rejects sensor noise.
   GRIP_STRENGTH: { min: 0, max: 120 },
diff --git a/src/lib/validations/user-prefs.ts b/src/lib/validations/user-prefs.ts
index 2f6200710..786926f62 100644
--- a/src/lib/validations/user-prefs.ts
+++ b/src/lib/validations/user-prefs.ts
@@ -41,6 +41,11 @@ export const labsLocalOcrPatchSchema = z.object({
   labsLocalOcrEnabled: z.boolean(),
 });
 
+/** `PATCH /api/auth/me/workout-routes` — keep workout GPS tracks (opt-in). */
+export const workoutRoutesPatchSchema = z.object({
+  storeWorkoutRoutes: z.boolean(),
+});
+
 /** `PATCH /api/auth/me/use-central-codex` — the operator's shared Codex. */
 export const useCentralCodexPatchSchema = z.object({
   useCentralCodex: z.boolean(),
diff --git a/src/lib/workouts/__tests__/insight-evidence.test.ts b/src/lib/workouts/__tests__/insight-evidence.test.ts
index da3f7b11f..a19fcfceb 100644
--- a/src/lib/workouts/__tests__/insight-evidence.test.ts
+++ b/src/lib/workouts/__tests__/insight-evidence.test.ts
@@ -6,7 +6,6 @@ import {
   assertNumericLeaves,
   buildWorkoutInsightEvidence,
   narrowSportType,
-  routeClimbM,
   summariseHrShape,
   summariseOwnHistory,
 } from "../insight-evidence";
@@ -90,38 +89,6 @@ describe("summariseHrShape", () => {
   });
 });
 
-describe("routeClimbM", () => {
-  it("sums only the positive altitude deltas", () => {
-    const geometry = {
-      type: "LineString",
-      coordinates: [
-        [8, 50, 100],
-        [8, 50, 140],
-        [8, 50, 110],
-        [8, 50, 160],
-      ],
-    };
-    // +40 then −30 then +50 → 90 climbed, not 60 net.
-    expect(routeClimbM(geometry)).toBe(90);
-  });
-
-  it("returns null when the geometry carries no altitude channel", () => {
-    // Withings ships static GPX with no altitudes. Reporting a confident 0
-    // would be a claim about flat terrain that the data does not make.
-    expect(
-      routeClimbM({
-        type: "LineString",
-        coordinates: [
-          [8, 50],
-          [8.1, 50.1],
-        ],
-      }),
-    ).toBeNull();
-    expect(routeClimbM(null)).toBeNull();
-    expect(routeClimbM("not geometry")).toBeNull();
-  });
-});
-
 describe("summariseOwnHistory", () => {
   const row = (durationSec: number, avgHeartRate: number | null) => ({
     durationSec,
@@ -176,7 +143,6 @@ describe("buildWorkoutInsightEvidence", () => {
     tz: "Europe/Berlin",
     hrSeries: null,
     zones: null,
-    routeGeometry: null,
     history: [],
   };
 
@@ -196,20 +162,7 @@ describe("buildWorkoutInsightEvidence", () => {
     expect(evidence.localDate).toMatch(/^\d{4}-\d{2}-\d{2}$/);
   });
 
-  it("prefers route-derived climb over the denormalised column", () => {
-    const evidence = buildWorkoutInsightEvidence({
-      ...base,
-      routeGeometry: {
-        coordinates: [
-          [8, 50, 100],
-          [8, 50, 130],
-        ],
-      },
-    });
-    expect(evidence.climbM).toBe(30);
-  });
-
-  it("falls back to the column when the route carries no altitudes", () => {
+  it("reads the climb from the stored column", () => {
     const evidence = buildWorkoutInsightEvidence(base);
     expect(evidence.climbM).toBe(210);
   });
@@ -240,7 +193,6 @@ describe("workoutInsightInputHash", () => {
     tz: "UTC",
     hrSeries: null,
     zones: null,
-    routeGeometry: null,
     history: [],
   });
 
@@ -372,7 +324,6 @@ describe("assertNumericLeaves", () => {
             },
           ],
         },
-        routeGeometry: null,
         history: [],
       }),
     ).toThrow(/non-numeric leaf/);
@@ -394,15 +345,14 @@ describe("assertNumericLeaves", () => {
       tz: "UTC",
       hrSeries: series([120, 130, 140, 150, 145, 138]),
       zones: null,
-      routeGeometry: null,
       history: [],
     });
     expect(evidence.hr).not.toBeNull();
     expect(evidence.hr).not.toHaveProperty("source");
   });
 
-  it("never carries route geometry — only the one number derived from it", () => {
-    const evidence = buildWorkoutInsightEvidence({
+  it("takes no route geometry at all", () => {
+    const input = {
       row: {
         sportType: "cycling",
         startedAt: new Date("2026-07-18T06:00:00.000Z"),
@@ -412,19 +362,19 @@ describe("assertNumericLeaves", () => {
         avgHeartRate: null,
         maxHeartRate: null,
         minHeartRate: null,
-        elevationM: null,
+        elevationM: 50,
       },
       tz: "UTC",
       hrSeries: null,
       zones: null,
-      routeGeometry: {
-        coordinates: [
-          [8.1, 50.1, 100],
-          [8.2, 50.2, 150],
-        ],
-      },
       history: [],
-    });
+    };
+    const withTrack = {
+      ...input,
+      // @ts-expect-error — the builder has no route input; a track cannot be handed to it.
+      routeGeometry: { coordinates: [[8.1, 50.1, 100]] },
+    } satisfies Parameters<typeof buildWorkoutInsightEvidence>[0];
+    const evidence = buildWorkoutInsightEvidence(withTrack);
     // Location history is not a figure and may not ride a prompt.
     expect(JSON.stringify(evidence)).not.toContain("8.1");
     expect(JSON.stringify(evidence)).not.toContain("coordinates");
diff --git a/src/lib/workouts/__tests__/route-climb.test.ts b/src/lib/workouts/__tests__/route-climb.test.ts
new file mode 100644
index 000000000..f83681843
--- /dev/null
+++ b/src/lib/workouts/__tests__/route-climb.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+
+import { routeClimbM } from "../route-climb";
+
+describe("routeClimbM", () => {
+  it("sums only the positive altitude deltas", () => {
+    const geometry = {
+      type: "LineString",
+      coordinates: [
+        [8, 50, 100],
+        [8, 50, 140],
+        [8, 50, 110],
+        [8, 50, 160],
+      ],
+    };
+    // +40 then −30 then +50 → 90 climbed, not 60 net.
+    expect(routeClimbM(geometry)).toBe(90);
+  });
+
+  it("returns null when the geometry carries no altitude channel", () => {
+    // Withings ships static GPX with no altitudes. Reporting a confident 0
+    // would be a claim about flat terrain that the data does not make.
+    expect(
+      routeClimbM({
+        type: "LineString",
+        coordinates: [
+          [8, 50],
+          [8.1, 50.1],
+        ],
+      }),
+    ).toBeNull();
+    expect(routeClimbM(null)).toBeNull();
+    expect(routeClimbM("not geometry")).toBeNull();
+  });
+});
diff --git a/src/lib/workouts/insight-evidence.ts b/src/lib/workouts/insight-evidence.ts
index ab68d2b91..3e47f8cce 100644
--- a/src/lib/workouts/insight-evidence.ts
+++ b/src/lib/workouts/insight-evidence.ts
@@ -221,34 +221,6 @@ export function summariseHrShape(
   };
 }
 
-/**
- * Total metres climbed, summed from a GeoJSON LineString's altitude channel.
- *
- * Only positive deltas count — this is climb, not net elevation change, which
- * is the figure a rider recognises. Returns null when the geometry carries no
- * altitude channel at all (Withings ships static GPX without one), so the
- * caller can fall back to the denormalised column instead of reporting a
- * confident zero.
- */
-export function routeClimbM(geometry: unknown): number | null {
-  if (!geometry || typeof geometry !== "object") return null;
-  const coords = (geometry as { coordinates?: unknown }).coordinates;
-  if (!Array.isArray(coords)) return null;
-
-  let climb = 0;
-  let previous: number | null = null;
-  let seen = 0;
-  for (const point of coords) {
-    if (!Array.isArray(point) || point.length < 3) continue;
-    const alt = point[2];
-    if (typeof alt !== "number" || !Number.isFinite(alt)) continue;
-    seen++;
-    if (previous !== null && alt > previous) climb += alt - previous;
-    previous = alt;
-  }
-  return seen >= 2 ? Math.round(climb) : null;
-}
-
 /** Slim row shape the own-history median reads. */
 export interface OwnHistoryRow {
   durationSec: number;
@@ -330,8 +302,6 @@ export interface BuildEvidenceInput {
   hrSeries: WorkoutHrSeries | null;
   /** Zones as the detail route computes them, or null. */
   zones: WorkoutZones | null;
-  /** `WorkoutRoute.geometry`, or null when the source shipped no route. */
-  routeGeometry: unknown;
   /** Same-sport sessions inside the lookback, excluding this workout. */
   history: readonly OwnHistoryRow[];
 }
@@ -412,7 +382,9 @@ export function buildWorkoutInsightEvidence(
     localDate: userDayKey(row.startedAt, input.tz),
     durationSec: row.durationSec,
     distanceM: row.totalDistanceM,
-    climbM: routeClimbM(input.routeGeometry) ?? row.elevationM,
+    // The stored column only. A kept GPS track already filled it at write
+    // time (`route-climb.ts`); the track itself never reaches this builder.
+    climbM: row.elevationM,
     activeEnergyKcal: row.totalEnergyKcal,
     avgHr: row.avgHeartRate,
     maxHr: row.maxHeartRate,
diff --git a/src/lib/workouts/route-climb.ts b/src/lib/workouts/route-climb.ts
new file mode 100644
index 000000000..9e2b8bd03
--- /dev/null
+++ b/src/lib/workouts/route-climb.ts
@@ -0,0 +1,37 @@
+/**
+ * Metres climbed, derived from a workout's GPS track at write time.
+ *
+ * The workout batch route fills `Workout.elevationM` from a kept track when
+ * the source sent no elevation of its own, so the figure lives on the
+ * workout row. Readers, the workout insight among them, take the column and
+ * never open the track: no AI path reads route geometry (the egress guard
+ * freezes the readers).
+ */
+
+/**
+ * Total metres climbed, summed from a GeoJSON LineString's altitude channel.
+ *
+ * Only positive deltas count — this is climb, not net elevation change, which
+ * is the figure a rider recognises. Returns null when the geometry carries no
+ * altitude channel at all (Withings ships static GPX without one), so the
+ * caller can fall back to the denormalised column instead of reporting a
+ * confident zero.
+ */
+export function routeClimbM(geometry: unknown): number | null {
+  if (!geometry || typeof geometry !== "object") return null;
+  const coords = (geometry as { coordinates?: unknown }).coordinates;
+  if (!Array.isArray(coords)) return null;
+
+  let climb = 0;
+  let previous: number | null = null;
+  let seen = 0;
+  for (const point of coords) {
+    if (!Array.isArray(point) || point.length < 3) continue;
+    const alt = point[2];
+    if (typeof alt !== "number" || !Number.isFinite(alt)) continue;
+    seen++;
+    if (previous !== null && alt > previous) climb += alt - previous;
+    previous = alt;
+  }
+  return seen >= 2 ? Math.round(climb) : null;
+}

From b76826a5f8baede791bb2ee60e51c525c1703bd6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Wed, 21 Oct 2026 20:20:10 +0200
Subject: [PATCH 5/8] test(workouts): call the route opt-in handlers with their
 real arity

---
 .../me/workout-routes/__tests__/route.test.ts | 26 +++----------------
 1 file changed, 4 insertions(+), 22 deletions(-)

diff --git a/src/app/api/auth/me/workout-routes/__tests__/route.test.ts b/src/app/api/auth/me/workout-routes/__tests__/route.test.ts
index dad36584d..e3a0cbbaf 100644
--- a/src/app/api/auth/me/workout-routes/__tests__/route.test.ts
+++ b/src/app/api/auth/me/workout-routes/__tests__/route.test.ts
@@ -60,10 +60,7 @@ beforeEach(() => {
 describe("/api/auth/me/workout-routes", () => {
   it("reads off when the row carries no value", async () => {
     vi.mocked(prisma.user.findUnique).mockResolvedValue(null);
-    const res = await GET(
-      new Request("http://localhost/api/auth/me/workout-routes") as never,
-      { params: Promise.resolve({}) } as never,
-    );
+    const res = await GET();
     expect(res.status).toBe(200);
     expect(await res.json()).toMatchObject({
       data: { storeWorkoutRoutes: false },
@@ -74,12 +71,7 @@ describe("/api/auth/me/workout-routes", () => {
     vi.mocked(prisma.user.findUnique).mockResolvedValue({
       storeWorkoutRoutes: false,
     } as never);
-    const res = await PATCH(
-      mkPatch({ storeWorkoutRoutes: true }) as never,
-      {
-        params: Promise.resolve({}),
-      } as never,
-    );
+    const res = await PATCH(mkPatch({ storeWorkoutRoutes: true }));
     expect(res.status).toBe(200);
     expect(await res.json()).toMatchObject({
       data: { storeWorkoutRoutes: true },
@@ -97,24 +89,14 @@ describe("/api/auth/me/workout-routes", () => {
   });
 
   it("refuses a malformed body with 422 and writes nothing", async () => {
-    const res = await PATCH(
-      mkPatch({ storeWorkoutRoutes: "yes" }) as never,
-      {
-        params: Promise.resolve({}),
-      } as never,
-    );
+    const res = await PATCH(mkPatch({ storeWorkoutRoutes: "yes" }));
     expect(res.status).toBe(422);
     expect(prisma.user.update).not.toHaveBeenCalled();
   });
 
   it("refuses an unauthenticated caller", async () => {
     vi.mocked(getSession).mockResolvedValue(null);
-    const res = await PATCH(
-      mkPatch({ storeWorkoutRoutes: true }) as never,
-      {
-        params: Promise.resolve({}),
-      } as never,
-    );
+    const res = await PATCH(mkPatch({ storeWorkoutRoutes: true }));
     expect(res.status).toBe(401);
     expect(prisma.user.update).not.toHaveBeenCalled();
   });

From cc8ea3dfbb1cd5825dd48e2f67f3506490c8d256 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Wed, 21 Oct 2026 20:26:15 +0200
Subject: [PATCH 6/8] feat(measurements): accept indoor CO2, temperature and
 humidity

Room climate from a home automation system gets three types of its own:
INDOOR_CO2 (ppm), INDOOR_TEMPERATURE (celsius, shown in Fahrenheit for
imperial readers) and INDOOR_HUMIDITY (percent). They arrive through the
existing ingest token (measurements:write, source EXTERNAL), sit in the
environment cluster beside daylight, and the daily rollup carries their
mean, low and high like any spot reading. They never mix with the body
temperatures or with the outdoor environment channels.

The Home Assistant page documents the three types, a rest_command that
sends a room as one request, a single-room automation, and an
importable blueprint (docs/integrations/blueprints) that skips sensors
reporting unknown or non-numeric states, converts Fahrenheit, and
stamps readings to the minute so a retried push is refused rather than
written twice.
---
 docs/api/openapi.yaml                         | 33 ++++++-
 .../blueprints/healthlog-room-climate.yaml    | 93 +++++++++++++++++++
 docs/integrations/home-assistant.md           | 80 ++++++++++++++++
 messages/de.json                              |  3 +
 messages/en.json                              |  3 +
 messages/es.json                              |  3 +
 messages/fr.json                              |  3 +
 messages/it.json                              |  3 +
 messages/ko.json                              |  3 +
 messages/nl.json                              |  3 +
 messages/pl.json                              |  3 +
 .../0433_indoor_climate_types/migration.sql   | 11 +++
 prisma/schema.prisma                          |  8 ++
 ...doctor-report-control-gating-guard.test.ts |  4 +-
 .../measurements/measurement-list-meta.ts     |  7 ++
 .../measurements/measurement-type-colors.ts   |  4 +
 .../__tests__/report-selection-panel.test.tsx |  2 +-
 .../measurement-type-enum-coverage.test.ts    |  6 +-
 src/lib/insights/chart-tokens.ts              |  4 +
 .../__tests__/apple-health-mapping.test.ts    |  4 +
 .../__tests__/indoor-climate.test.ts          | 61 ++++++++++++
 .../measurements/__tests__/unit-label.test.ts |  1 +
 src/lib/measurements/categories.ts            |  4 +
 src/lib/measurements/display-transform.ts     |  4 +
 src/lib/measurements/type-label-keys.ts       |  3 +
 src/lib/measurements/unit-map.ts              |  4 +
 src/lib/personal-records/pr-direction.ts      |  4 +
 .../__tests__/catalogue-guard.test.ts         |  4 +-
 src/lib/report-selection/catalogue.ts         |  6 ++
 .../fixtures/expected-measurement-loinc.json  | 18 ++++
 src/lib/signals/registry.ts                   | 72 ++++++++++++++
 src/lib/validations/measurement.ts            | 11 +++
 32 files changed, 463 insertions(+), 9 deletions(-)
 create mode 100644 docs/integrations/blueprints/healthlog-room-climate.yaml
 create mode 100644 prisma/migrations/0433_indoor_climate_types/migration.sql
 create mode 100644 src/lib/measurements/__tests__/indoor-climate.test.ts

diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml
index b390c93b3..35e6be480 100644
--- a/docs/api/openapi.yaml
+++ b/docs/api/openapi.yaml
@@ -4321,6 +4321,9 @@ paths:
               - MINDFUL_MINUTES
               - STATE_OF_MIND_VALENCE
               - AFIB_BURDEN
+              - INDOOR_CO2
+              - INDOOR_TEMPERATURE
+              - INDOOR_HUMIDITY
         - in: query
           name: from
           schema:
@@ -26000,7 +26003,7 @@ components:
               type: number
               const: 2
             leaves:
-              maxItems: 101
+              maxItems: 104
               type: array
               items:
                 type: string
@@ -26060,7 +26063,7 @@ components:
               type: number
               const: 2
             leaves:
-              maxItems: 101
+              maxItems: 104
               type: array
               items:
                 type: string
@@ -26901,6 +26904,9 @@ components:
             - MINDFUL_MINUTES
             - STATE_OF_MIND_VALENCE
             - AFIB_BURDEN
+            - INDOOR_CO2
+            - INDOOR_TEMPERATURE
+            - INDOOR_HUMIDITY
         value:
           type: number
         measuredAt:
@@ -28588,6 +28594,9 @@ components:
             - MINDFUL_MINUTES
             - STATE_OF_MIND_VALENCE
             - AFIB_BURDEN
+            - INDOOR_CO2
+            - INDOOR_TEMPERATURE
+            - INDOOR_HUMIDITY
         biomarkerId:
           type: string
           minLength: 1
@@ -29087,7 +29096,7 @@ components:
           type: number
           const: 2
         leaves:
-          maxItems: 101
+          maxItems: 104
           type: array
           items:
             type: string
@@ -30264,6 +30273,9 @@ components:
         - MINDFUL_MINUTES
         - STATE_OF_MIND_VALENCE
         - AFIB_BURDEN
+        - INDOOR_CO2
+        - INDOOR_TEMPERATURE
+        - INDOOR_HUMIDITY
       description: DB-stored measurement category. v1.4.23 added 7 Apple Health values (HRV, resting HR, active energy,
         flights, walking/running distance, VO2 max, body temperature).
     InsightsSettingsPutRequest:
@@ -39046,6 +39058,9 @@ components:
                   - STAND_HOURS
                   - MINDFUL_MINUTES
                   - STATE_OF_MIND_VALENCE
+                  - INDOOR_CO2
+                  - INDOOR_TEMPERATURE
+                  - INDOOR_HUMIDITY
                   - AFIB_BURDEN
               value:
                 type: number
@@ -39792,6 +39807,9 @@ components:
                             - STAND_HOURS
                             - MINDFUL_MINUTES
                             - STATE_OF_MIND_VALENCE
+                            - INDOOR_CO2
+                            - INDOOR_TEMPERATURE
+                            - INDOOR_HUMIDITY
                             - AFIB_BURDEN
                         - type: "null"
                     biomarkerName:
@@ -42273,6 +42291,9 @@ components:
                   - STAND_HOURS
                   - MINDFUL_MINUTES
                   - STATE_OF_MIND_VALENCE
+                  - INDOOR_CO2
+                  - INDOOR_TEMPERATURE
+                  - INDOOR_HUMIDITY
                   - AFIB_BURDEN
               dateKey:
                 type: string
@@ -43457,6 +43478,9 @@ components:
                       - STAND_HOURS
                       - MINDFUL_MINUTES
                       - STATE_OF_MIND_VALENCE
+                      - INDOOR_CO2
+                      - INDOOR_TEMPERATURE
+                      - INDOOR_HUMIDITY
                       - AFIB_BURDEN
                   - type: "null"
               intervalDays:
@@ -43675,6 +43699,9 @@ components:
                   - STAND_HOURS
                   - MINDFUL_MINUTES
                   - STATE_OF_MIND_VALENCE
+                  - INDOOR_CO2
+                  - INDOOR_TEMPERATURE
+                  - INDOOR_HUMIDITY
                   - AFIB_BURDEN
               metricSlot:
                 type:
diff --git a/docs/integrations/blueprints/healthlog-room-climate.yaml b/docs/integrations/blueprints/healthlog-room-climate.yaml
new file mode 100644
index 000000000..205ad0708
--- /dev/null
+++ b/docs/integrations/blueprints/healthlog-room-climate.yaml
@@ -0,0 +1,93 @@
+# Push a room's CO2, temperature and humidity to HealthLog every few minutes.
+#
+# 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
+  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. 15 is plenty for a daily picture.
+      default: 15
+      selector:
+        number:
+          min: 5
+          max: 60
+          step: 5
+          unit_of_measurement: min
+
+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 }}
+
+trigger:
+  - platform: time_pattern
+    minutes: "/5"
+
+condition:
+  - condition: template
+    value_template: >-
+      {{ now().minute % (interval_minutes | int(15)) == 0
+         and readings | count > 0 }}
+
+action:
+  - service: rest_command.healthlog_room_climate
+    data:
+      readings: "{{ readings }}"
diff --git a/docs/integrations/home-assistant.md b/docs/integrations/home-assistant.md
index 71d679ccc..d5423e650 100644
--- a/docs/integrations/home-assistant.md
+++ b/docs/integrations/home-assistant.md
@@ -149,6 +149,86 @@ Units are derived server-side from the type, so send the number in the unit
 above and do not send a `unit` field. The full enum is in
 `docs/api/openapi.yaml` under `MeasurementType`.
 
+## Room climate
+
+Indoor CO₂, temperature and humidity are their own types, kept apart from the
+body temperatures and from the outdoor weather the environment module pulls:
+
+| What the sensor reports | `type`               | Unit expected |
+| ----------------------- | -------------------- | ------------- |
+| Carbon dioxide          | `INDOOR_CO2`         | ppm           |
+| Room temperature        | `INDOOR_TEMPERATURE` | °C            |
+| Relative humidity       | `INDOOR_HUMIDITY`    | %             |
+
+Each push is kept as a reading, and the day's mean, low and high are what the
+charts and the daily views read, so a sensor sampled every 15 minutes gives a
+clear picture without anything further on your side. Pushing every few seconds
+adds rows, not detail.
+
+Add a second `rest_command` that takes a ready-made list of readings, so one
+request carries all three:
+
+```yaml
+rest_command:
+  healthlog_room_climate:
+    url: "https://healthlog.example.com/api/measurements"
+    method: POST
+    headers:
+      Authorization: !secret healthlog_token
+      Content-Type: "application/json"
+    payload: "{{ readings | to_json }}"
+```
+
+Then import the blueprint, 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 per room. It asks for the three
+sensors (each optional) and an interval. 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"
+    trigger:
+      - platform: 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 }}
+    condition:
+      - condition: template
+        value_template: "{{ readings | count > 0 }}"
+    action:
+      - service: rest_command.healthlog_room_climate
+        data:
+          readings: "{{ readings }}"
+```
+
+One request takes up to five readings, so a room is one call. Several rooms
+are several automations: the readings carry no room name, and two rooms pushed
+in the same minute collide on the 409 above. If you track more than one room,
+pick the one you sleep in; that is the one worth reading next to your sleep.
+
 ## Sending several readings at once
 
 A bare array writes up to five readings in one request — the shape to use for
diff --git a/messages/de.json b/messages/de.json
index 6b34c7498..9e4111523 100644
--- a/messages/de.json
+++ b/messages/de.json
@@ -917,6 +917,9 @@
     "typeMindfulMinutes": "Achtsamkeitsminuten",
     "typeStateOfMindValence": "Gemütszustand",
     "typeAfibBurden": "VHF-Last",
+    "typeIndoorCo2": "CO₂ (innen)",
+    "typeIndoorTemperature": "Raumtemperatur",
+    "typeIndoorHumidity": "Luftfeuchtigkeit (innen)",
     "durationReadAs": "Gelesen als {duration}",
     "durationHoursMinutes": "{hours} Std. {minutes} Min.",
     "durationHoursOnly": "{hours} Std.",
diff --git a/messages/en.json b/messages/en.json
index 60fe5c6be..6b5b799b4 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -917,6 +917,9 @@
     "typeMindfulMinutes": "Mindful minutes",
     "typeStateOfMindValence": "State of mind",
     "typeAfibBurden": "AFib burden",
+    "typeIndoorCo2": "Indoor CO₂",
+    "typeIndoorTemperature": "Indoor temperature",
+    "typeIndoorHumidity": "Indoor humidity",
     "durationReadAs": "Read as {duration}",
     "durationHoursMinutes": "{hours} h {minutes} min",
     "durationHoursOnly": "{hours} h",
diff --git a/messages/es.json b/messages/es.json
index fcfada1b1..f107f380c 100644
--- a/messages/es.json
+++ b/messages/es.json
@@ -917,6 +917,9 @@
     "typeMindfulMinutes": "Minutos de atención plena",
     "typeStateOfMindValence": "Estado de ánimo",
     "typeAfibBurden": "Carga de FA",
+    "typeIndoorCo2": "CO₂ interior",
+    "typeIndoorTemperature": "Temperatura interior",
+    "typeIndoorHumidity": "Humedad interior",
     "durationReadAs": "Se lee como {duration}",
     "durationHoursMinutes": "{hours} h {minutes} min",
     "durationHoursOnly": "{hours} h",
diff --git a/messages/fr.json b/messages/fr.json
index 843d5ebf6..2226dbcc2 100644
--- a/messages/fr.json
+++ b/messages/fr.json
@@ -917,6 +917,9 @@
     "typeMindfulMinutes": "Minutes de pleine conscience",
     "typeStateOfMindValence": "État d’esprit",
     "typeAfibBurden": "Charge de FA",
+    "typeIndoorCo2": "CO₂ intérieur",
+    "typeIndoorTemperature": "Température intérieure",
+    "typeIndoorHumidity": "Humidité intérieure",
     "durationReadAs": "Compris comme {duration}",
     "durationHoursMinutes": "{hours} h {minutes} min",
     "durationHoursOnly": "{hours} h",
diff --git a/messages/it.json b/messages/it.json
index 15d737a1c..570087490 100644
--- a/messages/it.json
+++ b/messages/it.json
@@ -917,6 +917,9 @@
     "typeMindfulMinutes": "Minuti di consapevolezza",
     "typeStateOfMindValence": "Stato d’animo",
     "typeAfibBurden": "Carico di FA",
+    "typeIndoorCo2": "CO₂ interna",
+    "typeIndoorTemperature": "Temperatura interna",
+    "typeIndoorHumidity": "Umidità interna",
     "durationReadAs": "Letto come {duration}",
     "durationHoursMinutes": "{hours} h {minutes} min",
     "durationHoursOnly": "{hours} h",
diff --git a/messages/ko.json b/messages/ko.json
index f23096369..92402257f 100644
--- a/messages/ko.json
+++ b/messages/ko.json
@@ -917,6 +917,9 @@
     "typeMindfulMinutes": "마음 챙기기 시간(분)",
     "typeStateOfMindValence": "마음 상태",
     "typeAfibBurden": "심방세동 부담",
+    "typeIndoorCo2": "실내 CO₂",
+    "typeIndoorTemperature": "실내 온도",
+    "typeIndoorHumidity": "실내 습도",
     "durationReadAs": "{duration}(으)로 읽었어요",
     "durationHoursMinutes": "{hours}시간 {minutes}분",
     "durationHoursOnly": "{hours}시간",
diff --git a/messages/nl.json b/messages/nl.json
index 3f6fabe35..af65f651a 100644
--- a/messages/nl.json
+++ b/messages/nl.json
@@ -917,6 +917,9 @@
     "typeMindfulMinutes": "Mindfulnessminuten",
     "typeStateOfMindValence": "Gemoedstoestand",
     "typeAfibBurden": "AF-belasting",
+    "typeIndoorCo2": "CO₂ binnen",
+    "typeIndoorTemperature": "Binnentemperatuur",
+    "typeIndoorHumidity": "Luchtvochtigheid binnen",
     "durationReadAs": "Gelezen als {duration}",
     "durationHoursMinutes": "{hours} u {minutes} min",
     "durationHoursOnly": "{hours} u",
diff --git a/messages/pl.json b/messages/pl.json
index 66982c68e..3f0e4089d 100644
--- a/messages/pl.json
+++ b/messages/pl.json
@@ -917,6 +917,9 @@
     "typeMindfulMinutes": "Minuty uważności",
     "typeStateOfMindValence": "Stan umysłu",
     "typeAfibBurden": "Obciążenie AF",
+    "typeIndoorCo2": "CO₂ w pomieszczeniu",
+    "typeIndoorTemperature": "Temperatura w pomieszczeniu",
+    "typeIndoorHumidity": "Wilgotność w pomieszczeniu",
     "durationReadAs": "Odczytano jako {duration}",
     "durationHoursMinutes": "{hours} godz. {minutes} min",
     "durationHoursOnly": "{hours} godz.",
diff --git a/prisma/migrations/0433_indoor_climate_types/migration.sql b/prisma/migrations/0433_indoor_climate_types/migration.sql
new file mode 100644
index 000000000..c07e7c564
--- /dev/null
+++ b/prisma/migrations/0433_indoor_climate_types/migration.sql
@@ -0,0 +1,11 @@
+-- Extend `measurement_type` with room-climate readings pushed through the
+-- ingest token (source EXTERNAL), for example by a Home Assistant
+-- automation: indoor CO2 (ppm), indoor temperature (celsius) and indoor
+-- relative humidity (percent).
+--
+-- Purely additive. IF NOT EXISTS keeps a replay harmless; enum values cannot
+-- be dropped in PostgreSQL, so there is no down path.
+
+ALTER TYPE "measurement_type" ADD VALUE IF NOT EXISTS 'INDOOR_CO2';
+ALTER TYPE "measurement_type" ADD VALUE IF NOT EXISTS 'INDOOR_TEMPERATURE';
+ALTER TYPE "measurement_type" ADD VALUE IF NOT EXISTS 'INDOOR_HUMIDITY';
diff --git a/prisma/schema.prisma b/prisma/schema.prisma
index 82129aac4..d6eeead54 100644
--- a/prisma/schema.prisma
+++ b/prisma/schema.prisma
@@ -1718,6 +1718,14 @@ enum MeasurementType {
   STAND_HOURS // count — HealthKit `HKCategoryTypeIdentifierAppleStandHour`. One row per hour in which the person stood (`stood` = 1; an `idle` hour is not stored); cumulative, daily SUM gives the stand-ring hours.
   MINDFUL_MINUTES // minutes — HealthKit `HKCategoryTypeIdentifierMindfulSession`. Session length from the sample's own dates; cumulative, daily SUM.
   STATE_OF_MIND_VALENCE // valence (−1..1) — HealthKit `HKStateOfMind.valence` (iOS 18+). How pleasant the logged emotion or mood felt, from very unpleasant (−1) to very pleasant (1). A self-report, not a measurement.
+  // ── v1.44 — room climate from a home automation system ──
+  // Pushed through the ingest token (`measurements:write`, source EXTERNAL),
+  // e.g. by a Home Assistant automation. Spot readings: the daily rollup
+  // carries mean, min and max. Indoor, so never mixed with the outdoor
+  // environment channels.
+  INDOOR_CO2 // ppm — indoor carbon dioxide concentration.
+  INDOOR_TEMPERATURE // celsius — indoor air temperature. Distinct from every body temperature type.
+  INDOOR_HUMIDITY // percent (0–100) — indoor relative humidity.
   AFIB_BURDEN // percent (0–100, scaled ×100 from Apple's 0..1 fraction) — HealthKit `atrialFibrillationBurden` (iOS 16+, AFib History). The share of time the watch estimated in AFib over a week. AWARENESS ONLY — never a HealthLog diagnosis.
 
   @@map("measurement_type")
diff --git a/src/__tests__/doctor-report-control-gating-guard.test.ts b/src/__tests__/doctor-report-control-gating-guard.test.ts
index 1c06583ae..b0763a13f 100644
--- a/src/__tests__/doctor-report-control-gating-guard.test.ts
+++ b/src/__tests__/doctor-report-control-gating-guard.test.ts
@@ -74,8 +74,8 @@ describe("report scope gating — structural guard", () => {
   it("reads a plausible catalogue", () => {
     // Sanity floor: a silently degraded catalogue would pass everything below
     // vacuously.
-    expect(ALL_LEAF_IDS.length).toBe(101);
-    expect(Object.keys(MEASUREMENT_LEAF_GROUP)).toHaveLength(83);
+    expect(ALL_LEAF_IDS.length).toBe(104);
+    expect(Object.keys(MEASUREMENT_LEAF_GROUP)).toHaveLength(86);
     expect(Object.keys(STRUCTURED_LEAF_GROUP)).toHaveLength(18);
   });
 
diff --git a/src/components/measurements/measurement-list-meta.ts b/src/components/measurements/measurement-list-meta.ts
index 5be62c111..e0d6a8125 100644
--- a/src/components/measurements/measurement-list-meta.ts
+++ b/src/components/measurements/measurement-list-meta.ts
@@ -139,6 +139,9 @@ export const MEASUREMENT_TYPE_LABEL_KEYS: Record<string, string> = {
   MINDFUL_MINUTES: "measurements.typeMindfulMinutes",
   STATE_OF_MIND_VALENCE: "measurements.typeStateOfMindValence",
   AFIB_BURDEN: "measurements.typeAfibBurden",
+  INDOOR_CO2: "measurements.typeIndoorCo2",
+  INDOOR_TEMPERATURE: "measurements.typeIndoorTemperature",
+  INDOOR_HUMIDITY: "measurements.typeIndoorHumidity",
 };
 
 export const MEASUREMENT_TYPE_ICONS: Record<string, LucideIcon> = {
@@ -282,6 +285,10 @@ export const MEASUREMENT_TYPE_ICONS: Record<string, LucideIcon> = {
   MINDFUL_MINUTES: Wind,
   STATE_OF_MIND_VALENCE: Gauge,
   AFIB_BURDEN: HeartPulse,
+  // Room climate: air, warmth, moisture.
+  INDOOR_CO2: Wind,
+  INDOOR_TEMPERATURE: Thermometer,
+  INDOOR_HUMIDITY: Droplets,
 };
 
 // The colour map lives in its own icon-free module so a surface that only
diff --git a/src/components/measurements/measurement-type-colors.ts b/src/components/measurements/measurement-type-colors.ts
index 76a7d6803..98409b66f 100644
--- a/src/components/measurements/measurement-type-colors.ts
+++ b/src/components/measurements/measurement-type-colors.ts
@@ -138,4 +138,8 @@ export const MEASUREMENT_TYPE_COLORS: Record<string, string> = {
   MINDFUL_MINUTES: "bg-chart-2/10 text-chart-2 dark:bg-chart-2/20",
   STATE_OF_MIND_VALENCE: "bg-chart-1/10 text-chart-1 dark:bg-chart-1/20",
   AFIB_BURDEN: "bg-chart-3/10 text-chart-3 dark:bg-chart-3/20",
+  // Room climate takes the environment family of daylight (chart-2).
+  INDOOR_CO2: "bg-chart-2/10 text-chart-2 dark:bg-chart-2/20",
+  INDOOR_TEMPERATURE: "bg-chart-2/10 text-chart-2 dark:bg-chart-2/20",
+  INDOOR_HUMIDITY: "bg-chart-2/10 text-chart-2 dark:bg-chart-2/20",
 };
diff --git a/src/components/settings/__tests__/report-selection-panel.test.tsx b/src/components/settings/__tests__/report-selection-panel.test.tsx
index b3c162515..ca32f7ac3 100644
--- a/src/components/settings/__tests__/report-selection-panel.test.tsx
+++ b/src/components/settings/__tests__/report-selection-panel.test.tsx
@@ -198,7 +198,7 @@ describe("<HealthRecordExportPanel> — the first run", () => {
     expect(groupChip(html, "activity")).toBe("0/11");
     expect(groupChip(html, "sleepRecovery")).toBe("0/16");
     expect(groupChip(html, "mobility")).toBe("0/11");
-    expect(groupChip(html, "environment")).toBe("0/4");
+    expect(groupChip(html, "environment")).toBe("0/7");
   });
 
   it("disables Generate while the scope is empty, and says what to do", () => {
diff --git a/src/lib/__tests__/measurement-type-enum-coverage.test.ts b/src/lib/__tests__/measurement-type-enum-coverage.test.ts
index 5ef5738b7..79c4093c6 100644
--- a/src/lib/__tests__/measurement-type-enum-coverage.test.ts
+++ b/src/lib/__tests__/measurement-type-enum-coverage.test.ts
@@ -120,10 +120,14 @@ const EXPECTED_TYPES = [
   "MINDFUL_MINUTES",
   "STATE_OF_MIND_VALENCE",
   "AFIB_BURDEN",
+  // ── v1.44 — room climate pushed through the ingest token ──
+  "INDOOR_CO2",
+  "INDOOR_TEMPERATURE",
+  "INDOOR_HUMIDITY",
 ] as const;
 
 describe("measurementTypeEnum coverage", () => {
-  it("exposes the 83 canonical measurement types", () => {
+  it("exposes the 86 canonical measurement types", () => {
     expect([...measurementTypeEnum.options].sort()).toEqual(
       [...EXPECTED_TYPES].sort(),
     );
diff --git a/src/lib/insights/chart-tokens.ts b/src/lib/insights/chart-tokens.ts
index 94df12acc..3b0fef932 100644
--- a/src/lib/insights/chart-tokens.ts
+++ b/src/lib/insights/chart-tokens.ts
@@ -145,6 +145,10 @@ export const ALLOWED_CHART_TOKENS = [
   "metric:MINDFUL_MINUTES",
   "metric:STATE_OF_MIND_VALENCE",
   "metric:AFIB_BURDEN",
+  // v1.44 — room climate from the ingest token.
+  "metric:INDOOR_CO2",
+  "metric:INDOOR_TEMPERATURE",
+  "metric:INDOOR_HUMIDITY",
   "metric:GRIP_STRENGTH",
   "metric:PAIN_NRS",
   "metric:WAIST_CIRCUMFERENCE",
diff --git a/src/lib/measurements/__tests__/apple-health-mapping.test.ts b/src/lib/measurements/__tests__/apple-health-mapping.test.ts
index 86afc5d32..b1ffdc978 100644
--- a/src/lib/measurements/__tests__/apple-health-mapping.test.ts
+++ b/src/lib/measurements/__tests__/apple-health-mapping.test.ts
@@ -23,6 +23,10 @@ import type { MeasurementType } from "@/generated/prisma/client";
  * silently failing the assertion.
  */
 const MEASUREMENT_TYPES_WITHOUT_HK_COUNTERPART = new Set<MeasurementType>([
+  // v1.44 — room climate arrives through the ingest token, not HealthKit.
+  "INDOOR_CO2",
+  "INDOOR_TEMPERATURE",
+  "INDOOR_HUMIDITY",
   // Withings-only metrics (no HK identifier ships any of these as a
   // first-class quantity — Apple delegates body-composition tail to
   // third-party devices via the BodyMass/BodyFat pair).
diff --git a/src/lib/measurements/__tests__/indoor-climate.test.ts b/src/lib/measurements/__tests__/indoor-climate.test.ts
new file mode 100644
index 000000000..a7ebc3d69
--- /dev/null
+++ b/src/lib/measurements/__tests__/indoor-climate.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+
+import { getUnitForType } from "@/lib/measurements/unit-map";
+import { getDisplayTransform } from "@/lib/measurements/display-transform";
+import { getMeasurementCategory } from "@/lib/measurements/categories";
+import { createMeasurementSchema } from "@/lib/validations/measurement";
+
+/**
+ * Room climate as a Home Assistant automation pushes it: the documented
+ * three-reading array through the ingest token, no source, no unit.
+ */
+const at = new Date(Date.now() - 60_000).toISOString();
+
+describe("indoor climate types", () => {
+  it("accepts the documented push shape for all three", () => {
+    for (const [type, value] of [
+      ["INDOOR_CO2", 812],
+      ["INDOOR_TEMPERATURE", 21.4],
+      ["INDOOR_HUMIDITY", 47],
+    ] as const) {
+      expect(
+        createMeasurementSchema.safeParse({ type, value, measuredAt: at })
+          .success,
+        type,
+      ).toBe(true);
+    }
+  });
+
+  it("refuses a reading no room produces", () => {
+    for (const [type, value] of [
+      ["INDOOR_CO2", 12_000],
+      ["INDOOR_TEMPERATURE", 75],
+      ["INDOOR_HUMIDITY", 101],
+    ] as const) {
+      expect(
+        createMeasurementSchema.safeParse({ type, value, measuredAt: at })
+          .success,
+        type,
+      ).toBe(false);
+    }
+  });
+
+  it("stores canonical units and shows temperature in the person's scale", () => {
+    expect(getUnitForType("INDOOR_CO2")).toBe("ppm");
+    expect(getUnitForType("INDOOR_TEMPERATURE")).toBe("celsius");
+    expect(getUnitForType("INDOOR_HUMIDITY")).toBe("%");
+    expect(
+      getDisplayTransform("INDOOR_TEMPERATURE", "imperial").displayUnit,
+    ).toBe("°F");
+  });
+
+  it("files all three under the environment cluster", () => {
+    for (const type of [
+      "INDOOR_CO2",
+      "INDOOR_TEMPERATURE",
+      "INDOOR_HUMIDITY",
+    ] as const) {
+      expect(getMeasurementCategory(type)).toBe("environment");
+    }
+  });
+});
diff --git a/src/lib/measurements/__tests__/unit-label.test.ts b/src/lib/measurements/__tests__/unit-label.test.ts
index 3c07ae748..dfd947eba 100644
--- a/src/lib/measurements/__tests__/unit-label.test.ts
+++ b/src/lib/measurements/__tests__/unit-label.test.ts
@@ -67,6 +67,7 @@ const SHARED_SYMBOLS: ReadonlySet<string> = new Set([
   "°C",
   "°F",
   "dBA",
+  "ppm",
   "mL/(kg·min)",
   "kg/m²",
   "mL",
diff --git a/src/lib/measurements/categories.ts b/src/lib/measurements/categories.ts
index 0bff7c895..0620110b2 100644
--- a/src/lib/measurements/categories.ts
+++ b/src/lib/measurements/categories.ts
@@ -230,6 +230,10 @@ export const MEASUREMENT_CATEGORIES: ReadonlyMap<
   ["STATE_OF_MIND_VALENCE", "scores"],
   // AFib burden joins the rhythm notifications on the cardiovascular surface.
   ["AFIB_BURDEN", "cardiovascular"],
+  // ── v1.44 — room climate joins daylight in the environment cluster ──
+  ["INDOOR_CO2", "environment"],
+  ["INDOOR_TEMPERATURE", "environment"],
+  ["INDOOR_HUMIDITY", "environment"],
 ]);
 
 /**
diff --git a/src/lib/measurements/display-transform.ts b/src/lib/measurements/display-transform.ts
index 03a4382cd..2dc71e322 100644
--- a/src/lib/measurements/display-transform.ts
+++ b/src/lib/measurements/display-transform.ts
@@ -179,6 +179,8 @@ const TRANSFORMS: Partial<
   BODY_TEMPERATURE: TEMPERATURE_TRANSFORM,
   SKIN_TEMPERATURE: TEMPERATURE_TRANSFORM,
   WRIST_TEMPERATURE: TEMPERATURE_TRANSFORM,
+  // v1.44 — room temperature reads in the person's own scale too.
+  INDOOR_TEMPERATURE: TEMPERATURE_TRANSFORM,
   // A signed baseline DEVIATION (Δ°C) — the °F imperial branch scales by
   // 1.8 but carries NO +32 offset. A one-degree-Celsius deviation is a
   // 1.8-degree-Fahrenheit deviation, not a 33.8 °F reading.
@@ -338,6 +340,8 @@ const INTEGER_DISPLAY_TYPES: ReadonlySet<string> = new Set([
   "STAND_MINUTES",
   "STAND_HOURS",
   "MINDFUL_MINUTES",
+  // CO2 sensors report whole ppm.
+  "INDOOR_CO2",
 ]);
 
 /**
diff --git a/src/lib/measurements/type-label-keys.ts b/src/lib/measurements/type-label-keys.ts
index 46a61d0a4..12e3cf186 100644
--- a/src/lib/measurements/type-label-keys.ts
+++ b/src/lib/measurements/type-label-keys.ts
@@ -110,6 +110,9 @@ export const MEASUREMENT_TYPE_LABEL_KEYS: Record<MeasurementType, string> = {
   MINDFUL_MINUTES: "measurements.typeMindfulMinutes",
   STATE_OF_MIND_VALENCE: "measurements.typeStateOfMindValence",
   AFIB_BURDEN: "measurements.typeAfibBurden",
+  INDOOR_CO2: "measurements.typeIndoorCo2",
+  INDOOR_TEMPERATURE: "measurements.typeIndoorTemperature",
+  INDOOR_HUMIDITY: "measurements.typeIndoorHumidity",
   GRIP_STRENGTH: "measurements.typeGripStrength",
   PAIN_NRS: "measurements.typePainNrs",
   WAIST_CIRCUMFERENCE: "measurements.typeWaistCircumference",
diff --git a/src/lib/measurements/unit-map.ts b/src/lib/measurements/unit-map.ts
index 71761e35c..943a0fade 100644
--- a/src/lib/measurements/unit-map.ts
+++ b/src/lib/measurements/unit-map.ts
@@ -166,6 +166,10 @@ const unitMap: Record<string, string> = {
   STATE_OF_MIND_VALENCE: "valence",
   // Percent of the week after the ×100 scaling.
   AFIB_BURDEN: "%",
+  // ── v1.44 — room climate ──
+  INDOOR_CO2: "ppm",
+  INDOOR_TEMPERATURE: "celsius",
+  INDOOR_HUMIDITY: "%",
 };
 
 export function getUnitForType(type: string): string {
diff --git a/src/lib/personal-records/pr-direction.ts b/src/lib/personal-records/pr-direction.ts
index dc8ecf4ad..f2ff28f9a 100644
--- a/src/lib/personal-records/pr-direction.ts
+++ b/src/lib/personal-records/pr-direction.ts
@@ -217,6 +217,10 @@ export function getPRDirection(
     // Neither is a goal axis a record could celebrate.
     case "AFIB_BURDEN":
     case "STATE_OF_MIND_VALENCE":
+    // v1.44 — room climate describes a room, not a person's effort.
+    case "INDOOR_CO2":
+    case "INDOOR_TEMPERATURE":
+    case "INDOOR_HUMIDITY":
     case "HIGH_HEART_RATE_EVENT":
     case "LOW_HEART_RATE_EVENT":
     case "WALKING_STEADINESS_EVENT":
diff --git a/src/lib/report-selection/__tests__/catalogue-guard.test.ts b/src/lib/report-selection/__tests__/catalogue-guard.test.ts
index 4e3ba4439..593bec93c 100644
--- a/src/lib/report-selection/__tests__/catalogue-guard.test.ts
+++ b/src/lib/report-selection/__tests__/catalogue-guard.test.ts
@@ -53,9 +53,9 @@ function resolves(key: string): boolean {
 
 describe("report selection catalogue", () => {
   it("carries every measurement type and every structured leaf", () => {
-    expect(MEASUREMENT_LEAF_IDS).toHaveLength(83);
+    expect(MEASUREMENT_LEAF_IDS).toHaveLength(86);
     expect(STRUCTURED_LEAF_IDS).toHaveLength(18);
-    expect(ALL_LEAF_IDS).toHaveLength(101);
+    expect(ALL_LEAF_IDS).toHaveLength(104);
   });
 
   it("resolves a label for every leaf", () => {
diff --git a/src/lib/report-selection/catalogue.ts b/src/lib/report-selection/catalogue.ts
index f53f1287a..de1683fef 100644
--- a/src/lib/report-selection/catalogue.ts
+++ b/src/lib/report-selection/catalogue.ts
@@ -184,6 +184,9 @@ export const MEASUREMENT_LEAF_GROUP: Record<MeasurementType, ReportGroupId> = {
   AUDIO_EXPOSURE_HEADPHONE: "environment",
   AUDIO_EXPOSURE_EVENT: "environment",
   TIME_IN_DAYLIGHT: "environment",
+  INDOOR_CO2: "environment",
+  INDOOR_TEMPERATURE: "environment",
+  INDOOR_HUMIDITY: "environment",
 
   // ── glucose ──
   BLOOD_GLUCOSE: "glucose",
@@ -311,6 +314,9 @@ export const LEAF_MODULE: Partial<Record<ReportLeafId, ModuleKey>> = {
   AUDIO_EXPOSURE_HEADPHONE: "environment",
   AUDIO_EXPOSURE_EVENT: "environment",
   TIME_IN_DAYLIGHT: "environment",
+  INDOOR_CO2: "environment",
+  INDOOR_TEMPERATURE: "environment",
+  INDOOR_HUMIDITY: "environment",
   // Glucose: the raw series and the derived panel.
   BLOOD_GLUCOSE: "glucose",
   GLUCOSE_PANEL: "glucose",
diff --git a/src/lib/signals/__tests__/fixtures/expected-measurement-loinc.json b/src/lib/signals/__tests__/fixtures/expected-measurement-loinc.json
index 905fa945d..c55d1200c 100644
--- a/src/lib/signals/__tests__/fixtures/expected-measurement-loinc.json
+++ b/src/lib/signals/__tests__/fixtures/expected-measurement-loinc.json
@@ -298,5 +298,23 @@
     "display": "Atrial fibrillation burden",
     "unit": "%",
     "category": "vital-signs"
+  },
+  "INDOOR_CO2": {
+    "loinc": null,
+    "display": "Indoor carbon dioxide",
+    "unit": "[ppm]",
+    "category": "activity"
+  },
+  "INDOOR_TEMPERATURE": {
+    "loinc": null,
+    "display": "Indoor air temperature",
+    "unit": "Cel",
+    "category": "activity"
+  },
+  "INDOOR_HUMIDITY": {
+    "loinc": null,
+    "display": "Indoor relative humidity",
+    "unit": "%",
+    "category": "activity"
   }
 }
diff --git a/src/lib/signals/registry.ts b/src/lib/signals/registry.ts
index d889362a8..cf467c8be 100644
--- a/src/lib/signals/registry.ts
+++ b/src/lib/signals/registry.ts
@@ -1914,6 +1914,78 @@ export const SIGNALS: Record<string, SignalDefinition> = {
       category: "vital-signs",
     },
   },
+  // ── v1.44 — room climate pushed through the ingest token ──
+  // Bands are the usual comfort guidance (CO2 under 1000 ppm as the long-
+  // standing ventilation threshold, 18–24 °C, 40–60 % RH); placement only.
+  INDOOR_CO2: {
+    key: "INDOOR_CO2",
+    kind: "measurement",
+    source: { measurementType: "INDOOR_CO2" },
+    displayName: "Indoor CO2",
+    unit: "ppm",
+    direction: "target-band",
+    archetype: "environmental-exposure",
+    normalRange: { low: 400, high: 1000 },
+    surfaces: {
+      detailPage: false,
+      correlationEligible: false,
+      coachSnapshot: false,
+      mcp: false,
+    },
+    fhir: {
+      // A room reading, not a body observation; no LOINC concept applies.
+      loinc: null,
+      display: "Indoor carbon dioxide",
+      unit: "[ppm]",
+      category: "activity",
+    },
+  },
+  INDOOR_TEMPERATURE: {
+    key: "INDOOR_TEMPERATURE",
+    kind: "measurement",
+    source: { measurementType: "INDOOR_TEMPERATURE" },
+    displayName: "Indoor temperature",
+    unit: "°C",
+    direction: "target-band",
+    archetype: "environmental-exposure",
+    normalRange: { low: 18, high: 24 },
+    surfaces: {
+      detailPage: false,
+      correlationEligible: false,
+      coachSnapshot: false,
+      mcp: false,
+    },
+    fhir: {
+      // A room reading, not a body observation; no LOINC concept applies.
+      loinc: null,
+      display: "Indoor air temperature",
+      unit: "Cel",
+      category: "activity",
+    },
+  },
+  INDOOR_HUMIDITY: {
+    key: "INDOOR_HUMIDITY",
+    kind: "measurement",
+    source: { measurementType: "INDOOR_HUMIDITY" },
+    displayName: "Indoor humidity",
+    unit: "%",
+    direction: "target-band",
+    archetype: "environmental-exposure",
+    normalRange: { low: 40, high: 60 },
+    surfaces: {
+      detailPage: false,
+      correlationEligible: false,
+      coachSnapshot: false,
+      mcp: false,
+    },
+    fhir: {
+      // A room reading, not a body observation; no LOINC concept applies.
+      loinc: null,
+      display: "Indoor relative humidity",
+      unit: "%",
+      category: "activity",
+    },
+  },
 };
 
 /** Type guard: narrow an arbitrary string to a registered signal key. */
diff --git a/src/lib/validations/measurement.ts b/src/lib/validations/measurement.ts
index 7134461ac..fa6a5692b 100644
--- a/src/lib/validations/measurement.ts
+++ b/src/lib/validations/measurement.ts
@@ -153,6 +153,10 @@ export const measurementTypeEnum = z.enum([
   "MINDFUL_MINUTES",
   "STATE_OF_MIND_VALENCE",
   "AFIB_BURDEN",
+  // ── v1.44 — room climate pushed through the ingest token ──
+  "INDOOR_CO2",
+  "INDOOR_TEMPERATURE",
+  "INDOOR_HUMIDITY",
 ]);
 
 /**
@@ -460,6 +464,13 @@ export const VALUE_RANGES: Record<string, { min: number; max: number }> = {
   // AFib burden as a percent of the week, after the ×100 scaling. A client
   // that already scaled sends 2 for 2 %, which lands at 200 and is refused.
   AFIB_BURDEN: { min: 0, max: 100 },
+  // ── v1.44 — room climate. CO2: outdoor air sits near 420 ppm and a closed
+  // bedroom can pass 3000; consumer sensors top out at 5000–10000 ppm.
+  INDOOR_CO2: { min: 0, max: 10000 },
+  // Indoor air °C: a cold cellar to an overheated attic.
+  INDOOR_TEMPERATURE: { min: -20, max: 60 },
+  // Relative humidity, percent.
+  INDOOR_HUMIDITY: { min: 0, max: 100 },
   // Grip strength kg — a child can read in the single digits, an elite athlete
   // tops ~90 kg; 120 is a generous ceiling that still rejects sensor noise.
   GRIP_STRENGTH: { min: 0, max: 120 },

From 846b0e5df006a9b827421f91073dd57889fe78fc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Wed, 21 Oct 2026 20:42:06 +0200
Subject: [PATCH 7/8] perf(measurements): insert fresh batch samples set-based;
 answer health while starting

POST /api/measurements/batch ran one interactive reconciler transaction
per fresh sample: a savepoint, three advisory locks, two candidate reads
and the insert, about ten round trips. A 500-entry upload of new samples
was 500 of those, the 2 to 15 second outliers. Fresh samples now land
through INSERT ... ON CONFLICT DO NOTHING under the same per-account
advisory lock. Both measurement identities are full unique indexes, so
the statement inserts exactly what the reconciler would have inserted,
and every skipped row still goes through the reconciler for its own
verdict. Only rows whose external and natural keys each occur once in
the batch are buffered, and the buffer is flushed before any other row
is reconciled, so the order of effects stays the sequential one. The
contract and every per-entry status are unchanged; a golden test runs
each batch through both paths against the same table.

/api/health took seconds after a start because register() awaited the
whole pg-boss worker start (queues, schedules, boot discovery) before
the server took a request. The worker, or a web process's producer, now
starts in the background after the blocking boot checks; the probe
answers at once with reason "starting" until it is up, and gives the
database two seconds before calling it not answering.
---
 docs/api/openapi.yaml                         |  19 +-
 ...asurement-write-plausibility-guard.test.ts |   4 +
 .../measurement-write-tail-guard.test.ts      |   1 +
 src/app/api/health/__tests__/route.test.ts    |  50 +++
 src/app/api/health/route.ts                   |  55 +++-
 .../__tests__/duplicate-prefilter.test.ts     | 164 +++++++++-
 src/app/api/measurements/batch/route.ts       | 303 +++++++++++++-----
 src/instrumentation.ts                        |  99 +++---
 src/lib/boot/startup-state.ts                 |  23 ++
 .../reconcile-external-measurement.ts         |  10 +-
 src/lib/openapi/routes/health.ts              |  15 +-
 .../measurements-batch-perf.test.ts           | 255 +++++++++++++++
 12 files changed, 835 insertions(+), 163 deletions(-)
 create mode 100644 src/lib/boot/startup-state.ts
 create mode 100644 tests/integration/measurements-batch-perf.test.ts

diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml
index 35e6be480..932209f27 100644
--- a/docs/api/openapi.yaml
+++ b/docs/api/openapi.yaml
@@ -22852,8 +22852,9 @@ paths:
                   - $ref: "#/components/schemas/HealthAdminResponse"
                   - $ref: "#/components/schemas/HealthPublicResponse"
         "503":
-          description: "Degraded — the database did not answer, or a role this process runs is not up. Same body shape as the 200,
-            with `status: \"degraded\"`. A restart loop reports this rather than failing to answer, so a monitor can
+          description: "Degraded — the database did not answer within two seconds, or a role this process runs is not up. Same
+            body shape as the 200, with `status: \"degraded\"`, and `reason: \"starting\"` while the background role is
+            still coming up after a start. A restart loop reports this rather than failing to answer, so a monitor can
             tell 'starting' from 'gone'."
           content:
             application/json:
@@ -84210,14 +84211,18 @@ components:
         when the process serves web, and the worker loop is running when the process runs the worker. `degraded` on any
         of those failing."
     HealthReason:
-      description: "Present only when the process refuses to serve for a reason a person has to fix.
-        `encryption_key_mismatch`: the configured encryption key cannot open the data in this database (checked at
-        boot). Every other route then answers 503 with `meta.errorCode` `encryption.key_mismatch`, and background jobs
-        are not started. Fix: restore the original key, point the server at the matching database, or start with an
-        empty one; then restart."
+      description: "Why a `degraded` process is degraded, when it is something other than a component failure.
+        `encryption_key_mismatch`: the process refuses to serve for a reason a person has to fix; the configured
+        encryption key cannot open the data in this database (checked at boot). Every other route then answers 503 with
+        `meta.errorCode` `encryption.key_mismatch`, and background jobs are not started. Fix: restore the original key,
+        point the server at the matching database, or start with an empty one; then restart. `starting`: the database
+        answers but the background role (the pg-boss worker, or the producer of a web-only process) is still coming up
+        after a start. Transient; nothing to fix, poll again. The probe answers at once while it lasts rather than
+        waiting for the start to finish."
       type: string
       enum:
         - encryption_key_mismatch
+        - starting
     HealthPublicResponse:
       type: object
       properties:
diff --git a/src/__tests__/measurement-write-plausibility-guard.test.ts b/src/__tests__/measurement-write-plausibility-guard.test.ts
index 9b3cf83e0..4ff24ab5c 100644
--- a/src/__tests__/measurement-write-plausibility-guard.test.ts
+++ b/src/__tests__/measurement-write-plausibility-guard.test.ts
@@ -73,6 +73,10 @@ const WRITERS: Record<string, Disposition> = {
     validatedIn: "lib/validations/measurement.ts",
   },
   "app/api/import/route.ts": { kind: "validator" },
+  // v1.44 — the set-based insert writes rows that already passed the
+  // route's `validateMeasurementRange` per entry; everything else goes
+  // through the reconciler, which gates itself.
+  "app/api/measurements/batch/route.ts": { kind: "validator" },
   "lib/mcp/writes.ts": { kind: "validator" },
   "lib/measurements/create-from-telegram.ts": { kind: "validator" },
   "lib/measurements/import-apple-health-export.ts": { kind: "validator" },
diff --git a/src/__tests__/measurement-write-tail-guard.test.ts b/src/__tests__/measurement-write-tail-guard.test.ts
index da045a6ed..6242c8a5b 100644
--- a/src/__tests__/measurement-write-tail-guard.test.ts
+++ b/src/__tests__/measurement-write-tail-guard.test.ts
@@ -44,6 +44,7 @@ const WRITE_SITES: Record<string, string> = {
   "app/api/measurements/bulk-delete/route.ts": TAIL,
   "app/api/measurements/by-external-ids/route.ts": TAIL,
   "app/api/measurements/restore/route.ts": TAIL,
+  "app/api/measurements/batch/route.ts": TAIL,
   "app/api/measurements/route.ts": TAIL,
   "app/api/mental-health/assessments/route.ts": TAIL,
   "lib/insights/score-row.ts": TAIL,
diff --git a/src/app/api/health/__tests__/route.test.ts b/src/app/api/health/__tests__/route.test.ts
index d3865a248..9c2ce8a16 100644
--- a/src/app/api/health/__tests__/route.test.ts
+++ b/src/app/api/health/__tests__/route.test.ts
@@ -163,3 +163,53 @@ describe("GET /api/health under ENCRYPTION_KEY_CHECK=warn", () => {
     }
   });
 });
+
+describe("GET /api/health while the background role starts", () => {
+  it("says `starting` at once, and `ok` when the role is up", async () => {
+    const { markStartup } = await import("@/lib/boot/startup-state");
+    vi.stubEnv("HEALTHLOG_PROCESS_TYPE", "web");
+    markStartup("starting");
+    try {
+      const starting = await health();
+      expect(starting.response.status).toBe(503);
+      expect(starting.body).toEqual({ status: "degraded", reason: "starting" });
+
+      getGlobalBoss.mockReturnValue({});
+      markStartup("ready");
+      const ready = await health();
+      expect(ready.response.status).toBe(200);
+      expect(ready.body).toEqual({ status: "ok" });
+    } finally {
+      markStartup("ready");
+    }
+  });
+
+  it("does not call a failed start `starting`", async () => {
+    const { markStartup } = await import("@/lib/boot/startup-state");
+    vi.stubEnv("HEALTHLOG_PROCESS_TYPE", "web");
+    markStartup("failed");
+    try {
+      const { response, body } = await health();
+      expect(response.status).toBe(503);
+      expect(body).toEqual({ status: "degraded" });
+    } finally {
+      markStartup("ready");
+    }
+  });
+
+  it("does not wait on a database that does not answer", async () => {
+    vi.useFakeTimers();
+    try {
+      vi.stubEnv("HEALTHLOG_PROCESS_TYPE", "web");
+      getGlobalBoss.mockReturnValue({});
+      queryRaw.mockImplementation(() => new Promise(() => undefined));
+      const pending = health();
+      await vi.advanceTimersByTimeAsync(2_000);
+      const { response, body } = await pending;
+      expect(response.status).toBe(503);
+      expect(body).toEqual({ status: "degraded" });
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
diff --git a/src/app/api/health/route.ts b/src/app/api/health/route.ts
index 2e7764036..43b8ff1f8 100644
--- a/src/app/api/health/route.ts
+++ b/src/app/api/health/route.ts
@@ -11,19 +11,41 @@ import {
   isKeyMismatch,
   KEY_MISMATCH_HEALTH_REASON,
 } from "@/lib/boot/key-mismatch-state";
+import { startupPhase } from "@/lib/boot/startup-state";
+
+/**
+ * How long the probe waits for `SELECT 1`. During a boot storm the pool can
+ * be saturated by the worker's start-up work; a probe that waits its turn
+ * held a monitor for seconds. Past this the database counts as not answering
+ * and the probe says `degraded` at once.
+ */
+const DB_PROBE_TIMEOUT_MS = 2_000;
+
+/** Reported while the background role is still coming up. */
+const STARTING_HEALTH_REASON = "starting";
+
+async function probeDatabase(): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      prisma.$queryRaw`SELECT 1`.then(() => true),
+      new Promise<boolean>((resolve) => {
+        timer = setTimeout(() => resolve(false), DB_PROBE_TIMEOUT_MS);
+      }),
+    ]);
+  } catch {
+    return false;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
 
 export const dynamic = "force-dynamic";
 
 export const GET = apiHandler(async () => {
   annotate({ action: { name: "health.check" } });
 
-  let dbOk = true;
-
-  try {
-    await prisma.$queryRaw`SELECT 1`;
-  } catch {
-    dbOk = false;
-  }
+  const dbOk = await probeDatabase();
 
   const worker = getWorkerStatus();
   const producerReady = getGlobalBoss() !== null;
@@ -31,20 +53,23 @@ export const GET = apiHandler(async () => {
   // other route; the probe says so in a word every caller may see, because
   // it is the one place a catalog install's status page reads.
   const keyMismatch = isKeyMismatch();
-  const reason = keyMismatch ? KEY_MISMATCH_HEALTH_REASON : undefined;
+  // Otherwise, while the background role is still starting, the 503 below
+  // says so: a transient state, not a fault, and not a hang.
+  const roleDown =
+    (shouldRunWeb() && !producerReady) ||
+    (shouldRunWorker() && !worker.running);
+  const reason = keyMismatch
+    ? KEY_MISMATCH_HEALTH_REASON
+    : dbOk && roleDown && startupPhase() === "starting"
+      ? STARTING_HEALTH_REASON
+      : undefined;
   // Under ENCRYPTION_KEY_CHECK=warn the same finding does not refuse; it is
   // named as a warning and leaves the status alone.
   const warning =
     !keyMismatch && getKeyMismatchWarning()
       ? KEY_MISMATCH_HEALTH_REASON
       : undefined;
-  const status =
-    !keyMismatch &&
-    dbOk &&
-    (!shouldRunWeb() || producerReady) &&
-    (!shouldRunWorker() || worker.running)
-      ? "ok"
-      : "degraded";
+  const status = !keyMismatch && dbOk && !roleDown ? "ok" : "degraded";
   const statusCode = status === "ok" ? 200 : 503;
 
   const cacheHeaders = {
diff --git a/src/app/api/measurements/batch/__tests__/duplicate-prefilter.test.ts b/src/app/api/measurements/batch/__tests__/duplicate-prefilter.test.ts
index 09ed7da58..7ce59b9f5 100644
--- a/src/app/api/measurements/batch/__tests__/duplicate-prefilter.test.ts
+++ b/src/app/api/measurements/batch/__tests__/duplicate-prefilter.test.ts
@@ -9,6 +9,11 @@
  * prefilter's read answering nothing, which is the pre-v1.42 path where every
  * row went through the reconciler. Statuses, reasons and counters must match
  * exactly; only the transaction count may differ.
+ *
+ * v1.44 — the golden run is also blind to the set-based insert: its
+ * `INSERT … ON CONFLICT DO NOTHING` stand-in lands nothing, so every row
+ * reaches the reconciler one at a time, the sequential path. The shipped run
+ * takes the set insert, and the two must still leave the same table.
  */
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { NextRequest } from "next/server";
@@ -29,6 +34,8 @@ const store = vi.hoisted(() => ({
   rows: [] as StoredRow[],
   /** Golden mode: the prefilter's read answers nothing. */
   prefilterBlind: false,
+  /** Golden mode: the set-based insert lands nothing. */
+  setInsertBlind: false,
   nextId: 1,
 }));
 
@@ -81,12 +88,70 @@ vi.mock("@/lib/db", () => {
         },
       ),
     },
-    $transaction: vi.fn(async (fn: (tx: unknown) => unknown) => fn({})),
+    $transaction: vi.fn(async (fn: (tx: unknown) => unknown) =>
+      fn({
+        measurement: {
+          // `INSERT … ON CONFLICT DO NOTHING` over both unique identities,
+          // in VALUES order, returning the rows that landed.
+          createManyAndReturn: async (args: {
+            data: Array<{
+              userId: string;
+              type: string;
+              source: string;
+              externalId: string;
+              measuredAt: Date;
+              sleepStage: string | null;
+              value: number;
+            }>;
+          }) => {
+            if (store.setInsertBlind) return [];
+            const landed: Array<{
+              type: string;
+              source: string;
+              externalId: string;
+            }> = [];
+            for (const d of args.data) {
+              const scope = store.rows.filter(
+                (r) =>
+                  r.userId === d.userId &&
+                  r.type === d.type &&
+                  r.source === d.source,
+              );
+              const conflict = scope.some(
+                (r) =>
+                  r.externalId === d.externalId ||
+                  (sameInstant(r.measuredAt, d.measuredAt) &&
+                    r.sleepStage === (d.sleepStage ?? null)),
+              );
+              if (conflict) continue;
+              store.rows.push({
+                id: `m${store.nextId++}`,
+                userId: d.userId,
+                type: d.type,
+                source: d.source,
+                externalId: d.externalId,
+                measuredAt: d.measuredAt,
+                sleepStage: d.sleepStage ?? null,
+                value: d.value,
+                deletedAt: null,
+              });
+              landed.push({
+                type: d.type,
+                source: d.source,
+                externalId: d.externalId,
+              });
+            }
+            return landed;
+          },
+        },
+      }),
+    ),
   };
   return { prisma };
 });
 
 vi.mock("@/lib/measurements/reconcile-external-measurement", () => ({
+  lockMeasurementUser: async () => undefined,
   reconcileExternalMeasurement: async (
     _tx: unknown,
     desired: {
@@ -283,6 +348,7 @@ async function golden(setup: () => void, entries: Entry[]) {
   store.nextId = 1;
   setup();
   store.prefilterBlind = true;
+  store.setInsertBlind = true;
   vi.mocked(prisma.$transaction).mockClear();
   const old = await post(entries);
   const oldTransactions = vi.mocked(prisma.$transaction).mock.calls.length;
@@ -292,6 +358,7 @@ async function golden(setup: () => void, entries: Entry[]) {
   store.nextId = 1;
   setup();
   store.prefilterBlind = false;
+  store.setInsertBlind = false;
   vi.mocked(prisma.$transaction).mockClear();
   const next = await post(entries);
   const transactions = vi.mocked(prisma.$transaction).mock.calls.length;
@@ -304,6 +371,7 @@ beforeEach(() => {
   vi.clearAllMocks();
   store.rows = [];
   store.prefilterBlind = false;
+  store.setInsertBlind = false;
   vi.mocked(getSession).mockResolvedValue({
     session: { id: "s", expiresAt: new Date(NOW + HOUR) },
     user: { id: USER, username: "u", role: "USER" as const },
@@ -334,7 +402,9 @@ describe("exact-duplicate prefilter (v1.42)", () => {
       entries,
     );
     expect(next.duplicates).toBe(500);
-    expect(oldTransactions).toBe(500);
+    // Sequentially: two set-insert statements that land nothing, then one
+    // reconciler transaction per row.
+    expect(oldTransactions).toBe(502);
     expect(transactions).toBe(0);
   });
 
@@ -366,7 +436,8 @@ describe("exact-duplicate prefilter (v1.42)", () => {
       weight("uuid-move", new Date(NOW - DAY)),
     ]);
     expect(next.entries[0].status).toBe("updated");
-    expect(transactions).toBe(1);
+    // The set insert skips it on the external identity, the reconciler moves it.
+    expect(transactions).toBe(2);
   });
 
   it("4: the same id with another sleep stage still reconciles", async () => {
@@ -389,7 +460,7 @@ describe("exact-duplicate prefilter (v1.42)", () => {
       sleepStage: 3,
     };
     const { transactions } = await golden(setup, [entry]);
-    expect(transactions).toBe(1);
+    expect(transactions).toBe(2);
   });
 
   it("5: `stats:` rows are never prefiltered; a second snapshot is superseded", async () => {
@@ -615,3 +686,88 @@ describe("folded_window guard (v1.42)", () => {
     expect(data.entries[0].status).toBe("inserted");
   });
 });
+
+describe("set-based insert (v1.44)", () => {
+  it("500 fresh samples land in two statements, as the reconciler would have", async () => {
+    const entries = Array.from({ length: 500 }, (_, i) =>
+      pulse(`fresh-${i}`, new Date(NOW - DAY - i * 60_000), 60 + (i % 30)),
+    );
+    const { next, oldTransactions, transactions } = await golden(
+      () => undefined,
+      entries,
+    );
+    expect(next.inserted).toBe(500);
+    expect(oldTransactions).toBe(502);
+    expect(transactions).toBe(2);
+  });
+
+  it("a mix of fresh, moved and resurrected rows leaves the same table", async () => {
+    const at = (h: number) => new Date(NOW - DAY - h * HOUR);
+    const setup = () => {
+      // Moves: the stored row sits at another instant.
+      seed({ type: "WEIGHT", externalId: "moved", measuredAt: at(9) });
+      // Resurrects: a tombstone at a different instant under the same id.
+      seed({
+        type: "WEIGHT",
+        externalId: "back",
+        measuredAt: at(8),
+        deletedAt: new Date(NOW - HOUR),
+      });
+      // Natural-identity collision under another id: reconciled, not inserted.
+      seed({ type: "WEIGHT", externalId: "other", measuredAt: at(3) });
+    };
+    const { next, transactions } = await golden(setup, [
+      weight("fresh-a", at(1)),
+      weight("moved", at(2)),
+      weight("collides", at(3)),
+      weight("fresh-b", at(4)),
+      weight("back", at(5)),
+      weight("fresh-c", at(6)),
+    ]);
+    expect(next.entries.map((e) => e.status)).toEqual([
+      "inserted",
+      "updated",
+      "updated",
+      "inserted",
+      "updated",
+      "inserted",
+    ]);
+    // One set statement, then the three rows it skipped.
+    expect(transactions).toBe(4);
+  });
+
+  it("a row sharing an identity in the batch flushes the buffer first", async () => {
+    const at = new Date(NOW - DAY);
+    const { next } = await golden(
+      () => undefined,
+      [
+        weight("solo", new Date(at.getTime() - HOUR)),
+        weight("twice", at),
+        weight("twice", at),
+      ],
+    );
+    expect(next.entries.map((e) => e.status)).toEqual([
+      "inserted",
+      "inserted",
+      "duplicate",
+    ]);
+  });
+
+  it("keeps the order when a later reconcile would claim a buffered row's slot", async () => {
+    // Stored X at t1. C moves X to t5; D and E share t1, so neither is
+    // buffered. Sequentially C frees t1 before D arrives: D inserts, E
+    // merges into D. Reconciling D before C would instead take X's row for
+    // D and leave C to insert, a different table with the same rows.
+    const t1 = new Date(NOW - DAY - HOUR);
+    const t5 = new Date(NOW - DAY - 5 * HOUR);
+    const { next } = await golden(
+      () => seed({ type: "WEIGHT", externalId: "X", measuredAt: t1 }),
+      [weight("X", t5), weight("Y", t1), weight("Z", t1)],
+    );
+    expect(next.entries.map((e) => e.status)).toEqual([
+      "updated",
+      "inserted",
+      "updated",
+    ]);
+  });
+});
diff --git a/src/app/api/measurements/batch/route.ts b/src/app/api/measurements/batch/route.ts
index 501b03fea..cda75930f 100644
--- a/src/app/api/measurements/batch/route.ts
+++ b/src/app/api/measurements/batch/route.ts
@@ -66,7 +66,11 @@ import {
   oppositeMergeSource,
   type MergeCandidate,
 } from "@/lib/measurements/cross-source-merge";
-import { reconcileExternalMeasurement } from "@/lib/measurements/reconcile-external-measurement";
+import {
+  lockMeasurementUser,
+  reconcileExternalMeasurement,
+  type MeasurementReconciliationVerdict,
+} from "@/lib/measurements/reconcile-external-measurement";
 import { classifyRangeRejection } from "@/lib/measurements/plausibility-gate";
 import {
   FOLDED_WINDOW_REASON,
@@ -134,6 +138,12 @@ const MAX_BATCH_ENTRIES = 500;
 // The cap is a DoS ceiling, not a tight bound.
 const MAX_BODY_BYTES = 4 * 1024 * 1024;
 
+/**
+ * Rows per set-based insert statement. 500 entries fit two statements; each
+ * row binds about fifteen parameters, far under PostgreSQL's 65 535.
+ */
+const SET_INSERT_CHUNK = 250;
+
 // v1.4.25 (security H-2): cap batch ingest at 60
 // batches per user per minute. Healthy iOS sync drains its
 // HealthKit observer queue in well under one batch per minute (the
@@ -635,6 +645,8 @@ async function postBatch(request: NextRequest): Promise<Response> {
   let updatedCount = 0;
   let duplicateCount = 0;
   let failedCount = 0;
+  // v1.44 — subset of `insertedCount` written by the set-based insert.
+  let setInsertedCount = 0;
   // v1.11.4 (iOS #2) — subset of `duplicateCount` collapsed by the
   // MANUAL↔APPLE_HEALTH same-reading merge (as opposed to a plain
   // composite-key duplicate). Surfaced as a dedicated wide-event count so
@@ -855,6 +867,188 @@ async function postBatch(request: NextRequest): Promise<Response> {
       [...foldedIndexes].map((index) => prepared[index]),
     );
 
+    /** The reconciler's input for one prepared row. */
+    const desiredFor = (p: Prepared) => {
+      const statsRow = isStatsExternalId(p.row.externalId as string);
+      return {
+        userId: user.id,
+        type: p.row.type as MeasurementType,
+        value: p.row.value as number,
+        valueMin: p.row.valueMin as number | null,
+        valueMax: p.row.valueMax as number | null,
+        unit: p.row.unit as string,
+        source: p.row
+          .source as Prisma.MeasurementUncheckedCreateInput["source"],
+        measuredAt: p.row.measuredAt as Date,
+        externalId: p.row.externalId as string,
+        externalSourceVersion: p.row.externalSourceVersion as string | null,
+        glucoseContext: p.row
+          .glucoseContext as Prisma.MeasurementUncheckedCreateInput["glucoseContext"],
+        sleepStage: p.row
+          .sleepStage as Prisma.MeasurementUncheckedCreateInput["sleepStage"],
+        rhythmClassification: p.row
+          .rhythmClassification as Prisma.MeasurementUncheckedCreateInput["rhythmClassification"],
+        deviceType: p.row.deviceType as string | null,
+        aggregationProvenance: statsRow
+          ? ("HEALTHKIT_STATISTICS" as const)
+          : null,
+      };
+    };
+
+    const pushMergeCandidate = (p: Prepared) => {
+      if (isMergeableSource(p.row.source as string)) {
+        inBatchCandidates.push({
+          type: p.row.type as MeasurementType,
+          source: p.row.source as string,
+          value: p.row.value as number,
+          measuredAt: p.row.measuredAt as Date,
+        });
+      }
+    };
+
+    /**
+     * Record one row's verdict. `candidate` is false for a row whose merge
+     * candidate was already pushed when it was buffered (see below).
+     */
+    const applyVerdict = (
+      p: Prepared,
+      verdict: Pick<MeasurementReconciliationVerdict, "status"> &
+        Partial<{
+          dirtyIdentities: Array<{ type: MeasurementType; measuredAt: Date }>;
+          error: { code?: string };
+        }>,
+      candidate: boolean,
+    ) => {
+      switch (verdict.status) {
+        case "inserted":
+          results[p.index] = { index: p.index, status: "inserted" };
+          insertedCount++;
+          insertedPrepared.push(p);
+          writtenIdentities.push({
+            type: p.row.type as MeasurementType,
+            measuredAt: p.row.measuredAt as Date,
+          });
+          break;
+        case "updated":
+        case "resurrected":
+          results[p.index] = { index: p.index, status: "updated" };
+          updatedCount++;
+          writtenIdentities.push(
+            {
+              type: p.row.type as MeasurementType,
+              measuredAt: p.row.measuredAt as Date,
+            },
+            ...(verdict.dirtyIdentities ?? []),
+          );
+          break;
+        case "duplicate":
+          results[p.index] = { index: p.index, status: "duplicate" };
+          duplicateCount++;
+          break;
+        case "failed":
+          results[p.index] = {
+            index: p.index,
+            status: "failed",
+            reason: verdict.error?.code ?? "write_failed",
+          };
+          failedCount++;
+          return;
+        case "rejected_range":
+          // The reconciler carries the same plausibility gate this route
+          // already applied above, so reaching here means the two disagreed —
+          // report it exactly as the earlier guard would have, and let the
+          // wide-event tally record which end refused.
+          results[p.index] = outOfRangeResult(
+            p.index,
+            p.row.type as string,
+            p.row.value as number,
+          );
+          return;
+      }
+      if (candidate) pushMergeCandidate(p);
+    };
+
+    const reconcileRow = (p: Prepared) =>
+      prisma.$transaction((tx) =>
+        reconcileExternalMeasurement(tx, desiredFor(p), {
+          exactExternalMatch: isStatsExternalId(p.row.externalId as string)
+            ? "update"
+            : "duplicate",
+        }),
+      );
+
+    // v1.44 — set-based inserts. A fresh sample used to cost one interactive
+    // transaction of about ten round trips (savepoint, three advisory locks,
+    // two candidate reads, the insert), so a 500-entry batch of new samples
+    // was 500 of those in a row: the 2–15 s outliers.
+    //
+    // The reconciler inserts exactly when no row, live or tombstoned, holds
+    // the entry's external identity `(type, source, externalId)` or its
+    // natural identity `(type, measuredAt, source, sleepStage)`. Both are
+    // full unique indexes (the natural one NULLS NOT DISTINCT), so
+    // `INSERT … ON CONFLICT DO NOTHING` inserts exactly those rows and skips
+    // every other; a skipped row then goes through the reconciler as before
+    // and gets its own verdict (update, resurrect, duplicate). The insert
+    // runs under the same per-account advisory lock the reconciler takes, so
+    // the two serialise like two reconcilers would.
+    //
+    // Only a row whose external and natural key each occur once in the batch
+    // is buffered, and the buffer is flushed before any other row reaches the
+    // reconciler. Such a row shares no identity with another entry, so no
+    // other entry's reconcile can create, move or retire a row at its
+    // identity, and inserting it out of turn changes nothing. Rows the insert
+    // skips are reconciled in their original order. A buffered row's merge
+    // candidate is pushed when it is buffered, as the sequential loop pushed
+    // it after a successful write; the only case that differs is a write that
+    // fails outright, where the candidate stays.
+    const pendingInserts: Prepared[] = [];
+    const flushPendingInserts = async () => {
+      if (pendingInserts.length === 0) return;
+      const batch = pendingInserts.splice(0, pendingInserts.length);
+      const landed = new Set<Prepared>();
+      try {
+        for (let i = 0; i < batch.length; i += SET_INSERT_CHUNK) {
+          const slice = batch.slice(i, i + SET_INSERT_CHUNK);
+          const rows = await prisma.$transaction(async (tx) => {
+            await lockMeasurementUser(tx, user.id);
+            return tx.measurement.createManyAndReturn({
+              data: slice.map((p) => ({
+                ...desiredFor(p),
+                sleepStage: (p.row.sleepStage ??
+                  null) as Prisma.MeasurementUncheckedCreateInput["sleepStage"],
+                deletedAt: null,
+              })),
+              skipDuplicates: true,
+              select: { type: true, source: true, externalId: true },
+            });
+          });
+          const keys = new Set(
+            rows.map((r) => `${r.type}::${r.source}::${r.externalId}`),
+          );
+          for (const p of slice) {
+            if (keys.has(`${p.row.type}::${p.row.source}::${p.row.externalId}`))
+              landed.add(p);
+          }
+        }
+      } catch (err) {
+        // Whatever did not land goes through the reconciler below, which
+        // turns a real database fault into a per-entry `failed` verdict.
+        annotate({
+          action: { name: "measurement.batch.set_insert_fallback" },
+          meta: {
+            error_class: err instanceof Error ? err.name : "unknown",
+            landed: landed.size,
+            pending: batch.length,
+          },
+        });
+      }
+      setInsertedCount += landed.size;
+      for (const p of batch) {
+        if (landed.has(p)) applyVerdict(p, { status: "inserted" }, false);
+        else applyVerdict(p, await reconcileRow(p), false);
+      }
+    };
+
     for (const p of prepared) {
       const externalId = p.row.externalId as string;
       const statsRow = isStatsExternalId(externalId);
@@ -895,101 +1089,29 @@ async function postBatch(request: NextRequest): Promise<Response> {
           : { index: p.index, status: "duplicate" };
         duplicateCount++;
         if (folded) foldedWindowCount++;
-        if (isMergeableSource(p.row.source as string)) {
-          inBatchCandidates.push({
-            type: p.row.type as MeasurementType,
-            source: p.row.source as string,
-            value: p.row.value as number,
-            measuredAt: p.row.measuredAt as Date,
-          });
-        }
+        pushMergeCandidate(p);
         continue;
       }
 
-      const verdict = await prisma.$transaction((tx) =>
-        reconcileExternalMeasurement(
-          tx,
-          {
-            userId: user.id,
-            type: p.row.type as MeasurementType,
-            value: p.row.value as number,
-            valueMin: p.row.valueMin as number | null,
-            valueMax: p.row.valueMax as number | null,
-            unit: p.row.unit as string,
-            source: p.row
-              .source as Prisma.MeasurementUncheckedCreateInput["source"],
-            measuredAt: p.row.measuredAt as Date,
-            externalId,
-            externalSourceVersion: p.row.externalSourceVersion as string | null,
-            glucoseContext: p.row
-              .glucoseContext as Prisma.MeasurementUncheckedCreateInput["glucoseContext"],
-            sleepStage: p.row
-              .sleepStage as Prisma.MeasurementUncheckedCreateInput["sleepStage"],
-            rhythmClassification: p.row
-              .rhythmClassification as Prisma.MeasurementUncheckedCreateInput["rhythmClassification"],
-            deviceType: p.row.deviceType as string | null,
-            aggregationProvenance: statsRow ? "HEALTHKIT_STATISTICS" : null,
-          },
-          { exactExternalMatch: statsRow ? "update" : "duplicate" },
-        ),
+      const naturalKey = naturalKeyOf(
+        p.row.type,
+        p.row.source,
+        p.row.measuredAt as Date,
+        p.row.sleepStage,
       );
-
-      switch (verdict.status) {
-        case "inserted":
-          results[p.index] = { index: p.index, status: "inserted" };
-          insertedCount++;
-          insertedPrepared.push(p);
-          writtenIdentities.push({
-            type: p.row.type as MeasurementType,
-            measuredAt: p.row.measuredAt as Date,
-          });
-          break;
-        case "updated":
-        case "resurrected":
-          results[p.index] = { index: p.index, status: "updated" };
-          updatedCount++;
-          writtenIdentities.push(
-            {
-              type: p.row.type as MeasurementType,
-              measuredAt: p.row.measuredAt as Date,
-            },
-            ...(verdict.dirtyIdentities ?? []),
-          );
-          break;
-        case "duplicate":
-          results[p.index] = { index: p.index, status: "duplicate" };
-          duplicateCount++;
-          break;
-        case "failed":
-          results[p.index] = {
-            index: p.index,
-            status: "failed",
-            reason: verdict.error.code ?? "write_failed",
-          };
-          failedCount++;
-          continue;
-        case "rejected_range":
-          // The reconciler carries the same plausibility gate this route
-          // already applied above, so reaching here means the two disagreed —
-          // report it exactly as the earlier guard would have, and let the
-          // wide-event tally record which end refused.
-          results[p.index] = outOfRangeResult(
-            p.index,
-            p.row.type as string,
-            p.row.value as number,
-          );
-          continue;
+      if (
+        externalKeyCounts.get(key) === 1 &&
+        naturalKeyCounts.get(naturalKey) === 1
+      ) {
+        pendingInserts.push(p);
+        pushMergeCandidate(p);
+        continue;
       }
 
-      if (isMergeableSource(p.row.source as string)) {
-        inBatchCandidates.push({
-          type: p.row.type as MeasurementType,
-          source: p.row.source as string,
-          value: p.row.value as number,
-          measuredAt: p.row.measuredAt as Date,
-        });
-      }
+      await flushPendingInserts();
+      applyVerdict(p, await reconcileRow(p), true);
     }
+    await flushPendingInserts();
   }
 
   // v1.43 — the hours, after the measurements. One write per slot: the last
@@ -1342,6 +1464,9 @@ async function postBatch(request: NextRequest): Promise<Response> {
       // v1.42 — duplicates refused because a live `stats:` row already
       // covers the sample's hour or day (`folded-window.ts`).
       folded_window: foldedWindowCount,
+      // v1.44 — inserts that took the set-based path rather than one
+      // reconciler transaction each.
+      set_inserted: setInsertedCount,
     },
   });
 
diff --git a/src/instrumentation.ts b/src/instrumentation.ts
index 01de8ed80..3f9cca282 100644
--- a/src/instrumentation.ts
+++ b/src/instrumentation.ts
@@ -79,57 +79,76 @@ export async function register() {
       // A diagnostic must never break boot.
     }
 
-    const { shouldRunWorker } = await import("@/lib/process-type");
+    // The background role starts after the server is up. Awaiting it here
+    // held every request, `/api/health` included, for the seconds pg-boss
+    // needs to start, provision its queues and run the boot discovery; the
+    // probe now answers `starting` meanwhile. A request that enqueues while
+    // the boss is not bound yet takes the same path as during a producer
+    // reconnect: a garnish skips its enqueue (the owning cron catches up),
+    // and a route that needs the worker answers 503 until it is up.
+    const [{ shouldRunWorker }, { markStartup }] = await Promise.all([
+      import("@/lib/process-type"),
+      import("@/lib/boot/startup-state"),
+    ]);
+    markStartup("starting");
     if (!shouldRunWorker()) {
       // Split deployment: web requests still produce queue jobs, but this
       // process owns no schedules, supervision, or consumers.
-      try {
-        const { startGlobalBossProducer } =
-          await import("@/lib/jobs/boss-instance");
-        const boss = await startGlobalBossProducer(process.env.DATABASE_URL);
-        if (boss) {
-          const { registerShutdownHandlers } =
-            await import("@/lib/jobs/reminder/worker-lifecycle");
-          registerShutdownHandlers(boss);
+      void (async () => {
+        try {
+          const { startGlobalBossProducer } =
+            await import("@/lib/jobs/boss-instance");
+          const boss = await startGlobalBossProducer(process.env.DATABASE_URL);
+          if (boss) {
+            const { registerShutdownHandlers } =
+              await import("@/lib/jobs/reminder/worker-lifecycle");
+            registerShutdownHandlers(boss);
+          }
+          markStartup(boss ? "ready" : "failed");
+        } catch (err) {
+          markStartup("failed");
+          // Queue-backed garnishes degrade independently; never make the web
+          // server unavailable because its producer connection failed.
+          console.error(
+            "[instrumentation] Failed to start pg-boss producer:",
+            err,
+          );
         }
-      } catch (err) {
-        // Queue-backed garnishes degrade independently; never make the web
-        // server unavailable because its producer connection failed.
-        console.error(
-          "[instrumentation] Failed to start pg-boss producer:",
-          err,
-        );
-      }
+      })();
       return;
     }
 
-    const { WideEventBuilder } = await import("@/lib/logging/event-builder");
-    const { emitIfSampled } = await import("@/lib/logging/transports");
+    void (async () => {
+      const { WideEventBuilder } = await import("@/lib/logging/event-builder");
+      const { emitIfSampled } = await import("@/lib/logging/transports");
 
-    // Emit startup event
-    const startupEvt = new WideEventBuilder("background");
-    startupEvt.setBackground({ task_name: "startup" });
+      // Emit startup event
+      const startupEvt = new WideEventBuilder("background");
+      startupEvt.setBackground({ task_name: "startup" });
 
-    try {
-      const { startReminderWorker } =
-        await import("@/lib/jobs/reminder-worker");
-      await startReminderWorker();
+      try {
+        const { startReminderWorker } =
+          await import("@/lib/jobs/reminder-worker");
+        await startReminderWorker();
+        markStartup("ready");
 
-      startupEvt.addMeta("reminder_worker", "started");
-      startupEvt.finish();
-      emitIfSampled(startupEvt.toJSON());
-    } catch (err) {
-      startupEvt.setError(err);
-      startupEvt.addMeta("reminder_worker", "failed");
-      startupEvt.finish();
-      emitIfSampled(startupEvt.toJSON());
+        startupEvt.addMeta("reminder_worker", "started");
+        startupEvt.finish();
+        emitIfSampled(startupEvt.toJSON());
+      } catch (err) {
+        markStartup("failed");
+        startupEvt.setError(err);
+        startupEvt.addMeta("reminder_worker", "failed");
+        startupEvt.finish();
+        emitIfSampled(startupEvt.toJSON());
 
-      // Still log to stderr for container health checks
-      console.error(
-        "[instrumentation] CRITICAL: Failed to start reminder worker:",
-        err,
-      );
-    }
+        // Still log to stderr for container health checks
+        console.error(
+          "[instrumentation] CRITICAL: Failed to start reminder worker:",
+          err,
+        );
+      }
+    })();
   }
 }
 
diff --git a/src/lib/boot/startup-state.ts b/src/lib/boot/startup-state.ts
new file mode 100644
index 000000000..59cd80a22
--- /dev/null
+++ b/src/lib/boot/startup-state.ts
@@ -0,0 +1,23 @@
+/**
+ * Where this process is in bringing up its background role.
+ *
+ * The pg-boss worker (or, in a web-only process, the send-only producer)
+ * starts after the HTTP server is already serving: starting it inside
+ * `register()` held every request, `/api/health` included, for the seconds
+ * pg-boss needs to start, provision its queues and run the boot discovery.
+ * The probe reads this to say `starting` while that is under way rather than
+ * hanging, and the operator sees a 503 that names a transient state.
+ *
+ * `null` means no background role was started in this process at all.
+ */
+export type StartupPhase = "starting" | "ready" | "failed";
+
+const KEY = Symbol.for("healthlog.boot.startupPhase");
+
+export function markStartup(phase: StartupPhase): void {
+  (globalThis as Record<symbol, unknown>)[KEY] = phase;
+}
+
+export function startupPhase(): StartupPhase | null {
+  return ((globalThis as Record<symbol, unknown>)[KEY] as StartupPhase) ?? null;
+}
diff --git a/src/lib/measurements/reconcile-external-measurement.ts b/src/lib/measurements/reconcile-external-measurement.ts
index d4fb50784..0fdd7b773 100644
--- a/src/lib/measurements/reconcile-external-measurement.ts
+++ b/src/lib/measurements/reconcile-external-measurement.ts
@@ -140,7 +140,13 @@ function lockKeys(desired: ExternalMeasurementWrite): string[] {
   ].sort();
 }
 
-async function lockUser(
+/**
+ * The per-account advisory lock every cooperative measurement writer takes
+ * first. Exported for the batch route's set-based insert, which takes it
+ * around its `INSERT … ON CONFLICT DO NOTHING` so it serialises with the
+ * reconciler exactly as a second reconciler would.
+ */
+export async function lockMeasurementUser(
   tx: PrismaTypes.TransactionClient,
   userId: string,
 ): Promise<void> {
@@ -259,7 +265,7 @@ export async function reconcileExternalMeasurement(
   await tx.$executeRawUnsafe(`SAVEPOINT ${SAVEPOINT}`);
 
   try {
-    await lockUser(tx, desired.userId);
+    await lockMeasurementUser(tx, desired.userId);
     for (const key of lockKeys(desired)) {
       await tx.$queryRaw(
         Prisma.sql`
diff --git a/src/lib/openapi/routes/health.ts b/src/lib/openapi/routes/health.ts
index 2540e8fe6..90d9221ba 100644
--- a/src/lib/openapi/routes/health.ts
+++ b/src/lib/openapi/routes/health.ts
@@ -26,11 +26,14 @@ const healthStatusEnum = z.enum(["ok", "degraded"]).meta({
     "`ok` when the database answers AND every role this process runs holds up: the pg-boss producer is bound when the process serves web, and the worker loop is running when the process runs the worker. `degraded` on any of those failing.",
 });
 
-const healthReason = z.enum(["encryption_key_mismatch"]).optional().meta({
-  id: "HealthReason",
-  description:
-    "Present only when the process refuses to serve for a reason a person has to fix. `encryption_key_mismatch`: the configured encryption key cannot open the data in this database (checked at boot). Every other route then answers 503 with `meta.errorCode` `encryption.key_mismatch`, and background jobs are not started. Fix: restore the original key, point the server at the matching database, or start with an empty one; then restart.",
-});
+const healthReason = z
+  .enum(["encryption_key_mismatch", "starting"])
+  .optional()
+  .meta({
+    id: "HealthReason",
+    description:
+      "Why a `degraded` process is degraded, when it is something other than a component failure. `encryption_key_mismatch`: the process refuses to serve for a reason a person has to fix; the configured encryption key cannot open the data in this database (checked at boot). Every other route then answers 503 with `meta.errorCode` `encryption.key_mismatch`, and background jobs are not started. Fix: restore the original key, point the server at the matching database, or start with an empty one; then restart. `starting`: the database answers but the background role (the pg-boss worker, or the producer of a web-only process) is still coming up after a start. Transient; nothing to fix, poll again. The probe answers at once while it lasts rather than waiting for the start to finish.",
+  });
 
 const healthPublicResponse = z
   .object({ status: healthStatusEnum, reason: healthReason })
@@ -92,7 +95,7 @@ export const healthPaths: NonNullable<ZodOpenApiObject["paths"]> = {
         },
         "503": {
           description:
-            "Degraded — the database did not answer, or a role this process runs is not up. Same body shape as the 200, with `status: \"degraded\"`. A restart loop reports this rather than failing to answer, so a monitor can tell 'starting' from 'gone'.",
+            "Degraded — the database did not answer within two seconds, or a role this process runs is not up. Same body shape as the 200, with `status: \"degraded\"`, and `reason: \"starting\"` while the background role is still coming up after a start. A restart loop reports this rather than failing to answer, so a monitor can tell 'starting' from 'gone'.",
           content: {
             "application/json": {
               schema: z.union([healthAdminResponse, healthPublicResponse]),
diff --git a/tests/integration/measurements-batch-perf.test.ts b/tests/integration/measurements-batch-perf.test.ts
new file mode 100644
index 000000000..900a4e4d1
--- /dev/null
+++ b/tests/integration/measurements-batch-perf.test.ts
@@ -0,0 +1,255 @@
+/**
+ * `POST /api/measurements/batch` under a realistic large batch.
+ *
+ * Production saw this route take 2 s and more, up to 15 s, on full
+ * 500-entry uploads. The cost was one interactive reconciler transaction
+ * (about ten round trips) per fresh sample. Since v1.44 fresh samples land
+ * through a set-based `INSERT … ON CONFLICT DO NOTHING` and only rows that
+ * hit an existing identity reach the reconciler.
+ *
+ * This suite pins the shape of the work rather than a machine's speed:
+ *   - a fresh 500-entry batch opens a handful of transactions, not 500;
+ *   - a re-post of the same batch opens none (the duplicate prefilter);
+ *   - the rollup leg runs once per request, not once per row;
+ *   - the wall-clock bound is generous, a tripwire for a regression back to
+ *     per-row work, not a benchmark.
+ */
+import { NextRequest } from "next/server";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { cookieJar } from "./mock-next-headers";
+import { getPrismaClient, truncateAllTables } from "./setup";
+
+const TEST_USER_ID = "user-batch-perf-test";
+
+vi.mock("next/headers", async () => {
+  const { cookieJar, headerJar } = await import("./mock-next-headers");
+  return {
+    headers: vi.fn(async () => ({
+      get: (name: string) => headerJar.get(name.toLowerCase()) ?? null,
+    })),
+    cookies: vi.fn(async () => ({
+      get: (name: string) => {
+        const value = cookieJar.get(name);
+        return value ? { name, value } : undefined;
+      },
+      set: (name: string, value: string) => {
+        cookieJar.set(name, value);
+      },
+      delete: (name: string) => {
+        cookieJar.delete(name);
+      },
+    })),
+  };
+});
+
+vi.mock("@/lib/db-compat", () => ({
+  ensureDbCompatibility: vi.fn().mockResolvedValue(undefined),
+}));
+
+const rollupCalls = vi.hoisted(() => ({ count: 0 }));
+vi.mock("@/lib/rollups/after-measurement-mutation", async () => {
+  const actual = await vi.importActual<
+    typeof import("@/lib/rollups/after-measurement-mutation")
+  >("@/lib/rollups/after-measurement-mutation");
+  return {
+    ...actual,
+    afterMeasurementMutation: (
+      ...args: Parameters<typeof actual.afterMeasurementMutation>
+    ) => {
+      rollupCalls.count += 1;
+      return actual.afterMeasurementMutation(...args);
+    },
+  };
+});
+
+beforeEach(async () => {
+  await truncateAllTables(getPrismaClient());
+  cookieJar.clear();
+  rollupCalls.count = 0;
+  await getPrismaClient().user.create({
+    data: {
+      id: TEST_USER_ID,
+      username: "batch-perf",
+      email: "batch-perf@example.test",
+      timezone: "Europe/Berlin",
+    },
+  });
+  const session = await getPrismaClient().session.create({
+    data: {
+      userId: TEST_USER_ID,
+      expiresAt: new Date(Date.now() + 60 * 60 * 1000),
+    },
+  });
+  cookieJar.set("healthlog_session", session.id);
+});
+
+/**
+ * What a phone sends after a day offline: dense heart rate, a few HRV and
+ * oxygen readings, a night of sleep stages, and the day's cumulative totals.
+ */
+function realisticBatch(dayOffset = 2): Array<Record<string, unknown>> {
+  const day = new Date(Date.now() - dayOffset * 86_400_000);
+  day.setUTCHours(0, 0, 0, 0);
+  const at = (minutes: number) =>
+    new Date(day.getTime() + minutes * 60_000).toISOString();
+  const entries: Array<Record<string, unknown>> = [];
+  for (let i = 0; i < 400; i++) {
+    entries.push({
+      hkIdentifier: "HKQuantityTypeIdentifierHeartRate",
+      value: 55 + (i % 40),
+      unit: "count/min",
+      startDate: at(i * 3),
+      endDate: at(i * 3),
+      externalId: `perf-hr-${dayOffset}-${i}`,
+    });
+  }
+  for (let i = 0; i < 40; i++) {
+    entries.push({
+      hkIdentifier: "HKQuantityTypeIdentifierHeartRateVariabilitySDNN",
+      value: 30 + i,
+      unit: "ms",
+      startDate: at(i * 30 + 1),
+      endDate: at(i * 30 + 1),
+      externalId: `perf-hrv-${dayOffset}-${i}`,
+    });
+    entries.push({
+      hkIdentifier: "HKQuantityTypeIdentifierOxygenSaturation",
+      value: 0.96,
+      unit: "%",
+      startDate: at(i * 30 + 2),
+      endDate: at(i * 30 + 2),
+      externalId: `perf-spo2-${dayOffset}-${i}`,
+    });
+  }
+  for (let i = 0; i < 16; i++) {
+    entries.push({
+      hkIdentifier: "HKCategoryTypeIdentifierSleepAnalysis",
+      value: 30,
+      unit: "min",
+      startDate: at(-480 + i * 30),
+      endDate: at(-450 + i * 30),
+      externalId: `perf-sleep-${dayOffset}-${i}`,
+      sleepStage: 3 + (i % 3),
+    });
+  }
+  const dayKey = day.toISOString().slice(0, 10);
+  for (const [hk, unit, value] of [
+    ["HKQuantityTypeIdentifierStepCount", "count", 9_431],
+    ["HKQuantityTypeIdentifierActiveEnergyBurned", "kcal", 512],
+    ["HKQuantityTypeIdentifierAppleExerciseTime", "min", 42],
+    ["HKQuantityTypeIdentifierAppleStandTime", "min", 180],
+  ] as const) {
+    entries.push({
+      hkIdentifier: hk,
+      value,
+      unit,
+      startDate: at(0),
+      endDate: at(18 * 60),
+      externalId: `stats:${hk}:${dayKey}`,
+    });
+  }
+  return entries;
+}
+
+async function post(entries: Array<Record<string, unknown>>) {
+  const { POST } = await import("@/app/api/measurements/batch/route");
+  const res = await POST(
+    new NextRequest("http://localhost/api/measurements/batch", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ entries }),
+    }),
+  );
+  expect(res.status).toBe(200);
+  return (
+    (await res.json()) as {
+      data: {
+        inserted: number;
+        updated: number;
+        duplicates: number;
+        failed: number;
+        skipped: number;
+      };
+    }
+  ).data;
+}
+
+describe("POST /api/measurements/batch — large-batch cost (real Postgres)", () => {
+  it("writes a fresh 500-entry batch in a handful of transactions", async () => {
+    const { prisma } = await import("@/lib/db");
+    const entries = realisticBatch();
+    expect(entries).toHaveLength(500);
+
+    const transaction = vi.spyOn(prisma, "$transaction");
+    const started = performance.now();
+    const result = await post(entries);
+    const elapsedMs = performance.now() - started;
+    const transactions = transaction.mock.calls.length;
+    transaction.mockRestore();
+
+    expect(result.failed).toBe(0);
+    expect(result.inserted).toBe(500);
+    // Two set statements (250 rows each) plus the hour-bucket and checkpoint
+    // writes. Before v1.44 this was one transaction per row: 500.
+    expect(transactions).toBeLessThanOrEqual(10);
+    expect(rollupCalls.count).toBe(1);
+    expect(
+      await getPrismaClient().measurement.count({
+        where: { userId: TEST_USER_ID },
+      }),
+    ).toBe(500);
+    // A tripwire, not a benchmark: per-row work on a local container sits
+    // well above this, the set path well below.
+    expect(elapsedMs).toBeLessThan(10_000);
+    console.info(
+      `[batch-perf] fresh 500: ${Math.round(elapsedMs)} ms, ${transactions} transactions`,
+    );
+  });
+
+  it("answers a re-post of the same batch without a transaction", async () => {
+    const { prisma } = await import("@/lib/db");
+    const entries = realisticBatch();
+    await post(entries);
+    rollupCalls.count = 0;
+
+    const transaction = vi.spyOn(prisma, "$transaction");
+    const started = performance.now();
+    const result = await post(entries);
+    const elapsedMs = performance.now() - started;
+    const transactions = transaction.mock.calls.length;
+    transaction.mockRestore();
+
+    // The four `stats:` rows carry overwrite semantics and reconcile; every
+    // sample is an exact duplicate and never reaches a transaction.
+    expect(result.inserted).toBe(0);
+    expect(result.duplicates + result.updated).toBe(500);
+    expect(transactions).toBeLessThanOrEqual(8);
+    expect(elapsedMs).toBeLessThan(10_000);
+    console.info(
+      `[batch-perf] re-post 500: ${Math.round(elapsedMs)} ms, ${transactions} transactions`,
+    );
+  });
+
+  it("keeps the set path's verdicts when the batch overlaps stored rows", async () => {
+    const entries = realisticBatch();
+    await post(entries.slice(0, 250));
+    // Move half of the stored heart-rate rows: same id, another instant.
+    const moved = entries.slice(0, 100).map((e) => ({
+      ...e,
+      startDate: new Date(
+        Date.parse(e.endDate as string) + 1_000,
+      ).toISOString(),
+      endDate: new Date(Date.parse(e.endDate as string) + 1_000).toISOString(),
+    }));
+    const result = await post([...moved, ...entries.slice(250)]);
+    expect(result.failed).toBe(0);
+    expect(result.updated).toBeGreaterThanOrEqual(100);
+    expect(result.inserted).toBe(250);
+    expect(
+      await getPrismaClient().measurement.count({
+        where: { userId: TEST_USER_ID, deletedAt: null },
+      }),
+    ).toBe(500);
+  });
+});

From 81e1f4cad139cc0e54a14fcddfd1d1d73d2c452b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Wed, 21 Oct 2026 20:51:13 +0200
Subject: [PATCH 8/8] fix(workouts): keep tracks and climb for accounts that
 already had them

Migration 0434 turns the route opt-in on for every account that already
holds a stored workout track, so its tracks keep arriving after the
upgrade; only accounts without one start off.

Workouts stored before this release with a track but no elevation get
their metres climbed written into Workout.elevationM by a one-time
background pass. It runs detached at worker boot, reads one track at a
time with a pause between batches of 100, and keeps its position in
app_settings, so a restart resumes and a finished pass ends at once.

The "starting" health reason is bounded: after five minutes the probe
says plain degraded and the process logs one line, and the time the
background role took to come up is logged either way. The compose
healthcheck's ten-minute start period already keeps those probes from
counting; its comment now says so.
---
 docker-compose.yml                            |   6 +-
 .../migration.sql                             |  21 +++
 prisma/schema.prisma                          |   4 +
 .../ai-egress-capability-guard.test.ts        |   2 +
 src/app/api/health/__tests__/route.test.ts    |  16 ++
 src/instrumentation.ts                        |  29 +++-
 src/lib/boot/startup-state.ts                 |  44 +++++-
 src/lib/jobs/reminder/register-maintenance.ts |  28 ++++
 .../workouts/__tests__/climb-backfill.test.ts | 137 ++++++++++++++++++
 src/lib/workouts/climb-backfill.ts            |  99 +++++++++++++
 .../workout-routes-opt-in-migration.test.ts   |  86 +++++++++++
 11 files changed, 460 insertions(+), 12 deletions(-)
 create mode 100644 prisma/migrations/0434_workout_routes_keep_and_climb_cursor/migration.sql
 create mode 100644 src/lib/workouts/__tests__/climb-backfill.test.ts
 create mode 100644 src/lib/workouts/climb-backfill.ts
 create mode 100644 tests/integration/workout-routes-opt-in-migration.test.ts

diff --git a/docker-compose.yml b/docker-compose.yml
index af4954609..c3aee3175 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -522,7 +522,11 @@ services:
       # 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.
+      # 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
diff --git a/prisma/migrations/0434_workout_routes_keep_and_climb_cursor/migration.sql b/prisma/migrations/0434_workout_routes_keep_and_climb_cursor/migration.sql
new file mode 100644
index 000000000..31087e330
--- /dev/null
+++ b/prisma/migrations/0434_workout_routes_keep_and_climb_cursor/migration.sql
@@ -0,0 +1,21 @@
+-- Nobody who already keeps workout tracks loses them with 0432's opt-in.
+--
+-- 0432 added `users.store_workout_routes`, off by default. An account that
+-- already holds at least one stored track has been syncing routes all along;
+-- for it the setting starts ON, so its tracks keep arriving after the
+-- upgrade. Only accounts without any stored track start OFF. Runs once, at
+-- the upgrade; a person who turns it off afterwards stays off.
+UPDATE "users" AS u
+SET "store_workout_routes" = true
+WHERE EXISTS (
+  SELECT 1
+  FROM "workout_routes" AS r
+  JOIN "workouts" AS w ON w."id" = r."workout_id"
+  WHERE w."user_id" = u."id"
+);
+
+-- Cursor of the one-time climb backfill (`src/lib/workouts/climb-backfill.ts`):
+-- workouts stored before this release with a track but no elevation get their
+-- metres climbed from the track, in id order, resumable across restarts.
+-- NULL = not started, 'done' = finished.
+ALTER TABLE "app_settings" ADD COLUMN IF NOT EXISTS "workout_climb_backfill_cursor" TEXT;
diff --git a/prisma/schema.prisma b/prisma/schema.prisma
index d6eeead54..3ad51ba8e 100644
--- a/prisma/schema.prisma
+++ b/prisma/schema.prisma
@@ -5421,6 +5421,10 @@ model AppSettings {
   /// Last dry-run status and result (account ordinals only, no ids); the apply
   /// step's precondition and the admin card's result.
   pulseDayMeanDryRunJson Json?     @map("pulse_day_mean_dry_run_json")
+  /// @internal: progress marker of the one-time workout climb backfill
+  /// (`src/lib/workouts/climb-backfill.ts`): the last workout id scanned,
+  /// `done` when finished, NULL before it starts. Operational, never shown.
+  workoutClimbBackfillCursor String? @map("workout_climb_backfill_cursor")
 
   @@map("app_settings")
 }
diff --git a/src/__tests__/ai-egress-capability-guard.test.ts b/src/__tests__/ai-egress-capability-guard.test.ts
index 140c21f96..a63ae2a69 100644
--- a/src/__tests__/ai-egress-capability-guard.test.ts
+++ b/src/__tests__/ai-egress-capability-guard.test.ts
@@ -323,6 +323,8 @@ describe("workout route geometry never reaches an AI path", () => {
     "lib/jobs/free-text-encryption-backfill.ts":
       "Seals legacy readable tracks in place.",
     "lib/workouts/route-geometry-cipher.ts": "The cipher itself.",
+    "lib/workouts/climb-backfill.ts":
+      "One-time backfill: derives metres climbed into Workout.elevationM.",
   };
 
   /** Directories whose code feeds a model. */
diff --git a/src/app/api/health/__tests__/route.test.ts b/src/app/api/health/__tests__/route.test.ts
index 9c2ce8a16..f2f91a004 100644
--- a/src/app/api/health/__tests__/route.test.ts
+++ b/src/app/api/health/__tests__/route.test.ts
@@ -213,3 +213,19 @@ describe("GET /api/health while the background role starts", () => {
     }
   });
 });
+
+describe("GET /api/health — the `starting` window is bounded", () => {
+  it("drops the reason once a start outlasts any real boot", async () => {
+    const { markStartup, STARTING_MAX_MS } =
+      await import("@/lib/boot/startup-state");
+    vi.stubEnv("HEALTHLOG_PROCESS_TYPE", "web");
+    markStartup("starting", Date.now() - STARTING_MAX_MS - 1_000);
+    try {
+      const { response, body } = await health();
+      expect(response.status).toBe(503);
+      expect(body).toEqual({ status: "degraded" });
+    } finally {
+      markStartup("ready");
+    }
+  });
+});
diff --git a/src/instrumentation.ts b/src/instrumentation.ts
index 3f9cca282..f152e67ca 100644
--- a/src/instrumentation.ts
+++ b/src/instrumentation.ts
@@ -86,11 +86,30 @@ export async function register() {
     // the boss is not bound yet takes the same path as during a producer
     // reconnect: a garnish skips its enqueue (the owning cron catches up),
     // and a route that needs the worker answers 503 until it is up.
-    const [{ shouldRunWorker }, { markStartup }] = await Promise.all([
+    const [
+      { shouldRunWorker },
+      { markStartup, startupPhase, startupElapsedMs, STARTING_MAX_MS },
+    ] = await Promise.all([
       import("@/lib/process-type"),
       import("@/lib/boot/startup-state"),
     ]);
     markStartup("starting");
+    // One line when the start takes longer than any real boot; from then on
+    // the probe reports plain `degraded` instead of `starting`.
+    setTimeout(() => {
+      if (startupPhase() === "stalled") {
+        console.warn(
+          `[boot] The background role is still not up after ${Math.round(STARTING_MAX_MS / 1000)} s; /api/health now reports degraded without "starting".`,
+        );
+      }
+    }, STARTING_MAX_MS + 1_000).unref();
+    const ready = (up: boolean) => {
+      const elapsed = startupElapsedMs();
+      markStartup(up ? "ready" : "failed");
+      console.info(
+        `[boot] background role ${up ? "ready" : "failed"} after ${elapsed ?? 0} ms`,
+      );
+    };
     if (!shouldRunWorker()) {
       // Split deployment: web requests still produce queue jobs, but this
       // process owns no schedules, supervision, or consumers.
@@ -104,9 +123,9 @@ export async function register() {
               await import("@/lib/jobs/reminder/worker-lifecycle");
             registerShutdownHandlers(boss);
           }
-          markStartup(boss ? "ready" : "failed");
+          ready(boss !== null);
         } catch (err) {
-          markStartup("failed");
+          ready(false);
           // Queue-backed garnishes degrade independently; never make the web
           // server unavailable because its producer connection failed.
           console.error(
@@ -130,13 +149,13 @@ export async function register() {
         const { startReminderWorker } =
           await import("@/lib/jobs/reminder-worker");
         await startReminderWorker();
-        markStartup("ready");
+        ready(true);
 
         startupEvt.addMeta("reminder_worker", "started");
         startupEvt.finish();
         emitIfSampled(startupEvt.toJSON());
       } catch (err) {
-        markStartup("failed");
+        ready(false);
         startupEvt.setError(err);
         startupEvt.addMeta("reminder_worker", "failed");
         startupEvt.finish();
diff --git a/src/lib/boot/startup-state.ts b/src/lib/boot/startup-state.ts
index 59cd80a22..b7dfafd26 100644
--- a/src/lib/boot/startup-state.ts
+++ b/src/lib/boot/startup-state.ts
@@ -8,16 +8,48 @@
  * The probe reads this to say `starting` while that is under way rather than
  * hanging, and the operator sees a 503 that names a transient state.
  *
+ * The window is bounded. A start that has not finished after
+ * `STARTING_MAX_MS` is no longer reported as `starting`: it reads `stalled`,
+ * the probe drops the reason and says plainly `degraded`, and the process
+ * logs one line saying so. An uptime monitor therefore never sees the
+ * "transient" label for longer than a real boot takes.
+ *
  * `null` means no background role was started in this process at all.
  */
-export type StartupPhase = "starting" | "ready" | "failed";
+export type StartupPhase = "starting" | "ready" | "failed" | "stalled";
 
-const KEY = Symbol.for("healthlog.boot.startupPhase");
+/** Longest a start is still called `starting`. Prod boots take 10–60 s. */
+export const STARTING_MAX_MS = 5 * 60_000;
 
-export function markStartup(phase: StartupPhase): void {
-  (globalThis as Record<symbol, unknown>)[KEY] = phase;
+const KEY = Symbol.for("healthlog.boot.startupState");
+
+interface State {
+  phase: Exclude<StartupPhase, "stalled">;
+  since: number;
 }
 
-export function startupPhase(): StartupPhase | null {
-  return ((globalThis as Record<symbol, unknown>)[KEY] as StartupPhase) ?? null;
+function state(): State | undefined {
+  return (globalThis as Record<symbol, unknown>)[KEY] as State | undefined;
+}
+
+export function markStartup(
+  phase: Exclude<StartupPhase, "stalled">,
+  now: number = Date.now(),
+): void {
+  (globalThis as Record<symbol, unknown>)[KEY] = { phase, since: now };
+}
+
+export function startupPhase(now: number = Date.now()): StartupPhase | null {
+  const current = state();
+  if (!current) return null;
+  if (current.phase === "starting" && now - current.since > STARTING_MAX_MS) {
+    return "stalled";
+  }
+  return current.phase;
+}
+
+/** Milliseconds since the current phase began, or null before any start. */
+export function startupElapsedMs(now: number = Date.now()): number | null {
+  const current = state();
+  return current ? now - current.since : null;
 }
diff --git a/src/lib/jobs/reminder/register-maintenance.ts b/src/lib/jobs/reminder/register-maintenance.ts
index 4b32a0724..b0e02c042 100644
--- a/src/lib/jobs/reminder/register-maintenance.ts
+++ b/src/lib/jobs/reminder/register-maintenance.ts
@@ -15,6 +15,7 @@
  * `intake-slot-dedup-queue`, `tls-pin-monitor-queue`, and `geo-backfill`
  * guards read THIS module.
  */
+import { trackBackgroundTask } from "@/lib/logging/background-tasks";
 import { PgBoss } from "pg-boss";
 import { GEO_BACKFILL_QUEUE, GEO_BACKFILL_CRON } from "@/lib/jobs/geo-backfill";
 import {
@@ -2166,4 +2167,31 @@ export async function enqueueMaintenanceBootDiscovery(): Promise<void> {
       err,
     );
   }
+
+  // v1.44 — one-time climb backfill for workouts stored with a track but no
+  // elevation (`climb-backfill.ts`). Detached: it reads one track at a time
+  // with a pause between batches and resumes from its cursor on the next
+  // boot, so it never holds the boot or the heap. A finished pass returns at
+  // once.
+  trackBackgroundTask(
+    (async () => {
+      const [{ prisma }, { runWorkoutClimbBackfill }] = await Promise.all([
+        import("@/lib/db"),
+        import("@/lib/workouts/climb-backfill"),
+      ]);
+      const result = await runWorkoutClimbBackfill({ prisma });
+      if (result.scanned > 0) {
+        workerLog(
+          "info",
+          `[workout-climb-backfill] scanned=${result.scanned} filled=${result.filled} done=${result.done}`,
+        );
+      }
+    })().catch((err) => {
+      workerLog(
+        "error",
+        "[workout-climb-backfill] failed; the next boot resumes from the cursor",
+        err,
+      );
+    }),
+  );
 }
diff --git a/src/lib/workouts/__tests__/climb-backfill.test.ts b/src/lib/workouts/__tests__/climb-backfill.test.ts
new file mode 100644
index 000000000..26094032d
--- /dev/null
+++ b/src/lib/workouts/__tests__/climb-backfill.test.ts
@@ -0,0 +1,137 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  CLIMB_BACKFILL_DONE,
+  runWorkoutClimbBackfill,
+} from "../climb-backfill";
+
+/**
+ * An in-memory stand-in: workouts with an optional readable track (the
+ * legacy column, which `readRouteGeometry` falls back to) and the cursor.
+ */
+function fake(
+  workouts: Array<{
+    id: string;
+    elevationM: number | null;
+    coords?: number[][];
+  }>,
+  cursor: string | null = null,
+) {
+  const state = { cursor, reads: 0 };
+  const prisma = {
+    appSettings: {
+      findUnique: async () => ({ workoutClimbBackfillCursor: state.cursor }),
+      upsert: async (args: {
+        update: { workoutClimbBackfillCursor: string };
+      }) => {
+        state.cursor = args.update.workoutClimbBackfillCursor;
+        return {};
+      },
+    },
+    workout: {
+      findMany: async (args: {
+        where: { id?: { gt: string } };
+        take: number;
+      }) =>
+        workouts
+          .filter((w) => w.elevationM === null && w.coords)
+          .filter((w) => !args.where.id || w.id > args.where.id.gt)
+          .sort((a, b) => a.id.localeCompare(b.id))
+          .slice(0, args.take)
+          .map((w) => ({ id: w.id })),
+      updateMany: async (args: {
+        where: { id: string };
+        data: { elevationM: number };
+      }) => {
+        const w = workouts.find((x) => x.id === args.where.id)!;
+        if (w.elevationM !== null) return { count: 0 };
+        w.elevationM = args.data.elevationM;
+        return { count: 1 };
+      },
+    },
+    workoutRoute: {
+      findUnique: async (args: { where: { workoutId: string } }) => {
+        state.reads += 1;
+        const w = workouts.find((x) => x.id === args.where.workoutId);
+        return w?.coords
+          ? {
+              geometry: { type: "LineString", coordinates: w.coords },
+              geometryEncrypted: null,
+            }
+          : null;
+      },
+    },
+  };
+  return { prisma: prisma as never, state, workouts };
+}
+
+describe("runWorkoutClimbBackfill", () => {
+  it("fills the climb from the track and marks the pass done", async () => {
+    const f = fake([
+      {
+        id: "a",
+        elevationM: null,
+        coords: [
+          [8, 50, 100],
+          [8, 50, 160],
+          [8, 50, 140],
+        ],
+      },
+      {
+        id: "b",
+        elevationM: 12,
+        coords: [
+          [8, 50, 0],
+          [8, 50, 500],
+        ],
+      },
+      {
+        id: "c",
+        elevationM: null,
+        coords: [
+          [8, 50],
+          [8.1, 50.1],
+        ],
+      },
+      { id: "d", elevationM: null },
+    ]);
+    const result = await runWorkoutClimbBackfill({
+      prisma: f.prisma,
+      pauseMs: 0,
+    });
+    expect(result).toEqual({ scanned: 2, filled: 1, done: true });
+    expect(f.workouts.find((w) => w.id === "a")?.elevationM).toBe(60);
+    // A stored elevation is never overwritten; no altitude stays NULL.
+    expect(f.workouts.find((w) => w.id === "b")?.elevationM).toBe(12);
+    expect(f.workouts.find((w) => w.id === "c")?.elevationM).toBeNull();
+    expect(f.state.cursor).toBe(CLIMB_BACKFILL_DONE);
+  });
+
+  it("resumes after the cursor and never re-reads what it passed", async () => {
+    const many = Array.from({ length: 250 }, (_, i) => ({
+      id: `w${String(i).padStart(4, "0")}`,
+      elevationM: null as number | null,
+      coords: [[8, 50]] as number[][],
+    }));
+    const f = fake(many);
+    const first = await runWorkoutClimbBackfill({
+      prisma: f.prisma,
+      pauseMs: 0,
+      maxBatches: 1,
+    });
+    expect(first).toEqual({ scanned: 100, filled: 0, done: false });
+    expect(f.state.cursor).toBe("w0099");
+    const rest = await runWorkoutClimbBackfill({
+      prisma: f.prisma,
+      pauseMs: 0,
+    });
+    expect(rest).toEqual({ scanned: 150, filled: 0, done: true });
+    expect(f.state.reads).toBe(250);
+    const again = await runWorkoutClimbBackfill({
+      prisma: f.prisma,
+      pauseMs: 0,
+    });
+    expect(again).toEqual({ scanned: 0, filled: 0, done: true });
+    expect(f.state.reads).toBe(250);
+  });
+});
diff --git a/src/lib/workouts/climb-backfill.ts b/src/lib/workouts/climb-backfill.ts
new file mode 100644
index 000000000..c66983c84
--- /dev/null
+++ b/src/lib/workouts/climb-backfill.ts
@@ -0,0 +1,99 @@
+/**
+ * One-time backfill: metres climbed for workouts stored before v1.44.
+ *
+ * Since v1.44 a kept GPS track fills `Workout.elevationM` when the workout is
+ * written (`route-climb.ts`), and the workout insight reads only that column.
+ * Workouts stored earlier with a track but no elevation used to get their
+ * climb from the track when the insight was built; this pass writes it into
+ * the column once so they keep it.
+ *
+ * Bounded and resumable: workouts are taken in id order, `BATCH` ids at a
+ * time, and each track is opened, reduced to one number and dropped before
+ * the next is read, so memory holds one track at most. The last id is stored
+ * in `AppSettings.workoutClimbBackfillCursor` after every batch; a restart
+ * continues from there, and `done` ends it for good. A track without an
+ * altitude channel leaves the column NULL, as before; the cursor has moved
+ * past it, so it is never read again. Workouts written after the upgrade
+ * already carry their climb, so one pass in id order is complete.
+ *
+ * Not an AI path: the number lands on the workout row, nothing else.
+ */
+import type { PrismaClient } from "@/generated/prisma/client";
+import { readRouteGeometry } from "@/lib/workouts/route-geometry-cipher";
+import { routeClimbM } from "@/lib/workouts/route-climb";
+
+export const CLIMB_BACKFILL_DONE = "done";
+const BATCH = 100;
+const SETTINGS_ID = "singleton";
+
+export interface ClimbBackfillResult {
+  scanned: number;
+  filled: number;
+  done: boolean;
+}
+
+type Client = Pick<PrismaClient, "appSettings" | "workout" | "workoutRoute">;
+
+export async function runWorkoutClimbBackfill(input: {
+  prisma: Client;
+  /** Pause between batches so the pass never crowds out request traffic. */
+  pauseMs?: number;
+  /** Upper bound on batches in one run; the next run resumes. */
+  maxBatches?: number;
+}): Promise<ClimbBackfillResult> {
+  const {
+    prisma,
+    pauseMs = 250,
+    maxBatches = Number.POSITIVE_INFINITY,
+  } = input;
+  const settings = await prisma.appSettings.findUnique({
+    where: { id: SETTINGS_ID },
+    select: { workoutClimbBackfillCursor: true },
+  });
+  let cursor = settings?.workoutClimbBackfillCursor ?? null;
+  const result: ClimbBackfillResult = { scanned: 0, filled: 0, done: false };
+  if (cursor === CLIMB_BACKFILL_DONE) return { ...result, done: true };
+
+  for (let batch = 0; batch < maxBatches; batch += 1) {
+    const ids = await prisma.workout.findMany({
+      where: {
+        elevationM: null,
+        route: { isNot: null },
+        ...(cursor ? { id: { gt: cursor } } : {}),
+      },
+      orderBy: { id: "asc" },
+      take: BATCH,
+      select: { id: true },
+    });
+    for (const { id } of ids) {
+      result.scanned += 1;
+      const route = await prisma.workoutRoute.findUnique({
+        where: { workoutId: id },
+        select: { geometry: true, geometryEncrypted: true },
+      });
+      const climb = route ? routeClimbM(readRouteGeometry(route)) : null;
+      if (climb !== null) {
+        // Only where the column is still empty: a sync that wrote an
+        // elevation in the meantime wins.
+        const { count } = await prisma.workout.updateMany({
+          where: { id, elevationM: null },
+          data: { elevationM: climb },
+        });
+        result.filled += count;
+      }
+    }
+    const finished = ids.length < BATCH;
+    cursor = finished ? CLIMB_BACKFILL_DONE : ids[ids.length - 1].id;
+    await prisma.appSettings.upsert({
+      where: { id: SETTINGS_ID },
+      create: { id: SETTINGS_ID, workoutClimbBackfillCursor: cursor },
+      update: { workoutClimbBackfillCursor: cursor },
+    });
+    if (finished) {
+      result.done = true;
+      return result;
+    }
+    if (pauseMs > 0) await new Promise((r) => setTimeout(r, pauseMs));
+  }
+  return result;
+}
diff --git a/tests/integration/workout-routes-opt-in-migration.test.ts b/tests/integration/workout-routes-opt-in-migration.test.ts
new file mode 100644
index 000000000..7a31bd846
--- /dev/null
+++ b/tests/integration/workout-routes-opt-in-migration.test.ts
@@ -0,0 +1,86 @@
+/**
+ * Migration 0434: an account that already holds a stored workout track keeps
+ * the route opt-in ON after the upgrade; an account without one starts OFF.
+ *
+ * The container applies every migration before any row exists, so the test
+ * seeds both kinds of account and runs the migration's UPDATE again, read
+ * from the migration file itself rather than copied, so it tests the shipped
+ * statement.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { getPrismaClient, truncateAllTables } from "./setup";
+
+const MIGRATION = join(
+  process.cwd(),
+  "prisma/migrations/0434_workout_routes_keep_and_climb_cursor/migration.sql",
+);
+
+function shippedUpdate(): string {
+  const sql = readFileSync(MIGRATION, "utf8");
+  const match = /UPDATE "users"[\s\S]*?;\n/.exec(sql);
+  if (!match) throw new Error("0434 carries no UPDATE of users");
+  return match[0];
+}
+
+beforeEach(async () => {
+  await truncateAllTables(getPrismaClient());
+});
+
+describe("0434 — route opt-in for accounts that already keep tracks", () => {
+  it("turns it on only where a track is stored", async () => {
+    const prisma = getPrismaClient();
+    for (const id of ["with-route", "without-route", "workout-no-route"]) {
+      await prisma.user.create({
+        data: { id, username: id, email: `${id}@example.test` },
+      });
+    }
+    const started = new Date("2026-09-01T07:00:00Z");
+    const ended = new Date("2026-09-01T08:00:00Z");
+    const withRoute = await prisma.workout.create({
+      data: {
+        userId: "with-route",
+        sportType: "running",
+        startedAt: started,
+        endedAt: ended,
+        durationSec: 3600,
+        source: "APPLE_HEALTH",
+        externalId: "w-1",
+      },
+    });
+    await prisma.workoutRoute.create({
+      data: {
+        workoutId: withRoute.id,
+        geometryEncrypted: Buffer.from("sealed"),
+      },
+    });
+    await prisma.workout.create({
+      data: {
+        userId: "workout-no-route",
+        sportType: "running",
+        startedAt: started,
+        endedAt: ended,
+        durationSec: 3600,
+        source: "APPLE_HEALTH",
+        externalId: "w-2",
+      },
+    });
+
+    await prisma.$executeRawUnsafe(shippedUpdate());
+
+    const flags = Object.fromEntries(
+      (
+        await prisma.user.findMany({
+          select: { id: true, storeWorkoutRoutes: true },
+        })
+      ).map((u) => [u.id, u.storeWorkoutRoutes]),
+    );
+    expect(flags).toEqual({
+      "with-route": true,
+      "without-route": false,
+      "workout-no-route": false,
+    });
+  });
+});