From d04939b813da2e9d5f4a0bc3e056616d78a57c90 Mon Sep 17 00:00:00 2001
From: Gaurav Patidar <patidargaurav4477@gmail.com>
Date: Wed, 9 Sep 2026 13:23:59 +0530
Subject: [PATCH] fix:docs

---
 CONTRIBUTING.md      | 19 +++++++++++++++++++
 DATA_SOURCES.md      | 30 ++++++++++++++++++++++++++++++
 docs/KNOWN-ISSUES.md |  6 +++---
 3 files changed, 52 insertions(+), 3 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6760dfd..029b535 100644
--- a/CONTRIBUTING.md
+++ b/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:
diff --git a/DATA_SOURCES.md b/DATA_SOURCES.md
index faa351d..bb06261 100644
--- a/DATA_SOURCES.md
+++ b/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
diff --git a/docs/KNOWN-ISSUES.md b/docs/KNOWN-ISSUES.md
index 33c665f..ca46d2e 100644
--- a/docs/KNOWN-ISSUES.md
+++ b/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`).
 
 ---