From 3b010189df2697e9d41b50cf3fbd7a50450974ab Mon Sep 17 00:00:00 2001
From: Mikkeli <mikkeli@novoyuuparosk.org>
Date: Thu, 3 Sep 2026 18:48:32 +0900
Subject: [PATCH] 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
---
 README.md                  | 23 +++++++++++++++++++++++
 docs/GUIDELINES.md         | 20 ++++++++++++++++++++
 docs/impl/plans/INITIAL.md | 26 ++++++++++++++++++++++++++
 docs/impl/reports/.gitkeep |  0
 4 files changed, 69 insertions(+)
 create mode 100644 README.md
 create mode 100644 docs/GUIDELINES.md
 create mode 100644 docs/impl/plans/INITIAL.md
 create mode 100644 docs/impl/reports/.gitkeep

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dc5accf
--- /dev/null
+++ b/README.md
@@ -0,0 +1,23 @@
+---
+type: default
+---
+# Flutter display client
+
+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
+
+The in-car display. Renders vehicle telemetry and a moving map, and runs on a
+tablet connected to the Orin over USB or WiFi.
+
+Flutter rather than native Android so the display unit stays swappable — the
+display is deliberately a separate unit from the compute, and nothing here should
+assume it will always be an Android tablet.
+
+It is a bus subscriber like any other display: it talks to the message bus and to
+[svc-gw](gitea:yukart/svc-gw), never to hardware.
+
+- 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..65338f6
--- /dev/null
+++ b/docs/GUIDELINES.md
@@ -0,0 +1,20 @@
+---
+type: default
+---
+# Display client guidelines
+
+## 1. The client knows the contract, not the car
+- No CAN frame IDs, no DBC knowledge, no device paths. Topic names and payload
+  schemas only.  
+- If rendering something requires new knowledge of the vehicle, that knowledge
+  belongs upstream in the decoder, not here.
+
+## 2. Render whatever state exists, immediately
+- Retained topics mean a client connecting mid-drive has state at once. Never
+  block the first paint on a full set of signals.  
+- Missing is a normal state and must have a visual form. It is not an error.
+
+## 3. Design for a split screen
+- The screen may be shared with another app. Do not assume full width.
+
+## 4. To be added
diff --git a/docs/impl/plans/INITIAL.md b/docs/impl/plans/INITIAL.md
new file mode 100644
index 0000000..dde09f9
--- /dev/null
+++ b/docs/impl/plans/INITIAL.md
@@ -0,0 +1,26 @@
+---
+type: default
+---
+# Initial plan
+
+## Order
+
+1. MQTT client, subscribing to the retained vehicle topics. Text readout only —
+   prove the contract before drawing anything.
+2. Gauges.
+3. Moving map: MapLibre against the PMTiles basemap served by the Orin, with the
+   position from `yukart/gnss/fix`. No routing involved.
+4. Guidance from `yukart/nav/guidance`, once [svc-nav](gitea:yukart/svc-nav) publishes it.
+
+A moving map with position, heading and trace is most of the value in a car and
+needs no routing engine at all. Routing is the expensive last fraction.
+
+## Open
+
+- **Transport.** Over USB the tablet has an IP link via RNDIS, so it can reach the
+  broker directly. Whether it should, or should go through `svc-gw`, is decided in
+  that repo — see its initial plan.
+- **CJK labels.** MapLibre cannot ship Japanese glyph sets as SDF ranges. Local
+  font rendering must be configured, or labels will be slow or absent.
+- **Sunlight.** A typical tablet is unreadable through a windscreen in daylight.
+  This is a hardware problem, but the UI should not make it worse.
diff --git a/docs/impl/reports/.gitkeep b/docs/impl/reports/.gitkeep
new file mode 100644
index 0000000..e69de29