commit 28665b427967cfbd09ece1ac0b02a4964c249094
Author: Mikkeli <mikkeli@novoyuuparosk.org>
Date:   Thu Sep 3 18:48:32 2026 +0900

    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

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..59113d8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,25 @@
+---
+type: default
+---
+# Map artifact minting
+
+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
+
+Workstation-side batch pipeline. Turns upstream OpenStreetMap into the two
+artifacts the car needs, which are unrelated to each other and built by different
+tools:
+
+| Artifact | Built by | Consumed by |
+|---|---|---|
+| Valhalla routing tiles — the road graph | `valhalla_build_tiles` | [svc-nav](gitea:yukart/svc-nav) |
+| Protomaps PMTiles basemap — the picture | `go-pmtiles` | [app-flutter](gitea:yukart/app-flutter) |
+
+**Nothing here runs on the Orin.** These are one-off jobs wanting RAM, cores and
+disk; the Orin only ever receives the output.
+
+- 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..5e6666e
--- /dev/null
+++ b/docs/GUIDELINES.md
@@ -0,0 +1,21 @@
+---
+type: default
+---
+# Map minting guidelines
+
+## 1. Artifacts are never committed
+- Routing tiles and basemaps are large binaries rebuilt from upstream. This repo
+  holds the scripts that produce them and a report of the procedure, nothing else.  
+- Every build records the source PBF's date. An artifact whose provenance is
+  unknown is an artifact to rebuild.
+
+## 2. Build the admin database first
+- `valhalla_build_admins` is what determines driving side, and it is a separate
+  step *before* the tile build.  
+- Skip it and Valhalla routes and narrates as though Japan drove on the right.
+
+## 3. Tiles ship as a directory, not a tar
+- Once for RAM on an 8 GB board, once because `rsync` deltas a tree of changed
+  files where a multi-gigabyte tar forces a full checksum at both ends.
+
+## 4. To be added
diff --git a/docs/impl/plans/INITIAL.md b/docs/impl/plans/INITIAL.md
new file mode 100644
index 0000000..85847b5
--- /dev/null
+++ b/docs/impl/plans/INITIAL.md
@@ -0,0 +1,29 @@
+---
+type: default
+---
+# Initial plan
+
+## Inputs
+
+| Source | What |
+|---|---|
+| Geofabrik | `japan-latest.osm.pbf`, 2.3 GB, or a regional extract |
+| Protomaps daily planet | sliced by bounding box, no planet download needed |
+
+Start with the region actually driven rather than all of Japan. Geofabrik publishes
+Kantō, Chūbu, Hokkaidō and others separately.
+
+## Steps
+
+1. Fetch the PBF for the target region.
+2. `valhalla_build_admins` — driving side and border data.
+3. `valhalla_build_tiles` — the routing graph, output as a directory.
+4. `go-pmtiles extract` against the Protomaps planet for the same bounding box.
+5. Record source dates and output sizes in a report under `docs/impl/reports/`.
+
+## Delivery
+
+Out of scope for now — the artifacts are moved by hand. When it stops being
+tolerable, `rsync` over the LAN only, never over LTE, with `--partial-dir` so a
+transfer survives being cut off. Swap atomically: build beside the live copy,
+symlink-swap, restart. Never overwrite tiles the server is reading.
diff --git a/docs/impl/reports/.gitkeep b/docs/impl/reports/.gitkeep
new file mode 100644
index 0000000..e69de29