Initial commit: sidebar+cards frontend redesign

Replaces the flat markdown-table layout with a sidebar (category nav) +
main panel (benchmark cards → inline leaderboard) using gr.Radio styled
as nav buttons and cards, gr.DataFrame for the leaderboard, and a
gradient topbar with stat pills.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+dashboard_cache.json
+state.json
+watcher.log
+.superpowers/
+*.html

README.md

@@ -0,0 +1,118 @@
+# HF Leaderboard Watcher — daily email digest
+
+Polls official benchmark leaderboards on the [Hugging Face Hub](https://huggingface.co/docs/hub/leaderboard-data-guide),
+diffs against local state, and emails you a digest of new model entries.
+
+Stdlib only and packaged as a [uv single-file script](https://docs.astral.sh/uv/guides/scripts/) (PEP 723 inline metadata). uv handles the Python interpreter — no virtualenv, no `pip install`.
+
+## Files
+
+- `watch.py` — the watcher.
+- `config.json` — created on first run; fill in your SMTP details.
+- `state.json` — auto; tracks already-seen `(benchmark, model)` pairs.
+- `watcher.log` — every run appends here.
+- `cron.log` — captured stdout/stderr from cron runs.
+
+## 1. Configure SMTP
+
+Edit `config.json` (or set env vars in your crontab — see below):
+
+```json
+{
+  "smtp_host": "smtp.gmail.com",
+  "smtp_port": 465,
+  "smtp_user": "you@gmail.com",
+  "smtp_password": "<app password>",
+  "email_from": "you@gmail.com",
+  "email_to": "you@gmail.com"
+}
+```
+
+For **Gmail**, generate an App Password at
+<https://myaccount.google.com/apppasswords> (requires 2FA).
+Other SMTP providers (Fastmail, Proton Bridge, SES, Mailgun, etc.) work
+the same way — port 465 = SMTPS, anything else = STARTTLS.
+
+Test it:
+
+```sh
+~/leaderboard-watcher/watch.py --test-email
+# or explicitly:
+uv run --script ~/leaderboard-watcher/watch.py --test-email
+```
+
+## 2. Cron job (already installed)
+
+```
+0 9 * * * cd /Users/nathan/leaderboard-watcher && /Users/nathan/.cargo/bin/uv run --script watch.py >> cron.log 2>&1
+```
+
+This runs every day at **09:00** local time.
+
+> **macOS gotcha**: `cron` needs **Full Disk Access**. Go to System
+> Settings → Privacy & Security → Full Disk Access → click `+` → press
+> ⌘⇧G → enter `/usr/sbin/cron` → enable. (You already have another
+> cron job running, so this is probably already done.)
+
+Useful commands:
+
+```sh
+crontab -l                                  # see installed jobs
+crontab -e                                  # edit
+tail -f ~/leaderboard-watcher/watcher.log   # tail the run log
+tail -f ~/leaderboard-watcher/cron.log      # tail cron's stdout/stderr
+```
+
+To change cadence, edit the `0 9 * * *` part:
+- `0 9 * * 1-5` = weekdays at 9am
+- `0 9,18 * * *` = 9am and 6pm
+- `*/30 * * * *` = every 30 minutes
+
+## 3. CLI flags
+
+The shebang line (`#!/usr/bin/env -S uv run --script`) makes the file directly executable:
+
+```sh
+./watch.py                # run one cycle (what cron calls)
+./watch.py --list         # print all official benchmark IDs
+./watch.py --reset        # delete state.json (next run reseeds silently)
+./watch.py --test-email   # send a test email and exit
+```
+
+Equivalent explicit form: `uv run --script watch.py [...]`.
+
+## How it works
+
+1. `GET /api/datasets?filter=benchmark:official` to discover ~22 benchmarks.
+   (Override with `"benchmarks": ["SWE-bench/SWE-bench_Verified", "cais/hle"]` in `config.json` to watch a fixed list.)
+2. `GET /api/datasets/{id}/leaderboard` per benchmark.
+3. New `modelId`s relative to `state.json` are collected.
+4. If there are any, an HTML+text digest email is sent grouped by benchmark
+   with rank, score, verified flag, and links to each model card.
+5. State is updated so each new model is reported only once.
+
+The first run is **silent** (it just seeds state). Set
+`silent_first_run: false` if you want to receive the entire current state
+on first run instead.
+
+By default no email is sent on days with zero new entries
+(`skip_email_when_empty: true`).
+
+## Gated benchmarks
+
+`cais/hle` and similar gated datasets need an HF token. The script
+auto-uses your `~/.cache/huggingface/token` (created by `hf auth login`),
+or you can set `HF_TOKEN` in the environment. **Cron has no access to
+your shell environment**, so if you rely on env vars, set them inside the
+crontab line itself, e.g.:
+
+```cron
+0 9 * * * SMTP_PASSWORD=xxxxx HF_TOKEN=hf_yyyy cd /Users/nathan/leaderboard-watcher && /Users/nathan/.cargo/bin/uv run --script watch.py >> cron.log 2>&1
+```
+
+## Uninstall
+
+```sh
+crontab -l | grep -v leaderboard-watcher | crontab -
+rm -rf ~/leaderboard-watcher
+```

app.py

@@ -0,0 +1,594 @@
+#!/usr/bin/env python3
+"""
+HF Hub Benchmark Dashboard — Gradio app.
+Run: python app.py
+"""
+
+import json
+import urllib.request
+import urllib.error
+from collections import defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+import gradio as gr
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+ROOT = Path(__file__).resolve().parent
+CACHE_PATH = ROOT / "dashboard_cache.json"
+CACHE_TTL_SECONDS = 6 * 60 * 60  # 6 hours
+
+CATEGORY_ORDER = [
+    "Knowledge",
+    "Math / Reasoning",
+    "Code / Engineering",
+    "Agents",
+    "Vision",
+    "Audio / Speech",
+    "Document / OCR",
+    "Retrieval / Embedding",
+    "NLP / Classification",
+    "Robotics",
+    "Other",
+]
+
+CATEGORY_ICONS = {
+    "Knowledge": "🧠",
+    "Math / Reasoning": "🔢",
+    "Code / Engineering": "💻",
+    "Agents": "🤖",
+    "Vision": "👁️",
+    "Audio / Speech": "🔊",
+    "Document / OCR": "📄",
+    "Retrieval / Embedding": "🔎",
+    "NLP / Classification": "🏷️",
+    "Robotics": "🦾",
+    "Other": "📦",
+}
+
+BENCHMARK_DISPLAY_NAMES = {
+    "openai/gsm8k": "GSM8K",
+    "Idavidrein/gpqa": "GPQA",
+    "allenai/olmOCR-bench": "olmOCR-Bench",
+    "llamaindex/ParseBench": "ParseBench",
+    "mercor/apex-agents": "APEX-Agents",
+    "harborframework/terminal-bench-2.0": "Terminal-Bench 2.0",
+    "SWE-bench/SWE-bench_Verified": "SWE-bench Verified",
+    "TIGER-Lab/MMLU-Pro": "MMLU-Pro",
+    "hf-audio/open-asr-leaderboard": "Open ASR Leaderboard",
+    "MathArena/aime_2026": "AIME 2026",
+    "claw-eval/Claw-Eval": "Claw-Eval",
+    "cais/hle": "HLE",
+    "likaixin/ScreenSpot-Pro": "ScreenSpot-Pro",
+    "nvidia/compute-eval": "ComputeEval",
+    "ScaleAI/SWE-bench_Pro": "SWE-bench Pro",
+    "FutureMa/EvasionBench": "EvasionBench",
+    "mteb/BRIGHT": "BRIGHT",
+    "Delores-Lin/MDPBench": "MDPBench",
+    "mteb/arguana": "ArguAna",
+    "MMMU/MMMU_Pro": "MMMU-Pro",
+    "LEXam-Benchmark/LEXam": "LEXam",
+    "mercor/ACE": "ACE",
+    "mercor/APEX-v1-extended": "APEX-v1",
+    "VLABench/vlabench_primitive_ft_lerobot_video": "VLABench",
+    "tiiuae/PBench": "PBench",
+    "MathArena/hmmt_feb_2026": "HMMT Feb 2026",
+    "collinear-ai/yc-bench": "YC-Bench",
+    "internlm/WildClawBench": "WildClawBench",
+    "MME-Benchmarks/Video-MME-v2": "Video-MME v2",
+    "open-agent-leaderboard/results": "Open Agent Leaderboard",
+}
+
+CUSTOM_CSS = """
+/* ---- Topbar ---- */
+.topbar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+    color: white;
+    padding: 14px 24px;
+    border-radius: 10px;
+    margin-bottom: 8px;
+    flex-wrap: wrap;
+    gap: 12px;
+}
+.topbar-title { font-size: 18px; font-weight: 700; margin-bottom: 2px; }
+.topbar-meta { font-size: 11px; opacity: 0.85; }
+.topbar-pills { display: flex; gap: 8px; flex-wrap: wrap; }
+.stat-pill {
+    background: rgba(255,255,255,0.2);
+    border-radius: 20px;
+    padding: 4px 14px;
+    font-size: 12px;
+    white-space: nowrap;
+}
+.stat-pill b { font-size: 14px; }
+
+/* ---- Sidebar column ---- */
+#sidebar-col {
+    background: white !important;
+    border-right: 1px solid #e5e7eb !important;
+    padding: 12px 0 !important;
+    border-radius: 10px 0 0 10px !important;
+}
+#sidebar-col > .form { background: transparent !important; box-shadow: none !important; border: none !important; }
+
+/* ---- Sidebar Radio → nav buttons ---- */
+#cat_radio {
+    background: transparent !important;
+    border: none !important;
+    box-shadow: none !important;
+    padding: 0 !important;
+}
+#cat_radio > .wrap {
+    flex-direction: column !important;
+    gap: 0 !important;
+    padding: 0 !important;
+}
+#cat_radio label {
+    display: flex !important;
+    align-items: center !important;
+    padding: 9px 16px !important;
+    margin: 0 !important;
+    border-left: 3px solid transparent !important;
+    border-radius: 0 !important;
+    cursor: pointer !important;
+    font-size: 13px !important;
+    color: #374151 !important;
+    background: white !important;
+    width: 100% !important;
+    box-sizing: border-box !important;
+    gap: 0 !important;
+}
+#cat_radio label:hover { background: #f3f4f6 !important; }
+#cat_radio label:has(input:checked) {
+    background: #ede9fe !important;
+    border-left-color: #7c3aed !important;
+    color: #5b21b6 !important;
+    font-weight: 600 !important;
+}
+#cat_radio input[type="radio"] { display: none !important; }
+#cat_radio .wrap span { margin-left: 0 !important; padding-left: 0 !important; }
+
+/* ---- Main column ---- */
+#main-col {
+    background: #f9fafb !important;
+    border-radius: 0 10px 10px 0 !important;
+    padding: 16px 20px !important;
+}
+#main-col > .form { background: transparent !important; box-shadow: none !important; border: none !important; }
+
+/* ---- Benchmark card Radio ---- */
+#bench_radio {
+    background: transparent !important;
+    border: none !important;
+    box-shadow: none !important;
+    padding: 0 !important;
+}
+#bench_radio > .wrap {
+    flex-direction: row !important;
+    flex-wrap: wrap !important;
+    gap: 10px !important;
+    padding: 4px 0 12px !important;
+}
+#bench_radio label {
+    display: flex !important;
+    align-items: center !important;
+    padding: 10px 14px !important;
+    border: 2px solid #e5e7eb !important;
+    border-radius: 10px !important;
+    cursor: pointer !important;
+    font-size: 12px !important;
+    background: white !important;
+    color: #374151 !important;
+    min-width: 150px !important;
+    margin: 0 !important;
+    gap: 0 !important;
+    transition: border-color 0.15s !important;
+}
+#bench_radio label:hover { border-color: #a78bfa !important; }
+#bench_radio label:has(input:checked) {
+    border-color: #7c3aed !important;
+    background: #faf5ff !important;
+    font-weight: 600 !important;
+    color: #5b21b6 !important;
+}
+#bench_radio input[type="radio"] { display: none !important; }
+#bench_radio .wrap span { margin-left: 0 !important; padding-left: 0 !important; }
+"""
+
+# ---------------------------------------------------------------------------
+# HF API helpers
+# ---------------------------------------------------------------------------
+
+
+def _http_get_json(url: str, token: str | None = None, timeout: int = 30):
+    req = urllib.request.Request(url, headers={"Accept": "application/json"})
+    if token:
+        req.add_header("Authorization", f"Bearer {token}")
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def _read_token() -> str | None:
+    import os
+    p = Path(os.path.expanduser("~/.cache/huggingface/token"))
+    if p.exists():
+        tok = p.read_text().strip()
+        if tok:
+            return tok
+    return os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+
+
+def discover_benchmarks(token=None) -> list[dict]:
+    url = "https://huggingface.co/api/datasets?filter=benchmark:official&limit=1000"
+    data = _http_get_json(url, token, timeout=30)
+    results = []
+    for d in data:
+        if not isinstance(d, dict) or "id" not in d:
+            continue
+        results.append({
+            "id": d["id"],
+            "tags": d.get("tags", []),
+            "description": (d.get("description") or "")[:200],
+        })
+    return results
+
+
+def get_leaderboard(dataset_id: str, token=None) -> list[dict]:
+    url = f"https://huggingface.co/api/datasets/{dataset_id}/leaderboard"
+    try:
+        data = _http_get_json(url, token, timeout=30)
+    except (urllib.error.HTTPError, urllib.error.URLError):
+        return []
+    if isinstance(data, dict) and "entries" in data:
+        data = data["entries"]
+    return data if isinstance(data, list) else []
+
+
+# ---------------------------------------------------------------------------
+# Categorisation
+# ---------------------------------------------------------------------------
+
+
+def categorize_benchmark(bench: dict) -> list[str]:
+    tags = bench.get("tags", [])
+    bid = bench["id"]
+    bid_lower = bid.lower()
+    categories = set()
+
+    if any(t in tags for t in ["modality:audio", "modality:speech"]):
+        categories.add("Audio / Speech")
+    if any(t in tags for t in ["modality:image", "modality:video"]):
+        categories.add("Vision")
+    if any(t in tags for t in ["modality:document"]):
+        categories.add("Document / OCR")
+    if any(t in tags for t in ["task_categories:robotics"]):
+        categories.add("Robotics")
+    if any(t in tags for t in ["task_categories:text-retrieval"]):
+        categories.add("Retrieval / Embedding")
+
+    if "math" in bid_lower or "aime" in bid_lower or "hmmt" in bid_lower or "gsm8k" in bid_lower:
+        categories.add("Math / Reasoning")
+    if "swe" in bid_lower or "terminal" in bid_lower or "compute-eval" in bid_lower:
+        categories.add("Code / Engineering")
+    if "agent" in bid_lower or "claw" in bid_lower or "apex-agent" in bid_lower or "wildclaw" in bid_lower or "yc-bench" in bid_lower:
+        categories.add("Agents")
+    if "mmlu" in bid_lower or "gpqa" in bid_lower or "hle" in bid_lower:
+        categories.add("Knowledge")
+    if "ocr" in bid_lower or "parse" in bid_lower or "mdp" in bid_lower:
+        categories.add("Document / OCR")
+    if "asr" in bid_lower:
+        categories.add("Audio / Speech")
+    if "screen" in bid_lower or "mmmu" in bid_lower or "video" in bid_lower or "pbench" in bid_lower:
+        categories.add("Vision")
+    if "evasion" in bid_lower or "lex" in bid_lower:
+        categories.add("NLP / Classification")
+    if "bright" in bid_lower or "arguana" in bid_lower:
+        categories.add("Retrieval / Embedding")
+
+    if not categories:
+        categories.add("Other")
+
+    return sorted(categories, key=lambda c: CATEGORY_ORDER.index(c) if c in CATEGORY_ORDER else 99)
+
+
+# ---------------------------------------------------------------------------
+# Data fetching & aggregation
+# ---------------------------------------------------------------------------
+
+
+def fetch_all_data() -> dict:
+    token = _read_token()
+    benchmarks = discover_benchmarks(token)
+    all_models: set[str] = set()
+    benchmark_data = []
+
+    for bench in benchmarks:
+        bid = bench["id"]
+        entries = get_leaderboard(bid, token)
+        models: set[str] = set()
+        model_details = []
+        for entry in entries:
+            mid = entry.get("modelId") or entry.get("model_id") or entry.get("model") or ""
+            if not mid:
+                continue
+            models.add(mid)
+            model_details.append({
+                "rank": entry.get("rank"),
+                "model_id": mid,
+                "value": entry.get("value"),
+                "verified": entry.get("verified", False),
+            })
+
+        model_details.sort(key=lambda x: (x["rank"] is None, x["rank"] or 999))
+        all_models.update(models)
+        cats = categorize_benchmark(bench)
+        display_name = BENCHMARK_DISPLAY_NAMES.get(bid, bid.split("/")[-1])
+
+        benchmark_data.append({
+            "id": bid,
+            "display_name": display_name,
+            "categories": cats,
+            "num_models": len(models),
+            "models": sorted(models),
+            "model_details": model_details,
+            "description": bench["description"],
+        })
+
+    cat_benchmarks: dict[str, list] = defaultdict(list)
+    cat_models: dict[str, set] = defaultdict(set)
+    for bd in benchmark_data:
+        for cat in bd["categories"]:
+            cat_benchmarks[cat].append(bd)
+            cat_models[cat].update(bd["models"])
+
+    return {
+        "total_benchmarks": len(benchmarks),
+        "total_unique_models": len(all_models),
+        "benchmarks_with_entries": sum(1 for bd in benchmark_data if bd["num_models"] > 0),
+        "benchmarks_empty": sum(1 for bd in benchmark_data if bd["num_models"] == 0),
+        "timestamp": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "all_models": sorted(all_models),
+        "benchmark_data": benchmark_data,
+        "categories": {
+            cat: {
+                "benchmarks": len(cat_benchmarks[cat]),
+                "unique_models": len(cat_models[cat]),
+            }
+            for cat in CATEGORY_ORDER
+            if cat in cat_benchmarks
+        },
+    }
+
+
+def load_cached_data() -> dict | None:
+    if not CACHE_PATH.exists():
+        return None
+    try:
+        d = json.loads(CACHE_PATH.read_text())
+        ts = d.get("timestamp", "")
+        if ts:
+            age = (datetime.now(timezone.utc) - datetime.fromisoformat(ts)).total_seconds()
+            if age < CACHE_TTL_SECONDS:
+                return d
+    except Exception:
+        pass
+    return None
+
+
+def save_cache(data: dict) -> None:
+    CACHE_PATH.write_text(json.dumps(data, indent=2))
+
+
+# ---------------------------------------------------------------------------
+# UI helpers
+# ---------------------------------------------------------------------------
+
+_app_data: dict = {}
+
+
+def _render_topbar(data: dict) -> str:
+    ts = data.get("timestamp", "?")[:19]
+    return (
+        f'<div class="topbar">'
+        f'<div><div class="topbar-title">🏆 HF Hub Benchmark Dashboard</div>'
+        f'<div class="topbar-meta">Last updated: {ts} UTC · auto-refreshes every 6h</div></div>'
+        f'<div class="topbar-pills">'
+        f'<div class="stat-pill"><b>{data["total_benchmarks"]}</b> benchmarks</div>'
+        f'<div class="stat-pill"><b>{data["total_unique_models"]}</b> models</div>'
+        f'<div class="stat-pill"><b>{data["benchmarks_with_entries"]}</b> active</div>'
+        f'<div class="stat-pill"><b>{data["benchmarks_empty"]}</b> empty</div>'
+        f'</div></div>'
+    )
+
+
+def _sidebar_choices(data: dict) -> list[tuple[str, str]]:
+    cats = data.get("categories", {})
+    result = []
+    for cat in CATEGORY_ORDER:
+        if cat not in cats:
+            continue
+        icon = CATEGORY_ICONS.get(cat, "")
+        count = cats[cat]["benchmarks"]
+        result.append((f"{icon} {cat}  ({count})", cat))
+    return result
+
+
+def _card_choices(data: dict, category: str) -> list[tuple[str, str]]:
+    bds = [bd for bd in data["benchmark_data"] if category in bd["categories"]]
+    bds.sort(key=lambda x: x["num_models"], reverse=True)
+    choices = []
+    for bd in bds:
+        owner = bd["id"].split("/")[0] if "/" in bd["id"] else ""
+        label = f"{bd['display_name']} · {bd['num_models']} models"
+        if owner:
+            label += f"  [{owner}]"
+        choices.append((label, bd["id"]))
+    return choices
+
+
+def _lb_rows(data: dict, bid: str) -> list[list]:
+    lookup = {bd["id"]: bd for bd in data["benchmark_data"]}
+    details = lookup.get(bid, {}).get("model_details", [])[:50]
+    return [
+        [
+            m["rank"] if m["rank"] is not None else "—",
+            m["model_id"],
+            str(m["value"]) if m["value"] is not None else "—",
+            "✅" if m["verified"] else "",
+        ]
+        for m in details
+    ]
+
+
+def _cat_header(data: dict, cat: str) -> str:
+    icon = CATEGORY_ICONS.get(cat, "")
+    info = data.get("categories", {}).get(cat, {})
+    return f"### {icon} {cat} &nbsp;·&nbsp; {info.get('benchmarks', 0)} benchmarks · {info.get('unique_models', 0)} models"
+
+
+# ---------------------------------------------------------------------------
+# Gradio app
+# ---------------------------------------------------------------------------
+
+
+def build_app() -> gr.Blocks:
+    global _app_data
+    _app_data = load_cached_data()
+    if _app_data is None:
+        _app_data = fetch_all_data()
+        save_cache(_app_data)
+
+    s_choices = _sidebar_choices(_app_data)
+    init_cat = s_choices[0][1] if s_choices else ""
+    c_choices = _card_choices(_app_data, init_cat)
+    init_bid = c_choices[0][1] if c_choices else ""
+
+    with gr.Blocks(
+        title="HF Hub Benchmark Dashboard",
+        css=CUSTOM_CSS,
+        theme=gr.themes.Soft(),
+    ) as demo:
+
+        topbar = gr.HTML(_render_topbar(_app_data))
+
+        with gr.Row(equal_height=True):
+            # --- Sidebar ---
+            with gr.Column(scale=1, min_width=210, elem_id="sidebar-col"):
+                cat_radio = gr.Radio(
+                    choices=s_choices,
+                    value=init_cat,
+                    label="Categories",
+                    elem_id="cat_radio",
+                )
+
+            # --- Main panel ---
+            with gr.Column(scale=4, elem_id="main-col"):
+                with gr.Row():
+                    cat_header = gr.Markdown(
+                        _cat_header(_app_data, init_cat),
+                        elem_id="cat-header",
+                    )
+                    refresh_btn = gr.Button(
+                        "🔄 Refresh Now", variant="primary", scale=0, min_width=150,
+                    )
+
+                bench_radio = gr.Radio(
+                    choices=c_choices,
+                    value=init_bid,
+                    show_label=False,
+                    elem_id="bench_radio",
+                )
+
+                lb_df = gr.DataFrame(
+                    value=_lb_rows(_app_data, init_bid),
+                    headers=["Rank", "Model", "Score", "Verified"],
+                    col_count=(4, "fixed"),
+                    interactive=False,
+                    wrap=True,
+                )
+
+                lb_link = gr.Markdown(
+                    f"[↗ View on Hub](https://huggingface.co/datasets/{init_bid})"
+                    if init_bid else ""
+                )
+
+        # ---- Event handlers ----
+
+        def on_category_change(cat: str):
+            new_c = _card_choices(_app_data, cat)
+            new_bid = new_c[0][1] if new_c else ""
+            return (
+                _cat_header(_app_data, cat),
+                gr.update(choices=new_c, value=new_bid),
+                _lb_rows(_app_data, new_bid),
+                f"[↗ View on Hub](https://huggingface.co/datasets/{new_bid})" if new_bid else "",
+            )
+
+        def on_benchmark_change(bid: str):
+            if not bid:
+                return [], ""
+            return (
+                _lb_rows(_app_data, bid),
+                f"[↗ View on Hub](https://huggingface.co/datasets/{bid})",
+            )
+
+        def on_refresh():
+            global _app_data
+            try:
+                new_data = fetch_all_data()
+                save_cache(new_data)
+                _app_data = new_data
+            except Exception as e:
+                err = f'<p style="color:#dc2626;font-size:12px;margin-top:4px">⚠️ Refresh failed: {e}</p>'
+                return (
+                    _render_topbar(_app_data) + err,
+                    gr.update(), gr.update(), gr.update(), gr.update(), gr.update(),
+                )
+
+            new_s = _sidebar_choices(_app_data)
+            new_cat = new_s[0][1] if new_s else ""
+            new_c = _card_choices(_app_data, new_cat)
+            new_bid = new_c[0][1] if new_c else ""
+            return (
+                _render_topbar(_app_data),
+                gr.update(choices=new_s, value=new_cat),
+                _cat_header(_app_data, new_cat),
+                gr.update(choices=new_c, value=new_bid),
+                _lb_rows(_app_data, new_bid),
+                f"[↗ View on Hub](https://huggingface.co/datasets/{new_bid})" if new_bid else "",
+            )
+
+        cat_radio.change(
+            fn=on_category_change,
+            inputs=cat_radio,
+            outputs=[cat_header, bench_radio, lb_df, lb_link],
+        )
+
+        bench_radio.change(
+            fn=on_benchmark_change,
+            inputs=bench_radio,
+            outputs=[lb_df, lb_link],
+        )
+
+        refresh_btn.click(
+            fn=on_refresh,
+            inputs=[],
+            outputs=[topbar, cat_radio, cat_header, bench_radio, lb_df, lb_link],
+            show_progress="full",
+        )
+
+    return demo
+
+
+if __name__ == "__main__":
+    demo = build_app()
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7861,
+    )

config.json

@@ -0,0 +1,14 @@
+{
+  "benchmarks": [],
+  "email_from": "",
+  "email_to": "",
+  "hf_token_path": "~/.cache/huggingface/token",
+  "request_delay_seconds": 0.3,
+  "silent_first_run": true,
+  "skip_email_when_empty": true,
+  "smtp_host": "smtp.gmail.com",
+  "smtp_password": "",
+  "smtp_port": 465,
+  "smtp_user": "",
+  "timeout": 30
+}

docs/superpowers/specs/2026-06-01-dashboard-frontend-redesign.md

@@ -0,0 +1,126 @@
+# Dashboard Frontend Redesign
+
+**Date:** 2026-06-01  
+**Scope:** `app.py` — UI layer only. Data fetching, caching, and categorisation logic are unchanged.
+
+---
+
+## Goal
+
+Replace the current single-scroll page of markdown tables with a sidebar + main-panel layout that makes the dashboard faster to navigate and easier to read.
+
+---
+
+## Layout
+
+```
+┌─────────────────────────────────────────────────────┐
+│  TOPBAR: title · stat pills · last-updated          │
+├──────────────┬──────────────────────────────────────┤
+│  SIDEBAR     │  MAIN PANEL                          │
+│  (180px)     │  header: category name + model count │
+│              │  + Refresh Now button                │
+│  Categories  │                                      │
+│  as buttons  │  Benchmark cards (chips)             │
+│              │                                      │
+│              │  ────────────────────────────────    │
+│              │  Inline leaderboard (gr.DataFrame)   │
+└──────────────┴──────────────────────────────────────┘
+```
+
+The sidebar is fixed-width (180 px). The main panel scrolls independently.
+
+---
+
+## Components
+
+### Top bar
+- `gr.HTML` block rendering a gradient bar with:
+  - App title ("🏆 HF Hub Benchmark Dashboard")
+  - Four stat pills: total benchmarks, unique models, active count, empty count
+  - Last-updated timestamp
+
+### Sidebar
+- `gr.Radio` component with `choices` built from `CATEGORY_ORDER` (icon + name + count)
+- `show_label=False`, `container=False` so it renders as a bare list
+- CSS hides the radio circle and styles each item as a full-width button with left-border active state
+- `.change()` event updates `selected_category` state
+
+### Main panel header
+- `gr.Markdown` showing the selected category name, icon, and unique model count
+- `gr.Button` ("🔄 Refresh Now") aligned right via `gr.Row`
+
+### Benchmark cards
+- `gr.Radio` component with `choices` built from the benchmarks in the selected category
+- Each choice label includes display name, model count, and dataset owner badge (rendered via `gr.Radio` label HTML)
+- CSS styles items as flex cards with purple border on selection
+- `.change()` event updates `selected_benchmark_id` state
+
+### Leaderboard table
+- `gr.DataFrame` populated from `model_details` of the selected benchmark
+- Columns: Rank, Model (plain string, not hyperlink — gr.DataFrame limitation), Score, Verified
+- Sortable by clicking column headers (built-in gr.DataFrame behaviour)
+- Shows up to 50 rows (same limit as current app)
+- Below the table: `gr.Markdown` with a "↗ View on Hub" link to the dataset page
+
+---
+
+## State
+
+Two `gr.State` values:
+
+| State | Type | Initial value |
+|---|---|---|
+| `selected_category` | `str` | First category that has benchmarks |
+| `selected_benchmark_id` | `str` | ID of the benchmark with the most models in the initial category |
+
+Both are updated by click handlers on sidebar buttons and benchmark cards.
+
+---
+
+## Event wiring
+
+```
+sidebar Radio.change  →  update selected_category state
+                      →  update main header Markdown (category name + model count)
+                      →  update benchmark cards Radio choices + default value
+                      →  update leaderboard DataFrame + Hub link Markdown
+
+cards Radio.change    →  update selected_benchmark_id state
+                      →  update leaderboard DataFrame + Hub link Markdown
+```
+
+The refresh button clears both state values back to defaults after fetching new data, then re-renders all outputs (same outputs list as today).
+
+---
+
+## CSS / Styling
+
+Custom CSS injected via `demo.launch(css=...)`. Key rules:
+
+- Topbar: `linear-gradient(135deg, #667eea 0%, #764ba2 100%)`
+- Active sidebar item: `border-left: 3px solid #7c3aed; background: #ede9fe; color: #5b21b6`
+- Selected benchmark card: `border: 2px solid #7c3aed; background: #faf5ff`
+- Table rows: subtle hover tint `#faf5ff`
+- Rank column: plain numbers, no per-cell colouring (gr.DataFrame does not support per-cell CSS)
+
+---
+
+## What is NOT changing
+
+- `fetch_all_data()`, `load_cached_data()`, `save_cache()` — untouched
+- `discover_benchmarks()`, `get_leaderboard()`, `categorize_benchmark()` — untouched
+- Cache TTL, cache file location — untouched
+- `BENCHMARK_DISPLAY_NAMES`, `CATEGORY_ORDER`, `CATEGORY_ICONS` — untouched
+- `demo.launch()` call (not switching to `gr.Server`)
+
+---
+
+## File structure
+
+All changes are in `app.py`. No new files needed.
+
+- Remove: `render_top_bar`, `render_stat_cards`, `render_category_table`, `render_benchmark_table`, `render_benchmark_detail`, `render_top_models` (all replaced by new helpers)
+- Add: `render_topbar_html`, `sidebar_choices`, `card_choices`, `render_lb_link_md`
+- The "Most-Benchmarked Models" section from the current app is removed — model counts are visible in the leaderboard table
+- `build_app()` is rewritten; data-layer functions above it are untouched

requirements.txt

@@ -0,0 +1 @@
+gradio>=5.0.0

test_watch.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Tests for leaderboard watcher — first_seen tracking."""
+
+import json
+import sys
+import tempfile
+import unittest
+from datetime import datetime, timezone
+from pathlib import Path
+from unittest.mock import patch
+
+# Make watch.py importable without executing main()
+sys.path.insert(0, str(Path(__file__).parent))
+import watch
+
+NOW = datetime(2026, 4, 30, 12, 0, 0, tzinfo=timezone.utc)
+NOW_ISO = "2026-04-30T12:00:00+00:00"
+
+
+class TestMigrateSeen(unittest.TestCase):
+    def test_list_migrates_to_dict_with_none_timestamps(self):
+        old = ["modelA", "modelB"]
+        result = watch.migrate_seen(old)
+        self.assertEqual(result, {"modelA": None, "modelB": None})
+
+    def test_dict_is_returned_unchanged(self):
+        existing = {"modelA": "2026-01-01T00:00:00+00:00", "modelB": None}
+        result = watch.migrate_seen(existing)
+        self.assertEqual(result, existing)
+
+    def test_empty_list_migrates_to_empty_dict(self):
+        self.assertEqual(watch.migrate_seen([]), {})
+
+    def test_empty_dict_returned_unchanged(self):
+        self.assertEqual(watch.migrate_seen({}), {})
+
+
+class TestDiffModels(unittest.TestCase):
+    def test_new_models_get_current_timestamp(self):
+        seen = {"old-model": "2026-01-01T00:00:00+00:00"}
+        current = ["old-model", "new-model"]
+        new_ids, updated_seen = watch.diff_models(seen, current, NOW)
+        self.assertEqual(new_ids, ["new-model"])
+        self.assertEqual(updated_seen["new-model"], NOW_ISO)
+
+    def test_existing_models_keep_their_timestamp(self):
+        original_ts = "2026-01-01T00:00:00+00:00"
+        seen = {"old-model": original_ts}
+        current = ["old-model"]
+        _, updated_seen = watch.diff_models(seen, current, NOW)
+        self.assertEqual(updated_seen["old-model"], original_ts)
+
+    def test_existing_model_with_none_timestamp_stays_none(self):
+        seen = {"old-model": None}
+        current = ["old-model"]
+        _, updated_seen = watch.diff_models(seen, current, NOW)
+        self.assertIsNone(updated_seen["old-model"])
+
+    def test_no_new_models_returns_empty_list(self):
+        seen = {"a": NOW_ISO, "b": NOW_ISO}
+        current = ["a", "b"]
+        new_ids, _ = watch.diff_models(seen, current, NOW)
+        self.assertEqual(new_ids, [])
+
+    def test_all_models_new_when_seen_is_empty(self):
+        current = ["x", "y"]
+        new_ids, updated_seen = watch.diff_models({}, current, NOW)
+        self.assertEqual(sorted(new_ids), ["x", "y"])
+        self.assertEqual(updated_seen["x"], NOW_ISO)
+        self.assertEqual(updated_seen["y"], NOW_ISO)
+
+    def test_models_removed_from_leaderboard_are_retained_in_seen(self):
+        seen = {"gone": "2026-01-01T00:00:00+00:00", "still-here": "2026-01-01T00:00:00+00:00"}
+        current = ["still-here"]
+        _, updated_seen = watch.diff_models(seen, current, NOW)
+        self.assertIn("gone", updated_seen)
+        self.assertIn("still-here", updated_seen)
+
+
+class TestStateRoundtrip(unittest.TestCase):
+    def test_state_saved_and_loaded_preserves_first_seen(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "state.json"
+            data = {
+                "some/dataset": {
+                    "seen": {"modelA": NOW_ISO, "modelB": None},
+                    "last_checked": NOW_ISO,
+                    "count": 2,
+                }
+            }
+            watch.save_json(path, data)
+            loaded = watch.load_json(path, {})
+            self.assertEqual(loaded["some/dataset"]["seen"]["modelA"], NOW_ISO)
+            self.assertIsNone(loaded["some/dataset"]["seen"]["modelB"])
+
+    def test_old_state_with_list_seen_is_migrated_on_load(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "state.json"
+            old_state = {
+                "some/dataset": {
+                    "seen": ["modelA", "modelB"],
+                    "last_checked": "2026-04-29T00:00:00+00:00",
+                    "count": 2,
+                }
+            }
+            path.write_text(json.dumps(old_state))
+            loaded = watch.load_json(path, {})
+            # Migration happens in run_once, not load_json — test the migration utility
+            ds_state = loaded["some/dataset"]
+            migrated = watch.migrate_seen(ds_state["seen"])
+            self.assertIsInstance(migrated, dict)
+            self.assertIsNone(migrated["modelA"])
+            self.assertIsNone(migrated["modelB"])
+
+
+if __name__ == "__main__":
+    unittest.main()

watch.py

@@ -0,0 +1,409 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""
+HF Hub leaderboard watcher — daily email digest.
+
+Run directly via the shebang (`./watch.py`) or `uv run --script watch.py`.
+uv will provision an isolated Python interpreter automatically; no
+`pip install` and no virtualenv to manage.
+
+Polls official benchmark leaderboards on the Hugging Face Hub, diffs against
+local state, and emails a digest of new model entries since the last run.
+
+Designed to be run once per day from cron.
+
+Docs: https://huggingface.co/docs/hub/leaderboard-data-guide
+
+Configuration: edit `config.json` (next to this script) or set the SMTP
+credentials via env vars: SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD,
+EMAIL_FROM, EMAIL_TO.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import smtplib
+import ssl
+import sys
+import time
+import urllib.error
+import urllib.request
+from datetime import datetime, timezone
+from email.message import EmailMessage
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+CONFIG_PATH = ROOT / "config.json"
+STATE_PATH = ROOT / "state.json"
+LOG_PATH = ROOT / "watcher.log"
+
+DEFAULT_CONFIG = {
+    # If empty, auto-discover all official benchmarks. Otherwise pin a list.
+    "benchmarks": [],
+
+    # SMTP settings — override with env vars (SMTP_HOST etc.) if you prefer.
+    # For Gmail: host=smtp.gmail.com, port=465, user=you@gmail.com,
+    #            password=<App Password from https://myaccount.google.com/apppasswords>.
+    "smtp_host": "smtp.gmail.com",
+    "smtp_port": 465,
+    "smtp_user": "",
+    "smtp_password": "",
+    "email_from": "",
+    "email_to": "",
+
+    # Don't send an email if there are zero new entries.
+    "skip_email_when_empty": True,
+
+    # Path to your HF token (used for gated benchmarks). Optional.
+    "hf_token_path": "~/.cache/huggingface/token",
+
+    # First run only seeds state silently — no flood email.
+    "silent_first_run": True,
+
+    "timeout": 30,
+    "request_delay_seconds": 0.3,
+}
+
+
+# ---------- utilities ----------
+
+def log(msg: str) -> None:
+    line = f"[{datetime.now(timezone.utc).isoformat(timespec='seconds')}] {msg}"
+    print(line, flush=True)
+    try:
+        with LOG_PATH.open("a") as f:
+            f.write(line + "\n")
+    except OSError:
+        pass
+
+
+def load_json(path: Path, default):
+    if not path.exists():
+        return default
+    try:
+        return json.loads(path.read_text())
+    except json.JSONDecodeError:
+        log(f"WARN: corrupt JSON at {path}, ignoring")
+        return default
+
+
+def save_json(path: Path, data) -> None:
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(data, indent=2, sort_keys=True))
+    tmp.replace(path)
+
+
+def load_config() -> dict:
+    if not CONFIG_PATH.exists():
+        save_json(CONFIG_PATH, DEFAULT_CONFIG)
+    cfg = dict(DEFAULT_CONFIG)
+    cfg.update(load_json(CONFIG_PATH, {}))
+    # Env var overrides for secrets / portability.
+    env_map = {
+        "smtp_host": "SMTP_HOST",
+        "smtp_port": "SMTP_PORT",
+        "smtp_user": "SMTP_USER",
+        "smtp_password": "SMTP_PASSWORD",
+        "email_from": "EMAIL_FROM",
+        "email_to": "EMAIL_TO",
+    }
+    for key, env in env_map.items():
+        if os.environ.get(env):
+            cfg[key] = os.environ[env]
+    cfg["smtp_port"] = int(cfg["smtp_port"])
+    return cfg
+
+
+def read_token(cfg: dict) -> str | None:
+    p = cfg.get("hf_token_path", "")
+    if p:
+        path = Path(os.path.expanduser(p))
+        if path.exists():
+            tok = path.read_text().strip()
+            if tok:
+                return tok
+    return os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+
+
+def http_get_json(url: str, token: str | None, timeout: int):
+    req = urllib.request.Request(url, headers={"Accept": "application/json"})
+    if token:
+        req.add_header("Authorization", f"Bearer {token}")
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+# ---------- HF API ----------
+
+def discover_official_benchmarks(token, timeout):
+    url = "https://huggingface.co/api/datasets?filter=benchmark:official&limit=1000"
+    data = http_get_json(url, token, timeout)
+    return [d["id"] for d in data if isinstance(d, dict) and "id" in d]
+
+
+def get_leaderboard(dataset_id, token, timeout):
+    url = f"https://huggingface.co/api/datasets/{dataset_id}/leaderboard"
+    data = http_get_json(url, token, timeout)
+    if isinstance(data, dict) and "entries" in data:
+        data = data["entries"]
+    return data if isinstance(data, list) else []
+
+
+# ---------- email ----------
+
+def render_digest(new_by_ds: dict[str, list[dict]]) -> tuple[str, str]:
+    """Return (plain_text, html) bodies."""
+    today = datetime.now().strftime("%Y-%m-%d")
+    total = sum(len(v) for v in new_by_ds.values())
+
+    # Plain text
+    lines = [f"HF Leaderboard digest — {today}", f"{total} new model entr{'y' if total == 1 else 'ies'} across {len(new_by_ds)} benchmark(s).", ""]
+    for ds, entries in sorted(new_by_ds.items()):
+        lines.append(f"### {ds}  ({len(entries)} new)")
+        lines.append(f"https://huggingface.co/datasets/{ds}")
+        for e in entries:
+            mid = e.get("modelId") or e.get("model_id") or "?"
+            rank = e.get("rank")
+            val = e.get("value")
+            verified = e.get("verified")
+            bits = []
+            if rank is not None:
+                bits.append(f"#{rank}")
+            bits.append(mid)
+            if val is not None:
+                bits.append(f"score={val}")
+            if verified:
+                bits.append("✓verified")
+            lines.append("  - " + "  ".join(bits))
+        lines.append("")
+    text_body = "\n".join(lines)
+
+    # HTML
+    rows = []
+    for ds, entries in sorted(new_by_ds.items()):
+        ds_url = f"https://huggingface.co/datasets/{ds}"
+        rows.append(f'<h3 style="margin:18px 0 6px"><a href="{ds_url}">{ds}</a> '
+                    f'<span style="color:#666;font-weight:normal">({len(entries)} new)</span></h3>')
+        rows.append('<table style="border-collapse:collapse;width:100%;font-size:14px">')
+        rows.append('<thead><tr style="background:#f4f4f5;text-align:left">'
+                    '<th style="padding:6px 8px">Rank</th>'
+                    '<th style="padding:6px 8px">Model</th>'
+                    '<th style="padding:6px 8px">Score</th>'
+                    '<th style="padding:6px 8px">Verified</th></tr></thead><tbody>')
+        for e in entries:
+            mid = e.get("modelId") or e.get("model_id") or "?"
+            mid_url = f"https://huggingface.co/{mid}"
+            rank = e.get("rank", "")
+            val = e.get("value", "")
+            verified = "✓" if e.get("verified") else ""
+            rows.append(f'<tr style="border-top:1px solid #eee">'
+                        f'<td style="padding:6px 8px">#{rank}</td>'
+                        f'<td style="padding:6px 8px"><a href="{mid_url}">{mid}</a></td>'
+                        f'<td style="padding:6px 8px">{val}</td>'
+                        f'<td style="padding:6px 8px">{verified}</td></tr>')
+        rows.append("</tbody></table>")
+
+    html_body = (
+        f'<div style="font-family:-apple-system,BlinkMacSystemFont,sans-serif;max-width:760px">'
+        f'<h2 style="margin-bottom:4px">HF Leaderboard digest — {today}</h2>'
+        f'<p style="color:#555;margin-top:0">'
+        f'{total} new model entr{"y" if total == 1 else "ies"} across {len(new_by_ds)} benchmark(s).</p>'
+        + "\n".join(rows) +
+        '<p style="color:#888;font-size:12px;margin-top:24px">'
+        'Source: <a href="https://huggingface.co/docs/hub/leaderboard-data-guide">HF leaderboard API</a>. '
+        'Sent by ~/leaderboard-watcher/watch.py.</p></div>'
+    )
+    return text_body, html_body
+
+
+def send_email(cfg: dict, subject: str, text_body: str, html_body: str) -> None:
+    user = cfg["smtp_user"]
+    pwd = cfg["smtp_password"]
+    sender = cfg["email_from"] or user
+    recipient = cfg["email_to"]
+    if not (user and pwd and recipient):
+        log("ERROR: SMTP credentials or recipient missing — set them in config.json or env vars (SMTP_USER, SMTP_PASSWORD, EMAIL_TO).")
+        return
+
+    msg = EmailMessage()
+    msg["From"] = sender
+    msg["To"] = recipient
+    msg["Subject"] = subject
+    msg.set_content(text_body)
+    msg.add_alternative(html_body, subtype="html")
+
+    host = cfg["smtp_host"]
+    port = cfg["smtp_port"]
+    ctx = ssl.create_default_context()
+    try:
+        if port == 465:
+            with smtplib.SMTP_SSL(host, port, context=ctx, timeout=30) as s:
+                s.login(user, pwd)
+                s.send_message(msg)
+        else:
+            with smtplib.SMTP(host, port, timeout=30) as s:
+                s.starttls(context=ctx)
+                s.login(user, pwd)
+                s.send_message(msg)
+        log(f"Email sent to {recipient} via {host}:{port}.")
+    except Exception as e:
+        log(f"ERROR sending email: {e}")
+
+
+# ---------- state helpers ----------
+
+def migrate_seen(seen_data) -> dict:
+    """Convert legacy list-of-ids to {model_id: first_seen_iso | None} dict."""
+    if isinstance(seen_data, list):
+        return {m: None for m in seen_data}
+    return seen_data
+
+
+def diff_models(seen: dict, current_ids: list, now: datetime) -> tuple[list, dict]:
+    """Return (new_ids, updated_seen_dict) given current leaderboard snapshot.
+
+    A model is only reported as "new" if it has appeared in at least 2 consecutive
+    runs. First-time appearances are recorded in state with a ``pending`` sentinel
+    and promoted on the next sighting. This guards against flaky external
+    leaderboards that intermittently drop and restore model entries.
+    """
+    now_iso = now.isoformat(timespec="seconds")
+    pending_marker = "pending"
+    current_set = set(current_ids)
+    new_ids: list[str] = []
+    updated = dict(seen)
+
+    # Handle pending models from the previous run that are no longer in
+    # the API. They stay in state so they won't be re-reported later,
+    # but we demote the pending marker to None so they don't persist.
+    for m, first_seen in list(updated.items()):
+        if first_seen == pending_marker and m not in current_set:
+            updated[m] = None  # treat as seeded, not new
+
+    for m in current_ids:
+        if m not in updated:
+            # First ever sighting — mark as pending, don't report yet.
+            updated[m] = pending_marker
+        elif updated[m] == pending_marker:
+            # Seen in the previous run too — promote to confirmed new.
+            updated[m] = now_iso
+            new_ids.append(m)
+        # else: already confirmed (has a real first_seen date) — no change.
+    return new_ids, updated
+
+
+# ---------- core ----------
+
+def run_once() -> int:
+    cfg = load_config()
+    token = read_token(cfg)
+    first_run_overall = not STATE_PATH.exists()
+    state = load_json(STATE_PATH, {})
+
+    benchmarks = cfg.get("benchmarks") or []
+    if not benchmarks:
+        log("Discovering official benchmark datasets...")
+        try:
+            benchmarks = discover_official_benchmarks(token, cfg["timeout"])
+        except Exception as e:
+            log(f"ERROR discovering benchmarks: {e}")
+            return 1
+    log(f"Checking {len(benchmarks)} benchmark(s).")
+
+    new_by_ds: dict[str, list[dict]] = {}
+
+    for ds in benchmarks:
+        try:
+            entries = get_leaderboard(ds, token, cfg["timeout"])
+        except urllib.error.HTTPError as e:
+            log(f"  {ds}: HTTP {e.code} ({e.reason}) — skipping")
+            continue
+        except Exception as e:
+            log(f"  {ds}: error {e} — skipping")
+            continue
+
+        current_ids = []
+        details: dict[str, dict] = {}
+        for entry in entries:
+            mid = entry.get("modelId") or entry.get("model_id") or entry.get("model")
+            if not mid:
+                continue
+            current_ids.append(mid)
+            details[mid] = entry
+
+        ds_state = state.get(ds, {})
+        seen = migrate_seen(ds_state.get("seen", {}))
+        first_time_for_ds = ds not in state
+        now = datetime.now(timezone.utc)
+        new_ids, updated_seen = diff_models(seen, current_ids, now)
+
+        state[ds] = {
+            "seen": updated_seen,
+            "last_checked": now.isoformat(timespec="seconds"),
+            "count": len(current_ids),
+        }
+
+        if not new_ids:
+            log(f"  {ds}: no new models ({len(current_ids)} total)")
+            continue
+
+        log(f"  {ds}: {len(new_ids)} new (of {len(current_ids)} total)")
+        for m in new_ids[:10]:
+            e = details.get(m, {})
+            rank = e.get("rank")
+            val = e.get("value")
+            first_seen = updated_seen.get(m)
+            log(f"      + #{rank} {m} score={val}  first_seen={first_seen}")
+        if len(new_ids) > 10:
+            log(f"      + … and {len(new_ids) - 10} more")
+        silent = (first_run_overall or first_time_for_ds) and cfg["silent_first_run"]
+        if not silent:
+            new_by_ds[ds] = [details[m] for m in new_ids]
+
+        time.sleep(cfg["request_delay_seconds"])
+
+    save_json(STATE_PATH, state)
+
+    total_new = sum(len(v) for v in new_by_ds.values())
+    if total_new == 0:
+        log("No new models to report.")
+        if cfg["skip_email_when_empty"]:
+            return 0
+        text_body = f"No new models on any of the {len(benchmarks)} watched benchmarks today."
+        html_body = f"<p>{text_body}</p>"
+        send_email(cfg, "HF Leaderboard digest — no new models", text_body, html_body)
+        return 0
+
+    subject = f"HF Leaderboard digest — {total_new} new model entr{'y' if total_new == 1 else 'ies'}"
+    text_body, html_body = render_digest(new_by_ds)
+    log(f"Sending digest: {total_new} new entries across {len(new_by_ds)} benchmark(s).")
+    send_email(cfg, subject, text_body, html_body)
+    return 0
+
+
+def main(argv):
+    if "--list" in argv:
+        cfg = load_config()
+        for b in discover_official_benchmarks(read_token(cfg), cfg["timeout"]):
+            print(b)
+        return 0
+    if "--reset" in argv:
+        if STATE_PATH.exists():
+            STATE_PATH.unlink()
+            print(f"Removed {STATE_PATH}")
+        return 0
+    if "--test-email" in argv:
+        cfg = load_config()
+        send_email(cfg, "HF Leaderboard watcher — test email",
+                   "If you can read this, SMTP works. 🎉",
+                   "<p>If you can read this, SMTP works. 🎉</p>")
+        return 0
+    return run_once()
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))