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
2026-09-03 18:48:32 +09:00
commit 3b010189df
4 changed files with 69 additions and 0 deletions
@@ -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
@@ -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.