End-to-end summary of the eight-axis audit + the two consecutive
hotfix releases that landed the hotfix-ready findings: security,
UX/a11y, code quality, mobile-deep, docs depth, README + GitHub
discoverability, perf, and test coverage. Lists what shipped, what
got deferred to v1.5.x, the operator-action delta (one obsoleted),
and the quantitative deltas (24 commits, 2 releases, 55 net new
tests, 5 new user-facing docs).
README:
- Add a "How it compares" matrix against Withings web, Apple Health,
Oura, Garmin, and generic CSV. The audit found this section absent;
self-hosters arrive comparing alternatives and bounce when there's
no head-to-head.
- Promote Apple Health import + AI Coach as standalone Key-Features
bullets. Apple Health was the v1.4.34 banner feature with zero
grep matches in the README until now; the audit ranked it the
single highest-intent search keyword for ex-iOS users. AI Coach
+ Insights moved out from under "Multi-Provider AI Insights" into
a dedicated bullet that names the Coach, Daily Briefing, Weekly
Report, and Health Score surfaces.
- Status block under "What it is" so visitors see release cadence
+ current focus (native iOS client) without trawling the changelog.
- Badge row: drop "PRs welcome" + duplicate Self-Hosted, add a live
"Latest release" badge + a GHCR multi-arch badge so the landing
page surfaces version + container distribution at a glance.
- Tagline tightened to lead with "self-hosted health tracker" + the
two integration anchors (Withings + Apple Health) — both phrases
are search-keyword fronts the GitHub search index picks up.
- Drop the dead SESSION_SECRET env entry from Quick Start (3
secrets, not 4) and the Environment Variables table — the env
var was documented as required but never read by code (per the
code-quality audit). Companion env-removal in docker-compose /
.env.example / entrypoint ships in a parallel batch.
- Add a one-line OpenAPI pointer above the API-Reference table so
integrators discover the codegen source.
Layout / OG metadata:
- openGraph + twitter cards now carry images, a higher-intent
description, and a summary_large_image card. Uses the existing
logo-readme.png as the OG asset; replace with a 1200x630 dashboard
capture when one ships.
GitHub repo metadata (via gh CLI, no git diff):
- description tightened from 290 chars to 156 chars, keyword-front.
- homepage flipped from a personal tenant to demo.healthlog.dev so
sidebar clicks land on a working demo instead of a login wall.
- Topics: dropped 6 generic/PII-adjacent entries (glp-1, mounjaro,
tracking, health, dashboard, bloodpressure), added 6 high-intent
ones (apple-health-import, withings-alternative, glucose-tracker,
mood-tracker, ai-insights, personal-dashboard).
Planning artifacts:
- 7 audit reports drop into .planning/round-audit-*.md covering
mobile-security, UX, code-quality, README/discoverability,
perf, mobile-deep (pending), test-coverage, docs-depth. These
are the working notes for the v1.4.34.4 audit-driven release.
Backfills the planning trail for v1.4.34: IW-C / IW-D / IW-G work-item
reports, the production slowness HAR investigation, the AASA rollout
trace from v1.4.33, and three pieces of research that informed the
follow-on perf work (XML import, carryover scope, cache aggregation).
The cache-aggregation research (research/v1434-r-cache-aggregation.md)
designed the per-route LRU pattern that IW-G shipped and is the
direct ancestor of the comprehensive-route rewrite this release lands.
Sub-wave E records the close-out work for v1.4.34: e2e flake fixes
in onboarding-flicker + mobile-viewport, AASA verification across
healthlog.dev / healthlog.bombeck.io / demo.healthlog.dev plus
Apple's CDN ingestion endpoints, and the web-freeze marker that
lands on the CHANGELOG, prisma/schema.prisma, and the v1.5
strategic-plan decision log.
A caveat: a concurrent IW-G commit swept the staged web-freeze
edits into its own commit before this sub-wave's atomic commit ran.
The content landed correctly (verified with git show a5dd8e1d); the
commit message attribution is the only thing out of place. The
report documents the situation so the release-prep run can read
the actual state from disk.
Extends the v1.4.33 Coach snapshot LRU shape into a reusable
ServerCache<T> with TTL expiry, capacity-bounded LRU eviction,
single-flight read coalescing, prefix delete, and per-instance
hit/miss/eviction/stampede counters. Adds five invalidation helpers
keyed by the per-user prefix scheme so write endpoints can flush every
cache that may reflect their changed rows in a single call.
The cached() wrapper attaches cache.<name>.outcome + cache.<name>.key_hash
to the active wide event so production logs carry the hit ratio without
leaking the userId portion of the cache key.
Hand-rolled to keep the dependency surface at zero — same recipe as the
snapshot cache the dashboard already relies on. Process-local; multi-
instance staleness is bounded by TTL, the Redis migration path stays a
future option.
Captures the analytics lastSeenByType surface, the bfcache-friendly
Cache-Control directive, the dashboard tile-strip staleDays wiring,
the CoachLaunchProvider hoist, and the dashboard hero CTA — three
commits on develop with quality gates passing across 4205 tests.
Round close-out for the v1.4.34 Apple Health export.zip import work-
item. Records the seven atomic commits (deps → schema → parser →
worker → endpoints → tests → changelog), the parser perf numbers,
the carry-overs (HKClinicalRecord, ECG waveforms, workout routes,
ActivitySummary, <Me>), and the quality-gate evidence.
Three atomic commits landed for the v1.4.34 IW-F-Perf sub-wave:
shared achievements query hook + consumer collapse + regression
test + read-only analytics audit. Documents the touch-disjoint
compliance, the deferred checklist migration behind IW-B, and the
quality-gate evidence.
v1.4.34 IW-F-Perf — three changes.
1) New `use-achievements-query.test.tsx` mounts three consumers under
one TanStack QueryClient and asserts the shared queryKey collapses
them into a single network call. Pre-fix the notifier issued its
own request alongside the card; the regression guard surfaces it
immediately if a future drift reintroduces a per-user
discriminator.
2) Refresh `recent-achievements-card.test.tsx` and
`achievements/__tests__/page.test.tsx` to mock the new shared hook
directly instead of the raw `@tanstack/react-query` `useQuery`
shim. The two test suites stay scoped to render-shape, not the
network plumbing.
3) Capture the `/api/analytics` slim-vs-thick audit in
`.planning/round-v1434-iwfperf-analytics-audit.md`. The dashboard
root reads `bpInTargetPct*` + `glucoseByContext` so it must stay
thick; the checklist is correctly slim by IW2 design but is
mounted inside the dashboard render tree so its slim call
duplicates the thick one already in flight. Documented two clean
migration paths and flagged the work for v1.4.34.x behind IW-B's
in-flight slim-slice routing.
Five atomic commits on develop covering the carryover infrastructure
items from research blueprint v1434-r-2 plus the GHCR double-build
fix from the v1.4.33 closure-report iceberg notes. Report itemises
touch surface, verification steps, out-of-scope guardrails honoured
during the parallel-IW round, and five seeded operator follow-ups
(env-var prune on apps-01, edge-01 MCP daemon restart, optional
duplicate cleanup, CODEX_OAUTH_CLIENT_ID intent confirmation, and
the next-tag verification that the workflow now fires exactly once).
Read-only audit captured via `mcp__coolify-apps01__env_vars` (list)
plus an attempted `mcp__coolify-edge01__env_vars` call. apps-01
returned 56 entries with the section-1/section-2 split documented
under CHANGELOG.md v1.3.1 — every key in section 2 is either a
duplicate of section 1, an empty placeholder, or (for
POSTGRES_PASSWORD) the literal default string left over from the
Compose template. Runtime reads the first match so containers stay
healthy; the duplicates are cosmetic clutter that make root-cause
debugging slower on the next deploy regression.
Edge-01 MCP returned a connection error (matches the v1.4.33
closure-report iceberg note) — env audit on that host needs SSH
until the MCP daemon is restarted.
No deletes performed — operator action only. The report seeds the
priority order: delete the `POSTGRES_PASSWORD` placeholder first,
then optionally bulk-prune the remaining section-2 duplicates,
then confirm intent for the section-2-only `CODEX_OAUTH_CLIENT_ID`
entry.
The first attempt at the F2 fix (f9b8f3bd) split the spotlight tour
backdrop into four rectangular dim panels around the spotlight rect
and opted each one back into pointer-events: auto with its own
onClick={handleSkip}. The intent was to keep the spotlighted target
clickable while preserving the "tap backdrop to dismiss" affordance.
The flaw: tour-step 1 on the dashboard spotlights the tile-strip,
which sits in the middle of the page. The header "Add" button sits
ABOVE the spotlight. The TOP dim strip (rendered from y=0 down to
where the spotlight begins) therefore covered the entire header
area, so the very target the F2 audit named — the header Add
dropdown — was still being eaten, just by a smaller rectangle.
The four-panel split fixed exactly ONE coordinate (inside the
spotlight rect) and broke every coordinate outside it that a real
user might want to click during the tour: header buttons, the
user-menu avatar, sidebar links, the locale switcher.
This commit ships the contract that Joyride / Shepherd / Intro.js
have all standardised on: the dim is purely visual. The whole
tour layer is pointer-events: none; only the tooltip card opts
back into hit-testing. The four-panel split survives because it
still serves the visual purpose of NOT dimming the spotlighted
target, but each panel is now a <div aria-hidden="true"> with
pointer-events: none — no onClick, no aria-label, no interactive
semantics. The center-placement fallback follows the same shape.
The tooltip's onClick={(e) => e.stopPropagation()} guard came off
because nothing bubbles to the dim any more. Tour state (Skip,
Back, Next) lives entirely on the tooltip's footer buttons,
matching the affordance users expect and keyboard-accessible via
the existing Esc shortcut.
The e2e regression spec at e2e/onboarding-tour-passthrough.spec.ts
gained a third case and tightened the first one. Case 1 now runs
document.elementsFromPoint at the quick-add button's centre, walks
the stack, and asserts that NO element belonging to the tour
overlay has computed pointer-events !== "none". This pinpoints the
regression instead of observing the symptom. Case 2 swapped from
"click a dim strip skips" (an artefact of the failed intermediate
fix) to "the explicit Skip button in the tooltip dismisses the
tour". Case 3 reads computed pointer-events from every
[data-testid="onboarding-tour-dim"] and asserts each is "none" —
the load-bearing invariant the F2 regression violated.
Quality gates: typecheck clean, eslint clean on the touched files,
all 43 onboarding unit tests pass, all 6 F2 e2e cases pass locally
(3 cases x chromium-desktop + chromium-mobile).
PR #178 open in draft state; CI green on lint/typecheck/test +
integration + builds + dependency audit + secret scanning. One
e2e workflow regression on the F2 onboarding-tour-passthrough
spec is documented as a v1.4.34 carry-over — IW8's fix passed
its unit-level integration test but fails its own paired e2e
spec.
Five-agent audit pass plus the Playwright runtime sweep against v1.4.32.
The five audit documents land alongside the 58 runtime screenshots and
the runtime-results.json that drove the seven highest-severity
implementation rounds (IW1, IW3, IW4, IW6, IW8) on this branch. Future
contributors can trace each implementation commit back to a finding
without re-running the audits.
Records the four commits landed on develop (6-helper fold, per-
request memo on `getAssistantFlags`, 60 s LRU on
`buildCoachSnapshot`, slim `?slice=summaries` slice + integration
test) plus the test delta (+114 unit, +3 integration) and the
deferred follow-ups (mislabelled `2d630994` commit, dashboard
wiring, slim slice's anomaly/prior-window stubs).
Records the four landed fixes: F2 (onboarding tour click pass-through),
F14 (bottom-nav defence-in-depth), F19 (web-vitals sampling at 10%),
and the A4 dead-code sweep (AssistantDisabledNotice + settings
placeholder copy). Notes the coordination boundary with IW1, IW3,
IW4, and IW6 plus the regression guard at
e2e/onboarding-tour-passthrough.spec.ts.
Production GET /api/analytics returned HTTP 500 for users with very long
measurement histories (request-id d86db8e5… 2026-05-16 14:39:51 UTC).
The wide-event log pinned the failure at Promise.all index 3 (PULSE) with
RangeError: Maximum call stack size exceeded — a power user's Apple-Health
heart-rate stream crossed V8's ~125k function-arity ceiling on the
Math.min(...values) / Math.max(...values) spread inside summarize().
Fold sum, min, and max into a single pass over values so the transient
argument array goes away and the working set stays bounded at the array
itself. Mean is now derived from the same fold's sum/length instead of
a second reduce. No public API change; min/max semantics for an empty
series remain null via the early-exit branch.
Adds a 250 000-row regression in trends.test.ts that raises the exact
production stacktrace before the fix and passes after, plus a new
src/app/api/analytics/__tests__/route.test.ts that pins the route-entry
contract (5 000-row PULSE + zero-row brand-new user) so the upcoming
C1 architectural rewrite can't silently reintroduce a spread anywhere
along the call chain. Touched-file lint and pnpm typecheck clean;
broader src/lib + src/app/api/analytics sweep is 2671 / 1 skipped.
Records the six implementation commits + the full-suite-green
state so a resumer can pick up the CHANGELOG / version bump /
release pipeline without re-discovering the diff. Iceberg notes
cover the latent Prisma-field-name bug fixed in Commit 1, the
default-visible `recentWorkouts` widget, the four metrics
intentionally without an empty-state CTA, and the SVG-polyline
route-preview decision deferring MapLibre / Leaflet to v1.5.x.
`08-locked-contracts.md` gains §14 — "Assistant feature-flag
scope (locked v1.4.31)". Carries the full
`GET /api/feature-flags` response shape, the master-kill rule,
the cache posture, and the gated server endpoint matrix.
The §14 scope-rule sub-section locks verbatim from
`.planning/RESPONSE-TO-IOS-TEAM-2026-05-16.md` §3 R5: the matrix
gates BOTH server-routed AND iOS on-device assistant surfaces.
Apple Foundation Models on-device Coach + Briefing surfaces in
the v0.6.0 iOS path honour the same flag matrix as the
server-routed surfaces; the operator's intent is "no model-driven
surface in this app on this server" regardless of where the
inference runs.
The "What is NOT in this file" stub renumbers from §14 to §15.
Five releases in a row (v1.4.27 → v1.4.30.1) the publish workflow
returned a 2xx from the Coolify webhook but the running container
on apps01 still carried the prior `:latest` digest. Host-side SSH
fallback patched it every time at ~5 minutes per release.
Root cause: GHCR's CDN edge layer takes 30-90 s to propagate a
fresh manifest write to consumer pull endpoints. The
`docker buildx imagetools create` + `inspect` steps confirm the
manifest at registry-write time, but the webhook fires
immediately afterwards. Coolify's pull lands inside the
edge-propagation window, gets the prior digest, declares no-op,
and returns success. The webhook itself works; the spacing
assumption between push and pull was wrong.
Fix: add `sleep 90` immediately after the auth + skip-mode
guards in the `Trigger Coolify deploy` step. Diagnostic line
prints the resolved image version (`steps.meta.outputs.version`)
before the sleep so the workflow log surfaces the exact tag the
operator can sanity-check.
Cost: ~30% on the publish-job duration, but only after the image
is fully on GHCR. The release-flow walk-through clock is
unaffected; the host-side SSH fallback remains available as a
backstop.
Full root-cause + hypothesis matrix + escalation plan documented
in `.planning/round-coolify-auto-deploy-fix-2026-05-16.md`.
§2 of the v1.5 strategic plan now ends v1.4.33 without the freeze
marker. A new v1.4.34 sub-section lands per
`.planning/RESPONSE-TO-IOS-TEAM-2026-05-16.md` §3 R2: scope is
`POST /api/import/apple-health-export` (multipart) + streaming XML
parser + async job model (`{ jobId }` + `/status` polling) +
per-MeasurementType ingestion stats + idempotent UPSERT on
`externalId` + admin endpoint variant + mapping for
HKQuantityTypeSample, HKCategoryTypeSample and HKWorkout
(HKClinicalRecord defers per R-F T3). Effort L (~3-4 days).
The web-freeze marker moves to v1.4.34. The freeze posture, the
v1.5.0 version-bump shape, and the decision-log §5 rows
(web-freeze trigger, v1.5 release shape, web patch sequence, plus
a new "Apple Health XML import slot" row) all renumber. The
deferred §4 row and §6 open question #3 close out — the import is
now scheduled, not deferred.
§5b "Coach SSE" and §6 "Coach SSE drawer iOS implementation" both
reframed per `.planning/RESPONSE-TO-IOS-TEAM-2026-05-16.md` §3 R6.
The server endpoint `GET /api/insights/chat` stays live indefinitely
for PWA users, future iOS reevaluation post-MDR, and any other
client that adopts the SSE protocol. v1.5.0 iOS ships Apple
Foundation Models on-device Daily Briefing + Trend Observations as
the primary assistant surface; a native server-Coach drawer is
deferred pending MDR Class-IIa pre-review.
§3 of the iOS contributor brief now reflects the v1.4.30 production
state (both hosts on the iOS-coordinated foundation tag) and the
v1.4.30.1 follow-up. The recent-releases table gains two rows; the
"endpoints the iOS client may consume today" list gains the four
v1.4.30 surfaces (`/api/sync/state`, `/api/mood-entries/bulk`,
`/api/medications/intake/bulk`,
`/api/admin/drain-per-sample-cumulative`) plus the new v1.4.30.1
`/api/measurement-categories` projection.
Appends §13 to `08-locked-contracts.md` codifying the hard-spec
delivered in `.planning/RESPONSE-TO-IOS-TEAM-2026-05-16.md` §3 R9.
Covers bulk-backfill, steady-state bidirectional sync, write
conflict (LWW by `updatedAt` with server-wins on the millisecond
tie), delete conflict (409 + canonical row vs 410 Gone), and the
`GET /api/sync/state` envelope shape.
iOS uses this as the contract for the v0.6.0 standalone-first track
once `SyncMode = paired` is the live state. The "What is NOT in
this file" stub renumbers to §14.
iOS team's 2026-05-16 response confirms two strategic pivots
(Apple Foundation Models on-device + standalone-first for v0.6.0)
and asks ten coordination items. Every R1-R10 answered with
hard-spec commitments. Two new items land in the v1.4.x roadmap:
GET /api/measurement-categories endpoint (R1, v1.4.30) and the
conflict-resolution policy lock (R9, v1.4.30). Apple Health XML
import (R2) slates to v1.4.34 alongside the freeze marker.
R-A Option A handoff prep. Adds dailyStatsExternalId() helper alongside
the v1.4.29 CUMULATIVE_HK_TYPES set; the helper mints
"stats:<HKQuantityTypeIdentifier>:<YYYY-MM-DD>" so iOS can UPSERT one
row per day per cumulative type via the existing batch endpoint, the
unique index collapses re-syncs idempotently, and a future PATCH-on-
divergence call updates a late-watch-sync revision without inserting a
second row. Handoff docs (06 + 08) lock the shape for the iOS client.
Cumulative-type set unchanged from v1.4.29; spot metrics keep the
per-sample uuid externalId. Server tolerates both shapes during the
cutover window — the drain script (next commit) collapses pre-existing
per-sample rows post-cutover.
Tests cover the helper round-trip, the cumulative-type identifier wall,
and the iOS-trusted date-string passthrough.
Single onboarding doc the iOS contributor (or their automation) reads
once and then references continuously. Covers: the release model
(v1.5.0 is version-bump-only marker), every convention every commit
must honour, what's live in production today (v1.4.29.1), what
incoming patches deliver through to web freeze, and the locked
forward state at v1.5.0 — every endpoint + DTO + Prisma column + new
MeasurementType the iOS app can rely on consuming by ship date.
Maintainer directive 2026-05-16: the iOS TestFlight build is already
posting per-sample cumulative rows; the daily-stats cutover cannot
wait for a v1.5 sprint. v1.4.30 now ships the R-A server-side helper
plus a one-shot drain script so the iOS TestFlight build can adopt
`HKStatisticsCollectionQuery` immediately. The remaining web patches
slide one slot — v1.4.31 picks up the assistant toggles + insights
blocking + Coolify auto-deploy fix, v1.4.32 + v1.4.33 carry the
HealthKit Tier 1 surfaces.
Daily-step aggregation hotfix shipped same day as v1.4.29; closure
stanza records PR #173, squash SHA 945b5566, tag, and the SSH
host-side fallback that finished apps01 rollout after Coolify
auto-deploy stalled for the third release in a row.
v1.4.29 ships dashboard performance + chart polish on both hosts.
Two new findings surfaced during the window: an /insights tab-strip
blocking root cause and an assistant-optional operator toggle plan.
Both land as v1.4.30 scope add-ons alongside the iOS server-prep menu.
Marc-André Bombeck