From 6abcf0483cc517c78dc249767001b855825c4147 Mon Sep 17 00:00:00 2001
From: hermes-explorigin <tim+hermes@thecookiejar.me>
Date: Mon, 10 Aug 2026 16:10:21 +0000
Subject: [PATCH] docs: add CONTRIBUTING.md with setup, automated checks, and
 local QA checklist

---
 CONTRIBUTING.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..4cbd538
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,107 @@
+# Contributing to Navigator
+
+Thanks for contributing! This file covers how to build, test, and verify changes
+to the Navigator web app before opening a PR or pushing.
+
+## Project layout (quick map)
+
+```
+scripts/osm-data.mjs     # Overpass API data fetch -> static/data/<area>.geojson
+scripts/osm-dump.mjs     # .osm.pbf dump ingestion -> POIs + routable road graph
+src/lib/routing.ts       # pure routing math (A*, POI avoidance, turn-by-turn)
+src/lib/routing.worker.ts# Web Worker entry that runs route() off the UI thread
+src/lib/prefs.ts         # unit-system preference (localStorage)
+src/lib/savedPoints.ts   # browser-local Saved Points store + export/import (merge)
+src/lib/components/      # MapView, DirectionsPanel, LocationDialog, …
+src/routes/+page.svelte  # top-level page (loads the manifest)
+```
+
+## Setup
+
+```bash
+npm install
+
+# Fetch & build all static data (Overpass + dump). Uses committed data if you
+# only need the frontend; see below for data-only commands.
+npm run build
+
+# For frontend work without re-fetching over the network:
+npm run build:static     # rebuilds just the static site from existing static/data
+npm run dev              # Vite dev server
+```
+
+Data-only commands (they hit Overpass / download .pbf — be mindful of rate
+limits):
+
+```bash
+npm run build:data       # Overpass fetch -> static/data/*.geojson
+npm run build:dump       # .osm.pbf ingestion -> *-poi.geojson + *-graph.json
+```
+
+## Running the automated checks
+
+Run all three before considering a change done:
+
+```bash
+npm run check            # svelte-check (types + Svelte diagnostics) — 0 errors/warnings
+npm test                 # 33k+ offline regression checks (data, routing, saved points)
+npm run build:static     # static site must build cleanly
+```
+
+These run offline (no Overpass/Nominatim) and are exactly what CI runs on every
+push. **If any of these fail, fix before pushing.**
+
+## Continuous Integration
+
+- CI runs on every push/PR via Gitea Actions (`.gitea/workflows/ci.yml`).
+- It runs `npm ci`, `npm run check`, `npm test`, `npm run build:static`, and
+  verifies `build/index.html` + `build/data` exist.
+- Requires a registered runner with the `host` label (host-mode, no Docker).
+
+## Manual QA checklist
+
+The automated tests cover the data and routing logic. Because this sandbox's
+browser tooling only reaches public URLs (and cloud browsers are intentionally not
+used), the **visual/interaction layer needs a manual local pass**. Open the app
+locally (`npm run dev`, or serve `build/` with any static server) and verify:
+
+1. **Empty-map click** opens a context dialog with **"Save point…"** — it does
+   **not** auto-save or auto-start routing.
+2. **Existing-point click** (a POI/zone/path) opens the dialog showing its info
+   and a **"Directions from here"** action.
+3. **"Directions from here"** pins the origin, opens the Directions panel, and
+   lets you pick a destination.
+4. **Second-point click** offers **"Directions to here"**, which sets it as the
+   destination.
+5. The **Directions** top-bar button and the top **"Data sources"** bar are
+   **gone** (routes start only via the context dialog).
+6. **Saved Points** toggle in the legend shows/hides the purple saved-point pins.
+7. **Preferences** → **Export / Import** round-trips saved points; import
+   **merges** (dedupes by id) rather than replacing.
+8. Route computation shows a **live progress bar** and the UI stays responsive
+   (Web Worker is off the main thread).
+9. **Drive mode** shows **turn-by-turn** steps (Head north / Turn right /
+   Arrive at destination); Walk mode shows distance + time without turn steps.
+
+### Reporting an issue
+
+If a checklist item fails, note:
+- The step number and what you did.
+- Expected vs. actual behavior.
+- Any console errors (browser dev tools → Console).
+- Screenshot if helpful.
+
+Then either file it or paste the details here for a fix.
+
+## Commit conventions
+
+Angular-style, e.g.:
+
+```
+feat(directions): run route in a Web Worker with live progress
+fix(ui): open context dialog on map click instead of auto-saving
+refactor(prefs): drop redundant unit override
+docs: document the context-dialog interaction
+```
+
+Commit small, logical units (often one per task) and keep CI green on each.
\ No newline at end of file