Consolidated hotfix landing the findings from a six-axis audit
covering mobile security, UX + accessibility, code quality + docs,
README + discoverability, web performance, and mobile-deep responsive
behaviour. None of the changes break the public API or the existing
data shape; every fix is additive and SAFE under the v1.4.34.x web
freeze. Full audit reports live in `.planning/round-audit-*.md`.
Security
- Password rotation now wipes API tokens + refresh tokens in the
same `$transaction` as session revocation. A stolen iOS Bearer no
longer survives a user-initiated password change or an admin reset.
- `/.well-known/` proxy bypass tightened to an explicit-allowlist
`Set`. Stale `/api/auth/codex/callback` PUBLIC_PATHS entry dropped.
- HSTS gains `preload`. Withings host removed from the global CSP
and gated to the integration's own routes.
- `getClientIp` warns once per process on `TRUST_PROXY_HOPS`/XFF
mismatch + exposes a tagged helper for tighter universal buckets.
- Service worker rejects off-origin notification-click URLs. Offline
fallback body switched to a locale-neutral icon. Manifest gains
`scope`, `id`, `display_override`.
UX + accessibility
- i18n leaks closed on Dialog/Sheet close-X, ChartSkeleton's loading
announcement, and the notifications-section breadcrumb.
- Focus rings on bottom-nav, the More overflow button, and the
mobile top-bar user menu.
- Tap-target floor: Input / NativeSelect / Select / DateTimeInput
switch to `h-11 sm:h-10`.
- Admin chip-strip auto-scroll-into-view (matches v1.4.33 settings).
- List-page subtitles visible on mobile.
- Insights empty-state CTA vocabulary normalised so the link opens
the right measurement form (was silently failing for
BODY_TEMPERATURE / BLOOD_GLUCOSE / PULSE).
Mobile-deep
- `viewport.themeColor` reacts to light/dark mode.
- TopBar + Coach FAB reserve safe-area-inset-top / -bottom for
notched iPhones.
- Sonner toaster switches to `theme="system"`.
Code quality
- `SESSION_SECRET` dropped — the env var was documented as required
but never read by code. Three secrets, not four. Self-hosters
upgrading can delete the existing line.
- `toJson<T>()` helper consolidates seven Prisma JSON-cast sites.
- `db-compat.ts` gains a header docstring naming it the
schema-bootstrap path.
- Passkey response types adopted from `@simplewebauthn/server`;
`any` + eslint-disable pragmas drop out.
- Zero-TODO CI gate added at `.github/workflows/no-todo-markers.yml`.
Documentation + discoverability
- README rework: How-it-compares matrix, Apple Health + AI Coach
promoted to standalone Key-Features bullets, status block, latest
release + GHCR badges, OpenAPI pointer, three-secret Quick Start.
- openGraph + twitter cards now carry `images` and a
`summary_large_image` Twitter card.
- GitHub repo metadata: description tightened from 290 to 156
chars + keyword-front, `homepageUrl` flipped from a personal
tenant to the demo site, six generic / PII-adjacent topics
swapped for six high-intent ones.
- Five new user-facing docs: `docs/self-hosting/getting-started.md`,
`docs/self-hosting/reverse-proxy.md`,
`docs/integrations/apple-health.md`,
`docs/integrations/withings.md`,
`docs/integrations/ai-providers.md`.
- `docs/README.md` clarifies the docs tree as internal playbooks
vs the user-facing `docs.healthlog.dev` site.
17 KiB
README + Docs + GitHub Discoverability Audit — 2026-05-16
Executive summary
The README is well-structured and content-rich, but it underplays the two strongest discoverability hooks the project actually ships: Apple Health import (the headline v1.4.34 feature is invisible in the README) and AI Insights / Coach as a visual differentiator (mentioned once, as a feature bullet, never shown). There is no hero screenshot or animated demo above the fold, no comparison table against Withings / Apple Health / Oura / self-hosted alternatives, and the GitHub description field omits "self-hosted health tracker" — the exact phrase the target user types into search. homepageUrl points at the production tenant (healthlog.bombeck.io) instead of the demo (demo.healthlog.dev) or the docs site. Fix shape: a hero image + 8-row comparison table + 3 keyword swaps in the GitHub description + 6 new topics would 5-10× search impressions without touching the codebase.
Findings — prioritized
F-1: No hero screenshot or animated demo above the fold
Severity: high
Scope: README
Citation: README.md:1-30 — header block is logo + badges + tagline + nav links; nothing visual until line 80 (Quick Start).
What's wrong: GitHub renders the first viewport on the repo landing page. Today a visitor sees a 120 px logo, four badges, and three text paragraphs — nothing that conveys "this is a dashboard product" until they scroll past the feature list. Every comparable repo (immich, mealie, paperless-ngx, dawarich) leads with a screenshot or animated GIF; this is the single highest-leverage README change.
Fix shape: Add a dashboard screenshot (or 2x grid: desktop + mobile PWA) right after the tagline, before badges. Ideally a .webp capture of the dashboard with the trends row + a Coach card visible. Add to public/screenshots/ and reference as <img src="public/screenshots/hero-dashboard.webp" />. No PII — use the demo tenant or synthetic data.
Effort: small (screenshot + commit)
F-2: Apple Health import — the headline v1.4.34 feature — missing from README
Severity: high
Scope: README, SEO
Citation: README.md:46-77 — Key Features list. Grep apple health against README: zero matches. CHANGELOG.md:94 ships it as the v1.4.34 banner feature.
What's wrong: "apple health export server" / "apple health xml import" / "apple health self-hosted" are exactly the queries a user looking to escape the iOS ecosystem types. The repo topics include apple-health; the README does not. GitHub search ranks README content; not surfacing the keyword in the README means the topic alone won't carry the search.
Fix shape: Add a dedicated Key-Features bullet: "Apple Health import — Drop your export.zip on the import page. The server streams it to disk, parses the XML (handles Zip64 / multi-GB exports), and folds every <Record>, <Workout>, <Correlation> into your timeline. Idempotent — re-upload to merge new data without duplicates." Mirror in the Integrations table.
Effort: trivial [hotfix-ready]
F-3: AI Coach / Insights surface buried in a single bullet
Severity: high
Scope: README, SEO
Citation: README.md:60 — single bullet "Multi-Provider AI Insights"; no "Coach", no "Daily Briefing", no "Health Score", no "Weekly Report".
What's wrong: Per maintainer-stated positioning, AI Insights are the differentiator. The README treats them as one feature among twelve. Coach (the conversational surface), Health Score (the daily tile), Daily Briefing, and Weekly Report — all shipped v1.4.20-onward — are not named in the README at all. A user comparing this against generic dashboards never learns the project's flagship.
Fix shape: Promote AI Insights to a dedicated section between "Why HealthLog?" and "Key Features", with three sub-bullets (Coach / Health Score / Briefing). One screenshot. Frame it as "evidence-grounded, multi-provider, your data stays on your network."
Effort: small
F-4: No comparison table
Severity: high
Scope: README, SEO (alternatives-linking is an SEO signal)
Citation: README.md — absent.
What's wrong: Visitors arrive comparing this against Withings web, Apple Health, Oura, Garmin Connect, and the few self-hosted options (Wger, OpenHealth, Wakapi for activity). Without a comparison table, they bounce to evaluate alternatives independently. Linking to alternatives is also a positive SEO signal (mutual relevance).
Fix shape: 6-column matrix: HealthLog | Withings | Apple Health | Oura web | Garmin Connect | Generic CSV. Rows: Self-hosted, Open source, BYOK AI, Withings sync, Apple Health import, Doctor PDF, Custom thresholds, No subscription, License. Place after "Why HealthLog?".
Effort: small [hotfix-ready]
F-5: GitHub description is technically dense but misses primary search keywords
Severity: high
Scope: repo metadata, SEO
Citation: GitHub UI → About → description: "Self-hosted, privacy-first personal health tracking PWA. Weight, blood pressure, body composition, glucose, sleep, mood, medications. Withings + Apple Health sync, multi-provider AI Insights (BYOK), client-side doctor-report PDF."
What's wrong: 290 characters — over the GitHub UI ~200 char cutoff for the About sidebar. The high-value phrase "self-hosted health tracker" (without "ing") isn't in there, which is what 80% of search queries phrase. "Apple Health" appears but "withings alternative" / "self-hosted apple health" do not.
Fix shape: ≤ 160 chars, keyword-front-loaded: "Self-hosted health tracker. Weight, blood pressure, glucose, mood, medications. Withings + Apple Health sync. AI Insights you own. AGPL." Edit via gh repo edit MBombeck/HealthLog --description "...".
Effort: trivial [hotfix-ready]
F-6: homepageUrl points at the maintainer's production tenant, not the demo
Severity: medium
Scope: repo metadata, SEO, privacy
Citation: GitHub repo → homepageUrl = https://healthlog.bombeck.io.
What's wrong: The maintainer's personal subdomain is exposed as the project homepage. It is not the public demo. New visitors clicking the sidebar link land on a login wall, not a working preview. Demo lives at demo.healthlog.dev; the project site at healthlog.dev.
Fix shape: gh repo edit MBombeck/HealthLog --homepage https://demo.healthlog.dev (or https://healthlog.dev once that landing exists). Demo is higher-impact for conversion.
Effort: trivial [hotfix-ready]
F-7: No custom social preview image (uses generic GitHub auto-OG)
Severity: medium
Scope: repo metadata, SEO
Citation: usesCustomOpenGraphImage: false in gh repo view output.
What's wrong: When the repo URL is pasted into Slack / Discord / Mastodon / X, the unfurl shows a generated tile with the repo name. Comparable projects (immich, dawarich) ship a branded 1280×640 PNG showing the dashboard. This is the visual that gets shared.
Fix shape: Upload a 1280×640 PNG via GitHub UI → Settings → Social preview. Suggested content: dashboard screenshot + "HealthLog — your health data, your server" tagline + logo. The same asset can live in public/og-image.png and be referenced from src/app/layout.tsx:49 (currently no images field in openGraph).
Effort: small
F-8: GitHub topics — high-relevance gaps + one low-value entry
Severity: medium
Scope: repo metadata, SEO
Citation: GitHub repo → topics array (19 entries).
What's wrong: Missing withings-alternative, apple-health-import, personal-dashboard, ai-insights, glucose-tracker, mood-tracker, doctor-report. Present glp-1 and mounjaro are PII-adjacent (specific medications the maintainer likely tracks) and dilute the search graph. tracking and health are too generic to win against millions of repos.
Fix shape: Replace glp-1, mounjaro, tracking, health with withings-alternative, apple-health-import, personal-dashboard, ai-insights, glucose-tracker, mood-tracker. See "Suggested topics" below for the ranked list.
Effort: trivial [hotfix-ready]
F-9: No .github/FUNDING.yml
Severity: low
Scope: repo metadata
Citation: find .github -iname "FUNDING*" returns empty; fundingLinks: [] in gh repo view.
What's wrong: No sidebar "Sponsor" button. AGPL self-hosted projects without funding visibility plateau on stars but not on sustained contribution. If the maintainer has any GitHub Sponsors / Ko-fi / Liberapay link, adding it surfaces a sponsor button on the repo page and on every PR.
Fix shape: .github/FUNDING.yml with github: [MBombeck] or similar. Skip if no funding intent.
Effort: trivial
F-10: docs/ tree is operator-/audit-heavy, user-facing guides live elsewhere
Severity: medium
Scope: docs/
Citation: find docs -name "*.md" — 27 of 31 files are docs/audit/v14XX-summary.md or ops/migration notes. No user-facing setup guide tree.
What's wrong: A visitor following "see Self-Hosting → Reverse Proxy" (README.md:107) is bounced to docs.healthlog.dev, but the in-repo docs/ tree appears to be the operator's working notes. There's no docs/getting-started.md, no docs/integrations/apple-health.md, no docs/integrations/withings.md, no docs/ai-providers.md in the repo. This is fine if docs.healthlog.dev is the canonical surface — but the canonical surface needs verifying, and docs/ should signal "see docs.healthlog.dev" with a README, not look like a half-built docs tree.
Fix shape: Add docs/README.md (top-level) saying "User docs live at docs.healthlog.dev. The files here are internal operator audits and migration notes." Or move audit/ into docs/audit/ ring-fenced. Verify the topics the README links to (/self-hosting/reverse-proxy/) exist on the public docs site.
Effort: small
F-11: No docs/api/openapi.yaml link in README
Severity: low
Scope: README, docs/
Citation: docs/api/openapi.yaml exists (docs/api/README.md:1) but the README's API Reference section (README.md:240-386) doesn't reference it.
What's wrong: A developer evaluating integration potential doesn't see an OpenAPI spec is available. The README's API table is good for scanning; the OpenAPI spec is the codegen target. Both should be discoverable.
Fix shape: Add one line above the API Reference collapsibles: "Machine-readable OpenAPI 3.1 spec: docs/api/openapi.yaml. Generates iOS DTO + any client codegen."
Effort: trivial [hotfix-ready]
F-12: README Tech Stack omits the iOS native client
Severity: low
Scope: README
Citation: README.md:111-128 — Tech Stack table; no iOS / Swift / SwiftUI row.
What's wrong: The repo carries docs/apple-store-connect-checklist.md and v1.4.23-onward CHANGELOG entries describing the native iOS app foundation. The README hides this; a visitor sees "web PWA only."
Fix shape: Add row "iOS client | SwiftUI (separate repo, in development)" or call it out in a Roadmap section.
Effort: trivial
F-13: No Roadmap / Status section
Severity: low
Scope: README
Citation: README.md — absent.
What's wrong: Visitors can't tell what's next, what's stable, or whether the project is alive. The CHANGELOG shows ~daily releases; that signal doesn't reach the landing.
Fix shape: A small "Status" section: "Active development. ~weekly releases. Current focus: native iOS client (v1.5)." Plus one-line Roadmap link to a GitHub Project board or to the discussion forum.
Effort: trivial
F-14: src/app/layout.tsx openGraph has no images field
Severity: low
Scope: SEO
Citation: src/app/layout.tsx:49-57 — openGraph block lacks images:.
What's wrong: When demo.healthlog.dev is shared in chat, the unfurl has no image. Same problem as F-7 but for the live app, not the repo.
Fix shape: Add images: [{ url: "/og-image.png", width: 1200, height: 630 }] and ship public/og-image.png. Same asset as F-7.
Effort: trivial
F-15: README has no badge for latest release or Docker pulls
Severity: low
Scope: README, SEO
Citation: README.md:11-17 — 5 badges, none of which surface version or activity.
What's wrong: A current-version badge tells visitors the project is alive without them scrolling. Docker pulls signal traction.
Fix shape: Add  and  (GHCR doesn't have a pulls counter but the latest-tag badge serves the same role).
Effort: trivial [hotfix-ready]
Suggested topics
Ranked by search-volume × relevance. Aim for 15-18 active topics; drop glp-1, mounjaro, tracking, health, dashboard (too generic).
self-hostedhealth-trackingpwanextjsapple-healthwithingsapple-health-importwithings-alternativepersonal-healthquantified-selfprivacyprismamedication-trackerglucose-trackermood-trackerai-insightsdockeragpl
Draft README revision
Not warranted as a full rewrite. The existing structure is sound; the top three changes (hero image + Apple Health bullet + comparison table) are additive edits to the current document. Suggested insertions to the existing README:
Insert after line 22 (before the "Website / Live Demo / Documentation" link row):
<p align="center">
<img src="public/screenshots/hero-dashboard.webp" alt="HealthLog dashboard — trends, Coach card, Health Score" width="900" />
</p>
Insert as a new section after "Why HealthLog?" (after line 44):
## How it compares
| | HealthLog | Withings web | Apple Health | Oura web | Generic CSV |
| ------------------------ | ------------------ | -------------- | ------------ | ---------- | ----------- |
| Self-hosted | Yes | No | No | No | Yes |
| Open source | AGPL-3.0 | No | No | No | n/a |
| Withings device sync | Yes (OAuth2) | Yes (native) | Via shortcut | No | No |
| Apple Health import | Yes (`export.zip`) | No | Native | No | Manual |
| Custom clinician targets | Yes (audit-logged) | Limited | No | No | n/a |
| Doctor-report PDF | Yes (client-side) | No | No | No | n/a |
| AI Insights | Multi-provider BYOK| No | Limited | Subscription| n/a |
| Subscription required | No | For some metrics| No | Yes | No |
| Your data leaves device | Never | Withings cloud | Apple cloud | Oura cloud | Depends |
Insert as a new bullet inside Key Features (between line 58 and line 60):
**Apple Health import** — Drop your iOS `export.zip` on the import page. Streaming parser handles multi-gigabyte archives (Zip64), folds every record / workout / correlation into your timeline, and stays idempotent on re-upload. Per-type ingestion stats and live progress on a status endpoint.
Insert as a new bullet inside Key Features, promoted to first position (replace current line 60 "Multi-Provider AI Insights"):
**AI Coach + Insights** — A conversational Coach trained on your own data, a daily briefing, a weekly report, and a Health Score tile on the dashboard. Pick OpenAI, Anthropic Claude, or any OpenAI-compatible local endpoint (Ollama, LM Studio, vLLM). BYOK or admin-shared. Evidence-grounded — every claim links back to the measurements that produced it. Local endpoints keep all data on your network.
Add a one-line Status block after the "What it is" paragraph (after line 36):
> **Status**: active. New releases roughly weekly — see [CHANGELOG](CHANGELOG.md). Current focus: native iOS client (v1.5).
Replace badges block (lines 11-17) with:
<p align="center">
<a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg" alt="License: AGPL-3.0" /></a>
<a href="https://github.com/MBombeck/HealthLog/releases"><img src="https://img.shields.io/github/v/release/MBombeck/HealthLog?sort=semver&color=success" alt="Latest release" /></a>
<img src="https://img.shields.io/badge/Self--Hosted-yes-success" alt="Self-Hosted" />
<img src="https://img.shields.io/badge/Next.js-16-black?logo=next.js" alt="Next.js 16" />
<img src="https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
<a href="https://github.com/MBombeck/HealthLog/pkgs/container/healthlog"><img src="https://img.shields.io/badge/GHCR-multi--arch-2496ED?logo=docker&logoColor=white" alt="GHCR" /></a>
</p>
Out of scope
- Rewriting
docs.healthlog.devcontent (separate audit; outside repo). - Producing the actual hero screenshot / OG image binary (asset creation, not code).
- Editing the live GitHub repo metadata (
description,topics,homepageUrl) — flagged as[hotfix-ready], awaiting maintainer command. - CONTRIBUTING.md / SECURITY.md / CODE_OF_CONDUCT.md content review beyond presence check (all three present and structurally sound; no critical issues found).
- Release-note quality audit per release (CHANGELOG is comprehensive; the v1.4.34 entry reads well).
- E2E / integration test coverage of the docs links themselves.