diff --git a/.planning/STATE.md b/.planning/STATE.md index 32936fdbe..fb88021dd 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -67,9 +67,11 @@ Combined sweep across HealthLog main repo + healthlog-docs + healthlog-landing ### F6 — Multi-agent QA on new docs -- [ ] After F2 lands: separate agents read dev-vs-prod docs -- [ ] Verify they describe actual deployed state — no incorrect claims -- [ ] Flag and fix anything inaccurate before tag +- [x] 38 docs site pages cross-checked against the live app (v1.4.19), CHANGELOG, `.env.example`, Dockerfile, docker-compose, docker-publish workflow +- [x] CRITICAL fixed inline: `19eb8de` (S3 env-var names + arm64 build claim removed) on healthlog-docs/main +- [x] HIGH fixed inline: `3d3ea21` (achievement count 38 → 59, `/admin/
` paths, AI rate-limit 2/h → 10/h, default-locale flip, comparison-overlay scope) on healthlog-docs/main +- [x] 9 MED + 5 LOW deferred to `.planning/v1421-backlog.md` "Docs site audit" section +- [x] Two flagged-but-uncertain items captured for maintainer review - Detailed report: `.planning/phase-F6-report.md` ## Wave B — Insights redesign with AI Coach (sequential) diff --git a/.planning/phase-F6-report.md b/.planning/phase-F6-report.md new file mode 100644 index 000000000..e00355bd7 --- /dev/null +++ b/.planning/phase-F6-report.md @@ -0,0 +1,86 @@ +# Phase F6 — docs.healthlog.dev accuracy audit + +Status: complete · 2026-05-10T15:42+02:00 + +Cross-referenced 38 `.mdx` pages under `healthlog-docs/src/content/docs/` +against the live app state (v1.4.19, image digest +`sha256:b48f93874cdb…`), CLAUDE.md, CHANGELOG.md, `.env.example`, +Dockerfile, docker-compose.yml, and `.github/workflows/docker-publish.yml`. + +## Findings + +| Severity | Count | Status | +|---|---|---| +| CRITICAL | 2 | fixed inline `19eb8de` | +| HIGH | 10 | fixed inline `3d3ea21` | +| MED | 9 | deferred to `v1421-backlog.md` | +| LOW | 5 | deferred to `v1421-backlog.md` | + +## Inline fixes + +### `19eb8de` — env-var + arch correctness + +- **S3 backup env-vars** in `configuration/environment-variables.mdx` + and `self-hosting/scaling.mdx`: `BACKUP_S3_ACCESS_KEY_ID` → + `BACKUP_S3_ACCESS_KEY` (matches `.env.example`), missing + `BACKUP_RETENTION_DAYS` and `BACKUP_ENCRYPTION_KEY` added. + Self-hosters following the docs would have got + `MissingRequiredParameter` errors on first backup run. +- **arm64 image claim** removed from `installation.mdx` and + `self-hosting/docker.mdx`. The workflow has been amd64-only since + v1.4.16 (qemu SIGILL on Next.js workers); v1.5 will re-add via + native arm64 runner. + +### `3d3ea21` — production-state alignment + +- Achievement count `38` → `59` plus a hidden-Easter-eggs note in + `getting-started/introduction.mdx` and `quick-start.mdx`. +- All `Settings → Administration` pointers rewritten to `/admin/
` + in `troubleshooting.mdx`, `monitoring.mdx`, `pwa-offline.mdx`, + `mood-tracking.mdx`, `security/self-hosting.mdx` (the legacy + Settings-shell admin tab was removed in v1.4.16 phase B6). +- `defaultLocale` default `de` → `en` in `admin-settings.mdx` + (matches the v1.4.16 English-default flip). +- AI Insights rate-limit `2/h` → `10/h` in `api/insights.mdx` and + `security/overview.mdx` (per v1.4.16 A7). +- AI Insights provider description replaced hard-coded `gpt-4o-mini` + with a generic "user's configured provider chain" phrasing + (provider-chain landed in v1.4.16 B5b). +- Mood enum locale note corrected. +- Comparison-overlay surface narrowed to `/insights` only per the + v1.4.19 A3 relocation in `dashboard/comparison.mdx`, + `features/dashboard-customization.mdx`, + `features/health-metrics.mdx`. + +`npm run build` green after each commit (46 pages, 0 warnings). + +## Deferred (in `v1421-backlog.md` "Docs site audit" section) + +9 MED items including: stale `1.2.0` docker-pull pin examples, +`architecture/database.mdx` model count drift (claims 22, schema has +26), background-jobs schedule timezone confusion (UTC vs +Europe/Berlin), missing `host-metric-sampler` and `feedback-aggregator` +job rows, "SHA-256 + HMAC" wording vs the actual keyed-HMAC-SHA-256 +storage, mood-API locale note carried over from v1.2 era. + +5 LOW polish items including the `/api/auth/me` example response +gravatarUrl freshness, security-overview rate-limit configurability +hints, Anthropic + Codex provider example responses on +`api/insights.mdx`, cross-link hygiene. + +## Flagged for maintainer + +- `api/insights.mdx`: documented as POST with session-cookie auth; the + live route also enforces a 24h DB cache that short-circuits the + rate limiter. F6 added a clarifying note but the `force=true` query + parameter is not yet documented — maintainer call. +- `architecture/database.mdx` lists `User.openaiKeyEncrypted`; + `settings/ai-providers.mdx` lists `User.aiOpenAiApiKey`. One of the + two is the editorial / one is the actual Prisma field — F6 left + both untouched pending verification. + +## Foundation status after F6 + +F0–F2 + F5 + F6 + FX all complete on `develop` (HealthLog), `main` +(healthlog-docs), `main` (healthlog-landing). Ready for B1 dispatch +(Insights redesign hero strip + Daily Briefing + Suggested-prompts). diff --git a/.planning/v1421-backlog.md b/.planning/v1421-backlog.md index e1ca66678..add4d4a10 100644 --- a/.planning/v1421-backlog.md +++ b/.planning/v1421-backlog.md @@ -42,3 +42,81 @@ The v1.4.19 quality-of-life audit deferred 31 MED + 16 LOW + 4 HIGH + 4 reconcile-HIGH items into `.planning/v1420-backlog.md`. v1.4.20 picks selectively (the redesign owns its own scope); the rest moves here on v1.4.21 kickoff. See that file for the full list. + +## Docs site audit (v1.4.19 cross-reference, deferred MED + LOW) + +Audit walked all 38 pages under `healthlog-docs/src/content/docs/**` +against the live app (v1.4.19, image digest `sha256:b48f93874cdb…`), +the CHANGELOG, `.env.example`, `Dockerfile`, `docker-compose.yml`, and +`.github/workflows/docker-publish.yml`. CRITICAL + HIGH already landed +on `healthlog-docs/main` (commits `19eb8de`, `3d3ea21`). Items below +are MED + LOW and were deliberately left for a hygiene pass. + +### MED — stale or imprecise but not load-bearing + +- **Stale version pins in installation / docker / admin examples.** + `getting-started/installation.mdx` and `self-hosting/docker.mdx` show + `:1.2.0` as the pin example; `api/admin.mdx` returns `"version": + "1.2.1"` in its sample response. Bump all three to a current `1.4.x` + reference on the next docs sweep. +- **`architecture/database.mdx` model count + measurement-type list.** + Page claims **22 models**; current schema has **26**. Measurement + table also stops at the v1.2 catalogue (WEIGHT / BP_SYS / BP_DIA / + PULSE / BODY_FAT / SLEEP_DURATION / ACTIVITY_STEPS) — needs the v1.3 + additions (BLOOD_GLUCOSE, OXYGEN_SATURATION, TOTAL_BODY_WATER, + BONE_MASS) so the API page and the architecture page agree. +- **`architecture/background-jobs.mdx` schedule timezone.** Lists + `Sunday 03:00 UTC` and `02:00–02:30 UTC` for the data-backup and + insights queues. Actual schedule is **Europe/Berlin** (CLAUDE.md + + `admin/backups.mdx` already document it correctly). Same drift in + `features/export-import.mdx` (`Schedule: Sunday 03:00 UTC` block on + line 96) — keep both in sync. +- **`architecture/background-jobs.mdx` job catalogue is incomplete.** + Missing `host-metric-sampler` (v1.4.16, host CPU/mem/IO every minute) + and `feedback-aggregator` (v1.4.16, daily 04:00 Europe/Berlin AI + feedback rollup). Add rows for both. +- **API token hashing wording.** `architecture/overview.mdx` and + `security/overview.mdx` describe the token store as "SHA-256 + HMAC" + / "stored as SHA-256 + HMAC hashes". The actual algorithm is **keyed + HMAC-SHA-256** (`API_TOKEN_HMAC_KEY` in `.env.example`, + `src/lib/auth/hmac.ts`). The other API/integrations/external-ingest + pages already use the correct phrasing — bring these two into line. +- **`api/insights.mdx` provider claim.** Now generic ("user's + configured provider chain") after the v1.4.19 docs fix; the per- + provider request/response examples could still be tightened to show + Anthropic / Codex shapes alongside the OpenAI one. Cosmetic. +- **`api/mood.mdx` "primary UI language is German" note.** Wording + carried over from the v1.2 era. Already corrected in + `features/mood-tracking.mdx`; mirror the same locale-neutral + phrasing in the API page. +- **Architecture overview i18n line** (`overview.mdx` line 105). Lists + "Supported languages: German and English" without flagging that + English is the codebase default. Tighten to match CLAUDE.md. +- **`features/export-import.mdx` Sunday-03:00-UTC block.** See above — + same Berlin/UTC drift; the surrounding paragraph already hints at + pg-boss without naming the timezone explicitly. + +### LOW — wording and polish + +- **`api/overview.mdx` example response includes `email` field.** The + `/api/auth/me` route returns `gravatarUrl` and the user shape; the + example could be refreshed to include the gravatar URL pattern that + the `/auth/me` handler now ships. +- **`getting-started/installation.mdx` "Pin a specific version".** + After the version-bump pass (see MED above), tighten the surrounding + paragraph to mention SLSA + SBOM verification commands once instead + of twice. +- **`security/overview.mdx` rate-limit table polish.** Now shows + `10 req/h (configurable …)` for AI insights — apply the same + configurability hint to the data-ingest row and the bug-report row + for consistency, if either is configurable. +- **`api/insights.mdx` provider example responses.** Add a short + Anthropic and Codex sample alongside the existing OpenAI shape so + client implementers know what to expect. Pure DX polish. +- **Cross-link hygiene.** A handful of pages still link to + `/settings/admin` or `/settings/administration` style anchors that + were rewritten — search the tree for any remaining instances after + the next set of edits. + +Total deferred from this audit: **9 MED + 5 LOW**. CRITICAL + HIGH +fixed inline at `healthlog-docs` commits `19eb8de` and `3d3ea21`.