docs: bring the README, data sources and known issues up to date (#712)

Reflect the weather stack, analyst records and feed provenance, satellite pass predictions and live camera video that landed since the last full pass.

Co-authored-by: Matt Van Horn <[email protected]>

docs/APPLICATION.md

@@ -105,14 +105,17 @@ checks when changing this wiring.
 
 `src/search` owns forward/reverse geocoding, place search and route provider
 interfaces. `createStandaloneApplication({ geospatial })` accepts `endpoints`
-and `providers`; the defaults preserve Google/Photon search, Google place context
-and the local OSRM route proxy. Location, annotations, HUD labels and voice use
-the composed service. Provider-specific credentials belong in the selected
-transport; server secrets never belong in browser configuration.
+and `providers`. Default forward search tries decimal coordinates and bundled
+place names (`presets`) first, without a network request, then Google when a key
+is configured, Photon, and the local `/api/geocode` Nominatim route. The
+defaults also keep Google place context and the local OSRM route proxy.
+Location, annotations, HUD labels and voice use the composed service.
+Provider-specific credentials belong in the selected transport; server secrets
+never belong in browser configuration.
 
-For a compatible protocol, configure `geocode`, `photon`, `reverse`, `textSearch`,
-`nearby` or `route` endpoints. These are developer-selected configuration, not
-URLs accepted from page queries or model arguments. A different protocol supplies
+For a compatible protocol, configure `geocode`, `photon`, `nominatim`, `reverse`,
+`textSearch`, `nearby` or `route` endpoints. These are developer-selected
+configuration, not URLs accepted from page queries or model arguments. A different protocol supplies
 an adapter function instead. The exported `createDefaultPlaceSearch` constructor
 supports the same options for direct composition:
 
@@ -181,10 +184,14 @@ separate constructors. Pass these to `createApplication`; use its `signal` and
 `defer` for ownership. The compatibility catalog is still page-scoped: construct
 one application per page. Controls, actions and renderers use the same layer
 instances. Configure sources with `application/sources` before registration or
-state restoration, and release them after the consumers stop.
+state restoration, and release them after the consumers stop. The catalog
+constructor (`application/layers`) also requires `wind`, `weather` and
+`cyclones` sources with `getSnapshot` for the Weather layers, and owns the
+observed-history clock those layers share for the catalog's lifetime.
 
 `application/services` accepts boundary, terrain, regional-context, weather and
-summary services. `application/requests` supplies the existing HTTP protocols
+summary services; its weather service supplies cockpit local conditions, not the
+Weather layers. `application/requests` supplies the existing HTTP protocols
 with configurable endpoints and a scoped transport. Changing an endpoint works
 only for a compatible protocol; another protocol supplies a service adapter.
 Cancellation discards late response bodies, and replacing a source invalidates

docs/CURRENT-STATE.md

@@ -146,12 +146,11 @@ messages use each product's eligibility gap (30 minutes, or three hours for the
 global mosaic). Wind shows forecast valid and issue times and does not follow
 history. Satellite clouds uses Clouds only / Full image configuration labels.
 
-Left weather rows retain the toggle, one status line with a source tooltip,
-configuration chips and the cyclone selection/focus list. Cyclone advisory,
-position time, wind, pressure, geometry status and the official advisory link
-live in the card. Controls opens the corresponding left row. The panel hides
-when empty, auto-expands once per page session and then preserves the user's
-collapsed state. Status lines reserve their space and refreshes are coalesced
+Left weather rows retain only the toggle and one status line with a source
+tooltip. Configuration and the cyclone Storms list live in the cards, as do the
+cyclone advisory, position time, wind, pressure, geometry status and the
+official advisory link. The panel hides when empty, auto-expands once per page
+session and then preserves the user's collapsed state. Status lines reserve their space and refreshes are coalesced
 per frame. Generic keyed rail cards and the native rail timeline preserve DOM
 nodes and avoid identical writes; the weather panel owns descriptor mapping.
 Inspection emphasizes the chosen scalar and marks the exact sampled location;
@@ -2637,7 +2636,7 @@ test:track` 43 tracking invariants · headless QA harnesses under
 > ISS pass prediction, and per-layer data attribution. Gate at close: unit 98/98, build clean,
 > track 19/19, + five QA harnesses (heading 16/16, sprites 9/9, cctv 5/5, failstate 5/5,
 > attribution 18/18). New modules: `src/data/{motionModel,aircraftMeta,aircraftClass,aircraftIcons,issPass,routePlausible,dataCredits}.js`.
-> The live runtime now declares 28 voice tools; the 17→20 count above is retained only as milestone history.
+> The live runtime now declares 29 voice tools; the 17→20 count above is retained only as milestone history.
 
 ## Canonical Docs Order
 
@@ -3526,7 +3525,7 @@ silently demoting every later lookup for the session.
 
 - **Token flow**: browser fetches a short-lived client secret from `/api/realtime/token`; the Vite middleware holds `OPENAI_API_KEY` and posts the full session config (instructions, tool schemas, VAD, truncation) to `api.openai.com/v1/realtime/client_secrets`. SDP exchange goes directly to `api.openai.com/v1/realtime/calls` with the ephemeral token.
 - **Session defaults** (env-tunable): model `gpt-realtime-2` (or `gpt-realtime-2.1-mini` when the MINI tier is selected — see the model-tier entry below), voice `marin`, reasoning effort `low`, semantic VAD with low eagerness, no response interruption, context window truncated to ~3,000 post-instruction tokens with 0.5 retention ratio — the conversational window stays short because map state is fetched live per turn.
-- **Twenty-eight tools** (schemas defined server-side in `vite.config.js`, executed client-side in `src/voice/gevActions.js`): `fly_to_location`, `select_nearest_aircraft`, `adjust_camera_zoom`, `zoom_to_globe`, `set_layer_visibility`, `show_data_layers_menu`, `set_panel_open`, `set_visual_style`, `get_entity_context`, `get_current_view_state`, `set_hud`, `set_detection`, `set_map_stack`, `set_post_processing`, `control_scene`, `control_cctv`, `set_context_mode`, `control_cockpit`, `control_radio`, `track_entity`, `stop_tracking`, `frame_overhead`, `annotate_map`, `clear_annotations`, `move_camera`, `fly_route`, `analyst_query`, and `next_iss_pass`.
+- **Twenty-nine tools** (argument schemas in `src/voice/actionSchemas.js`, served with their descriptions by `server/providers/openai/tools.js`, executed client-side in `src/voice/gevActions.js`): `fly_to_location`, `select_nearest_aircraft`, `adjust_camera_zoom`, `zoom_to_globe`, `set_layer_visibility`, `show_data_layers_menu`, `set_panel_open`, `set_visual_style`, `get_entity_context`, `get_current_view_state`, `set_hud`, `set_detection`, `set_map_stack`, `set_post_processing`, `control_scene`, `control_cctv`, `set_context_mode`, `control_cockpit`, `control_radio`, `track_entity`, `stop_tracking`, `frame_overhead`, `annotate_map`, `clear_annotations`, `move_camera`, `fly_route`, `analyst_query`, `next_iss_pass`, and `next_satellite_pass`.
 
 > **Reading `npm test` totals:** the count depends on the Node major. The two
 > GC-bracketed allocation microbenchmarks (`src/data/focusAllocations.test.mjs`
@@ -4166,9 +4165,9 @@ restoring a host joins the retained history target. The wind row explicitly says
 “Forecast · does not follow history” while the observed clock is in history mode.
 The catalog exposes `weatherClock` and destroys it with its lifetime signal.
 
-Existing row controls retain source, opacity, coverage navigation and transport;
-no controls move in this pass. The viewer clock is untouched. Observation layers
-are off by default; share/persist includes appearance and product, while history
+Source, opacity, coverage navigation and transport controls live in the WEATHER
+panel's cards and timeline, not in the rows. The viewer clock is untouched.
+Observation layers are off by default; share/persist includes appearance and product, while history
 is transient and shared links open latest. Rendering retains the previous frame
 when an incoming frame fails; no eligible historical frame instead hides imagery.
 

docs/KNOWN-ISSUES.md

@@ -1,6 +1,6 @@
 # KNOWN ISSUES
 
-Updated: July 8, 2026
+Updated: September 22, 2026
 
 This file tracks active runtime issues only.
 
@@ -78,6 +78,56 @@ Status: Open (owner-accepted 2026-07-08, documented)
 
 ---
 
+### Weather layers: coverage and meaning
+Status: Open (source limits, by design)
+
+- **Rain radar covers the contiguous United States only.** It shows MRMS
+  reflectivity in dBZ, not rainfall rate or a forecast; a gap in coverage does not
+  mean no precipitation.
+- **Lightning density is a ground-network grid, not GLM flashes.** It is NOAA's
+  15-minute density product derived from Vaisala NLDN/GLD360 on an approximately
+  8 km grid, for the Americas and Pacific only (110°E across the dateline to 0°,
+  25°S–80°N). It is not a live strike counter or an all-clear.
+- **Cyclone advisories cover NOAA's basins only:** the Atlantic and the
+  eastern/central North Pacific (NHC and CPHC). Storms elsewhere do not appear.
+  The cone is forecast-center uncertainty, not storm size.
+- **Satellite clouds:** global infrared is hourly with typically 2–3 hours of
+  source latency. Clouds only is a brightness filter, not a cloud mask.
+- **Wind is a forecast.** The animation flows through one forecast on an
+  approximately 1° grid and does not advance forecast time or follow the
+  observed-history timeline.
+- **History is not shared.** Share links carry the weather layers and their
+  settings but open at Latest.
+- **3D Tiles detail window during history playback:** when a frame's detail image
+  is slow to arrive, the window may fall back to the coarser full-extent image
+  until it does.
+- Native hardware GPU behavior of the wind and weather renderers is not yet
+  verified.
+
+---
+
+### Satellite passes and analyst answers
+Status: Open (by design)
+
+- Pass predictions search the next 24 hours for satellites in the loaded catalog.
+  Visibility is a geometric estimate (satellite sunlit, observer's Sun at or
+  below −6°); it ignores weather, satellite brightness and orbital-element age.
+- Analyst counts and ranks cover a bounded set of loaded records (by default
+  2,000 per layer for satellites, datacenters and dams), so omitted records can
+  change a nearest or count answer. Satellite distance is ground distance.
+
+---
+
+### Live camera video (HLS)
+Status: Open (limits)
+
+- At most two live-video sessions run at once. RTMP-only sources and encrypted,
+  fMP4 or byte-range playlists are not supported.
+- When live video fails, the camera falls back to its labeled still, Street View
+  or placeholder frame, which is not live video.
+
+---
+
 ## Closed / Intentional (for clarity)
 
 ### Proxy SSRF and error-surface hardening gaps
@@ -118,5 +168,14 @@ Context:
   converted to **live NASA FIRMS data** on 2026-07-16: the `/api/firms` proxy merges
   three VIIRS NRT sources (trailing 24 h, 30 min cache, serve-stale-on-failure) and the
   bundled snapshot was deleted. Requires a free server-side `FIRMS_MAP_KEY`; without it
-  the layer shows a KEY REQUIRED state.
-- Weather radar is still held out of OSS v1 after QA found the previous overlay did not provide reliable visible value.
+  the layer row reads "Needs FIRMS_MAP_KEY — add it in Provider Settings".
+
+---
+
+### Weather radar held out of the open-source release
+Status: Closed — observed rain radar shipped (September 2026)
+
+Context:
+- Rain radar, Satellite clouds, Lightning density, Wind and Cyclone advisories
+  are in the Weather group of Data Layers. Their current limits are listed under
+  "Weather layers: coverage and meaning" above.