commit 32d5df87ab40e1ed8ff7d2c132da2e8e9e9f1568
Author: Mikkeli <mikkeli@novoyuuparosk.org>
Date:   Fri Sep 4 00:51:32 2026 +0900

    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

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..de06c41
--- /dev/null
+++ b/README.md
@@ -0,0 +1,21 @@
+---
+type: default
+---
+# Mocks and fixtures
+
+Part of **Project Yukart**, making an old 2008 Mitsubishi Z27AG a bit smarter with modern technologies.  
+This file serves as the minimalist portal to other docs
+
+
+## What this repo is about
+
+Everything needed to bring up a believable fake car on a workstation, so the rest
+of the project can be developed with no Jetson, no PCBs and no Z27AG present.
+
+One repo rather than one per fixture: they share the contract, they change
+together when a schema changes, and the whole point is to bring the fake
+environment up in a single step. Splitting them would make that an orchestration
+problem for no gain.
+
+- For implementation practice guidelines, refer to the [guidelines](docs/GUIDELINES.md);  
+- For implementation plans and history, refer to [them](docs/impl/);
diff --git a/docs/GUIDELINES.md b/docs/GUIDELINES.md
new file mode 100644
index 0000000..b5b8310
--- /dev/null
+++ b/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
diff --git a/docs/impl/plans/INITIAL.md b/docs/impl/plans/INITIAL.md
new file mode 100644
index 0000000..764f178
--- /dev/null
+++ b/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.
diff --git a/docs/impl/reports/.gitkeep b/docs/impl/reports/.gitkeep
new file mode 100644
index 0000000..e69de29