trainlog/docs/README.md

Trainlog documentation

This file is the canonical documentation index. Canonical documents describe the current contract or state; reviews/ and CHANGELOG.md retain historical evidence and chronology.

Start here

• Current state owns present schemas, capabilities, validation, and active limitations.
• Architecture owns component, process, storage, transport, and responsibility boundaries.
• Roadmap owns the current cursor and future work.

Interfaces

• Android owns field-companion capture, local persistence, glanceable summaries, permissions, and Android interaction rules.
• Desktop TUI owns Notcurses navigation, correction, detailed consultation, analytics, graphs, and long-term follow-up behavior.

Data model

• Exercise data model owns exercise profiles, occurrence identity, planned-versus-actual work, load, and MAX semantics.
• Database owns desktop SQLite tables, constraints, transactions, and migrations.
• Training feedback owns immediate feedback, immutable revisions, and J+1/session follow-up semantics.
• Domain documentation owns cited anatomy, biomechanics, equipment interpretation, training knowledge, and session-generation science.

Synchronization and exchange

• Synchronization exchange owns the active MTP workflow, artifact direction, replay, publication, receipts, and daemon behavior.
• Exchange formats owns frozen Trainlog JSON V1 and separately versioned contracts, including AI exchange definitions.

Analytics

• Desktop TUI owns visible statistics, MAX, body analytics, calendar buckets, and graph behavior.
• Current state records which analytics are implemented.
• Exercise data model owns the distinctions between measured MAX, performed work, plans, and estimates.

Development

• Tests and validation owns durable build, test, sanitizer, contract, and hardware-validation commands.
• Coding style owns C17/Kotlin style and comment rules.
• Development contract owns frozen boundaries, invariants, validation policy, and safe device-testing policy.
• Android build notes are the Android setup entry point.
• Format material indexes frozen schema assets.

Design

• Design records retain proposals and design-gate evidence. They are not the authority for current implementation status.

Reviews and history

• Review records retain historical audits, incidents, checkpoints, and validation evidence. Their status and paths are historical.
• Changelog owns chronological change history.

Ownership rule

Do not copy long normative explanations between documents. The repository README.md is the entry point, this file is the index, current_state.md is the snapshot, and roadmap.md is future-oriented.