docs: document sleep diary v1

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased — 0.1.4
 
+- Added Sleep Diary V1 across desktop schema v29, Android schema v26, Analyse,
+  full-generation synchronization and a deterministic local vector PDF agenda.
+  Entries retain causal revisions, absolute timestamped events, the five-value
+  appreciation scale and user-authored notes; no medical interpretation or
+  heart-rate data is introduced.
+
 Development opened after stable v0.1.3 release.
 
 - Implemented the loopback-only Web Analyse V1 workspace and shared bounded

README.md

@@ -24,7 +24,7 @@ over direct MTP; it never copies SQLite database files between devices.
 |---|---|
 | Android | Capture and quickly correct sets, repetitions, loads, durations, and continuous activities; reorder active and completed-session occurrences; capture feedback, J+1 follow-ups, body measurements, and AI proposals; trigger sync; show quick summaries. |
 | Desktop TUI | Administer, inspect, maintain, import/export, correct canonical history, and provide technical tools. |
-| Local Web (0.1.4 development) | Display the Dashboard, the operational Programmes calendar, Sessions administration, and the desktop exercise catalogue through typed Trainlog Core/API boundaries. Exercises supports search/filter, detail, creation, editing and causal retirement; equipment is read-only. Analyse is the current implementation cursor. |
+| Local Web (0.1.4 development) | Display Dashboard, Programmes, Sessions, Exercises and factual Analyse workspaces. Analyse includes the Sleep Diary editor, 18:00-to-18:00 agenda and local vector PDF export. |
 
 No interface reconstructs business truth from SQLite tables. The local Web is
 a sibling adapter, not an extension of the TUI. On `main`, its loopback-only
@@ -335,7 +335,7 @@ not contain cloud credentials and does not run `rclone`.
 As of 2026-09-18:
 
 - `TRAINLOG_FORMAT_V1=PASS/FROZEN`;
-- desktop SQLite schema v28 and Android SQLite schema v25;
+- desktop SQLite schema v29 and Android SQLite schema v26;
 - Notcurses is the only active desktop terminal backend;
 - direct storage is `/storage/emulated/0/Documents/Trainlog` under Android's
   all-files access setting;

docs/android.md

@@ -1,5 +1,13 @@
 # Android application
 
+## Sleep Diary V1
+
+Android schema v26 additively mirrors the Sleep Diary revision/event model for
+local-first field capture. Its compact Morning and Day sections edit one
+durable night/day entry without reproducing the desktop/PDF grid. Creation,
+correction and logical deletion are revision guarded and survive repository
+reopen. Full-generation exchange transports the companion, never SQLite.
+
 ## Background USB and private Drive synchronization
 
 SyncScreen and the explicitly enabled background service invoke one

docs/current_state.md

@@ -107,8 +107,8 @@ parallel implementation of its rules.
 | Boundary | Current state |
 |---|---|
 | Frozen project exchange | `TRAINLOG_FORMAT_V1=PASS/FROZEN` |
-| Desktop SQLite | schema v28 |
+| Desktop SQLite | schema v29; Sleep Diary V1 is additive in v29 |
-| Android SQLite | schema v25 |
+| Android SQLite | schema v26; Sleep Diary V1 is additive in v26 |
 | Mobile snapshot | V3 active; V1/V2 readable legacy inputs; explicit V4 codec staged, not selected by transport |
 | Desktop terminal backend | Notcurses only |
 | Trainlog product version | `0.1.4` development, synchronized across Android and desktop; latest stable release: `v0.1.3` |
@@ -129,6 +129,7 @@ parallel implementation of its rules.
 | Web Dashboard tiles | `WEB_DASHBOARD_TILES_V1=PASS/FROZEN` |
 | Web Dashboard visualizations | `WEB_DASHBOARD_VISUALIZATIONS_V1=PASS/FROZEN` |
 | Web Dashboard V1 | `WEB_DASHBOARD_V1=PASS/FROZEN` |
+| Sleep Diary V1 | Implemented on the 0.1.4 review branch: timestamped causal diary, Web/Android capture, full-generation companion and local vector PDF |
 | Web Sessions V1 | `TRAINLOG_WEB_SESSIONS_V1=PASS/FROZEN` (controlled desktop/Android deployment validated) |
 | Web Sessions deletion and Programs V1 | `TRAINLOG_WEB_SESSIONS_DELETE_AND_PROGRAMS_V1=PASS` (private grouped rollout validated) |
 | Programs presentation, Android projection, and deletion | `TRAINLOG_PROGRAMS_PRESENTATION_ANDROID_DELETE_V1=PASS` (private coordinated deployment and restart/replay validated) |

docs/database.md

@@ -1,5 +1,21 @@
 # Desktop database
 
+## Schema v29: Sleep Diary V1
+
+Schema v29 additively owns `sleep_diary_entries`, immutable
+`sleep_diary_revisions`, and revision-owned `sleep_diary_events`. An entry is
+one night and its associated day. Point events have an offset-bearing
+`start_at`; intervals additionally have an absolute `end_at` strictly after
+their start. The 18:00-to-18:00 agenda is only a projection and is never stored
+as cells.
+
+Mutations advance `current_revision_id` only when the caller supplies the
+current parent. Logical deletion advances the revision and retains the
+tombstone. Qualities preserve `TB`, `B`, `Moy`, `M`, and `TM` exactly.
+
+The absolute timestamps are the future heart-rate correlation boundary. Sleep
+Diary V1 does not store, infer, or simulate heart-rate data.
+
 ## Schema v28: terminal Program execution provenance
 
 Schema v28 extends `program_session_executions.state` with the terminal

docs/roadmap.md

@@ -29,7 +29,7 @@ distinction between measured values and estimates.
 ## Current baseline
 
 Stable v0.1.2 is the release baseline for the v0.1.3 development cycle.
-Desktop schema v28, Android schema v25, Notcurses, direct `Documents/Trainlog`
+Desktop schema v29, Android schema v26, Notcurses, direct `Documents/Trainlog`
 storage, mobile export V3, Training Knowledge V1, Body Zones V1, Training
 Feedback V1/V2, STATS V1, and Session Generator V1 are implemented. Session
 Generator V1 is hidden pending V2. AI session-draft exchange retains its
@@ -58,6 +58,10 @@ The v0.1.4 cursor proceeds from stable v0.1.3 and its validated Web, Program
 execution, USB/Drive generation, ACK, and causal-deletion contracts without
 reopening those completed gates.
 
+Sleep Diary V1 is implemented on `trainlog-0.1.4-sleep-diary-v1` and remains
+under grouped review before integration. Heart-rate sensor ingestion remains
+future scope; absolute diary timestamps are its prepared extension boundary.
+
 ```text
 CURRENT_OPERATIONAL_CURSOR=TRAINLOG_WEB_ANALYSIS_V1
 ```

docs/sync_exchange.md

@@ -1,5 +1,18 @@
 # Synchronization exchange
 
+## Sleep Diary companion
+
+`trainlog-sleep-diary`, version 1, is emitted by full generations on the 0.1.4
+Sleep Diary branch. It is optional when consuming an older generation so a
+pre-domain artifact remains replayable. It carries bounded complete entry snapshots with
+stable identities, the current immutable revision and causal parent,
+offset-bearing timestamps, appreciations, notes and logical deletion. Exact
+revision replay is unchanged; sibling revisions and resurrection after deletion
+are rejected in the generation consumption transaction.
+
+This does not change `TRAINLOG_FORMAT_V1`, manifests, ACKs, MTP or Drive
+transport ownership.
+
 ## USB-priority and private Drive transport
 
 Full-generation synchronization has one business engine and two byte

docs/tests.md

@@ -1,5 +1,10 @@
 # Tests and validation
 
+Sleep Diary coverage includes schema creation/migration, midnight and DST
+offsets, revision conflict, logical deletion/reopen, companion replay and
+rollback, Web periods/deep links, Android persistence, and vector PDF
+construction/pagination for 7, 14, 21 and 30 synthetic days.
+
 `web_analysis` covers empty history, every 7/30/90/all period selector,
 loaded and unloaded repetitions, continuous duration/distance/speed, explicit
 persisted MAX, multiple primary BODY ZONES, partial measurements, one- and