AGENTS.md: point agents at the v2 surface (app.py + ui/ + wavereader/), legacy/ frozen

AGENTS.md

@@ -1,102 +1,50 @@
 # AGENTS.md
 
 Guidance for AI coding agents working in this repo. The active surface is
-`main.py` + `app/` + `data/`. `wavereader/` was deleted after its port
-to `app/agent.py` + `app/agent_tools.py`.
+`app.py` + `ui/` + `wavereader/` + `data/` (the v2 rebuild). `legacy/`
+holds the frozen v1 front end (`main.py` + `app/`) — don't extend it; it
+survives only as the fallback layer in `ui/_compat.py`.
 
 ## What is live now
 
-- `main.py` — Gradio map front end. Run with `uv run python main.py`.
-- `app/generate_surf_break.py` — single-shot structured-JSON generator.
-- `app/generate_base_data.py` — batch/resumable enrichment runner.
-- `data/` — `australia-surf-breaks.json` (input list),
-  `australia-surf-breaks-enriched.json` (generated output),
-  `surf-break-schema.json` (conformance contract),
+- `app.py` — v2 entrypoint: `build()` + `gr.api` tools +
+  `demo.launch(css=APP_CSS, mcp_server=True)`. Run `uv run python app.py`.
+- `ui/` — the front end: `app.py` (layout + wiring, ≤3 `gr.State`),
+  `panels/{book,swell,agent}.py`, `charts/{score,swell,wind,seafloor,climate,map}.py`,
+  `_compat.py` (backend access: v2 core → `legacy.app.*` → stubs),
+  `theme.py` (`APP_CSS`, lo-fi Courier identity — don't restyle without asking).
+- `wavereader/` — pure core, typed + tested, no Gradio imports:
+  `breaks.py` (catalogue, memoized `load_breaks`), `openmeteo.py`
+  (versioned/atomic disk cache, seaward grid-snap), `scoring.py` (deterministic
+  0–10 engine — the LLM never owns numbers), `seafloor.py` (GEBCO world model),
+  `climate.py` (ERA5 5-yr profiles + audit), `tools.py` (the typed tool
+  functions shared by agent + MCP), `agent.py` (smolagents `ToolCallingAgent`,
+  native tool calls, budget: 6 steps / 2 score_week / 700 tokens),
+  `narrate.py` + `llm.py` (one InferenceClient factory:
+  Nemotron 3.5 Lightning via fireworks-ai, `WR_*` env overrides).
+- `scripts/warm_caches.py` — pre-fill forecast + seafloor caches (demo hot
+  start). `scripts/build_climate.py` — climatology builder.
+- `data/` — `australia-surf-breaks-enriched.json` (238 breaks),
+  `surf-break-schema.json` (contract), `climate/*.json` (ERA5 profiles),
   `surf-break-example-bells.json` (prompt worked example).
+- `documents/VIDEO_SCRIPT.md` — the GTC entry video shot list.
 
-## Front-end modules (`main.py` + `app/` UI layer)
+## Conventions that matter
 
-Entry: `main.py` (thin: re-exports + `main()` → `demo.launch(css=APP_CSS)`)
-calls `app/ui.py::build_demo()`. Run with `uv run python main.py`.
+- Staged spin-ups: `ui/panels/swell.py::fetch_forecast` is a **generator**
+  that yields stage 1 (charts, ~ms) then stage 2 (seafloor world model from
+  a parallel thread). Status lines name the engine + latency. Keep that
+  pattern for anything slow.
+- Charts: theme through `ui/charts/_style.py::style_fig`; weekend shading
+  via `add_weekend_shading`. Seafloor display is bicubically smoothed
+  (scipy) — smoothing is display-only; stats stay on the raw grid.
+- MCP surface = exactly `score_week` / `rank_region_week` / `explain_score`
+  (`gr.api` in `app.py`). All event listeners are registered with
+  `api_name=False` — keep it that way.
+- The LLM never owns numbers. Scores/forecasts/analysis stay deterministic;
+  the model narrates and cites tools.
 
-- `app/config.py` — paths (`DATA_PATH`), `ALL`, `SKILL_ORDER`/`SKILL_COLORS`,
-  `AUSTRALIA_CENTER`/`ZOOM`, shared strings (`SCORE_EXPLAINER_MD`,
-  `BROWSE_INTRO`, `AGENT_INTRO`, ...). `app/theme.py` — `APP_CSS` only.
-- `app/breaks_data.py` — `load_breaks()` reads
-  `data/australia-surf-breaks-enriched.json` into `DF` (handles legacy
-  `{"name | state | region": {...}}` dict format too, drops `error` rows).
-  Derives `STATES`, `REGIONS_BY_STATE`, `ALL_REGIONS`, `SKILLS`.
-  `filter_breaks(df, state, region, skill)` — `"All"`/None = no filter,
-  case-insensitive on canonical `state` / `region` / `skillLevel`.
-- `app/maps.py` — `build_map(records, default_view)` (Plotly `Scattermap`,
-  `open-street-map` style, marker colour by `SKILL_COLORS`, point order ==
-  records order). Auto-centers/zooms via `_zoom_for_span()` unless
-  `default_view` (unfiltered → whole Australia). `build_map_with_custom()`
-  adds the gold star marker for the session break. `_lat()` / `_lng()`
-  return None on missing coords.
-- `app/break_details.py` — `break_to_table(break_)` flattens one record to a
-  Field/Value dataframe; `_join()` stringifies list fields; `_cam_*` wrappers
-  + `CAMS` overlay via direct `from app import surf_cams` (optional, never
-  breaks the UI).
-- `app/browse_sync.py` — `update_map`, `on_break_pick`, region-choice
-  helpers, `mirror_*` one-way filter↔prefs sync, `resync_on_mode_toggle`,
-  `_format_pref_chip`. `_resolve_pick()` maps a break-list label back to its
-  record (custom break carries a `⭐ (your break)` suffix).
-- `app/custom_break.py` — `generate_custom_break()` streams
-  `(telemetry, details, map, dropdown, state)` tuples via `yield` (lazy
-  `from app import generate_surf_break`, no `importlib` shims). Empty custom
-  state/region fields fall back to the main map filters; explicit values win.
-  Exactly one custom break per session (`gr.State`, never written to disk).
-  `clear_custom_break()` deletes it.
-- `app/forecast_handlers.py` — `fetch_forecast()` (deterministic charts via
-  lazy `app.surf_forecast`) + `generate_reports()` (streams
-  `app.generate_surf_report` markdown).
-- `app/agent_trace.py` — trace coercion (`_coerce_scored_hours`,
-  `_coerce_rank_rows`, `_coerce_forecast_hours`), telemetry builders,
-  chart trios. `app/agent_chat.py` — `chat_fn` (lazy
-  `from app import agent`, session-persistent `SurfAgent`), spot dropdown,
-  leaderboard select.
-- `app/ui.py` — `build_demo()` layout + event wiring only (no logic).
-
-Conventions: lo-fi theme via `APP_CSS` (light blue bg `#d6e9f8`, dark blue
-`#0b2c5c`, Courier). Don't restyle without asking. Keep callbacks wired in
-`build_demo()` (`state_dd`/`region_dd`/`skill_dd` → `update_map`;
-`break_dd` → `on_break_pick`; `generate_btn` → `generate_custom_break`;
-`clear_btn` → `clear_custom_break`).
-
-## `app/` map of the code
-
-`app/generate_surf_break.py`:
-
-- `MODEL_ID = "nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16"`,
-  `PROVIDER = "fireworks-ai"`. Swap only to a model actually served by an
-  Inference Provider you have enabled.
-- `load_prompt_parts()` reads schema + Bells example from `data/`.
-- `build_surf_break_prompt(break_name, state, region)` — rules: JSON only,
-  populate required fields, strict enums, real-world geography (not generic
-  defaults), best-estimate coords, primary takeoff zone, 2–4 sentence
-  description, copy state/region verbatim into top-level AND
-  `location.state`/`location.region`.
-- `extract_json()` tolerates ```fences, else grabs outermost`{...}`.
-- `generate_surf_break(...)` — one `InferenceClient.chat.completions.create`
-  call (temp 0.4, max_tokens 2048). Deliberately NOT a smolagents CodeAgent
-  (ReAct `<code>` format conflicts with raw-JSON instruction — see module
-  docstring). CLI: `python app/generate_surf_break.py [name] [state] [region]`.
-- Needs `HF_TOKEN` env (Inference Providers access).
-
-`app/generate_base_data.py`:
-
-- `load_break_list()` flattens `Australia_Surf_Breaks: state → region →
-[names]` into `{break_name, state, region}` in stable order.
-- `enrich_result()` merges LLM output with canonical `state`/`region` from
-  the input list + stable `id`; normalizes `location.state/region`.
-- `load_existing_results()` / `save_results()` — resume-safe; accepts legacy
-  dict format, writes sorted list by (state, region, name).
-- `generate_with_retries()` — 2 attempts, linear backoff; failures are NOT
-  persisted (missing entries retry next run).
-- `main()` saves after every break + `REQUEST_DELAY = 1.0`s between calls.
-
-## `data/` contracts
+## Data contracts
 
 - Required break fields: `name`, `state`, `region`, `location`,
   `skillLevel`, `breakType`, `peakType`, `idealSwell`, `idealWind`,
@@ -107,25 +55,16 @@ Conventions: lo-fi theme via `APP_CSS` (light blue bg `#d6e9f8`, dark blue
   model. `location.country` is `"Australia"`.
 - New prompts must load schema + example from `data/` (don't paste copies).
 
-## `wavereader/` (deleted after port — see `app/agent.py` + `app/agent_tools.py`)
-
-- Ported: `app/agent_tools.py` (deterministic forecast/score/knowledge
-  functions over `data/australia-surf-breaks-enriched.json` via
-  `app/forecasts.py` + `app/scoring.py` + `app/adapters.py`),
-  `app/agent.py` (smolagents CodeAgent, HF Router, Nemotron defaults, trace
-  capture, single Tool definitions).
-- `main.py` "surf agent" tab chats via `SurfAgent.run_stream` and rebuilds
-  score/swell/wind charts from the trace's `score_week` payload.
-- The LLM never owns numbers — scores/forecasts stay deterministic.
-
 ## Rules for edits
 
-1. `app/` is tracked in this repo (no nested git — don't re-init one).
-2. Never commit `.env`, `.venv/`, `__pycache__/`, `.DS_Store` (all ignored).
+1. Everything is tracked in this repo (no nested git — don't re-init one).
+2. Never commit `.env`, `.venv/`, `__pycache__/`, `.DS_Store`, `.cache/`
+   (all ignored).
 3. Never read `.env` or print secrets/tokens. Use `.env.example` for var
    names; check presence with `printenv HF_TOKEN | wc -c` or
    `[ -n "$HF_TOKEN" ]` style checks that never echo the value.
-4. Keep prompt files in `data/`; keep `main.py` free of embedded schema text.
-5. Test cheaply: `uv run python -c "from pathlib import Path; import main"` for
-   import health; full generation calls cost inference — use the single-break
-   CLI before running the batch.
+4. Keep prompt files in `data/`; keep `app.py` free of embedded schema text.
+5. Test cheaply: `uv run pytest -q` (offline fixtures) +
+   `uv run python -c "import app"` for import health. Live LLM calls cost
+   inference — dry-run the agent via the injected fake model
+   (`tests/test_agent_dryrun.py`) before any live turn.