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

@@ -0,0 +1,19 @@
+---
+type: default
+---
+# Telemetry gateway
+
+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
+
+Runs on the Orin. The network-facing surface for external display clients:
+aggregates and rate-limits bus traffic on their behalf, and fronts the navigation
+HTTP API so a display has one address to talk to.
+
+It is a bus subscriber. It never touches hardware and never transmits on CAN.
+
+- For implementation practice guidelines, refer to the [guidelines](docs/GUIDELINES.md);  
+- For implementation plans and history, refer to [them](docs/impl/);

docs/GUIDELINES.md

@@ -0,0 +1,16 @@
+---
+type: default
+---
+# Gateway guidelines
+
+## 1. Read-only with respect to acquisition
+- The gateway subscribes. It never opens a CAN socket, TX-capable or otherwise.  
+- `obd-poller` is the single writer on the bus. Nothing here changes that.
+
+## 2. Aggregate, do not relay
+- A 500 kbps CAN bus produces far more traffic than a display can use or a USB
+  link should carry. Downsample and summarise here.  
+- If the gateway is only forwarding a topic unchanged, that client should have
+  subscribed to the broker directly instead.
+
+## 3. To be added

docs/impl/plans/INITIAL.md

@@ -0,0 +1,30 @@
+---
+type: default
+---
+# Initial plan
+
+## The scope question, first
+
+This started as "aggregator and pusher to the tablet over USB". The pushing part
+may not need to exist: over USB the tablet has an IP link via RNDIS, and the
+architecture already says Class B devices reaching the bus over IP connect to the
+broker directly. A Flutter MQTT client can talk to mosquitto with no hop in between.
+
+What does not go away:
+
+| Job | Why it needs a gateway |
+|---|---|
+| Aggregation | Raw CAN at 500 kbps must never reach a display; something has to downsample |
+| Nav HTTP proxy | Route requests are request/response and fit MQTT badly |
+| Static assets | Serving the PMTiles basemap to the display |
+| Non-IP transports | BT SPP and plain serial for ESP32 clients have no broker access |
+
+So: build the aggregation and the HTTP surface. Do not build a telemetry relay for
+clients that can already subscribe for themselves.
+
+## Order
+
+1. Static file serving for the basemap — smallest useful thing, unblocks the map.
+2. Nav HTTP proxy to [svc-nav](gitea:yukart/svc-nav).
+3. Aggregation and rate limiting, once there is real CAN traffic to aggregate.
+4. Serial bridge, when an ESP32 client exists.