#+TITLE: Weather kit — for the Dupre kit / waybar / Wayland UX
#+AUTHOR: Craig Jennings
#+DATE: 2026-07-18

Built to completion elsewhere and handed to archsetup, which owns the Dupre kit,
waybar, and the Wayland UI/UX and will maintain it from here. This note is the
integration guide: what's in the package, the data contract, and how each
surface consumes it.

* What's in the package

| File                 | Purpose                                                                 |
|----------------------+-------------------------------------------------------------------------|
| =weather=            | The fetcher. Python 3, stdlib only. Hits Open-Meteo, normalises, caches. |
| =weather-glyphs.svg= | The custom condition glyph set (9 symbols, currentColor).               |
| =weather-chip.html=  | Reference renderer: the chosen chip, wired to the contract. Port target.|
| =README.org=         | This file.                                                              |

* The design decisions it encodes (settled over the 2026-07-18 session)

- *Source: Open-Meteo, =model=best_match=.* No API key, no signup, non-commercial
  free tier (10k calls/day; a 15-min poll is ~96/day). =best_match= auto-selects
  the most accurate regional model — NOAA blend in the US, ECMWF/ICON abroad — so
  the same binary is right on ratio in New Orleans and on velox travelling. For a
  bar chip there's no perceptible accuracy gap vs the NWS API, and NWS is US-only,
  so Open-Meteo is the single source. (NWS stays a possible *additive* feature
  later, only for official US severe-weather alerts.)
- *One fetcher, one cache, thin renderers.* Every surface shells out to =weather=
  and renders the JSON. Nobody re-implements the API call or the cache. A shared
  cache means several widgets polling still hit the API at most once per TTL and
  all show the identical reading.
- *Windy is a condition, not a compass reading.* Below the threshold the chip
  shows the direction vane + speed; at/above it, the gust glyph + speed. Same
  width either way. Threshold default *15 mph* (Beaufort 4 — where wind stops
  being ambient). It's a =--windy-threshold= flag, derived at output from
  =wind_mph=, so changing it takes effect without a cache bust.
- *Custom glyphs, not Nerd Font.* Seven conditions + a gust mark + a vane, drawn
  to sit in the instrument aesthetic. =currentColor=, so each surface recolours.

* The contract (=weather --json=)

#+begin_src json
{
  "temp_f": 82, "feels_f": 92,
  "condition": "clear",     // clear | partly | cloud | fog | rain | snow | storm
  "wmo_code": 0,
  "windy": false,           // wind_mph >= threshold
  "wind_mph": 6, "wind_dir": "WNW", "wind_deg": 293,
  "location": "New Orleans",
  "observed": "2026-07-18T01:00", "stale": false
}
#+end_src

=condition= is the coupling to the glyphs. Mapping (also in =weather-chip.html=):
=clear->wx-sun=, =partly->wx-partly=, =cloud->wx-cloud=, =fog->wx-fog=,
=rain->wx-rain=, =snow->wx-snow=, =storm->wx-storm=; plus =wx-wind= (shown when
=windy=) and =wx-vane= (shown otherwise, rotated by =wind_deg=). A consumer never
sees the WMO number unless it wants =wmo_code=.

=stale: true= means the network fetch failed and this is the last good reading —
render it dimmed, never blank the bar.

* WMO weather-code -> condition (what the fetcher collapses)

| WMO code(s)                          | condition |
|--------------------------------------+-----------|
| 0                                    | clear     |
| 1, 2                                 | partly    |
| 3                                    | cloud     |
| 45, 48                               | fog       |
| 51-57, 61-67, 80-82                  | rain      |
| 71-77, 85-86                         | snow      |
| 95, 96, 99                           | storm     |
| (anything unmapped)                  | cloud     |

* Install

Drop =weather= on =PATH= the way the other fleet CLIs travel (=agent-page=, etc.):
into the rulesets/dotfiles bin so =make install= / stow links it to
=~/.local/bin/weather= on every machine. It's dependency-free, so nothing else to
provision.

No coordinates are baked in (nothing personal ships in the repo). Each machine
sets its own location, resolved in order:

1. =--lat/--lon= flags.
2. =$WEATHER_LAT= / =$WEATHER_LON= (and optional =$WEATHER_NAME=).
3. =~/.config/weather/config.json= — ={"lat":29.97,"lon":-90.09,"name":"New Orleans"}=.
   Add ="use_geo": true= (or pass =--geo=) to prefer =whereami= — the right call
   on velox, which travels.

* How each surface consumes it

- *waybar* — a custom module:
  #+begin_src jsonc
  "custom/weather": { "exec": "weather --format waybar", "return-type": "json",
                      "interval": 900, "on-click": "..." }
  #+end_src
  =--format waybar= emits ={text, alt, class, tooltip}=; the stylesheet picks the
  icon by =alt=/=class= (=.clear=, =.windy=, =.stale=, ...).
- *Dupre kit / =svg.el=* — =(json-parse-string (shell-command-to-string "weather --json"))=,
  then render the chip. =weather-chip.html='s =renderChip(reading)= is the exact
  logic to port: glyph, temp, wind slot (gust vs vane by =windy=).
- *clock-panel (Python)* — =json.loads(subprocess.run(["weather","--json"],...).stdout)=.
  No HTTP in clock-panel at all.

* Notes / open choices for the maintainer

- Poll cadence lives with the consumer (waybar =interval=), not the tool; the tool
  just honours its own cache TTL (=--ttl=, default 900s).
- =weather-glyphs.svg= is the canonical glyph source. =weather-chip.html= inlines a
  copy for a standalone demo — if the glyphs change, update both (or have the kit
  build inline from the =.svg=).
- The chip currently shows the wind slot always. If it ever reads busy on a packed
  bar, hiding the slot below the threshold (show only when windy) is a one-line
  change — the data's already there.
- A "windy later today" hint would want the hourly endpoint (=hourly=wind_speed_10m=)
  and a small max-over-next-N-hours; the fetcher is structured to add that as a
  second field without touching consumers.