From b3f61d0c75dcd560c8feb7d903f141af096d613d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 19:35:11 +0200
Subject: [PATCH 01/30] fix(medications): surface the first rolling dose at the
 start date
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rolling schedules anchored next-due on start + N days when no intake had
been logged yet, which skipped the dose due AT the start date and
suppressed its reminder (the worker shares this engine). The +N cadence
now begins only after the first intake is logged: with no intake the
first dose is due at startsOn (or createdAt). A past start date with no
intake surfaces the dose as due/overdue rather than rolling it forward —
nextOccurrenceAfter floors the rolling search to the start of the user's
day so an overdue or due-earlier-today dose stays visible.

The post-intake re-anchor (lastIntakeAt + N) and the endsOn cap are
unchanged; PRN, one-shot, RRULE and legacy cadences are unaffected.
---
 .../scheduling/__tests__/next-due.test.ts     | 120 ++++++++++++++++++
 .../scheduling/__tests__/recurrence.test.ts   | 115 ++++++++++++++++-
 src/lib/medications/scheduling/recurrence.ts  |  64 +++++++---
 3 files changed, 278 insertions(+), 21 deletions(-)
 create mode 100644 src/lib/medications/scheduling/__tests__/next-due.test.ts

diff --git a/src/lib/medications/scheduling/__tests__/next-due.test.ts b/src/lib/medications/scheduling/__tests__/next-due.test.ts
new file mode 100644
index 000000000..c80bcadd2
--- /dev/null
+++ b/src/lib/medications/scheduling/__tests__/next-due.test.ts
@@ -0,0 +1,120 @@
+/**
+ * v1.8.5 — `computeNextDueAt` tests, focused on the rolling-cadence
+ * first-dose semantics.
+ *
+ * The server computes `nextDueAt` by asking the canonical engine for the
+ * earliest next slot across a medication's schedules. The medically
+ * important case: a rolling course whose `startsOn` is earlier today with
+ * no intake logged must surface its start dose as DUE/OVERDUE ("take
+ * now"), not roll it forward by N days (which also suppressed its
+ * reminder, since the worker shares the engine).
+ */
+import { describe, expect, it } from "vitest";
+
+import { computeNextDueAt } from "../next-due";
+import type {
+  WorkerMedicationRow,
+  WorkerScheduleRow,
+} from "../worker-helpers";
+
+function d(iso: string): Date {
+  return new Date(iso);
+}
+
+function makeMedication(
+  overrides: Partial<WorkerMedicationRow> = {},
+): WorkerMedicationRow {
+  return {
+    id: "med-1",
+    startsOn: null,
+    endsOn: null,
+    oneShot: false,
+    createdAt: d("2026-01-01T00:00:00Z"),
+    ...overrides,
+  };
+}
+
+function makeRollingSchedule(
+  overrides: Partial<WorkerScheduleRow> = {},
+): WorkerScheduleRow {
+  return {
+    id: "sched-1",
+    windowStart: "08:00",
+    windowEnd: "09:00",
+    daysOfWeek: null,
+    timesOfDay: ["08:00"],
+    reminderGraceMinutes: null,
+    rrule: null,
+    rollingIntervalDays: 7,
+    scheduleType: "SCHEDULED",
+    cyclicOnWeeks: null,
+    cyclicOffWeeks: null,
+    ...overrides,
+  };
+}
+
+const BERLIN = "Europe/Berlin";
+
+function berlinDay(date: Date): string {
+  return new Intl.DateTimeFormat("en-CA", {
+    timeZone: BERLIN,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).format(date);
+}
+
+describe("computeNextDueAt — rolling first dose", () => {
+  it("surfaces an overdue first dose (past startsOn, no intake) as DUE today", () => {
+    const startsOn = d("2026-06-10T06:00:00Z"); // 08:00 Berlin slot is past
+    const now = d("2026-06-10T12:00:00Z"); // noon, after the slot
+    const next = computeNextDueAt({
+      medication: makeMedication({ startsOn }),
+      schedules: [makeRollingSchedule()],
+      now,
+      userTz: BERLIN,
+      lastIntakeAt: null,
+    });
+    expect(next).not.toBeNull();
+    expect(next!.getTime()).toBeLessThan(now.getTime()); // overdue
+    expect(berlinDay(next!)).toBe("2026-06-10");
+  });
+
+  it("returns the future first dose AT startsOn (no intake) without adding N", () => {
+    const startsOn = d("2026-06-12T00:00:00Z");
+    const now = d("2026-06-10T12:00:00Z");
+    const next = computeNextDueAt({
+      medication: makeMedication({ startsOn }),
+      schedules: [makeRollingSchedule()],
+      now,
+      userTz: BERLIN,
+      lastIntakeAt: null,
+    });
+    expect(next).not.toBeNull();
+    expect(berlinDay(next!)).toBe("2026-06-12");
+  });
+
+  it("re-anchors on lastIntakeAt + N once an intake exists", () => {
+    const now = d("2026-06-10T12:00:00Z");
+    const next = computeNextDueAt({
+      medication: makeMedication({ startsOn: d("2026-06-01T00:00:00Z") }),
+      schedules: [makeRollingSchedule()],
+      now,
+      userTz: BERLIN,
+      lastIntakeAt: d("2026-06-09T08:00:00Z"),
+    });
+    expect(next).not.toBeNull();
+    expect(berlinDay(next!)).toBe("2026-06-16"); // 2026-06-09 + 7d
+  });
+
+  it("returns null when no schedules", () => {
+    const next = computeNextDueAt({
+      medication: makeMedication(),
+      schedules: [],
+      now: d("2026-06-10T12:00:00Z"),
+      userTz: BERLIN,
+      lastIntakeAt: null,
+    });
+    expect(next).toBeNull();
+  });
+});
diff --git a/src/lib/medications/scheduling/__tests__/recurrence.test.ts b/src/lib/medications/scheduling/__tests__/recurrence.test.ts
index 9dbfcb921..daaa9fa2b 100644
--- a/src/lib/medications/scheduling/__tests__/recurrence.test.ts
+++ b/src/lib/medications/scheduling/__tests__/recurrence.test.ts
@@ -279,9 +279,12 @@ describe("occurrencesBetween — rolling", () => {
     );
   });
 
-  it("rollingIntervalDays=7 + lastIntakeAt=null + startsOn=T-2d emits one at T+5d", () => {
+  it("rollingIntervalDays=7 + lastIntakeAt=null + future startsOn → first dose due AT startsOn (not startsOn+N)", () => {
+    // v1.8.5 — with no intake yet the FIRST rolling dose lands ON the
+    // start date, not start + N. A future startsOn therefore emits its
+    // slot at startsOn itself.
     const NOW = d("2026-06-10T12:00:00Z");
-    const startsOn = new Date(NOW.getTime() - 2 * 24 * 60 * 60 * 1000);
+    const startsOn = new Date(NOW.getTime() + 2 * 24 * 60 * 60 * 1000);
     const schedule = makeSchedule({
       rollingIntervalDays: 7,
       timesOfDay: ["08:00"],
@@ -294,7 +297,7 @@ describe("occurrencesBetween — rolling", () => {
     const to = new Date(NOW.getTime() + 14 * 24 * 60 * 60 * 1000);
     const slots = occurrencesBetween(schedule, from, to, ctx);
     expect(slots).toHaveLength(1);
-    const expectedDay = new Date(startsOn.getTime() + 7 * 24 * 60 * 60 * 1000);
+    // The slot is the start dose itself (startsOn), NOT startsOn + 7d.
     expect(
       new Intl.DateTimeFormat("en-CA", {
         timeZone: "Europe/Berlin",
@@ -308,10 +311,36 @@ describe("occurrencesBetween — rolling", () => {
         year: "numeric",
         month: "2-digit",
         day: "2-digit",
-      }).format(expectedDay),
+      }).format(startsOn),
     );
   });
 
+  it("rollingIntervalDays=7 + lastIntakeAt=null + startsOn=today → first dose due today", () => {
+    // Fresh rolling course starting today: the start dose is due today,
+    // not seven days out.
+    const startsOn = d("2026-06-10T00:00:00Z");
+    const schedule = makeSchedule({
+      rollingIntervalDays: 7,
+      timesOfDay: ["08:00"],
+    });
+    const ctx = makeCtx({
+      lastIntakeAt: null,
+      medication: { startsOn },
+    });
+    const from = d("2026-06-10T00:00:00Z");
+    const to = d("2026-06-24T23:59:59Z");
+    const slots = occurrencesBetween(schedule, from, to, ctx);
+    expect(slots).toHaveLength(1);
+    expect(
+      new Intl.DateTimeFormat("en-CA", {
+        timeZone: "Europe/Berlin",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+      }).format(slots[0].at),
+    ).toBe("2026-06-10");
+  });
+
   it("rolling terminates when endsOn falls before next-due", () => {
     const NOW = d("2026-06-10T12:00:00Z");
     const lastIntake = new Date(NOW.getTime() - 3 * 24 * 60 * 60 * 1000);
@@ -332,6 +361,84 @@ describe("occurrencesBetween — rolling", () => {
     );
     expect(slots).toHaveLength(0);
   });
+
+  it("nextOccurrenceAfter surfaces an overdue first dose (past startsOn, no intake) as DUE today", () => {
+    // v1.8.5 — a rolling course whose startsOn is earlier today with no
+    // intake logged yet must surface the start dose as DUE/OVERDUE, not
+    // roll it forward by N. The strict `> now` filter previously dropped
+    // it; the rolling branch now floors to the start of the user's day.
+    const startsOn = d("2026-06-10T06:00:00Z"); // 08:00 Berlin slot is past
+    const NOW = d("2026-06-10T12:00:00Z"); // noon — after the 08:00 slot
+    const schedule = makeSchedule({
+      rollingIntervalDays: 7,
+      timesOfDay: ["08:00"],
+    });
+    const ctx = makeCtx({
+      lastIntakeAt: null,
+      medication: { startsOn },
+    });
+    const next = nextOccurrenceAfter(schedule, NOW, ctx);
+    expect(next).not.toBeNull();
+    // The surfaced slot is today's start dose (08:00 Berlin), already in
+    // the past relative to NOW — i.e. overdue, "take now".
+    expect(next!.at.getTime()).toBeLessThan(NOW.getTime());
+    expect(
+      new Intl.DateTimeFormat("en-CA", {
+        timeZone: "Europe/Berlin",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+      }).format(next!.at),
+    ).toBe("2026-06-10");
+  });
+
+  it("nextOccurrenceAfter returns the future first dose AT startsOn (no intake) without adding N", () => {
+    const NOW = d("2026-06-10T12:00:00Z");
+    const startsOn = d("2026-06-12T00:00:00Z"); // 2 days out
+    const schedule = makeSchedule({
+      rollingIntervalDays: 7,
+      timesOfDay: ["08:00"],
+    });
+    const ctx = makeCtx({
+      lastIntakeAt: null,
+      medication: { startsOn },
+    });
+    const next = nextOccurrenceAfter(schedule, NOW, ctx);
+    expect(next).not.toBeNull();
+    expect(
+      new Intl.DateTimeFormat("en-CA", {
+        timeZone: "Europe/Berlin",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+      }).format(next!.at),
+    ).toBe("2026-06-12");
+  });
+
+  it("nextOccurrenceAfter re-anchors on lastIntakeAt + N after an intake", () => {
+    // The v1.8.4 re-anchor must stay: once an intake exists, the next
+    // slot is lastIntakeAt + N, NOT the start date.
+    const NOW = d("2026-06-10T12:00:00Z");
+    const lastIntake = d("2026-06-09T08:00:00Z");
+    const schedule = makeSchedule({
+      rollingIntervalDays: 7,
+      timesOfDay: ["08:00"],
+    });
+    const ctx = makeCtx({
+      lastIntakeAt: lastIntake,
+      medication: { startsOn: d("2026-06-01T00:00:00Z") },
+    });
+    const next = nextOccurrenceAfter(schedule, NOW, ctx);
+    expect(next).not.toBeNull();
+    expect(
+      new Intl.DateTimeFormat("en-CA", {
+        timeZone: "Europe/Berlin",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+      }).format(next!.at),
+    ).toBe("2026-06-16"); // 2026-06-09 + 7d
+  });
 });
 
 // ────────────────────────────────────────────────────────────────────
diff --git a/src/lib/medications/scheduling/recurrence.ts b/src/lib/medications/scheduling/recurrence.ts
index 6496ad39c..8b59e1bd5 100644
--- a/src/lib/medications/scheduling/recurrence.ts
+++ b/src/lib/medications/scheduling/recurrence.ts
@@ -16,10 +16,11 @@
  *   1. **One-shot** (`medication.oneShot === true`) — single slot at
  *      the anchor date, one per `timesOfDay` entry.
  *   2. **Rolling** (`schedule.rollingIntervalDays !== null`) — next
- *      slot is `lastIntakeAt + N days` (or `startsOn + N days` if
- *      the user has never logged an intake). Only the immediately
- *      next slot is emitted; further slots depend on the user
- *      actually logging the intake.
+ *      slot is `lastIntakeAt + N days`. With no intake yet the FIRST
+ *      dose is due AT `startsOn ?? createdAt` (not `+ N`); the `+ N`
+ *      cadence only begins once the first intake is logged. Only the
+ *      immediately next slot is emitted; further slots depend on the
+ *      user actually logging the intake.
  *   3. **RRULE** (`schedule.rrule !== null`) — RFC 5545 expansion
  *      via the `rrule` npm lib. Day-anchored dates are returned in
  *      UTC by the library; each `timesOfDay` entry is then applied
@@ -248,15 +249,19 @@ export function nextOccurrenceAfter(
   }
 
   // Rolling is also single-slot (only emits the immediately next).
+  //
+  // v1.8.5 — floor the search window to the start of the user's current
+  // day rather than the strict `after` instant. A rolling dose whose slot
+  // lands earlier today (a past `startsOn` with no intake, or an overdue
+  // `lastIntakeAt + N`) is DUE/OVERDUE and must surface as "take now",
+  // not be skipped by a strict `> now` filter. Flooring to start-of-day
+  // keeps a slot the user has not yet acted on visible through the rest
+  // of its due day instead of silently rolling it forward by N.
   if (schedule.rollingIntervalDays !== null) {
-    const slots = expandRolling(
-      schedule,
-      ctx,
-      new Date(after.getTime() + 1),
-      limit,
-    );
+    const dayFloor = startOfDayInTz(after, ctx.timeZone);
+    const slots = expandRolling(schedule, ctx, dayFloor, limit);
     for (const s of slots) {
-      if (s.at.getTime() <= after.getTime()) continue;
+      if (s.at.getTime() < dayFloor.getTime()) continue;
       if (cyclic && !isInCyclicOnWeek(s.at, schedule, ctx)) continue;
       return s;
     }
@@ -334,9 +339,21 @@ function expandOneShot(
 // ────────────────────────────────────────────────────────────────────
 
 /**
- * Rolling cadence — "every N days from last intake". Emits one
- * occurrence at `(lastIntakeAt ?? startsOn ?? createdAt) + N days`,
- * applied at the first `timesOfDay` entry (or `windowStart`).
+ * Rolling cadence — "every N days from last intake".
+ *
+ * Anchoring (v1.8.5 — medically-correct first dose):
+ *   - After an intake → next slot is `lastIntakeAt + N days` (the
+ *     v1.8.4 re-anchor). Logging a dose pushes the next one out by N.
+ *   - No intake yet → the FIRST dose is due AT `startsOn ?? createdAt`,
+ *     NOT `start + N`. A rolling course's first dose lands on the start
+ *     date; the `+ N` cadence only kicks in once the first intake is
+ *     logged. The pre-v1.8.5 engine emitted `start + N` here, which
+ *     silently skipped the start-date dose (and suppressed its reminder,
+ *     since the worker shares this engine).
+ *
+ * A past `startsOn` with no intake therefore surfaces the start dose as
+ * DUE/OVERDUE ("take now") via `nextOccurrenceAfter`'s rolling branch,
+ * rather than rolling it forward.
  *
  * Design choice: only the FIRST time-of-day entry is emitted even
  * when multiple are configured. The rolling semantic — "every N days
@@ -358,10 +375,13 @@ function expandRolling(
 ): Occurrence[] {
   const n = schedule.rollingIntervalDays;
   if (n === null || n <= 0) return [];
-  const anchor =
-    ctx.lastIntakeAt ?? ctx.medication.startsOn ?? ctx.medication.createdAt;
 
-  const nextDue = new Date(anchor.getTime() + n * DAY_MS);
+  // After an intake the next dose is N days out. With no intake yet the
+  // FIRST dose is the start date itself (no `+ N`) — see the doc comment.
+  const nextDue =
+    ctx.lastIntakeAt !== null
+      ? new Date(ctx.lastIntakeAt.getTime() + n * DAY_MS)
+      : ctx.medication.startsOn ?? ctx.medication.createdAt;
 
   // endsOn cap.
   if (
@@ -560,6 +580,16 @@ function applyTimeOfDayToDate(day: Date, hhmm: string, tz: string): Date {
   return guess;
 }
 
+/**
+ * The UTC instant of midnight (00:00 wall-clock) on `instant`'s day in
+ * the user's IANA timezone. Used by the rolling-cadence next-due search
+ * to floor the window to the start of the user's current day so an
+ * overdue / due-earlier-today rolling dose still surfaces.
+ */
+function startOfDayInTz(instant: Date, tz: string): Date {
+  return applyTimeOfDayToDate(instant, "00:00", tz);
+}
+
 function tzOffsetMinutes(date: Date, tz: string): number {
   const parts = wallClockInTz(date, tz);
   const asIfUtc = Date.UTC(

From ddb08b048ac84af4a19d84157a2a39043a87ba78 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 19:36:33 +0200
Subject: [PATCH 02/30] fix(medications): stop the delete confirm hanging in a
 spinner
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deleting a medication from the danger zone awaited a prefix-invalidate of
the "medications" key bundle before navigating. That bundle covers the
detail page's own active query, so the invalidation refetched the just-
deleted resource, hit a 404, retried with backoff, and never resolved —
the confirm button spun forever even though the delete had persisted.

Evict the detail query before invalidating, navigate to the list first,
then fire-and-forget the dependent-bundle invalidation. The busy state is
also cleared on the failed-response path. The detail query opts out of
retries so a deleted-resource refetch never burns a backoff cycle.
---
 src/app/medications/[id]/page.tsx             |  5 ++++
 .../sections/destructive-zone-section.tsx     | 30 +++++++++++++++----
 2 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/src/app/medications/[id]/page.tsx b/src/app/medications/[id]/page.tsx
index 4ce75cc2a..4f5a5aa93 100644
--- a/src/app/medications/[id]/page.tsx
+++ b/src/app/medications/[id]/page.tsx
@@ -132,6 +132,11 @@ export default function MedicationDetailPage({
       return (await res.json()).data as MedicationDetailSnapshot;
     },
     enabled: isAuthenticated,
+    // A deleted medication 404s here. Don't burn a retry/backoff cycle on
+    // a resource that no longer exists — the delete handler evicts this
+    // key on success, but `retry: false` hardens any caller that
+    // prefix-invalidates `["medications"]` while this page is mounted.
+    retry: false,
   });
 
   // v1.7.2 W3 — derive the wizard payload purely to feed the read-only
diff --git a/src/components/medications/sections/destructive-zone-section.tsx b/src/components/medications/sections/destructive-zone-section.tsx
index 16888ed9a..29d617ed0 100644
--- a/src/components/medications/sections/destructive-zone-section.tsx
+++ b/src/components/medications/sections/destructive-zone-section.tsx
@@ -47,7 +47,11 @@ import { Card } from "@/components/ui/card";
 import { Separator } from "@/components/ui/separator";
 import { Switch } from "@/components/ui/switch";
 import { useTranslations } from "@/lib/i18n/context";
-import { invalidateKeys, medicationDependentKeys } from "@/lib/query-keys";
+import {
+  invalidateKeys,
+  medicationDependentKeys,
+  queryKeys,
+} from "@/lib/query-keys";
 
 const PAUSE_SWITCH_ID = "medication-detail-pause-switch";
 const PAUSE_TITLE_ID = "medication-detail-pause-title";
@@ -283,15 +287,29 @@ export function DangerZoneBody({
       });
       if (!res.ok) {
         toast.error(t("medications.detail.zone.delete.failed"));
+        setTier3bBusy(false);
         return;
       }
-      // Cache cascade first so the list page paints without the
-      // medication, then route. The bundle includes
-      // `compliance-chart-inline` so the inline chart's stale cache
-      // evicts before the user lands on the list.
-      await invalidateKeys(queryClient, medicationDependentKeys);
+      // Drop the deleted medication's own detail query before the
+      // prefix-invalidate below. `medicationDependentKeys` carries
+      // `["medications"]`, which covers the active `["medications", id]`
+      // detail query on this page; awaiting that invalidation refetched
+      // a now-404 resource, retried, and hung the spinner forever (the
+      // delete had already persisted server-side). `removeQueries`
+      // evicts the dead key so the prefix-invalidate can't refetch it.
+      queryClient.removeQueries({
+        queryKey: queryKeys.medicationDetail(medicationId),
+      });
+      // Navigate away first — we're leaving the detail page, so the
+      // dependent-bundle invalidation can settle in the background while
+      // the list page mounts and re-reads `["medications"]` fresh.
       toast.success(t("medications.detail.zone.delete.toast"));
+      setDeleteDialogOpen(false);
       router.push("/medications");
+      // Fire-and-forget the dependent-bundle invalidation (list /
+      // analytics / compliance / inline chart). Not awaited: navigation
+      // already happened and a transient refetch must not block it.
+      void invalidateKeys(queryClient, medicationDependentKeys);
     } catch {
       toast.error(t("medications.detail.zone.delete.failed"));
       setTier3bBusy(false);

From d660279c97f687bb6c7468e844672d04c609b1cb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 19:37:58 +0200
Subject: [PATCH 03/30] fix(medications): stop the wizard showing each
 time-of-day suggestion twice

The schedule wizard's time-of-day step rendered the four suggested times
twice: once as the icon chips from the step itself, and again as the
labelled preset row built into the chip component below. Add an opt-out
on the chip component and pass it from the step so only the icon-based
suggestions remain. The period is still conveyed by the icon plus an
aria-label; the offered times and selection logic are unchanged. The
preset row stays on by default for every other caller.
---
 .../scheduling/TimesOfDayChips.tsx            | 76 +++++++++++--------
 .../__tests__/TimesOfDayChips.test.tsx        | 18 +++++
 .../medications/wizard/steps/Step7Times.tsx   |  4 +
 3 files changed, 65 insertions(+), 33 deletions(-)

diff --git a/src/components/medications/scheduling/TimesOfDayChips.tsx b/src/components/medications/scheduling/TimesOfDayChips.tsx
index 3b01e87b3..b166b6293 100644
--- a/src/components/medications/scheduling/TimesOfDayChips.tsx
+++ b/src/components/medications/scheduling/TimesOfDayChips.tsx
@@ -46,6 +46,13 @@ export interface TimesOfDayChipsProps {
   disabled?: boolean;
   /** Translation namespace prefix. */
   i18nPrefix?: string;
+  /**
+   * Render the built-in Morning / Noon / Evening / Night preset row.
+   * Default `true`. The wizard's Step 7 supplies its own icon-based
+   * preset row, so it passes `false` to avoid showing each suggested
+   * time twice (the icon chip from Step 7 and the labelled chip here).
+   */
+  showPresets?: boolean;
 }
 
 /** Preset table — wall-clock HH:mm and i18n suffix key. */
@@ -106,6 +113,7 @@ export function TimesOfDayChips({
   maxChips = 8,
   disabled = false,
   i18nPrefix = "medications.scheduling.timesOfDay",
+  showPresets = true,
 }: TimesOfDayChipsProps) {
   const { t } = useTranslations();
   const inputId = useId();
@@ -165,38 +173,40 @@ export function TimesOfDayChips({
       aria-label={t(`${i18nPrefix}.label`)}
     >
       {/* Preset row */}
-      <div
-        role="group"
-        aria-label={t(`${i18nPrefix}.label`)}
-        className="flex flex-wrap gap-1.5"
-        data-slot="times-of-day-presets"
-      >
-        {PRESETS.map(({ key, value: preset }) => {
-          const isOn = sortedValue.includes(preset);
-          const label = `${t(`${i18nPrefix}.presets.${key}`)} ${preset}`;
-          return (
-            <button
-              key={key}
-              type="button"
-              disabled={disabled || (!isOn && atCap)}
-              aria-pressed={isOn}
-              aria-label={label}
-              data-slot="times-of-day-preset"
-              data-preset={key}
-              data-active={isOn ? "true" : "false"}
-              onClick={() => onPresetToggle(preset)}
-              className={[
-                "focus-visible:ring-ring inline-flex h-11 items-center gap-1 rounded-md border px-3 text-xs font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:opacity-50",
-                isOn
-                  ? "bg-primary text-primary-foreground border-primary"
-                  : "border-border bg-background text-foreground hover:bg-muted",
-              ].join(" ")}
-            >
-              {label}
-            </button>
-          );
-        })}
-      </div>
+      {showPresets && (
+        <div
+          role="group"
+          aria-label={t(`${i18nPrefix}.label`)}
+          className="flex flex-wrap gap-1.5"
+          data-slot="times-of-day-presets"
+        >
+          {PRESETS.map(({ key, value: preset }) => {
+            const isOn = sortedValue.includes(preset);
+            const label = `${t(`${i18nPrefix}.presets.${key}`)} ${preset}`;
+            return (
+              <button
+                key={key}
+                type="button"
+                disabled={disabled || (!isOn && atCap)}
+                aria-pressed={isOn}
+                aria-label={label}
+                data-slot="times-of-day-preset"
+                data-preset={key}
+                data-active={isOn ? "true" : "false"}
+                onClick={() => onPresetToggle(preset)}
+                className={[
+                  "focus-visible:ring-ring inline-flex h-11 items-center gap-1 rounded-md border px-3 text-xs font-medium transition-colors focus-visible:ring-2 focus-visible:outline-none disabled:opacity-50",
+                  isOn
+                    ? "bg-primary text-primary-foreground border-primary"
+                    : "border-border bg-background text-foreground hover:bg-muted",
+                ].join(" ")}
+              >
+                {label}
+              </button>
+            );
+          })}
+        </div>
+      )}
 
       {/* Chip list */}
       {sortedValue.length === 0 ? (
@@ -225,7 +235,7 @@ export function TimesOfDayChips({
                 disabled={disabled}
                 aria-label={`${t(`${i18nPrefix}.remove`)} ${time}`}
                 onClick={() => onRemove(time)}
-                className="focus-visible:ring-ring inline-flex h-7 w-7 items-center justify-center rounded-sm hover:bg-background focus-visible:outline-none focus-visible:ring-2 disabled:opacity-50"
+                className="focus-visible:ring-ring hover:bg-background inline-flex h-7 w-7 items-center justify-center rounded-sm focus-visible:ring-2 focus-visible:outline-none disabled:opacity-50"
                 data-slot="times-of-day-chip-remove"
               >
                 <X className="h-3.5 w-3.5" aria-hidden="true" />
diff --git a/src/components/medications/scheduling/__tests__/TimesOfDayChips.test.tsx b/src/components/medications/scheduling/__tests__/TimesOfDayChips.test.tsx
index 3e21c8193..61a5be8fe 100644
--- a/src/components/medications/scheduling/__tests__/TimesOfDayChips.test.tsx
+++ b/src/components/medications/scheduling/__tests__/TimesOfDayChips.test.tsx
@@ -143,4 +143,22 @@ describe("<TimesOfDayChips> — SSR render", () => {
     expect(html).not.toContain('data-slot="times-of-day-presets"');
     expect(html).toMatch(/value="09:30"/);
   });
+
+  it("suppresses the built-in preset row when showPresets is false", () => {
+    // The wizard's Step 7 supplies its own icon-based preset row; passing
+    // showPresets={false} keeps each suggested time from rendering twice.
+    const html = render(
+      <TimesOfDayChips value={["08:00"]} showPresets={false} onChange={NOOP} />,
+    );
+    expect(html).not.toContain('data-slot="times-of-day-presets"');
+    // The chip list (the actual selected values) still renders.
+    expect(html).toContain('data-slot="times-of-day-list"');
+  });
+
+  it("renders the preset row by default (showPresets defaults true)", () => {
+    const html = render(
+      <TimesOfDayChips value={["08:00"]} onChange={NOOP} />,
+    );
+    expect(html).toContain('data-slot="times-of-day-presets"');
+  });
 });
diff --git a/src/components/medications/wizard/steps/Step7Times.tsx b/src/components/medications/wizard/steps/Step7Times.tsx
index 54784c074..507ce5fa5 100644
--- a/src/components/medications/wizard/steps/Step7Times.tsx
+++ b/src/components/medications/wizard/steps/Step7Times.tsx
@@ -77,6 +77,10 @@ export function Step7Times({ payload, applyPartial }: StepProps) {
         value={payload.timesOfDay}
         onChange={(timesOfDay) => applyPartial({ timesOfDay })}
         maxChips={8}
+        // The icon-based preset row above already offers the four
+        // suggested times; suppress the chips' own labelled preset row so
+        // each suggestion isn't shown twice.
+        showPresets={false}
       />
     </div>
   );

From 5771b36899b4f62339783fb161e25ea2b145d1f6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 19:47:20 +0200
Subject: [PATCH 04/30] feat(insights): tighten category-page density and
 balance the overview hero
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Polish the Insights surfaces for a denser, more deliberate rhythm.

Category pages:
- Collapse the double caption under the heading. The explainer
  definition and the description paragraph used to stack, so every
  metric page opened with two near-duplicative muted lines before any
  data. Keep the explainer body as the single caption; render the
  description only when no explainer is set.
- Tighten the header gap (space-y-1.5) and the block rhythm
  (space-y-4 md:space-y-5) so the heading-to-first-data distance
  shrinks by roughly one text block.
- Demote the target summary from a full bordered card to an inline
  band (bg-muted/30 rounded-lg px-3 py-2). One line of range text no
  longer reserves the card primitive's py-4/py-6 shell padding.
- Close the gap under the assessment heading. The card primitive's
  gap-4/gap-6 flex gap floated the title well above its prose; override
  to gap-2 md:gap-3 with py-4/py-5 across every status variant.

Overview hero:
- Condense the "ask the coach" band — denser prompt chips and a
  bottom-pinned strip so the left column stops out-running the
  Health Score card.
- Give the Health Score breakdown more vertical presence (looser row
  rhythm, taller component bars) so the right column fills the row
  height instead of leaving the bottom empty.
---
 src/components/insights/health-score-card.tsx | 14 +++--
 src/components/insights/hero-strip.tsx        |  8 ++-
 .../insights/insight-status-card.tsx          | 21 +++++--
 .../insights/metric-target-summary.tsx        | 59 +++++++++++--------
 src/components/insights/sub-page-shell.tsx    | 19 ++++--
 src/components/insights/suggested-prompts.tsx | 14 ++++-
 6 files changed, 91 insertions(+), 44 deletions(-)

diff --git a/src/components/insights/health-score-card.tsx b/src/components/insights/health-score-card.tsx
index f2a3725b8..54a2e410c 100644
--- a/src/components/insights/health-score-card.tsx
+++ b/src/components/insights/health-score-card.tsx
@@ -265,7 +265,7 @@ export function HealthScoreCard({
           the bottom, and the card fills the row down to the
           "Wirkt mein Medikament?" chip — closing Marc's "Karte hört
           bei der Trennlinie auf" report against v1.4.36. */}
-      <div className="grid flex-1 grid-rows-[auto_auto_auto_auto_auto_1fr_auto] gap-3">
+      <div className="grid flex-1 grid-rows-[auto_auto_auto_auto_auto_1fr_auto] gap-3.5">
         <div className="flex items-center justify-between gap-2">
           <div className="flex min-w-0 items-center gap-2">
             <p
@@ -382,14 +382,20 @@ export function HealthScoreCard({
 
         <ul
           data-slot="health-score-card-components"
-          className="space-y-1.5 border-t pt-3"
+          // v1.8.5 W4a — the always-visible "Zusammensetzung" breakdown is
+          // the natural place to add weight to the Health-Score card so it
+          // fills the hero-row height instead of leaving the right column
+          // short and bottom-empty. Loosen the row rhythm (`space-y-2.5` vs
+          // `space-y-1.5`) and the divider stride (`pt-3.5`) so the four
+          // component bars read as a richer block; no new data, no new row.
+          className="space-y-2.5 border-t pt-3.5"
         >
           {componentEntries.map(({ key, label, value }) => (
             <li
               key={key}
               data-slot="health-score-card-component-row"
               data-component={key}
-              className="flex items-center gap-2 text-[11px]"
+              className="flex items-center gap-2 text-xs"
             >
               {/* v1.4.25 W3 — widened label column from w-16 (64px) to
                   w-24 (96px) so the longest German label
@@ -399,7 +405,7 @@ export function HealthScoreCard({
                 {label}
               </span>
               <div
-                className="bg-muted/50 h-1 flex-1 overflow-hidden rounded-full"
+                className="bg-muted/50 h-1.5 flex-1 overflow-hidden rounded-full"
                 aria-hidden="true"
               >
                 <div
diff --git a/src/components/insights/hero-strip.tsx b/src/components/insights/hero-strip.tsx
index 8dcef0aa1..83180be62 100644
--- a/src/components/insights/hero-strip.tsx
+++ b/src/components/insights/hero-strip.tsx
@@ -262,7 +262,13 @@ export function HeroStrip({
           {coachEnabled && (
             <div
               data-slot="insights-hero-strip-prompts"
-              className="border-border/50 border-t pt-4"
+              // v1.8.5 W4a — condense the "Coach fragen" band so the left
+              // column stops out-running the Health-Score card on the
+              // right. Tighter top padding (`pt-3` vs `pt-4`) plus a
+              // `mt-auto` push pins the chip strip to the bottom of the
+              // left column, so the recovered slack lands between the meta
+              // row and the prompts instead of stacking the column tall.
+              className="border-border/50 mt-auto border-t pt-3"
             >
               {/*
                * v1.4.20 phase B2b — chip clicks open the Coach drawer
diff --git a/src/components/insights/insight-status-card.tsx b/src/components/insights/insight-status-card.tsx
index c3e2b30d7..24f0f261f 100644
--- a/src/components/insights/insight-status-card.tsx
+++ b/src/components/insights/insight-status-card.tsx
@@ -57,6 +57,7 @@ export function InsightStatusCard({
         aria-busy="true"
         aria-live="polite"
         data-testid="insight-status-card-preparing"
+        className="gap-2 py-4 md:gap-3 md:py-5"
       >
         <CardHeader className="pb-2">
           <div className="flex items-center gap-2">
@@ -88,7 +89,12 @@ export function InsightStatusCard({
     // (`text-sm` → 0.875 rem) so the post-load swap reflows by less
     // than a row.
     return (
-      <Card aria-busy="true" aria-live="polite" data-testid="insight-status-card-loading">
+      <Card
+        aria-busy="true"
+        aria-live="polite"
+        data-testid="insight-status-card-loading"
+        className="gap-2 py-4 md:gap-3 md:py-5"
+      >
         <CardHeader className="pb-2">
           <div className="flex items-center gap-2">
             <div className="bg-muted h-5 w-5 animate-pulse rounded motion-reduce:animate-none" />
@@ -108,7 +114,7 @@ export function InsightStatusCard({
 
   if (!hasProvider) {
     return (
-      <Card className="opacity-60">
+      <Card className="gap-2 py-4 opacity-60 md:gap-3 md:py-5">
         <CardHeader className="pb-2">
           <div className="flex items-center gap-2">
             {icon}
@@ -126,7 +132,7 @@ export function InsightStatusCard({
 
   if (!text) {
     return (
-      <Card>
+      <Card className="gap-2 py-4 md:gap-3 md:py-5">
         <CardHeader className="pb-2">
           <div className="flex items-center gap-2">
             {icon}
@@ -150,7 +156,14 @@ export function InsightStatusCard({
     // on the success card closes the load→loaded transition signal.
     <Card
       aria-live="polite"
-      className="animate-insight-in border-l-dracula-purple border-l-2"
+      // v1.8.5 W4a — the `Card` primitive ships `gap-4 md:gap-6` as the flex
+      // gap between header and content, which floated the "Einschätzung"
+      // heading ~16-24 px above its prose. Override to `gap-2 md:gap-3` (the
+      // `CardHeader`'s own `pb-2` does not touch the flex gap) and trim the
+      // shell padding to `py-4 md:py-5` so the assessment block reads tight
+      // in the denser sub-page rhythm. The same override lands on every
+      // status variant below so the gap is consistent across states.
+      className="animate-insight-in border-l-dracula-purple gap-2 border-l-2 py-4 md:gap-3 md:py-5"
     >
       <CardHeader className="pb-2">
         <div className="flex items-center justify-between">
diff --git a/src/components/insights/metric-target-summary.tsx b/src/components/insights/metric-target-summary.tsx
index b2733a0a8..9844d67e9 100644
--- a/src/components/insights/metric-target-summary.tsx
+++ b/src/components/insights/metric-target-summary.tsx
@@ -7,7 +7,6 @@ import { Target } from "lucide-react";
 import { useAuth } from "@/hooks/use-auth";
 import { queryKeys } from "@/lib/query-keys";
 import { useTranslations } from "@/lib/i18n/context";
-import { Card, CardContent } from "@/components/ui/card";
 
 /**
  * v1.8.0 — surface the numeric target range + in-target share on each
@@ -143,31 +142,39 @@ export function MetricTargetSummary({ slug }: MetricTargetSummaryProps) {
     : null;
 
   return (
-    <Card data-slot="metric-target-summary">
-      <CardContent className="flex flex-wrap items-center justify-between gap-x-4 gap-y-2 py-3">
-        <div className="flex items-center gap-2.5">
-          <Target
-            className="text-dracula-green size-4 shrink-0"
-            aria-hidden="true"
-          />
-          <div className="space-y-0.5">
-            <p className="text-sm font-medium">{rangeLabel}</p>
-            {sharePct != null ? (
-              <p className="text-muted-foreground text-xs">
-                {t("insights.subPage.target.inTargetShare", {
-                  pct: sharePct,
-                })}
-              </p>
-            ) : null}
-          </div>
+    // v1.8.5 W4a — demote the target summary from a full bordered `Card`
+    // (which carried the primitive's `py-4 md:py-6` shell padding around a
+    // `py-3` content block — far too much vertical reserve for one line of
+    // range text) to a compact inline band. The green target glyph, the
+    // range string, the in-target share, and the "adjust" link all stay;
+    // only the wrapper shell changes so the block reads as a strip, not a
+    // card, in the tightened sub-page rhythm.
+    <div
+      data-slot="metric-target-summary"
+      className="bg-muted/30 flex flex-wrap items-center justify-between gap-x-4 gap-y-1.5 rounded-lg px-3 py-2"
+    >
+      <div className="flex items-center gap-2.5">
+        <Target
+          className="text-dracula-green size-4 shrink-0"
+          aria-hidden="true"
+        />
+        <div className="space-y-0.5">
+          <p className="text-sm font-medium">{rangeLabel}</p>
+          {sharePct != null ? (
+            <p className="text-muted-foreground text-xs">
+              {t("insights.subPage.target.inTargetShare", {
+                pct: sharePct,
+              })}
+            </p>
+          ) : null}
         </div>
-        <Link
-          href="/targets"
-          className="text-muted-foreground hover:text-foreground focus-visible:ring-ring/50 inline-flex min-h-11 items-center rounded-sm px-1 text-xs font-medium underline-offset-4 transition-colors hover:underline focus-visible:ring-2 focus-visible:outline-none"
-        >
-          {t("insights.subPage.target.adjustLink")}
-        </Link>
-      </CardContent>
-    </Card>
+      </div>
+      <Link
+        href="/targets"
+        className="text-muted-foreground hover:text-foreground focus-visible:ring-ring/50 inline-flex min-h-11 items-center rounded-sm px-1 text-xs font-medium underline-offset-4 transition-colors hover:underline focus-visible:ring-2 focus-visible:outline-none"
+      >
+        {t("insights.subPage.target.adjustLink")}
+      </Link>
+    </div>
   );
 }
diff --git a/src/components/insights/sub-page-shell.tsx b/src/components/insights/sub-page-shell.tsx
index b26575fe0..52f662488 100644
--- a/src/components/insights/sub-page-shell.tsx
+++ b/src/components/insights/sub-page-shell.tsx
@@ -100,8 +100,8 @@ export function SubPageShell({
   }, [focusOnMount]);
 
   return (
-    <div data-slot="insights-subpage" className="space-y-6">
-      <header className="space-y-2">
+    <div data-slot="insights-subpage" className="space-y-4 md:space-y-5">
+      <header className="space-y-1.5">
         <div className="flex flex-wrap items-center gap-2">
           <h1
             ref={headingRef}
@@ -129,9 +129,16 @@ export function SubPageShell({
         </div>
         {explainerMetric ? (
           // v1.8.4 — surface the explainer definition inline, reusing the
-          // exact body string the `?` popover reads. Muted caption styling
-          // matches the description paragraph below so the under-heading
-          // band reads as one calm block.
+          // exact body string the `?` popover reads.
+          //
+          // v1.8.5 W4a — render the explainer body as the *single* caption
+          // under the heading. Pre-v1.8.5 both this paragraph and the
+          // `description` below it stacked, so every metric page opened
+          // with two near-duplicative muted captions before any data — the
+          // root of the "airy / static under the heading" feel. The
+          // explainer body is the definition, so it wins; the description
+          // only renders when no explainer is set (the mother page and any
+          // future explainer-less sub-page).
           <p
             data-slot="metric-explainer-inline"
             className="text-muted-foreground text-sm leading-relaxed"
@@ -139,7 +146,7 @@ export function SubPageShell({
             {t(`insights.subPage.explainer.${explainerMetric}Body`)}
           </p>
         ) : null}
-        {description ? (
+        {description && !explainerMetric ? (
           <p className="text-muted-foreground text-sm">{description}</p>
         ) : null}
       </header>
diff --git a/src/components/insights/suggested-prompts.tsx b/src/components/insights/suggested-prompts.tsx
index bd117a85b..dce24bdb2 100644
--- a/src/components/insights/suggested-prompts.tsx
+++ b/src/components/insights/suggested-prompts.tsx
@@ -70,7 +70,10 @@ export function SuggestedPrompts({
   return (
     <div
       data-slot="insights-suggested-prompts"
-      className={cn("flex flex-wrap items-center gap-2", className)}
+      // v1.8.5 W4a — tighten the chip row gutter (`gap-1.5` vs `gap-2`) so
+      // the condensed Coach band reads as a dense, deliberate strip rather
+      // than an airy wrap. The chips themselves shrink their padding below.
+      className={cn("flex flex-wrap items-center gap-1.5", className)}
     >
       <span
         data-slot="insights-suggested-prompts-label"
@@ -84,10 +87,15 @@ export function SuggestedPrompts({
           type="button"
           onClick={() => onPick(prompt)}
           data-slot="insights-suggested-prompts-chip"
+          // v1.8.5 W4a — denser chips. The tap target stays comfortable
+          // (`min-h-9` ≈ 36 px, the WCAG/iOS floor) but the horizontal
+          // padding + type size drop a notch so five prompts pack into
+          // fewer rows and the left column stops towering over the
+          // Health-Score card.
           className={cn(
             "border-dracula-purple/18 hover:border-dracula-purple/40 hover:text-foreground",
-            "text-muted-foreground inline-flex min-h-11 items-center gap-1.5",
-            "rounded-full border bg-transparent px-3.5 py-2 text-[13px]",
+            "text-muted-foreground inline-flex min-h-9 items-center gap-1.5",
+            "rounded-full border bg-transparent px-3 py-1.5 text-xs",
             "transition-colors focus-visible:ring-2 focus-visible:outline-none",
             "focus-visible:ring-dracula-purple/50",
           )}

From 93790aa0431fef6d4b870a859b1bb09fd356ea3d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 19:48:08 +0200
Subject: [PATCH 05/30] feat(measurements): consolidate gait/mobility HealthKit
 metrics nightly

Extend the daily-mean consolidation to cover the high-frequency
gait/mobility metrics that previously mapped to no consolidation set and
piled up at sampling granularity: walking asymmetry, walking
double-support, walking steadiness, and walking heart-rate average. The
correct daily reduction for these is the mean, matching the Health-app
display; all four stay disjoint from the cumulative (sum) set.

Fold the daily-mean drain onto the existing nightly cumulative-drain tick
so new high-frequency spot samples no longer accumulate raw between worker
reboots. The two passes share one concurrency-1 cron, keeping the
maintenance window a single sequential walk. Boot-time discovery stays as
the back-fill for accounts that accumulated raw rows before this shipped.

Recompute the affected day's rollup bucket after the consolidation
commits, the same way the ingest path does, so a rollup-covered read
reflects the single consolidated row rather than a stale mean derived from
the now soft-deleted per-sample rows.

Regular heart-rate / pulse stays raw: it is a discrete clinical reading
and feeds correlation and scatter analytics. No schema change.
---
 ...server-to-ios-mean-metric-consolidation.md | 67 ++++++++++++++
 src/lib/jobs/reminder-worker.ts               | 30 ++++++
 .../__tests__/apple-health-mapping.test.ts    | 17 ++++
 .../__tests__/consolidate-daily-mean.test.ts  | 92 ++++++++++++++++++-
 src/lib/measurements/apple-health-mapping.ts  | 11 +++
 .../measurements/consolidate-daily-mean.ts    | 15 ++-
 .../consolidate-daily-mean.test.ts            | 56 +++++++++++
 7 files changed, 284 insertions(+), 4 deletions(-)
 create mode 100644 .planning/ios-coord/v1.8.5-server-to-ios-mean-metric-consolidation.md

diff --git a/.planning/ios-coord/v1.8.5-server-to-ios-mean-metric-consolidation.md b/.planning/ios-coord/v1.8.5-server-to-ios-mean-metric-consolidation.md
new file mode 100644
index 000000000..a694a1892
--- /dev/null
+++ b/.planning/ios-coord/v1.8.5-server-to-ios-mean-metric-consolidation.md
@@ -0,0 +1,67 @@
+# v1.8.5 — server folds high-frequency mean metrics nightly (informational, no iOS change)
+
+Direction: server → iOS. Status: informational + optional. No breaking
+change. iOS needs zero changes for correctness.
+
+## What changed on the server
+
+The server now consolidates the high-frequency HealthKit "spot" metrics
+into one canonical daily row per metric per day, server-side, on a nightly
+cron — the same treatment cumulative metrics (steps, energy, distance)
+already get. The daily reduction is the **MEAN** of the day's samples,
+written at local-noon under the existing
+`stats:<HKQuantityTypeIdentifier>:<YYYY-MM-DD>` externalId shape, and the
+per-sample rows are soft-deleted (tombstoned, pruned later).
+
+v1.8.5 extends the consolidated set to cover the gait/mobility metrics that
+previously piled up at sampling granularity:
+
+- `WalkingAsymmetryPercentage` (WALKING_ASYMMETRY)
+- `WalkingDoubleSupportPercentage` (WALKING_DOUBLE_SUPPORT)
+- `AppleWalkingSteadiness` (WALKING_STEADINESS)
+- `WalkingHeartRateAverage` (WALKING_HEART_RATE_AVERAGE)
+
+joining the metrics already folded since v1.7.0: `RespiratoryRate`,
+`EnvironmentalAudioExposure`, `HeadphoneAudioExposure`, `WalkingSpeed`,
+`WalkingStepLength`.
+
+The fold now runs on the nightly maintenance tick (alongside the cumulative
+drain), not just at worker boot. A 36-hour grace window keeps the current
+day's in-flight watch syncs raw so the live "today" view stays current.
+
+## What this means for iOS
+
+**Nothing is required.** Keep sending these metrics as per-sample rows with
+opaque UUID externalIds exactly as today. The server folds them nightly;
+the daily read path averages over the single consolidated row, so the
+metric pages and detail history read consistently with no client change.
+
+Existing accumulated per-sample rows are back-consolidated automatically on
+the first deploy by the boot-time discovery pass — no migration, no manual
+backfill.
+
+## Pulse is unchanged — still raw
+
+Regular heart-rate / `PULSE` is deliberately NOT consolidated. It is a
+discrete clinical reading and feeds correlation + scatter analytics, which
+read raw PULSE rows. Keep posting PULSE per-sample as today. Its display
+already daily-averages via the read-path AVG; storage stays raw.
+
+## Optional future optimisation (not required, not yet scheduled)
+
+If iOS later wants to cut upload volume for these mean metrics, it MAY send
+them pre-aggregated as a daily value under the same `stats:` shape it
+already uses for cumulative metrics — e.g.
+`stats:HKQuantityTypeIdentifierWalkingSpeed:2026-06-01`. The server's batch
+route already routes any `stats:*` externalId to the idempotent overwrite
+path, so no server change is needed to accept it.
+
+One caveat if iOS adopts this: for a mean metric the daily `stats:` value
+must carry the **average**, not the sum. Compute it on-device with
+`HKStatisticsCollectionQuery` using the `discreteAverage` option (NOT
+`cumulativeSum`, which is correct only for the cumulative metrics). The
+server-side nightly fold remains the safety net for any client not on that
+contract, so this stays a pure bandwidth optimisation rather than a
+correctness dependency.
+
+No `docs/api/openapi.yaml` change — the batch contract is unchanged.
diff --git a/src/lib/jobs/reminder-worker.ts b/src/lib/jobs/reminder-worker.ts
index d83ef925c..89054b608 100644
--- a/src/lib/jobs/reminder-worker.ts
+++ b/src/lib/jobs/reminder-worker.ts
@@ -118,6 +118,10 @@ import {
   drainPerSampleCumulative,
   DRAIN_CUMULATIVE_CUTOFF_HOURS,
 } from "@/lib/measurements/drain-per-sample-cumulative";
+import {
+  consolidateDailyMean,
+  MEAN_CONSOLIDATION_CUTOFF_HOURS,
+} from "@/lib/measurements/consolidate-daily-mean";
 import {
   STEP_CONSOLIDATION_QUEUE,
   STEP_CONSOLIDATION_CONCURRENCY,
@@ -2601,6 +2605,32 @@ export async function startReminderWorker() {
           recordError();
           workerLog("error", "[drain-cumulative] run failed", err);
         }
+
+        // v1.8.5 — fold the daily-MEAN drain onto the same nightly tick as
+        // the cumulative (SUM) drain. The mean drain was previously
+        // boot-discovery only, so between worker reboots new high-frequency
+        // spot samples (walking speed, respiratory rate, gait/mobility,
+        // audio exposure) accumulated raw. Running both passes on one
+        // concurrency-1 cron keeps the maintenance window a single
+        // sequential walk and never crowds the request pool. The global
+        // (no `userId`) signature drains every user; the 36-hour grace
+        // cutoff keeps today's in-flight watch syncs raw. Boot discovery
+        // stays as the back-fill for accounts that accumulated raw rows
+        // before this cron shipped.
+        try {
+          const meanSummary = await consolidateDailyMean(getWorkerPrisma(), {
+            dryRun: false,
+            cutoffHours: MEAN_CONSOLIDATION_CUTOFF_HOURS,
+            log: (line) => workerLog("info", line),
+          });
+          workerLog(
+            "info",
+            `[mean-consolidation] triggeredAt=${job.data.triggeredAt} usersScanned=${meanSummary.totals.usersScanned} daysConsolidated=${meanSummary.totals.daysConsolidated} perSampleRowsSoftDeleted=${meanSummary.totals.perSampleRowsSoftDeleted} dailyRowsUpserted=${meanSummary.totals.dailyRowsUpserted}`,
+          );
+        } catch (err) {
+          recordError();
+          workerLog("error", "[mean-consolidation] nightly run failed", err);
+        }
       }
     },
   );
diff --git a/src/lib/measurements/__tests__/apple-health-mapping.test.ts b/src/lib/measurements/__tests__/apple-health-mapping.test.ts
index b9adf88e7..0c30f9b4d 100644
--- a/src/lib/measurements/__tests__/apple-health-mapping.test.ts
+++ b/src/lib/measurements/__tests__/apple-health-mapping.test.ts
@@ -648,10 +648,27 @@ describe("HIGH_FREQUENCY_MEAN_TYPES (v1.7.0)", () => {
         "AUDIO_EXPOSURE_HEADPHONE",
         "WALKING_SPEED",
         "WALKING_STEP_LENGTH",
+        // v1.8.5 — the gait/mobility metrics that previously fell to no
+        // consolidation set and piled up raw at sampling granularity.
+        "WALKING_ASYMMETRY",
+        "WALKING_DOUBLE_SUPPORT",
+        "WALKING_STEADINESS",
+        "WALKING_HEART_RATE_AVERAGE",
       ].sort(),
     );
   });
 
+  it("consolidates the v1.8.5 gait/mobility metrics", () => {
+    for (const type of [
+      "WALKING_ASYMMETRY",
+      "WALKING_DOUBLE_SUPPORT",
+      "WALKING_STEADINESS",
+      "WALKING_HEART_RATE_AVERAGE",
+    ] as const) {
+      expect(HIGH_FREQUENCY_MEAN_TYPES.has(type)).toBe(true);
+    }
+  });
+
   it("every mean type resolves to a HealthKit identifier", () => {
     for (const type of HIGH_FREQUENCY_MEAN_TYPES) {
       expect(hkIdentifierForType(type)).not.toBeNull();
diff --git a/src/lib/measurements/__tests__/consolidate-daily-mean.test.ts b/src/lib/measurements/__tests__/consolidate-daily-mean.test.ts
index ff95152e6..33e5f8d36 100644
--- a/src/lib/measurements/__tests__/consolidate-daily-mean.test.ts
+++ b/src/lib/measurements/__tests__/consolidate-daily-mean.test.ts
@@ -1,4 +1,11 @@
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const { recomputeBucketsForMeasurement } = vi.hoisted(() => ({
+  recomputeBucketsForMeasurement: vi.fn().mockResolvedValue(undefined),
+}));
+vi.mock("@/lib/rollups/measurement-rollups", () => ({
+  recomputeBucketsForMeasurement,
+}));
 
 import {
   bucketMeanRows,
@@ -6,7 +13,7 @@ import {
   meanBucketValue,
 } from "../consolidate-daily-mean";
 import type { PerSampleRow } from "../drain-per-sample-cumulative";
-import type { PrismaClient } from "@/generated/prisma/client";
+import type { MeasurementType, PrismaClient } from "@/generated/prisma/client";
 
 function row(
   id: string,
@@ -14,10 +21,11 @@ function row(
   iso: string,
   externalId: string | null = null,
   unit = "m/s",
+  type: MeasurementType = "WALKING_SPEED",
 ): PerSampleRow {
   return {
     id,
-    type: "WALKING_SPEED",
+    type,
     value,
     measuredAt: new Date(iso),
     externalId,
@@ -25,6 +33,10 @@ function row(
   };
 }
 
+beforeEach(() => {
+  recomputeBucketsForMeasurement.mockClear();
+});
+
 describe("consolidate-daily-mean — reducer + bucketing", () => {
   it("computes the arithmetic mean of a per-day bucket", () => {
     const rows = [
@@ -141,6 +153,80 @@ describe("consolidateDailyMean — drain flow (mocked Prisma)", () => {
     };
     expect(updArg.data.deletedAt).toBeInstanceOf(Date);
     expect(summary.totals.daysConsolidated).toBe(1);
+
+    // T3 — the rollup DAY bucket must be recomputed for the touched
+    // (user, type, day) so a rollup-covered read does not serve a
+    // pre-drain mean derived from the now soft-deleted samples.
+    expect(recomputeBucketsForMeasurement).toHaveBeenCalledTimes(1);
+    const [uid, type, measuredAt] =
+      recomputeBucketsForMeasurement.mock.calls[0];
+    expect(uid).toBe("user-1");
+    expect(type).toBe("WALKING_SPEED");
+    expect(measuredAt).toBeInstanceOf(Date);
+  });
+
+  it("routes the v1.8.5 gait/mobility types through the drain", async () => {
+    const { mock, upsert } = buildPrismaMock({
+      WALKING_ASYMMETRY: [
+        row("a", 2.0, "2026-05-01T08:00:00.000Z", null, "%", "WALKING_ASYMMETRY"),
+        row("b", 4.0, "2026-05-01T09:00:00.000Z", null, "%", "WALKING_ASYMMETRY"),
+      ],
+      WALKING_HEART_RATE_AVERAGE: [
+        row(
+          "c",
+          90,
+          "2026-05-01T08:00:00.000Z",
+          null,
+          "count/min",
+          "WALKING_HEART_RATE_AVERAGE",
+        ),
+        row(
+          "d",
+          110,
+          "2026-05-01T09:00:00.000Z",
+          null,
+          "count/min",
+          "WALKING_HEART_RATE_AVERAGE",
+        ),
+      ],
+    });
+
+    const summary = await consolidateDailyMean(mock, { log: () => {} });
+
+    // One consolidated daily row per type — the day's MEAN, not the sum.
+    const byType = new Map(
+      upsert.mock.calls.map((c) => {
+        const arg = c[0] as {
+          where: { userId_type_source_externalId: { type: string } };
+          create: { value: number };
+        };
+        return [arg.where.userId_type_source_externalId.type, arg.create.value];
+      }),
+    );
+    expect(byType.get("WALKING_ASYMMETRY")).toBeCloseTo(3.0, 6);
+    expect(byType.get("WALKING_HEART_RATE_AVERAGE")).toBeCloseTo(100, 6);
+    expect(summary.totals.daysConsolidated).toBe(2);
+    // Recompute fires once per consolidated (type, day).
+    expect(recomputeBucketsForMeasurement).toHaveBeenCalledTimes(2);
+  });
+
+  it("never scans PULSE even alongside the gait types", async () => {
+    const { mock, findManyMeasurement } = buildPrismaMock({});
+    await consolidateDailyMean(mock, { log: () => {} });
+    const scannedTypes = findManyMeasurement.mock.calls.map(
+      (c) => (c[0] as { where: { type: string } }).where.type,
+    );
+    expect(scannedTypes).toContain("WALKING_ASYMMETRY");
+    expect(scannedTypes).toContain("WALKING_STEADINESS");
+    expect(scannedTypes).not.toContain("PULSE");
+  });
+
+  it("does not recompute on a dry-run", async () => {
+    const { mock } = buildPrismaMock({
+      WALKING_SPEED: [row("a", 1.0, "2026-05-01T08:00:00.000Z")],
+    });
+    await consolidateDailyMean(mock, { dryRun: true, log: () => {} });
+    expect(recomputeBucketsForMeasurement).not.toHaveBeenCalled();
   });
 
   it("passes the grace cutoff into the scan when cutoffHours is set", async () => {
diff --git a/src/lib/measurements/apple-health-mapping.ts b/src/lib/measurements/apple-health-mapping.ts
index 9ced6a938..4839bc4c5 100644
--- a/src/lib/measurements/apple-health-mapping.ts
+++ b/src/lib/measurements/apple-health-mapping.ts
@@ -527,6 +527,17 @@ export const HIGH_FREQUENCY_MEAN_TYPES: ReadonlySet<MeasurementType> = new Set<M
   "AUDIO_EXPOSURE_HEADPHONE",
   "WALKING_SPEED",
   "WALKING_STEP_LENGTH",
+  // v1.8.5 — the gait/mobility metrics Apple Health emits at sampling
+  // granularity (asymmetry/double-support per walk, walking heart-rate
+  // average per walk, steadiness as a near-daily rollup). They previously
+  // mapped to `latest` and belonged to no consolidation set, so every
+  // sample piled up raw. MEAN is the correct daily reduction and matches
+  // the Health-app display; all four stay disjoint from
+  // `CUMULATIVE_HK_TYPES`.
+  "WALKING_ASYMMETRY",
+  "WALKING_DOUBLE_SUPPORT",
+  "WALKING_STEADINESS",
+  "WALKING_HEART_RATE_AVERAGE",
 ]);
 
 /**
diff --git a/src/lib/measurements/consolidate-daily-mean.ts b/src/lib/measurements/consolidate-daily-mean.ts
index 5b66db328..555649734 100644
--- a/src/lib/measurements/consolidate-daily-mean.ts
+++ b/src/lib/measurements/consolidate-daily-mean.ts
@@ -12,7 +12,8 @@
  *
  * Scope per `HIGH_FREQUENCY_MEAN_TYPES`:
  *   RESPIRATORY_RATE, AUDIO_EXPOSURE_ENV, AUDIO_EXPOSURE_HEADPHONE,
- *   WALKING_SPEED, WALKING_STEP_LENGTH
+ *   WALKING_SPEED, WALKING_STEP_LENGTH, WALKING_ASYMMETRY,
+ *   WALKING_DOUBLE_SUPPORT, WALKING_STEADINESS, WALKING_HEART_RATE_AVERAGE
  *
  * PULSE is NOT in the set — correlation/scatter analytics read raw PULSE
  * rows. PULSE keeps raw storage; its display stays daily-averaged via
@@ -58,6 +59,7 @@ import {
   type DayWriteOutcome,
 } from "./consolidation-base";
 import { type PerSampleRow } from "./drain-per-sample-cumulative";
+import { recomputeBucketsForMeasurement } from "@/lib/rollups/measurement-rollups";
 
 /**
  * Grace window — rows newer than `now() - cutoffHours` stay raw so
@@ -241,6 +243,17 @@ export async function consolidateDailyMean(
         });
         removed = del.count;
       });
+
+      // T3 — recompute the affected (user, type, day) rollup buckets after
+      // the consolidation commits, the same way the batch route does on
+      // ingest. Without it, a rollup-covered read could serve a pre-drain
+      // mean derived from the now soft-deleted per-sample rows: the rollup
+      // tier reads only `deleted_at IS NULL`, so the stale DAY bucket must
+      // be re-aggregated against the single consolidated row. The
+      // canonical timestamp is local-noon of the consolidated day, which
+      // lands the recompute on the correct UTC day bucket.
+      await recomputeBucketsForMeasurement(userId, type, canonicalTimestamp);
+
       return { kind: "written", sourceRowsRemoved: removed };
     },
     recordBucket: ({
diff --git a/tests/integration/consolidate-daily-mean.test.ts b/tests/integration/consolidate-daily-mean.test.ts
index 1eeeceece..317e68a45 100644
--- a/tests/integration/consolidate-daily-mean.test.ts
+++ b/tests/integration/consolidate-daily-mean.test.ts
@@ -199,6 +199,62 @@ describe("consolidateDailyMean (real Postgres)", () => {
     expect(live).toHaveLength(2);
   });
 
+  it("consolidates a v1.8.5 gait type and recomputes the DAY rollup", async () => {
+    const prisma = getPrismaClient();
+    await prisma.measurement.createMany({
+      data: [
+        {
+          userId: TEST_USER_ID,
+          type: "WALKING_ASYMMETRY",
+          value: 2.0,
+          unit: "%",
+          source: "APPLE_HEALTH",
+          measuredAt: new Date("2026-05-16T08:00:00.000Z"),
+          externalId: "hk-asym-1",
+        },
+        {
+          userId: TEST_USER_ID,
+          type: "WALKING_ASYMMETRY",
+          value: 4.0,
+          unit: "%",
+          source: "APPLE_HEALTH",
+          measuredAt: new Date("2026-05-16T14:00:00.000Z"),
+          externalId: "hk-asym-2",
+        },
+      ],
+    });
+
+    const summary = await consolidateDailyMean(prisma, {
+      userId: TEST_USER_ID,
+      dryRun: false,
+      log: () => {},
+    });
+    expect(summary.totals.daysConsolidated).toBe(1);
+
+    // One live daily MEAN row carrying 3.0 (the mean of 2 + 4), not 6.
+    const live = await prisma.measurement.findMany({
+      where: {
+        userId: TEST_USER_ID,
+        type: "WALKING_ASYMMETRY",
+        deletedAt: null,
+      },
+    });
+    expect(live).toHaveLength(1);
+    expect(live[0].value).toBeCloseTo(3.0, 6);
+
+    // T3 — the DAY rollup bucket reflects the single consolidated row, not
+    // a pre-drain mean over the now soft-deleted samples.
+    const dayRollup = await prisma.measurementRollup.findMany({
+      where: {
+        userId: TEST_USER_ID,
+        type: "WALKING_ASYMMETRY",
+        granularity: "DAY",
+      },
+    });
+    expect(dayRollup).toHaveLength(1);
+    expect(dayRollup[0].mean).toBeCloseTo(3.0, 6);
+  });
+
   it("is idempotent — a second run is a no-op", async () => {
     const prisma = getPrismaClient();
     await prisma.measurement.createMany({

From 1fcc5ba96bab52c5a069d4634ac763c5c827510d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 19:51:08 +0200
Subject: [PATCH 06/30] feat(medications): adapt the compliance display to
 cadence density
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A rolling 7-/30-day percentage is meaningful for daily and weekday
medications but noise for sparse cadences: a med dosed every few weeks
has at most one expected dose in a 7-day window, so the bar swings
between 0 and 100 off a single sample.

Decide the display server-side from expected-dose density. When the
30-day window holds at least four expected doses the percentage bars
stay; below that the card swaps to an uptime-style per-dose timeline
where each cell is one expected dose — taken, missed, skipped or
upcoming — with a "last N doses" summary and a dose-indexed streak.

The compliance route returns an additive complianceDisplay block
(mode, expected7/30, the dose timeline, the summary) alongside the
existing compliance7/30 fields, which the iOS client and the Health
Score read unchanged. Read-path only; no schema change.

- compliance.ts: add expectedSlotsBetween and buildComplianceDisplay
  over the canonical recurrence engine
- dose-adherence-timeline: plain flex cells reusing the heatmap colour
  tokens and tap-to-pin tooltip
- switch the standard and GLP-1 cards on the server-decided mode
---
 messages/de.json                              |   7 +
 messages/en.json                              |   7 +
 messages/es.json                              |   7 +
 messages/fr.json                              |   7 +
 messages/it.json                              |   7 +
 messages/pl.json                              |   7 +
 .../[id]/compliance/__tests__/route.test.ts   |  95 ++++++
 .../api/medications/[id]/compliance/route.ts  |  26 +-
 .../card-parts/dose-adherence-timeline.tsx    | 173 +++++++++++
 .../medications/glp1-medication-card.tsx      |  46 ++-
 .../medications/medication-card.tsx           |  45 ++-
 .../analytics/__tests__/compliance.test.ts    | 275 +++++++++++++++++
 src/lib/analytics/compliance.ts               | 284 ++++++++++++++++++
 13 files changed, 967 insertions(+), 19 deletions(-)
 create mode 100644 src/components/medications/card-parts/dose-adherence-timeline.tsx

diff --git a/messages/de.json b/messages/de.json
index c55754cd6..5c21154dd 100644
--- a/messages/de.json
+++ b/messages/de.json
@@ -547,6 +547,13 @@
     "lastIntake": "Letzte Einnahme:",
     "nextIntake": "Nächste Einnahme:",
     "dayStreak": "Tage Serie",
+    "lastNDoses": "Letzte {total} Dosen: {taken} von {total}",
+    "doseStreak": "{count} in Folge",
+    "doseTimelineAriaLabel": "Jüngste Einnahmetreue",
+    "doseTaken": "Genommen",
+    "doseMissed": "Verpasst",
+    "doseSkipped": "Übersprungen",
+    "doseUpcoming": "Anstehend",
     "taken": "Genommen",
     "skipped": "Übersprungen",
     "intakeToastTaken": "{name} als genommen erfasst",
diff --git a/messages/en.json b/messages/en.json
index 2a3a1109a..6af21ada1 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -547,6 +547,13 @@
     "lastIntake": "Last intake:",
     "nextIntake": "Next intake:",
     "dayStreak": "day streak",
+    "lastNDoses": "Last {total} doses: {taken} of {total}",
+    "doseStreak": "{count} in a row",
+    "doseTimelineAriaLabel": "Recent dose adherence",
+    "doseTaken": "Taken",
+    "doseMissed": "Missed",
+    "doseSkipped": "Skipped",
+    "doseUpcoming": "Upcoming",
     "taken": "Taken",
     "skipped": "Skipped",
     "intakeToastTaken": "{name} recorded as taken",
diff --git a/messages/es.json b/messages/es.json
index 646426611..59eed95f0 100644
--- a/messages/es.json
+++ b/messages/es.json
@@ -547,6 +547,13 @@
     "lastIntake": "Última toma:",
     "nextIntake": "Próxima toma:",
     "dayStreak": "días de racha",
+    "lastNDoses": "Últimas {total} dosis: {taken} de {total}",
+    "doseStreak": "{count} seguidas",
+    "doseTimelineAriaLabel": "Adherencia reciente a las dosis",
+    "doseTaken": "Tomada",
+    "doseMissed": "Omitida",
+    "doseSkipped": "Saltada",
+    "doseUpcoming": "Próxima",
     "taken": "Tomada",
     "skipped": "Omitida",
     "intakeToastTaken": "{name} registrada como tomada",
diff --git a/messages/fr.json b/messages/fr.json
index 27f3d555d..029d00f7e 100644
--- a/messages/fr.json
+++ b/messages/fr.json
@@ -547,6 +547,13 @@
     "lastIntake": "Dernière prise :",
     "nextIntake": "Prochaine prise :",
     "dayStreak": "jours de série",
+    "lastNDoses": "{total} dernières doses : {taken} sur {total}",
+    "doseStreak": "{count} d'affilée",
+    "doseTimelineAriaLabel": "Observance récente des doses",
+    "doseTaken": "Pris",
+    "doseMissed": "Manqué",
+    "doseSkipped": "Ignoré",
+    "doseUpcoming": "À venir",
     "taken": "Pris",
     "skipped": "Sauté",
     "intakeToastTaken": "{name} enregistré comme pris",
diff --git a/messages/it.json b/messages/it.json
index 4b4417156..f28a7b9ac 100644
--- a/messages/it.json
+++ b/messages/it.json
@@ -547,6 +547,13 @@
     "lastIntake": "Ultima assunzione:",
     "nextIntake": "Prossima assunzione:",
     "dayStreak": "giorni di serie",
+    "lastNDoses": "Ultime {total} dosi: {taken} su {total}",
+    "doseStreak": "{count} di fila",
+    "doseTimelineAriaLabel": "Aderenza recente alle dosi",
+    "doseTaken": "Assunta",
+    "doseMissed": "Mancata",
+    "doseSkipped": "Saltata",
+    "doseUpcoming": "In arrivo",
     "taken": "Assunta",
     "skipped": "Saltata",
     "intakeToastTaken": "{name} registrata come assunta",
diff --git a/messages/pl.json b/messages/pl.json
index 87e160988..8e8098fe5 100644
--- a/messages/pl.json
+++ b/messages/pl.json
@@ -547,6 +547,13 @@
     "lastIntake": "Ostatnie przyjęcie:",
     "nextIntake": "Następne przyjęcie:",
     "dayStreak": "dni serii",
+    "lastNDoses": "Ostatnie {total} dawek: {taken} z {total}",
+    "doseStreak": "{count} z rzędu",
+    "doseTimelineAriaLabel": "Ostatnie przestrzeganie dawek",
+    "doseTaken": "Przyjęte",
+    "doseMissed": "Pominięte",
+    "doseSkipped": "Opuszczone",
+    "doseUpcoming": "Nadchodzące",
     "taken": "Przyjęte",
     "skipped": "Pominięte",
     "intakeToastTaken": "{name} oznaczone jako przyjęte",
diff --git a/src/app/api/medications/[id]/compliance/__tests__/route.test.ts b/src/app/api/medications/[id]/compliance/__tests__/route.test.ts
index 935f1b1f7..a281f05e5 100644
--- a/src/app/api/medications/[id]/compliance/__tests__/route.test.ts
+++ b/src/app/api/medications/[id]/compliance/__tests__/route.test.ts
@@ -115,6 +115,13 @@ async function callRoute(): Promise<Record<string, unknown>> {
   return body.data.dailyCompliance as Record<string, unknown>;
 }
 
+async function callRouteData(): Promise<Record<string, unknown>> {
+  const res = await GET(new Request("http://localhost"), ROUTE_PARAMS);
+  expect(res.status).toBe(200);
+  const body = await res.json();
+  return body.data as Record<string, unknown>;
+}
+
 describe("GET /api/medications/[id]/compliance — per-slot timing", () => {
   it("classifies both doses of a single-row twice-daily schedule as on_time (green cell)", async () => {
     const { start: dayStart } = dayBoundsForOffset(DAY_OFFSET);
@@ -239,3 +246,91 @@ describe("GET /api/medications/[id]/compliance — per-slot timing", () => {
     expect(entry!.onTime).toBe(1);
   });
 });
+
+// v1.8.5 — the additive `complianceDisplay` block. The server decides the
+// render mode from expected-dose density: a daily med keeps the percentage
+// bars (`"percent"`), a sparse rolling/long-interval med swaps to the
+// per-dose timeline (`"timeline"`). The existing `compliance7` /
+// `compliance30` fields stay untouched.
+describe("GET /api/medications/[id]/compliance — complianceDisplay", () => {
+  it("daily med → mode: percent", async () => {
+    vi.mocked(prisma.medication.findUnique).mockResolvedValue(
+      medication([
+        {
+          id: "sched-1",
+          windowStart: "08:00",
+          windowEnd: "09:00",
+          timesOfDay: ["08:00"],
+          daysOfWeek: null,
+          rrule: "FREQ=DAILY",
+          rollingIntervalDays: null,
+          reminderGraceMinutes: null,
+          scheduleType: "SCHEDULED",
+          cyclicOnWeeks: null,
+          cyclicOffWeeks: null,
+        },
+      ]) as never,
+    );
+    vi.mocked(prisma.medicationIntakeEvent.findMany).mockResolvedValue(
+      [] as never,
+    );
+
+    const data = await callRouteData();
+    const display = data.complianceDisplay as {
+      mode: string;
+      expected30: number;
+      minStableDoses: number;
+    };
+    expect(display.mode).toBe("percent");
+    expect(display.expected30).toBeGreaterThanOrEqual(display.minStableDoses);
+    // The legacy fields stay on the wire.
+    expect(data.compliance7).toBeDefined();
+    expect(data.compliance30).toBeDefined();
+  });
+
+  it("35-day-interval med → mode: timeline", async () => {
+    vi.mocked(prisma.medication.findUnique).mockResolvedValue(
+      {
+        id: "med-1",
+        userId: "user-1",
+        createdAt: new Date(Date.now() - 200 * 24 * 60 * 60 * 1000),
+        startsOn: new Date(Date.now() - 25 * 24 * 60 * 60 * 1000),
+        endsOn: null,
+        oneShot: false,
+        schedules: [
+          {
+            id: "sched-1",
+            windowStart: "10:00",
+            windowEnd: "11:00",
+            timesOfDay: ["10:00"],
+            daysOfWeek: null,
+            rrule: null,
+            rollingIntervalDays: 35,
+            reminderGraceMinutes: null,
+            scheduleType: "SCHEDULED",
+            cyclicOnWeeks: null,
+            cyclicOffWeeks: null,
+          },
+        ],
+      } as never,
+    );
+    // One past intake re-anchors the rolling cadence ~25 days ago, so the
+    // next slot lands beyond the 30-day window → <4 expected → timeline.
+    vi.mocked(prisma.medicationIntakeEvent.findMany).mockResolvedValue([
+      {
+        takenAt: new Date(Date.now() - 25 * 24 * 60 * 60 * 1000),
+        skipped: false,
+        scheduledFor: new Date(Date.now() - 25 * 24 * 60 * 60 * 1000),
+      },
+    ] as never);
+
+    const data = await callRouteData();
+    const display = data.complianceDisplay as {
+      mode: string;
+      expected30: number;
+      minStableDoses: number;
+    };
+    expect(display.mode).toBe("timeline");
+    expect(display.expected30).toBeLessThan(display.minStableDoses);
+  });
+});
diff --git a/src/app/api/medications/[id]/compliance/route.ts b/src/app/api/medications/[id]/compliance/route.ts
index b46d41a35..7dce9c68c 100644
--- a/src/app/api/medications/[id]/compliance/route.ts
+++ b/src/app/api/medications/[id]/compliance/route.ts
@@ -3,6 +3,7 @@ import { apiHandler, requireAuth } from "@/lib/api-handler";
 import { annotate } from "@/lib/logging/context";
 import { apiSuccess, apiError } from "@/lib/api-response";
 import {
+  buildComplianceDisplay,
   buildComplianceMedicationContext,
   calculateCompliance,
   classifyIntakeTiming,
@@ -141,6 +142,18 @@ export const GET = apiHandler(
       { medicationContext },
     );
 
+    // v1.8.5 — the additive display block. `mode` is server-decided from
+    // expected-dose density: dense cadences keep the 7-/30-day percentage
+    // bars (`"percent"`), sparse cadences (weekly, bi-/tri-weekly, rolling
+    // 35-day injections) swap to the per-dose uptime strip (`"timeline"`).
+    // `compliance7` / `compliance30` above are untouched — iOS + the Health
+    // Score read them verbatim.
+    const complianceDisplay = buildComplianceDisplay(
+      mapped,
+      medication.schedules,
+      medicationContext,
+    );
+
     // Build daily compliance map for heatmap/line chart (90 days)
     const now = new Date();
     const dailyCompliance: Record<string, DailyComplianceEntry> = {};
@@ -273,9 +286,18 @@ export const GET = apiHandler(
         entity_type: "medication",
         entity_id: id,
       },
-      meta: { compliance7: compliance7.rate, compliance30: compliance30.rate },
+      meta: {
+        compliance7: compliance7.rate,
+        compliance30: compliance30.rate,
+        displayMode: complianceDisplay.mode,
+      },
     });
 
-    return apiSuccess({ compliance7, compliance30, dailyCompliance });
+    return apiSuccess({
+      compliance7,
+      compliance30,
+      dailyCompliance,
+      complianceDisplay,
+    });
   },
 );
diff --git a/src/components/medications/card-parts/dose-adherence-timeline.tsx b/src/components/medications/card-parts/dose-adherence-timeline.tsx
new file mode 100644
index 000000000..fc305b54b
--- /dev/null
+++ b/src/components/medications/card-parts/dose-adherence-timeline.tsx
@@ -0,0 +1,173 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { Flame } from "lucide-react";
+
+import { useFormatters, useTranslations } from "@/lib/i18n/context";
+
+/**
+ * v1.8.5 — uptime-style per-dose adherence strip for sparse cadences.
+ *
+ * The medication cards keep the 7-/30-day percentage bars for dense
+ * cadences (daily / multi-daily / weekday meds) where the denominator is
+ * large enough for the percentage to be stable. For sparse cadences
+ * (weekly, bi-/tri-weekly, rolling 35-day injections) a rolling percentage
+ * swings violently off one sample and tells the user nothing; the server
+ * flips `complianceDisplay.mode` to `"timeline"` and this strip takes over.
+ *
+ * Each cell is one EXPECTED dose (not a calendar day), oldest → newest:
+ * taken=green / missed=red / skipped=grey / upcoming=outline. The color
+ * tokens and the tap-to-pin tooltip mirror the 90-day compliance heatmap
+ * (`src/components/charts/compliance-heatmap.tsx`) so the two surfaces read
+ * the same. Plain flex divs, not Recharts — a fixed-size status-cell row
+ * needs no chart container, axis, or tooltip plumbing.
+ */
+
+export type DoseStatus = "taken" | "missed" | "skipped" | "upcoming";
+export type DoseTiming = "early" | "on_time" | "late" | "very_late" | "missed";
+
+export interface DoseAdherenceCell {
+  scheduledFor: string;
+  status: DoseStatus;
+  takenAt: string | null;
+  timing: DoseTiming | null;
+  site: string | null;
+}
+
+interface DoseAdherenceTimelineProps {
+  doses: DoseAdherenceCell[];
+  summary: { taken: number; total: number; doseStreak: number };
+}
+
+// v1.4.27 MB7 / CF-10 precedent — clear the 14 px touch floor (with the
+// gap the row stays tap-friendly on narrow viewports). Mirrors the
+// heatmap's `CELL_FLOOR_PX`.
+const CELL_PX = 14;
+
+/** Token mirror of the heatmap's status palette. */
+function cellColor(status: DoseStatus, timing: DoseTiming | null): string {
+  if (status === "upcoming") return "transparent";
+  if (status === "skipped") return "var(--secondary)";
+  if (status === "missed") return "var(--dracula-red)";
+  // taken — shade by punctuality, same ladder the heatmap uses.
+  if (timing === "very_late") return "var(--dracula-orange)";
+  if (timing === "late") return "var(--dracula-yellow)";
+  return "var(--dracula-green)";
+}
+
+export function DoseAdherenceTimeline({
+  doses,
+  summary,
+}: DoseAdherenceTimelineProps) {
+  const { t } = useTranslations();
+  const fmt = useFormatters();
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const [tooltip, setTooltip] = useState<{
+    x: number;
+    y: number;
+    text: string;
+    pinned?: boolean;
+  } | null>(null);
+
+  // Mirror the heatmap: an outside tap clears a pinned tooltip so a touch
+  // user can dismiss the per-cell detail. Gated on `pinned` so the hover
+  // flow never pays the indirection.
+  useEffect(() => {
+    if (!tooltip?.pinned) return;
+    const handlePointer = (event: PointerEvent) => {
+      const container = containerRef.current;
+      if (!container) return;
+      if (!container.contains(event.target as Node)) setTooltip(null);
+    };
+    document.addEventListener("pointerdown", handlePointer, true);
+    return () => {
+      document.removeEventListener("pointerdown", handlePointer, true);
+    };
+  }, [tooltip?.pinned]);
+
+  function statusLabel(status: DoseStatus): string {
+    if (status === "taken") return t("medications.doseTaken");
+    if (status === "missed") return t("medications.doseMissed");
+    if (status === "skipped") return t("medications.doseSkipped");
+    return t("medications.doseUpcoming");
+  }
+
+  function cellText(cell: DoseAdherenceCell): string {
+    const when = fmt.dateTime(cell.scheduledFor);
+    return `${when} — ${statusLabel(cell.status)}`;
+  }
+
+  return (
+    <div className="space-y-2" ref={containerRef}>
+      <div className="relative">
+        <div
+          className="flex flex-wrap gap-1"
+          role="img"
+          aria-label={t("medications.doseTimelineAriaLabel")}
+        >
+          {doses.map((cell, i) => {
+            const isUpcoming = cell.status === "upcoming";
+            return (
+              <div
+                key={`${cell.scheduledFor}-${i}`}
+                className={`shrink-0 cursor-pointer rounded-sm ${
+                  isUpcoming ? "border-border border border-dashed" : ""
+                }`}
+                style={{
+                  width: CELL_PX,
+                  height: CELL_PX,
+                  backgroundColor: cellColor(cell.status, cell.timing),
+                }}
+                onPointerEnter={(e) => {
+                  if (e.pointerType === "touch") return;
+                  setTooltip({
+                    x: e.clientX,
+                    y: e.clientY,
+                    text: cellText(cell),
+                  });
+                }}
+                onPointerLeave={(e) => {
+                  if (e.pointerType === "touch") return;
+                  setTooltip((prev) => (prev?.pinned ? prev : null));
+                }}
+                onPointerDown={(e) => {
+                  if (e.pointerType !== "touch") return;
+                  setTooltip({
+                    x: e.clientX,
+                    y: e.clientY,
+                    text: cellText(cell),
+                    pinned: true,
+                  });
+                }}
+              />
+            );
+          })}
+        </div>
+
+        {tooltip && (
+          <div
+            className="bg-popover text-popover-foreground border-border pointer-events-none fixed z-50 rounded-md border px-2 py-1 text-xs shadow-md"
+            style={{ left: tooltip.x + 10, top: tooltip.y - 30 }}
+          >
+            {tooltip.text}
+          </div>
+        )}
+      </div>
+
+      <div className="text-muted-foreground flex items-center gap-3 text-xs">
+        <span>
+          {t("medications.lastNDoses", {
+            total: summary.total,
+            taken: summary.taken,
+          })}
+        </span>
+        {summary.doseStreak > 0 && (
+          <span className="text-dracula-orange flex items-center gap-1 font-medium">
+            <Flame className="h-3.5 w-3.5" />
+            {t("medications.doseStreak", { count: summary.doseStreak })}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/medications/glp1-medication-card.tsx b/src/components/medications/glp1-medication-card.tsx
index 0b8956ac0..f9db3485a 100644
--- a/src/components/medications/glp1-medication-card.tsx
+++ b/src/components/medications/glp1-medication-card.tsx
@@ -10,6 +10,10 @@ import { MedicationCardMenu } from "@/components/medications/medication-card-men
 import { MedicationStateBadges } from "@/components/medications/card-parts/medication-state-badges";
 import { MedicationStatusPill } from "@/components/medications/card-parts/medication-status-pill";
 import { MedicationComplianceBars } from "@/components/medications/card-parts/medication-compliance-bars";
+import {
+  DoseAdherenceTimeline,
+  type DoseAdherenceCell,
+} from "@/components/medications/card-parts/dose-adherence-timeline";
 import { MedicationIntakeActions } from "@/components/medications/card-parts/medication-intake-actions";
 import { useTranslations, useFormatters } from "@/lib/i18n/context";
 import {
@@ -91,9 +95,24 @@ export interface Glp1Medication {
   schedules: ScheduleLite[];
 }
 
+interface ComplianceDisplay {
+  mode: "percent" | "timeline";
+  expected7: number;
+  expected30: number;
+  minStableDoses: number;
+  doseTimeline: DoseAdherenceCell[];
+  recentDoseSummary: { taken: number; total: number; doseStreak: number };
+}
+
 interface ComplianceData {
   compliance7: { rate: number; streak: number };
   compliance30: { rate: number };
+  /**
+   * v1.8.5 — server-decided render mode. GLP-1 injections are commonly
+   * weekly, so this card flips to the per-dose timeline more often than
+   * the generic one. Additive — older mocks omit it.
+   */
+  complianceDisplay?: ComplianceDisplay;
 }
 
 interface DetailsResponse {
@@ -420,15 +439,24 @@ export function Glp1MedicationCard({
             Glp1InventoryDTO slot on /api/medications/[id]/glp1 stays
             in the response shape; only the web mounts are gone. */}
 
-        {/* Compliance bars — shared with the generic card so the page
-            grid stays harmonious. */}
-        {medication.active && compliance && (
-          <MedicationComplianceBars
-            rate7={rate7}
-            rate30={rate30}
-            streak={streak}
-          />
-        )}
+        {/* Compliance region — shared decision with the generic card.
+            Dense cadences keep the bars; sparse cadences (most weekly
+            GLP-1 injections) swap to the per-dose uptime strip. Falls back
+            to the bars when the older payload omits `complianceDisplay`. */}
+        {medication.active &&
+          compliance &&
+          (compliance.complianceDisplay?.mode === "timeline" ? (
+            <DoseAdherenceTimeline
+              doses={compliance.complianceDisplay.doseTimeline}
+              summary={compliance.complianceDisplay.recentDoseSummary}
+            />
+          ) : (
+            <MedicationComplianceBars
+              rate7={rate7}
+              rate30={rate30}
+              streak={streak}
+            />
+          ))}
 
         {/* Primary actions row — shared with the generic medication
             card. The GLP-1-specific side-effect quick-log lives in the
diff --git a/src/components/medications/medication-card.tsx b/src/components/medications/medication-card.tsx
index 47ebb329b..7d619eb22 100644
--- a/src/components/medications/medication-card.tsx
+++ b/src/components/medications/medication-card.tsx
@@ -9,6 +9,10 @@ import { MedicationCardMenu } from "@/components/medications/medication-card-men
 import { MedicationStateBadges } from "@/components/medications/card-parts/medication-state-badges";
 import { MedicationStatusPill } from "@/components/medications/card-parts/medication-status-pill";
 import { MedicationComplianceBars } from "@/components/medications/card-parts/medication-compliance-bars";
+import {
+  DoseAdherenceTimeline,
+  type DoseAdherenceCell,
+} from "@/components/medications/card-parts/dose-adherence-timeline";
 import { MedicationIntakeActions } from "@/components/medications/card-parts/medication-intake-actions";
 import { formatTimeWindowRange } from "@/lib/time-window-format";
 import { formatDateTime, formatTime } from "@/lib/format";
@@ -62,6 +66,15 @@ interface Medication {
   schedules: Schedule[];
 }
 
+interface ComplianceDisplay {
+  mode: "percent" | "timeline";
+  expected7: number;
+  expected30: number;
+  minStableDoses: number;
+  doseTimeline: DoseAdherenceCell[];
+  recentDoseSummary: { taken: number; total: number; doseStreak: number };
+}
+
 interface ComplianceData {
   compliance7: {
     totalExpected: number;
@@ -74,6 +87,12 @@ interface ComplianceData {
   compliance30: {
     rate: number;
   };
+  /**
+   * v1.8.5 — server-decided render mode for the compliance region. Dense
+   * cadences keep the 7-/30-day bars (`"percent"`); sparse cadences swap to
+   * the per-dose uptime strip (`"timeline"`). Additive — older mocks omit it.
+   */
+  complianceDisplay?: ComplianceDisplay;
 }
 
 interface MedicationCardProps {
@@ -327,14 +346,24 @@ export function MedicationCard({
           </p>
         )}
 
-        {/* Compliance bar */}
-        {medication.active && compliance && (
-          <MedicationComplianceBars
-            rate7={rate7}
-            rate30={rate30}
-            streak={streak}
-          />
-        )}
+        {/* Compliance region — the server decides whether the percentage
+            bars stay (dense cadences) or the per-dose uptime strip takes
+            over (sparse cadences). Falls back to the bars when the older
+            payload omits `complianceDisplay`. */}
+        {medication.active &&
+          compliance &&
+          (compliance.complianceDisplay?.mode === "timeline" ? (
+            <DoseAdherenceTimeline
+              doses={compliance.complianceDisplay.doseTimeline}
+              summary={compliance.complianceDisplay.recentDoseSummary}
+            />
+          ) : (
+            <MedicationComplianceBars
+              rate7={rate7}
+              rate30={rate30}
+              streak={streak}
+            />
+          ))}
 
         {/* Quick actions — primary buttons of the medication card. */}
         {medication.active && (
diff --git a/src/lib/analytics/__tests__/compliance.test.ts b/src/lib/analytics/__tests__/compliance.test.ts
index 9843df47a..6c9b91459 100644
--- a/src/lib/analytics/__tests__/compliance.test.ts
+++ b/src/lib/analytics/__tests__/compliance.test.ts
@@ -14,10 +14,13 @@
  */
 import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
 import {
+  MIN_STABLE_DOSES,
+  buildComplianceDisplay,
   buildComplianceMedicationContext,
   calculateCompliance,
   classifyIntakeTiming,
   expectedSlotCountForDay,
+  expectedSlotsBetween,
   lastNonSkippedTakenAt,
   type ComplianceMedicationContext,
   type ComplianceSchedule,
@@ -1019,3 +1022,275 @@ describe("classifyIntakeTiming", () => {
     );
   });
 });
+
+// v1.8.5 — the cadence-density rule + the per-dose uptime strip.
+// `buildComplianceDisplay` decides whether the card keeps the 7-/30-day
+// percentage bars (dense cadences) or swaps to a per-dose timeline
+// (sparse cadences). The 30-day window is the density yardstick.
+describe("buildComplianceDisplay — density rule + dose timeline", () => {
+  const NOW = new Date("2025-06-15T12:00:00Z");
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(NOW);
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  function ctx(
+    overrides: Partial<ComplianceMedicationContext> = {},
+  ): ComplianceMedicationContext {
+    return buildComplianceMedicationContext(
+      {
+        startsOn: overrides.startsOn ?? null,
+        endsOn: overrides.endsOn ?? null,
+        oneShot: overrides.oneShot ?? false,
+        // Created well before the windows so no day is excluded.
+        createdAt: overrides.createdAt ?? new Date("2025-01-01T00:00:00Z"),
+      },
+      overrides.lastIntakeAt ?? null,
+      overrides.timeZone ?? "UTC",
+    );
+  }
+
+  it("echoes the threshold so a client can re-derive the mode", () => {
+    const display = buildComplianceDisplay(
+      [],
+      [{ windowStart: "08:00", windowEnd: "09:00", daysOfWeek: null, rrule: "FREQ=DAILY", timesOfDay: ["08:00"] }],
+      ctx(),
+      { now: NOW },
+    );
+    expect(display.minStableDoses).toBe(MIN_STABLE_DOSES);
+  });
+
+  it("daily med → percent mode (30-day window clears the 4-dose floor)", () => {
+    const schedules: ComplianceSchedule[] = [
+      {
+        windowStart: "08:00",
+        windowEnd: "09:00",
+        daysOfWeek: null,
+        rrule: "FREQ=DAILY",
+        timesOfDay: ["08:00"],
+      },
+    ];
+    const display = buildComplianceDisplay([], schedules, ctx(), { now: NOW });
+    expect(display.mode).toBe("percent");
+    expect(display.expected30).toBeGreaterThanOrEqual(MIN_STABLE_DOSES);
+  });
+
+  it("35-day-interval med → timeline mode (sparse: <4 doses in 30 days)", () => {
+    // A monthly injection: one dose every 5 weeks. Anchored on a recent
+    // start so the engine emits at most one slot inside the 30-day window.
+    const schedules: ComplianceSchedule[] = [
+      {
+        windowStart: "10:00",
+        windowEnd: "11:00",
+        daysOfWeek: null,
+        rollingIntervalDays: 35,
+        timesOfDay: ["10:00"],
+      },
+    ];
+    const display = buildComplianceDisplay(
+      [],
+      schedules,
+      ctx({
+        startsOn: new Date("2025-05-01T00:00:00Z"),
+        // Rolling cadences re-anchor on the last non-skipped intake.
+        lastIntakeAt: new Date("2025-05-20T10:00:00Z"),
+      }),
+      { now: NOW },
+    );
+    expect(display.mode).toBe("timeline");
+    expect(display.expected30).toBeLessThan(MIN_STABLE_DOSES);
+  });
+
+  it("weekly med → timeline mode (≥4 needs ~28 days; 30d holds ~4 but <4 when phased)", () => {
+    // Weekly Mondays-only: across a 30-day trailing window this yields ~4
+    // Mondays. With a start mid-window the realised count drops below 4 →
+    // timeline. Pin the realised count rather than asserting a fixed mode
+    // independent of phase.
+    const schedules: ComplianceSchedule[] = [
+      {
+        windowStart: "08:00",
+        windowEnd: "09:00",
+        daysOfWeek: null,
+        rrule: "FREQ=WEEKLY;BYDAY=MO",
+        timesOfDay: ["08:00"],
+      },
+    ];
+    const display = buildComplianceDisplay(
+      [],
+      schedules,
+      ctx({ startsOn: new Date("2025-05-26T00:00:00Z") }),
+      { now: NOW },
+    );
+    // 2025-05-26 .. 2025-06-15 → Mondays 5/26, 6/2, 6/9 → 3 expected < 4.
+    expect(display.expected30).toBeLessThan(MIN_STABLE_DOSES);
+    expect(display.mode).toBe("timeline");
+  });
+
+  it("builds taken / missed / skipped cells from the paired engine timeline", () => {
+    // Weekly Mondays, three past Mondays inside the window: one taken on
+    // time, one skipped, one missed (no intake). The strip mirrors that.
+    const schedules: ComplianceSchedule[] = [
+      {
+        windowStart: "08:00",
+        windowEnd: "09:00",
+        daysOfWeek: null,
+        rrule: "FREQ=WEEKLY;BYDAY=MO",
+        timesOfDay: ["08:00"],
+      },
+    ];
+    const events = [
+      // 2025-06-09 Monday — taken on time.
+      {
+        scheduledFor: new Date("2025-06-09T08:00:00Z"),
+        takenAt: new Date("2025-06-09T08:10:00Z"),
+        skipped: false,
+      },
+      // 2025-06-02 Monday — skipped.
+      {
+        scheduledFor: new Date("2025-06-02T08:00:00Z"),
+        takenAt: null,
+        skipped: true,
+      },
+      // 2025-05-26 Monday — no event → missed.
+    ];
+    const display = buildComplianceDisplay(
+      events,
+      schedules,
+      ctx({ startsOn: new Date("2025-05-26T00:00:00Z") }),
+      { now: NOW },
+    );
+    const past = display.doseTimeline.filter((c) => c.status !== "upcoming");
+    const statuses = past.map((c) => c.status);
+    expect(statuses).toContain("taken");
+    expect(statuses).toContain("skipped");
+    expect(statuses).toContain("missed");
+
+    const takenCell = past.find((c) => c.status === "taken")!;
+    expect(takenCell.takenAt).not.toBeNull();
+    expect(takenCell.timing).toBe("on_time");
+
+    const skippedCell = past.find((c) => c.status === "skipped")!;
+    expect(skippedCell.takenAt).toBeNull();
+    expect(skippedCell.timing).toBeNull();
+
+    // Summary: taken counts in numerator + denominator; skipped excluded
+    // from both; missed in denominator only.
+    expect(display.recentDoseSummary.taken).toBe(1);
+    expect(display.recentDoseSummary.total).toBe(2); // taken + missed
+  });
+
+  it("dose-streak: counts consecutive taken-or-skipped back from the newest, breaks on a miss", () => {
+    // Weekly Mondays: 5/26 missed, 6/2 taken, 6/9 taken → newest-back
+    // streak = 2 (stops at the 5/26 miss).
+    const schedules: ComplianceSchedule[] = [
+      {
+        windowStart: "08:00",
+        windowEnd: "09:00",
+        daysOfWeek: null,
+        rrule: "FREQ=WEEKLY;BYDAY=MO",
+        timesOfDay: ["08:00"],
+      },
+    ];
+    const events = [
+      {
+        scheduledFor: new Date("2025-06-09T08:00:00Z"),
+        takenAt: new Date("2025-06-09T08:05:00Z"),
+        skipped: false,
+      },
+      {
+        scheduledFor: new Date("2025-06-02T08:00:00Z"),
+        takenAt: new Date("2025-06-02T08:05:00Z"),
+        skipped: false,
+      },
+      // 5/26 missed.
+    ];
+    const display = buildComplianceDisplay(
+      events,
+      schedules,
+      ctx({ startsOn: new Date("2025-05-26T00:00:00Z") }),
+      { now: NOW },
+    );
+    expect(display.recentDoseSummary.doseStreak).toBe(2);
+  });
+
+  it("caps the past strip at 12 cells for a dense daily med", () => {
+    const schedules: ComplianceSchedule[] = [
+      {
+        windowStart: "08:00",
+        windowEnd: "09:00",
+        daysOfWeek: null,
+        rrule: "FREQ=DAILY",
+        timesOfDay: ["08:00"],
+      },
+    ];
+    const display = buildComplianceDisplay([], schedules, ctx(), { now: NOW });
+    const past = display.doseTimeline.filter((c) => c.status !== "upcoming");
+    expect(past.length).toBeLessThanOrEqual(12);
+  });
+});
+
+describe("expectedSlotsBetween", () => {
+  function ctx(
+    overrides: Partial<ComplianceMedicationContext> = {},
+  ): ComplianceMedicationContext {
+    return buildComplianceMedicationContext(
+      {
+        startsOn: overrides.startsOn ?? null,
+        endsOn: overrides.endsOn ?? null,
+        oneShot: overrides.oneShot ?? false,
+        createdAt: overrides.createdAt ?? new Date("2025-01-01T00:00:00Z"),
+      },
+      overrides.lastIntakeAt ?? null,
+      overrides.timeZone ?? "UTC",
+    );
+  }
+
+  it("returns the occurrences themselves, ascending by instant", () => {
+    const schedules: ComplianceSchedule[] = [
+      {
+        windowStart: "08:00",
+        windowEnd: "09:00",
+        daysOfWeek: null,
+        rrule: "FREQ=DAILY",
+        timesOfDay: ["08:00", "20:00"],
+      },
+    ];
+    const slots = expectedSlotsBetween(
+      schedules,
+      new Date("2025-06-09T00:00:00Z"),
+      new Date("2025-06-10T23:59:59Z"),
+      ctx(),
+    );
+    // Two days × two times = four slots, ascending.
+    expect(slots.length).toBe(4);
+    for (let i = 1; i < slots.length; i++) {
+      expect(slots[i].at.getTime()).toBeGreaterThanOrEqual(
+        slots[i - 1].at.getTime(),
+      );
+    }
+  });
+
+  it("excludes PRN schedules from the expected slots", () => {
+    const schedules: ComplianceSchedule[] = [
+      {
+        windowStart: "08:00",
+        windowEnd: "09:00",
+        daysOfWeek: null,
+        scheduleType: "PRN",
+        rrule: "FREQ=DAILY",
+        timesOfDay: ["08:00"],
+      },
+    ];
+    const slots = expectedSlotsBetween(
+      schedules,
+      new Date("2025-06-09T00:00:00Z"),
+      new Date("2025-06-12T00:00:00Z"),
+      ctx(),
+    );
+    expect(slots.length).toBe(0);
+  });
+});
diff --git a/src/lib/analytics/compliance.ts b/src/lib/analytics/compliance.ts
index c2a34f004..072089900 100644
--- a/src/lib/analytics/compliance.ts
+++ b/src/lib/analytics/compliance.ts
@@ -23,12 +23,15 @@ import {
   buildCadenceTimeline,
   type CadenceEngineContext,
   type IntakeEventLike,
+  type PairedDose,
   type ScheduleLike,
 } from "@/lib/medications/scheduling/cadence";
 import {
   occurrencesBetween,
+  type Occurrence,
   type ScheduleType,
 } from "@/lib/medications/scheduling/recurrence";
+import type { InjectionSiteKey } from "@/lib/medications/injection-sites";
 
 interface IntakeEvent {
   takenAt: Date | null;
@@ -302,6 +305,287 @@ export function expectedSlotCountForDay(
   return count;
 }
 
+/**
+ * v1.8.5 — the sibling of {@link expectedSlotCountForDay} that returns the
+ * expected-dose occurrences *themselves* (ascending by instant) over an
+ * arbitrary window, rather than just the per-day count. Same loop, same
+ * canonical-engine delegation; we keep the slots so the dose-adherence
+ * timeline can pair each expected slot to its intake.
+ *
+ * Used by {@link buildComplianceDisplay} to decide the card's render mode
+ * (percent bars vs an uptime-style per-dose strip) and to build the strip.
+ * `occurrencesBetween` is inclusive of both ends; the caller passes a
+ * `[from, to]` window and we sort the union of every schedule's slots so
+ * a multi-schedule medication interleaves its slots in time order.
+ */
+export function expectedSlotsBetween(
+  schedules: ComplianceSchedule[],
+  from: Date,
+  to: Date,
+  ctx: ComplianceMedicationContext,
+): Occurrence[] {
+  const recurrenceCtx = {
+    medication: {
+      id: "compliance-slots",
+      startsOn: ctx.startsOn,
+      endsOn: ctx.endsOn,
+      oneShot: ctx.oneShot,
+      createdAt: ctx.createdAt,
+    },
+    timeZone: ctx.timeZone,
+    lastIntakeAt: ctx.lastIntakeAt,
+  };
+  const all: Occurrence[] = [];
+  for (let i = 0; i < schedules.length; i++) {
+    const s = schedules[i];
+    const canonical = {
+      id: `compliance-slots-${i}`,
+      rrule: s.rrule ?? null,
+      rollingIntervalDays: s.rollingIntervalDays ?? null,
+      timesOfDay: s.timesOfDay ?? [],
+      daysOfWeek: s.daysOfWeek ?? null,
+      windowStart: s.windowStart,
+      windowEnd: s.windowEnd,
+      reminderGraceMinutes: s.reminderGraceMinutes ?? null,
+      scheduleType: s.scheduleType ?? ("SCHEDULED" as const),
+      cyclicOnWeeks: s.cyclicOnWeeks ?? null,
+      cyclicOffWeeks: s.cyclicOffWeeks ?? null,
+    };
+    all.push(...occurrencesBetween(canonical, from, to, recurrenceCtx));
+  }
+  return all.sort((a, b) => a.at.getTime() - b.at.getTime());
+}
+
+/**
+ * v1.8.5 — render mode for the per-medication compliance display. A
+ * window's percentage is only meaningful once the denominator is large
+ * enough that a single miss moves the rate by a small amount; below that
+ * the bar swings violently and tells the user nothing. So:
+ *
+ * - `"percent"`: keep the 7-/30-day percentage bars (dense cadences:
+ *   daily, multi-daily, weekday meds). The window holds ≥
+ *   `MIN_STABLE_DOSES` expected doses.
+ * - `"timeline"`: swap to an uptime-style per-dose strip (sparse cadences:
+ *   weekly, bi-/tri-weekly, rolling 35-day injections) where each cell is
+ *   one expected dose, taken=green / missed=red / skipped=grey.
+ */
+export type ComplianceDisplayMode = "percent" | "timeline";
+
+/**
+ * v1.8.5 — one cell of the dose-adherence timeline. A projection of the
+ * canonical engine's expected-dose slots paired with the recorded intake,
+ * oldest → newest. `site` is reserved for injection meds so the strip can
+ * dual-encode rotation; it is `null` until the per-dose injection-site
+ * write path lands.
+ */
+export interface DoseTimelineCell {
+  /** ISO instant of the expected dose slot. */
+  scheduledFor: string;
+  status: "taken" | "missed" | "skipped" | "upcoming";
+  /** ISO instant the dose was logged, or null when not taken. */
+  takenAt: string | null;
+  /** Punctuality bucket for a taken dose; null when not taken. */
+  timing: IntakeTimingClass | null;
+  /** Injection zone for injection meds; null otherwise / when unrecorded. */
+  site: InjectionSiteKey | null;
+}
+
+/**
+ * v1.8.5 — the additive compliance-display block returned alongside the
+ * existing `compliance7` / `compliance30` fields (which iOS + the Health
+ * Score still read verbatim). The server decides `mode` from the density
+ * rule so the client stays dumb.
+ */
+export interface ComplianceDisplay {
+  mode: ComplianceDisplayMode;
+  /** Realised expected dose count over the 7-day window. */
+  expected7: number;
+  /** Realised expected dose count over the 30-day window. */
+  expected30: number;
+  /** Echo of the density threshold so a client can re-derive the mode. */
+  minStableDoses: number;
+  /** Uptime strip — last N expected dose slots, oldest → newest. */
+  doseTimeline: DoseTimelineCell[];
+  /** Compact summary for the "last N doses" line. */
+  recentDoseSummary: { taken: number; total: number; doseStreak: number };
+}
+
+/**
+ * v1.8.5 — the floor at which a window's percentage is stable. Four
+ * expected doses is the point where a single miss moves the rate by ≤25%
+ * rather than ±50–100%. A daily med clears it in 4 days; a weekly med
+ * needs ~28 days; a tri-weekly / 35-day-rolling med never clears it in a
+ * 30-day window — which is exactly the signal to show the timeline.
+ */
+export const MIN_STABLE_DOSES = 4;
+
+/** Number of past dose cells the card strip carries. */
+const TIMELINE_PAST_DOSES = 12;
+/** Number of upcoming dose cells appended so the strip shows what's next. */
+const TIMELINE_UPCOMING_DOSES = 2;
+
+/** A single paired dose, distilled into a timeline cell. */
+function toTimelineCell(dose: PairedDose): DoseTimelineCell {
+  const takenAt = dose.match?.takenAt ?? null;
+  return {
+    scheduledFor: dose.windowStart.toISOString(),
+    status: dose.status,
+    takenAt: takenAt ? takenAt.toISOString() : null,
+    // Punctuality is computed against the slot window the engine already
+    // emitted. `windowStart` / `windowEnd` are full instants here; reuse
+    // the HH:mm classifier by formatting them back to wall-clock on the
+    // slot's own day so an early / late dose reads correctly.
+    timing:
+      dose.status === "taken" && takenAt
+        ? classifyIntakeTiming(
+            takenAt,
+            hhmmOf(dose.windowStart),
+            hhmmOf(dose.windowEnd),
+            dose.windowStart,
+          )
+        : null,
+    // Injection-site dual-encoding is reserved for the per-dose write
+    // path; the compliance read does not yet carry it.
+    site: null,
+  };
+}
+
+/** Format a Date's UTC wall-clock as "HH:mm" for the punctuality classifier. */
+function hhmmOf(d: Date): string {
+  const h = String(d.getUTCHours()).padStart(2, "0");
+  const m = String(d.getUTCMinutes()).padStart(2, "0");
+  return `${h}:${m}`;
+}
+
+/**
+ * v1.8.5 — compute the additive {@link ComplianceDisplay} block.
+ *
+ * The mode is decided purely by density: when the 30-day window holds at
+ * least {@link MIN_STABLE_DOSES} expected doses the percentage bars stay
+ * (`"percent"`); otherwise the per-dose timeline takes over (`"timeline"`).
+ * The 30-day window is the honest denominator — a weekly med clears the
+ * floor there, a sparse injection never does.
+ *
+ * The timeline itself is a projection of {@link buildCadenceTimeline}: the
+ * engine already pairs each expected slot to its closest intake, so we
+ * take the last {@link TIMELINE_PAST_DOSES} past slots plus a couple of
+ * upcoming ones and distil each into a cell. `doseStreak` counts
+ * consecutive taken-or-skipped doses back from the newest non-upcoming
+ * dose — dose-indexed, unlike the day-indexed `streak` on
+ * {@link ComplianceResult} which inflates on off-cadence days.
+ */
+export function buildComplianceDisplay(
+  events: IntakeEvent[],
+  schedules: ComplianceSchedule[],
+  ctx: ComplianceMedicationContext,
+  options?: { now?: Date },
+): ComplianceDisplay {
+  const now = options?.now ?? new Date();
+  const DAY_MS = 24 * 60 * 60 * 1000;
+
+  // Realised expected counts over each window. `expectedSlotsBetween`
+  // already excludes PRN / off-cadence days through the canonical engine.
+  const from7 = new Date(now.getTime() - 7 * DAY_MS);
+  const from30 = new Date(now.getTime() - 30 * DAY_MS);
+  const expected7 = expectedSlotsBetween(schedules, from7, now, ctx).length;
+  const expected30 = expectedSlotsBetween(schedules, from30, now, ctx).length;
+
+  const mode: ComplianceDisplayMode =
+    expected30 >= MIN_STABLE_DOSES ? "percent" : "timeline";
+
+  // Build the per-dose strip from the same engine the cadence chart uses.
+  // Pull a generous past window (90 days) so even a 35-day-rolling med
+  // surfaces a few cells, then keep the last N plus a short look-ahead.
+  const engineCtx: CadenceEngineContext = {
+    startsOn: ctx.startsOn,
+    endsOn: ctx.endsOn,
+    oneShot: ctx.oneShot,
+    createdAt: ctx.createdAt,
+    lastIntakeAt: ctx.lastIntakeAt,
+    timeZone: ctx.timeZone,
+  };
+  const normalisedSchedules: ScheduleLike[] = schedules.map((s, i) => ({
+    id: `display-${i}`,
+    windowStart: s.windowStart,
+    windowEnd: s.windowEnd,
+    daysOfWeek: s.daysOfWeek ?? null,
+    rrule: s.rrule ?? null,
+    rollingIntervalDays: s.rollingIntervalDays ?? null,
+    timesOfDay: s.timesOfDay,
+    reminderGraceMinutes: s.reminderGraceMinutes ?? null,
+    scheduleType: s.scheduleType ?? null,
+    cyclicOnWeeks: s.cyclicOnWeeks ?? null,
+    cyclicOffWeeks: s.cyclicOffWeeks ?? null,
+  }));
+  const normalisedEvents: IntakeEventLike[] = events.map((e) => ({
+    scheduledFor: e.scheduledFor,
+    takenAt: e.takenAt,
+    skipped: e.skipped,
+  }));
+
+  // Past window for the strip — bounded so a daily med doesn't return
+  // hundreds of cells. `buildCadenceTimeline` anchors on `now - windowDays`
+  // and projects forward; a small look-ahead is added below.
+  const STRIP_PAST_DAYS = 90;
+  const past = buildCadenceTimeline(
+    normalisedSchedules,
+    normalisedEvents,
+    now,
+    STRIP_PAST_DAYS,
+    ctx.createdAt,
+    engineCtx.timeZone,
+    engineCtx,
+  )
+    .filter((d) => d.status !== "upcoming")
+    .sort((a, b) => a.windowStart.getTime() - b.windowStart.getTime());
+
+  // Upcoming slots — expand a short forward window and keep the soonest.
+  const lookahead = new Date(now.getTime() + 60 * DAY_MS);
+  const upcoming = buildCadenceTimeline(
+    normalisedSchedules,
+    normalisedEvents,
+    lookahead,
+    60,
+    ctx.createdAt,
+    engineCtx.timeZone,
+    engineCtx,
+  )
+    .filter((d) => d.status === "upcoming" && d.windowStart.getTime() > now.getTime())
+    .sort((a, b) => a.windowStart.getTime() - b.windowStart.getTime())
+    .slice(0, TIMELINE_UPCOMING_DOSES);
+
+  const recentPast = past.slice(-TIMELINE_PAST_DOSES);
+  const doseTimeline = [...recentPast, ...upcoming].map(toTimelineCell);
+
+  // Summary over the past cells the strip shows.
+  const summaryTaken = recentPast.filter((d) => d.status === "taken").length;
+  const summaryTotal = recentPast.filter(
+    (d) => d.status === "taken" || d.status === "missed",
+  ).length;
+
+  // Dose-streak: consecutive taken-or-skipped doses, newest → oldest, from
+  // the newest non-upcoming dose. A miss breaks it; a skip does not.
+  let doseStreak = 0;
+  for (let i = recentPast.length - 1; i >= 0; i--) {
+    const s = recentPast[i].status;
+    if (s === "missed") break;
+    if (s === "taken" || s === "skipped") doseStreak++;
+  }
+
+  return {
+    mode,
+    expected7,
+    expected30,
+    minStableDoses: MIN_STABLE_DOSES,
+    doseTimeline,
+    recentDoseSummary: {
+      taken: summaryTaken,
+      total: summaryTotal,
+      doseStreak,
+    },
+  };
+}
+
 /**
  * Calculate compliance for a medication over a given period.
  *

From 84e592b17eea35ffa965abed02793b12047c5e42 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 19:53:40 +0200
Subject: [PATCH 07/30] feat(insights): enrich the mood page with calendar,
 distribution, weekday, and correlation views
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lift the mood aggregates the AI status generator already computes —
tag frequency + per-tag average, in-target share, and the
mood × metric Pearson correlations — into a shared
`mood-aggregates.ts` so the prose and the new charts read off one
implementation. `mood-status.ts` now consumes the shared helpers
instead of its own inline copies.

Add a cached `/api/mood/insights` endpoint that returns the
pre-computed shapes (summary, heatmap, distribution, weekday, tags,
correlations) behind a 60-second server cache and a bounded 365-day
read — a cheap read-only path, never a synchronous model call. The
bucket invalidates alongside the mood-analytics cache on a mood write.

Render the shapes on the mood Insights page:

- a calendar heatmap forked from the compliance heatmap, coloured by
  the same mood-score bands as the line chart, with an adaptive
  window (30 days until ~90 days of history, then 90, then a full
  year past 180 days) so the grid is never mostly empty;
- a mood distribution bar chart (share of days per level);
- average mood by weekday with a best/toughest-day callout;
- a tag / trigger breakdown (frequency bars + per-tag average);
- mood vs. sleep / activity / pulse correlation cards reusing the
  existing scatter chart.

Add the supporting i18n keys across all six locales.
---
 messages/de.json                              |  45 +-
 messages/en.json                              |  45 +-
 messages/es.json                              |  45 +-
 messages/fr.json                              |  45 +-
 messages/it.json                              |  45 +-
 messages/pl.json                              |  45 +-
 src/app/api/mood/insights/route.ts            |  43 ++
 src/app/insights/mood/page.tsx                |   3 +
 src/components/charts/mood-heatmap.tsx        | 316 +++++++++++
 .../insights/mood/mood-correlation-cards.tsx  | 151 ++++++
 .../insights/mood/mood-distribution-chart.tsx | 100 ++++
 .../insights/mood/mood-insights-sections.tsx  | 143 +++++
 .../insights/mood/mood-tag-breakdown.tsx      |  63 +++
 .../insights/mood/mood-weekday-chart.tsx      | 144 +++++
 src/lib/cache/invalidate.ts                   |   3 +
 src/lib/cache/server-cache.ts                 |  12 +
 .../__tests__/mood-aggregates.test.ts         | 238 +++++++++
 src/lib/insights/mood-aggregates.ts           | 503 ++++++++++++++++++
 src/lib/insights/mood-status.ts               | 102 +---
 src/lib/query-keys.ts                         |   8 +
 20 files changed, 2003 insertions(+), 96 deletions(-)
 create mode 100644 src/app/api/mood/insights/route.ts
 create mode 100644 src/components/charts/mood-heatmap.tsx
 create mode 100644 src/components/insights/mood/mood-correlation-cards.tsx
 create mode 100644 src/components/insights/mood/mood-distribution-chart.tsx
 create mode 100644 src/components/insights/mood/mood-insights-sections.tsx
 create mode 100644 src/components/insights/mood/mood-tag-breakdown.tsx
 create mode 100644 src/components/insights/mood/mood-weekday-chart.tsx
 create mode 100644 src/lib/insights/__tests__/mood-aggregates.test.ts
 create mode 100644 src/lib/insights/mood-aggregates.ts

diff --git a/messages/de.json b/messages/de.json
index 5c21154dd..f80464152 100644
--- a/messages/de.json
+++ b/messages/de.json
@@ -1346,7 +1346,16 @@
     "personalBaseline": "Dein Mittel",
     "deltaVsBaseline": "{delta} vs. dein Mittel",
     "deltaUnchanged": "entspricht deinem Mittel",
-    "deltaVsTarget": "{delta} vs. Ziel"
+    "deltaVsTarget": "{delta} vs. Ziel",
+    "weekdaysFull": {
+      "mon": "Montag",
+      "tue": "Dienstag",
+      "wed": "Mittwoch",
+      "thu": "Donnerstag",
+      "fri": "Freitag",
+      "sat": "Samstag",
+      "sun": "Sonntag"
+    }
   },
   "chart": {
     "overlay": {
@@ -2275,7 +2284,39 @@
         "description": "Werte erscheinen hier, sobald Apple Health synchronisiert."
       }
     },
-    "navWalkingSpeed": "Gehgeschwindigkeit"
+    "navWalkingSpeed": "Gehgeschwindigkeit",
+    "mood": {
+      "heatmapTitle": "Stimmungskalender",
+      "heatmapNoEntry": "Kein Eintrag",
+      "legendGreat": "Super",
+      "legendGood": "Gut",
+      "legendOkay": "Okay",
+      "legendLow": "Niedrig",
+      "distributionTitle": "Stimmungsverteilung",
+      "distributionDaysUnit": "Tage",
+      "weekdayTitle": "Durchschnitt nach Wochentag",
+      "weekdayNoData": "Keine Daten",
+      "weekdayBestWorst": "Bester Tag: {best} · Schwerster Tag: {worst}",
+      "tagsTitle": "Tags und Auslöser",
+      "tagAvgMood": "Durchschnittliche Stimmung mit diesem Tag",
+      "correlationsTitle": "Stimmung und andere Werte",
+      "correlationsDescription": "Wie sich deine Stimmung am selben Tag mit Schlaf, Aktivität und Puls bewegt.",
+      "correlation": {
+        "sleepTitle": "Stimmung vs. Schlaf",
+        "stepsTitle": "Stimmung vs. Aktivität",
+        "pulseTitle": "Stimmung vs. Puls",
+        "sleepAxis": "Schlaf (Min.)",
+        "stepsAxis": "Schritte",
+        "pulseAxis": "Puls (bpm)",
+        "strengthStrong": "Stark",
+        "strengthModerate": "Moderat",
+        "strengthWeak": "Schwach",
+        "strengthNone": "Keine",
+        "source": "{n} gepaarte Tage · r = {r}",
+        "emptyTitle": "Noch nicht genug gepaarte Daten",
+        "emptyDescription": "Erfasse Stimmung und diesen Wert an denselben Tagen, um einen Zusammenhang zu sehen."
+      }
+    }
   },
   "thresholds": {
     "defaultLabel": "Default",
diff --git a/messages/en.json b/messages/en.json
index 6af21ada1..a27b5e425 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -1346,7 +1346,16 @@
     "personalBaseline": "Your normal",
     "deltaVsBaseline": "{delta} vs. your normal",
     "deltaUnchanged": "matches your normal",
-    "deltaVsTarget": "{delta} vs. target"
+    "deltaVsTarget": "{delta} vs. target",
+    "weekdaysFull": {
+      "mon": "Monday",
+      "tue": "Tuesday",
+      "wed": "Wednesday",
+      "thu": "Thursday",
+      "fri": "Friday",
+      "sat": "Saturday",
+      "sun": "Sunday"
+    }
   },
   "chart": {
     "overlay": {
@@ -2275,7 +2284,39 @@
         "description": "Walking-speed readings appear here once Apple Health syncs."
       }
     },
-    "navWalkingSpeed": "Walking Speed"
+    "navWalkingSpeed": "Walking Speed",
+    "mood": {
+      "heatmapTitle": "Mood calendar",
+      "heatmapNoEntry": "No entry",
+      "legendGreat": "Great",
+      "legendGood": "Good",
+      "legendOkay": "Okay",
+      "legendLow": "Low",
+      "distributionTitle": "Mood distribution",
+      "distributionDaysUnit": "days",
+      "weekdayTitle": "Average by weekday",
+      "weekdayNoData": "No data",
+      "weekdayBestWorst": "Best day: {best} · Toughest day: {worst}",
+      "tagsTitle": "Tags and triggers",
+      "tagAvgMood": "Average mood when tagged",
+      "correlationsTitle": "Mood and other metrics",
+      "correlationsDescription": "How your mood moves with sleep, activity, and pulse on the same day.",
+      "correlation": {
+        "sleepTitle": "Mood vs. sleep",
+        "stepsTitle": "Mood vs. activity",
+        "pulseTitle": "Mood vs. pulse",
+        "sleepAxis": "Sleep (min)",
+        "stepsAxis": "Steps",
+        "pulseAxis": "Pulse (bpm)",
+        "strengthStrong": "Strong",
+        "strengthModerate": "Moderate",
+        "strengthWeak": "Weak",
+        "strengthNone": "None",
+        "source": "{n} paired days · r = {r}",
+        "emptyTitle": "Not enough paired data yet",
+        "emptyDescription": "Log mood and this metric on the same days to see a correlation."
+      }
+    }
   },
   "thresholds": {
     "defaultLabel": "Default",
diff --git a/messages/es.json b/messages/es.json
index 59eed95f0..5c75fa700 100644
--- a/messages/es.json
+++ b/messages/es.json
@@ -1346,7 +1346,16 @@
     "personalBaseline": "Tu media",
     "deltaVsBaseline": "{delta} vs. tu media",
     "deltaUnchanged": "coincide con tu media",
-    "deltaVsTarget": "{delta} vs. objetivo"
+    "deltaVsTarget": "{delta} vs. objetivo",
+    "weekdaysFull": {
+      "mon": "Lunes",
+      "tue": "Martes",
+      "wed": "Miércoles",
+      "thu": "Jueves",
+      "fri": "Viernes",
+      "sat": "Sábado",
+      "sun": "Domingo"
+    }
   },
   "chart": {
     "overlay": {
@@ -2275,7 +2284,39 @@
         "description": "Las lecturas aparecen aquí cuando Apple Health sincroniza."
       }
     },
-    "navWalkingSpeed": "Velocidad al andar"
+    "navWalkingSpeed": "Velocidad al andar",
+    "mood": {
+      "heatmapTitle": "Calendario de ánimo",
+      "heatmapNoEntry": "Sin registro",
+      "legendGreat": "Genial",
+      "legendGood": "Bien",
+      "legendOkay": "Regular",
+      "legendLow": "Bajo",
+      "distributionTitle": "Distribución del ánimo",
+      "distributionDaysUnit": "días",
+      "weekdayTitle": "Promedio por día de la semana",
+      "weekdayNoData": "Sin datos",
+      "weekdayBestWorst": "Mejor día: {best} · Día más difícil: {worst}",
+      "tagsTitle": "Etiquetas y desencadenantes",
+      "tagAvgMood": "Ánimo promedio con esta etiqueta",
+      "correlationsTitle": "Ánimo y otras métricas",
+      "correlationsDescription": "Cómo se mueve tu ánimo con el sueño, la actividad y el pulso el mismo día.",
+      "correlation": {
+        "sleepTitle": "Ánimo vs. sueño",
+        "stepsTitle": "Ánimo vs. actividad",
+        "pulseTitle": "Ánimo vs. pulso",
+        "sleepAxis": "Sueño (min)",
+        "stepsAxis": "Pasos",
+        "pulseAxis": "Pulso (lpm)",
+        "strengthStrong": "Fuerte",
+        "strengthModerate": "Moderada",
+        "strengthWeak": "Débil",
+        "strengthNone": "Ninguna",
+        "source": "{n} días emparejados · r = {r}",
+        "emptyTitle": "Aún no hay suficientes datos emparejados",
+        "emptyDescription": "Registra el ánimo y esta métrica los mismos días para ver una correlación."
+      }
+    }
   },
   "thresholds": {
     "defaultLabel": "Por defecto",
diff --git a/messages/fr.json b/messages/fr.json
index 029d00f7e..477e1d1df 100644
--- a/messages/fr.json
+++ b/messages/fr.json
@@ -1346,7 +1346,16 @@
     "personalBaseline": "Ta moyenne",
     "deltaVsBaseline": "{delta} vs. ta moyenne",
     "deltaUnchanged": "correspond à ta moyenne",
-    "deltaVsTarget": "{delta} vs. cible"
+    "deltaVsTarget": "{delta} vs. cible",
+    "weekdaysFull": {
+      "mon": "Lundi",
+      "tue": "Mardi",
+      "wed": "Mercredi",
+      "thu": "Jeudi",
+      "fri": "Vendredi",
+      "sat": "Samedi",
+      "sun": "Dimanche"
+    }
   },
   "chart": {
     "overlay": {
@@ -2275,7 +2284,39 @@
         "description": "Les relevés apparaissent ici dès qu’Apple Health se synchronise."
       }
     },
-    "navWalkingSpeed": "Vitesse de marche"
+    "navWalkingSpeed": "Vitesse de marche",
+    "mood": {
+      "heatmapTitle": "Calendrier d'humeur",
+      "heatmapNoEntry": "Aucune entrée",
+      "legendGreat": "Excellent",
+      "legendGood": "Bien",
+      "legendOkay": "Correct",
+      "legendLow": "Bas",
+      "distributionTitle": "Répartition de l'humeur",
+      "distributionDaysUnit": "jours",
+      "weekdayTitle": "Moyenne par jour de la semaine",
+      "weekdayNoData": "Aucune donnée",
+      "weekdayBestWorst": "Meilleur jour : {best} · Jour le plus difficile : {worst}",
+      "tagsTitle": "Étiquettes et déclencheurs",
+      "tagAvgMood": "Humeur moyenne avec cette étiquette",
+      "correlationsTitle": "Humeur et autres mesures",
+      "correlationsDescription": "Comment votre humeur évolue avec le sommeil, l'activité et le pouls le même jour.",
+      "correlation": {
+        "sleepTitle": "Humeur vs. sommeil",
+        "stepsTitle": "Humeur vs. activité",
+        "pulseTitle": "Humeur vs. pouls",
+        "sleepAxis": "Sommeil (min)",
+        "stepsAxis": "Pas",
+        "pulseAxis": "Pouls (bpm)",
+        "strengthStrong": "Forte",
+        "strengthModerate": "Modérée",
+        "strengthWeak": "Faible",
+        "strengthNone": "Aucune",
+        "source": "{n} jours appariés · r = {r}",
+        "emptyTitle": "Pas encore assez de données appariées",
+        "emptyDescription": "Enregistrez l'humeur et cette mesure les mêmes jours pour voir une corrélation."
+      }
+    }
   },
   "thresholds": {
     "defaultLabel": "Par défaut",
diff --git a/messages/it.json b/messages/it.json
index f28a7b9ac..f8dffe04e 100644
--- a/messages/it.json
+++ b/messages/it.json
@@ -1346,7 +1346,16 @@
     "personalBaseline": "La tua media",
     "deltaVsBaseline": "{delta} vs. la tua media",
     "deltaUnchanged": "corrisponde alla tua media",
-    "deltaVsTarget": "{delta} vs. obiettivo"
+    "deltaVsTarget": "{delta} vs. obiettivo",
+    "weekdaysFull": {
+      "mon": "Lunedì",
+      "tue": "Martedì",
+      "wed": "Mercoledì",
+      "thu": "Giovedì",
+      "fri": "Venerdì",
+      "sat": "Sabato",
+      "sun": "Domenica"
+    }
   },
   "chart": {
     "overlay": {
@@ -2275,7 +2284,39 @@
         "description": "Le letture appaiono qui quando Apple Health si sincronizza."
       }
     },
-    "navWalkingSpeed": "Velocità di cammino"
+    "navWalkingSpeed": "Velocità di cammino",
+    "mood": {
+      "heatmapTitle": "Calendario dell'umore",
+      "heatmapNoEntry": "Nessun dato",
+      "legendGreat": "Ottimo",
+      "legendGood": "Buono",
+      "legendOkay": "Discreto",
+      "legendLow": "Basso",
+      "distributionTitle": "Distribuzione dell'umore",
+      "distributionDaysUnit": "giorni",
+      "weekdayTitle": "Media per giorno della settimana",
+      "weekdayNoData": "Nessun dato",
+      "weekdayBestWorst": "Giorno migliore: {best} · Giorno più difficile: {worst}",
+      "tagsTitle": "Tag e fattori scatenanti",
+      "tagAvgMood": "Umore medio con questo tag",
+      "correlationsTitle": "Umore e altre metriche",
+      "correlationsDescription": "Come il tuo umore si muove con sonno, attività e battito nello stesso giorno.",
+      "correlation": {
+        "sleepTitle": "Umore vs. sonno",
+        "stepsTitle": "Umore vs. attività",
+        "pulseTitle": "Umore vs. battito",
+        "sleepAxis": "Sonno (min)",
+        "stepsAxis": "Passi",
+        "pulseAxis": "Battito (bpm)",
+        "strengthStrong": "Forte",
+        "strengthModerate": "Moderata",
+        "strengthWeak": "Debole",
+        "strengthNone": "Nessuna",
+        "source": "{n} giorni appaiati · r = {r}",
+        "emptyTitle": "Non ci sono ancora abbastanza dati appaiati",
+        "emptyDescription": "Registra umore e questa metrica negli stessi giorni per vedere una correlazione."
+      }
+    }
   },
   "thresholds": {
     "defaultLabel": "Predefinito",
diff --git a/messages/pl.json b/messages/pl.json
index 8e8098fe5..f61ac8f73 100644
--- a/messages/pl.json
+++ b/messages/pl.json
@@ -1346,7 +1346,16 @@
     "personalBaseline": "Twoja średnia",
     "deltaVsBaseline": "{delta} vs. twoja średnia",
     "deltaUnchanged": "odpowiada twojej średniej",
-    "deltaVsTarget": "{delta} vs. cel"
+    "deltaVsTarget": "{delta} vs. cel",
+    "weekdaysFull": {
+      "mon": "Poniedziałek",
+      "tue": "Wtorek",
+      "wed": "Środa",
+      "thu": "Czwartek",
+      "fri": "Piątek",
+      "sat": "Sobota",
+      "sun": "Niedziela"
+    }
   },
   "chart": {
     "overlay": {
@@ -2275,7 +2284,39 @@
         "description": "Odczyty pojawią się tutaj po synchronizacji Apple Health."
       }
     },
-    "navWalkingSpeed": "Prędkość chodu"
+    "navWalkingSpeed": "Prędkość chodu",
+    "mood": {
+      "heatmapTitle": "Kalendarz nastroju",
+      "heatmapNoEntry": "Brak wpisu",
+      "legendGreat": "Świetnie",
+      "legendGood": "Dobrze",
+      "legendOkay": "W porządku",
+      "legendLow": "Nisko",
+      "distributionTitle": "Rozkład nastroju",
+      "distributionDaysUnit": "dni",
+      "weekdayTitle": "Średnia wg dnia tygodnia",
+      "weekdayNoData": "Brak danych",
+      "weekdayBestWorst": "Najlepszy dzień: {best} · Najtrudniejszy dzień: {worst}",
+      "tagsTitle": "Tagi i wyzwalacze",
+      "tagAvgMood": "Średni nastrój z tym tagiem",
+      "correlationsTitle": "Nastrój a inne wskaźniki",
+      "correlationsDescription": "Jak Twój nastrój zmienia się wraz ze snem, aktywnością i tętnem tego samego dnia.",
+      "correlation": {
+        "sleepTitle": "Nastrój a sen",
+        "stepsTitle": "Nastrój a aktywność",
+        "pulseTitle": "Nastrój a tętno",
+        "sleepAxis": "Sen (min)",
+        "stepsAxis": "Kroki",
+        "pulseAxis": "Tętno (bpm)",
+        "strengthStrong": "Silna",
+        "strengthModerate": "Umiarkowana",
+        "strengthWeak": "Słaba",
+        "strengthNone": "Brak",
+        "source": "{n} sparowanych dni · r = {r}",
+        "emptyTitle": "Za mało sparowanych danych",
+        "emptyDescription": "Rejestruj nastrój i ten wskaźnik w te same dni, aby zobaczyć korelację."
+      }
+    }
   },
   "thresholds": {
     "defaultLabel": "Domyślne",
diff --git a/src/app/api/mood/insights/route.ts b/src/app/api/mood/insights/route.ts
new file mode 100644
index 000000000..a21037371
--- /dev/null
+++ b/src/app/api/mood/insights/route.ts
@@ -0,0 +1,43 @@
+import { apiSuccess } from "@/lib/api-response";
+import { apiHandler, requireAuth } from "@/lib/api-handler";
+import { annotate } from "@/lib/logging/context";
+import { cached, caches, type ServerCache } from "@/lib/cache/server-cache";
+import {
+  fetchMoodAggregates,
+  type MoodAggregates,
+} from "@/lib/insights/mood-aggregates";
+
+export const dynamic = "force-dynamic";
+
+/**
+ * v1.8.5 — pre-computed mood-insights aggregates for the Mood Insights
+ * page (heatmap, distribution, weekday pattern, tag breakdown,
+ * cross-metric correlations, summary headline).
+ *
+ * The page stays a client component for the interactive line chart but
+ * reads the heavy aggregates from here: the compute runs server-side
+ * once per 60-s cache window, the browser only ever receives pre-shaped
+ * data (no raw mood rows). This follows the v1.8.3 anti-freeze posture
+ * — a cheap cached read, never a synchronous LLM call.
+ */
+export const GET = apiHandler(async () => {
+  const { user } = await requireAuth();
+
+  const result = await cached(
+    caches.moodInsights as ServerCache<MoodAggregates>,
+    user.id,
+    () => fetchMoodAggregates(user.id),
+    annotate,
+  );
+
+  annotate({
+    action: { name: "mood.insights.read" },
+    meta: {
+      total_entries: result.summary.totalEntries,
+      heatmap_window_days: result.heatmap.windowDays,
+      tag_count: result.tags.length,
+    },
+  });
+
+  return apiSuccess(result);
+});
diff --git a/src/app/insights/mood/page.tsx b/src/app/insights/mood/page.tsx
index cdb451715..ce89442ef 100644
--- a/src/app/insights/mood/page.tsx
+++ b/src/app/insights/mood/page.tsx
@@ -16,6 +16,7 @@ import { CoachLaunchButton } from "@/components/insights/coach-launch-button";
 import { InsightStatusCard } from "@/components/insights/insight-status-card";
 import { MetricEmptyState } from "@/components/insights/metric-empty-state";
 import { MetricTargetSummary } from "@/components/insights/metric-target-summary";
+import { MoodInsightsSections } from "@/components/insights/mood/mood-insights-sections";
 import { SubPageShell } from "@/components/insights/sub-page-shell";
 
 /**
@@ -107,6 +108,8 @@ export default function InsightsStimmungPage() {
 
       <MetricTargetSummary slug="mood" />
 
+      <MoodInsightsSections />
+
       <InsightStatusCard
         title={t("insights.assessmentTitle")}
         icon={<Smile className="h-5 w-5" />}
diff --git a/src/components/charts/mood-heatmap.tsx b/src/components/charts/mood-heatmap.tsx
new file mode 100644
index 000000000..35bf3fc28
--- /dev/null
+++ b/src/components/charts/mood-heatmap.tsx
@@ -0,0 +1,316 @@
+"use client";
+
+import { useState, useMemo, useEffect, useRef } from "react";
+import { useTranslations } from "@/lib/i18n/context";
+import { moodLabelKeyForScore } from "@/lib/mood/labels";
+
+/**
+ * v1.8.5 — mood calendar heatmap.
+ *
+ * Forked from `compliance-heatmap.tsx`: same SVG cell-grid, Monday-aligned
+ * columns, month markers, tap-to-pin tooltip, and `stretch` adaptive cell
+ * sizing. The one swap is `getColor` — instead of an expected/taken
+ * compliance map, each cell is coloured by its daily-mean mood score band
+ * (matching the `mood-chart.tsx` VALUE_BANDS: 1–2 red, 2–3 orange, 3–5
+ * green). One cell per calendar day; days with no entry render in the
+ * neutral `--secondary` fill.
+ */
+
+interface MoodHeatmapCell {
+  /** YYYY-MM-DD day key. */
+  date: string;
+  /** Daily-mean mood score 1..5. */
+  score: number;
+  /** Number of entries that fed the mean. */
+  samples: number;
+}
+
+interface MoodHeatmapProps {
+  /** Per-day cells keyed by YYYY-MM-DD. */
+  cells: Record<string, MoodHeatmapCell>;
+  days?: number;
+  stretch?: boolean;
+}
+
+const CELL_SIZE = 18;
+const GAP = 3;
+const CELL_FLOOR_PX = 14;
+
+/**
+ * Mood score band → Dracula colour. Mirrors `mood-chart.tsx` VALUE_BANDS
+ * (1–2 red, 2–3 orange, 3–5 green) and the green/orange thresholds in
+ * `mood-aggregates.ts`. No score (no entry that day) → neutral fill.
+ */
+function getColor(score: number | null): string {
+  if (score == null) return "var(--secondary)";
+  if (score < 2) return "var(--dracula-red)";
+  if (score < 3) return "var(--dracula-orange)";
+  if (score < 3.5) return "var(--dracula-yellow)";
+  return "var(--dracula-green)";
+}
+
+function formatDateDE(dateStr: string): string {
+  const d = new Date(dateStr + "T00:00:00Z");
+  return `${d.getUTCDate()}.${d.getUTCMonth() + 1}.${d.getUTCFullYear()}`;
+}
+
+export function MoodHeatmap({
+  cells: cellData,
+  days = 90,
+  stretch = false,
+}: MoodHeatmapProps) {
+  const { t } = useTranslations();
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const [containerWidth, setContainerWidth] = useState(0);
+  const [tooltip, setTooltip] = useState<{
+    x: number;
+    y: number;
+    text: string;
+    pinned?: boolean;
+  } | null>(null);
+
+  useEffect(() => {
+    if (!tooltip?.pinned) return;
+    const handlePointer = (event: PointerEvent) => {
+      const container = containerRef.current;
+      if (!container) return;
+      if (!container.contains(event.target as Node)) {
+        setTooltip(null);
+      }
+    };
+    document.addEventListener("pointerdown", handlePointer, true);
+    return () => {
+      document.removeEventListener("pointerdown", handlePointer, true);
+    };
+  }, [tooltip?.pinned]);
+
+  const WEEKDAY_LABELS = [
+    t("charts.weekdays.mon"),
+    "",
+    t("charts.weekdays.wed"),
+    "",
+    t("charts.weekdays.fri"),
+    "",
+    t("charts.weekdays.sun"),
+  ];
+
+  useEffect(() => {
+    if (!stretch) return;
+    const element = containerRef.current;
+    if (!element) return;
+
+    const updateWidth = () => {
+      setContainerWidth(element.clientWidth);
+    };
+
+    updateWidth();
+    const observer = new ResizeObserver(updateWidth);
+    observer.observe(element);
+
+    return () => {
+      observer.disconnect();
+    };
+  }, [stretch]);
+
+  const { cells, weeks, monthMarkers } = useMemo(() => {
+    const MONTH_LABELS = [
+      t("charts.months.jan"),
+      t("charts.months.feb"),
+      t("charts.months.mar"),
+      t("charts.months.apr"),
+      t("charts.months.may"),
+      t("charts.months.jun"),
+      t("charts.months.jul"),
+      t("charts.months.aug"),
+      t("charts.months.sep"),
+      t("charts.months.oct"),
+      t("charts.months.nov"),
+      t("charts.months.dec"),
+    ];
+    const now = new Date();
+    const cellList: Array<{
+      dateKey: string;
+      col: number;
+      row: number;
+      color: string;
+      cell: MoodHeatmapCell | null;
+    }> = [];
+
+    const dates: Date[] = [];
+    for (let d = days - 1; d >= 0; d--) {
+      const date = new Date(now.getTime() - d * 24 * 60 * 60 * 1000);
+      dates.push(date);
+    }
+
+    // Monday-align + month markers read off the UTC accessors so the
+    // grid matches the UTC-anchored dateKey (mirrors compliance-heatmap).
+    const firstDate = dates[0];
+    const firstDow = (firstDate.getUTCDay() + 6) % 7; // Monday = 0
+
+    let col = 0;
+    const markers: Array<{ col: number; label: string }> = [];
+    let lastMonth = -1;
+
+    for (let i = 0; i < dates.length; i++) {
+      const date = dates[i];
+      const dow = (date.getUTCDay() + 6) % 7; // Monday = 0
+      const currentCol = Math.floor((i + firstDow) / 7);
+      const row = dow;
+      const dateKey = date.toISOString().slice(0, 10);
+      const cell = cellData[dateKey] ?? null;
+
+      const month = date.getUTCMonth();
+      if (month !== lastMonth) {
+        markers.push({ col: currentCol, label: MONTH_LABELS[month] });
+        lastMonth = month;
+      }
+
+      cellList.push({
+        dateKey,
+        col: currentCol,
+        row,
+        color: getColor(cell?.score ?? null),
+        cell,
+      });
+
+      col = Math.max(col, currentCol);
+    }
+
+    return { cells: cellList, weeks: col + 1, monthMarkers: markers };
+  }, [cellData, days, t]);
+
+  const labelWidth = stretch ? 0 : 76;
+  const headerHeight = 18;
+  const cellSize =
+    stretch && containerWidth > 0
+      ? Math.max(
+          CELL_FLOOR_PX,
+          (containerWidth - labelWidth - Math.max(0, weeks - 1) * GAP) /
+            Math.max(weeks, 1),
+        )
+      : CELL_SIZE;
+  const step = cellSize + GAP;
+  const svgWidth = labelWidth + weeks * cellSize + Math.max(0, weeks - 1) * GAP;
+  const svgHeight = headerHeight + 7 * cellSize + 6 * GAP;
+
+  return (
+    <div className={`relative ${stretch ? "w-full" : ""}`} ref={containerRef}>
+      <div
+        className={
+          stretch
+            ? "w-full sm:w-full overflow-x-auto sm:overflow-visible"
+            : "overflow-x-auto"
+        }
+      >
+        <svg
+          width={svgWidth}
+          height={svgHeight}
+          className={stretch ? "block w-full" : "block"}
+          onMouseLeave={() => setTooltip((prev) => (prev?.pinned ? prev : null))}
+        >
+          {monthMarkers.map((m, i) => (
+            <text
+              key={i}
+              x={labelWidth + m.col * step}
+              y={11}
+              className="fill-muted-foreground"
+              fontSize={10}
+            >
+              {m.label}
+            </text>
+          ))}
+
+          {!stretch &&
+            WEEKDAY_LABELS.map(
+              (label, i) =>
+                label && (
+                  <text
+                    key={i}
+                    x={labelWidth - 6}
+                    y={headerHeight + i * step + cellSize * 0.65}
+                    textAnchor="end"
+                    className="fill-muted-foreground"
+                    fontSize={10}
+                  >
+                    {label}
+                  </text>
+                ),
+            )}
+
+          {cells.map((cell) => {
+            const buildText = (): string => {
+              if (!cell.cell) {
+                return `${formatDateDE(cell.dateKey)}: ${t("insights.mood.heatmapNoEntry")}`;
+              }
+              const labelKey = moodLabelKeyForScore(Math.round(cell.cell.score));
+              const moodLabel = labelKey ? t(labelKey) : "";
+              return `${formatDateDE(cell.dateKey)}: ${cell.cell.score.toFixed(1)}${moodLabel ? ` · ${moodLabel}` : ""}`;
+            };
+            return (
+              <rect
+                key={cell.dateKey}
+                x={labelWidth + cell.col * step}
+                y={headerHeight + cell.row * step}
+                width={cellSize}
+                height={cellSize}
+                rx={2}
+                fill={cell.color}
+                className="cursor-pointer"
+                onPointerEnter={(e) => {
+                  if (e.pointerType === "touch") return;
+                  setTooltip({
+                    x: e.clientX,
+                    y: e.clientY,
+                    text: buildText(),
+                  });
+                }}
+                onPointerLeave={(e) => {
+                  if (e.pointerType === "touch") return;
+                  setTooltip((prev) => (prev?.pinned ? prev : null));
+                }}
+                onPointerDown={(e) => {
+                  if (e.pointerType !== "touch") return;
+                  setTooltip({
+                    x: e.clientX,
+                    y: e.clientY,
+                    text: buildText(),
+                    pinned: true,
+                  });
+                }}
+              />
+            );
+          })}
+        </svg>
+      </div>
+
+      {tooltip && (
+        <div
+          className="bg-popover text-popover-foreground border-border pointer-events-none fixed z-50 rounded-md border px-2 py-1 text-xs shadow-md"
+          style={{ left: tooltip.x + 10, top: tooltip.y - 30 }}
+        >
+          {tooltip.text}
+        </div>
+      )}
+
+      <div
+        className="text-muted-foreground mt-2 flex flex-wrap items-center gap-3 text-xs"
+        style={{ marginLeft: stretch ? 0 : labelWidth }}
+      >
+        {[
+          { color: "var(--dracula-green)", label: t("insights.mood.legendGreat") },
+          { color: "var(--dracula-yellow)", label: t("insights.mood.legendGood") },
+          { color: "var(--dracula-orange)", label: t("insights.mood.legendOkay") },
+          { color: "var(--dracula-red)", label: t("insights.mood.legendLow") },
+        ].map(({ color, label }) => (
+          <span key={label} className="flex items-center gap-1">
+            <div
+              className="h-3 w-3 rounded-sm"
+              style={{ backgroundColor: color }}
+            />
+            {label}
+          </span>
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/insights/mood/mood-correlation-cards.tsx b/src/components/insights/mood/mood-correlation-cards.tsx
new file mode 100644
index 000000000..cdb3bcc7b
--- /dev/null
+++ b/src/components/insights/mood/mood-correlation-cards.tsx
@@ -0,0 +1,151 @@
+"use client";
+
+import dynamic from "next/dynamic";
+import { Activity } from "lucide-react";
+
+import { Badge } from "@/components/ui/badge";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { EmptyState } from "@/components/ui/empty-state";
+import { useTranslations } from "@/lib/i18n/context";
+import type { CorrelationResult } from "@/lib/analytics/correlations";
+
+/**
+ * v1.8.5 — mood × metric correlation cards (Apple "Life Factors" parity).
+ *
+ * Reuses the shared `<ScatterCorrelationChart>` (same wrapper the
+ * mother-page correlation cards ride) for each mood × (sleep / steps /
+ * pulse) pair. The Pearson math comes pre-computed from
+ * `/api/mood/insights` (single source of truth with the LLM snapshot).
+ * Below-threshold pairs render an EmptyState rather than a misleading
+ * near-zero scatter.
+ */
+
+const ScatterCorrelationChart = dynamic(
+  () =>
+    import("@/components/charts/scatter-correlation-chart").then((mod) => ({
+      default: mod.ScatterCorrelationChart,
+    })),
+  {
+    ssr: false,
+    loading: () => (
+      <div className="bg-muted/40 aspect-square min-h-[180px] w-full animate-pulse rounded-md motion-reduce:animate-none sm:aspect-[3/2] sm:h-auto" />
+    ),
+  },
+);
+
+export interface MoodCorrelationPoint {
+  x: number;
+  y: number;
+  [key: string]: number;
+}
+
+export interface MoodMetricCorrelationData {
+  result: CorrelationResult | null;
+  points: MoodCorrelationPoint[];
+  n: number;
+}
+
+type MetricKind = "sleep" | "steps" | "pulse";
+
+const TITLE_KEY: Record<MetricKind, string> = {
+  sleep: "insights.mood.correlation.sleepTitle",
+  steps: "insights.mood.correlation.stepsTitle",
+  pulse: "insights.mood.correlation.pulseTitle",
+};
+
+const Y_LABEL_KEY: Record<MetricKind, string> = {
+  sleep: "insights.mood.correlation.sleepAxis",
+  steps: "insights.mood.correlation.stepsAxis",
+  pulse: "insights.mood.correlation.pulseAxis",
+};
+
+const FILL_BY_KIND: Record<MetricKind, string> = {
+  sleep: "var(--dracula-purple)",
+  steps: "var(--dracula-cyan)",
+  pulse: "var(--dracula-pink)",
+};
+
+const STRENGTH_KEY: Record<CorrelationResult["strength"], string> = {
+  stark: "insights.mood.correlation.strengthStrong",
+  moderat: "insights.mood.correlation.strengthModerate",
+  schwach: "insights.mood.correlation.strengthWeak",
+  keine: "insights.mood.correlation.strengthNone",
+};
+
+function MoodCorrelationCard({
+  kind,
+  data,
+}: {
+  kind: MetricKind;
+  data: MoodMetricCorrelationData;
+}) {
+  const { t } = useTranslations();
+  const hasResult = data.result != null && data.n >= 5;
+
+  return (
+    <Card data-slot="mood-correlation-card" data-kind={kind}>
+      <CardHeader className="pb-2">
+        <div className="flex items-start justify-between gap-2">
+          <CardTitle className="text-sm font-semibold">
+            {t(TITLE_KEY[kind])}
+          </CardTitle>
+          {hasResult && data.result && (
+            <Badge variant="outline" className="shrink-0 text-[10px]">
+              {t(STRENGTH_KEY[data.result.strength])}
+            </Badge>
+          )}
+        </div>
+      </CardHeader>
+      <CardContent className="space-y-3">
+        {hasResult && data.result ? (
+          <>
+            <ScatterCorrelationChart
+              data={data.points}
+              fill={FILL_BY_KIND[kind]}
+              xAxis={{
+                dataKey: "x",
+                name: t("insights.moodSectionTitle"),
+                domain: [1, 5],
+                ticks: [1, 2, 3, 4, 5],
+              }}
+              yAxis={{ dataKey: "y", name: t(Y_LABEL_KEY[kind]) }}
+              height={180}
+            />
+            <p className="text-muted-foreground text-[11px]">
+              {t("insights.mood.correlation.source", {
+                n: data.n,
+                r: data.result.r.toFixed(2),
+              })}
+            </p>
+          </>
+        ) : (
+          <EmptyState
+            variant="plain"
+            size="compact"
+            icon={<Activity className="size-5" />}
+            title={t("insights.mood.correlation.emptyTitle")}
+            description={t("insights.mood.correlation.emptyDescription")}
+          />
+        )}
+      </CardContent>
+    </Card>
+  );
+}
+
+export function MoodCorrelationCards({
+  sleep,
+  steps,
+  pulse,
+}: {
+  sleep: MoodMetricCorrelationData;
+  steps: MoodMetricCorrelationData;
+  pulse: MoodMetricCorrelationData;
+}) {
+  return (
+    <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+      <MoodCorrelationCard kind="sleep" data={sleep} />
+      <MoodCorrelationCard kind="steps" data={steps} />
+      <MoodCorrelationCard kind="pulse" data={pulse} />
+    </div>
+  );
+}
diff --git a/src/components/insights/mood/mood-distribution-chart.tsx b/src/components/insights/mood/mood-distribution-chart.tsx
new file mode 100644
index 000000000..5e049daff
--- /dev/null
+++ b/src/components/insights/mood/mood-distribution-chart.tsx
@@ -0,0 +1,100 @@
+"use client";
+
+import {
+  Bar,
+  BarChart,
+  Cell,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from "recharts";
+
+import { useTranslations } from "@/lib/i18n/context";
+import { moodLabelKeyForScore } from "@/lib/mood/labels";
+
+/**
+ * v1.8.5 — mood distribution (share of days per level).
+ *
+ * One bar per discrete mood level 1..5, coloured by the same band map
+ * as the heatmap + line chart. Counts are days (daily means rounded to
+ * the nearest level) so multi-entry days never over-weight the
+ * histogram — consistent with the rest of the surface's daily-mean
+ * convention.
+ */
+
+export interface MoodDistributionRow {
+  score: number;
+  count: number;
+}
+
+const BAR_COLOR_BY_SCORE: Record<number, string> = {
+  1: "var(--dracula-red)",
+  2: "var(--dracula-orange)",
+  3: "var(--dracula-yellow)",
+  4: "var(--dracula-green)",
+  5: "var(--dracula-green)",
+};
+
+export function MoodDistributionChart({
+  distribution,
+}: {
+  distribution: MoodDistributionRow[];
+}) {
+  const { t } = useTranslations();
+
+  const data = distribution.map((row) => {
+    const labelKey = moodLabelKeyForScore(row.score);
+    return {
+      score: row.score,
+      count: row.count,
+      label: labelKey ? t(labelKey) : String(row.score),
+    };
+  });
+
+  return (
+    <div className="aspect-[3/2] min-h-[180px] w-full">
+      <ResponsiveContainer width="100%" height="100%">
+        <BarChart data={data} margin={{ top: 8, right: 12, bottom: 8, left: 0 }}>
+          <XAxis
+            dataKey="label"
+            tick={{ fontSize: 11, fill: "var(--dracula-fg)" }}
+            stroke="var(--dracula-comment)"
+            interval={0}
+          />
+          <YAxis
+            allowDecimals={false}
+            tick={{ fontSize: 11, fill: "var(--dracula-fg)" }}
+            stroke="var(--dracula-comment)"
+            width={28}
+          />
+          <Tooltip
+            cursor={{ fill: "var(--secondary)", opacity: 0.4 }}
+            contentStyle={{
+              backgroundColor: "var(--card)",
+              border: "1px solid var(--border)",
+              borderRadius: "0.5rem",
+              fontSize: "0.75rem",
+            }}
+            itemStyle={{ color: "var(--dracula-fg)" }}
+            labelStyle={{ color: "var(--dracula-fg)" }}
+            formatter={(value) =>
+              [
+                `${value ?? 0} ${t("insights.mood.distributionDaysUnit")}`,
+                t("insights.mood.distributionTitle"),
+              ] as [string, string]
+            }
+          />
+          <Bar dataKey="count" radius={[3, 3, 0, 0]}>
+            {data.map((row) => (
+              <Cell
+                key={row.score}
+                fill={BAR_COLOR_BY_SCORE[row.score] ?? "var(--dracula-purple)"}
+              />
+            ))}
+          </Bar>
+        </BarChart>
+      </ResponsiveContainer>
+    </div>
+  );
+}
diff --git a/src/components/insights/mood/mood-insights-sections.tsx b/src/components/insights/mood/mood-insights-sections.tsx
new file mode 100644
index 000000000..7e5187919
--- /dev/null
+++ b/src/components/insights/mood/mood-insights-sections.tsx
@@ -0,0 +1,143 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Skeleton } from "@/components/ui/skeleton";
+import { useAuth } from "@/hooks/use-auth";
+import { queryKeys } from "@/lib/query-keys";
+import { useTranslations } from "@/lib/i18n/context";
+import { MoodHeatmap } from "@/components/charts/mood-heatmap";
+import {
+  MoodDistributionChart,
+  type MoodDistributionRow,
+} from "./mood-distribution-chart";
+import {
+  MoodWeekdayChart,
+  type MoodWeekdayRow,
+} from "./mood-weekday-chart";
+import {
+  MoodTagBreakdown,
+  type MoodTagRow,
+} from "./mood-tag-breakdown";
+import {
+  MoodCorrelationCards,
+  type MoodMetricCorrelationData,
+} from "./mood-correlation-cards";
+
+/**
+ * v1.8.5 — additional Mood Insights sections.
+ *
+ * Reads the pre-computed aggregate bundle from `/api/mood/insights`
+ * (cheap cached server read, no LLM) and paints the heatmap,
+ * distribution, weekday pattern, tag breakdown, and mood × metric
+ * correlation cards. Renders nothing while loading / on error / on an
+ * empty data set so the page degrades gracefully to the line chart.
+ */
+
+interface MoodInsightsResponse {
+  summary: {
+    totalEntries: number;
+  };
+  heatmap: {
+    windowDays: number;
+    cells: Array<{ date: string; score: number; samples: number }>;
+  };
+  distribution: MoodDistributionRow[];
+  weekday: MoodWeekdayRow[];
+  tags: MoodTagRow[];
+  correlations: {
+    sleep: MoodMetricCorrelationData;
+    steps: MoodMetricCorrelationData;
+    pulse: MoodMetricCorrelationData;
+  };
+}
+
+function SectionCard({
+  title,
+  children,
+}: {
+  title: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <Card>
+      <CardHeader className="pb-2">
+        <CardTitle className="text-base">{title}</CardTitle>
+      </CardHeader>
+      <CardContent>{children}</CardContent>
+    </Card>
+  );
+}
+
+export function MoodInsightsSections() {
+  const { isAuthenticated } = useAuth();
+  const { t } = useTranslations();
+
+  const { data, isLoading } = useQuery({
+    queryKey: queryKeys.moodInsights(),
+    queryFn: async () => {
+      const res = await fetch("/api/mood/insights");
+      if (!res.ok) throw new Error("Failed");
+      const json = await res.json();
+      return json.data as MoodInsightsResponse;
+    },
+    enabled: isAuthenticated,
+    staleTime: 60_000,
+  });
+
+  if (isLoading) {
+    return <Skeleton className="h-48 w-full rounded-lg" />;
+  }
+
+  if (!data || data.summary.totalEntries === 0) {
+    return null;
+  }
+
+  const heatmapCells = Object.fromEntries(
+    data.heatmap.cells.map((cell) => [cell.date, cell]),
+  );
+
+  const hasTags = data.tags.length > 0;
+
+  return (
+    <div className="space-y-4">
+      <SectionCard title={t("insights.mood.heatmapTitle")}>
+        <MoodHeatmap
+          cells={heatmapCells}
+          days={data.heatmap.windowDays}
+          stretch
+        />
+      </SectionCard>
+
+      <div className="grid gap-4 lg:grid-cols-2">
+        <SectionCard title={t("insights.mood.distributionTitle")}>
+          <MoodDistributionChart distribution={data.distribution} />
+        </SectionCard>
+        <SectionCard title={t("insights.mood.weekdayTitle")}>
+          <MoodWeekdayChart weekday={data.weekday} />
+        </SectionCard>
+      </div>
+
+      {hasTags && (
+        <SectionCard title={t("insights.mood.tagsTitle")}>
+          <MoodTagBreakdown tags={data.tags} />
+        </SectionCard>
+      )}
+
+      <div className="space-y-2">
+        <h3 className="text-base font-semibold">
+          {t("insights.mood.correlationsTitle")}
+        </h3>
+        <p className="text-muted-foreground text-sm">
+          {t("insights.mood.correlationsDescription")}
+        </p>
+        <MoodCorrelationCards
+          sleep={data.correlations.sleep}
+          steps={data.correlations.steps}
+          pulse={data.correlations.pulse}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/insights/mood/mood-tag-breakdown.tsx b/src/components/insights/mood/mood-tag-breakdown.tsx
new file mode 100644
index 000000000..f7bb8044f
--- /dev/null
+++ b/src/components/insights/mood/mood-tag-breakdown.tsx
@@ -0,0 +1,63 @@
+"use client";
+
+import { useTranslations } from "@/lib/i18n/context";
+
+/**
+ * v1.8.5 — tag / trigger breakdown.
+ *
+ * Ranked horizontal bars over tag frequency, with the per-tag average
+ * mood ("lift") rendered as a coloured score chip. The aggregation comes
+ * pre-computed from `/api/mood/insights` (shared with the LLM snapshot's
+ * tag block, so the prose and the chart agree). Works on the flat
+ * free-text tag array we hold today — the structured-tag taxonomy with
+ * icons is a separate later piece.
+ */
+
+export interface MoodTagRow {
+  tag: string;
+  count: number;
+  avgScore: number;
+}
+
+function colorForScore(score: number): string {
+  if (score < 2) return "var(--dracula-red)";
+  if (score < 3) return "var(--dracula-orange)";
+  if (score < 3.5) return "var(--dracula-yellow)";
+  return "var(--dracula-green)";
+}
+
+export function MoodTagBreakdown({ tags }: { tags: MoodTagRow[] }) {
+  const { t } = useTranslations();
+  const maxCount = tags.reduce((m, row) => Math.max(m, row.count), 0) || 1;
+
+  return (
+    <ul className="space-y-2" data-slot="mood-tag-breakdown">
+      {tags.map((row) => (
+        <li key={row.tag} className="flex items-center gap-2 text-sm">
+          <span className="text-foreground w-28 shrink-0 truncate" title={row.tag}>
+            {row.tag}
+          </span>
+          <div className="bg-secondary relative h-3 flex-1 overflow-hidden rounded-full">
+            <div
+              className="absolute inset-y-0 left-0 rounded-full"
+              style={{
+                width: `${(row.count / maxCount) * 100}%`,
+                backgroundColor: colorForScore(row.avgScore),
+              }}
+            />
+          </div>
+          <span className="text-muted-foreground w-6 shrink-0 text-right tabular-nums">
+            {row.count}
+          </span>
+          <span
+            className="w-10 shrink-0 text-right text-xs font-medium tabular-nums"
+            style={{ color: colorForScore(row.avgScore) }}
+            title={t("insights.mood.tagAvgMood")}
+          >
+            {row.avgScore.toFixed(1)}
+          </span>
+        </li>
+      ))}
+    </ul>
+  );
+}
diff --git a/src/components/insights/mood/mood-weekday-chart.tsx b/src/components/insights/mood/mood-weekday-chart.tsx
new file mode 100644
index 000000000..3842a64cc
--- /dev/null
+++ b/src/components/insights/mood/mood-weekday-chart.tsx
@@ -0,0 +1,144 @@
+"use client";
+
+import { useMemo } from "react";
+import {
+  Bar,
+  BarChart,
+  Cell,
+  ReferenceLine,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from "recharts";
+
+import { useTranslations } from "@/lib/i18n/context";
+
+/**
+ * v1.8.5 — average mood per weekday (Monday-aligned).
+ *
+ * One bar per weekday over the average daily-mean mood, with the
+ * best/worst day called out below the chart. Empty weekdays (no data)
+ * render as a zero-height bar so the seven-column rhythm stays intact.
+ */
+
+export interface MoodWeekdayRow {
+  /** 0 = Monday … 6 = Sunday. */
+  weekday: number;
+  avgScore: number | null;
+  count: number;
+}
+
+const WEEKDAY_LABEL_KEYS = [
+  "charts.weekdaysFull.mon",
+  "charts.weekdaysFull.tue",
+  "charts.weekdaysFull.wed",
+  "charts.weekdaysFull.thu",
+  "charts.weekdaysFull.fri",
+  "charts.weekdaysFull.sat",
+  "charts.weekdaysFull.sun",
+] as const;
+
+function colorForScore(score: number): string {
+  if (score < 2) return "var(--dracula-red)";
+  if (score < 3) return "var(--dracula-orange)";
+  if (score < 3.5) return "var(--dracula-yellow)";
+  return "var(--dracula-green)";
+}
+
+export function MoodWeekdayChart({ weekday }: { weekday: MoodWeekdayRow[] }) {
+  const { t } = useTranslations();
+
+  const data = weekday.map((row) => ({
+    weekday: row.weekday,
+    label: t(WEEKDAY_LABEL_KEYS[row.weekday]),
+    value: row.avgScore ?? 0,
+    avgScore: row.avgScore,
+    count: row.count,
+  }));
+
+  const { best, worst } = useMemo(() => {
+    const populated = weekday.filter(
+      (r): r is MoodWeekdayRow & { avgScore: number } => r.avgScore != null,
+    );
+    if (populated.length === 0) return { best: null, worst: null };
+    let bestRow = populated[0];
+    let worstRow = populated[0];
+    for (const row of populated) {
+      if (row.avgScore > bestRow.avgScore) bestRow = row;
+      if (row.avgScore < worstRow.avgScore) worstRow = row;
+    }
+    return { best: bestRow, worst: worstRow };
+  }, [weekday]);
+
+  return (
+    <div className="space-y-2">
+      <div className="aspect-[3/2] min-h-[160px] w-full">
+        <ResponsiveContainer width="100%" height="100%">
+          <BarChart
+            data={data}
+            margin={{ top: 8, right: 12, bottom: 8, left: 0 }}
+          >
+            <XAxis
+              dataKey="label"
+              tick={{ fontSize: 11, fill: "var(--dracula-fg)" }}
+              stroke="var(--dracula-comment)"
+              interval={0}
+            />
+            <YAxis
+              domain={[1, 5]}
+              ticks={[1, 2, 3, 4, 5]}
+              tick={{ fontSize: 11, fill: "var(--dracula-fg)" }}
+              stroke="var(--dracula-comment)"
+              width={24}
+            />
+            <ReferenceLine y={3.5} stroke="var(--dracula-green)" strokeDasharray="3 3" />
+            <Tooltip
+              cursor={{ fill: "var(--secondary)", opacity: 0.4 }}
+              contentStyle={{
+                backgroundColor: "var(--card)",
+                border: "1px solid var(--border)",
+                borderRadius: "0.5rem",
+                fontSize: "0.75rem",
+              }}
+              itemStyle={{ color: "var(--dracula-fg)" }}
+              labelStyle={{ color: "var(--dracula-fg)" }}
+              formatter={(_value, _name, item) => {
+                const payload = item?.payload as
+                  | { avgScore: number | null; count: number }
+                  | undefined;
+                if (!payload || payload.avgScore == null) {
+                  return [t("insights.mood.weekdayNoData"), ""];
+                }
+                return [
+                  `${payload.avgScore.toFixed(1)} (${payload.count})`,
+                  t("insights.mood.weekdayTitle"),
+                ];
+              }}
+            />
+            <Bar dataKey="value" radius={[3, 3, 0, 0]}>
+              {data.map((row) => (
+                <Cell
+                  key={row.weekday}
+                  fill={
+                    row.avgScore == null
+                      ? "var(--secondary)"
+                      : colorForScore(row.avgScore)
+                  }
+                />
+              ))}
+            </Bar>
+          </BarChart>
+        </ResponsiveContainer>
+      </div>
+      {best && worst && (
+        <p className="text-muted-foreground text-xs">
+          {t("insights.mood.weekdayBestWorst", {
+            best: t(WEEKDAY_LABEL_KEYS[best.weekday]),
+            worst: t(WEEKDAY_LABEL_KEYS[worst.weekday]),
+          })}
+        </p>
+      )}
+    </div>
+  );
+}
diff --git a/src/lib/cache/invalidate.ts b/src/lib/cache/invalidate.ts
index 9b527c6a2..f8b57b4bd 100644
--- a/src/lib/cache/invalidate.ts
+++ b/src/lib/cache/invalidate.ts
@@ -76,6 +76,9 @@ export function invalidateUserMood(userId: string): void {
   // v1.4.36 W1 — mood writes change the mood target rows on the
   // insights/targets response (MOOD_SCORE, MOOD_STABILITY).
   caches.insightsTargets.deleteByPrefix(userId);
+  // v1.8.5 — mood writes dirty every dimension of the mood-insights
+  // aggregate (heatmap cell, distribution, weekday, tag breakdown).
+  caches.moodInsights.deleteByPrefix(userId);
 }
 
 /**
diff --git a/src/lib/cache/server-cache.ts b/src/lib/cache/server-cache.ts
index 03fd6a58f..638df3f07 100644
--- a/src/lib/cache/server-cache.ts
+++ b/src/lib/cache/server-cache.ts
@@ -260,6 +260,18 @@ export const caches = {
     maxEntries: 1000,
     ttlMs: 60_000,
   }),
+  /**
+   * v1.8.5 — pre-computed mood-insights aggregates (heatmap, distribution,
+   * weekday, tags, cross-metric correlations) for the Mood Insights page.
+   * Read on every `/insights/mood` mount; bounded 365-day live read behind
+   * the cache. 60 s TTL matches `moodAnalytics`; invalidated alongside it
+   * on a mood write via `invalidateUserMood`.
+   */
+  moodInsights: new ServerCache<unknown>({
+    name: "moodInsights",
+    maxEntries: 1000,
+    ttlMs: 60_000,
+  }),
   /**
    * v1.4.36 W1 — `/api/insights/targets` is read on every Insights
    * mount and runs >1 s cold (it pulls 30-day measurements for every
diff --git a/src/lib/insights/__tests__/mood-aggregates.test.ts b/src/lib/insights/__tests__/mood-aggregates.test.ts
new file mode 100644
index 000000000..8c4b3cd1a
--- /dev/null
+++ b/src/lib/insights/__tests__/mood-aggregates.test.ts
@@ -0,0 +1,238 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  computeDistribution,
+  computeHeatmapCells,
+  computeInTargetPct,
+  computeMoodAggregates,
+  computeMoodMetricCorrelation,
+  computeTagSummary,
+  computeWeekdayAverages,
+  selectHeatmapWindow,
+  type CrossMetricMeasurement,
+  type MoodAggregateEntry,
+} from "../mood-aggregates";
+
+const dayMs = 24 * 60 * 60 * 1000;
+
+/** Anchor "now" at a fixed UTC instant so day-key math is deterministic. */
+const NOW = new Date("2026-06-01T12:00:00.000Z");
+
+function dayKey(offset: number): string {
+  return new Date(NOW.getTime() - offset * dayMs).toISOString().slice(0, 10);
+}
+
+function entry(
+  offset: number,
+  score: number,
+  tags: unknown = null,
+): MoodAggregateEntry {
+  const ts = new Date(NOW.getTime() - offset * dayMs);
+  return { date: dayKey(offset), score, tags, moodLoggedAt: ts };
+}
+
+describe("selectHeatmapWindow", () => {
+  it("uses a 30-day window below 90 days of history", () => {
+    expect(selectHeatmapWindow(0)).toBe(30);
+    expect(selectHeatmapWindow(45)).toBe(30);
+    expect(selectHeatmapWindow(89)).toBe(30);
+  });
+
+  it("uses a 90-day window between 90 and 180 days inclusive", () => {
+    expect(selectHeatmapWindow(90)).toBe(90);
+    expect(selectHeatmapWindow(150)).toBe(90);
+    expect(selectHeatmapWindow(180)).toBe(90);
+  });
+
+  it("uses a 365-day window beyond 180 days", () => {
+    expect(selectHeatmapWindow(181)).toBe(365);
+    expect(selectHeatmapWindow(400)).toBe(365);
+  });
+});
+
+describe("computeTagSummary", () => {
+  it("ranks tags by frequency, drops singletons, and averages the score", () => {
+    const entries: MoodAggregateEntry[] = [
+      entry(1, 5, ["sport", "work"]),
+      entry(2, 3, ["work"]),
+      entry(3, 1, ["work"]),
+      entry(4, 4, ["sport"]),
+      entry(5, 2, ["solo-tag"]), // count 1 → dropped
+    ];
+    const tags = computeTagSummary(entries, NOW);
+    expect(tags).toEqual([
+      { tag: "work", count: 3, avgScore: 3 },
+      { tag: "sport", count: 2, avgScore: 4.5 },
+    ]);
+  });
+
+  it("excludes entries older than the window", () => {
+    const entries: MoodAggregateEntry[] = [
+      entry(1, 5, ["recent"]),
+      entry(2, 5, ["recent"]),
+      entry(200, 5, ["old"]),
+      entry(201, 5, ["old"]),
+    ];
+    const tags = computeTagSummary(entries, NOW, 90);
+    expect(tags.map((t) => t.tag)).toEqual(["recent"]);
+  });
+});
+
+describe("computeInTargetPct", () => {
+  it("returns the share of the newest 30 daily buckets in the green band", () => {
+    const daily = [
+      { dayOffset: 0, value: 4 },
+      { dayOffset: 1, value: 3 }, // below 3.5 → out
+      { dayOffset: 2, value: 5 },
+      { dayOffset: 3, value: 3.5 }, // exactly green min → in
+    ];
+    // 3 of 4 in target → 75
+    expect(computeInTargetPct(daily)).toBe(75);
+  });
+
+  it("ignores buckets older than 30 days and returns null when empty", () => {
+    expect(computeInTargetPct([{ dayOffset: 40, value: 5 }])).toBeNull();
+    expect(computeInTargetPct([])).toBeNull();
+  });
+});
+
+describe("computeDistribution", () => {
+  it("rounds daily means to discrete levels and reports every level 1..5", () => {
+    const daily = [
+      { dayOffset: 0, value: 5 },
+      { dayOffset: 1, value: 4.4 }, // → 4
+      { dayOffset: 2, value: 3.6 }, // → 4
+      { dayOffset: 3, value: 1 },
+    ];
+    expect(computeDistribution(daily)).toEqual([
+      { score: 1, count: 1 },
+      { score: 2, count: 0 },
+      { score: 3, count: 0 },
+      { score: 4, count: 2 },
+      { score: 5, count: 1 },
+    ]);
+  });
+});
+
+describe("computeWeekdayAverages", () => {
+  it("groups daily means by Monday-aligned weekday", () => {
+    // 2026-06-01 is a Monday (UTC). dayOffset 0 = Mon, 1 = Sun, 7 = Mon.
+    const daily = [
+      { dayOffset: 0, value: 4 }, // Mon
+      { dayOffset: 7, value: 2 }, // Mon
+      { dayOffset: 1, value: 5 }, // Sun
+    ];
+    const rows = computeWeekdayAverages(daily, NOW);
+    const mon = rows.find((r) => r.weekday === 0);
+    const sun = rows.find((r) => r.weekday === 6);
+    expect(mon).toEqual({ weekday: 0, avgScore: 3, count: 2 });
+    expect(sun).toEqual({ weekday: 6, avgScore: 5, count: 1 });
+    // every weekday present
+    expect(rows).toHaveLength(7);
+    expect(rows.find((r) => r.weekday === 2)).toEqual({
+      weekday: 2,
+      avgScore: null,
+      count: 0,
+    });
+  });
+});
+
+describe("computeHeatmapCells", () => {
+  it("averages multi-entry days and clips to the window", () => {
+    const entries: MoodAggregateEntry[] = [
+      entry(0, 4),
+      { ...entry(0, 2), moodLoggedAt: new Date(NOW.getTime() - 0.1 * dayMs) },
+      entry(5, 1),
+      entry(45, 3), // outside a 30-day window
+    ];
+    const cells = computeHeatmapCells(entries, NOW, 30);
+    const today = cells.find((c) => c.date === dayKey(0));
+    expect(today).toEqual({ date: dayKey(0), score: 3, samples: 2 });
+    // The 45-day-old entry is clipped.
+    expect(cells.find((c) => c.date === dayKey(45))).toBeUndefined();
+    // Sorted ascending by date.
+    expect(cells.map((c) => c.date)).toEqual(
+      [...cells.map((c) => c.date)].sort(),
+    );
+  });
+});
+
+describe("computeMoodMetricCorrelation", () => {
+  it("pairs on dayOffset and returns scatter points + a coefficient", () => {
+    const moodDaily = [
+      { dayOffset: 0, value: 5 },
+      { dayOffset: 1, value: 4 },
+      { dayOffset: 2, value: 3 },
+      { dayOffset: 3, value: 2 },
+      { dayOffset: 4, value: 1 },
+    ];
+    // Perfectly positively correlated metric.
+    const metricDaily = moodDaily.map((b) => ({
+      dayOffset: b.dayOffset,
+      value: b.value * 10,
+    }));
+    const corr = computeMoodMetricCorrelation(moodDaily, metricDaily, NOW);
+    expect(corr.n).toBe(5);
+    expect(corr.points).toHaveLength(5);
+    expect(corr.result?.r).toBe(1);
+    expect(corr.points[0]).toEqual({ x: 5, y: 50 });
+  });
+
+  it("returns a null coefficient below the minimum pair count", () => {
+    const moodDaily = [
+      { dayOffset: 0, value: 5 },
+      { dayOffset: 1, value: 4 },
+    ];
+    const metricDaily = [{ dayOffset: 0, value: 1 }];
+    const corr = computeMoodMetricCorrelation(moodDaily, metricDaily, NOW);
+    expect(corr.n).toBe(1);
+    expect(corr.result).toBeNull();
+  });
+});
+
+describe("computeMoodAggregates", () => {
+  it("assembles every dimension and derives the summary headline", () => {
+    const entries: MoodAggregateEntry[] = [];
+    for (let day = 0; day < 200; day++) {
+      entries.push(entry(day, ((day % 5) + 1) as number, ["daily"]));
+    }
+    // oldest-first ordering (matches the DB read .reverse()).
+    entries.reverse();
+
+    const measurements: CrossMetricMeasurement[] = [];
+    for (let day = 0; day < 10; day++) {
+      measurements.push({
+        type: "PULSE",
+        value: 60 + day,
+        measuredAt: new Date(NOW.getTime() - day * dayMs),
+      });
+    }
+
+    const agg = computeMoodAggregates({ entries, measurements, now: NOW });
+
+    // 200 days of history → 365-day heatmap window.
+    expect(agg.heatmap.windowDays).toBe(365);
+    expect(agg.summary.totalEntries).toBe(200);
+    expect(agg.summary.totalSpanDays).toBe(199);
+    expect(agg.distribution).toHaveLength(5);
+    expect(agg.weekday).toHaveLength(7);
+    expect(agg.tags.map((t) => t.tag)).toContain("daily");
+    expect(agg.correlations.pulse.n).toBeGreaterThanOrEqual(5);
+    // No sleep / steps rows supplied → empty correlation.
+    expect(agg.correlations.sleep.n).toBe(0);
+    expect(agg.correlations.sleep.result).toBeNull();
+  });
+
+  it("handles an empty entry set without throwing", () => {
+    const agg = computeMoodAggregates({
+      entries: [],
+      measurements: [],
+      now: NOW,
+    });
+    expect(agg.summary.totalEntries).toBe(0);
+    expect(agg.summary.mean).toBeNull();
+    expect(agg.heatmap.windowDays).toBe(30);
+    expect(agg.heatmap.cells).toEqual([]);
+    expect(agg.distribution.every((d) => d.count === 0)).toBe(true);
+  });
+});
diff --git a/src/lib/insights/mood-aggregates.ts b/src/lib/insights/mood-aggregates.ts
new file mode 100644
index 000000000..76de65865
--- /dev/null
+++ b/src/lib/insights/mood-aggregates.ts
@@ -0,0 +1,503 @@
+/**
+ * v1.8.5 — shared mood-aggregate computation.
+ *
+ * Single source of truth for the analytics the mood surface needs.
+ * `mood-status.ts` (the LLM snapshot builder) and `/api/mood/insights`
+ * (the visualization endpoint) both consume these pure functions so the
+ * numbers the user sees match the numbers the model reasons over — no
+ * drift between the prose and the charts.
+ *
+ * Everything here is a pure function over already-fetched rows. The DB
+ * read + orchestration lives in `fetchMoodAggregates` at the bottom;
+ * the per-dimension helpers above it take plain arrays so they unit-test
+ * without a database.
+ */
+
+import { prisma } from "@/lib/db";
+import {
+  pearsonCorrelation,
+  type CorrelationResult,
+  type PairedPoint,
+} from "@/lib/analytics/correlations";
+import {
+  applyPayloadBudget,
+  dayOffsetToBerlinDayKey,
+  type DailyBucket,
+} from "@/lib/insights/bucket-series";
+import { round, summarizeSeries } from "@/lib/insights/status-shared";
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * Minimal daily-bucket shape the aggregates read. `DailyBucket` (from
+ * `bucket-series`) carries an extra `n` field; the helpers only ever
+ * touch `dayOffset` + `value`, so accepting the narrow shape keeps them
+ * trivially testable without synthesising the unused field.
+ */
+type DailyPoint = Pick<DailyBucket, "dayOffset" | "value">;
+
+/** Raw mood row shape the aggregates operate on. */
+export interface MoodAggregateEntry {
+  /** TZ-anchored day key (YYYY-MM-DD). */
+  date: string;
+  /** Numeric mood score 1..5. */
+  score: number;
+  /** JSON tag array, or null. */
+  tags: unknown;
+  /** Exact log timestamp — carries time-of-day. */
+  moodLoggedAt: Date;
+}
+
+/** Cross-metric row shape (WEIGHT / BLOOD_PRESSURE_SYS / PULSE / …). */
+export interface CrossMetricMeasurement {
+  type: string;
+  value: number;
+  measuredAt: Date;
+}
+
+// --- Target bands (mirror mood-chart VALUE_BANDS + mood-status) ---
+
+/**
+ * The mood-status generator grades "in target" as score >= 3.5. The
+ * mood-chart paints three reference bands (1–2 red, 2–3 orange, 3–5
+ * green). We keep both anchored here so the heatmap colour map and the
+ * in-target headline never drift from the line chart.
+ */
+export const MOOD_GREEN_MIN = 3.5;
+export const MOOD_GREEN_MAX = 5;
+export const MOOD_ORANGE_MIN = 2;
+export const MOOD_ORANGE_MAX = 3.5;
+
+// --- Pair two daily-bucket series on dayOffset (lifted from mood-status) ---
+
+/**
+ * Pair two daily-bucket series on `dayOffset`. The synthesised `date`
+ * field is anchored at the UTC midnight of the Berlin calendar day —
+ * `dayOffsetToBerlinDayKey()` is the source of truth so DST boundaries
+ * don't slip the day-key by one. Each pair also carries `dayKey`
+ * directly so callers can label points without re-formatting.
+ */
+export function pairDailyBuckets(
+  seriesA: DailyPoint[],
+  seriesB: DailyPoint[],
+  now: Date,
+): Array<PairedPoint & { dayKey: string }> {
+  const mapB = new Map(seriesB.map((entry) => [entry.dayOffset, entry.value]));
+
+  return seriesA
+    .map((entry) => {
+      const b = mapB.get(entry.dayOffset);
+      if (b == null) return null;
+      const dayKey = dayOffsetToBerlinDayKey(now, entry.dayOffset);
+      const [y, m, d] = dayKey.split("-").map(Number);
+      return {
+        a: entry.value,
+        b,
+        date: new Date(Date.UTC(y, m - 1, d)),
+        dayKey,
+      };
+    })
+    .filter(
+      (entry): entry is PairedPoint & { dayKey: string } => entry !== null,
+    );
+}
+
+// --- Tag frequency + per-tag avg score (lifted from mood-status) ---
+
+export interface TagSummaryRow {
+  tag: string;
+  count: number;
+  avgScore: number;
+}
+
+/**
+ * Tag frequency + per-tag average mood over a recency window.
+ *
+ * Keeps the v1.4.5 ~90-day window so the model still gets a recency-
+ * weighted view of tag patterns; the caller slices by date, not by
+ * record count. Only tags with count >= 2 survive (a single mention is
+ * noise), top 10 by frequency.
+ */
+export function computeTagSummary(
+  entries: MoodAggregateEntry[],
+  now: Date,
+  windowDays = 90,
+): TagSummaryRow[] {
+  const cutoff = now.getTime() - windowDays * MS_PER_DAY;
+  const tagCounts = new Map<string, { count: number; scoreSum: number }>();
+  for (const entry of entries) {
+    if (entry.moodLoggedAt.getTime() < cutoff) continue;
+    if (entry.tags && Array.isArray(entry.tags)) {
+      for (const tag of entry.tags as string[]) {
+        const current = tagCounts.get(tag) ?? { count: 0, scoreSum: 0 };
+        current.count += 1;
+        current.scoreSum += entry.score;
+        tagCounts.set(tag, current);
+      }
+    }
+  }
+  return Array.from(tagCounts.entries())
+    .filter(([, stats]) => stats.count >= 2)
+    .sort((a, b) => b[1].count - a[1].count)
+    .slice(0, 10)
+    .map(([tag, stats]) => ({
+      tag,
+      count: stats.count,
+      avgScore: round(stats.scoreSum / stats.count, 2),
+    }));
+}
+
+// --- In-target % over the last 30 daily points (lifted from mood-status) ---
+
+/**
+ * Share (0..100) of the newest 30 daily mood buckets that land in the
+ * green band (>= 3.5). Returns null when there is no recent data.
+ */
+export function computeInTargetPct(daily: DailyPoint[]): number | null {
+  const recent = daily.filter((bucket) => bucket.dayOffset < 30);
+  if (recent.length === 0) return null;
+  const inTarget = recent.filter(
+    (entry) => entry.value >= MOOD_GREEN_MIN && entry.value <= MOOD_GREEN_MAX,
+  ).length;
+  return round((inTarget / recent.length) * 100, 1);
+}
+
+// --- Mood distribution (share per discrete level) ---
+
+export interface DistributionRow {
+  /** Rounded mood level 1..5. */
+  score: number;
+  count: number;
+}
+
+/**
+ * Distribution of daily-mean mood across the five discrete levels.
+ *
+ * Open product question #2 (design §7) resolves to the daily-mean
+ * convention used everywhere else on the surface: each day contributes
+ * one observation, its mean rounded to the nearest level. This keeps
+ * multi-entry days from over-weighting the histogram and matches the
+ * heatmap (one cell per day).
+ */
+export function computeDistribution(daily: DailyPoint[]): DistributionRow[] {
+  const counts = new Map<number, number>();
+  for (const bucket of daily) {
+    const level = Math.min(5, Math.max(1, Math.round(bucket.value)));
+    counts.set(level, (counts.get(level) ?? 0) + 1);
+  }
+  const rows: DistributionRow[] = [];
+  for (let score = 1; score <= 5; score++) {
+    rows.push({ score, count: counts.get(score) ?? 0 });
+  }
+  return rows;
+}
+
+// --- Average mood by weekday ---
+
+export interface WeekdayRow {
+  /** 0 = Monday … 6 = Sunday. */
+  weekday: number;
+  avgScore: number | null;
+  count: number;
+}
+
+/**
+ * Average daily-mean mood grouped by weekday (Monday = 0). The weekday
+ * is read off the day-key in UTC so it matches the heatmap's UTC-anchored
+ * Monday alignment (`compliance-heatmap` reads `getUTCDay`).
+ */
+export function computeWeekdayAverages(
+  daily: DailyPoint[],
+  now: Date,
+): WeekdayRow[] {
+  const sums = new Map<number, { sum: number; count: number }>();
+  for (const bucket of daily) {
+    const dayKey = dayOffsetToBerlinDayKey(now, bucket.dayOffset);
+    const d = new Date(dayKey + "T00:00:00Z");
+    const weekday = (d.getUTCDay() + 6) % 7; // Monday = 0
+    const cur = sums.get(weekday) ?? { sum: 0, count: 0 };
+    cur.sum += bucket.value;
+    cur.count += 1;
+    sums.set(weekday, cur);
+  }
+  const rows: WeekdayRow[] = [];
+  for (let weekday = 0; weekday < 7; weekday++) {
+    const agg = sums.get(weekday);
+    rows.push({
+      weekday,
+      avgScore: agg ? round(agg.sum / agg.count, 2) : null,
+      count: agg?.count ?? 0,
+    });
+  }
+  return rows;
+}
+
+// --- Heatmap (one cell per day, score band per cell) ---
+
+export type HeatmapWindowDays = 30 | 90 | 365;
+
+/**
+ * Adaptive heatmap window so the grid is never mostly-empty.
+ *
+ * - < 90 days of history → 30-day window (a fresh logger sees a dense
+ *   month, not a sparse year).
+ * - 90..180 days → 90-day window.
+ * - > 180 days → 365-day "year in pixels" (Daylio parity).
+ *
+ * `historyDays` is the span between the oldest and newest entry.
+ */
+export function selectHeatmapWindow(historyDays: number): HeatmapWindowDays {
+  if (historyDays > 180) return 365;
+  if (historyDays >= 90) return 90;
+  return 30;
+}
+
+export interface HeatmapCell {
+  /** YYYY-MM-DD day key. */
+  date: string;
+  /** Daily-mean mood score for the day. */
+  score: number;
+  /** Number of entries that fed the mean. */
+  samples: number;
+}
+
+/**
+ * Build the per-day heatmap cells from raw mood rows. One cell per day
+ * key carrying the daily mean (multi-entry days averaged), restricted to
+ * the adaptive window.
+ */
+export function computeHeatmapCells(
+  entries: MoodAggregateEntry[],
+  now: Date,
+  windowDays: HeatmapWindowDays,
+): HeatmapCell[] {
+  const cutoff = now.getTime() - windowDays * MS_PER_DAY;
+  const byDay = new Map<string, { sum: number; count: number }>();
+  for (const entry of entries) {
+    if (entry.moodLoggedAt.getTime() < cutoff) continue;
+    const cur = byDay.get(entry.date) ?? { sum: 0, count: 0 };
+    cur.sum += entry.score;
+    cur.count += 1;
+    byDay.set(entry.date, cur);
+  }
+  return Array.from(byDay.entries())
+    .map(([date, stats]) => ({
+      date,
+      score: round(stats.sum / stats.count, 2),
+      samples: stats.count,
+    }))
+    .sort((a, b) => a.date.localeCompare(b.date));
+}
+
+// --- Cross-metric correlation (lifted from mood-status) ---
+
+export interface CorrelationScatterPoint {
+  x: number;
+  y: number;
+  /** Index signature so the point satisfies the chart's
+   * `Record<string, number>` data constraint. */
+  [key: string]: number;
+}
+
+export interface MoodMetricCorrelation {
+  result: CorrelationResult | null;
+  /** Mood (x) vs metric (y) scatter points, paired by day. */
+  points: CorrelationScatterPoint[];
+  n: number;
+}
+
+/**
+ * Pearson correlation between the mood daily series and one metric daily
+ * series, paired on `dayOffset`. Returns the scatter points so the
+ * caller can paint a `<ScatterCorrelationChart>` from the same pairing
+ * the coefficient was computed over.
+ */
+export function computeMoodMetricCorrelation(
+  moodDaily: DailyPoint[],
+  metricDaily: DailyPoint[],
+  now: Date,
+): MoodMetricCorrelation {
+  const pairs = pairDailyBuckets(moodDaily, metricDaily, now);
+  const result = pearsonCorrelation(pairs);
+  const points = pairs.map((p) => ({ x: p.a, y: p.b }));
+  return { result, points, n: pairs.length };
+}
+
+// --- Orchestrated aggregate shape ---
+
+export interface MoodAggregates {
+  summary: {
+    points: number;
+    mean: number | null;
+    min: number | null;
+    max: number | null;
+    latest: number | null;
+    /** latest daily mean minus the previous daily mean. */
+    delta: number | null;
+    inTargetPct: number | null;
+    totalEntries: number;
+    totalSpanDays: number;
+    newestEntryDaysAgo: number | null;
+  };
+  heatmap: {
+    windowDays: HeatmapWindowDays;
+    cells: HeatmapCell[];
+  };
+  distribution: DistributionRow[];
+  weekday: WeekdayRow[];
+  tags: TagSummaryRow[];
+  correlations: {
+    sleep: MoodMetricCorrelation;
+    steps: MoodMetricCorrelation;
+    pulse: MoodMetricCorrelation;
+    weight: MoodMetricCorrelation;
+    bloodPressureSystolic: MoodMetricCorrelation;
+  };
+}
+
+/**
+ * Compute every mood aggregate from already-fetched rows. Pure — no DB
+ * access — so callers (the endpoint and the unit tests) control the
+ * fetch + the clock.
+ */
+export function computeMoodAggregates(args: {
+  entries: MoodAggregateEntry[];
+  measurements: CrossMetricMeasurement[];
+  now: Date;
+}): MoodAggregates {
+  const { entries, measurements, now } = args;
+
+  const moodPoints = entries.map((entry) => ({
+    measuredAt: entry.moodLoggedAt,
+    value: entry.score,
+  }));
+  const moodSeries = applyPayloadBudget(moodPoints, { now });
+  const moodDaily = moodSeries.daily;
+
+  const moodSummary = summarizeSeries(
+    moodDaily.map((bucket) => ({ value: bucket.value })),
+  );
+
+  // daily[0] = newest bucket (lowest dayOffset).
+  const latest = moodDaily[0] ?? null;
+  const previous = moodDaily[1] ?? null;
+
+  const oldestEntry = entries.length > 0 ? entries[0].moodLoggedAt : null;
+  const newestEntry =
+    entries.length > 0 ? entries[entries.length - 1].moodLoggedAt : null;
+  const totalSpanDays =
+    oldestEntry && newestEntry
+      ? Math.round((newestEntry.getTime() - oldestEntry.getTime()) / MS_PER_DAY)
+      : 0;
+  const newestEntryDaysAgo = newestEntry
+    ? Math.round((now.getTime() - newestEntry.getTime()) / MS_PER_DAY)
+    : null;
+
+  const metricDaily = (type: string) =>
+    applyPayloadBudget(
+      measurements
+        .filter((m) => m.type === type)
+        .map((m) => ({ measuredAt: m.measuredAt, value: m.value })),
+      { now },
+    ).daily;
+
+  const windowDays = selectHeatmapWindow(totalSpanDays);
+
+  return {
+    summary: {
+      points: moodSummary?.points ?? 0,
+      mean: moodSummary?.mean ?? null,
+      min: moodSummary?.min ?? null,
+      max: moodSummary?.max ?? null,
+      latest: latest?.value ?? null,
+      delta:
+        latest && previous ? round(latest.value - previous.value, 2) : null,
+      inTargetPct: computeInTargetPct(moodDaily),
+      totalEntries: entries.length,
+      totalSpanDays,
+      newestEntryDaysAgo,
+    },
+    heatmap: {
+      windowDays,
+      cells: computeHeatmapCells(entries, now, windowDays),
+    },
+    distribution: computeDistribution(moodDaily),
+    weekday: computeWeekdayAverages(moodDaily, now),
+    tags: computeTagSummary(entries, now),
+    correlations: {
+      sleep: computeMoodMetricCorrelation(
+        moodDaily,
+        metricDaily("SLEEP_DURATION"),
+        now,
+      ),
+      steps: computeMoodMetricCorrelation(
+        moodDaily,
+        metricDaily("ACTIVITY_STEPS"),
+        now,
+      ),
+      pulse: computeMoodMetricCorrelation(
+        moodDaily,
+        metricDaily("PULSE"),
+        now,
+      ),
+      weight: computeMoodMetricCorrelation(
+        moodDaily,
+        metricDaily("WEIGHT"),
+        now,
+      ),
+      bloodPressureSystolic: computeMoodMetricCorrelation(
+        moodDaily,
+        metricDaily("BLOOD_PRESSURE_SYS"),
+        now,
+      ),
+    },
+  };
+}
+
+/**
+ * DB read + orchestration for the mood-insights endpoint.
+ *
+ * Bounded reads mirror the mood-status path: 365 days of mood rows (the
+ * heatmap window never exceeds a year) and 365 days × 5 cross-metric
+ * channels. Tombstoned rows are excluded so the analytics match the
+ * line chart.
+ */
+export async function fetchMoodAggregates(
+  userId: string,
+  now: Date = new Date(),
+): Promise<MoodAggregates> {
+  const windowCutoff = new Date(now.getTime() - 365 * MS_PER_DAY);
+
+  const entries = await prisma.moodEntry
+    .findMany({
+      where: { userId, deletedAt: null, moodLoggedAt: { gte: windowCutoff } },
+      orderBy: { moodLoggedAt: "desc" },
+      take: 2000,
+      select: { date: true, score: true, tags: true, moodLoggedAt: true },
+    })
+    .then((rows) => rows.reverse());
+
+  const measurements = await prisma.measurement
+    .findMany({
+      where: {
+        userId,
+        deletedAt: null,
+        measuredAt: { gte: windowCutoff },
+        type: {
+          in: [
+            "WEIGHT",
+            "BLOOD_PRESSURE_SYS",
+            "PULSE",
+            "SLEEP_DURATION",
+            "ACTIVITY_STEPS",
+          ],
+        },
+      },
+      orderBy: { measuredAt: "desc" },
+      take: 5000,
+      select: { type: true, value: true, measuredAt: true },
+    })
+    .then((rows) => rows.reverse());
+
+  return computeMoodAggregates({ entries, measurements, now });
+}
diff --git a/src/lib/insights/mood-status.ts b/src/lib/insights/mood-status.ts
index 5c762c4aa..5852677fc 100644
--- a/src/lib/insights/mood-status.ts
+++ b/src/lib/insights/mood-status.ts
@@ -5,15 +5,17 @@ import {
   formatPreviousContextForPrompt,
   getPreviousInsightContext,
 } from "@/lib/insights/memory";
+import { pearsonCorrelation } from "@/lib/analytics/correlations";
+import { applyPayloadBudget } from "@/lib/insights/bucket-series";
 import {
-  pearsonCorrelation,
-  type PairedPoint,
-} from "@/lib/analytics/correlations";
-import {
-  applyPayloadBudget,
-  dayOffsetToBerlinDayKey,
-  type DailyBucket,
-} from "@/lib/insights/bucket-series";
+  MOOD_GREEN_MAX,
+  MOOD_GREEN_MIN,
+  MOOD_ORANGE_MAX,
+  MOOD_ORANGE_MIN,
+  computeInTargetPct,
+  computeTagSummary,
+  pairDailyBuckets,
+} from "@/lib/insights/mood-aggregates";
 import {
   buildGradedSeriesFromPoints,
   degradeStatusSnapshotToBudget,
@@ -36,38 +38,6 @@ import { returnTimeoutFallback } from "@/lib/insights/timeout-fallback";
 import { annotate } from "@/lib/logging/context";
 import { toBerlinDayKey } from "@/lib/tz/resolver";
 
-/**
- * Pair two daily-bucket series on `dayOffset`. The synthesised `date`
- * field is anchored at the UTC midnight of the Berlin calendar day —
- * `dayOffsetToBerlinDayKey()` is the source of truth so DST boundaries
- * don't slip the day-key by one. Each pair also carries `dayKey`
- * directly so callers can label points without re-formatting.
- */
-function pairDailyBuckets(
-  seriesA: DailyBucket[],
-  seriesB: DailyBucket[],
-  now: Date,
-): Array<PairedPoint & { dayKey: string }> {
-  const mapB = new Map(seriesB.map((entry) => [entry.dayOffset, entry.value]));
-
-  return seriesA
-    .map((entry) => {
-      const b = mapB.get(entry.dayOffset);
-      if (b == null) return null;
-      const dayKey = dayOffsetToBerlinDayKey(now, entry.dayOffset);
-      const [y, m, d] = dayKey.split("-").map(Number);
-      return {
-        a: entry.value,
-        b,
-        date: new Date(Date.UTC(y, m - 1, d)),
-        dayKey,
-      };
-    })
-    .filter(
-      (entry): entry is PairedPoint & { dayKey: string } => entry !== null,
-    );
-}
-
 export async function generateMoodStatusForUser(
   userId: string,
   options?: {
@@ -161,26 +131,13 @@ export async function generateMoodStatusForUser(
     moodSeries.daily.map((bucket) => ({ value: bucket.value })),
   );
 
-  const greenMin = 3.5;
-  const greenMax = 5;
-  const orangeMin = 2;
-  const orangeMax = 3.5;
+  const greenMin = MOOD_GREEN_MIN;
+  const greenMax = MOOD_GREEN_MAX;
+  const orangeMin = MOOD_ORANGE_MIN;
+  const orangeMax = MOOD_ORANGE_MAX;
 
   // "Last 30 daily points" = the newest 30 daily buckets (offsets 0..29).
-  const recentMoodDaily = moodSeries.daily.filter(
-    (bucket) => bucket.dayOffset < 30,
-  );
-  const inTargetPctLast30DailyPoints =
-    recentMoodDaily.length === 0
-      ? null
-      : round(
-          (recentMoodDaily.filter(
-            (entry) => entry.value >= greenMin && entry.value <= greenMax,
-          ).length /
-            recentMoodDaily.length) *
-            100,
-          1,
-        );
+  const inTargetPctLast30DailyPoints = computeInTargetPct(moodSeries.daily);
 
   // daily[0] = newest bucket (lowest dayOffset).
   const latestMood = moodSeries.daily[0] ?? null;
@@ -262,32 +219,9 @@ export async function generateMoodStatusForUser(
 
   // Extract tag frequencies from recent entries — keep the v1.4.5
   // ~90-day window so the model still gets a recency-weighted view of
-  // tag patterns. The mood DB query already pulls 3 years (no where
-  // filter); we slice by date here, not by record count.
-  const tagWindowCutoff = new Date(now.getTime() - 90 * 24 * 60 * 60 * 1000);
-  const recentEntries = entries.filter(
-    (entry) => entry.moodLoggedAt.getTime() >= tagWindowCutoff.getTime(),
-  );
-  const tagCounts = new Map<string, { count: number; scoreSum: number }>();
-  for (const entry of recentEntries) {
-    if (entry.tags && Array.isArray(entry.tags)) {
-      for (const tag of entry.tags as string[]) {
-        const current = tagCounts.get(tag) ?? { count: 0, scoreSum: 0 };
-        current.count += 1;
-        current.scoreSum += entry.score;
-        tagCounts.set(tag, current);
-      }
-    }
-  }
-  const tagSummary = Array.from(tagCounts.entries())
-    .filter(([, stats]) => stats.count >= 2)
-    .sort((a, b) => b[1].count - a[1].count)
-    .slice(0, 10)
-    .map(([tag, stats]) => ({
-      tag,
-      count: stats.count,
-      avgScore: round(stats.scoreSum / stats.count, 2),
-    }));
+  // tag patterns. Shared with the `/api/mood/insights` tag breakdown
+  // via `computeTagSummary` so the prose and the chart never drift.
+  const tagSummary = computeTagSummary(entries, now);
 
   const snapshot = {
     locale,
diff --git a/src/lib/query-keys.ts b/src/lib/query-keys.ts
index 440e2a51d..88e9f5986 100644
--- a/src/lib/query-keys.ts
+++ b/src/lib/query-keys.ts
@@ -53,6 +53,13 @@ export const queryKeys = {
   analytics: (slice?: "summaries") =>
     (slice ? (["analytics", slice] as const) : (["analytics"] as const)),
   moodAnalytics: () => ["mood-analytics"] as const,
+  /**
+   * v1.8.5 — pre-computed mood-insights aggregates (heatmap, distribution,
+   * weekday, tag breakdown, cross-metric correlations) for the Mood
+   * Insights page. Read-only; invalidated on a mood write through the
+   * `moodDependentKeys` fan-out below.
+   */
+  moodInsights: () => ["mood-insights"] as const,
 
   /**
    * v1.7.0 W6 — unified dashboard first-paint snapshot. One client cell
@@ -385,6 +392,7 @@ export const measurementDependentKeys = [
 export const moodDependentKeys = [
   queryKeys.moodEntries(),
   queryKeys.moodAnalytics(),
+  queryKeys.moodInsights(),
   queryKeys.insightsRoot(),
   queryKeys.insightsTargets(),
   queryKeys.gamificationAchievements(),

From b99a0152667282b400f366a53f461a46f5c3ee61 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 20:17:34 +0200
Subject: [PATCH 08/30] feat(medications): make injection-site tracking and
 rotation real
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The injection_site column on intake events was read across several
surfaces but never written, so site tracking was effectively dead. Wire
it end-to-end as a per-medication opt-in, gated on an INJECTION delivery
form and default off.

- Schema: add medications.track_injection_sites + allowed_injection_sites
  and users.global_excluded_injection_sites (migrations 0099, 0100;
  additive, defaulted, no backfill).
- Intake write path: accept an optional injectionSite on the per-med,
  status-toggle, and bulk intake routes. Persist it only on a taken
  injection with tracking enabled, validated against the medication's
  effective allowed set (per-med allowed sites minus the user-level
  global exclusion, deny wins) — a disallowed site returns 422 (the bulk
  route skips the entry).
- Rotation: extend the least-recently-used recommender with an allowed
  filter; the picker disables sites outside the effective set.
- UI: per-medication tracking toggle + allowed-sites editor in the dose
  wizard step, a skippable post-dose site prompt on both medication
  cards, and a Settings card for the user-level global exclusion.
- Contract: injectionSite is additive on the intake request; OpenAPI
  regenerated. New GET/PATCH /api/auth/me/injection-site-prefs.

The site capture is always optional and never blocks logging a dose.
---
 .../v1.8.5-server-to-ios-injection-site.md    |  82 +++++++++++
 docs/api/openapi.yaml                         |  59 +++++++-
 messages/de.json                              |  17 ++-
 messages/en.json                              |  17 ++-
 messages/es.json                              |  17 ++-
 messages/fr.json                              |  17 ++-
 messages/it.json                              |  17 ++-
 messages/pl.json                              |  17 ++-
 .../migration.sql                             |  34 +++++
 .../migration.sql                             |  30 ++++
 prisma/schema.prisma                          |  20 +++
 .../api/auth/me/injection-site-prefs/route.ts | 129 +++++++++++++++++
 src/app/api/medications/[id]/intake/route.ts  |  56 +++++++-
 src/app/api/medications/[id]/route.ts         |   7 +
 src/app/api/medications/intake/bulk/route.ts  |  69 ++++++++-
 src/app/api/medications/intake/route.ts       |  56 +++++++-
 src/app/api/medications/route.ts              |   6 +
 src/app/medications/page.tsx                  |   6 +
 .../medications/glp1-medication-card.tsx      |  60 ++++++++
 .../medications/injection-site-picker.tsx     |  56 ++++++--
 .../medications/log-injection-site-dialog.tsx | 110 +++++++++++++++
 .../medications/medication-card.tsx           |  60 ++++++++
 .../medications/wizard/steps/Step3Dose.tsx    | 132 +++++++++++++-----
 .../medications/wizard/wizard-payload.ts      |  36 +++++
 src/components/settings/dashboard-section.tsx |   3 +
 .../settings/injection-sites-card.tsx         |  91 ++++++++++++
 .../__tests__/injection-site-write.test.ts    |  79 +++++++++++
 .../__tests__/injection-sites.test.ts         |  91 ++++++++++++
 src/lib/medications/injection-site-write.ts   |  79 +++++++++++
 src/lib/medications/injection-sites.ts        |  75 +++++++++-
 src/lib/medications/scheduling/slot-upsert.ts |  27 +++-
 .../medications/use-injection-site-prefs.ts   |  29 ++++
 src/lib/query-keys.ts                         |   3 +
 src/lib/validations/medication.ts             |  67 ++++++++-
 34 files changed, 1577 insertions(+), 77 deletions(-)
 create mode 100644 .planning/ios-coord/v1.8.5-server-to-ios-injection-site.md
 create mode 100644 prisma/migrations/0099_v185_medication_injection_tracking/migration.sql
 create mode 100644 prisma/migrations/0100_v185_user_global_excluded_injection_sites/migration.sql
 create mode 100644 src/app/api/auth/me/injection-site-prefs/route.ts
 create mode 100644 src/components/medications/log-injection-site-dialog.tsx
 create mode 100644 src/components/settings/injection-sites-card.tsx
 create mode 100644 src/lib/medications/__tests__/injection-site-write.test.ts
 create mode 100644 src/lib/medications/injection-site-write.ts
 create mode 100644 src/lib/medications/use-injection-site-prefs.ts

diff --git a/.planning/ios-coord/v1.8.5-server-to-ios-injection-site.md b/.planning/ios-coord/v1.8.5-server-to-ios-injection-site.md
new file mode 100644
index 000000000..71a999f18
--- /dev/null
+++ b/.planning/ios-coord/v1.8.5-server-to-ios-injection-site.md
@@ -0,0 +1,82 @@
+# v1.8.5 — server → iOS: injection-site capture on intake
+
+**Direction:** server → iOS
+**Status:** additive, non-breaking. iOS adoption is optional.
+
+## What changed
+
+Injection-site tracking is now real on the server. The `injectionSite`
+column on the intake event existed but was never written; v1.8.5 makes
+the capture + rotation path end-to-end.
+
+### 1. New optional request field: `injectionSite`
+
+`POST /api/medications/{id}/intake`, `POST /api/medications/intake`
+(status toggle), and `POST /api/medications/intake/bulk` now accept an
+optional `injectionSite` on a **taken** write. Enum values:
+
+```
+ABDOMEN_LEFT, ABDOMEN_RIGHT, ABDOMEN_UPPER_LEFT, ABDOMEN_UPPER_RIGHT,
+THIGH_LEFT, THIGH_RIGHT, UPPER_ARM_LEFT, UPPER_ARM_RIGHT
+```
+
+The field is **optional everywhere** — omit it and the dose records
+exactly as before. There is no behaviour change for any existing client
+that never sends it. (It is the same enum the response already echoes via
+the GLP-1 detail endpoint, so the type is already known to the client.)
+
+### 2. Server-side gating + validation (important for iOS UX)
+
+The server only persists `injectionSite` when ALL hold:
+
+- the dose is being recorded **taken** (never on a skip),
+- the medication is `deliveryForm === "INJECTION"`,
+- the medication has `trackInjectionSites === true`,
+- the submitted site is in the medication's **effective allowed set**.
+
+The effective allowed set = the per-medication `allowedInjectionSites`
+(empty = all eight) **minus** the user-level
+`globalExcludedInjectionSites` deny-list. **Deny always wins**: a site the
+user globally excluded is never valid even if a medication lists it as
+preferred.
+
+A submitted site outside the effective set:
+- per-medication + status-toggle routes → **422**
+  `errorCode: "medications.intake.injection_site.disallowed"`.
+- bulk route → that entry is reported `status: "skipped"`,
+  `reason: "injection_site_not_allowed"` (the batch still succeeds).
+
+A site sent for a non-injection / tracking-off medication, or on a skip,
+is silently dropped (the dose still records, no error).
+
+iOS should only offer the picker when the medication is an injection with
+tracking enabled, and restrict the choices to the effective allowed set,
+so the 422 path stays an edge case (stale UI / race).
+
+### 3. New medication fields (read + write)
+
+`GET /api/medications` and `GET /api/medications/{id}` now echo:
+
+- `trackInjectionSites: boolean` (default `false`)
+- `allowedInjectionSites: InjectionSite[]` (default `[]` = no restriction)
+
+`POST /api/medications` + `PUT /api/medications/{id}` accept both as
+optional fields (field-by-field; `false` / `[]` are valid explicit
+values — `false` deactivates tracking, `[]` clears the per-med list).
+
+### 4. New user-level endpoint
+
+`GET` / `PATCH /api/auth/me/injection-site-prefs`
+
+```
+{ "globalExcludedInjectionSites": InjectionSite[] }
+```
+
+The PATCH hard-sets the deny-list (empty array clears it). 60/min rate
+limit, same envelope as `unit-preference`.
+
+## Contract source
+
+All of the above is in `docs/api/openapi.yaml` (regenerated this
+release). No field was removed or renamed; every addition is optional /
+defaulted. Existing iOS builds keep working untouched.
diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml
index 5e72f31ea..89be8acd4 100644
--- a/docs/api/openapi.yaml
+++ b/docs/api/openapi.yaml
@@ -2123,6 +2123,26 @@ components:
             - ORAL
             - INJECTION
             - OTHER
+        trackInjectionSites:
+          description: Per-medication injection-site tracking opt-in. Default false. Only meaningful for an INJECTION delivery
+            form; when true the client prompts (skippably) for the site after a taken dose.
+          type: boolean
+        allowedInjectionSites:
+          description: Per-medication allowed / preferred injection sites. Empty array = no per-medication restriction (every site
+            offered). The effective pickable set is this list minus the user's global exclusion.
+          maxItems: 8
+          type: array
+          items:
+            type: string
+            enum:
+              - ABDOMEN_LEFT
+              - ABDOMEN_RIGHT
+              - ABDOMEN_UPPER_LEFT
+              - ABDOMEN_UPPER_RIGHT
+              - THIGH_LEFT
+              - THIGH_RIGHT
+              - UPPER_ARM_LEFT
+              - UPPER_ARM_RIGHT
         notificationsEnabled:
           type: boolean
         liveActivityEnabled:
@@ -2303,6 +2323,26 @@ components:
             - ORAL
             - INJECTION
             - OTHER
+        trackInjectionSites:
+          description: Per-medication injection-site tracking opt-in. Only meaningful for an INJECTION delivery form. Set false to
+            deactivate tracking.
+          type: boolean
+        allowedInjectionSites:
+          description: Per-medication allowed / preferred injection sites. Empty array clears the restriction. The effective
+            pickable set subtracts the user's global exclusion (deny wins).
+          maxItems: 8
+          type: array
+          items:
+            type: string
+            enum:
+              - ABDOMEN_LEFT
+              - ABDOMEN_RIGHT
+              - ABDOMEN_UPPER_LEFT
+              - ABDOMEN_UPPER_RIGHT
+              - THIGH_LEFT
+              - THIGH_RIGHT
+              - UPPER_ARM_LEFT
+              - UPPER_ARM_RIGHT
         active:
           type: boolean
         notificationsEnabled:
@@ -2381,11 +2421,28 @@ components:
             row.
           type: string
           maxLength: 128
+        injectionSite:
+          description: Optional injection site for a taken dose. Honoured only when the medication is an INJECTION with
+            site-tracking enabled; validated against the medication's effective allowed set (per-medication allowed
+            sites minus the user's global exclusion). A disallowed site returns 422. Omit to record the dose without a
+            site.
+          type: string
+          enum:
+            - ABDOMEN_LEFT
+            - ABDOMEN_RIGHT
+            - ABDOMEN_UPPER_LEFT
+            - ABDOMEN_UPPER_RIGHT
+            - THIGH_LEFT
+            - THIGH_RIGHT
+            - UPPER_ARM_LEFT
+            - UPPER_ARM_RIGHT
       required:
         - medicationId
       description: Per-medication intake log body. Idempotent via `idempotencyKey`; the server also dedupes by a 60-second
         sliding window when the key is absent. Non-skipped intakes auto-decrement pen inventory (best-effort), refresh
-        the per-day compliance rollup, and — for one-shot medications — flip `active` to false.
+        the per-day compliance rollup, and — for one-shot medications — flip `active` to false. The optional
+        `injectionSite` is persisted only for an INJECTION medication with site-tracking enabled and is validated
+        against the medication's effective allowed set (422 on a disallowed value).
     MedicationExtractRequest:
       type: object
       properties:
diff --git a/messages/de.json b/messages/de.json
index f80464152..dbfd00e78 100644
--- a/messages/de.json
+++ b/messages/de.json
@@ -1271,7 +1271,18 @@
         "plannedSuffix": "geplant",
         "drugLevelDisclosure": "Geschätzte Wirkstoffkurve anzeigen"
       }
-    }
+    },
+    "logInjectionSiteTitle": "Injektionsstelle erfassen",
+    "logInjectionSiteDescription": "Wo hast du {name} gespritzt? Optional — du kannst dies überspringen.",
+    "logInjectionSiteSkip": "Überspringen",
+    "logInjectionSiteConfirm": "Stelle speichern",
+    "logInjectionSiteNoneAvailable": "Keine Injektionsstelle verfügbar — alle Stellen sind in deinen Einstellungen ausgeschlossen.",
+    "trackInjectionSitesToggle": "Injektionsstellen erfassen",
+    "trackInjectionSitesHint": "Nach einer eingenommenen Dosis nach der verwendeten Stelle fragen und die nächste Rotation vorschlagen.",
+    "allowedSitesLabel": "Erlaubte Stellen",
+    "allowedSitesHint": "Alle ausgewählt lassen für keine Einschränkung. Global ausgeschlossene Stellen werden nie angeboten.",
+    "injectionRotationOverviewTitle": "Stellen-Rotation",
+    "injectionRotationNextSuggested": "Vorschlag als Nächstes: {site}"
   },
   "charts": {
     "loadingLabel": "Diagramm wird geladen…",
@@ -3074,7 +3085,9 @@
       "fhirNote": "Die strukturierte Ausgabe folgt dem FHIR-R4-Standard (ePA-kompatibel).",
       "generate": "Erstellen",
       "error": "Export fehlgeschlagen ({code})."
-    }
+    },
+    "globalExcludedInjectionSitesLabel": "Global ausgeschlossene Injektionsstellen",
+    "globalExcludedInjectionSitesHint": "Hier gelistete Stellen werden für keine Medikation angeboten und beim Erfassen einer Dosis abgelehnt — auch wenn eine Medikation sie bevorzugt."
   },
   "admin": {
     "title": "Administration",
diff --git a/messages/en.json b/messages/en.json
index a27b5e425..83ec368d5 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -1271,7 +1271,18 @@
         "plannedSuffix": "planned",
         "drugLevelDisclosure": "Show estimated drug-level curve"
       }
-    }
+    },
+    "logInjectionSiteTitle": "Log injection site",
+    "logInjectionSiteDescription": "Where did you inject {name}? Optional — you can skip this.",
+    "logInjectionSiteSkip": "Skip",
+    "logInjectionSiteConfirm": "Save site",
+    "logInjectionSiteNoneAvailable": "No injection site is available — every site is excluded in your settings.",
+    "trackInjectionSitesToggle": "Track injection sites",
+    "trackInjectionSitesHint": "After a dose is taken, ask which site was used and suggest the next rotation.",
+    "allowedSitesLabel": "Allowed sites",
+    "allowedSitesHint": "Leave all selected for no restriction. Sites you excluded globally are never offered.",
+    "injectionRotationOverviewTitle": "Site rotation",
+    "injectionRotationNextSuggested": "Suggested next: {site}"
   },
   "charts": {
     "loadingLabel": "Loading chart…",
@@ -3074,7 +3085,9 @@
       "fhirNote": "The structured output follows the FHIR R4 standard (ePA-compatible).",
       "generate": "Generate",
       "error": "Export failed ({code})."
-    }
+    },
+    "globalExcludedInjectionSitesLabel": "Globally excluded injection sites",
+    "globalExcludedInjectionSitesHint": "Sites listed here are never offered for any medication and rejected when logging a dose, even if a medication prefers them."
   },
   "admin": {
     "title": "Administration",
diff --git a/messages/es.json b/messages/es.json
index 5c75fa700..00e26dad5 100644
--- a/messages/es.json
+++ b/messages/es.json
@@ -1271,7 +1271,18 @@
         "plannedSuffix": "planificado",
         "drugLevelDisclosure": "Mostrar curva estimada del principio activo"
       }
-    }
+    },
+    "logInjectionSiteTitle": "Log injection site",
+    "logInjectionSiteDescription": "Where did you inject {name}? Optional — you can skip this.",
+    "logInjectionSiteSkip": "Skip",
+    "logInjectionSiteConfirm": "Save site",
+    "logInjectionSiteNoneAvailable": "No injection site is available — every site is excluded in your settings.",
+    "trackInjectionSitesToggle": "Track injection sites",
+    "trackInjectionSitesHint": "After a dose is taken, ask which site was used and suggest the next rotation.",
+    "allowedSitesLabel": "Allowed sites",
+    "allowedSitesHint": "Leave all selected for no restriction. Sites you excluded globally are never offered.",
+    "injectionRotationOverviewTitle": "Site rotation",
+    "injectionRotationNextSuggested": "Suggested next: {site}"
   },
   "charts": {
     "loadingLabel": "Cargando la gráfica…",
@@ -3074,7 +3085,9 @@
       "fhirNote": "La salida estructurada sigue el estándar FHIR R4 (compatible con ePA).",
       "generate": "Generar",
       "error": "Error en la exportación ({code})."
-    }
+    },
+    "globalExcludedInjectionSitesLabel": "Globally excluded injection sites",
+    "globalExcludedInjectionSitesHint": "Sites listed here are never offered for any medication and rejected when logging a dose, even if a medication prefers them."
   },
   "admin": {
     "title": "Administration",
diff --git a/messages/fr.json b/messages/fr.json
index 477e1d1df..91fc51b2c 100644
--- a/messages/fr.json
+++ b/messages/fr.json
@@ -1271,7 +1271,18 @@
         "plannedSuffix": "prévu",
         "drugLevelDisclosure": "Afficher la courbe estimée du principe actif"
       }
-    }
+    },
+    "logInjectionSiteTitle": "Log injection site",
+    "logInjectionSiteDescription": "Where did you inject {name}? Optional — you can skip this.",
+    "logInjectionSiteSkip": "Skip",
+    "logInjectionSiteConfirm": "Save site",
+    "logInjectionSiteNoneAvailable": "No injection site is available — every site is excluded in your settings.",
+    "trackInjectionSitesToggle": "Track injection sites",
+    "trackInjectionSitesHint": "After a dose is taken, ask which site was used and suggest the next rotation.",
+    "allowedSitesLabel": "Allowed sites",
+    "allowedSitesHint": "Leave all selected for no restriction. Sites you excluded globally are never offered.",
+    "injectionRotationOverviewTitle": "Site rotation",
+    "injectionRotationNextSuggested": "Suggested next: {site}"
   },
   "charts": {
     "loadingLabel": "Chargement du graphique…",
@@ -3074,7 +3085,9 @@
       "fhirNote": "La sortie structurée suit la norme FHIR R4 (compatible ePA).",
       "generate": "Générer",
       "error": "Échec de l’export ({code})."
-    }
+    },
+    "globalExcludedInjectionSitesLabel": "Globally excluded injection sites",
+    "globalExcludedInjectionSitesHint": "Sites listed here are never offered for any medication and rejected when logging a dose, even if a medication prefers them."
   },
   "admin": {
     "title": "Administration",
diff --git a/messages/it.json b/messages/it.json
index f8dffe04e..9dbe62040 100644
--- a/messages/it.json
+++ b/messages/it.json
@@ -1271,7 +1271,18 @@
         "plannedSuffix": "pianificato",
         "drugLevelDisclosure": "Mostra la curva stimata del principio attivo"
       }
-    }
+    },
+    "logInjectionSiteTitle": "Log injection site",
+    "logInjectionSiteDescription": "Where did you inject {name}? Optional — you can skip this.",
+    "logInjectionSiteSkip": "Skip",
+    "logInjectionSiteConfirm": "Save site",
+    "logInjectionSiteNoneAvailable": "No injection site is available — every site is excluded in your settings.",
+    "trackInjectionSitesToggle": "Track injection sites",
+    "trackInjectionSitesHint": "After a dose is taken, ask which site was used and suggest the next rotation.",
+    "allowedSitesLabel": "Allowed sites",
+    "allowedSitesHint": "Leave all selected for no restriction. Sites you excluded globally are never offered.",
+    "injectionRotationOverviewTitle": "Site rotation",
+    "injectionRotationNextSuggested": "Suggested next: {site}"
   },
   "charts": {
     "loadingLabel": "Caricamento del grafico…",
@@ -3074,7 +3085,9 @@
       "fhirNote": "L’output strutturato segue lo standard FHIR R4 (compatibile ePA).",
       "generate": "Genera",
       "error": "Esportazione non riuscita ({code})."
-    }
+    },
+    "globalExcludedInjectionSitesLabel": "Globally excluded injection sites",
+    "globalExcludedInjectionSitesHint": "Sites listed here are never offered for any medication and rejected when logging a dose, even if a medication prefers them."
   },
   "admin": {
     "title": "Administration",
diff --git a/messages/pl.json b/messages/pl.json
index f61ac8f73..51cb4985b 100644
--- a/messages/pl.json
+++ b/messages/pl.json
@@ -1271,7 +1271,18 @@
         "plannedSuffix": "zaplanowane",
         "drugLevelDisclosure": "Pokaż szacowaną krzywą stężenia leku"
       }
-    }
+    },
+    "logInjectionSiteTitle": "Log injection site",
+    "logInjectionSiteDescription": "Where did you inject {name}? Optional — you can skip this.",
+    "logInjectionSiteSkip": "Skip",
+    "logInjectionSiteConfirm": "Save site",
+    "logInjectionSiteNoneAvailable": "No injection site is available — every site is excluded in your settings.",
+    "trackInjectionSitesToggle": "Track injection sites",
+    "trackInjectionSitesHint": "After a dose is taken, ask which site was used and suggest the next rotation.",
+    "allowedSitesLabel": "Allowed sites",
+    "allowedSitesHint": "Leave all selected for no restriction. Sites you excluded globally are never offered.",
+    "injectionRotationOverviewTitle": "Site rotation",
+    "injectionRotationNextSuggested": "Suggested next: {site}"
   },
   "charts": {
     "loadingLabel": "Ładowanie wykresu…",
@@ -3074,7 +3085,9 @@
       "fhirNote": "Dane ustrukturyzowane są zgodne ze standardem FHIR R4 (kompatybilne z ePA).",
       "generate": "Generuj",
       "error": "Eksport nie powiódł się ({code})."
-    }
+    },
+    "globalExcludedInjectionSitesLabel": "Globally excluded injection sites",
+    "globalExcludedInjectionSitesHint": "Sites listed here are never offered for any medication and rejected when logging a dose, even if a medication prefers them."
   },
   "admin": {
     "title": "Administration",
diff --git a/prisma/migrations/0099_v185_medication_injection_tracking/migration.sql b/prisma/migrations/0099_v185_medication_injection_tracking/migration.sql
new file mode 100644
index 000000000..4d46e7985
--- /dev/null
+++ b/prisma/migrations/0099_v185_medication_injection_tracking/migration.sql
@@ -0,0 +1,34 @@
+-- v1.8.5 — per-medication injection-site tracking.
+--
+-- Makes injection-site tracking + rotation real. Prior to this release
+-- the `injection_site` column on `medication_intake_events` was read in
+-- several surfaces but never written; tracking was effectively dead.
+--
+-- Two additive, defaulted columns on `medications`:
+--
+--   - `track_injection_sites` — per-medication opt-in. Only meaningful
+--     (and only offered in the UI) when `delivery_form = 'INJECTION'`.
+--     Default false: the post-dose site prompt fires only when this is
+--     true, and the prompt is always skippable. Deactivatable any time.
+--
+--   - `allowed_injection_sites` — per-medication allowed / preferred
+--     sites. Empty = no per-medication restriction (every site offered).
+--     The effective pickable set is this list MINUS the user-level
+--     `users.global_excluded_injection_sites` deny-list (deny wins). The
+--     intake write path validates a submitted site against the effective
+--     set and rejects (422) a disallowed value.
+--
+-- Both columns are additive + defaulted; no backfill is required. The
+-- `injection_site` enum type already exists (migration 0046).
+--
+-- Idempotent guards (`IF NOT EXISTS`) make reruns safe.
+--
+-- Reversibility:
+--   ALTER TABLE "medications" DROP COLUMN IF EXISTS "track_injection_sites";
+--   ALTER TABLE "medications" DROP COLUMN IF EXISTS "allowed_injection_sites";
+-- A roll-back loses the opt-in flag + the per-medication site list; the
+-- application reads tolerate a missing column / default-empty value.
+
+ALTER TABLE "medications"
+    ADD COLUMN IF NOT EXISTS "track_injection_sites" BOOLEAN NOT NULL DEFAULT false,
+    ADD COLUMN IF NOT EXISTS "allowed_injection_sites" "injection_site"[] NOT NULL DEFAULT ARRAY[]::"injection_site"[];
diff --git a/prisma/migrations/0100_v185_user_global_excluded_injection_sites/migration.sql b/prisma/migrations/0100_v185_user_global_excluded_injection_sites/migration.sql
new file mode 100644
index 000000000..c6912a979
--- /dev/null
+++ b/prisma/migrations/0100_v185_user_global_excluded_injection_sites/migration.sql
@@ -0,0 +1,30 @@
+-- v1.8.5 — user-level global injection-site exclusion.
+--
+-- A per-user deny-list of injection sites. Sites listed here are never
+-- offered for ANY medication's injection-site picker, and the intake
+-- write path rejects (422) a submitted site that lands on this list —
+-- even when the per-medication `medications.allowed_injection_sites`
+-- lists it as preferred. Deny always wins.
+--
+-- Typical use: a user develops lipohypertrophy at one site and wants it
+-- excluded across every injectable they track, without editing each
+-- medication's allowed list individually.
+--
+-- Single additive, defaulted enum-array column on `users`. Default
+-- `'{}'` = no global exclusion (the pre-v1.8.5 behaviour). No backfill.
+-- The `injection_site` enum type already exists (migration 0046).
+--
+-- Idempotent guard (`IF NOT EXISTS`) makes reruns safe.
+--
+-- Reversibility:
+--   ALTER TABLE "users" DROP COLUMN IF EXISTS "global_excluded_injection_sites";
+-- A roll-back loses the global deny-list (every site becomes pickable
+-- again, subject to each medication's own allowed list); the
+-- application reads tolerate a missing column / default-empty value.
+--
+-- No index — reads are per-user at request time (`WHERE id = $1`),
+-- matching `insights_exclude_metrics` and the other display-pref
+-- columns on the same table.
+
+ALTER TABLE "users"
+    ADD COLUMN IF NOT EXISTS "global_excluded_injection_sites" "injection_site"[] NOT NULL DEFAULT ARRAY[]::"injection_site"[];
diff --git a/prisma/schema.prisma b/prisma/schema.prisma
index af4015027..b7060a1dd 100644
--- a/prisma/schema.prisma
+++ b/prisma/schema.prisma
@@ -43,6 +43,13 @@ model User {
   // behaviour for every existing row.
   insightsExcludeMetrics     String[]  @default([]) @map("insights_exclude_metrics")
 
+  // v1.8.5 — user-level injection-site deny-list. Sites listed here are
+  // never offered for ANY medication's injection-site picker and the
+  // intake write path 422s a submitted site that lands on this list,
+  // even when the per-medication `allowedInjectionSites` lists it as
+  // preferred (deny always wins). Default `[]` = no global exclusion.
+  globalExcludedInjectionSites InjectionSite[] @default([]) @map("global_excluded_injection_sites")
+
   // Telegram notifications (per-user)
   telegramBotToken String? @map("telegram_bot_token") // AES-256-GCM encrypted
   telegramChatId   String? @map("telegram_chat_id")
@@ -917,6 +924,19 @@ model Medication {
   /// A one-time injection is `oneShot = true` + `deliveryForm =
   /// INJECTION`. The migration backfills ORAL for every existing row.
   deliveryForm         MedicationDeliveryForm @default(ORAL) @map("delivery_form")
+  /// v1.8.5 — per-medication injection-site tracking opt-in. Only
+  /// meaningful (and only offered in the UI) when `deliveryForm ===
+  /// INJECTION`. Default false: after marking a dose taken the client
+  /// prompts for the site only when this is true, and the prompt is
+  /// always skippable (never blocking). Deactivatable at any time.
+  trackInjectionSites  Boolean @default(false) @map("track_injection_sites")
+  /// v1.8.5 — per-medication allowed / preferred injection sites. Empty
+  /// = no per-medication restriction (every site is offered). The
+  /// effective pickable set is this list MINUS the user-level
+  /// `globalExcludedInjectionSites` deny-list (deny always wins). The
+  /// intake write path validates a submitted site against the effective
+  /// set and 422s on a disallowed value.
+  allowedInjectionSites InjectionSite[] @default([]) @map("allowed_injection_sites")
   /// v1.7.0 — iOS Live Activity opt-in for this medication's reminders.
   /// Default false; existing rows backfill false. The server stores +
   /// echoes the flag; the iOS client owns the ActivityKit lifecycle. No
diff --git a/src/app/api/auth/me/injection-site-prefs/route.ts b/src/app/api/auth/me/injection-site-prefs/route.ts
new file mode 100644
index 000000000..b265988f0
--- /dev/null
+++ b/src/app/api/auth/me/injection-site-prefs/route.ts
@@ -0,0 +1,129 @@
+/**
+ * v1.8.5 — user-level injection-site preferences endpoint.
+ *
+ *  GET    /api/auth/me/injection-site-prefs
+ *    → `{ globalExcludedInjectionSites: InjectionSite[] }`
+ *
+ *  PATCH  /api/auth/me/injection-site-prefs
+ *    Body: `{ globalExcludedInjectionSites: InjectionSite[] }`
+ *    → the resolved next state (idempotent hard-set).
+ *
+ * The global exclusion is a per-user deny-list. Sites listed here are
+ * never offered for ANY medication's injection-site picker, and the
+ * intake write path rejects (422) a submitted site that lands on this
+ * list — even when a medication's `allowedInjectionSites` lists it as
+ * preferred (deny always wins).
+ *
+ * Mirrors the `unit-preference` per-user-scalar pattern: 60/min rate
+ * limit, Zod safeParse → 422 via `returnAllZodIssues`, audit-log row,
+ * field-by-field write (no mass assignment).
+ */
+import { z } from "zod/v4";
+
+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 {
+  injectionSiteEnum,
+  INJECTION_SITE_VALUES,
+  type InjectionSiteValue,
+} from "@/lib/validations/medication";
+import { NextRequest } from "next/server";
+
+export const dynamic = "force-dynamic";
+
+const PATCH_RATE_LIMIT = 60;
+const PATCH_WINDOW_MS = 60_000;
+
+const patchBodySchema = z.object({
+  // Dedup at write time; cap at the full enum size. An empty array
+  // clears the exclusion.
+  globalExcludedInjectionSites: z
+    .array(injectionSiteEnum)
+    .max(INJECTION_SITE_VALUES.length)
+    .meta({
+      description:
+        "User-level injection-site deny-list. Sites here are never offered for any medication and rejected at intake (deny wins). Empty array clears the exclusion.",
+    }),
+});
+
+interface InjectionSitePrefsResponse {
+  globalExcludedInjectionSites: InjectionSiteValue[];
+}
+
+export const GET = apiHandler(async () => {
+  const { user } = await requireAuth();
+  annotate({ action: { name: "auth.me.injection-site-prefs.get" } });
+
+  const row = await prisma.user.findUnique({
+    where: { id: user.id },
+    select: { globalExcludedInjectionSites: true },
+  });
+  const payload: InjectionSitePrefsResponse = {
+    globalExcludedInjectionSites: (row?.globalExcludedInjectionSites ??
+      []) as InjectionSiteValue[],
+  };
+  return apiSuccess(payload);
+});
+
+export const PATCH = apiHandler(async (request: NextRequest) => {
+  const { user } = await requireAuth();
+
+  const rl = await checkRateLimit(
+    `injection-site-prefs: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(request);
+  if (jsonError) return jsonError;
+
+  const parsed = patchBodySchema.safeParse(body);
+  if (!parsed.success) {
+    annotate({
+      action: { name: "auth.me.injection-site-prefs.patch.invalid_shape" },
+    });
+    return returnAllZodIssues(parsed.error, 422);
+  }
+
+  // Dedup while preserving canonical order from the enum tuple.
+  const submitted = new Set(parsed.data.globalExcludedInjectionSites);
+  const next = INJECTION_SITE_VALUES.filter((s) => submitted.has(s));
+
+  await prisma.user.update({
+    where: { id: user.id },
+    data: { globalExcludedInjectionSites: next },
+  });
+
+  await auditLog("user.injection-site-prefs.update", {
+    userId: user.id,
+    ipAddress: getClientIp(request),
+    details: { count: next.length },
+  });
+
+  annotate({
+    action: { name: "auth.me.injection-site-prefs.patch" },
+    meta: { excluded_count: next.length },
+  });
+
+  const payload: InjectionSitePrefsResponse = {
+    globalExcludedInjectionSites: next,
+  };
+  return apiSuccess(payload);
+});
diff --git a/src/app/api/medications/[id]/intake/route.ts b/src/app/api/medications/[id]/intake/route.ts
index 5984eda74..993dc1ac2 100644
--- a/src/app/api/medications/[id]/intake/route.ts
+++ b/src/app/api/medications/[id]/intake/route.ts
@@ -3,6 +3,7 @@ import { apiHandler, requireAuth } from "@/lib/api-handler";
 import { annotate } from "@/lib/logging/context";
 import { auditLog } from "@/lib/auth/audit";
 import {
+  apiError,
   apiSuccess,
   getClientIp,
   returnAllZodIssues,
@@ -13,6 +14,8 @@ import {
   intakeSchema,
   listIntakeEventsSchema,
 } from "@/lib/validations/medication";
+import { resolveInjectionSiteForWrite } from "@/lib/medications/injection-site-write";
+import type { InjectionSiteKey } from "@/lib/medications/injection-sites";
 import { withIdempotency } from "@/lib/idempotency";
 import { consumeOneDose } from "@/lib/medications/inventory/service";
 import { reconcileOneShotState } from "@/lib/medications/lifecycle";
@@ -76,7 +79,51 @@ async function postIntake(request: NextRequest, { params }: RouteParams) {
     return returnAllZodIssues(parsed.error, 422);
   }
 
-  const { scheduledFor, takenAt, skipped, idempotencyKey } = parsed.data;
+  const { scheduledFor, takenAt, skipped, idempotencyKey, injectionSite } =
+    parsed.data;
+
+  // v1.8.5 — resolve + server-validate the optional injection site. Load
+  // the medication's delivery form + tracking opt-in + per-medication
+  // allowed sites, plus the user's global exclusion deny-list. A site
+  // outside the effective allowed set is a hard 422; a site on a
+  // non-injection / tracking-off med (or a skip) is silently dropped.
+  let resolvedInjectionSite: InjectionSiteKey | null = null;
+  if (injectionSite !== undefined) {
+    const [med, userRow] = await Promise.all([
+      prisma.medication.findUnique({
+        where: { id },
+        select: {
+          deliveryForm: true,
+          trackInjectionSites: true,
+          allowedInjectionSites: true,
+        },
+      }),
+      prisma.user.findUnique({
+        where: { id: user.id },
+        select: { globalExcludedInjectionSites: true },
+      }),
+    ]);
+    const resolution = resolveInjectionSiteForWrite({
+      submitted: injectionSite,
+      taken: !skipped,
+      deliveryForm: med?.deliveryForm ?? "ORAL",
+      trackInjectionSites: med?.trackInjectionSites ?? false,
+      allowedInjectionSites: (med?.allowedInjectionSites ??
+        []) as InjectionSiteKey[],
+      globalExcludedInjectionSites: (userRow?.globalExcludedInjectionSites ??
+        []) as InjectionSiteKey[],
+    });
+    if (resolution.kind === "disallowed") {
+      annotate({
+        action: { name: "medication.intake.injection_site.disallowed" },
+        meta: { medication_id: id, site: resolution.site },
+      });
+      return apiError("Injection site is not allowed for this medication", 422, {
+        errorCode: "medications.intake.injection_site.disallowed",
+      });
+    }
+    resolvedInjectionSite = resolution.site;
+  }
 
   const resolvedTakenAt = skipped ? null : (takenAt ?? new Date());
   const incomingScheduledFor = scheduledFor ?? takenAt ?? new Date();
@@ -163,6 +210,9 @@ async function postIntake(request: NextRequest, { params }: RouteParams) {
       isExplicitSkip,
       idempotencyKey: idempotencyKey ?? null,
       createSource: "WEB",
+      // v1.8.5 — resolved + validated site (null unless a tracking-on
+      // injection taken write supplied an allowed site).
+      injectionSite: resolvedInjectionSite,
     });
     event = applied.row;
     consumedTransition = applied.consumedTransition;
@@ -186,6 +236,10 @@ async function postIntake(request: NextRequest, { params }: RouteParams) {
           skipped,
           source: "WEB",
           idempotencyKey: idempotencyKey ?? null,
+          // v1.8.5 — site only on a resolved taken-injection write.
+          ...(resolvedInjectionSite !== null && {
+            injectionSite: resolvedInjectionSite,
+          }),
         },
       }),
       // Reset snooze when medication is taken
diff --git a/src/app/api/medications/[id]/route.ts b/src/app/api/medications/[id]/route.ts
index a899b8c5b..c1abfc1bf 100644
--- a/src/app/api/medications/[id]/route.ts
+++ b/src/app/api/medications/[id]/route.ts
@@ -130,6 +130,8 @@ export const PUT = apiHandler(
       treatmentClass,
       dosesPerUnit,
       deliveryForm,
+      trackInjectionSites,
+      allowedInjectionSites,
       active,
       notificationsEnabled,
       liveActivityEnabled,
@@ -222,6 +224,11 @@ export const PUT = apiHandler(
       ...(treatmentClass !== undefined && { treatmentClass }),
       ...(dosesPerUnit !== undefined && { dosesPerUnit }),
       ...(deliveryForm !== undefined && { deliveryForm }),
+      // v1.8.5 — injection-site tracking opt-in + per-medication allowed
+      // sites. Field-by-field; `false` / `[]` are valid explicit values
+      // (deactivate tracking / clear the per-med restriction).
+      ...(trackInjectionSites !== undefined && { trackInjectionSites }),
+      ...(allowedInjectionSites !== undefined && { allowedInjectionSites }),
       ...(active !== undefined && { active }),
       ...(notificationsEnabled !== undefined && { notificationsEnabled }),
       // v1.7.0 — iOS reminder flags, field-by-field.
diff --git a/src/app/api/medications/intake/bulk/route.ts b/src/app/api/medications/intake/bulk/route.ts
index 660ddc731..6cfb38f89 100644
--- a/src/app/api/medications/intake/bulk/route.ts
+++ b/src/app/api/medications/intake/bulk/route.ts
@@ -51,6 +51,12 @@ import {
   applyCanonicalSlotWrite,
   resolveSlotInstantForWrite,
 } from "@/lib/medications/scheduling/slot-upsert";
+import { resolveInjectionSiteForWrite } from "@/lib/medications/injection-site-write";
+import {
+  injectionSiteEnum,
+  type InjectionSiteValue,
+} from "@/lib/validations/medication";
+import type { InjectionSiteKey } from "@/lib/medications/injection-sites";
 
 const MAX_ENTRIES_PER_BATCH = 500;
 const BATCH_RATE_LIMIT_MAX = 60;
@@ -68,6 +74,11 @@ const bulkEntrySchema = z.object({
     .optional(),
   skipped: z.boolean().optional().default(false),
   idempotencyKey: z.string().min(1).max(128).optional(),
+  // v1.8.5 — optional per-entry injection site. Validated against the
+  // medication's effective allowed set; a disallowed site marks the
+  // entry skipped (`injection_site_not_allowed`) without failing the
+  // whole batch, matching the bulk endpoint's per-entry contract.
+  injectionSite: injectionSiteEnum.optional(),
 });
 
 const bulkPayloadSchema = z.object({
@@ -157,9 +168,35 @@ async function postBulk(request: NextRequest): Promise<Response> {
   const medicationIds = Array.from(new Set(entries.map((e) => e.medicationId)));
   const ownedMedications = await prisma.medication.findMany({
     where: { id: { in: medicationIds }, userId: user.id },
-    select: { id: true },
+    // v1.8.5 — pull the injection-tracking fields so a per-entry
+    // `injectionSite` can be resolved + validated without an extra
+    // per-entry read.
+    select: {
+      id: true,
+      deliveryForm: true,
+      trackInjectionSites: true,
+      allowedInjectionSites: true,
+    },
   });
   const ownedSet = new Set(ownedMedications.map((m) => m.id));
+  const medById = new Map(ownedMedications.map((m) => [m.id, m]));
+
+  // v1.8.5 — the user's global exclusion deny-list, loaded once for the
+  // whole batch (it is user-scoped, not per-medication). Only read when
+  // at least one entry actually carries an `injectionSite`, so the hot
+  // sync path (no site) pays for zero extra round-trips.
+  const batchHasInjectionSite = entries.some(
+    (e) => e.injectionSite !== undefined,
+  );
+  let globalExcluded: InjectionSiteValue[] = [];
+  if (batchHasInjectionSite) {
+    const userRow = await prisma.user.findUnique({
+      where: { id: user.id },
+      select: { globalExcludedInjectionSites: true },
+    });
+    globalExcluded = (userRow?.globalExcludedInjectionSites ??
+      []) as InjectionSiteValue[];
+  }
 
   const results: EntryResult[] = [];
   let inserted = 0;
@@ -209,6 +246,31 @@ async function postBulk(request: NextRequest): Promise<Response> {
       const isExplicitTaken = !entry.skipped && entry.takenAt !== undefined;
       const isExplicitSkip = entry.skipped === true;
 
+      // v1.8.5 — resolve + validate the optional per-entry injection
+      // site. A disallowed site marks the entry skipped without failing
+      // the batch (per-entry contract); a non-injection / tracking-off /
+      // non-taken entry silently drops it.
+      let resolvedInjectionSite: InjectionSiteKey | null = null;
+      if (entry.injectionSite !== undefined) {
+        const med = medById.get(entry.medicationId);
+        const resolution = resolveInjectionSiteForWrite({
+          submitted: entry.injectionSite,
+          taken: isExplicitTaken,
+          deliveryForm: med?.deliveryForm ?? "ORAL",
+          trackInjectionSites: med?.trackInjectionSites ?? false,
+          allowedInjectionSites: (med?.allowedInjectionSites ??
+            []) as InjectionSiteKey[],
+          globalExcludedInjectionSites: globalExcluded as InjectionSiteKey[],
+        });
+        if (resolution.kind === "disallowed") {
+          const reason = "injection_site_not_allowed";
+          skipped.push({ index: i, reason });
+          results.push({ index: i, status: "skipped", reason });
+          continue;
+        }
+        resolvedInjectionSite = resolution.site;
+      }
+
       if (canonicalSlot) {
         // Scheduled dose — converge onto the one canonical slot row through
         // the shared upsert: H1 deterministic selection, C2 no-downgrade
@@ -226,6 +288,7 @@ async function postBulk(request: NextRequest): Promise<Response> {
           isExplicitSkip,
           idempotencyKey: entry.idempotencyKey ?? null,
           createSource: "API",
+          injectionSite: resolvedInjectionSite,
         });
         if (applied.noDowngradeNoOp) {
           // C2 — pending echo onto an already-actioned slot. Report it as a
@@ -253,6 +316,10 @@ async function postBulk(request: NextRequest): Promise<Response> {
             skipped: entry.skipped,
             source: "API",
             idempotencyKey: entry.idempotencyKey ?? null,
+            // v1.8.5 — site only on a resolved taken-injection entry.
+            ...(resolvedInjectionSite !== null && {
+              injectionSite: resolvedInjectionSite,
+            }),
           },
         });
         inserted += 1;
diff --git a/src/app/api/medications/intake/route.ts b/src/app/api/medications/intake/route.ts
index 77b31b80e..7e0792d2e 100644
--- a/src/app/api/medications/intake/route.ts
+++ b/src/app/api/medications/intake/route.ts
@@ -36,6 +36,11 @@ import {
   type ComplianceBucket as RollupComplianceBucket,
 } from "@/lib/rollups/medication-compliance-rollups";
 import { projectTodayIntakesAndRecompute } from "@/lib/medications/scheduling/project-today-intakes";
+import { resolveInjectionSiteForWrite } from "@/lib/medications/injection-site-write";
+import {
+  injectionSiteEnum,
+  type InjectionSiteValue,
+} from "@/lib/validations/medication";
 
 const querySchema = z.object({
   scope: z.enum(["today", "compliance"]),
@@ -53,6 +58,10 @@ const updateSchema = z.object({
     .datetime({ offset: true })
     .transform((s) => new Date(s))
     .optional(),
+  // v1.8.5 — optional injection site captured alongside a "taken"
+  // status toggle. Validated server-side against the medication's
+  // effective allowed set; ignored for skipped / snoozed.
+  injectionSite: injectionSiteEnum.optional(),
 });
 
 function startOfDayInTz(date: Date, tz: string): Date {
@@ -314,17 +323,58 @@ export const POST = apiHandler(async (request: NextRequest) => {
     return returnAllZodIssues(parsed.error, 422);
   }
 
-  const { intakeId, status, takenAt, snoozedUntil } = parsed.data;
+  const { intakeId, status, takenAt, snoozedUntil, injectionSite } =
+    parsed.data;
 
   // v1.7.0 sync — a tombstoned intake 404s on a status toggle; the
   // `deletedAt: null` filter refuses to mutate a soft-deleted row.
   const existing = await prisma.medicationIntakeEvent.findFirst({
     where: { id: intakeId, deletedAt: null },
+    include: {
+      medication: {
+        select: {
+          deliveryForm: true,
+          trackInjectionSites: true,
+          allowedInjectionSites: true,
+        },
+      },
+    },
   });
   if (!existing || existing.userId !== user.id) {
     return apiError("Intake event not found", 404);
   }
 
+  // v1.8.5 — resolve + server-validate the optional injection site for a
+  // "taken" toggle. A site outside the medication's effective allowed
+  // set is a hard 422; non-injection / tracking-off / non-taken drops it.
+  let resolvedInjectionSite: InjectionSiteValue | null = null;
+  if (injectionSite !== undefined) {
+    const userRow = await prisma.user.findUnique({
+      where: { id: user.id },
+      select: { globalExcludedInjectionSites: true },
+    });
+    const resolution = resolveInjectionSiteForWrite({
+      submitted: injectionSite,
+      taken: status === "taken",
+      deliveryForm: existing.medication.deliveryForm,
+      trackInjectionSites: existing.medication.trackInjectionSites,
+      allowedInjectionSites:
+        existing.medication.allowedInjectionSites as InjectionSiteValue[],
+      globalExcludedInjectionSites: (userRow?.globalExcludedInjectionSites ??
+        []) as InjectionSiteValue[],
+    });
+    if (resolution.kind === "disallowed") {
+      annotate({
+        action: { name: "medication.intake.injection_site.disallowed" },
+        meta: { medication_id: existing.medicationId, site: resolution.site },
+      });
+      return apiError("Injection site is not allowed for this medication", 422, {
+        errorCode: "medications.intake.injection_site.disallowed",
+      });
+    }
+    resolvedInjectionSite = resolution.site;
+  }
+
   const userTzForHook = user.timezone ?? DEFAULT_TIMEZONE;
 
   let updated;
@@ -338,6 +388,10 @@ export const POST = apiHandler(async (request: NextRequest) => {
           takenAt: takenAt ?? new Date(),
           skipped: false,
           syncVersion: { increment: 1 },
+          // v1.8.5 — persist the resolved site on the taken branch.
+          ...(resolvedInjectionSite !== null && {
+            injectionSite: resolvedInjectionSite,
+          }),
         },
       }),
       prisma.medication.update({
diff --git a/src/app/api/medications/route.ts b/src/app/api/medications/route.ts
index f04616a1b..8ab1cf5e6 100644
--- a/src/app/api/medications/route.ts
+++ b/src/app/api/medications/route.ts
@@ -155,6 +155,8 @@ export const POST = apiHandler(async (request: NextRequest) => {
     treatmentClass,
     dosesPerUnit,
     deliveryForm,
+    trackInjectionSites,
+    allowedInjectionSites,
     notificationsEnabled,
     liveActivityEnabled,
     criticalAlarmEnabled,
@@ -219,6 +221,10 @@ export const POST = apiHandler(async (request: NextRequest) => {
       ...(dosesPerUnit !== undefined && { dosesPerUnit }),
       // v1.6.0 — route of administration; Prisma defaults to ORAL when omitted.
       ...(deliveryForm !== undefined && { deliveryForm }),
+      // v1.8.5 — injection-site tracking opt-in + per-medication allowed
+      // sites; Prisma defaults to false / [] when omitted.
+      ...(trackInjectionSites !== undefined && { trackInjectionSites }),
+      ...(allowedInjectionSites !== undefined && { allowedInjectionSites }),
       // v1.7.0 — iOS reminder flags; Prisma defaults both to false.
       ...(liveActivityEnabled !== undefined && { liveActivityEnabled }),
       ...(criticalAlarmEnabled !== undefined && { criticalAlarmEnabled }),
diff --git a/src/app/medications/page.tsx b/src/app/medications/page.tsx
index 37858ce52..10d81def0 100644
--- a/src/app/medications/page.tsx
+++ b/src/app/medications/page.tsx
@@ -44,6 +44,10 @@ interface Medication {
   dosesPerUnit?: number | null;
   /** v1.6.0 — route of administration (ORAL | INJECTION | OTHER). */
   deliveryForm?: string;
+  /** v1.8.5 — per-medication injection-site tracking opt-in. */
+  trackInjectionSites?: boolean;
+  /** v1.8.5 — per-medication allowed / preferred injection sites. */
+  allowedInjectionSites?: string[];
   active: boolean;
   notificationsEnabled: boolean;
   pausedAt: string | null;
@@ -374,6 +378,8 @@ function medicationToPayload(med: Medication): MedicationPayload {
     treatmentClass: med.treatmentClass,
     deliveryForm: med.deliveryForm,
     dosesPerUnit: med.dosesPerUnit ?? null,
+    trackInjectionSites: med.trackInjectionSites ?? false,
+    allowedInjectionSites: med.allowedInjectionSites ?? [],
     notificationsEnabled: med.notificationsEnabled,
     startsOn: med.startsOn ? new Date(med.startsOn) : null,
     endsOn: med.endsOn ? new Date(med.endsOn) : null,
diff --git a/src/components/medications/glp1-medication-card.tsx b/src/components/medications/glp1-medication-card.tsx
index f9db3485a..c1a28bd07 100644
--- a/src/components/medications/glp1-medication-card.tsx
+++ b/src/components/medications/glp1-medication-card.tsx
@@ -27,6 +27,8 @@ import {
   nextInjectionSite,
   type InjectionSiteKey,
 } from "@/lib/medications/injection-sites";
+import { LogInjectionSiteDialog } from "@/components/medications/log-injection-site-dialog";
+import { useGlobalExcludedInjectionSites } from "@/lib/medications/use-injection-site-prefs";
 import {
   reduceCurrentWindowStatus,
   toBerlinDate,
@@ -79,6 +81,12 @@ export interface Glp1Medication {
   category: string;
   treatmentClass?: string;
   dosesPerUnit?: number | null;
+  /** v1.6.0 — route of administration (drives the injection-site prompt). */
+  deliveryForm?: string;
+  /** v1.8.5 — per-medication injection-site tracking opt-in. */
+  trackInjectionSites?: boolean;
+  /** v1.8.5 — per-medication allowed / preferred injection sites. */
+  allowedInjectionSites?: string[];
   active: boolean;
   notificationsEnabled: boolean;
   pausedAt: string | null;
@@ -191,6 +199,12 @@ export function Glp1MedicationCard({
   const fmt = useFormatters();
   const [intakeLoading, setIntakeLoading] = useState<string | null>(null);
   const [, forceUpdate] = useReducer((x: number) => x + 1, 0);
+  // v1.8.5 — post-dose injection-site prompt (see medication-card.tsx).
+  const [siteIntakeId, setSiteIntakeId] = useState<string | null>(null);
+  const globalExcluded = useGlobalExcludedInjectionSites();
+  const tracksInjection =
+    medication.deliveryForm === "INJECTION" &&
+    medication.trackInjectionSites === true;
 
   const { data: compliance } = useQuery({
     queryKey: queryKeys.medicationCompliance(medication.id),
@@ -259,12 +273,39 @@ export function Glp1MedicationCard({
           ),
         );
         await invalidateKeys(queryClient, medicationDependentKeys);
+        // v1.8.5 — prompt (skippably) for the injection site on a taken
+        // dose when tracking is enabled.
+        if (!skipped && tracksInjection) {
+          try {
+            const json = await res.json();
+            const eventId = json?.data?.id as string | undefined;
+            if (eventId) setSiteIntakeId(eventId);
+          } catch {
+            /* dose recorded; the site prompt is best-effort */
+          }
+        }
       }
     } finally {
       setIntakeLoading(null);
     }
   }
 
+  async function confirmInjectionSite(site: InjectionSiteKey) {
+    const intakeId = siteIntakeId;
+    setSiteIntakeId(null);
+    if (!intakeId) return;
+    const res = await fetch("/api/medications/intake", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ intakeId, status: "taken", injectionSite: site }),
+    });
+    if (res.ok) {
+      await invalidateKeys(queryClient, medicationDependentKeys);
+    } else {
+      toast.error(t("medications.logInjectionSiteNoneAvailable"));
+    }
+  }
+
   const schedule = medication.schedules[0] ?? null;
   const now = new Date();
   const next = nextInjectionFromServer(medication.nextDueAt, now);
@@ -469,6 +510,25 @@ export function Glp1MedicationCard({
           />
         )}
       </CardContent>
+
+      {/* v1.8.5 — post-dose injection-site capture (optional, skippable). */}
+      {tracksInjection && (
+        <LogInjectionSiteDialog
+          open={siteIntakeId !== null}
+          medicationName={medication.name}
+          allowedInjectionSites={
+            (medication.allowedInjectionSites ?? []) as InjectionSiteKey[]
+          }
+          globalExcludedInjectionSites={globalExcluded}
+          history={
+            recentInjections
+              .map((r) => r.injectionSite)
+              .filter(Boolean) as InjectionSiteKey[]
+          }
+          onConfirm={confirmInjectionSite}
+          onSkip={() => setSiteIntakeId(null)}
+        />
+      )}
     </Card>
   );
 }
diff --git a/src/components/medications/injection-site-picker.tsx b/src/components/medications/injection-site-picker.tsx
index f4246728a..7d166184f 100644
--- a/src/components/medications/injection-site-picker.tsx
+++ b/src/components/medications/injection-site-picker.tsx
@@ -32,6 +32,15 @@ interface InjectionSitePickerProps {
   /** Recent rotation history (most recent first). Powers the
    *  "recommended next site" dashed-ring annotation. */
   history?: ReadonlyArray<InjectionSiteKey>;
+  /**
+   * v1.8.5 — the effective allowed set (per-medication allowed sites
+   * minus the user's global exclusion). When supplied, sites outside it
+   * render disabled + non-interactive and the rotation recommendation is
+   * constrained to this set. `undefined` keeps the legacy all-sites
+   * picker (e.g. the wizard rotation preview, which has no medication
+   * context yet).
+   */
+  allowed?: ReadonlyArray<InjectionSiteKey>;
   /** Called when the user picks a site. */
   onChange: (site: InjectionSiteKey) => void;
   /** Optional class for the outer wrapper. */
@@ -41,11 +50,15 @@ interface InjectionSitePickerProps {
 export function InjectionSitePicker({
   value,
   history = [],
+  allowed,
   onChange,
   className,
 }: InjectionSitePickerProps) {
   const { t } = useTranslations();
-  const recommended = nextInjectionSite(history);
+  const recommended = nextInjectionSite(history, 4, allowed);
+  const allowedSet = allowed ? new Set(allowed) : null;
+  const isAllowed = (site: InjectionSiteKey) =>
+    allowedSet === null || allowedSet.has(site);
 
   return (
     <div
@@ -138,9 +151,13 @@ export function InjectionSitePicker({
           const coord = SITE_COORDS[site];
           const isActive = site === value;
           const isRecommended = site === recommended;
+          // v1.8.5 — a site outside the effective allowed set renders
+          // disabled (dimmed, non-interactive) so the user cannot pick a
+          // site the server would reject.
+          const disabled = !isAllowed(site);
           return (
             <g key={site}>
-              {isRecommended && !isActive && (
+              {isRecommended && !isActive && !disabled && (
                 <circle
                   cx={coord.x}
                   cy={coord.y}
@@ -156,9 +173,11 @@ export function InjectionSitePicker({
                 cy={coord.y}
                 r="6"
                 className={
-                  isActive
-                    ? "fill-primary stroke-primary-foreground"
-                    : "fill-muted stroke-foreground/60 hover:fill-accent"
+                  disabled
+                    ? "fill-muted/30 stroke-foreground/20"
+                    : isActive
+                      ? "fill-primary stroke-primary-foreground"
+                      : "fill-muted stroke-foreground/60 hover:fill-accent"
                 }
                 strokeWidth="1.5"
               />
@@ -175,17 +194,26 @@ export function InjectionSitePicker({
                 r="12"
                 fill="transparent"
                 role="button"
-                tabIndex={0}
+                tabIndex={disabled ? -1 : 0}
                 aria-pressed={isActive}
+                aria-disabled={disabled}
                 aria-label={t(describeInjectionSite(site))}
-                onClick={() => onChange(site)}
-                onKeyDown={(e) => {
-                  if (e.key === "Enter" || e.key === " ") {
-                    e.preventDefault();
-                    onChange(site);
-                  }
-                }}
-                className="cursor-pointer focus:outline-none focus-visible:stroke-current focus-visible:stroke-2"
+                onClick={disabled ? undefined : () => onChange(site)}
+                onKeyDown={
+                  disabled
+                    ? undefined
+                    : (e) => {
+                        if (e.key === "Enter" || e.key === " ") {
+                          e.preventDefault();
+                          onChange(site);
+                        }
+                      }
+                }
+                className={
+                  disabled
+                    ? "cursor-not-allowed focus:outline-none"
+                    : "cursor-pointer focus:outline-none focus-visible:stroke-current focus-visible:stroke-2"
+                }
               />
             </g>
           );
diff --git a/src/components/medications/log-injection-site-dialog.tsx b/src/components/medications/log-injection-site-dialog.tsx
new file mode 100644
index 000000000..748b78e3f
--- /dev/null
+++ b/src/components/medications/log-injection-site-dialog.tsx
@@ -0,0 +1,110 @@
+"use client";
+
+import { useState } from "react";
+
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Button } from "@/components/ui/button";
+import { InjectionSitePicker } from "@/components/medications/injection-site-picker";
+import {
+  effectiveAllowedSites,
+  type InjectionSiteKey,
+} from "@/lib/medications/injection-sites";
+import { useTranslations } from "@/lib/i18n/context";
+
+/**
+ * v1.8.5 — post-dose injection-site capture.
+ *
+ * Shown after a taken dose for a medication with
+ * `deliveryForm === "INJECTION"` and `trackInjectionSites === true`. The
+ * capture is OPTIONAL and always skippable — closing or "skip" records
+ * no site, the dose stays logged regardless. The picker is constrained
+ * to the medication's effective allowed set (per-medication allowed sites
+ * minus the user's global exclusion), and the rotation suggestion runs
+ * within that set.
+ */
+interface LogInjectionSiteDialogProps {
+  open: boolean;
+  medicationName: string;
+  /** Per-medication allowed / preferred sites ([] = no restriction). */
+  allowedInjectionSites: ReadonlyArray<InjectionSiteKey>;
+  /** User-level global exclusion deny-list. */
+  globalExcludedInjectionSites: ReadonlyArray<InjectionSiteKey>;
+  /** Recent rotation history (most recent first) for the dashed-ring hint. */
+  history: ReadonlyArray<InjectionSiteKey>;
+  /** Submit the chosen site (the parent PATCHes it onto the intake). */
+  onConfirm: (site: InjectionSiteKey) => void;
+  /** Dismiss without recording a site (the dose stays taken). */
+  onSkip: () => void;
+}
+
+export function LogInjectionSiteDialog({
+  open,
+  medicationName,
+  allowedInjectionSites,
+  globalExcludedInjectionSites,
+  history,
+  onConfirm,
+  onSkip,
+}: LogInjectionSiteDialogProps) {
+  const { t } = useTranslations();
+  const [selected, setSelected] = useState<InjectionSiteKey | null>(null);
+
+  const allowed = effectiveAllowedSites(
+    allowedInjectionSites,
+    globalExcludedInjectionSites,
+  );
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        if (!next) onSkip();
+      }}
+    >
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>{t("medications.logInjectionSiteTitle")}</DialogTitle>
+          <DialogDescription>
+            {t("medications.logInjectionSiteDescription", {
+              name: medicationName,
+            })}
+          </DialogDescription>
+        </DialogHeader>
+
+        {allowed.length === 0 ? (
+          <p className="text-muted-foreground py-4 text-center text-sm">
+            {t("medications.logInjectionSiteNoneAvailable")}
+          </p>
+        ) : (
+          <InjectionSitePicker
+            value={selected}
+            history={history}
+            allowed={allowed}
+            onChange={setSelected}
+          />
+        )}
+
+        <DialogFooter className="gap-2 sm:gap-2">
+          <Button variant="outline" onClick={onSkip}>
+            {t("medications.logInjectionSiteSkip")}
+          </Button>
+          <Button
+            disabled={selected === null}
+            onClick={() => {
+              if (selected !== null) onConfirm(selected);
+            }}
+          >
+            {t("medications.logInjectionSiteConfirm")}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/src/components/medications/medication-card.tsx b/src/components/medications/medication-card.tsx
index 7d619eb22..fbb9247e9 100644
--- a/src/components/medications/medication-card.tsx
+++ b/src/components/medications/medication-card.tsx
@@ -27,6 +27,9 @@ import {
   medicationDependentKeys,
   queryKeys,
 } from "@/lib/query-keys";
+import { LogInjectionSiteDialog } from "@/components/medications/log-injection-site-dialog";
+import { useGlobalExcludedInjectionSites } from "@/lib/medications/use-injection-site-prefs";
+import type { InjectionSiteKey } from "@/lib/medications/injection-sites";
 
 interface Schedule {
   id: string;
@@ -50,6 +53,12 @@ interface Medication {
    */
   treatmentClass?: string;
   dosesPerUnit?: number | null;
+  /** v1.6.0 — route of administration (drives the injection-site prompt). */
+  deliveryForm?: string;
+  /** v1.8.5 — per-medication injection-site tracking opt-in. */
+  trackInjectionSites?: boolean;
+  /** v1.8.5 — per-medication allowed / preferred injection sites. */
+  allowedInjectionSites?: string[];
   active: boolean;
   notificationsEnabled: boolean;
   pausedAt: string | null;
@@ -122,6 +131,14 @@ export function MedicationCard({
   const { t, locale } = useTranslations();
   const fmt = useFormatters();
   const [intakeLoading, setIntakeLoading] = useState<string | null>(null);
+  // v1.8.5 — post-dose injection-site prompt state. Holds the intake
+  // event id returned by the take POST so the confirm handler can PATCH
+  // the chosen site onto it. Null = dialog closed.
+  const [siteIntakeId, setSiteIntakeId] = useState<string | null>(null);
+  const globalExcluded = useGlobalExcludedInjectionSites();
+  const tracksInjection =
+    medication.deliveryForm === "INJECTION" &&
+    medication.trackInjectionSites === true;
 
   const { data: compliance } = useQuery({
     queryKey: queryKeys.medicationCompliance(medication.id),
@@ -171,12 +188,40 @@ export function MedicationCard({
           ),
         );
         await invalidateKeys(queryClient, medicationDependentKeys);
+        // v1.8.5 — after a TAKEN dose on a tracking-enabled injection,
+        // prompt (skippably) for the site. The dialog PATCHes it onto
+        // the just-created event via the status-toggle route.
+        if (!skipped && tracksInjection) {
+          try {
+            const json = await res.json();
+            const eventId = json?.data?.id as string | undefined;
+            if (eventId) setSiteIntakeId(eventId);
+          } catch {
+            /* dose recorded; the site prompt is best-effort */
+          }
+        }
       }
     } finally {
       setIntakeLoading(null);
     }
   }
 
+  async function confirmInjectionSite(site: InjectionSiteKey) {
+    const intakeId = siteIntakeId;
+    setSiteIntakeId(null);
+    if (!intakeId) return;
+    const res = await fetch("/api/medications/intake", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ intakeId, status: "taken", injectionSite: site }),
+    });
+    if (res.ok) {
+      await invalidateKeys(queryClient, medicationDependentKeys);
+    } else {
+      toast.error(t("medications.logInjectionSiteNoneAvailable"));
+    }
+  }
+
   const rate7 = compliance?.compliance7?.rate ?? 0;
   const rate30 = compliance?.compliance30?.rate ?? 0;
   const streak = compliance?.compliance7?.streak ?? 0;
@@ -373,6 +418,21 @@ export function MedicationCard({
           />
         )}
       </CardContent>
+
+      {/* v1.8.5 — post-dose injection-site capture (optional, skippable). */}
+      {tracksInjection && (
+        <LogInjectionSiteDialog
+          open={siteIntakeId !== null}
+          medicationName={medication.name}
+          allowedInjectionSites={
+            (medication.allowedInjectionSites ?? []) as InjectionSiteKey[]
+          }
+          globalExcludedInjectionSites={globalExcluded}
+          history={[]}
+          onConfirm={confirmInjectionSite}
+          onSkip={() => setSiteIntakeId(null)}
+        />
+      )}
     </Card>
   );
 }
diff --git a/src/components/medications/wizard/steps/Step3Dose.tsx b/src/components/medications/wizard/steps/Step3Dose.tsx
index 170a7fa58..f1eb35493 100644
--- a/src/components/medications/wizard/steps/Step3Dose.tsx
+++ b/src/components/medications/wizard/steps/Step3Dose.tsx
@@ -13,8 +13,13 @@ import {
   SelectValue,
 } from "@/components/ui/select";
 import { Button } from "@/components/ui/button";
-import { InjectionSitePicker } from "@/components/medications/injection-site-picker";
-import type { InjectionSiteKey } from "@/lib/medications/injection-sites";
+import { Switch } from "@/components/ui/switch";
+import { Checkbox } from "@/components/ui/checkbox";
+import {
+  INJECTION_SITE_KEYS,
+  describeInjectionSite,
+  type InjectionSiteKey,
+} from "@/lib/medications/injection-sites";
 import type { MedicationDeliveryForm } from "@/lib/validations/medication";
 import { useTranslations } from "@/lib/i18n/context";
 
@@ -48,14 +53,24 @@ const DELIVERY_FORM_KEYS: readonly MedicationDeliveryForm[] = [
 
 export function Step3Dose({ payload, applyPartial }: StepProps) {
   const { t } = useTranslations();
-  // The injection-site rotation map is a visual aide on the editor: the
-  // chosen site is persisted per intake-event (no medication-level
-  // column), so the picker selection here is a local preview the user
-  // collapses when not needed.
-  const [siteOpen, setSiteOpen] = useState(false);
-  const [previewSite, setPreviewSite] = useState<InjectionSiteKey | null>(null);
+  // v1.8.5 — injection-site tracking is a per-medication opt-in surfaced
+  // only for an INJECTION delivery form. When enabled, the user can
+  // restrict the allowed sites; an empty selection means "no
+  // restriction" (every site offered, minus the global exclusion).
+  const [allowedOpen, setAllowedOpen] = useState(false);
   const isInjection = payload.deliveryForm === "INJECTION";
 
+  function toggleAllowedSite(site: InjectionSiteKey, checked: boolean) {
+    const current = new Set(payload.allowedInjectionSites);
+    if (checked) current.add(site);
+    else current.delete(site);
+    applyPartial({
+      allowedInjectionSites: INJECTION_SITE_KEYS.filter((s) =>
+        current.has(s),
+      ),
+    });
+  }
+
   return (
     <div className="space-y-6" data-slot="wizard-step3">
       <div className="grid grid-cols-2 gap-3">
@@ -151,40 +166,83 @@ export function Step3Dose({ payload, applyPartial }: StepProps) {
         </div>
       </div>
 
-      {/* v1.6.0 — collapsible injection-site rotation map. Shown only for
-          INJECTION delivery; the per-dose site is logged at intake time
-          so this surface is an optional rotation aide, not a persisted
-          medication field. */}
+      {/* v1.8.5 — injection-site tracking opt-in + allowed-sites editor.
+          Shown only for an INJECTION delivery form. Default off; enabling
+          it surfaces the post-dose site prompt and the rotation
+          suggestion. The allowed-sites checklist restricts the picker
+          (empty = no restriction). */}
       {isInjection && (
         <div
-          className="border-border/60 rounded-lg border"
+          className="border-border/60 space-y-3 rounded-lg border p-3"
           data-slot="wizard-injection-site"
         >
-          <Button
-            type="button"
-            variant="ghost"
-            className="h-11 w-full justify-between px-3"
-            aria-expanded={siteOpen}
-            onClick={() => setSiteOpen((prev) => !prev)}
-          >
-            <span className="text-sm font-medium">
-              {t("medications.wizard.steps.step3.injectionSiteToggle")}
+          <label className="flex items-start justify-between gap-3">
+            <span className="space-y-0.5">
+              <span className="block text-sm font-medium">
+                {t("medications.trackInjectionSitesToggle")}
+              </span>
+              <span className="text-muted-foreground block text-xs">
+                {t("medications.trackInjectionSitesHint")}
+              </span>
             </span>
-            {siteOpen ? (
-              <ChevronUp aria-hidden="true" className="h-4 w-4" />
-            ) : (
-              <ChevronDown aria-hidden="true" className="h-4 w-4" />
-            )}
-          </Button>
-          {siteOpen && (
-            <div className="space-y-2 px-3 pb-4">
-              <p className="text-muted-foreground text-xs">
-                {t("medications.wizard.steps.step3.injectionSiteHint")}
-              </p>
-              <InjectionSitePicker
-                value={previewSite}
-                onChange={setPreviewSite}
-              />
+            <Switch
+              checked={payload.trackInjectionSites}
+              onCheckedChange={(checked) =>
+                applyPartial({
+                  trackInjectionSites: checked,
+                  // Clear the per-med restriction when tracking is turned off.
+                  ...(checked ? {} : { allowedInjectionSites: [] }),
+                })
+              }
+              aria-label={t("medications.trackInjectionSitesToggle")}
+            />
+          </label>
+
+          {payload.trackInjectionSites && (
+            <div className="space-y-2">
+              <Button
+                type="button"
+                variant="ghost"
+                className="h-9 w-full justify-between px-2"
+                aria-expanded={allowedOpen}
+                onClick={() => setAllowedOpen((prev) => !prev)}
+              >
+                <span className="text-sm font-medium">
+                  {t("medications.allowedSitesLabel")}
+                </span>
+                {allowedOpen ? (
+                  <ChevronUp aria-hidden="true" className="h-4 w-4" />
+                ) : (
+                  <ChevronDown aria-hidden="true" className="h-4 w-4" />
+                )}
+              </Button>
+              {allowedOpen && (
+                <div className="space-y-2 px-1">
+                  <p className="text-muted-foreground text-xs">
+                    {t("medications.allowedSitesHint")}
+                  </p>
+                  <div className="grid grid-cols-2 gap-2">
+                    {INJECTION_SITE_KEYS.map((site) => {
+                      const checked =
+                        payload.allowedInjectionSites.includes(site);
+                      return (
+                        <label
+                          key={site}
+                          className="flex items-center gap-2 text-sm"
+                        >
+                          <Checkbox
+                            checked={checked}
+                            onCheckedChange={(c) =>
+                              toggleAllowedSite(site, c === true)
+                            }
+                          />
+                          {t(describeInjectionSite(site))}
+                        </label>
+                      );
+                    })}
+                  </div>
+                </div>
+              )}
             </div>
           )}
         </div>
diff --git a/src/components/medications/wizard/wizard-payload.ts b/src/components/medications/wizard/wizard-payload.ts
index 4ba7b9b73..984a05707 100644
--- a/src/components/medications/wizard/wizard-payload.ts
+++ b/src/components/medications/wizard/wizard-payload.ts
@@ -63,6 +63,7 @@ import {
   type MedicationCategoryValue,
   type MedicationDeliveryForm,
 } from "@/lib/validations/medication";
+import type { InjectionSiteKey } from "@/lib/medications/injection-sites";
 
 // ────────────────────────────────────────────────────────────────────
 // Step 2 — treatment-class taxonomy
@@ -207,6 +208,18 @@ export interface WizardPayload {
    * inventory tracking off (maps to `undefined` / NULL on the wire).
    */
   dosesPerUnit: string;
+  /**
+   * v1.8.5 — per-medication injection-site tracking opt-in. Only
+   * surfaced in Step 3 when `deliveryForm === "INJECTION"`. Default
+   * false (opt-in). Toggling it off clears `allowedInjectionSites`.
+   */
+  trackInjectionSites: boolean;
+  /**
+   * v1.8.5 — per-medication allowed / preferred injection sites. Empty =
+   * no restriction (every site offered). Only meaningful when
+   * `trackInjectionSites` is true.
+   */
+  allowedInjectionSites: InjectionSiteKey[];
   /** Set in Step 5 — mirrors `schedules[activeScheduleIndex].mode`. */
   mode: "oneShot" | "recurring" | null;
   /** Mirrors `schedules[activeScheduleIndex].cadence`. */
@@ -253,6 +266,8 @@ export function emptyWizardPayload(): WizardPayload {
     treatmentRow: null,
     deliveryForm: "ORAL",
     dosesPerUnit: "",
+    trackInjectionSites: false,
+    allowedInjectionSites: [],
     mode: draft.mode,
     cadence: draft.cadence,
     subControls: draft.subControls,
@@ -463,6 +478,10 @@ export interface CreateMedicationBody {
   deliveryForm: MedicationDeliveryForm;
   /** v1.6.0 — doses per pen / vial. Omitted when inventory is off. */
   dosesPerUnit?: number;
+  /** v1.8.5 — injection-site tracking opt-in. Omitted for non-injections. */
+  trackInjectionSites?: boolean;
+  /** v1.8.5 — per-medication allowed sites. Omitted when tracking is off. */
+  allowedInjectionSites?: InjectionSiteKey[];
   /**
    * v1.5.5 D-3 §10 invariant 16 — the wizard owns the create-time
    * default for `notificationsEnabled` but never overwrites it on
@@ -602,6 +621,16 @@ export function buildCreateBody(
       parsedDosesPerUnit >= 1 && {
         dosesPerUnit: parsedDosesPerUnit,
       }),
+    // v1.8.5 — injection-site tracking is only meaningful for an
+    // INJECTION delivery form. Always send the boolean for an injection
+    // (so edits can deactivate it); send the allowed list only when
+    // tracking is on. Non-injections omit both (server keeps defaults).
+    ...(committed.deliveryForm === "INJECTION" && {
+      trackInjectionSites: committed.trackInjectionSites,
+      ...(committed.trackInjectionSites && {
+        allowedInjectionSites: committed.allowedInjectionSites,
+      }),
+    }),
     // v1.5.5 D-3 §10 invariant 16 — `notificationsEnabled` only on
     // create. Edits never round-trip the wizard's default because the
     // detail page's notifications switch is the single source of
@@ -807,6 +836,10 @@ export interface MedicationPayload {
   deliveryForm?: string;
   /** v1.6.0 — doses per pen / vial. NULL = inventory tracking off. */
   dosesPerUnit?: number | null;
+  /** v1.8.5 — injection-site tracking opt-in. */
+  trackInjectionSites?: boolean;
+  /** v1.8.5 — per-medication allowed / preferred injection sites. */
+  allowedInjectionSites?: string[];
   notificationsEnabled: boolean;
   startsOn: Date | null;
   endsOn: Date | null;
@@ -906,6 +939,9 @@ export function hydrateWizardPayload(initial: MedicationPayload): WizardPayload
       typeof initial.dosesPerUnit === "number" && initial.dosesPerUnit >= 1
         ? String(initial.dosesPerUnit)
         : "",
+    trackInjectionSites: initial.trackInjectionSites ?? false,
+    allowedInjectionSites: (initial.allowedInjectionSites ??
+      []) as InjectionSiteKey[],
     mode: first.mode,
     cadence: first.cadence,
     subControls: first.subControls,
diff --git a/src/components/settings/dashboard-section.tsx b/src/components/settings/dashboard-section.tsx
index 588c6434c..55ee5ff02 100644
--- a/src/components/settings/dashboard-section.tsx
+++ b/src/components/settings/dashboard-section.tsx
@@ -2,6 +2,7 @@
 
 import { DashboardLayoutSection } from "@/components/settings/dashboard-layout-section";
 import { UnitPreferenceCard } from "@/components/settings/unit-preference-card";
+import { InjectionSitesCard } from "@/components/settings/injection-sites-card";
 import { useAuth } from "@/hooks/use-auth";
 import { useTranslations } from "@/lib/i18n/context";
 
@@ -28,6 +29,8 @@ export function DashboardSection() {
 
       <UnitPreferenceCard isAuthenticated={isAuthenticated} />
 
+      <InjectionSitesCard isAuthenticated={isAuthenticated} />
+
       <DashboardLayoutSection id="dashboard-layout" />
     </section>
   );
diff --git a/src/components/settings/injection-sites-card.tsx b/src/components/settings/injection-sites-card.tsx
new file mode 100644
index 000000000..63ae404fd
--- /dev/null
+++ b/src/components/settings/injection-sites-card.tsx
@@ -0,0 +1,91 @@
+"use client";
+
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { Syringe } from "lucide-react";
+
+import { SettingsCardHeader } from "@/components/settings/_card-header";
+import { Checkbox } from "@/components/ui/checkbox";
+import { useTranslations } from "@/lib/i18n/context";
+import { queryKeys } from "@/lib/query-keys";
+import {
+  INJECTION_SITE_KEYS,
+  describeInjectionSite,
+  type InjectionSiteKey,
+} from "@/lib/medications/injection-sites";
+
+/**
+ * v1.8.5 — Settings → global injection-site exclusion.
+ *
+ * A per-user deny-list. Sites checked here are never offered for any
+ * medication's injection-site picker and are rejected (422) at intake —
+ * even when a medication lists them as preferred (deny always wins).
+ * Reads + PATCHes `GET/PATCH /api/auth/me/injection-site-prefs`; the
+ * mutation invalidates `injectionSitePrefs()` so every picker re-reads.
+ */
+export function InjectionSitesCard({
+  isAuthenticated,
+}: {
+  isAuthenticated: boolean;
+}) {
+  const { t } = useTranslations();
+  const queryClient = useQueryClient();
+
+  const { data } = useQuery({
+    queryKey: queryKeys.injectionSitePrefs(),
+    queryFn: async () => {
+      const res = await fetch("/api/auth/me/injection-site-prefs");
+      if (!res.ok) return [] as InjectionSiteKey[];
+      const json = await res.json();
+      return (json.data?.globalExcludedInjectionSites ??
+        []) as InjectionSiteKey[];
+    },
+    enabled: isAuthenticated,
+    staleTime: 5 * 60 * 1000,
+  });
+  const excluded: InjectionSiteKey[] = data ?? [];
+
+  const mutation = useMutation({
+    mutationFn: async (next: InjectionSiteKey[]) => {
+      const res = await fetch("/api/auth/me/injection-site-prefs", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ globalExcludedInjectionSites: next }),
+      });
+      if (!res.ok) throw new Error("patch_failed");
+    },
+    onSuccess: () => {
+      void queryClient.invalidateQueries({
+        queryKey: queryKeys.injectionSitePrefs(),
+      });
+    },
+  });
+
+  function toggle(site: InjectionSiteKey, checked: boolean) {
+    const set = new Set(excluded);
+    if (checked) set.add(site);
+    else set.delete(site);
+    mutation.mutate(INJECTION_SITE_KEYS.filter((s) => set.has(s)));
+  }
+
+  return (
+    <div className="rounded-lg border p-4">
+      <SettingsCardHeader
+        icon={Syringe}
+        title={t("settings.globalExcludedInjectionSitesLabel")}
+        description={t("settings.globalExcludedInjectionSitesHint")}
+      />
+      <div className="mt-3 grid grid-cols-2 gap-2">
+        {INJECTION_SITE_KEYS.map((site) => (
+          <label key={site} className="flex items-center gap-2 text-sm">
+            <Checkbox
+              checked={excluded.includes(site)}
+              disabled={mutation.isPending}
+              onCheckedChange={(c) => toggle(site, c === true)}
+            />
+            {t(describeInjectionSite(site))}
+          </label>
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/src/lib/medications/__tests__/injection-site-write.test.ts b/src/lib/medications/__tests__/injection-site-write.test.ts
new file mode 100644
index 000000000..64bac801b
--- /dev/null
+++ b/src/lib/medications/__tests__/injection-site-write.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+
+import { resolveInjectionSiteForWrite } from "@/lib/medications/injection-site-write";
+
+const base = {
+  taken: true,
+  deliveryForm: "INJECTION",
+  trackInjectionSites: true,
+  allowedInjectionSites: [] as const,
+  globalExcludedInjectionSites: [] as const,
+};
+
+describe("resolveInjectionSiteForWrite()", () => {
+  it("persists a valid site on a taken injection with tracking on", () => {
+    const r = resolveInjectionSiteForWrite({ ...base, submitted: "THIGH_LEFT" });
+    expect(r).toEqual({ kind: "ok", site: "THIGH_LEFT" });
+  });
+
+  it("drops the site when the medication is not an INJECTION", () => {
+    const r = resolveInjectionSiteForWrite({
+      ...base,
+      deliveryForm: "ORAL",
+      submitted: "THIGH_LEFT",
+    });
+    expect(r).toEqual({ kind: "ok", site: null });
+  });
+
+  it("drops the site when tracking is disabled (default-off)", () => {
+    const r = resolveInjectionSiteForWrite({
+      ...base,
+      trackInjectionSites: false,
+      submitted: "THIGH_LEFT",
+    });
+    expect(r).toEqual({ kind: "ok", site: null });
+  });
+
+  it("drops the site on a skipped write (optional, never blocking)", () => {
+    const r = resolveInjectionSiteForWrite({
+      ...base,
+      taken: false,
+      submitted: "THIGH_LEFT",
+    });
+    expect(r).toEqual({ kind: "ok", site: null });
+  });
+
+  it("treats an omitted site as no-site (optional capture)", () => {
+    const r = resolveInjectionSiteForWrite({ ...base, submitted: undefined });
+    expect(r).toEqual({ kind: "ok", site: null });
+  });
+
+  it("rejects a site outside the per-medication allowed set (422)", () => {
+    const r = resolveInjectionSiteForWrite({
+      ...base,
+      allowedInjectionSites: ["THIGH_RIGHT"],
+      submitted: "ABDOMEN_LEFT",
+    });
+    expect(r).toEqual({ kind: "disallowed", site: "ABDOMEN_LEFT" });
+  });
+
+  it("rejects a globally excluded site even when per-med-preferred (deny wins)", () => {
+    const r = resolveInjectionSiteForWrite({
+      ...base,
+      allowedInjectionSites: ["ABDOMEN_LEFT"],
+      globalExcludedInjectionSites: ["ABDOMEN_LEFT"],
+      submitted: "ABDOMEN_LEFT",
+    });
+    expect(r).toEqual({ kind: "disallowed", site: "ABDOMEN_LEFT" });
+  });
+
+  it("accepts a per-med-allowed site that is not globally excluded", () => {
+    const r = resolveInjectionSiteForWrite({
+      ...base,
+      allowedInjectionSites: ["ABDOMEN_LEFT", "THIGH_RIGHT"],
+      globalExcludedInjectionSites: ["ABDOMEN_LEFT"],
+      submitted: "THIGH_RIGHT",
+    });
+    expect(r).toEqual({ kind: "ok", site: "THIGH_RIGHT" });
+  });
+});
diff --git a/src/lib/medications/__tests__/injection-sites.test.ts b/src/lib/medications/__tests__/injection-sites.test.ts
index 28a1ddd4f..252cfdcd3 100644
--- a/src/lib/medications/__tests__/injection-sites.test.ts
+++ b/src/lib/medications/__tests__/injection-sites.test.ts
@@ -4,6 +4,8 @@ import {
   INJECTION_SITE_KEYS,
   SITE_COORDS,
   describeInjectionSite,
+  effectiveAllowedSites,
+  isSiteAllowed,
   nextInjectionSite,
 } from "@/lib/medications/injection-sites";
 
@@ -51,6 +53,95 @@ describe("injection-sites", () => {
     });
   });
 
+  describe("effectiveAllowedSites() — deny-wins combination", () => {
+    it("returns every site when no per-med list and no exclusion", () => {
+      expect(effectiveAllowedSites([], [])).toEqual([...INJECTION_SITE_KEYS]);
+    });
+
+    it("restricts to the per-med list in canonical order", () => {
+      expect(
+        effectiveAllowedSites(["THIGH_RIGHT", "ABDOMEN_LEFT"], []),
+      ).toEqual(["ABDOMEN_LEFT", "THIGH_RIGHT"]);
+    });
+
+    it("drops globally excluded sites even with an empty per-med list", () => {
+      const result = effectiveAllowedSites([], ["ABDOMEN_LEFT", "THIGH_LEFT"]);
+      expect(result).not.toContain("ABDOMEN_LEFT");
+      expect(result).not.toContain("THIGH_LEFT");
+      expect(result).toContain("ABDOMEN_RIGHT");
+    });
+
+    it("global exclusion WINS over a per-med preferred site", () => {
+      // The user lists ABDOMEN_LEFT as preferred for this med, but has
+      // globally excluded it (e.g. lipohypertrophy). Deny wins.
+      const result = effectiveAllowedSites(
+        ["ABDOMEN_LEFT", "THIGH_RIGHT"],
+        ["ABDOMEN_LEFT"],
+      );
+      expect(result).toEqual(["THIGH_RIGHT"]);
+    });
+
+    it("returns an empty set when the exclusion covers everything", () => {
+      expect(
+        effectiveAllowedSites([], [...INJECTION_SITE_KEYS]),
+      ).toEqual([]);
+    });
+  });
+
+  describe("isSiteAllowed()", () => {
+    it("accepts a site in the effective allowed set", () => {
+      expect(isSiteAllowed("THIGH_RIGHT", ["THIGH_RIGHT"], [])).toBe(true);
+    });
+
+    it("rejects a site outside the per-med allowed set", () => {
+      expect(isSiteAllowed("ABDOMEN_LEFT", ["THIGH_RIGHT"], [])).toBe(false);
+    });
+
+    it("rejects a globally excluded site even when per-med-allowed", () => {
+      expect(
+        isSiteAllowed("ABDOMEN_LEFT", ["ABDOMEN_LEFT"], ["ABDOMEN_LEFT"]),
+      ).toBe(false);
+    });
+  });
+
+  describe("nextInjectionSite() — allowed-set rotation", () => {
+    it("never recommends a site outside the allowed set", () => {
+      const allowed = ["THIGH_LEFT", "THIGH_RIGHT"] as const;
+      const rec = nextInjectionSite(["THIGH_LEFT"], 4, allowed);
+      expect(rec).toBe("THIGH_RIGHT");
+    });
+
+    it("undefined allowed argument keeps legacy all-sites behaviour", () => {
+      // No third argument → rotation over all eight sites, so it picks
+      // a far site rather than the most-recent ABDOMEN_LEFT.
+      expect(nextInjectionSite(["ABDOMEN_LEFT"])).not.toBe("ABDOMEN_LEFT");
+    });
+
+    it("returns null when the effective set is empty (everything excluded)", () => {
+      const everythingExcluded = effectiveAllowedSites(
+        [],
+        [...INJECTION_SITE_KEYS],
+      );
+      expect(everythingExcluded).toEqual([]);
+      expect(
+        nextInjectionSite(["ABDOMEN_LEFT"], 4, everythingExcluded),
+      ).toBeNull();
+    });
+
+    it("picks the least-recently-used site within the allowed set", () => {
+      // Allowed = three thigh/abdomen sites; history used two of them
+      // recently, so the LRU/untouched one wins.
+      const allowed = ["ABDOMEN_LEFT", "ABDOMEN_RIGHT", "THIGH_LEFT"] as const;
+      const rec = nextInjectionSite(["ABDOMEN_LEFT", "ABDOMEN_RIGHT"], 4, allowed);
+      expect(rec).toBe("THIGH_LEFT");
+    });
+
+    it("falls back to first allowed candidate for empty history", () => {
+      const rec = nextInjectionSite([], 4, ["THIGH_LEFT", "THIGH_RIGHT"]);
+      expect(rec).toBe("THIGH_LEFT");
+    });
+  });
+
   describe("describeInjectionSite()", () => {
     it("returns the right i18n key per site", () => {
       expect(describeInjectionSite("ABDOMEN_LEFT")).toBe(
diff --git a/src/lib/medications/injection-site-write.ts b/src/lib/medications/injection-site-write.ts
new file mode 100644
index 000000000..b68362b36
--- /dev/null
+++ b/src/lib/medications/injection-site-write.ts
@@ -0,0 +1,79 @@
+/**
+ * v1.8.5 — server-side guard for the injection-site write path.
+ *
+ * The intake routes (`POST /api/medications/[id]/intake`,
+ * `POST /api/medications/intake`, `POST /api/medications/intake/bulk`)
+ * accept an optional `injectionSite` and must only ever persist it when:
+ *
+ *   1. the medication is an INJECTION (`deliveryForm === "INJECTION"`),
+ *   2. site-tracking is enabled on the medication
+ *      (`trackInjectionSites === true`),
+ *   3. the dose is being recorded as TAKEN (never on a skip),
+ *   4. the submitted site is a member of the medication's EFFECTIVE
+ *      allowed set — the per-medication `allowedInjectionSites` minus the
+ *      user's `globalExcludedInjectionSites` deny-list (deny wins).
+ *
+ * A submitted site that fails (1)–(3) is silently dropped (the dose still
+ * records, the column stays NULL). A site that fails (4) — a disallowed
+ * value — is a hard validation error the route surfaces as 422, because
+ * the client should never offer a site outside the effective set; a
+ * request that does is either stale UI or a hand-rolled call.
+ */
+import {
+  effectiveAllowedSites,
+  type InjectionSiteKey,
+} from "@/lib/medications/injection-sites";
+
+export interface ResolveInjectionSiteInput {
+  /** The submitted site, or null/undefined when the client omitted it. */
+  submitted: InjectionSiteKey | null | undefined;
+  /** True only for a taken (non-skipped) write. */
+  taken: boolean;
+  /** The medication's delivery form. */
+  deliveryForm: string;
+  /** The medication's per-medication tracking opt-in. */
+  trackInjectionSites: boolean;
+  /** The medication's per-medication allowed / preferred sites. */
+  allowedInjectionSites: ReadonlyArray<InjectionSiteKey>;
+  /** The user's global exclusion deny-list. */
+  globalExcludedInjectionSites: ReadonlyArray<InjectionSiteKey>;
+}
+
+export type ResolveInjectionSiteResult =
+  | { kind: "ok"; site: InjectionSiteKey | null }
+  | { kind: "disallowed"; site: InjectionSiteKey };
+
+/**
+ * Resolve the site to persist for an intake write, or report that the
+ * submitted site is disallowed.
+ *
+ *   - `{ kind: "ok", site: null }`  → persist NULL (no site recorded);
+ *     covers an omitted site, a skip, a non-injection / tracking-off med.
+ *   - `{ kind: "ok", site }`        → persist the validated site.
+ *   - `{ kind: "disallowed", site }`→ the route returns 422.
+ */
+export function resolveInjectionSiteForWrite(
+  input: ResolveInjectionSiteInput,
+): ResolveInjectionSiteResult {
+  const { submitted, taken, deliveryForm, trackInjectionSites } = input;
+
+  // No site submitted, or the write is not a taken-injection on a
+  // tracking-enabled medication → never persist a site.
+  if (
+    submitted == null ||
+    !taken ||
+    deliveryForm !== "INJECTION" ||
+    !trackInjectionSites
+  ) {
+    return { kind: "ok", site: null };
+  }
+
+  const allowed = effectiveAllowedSites(
+    input.allowedInjectionSites,
+    input.globalExcludedInjectionSites,
+  );
+  if (!allowed.includes(submitted)) {
+    return { kind: "disallowed", site: submitted };
+  }
+  return { kind: "ok", site: submitted };
+}
diff --git a/src/lib/medications/injection-sites.ts b/src/lib/medications/injection-sites.ts
index 29c937fb4..29af71019 100644
--- a/src/lib/medications/injection-sites.ts
+++ b/src/lib/medications/injection-sites.ts
@@ -42,23 +42,83 @@ export const SITE_COORDS: Record<InjectionSiteKey, { x: number; y: number }> = {
   UPPER_ARM_RIGHT: { x: 102, y: 82 },
 };
 
+/**
+ * v1.8.5 — resolve the effective allowed set for a medication given the
+ * per-medication preference and the user-level global exclusion. The
+ * global exclusion is a deny-list and ALWAYS wins: a site the user has
+ * globally excluded is never offered, even if a per-medication entry
+ * lists it as preferred. An empty per-medication list means "no
+ * restriction" — every site is allowed (minus the global exclusion).
+ *
+ * Returns the sites in canonical `INJECTION_SITE_KEYS` order so callers
+ * render a stable picker. The result can be empty only when the global
+ * exclusion covers every remaining site — callers treat an empty set as
+ * "no recommendation, picker shows nothing selectable".
+ */
+export function effectiveAllowedSites(
+  allowed: ReadonlyArray<InjectionSiteKey>,
+  globalExcluded: ReadonlyArray<InjectionSiteKey>,
+): InjectionSiteKey[] {
+  const excludedSet = new Set(globalExcluded);
+  // Empty per-med list = no per-med restriction → start from all sites.
+  const base: ReadonlyArray<InjectionSiteKey> =
+    allowed.length === 0 ? INJECTION_SITE_KEYS : allowed;
+  const allowedSet = new Set(base);
+  // Canonical order, per-med restriction applied, global exclusion wins.
+  return INJECTION_SITE_KEYS.filter(
+    (site) => allowedSet.has(site) && !excludedSet.has(site),
+  );
+}
+
+/**
+ * v1.8.5 — server-side guard: is `site` a member of the effective
+ * allowed set for this medication? Used by the intake write path to
+ * reject (422) a site the user can no longer pick.
+ */
+export function isSiteAllowed(
+  site: InjectionSiteKey,
+  allowed: ReadonlyArray<InjectionSiteKey>,
+  globalExcluded: ReadonlyArray<InjectionSiteKey>,
+): boolean {
+  return effectiveAllowedSites(allowed, globalExcluded).includes(site);
+}
+
 /**
  * Recommend the next injection site given the recent rotation
  * history. Strategy: maximise the average Euclidean distance from the
  * candidate to each of the last N sites (N defaults to 4), tie-break
  * by least-recently-used (an unseen site beats a stale one).
  *
- * Returns `null` only when the input history is empty (no
- * recommendation to make — the picker shows all sites as available).
+ * v1.8.5 — an optional `allowed` set constrains the candidate pool to
+ * the effective allowed sites (per-med list minus the global
+ * exclusion). Pass the result of {@link effectiveAllowedSites}.
+ *   - `undefined` (no argument) → legacy "all eight sites" behaviour.
+ *   - a non-empty array → the recommender never suggests a site outside it.
+ *   - an explicitly-EMPTY array → no candidate (every site excluded);
+ *     the function returns `null`.
+ *
+ * Returns `null` when there is no candidate to recommend — an empty
+ * effective set, or when the only allowed site is the most-recent pick.
  */
 export function nextInjectionSite(
   history: ReadonlyArray<InjectionSiteKey>,
   windowSize = 4,
+  allowed?: ReadonlyArray<InjectionSiteKey>,
 ): InjectionSiteKey | null {
+  // v1.8.5 — restrict the candidate pool when an allowed set is given.
+  // `undefined` keeps the legacy all-sites behaviour; an explicitly
+  // empty array means "nothing allowed" and yields no recommendation.
+  const candidates: ReadonlyArray<InjectionSiteKey> =
+    allowed === undefined
+      ? INJECTION_SITE_KEYS
+      : INJECTION_SITE_KEYS.filter((s) => allowed.includes(s));
+  if (candidates.length === 0) return null;
+
   if (history.length === 0) {
-    // First-time user — recommend a sensible default (abdomen left)
-    // rather than null. The card needs SOMETHING to point to.
-    return "ABDOMEN_LEFT";
+    // First-time user — recommend a sensible default. Within an allowed
+    // set the first candidate in canonical order stands in for the
+    // legacy "abdomen left" pick.
+    return candidates.includes("ABDOMEN_LEFT") ? "ABDOMEN_LEFT" : candidates[0];
   }
 
   const recent = history.slice(0, windowSize);
@@ -72,10 +132,10 @@ export function nextInjectionSite(
     }
   }
 
-  let bestSite: InjectionSiteKey = INJECTION_SITE_KEYS[0];
+  let bestSite: InjectionSiteKey | null = null;
   let bestScore = -Infinity;
 
-  for (const candidate of INJECTION_SITE_KEYS) {
+  for (const candidate of candidates) {
     if (candidate === recent[0]) continue; // never recommend the most-recent site
     const candidateCoord = SITE_COORDS[candidate];
     let dist = 0;
@@ -95,6 +155,7 @@ export function nextInjectionSite(
     }
   }
 
+  // Only candidate was the most-recent site — nothing else to rotate to.
   return bestSite;
 }
 
diff --git a/src/lib/medications/scheduling/slot-upsert.ts b/src/lib/medications/scheduling/slot-upsert.ts
index d01696dcb..09d21612b 100644
--- a/src/lib/medications/scheduling/slot-upsert.ts
+++ b/src/lib/medications/scheduling/slot-upsert.ts
@@ -19,6 +19,7 @@ import type { PrismaClient } from "@/generated/prisma/client";
 import { prisma as defaultPrisma } from "@/lib/db";
 import { resolveCanonicalSlotInstant } from "@/lib/medications/scheduling/resolve-slot-instant";
 import type { WorkerScheduleRow } from "@/lib/medications/scheduling/worker-helpers";
+import type { InjectionSiteKey } from "@/lib/medications/injection-sites";
 
 type PrismaLike = Pick<PrismaClient, "medication" | "medicationIntakeEvent">;
 
@@ -58,6 +59,14 @@ export interface ApplyCanonicalSlotWriteInput {
   idempotencyKey: string | null;
   /** Source to stamp on a freshly-created slot row. */
   createSource: "WEB" | "API";
+  /**
+   * v1.8.5 — resolved + server-validated injection site to persist on a
+   * taken write. `null` = no site (the column stays / is set NULL). Only
+   * ever non-null on an explicit taken write for a tracking-enabled
+   * INJECTION medication; the route resolves + validates it before the
+   * upsert, so this is trusted here.
+   */
+  injectionSite?: InjectionSiteKey | null;
 }
 
 export interface ApplyCanonicalSlotWriteResult {
@@ -158,6 +167,7 @@ export async function applyCanonicalSlotWrite(
     skipped,
     idempotencyKey,
     createSource,
+    injectionSite = null,
   } = input;
 
   const rows = await findSlotRows(client, userId, medicationId, canonicalSlot);
@@ -183,6 +193,9 @@ export async function applyCanonicalSlotWrite(
         skipped,
         source: createSource,
         idempotencyKey,
+        // v1.8.5 — site only when the route resolved one (taken
+        // injection, tracking on, validated allowed).
+        ...(injectionSite !== null && { injectionSite }),
       },
       select: SLOT_ROW_SELECT,
     })) as SlotIntakeRow;
@@ -221,8 +234,14 @@ async function applyToExisting(
   existing: SlotIntakeRow,
   input: ApplyCanonicalSlotWriteInput,
 ): Promise<ApplyCanonicalSlotWriteResult> {
-  const { takenAt, skipped, isExplicitTaken, isExplicitSkip, idempotencyKey } =
-    input;
+  const {
+    takenAt,
+    skipped,
+    isExplicitTaken,
+    isExplicitSkip,
+    idempotencyKey,
+    injectionSite = null,
+  } = input;
 
   const existingActioned = existing.takenAt !== null || existing.skipped;
   const incomingIsPendingEcho = !isExplicitTaken && !isExplicitSkip;
@@ -255,6 +274,10 @@ async function applyToExisting(
       skipped,
       syncVersion: { increment: 1 },
       idempotencyKey: idempotencyKey ?? existing.idempotencyKey ?? null,
+      // v1.8.5 — write the site only when this write carries a resolved
+      // one (taken injection, tracking on, validated). Never clear a
+      // previously-recorded site with a null on an idempotent re-post.
+      ...(injectionSite !== null && { injectionSite }),
     },
     select: SLOT_ROW_SELECT,
   })) as SlotIntakeRow;
diff --git a/src/lib/medications/use-injection-site-prefs.ts b/src/lib/medications/use-injection-site-prefs.ts
new file mode 100644
index 000000000..e6bdeffe5
--- /dev/null
+++ b/src/lib/medications/use-injection-site-prefs.ts
@@ -0,0 +1,29 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+
+import { queryKeys } from "@/lib/query-keys";
+import type { InjectionSiteKey } from "@/lib/medications/injection-sites";
+
+/**
+ * v1.8.5 — read the user's global injection-site exclusion deny-list.
+ *
+ * Shared by every surface that constrains the injection-site picker: the
+ * post-dose log dialog, the per-medication allowed-sites editor, and the
+ * Settings exclusion editor. Cached generously — the value changes rarely
+ * and the mutation invalidates `injectionSitePrefs()`.
+ */
+export function useGlobalExcludedInjectionSites(): InjectionSiteKey[] {
+  const { data } = useQuery({
+    queryKey: queryKeys.injectionSitePrefs(),
+    queryFn: async () => {
+      const res = await fetch("/api/auth/me/injection-site-prefs");
+      if (!res.ok) return [] as InjectionSiteKey[];
+      const json = await res.json();
+      return ((json.data?.globalExcludedInjectionSites ??
+        []) as InjectionSiteKey[]);
+    },
+    staleTime: 5 * 60 * 1000,
+  });
+  return data ?? [];
+}
diff --git a/src/lib/query-keys.ts b/src/lib/query-keys.ts
index 88e9f5986..f75f6149b 100644
--- a/src/lib/query-keys.ts
+++ b/src/lib/query-keys.ts
@@ -180,6 +180,9 @@ export const queryKeys = {
   settingsReminderThresholds: () =>
     ["settings", "reminder-thresholds"] as const,
 
+  /** v1.8.5 — user-level injection-site preferences (global exclusion). */
+  injectionSitePrefs: () => ["settings", "injection-site-prefs"] as const,
+
   /**
    * v1.4.41 W-FRONTEND-FACTORY — Settings → AI surfaces (provider chain,
    * insights settings, user provider preference) and the targets editor
diff --git a/src/lib/validations/medication.ts b/src/lib/validations/medication.ts
index 9b0d884d7..a15e8f958 100644
--- a/src/lib/validations/medication.ts
+++ b/src/lib/validations/medication.ts
@@ -1,6 +1,19 @@
 import { z } from "zod/v4";
 
 import { SCHEDULE_TYPES } from "@/lib/medications/scheduling/recurrence";
+import { INJECTION_SITE_KEYS } from "@/lib/medications/injection-sites";
+
+/**
+ * v1.8.5 — the eight injection-site enum values, mirrored from the
+ * Prisma `InjectionSite` enum via the shared `INJECTION_SITE_KEYS`
+ * tuple. Reused by the intake + bulk-intake request schemas (the
+ * `injectionSite` field) and the per-medication allowed-sites editor.
+ */
+export const INJECTION_SITE_VALUES = INJECTION_SITE_KEYS;
+export type InjectionSiteValue = (typeof INJECTION_SITE_VALUES)[number];
+
+/** Zod enum over the eight injection sites. */
+export const injectionSiteEnum = z.enum(INJECTION_SITE_VALUES);
 
 const timeRegex = /^([01]\d|2[0-3]):([0-5]\d)$/;
 /**
@@ -294,6 +307,28 @@ export const createMedicationSchema = z
     dosesPerUnit: z.number().int().min(1).max(100).optional(),
     /** v1.6.0 — route of administration (ORAL | INJECTION | OTHER). */
     deliveryForm: z.enum(MEDICATION_DELIVERY_FORM_VALUES).optional(),
+    /**
+     * v1.8.5 — per-medication injection-site tracking opt-in. Default
+     * false. Only meaningful when `deliveryForm === "INJECTION"`.
+     */
+    trackInjectionSites: z
+      .boolean()
+      .optional()
+      .describe(
+        "Per-medication injection-site tracking opt-in. Default false. Only meaningful for an INJECTION delivery form; when true the client prompts (skippably) for the site after a taken dose.",
+      ),
+    /**
+     * v1.8.5 — per-medication allowed / preferred injection sites.
+     * Empty = no per-medication restriction. The effective pickable set
+     * subtracts the user's global exclusion (deny wins).
+     */
+    allowedInjectionSites: z
+      .array(injectionSiteEnum)
+      .max(INJECTION_SITE_VALUES.length)
+      .optional()
+      .describe(
+        "Per-medication allowed / preferred injection sites. Empty array = no per-medication restriction (every site offered). The effective pickable set is this list minus the user's global exclusion.",
+      ),
     notificationsEnabled: z.boolean().optional(),
     /** v1.7.0 — iOS Live Activity opt-in for this medication's reminders. */
     liveActivityEnabled: z
@@ -339,6 +374,21 @@ export const updateMedicationSchema = z
     dosesPerUnit: z.number().int().min(1).max(100).nullable().optional(),
     /** v1.6.0 — route of administration (ORAL | INJECTION | OTHER). */
     deliveryForm: z.enum(MEDICATION_DELIVERY_FORM_VALUES).optional(),
+    /** v1.8.5 — per-medication injection-site tracking opt-in. */
+    trackInjectionSites: z
+      .boolean()
+      .optional()
+      .describe(
+        "Per-medication injection-site tracking opt-in. Only meaningful for an INJECTION delivery form. Set false to deactivate tracking.",
+      ),
+    /** v1.8.5 — per-medication allowed / preferred injection sites. */
+    allowedInjectionSites: z
+      .array(injectionSiteEnum)
+      .max(INJECTION_SITE_VALUES.length)
+      .optional()
+      .describe(
+        "Per-medication allowed / preferred injection sites. Empty array clears the restriction. The effective pickable set subtracts the user's global exclusion (deny wins).",
+      ),
     active: z.boolean().optional(),
     notificationsEnabled: z.boolean().optional(),
     /** v1.7.0 — iOS Live Activity opt-in for this medication's reminders. */
@@ -432,11 +482,26 @@ export const intakeSchema = z
       .describe(
         "Caller-issued de-dup key. A second POST with the same key returns the original event without creating a new row.",
       ),
+    /**
+     * v1.8.5 — optional injection-site capture. Only honoured on a
+     * non-skipped (taken) write for a medication with
+     * `deliveryForm === "INJECTION"` and `trackInjectionSites === true`.
+     * The site is validated server-side against the medication's
+     * effective allowed set (per-medication `allowedInjectionSites`
+     * minus the user's `globalExcludedInjectionSites` deny-list); a
+     * disallowed value is rejected with 422. Always optional — the
+     * client may omit it (the dose still records).
+     */
+    injectionSite: injectionSiteEnum
+      .optional()
+      .describe(
+        "Optional injection site for a taken dose. Honoured only when the medication is an INJECTION with site-tracking enabled; validated against the medication's effective allowed set (per-medication allowed sites minus the user's global exclusion). A disallowed site returns 422. Omit to record the dose without a site.",
+      ),
   })
   .meta({
     id: "MedicationIntakeRequest",
     description:
-      "Per-medication intake log body. Idempotent via `idempotencyKey`; the server also dedupes by a 60-second sliding window when the key is absent. Non-skipped intakes auto-decrement pen inventory (best-effort), refresh the per-day compliance rollup, and — for one-shot medications — flip `active` to false.",
+      "Per-medication intake log body. Idempotent via `idempotencyKey`; the server also dedupes by a 60-second sliding window when the key is absent. Non-skipped intakes auto-decrement pen inventory (best-effort), refresh the per-day compliance rollup, and — for one-shot medications — flip `active` to false. The optional `injectionSite` is persisted only for an INJECTION medication with site-tracking enabled and is validated against the medication's effective allowed set (422 on a disallowed value).",
   });
 
 export const externalIntakeSchema = z.object({

From cf649f72ce2ea1d6a54f07b62853b9938caf40e6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 20:14:49 +0200
Subject: [PATCH 09/30] feat(mood): structured tag taxonomy + note capture and
 timeline
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add the Category -> Tag taxonomy the mood surface was missing and the
free-text note the web form could never write, then surface both on the
Insights mood page.

Schema (migration 0101): a global MoodTagCategory -> MoodTag catalog
plus a MoodEntryTagLink join, seeded with a default five-category set
(i18n-keyed labels, Lucide icons). Purely additive — the legacy flat
MoodEntry.tags JSON column, the GLP-1 quick-tags, and the Telegram /
MoodLog sync are untouched; an entry can carry both axes.

Capture: the mood-logging form and the edit sheet gain a Textarea for
the note (model + API already accepted it) and an icon-chip picker over
the taxonomy catalog (GET /api/mood/tags). Create / update resolve the
picked keys to links; unknown keys drop silently against the catalog.

Insights: a structured-tag breakdown (icon + per-tag avg-mood lift) and
a notes timeline join the existing distribution / weekday / flat-tag
sections. The aggregate extension also fixes the flat-tag axis, which
read the raw JSON string and so never populated.

i18n across all six locales. Tests cover the taxonomy aggregation, the
note round-trip, the structured-tag schema, and the notes timeline.
---
 messages/de.json                              |  48 +++-
 messages/en.json                              |  48 +++-
 messages/es.json                              |  48 +++-
 messages/fr.json                              |  48 +++-
 messages/it.json                              |  48 +++-
 messages/pl.json                              |  48 +++-
 .../0101_v185_mood_tag_taxonomy/migration.sql | 252 ++++++++++++++++++
 prisma/schema.prisma                          |  80 ++++++
 src/app/api/mood-entries/[id]/route.ts        |   8 +
 src/app/api/mood-entries/route.ts             |  22 +-
 src/app/api/mood/tags/route.ts                |  43 +++
 .../insights/mood/mood-insights-sections.tsx  |  24 ++
 .../insights/mood/mood-notes-timeline.tsx     |  78 ++++++
 .../mood/mood-structured-tag-breakdown.tsx    |  76 ++++++
 src/components/mood/mood-form.tsx             |  50 ++++
 src/components/mood/mood-list.tsx             |  61 ++++-
 src/components/mood/mood-tag-icons.ts         |  83 ++++++
 src/components/mood/mood-tag-picker.tsx       | 112 ++++++++
 .../__tests__/mood-aggregates.test.ts         |  76 ++++++
 src/lib/insights/mood-aggregates.ts           | 199 +++++++++++++-
 src/lib/mood/tag-links.ts                     |  73 +++++
 src/lib/mood/tag-taxonomy.ts                  | 113 ++++++++
 src/lib/query-keys.ts                         |   8 +
 src/lib/validations/__tests__/moodlog.test.ts |  47 +++-
 src/lib/validations/moodlog.ts                |  13 +
 25 files changed, 1688 insertions(+), 18 deletions(-)
 create mode 100644 prisma/migrations/0101_v185_mood_tag_taxonomy/migration.sql
 create mode 100644 src/app/api/mood/tags/route.ts
 create mode 100644 src/components/insights/mood/mood-notes-timeline.tsx
 create mode 100644 src/components/insights/mood/mood-structured-tag-breakdown.tsx
 create mode 100644 src/components/mood/mood-tag-icons.ts
 create mode 100644 src/components/mood/mood-tag-picker.tsx
 create mode 100644 src/lib/mood/tag-links.ts
 create mode 100644 src/lib/mood/tag-taxonomy.ts

diff --git a/messages/de.json b/messages/de.json
index dbfd00e78..f53fb4e6c 100644
--- a/messages/de.json
+++ b/messages/de.json
@@ -461,7 +461,49 @@
     "deleteConfirmTitle": "Eintrag löschen?",
     "deleteConfirmDescription": "Dieser Stimmungseintrag wird unwiderruflich gelöscht.",
     "pageInfo": "Seite {page} von {total}",
-    "loginRequired": "Bitte anmelden, um Stimmungseinträge zu sehen."
+    "loginRequired": "Bitte anmelden, um Stimmungseinträge zu sehen.",
+    "note": "Notiz",
+    "notePlaceholder": "Notiz dazu, wie du dich fühlst…",
+    "tagPicker": "Tags",
+    "tagCategory": {
+      "feelings": "Gefühle",
+      "sleep": "Schlaf",
+      "health": "Gesundheit",
+      "social": "Soziales",
+      "work": "Arbeit"
+    },
+    "tag": {
+      "happy": "glücklich",
+      "excited": "aufgeregt",
+      "grateful": "dankbar",
+      "relaxed": "entspannt",
+      "content": "zufrieden",
+      "tired": "müde",
+      "unsure": "unsicher",
+      "bored": "gelangweilt",
+      "tense": "angespannt",
+      "angry": "wütend",
+      "stressed": "gestresst",
+      "sad": "traurig",
+      "sleptWell": "gut geschlafen",
+      "sleptOk": "mäßig geschlafen",
+      "sleptPoorly": "schlecht geschlafen",
+      "earlyNight": "früh im Bett",
+      "workedOut": "trainiert",
+      "ateWell": "gesund gegessen",
+      "hydrated": "Wasser getrunken",
+      "walked": "spazieren",
+      "alcohol": "Alkohol",
+      "family": "Familie",
+      "friends": "Freunde",
+      "party": "Party",
+      "alone": "allein",
+      "productive": "produktiv",
+      "overtime": "Überstunden",
+      "dayOff": "Feierabend",
+      "travel": "Reise",
+      "sickDay": "Krankheitstag"
+    }
   },
   "medications": {
     "title": "Medikamente",
@@ -2326,7 +2368,9 @@
         "source": "{n} gepaarte Tage · r = {r}",
         "emptyTitle": "Noch nicht genug gepaarte Daten",
         "emptyDescription": "Erfasse Stimmung und diesen Wert an denselben Tagen, um einen Zusammenhang zu sehen."
-      }
+      },
+      "structuredTagsTitle": "Tag-Auswertung",
+      "notesTimelineTitle": "Notizen"
     }
   },
   "thresholds": {
diff --git a/messages/en.json b/messages/en.json
index 83ec368d5..f64dbe583 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -461,7 +461,49 @@
     "deleteConfirmTitle": "Delete entry?",
     "deleteConfirmDescription": "This mood entry will be permanently deleted.",
     "pageInfo": "Page {page} of {total}",
-    "loginRequired": "Please sign in to view mood entries."
+    "loginRequired": "Please sign in to view mood entries.",
+    "note": "Note",
+    "notePlaceholder": "Add a note about how you're feeling…",
+    "tagPicker": "Tags",
+    "tagCategory": {
+      "feelings": "Feelings",
+      "sleep": "Sleep",
+      "health": "Health",
+      "social": "Social",
+      "work": "Work"
+    },
+    "tag": {
+      "happy": "happy",
+      "excited": "excited",
+      "grateful": "grateful",
+      "relaxed": "relaxed",
+      "content": "content",
+      "tired": "tired",
+      "unsure": "unsure",
+      "bored": "bored",
+      "tense": "tense",
+      "angry": "angry",
+      "stressed": "stressed",
+      "sad": "sad",
+      "sleptWell": "slept well",
+      "sleptOk": "slept okay",
+      "sleptPoorly": "slept poorly",
+      "earlyNight": "early night",
+      "workedOut": "worked out",
+      "ateWell": "ate well",
+      "hydrated": "hydrated",
+      "walked": "walked",
+      "alcohol": "alcohol",
+      "family": "family",
+      "friends": "friends",
+      "party": "party",
+      "alone": "alone",
+      "productive": "productive",
+      "overtime": "overtime",
+      "dayOff": "day off",
+      "travel": "travel",
+      "sickDay": "sick day"
+    }
   },
   "medications": {
     "title": "Medications",
@@ -2326,7 +2368,9 @@
         "source": "{n} paired days · r = {r}",
         "emptyTitle": "Not enough paired data yet",
         "emptyDescription": "Log mood and this metric on the same days to see a correlation."
-      }
+      },
+      "structuredTagsTitle": "Tag breakdown",
+      "notesTimelineTitle": "Notes"
     }
   },
   "thresholds": {
diff --git a/messages/es.json b/messages/es.json
index 00e26dad5..1c96e71c4 100644
--- a/messages/es.json
+++ b/messages/es.json
@@ -461,7 +461,49 @@
     "deleteConfirmTitle": "¿Eliminar entrada?",
     "deleteConfirmDescription": "Esta entrada de estado de ánimo se eliminará de forma permanente.",
     "pageInfo": "Página {page} de {total}",
-    "loginRequired": "Inicia sesión para ver tus estados de ánimo."
+    "loginRequired": "Inicia sesión para ver tus estados de ánimo.",
+    "note": "Nota",
+    "notePlaceholder": "Añade una nota sobre cómo te sientes…",
+    "tagPicker": "Etiquetas",
+    "tagCategory": {
+      "feelings": "Sentimientos",
+      "sleep": "Sueño",
+      "health": "Salud",
+      "social": "Social",
+      "work": "Trabajo"
+    },
+    "tag": {
+      "happy": "feliz",
+      "excited": "emocionado",
+      "grateful": "agradecido",
+      "relaxed": "relajado",
+      "content": "satisfecho",
+      "tired": "cansado",
+      "unsure": "inseguro",
+      "bored": "aburrido",
+      "tense": "tenso",
+      "angry": "enfadado",
+      "stressed": "estresado",
+      "sad": "triste",
+      "sleptWell": "dormí bien",
+      "sleptOk": "dormí regular",
+      "sleptPoorly": "dormí mal",
+      "earlyNight": "me acosté pronto",
+      "workedOut": "entrené",
+      "ateWell": "comí bien",
+      "hydrated": "bebí agua",
+      "walked": "caminé",
+      "alcohol": "alcohol",
+      "family": "familia",
+      "friends": "amigos",
+      "party": "fiesta",
+      "alone": "solo",
+      "productive": "productivo",
+      "overtime": "horas extra",
+      "dayOff": "día libre",
+      "travel": "viaje",
+      "sickDay": "día de baja"
+    }
   },
   "medications": {
     "title": "Medicamentos",
@@ -2326,7 +2368,9 @@
         "source": "{n} días emparejados · r = {r}",
         "emptyTitle": "Aún no hay suficientes datos emparejados",
         "emptyDescription": "Registra el ánimo y esta métrica los mismos días para ver una correlación."
-      }
+      },
+      "structuredTagsTitle": "Desglose de etiquetas",
+      "notesTimelineTitle": "Notas"
     }
   },
   "thresholds": {
diff --git a/messages/fr.json b/messages/fr.json
index 91fc51b2c..8063ccc6f 100644
--- a/messages/fr.json
+++ b/messages/fr.json
@@ -461,7 +461,49 @@
     "deleteConfirmTitle": "Supprimer l’entrée ?",
     "deleteConfirmDescription": "Cette entrée d’humeur sera supprimée définitivement.",
     "pageInfo": "Page {page} sur {total}",
-    "loginRequired": "Connecte-toi pour voir tes entrées d’humeur."
+    "loginRequired": "Connecte-toi pour voir tes entrées d’humeur.",
+    "note": "Note",
+    "notePlaceholder": "Ajoutez une note sur votre ressenti…",
+    "tagPicker": "Étiquettes",
+    "tagCategory": {
+      "feelings": "Émotions",
+      "sleep": "Sommeil",
+      "health": "Santé",
+      "social": "Social",
+      "work": "Travail"
+    },
+    "tag": {
+      "happy": "heureux",
+      "excited": "enthousiaste",
+      "grateful": "reconnaissant",
+      "relaxed": "détendu",
+      "content": "satisfait",
+      "tired": "fatigué",
+      "unsure": "incertain",
+      "bored": "ennuyé",
+      "tense": "tendu",
+      "angry": "en colère",
+      "stressed": "stressé",
+      "sad": "triste",
+      "sleptWell": "bien dormi",
+      "sleptOk": "sommeil moyen",
+      "sleptPoorly": "mal dormi",
+      "earlyNight": "couché tôt",
+      "workedOut": "fait du sport",
+      "ateWell": "bien mangé",
+      "hydrated": "bu de l'eau",
+      "walked": "marché",
+      "alcohol": "alcool",
+      "family": "famille",
+      "friends": "amis",
+      "party": "fête",
+      "alone": "seul",
+      "productive": "productif",
+      "overtime": "heures sup",
+      "dayOff": "jour de repos",
+      "travel": "voyage",
+      "sickDay": "jour de maladie"
+    }
   },
   "medications": {
     "title": "Médicaments",
@@ -2326,7 +2368,9 @@
         "source": "{n} jours appariés · r = {r}",
         "emptyTitle": "Pas encore assez de données appariées",
         "emptyDescription": "Enregistrez l'humeur et cette mesure les mêmes jours pour voir une corrélation."
-      }
+      },
+      "structuredTagsTitle": "Répartition des étiquettes",
+      "notesTimelineTitle": "Notes"
     }
   },
   "thresholds": {
diff --git a/messages/it.json b/messages/it.json
index 9dbe62040..2b00fb2b2 100644
--- a/messages/it.json
+++ b/messages/it.json
@@ -461,7 +461,49 @@
     "deleteConfirmTitle": "Eliminare la voce?",
     "deleteConfirmDescription": "Questa voce dell’umore sarà eliminata in modo definitivo.",
     "pageInfo": "Pagina {page} di {total}",
-    "loginRequired": "Accedi per vedere le voci dell’umore."
+    "loginRequired": "Accedi per vedere le voci dell’umore.",
+    "note": "Nota",
+    "notePlaceholder": "Aggiungi una nota su come ti senti…",
+    "tagPicker": "Etichette",
+    "tagCategory": {
+      "feelings": "Emozioni",
+      "sleep": "Sonno",
+      "health": "Salute",
+      "social": "Sociale",
+      "work": "Lavoro"
+    },
+    "tag": {
+      "happy": "felice",
+      "excited": "entusiasta",
+      "grateful": "grato",
+      "relaxed": "rilassato",
+      "content": "soddisfatto",
+      "tired": "stanco",
+      "unsure": "incerto",
+      "bored": "annoiato",
+      "tense": "teso",
+      "angry": "arrabbiato",
+      "stressed": "stressato",
+      "sad": "triste",
+      "sleptWell": "dormito bene",
+      "sleptOk": "dormito così così",
+      "sleptPoorly": "dormito male",
+      "earlyNight": "a letto presto",
+      "workedOut": "allenato",
+      "ateWell": "mangiato bene",
+      "hydrated": "bevuto acqua",
+      "walked": "camminato",
+      "alcohol": "alcol",
+      "family": "famiglia",
+      "friends": "amici",
+      "party": "festa",
+      "alone": "da solo",
+      "productive": "produttivo",
+      "overtime": "straordinari",
+      "dayOff": "giorno libero",
+      "travel": "viaggio",
+      "sickDay": "giorno di malattia"
+    }
   },
   "medications": {
     "title": "Farmaci",
@@ -2326,7 +2368,9 @@
         "source": "{n} giorni appaiati · r = {r}",
         "emptyTitle": "Non ci sono ancora abbastanza dati appaiati",
         "emptyDescription": "Registra umore e questa metrica negli stessi giorni per vedere una correlazione."
-      }
+      },
+      "structuredTagsTitle": "Analisi etichette",
+      "notesTimelineTitle": "Note"
     }
   },
   "thresholds": {
diff --git a/messages/pl.json b/messages/pl.json
index 51cb4985b..a34c6ad4e 100644
--- a/messages/pl.json
+++ b/messages/pl.json
@@ -461,7 +461,49 @@
     "deleteConfirmTitle": "Usunąć wpis?",
     "deleteConfirmDescription": "Ten wpis nastroju zostanie nieodwracalnie usunięty.",
     "pageInfo": "Strona {page} z {total}",
-    "loginRequired": "Zaloguj się, aby zobaczyć wpisy nastroju."
+    "loginRequired": "Zaloguj się, aby zobaczyć wpisy nastroju.",
+    "note": "Notatka",
+    "notePlaceholder": "Dodaj notatkę o swoim samopoczuciu…",
+    "tagPicker": "Tagi",
+    "tagCategory": {
+      "feelings": "Uczucia",
+      "sleep": "Sen",
+      "health": "Zdrowie",
+      "social": "Społeczne",
+      "work": "Praca"
+    },
+    "tag": {
+      "happy": "szczęśliwy",
+      "excited": "podekscytowany",
+      "grateful": "wdzięczny",
+      "relaxed": "zrelaksowany",
+      "content": "zadowolony",
+      "tired": "zmęczony",
+      "unsure": "niepewny",
+      "bored": "znudzony",
+      "tense": "spięty",
+      "angry": "zły",
+      "stressed": "zestresowany",
+      "sad": "smutny",
+      "sleptWell": "dobrze spałem",
+      "sleptOk": "sen średni",
+      "sleptPoorly": "źle spałem",
+      "earlyNight": "wcześnie spać",
+      "workedOut": "trening",
+      "ateWell": "zdrowo zjadłem",
+      "hydrated": "piłem wodę",
+      "walked": "spacer",
+      "alcohol": "alkohol",
+      "family": "rodzina",
+      "friends": "znajomi",
+      "party": "impreza",
+      "alone": "sam",
+      "productive": "produktywny",
+      "overtime": "nadgodziny",
+      "dayOff": "dzień wolny",
+      "travel": "podróż",
+      "sickDay": "dzień chorobowy"
+    }
   },
   "medications": {
     "title": "Leki",
@@ -2326,7 +2368,9 @@
         "source": "{n} sparowanych dni · r = {r}",
         "emptyTitle": "Za mało sparowanych danych",
         "emptyDescription": "Rejestruj nastrój i ten wskaźnik w te same dni, aby zobaczyć korelację."
-      }
+      },
+      "structuredTagsTitle": "Podział tagów",
+      "notesTimelineTitle": "Notatki"
     }
   },
   "thresholds": {
diff --git a/prisma/migrations/0101_v185_mood_tag_taxonomy/migration.sql b/prisma/migrations/0101_v185_mood_tag_taxonomy/migration.sql
new file mode 100644
index 000000000..3afb5449f
--- /dev/null
+++ b/prisma/migrations/0101_v185_mood_tag_taxonomy/migration.sql
@@ -0,0 +1,252 @@
+-- v1.8.5 — structured mood-tag taxonomy.
+--
+-- Adds a global Category -> Tag catalog plus a per-entry join, modelled
+-- on the standalone mood diary's structured taxonomy. Purely additive:
+-- the legacy flat `mood_entries.tags` JSON column is untouched and keeps
+-- working for every existing row, the GLP-1 quick-tag chips, and the
+-- Telegram / MoodLog sync. The structured taxonomy is a second, richer
+-- capture surface; the tag-frequency / lift breakdown folds the two
+-- axes together.
+--
+-- `label_key` columns carry an i18n message key (resolved client-side
+-- against all six locales) rather than a hard-coded label, so the seeded
+-- catalog renders localised everywhere. The seed at the bottom uses
+-- deterministic ids + ON CONFLICT upsert so re-running is idempotent.
+--
+-- Reversibility (down):
+--   DROP TABLE IF EXISTS "mood_entry_tag_links";
+--   DROP TABLE IF EXISTS "mood_tags";
+--   DROP TABLE IF EXISTS "mood_tag_categories";
+
+-- CreateTable
+CREATE TABLE "mood_tag_categories" (
+    "id" TEXT NOT NULL,
+    "key" TEXT NOT NULL,
+    "label_key" TEXT NOT NULL,
+    "icon" TEXT,
+    "sort_order" INTEGER NOT NULL DEFAULT 0,
+    "is_active" BOOLEAN NOT NULL DEFAULT true,
+
+    CONSTRAINT "mood_tag_categories_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "mood_tags" (
+    "id" TEXT NOT NULL,
+    "category_id" TEXT NOT NULL,
+    "key" TEXT NOT NULL,
+    "label_key" TEXT NOT NULL,
+    "icon" TEXT,
+    "sort_order" INTEGER NOT NULL DEFAULT 0,
+    "is_active" BOOLEAN NOT NULL DEFAULT true,
+
+    CONSTRAINT "mood_tags_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "mood_entry_tag_links" (
+    "mood_entry_id" TEXT NOT NULL,
+    "mood_tag_id" TEXT NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "mood_entry_tag_links_pkey" PRIMARY KEY ("mood_entry_id","mood_tag_id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "mood_tag_categories_key_key" ON "mood_tag_categories"("key");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "mood_tags_key_key" ON "mood_tags"("key");
+
+-- CreateIndex
+CREATE INDEX "mood_tags_category_id_sort_order_idx" ON "mood_tags"("category_id", "sort_order");
+
+-- CreateIndex
+CREATE INDEX "mood_entry_tag_links_mood_tag_id_idx" ON "mood_entry_tag_links"("mood_tag_id");
+
+-- AddForeignKey
+ALTER TABLE "mood_tags" ADD CONSTRAINT "mood_tags_category_id_fkey" FOREIGN KEY ("category_id") REFERENCES "mood_tag_categories"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "mood_entry_tag_links" ADD CONSTRAINT "mood_entry_tag_links_mood_entry_id_fkey" FOREIGN KEY ("mood_entry_id") REFERENCES "mood_entries"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "mood_entry_tag_links" ADD CONSTRAINT "mood_entry_tag_links_mood_tag_id_fkey" FOREIGN KEY ("mood_tag_id") REFERENCES "mood_tags"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- Seed the default taxonomy (idempotent upsert by `key`). Mirrors
+-- `src/lib/mood/tag-taxonomy.ts` — keep the two in sync if either
+-- changes.
+INSERT INTO "mood_tag_categories" ("id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mtc_feelings', 'feelings', 'mood.tagCategory.feelings', 'Heart', 0, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_happy', 'mtc_feelings', 'happy', 'mood.tag.happy', 'Smile', 0, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_excited', 'mtc_feelings', 'excited', 'mood.tag.excited', 'Zap', 1, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_grateful', 'mtc_feelings', 'grateful', 'mood.tag.grateful', 'HandHeart', 2, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_relaxed', 'mtc_feelings', 'relaxed', 'mood.tag.relaxed', 'CloudSun', 3, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_content', 'mtc_feelings', 'content', 'mood.tag.content', 'ThumbsUp', 4, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_tired', 'mtc_feelings', 'tired', 'mood.tag.tired', 'Moon', 5, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_unsure', 'mtc_feelings', 'unsure', 'mood.tag.unsure', 'HelpCircle', 6, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_bored', 'mtc_feelings', 'bored', 'mood.tag.bored', 'Meh', 7, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_tense', 'mtc_feelings', 'tense', 'mood.tag.tense', 'AlertTriangle', 8, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_angry', 'mtc_feelings', 'angry', 'mood.tag.angry', 'Flame', 9, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_stressed', 'mtc_feelings', 'stressed', 'mood.tag.stressed', 'Brain', 10, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_sad', 'mtc_feelings', 'sad', 'mood.tag.sad', 'Frown', 11, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tag_categories" ("id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mtc_sleep', 'sleep', 'mood.tagCategory.sleep', 'BedDouble', 1, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_slept_well', 'mtc_sleep', 'slept_well', 'mood.tag.sleptWell', 'Moon', 0, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_slept_ok', 'mtc_sleep', 'slept_ok', 'mood.tag.sleptOk', 'CloudMoon', 1, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_slept_poorly', 'mtc_sleep', 'slept_poorly', 'mood.tag.sleptPoorly', 'MoonStar', 2, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_early_night', 'mtc_sleep', 'early_night', 'mood.tag.earlyNight', 'Clock', 3, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tag_categories" ("id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mtc_health', 'health', 'mood.tagCategory.health', 'HeartPulse', 2, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_worked_out', 'mtc_health', 'worked_out', 'mood.tag.workedOut', 'Dumbbell', 0, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_ate_well', 'mtc_health', 'ate_well', 'mood.tag.ateWell', 'Apple', 1, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_hydrated', 'mtc_health', 'hydrated', 'mood.tag.hydrated', 'GlassWater', 2, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_walked', 'mtc_health', 'walked', 'mood.tag.walked', 'Footprints', 3, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_alcohol', 'mtc_health', 'alcohol', 'mood.tag.alcohol', 'Wine', 4, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tag_categories" ("id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mtc_social', 'social', 'mood.tagCategory.social', 'Users', 3, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_family', 'mtc_social', 'family', 'mood.tag.family', 'Home', 0, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_friends', 'mtc_social', 'friends', 'mood.tag.friends', 'Users', 1, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_party', 'mtc_social', 'party', 'mood.tag.party', 'PartyPopper', 2, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_alone', 'mtc_social', 'alone', 'mood.tag.alone', 'User', 3, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tag_categories" ("id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mtc_work', 'work', 'mood.tagCategory.work', 'Briefcase', 4, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_productive', 'mtc_work', 'productive', 'mood.tag.productive', 'CheckCircle', 0, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_overtime', 'mtc_work', 'overtime', 'mood.tag.overtime', 'Clock', 1, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_day_off', 'mtc_work', 'day_off', 'mood.tag.dayOff', 'LogOut', 2, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_travel', 'mtc_work', 'travel', 'mood.tag.travel', 'Plane', 3, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
+
+INSERT INTO "mood_tags" ("id", "category_id", "key", "label_key", "icon", "sort_order", "is_active")
+VALUES ('mt_sick_day', 'mtc_work', 'sick_day', 'mood.tag.sickDay', 'Thermometer', 4, true)
+ON CONFLICT ("key") DO UPDATE SET
+  "category_id" = EXCLUDED."category_id", "label_key" = EXCLUDED."label_key", "icon" = EXCLUDED."icon", "sort_order" = EXCLUDED."sort_order";
diff --git a/prisma/schema.prisma b/prisma/schema.prisma
index b7060a1dd..e03a08b5f 100644
--- a/prisma/schema.prisma
+++ b/prisma/schema.prisma
@@ -1560,6 +1560,13 @@ model MoodEntry {
 
   user User @relation(fields: [userId], references: [id], onDelete: Cascade)
 
+  // v1.8.5 — structured-tag links. Additive alongside the legacy flat
+  // `tags` JSON string: an entry can carry both (a free-text tag the user
+  // typed AND a structured tag they picked from the taxonomy). The
+  // aggregates read whichever is present; existing rows keep their flat
+  // `tags` untouched.
+  tagLinks MoodEntryTagLink[]
+
   @@unique([userId, date, moodLoggedAt])
   @@index([userId, date])
   // v1.7.0 sync — keyset support for the `/api/sync/changes` mood feed
@@ -1568,6 +1575,79 @@ model MoodEntry {
   @@map("mood_entries")
 }
 
+// ─── Mood Tag Taxonomy (v1.8.5 W6-tax) ────────────────────────
+//
+// Structured, icon-bearing tag catalog modelled on the standalone mood
+// diary's Category → TagItem shape. Global reference data (one shared
+// catalog for the deployment, not per-user): a self-hoster's account
+// inherits the seeded categories the same way the metric-type enum is
+// shared. `MoodEntryTagLink` is the per-entry join.
+//
+// Backward-compat: this is purely ADDITIVE. The legacy flat
+// `MoodEntry.tags` (a JSON string array of free-text keys) keeps working
+// unchanged — the GLP-1 quick-tag chips, the Telegram/MoodLog sync, and
+// every existing row stay on the flat axis. The structured taxonomy is a
+// second, richer capture surface that the tag-frequency / lift breakdown
+// folds in next to the flat tags (`mood-aggregates.ts`).
+//
+// `labelKey` carries an i18n key (resolved client-side against all six
+// locales) rather than a hard-coded German label, so the seeded catalog
+// renders localised everywhere. `icon` is a Lucide icon name rendered by
+// the capture UI + breakdown.
+model MoodTagCategory {
+  id        String  @id @default(cuid())
+  /// Stable machine key (e.g. `feelings`). Unique across the catalog so
+  /// the seed migration can upsert idempotently.
+  key       String  @unique
+  /// i18n message key for the category label (`mood.tagCategory.<key>`).
+  labelKey  String  @map("label_key")
+  /// Lucide icon name for the category header.
+  icon      String?
+  sortOrder Int     @default(0) @map("sort_order")
+  /// Soft-hide a category without deleting its historical links.
+  isActive  Boolean @default(true) @map("is_active")
+
+  tags MoodTag[]
+
+  @@map("mood_tag_categories")
+}
+
+model MoodTag {
+  id         String  @id @default(cuid())
+  categoryId String  @map("category_id")
+  /// Stable machine key (e.g. `happy`). Unique across the catalog.
+  key        String  @unique
+  /// i18n message key for the tag label (`mood.tag.<key>`).
+  labelKey   String  @map("label_key")
+  /// Lucide icon name for the tag chip.
+  icon       String?
+  sortOrder  Int     @default(0) @map("sort_order")
+  isActive   Boolean @default(true) @map("is_active")
+
+  category MoodTagCategory    @relation(fields: [categoryId], references: [id], onDelete: Cascade)
+  links    MoodEntryTagLink[]
+
+  @@index([categoryId, sortOrder])
+  @@map("mood_tags")
+}
+
+// Join: which structured tags a mood entry carries. Composite PK keeps
+// the pairing unique; cascade on both sides so deleting an entry (or a
+// catalog tag) cleans up its links. Distinct from the flat `tags` JSON
+// column on `MoodEntry`.
+model MoodEntryTagLink {
+  moodEntryId String   @map("mood_entry_id")
+  moodTagId   String   @map("mood_tag_id")
+  createdAt   DateTime @default(now()) @map("created_at")
+
+  moodEntry MoodEntry @relation(fields: [moodEntryId], references: [id], onDelete: Cascade)
+  moodTag   MoodTag   @relation(fields: [moodTagId], references: [id], onDelete: Cascade)
+
+  @@id([moodEntryId, moodTagId])
+  @@index([moodTagId])
+  @@map("mood_entry_tag_links")
+}
+
 // ─── Mood Reminder Dispatch Ledger (v0.5.4 ios-coord) ─────
 //
 // Idempotency guard for the daily 22:00 MOOD_REMINDER push. The
diff --git a/src/app/api/mood-entries/[id]/route.ts b/src/app/api/mood-entries/[id]/route.ts
index c68f8d21c..fd2849322 100644
--- a/src/app/api/mood-entries/[id]/route.ts
+++ b/src/app/api/mood-entries/[id]/route.ts
@@ -18,6 +18,7 @@ import { annotate } from "@/lib/logging/context";
 import { moodDateKey, DEFAULT_TIMEZONE } from "@/lib/mood/date-key";
 import { invalidateUserMood } from "@/lib/cache/invalidate";
 import { recomputeMoodBucketsForEntry } from "@/lib/rollups/mood-rollups";
+import { replaceTagLinks } from "@/lib/mood/tag-links";
 
 type RouteParams = { params: Promise<{ id: string }> };
 
@@ -138,6 +139,13 @@ export const PUT = apiHandler(
       data: updateData,
     });
 
+    // v1.8.5 — full replacement of the structured-tag link set when
+    // `tagKeys` is present in the body. `null` clears every link; an
+    // omitted field leaves the links untouched.
+    if (data.tagKeys !== undefined) {
+      await replaceTagLinks(id, data.tagKeys ?? []);
+    }
+
     await auditLog("moodEntry.update", {
       userId: user.id,
       ipAddress: getClientIp(request),
diff --git a/src/app/api/mood-entries/route.ts b/src/app/api/mood-entries/route.ts
index 5afdfba91..8f3dad697 100644
--- a/src/app/api/mood-entries/route.ts
+++ b/src/app/api/mood-entries/route.ts
@@ -22,6 +22,7 @@ import { moodDateKey, DEFAULT_TIMEZONE } from "@/lib/mood/date-key";
 import { invalidateUserMood } from "@/lib/cache/invalidate";
 import { recomputeMoodBucketsForEntry } from "@/lib/rollups/mood-rollups";
 import { pushMoodEntriesToMoodLog } from "@/lib/moodlog/push";
+import { createTagLinks } from "@/lib/mood/tag-links";
 
 function parseTags(tags: string | null): string[] {
   if (!tags) return [];
@@ -90,6 +91,13 @@ export const GET = apiHandler(async (request: NextRequest) => {
       orderBy: { [sortBy]: sortDir },
       take: limit,
       skip: offset,
+      // v1.8.5 — include the structured-tag link keys so the edit form
+      // can pre-populate the taxonomy picker.
+      include: {
+        tagLinks: {
+          select: { moodTag: { select: { key: true } } },
+        },
+      },
     }),
     prisma.moodEntry.count({ where }),
   ]);
@@ -99,9 +107,11 @@ export const GET = apiHandler(async (request: NextRequest) => {
     meta: { total, limit, offset },
   });
 
-  const entriesWithParsedTags = entries.map((e) => ({
+  const entriesWithParsedTags = entries.map(({ tagLinks, ...e }) => ({
     ...e,
     tags: parseTags(e.tags),
+    // v1.8.5 — flat list of structured-tag keys attached to the entry.
+    tagKeys: tagLinks.map((link) => link.moodTag.key),
   }));
 
   return apiSuccess({
@@ -147,7 +157,7 @@ async function postMoodEntry(request: NextRequest) {
     return returnAllZodIssues(parsed.error, 422);
   }
 
-  const { mood, tags, note, moodLoggedAt, source } = parsed.data;
+  const { mood, tags, tagKeys, note, moodLoggedAt, source } = parsed.data;
   // v1.4.25 W7b (Decision A) — anchor the `date` string to the user's
   // current displayTimezone and store the resolved zone on the row.
   // Legacy rows with `tz IS NULL` continue to read as Europe/Berlin
@@ -171,6 +181,14 @@ async function postMoodEntry(request: NextRequest) {
       },
     });
 
+    // v1.8.5 — write the structured-tag links. Unknown keys are dropped
+    // inside the helper (the catalog is the source of truth). Best-effort
+    // is wrong here — the links are user-intended content, not a cache —
+    // so a failure surfaces as a 5xx via the outer try/catch.
+    if (tagKeys && tagKeys.length > 0) {
+      await createTagLinks(entry.id, tagKeys);
+    }
+
     await auditLog("moodEntry.create", {
       userId: user.id,
       ipAddress: getClientIp(request),
diff --git a/src/app/api/mood/tags/route.ts b/src/app/api/mood/tags/route.ts
new file mode 100644
index 000000000..6cf10e667
--- /dev/null
+++ b/src/app/api/mood/tags/route.ts
@@ -0,0 +1,43 @@
+import { prisma } from "@/lib/db";
+import { apiSuccess } from "@/lib/api-response";
+import { apiHandler, requireAuth } from "@/lib/api-handler";
+import { annotate } from "@/lib/logging/context";
+
+export const dynamic = "force-dynamic";
+
+/**
+ * v1.8.5 — structured mood-tag taxonomy catalog.
+ *
+ * Returns the active Category -> Tag tree the mood-logging form renders
+ * as a pick-from-catalog capture surface. Global reference data (one
+ * shared catalog for the deployment, seeded by migration 0101), so the
+ * read carries no per-user filter and no encryption. The `labelKey`
+ * fields resolve client-side against the active locale.
+ */
+export const GET = apiHandler(async () => {
+  // Auth-gated like every app route — the catalog is not public, but it
+  // is identical for every authenticated user.
+  await requireAuth();
+
+  const categories = await prisma.moodTagCategory.findMany({
+    where: { isActive: true },
+    orderBy: { sortOrder: "asc" },
+    select: {
+      key: true,
+      labelKey: true,
+      icon: true,
+      tags: {
+        where: { isActive: true },
+        orderBy: { sortOrder: "asc" },
+        select: { key: true, labelKey: true, icon: true },
+      },
+    },
+  });
+
+  annotate({
+    action: { name: "mood.tags.catalog.read" },
+    meta: { category_count: categories.length },
+  });
+
+  return apiSuccess({ categories });
+});
diff --git a/src/components/insights/mood/mood-insights-sections.tsx b/src/components/insights/mood/mood-insights-sections.tsx
index 7e5187919..db1b9bc6e 100644
--- a/src/components/insights/mood/mood-insights-sections.tsx
+++ b/src/components/insights/mood/mood-insights-sections.tsx
@@ -24,6 +24,14 @@ import {
   MoodCorrelationCards,
   type MoodMetricCorrelationData,
 } from "./mood-correlation-cards";
+import {
+  MoodStructuredTagBreakdown,
+  type MoodStructuredTagRow,
+} from "./mood-structured-tag-breakdown";
+import {
+  MoodNotesTimeline,
+  type MoodNoteEntry,
+} from "./mood-notes-timeline";
 
 /**
  * v1.8.5 — additional Mood Insights sections.
@@ -46,6 +54,8 @@ interface MoodInsightsResponse {
   distribution: MoodDistributionRow[];
   weekday: MoodWeekdayRow[];
   tags: MoodTagRow[];
+  structuredTags: MoodStructuredTagRow[];
+  notesTimeline: MoodNoteEntry[];
   correlations: {
     sleep: MoodMetricCorrelationData;
     steps: MoodMetricCorrelationData;
@@ -99,6 +109,8 @@ export function MoodInsightsSections() {
   );
 
   const hasTags = data.tags.length > 0;
+  const hasStructuredTags = data.structuredTags.length > 0;
+  const hasNotes = data.notesTimeline.length > 0;
 
   return (
     <div className="space-y-4">
@@ -119,6 +131,12 @@ export function MoodInsightsSections() {
         </SectionCard>
       </div>
 
+      {hasStructuredTags && (
+        <SectionCard title={t("insights.mood.structuredTagsTitle")}>
+          <MoodStructuredTagBreakdown tags={data.structuredTags} />
+        </SectionCard>
+      )}
+
       {hasTags && (
         <SectionCard title={t("insights.mood.tagsTitle")}>
           <MoodTagBreakdown tags={data.tags} />
@@ -138,6 +156,12 @@ export function MoodInsightsSections() {
           pulse={data.correlations.pulse}
         />
       </div>
+
+      {hasNotes && (
+        <SectionCard title={t("insights.mood.notesTimelineTitle")}>
+          <MoodNotesTimeline notes={data.notesTimeline} />
+        </SectionCard>
+      )}
     </div>
   );
 }
diff --git a/src/components/insights/mood/mood-notes-timeline.tsx b/src/components/insights/mood/mood-notes-timeline.tsx
new file mode 100644
index 000000000..136cdbcfd
--- /dev/null
+++ b/src/components/insights/mood/mood-notes-timeline.tsx
@@ -0,0 +1,78 @@
+"use client";
+
+import { formatDateTime } from "@/lib/format";
+import { useTranslations } from "@/lib/i18n/context";
+import { MOOD_LABEL_KEYS } from "@/lib/mood/labels";
+
+/**
+ * v1.8.5 (C1) — notes timeline.
+ *
+ * Chronological feed of recent mood entries that carry a free-text note,
+ * each with its score, mood label, note text, and tag chips. Renders the
+ * note as a plain React text child (no markdown library — the project
+ * forbids one for XSS reasons).
+ */
+
+export interface MoodNoteEntry {
+  date: string;
+  loggedAt: string;
+  score: number;
+  mood: string | null;
+  note: string;
+  tags: string[];
+  structuredTagLabelKeys: string[];
+}
+
+export function MoodNotesTimeline({ notes }: { notes: MoodNoteEntry[] }) {
+  const { t } = useTranslations();
+
+  return (
+    <ul className="space-y-3" data-slot="mood-notes-timeline">
+      {notes.map((entry) => {
+        const moodLabel =
+          entry.mood && MOOD_LABEL_KEYS[entry.mood]
+            ? t(MOOD_LABEL_KEYS[entry.mood])
+            : entry.mood;
+        return (
+          <li
+            key={`${entry.loggedAt}-${entry.date}`}
+            className="border-border/60 border-l-2 pl-3"
+          >
+            <div className="text-muted-foreground flex items-center gap-2 text-xs">
+              <span className="text-foreground font-semibold tabular-nums">
+                {entry.score}
+              </span>
+              {moodLabel && <span>({moodLabel})</span>}
+              <span>·</span>
+              <span>{formatDateTime(entry.loggedAt)}</span>
+            </div>
+            <p className="text-foreground/90 mt-0.5 text-sm whitespace-pre-wrap">
+              {entry.note}
+            </p>
+            {(entry.structuredTagLabelKeys.length > 0 ||
+              entry.tags.length > 0) && (
+              <div className="mt-1 flex flex-wrap gap-1">
+                {entry.structuredTagLabelKeys.map((labelKey) => (
+                  <span
+                    key={labelKey}
+                    className="bg-muted text-muted-foreground rounded-full px-2 py-0.5 text-[10px]"
+                  >
+                    {t(labelKey)}
+                  </span>
+                ))}
+                {entry.tags.map((tag) => (
+                  <span
+                    key={tag}
+                    className="border-border/70 text-muted-foreground rounded-full border px-2 py-0.5 text-[10px]"
+                  >
+                    {tag}
+                  </span>
+                ))}
+              </div>
+            )}
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
diff --git a/src/components/insights/mood/mood-structured-tag-breakdown.tsx b/src/components/insights/mood/mood-structured-tag-breakdown.tsx
new file mode 100644
index 000000000..423cb31ac
--- /dev/null
+++ b/src/components/insights/mood/mood-structured-tag-breakdown.tsx
@@ -0,0 +1,76 @@
+"use client";
+
+import { useTranslations } from "@/lib/i18n/context";
+import { moodTagIcon } from "@/components/mood/mood-tag-icons";
+
+/**
+ * v1.8.5 — structured-tag breakdown.
+ *
+ * Ranked icon-bearing rows over the taxonomy tags the user picked,
+ * grouped under their category, with the per-tag average mood ("lift")
+ * as a coloured score. Distinct from the flat free-text breakdown:
+ * structured tags carry icons + categories from the curated catalog.
+ */
+
+export interface MoodStructuredTagRow {
+  key: string;
+  categoryKey: string;
+  labelKey: string;
+  icon: string | null;
+  count: number;
+  avgScore: number;
+}
+
+function colorForScore(score: number): string {
+  if (score < 2) return "var(--dracula-red)";
+  if (score < 3) return "var(--dracula-orange)";
+  if (score < 3.5) return "var(--dracula-yellow)";
+  return "var(--dracula-green)";
+}
+
+export function MoodStructuredTagBreakdown({
+  tags,
+}: {
+  tags: MoodStructuredTagRow[];
+}) {
+  const { t } = useTranslations();
+  const maxCount = tags.reduce((m, row) => Math.max(m, row.count), 0) || 1;
+
+  return (
+    <ul className="space-y-2" data-slot="mood-structured-tag-breakdown">
+      {tags.map((row) => {
+        const Icon = moodTagIcon(row.icon);
+        return (
+          <li key={row.key} className="flex items-center gap-2 text-sm">
+            <Icon
+              className="text-muted-foreground h-4 w-4 shrink-0"
+              aria-hidden="true"
+            />
+            <span className="text-foreground w-28 shrink-0 truncate">
+              {t(row.labelKey)}
+            </span>
+            <div className="bg-secondary relative h-3 flex-1 overflow-hidden rounded-full">
+              <div
+                className="absolute inset-y-0 left-0 rounded-full"
+                style={{
+                  width: `${(row.count / maxCount) * 100}%`,
+                  backgroundColor: colorForScore(row.avgScore),
+                }}
+              />
+            </div>
+            <span className="text-muted-foreground w-6 shrink-0 text-right tabular-nums">
+              {row.count}
+            </span>
+            <span
+              className="w-10 shrink-0 text-right text-xs font-medium tabular-nums"
+              style={{ color: colorForScore(row.avgScore) }}
+              title={t("insights.mood.tagAvgMood")}
+            >
+              {row.avgScore.toFixed(1)}
+            </span>
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
diff --git a/src/components/mood/mood-form.tsx b/src/components/mood/mood-form.tsx
index cf7956f68..a42ce14e1 100644
--- a/src/components/mood/mood-form.tsx
+++ b/src/components/mood/mood-form.tsx
@@ -11,6 +11,7 @@ import {
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
 import { DateTimeInput } from "@/components/ui/date-input";
 import { Label } from "@/components/ui/label";
 import { Loader2, MoreHorizontal, Plus, RotateCcw } from "lucide-react";
@@ -18,6 +19,7 @@ import { toast } from "sonner";
 import { useTranslations } from "@/lib/i18n/context";
 import { useRovingRadioGroup } from "@/hooks/use-roving-radio-group";
 import { invalidateKeys, moodDependentKeys } from "@/lib/query-keys";
+import { MoodTagPicker } from "./mood-tag-picker";
 
 const MOOD_LEVELS = [
   { value: "SUPER_GUT", score: 5, labelKey: "mood.levelSuperGut" },
@@ -77,10 +79,22 @@ export function MoodForm({ onSuccess, onCancel, footerSlot }: MoodFormProps) {
     onSelect: (index) => setMood(MOOD_LEVELS[index]!.value),
   });
   const [tagsInput, setTagsInput] = useState("");
+  // v1.8.5 — structured-tag keys picked from the taxonomy catalog.
+  const [tagKeys, setTagKeys] = useState<string[]>([]);
+  // v1.8.5 (C1) — first-class free-text note. The model + API already
+  // accepted `note`; the web form was the only surface that couldn't
+  // write it.
+  const [note, setNote] = useState("");
   const [moodLoggedAt, setMoodLoggedAt] = useState(getDefaultMoodLoggedAtValue);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
+  function toggleTagKey(key: string) {
+    setTagKeys((prev) =>
+      prev.includes(key) ? prev.filter((k) => k !== key) : [...prev, key],
+    );
+  }
+
   // v1.4.27 MB3 — error banner descriptor for the timestamp input.
   const errorId = useId();
   const errorDescriptor = error ? errorId : undefined;
@@ -93,6 +107,8 @@ export function MoodForm({ onSuccess, onCancel, footerSlot }: MoodFormProps) {
   function resetForm() {
     setMood("");
     setTagsInput("");
+    setTagKeys([]);
+    setNote("");
     setMoodLoggedAt(getDefaultMoodLoggedAtValue());
     setError(null);
   }
@@ -110,12 +126,16 @@ export function MoodForm({ onSuccess, onCancel, footerSlot }: MoodFormProps) {
         .map((t) => t.trim())
         .filter(Boolean);
 
+      const trimmedNote = note.trim();
+
       const res = await fetch("/api/mood-entries", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
           mood,
           tags: tags.length > 0 ? tags : undefined,
+          tagKeys: tagKeys.length > 0 ? tagKeys : undefined,
+          note: trimmedNote.length > 0 ? trimmedNote : undefined,
           moodLoggedAt: timestamp,
         }),
       });
@@ -308,6 +328,36 @@ export function MoodForm({ onSuccess, onCancel, footerSlot }: MoodFormProps) {
         </div>
       </div>
 
+      {/* v1.8.5 — structured-tag taxonomy picker. Additive next to the
+          free-text input above; an entry can carry both axes. */}
+      <div className="space-y-2">
+        <Label>
+          {t("mood.tagPicker")}{" "}
+          <span className="text-muted-foreground font-normal">
+            ({t("common.optional")})
+          </span>
+        </Label>
+        <MoodTagPicker selected={tagKeys} onToggle={toggleTagKey} />
+      </div>
+
+      {/* v1.8.5 (C1) — free-text note. */}
+      <div className="space-y-2">
+        <Label htmlFor="mood-note">
+          {t("mood.note")}{" "}
+          <span className="text-muted-foreground font-normal">
+            ({t("common.optional")})
+          </span>
+        </Label>
+        <Textarea
+          id="mood-note"
+          value={note}
+          onChange={(e) => setNote(e.target.value)}
+          placeholder={t("mood.notePlaceholder")}
+          maxLength={500}
+          rows={3}
+        />
+      </div>
+
       {error && (
         <div
           id={errorId}
diff --git a/src/components/mood/mood-list.tsx b/src/components/mood/mood-list.tsx
index cc127e21b..d8f729cd6 100644
--- a/src/components/mood/mood-list.tsx
+++ b/src/components/mood/mood-list.tsx
@@ -31,6 +31,7 @@ import {
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
 import { DateTimeInput } from "@/components/ui/date-input";
 import { Label } from "@/components/ui/label";
 import {
@@ -64,6 +65,7 @@ import {
 } from "@/lib/mood/labels";
 import { invalidateKeys, moodDependentKeys } from "@/lib/query-keys";
 import { useRovingRadioGroup } from "@/hooks/use-roving-radio-group";
+import { MoodTagPicker } from "./mood-tag-picker";
 
 // Re-export the score map under the legacy local name to keep the
 // rest of this file unchanged. v1.4.27 B6 / BL-P6-11 — the single
@@ -76,6 +78,9 @@ interface MoodEntry {
   mood: string;
   score: number;
   tags: string[];
+  // v1.8.5 — structured-tag keys + free-text note.
+  tagKeys: string[];
+  note: string | null;
   source: string;
   moodLoggedAt: string;
 }
@@ -127,8 +132,16 @@ export function MoodList({ onAddFirst }: MoodListProps = {}) {
     onSelect: (index) => setEditMood(MOOD_LEVELS_LIST[index]!),
   });
   const [editTagsInput, setEditTagsInput] = useState("");
+  const [editTagKeys, setEditTagKeys] = useState<string[]>([]);
+  const [editNote, setEditNote] = useState("");
   const [editMoodLoggedAt, setEditMoodLoggedAt] = useState("");
   const [editError, setEditError] = useState<string | null>(null);
+
+  function toggleEditTagKey(key: string) {
+    setEditTagKeys((prev) =>
+      prev.includes(key) ? prev.filter((k) => k !== key) : [...prev, key],
+    );
+  }
   const [editDeleteDialogOpen, setEditDeleteDialogOpen] = useState(false);
   // v1.4.27 R4 RC2 — Sheet-branch sticky-pinned footer slot.
   const editFormId = useId();
@@ -194,17 +207,21 @@ export function MoodList({ onAddFirst }: MoodListProps = {}) {
       id,
       mood,
       tags,
+      tagKeys,
+      note,
       moodLoggedAt,
     }: {
       id: string;
       mood: string;
       tags: string[] | null;
+      tagKeys: string[];
+      note: string | null;
       moodLoggedAt: string;
     }) => {
       const res = await fetch(`/api/mood-entries/${id}`, {
         method: "PUT",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ mood, tags, moodLoggedAt }),
+        body: JSON.stringify({ mood, tags, tagKeys, note, moodLoggedAt }),
       });
 
       const json = await res.json();
@@ -228,6 +245,8 @@ export function MoodList({ onAddFirst }: MoodListProps = {}) {
     setEditing(entry);
     setEditMood(entry.mood);
     setEditTagsInput(entry.tags.join(", "));
+    setEditTagKeys(entry.tagKeys ?? []);
+    setEditNote(entry.note ?? "");
     setEditMoodLoggedAt(toDateTimeLocalValue(entry.moodLoggedAt));
     setEditError(null);
   }
@@ -266,11 +285,15 @@ export function MoodList({ onAddFirst }: MoodListProps = {}) {
       .map((t) => t.trim())
       .filter(Boolean);
 
+    const trimmedNote = editNote.trim();
+
     setEditError(null);
     updateMutation.mutate({
       id: editing.id,
       mood: editMood,
       tags: tags.length > 0 ? tags : null,
+      tagKeys: editTagKeys,
+      note: trimmedNote.length > 0 ? trimmedNote : null,
       moodLoggedAt: measuredDate.toISOString(),
     });
   }
@@ -395,6 +418,11 @@ export function MoodList({ onAddFirst }: MoodListProps = {}) {
                       </TableCell>
                       <TableCell className="text-muted-foreground text-sm">
                         {entry.tags.length > 0 ? entry.tags.join(", ") : "-"}
+                        {entry.note && (
+                          <p className="text-muted-foreground/80 mt-0.5 line-clamp-2 text-xs italic">
+                            {entry.note}
+                          </p>
+                        )}
                       </TableCell>
                       <TableCell className="text-muted-foreground text-sm">
                         {formatDateTime(entry.moodLoggedAt)}
@@ -467,6 +495,11 @@ export function MoodList({ onAddFirst }: MoodListProps = {}) {
                           {entry.tags.join(", ")}
                         </p>
                       )}
+                      {entry.note && (
+                        <p className="text-muted-foreground/80 truncate text-xs italic">
+                          {entry.note}
+                        </p>
+                      )}
                     </div>
                   </div>
                   <div className="flex shrink-0 items-center gap-1">
@@ -603,6 +636,32 @@ export function MoodList({ onAddFirst }: MoodListProps = {}) {
                 />
               </div>
 
+              {/* v1.8.5 — structured-tag taxonomy picker. */}
+              <div className="space-y-2">
+                <Label>
+                  {t("mood.tagPicker")} ({t("common.optional")})
+                </Label>
+                <MoodTagPicker
+                  selected={editTagKeys}
+                  onToggle={toggleEditTagKey}
+                />
+              </div>
+
+              {/* v1.8.5 (C1) — free-text note. */}
+              <div className="space-y-2">
+                <Label htmlFor="edit-mood-note">
+                  {t("mood.note")} ({t("common.optional")})
+                </Label>
+                <Textarea
+                  id="edit-mood-note"
+                  value={editNote}
+                  onChange={(e) => setEditNote(e.target.value)}
+                  placeholder={t("mood.notePlaceholder")}
+                  maxLength={500}
+                  rows={3}
+                />
+              </div>
+
               {editError && (
                 <div
                   role="alert"
diff --git a/src/components/mood/mood-tag-icons.ts b/src/components/mood/mood-tag-icons.ts
new file mode 100644
index 000000000..1b8146ac9
--- /dev/null
+++ b/src/components/mood/mood-tag-icons.ts
@@ -0,0 +1,83 @@
+import {
+  AlertTriangle,
+  Apple,
+  BedDouble,
+  Brain,
+  Briefcase,
+  CheckCircle,
+  Clock,
+  CloudMoon,
+  CloudSun,
+  Dumbbell,
+  Flame,
+  Footprints,
+  Frown,
+  GlassWater,
+  HandHeart,
+  Heart,
+  HeartPulse,
+  HelpCircle,
+  Home,
+  LogOut,
+  Meh,
+  Moon,
+  MoonStar,
+  PartyPopper,
+  Plane,
+  Smile,
+  Tag,
+  Thermometer,
+  ThumbsUp,
+  User,
+  Users,
+  Wine,
+  Zap,
+  type LucideIcon,
+} from "lucide-react";
+
+/**
+ * v1.8.5 — icon-name → Lucide component map for the structured mood-tag
+ * taxonomy. The catalog stores Lucide icon names as strings (so the
+ * server stays icon-library-agnostic); this map resolves them on the
+ * client. Mirrors the static-map convention used by the workout / sport
+ * icon lookups. `Tag` is the fallback for an unmapped name.
+ */
+const MOOD_TAG_ICONS: Record<string, LucideIcon> = {
+  AlertTriangle,
+  Apple,
+  BedDouble,
+  Brain,
+  Briefcase,
+  CheckCircle,
+  Clock,
+  CloudMoon,
+  CloudSun,
+  Dumbbell,
+  Flame,
+  Footprints,
+  Frown,
+  GlassWater,
+  HandHeart,
+  Heart,
+  HeartPulse,
+  HelpCircle,
+  Home,
+  LogOut,
+  Meh,
+  Moon,
+  MoonStar,
+  PartyPopper,
+  Plane,
+  Smile,
+  Thermometer,
+  ThumbsUp,
+  User,
+  Users,
+  Wine,
+  Zap,
+};
+
+export function moodTagIcon(name: string | null | undefined): LucideIcon {
+  if (!name) return Tag;
+  return MOOD_TAG_ICONS[name] ?? Tag;
+}
diff --git a/src/components/mood/mood-tag-picker.tsx b/src/components/mood/mood-tag-picker.tsx
new file mode 100644
index 000000000..76dbae0ec
--- /dev/null
+++ b/src/components/mood/mood-tag-picker.tsx
@@ -0,0 +1,112 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+
+import { Skeleton } from "@/components/ui/skeleton";
+import { useAuth } from "@/hooks/use-auth";
+import { queryKeys } from "@/lib/query-keys";
+import { useTranslations } from "@/lib/i18n/context";
+import { moodTagIcon } from "./mood-tag-icons";
+
+/**
+ * v1.8.5 — structured mood-tag capture surface.
+ *
+ * Loads the global Category -> Tag catalog from `/api/mood/tags` and
+ * renders one labelled group per category with icon chips the user can
+ * toggle. Selection is a controlled set of tag keys lifted to the
+ * parent form, which sends them as `tagKeys` on create / update.
+ *
+ * Additive next to the legacy free-text tag input: a user can use
+ * either or both. Renders nothing if the catalog is empty so a
+ * deployment that cleared the taxonomy degrades to the free-text field.
+ */
+
+interface CatalogTag {
+  key: string;
+  labelKey: string;
+  icon: string | null;
+}
+
+interface CatalogCategory {
+  key: string;
+  labelKey: string;
+  icon: string | null;
+  tags: CatalogTag[];
+}
+
+interface CatalogResponse {
+  categories: CatalogCategory[];
+}
+
+export function MoodTagPicker({
+  selected,
+  onToggle,
+}: {
+  selected: string[];
+  onToggle: (tagKey: string) => void;
+}) {
+  const { isAuthenticated } = useAuth();
+  const { t } = useTranslations();
+
+  const { data, isLoading } = useQuery({
+    queryKey: queryKeys.moodTagCatalog(),
+    queryFn: async () => {
+      const res = await fetch("/api/mood/tags");
+      if (!res.ok) throw new Error("Failed");
+      const json = await res.json();
+      return json.data as CatalogResponse;
+    },
+    enabled: isAuthenticated,
+    // The catalog only changes on a migration / admin edit.
+    staleTime: 60 * 60 * 1000,
+  });
+
+  if (isLoading) {
+    return <Skeleton className="h-24 w-full rounded-lg" />;
+  }
+
+  if (!data || data.categories.length === 0) {
+    return null;
+  }
+
+  const selectedSet = new Set(selected);
+
+  return (
+    <div className="space-y-3" data-slot="mood-tag-picker">
+      {data.categories.map((category) => {
+        const CategoryIcon = moodTagIcon(category.icon);
+        return (
+          <div key={category.key} className="space-y-1.5">
+            <div className="text-muted-foreground flex items-center gap-1.5 text-xs font-medium">
+              <CategoryIcon className="h-3.5 w-3.5" aria-hidden="true" />
+              <span>{t(category.labelKey)}</span>
+            </div>
+            <div className="flex flex-wrap gap-1.5">
+              {category.tags.map((tag) => {
+                const TagIcon = moodTagIcon(tag.icon);
+                const isActive = selectedSet.has(tag.key);
+                const label = t(tag.labelKey);
+                return (
+                  <button
+                    key={tag.key}
+                    type="button"
+                    onClick={() => onToggle(tag.key)}
+                    aria-pressed={isActive}
+                    className={`inline-flex min-h-8 items-center gap-1.5 rounded-full border px-2.5 py-1 text-xs transition-colors ${
+                      isActive
+                        ? "border-primary bg-primary/15 text-primary"
+                        : "border-border/70 bg-muted text-foreground/75 hover:bg-accent hover:text-foreground"
+                    }`}
+                  >
+                    <TagIcon className="h-3.5 w-3.5" aria-hidden="true" />
+                    {label}
+                  </button>
+                );
+              })}
+            </div>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/src/lib/insights/__tests__/mood-aggregates.test.ts b/src/lib/insights/__tests__/mood-aggregates.test.ts
index 8c4b3cd1a..b8408320d 100644
--- a/src/lib/insights/__tests__/mood-aggregates.test.ts
+++ b/src/lib/insights/__tests__/mood-aggregates.test.ts
@@ -6,11 +6,14 @@ import {
   computeInTargetPct,
   computeMoodAggregates,
   computeMoodMetricCorrelation,
+  computeNotesTimeline,
+  computeStructuredTagSummary,
   computeTagSummary,
   computeWeekdayAverages,
   selectHeatmapWindow,
   type CrossMetricMeasurement,
   type MoodAggregateEntry,
+  type StructuredTagRef,
 } from "../mood-aggregates";
 
 const dayMs = 24 * 60 * 60 * 1000;
@@ -78,6 +81,79 @@ describe("computeTagSummary", () => {
   });
 });
 
+describe("computeStructuredTagSummary", () => {
+  function entryWithStructured(
+    offset: number,
+    score: number,
+    structuredTags: StructuredTagRef[],
+  ): MoodAggregateEntry {
+    return { ...entry(offset, score, null), structuredTags };
+  }
+
+  it("ranks structured tags by frequency, keeps singletons, and groups by category", () => {
+    const entries: MoodAggregateEntry[] = [
+      entryWithStructured(1, 5, [
+        { key: "happy", categoryKey: "feelings", labelKey: "mood.tag.happy", icon: "Smile" },
+        { key: "worked_out", categoryKey: "health", labelKey: "mood.tag.workedOut", icon: "Dumbbell" },
+      ]),
+      entryWithStructured(2, 3, [
+        { key: "happy", categoryKey: "feelings", labelKey: "mood.tag.happy", icon: "Smile" },
+      ]),
+      entryWithStructured(3, 1, [
+        { key: "stressed", categoryKey: "feelings", labelKey: "mood.tag.stressed", icon: "Brain" },
+      ]),
+    ];
+    const rows = computeStructuredTagSummary(entries, NOW);
+    const happy = rows.find((r) => r.key === "happy");
+    expect(happy).toEqual({
+      key: "happy",
+      categoryKey: "feelings",
+      labelKey: "mood.tag.happy",
+      icon: "Smile",
+      count: 2,
+      avgScore: 4,
+    });
+    // singletons are kept for the structured breakdown (curated catalog,
+    // not noisy free text).
+    expect(rows.find((r) => r.key === "stressed")?.count).toBe(1);
+    expect(rows.find((r) => r.key === "worked_out")?.categoryKey).toBe("health");
+    // ranked by frequency desc.
+    expect(rows[0].key).toBe("happy");
+  });
+
+  it("excludes entries older than the window and ignores entries without structured tags", () => {
+    const entries: MoodAggregateEntry[] = [
+      entryWithStructured(1, 5, [
+        { key: "happy", categoryKey: "feelings", labelKey: "mood.tag.happy", icon: "Smile" },
+      ]),
+      entryWithStructured(200, 5, [
+        { key: "sad", categoryKey: "feelings", labelKey: "mood.tag.sad", icon: "Frown" },
+      ]),
+      entry(2, 4, ["flat-only"]), // no structuredTags → ignored here
+    ];
+    const rows = computeStructuredTagSummary(entries, NOW, 90);
+    expect(rows.map((r) => r.key)).toEqual(["happy"]);
+  });
+});
+
+describe("computeNotesTimeline", () => {
+  it("returns noted entries newest-first, skips empty notes, and caps at the limit", () => {
+    const entries: MoodAggregateEntry[] = [
+      { ...entry(5, 2, ["x"]), note: "oldest", mood: "SCHLECHT" },
+      { ...entry(3, 4, null), note: "   ", mood: "GUT" }, // blank → skipped
+      { ...entry(2, 5, null), note: "middle", mood: "SUPER_GUT" },
+      { ...entry(1, 3, null), note: "newest", mood: "OKAY" },
+    ];
+    const timeline = computeNotesTimeline(entries, 2);
+    expect(timeline.map((n) => n.note)).toEqual(["newest", "middle"]);
+    expect(timeline[0]).toMatchObject({ score: 3, mood: "OKAY", note: "newest" });
+  });
+
+  it("returns an empty array when no entry carries a note", () => {
+    expect(computeNotesTimeline([entry(1, 4, ["x"])])).toEqual([]);
+  });
+});
+
 describe("computeInTargetPct", () => {
   it("returns the share of the newest 30 daily buckets in the green band", () => {
     const daily = [
diff --git a/src/lib/insights/mood-aggregates.ts b/src/lib/insights/mood-aggregates.ts
index 76de65865..1a7f746d6 100644
--- a/src/lib/insights/mood-aggregates.ts
+++ b/src/lib/insights/mood-aggregates.ts
@@ -28,6 +28,24 @@ import { round, summarizeSeries } from "@/lib/insights/status-shared";
 
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
 
+/**
+ * Parse the flat `MoodEntry.tags` JSON string into a string array. The
+ * column stores a JSON-encoded array (or null); the read path must
+ * decode it before `computeTagSummary`'s `Array.isArray` check, otherwise
+ * the flat-tag axis silently collapses to empty (the raw string is never
+ * an array). Defensive against malformed JSON — returns `[]` on a parse
+ * failure rather than throwing.
+ */
+function parseTags(tags: string | null): string[] {
+  if (!tags) return [];
+  try {
+    const parsed = JSON.parse(tags);
+    return Array.isArray(parsed) ? (parsed as string[]) : [];
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Minimal daily-bucket shape the aggregates read. `DailyBucket` (from
  * `bucket-series`) carries an extra `n` field; the helpers only ever
@@ -36,6 +54,23 @@ const MS_PER_DAY = 24 * 60 * 60 * 1000;
  */
 type DailyPoint = Pick<DailyBucket, "dayOffset" | "value">;
 
+/**
+ * A structured tag attached to a mood entry, resolved from the catalog
+ * (`mood_tags` + its parent `mood_tag_categories`) via the
+ * `mood_entry_tag_links` join. Carried alongside the legacy flat `tags`
+ * string so the breakdown can surface both axes.
+ */
+export interface StructuredTagRef {
+  /** Stable tag key (e.g. `happy`). */
+  key: string;
+  /** Parent category key (e.g. `feelings`). */
+  categoryKey: string;
+  /** i18n message key for the tag label. */
+  labelKey: string;
+  /** Lucide icon name, or null. */
+  icon: string | null;
+}
+
 /** Raw mood row shape the aggregates operate on. */
 export interface MoodAggregateEntry {
   /** TZ-anchored day key (YYYY-MM-DD). */
@@ -46,6 +81,59 @@ export interface MoodAggregateEntry {
   tags: unknown;
   /** Exact log timestamp — carries time-of-day. */
   moodLoggedAt: Date;
+  /**
+   * v1.8.5 — structured tags from the taxonomy join. Additive next to
+   * the flat `tags`: an entry can carry both. Optional so the legacy
+   * aggregate tests (flat tags only) keep their narrow fixtures.
+   */
+  structuredTags?: StructuredTagRef[];
+  /** v1.8.5 — free-text note (C1). */
+  note?: string | null;
+  /** Mood enum (for the notes timeline label / colour). */
+  mood?: string;
+}
+
+// --- Notes timeline (v1.8.5 C1 — qualitative reflection feed) ---
+
+export interface NoteTimelineEntry {
+  /** TZ-anchored day key. */
+  date: string;
+  /** ISO timestamp of the log. */
+  loggedAt: string;
+  score: number;
+  mood: string | null;
+  note: string;
+  /** Flat free-text tags on the entry. */
+  tags: string[];
+  /** Structured-tag labels (i18n keys) on the entry. */
+  structuredTagLabelKeys: string[];
+}
+
+/**
+ * Recent entries that carry a free-text note, newest first. Bounded to
+ * `limit` so the cached aggregate payload stays small. Entries without a
+ * note are skipped — the timeline is the qualitative-reflection feed.
+ */
+export function computeNotesTimeline(
+  entries: MoodAggregateEntry[],
+  limit = 20,
+): NoteTimelineEntry[] {
+  return entries
+    .filter((entry) => typeof entry.note === "string" && entry.note.trim())
+    .slice()
+    .reverse() // entries arrive oldest-first; show newest first
+    .slice(0, limit)
+    .map((entry) => ({
+      date: entry.date,
+      loggedAt: entry.moodLoggedAt.toISOString(),
+      score: entry.score,
+      mood: entry.mood ?? null,
+      note: entry.note!.trim(),
+      tags: Array.isArray(entry.tags) ? (entry.tags as string[]) : [],
+      structuredTagLabelKeys: (entry.structuredTags ?? []).map(
+        (tag) => tag.labelKey,
+      ),
+    }));
 }
 
 /** Cross-metric row shape (WEIGHT / BLOOD_PRESSURE_SYS / PULSE / …). */
@@ -147,6 +235,71 @@ export function computeTagSummary(
     }));
 }
 
+// --- Structured-tag frequency + per-tag avg score (v1.8.5 taxonomy) ---
+
+export interface StructuredTagRow {
+  key: string;
+  categoryKey: string;
+  labelKey: string;
+  icon: string | null;
+  count: number;
+  avgScore: number;
+}
+
+/**
+ * Frequency + per-tag average mood for the structured taxonomy tags,
+ * over the same recency window as the flat-tag summary.
+ *
+ * Unlike `computeTagSummary` (flat free text), singletons are KEPT — a
+ * structured tag comes from a curated catalog the user deliberately
+ * picked, so a single occurrence is signal, not noise. Ranked by
+ * frequency desc, then label key for a stable order. The category key
+ * rides along so the UI can group the bars by category with icons.
+ */
+export function computeStructuredTagSummary(
+  entries: MoodAggregateEntry[],
+  now: Date,
+  windowDays = 90,
+): StructuredTagRow[] {
+  const cutoff = now.getTime() - windowDays * MS_PER_DAY;
+  const byKey = new Map<
+    string,
+    {
+      categoryKey: string;
+      labelKey: string;
+      icon: string | null;
+      count: number;
+      scoreSum: number;
+    }
+  >();
+  for (const entry of entries) {
+    if (entry.moodLoggedAt.getTime() < cutoff) continue;
+    if (!entry.structuredTags) continue;
+    for (const tag of entry.structuredTags) {
+      const current = byKey.get(tag.key) ?? {
+        categoryKey: tag.categoryKey,
+        labelKey: tag.labelKey,
+        icon: tag.icon,
+        count: 0,
+        scoreSum: 0,
+      };
+      current.count += 1;
+      current.scoreSum += entry.score;
+      byKey.set(tag.key, current);
+    }
+  }
+  return Array.from(byKey.entries())
+    .map(([key, stats]) => ({
+      key,
+      categoryKey: stats.categoryKey,
+      labelKey: stats.labelKey,
+      icon: stats.icon,
+      count: stats.count,
+      avgScore: round(stats.scoreSum / stats.count, 2),
+    }))
+    .sort((a, b) => b.count - a.count || a.labelKey.localeCompare(b.labelKey));
+}
+
 // --- In-target % over the last 30 daily points (lifted from mood-status) ---
 
 /**
@@ -346,6 +499,10 @@ export interface MoodAggregates {
   distribution: DistributionRow[];
   weekday: WeekdayRow[];
   tags: TagSummaryRow[];
+  /** v1.8.5 — structured-tag breakdown from the taxonomy join. */
+  structuredTags: StructuredTagRow[];
+  /** v1.8.5 — recent notes timeline (qualitative-reflection feed). */
+  notesTimeline: NoteTimelineEntry[];
   correlations: {
     sleep: MoodMetricCorrelation;
     steps: MoodMetricCorrelation;
@@ -424,6 +581,8 @@ export function computeMoodAggregates(args: {
     distribution: computeDistribution(moodDaily),
     weekday: computeWeekdayAverages(moodDaily, now),
     tags: computeTagSummary(entries, now),
+    structuredTags: computeStructuredTagSummary(entries, now),
+    notesTimeline: computeNotesTimeline(entries),
     correlations: {
       sleep: computeMoodMetricCorrelation(
         moodDaily,
@@ -473,9 +632,45 @@ export async function fetchMoodAggregates(
       where: { userId, deletedAt: null, moodLoggedAt: { gte: windowCutoff } },
       orderBy: { moodLoggedAt: "desc" },
       take: 2000,
-      select: { date: true, score: true, tags: true, moodLoggedAt: true },
+      select: {
+        date: true,
+        score: true,
+        tags: true,
+        moodLoggedAt: true,
+        mood: true,
+        note: true,
+        // v1.8.5 — pull the structured-tag links + their catalog rows so
+        // the breakdown can fold structured tags next to the flat ones.
+        tagLinks: {
+          select: {
+            moodTag: {
+              select: {
+                key: true,
+                labelKey: true,
+                icon: true,
+                category: { select: { key: true } },
+              },
+            },
+          },
+        },
+      },
     })
-    .then((rows) => rows.reverse());
+    .then((rows) =>
+      rows.reverse().map((row) => ({
+        date: row.date,
+        score: row.score,
+        tags: parseTags(row.tags),
+        moodLoggedAt: row.moodLoggedAt,
+        mood: row.mood,
+        note: row.note,
+        structuredTags: row.tagLinks.map((link) => ({
+          key: link.moodTag.key,
+          categoryKey: link.moodTag.category.key,
+          labelKey: link.moodTag.labelKey,
+          icon: link.moodTag.icon,
+        })),
+      })),
+    );
 
   const measurements = await prisma.measurement
     .findMany({
diff --git a/src/lib/mood/tag-links.ts b/src/lib/mood/tag-links.ts
new file mode 100644
index 000000000..ad6006d36
--- /dev/null
+++ b/src/lib/mood/tag-links.ts
@@ -0,0 +1,73 @@
+import { prisma } from "@/lib/db";
+
+/**
+ * v1.8.5 — structured-tag link helpers.
+ *
+ * Resolve a list of catalog tag keys (`mood_tags.key`) to their ids and
+ * write the `mood_entry_tag_links` join for a mood entry. The catalog is
+ * the source of truth: unknown keys are dropped silently so a stale
+ * client can never mint a link to a tag the deployment doesn't carry.
+ */
+
+/**
+ * Resolve catalog tag keys to ids, dropping unknown / inactive keys.
+ * Returns the ids in catalog order (deduped).
+ */
+export async function resolveTagKeysToIds(keys: string[]): Promise<string[]> {
+  const unique = Array.from(new Set(keys));
+  if (unique.length === 0) return [];
+  const rows = await prisma.moodTag.findMany({
+    where: { key: { in: unique }, isActive: true },
+    select: { id: true },
+  });
+  return rows.map((row) => row.id);
+}
+
+/**
+ * Create the structured-tag links for a freshly-created entry. No-op on
+ * an empty / all-unknown key set.
+ */
+export async function createTagLinks(
+  moodEntryId: string,
+  keys: string[],
+): Promise<void> {
+  const tagIds = await resolveTagKeysToIds(keys);
+  if (tagIds.length === 0) return;
+  await prisma.moodEntryTagLink.createMany({
+    data: tagIds.map((moodTagId) => ({ moodEntryId, moodTagId })),
+    skipDuplicates: true,
+  });
+}
+
+/**
+ * Replace the full structured-tag link set for an entry. `keys` is the
+ * desired set; the helper deletes links no longer present and inserts
+ * the new ones, leaving unchanged links in place. Passing an empty array
+ * clears every link.
+ */
+export async function replaceTagLinks(
+  moodEntryId: string,
+  keys: string[],
+): Promise<void> {
+  const desiredIds = new Set(await resolveTagKeysToIds(keys));
+  const existing = await prisma.moodEntryTagLink.findMany({
+    where: { moodEntryId },
+    select: { moodTagId: true },
+  });
+  const existingIds = new Set(existing.map((row) => row.moodTagId));
+
+  const toDelete = [...existingIds].filter((id) => !desiredIds.has(id));
+  const toCreate = [...desiredIds].filter((id) => !existingIds.has(id));
+
+  if (toDelete.length > 0) {
+    await prisma.moodEntryTagLink.deleteMany({
+      where: { moodEntryId, moodTagId: { in: toDelete } },
+    });
+  }
+  if (toCreate.length > 0) {
+    await prisma.moodEntryTagLink.createMany({
+      data: toCreate.map((moodTagId) => ({ moodEntryId, moodTagId })),
+      skipDuplicates: true,
+    });
+  }
+}
diff --git a/src/lib/mood/tag-taxonomy.ts b/src/lib/mood/tag-taxonomy.ts
new file mode 100644
index 000000000..15c1fc0dc
--- /dev/null
+++ b/src/lib/mood/tag-taxonomy.ts
@@ -0,0 +1,113 @@
+/**
+ * v1.8.5 — default mood-tag taxonomy.
+ *
+ * The canonical Category → Tag catalog seeded into `mood_tag_categories`
+ * + `mood_tags` by migration `0101_v185_mood_tag_taxonomy`. Modelled on
+ * the standalone mood diary's structured taxonomy but keyed on i18n
+ * message keys (resolved against all six locales) rather than hard-coded
+ * labels, so the catalog renders localised everywhere.
+ *
+ * The ids are deterministic string literals so the migration seed is
+ * idempotent (re-running upserts by `key`) and so the catalog rows are
+ * stable across deployments. Keys are stable machine identifiers; the
+ * `labelKey` is the i18n key the capture UI + breakdown resolve.
+ *
+ * This is purely additive next to the legacy flat `MoodEntry.tags` JSON
+ * column — the structured taxonomy is a second capture surface, not a
+ * replacement.
+ */
+
+export interface MoodTagSeed {
+  /** Stable machine key, unique across the catalog. */
+  key: string;
+  /** i18n message key `mood.tag.<key>`. */
+  labelKey: string;
+  /** Lucide icon name. */
+  icon: string;
+}
+
+export interface MoodTagCategorySeed {
+  key: string;
+  /** i18n message key `mood.tagCategory.<key>`. */
+  labelKey: string;
+  /** Lucide icon name for the category header. */
+  icon: string;
+  tags: MoodTagSeed[];
+}
+
+/**
+ * The seeded taxonomy. Order within the arrays is the `sortOrder` used
+ * for the catalog rows (category index, tag index within its category).
+ */
+export const MOOD_TAG_TAXONOMY: MoodTagCategorySeed[] = [
+  {
+    key: "feelings",
+    labelKey: "mood.tagCategory.feelings",
+    icon: "Heart",
+    tags: [
+      { key: "happy", labelKey: "mood.tag.happy", icon: "Smile" },
+      { key: "excited", labelKey: "mood.tag.excited", icon: "Zap" },
+      { key: "grateful", labelKey: "mood.tag.grateful", icon: "HandHeart" },
+      { key: "relaxed", labelKey: "mood.tag.relaxed", icon: "CloudSun" },
+      { key: "content", labelKey: "mood.tag.content", icon: "ThumbsUp" },
+      { key: "tired", labelKey: "mood.tag.tired", icon: "Moon" },
+      { key: "unsure", labelKey: "mood.tag.unsure", icon: "HelpCircle" },
+      { key: "bored", labelKey: "mood.tag.bored", icon: "Meh" },
+      { key: "tense", labelKey: "mood.tag.tense", icon: "AlertTriangle" },
+      { key: "angry", labelKey: "mood.tag.angry", icon: "Flame" },
+      { key: "stressed", labelKey: "mood.tag.stressed", icon: "Brain" },
+      { key: "sad", labelKey: "mood.tag.sad", icon: "Frown" },
+    ],
+  },
+  {
+    key: "sleep",
+    labelKey: "mood.tagCategory.sleep",
+    icon: "BedDouble",
+    tags: [
+      { key: "slept_well", labelKey: "mood.tag.sleptWell", icon: "Moon" },
+      { key: "slept_ok", labelKey: "mood.tag.sleptOk", icon: "CloudMoon" },
+      { key: "slept_poorly", labelKey: "mood.tag.sleptPoorly", icon: "MoonStar" },
+      { key: "early_night", labelKey: "mood.tag.earlyNight", icon: "Clock" },
+    ],
+  },
+  {
+    key: "health",
+    labelKey: "mood.tagCategory.health",
+    icon: "HeartPulse",
+    tags: [
+      { key: "worked_out", labelKey: "mood.tag.workedOut", icon: "Dumbbell" },
+      { key: "ate_well", labelKey: "mood.tag.ateWell", icon: "Apple" },
+      { key: "hydrated", labelKey: "mood.tag.hydrated", icon: "GlassWater" },
+      { key: "walked", labelKey: "mood.tag.walked", icon: "Footprints" },
+      { key: "alcohol", labelKey: "mood.tag.alcohol", icon: "Wine" },
+    ],
+  },
+  {
+    key: "social",
+    labelKey: "mood.tagCategory.social",
+    icon: "Users",
+    tags: [
+      { key: "family", labelKey: "mood.tag.family", icon: "Home" },
+      { key: "friends", labelKey: "mood.tag.friends", icon: "Users" },
+      { key: "party", labelKey: "mood.tag.party", icon: "PartyPopper" },
+      { key: "alone", labelKey: "mood.tag.alone", icon: "User" },
+    ],
+  },
+  {
+    key: "work",
+    labelKey: "mood.tagCategory.work",
+    icon: "Briefcase",
+    tags: [
+      { key: "productive", labelKey: "mood.tag.productive", icon: "CheckCircle" },
+      { key: "overtime", labelKey: "mood.tag.overtime", icon: "Clock" },
+      { key: "day_off", labelKey: "mood.tag.dayOff", icon: "LogOut" },
+      { key: "travel", labelKey: "mood.tag.travel", icon: "Plane" },
+      { key: "sick_day", labelKey: "mood.tag.sickDay", icon: "Thermometer" },
+    ],
+  },
+];
+
+/** Flat list of every seeded tag key (for validation / lookups). */
+export const MOOD_TAG_KEYS: string[] = MOOD_TAG_TAXONOMY.flatMap((c) =>
+  c.tags.map((tagSeed) => tagSeed.key),
+);
diff --git a/src/lib/query-keys.ts b/src/lib/query-keys.ts
index f75f6149b..cd302d53f 100644
--- a/src/lib/query-keys.ts
+++ b/src/lib/query-keys.ts
@@ -60,6 +60,14 @@ export const queryKeys = {
    * `moodDependentKeys` fan-out below.
    */
   moodInsights: () => ["mood-insights"] as const,
+  /**
+   * v1.8.5 — structured mood-tag taxonomy catalog (global reference
+   * data, identical for every user). Read by the mood-logging form's
+   * tag-category capture surface. Not invalidated on a mood write — the
+   * catalog only changes on a migration / admin edit, so a long
+   * `staleTime` is fine.
+   */
+  moodTagCatalog: () => ["mood-tag-catalog"] as const,
 
   /**
    * v1.7.0 W6 — unified dashboard first-paint snapshot. One client cell
diff --git a/src/lib/validations/__tests__/moodlog.test.ts b/src/lib/validations/__tests__/moodlog.test.ts
index c7a812de0..06ed3d078 100644
--- a/src/lib/validations/__tests__/moodlog.test.ts
+++ b/src/lib/validations/__tests__/moodlog.test.ts
@@ -1,5 +1,50 @@
 import { describe, expect, it } from "vitest";
-import { moodLogCredentialsSchema } from "../moodlog";
+import {
+  moodLogCredentialsSchema,
+  createMoodEntrySchema,
+  updateMoodEntrySchema,
+} from "../moodlog";
+
+describe("createMoodEntrySchema — note + structured tagKeys (v1.8.5)", () => {
+  const base = { mood: "GUT", moodLoggedAt: "2026-06-01T12:00:00.000Z" };
+
+  it("round-trips the note field", () => {
+    const r = createMoodEntrySchema.safeParse({ ...base, note: "felt great" });
+    expect(r.success).toBe(true);
+    if (r.success) expect(r.data.note).toBe("felt great");
+  });
+
+  it("accepts structured tagKeys alongside flat tags", () => {
+    const r = createMoodEntrySchema.safeParse({
+      ...base,
+      tags: ["nausea"],
+      tagKeys: ["happy", "worked_out"],
+    });
+    expect(r.success).toBe(true);
+    if (r.success) {
+      expect(r.data.tagKeys).toEqual(["happy", "worked_out"]);
+      expect(r.data.tags).toEqual(["nausea"]);
+    }
+  });
+
+  it("rejects an over-long note and an over-large tagKeys set", () => {
+    expect(
+      createMoodEntrySchema.safeParse({ ...base, note: "x".repeat(501) }).success,
+    ).toBe(false);
+    expect(
+      createMoodEntrySchema.safeParse({
+        ...base,
+        tagKeys: Array.from({ length: 31 }, (_, i) => `t${i}`),
+      }).success,
+    ).toBe(false);
+  });
+
+  it("allows update to clear tagKeys with null", () => {
+    const r = updateMoodEntrySchema.safeParse({ tagKeys: null });
+    expect(r.success).toBe(true);
+    if (r.success) expect(r.data.tagKeys).toBeNull();
+  });
+});
 
 describe("moodLogCredentialsSchema SSRF guard", () => {
   it("accepts a public moodLog URL", () => {
diff --git a/src/lib/validations/moodlog.ts b/src/lib/validations/moodlog.ts
index a6c018acd..54f9dbd81 100644
--- a/src/lib/validations/moodlog.ts
+++ b/src/lib/validations/moodlog.ts
@@ -78,9 +78,19 @@ export function getScoreForMood(mood: string): number {
   return MOOD_SCORE_MAP[mood] ?? 3;
 }
 
+// v1.8.5 — structured-tag keys picked from the catalog (`mood_tags.key`).
+// Additive alongside the flat free-text `tags`: an entry can carry both.
+// Bounded so a single create can't fan out an unbounded link set.
+const structuredTagKeys = z.array(z.string().max(60)).max(30);
+
 export const createMoodEntrySchema = z.object({
   mood: moodLevelEnum,
   tags: z.array(z.string().max(50)).max(20).optional(),
+  // v1.8.5 — structured-tag keys from the taxonomy. Server resolves each
+  // key to a `MoodTag` row and writes the `MoodEntryTagLink` join;
+  // unknown keys are dropped silently (the catalog is the source of
+  // truth, a stale client can't mint a tag).
+  tagKeys: structuredTagKeys.optional(),
   // v1.4.30 H-5 — first-class free-text note. Replaces the
   // `tags: ["note:<text>"]` workaround. Capped at 500 chars so the
   // Coach evidence shelf renders cleanly without truncating chips.
@@ -92,6 +102,9 @@ export const createMoodEntrySchema = z.object({
 export const updateMoodEntrySchema = z.object({
   mood: moodLevelEnum.optional(),
   tags: z.array(z.string().max(50)).max(20).nullable().optional(),
+  // v1.8.5 — full replacement of the structured-tag set when present.
+  // `null` clears every link; omit to leave links untouched.
+  tagKeys: structuredTagKeys.nullable().optional(),
   note: z.string().max(500).nullable().optional(),
   moodLoggedAt: z.iso
     .datetime({ offset: true })

From 6ce09cc76da7dad5c6e31f1f8d1eaf8685b0eda8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 20:15:25 +0200
Subject: [PATCH 10/30] feat(insights): stat strip, range band, all-readings
 subpage, diversity nudge
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add the data-value features to the insights category pages on top of the
density pass:

- Stat strip: lead each metric page with min / max / median / mean,
  read from the already-fetched analytics summaries slice (no new
  network). Median is now computed in both summary producers — exact in
  the live path, a windowed PERCENTILE_CONT in the rollup-tier slim
  slice. The thin HealthKit pages mount it too for parity; no AI
  assessment is added there.
- Range band: shade an Apple-Health-style min-max area around the daily
  mean line where the data supports it (non-cumulative metrics). The
  daily-aggregate read now emits per-day min / max from the rollup
  buckets; the band rides the existing target-range toggle.
- All readings: a dedicated per-metric subpage at /insights/values/<type>
  reusing the measurement list pinned to one type (pagination + inline
  edit/delete). A clear entry button mounts at the foot of each
  category page.
- Diversity nudge: a gentle hint when a metric's readings cluster on one
  weekday or time of day, computed from a bounded, cached timestamp
  window — non-blocking, self-gating.

All new reads stay cache-friendly and off the navigation path.
---
 e2e/utils/mock-dashboard-snapshot.ts          |   1 +
 messages/de.json                              |  20 ++-
 messages/en.json                              |  20 ++-
 messages/es.json                              |  20 ++-
 messages/fr.json                              |  20 ++-
 messages/it.json                              |  20 ++-
 messages/pl.json                              |  20 ++-
 src/app/api/measurements/route.ts             |  11 ++
 src/app/insights/pulse/page.tsx               |  16 +++
 src/app/insights/values/[type]/page.tsx       |  67 ++++++++++
 src/app/insights/weight/page.tsx              |  14 +-
 src/components/charts/health-chart.tsx        |  82 +++++++++++-
 .../insights-tab-strip-memo.test.tsx          |   1 +
 .../__tests__/insights-tab-strip.test.tsx     |   1 +
 .../__tests__/metric-stat-strip.test.tsx      |  81 ++++++++++++
 .../__tests__/vo2-max-chart-row.test.tsx      |   2 +
 .../insights/healthkit-metric-page.tsx        |  32 ++++-
 .../insights/measurement-diversity-nudge.tsx  |  92 +++++++++++++
 src/components/insights/metric-stat-strip.tsx |  98 ++++++++++++++
 src/components/insights/sub-page-shell.tsx    |  49 +++++++
 .../measurement-list-locked-type.test.tsx     |  79 +++++++++++
 .../measurements/measurement-list.tsx         |  68 +++++++---
 .../__tests__/merge-slim-thick.test.ts        |   1 +
 .../__tests__/summaries-slice.test.ts         |   5 +
 src/lib/analytics/__tests__/trends.test.ts    |  24 ++++
 src/lib/analytics/summaries-slice.ts          |  23 ++++
 src/lib/analytics/trends.ts                   |  22 +++
 .../__tests__/measurement-diversity.test.ts   |  65 +++++++++
 .../__tests__/metric-availability.test.ts     |   1 +
 src/lib/insights/comprehensive-aggregator.ts  |   8 ++
 src/lib/insights/measurement-diversity.ts     | 125 ++++++++++++++++++
 src/lib/query-keys.ts                         |  12 ++
 32 files changed, 1063 insertions(+), 37 deletions(-)
 create mode 100644 src/app/insights/values/[type]/page.tsx
 create mode 100644 src/components/insights/__tests__/metric-stat-strip.test.tsx
 create mode 100644 src/components/insights/measurement-diversity-nudge.tsx
 create mode 100644 src/components/insights/metric-stat-strip.tsx
 create mode 100644 src/components/measurements/__tests__/measurement-list-locked-type.test.tsx
 create mode 100644 src/lib/insights/__tests__/measurement-diversity.test.ts
 create mode 100644 src/lib/insights/measurement-diversity.ts

diff --git a/e2e/utils/mock-dashboard-snapshot.ts b/e2e/utils/mock-dashboard-snapshot.ts
index 5bc9aa094..29043ee61 100644
--- a/e2e/utils/mock-dashboard-snapshot.ts
+++ b/e2e/utils/mock-dashboard-snapshot.ts
@@ -37,6 +37,7 @@ function summary(partial: Partial<DataSummary>): DataSummary {
     min: null,
     max: null,
     mean: null,
+    median: null,
     avg7: null,
     avg30: null,
     slope7: null,
diff --git a/messages/de.json b/messages/de.json
index f53fb4e6c..b77f2b496 100644
--- a/messages/de.json
+++ b/messages/de.json
@@ -1408,7 +1408,8 @@
       "fri": "Freitag",
       "sat": "Samstag",
       "sun": "Sonntag"
-    }
+    },
+    "rangeBand": "Bereich"
   },
   "chart": {
     "overlay": {
@@ -1956,7 +1957,22 @@
         "bloodGlucoseBody": "Der Blutzucker ist die Zuckermenge in deinem Blut, die wichtigste Energiequelle des Körpers. Er steigt nach dem Essen und pendelt sich zwischen den Mahlzeiten ein; dauerhaft hohe Werte können auf Diabetes oder Prädiabetes hinweisen.",
         "skinTemperatureTitle": "Hauttemperatur",
         "skinTemperatureBody": "Die Hauttemperatur ist hier die kleine nächtliche Abweichung deiner Handgelenkstemperatur von deinem eigenen Ausgangswert, keine absolute Fiebermessung. Veränderungen können Schlaf, Umgebung, Krankheit oder Zyklusphase widerspiegeln."
-      }
+      },
+      "stats": {
+        "label": "Zusammenfassende Statistik",
+        "min": "Min",
+        "max": "Max",
+        "median": "Median",
+        "mean": "Mittelwert"
+      },
+      "showAllValues": "Alle Werte anzeigen",
+      "valuesPageTitle": "{metric} — alle Werte",
+      "valuesPageDescription": "Jeder einzelne Wert hinter dieser Kennzahl. Einträge lassen sich direkt bearbeiten oder entfernen.",
+      "diversity": {
+        "weekday": "Die meisten deiner {metric}-Werte fallen auf einen Wochentag. Messungen an anderen Tagen ergeben ein vollständigeres Bild.",
+        "timeOfDay": "Die meisten deiner {metric}-Werte fallen auf eine ähnliche Tageszeit. Unterschiedliche Zeiten ergeben ein vollständigeres Bild."
+      },
+      "valuesBack": "Zurück zu Insights"
     },
     "sleep": {
       "title": "Schlaf",
diff --git a/messages/en.json b/messages/en.json
index f64dbe583..29888b6f3 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -1408,7 +1408,8 @@
       "fri": "Friday",
       "sat": "Saturday",
       "sun": "Sunday"
-    }
+    },
+    "rangeBand": "Range"
   },
   "chart": {
     "overlay": {
@@ -1956,7 +1957,22 @@
         "bloodGlucoseBody": "Blood glucose is the amount of sugar in your blood, the body's main energy source. It rises after eating and settles between meals; readings that stay high over time can signal diabetes or prediabetes.",
         "skinTemperatureTitle": "Skin temperature",
         "skinTemperatureBody": "Skin temperature here is the small nightly change in your wrist temperature from your own baseline, not an absolute fever reading. Shifts can track sleep, environment, illness, or menstrual-cycle phase."
-      }
+      },
+      "stats": {
+        "label": "Summary statistics",
+        "min": "Min",
+        "max": "Max",
+        "median": "Median",
+        "mean": "Mean"
+      },
+      "showAllValues": "Show all readings",
+      "valuesPageTitle": "{metric} — all readings",
+      "valuesPageDescription": "Every reading behind this metric. Edit or remove an entry directly.",
+      "diversity": {
+        "weekday": "Most of your {metric} readings land on one weekday. Logging on other days gives a fuller picture.",
+        "timeOfDay": "Most of your {metric} readings land at a similar time of day. Varying the time gives a fuller picture."
+      },
+      "valuesBack": "Back to insights"
     },
     "sleep": {
       "title": "Sleep",
diff --git a/messages/es.json b/messages/es.json
index 1c96e71c4..dfe8993b0 100644
--- a/messages/es.json
+++ b/messages/es.json
@@ -1408,7 +1408,8 @@
       "fri": "Viernes",
       "sat": "Sábado",
       "sun": "Domingo"
-    }
+    },
+    "rangeBand": "Rango"
   },
   "chart": {
     "overlay": {
@@ -1956,7 +1957,22 @@
         "bloodGlucoseBody": "La glucosa en sangre es la cantidad de azúcar en tu sangre, la principal fuente de energía del cuerpo. Sube tras comer y se estabiliza entre comidas; valores que se mantienen altos con el tiempo pueden indicar diabetes o prediabetes.",
         "skinTemperatureTitle": "Temperatura de la piel",
         "skinTemperatureBody": "La temperatura de la piel aquí es el pequeño cambio nocturno de la temperatura de tu muñeca respecto a tu propio valor de referencia, no una medición absoluta de fiebre. Las variaciones pueden seguir el sueño, el entorno, una enfermedad o la fase del ciclo menstrual."
-      }
+      },
+      "stats": {
+        "label": "Estadísticas resumidas",
+        "min": "Mín",
+        "max": "Máx",
+        "median": "Mediana",
+        "mean": "Media"
+      },
+      "showAllValues": "Mostrar todas las mediciones",
+      "valuesPageTitle": "{metric} — todas las mediciones",
+      "valuesPageDescription": "Cada medición detrás de esta métrica. Edita o elimina una entrada directamente.",
+      "diversity": {
+        "weekday": "La mayoría de tus mediciones de {metric} caen en un mismo día de la semana. Registrar en otros días ofrece una imagen más completa.",
+        "timeOfDay": "La mayoría de tus mediciones de {metric} caen a una hora similar del día. Variar la hora ofrece una imagen más completa."
+      },
+      "valuesBack": "Volver a Insights"
     },
     "sleep": {
       "title": "Sueño",
diff --git a/messages/fr.json b/messages/fr.json
index 8063ccc6f..7ae6e73a1 100644
--- a/messages/fr.json
+++ b/messages/fr.json
@@ -1408,7 +1408,8 @@
       "fri": "Vendredi",
       "sat": "Samedi",
       "sun": "Dimanche"
-    }
+    },
+    "rangeBand": "Plage"
   },
   "chart": {
     "overlay": {
@@ -1956,7 +1957,22 @@
         "bloodGlucoseBody": "La glycémie est la quantité de sucre dans votre sang, principale source d'énergie de l'organisme. Elle augmente après les repas et se stabilise entre eux ; des valeurs durablement élevées peuvent signaler un diabète ou un prédiabète.",
         "skinTemperatureTitle": "Température cutanée",
         "skinTemperatureBody": "La température cutanée correspond ici à la petite variation nocturne de la température de votre poignet par rapport à votre propre référence, et non à une mesure absolue de fièvre. Les variations peuvent suivre le sommeil, l'environnement, une maladie ou la phase du cycle menstruel."
-      }
+      },
+      "stats": {
+        "label": "Statistiques récapitulatives",
+        "min": "Min",
+        "max": "Max",
+        "median": "Médiane",
+        "mean": "Moyenne"
+      },
+      "showAllValues": "Afficher toutes les mesures",
+      "valuesPageTitle": "{metric} — toutes les mesures",
+      "valuesPageDescription": "Chaque mesure derrière cette métrique. Modifiez ou supprimez une entrée directement.",
+      "diversity": {
+        "weekday": "La plupart de vos mesures de {metric} tombent le même jour de la semaine. Enregistrer d'autres jours donne une image plus complète.",
+        "timeOfDay": "La plupart de vos mesures de {metric} tombent à une heure similaire de la journée. Varier l'heure donne une image plus complète."
+      },
+      "valuesBack": "Retour aux Insights"
     },
     "sleep": {
       "title": "Sommeil",
diff --git a/messages/it.json b/messages/it.json
index 2b00fb2b2..d290ac44f 100644
--- a/messages/it.json
+++ b/messages/it.json
@@ -1408,7 +1408,8 @@
       "fri": "Venerdì",
       "sat": "Sabato",
       "sun": "Domenica"
-    }
+    },
+    "rangeBand": "Intervallo"
   },
   "chart": {
     "overlay": {
@@ -1956,7 +1957,22 @@
         "bloodGlucoseBody": "La glicemia è la quantità di zucchero nel sangue, la principale fonte di energia del corpo. Sale dopo i pasti e si stabilizza tra un pasto e l'altro; valori che restano alti nel tempo possono indicare diabete o prediabete.",
         "skinTemperatureTitle": "Temperatura cutanea",
         "skinTemperatureBody": "La temperatura cutanea qui è la piccola variazione notturna della temperatura del polso rispetto al tuo valore di riferimento, non una misura assoluta della febbre. Le variazioni possono seguire sonno, ambiente, malattia o fase del ciclo mestruale."
-      }
+      },
+      "stats": {
+        "label": "Statistiche riepilogative",
+        "min": "Min",
+        "max": "Max",
+        "median": "Mediana",
+        "mean": "Media"
+      },
+      "showAllValues": "Mostra tutte le misurazioni",
+      "valuesPageTitle": "{metric} — tutte le misurazioni",
+      "valuesPageDescription": "Ogni misurazione dietro questa metrica. Modifica o rimuovi una voce direttamente.",
+      "diversity": {
+        "weekday": "La maggior parte delle tue misurazioni di {metric} cade in un solo giorno della settimana. Registrare in altri giorni offre un quadro più completo.",
+        "timeOfDay": "La maggior parte delle tue misurazioni di {metric} cade in un orario simile della giornata. Variare l'orario offre un quadro più completo."
+      },
+      "valuesBack": "Torna a Insights"
     },
     "sleep": {
       "title": "Sonno",
diff --git a/messages/pl.json b/messages/pl.json
index a34c6ad4e..c511d661f 100644
--- a/messages/pl.json
+++ b/messages/pl.json
@@ -1408,7 +1408,8 @@
       "fri": "Piątek",
       "sat": "Sobota",
       "sun": "Niedziela"
-    }
+    },
+    "rangeBand": "Zakres"
   },
   "chart": {
     "overlay": {
@@ -1956,7 +1957,22 @@
         "bloodGlucoseBody": "Poziom glukozy we krwi to ilość cukru we krwi, głównego źródła energii organizmu. Rośnie po jedzeniu i ustala się między posiłkami; wartości utrzymujące się wysoko mogą sygnalizować cukrzycę lub stan przedcukrzycowy.",
         "skinTemperatureTitle": "Temperatura skóry",
         "skinTemperatureBody": "Temperatura skóry to tutaj niewielka nocna zmiana temperatury nadgarstka względem twojej własnej wartości bazowej, a nie bezwzględny pomiar gorączki. Zmiany mogą odzwierciedlać sen, otoczenie, chorobę lub fazę cyklu menstruacyjnego."
-      }
+      },
+      "stats": {
+        "label": "Statystyki podsumowujące",
+        "min": "Min",
+        "max": "Maks",
+        "median": "Mediana",
+        "mean": "Średnia"
+      },
+      "showAllValues": "Pokaż wszystkie pomiary",
+      "valuesPageTitle": "{metric} — wszystkie pomiary",
+      "valuesPageDescription": "Każdy pomiar stojący za tą metryką. Edytuj lub usuń wpis bezpośrednio.",
+      "diversity": {
+        "weekday": "Większość Twoich pomiarów {metric} przypada na jeden dzień tygodnia. Pomiary w inne dni dają pełniejszy obraz.",
+        "timeOfDay": "Większość Twoich pomiarów {metric} przypada o podobnej porze dnia. Różne pory dają pełniejszy obraz."
+      },
+      "valuesBack": "Powrót do Insights"
     },
     "sleep": {
       "title": "Sen",
diff --git a/src/app/api/measurements/route.ts b/src/app/api/measurements/route.ts
index 7331f81c8..ce3a032fb 100644
--- a/src/app/api/measurements/route.ts
+++ b/src/app/api/measurements/route.ts
@@ -328,6 +328,8 @@ export const GET = apiHandler(async (request: NextRequest) => {
         // legacy fallback below covers the boot-backfill convergence
         // window when an existing bucket pre-dates v1.4.39.
         sumValue: true,
+        minValue: true,
+        maxValue: true,
       },
     });
     // v1.4.39.2 — coverage-mismatch fallback. v1.4.39.1 wired the
@@ -417,6 +419,8 @@ export const GET = apiHandler(async (request: NextRequest) => {
               mean: true,
               count: true,
               sumValue: true,
+              minValue: true,
+              maxValue: true,
             },
           });
         } catch (err) {
@@ -454,6 +458,13 @@ export const GET = apiHandler(async (request: NextRequest) => {
           : r.mean,
         measuredAt: r.bucketStart.toISOString(),
         count: r.count,
+        // v1.8.5 — per-day min / max so the chart can shade an
+        // Apple-Health-style range band around the daily mean line.
+        // Omitted for cumulative metrics (steps, distance, …) where the
+        // daily value is a SUM, not a central tendency, so an intra-day
+        // spread band carries no meaning.
+        minValue: useSum ? undefined : r.minValue,
+        maxValue: useSum ? undefined : r.maxValue,
       }));
       annotate({
         action: { name: "measurement.list" },
diff --git a/src/app/insights/pulse/page.tsx b/src/app/insights/pulse/page.tsx
index 073bf3dca..a36cb2a64 100644
--- a/src/app/insights/pulse/page.tsx
+++ b/src/app/insights/pulse/page.tsx
@@ -13,6 +13,8 @@ import { HealthChartDynamic } from "@/components/charts/health-chart-dynamic";
 import { CoachLaunchButton } from "@/components/insights/coach-launch-button";
 import { InsightStatusCard } from "@/components/insights/insight-status-card";
 import { MetricEmptyState } from "@/components/insights/metric-empty-state";
+import { MetricStatStrip } from "@/components/insights/metric-stat-strip";
+import { MeasurementDiversityNudge } from "@/components/insights/measurement-diversity-nudge";
 import { MetricTargetSummary } from "@/components/insights/metric-target-summary";
 import { SubPageShell } from "@/components/insights/sub-page-shell";
 import { Vo2MaxChartRow } from "@/components/insights/vo2-max-chart-row";
@@ -114,6 +116,20 @@ export default function InsightsPulsPage() {
       title={t("insights.pulseSectionTitle")}
       description={t("insights.subPage.pulsDescription")}
       explainerMetric="pulse"
+      statStrip={
+        <MetricStatStrip
+          summary={analytics?.summaries?.PULSE ?? null}
+          unit="bpm"
+        />
+      }
+      diversityNudge={
+        <MeasurementDiversityNudge
+          measurementType="PULSE"
+          metricLabel={t("insights.pulseSectionTitle")}
+          timeZone={user?.timezone ?? undefined}
+        />
+      }
+      showAllValuesType="PULSE"
     >
       <HealthChartDynamic
         chartKey="pulse"
diff --git a/src/app/insights/values/[type]/page.tsx b/src/app/insights/values/[type]/page.tsx
new file mode 100644
index 000000000..e1915e2a3
--- /dev/null
+++ b/src/app/insights/values/[type]/page.tsx
@@ -0,0 +1,67 @@
+"use client";
+
+import { use } from "react";
+import Link from "next/link";
+import { notFound } from "next/navigation";
+import { ArrowLeft } from "lucide-react";
+
+import { useTranslations } from "@/lib/i18n/context";
+import { measurementTypeEnum } from "@/lib/validations/measurement";
+import { MEASUREMENT_TYPE_LABEL_KEYS } from "@/components/measurements/measurement-list-meta";
+import { Button } from "@/components/ui/button";
+import { MeasurementList } from "@/components/measurements/measurement-list";
+import { SubPageShell } from "@/components/insights/sub-page-shell";
+
+/**
+ * v1.8.5 — `/insights/values/[type]`.
+ *
+ * The "show all readings" subpage for a single metric. The insights
+ * category pages link here with their `MeasurementType` as the route
+ * segment (e.g. `/insights/values/WEIGHT`); this page pins the existing
+ * `<MeasurementList>` to that type via `lockedType`, giving the user the
+ * full paginated, inline-editable raw-readings view without rebuilding
+ * any of the list machinery.
+ *
+ * A single dynamic route serves every metric — the enum guard rejects an
+ * unknown segment with a 404 rather than rendering an empty list for a
+ * typo'd type.
+ */
+export default function InsightsMetricValuesPage({
+  params,
+}: {
+  params: Promise<{ type: string }>;
+}) {
+  const { t } = useTranslations();
+  const { type } = use(params);
+
+  // Reject any segment that is not a real MeasurementType so a typo'd
+  // deep-link 404s instead of mounting a blank list.
+  if (!measurementTypeEnum.options.includes(type as never)) {
+    notFound();
+  }
+
+  const labelKey = MEASUREMENT_TYPE_LABEL_KEYS[type];
+  const metricLabel = labelKey ? t(labelKey) : type;
+
+  return (
+    <SubPageShell
+      title={t("insights.subPage.valuesPageTitle", { metric: metricLabel })}
+      description={t("insights.subPage.valuesPageDescription")}
+    >
+      <Button
+        asChild
+        variant="ghost"
+        size="sm"
+        data-slot="metric-values-back"
+        className="-ml-2 w-fit"
+      >
+        <Link href="/insights">
+          <ArrowLeft className="mr-1 size-4" aria-hidden="true" />
+          {t("insights.subPage.valuesBack")}
+        </Link>
+      </Button>
+
+      <MeasurementList lockedType={type} />
+    </SubPageShell>
+  );
+}
diff --git a/src/app/insights/weight/page.tsx b/src/app/insights/weight/page.tsx
index c150d178f..209622e39 100644
--- a/src/app/insights/weight/page.tsx
+++ b/src/app/insights/weight/page.tsx
@@ -13,6 +13,8 @@ import { HealthChartDynamic } from "@/components/charts/health-chart-dynamic";
 import { CoachLaunchButton } from "@/components/insights/coach-launch-button";
 import { InsightStatusCard } from "@/components/insights/insight-status-card";
 import { MetricEmptyState } from "@/components/insights/metric-empty-state";
+import { MetricStatStrip } from "@/components/insights/metric-stat-strip";
+import { MeasurementDiversityNudge } from "@/components/insights/measurement-diversity-nudge";
 import { MetricTargetSummary } from "@/components/insights/metric-target-summary";
 import { SubPageShell } from "@/components/insights/sub-page-shell";
 import { buildWeightBandsFromHeight } from "@/lib/analytics/value-bands";
@@ -37,7 +39,8 @@ export default function InsightsGewichtPage() {
   const { data: status, isLoading: isStatusLoading } =
     useInsightStatus("weight");
 
-  const { isEmpty } = useInsightsAnalytics("WEIGHT");
+  const { data: analytics, isEmpty } = useInsightsAnalytics("WEIGHT");
+  const weightSummary = analytics?.summaries?.WEIGHT ?? null;
 
   if (isEmpty) {
     return (
@@ -75,6 +78,15 @@ export default function InsightsGewichtPage() {
       title={t("insights.weightSectionTitle")}
       description={t("insights.subPage.gewichtDescription")}
       explainerMetric="weight"
+      statStrip={<MetricStatStrip summary={weightSummary} unit="kg" />}
+      diversityNudge={
+        <MeasurementDiversityNudge
+          measurementType="WEIGHT"
+          metricLabel={t("insights.weightSectionTitle")}
+          timeZone={user?.timezone ?? undefined}
+        />
+      }
+      showAllValuesType="WEIGHT"
     >
       <HealthChartDynamic
         chartKey="weight"
diff --git a/src/components/charts/health-chart.tsx b/src/components/charts/health-chart.tsx
index 76489219a..d5c47b77e 100644
--- a/src/components/charts/health-chart.tsx
+++ b/src/components/charts/health-chart.tsx
@@ -7,6 +7,7 @@ import {
   ResponsiveContainer,
   ComposedChart,
   Line,
+  Area,
   XAxis,
   YAxis,
   CartesianGrid,
@@ -193,12 +194,20 @@ interface ChartDataPoint {
   date: string;
   timestamp: number;
   pointIndex?: number;
-  [key: string]: string | number | undefined;
+  // v1.8.5 — `${type}__range` keys carry a `[min, max]` tuple for the
+  // range-band <Area>; every other key stays a scalar.
+  [key: string]: string | number | undefined | [number, number];
 }
 
 interface MeasurementApiRow {
   measuredAt: string;
   value: number;
+  // v1.8.5 — per-day min / max emitted by the rollup daily-aggregate
+  // path (non-cumulative metrics only). Drive the Apple-Health-style
+  // range band shaded around the mean line. Absent on the raw-row path
+  // (windows ≤ 7 days) and on cumulative metrics.
+  minValue?: number;
+  maxValue?: number;
   // v1.4.43 W2-CHART-GATE — the rollup / daily-aggregate paths return
   // the underlying raw-row count per bucket. Used downstream to gate
   // the "more days needed" empty-state copy on the actual measurement
@@ -597,7 +606,19 @@ export function HealthChart({
         string,
         {
           timestamp: number;
-          values: Record<string, { sum: number; count: number }>;
+          values: Record<
+            string,
+            {
+              sum: number;
+              count: number;
+              // v1.8.5 — per-bucket spread for the range band. Seeded
+              // from the rollup daily-aggregate's min / max columns;
+              // null when the API row carries no spread (raw-row path
+              // or cumulative metric).
+              min: number | null;
+              max: number | null;
+            }
+          >;
         }
       >();
 
@@ -674,9 +695,30 @@ export function HealthChart({
             timestamp: dayKeyToTimestamp(dayKey),
             values: {},
           };
-          const current = bucket.values[type] ?? { sum: 0, count: 0 };
+          const current = bucket.values[type] ?? {
+            sum: 0,
+            count: 0,
+            min: null,
+            max: null,
+          };
           current.sum += value;
           current.count += 1;
+          // v1.8.5 — carry the rollup bucket's min / max through when the
+          // API supplies them (daily-aggregate path, non-cumulative).
+          // `valueScale` already folded into `value` above; apply the
+          // same scale to the spread so the band tracks the line.
+          if (
+            typeof measurement.minValue === "number" &&
+            typeof measurement.maxValue === "number" &&
+            valueMode !== "bmi"
+          ) {
+            const scaledMin = measurement.minValue * valueScale;
+            const scaledMax = measurement.maxValue * valueScale;
+            current.min =
+              current.min === null ? scaledMin : Math.min(current.min, scaledMin);
+            current.max =
+              current.max === null ? scaledMax : Math.max(current.max, scaledMax);
+          }
           bucket.values[type] = current;
           dailyAggregates.set(dayKey, bucket);
         }
@@ -702,6 +744,13 @@ export function HealthChart({
               type as MeasurementType,
             );
             point[type] = isCumulative ? stats.sum : stats.sum / stats.count;
+            // v1.8.5 — emit the day's spread as a `[min, max]` tuple key
+            // so the range-band <Area> can shade it. Only when the
+            // rollup supplied both bounds and the metric is not
+            // cumulative (a SUM has no meaningful intra-day spread).
+            if (!isCumulative && stats.min !== null && stats.max !== null) {
+              point[`${type}__range`] = [stats.min, stats.max] as never;
+            }
           }
 
           return point;
@@ -1746,6 +1795,33 @@ export function HealthChart({
                     }}
                   />
                 )}
+                {/* v1.8.5 — min–max range band. An Apple-Health-style
+                    shaded area between each day's min and max, painted
+                    behind the mean line so it reads as context, not a
+                    second series. Gated on `!mini` (the dashboard
+                    sparkline stays clean) and on the daily-aggregate
+                    path supplying a `[min, max]` tuple per point — single
+                    non-cumulative metrics with intra-day spread (pulse,
+                    weight, glucose, BP). The toggle rides the existing
+                    target-range pref so the user controls both bands
+                    from one switch. */}
+                {!mini &&
+                  showBands &&
+                  types.map((type, i) => (
+                    <Area
+                      key={`${type}__range`}
+                      type="monotone"
+                      dataKey={`${type}__range`}
+                      name={`${getTypeLabel(type, valueMode, t)} (${t("charts.rangeBand")})`}
+                      stroke="none"
+                      fill={colors[i % colors.length]}
+                      fillOpacity={0.12}
+                      connectNulls
+                      isAnimationActive={animationsEnabled}
+                      legendType="none"
+                      tooltipType="none"
+                    />
+                  ))}
                 {types.map((type, i) => (
                   <Line
                     key={type}
diff --git a/src/components/insights/__tests__/insights-tab-strip-memo.test.tsx b/src/components/insights/__tests__/insights-tab-strip-memo.test.tsx
index 4e142bf4a..3987da8a5 100644
--- a/src/components/insights/__tests__/insights-tab-strip-memo.test.tsx
+++ b/src/components/insights/__tests__/insights-tab-strip-memo.test.tsx
@@ -20,6 +20,7 @@ function fakeSummary(count: number): DataSummary {
     min: null,
     max: null,
     mean: null,
+    median: null,
     avg7: null,
     avg30: null,
     slope7: null,
diff --git a/src/components/insights/__tests__/insights-tab-strip.test.tsx b/src/components/insights/__tests__/insights-tab-strip.test.tsx
index c69bfaffb..c13f477f1 100644
--- a/src/components/insights/__tests__/insights-tab-strip.test.tsx
+++ b/src/components/insights/__tests__/insights-tab-strip.test.tsx
@@ -30,6 +30,7 @@ function fakeSummary(count: number): DataSummary {
     min: null,
     max: null,
     mean: null,
+    median: null,
     avg7: null,
     avg30: null,
     slope7: null,
diff --git a/src/components/insights/__tests__/metric-stat-strip.test.tsx b/src/components/insights/__tests__/metric-stat-strip.test.tsx
new file mode 100644
index 000000000..24ce1db02
--- /dev/null
+++ b/src/components/insights/__tests__/metric-stat-strip.test.tsx
@@ -0,0 +1,81 @@
+import { describe, it, expect } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+
+import { I18nProvider } from "@/lib/i18n/context";
+import type { DataSummary } from "@/lib/analytics/trends";
+
+import { MetricStatStrip } from "../metric-stat-strip";
+
+/**
+ * v1.8.5 — `<MetricStatStrip>` SSR coverage.
+ *
+ * The strip leads the insights category pages with the four central
+ * stats — min / max / median / mean — read from the already-fetched
+ * `summaries` slice (zero new network). Acceptance:
+ *   1. Renders four labelled cells: min, max, median, mean.
+ *   2. Each cell shows the formatted value + the metric unit.
+ *   3. A null summary (read in flight) renders nothing rather than a
+ *      strip full of em-dashes.
+ *   4. A zero-count summary renders nothing (brand-new metric, no data).
+ */
+
+function render(node: React.ReactNode, locale: "en" | "de" = "en") {
+  return renderToStaticMarkup(
+    <I18nProvider initialLocale={locale}>{node}</I18nProvider>,
+  );
+}
+
+const populated: DataSummary = {
+  count: 42,
+  latest: 72,
+  min: 58,
+  max: 88,
+  mean: 70.4,
+  median: 71,
+  avg7: 71,
+  avg30: 70,
+  slope7: null,
+  slope30: null,
+  slope90: null,
+  anomalyCount: 0,
+  avg30LastMonth: null,
+  avg30LastYear: null,
+};
+
+describe("<MetricStatStrip>", () => {
+  it("renders the four stat cells with min / max / median / mean", () => {
+    const html = render(<MetricStatStrip summary={populated} unit="bpm" />);
+    expect(html).toContain('data-stat="min"');
+    expect(html).toContain('data-stat="max"');
+    expect(html).toContain('data-stat="median"');
+    expect(html).toContain('data-stat="mean"');
+  });
+
+  it("shows the formatted values and the unit", () => {
+    const html = render(<MetricStatStrip summary={populated} unit="bpm" />);
+    expect(html).toContain("58");
+    expect(html).toContain("88");
+    expect(html).toContain("71");
+    expect(html).toContain("bpm");
+  });
+
+  it("renders nothing while the summary is still loading", () => {
+    const html = render(<MetricStatStrip summary={null} unit="bpm" />);
+    expect(html).toBe("");
+  });
+
+  it("renders nothing for a zero-count metric", () => {
+    const empty: DataSummary = { ...populated, count: 0 };
+    const html = render(<MetricStatStrip summary={empty} unit="bpm" />);
+    expect(html).toBe("");
+  });
+
+  it("falls back to mean when median is absent (older payload)", () => {
+    const noMedian: DataSummary = { ...populated, median: null };
+    const html = render(<MetricStatStrip summary={noMedian} unit="bpm" />);
+    // Median cell still paints (em-dash) so the four-up grid stays
+    // balanced; min / max / mean keep their values.
+    expect(html).toContain('data-stat="median"');
+    expect(html).toContain('data-stat="mean"');
+  });
+});
diff --git a/src/components/insights/__tests__/vo2-max-chart-row.test.tsx b/src/components/insights/__tests__/vo2-max-chart-row.test.tsx
index 778bb20aa..7c486ebb2 100644
--- a/src/components/insights/__tests__/vo2-max-chart-row.test.tsx
+++ b/src/components/insights/__tests__/vo2-max-chart-row.test.tsx
@@ -41,6 +41,7 @@ const populatedSummary: DataSummary = {
   min: 38.1,
   max: 45.7,
   mean: 41.5,
+  median: 41.4,
   avg7: 42.0,
   avg30: 41.8,
   slope7: null,
@@ -57,6 +58,7 @@ const emptySummary: DataSummary = {
   min: null,
   max: null,
   mean: null,
+  median: null,
   avg7: null,
   avg30: null,
   slope7: null,
diff --git a/src/components/insights/healthkit-metric-page.tsx b/src/components/insights/healthkit-metric-page.tsx
index ce776b03f..2b0f0ad0d 100644
--- a/src/components/insights/healthkit-metric-page.tsx
+++ b/src/components/insights/healthkit-metric-page.tsx
@@ -13,6 +13,8 @@ import { Button } from "@/components/ui/button";
 import { CoachLaunchButton } from "@/components/insights/coach-launch-button";
 import { HealthChartDynamic } from "@/components/charts/health-chart-dynamic";
 import { MetricEmptyState } from "@/components/insights/metric-empty-state";
+import { MetricStatStrip } from "@/components/insights/metric-stat-strip";
+import { MeasurementDiversityNudge } from "@/components/insights/measurement-diversity-nudge";
 import { SubPageShell } from "@/components/insights/sub-page-shell";
 
 /**
@@ -107,7 +109,26 @@ export function HealthKitMetricPage({
   const { t } = useTranslations();
   const { compareBaseline } = useInsightsLayoutPrefs(isAuthenticated);
 
-  const { isEmpty } = useInsightsAnalytics(insightMetric);
+  const { data: analytics, isEmpty } = useInsightsAnalytics(insightMetric);
+  const rawSummary = analytics?.summaries?.[measurementType] ?? null;
+  // The stat strip renders display-unit values. The summary holds stored
+  // values, so when the page renders a scaled unit (e.g. WALKING_SPEED
+  // stores m/s but displays km/h via `valueScale`), fold the same scale
+  // into the strip's min / max / median / mean so the numbers and the
+  // unit agree. `valueScale` defaults to 1 (identity) → byte-identical
+  // for every non-scaled metric.
+  const scale = valueScale ?? 1;
+  const summary =
+    rawSummary && scale !== 1
+      ? {
+          ...rawSummary,
+          min: rawSummary.min === null ? null : rawSummary.min * scale,
+          max: rawSummary.max === null ? null : rawSummary.max * scale,
+          mean: rawSummary.mean === null ? null : rawSummary.mean * scale,
+          median:
+            rawSummary.median === null ? null : rawSummary.median * scale,
+        }
+      : rawSummary;
 
   const title = t(`${i18nPrefix}.title`);
   const description = t(`${i18nPrefix}.description`);
@@ -143,6 +164,15 @@ export function HealthKitMetricPage({
       title={title}
       description={description}
       explainerMetric={explainerMetric}
+      statStrip={<MetricStatStrip summary={summary} unit={yAxisUnit ?? unit} />}
+      diversityNudge={
+        <MeasurementDiversityNudge
+          measurementType={measurementType}
+          metricLabel={title}
+          timeZone={user?.timezone ?? undefined}
+        />
+      }
+      showAllValuesType={measurementType}
     >
       <HealthChartDynamic
         chartKey={chartKey}
diff --git a/src/components/insights/measurement-diversity-nudge.tsx b/src/components/insights/measurement-diversity-nudge.tsx
new file mode 100644
index 000000000..23b81d76b
--- /dev/null
+++ b/src/components/insights/measurement-diversity-nudge.tsx
@@ -0,0 +1,92 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import { Lightbulb } from "lucide-react";
+
+import { useAuth } from "@/hooks/use-auth";
+import { useTranslations } from "@/lib/i18n/context";
+import { queryKeys } from "@/lib/query-keys";
+import { detectMeasurementDiversity } from "@/lib/insights/measurement-diversity";
+
+/**
+ * v1.8.5 — measurement-diversity nudge for the insights category pages.
+ *
+ * When a metric's readings cluster on a single weekday or a narrow
+ * time-of-day band, the trend reads a biased slice of reality. This
+ * component fetches a bounded recent window of raw timestamps for the
+ * metric, runs the pure `detectMeasurementDiversity` check, and — only
+ * when the spread is genuinely lopsided — surfaces a gentle hint to
+ * measure on other days / times.
+ *
+ * v1.8.3 anti-freeze posture: the read is a bounded `limit`-capped query
+ * with a 5-minute `staleTime`, fires only after the page has mounted
+ * (no SSR blocking), and renders nothing while in flight or when the
+ * spread is healthy. No new server route — it rides the existing
+ * `/api/measurements` list endpoint.
+ */
+
+interface MeasurementDiversityNudgeProps {
+  /** The page's `MeasurementType`. */
+  measurementType: string;
+  /** Localised metric name woven into the hint copy. */
+  metricLabel: string;
+  /** User's IANA timezone so weekday / hour resolve in the wall clock. */
+  timeZone?: string;
+}
+
+/** Bounded window of recent rows — enough to read a pattern, never heavy. */
+const WINDOW_SIZE = 120;
+
+export function MeasurementDiversityNudge({
+  measurementType,
+  metricLabel,
+  timeZone,
+}: MeasurementDiversityNudgeProps) {
+  const { t } = useTranslations();
+  const { isAuthenticated } = useAuth();
+
+  const { data: timestamps } = useQuery({
+    queryKey: queryKeys.measurementDiversity(measurementType),
+    queryFn: async (): Promise<string[]> => {
+      const params = new URLSearchParams();
+      params.set("type", measurementType);
+      params.set("limit", String(WINDOW_SIZE));
+      params.set("sortBy", "measuredAt");
+      params.set("sortDir", "desc");
+      const res = await fetch(`/api/measurements?${params}`);
+      if (!res.ok) return [];
+      const json = await res.json();
+      const rows = (json.data?.measurements ?? []) as Array<{
+        measuredAt: string;
+      }>;
+      return rows.map((r) => r.measuredAt);
+    },
+    enabled: isAuthenticated,
+    // The pattern shifts slowly — a 5-minute cache keeps the nudge calm
+    // and shares the read budget with the rest of the page.
+    staleTime: 5 * 60 * 1000,
+  });
+
+  if (!timestamps) return null;
+
+  const signal = detectMeasurementDiversity(timestamps, timeZone);
+  if (!signal) return null;
+
+  const message = t(`insights.subPage.diversity.${signal.kind}`, {
+    metric: metricLabel,
+  });
+
+  return (
+    <div
+      data-slot="measurement-diversity-nudge"
+      role="note"
+      className="bg-muted/40 text-muted-foreground flex items-start gap-2.5 rounded-lg px-3 py-2.5 text-sm"
+    >
+      <Lightbulb
+        className="text-dracula-yellow mt-0.5 size-4 shrink-0"
+        aria-hidden="true"
+      />
+      <p className="leading-relaxed">{message}</p>
+    </div>
+  );
+}
diff --git a/src/components/insights/metric-stat-strip.tsx b/src/components/insights/metric-stat-strip.tsx
new file mode 100644
index 000000000..40e5789bd
--- /dev/null
+++ b/src/components/insights/metric-stat-strip.tsx
@@ -0,0 +1,98 @@
+"use client";
+
+import { useFormatters, useTranslations } from "@/lib/i18n/context";
+import type { DataSummary } from "@/lib/analytics/trends";
+
+/**
+ * v1.8.5 — at-a-glance stat strip for the insights category pages.
+ *
+ * Leads each metric page with the four central statistics — min / max /
+ * median / mean — read straight from the already-fetched `summaries`
+ * slice (`useInsightsAnalytics`). Zero new network: the layout shell and
+ * the empty-state gate already warm the `["analytics", "summaries"]`
+ * cache, so the strip is a pure render of cached numbers. This is the
+ * numbers-first header Apple Health / Withings / Oura lead their detail
+ * screens with — the single biggest "data-rich" lift per unit effort.
+ *
+ * Median sits alongside mean on purpose: a series with a handful of very
+ * high or very low readings drags the mean away from the typical value,
+ * and showing both makes that skew legible rather than hidden.
+ *
+ * The thin HealthKit pages (`HealthkitMetricPage`) mount this too so they
+ * reach parity with the bespoke pages — a rich numeric header even where
+ * there is no target band or AI assessment.
+ */
+
+interface MetricStatStripProps {
+  /**
+   * Analytics summary for the page's `MeasurementType`. Null is allowed
+   * so the parent doesn't have to gate on the network read finishing —
+   * the strip simply doesn't paint until the data lands. A zero-count
+   * summary (brand-new metric) also renders nothing; the page's
+   * empty-state owns that surface.
+   */
+  summary: DataSummary | null;
+  /** Unit suffix rendered next to each value (e.g. `bpm`, `kg`). */
+  unit: string;
+  /**
+   * Decimal precision for the formatted values. Defaults to 1 — enough
+   * for weight (78.4) and HRV (41.5) without trailing noise on integer
+   * metrics, which `Intl.NumberFormat` drops anyway.
+   */
+  fractionDigits?: number;
+}
+
+export function MetricStatStrip({
+  summary,
+  unit,
+  fractionDigits = 1,
+}: MetricStatStripProps) {
+  const { t } = useTranslations();
+  const fmt = useFormatters();
+
+  // Nothing to show until the summary lands or for a metric with no
+  // readings — the page's empty-state covers the zero-data case.
+  if (!summary || summary.count <= 0) return null;
+
+  const format = (value: number | null): string =>
+    value === null ? "—" : `${fmt.number(value, fractionDigits)} ${unit}`;
+
+  const cells: Array<{ key: string; label: string; value: number | null }> = [
+    { key: "min", label: t("insights.subPage.stats.min"), value: summary.min },
+    { key: "max", label: t("insights.subPage.stats.max"), value: summary.max },
+    {
+      key: "median",
+      label: t("insights.subPage.stats.median"),
+      value: summary.median,
+    },
+    {
+      key: "mean",
+      label: t("insights.subPage.stats.mean"),
+      value: summary.mean,
+    },
+  ];
+
+  return (
+    <section
+      data-slot="metric-stat-strip"
+      aria-label={t("insights.subPage.stats.label")}
+      className="bg-card border-border grid grid-cols-2 gap-3 rounded-xl border p-4 sm:grid-cols-4 [&>div]:min-h-[56px]"
+    >
+      {cells.map((cell) => (
+        <div
+          key={cell.key}
+          data-slot="metric-stat"
+          data-stat={cell.key}
+          className="space-y-1"
+        >
+          <p className="text-muted-foreground text-[10px] tracking-wide uppercase">
+            {cell.label}
+          </p>
+          <p className="text-lg font-semibold tabular-nums">
+            {format(cell.value)}
+          </p>
+        </div>
+      ))}
+    </section>
+  );
+}
diff --git a/src/components/insights/sub-page-shell.tsx b/src/components/insights/sub-page-shell.tsx
index 52f662488..1bb8454d6 100644
--- a/src/components/insights/sub-page-shell.tsx
+++ b/src/components/insights/sub-page-shell.tsx
@@ -1,8 +1,11 @@
 "use client";
 
 import { useEffect, useRef, type ReactNode } from "react";
+import Link from "next/link";
+import { ListOrdered } from "lucide-react";
 
 import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
 import { MetricExplainer } from "@/components/insights/metric-explainer";
 import { useScrollResetOnRoute } from "@/hooks/use-scroll-reset-on-route";
 import { useTranslations } from "@/lib/i18n/context";
@@ -66,6 +69,26 @@ export interface SubPageShellProps {
    * affordance, not an a11y one.
    */
   focusOnMount?: boolean;
+  /**
+   * v1.8.5 W4b — numbers-first stat strip rendered directly beneath the
+   * header, above the chart. Sub-pages pass `<MetricStatStrip metric=… />`
+   * so every metric (including the thin HealthKit pages) leads with
+   * min / max / median / mean. Omitted on the empty-state branch.
+   */
+  statStrip?: ReactNode;
+  /**
+   * v1.8.5 W4b — measurement-diversity nudge mounted just under the stat
+   * strip. A gentle hint when readings cluster on one weekday / time.
+   * Self-gating: renders nothing when the spread is healthy.
+   */
+  diversityNudge?: ReactNode;
+  /**
+   * v1.8.5 W4b — a "show all readings" entry rendered at the foot of the
+   * page, after the chart + cards. Sub-pages pass the metric's
+   * `MeasurementType`; the shell renders a button that links to the
+   * dedicated `/insights/values/<type>` subpage.
+   */
+  showAllValuesType?: string;
   children: ReactNode;
 }
 
@@ -75,6 +98,9 @@ export function SubPageShell({
   description,
   explainerMetric,
   focusOnMount = false,
+  statStrip,
+  diversityNudge,
+  showAllValuesType,
   children,
 }: SubPageShellProps) {
   const { t } = useTranslations();
@@ -150,7 +176,30 @@ export function SubPageShell({
           <p className="text-muted-foreground text-sm">{description}</p>
         ) : null}
       </header>
+      {/* v1.8.5 W4b — numbers-first stat strip + diversity nudge sit
+          between the header and the chart so the page leads with data,
+          mirroring the Apple Health / Withings detail layout. Both are
+          self-gating (render nothing without data), so the spacing
+          rhythm holds on the empty-state and brand-new-metric paths. */}
+      {statStrip}
+      {diversityNudge}
       {children}
+      {/* v1.8.5 W4b — "show all readings" entry at the foot, linking to
+          the dedicated per-metric values subpage. */}
+      {showAllValuesType ? (
+        <Button
+          asChild
+          variant="outline"
+          size="sm"
+          data-slot="metric-show-all-values"
+          className="w-full sm:w-auto"
+        >
+          <Link href={`/insights/values/${showAllValuesType}`}>
+            <ListOrdered className="mr-1.5 size-4" aria-hidden="true" />
+            {t("insights.subPage.showAllValues")}
+          </Link>
+        </Button>
+      ) : null}
     </div>
   );
 }
diff --git a/src/components/measurements/__tests__/measurement-list-locked-type.test.tsx b/src/components/measurements/__tests__/measurement-list-locked-type.test.tsx
new file mode 100644
index 000000000..97ac77da4
--- /dev/null
+++ b/src/components/measurements/__tests__/measurement-list-locked-type.test.tsx
@@ -0,0 +1,79 @@
+import { describe, expect, it, vi } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+
+/**
+ * v1.8.5 — `<MeasurementList lockedType>` for the insights "all readings"
+ * subpage. When pinned to a type the global type selector is suppressed
+ * and every row belongs to that metric; the list still paginates and
+ * exposes inline edit/delete (unchanged from the unlocked path).
+ */
+
+vi.mock("next/navigation", () => ({
+  useRouter: () => ({ push: vi.fn(), replace: vi.fn() }),
+  usePathname: () => "/insights/values/WEIGHT",
+}));
+
+vi.mock("@tanstack/react-query", () => ({
+  useQuery: () => ({
+    data: {
+      measurements: [
+        {
+          id: "m1",
+          type: "WEIGHT",
+          value: 78.4,
+          unit: "kg",
+          source: "MANUAL",
+          measuredAt: "2026-05-30T08:00:00.000Z",
+          notes: null,
+        },
+      ],
+      meta: { total: 1 },
+    },
+    isLoading: false,
+  }),
+  useQueryClient: () => ({ invalidateQueries: vi.fn() }),
+  useMutation: () => ({
+    mutate: vi.fn(),
+    mutateAsync: vi.fn(),
+    isPending: false,
+    isError: false,
+    error: null,
+  }),
+}));
+
+vi.mock("@/hooks/use-auth", () => ({
+  useAuth: () => ({
+    user: { id: "u1", username: "marc", role: "USER" },
+    isAuthenticated: true,
+    isLoading: false,
+  }),
+}));
+
+import { I18nProvider } from "@/lib/i18n/context";
+import { MeasurementList } from "../measurement-list";
+
+function render(lockedType?: string) {
+  return renderToStaticMarkup(
+    <I18nProvider initialLocale="en">
+      <MeasurementList lockedType={lockedType} />
+    </I18nProvider>,
+  );
+}
+
+describe("MeasurementList — lockedType", () => {
+  it("hides the type selector when locked to a metric", () => {
+    const locked = render("WEIGHT");
+    const unlocked = render();
+    // The unlocked list paints the filter trigger; the locked one does
+    // not (the metric is fixed by the route).
+    expect(unlocked).toContain("Filter by type");
+    expect(locked).not.toContain('role="combobox"');
+  });
+
+  it("loads the metric's readings", () => {
+    const html = render("WEIGHT");
+    // The single seeded WEIGHT row renders with its value + unit.
+    expect(html).toContain("78.4");
+    expect(html).toContain("kg");
+  });
+});
diff --git a/src/components/measurements/measurement-list.tsx b/src/components/measurements/measurement-list.tsx
index 816b78c8c..60019e5da 100644
--- a/src/components/measurements/measurement-list.tsx
+++ b/src/components/measurements/measurement-list.tsx
@@ -103,6 +103,15 @@ interface MeasurementListProps {
    * (fallback to the header CTA) instead of crashing.
    */
   onAddFirst?: () => void;
+  /**
+   * v1.8.5 — pin the list to a single `MeasurementType` and hide the
+   * type selector. Used by the insights "all readings" subpage, which
+   * already knows the metric from the route and wants a focused list
+   * (pagination + inline edit/delete) rather than the global filter UI.
+   * When set, the type `Select` is not rendered and every fetch is
+   * scoped to this type; the count caption still shows.
+   */
+  lockedType?: string;
 }
 
 const PAGE_SIZE = 25;
@@ -152,12 +161,20 @@ function sourceBadgeClass(source: string): string {
   return "";
 }
 
-export function MeasurementList({ onEdit, onAddFirst }: MeasurementListProps) {
+export function MeasurementList({
+  onEdit,
+  onAddFirst,
+  lockedType,
+}: MeasurementListProps) {
   const { t } = useTranslations();
   const fmt = useFormatters();
   const { isAuthenticated } = useAuth();
   const queryClient = useQueryClient();
-  const [typeFilter, setTypeFilterRaw] = useState<string>("ALL");
+  // v1.8.5 — when `lockedType` is set the list is pinned to that metric
+  // and the type selector is hidden; the filter state seeds from it.
+  const [typeFilter, setTypeFilterRaw] = useState<string>(
+    lockedType ?? "ALL",
+  );
   const [page, setPage] = useState(1);
   const [sortBy, setSortBy] = useState<string>("measuredAt");
   const [sortDir, setSortDir] = useState<"asc" | "desc">("desc");
@@ -419,22 +436,31 @@ export function MeasurementList({ onEdit, onAddFirst }: MeasurementListProps) {
             Pixel 5 (375 px content width) left only ~120 px for the
             count, which wrapped to 2 lines. */}
         <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
-          <Select value={typeFilter} onValueChange={setTypeFilter}>
-            <SelectTrigger
-              className="w-full sm:w-48"
-              aria-label={t("measurements.filterByType")}
-            >
-              <SelectValue placeholder={t("measurements.allTypes")} />
-            </SelectTrigger>
-            <SelectContent>
-              <SelectItem value="ALL">{t("measurements.allTypes")}</SelectItem>
-              {Object.entries(TYPE_LABEL_KEYS).map(([val, labelKey]) => (
-                <SelectItem key={val} value={val}>
-                  {t(labelKey)}
+          {lockedType ? (
+            // v1.8.5 — the insights "all readings" subpage knows the
+            // metric from the route, so the global type selector is
+            // suppressed; the count caption still anchors the column.
+            <span className="sr-only">{t("measurements.filterByType")}</span>
+          ) : (
+            <Select value={typeFilter} onValueChange={setTypeFilter}>
+              <SelectTrigger
+                className="w-full sm:w-48"
+                aria-label={t("measurements.filterByType")}
+              >
+                <SelectValue placeholder={t("measurements.allTypes")} />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="ALL">
+                  {t("measurements.allTypes")}
                 </SelectItem>
-              ))}
-            </SelectContent>
-          </Select>
+                {Object.entries(TYPE_LABEL_KEYS).map(([val, labelKey]) => (
+                  <SelectItem key={val} value={val}>
+                    {t(labelKey)}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          )}
           {data?.meta?.total !== undefined && (
             <span className="text-muted-foreground text-sm">
               {t("measurements.measurementCount", {
@@ -457,17 +483,19 @@ export function MeasurementList({ onEdit, onAddFirst }: MeasurementListProps) {
           <EmptyState
             icon={<Activity className="size-6" />}
             title={
-              typeFilter === "ALL"
+              typeFilter === "ALL" || lockedType
                 ? t("measurements.emptyTitle")
                 : t("measurements.emptyFilteredTitle")
             }
             description={
-              typeFilter === "ALL"
+              typeFilter === "ALL" || lockedType
                 ? t("measurements.emptyDescription")
                 : t("measurements.emptyFilteredDescription")
             }
             action={
-              typeFilter !== "ALL" ? (
+              // v1.8.5 — a locked-type list has no "reset filter" path;
+              // the metric is fixed by the route.
+              typeFilter !== "ALL" && !lockedType ? (
                 <Button
                   variant="outline"
                   onClick={() => setTypeFilter("ALL")}
diff --git a/src/lib/analytics/__tests__/merge-slim-thick.test.ts b/src/lib/analytics/__tests__/merge-slim-thick.test.ts
index bcedca54a..978a28573 100644
--- a/src/lib/analytics/__tests__/merge-slim-thick.test.ts
+++ b/src/lib/analytics/__tests__/merge-slim-thick.test.ts
@@ -24,6 +24,7 @@ const stubSummary = (): DataSummary => ({
   min: 76,
   max: 80,
   mean: 78,
+  median: 78,
   avg7: 78.2,
   avg30: 77.9,
   slope7: null,
diff --git a/src/lib/analytics/__tests__/summaries-slice.test.ts b/src/lib/analytics/__tests__/summaries-slice.test.ts
index b367e478e..53d1b2286 100644
--- a/src/lib/analytics/__tests__/summaries-slice.test.ts
+++ b/src/lib/analytics/__tests__/summaries-slice.test.ts
@@ -74,6 +74,7 @@ describe("computeSummariesSlice", () => {
         min: null,
         max: null,
         mean: null,
+        median: null,
         avg7: null,
         avg30: null,
         slope7: null,
@@ -273,6 +274,7 @@ describe("computeSummariesSlice", () => {
             type: "WEIGHT",
             avg7: 82,
             avg30: 82.5,
+            median: 82.1,
             slope7: 0.02,
             r2_7: 0.5,
             slope30: 0.01,
@@ -307,6 +309,9 @@ describe("computeSummariesSlice", () => {
       expect(weight.min).toBe(79.5);
       expect(weight.max).toBe(84.0);
       expect(weight.mean).toBe(82);
+      // v1.8.5 — the windowed median flows through from the narrow
+      // `PERCENTILE_CONT` column onto the slim summary.
+      expect(weight.median).toBe(82.1);
       expect(weight.latest).toBe(82.7);
       expect(weight.avg7).toBe(82);
       expect(weight.slope7).toEqual({
diff --git a/src/lib/analytics/__tests__/trends.test.ts b/src/lib/analytics/__tests__/trends.test.ts
index 4bbf9c16c..031f43431 100644
--- a/src/lib/analytics/__tests__/trends.test.ts
+++ b/src/lib/analytics/__tests__/trends.test.ts
@@ -76,6 +76,7 @@ describe("summarize", () => {
     expect(summary.min).toBeNull();
     expect(summary.max).toBeNull();
     expect(summary.mean).toBeNull();
+    expect(summary.median).toBeNull();
     expect(summary.avg7).toBeNull();
     expect(summary.avg30).toBeNull();
   });
@@ -88,10 +89,33 @@ describe("summarize", () => {
     expect(summary.min).toBe(70);
     expect(summary.max).toBe(80);
     expect(summary.mean).toBe(75);
+    // 11 values — odd length, median is the 6th value (75).
+    expect(summary.median).toBe(75);
     expect(summary.avg7).not.toBeNull();
     expect(summary.slope7).not.toBeNull();
   });
 
+  // v1.8.5 — median powers the category-page stat strip. It must be the
+  // 50th percentile over VALUES (not timestamps) and must resist a skew
+  // the mean would otherwise hide.
+  it("computes the median over an even-length series as the midpoint", () => {
+    // Four values; median = (72 + 74) / 2 = 73. Insertion order is
+    // intentionally not sorted to prove the helper sorts by value.
+    const data = makePoints([74, 70, 72, 76], 4);
+    const summary = summarize(data);
+    expect(summary.median).toBe(73);
+  });
+
+  it("median diverges from the mean on a right-skewed series", () => {
+    // One large outlier drags the mean up; the median stays at the
+    // central reading — exactly the honesty the stat strip surfaces.
+    const data = makePoints([10, 11, 12, 13, 200], 5);
+    const summary = summarize(data);
+    expect(summary.median).toBe(12);
+    expect(summary.mean).not.toBe(summary.median);
+    expect(summary.mean as number).toBeGreaterThan(summary.median as number);
+  });
+
   // v3 audit caught a divergence: summarize().avg7 used `now` as the
   // window anchor, while trendSlope() used the last point. A stale
   // series (no readings for weeks) reported a slope but no average.
diff --git a/src/lib/analytics/summaries-slice.ts b/src/lib/analytics/summaries-slice.ts
index d088b371f..1125aea0d 100644
--- a/src/lib/analytics/summaries-slice.ts
+++ b/src/lib/analytics/summaries-slice.ts
@@ -109,6 +109,16 @@ interface NarrowAggregateRow {
   type: string;
   avg7: number | null;
   avg30: number | null;
+  /**
+   * v1.8.5 — 50th percentile over the trailing 90-day window. The
+   * windowed median is cheap (the narrow query already index-scans the
+   * 90-day partition) and represents the central reading the stat strip
+   * surfaces next to min / max / mean. An all-time median would require
+   * sorting every raw row per type, which the rollup tier cannot
+   * compose and which the perf posture (v1.8.3 anti-freeze) forbids on
+   * the read path. Null when the window holds no rows.
+   */
+  median: number | null;
   avg30_last_month: number | null;
   slope7: number | null;
   r2_7: number | null;
@@ -159,6 +169,7 @@ function emptySummary(): DataSummary {
     min: null,
     max: null,
     mean: null,
+    median: null,
     avg7: null,
     avg30: null,
     slope7: null,
@@ -271,6 +282,11 @@ async function computeFromRollups(userId: string): Promise<SummariesSlice> {
           WHERE m."measured_at" >= NOW() - INTERVAL '60 days'
             AND m."measured_at" <  NOW() - INTERVAL '30 days'
         )::double precision                                           AS avg30_last_month,
+        PERCENTILE_CONT(0.5) WITHIN GROUP (
+          ORDER BY m."value"
+        ) FILTER (
+          WHERE m."measured_at" >= NOW() - INTERVAL '90 days'
+        )::double precision                                           AS median,
         REGR_SLOPE(
           m."value",
           EXTRACT(EPOCH FROM m."measured_at") / 86400.0
@@ -414,6 +430,7 @@ async function computeFromRollups(userId: string): Promise<SummariesSlice> {
       min: round2(row.min),
       max: round2(row.max),
       mean: round2(row.mean),
+      median: round2(narrow?.median ?? null),
       avg7: round2(narrow?.avg7 ?? null),
       avg30: round2(narrow?.avg30 ?? null),
       slope7: buildSlope(narrow?.slope7 ?? null, narrow?.r2_7 ?? null),
@@ -509,6 +526,11 @@ async function computeFromLiveAggregate(
           WHERE m."measured_at" >= NOW() - INTERVAL '60 days'
             AND m."measured_at" <  NOW() - INTERVAL '30 days'
         )::double precision                                           AS avg30_last_month,
+        PERCENTILE_CONT(0.5) WITHIN GROUP (
+          ORDER BY m."value"
+        ) FILTER (
+          WHERE m."measured_at" >= NOW() - INTERVAL '90 days'
+        )::double precision                                           AS median,
         REGR_SLOPE(
           m."value",
           EXTRACT(EPOCH FROM m."measured_at") / 86400.0
@@ -617,6 +639,7 @@ async function computeFromLiveAggregate(
       min: round2(row.min_value),
       max: round2(row.max_value),
       mean: round2(row.mean_value),
+      median: round2(win?.median ?? null),
       avg7: round2(win?.avg7 ?? null),
       avg30: round2(win?.avg30 ?? null),
       slope7: buildSlope(win?.slope7 ?? null, win?.r2_7 ?? null),
diff --git a/src/lib/analytics/trends.ts b/src/lib/analytics/trends.ts
index c5a57c41a..eae723f45 100644
--- a/src/lib/analytics/trends.ts
+++ b/src/lib/analytics/trends.ts
@@ -120,6 +120,13 @@ export interface DataSummary {
   max: number | null;
   /** Null when the series is empty (vs the previous 0 sentinel). */
   mean: number | null;
+  /**
+   * v1.8.5 — 50th percentile (median) of the value series. Surfaced on
+   * the insights category-page stat strip alongside min / max / mean so
+   * a skewed series (a few very high or very low readings dragging the
+   * mean) reads honestly. Null when the series is empty.
+   */
+  median: number | null;
   avg7: number | null;
   avg30: number | null;
   slope7: TrendSlope | null;
@@ -152,6 +159,7 @@ export function summarize(data: DataPoint[]): DataSummary {
       min: null,
       max: null,
       mean: null,
+      median: null,
       avg7: null,
       avg30: null,
       slope7: null,
@@ -184,6 +192,19 @@ export function summarize(data: DataPoint[]): DataSummary {
   }
   const mean = sum / values.length;
 
+  // v1.8.5 — median (50th percentile) over the full series. A separate
+  // numeric sort from the date-ordered `sorted` array above so the
+  // percentile is taken over values, not timestamps. Linear-interpolated
+  // midpoint on an even-length series (the standard PERCENTILE_CONT
+  // definition) so this matches the SQL `PERCENTILE_CONT(0.5)` the
+  // rollup-tier slim slice emits.
+  const valueSorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(valueSorted.length / 2);
+  const median =
+    valueSorted.length % 2 === 0
+      ? (valueSorted[mid - 1] + valueSorted[mid]) / 2
+      : valueSorted[mid];
+
   const now = Date.now();
   const DAY = 24 * 60 * 60 * 1000;
   const last7 = sorted.filter((p) => now - p.date.getTime() < 7 * DAY);
@@ -215,6 +236,7 @@ export function summarize(data: DataPoint[]): DataSummary {
     min: minVal,
     max: maxVal,
     mean: Math.round(mean * 100) / 100,
+    median: Math.round(median * 100) / 100,
     avg7:
       last7.length > 0
         ? Math.round(
diff --git a/src/lib/insights/__tests__/measurement-diversity.test.ts b/src/lib/insights/__tests__/measurement-diversity.test.ts
new file mode 100644
index 000000000..a95fb1ed7
--- /dev/null
+++ b/src/lib/insights/__tests__/measurement-diversity.test.ts
@@ -0,0 +1,65 @@
+import { describe, it, expect } from "vitest";
+
+import { detectMeasurementDiversity } from "../measurement-diversity";
+
+/**
+ * v1.8.5 — measurement-diversity detection.
+ *
+ * The nudge fires when a metric's readings cluster on a single weekday
+ * or a narrow time-of-day band, hinting the user to spread their
+ * measurements for a fuller picture. Pure function over ISO timestamps
+ * so the unit test pins the thresholds without a DOM.
+ */
+
+// Build N ISO timestamps, all on the same weekday (Tuesdays) at 09:00.
+function tuesdaysAt(hour: number, count: number): string[] {
+  // 2026-06-02 is a Tuesday.
+  const out: string[] = [];
+  for (let i = 0; i < count; i++) {
+    const d = new Date(2026, 5, 2 + i * 7, hour, 0, 0);
+    out.push(d.toISOString());
+  }
+  return out;
+}
+
+// Build N timestamps spread across every weekday at varied hours.
+function spreadAcrossWeek(count: number): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < count; i++) {
+    const d = new Date(2026, 5, 1 + i, 6 + (i % 12), 0, 0);
+    out.push(d.toISOString());
+  }
+  return out;
+}
+
+describe("detectMeasurementDiversity", () => {
+  it("returns null below the minimum sample floor", () => {
+    expect(detectMeasurementDiversity(tuesdaysAt(9, 3))).toBeNull();
+  });
+
+  it("flags a weekday cluster when most readings fall on one day", () => {
+    const result = detectMeasurementDiversity(tuesdaysAt(9, 10));
+    expect(result).not.toBeNull();
+    expect(result?.kind).toBe("weekday");
+  });
+
+  it("flags a time-of-day cluster when the weekday is spread", () => {
+    // Spread across weekdays but every reading at 08:00 → time cluster.
+    const sameHour: string[] = [];
+    for (let i = 0; i < 12; i++) {
+      sameHour.push(new Date(2026, 5, 1 + i, 8, 0, 0).toISOString());
+    }
+    const result = detectMeasurementDiversity(sameHour);
+    expect(result?.kind).toBe("timeOfDay");
+  });
+
+  it("returns null for well-spread readings", () => {
+    expect(detectMeasurementDiversity(spreadAcrossWeek(14))).toBeNull();
+  });
+
+  it("ignores invalid timestamps without throwing", () => {
+    const mixed = [...tuesdaysAt(9, 10), "not-a-date", ""];
+    const result = detectMeasurementDiversity(mixed);
+    expect(result?.kind).toBe("weekday");
+  });
+});
diff --git a/src/lib/insights/__tests__/metric-availability.test.ts b/src/lib/insights/__tests__/metric-availability.test.ts
index d55cf454a..8d83d60ca 100644
--- a/src/lib/insights/__tests__/metric-availability.test.ts
+++ b/src/lib/insights/__tests__/metric-availability.test.ts
@@ -19,6 +19,7 @@ function fakeSummary(count: number): DataSummary {
     min: null,
     max: null,
     mean: null,
+    median: null,
     avg7: null,
     avg30: null,
     slope7: null,
diff --git a/src/lib/insights/comprehensive-aggregator.ts b/src/lib/insights/comprehensive-aggregator.ts
index b6b598e39..10ec3e72d 100644
--- a/src/lib/insights/comprehensive-aggregator.ts
+++ b/src/lib/insights/comprehensive-aggregator.ts
@@ -490,6 +490,11 @@ async function buildFromRollups(
       min: round2(composed.min),
       max: round2(composed.max),
       mean: round2(composed.mean),
+      // v1.8.5 — the comprehensive aggregator feeds the AI snapshot, not
+      // the category-page stat strip, and does not compute a percentile.
+      // Left null so the shared `DataSummary` contract holds without
+      // paying a per-type percentile sort on the AI read path.
+      median: null,
       avg7: round2(narrow?.avg7 ?? null),
       avg30: round2(narrow?.avg30 ?? null),
       slope7: buildSlope(narrow?.slope7 ?? null, narrow?.r2_7 ?? null),
@@ -662,6 +667,9 @@ async function buildFromLiveAggregate(
       min: round2(row.min_value),
       max: round2(row.max_value),
       mean: round2(row.mean_value),
+      // v1.8.5 — see the parallel block above: the AI snapshot path
+      // omits the percentile.
+      median: null,
       avg7: round2(row.avg7),
       avg30: round2(row.avg30),
       slope7: buildSlope(row.slope7, row.r2_7),
diff --git a/src/lib/insights/measurement-diversity.ts b/src/lib/insights/measurement-diversity.ts
new file mode 100644
index 000000000..c9d1c20a2
--- /dev/null
+++ b/src/lib/insights/measurement-diversity.ts
@@ -0,0 +1,125 @@
+/**
+ * v1.8.5 — measurement-diversity detection for the insights category
+ * pages.
+ *
+ * When a user's readings for a metric cluster on a single weekday (only
+ * Tuesdays) or a narrow time-of-day band (always right after waking),
+ * the trend reads a biased slice of reality. This helper inspects the
+ * timestamps of a bounded recent window and, if the spread is too
+ * narrow, returns a hint the page surfaces as a gentle nudge to measure
+ * on other days / times.
+ *
+ * Pure + deterministic over ISO timestamp strings so it is trivially
+ * unit-tested and cache-friendly: the component computes it from the
+ * raw rows it already has, with no blocking work and no extra round-trip
+ * beyond the bounded list fetch it shares with the values subpage.
+ */
+
+export type DiversityKind = "weekday" | "timeOfDay";
+
+export interface DiversitySignal {
+  kind: DiversityKind;
+  /** Share (0–1) of readings that fell in the dominant bucket. */
+  share: number;
+}
+
+/**
+ * Minimum number of valid readings before the nudge can fire. Below
+ * this the clustering is not yet meaningful — a handful of readings on
+ * one day is normal for a brand-new metric.
+ */
+const MIN_SAMPLES = 8;
+
+/**
+ * Fraction of readings that must fall in a single bucket for the bucket
+ * to count as a cluster. 0.7 keeps the nudge conservative — it only
+ * fires when the spread is genuinely lopsided.
+ */
+const CLUSTER_THRESHOLD = 0.7;
+
+/**
+ * Time-of-day bands (in hours). A reading clusters by time when ≥
+ * `CLUSTER_THRESHOLD` of readings fall in the same 6-hour band.
+ */
+const TIME_BAND_HOURS = 6;
+
+interface LocalParts {
+  weekday: number; // 0–6
+  hour: number; // 0–23
+}
+
+/**
+ * Resolve a timestamp's weekday + hour in the given IANA timezone, or
+ * the runtime-local zone when none is supplied. Returns null for an
+ * unparseable timestamp so the caller can skip it.
+ */
+function localParts(iso: string, timeZone?: string): LocalParts | null {
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return null;
+  if (!timeZone) {
+    return { weekday: date.getDay(), hour: date.getHours() };
+  }
+  // Intl resolves the wall-clock weekday + hour in the target zone.
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    weekday: "short",
+    hour: "numeric",
+    hour12: false,
+  }).formatToParts(date);
+  const weekdayName = parts.find((p) => p.type === "weekday")?.value ?? "";
+  const hourStr = parts.find((p) => p.type === "hour")?.value ?? "0";
+  const weekdayMap: Record<string, number> = {
+    Sun: 0,
+    Mon: 1,
+    Tue: 2,
+    Wed: 3,
+    Thu: 4,
+    Fri: 5,
+    Sat: 6,
+  };
+  const weekday = weekdayMap[weekdayName] ?? 0;
+  // `hour12: false` can emit "24" for midnight in some engines.
+  const hour = Number(hourStr) % 24;
+  return { weekday, hour: Number.isFinite(hour) ? hour : 0 };
+}
+
+/**
+ * Inspect the timestamps and return the dominant clustering signal, or
+ * null when the readings are well spread (or below the sample floor).
+ * Weekday clustering takes precedence — it is the coarser, more
+ * actionable bias ("you only measure on Tuesdays").
+ */
+export function detectMeasurementDiversity(
+  timestamps: ReadonlyArray<string>,
+  timeZone?: string,
+): DiversitySignal | null {
+  const parts: LocalParts[] = [];
+  for (const iso of timestamps) {
+    const p = localParts(iso, timeZone);
+    if (p) parts.push(p);
+  }
+  if (parts.length < MIN_SAMPLES) return null;
+
+  // Weekday histogram.
+  const weekdayCounts = new Array<number>(7).fill(0);
+  for (const p of parts) weekdayCounts[p.weekday] += 1;
+  const topWeekday = Math.max(...weekdayCounts);
+  const weekdayShare = topWeekday / parts.length;
+  if (weekdayShare >= CLUSTER_THRESHOLD) {
+    return { kind: "weekday", share: weekdayShare };
+  }
+
+  // Time-of-day histogram (6-hour bands → 4 buckets).
+  const bandCount = Math.ceil(24 / TIME_BAND_HOURS);
+  const bandCounts = new Array<number>(bandCount).fill(0);
+  for (const p of parts) {
+    bandCounts[Math.floor(p.hour / TIME_BAND_HOURS) % bandCount] += 1;
+  }
+  const topBand = Math.max(...bandCounts);
+  const timeShare = topBand / parts.length;
+  if (timeShare >= CLUSTER_THRESHOLD) {
+    return { kind: "timeOfDay", share: timeShare };
+  }
+
+  return null;
+}
diff --git a/src/lib/query-keys.ts b/src/lib/query-keys.ts
index cd302d53f..4c223cffa 100644
--- a/src/lib/query-keys.ts
+++ b/src/lib/query-keys.ts
@@ -374,6 +374,16 @@ export const queryKeys = {
       toIso,
       valueScale,
     ] as const,
+
+  /**
+   * v1.8.5 — bounded recent-timestamp read powering the
+   * measurement-diversity nudge on an insights category page. Keyed by
+   * the page's `MeasurementType` so each metric caches its own window.
+   * Shares the `measurement-dependent` invalidation prefix below so an
+   * edit/delete in the values subpage re-runs the clustering check.
+   */
+  measurementDiversity: (type: string) =>
+    ["measurement-diversity", type] as const,
 };
 
 /**
@@ -394,6 +404,8 @@ export const measurementDependentKeys = [
   queryKeys.insightsTargets(),
   queryKeys.gamificationAchievements(),
   ["chart-data"] as const,
+  // v1.8.5 — re-run the diversity-nudge clustering when readings change.
+  ["measurement-diversity"] as const,
 ];
 
 /**

From 5de9ddb0ccf13f0ed3f90f1d84a1c2a7f1914f0e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 20:06:11 +0200
Subject: [PATCH 11/30] feat(insights): drive the Trends charts from the daily
 briefing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The overview Trends row used to render a fixed BP / weight / mood
triple regardless of what the day's data surfaced. It now mirrors the
daily briefing: the row charts exactly the metrics the briefing flags,
in the briefing's priority order, deduped and capped at three. When no
briefing is available — cold mount, a web-only account with no
findings, or a pre-briefing cached payload — selection falls back to
the legacy BP / weight / mood triple so the row never paints empty.

Selection lives in `trend-chart-select.ts` as a pure, unit-tested
mapping from each briefing `sourceMetric` to a chart descriptor
(series, colour, unit, title key). Adherence-context findings
(compliance, GLP-1 plateau) have no standalone trend series and are
skipped so the next finding fills the slot. Annotations stay on the
legacy triple; additive HealthKit metrics render chart-only. The chart
set is derived from the briefing payload already on the page, so there
is no new blocking call.
---
 messages/de.json                              |   7 +
 messages/en.json                              |   7 +
 messages/es.json                              |   7 +
 messages/fr.json                              |   7 +
 messages/it.json                              |   7 +
 messages/pl.json                              |   7 +
 src/app/insights/page.tsx                     |   1 +
 .../insights/__tests__/trends-row.test.tsx    |  55 ++++
 src/components/insights/trends-row.tsx        | 192 +++++++------
 .../__tests__/trend-chart-select.test.ts      | 141 +++++++++
 src/lib/insights/trend-chart-select.ts        | 268 ++++++++++++++++++
 11 files changed, 609 insertions(+), 90 deletions(-)
 create mode 100644 src/lib/insights/__tests__/trend-chart-select.test.ts
 create mode 100644 src/lib/insights/trend-chart-select.ts

diff --git a/messages/de.json b/messages/de.json
index b77f2b496..427e7d436 100644
--- a/messages/de.json
+++ b/messages/de.json
@@ -1335,6 +1335,13 @@
     "bodyFat": "Körperfett",
     "sleep": "Schlaf",
     "steps": "Schritte",
+    "hrv": "HRV",
+    "restingHeartRate": "Ruhepuls",
+    "activeEnergy": "Aktive Energie",
+    "flights": "Treppen",
+    "distance": "Geh- + Laufstrecke",
+    "vo2Max": "VO₂max",
+    "bodyTemperature": "Körpertemperatur",
     "noData": "Keine Daten im gewählten Zeitraum",
     "bucketWeekly": "Wochendurchschnitt",
     "bucketMonthly": "Monatsdurchschnitt",
diff --git a/messages/en.json b/messages/en.json
index 29888b6f3..f89b859b5 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -1335,6 +1335,13 @@
     "bodyFat": "Body Fat",
     "sleep": "Sleep",
     "steps": "Steps",
+    "hrv": "HRV",
+    "restingHeartRate": "Resting heart rate",
+    "activeEnergy": "Active energy",
+    "flights": "Flights climbed",
+    "distance": "Walking + running distance",
+    "vo2Max": "VO₂ max",
+    "bodyTemperature": "Body temperature",
     "noData": "No data in selected time range",
     "bucketWeekly": "Weekly avg",
     "bucketMonthly": "Monthly avg",
diff --git a/messages/es.json b/messages/es.json
index dfe8993b0..4e03cd711 100644
--- a/messages/es.json
+++ b/messages/es.json
@@ -1335,6 +1335,13 @@
     "bodyFat": "Grasa corporal",
     "sleep": "Sueño",
     "steps": "Pasos",
+    "hrv": "VFC",
+    "restingHeartRate": "FC en reposo",
+    "activeEnergy": "Energía activa",
+    "flights": "Pisos subidos",
+    "distance": "Distancia a pie + corriendo",
+    "vo2Max": "VO₂ máx",
+    "bodyTemperature": "Temperatura corporal",
     "noData": "Sin datos en el periodo seleccionado",
     "bucketWeekly": "Media semanal",
     "bucketMonthly": "Media mensual",
diff --git a/messages/fr.json b/messages/fr.json
index 7ae6e73a1..798d3d114 100644
--- a/messages/fr.json
+++ b/messages/fr.json
@@ -1335,6 +1335,13 @@
     "bodyFat": "Masse grasse",
     "sleep": "Sommeil",
     "steps": "Pas",
+    "hrv": "VFC",
+    "restingHeartRate": "FC au repos",
+    "activeEnergy": "Énergie active",
+    "flights": "Étages gravis",
+    "distance": "Distance marche + course",
+    "vo2Max": "VO₂ max",
+    "bodyTemperature": "Température corporelle",
     "noData": "Aucune donnée sur la période sélectionnée",
     "bucketWeekly": "Moyenne hebdomadaire",
     "bucketMonthly": "Moyenne mensuelle",
diff --git a/messages/it.json b/messages/it.json
index d290ac44f..28e18988d 100644
--- a/messages/it.json
+++ b/messages/it.json
@@ -1335,6 +1335,13 @@
     "bodyFat": "Massa grassa",
     "sleep": "Sonno",
     "steps": "Passi",
+    "hrv": "HRV",
+    "restingHeartRate": "FC a riposo",
+    "activeEnergy": "Energia attiva",
+    "flights": "Piani saliti",
+    "distance": "Distanza camminata + corsa",
+    "vo2Max": "VO₂ max",
+    "bodyTemperature": "Temperatura corporea",
     "noData": "Nessun dato nel periodo selezionato",
     "bucketWeekly": "Media settimanale",
     "bucketMonthly": "Media mensile",
diff --git a/messages/pl.json b/messages/pl.json
index c511d661f..3b1764904 100644
--- a/messages/pl.json
+++ b/messages/pl.json
@@ -1335,6 +1335,13 @@
     "bodyFat": "Tkanka tłuszczowa",
     "sleep": "Sen",
     "steps": "Kroki",
+    "hrv": "HRV",
+    "restingHeartRate": "Tętno spoczynkowe",
+    "activeEnergy": "Energia czynna",
+    "flights": "Pokonane piętra",
+    "distance": "Dystans marsz + bieg",
+    "vo2Max": "VO₂ max",
+    "bodyTemperature": "Temperatura ciała",
     "noData": "Brak danych w wybranym okresie",
     "bucketWeekly": "Średnia tygodniowa",
     "bucketMonthly": "Średnia miesięczna",
diff --git a/src/app/insights/page.tsx b/src/app/insights/page.tsx
index a7df175c1..0153fc9d9 100644
--- a/src/app/insights/page.tsx
+++ b/src/app/insights/page.tsx
@@ -225,6 +225,7 @@ export default function InsightsPage() {
       )}
 
       <TrendsRow
+        briefing={briefingPayload}
         annotations={advisor.payload?.trendAnnotations ?? null}
         loading={advisor.isLoading || advisor.isRegenerating}
       />
diff --git a/src/components/insights/__tests__/trends-row.test.tsx b/src/components/insights/__tests__/trends-row.test.tsx
index 7c518b0a2..490189708 100644
--- a/src/components/insights/__tests__/trends-row.test.tsx
+++ b/src/components/insights/__tests__/trends-row.test.tsx
@@ -30,6 +30,23 @@ vi.mock("next/dynamic", () => ({
 }));
 
 import { TrendsRow } from "../trends-row";
+import type { DailyBriefing } from "@/lib/ai/schema";
+
+function briefing(
+  metrics: DailyBriefing["keyFindings"][number]["sourceMetric"][],
+): DailyBriefing {
+  return {
+    paragraph: "Synthesised briefing paragraph.",
+    keyFindings: metrics.map((sourceMetric) => ({
+      tone: "watch" as const,
+      headline: `${sourceMetric} headline`,
+      detail: `${sourceMetric} detail`,
+      delta: null,
+      sourceWindow: "30d" as const,
+      sourceMetric,
+    })),
+  };
+}
 
 function render(node: React.ReactNode, locale: "en" | "de" = "en") {
   const queryClient = new QueryClient({
@@ -165,6 +182,44 @@ describe("<TrendsRow>", () => {
     expect(pending.length).toBe(3);
   });
 
+  // ── v1.8.5 — dynamic chart set driven by the daily briefing ───────
+  it("charts the metrics the briefing flags, in briefing order", () => {
+    const html = render(
+      <TrendsRow briefing={briefing(["weight", "pulse", "sleep"])} />,
+    );
+    expect(html).toMatch(/data-metric="weight"/);
+    expect(html).toMatch(/data-metric="pulse"/);
+    expect(html).toMatch(/data-metric="sleep"/);
+    // The default BP / mood tiles drop out when the briefing flags
+    // other metrics.
+    expect(html).not.toMatch(/data-metric="bp"/);
+    expect(html).not.toMatch(/data-metric="mood"/);
+  });
+
+  it("caps the briefing-driven set at three tiles", () => {
+    const html = render(
+      <TrendsRow
+        briefing={briefing(["weight", "pulse", "sleep", "hrv", "steps"])}
+      />,
+    );
+    const cards = html.match(/data-slot="trends-row-card"/g) ?? [];
+    expect(cards.length).toBe(3);
+  });
+
+  it("falls back to BP / weight / mood when the briefing is empty", () => {
+    const html = render(<TrendsRow briefing={briefing([])} />);
+    expect(html).toMatch(/data-metric="bp"/);
+    expect(html).toMatch(/data-metric="weight"/);
+    expect(html).toMatch(/data-metric="mood"/);
+  });
+
+  it("renders additive metrics chart-only (no annotation slot)", () => {
+    const html = render(<TrendsRow briefing={briefing(["pulse"])} />);
+    expect(html).toMatch(/data-metric="pulse"/);
+    // No TrendAnnotation empty/pending slot for a chart-only tile.
+    expect(html).not.toMatch(/data-slot="trend-annotation-empty"/);
+  });
+
   it("propagates per-metric confidence chips", () => {
     const html = render(
       <TrendsRow
diff --git a/src/components/insights/trends-row.tsx b/src/components/insights/trends-row.tsx
index 88ecd7322..155f5c0d0 100644
--- a/src/components/insights/trends-row.tsx
+++ b/src/components/insights/trends-row.tsx
@@ -5,6 +5,12 @@ import { useTranslations } from "@/lib/i18n/context";
 import { useAuth } from "@/hooks/use-auth";
 import { ChartSkeleton } from "@/components/charts/chart-skeleton";
 import { HealthChartDynamicMini } from "@/components/charts/health-chart-dynamic";
+import type { DailyBriefing } from "@/lib/ai/schema";
+import {
+  selectTrendCharts,
+  type TrendAnnotationKey,
+  type TrendChartConfig,
+} from "@/lib/insights/trend-chart-select";
 import {
   TrendAnnotation,
   type TrendAnnotationConfidenceBand,
@@ -12,20 +18,30 @@ import {
 } from "./trend-annotation";
 
 /**
- * Trends row — three small charts (BP / Weight / Mood) above a
- * one-sentence assessment each. Recharts is ~108 KiB Brotli, so the
- * three charts ride the shared lazy-import boundary
- * (`<HealthChartDynamicDynamic>` for BP + weight; MoodChart still resolves
- * locally because no shared re-export exists yet for it).
+ * Trends row — a small chart per metric above a one-sentence
+ * assessment. Recharts is ~108 KiB Brotli, so the charts ride the
+ * shared lazy-import boundary (`<HealthChartDynamicMini>` for every
+ * measurement series; `<MoodChart>` resolves locally because no shared
+ * re-export exists for it yet).
+ *
+ * v1.8.5 — the chart set is DYNAMIC. It mirrors the daily briefing:
+ * the row charts exactly the metrics the briefing flags, in the
+ * briefing's priority order, deduped and capped (top three). When no
+ * briefing is available — cold mount, web-only account with no
+ * findings, or a pre-briefing cached payload — `selectTrendCharts`
+ * falls back to the legacy BP / weight / mood triple so the row never
+ * paints empty. Selection lives in `@/lib/insights/trend-chart-select`
+ * (pure + unit-tested); this component is the renderer.
  *
  * Layout:
  *   - `<md`: single column, full width
  *   - `>=md`: 3-up grid, equal column tracks
  *
  * Annotations come from `trendAnnotations.{bp,weight,mood}` on the
- * Insights payload. When a metric's annotation is null, the
- * `<TrendAnnotation>` empty state hints at the gap without breaking
- * the row's visual rhythm.
+ * Insights payload and only attach to those three slots (the advisor
+ * authors annotations for the legacy triple). Additive metrics render
+ * chart-only. When a slot's annotation is null, `<TrendAnnotation>`'s
+ * empty state hints at the gap without breaking the row's rhythm.
  */
 
 const MoodChart = dynamic(
@@ -38,9 +54,16 @@ const MoodChart = dynamic(
 
 interface TrendsRowProps {
   /**
-   * Assistant-authored one-sentence annotations, keyed by metric. Optional —
-   * legacy advisor payloads (pre-PROMPT_VERSION 4.20.1) won't carry
-   * the field.
+   * Daily briefing payload. Drives the chart set: the row charts the
+   * metrics the briefing flags, in order, deduped + capped. `null` /
+   * omitted → the default BP / weight / mood triple.
+   */
+  briefing?: DailyBriefing | null;
+  /**
+   * Assistant-authored one-sentence annotations, keyed by metric. Only
+   * the legacy triple (bp / weight / mood) carries annotations.
+   * Optional — legacy advisor payloads (pre-PROMPT_VERSION 4.20.1)
+   * won't carry the field.
    */
   annotations?: {
     bp?: string | null;
@@ -67,17 +90,38 @@ interface TrendsRowProps {
   loading?: boolean;
 }
 
+function MetricChart({ config, title }: { config: TrendChartConfig; title: string }) {
+  const { user } = useAuth();
+  const userTimezone = user?.timezone;
+  if (config.kind === "mood") {
+    return <MoodChart title={title} mini userTimezone={userTimezone} />;
+  }
+  return (
+    <HealthChartDynamicMini
+      types={config.types}
+      title={title}
+      colors={config.colors}
+      unit={config.unit}
+      yAxisUnit={config.yAxisUnit}
+      mini
+      userTimezone={userTimezone}
+    />
+  );
+}
+
 export function TrendsRow({
+  briefing,
   annotations,
   confidence,
   loading = false,
 }: TrendsRowProps) {
   const { t } = useTranslations();
-  const { user } = useAuth();
-  const userTimezone = user?.timezone;
-  const bpAnnotation = annotations?.bp ?? null;
-  const weightAnnotation = annotations?.weight ?? null;
-  const moodAnnotation = annotations?.mood ?? null;
+
+  // v1.8.5 — derive the chart set from the briefing. No new fetch: the
+  // briefing payload is already on the page (advisor cache), so this is
+  // a pure read that respects the v1.8.3 anti-freeze contract.
+  const charts = selectTrendCharts(briefing);
+
   // v1.4.36 W2 T3 — derive the tri-state status per metric from the
   // advisor's loading flag + the annotation presence. Pending wins
   // over needs_data so a mid-generation regenerate doesn't flash the
@@ -87,6 +131,9 @@ export function TrendsRow({
     return annotation ? "generated" : "needs_data";
   };
 
+  const annotationFor = (key: TrendAnnotationKey): string | null =>
+    annotations?.[key] ?? null;
+
   return (
     <section
       data-slot="trends-row"
@@ -122,81 +169,46 @@ export function TrendsRow({
           mobile single-column path picks up the same row contract
           when the user expands the strip side-by-side via the
           orientation-change. The chart slot is now wrapped in a
-          fixed-height shell so BP / weight / mood all paint the
-          series at the same vertical position; the annotation slot
-          clamps via `<TrendAnnotation>` so long captions can't pull
-          the row taller than the design constant. */}
+          fixed-height shell so the series paint at the same vertical
+          position; the annotation slot clamps via `<TrendAnnotation>`
+          so long captions can't pull the row taller than the design
+          constant.
+
+          v1.8.5 — the cards are now rendered from the dynamic chart
+          set instead of three hard-coded tiles. The grid + slot
+          contract is unchanged; the card count tracks the briefing
+          (capped at three so the 3-up template still holds). */}
       <div className="grid auto-rows-fr grid-cols-1 gap-4 md:grid-cols-3 md:items-stretch">
-        <div
-          data-slot="trends-row-card"
-          data-metric="bp"
-          className="flex h-full flex-col gap-2 md:min-h-[300px]"
-        >
-          {/* v1.4.28 R3c-Insights — fixed chart slot. `<HealthChartDynamic>`
-              mini paints its own 140 px chart band; this wrapper pins
-              the total chart-envelope height so the mood tile's Card
-              wrapper (which carries a heavier shell on a default
-              shadcn Card) lines up with the BP/weight tiles' lighter
-              shell. Both chart types ship the same data-slot now. */}
-          <div data-slot="trends-row-chart-slot" className="h-[180px] shrink-0">
-            <HealthChartDynamicMini
-              types={["BLOOD_PRESSURE_SYS", "BLOOD_PRESSURE_DIA"]}
-              title={t("charts.bloodPressure")}
-              colors={["#ff79c6", "#8be9fd"]}
-              unit="mmHg"
-              yAxisUnit="mmHg"
-              mini
-              userTimezone={userTimezone}
-            />
-          </div>
-          <TrendAnnotation
-            metric="bp"
-            annotation={bpAnnotation}
-            confidence={confidence?.bp}
-            status={statusFor(bpAnnotation)}
-          />
-        </div>
-        <div
-          data-slot="trends-row-card"
-          data-metric="weight"
-          className="flex h-full flex-col gap-2 md:min-h-[300px]"
-        >
-          <div data-slot="trends-row-chart-slot" className="h-[180px] shrink-0">
-            <HealthChartDynamicMini
-              types={["WEIGHT"]}
-              title={t("charts.weight")}
-              colors={["#bd93f9"]}
-              unit="kg"
-              mini
-              userTimezone={userTimezone}
-            />
-          </div>
-          <TrendAnnotation
-            metric="weight"
-            annotation={weightAnnotation}
-            confidence={confidence?.weight}
-            status={statusFor(weightAnnotation)}
-          />
-        </div>
-        <div
-          data-slot="trends-row-card"
-          data-metric="mood"
-          className="flex h-full flex-col gap-2 md:min-h-[300px]"
-        >
-          <div data-slot="trends-row-chart-slot" className="h-[180px] shrink-0">
-            <MoodChart
-              title={t("charts.mood")}
-              mini
-              userTimezone={userTimezone}
-            />
-          </div>
-          <TrendAnnotation
-            metric="mood"
-            annotation={moodAnnotation}
-            confidence={confidence?.mood}
-            status={statusFor(moodAnnotation)}
-          />
-        </div>
+        {charts.map((config) => {
+          const title = t(config.titleKey);
+          return (
+            <div
+              key={config.metric}
+              data-slot="trends-row-card"
+              data-metric={config.metric}
+              className="flex h-full flex-col gap-2 md:min-h-[300px]"
+            >
+              {/* v1.4.28 R3c-Insights — fixed chart slot. The mini
+                  chart paints its own band; this wrapper pins the
+                  total chart-envelope height so every tile lines up on
+                  a single baseline regardless of the chart kind. */}
+              <div
+                data-slot="trends-row-chart-slot"
+                className="h-[180px] shrink-0"
+              >
+                <MetricChart config={config} title={title} />
+              </div>
+              {config.annotationKey ? (
+                <TrendAnnotation
+                  metric={config.annotationKey}
+                  annotation={annotationFor(config.annotationKey)}
+                  confidence={confidence?.[config.annotationKey]}
+                  status={statusFor(annotationFor(config.annotationKey))}
+                />
+              ) : null}
+            </div>
+          );
+        })}
       </div>
     </section>
   );
diff --git a/src/lib/insights/__tests__/trend-chart-select.test.ts b/src/lib/insights/__tests__/trend-chart-select.test.ts
new file mode 100644
index 000000000..49f58b2f1
--- /dev/null
+++ b/src/lib/insights/__tests__/trend-chart-select.test.ts
@@ -0,0 +1,141 @@
+import { describe, it, expect } from "vitest";
+
+import type {
+  DailyBriefing,
+  DailyBriefingKeyFinding,
+} from "@/lib/ai/schema";
+import {
+  selectTrendCharts,
+  DEFAULT_TREND_CHART_CAP,
+  TREND_CHART_CONFIG,
+} from "../trend-chart-select";
+
+/**
+ * v1.8.5 — the Trends row charts the metrics the daily briefing flags,
+ * in briefing order, deduped, capped, with the legacy BP / weight /
+ * mood triple as the fallback. These tests pin the selection contract;
+ * the renderer is a thin consumer.
+ */
+
+function finding(
+  sourceMetric: DailyBriefingKeyFinding["sourceMetric"],
+): DailyBriefingKeyFinding {
+  return {
+    tone: "watch",
+    headline: `${sourceMetric} headline`,
+    detail: `${sourceMetric} detail`,
+    delta: null,
+    sourceWindow: "30d",
+    sourceMetric,
+  };
+}
+
+function briefing(
+  metrics: DailyBriefingKeyFinding["sourceMetric"][],
+): DailyBriefing {
+  return {
+    paragraph: "Synthesised briefing paragraph.",
+    keyFindings: metrics.map(finding),
+  };
+}
+
+describe("selectTrendCharts", () => {
+  it("falls back to the BP / weight / mood triple when the briefing is null", () => {
+    const charts = selectTrendCharts(null);
+    expect(charts.map((c) => c.metric)).toEqual(["bp", "weight", "mood"]);
+  });
+
+  it("falls back to the default triple when the briefing is undefined", () => {
+    const charts = selectTrendCharts(undefined);
+    expect(charts.map((c) => c.metric)).toEqual(["bp", "weight", "mood"]);
+  });
+
+  it("falls back when the briefing carries no key findings", () => {
+    const charts = selectTrendCharts(briefing([]));
+    expect(charts.map((c) => c.metric)).toEqual(["bp", "weight", "mood"]);
+  });
+
+  it("charts exactly the metrics the briefing flags, in briefing order", () => {
+    const charts = selectTrendCharts(briefing(["weight", "pulse", "sleep"]));
+    expect(charts.map((c) => c.metric)).toEqual(["weight", "pulse", "sleep"]);
+  });
+
+  it("dedupes repeated metrics, keeping first-seen order", () => {
+    const charts = selectTrendCharts(
+      briefing(["bp", "weight", "bp", "pulse"]),
+    );
+    expect(charts.map((c) => c.metric)).toEqual(["bp", "weight", "pulse"]);
+  });
+
+  it("caps at the default of three", () => {
+    const charts = selectTrendCharts(
+      briefing(["weight", "pulse", "sleep", "hrv", "steps"]),
+    );
+    expect(charts).toHaveLength(DEFAULT_TREND_CHART_CAP);
+    expect(charts.map((c) => c.metric)).toEqual(["weight", "pulse", "sleep"]);
+  });
+
+  it("honours a custom cap", () => {
+    const charts = selectTrendCharts(briefing(["weight", "pulse", "sleep"]), {
+      cap: 2,
+    });
+    expect(charts.map((c) => c.metric)).toEqual(["weight", "pulse"]);
+  });
+
+  it("clamps a zero/negative cap to at least one", () => {
+    const charts = selectTrendCharts(briefing(["weight", "pulse"]), { cap: 0 });
+    expect(charts).toHaveLength(1);
+    expect(charts[0].metric).toBe("weight");
+  });
+
+  it("skips metrics with no standalone trend chart (compliance, glp1_plateau)", () => {
+    const charts = selectTrendCharts(
+      briefing(["compliance", "weight", "glp1_plateau", "pulse"]),
+    );
+    expect(charts.map((c) => c.metric)).toEqual(["weight", "pulse"]);
+  });
+
+  it("falls back to the default triple when every finding is chartless", () => {
+    const charts = selectTrendCharts(briefing(["compliance", "glp1_plateau"]));
+    expect(charts.map((c) => c.metric)).toEqual(["bp", "weight", "mood"]);
+  });
+
+  it("resolves additive HealthKit metrics to a chart config", () => {
+    const charts = selectTrendCharts(briefing(["hrv", "active_energy"]));
+    expect(charts.map((c) => c.metric)).toEqual(["hrv", "active_energy"]);
+    expect(charts[0].types).toEqual(["HEART_RATE_VARIABILITY"]);
+    expect(charts[1].types).toEqual(["ACTIVE_ENERGY_BURNED"]);
+  });
+
+  it("carries an annotation key only for the legacy triple", () => {
+    const charts = selectTrendCharts(
+      briefing(["bp", "weight", "mood"]),
+    );
+    expect(charts.map((c) => c.annotationKey)).toEqual([
+      "bp",
+      "weight",
+      "mood",
+    ]);
+    const pulseCharts = selectTrendCharts(briefing(["pulse"]));
+    expect(pulseCharts[0].annotationKey).toBeUndefined();
+  });
+
+  it("maps the mood slot to the bespoke mood chart kind", () => {
+    const charts = selectTrendCharts(briefing(["mood"]));
+    expect(charts[0].kind).toBe("mood");
+    expect(charts[0].types).toEqual([]);
+  });
+
+  it("every chart-bearing sourceMetric resolves to a non-empty health-chart series", () => {
+    for (const [metric, config] of Object.entries(TREND_CHART_CONFIG)) {
+      if (!config) continue;
+      if (config.kind === "health-chart") {
+        expect(config.types.length, `${metric} types`).toBeGreaterThan(0);
+        expect(
+          config.colors.length,
+          `${metric} colors`,
+        ).toBeGreaterThanOrEqual(config.types.length);
+      }
+    }
+  });
+});
diff --git a/src/lib/insights/trend-chart-select.ts b/src/lib/insights/trend-chart-select.ts
new file mode 100644
index 000000000..bfdd9f8d5
--- /dev/null
+++ b/src/lib/insights/trend-chart-select.ts
@@ -0,0 +1,268 @@
+import type {
+  DailyBriefing,
+  DailyBriefingKeyFinding,
+} from "@/lib/ai/schema";
+
+/**
+ * v1.8.5 — derive the Insights overview "Trends" chart set from the
+ * daily briefing.
+ *
+ * The Trends row used to be a fixed BP / weight / mood triple. The
+ * briefing already surfaces the day's load-bearing findings (each one
+ * tied to a `sourceMetric`), so the row should chart exactly those
+ * flagged metrics — in the briefing's own priority order, deduped,
+ * capped, with the legacy triple as the fallback when the briefing is
+ * empty or unavailable.
+ *
+ * This module is the pure mapping layer:
+ *   - `TREND_CHART_CONFIG` maps every briefing `sourceMetric` to a
+ *     concrete chart descriptor (which measurement series to plot, its
+ *     colour + unit + i18n title key, and whether the advisor supplies
+ *     a one-sentence annotation for it).
+ *   - `selectTrendCharts(briefing, opts)` walks the briefing findings,
+ *     resolves each to a chart slot, dedupes, caps, and falls back to
+ *     the default triple when nothing usable surfaces.
+ *
+ * Kept free of React/Recharts so the selection logic is unit-testable
+ * in isolation and the renderer stays a thin consumer.
+ */
+
+/**
+ * The annotation key the advisor populates for a slot, when one exists.
+ * Only the legacy triple (bp / weight / mood) carries AI annotations in
+ * `trendAnnotations`; every additive metric renders chart-only.
+ */
+export type TrendAnnotationKey = "bp" | "weight" | "mood";
+
+/**
+ * How the slot's chart is rendered. `mood` resolves to the bespoke
+ * `<MoodChart>` (self-fetching, no measurement-type series); every
+ * other slot resolves to `<HealthChart>` driven by `types`.
+ */
+export type TrendChartKind = "health-chart" | "mood";
+
+export interface TrendChartConfig {
+  /** Stable slot id — used as the `data-metric` attribute + React key. */
+  metric: string;
+  /** Which chart component to mount. */
+  kind: TrendChartKind;
+  /**
+   * Measurement series for the `health-chart` kind. Empty for `mood`
+   * (the mood chart self-fetches its own aggregate).
+   */
+  types: string[];
+  /** Recharts stroke colours, positionally matched to `types`. */
+  colors: string[];
+  /** Display unit (chart legend / tooltip). */
+  unit?: string;
+  /** Y-axis unit label when it differs from the value unit. */
+  yAxisUnit?: string;
+  /** i18n key for the chart title (`charts.*`). */
+  titleKey: string;
+  /**
+   * When set, the slot carries an advisor annotation under the chart
+   * and uses the typed `<TrendAnnotation>` empty-state copy. Omitted
+   * for additive metrics that render chart-only.
+   */
+  annotationKey?: TrendAnnotationKey;
+}
+
+/**
+ * Per-`sourceMetric` chart descriptor. `null` marks a metric that has
+ * no standalone trend chart in this row (compliance + the GLP-1
+ * plateau finding are adherence-context observations, not a single
+ * plottable series), so a finding on that metric is skipped during
+ * selection and the next finding fills the slot instead.
+ *
+ * Colours + units mirror the dedicated sub-pages so a metric looks
+ * identical whether the user lands on it here or on `/insights/<slug>`.
+ */
+export const TREND_CHART_CONFIG: Record<
+  DailyBriefingKeyFinding["sourceMetric"],
+  TrendChartConfig | null
+> = {
+  bp: {
+    metric: "bp",
+    kind: "health-chart",
+    types: ["BLOOD_PRESSURE_SYS", "BLOOD_PRESSURE_DIA"],
+    colors: ["#ff79c6", "#8be9fd"],
+    unit: "mmHg",
+    yAxisUnit: "mmHg",
+    titleKey: "charts.bloodPressure",
+    annotationKey: "bp",
+  },
+  weight: {
+    metric: "weight",
+    kind: "health-chart",
+    types: ["WEIGHT"],
+    colors: ["#bd93f9"],
+    unit: "kg",
+    titleKey: "charts.weight",
+    annotationKey: "weight",
+  },
+  pulse: {
+    metric: "pulse",
+    kind: "health-chart",
+    types: ["PULSE"],
+    colors: ["#50fa7b"],
+    unit: "bpm",
+    yAxisUnit: "bpm",
+    titleKey: "charts.pulse",
+  },
+  mood: {
+    metric: "mood",
+    kind: "mood",
+    types: [],
+    colors: [],
+    titleKey: "charts.mood",
+    annotationKey: "mood",
+  },
+  sleep: {
+    metric: "sleep",
+    kind: "health-chart",
+    types: ["SLEEP_DURATION"],
+    colors: ["#8be9fd"],
+    unit: "h",
+    yAxisUnit: "h",
+    titleKey: "charts.sleep",
+  },
+  steps: {
+    metric: "steps",
+    kind: "health-chart",
+    types: ["ACTIVITY_STEPS"],
+    colors: ["#50fa7b"],
+    unit: "steps",
+    yAxisUnit: "steps",
+    titleKey: "charts.steps",
+  },
+  hrv: {
+    metric: "hrv",
+    kind: "health-chart",
+    types: ["HEART_RATE_VARIABILITY"],
+    colors: ["#bd93f9"],
+    unit: "ms",
+    yAxisUnit: "ms",
+    titleKey: "charts.hrv",
+  },
+  resting_hr: {
+    metric: "resting_hr",
+    kind: "health-chart",
+    types: ["RESTING_HEART_RATE"],
+    colors: ["#ff79c6"],
+    unit: "bpm",
+    yAxisUnit: "bpm",
+    titleKey: "charts.restingHeartRate",
+  },
+  active_energy: {
+    metric: "active_energy",
+    kind: "health-chart",
+    types: ["ACTIVE_ENERGY_BURNED"],
+    colors: ["#ffb86c"],
+    unit: "kcal",
+    yAxisUnit: "kcal",
+    titleKey: "charts.activeEnergy",
+  },
+  flights: {
+    metric: "flights",
+    kind: "health-chart",
+    types: ["FLIGHTS_CLIMBED"],
+    colors: ["#f1fa8c"],
+    unit: "flights",
+    yAxisUnit: "flights",
+    titleKey: "charts.flights",
+  },
+  distance: {
+    metric: "distance",
+    kind: "health-chart",
+    types: ["WALKING_RUNNING_DISTANCE"],
+    colors: ["#8be9fd"],
+    unit: "km",
+    yAxisUnit: "km",
+    titleKey: "charts.distance",
+  },
+  vo2_max: {
+    metric: "vo2_max",
+    kind: "health-chart",
+    types: ["VO2_MAX"],
+    colors: ["#50fa7b"],
+    unit: "mL/kg·min",
+    yAxisUnit: "mL/kg·min",
+    titleKey: "charts.vo2Max",
+  },
+  body_temp: {
+    metric: "body_temp",
+    kind: "health-chart",
+    types: ["BODY_TEMPERATURE"],
+    colors: ["#ff5555"],
+    unit: "°C",
+    yAxisUnit: "°C",
+    titleKey: "charts.bodyTemperature",
+  },
+  // Adherence-context findings — no single plottable trend series in
+  // this row. A finding on one of these is skipped during selection so
+  // the next finding (or the default fallback) takes the slot.
+  compliance: null,
+  glp1_plateau: null,
+};
+
+/**
+ * Default chart set when the briefing is empty / unavailable. Mirrors
+ * the legacy fixed Trends triple so a cold mount, a web-only account
+ * with no findings, or a pre-briefing payload keeps the familiar
+ * BP / weight / mood row.
+ */
+export const DEFAULT_TREND_METRICS: ReadonlyArray<
+  DailyBriefingKeyFinding["sourceMetric"]
+> = ["bp", "weight", "mood"];
+
+/** Max charts the row renders. Three keeps the equal-height 3-up grid. */
+export const DEFAULT_TREND_CHART_CAP = 3;
+
+export interface SelectTrendChartsOptions {
+  /** Max number of charts to return. Defaults to {@link DEFAULT_TREND_CHART_CAP}. */
+  cap?: number;
+}
+
+function configsFor(
+  metrics: ReadonlyArray<DailyBriefingKeyFinding["sourceMetric"]>,
+  cap: number,
+): TrendChartConfig[] {
+  const seen = new Set<string>();
+  const out: TrendChartConfig[] = [];
+  for (const metric of metrics) {
+    if (out.length >= cap) break;
+    const config = TREND_CHART_CONFIG[metric];
+    if (!config) continue; // metric has no standalone trend chart
+    if (seen.has(config.metric)) continue; // dedupe
+    seen.add(config.metric);
+    out.push(config);
+  }
+  return out;
+}
+
+/**
+ * Resolve the Trends-row chart set from a daily briefing.
+ *
+ * Order follows the briefing's own `keyFindings` ordering (the model
+ * emits the most load-bearing finding first). Metrics are deduped on
+ * their chart slot and the result is capped. When the briefing is
+ * `null`, carries no findings, or every finding maps to a
+ * chartless metric, the default BP / weight / mood triple is returned
+ * so the row never paints empty.
+ */
+export function selectTrendCharts(
+  briefing: DailyBriefing | null | undefined,
+  options: SelectTrendChartsOptions = {},
+): TrendChartConfig[] {
+  const cap = Math.max(1, options.cap ?? DEFAULT_TREND_CHART_CAP);
+
+  const findingMetrics =
+    briefing?.keyFindings?.map((f) => f.sourceMetric) ?? [];
+  const fromBriefing = configsFor(findingMetrics, cap);
+
+  if (fromBriefing.length > 0) {
+    return fromBriefing;
+  }
+
+  return configsFor(DEFAULT_TREND_METRICS, cap);
+}

From 0f7ca61e2fb69b182a969da261d831035829f13d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 20:38:20 +0200
Subject: [PATCH 12/30] feat(insights): port the target reference panel onto
 the category pages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Grow the per-category insights target summary from a one-line range card
into a compact reference panel that surfaces the band range, the verbal
status, the guideline source, the in-target share, the 30-day average,
the range bar and the 7-day consistency strip — all from the Targets
data already on the wire, reading the same shared cache. Extract the
status pill and the source-link resolver into shared primitives so the
Targets card and the insights panel can never disagree, and wire blood
glucose into the summary with its per-context split and unit conversion.
---
 src/app/insights/blood-glucose/page.tsx       |   1 +
 src/app/targets/page.tsx                      |  36 +--
 .../__tests__/metric-target-summary.test.tsx  | 200 ++++++++++--
 .../insights/healthkit-metric-page.tsx        |  12 +
 .../insights/metric-target-summary.tsx        | 296 +++++++++++++++---
 .../__tests__/target-status-pill.test.tsx     |  72 +++++
 src/components/targets/target-card.tsx        | 166 +---------
 src/components/targets/target-status-pill.tsx | 220 +++++++++++++
 src/lib/targets/__tests__/source-link.test.ts |  66 ++++
 src/lib/targets/source-link.ts                |  44 +++
 10 files changed, 844 insertions(+), 269 deletions(-)
 create mode 100644 src/components/targets/__tests__/target-status-pill.test.tsx
 create mode 100644 src/components/targets/target-status-pill.tsx
 create mode 100644 src/lib/targets/__tests__/source-link.test.ts
 create mode 100644 src/lib/targets/source-link.ts

diff --git a/src/app/insights/blood-glucose/page.tsx b/src/app/insights/blood-glucose/page.tsx
index c71a5e9fa..d87b52c80 100644
--- a/src/app/insights/blood-glucose/page.tsx
+++ b/src/app/insights/blood-glucose/page.tsx
@@ -25,6 +25,7 @@ export default function InsightsBlutzuckerPage() {
       yAxisUnit="mg/dL"
       emptyStateIcon={<Droplet className="size-6" />}
       emptyStateCtaType={null}
+      targetSummarySlug="blood-glucose"
       coachPrefill="I haven't logged any blood glucose yet — what does this metric tell me about my health, and how do I improve it?"
     />
   );
diff --git a/src/app/targets/page.tsx b/src/app/targets/page.tsx
index 2775fd27b..9d6a9e49a 100644
--- a/src/app/targets/page.tsx
+++ b/src/app/targets/page.tsx
@@ -14,6 +14,7 @@ import {
   type TargetCardData,
 } from "@/components/targets/target-card";
 import { TargetsSummaryHeader } from "@/components/targets/targets-summary-header";
+import { getTargetSourceLink } from "@/lib/targets/source-link";
 import { CoachDrawer } from "@/components/insights/coach-panel/coach-drawer";
 import { useCoachHandoff } from "@/hooks/use-coach-handoff";
 import { useFeatureFlags } from "@/hooks/use-feature-flags";
@@ -92,41 +93,6 @@ function sortKey(target: TargetData): number {
   return FIXED_TARGET_ORDER[target.type] ?? 100;
 }
 
-/**
- * Source-citation URL for each target type. Kept on the page (rather
- * than the card) so the card stays presentational and the routing
- * stays declarative.
- */
-function getTargetSourceLink(target: TargetData): string | null {
-  if (target.type === "WEIGHT" || target.type === "BMI") {
-    return "https://www.who.int/news-room/fact-sheets/detail/obesity-and-overweight";
-  }
-  if (
-    target.type === "BLOOD_PRESSURE" ||
-    target.type === "BLOOD_PRESSURE_IN_TARGET"
-  ) {
-    return "https://academic.oup.com/eurheartj/article/39/33/3021/5079119";
-  }
-  if (target.type === "PULSE") {
-    if (target.source.includes("CDC/NCHS")) {
-      return "https://www.cdc.gov/nchs/data/nhsr/nhsr041.pdf";
-    }
-    if (target.source.includes("AHA")) {
-      return "https://www.heart.org/en/health-topics/high-blood-pressure/the-facts-about-high-blood-pressure/all-about-heart-rate-pulse";
-    }
-  }
-  if (target.type === "SLEEP_DURATION") {
-    return "https://aasm.org/seven-or-more-hours-of-sleep-per-night-a-health-necessity-for-adults/";
-  }
-  if (target.type === "BODY_FAT") {
-    return "https://www.acefitness.org/resources/everyone/blog/6596/what-are-the-guidelines-for-percentage-of-body-fat-loss/";
-  }
-  if (target.type === "ACTIVITY_STEPS") {
-    return "https://www.who.int/publications/i/item/9789240015128";
-  }
-  return null;
-}
-
 export default function TargetsPage() {
   const { t } = useTranslations();
   const { isAuthenticated, user } = useAuth();
diff --git a/src/components/insights/__tests__/metric-target-summary.test.tsx b/src/components/insights/__tests__/metric-target-summary.test.tsx
index 0d3ed5aa4..0ff5bbaf9 100644
--- a/src/components/insights/__tests__/metric-target-summary.test.tsx
+++ b/src/components/insights/__tests__/metric-target-summary.test.tsx
@@ -4,15 +4,18 @@ import { renderToStaticMarkup } from "react-dom/server";
 import { I18nProvider } from "@/lib/i18n/context";
 
 /**
- * v1.8.0 — `<MetricTargetSummary>` unit tests.
+ * v1.8.0 → v1.8.5 — `<MetricTargetSummary>` unit tests.
  *
- * The card surfaces the numeric target range + the in-target share on
- * each insights category page, reading the same `/api/insights/targets`
- * payload that powers `/targets`. The component depends on `useAuth`
- * (gate) and TanStack Query (`useQuery`) for the payload, so both are
- * mocked here and the assertions run through SSR — the load-bearing
- * behaviour is the range/share rendering + the slug→type mapping, not
- * the live fetch.
+ * The panel surfaces the numeric target range, the verbal status pill,
+ * the guideline source, the in-target share, the 30-day average, the
+ * range bar and the 7-day consistency strip on each insights category
+ * page, reading the same `/api/insights/targets` payload that powers
+ * `/targets`. The component depends on `useAuth` (gate) and TanStack
+ * Query (`useQuery`) for the payload, so both are mocked here and the
+ * assertions run through SSR — the load-bearing behaviour is the
+ * range/share/source rendering + the slug→type mapping (including the
+ * blood-glucose per-context split + unit conversion), not the live
+ * fetch.
  */
 
 vi.mock("@/hooks/use-auth", () => ({
@@ -26,17 +29,31 @@ vi.mock("@tanstack/react-query", () => ({
 
 const { MetricTargetSummary } = await import("../metric-target-summary");
 
+interface TargetFixtureItem {
+  type: string;
+  label: string;
+  current: number | null;
+  average30: number | null;
+  unit: string;
+  range: { min: number; max: number } | null;
+  classification: { category: string; color: string } | null;
+  source: string;
+  daysInRange7d: number;
+  daysLogged7d: number;
+  daysInRange30d: number;
+  daysLogged30d: number;
+  insufficientData: boolean;
+  consistency7d: ReadonlyArray<"in" | "near" | "out" | null>;
+}
+
 interface TargetsFixture {
-  targets: Array<{
-    type: string;
+  targets: TargetFixtureItem[];
+  bpDiastolic: {
     current: number | null;
-    unit: string;
+    average30: number | null;
     range: { min: number; max: number } | null;
-    daysInRange30d: number;
-    daysLogged30d: number;
-    insufficientData: boolean;
-  }>;
-  bpDiastolic: { current: number | null; range: { min: number; max: number } | null };
+  };
+  profile?: { glucoseUnit?: string | null };
 }
 
 function renderWith(slug: string, data: TargetsFixture | undefined) {
@@ -48,34 +65,87 @@ function renderWith(slug: string, data: TargetsFixture | undefined) {
   );
 }
 
+const WEIGHT_ITEM: TargetFixtureItem = {
+  type: "WEIGHT",
+  label: "Weight",
+  current: 72,
+  average30: 71.4,
+  unit: "kg",
+  range: { min: 60.1, max: 80.9 },
+  classification: { category: "Normal", color: "#50fa7b" },
+  source: "WHO BMI",
+  daysInRange7d: 5,
+  daysLogged7d: 7,
+  daysInRange30d: 18,
+  daysLogged30d: 24,
+  insufficientData: false,
+  consistency7d: ["in", "in", "near", "in", "out", "in", "in"],
+};
+
 const WEIGHT_DATA: TargetsFixture = {
-  targets: [
-    {
-      type: "WEIGHT",
-      current: 72,
-      unit: "kg",
-      range: { min: 60.1, max: 80.9 },
-      daysInRange30d: 18,
-      daysLogged30d: 24,
-      insufficientData: false,
-    },
-  ],
-  bpDiastolic: { current: null, range: null },
+  targets: [WEIGHT_ITEM],
+  bpDiastolic: { current: null, average30: null, range: null },
 };
 
 const BP_DATA: TargetsFixture = {
   targets: [
     {
       type: "BLOOD_PRESSURE",
+      label: "Blood pressure",
       current: 124,
+      average30: 122,
       unit: "mmHg",
       range: { min: 120, max: 129 },
+      classification: { category: "Optimal", color: "#50fa7b" },
+      source: "ESH 2023",
+      daysInRange7d: 3,
+      daysLogged7d: 6,
       daysInRange30d: 10,
       daysLogged30d: 20,
       insufficientData: false,
+      consistency7d: ["in", "near", "in", "out", "in", "near", "in"],
     },
   ],
-  bpDiastolic: { current: 78, range: { min: 70, max: 79 } },
+  bpDiastolic: { current: 78, average30: 76, range: { min: 70, max: 79 } },
+};
+
+const GLUCOSE_DATA: TargetsFixture = {
+  targets: [
+    {
+      type: "BLOOD_GLUCOSE_FASTING",
+      label: "targets.glucoseFasting",
+      current: 95,
+      average30: 92,
+      unit: "mg/dL",
+      range: { min: 70, max: 100 },
+      classification: { category: "Optimal", color: "#50fa7b" },
+      source: "ADA 2024 / DDG",
+      daysInRange7d: 4,
+      daysLogged7d: 5,
+      daysInRange30d: 12,
+      daysLogged30d: 15,
+      insufficientData: false,
+      consistency7d: ["in", "in", "near", "in", "in", "in", "in"],
+    },
+    {
+      type: "BLOOD_GLUCOSE_POSTPRANDIAL",
+      label: "targets.glucosePostprandial",
+      current: 140,
+      average30: 138,
+      unit: "mg/dL",
+      range: { min: 70, max: 140 },
+      classification: { category: "Optimal", color: "#50fa7b" },
+      source: "ADA 2024 / DDG",
+      daysInRange7d: 3,
+      daysLogged7d: 4,
+      daysInRange30d: 9,
+      daysLogged30d: 12,
+      insufficientData: false,
+      consistency7d: ["in", "near", "in", "in", null, "in", "in"],
+    },
+  ],
+  bpDiastolic: { current: null, average30: null, range: null },
+  profile: { glucoseUnit: "mg/dL" },
 };
 
 describe("<MetricTargetSummary>", () => {
@@ -87,10 +157,35 @@ describe("<MetricTargetSummary>", () => {
     expect(html).toContain("75% of logged days within target");
   });
 
+  it("renders the verbal status pill + the guideline source", () => {
+    const html = renderWith("weight", WEIGHT_DATA);
+    expect(html).toContain('data-slot="target-status-pill"');
+    // EN label for the "Normal" classification category.
+    expect(html).toContain("Normal");
+    // Source citation + external-link.
+    expect(html).toContain("Source: WHO BMI");
+    // The WHO obesity fact-sheet URL resolves for WEIGHT.
+    expect(html).toContain(
+      "who.int/news-room/fact-sheets/detail/obesity-and-overweight",
+    );
+  });
+
+  it("renders the range bar + the 30-day average + the consistency strip", () => {
+    const html = renderWith("weight", WEIGHT_DATA);
+    expect(html).toContain('data-slot="target-range-bar"');
+    expect(html).toContain('data-slot="consistency-strip"');
+    expect(html).toContain("30-day average: 71.4 kg");
+  });
+
   it("stitches the systolic + diastolic bands for blood pressure", () => {
     const html = renderWith("blood-pressure", BP_DATA);
     expect(html).toContain("Target: 120–129 / 70–79 mmHg");
     expect(html).toContain("50% of logged days within target");
+    // The diastolic range bar renders alongside the systolic one.
+    const barCount = (html.match(/data-slot="target-range-bar"/g) ?? []).length;
+    expect(barCount).toBe(2);
+    // 30-day average stitches the diastolic pair.
+    expect(html).toContain("30-day average: 122/76 mmHg");
   });
 
   it("renders the adjust-target link to /targets", () => {
@@ -99,13 +194,14 @@ describe("<MetricTargetSummary>", () => {
     expect(html).toContain("Adjust target range");
   });
 
-  it("suppresses the share when the route flags insufficient data", () => {
+  it("suppresses the share + strip when the route flags insufficient data", () => {
     const html = renderWith("weight", {
       ...WEIGHT_DATA,
-      targets: [{ ...WEIGHT_DATA.targets[0], insufficientData: true }],
+      targets: [{ ...WEIGHT_ITEM, insufficientData: true }],
     });
     expect(html).toContain("Target: 60.1–80.9 kg");
     expect(html).not.toContain("of logged days within target");
+    expect(html).not.toContain('data-slot="consistency-strip"');
   });
 
   it("renders nothing for a slug without a numeric target", () => {
@@ -121,8 +217,48 @@ describe("<MetricTargetSummary>", () => {
   it("renders nothing when the matching target has no range", () => {
     const html = renderWith("weight", {
       ...WEIGHT_DATA,
-      targets: [{ ...WEIGHT_DATA.targets[0], range: null }],
+      targets: [{ ...WEIGHT_ITEM, range: null }],
     });
     expect(html).toBe("");
   });
+
+  describe("blood-glucose per-context split", () => {
+    it("renders one panel per logged glucose context in mg/dL", () => {
+      const html = renderWith("blood-glucose", GLUCOSE_DATA);
+      const panelCount = (
+        html.match(/data-slot="metric-target-summary"/g) ?? []
+      ).length;
+      expect(panelCount).toBe(2);
+      // mg/dL display unit keeps the canonical values unchanged.
+      expect(html).toContain("Target: 70–100 mg/dL");
+      expect(html).toContain("Target: 70–140 mg/dL");
+      // ADA / DDG source surfaces for each panel.
+      expect(html).toContain("Source: ADA 2024 / DDG");
+      // The i18n label keys resolve to EN context headings (rendered
+      // upper-cased by the heading style but kept as text content).
+      expect(html).toContain("Glucose — fasting");
+      expect(html).toContain("Glucose — post-meal");
+    });
+
+    it("converts the glucose bands to mmol/L when the profile prefers it", () => {
+      const html = renderWith("blood-glucose", {
+        ...GLUCOSE_DATA,
+        profile: { glucoseUnit: "mmol/L" },
+      });
+      // 70 mg/dL → 3.9, 100 mg/dL → 5.5, 140 mg/dL → 7.8 mmol/L
+      // (the /targets converter rounds to one decimal).
+      expect(html).toContain("Target: 3.9–5.5 mmol/L");
+      expect(html).toContain("Target: 3.9–7.8 mmol/L");
+      expect(html).toContain("mmol/L");
+    });
+
+    it("renders nothing when no glucose context has a band", () => {
+      const html = renderWith("blood-glucose", {
+        targets: [],
+        bpDiastolic: { current: null, average30: null, range: null },
+        profile: { glucoseUnit: "mg/dL" },
+      });
+      expect(html).toBe("");
+    });
+  });
 });
diff --git a/src/components/insights/healthkit-metric-page.tsx b/src/components/insights/healthkit-metric-page.tsx
index 2b0f0ad0d..6394144d5 100644
--- a/src/components/insights/healthkit-metric-page.tsx
+++ b/src/components/insights/healthkit-metric-page.tsx
@@ -15,6 +15,7 @@ import { HealthChartDynamic } from "@/components/charts/health-chart-dynamic";
 import { MetricEmptyState } from "@/components/insights/metric-empty-state";
 import { MetricStatStrip } from "@/components/insights/metric-stat-strip";
 import { MeasurementDiversityNudge } from "@/components/insights/measurement-diversity-nudge";
+import { MetricTargetSummary } from "@/components/insights/metric-target-summary";
 import { SubPageShell } from "@/components/insights/sub-page-shell";
 
 /**
@@ -88,6 +89,13 @@ export interface HealthKitMetricPageProps {
    * Resolves `insights.subPage.explainer.<explainerMetric>{Title,Body}`.
    */
   explainerMetric?: string;
+  /**
+   * v1.8.5 W5 — when set, renders `<MetricTargetSummary slug=…>` beneath
+   * the chart. Used by blood glucose, whose per-context ADA / DDG bands
+   * live on the targets wire but whose page rides this generic scaffold
+   * rather than a bespoke module. Omit it for metrics without a target.
+   */
+  targetSummarySlug?: string;
 }
 
 export function HealthKitMetricPage({
@@ -104,6 +112,7 @@ export function HealthKitMetricPage({
   coachPrefill,
   valueScale,
   explainerMetric,
+  targetSummarySlug,
 }: HealthKitMetricPageProps) {
   const { user, isAuthenticated } = useAuth();
   const { t } = useTranslations();
@@ -186,6 +195,9 @@ export function HealthKitMetricPage({
         userTimezone={user?.timezone}
         valueScale={valueScale}
       />
+      {targetSummarySlug ? (
+        <MetricTargetSummary slug={targetSummarySlug} />
+      ) : null}
       <CoachLaunchButton />
     </SubPageShell>
   );
diff --git a/src/components/insights/metric-target-summary.tsx b/src/components/insights/metric-target-summary.tsx
index 9844d67e9..9508ff34a 100644
--- a/src/components/insights/metric-target-summary.tsx
+++ b/src/components/insights/metric-target-summary.tsx
@@ -2,14 +2,19 @@
 
 import Link from "next/link";
 import { useQuery } from "@tanstack/react-query";
-import { Target } from "lucide-react";
+import { ExternalLink, Target } from "lucide-react";
 
 import { useAuth } from "@/hooks/use-auth";
 import { queryKeys } from "@/lib/query-keys";
 import { useTranslations } from "@/lib/i18n/context";
+import { convertGlucose, resolveGlucoseUnit } from "@/lib/glucose";
+import { RangeBar } from "@/components/targets/range-bar";
+import { ConsistencyStrip } from "@/components/targets/consistency-strip";
+import { TargetStatusPill } from "@/components/targets/target-status-pill";
+import { getTargetSourceLink } from "@/lib/targets/source-link";
 
 /**
- * v1.8.0 — surface the numeric target range + in-target share on each
+ * v1.8.0 → v1.8.5 — surface the per-metric target reference panel on each
  * insights category page, directly beneath the chart / assessment.
  *
  * The data is the same `/api/insights/targets` payload that powers the
@@ -19,22 +24,24 @@ import { useTranslations } from "@/lib/i18n/context";
  * cache the `/targets` page then reuses. We never recompute the ranges
  * here: the route is the single source of truth for the age-based ESH
  * blood-pressure band, the WHO weight / BMI band, the Karvonen pulse
- * band, the AASM sleep band, and the medication / mood / step targets.
+ * band, the AASM sleep band, the ADA / DDG glucose bands, and the
+ * medication / mood targets.
  *
- * Each insights slug maps to one target `type`. Blood pressure is the one
- * composite case: the route emits the systolic band on the
- * `BLOOD_PRESSURE` target and the diastolic band on the top-level
- * `bpDiastolic` slot, so we stitch them back into a `S/D` range string.
+ * v1.8.5 W5 — the panel grew from a one-line range card into a compact
+ * reference panel that ports the context the `/targets` card carries:
  *
- * The "in target" share reads `daysInRange30d / daysLogged30d` — the
- * fraction of logged days over the last 30 whose mean reading landed in
- * the green band. We hide the share alone when the route flags
- * `insufficientData`; the range stays visible so the band is always
- * legible. This matches the `/targets` consistency strip so the two
- * surfaces never disagree.
+ *   • Row 1: target range string + `<TargetStatusPill>` + source link
+ *            (the "what is the band / what is it based on" answer).
+ *   • Row 2: `<RangeBar>` — where today's value sits inside the band
+ *            (the spatial answer). BP renders the second diastolic bar.
+ *   • Row 3: in-target share % + the 30-day average.
+ *   • Row 4: `<ConsistencyStrip>` — the last seven days at a glance.
+ *   • Footer: the "Adjust target range" link to `/targets`.
  *
- * A discreet "Adjust target range" link routes to `/targets`, which
- * stays the canonical place to view / tune the bands.
+ * Each insights slug maps to one target `type`, except blood glucose
+ * which maps to up to four per-context cards (fasting / postprandial /
+ * random / bedtime) — those carry mg/dL canonical values that we convert
+ * to the user's display unit exactly like the `/targets` page does.
  */
 
 interface TargetRange {
@@ -42,22 +49,38 @@ interface TargetRange {
   max: number;
 }
 
+interface TargetClassification {
+  category: string;
+  color: string;
+}
+
 interface TargetItem {
   type: string;
+  label: string;
   current: number | null;
+  average30: number | null;
   unit: string;
   range: TargetRange | null;
+  classification: TargetClassification | null;
+  source: string;
+  daysInRange7d: number;
+  daysLogged7d: number;
   daysInRange30d: number;
   daysLogged30d: number;
   insufficientData: boolean;
+  consistency7d: ReadonlyArray<"in" | "near" | "out" | null>;
 }
 
 interface TargetsResponse {
   targets: TargetItem[];
   bpDiastolic: {
     current: number | null;
+    average30: number | null;
     range: TargetRange | null;
   };
+  profile?: {
+    glucoseUnit?: string | null;
+  };
 }
 
 /**
@@ -65,6 +88,10 @@ interface TargetsResponse {
  * Slugs without a numeric target (HRV, oxygen saturation, body
  * temperature, active energy, workouts, resting HR) are absent — the
  * component renders nothing for them, so the sub-page collapses cleanly.
+ *
+ * Blood glucose is the one slug that fans out to several target types:
+ * the route emits one card per logged context, so the summary renders a
+ * reference panel for each.
  */
 const SLUG_TO_TARGET_TYPE: Record<string, string> = {
   "blood-pressure": "BLOOD_PRESSURE",
@@ -76,6 +103,14 @@ const SLUG_TO_TARGET_TYPE: Record<string, string> = {
   medications: "MEDICATION_COMPLIANCE",
 };
 
+/** Glucose context target types, in the route's emission order. */
+const GLUCOSE_TARGET_TYPES = [
+  "BLOOD_GLUCOSE_FASTING",
+  "BLOOD_GLUCOSE_POSTPRANDIAL",
+  "BLOOD_GLUCOSE_RANDOM",
+  "BLOOD_GLUCOSE_BEDTIME",
+];
+
 interface MetricTargetSummaryProps {
   /** Insights category slug, e.g. `"blood-pressure"`. */
   slug: string;
@@ -90,6 +125,7 @@ export function MetricTargetSummary({ slug }: MetricTargetSummaryProps) {
   const { t } = useTranslations();
   const { isAuthenticated } = useAuth();
 
+  const isGlucose = slug === "blood-glucose";
   const targetType = SLUG_TO_TARGET_TYPE[slug];
 
   const { data } = useQuery({
@@ -100,23 +136,98 @@ export function MetricTargetSummary({ slug }: MetricTargetSummaryProps) {
       const json = await res.json();
       return json.data as TargetsResponse;
     },
-    enabled: isAuthenticated && targetType != null,
+    enabled: isAuthenticated && (targetType != null || isGlucose),
   });
 
   // No numeric target for this slug, or the payload hasn't resolved yet.
-  if (!targetType || !data) return null;
+  if ((!targetType && !isGlucose) || !data) return null;
+
+  // Glucose: one panel per logged context, converting the canonical
+  // mg/dL values to the user's display unit exactly like the /targets
+  // page. The route's per-context labels are i18n keys, so resolve them.
+  if (isGlucose) {
+    const displayUnit = resolveGlucoseUnit(data.profile?.glucoseUnit ?? null);
+    const convert = (v: number | null) =>
+      v == null ? null : convertGlucose(v, displayUnit);
+    const panels = GLUCOSE_TARGET_TYPES.map((type) =>
+      data.targets.find((entry) => entry.type === type),
+    )
+      .filter((entry): entry is TargetItem => entry != null && entry.range != null)
+      .map((entry) => ({
+        ...entry,
+        label: t(entry.label),
+        unit: displayUnit,
+        current: convert(entry.current),
+        average30: convert(entry.average30),
+        range: entry.range
+          ? {
+              min: convertGlucose(entry.range.min, displayUnit),
+              max: convertGlucose(entry.range.max, displayUnit),
+            }
+          : null,
+      }));
+
+    if (panels.length === 0) return null;
+
+    return (
+      <div className="space-y-2" data-slot="metric-target-summary-group">
+        {panels.map((panel) => (
+          <TargetReferencePanel
+            key={panel.type}
+            target={panel}
+            heading={panel.label}
+          />
+        ))}
+      </div>
+    );
+  }
 
   const target = data.targets.find((entry) => entry.type === targetType);
   if (!target || !target.range) return null;
 
+  return (
+    <TargetReferencePanel
+      target={target}
+      bpDiastolic={
+        targetType === "BLOOD_PRESSURE" ? data.bpDiastolic : undefined
+      }
+    />
+  );
+}
+
+interface TargetReferencePanelProps {
+  target: TargetItem;
+  bpDiastolic?: TargetsResponse["bpDiastolic"];
+  /** Optional sub-heading shown above the panel (used for glucose contexts). */
+  heading?: string;
+}
+
+/**
+ * One compact reference panel: range + status pill + source, a range
+ * bar (plus a diastolic bar for BP), the in-target share + 30-day
+ * average, the 7-day consistency strip, and the adjust-target link.
+ * All fields come from the `/api/insights/targets` payload — nothing is
+ * recomputed here.
+ */
+function TargetReferencePanel({
+  target,
+  bpDiastolic,
+  heading,
+}: TargetReferencePanelProps) {
+  const { t } = useTranslations();
+
   const { range, unit } = target;
+  if (!range) return null;
+
+  const isBp = target.type === "BLOOD_PRESSURE";
+  const isMedicationCompliance = target.type === "MEDICATION_COMPLIANCE";
 
   // Compose the range string. Blood pressure stitches the systolic band
   // (on this target) with the diastolic band (on `bpDiastolic`) so the
   // user reads the familiar `S/D` pair.
   let rangeLabel: string;
-  if (targetType === "BLOOD_PRESSURE" && data.bpDiastolic.range) {
-    const dia = data.bpDiastolic.range;
+  if (isBp && bpDiastolic?.range) {
+    const dia = bpDiastolic.range;
     rangeLabel = t("insights.subPage.target.bpRange", {
       sysMin: fmt(range.min),
       sysMax: fmt(range.max),
@@ -132,49 +243,138 @@ export function MetricTargetSummary({ slug }: MetricTargetSummaryProps) {
     });
   }
 
+  const sourceLink = getTargetSourceLink(target);
+
   // In-target share: fraction of logged days in the green band over the
   // last 30. Suppressed when the route flagged insufficient data so the
   // sub-page mirrors the `/targets` strip exactly.
-  const showShare =
-    !target.insufficientData && target.daysLogged30d > 0;
+  const showShare = !target.insufficientData && target.daysLogged30d > 0;
   const sharePct = showShare
     ? Math.round((target.daysInRange30d / target.daysLogged30d) * 100)
     : null;
 
+  // 30-day average. BP stitches the diastolic average into the familiar
+  // `S/D` pair; everything else rounds to one decimal.
+  let averageLabel: string | null = null;
+  if (target.average30 != null) {
+    const avgValue =
+      isBp && bpDiastolic?.average30 != null
+        ? `${Math.round(target.average30)}/${Math.round(bpDiastolic.average30)}`
+        : String(Math.round(target.average30 * 10) / 10);
+    averageLabel = `${t("targets.average30d")} ${avgValue} ${unit}`;
+  }
+
+  const showConsistency =
+    !target.insufficientData &&
+    target.consistency7d != null &&
+    target.consistency7d.length > 0;
+
   return (
-    // v1.8.5 W4a — demote the target summary from a full bordered `Card`
-    // (which carried the primitive's `py-4 md:py-6` shell padding around a
-    // `py-3` content block — far too much vertical reserve for one line of
-    // range text) to a compact inline band. The green target glyph, the
-    // range string, the in-target share, and the "adjust" link all stay;
-    // only the wrapper shell changes so the block reads as a strip, not a
-    // card, in the tightened sub-page rhythm.
     <div
       data-slot="metric-target-summary"
-      className="bg-muted/30 flex flex-wrap items-center justify-between gap-x-4 gap-y-1.5 rounded-lg px-3 py-2"
+      data-target-type={target.type}
+      className="bg-muted/30 space-y-3 rounded-lg px-3 py-2.5"
     >
-      <div className="flex items-center gap-2.5">
-        <Target
-          className="text-dracula-green size-4 shrink-0"
-          aria-hidden="true"
-        />
-        <div className="space-y-0.5">
-          <p className="text-sm font-medium">{rangeLabel}</p>
-          {sharePct != null ? (
-            <p className="text-muted-foreground text-xs">
-              {t("insights.subPage.target.inTargetShare", {
-                pct: sharePct,
-              })}
-            </p>
+      {/* Row 1: target range string + status pill + source link. */}
+      <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-1.5">
+        <div className="flex items-center gap-2.5">
+          <Target
+            className="text-dracula-green size-4 shrink-0"
+            aria-hidden="true"
+          />
+          <div className="space-y-0.5">
+            {heading ? (
+              <p className="text-muted-foreground text-[0.6875rem] font-medium tracking-[0.06em] uppercase">
+                {heading}
+              </p>
+            ) : null}
+            <p className="text-sm font-medium">{rangeLabel}</p>
+          </div>
+        </div>
+        <div className="flex items-center gap-2">
+          {target.classification ? (
+            <TargetStatusPill
+              classification={target.classification}
+              range={range}
+              unit={unit}
+              source={target.source}
+            />
           ) : null}
         </div>
       </div>
-      <Link
-        href="/targets"
-        className="text-muted-foreground hover:text-foreground focus-visible:ring-ring/50 inline-flex min-h-11 items-center rounded-sm px-1 text-xs font-medium underline-offset-4 transition-colors hover:underline focus-visible:ring-2 focus-visible:outline-none"
-      >
-        {t("insights.subPage.target.adjustLink")}
-      </Link>
+
+      {/* Row 2: range bar — where today's value sits inside the band. */}
+      {target.current != null ? (
+        <RangeBar
+          value={target.current}
+          min={range.min}
+          max={range.max}
+          unit={unit}
+          orangeMin={isMedicationCompliance ? 70 : undefined}
+          orangeMax={isMedicationCompliance ? 100 : undefined}
+        />
+      ) : null}
+
+      {/* Row 2b: diastolic range bar for blood pressure. */}
+      {isBp && bpDiastolic?.range && bpDiastolic.current != null ? (
+        <div className="space-y-1">
+          <p className="text-muted-foreground text-xs">
+            {t("targets.diastolic")}
+          </p>
+          <RangeBar
+            value={bpDiastolic.current}
+            min={bpDiastolic.range.min}
+            max={bpDiastolic.range.max}
+            unit="mmHg"
+          />
+        </div>
+      ) : null}
+
+      {/* Row 3: in-target share + 30-day average. */}
+      {sharePct != null || averageLabel ? (
+        <div className="text-muted-foreground flex flex-wrap items-center gap-x-3 gap-y-0.5 text-xs">
+          {sharePct != null ? (
+            <span>
+              {t("insights.subPage.target.inTargetShare", { pct: sharePct })}
+            </span>
+          ) : null}
+          {averageLabel ? <span>{averageLabel}</span> : null}
+        </div>
+      ) : null}
+
+      {/* Row 4: 7-day consistency strip. */}
+      {showConsistency && target.consistency7d ? (
+        <ConsistencyStrip
+          days={target.consistency7d}
+          daysInRange={target.daysInRange7d ?? 0}
+          daysLogged={target.daysLogged7d ?? 0}
+        />
+      ) : null}
+
+      {/* Footer: source link + adjust-target link. */}
+      <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-1.5 pt-0.5">
+        {sourceLink ? (
+          <a
+            href={sourceLink}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="text-muted-foreground hover:text-foreground inline-flex items-center gap-1 text-xs"
+          >
+            <span>{t("targets.sourceLabel", { source: target.source })}</span>
+            <ExternalLink className="size-3" aria-hidden="true" />
+          </a>
+        ) : (
+          <span className="text-muted-foreground text-xs">
+            {t("targets.sourceLabel", { source: target.source })}
+          </span>
+        )}
+        <Link
+          href="/targets"
+          className="text-muted-foreground hover:text-foreground focus-visible:ring-ring/50 inline-flex min-h-11 items-center rounded-sm px-1 text-xs font-medium underline-offset-4 transition-colors hover:underline focus-visible:ring-2 focus-visible:outline-none"
+        >
+          {t("insights.subPage.target.adjustLink")}
+        </Link>
+      </div>
     </div>
   );
 }
diff --git a/src/components/targets/__tests__/target-status-pill.test.tsx b/src/components/targets/__tests__/target-status-pill.test.tsx
new file mode 100644
index 000000000..f1ef31eb4
--- /dev/null
+++ b/src/components/targets/__tests__/target-status-pill.test.tsx
@@ -0,0 +1,72 @@
+import { describe, it, expect } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+
+import { I18nProvider } from "@/lib/i18n/context";
+import {
+  TargetStatusPill,
+  statusGroupForCategory,
+} from "../target-status-pill";
+
+/**
+ * v1.8.5 W5 — `<TargetStatusPill>` was extracted from `target-card.tsx`
+ * so the Targets card and the Insights reference panel render the
+ * identical pill from the same server-emitted classification category.
+ * These tests pin the category → semantic-group mapping (which drives
+ * the pill colour) and the rendered label + range/source tooltip.
+ */
+
+function render(props: Parameters<typeof TargetStatusPill>[0]) {
+  return renderToStaticMarkup(
+    <I18nProvider initialLocale="en">
+      <TargetStatusPill {...props} />
+    </I18nProvider>,
+  );
+}
+
+describe("statusGroupForCategory", () => {
+  it("paints in-band categories green", () => {
+    expect(statusGroupForCategory("Normal")).toBe("in");
+    expect(statusGroupForCategory("Optimal")).toBe("in");
+    expect(statusGroupForCategory("On target")).toBe("in");
+  });
+
+  it("paints far-out categories red", () => {
+    expect(statusGroupForCategory("Hypertension Grade 3")).toBe("out");
+    expect(statusGroupForCategory("Significantly elevated")).toBe("out");
+    expect(statusGroupForCategory("Tachycardia")).toBe("out");
+  });
+
+  it("falls back to amber for caution + unmapped categories", () => {
+    expect(statusGroupForCategory("Slightly elevated")).toBe("near");
+    expect(statusGroupForCategory("Overweight")).toBe("near");
+    expect(statusGroupForCategory("Totally Unknown Category")).toBe("near");
+  });
+});
+
+describe("<TargetStatusPill>", () => {
+  it("renders the translated label + the in/out status attribute", () => {
+    const html = render({
+      classification: { category: "Optimal", color: "#50fa7b" },
+      range: { min: 120, max: 129 },
+      unit: "mmHg",
+      source: "ESH 2023",
+    });
+    expect(html).toContain('data-slot="target-status-pill"');
+    expect(html).toContain('data-status="in"');
+    expect(html).toContain("Optimal");
+    // The tooltip trigger is the pill itself; the range/source content
+    // lives behind a closed Radix tooltip and is not in static markup.
+    expect(html).toContain('data-state="closed"');
+  });
+
+  it("renders the raw category when no translation key matches", () => {
+    const html = render({
+      classification: { category: "Totally Unknown Category", color: "#fff" },
+      range: null,
+      unit: "kg",
+      source: "Custom",
+    });
+    expect(html).toContain("Totally Unknown Category");
+    expect(html).toContain('data-status="near"');
+  });
+});
diff --git a/src/components/targets/target-card.tsx b/src/components/targets/target-card.tsx
index 64f3a4cc0..24c3192bd 100644
--- a/src/components/targets/target-card.tsx
+++ b/src/components/targets/target-card.tsx
@@ -32,6 +32,11 @@ import { useFeatureFlags } from "@/hooks/use-feature-flags";
 import { moodStabilityLabel } from "@/lib/targets/mood-stability-label";
 import { ConsistencyStrip } from "./consistency-strip";
 import { RangeBar } from "./range-bar";
+import {
+  TargetStatusPill,
+  statusGroupForCategory,
+  translateStatus,
+} from "./target-status-pill";
 import { TargetCoachButton } from "./target-coach-button";
 import { TargetEditSheet } from "./target-edit-sheet";
 import { buildTargetPrompt } from "@/lib/ai/coach/target-prompts";
@@ -96,128 +101,6 @@ const TYPE_COLORS: Record<string, string> = {
   BLOOD_GLUCOSE_BEDTIME: "text-dracula-red",
 };
 
-const STATUS_CATEGORY_KEY: Record<string, string> = {
-  Underweight: "underweight",
-  Normal: "normal",
-  Overweight: "overweight",
-  "Obesity Grade I": "obesityGrade1",
-  "Obesity Grade II": "obesityGrade2",
-  "Obesity Grade III": "obesityGrade3",
-  Optimal: "optimal",
-  "High-normal": "highNormal",
-  "Hypertension Grade 1": "hypertensionGrade1",
-  "Hypertension Grade 2": "hypertensionGrade2",
-  "Hypertension Grade 3": "hypertensionGrade3",
-  Bradycardia: "bradycardia",
-  Elevated: "elevated",
-  Tachycardia: "tachycardia",
-  "Significantly low": "significantlyLow",
-  "Slightly low": "slightlyLow",
-  "On target": "onTarget",
-  "Slightly elevated": "slightlyElevated",
-  "Significantly elevated": "significantlyElevated",
-  "Far too short": "farTooShort",
-  "Too short": "tooShort",
-  "Slightly long": "slightlyLong",
-  "Far too long": "farTooLong",
-  "Below essential": "belowEssential",
-  Essential: "essential",
-  Athletic: "athletic",
-  Fitness: "fitness",
-  Acceptable: "acceptable",
-  Obese: "obese",
-  "Very low": "veryLow",
-  "Low active": "lowActive",
-  "Moderately active": "moderatelyActive",
-  Active: "active",
-  "Very active": "veryActive",
-  Good: "good",
-  Moderate: "moderate",
-  Low: "low",
-  High: "high",
-  "Very good": "veryGood",
-  "Very stable": "veryStable",
-  Stable: "stable",
-  Fluctuating: "fluctuating",
-};
-
-/** Resolve a server-emitted classification.category to its translated label. */
-function translateStatus(
-  category: string,
-  t: (key: string, vars?: Record<string, string>) => string,
-): string {
-  const key = STATUS_CATEGORY_KEY[category];
-  if (!key) return category;
-  return t(`targets.status.${key}`);
-}
-
-/**
- * Map an in-band classification category to one of three semantic
- * groups. Used to drive the status-pill style without re-classifying
- * the value from scratch; the server's category is canonical.
- *
- * "in" = inside the green band ("On target", "Normal", "Optimal", …).
- * "near" = inside the orange band ("Slightly elevated", "Overweight",
- *   …) or a step inside an obesity / hypertension grade-1 band.
- * "out" = outside all bands ("Hypertension Grade 3", "Obesity Grade
- *   III", "Tachycardia" away from the target band, …).
- *
- * When the category is unmapped we fall back to "near" — the safe
- * middle, which paints the pill in the neutral amber tone rather than
- * lighting up a false-positive green/red.
- */
-function statusGroupForCategory(category: string): "in" | "near" | "out" {
-  const greenCategories = new Set([
-    "Normal",
-    "Optimal",
-    "On target",
-    "Good",
-    "Very good",
-    "Very stable",
-    "Stable",
-    "Athletic",
-    "Fitness",
-    "Acceptable",
-    "Active",
-    "Very active",
-    "Moderately active",
-    "Essential",
-  ]);
-  const redCategories = new Set([
-    "Obesity Grade III",
-    "Hypertension Grade 3",
-    "Significantly elevated",
-    "Significantly low",
-    "Far too short",
-    "Far too long",
-    "Tachycardia",
-    "Bradycardia",
-    "Low",
-    "High",
-    "Fluctuating",
-    "Below essential",
-    "Very low",
-  ]);
-  if (greenCategories.has(category)) return "in";
-  if (redCategories.has(category)) return "out";
-  return "near";
-}
-
-// Use the Tailwind v4 parenthesised CSS-variable shorthand
-// (bg-VAR-PAREN-FORM-/N) instead of the legacy bracketed VAR-form. The
-// bracketed form combined with an opacity modifier emits an escaped
-// class selector that Turbopack's CSS parser rejects with
-// "Unexpected token Delim('.')" because the scanner picks the literal
-// string out of source files (including this comment) and emits a CSS
-// rule for it. The parenthesised shorthand produces a clean selector
-// that parses cleanly. See the Tailwind v4 upgrade guide for the
-// migration from bracket-form to paren-form for CSS-variable values.
-const STATUS_PILL_STYLES: Record<"in" | "near" | "out", string> = {
-  in: "bg-(--dracula-green)/12 text-(--dracula-green) ring-(--dracula-green)/30",
-  near: "bg-(--dracula-orange)/14 text-(--dracula-orange) ring-(--dracula-orange)/30",
-  out: "bg-(--dracula-red)/12 text-(--dracula-red) ring-(--dracula-red)/30",
-};
-
 interface TargetClassification {
   category: string;
   color: string;
@@ -373,7 +256,6 @@ export function TargetCard({
   const statusGroup = target.classification
     ? statusGroupForCategory(target.classification.category)
     : "near";
-  const statusPillStyle = STATUS_PILL_STYLES[statusGroup];
   const statusLabel = target.classification
     ? translateStatus(target.classification.category, t)
     : null;
@@ -452,37 +334,13 @@ export function TargetCard({
             </h3>
           </div>
           <div className="flex items-center gap-2 self-end sm:self-auto">
-            {statusLabel ? (
-              <TooltipProvider>
-                <Tooltip>
-                  <TooltipTrigger asChild>
-                    <span
-                      data-slot="target-status-pill"
-                      data-status={statusGroup}
-                      className={cn(
-                        "inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium ring-1",
-                        statusPillStyle,
-                      )}
-                    >
-                      {statusLabel}
-                    </span>
-                  </TooltipTrigger>
-                  <TooltipContent>
-                    {target.range && (
-                      <p className="text-xs">
-                        {t("targets.targetRangeValue", {
-                          min: String(target.range.min),
-                          max: String(target.range.max),
-                          unit: target.unit,
-                        })}
-                      </p>
-                    )}
-                    <p className="text-xs">
-                      {t("targets.sourceLabel", { source: target.source })}
-                    </p>
-                  </TooltipContent>
-                </Tooltip>
-              </TooltipProvider>
+            {target.classification ? (
+              <TargetStatusPill
+                classification={target.classification}
+                range={target.range}
+                unit={target.unit}
+                source={target.source}
+              />
             ) : null}
             <Button
               type="button"
diff --git a/src/components/targets/target-status-pill.tsx b/src/components/targets/target-status-pill.tsx
new file mode 100644
index 000000000..1959e966a
--- /dev/null
+++ b/src/components/targets/target-status-pill.tsx
@@ -0,0 +1,220 @@
+"use client";
+
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { cn } from "@/lib/utils";
+import { useTranslations } from "@/lib/i18n/context";
+
+/**
+ * v1.8.5 W5 — `<TargetStatusPill>` extracted from `target-card.tsx`.
+ *
+ * The verbal status pill ("Optimal", "Slightly elevated", localized)
+ * is now a shared primitive so both the Targets card and the Insights
+ * per-category reference panel render the identical pill from the same
+ * server-emitted `classification.category`. Single-sourcing the
+ * category → label → colour mapping here means the two surfaces can
+ * never disagree on what a band reads or which tone it paints.
+ *
+ * Behaviour is byte-identical to the previous inline version in
+ * `target-card.tsx`: a coloured pill (green in-band / amber caution /
+ * red out) with a tooltip carrying the target range + guideline source.
+ */
+
+interface TargetClassification {
+  category: string;
+  color: string;
+}
+
+interface TargetRange {
+  min: number;
+  max: number;
+}
+
+/**
+ * Server classification category → i18n key under `targets.status.*`.
+ * The category is canonical (emitted by `/api/insights/targets`); this
+ * map only resolves it to the localized label.
+ */
+const STATUS_CATEGORY_KEY: Record<string, string> = {
+  Underweight: "underweight",
+  Normal: "normal",
+  Overweight: "overweight",
+  "Obesity Grade I": "obesityGrade1",
+  "Obesity Grade II": "obesityGrade2",
+  "Obesity Grade III": "obesityGrade3",
+  Optimal: "optimal",
+  "High-normal": "highNormal",
+  "Hypertension Grade 1": "hypertensionGrade1",
+  "Hypertension Grade 2": "hypertensionGrade2",
+  "Hypertension Grade 3": "hypertensionGrade3",
+  Bradycardia: "bradycardia",
+  Elevated: "elevated",
+  Tachycardia: "tachycardia",
+  "Significantly low": "significantlyLow",
+  "Slightly low": "slightlyLow",
+  "On target": "onTarget",
+  "Slightly elevated": "slightlyElevated",
+  "Significantly elevated": "significantlyElevated",
+  "Far too short": "farTooShort",
+  "Too short": "tooShort",
+  "Slightly long": "slightlyLong",
+  "Far too long": "farTooLong",
+  "Below essential": "belowEssential",
+  Essential: "essential",
+  Athletic: "athletic",
+  Fitness: "fitness",
+  Acceptable: "acceptable",
+  Obese: "obese",
+  "Very low": "veryLow",
+  "Low active": "lowActive",
+  "Moderately active": "moderatelyActive",
+  Active: "active",
+  "Very active": "veryActive",
+  Good: "good",
+  Moderate: "moderate",
+  Low: "low",
+  High: "high",
+  "Very good": "veryGood",
+  "Very stable": "veryStable",
+  Stable: "stable",
+  Fluctuating: "fluctuating",
+};
+
+/** Resolve a server-emitted classification.category to its translated label. */
+export function translateStatus(
+  category: string,
+  t: (key: string, vars?: Record<string, string>) => string,
+): string {
+  const key = STATUS_CATEGORY_KEY[category];
+  if (!key) return category;
+  return t(`targets.status.${key}`);
+}
+
+/**
+ * Map an in-band classification category to one of three semantic
+ * groups. Used to drive the status-pill style without re-classifying
+ * the value from scratch; the server's category is canonical.
+ *
+ * "in" = inside the green band ("On target", "Normal", "Optimal", …).
+ * "near" = inside the orange band ("Slightly elevated", "Overweight",
+ *   …) or a step inside an obesity / hypertension grade-1 band.
+ * "out" = outside all bands ("Hypertension Grade 3", "Obesity Grade
+ *   III", "Tachycardia" away from the target band, …).
+ *
+ * When the category is unmapped we fall back to "near" — the safe
+ * middle, which paints the pill in the neutral amber tone rather than
+ * lighting up a false-positive green/red.
+ */
+export function statusGroupForCategory(
+  category: string,
+): "in" | "near" | "out" {
+  const greenCategories = new Set([
+    "Normal",
+    "Optimal",
+    "On target",
+    "Good",
+    "Very good",
+    "Very stable",
+    "Stable",
+    "Athletic",
+    "Fitness",
+    "Acceptable",
+    "Active",
+    "Very active",
+    "Moderately active",
+    "Essential",
+  ]);
+  const redCategories = new Set([
+    "Obesity Grade III",
+    "Hypertension Grade 3",
+    "Significantly elevated",
+    "Significantly low",
+    "Far too short",
+    "Far too long",
+    "Tachycardia",
+    "Bradycardia",
+    "Low",
+    "High",
+    "Fluctuating",
+    "Below essential",
+    "Very low",
+  ]);
+  if (greenCategories.has(category)) return "in";
+  if (redCategories.has(category)) return "out";
+  return "near";
+}
+
+// Use the Tailwind v4 parenthesised CSS-variable shorthand
+// (bg-VAR-PAREN-FORM-/N) instead of the legacy bracketed VAR-form. The
+// bracketed form combined with an opacity modifier emits an escaped
+// class selector that Turbopack's CSS parser rejects with
+// "Unexpected token Delim('.')" because the scanner picks the literal
+// string out of source files (including this comment) and emits a CSS
+// rule for it. The parenthesised shorthand produces a clean selector
+// that parses cleanly. See the Tailwind v4 upgrade guide for the
+// migration from bracket-form to paren-form for CSS-variable values.
+export const STATUS_PILL_STYLES: Record<"in" | "near" | "out", string> = {
+  in: "bg-(--dracula-green)/12 text-(--dracula-green) ring-(--dracula-green)/30",
+  near: "bg-(--dracula-orange)/14 text-(--dracula-orange) ring-(--dracula-orange)/30",
+  out: "bg-(--dracula-red)/12 text-(--dracula-red) ring-(--dracula-red)/30",
+};
+
+export interface TargetStatusPillProps {
+  classification: TargetClassification;
+  range: TargetRange | null;
+  unit: string;
+  source: string;
+}
+
+/**
+ * Verbal status pill with a tooltip carrying the target range + the
+ * guideline source. The pill colour is derived from the classification
+ * category's semantic group; unmapped categories paint amber.
+ */
+export function TargetStatusPill({
+  classification,
+  range,
+  unit,
+  source,
+}: TargetStatusPillProps) {
+  const { t } = useTranslations();
+
+  const statusGroup = statusGroupForCategory(classification.category);
+  const statusPillStyle = STATUS_PILL_STYLES[statusGroup];
+  const statusLabel = translateStatus(classification.category, t);
+
+  return (
+    <TooltipProvider>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <span
+            data-slot="target-status-pill"
+            data-status={statusGroup}
+            className={cn(
+              "inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium ring-1",
+              statusPillStyle,
+            )}
+          >
+            {statusLabel}
+          </span>
+        </TooltipTrigger>
+        <TooltipContent>
+          {range && (
+            <p className="text-xs">
+              {t("targets.targetRangeValue", {
+                min: String(range.min),
+                max: String(range.max),
+                unit,
+              })}
+            </p>
+          )}
+          <p className="text-xs">{t("targets.sourceLabel", { source })}</p>
+        </TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  );
+}
diff --git a/src/lib/targets/__tests__/source-link.test.ts b/src/lib/targets/__tests__/source-link.test.ts
new file mode 100644
index 000000000..8f0571704
--- /dev/null
+++ b/src/lib/targets/__tests__/source-link.test.ts
@@ -0,0 +1,66 @@
+import { describe, it, expect } from "vitest";
+
+import { getTargetSourceLink } from "../source-link";
+
+/**
+ * v1.8.5 W5 — `getTargetSourceLink` was extracted from the Targets page
+ * so both the Targets card and the Insights reference panel resolve the
+ * identical guideline-citation URL. These tests pin the type → URL map
+ * and the pulse source-substring branching.
+ */
+describe("getTargetSourceLink", () => {
+  it("maps weight + BMI to the WHO obesity fact-sheet", () => {
+    const url =
+      "https://www.who.int/news-room/fact-sheets/detail/obesity-and-overweight";
+    expect(getTargetSourceLink({ type: "WEIGHT", source: "WHO BMI" })).toBe(url);
+    expect(getTargetSourceLink({ type: "BMI", source: "WHO BMI" })).toBe(url);
+  });
+
+  it("maps blood pressure (and the in-target derivative) to the ESH paper", () => {
+    const url =
+      "https://academic.oup.com/eurheartj/article/39/33/3021/5079119";
+    expect(
+      getTargetSourceLink({ type: "BLOOD_PRESSURE", source: "ESH 2023" }),
+    ).toBe(url);
+    expect(
+      getTargetSourceLink({
+        type: "BLOOD_PRESSURE_IN_TARGET",
+        source: "ESH 2023",
+      }),
+    ).toBe(url);
+  });
+
+  it("branches the pulse link on the source substring", () => {
+    expect(
+      getTargetSourceLink({ type: "PULSE", source: "CDC/NCHS 2011" }),
+    ).toBe("https://www.cdc.gov/nchs/data/nhsr/nhsr041.pdf");
+    expect(getTargetSourceLink({ type: "PULSE", source: "AHA" })).toBe(
+      "https://www.heart.org/en/health-topics/high-blood-pressure/the-facts-about-high-blood-pressure/all-about-heart-rate-pulse",
+    );
+    // An unrecognised pulse source resolves to no link rather than a wrong one.
+    expect(getTargetSourceLink({ type: "PULSE", source: "Karvonen" })).toBe(
+      null,
+    );
+  });
+
+  it("maps sleep, body fat, and steps to their respective guidelines", () => {
+    expect(
+      getTargetSourceLink({ type: "SLEEP_DURATION", source: "AASM" }),
+    ).toContain("aasm.org");
+    expect(getTargetSourceLink({ type: "BODY_FAT", source: "ACE" })).toContain(
+      "acefitness.org",
+    );
+    expect(
+      getTargetSourceLink({ type: "ACTIVITY_STEPS", source: "WHO" }),
+    ).toContain("who.int/publications");
+  });
+
+  it("returns null for a type without a guideline citation", () => {
+    expect(
+      getTargetSourceLink({ type: "MEDICATION_COMPLIANCE", source: "—" }),
+    ).toBe(null);
+    expect(
+      getTargetSourceLink({ type: "BLOOD_GLUCOSE_FASTING", source: "ADA" }),
+    ).toBe(null);
+  });
+});
diff --git a/src/lib/targets/source-link.ts b/src/lib/targets/source-link.ts
new file mode 100644
index 000000000..7e6bccc99
--- /dev/null
+++ b/src/lib/targets/source-link.ts
@@ -0,0 +1,44 @@
+/**
+ * v1.8.5 W5 — `getTargetSourceLink` extracted from
+ * `src/app/targets/page.tsx`.
+ *
+ * Resolves the guideline-source citation URL for a target, keyed off
+ * the target `type` and (for pulse) substrings of the `source` label.
+ * Pure function with no React / page coupling so both the Targets page
+ * and the Insights per-category reference panel resolve the identical
+ * URL — the citation link can never drift between the two surfaces.
+ */
+export interface TargetSourceLinkInput {
+  type: string;
+  source: string;
+}
+
+export function getTargetSourceLink(target: TargetSourceLinkInput): string | null {
+  if (target.type === "WEIGHT" || target.type === "BMI") {
+    return "https://www.who.int/news-room/fact-sheets/detail/obesity-and-overweight";
+  }
+  if (
+    target.type === "BLOOD_PRESSURE" ||
+    target.type === "BLOOD_PRESSURE_IN_TARGET"
+  ) {
+    return "https://academic.oup.com/eurheartj/article/39/33/3021/5079119";
+  }
+  if (target.type === "PULSE") {
+    if (target.source.includes("CDC/NCHS")) {
+      return "https://www.cdc.gov/nchs/data/nhsr/nhsr041.pdf";
+    }
+    if (target.source.includes("AHA")) {
+      return "https://www.heart.org/en/health-topics/high-blood-pressure/the-facts-about-high-blood-pressure/all-about-heart-rate-pulse";
+    }
+  }
+  if (target.type === "SLEEP_DURATION") {
+    return "https://aasm.org/seven-or-more-hours-of-sleep-per-night-a-health-necessity-for-adults/";
+  }
+  if (target.type === "BODY_FAT") {
+    return "https://www.acefitness.org/resources/everyone/blog/6596/what-are-the-guidelines-for-percentage-of-body-fat-loss/";
+  }
+  if (target.type === "ACTIVITY_STEPS") {
+    return "https://www.who.int/publications/i/item/9789240015128";
+  }
+  return null;
+}

From b5e98533b82eff55a86be709ba31d23f14389b21 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 20:46:49 +0200
Subject: [PATCH 13/30] fix(export): move HealthKit placeholder codes off the
 LOINC namespace

Six HealthKit metrics without a published LOINC term were coded under
http://loinc.org, which fails FHIR R4 conformance (a non-LOINC code must
not sit in the LOINC namespace). Route any HKQuantityTypeIdentifier code
onto a shared custom CodeSystem (https://healthlog.dev/fhir/CodeSystem/healthkit),
keeping the raw HealthKit identifier as the code so the export stays
byte-aligned with the native client's exporter.
---
 src/lib/fhir/__tests__/build-bundle.test.ts | 38 +++++++++++++++++++++
 src/lib/fhir/build-bundle.ts                | 10 +++++-
 src/lib/fhir/loinc-map.ts                   | 19 ++++++++---
 3 files changed, 62 insertions(+), 5 deletions(-)

diff --git a/src/lib/fhir/__tests__/build-bundle.test.ts b/src/lib/fhir/__tests__/build-bundle.test.ts
index 98378b987..985b7a263 100644
--- a/src/lib/fhir/__tests__/build-bundle.test.ts
+++ b/src/lib/fhir/__tests__/build-bundle.test.ts
@@ -398,6 +398,44 @@ describe("buildFhirDocumentBundle", () => {
     expect(flights?.valueQuantity?.code).toBe("{flights}");
   });
 
+  it("routes HealthKit placeholder codes onto the custom CodeSystem, never LOINC", () => {
+    const bundle = buildFhirDocumentBundle(
+      makeData({
+        measurements: {
+          WEIGHT: [{ value: 80, measuredAt: "2026-04-30T08:00:00.000Z" }],
+          FLIGHTS_CLIMBED: [
+            { value: 12, measuredAt: "2026-04-30T08:00:00.000Z" },
+          ],
+        },
+      }),
+      { insuranceNumber: null },
+      FIXED_NOW,
+    );
+    const codings = observationsOf(bundle).flatMap((o) => o.code.coding ?? []);
+
+    // A real LOINC metric keeps the LOINC namespace.
+    const weight = codings.find((c) => c.code === "29463-7");
+    expect(weight?.system).toBe("http://loinc.org");
+
+    // The HealthKit placeholder moves to the shared custom CodeSystem with the
+    // raw HK identifier as the code (byte-aligned with the iOS exporter).
+    const flightsCoding = codings.find(
+      (c) => c.code === "HKQuantityTypeIdentifierFlightsClimbed",
+    );
+    expect(flightsCoding?.system).toBe(
+      "https://healthlog.dev/fhir/CodeSystem/healthkit",
+    );
+
+    // Conformance invariant: no HealthKit identifier is ever emitted under the
+    // LOINC namespace anywhere in the bundle.
+    const hkUnderLoinc = codings.filter(
+      (c) =>
+        c.system === "http://loinc.org" &&
+        c.code?.startsWith("HKQuantityTypeIdentifier"),
+    );
+    expect(hkUnderLoinc).toHaveLength(0);
+  });
+
   it("discriminates glucose LOINC by context (random/fasting/afterMeal)", () => {
     const bundle = buildFhirDocumentBundle(
       makeData({
diff --git a/src/lib/fhir/build-bundle.ts b/src/lib/fhir/build-bundle.ts
index 229e5d827..f816843de 100644
--- a/src/lib/fhir/build-bundle.ts
+++ b/src/lib/fhir/build-bundle.ts
@@ -21,6 +21,7 @@ import type { DoctorReportData } from "@/lib/doctor-report-data";
 import { resolveGlucoseUnit, convertGlucose } from "@/lib/glucose";
 import {
   LOINC_SYSTEM,
+  HEALTHKIT_CODESYSTEM,
   UCUM_SYSTEM,
   MEASUREMENT_LOINC,
   BP_PANEL_LOINC,
@@ -66,8 +67,15 @@ function escapeXml(value: string): string {
 
 function codeableFromMapping(m: LoincMapping): FhirCodeableConcept {
   if (m.loinc) {
+    // HealthKit placeholder codes have no published LOINC term; they must not
+    // sit under the LOINC namespace (a non-LOINC code there is a conformance
+    // violation). Route them onto the shared custom CodeSystem instead —
+    // byte-aligned with the iOS exporter.
+    const system = m.loinc.startsWith("HKQuantityTypeIdentifier")
+      ? HEALTHKIT_CODESYSTEM
+      : LOINC_SYSTEM;
     return {
-      coding: [{ system: LOINC_SYSTEM, code: m.loinc, display: m.display }],
+      coding: [{ system, code: m.loinc, display: m.display }],
       text: m.display,
     };
   }
diff --git a/src/lib/fhir/loinc-map.ts b/src/lib/fhir/loinc-map.ts
index 2cbae62df..5e662a244 100644
--- a/src/lib/fhir/loinc-map.ts
+++ b/src/lib/fhir/loinc-map.ts
@@ -12,6 +12,15 @@
 
 export const LOINC_SYSTEM = "http://loinc.org";
 export const UCUM_SYSTEM = "http://unitsofmeasure.org";
+/**
+ * Shared custom CodeSystem for HealthKit placeholder metrics that have no
+ * published LOINC term. A non-LOINC code under `http://loinc.org` is a FHIR
+ * conformance violation, so these route here instead. Byte-aligned with the
+ * iOS exporter (confirmed 2026-06-01) — both clients emit the identical
+ * `system` + raw `HKQuantityTypeIdentifier…` `code`.
+ */
+export const HEALTHKIT_CODESYSTEM =
+  "https://healthlog.dev/fhir/CodeSystem/healthkit";
 
 export type FhirObservationCategory =
   | "vital-signs"
@@ -145,10 +154,12 @@ export const MEASUREMENT_LOINC: Record<string, LoincMapping> = {
     unit: "kg",
     category: "vital-signs",
   },
-  // HK-placeholder codes — no published LOINC term. iOS emits the HealthKit
-  // identifier STRING as the `code` (in the LOINC system slot); the server
-  // must emit the identical placeholder, not invent a LOINC. The `loinc`
-  // field below carries that placeholder string verbatim.
+  // HK-placeholder codes — no published LOINC term. Both iOS and the server
+  // emit the HealthKit identifier STRING as the `code` under the shared
+  // `HEALTHKIT_CODESYSTEM` (NOT the LOINC namespace — a non-LOINC code under
+  // http://loinc.org fails FHIR conformance). The `loinc` field below carries
+  // the placeholder string verbatim; the builder routes any
+  // `HKQuantityTypeIdentifier…` code onto the custom system.
   WALKING_DOUBLE_SUPPORT: {
     loinc: "HKQuantityTypeIdentifierWalkingDoubleSupportPercentage",
     display: "Walking double support percentage",

From fef88787e9569c47919cd9c08c6947505235e630 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 20:59:35 +0200
Subject: [PATCH 14/30] fix(medications): surface a multi-day-overdue first
 rolling dose
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A rolling cadence with no intake logged anchors its first dose at
startsOn ?? createdAt. When that anchor falls on a prior calendar day
the dose is overdue by a day or more, but nextOccurrenceAfter floored
the search window to the start of the user's current day and dropped it
— so the dashboard showed no next-due and the reminder worker, which
shares this engine, emitted nothing. Clamp the floor to the first-dose
day in the no-intake branch so a multi-day-overdue start dose surfaces
as overdue. The post-intake re-anchor (lastIntakeAt + N) is unaffected.
---
 .../scheduling/__tests__/recurrence.test.ts   | 32 +++++++++++++++++++
 src/lib/medications/scheduling/recurrence.ts  | 29 +++++++++++++++--
 2 files changed, 59 insertions(+), 2 deletions(-)

diff --git a/src/lib/medications/scheduling/__tests__/recurrence.test.ts b/src/lib/medications/scheduling/__tests__/recurrence.test.ts
index daaa9fa2b..f81918b27 100644
--- a/src/lib/medications/scheduling/__tests__/recurrence.test.ts
+++ b/src/lib/medications/scheduling/__tests__/recurrence.test.ts
@@ -392,6 +392,38 @@ describe("occurrencesBetween — rolling", () => {
     ).toBe("2026-06-10");
   });
 
+  it("nextOccurrenceAfter surfaces a multi-day-overdue first dose (startsOn days ago, no intake)", () => {
+    // v1.8.5 — a rolling course whose startsOn is several calendar days in
+    // the past with no intake logged must still surface the start dose as
+    // OVERDUE ("take now"). Flooring the search window only to the start of
+    // the user's current day dropped the dose out of existence, returning
+    // null — no next-due AND no reminder. The floor must reach back to the
+    // first-dose instant in the no-intake case.
+    const startsOn = d("2026-06-07T06:00:00Z"); // 3 days before NOW
+    const NOW = d("2026-06-10T12:00:00Z");
+    const schedule = makeSchedule({
+      rollingIntervalDays: 7,
+      timesOfDay: ["08:00"],
+    });
+    const ctx = makeCtx({
+      lastIntakeAt: null,
+      medication: { startsOn },
+    });
+    const next = nextOccurrenceAfter(schedule, NOW, ctx);
+    expect(next).not.toBeNull();
+    // The surfaced slot is the start dose (08:00 Berlin on the startsOn day),
+    // overdue by ~3 days relative to NOW.
+    expect(next!.at.getTime()).toBeLessThan(NOW.getTime());
+    expect(
+      new Intl.DateTimeFormat("en-CA", {
+        timeZone: "Europe/Berlin",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+      }).format(next!.at),
+    ).toBe("2026-06-07");
+  });
+
   it("nextOccurrenceAfter returns the future first dose AT startsOn (no intake) without adding N", () => {
     const NOW = d("2026-06-10T12:00:00Z");
     const startsOn = d("2026-06-12T00:00:00Z"); // 2 days out
diff --git a/src/lib/medications/scheduling/recurrence.ts b/src/lib/medications/scheduling/recurrence.ts
index 8b59e1bd5..c0db43330 100644
--- a/src/lib/medications/scheduling/recurrence.ts
+++ b/src/lib/medications/scheduling/recurrence.ts
@@ -259,9 +259,21 @@ export function nextOccurrenceAfter(
   // of its due day instead of silently rolling it forward by N.
   if (schedule.rollingIntervalDays !== null) {
     const dayFloor = startOfDayInTz(after, ctx.timeZone);
-    const slots = expandRolling(schedule, ctx, dayFloor, limit);
+    // With no intake logged the first dose anchors at `startsOn ?? createdAt`.
+    // When that anchor is on a PRIOR calendar day the dose is overdue by ≥1
+    // day and must still surface ("take now"); flooring only to the start of
+    // the user's current day dropped it out of existence (null next-due AND
+    // no reminder). Reach the floor back to the first-dose instant in that
+    // case so a multi-day-overdue start dose is returned. After an intake the
+    // re-anchor (`lastIntakeAt + N`) is always in the future, so the dayFloor
+    // is the correct, tighter bound there.
+    const floor =
+      ctx.lastIntakeAt === null
+        ? new Date(Math.min(dayFloor.getTime(), firstRollingDoseDayFloor(ctx)))
+        : dayFloor;
+    const slots = expandRolling(schedule, ctx, floor, limit);
     for (const s of slots) {
-      if (s.at.getTime() < dayFloor.getTime()) continue;
+      if (s.at.getTime() < floor.getTime()) continue;
       if (cyclic && !isInCyclicOnWeek(s.at, schedule, ctx)) continue;
       return s;
     }
@@ -367,6 +379,19 @@ function expandOneShot(
  * historical intake events, not "expected slots" the schedule
  * predicts forward.
  */
+/**
+ * Start-of-day (in the user's timezone) of the no-intake first rolling dose
+ * anchor — `startsOn ?? createdAt`. Used by `nextOccurrenceAfter` to clamp the
+ * search floor so a multi-day-overdue first dose still surfaces. Mirrors the
+ * anchor `expandRolling` emits in the `lastIntakeAt === null` branch; flooring
+ * to the anchor's start-of-day keeps the time-of-day slot (e.g. 08:00) within
+ * the window rather than ahead of a raw-instant floor.
+ */
+function firstRollingDoseDayFloor(ctx: RecurrenceContext): number {
+  const anchor = ctx.medication.startsOn ?? ctx.medication.createdAt;
+  return startOfDayInTz(anchor, ctx.timeZone).getTime();
+}
+
 function expandRolling(
   schedule: CanonicalSchedule,
   ctx: RecurrenceContext,

From 7e7702d6c943819d175186f189194d59e1c89e26 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 20:59:59 +0200
Subject: [PATCH 15/30] refactor(medications): single-source the injection-site
 allow check

resolveInjectionSiteForWrite reimplemented the effectiveAllowedSites(...)
.includes(...) membership test inline, duplicating the isSiteAllowed
helper that already wraps it. Call isSiteAllowed so the write-path guard
and the helper share one definition.
---
 src/lib/medications/injection-site-write.ts | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/src/lib/medications/injection-site-write.ts b/src/lib/medications/injection-site-write.ts
index b68362b36..d8116cc4d 100644
--- a/src/lib/medications/injection-site-write.ts
+++ b/src/lib/medications/injection-site-write.ts
@@ -20,7 +20,7 @@
  * request that does is either stale UI or a hand-rolled call.
  */
 import {
-  effectiveAllowedSites,
+  isSiteAllowed,
   type InjectionSiteKey,
 } from "@/lib/medications/injection-sites";
 
@@ -68,11 +68,13 @@ export function resolveInjectionSiteForWrite(
     return { kind: "ok", site: null };
   }
 
-  const allowed = effectiveAllowedSites(
-    input.allowedInjectionSites,
-    input.globalExcludedInjectionSites,
-  );
-  if (!allowed.includes(submitted)) {
+  if (
+    !isSiteAllowed(
+      submitted,
+      input.allowedInjectionSites,
+      input.globalExcludedInjectionSites,
+    )
+  ) {
     return { kind: "disallowed", site: submitted };
   }
   return { kind: "ok", site: submitted };

From ad693cd862f341adced2f95f0e3177a22413d066 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 21:01:30 +0200
Subject: [PATCH 16/30] refactor(medications): extract the compliance
 slot-context builders

expectedSlotCountForDay and expectedSlotsBetween each rebuilt the same
canonical-schedule and recurrence-context literals inline, differing only
by id prefix and count-vs-collect. Extract toRecurrenceCtx and
toCanonicalSchedule so both share one adapter; behaviour identical.
---
 src/lib/analytics/compliance.ts | 112 +++++++++++++++++---------------
 1 file changed, 60 insertions(+), 52 deletions(-)

diff --git a/src/lib/analytics/compliance.ts b/src/lib/analytics/compliance.ts
index 072089900..8bcc7a20c 100644
--- a/src/lib/analytics/compliance.ts
+++ b/src/lib/analytics/compliance.ts
@@ -28,7 +28,9 @@ import {
 } from "@/lib/medications/scheduling/cadence";
 import {
   occurrencesBetween,
+  type CanonicalSchedule,
   type Occurrence,
+  type RecurrenceContext,
   type ScheduleType,
 } from "@/lib/medications/scheduling/recurrence";
 import type { InjectionSiteKey } from "@/lib/medications/injection-sites";
@@ -252,6 +254,53 @@ export function lastNonSkippedTakenAt(
   }, null);
 }
 
+/**
+ * v1.8.5 — adapt a compliance medication context to the canonical engine's
+ * {@link RecurrenceContext}. The synthetic medication `id` only labels the
+ * row for the engine's internal logging; the `idTag` keeps the two callers'
+ * historical prefixes (`compliance-daily` vs `compliance-slots`) distinct.
+ */
+function toRecurrenceCtx(
+  ctx: ComplianceMedicationContext,
+  idTag: string,
+): RecurrenceContext {
+  return {
+    medication: {
+      id: idTag,
+      startsOn: ctx.startsOn,
+      endsOn: ctx.endsOn,
+      oneShot: ctx.oneShot,
+      createdAt: ctx.createdAt,
+    },
+    timeZone: ctx.timeZone,
+    lastIntakeAt: ctx.lastIntakeAt,
+  };
+}
+
+/**
+ * v1.8.5 — adapt a {@link ComplianceSchedule} to the canonical engine's
+ * {@link CanonicalSchedule}, defaulting the optional fields the compliance
+ * payload may omit. `id` is engine-internal labelling only.
+ */
+function toCanonicalSchedule(
+  s: ComplianceSchedule,
+  id: string,
+): CanonicalSchedule {
+  return {
+    id,
+    rrule: s.rrule ?? null,
+    rollingIntervalDays: s.rollingIntervalDays ?? null,
+    timesOfDay: s.timesOfDay ?? [],
+    daysOfWeek: s.daysOfWeek ?? null,
+    windowStart: s.windowStart,
+    windowEnd: s.windowEnd,
+    reminderGraceMinutes: s.reminderGraceMinutes ?? null,
+    scheduleType: s.scheduleType ?? "SCHEDULED",
+    cyclicOnWeeks: s.cyclicOnWeeks ?? null,
+    cyclicOffWeeks: s.cyclicOffWeeks ?? null,
+  };
+}
+
 /**
  * v1.7.0 item 5 — count the expected dose slots a medication's schedules
  * emit inside `[dayStart, dayEnd)`, routed through the canonical engine.
@@ -267,34 +316,10 @@ export function expectedSlotCountForDay(
   ctx: ComplianceMedicationContext,
 ): number {
   let count = 0;
-  const recurrenceCtx = {
-    medication: {
-      id: "compliance-daily",
-      startsOn: ctx.startsOn,
-      endsOn: ctx.endsOn,
-      oneShot: ctx.oneShot,
-      createdAt: ctx.createdAt,
-    },
-    timeZone: ctx.timeZone,
-    lastIntakeAt: ctx.lastIntakeAt,
-  };
+  const recurrenceCtx = toRecurrenceCtx(ctx, "compliance-daily");
   for (let i = 0; i < schedules.length; i++) {
-    const s = schedules[i];
-    const canonical = {
-      id: `compliance-daily-${i}`,
-      rrule: s.rrule ?? null,
-      rollingIntervalDays: s.rollingIntervalDays ?? null,
-      timesOfDay: s.timesOfDay ?? [],
-      daysOfWeek: s.daysOfWeek ?? null,
-      windowStart: s.windowStart,
-      windowEnd: s.windowEnd,
-      reminderGraceMinutes: s.reminderGraceMinutes ?? null,
-      scheduleType: s.scheduleType ?? ("SCHEDULED" as const),
-      cyclicOnWeeks: s.cyclicOnWeeks ?? null,
-      cyclicOffWeeks: s.cyclicOffWeeks ?? null,
-    };
     count += occurrencesBetween(
-      canonical,
+      toCanonicalSchedule(schedules[i], `compliance-daily-${i}`),
       dayStart,
       // occurrencesBetween is inclusive of both ends; subtract 1 ms so a
       // slot exactly at the next day's midnight doesn't double-count.
@@ -324,34 +349,17 @@ export function expectedSlotsBetween(
   to: Date,
   ctx: ComplianceMedicationContext,
 ): Occurrence[] {
-  const recurrenceCtx = {
-    medication: {
-      id: "compliance-slots",
-      startsOn: ctx.startsOn,
-      endsOn: ctx.endsOn,
-      oneShot: ctx.oneShot,
-      createdAt: ctx.createdAt,
-    },
-    timeZone: ctx.timeZone,
-    lastIntakeAt: ctx.lastIntakeAt,
-  };
+  const recurrenceCtx = toRecurrenceCtx(ctx, "compliance-slots");
   const all: Occurrence[] = [];
   for (let i = 0; i < schedules.length; i++) {
-    const s = schedules[i];
-    const canonical = {
-      id: `compliance-slots-${i}`,
-      rrule: s.rrule ?? null,
-      rollingIntervalDays: s.rollingIntervalDays ?? null,
-      timesOfDay: s.timesOfDay ?? [],
-      daysOfWeek: s.daysOfWeek ?? null,
-      windowStart: s.windowStart,
-      windowEnd: s.windowEnd,
-      reminderGraceMinutes: s.reminderGraceMinutes ?? null,
-      scheduleType: s.scheduleType ?? ("SCHEDULED" as const),
-      cyclicOnWeeks: s.cyclicOnWeeks ?? null,
-      cyclicOffWeeks: s.cyclicOffWeeks ?? null,
-    };
-    all.push(...occurrencesBetween(canonical, from, to, recurrenceCtx));
+    all.push(
+      ...occurrencesBetween(
+        toCanonicalSchedule(schedules[i], `compliance-slots-${i}`),
+        from,
+        to,
+        recurrenceCtx,
+      ),
+    );
   }
   return all.sort((a, b) => a.at.getTime() - b.at.getTime());
 }

From f29ac6d96e85b24be510b28a3b398e3ff68bdcc9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 21:04:45 +0200
Subject: [PATCH 17/30] fix(a11y): give the injection-site picker a visible
 focus state and accessible names
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The SVG site picker painted its focus ring as the stroke of a transparent
hit-target circle — effectively invisible on the muted body map, a WCAG
2.4.7 risk — and conveyed the recommended next site only through the
dashed ring (no screen-reader cue). Track keyboard focus and paint a
contrasting halo on the filled dot, and fold the recommendation into the
recommended site's aria-label so the rotation guidance reaches assistive
tech. Adds injectionSiteRecommendedAriaLabel across all six locales.
---
 messages/de.json                              |  1 +
 messages/en.json                              |  1 +
 messages/es.json                              |  1 +
 messages/fr.json                              |  1 +
 messages/it.json                              |  1 +
 messages/pl.json                              |  1 +
 .../__tests__/injection-site-picker.test.tsx  | 31 +++++++++++--
 .../medications/injection-site-picker.tsx     | 44 ++++++++++++++++++-
 8 files changed, 76 insertions(+), 5 deletions(-)

diff --git a/messages/de.json b/messages/de.json
index 427e7d436..d571f4242 100644
--- a/messages/de.json
+++ b/messages/de.json
@@ -994,6 +994,7 @@
     },
     "injectionSiteBodyOutlineAriaLabel": "Körperumriss",
     "injectionSitePickerAriaLabel": "Injektionsstelle auswählen",
+    "injectionSiteRecommendedAriaLabel": "{site} – empfohlene nächste Stelle",
     "siteAbdomenLeft": "Bauch, unten links",
     "siteAbdomenRight": "Bauch, unten rechts",
     "siteAbdomenUpperLeft": "Bauch, oben links",
diff --git a/messages/en.json b/messages/en.json
index f89b859b5..3552e65e5 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -994,6 +994,7 @@
     },
     "injectionSiteBodyOutlineAriaLabel": "Body outline",
     "injectionSitePickerAriaLabel": "Injection site picker",
+    "injectionSiteRecommendedAriaLabel": "{site} — recommended next site",
     "siteAbdomenLeft": "Abdomen, lower left",
     "siteAbdomenRight": "Abdomen, lower right",
     "siteAbdomenUpperLeft": "Abdomen, upper left",
diff --git a/messages/es.json b/messages/es.json
index 4e03cd711..2e5d8d824 100644
--- a/messages/es.json
+++ b/messages/es.json
@@ -994,6 +994,7 @@
     },
     "injectionSiteBodyOutlineAriaLabel": "Silueta del cuerpo",
     "injectionSitePickerAriaLabel": "Selector de sitio de inyección",
+    "injectionSiteRecommendedAriaLabel": "{site}: sitio siguiente recomendado",
     "siteAbdomenLeft": "Abdomen, inferior izquierdo",
     "siteAbdomenRight": "Abdomen, inferior derecho",
     "siteAbdomenUpperLeft": "Abdomen, superior izquierdo",
diff --git a/messages/fr.json b/messages/fr.json
index 798d3d114..23e0a8dd8 100644
--- a/messages/fr.json
+++ b/messages/fr.json
@@ -994,6 +994,7 @@
     },
     "injectionSiteBodyOutlineAriaLabel": "Silhouette du corps",
     "injectionSitePickerAriaLabel": "Sélecteur de site d'injection",
+    "injectionSiteRecommendedAriaLabel": "{site} — prochain site recommandé",
     "siteAbdomenLeft": "Abdomen, en bas à gauche",
     "siteAbdomenRight": "Abdomen, en bas à droite",
     "siteAbdomenUpperLeft": "Abdomen, en haut à gauche",
diff --git a/messages/it.json b/messages/it.json
index 28e18988d..e15b10574 100644
--- a/messages/it.json
+++ b/messages/it.json
@@ -994,6 +994,7 @@
     },
     "injectionSiteBodyOutlineAriaLabel": "Sagoma del corpo",
     "injectionSitePickerAriaLabel": "Selettore del sito di iniezione",
+    "injectionSiteRecommendedAriaLabel": "{site} — prossimo sito consigliato",
     "siteAbdomenLeft": "Addome, basso a sinistra",
     "siteAbdomenRight": "Addome, basso a destra",
     "siteAbdomenUpperLeft": "Addome, alto a sinistra",
diff --git a/messages/pl.json b/messages/pl.json
index 3b1764904..cb5d3660a 100644
--- a/messages/pl.json
+++ b/messages/pl.json
@@ -994,6 +994,7 @@
     },
     "injectionSiteBodyOutlineAriaLabel": "Sylwetka ciała",
     "injectionSitePickerAriaLabel": "Wybór miejsca iniekcji",
+    "injectionSiteRecommendedAriaLabel": "{site} — zalecane następne miejsce",
     "siteAbdomenLeft": "Brzuch, dolny lewy",
     "siteAbdomenRight": "Brzuch, dolny prawy",
     "siteAbdomenUpperLeft": "Brzuch, górny lewy",
diff --git a/src/components/medications/__tests__/injection-site-picker.test.tsx b/src/components/medications/__tests__/injection-site-picker.test.tsx
index 20976ff33..edc2ee342 100644
--- a/src/components/medications/__tests__/injection-site-picker.test.tsx
+++ b/src/components/medications/__tests__/injection-site-picker.test.tsx
@@ -90,6 +90,25 @@ describe("<InjectionSitePicker>", () => {
     expect(html).toContain("Recommended next:");
   });
 
+  it("folds the recommendation into the recommended site's aria-label (SR parity)", () => {
+    // The "recommended next site" cue must not be purely visual (the
+    // dashed ring). The recommended site's interactive circle carries an
+    // aria-label that includes the recommendation, while every other
+    // site keeps its plain site name.
+    const html = render(
+      <InjectionSitePicker
+        value={null}
+        history={["ABDOMEN_LEFT", "ABDOMEN_UPPER_LEFT"]}
+        onChange={() => {}}
+      />,
+    );
+
+    // Exactly one site is recommended → exactly one composed label.
+    const composed =
+      html.match(/aria-label="[^"]*— recommended next site"/g) ?? [];
+    expect(composed.length).toBe(1);
+  });
+
   it("fires onChange(site) when the click handler is invoked", () => {
     // SSR can't dispatch DOM events; smoke-check the contract by
     // invoking the supplied handler with each enum value. The picker
@@ -130,8 +149,12 @@ describe("<InjectionSitePicker>", () => {
     );
 
     // The full set of EN labels must appear in the SSR string —
-    // verifies the t() lookup matches each enum value's i18n key.
-    expect(html).toContain('aria-label="Abdomen, lower left"');
+    // verifies the t() lookup matches each enum value's i18n key. With
+    // empty history the recommender lands on ABDOMEN_LEFT, so its label
+    // folds in the "recommended next site" cue.
+    expect(html).toContain(
+      'aria-label="Abdomen, lower left — recommended next site"',
+    );
     expect(html).toContain('aria-label="Abdomen, lower right"');
     expect(html).toContain('aria-label="Abdomen, upper left"');
     expect(html).toContain('aria-label="Abdomen, upper right"');
@@ -149,7 +172,9 @@ describe("<InjectionSitePicker>", () => {
       "de",
     );
 
-    expect(html).toContain('aria-label="Bauch, unten links"');
+    expect(html).toContain(
+      'aria-label="Bauch, unten links – empfohlene nächste Stelle"',
+    );
     expect(html).toContain('aria-label="Bauch, unten rechts"');
     expect(html).toContain('aria-label="Bauch, oben links"');
     expect(html).toContain('aria-label="Bauch, oben rechts"');
diff --git a/src/components/medications/injection-site-picker.tsx b/src/components/medications/injection-site-picker.tsx
index 7d166184f..ad1210511 100644
--- a/src/components/medications/injection-site-picker.tsx
+++ b/src/components/medications/injection-site-picker.tsx
@@ -1,5 +1,7 @@
 "use client";
 
+import { useState } from "react";
+
 import { useTranslations } from "@/lib/i18n/context";
 import {
   INJECTION_SITE_KEYS,
@@ -59,6 +61,21 @@ export function InjectionSitePicker({
   const allowedSet = allowed ? new Set(allowed) : null;
   const isAllowed = (site: InjectionSiteKey) =>
     allowedSet === null || allowedSet.has(site);
+  // Track which site currently holds keyboard focus so we can paint a
+  // high-contrast focus halo on the filled dot itself — a transparent
+  // hit-target stroke alone is effectively invisible on the muted body
+  // map (WCAG 2.4.7).
+  const [focusedSite, setFocusedSite] = useState<InjectionSiteKey | null>(null);
+
+  // Accessible name: fold the rotation recommendation into the label so a
+  // screen-reader user gets the "recommended next site" cue that is
+  // otherwise conveyed only by the dashed ring.
+  const siteLabel = (site: InjectionSiteKey): string => {
+    const name = t(describeInjectionSite(site));
+    return site === recommended
+      ? t("medications.injectionSiteRecommendedAriaLabel", { site: name })
+      : name;
+  };
 
   return (
     <div
@@ -155,8 +172,22 @@ export function InjectionSitePicker({
           // disabled (dimmed, non-interactive) so the user cannot pick a
           // site the server would reject.
           const disabled = !isAllowed(site);
+          const isFocused = site === focusedSite;
           return (
             <g key={site}>
+              {/* Keyboard focus halo — a contrasting ring on the filled dot
+                  that only shows while this site holds focus. Painted under
+                  the recommendation ring and the dot so both stay legible. */}
+              {isFocused && !disabled && (
+                <circle
+                  cx={coord.x}
+                  cy={coord.y}
+                  r="10.5"
+                  fill="none"
+                  className="stroke-ring"
+                  strokeWidth="2.5"
+                />
+              )}
               {isRecommended && !isActive && !disabled && (
                 <circle
                   cx={coord.x}
@@ -197,8 +228,17 @@ export function InjectionSitePicker({
                 tabIndex={disabled ? -1 : 0}
                 aria-pressed={isActive}
                 aria-disabled={disabled}
-                aria-label={t(describeInjectionSite(site))}
+                aria-label={siteLabel(site)}
                 onClick={disabled ? undefined : () => onChange(site)}
+                onFocus={disabled ? undefined : () => setFocusedSite(site)}
+                onBlur={
+                  disabled
+                    ? undefined
+                    : () =>
+                        setFocusedSite((current) =>
+                          current === site ? null : current,
+                        )
+                }
                 onKeyDown={
                   disabled
                     ? undefined
@@ -212,7 +252,7 @@ export function InjectionSitePicker({
                 className={
                   disabled
                     ? "cursor-not-allowed focus:outline-none"
-                    : "cursor-pointer focus:outline-none focus-visible:stroke-current focus-visible:stroke-2"
+                    : "cursor-pointer focus:outline-none"
                 }
               />
             </g>

From 6bc51249bae25ffaa496a20f558573b848e8ed23 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 21:06:03 +0200
Subject: [PATCH 18/30] chore(i18n): drop two orphaned injection-rotation keys
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

medications.injectionRotationOverviewTitle and
medications.injectionRotationNextSuggested have no t() reference anywhere
in the tree — leftovers from an injection-rotation overview that did not
land. Remove them so the bundle carries only live keys.
---
 messages/de.json | 4 +---
 messages/en.json | 4 +---
 2 files changed, 2 insertions(+), 6 deletions(-)

diff --git a/messages/de.json b/messages/de.json
index d571f4242..e880d7d36 100644
--- a/messages/de.json
+++ b/messages/de.json
@@ -1323,9 +1323,7 @@
     "trackInjectionSitesToggle": "Injektionsstellen erfassen",
     "trackInjectionSitesHint": "Nach einer eingenommenen Dosis nach der verwendeten Stelle fragen und die nächste Rotation vorschlagen.",
     "allowedSitesLabel": "Erlaubte Stellen",
-    "allowedSitesHint": "Alle ausgewählt lassen für keine Einschränkung. Global ausgeschlossene Stellen werden nie angeboten.",
-    "injectionRotationOverviewTitle": "Stellen-Rotation",
-    "injectionRotationNextSuggested": "Vorschlag als Nächstes: {site}"
+    "allowedSitesHint": "Alle ausgewählt lassen für keine Einschränkung. Global ausgeschlossene Stellen werden nie angeboten."
   },
   "charts": {
     "loadingLabel": "Diagramm wird geladen…",
diff --git a/messages/en.json b/messages/en.json
index 3552e65e5..b72e5de89 100644
--- a/messages/en.json
+++ b/messages/en.json
@@ -1323,9 +1323,7 @@
     "trackInjectionSitesToggle": "Track injection sites",
     "trackInjectionSitesHint": "After a dose is taken, ask which site was used and suggest the next rotation.",
     "allowedSitesLabel": "Allowed sites",
-    "allowedSitesHint": "Leave all selected for no restriction. Sites you excluded globally are never offered.",
-    "injectionRotationOverviewTitle": "Site rotation",
-    "injectionRotationNextSuggested": "Suggested next: {site}"
+    "allowedSitesHint": "Leave all selected for no restriction. Sites you excluded globally are never offered."
   },
   "charts": {
     "loadingLabel": "Loading chart…",

From a5c894b58eb300257a84ee54e4c182d0763fcfce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 21:06:08 +0200
Subject: [PATCH 19/30] i18n(medications): translate the injection-site strings
 for es/fr/it/pl

The injection-site / log-dialog / settings cluster shipped translated in
de and en but verbatim English in es, fr, it and pl, so those users saw
English copy in the medication wizard, the log-injection-site dialog and
the settings injection card. Localise the eleven keys and drop the two
orphaned injection-rotation keys in the same bundles.
---
 messages/es.json | 24 +++++++++++-------------
 messages/fr.json | 24 +++++++++++-------------
 messages/it.json | 24 +++++++++++-------------
 messages/pl.json | 24 +++++++++++-------------
 4 files changed, 44 insertions(+), 52 deletions(-)

diff --git a/messages/es.json b/messages/es.json
index 2e5d8d824..4a09a62ae 100644
--- a/messages/es.json
+++ b/messages/es.json
@@ -1315,17 +1315,15 @@
         "drugLevelDisclosure": "Mostrar curva estimada del principio activo"
       }
     },
-    "logInjectionSiteTitle": "Log injection site",
-    "logInjectionSiteDescription": "Where did you inject {name}? Optional — you can skip this.",
-    "logInjectionSiteSkip": "Skip",
-    "logInjectionSiteConfirm": "Save site",
-    "logInjectionSiteNoneAvailable": "No injection site is available — every site is excluded in your settings.",
-    "trackInjectionSitesToggle": "Track injection sites",
-    "trackInjectionSitesHint": "After a dose is taken, ask which site was used and suggest the next rotation.",
-    "allowedSitesLabel": "Allowed sites",
-    "allowedSitesHint": "Leave all selected for no restriction. Sites you excluded globally are never offered.",
-    "injectionRotationOverviewTitle": "Site rotation",
-    "injectionRotationNextSuggested": "Suggested next: {site}"
+    "logInjectionSiteTitle": "Registrar sitio de inyección",
+    "logInjectionSiteDescription": "¿Dónde te inyectaste {name}? Opcional: puedes omitirlo.",
+    "logInjectionSiteSkip": "Omitir",
+    "logInjectionSiteConfirm": "Guardar sitio",
+    "logInjectionSiteNoneAvailable": "No hay ningún sitio de inyección disponible: todos los sitios están excluidos en tu configuración.",
+    "trackInjectionSitesToggle": "Registrar sitios de inyección",
+    "trackInjectionSitesHint": "Tras administrar una dosis, pregunta qué sitio se usó y sugiere la siguiente rotación.",
+    "allowedSitesLabel": "Sitios permitidos",
+    "allowedSitesHint": "Deja todos seleccionados para no aplicar restricciones. Los sitios que excluiste globalmente nunca se ofrecen."
   },
   "charts": {
     "loadingLabel": "Cargando la gráfica…",
@@ -3154,8 +3152,8 @@
       "generate": "Generar",
       "error": "Error en la exportación ({code})."
     },
-    "globalExcludedInjectionSitesLabel": "Globally excluded injection sites",
-    "globalExcludedInjectionSitesHint": "Sites listed here are never offered for any medication and rejected when logging a dose, even if a medication prefers them."
+    "globalExcludedInjectionSitesLabel": "Sitios de inyección excluidos globalmente",
+    "globalExcludedInjectionSitesHint": "Los sitios listados aquí no se ofrecen para ningún medicamento y se rechazan al registrar una dosis, aunque un medicamento los prefiera."
   },
   "admin": {
     "title": "Administration",
diff --git a/messages/fr.json b/messages/fr.json
index 23e0a8dd8..b0536ba98 100644
--- a/messages/fr.json
+++ b/messages/fr.json
@@ -1315,17 +1315,15 @@
         "drugLevelDisclosure": "Afficher la courbe estimée du principe actif"
       }
     },
-    "logInjectionSiteTitle": "Log injection site",
-    "logInjectionSiteDescription": "Where did you inject {name}? Optional — you can skip this.",
-    "logInjectionSiteSkip": "Skip",
-    "logInjectionSiteConfirm": "Save site",
-    "logInjectionSiteNoneAvailable": "No injection site is available — every site is excluded in your settings.",
-    "trackInjectionSitesToggle": "Track injection sites",
-    "trackInjectionSitesHint": "After a dose is taken, ask which site was used and suggest the next rotation.",
-    "allowedSitesLabel": "Allowed sites",
-    "allowedSitesHint": "Leave all selected for no restriction. Sites you excluded globally are never offered.",
-    "injectionRotationOverviewTitle": "Site rotation",
-    "injectionRotationNextSuggested": "Suggested next: {site}"
+    "logInjectionSiteTitle": "Enregistrer le site d'injection",
+    "logInjectionSiteDescription": "Où avez-vous injecté {name} ? Facultatif — vous pouvez l'ignorer.",
+    "logInjectionSiteSkip": "Ignorer",
+    "logInjectionSiteConfirm": "Enregistrer le site",
+    "logInjectionSiteNoneAvailable": "Aucun site d'injection disponible — tous les sites sont exclus dans vos réglages.",
+    "trackInjectionSitesToggle": "Suivre les sites d'injection",
+    "trackInjectionSitesHint": "Après la prise d'une dose, demander quel site a été utilisé et suggérer la prochaine rotation.",
+    "allowedSitesLabel": "Sites autorisés",
+    "allowedSitesHint": "Laissez tout sélectionné pour aucune restriction. Les sites exclus globalement ne sont jamais proposés."
   },
   "charts": {
     "loadingLabel": "Chargement du graphique…",
@@ -3154,8 +3152,8 @@
       "generate": "Générer",
       "error": "Échec de l’export ({code})."
     },
-    "globalExcludedInjectionSitesLabel": "Globally excluded injection sites",
-    "globalExcludedInjectionSitesHint": "Sites listed here are never offered for any medication and rejected when logging a dose, even if a medication prefers them."
+    "globalExcludedInjectionSitesLabel": "Sites d'injection exclus globalement",
+    "globalExcludedInjectionSitesHint": "Les sites listés ici ne sont proposés pour aucun médicament et sont refusés lors de l'enregistrement d'une dose, même si un médicament les privilégie."
   },
   "admin": {
     "title": "Administration",
diff --git a/messages/it.json b/messages/it.json
index e15b10574..73de3baa4 100644
--- a/messages/it.json
+++ b/messages/it.json
@@ -1315,17 +1315,15 @@
         "drugLevelDisclosure": "Mostra la curva stimata del principio attivo"
       }
     },
-    "logInjectionSiteTitle": "Log injection site",
-    "logInjectionSiteDescription": "Where did you inject {name}? Optional — you can skip this.",
-    "logInjectionSiteSkip": "Skip",
-    "logInjectionSiteConfirm": "Save site",
-    "logInjectionSiteNoneAvailable": "No injection site is available — every site is excluded in your settings.",
-    "trackInjectionSitesToggle": "Track injection sites",
-    "trackInjectionSitesHint": "After a dose is taken, ask which site was used and suggest the next rotation.",
-    "allowedSitesLabel": "Allowed sites",
-    "allowedSitesHint": "Leave all selected for no restriction. Sites you excluded globally are never offered.",
-    "injectionRotationOverviewTitle": "Site rotation",
-    "injectionRotationNextSuggested": "Suggested next: {site}"
+    "logInjectionSiteTitle": "Registra il sito di iniezione",
+    "logInjectionSiteDescription": "Dove hai iniettato {name}? Facoltativo — puoi saltarlo.",
+    "logInjectionSiteSkip": "Salta",
+    "logInjectionSiteConfirm": "Salva il sito",
+    "logInjectionSiteNoneAvailable": "Nessun sito di iniezione disponibile: tutti i siti sono esclusi nelle tue impostazioni.",
+    "trackInjectionSitesToggle": "Registra i siti di iniezione",
+    "trackInjectionSitesHint": "Dopo l'assunzione di una dose, chiedi quale sito è stato usato e suggerisci la rotazione successiva.",
+    "allowedSitesLabel": "Siti consentiti",
+    "allowedSitesHint": "Lascia tutti selezionati per nessuna restrizione. I siti esclusi globalmente non vengono mai proposti."
   },
   "charts": {
     "loadingLabel": "Caricamento del grafico…",
@@ -3154,8 +3152,8 @@
       "generate": "Genera",
       "error": "Esportazione non riuscita ({code})."
     },
-    "globalExcludedInjectionSitesLabel": "Globally excluded injection sites",
-    "globalExcludedInjectionSitesHint": "Sites listed here are never offered for any medication and rejected when logging a dose, even if a medication prefers them."
+    "globalExcludedInjectionSitesLabel": "Siti di iniezione esclusi globalmente",
+    "globalExcludedInjectionSitesHint": "I siti elencati qui non vengono proposti per alcun farmaco e vengono rifiutati al momento della registrazione di una dose, anche se un farmaco li preferisce."
   },
   "admin": {
     "title": "Administration",
diff --git a/messages/pl.json b/messages/pl.json
index cb5d3660a..d781ee6f1 100644
--- a/messages/pl.json
+++ b/messages/pl.json
@@ -1315,17 +1315,15 @@
         "drugLevelDisclosure": "Pokaż szacowaną krzywą stężenia leku"
       }
     },
-    "logInjectionSiteTitle": "Log injection site",
-    "logInjectionSiteDescription": "Where did you inject {name}? Optional — you can skip this.",
-    "logInjectionSiteSkip": "Skip",
-    "logInjectionSiteConfirm": "Save site",
-    "logInjectionSiteNoneAvailable": "No injection site is available — every site is excluded in your settings.",
-    "trackInjectionSitesToggle": "Track injection sites",
-    "trackInjectionSitesHint": "After a dose is taken, ask which site was used and suggest the next rotation.",
-    "allowedSitesLabel": "Allowed sites",
-    "allowedSitesHint": "Leave all selected for no restriction. Sites you excluded globally are never offered.",
-    "injectionRotationOverviewTitle": "Site rotation",
-    "injectionRotationNextSuggested": "Suggested next: {site}"
+    "logInjectionSiteTitle": "Zarejestruj miejsce iniekcji",
+    "logInjectionSiteDescription": "Gdzie wstrzyknięto {name}? Opcjonalnie — możesz to pominąć.",
+    "logInjectionSiteSkip": "Pomiń",
+    "logInjectionSiteConfirm": "Zapisz miejsce",
+    "logInjectionSiteNoneAvailable": "Brak dostępnego miejsca iniekcji — wszystkie miejsca są wykluczone w Twoich ustawieniach.",
+    "trackInjectionSitesToggle": "Rejestruj miejsca iniekcji",
+    "trackInjectionSitesHint": "Po przyjęciu dawki zapytaj, którego miejsca użyto, i zaproponuj kolejną rotację.",
+    "allowedSitesLabel": "Dozwolone miejsca",
+    "allowedSitesHint": "Pozostaw wszystkie zaznaczone, aby nie stosować ograniczeń. Miejsca wykluczone globalnie nigdy nie są proponowane."
   },
   "charts": {
     "loadingLabel": "Ładowanie wykresu…",
@@ -3154,8 +3152,8 @@
       "generate": "Generuj",
       "error": "Eksport nie powiódł się ({code})."
     },
-    "globalExcludedInjectionSitesLabel": "Globally excluded injection sites",
-    "globalExcludedInjectionSitesHint": "Sites listed here are never offered for any medication and rejected when logging a dose, even if a medication prefers them."
+    "globalExcludedInjectionSitesLabel": "Globalnie wykluczone miejsca iniekcji",
+    "globalExcludedInjectionSitesHint": "Miejsca wymienione tutaj nie są proponowane dla żadnego leku i są odrzucane przy rejestrowaniu dawki, nawet jeśli lek je preferuje."
   },
   "admin": {
     "title": "Administration",

From fcf5114620ad603bfdffdc86d51360159c02a8e9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 21:09:21 +0200
Subject: [PATCH 20/30] chore(mood): drop the superseded tag-taxonomy seeder

The structured tag catalog is seeded directly by migration
0101_v185_mood_tag_taxonomy and served from Postgres via the
/api/mood/tags route, so the parallel TypeScript copy had no
importer and tripped the knip gate.
---
 src/lib/mood/tag-taxonomy.ts | 113 -----------------------------------
 1 file changed, 113 deletions(-)
 delete mode 100644 src/lib/mood/tag-taxonomy.ts

diff --git a/src/lib/mood/tag-taxonomy.ts b/src/lib/mood/tag-taxonomy.ts
deleted file mode 100644
index 15c1fc0dc..000000000
--- a/src/lib/mood/tag-taxonomy.ts
+++ /dev/null
@@ -1,113 +0,0 @@
-/**
- * v1.8.5 — default mood-tag taxonomy.
- *
- * The canonical Category → Tag catalog seeded into `mood_tag_categories`
- * + `mood_tags` by migration `0101_v185_mood_tag_taxonomy`. Modelled on
- * the standalone mood diary's structured taxonomy but keyed on i18n
- * message keys (resolved against all six locales) rather than hard-coded
- * labels, so the catalog renders localised everywhere.
- *
- * The ids are deterministic string literals so the migration seed is
- * idempotent (re-running upserts by `key`) and so the catalog rows are
- * stable across deployments. Keys are stable machine identifiers; the
- * `labelKey` is the i18n key the capture UI + breakdown resolve.
- *
- * This is purely additive next to the legacy flat `MoodEntry.tags` JSON
- * column — the structured taxonomy is a second capture surface, not a
- * replacement.
- */
-
-export interface MoodTagSeed {
-  /** Stable machine key, unique across the catalog. */
-  key: string;
-  /** i18n message key `mood.tag.<key>`. */
-  labelKey: string;
-  /** Lucide icon name. */
-  icon: string;
-}
-
-export interface MoodTagCategorySeed {
-  key: string;
-  /** i18n message key `mood.tagCategory.<key>`. */
-  labelKey: string;
-  /** Lucide icon name for the category header. */
-  icon: string;
-  tags: MoodTagSeed[];
-}
-
-/**
- * The seeded taxonomy. Order within the arrays is the `sortOrder` used
- * for the catalog rows (category index, tag index within its category).
- */
-export const MOOD_TAG_TAXONOMY: MoodTagCategorySeed[] = [
-  {
-    key: "feelings",
-    labelKey: "mood.tagCategory.feelings",
-    icon: "Heart",
-    tags: [
-      { key: "happy", labelKey: "mood.tag.happy", icon: "Smile" },
-      { key: "excited", labelKey: "mood.tag.excited", icon: "Zap" },
-      { key: "grateful", labelKey: "mood.tag.grateful", icon: "HandHeart" },
-      { key: "relaxed", labelKey: "mood.tag.relaxed", icon: "CloudSun" },
-      { key: "content", labelKey: "mood.tag.content", icon: "ThumbsUp" },
-      { key: "tired", labelKey: "mood.tag.tired", icon: "Moon" },
-      { key: "unsure", labelKey: "mood.tag.unsure", icon: "HelpCircle" },
-      { key: "bored", labelKey: "mood.tag.bored", icon: "Meh" },
-      { key: "tense", labelKey: "mood.tag.tense", icon: "AlertTriangle" },
-      { key: "angry", labelKey: "mood.tag.angry", icon: "Flame" },
-      { key: "stressed", labelKey: "mood.tag.stressed", icon: "Brain" },
-      { key: "sad", labelKey: "mood.tag.sad", icon: "Frown" },
-    ],
-  },
-  {
-    key: "sleep",
-    labelKey: "mood.tagCategory.sleep",
-    icon: "BedDouble",
-    tags: [
-      { key: "slept_well", labelKey: "mood.tag.sleptWell", icon: "Moon" },
-      { key: "slept_ok", labelKey: "mood.tag.sleptOk", icon: "CloudMoon" },
-      { key: "slept_poorly", labelKey: "mood.tag.sleptPoorly", icon: "MoonStar" },
-      { key: "early_night", labelKey: "mood.tag.earlyNight", icon: "Clock" },
-    ],
-  },
-  {
-    key: "health",
-    labelKey: "mood.tagCategory.health",
-    icon: "HeartPulse",
-    tags: [
-      { key: "worked_out", labelKey: "mood.tag.workedOut", icon: "Dumbbell" },
-      { key: "ate_well", labelKey: "mood.tag.ateWell", icon: "Apple" },
-      { key: "hydrated", labelKey: "mood.tag.hydrated", icon: "GlassWater" },
-      { key: "walked", labelKey: "mood.tag.walked", icon: "Footprints" },
-      { key: "alcohol", labelKey: "mood.tag.alcohol", icon: "Wine" },
-    ],
-  },
-  {
-    key: "social",
-    labelKey: "mood.tagCategory.social",
-    icon: "Users",
-    tags: [
-      { key: "family", labelKey: "mood.tag.family", icon: "Home" },
-      { key: "friends", labelKey: "mood.tag.friends", icon: "Users" },
-      { key: "party", labelKey: "mood.tag.party", icon: "PartyPopper" },
-      { key: "alone", labelKey: "mood.tag.alone", icon: "User" },
-    ],
-  },
-  {
-    key: "work",
-    labelKey: "mood.tagCategory.work",
-    icon: "Briefcase",
-    tags: [
-      { key: "productive", labelKey: "mood.tag.productive", icon: "CheckCircle" },
-      { key: "overtime", labelKey: "mood.tag.overtime", icon: "Clock" },
-      { key: "day_off", labelKey: "mood.tag.dayOff", icon: "LogOut" },
-      { key: "travel", labelKey: "mood.tag.travel", icon: "Plane" },
-      { key: "sick_day", labelKey: "mood.tag.sickDay", icon: "Thermometer" },
-    ],
-  },
-];
-
-/** Flat list of every seeded tag key (for validation / lookups). */
-export const MOOD_TAG_KEYS: string[] = MOOD_TAG_TAXONOMY.flatMap((c) =>
-  c.tags.map((tagSeed) => tagSeed.key),
-);

From d5580917cc0b5a7d3f9a3f0ed7b6eeb2e8c14aa3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 21:10:55 +0200
Subject: [PATCH 21/30] fix(mood): write tag links inside the entry transaction

The mood entry was committed before createTagLinks/replaceTagLinks ran,
so a tag-link failure 5xx'd after the entry already existed and a client
retry minted a duplicate entry. Wrap the entry write and the tag-link
write in one $transaction and thread the tx client through both helpers
so they commit or roll back together.
---
 src/app/api/mood-entries/[id]/route.ts        | 29 ++++--
 .../api/mood-entries/__tests__/route.test.ts  | 95 +++++++++++++++++++
 src/app/api/mood-entries/route.ts             | 47 +++++----
 src/lib/mood/tag-links.ts                     | 32 +++++--
 4 files changed, 165 insertions(+), 38 deletions(-)

diff --git a/src/app/api/mood-entries/[id]/route.ts b/src/app/api/mood-entries/[id]/route.ts
index fd2849322..aff2f1548 100644
--- a/src/app/api/mood-entries/[id]/route.ts
+++ b/src/app/api/mood-entries/[id]/route.ts
@@ -134,17 +134,26 @@ export const PUT = apiHandler(
     // monotonic value and paired clients reconcile higher-wins.
     updateData.syncVersion = { increment: 1 };
 
-    const entry = await prisma.moodEntry.update({
-      where: { id },
-      data: updateData,
-    });
+    // v1.8.5 — update the entry and replace its structured-tag links in
+    // one transaction. A tag-link failure must roll the entry update back
+    // too — otherwise a client retry on the 5xx double-applies the edit
+    // (and the `syncVersion` increment). The tx client is threaded through
+    // the helper so both writes commit (or abort) together.
+    const entry = await prisma.$transaction(async (tx) => {
+      const updated = await tx.moodEntry.update({
+        where: { id },
+        data: updateData,
+      });
 
-    // v1.8.5 — full replacement of the structured-tag link set when
-    // `tagKeys` is present in the body. `null` clears every link; an
-    // omitted field leaves the links untouched.
-    if (data.tagKeys !== undefined) {
-      await replaceTagLinks(id, data.tagKeys ?? []);
-    }
+      // Full replacement of the structured-tag link set when `tagKeys`
+      // is present in the body. `null` clears every link; an omitted
+      // field leaves the links untouched.
+      if (data.tagKeys !== undefined) {
+        await replaceTagLinks(id, data.tagKeys ?? [], tx);
+      }
+
+      return updated;
+    });
 
     await auditLog("moodEntry.update", {
       userId: user.id,
diff --git a/src/app/api/mood-entries/__tests__/route.test.ts b/src/app/api/mood-entries/__tests__/route.test.ts
index 34cf8ee17..a6f45e5dd 100644
--- a/src/app/api/mood-entries/__tests__/route.test.ts
+++ b/src/app/api/mood-entries/__tests__/route.test.ts
@@ -4,6 +4,19 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { NextRequest } from "next/server";
 
+// v1.8.5 — the POST happy path writes the entry + its structured-tag
+// links inside one `$transaction`. The mock hands the same client object
+// to the interactive-transaction callback so the route's tx-scoped writes
+// (entry create + tag-link read-back) resolve against the same fakes.
+const txClient = {
+  moodEntry: {
+    create: vi.fn(),
+  },
+  moodEntryTagLink: {
+    findMany: vi.fn().mockResolvedValue([]),
+  },
+};
+
 vi.mock("@/lib/db", () => ({
   prisma: {
     moodEntry: {
@@ -11,10 +24,20 @@ vi.mock("@/lib/db", () => ({
       count: vi.fn().mockResolvedValue(0),
       create: vi.fn(),
     },
+    moodEntryTagLink: {
+      findMany: vi.fn().mockResolvedValue([]),
+    },
     auditLog: { create: vi.fn() },
+    $transaction: vi.fn(
+      async (fn: (tx: typeof txClient) => unknown) => fn(txClient),
+    ),
   },
 }));
 
+vi.mock("@/lib/mood/tag-links", () => ({
+  createTagLinks: vi.fn().mockResolvedValue(undefined),
+}));
+
 vi.mock("@/lib/auth/session", () => ({ getSession: vi.fn() }));
 vi.mock("@/lib/auth/audit", () => ({
   auditLog: vi.fn().mockResolvedValue(undefined),
@@ -31,6 +54,9 @@ vi.mock("@/lib/cache/invalidate", () => ({
 vi.mock("@/lib/rollups/mood-rollups", () => ({
   recomputeMoodBucketsForEntry: vi.fn().mockResolvedValue(undefined),
 }));
+vi.mock("@/lib/moodlog/push", () => ({
+  pushMoodEntriesToMoodLog: vi.fn().mockResolvedValue(undefined),
+}));
 vi.mock("@/lib/logging/transports", () => ({ emitIfSampled: vi.fn() }));
 vi.mock("@/lib/db-compat", () => ({
   ensureDbCompatibility: vi.fn().mockResolvedValue(undefined),
@@ -47,6 +73,9 @@ vi.mock("next/headers", () => ({
 import { GET, POST } from "../route";
 import { prisma } from "@/lib/db";
 import { getSession } from "@/lib/auth/session";
+import { createTagLinks } from "@/lib/mood/tag-links";
+import { recomputeMoodBucketsForEntry } from "@/lib/rollups/mood-rollups";
+import { pushMoodEntriesToMoodLog } from "@/lib/moodlog/push";
 
 const SESSION_OK = {
   session: { id: "sess-1", expiresAt: new Date(Date.now() + 3_600_000) },
@@ -69,6 +98,20 @@ beforeEach(() => {
   vi.resetAllMocks();
   vi.mocked(getSession).mockResolvedValue(SESSION_OK as never);
   vi.mocked(prisma.auditLog.create).mockResolvedValue({} as never);
+  // Re-establish the interactive-transaction passthrough after the reset.
+  vi.mocked(prisma.$transaction).mockImplementation(
+    async (fn: unknown) => (fn as (tx: typeof txClient) => unknown)(txClient),
+  );
+  txClient.moodEntryTagLink.findMany.mockResolvedValue([]);
+  vi.mocked(createTagLinks).mockResolvedValue(undefined);
+  // `reset` blanks the post-commit best-effort mocks; restore the promise
+  // returns so `recompute(...)` awaits and `push(...).catch()` is callable.
+  vi.mocked(recomputeMoodBucketsForEntry).mockResolvedValue(undefined);
+  vi.mocked(pushMoodEntriesToMoodLog).mockResolvedValue({
+    pushed: 0,
+    skipped: 0,
+    status: "ok",
+  });
 });
 
 describe("GET /api/mood-entries — 422 multi-issue (v1.4.43 W6)", () => {
@@ -174,3 +217,55 @@ describe("POST /api/mood-entries — 422 multi-issue (v1.4.43 W6)", () => {
     expect(res.status).toBe(422);
   });
 });
+
+describe("POST /api/mood-entries — entry + tag-links transaction (v1.8.5)", () => {
+  const VALID_BODY = {
+    mood: "GUT",
+    moodLoggedAt: "2026-06-01T08:00:00.000Z",
+    tagKeys: ["happy"],
+  };
+
+  it("writes the entry + tag links through the transaction client", async () => {
+    txClient.moodEntry.create.mockResolvedValue({
+      id: "mood-1",
+      tags: null,
+      moodLoggedAt: new Date(VALID_BODY.moodLoggedAt),
+      mood: "GUT",
+      note: null,
+      source: "MANUAL",
+      date: "2026-06-01",
+    });
+
+    const res = await POST(postReq(VALID_BODY));
+    expect(res.status).toBe(201);
+    // The tag-link write runs against the same `$transaction` client that
+    // created the entry, so both commit (or roll back) together.
+    expect(createTagLinks).toHaveBeenCalledWith("mood-1", ["happy"], txClient);
+  });
+
+  it("rolls the entry back when the tag-link write fails (no commit)", async () => {
+    txClient.moodEntry.create.mockResolvedValue({
+      id: "mood-2",
+      tags: null,
+      moodLoggedAt: new Date(VALID_BODY.moodLoggedAt),
+      mood: "GUT",
+      note: null,
+      source: "MANUAL",
+      date: "2026-06-01",
+    });
+    // A failing tag-link write must propagate out of the transaction so
+    // Prisma aborts the entry create — the route surfaces it as a 5xx and
+    // the entry is never committed (no audit row, no rollup recompute).
+    vi.mocked(createTagLinks).mockRejectedValueOnce(new Error("link write"));
+
+    const res = await POST(postReq(VALID_BODY));
+    expect(res.status).toBe(500);
+
+    const { auditLog } = await import("@/lib/auth/audit");
+    expect(auditLog).not.toHaveBeenCalled();
+    const { recomputeMoodBucketsForEntry } = await import(
+      "@/lib/rollups/mood-rollups"
+    );
+    expect(recomputeMoodBucketsForEntry).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/app/api/mood-entries/route.ts b/src/app/api/mood-entries/route.ts
index 8f3dad697..3c85035db 100644
--- a/src/app/api/mood-entries/route.ts
+++ b/src/app/api/mood-entries/route.ts
@@ -167,27 +167,34 @@ async function postMoodEntry(request: NextRequest) {
   const score = getScoreForMood(mood);
 
   try {
-    const entry = await prisma.moodEntry.create({
-      data: {
-        userId: user.id,
-        date,
-        tz,
-        mood,
-        score,
-        tags: tags ? JSON.stringify(tags) : null,
-        note: note ?? null,
-        source: source ?? "MANUAL",
-        moodLoggedAt,
-      },
-    });
+    // v1.8.5 — write the entry and its structured-tag links in one
+    // transaction. The links are user-intended content, not a cache, so a
+    // tag-link failure must roll the entry back too — otherwise a client
+    // retry on the 5xx mints a duplicate entry. The tx client is threaded
+    // through the helper so both writes commit (or abort) together.
+    const entry = await prisma.$transaction(async (tx) => {
+      const created = await tx.moodEntry.create({
+        data: {
+          userId: user.id,
+          date,
+          tz,
+          mood,
+          score,
+          tags: tags ? JSON.stringify(tags) : null,
+          note: note ?? null,
+          source: source ?? "MANUAL",
+          moodLoggedAt,
+        },
+      });
 
-    // v1.8.5 — write the structured-tag links. Unknown keys are dropped
-    // inside the helper (the catalog is the source of truth). Best-effort
-    // is wrong here — the links are user-intended content, not a cache —
-    // so a failure surfaces as a 5xx via the outer try/catch.
-    if (tagKeys && tagKeys.length > 0) {
-      await createTagLinks(entry.id, tagKeys);
-    }
+      if (tagKeys && tagKeys.length > 0) {
+        // Unknown keys are dropped inside the helper (the catalog is the
+        // source of truth).
+        await createTagLinks(created.id, tagKeys, tx);
+      }
+
+      return created;
+    });
 
     await auditLog("moodEntry.create", {
       userId: user.id,
diff --git a/src/lib/mood/tag-links.ts b/src/lib/mood/tag-links.ts
index ad6006d36..7be96add7 100644
--- a/src/lib/mood/tag-links.ts
+++ b/src/lib/mood/tag-links.ts
@@ -1,3 +1,4 @@
+import type { Prisma, PrismaClient } from "@/generated/prisma/client";
 import { prisma } from "@/lib/db";
 
 /**
@@ -7,16 +8,29 @@ import { prisma } from "@/lib/db";
  * write the `mood_entry_tag_links` join for a mood entry. The catalog is
  * the source of truth: unknown keys are dropped silently so a stale
  * client can never mint a link to a tag the deployment doesn't carry.
+ *
+ * Every helper accepts an optional `db` client so the caller can thread
+ * the same `$transaction` client that wrote the entry — the entry row and
+ * its links then commit (or roll back) together.
  */
 
+/**
+ * A Prisma client the helpers can run against: the singleton or a
+ * `$transaction` interactive client.
+ */
+type TagLinkDb = PrismaClient | Prisma.TransactionClient;
+
 /**
  * Resolve catalog tag keys to ids, dropping unknown / inactive keys.
  * Returns the ids in catalog order (deduped).
  */
-export async function resolveTagKeysToIds(keys: string[]): Promise<string[]> {
+export async function resolveTagKeysToIds(
+  keys: string[],
+  db: TagLinkDb = prisma,
+): Promise<string[]> {
   const unique = Array.from(new Set(keys));
   if (unique.length === 0) return [];
-  const rows = await prisma.moodTag.findMany({
+  const rows = await db.moodTag.findMany({
     where: { key: { in: unique }, isActive: true },
     select: { id: true },
   });
@@ -30,10 +44,11 @@ export async function resolveTagKeysToIds(keys: string[]): Promise<string[]> {
 export async function createTagLinks(
   moodEntryId: string,
   keys: string[],
+  db: TagLinkDb = prisma,
 ): Promise<void> {
-  const tagIds = await resolveTagKeysToIds(keys);
+  const tagIds = await resolveTagKeysToIds(keys, db);
   if (tagIds.length === 0) return;
-  await prisma.moodEntryTagLink.createMany({
+  await db.moodEntryTagLink.createMany({
     data: tagIds.map((moodTagId) => ({ moodEntryId, moodTagId })),
     skipDuplicates: true,
   });
@@ -48,9 +63,10 @@ export async function createTagLinks(
 export async function replaceTagLinks(
   moodEntryId: string,
   keys: string[],
+  db: TagLinkDb = prisma,
 ): Promise<void> {
-  const desiredIds = new Set(await resolveTagKeysToIds(keys));
-  const existing = await prisma.moodEntryTagLink.findMany({
+  const desiredIds = new Set(await resolveTagKeysToIds(keys, db));
+  const existing = await db.moodEntryTagLink.findMany({
     where: { moodEntryId },
     select: { moodTagId: true },
   });
@@ -60,12 +76,12 @@ export async function replaceTagLinks(
   const toCreate = [...desiredIds].filter((id) => !existingIds.has(id));
 
   if (toDelete.length > 0) {
-    await prisma.moodEntryTagLink.deleteMany({
+    await db.moodEntryTagLink.deleteMany({
       where: { moodEntryId, moodTagId: { in: toDelete } },
     });
   }
   if (toCreate.length > 0) {
-    await prisma.moodEntryTagLink.createMany({
+    await db.moodEntryTagLink.createMany({
       data: toCreate.map((moodTagId) => ({ moodEntryId, moodTagId })),
       skipDuplicates: true,
     });

From 78d3478ad28b82ef7b5ae37c80e6e042fdadc7cd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 21:11:47 +0200
Subject: [PATCH 22/30] fix(mood): return tag keys from create and update

The list GET surfaces tagKeys per entry but the create and update
responses omitted it, so a client hydrating from the response body
showed an empty tag set until the next refetch. Read the persisted
link keys back inside the write transaction and include them in both
response bodies.
---
 src/app/api/mood-entries/[id]/route.ts        | 47 +++++++++----
 .../api/mood-entries/__tests__/route.test.ts  | 24 +++++++
 src/app/api/mood-entries/route.ts             | 67 +++++++++++++------
 3 files changed, 102 insertions(+), 36 deletions(-)

diff --git a/src/app/api/mood-entries/[id]/route.ts b/src/app/api/mood-entries/[id]/route.ts
index aff2f1548..f0e940154 100644
--- a/src/app/api/mood-entries/[id]/route.ts
+++ b/src/app/api/mood-entries/[id]/route.ts
@@ -139,21 +139,33 @@ export const PUT = apiHandler(
     // too — otherwise a client retry on the 5xx double-applies the edit
     // (and the `syncVersion` increment). The tx client is threaded through
     // the helper so both writes commit (or abort) together.
-    const entry = await prisma.$transaction(async (tx) => {
-      const updated = await tx.moodEntry.update({
-        where: { id },
-        data: updateData,
-      });
+    const { entry, persistedTagKeys } = await prisma.$transaction(
+      async (tx) => {
+        const updated = await tx.moodEntry.update({
+          where: { id },
+          data: updateData,
+        });
 
-      // Full replacement of the structured-tag link set when `tagKeys`
-      // is present in the body. `null` clears every link; an omitted
-      // field leaves the links untouched.
-      if (data.tagKeys !== undefined) {
-        await replaceTagLinks(id, data.tagKeys ?? [], tx);
-      }
+        // Full replacement of the structured-tag link set when `tagKeys`
+        // is present in the body. `null` clears every link; an omitted
+        // field leaves the links untouched.
+        if (data.tagKeys !== undefined) {
+          await replaceTagLinks(id, data.tagKeys ?? [], tx);
+        }
 
-      return updated;
-    });
+        // v1.8.5 — read the persisted link keys back so the update
+        // response mirrors the list GET shape exactly.
+        const links = await tx.moodEntryTagLink.findMany({
+          where: { moodEntryId: id },
+          select: { moodTag: { select: { key: true } } },
+        });
+
+        return {
+          entry: updated,
+          persistedTagKeys: links.map((link) => link.moodTag.key),
+        };
+      },
+    );
 
     await auditLog("moodEntry.update", {
       userId: user.id,
@@ -194,7 +206,14 @@ export const PUT = apiHandler(
       });
     }
 
-    return apiSuccess({ ...entry, tags: parseTags(entry.tags) });
+    return apiSuccess({
+      ...entry,
+      tags: parseTags(entry.tags),
+      // v1.8.5 — surface the persisted structured-tag keys so a client
+      // hydrating from the update response renders the tag set without a
+      // refetch (shape-matches the list GET).
+      tagKeys: persistedTagKeys,
+    });
   },
 );
 
diff --git a/src/app/api/mood-entries/__tests__/route.test.ts b/src/app/api/mood-entries/__tests__/route.test.ts
index a6f45e5dd..d15b8852c 100644
--- a/src/app/api/mood-entries/__tests__/route.test.ts
+++ b/src/app/api/mood-entries/__tests__/route.test.ts
@@ -243,6 +243,30 @@ describe("POST /api/mood-entries — entry + tag-links transaction (v1.8.5)", ()
     expect(createTagLinks).toHaveBeenCalledWith("mood-1", ["happy"], txClient);
   });
 
+  it("returns the persisted tagKeys in the create response", async () => {
+    txClient.moodEntry.create.mockResolvedValue({
+      id: "mood-1",
+      tags: null,
+      moodLoggedAt: new Date(VALID_BODY.moodLoggedAt),
+      mood: "GUT",
+      note: null,
+      source: "MANUAL",
+      date: "2026-06-01",
+    });
+    txClient.moodEntryTagLink.findMany.mockResolvedValue([
+      { moodTag: { key: "happy" } },
+    ]);
+
+    const res = await POST(postReq(VALID_BODY));
+    expect(res.status).toBe(201);
+    const body = (await res.json()) as {
+      data: { id: string; tagKeys: string[] };
+    };
+    // Read-after-write parity: the create response carries the same
+    // `tagKeys` the list GET surfaces.
+    expect(body.data.tagKeys).toEqual(["happy"]);
+  });
+
   it("rolls the entry back when the tag-link write fails (no commit)", async () => {
     txClient.moodEntry.create.mockResolvedValue({
       id: "mood-2",
diff --git a/src/app/api/mood-entries/route.ts b/src/app/api/mood-entries/route.ts
index 3c85035db..40a95fe20 100644
--- a/src/app/api/mood-entries/route.ts
+++ b/src/app/api/mood-entries/route.ts
@@ -172,29 +172,42 @@ async function postMoodEntry(request: NextRequest) {
     // tag-link failure must roll the entry back too — otherwise a client
     // retry on the 5xx mints a duplicate entry. The tx client is threaded
     // through the helper so both writes commit (or abort) together.
-    const entry = await prisma.$transaction(async (tx) => {
-      const created = await tx.moodEntry.create({
-        data: {
-          userId: user.id,
-          date,
-          tz,
-          mood,
-          score,
-          tags: tags ? JSON.stringify(tags) : null,
-          note: note ?? null,
-          source: source ?? "MANUAL",
-          moodLoggedAt,
-        },
-      });
+    const { entry, persistedTagKeys } = await prisma.$transaction(
+      async (tx) => {
+        const created = await tx.moodEntry.create({
+          data: {
+            userId: user.id,
+            date,
+            tz,
+            mood,
+            score,
+            tags: tags ? JSON.stringify(tags) : null,
+            note: note ?? null,
+            source: source ?? "MANUAL",
+            moodLoggedAt,
+          },
+        });
 
-      if (tagKeys && tagKeys.length > 0) {
-        // Unknown keys are dropped inside the helper (the catalog is the
-        // source of truth).
-        await createTagLinks(created.id, tagKeys, tx);
-      }
+        if (tagKeys && tagKeys.length > 0) {
+          // Unknown keys are dropped inside the helper (the catalog is the
+          // source of truth).
+          await createTagLinks(created.id, tagKeys, tx);
+        }
 
-      return created;
-    });
+        // v1.8.5 — read the persisted link keys back so the create
+        // response mirrors the list GET shape exactly (unknown keys
+        // already filtered out).
+        const links = await tx.moodEntryTagLink.findMany({
+          where: { moodEntryId: created.id },
+          select: { moodTag: { select: { key: true } } },
+        });
+
+        return {
+          entry: created,
+          persistedTagKeys: links.map((link) => link.moodTag.key),
+        };
+      },
+    );
 
     await auditLog("moodEntry.create", {
       userId: user.id,
@@ -250,7 +263,17 @@ async function postMoodEntry(request: NextRequest) {
       // rejection in the Next.js runtime.
     });
 
-    return apiSuccess({ ...entry, tags: parseTags(entry.tags) }, 201);
+    return apiSuccess(
+      {
+        ...entry,
+        tags: parseTags(entry.tags),
+        // v1.8.5 — surface the persisted structured-tag keys so a client
+        // hydrating from the create response renders the tag set without a
+        // refetch (shape-matches the list GET).
+        tagKeys: persistedTagKeys,
+      },
+      201,
+    );
   } catch (err) {
     if (
       err instanceof Prisma.PrismaClientKnownRequestError &&

From baa1ff250cd35b57150b318e652d4b7da9368224 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 21:13:03 +0200
Subject: [PATCH 23/30] refactor(insights): table-drive the mood correlations

The five mood-metric correlations and the measurement query's type
filter were two hand-kept copies of the same channel list. Introduce a
CORRELATION_METRICS map and single-source both the correlations object
and the fetch filter from it so they cannot drift.
---
 src/lib/insights/mood-aggregates.ts | 70 +++++++++++------------------
 1 file changed, 27 insertions(+), 43 deletions(-)

diff --git a/src/lib/insights/mood-aggregates.ts b/src/lib/insights/mood-aggregates.ts
index 1a7f746d6..7f17e4886 100644
--- a/src/lib/insights/mood-aggregates.ts
+++ b/src/lib/insights/mood-aggregates.ts
@@ -478,6 +478,23 @@ export function computeMoodMetricCorrelation(
 
 // --- Orchestrated aggregate shape ---
 
+/**
+ * v1.8.5 — the cross-metric channels the mood page correlates against,
+ * mapping the correlation key the UI reads to its measurement type. This
+ * is the single source for both the `correlations` object below and the
+ * `fetchMoodAggregates` measurement `in:[...]` filter, so the two can
+ * never drift out of sync.
+ */
+export const CORRELATION_METRICS = {
+  sleep: "SLEEP_DURATION",
+  steps: "ACTIVITY_STEPS",
+  pulse: "PULSE",
+  weight: "WEIGHT",
+  bloodPressureSystolic: "BLOOD_PRESSURE_SYS",
+} as const;
+
+type CorrelationKey = keyof typeof CORRELATION_METRICS;
+
 export interface MoodAggregates {
   summary: {
     points: number;
@@ -503,13 +520,7 @@ export interface MoodAggregates {
   structuredTags: StructuredTagRow[];
   /** v1.8.5 — recent notes timeline (qualitative-reflection feed). */
   notesTimeline: NoteTimelineEntry[];
-  correlations: {
-    sleep: MoodMetricCorrelation;
-    steps: MoodMetricCorrelation;
-    pulse: MoodMetricCorrelation;
-    weight: MoodMetricCorrelation;
-    bloodPressureSystolic: MoodMetricCorrelation;
-  };
+  correlations: Record<CorrelationKey, MoodMetricCorrelation>;
 }
 
 /**
@@ -583,33 +594,12 @@ export function computeMoodAggregates(args: {
     tags: computeTagSummary(entries, now),
     structuredTags: computeStructuredTagSummary(entries, now),
     notesTimeline: computeNotesTimeline(entries),
-    correlations: {
-      sleep: computeMoodMetricCorrelation(
-        moodDaily,
-        metricDaily("SLEEP_DURATION"),
-        now,
-      ),
-      steps: computeMoodMetricCorrelation(
-        moodDaily,
-        metricDaily("ACTIVITY_STEPS"),
-        now,
-      ),
-      pulse: computeMoodMetricCorrelation(
-        moodDaily,
-        metricDaily("PULSE"),
-        now,
-      ),
-      weight: computeMoodMetricCorrelation(
-        moodDaily,
-        metricDaily("WEIGHT"),
-        now,
-      ),
-      bloodPressureSystolic: computeMoodMetricCorrelation(
-        moodDaily,
-        metricDaily("BLOOD_PRESSURE_SYS"),
-        now,
-      ),
-    },
+    correlations: Object.fromEntries(
+      Object.entries(CORRELATION_METRICS).map(([key, type]) => [
+        key,
+        computeMoodMetricCorrelation(moodDaily, metricDaily(type), now),
+      ]),
+    ) as MoodAggregates["correlations"],
   };
 }
 
@@ -678,15 +668,9 @@ export async function fetchMoodAggregates(
         userId,
         deletedAt: null,
         measuredAt: { gte: windowCutoff },
-        type: {
-          in: [
-            "WEIGHT",
-            "BLOOD_PRESSURE_SYS",
-            "PULSE",
-            "SLEEP_DURATION",
-            "ACTIVITY_STEPS",
-          ],
-        },
+        // v1.8.5 — single-sourced from CORRELATION_METRICS so the fetched
+        // channels and the computed correlations never drift apart.
+        type: { in: Object.values(CORRELATION_METRICS) },
       },
       orderBy: { measuredAt: "desc" },
       take: 5000,

From bd0b284201fddce5742251e40118f8941365b4ce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 21:13:39 +0200
Subject: [PATCH 24/30] fix(a11y): enlarge mood tag chips to the 44px tap
 target

The structured-tag picker chips and the side-effect chips sat at 32px
(min-h-8), under the 44px minimum and a fat-finger risk on a phone where
they wrap tightly. Bump both to min-h-11 with matched padding so the tap
target clears 44px without loosening the visual density.
---
 src/components/mood/mood-form.tsx       | 2 +-
 src/components/mood/mood-tag-picker.tsx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/components/mood/mood-form.tsx b/src/components/mood/mood-form.tsx
index a42ce14e1..38ac2d570 100644
--- a/src/components/mood/mood-form.tsx
+++ b/src/components/mood/mood-form.tsx
@@ -313,7 +313,7 @@ export function MoodForm({ onSuccess, onCancel, footerSlot }: MoodFormProps) {
                       setTagsInput(next);
                     }
                   }}
-                  className={`min-h-8 rounded-full border px-2.5 py-1 text-xs transition-colors ${
+                  className={`inline-flex min-h-11 items-center rounded-full border px-3 py-2 text-xs transition-colors ${
                     isActive
                       ? "border-primary bg-primary/15 text-primary"
                       : "border-border/70 bg-muted text-foreground/75 hover:bg-accent hover:text-foreground"
diff --git a/src/components/mood/mood-tag-picker.tsx b/src/components/mood/mood-tag-picker.tsx
index 76dbae0ec..25139e103 100644
--- a/src/components/mood/mood-tag-picker.tsx
+++ b/src/components/mood/mood-tag-picker.tsx
@@ -92,7 +92,7 @@ export function MoodTagPicker({
                     type="button"
                     onClick={() => onToggle(tag.key)}
                     aria-pressed={isActive}
-                    className={`inline-flex min-h-8 items-center gap-1.5 rounded-full border px-2.5 py-1 text-xs transition-colors ${
+                    className={`inline-flex min-h-11 items-center gap-1.5 rounded-full border px-3 py-2 text-xs transition-colors ${
                       isActive
                         ? "border-primary bg-primary/15 text-primary"
                         : "border-border/70 bg-muted text-foreground/75 hover:bg-accent hover:text-foreground"

From b10569dc443a69bae77e4ba2d783d1d8161ba0c3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 21:14:08 +0200
Subject: [PATCH 25/30] fix(insights): give the mood distribution chart a
 zero-bucket track

A mood level with no days painted a zero-height bar with no affordance,
reading as missing rather than "0". Add a faint full-height track behind
each bar so empty buckets stay legible; the coloured bar paints over the
track for the populated levels.
---
 .../insights/mood/mood-distribution-chart.tsx          | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/components/insights/mood/mood-distribution-chart.tsx b/src/components/insights/mood/mood-distribution-chart.tsx
index 5e049daff..7e2f39915 100644
--- a/src/components/insights/mood/mood-distribution-chart.tsx
+++ b/src/components/insights/mood/mood-distribution-chart.tsx
@@ -85,7 +85,15 @@ export function MoodDistributionChart({
               ] as [string, string]
             }
           />
-          <Bar dataKey="count" radius={[3, 3, 0, 0]}>
+          <Bar
+            dataKey="count"
+            radius={[3, 3, 0, 0]}
+            // v1.8.5 — faint full-height track behind each bar so a
+            // zero-count level still reads as a present "0" bucket rather
+            // than a missing slot. The coloured bar paints over the track
+            // for non-empty levels.
+            background={{ fill: "var(--secondary)", opacity: 0.35, radius: 3 }}
+          >
             {data.map((row) => (
               <Cell
                 key={row.score}

From 146867b09f59ac3450043e2cbf38d0313115d878 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 21:04:25 +0200
Subject: [PATCH 26/30] fix(insights): show one adjust-target link for the
 glucose panel group
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The blood-glucose reference panel fans out to up to four per-context
panels (fasting / postprandial / random / bedtime), each previously
emitting its own identical "Adjust target range" link to /targets — so
the page stacked up to four copies of the same link. Lift the link to
the group wrapper and render it once; keep the per-panel link for the
non-glucose single-panel path.
---
 .../insights/metric-target-summary.tsx        | 34 +++++++++++++++----
 1 file changed, 28 insertions(+), 6 deletions(-)

diff --git a/src/components/insights/metric-target-summary.tsx b/src/components/insights/metric-target-summary.tsx
index 9508ff34a..c444dc25c 100644
--- a/src/components/insights/metric-target-summary.tsx
+++ b/src/components/insights/metric-target-summary.tsx
@@ -169,6 +169,9 @@ export function MetricTargetSummary({ slug }: MetricTargetSummaryProps) {
 
     if (panels.length === 0) return null;
 
+    // Glucose fans out to up to four per-context panels. The
+    // "Adjust target range" link is identical on every one, so render
+    // it once for the whole group rather than repeating it per panel.
     return (
       <div className="space-y-2" data-slot="metric-target-summary-group">
         {panels.map((panel) => (
@@ -176,8 +179,12 @@ export function MetricTargetSummary({ slug }: MetricTargetSummaryProps) {
             key={panel.type}
             target={panel}
             heading={panel.label}
+            hideAdjustLink
           />
         ))}
+        <div className="flex justify-end px-1">
+          <AdjustTargetLink />
+        </div>
       </div>
     );
   }
@@ -200,6 +207,25 @@ interface TargetReferencePanelProps {
   bpDiastolic?: TargetsResponse["bpDiastolic"];
   /** Optional sub-heading shown above the panel (used for glucose contexts). */
   heading?: string;
+  /**
+   * Suppress the per-panel "Adjust target range" link. Glucose stacks
+   * up to four panels and lifts a single link to the group wrapper, so
+   * each panel omits its own to avoid repeating the same link.
+   */
+  hideAdjustLink?: boolean;
+}
+
+/** The shared "Adjust target range" link to the `/targets` editing surface. */
+function AdjustTargetLink() {
+  const { t } = useTranslations();
+  return (
+    <Link
+      href="/targets"
+      className="text-muted-foreground hover:text-foreground focus-visible:ring-ring/50 inline-flex min-h-11 items-center rounded-sm px-1 text-xs font-medium underline-offset-4 transition-colors hover:underline focus-visible:ring-2 focus-visible:outline-none"
+    >
+      {t("insights.subPage.target.adjustLink")}
+    </Link>
+  );
 }
 
 /**
@@ -213,6 +239,7 @@ function TargetReferencePanel({
   target,
   bpDiastolic,
   heading,
+  hideAdjustLink,
 }: TargetReferencePanelProps) {
   const { t } = useTranslations();
 
@@ -368,12 +395,7 @@ function TargetReferencePanel({
             {t("targets.sourceLabel", { source: target.source })}
           </span>
         )}
-        <Link
-          href="/targets"
-          className="text-muted-foreground hover:text-foreground focus-visible:ring-ring/50 inline-flex min-h-11 items-center rounded-sm px-1 text-xs font-medium underline-offset-4 transition-colors hover:underline focus-visible:ring-2 focus-visible:outline-none"
-        >
-          {t("insights.subPage.target.adjustLink")}
-        </Link>
+        {hideAdjustLink ? null : <AdjustTargetLink />}
       </div>
     </div>
   );

From 0b10932c53fdf50454259481295f7bc9b2129c95 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 21:04:30 +0200
Subject: [PATCH 27/30] docs(insights): pin the median window contract across
 the summary paths
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

DataSummary.median carries two windows under one field name: the SQL
summaries-slice path windows PERCENTILE_CONT to the trailing 90 days,
while the JS summarize() takes the median over the full series it is
handed (a caller-defined window). No user-visible bug today — the stat
strip only reads the 90-day SQL path — but a future consumer reading
summary.median off a summarize()-derived payload would silently get a
different number. Document the window on the type and at both call sites
so the divergence is explicit; the percentile algorithm matches, only
the window differs.
---
 src/lib/analytics/summaries-slice.ts |  6 ++++++
 src/lib/analytics/trends.ts          | 27 +++++++++++++++++++++------
 2 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/src/lib/analytics/summaries-slice.ts b/src/lib/analytics/summaries-slice.ts
index 1125aea0d..9a1ce8988 100644
--- a/src/lib/analytics/summaries-slice.ts
+++ b/src/lib/analytics/summaries-slice.ts
@@ -117,6 +117,12 @@ interface NarrowAggregateRow {
    * sorting every raw row per type, which the rollup tier cannot
    * compose and which the perf posture (v1.8.3 anti-freeze) forbids on
    * the read path. Null when the window holds no rows.
+   *
+   * NOTE: this window (trailing 90 days) is the contract for the stat
+   * strip's `DataSummary.median`. The JS `summarize()` in `trends.ts`
+   * computes its median over the *full* series it is handed (a
+   * caller-defined window), so the two share a field name but not a
+   * window — see the `median` doc on `DataSummary`.
    */
   median: number | null;
   avg30_last_month: number | null;
diff --git a/src/lib/analytics/trends.ts b/src/lib/analytics/trends.ts
index eae723f45..7d8b988ac 100644
--- a/src/lib/analytics/trends.ts
+++ b/src/lib/analytics/trends.ts
@@ -125,6 +125,17 @@ export interface DataSummary {
    * the insights category-page stat strip alongside min / max / mean so
    * a skewed series (a few very high or very low readings dragging the
    * mean) reads honestly. Null when the series is empty.
+   *
+   * Window: caller-defined. `summarize()` computes the median over the
+   * full `DataPoint[]` it is handed, so the window is whatever the caller
+   * passed (full history for `/api/measurements/series`, per-day means
+   * for the snapshot builder, …). It is NOT guaranteed to be the trailing
+   * 90-day window. The insights stat strip does not read this value — its
+   * median comes from the SQL `summaries-slice` path, which fixes the
+   * window to the trailing 90 days (`PERCENTILE_CONT(0.5) … FILTER (WHERE
+   * measured_at >= NOW() - INTERVAL '90 days')`). A consumer comparing the
+   * two must account for the differing windows. The percentile *algorithm*
+   * matches (linear-interpolated midpoint), only the window differs.
    */
   median: number | null;
   avg7: number | null;
@@ -192,12 +203,16 @@ export function summarize(data: DataPoint[]): DataSummary {
   }
   const mean = sum / values.length;
 
-  // v1.8.5 — median (50th percentile) over the full series. A separate
-  // numeric sort from the date-ordered `sorted` array above so the
-  // percentile is taken over values, not timestamps. Linear-interpolated
-  // midpoint on an even-length series (the standard PERCENTILE_CONT
-  // definition) so this matches the SQL `PERCENTILE_CONT(0.5)` the
-  // rollup-tier slim slice emits.
+  // v1.8.5 — median (50th percentile) over the FULL series handed to
+  // this function (the window is caller-defined; see the `median` doc on
+  // DataSummary). A separate numeric sort from the date-ordered `sorted`
+  // array above so the percentile is taken over values, not timestamps.
+  // Linear-interpolated midpoint on an even-length series (the standard
+  // PERCENTILE_CONT definition) so the *algorithm* matches the SQL
+  // `PERCENTILE_CONT(0.5)` the rollup-tier slim slice emits — but note
+  // the SQL path windows to the trailing 90 days while this path does
+  // not, so the two are byte-comparable only when the caller already
+  // passed a 90-day series.
   const valueSorted = [...values].sort((a, b) => a - b);
   const mid = Math.floor(valueSorted.length / 2);
   const median =

From 6a2762ec35a2e190864c918c402511e6a734da80 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 21:04:38 +0200
Subject: [PATCH 28/30] fix(a11y): raise the target status-pill text contrast
 to AA

The status pill painted full-saturation Dracula green/orange/red text on
a 12-14% same-hue tint. That fails WCAG AA (4.5:1) for the out tone on
the muted insights reference panel in dark mode (3.87:1) and for every
tone on a white card in light mode (1.2-2.7:1), since the pill used the
raw Dracula palette rather than the theme-aware feedback tokens.

Switch the pill to dedicated theme-aware tokens (status-pill-in/near/out)
and a 10% tint: dark mode keeps Dracula green/orange and lifts the out
tone off #ff5555 to a lighter red; light mode adopts the darker
AA-corrected family already used for the chart and destructive colours.
All three tones now clear 4.5:1 on both bg-card and bg-muted/30 in both
themes (worst case 4.62:1).
---
 src/app/globals.css                           | 33 +++++++++++++++++++
 src/components/targets/target-status-pill.tsx | 14 ++++++--
 2 files changed, 44 insertions(+), 3 deletions(-)

diff --git a/src/app/globals.css b/src/app/globals.css
index ea3744a81..a3e673edc 100644
--- a/src/app/globals.css
+++ b/src/app/globals.css
@@ -97,6 +97,18 @@
   --color-success: var(--success);
   --color-warning: var(--warning);
   --color-info: var(--info);
+
+  /*
+   * Status-pill text tokens. The target status pill paints coloured text
+   * on a 10% same-hue tint; the raw Dracula green/orange/red would fail
+   * WCAG AA (4.5:1) for the "out" tone on the muted reference panel in
+   * dark mode and for every tone on a white card in light mode. These
+   * theme-aware tokens land each tone at or above AA on both `bg-card`
+   * and `bg-muted/30` in both themes while keeping the Dracula feel.
+   */
+  --color-status-pill-in: var(--status-pill-in);
+  --color-status-pill-near: var(--status-pill-near);
+  --color-status-pill-out: var(--status-pill-out);
 }
 
 /*
@@ -167,6 +179,16 @@
   --sidebar-border: #44475a;
   --sidebar-ring: #bd93f9;
 
+  /*
+   * Status-pill text in dark mode. "in" / "near" keep the Dracula
+   * green / orange (both clear AA on the muted panel); "out" lifts off
+   * the raw `#ff5555`, which lands at 3.99:1 on `bg-muted/30`, to a
+   * lighter Dracula red that clears 4.5:1 on both card and panel.
+   */
+  --status-pill-in: #50fa7b;
+  --status-pill-near: #ffb86c;
+  --status-pill-out: #ff8a8a;
+
   color-scheme: dark;
 }
 
@@ -212,6 +234,17 @@
   --sidebar-border: #cfcfde;
   --sidebar-ring: #644ac9;
 
+  /*
+   * Status-pill text in light mode (Alucard). The bright Dracula
+   * green / orange / red read 1.2–2.7:1 on a near-white tint; these
+   * darker tones — the same family already used for `--success` /
+   * `--warning` / the light-mode reds — clear AA on both the white card
+   * and the muted reference panel.
+   */
+  --status-pill-in: #14720a;
+  --status-pill-near: #a34d14;
+  --status-pill-out: #b32d1e;
+
   color-scheme: light;
 }
 
diff --git a/src/components/targets/target-status-pill.tsx b/src/components/targets/target-status-pill.tsx
index 1959e966a..d2272572d 100644
--- a/src/components/targets/target-status-pill.tsx
+++ b/src/components/targets/target-status-pill.tsx
@@ -148,6 +148,14 @@ export function statusGroupForCategory(
   return "near";
 }
 
+// Coloured text on a 10% same-hue tint with a 30% ring. The tint and
+// text share one theme-aware token per tone (`--status-pill-{in,near,
+// out}` in globals.css) so the pill clears WCAG AA (4.5:1) on both the
+// Targets card (`bg-card`) and the W5 insights reference panel
+// (`bg-muted/30`) in both dark and light themes — the raw Dracula
+// green/orange/red failed AA for the "out" tone on the muted panel in
+// dark mode and for every tone on a white card in light mode.
+//
 // Use the Tailwind v4 parenthesised CSS-variable shorthand
 // (bg-VAR-PAREN-FORM-/N) instead of the legacy bracketed VAR-form. The
 // bracketed form combined with an opacity modifier emits an escaped
@@ -158,9 +166,9 @@ export function statusGroupForCategory(
 // that parses cleanly. See the Tailwind v4 upgrade guide for the
 // migration from bracket-form to paren-form for CSS-variable values.
 export const STATUS_PILL_STYLES: Record<"in" | "near" | "out", string> = {
-  in: "bg-(--dracula-green)/12 text-(--dracula-green) ring-(--dracula-green)/30",
-  near: "bg-(--dracula-orange)/14 text-(--dracula-orange) ring-(--dracula-orange)/30",
-  out: "bg-(--dracula-red)/12 text-(--dracula-red) ring-(--dracula-red)/30",
+  in: "bg-(--status-pill-in)/10 text-(--status-pill-in) ring-(--status-pill-in)/30",
+  near: "bg-(--status-pill-near)/10 text-(--status-pill-near) ring-(--status-pill-near)/30",
+  out: "bg-(--status-pill-out)/10 text-(--status-pill-out) ring-(--status-pill-out)/30",
 };
 
 export interface TargetStatusPillProps {

From bdacd78b0af658ed86d8d16c0281b8f58f71d78c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 21:21:02 +0200
Subject: [PATCH 29/30] =?UTF-8?q?chore(release):=20v1.8.5=20=E2=80=94=20In?=
 =?UTF-8?q?sights=20reference=20panels,=20mood=20depth,=20injection=20trac?=
 =?UTF-8?q?king?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CHANGELOG.md | 27 +++++++++++++++++++++++++++
 package.json |  2 +-
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 92abd02d2..af8ac9363 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,32 @@
 # Changelog
 
+## [1.8.5] — 2026-06-01 — Insights reference panels, mood depth, injection tracking
+
+### Added
+
+- **A target reference panel on every Insights category page.** Each metric now shows the target band, where the latest reading sits inside it, a plain-language status, the guideline source behind the range, the 30-day average and a seven-day consistency strip — the same reference the Targets page carries, now on the page where you read the trend. Blood glucose surfaces one panel per context (fasting, post-meal, random, bedtime).
+- **A statistics strip per metric** — minimum, maximum, median and mean — plus a dedicated page that lists every underlying reading with edit and delete, reachable from each Insights category.
+- **Injection-site tracking and rotation.** Opt-in per medication (injections only): record the site after a dose, see the history on a body map, and get a rotation suggestion. Sites can be restricted per medication, and an account-level exclusion always wins.
+- **Structured mood tags and a per-entry note**, with a notes timeline so the context behind a mood is kept alongside the score.
+- **A richer mood page** — calendar heatmap, score distribution, weekday pattern, and correlations with sleep and activity.
+- **A measurement-diversity nudge** that suggests logging at other times or days when readings cluster, for a fuller picture.
+
+### Changed
+
+- **The medication compliance display adapts to how often a dose is due** — a percentage for frequent schedules, a dose-by-dose adherence timeline for sparse ones, so an every-few-weeks medication reads sensibly.
+- **The Trends section now follows the daily briefing**, charting the metrics the briefing actually flags rather than a fixed set.
+- **Tightened the Insights category pages and rebalanced the overview** for a denser, calmer layout.
+- **Gait and mobility metrics from Apple Health are consolidated to a daily mean overnight**, while discrete clinical readings (weight, blood pressure, glucose, mood, pulse) stay raw.
+- **The health-record FHIR export codes HealthKit-only metrics under a dedicated code system** instead of the LOINC namespace, for FHIR R4 conformance and alignment with the native client.
+
+### Fixed
+
+- **A rolling-interval medication now surfaces its first dose at the start date** — including when that date is already in the past — so the dashboard and reminders no longer skip the opening dose.
+- **The medication wizard no longer shows each time-of-day suggestion twice.**
+- **Deleting a medication no longer hangs on a spinner.**
+- **Mood entries with tags save atomically** — the entry and its tags commit together, and create and update return the saved tags immediately rather than after a refresh.
+- **Accessibility:** the injection-site picker has a visible focus state and screen-reader labels; mood tag chips and the status pill meet the contrast and minimum tap-target guidelines.
+
 ## [1.8.4] — 2026-06-01 — Medication card accuracy + Insights polish
 
 ### Fixed
diff --git a/package.json b/package.json
index ed9603af0..f6ff459ec 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "healthlog",
-  "version": "1.8.4",
+  "version": "1.8.5",
   "description": "Self-hosted personal-health-tracking PWA with Withings integration, AI insights, and doctor-report PDF export.",
   "license": "AGPL-3.0-only",
   "homepage": "https://healthlog.dev",

From 0fe2ac6d51499b470a9db18bd3526c4c5c1c00f6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marc-Andr=C3=A9=20Bombeck?= <mbombeck@gmail.com>
Date: Mon, 1 Jun 2026 21:36:40 +0200
Subject: [PATCH 30/30] chore(api): regenerate the OpenAPI spec for 1.8.5

---
 docs/api/openapi.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml
index 89be8acd4..2788fb057 100644
--- a/docs/api/openapi.yaml
+++ b/docs/api/openapi.yaml
@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: HealthLog API
-  version: 1.8.4
+  version: 1.8.5
   description: >-
     Self-hosted personal-health-tracking PWA — public API surface for the iOS native client and external ingest.