[39/39] refactor: remove obsolete interfaces and document architecture

README.md

@@ -43,15 +43,19 @@ The UI modules use unidirectional MVI:
 
 `Composable → Intent → ViewModel → use case → repository/service → State + Effect`
 
-UI launchers execute one-shot effects, while decisions and state transitions remain in ViewModels, reducers, and focused use cases. Hilt provides production dependencies and interfaces keep platform boundaries replaceable in tests.
+UI launchers execute one-shot effects, while decisions and state transitions remain in workflow-owned ViewModels, reducers, and focused use cases. The phone shell owns navigation only. Hilt provides production dependencies and interfaces keep platform boundaries replaceable in tests.
 
 Modules:
 
-- `app`: phone Compose UI, MVI, permissions, native document storage, and received watch files.
+- `app`: phone Compose UI, workflow-owned MVI, paired-recording policy, permissions, and received watch files.
 - `wear`: Wear Compose Material 3 UI, MVI, live charts, recording, and phone launch flow.
-- `core`: DataStore preferences, storage contracts, reducers, and reusable test fixtures.
-- `sensorservices`: foreground measurement service and linear sensor/GPS writers.
-- `WearOsLib`: coroutine-based connectivity, versioned command protocol, and Channel file transport.
+- `core-common`: platform-neutral `AppResult`, stable application errors, and diagnostics contracts.
+- `recording-core`: pure Kotlin recording state machine, source roles, scheduling, and cleanup policy.
+- `core`: Android DataStore preferences, document storage, local rotating diagnostics, and reusable test fixtures.
+- `sensorservices`: Android recording adapters, foreground host, and linear sensor/GPS writers. It has no Wear dependency.
+- `WearOsLib`: coroutine-based connectivity, strict protocol v2 command encoding, and Channel file transport. App policy stays in `app` and `wear`.
+
+Paired phone/watch recording is all-or-nothing: both sides prepare before either commits, commands are session-correlated and idempotent, timeouts use bounded retries, and rejection or timeout compensates both sides.
 
 ## Platform and toolchain
 

docs/adr/0001-use-explicit-application-outcomes.md

@@ -0,0 +1,5 @@
+# Use explicit application outcomes
+
+Expected failures crossing repository, storage, protocol, recording, use-case, or presentation interfaces use a shared `AppResult<T>` and data-only `AppError`. Kotlin `Result<T>` and custom exceptions do not cross those interfaces because callers need stable error codes, exhaustive handling, and diagnostics without constructor side effects.
+
+Infrastructure adapters translate expected exceptions and preserve safe causes. Application entry points record terminal failures through an injected local diagnostic logger. User-facing messages remain presentation decisions.

docs/adr/0002-separate-recording-engine-from-android-adapters.md

@@ -0,0 +1,5 @@
+# Separate the recording engine from Android adapters
+
+Recording state, scheduling policy, source coordination, cleanup, and terminal events live in a pure Kotlin `recording-core` module. Android sensor capture, foreground hosting, notifications, wake locks, battery callbacks, GPS, and storage streams remain adapters in `sensorservices`.
+
+This split keeps the recording state machine testable without Android and prevents Wear transport policy from entering the local recording module.

docs/adr/0003-coordinate-paired-recordings-with-protocol-v2.md

@@ -0,0 +1,5 @@
+# Coordinate paired recordings with protocol version 2
+
+Paired phone and watch recording uses a breaking, session-identified prepare, commit, abort, and stop protocol. Both sides must prepare before either side commits. Commands are idempotent, bounded by timeouts, and retried with the same session ID.
+
+The phone owns the paired workflow. `WearOsLib` owns typed protocol encoding and transport, while phone and watch applications own command behavior. Unsupported protocol versions fail explicitly.

docs/adr/0004-own-presentation-state-by-user-workflow.md

@@ -0,0 +1,5 @@
+# Own presentation state by user workflow
+
+Phone presentation state is owned by onboarding, recording, and settings workflows rather than one application-wide MVI contract. The recording workflow spans selection, details, preview, setup, permissions, active recording, and annotations because those routes edit or observe one recording plan.
+
+The application shell owns navigation and a small read-only view of recording session facts. Routes remain stateless and receive focused state and actions from their owning feature.