Scaffold repo: docs layout, guidelines and initial plan

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013kj58Jugkic783b8ZrtTVZ

docs/GUIDELINES.md

@@ -0,0 +1,26 @@
+---
+type: default
+---
+# Mock and fixture guidelines
+
+## 1. Fixtures publish the real contract
+- A fixture emits the **real topic with the real payload schema**. `yukart/gnss/fix`
+  from a replayed track must be indistinguishable, at the bus, from a real fix.  
+- A fixture that invents its own topic or shape is worse than no fixture: it defers
+  the integration work instead of removing it.
+
+## 2. Never stub our own services
+- Stub the **car** and the **hardware**. Never stub `svc-gw`, `svc-nav` or anything
+  else we wrote.  
+- A stub of our own service is a second implementation of our own contract, and it
+  will drift from the first. Run the real service against fake inputs instead —
+  none of our services touch hardware, so they all run on x86 unmodified.
+
+## 3. Prefer upstream tools, wrap rather than rewrite
+- `vcan`, `canplayer` and ICSim already solve the CAN problem. This repo holds the
+  scripts that drive them, not reimplementations of them.
+
+## 4. Recorded logs are data, not source
+- `candump` logs and GPX tracks are artifacts. Reference them, do not commit them.
+
+## 5. To be added

docs/impl/plans/INITIAL.md

@@ -0,0 +1,37 @@
+---
+type: default
+---
+# Initial plan
+
+## What actually needs building
+
+| Need | Answer | Ours? |
+|---|---|---|
+| A CAN bus that isn't a car | `vcan` — kernel module, no bitrate to configure | No |
+| Replay real captures | `canplayer`, with frame mapping so a log recorded on `can1` plays onto `vcan0` | No |
+| Traffic before any capture exists | **ICSim** — simulated cluster with speed, doors, indicators | No |
+| GNSS fix | GPX or synthetic track → `yukart/gnss/fix` | **Yes**, small |
+| Local broker | a mosquitto config for the workstation | Trivial |
+| App boundary peer | only if the full stack proves too heavy for Flutter iteration | **Deferred** |
+
+Two of the three fixtures are configuration, not code.
+
+## Why ICSim matters more than it looks
+
+Phase 2 is the hard part of this project: correlating observed frames against a
+written event log to work out what the Z27AG is saying. ICSim is built for exactly
+that exercise — a simulated cluster with controllable speed, doors and indicators,
+and four noise levels where level 0 is clean packets and level 3 randomises
+arbitration IDs and byte positions.
+
+So the whole decode workflow can be practised, and the decoder written and tested,
+before a single real capture exists. That is worth doing while the PCBs are
+unassembled.
+
+## Order
+
+1. `vcan` bring-up script — everything else needs a bus.
+2. ICSim, vendored or documented, driving `vcan0`.
+3. GNSS fixture publishing `yukart/gnss/fix`.
+4. Local mosquitto config, and a single entry point that brings the whole fake car up.
+5. `canplayer` wrappers — only useful once Phase 1 has produced real captures.