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,21 @@
+---
+type: default
+---
+# Navigation service
+
+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. Answers routing questions and publishes turn-by-turn guidance
+onto the message bus, so no display has to know where routes come from.
+
+Routing is served by a local Valhalla instance against artifacts built by
+[tool-mapmint](gitea:yukart/tool-mapmint), which is the offline-capable default.
+The provider is kept behind an interface so a cloud routing API can be swapped in
+without touching anything downstream.
+
+- 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,18 @@
+---
+type: default
+---
+# Navigation service guidelines
+
+## 1. Routing providers stay behind one interface
+- Nothing outside the provider boundary may reference Valhalla types, Valhalla
+  URLs, or Valhalla's response shapes.  
+- A cloud provider (GCP or equivalent) must be addable without changes to the
+  bridge, the published topics, or any display.  
+- Local Valhalla is the default because it works with no signal; a cloud provider
+  is an option, never a dependency.
+
+## 2. Guidance is published, routes are requested
+- Live guidance goes onto `yukart/nav/guidance`, retained.  
+- Route requests are request/response and are served over HTTP, not MQTT.
+
+## 3. To be added

docs/impl/plans/INITIAL.md

@@ -0,0 +1,32 @@
+---
+type: default
+---
+# Initial plan
+
+## Scope
+
+Turn a GNSS fix plus a destination into guidance on the bus. Nothing about
+rendering — that belongs to the display client.
+
+## Order
+
+1. Confirm Valhalla builds and runs on the Jetson (arm64). This is the one real
+   integration risk in the whole navigation workstream — upstream's arm64
+   container story is unsettled. Do it before anything else.
+2. Stand up Valhalla against artifacts from `tool-mapmint`, serving HTTP locally.
+3. Define the routing provider interface, with Valhalla as the first implementation.
+4. Bridge: subscribe to `yukart/gnss/fix`, publish `yukart/nav/guidance`.
+5. Meili map matching over recorded sessions — see below.
+
+## Why map matching comes early
+
+Meili's `trace_attributes` snaps a recorded GNSS trace onto OSM and returns road
+attribution along it: speed limit, road class, geometry. That is ground truth for
+validating reverse-engineered CAN signals, which is otherwise guesswork. It is
+worth having before any navigation UI exists.
+
+## Blocked on
+
+Live guidance needs a GNSS fix, which needs gpsd, which needs the SIM7600 brought
+up in [orin-nano-env-setup](gitea:yukart/orin-nano-env-setup). Everything else here
+can be built and validated against a replayed trace.