HealthLog/docs/audit/v1416-summary.md

HealthLog v1.4.16 — Release Summary

Release brief

✅ Live: v1.4.16 on https://healthlog.bombeck.io — image digest sha256:05f8a126d639… (was v1.4.15: ace7d441f47b…), /api/version returns 1.4.16.

🆕 What's new

• AI insights now show WHY each recommendation appears — data window, comparison, deviation — with a confidence meter and a thumbs feedback control on every rec.
• Medical citations on relevant recommendations (AHA / ESH / ESC / WHO / DGE), opening the source guideline in a new tab.
• Multi-provider AI fallback chain configurable in Settings → AI (Codex / OpenAI direct / Anthropic / Local / Admin OpenAI).
• Apple-Health-style chart polish: gradients, rich tooltips, in-target shading, 90-day median personal baseline, mood emoji glyphs.
• Comparison overlay on charts, tiles, and the AI summary: "vs. last month" / "vs. last year" with delta callout.
• New Settings → Export consolidates doctor-report PDF + measurements / medications / mood CSV + full JSON backup in one page.
• Achievements page (/achievements) plus dashboard preview card.
• Onboarding tour for new users (skippable, replayable).
• Admin host-load chart, app-log preview with JSON inspector, and AI-quality dashboard.
• Backup full lifecycle — restore, download, upload, audit trail.

🔧 What's fixed

• BD-Zielbereich percentage finally counts in-range readings (predicate was too narrow — was always 0% on normotensive data).
• Trend on "all" filter shows a meaningful split-half delta instead of 0.
• Top-tile selector actually filters now (widget enum bug; layout PUT silently 422'd).
• Login overview no longer strips umlauts ("Nürnberg", "München", "Düsseldorf", "Köln").
• /admin/api-tokens table is responsive on mobile (card list at <md).
• Skip-link no longer blocks logo click.
• Cached AI insights replaced when regenerated (no stale dashboard).

⚙️ Infrastructure

• docker-publish main-branch hang fixed — root cause was qemu-arm64 SIGILL during multi-arch emulation; arm64 dropped from main publish. Native ARM runner matrix planned for v1.5.
• CI integration tests + e2e workflows green again.

⚠️ Hard-Reload (Cmd+Shift+R) for SW reset. 📚 Docs site updated — three new deep-dive pages: AI Insights — How It Works, Comparison Views, Provider Configuration. 🎯 v1.5 roadmap: see .planning/phase-D-product-lead-review.md.

---

What landed (per area, with commit SHAs)

Cleanup A — Quick fixes

Bucket	Commit	Subject
A1	77fe256	fix(nav): admin sub-items don't expand from gravatar dropdown or admin-link click
A2	577d8dd	fix(insights): BD-Zielbereich computes correctly for real measurement data
A3	277a5aa	fix(admin): api-tokens table no horizontal overflow on Pixel-5 viewport
A4	4df6dac	feat(charts): "7-Tage-Trend" rename + slope30 fallback for sparse metrics
A5	93e712d	fix(dashboard): top-tile selector persists (widget-id enum drift fixed)
A6	9b01c86	feat(charts): medication chart matches other charts (7d trend + indicator + target-range)
A7	(within 9b01c86)	feat(insights): rate-limit 10/h + cache-evict on regenerate (cross-agent race captured A7)
A8a	2da0703	fix(geo): preserve umlauts in city names (login-overview no longer renders "Nrnberg")
A8b	af77e5e	feat(charts): split-half mean delta on long-window trend

Cleanup B — Quality-leap features

Bucket	Headline commits	What it does
B1a	74c2eb8, 901f44e, 8008613, 2611bb4	BP / weight / pulse / mood / medication chart polish
B1b	4d7d074, 9e8be4b, b76351e, 0c287f1, d2cdf9d, 5063ad7, 3b0d21e	/insights hero + recs grid + dashboard preview
B2	(worktree agent/b2-ai-provider-ux ff)	Single-pulldown Settings → AI + chain editor
B3	5d1ece1, f1bd801, 2877710, (chart inside 8d9f864)	Admin host-load chart (in-process sampler, 7d)
B4	(audit-log inside 8ac5602), 4cc3d8d, 6520ae4	Admin audit-log filter + CSV + app-log preview
B5a	27f3933, 466b8b5, 7fbfca6, 53aade9, a66c128	Curated medical-reference bundle + citation footnote
B5b	2611bb4 (column), runner inside 901f44e, 613d661, d2bda42	Multi-provider fallback chain + last-working cache
B5c	8a438a0, c39a527, 13f1ae5, c8b30c1, 7f54c0c, 680f84c, 10a67ff, fed2e7e	Per-rec rationale (window / comparedTo / deviation)
B5d	0cb0373, af21d4d, 7ec1030, 63cfd8e, d343ab5, 173c3e1	Deterministic confidence meter (server-overrides)
B5e	badc893, 8255e3e, ca84fb7, 47ca1e4, 71ffe30, 8879282	RecommendationFeedback + daily aggregator + admin
B6	01a05e4, a432cb2, ed0cfda, d914f76	Settings naming audit + i18n parity guard
B7	621109c, a512650, 94c748d, (routes inside 226cac4), d5c8912, 830b2b0, e628f33	Settings → Export consolidation
B8	775df8c, 2cf7b74, e4a408e, f9f99ea	Comparison overlay on charts + tiles + AI narration

Cleanup C — Catch-up (deferred from v1.4.15)

Item	Commit	Notes
CI fix (encryption-key + tour-overlay)	fbcd106	Both pre-existing red since d8c549e; both green from here on
H1 admin restore-failed scrub	fdac9e2	code-review HIGH
H2 moodEntry.tags JSON-array refine	7f1a4de	code-review HIGH
H4 tour-launcher per-user sessionKey	2afe3c4	code-review HIGH
H4 design 44 px tap targets sweep	b863e2c	tour / backups / notifications
i18n parity Quelle / Leitlinie	2a7ef72	B5a follow-on
MED tabs horizontal scroll	d7c2b2a
MED bottom-nav 5+More	072eee6	overflow sheet
MED system-status retry button	65b4bf9
Auto-deploy v1.5 doc	4be6465	Coolify auto-deploy stays on git-push for v1.4.16; deferred
docker-publish drop qemu-arm64	cc0f343	qemu-SIGILL root cause; native-runner matrix in v1.5

5 of 8 deferred HIGH from v1.4.15 Cleanup-D landed; 3 of 5 deferred MED from A5 mobile landed; Coolify image-digest auto-deploy deferred per the maintainer's "leave it" call.

Cleanup D — Multi-pass QA + Reconcile

• CRITICAL (3 of 3 cleared): C1 wired (aae968a — <InsightAdvisorCard> mounts on /insights), C2 wired (8a5b6de — <InsightsCardPreview> mounts on /), C3 on-surface comparison toggle (6e74d38).
• HIGH (9 fixed inline): 5f7b9d8, 6863ecb, fb12f09, c3451a4, 2f057f4, 5661439. 11 HIGH deferred to v1.5 backlog.
• Simplify (7 of 8 apply-yes landed): f3025a8. F1 + F8 are apply-no, flagged for the maintainer.
• Product-Lead review stands as-is and IS the strategic v1.5 plan (.planning/phase-D-product-lead-review.md).
• Style cleanup: c63cddc.

Cleanup E — Release

Item	Result
Pre-release verify	pnpm typecheck clean; pnpm test 1540/1540; integration 59/59
Release commit	d443c22 chore(release): v1.4.16
Tag	v1.4.16 (annotated)
GHCR — tag run	25616783583 success, digest 2f1a0d6b381d…
GHCR — main run	25616782255 success, digest 4841bef396ad…
Coolify auto-deploy	NO — same race as v1.4.14/v1.4.15; retag-on-host fallback used
Live image digest	sha256:05f8a126d63962d9a4af4769de830d3fee022d634787e811b4339ee464420daa
/api/version transition	1.4.15 → 1.4.16 at 2026-05-10T03:45:58+02:00
Smoke (14 routes, live session)	13/14 200; /dashboard 404 expected (root is dashboard)
GH release	https://github.com/MBombeck/HealthLog/releases/tag/v1.4.16
Docs site	8addef4 + 2a5802b on healthlog-docs/main (44 pages, three new deep-dive pages)
Landing site	3d17207 on healthlog-landing/main (1.4.15 → 1.4.16, AI cards updated)

---

What was deferred + why

Full backlog: .planning/v15-backlog.md. Highlights:

• 11 HIGH from QA → v1.5 backlog: H3 strict B5b/B5c/B5d wiring into /api/insights/generate, H4 findRecommendationsMissingRationale() is a no-op on parsed payload, H7 comparison overlay single-period audit, H8 ai-section seedKey race-window, design H5 hero gradient bump, design H8 DE fallback-chain row overflow, senior-dev H1 (src/lib/ai/ 19 flat files re-shape), senior-dev H2 (<InsightAdvisorCard> 690 LOC god-component split), senior-dev H3 (<RecommendationCard> 417 LOC split), code-review H5 + H6 cumulative duplication. Sized in the product-lead review.
• 2 simplify-no items: F1 runWithFallback test-only (delete and migrate or wire to strict variant — maintainer's call), F8 RecommendationCard.normalise() indirection (mechanical rewrite spans 8+ JSX sites).
• Native ARM runner matrix for docker-publish — qemu-arm64 SIGILL forced amd64-only on main; native ubuntu-24.04-arm matrix is the v1.5 plan.
• Coolify image-digest auto-deploy — still on git-push trigger; deferred per the maintainer's "leave it" call. The manual Coolify UI toggle is the 5-min realistic fix per docs/audit/v1416-auto-deploy-fix.md.
• Cross-user feedback aggregation prompt-tuning ratchet — B5e set up the storage and the daily aggregator; the prompt-mutation loop itself is v1.4.17 / v1.5 work.
• Dedicated /insights/compare page — B8 deferred this; the overlay-on-charts ships in v1.4.16. i18n keys comparison.insightsCallout.{lastMonth,lastYear} reserved so the future component drops in clean.
• Senior-dev H1 + H2 splits from v1.4.15 — both still open; carry forward into v1.4.17 architectural pass.
• Mood-chart H3 (chart-presentation) from v1.4.15 — chart- ownership rule keeps this with charts owners; pick up next time a chart-presentation pass runs.

---

CI / Test status

• pnpm typecheck — 0 errors.
• pnpm lint — 0 errors / 12 pre-existing warnings.
• pnpm test — 1539 unit tests green (started v1.4.16 release cycle at ~1048; +491 net across A/B/C/D/E cleanups).
• pnpm test:integration — 59 / 59 green (was 31 at v1.4.15).
• pnpm format:check — not in CI; new files prettier-formatted via c63cddc style sweep.
• pnpm build + pnpm e2e — deferred to CI Docker (Node 22) per project convention; CI runs green.

---

Production state

• URL: https://healthlog.bombeck.io
• /api/version: 1.4.16 ✓
• Image digest: sha256:05f8a126d63962d9a4af4769de830d3fee022d634787e811b4339ee464420daa (was v1.4.15: sha256:ace7d441f47bd8c69fd0c5e2417b7f6c53bc387aa10c9aa541ad5e6321e9581d)
• Smoke (14 routes, live session): 200 across /, /insights, /auth/login, /settings/integrations, /settings/notifications, /settings/ai, /settings/export, /admin, /admin/users, /admin/backups, /admin/system-status, /admin/app-logs, /achievements. /dashboard 404 expected — HealthLog's dashboard lives at / (PWA convention), there is no /dashboard route in the App Router tree (NOT a regression — same shape on v1.4.15).
• Deploy method: GHCR-tag-build :1.4.16 succeeded (Cleanup-C C3 fix dropped arm64 on main and made BOTH GHCR runs green for the first time since v1.4.13). Coolify auto-deploy fired on the chore(release) commit before GHCR finished and pulled the host's stale local :latest cache; retag-on-host fallback (docker pull :1.4.16 && docker tag :1.4.16 :latest && docker compose up -d app) flipped /api/version 1 s after the up command returned.
• Coolify auto-deploy: still fires on every git-push (deferred per the maintainer's call); v1.5 plan in docs/audit/v1416-auto-deploy-fix.md.
• GitHub release: https://github.com/MBombeck/HealthLog/releases/tag/v1.4.16
• Tag naming (unchanged since v1.4.14): GHCR-OCI tag is :1.4.16 (no v prefix); git tag is v1.4.16.

---

Docs / Landing

• healthlog-docs (Starlight) — 44 pages, three new deep-dive routes:
  • /insights/how-it-works/ — recommendation card walk-through, deterministic confidence computation, fallback hard-fail policy, "low confidence" semantics, feedback usage today + planned, per-user privacy.
  • /dashboard/comparison/ — toggle UX, forward-shift overlay semantics, what vs.-last-month / vs.-last-year actually compute, sparse-data handling, deferred follow-ups.
  • /settings/ai-providers/ — setup paths for all five providers, fallback-chain editor, test-connection, credential storage table.
• healthlog-landing (Next.js) — softwareVersion 1.4.15 → 1.4.16 in JSON-LD; AI-insights hero card rewritten as "AI insights that show their work" leading with explainability + confidence + citations; capability badges row picks up two new badges.

---

v1.5 strategic outlook

The Product-Lead review at .planning/phase-D-product-lead-review.md contains the full v1.5 roadmap and is the strategic plan for v1.5. Top items to look at:

1. Coolify image-digest trigger (C.1) — replaces git-push churn. 5-min manual Coolify UI toggle.
2. Native ARM runner matrix (C.2) — re-add linux/arm64 to GHCR matrix via native ubuntu-24.04-arm runner.
3. Cross-user feedback ratchet → prompt-tuning (C.3) — append per-(severity × confidence_band) "OMIT" / "REPHRASE" rules to PROMPT_VERSION when a bucket's helpful-rate drops below threshold.
4. Dedicated /insights/compare page (C.4) — sticky baseline picker + aiInsightResponseSchema.comparison field + <InsightsComparisonCallout> above the recs grid.
5. iOS native client API contract freeze (C.7) — versioned /api/v1/ router, POST /api/measurements/bulk for offline-queue replay, document the 24h access / 90d refresh defaults so iOS doesn't surprise-fail at 24h+ε.
6. Apple Health import via iOS (C.11a) — XML parse + map + bulk endpoint; the natural pipe is the iOS app.
7. (See review §C.5 streaming + A/B + per-user prompt prefix, §C.6 charts library decision, §C.8 security hardening sweep, §C.9 performance, §C.10 S3 backup push, §C.11 Garmin / Oura integrations.)

Recommended 6-week focus pick from the review: C.1 + C.2 + C.4 + C.7 + C.10 + C.11a Apple Health.

---

Hard-Reload reminder

Cmd+Shift+R (Mac) / Ctrl+Shift+R (Linux/Win) — the new service worker otherwise still serves v1.4.15 chunks from cache. One-shot is enough.