# Domain Documentation

MotorSignal uses a single-context documentation layout. There is no repository `CONTEXT.md`, `CONTEXT-MAP.md`, or ADR directory yet; proceed without inventing them unless domain-modeling work requires one.

## Authority Order

1. `AGENTS.md` and explicit task instructions.
2. Current production code, schema declarations, and tests.
3. Current architecture and specification documents relevant to the subsystem.
4. Planning documents, audit reports, changelogs, and development history as historical evidence only.

When documents conflict, verify behavior in code and tests. Do not revive obsolete values such as Drift Schema 5 or a 5 Hz authoritative telemetry rate; the current contracts are Schema 7 and 20 Hz / 50 ms acquisition.

## Documentation Map

- Telemetry and field validation: `docs/architecture/telemetry-architecture.md`, `docs/architecture/telemetry-validation.md`, and `docs/guides/field-testing.md`.
- Cloud and sync: `docs/architecture/cloud-data-model.md`, `docs/architecture/cloud-architecture.md`, and `cloudflare/motorsignal-r2-worker/README.md`.
- Product and entitlement intent: `docs/product/free-pro-spec.md` and `docs/product/roadmap.md`. These are planning baselines, not proof that features exist.
- Interface language and visual tokens: `docs/design/design-system.md`. Validate behavioral and timing claims against current code.
- Releases and versions: `docs/RELEASING.md` and `docs/VERSIONING.md`. Preserve Semantic Versioning and monotonically increasing build numbers; use current `AGENTS.md` verification gates and current schema values where old examples conflict.
- Waze relay operation: `server/waze_relay/README.md`.
- `CHANGELOG.md` is the canonical release record. `docs/archive/` contains dated feature histories, environment audits, phase reports, discovery documents, and gap audits. Never treat their old test counts, release status, schema numbers, or pending physical-validation claims as current proof.

## Stable Vocabulary

Use established terms consistently: `TelemetryService`, `SensorFusionService`, `RideStateMachine`, `AppDatabase`, `SyncManager`, `SyncOutbox`, `FirebaseSyncProvider`, `FieldTestExportService`, `cloudRideId`, telemetry bundle, local source of truth, and offline-first sync.

Flag any proposed change that conflicts with these domain contracts or would require a new architectural decision record.