UMEP-dev
diff --git a/‎.claude/rules/docs/conventions.md‎
Lines changed: 16 additions & 0 deletions b/‎.claude/rules/docs/conventions.md‎
Lines changed: 16 additions & 0 deletions
diff --git a/‎.impeccable.md‎
Lines changed: 67 additions & 0 deletions b/‎.impeccable.md‎
Lines changed: 67 additions & 0 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 28 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 28 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 4 additions & 4 deletions b/‎README.md‎
Lines changed: 4 additions & 4 deletions
diff --git a/‎docs/README.md‎
Lines changed: 1 addition & 1 deletion b/‎docs/README.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎docs/source/_ext/publications_topic_annotate.py‎
Lines changed: 107 additions & 0 deletions b/‎docs/source/_ext/publications_topic_annotate.py‎
Lines changed: 107 additions & 0 deletions
diff --git a/‎docs/source/_static/publications-filter.css‎
Lines changed: 77 additions & 0 deletions b/‎docs/source/_static/publications-filter.css‎
Lines changed: 77 additions & 0 deletions
@@ -1,6 +1,8 @@
 ---
 paths:
   - docs/**/*
+  - site/**/*
+  - README.md
 ---
 
 # Documentation Conventions
@@ -9,6 +11,20 @@ Conventions for SUEWS documentation (Sphinx, RST, Markdown).
 
 ---
 
+## Links to docs.suews.io — URL format
+
+**Always** use the `/stable/` or `/latest/` prefix. **Never** use `/en/latest/`.
+
+- Correct: `https://docs.suews.io/stable/acknowledgement.html`, `https://docs.suews.io/stable/getting-started.html`
+- Correct (dev version): `https://docs.suews.io/latest/acknowledgement.html`
+- Wrong (stale, 404s today): `https://docs.suews.io/en/latest/acknowledgement.html`
+
+The `en/latest/` pattern is an old ReadTheDocs language-prefixed layout. The SUEWS docs site now serves at `/stable/` (production) and `/latest/` (development). `https://docs.suews.io/` itself 302-redirects to `/stable/`.
+
+All known `/en/latest/` occurrences in the repo were swept to `/stable/` on 2026-04-19. If this pattern reappears in a PR, block it — it will 404 for users.
+
+---
+
 ## Build Commands
 
 ```bash
 
@@ -0,0 +1,67 @@
+# Impeccable Design Context — SUEWS
+
+Captured via `/impeccable teach` on 2026-04-18.
+
+This file is the single source of truth for design direction on any SUEWS-facing surface (suews.io landing, brand showcase, future dashboards, interactive documentation). All impeccable-family skills (`/craft`, `/polish`, `/critique`, `/animate`, etc.) read this file before producing work.
+
+## Design Context
+
+### Users
+
+Two audiences, weighted **equally**:
+
+- **Urban climate researchers & PhD students** — landing on suews.io to evaluate whether SUEWS fits their science question, verify citations and provenance, reach the Sphinx docs, or find the Discourse community. Technical, sceptical, will notice unsupported claims.
+- **Architects, engineers, and built-environment consultancies** (exemplified by the Foster + Partners / Arup lines of enquiry) — assessing whether SUEWS is serious enough to use in commercial microclimate workflows. Not a pure software-buyer audience; they want proof of scientific rigour, not a SaaS pitch.
+
+Secondary, design around but do not optimise for: UMEP/QGIS users arriving sideways, funders skimming for institutional credibility, and journalists chasing urban-heat stories.
+
+Job-to-be-done on suews.io: **"Convince me in 30 seconds this is a serious, well-maintained, scientifically grounded model — then get me to the docs."**
+
+### Brand Personality
+
+Ting's words: **quietly confident, not fancy.**
+
+Expanded: *rigorous, grounded, unshowy, enduring.* SUEWS has run for 15+ years across 20+ cities — the design should feel like a well-kept scientific instrument, not a 2025 AI startup. No hype, no glow, no "revolutionary". Authority comes from restraint and from the evidence on the page (citations, years active, institutional backing).
+
+Emotional goals: **trust, competence, calm.** A reader should feel they've landed somewhere careful.
+
+### Aesthetic Direction
+
+The existing visual system in `site/` is the established brand. Treat it as canonical, not a starting point to redesign:
+
+- **Palette**: Deep Blue `#2D3142`, Warm Stone `#5D5852`, Golden Sun `#F7B538`, Sun Core `#E85D04`, Forest Green `#09a25c`, Ocean Blue `#0077B6`, Sky Blue `#5DADE2`, Wave Blue `#0558a5`. These map to the physical constituents of the model (urban fabric, sun, vegetation, water) — the palette is the model's conceptual diagram.
+- **Theme**: dark default (suits the editorial/scientific register and the audience's typical viewing context — late-evening reading, researchers in dim offices) with a working light toggle. Respect `prefers-color-scheme`.
+- **Typography** — intentionally kept: Crimson Pro (display/serif), Instrument Sans (UI/body), JetBrains Mono (code/metrics). Yes, Crimson Pro and Instrument Sans appear on impeccable's "reflex fonts" watch-list, but they are already load-bearing on suews.io and the brand has settled. Do **not** churn them on the landing page. For *new* surfaces (dashboards, interactive tools, posters) where there's no prior commitment, reach beyond the reflex list first.
+- **Signature motifs**: topographic contour rings as ambient background, golden-hour halo on the logo, golden-ratio composition (1:1.618) for the logo glyph. These are the one-thing-you-remember — keep them.
+- **Register**: editorial-scientific, closer to a Royal Society journal landing page than a software product page. Facts in roman; emphasis via italic and weight, not colour shifts or gradients.
+
+### Anti-references
+
+SUEWS should explicitly *not* look like:
+
+- A generic AI/ML startup (cyan-on-dark, purple-to-blue gradients, glowing neon accents, glassmorphism cards).
+- A 2024–2025 AI-generated template (identical cards in a 3-col grid, rounded-rect icon above every heading, gradient text for impact).
+- A consumer SaaS marketing page (big-number hero metrics in service of conversion, aggressive CTAs, persuasion patterns).
+- A legacy university-department site (1990s table layouts, Comic Sans, stacked centred everything).
+
+### Accessibility
+
+Target: **WCAG 2.2 AA across the whole site**. AAA is not a design goal — it would force the palette into a flatness that fights the editorial register, and the audience doesn't warrant it.
+
+Required practices on every new surface:
+
+- Text contrast verified against actual palette combinations (the current `text-muted` token `rgba(255,255,255,0.35)` on `#0F1119` is borderline for small text — audit before reuse).
+- Honour `prefers-reduced-motion`. The landing page currently has looping contour pulse, wave undulation, sun glow, and staggered card reveals — all of these must be reduced to static or single-shot when the user has requested less motion.
+- Focus states visible on all interactive surfaces. The current theme toggle and resource cards must have keyboard-visible focus rings, not only hover states.
+- No colour-only meaning. The golden-sun / water-blue / forest-green mapping to physical constituents is evocative but must not be the sole carrier of information.
+- No synthetic bold on display type; ensure Crimson Pro ships the real weights.
+
+### Design Principles
+
+Use these as the tie-breaker whenever a design decision is contested. If you can't tell whether a change improves the site, ask which principle it serves.
+
+1. **Evidence over assertion.** Prefer showing (citations, years, sites, institutional names, a real log of activity) over claiming ("powerful", "industry-leading"). If a claim can't be backed on the page, cut it.
+2. **Restraint is the voice.** Quiet confidence means one accent colour at a time, one motion at a time, whitespace over decoration. If a flourish doesn't earn its place, delete it.
+3. **The palette is the model.** Sun / water / vegetation / urban fabric colours map to what SUEWS simulates — use them to reinforce meaning, not as decoration. Don't introduce colours from outside this system.
+4. **Readable first, elegant second.** Body type at a comfortable size, line length capped at ~70ch, contrast audited. An elegant layout that fatigues a researcher after two screens is a failure.
+5. **Keep the topographic signature.** Contour rings, golden-hour glow, golden-ratio composition — these are what distinguish SUEWS from every other academic-software landing. Protect them; don't dilute them with generic decoration.
@@ -42,8 +42,36 @@ Full setup: `/setup-dev` | Style check: `/lint-code` | Build check: `/verify-bui
 
 Rules in `.claude/rules/` load automatically based on files being edited.
 
+## Design Context
+
+Applies to any SUEWS-facing surface: `site/` landing, brand showcase, future dashboards, interactive docs. Full rationale and tie-breaker principles live in `.impeccable.md` at project root — read it before any design work (`/craft`, `/polish`, `/critique`, `/animate`, etc.).
+
+- **Users** — Two audiences, equally weighted:
+  - Urban climate researchers & PhD students verifying SUEWS is scientifically sound.
+  - Architects, engineers, and built-environment consultancies (Foster + Partners, Arup pattern) assessing commercial fit.
+  - Job-to-be-done: "Convince me in 30 seconds this is a serious, well-maintained, scientifically grounded model — then get me to the docs."
+- **Brand personality** — *Quietly confident, not fancy.* Rigorous, grounded, unshowy, enduring. Emotional goals: trust, competence, calm. No hype, no glow, no "revolutionary".
+- **Aesthetic direction** — Established visual system in `site/` is canonical:
+  - Palette tied to the model's physics (Deep Blue `#2D3142`, Golden Sun `#F7B538`, Sun Core `#E85D04`, Forest Green `#09a25c`, Ocean Blue `#0077B6`, Sky Blue `#5DADE2`, Wave Blue `#0558a5`).
+  - Dark default with working light toggle; honour `prefers-color-scheme`.
+  - Typography kept: Crimson Pro (display), Instrument Sans (UI), JetBrains Mono (code). Load-bearing on the landing — do not churn. For *new* surfaces, reach beyond these first.
+  - Signature motifs: topographic contour rings, golden-hour halo, golden-ratio logo composition. Protect; do not dilute.
+- **Anti-references** — Do NOT look like a generic AI/ML startup (cyan-on-dark, purple gradients, glassmorphism), a 2024–2025 AI template (identical card grids, gradient text), a consumer SaaS page, or a legacy university department site.
+- **Accessibility** — Target WCAG 2.2 AA (not AAA — fights the editorial register). Required on every surface:
+  - Contrast audited against the actual palette (the `text-muted` token is borderline for small text).
+  - Honour `prefers-reduced-motion` — the landing page has several concurrent animations.
+  - Visible keyboard focus rings everywhere.
+  - No colour-only meaning; ensure the Crimson Pro weights are real, not synthetic bold.
+- **Design principles** (tie-breakers when a change is contested):
+  1. Evidence over assertion.
+  2. Restraint is the voice.
+  3. The palette is the model.
+  4. Readable first, elegant second.
+  5. Keep the topographic signature.
+
 ## References
 
+- `.impeccable.md` - Design context (full rationale, used by impeccable-family skills)
 - `.claude/README.md` - Full workspace documentation
 - `.claude/skills/` - Detailed skill workflows
 - `.claude/rules/` - Style conventions
@@ -64,10 +64,10 @@ Full documentation: **[docs.suews.io](https://docs.suews.io)**
 
 ## Documentation
 
-* **[Getting Started](https://docs.suews.io/en/latest/getting-started.html)** -- installation and first simulation
-* **[Tutorials](https://docs.suews.io/en/latest/tutorials.html)** -- hands-on guides with sample data
-* **[Input/Output Reference](https://docs.suews.io/en/latest/inputs.html)** -- configuration and data formats
-* **[Scientific Background](https://docs.suews.io/en/latest/parameterisations-and-sub-models.html)** -- physics schemes and parameterisations
+* **[Getting Started](https://docs.suews.io/stable/workflow.html)** -- installation and first simulation
+* **[Tutorials](https://docs.suews.io/stable/auto_examples/index.html)** -- hands-on guides with sample data
+* **[Input/Output Reference](https://docs.suews.io/stable/inputs/index.html)** -- configuration and data formats
+* **[Scientific Background](https://docs.suews.io/stable/parameterisations-and-sub-models.html)** -- physics schemes and parameterisations
 * **[Community Forum](https://community.suews.io)** -- questions, discussion, and support
 
 ## Citation
 
@@ -21,7 +21,7 @@ This directory contains the complete documentation build system for SUEWS (Surfa
 - **`installation.rst`**: Installation instructions
 - **`workflow.rst`**: User workflow guidance  
 - **`notation.rst`**: Mathematical notation and symbols
-- **`acknowledgement.rst`**: Credits and acknowledgments
+- **`acknowledgement.rst`**: Stub page linking to canonical team / funding / dependencies pages on suews.io
 - **`troubleshooting.rst`**: Common issues and solutions
 
 #### Input/Output Reference
 
@@ -0,0 +1,107 @@
+"""
+Sphinx extension: publications_topic_annotate.
+
+Tags each bibliography ``<li>`` on the two publication pages with CSS
+classes derived from the BibTeX entry's ``keywords`` field so the
+client-side chip filter (``publications-filter.js``) can hide/show
+entries by topic without duplicating them across static subsections.
+
+Pipeline:
+
+* ``builder-inited``: parse ``refs-SUEWS.bib`` and ``refs-community.bib``
+  once with pybtex and cache a ``citekey -> [slug, ...]`` map on
+  ``app.env``.
+* ``doctree-resolved``: on the two publication pages only, read the
+  sphinxcontrib-bibtex domain's ``citations`` list to get the mapping
+  from rendered ``citation_id`` (the docutils-generated ``id2`` etc.
+  on the ``<li>``) back to the original bib citekey. Walk every
+  ``list_item`` node and, when its first id matches a known citation,
+  extend ``classes`` with ``pub-entry`` plus one ``pub-kw-<slug>`` per
+  keyword slug. Docutils turns those into ``class=`` on the rendered
+  ``<li>`` element.
+
+The bib file read via pybtex is the source of truth for keywords;
+sphinxcontrib-bibtex is consulted only to bridge rendered ids back to
+cite keys.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from docutils import nodes
+from pybtex.database import parse_file
+
+TOPIC_PAGES = frozenset({"related_publications", "community_publications"})
+BIB_FILES = ("assets/refs/refs-SUEWS.bib", "assets/refs/refs-community.bib")
+
+
+def _parse_bibs(srcdir: Path) -> dict[str, list[str]]:
+    """Return ``{citekey: [slug, ...]}`` for both SUEWS bib files."""
+    out: dict[str, list[str]] = {}
+    for bib_path in BIB_FILES:
+        full = Path(srcdir) / bib_path
+        if not full.exists():
+            continue
+        db = parse_file(str(full), bib_format="bibtex")
+        for key, entry in db.entries.items():
+            raw = entry.fields.get("keywords", "")
+            slugs = sorted({s.strip() for s in raw.split(",") if s.strip()})
+            out[key] = slugs
+    return out
+
+
+def _citation_id_to_key(app, docname: str) -> dict[str, str]:
+    """Map rendered docutils ids on bibliography ``<li>`` back to cite keys.
+
+    Scoped to ``docname`` because sphinxcontrib-bibtex reuses short ids
+    (``id2``, ``id3``, ...) inside each document, so a global map causes
+    cross-page collisions.
+    """
+    try:
+        domain = app.env.get_domain("cite")
+    except Exception:
+        return {}
+    citations = getattr(domain, "citations", []) or []
+    return {
+        c.citation_id: c.key
+        for c in citations
+        if c.bibliography_key.docname == docname
+    }
+
+
+def _on_builder_inited(app) -> None:
+    app.env.pub_topic_map = _parse_bibs(Path(app.srcdir))
+
+
+def _on_doctree_resolved(app, doctree, docname: str) -> None:
+    if docname not in TOPIC_PAGES:
+        return
+    citekey_map: dict[str, list[str]] = getattr(app.env, "pub_topic_map", {}) or {}
+    if not citekey_map:
+        return
+    id_to_key = _citation_id_to_key(app, docname)
+    if not id_to_key:
+        return
+    for list_item in doctree.traverse(nodes.list_item):
+        ids = list_item.get("ids") or []
+        citekey = next((id_to_key[i] for i in ids if i in id_to_key), None)
+        if citekey is None:
+            continue
+        slugs = citekey_map.get(citekey, [])
+        to_add = ["pub-entry"] + [f"pub-kw-{s}" for s in slugs]
+        existing = list_item.get("classes") or []
+        for cls in to_add:
+            if cls not in existing:
+                existing.append(cls)
+        list_item["classes"] = existing
+
+
+def setup(app):
+    app.connect("builder-inited", _on_builder_inited)
+    app.connect("doctree-resolved", _on_doctree_resolved)
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }
@@ -0,0 +1,77 @@
+/*
+ * publications-filter.css — chip styling for the topic filter on
+ * `related_publications` and `community_publications`.
+ *
+ * Uses pydata_sphinx_theme / sphinx_book_theme CSS custom properties
+ * (`--pst-color-*`) so the chips feel native to the docs theme in both
+ * light and dark modes, with sensible fallbacks.
+ */
+
+.pub-filter {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin: 16px 0 28px;
+  padding: 0;
+}
+
+.pub-filter__chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 14px;
+  font: inherit;
+  font-size: 0.85rem;
+  line-height: 1.4;
+  color: var(--pst-color-text-base, #374151);
+  background: transparent;
+  border: 1px solid var(--pst-color-border, rgba(0, 0, 0, 0.15));
+  border-radius: 999px;
+  cursor: pointer;
+  transition: background-color 200ms ease, border-color 200ms ease, color 200ms ease;
+  white-space: nowrap;
+}
+
+.pub-filter__chip:hover:not(:disabled) {
+  border-color: var(--pst-color-primary, #0558a5);
+  color: var(--pst-color-primary, #0558a5);
+}
+
+.pub-filter__chip:focus-visible {
+  outline: 2px solid var(--pst-color-primary, #0558a5);
+  outline-offset: 2px;
+}
+
+.pub-filter__chip.is-active {
+  background: var(--pst-color-primary, #0558a5);
+  border-color: var(--pst-color-primary, #0558a5);
+  color: var(--pst-color-background, #ffffff);
+}
+
+.pub-filter__chip.is-empty,
+.pub-filter__chip:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.pub-filter__chip--all {
+  font-weight: 500;
+}
+
+.pub-filter__count {
+  font-size: 0.75rem;
+  opacity: 0.75;
+  font-variant-numeric: tabular-nums;
+}
+
+.pub-filter__empty {
+  margin: 12px 0 24px;
+  font-style: italic;
+  color: var(--pst-color-text-muted, #6b7280);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .pub-filter__chip {
+    transition: none;
+  }
+}