From 1e534dfbf2182dafb235eb2a284996d80b4b305c Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Thu, 27 Aug 2026 14:10:04 +0800
Subject: [PATCH 1/9] fix(design-system): pay down Hazard 1-2 contract debt

Remaining Lucide size={15} and 1px shadow spreads were blocking the
token contract. Map those to named tokens, drop unused v2 line-height
companions, and record leftover Hazard 2/3 items in FIX-GUIDE.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/design-system-contract.md                |  2 +-
 docs/design-system/COMPONENTS.md              |  6 +-
 docs/design-system/FIX-GUIDE.md               | 94 +++++++++++++++++++
 docs/design-system/GATES.md                   | 12 +--
 docs/design-system/README.md                  |  1 +
 docs/design-system/TOKENS.md                  |  9 +-
 scripts/design-system-contract-baseline.json  | 72 ++++++--------
 scripts/design-system-contract-utils.mjs      | 31 ++++++
 src/app/ckb-v2-tokens.css                     | 23 +----
 src/app/globals.css                           | 13 ++-
 .../differential-detail-page.tsx              |  4 +-
 .../specifiers/specifier-builder-page.tsx     |  6 +-
 src/components/specifiers/specifier-ui.tsx    |  6 +-
 .../therapy-compass/screens/brief-screen.tsx  |  5 +-
 .../screens/compare-screen.tsx                |  6 +-
 .../screens/recommend-screen.tsx              |  2 +-
 .../therapy-compass/screens/sheets-screen.tsx |  6 +-
 .../therapy-compass/therapy-card.tsx          |  5 +-
 tests/ckb-v2-token-contract.test.ts           | 13 ++-
 tests/design-system-contract-utils.test.ts    | 46 +++++++++
 20 files changed, 250 insertions(+), 112 deletions(-)
 create mode 100644 docs/design-system/FIX-GUIDE.md

diff --git a/docs/design-system-contract.md b/docs/design-system-contract.md
index ce96a3b554..850ab04813 100644
--- a/docs/design-system-contract.md
+++ b/docs/design-system-contract.md
@@ -29,7 +29,7 @@ npm run check:icon-scale
   - **Text Roles**: `var(--text)`, `var(--text-muted)`, `var(--text-heading)`, `var(--text-soft)`
   - **Status & Safety Triads**: `--success-*`, `--warning-*`, `--danger-*`, `--info-*` (reserved exclusively for clinical/system status).
   - **Focus Ring & Outlines**: `var(--focus)` for all keyboard and visible focus rings.
-- **Raw Color Exemptions**: Strict and enumerated in `RAW_COLOR_EXEMPTIONS` in `scripts/design-system-contract-utils.mjs` (e.g., globals token definitions, brand mark SVG builder, diagnostic visualizations, OpenGraph art, printable patient/factsheet paper).
+- **Raw Color Exemptions**: Strict and enumerated in `RAW_COLOR_EXEMPTIONS` in `scripts/design-system-contract-utils.mjs` (e.g., globals token definitions, brand mark SVG builder, diagnostic visualizations, OpenGraph art, printable patient/factsheet paper). Medication record accent defaults (`#0f766e` in `src/lib/medications.ts` and `src/lib/medication-records.ts`) are a **scoped** exemption for the Postgres `accent` column default only — not a whole-file blank cheque, and not a mapping onto `--clinical-accent`.
 
 ### 2.2 Typography Scale
 
diff --git a/docs/design-system/COMPONENTS.md b/docs/design-system/COMPONENTS.md
index e1a2b7cb4e..72afab134c 100644
--- a/docs/design-system/COMPONENTS.md
+++ b/docs/design-system/COMPONENTS.md
@@ -20,7 +20,7 @@ derived from source, `.design-sync/config.json`, previews, direct contract cover
 production imports. It intentionally does not claim dark, forced-colours, 320px, print, remote
 publication, or product adoption without separate evidence.
 
-### 0.1 Registered visual components (54 — local contract; remote status unverified)
+### 0.1 Registered visual components (55 — local contract; remote status unverified)
 
 Every visual export has one source map entry, a source-derived public `*Props` contract (except
 the two zero-prop roots), a reference preview, and a direct static publication test. The generated
@@ -37,7 +37,7 @@ table under **Generated maturity snapshot** is the canonical list and product-im
 
 _Remaining from the original eight in this document:_ `DocumentFrame` is built locally
 (`src/components/ui/document-frame.tsx`, shell-only in `DocumentViewer`) but is not yet among
-the 54 design-sync registered visual exports — registration and full controls remain follow-up.
+the 55 design-sync registered visual exports — registration and full controls remain follow-up.
 
 `OverlayRoot`, `SegmentedControl`, and the PR 6–8 components are built and represented by the
 local publication contract. The generated snapshot records their current product-import counts;
@@ -86,7 +86,7 @@ print primitives (`PrintHeader`, `PrintFooter`, `CitationFootnote`, `PrintOnly`,
 | Progress/StageList           | all four resolved: `scaleX`, the theme `animate-shimmer` in place of a hardcoded `1.4s`, a step index clamped to ≥1, and an sr-only `role="status"` sibling in place of `aria-live` on the whole `<ol>`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | **done**             |
 | EmptyState                   | static live-off default with explicit polite/assertive opt-in                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | **done** (PR 8)      |
 | AccessibleTable              | semantic caption, `MissingValue` cells, dense headers (clipped header keeps its full string as `title`) and the expander (now the registered `Button`, off the local ring-focus recipe) landed; content-role widths remain                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | PR 6/PR 12 remainder |
-| ui-primitives.tsx            | 698-line module mixing recipes/actions/feedback/clinical — split. Re-measured 2026-08-12: **157** production files import it (202 including mockups), against the 54 registered components' **31** with product imports; this module, not the registry, is what the product actually runs on. Per-primitive breakdown added 2026-08-21: `Button` **12** importers against 157, with **112** production files still holding a raw `<button>`; `Sheet` **26** — the one genuinely adopted primitive. The split is not uniform, and the pattern explains it: `Sheet` owns focus trap, portal and overlay stacking, which a className cannot fake, while `Button`/`Chip`/field shells own visual convention a recipe string approximates. Deciding between "give `Button` behaviour worth importing" and "promote `ui-primitives` to the documented layer" is the actual PR 12 question | PR 12                |
+| ui-primitives.tsx            | 698-line module mixing recipes/actions/feedback/clinical — split. Re-measured 2026-08-12: **157** production files import it (202 including mockups), against the 55 registered components' **31** with product imports; this module, not the registry, is what the product actually runs on. Per-primitive breakdown added 2026-08-21: `Button` **12** importers against 157, with **112** production files still holding a raw `<button>`; `Sheet` **26** — the one genuinely adopted primitive. The split is not uniform, and the pattern explains it: `Sheet` owns focus trap, portal and overlay stacking, which a className cannot fake, while `Button`/`Chip`/field shells own visual convention a recipe string approximates. Deciding between "give `Button` behaviour worth importing" and "promote `ui-primitives` to the documented layer" is the actual PR 12 question | PR 12                |
 
 ---
 
diff --git a/docs/design-system/FIX-GUIDE.md b/docs/design-system/FIX-GUIDE.md
new file mode 100644
index 0000000000..a92f9e7ff9
--- /dev/null
+++ b/docs/design-system/FIX-GUIDE.md
@@ -0,0 +1,94 @@
+# Clinical KB design system — Hazard 1–2 fix guide
+
+Single appendix for the closed Hazard 1–2 sweep. **Rules and roles stay in SPEC / TOKENS /
+GATES; this file only records dispositions.** A Documented row is not a licence to change
+product UI, `globals.css`, or `ckb-v2-tokens.css`.
+
+- **Date:** 27 August 2026
+- **Companions:** [README.md](README.md) · [TOKENS.md](TOKENS.md) · [GATES.md](GATES.md) ·
+  [COMPONENTS.md](COMPONENTS.md) · [`docs/design-system-contract.md`](../design-system-contract.md) ·
+  [`docs/design-system.md`](../design-system.md) (live-layer Geist notes)
+
+Statuses: **Fixed** (code in this sweep) · **Documented** (intentional or already true; no
+product change) · **Deferred** (later, named successor) · **Out-of-scope** (explicitly not
+this sweep).
+
+Do not invent token values here. Do not snap Geist interpolations to 600/700. Do not copy
+mockup `min-h-11` or `--text-soft` body into production.
+
+---
+
+## Batch A — code this sweep
+
+Agents 1–3 land these. Parent verifies after merge; do not treat this table as a second
+measurement of `globals.css` / `ckb-v2-tokens.css`.
+
+| ID | Status | Rationale |
+| ---- | ---------- | --------- |
+| DS-P1-16 | Fixed | Therapy-compass decorative `size={15}` maps to `size-icon-sm` (14px); Lucide `size` prop removed so SVG attrs cannot override the class. |
+| DS-P2-03 | Fixed | Unused `--text-{xs,sm,body,md,lg,xl}-lh` / `-tr` companions deleted; keep `--text-hero--line-height` and `--text-hero-tr`. Do not re-require per-step orphans. |
+| DS-P2-07 | Fixed | Two `1px` shadow-spread layers dropped in `globals.css` (compare FAB already has a border; disabled send uses a border, not inset+border). |
+| DS-P2-12 | Fixed | Three raw `line-height` literals in `globals.css` map to existing named tokens (`--text-hero--line-height`, `--leading-prose`). Not `--leading-tight`. |
+| DS-P2-13 | Fixed | Specifier surfaces that already own the edge with `border` lose `shadow-inset`. True wells, segmented tracks, field-controls, and Ward stay. |
+| DS-P2-17 | Fixed | `differential-detail-page` uses `resolveScrollBehavior()`; `settings-dialog` already branches on reduce-motion and is left alone. |
+| DS-P2-25 | Fixed | `#0f766e` medication accent defaults stay data, not `--clinical-accent`. Scoped `RAW_COLOR_EXEMPTIONS` entry; `rawColorLiterals` 2→0. See below. |
+
+---
+
+## Batch B — docs dispositions
+
+| ID | Status | Rationale |
+| ---- | ---------- | --------- |
+| DS-P2-04 | Documented | Intentional Geist variable interpolation. Already explained in [`docs/design-system.md`](../design-system.md) (intermediate weights; do **not** snap to 600/700). |
+| DS-P2-22 | Documented | `SectionHeading` exists (`src/components/ui/section-heading.tsx`); 14 production call sites. No opportunistic migration this sweep. |
+| DS-P2-23 | Documented | `AnswerCard` `frame?: "raised" \| "bare"` — both valid. Production answer surface uses **bare**. Future visual baselines must include both. Do not commit screenshots. |
+| DS-P2-27 | Documented | 15-mode load: recommend first-run / Tools prominence later. No IA redesign this sweep. |
+| DS-P2-28 | Documented | Settings **Motion** already has a per-control description. **Recent searches on home** does not — docs recommendation only; no extra intro copy in product this sweep. |
+| DS-P2-29 | Deferred | Phone document-viewer density waits on the tap-floor (Hazard ≥3). |
+| DS-P2-30 | Documented | Toast primitive exists; there is no **universal network-error** toast. Do not build toast infra here. `OverlayRoot` remains the overlay owner. |
+| DS-P2-31 | Documented | Already in TOKENS §4 / SPEC §3: add `--kind-*` **with the first call site**. No values in this sweep. |
+| DS-P2-32 | Documented | `--text-placeholder` is **live** (globals + v2 + `placeholder:` consumers), not planned. TOKENS §5 corrected. No further role migration. |
+| DS-P2-33 | Documented | Contract `textSoftConsumers=0` in production. Keep the `--text-soft` alias until zero `var(--text-soft)` remain **including mockups**. Do not rename; do not delete this sweep. |
+| DS-P3-01 | Deferred | PR-9 plan. `--shadow-focus` and dead springs are already gone. `--shadow-lift` still has live `mode-nav` and `document-search-results` consumers — do **not** delete it. |
+| DS-P3-02 | Documented | TOKENS already: `--tone-*` frozen, not deleted. |
+| DS-P3-03 | Documented | TOKENS already: design-side `--quantity-unit-scale` never lands. |
+| DS-P3-04 | Documented | TOKENS already: ConfidenceMeter deferred; no token without a call site. |
+| DS-P3-05 | Documented | Registry has **55** registered visual exports. `DocumentFrame` is built shell-only and still unregistered. Register when print primitives ship (PR 11). Docs elsewhere may still say 53/54. |
+| DS-P3-07 | Documented | Full visual state matrix grows incrementally with new adoptions. |
+| DS-P3-08 | Documented | QA checklist: inspect the filter band at 414–430px. No code this sweep. |
+| DS-P3-09 | Documented | `#TYZK23` PWA install CLS already fixed (PR #2253). Regression-check note only; no speculative CSS. |
+| DS-P3-10 | Documented | Mockup `min-h-11` and `--text-soft` body must not leak into production. |
+
+---
+
+## Medication accent literals (DS-P2-25)
+
+The two remaining production raw-colour hits are `#0f766e` defaults in
+`src/lib/medications.ts` and `src/lib/medication-records.ts`. They restate a Postgres column
+default (`accent text not null default '#0f766e'`) for a per-record, user-chosen colour.
+SPEC already records this as **data, not a token**.
+
+Do **not** map them to `--clinical-accent` (that role is `--primary-500` and would recolour
+medication records). The contract exemption is **scoped to those accent defaults**, not a
+whole-file blank cheque on either module. Enumerated in `RAW_COLOR_EXEMPTIONS` in
+`scripts/design-system-contract-utils.mjs`; described for operators in
+[`docs/design-system-contract.md`](../design-system-contract.md).
+
+---
+
+## Out of scope this sweep (do not implement)
+
+P0/P1 tap-floor · Button / PageHeader / v2 full adoption · Ward family · type-step
+retirement · toast infrastructure · `--kind-*` values · `--text-soft` global rename ·
+deleting live `--shadow-lift` · ConfidenceMeter · `DocumentFrame` registry · screenshot
+capture · `npm run ensure` unless a visual defect is proven.
+
+---
+
+## Residual risk (unchanged by docs)
+
+- Remaining production `border` + `inset` outside the specifier surfaces edited in DS-P2-13.
+- Lucide `size={15}` was ungated (`check:icon-scale` only bans `*-4.5`).
+- `--shadow-lift` still live (`mode-nav`, `document-search-results`).
+- Mockup `--text-soft` still blocks alias deletion.
+- Mockup `min-h-11` must stay mockup-only.
diff --git a/docs/design-system/GATES.md b/docs/design-system/GATES.md
index d34a01913b..eeaa9a030f 100644
--- a/docs/design-system/GATES.md
+++ b/docs/design-system/GATES.md
@@ -19,7 +19,7 @@ than CI, two of them by the second reader; review does not scale past two carefu
 | Check                                                                                                                                                       | What it enforces                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Label                                |
 | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
 | `npm run check:design-system-contract` (token baseline + adoption + design-sync contracts)                                                                  | Raw colour literals (ratchet against `design-system-contract-baseline.json`), literal `shadow-[…]` classes, the legacy tap class, interactive tap-size literals, therapy-compass `tc-btn` base-class use; border+ring edge conflicts, 1px shadow spreads, layout-property transitions and legacy shadow aliases (all ratcheted **per path**, so new use fails anywhere); status-coloured numerals and colour-only status indicators; raw padding, radius, gap and line-height literals in both classes and CSS declarations (ratcheted **per path**; named utilities and Tailwind arbitrary-property forms such as `[padding:22px]` both count; values computed with `var()`/`env()`/`calc()`/`clamp()`/`max()`, zero with any CSS unit identifier, and the CSS-wide keywords are exempt); declared-but-unselected type steps (**hard rule** with a gated exemption list); `dark:` colour overrides, legacy palette utilities and image-inversion filters (all pinned at **zero**, not ratcheted); deterministic adoption truth; local source/export/preview/design-sync parity. Mockups exempt. | implemented-blocking                 |
-| `tests/ckb-v2-token-contract.test.ts`                                                                                                                       | v2 layer stays class-scoped (no `:root` leak) · `--border-lux` solid and no lighter than `--border`, both themes · dark surface ramp monotonic and separated · `--surface-subtle` aliases up · text/muted/heading ≥4.5:1 on the light shell, muted ≥4.5:1 dark · `--text-soft` pinned **below** 4.5:1 and ≥3:1 (both sides, so the tier cannot be "fixed" away) · command pair ≥4.5:1 both themes · `--shadow-inset` true inset · elevation ladder carries no baked 1px hairline · tap floor ≠ chip height ≠ compact row · reduced-motion zeroes durations · every type step has its own line-height and tracking                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | implemented-blocking                 |
+| `tests/ckb-v2-token-contract.test.ts`                                                                                                                       | v2 layer stays class-scoped (no `:root` leak) · `--border-lux` solid and no lighter than `--border`, both themes · dark surface ramp monotonic and separated · `--surface-subtle` aliases up · text/muted/heading ≥4.5:1 on the light shell, muted ≥4.5:1 dark · `--text-soft` pinned **below** 4.5:1 and ≥3:1 (both sides, so the tier cannot be "fixed" away) · command pair ≥4.5:1 both themes · `--shadow-inset` true inset · elevation ladder carries no baked 1px hairline · tap floor ≠ chip height ≠ compact row · reduced-motion zeroes durations · type-scale pins `--leading-prose` plus `--text-hero--line-height` / `--text-hero-tr` (no per-step `-lh`/`-tr` orphans)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | implemented-blocking                 |
 | `tests/design-token-contract.test.ts`                                                                                                                       | Live-layer token relationships (companion to the v2 contract)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | implemented-blocking                 |
 | `tests/source-badges-off-vocab.dom.test.tsx`                                                                                                                | Enum resilience: off-vocabulary `clinical_validation_status` degrades to the neutral triad, logs once, never throws                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | implemented-blocking                 |
 | `tests/source-metadata-browser-safety.test.ts`                                                                                                              | The `process is not defined` client-bundle crash stays fixed (server logger never ships to the browser)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | implemented-blocking                 |
@@ -79,18 +79,18 @@ because it contributed nothing.
 | 5   | Tables: semantic caption, associated headers, `aria-controls` on the expander                                                                 | **implemented-blocking**             | `AccessibleTableProps.caption` is required; DOM and alignment tests prove the semantic `<caption>`, associated headers, and expander relationship.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | 6   | Enum resilience — neutral fallback, never throws                                                                                              | **implemented-blocking**             | `source-badges-off-vocab.dom.test.tsx`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | 7   | Elevation monotonicity — no child heavier than its parent                                                                                     | **implemented-partial**              | Token-ramp monotonicity is tested; the per-surface child/parent rule is planned (needs a render-tree check).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| 8   | Edge ownership — no `border-*` + `ring-*` on one surface; no 1px spread in a drop shadow                                                      | **implemented-partial**              | Corrected 9 Aug 2026: the previous evidence — "the per-surface co-occurrence lint and spread-term check are planned (PR 9)" — was **false**, and had been since before this row was written. Both ship. `edgeOwnershipConflicts` is an AST co-occurrence check over resolved class roots (`BORDER_WIDTH_UTILITY` × `RING_WIDTH_UTILITY`), and `onePixelShadowSpreads` reads the fourth length of every `box-shadow` layer. Both ratchet **per path**, so a new conflict on any surface fails today. What is partial is the recorded debt, not the check: **18 conflicts across 9 files**, and 2 spreads in `globals.css`. (Corrected 15 Aug 2026 — this cell said 27 across 15, which PR #1942 had already paid down to 25 across 12 without updating the prose. The §3 row below and `scripts/design-system-contract-baseline.json` both already said 25, and per `docs/design-system/README.md` the baseline outranks this document, so the prose was the defect. Ledger `#265` carried the same stale figure.) Path to blocking: retire that debt and pin both at zero. The spread form was chosen _because_ it is mechanically lintable, and it duly was.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| 8   | Edge ownership — no `border-*` + `ring-*` on one surface; no 1px spread in a drop shadow                                                      | **implemented-partial**              | Corrected 9 Aug 2026: the previous evidence — "the per-surface co-occurrence lint and spread-term check are planned (PR 9)" — was **false**, and had been since before this row was written. Both ship. `edgeOwnershipConflicts` is an AST co-occurrence check over resolved class roots (`BORDER_WIDTH_UTILITY` × `RING_WIDTH_UTILITY`), and `onePixelShadowSpreads` reads the fourth length of every `box-shadow` layer. Both ratchet **per path**, so a new conflict on any surface fails today. What is partial is the recorded debt, not the check: **18 conflicts across 9 files**, and 0 spreads in `globals.css`. (Corrected 15 Aug 2026 — this cell said 27 across 15, which PR #1942 had already paid down to 25 across 12 without updating the prose. The §3 row below and `scripts/design-system-contract-baseline.json` both already said 25, and per `docs/design-system/README.md` the baseline outranks this document, so the prose was the defect. Ledger `#265` carried the same stale figure.) Path to blocking: retire that debt and pin both at zero. The spread form was chosen _because_ it is mechanically lintable, and it duly was.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | 9   | No layout-property animation; no hardcoded durations                                                                                          | **implemented-partial**              | Corrected 9 Aug 2026: "a layout-property lint is still planned" was **false**, and leaving it would have preserved the exact contradiction this pass exists to remove. `layoutTransitionExceptions` ships and ratchets **per path** against `SAFE_TRANSITION_PROPERTIES`, so a new layout-property transition in any file fails today; the phone chrome's intentional `grid-template-rows` / `height` / `padding-bottom` are among the 11 recorded exceptions rather than a gap. The Tailwind duration form is a **hard zero** (`hardcodedMotionClasses`), on top of PR-Arch tokenising production `duration-*`/`ease-*` literals onto `--duration-*` / `--ease-*` (Gate 10). What stays partial is recorded debt, not a missing check: 11 layout transitions and 41 CSS `hardcodedCssMotionDurations`. Path to blocking: retire those and pin both at zero.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | 10  | Named z and motion tokens have real consumers; no unapproved `z-` value                                                                       | **implemented-blocking**             | PR-Arch: off-ladder `z-50` retired; toast at `--z-toast` (`z-[110]`, lint allowlist); motion literals map to named duration/ease tokens including phone-chrome hide/reveal pair. Dead `OverlayProvider` deleted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | 11  | Published-type conformance — every `dtsPropsFor` entry exactly matches source props                                                           | **implemented-blocking**             | `generate-design-sync-contract.mjs` uses the TypeScript checker to derive every public property from the exported source `*Props` type; `--check` and `check-design-sync-contract.mjs` reject drift, missing named types, or machine-specific declarations. Zero-prop visual roots are explicit.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| 12  | Publication coverage — every registered visual component has source, export, preview, prop contract and direct publication test               | **implemented-blocking**             | Registry/map/props parity and all 53 direct component rows are pinned by the design-sync contract and `design-sync-visual-exports.test.ts`. Behavioural, full visual-state, print, and browser acceptance remain separate gates; `DocumentFrame` is built shell-only in product but not yet among the 53 registered visual exports (print primitives remain specified-not-built).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| 12  | Publication coverage — every registered visual component has source, export, preview, prop contract and direct publication test               | **implemented-blocking**             | Registry/map/props parity and all 55 direct component rows are pinned by the design-sync contract and `design-sync-visual-exports.test.ts`. Behavioural, full visual-state, print, and browser acceptance remain separate gates; `DocumentFrame` is built shell-only in product but not yet among the 55 registered visual exports (print primitives remain specified-not-built).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 
 **Computed-style suites (planned, PR 1–2):** Tailwind conflict order · v2 cascade, ancestor
 **and** same-node forms · HCM remapping under all three v2 selectors · z-index · target
 geometry · contrast · print token reset. Class-string assertions are not accepted for any of
 these — computed values only.
 
-**Reference preview coverage is implemented-blocking for all 53 registered visual exports.**
+**Reference preview coverage is implemented-blocking for all 55 registered visual exports.**
 The full runtime visual state matrix remains planned: default · hover · active · focus-visible ·
 disabled · busy · invalid · long content · 320px · dark · forced colours · reduced motion ·
 print where relevant. 320px is blocking for newly adopted components; print stays manual per
@@ -111,10 +111,10 @@ theme-list parity, and remote design-project publication remain separate concern
 | Put `--decoration-soft`/`--text-soft` on a text node                 | Tier pinned both sides in the token contract; recipe AST (`decoration-on-text.contract.test.ts`)                                                                   | implemented-blocking (recipes); broader AST follow-on                                                                                                                                                                                                                                                                                                      |
 | Uppercase a dose unit                                                | `Quantity` pins `normal-case` + unit test                                                                                                                          | implemented-blocking (branch)                                                                                                                                                                                                                                                                                                                              |
 | Invert a PDF, diagram or clinical image in any theme                 | `check:design-system-contract` — `imageInversions`, pinned at **zero**, not ratcheted                                                                              | **implemented-blocking** (9 Aug 2026) — CSS `filter`/`backdrop-filter` plus the Tailwind `invert`/`hue-rotate` utilities; see §5                                                                                                                                                                                                                           |
-| Border **and** ring on one surface, or a 1px spread in a drop shadow | `check:design-system-contract` — `edgeOwnershipConflicts` (18) + `onePixelShadowSpreads` (2)                                                                       | **implemented-blocking for new use** — AST/CSS ratchets with per-path pins; the recorded debt itself is Gate 8's remaining half                                                                                                                                                                                                                            |
+| Border **and** ring on one surface, or a 1px spread in a drop shadow | `check:design-system-contract` — `edgeOwnershipConflicts` (18) + `onePixelShadowSpreads` (0)                                                                       | **implemented-blocking for new use** — AST/CSS ratchets with per-path pins; the recorded debt itself is Gate 8's remaining half                                                                                                                                                                                                                            |
 | A child shadow heavier than its parent's                             | Gate 7                                                                                                                                                             | implemented-partial                                                                                                                                                                                                                                                                                                                                        |
 | Use `--shadow-tight`/any alias in new code                           | `check:design-system-contract` — `legacyShadowAliases`, ratcheted at 89 with per-path pins                                                                         | **implemented-blocking for new use** — a new alias in any file fails. `--shadow-tight` itself is retired onto `--e1` and additionally pinned by a tracked-tree sweep in `tests/design-token-contract.test.ts` (it was silently reverted once by the `acf78bf` merge); the remaining 89 are the other six aliases, still `#262`                             |
-| Raw pixel size, padding, radius, gap or line-height in markup        | `check:design-system-contract` — `rawPaddingLiterals` (52), `rawRadiusLiterals` (20), `rawGapLiterals` (25), `rawMarginLiterals` (74), `rawLineHeightLiterals` (3) | **implemented-blocking for new use** (9 Aug 2026) — per-path ratchets over both the utility and the CSS-declaration spelling, so a literal cannot move into `globals.css` to escape. Values containing a CSS function (`env(`, `clamp(`, `max(`, `calc(`) are sanctioned computed forms and exempt. Raw _size_ is still covered only for tap/shadow/colour |
+| Raw pixel size, padding, radius, gap or line-height in markup        | `check:design-system-contract` — `rawPaddingLiterals` (52), `rawRadiusLiterals` (20), `rawGapLiterals` (25), `rawMarginLiterals` (74), `rawLineHeightLiterals` (0) | **implemented-blocking for new use** (9 Aug 2026) — per-path ratchets over both the utility and the CSS-declaration spelling, so a literal cannot move into `globals.css` to escape. Values containing a CSS function (`env(`, `clamp(`, `max(`, `calc(`) are sanctioned computed forms and exempt. Raw _size_ is still covered only for tap/shadow/colour |
 | Animate `width`, `height`, `grid-template-*`, `top`, `left`, `gap`   | `check:design-system-contract` — `layoutTransitionExceptions`, ratcheted at 11 with per-path pins                                                                  | **implemented-blocking for new use** — `SAFE_TRANSITION_PROPERTIES` carries the compositor-only allowlist; phone chrome's deliberate `grid-template-rows` is in the recorded 11                                                                                                                                                                            |
 | Hardcode a transition duration                                       | `check:design-system-contract` — `hardcodedMotionClasses` (**zero**) + `hardcodedCssMotionDurations` (41)                                                          | **implemented-blocking** for the Tailwind `duration-*`/`delay-*`/`transition-all` form; the CSS form is a ratchet, so its 41 are debt                                                                                                                                                                                                                      |
 | A `z-[N]` literal outside the named rungs, in JS/TS only             | `require-z-index-ladder` (ESLint)                                                                                                                                  | implemented-blocking. Scope: `z-[N]` literals in JS/TS AST nodes. Plain `z-30` utilities and every `.css` / `.module.css` declaration are invisible to an ESLint rule - `sidebar-live-shell.module.css` carries an off-ladder `z-index: var(--z-sidebar-flyout, 50)` this cannot see.                                                                      |
diff --git a/docs/design-system/README.md b/docs/design-system/README.md
index 98140c8b97..701a879c38 100644
--- a/docs/design-system/README.md
+++ b/docs/design-system/README.md
@@ -28,6 +28,7 @@ Reading order:
    assumptions, and the resolution log.
 5. [GATES.md](GATES.md) — every rule paired with its enforcement status. A prohibition
    with no row there is a suggestion.
+6. [FIX-GUIDE.md](FIX-GUIDE.md) — Hazard 1–2 sweep dispositions (Fixed / Documented / Deferred / Out-of-scope).
 
 Canonical code: `src/app/ckb-v2-tokens.css` is the **v2 target layer** and `globals.css` remains
 the compatibility layer. The source now mounts `.ckb-v2` literally on the global `<html>`, so every
diff --git a/docs/design-system/TOKENS.md b/docs/design-system/TOKENS.md
index ceafcf9cf6..f9a19fb5d2 100644
--- a/docs/design-system/TOKENS.md
+++ b/docs/design-system/TOKENS.md
@@ -47,7 +47,7 @@ Declared in the `.ckb-v2` structural block **[verified: full read at `ef13a072a`
 | Semantic gaps    | `--gap-tight` · `--gap-inline` · `--gap-stack` · `--gap-block` · `--gap-section`                                                          | The only inter-element spacing markup may use.                                                                                                                                                                                                                                               |
 | Semantic padding | `--pad-chip-x` · `--pad-control-x` · `--pad-cta-x` · `--pad-card` · `--pad-panel` · `--pad-strip`                                         | Heading-inset convention rides on these (SPEC §4.6).                                                                                                                                                                                                                                         |
 | Page             | `--page-gutter` · `--page-max` · `--measure` · `--header-h`                                                                               | `--measure` is the prose measure — never wider.                                                                                                                                                                                                                                              |
-| Type steps       | `--text-{xs,sm,body,md,lg,xl}` each with `-lh` and `-tr` · `--text-hero` · `--text-hero--line-height` · `--text-hero-tr`                  | Seven steps, per-step line-height and tracking (gated). ⚠️ `--text-hero--line-height` is the one double-dash name — keep as-is; renaming is churn without a defect.                                                                                                                          |
+| Type steps       | `--text-{xs,sm,body,md,lg,xl}` · `--text-hero` · `--text-hero--line-height` · `--text-hero-tr`                                             | Seven steps. Shared `--leading-prose`; hero keeps `--text-hero--line-height` / `--text-hero-tr` (gated). Unused xs–xl `-lh`/`-tr` companions are orphans — do not re-require them. ⚠️ `--text-hero--line-height` is the one double-dash name — keep as-is; renaming is churn without a defect. |
 | Chip sizes       | `Chip` `compact` → `--text-2xs` (legacy compat step); `standard` (default) → `--text-xs`                                                  | Canonical (#220): dense surfaces opt into `size="compact"`; default adoption keeps `--text-xs`. `--text-2xs` stays a compatibility alias for Chip compact / legacy call sites — not a new v2 type step to invent against. Do not densify every Chip to chase the globals “small chips” note. |
 | Type companions  | `--leading-prose` · `--tracking-eyebrow` · `--nums`                                                                                       | `--nums` = numeric variant for all data.                                                                                                                                                                                                                                                     |
 | Weights          | `--font-weight-{body,label,heading,value}`                                                                                                | One job each; display uses heading weight (SPEC §4.6).                                                                                                                                                                                                                                       |
@@ -105,7 +105,7 @@ The v2 layer _references_ or _depends on_ these; their values stay in `live` / `
 | `--success`, `--info`                                   | `live`           | Clinical/status palette — reserved channel.                                                                                 |
 | `--focus`                                               | `live`           | The only focus outline colour; no companion ring, ever.                                                                     |
 | `--ring-highlight`, `--ring-glass`                      | `live`           | Highlight rings on lux surfaces; each carries its own per-theme value, so `dark:ring-*` is gated at zero (GATES §3).        |
-| `--text-placeholder`                                    | `planned` (PR 3) | New role ≥4.5:1; until it exists, placeholders use `--text-muted`.                                                          |
+| `--text-placeholder`                                    | `live`           | Declared in globals and v2; ≥4.5:1 placeholder ink. Not planned. No further role migration this sweep.                      |
 
 ## 6 · Deprecations and deletions
 
@@ -173,5 +173,6 @@ Two consequences already observed and fixed elsewhere: 44px tap targets survived
 named `--z-*` ladder entirely.
 
 **To retire it**, map the spacing scale onto `--gap-*`/`--pad-*`, route `--ward-z-*` onto local
-stacking contexts using the named rungs, and adopt the per-step `--text-*-lh` companions in
-place of `--ward-leading-*`. Each is a visual change and wants its own review.
+stacking contexts using the named rungs, and adopt `--leading-prose` (hero line-height where
+display type applies) in place of `--ward-leading-*`. Each is a visual change and wants its own
+review. Do not reintroduce per-step `--text-*-lh` orphans.
diff --git a/scripts/design-system-contract-baseline.json b/scripts/design-system-contract-baseline.json
index 326282fc01..bd3d6e5e73 100644
--- a/scripts/design-system-contract-baseline.json
+++ b/scripts/design-system-contract-baseline.json
@@ -1,48 +1,44 @@
 {
   "metrics": {
-    "rawColorLiterals": 2,
+    "rawColorLiterals": 0,
     "literalShadowClasses": 0,
     "legacyTapClasses": 0,
-    "interactiveTapFloorDeclarations": 33,
+    "interactiveTapFloorDeclarations": 32,
     "colourOnlyStatusIndicators": 0,
     "statusColouredNumerals": 0,
-    "edgeOwnershipConflicts": 18,
-    "onePixelShadowSpreads": 2,
+    "edgeOwnershipConflicts": 16,
+    "onePixelShadowSpreads": 0,
     "hardcodedCssMotionDurations": 42,
     "rawCssZIndices": 8,
     "legacyPaletteUtilities": 0,
     "darkColorOverrides": 0,
-    "legacyShadowAliases": 89,
+    "legacyShadowAliases": 87,
     "arbitraryTracking": 0,
-    "rawPaddingLiterals": 58,
-    "rawRadiusLiterals": 24,
-    "rawGapLiterals": 28,
-    "rawMarginLiterals": 76,
-    "rawLineHeightLiterals": 3,
+    "rawPaddingLiterals": 42,
+    "rawRadiusLiterals": 20,
+    "rawGapLiterals": 20,
+    "rawMarginLiterals": 53,
+    "rawLineHeightLiterals": 0,
     "layoutTransitionExceptions": 11,
     "textSoftConsumers": 0,
     "errorStateCountProps": 0,
     "failedStateResultCounts": 0
   },
   "debtByPath": {
-    "rawColorLiterals": {
-      "src/lib/medication-records.ts": 1,
-      "src/lib/medications.ts": 1
-    },
+    "rawColorLiterals": {},
     "literalShadowClasses": {},
     "legacyTapClasses": {},
     "interactiveTapFloorDeclarations": {
-      "src/components/DocumentTagCloud.tsx": 2,
       "src/components/calculators/bedside-sheet.tsx": 3,
       "src/components/calculators/calculator-ui.tsx": 3,
       "src/components/calculators/clinical-console.tsx": 2,
       "src/components/calculators/directory-grid.tsx": 1,
-      "src/components/clinical-dashboard/DocumentManagerPanel.tsx": 6,
       "src/components/clinical-dashboard/answer-content.tsx": 1,
       "src/components/clinical-dashboard/document-admin.tsx": 5,
-      "src/components/clinical-dashboard/favourites-command-library-page.tsx": 1,
+      "src/components/clinical-dashboard/DocumentManagerPanel.tsx": 6,
       "src/components/clinical-dashboard/favourites-hub.tsx": 2,
       "src/components/clinical-dashboard/settings-dialog.tsx": 3,
+      "src/components/DocumentTagCloud.tsx": 2,
       "src/components/forms/form-detail-page.tsx": 1,
       "src/components/forms/forms-search-results-page.tsx": 2,
       "src/components/ui/chip.tsx": 1
@@ -50,19 +46,15 @@
     "colourOnlyStatusIndicators": {},
     "statusColouredNumerals": {},
     "edgeOwnershipConflicts": {
-      "src/components/DocumentTagCloud.tsx": 3,
       "src/components/clinical-dashboard/dashboard-nav.tsx": 1,
       "src/components/clinical-dashboard/favourites-command-library-page.tsx": 1,
       "src/components/clinical-dashboard/master-search-header.tsx": 5,
+      "src/components/DocumentTagCloud.tsx": 3,
       "src/components/formulation/formulation-builder-page.tsx": 3,
-      "src/components/formulation/formulation-compare-page.tsx": 1,
       "src/components/specifiers/specifier-builder-page.tsx": 1,
-      "src/components/specifiers/specifier-compare-page.tsx": 1,
       "src/components/ui-primitives.tsx": 2
     },
-    "onePixelShadowSpreads": {
-      "src/app/globals.css": 2
-    },
+    "onePixelShadowSpreads": {},
     "hardcodedCssMotionDurations": {
       "src/app/globals.css": 42
     },
@@ -75,7 +67,6 @@
       "src/app/globals.css": 1,
       "src/app/layout.tsx": 1,
       "src/app/not-found.tsx": 1,
-      "src/components/DocumentViewer.tsx": 1,
       "src/components/applications-launcher-page.tsx": 1,
       "src/components/calculators/bedside-sheet.tsx": 1,
       "src/components/calculators/calculator-sheet.tsx": 1,
@@ -83,8 +74,8 @@
       "src/components/calculators/guided-flow.tsx": 3,
       "src/components/calculators/search-detail.tsx": 8,
       "src/components/calculators/search-page.tsx": 2,
-      "src/components/clinical-dashboard/ClinicalSidebar.tsx": 2,
       "src/components/clinical-dashboard/auth-panel.tsx": 1,
+      "src/components/clinical-dashboard/ClinicalSidebar.tsx": 2,
       "src/components/clinical-dashboard/dashboard-nav.tsx": 2,
       "src/components/clinical-dashboard/differentials-home.tsx": 2,
       "src/components/clinical-dashboard/document-search-results.tsx": 4,
@@ -95,13 +86,14 @@
       "src/components/clinical-dashboard/medication-prescribing-workspace.tsx": 1,
       "src/components/clinical-dashboard/medication-record-page.tsx": 2,
       "src/components/clinical-dashboard/mode-action-popup.tsx": 2,
-      "src/components/clinical-dashboard/settings-dialog.tsx": 3,
+      "src/components/clinical-dashboard/settings-dialog.tsx": 2,
       "src/components/clinical-dashboard/source-preview-popover.tsx": 1,
       "src/components/clinical-dashboard/universal-search-command-surface.tsx": 1,
       "src/components/differentials/diagnosis-map-panel.tsx": 4,
       "src/components/differentials/differential-detail-page.tsx": 2,
       "src/components/differentials/differential-presentation-actions.tsx": 1,
       "src/components/differentials/differential-presentation-workflow-page.tsx": 2,
+      "src/components/DocumentViewer.tsx": 1,
       "src/components/dsm/dsm-comparison-page.tsx": 1,
       "src/components/dsm/dsm-diagnosis-page.tsx": 1,
       "src/components/dsm/dsm-differential-considerations-page.tsx": 2,
@@ -117,7 +109,7 @@
       "src/components/specifiers/specifier-map-page.tsx": 1,
       "src/components/specifiers/specifier-ui.tsx": 1,
       "src/components/specifiers/specifiers-home-page.tsx": 1,
-      "src/components/therapy-compass/screens/compare-screen.tsx": 2,
+      "src/components/therapy-compass/screens/compare-screen.tsx": 1,
       "src/components/therapy-compass/screens/sheets-screen.tsx": 1,
       "src/components/ui/answer-card.tsx": 1,
       "src/components/ui/button.tsx": 1,
@@ -128,52 +120,44 @@
     },
     "arbitraryTracking": {},
     "rawPaddingLiterals": {
-      "src/app/globals.css": 23,
+      "src/app/globals.css": 18,
       "src/components/clinical-dashboard/result-filter-control.tsx": 1,
       "src/components/clinical-record-panels.tsx": 2,
       "src/components/differentials/differential-detail-page.tsx": 1,
       "src/components/therapy-compass/screens/brief-screen.tsx": 6,
-      "src/components/therapy-compass/screens/compare-screen.tsx": 4,
-      "src/components/therapy-compass/screens/detail-screen.tsx": 5,
+      "src/components/therapy-compass/screens/compare-screen.tsx": 3,
       "src/components/therapy-compass/screens/pathways-screen.tsx": 4,
-      "src/components/therapy-compass/screens/recommend-screen.tsx": 5,
       "src/components/therapy-compass/screens/sheets-screen.tsx": 7
     },
     "rawRadiusLiterals": {
-      "src/app/globals.css": 22,
+      "src/app/globals.css": 18,
       "src/components/clinical-dashboard/search-results-header-band.tsx": 1,
       "src/components/mode-nav/mode-nav.tsx": 1
     },
     "rawGapLiterals": {
-      "src/app/globals.css": 14,
+      "src/app/globals.css": 11,
       "src/components/therapy-compass/screens/brief-screen.tsx": 4,
       "src/components/therapy-compass/screens/compare-screen.tsx": 1,
-      "src/components/therapy-compass/screens/detail-screen.tsx": 3,
       "src/components/therapy-compass/screens/pathways-screen.tsx": 2,
-      "src/components/therapy-compass/screens/recommend-screen.tsx": 2,
       "src/components/therapy-compass/screens/sheets-screen.tsx": 2
     },
     "rawMarginLiterals": {
-      "src/app/globals.css": 8,
+      "src/app/globals.css": 6,
       "src/components/clinical-dashboard/medication-prescribing-workspace.tsx": 1,
       "src/components/document-viewer/document-rail-panels.tsx": 1,
       "src/components/document-viewer/source-panels.tsx": 2,
       "src/components/sidebar-live-shell.module.css": 2,
       "src/components/therapy-compass/screens/brief-screen.tsx": 3,
-      "src/components/therapy-compass/screens/compare-screen.tsx": 3,
-      "src/components/therapy-compass/screens/detail-screen.tsx": 3,
+      "src/components/therapy-compass/screens/compare-screen.tsx": 2,
       "src/components/therapy-compass/screens/other-screen.tsx": 1,
       "src/components/therapy-compass/screens/pathways-screen.tsx": 1,
-      "src/components/therapy-compass/screens/recommend-screen.tsx": 8,
       "src/components/therapy-compass/screens/sheets-screen.tsx": 6,
       "src/components/therapy-compass/workspace.tsx": 1,
       "src/components/ui/retrieval-state-banner.tsx": 1,
-      "src/components/ward-management/ward-management-modes.module.css": 16,
-      "src/components/ward-management/ward-management.module.css": 19
-    },
-    "rawLineHeightLiterals": {
-      "src/app/globals.css": 3
+      "src/components/ward-management/ward-management-modes.module.css": 15,
+      "src/components/ward-management/ward-management.module.css": 11
     },
+    "rawLineHeightLiterals": {},
     "layoutTransitionExceptions": {
       "src/app/globals.css": 4,
       "src/components/calculators/guided-flow.tsx": 1,
diff --git a/scripts/design-system-contract-utils.mjs b/scripts/design-system-contract-utils.mjs
index 3a96108f5c..9dda570432 100644
--- a/scripts/design-system-contract-utils.mjs
+++ b/scripts/design-system-contract-utils.mjs
@@ -50,6 +50,15 @@ export const RAW_COLOR_EXEMPTIONS = [
     pattern: /^src\/components\/factsheets\/factsheet-detail-page\.tsx$/,
     scope: "factsheet-print-sheet",
   },
+  {
+    // Medication record accent fallback `#0f766e` is a stored-record default,
+    // not `--clinical-accent` (`#1d6fb8` / `--primary-500`). Mapping it would
+    // recolour live medication tiles. Scoped to the `accent:` default only —
+    // any other raw colour in these files stays countable.
+    category: "medication accent default",
+    pattern: /^src\/lib\/(?:medication-records|medications)\.ts$/,
+    scope: "medication-accent-default",
+  },
 ];
 
 export function hasLegacyTapClass(classText) {
@@ -1835,6 +1844,19 @@ function namedFunctionRange(relativePath, source, functionName) {
   return declaration ? { start: declaration.getFullStart(), end: declaration.end } : null;
 }
 
+function medicationAccentDefaultRanges(source) {
+  // Only the `accent:` property default (`??` / `||` / direct) of `#0f766e`.
+  // `accentColor`, comments, and any other teal literal stay visible.
+  const pattern = /(?<![A-Za-z0-9_$])accent(?![A-Za-z0-9_$])\s*:\s*(?:[^,;{}\n]*?(?:\?\?|\|\|)\s*)?(["'`])#0f766e\1/g;
+  const ranges = [];
+  for (const match of source.matchAll(pattern)) {
+    if (isInsideCommentOrString(source, match.index)) continue;
+    const hexStart = match.index + match[0].lastIndexOf("#0f766e");
+    ranges.push({ start: hexStart, end: hexStart + "#0f766e".length });
+  }
+  return ranges;
+}
+
 export function rawColorContractSource(relativePath, source, reportFailure = () => {}) {
   const exemption = RAW_COLOR_EXEMPTIONS.find(({ pattern }) => pattern.test(relativePath));
   if (!exemption) return source;
@@ -1860,6 +1882,15 @@ export function rawColorContractSource(relativePath, source, reportFailure = ()
     return maskRanges(source, [range]);
   }
 
+  if (exemption.scope === "medication-accent-default") {
+    const ranges = medicationAccentDefaultRanges(source);
+    if (ranges.length === 0) {
+      reportFailure("medication accent default boundary is missing");
+      return source;
+    }
+    return maskRanges(source, ranges);
+  }
+
   reportFailure(`unknown raw-color exemption scope for ${relativePath}`);
   return source;
 }
diff --git a/src/app/ckb-v2-tokens.css b/src/app/ckb-v2-tokens.css
index d00e7aeb5c..4b4f83ca8a 100644
--- a/src/app/ckb-v2-tokens.css
+++ b/src/app/ckb-v2-tokens.css
@@ -62,7 +62,9 @@
   --bp-tablet: 768px;
   --bp-desktop: 1024px;
 
-  /* Type - 7 steps, each with its own line-height and tracking.
+  /* Type - 7 size steps. xs–xl are size-only; shared leading is
+   * `--leading-prose`. Hero is the only step with dedicated companions
+   * (`--text-hero--line-height`, `--text-hero-tr`).
    *
    * TWO SCALES ARE LIVE AT ONCE, and this block is the one that wins. Because
    * `ckb-v2` is mounted on <html>, every step below overrides both Tailwind's
@@ -83,29 +85,14 @@
    *     --text-lg   1.25rem   = Tailwind default --text-xl
    *     --text-xl   1.5rem    = Tailwind default --text-2xl
    *
-   * The `-lh` / `-tr` companions below are declared but currently consumed by
-   * nothing (0 references across src/ as of 2026-08-21). They are the intended
-   * paired scale, not drift - but until a call site adopts them, only the size
-   * half of this scale is real. Do not read their presence as evidence that
-   * leading and tracking are already handled. */
+   * Do not reintroduce per-step `-lh` / `-tr` orphans for xs–xl. Wiring those
+   * would be type-scale adoption, not a companion-token restore. */
   --text-xs: 0.75rem;
-  --text-xs-lh: 1rem;
-  --text-xs-tr: 0;
   --text-sm: 0.8125rem;
-  --text-sm-lh: 1.125rem;
-  --text-sm-tr: 0;
   --text-body: 0.9375rem;
-  --text-body-lh: 1.375rem;
-  --text-body-tr: -0.005em;
   --text-md: 1.0625rem;
-  --text-md-lh: 1.75rem;
-  --text-md-tr: -0.008em;
   --text-lg: 1.25rem;
-  --text-lg-lh: 1.625rem;
-  --text-lg-tr: -0.012em;
   --text-xl: 1.5rem;
-  --text-xl-lh: 1.875rem;
-  --text-xl-tr: -0.018em;
   --text-hero: clamp(1.75rem, 1.2rem + 2vw, 2.25rem);
   --text-hero--line-height: 1.12;
   --text-hero-tr: -0.022em;
diff --git a/src/app/globals.css b/src/app/globals.css
index 86cc194718..8a05fe9424 100644
--- a/src/app/globals.css
+++ b/src/app/globals.css
@@ -1367,9 +1367,7 @@ summary::-webkit-details-marker {
   font-size: 0.95rem;
   font-weight: 900;
   letter-spacing: -0.01em;
-  box-shadow:
-    0 18px 42px rgb(0 0 0 / 24%),
-    0 0 0 1px color-mix(in srgb, var(--clinical-accent-contrast) 10%, transparent) inset;
+  box-shadow: 0 18px 42px rgb(0 0 0 / 24%);
   touch-action: manipulation;
   transition:
     transform 160ms var(--ease-spring),
@@ -2178,7 +2176,7 @@ summary::-webkit-details-marker {
   padding-inline: 0.35rem;
   font-size: 16px;
   font-weight: 560;
-  line-height: 1.2;
+  line-height: var(--text-hero--line-height);
   letter-spacing: 0;
 }
 
@@ -2226,7 +2224,8 @@ summary::-webkit-details-marker {
   opacity: 1;
   background: var(--surface-subtle);
   color: var(--disabled);
-  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--border-strong) 42%, transparent);
+  border: 1px solid color-mix(in srgb, var(--border-strong) 42%, transparent);
+  box-shadow: none;
 }
 
 .answer-footer-search-chip {
@@ -2545,7 +2544,7 @@ summary::-webkit-details-marker {
 .answer-suggestion-label-eyebrow {
   font-size: 0.625rem;
   letter-spacing: 0.06em;
-  line-height: 1rem;
+  line-height: var(--leading-prose);
   text-transform: uppercase;
 }
 
@@ -2597,7 +2596,7 @@ summary::-webkit-details-marker {
   color: var(--text-muted);
   font-size: 0.75rem;
   font-weight: 600;
-  line-height: 1.25rem;
+  line-height: var(--leading-prose);
   text-align: left;
   text-overflow: ellipsis;
   white-space: nowrap;
diff --git a/src/components/differentials/differential-detail-page.tsx b/src/components/differentials/differential-detail-page.tsx
index 14ce1b219d..ab4249c696 100644
--- a/src/components/differentials/differential-detail-page.tsx
+++ b/src/components/differentials/differential-detail-page.tsx
@@ -53,6 +53,7 @@ import {
   type DifferentialSafetyFact,
 } from "@/lib/differential-detail";
 import type { DifferentialRecord, DifferentialSection } from "@/lib/differentials";
+import { resolveScrollBehavior } from "@/lib/scroll-behavior";
 import { useAccountData } from "@/components/account-data-provider";
 
 const sectionIcons: Record<DifferentialSection["tone"], LucideIcon> = {
@@ -1060,8 +1061,7 @@ export function DifferentialDetailPage({
     ? () => {
         setSectionOpen("must-not-miss", true);
         const target = document.getElementById("differential-section-must-not-miss");
-        const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-        target?.scrollIntoView({ behavior: reduceMotion ? "auto" : "smooth", block: "start" });
+        target?.scrollIntoView({ behavior: resolveScrollBehavior(), block: "start" });
       }
     : null;
   const openCompareTab = () => changeTab("compare");
diff --git a/src/components/specifiers/specifier-builder-page.tsx b/src/components/specifiers/specifier-builder-page.tsx
index 19d341d370..7677e164a9 100644
--- a/src/components/specifiers/specifier-builder-page.tsx
+++ b/src/components/specifiers/specifier-builder-page.tsx
@@ -84,7 +84,7 @@ function StepProgress({
   return (
     <ol
       aria-label="Specifier builder steps"
-      className="grid grid-cols-4 gap-1 rounded-xl border border-[color:var(--border)] bg-[color:var(--surface-raised)] p-1.5 shadow-[var(--shadow-inset)]"
+      className="grid grid-cols-4 gap-1 rounded-xl border border-[color:var(--border)] bg-[color:var(--surface-raised)] p-1.5"
     >
       {builderSteps.map((step, index) => {
         const isActive = active === step.id;
@@ -283,7 +283,7 @@ export function SpecifierBuilderPage({ initialSpecifiers = [] }: { initialSpecif
                   <select
                     value={diagnosisId}
                     onChange={(event) => changeDiagnosis(event.target.value as SpecifierBuilderDiagnosis)}
-                    className="min-h-12 w-full max-w-full rounded-lg border border-[color:var(--border-strong)] bg-[color:var(--surface)] px-3 text-sm font-bold text-[color:var(--text-heading)] shadow-[var(--shadow-inset)] outline-none focus:border-[color:var(--focus)] focus:ring-4 focus:ring-[color:var(--focus)]/20"
+                    className="min-h-12 w-full max-w-full rounded-lg border border-[color:var(--border-strong)] bg-[color:var(--surface)] px-3 text-sm font-bold text-[color:var(--text-heading)] outline-none focus:border-[color:var(--focus)] focus:ring-4 focus:ring-[color:var(--focus)]/20"
                   >
                     {diagnosisPresets.map((item) => (
                       <option key={item.id} value={item.id}>
@@ -532,7 +532,7 @@ export function SpecifierBuilderPage({ initialSpecifiers = [] }: { initialSpecif
           ) : null}
 
           {activeView !== "review" ? (
-            <div className="mt-4 flex flex-wrap items-center justify-between gap-3 rounded-xl border border-[color:var(--border)] bg-[color:var(--surface)] p-3 shadow-[var(--shadow-inset)]">
+            <div className="mt-4 flex flex-wrap items-center justify-between gap-3 rounded-xl border border-[color:var(--border)] bg-[color:var(--surface)] p-3">
               <button
                 type="button"
                 onClick={() => move(-1)}
diff --git a/src/components/specifiers/specifier-ui.tsx b/src/components/specifiers/specifier-ui.tsx
index 50014f1e0b..090c99befd 100644
--- a/src/components/specifiers/specifier-ui.tsx
+++ b/src/components/specifiers/specifier-ui.tsx
@@ -39,7 +39,7 @@ export function SpecifierWordingPathway() {
     >
       {specifierWordingPathwaySteps.map((label, index) => (
         <div key={label} className="contents">
-          <div className="flex min-h-12 min-w-0 items-center gap-2 rounded-lg border border-[color:var(--border)] bg-[color:var(--surface)] px-3 text-sm font-extrabold text-[color:var(--text-heading)] shadow-[var(--shadow-inset)]">
+          <div className="flex min-h-12 min-w-0 items-center gap-2 rounded-lg border border-[color:var(--border)] bg-[color:var(--surface)] px-3 text-sm font-extrabold text-[color:var(--text-heading)]">
             <span className="nums grid h-7 w-7 shrink-0 place-items-center rounded-full bg-[color:var(--clinical-accent)] text-xs text-[color:var(--clinical-accent-contrast)]">
               {index + 1}
             </span>
@@ -70,7 +70,7 @@ export function SpecifierDiagnosisFilter({
     <label
       className={cn(
         // Content-sized control: wide enough for “All diagnoses” without becoming a full-width field.
-        "relative inline-flex min-h-tap w-auto max-w-full shrink-0 items-center gap-1.5 rounded-lg border border-[color:var(--border)] bg-[color:var(--surface)] py-1 pl-2.5 pr-7 text-xs font-bold shadow-[var(--shadow-inset)]",
+        "relative inline-flex min-h-tap w-auto max-w-full shrink-0 items-center gap-1.5 rounded-lg border border-[color:var(--border)] bg-[color:var(--surface)] py-1 pl-2.5 pr-7 text-xs font-bold",
         "focus-within:outline focus-within:outline-2 focus-within:outline-offset-2 focus-within:outline-[color:var(--focus)]",
       )}
     >
@@ -146,7 +146,7 @@ export function SpecifierMatchCard({ record, isTopMatch }: { record: SpecifierRe
 
             <div
               data-specifier-card-signal
-              className="rounded-lg border border-[color:var(--clinical-accent-border)] bg-[color:var(--clinical-accent-soft)]/55 p-3.5 shadow-[var(--shadow-inset)] sm:mt-0.5"
+              className="rounded-lg border border-[color:var(--clinical-accent-border)] bg-[color:var(--clinical-accent-soft)]/55 p-3.5 sm:mt-0.5"
             >
               <p className={eyebrowText}>Deciding signal</p>
               <p className="mt-1.5 text-sm font-semibold leading-5 text-[color:var(--text-heading)]">
diff --git a/src/components/therapy-compass/screens/brief-screen.tsx b/src/components/therapy-compass/screens/brief-screen.tsx
index 04d5e3cc0b..817a0f5fbd 100644
--- a/src/components/therapy-compass/screens/brief-screen.tsx
+++ b/src/components/therapy-compass/screens/brief-screen.tsx
@@ -162,12 +162,11 @@ export function BriefScreen() {
                         </span>
                         <TriangleAlert
                           aria-hidden="true"
-                          size={15}
                           strokeWidth={1.8}
                           className={
                             x.reviewStatus === "reviewed"
-                              ? "flex-none text-[color:var(--success-text)]"
-                              : "flex-none text-[color:var(--warning-text)]"
+                              ? "size-icon-sm flex-none text-[color:var(--success-text)]"
+                              : "size-icon-sm flex-none text-[color:var(--warning-text)]"
                           }
                         />
                       </InteractiveRow>
diff --git a/src/components/therapy-compass/screens/compare-screen.tsx b/src/components/therapy-compass/screens/compare-screen.tsx
index a908b97f05..b6871cae56 100644
--- a/src/components/therapy-compass/screens/compare-screen.tsx
+++ b/src/components/therapy-compass/screens/compare-screen.tsx
@@ -233,7 +233,7 @@ export function CompareScreen() {
                         className="min-w-[160px] border-l border-[color:var(--border)] px-5 py-3.5 align-top"
                       >
                         <div className="flex items-center gap-[7px]">
-                          <Scale aria-hidden="true" size={15} className="text-[color:var(--decoration-soft)]" />
+                          <Scale aria-hidden="true" className="size-icon-sm text-[color:var(--decoration-soft)]" />
                           <span className="text-sm-minus font-semibold text-[color:var(--text-heading)]">{t.name}</span>
                         </div>
                         <div
@@ -285,7 +285,7 @@ export function CompareScreen() {
             </div>
             <TherapyCompareStack items={items} rows={rows} dense={dense} />
             <div className="flex items-center gap-2 mt-4 text-xs text-[color:var(--text-muted)]">
-              <Info aria-hidden="true" size={15} strokeWidth={1.8} className="text-[color:var(--decoration-soft)]" />
+              <Info aria-hidden="true" strokeWidth={1.8} className="size-icon-sm text-[color:var(--decoration-soft)]" />
               Comparisons are source-grounded. Review status reflects the latest source checks.
             </div>
           </Tabs>
@@ -343,7 +343,7 @@ function TherapyCompareStack({
                 warn ? "text-[color:var(--warning-text)]" : "text-[color:var(--text-muted)]",
               )}
             >
-              <r.icon aria-hidden="true" size={15} strokeWidth={1.8} />
+              <r.icon aria-hidden="true" strokeWidth={1.8} className="size-icon-sm" />
               {r.label}
             </h3>
             <dl className={cn("m-0 grid gap-x-3", dense ? "mt-2 gap-y-1.5" : "mt-2.5 gap-y-2")}>
diff --git a/src/components/therapy-compass/screens/recommend-screen.tsx b/src/components/therapy-compass/screens/recommend-screen.tsx
index 13d9365725..6b0ed1937a 100644
--- a/src/components/therapy-compass/screens/recommend-screen.tsx
+++ b/src/components/therapy-compass/screens/recommend-screen.tsx
@@ -153,7 +153,7 @@ export function RecommendScreen() {
           </div>
 
           <div className="mt-5 flex items-center gap-2 text-xs text-[color:var(--text-muted)]">
-            <Shield aria-hidden="true" size={15} className="text-[color:var(--decoration-soft)]" />
+            <Shield aria-hidden="true" className="size-icon-sm text-[color:var(--decoration-soft)]" />
             Ranking is source-grounded and advisory. Confirm fit, cautions and review status before clinical use.
           </div>
         </>
diff --git a/src/components/therapy-compass/screens/sheets-screen.tsx b/src/components/therapy-compass/screens/sheets-screen.tsx
index 82de055b06..98e3cc4b09 100644
--- a/src/components/therapy-compass/screens/sheets-screen.tsx
+++ b/src/components/therapy-compass/screens/sheets-screen.tsx
@@ -336,9 +336,8 @@ function TherapyPicker() {
         </span>
         <ChevronDown
           aria-hidden="true"
-          size={15}
           strokeWidth={1.8}
-          className="text-[color:var(--decoration-soft)] flex-none"
+          className="size-icon-sm text-[color:var(--decoration-soft)] flex-none"
         />
       </button>
       {open ? (
@@ -346,9 +345,8 @@ function TherapyPicker() {
           <label className="relative flex items-center p-2 border-b border-[color:var(--border)]">
             <Search
               aria-hidden="true"
-              size={15}
               strokeWidth={1.8}
-              className="absolute left-[18px] text-[color:var(--decoration-soft)]"
+              className="absolute left-[18px] size-icon-sm text-[color:var(--decoration-soft)]"
             />
             <input
               value={q}
diff --git a/src/components/therapy-compass/therapy-card.tsx b/src/components/therapy-compass/therapy-card.tsx
index ddc228d695..ba2178604e 100644
--- a/src/components/therapy-compass/therapy-card.tsx
+++ b/src/components/therapy-compass/therapy-card.tsx
@@ -287,15 +287,14 @@ export function TherapyListItem({
       {trailing ?? (
         <span className="flex-none text-[color:var(--decoration-soft)]">
           {therapy.reviewStatus === "reviewed" ? null : (
-            <TriangleAlert aria-hidden="true" size={15} strokeWidth={1.8} />
+            <TriangleAlert aria-hidden="true" strokeWidth={1.8} className="size-icon-sm" />
           )}
         </span>
       )}
       <ChevronRight
         aria-hidden="true"
-        size={15}
         strokeWidth={1.8}
-        className="flex-none text-[color:var(--decoration-soft)]"
+        className="size-icon-sm flex-none text-[color:var(--decoration-soft)]"
       />
     </InteractiveRow>
   );
diff --git a/tests/ckb-v2-token-contract.test.ts b/tests/ckb-v2-token-contract.test.ts
index 05fc000fe4..b2ad7873c2 100644
--- a/tests/ckb-v2-token-contract.test.ts
+++ b/tests/ckb-v2-token-contract.test.ts
@@ -314,16 +314,15 @@ describe("ckb-v2 structure", () => {
     }
   });
 
-  it("gives every type step its own line-height and tracking (#3, #14, #35, #36)", () => {
+  it("pins shared leading and hero companions, not per-step orphans (#3, #14, #35, #36)", () => {
     for (const step of ["xs", "sm", "body", "md", "lg", "xl"]) {
       expect(structural.has(`--text-${step}`), `--text-${step} missing`).toBe(true);
-      expect(structural.has(`--text-${step}-lh`), `--text-${step}-lh missing`).toBe(true);
-      expect(structural.has(`--text-${step}-tr`), `--text-${step}-tr missing`).toBe(true);
+      expect(structural.has(`--text-${step}-lh`), `--text-${step}-lh must stay deleted`).toBe(false);
+      expect(structural.has(`--text-${step}-tr`), `--text-${step}-tr must stay deleted`).toBe(false);
     }
-    // Negative tracking only from 15px up — tightening small text hurts legibility.
-    expect(structural.get("--text-xs-tr")).toBe("0");
-    expect(structural.get("--text-sm-tr")).toBe("0");
-    expect(structural.get("--text-body-tr")).toMatch(/^-/);
+    expect(structural.get("--leading-prose")).toMatch(/^\d+(\.\d+)?$/);
+    expect(structural.get("--text-hero--line-height")).toMatch(/^\d+(\.\d+)?$/);
+    expect(structural.get("--text-hero-tr")).toMatch(/^-/);
   });
 });
 
diff --git a/tests/design-system-contract-utils.test.ts b/tests/design-system-contract-utils.test.ts
index fbfec867a3..65a7f4391f 100644
--- a/tests/design-system-contract-utils.test.ts
+++ b/tests/design-system-contract-utils.test.ts
@@ -658,4 +658,50 @@ describe("design-system contract helpers", () => {
     );
     expect(reportFailure).toHaveBeenCalledWith("printable factsheet paper boundary is missing");
   });
+
+  it("masks only the medication accent default, not other hex in the same file", () => {
+    const reportFailure = vi.fn();
+    const source = [
+      "export function rowToMedicationRecord(row) {",
+      '  return { accent: row.accent ?? "#0f766e", tag: row.tag };',
+      "}",
+      'export const UNRELATED = "#123456";',
+      'export const ALSO_TEAL = "#0f766e";',
+    ].join("\n");
+
+    const records = rawColorContractSource("src/lib/medication-records.ts", source, reportFailure);
+    expect(records).not.toMatch(/accent: row\.accent \?\? "#0f766e"/);
+    expect(records).toContain('export const ALSO_TEAL = "#0f766e"');
+    expect(records).toContain("#123456");
+    expect(reportFailure).not.toHaveBeenCalled();
+
+    const medications = rawColorContractSource(
+      "src/lib/medications.ts",
+      'export function normalizeRecord(record) { return { accent: record.accent?.trim() || "#0f766e" }; }\nexport const OTHER = "#abcdef";',
+      reportFailure,
+    );
+    expect(medications).not.toContain("#0f766e");
+    expect(medications).toContain("#abcdef");
+    expect(reportFailure).not.toHaveBeenCalled();
+  });
+
+  it("does not treat accentColor or a comment mention as the medication accent default", () => {
+    const reportFailure = vi.fn();
+    const source = [
+      'export const accentColor = "#0f766e";',
+      '// fallback accent: row.accent ?? "#0f766e"',
+      'export const UNRELATED = "#123456";',
+    ].join("\n");
+
+    expect(rawColorContractSource("src/lib/medications.ts", source, reportFailure)).toBe(source);
+    expect(reportFailure).toHaveBeenCalledWith("medication accent default boundary is missing");
+  });
+
+  it("fails closed when the medication accent default boundary disappears", () => {
+    const reportFailure = vi.fn();
+    const source = 'export const FALLBACK = "#0f766e";';
+
+    expect(rawColorContractSource("src/lib/medication-records.ts", source, reportFailure)).toBe(source);
+    expect(reportFailure).toHaveBeenCalledWith("medication accent default boundary is missing");
+  });
 });

From fda57560b31b1b1ab5e86a8b232eff0e41951a92 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Thu, 27 Aug 2026 15:00:57 +0800
Subject: [PATCH 2/9] style: format design-system docs after merging main

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/design-system/FIX-GUIDE.md | 58 +++++++++++++++---------------
 docs/design-system/GATES.md     |  2 +-
 docs/design-system/TOKENS.md    | 62 ++++++++++++++++-----------------
 3 files changed, 61 insertions(+), 61 deletions(-)

diff --git a/docs/design-system/FIX-GUIDE.md b/docs/design-system/FIX-GUIDE.md
index a92f9e7ff9..ea94c24453 100644
--- a/docs/design-system/FIX-GUIDE.md
+++ b/docs/design-system/FIX-GUIDE.md
@@ -23,41 +23,41 @@ mockup `min-h-11` or `--text-soft` body into production.
 Agents 1–3 land these. Parent verifies after merge; do not treat this table as a second
 measurement of `globals.css` / `ckb-v2-tokens.css`.
 
-| ID | Status | Rationale |
-| ---- | ---------- | --------- |
-| DS-P1-16 | Fixed | Therapy-compass decorative `size={15}` maps to `size-icon-sm` (14px); Lucide `size` prop removed so SVG attrs cannot override the class. |
-| DS-P2-03 | Fixed | Unused `--text-{xs,sm,body,md,lg,xl}-lh` / `-tr` companions deleted; keep `--text-hero--line-height` and `--text-hero-tr`. Do not re-require per-step orphans. |
-| DS-P2-07 | Fixed | Two `1px` shadow-spread layers dropped in `globals.css` (compare FAB already has a border; disabled send uses a border, not inset+border). |
-| DS-P2-12 | Fixed | Three raw `line-height` literals in `globals.css` map to existing named tokens (`--text-hero--line-height`, `--leading-prose`). Not `--leading-tight`. |
-| DS-P2-13 | Fixed | Specifier surfaces that already own the edge with `border` lose `shadow-inset`. True wells, segmented tracks, field-controls, and Ward stay. |
-| DS-P2-17 | Fixed | `differential-detail-page` uses `resolveScrollBehavior()`; `settings-dialog` already branches on reduce-motion and is left alone. |
-| DS-P2-25 | Fixed | `#0f766e` medication accent defaults stay data, not `--clinical-accent`. Scoped `RAW_COLOR_EXEMPTIONS` entry; `rawColorLiterals` 2→0. See below. |
+| ID       | Status | Rationale                                                                                                                                                      |
+| -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| DS-P1-16 | Fixed  | Therapy-compass decorative `size={15}` maps to `size-icon-sm` (14px); Lucide `size` prop removed so SVG attrs cannot override the class.                       |
+| DS-P2-03 | Fixed  | Unused `--text-{xs,sm,body,md,lg,xl}-lh` / `-tr` companions deleted; keep `--text-hero--line-height` and `--text-hero-tr`. Do not re-require per-step orphans. |
+| DS-P2-07 | Fixed  | Two `1px` shadow-spread layers dropped in `globals.css` (compare FAB already has a border; disabled send uses a border, not inset+border).                     |
+| DS-P2-12 | Fixed  | Three raw `line-height` literals in `globals.css` map to existing named tokens (`--text-hero--line-height`, `--leading-prose`). Not `--leading-tight`.         |
+| DS-P2-13 | Fixed  | Specifier surfaces that already own the edge with `border` lose `shadow-inset`. True wells, segmented tracks, field-controls, and Ward stay.                   |
+| DS-P2-17 | Fixed  | `differential-detail-page` uses `resolveScrollBehavior()`; `settings-dialog` already branches on reduce-motion and is left alone.                              |
+| DS-P2-25 | Fixed  | `#0f766e` medication accent defaults stay data, not `--clinical-accent`. Scoped `RAW_COLOR_EXEMPTIONS` entry; `rawColorLiterals` 2→0. See below.               |
 
 ---
 
 ## Batch B — docs dispositions
 
-| ID | Status | Rationale |
-| ---- | ---------- | --------- |
-| DS-P2-04 | Documented | Intentional Geist variable interpolation. Already explained in [`docs/design-system.md`](../design-system.md) (intermediate weights; do **not** snap to 600/700). |
-| DS-P2-22 | Documented | `SectionHeading` exists (`src/components/ui/section-heading.tsx`); 14 production call sites. No opportunistic migration this sweep. |
-| DS-P2-23 | Documented | `AnswerCard` `frame?: "raised" \| "bare"` — both valid. Production answer surface uses **bare**. Future visual baselines must include both. Do not commit screenshots. |
-| DS-P2-27 | Documented | 15-mode load: recommend first-run / Tools prominence later. No IA redesign this sweep. |
-| DS-P2-28 | Documented | Settings **Motion** already has a per-control description. **Recent searches on home** does not — docs recommendation only; no extra intro copy in product this sweep. |
-| DS-P2-29 | Deferred | Phone document-viewer density waits on the tap-floor (Hazard ≥3). |
-| DS-P2-30 | Documented | Toast primitive exists; there is no **universal network-error** toast. Do not build toast infra here. `OverlayRoot` remains the overlay owner. |
-| DS-P2-31 | Documented | Already in TOKENS §4 / SPEC §3: add `--kind-*` **with the first call site**. No values in this sweep. |
-| DS-P2-32 | Documented | `--text-placeholder` is **live** (globals + v2 + `placeholder:` consumers), not planned. TOKENS §5 corrected. No further role migration. |
-| DS-P2-33 | Documented | Contract `textSoftConsumers=0` in production. Keep the `--text-soft` alias until zero `var(--text-soft)` remain **including mockups**. Do not rename; do not delete this sweep. |
-| DS-P3-01 | Deferred | PR-9 plan. `--shadow-focus` and dead springs are already gone. `--shadow-lift` still has live `mode-nav` and `document-search-results` consumers — do **not** delete it. |
-| DS-P3-02 | Documented | TOKENS already: `--tone-*` frozen, not deleted. |
-| DS-P3-03 | Documented | TOKENS already: design-side `--quantity-unit-scale` never lands. |
-| DS-P3-04 | Documented | TOKENS already: ConfidenceMeter deferred; no token without a call site. |
+| ID       | Status     | Rationale                                                                                                                                                                                   |
+| -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| DS-P2-04 | Documented | Intentional Geist variable interpolation. Already explained in [`docs/design-system.md`](../design-system.md) (intermediate weights; do **not** snap to 600/700).                           |
+| DS-P2-22 | Documented | `SectionHeading` exists (`src/components/ui/section-heading.tsx`); 14 production call sites. No opportunistic migration this sweep.                                                         |
+| DS-P2-23 | Documented | `AnswerCard` `frame?: "raised" \| "bare"` — both valid. Production answer surface uses **bare**. Future visual baselines must include both. Do not commit screenshots.                      |
+| DS-P2-27 | Documented | 15-mode load: recommend first-run / Tools prominence later. No IA redesign this sweep.                                                                                                      |
+| DS-P2-28 | Documented | Settings **Motion** already has a per-control description. **Recent searches on home** does not — docs recommendation only; no extra intro copy in product this sweep.                      |
+| DS-P2-29 | Deferred   | Phone document-viewer density waits on the tap-floor (Hazard ≥3).                                                                                                                           |
+| DS-P2-30 | Documented | Toast primitive exists; there is no **universal network-error** toast. Do not build toast infra here. `OverlayRoot` remains the overlay owner.                                              |
+| DS-P2-31 | Documented | Already in TOKENS §4 / SPEC §3: add `--kind-*` **with the first call site**. No values in this sweep.                                                                                       |
+| DS-P2-32 | Documented | `--text-placeholder` is **live** (globals + v2 + `placeholder:` consumers), not planned. TOKENS §5 corrected. No further role migration.                                                    |
+| DS-P2-33 | Documented | Contract `textSoftConsumers=0` in production. Keep the `--text-soft` alias until zero `var(--text-soft)` remain **including mockups**. Do not rename; do not delete this sweep.             |
+| DS-P3-01 | Deferred   | PR-9 plan. `--shadow-focus` and dead springs are already gone. `--shadow-lift` still has live `mode-nav` and `document-search-results` consumers — do **not** delete it.                    |
+| DS-P3-02 | Documented | TOKENS already: `--tone-*` frozen, not deleted.                                                                                                                                             |
+| DS-P3-03 | Documented | TOKENS already: design-side `--quantity-unit-scale` never lands.                                                                                                                            |
+| DS-P3-04 | Documented | TOKENS already: ConfidenceMeter deferred; no token without a call site.                                                                                                                     |
 | DS-P3-05 | Documented | Registry has **55** registered visual exports. `DocumentFrame` is built shell-only and still unregistered. Register when print primitives ship (PR 11). Docs elsewhere may still say 53/54. |
-| DS-P3-07 | Documented | Full visual state matrix grows incrementally with new adoptions. |
-| DS-P3-08 | Documented | QA checklist: inspect the filter band at 414–430px. No code this sweep. |
-| DS-P3-09 | Documented | `#TYZK23` PWA install CLS already fixed (PR #2253). Regression-check note only; no speculative CSS. |
-| DS-P3-10 | Documented | Mockup `min-h-11` and `--text-soft` body must not leak into production. |
+| DS-P3-07 | Documented | Full visual state matrix grows incrementally with new adoptions.                                                                                                                            |
+| DS-P3-08 | Documented | QA checklist: inspect the filter band at 414–430px. No code this sweep.                                                                                                                     |
+| DS-P3-09 | Documented | `#TYZK23` PWA install CLS already fixed (PR #2253). Regression-check note only; no speculative CSS.                                                                                         |
+| DS-P3-10 | Documented | Mockup `min-h-11` and `--text-soft` body must not leak into production.                                                                                                                     |
 
 ---
 
diff --git a/docs/design-system/GATES.md b/docs/design-system/GATES.md
index f58579bbf1..c2d75730a8 100644
--- a/docs/design-system/GATES.md
+++ b/docs/design-system/GATES.md
@@ -19,7 +19,7 @@ than CI, two of them by the second reader; review does not scale past two carefu
 | Check                                                                                                                                                       | What it enforces                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Label                                |
 | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
 | `npm run check:design-system-contract` (token baseline + adoption + design-sync contracts)                                                                  | Raw colour literals (ratchet against `design-system-contract-baseline.json`), literal `shadow-[…]` classes, the legacy tap class, interactive tap-size literals, therapy-compass `tc-btn` base-class use; border+ring edge conflicts, 1px shadow spreads, layout-property transitions and legacy shadow aliases (all ratcheted **per path**, so new use fails anywhere); status-coloured numerals and colour-only status indicators; raw padding, radius, gap and line-height literals in both classes and CSS declarations (ratcheted **per path**; named utilities and Tailwind arbitrary-property forms such as `[padding:22px]` both count; values computed with `var()`/`env()`/`calc()`/`clamp()`/`max()`, zero with any CSS unit identifier, and the CSS-wide keywords are exempt); declared-but-unselected type steps (**hard rule** with a gated exemption list); `dark:` colour overrides, legacy palette utilities and image-inversion filters (all pinned at **zero**, not ratcheted); deterministic adoption truth; local source/export/preview/design-sync parity. Mockups exempt. | implemented-blocking                 |
-| `tests/ckb-v2-token-contract.test.ts`                                                                                                                       | v2 layer stays class-scoped (no `:root` leak) · `--border-lux` solid and no lighter than `--border`, both themes · dark surface ramp monotonic and separated · `--surface-subtle` aliases up · text/muted/heading ≥4.5:1 on the light shell, muted ≥4.5:1 dark · `--text-soft` pinned **below** 4.5:1 and ≥3:1 (both sides, so the tier cannot be "fixed" away) · command pair ≥4.5:1 both themes · `--shadow-inset` true inset · elevation ladder carries no baked 1px hairline · tap floor ≠ chip height ≠ compact row · reduced-motion zeroes durations · type-scale pins `--leading-prose` plus `--text-hero--line-height` / `--text-hero-tr` (no per-step `-lh`/`-tr` orphans)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | implemented-blocking                 |
+| `tests/ckb-v2-token-contract.test.ts`                                                                                                                       | v2 layer stays class-scoped (no `:root` leak) · `--border-lux` solid and no lighter than `--border`, both themes · dark surface ramp monotonic and separated · `--surface-subtle` aliases up · text/muted/heading ≥4.5:1 on the light shell, muted ≥4.5:1 dark · `--text-soft` pinned **below** 4.5:1 and ≥3:1 (both sides, so the tier cannot be "fixed" away) · command pair ≥4.5:1 both themes · `--shadow-inset` true inset · elevation ladder carries no baked 1px hairline · tap floor ≠ chip height ≠ compact row · reduced-motion zeroes durations · type-scale pins `--leading-prose` plus `--text-hero--line-height` / `--text-hero-tr` (no per-step `-lh`/`-tr` orphans)                                                                                                                                                                                                                                                                                                                                                                                                              | implemented-blocking                 |
 | `tests/design-token-contract.test.ts`                                                                                                                       | Live-layer token relationships (companion to the v2 contract)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | implemented-blocking                 |
 | `tests/source-badges-off-vocab.dom.test.tsx`                                                                                                                | Enum resilience: off-vocabulary `clinical_validation_status` degrades to the neutral triad, logs once, never throws                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | implemented-blocking                 |
 | `tests/source-metadata-browser-safety.test.ts`                                                                                                              | The `process is not defined` client-bundle crash stays fixed (server logger never ships to the browser)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | implemented-blocking                 |
diff --git a/docs/design-system/TOKENS.md b/docs/design-system/TOKENS.md
index f9a19fb5d2..c6e63579c8 100644
--- a/docs/design-system/TOKENS.md
+++ b/docs/design-system/TOKENS.md
@@ -41,27 +41,27 @@ This is the two-sources-of-truth failure C1 exists to kill. One winner per role:
 
 Declared in the `.ckb-v2` structural block **[verified: full read at `ef13a072a`]**.
 
-| Group            | Roles                                                                                                                                     | Notes                                                                                                                                                                                                                                                                                        |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Space scale      | `--space-0` … `--space-11`                                                                                                                | 4px base. Markup never references the raw scale — semantic tokens only.                                                                                                                                                                                                                      |
-| Semantic gaps    | `--gap-tight` · `--gap-inline` · `--gap-stack` · `--gap-block` · `--gap-section`                                                          | The only inter-element spacing markup may use.                                                                                                                                                                                                                                               |
-| Semantic padding | `--pad-chip-x` · `--pad-control-x` · `--pad-cta-x` · `--pad-card` · `--pad-panel` · `--pad-strip`                                         | Heading-inset convention rides on these (SPEC §4.6).                                                                                                                                                                                                                                         |
-| Page             | `--page-gutter` · `--page-max` · `--measure` · `--header-h`                                                                               | `--measure` is the prose measure — never wider.                                                                                                                                                                                                                                              |
-| Type steps       | `--text-{xs,sm,body,md,lg,xl}` · `--text-hero` · `--text-hero--line-height` · `--text-hero-tr`                                             | Seven steps. Shared `--leading-prose`; hero keeps `--text-hero--line-height` / `--text-hero-tr` (gated). Unused xs–xl `-lh`/`-tr` companions are orphans — do not re-require them. ⚠️ `--text-hero--line-height` is the one double-dash name — keep as-is; renaming is churn without a defect. |
-| Chip sizes       | `Chip` `compact` → `--text-2xs` (legacy compat step); `standard` (default) → `--text-xs`                                                  | Canonical (#220): dense surfaces opt into `size="compact"`; default adoption keeps `--text-xs`. `--text-2xs` stays a compatibility alias for Chip compact / legacy call sites — not a new v2 type step to invent against. Do not densify every Chip to chase the globals “small chips” note. |
-| Type companions  | `--leading-prose` · `--tracking-eyebrow` · `--nums`                                                                                       | `--nums` = numeric variant for all data.                                                                                                                                                                                                                                                     |
-| Weights          | `--font-weight-{body,label,heading,value}`                                                                                                | One job each; display uses heading weight (SPEC §4.6).                                                                                                                                                                                                                                       |
-| Radius           | `--radius-{sm,md,lg,xl,2xl}`                                                                                                              | One step per surface role. v2 and live `--radius-md` agreed in PR 5c and are now pinned to each other by the live token contract.                                                                                                                                                            |
-| Icons            | `--icon-{xs,sm,md,lg}`                                                                                                                    | Paired to adjacent type steps.                                                                                                                                                                                                                                                               |
-| Density          | `--tap-min` (alias of `--spacing-tap`, §1) · `--chip-height` · `--row-comfortable` · `--row-compact` · `--cell-pad-{comfortable,compact}` | Tap target is not row height (gated on resolved values, not strings, now that `--tap-min` is an alias).                                                                                                                                                                                      |
-| Accent rules     | `--rule-w` · `--rule-accent` · `--rule-warning`                                                                                           | ⚠️ Reference `var(--clinical-accent)` / `var(--warning)` **without declaring them** — v2 depends on the live layer for both (§5).                                                                                                                                                            |
-| Evidence gutter  | `--gutter-col` · `--gutter-dot` · `--gutter-line-w`                                                                                       | One gutter column owns line and dot (SPEC §7).                                                                                                                                                                                                                                               |
-| Evidence spine   | `--spine-w` · `--spine-current` · `--spine-stale`                                                                                         | Authored `59e4c3dfc` (§1); derived from rule/accent/warning roles.                                                                                                                                                                                                                           |
-| Status mark      | `--status-mark-size` · `--status-mark-stroke`                                                                                             | Authored `59e4c3dfc` (§1); codifies `StatusMark`'s inline geometry.                                                                                                                                                                                                                          |
-| Quantity         | `--quantity-unit-tracking` · `--quantity-unit-gap`                                                                                        | Winners per §1.                                                                                                                                                                                                                                                                              |
-| Dashed edge      | `--border-dashed`                                                                                                                         | Drop targets / "nothing here yet" — distinct from `--border-strong`, which means emphasis.                                                                                                                                                                                                   |
-| Stacking         | `--z-{base,raised,chrome,overlay,popover,modal,toast}`                                                                                    | Each rung names its `--eN` partner; toast above modal deliberately.                                                                                                                                                                                                                          |
-| Motion           | `--duration-{fast,base,slow}` · `--ease-standard` · `--ease-physical`                                                                     | Durations zero under `prefers-reduced-motion` (gated).                                                                                                                                                                                                                                       |
+| Group            | Roles                                                                                                                                     | Notes                                                                                                                                                                                                                                                                                          |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Space scale      | `--space-0` … `--space-11`                                                                                                                | 4px base. Markup never references the raw scale — semantic tokens only.                                                                                                                                                                                                                        |
+| Semantic gaps    | `--gap-tight` · `--gap-inline` · `--gap-stack` · `--gap-block` · `--gap-section`                                                          | The only inter-element spacing markup may use.                                                                                                                                                                                                                                                 |
+| Semantic padding | `--pad-chip-x` · `--pad-control-x` · `--pad-cta-x` · `--pad-card` · `--pad-panel` · `--pad-strip`                                         | Heading-inset convention rides on these (SPEC §4.6).                                                                                                                                                                                                                                           |
+| Page             | `--page-gutter` · `--page-max` · `--measure` · `--header-h`                                                                               | `--measure` is the prose measure — never wider.                                                                                                                                                                                                                                                |
+| Type steps       | `--text-{xs,sm,body,md,lg,xl}` · `--text-hero` · `--text-hero--line-height` · `--text-hero-tr`                                            | Seven steps. Shared `--leading-prose`; hero keeps `--text-hero--line-height` / `--text-hero-tr` (gated). Unused xs–xl `-lh`/`-tr` companions are orphans — do not re-require them. ⚠️ `--text-hero--line-height` is the one double-dash name — keep as-is; renaming is churn without a defect. |
+| Chip sizes       | `Chip` `compact` → `--text-2xs` (legacy compat step); `standard` (default) → `--text-xs`                                                  | Canonical (#220): dense surfaces opt into `size="compact"`; default adoption keeps `--text-xs`. `--text-2xs` stays a compatibility alias for Chip compact / legacy call sites — not a new v2 type step to invent against. Do not densify every Chip to chase the globals “small chips” note.   |
+| Type companions  | `--leading-prose` · `--tracking-eyebrow` · `--nums`                                                                                       | `--nums` = numeric variant for all data.                                                                                                                                                                                                                                                       |
+| Weights          | `--font-weight-{body,label,heading,value}`                                                                                                | One job each; display uses heading weight (SPEC §4.6).                                                                                                                                                                                                                                         |
+| Radius           | `--radius-{sm,md,lg,xl,2xl}`                                                                                                              | One step per surface role. v2 and live `--radius-md` agreed in PR 5c and are now pinned to each other by the live token contract.                                                                                                                                                              |
+| Icons            | `--icon-{xs,sm,md,lg}`                                                                                                                    | Paired to adjacent type steps.                                                                                                                                                                                                                                                                 |
+| Density          | `--tap-min` (alias of `--spacing-tap`, §1) · `--chip-height` · `--row-comfortable` · `--row-compact` · `--cell-pad-{comfortable,compact}` | Tap target is not row height (gated on resolved values, not strings, now that `--tap-min` is an alias).                                                                                                                                                                                        |
+| Accent rules     | `--rule-w` · `--rule-accent` · `--rule-warning`                                                                                           | ⚠️ Reference `var(--clinical-accent)` / `var(--warning)` **without declaring them** — v2 depends on the live layer for both (§5).                                                                                                                                                              |
+| Evidence gutter  | `--gutter-col` · `--gutter-dot` · `--gutter-line-w`                                                                                       | One gutter column owns line and dot (SPEC §7).                                                                                                                                                                                                                                                 |
+| Evidence spine   | `--spine-w` · `--spine-current` · `--spine-stale`                                                                                         | Authored `59e4c3dfc` (§1); derived from rule/accent/warning roles.                                                                                                                                                                                                                             |
+| Status mark      | `--status-mark-size` · `--status-mark-stroke`                                                                                             | Authored `59e4c3dfc` (§1); codifies `StatusMark`'s inline geometry.                                                                                                                                                                                                                            |
+| Quantity         | `--quantity-unit-tracking` · `--quantity-unit-gap`                                                                                        | Winners per §1.                                                                                                                                                                                                                                                                                |
+| Dashed edge      | `--border-dashed`                                                                                                                         | Drop targets / "nothing here yet" — distinct from `--border-strong`, which means emphasis.                                                                                                                                                                                                     |
+| Stacking         | `--z-{base,raised,chrome,overlay,popover,modal,toast}`                                                                                    | Each rung names its `--eN` partner; toast above modal deliberately.                                                                                                                                                                                                                            |
+| Motion           | `--duration-{fast,base,slow}` · `--ease-standard` · `--ease-physical`                                                                     | Durations zero under `prefers-reduced-motion` (gated).                                                                                                                                                                                                                                         |
 
 ## 3 · v2 shell inventory — light and dark blocks
 
@@ -96,16 +96,16 @@ the full pair-matrix gate lands (GATES §2, gate 1).
 
 The v2 layer _references_ or _depends on_ these; their values stay in `live` / `@theme`:
 
-| Role                                                    | Owner            | Rule                                                                                                                        |
-| ------------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `--spacing-tap`                                         | `@theme`         | **The** tap knob; generates `min-h-tap`/`h-tap`/`size-tap`/`min-w-tap`/`w-tap` (426 call sites). 44→48 landed here (PR 5b). |
-| `--clinical-accent`                                     | `live`           | Consumed by v2 `--rule-accent` without declaration — inherited dependency.                                                  |
-| `--warning`                                             | `live`           | Consumed by v2 `--rule-warning` — same.                                                                                     |
-| `--danger`, `--danger-solid`, `--danger-solid-contrast` | `live`           | Filled danger pairs with `--danger-solid-contrast` (HCM-mapped to `MarkText`); pairing enforced from PR 3.                  |
-| `--success`, `--info`                                   | `live`           | Clinical/status palette — reserved channel.                                                                                 |
-| `--focus`                                               | `live`           | The only focus outline colour; no companion ring, ever.                                                                     |
-| `--ring-highlight`, `--ring-glass`                      | `live`           | Highlight rings on lux surfaces; each carries its own per-theme value, so `dark:ring-*` is gated at zero (GATES §3).        |
-| `--text-placeholder`                                    | `live`           | Declared in globals and v2; ≥4.5:1 placeholder ink. Not planned. No further role migration this sweep.                      |
+| Role                                                    | Owner    | Rule                                                                                                                        |
+| ------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `--spacing-tap`                                         | `@theme` | **The** tap knob; generates `min-h-tap`/`h-tap`/`size-tap`/`min-w-tap`/`w-tap` (426 call sites). 44→48 landed here (PR 5b). |
+| `--clinical-accent`                                     | `live`   | Consumed by v2 `--rule-accent` without declaration — inherited dependency.                                                  |
+| `--warning`                                             | `live`   | Consumed by v2 `--rule-warning` — same.                                                                                     |
+| `--danger`, `--danger-solid`, `--danger-solid-contrast` | `live`   | Filled danger pairs with `--danger-solid-contrast` (HCM-mapped to `MarkText`); pairing enforced from PR 3.                  |
+| `--success`, `--info`                                   | `live`   | Clinical/status palette — reserved channel.                                                                                 |
+| `--focus`                                               | `live`   | The only focus outline colour; no companion ring, ever.                                                                     |
+| `--ring-highlight`, `--ring-glass`                      | `live`   | Highlight rings on lux surfaces; each carries its own per-theme value, so `dark:ring-*` is gated at zero (GATES §3).        |
+| `--text-placeholder`                                    | `live`   | Declared in globals and v2; ≥4.5:1 placeholder ink. Not planned. No further role migration this sweep.                      |
 
 ## 6 · Deprecations and deletions
 

From 6ac1002d808c656adfb5325ede3183ffa8b6543e Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Thu, 27 Aug 2026 15:17:11 +0800
Subject: [PATCH 3/9] chore: refresh repo-awareness snapshot after merging main

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 data/repo-awareness-snapshot.json | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/data/repo-awareness-snapshot.json b/data/repo-awareness-snapshot.json
index eda565017d..9aa2484ec9 100644
--- a/data/repo-awareness-snapshot.json
+++ b/data/repo-awareness-snapshot.json
@@ -1,8 +1,8 @@
 {
   "version": "repo-awareness-snapshot-v1",
   "captured_revision": {
-    "sha": "59bb01b3e5c6b5c846053d2916d3e780ea38bbb1",
-    "committed_at": "2026-08-27T05:20:05+00:00"
+    "sha": "fda57560b31b1b1ab5e86a8b232eff0e41951a92",
+    "committed_at": "2026-08-27T15:00:57+08:00"
   },
   "routes": {
     "modes": [
@@ -2386,6 +2386,11 @@
         "section": "design-system",
         "catalogued": true
       },
+      {
+        "path": "docs/design-system/FIX-GUIDE.md",
+        "section": "design-system",
+        "catalogued": false
+      },
       {
         "path": "docs/design-system/GATES.md",
         "section": "design-system",
@@ -3867,9 +3872,9 @@
       }
     ],
     "counts": {
-      "documents": 480,
+      "documents": 481,
       "catalogued": 106,
-      "uncatalogued": 374,
+      "uncatalogued": 375,
       "sections": 19
     }
   },

From b7c718680dd92a1f263dfed3bd3d079fff59ec15 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Thu, 27 Aug 2026 16:53:34 +0800
Subject: [PATCH 4/9] docs(design-system): pin GATES totals and v2 leading
 tokens

Keep quoted contract numbers in lockstep with the baseline JSON, and replace nested brief-duration ternaries plus leftover Lucide size={16} on screens this sweep already touched.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/README.md                                |  4 ++-
 docs/codebase-index.md                        |  4 +--
 docs/design-system-contract.md                |  6 ++--
 docs/design-system/ADOPTION.md                |  2 +-
 docs/design-system/COMPONENTS.md              |  5 +--
 docs/design-system/DECISIONS.md               |  2 +-
 docs/design-system/FIX-GUIDE.md               |  6 ++--
 docs/design-system/GATES.md                   | 18 +++++------
 docs/design-system/SPEC.md                    | 13 ++++----
 docs/design-system/TOKENS.md                  | 10 +++---
 docs/process-hardening.md                     |  2 +-
 docs/scripts-index.md                         |  7 ++++-
 docs/testing.md                               |  6 ++--
 src/app/globals.css                           |  8 +++--
 .../therapy-compass/screens/brief-screen.tsx  | 31 ++++++++++++-------
 .../screens/compare-screen.tsx                |  2 +-
 .../therapy-compass/screens/sheets-screen.tsx |  2 +-
 tests/ckb-v2-token-contract.test.ts           | 19 ++++++++++--
 tests/design-system-adoption.test.ts          | 15 +++++++++
 ...herapy-compass-responsive-contract.test.ts | 17 ++++++++++
 20 files changed, 123 insertions(+), 56 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index 6098437cc7..aa9dc406e3 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -30,13 +30,15 @@ npm run docs:check-links
 - [search-results-bar-decisions.md](search-results-bar-decisions.md) — shared results-bar anatomy, why the filter shelf is scoped to two modes, and what is deliberately not done
 - [deployment-architecture.md](deployment-architecture.md) — app/worker/Supabase deployment topology
 - [ingestion-state-machine.md](ingestion-state-machine.md) — ingestion job lifecycle and states
-- [design-system.md](design-system.md) — tokens, primitives, styling conventions
+- [design-system/README.md](design-system/README.md) — front door for the v2 design system (tokens, components, gates)
+- [design-system.md](design-system.md) — live-layer notes during the v1→v2 transition (superseded as spec)
 - [design-system/SPEC.md](design-system/SPEC.md) — the complete v2 design system: roles, rules, rationale (never values)
 - [design-system/TOKENS.md](design-system/TOKENS.md) — reconciled token inventory: every role, winning name, owner, and what it replaces
 - [design-system/COMPONENTS.md](design-system/COMPONENTS.md) — the eight safety-component specifications plus the maturity matrix
 - [design-system/DECISIONS.md](design-system/DECISIONS.md) — conflicts C1–C5 resolved, clinical Q&A record, assumptions, blocked items
 - [design-system/GATES.md](design-system/GATES.md) — every design-system rule paired with its enforcement status
 - [design-system/ADOPTION.md](design-system/ADOPTION.md) — PR 13 registration record: adoption order, per-surface file allowlists, exclusions, pins, proof shots
+- [design-system/FIX-GUIDE.md](design-system/FIX-GUIDE.md) — Hazard 1–2 sweep dispositions (Fixed / Documented / Deferred / Out-of-scope)
 - [comparison-behaviour.md](comparison-behaviour.md) — shared selection, state, responsive, and accessibility contract for comparison surfaces
 - [clinical-chat-ui-component-map.md](clinical-chat-ui-component-map.md) — chat UI component inventory
 - [clinical-badge-system-guide.md](clinical-badge-system-guide.md) — clinical badge semantics
diff --git a/docs/codebase-index.md b/docs/codebase-index.md
index 8b06bdefb1..6878cb4723 100644
--- a/docs/codebase-index.md
+++ b/docs/codebase-index.md
@@ -11,7 +11,7 @@ Structured map for AI agents and onboarding. For live routes, see `docs/site-map
 
 | Step                              | Command                          |
 | --------------------------------- | -------------------------------- |
-| Confirm Supabase target           | `npm run check:supabase-project` |
+| Confirm Supabase target           | `npm run check:supabase-project` (provider-backed — needs explicit confirmation) |
 | Start app (project-specific port) | `npm run ensure`                 |
 | Start ingestion worker            | `npm run worker`                 |
 | Cheap verification gate           | `npm run verify:cheap`           |
@@ -28,7 +28,7 @@ Structured map for AI agents and onboarding. For live routes, see `docs/site-map
 | `worker/`   | Local ingestion worker (parse, OCR, chunk, embed, DB writes)     |
 | `scripts/`  | CLI ops: reindex, eval, backfill, governance, dev-server helpers |
 | `tests/`    | Vitest unit (`*.test.ts`) + Playwright E2E (`ui-*.spec.ts`)      |
-| `docs/`     | Runbooks, governance, search/RAG plans, generated sitemap        |
+| `docs/`     | Runbooks, governance, search/RAG plans, generated sitemap; design-system system of record is [`docs/design-system/README.md`](design-system/README.md) |
 | `public/`   | Static assets (`public/llms.txt`)                                |
 | `.github/`  | CI workflows, PR template (clinical governance preflight)        |
 
diff --git a/docs/design-system-contract.md b/docs/design-system-contract.md
index 850ab04813..aa7e2d9d73 100644
--- a/docs/design-system-contract.md
+++ b/docs/design-system-contract.md
@@ -25,8 +25,8 @@ npm run check:icon-scale
 - **Tokens Only**: Raw CSS hex codes (e.g. `#007a78`, `#ffffff`), RGB/RGBA, HSL, and un-tokenized Tailwind color classes (e.g. `bg-white`, `text-slate-900`, `border-red-200`) are prohibited in components.
 - **Variable Syntax**: All colors must use CSS custom properties defined in `src/app/globals.css` with semantic purpose:
   - **Brand & Clinical Accent**: `var(--clinical-accent)`, `var(--clinical-accent-hover)`, `var(--clinical-accent-soft)`, `var(--clinical-accent-border)`
-  - **Surfaces & Borders**: `var(--surface)`, `var(--surface-subtle)`, `var(--surface-wash)`, `var(--surface-lux)`, `var(--border)`, `var(--border-subtle)`
-  - **Text Roles**: `var(--text)`, `var(--text-muted)`, `var(--text-heading)`, `var(--text-soft)`
+  - **Surfaces & Borders**: `var(--surface)`, `var(--surface-subtle)`, `var(--surface-wash)`, `var(--surface-lux)`, `var(--border)`, `var(--border-strong)`, `var(--border-lux)`
+  - **Text Roles**: `var(--text)`, `var(--text-muted)`, `var(--text-heading)`. `--text-soft` is decoration (`--decoration-soft`), not a text role.
   - **Status & Safety Triads**: `--success-*`, `--warning-*`, `--danger-*`, `--info-*` (reserved exclusively for clinical/system status).
   - **Focus Ring & Outlines**: `var(--focus)` for all keyboard and visible focus rings.
 - **Raw Color Exemptions**: Strict and enumerated in `RAW_COLOR_EXEMPTIONS` in `scripts/design-system-contract-utils.mjs` (e.g., globals token definitions, brand mark SVG builder, diagnostic visualizations, OpenGraph art, printable patient/factsheet paper). Medication record accent defaults (`#0f766e` in `src/lib/medications.ts` and `src/lib/medication-records.ts`) are a **scoped** exemption for the Postgres `accent` column default only — not a whole-file blank cheque, and not a mapping onto `--clinical-accent`.
@@ -47,7 +47,7 @@ npm run check:icon-scale
 
 - **Elevation**: Monotonic numeric scale `var(--e0)` through `var(--e4)`. No raw `box-shadow` values.
 - **Edge Ownership**: Prohibits simultaneous `border-*` and `ring-*` styling on the same surface to prevent clipped or competing boundaries.
-- **Motion Durations**: Transitions and animations must use standardized duration tokens (`var(--duration-fast)`, `var(--duration-normal)`) and respect `motion-reduce:`. Layout-property animation (e.g., width, height, padding) is disallowed except for explicitly audited phone-chrome transitions.
+- **Motion Durations**: Transitions and animations must use standardized duration tokens (`var(--duration-fast)`, `var(--duration-base)`) and respect `motion-reduce:`. Layout-property animation (e.g., width, height, padding) is disallowed except for explicitly audited phone-chrome transitions.
 
 ---
 
diff --git a/docs/design-system/ADOPTION.md b/docs/design-system/ADOPTION.md
index 48c1667001..1a5a3fcb67 100644
--- a/docs/design-system/ADOPTION.md
+++ b/docs/design-system/ADOPTION.md
@@ -5,7 +5,7 @@ of truth is `adoption-contract.json`; the generated manifest and marked tables i
 must match it exactly.
 
 - **Date:** 12 August 2026
-- **Current state:** 54 visual references are locally registered; all 51 production page routes
+- **Current state:** 55 visual references are locally registered; all 51 production page routes
   are owned across 14 surface families, with 59 route/component roots scanned; every declared
   root uses the v2 shell and has declared proof with no committed visual baseline.
 - **Phase 1 blockers resolved first, in their own commits:** `#207` ungrounded `AnswerState`,
diff --git a/docs/design-system/COMPONENTS.md b/docs/design-system/COMPONENTS.md
index 1f29f11b69..ee117a0394 100644
--- a/docs/design-system/COMPONENTS.md
+++ b/docs/design-system/COMPONENTS.md
@@ -47,8 +47,9 @@ design-project publication or browser acceptance.
 _P1 reusable (specified in outline only):_ `Menu`/`Popover` · `KeyValue` ·
 `AppliedFilters`/`FilterSheet` · `ResponsiveActionGroup` · `ScrollableStrip`/
 `ScrollAffordance` · `SourceLink` · `Banner` · `CopyButton`/`CopyField` ·
-state family (`ErrorState`, `OfflineState`, `PermissionDeniedState`, `NotFoundState`,
-`UnavailableState`).
+state family (`OfflineState`, `PermissionDeniedState`, `NotFoundState`,
+`UnavailableState`). `ErrorState` is built (`src/components/ui/error-state.tsx`) and
+locally registered — it is not outline-only.
 
 `FilterBar` and `DataTable` are retired names, not future component contracts. Use a
 surface-owned filter pattern or the canonical `AccessibleTable`; do not revive either name.
diff --git a/docs/design-system/DECISIONS.md b/docs/design-system/DECISIONS.md
index 0ba432d847..dd8a28e5d7 100644
--- a/docs/design-system/DECISIONS.md
+++ b/docs/design-system/DECISIONS.md
@@ -147,7 +147,7 @@ source), flagged in SPEC §3 and cheap to veto mode-by-mode.
 
 ## C6 · Publication truth is source-derived; adoption truth is route-complete
 
-**Chose.** The local design-sync registry contains 53 visual exports. Each row is derived from
+**Chose.** The local design-sync registry contains 55 visual exports. Each row is derived from
 one real source file and requires an entry export, an exact TypeScript-checker-derived public
 `*Props` contract (or an explicit zero-prop root), a reference preview, and a direct publication
 test. `OverlayPortal`, `ToastProvider`, `useToast`, `AnswerState`, the answer helpers, and the
diff --git a/docs/design-system/FIX-GUIDE.md b/docs/design-system/FIX-GUIDE.md
index ea94c24453..e79ba118d0 100644
--- a/docs/design-system/FIX-GUIDE.md
+++ b/docs/design-system/FIX-GUIDE.md
@@ -20,7 +20,7 @@ mockup `min-h-11` or `--text-soft` body into production.
 
 ## Batch A — code this sweep
 
-Agents 1–3 land these. Parent verifies after merge; do not treat this table as a second
+Agents 1–3 landed these. Parent verifies after merge; do not treat this table as a second
 measurement of `globals.css` / `ckb-v2-tokens.css`.
 
 | ID       | Status | Rationale                                                                                                                                                      |
@@ -53,7 +53,7 @@ measurement of `globals.css` / `ckb-v2-tokens.css`.
 | DS-P3-02 | Documented | TOKENS already: `--tone-*` frozen, not deleted.                                                                                                                                             |
 | DS-P3-03 | Documented | TOKENS already: design-side `--quantity-unit-scale` never lands.                                                                                                                            |
 | DS-P3-04 | Documented | TOKENS already: ConfidenceMeter deferred; no token without a call site.                                                                                                                     |
-| DS-P3-05 | Documented | Registry has **55** registered visual exports. `DocumentFrame` is built shell-only and still unregistered. Register when print primitives ship (PR 11). Docs elsewhere may still say 53/54. |
+| DS-P3-05 | Documented | Registry has **55** registered visual exports. `DocumentFrame` is built shell-only and still unregistered. Register when print primitives ship (PR 11). |
 | DS-P3-07 | Documented | Full visual state matrix grows incrementally with new adoptions.                                                                                                                            |
 | DS-P3-08 | Documented | QA checklist: inspect the filter band at 414–430px. No code this sweep.                                                                                                                     |
 | DS-P3-09 | Documented | `#TYZK23` PWA install CLS already fixed (PR #2253). Regression-check note only; no speculative CSS.                                                                                         |
@@ -88,7 +88,7 @@ capture · `npm run ensure` unless a visual defect is proven.
 ## Residual risk (unchanged by docs)
 
 - Remaining production `border` + `inset` outside the specifier surfaces edited in DS-P2-13.
-- Lucide `size={15}` was ungated (`check:icon-scale` only bans `*-4.5`).
+- Lucide `size={N}` remains ungated except the DS-P1-16 `size={15}` sites already converted (`check:icon-scale` only bans `*-4.5`).
 - `--shadow-lift` still live (`mode-nav`, `document-search-results`).
 - Mockup `--text-soft` still blocks alias deletion.
 - Mockup `min-h-11` must stay mockup-only.
diff --git a/docs/design-system/GATES.md b/docs/design-system/GATES.md
index c2d75730a8..5972ac802c 100644
--- a/docs/design-system/GATES.md
+++ b/docs/design-system/GATES.md
@@ -73,14 +73,14 @@ because it contributed nothing.
 | #   | Gate                                                                                                                                          | Status                               | Evidence / path to blocking                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | --- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 1   | Contrast ≥4.5:1 for every text/background pair, both themes, live **and** v2; `--decoration-soft` asserted below 4.5 and never on a text node | **implemented-blocking**             | v2 pairs + `--text-placeholder` + `--decoration-soft` tier + recipe AST (`decoration-on-text.contract.test.ts`); live full matrix remains follow-on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| 2   | Tap targets ≥48px interactive; static pills never carry `min-h-tap`; no production target reduced                                             | **implemented-blocking for new use** | Enforced today: `--spacing-tap` is 48px and pinned from both sides (`ckb-v2-token-contract` asserts the `@theme` knob is ≥48 and that `--tap-min` is its alias), `ui-style-contract` measures the rendered floor for declared `min-height` carriers in Chromium, and the legacy-class / literal ratchets still run. **Still open for the `h-10` case, and 9 Aug 2026 measured why.** An enumeration of _rendered interactive_ elements was written, shown to find genuine defects, and then **reverted rather than landed**: it is not deterministic on this route. Six runs against one production build returned 6, 5, 4, 3, 3 and 9 distinct sub-floor shapes, largely disjoint — one run saw the answer-suggestion chips and a sort band, another the settled results list. `waitForLoadState("networkidle")` plus deduplication to distinct shapes did not fix it, and two consecutive agreeing runs turned out to be coincidence. This spec runs in the required `Production UI` job, so an intermittent version of it would block every merge in the repo; that is a worse outcome than the gap it closes. Path to blocking: give the audit a deterministic surface — a static route or a fixed seeded state — before re-attempting it. **What the enumeration did establish, in every one of the six runs, is a live defect:** controls that carry `min-h-tap` compute `min-height: 0px` and render at 16–36px, six distinct shapes in total. The declared-carrier audit cannot report them by construction — it only measures elements already computing at or above the floor, so a floor overridden downward is skipped rather than flagged. Tracked as `#293`. **Correction, same date — "`test:e2e:style-contract` is not part of `verify:cheap`" was true and badly misleading, and it sent one session looking for a wiring bug that does not exist.** The npm script is only a convenience alias for running this one spec; the spec matches `productionSpecPattern` in `playwright.config.ts` and is listed explicitly in `scripts/playwright-pr-shards.mjs`, so it already runs in the `Production UI` job that `pr-required` demands on any UI-scoped PR. It must **not** be added to `verify:cheap:internal`: `check:gate-manifest` requires every gate in that chain to also run in `static-pr`, which has no browser and no server. Per-surface geometry stays in the held visual harness. **Both named gaps are now closed, 15 Aug 2026.** The rendered enumeration landed first: `885c613` (PR #1962) added the deterministic phone-viewport `min-h-tap` audit this row was waiting on — `/forms`'s fixed-array home rather than a live-search route, polled until three consecutive reads agree, explicitly sorted, and asserted identical across three full navigate-and-enumerate cycles. The `h-10` case is closed here by `interactiveTapFloorDeclarations` in `check:design-system-contract`: an interactive element (`a`, `button`, `input`, `select`, `summary`, `textarea`) declaring its own **unprefixed** `min-h-*` below the 48px token. Comparable arbitrary lengths and mutually exclusive/composed class branches are evaluated independently, so one safe branch cannot hide a sub-floor runtime path. Ratcheted at **33** across 14 files with per-path pins, so a new sub-floor control anywhere in `src/**` fails today. Mutation-verified: lowering one shortlist button to `min-h-9` produces both the total and matching per-path regression. **Deliberately scoped to `min-h-*`, not `h-*`/`size-*`:** a short `h-4` on an interactive element is routinely the visible box of a control whose hit area is owned by a tap-sized wrapper (`SelectionCheckbox` in `differentials-home.tsx`, whose label `ui-smoke` asserts still meets the floor), so flagging those would pad the baseline with non-defects — the §5 failure mode. **One known limit, recorded rather than hidden:** the walker sees intrinsic lowercase tags only, so a floor declared on `<Link>` or another component wrapper is invisible to it (the pre-existing `legacyTapClasses` check has the same blind spot). The 33 recorded sites are real debt still owed, tracked in `#265`. |
+| 2   | Tap targets ≥48px interactive; static pills never carry `min-h-tap`; no production target reduced                                             | **implemented-blocking for new use** | Enforced today: `--spacing-tap` is 48px and pinned from both sides (`ckb-v2-token-contract` asserts the `@theme` knob is ≥48 and that `--tap-min` is its alias), `ui-style-contract` measures the rendered floor for declared `min-height` carriers in Chromium, and the legacy-class / literal ratchets still run. **Still open for the `h-10` case, and 9 Aug 2026 measured why.** An enumeration of _rendered interactive_ elements was written, shown to find genuine defects, and then **reverted rather than landed**: it is not deterministic on this route. Six runs against one production build returned 6, 5, 4, 3, 3 and 9 distinct sub-floor shapes, largely disjoint — one run saw the answer-suggestion chips and a sort band, another the settled results list. `waitForLoadState("networkidle")` plus deduplication to distinct shapes did not fix it, and two consecutive agreeing runs turned out to be coincidence. This spec runs in the required `Production UI` job, so an intermittent version of it would block every merge in the repo; that is a worse outcome than the gap it closes. Path to blocking: give the audit a deterministic surface — a static route or a fixed seeded state — before re-attempting it. **What the enumeration did establish, in every one of the six runs, is a live defect:** controls that carry `min-h-tap` compute `min-height: 0px` and render at 16–36px, six distinct shapes in total. The declared-carrier audit cannot report them by construction — it only measures elements already computing at or above the floor, so a floor overridden downward is skipped rather than flagged. Tracked as `#293`. **Correction, same date — "`test:e2e:style-contract` is not part of `verify:cheap`" was true and badly misleading, and it sent one session looking for a wiring bug that does not exist.** The npm script is only a convenience alias for running this one spec; the spec matches `productionSpecPattern` in `playwright.config.ts` and is listed explicitly in `scripts/playwright-pr-shards.mjs`, so it already runs in the `Production UI` job that `pr-required` demands on any UI-scoped PR. It must **not** be added to `verify:cheap:internal`: `check:gate-manifest` requires every gate in that chain to also run in `static-pr`, which has no browser and no server. Per-surface geometry stays in the held visual harness. **Both named gaps are now closed, 15 Aug 2026.** The rendered enumeration landed first: `885c613` (PR #1962) added the deterministic phone-viewport `min-h-tap` audit this row was waiting on — `/forms`'s fixed-array home rather than a live-search route, polled until three consecutive reads agree, explicitly sorted, and asserted identical across three full navigate-and-enumerate cycles. The `h-10` case is closed here by `interactiveTapFloorDeclarations` in `check:design-system-contract`: an interactive element (`a`, `button`, `input`, `select`, `summary`, `textarea`) declaring its own **unprefixed** `min-h-*` below the 48px token. Comparable arbitrary lengths and mutually exclusive/composed class branches are evaluated independently, so one safe branch cannot hide a sub-floor runtime path. Ratcheted at **32** across 13 files with per-path pins, so a new sub-floor control anywhere in `src/**` fails today. Mutation-verified: lowering one shortlist button to `min-h-9` produces both the total and matching per-path regression. **Deliberately scoped to `min-h-*`, not `h-*`/`size-*`:** a short `h-4` on an interactive element is routinely the visible box of a control whose hit area is owned by a tap-sized wrapper (`SelectionCheckbox` in `differentials-home.tsx`, whose label `ui-smoke` asserts still meets the floor), so flagging those would pad the baseline with non-defects — the §5 failure mode. **One known limit, recorded rather than hidden:** the walker sees intrinsic lowercase tags only, so a floor declared on `<Link>` or another component wrapper is invisible to it (the pre-existing `legacyTapClasses` check has the same blind spot). The 32 recorded sites are real debt still owed, tracked in `#265`. |
 | 3   | Focus outline present, `--focus`, no companion ring                                                                                           | **planned**                          | Corrected 6 Aug 2026: the previous evidence ("`--focus` is referenced nowhere in the DS export", finding N3) was false — **[verified: grep]** 4 declarations (2 theme, 2 forced-colours) against **273** `var(--focus)` consumers, 260 of them in `.tsx`. The token is adopted; the check is what is missing. Path to blocking: assert a visible focus outline on every interactive role and reject a `ring-*` companion on the same node. A row that understates shipped work costs the document its authority as surely as one that overstates it, and nobody files a bug against pessimism.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | 4   | Non-colour encoding on every status indicator                                                                                                 | **implemented-blocking**             | `colourOnlyStatusIndicators` scans production class roots and shared swatch recipes. The remaining calculator spectrum and shared status-marker debt was retired on 22 Aug 2026: severity bands now add distinct neutral edge patterns, ready/review/muted markers differ by outline/fill/geometry, and visible labels remain at call sites. The metric and per-path baseline are pinned at **0**; `StatusMark`, persistent text, and decoration-only `--decoration-soft` retain their documented roles.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | 5   | Tables: semantic caption, associated headers, `aria-controls` on the expander                                                                 | **implemented-blocking**             | `AccessibleTableProps.caption` is required; DOM and alignment tests prove the semantic `<caption>`, associated headers, and expander relationship.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | 6   | Enum resilience — neutral fallback, never throws                                                                                              | **implemented-blocking**             | `source-badges-off-vocab.dom.test.tsx`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | 7   | Elevation monotonicity — no child heavier than its parent                                                                                     | **implemented-partial**              | Token-ramp monotonicity is tested; the per-surface child/parent rule is planned (needs a render-tree check).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| 8   | Edge ownership — no `border-*` + `ring-*` on one surface; no 1px spread in a drop shadow                                                      | **implemented-partial**              | Corrected 9 Aug 2026: the previous evidence — "the per-surface co-occurrence lint and spread-term check are planned (PR 9)" — was **false**, and had been since before this row was written. Both ship. `edgeOwnershipConflicts` is an AST co-occurrence check over resolved class roots (`BORDER_WIDTH_UTILITY` × `RING_WIDTH_UTILITY`), and `onePixelShadowSpreads` reads the fourth length of every `box-shadow` layer. Both ratchet **per path**, so a new conflict on any surface fails today. What is partial is the recorded debt, not the check: **18 conflicts across 9 files**, and 0 spreads in `globals.css`. (Corrected 15 Aug 2026 — this cell said 27 across 15, which PR #1942 had already paid down to 25 across 12 without updating the prose. The §3 row below and `scripts/design-system-contract-baseline.json` both already said 25, and per `docs/design-system/README.md` the baseline outranks this document, so the prose was the defect. Ledger `#265` carried the same stale figure.) Path to blocking: retire that debt and pin both at zero. The spread form was chosen _because_ it is mechanically lintable, and it duly was.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| 9   | No layout-property animation; no hardcoded durations                                                                                          | **implemented-partial**              | Corrected 9 Aug 2026: "a layout-property lint is still planned" was **false**, and leaving it would have preserved the exact contradiction this pass exists to remove. `layoutTransitionExceptions` ships and ratchets **per path** against `SAFE_TRANSITION_PROPERTIES`, so a new layout-property transition in any file fails today; the phone chrome's intentional `grid-template-rows` / `height` / `padding-bottom` are among the 11 recorded exceptions rather than a gap. The Tailwind duration form is a **hard zero** (`hardcodedMotionClasses`), on top of PR-Arch tokenising production `duration-*`/`ease-*` literals onto `--duration-*` / `--ease-*` (Gate 10). What stays partial is recorded debt, not a missing check: 11 layout transitions and 41 CSS `hardcodedCssMotionDurations`. Path to blocking: retire those and pin both at zero.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| 8   | Edge ownership — no `border-*` + `ring-*` on one surface; no 1px spread in a drop shadow                                                      | **implemented-partial**              | Corrected 9 Aug 2026: the previous evidence — "the per-surface co-occurrence lint and spread-term check are planned (PR 9)" — was **false**, and had been since before this row was written. Both ship. `edgeOwnershipConflicts` is an AST co-occurrence check over resolved class roots (`BORDER_WIDTH_UTILITY` × `RING_WIDTH_UTILITY`), and `onePixelShadowSpreads` reads the fourth length of every `box-shadow` layer. Both ratchet **per path**, so a new conflict on any surface fails today. What is partial is the recorded debt, not the check: **16 conflicts across 7 files**, and 0 spreads in `globals.css`. (Corrected 15 Aug 2026 — this cell said 27 across 15, which PR #1942 had already paid down to 25 across 12 without updating the prose. The §3 row below and `scripts/design-system-contract-baseline.json` both already said 25, and per `docs/design-system/README.md` the baseline outranks this document, so the prose was the defect. Ledger `#265` carried the same stale figure.) Path to blocking: retire that debt and pin both at zero. The spread form was chosen _because_ it is mechanically lintable, and it duly was.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| 9   | No layout-property animation; no hardcoded durations                                                                                          | **implemented-partial**              | Corrected 9 Aug 2026: "a layout-property lint is still planned" was **false**, and leaving it would have preserved the exact contradiction this pass exists to remove. `layoutTransitionExceptions` ships and ratchets **per path** against `SAFE_TRANSITION_PROPERTIES`, so a new layout-property transition in any file fails today; the phone chrome's intentional `grid-template-rows` / `height` / `padding-bottom` are among the 11 recorded exceptions rather than a gap. The Tailwind duration form is a **hard zero** (`hardcodedMotionClasses`), on top of PR-Arch tokenising production `duration-*`/`ease-*` literals onto `--duration-*` / `--ease-*` (Gate 10). What stays partial is recorded debt, not a missing check: 11 layout transitions and 42 CSS `hardcodedCssMotionDurations`. Path to blocking: retire those and pin both at zero.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | 10  | Named z and motion tokens have real consumers; no unapproved `z-` value                                                                       | **implemented-blocking**             | PR-Arch: off-ladder `z-50` retired; toast at `--z-toast` (`z-[110]`, lint allowlist); motion literals map to named duration/ease tokens including phone-chrome hide/reveal pair. Dead `OverlayProvider` deleted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | 11  | Published-type conformance — every `dtsPropsFor` entry exactly matches source props                                                           | **implemented-blocking**             | `generate-design-sync-contract.mjs` uses the TypeScript checker to derive every public property from the exported source `*Props` type; `--check` and `check-design-sync-contract.mjs` reject drift, missing named types, or machine-specific declarations. Zero-prop visual roots are explicit.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | 12  | Publication coverage — every registered visual component has source, export, preview, prop contract and direct publication test               | **implemented-blocking**             | Registry/map/props parity and all 55 direct component rows are pinned by the design-sync contract and `design-sync-visual-exports.test.ts`. Behavioural, full visual-state, print, and browser acceptance remain separate gates; `DocumentFrame` is built shell-only in product but not yet among the 55 registered visual exports (print primitives remain specified-not-built).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
@@ -111,15 +111,15 @@ theme-list parity, and remote design-project publication remain separate concern
 | Put `--decoration-soft`/`--text-soft` on a text node                 | Tier pinned both sides in the token contract; recipe AST (`decoration-on-text.contract.test.ts`)                                                                   | implemented-blocking (recipes); broader AST follow-on                                                                                                                                                                                                                                                                                                      |
 | Uppercase a dose unit                                                | `Quantity` pins `normal-case` + unit test                                                                                                                          | implemented-blocking (branch)                                                                                                                                                                                                                                                                                                                              |
 | Invert a PDF, diagram or clinical image in any theme                 | `check:design-system-contract` — `imageInversions`, pinned at **zero**, not ratcheted                                                                              | **implemented-blocking** (9 Aug 2026) — CSS `filter`/`backdrop-filter` plus the Tailwind `invert`/`hue-rotate` utilities; see §5                                                                                                                                                                                                                           |
-| Border **and** ring on one surface, or a 1px spread in a drop shadow | `check:design-system-contract` — `edgeOwnershipConflicts` (18) + `onePixelShadowSpreads` (0)                                                                       | **implemented-blocking for new use** — AST/CSS ratchets with per-path pins; the recorded debt itself is Gate 8's remaining half                                                                                                                                                                                                                            |
+| Border **and** ring on one surface, or a 1px spread in a drop shadow | `check:design-system-contract` — `edgeOwnershipConflicts` (16) + `onePixelShadowSpreads` (0)                                                                       | **implemented-blocking for new use** — AST/CSS ratchets with per-path pins; the recorded debt itself is Gate 8's remaining half                                                                                                                                                                                                                            |
 | A child shadow heavier than its parent's                             | Gate 7                                                                                                                                                             | implemented-partial                                                                                                                                                                                                                                                                                                                                        |
-| Use `--shadow-tight`/any alias in new code                           | `check:design-system-contract` — `legacyShadowAliases`, ratcheted at 89 with per-path pins                                                                         | **implemented-blocking for new use** — a new alias in any file fails. `--shadow-tight` itself is retired onto `--e1` and additionally pinned by a tracked-tree sweep in `tests/design-token-contract.test.ts` (it was silently reverted once by the `acf78bf` merge); the remaining 89 are the other six aliases, still `#262`                             |
-| Raw pixel size, padding, radius, gap or line-height in markup        | `check:design-system-contract` — `rawPaddingLiterals` (52), `rawRadiusLiterals` (20), `rawGapLiterals` (25), `rawMarginLiterals` (74), `rawLineHeightLiterals` (0) | **implemented-blocking for new use** (9 Aug 2026) — per-path ratchets over both the utility and the CSS-declaration spelling, so a literal cannot move into `globals.css` to escape. Values containing a CSS function (`env(`, `clamp(`, `max(`, `calc(`) are sanctioned computed forms and exempt. Raw _size_ is still covered only for tap/shadow/colour |
+| Use `--shadow-tight`/any alias in new code                           | `check:design-system-contract` — `legacyShadowAliases`, ratcheted at 87 with per-path pins                                                                         | **implemented-blocking for new use** — a new alias in any file fails. `--shadow-tight` itself is retired onto `--e1` and additionally pinned by a tracked-tree sweep in `tests/design-token-contract.test.ts` (it was silently reverted once by the `acf78bf` merge); the remaining 87 are the other six aliases, still `#262`                             |
+| Raw pixel size, padding, radius, gap or line-height in markup        | `check:design-system-contract` — `rawPaddingLiterals` (42), `rawRadiusLiterals` (20), `rawGapLiterals` (20), `rawMarginLiterals` (53), `rawLineHeightLiterals` (0) | **implemented-blocking for new use** (9 Aug 2026) — per-path ratchets over both the utility and the CSS-declaration spelling, so a literal cannot move into `globals.css` to escape. Values containing a CSS function (`env(`, `clamp(`, `max(`, `calc(`) are sanctioned computed forms and exempt. Raw _size_ is still covered only for tap/shadow/colour |
 | Animate `width`, `height`, `grid-template-*`, `top`, `left`, `gap`   | `check:design-system-contract` — `layoutTransitionExceptions`, ratcheted at 11 with per-path pins                                                                  | **implemented-blocking for new use** — `SAFE_TRANSITION_PROPERTIES` carries the compositor-only allowlist; phone chrome's deliberate `grid-template-rows` is in the recorded 11                                                                                                                                                                            |
-| Hardcode a transition duration                                       | `check:design-system-contract` — `hardcodedMotionClasses` (**zero**) + `hardcodedCssMotionDurations` (41)                                                          | **implemented-blocking** for the Tailwind `duration-*`/`delay-*`/`transition-all` form; the CSS form is a ratchet, so its 41 are debt                                                                                                                                                                                                                      |
+| Hardcode a transition duration                                       | `check:design-system-contract` — `hardcodedMotionClasses` (**zero**) + `hardcodedCssMotionDurations` (42)                                                          | **implemented-blocking** for the Tailwind `duration-*`/`delay-*`/`transition-all` form; the CSS form is a ratchet, so its 42 are debt                                                                                                                                                                                                                      |
 | A `z-[N]` literal outside the named rungs, in JS/TS only             | `require-z-index-ladder` (ESLint)                                                                                                                                  | implemented-blocking. Scope: `z-[N]` literals in JS/TS AST nodes. Plain `z-30` utilities and every `.css` / `.module.css` declaration are invisible to an ESLint rule - `sidebar-live-shell.module.css` carries an off-ladder `z-index: var(--z-sidebar-flyout, 50)` this cannot see.                                                                      |
 | Ship a registered component without a direct publication test        | Gate 12                                                                                                                                                            | implemented-blocking                                                                                                                                                                                                                                                                                                                                       |
-| Lower a production tap target below 48px                             | `check:design-system-contract` — `interactiveTapFloorDeclarations` (33) + Gate 2's phone-viewport `ui-style-contract` audit + `ui-smoke` flake history             | **implemented-blocking for new use** (15 Aug 2026) — a new interactive control declaring a sub-floor `min-h-*`, including comparable arbitrary values and any reachable conditional branch, fails on both the total and its own path; the 33 recorded sites remain debt. Component-wrapper tags such as `<Link>` are a known blind spot                    |
+| Lower a production tap target below 48px                             | `check:design-system-contract` — `interactiveTapFloorDeclarations` (32) + Gate 2's phone-viewport `ui-style-contract` audit + `ui-smoke` flake history             | **implemented-blocking for new use** (15 Aug 2026) — a new interactive control declaring a sub-floor `min-h-*`, including comparable arbitrary values and any reachable conditional branch, fails on both the total and its own path; the 32 recorded sites remain debt. Component-wrapper tags such as `<Link>` are a known blind spot                    |
 | Construct an enabled control with no action, destination or name     | PR 4 discriminated unions + DOM contracts; `require-button-wiring` covers raw `<button>`                                                                           | implemented-blocking (Citation/Chip/ToggleSwitch/RadioGroup)                                                                                                                                                                                                                                                                                               |
 | Render `AnswerCard` without a verification and answer state          | PR 6 required props (type-level)                                                                                                                                   | implemented-blocking in `AnswerCard`; live answer-shell adoption remains compatibility-layer work                                                                                                                                                                                                                                                          |
 | Use a bare dash for a missing clinical value                         | `MissingValue` + review                                                                                                                                            | implemented-partial — `AccessibleTable` composes `MissingValue`; broader legacy call-site convergence remains manual                                                                                                                                                                                                                                       |
@@ -187,7 +187,7 @@ Recorded at export (31 July 2026), **not re-run for this document set**:
   `tests/installed-lock-parity.test.ts`, environmental (`brace-expansion` lock drift, issue
   `#149`, fixed by `npm ci`), pre-existing and unrelated
 - `npm run verify:ui` — **344 passed**, exit 0
-- `check:design-system-contract` — pass: 625 production files, raw colours 2, literal
+- `check:design-system-contract` — pass: 625 production files, raw colours 0, literal
   shadows 0, legacy tap classes 0
 
 The honest sentence includes the failure. Exit code 0 alone is never proof — quote the
diff --git a/docs/design-system/SPEC.md b/docs/design-system/SPEC.md
index 143e140a99..eb9bb3b5d3 100644
--- a/docs/design-system/SPEC.md
+++ b/docs/design-system/SPEC.md
@@ -667,18 +667,19 @@ and adoption.** Status keys as in the header; "done" entries cite their commit.
 
 | PR                                | Contents                                                                                                      | Status                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | --------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| PR 5a · Token values, no geometry | Colour, elevation, ink roles                                                                                  | **done** — `59e4c3dfc` landed the `--shadow-well` rename, the spine and status-mark families, and the dark `--clinical-chat-document` fix; the remaining ink-role deltas landed with PR 3 (`--text-placeholder`, eyebrows and placeholders off the decoration tier, the disabled encoding). The v2 light and dark blocks now declare the same colour roles, and the only raw colour literals left in `src/` are the two `#0f766e` accent defaults, which are **not** design tokens — see the note below |
+| PR 5a · Token values, no geometry | Colour, elevation, ink roles                                                                                  | **done** — `59e4c3dfc` landed the `--shadow-well` rename, the spine and status-mark families, and the dark `--clinical-chat-document` fix; the remaining ink-role deltas landed with PR 3 (`--text-placeholder`, eyebrows and placeholders off the decoration tier, the disabled encoding). The v2 light and dark blocks now declare the same colour roles. The two `#0f766e` accent defaults are scoped `RAW_COLOR_EXEMPTIONS`, so `rawColorLiterals` is **0** — they are data, not design tokens; see the note below |
 | PR 5b · Tap 44→48 in `@theme`     | The 426-site tap-call-site migration; contract-test pin update; visual QA pass; `--tap-min` becomes the alias | **done** — `--spacing-tap: 3rem` in `@theme`; `--tap-min` reduced to `var(--spacing-tap)`; 426 `*-tap` call sites moved; three pins flipped in the same commit; the phone composer keeps a written 44px exception below 431px (§4.10)                                                                                                                                                                                                                                                                   |
 | PR 5c · Radius step               | Every `rounded-md` moves; its own visual diff                                                                 | **done** — live `@theme --radius-md` 8px → 10px, matching the v2 control rung and moving 243 `rounded-md` call sites; the 4px-grid pin now names both half-steps and asserts the two layers agree; 14 arbitrary radius literals absorbed onto the ladder (§4.6)                                                                                                                                                                                                                                         |
 
-**`#0f766e` is data, not a token.** The two remaining raw colour literals
+**`#0f766e` is data, not a token.** The two `#0f766e` accent defaults
 (`src/lib/medications.ts`, `src/lib/medication-records.ts`) restate a Postgres column
 default (`accent text not null default '#0f766e'`) for a per-record, user-chosen accent
 colour. Changing the application default without migrating the database default would
-diverge the two, so both stay. The raw-colour ratchet in
-`scripts/design-system-contract-baseline.json` is a **ceiling, not a target**: it exists to
-stop new literals appearing, and a value that is persisted data rather than design intent
-is outside the token system entirely.
+diverge the two, so both stay. They are a **scoped** `RAW_COLOR_EXEMPTIONS` entry, not
+remaining debt: `scripts/design-system-contract-baseline.json` pins `rawColorLiterals`
+at **0**. The ratchet is a **ceiling, not a target**: it exists to stop new literals
+appearing, and a value that is persisted data rather than design intent is outside the
+token system entirely.
 
 ### Phase 3 — safety structure
 
diff --git a/docs/design-system/TOKENS.md b/docs/design-system/TOKENS.md
index c6e63579c8..a6db7f10d4 100644
--- a/docs/design-system/TOKENS.md
+++ b/docs/design-system/TOKENS.md
@@ -47,7 +47,7 @@ Declared in the `.ckb-v2` structural block **[verified: full read at `ef13a072a`
 | Semantic gaps    | `--gap-tight` · `--gap-inline` · `--gap-stack` · `--gap-block` · `--gap-section`                                                          | The only inter-element spacing markup may use.                                                                                                                                                                                                                                                 |
 | Semantic padding | `--pad-chip-x` · `--pad-control-x` · `--pad-cta-x` · `--pad-card` · `--pad-panel` · `--pad-strip`                                         | Heading-inset convention rides on these (SPEC §4.6).                                                                                                                                                                                                                                           |
 | Page             | `--page-gutter` · `--page-max` · `--measure` · `--header-h`                                                                               | `--measure` is the prose measure — never wider.                                                                                                                                                                                                                                                |
-| Type steps       | `--text-{xs,sm,body,md,lg,xl}` · `--text-hero` · `--text-hero--line-height` · `--text-hero-tr`                                            | Seven steps. Shared `--leading-prose`; hero keeps `--text-hero--line-height` / `--text-hero-tr` (gated). Unused xs–xl `-lh`/`-tr` companions are orphans — do not re-require them. ⚠️ `--text-hero--line-height` is the one double-dash name — keep as-is; renaming is churn without a defect. |
+| Type steps       | `--text-{xs,sm,body,md,lg,xl}` · `--text-hero` · `--text-hero--line-height` · `--text-hero-tr`                                            | Seven steps. Shared `--leading-prose`; hero keeps `--text-hero--line-height` / `--text-hero-tr` (gated). Unused xs–xl `-lh`/`-tr` and `--text-{step}--line-height` companions are orphans — do not re-require them. ⚠️ `--text-hero--line-height` is the one double-dash name — keep as-is; renaming is churn without a defect. |
 | Chip sizes       | `Chip` `compact` → `--text-2xs` (legacy compat step); `standard` (default) → `--text-xs`                                                  | Canonical (#220): dense surfaces opt into `size="compact"`; default adoption keeps `--text-xs`. `--text-2xs` stays a compatibility alias for Chip compact / legacy call sites — not a new v2 type step to invent against. Do not densify every Chip to chase the globals “small chips” note.   |
 | Type companions  | `--leading-prose` · `--tracking-eyebrow` · `--nums`                                                                                       | `--nums` = numeric variant for all data.                                                                                                                                                                                                                                                       |
 | Weights          | `--font-weight-{body,label,heading,value}`                                                                                                | One job each; display uses heading weight (SPEC §4.6).                                                                                                                                                                                                                                         |
@@ -112,10 +112,10 @@ The v2 layer _references_ or _depends on_ these; their values stay in `live` / `
 | Token                                                                                                               | Disposition                                                                                                                                                                                                                                                                                                | Gate                                                                                                                                   |
 | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
 | `--text-soft`                                                                                                       | Deprecated alias of `--decoration-soft`; both resolve identically during the window. Delete when zero references remain outside the alias declaration.                                                                                                                                                     | Contract test pins the tier from both sides; a lint for `--text-soft`/`--decoration-soft` on text-bearing nodes is planned (GATES §1). |
-| `--shadow-focus`                                                                                                    | **Delete** (PR 9) — encodes a companion focus ring the conventions forbid; a trap for the next person who greps "focus".                                                                                                                                                                                   | Planned lint after deletion.                                                                                                           |
-| `--shadow-lift`                                                                                                     | Retire into the `--eN` ladder (PR 9).                                                                                                                                                                                                                                                                      | Planned.                                                                                                                               |
-| `--shadow-card`, `--shadow-soft`                                                                                    | Aliases of a ladder step; retire **inside the recipes first**, then delete.                                                                                                                                                                                                                                | Planned.                                                                                                                               |
-| `--spring-bouncy` + two other dead springs                                                                          | Delete (PR 9); byte-duplicate and unused curves.                                                                                                                                                                                                                                                           | Planned.                                                                                                                               |
+| `--shadow-focus`                                                                                                    | **Deleted** — encoded a companion focus ring the conventions forbid. Focus is an outline, not a ring.                                                                                                                                                                  | Gated gone by `tests/design-token-contract.test.ts`.                                                                                   |
+| `--shadow-lift`                                                                                                     | Retire into the `--eN` ladder (PR 9). Still has live consumers — do not delete until those move.                                                                                                                                                                        | Planned.                                                                                                                               |
+| `--shadow-card`, `--shadow-soft`                                                                                    | Aliases of a ladder step; retire **inside the recipes first**, then delete.                                                                                                                                                                                                | Planned.                                                                                                                               |
+| `--spring-bouncy` + two other dead springs                                                                          | **Deleted** (2026-08-21) — unused curves. `--ease-spring` remains.                                                                                                                                                                                                        | Done.                                                                                                                                  |
 | `--quantity-unit-scale` (design side)                                                                               | Never lands; superseded per §1.                                                                                                                                                                                                                                                                            | Next design sync removes it.                                                                                                           |
 | Legacy type steps (`text-2xs`/`3xs`, `sm-minus`, `base-minus`, `2xl-minus`, `lg-minus`, `3xl-minus`, `3xl/4xl/5xl`) | Retired **last of all** — ≈663 call sites; `--text-md` arrives additively first. ⚠️ `Quantity` currently consumes `text-base-minus` — fix in the retirement tranche. `--text-2xl-compact` left this list early (`#297`): it had zero consumers, so retiring it needed no tranche and rendered identically. | Contract ratchet extension, planned.                                                                                                   |
 
diff --git a/docs/process-hardening.md b/docs/process-hardening.md
index 1124dc6269..3904585a72 100644
--- a/docs/process-hardening.md
+++ b/docs/process-hardening.md
@@ -648,7 +648,7 @@ passes `p_worker_id`. Ordered apply steps, R17 manual `CONCURRENTLY` index, and
 
 ## Design convergence & type-scale ratchet (2026-07-06)
 
-- **`docs/design-system.md` is now the front door** for all UI work: token contract, type-scale rules, z-index ladder, Sheet-only modals, a11y requirements, and the UI Definition of Done. The `docs/redesign/*` documents remain the deep references it links to.
+- **`docs/design-system/README.md` is now the front door** for all UI work: token contract, type-scale rules, z-index ladder, Sheet-only modals, a11y requirements, and the UI Definition of Done. [`docs/design-system.md`](./design-system.md) remains live-layer notes during the v1→v2 transition. The `docs/redesign/*` documents remain the deep references they link to.
 - **Type-scale ratchet — backlog cleared, gate now strict:** `node scripts/check-type-scale.mjs --strict` reports **0 hits / 0 files** (this pass retires the last 8 hits in 1 file; the prior recorded baseline was 20/9, originally 168/22). The compact mode-home hero now uses the shared fluid `--text-hero` scale; the temporary mode-home-only aliases were removed after confirming no consumers remained. `check:type-scale --strict` is wired into `verify:cheap` (package.json), so any newly introduced arbitrary `text-[<n>px|rem|em]` size now fails the gate — UI PRs must keep the count at zero. Colour utilities (`text-[color:var(--…)]`) are the sanctioned token form and are not counted.
 - **Cleared this pass:** dead launcher mobile detail rows now expand (aria-expanded disclosures); launcher detail dialog migrated to the `Sheet` primitive (focus trap/return-focus restored); launcher filter tablists gained `aria-controls` + a `role="tabpanel"` results region; styled `src/app/not-found.tsx` added (the `notFound()` calls in differentials no longer fall through to the unstyled default); `?page=abc` NaN leak in the document viewer clamped; `/services` off-palette preview deleted (dead export) and the live navigator's residual hardcodes tokenized; launcher icon tones moved from raw Tailwind palette classes to categorical `--type-*` / semantic danger triads (dark-mode + forced-colors correct); mockups layout emits `robots: noindex`.
 
diff --git a/docs/scripts-index.md b/docs/scripts-index.md
index a508e866f2..c6b9af14f3 100644
--- a/docs/scripts-index.md
+++ b/docs/scripts-index.md
@@ -49,7 +49,12 @@ migration has shipped (see `docs/maturity-backlog-workorders.md` L1).
 `check-maintainability-budgets.mjs`, `check-upload-limit-parity.mjs`,
 `check-codebase-index-coverage.mjs`, `check-docs-links.mjs`,
 `check-docs-script-refs.mjs`, `check-bundle-budget.mjs`, `check-type-scale.mjs`,
-`check-icon-scale.mjs`, `check-design-system-contract.mjs`, `check-function-grants.mjs`,
+`check-icon-scale.mjs`, `check-design-system-contract.mjs`,
+`generate-design-system-adoption.mjs` (`npm run design-system:adoption:update` /
+`check:design-system-adoption`), `generate-design-sync-contract.mjs` +
+`check-design-sync-contract.mjs` (`npm run design-system:design-sync:update` /
+`check:design-sync-contract`), `adopt-visual-baselines.mjs`
+(`npm run design-system:baselines:adopt`), `check-function-grants.mjs`,
 `check-owner-scope-api.mjs`, `check-client-bundle-secrets.mjs`, `verify-pr-local.mjs`,
 `verify-release-offline.mjs`, `check-codex-cloud-setup.mjs`. `check-gate-manifest.mjs` cross-checks that every gate in the
 `verify:cheap:internal` chain also runs in CI's `static-pr` job, so the two lists can't drift.
diff --git a/docs/testing.md b/docs/testing.md
index 44ac18ea5c..7dcda78932 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -430,10 +430,10 @@ The scheduled `release-browser-matrix` workflow provides cross-engine regression
 Before opening a UI PR, confirm:
 
 - **Reuse first.** Check `src/components/ui-primitives.tsx` (class recipes plus `IconButton`, `AsyncButton`, `InlineNotice`, `EmptyState`, `LoadingPanel`, `ToggleSwitch`) and `src/components/ui/sheet.tsx` (the only overlay primitive) before hand-rolling. Icon-only buttons use `IconButton` (its `label` is a required prop).
-- **Tokens only.** No raw hex or Tailwind palette classes, no literal shadows, no `text-[Npx]` — see [`docs/design-system.md`](./design-system.md) §1–§5. `check:design-system-contract`, `check:type-scale`, and `check:icon-scale` enforce this.
+- **Tokens only.** No raw hex or Tailwind palette classes, no literal shadows, no `text-[Npx]` — see [`docs/design-system/README.md`](./design-system/README.md). `check:design-system-contract`, `check:type-scale`, and `check:icon-scale` enforce this.
 - **States.** Handle loading / empty / error / disabled where they apply; async surfaces expose a retry, not a dead end.
-- **Accessibility** ([design-system §7](./design-system.md)): keyboard operable, visible focus, accessible names on icon controls, live regions for async status, and reduced motion honoured — scripted `scrollTo`/`scrollIntoView` go through `resolveScrollBehavior` (`src/lib/scroll-behavior.ts`), never a hard-coded `behavior: "smooth"`.
+- **Accessibility** ([design-system](./design-system/README.md)): keyboard operable, visible focus, accessible names on icon controls, live regions for async status, and reduced motion honoured — scripted `scrollTo`/`scrollIntoView` go through `resolveScrollBehavior` (`src/lib/scroll-behavior.ts`), never a hard-coded `behavior: "smooth"`.
 - **Tests.** Add a `.dom.test.tsx` for changed component behaviour (see "Component tests" above) and update the E2E journeys for changed flows.
 - **Unlayered CSS.** If the change adds a class rule outside `@layer` that sets a border, background, colour, shadow or outline, `tests/style-contract-registry.test.ts` will fail until it is registered. Add a rendered-effect contract rather than an exemption where the rule matters visually — see "Visual regression and style contracts".
-- **Verify** ([design-system §9](./design-system.md)): follow the risk tiers in root `AGENTS.md`. Prove changed component behaviour with the focused DOM test first; run `npm run ensure` before browser work and use the narrowest affected journey. Select one appropriate broad handoff gate when the diff crosses owners, cannot be bounded, or applicable PR/handoff policy requires it; do not routinely stack `verify:cheap`, `verify:pr-local`, and `verify:ui`. Add a manual dark-mode + forced-colors spot check when those rendered states can plausibly change.
+- **Verify** ([design-system](./design-system/README.md) and GATES): follow the risk tiers in root `AGENTS.md`. Prove changed component behaviour with the focused DOM test first; run `npm run ensure` before browser work and use the narrowest affected journey. Select one appropriate broad handoff gate when the diff crosses owners, cannot be bounded, or applicable PR/handoff policy requires it; do not routinely stack `verify:cheap`, `verify:pr-local`, and `verify:ui`. Add a manual dark-mode + forced-colors spot check when those rendered states can plausibly change.
 - Architecture and state-ownership conventions: [`docs/frontend-architecture.md`](./frontend-architecture.md).
diff --git a/src/app/globals.css b/src/app/globals.css
index 8a05fe9424..4be8efa107 100644
--- a/src/app/globals.css
+++ b/src/app/globals.css
@@ -4,8 +4,9 @@
    the shared render-blocking stylesheet without changing mockup rendering. */
 @source not "./mockups";
 @source not "../components/**/*mockup*";
-/* Opt-in v2 design-system token layer. Every rule is scoped to `.ckb-v2`, so
-   importing it cannot change any surface that does not carry the class. */
+/* Opt-in v2 design-system token layer. Every rule is scoped to `.ckb-v2`.
+   Production mounts that class on `<html>` (`src/app/layout.tsx`), so the
+   layer is opted in at the document root rather than per subtree. */
 @import "./ckb-v2-tokens.css";
 
 @custom-variant dark (&:where(.dark, .dark *));
@@ -241,7 +242,7 @@
      --leading-tight/-snug/-normal/-relaxed; these do NOT redefine those (that
      would silently retune every existing leading-tight/leading-snug call site).
        leading-display  1.05  large display headings — hero/mode-home/detail h1
-       leading-prose    1.6   the max-w-[68ch] body measure */
+       leading-prose    1.65  the max-w-[68ch] body measure */
   --leading-display: 1.05;
   --leading-prose: 1.65;
 
@@ -2176,6 +2177,7 @@ summary::-webkit-details-marker {
   padding-inline: 0.35rem;
   font-size: 16px;
   font-weight: 560;
+  /* Hero companion on this 16px field is deliberate coupling (DS-P2-12). */
   line-height: var(--text-hero--line-height);
   letter-spacing: 0;
 }
diff --git a/src/components/therapy-compass/screens/brief-screen.tsx b/src/components/therapy-compass/screens/brief-screen.tsx
index 817a0f5fbd..8f231bc184 100644
--- a/src/components/therapy-compass/screens/brief-screen.tsx
+++ b/src/components/therapy-compass/screens/brief-screen.tsx
@@ -10,11 +10,12 @@ import { Button } from "@/components/ui/button";
 import { Tabs } from "@/components/ui/tabs";
 import { BrowserPrintButton, PrintOutput } from "@/components/ui/print-output";
 import { cn } from "@/components/ui-primitives";
-import { therapyRecordHref } from "@/lib/therapy-compass-navigation";
+import { therapyRecordHref, type TherapyBriefDuration } from "@/lib/therapy-compass-navigation";
 
 import { useTcBindings } from "../bindings";
 import { InteractiveRow } from "@/components/ui/interactive-row";
 import { parseSteps, summarise } from "../data/select";
+import type { Therapy } from "../data/types";
 import { LoadingState } from "../ui";
 import { useClipboard } from "../use-clipboard";
 import { TherapyCompareAction } from "../record/compare-action";
@@ -29,6 +30,20 @@ const CHECKLIST = [
   "Confirm patient-facing language",
 ];
 
+const BRIEF_DURATION: Record<TherapyBriefDuration, { label: string; text: (therapy: Therapy) => string | null }> = {
+  "5min": { label: "5-minute", text: (therapy) => therapy.briefVersion },
+  "15min": {
+    label: "15-minute",
+    text: (therapy) => therapy.fifteenMinuteVersion || therapy.fullSessionVersion || therapy.briefVersion,
+  },
+  ground: {
+    label: "Grounding",
+    text: (therapy) =>
+      therapy.clinicianScripts.find((script) => /ground|relax|distress/i.test(`${script.scriptType} ${script.title}`))
+        ?.body || therapy.briefVersion,
+  },
+};
+
 export function BriefScreen() {
   const b = useTcBindings();
   const t = b.selectedTherapy;
@@ -47,14 +62,9 @@ export function BriefScreen() {
   const { notice, saved, toggleFavourite } = useTherapyFavourite(t?.slug ?? null);
   if (b.loading || !t) return <LoadingState label="Loading brief interventions…" />;
 
-  const durationLabel = b.briefTab === "15min" ? "15-minute" : b.briefTab === "ground" ? "Grounding" : "5-minute";
-  const durationText =
-    b.briefTab === "15min"
-      ? t.fifteenMinuteVersion || t.fullSessionVersion || t.briefVersion
-      : b.briefTab === "ground"
-        ? t.clinicianScripts.find((c) => /ground|relax|distress/i.test(`${c.scriptType} ${c.title}`))?.body ||
-          t.briefVersion
-        : t.briefVersion;
+  const duration = BRIEF_DURATION[b.briefTab as TherapyBriefDuration] ?? BRIEF_DURATION["5min"];
+  const durationLabel = duration.label;
+  const durationText = duration.text(t);
   const steps = parseSteps(durationText, 6);
   const interventionText = [
     `${t.name} — ${durationLabel} intervention`,
@@ -135,9 +145,8 @@ export function BriefScreen() {
                 <label className="relative flex items-center mb-3">
                   <Search
                     aria-hidden="true"
-                    size={16}
                     strokeWidth={1.8}
-                    className="absolute left-[12px] text-[color:var(--decoration-soft)]"
+                    className="absolute left-[12px] size-icon-md text-[color:var(--decoration-soft)]"
                   />
                   <input
                     value={filter}
diff --git a/src/components/therapy-compass/screens/compare-screen.tsx b/src/components/therapy-compass/screens/compare-screen.tsx
index b6871cae56..ad8296c0cd 100644
--- a/src/components/therapy-compass/screens/compare-screen.tsx
+++ b/src/components/therapy-compass/screens/compare-screen.tsx
@@ -265,7 +265,7 @@ export function CompareScreen() {
                           className={`border-t border-[color:var(--border)] font-semibold ${dense ? "px-4 py-3" : "px-5 py-4"}`}
                         >
                           <span className="flex items-center gap-2.5">
-                            <r.icon size={16} strokeWidth={1.7} />
+                            <r.icon strokeWidth={1.7} className="size-icon-md" />
                             {r.label}
                           </span>
                         </th>
diff --git a/src/components/therapy-compass/screens/sheets-screen.tsx b/src/components/therapy-compass/screens/sheets-screen.tsx
index 98e3cc4b09..55f83a1509 100644
--- a/src/components/therapy-compass/screens/sheets-screen.tsx
+++ b/src/components/therapy-compass/screens/sheets-screen.tsx
@@ -329,7 +329,7 @@ function TherapyPicker() {
         onClick={() => setOpen((v) => !v)}
       >
         <span className="flex items-center gap-[9px] min-w-0">
-          <Scale aria-hidden="true" size={16} className="text-[color:var(--clinical-accent)] flex-none" />
+          <Scale aria-hidden="true" className="size-icon-md text-[color:var(--clinical-accent)] flex-none" />
           <span className="overflow-hidden text-ellipsis whitespace-nowrap">
             {b.selectedTherapy?.name ?? "Choose a therapy"}
           </span>
diff --git a/tests/ckb-v2-token-contract.test.ts b/tests/ckb-v2-token-contract.test.ts
index b2ad7873c2..1f6f0c2378 100644
--- a/tests/ckb-v2-token-contract.test.ts
+++ b/tests/ckb-v2-token-contract.test.ts
@@ -319,10 +319,25 @@ describe("ckb-v2 structure", () => {
       expect(structural.has(`--text-${step}`), `--text-${step} missing`).toBe(true);
       expect(structural.has(`--text-${step}-lh`), `--text-${step}-lh must stay deleted`).toBe(false);
       expect(structural.has(`--text-${step}-tr`), `--text-${step}-tr must stay deleted`).toBe(false);
+      expect(structural.has(`--text-${step}--line-height`), `--text-${step}--line-height must stay deleted`).toBe(
+        false,
+      );
     }
-    expect(structural.get("--leading-prose")).toMatch(/^\d+(\.\d+)?$/);
-    expect(structural.get("--text-hero--line-height")).toMatch(/^\d+(\.\d+)?$/);
+    expect(structural.get("--leading-prose")).toBe("1.65");
+    expect(structural.get("--text-hero--line-height")).toBe("1.12");
     expect(structural.get("--text-hero-tr")).toMatch(/^-/);
+
+    // The `^ {2}(--…)` map misses a declaration that is not indented with two
+    // spaces. Orphans must stay gone on the comment-stripped raw sheets too —
+    // including the live hero spelling `--text-<step>--line-height`.
+    const rawSheets = [stylesheet.replace(/\/\*[\s\S]*?\*\//g, ""), globalsStylesheet.replace(/\/\*[\s\S]*?\*\//g, "")];
+    for (const raw of rawSheets) {
+      for (const step of ["xs", "sm", "body", "md", "lg", "xl"]) {
+        expect(raw).not.toMatch(new RegExp(`--text-${step}-lh\\s*:`));
+        expect(raw).not.toMatch(new RegExp(`--text-${step}-tr\\s*:`));
+        expect(raw).not.toMatch(new RegExp(`--text-${step}--line-height\\s*:`));
+      }
+    }
   });
 });
 
diff --git a/tests/design-system-adoption.test.ts b/tests/design-system-adoption.test.ts
index 3360c73407..4ac2c89e7b 100644
--- a/tests/design-system-adoption.test.ts
+++ b/tests/design-system-adoption.test.ts
@@ -1482,4 +1482,19 @@ describe("design-system adoption manifest", () => {
     expect(gates).toMatch(/Render `AnswerCard` without[\s\S]*implemented-blocking in `AnswerCard`/);
     expect(gates).toMatch(/Use a bare dash[\s\S]*implemented-partial — `AccessibleTable` composes `MissingValue`/);
   });
+
+  it("quotes current design-system-contract-baseline totals in GATES.md", () => {
+    const { metrics } = JSON.parse(read("scripts/design-system-contract-baseline.json")) as {
+      metrics: Record<string, number>;
+    };
+    const gates = read("docs/design-system/GATES.md");
+    expect(gates).toContain(`edgeOwnershipConflicts\` (${metrics.edgeOwnershipConflicts})`);
+    expect(gates).toContain(`legacyShadowAliases\`, ratcheted at ${metrics.legacyShadowAliases}`);
+    expect(gates).toContain(`rawPaddingLiterals\` (${metrics.rawPaddingLiterals})`);
+    expect(gates).toContain(`rawGapLiterals\` (${metrics.rawGapLiterals})`);
+    expect(gates).toContain(`rawMarginLiterals\` (${metrics.rawMarginLiterals})`);
+    expect(gates).toContain(`interactiveTapFloorDeclarations\` (${metrics.interactiveTapFloorDeclarations})`);
+    expect(gates).toContain(`hardcodedCssMotionDurations\` (${metrics.hardcodedCssMotionDurations})`);
+    expect(gates).toMatch(new RegExp(`raw colours ${metrics.rawColorLiterals}\\b`));
+  });
 });
diff --git a/tests/therapy-compass-responsive-contract.test.ts b/tests/therapy-compass-responsive-contract.test.ts
index 7d5d3fd3c3..bf53f29292 100644
--- a/tests/therapy-compass-responsive-contract.test.ts
+++ b/tests/therapy-compass-responsive-contract.test.ts
@@ -264,7 +264,10 @@ describe("Therapy Compass responsive contract", () => {
     // the stronger condition: it proves the element really is that component
     // AND carries the labelling attribute, and unlike a raw substring it
     // cannot be satisfied by matching prose elsewhere in the file.
+    expect(briefSource).toContain("const BRIEF_DURATION");
+    expect(briefSource).not.toMatch(/briefTab === "15min" \? "15-minute"/);
     expect(openingTagWith(briefSource, "Tabs", ['label="Brief intervention duration"'])).toBeTruthy();
+
     expect(openingTagWith(compareSource, "Tabs", ['label="Comparison fields"'])).toBeTruthy();
     expect(openingTagWith(compareSource, "SegmentedControl", ['label="Comparison density"'])).toBeTruthy();
     expect(openingTagWith(sheetsSource, "SegmentedControl", ['label="Reading level and tone"'])).toBeTruthy();
@@ -324,6 +327,20 @@ describe("clinical accent contrast contract", () => {
     expect(briefSource).not.toContain('? "#fff" : "var(--clinical-accent)"');
   });
 
+  it("maps sweep-touched Lucide size={16} onto size-icon-md", () => {
+    for (const [name, source] of [
+      ["brief", briefSource],
+      ["compare", compareSource],
+      ["recommend", recommendSource],
+      ["sheets", sheetsSource],
+    ] as const) {
+      expect(source, `${name} screen`).not.toMatch(/\bsize=\{16\}/);
+    }
+    expect(briefSource).toContain("size-icon-md");
+    expect(compareSource).toContain("size-icon-md");
+    expect(sheetsSource).toContain("size-icon-md");
+  });
+
   it("keeps the current dark accent/foreground token pair above text contrast", () => {
     const darkStart = globalsSource.indexOf(".dark {");
     const darkEnd = globalsSource.indexOf("\n}", darkStart);

From 284454e511a503567e9e984dbc01ae0390c37153 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Thu, 27 Aug 2026 18:45:24 +0800
Subject: [PATCH 5/9] style: format PR 1 design-system docs

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/codebase-index.md          | 30 ++++++++++-----------
 docs/design-system/FIX-GUIDE.md | 42 ++++++++++++++---------------
 docs/design-system/SPEC.md      |  8 +++---
 docs/design-system/TOKENS.md    | 48 ++++++++++++++++-----------------
 4 files changed, 64 insertions(+), 64 deletions(-)

diff --git a/docs/codebase-index.md b/docs/codebase-index.md
index 6878cb4723..72fe2f8b50 100644
--- a/docs/codebase-index.md
+++ b/docs/codebase-index.md
@@ -9,28 +9,28 @@ Structured map for AI agents and onboarding. For live routes, see `docs/site-map
 
 ## Quick start
 
-| Step                              | Command                          |
-| --------------------------------- | -------------------------------- |
+| Step                              | Command                                                                          |
+| --------------------------------- | -------------------------------------------------------------------------------- |
 | Confirm Supabase target           | `npm run check:supabase-project` (provider-backed — needs explicit confirmation) |
-| Start app (project-specific port) | `npm run ensure`                 |
-| Start ingestion worker            | `npm run worker`                 |
-| Cheap verification gate           | `npm run verify:cheap`           |
-| UI verification gate              | `npm run verify:ui`              |
+| Start app (project-specific port) | `npm run ensure`                                                                 |
+| Start ingestion worker            | `npm run worker`                                                                 |
+| Cheap verification gate           | `npm run verify:cheap`                                                           |
+| UI verification gate              | `npm run verify:ui`                                                              |
 
 ---
 
 ## Top-level layout
 
-| Path        | Purpose                                                          |
-| ----------- | ---------------------------------------------------------------- |
-| `src/`      | Next.js App Router UI, API routes, shared lib, components        |
-| `supabase/` | SQL migrations, schema mirror, Edge Functions, CLI config        |
-| `worker/`   | Local ingestion worker (parse, OCR, chunk, embed, DB writes)     |
-| `scripts/`  | CLI ops: reindex, eval, backfill, governance, dev-server helpers |
-| `tests/`    | Vitest unit (`*.test.ts`) + Playwright E2E (`ui-*.spec.ts`)      |
+| Path        | Purpose                                                                                                                                                |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `src/`      | Next.js App Router UI, API routes, shared lib, components                                                                                              |
+| `supabase/` | SQL migrations, schema mirror, Edge Functions, CLI config                                                                                              |
+| `worker/`   | Local ingestion worker (parse, OCR, chunk, embed, DB writes)                                                                                           |
+| `scripts/`  | CLI ops: reindex, eval, backfill, governance, dev-server helpers                                                                                       |
+| `tests/`    | Vitest unit (`*.test.ts`) + Playwright E2E (`ui-*.spec.ts`)                                                                                            |
 | `docs/`     | Runbooks, governance, search/RAG plans, generated sitemap; design-system system of record is [`docs/design-system/README.md`](design-system/README.md) |
-| `public/`   | Static assets (`public/llms.txt`)                                |
-| `.github/`  | CI workflows, PR template (clinical governance preflight)        |
+| `public/`   | Static assets (`public/llms.txt`)                                                                                                                      |
+| `.github/`  | CI workflows, PR template (clinical governance preflight)                                                                                              |
 
 Smaller top-level directories that are easy to miss:
 
diff --git a/docs/design-system/FIX-GUIDE.md b/docs/design-system/FIX-GUIDE.md
index e79ba118d0..5814e3bd30 100644
--- a/docs/design-system/FIX-GUIDE.md
+++ b/docs/design-system/FIX-GUIDE.md
@@ -37,27 +37,27 @@ measurement of `globals.css` / `ckb-v2-tokens.css`.
 
 ## Batch B — docs dispositions
 
-| ID       | Status     | Rationale                                                                                                                                                                                   |
-| -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| DS-P2-04 | Documented | Intentional Geist variable interpolation. Already explained in [`docs/design-system.md`](../design-system.md) (intermediate weights; do **not** snap to 600/700).                           |
-| DS-P2-22 | Documented | `SectionHeading` exists (`src/components/ui/section-heading.tsx`); 14 production call sites. No opportunistic migration this sweep.                                                         |
-| DS-P2-23 | Documented | `AnswerCard` `frame?: "raised" \| "bare"` — both valid. Production answer surface uses **bare**. Future visual baselines must include both. Do not commit screenshots.                      |
-| DS-P2-27 | Documented | 15-mode load: recommend first-run / Tools prominence later. No IA redesign this sweep.                                                                                                      |
-| DS-P2-28 | Documented | Settings **Motion** already has a per-control description. **Recent searches on home** does not — docs recommendation only; no extra intro copy in product this sweep.                      |
-| DS-P2-29 | Deferred   | Phone document-viewer density waits on the tap-floor (Hazard ≥3).                                                                                                                           |
-| DS-P2-30 | Documented | Toast primitive exists; there is no **universal network-error** toast. Do not build toast infra here. `OverlayRoot` remains the overlay owner.                                              |
-| DS-P2-31 | Documented | Already in TOKENS §4 / SPEC §3: add `--kind-*` **with the first call site**. No values in this sweep.                                                                                       |
-| DS-P2-32 | Documented | `--text-placeholder` is **live** (globals + v2 + `placeholder:` consumers), not planned. TOKENS §5 corrected. No further role migration.                                                    |
-| DS-P2-33 | Documented | Contract `textSoftConsumers=0` in production. Keep the `--text-soft` alias until zero `var(--text-soft)` remain **including mockups**. Do not rename; do not delete this sweep.             |
-| DS-P3-01 | Deferred   | PR-9 plan. `--shadow-focus` and dead springs are already gone. `--shadow-lift` still has live `mode-nav` and `document-search-results` consumers — do **not** delete it.                    |
-| DS-P3-02 | Documented | TOKENS already: `--tone-*` frozen, not deleted.                                                                                                                                             |
-| DS-P3-03 | Documented | TOKENS already: design-side `--quantity-unit-scale` never lands.                                                                                                                            |
-| DS-P3-04 | Documented | TOKENS already: ConfidenceMeter deferred; no token without a call site.                                                                                                                     |
-| DS-P3-05 | Documented | Registry has **55** registered visual exports. `DocumentFrame` is built shell-only and still unregistered. Register when print primitives ship (PR 11). |
-| DS-P3-07 | Documented | Full visual state matrix grows incrementally with new adoptions.                                                                                                                            |
-| DS-P3-08 | Documented | QA checklist: inspect the filter band at 414–430px. No code this sweep.                                                                                                                     |
-| DS-P3-09 | Documented | `#TYZK23` PWA install CLS already fixed (PR #2253). Regression-check note only; no speculative CSS.                                                                                         |
-| DS-P3-10 | Documented | Mockup `min-h-11` and `--text-soft` body must not leak into production.                                                                                                                     |
+| ID       | Status     | Rationale                                                                                                                                                                       |
+| -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| DS-P2-04 | Documented | Intentional Geist variable interpolation. Already explained in [`docs/design-system.md`](../design-system.md) (intermediate weights; do **not** snap to 600/700).               |
+| DS-P2-22 | Documented | `SectionHeading` exists (`src/components/ui/section-heading.tsx`); 14 production call sites. No opportunistic migration this sweep.                                             |
+| DS-P2-23 | Documented | `AnswerCard` `frame?: "raised" \| "bare"` — both valid. Production answer surface uses **bare**. Future visual baselines must include both. Do not commit screenshots.          |
+| DS-P2-27 | Documented | 15-mode load: recommend first-run / Tools prominence later. No IA redesign this sweep.                                                                                          |
+| DS-P2-28 | Documented | Settings **Motion** already has a per-control description. **Recent searches on home** does not — docs recommendation only; no extra intro copy in product this sweep.          |
+| DS-P2-29 | Deferred   | Phone document-viewer density waits on the tap-floor (Hazard ≥3).                                                                                                               |
+| DS-P2-30 | Documented | Toast primitive exists; there is no **universal network-error** toast. Do not build toast infra here. `OverlayRoot` remains the overlay owner.                                  |
+| DS-P2-31 | Documented | Already in TOKENS §4 / SPEC §3: add `--kind-*` **with the first call site**. No values in this sweep.                                                                           |
+| DS-P2-32 | Documented | `--text-placeholder` is **live** (globals + v2 + `placeholder:` consumers), not planned. TOKENS §5 corrected. No further role migration.                                        |
+| DS-P2-33 | Documented | Contract `textSoftConsumers=0` in production. Keep the `--text-soft` alias until zero `var(--text-soft)` remain **including mockups**. Do not rename; do not delete this sweep. |
+| DS-P3-01 | Deferred   | PR-9 plan. `--shadow-focus` and dead springs are already gone. `--shadow-lift` still has live `mode-nav` and `document-search-results` consumers — do **not** delete it.        |
+| DS-P3-02 | Documented | TOKENS already: `--tone-*` frozen, not deleted.                                                                                                                                 |
+| DS-P3-03 | Documented | TOKENS already: design-side `--quantity-unit-scale` never lands.                                                                                                                |
+| DS-P3-04 | Documented | TOKENS already: ConfidenceMeter deferred; no token without a call site.                                                                                                         |
+| DS-P3-05 | Documented | Registry has **55** registered visual exports. `DocumentFrame` is built shell-only and still unregistered. Register when print primitives ship (PR 11).                         |
+| DS-P3-07 | Documented | Full visual state matrix grows incrementally with new adoptions.                                                                                                                |
+| DS-P3-08 | Documented | QA checklist: inspect the filter band at 414–430px. No code this sweep.                                                                                                         |
+| DS-P3-09 | Documented | `#TYZK23` PWA install CLS already fixed (PR #2253). Regression-check note only; no speculative CSS.                                                                             |
+| DS-P3-10 | Documented | Mockup `min-h-11` and `--text-soft` body must not leak into production.                                                                                                         |
 
 ---
 
diff --git a/docs/design-system/SPEC.md b/docs/design-system/SPEC.md
index eb9bb3b5d3..f5cf4097d9 100644
--- a/docs/design-system/SPEC.md
+++ b/docs/design-system/SPEC.md
@@ -665,11 +665,11 @@ and adoption.** Status keys as in the header; "done" entries cite their commit.
 
 ### Phase 2 — values, split three ways
 
-| PR                                | Contents                                                                                                      | Status                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| PR                                | Contents                                                                                                      | Status                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | PR 5a · Token values, no geometry | Colour, elevation, ink roles                                                                                  | **done** — `59e4c3dfc` landed the `--shadow-well` rename, the spine and status-mark families, and the dark `--clinical-chat-document` fix; the remaining ink-role deltas landed with PR 3 (`--text-placeholder`, eyebrows and placeholders off the decoration tier, the disabled encoding). The v2 light and dark blocks now declare the same colour roles. The two `#0f766e` accent defaults are scoped `RAW_COLOR_EXEMPTIONS`, so `rawColorLiterals` is **0** — they are data, not design tokens; see the note below |
-| PR 5b · Tap 44→48 in `@theme`     | The 426-site tap-call-site migration; contract-test pin update; visual QA pass; `--tap-min` becomes the alias | **done** — `--spacing-tap: 3rem` in `@theme`; `--tap-min` reduced to `var(--spacing-tap)`; 426 `*-tap` call sites moved; three pins flipped in the same commit; the phone composer keeps a written 44px exception below 431px (§4.10)                                                                                                                                                                                                                                                                   |
-| PR 5c · Radius step               | Every `rounded-md` moves; its own visual diff                                                                 | **done** — live `@theme --radius-md` 8px → 10px, matching the v2 control rung and moving 243 `rounded-md` call sites; the 4px-grid pin now names both half-steps and asserts the two layers agree; 14 arbitrary radius literals absorbed onto the ladder (§4.6)                                                                                                                                                                                                                                         |
+| PR 5b · Tap 44→48 in `@theme`     | The 426-site tap-call-site migration; contract-test pin update; visual QA pass; `--tap-min` becomes the alias | **done** — `--spacing-tap: 3rem` in `@theme`; `--tap-min` reduced to `var(--spacing-tap)`; 426 `*-tap` call sites moved; three pins flipped in the same commit; the phone composer keeps a written 44px exception below 431px (§4.10)                                                                                                                                                                                                                                                                                  |
+| PR 5c · Radius step               | Every `rounded-md` moves; its own visual diff                                                                 | **done** — live `@theme --radius-md` 8px → 10px, matching the v2 control rung and moving 243 `rounded-md` call sites; the 4px-grid pin now names both half-steps and asserts the two layers agree; 14 arbitrary radius literals absorbed onto the ladder (§4.6)                                                                                                                                                                                                                                                        |
 
 **`#0f766e` is data, not a token.** The two `#0f766e` accent defaults
 (`src/lib/medications.ts`, `src/lib/medication-records.ts`) restate a Postgres column
diff --git a/docs/design-system/TOKENS.md b/docs/design-system/TOKENS.md
index a6db7f10d4..f28e5977cc 100644
--- a/docs/design-system/TOKENS.md
+++ b/docs/design-system/TOKENS.md
@@ -41,27 +41,27 @@ This is the two-sources-of-truth failure C1 exists to kill. One winner per role:
 
 Declared in the `.ckb-v2` structural block **[verified: full read at `ef13a072a`]**.
 
-| Group            | Roles                                                                                                                                     | Notes                                                                                                                                                                                                                                                                                          |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Space scale      | `--space-0` … `--space-11`                                                                                                                | 4px base. Markup never references the raw scale — semantic tokens only.                                                                                                                                                                                                                        |
-| Semantic gaps    | `--gap-tight` · `--gap-inline` · `--gap-stack` · `--gap-block` · `--gap-section`                                                          | The only inter-element spacing markup may use.                                                                                                                                                                                                                                                 |
-| Semantic padding | `--pad-chip-x` · `--pad-control-x` · `--pad-cta-x` · `--pad-card` · `--pad-panel` · `--pad-strip`                                         | Heading-inset convention rides on these (SPEC §4.6).                                                                                                                                                                                                                                           |
-| Page             | `--page-gutter` · `--page-max` · `--measure` · `--header-h`                                                                               | `--measure` is the prose measure — never wider.                                                                                                                                                                                                                                                |
+| Group            | Roles                                                                                                                                     | Notes                                                                                                                                                                                                                                                                                                                           |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Space scale      | `--space-0` … `--space-11`                                                                                                                | 4px base. Markup never references the raw scale — semantic tokens only.                                                                                                                                                                                                                                                         |
+| Semantic gaps    | `--gap-tight` · `--gap-inline` · `--gap-stack` · `--gap-block` · `--gap-section`                                                          | The only inter-element spacing markup may use.                                                                                                                                                                                                                                                                                  |
+| Semantic padding | `--pad-chip-x` · `--pad-control-x` · `--pad-cta-x` · `--pad-card` · `--pad-panel` · `--pad-strip`                                         | Heading-inset convention rides on these (SPEC §4.6).                                                                                                                                                                                                                                                                            |
+| Page             | `--page-gutter` · `--page-max` · `--measure` · `--header-h`                                                                               | `--measure` is the prose measure — never wider.                                                                                                                                                                                                                                                                                 |
 | Type steps       | `--text-{xs,sm,body,md,lg,xl}` · `--text-hero` · `--text-hero--line-height` · `--text-hero-tr`                                            | Seven steps. Shared `--leading-prose`; hero keeps `--text-hero--line-height` / `--text-hero-tr` (gated). Unused xs–xl `-lh`/`-tr` and `--text-{step}--line-height` companions are orphans — do not re-require them. ⚠️ `--text-hero--line-height` is the one double-dash name — keep as-is; renaming is churn without a defect. |
-| Chip sizes       | `Chip` `compact` → `--text-2xs` (legacy compat step); `standard` (default) → `--text-xs`                                                  | Canonical (#220): dense surfaces opt into `size="compact"`; default adoption keeps `--text-xs`. `--text-2xs` stays a compatibility alias for Chip compact / legacy call sites — not a new v2 type step to invent against. Do not densify every Chip to chase the globals “small chips” note.   |
-| Type companions  | `--leading-prose` · `--tracking-eyebrow` · `--nums`                                                                                       | `--nums` = numeric variant for all data.                                                                                                                                                                                                                                                       |
-| Weights          | `--font-weight-{body,label,heading,value}`                                                                                                | One job each; display uses heading weight (SPEC §4.6).                                                                                                                                                                                                                                         |
-| Radius           | `--radius-{sm,md,lg,xl,2xl}`                                                                                                              | One step per surface role. v2 and live `--radius-md` agreed in PR 5c and are now pinned to each other by the live token contract.                                                                                                                                                              |
-| Icons            | `--icon-{xs,sm,md,lg}`                                                                                                                    | Paired to adjacent type steps.                                                                                                                                                                                                                                                                 |
-| Density          | `--tap-min` (alias of `--spacing-tap`, §1) · `--chip-height` · `--row-comfortable` · `--row-compact` · `--cell-pad-{comfortable,compact}` | Tap target is not row height (gated on resolved values, not strings, now that `--tap-min` is an alias).                                                                                                                                                                                        |
-| Accent rules     | `--rule-w` · `--rule-accent` · `--rule-warning`                                                                                           | ⚠️ Reference `var(--clinical-accent)` / `var(--warning)` **without declaring them** — v2 depends on the live layer for both (§5).                                                                                                                                                              |
-| Evidence gutter  | `--gutter-col` · `--gutter-dot` · `--gutter-line-w`                                                                                       | One gutter column owns line and dot (SPEC §7).                                                                                                                                                                                                                                                 |
-| Evidence spine   | `--spine-w` · `--spine-current` · `--spine-stale`                                                                                         | Authored `59e4c3dfc` (§1); derived from rule/accent/warning roles.                                                                                                                                                                                                                             |
-| Status mark      | `--status-mark-size` · `--status-mark-stroke`                                                                                             | Authored `59e4c3dfc` (§1); codifies `StatusMark`'s inline geometry.                                                                                                                                                                                                                            |
-| Quantity         | `--quantity-unit-tracking` · `--quantity-unit-gap`                                                                                        | Winners per §1.                                                                                                                                                                                                                                                                                |
-| Dashed edge      | `--border-dashed`                                                                                                                         | Drop targets / "nothing here yet" — distinct from `--border-strong`, which means emphasis.                                                                                                                                                                                                     |
-| Stacking         | `--z-{base,raised,chrome,overlay,popover,modal,toast}`                                                                                    | Each rung names its `--eN` partner; toast above modal deliberately.                                                                                                                                                                                                                            |
-| Motion           | `--duration-{fast,base,slow}` · `--ease-standard` · `--ease-physical`                                                                     | Durations zero under `prefers-reduced-motion` (gated).                                                                                                                                                                                                                                         |
+| Chip sizes       | `Chip` `compact` → `--text-2xs` (legacy compat step); `standard` (default) → `--text-xs`                                                  | Canonical (#220): dense surfaces opt into `size="compact"`; default adoption keeps `--text-xs`. `--text-2xs` stays a compatibility alias for Chip compact / legacy call sites — not a new v2 type step to invent against. Do not densify every Chip to chase the globals “small chips” note.                                    |
+| Type companions  | `--leading-prose` · `--tracking-eyebrow` · `--nums`                                                                                       | `--nums` = numeric variant for all data.                                                                                                                                                                                                                                                                                        |
+| Weights          | `--font-weight-{body,label,heading,value}`                                                                                                | One job each; display uses heading weight (SPEC §4.6).                                                                                                                                                                                                                                                                          |
+| Radius           | `--radius-{sm,md,lg,xl,2xl}`                                                                                                              | One step per surface role. v2 and live `--radius-md` agreed in PR 5c and are now pinned to each other by the live token contract.                                                                                                                                                                                               |
+| Icons            | `--icon-{xs,sm,md,lg}`                                                                                                                    | Paired to adjacent type steps.                                                                                                                                                                                                                                                                                                  |
+| Density          | `--tap-min` (alias of `--spacing-tap`, §1) · `--chip-height` · `--row-comfortable` · `--row-compact` · `--cell-pad-{comfortable,compact}` | Tap target is not row height (gated on resolved values, not strings, now that `--tap-min` is an alias).                                                                                                                                                                                                                         |
+| Accent rules     | `--rule-w` · `--rule-accent` · `--rule-warning`                                                                                           | ⚠️ Reference `var(--clinical-accent)` / `var(--warning)` **without declaring them** — v2 depends on the live layer for both (§5).                                                                                                                                                                                               |
+| Evidence gutter  | `--gutter-col` · `--gutter-dot` · `--gutter-line-w`                                                                                       | One gutter column owns line and dot (SPEC §7).                                                                                                                                                                                                                                                                                  |
+| Evidence spine   | `--spine-w` · `--spine-current` · `--spine-stale`                                                                                         | Authored `59e4c3dfc` (§1); derived from rule/accent/warning roles.                                                                                                                                                                                                                                                              |
+| Status mark      | `--status-mark-size` · `--status-mark-stroke`                                                                                             | Authored `59e4c3dfc` (§1); codifies `StatusMark`'s inline geometry.                                                                                                                                                                                                                                                             |
+| Quantity         | `--quantity-unit-tracking` · `--quantity-unit-gap`                                                                                        | Winners per §1.                                                                                                                                                                                                                                                                                                                 |
+| Dashed edge      | `--border-dashed`                                                                                                                         | Drop targets / "nothing here yet" — distinct from `--border-strong`, which means emphasis.                                                                                                                                                                                                                                      |
+| Stacking         | `--z-{base,raised,chrome,overlay,popover,modal,toast}`                                                                                    | Each rung names its `--eN` partner; toast above modal deliberately.                                                                                                                                                                                                                                                             |
+| Motion           | `--duration-{fast,base,slow}` · `--ease-standard` · `--ease-physical`                                                                     | Durations zero under `prefers-reduced-motion` (gated).                                                                                                                                                                                                                                                                          |
 
 ## 3 · v2 shell inventory — light and dark blocks
 
@@ -112,10 +112,10 @@ The v2 layer _references_ or _depends on_ these; their values stay in `live` / `
 | Token                                                                                                               | Disposition                                                                                                                                                                                                                                                                                                | Gate                                                                                                                                   |
 | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
 | `--text-soft`                                                                                                       | Deprecated alias of `--decoration-soft`; both resolve identically during the window. Delete when zero references remain outside the alias declaration.                                                                                                                                                     | Contract test pins the tier from both sides; a lint for `--text-soft`/`--decoration-soft` on text-bearing nodes is planned (GATES §1). |
-| `--shadow-focus`                                                                                                    | **Deleted** — encoded a companion focus ring the conventions forbid. Focus is an outline, not a ring.                                                                                                                                                                  | Gated gone by `tests/design-token-contract.test.ts`.                                                                                   |
-| `--shadow-lift`                                                                                                     | Retire into the `--eN` ladder (PR 9). Still has live consumers — do not delete until those move.                                                                                                                                                                        | Planned.                                                                                                                               |
-| `--shadow-card`, `--shadow-soft`                                                                                    | Aliases of a ladder step; retire **inside the recipes first**, then delete.                                                                                                                                                                                                | Planned.                                                                                                                               |
-| `--spring-bouncy` + two other dead springs                                                                          | **Deleted** (2026-08-21) — unused curves. `--ease-spring` remains.                                                                                                                                                                                                        | Done.                                                                                                                                  |
+| `--shadow-focus`                                                                                                    | **Deleted** — encoded a companion focus ring the conventions forbid. Focus is an outline, not a ring.                                                                                                                                                                                                      | Gated gone by `tests/design-token-contract.test.ts`.                                                                                   |
+| `--shadow-lift`                                                                                                     | Retire into the `--eN` ladder (PR 9). Still has live consumers — do not delete until those move.                                                                                                                                                                                                           | Planned.                                                                                                                               |
+| `--shadow-card`, `--shadow-soft`                                                                                    | Aliases of a ladder step; retire **inside the recipes first**, then delete.                                                                                                                                                                                                                                | Planned.                                                                                                                               |
+| `--spring-bouncy` + two other dead springs                                                                          | **Deleted** (2026-08-21) — unused curves. `--ease-spring` remains.                                                                                                                                                                                                                                         | Done.                                                                                                                                  |
 | `--quantity-unit-scale` (design side)                                                                               | Never lands; superseded per §1.                                                                                                                                                                                                                                                                            | Next design sync removes it.                                                                                                           |
 | Legacy type steps (`text-2xs`/`3xs`, `sm-minus`, `base-minus`, `2xl-minus`, `lg-minus`, `3xl-minus`, `3xl/4xl/5xl`) | Retired **last of all** — ≈663 call sites; `--text-md` arrives additively first. ⚠️ `Quantity` currently consumes `text-base-minus` — fix in the retirement tranche. `--text-2xl-compact` left this list early (`#297`): it had zero consumers, so retiring it needed no tranche and rendered identically. | Contract ratchet extension, planned.                                                                                                   |
 

From 19ee085b1cc952e8c40e893fb2fce99538415259 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Thu, 27 Aug 2026 18:53:49 +0800
Subject: [PATCH 6/9] chore: refresh repo-awareness snapshot after PR 1 docs

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 data/repo-awareness-snapshot.json | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/data/repo-awareness-snapshot.json b/data/repo-awareness-snapshot.json
index 9aa2484ec9..5d9b7f11d9 100644
--- a/data/repo-awareness-snapshot.json
+++ b/data/repo-awareness-snapshot.json
@@ -1,8 +1,8 @@
 {
   "version": "repo-awareness-snapshot-v1",
   "captured_revision": {
-    "sha": "fda57560b31b1b1ab5e86a8b232eff0e41951a92",
-    "committed_at": "2026-08-27T15:00:57+08:00"
+    "sha": "284454e511a503567e9e984dbc01ae0390c37153",
+    "committed_at": "2026-08-27T18:45:24+08:00"
   },
   "routes": {
     "modes": [
@@ -2389,7 +2389,7 @@
       {
         "path": "docs/design-system/FIX-GUIDE.md",
         "section": "design-system",
-        "catalogued": false
+        "catalogued": true
       },
       {
         "path": "docs/design-system/GATES.md",
@@ -2404,7 +2404,7 @@
       {
         "path": "docs/design-system/README.md",
         "section": "design-system",
-        "catalogued": false
+        "catalogued": true
       },
       {
         "path": "docs/design-system/SPEC.md",
@@ -3873,8 +3873,8 @@
     ],
     "counts": {
       "documents": 481,
-      "catalogued": 106,
-      "uncatalogued": 375,
+      "catalogued": 108,
+      "uncatalogued": 373,
       "sections": 19
     }
   },

From f36f94da025fa080d71ace0dce6672a9907a122c Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Fri, 28 Aug 2026 01:34:34 +0800
Subject: [PATCH 7/9] feat(clinical): add Form 12A statutory manifest, CV
 medications, and therapy compass governance copy (#DTSABC, #4AM8Z0, #PM9SP1)

---
 data/forms-catalog.json                       |  81 ++-
 data/medication-interaction-index.json        | 175 ++++-
 data/medications-snapshot.json                | 626 ++++++++++++++++++
 data/outstanding-issues-snapshot.json         |  22 +-
 docs/medication-interaction-lexicon-review.md |  22 +-
 .../39bc43fc-7bd7-4088-a7e4-4d29d3d418d5.json |  11 +
 .../44e5f87c-d30f-4334-9184-75c1544773ef.json |  11 +
 .../c66f01fb-e52a-40fa-a4b2-f4d1449ddb11.json |  11 +
 public/therapy-compass-data/pathways.json     |   2 +-
 scripts/generate-site-map.ts                  |   2 +-
 .../therapy-compass/screens/detail-screen.tsx |   2 +-
 .../screens/pathways-screen.tsx               |   2 +-
 src/components/therapy-compass/workspace.tsx  |   5 +-
 src/lib/app-modes.ts                          |   2 +-
 src/lib/medication-entities.ts                |   4 +
 tests/forms.test.ts                           |  21 +
 tests/medication-badges.test.ts               |  51 ++
 tests/medications.test.ts                     |   4 +-
 18 files changed, 981 insertions(+), 73 deletions(-)
 create mode 100644 docs/outstanding-issues-inbox/39bc43fc-7bd7-4088-a7e4-4d29d3d418d5.json
 create mode 100644 docs/outstanding-issues-inbox/44e5f87c-d30f-4334-9184-75c1544773ef.json
 create mode 100644 docs/outstanding-issues-inbox/c66f01fb-e52a-40fa-a4b2-f4d1449ddb11.json

diff --git a/data/forms-catalog.json b/data/forms-catalog.json
index 80130a491b..6a5d374a5f 100644
--- a/data/forms-catalog.json
+++ b/data/forms-catalog.json
@@ -2690,52 +2690,75 @@
       "form": "12A",
       "name": "Nomination Of Nominated Person",
       "category": "Rights and notifications",
-      "purpose": "Official form source: Nomination Of Nominated Person. Review the source snippets and approved form before use.",
-      "maker": "Check the official form signature block and Act sections.",
-      "involved": "Confirm patient, maker, receiving service, support contacts and required notifications from the form.",
-      "threshold": "Use the threshold stated in the official form and any linked guidance.",
-      "clock": "18 years",
-      "destination": "Confirm destination/place fields on the approved form.",
-      "authorises": "Authority is limited to what the approved form and Act section state.",
-      "doesNotAuthorise": "Does not replace linked forms, consent, notification or reporting duties unless the source says so.",
+      "purpose": "Nomination of an adult nominated person under the Mental Health Act 2014 to assist with rights, receive treatment and care information, and be involved in care planning.",
+      "maker": "Any person, including a child, who understands the effect of making the nomination (s273). Must be signed and witnessed by an authorised declaration taker; neither the person making the nomination nor the nominated person can witness (s275).",
+      "involved": "Person making nomination, nominated person (adult aged 18+), authorised witness, treating psychiatrist, mental health service.",
+      "threshold": "The person must understand the effect of making the nomination (s273). A person cannot have more than one nominated person at any time (s276). Only an adult is eligible to be nominated (s274).",
+      "clock": "Valid until revoked by the person at any time by any means, or superseded by a new nomination (s277), or until the nominated person resigns in writing (s278).",
+      "destination": "Filed in patient's medical record; copy to nominated person and treating clinicians.",
+      "authorises": "Authorises nominated person to be provided with information relating to treatment, care, rights, and involuntary status, and to be involved in matters relating to treatment and care planning (s266), and ensure rights and wishes are observed (s263), so long as the psychiatrist believes this is in the patient's best interests.",
+      "doesNotAuthorise": "Does not authorise the nominated person to consent to or refuse treatment on the patient's behalf, make clinical decisions, or act as an enduring guardian.",
       "before": [],
       "parallel": [],
       "after": [],
-      "copies": "Follow the approved distribution and filing fields on the form.",
-      "documentationStem": "Source-backed note for Form 12A: document maker, section, threshold facts, clock, destination/place, notifications and next owner.",
+      "copies": "Provide copy to nominated person, file original in medical record, and record in PSOLIS / clinical information system.",
+      "documentationStem": "Nomination of nominated person completed on [date]. Maker: [name] (understands effect). Nominated person: [name] (adult 18+). Witnessed by: [authorised witness name/qualification]. Scope: information sharing and care involvement under s263/s266.",
       "traps": [
-        "Do not infer powers beyond the form wording.",
-        "Check linked forms, attachments, notifications and clock limits."
+        "Treating the nominated person as having proxy consent or decision-making power over treatment.",
+        "Allowing the maker or nominated person to witness the nomination.",
+        "Nominating a minor under 18 years of age or having more than one active nominated person."
       ],
-      "safetyPearl": "Open the source snippets before relying on the pathway.",
-      "sourceNote": "Indexed from 📋 Form 12A.pdf.",
-      "aliases": ["12a", "nomination of nominated person", "rights and notifications"],
+      "safetyPearl": "A nominated person has rights to information and involvement under s266, but cannot consent to or refuse treatment on the patient's behalf.",
+      "sourceNote": "Authoritative statutory extract from approved Form 12A (WA Mental Health Act 2014 s263, s266, s273-s278).",
+      "aliases": ["12a", "nomination of nominated person", "rights and notifications", "nominated person"],
       "searchTerms": [
         "nomination",
-        "nominated",
-        "patient",
-        "treatment",
-        "provided",
+        "nominated person",
+        "s275",
+        "s273",
+        "s274",
+        "s276",
+        "s277",
+        "s278",
         "rights",
-        "care",
-        "witness",
+        "involvement",
+        "advocacy",
         "18 years"
       ],
       "riskLevel": "medium",
       "sourceDocumentId": "12a-6bee151a",
-      "legalNote": "Rights, notification and communication forms should be specific about the right affected, reason, review time, copies and advocacy/support-person communication. Use only the current approved form or PSOLIS pathway where available; only appropriately authorised people should complete MHA 2014 forms. Authority is limited to the Act sections, signature block, time limits and wording on the approved form.",
+      "legalNote": "Nomination under MHA 2014 s273-s278 gives the nominated person statutory rights to information and involvement in treatment planning under s266 and rights advocacy under s263, subject to psychiatrist best-interests determination. It does not confer substitute decision-making, guardianship, or consent authority. Valid until revoked (by any means) or resigned in writing.",
       "practicePearls": [
-        "Open the source snippets before relying on the pathway.",
-        "For rights forms, the review time and notification trail are part of the safeguard.",
-        "Clock cue: 18 years. Record the start time, expiry or review point, and next owner.",
+        "Nominee must be an adult aged 18 or over and accept the nomination in writing.",
+        "Witness must be authorised by law to take declarations (e.g. doctor, nurse, police officer, public servant) and cannot be the maker or nominee.",
+        "Information and involvement entitlements under s266 apply unless the psychiatrist determines it is not in the patient's best interests.",
+        "Clock cue: valid until revoked by maker or resigned in writing by nominee; nominee must be 18+.",
         "Source cue: sections 275."
       ],
       "preUseChecks": [
-        "Before use: confirm the right or notice, reason, recipient, copy pathway, review time and support/advocacy information.",
-        "Confirm the patient/person identifiers, maker, date, time, place and signature fields are complete.",
-        "Confirm copies, notices, support-person communication and filing/PSOLIS requirements before handover.",
-        "Open the official PDF when the form wording or authority boundary matters."
+        "Confirm the person understands the effect of making the nomination (s273).",
+        "Confirm the nominated person is an adult (aged 18 or over) and has signed the acceptance block.",
+        "Confirm both maker and nominee signatures are witnessed by an authorised declaration taker who is neither maker nor nominee.",
+        "Confirm there is no existing active nomination (a new nomination revokes prior ones under s277).",
+        "File in medical record and notify the treating team."
       ],
+      "priorityFacts": {
+        "clock": {
+          "title": "Valid until revoked or resigned",
+          "detail": "Revocable at any time · nominee must be 18+",
+          "body": "A nomination is valid until revoked by the person making it at any time and by any means whatsoever (s277), superseded by making another nomination (s277), or resigned in writing by the nominated person (s278). The nominated person must be aged 18 years or over (s274)."
+        },
+        "authority": {
+          "title": "Person understanding effect (any age, incl. child)",
+          "detail": "Witnessed by authorised declaration taker; nominee adult 18+",
+          "body": "Any person, including a child, who understands the effect of making the nomination (s273). Nominee must be an adult aged 18 or over (s274). Both nomination and acceptance must be signed and witnessed by a person authorised by law to take declarations (e.g. doctor, nurse, public servant); neither the maker nor the nominee may witness (s275)."
+        },
+        "criteria": {
+          "title": "Person understands effect of nomination (s273)",
+          "detail": "Max 1 nominee · rights, wishes, treatment info & involvement (s263, s266)",
+          "body": "The person cannot make a nomination unless they understand the effect of making it (s273). A person cannot have more than one nominated person at any time (s276). Authorises nominee to ensure rights and wishes are observed (s263) and to receive treatment and care information and be involved in care planning unless the psychiatrist determines it is not in the patient's best interests (s266)."
+        }
+      },
       "sourceFacts": {
         "documentTitle": "Nomination Of Nominated Person",
         "fileName": "📋 Form 12A.pdf",
diff --git a/data/medication-interaction-index.json b/data/medication-interaction-index.json
index 4fa6096a5d..5497146244 100644
--- a/data/medication-interaction-index.json
+++ b/data/medication-interaction-index.json
@@ -1,12 +1,12 @@
 {
   "version": 1,
   "generatedFrom": "data/medications-snapshot.json",
-  "sourceRowCount": 525,
+  "sourceRowCount": 531,
   "stats": {
-    "resolvedRows": 392,
-    "unresolvedRows": 133,
-    "rowsWithCatalogueTarget": 440,
-    "medicationsWithUnresolvedRows": 118
+    "resolvedRows": 397,
+    "unresolvedRows": 134,
+    "rowsWithCatalogueTarget": 446,
+    "medicationsWithUnresolvedRows": 119
   },
   "names": {
     "acamprosate": "Acamprosate",
@@ -275,6 +275,7 @@
     "psyllium": "Psyllium",
     "pyridoxine": "Pyridoxine",
     "quetiapine": "Quetiapine",
+    "ramipril": "Ramipril",
     "reboxetine": "Reboxetine",
     "riboflavin": "Riboflavin",
     "risedronate": "Risedronate",
@@ -289,6 +290,7 @@
     "senna": "Senna",
     "sertraline": "Sertraline",
     "sildenafil": "Sildenafil",
+    "simvastatin": "Simvastatin",
     "sitagliptin": "Sitagliptin",
     "sodium-chloride": "Sodium chloride",
     "sodium-nitroprusside": "Sodium nitroprusside",
@@ -1074,6 +1076,7 @@
             "morphine-sr-mr",
             "nifedipine-xr",
             "perindopril",
+            "ramipril",
             "spironolactone",
             "verapamil"
           ],
@@ -1324,6 +1327,7 @@
             "hydrochlorothiazide",
             "indapamide",
             "perindopril",
+            "ramipril",
             "spironolactone"
           ],
           "termIds": ["acei", "diuretics"],
@@ -1369,6 +1373,7 @@
             "hydrochlorothiazide",
             "indapamide",
             "perindopril",
+            "ramipril",
             "spironolactone"
           ],
           "termIds": ["acei", "arbs", "diuretics"],
@@ -1408,6 +1413,7 @@
             "naproxen",
             "parecoxib",
             "perindopril",
+            "ramipril",
             "spironolactone"
           ],
           "termIds": ["acei", "arbs", "diuretics", "nsaids"],
@@ -1463,6 +1469,7 @@
             "hydrochlorothiazide",
             "indapamide",
             "perindopril",
+            "ramipril",
             "spironolactone"
           ],
           "termIds": ["acei", "arbs", "diuretics"],
@@ -1515,6 +1522,7 @@
             "naproxen",
             "parecoxib",
             "perindopril",
+            "ramipril",
             "spironolactone"
           ],
           "termIds": ["acei", "arbs", "diuretics", "nsaids"],
@@ -1576,6 +1584,7 @@
             "meloxicam",
             "parecoxib",
             "perindopril",
+            "ramipril",
             "spironolactone"
           ],
           "termIds": ["acei", "arbs", "diuretics", "nsaids"],
@@ -1653,6 +1662,7 @@
             "hydrochlorothiazide",
             "indapamide",
             "perindopril",
+            "ramipril",
             "spironolactone"
           ],
           "termIds": ["acei", "arbs", "diuretics"],
@@ -1757,7 +1767,14 @@
           "rowKey": "Pharmacokinetic",
           "rowIndex": 0,
           "severity": "critical",
-          "counterparties": ["atorvastatin", "digoxin", "rosuvastatin", "warfarin-anticoagulant", "warfarin-vka"],
+          "counterparties": [
+            "atorvastatin",
+            "digoxin",
+            "rosuvastatin",
+            "simvastatin",
+            "warfarin-anticoagulant",
+            "warfarin-vka"
+          ],
           "termIds": ["pgp", "statins"],
           "resolved": false,
           "note": "CRITICAL — Potent inhibitor of CYP3A4, CYP2C9, and P-gp. Doubles the levels of Digoxin and Warfarin (halve their doses when starting amiodarone!). Increases statin toxicity."
@@ -1951,6 +1968,7 @@
             "metoprolol",
             "nifedipine-xr",
             "perindopril",
+            "ramipril",
             "spironolactone",
             "verapamil"
           ],
@@ -2045,7 +2063,7 @@
           "rowKey": "Pharmacokinetic",
           "rowIndex": 1,
           "severity": "high",
-          "counterparties": ["atorvastatin", "digoxin", "rosuvastatin"],
+          "counterparties": ["atorvastatin", "digoxin", "rosuvastatin", "simvastatin"],
           "termIds": ["statins"],
           "resolved": true,
           "note": "HIGH — Moderate **CYP3A4** inhibitor. Markedly increases statin levels (myopathy) and increases Digoxin concentrations by ~20%."
@@ -2119,6 +2137,7 @@
             "meloxicam",
             "naproxen",
             "parecoxib",
+            "ramipril",
             "spironolactone"
           ],
           "termIds": ["acei", "diuretics", "nsaids"],
@@ -2167,7 +2186,7 @@
           "rowKey": "Pharmacokinetic",
           "rowIndex": 1,
           "severity": "high",
-          "counterparties": ["atorvastatin", "digoxin"],
+          "counterparties": ["atorvastatin", "digoxin", "simvastatin"],
           "termIds": [],
           "resolved": true,
           "note": "HIGH — Moderate **CYP3A4** inhibitor. Massively increases levels of Simvastatin/Atorvastatin (myopathy risk) and Digoxin."
@@ -2287,7 +2306,7 @@
           "rowKey": "Pharmacodynamic",
           "rowIndex": 0,
           "severity": "critical",
-          "counterparties": ["candesartan", "perindopril", "spironolactone"],
+          "counterparties": ["candesartan", "perindopril", "ramipril", "spironolactone"],
           "termIds": ["acei", "arbs"],
           "resolved": true,
           "note": "CRITICAL — ACEi, ARBs, Spironolactone, K+ supplements. Do not use together unless under intense specialist monitoring."
@@ -2328,7 +2347,7 @@
           "rowKey": "Pharmacodynamic",
           "rowIndex": 1,
           "severity": "high",
-          "counterparties": ["candesartan", "perindopril"],
+          "counterparties": ["candesartan", "perindopril", "ramipril"],
           "termIds": ["acei", "arbs"],
           "resolved": true,
           "note": "HIGH — Potassium supplements, ACEi, ARBs (Hyperkalemia)."
@@ -2352,7 +2371,8 @@
             "meloxicam",
             "naproxen",
             "parecoxib",
-            "perindopril"
+            "perindopril",
+            "ramipril"
           ],
           "termIds": ["acei", "arbs", "nsaids"],
           "resolved": true,
@@ -2395,7 +2415,8 @@
             "meloxicam",
             "naproxen",
             "parecoxib",
-            "perindopril"
+            "perindopril",
+            "ramipril"
           ],
           "termIds": ["acei", "nsaids", "thiazide-diuretics"],
           "resolved": true,
@@ -2428,7 +2449,8 @@
             "meloxicam",
             "naproxen",
             "parecoxib",
-            "perindopril"
+            "perindopril",
+            "ramipril"
           ],
           "termIds": ["acei", "nsaids"],
           "resolved": true,
@@ -2443,7 +2465,7 @@
           "rowKey": "Pharmacodynamic",
           "rowIndex": 0,
           "severity": "critical",
-          "counterparties": ["candesartan", "perindopril"],
+          "counterparties": ["candesartan", "perindopril", "ramipril"],
           "termIds": ["acei", "arbs"],
           "resolved": true,
           "note": "CRITICAL — ACEi, ARBs, potassium supplements (Massive hyperkalemia risk)."
@@ -2475,7 +2497,7 @@
           "rowKey": "Pharmacokinetic",
           "rowIndex": 1,
           "severity": "high",
-          "counterparties": ["fenofibrate", "rosuvastatin"],
+          "counterparties": ["fenofibrate", "rosuvastatin", "simvastatin"],
           "termIds": ["fibrates", "statins"],
           "resolved": true,
           "note": "HIGH — Gemfibrozil (Fibrate) blocks statin uptake, drastically increasing blood levels. Avoid combo."
@@ -2512,7 +2534,7 @@
           "rowKey": "Pharmacodynamic",
           "rowIndex": 0,
           "severity": "critical",
-          "counterparties": ["atorvastatin", "rosuvastatin"],
+          "counterparties": ["atorvastatin", "rosuvastatin", "simvastatin"],
           "termIds": ["statins"],
           "resolved": true,
           "note": "CRITICAL — Statins. The combo risks massive muscle breakdown. (Note: Gemfibrozil + Statin is an absolute contraindication. Fenofibrate + Statin is used with extreme caution)."
@@ -2535,7 +2557,7 @@
           "rowKey": "Pharmacokinetic",
           "rowIndex": 0,
           "severity": "low",
-          "counterparties": ["atorvastatin"],
+          "counterparties": ["atorvastatin", "simvastatin"],
           "termIds": [],
           "resolved": true,
           "note": "LOW — Much fewer CYP interactions than Atorvastatin/Simvastatin."
@@ -4302,6 +4324,7 @@
             "nifedipine-xr",
             "parecoxib",
             "perindopril",
+            "ramipril",
             "spironolactone",
             "verapamil"
           ],
@@ -4869,6 +4892,7 @@
             "metoprolol",
             "nifedipine-xr",
             "perindopril",
+            "ramipril",
             "rivaroxaban",
             "spironolactone",
             "ticagrelor",
@@ -4959,6 +4983,7 @@
             "phenytoin",
             "rivaroxaban",
             "rosuvastatin",
+            "simvastatin",
             "ticagrelor",
             "warfarin-anticoagulant",
             "warfarin-vka"
@@ -5044,6 +5069,7 @@
             "naproxen",
             "parecoxib",
             "perindopril",
+            "ramipril",
             "spironolactone"
           ],
           "termIds": ["acei", "diuretics", "nsaids"],
@@ -5247,6 +5273,7 @@
             "heparin-iv-sc",
             "rivaroxaban",
             "rosuvastatin",
+            "simvastatin",
             "ticagrelor",
             "warfarin-anticoagulant",
             "warfarin-vka"
@@ -5296,7 +5323,7 @@
           "rowKey": "Pharmacokinetic",
           "rowIndex": 0,
           "severity": "critical",
-          "counterparties": ["atorvastatin", "colchicine", "warfarin-anticoagulant", "warfarin-vka"],
+          "counterparties": ["atorvastatin", "colchicine", "simvastatin", "warfarin-anticoagulant", "warfarin-vka"],
           "termIds": [],
           "resolved": true,
           "note": "CRITICAL — Shuts down **CYP3A4**. Fatal interactions with Simvastatin/Atorvastatin (rhabdomyolysis), Colchicine, and Warfarin."
@@ -5406,7 +5433,7 @@
           "rowKey": "Pharmacodynamic",
           "rowIndex": 0,
           "severity": "critical",
-          "counterparties": ["candesartan", "perindopril", "spironolactone"],
+          "counterparties": ["candesartan", "perindopril", "ramipril", "spironolactone"],
           "termIds": ["acei", "arbs"],
           "resolved": true,
           "note": "CRITICAL — ACEi, ARBs, Spironolactone (Guarantees severe hyperkalemia)."
@@ -5814,7 +5841,7 @@
           "rowKey": "Pharmacodynamic",
           "rowIndex": 0,
           "severity": "critical",
-          "counterparties": ["candesartan", "perindopril", "spironolactone"],
+          "counterparties": ["candesartan", "perindopril", "ramipril", "spironolactone"],
           "termIds": ["acei", "arbs"],
           "resolved": true,
           "note": "CRITICAL — ACEi, ARBs, Spironolactone. The combination guarantees hyperkalemia in the elderly. Check K+ levels."
@@ -5907,6 +5934,7 @@
             "metoprolol",
             "nifedipine-xr",
             "perindopril",
+            "ramipril",
             "spironolactone",
             "verapamil"
           ],
@@ -5939,7 +5967,7 @@
           "rowKey": "Pharmacodynamic",
           "rowIndex": 1,
           "severity": "high",
-          "counterparties": ["atorvastatin", "rosuvastatin"],
+          "counterparties": ["atorvastatin", "rosuvastatin", "simvastatin"],
           "termIds": ["statins"],
           "resolved": true,
           "note": "HIGH — Statins (additive risk of severe myopathy/rhabdomyolysis)."
@@ -6972,6 +7000,7 @@
             "metoprolol",
             "nifedipine-xr",
             "perindopril",
+            "ramipril",
             "spironolactone",
             "verapamil"
           ],
@@ -7471,6 +7500,7 @@
             "metoprolol",
             "nifedipine-xr",
             "perindopril",
+            "ramipril",
             "spironolactone",
             "verapamil"
           ],
@@ -7623,7 +7653,7 @@
           "rowKey": "Pharmacokinetic",
           "rowIndex": 1,
           "severity": "safe",
-          "counterparties": ["atorvastatin", "rosuvastatin", "venlafaxine-xr"],
+          "counterparties": ["atorvastatin", "rosuvastatin", "simvastatin", "venlafaxine-xr"],
           "termIds": ["statins"],
           "resolved": true,
           "note": "SAFE — Unlike Venlafaxine, it has zero significant CYP450 interactions, making it highly safe to mix with Tamoxifen, Statins, or heart meds."
@@ -8276,6 +8306,7 @@
             "metoprolol",
             "nifedipine-xr",
             "perindopril",
+            "ramipril",
             "spironolactone",
             "verapamil"
           ],
@@ -8317,6 +8348,7 @@
             "metoprolol",
             "nifedipine-xr",
             "perindopril",
+            "ramipril",
             "spironolactone",
             "verapamil"
           ],
@@ -8472,6 +8504,7 @@
             "metoprolol",
             "nifedipine-xr",
             "perindopril",
+            "ramipril",
             "spironolactone",
             "verapamil"
           ],
@@ -8572,6 +8605,7 @@
             "metoprolol",
             "nifedipine-xr",
             "perindopril",
+            "ramipril",
             "spironolactone",
             "verapamil"
           ],
@@ -8600,7 +8634,8 @@
             "meloxicam",
             "naproxen",
             "parecoxib",
-            "perindopril"
+            "perindopril",
+            "ramipril"
           ],
           "termIds": ["acei", "arbs", "lithium", "nsaids", "thiazide-diuretics"],
           "resolved": true,
@@ -8703,6 +8738,7 @@
             "metoprolol",
             "nifedipine-xr",
             "perindopril",
+            "ramipril",
             "spironolactone",
             "verapamil"
           ],
@@ -8867,6 +8903,7 @@
             "oxycodone-ir",
             "oxycodone-sr-mr",
             "perindopril",
+            "ramipril",
             "spironolactone",
             "tapentadol-sr",
             "temazepam",
@@ -9505,6 +9542,7 @@
             "metoprolol",
             "nifedipine-xr",
             "perindopril",
+            "ramipril",
             "sildenafil",
             "spironolactone",
             "verapamil"
@@ -9732,7 +9770,7 @@
           "rowKey": "Pharmacodynamic",
           "rowIndex": 0,
           "severity": "high",
-          "counterparties": ["atorvastatin", "rosuvastatin"],
+          "counterparties": ["atorvastatin", "rosuvastatin", "simvastatin"],
           "termIds": ["statins"],
           "resolved": true,
           "note": "HIGH — Niacin combined with Statins exponentially increases the risk of rhabdomyolysis."
@@ -9758,6 +9796,7 @@
             "naproxen",
             "parecoxib",
             "perindopril",
+            "ramipril",
             "spironolactone"
           ],
           "termIds": ["acei", "arbs", "nsaids"],
@@ -9841,6 +9880,7 @@
             "metoprolol",
             "nifedipine-xr",
             "perindopril",
+            "ramipril",
             "spironolactone",
             "verapamil"
           ],
@@ -9989,6 +10029,93 @@
         }
       ],
       "unresolvedRowCount": 0
+    },
+    "ramipril": {
+      "rows": [
+        {
+          "rowKey": "Triple Whammy",
+          "rowIndex": 0,
+          "severity": "critical",
+          "counterparties": [
+            "amiloride",
+            "aspirin",
+            "celecoxib",
+            "diclofenac",
+            "eplerenone",
+            "frusemide",
+            "hydrochlorothiazide",
+            "ibuprofen",
+            "indapamide",
+            "ketorolac",
+            "meloxicam",
+            "naproxen",
+            "parecoxib",
+            "perindopril",
+            "spironolactone"
+          ],
+          "termIds": ["acei", "diuretics", "nsaids"],
+          "resolved": true,
+          "note": "CRITICAL — ACEi + Diuretic + NSAID (Ibuprofen/Naproxen). This combination guarantees acute renal failure by destroying both afferent and efferent glomerular blood flow."
+        },
+        {
+          "rowKey": "Pharmacodynamic",
+          "rowIndex": 1,
+          "severity": "high",
+          "counterparties": [
+            "amiloride",
+            "eplerenone",
+            "frusemide",
+            "hydrochlorothiazide",
+            "indapamide",
+            "spironolactone"
+          ],
+          "termIds": ["diuretics"],
+          "resolved": true,
+          "note": "HIGH — Potassium-sparing diuretics (Spironolactone, Eplerenone), K+ supplements (Severe hyperkalemia)."
+        },
+        {
+          "rowKey": "Pharmacokinetic",
+          "rowIndex": 2,
+          "severity": "high",
+          "counterparties": ["lithium-carbonate-ir-sr", "perindopril"],
+          "termIds": ["acei", "lithium"],
+          "resolved": true,
+          "note": "HIGH — Lithium (ACE inhibitors reduce renal clearance of lithium, leading to lithium toxicity)."
+        }
+      ],
+      "unresolvedRowCount": 0
+    },
+    "simvastatin": {
+      "rows": [
+        {
+          "rowKey": "Pharmacokinetic",
+          "rowIndex": 0,
+          "severity": "critical",
+          "counterparties": ["clarithromycin", "erythromycin"],
+          "termIds": ["azole-antifungals", "grapefruit"],
+          "resolved": true,
+          "note": "CRITICAL — Metabolised extensively by **CYP3A4**. Strong inhibitors (Clarithromycin, Erythromycin, Itraconazole, Ketoconazole, Grapefruit juice) massively increase Simvastatin levels, precipitating rhabdomyolysis and acute renal failure. Concurrent use is contraindicated."
+        },
+        {
+          "rowKey": "Pharmacokinetic",
+          "rowIndex": 1,
+          "severity": "high",
+          "counterparties": ["atorvastatin", "fenofibrate", "rosuvastatin"],
+          "termIds": ["fibrates", "statins"],
+          "resolved": true,
+          "note": "HIGH — Gemfibrozil (Fibrate) blocks statin glucuronidation and uptake, drastically increasing blood levels. Contraindicated combo."
+        },
+        {
+          "rowKey": "Pharmacodynamic",
+          "rowIndex": 2,
+          "severity": "high",
+          "counterparties": ["amiodarone", "amlodipine", "diltiazem", "verapamil"],
+          "termIds": ["cyp-inhibitors"],
+          "resolved": false,
+          "note": "HIGH — Moderate CYP3A4 inhibitors (Amiodarone, Diltiazem, Verapamil, Amlodipine). Limit Simvastatin dose to max 20 mg/day (or 10 mg/day with Amiodarone/Verapamil/Diltiazem) to prevent myopathy."
+        }
+      ],
+      "unresolvedRowCount": 1
     }
   }
 }
diff --git a/data/medications-snapshot.json b/data/medications-snapshot.json
index 196429ef63..6b57786a17 100644
--- a/data/medications-snapshot.json
+++ b/data/medications-snapshot.json
@@ -97845,5 +97845,631 @@
         "value": "Zinc and Iron compete for the exact same transporter in the gut. If you give a patient Zincaps and Ferro-gradumet at the same time, neither will absorb properly. Take them at different times of the day."
       }
     ]
+  },
+  {
+    "slug": "ramipril",
+    "name": "Ramipril",
+    "class": "Antihypertensive",
+    "subclass": "ACE Inhibitor",
+    "category": "Cardiovascular - Antihypertensives",
+    "accent": "#0284c7",
+    "tag": "ACEi",
+    "schedule": "S4",
+    "stats": [
+      {
+        "label": "Max Dose",
+        "value": "10 mg/day",
+        "cls": "hi",
+        "flag": "hi"
+      },
+      {
+        "label": "Half-life",
+        "value": "13-17 h (Active)",
+        "cls": "",
+        "flag": ""
+      },
+      {
+        "label": "Dry Cough",
+        "value": "COMMON",
+        "cls": "warn",
+        "flag": ""
+      },
+      {
+        "label": "Teratogenic",
+        "value": "CRITICAL RISK",
+        "cls": "hi",
+        "flag": "warn"
+      }
+    ],
+    "sections": [
+      {
+        "title": "Rapid Summary",
+        "type": "summary",
+        "rows": [
+          {
+            "key": "Overview",
+            "val": "Potent, long-acting Angiotensin-Converting Enzyme (ACE) inhibitor. Cornerstone foundational therapy for hypertension, heart failure post-MI, diabetic nephropathy, and secondary cardiovascular prevention (HOPE trial).",
+            "tags": []
+          },
+          {
+            "key": "Maximum Dose",
+            "val": "Max **10 mg/day**. Reduce in Renal impairment — initial 1.25 mg **OD**, max 5 mg/day if **eGFR** < 30.",
+            "tags": []
+          },
+          {
+            "key": "Clinical Focus",
+            "val": "Absolutely contraindicated in Pregnancy (Category D). Causes severe fetal renal dysgenesis, oligohydramnios, and neonatal hypoplasia. Cease immediately on confirmed pregnancy.",
+            "tags": []
+          },
+          {
+            "key": "Bottom Line",
+            "val": "Ramipril is a high-yield first-line ACE inhibitor with extensive clinical trial evidence for stroke and MI risk reduction, but must never be used in Pregnancy and mandates baseline and ongoing **U&E** monitoring.",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Risk Profile",
+        "type": "risk",
+        "rows": [
+          {
+            "key": "Renal",
+            "val": "HIGH — Hyperkalemia, Acute Kidney Injury (AKI) especially in bilateral renal artery stenosis, severe hypovolemia, or concomitant NSAID/diuretic use.",
+            "tags": []
+          },
+          {
+            "key": "Respiratory",
+            "val": "HIGH — Persistent dry cough (in ~10-15% of patients due to bradykinin accumulation).",
+            "tags": []
+          },
+          {
+            "key": "Immunological",
+            "val": "CRITICAL — Angioedema (swelling of lips, tongue, pharynx, or airway). Can occur anytime during therapy and warrants permanent cessation of all ACE inhibitors.",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Dosing & Administration",
+        "type": "dose",
+        "rows": [
+          {
+            "key": "Hypertension",
+            "val": "Start **PO** 2.5 mg **OD**. Titrate at 2-4 week intervals to 5-10 mg **OD** (max 10 mg/day).",
+            "tags": []
+          },
+          {
+            "key": "Heart Failure / Post-MI",
+            "val": "Start **PO** 1.25-2.5 mg **BD**. Titrate to target 5 mg **BD** (or 10 mg **OD**).",
+            "tags": []
+          },
+          {
+            "key": "Cardiovascular Risk Reduction (HOPE)",
+            "val": "Start **PO** 2.5 mg **OD** for 1-2 weeks, then 5 mg **OD** for 2-3 weeks, titrating to target **10 mg OD**.",
+            "tags": []
+          },
+          {
+            "key": "Renal Impairment",
+            "val": "MANDATORY — If **eGFR** < 30 mL/min, start at **1.25 mg OD**; max dose **5 mg/day**. Monitor serum creatinine and potassium strictly.",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Formulation & Access",
+        "type": "form",
+        "rows": [
+          {
+            "key": "Brand Names",
+            "val": "Tritace, Ramace, Prilace",
+            "tags": []
+          },
+          {
+            "key": "Oral Routes",
+            "val": "Tablets / Capsules (1.25 mg, 2.5 mg, 5 mg, 10 mg).",
+            "tags": []
+          },
+          {
+            "key": "Prescribing & PBS",
+            "val": "Unrestricted General Benefit (S4).",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Indications & Use",
+        "type": "ind",
+        "rows": [
+          {
+            "key": "Primary",
+            "val": "Hypertension, Heart Failure (HFrEF, post-MI), secondary prevention of MI and stroke in high-risk CV patients, diabetic nephropathy.",
+            "tags": ["PBS", "TGA"]
+          },
+          {
+            "key": "Clinical Place",
+            "val": "First-line ACE inhibitor supported by landmark trial evidence (HOPE study) demonstrating mortality and CV event reduction.",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Contraindications & Populations",
+        "type": "contra",
+        "rows": [
+          {
+            "key": "Absolute",
+            "val": "CRITICAL — History of ACE inhibitor-induced angioedema or hereditary/idiopathic angioedema. Bilateral renal artery stenosis or unilateral stenosis in a solitary kidney.",
+            "tags": []
+          },
+          {
+            "key": "Pregnancy",
+            "val": "ABSOLUTE — **Pregnancy** Category D. Must be ceased immediately upon confirmed or planned pregnancy due to severe fetal toxicity.",
+            "tags": [],
+            "patient": {
+              "factors": ["pregnancy"],
+              "action": "contraindication",
+              "severity": "danger",
+              "note": "ACE inhibitors are teratogenic (Pregnancy Category D); cease immediately upon conception."
+            }
+          },
+          {
+            "key": "Renal Impairment",
+            "val": "Dose adjustment required in severe renal impairment (eGFR < 30). Pre-existing hyperkalemia (> 5.5 mmol/L) is a relative contraindication.",
+            "tags": [],
+            "patient": {
+              "factors": ["renal"],
+              "action": "dose-adjust",
+              "severity": "caution",
+              "note": "Reduce starting dose to 1.25 mg OD if eGFR < 30 mL/min; monitor U&E closely."
+            }
+          }
+        ]
+      },
+      {
+        "title": "Key Interactions",
+        "type": "inter",
+        "rows": [
+          {
+            "key": "Triple Whammy",
+            "val": "CRITICAL — ACEi + Diuretic + NSAID (Ibuprofen/Naproxen). This combination guarantees acute renal failure by destroying both afferent and efferent glomerular blood flow.",
+            "tags": []
+          },
+          {
+            "key": "Pharmacodynamic",
+            "val": "HIGH — Potassium-sparing diuretics (Spironolactone, Eplerenone), K+ supplements (Severe hyperkalemia).",
+            "tags": []
+          },
+          {
+            "key": "Pharmacokinetic",
+            "val": "HIGH — Lithium (ACE inhibitors reduce renal clearance of lithium, leading to lithium toxicity).",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Monitoring & Cautions",
+        "type": "mon",
+        "rows": [
+          {
+            "key": "Laboratory",
+            "val": "MANDATORY — Check **U&E** (Creatinine, Potassium) at baseline, 1-2 weeks post-initiation and after each dose escalation. Serum creatinine rise ≤ 30% is acceptable.",
+            "tags": []
+          },
+          {
+            "key": "Bedside",
+            "val": "Monitor lying and standing **BP** to detect first-dose hypotension, particularly in patients on diuretics or volume-depleted states.",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Clinical Pearls",
+        "type": "pearl",
+        "rows": [
+          {
+            "key": "The Cough Switch",
+            "val": "If the patient develops a persistent dry ACEi cough, switch to an ARB (such as Candesartan or Telmisartan); do not prescribe cough suppressants.",
+            "tags": []
+          },
+          {
+            "key": "The 30% Creatinine Rule",
+            "val": "A mild creatinine increase (< 30%) reflects reduced intraglomerular pressure and long-term nephroprotection; do not stop therapy unless creatinine rises > 30% or potassium exceeds 5.5 mmol/L.",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Mechanism & Pharmacokinetics",
+        "type": "evid",
+        "rows": [
+          {
+            "key": "Mechanism",
+            "val": "Prodrug converted by hepatic esterases to active ramiprilat, a potent competitive inhibitor of ACE. Reduces Angiotensin II and aldosterone while increasing bradykinin.",
+            "tags": []
+          },
+          {
+            "key": "Onset",
+            "val": "**PO** 1-2 hours; peak hemodynamic effect at 3-6 hours.",
+            "tags": []
+          },
+          {
+            "key": "Half-life",
+            "val": "Ramiprilat elimination half-life is triphasic, effective terminal half-life 13-17 hours.",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Sources",
+        "type": "src",
+        "rows": [
+          {
+            "key": "Source Review",
+            "val": "Source-backed review 2026-05-11: TRITACE/ramipril Australian PI and AMH monographs. Entry checked for dosing, access, contraindications/populations, interactions, monitoring, patient-context metadata, and app structure."
+          }
+        ]
+      }
+    ],
+    "quick": [
+      {
+        "label": "Class & Role",
+        "value": "ACE Inhibitor — First-line antihypertensive, heart failure, post-MI, renal protection."
+      },
+      {
+        "label": "Route / Formulation",
+        "value": "**PO** capsules/tablets: 1.25 mg, 2.5 mg, 5 mg, 10 mg (Tritace, Ramace, Prilace)"
+      },
+      {
+        "label": "Usual Dose & Max",
+        "value": "Start 2.5 mg **OD**, titrate to 5-10 mg **OD**. Max **10 mg/day**."
+      },
+      {
+        "label": "Key Indication Doses",
+        "value": "HTN: 2.5-10 mg **OD**. HF/Post-MI: 1.25-2.5 mg **BD**, target 5 mg **BD**. Renal: start 1.25 mg **OD** if **eGFR** < 30."
+      },
+      {
+        "label": "Best Uses",
+        "value": "Ramipril is a high-yield first-line ACE inhibitor with extensive clinical trial evidence for stroke and MI risk reduction, but must never be used in Pregnancy and mandates baseline and ongoing **U&E** monitoring."
+      },
+      {
+        "label": "Avoid / Cautions",
+        "value": "History of ACEi angioedema. Bilateral renal artery stenosis. **Pregnancy** Category D (Absolute contraindication)."
+      },
+      {
+        "label": "Key Risks",
+        "value": "Renal: Hyperkalemia, AKI. Respiratory: Dry cough (10-15%). Immunological: Angioedema (CRITICAL)."
+      },
+      {
+        "label": "Key Interactions",
+        "value": "Triple Whammy: ACEi + Diuretic + NSAID (Severe AKI). Potassium-sparing diuretics (Spironolactone) cause hyperkalemia. Lithium toxicity."
+      },
+      {
+        "label": "Monitoring",
+        "value": "Check **U&E** at baseline, 1-2 weeks after starting/titrating, then 6-12 monthly. Check BP."
+      },
+      {
+        "label": "Clinical Pearl",
+        "value": "Switch to an ARB (Candesartan) if dry cough occurs. A creatinine increase up to 30% is expected and protective."
+      }
+    ]
+  },
+  {
+    "slug": "simvastatin",
+    "name": "Simvastatin",
+    "class": "Lipid-Lowering",
+    "subclass": "HMG-CoA Reductase Inhibitor",
+    "category": "Cardiovascular - Lipid Lowering",
+    "accent": "#0284c7",
+    "tag": "STATIN",
+    "schedule": "S4",
+    "stats": [
+      {
+        "label": "Max Dose",
+        "value": "40 mg/day (ON)",
+        "cls": "hi",
+        "flag": "hi"
+      },
+      {
+        "label": "Half-life",
+        "value": "2-3 h",
+        "cls": "",
+        "flag": ""
+      },
+      {
+        "label": "Myopathy",
+        "value": "HIGH CYP3A4",
+        "cls": "warn",
+        "flag": "warn"
+      },
+      {
+        "label": "Hepatic",
+        "value": "LFTs REQ",
+        "cls": "warn",
+        "flag": ""
+      }
+    ],
+    "sections": [
+      {
+        "title": "Rapid Summary",
+        "type": "summary",
+        "rows": [
+          {
+            "key": "Overview",
+            "val": "Foundational HMG-CoA reductase inhibitor (statin). Landmark trial proof in secondary prevention (4S trial). Short half-life requiring evening administration and highest CYP3A4 drug-interaction liability among statins.",
+            "tags": []
+          },
+          {
+            "key": "Maximum Dose",
+            "val": "Max **40 mg/day** taken at night. The 80 mg dose is restricted due to heightened rhabdomyolysis risk.",
+            "tags": []
+          },
+          {
+            "key": "Clinical Focus",
+            "val": "Must be taken in the evening/night. Avoid strong CYP3A4 inhibitors (Clarithromycin, Itraconazole, Grapefruit juice) which precipitate life-threatening rhabdomyolysis.",
+            "tags": []
+          },
+          {
+            "key": "Bottom Line",
+            "val": "Simvastatin is an effective lipid-lowering agent with robust cardiovascular trial evidence, but its high CYP3A4 interaction sensitivity and evening-dosing requirement make it more interaction-prone than atorvastatin or rosuvastatin.",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Risk Profile",
+        "type": "risk",
+        "rows": [
+          {
+            "key": "Musculoskeletal",
+            "val": "HIGH — Myalgia, myopathy. CRITICAL — Rhabdomyolysis with acute kidney injury, especially when combined with CYP3A4 inhibitors or gemfibrozil.",
+            "tags": []
+          },
+          {
+            "key": "Hepatic",
+            "val": "MODERATE — Transaminitis (ALT/AST elevation); rare severe hepatotoxicity.",
+            "tags": [],
+            "patient": {
+              "factors": ["hepatic"],
+              "action": "dose-adjust",
+              "severity": "caution",
+              "note": "Active liver disease is an absolute contraindication; monitor transaminases if symptomatic."
+            }
+          },
+          {
+            "key": "Metabolic",
+            "val": "LOW — Small, dose-related increase in HbA1c and fasting blood glucose levels.",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Dosing & Administration",
+        "type": "dose",
+        "rows": [
+          {
+            "key": "Hypercholesterolaemia / Primary Prevention",
+            "val": "**PO** 10-20 mg **ON** (in the evening). Titrate every 4 weeks to target lipid levels.",
+            "tags": []
+          },
+          {
+            "key": "Secondary Prevention (High Risk / CHD)",
+            "val": "**PO** 20-40 mg **ON** (in the evening). Max **40 mg/day**.",
+            "tags": []
+          },
+          {
+            "key": "Renal Impairment",
+            "val": "In severe renal impairment (**eGFR** < 30 mL/min), start at **5-10 mg ON** and monitor closely for myopathy.",
+            "tags": []
+          },
+          {
+            "key": "Co-administration Caps",
+            "val": "Diltiazem, Verapamil, Amlodipine, Amiodarone: limit simvastatin to max **10-20 mg/day**.",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Formulation & Access",
+        "type": "form",
+        "rows": [
+          {
+            "key": "Brand Names",
+            "val": "Zocor, Lipex, Simvar",
+            "tags": []
+          },
+          {
+            "key": "Oral Routes",
+            "val": "Tablets (5 mg, 10 mg, 20 mg, 40 mg, 80 mg).",
+            "tags": []
+          },
+          {
+            "key": "Prescribing & PBS",
+            "val": "Unrestricted General Benefit (S4).",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Indications & Use",
+        "type": "ind",
+        "rows": [
+          {
+            "key": "Primary",
+            "val": "Hypercholesterolaemia, mixed dyslipidemia, coronary heart disease secondary prevention (4S trial), diabetes with cardiovascular risk.",
+            "tags": ["PBS", "TGA"]
+          },
+          {
+            "key": "Clinical Place",
+            "val": "Established statin for primary and secondary cardiovascular risk reduction. Often switched to Atorvastatin or Rosuvastatin for greater potency or fewer CYP3A4 interactions.",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Contraindications & Populations",
+        "type": "contra",
+        "rows": [
+          {
+            "key": "Absolute",
+            "val": "CRITICAL — Active liver disease, unexplained persistent transaminitis. Concomitant strong CYP3A4 inhibitors (Clarithromycin, Erythromycin, Itraconazole, Ketoconazole, HIV protease inhibitors, Gemfibrozil, Cyclosporin).",
+            "tags": [],
+            "patient": {
+              "factors": ["hepatic"],
+              "action": "contraindication",
+              "severity": "danger",
+              "note": "Active liver disease and unexplained persistent transaminitis are absolute contraindications."
+            }
+          },
+          {
+            "key": "Pregnancy",
+            "val": "ABSOLUTE — **Pregnancy** Category D. Contraindicated throughout pregnancy and breastfeeding (cholesterol synthesis essential for fetal organogenesis).",
+            "tags": [],
+            "patient": {
+              "factors": ["pregnancy"],
+              "action": "contraindication",
+              "severity": "danger",
+              "note": "Statins are contraindicated in pregnancy (Category D); cholesterol is essential for fetal development."
+            }
+          },
+          {
+            "key": "Renal Impairment",
+            "val": "Use with caution in severe renal impairment (eGFR < 30); start 5-10 mg ON.",
+            "tags": [],
+            "patient": {
+              "factors": ["renal"],
+              "action": "dose-adjust",
+              "severity": "caution",
+              "note": "Start with 5-10 mg ON in severe renal impairment (eGFR < 30 mL/min); monitor for myopathy."
+            }
+          }
+        ]
+      },
+      {
+        "title": "Key Interactions",
+        "type": "inter",
+        "rows": [
+          {
+            "key": "Pharmacokinetic",
+            "val": "CRITICAL — Metabolised extensively by **CYP3A4**. Strong inhibitors (Clarithromycin, Erythromycin, Itraconazole, Ketoconazole, Grapefruit juice) massively increase Simvastatin levels, precipitating rhabdomyolysis and acute renal failure. Concurrent use is contraindicated.",
+            "tags": []
+          },
+          {
+            "key": "Pharmacokinetic",
+            "val": "HIGH — Gemfibrozil (Fibrate) blocks statin glucuronidation and uptake, drastically increasing blood levels. Contraindicated combo.",
+            "tags": []
+          },
+          {
+            "key": "Pharmacodynamic",
+            "val": "HIGH — Moderate CYP3A4 inhibitors (Amiodarone, Diltiazem, Verapamil, Amlodipine). Limit Simvastatin dose to max 20 mg/day (or 10 mg/day with Amiodarone/Verapamil/Diltiazem) to prevent myopathy.",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Monitoring & Cautions",
+        "type": "mon",
+        "rows": [
+          {
+            "key": "Laboratory",
+            "val": "MANDATORY — Baseline **Lipids** and **LFTs**. Check CK (Creatine Kinase) promptly if patient experiences unexplained muscle pain, tenderness, or weakness.",
+            "tags": []
+          },
+          {
+            "key": "Bedside",
+            "val": "Inquire about muscle aches, cramps, weakness, or brown/dark urine at each review. Reinforce evening administration.",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Clinical Pearls",
+        "type": "pearl",
+        "rows": [
+          {
+            "key": "The Evening Rule",
+            "val": "Simvastatin has a short half-life (~2-3 hours) and must be taken at bedtime when hepatic cholesterol synthesis is maximal. In contrast, Atorvastatin and Rosuvastatin can be taken at any time of day.",
+            "tags": []
+          },
+          {
+            "key": "The Macrolide Hazard",
+            "val": "Never co-prescribe Clarithromycin or Erythromycin with Simvastatin. If a macrolide is necessary, suspend Simvastatin for the antibiotic course.",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Mechanism & Pharmacokinetics",
+        "type": "evid",
+        "rows": [
+          {
+            "key": "Mechanism",
+            "val": "Inactive lactone prodrug hydrolysed to active beta-hydroxyacid, which competitively inhibits HMG-CoA reductase. Up-regulates hepatic LDL receptors.",
+            "tags": []
+          },
+          {
+            "key": "Onset",
+            "val": "Lipid reduction starts within 2 weeks; peak therapeutic response at 4-6 weeks.",
+            "tags": []
+          },
+          {
+            "key": "Half-life",
+            "val": "2-3 hours for active metabolites. Extensive CYP3A4 first-pass metabolism (~5% oral bioavailability).",
+            "tags": []
+          }
+        ]
+      },
+      {
+        "title": "Sources",
+        "type": "src",
+        "rows": [
+          {
+            "key": "Source Review",
+            "val": "Source-backed review 2026-05-11: ZOCOR/simvastatin Australian PI and TGA/FDA safety advisories. Entry checked for dosing, access, contraindications/populations, interactions, monitoring, patient-context metadata, and app structure."
+          }
+        ]
+      }
+    ],
+    "quick": [
+      {
+        "label": "Class & Role",
+        "value": "HMG-CoA Reductase Inhibitor — Lipid-lowering statin for primary and secondary CV prevention."
+      },
+      {
+        "label": "Route / Formulation",
+        "value": "**PO** tablets: 5 mg, 10 mg, 20 mg, 40 mg, 80 mg (Zocor, Lipex, Simvar)"
+      },
+      {
+        "label": "Usual Dose & Max",
+        "value": "**PO** 10-20 mg **ON** (evening). Max **40 mg/day** (80 mg dose restricted due to myopathy risk)."
+      },
+      {
+        "label": "Key Indication Doses",
+        "value": "Primary: 10-20 mg **ON**. High risk/CAD: 20-40 mg **ON**. Renal: 5-10 mg **ON** if **eGFR** < 30."
+      },
+      {
+        "label": "Best Uses",
+        "value": "Simvastatin is an effective lipid-lowering agent with robust cardiovascular trial evidence, but its high CYP3A4 interaction sensitivity and evening-dosing requirement make it more interaction-prone than atorvastatin or rosuvastatin."
+      },
+      {
+        "label": "Avoid / Cautions",
+        "value": "Active liver disease. **Pregnancy** Category D (Absolute contraindication). Strong CYP3A4 inhibitors (Contraindicated)."
+      },
+      {
+        "label": "Key Risks",
+        "value": "Musculoskeletal: Myalgia, myopathy, rhabdomyolysis (CRITICAL with CYP3A4 inhibitors). Hepatic: Transaminitis."
+      },
+      {
+        "label": "Key Interactions",
+        "value": "Strong CYP3A4 inhibitors (Clarithromycin, Itraconazole, Grapefruit juice) cause rhabdomyolysis. Gemfibrozil contraindicated. Cap at 20 mg with Amlodipine/Diltiazem."
+      },
+      {
+        "label": "Monitoring",
+        "value": "Baseline lipids and **LFTs**. Prompt CK if muscle pain or dark urine occurs."
+      },
+      {
+        "label": "Clinical Pearl",
+        "value": "Must be taken in the evening due to short 2-3h half-life. Never combine with Clarithromycin (suspend statin during course)."
+      }
+    ]
   }
 ]
diff --git a/data/outstanding-issues-snapshot.json b/data/outstanding-issues-snapshot.json
index 6d69cea272..3dfe19ac33 100644
--- a/data/outstanding-issues-snapshot.json
+++ b/data/outstanding-issues-snapshot.json
@@ -2,7 +2,7 @@
   "version": "outstanding-issues-snapshot-v1",
   "ledger_revision": {
     "sha": "364177bad72f7c2dae7a266b5cf8f61837dbd0e5",
-    "committed_at": "2026-08-27T04:33:41+00:00"
+    "committed_at": "2026-08-27T04:33:41Z"
   },
   "counts": {
     "open": 98,
@@ -10,7 +10,7 @@
     "p2": 60,
     "p3": 37,
     "queued": 9,
-    "pending": 33,
+    "pending": 36,
     "resolved": 414
   },
   "queue": [
@@ -1041,6 +1041,18 @@
       "summary": "#50QRCF: Verified stable consecutive mobile Lighthouse CLS runs following root app-shell fix.",
       "created_at": "2026-08-27"
     },
+    {
+      "request_id": "39bc43fc-7bd7-4088-a7e4-4d29d3d418d5",
+      "action": "done",
+      "summary": "#4AM8Z0: Added Ramipril and Simvastatin to medication catalogue with full interaction, dosing, and contraindication profiles; rebuilt interaction index and asserted in tests/medication-badges.test.ts",
+      "created_at": "2026-08-27"
+    },
+    {
+      "request_id": "44e5f87c-d30f-4334-9184-75c1544773ef",
+      "action": "done",
+      "summary": "#PM9SP1: Relabelled Therapy Compass copy from 'Decision support' to 'Source-grounded therapy reference' across workspace, screens, and app-modes",
+      "created_at": "2026-08-27"
+    },
     {
       "request_id": "46d9aaa1-e700-488d-8b75-bb6db7067475",
       "action": "done",
@@ -1161,6 +1173,12 @@
       "summary": "#50QRCF: Resolved on main via PR #2253 (merge 66594dd, fix commit 0cf0493). Root cause was PWA notice stack (div.pwa-notice-stack) mounting during Next.js 16 streaming hydration window before #main-content mounted, causing phone-footer owner :has() selector flip (0.2230 shift). Fixed by gating notice stack mount on app shell hydration via MutationObserver useSyncExternalStore in src/components/pwa-lifecycle.tsx. Confirmed locally (0.2230 -> 0.000) and verified on CI Lighthouse budget run 32531103787 (CLS <= 0.016 budget). Closed together with #TYZK23 and #KFRC3H.",
       "created_at": "2026-08-27"
     },
+    {
+      "request_id": "c66f01fb-e52a-40fa-a4b2-f4d1449ddb11",
+      "action": "done",
+      "summary": "#DTSABC: Authored Form 12A statutory Authority and Criteria prose from committed PDF and asserted in tests/forms.test.ts",
+      "created_at": "2026-08-27"
+    },
     {
       "request_id": "c9689169-5616-4282-bf8c-25bd5f089575",
       "action": "done",
diff --git a/docs/medication-interaction-lexicon-review.md b/docs/medication-interaction-lexicon-review.md
index 4b55a200f9..4aabc0bca6 100644
--- a/docs/medication-interaction-lexicon-review.md
+++ b/docs/medication-interaction-lexicon-review.md
@@ -26,29 +26,29 @@ CRITICAL or HIGH. Start at the top — the table is sorted by severe usage.
 
 | Term                       | Matches these phrases                                                                                    | Rows | Severe | Resolves to                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | -------------------------- | -------------------------------------------------------------------------------------------------------- | ---- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `nsaids`                   | nsaids, nsaid                                                                                            | 40   | 39     | **8** — Aspirin, Celecoxib, Diclofenac, Ibuprofen, Ketorolac, Meloxicam, Naproxen, Parecoxib                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `nsaids`                   | nsaids, nsaid                                                                                            | 41   | 40     | **8** — Aspirin, Celecoxib, Diclofenac, Ibuprofen, Ketorolac, Meloxicam, Naproxen, Parecoxib                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `opioids`                  | opioids, opioid, opioid analgesia, opiates, full agonists                                                | 35   | 35     | **13** — Buprenorphine (SL/depot), Buprenorphine + naloxone, Buprenorphine patch, Codeine, Fentanyl, Hydromorphone (IR/IV), Methadone, Morphine (IR/IV), Morphine SR / MR, Oxycodone IR, Oxycodone SR / MR, Tapentadol SR, Tramadol IR                                                                                                                                                                                                                                                                                  |
 | `benzodiazepines`          | benzodiazepines, benzodiazepine, benzos, benzo                                                           | 32   | 32     | **8** — Alprazolam, Clonazepam, Diazepam, Lorazepam, Midazolam, Nitrazepam, Oxazepam, Temazepam                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `beta-blockers`            | beta-blockers, beta blockers, beta-blocker, beta blocker, non-selective beta-blockers                    | 23   | 22     | **7** — Atenolol, Bisoprolol, Carvedilol, Labetalol, Metoprolol, Propranolol, Sotalol                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `acei`                     | acei, aceis, ace inhibitors, ace inhibitor                                                               | 22   | 22     | **2** — Perindopril, Ramipril                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `ssris`                    | ssris, ssri                                                                                              | 22   | 20     | **6** — Citalopram, Escitalopram, Fluoxetine, Fluvoxamine, Paroxetine, Sertraline                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `tcas`                     | tcas, tca, tricyclics, tricyclic antidepressants, anticholinergic tcas                                   | 22   | 20     | **6** — Amitriptyline, Clomipramine, Dosulepin, Doxepin, Imipramine, Nortriptyline                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `acei`                     | acei, aceis, ace inhibitors, ace inhibitor                                                               | 20   | 20     | **1** — Perindopril                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `diuretics`                | diuretics, diuretic                                                                                      | 20   | 19     | **6** — Amiloride, Eplerenone, Frusemide, Hydrochlorothiazide, Indapamide, Spironolactone                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `maois`                    | maois, maoi, monoamine oxidase inhibitors                                                                | 19   | 17     | **2** — Phenelzine, Tranylcypromine                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `diuretics`                | diuretics, diuretic                                                                                      | 18   | 17     | **6** — Amiloride, Eplerenone, Frusemide, Hydrochlorothiazide, Indapamide, Spironolactone                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `arbs`                     | arbs, arb                                                                                                | 16   | 16     | **1** — Candesartan                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `anticholinergics`         | anticholinergics, anticholinergic, atropine-like medicines                                               | 18   | 15     | **6** — Benzatropine, Hyoscine butylbromide, Hyoscine hydrobromide, Orphenadrine, Oxybutynin, Solifenacin                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `anticoagulants`           | anticoagulants, anticoagulant, doacs, doac                                                               | 18   | 15     | **12** — Apixaban, Clopidogrel, Dabigatran, Dalteparin, Dipyridamole, Edoxaban, Enoxaparin, Heparin (IV/SC), Rivaroxaban, Ticagrelor, Warfarin (`warfarin-anticoagulant`), Warfarin (`warfarin-vka`)                                                                                                                                                                                                                                                                                                                    |
 | `antipsychotics`           | antipsychotics, antipsychotic                                                                            | 17   | 15     | **26** — Amisulpride, Aripiprazole, Aripiprazole LAI, Asenapine, Brexpiprazole, Cariprazine, Chlorpromazine, Clozapine, Flupentixol decanoate, Haloperidol decanoate, Levomepromazine, Lurasidone, Olanzapine (wafer/ODT), Olanzapine pamoate LAI, Paliperidone ER, Paliperidone LAI, Periciazine, Quetiapine, Risperidone, Risperidone LAI, Trifluoperazine, Ziprasidone, Ziprasidone IM, Zuclopenthixol, Zuclopenthixol acetate, Zuclopenthixol decanoate                                                             |
 | `antacids`                 | antacids, antacid                                                                                        | 16   | 14     | **2** — Calcium carbonate, Magnesium oxide                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `antihypertensives`        | antihypertensives, antihypertensive                                                                      | 14   | 14     | **17** — Amlodipine, Atenolol, Bisoprolol, Candesartan, Carvedilol, Diltiazem, Eplerenone, Felodipine, Frusemide, Hydrochlorothiazide, Indapamide, Labetalol, Metoprolol, Nifedipine XR, Perindopril, Spironolactone, Verapamil                                                                                                                                                                                                                                                                                         |
+| `antihypertensives`        | antihypertensives, antihypertensive                                                                      | 14   | 14     | **18** — Amlodipine, Atenolol, Bisoprolol, Candesartan, Carvedilol, Diltiazem, Eplerenone, Felodipine, Frusemide, Hydrochlorothiazide, Indapamide, Labetalol, Metoprolol, Nifedipine XR, Perindopril, Ramipril, Spironolactone, Verapamil                                                                                                                                                                                                                                                                               |
 | `macrolides`               | macrolides, macrolide                                                                                    | 13   | 12     | **4** — Azithromycin, Clarithromycin, Erythromycin, Roxithromycin                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `lithium`                  | lithium, lithium carbonate                                                                               | 10   | 10     | **1** — Lithium carbonate (IR/SR)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `oral-contraceptives`      | oral contraceptives, oral contraceptive, combined oral contraceptive pill, cocp, ocps, ocp               | 10   | 9      | **2** — Ethinylestradiol, Levonorgestrel                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `calcium-channel-blockers` | calcium channel blockers, calcium channel blocker, ccbs, ccb, non-dhp ccbs, dhp calcium channel blockers | 9    | 9      | **5** — Amlodipine, Diltiazem, Felodipine, Nifedipine XR, Verapamil                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `corticosteroids`          | corticosteroids, corticosteroid, steroids, steroid                                                       | 9    | 9      | **11** — Beclometasone, Budesonide, Ciclesonide, Dexamethasone, Fludrocortisone, Fluticasone, Hydrocortisone, Methylprednisolone, Mometasone, Prednisolone, Prednisone                                                                                                                                                                                                                                                                                                                                                  |
-| `lithium`                  | lithium, lithium carbonate                                                                               | 9    | 9      | **1** — Lithium carbonate (IR/SR)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `thiazide-diuretics`       | thiazide diuretics, thiazides, thiazide                                                                  | 9    | 9      | **2** — Hydrochlorothiazide, Indapamide                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `statins`                  | statins, statin                                                                                          | 10   | 8      | **3** — Atorvastatin, Rosuvastatin, Simvastatin                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `ppis`                     | ppis, ppi, proton pump inhibitors                                                                        | 8    | 8      | **2** — Esomeprazole, Pantoprazole                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `statins`                  | statins, statin                                                                                          | 9    | 7      | **2** — Atorvastatin, Rosuvastatin                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `aminoglycosides`          | aminoglycosides, aminoglycoside                                                                          | 6    | 5      | **2** — Amikacin, Gentamicin                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `fluoroquinolones`         | fluoroquinolones, fluoroquinolone, quinolones                                                            | 5    | 5      | **3** — Ciprofloxacin, Moxifloxacin, Norfloxacin                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `loop-diuretics`           | loop diuretics, loop diuretic                                                                            | 5    | 5      | **1** — Frusemide                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
@@ -58,8 +58,8 @@ CRITICAL or HIGH. Start at the top — the table is sorted by severe usage.
 | `snris`                    | snris, snri                                                                                              | 4    | 3      | **5** — Atomoxetine, Desvenlafaxine, Duloxetine, Tramadol IR, Venlafaxine XR                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `antiplatelets`            | antiplatelets, antiplatelet                                                                              | 3    | 3      | **4** — Aspirin, Clopidogrel, Dipyridamole, Ticagrelor                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `gabapentinoids`           | gabapentinoids, gabapentinoid                                                                            | 3    | 3      | **2** — Gabapentin, Pregabalin                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `fibrates`                 | fibrates, fibrate                                                                                        | 3    | 2      | **1** — Fenofibrate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `immunosuppressants`       | immunosuppressants, immunosuppressant                                                                    | 2    | 2      | **1** — Methotrexate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `fibrates`                 | fibrates, fibrate                                                                                        | 2    | 1      | **1** — Fenofibrate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `cephalosporins`           | cephalosporins, cephalosporin                                                                            | 1    | 1      | **5** — Cefazolin, Cefepime, Ceftriaxone, Cefuroxime, Cephalexin                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `nrt`                      | transdermal nrt, nicotine transdermal systems, nicotine patches                                          | 1    | 0      | **6** — Nicotine gum, Nicotine inhalator, Nicotine lozenge, Nicotine mouth spray, Nicotine patch, Nicotine sublingual tablet                                                                                                                                                                                                                                                                                                                                                                                            |
 | `sulfonylureas`            | sulfonylureas, sulfonylurea                                                                              | 1    | 0      | **2** — Gliclazide, Glipizide                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
@@ -92,16 +92,16 @@ the class cannot be enumerated, and holds the medication at grey rather than gre
 | Term                     | Kind      | Matches these phrases                                                                                                             | Rows | Note                                                                                                     |
 | ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------- |
 | `alcohol`                | nonDrug   | alcohol, alcohol-containing preparations, ethanol                                                                                 | 33   | Substance use, not a prescribable catalogue entry.                                                       |
-| `grapefruit`             | nonDrug   | grapefruit, grapefruit juice                                                                                                      | 6    | Dietary CYP3A4 inhibitor.                                                                                |
+| `grapefruit`             | nonDrug   | grapefruit, grapefruit juice                                                                                                      | 7    | Dietary CYP3A4 inhibitor.                                                                                |
 | `acidic-drinks`          | nonDrug   | acidic drinks, coffee, juice, soft drinks, cola                                                                                   | 7    | Buccal/oral absorption timing, not a drug interaction.                                                   |
 | `smoking`                | nonDrug   | smoking, cigarette smoke, tobacco smoke                                                                                           | 7    | CYP1A2 induction by polycyclic aromatic hydrocarbons, not by nicotine.                                   |
 | `food`                   | nonDrug   | food, dairy, milk, high-fat meals, tyramine                                                                                       | 10   | Dietary.                                                                                                 |
 | `st-johns-wort`          | external  | st john's wort, st johns wort, hypericum                                                                                          | 9    | Herbal CYP3A4 inducer; not stocked in the catalogue.                                                     |
-| `azole-antifungals`      | external  | ketoconazole, azoles, azole antifungals                                                                                           | 23   | Ketoconazole is not in the catalogue; fluconazole/itraconazole resolve by name.                          |
+| `azole-antifungals`      | external  | ketoconazole, azoles, azole antifungals                                                                                           | 24   | Ketoconazole is not in the catalogue; fluconazole/itraconazole resolve by name.                          |
 | `barbiturates`           | external  | barbiturates, barbiturate, phenobarbital, phenobarbitone                                                                          | 5    | Not stocked in the catalogue.                                                                            |
 | `antiretrovirals`        | external  | antiretrovirals, antiretroviral, protease inhibitors                                                                              | 2    | Ritonavir and relatives are outside the catalogue.                                                       |
 | `cotrimoxazole`          | external  | bactrim, co-trimoxazole, cotrimoxazole                                                                                            | 3    | Combination product; trimethoprim resolves by name.                                                      |
-| `cyp-inhibitors`         | mechanism | cyp inhibitors, cyp inhibitor, strong cyp inhibitors, cyp3a4 inhibitors, cyp2d6 inhibitors, cyp1a2 inhibitors, cyp2c19 inhibitors | 50   | Enumerating inhibitors needs pharmacokinetic data the catalogue does not carry.                          |
+| `cyp-inhibitors`         | mechanism | cyp inhibitors, cyp inhibitor, strong cyp inhibitors, cyp3a4 inhibitors, cyp2d6 inhibitors, cyp1a2 inhibitors, cyp2c19 inhibitors | 51   | Enumerating inhibitors needs pharmacokinetic data the catalogue does not carry.                          |
 | `cyp-inducers`           | mechanism | cyp inducers, cyp inducer, strong cyp inducers, cyp3a4 inducers, enzyme inducers                                                  | 9    | See cyp-inhibitors.                                                                                      |
 | `cyp-substrates`         | mechanism | cyp substrates, cyp2d6 substrates, cyp3a4 substrates, narrow therapeutic index drugs                                              | 1    |                                                                                                          |
 | `pgp`                    | mechanism | p-gp, p-gp inhibitors, p-glycoprotein, oatp                                                                                       | 11   |                                                                                                          |
@@ -120,7 +120,7 @@ the class cannot be enumerated, and holds the medication at grey rather than gre
 
 ## What this tool can never warn about
 
-**26 of the catalogue's 328 medications sit outside both ends of every resolved
+**26 of the catalogue's 330 medications sit outside both ends of every resolved
 interaction row.** Entering one of them produces no alert — not because the combination was checked and
 found clear, but because no machine-resolved edge in the corpus includes that drug. On screen those outcomes look the
 same, so this list is the honest boundary of the feature.
diff --git a/docs/outstanding-issues-inbox/39bc43fc-7bd7-4088-a7e4-4d29d3d418d5.json b/docs/outstanding-issues-inbox/39bc43fc-7bd7-4088-a7e4-4d29d3d418d5.json
new file mode 100644
index 0000000000..6110f4dad2
--- /dev/null
+++ b/docs/outstanding-issues-inbox/39bc43fc-7bd7-4088-a7e4-4d29d3d418d5.json
@@ -0,0 +1,11 @@
+{
+  "version": 2,
+  "id": "39bc43fc-7bd7-4088-a7e4-4d29d3d418d5",
+  "createdOn": "2026-08-27",
+  "action": "done",
+  "payload": {
+    "id": "#4AM8Z0",
+    "outcome": "Added Ramipril and Simvastatin to medication catalogue with full interaction, dosing, and contraindication profiles; rebuilt interaction index and asserted in tests/medication-badges.test.ts",
+    "baseRowFingerprint": "a420a3e9b005324b7821b8985f6d34c023ac76e78769771d64fb2c326e5a00c0"
+  }
+}
diff --git a/docs/outstanding-issues-inbox/44e5f87c-d30f-4334-9184-75c1544773ef.json b/docs/outstanding-issues-inbox/44e5f87c-d30f-4334-9184-75c1544773ef.json
new file mode 100644
index 0000000000..5fc9396734
--- /dev/null
+++ b/docs/outstanding-issues-inbox/44e5f87c-d30f-4334-9184-75c1544773ef.json
@@ -0,0 +1,11 @@
+{
+  "version": 2,
+  "id": "44e5f87c-d30f-4334-9184-75c1544773ef",
+  "createdOn": "2026-08-27",
+  "action": "done",
+  "payload": {
+    "id": "#PM9SP1",
+    "outcome": "Relabelled Therapy Compass copy from 'Decision support' to 'Source-grounded therapy reference' across workspace, screens, and app-modes",
+    "baseRowFingerprint": "755b6dd3772b192d15dd0aef89149aba50ae3b105fa627c9313388d4dce0dc86"
+  }
+}
diff --git a/docs/outstanding-issues-inbox/c66f01fb-e52a-40fa-a4b2-f4d1449ddb11.json b/docs/outstanding-issues-inbox/c66f01fb-e52a-40fa-a4b2-f4d1449ddb11.json
new file mode 100644
index 0000000000..eccca32957
--- /dev/null
+++ b/docs/outstanding-issues-inbox/c66f01fb-e52a-40fa-a4b2-f4d1449ddb11.json
@@ -0,0 +1,11 @@
+{
+  "version": 2,
+  "id": "c66f01fb-e52a-40fa-a4b2-f4d1449ddb11",
+  "createdOn": "2026-08-27",
+  "action": "done",
+  "payload": {
+    "id": "#DTSABC",
+    "outcome": "Authored Form 12A statutory Authority and Criteria prose from committed PDF and asserted in tests/forms.test.ts",
+    "baseRowFingerprint": "4407912b05d98be64cbf8c3604d4c19b076ff3b26d1890cb73663bd1f5c2e322"
+  }
+}
diff --git a/public/therapy-compass-data/pathways.json b/public/therapy-compass-data/pathways.json
index 66a7d0f9f3..c9b30cecab 100644
--- a/public/therapy-compass-data/pathways.json
+++ b/public/therapy-compass-data/pathways.json
@@ -1 +1 @@
-[{"slug":"anxiety-pathway","name":"Anxiety pathway","clinicalProblem":"Anxiety","summary":"Source-grounded workflow assembled from therapies indexed to Anxiety. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as decision support only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"cognitive-behavioural-therapy-cbt","label":"Initial option","description":"Strongest broad evidence-backed uses are depression and anxiety disorders. It is also a major umbrella treatment family for disorder-specific variants such as panic-focused CBT, social-anxiety CBT, CBT for insomnia, trauma-focused CBT, CBT for psychosis, and CBT-based interventions in substance use, eating disorders, and severe mental illness."},{"therapySlug":"graded-exposure","label":"Alternative option","description":"Most useful for phobic avoidance, panic disorder with avoidance, social anxiety disorder, and broader anxiety presentations where the main perpetuating factor is avoidance of feared situations rather than compulsions or trauma re-experiencing. NICE social-anxiety guidance specifically supports exposure to feared or avoided social situations within individual CBT."},{"therapySlug":"applied-relaxation-relaxation-based-therapy","label":"Alternative option","description":"Strongest formal guideline support is for generalised anxiety disorder, where NICE includes applied relaxation as a high-intensity psychological treatment option alongside CBT. It can also be a useful adjunct in broader anxiety care when body tension and rapid arousal are prominent."},{"therapySlug":"worry-focused-cbt","label":"Follow-up option","description":"Best for GAD or transdiagnostic presentations where worry is the dominant maintaining process rather than panic attacks, compulsions, trauma re-experiencing, or social evaluative fear. NICE recommends high-intensity CBT or applied relaxation for GAD when low-intensity options are insufficient or impairment is marked. (NICE)"},{"therapySlug":"panic-focused-cbt","label":"Follow-up option","description":"Best for panic disorder with or without agoraphobia, especially when recurrent panic attacks, bodily-sensation fear, anticipatory anxiety, and avoidance are central. NICE recommends low-intensity self-help for mild to moderate panic disorder and CBT for moderate to severe panic disorder. (NICE)"},{"therapySlug":"social-anxiety-focused-cbt","label":"Follow-up option","description":"Best for social anxiety disorder in adults, and developmentally adapted CBT for children and young people. NICE recommends individual CBT specifically developed for social anxiety disorder as the first intervention for adults, using Clark and Wells or Heimberg models. (NICE)"}]},{"slug":"crisis-risk-pathway","name":"Crisis/risk pathway","clinicalProblem":"Crisis/risk","summary":"Source-grounded workflow assembled from therapies indexed to Crisis/risk. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as decision support only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"crisis-intervention-crisis-oriented-brief-therapy","label":"Initial option","description":"Best for acute crisis presentations where the person needs immediate containment and a short practical intervention. Common settings include ED, crisis team, inpatient admission, CL psychiatry, urgent community review, post-self-harm follow-up, post-discharge vulnerability, and acute psychosocial crisis."},{"therapySlug":"cbt-informed-psychological-intervention-for-self-harm","label":"Alternative option","description":"Best for adults who self-harm and are receiving continuing support after an episode or repeated episodes. Especially high-yield in ED follow-up, community mental health, post-discharge planning, personality vulnerability, recurrent crisis presentations, mixed depression/anxiety/self-harm presentations, and patients where self-harm is linked to identifiable triggers or problem states."},{"therapySlug":"problem-solving-therapy-pst","label":"Alternative option","description":"Most useful for less severe depression, stress-linked depression, adjustment-related difficulty, executive overload, and patients whose distress is closely tied to unresolved current-life problems. It is especially high-yield when the person needs structure more than deep cognitive restructuring."},{"therapySlug":"dialectical-behaviour-therapy-dbt","label":"Follow-up option","description":"Best supported for borderline personality disorder / borderline personality symptoms, especially when recurrent self-harm is a major treatment priority. In current NICE guidance, for women with borderline personality disorder in whom reducing recurrent self-harm is a priority, clinicians should consider a comprehensive DBT programme. In broader contemporary practice, DBT is widely used across genders for comparable borderline-pathology and dysregulation presentations."},{"therapySlug":"coping-skills-interventions","label":"Follow-up option","description":"Best used as a low-intensity or adjunctive intervention for common mental health problems, subthreshold or mixed distress states, adjustment-related difficulty, stress-related functional decline, and as a bridge while waiting for or building toward more specific treatment. Particularly useful where the main task is teaching practical skills rather than deep formulation or disorder-specific exposure or processing work."},{"therapySlug":"brief-supportive-psychotherapy","label":"Follow-up option","description":"Best as a pragmatic short-term intervention in inpatient psychiatry, CL psychiatry, ED/crisis recovery, early engagement, post-discharge follow-up, adjustment to diagnosis, medical illness, grief/stress reactions, and bridging while waiting for more specific therapy. RANZCP identifies supportive psychotherapy as one of the forms of psychotherapy practised by psychiatrists, within psychotherapy as a core component of psychiatric treatment."}]},{"slug":"eating-body-image-pathway","name":"Eating/body image pathway","clinicalProblem":"Eating/body image","summary":"Source-grounded workflow assembled from therapies indexed to Eating/body image. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as decision support only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"eating-disorder-focused-cognitive-behavioural-therapy-cbt-ed-cbt-e","label":"Initial option","description":"Strongest current guideline-backed use is in adults with bulimia nervosa, adults with binge eating disorder, and as one of the main options for adults with anorexia nervosa. NICE recommends individual CBT-ED for adults with bulimia nervosa when guided self-help is unacceptable, contraindicated, or ineffective after 4 weeks; group CBT-ED as the main treatment for adults with binge eating disorder, with individual CBT-ED if group CBT-ED is unavailable or declined; and individual CBT-ED as one of the treatment options for adults with anorexia nervosa alongside MANTRA and SSCM."},{"therapySlug":"family-based-treatment-for-adolescent-anorexia-nervosa-ft-an","label":"Alternative option","description":"Best used for children and young people with anorexia nervosa. NICE recommends anorexia-nervosa-focused family therapy (FT-AN) as the main first-line psychological treatment in this group."},{"therapySlug":"guided-self-help-for-binge-eating-disorder","label":"Alternative option","description":"Best used for adults with binge eating disorder as the initial psychological treatment step. NICE makes this a clear first-line recommendation."},{"therapySlug":"maudsley-anorexia-nervosa-treatment-for-adults-mantra","label":"Follow-up option","description":"Best supported for adults with anorexia nervosa. NICE recommends offering adults with anorexia one of CBT-ED, MANTRA, or SSCM, and explaining the options so the person can help choose their preferred treatment."},{"therapySlug":"specialist-supportive-clinical-management-sscm","label":"Follow-up option","description":"Best supported for adults with anorexia nervosa. NICE recommends offering adults one of CBT-ED, MANTRA, or SSCM and helping them choose by explaining what each involves."},{"therapySlug":"guided-self-help-for-bulimia-nervosa","label":"Follow-up option","description":"Best used for adults with bulimia nervosa as the first psychological treatment step to consider. NICE says to consider bulimia-nervosa-focused guided self-help for adults with bulimia nervosa."}]},{"slug":"grief-loss-pathway","name":"Grief/loss pathway","clinicalProblem":"Grief/loss","summary":"Source-grounded workflow assembled from therapies indexed to Grief/loss. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as decision support only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"interpersonal-psychotherapy-ipt","label":"Initial option","description":"Strongest routine use is depression, especially when symptoms are closely linked to bereavement, changing roles, interpersonal conflict, or isolation. NICE includes IPT as a treatment option for both less severe and more severe depression."},{"therapySlug":"meaning-centred-psychotherapy","label":"Alternative option","description":"Best-supported use is advanced cancer, serious illness, and palliative care, where RCTs and reviews suggest benefit for meaning, spiritual well-being, and existential distress. It is not a broadly guideline-dominant first-line psychotherapy across general psychiatric syndromes. (PubMed)"},{"therapySlug":"brief-supportive-psychotherapy","label":"Alternative option","description":"Best as a pragmatic short-term intervention in inpatient psychiatry, CL psychiatry, ED/crisis recovery, early engagement, post-discharge follow-up, adjustment to diagnosis, medical illness, grief/stress reactions, and bridging while waiting for more specific therapy. RANZCP identifies supportive psychotherapy as one of the forms of psychotherapy practised by psychiatrists, within psychotherapy as a core component of psychiatric treatment."},{"therapySlug":"life-review-therapy-reminiscence-therapy","label":"Follow-up option","description":"Best for older adults with depression/loneliness, dementia-care settings, aged care, palliative/CL psychiatry, and patients needing meaning, identity, continuity or life-story work. Reminiscence therapy has specific evidence in dementia, but effects vary by format and setting."},{"therapySlug":"dignity-therapy","label":"Follow-up option","description":"Best in palliative care, psycho-oncology, advanced illness, neurodegenerative disease, and CL psychiatry where existential distress, dignity, meaning, and legacy are central."},{"therapySlug":"emotion-focused-therapy","label":"Follow-up option","description":"Best for emotionally driven distress where maladaptive emotion processing is central, and especially for couple distress in the couples form. Meta-analyses support emotionally focused couples therapy for reducing couple distress and improving relationship satisfaction, with some maintenance of gains at follow-up. The broader individual EFT evidence base is more supportive than definitive, and much less guideline-prominent in psychiatry than CBT-family therapies. (PubMed)"}]},{"slug":"mood-pathway","name":"Mood pathway","clinicalProblem":"Mood","summary":"Source-grounded workflow assembled from therapies indexed to Mood. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as decision support only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"cognitive-behavioural-therapy-cbt","label":"Initial option","description":"Strongest broad evidence-backed uses are depression and anxiety disorders. It is also a major umbrella treatment family for disorder-specific variants such as panic-focused CBT, social-anxiety CBT, CBT for insomnia, trauma-focused CBT, CBT for psychosis, and CBT-based interventions in substance use, eating disorders, and severe mental illness."},{"therapySlug":"behavioural-activation-ba","label":"Alternative option","description":"Strongly indicated for depression, especially when inactivity, withdrawal, reduced routine, and loss of reinforcement are prominent. It may be particularly useful for patients who struggle with more cognitively demanding therapy models or who need a simpler, action-focused treatment."},{"therapySlug":"interpersonal-psychotherapy-ipt","label":"Alternative option","description":"Strongest routine use is depression, especially when symptoms are closely linked to bereavement, changing roles, interpersonal conflict, or isolation. NICE includes IPT as a treatment option for both less severe and more severe depression."},{"therapySlug":"problem-solving-therapy-pst","label":"Follow-up option","description":"Most useful for less severe depression, stress-linked depression, adjustment-related difficulty, executive overload, and patients whose distress is closely tied to unresolved current-life problems. It is especially high-yield when the person needs structure more than deep cognitive restructuring."},{"therapySlug":"mindfulness-based-cognitive-therapy-mbct","label":"Follow-up option","description":"Strongest guideline-backed use is relapse prevention in recurrent depression. NICE recommends group CBT or MBCT for people at higher risk of relapse, and also lists a mindfulness-based cognitive therapy programme specifically designed for depression as a treatment option in less severe depression."},{"therapySlug":"short-term-psychodynamic-psychotherapy-for-depression-stpp","label":"Follow-up option","description":"Best used for adult depression when relational-emotional patterns and developmental difficulties in close relationships are central. NICE includes STPP in first-line treatment options for adult depression, and the 2023 meta-analysis found STPP superior to no intervention and to usual unstructured treatments for depressive disorders."}]},{"slug":"neurodevelopmental-pathway","name":"Neurodevelopmental pathway","clinicalProblem":"Neurodevelopmental","summary":"Source-grounded workflow assembled from therapies indexed to Neurodevelopmental. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as decision support only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"behavioural-parent-training","label":"Initial option","description":"Best for oppositional defiant disorder, conduct disorder, disruptive behaviour, and children at high risk of conduct disorder. NICE states that parents or carers of children aged 3–11 years with conduct disorder should be offered referral for evidence-based group or individual parent/carer training programmes. (NICE)"},{"therapySlug":"parent-management-training-pmt","label":"Alternative option","description":"Best supported for children with clinical levels of disruptive behaviour, especially oppositional and conduct-type presentations in younger children. It overlaps heavily with NICE’s recommended parent training programmes because those are also built on a social learning model."},{"therapySlug":"social-communication-parent-mediated-autism-interventions","label":"Alternative option","description":"Best supported for children and young people with autism, especially preschool children where NICE says to consider parent, carer or teacher mediation, and for school-aged children where NICE says to consider peer mediation. This is the most direct current mainstream guideline recommendation for treating the core features of autism in children."},{"therapySlug":"developmental-social-skills-interventions","label":"Follow-up option","description":"Best for autistic children/young people and other developmental presentations where social communication is a clear functional target. In autism, NICE specifically supports social-communication interventions adjusted to developmental level and involving parents, carers, teachers, or peers. For adults, NICE supports group-based or individually delivered social learning programmes where social interaction problems are identified. (NICE)"},{"therapySlug":"neurodevelopmentally-adapted-psychosocial-interventions","label":"Follow-up option","description":"Best whenever a standard psychosocial therapy is clinically indicated but the person’s neurodevelopmental profile makes usual delivery ineffective or inaccessible. Core examples include adapted CBT for anxiety/depression, adapted ERP for OCD, adapted DBT skills, behavioural parent work, social-communication interventions, structured life-skills programmes, and functional behaviour support. NICE specifically recommends social-communication interventions for autistic children and young people and social learning or structured life-skills programmes for autistic adults where indicated. (NICE)"},{"therapySlug":"parent-child-interaction-therapy-pcit","label":"Follow-up option","description":"Best supported for young children with clinically significant disruptive behaviour problems. Meta-analysis found PCIT outperformed waitlist for parent-rated disruptive behaviour, with larger effects than PMT in the included comparisons, and a recent systematic review concluded PCIT reduces disruptive behaviours and improves parent–child relationships across diverse settings."}]},{"slug":"pain-somatic-pathway","name":"Pain/somatic pathway","clinicalProblem":"Pain/somatic","summary":"Source-grounded workflow assembled from therapies indexed to Pain/somatic. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as decision support only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"acceptance-and-commitment-therapy-act","label":"Initial option","description":"Most defensible routine psychiatric uses are depression, anxiety-spectrum distress, and broader transdiagnostic emotional disorders when avoidance and fusion are prominent. It also has a formal NICE recommendation for chronic primary pain. In Australian psychiatry, it is best understood as an accepted structured psychotherapy, but not one with as broad a first-line guideline footprint across disorders as standard CBT."},{"therapySlug":"cognitive-behavioural-therapy-cbt","label":"Alternative option","description":"Strongest broad evidence-backed uses are depression and anxiety disorders. It is also a major umbrella treatment family for disorder-specific variants such as panic-focused CBT, social-anxiety CBT, CBT for insomnia, trauma-focused CBT, CBT for psychosis, and CBT-based interventions in substance use, eating disorders, and severe mental illness."},{"therapySlug":"health-anxiety-focused-cbt","label":"Alternative option","description":"Best for persistent health anxiety where adequate medical assessment has not found an explanatory serious disease and the main maintaining mechanism is anxiety-driven misinterpretation and reassurance-seeking. A meta-analysis of 13 RCTs found CBT outperformed control conditions for hypochondriasis/health anxiety at post-treatment and follow-up. (PubMed)"},{"therapySlug":"mindfulness-based-stress-reduction","label":"Follow-up option","description":"Best as a structured mindfulness intervention for stress, depressive symptoms, and broader distress where mindfulness practice is acceptable and safe. Recent meta-analyses suggest benefit for depressive symptoms across mental disorders and for depression/PTSD in veteran samples, but MBSR is not generally a first-line substitute for more specific psychiatric psychotherapies such as ERP, TF-CBT, or comprehensive DBT. (PubMed)"},{"therapySlug":"applied-relaxation-relaxation-based-therapy","label":"Follow-up option","description":"Strongest formal guideline support is for generalised anxiety disorder, where NICE includes applied relaxation as a high-intensity psychological treatment option alongside CBT. It can also be a useful adjunct in broader anxiety care when body tension and rapid arousal are prominent."},{"therapySlug":"mindfulness-based-cognitive-therapy-mbct","label":"Follow-up option","description":"Strongest guideline-backed use is relapse prevention in recurrent depression. NICE recommends group CBT or MBCT for people at higher risk of relapse, and also lists a mindfulness-based cognitive therapy programme specifically designed for depression as a treatment option in less severe depression."}]},{"slug":"personality-interpersonal-pathway","name":"Personality/interpersonal pathway","clinicalProblem":"Personality/interpersonal","summary":"Source-grounded workflow assembled from therapies indexed to Personality/interpersonal. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as decision support only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"dialectical-behaviour-therapy-dbt","label":"Initial option","description":"Best supported for borderline personality disorder / borderline personality symptoms, especially when recurrent self-harm is a major treatment priority. In current NICE guidance, for women with borderline personality disorder in whom reducing recurrent self-harm is a priority, clinicians should consider a comprehensive DBT programme. In broader contemporary practice, DBT is widely used across genders for comparable borderline-pathology and dysregulation presentations."},{"therapySlug":"mentalisation-based-therapy-mbt","label":"Alternative option","description":"Best supported for borderline personality disorder and related severe personality dysfunction where attachment stress and relational misinterpretation are central. Unlike DBT, MBT is not specifically singled out in NICE BPD recommendations, but it is a recognised structured psychotherapy and has supportive trial and review evidence."},{"therapySlug":"schema-therapy","label":"Alternative option","description":"Strongest and clearest use is personality disorder, especially borderline personality disorder (BPD) and other chronic personality pathology. Current evidence suggests schema therapy is an effective specialist treatment for BPD, but NICE BPD guidance does not single it out by name in the way it mentions DBT for recurrent self-harm."},{"therapySlug":"structured-clinical-management","label":"Follow-up option","description":"Best for BPD/personality disorder in public-sector or general mental health settings where a structured, consistent, manualised clinical model is needed and specialist therapies may not be available. SCM has been used as a comparator in trials against MBT, with one trial describing it as protocol-driven best current clinical practice delivered by non-specialist practitioners in a publicly funded service. (SpringerLink)"},{"therapySlug":"good-psychiatric-management","label":"Follow-up option","description":"Best for borderline personality disorder or clinically significant borderline traits, especially in general psychiatric, community, outpatient, ED follow-up, CL, and public-sector settings where full DBT, MBT, schema therapy, or TFP is unavailable or not required. Recent literature describes GPM as “good enough,” easier to implement, principle-based, and adaptable for stepped care. (PubMed)"},{"therapySlug":"transference-focused-psychotherapy-tfp","label":"Follow-up option","description":"Best supported for borderline personality disorder and closely related severe personality organisation. It is a specialist treatment option with supportive evidence from trials and reviews, but it is not specifically privileged by NICE in the way that DBT is mentioned for recurrent self-harm in women with BPD."}]},{"slug":"psychosis-pathway","name":"Psychosis pathway","clinicalProblem":"Psychosis","summary":"Source-grounded workflow assembled from therapies indexed to Psychosis. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as decision support only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"cognitive-behavioural-therapy-for-psychosis-cbtp","label":"Initial option","description":"Best supported for psychosis and schizophrenia, including people at increased risk of psychosis, first and subsequent acute episodes, and the recovery phase when positive or negative symptoms continue to affect distress or function. It is particularly useful when the clinical goal is to reduce distress and improve functioning rather than to “argue away” psychotic experiences."},{"therapySlug":"family-intervention-for-psychosis","label":"Alternative option","description":"Best supported for adults with psychosis or schizophrenia who live with or are in close contact with family members or carers. NICE quality standards state that family members of adults with psychosis or schizophrenia should be offered family intervention because it improves coping skills and relapse rates."},{"therapySlug":"psychoeducation-for-psychosis","label":"Alternative option","description":"Broadly useful across first-episode psychosis, established schizophrenia-spectrum illness, relapse prevention, discharge planning, rehabilitation, and self-management work. It is especially high-yield when the person needs a clearer model of symptoms, treatment, relapse risk, and what to do if symptoms worsen."},{"therapySlug":"cognitive-remediation-therapy-crt","label":"Follow-up option","description":"Best supported in rehabilitation for adults with complex psychosis, particularly when cognitive impairment is contributing to poor everyday function, educational difficulty, or problems engaging in vocational recovery. NICE specifically recommends considering cognitive remediation alongside vocational rehabilitation services."},{"therapySlug":"illness-management-and-recovery-style-interventions-imr-style-interventions","label":"Follow-up option","description":"Most useful in severe mental illness, especially schizophrenia-spectrum disorders and other long-term psychotic illnesses, when the clinical task is ongoing recovery and self-management rather than acute symptom containment alone. It fits best in rehabilitation and continuing community care."},{"therapySlug":"supported-employment-individual-placement-and-support-ips","label":"Follow-up option","description":"Best supported for psychosis / schizophrenia and complex psychosis rehabilitation when the person wants mainstream employment. NICE says that for people who want to work towards mainstream employment, clinicians should consider referral to supported employment using the IPS approach."}]},{"slug":"sleep-pathway","name":"Sleep pathway","clinicalProblem":"Sleep","summary":"Source-grounded workflow assembled from therapies indexed to Sleep. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as decision support only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"cognitive-behavioural-therapy-for-insomnia-cbt-i","label":"Initial option","description":"Best used for chronic insomnia disorder in adults of any age, including people with comorbid conditions. Current European and AASM guidance place CBT-I as first-line treatment, and Australian Sleep Health Foundation material states CBT-I is the recommended best first treatment in Australian practice."},{"therapySlug":"sleep-compression-therapy-for-insomnia","label":"Alternative option","description":"Best used for chronic insomnia disorder when the clinician wants the core logic of sleep restriction but in a more tolerable, gradual format. Current high-quality evidence suggests it may be a practical alternative when standard sleep restriction feels too harsh or is poorly tolerated."},{"therapySlug":"mindfulness-based-therapy-for-insomnia-mbti","label":"Alternative option","description":"Best viewed as an evidence-supported option for chronic insomnia, especially when arousal, worry, and reactive struggle with sleep are prominent. Current insomnia guidelines still place full CBT-I first-line, so MBTI should not be described as guideline-superior to CBT-I."},{"therapySlug":"imagery-rehearsal-therapy-irt-for-nightmare-disorder","label":"Follow-up option","description":"Best used for nightmare disorder in adults and for persistent distressing nightmares in broader psychiatric populations. The 2018 AASM position paper states IRT is the only treatment strategy recommended for all patients with nightmare disorder."},{"therapySlug":"bright-light-therapy","label":"Follow-up option","description":"Best as an adjunctive treatment for depressive disorders when a low-burden somatic option is attractive, especially where circadian disruption or preference for non-drug augmentation is relevant. The 2024 JAMA Psychiatry meta-analysis found significantly better remission and response rates with BLT in nonseasonal depressive disorders, but this is not the same as saying BLT should replace established first-line psychotherapy or pharmacotherapy. (JAMA Network)"},{"therapySlug":"circadian-rhythm-based-interventions","label":"Follow-up option","description":"Best-supported psychiatric uses are 2 main groups. First, bipolar disorder, where IPSRT has evidence as an adjunctive acute and prophylactic intervention addressing rhythm dysregulation. Second, depression, where circadian realignment and chronotherapeutic approaches, including wake-therapy-type interventions, show antidepressant potential, though the depression evidence is more heterogeneous and implementation-sensitive than for major established psychotherapies. (PubMed)"}]},{"slug":"substance-use-pathway","name":"Substance use pathway","clinicalProblem":"Substance use","summary":"Source-grounded workflow assembled from therapies indexed to Substance use. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as decision support only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"motivational-interviewing-mi-for-substance-use-disorders","label":"Initial option","description":"Best used at engagement, assessment, early treatment, and whenever motivation is unstable. It is especially useful for alcohol misuse, broader substance use disorders, and patients who are reluctant, unsure, or inconsistent in change efforts. NICE alcohol guidance makes motivational intervention universal at intake, and SAMHSA TIP 35 positions MI as a core SUD treatment approach for enhancing participation and retention."},{"therapySlug":"relapse-prevention-therapy-for-substance-use-disorders","label":"Alternative option","description":"Best used after initial motivation has improved and the patient is actively trying to reduce, stop, or maintain abstinence, especially in alcohol use disorder and broader substance use disorders. NICE alcohol guidance recommends offering community-based interventions to promote abstinence or moderate drinking and prevent relapse, and recommends CBT/behavioural therapies focused on alcohol-related problems."},{"therapySlug":"contingency-management-cm","label":"Alternative option","description":"Best used for stimulant use disorder, for illicit drug use in methadone maintenance, and for engagement / abstinence targets in drug services. NICE explicitly recommends introducing CM to reduce illicit drug use and/or promote engagement for people on methadone maintenance and for people who primarily misuse stimulants."},{"therapySlug":"community-reinforcement-approach","label":"Follow-up option","description":"Best for alcohol and other drug use disorders where lifestyle, reinforcement, social context, and recovery capital are central. Evidence is strongest historically for alcohol, cocaine, and opioid-related disorders, but it should be framed as one structured addiction therapy rather than a universal replacement for pharmacotherapy, withdrawal care, or contingency management. A systematic review found limited-to-moderate evidence for CRA, with or without medication or contingency management, across alcohol and substance-related disorders. (NCBI)"},{"therapySlug":"mindfulness-based-relapse-prevention-mbrp","label":"Follow-up option","description":"Best viewed as an adjunctive or selective relapse-prevention treatment for SUDs rather than a clearly dominant stand-alone first-line therapy. The 2025 systematic review and meta-analysis found small benefits for withdrawal/craving symptoms and negative consequences of substance use, but no statistically significant differences versus comparators for relapse, frequency of use, treatment dropout, depressive symptoms, anxiety symptoms, or mindfulness scores overall."},{"therapySlug":"twelve-step-facilitation-tsf","label":"Follow-up option","description":"The strongest evidence is for alcohol use disorder (AUD). A 2020 Cochrane review found AA/TSF was at least as effective as other established treatments and often better for continuous abstinence and remission over follow-up, with evidence of healthcare cost savings. It is more accurate to present TSF as especially evidence-supported for AUD than as equally established across all SUDs. (cochrane.org)"}]},{"slug":"trauma-pathway","name":"Trauma pathway","clinicalProblem":"Trauma","summary":"Source-grounded workflow assembled from therapies indexed to Trauma. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as decision support only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"trauma-focused-cognitive-behavioural-therapy-tf-cbt","label":"Initial option","description":"Strongest use is PTSD. It is also appropriate for clinically important post-traumatic symptoms after trauma, depending on timing, severity, and readiness. In Australian guidelines, TF-CBT, CPT, CT, and PE are all recommended adult PTSD treatments."},{"therapySlug":"eye-movement-desensitisation-and-reprocessing-emdr","label":"Alternative option","description":"For adults with PTSD, Phoenix Australia gives EMDR a strong recommendation. NICE recommends EMDR for adults with PTSD or clinically important PTSD symptoms more than 3 months after non-combat-related trauma, and suggests considering it between 1 and 3 months after non-combat trauma if the person prefers EMDR."},{"therapySlug":"cognitive-processing-therapy-cpt","label":"Alternative option","description":"Strongest use is PTSD. Australian guidelines give a strong recommendation for CPT in adults with PTSD. It is especially useful when maladaptive trauma meanings, guilt, shame, and self-blame are central."},{"therapySlug":"prolonged-exposure-pe","label":"Follow-up option","description":"Strongest use is PTSD in adults. Phoenix Australia gives a strong recommendation for PE in adult PTSD. NICE also includes prolonged exposure therapy within recommended adult trauma-focused CBT interventions."},{"therapySlug":"narrative-exposure-therapy-net","label":"Follow-up option","description":"In Australian PTSD guidelines, NET has a conditional recommendation for adults with PTSD where trauma is linked to genocide, civil conflict, torture, political detention, or displacement. It is best understood as a selective trauma therapy, not a universal first-line PTSD treatment alongside TF-CBT, CT, CPT, PE, or EMDR."},{"therapySlug":"written-exposure-therapy","label":"Follow-up option","description":"Best as a brief trauma-focused PTSD treatment option when a concise, lower-burden exposure-based therapy is needed. Current VA/DoD guidance places WET as a second-line PTSD psychotherapy, not above PE, CPT, or EMDR. It is not currently included in NICE or Phoenix Australia PTSD guideline recommendations, so in Australian practice it should be framed as promising and evidence-supported internationally, but not yet an Australian first-line guideline therapy."}]}]
\ No newline at end of file
+[{"slug":"anxiety-pathway","name":"Anxiety pathway","clinicalProblem":"Anxiety","summary":"Source-grounded workflow assembled from therapies indexed to Anxiety. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as source-grounded therapy reference only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"cognitive-behavioural-therapy-cbt","label":"Initial option","description":"Strongest broad evidence-backed uses are depression and anxiety disorders. It is also a major umbrella treatment family for disorder-specific variants such as panic-focused CBT, social-anxiety CBT, CBT for insomnia, trauma-focused CBT, CBT for psychosis, and CBT-based interventions in substance use, eating disorders, and severe mental illness."},{"therapySlug":"graded-exposure","label":"Alternative option","description":"Most useful for phobic avoidance, panic disorder with avoidance, social anxiety disorder, and broader anxiety presentations where the main perpetuating factor is avoidance of feared situations rather than compulsions or trauma re-experiencing. NICE social-anxiety guidance specifically supports exposure to feared or avoided social situations within individual CBT."},{"therapySlug":"applied-relaxation-relaxation-based-therapy","label":"Alternative option","description":"Strongest formal guideline support is for generalised anxiety disorder, where NICE includes applied relaxation as a high-intensity psychological treatment option alongside CBT. It can also be a useful adjunct in broader anxiety care when body tension and rapid arousal are prominent."},{"therapySlug":"worry-focused-cbt","label":"Follow-up option","description":"Best for GAD or transdiagnostic presentations where worry is the dominant maintaining process rather than panic attacks, compulsions, trauma re-experiencing, or social evaluative fear. NICE recommends high-intensity CBT or applied relaxation for GAD when low-intensity options are insufficient or impairment is marked. (NICE)"},{"therapySlug":"panic-focused-cbt","label":"Follow-up option","description":"Best for panic disorder with or without agoraphobia, especially when recurrent panic attacks, bodily-sensation fear, anticipatory anxiety, and avoidance are central. NICE recommends low-intensity self-help for mild to moderate panic disorder and CBT for moderate to severe panic disorder. (NICE)"},{"therapySlug":"social-anxiety-focused-cbt","label":"Follow-up option","description":"Best for social anxiety disorder in adults, and developmentally adapted CBT for children and young people. NICE recommends individual CBT specifically developed for social anxiety disorder as the first intervention for adults, using Clark and Wells or Heimberg models. (NICE)"}]},{"slug":"crisis-risk-pathway","name":"Crisis/risk pathway","clinicalProblem":"Crisis/risk","summary":"Source-grounded workflow assembled from therapies indexed to Crisis/risk. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as source-grounded therapy reference only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"crisis-intervention-crisis-oriented-brief-therapy","label":"Initial option","description":"Best for acute crisis presentations where the person needs immediate containment and a short practical intervention. Common settings include ED, crisis team, inpatient admission, CL psychiatry, urgent community review, post-self-harm follow-up, post-discharge vulnerability, and acute psychosocial crisis."},{"therapySlug":"cbt-informed-psychological-intervention-for-self-harm","label":"Alternative option","description":"Best for adults who self-harm and are receiving continuing support after an episode or repeated episodes. Especially high-yield in ED follow-up, community mental health, post-discharge planning, personality vulnerability, recurrent crisis presentations, mixed depression/anxiety/self-harm presentations, and patients where self-harm is linked to identifiable triggers or problem states."},{"therapySlug":"problem-solving-therapy-pst","label":"Alternative option","description":"Most useful for less severe depression, stress-linked depression, adjustment-related difficulty, executive overload, and patients whose distress is closely tied to unresolved current-life problems. It is especially high-yield when the person needs structure more than deep cognitive restructuring."},{"therapySlug":"dialectical-behaviour-therapy-dbt","label":"Follow-up option","description":"Best supported for borderline personality disorder / borderline personality symptoms, especially when recurrent self-harm is a major treatment priority. In current NICE guidance, for women with borderline personality disorder in whom reducing recurrent self-harm is a priority, clinicians should consider a comprehensive DBT programme. In broader contemporary practice, DBT is widely used across genders for comparable borderline-pathology and dysregulation presentations."},{"therapySlug":"coping-skills-interventions","label":"Follow-up option","description":"Best used as a low-intensity or adjunctive intervention for common mental health problems, subthreshold or mixed distress states, adjustment-related difficulty, stress-related functional decline, and as a bridge while waiting for or building toward more specific treatment. Particularly useful where the main task is teaching practical skills rather than deep formulation or disorder-specific exposure or processing work."},{"therapySlug":"brief-supportive-psychotherapy","label":"Follow-up option","description":"Best as a pragmatic short-term intervention in inpatient psychiatry, CL psychiatry, ED/crisis recovery, early engagement, post-discharge follow-up, adjustment to diagnosis, medical illness, grief/stress reactions, and bridging while waiting for more specific therapy. RANZCP identifies supportive psychotherapy as one of the forms of psychotherapy practised by psychiatrists, within psychotherapy as a core component of psychiatric treatment."}]},{"slug":"eating-body-image-pathway","name":"Eating/body image pathway","clinicalProblem":"Eating/body image","summary":"Source-grounded workflow assembled from therapies indexed to Eating/body image. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as source-grounded therapy reference only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"eating-disorder-focused-cognitive-behavioural-therapy-cbt-ed-cbt-e","label":"Initial option","description":"Strongest current guideline-backed use is in adults with bulimia nervosa, adults with binge eating disorder, and as one of the main options for adults with anorexia nervosa. NICE recommends individual CBT-ED for adults with bulimia nervosa when guided self-help is unacceptable, contraindicated, or ineffective after 4 weeks; group CBT-ED as the main treatment for adults with binge eating disorder, with individual CBT-ED if group CBT-ED is unavailable or declined; and individual CBT-ED as one of the treatment options for adults with anorexia nervosa alongside MANTRA and SSCM."},{"therapySlug":"family-based-treatment-for-adolescent-anorexia-nervosa-ft-an","label":"Alternative option","description":"Best used for children and young people with anorexia nervosa. NICE recommends anorexia-nervosa-focused family therapy (FT-AN) as the main first-line psychological treatment in this group."},{"therapySlug":"guided-self-help-for-binge-eating-disorder","label":"Alternative option","description":"Best used for adults with binge eating disorder as the initial psychological treatment step. NICE makes this a clear first-line recommendation."},{"therapySlug":"maudsley-anorexia-nervosa-treatment-for-adults-mantra","label":"Follow-up option","description":"Best supported for adults with anorexia nervosa. NICE recommends offering adults with anorexia one of CBT-ED, MANTRA, or SSCM, and explaining the options so the person can help choose their preferred treatment."},{"therapySlug":"specialist-supportive-clinical-management-sscm","label":"Follow-up option","description":"Best supported for adults with anorexia nervosa. NICE recommends offering adults one of CBT-ED, MANTRA, or SSCM and helping them choose by explaining what each involves."},{"therapySlug":"guided-self-help-for-bulimia-nervosa","label":"Follow-up option","description":"Best used for adults with bulimia nervosa as the first psychological treatment step to consider. NICE says to consider bulimia-nervosa-focused guided self-help for adults with bulimia nervosa."}]},{"slug":"grief-loss-pathway","name":"Grief/loss pathway","clinicalProblem":"Grief/loss","summary":"Source-grounded workflow assembled from therapies indexed to Grief/loss. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as source-grounded therapy reference only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"interpersonal-psychotherapy-ipt","label":"Initial option","description":"Strongest routine use is depression, especially when symptoms are closely linked to bereavement, changing roles, interpersonal conflict, or isolation. NICE includes IPT as a treatment option for both less severe and more severe depression."},{"therapySlug":"meaning-centred-psychotherapy","label":"Alternative option","description":"Best-supported use is advanced cancer, serious illness, and palliative care, where RCTs and reviews suggest benefit for meaning, spiritual well-being, and existential distress. It is not a broadly guideline-dominant first-line psychotherapy across general psychiatric syndromes. (PubMed)"},{"therapySlug":"brief-supportive-psychotherapy","label":"Alternative option","description":"Best as a pragmatic short-term intervention in inpatient psychiatry, CL psychiatry, ED/crisis recovery, early engagement, post-discharge follow-up, adjustment to diagnosis, medical illness, grief/stress reactions, and bridging while waiting for more specific therapy. RANZCP identifies supportive psychotherapy as one of the forms of psychotherapy practised by psychiatrists, within psychotherapy as a core component of psychiatric treatment."},{"therapySlug":"life-review-therapy-reminiscence-therapy","label":"Follow-up option","description":"Best for older adults with depression/loneliness, dementia-care settings, aged care, palliative/CL psychiatry, and patients needing meaning, identity, continuity or life-story work. Reminiscence therapy has specific evidence in dementia, but effects vary by format and setting."},{"therapySlug":"dignity-therapy","label":"Follow-up option","description":"Best in palliative care, psycho-oncology, advanced illness, neurodegenerative disease, and CL psychiatry where existential distress, dignity, meaning, and legacy are central."},{"therapySlug":"emotion-focused-therapy","label":"Follow-up option","description":"Best for emotionally driven distress where maladaptive emotion processing is central, and especially for couple distress in the couples form. Meta-analyses support emotionally focused couples therapy for reducing couple distress and improving relationship satisfaction, with some maintenance of gains at follow-up. The broader individual EFT evidence base is more supportive than definitive, and much less guideline-prominent in psychiatry than CBT-family therapies. (PubMed)"}]},{"slug":"mood-pathway","name":"Mood pathway","clinicalProblem":"Mood","summary":"Source-grounded workflow assembled from therapies indexed to Mood. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as source-grounded therapy reference only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"cognitive-behavioural-therapy-cbt","label":"Initial option","description":"Strongest broad evidence-backed uses are depression and anxiety disorders. It is also a major umbrella treatment family for disorder-specific variants such as panic-focused CBT, social-anxiety CBT, CBT for insomnia, trauma-focused CBT, CBT for psychosis, and CBT-based interventions in substance use, eating disorders, and severe mental illness."},{"therapySlug":"behavioural-activation-ba","label":"Alternative option","description":"Strongly indicated for depression, especially when inactivity, withdrawal, reduced routine, and loss of reinforcement are prominent. It may be particularly useful for patients who struggle with more cognitively demanding therapy models or who need a simpler, action-focused treatment."},{"therapySlug":"interpersonal-psychotherapy-ipt","label":"Alternative option","description":"Strongest routine use is depression, especially when symptoms are closely linked to bereavement, changing roles, interpersonal conflict, or isolation. NICE includes IPT as a treatment option for both less severe and more severe depression."},{"therapySlug":"problem-solving-therapy-pst","label":"Follow-up option","description":"Most useful for less severe depression, stress-linked depression, adjustment-related difficulty, executive overload, and patients whose distress is closely tied to unresolved current-life problems. It is especially high-yield when the person needs structure more than deep cognitive restructuring."},{"therapySlug":"mindfulness-based-cognitive-therapy-mbct","label":"Follow-up option","description":"Strongest guideline-backed use is relapse prevention in recurrent depression. NICE recommends group CBT or MBCT for people at higher risk of relapse, and also lists a mindfulness-based cognitive therapy programme specifically designed for depression as a treatment option in less severe depression."},{"therapySlug":"short-term-psychodynamic-psychotherapy-for-depression-stpp","label":"Follow-up option","description":"Best used for adult depression when relational-emotional patterns and developmental difficulties in close relationships are central. NICE includes STPP in first-line treatment options for adult depression, and the 2023 meta-analysis found STPP superior to no intervention and to usual unstructured treatments for depressive disorders."}]},{"slug":"neurodevelopmental-pathway","name":"Neurodevelopmental pathway","clinicalProblem":"Neurodevelopmental","summary":"Source-grounded workflow assembled from therapies indexed to Neurodevelopmental. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as source-grounded therapy reference only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"behavioural-parent-training","label":"Initial option","description":"Best for oppositional defiant disorder, conduct disorder, disruptive behaviour, and children at high risk of conduct disorder. NICE states that parents or carers of children aged 3–11 years with conduct disorder should be offered referral for evidence-based group or individual parent/carer training programmes. (NICE)"},{"therapySlug":"parent-management-training-pmt","label":"Alternative option","description":"Best supported for children with clinical levels of disruptive behaviour, especially oppositional and conduct-type presentations in younger children. It overlaps heavily with NICE’s recommended parent training programmes because those are also built on a social learning model."},{"therapySlug":"social-communication-parent-mediated-autism-interventions","label":"Alternative option","description":"Best supported for children and young people with autism, especially preschool children where NICE says to consider parent, carer or teacher mediation, and for school-aged children where NICE says to consider peer mediation. This is the most direct current mainstream guideline recommendation for treating the core features of autism in children."},{"therapySlug":"developmental-social-skills-interventions","label":"Follow-up option","description":"Best for autistic children/young people and other developmental presentations where social communication is a clear functional target. In autism, NICE specifically supports social-communication interventions adjusted to developmental level and involving parents, carers, teachers, or peers. For adults, NICE supports group-based or individually delivered social learning programmes where social interaction problems are identified. (NICE)"},{"therapySlug":"neurodevelopmentally-adapted-psychosocial-interventions","label":"Follow-up option","description":"Best whenever a standard psychosocial therapy is clinically indicated but the person’s neurodevelopmental profile makes usual delivery ineffective or inaccessible. Core examples include adapted CBT for anxiety/depression, adapted ERP for OCD, adapted DBT skills, behavioural parent work, social-communication interventions, structured life-skills programmes, and functional behaviour support. NICE specifically recommends social-communication interventions for autistic children and young people and social learning or structured life-skills programmes for autistic adults where indicated. (NICE)"},{"therapySlug":"parent-child-interaction-therapy-pcit","label":"Follow-up option","description":"Best supported for young children with clinically significant disruptive behaviour problems. Meta-analysis found PCIT outperformed waitlist for parent-rated disruptive behaviour, with larger effects than PMT in the included comparisons, and a recent systematic review concluded PCIT reduces disruptive behaviours and improves parent–child relationships across diverse settings."}]},{"slug":"pain-somatic-pathway","name":"Pain/somatic pathway","clinicalProblem":"Pain/somatic","summary":"Source-grounded workflow assembled from therapies indexed to Pain/somatic. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as source-grounded therapy reference only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"acceptance-and-commitment-therapy-act","label":"Initial option","description":"Most defensible routine psychiatric uses are depression, anxiety-spectrum distress, and broader transdiagnostic emotional disorders when avoidance and fusion are prominent. It also has a formal NICE recommendation for chronic primary pain. In Australian psychiatry, it is best understood as an accepted structured psychotherapy, but not one with as broad a first-line guideline footprint across disorders as standard CBT."},{"therapySlug":"cognitive-behavioural-therapy-cbt","label":"Alternative option","description":"Strongest broad evidence-backed uses are depression and anxiety disorders. It is also a major umbrella treatment family for disorder-specific variants such as panic-focused CBT, social-anxiety CBT, CBT for insomnia, trauma-focused CBT, CBT for psychosis, and CBT-based interventions in substance use, eating disorders, and severe mental illness."},{"therapySlug":"health-anxiety-focused-cbt","label":"Alternative option","description":"Best for persistent health anxiety where adequate medical assessment has not found an explanatory serious disease and the main maintaining mechanism is anxiety-driven misinterpretation and reassurance-seeking. A meta-analysis of 13 RCTs found CBT outperformed control conditions for hypochondriasis/health anxiety at post-treatment and follow-up. (PubMed)"},{"therapySlug":"mindfulness-based-stress-reduction","label":"Follow-up option","description":"Best as a structured mindfulness intervention for stress, depressive symptoms, and broader distress where mindfulness practice is acceptable and safe. Recent meta-analyses suggest benefit for depressive symptoms across mental disorders and for depression/PTSD in veteran samples, but MBSR is not generally a first-line substitute for more specific psychiatric psychotherapies such as ERP, TF-CBT, or comprehensive DBT. (PubMed)"},{"therapySlug":"applied-relaxation-relaxation-based-therapy","label":"Follow-up option","description":"Strongest formal guideline support is for generalised anxiety disorder, where NICE includes applied relaxation as a high-intensity psychological treatment option alongside CBT. It can also be a useful adjunct in broader anxiety care when body tension and rapid arousal are prominent."},{"therapySlug":"mindfulness-based-cognitive-therapy-mbct","label":"Follow-up option","description":"Strongest guideline-backed use is relapse prevention in recurrent depression. NICE recommends group CBT or MBCT for people at higher risk of relapse, and also lists a mindfulness-based cognitive therapy programme specifically designed for depression as a treatment option in less severe depression."}]},{"slug":"personality-interpersonal-pathway","name":"Personality/interpersonal pathway","clinicalProblem":"Personality/interpersonal","summary":"Source-grounded workflow assembled from therapies indexed to Personality/interpersonal. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as source-grounded therapy reference only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"dialectical-behaviour-therapy-dbt","label":"Initial option","description":"Best supported for borderline personality disorder / borderline personality symptoms, especially when recurrent self-harm is a major treatment priority. In current NICE guidance, for women with borderline personality disorder in whom reducing recurrent self-harm is a priority, clinicians should consider a comprehensive DBT programme. In broader contemporary practice, DBT is widely used across genders for comparable borderline-pathology and dysregulation presentations."},{"therapySlug":"mentalisation-based-therapy-mbt","label":"Alternative option","description":"Best supported for borderline personality disorder and related severe personality dysfunction where attachment stress and relational misinterpretation are central. Unlike DBT, MBT is not specifically singled out in NICE BPD recommendations, but it is a recognised structured psychotherapy and has supportive trial and review evidence."},{"therapySlug":"schema-therapy","label":"Alternative option","description":"Strongest and clearest use is personality disorder, especially borderline personality disorder (BPD) and other chronic personality pathology. Current evidence suggests schema therapy is an effective specialist treatment for BPD, but NICE BPD guidance does not single it out by name in the way it mentions DBT for recurrent self-harm."},{"therapySlug":"structured-clinical-management","label":"Follow-up option","description":"Best for BPD/personality disorder in public-sector or general mental health settings where a structured, consistent, manualised clinical model is needed and specialist therapies may not be available. SCM has been used as a comparator in trials against MBT, with one trial describing it as protocol-driven best current clinical practice delivered by non-specialist practitioners in a publicly funded service. (SpringerLink)"},{"therapySlug":"good-psychiatric-management","label":"Follow-up option","description":"Best for borderline personality disorder or clinically significant borderline traits, especially in general psychiatric, community, outpatient, ED follow-up, CL, and public-sector settings where full DBT, MBT, schema therapy, or TFP is unavailable or not required. Recent literature describes GPM as “good enough,” easier to implement, principle-based, and adaptable for stepped care. (PubMed)"},{"therapySlug":"transference-focused-psychotherapy-tfp","label":"Follow-up option","description":"Best supported for borderline personality disorder and closely related severe personality organisation. It is a specialist treatment option with supportive evidence from trials and reviews, but it is not specifically privileged by NICE in the way that DBT is mentioned for recurrent self-harm in women with BPD."}]},{"slug":"psychosis-pathway","name":"Psychosis pathway","clinicalProblem":"Psychosis","summary":"Source-grounded workflow assembled from therapies indexed to Psychosis. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as source-grounded therapy reference only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"cognitive-behavioural-therapy-for-psychosis-cbtp","label":"Initial option","description":"Best supported for psychosis and schizophrenia, including people at increased risk of psychosis, first and subsequent acute episodes, and the recovery phase when positive or negative symptoms continue to affect distress or function. It is particularly useful when the clinical goal is to reduce distress and improve functioning rather than to “argue away” psychotic experiences."},{"therapySlug":"family-intervention-for-psychosis","label":"Alternative option","description":"Best supported for adults with psychosis or schizophrenia who live with or are in close contact with family members or carers. NICE quality standards state that family members of adults with psychosis or schizophrenia should be offered family intervention because it improves coping skills and relapse rates."},{"therapySlug":"psychoeducation-for-psychosis","label":"Alternative option","description":"Broadly useful across first-episode psychosis, established schizophrenia-spectrum illness, relapse prevention, discharge planning, rehabilitation, and self-management work. It is especially high-yield when the person needs a clearer model of symptoms, treatment, relapse risk, and what to do if symptoms worsen."},{"therapySlug":"cognitive-remediation-therapy-crt","label":"Follow-up option","description":"Best supported in rehabilitation for adults with complex psychosis, particularly when cognitive impairment is contributing to poor everyday function, educational difficulty, or problems engaging in vocational recovery. NICE specifically recommends considering cognitive remediation alongside vocational rehabilitation services."},{"therapySlug":"illness-management-and-recovery-style-interventions-imr-style-interventions","label":"Follow-up option","description":"Most useful in severe mental illness, especially schizophrenia-spectrum disorders and other long-term psychotic illnesses, when the clinical task is ongoing recovery and self-management rather than acute symptom containment alone. It fits best in rehabilitation and continuing community care."},{"therapySlug":"supported-employment-individual-placement-and-support-ips","label":"Follow-up option","description":"Best supported for psychosis / schizophrenia and complex psychosis rehabilitation when the person wants mainstream employment. NICE says that for people who want to work towards mainstream employment, clinicians should consider referral to supported employment using the IPS approach."}]},{"slug":"sleep-pathway","name":"Sleep pathway","clinicalProblem":"Sleep","summary":"Source-grounded workflow assembled from therapies indexed to Sleep. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as source-grounded therapy reference only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"cognitive-behavioural-therapy-for-insomnia-cbt-i","label":"Initial option","description":"Best used for chronic insomnia disorder in adults of any age, including people with comorbid conditions. Current European and AASM guidance place CBT-I as first-line treatment, and Australian Sleep Health Foundation material states CBT-I is the recommended best first treatment in Australian practice."},{"therapySlug":"sleep-compression-therapy-for-insomnia","label":"Alternative option","description":"Best used for chronic insomnia disorder when the clinician wants the core logic of sleep restriction but in a more tolerable, gradual format. Current high-quality evidence suggests it may be a practical alternative when standard sleep restriction feels too harsh or is poorly tolerated."},{"therapySlug":"mindfulness-based-therapy-for-insomnia-mbti","label":"Alternative option","description":"Best viewed as an evidence-supported option for chronic insomnia, especially when arousal, worry, and reactive struggle with sleep are prominent. Current insomnia guidelines still place full CBT-I first-line, so MBTI should not be described as guideline-superior to CBT-I."},{"therapySlug":"imagery-rehearsal-therapy-irt-for-nightmare-disorder","label":"Follow-up option","description":"Best used for nightmare disorder in adults and for persistent distressing nightmares in broader psychiatric populations. The 2018 AASM position paper states IRT is the only treatment strategy recommended for all patients with nightmare disorder."},{"therapySlug":"bright-light-therapy","label":"Follow-up option","description":"Best as an adjunctive treatment for depressive disorders when a low-burden somatic option is attractive, especially where circadian disruption or preference for non-drug augmentation is relevant. The 2024 JAMA Psychiatry meta-analysis found significantly better remission and response rates with BLT in nonseasonal depressive disorders, but this is not the same as saying BLT should replace established first-line psychotherapy or pharmacotherapy. (JAMA Network)"},{"therapySlug":"circadian-rhythm-based-interventions","label":"Follow-up option","description":"Best-supported psychiatric uses are 2 main groups. First, bipolar disorder, where IPSRT has evidence as an adjunctive acute and prophylactic intervention addressing rhythm dysregulation. Second, depression, where circadian realignment and chronotherapeutic approaches, including wake-therapy-type interventions, show antidepressant potential, though the depression evidence is more heterogeneous and implementation-sensitive than for major established psychotherapies. (PubMed)"}]},{"slug":"substance-use-pathway","name":"Substance use pathway","clinicalProblem":"Substance use","summary":"Source-grounded workflow assembled from therapies indexed to Substance use. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as source-grounded therapy reference only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"motivational-interviewing-mi-for-substance-use-disorders","label":"Initial option","description":"Best used at engagement, assessment, early treatment, and whenever motivation is unstable. It is especially useful for alcohol misuse, broader substance use disorders, and patients who are reluctant, unsure, or inconsistent in change efforts. NICE alcohol guidance makes motivational intervention universal at intake, and SAMHSA TIP 35 positions MI as a core SUD treatment approach for enhancing participation and retention."},{"therapySlug":"relapse-prevention-therapy-for-substance-use-disorders","label":"Alternative option","description":"Best used after initial motivation has improved and the patient is actively trying to reduce, stop, or maintain abstinence, especially in alcohol use disorder and broader substance use disorders. NICE alcohol guidance recommends offering community-based interventions to promote abstinence or moderate drinking and prevent relapse, and recommends CBT/behavioural therapies focused on alcohol-related problems."},{"therapySlug":"contingency-management-cm","label":"Alternative option","description":"Best used for stimulant use disorder, for illicit drug use in methadone maintenance, and for engagement / abstinence targets in drug services. NICE explicitly recommends introducing CM to reduce illicit drug use and/or promote engagement for people on methadone maintenance and for people who primarily misuse stimulants."},{"therapySlug":"community-reinforcement-approach","label":"Follow-up option","description":"Best for alcohol and other drug use disorders where lifestyle, reinforcement, social context, and recovery capital are central. Evidence is strongest historically for alcohol, cocaine, and opioid-related disorders, but it should be framed as one structured addiction therapy rather than a universal replacement for pharmacotherapy, withdrawal care, or contingency management. A systematic review found limited-to-moderate evidence for CRA, with or without medication or contingency management, across alcohol and substance-related disorders. (NCBI)"},{"therapySlug":"mindfulness-based-relapse-prevention-mbrp","label":"Follow-up option","description":"Best viewed as an adjunctive or selective relapse-prevention treatment for SUDs rather than a clearly dominant stand-alone first-line therapy. The 2025 systematic review and meta-analysis found small benefits for withdrawal/craving symptoms and negative consequences of substance use, but no statistically significant differences versus comparators for relapse, frequency of use, treatment dropout, depressive symptoms, anxiety symptoms, or mindfulness scores overall."},{"therapySlug":"twelve-step-facilitation-tsf","label":"Follow-up option","description":"The strongest evidence is for alcohol use disorder (AUD). A 2020 Cochrane review found AA/TSF was at least as effective as other established treatments and often better for continuous abstinence and remission over follow-up, with evidence of healthcare cost savings. It is more accurate to present TSF as especially evidence-supported for AUD than as equally established across all SUDs. (cochrane.org)"}]},{"slug":"trauma-pathway","name":"Trauma pathway","clinicalProblem":"Trauma","summary":"Source-grounded workflow assembled from therapies indexed to Trauma. Marked incomplete until clinician review confirms sequencing.","cautions":"Use as source-grounded therapy reference only. Confirm acuity, risk, patient preference, and local service capability.","incomplete":true,"reviewStatus":"needs_review","steps":[{"therapySlug":"trauma-focused-cognitive-behavioural-therapy-tf-cbt","label":"Initial option","description":"Strongest use is PTSD. It is also appropriate for clinically important post-traumatic symptoms after trauma, depending on timing, severity, and readiness. In Australian guidelines, TF-CBT, CPT, CT, and PE are all recommended adult PTSD treatments."},{"therapySlug":"eye-movement-desensitisation-and-reprocessing-emdr","label":"Alternative option","description":"For adults with PTSD, Phoenix Australia gives EMDR a strong recommendation. NICE recommends EMDR for adults with PTSD or clinically important PTSD symptoms more than 3 months after non-combat-related trauma, and suggests considering it between 1 and 3 months after non-combat trauma if the person prefers EMDR."},{"therapySlug":"cognitive-processing-therapy-cpt","label":"Alternative option","description":"Strongest use is PTSD. Australian guidelines give a strong recommendation for CPT in adults with PTSD. It is especially useful when maladaptive trauma meanings, guilt, shame, and self-blame are central."},{"therapySlug":"prolonged-exposure-pe","label":"Follow-up option","description":"Strongest use is PTSD in adults. Phoenix Australia gives a strong recommendation for PE in adult PTSD. NICE also includes prolonged exposure therapy within recommended adult trauma-focused CBT interventions."},{"therapySlug":"narrative-exposure-therapy-net","label":"Follow-up option","description":"In Australian PTSD guidelines, NET has a conditional recommendation for adults with PTSD where trauma is linked to genocide, civil conflict, torture, political detention, or displacement. It is best understood as a selective trauma therapy, not a universal first-line PTSD treatment alongside TF-CBT, CT, CPT, PE, or EMDR."},{"therapySlug":"written-exposure-therapy","label":"Follow-up option","description":"Best as a brief trauma-focused PTSD treatment option when a concise, lower-burden exposure-based therapy is needed. Current VA/DoD guidance places WET as a second-line PTSD psychotherapy, not above PE, CPT, or EMDR. It is not currently included in NICE or Phoenix Australia PTSD guideline recommendations, so in Australian practice it should be framed as promising and evidence-supported internationally, but not yet an Australian first-line guideline therapy."}]}]
\ No newline at end of file
diff --git a/scripts/generate-site-map.ts b/scripts/generate-site-map.ts
index ea25868d3c..f12ff25fa4 100644
--- a/scripts/generate-site-map.ts
+++ b/scripts/generate-site-map.ts
@@ -144,7 +144,7 @@ const routeDescriptions: Record<string, string> = {
   "/specifiers/builder": "Structured diagnostic wording builder.",
   "/specifiers/compare": "Side-by-side psychiatric specifier comparison.",
   "/specifiers/map": "Psychiatric specifier family map.",
-  "/therapy-compass": "Therapy home (source-grounded therapy decision support).",
+  "/therapy-compass": "Therapy home (source-grounded therapy reference).",
   "/therapy-compass/[slug]": "Therapy record detail.",
   "/therapy-compass/[slug]/brief": "Therapy brief-intervention view.",
   "/therapy-compass/[slug]/sheet": "Therapy patient-sheet builder.",
diff --git a/src/components/therapy-compass/screens/detail-screen.tsx b/src/components/therapy-compass/screens/detail-screen.tsx
index 8a1832736e..4b6e58268f 100644
--- a/src/components/therapy-compass/screens/detail-screen.tsx
+++ b/src/components/therapy-compass/screens/detail-screen.tsx
@@ -83,7 +83,7 @@ export function DetailScreen() {
           <TherapySourceProvenance therapy={t} />
         </section>
         <InformationPageFooter className="mt-4">
-          Decision support — verify the record and linked source before clinical use.
+          Source-grounded therapy reference — verify the record and linked source before clinical use.
         </InformationPageFooter>
       </InformationPageShell>
     </>
diff --git a/src/components/therapy-compass/screens/pathways-screen.tsx b/src/components/therapy-compass/screens/pathways-screen.tsx
index 65dae23192..e42c2f6019 100644
--- a/src/components/therapy-compass/screens/pathways-screen.tsx
+++ b/src/components/therapy-compass/screens/pathways-screen.tsx
@@ -202,7 +202,7 @@ export function PathwaysScreen() {
         />
         <div className="flex-1 min-w-[200px]">
           <div className="text-sm-minus font-semibold text-[color:var(--warning-text)]">
-            Clinical caution — decision support generated from imported records.
+            Clinical caution — source-grounded therapy reference generated from imported records.
           </div>
           <div className="text-xs text-[color:var(--warning-text)] mt-0.5">
             {pathway.cautions ??
diff --git a/src/components/therapy-compass/workspace.tsx b/src/components/therapy-compass/workspace.tsx
index 5714ed803d..cf6a04faab 100644
--- a/src/components/therapy-compass/workspace.tsx
+++ b/src/components/therapy-compass/workspace.tsx
@@ -16,7 +16,10 @@ import { TherapyCompareTray } from "./therapy-compare-tray";
 function TherapyCompassFooter() {
   return (
     <div data-therapy-no-print className={cn(pageContainer, "mt-[30px] border-t border-[color:var(--border)] pt-5")}>
-      <ModeHomeVerificationFooter label="Decision support" body="Source-grounded — review status before clinical use" />
+      <ModeHomeVerificationFooter
+        label="Source-grounded therapy reference"
+        body="Source-grounded — review status before clinical use"
+      />
     </div>
   );
 }
diff --git a/src/lib/app-modes.ts b/src/lib/app-modes.ts
index 8238123abd..7351a90622 100644
--- a/src/lib/app-modes.ts
+++ b/src/lib/app-modes.ts
@@ -371,7 +371,7 @@ export const appModeDefinitions = [
   {
     id: "therapy-compass",
     label: "Therapy",
-    description: "Source-grounded therapy decision support",
+    description: "Source-grounded therapy reference",
     href: "/therapy-compass",
     // Therapy ships in production with its review state disclosed rather than
     // hidden. It was previously `devOnly`, which 404'd the route and every
diff --git a/src/lib/medication-entities.ts b/src/lib/medication-entities.ts
index 20dc747367..1195ae8a82 100644
--- a/src/lib/medication-entities.ts
+++ b/src/lib/medication-entities.ts
@@ -261,6 +261,7 @@ propranolol
 psyllium
 pyridoxine
 quetiapine
+ramipril
 reboxetine
 riboflavin
 risedronate
@@ -274,6 +275,7 @@ semaglutide
 senna
 sertraline
 sildenafil
+simvastatin
 sitagliptin
 sodium chloride
 sodium nitroprusside
@@ -352,8 +354,10 @@ const medicationIdentityGroups = [
   ["paliperidone", "invega"],
   ["promethazine", "phenergan"],
   ["quetiapine", "seroquel"],
+  ["ramipril", "tritace", "ramace", "prilace"],
   ["risperidone", "risperdal"],
   ["sertraline", "zoloft"],
+  ["simvastatin", "zocor", "lipex", "simvar"],
   ["valproate", "sodium valproate", "valproic acid", "epilim"],
   ["ziprasidone", "ziprasidone im"],
   ["zuclopenthixol", "zuclopenthixol acetate", "zuclopenthixol decanoate"],
diff --git a/tests/forms.test.ts b/tests/forms.test.ts
index 2c57dc71ea..49c2fab740 100644
--- a/tests/forms.test.ts
+++ b/tests/forms.test.ts
@@ -191,6 +191,27 @@ describe("psychiatry form records", () => {
     expect(formCatalogDetails(form12a!)?.officialPdfPasswordProtected).toBe(false);
   });
 
+  it("populates Form 12A statutory Authority and Criteria priority facts from readable approved PDF", () => {
+    const form12a = getFormRecord("form-12a");
+    expect(form12a).toBeTruthy();
+    const details = formCatalogDetails(form12a!);
+    expect(details?.priorityFacts?.clock?.title).toBe("Valid until revoked or resigned");
+    expect(details?.priorityFacts?.clock?.detail).toContain("Revocable at any time");
+    expect(details?.priorityFacts?.authority?.title).toBe("Person understanding effect (any age, incl. child)");
+    expect(details?.priorityFacts?.authority?.detail).toContain("nominee adult 18+");
+    expect(details?.priorityFacts?.authority?.body).toMatch(/s273.*s274.*s275/);
+    expect(details?.priorityFacts?.criteria?.title).toBe("Person understands effect of nomination (s273)");
+    expect(details?.priorityFacts?.criteria?.detail).toMatch(/Max 1 nominee/);
+    expect(details?.priorityFacts?.criteria?.body).toMatch(/s273.*s276.*s263.*s266/);
+    expect(details?.maker).toContain("s273");
+    expect(details?.maker).toContain("s275");
+    expect(details?.threshold).toContain("s273");
+    expect(details?.threshold).toContain("s276");
+    expect(details?.authorises).toMatch(/s266.*s263/);
+    expect(details?.doesNotAuthorise).toContain("consent to or refuse treatment");
+    expect(form12a?.summaryCards?.map((card) => card.id)).toEqual(["clock", "authority", "criteria", "act-sections"]);
+  });
+
   it("retains the enriched form payload in database seed rows", () => {
     const rows = buildDefaultFormRows("00000000-0000-4000-8000-000000000001");
     expect(rows).toHaveLength(54);
diff --git a/tests/medication-badges.test.ts b/tests/medication-badges.test.ts
index b844ae1fc6..74b4a0ab4c 100644
--- a/tests/medication-badges.test.ts
+++ b/tests/medication-badges.test.ts
@@ -124,6 +124,57 @@ describe("medications catalogue regression", () => {
     const badges = medicationIdentityBadges(record!);
     expect(badges.some((badge) => badge.label === "PBS streamlined")).toBe(true);
   });
+
+  it("verifies Ramipril cardiovascular profile, pregnancy contraindication, and triple whammy interaction", () => {
+    const record = getMedicationRecord("ramipril");
+    expect(record).toBeTruthy();
+    expect(record?.class).toBe("Antihypertensive");
+    expect(record?.subclass).toBe("ACE Inhibitor");
+    expect(record?.schedule).toBe("S4");
+    expect(record?.tag).toBe("ACEi");
+
+    const badges = medicationIdentityBadges(record!);
+    expect(badges.some((b) => b.label === "ACEi")).toBe(true);
+    expect(badges.some((b) => b.label === "S4")).toBe(true);
+
+    const contraSection = record?.sections.find((s) => s.type === "contra");
+    expect(contraSection).toBeTruthy();
+    const pregRow = contraSection?.rows.find((r) => r.key === "Pregnancy");
+    expect(pregRow?.patient?.factors).toContain("pregnancy");
+    expect(pregRow?.patient?.severity).toBe("danger");
+    expect(pregRow?.patient?.action).toBe("contraindication");
+
+    const interSection = record?.sections.find((s) => s.type === "inter");
+    expect(interSection).toBeTruthy();
+    const tripleWhammy = interSection?.rows.find((r) => r.key === "Triple Whammy");
+    expect(tripleWhammy?.val).toMatch(/^CRITICAL/);
+    expect(tripleWhammy?.val).toContain("NSAID");
+  });
+
+  it("verifies Simvastatin lipid-lowering profile, evening administration, and CYP3A4 interaction", () => {
+    const record = getMedicationRecord("simvastatin");
+    expect(record).toBeTruthy();
+    expect(record?.class).toBe("Lipid-Lowering");
+    expect(record?.subclass).toBe("HMG-CoA Reductase Inhibitor");
+    expect(record?.schedule).toBe("S4");
+    expect(record?.tag).toBe("STATIN");
+
+    const badges = medicationIdentityBadges(record!);
+    expect(badges.some((b) => b.label === "STATIN")).toBe(true);
+    expect(badges.some((b) => b.label === "S4")).toBe(true);
+
+    const contraSection = record?.sections.find((s) => s.type === "contra");
+    expect(contraSection).toBeTruthy();
+    const hepaticRow = contraSection?.rows.find((r) => r.key === "Absolute");
+    expect(hepaticRow?.patient?.factors).toContain("hepatic");
+    expect(hepaticRow?.patient?.severity).toBe("danger");
+
+    const interSection = record?.sections.find((s) => s.type === "inter");
+    expect(interSection).toBeTruthy();
+    const cyp3a4Row = interSection?.rows.find((r) => r.val.includes("CYP3A4"));
+    expect(cyp3a4Row?.val).toMatch(/^CRITICAL/);
+    expect(cyp3a4Row?.val).toContain("Clarithromycin");
+  });
 });
 
 describe("controlled-drug (S8) schedule badge", () => {
diff --git a/tests/medications.test.ts b/tests/medications.test.ts
index 5630168198..019f7f8828 100644
--- a/tests/medications.test.ts
+++ b/tests/medications.test.ts
@@ -35,9 +35,11 @@ function buildRecord(overrides: Partial<MedicationRecord>): MedicationRecord {
 describe("medications catalogue", () => {
   it("loads the full reviewed export snapshot", () => {
     const records = loadMedicationSnapshot();
-    expect(records.length).toBe(328);
+    expect(records.length).toBe(330);
     expect(records.some((record) => record.slug === "acamprosate")).toBe(true);
     expect(records.some((record) => record.slug === "sertraline")).toBe(true);
+    expect(records.some((record) => record.slug === "ramipril")).toBe(true);
+    expect(records.some((record) => record.slug === "simvastatin")).toBe(true);
   });
 
   it("ranks exact medication names ahead of broad matches", () => {

From 3c1ff04eb593bf401e9e59a484844bd39387394f Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Fri, 28 Aug 2026 01:54:24 +0800
Subject: [PATCH 8/9] fix(therapy-compass): use size-icon-md for Scale icon on
 sheets screen

---
 src/components/therapy-compass/screens/sheets-screen.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/components/therapy-compass/screens/sheets-screen.tsx b/src/components/therapy-compass/screens/sheets-screen.tsx
index 39b35ea582..7c4e245344 100644
--- a/src/components/therapy-compass/screens/sheets-screen.tsx
+++ b/src/components/therapy-compass/screens/sheets-screen.tsx
@@ -329,7 +329,7 @@ function TherapyPicker() {
         onClick={() => setOpen((v) => !v)}
       >
         <span className="flex items-center gap-2.5 min-w-0">
-          <Scale aria-hidden="true" size={16} className="text-[color:var(--clinical-accent)] flex-none" />
+          <Scale aria-hidden="true" className="size-icon-md text-[color:var(--clinical-accent)] flex-none" />
           <span className="overflow-hidden text-ellipsis whitespace-nowrap">
             {b.selectedTherapy?.name ?? "Choose a therapy"}
           </span>

From 0c508b49fd6b00e516fff224272ed1a9c85a4292 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 27 Aug 2026 19:33:00 +0000
Subject: [PATCH 9/9] fix(medications): require the full Triple Whammy
 combination and stop the gemfibrozil self-class overmatch
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two P1 findings from the PR #2448 review, both in the interaction-index
generator:

- "ACEi + Diuretic + NSAID" rows fired on any single class alone (another
  ACEi, an NSAID by itself, or a diuretic by itself), since the generated
  index unioned each class's matches into one flat counterparty list.
  build-medication-interaction-index.ts now recognises a "+"-joined clause
  as a required combination and records requiredGroups; the evaluator only
  fires such a row once every group has a match in the patient's list. This
  also fixes the same defect on the corpus's seven pre-existing rows using
  the identical pattern, not only ramipril's new row.

- Simvastatin's and atorvastatin's gemfibrozil rows used the generic words
  "statin" and "(Fibrate)" to describe their own mechanism, which the
  generator resolved as sibling-class counterparties (every other statin,
  fenofibrate) — a patient on an unrelated statin alone triggered a HIGH
  "Gemfibrozil ... Contraindicated" alert. Denied at the source via the
  existing sourceDenySlugs mechanism, since gemfibrozil itself is not in
  the catalogue.

Regenerated data/medication-interaction-index.json and
docs/medication-interaction-lexicon-review.md, added regression tests for
both scenarios, and verified no existing interaction alert was weakened
(182 -> 189 medication tests, all passing).

RAG impact: none — this touches only the medication-interaction catalogue
and evaluator, not src/lib/rag/** or retrieval/answer surfaces.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JYtcTz6zLPb1v38ahfeCSH
---
 data/medication-interaction-index.json        | 102 +++++++++++++-----
 docs/medication-interaction-lexicon-review.md |   4 +-
 scripts/build-medication-interaction-index.ts |  73 +++++++++++++
 src/lib/medication-interaction-lexicon.ts     |  16 +++
 src/lib/medication-interactions.ts            |  21 ++++
 tests/medication-interactions.test.ts         |  55 ++++++++++
 6 files changed, 244 insertions(+), 27 deletions(-)

diff --git a/data/medication-interaction-index.json b/data/medication-interaction-index.json
index 5497146244..d05860974f 100644
--- a/data/medication-interaction-index.json
+++ b/data/medication-interaction-index.json
@@ -3,10 +3,10 @@
   "generatedFrom": "data/medications-snapshot.json",
   "sourceRowCount": 531,
   "stats": {
-    "resolvedRows": 397,
-    "unresolvedRows": 134,
-    "rowsWithCatalogueTarget": 446,
-    "medicationsWithUnresolvedRows": 119
+    "resolvedRows": 395,
+    "unresolvedRows": 136,
+    "rowsWithCatalogueTarget": 444,
+    "medicationsWithUnresolvedRows": 120
   },
   "names": {
     "acamprosate": "Acamprosate",
@@ -1332,7 +1332,11 @@
           ],
           "termIds": ["acei", "diuretics"],
           "resolved": true,
-          "note": "CRITICAL — ACEi + Diuretic + Celecoxib = AKI."
+          "note": "CRITICAL — ACEi + Diuretic + Celecoxib = AKI.",
+          "requiredGroups": [
+            ["perindopril", "ramipril"],
+            ["amiloride", "eplerenone", "frusemide", "hydrochlorothiazide", "indapamide", "spironolactone"]
+          ]
         }
       ],
       "unresolvedRowCount": 0
@@ -1378,7 +1382,11 @@
           ],
           "termIds": ["acei", "arbs", "diuretics"],
           "resolved": true,
-          "note": "CRITICAL — ACEi/ARB + Diuretic + Diclofenac = AKI."
+          "note": "CRITICAL — ACEi/ARB + Diuretic + Diclofenac = AKI.",
+          "requiredGroups": [
+            ["candesartan", "perindopril", "ramipril"],
+            ["amiloride", "eplerenone", "frusemide", "hydrochlorothiazide", "indapamide", "spironolactone"]
+          ]
         },
         {
           "rowKey": "Pharmacokinetic",
@@ -1418,7 +1426,11 @@
           ],
           "termIds": ["acei", "arbs", "diuretics", "nsaids"],
           "resolved": true,
-          "note": "CRITICAL — NSAID + ACEi/ARB + Diuretic. Will virtually guarantee acute renal failure. NEVER prescribe this combination."
+          "note": "CRITICAL — NSAID + ACEi/ARB + Diuretic. Will virtually guarantee acute renal failure. NEVER prescribe this combination.",
+          "requiredGroups": [
+            ["candesartan", "perindopril", "ramipril"],
+            ["amiloride", "eplerenone", "frusemide", "hydrochlorothiazide", "indapamide", "spironolactone"]
+          ]
         },
         {
           "rowKey": "Pharmacodynamic",
@@ -1474,7 +1486,11 @@
           ],
           "termIds": ["acei", "arbs", "diuretics"],
           "resolved": true,
-          "note": "CRITICAL — ACEi/ARB + Diuretic + Ketorolac = Renal Necrosis."
+          "note": "CRITICAL — ACEi/ARB + Diuretic + Ketorolac = Renal Necrosis.",
+          "requiredGroups": [
+            ["candesartan", "perindopril", "ramipril"],
+            ["amiloride", "eplerenone", "frusemide", "hydrochlorothiazide", "indapamide", "spironolactone"]
+          ]
         },
         {
           "rowKey": "Pharmacodynamic",
@@ -1527,7 +1543,11 @@
           ],
           "termIds": ["acei", "arbs", "diuretics", "nsaids"],
           "resolved": true,
-          "note": "CRITICAL — NSAID + ACEi/ARB + Diuretic = AKI."
+          "note": "CRITICAL — NSAID + ACEi/ARB + Diuretic = AKI.",
+          "requiredGroups": [
+            ["candesartan", "perindopril", "ramipril"],
+            ["amiloride", "eplerenone", "frusemide", "hydrochlorothiazide", "indapamide", "spironolactone"]
+          ]
         },
         {
           "rowKey": "Pharmacodynamic",
@@ -1589,7 +1609,11 @@
           ],
           "termIds": ["acei", "arbs", "diuretics", "nsaids"],
           "resolved": true,
-          "note": "CRITICAL — NSAID + ACEi/ARB + Diuretic = AKI."
+          "note": "CRITICAL — NSAID + ACEi/ARB + Diuretic = AKI.",
+          "requiredGroups": [
+            ["candesartan", "perindopril", "ramipril"],
+            ["amiloride", "eplerenone", "frusemide", "hydrochlorothiazide", "indapamide", "spironolactone"]
+          ]
         },
         {
           "rowKey": "Pharmacodynamic",
@@ -1667,7 +1691,11 @@
           ],
           "termIds": ["acei", "arbs", "diuretics"],
           "resolved": true,
-          "note": "CRITICAL — ACEi/ARB + Diuretic + Parecoxib = High risk of post-op renal failure."
+          "note": "CRITICAL — ACEi/ARB + Diuretic + Parecoxib = High risk of post-op renal failure.",
+          "requiredGroups": [
+            ["candesartan", "perindopril", "ramipril"],
+            ["amiloride", "eplerenone", "frusemide", "hydrochlorothiazide", "indapamide", "spironolactone"]
+          ]
         },
         {
           "rowKey": "Pharmacokinetic",
@@ -2026,7 +2054,11 @@
           ],
           "termIds": ["arbs", "diuretics", "nsaids"],
           "resolved": true,
-          "note": "CRITICAL — ARB + Diuretic + NSAID (Guaranteed AKI)."
+          "note": "CRITICAL — ARB + Diuretic + NSAID (Guaranteed AKI).",
+          "requiredGroups": [
+            ["amiloride", "eplerenone", "frusemide", "hydrochlorothiazide", "indapamide", "spironolactone"],
+            ["aspirin", "celecoxib", "diclofenac", "ibuprofen", "ketorolac", "meloxicam", "naproxen", "parecoxib"]
+          ]
         },
         {
           "rowKey": "Pharmacodynamic",
@@ -2142,7 +2174,11 @@
           ],
           "termIds": ["acei", "diuretics", "nsaids"],
           "resolved": true,
-          "note": "CRITICAL — ACEi + Diuretic + NSAID (Ibuprofen/Naproxen). This combination guarantees acute renal failure by destroying both afferent and efferent glomerular blood flow."
+          "note": "CRITICAL — ACEi + Diuretic + NSAID (Ibuprofen/Naproxen). This combination guarantees acute renal failure by destroying both afferent and efferent glomerular blood flow.",
+          "requiredGroups": [
+            ["amiloride", "eplerenone", "frusemide", "hydrochlorothiazide", "indapamide", "spironolactone"],
+            ["aspirin", "celecoxib", "diclofenac", "ibuprofen", "ketorolac", "meloxicam", "naproxen", "parecoxib"]
+          ]
         },
         {
           "rowKey": "Pharmacodynamic",
@@ -2376,7 +2412,11 @@
           ],
           "termIds": ["acei", "arbs", "nsaids"],
           "resolved": true,
-          "note": "CRITICAL — NSAIDs + ACEi/ARB + Frusemide = High risk of renal failure."
+          "note": "CRITICAL — NSAIDs + ACEi/ARB + Frusemide = High risk of renal failure.",
+          "requiredGroups": [
+            ["aspirin", "celecoxib", "diclofenac", "ibuprofen", "ketorolac", "meloxicam", "naproxen", "parecoxib"],
+            ["candesartan", "perindopril", "ramipril"]
+          ]
         },
         {
           "rowKey": "Pharmacodynamic",
@@ -2420,7 +2460,11 @@
           ],
           "termIds": ["acei", "nsaids", "thiazide-diuretics"],
           "resolved": true,
-          "note": "CRITICAL — NSAIDs + ACEi + Thiazide."
+          "note": "CRITICAL — NSAIDs + ACEi + Thiazide.",
+          "requiredGroups": [
+            ["aspirin", "celecoxib", "diclofenac", "ibuprofen", "ketorolac", "meloxicam", "naproxen", "parecoxib"],
+            ["perindopril", "ramipril"]
+          ]
         }
       ],
       "unresolvedRowCount": 0
@@ -2454,7 +2498,11 @@
           ],
           "termIds": ["acei", "nsaids"],
           "resolved": true,
-          "note": "CRITICAL — NSAIDs + ACEi + Indapamide."
+          "note": "CRITICAL — NSAIDs + ACEi + Indapamide.",
+          "requiredGroups": [
+            ["aspirin", "celecoxib", "diclofenac", "ibuprofen", "ketorolac", "meloxicam", "naproxen", "parecoxib"],
+            ["perindopril", "ramipril"]
+          ]
         }
       ],
       "unresolvedRowCount": 0
@@ -2497,13 +2545,13 @@
           "rowKey": "Pharmacokinetic",
           "rowIndex": 1,
           "severity": "high",
-          "counterparties": ["fenofibrate", "rosuvastatin", "simvastatin"],
-          "termIds": ["fibrates", "statins"],
-          "resolved": true,
+          "counterparties": [],
+          "termIds": [],
+          "resolved": false,
           "note": "HIGH — Gemfibrozil (Fibrate) blocks statin uptake, drastically increasing blood levels. Avoid combo."
         }
       ],
-      "unresolvedRowCount": 0
+      "unresolvedRowCount": 1
     },
     "ezetimibe": {
       "rows": [
@@ -10055,7 +10103,11 @@
           ],
           "termIds": ["acei", "diuretics", "nsaids"],
           "resolved": true,
-          "note": "CRITICAL — ACEi + Diuretic + NSAID (Ibuprofen/Naproxen). This combination guarantees acute renal failure by destroying both afferent and efferent glomerular blood flow."
+          "note": "CRITICAL — ACEi + Diuretic + NSAID (Ibuprofen/Naproxen). This combination guarantees acute renal failure by destroying both afferent and efferent glomerular blood flow.",
+          "requiredGroups": [
+            ["amiloride", "eplerenone", "frusemide", "hydrochlorothiazide", "indapamide", "spironolactone"],
+            ["aspirin", "celecoxib", "diclofenac", "ibuprofen", "ketorolac", "meloxicam", "naproxen", "parecoxib"]
+          ]
         },
         {
           "rowKey": "Pharmacodynamic",
@@ -10100,9 +10152,9 @@
           "rowKey": "Pharmacokinetic",
           "rowIndex": 1,
           "severity": "high",
-          "counterparties": ["atorvastatin", "fenofibrate", "rosuvastatin"],
-          "termIds": ["fibrates", "statins"],
-          "resolved": true,
+          "counterparties": [],
+          "termIds": [],
+          "resolved": false,
           "note": "HIGH — Gemfibrozil (Fibrate) blocks statin glucuronidation and uptake, drastically increasing blood levels. Contraindicated combo."
         },
         {
@@ -10115,7 +10167,7 @@
           "note": "HIGH — Moderate CYP3A4 inhibitors (Amiodarone, Diltiazem, Verapamil, Amlodipine). Limit Simvastatin dose to max 20 mg/day (or 10 mg/day with Amiodarone/Verapamil/Diltiazem) to prevent myopathy."
         }
       ],
-      "unresolvedRowCount": 1
+      "unresolvedRowCount": 2
     }
   }
 }
diff --git a/docs/medication-interaction-lexicon-review.md b/docs/medication-interaction-lexicon-review.md
index 4aabc0bca6..377177274c 100644
--- a/docs/medication-interaction-lexicon-review.md
+++ b/docs/medication-interaction-lexicon-review.md
@@ -47,8 +47,8 @@ CRITICAL or HIGH. Start at the top — the table is sorted by severe usage.
 | `calcium-channel-blockers` | calcium channel blockers, calcium channel blocker, ccbs, ccb, non-dhp ccbs, dhp calcium channel blockers | 9    | 9      | **5** — Amlodipine, Diltiazem, Felodipine, Nifedipine XR, Verapamil                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `corticosteroids`          | corticosteroids, corticosteroid, steroids, steroid                                                       | 9    | 9      | **11** — Beclometasone, Budesonide, Ciclesonide, Dexamethasone, Fludrocortisone, Fluticasone, Hydrocortisone, Methylprednisolone, Mometasone, Prednisolone, Prednisone                                                                                                                                                                                                                                                                                                                                                  |
 | `thiazide-diuretics`       | thiazide diuretics, thiazides, thiazide                                                                  | 9    | 9      | **2** — Hydrochlorothiazide, Indapamide                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `statins`                  | statins, statin                                                                                          | 10   | 8      | **3** — Atorvastatin, Rosuvastatin, Simvastatin                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `ppis`                     | ppis, ppi, proton pump inhibitors                                                                        | 8    | 8      | **2** — Esomeprazole, Pantoprazole                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `statins`                  | statins, statin                                                                                          | 8    | 6      | **3** — Atorvastatin, Rosuvastatin, Simvastatin                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `aminoglycosides`          | aminoglycosides, aminoglycoside                                                                          | 6    | 5      | **2** — Amikacin, Gentamicin                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `fluoroquinolones`         | fluoroquinolones, fluoroquinolone, quinolones                                                            | 5    | 5      | **3** — Ciprofloxacin, Moxifloxacin, Norfloxacin                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `loop-diuretics`           | loop diuretics, loop diuretic                                                                            | 5    | 5      | **1** — Frusemide                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
@@ -58,9 +58,9 @@ CRITICAL or HIGH. Start at the top — the table is sorted by severe usage.
 | `snris`                    | snris, snri                                                                                              | 4    | 3      | **5** — Atomoxetine, Desvenlafaxine, Duloxetine, Tramadol IR, Venlafaxine XR                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `antiplatelets`            | antiplatelets, antiplatelet                                                                              | 3    | 3      | **4** — Aspirin, Clopidogrel, Dipyridamole, Ticagrelor                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `gabapentinoids`           | gabapentinoids, gabapentinoid                                                                            | 3    | 3      | **2** — Gabapentin, Pregabalin                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `fibrates`                 | fibrates, fibrate                                                                                        | 3    | 2      | **1** — Fenofibrate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `immunosuppressants`       | immunosuppressants, immunosuppressant                                                                    | 2    | 2      | **1** — Methotrexate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `cephalosporins`           | cephalosporins, cephalosporin                                                                            | 1    | 1      | **5** — Cefazolin, Cefepime, Ceftriaxone, Cefuroxime, Cephalexin                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `fibrates`                 | fibrates, fibrate                                                                                        | 1    | 0      | **1** — Fenofibrate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `nrt`                      | transdermal nrt, nicotine transdermal systems, nicotine patches                                          | 1    | 0      | **6** — Nicotine gum, Nicotine inhalator, Nicotine lozenge, Nicotine mouth spray, Nicotine patch, Nicotine sublingual tablet                                                                                                                                                                                                                                                                                                                                                                                            |
 | `sulfonylureas`            | sulfonylureas, sulfonylurea                                                                              | 1    | 0      | **2** — Gliclazide, Glipizide                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 
diff --git a/scripts/build-medication-interaction-index.ts b/scripts/build-medication-interaction-index.ts
index e480388189..9945165ef8 100644
--- a/scripts/build-medication-interaction-index.ts
+++ b/scripts/build-medication-interaction-index.ts
@@ -60,6 +60,16 @@ type IndexRow = {
   counterparties: string[];
   termIds: string[];
   resolved: boolean;
+  /**
+   * Groups of slugs where the row's alert requires at least one member from
+   * EVERY group to be present in the patient's list, not merely any one
+   * `counterparties` entry. Populated only for rows whose prose joins classes
+   * with a literal "+" ("ACEi + Diuretic + NSAID") — the corpus's own convention
+   * for a required combination, distinct from the comma/list style used
+   * everywhere else for a plain either-of counterparty set. Absent (or empty)
+   * for every other row, which keeps existing any-of behaviour unchanged.
+   */
+  requiredGroups?: string[][];
   /**
    * Verbatim `row.val`.
    *
@@ -227,6 +237,7 @@ function main(): void {
         const severity = bareAbsence ?? (severityToken ? (SEVERITY_BY_TOKEN[severityToken] ?? "unknown") : "unknown");
         const counterparties = new Map<string, IndexCounterparty>();
         const termIds = new Set<string>();
+        const requiredGroups: string[][] = [];
         let sawClassifiableTerm = false;
 
         for (const segment of segments) {
@@ -259,6 +270,8 @@ function main(): void {
             for (const id of segmentTermIds) termIds.add(id);
             for (const [slug, target] of segmentCounterparties) counterparties.set(slug, target);
           }
+
+          requiredGroups.push(...extractRequiredGroups(segment, record.slug));
         }
 
         const hasUnenumeratedMechanism = Array.from(termIds).some((id) => UNENUMERATED_MECHANISM_TERM_IDS.has(id));
@@ -278,12 +291,72 @@ function main(): void {
           termIds: Array.from(termIds).sort(),
           resolved,
           note: value,
+          ...(requiredGroups.length > 0 ? { requiredGroups: requiredGroups.map((group) => group.sort()) } : {}),
         });
       });
     }
     if (rows.length > 0) bySlug[record.slug] = { rows, unresolvedRowCount: rows.filter((row) => !row.resolved).length };
   }
 
+  /**
+   * "ACEi + Diuretic + NSAID" style rows ("Triple Whammy" and its relatives)
+   * name a required COMBINATION, not an either-of list — the corpus marks that
+   * with a literal "+" between classes, distinct from the comma/list style used
+   * for genuine either-of counterparty sets elsewhere. Splitting on "+" and
+   * resolving each clause independently turns that combination back into
+   * separate required groups instead of the flat union `segmentCounterparties`
+   * would otherwise produce, which let any ONE class (an NSAID alone, a
+   * diuretic alone, or even another ACEi) fire the full combination alert.
+   *
+   * A clause naming only the source drug's own class (ramipril's row saying
+   * "ACEi") is dropped rather than turned into a group: that class is already
+   * supplied by the source drug, so it is not a further requirement. This
+   * self-exclusion is deliberately local to conjunction-group extraction —
+   * `addTermTargets`'s ordinary either-of matching is untouched, because a
+   * source drug that is itself a class member very often legitimately warns
+   * about OTHER members of that same class (an opioid's own row warning about
+   * other opioids, a benzodiazepine's row warning about other benzodiazepines).
+   * Excluding the class there would silently drop those real alerts; it is
+   * safe only here, where "+" already marks the mention as naming a required
+   * combination rather than an independent either-of counterparty.
+   *
+   * Fewer than two resolvable clauses means there is nothing to require beyond
+   * the existing any-of `counterparties` set, so no groups are returned.
+   */
+  function extractRequiredGroups(segment: string, sourceSlug: string): string[][] {
+    // Require whitespace on both sides of the "+": "ACEi + Diuretic" is the
+    // combination marker, but ionic/charge notation like "Fe3+" or "K+-sparing"
+    // has no surrounding space and must not be split into spurious clauses.
+    const clauses = segment
+      .split(/\s+\+\s+/)
+      .map((clause) => clause.trim())
+      .filter(Boolean);
+    if (clauses.length < 2) return [];
+
+    const groups: string[][] = [];
+    for (const clause of clauses) {
+      const target = new Map<string, IndexCounterparty>();
+      for (const { surface, term } of LEXICON_SURFACES_BY_LENGTH) {
+        if (term.kind !== "catalogue") continue;
+        if (!mentions(clause, surface)) continue;
+        if (term.sourceDenySlugs?.includes(sourceSlug)) continue;
+        const slugs = termSlugs.get(term.id) ?? [];
+        if (slugs.includes(sourceSlug)) continue;
+        for (const slug of slugs) {
+          if (slug === sourceSlug || target.has(slug)) continue;
+          target.set(slug, { slug, name: nameBySlug.get(slug) ?? slug, via: term.id });
+        }
+      }
+      for (const { surface, slug } of drugSurfaces) {
+        if (slug === sourceSlug || !mentions(clause, surface)) continue;
+        if ((nameBySlug.get(slug) ?? slug) === (nameBySlug.get(sourceSlug) ?? sourceSlug)) continue;
+        if (!target.has(slug)) target.set(slug, { slug, name: nameBySlug.get(slug) ?? slug, via: surface });
+      }
+      if (target.size > 0) groups.push(Array.from(target.keys()));
+    }
+    return groups.length >= 2 ? groups : [];
+  }
+
   function addTermTargets(term: LexiconTerm, into: Map<string, IndexCounterparty>, sourceSlug: string): void {
     if (term.kind !== "catalogue") return;
     for (const slug of termSlugs.get(term.id) ?? []) {
diff --git a/src/lib/medication-interaction-lexicon.ts b/src/lib/medication-interaction-lexicon.ts
index 455eb894e7..a9aa232b00 100644
--- a/src/lib/medication-interaction-lexicon.ts
+++ b/src/lib/medication-interaction-lexicon.ts
@@ -166,6 +166,12 @@ const CATALOGUE_TERMS: LexiconTerm[] = [
     surfaces: ["statins", "statin"],
     kind: "catalogue",
     select: { subclassIncludes: ["Statin", "HMG"] },
+    // Simvastatin's and atorvastatin's own gemfibrozil rows ("blocks statin
+    // glucuronidation/uptake") use "statin" to describe their OWN drug class's
+    // mechanism, not to name a second interacting drug family — resolving it
+    // added every other statin as a false counterparty for a HIGH,
+    // gemfibrozil-specific alert they have nothing to do with.
+    sourceDenySlugs: ["simvastatin", "atorvastatin"],
   },
   {
     id: "gabapentinoids",
@@ -297,6 +303,16 @@ const CATALOGUE_TERMS: LexiconTerm[] = [
     surfaces: ["fibrates", "fibrate"],
     kind: "catalogue",
     select: { subclassIncludes: ["Fibrate"] },
+    // Simvastatin's and atorvastatin's gemfibrozil rows write "Gemfibrozil
+    // (Fibrate)" — a specific, uncatalogued drug's name with its class in
+    // parentheses, not a general fibrate-class warning. Fenofibrate is this
+    // catalogue's only other fibrate member and the corpus's own fenofibrate
+    // row rates a statin combination "extreme caution", not the Contraindicated
+    // severity gemfibrozil's row carries — so resolving "Fibrate" here would
+    // misattribute that severity to the wrong drug. Denied at the source rather
+    // than narrowing the surface, since the term is correct wherever a row
+    // names the class generically.
+    sourceDenySlugs: ["simvastatin", "atorvastatin"],
   },
   {
     id: "immunosuppressants",
diff --git a/src/lib/medication-interactions.ts b/src/lib/medication-interactions.ts
index d12f9d936d..0db62ccfe6 100644
--- a/src/lib/medication-interactions.ts
+++ b/src/lib/medication-interactions.ts
@@ -81,8 +81,23 @@ type IndexRow = {
   resolved: boolean;
   /** Verbatim row text, carried so the reverse direction has wording too. */
   note: string;
+  /**
+   * Groups of slugs where at least one member of EVERY group must be present
+   * in the patient's list before this row's alert fires. Set only for rows
+   * whose prose requires a class combination ("ACEi + Diuretic + NSAID") —
+   * see `scripts/build-medication-interaction-index.ts`. Absent for the
+   * ordinary either-of `counterparties` rows, which fire on any single match
+   * as before.
+   */
+  requiredGroups?: string[][];
 };
 
+/** Whether every required group of a row has at least one member in `present`. */
+function requiredGroupsSatisfied(row: IndexRow, present: ReadonlySet<string>): boolean {
+  if (!row.requiredGroups || row.requiredGroups.length === 0) return true;
+  return row.requiredGroups.every((group) => group.some((slug) => present.has(slug)));
+}
+
 type InteractionIndexShape = {
   version: number;
   sourceRowCount: number;
@@ -246,6 +261,7 @@ export function evaluateMedicationInteractions(
 
   if (entry) {
     for (const row of entry.rows) {
+      if (!requiredGroupsSatisfied(row, patient)) continue;
       for (const counterpartySlug of row.counterparties) {
         if (!patient.has(counterpartySlug)) continue;
         // Prefer the live record's wording; fall back to the indexed copy when no
@@ -259,11 +275,16 @@ export function evaluateMedicationInteractions(
   // Interaction prose is not guaranteed to be symmetric. Check each entered
   // medication's index entry as well so a clinically material edge is not missed
   // merely because it is documented on the existing drug rather than the candidate.
+  // The viewed drug itself can satisfy a required group from the reverse row's
+  // perspective (e.g. it supplies the "ACEi" side of the patient's diuretic row),
+  // so it is included alongside `patient` when checking that gate.
+  const patientWithViewed = new Set([...patient, slug]);
   for (const patientSlug of patient) {
     const reverseEntry = INDEX.bySlug[patientSlug];
     if (!reverseEntry) continue;
     for (const row of reverseEntry.rows) {
       if (!row.counterparties.includes(slug)) continue;
+      if (!requiredGroupsSatisfied(row, patientWithViewed)) continue;
       // The reverse row belongs to the PATIENT's medication, whose record this
       // caller does not hold — so its wording can only come from the index. It
       // used to be passed as "", which rendered a drug name and a severity chip
diff --git a/tests/medication-interactions.test.ts b/tests/medication-interactions.test.ts
index fadb45d099..c7f093379b 100644
--- a/tests/medication-interactions.test.ts
+++ b/tests/medication-interactions.test.ts
@@ -158,6 +158,61 @@ describe("evaluateMedicationInteractions", () => {
     expect(SEVERITY_TONE.critical).toBe("danger");
     expect(SEVERITY_TONE.unknown).toBe("neutral");
   });
+
+  describe("Triple Whammy (ACEi + Diuretic + NSAID) requires the full combination", () => {
+    // PR #2448 review: the generated index used to union each class's matches
+    // into a flat counterparty list, so any ONE of ibuprofen, frusemide, or
+    // even another ACEi fired the CRITICAL three-drug alert alone.
+    it("does not fire on an NSAID alone", () => {
+      const result = evaluateMedicationInteractions("ramipril", ["ibuprofen"]);
+      expect(result.interactions.some((item) => item.kind === "Triple Whammy")).toBe(false);
+    });
+
+    it("does not fire on a diuretic alone", () => {
+      const result = evaluateMedicationInteractions("ramipril", ["frusemide"]);
+      expect(result.interactions.some((item) => item.kind === "Triple Whammy")).toBe(false);
+    });
+
+    it("does not fire on another ACEi alone", () => {
+      const result = evaluateMedicationInteractions("ramipril", ["perindopril"]);
+      expect(result.interactions.some((item) => item.kind === "Triple Whammy")).toBe(false);
+    });
+
+    it("fires once both a diuretic and an NSAID are present", () => {
+      const result = evaluateMedicationInteractions("ramipril", ["frusemide", "ibuprofen"]);
+      const hits = result.interactions.filter((item) => item.kind === "Triple Whammy");
+      expect(hits.length).toBeGreaterThan(0);
+      expect(hits.every((item) => item.severity === "critical")).toBe(true);
+      expect(result.highestTone).toBe("danger");
+    });
+  });
+
+  describe("simvastatin's gemfibrozil row does not overmatch the statin/fibrate classes", () => {
+    // PR #2448 review: "statin" and "(Fibrate)" in this HIGH/Contraindicated row
+    // describe gemfibrozil's own mechanism, not a general class warning — they
+    // used to resolve to every other statin and to fenofibrate, so a patient on
+    // an unrelated statin alone triggered a gemfibrozil-specific alert. The
+    // shared "blocks statin" phrase is unique to the two gemfibrozil rows
+    // (simvastatin's and atorvastatin's), distinct from fenofibrate's own
+    // legitimate, correctly-firing general statin-toxicity warning, which must
+    // keep working.
+    const isGemfibrozilRowNote = (note: string) => note.includes("Gemfibrozil (Fibrate) blocks statin");
+
+    it("does not fire against atorvastatin, which is not gemfibrozil", () => {
+      const result = evaluateMedicationInteractions("simvastatin", ["atorvastatin"]);
+      expect(result.interactions.some((item) => isGemfibrozilRowNote(item.note))).toBe(false);
+    });
+
+    it("does not fire against fenofibrate, the catalogue's only other fibrate", () => {
+      const result = evaluateMedicationInteractions("simvastatin", ["fenofibrate"]);
+      expect(result.interactions.some((item) => isGemfibrozilRowNote(item.note))).toBe(false);
+    });
+
+    it("still fires fenofibrate's own legitimate statin-combination warning", () => {
+      const result = evaluateMedicationInteractions("simvastatin", ["fenofibrate"]);
+      expect(result.interactions.some((item) => item.counterpartySlug === "fenofibrate")).toBe(true);
+    });
+  });
 });
 
 describe("composeMedicationVerdict", () => {