MotorSignal-App/docs/agents/domain.md

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: TELEMETRY_ARCHITECTURE.md, TELEMETRY_VALIDATION.md, and FIELD_TESTING.md.
• Cloud and sync: MOTORSIGNAL_FINAL_CLOUD_DATA_MODEL.md, MOTORSIGNAL_CLOUD_ARCHITECTURE.md, and cloudflare/motorsignal-r2-worker/README.md.
• Product and entitlement intent: MOTORSIGNAL_FREE_PRO_SPEC.md and MOTORSIGNAL_PRODUCT_ROADMAP.md. These are planning baselines, not proof that features exist.
• Interface language and visual tokens: DESIGN.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, FEATURES_CHANGELOG.md, DEVELOPMENT_HISTORY.md, MOTORSIGNAL_AI_ENVIRONMENT_AUDIT.md, phase reports, discovery documents, and gap audits are dated evidence. 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.