diff --git a/README.md b/README.md
index 6b0335e..ee81c41 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,9 @@ ghosts anchored to real-world positions, each from their own viewpoint.
 residents/tracks, character editor, admin suite, dev error overlay, password-
 protected final mode, deployment — carries over unchanged.
 
+**[docs/PAGES.md](docs/PAGES.md) — every page the exhibit serves, and the API
+endpoints worth opening while debugging.** Keep it updated as pages change.
+
 ## What changed in v3
 
 The per-marker POS-IT → confidence-weighted fusion pipeline is replaced by a
@@ -29,7 +32,8 @@ The per-marker POS-IT → confidence-weighted fusion pipeline is replaced by a
 
 OpenCV.js (~13 MB WASM) is fetched at Docker build time (pinned
 `@techstark/opencv-js@4.12.0-release.1`) and lazy-loaded on the client after
-Start. If it fails to load, the app falls back to the v2 engine automatically.
+Start, with download progress shown in the dev HUD (`cv:loading 42%`). If it
+fails or stalls past 45 s, the app falls back to the v2 engine automatically.
 
 ## Dual engines (on-table A/B)
 
@@ -40,7 +44,7 @@ Dev HUD overlay tap zones (thirds):
 
 | zone   | opencv engine              | posit engine                |
 |--------|----------------------------|-----------------------------|
-| top    | switch engine              | switch engine               |
+| top    | switch engine (retries load if it failed) | switch engine |
 | middle | axis mode (`std`/`ymirror`)| rotation mode (`fr`/…)      |
 | bottom | —                          | camera correction (`none`/…)|
 
@@ -50,6 +54,26 @@ horizontal FOV override: `localStorage nbx.hfovDeg` (default 60, both engines).
 `axis ymirror` exists as on-device insurance: if the world appears mirrored /
 camera under the table in opencv mode, tap the middle third once.
 
+## Reading the dev HUD
+
+```
+ws open  rx scene,active,pong        <- WebSocket state + recent message types
+ghost recs 1                         <- ghost records the client is holding
+eng opencv  FROZEN                   <- engine; FROZEN = ghost motion paused (tap tracking chip)
+axis std  cv:ready                   <- engine mode + OpenCV load state
+markers 2  reproj 0.4px              <- crests detected + mean reprojection error
+raw / view / up / pos                <- solved camera pose
+m0 px(0.02,-0.05) proj(-0.71,0.63)   <- AIM CHECK, see below
+ghost ndc(-0.90,0.80) off-screen     <- first ghost's screen position
+```
+
+**Aim check.** `px` is where the crest actually sits in the camera frame
+(`0,0` = centre); `proj` is where the solved pose *projects* it. Point straight
+at a crest so `px` ≈ `(0,0)` — if `proj` disagrees, the camera-frame convention
+is wrong, not the tracking. A sign flip on x means mirrored, on y means
+Y-inverted, on both means a 180° roll. Ghosts also carry a magenta always-on-top
+beacon in dev mode, so "no ghost" and "ghost off-screen" can't be confused.
+
 ## First-time load (in place of v2)
 
 ```