Merge d04939b813 into 759652207f

CONTRIBUTING.md

@@ -27,6 +27,25 @@ through Pinokio; the terminal path above remains the contributor path.
 
 Open `http://localhost:4173`. Before sending a PR run `npm run build`, `npm test`, and `npm run test:track` (dev server must be up) — **all three must stay green.**
 
+### Test prerequisites
+
+- **`npm test`** — unit tests. Runs standalone; no dev server or credentials
+  required. Exit code is the gate.
+- **`npm run test:track`** — the 3D flight-tracking regression harness. It
+  drives the **real app** in headless Chromium, so it **requires a running
+  dev server** on the default port (`http://localhost:4173`). Pass
+  `--url <app-url>` to point it at another instance (e.g.
+  `node scripts/track-regression.mjs --url http://localhost:4272`). It does not
+  depend on live OpenSky / adsb.lol / AISStream (those are optional or
+  rate-limited locally); it installs a persistent `fetch` shim that returns
+  synthetic aircraft in the exact upstream payload shapes the layers parse.
+- **`npm run build`** — production Vite build. No server or credentials
+  required; it validates that the client bundle compiles cleanly.
+
+If you change runtime behavior, update `docs/CURRENT-STATE.md` and
+`CHANGELOG.md` in the same PR. For a deeper catalog of what each harness
+checks and what it needs to run, see [TESTING.md](TESTING.md).
+
 ## Good first contributions
 
 The highest-leverage places to jump in:

DATA_SOURCES.md

@@ -125,6 +125,36 @@ the retrieval date (2026-07-30), exact download URL, license evidence, and the
 deterministic transform (`scripts/build-sf-neighborhoods.mjs`: `nhood` → `name`, ~2 m
 Douglas-Peucker simplification, 6-decimal rounding).
 
+### Pilot CCTV source packs (`config/`)
+
+`config/cctv_sources.shinjuku.json` is a **demo source pack** (3 cameras:
+Shinjuku Crossing, Shinjuku Station West, Shibuya Scramble) used for
+projection-pipeline testing. The feeds are Google-hosted sample MP4 videos
+(`storage.googleapis.com/gtv-videos-bucket/sample/`), not live public cameras.
+Camera poses (coordinates, heading, pitch, FOV, mount height) are fabricated
+priors placed at recognizable Tokyo intersections.
+
+Use the pack by setting:
+
+```bash
+CCTV_SOURCES_FILE=config/cctv_sources.shinjuku.json npm run dev
+```
+
+Or equivalently, via `./scripts/dev-cctv.sh`:
+
+```bash
+CCTV_SOURCES_FILE=config/cctv_sources.shinjuku.json ./scripts/dev-cctv.sh
+```
+
+The pack exercises the same CCTV registration and frustum-projection pipeline
+as live city packs without requiring network access to a camera catalog. It is
+**not** a live data source and carries no external attribution requirement. The
+sample videos are publicly available Google test media.
+
+`config/cctv_sources.austin.json` is the reference live pack. Custom source
+packs follow the same JSON schema (see either file); `CCTV_SOURCES_JSON`
+accepts inline JSON as an alternative to a file path.
+
 ---
 
 ## In-app attribution

docs/KNOWN-ISSUES.md

@@ -57,9 +57,9 @@ Status: Open (owner-accepted 2026-07-08, documented)
   a few stragglers take one more poll.
 - **Born-grounded first poll:** a contact first seen on the ground with no altitude
   data renders at the geoid for ≤1 poll until its floor cell warms.
-- Full context, improvement ideas, and the verification oracle
-  (`scripts/qa-floor-verify.mjs`):
-  `docs/superpowers/reports/2026-07-08-height-datum-handover.md`.
+- Verify floor-placement behavior with `scripts/qa-floor-verify.mjs` against a
+  running local app; set `QA_BASE_URL` when it is not on the default port
+  (`http://localhost:4173`).
 
 ---