# AGENTS.md

Guidance for AI coding agents working in this repo. The active surface is
`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

- `app.py` — v2 entrypoint: `build()` + `gr.api` tools +
  `demo.launch(css=APP_CSS, mcp_server=True)`. Run `uv run python app.py`.
- `ui/` — the single-page front end (no tabs): `app.py` (layout + wiring,
  ≤3 `gr.State`; Bells Beach auto-selected on load so there are no empty
  states), `panels/{lens,story,intel,agent}.py` (map-lens column | forecast
  story | intel rail | full-width agent bar), `charts/{strip,score,seafloor,climate,map,_style}.py`,
  `contracts.py` (`SELECT_KEYS`/`FETCH_KEYS`/`AGENT_KEYS` + `fill()` —
  handlers return via `fill(KEYS, …)` so output ordering can't drift),
  `_compat.py` (backend access: v2 core → `legacy.app.*` → stubs; also
  wetsuit hints, engine chips, surf cams), `theme.py` (`APP_CSS`, IBM Plex
  Mono lo-fi 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; `break_climate` reads the
  profile embedded on each break record, per-slug file fallback), `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 Ultra via deepinfra, `WR_*` env overrides).
- `scripts/warm_caches.py` — pre-fill forecast + seafloor caches (demo hot
  start). `scripts/build_climate.py` — climatology builder (re-embeds built
  profiles into the catalogue after each run, backup first).
- `scripts/check_coords.py` + `scripts/check_coast.py` — break-coordinate
  maintenance: `check_coords` validates/fixes state/region/duplicate
  placement against OSM; `check_coast` audits GEBCO elevation at every
  break point and (`--fix`) snaps non-coastal ones to the nearest 0 m
  shoreline crossing (both write a timestamped backup first).
- `data/` — `australia-surf-breaks-enriched.json` (238 breaks; each record
  embeds its ERA5 profile under `climate` — 236 of 238, the two duplicate
  Gnaraloo rows have no profile),
  `surf-break-schema.json` (contract), `climate/*.json` (per-slug ERA5
  profiles — `build_climate.py` output and `break_climate`'s fallback;
  also `index.json` manifest), `surf-cams.json` (camera links keyed
  `"name | state | region"`), `surf-break-example-bells.json` (prompt worked
  example).

## Deploying to HF Spaces

- The Space `lucashudsn/wavereader` (public) *is* this repo — remote
  `space`. Every push to `main` auto-deploys via
  `.github/workflows/deploy-space.yml` (needs the GitHub repo secret
  `HF_TOKEN`) — merging to main ships it; no manual step. For any other
  branch, ship manually with `scripts/deploy_space.sh [ref]` (builds a
  throwaway commit that prepends `space-config.yaml` to `README.md` and
  force-pushes it to `space:main` — Spaces need YAML frontmatter, GitHub
  doesn't have to see it; the ref defaults to your current branch), then
  `git push origin <branch>` to keep GitHub in sync. The Space builds
  from the pushed commit; watch *Logs → Build* on the Space page or poll
  `HfApi().get_space_runtime("lucashudsn/wavereader")` until `RUNNING`.
- `space-config.yaml` is the Space config. Keep
  `sdk_version` in lockstep with the gradio pin in `requirements.txt`
  (regenerate that file only via `uv export --no-hashes
  --format requirements-txt --no-dev -o requirements.txt` — other
  invocations can leave stray progress lines that break pip), and
  `python_version` in lockstep with `pyproject.toml`'s `requires-python`.
  If you change Space settings via the web UI, HF rewrites the Space's
  `README.md` — mirror anything you care about back into the yaml.
- `HF_TOKEN` is a Space secret (set once via *Settings → Variables and
  secrets* or `HfApi().add_space_secret`); `WR_*` overrides can be added
  the same way. `.cache/` is ephemeral on the Space and rebuilds lazily —
  no persistent storage, no warm step.

## Conventions that matter

- One spot drives everything: `selected` (gr.State) is the single source of
  truth — picking a spot re-aims the map, badges, forecast strip, world
  model and climatology together. Keep it that way.
- Staged spin-ups: `ui/panels/story.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`. The week strip lives in `charts/strip.py`
  (score/swell/wind rows); window slicing (weekend/mornings/arvos) re-charts
  from state via `filter_hours` — no refetch. Seafloor display is bicubically
  smoothed (scipy) and its wave animation is period-driven — smoothing and
  animation are 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.

## Data contracts

- Required break fields: `name`, `state`, `region`, `location`,
  `skillLevel`, `breakType`, `peakType`, `idealSwell`, `idealWind`,
  `idealTide`. Optional: `description`, `id`, `bestSeason`, `hazards`,
  `crowdFactor`. Never invent enum values — check
  `data/surf-break-schema.json` first.
- Canonical `state`/`region` always come from the input list, never the
  model. `location.country` is `"Australia"`.
- New prompts must load schema + example from `data/` (don't paste copies).

## Rules for edits

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 `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.