docs: scaffold polisher-control foundation

docs/04-host-teensy-protocol-v1.md

@@ -0,0 +1,60 @@
+# Host ↔ Teensy Protocol v1 — Working Spec
+
+Status: draft scaffold. Cédric should finalize the exact wire format before implementation locks.
+
+## Philosophy
+
+This is a setpoint/telemetry protocol, not G-code.
+
+Requirements:
+- versioned frames;
+- length-delimited or COBS-delimited framing;
+- CRC-16 or CRC-32 on every frame;
+- deterministic parsing;
+- ACK/NACK for every command;
+- machine-readable NACK reason codes;
+- no text parsing in the control path.
+
+## Host → Teensy messages
+
+- `HEARTBEAT`
+- `MANUAL_START`
+- `SETPOINT`
+- `MANUAL_STOP`
+- `SEGMENT_START`
+- `PAUSE`
+- `RESUME`
+- `ABORT`
+- `ESTOP`
+
+## Teensy → Host messages
+
+- `ACK`
+- `NACK`
+- `TELEMETRY`
+- `EVENT`
+- `SEGMENT_DONE`
+- `ABORT_COMPLETE`
+
+## v1 production subset
+
+Manual v1 only needs:
+- `HEARTBEAT`
+- `MANUAL_START`
+- `SETPOINT`
+- `MANUAL_STOP`
+- `ACK` / `NACK`
+- `TELEMETRY`
+- `EVENT`
+
+But define and parse the future segment messages now so Phase 3 does not require a protocol reset.
+
+## Open protocol choices
+
+- JSON-lines, MessagePack, or compact binary structs?
+- CRC-16 vs CRC-32?
+- COBS framing vs length-prefix + CRC?
+- Serial baud rate and reconnect behavior?
+- Whether heartbeat is host-only or bidirectional?
+
+Recommendation: choose the simplest robust format Cédric is comfortable debugging on the bench.