trainlog/docs/reviews/documentation_deep_review_v1.md

# Documentation deep review V1 — 2026-10-02

## Scope and evidence hierarchy

This review covers the linear development source at
`f4ddcfdb05e9627397f7225c05f40212e9de1ea6`
(`trainlog-sleep-single-selector-weeks-v1`). Its ancestors include `3a4ec34`
(Program rollout), `8995843` (current Program projection), `c2935b8` (Web body
figures), and the Sleep sport/PDF/paging changes. It does not integrate or
describe as delivered the uncommitted Dashboard layout work in the separate
`trainlog-dashboard-polish-v1` worktree. Stable v0.1.6 and the 0.1.7
development line are different publication states.

Normative frozen contracts take priority over source implementation; source and
tests establish capabilities of this commit; dated rollout records establish
only the installation they observed; design/review files retain history. The
observed PC/Web launcher path names the `f4ddcfd` package. That observation
alone is not a byte comparison of a running process, an Android APK inspection,
or proof of every synchronization service's package. The earlier verified
Program rollout records desktop/Android schemas v37/v34. No private health
data, PDF, database or device identifier was read for this review.

## Coverage inventory

The 105 tracked baseline Markdown files include root `README.md`, `AGENTS.md`,
`CHANGELOG.md`, `android/README.md`, `format/README.md`, 17 primary `docs/*.md`
owners, domain and design records, release notes and historical reviews. This
revision adds an indexed Sleep guide and this review. The primary owners were
inspected against code, migration constants, Meson/Gradle settings, tests and
retained rollout records. Designs, releases and reviews were mapped as dated
evidence rather than rewritten into current status. The tracked Markdown
relative-link scan found no missing target before publication. External link
availability was not verified.

| Document/section | Claim | Evidence (commit, path, symbol or test) | Gap | Correction | Status |
| --- | --- | --- | --- | --- | --- |
| `AGENTS.md` scope | Analyse, Programmes, Sessions and Exercises are placeholders | `web/src/routes/`; `docs/web_sessions.md`; `docs/web_exercises.md` at `f4ddcfd` | Obsolete present tense | Names implemented routes | Corrected |
| `AGENTS.md`, database and Android status | Current schemas v26/v24, v28/v17 or v36/v33 | `tui/include/trainlog/database.h` `TRAINLOG_DATABASE_SCHEMA_VERSION=37`; `TrainlogRepository.kt` helper `version=34`; migration tests | Mixed historical and current versions | Current source v37/v34; historical migration steps retained | Corrected |
| `current_state.md`, roadmap | `c2935b8`/`3758875` Web package served | Observed launcher target names `sleep-single-selector-weeks-v1-f4ddcfd`; ancestor graph | Package claim stale; running bytes unverified | Reports launcher observation and separate Program rollout | Corrected with limit |
| Sleep agenda | Old selector or calendar-week interpretation | `SleepDiaryWorkspace.tsx` `initialAgendaPageSize`, `recentEntries`, `visibleEntries`; Sleep component tests | Seven recorded rows can span more than seven dates | Current 7/14/21/28/All row counts, default seven; old values migration only | Corrected |
| Sleep PDF and sport | Page controls could be confused with export range | `SleepDiaryWorkspace.tsx` `pdfStartDate`/`pdfEndDate`; `sleepVisualProjection`; Web PDF tests | Selection and visible page have different scopes | Documents independent inclusive range and factual sport bands | Verified in source |
| Programs | Rescheduling labelled future/candidate | `docs/program_format_v1.md`; `docs/sync_exchange.md`; `tui/tests/test_web_programs.c`; Android v34 projection | Development capability mislabelled future | Describes implemented development contract and partial V1-peer convergence | Corrected |
| Web package | `npm test` could be mistaken for embedded runtime proof | `meson_options.txt` `web`; `tui/meson.build` frontend target/tests; `tools/package_sync_candidate.py` asset gate | Source tests and package differ | README requires `-Dweb=enabled`, Meson tests, compatible bundle | Corrected |
| Synchronization | One ACK might imply universal convergence | `docs/sync_exchange.md` Programs V2 matrix; generation and ACK implementation | V1-only peer omits rescheduled Program while other domains proceed | Added domain/format/selection/ACK matrix | Corrected |
| Transport narrative | Current Web edits and architecture described USB as universal priority | `docs/sync_exchange.md` Bluetooth selector; `tools/sync_peer_worker.py`; private rollout record | Conflated paired Bluetooth path with separate USB/Drive workflow | Separated automatic paired choice from legacy configured workflow | Corrected |
| Rollout readiness | Historical eight-generation limit could look universal/current | `tools/sync_generation_exchange.py` `MAX_RETAINED_PER_PEER=16`; Android `SyncGenerationService.MAX_RETAINED_PER_PEER=8`; `tools/sync_peer_worker.py` MTP timeout | Desktop/Android ceilings differ; timeout is not success proof | Separated limits and historical bridge instructions | Corrected |
| Sleep user path | Capture, agenda and PDF behavior had no short indexed guide | `TrainlogRepository.kt`; `SleepDiaryWorkspace.tsx`; Sleep projection/PDF tests | Readers had to assemble workflow from state and code | Added indexed factual guide with privacy and evidence boundaries | Corrected |
| Backup/rollback | Old executable could be mistaken for schema rollback | `tools/backup_trainlog_sqlite.py` SQLite backup API; `docs/sync_rollout_readiness.md` | Needs paired compatibility and retained backups | Existing procedure retained and linked from README | Verified in documentation |
| Tests | Largest historical totals could look like current validation | `docs/tests.md` dated checkpoints; `tui/meson.build`; Web scripts | Build configuration and skipped tests were implicit | Added evidence-reading rule | Corrected |
| 0.1.8 | Possible training ideas could look implemented | `docs/roadmap.md`; present catalog/feedback/Sleep/Cardio owners | No approved algorithm or medical rule | Proposed-only section with human validation | Corrected |

## Validation performed in the isolated documentation worktree

`python3 tools/validate_json.py` and
`python3 tools/validate_import_contract.py` passed. With a local
`-Dweb=enabled` Meson build, strict compilation and **114/114** registered
tests passed, including the embedded frontend and package self-containment
checks. A preliminary `-Dweb=disabled` run passed 111/112; its deployment
package test rejected the intentionally absent Web assets as designed. The
changed C/H format gate passed with no changed C/H file. Relative links across
the tracked baseline plus new Markdown files and `git diff --check` passed.
These checks used build artifacts in this worktree and synthetic test data;
they did not exercise a personal device, database or service.

## Boundaries and open evidence

The source can prove format selection, persistence rules and test coverage; it
cannot prove that a particular uninspected phone or service is currently
running that source. The `f4ddcfd` launcher observation identifies a package
path, not a live process hash. The private rollout and Firefox/PDF records are
dated evidence for their stated configurations. Android path reconstruction for
the Web silhouette is source parity evidence, not an Android runtime
screenshot. The local desktop 16-generation and Android eight-generation
admission limits, and the 90-second MTP operation budget, are bounded
configuration, not a guarantee against interruption or proof that transient
storage occupation is always lower than either ceiling.

No code defect was confirmed by this documentation pass. A broad line-by-line
revalidation of every historical review and every external URL is outside the
verified coverage; their current status must not be inferred from this matrix.
No application, database, service, synchronization or personal-data operation
belongs to this documentation branch.