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 28665b4279
4 changed files with 75 additions and 0 deletions
@@ -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
@@ -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.