docs(style): enforce readable source formatting

.clang-format

@@ -0,0 +1,19 @@
+---
+BasedOnStyle: LLVM
+Language: Cpp
+Standard: c++17
+ColumnLimit: 100
+IndentWidth: 4
+InsertBraces: true
+ContinuationIndentWidth: 4
+UseTab: Never
+BreakBeforeBraces: Attach
+AllowShortBlocksOnASingleLine: Never
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortEnumsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: None
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+BinPackArguments: false
+BinPackParameters: false
+SortIncludes: Never

AGENTS.md

@@ -287,6 +287,12 @@ Exact UI strings, user data, identifiers, commands, paths, protocol fields,
 version/status markers, citations, and historical evidence are not translated
 merely to satisfy the prose-language rule.
 
+Production code, tests, fixtures expressed as source, and repository tooling
+must remain readable by a human reviewer. Do not compress functions, control
+flow, declarations, assertions, or cleanup onto one line to reduce line or
+token count. Grouped missions may and should use small comprehensible commits.
+Perform an explicit readability review before the final commit.
+
 Canonical documents:
 
 - `README.md`;

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased — 0.1.2
 
+- Normalized the recent synchronization, generation-MTP, Android backup,
+  Web Dashboard serialization, tests, I/O doubles and packaging code for human
+  readability. Added scoped C formatting rules and review guidance without
+  changing synchronization protocols, assertions, deployment state or runtime
+  behavior.
+
 - Added the production libudev/libmtp generation adapter with bounded peer
   selection, object transfer and manifest-last publication; wired the trusted
   orchestrator mode and proved the full Firefox/Android/desktop conversation

docs/coding_style.md

@@ -6,6 +6,11 @@ Code must optimize for readability, correctness, and maintainability.
 
 Avoid clever code when a straightforward implementation is easier to verify.
 
+These rules apply equally to production code, tests, I/O doubles, migration
+bridges, and repository tooling. Code must not be manually compacted to save
+lines or prompt tokens. A grouped mission remains compatible with small,
+reviewable commits.
+
 ## 2. C standard
 
 The TUI uses C17.
@@ -91,11 +96,33 @@ Good:
 
 ## 6. Formatting
 
-The repository currently has no canonical `.clang-format` file. Do not apply a
-bulk formatter with tool-default behavior; introducing a format definition and
-any broad normalization requires a dedicated, reviewable change.
+The repository `.clang-format` defines the C presentation used by normalized
+files. It targets 100 columns, four-space indentation, one statement per line,
+explicit control-flow braces, vertical long parameter lists, and no short
+function or control body on one line. Contract literals may exceed the target
+when splitting them would make the protocol less reviewable.
 
-Formatting changes should not be mixed with unrelated semantic changes when avoidable.
+Do not apply the formatter blindly to the entire historical tree. A change
+normalizes the files it owns and checks that explicit scope. The reproducible,
+non-mutating check for the currently normalized C readability scope is:
+
+```bash
+clang-format --dry-run --Werror \
+  tui/src/dashboard_layout.c \
+  tui/src/generation_mtp.c \
+  tui/src/json_writer.c \
+  tui/src/web_dashboard.c \
+  tui/src/web_dashboard_json.c \
+  tui/include/trainlog/generation_mtp.h \
+  tui/tools/generation_mtp_adapter.c \
+  tui/tests/generation_mtp_adapter_double.c \
+  tui/tests/test_generation_mtp.c \
+  tui/tests/test_web_server.c
+```
+
+Formatting changes should not be mixed with unrelated semantic changes when
+avoidable. Review readability explicitly before the final commit, including
+tests and cleanup/error paths.
 
 ## 7. Error handling
 
@@ -130,3 +157,7 @@ The Android side should favor:
 - small view models;
 - no unnecessary framework abstraction;
 - clear serialization types matching the Trainlog JSON contract.
+
+Python and Kotlin follow the same human-readability requirement: avoid
+single-line compound statements, compressed exception handling, and opaque
+chains of unrelated mutations. Formatters are aids, not substitutes for review.

docs/current_state.md

@@ -10,6 +10,12 @@ and deployment are not complete.
 
 Snapshot date: **2026-09-17**.
 
+`TRAINLOG_CODE_READABILITY_V1` normalizes the recent generation-MTP,
+generation/ACK, Android-backup, Web Dashboard serialization, tests, doubles and
+packaging workflows without changing their contracts. The scoped C formatter
+check is canonical for those files only; it does not claim that the historical
+repository has been globally reformatted.
+
 This document owns the current implemented state. Historical checkpoints and
 closed incidents belong in [reviews](reviews/) and the
 [changelog](../CHANGELOG.md).

docs/tests.md

@@ -1307,3 +1307,19 @@ the analogous test on the exact schema-v17 source and feeds its archive to
 These are software proofs. They do not claim physical USB/MTP behavior,
 installation over the signed release, a real user backup, or a real-device
 restore.
+
+## Readability validation
+
+The normalized C scope is checked non-mutatively with the explicit
+`clang-format --dry-run --Werror` command in `docs/coding_style.md`. Clang C17,
+the normal Meson inventory and the ASan/UBSan inventory preserve the existing
+behavioral assertions. Python syntax/orchestrator tests, Android generation and
+backup tests, the I/O-boundary MTP browser proof, JSON/import validators and
+the isolated harness cover the other normalized sources.
+
+GCC 16.2.1 now compiles beyond the former `misleading-indentation` failures in
+`json_writer.c`, `web_dashboard_json.c`, `web_dashboard.c`,
+`dashboard_layout.c`, and `generation_mtp.c`. The separate strict build remains
+blocked by distinct pre-existing `format-truncation` diagnostics in the Web
+accepted-response buffer and bounded test path buffers. Warning policy remains
+unchanged; GCC is not reported as green.