made some cosmetic changes, and reformatted charts, create surf report generation function and tested

README.md

@@ -1,12 +1,15 @@
 # wave~reader
 
-Australian surf-break encyclopaedia + deterministic surf forecast (two Gradio tabs).
+Australian surf-break encyclopaedia + scored surf forecast (two Gradio tabs).
 
 Tab 1 (`encyclopedia`) filters spots on a Plotly `Scattermap` and shows
-break details. Tab 2 (`surf forecast`) fetches Open-Meteo marine + wind
-data for the selected break and scores every hour 0–10. The LLM never
-owns numbers — generation lives in `app/`, scores/forecasts stay
-deterministic in `wavereader/`.
+break details. Tab 2 (`surf forecast`) is two-stage: Stage 1 fetches
+Open-Meteo marine + wind data for the selected break and scores every
+hour 0–10 (deterministic); Stage 2 optionally streams a short LLM
+dot-point report that narrates those scores. The LLM never owns
+numbers — generation lives in `app/generate_surf_break.py` /
+`app/generate_surf_report.py`, scores/forecasts stay deterministic in
+`app/scoring.py` + `app/forecasts.py`.
 
 ## Layout
 
@@ -16,6 +19,7 @@ app/
   generate_surf_break.py         # single-shot structured-JSON break generator
   generate_base_data.py          # batch/resumable enrichment runner
   surf_forecast.py               # scored-forecast service + Plotly builders (no Gradio)
+  generate_surf_report.py        # Stage-2 streamed LLM report (narrates scores only)
   forecasts.py                   # Open-Meteo marine + weather client, disk cache
   scoring.py                     # deterministic 0–10 surf-quality engine
   adapters.py                    # enriched-break -> scoring-spot bridge (flat 15kt wind)
@@ -24,11 +28,11 @@ data/
   australia-surf-breaks-enriched.json  # output: list of schema-valid breaks
   surf-break-schema.json               # JSON Schema every break must conform to
   surf-break-example-bells.json        # worked example (Bells Beach) used in the prompt
-wavereader/
-  agent.py / tools.py            # kept, agent not wired into UI yet
+wavereader/                      # legacy-kept, not wired into the UI
+  agent.py / tools.py            # agentic forecast-explanation layer (kept for later)
 documents/
   ENCYCLOPEDIA.md                # encyclopedia tab deep dive
-  FORECAST.md                    # forecast tab deep dive (pipeline, scoring, cache)
+  FORECAST.md                    # forecast tab deep dive (pipeline, scoring, cache, report)
 ```
 
 ## Setup
@@ -42,9 +46,11 @@ cp .env.example .env   # then fill in HF_TOKEN
 ```
 
 `HF_TOKEN` (Inference Providers access,
-https://huggingface.co/settings/tokens) is only needed for break
-generation (`app/`). The forecast tab needs network access to Open-Meteo,
-with disk cache fallback under `.cache/` (git-ignored).
+https://huggingface.co/settings/tokens) is needed for break generation
+(`app/generate_surf_break.py`) and the Stage-2 surf report
+(`app/generate_surf_report.py`). The Stage-1 forecast charts need
+network access to Open-Meteo, with disk cache fallback under `.cache/`
+(git-ignored).
 
 ## Run the front end
 
@@ -59,11 +65,14 @@ Two tabs share one `selected_break` state:
   its details table. "Can't find your local break?" generates one live
   via `app/generate_surf_break.py` — session-only (`gr.State`, never
   written to `data/`). See `documents/ENCYCLOPEDIA.md`.
-- **surf forecast** — pick a break on tab 1, then press **Get forecast**
-  on tab 2. Skill defaults to the break's own `skillLevel`
-  (`pro-only` → `expert`); days slider 1–7. Shows best-window hero,
-  score curve, component breakdown, waves + wind charts, daily-best and
-  hourly tables. See `documents/FORECAST.md`.
+- **surf forecast** — pick a break on tab 1, then press **Get forecast
+  (charts)** on tab 2. Skill defaults to the break's own `skillLevel`
+  (`pro-only` → `expert`); window is fixed at 7 days. Shows a best-window
+  hero, score bars (red → green, gold ★ on the best hour), swell
+  height + period chart, and a wind-arrows strip (colour = direction
+  quality, size = strength). Then optionally press **Generate surf
+  report ✨** for a streamed dot-point write-up (one bullet per day +
+  `**Recommendation: …**`). See `documents/FORECAST.md`.
 
 ## Generate break data
 
@@ -103,14 +112,24 @@ fences / outermost `{...}` and parses. `enrich_result()` pins canonical
 
 ## Forecast pipeline (short)
 
-`main.py fetch_forecast` → `app/surf_forecast.get_scored_week`
-(break → `adapters.enriched_to_scoring_spot` → `forecasts.get_forecast`
-→ `scoring.score_week`) → Plotly figs + tables. Wind tolerance is a
-flat `15kt` (`adapters.DEFAULT_WIND_MAX_KT`) because the schema carries
-no wind-strength number. Full detail in `documents/FORECAST.md`.
+Stage 1 (`main.py fetch_forecast` → `app/surf_forecast.get_scored_week`):
+break → `adapters.enriched_to_scoring_spot` → `forecasts.get_forecast`
+→ `scoring.score_week` → score / swell / wind figs + `scored_payload`
+(best + daily bests + scored hours). Wind tolerance is a flat `15kt`
+(`adapters.DEFAULT_WIND_MAX_KT`) because the schema carries no
+wind-strength number.
+
+Stage 2 (`main.py generate_reports` →
+`app/generate_surf_report.generate_surf_report_stream`): the prompt
+carries only the daily bests (≤7 lines) + best window + a one-line
+break summary; the model streams plain markdown (one bullet per day +
+`Recommendation` line) with reasoning disabled (`/no_think` +
+`reasoning_effort: "none"`). It narrates the provided scores only.
+Full detail in `documents/FORECAST.md`.
 
 ## Kept for later
 
-`wavereader/agent.py` / `wavereader/tools.py` are the agentic
-forecast-explanation layer. Not wired into the UI yet — the forecast
-tab is deterministic only by design.
+`wavereader/agent.py` / `wavereader/tools.py` are the legacy agentic
+forecast-explanation layer. Not wired into the UI — the forecast tab
+is Stage-1 deterministic plus the Stage-2 `generate_surf_report.py`
+narrator by design.

app/generate_surf_report.py

@@ -0,0 +1,304 @@
+"""
+Hugging Face Inference Providers + NVIDIA Nemotron 3 -- short surf report.
+
+Same framework as ``generate_surf_break.py`` (deliberately NOT a smolagents
+CodeAgent -- single-shot call via ``InferenceClient.chat.completions.create``).
+
+Speed-first design (TTFT is dominated by prompt prefill + output length):
+
+- The prompt carries ONLY the daily bests (<=7 lines) + the single best
+  window + a one-line break summary. The old version sent every scored
+  hour (~168 rows for 7 days) plus the full break record -- that prefill
+  is what made generation feel like it never started.
+- Output is plain markdown, NOT JSON: one dot-point (bullet) per day
+  covering the day-by-day outlook (one full sentence per day), plus a final
+  line naming the single best day/window to surf. Short output
+  (~350 tokens) with ``max_tokens=800``.
+- Plain text also streams cleanly: what the user watches arrive IS the
+  report -- no JSON escape decoding or partial-parse step.
+
+The LLM never owns numbers -- scores/forecasts stay deterministic in
+``app/scoring.py`` + ``app/forecasts.py``. The prompt instructs the model to
+narrate only the provided numbers, never invent swell/wind/score values.
+
+Requires ``HF_TOKEN`` env (Inference Providers access).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+
+from huggingface_hub import InferenceClient
+
+MODEL_ID = "nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B-BF16"
+PROVIDER = "deepinfra"
+
+MAX_TOKENS = 800
+TEMPERATURE = 0.3
+
+# Reasoning runs in a separate channel, not in the visible text:
+# - DeepInfra honors ``reasoning_effort: "none"`` (disables chain-of-thought
+#   entirely: faster, cheaper, direct answer). Passed via ``extra_body``.
+# - Nemotron itself honors the ``/no_think`` system-prompt directive.
+# Without these, the model can spend the whole token budget "thinking" and
+# leave nothing for the report -- which is exactly the blank output seen
+# in the UI. Marker/cleaning logic below stays as a safety net.
+SYSTEM_PROMPT = "/no_think\nWrite only the final surf summary. Never reveal thinking, reasoning, or planning."
+EXTRA_BODY = {"reasoning_effort": "none"}
+
+
+def _day_line(d: dict) -> str:
+    """One daily best as a single compact line for the prompt."""
+    d = d or {}
+    # best_window() returns a raw scored row with no 'date' key -- derive
+    # it from the timestamp so the model never sees a "None" date (which
+    # visibly confused it into reasoning out loud about what "None" means).
+    date = d.get("date") or str(d.get("time") or "")[:10] or "?"
+    return (
+        f"{date} {d.get('time')} | score={d.get('score')}/10 | "
+        f"wave={d.get('wave_height_m')}m@{d.get('wave_period_s')}s | "
+        f"wind={d.get('wind_speed_kt')}kt@{d.get('wind_direction_deg')}deg"
+    )
+
+
+def _break_line(break_: dict) -> str:
+    """One-line break context: ideals + hazards only, truncated."""
+    swell = (break_ or {}).get("idealSwell") or {}
+    wind = (break_ or {}).get("idealWind") or {}
+    size = swell.get("sizeRangeFt") or {}
+    hazards = (break_ or {}).get("hazards") or []
+    if isinstance(hazards, list):
+        hazards = ", ".join(str(h) for h in hazards[:3])
+    return (
+        f"{break_.get('name')}, {break_.get('region')}, {break_.get('state')} | "
+        f"ideal swell {swell.get('direction')} {size.get('min')}-{size.get('max')}ft | "
+        f"ideal wind {wind.get('direction')} | hazards: {hazards}"
+    )
+
+
+def build_surf_report_prompt(
+    break_: dict,
+    skill: str,
+    daily: list[dict],
+    best: dict | None,
+    days: int,
+) -> str:
+    """Assemble the tiny report prompt: daily bests + best window only."""
+    daily_block = "\n".join(_day_line(d) for d in (daily or []))
+    best_block = _day_line(best) if best else "none"
+
+    return f"""You are a surf report writer. You narrate deterministic forecast scores -- you never invent numbers.
+
+Rules:
+1. Wrap your ENTIRE response between these markers, on their own lines, with NOTHING outside them -- no intro, no thinking, no notes, no commentary:
+@@REPORT@@
+<your dot-point report, then recommendation line>
+@@END@@
+2. NEVER show your thinking, reasoning, planning, or notes to yourself. Do NOT use <think> tags or any reasoning preamble -- the first thing you emit is @@REPORT@@, the last thing is @@END@@.
+3. Use ONLY the numbers/times below. Never invent wave heights, periods, wind speeds, directions, or scores.
+4. Write one dot-point (markdown bullet starting with "- ") per day below, in date order, for a {skill} surfer. Each bullet names the date with its score, wave height/period and wind, followed by one full sentence explaining the outlook in plain language (e.g. what the conditions will feel like and whether it suits a {skill} surfer). If a day scores poorly, say so plainly in a full sentence. One bullet per day, no extra bullets.
+5. After the bullets, add a blank line then exactly one line: **Recommendation: <date + time> -- <one short reason>.** naming the single best day/window to surf.
+
+Break: {_break_line(break_ or {})}
+Skill: {skill} | Window: {days} day(s)
+
+Best window: {best_block}
+
+Daily bests:
+{daily_block}
+
+Report:"""
+
+
+def _strip_fences(text: str) -> str:
+    """Remove stray code fences if the model added them anyway."""
+    text = (text or "").strip()
+    fence_match = re.search(r"```(?:\w+)?\s*(.*?)\s*```", text, re.DOTALL)
+    if fence_match:
+        return fence_match.group(1).strip()
+    return text
+
+
+_THINK_RE = re.compile(
+    r"<\s*(think|thinking|reason|reasoning)[^>]*>.*?(<\s*/\s*\1\s*>|$)",
+    re.DOTALL | re.IGNORECASE,
+)
+_STRAY_TAG_RE = re.compile(
+    r"<\s*/?\s*(think|thinking|reason|reasoning)[^>]*>", re.IGNORECASE
+)
+
+
+_REPORT_START = "@@REPORT@@"
+_REPORT_END = "@@END@@"
+
+# Sentences containing these phrases (case-insensitive) are model
+# planning/thinking leaked as plain text (no <think> tags), e.g. "We need
+# to produce dot-points...". Kept narrow on purpose: ordinary surf outlook
+# words ("could be", "probably", "should be") are legit report language
+# and must never be filtered.
+_META_PHRASES = (
+    "we need to",
+    "i need to",
+    "need to produce",
+    "need to output",
+    "must end with",
+    "must include",
+    "must name",
+    "the best window given",
+    "requirement",
+    "need to ",
+    "plan:",
+    "thinking:",
+    "reasoning:",
+)
+
+_SENT_SPLIT_RE = re.compile(r"(?<=[.!?])\s+|\n+")
+
+
+def _drop_thinking_sentences(text: str) -> str:
+    """Remove plain-text planning sentences; return "" if nothing remains.
+
+    Joins with newlines when the text is a dot-point list so bullets
+    survive the fallback path; otherwise joins with spaces.
+    """
+    parts = [p for p in _SENT_SPLIT_RE.split(text or "") if p.strip()]
+    kept = [
+        p for p in parts if not any(m in p.lower() for m in _META_PHRASES)
+    ]
+    if any(p.lstrip().startswith(("-", "*")) for p in kept):
+        return "\n".join(kept).strip()
+    return " ".join(kept).strip()
+
+
+def _clean_output(text: str) -> str:
+    """Strip reasoning traces + markers + fences so only the summary remains.
+
+    Three layers, in order:
+
+    1. ``<think>...</think>`` blocks (complete or unclosed mid-stream).
+    2. ``@@REPORT@@ ... @@END@@`` markers: everything outside them is
+       discarded. Mid-stream (start seen, end not yet) returns whatever
+       follows the start marker; pre-marker thinking yields "" so the UI
+       shows its streaming placeholder instead of the model's planning.
+    3. Fallback when the model ignores the markers: drop plain-text
+       planning sentences ("We need to produce...", "Probably best
+       is..."). Returns "" when only thinking has arrived so far.
+    """
+    text = text or ""
+    # Remove complete <think>...</think> blocks, and a trailing unclosed
+    # <think>... block (common mid-stream).
+    text = _THINK_RE.sub("", text)
+    text = _STRAY_TAG_RE.sub("", text)
+    if _REPORT_START in text:
+        after = text.split(_REPORT_START, 1)[1]
+        if _REPORT_END in after:
+            after = after.split(_REPORT_END, 1)[0]
+        return _strip_fences(after).strip()
+    cleaned = _strip_fences(text).strip()
+    if not cleaned:
+        return ""
+    filtered = _drop_thinking_sentences(cleaned)
+    return filtered
+
+
+def generate_surf_report(
+    break_: dict,
+    skill: str,
+    daily: list[dict],
+    best: dict | None,
+    days: int,
+    model_id: str = MODEL_ID,
+    provider: str = PROVIDER,
+    max_tokens: int = MAX_TOKENS,
+    temperature: float = TEMPERATURE,
+) -> str:
+    """Generate the short plain-markdown report in one LLM call."""
+    client = InferenceClient(provider=provider, api_key=os.environ.get("HF_TOKEN"))
+
+    prompt = build_surf_report_prompt(
+        break_=break_, skill=skill, daily=daily, best=best, days=days
+    )
+
+    completion = client.chat.completions.create(
+        model=model_id,
+        messages=[
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": prompt},
+        ],
+        max_tokens=max_tokens,
+        temperature=temperature,
+        extra_body=EXTRA_BODY,
+    )
+
+    return _clean_output(completion.choices[0].message.content)
+
+
+def generate_surf_report_stream(
+    break_: dict,
+    skill: str,
+    daily: list[dict],
+    best: dict | None,
+    days: int,
+    model_id: str = MODEL_ID,
+    provider: str = PROVIDER,
+    max_tokens: int = MAX_TOKENS,
+    temperature: float = TEMPERATURE,
+    stats: dict | None = None,
+):
+    """Stream the short report token-by-token.
+
+    Yields the accumulated plain-text report after every delta, so the
+    Gradio handler displays exactly what the user will read -- no
+    post-parse step needed. Reasoning is disabled at the API level
+    (``reasoning_effort: "none"`` + ``/no_think``), so ``delta.content``
+    carries the final answer; anything thinking-shaped that still slips
+    through is stripped live. If ``stats`` is given, it is filled with
+    ``reasoning_chars`` (hidden reasoning-channel text, never displayed)
+    and ``content_chars`` so callers can prove the visible text is the
+    final report, not the thinking stage.
+    """
+    client = InferenceClient(provider=provider, api_key=os.environ.get("HF_TOKEN"))
+
+    prompt = build_surf_report_prompt(
+        break_=break_, skill=skill, daily=daily, best=best, days=days
+    )
+
+    stream = client.chat.completions.create(
+        model=model_id,
+        messages=[
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": prompt},
+        ],
+        max_tokens=max_tokens,
+        temperature=temperature,
+        stream=True,
+        extra_body=EXTRA_BODY,
+    )
+
+    accumulated = ""
+    reasoning_chars = 0
+    for chunk in stream:
+        try:
+            delta = chunk.choices[0].delta
+        except (AttributeError, IndexError):
+            delta = None
+        content = getattr(delta, "content", None) if delta is not None else None
+        # Reasoning channel, when present, stays hidden -- counted only.
+        reasoning = getattr(delta, "reasoning_content", None) if delta is not None else None
+        if reasoning:
+            reasoning_chars += len(reasoning)
+        if content:
+            accumulated += content
+            yield _clean_output(accumulated)
+    if stats is not None:
+        stats["reasoning_chars"] = reasoning_chars
+        stats["content_chars"] = len(accumulated)
+    if accumulated:
+        yield _clean_output(accumulated)
+
+
+if __name__ == "__main__":
+    print("Usage: import generate_surf_report() from main.py -- no standalone CLI.")
+    sys.exit(0)

app/surf_forecast.py

@@ -8,6 +8,8 @@ from __future__ import annotations
 
 from typing import Any, Optional
 
+import math
+
 import plotly.graph_objects as go
 
 from app.adapters import break_skill, enriched_to_scoring_spot, get_coords, normalize_skill
@@ -158,6 +160,65 @@ def _score_color(score: float) -> str:
 _ARROWS_8 = ["↑", "↗", "→", "↘", "↓", "↙", "←", "↖"]
 _COMPASS_8 = ["N", "NE", "E", "SE", "S", "SW", "W", "NW"]
 
+_COMPASS_DEG_16 = {
+    "N": 0.0, "NNE": 22.5, "NE": 45.0, "ENE": 67.5,
+    "E": 90.0, "ESE": 112.5, "SE": 135.0, "SSE": 157.5,
+    "S": 180.0, "SSW": 202.5, "SW": 225.0, "WSW": 247.5,
+    "W": 270.0, "WNW": 292.5, "NW": 315.0, "NNW": 337.5,
+}
+
+# Arrow colours: direction quality only (size encodes strength).
+_WIND_GOOD = "#1a9850"  # green — offshore / good direction
+_WIND_CROSS = "#eab308"  # yellow — cross-shore
+_WIND_BAD = "#d73027"  # red — onshore
+
+
+def _parse_dir_to_deg(direction: Any) -> float | None:
+    """Parse 'N', 'NE/SW', 'N to SW' style bearings to degrees (cyclic mean)."""
+    if direction is None:
+        return None
+    if isinstance(direction, (int, float)):
+        try:
+            return float(direction) % 360.0
+        except (TypeError, ValueError):
+            return None
+    text = str(direction).replace(",", "/").replace(" to ", "/").replace(" ", "").upper()
+    parts = [p for p in text.split("/") if p in _COMPASS_DEG_16]
+    if not parts:
+        return None
+    sin_sum = sum(math.sin(math.radians(_COMPASS_DEG_16[p])) for p in parts)
+    cos_sum = sum(math.cos(math.radians(_COMPASS_DEG_16[p])) for p in parts)
+    return math.degrees(math.atan2(sin_sum, cos_sum)) % 360.0
+
+
+def _angular_diff(a: float, b: float) -> float:
+    d = abs(float(a) - float(b)) % 360.0
+    return d if d <= 180.0 else 360.0 - d
+
+
+def _wind_quality_color(wind_from_deg: float, offshore_from_deg: float | None) -> str:
+    """Green (offshore) ≤45°, yellow (cross) ≤135°, else red (onshore)."""
+    if offshore_from_deg is None:
+        return "#0b2c5c"
+    try:
+        diff = _angular_diff(float(wind_from_deg), float(offshore_from_deg))
+    except (TypeError, ValueError):
+        return "#0b2c5c"
+    if diff <= 45.0:
+        return _WIND_GOOD
+    if diff <= 135.0:
+        return _WIND_CROSS
+    return _WIND_BAD
+
+
+def _wind_arrow_size(speed_kt: Any) -> float:
+    """Arrow size encodes strength: ~22 pt when light → ~33 pt when strong (1–1.5x)."""
+    try:
+        s = max(0.0, float(speed_kt))
+    except (TypeError, ValueError):
+        return 22.0
+    return 22.0 + 11.0 * min(s, 30.0) / 30.0
+
 
 def _deg_to_compass(deg: float) -> str:
     """8-point compass label for a meteorological degree."""
@@ -275,45 +336,59 @@ def build_waves_fig(scored: list[dict]) -> go.Figure:
     return _strip_layout(fig, height=230, hide_x=True)
 
 
-def build_wind_fig(scored: list[dict]) -> go.Figure:
-    """Wind speed line + arrow markers showing blow-to direction."""
+def build_wind_fig(scored: list[dict], spot: dict | None = None) -> go.Figure:
+    """Wind as colored arrows only: colour = direction quality, size = strength.
+
+    Green = offshore/good (≤45° from the spot's ideal), yellow = cross-shore,
+    red = onshore (>135°). Arrow size scales 22→33 pt (1–1.5x) with wind
+    speed in kt; heavy font weight keeps them thick. Single row, no y-axis —
+    strength reads from size only, exact kt on hover. Arrows point where the
+    wind blows TO. ``spot`` is the scoring spot (``ideal_wind.direction``);
+    without it all arrows fall back to dark blue.
+    """
     if not scored:
         return _empty_fig()
     times = [r.get("time") for r in scored]
     speeds = [r.get("wind_speed_kt") for r in scored]
     dirs = [r.get("wind_direction_deg") for r in scored]
+    offshore_deg: float | None = None
+    if isinstance(spot, dict):
+        offshore_deg = _parse_dir_to_deg((spot.get("ideal_wind") or {}).get("direction"))
     fig = go.Figure()
-    fig.add_trace(
-        go.Scatter(
-            x=times,
-            y=speeds,
-            mode="lines",
-            fill="tozeroy",
-            fillcolor="rgba(44,160,44,0.18)",
-            line={"color": "#2ca02c", "width": 2},
-            hovertemplate="%{x}<br>%{y:.0f} kt %{customdata}<extra></extra>",
-            customdata=[f"from {_deg_to_compass(d)} ({float(d):.0f}°)" for d in dirs],
-            name="speed (kt)",
-        )
-    )
     # Subsample arrows so the strip stays readable (~1 per 6 h on a 7-day view).
     step = max(1, len(times) // 28)
     idx = list(range(0, len(times), step))
+    colors = [_wind_quality_color(dirs[i], offshore_deg) for i in idx]
+    sizes = [_wind_arrow_size(speeds[i]) for i in idx]
     fig.add_trace(
         go.Scatter(
             x=[times[i] for i in idx],
-            y=[speeds[i] for i in idx],
+            y=[1.0] * len(idx),
             mode="text",
             text=[_deg_to_arrow_from(dirs[i]) for i in idx],
-            textfont={"size": 17, "color": "#0b2c5c"},
+            textfont={
+                "size": sizes,
+                "color": colors,
+                "family": "Arial Black, Arial, sans-serif",
+            },
             hovertemplate="%{x}<br>%{customdata}<extra></extra>",
             customdata=[
                 f"{float(speeds[i]):.0f} kt from {_deg_to_compass(dirs[i])} "
                 f"({float(dirs[i]):.0f}°) — arrow points where it blows to"
                 for i in idx
             ],
-            name="direction →",
+            name="wind",
+            showlegend=False,
         )
     )
-    fig.update_layout(title="Wind (arrows point where wind blows to)", yaxis={"title": "kt"})
-    return _strip_layout(fig, height=230, hide_x=False)
+    # No legend — the title already carries the colour meaning, and the
+    # overlay legend was blocking arrows.
+    fig.update_layout(
+        title="Wind (green=offshore, yellow=cross, red=onshore; size=strength)",
+        yaxis={"visible": False, "showticklabels": False, "range": [0.5, 1.5]},
+        showlegend=False,
+    )
+    fig = _strip_layout(fig, height=170, hide_x=False)
+    fig.update_yaxes(visible=False, showticklabels=False, showgrid=False, zeroline=False)
+    fig.update_layout(showlegend=False)
+    return fig

documents/FORECAST.md

@@ -1,28 +1,41 @@
 # Surf forecast tab
 
 The `surf forecast` tab in `main.py:build_demo()` scores the break
-selected on the `encyclopedia` tab. Fully deterministic: Open-Meteo
-numbers in, `scoring.py` numbers out. No agent/LLM in this path.
+selected on the `encyclopedia` tab. Two stages:
+
+- **Stage 1 — deterministic charts** (`fetch_forecast`): Open-Meteo
+  numbers in, `scoring.py` numbers out. No agent/LLM in this path.
+- **Stage 2 — narrated report** (`generate_reports`, opt-in): the LLM
+  narrates the Stage-1 scores only — it never invents swell/wind/score
+  values.
 
 ## Pipeline
 
 ```
 pick break (tab 1, break_dd -> selected_break gr.State)
-  -> press "Get forecast" (tab 2, fetch_btn)
+  -> press "Get forecast (charts)" (tab 2, fetch_btn)
   -> fetch_forecast() [main.py]
-  -> _load_forecast() [importlib, app/surf_forecast.py, no package import]
-  -> get_scored_week(break, skill, days)
+  -> _load_forecast() [importlib, app/surf_forecast.py]
+  -> get_scored_week(break, skill, days=7)
        -> adapters.enriched_to_scoring_spot(break)   # schema -> scoring shape
        -> forecasts.get_forecast(lat, lng, days)     # marine + wind, cached
        -> scoring.score_week(forecast, spot, skill)  # 0-10 per hour
-  -> best_window / daily_best / build_*_fig + tables
+  -> best_window / daily_best / build_score_fig / build_waves_fig / build_wind_fig
+  -> scored_payload gr.State {break, skill, spot, scored, daily, best, days}
+  -> press "Generate surf report" (tab 2, report_btn) [optional]
+  -> generate_reports() [main.py]
+  -> _load_report() [importlib, app/generate_surf_report.py]
+  -> generate_surf_report_stream(break, skill, daily, best, days)
 ```
 
-`fetch_forecast` shows `gr.Progress` steps and writes human-readable
-status into `status_box`; any exception surfaces there with empty figs
-(no traceback in UI).
+`fetch_forecast` fixes `days = 7` (no days slider in the UI;
+`get_scored_week` still clamps any `days` arg to 1–7). It shows
+`gr.Progress` steps and writes human-readable status into `status_box`
+plus a tool-call trace into `report_telemetry_box`; any exception
+surfaces there with empty figs (no traceback in UI). An empty `scored`
+list disables the report path (`scored_payload = None`).
 
-## Adapter (`wavereader/adapters.py`)
+## Adapter (`app/adapters.py`)
 
 `scoring.py` expects the old spot shape; the enriched schema differs,
 so the adapter bridges it:
@@ -30,44 +43,52 @@ so the adapter bridges it:
 | scoring expects | enriched has | mapping |
 |---|---|---|
 | `ideal_swell.direction: "SE"` | `idealSwell.direction: ["E","ESE","SE"]` | `/`-join list (`_dir_to_deg` parses `/` as cyclic mean); empty → `"E"` |
-| `ideal_swell.size_ft_min/max` | `idealSwell.sizeRangeFt.{min,max}` | float cast |
+| `ideal_swell.size_ft_min/max` | `idealSwell.sizeRangeFt.{min,max}` | float cast (missing → `0.0`) |
 | `ideal_wind.direction` | `idealWind.direction: [...]` | same `/`-join; empty → `"E"` |
 | `ideal_wind.strength_kt_max` | only `idealWind.type` (offshore/…) | flat `15.0` (`DEFAULT_WIND_MAX_KT`) — schema has no knots value; final limit is `min(15, skill_profile_max)` in `_score_wind` |
-| skill `beginner/intermediate/advanced/expert` | + `pro-only` | `pro-only` → `expert`; unknown/None → `intermediate` |
+| skill `beginner/intermediate/advanced/expert` | + `pro-only` | `pro-only`/`pro only`/`pro` → `expert`; unknown/None → `intermediate` |
 
 Helpers: `normalize_skill()`, `break_skill()` (break's own tier),
-`get_coords()` (mirrors `main.py _lat/_lng`, `None` on missing).
+`get_coords()` (mirrors `main.py _lat`/`_lng`, `None` on missing).
 
-## Forecast client (`wavereader/forecasts.py`)
+## Forecast client (`app/forecasts.py`)
 
 - Two Open-Meteo endpoints merged on `time` by `_build_normalized`:
   `marine-api.open-meteo.com` (hourly `wave_height`, `wave_period`,
   `wave_direction`, `wind_wave_height`, `swell_wave_height`) +
   `api.open-meteo.com` (hourly `wind_speed_10m` in km/h, converted to
   knots in `score_week`, + `wind_direction_10m`). Marine serves no wind.
-- Grid snap: coords shift ~0.13° seaward (`_seaward_offset`: TAS/south
-  coast south, east coast east, west coast west) so lookups land on a
-  marine grid point.
+- Grid snap: coords shift ~0.13° seaward (`_seaward_offset`, rounded to
+  2 dp by `_round_coords`) so lookups land on a marine grid point —
+  TAS (`lat <= -39.5`) shifts south, east coast (`lon >= 147`) shifts
+  east, west coast (`lon <= 125`) shifts west, otherwise (SA/VIC south
+  coast) shifts south.
 - Cache: `.cache/forecasts/<lat>_<lon>_<days>.json` envelope
-  `{fetched_at, data}`, TTL 6h (`CACHE_TTL_SECONDS`). Fresh cache served
-  without network; on API failure the stale entry is served as fallback;
-  raises only with no usable data at all. Horizon: hourly, 1–7 days
-  (`days_slider`, clamped).
+  `{fetched_at, data}` (key from the *raw* spot coords; the seaward
+  offset is a fetch detail only). TTL 6h (`CACHE_TTL_SECONDS`). Fresh
+  cache served without network (written atomically via tmp + rename);
+  on API failure the stale entry is served as fallback (legacy
+  pre-envelope files return with `fetched_at = 0` so they still work
+  as stale fallback); raises only with no usable data at all.
 
-## Scoring (`wavereader/scoring.py`)
+## Scoring (`app/scoring.py`)
 
 Per hour (`score_hour`), weights `swell_size 0.30 / swell_direction
 0.20 / wind 0.30 / period 0.20` (redistributed when direction missing):
 
-- **size** — 10 inside spot's `[min,max]`, Gaussian falloff outside,
-  multiplied by skill comfort penalty → 0 above `max_safe_size_ft`.
-- **direction** — Gaussian on angular diff to ideal (σ = 30°).
+- **size** — 10 inside spot's `[min,max]`, Gaussian falloff outside
+  (`σ = max(1.0, min*0.4)` below, `σ = max(1.5, max*0.5)` above),
+  multiplied by skill comfort multiplier → 0 above `max_safe_size_ft`.
+- **direction** — Gaussian on angular diff to ideal
+  (`σ = 45/1.5 = 30°`, so 45° off ≈ 3.2/10).
 - **wind** — mean of speed (10 if ≤ limit else 0; glassy ≤5kt always 10)
-  and direction (cosine falloff from offshore). Limit =
+  and direction (`10 * max(0, cos(diff/2))`, i.e. perfect offshore →
+  10, 180° off (onshore) → 0). Limit =
   `min(spot 15kt, skill max)`.
 - **period** — 0 at ≤4s, linear to 10 at ≥14s, never penalised above.
 
-`score_week` skips hours with nulls. Skill profiles (ft / kt / s):
+`score_week` skips hours with nulls and converts `wind_speed_10m`
+km/h → kt (`× 0.539957`). Skill profiles (ft / kt / s):
 
 | skill | comfort ft | max safe ft | max wind kt |
 |---|---|---|---|
@@ -78,24 +99,63 @@ Per hour (`score_hour`), weights `swell_size 0.30 / swell_direction
 
 ## UI outputs (`app/surf_forecast.py` builders)
 
+`get_scored_week` returns `{forecast, scored, spot, skill, lat, lng}`.
+`daily_best` groups by date (first 10 chars of `time`) and returns
+`{date, time, score, wave_height_m, wave_period_s, wind_speed_kt,
+wind_direction_deg}` per day. `best_window` is the single
+highest-scoring hour.
+
 - `best_md` hero: `**score/10 @ time** — H m @ P s, wind Wkt (deg°)`.
-- `build_score_fig` — time → score line (y 0–10) + best-hour marker.
-- `build_components_fig` — 4 lines: `swell_size / swell_direction /
-  wind / period`.
-- `build_waves_fig` — `wave_height_m` + `wave_period_s` (right axis).
-- `build_wind_fig` — `wind_speed_kt` line.
-- `daily_df` — best hour per date via `daily_best`.
-- `hourly_df` — every scored hour: time, score, 4 components, wave
-  height/period, wind kt.
-- Empty `scored` → figs annotated `No forecast data`, tables empty.
+- `build_score_fig` — score bars coloured red → green by quality
+  (≥8 dark green, ≥6 light green, ≥4 yellow, ≥2 orange, else red) +
+  gold ★ marker on the best hour.
+- `build_waves_fig` — `wave_height_m` filled area (blue, left axis) +
+  `wave_period_s` line (orange, right axis).
+- `build_wind_fig` — arrows only, no y-axis: colour = direction
+  quality vs the spot's ideal offshore (green ≤45°, yellow cross
+  ≤135°, red onshore above that; dark blue when the spot has no
+  parseable direction), size = strength (22 → 33pt over 0–30kt),
+  subsampled to ~28 arrows. Arrows point where the wind blows TO;
+  exact kt + compass on hover.
+- All three share `_strip_layout` styling (compact heights, unified
+  hover, white plot bg). `build_components_fig` is retired (returns
+  `No forecast data`) — use `build_score_fig`.
+- Empty `scored` → figs annotated `No forecast data`, report disabled.
+
+## Stage-2 report (`app/generate_surf_report.py`)
+
+Same framework as break generation (single-shot `InferenceClient`
+call, `nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B-BF16` via
+`provider="deepinfra"`, deliberately NOT a smolagents CodeAgent).
+Speed-first: the prompt carries ONLY the daily bests (≤7 lines) + the
+single best window + a one-line break summary (ideals + up to 3
+hazards) — never the full hourly table or full break record.
+
+- Output is plain markdown, NOT JSON: one `- ` bullet per day in date
+  order (date, score, height/period, wind, short outlook phrase) plus
+  a final `**Recommendation: <date + time> -- <reason>.**` line.
+  `max_tokens=500`, `temperature=0.3`.
+- Reasoning disabled at the API level (`EXTRA_BODY =
+  {"reasoning_effort": "none"}` + `/no_think` system prompt). Markers
+  `@@REPORT@@ … @@END@@` fence the answer; `_clean_output` strips
+  `<think>` blocks, fences, and plain-text planning sentences
+  ("we need to…") live during streaming.
+- `generate_surf_report_stream` yields the accumulated cleaned report
+  per delta; `stats` reports `reasoning_chars` (hidden channel, never
+  displayed) vs `content_chars` so callers can prove the visible text
+  is the final report. `main.py generate_reports` yields an instant
+  "Contacting report model…" placeholder first so the button never
+  looks dead, then streams. LLM failure keeps the deterministic
+  charts — only the report box shows the error.
 
 ## Behaviour + limits
 
 - Explicit **Get forecast** button — no auto-fetch on pick (saves API
-  calls). Skill dropdown defaults to the selected break's tier; days
-  default 7.
+  calls). Skill dropdown defaults to the selected break's tier
+  (`pro-only` → `expert`); window fixed at 7 days. Report is a second
+  explicit opt-in after inspecting the charts.
 - Missing coords → `ValueError` → status error. No-break → warning
-  state, no fetch.
+  state, no fetch. No scored hours → warning, report disabled.
 - Custom ⭐ break works identically (same schema + coords).
 - Known limits: no tide curves (Open-Meteo has none — `idealTide` is
   qualitative only); flat 15kt wind tolerance for all spots; swell

main.py

@@ -14,6 +14,8 @@ from plotly import graph_objects as go
 DATA_PATH = Path(__file__).parent / "data" / "australia-surf-breaks-enriched.json"
 GENERATOR_PATH = Path(__file__).parent / "app" / "generate_surf_break.py"
 FORECAST_PATH = Path(__file__).parent / "app" / "surf_forecast.py"
+REPORT_PATH = Path(__file__).parent / "app" / "generate_surf_report.py"
+FAVICON_PATH = Path(__file__).parent / "assets" / "wave.svg"
 
 ALL = "All"
 
@@ -45,17 +47,30 @@ APP_CSS = """
     text-transform: lowercase;
     margin-bottom: 0 !important;
 }
-.hero-sub {
-    font-size: 1.3em !important;
-    text-transform: uppercase;
-    letter-spacing: 3px;
-    border-top: 2px dashed #0b2c5c;
-    border-bottom: 2px dashed #0b2c5c;
-    padding: 6px 0;
-}
 button, select {
     font-family: "Courier New", Courier, monospace !important;
 }
+/* primary (orange) buttons -> dark blue */
+.gradio-container {
+    --button-primary-background-fill: #0b2c5c !important;
+    --button-primary-background-fill-hover: #13407e !important;
+    --button-primary-text-color: #ffffff !important;
+    --button-primary-border-color: #0b2c5c !important;
+}
+.gradio-container button.primary,
+.gradio-container .gr-button-primary,
+button.primary, button.lg.primary {
+    background: #0b2c5c !important;
+    border-color: #0b2c5c !important;
+    color: #ffffff !important;
+}
+.gradio-container button.primary:hover,
+.gradio-container .gr-button-primary:hover,
+button.primary:hover, button.lg.primary:hover {
+    background: #13407e !important;
+    border-color: #13407e !important;
+    color: #ffffff !important;
+}
 .break-list { max-height: 210px; overflow-y: auto; border: 1px solid #0b2c5c; border-radius: 8px; padding: 4px; background: #eef6fd !important; }
 """
 
@@ -84,6 +99,18 @@ def _load_forecast():
     return module
 
 
+def _load_report():
+    """Load app/generate_surf_report.py without requiring app/ to be a package."""
+    spec = importlib.util.spec_from_file_location(
+        "surf_report_generator", REPORT_PATH
+    )
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Cannot load report generator from {REPORT_PATH}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
 def _empty_forecast_fig() -> go.Figure:
     fig = go.Figure()
     fig.add_annotation(text="No forecast data", showarrow=False, font={"size": 16})
@@ -547,43 +574,72 @@ def clear_custom_break(base_records: list[dict], selected: dict | None = None):
 def fetch_forecast(
     selected_break: dict | None,
     skill: str,
-    days: int,
     progress=gr.Progress(),
 ):
-    """Score a 1–7 day forecast for the shared ``selected_break`` (explicit button).
-
-    Deterministic only: delegates to ``app/surf_forecast.get_scored_week``
-    (Open-Meteo + deterministic scoring; stale-cache fallback lives inside
-    ``get_forecast``). No agent involved.
+    """Stage 1 — deterministic forecast only: score + build the 3 charts.
+
+    Delegates to ``app/surf_forecast.get_scored_week`` (Open-Meteo +
+    deterministic scoring) and builds score / swell / wind figs. No LLM
+    call here, so the graphs render immediately and the user can inspect
+    them before opting into Stage 2 (``generate_reports``). Yields
+    (status, best, score_fig, waves_fig, wind_fig, scored_payload,
+    telemetry) tuples. The LLM never owns numbers — it only narrates
+    these scores in Stage 2.
     """
-    empty_df = pd.DataFrame()
-    if not selected_break:
+    logs: list[str] = []
+
+    def emit(status, best_md, score_fig, waves_fig, wind_fig, payload):
         return (
+            status,
+            best_md,
+            score_fig,
+            waves_fig,
+            wind_fig,
+            payload,
+            _telemetry(logs),
+        )
+
+    if not selected_break:
+        logs.append("⚠️ No break selected — pick one in the encyclopedia tab.")
+        yield emit(
             "⚠️ Pick a break in the encyclopedia tab first.",
             "_Pick a break first._",
             _empty_forecast_fig(),
             _empty_forecast_fig(),
             _empty_forecast_fig(),
-            empty_df,
-            empty_df,
+            None,
         )
+        return
     try:
-        try:
-            days_int = max(1, min(7, int(days)))
-        except (TypeError, ValueError):
-            days_int = 7
-        progress(0.1, desc="Loading forecast module…")
+        days_int = 7
+        t0 = time.time()
+        logs.append(
+            f"🔧 [tool: get_scored_week] break='{selected_break.get('name', '?')}' "
+            f"skill='{skill}' days={days_int} (Open-Meteo marine+wind → scoring.score_week)."
+        )
+        progress(0.15, desc="Fetching + scoring forecast…")
+        yield emit(
+            "⏳ Fetching + scoring forecast…",
+            "_Scoring…_",
+            _empty_forecast_fig(),
+            _empty_forecast_fig(),
+            _empty_forecast_fig(),
+            None,
+        )
+
         mod = _load_forecast()
-        progress(0.3, desc="Fetching + scoring forecast…")
         result = mod.get_scored_week(
             selected_break, skill=skill, days=days_int
         )
         scored = result.get("scored", []) or []
-        progress(0.7, desc="Building charts…")
+        skill_used = result.get("skill", skill)
+        spot = result.get("spot", {})
+        progress(0.6, desc="Building charts…")
         score_fig = mod.build_score_fig(scored)
         waves_fig = mod.build_waves_fig(scored)
-        wind_fig = mod.build_wind_fig(scored)
+        wind_fig = mod.build_wind_fig(scored, spot)
         best = mod.best_window(scored)
+        daily = mod.daily_best(scored)
         if best:
             best_md = (
                 f"**{best.get('score')}/10 @ {best.get('time')}** — "
@@ -593,147 +649,243 @@ def fetch_forecast(
             )
         else:
             best_md = "_No scored hours in this window._"
-        daily = pd.DataFrame(mod.daily_best(scored))
-        hourly_rows = []
-        for r in scored:
-            comps = r.get("components") or {}
-            hourly_rows.append(
-                {
-                    "time": r.get("time"),
-                    "score": r.get("score"),
-                    "swell_size": comps.get("swell_size"),
-                    "swell_direction": comps.get("swell_direction"),
-                    "wind": comps.get("wind"),
-                    "period": comps.get("period"),
-                    "wave_height_m": r.get("wave_height_m"),
-                    "wave_period_s": r.get("wave_period_s"),
-                    "wind_speed_kt": r.get("wind_speed_kt"),
-                }
+        dt = time.time() - t0
+        logs.append(
+            f"📊 [tool: score_week] {len(scored)} hour(s) scored "
+            f"(skill={skill_used}, daily bests={len(daily)}) in {dt:.1f}s."
+        )
+        progress(1.0, desc="Charts ready")
+        if not scored:
+            logs.append("⚠️ No scored hours — charts are empty, report disabled.")
+            yield emit(
+                f"⚠️ {selected_break.get('name', '?')} · no scored hours ({days_int}d).",
+                best_md,
+                score_fig,
+                waves_fig,
+                wind_fig,
+                None,
             )
-        hourly = pd.DataFrame(
-            hourly_rows,
-            columns=[
-                "time",
-                "score",
-                "swell_size",
-                "swell_direction",
-                "wind",
-                "period",
-                "wave_height_m",
-                "wave_period_s",
-                "wind_speed_kt",
-            ],
+            return
+
+        logs.append(
+            "✅ Charts ready — inspect them above, then press "
+            "“Generate surf report ✨” for the write-up (one sentence per day + recommendation)."
         )
-        progress(1.0, desc="Done")
         status = (
             f"✅ {selected_break.get('name', '?')} · "
-            f"skill {result.get('skill')} · "
-            f"{len(scored)} hour(s) scored ({days_int}d)."
-        )
-        return (
-            status,
-            best_md,
-            score_fig,
-            waves_fig,
-            wind_fig,
-            daily,
-            hourly,
+            f"skill {skill_used} · "
+            f"{len(scored)} hour(s) scored ({days_int}d). "
+            f"Charts ready — generate the report when ready."
         )
+        payload = {
+            "break": selected_break,
+            "skill": skill_used,
+            "spot": spot,
+            "scored": scored,
+            "daily": daily,
+            "best": best,
+            "days": days_int,
+        }
+        yield emit(status, best_md, score_fig, waves_fig, wind_fig, payload)
     except Exception as e:  # noqa: BLE001 — surface fetch/score errors in the status box
-        return (
+        logs.append(f"❌ Forecast failed: {e}")
+        yield emit(
             f"❌ Forecast failed: {e}",
             "_Forecast failed._",
             _empty_forecast_fig(),
             _empty_forecast_fig(),
             _empty_forecast_fig(),
-            empty_df,
-            empty_df,
+            None,
+        )
+
+
+def generate_reports(
+    scored_payload: dict | None,
+    progress=gr.Progress(),
+):
+    """Stage 2 — short narrated report, streamed live as plain markdown.
+
+    Reads the ``scored_payload`` saved by :func:`fetch_forecast` and calls
+    ``app/generate_surf_report.generate_surf_report_stream`` (same
+    InferenceClient framework/model as break generation, ``stream=True``).
+    The prompt carries only the daily bests (<=7 lines) + best window, and
+    the model returns one dot-point per day (one full sentence of outlook
+    per day) plus a ``**Recommendation: ...**``
+    line — small prompt + short output keeps time-to-first-token low. Yields
+    (report_md, telemetry) tuples; the streamed text IS the report, so no
+    parse step. The LLM narrates the provided scores only.
+    """
+    logs: list[str] = []
+
+    def emit(report_md):
+        return (report_md, _telemetry(logs))
+
+    daily = (scored_payload or {}).get("daily") or []
+    if not scored_payload or not daily:
+        logs.append("⚠️ No scored forecast yet — press “Get forecast” first.")
+        yield emit("_No report yet — press “Get forecast” first._")
+        return
+
+    # Instant feedback first: this yield renders before any network wait,
+    # so the button never looks dead while the model spins up.
+    logs.append(
+        f"🔧 [tool: build_surf_report_prompt] {len(daily)} daily bests + "
+        f"best window → tiny prompt (no hourly rows)."
+    )
+    progress(0.1, desc="Contacting report model…")
+    yield emit("_Contacting report model… first words appear below as written._")
+
+    try:
+        rep = _load_report()
+        logs.append(
+            f"🧠 [tool: generate_surf_report_stream] InferenceClient "
+            f"provider='{rep.PROVIDER}' model='{rep.MODEL_ID}' "
+            f"(stream=True, temp={rep.TEMPERATURE}, max_tokens={rep.MAX_TOKENS}, "
+            f"reasoning disabled via extra_body={rep.EXTRA_BODY} + /no_think)…"
         )
+        progress(0.3, desc="Streaming surf report…")
+        yield emit("_Streaming…_")
+
+        t0 = time.time()
+        text = ""
+        chunk_count = 0
+        stream_stats: dict = {}
+        for text in rep.generate_surf_report_stream(
+            break_=scored_payload["break"],
+            skill=scored_payload["skill"],
+            daily=daily,
+            best=scored_payload.get("best"),
+            days=scored_payload.get("days", len(daily)),
+            stats=stream_stats,
+        ):
+            chunk_count += 1
+            yield emit(text + "\n\n⌨️ _streaming…_")
+        if not text.strip():
+            raise ValueError(
+                "Empty stream from report generator "
+                f"(reasoning_chars={stream_stats.get('reasoning_chars', '?')}, "
+                f"content_chars={stream_stats.get('content_chars', '?')})."
+            )
+
+        dt = time.time() - t0
+        logs.append(
+            f"✅ Done in {dt:.1f}s → {chunk_count} chunk(s), "
+            f"final report {len(text)} chars "
+            f"(content={stream_stats.get('content_chars', '?')} chars, "
+            f"hidden reasoning={stream_stats.get('reasoning_chars', '?')} chars — "
+            f"what you see above is the final report, not the thinking)."
+        )
+        progress(1.0, desc="Done")
+        yield emit(text)
+    except Exception as e:  # noqa: BLE001 — LLM failure keeps deterministic charts
+        logs.append(f"❌ Report generation failed: {e}")
+        logs.append("💡 Check HF_TOKEN is set and the inference provider serves the model.")
+        logs.append("ℹ️ Charts + best window above are deterministic and still valid.")
+        yield emit("_Report generation failed — charts above still apply._")
 
 
 def build_demo() -> gr.Blocks:
     with gr.Blocks(title="wave~reader — Australian surf encyclopaedia") as demo:
         gr.Markdown("# wave~reader", elem_classes=["hero-title"])
-        gr.Markdown("## Australian surf encyclopaedia", elem_classes=["hero-sub"])
-        gr.Markdown("filter spots, hover a dot for its name, then pick a break for details. [lo-fi edition]")
+        gr.Markdown(
+            "a guide to australiab surf breaks — browse 238 breaks on the **encyclopedia** page, "
+            "then score the week ahead + get an ai write-up on the **surf forecast** page."
+        )
         records_state = gr.State(_records(DF))
         custom_state = gr.State(None)  # one session-only break; never persisted
         selected_break = gr.State(None)  # shared pick for the forecast tab
-        with gr.Tab("encyclopedia"):
-            with gr.Row():
-                state_dd = gr.Dropdown([ALL, *STATES], value=ALL, label="State")
-                region_dd = gr.Dropdown([ALL, *ALL_REGIONS], value=ALL, label="Region")
-                skill_dd = gr.Dropdown([ALL, *SKILLS], value=ALL, label="Skill level")
-            count_md = gr.Markdown(f"**{len(DF)}** spot(s)")
-            with gr.Row():
-                with gr.Column(scale=3):
-                    map_plot = gr.Plot(build_map(_records(DF), default_view=True), label="Spots")
-                    cant_find_btn = gr.Button(
-                        "Can't find your local break?", variant="secondary"
-                    )
-                    with gr.Group(visible=False) as custom_box:
-                        gr.Markdown(
-                            "### Generate your local break\n"
-                            "One break per session, generated live via "
-                            "`app/generate_surf_break.py`. Session-only — "
-                            "never saved, deleted when your session ends."
+        scored_state = gr.State(None)  # stage-1 scored payload feeding stage-2 report
+        with gr.Tabs() as tabs:
+            with gr.Tab("encyclopedia", id="encyclopedia"):
+                gr.Markdown("### Australian surf encyclopaedia")
+                gr.Markdown("filter spots, hover a dot for its name, then pick a break for details.")
+                with gr.Row():
+                    state_dd = gr.Dropdown([ALL, *STATES], value=ALL, label="State")
+                    region_dd = gr.Dropdown([ALL, *ALL_REGIONS], value=ALL, label="Region")
+                    skill_dd = gr.Dropdown([ALL, *SKILLS], value=ALL, label="Skill level")
+                count_md = gr.Markdown(f"**{len(DF)}** spot(s)")
+                with gr.Row():
+                    with gr.Column(scale=3):
+                        map_plot = gr.Plot(build_map(_records(DF), default_view=True), label="Spots")
+                        cant_find_btn = gr.Button(
+                            "Can't find your local break?", variant="secondary"
                         )
-                        with gr.Row():
-                            custom_state_dd = gr.Dropdown(
-                                STATES, value=None, label="State"
+                        with gr.Group(visible=False) as custom_box:
+                            gr.Markdown(
+                                "### Generate your local break\n"
+                                "One break per session, generated live via "
+                                "`app/generate_surf_break.py`. Session-only — "
+                                "never saved, deleted when your session ends."
                             )
-                            custom_region_dd = gr.Dropdown(
-                                ALL_REGIONS,
-                                value=None,
-                                label="Region (or type a new one)",
-                                allow_custom_value=True,
+                            with gr.Row():
+                                custom_state_dd = gr.Dropdown(
+                                    STATES, value=None, label="State"
+                                )
+                                custom_region_dd = gr.Dropdown(
+                                    ALL_REGIONS,
+                                    value=None,
+                                    label="Region (or type a new one)",
+                                    allow_custom_value=True,
+                                )
+                            custom_name_txt = gr.Textbox(
+                                label="Break name", placeholder="e.g. Kilcunda"
                             )
-                        custom_name_txt = gr.Textbox(
-                            label="Break name", placeholder="e.g. Kilcunda"
+                            with gr.Row():
+                                generate_btn = gr.Button("Generate my break", variant="primary")
+                                clear_btn = gr.Button("Delete my break", variant="stop")
+                            telemetry_box = gr.Textbox(
+                                label="Generation telemetry (tool calls)",
+                                lines=8,
+                                max_lines=14,
+                                interactive=False,
+                                placeholder="Press “Generate my break” to see the tool-call trace…",
+                            )
+                    with gr.Column(scale=2):
+                        break_dd = gr.Radio(
+                            choices=[r.get("name", "?") for r in _records(DF)],
+                            value=None,
+                            label="Breaks (pick one for details)",
+                            elem_classes=["break-list"],
+                        )
+                        details_df = gr.Dataframe(
+                            headers=["Field", "Value"],
+                            row_count=(16, "fixed"),
+                            column_count=(2, "fixed"),
+                            label="Break details",
+                            wrap=True,
                         )
-                        with gr.Row():
-                            generate_btn = gr.Button("Generate my break", variant="primary")
-                            clear_btn = gr.Button("Delete my break", variant="stop")
-                        telemetry_box = gr.Textbox(
-                            label="Generation telemetry (tool calls)",
-                            lines=8,
-                            max_lines=14,
-                            interactive=False,
-                            placeholder="Press “Generate my break” to see the tool-call trace…",
+                        go_forecast_btn = gr.Button(
+                            "Check surf forecast →", variant="primary"
                         )
-                with gr.Column(scale=2):
-                    break_dd = gr.Radio(
-                        choices=[r.get("name", "?") for r in _records(DF)],
-                        value=None,
-                        label="Breaks (pick one for details)",
-                        elem_classes=["break-list"],
-                    )
-                    details_df = gr.Dataframe(
-                        headers=["Field", "Value"],
-                        row_count=(16, "fixed"),
-                        column_count=(2, "fixed"),
-                        label="Break details",
-                        wrap=True,
-                    )
-        with gr.Tab("surf forecast"):
-            fc_header = gr.Markdown(_NO_BREAK_HEADER)
-            with gr.Row():
+            with gr.Tab("surf forecast", id="forecast"):
+                gr.Markdown("### Surf forecast")
+                gr.Markdown(
+                    "pick a break in the encyclopedia, then press get forecast "
+                    "for scored charts + an optional ai report."
+                )
+                fc_header = gr.Markdown(_NO_BREAK_HEADER)
                 fc_skill = gr.Dropdown(
                     SKILL_ORDER, value="intermediate", label="Skill level"
                 )
-                days_slider = gr.Slider(1, 7, value=7, step=1, label="Days")
-            fetch_btn = gr.Button("Get forecast", variant="primary")
-            status_box = gr.Textbox(
-                label="Status",
-                interactive=False,
-                placeholder="Pick a break, then press “Get forecast”…",
-            )
-            best_md = gr.Markdown("_No forecast yet._")
-            score_plot = gr.Plot(label="Score")
-            waves_plot = gr.Plot(label="Swell")
-            wind_plot = gr.Plot(label="Wind")
-            daily_df = gr.Dataframe(label="Best hour each day", wrap=True)
-            hourly_df = gr.Dataframe(label="All scored hours", wrap=True)
+                fetch_btn = gr.Button("Get forecast (charts)", variant="primary")
+                status_box = gr.Textbox(
+                    label="Status",
+                    interactive=False,
+                    placeholder="Pick a break, then press “Get forecast”…",
+                )
+                best_md = gr.Markdown("_No forecast yet._")
+                score_plot = gr.Plot(label="Score (0-10)")
+                waves_plot = gr.Plot(label="Swell")
+                wind_plot = gr.Plot(label="Wind (kt)")
+                report_btn = gr.Button("Generate surf report ✨", variant="secondary")
+                report_md = gr.Markdown("_No report yet — get the forecast, then generate the report._")
+                report_telemetry_box = gr.Textbox(
+                    label="Report telemetry (tool calls)",
+                    lines=8,
+                    max_lines=14,
+                    interactive=False,
+                    placeholder="Press “Get forecast” for scoring trace, then “Generate surf report”…",
+                )
 
         def _toggle_custom_box(visible: bool):
             return gr.update(visible=not visible), not visible
@@ -780,6 +932,11 @@ def build_demo() -> gr.Blocks:
             inputs=[break_dd, records_state, custom_state],
             outputs=[details_df, selected_break, fc_header, fc_skill],
         )
+        go_forecast_btn.click(
+            lambda: gr.Tabs(selected="forecast"),
+            inputs=None,
+            outputs=[tabs],
+        )
         generate_btn.click(
             generate_custom_break,
             inputs=[
@@ -809,22 +966,30 @@ def build_demo() -> gr.Blocks:
         )
         fetch_btn.click(
             fetch_forecast,
-            inputs=[selected_break, fc_skill, days_slider],
+            inputs=[selected_break, fc_skill],
             outputs=[
                 status_box,
                 best_md,
                 score_plot,
                 waves_plot,
                 wind_plot,
-                daily_df,
-                hourly_df,
+                scored_state,
+                report_telemetry_box,
+            ],
+        )
+        report_btn.click(
+            generate_reports,
+            inputs=[scored_state],
+            outputs=[
+                report_md,
+                report_telemetry_box,
             ],
         )
     return demo
 
 
 def main():
-    build_demo().launch(css=APP_CSS)
+    build_demo().launch(css=APP_CSS, favicon_path=str(FAVICON_PATH))
 
 
 if __name__ == "__main__":