Add Codex handoff doc

docs/codex-handoff.md

@@ -0,0 +1,169 @@
+# Xterra Overland Dashboard - Codex Handoff
+
+## Repository
+
+This repository is the source of truth.
+
+Before making any code changes:
+
+1. Read:
+   - docs/project-state.md
+   - docs/hardware-status.md
+   - docs/protocol.md
+   - docs/pico-architecture.md
+   - docs/ui-wireframes.md
+   - docs/implementation-roadmap.md
+
+2. Inspect the existing codebase.
+
+3. Do not assume documentation is correct.
+   Verify implementation against documentation.
+
+4. Prefer incremental commits.
+
+5. Run tests before proposing changes.
+
+---
+
+# Project Overview
+
+The project is an overland vehicle monitoring and control system for a Nissan Xterra.
+
+Architecture:
+
+## Dashboard
+
+- Raspberry Pi Pico 2 W
+- 3.5" 320x480 ST7796S display
+- FT6336U capacitive touch
+- Active buzzer
+
+Responsibilities:
+
+- Live monitoring
+- Relay control
+- Alarms
+- Touchscreen UI
+
+## Cargo Controller
+
+- ESP32 relay board
+- GPIO16 = Starlink relay trigger
+- GPIO17 = Fridge relay trigger
+
+Important:
+
+The ESP32 relay outputs do NOT carry load current.
+
+They only trigger Bosch automotive relays.
+
+High-current loads never pass through ESP32 relay contacts.
+
+---
+
+# Communications
+
+Primary:
+
+- UART over CAT5
+- 115200 baud
+- Newline-delimited JSON
+
+Backup:
+
+- WiFi HTTP API
+
+Fallback only:
+
+- RS-485 (not currently planned)
+
+Protocol specification:
+
+docs/protocol.md
+
+---
+
+# Temperature Sensors
+
+DS18B20 sensors:
+
+- Fridge Zone 1
+- Fridge Zone 2
+- Rear Seat Area
+- Outside Air
+
+Missing sensors should report:
+
+- temperature = null
+- sensor_health = false
+
+---
+
+# Current Status
+
+Completed:
+
+- ESP32 firmware compiles
+- UART protocol defined
+- Pico architecture defined
+- Pico state management implemented
+- Alarm system implemented
+- Communication service implemented
+- HTTP fallback implemented
+- Touch routing abstraction implemented
+- Display abstraction implemented
+- Unit tests implemented
+
+In Progress:
+
+- ESP32 hardware bring-up
+
+Not Started:
+
+- Pico display integration
+- Pico touch integration
+- Pico UART integration
+- Real hardware drivers
+
+---
+
+# Development Rules
+
+1. Prefer small commits.
+
+2. Preserve existing architecture.
+
+3. Keep business logic hardware-independent.
+
+4. Hardware-specific code belongs in:
+
+hardware/
+
+5. Communication-specific code belongs in:
+
+comms/
+
+6. UI state transformation belongs in:
+
+view models
+
+7. Add tests whenever possible.
+
+---
+
+# Immediate Goal
+
+Current milestone:
+
+ESP32 hardware bring-up.
+
+Success criteria:
+
+- Firmware uploads
+- WiFi AP starts
+- HTTP API responds
+- Relay outputs work
+- DS18B20 framework works
+- UART initializes
+
+Do not begin large UI rewrites until ESP32 hardware validation is complete.