Populate design, architecture and repo layout docs

project-yukart becomes the code-free hub: overview, roadmap and cross-cutting
design only. Each app or app cluster gets its own repo, indexed from here.

- ARCHITECTURE.md: separate services over a message bus, with displays as bus
  subscribers so the directly-driven screen, Android client and ESP32 panel
  share one contract. Records CAN scope (listen-only + OBD-II as sole writer)
  and a decisions table for choices still in flux.
- REPOS.md: repo splitting rule, planned repos, naming, and Gitea template-repo
  policy (scaffolding only — no upstream link after instantiation).
- ROADMAP.md: phases 0-5, capture and decode before displays.

Bus choice (MQTT) is marked proposed pending a check against real CAN rates;
implementation language is still open.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/REPOS.md

@@ -0,0 +1,86 @@
+# Repositories
+
+## Splitting rule
+
+- **`project-yukart`** — overview, roadmap, cross-cutting design. No code, ever.
+- **`orin-nano-env-setup`** — the host: kernel modules, drivers, OS packages,
+  device permissions, systemd plumbing. Anything that must be true *before* an
+  application starts.
+- **One repo per application or application cluster.** A cluster is a set of
+  services that are developed, versioned and deployed together.
+- **Helper/deployment repos** stand alone when they are reusable outside Yukart.
+
+Anything cross-repo — topic names, payload schemas, the DBC — belongs in the
+contracts repo, not copied into each consumer.
+
+## Current
+
+| Repository | Role |
+|---|---|
+| [project-yukart](gitea:yukart/project-yukart) | Hub: overview, roadmap, architecture |
+| [orin-nano-env-setup](gitea:yukart/orin-nano-env-setup) | Jetson host bring-up |
+
+## Planned
+
+| Repository | Role | Why separate |
+|---|---|---|
+| `yukart-contracts` | Topic namespace, payload schemas, Z27AG DBC | Consumed by every other repo, including non-Jetson clients; must not be duplicated |
+| `yukart-core` | Acquisition + processing cluster: `can-bridge`, `obd-poller`, `gnss`, `decoder`, `recorder` | Developed and deployed as one unit on the Orin |
+| `yukart-gw` | `telemetry-gw` — serves external display clients | Independent release cycle from acquisition; the network-facing surface |
+| `yukart-hud` | Local renderer for the directly-driven screen (Class A) | Its own toolchain and graphics stack |
+| `yukart-android` | Android display client (Class B) | Entirely separate toolchain and release process |
+| `yukart-esp32-display` | ESP32 RLCD/e-ink display firmware (Class B) | Embedded toolchain, flashed not deployed |
+| `yukart-analysis` | Offline session analysis, reverse-engineering notebooks | Runs off-car, no runtime coupling |
+
+Create these lazily — when there is something to put in them, not before.
+
+## Naming
+
+- `yukart-*` for project-specific repositories.
+- **No prefix** for reusable helpers, since the prefix would be a lie the first
+  time one is used in another project.
+
+## Helper and deployment repos
+
+Arduino and ESP32 work implies flashing, build and deployment scaffolding that
+is likely to be reused. Keep those unprefixed and generic — e.g. an ESP32
+project skeleton with the toolchain, flashing scripts and CI already wired up.
+
+### Gitea template repositories
+
+Gitea supports these: repo **Settings → Repository → Template**, after which the
+repo offers **"Use this template"** to create new repos from it.
+
+Use a template repo for **scaffolding** — a new ESP32 or Arduino project that
+should start with the toolchain, directory layout and flashing scripts in place.
+
+Do **not** use one for code you intend to keep updating in one place. Template
+instantiation is a fork-at-create: the copy has no link back, so improvements to
+the template never reach repos already created from it. For genuinely shared
+code, use a git submodule or publish a package instead.
+
+Rule of thumb: *template for the starting shape, submodule/package for living
+code.*
+
+## Linking convention
+
+Cross-repo links use the `gitea:owner/repo` scheme, as established in the hub
+README — e.g. `[Environment setup](gitea:yukart/orin-nano-env-setup)`.
+
+## Per-repo document layout
+
+Following the convention already set by `orin-nano-env-setup`:
+
+```
+README.md            minimal portal, points everywhere else
+docs/
+  GUIDELINES.md      implementation practice for this repo
+  BOM.md             hardware, where the repo owns hardware
+  impl/
+    plans/           what is intended
+    reports/         what actually happened, and why
+```
+
+The `impl/plans` ÷ `impl/reports` split is worth keeping: plans go stale,
+reports do not. A report like `PCAN-SETUP.md` stays valuable precisely because
+it records the investigation and the dead ends, not just the final commands.