docs: settle weather source on OpenWeatherMap

A polybar backup script for OWM turned up, which beats the weather.com
scraper: it has a working condition mapping. Port the domain knowledge,
not the code.

Worth keeping: the OWM condition-id ranges, day/night selection against
sys.sunrise/sys.sunset, and the Beaufort wind thresholds. Becomes a
table in data.lua.

Not portable: polybar %{F}/%{T} format tokens, hardcoded hex (UDT roles
replace them), bc conversions (Lua arithmetic), one-line output (a
card). So the script shrinks to curl-and-cache and Lua does the rest.

The reference script hardcodes a live API key plus city and country. The
key and location move to ~/.config/udt/weather.env, outside the repo,
same reasoning as roles.conf. Nothing carries a key in-repo, and
weather.env is gitignored so a stray copy cannot be staged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2 files changed, 50 insertions, 8 deletions

diff --git a/.gitignore b/.gitignore
index 72b17c9..aa0c404 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 HANDOFF.md
+weather.env
diff --git a/docs/superpowers/specs/2026-09-16-conky-lua-dashboard-design.md b/docs/superpowers/specs/2026-09-16-conky-lua-dashboard-design.md
index 059205b..08b434b 100644
--- a/docs/superpowers/specs/2026-09-16-conky-lua-dashboard-design.md
+++ b/docs/superpowers/specs/2026-09-16-conky-lua-dashboard-design.md
@@ -169,12 +169,52 @@ function: `playerctl` for MPRIS now-playing, and the weather fetch below.
 Deferred past the v1 slice, then implemented as a fetch script writing a cache
 file that `data.lua` reads. The dashboard never blocks on the network.
 
-`~/Programming/waybar-weather.py` exists and is the starting point, but it is
-not reusable as-is: it scrapes `weather.com` HTML with `pyquery`, a third-party
-dependency, and screen-scraping breaks whenever the site's markup changes. The
-replacement targets a documented endpoint (`wttr.in` JSON, or an API with a key)
-and is reimplemented rather than copied. The location id in that script is
-personal data and does not move into this repo.
+**Source: OpenWeatherMap**, via the current-weather endpoint. Chosen over
+`wttr.in` because a working reference implementation already exists, with a
+condition mapping worth keeping.
+
+Two prior scripts were examined:
+
+`~/Programming/waybar-weather.py` is **rejected**. It scrapes `weather.com`
+HTML with `pyquery`, a third-party dependency, and screen-scraping breaks
+whenever the markup changes.
+
+`/data/udt-backup/polybar/modules/weather/openweathermap-simple.sh` is the
+**reference**. What is worth porting is its accumulated domain knowledge, not
+its code:
+
+- The OWM condition-id mapping: `<=232` thunderstorm, `<=311` light drizzle,
+  `<=321` heavy drizzle, `<=531` rain, `<=622` snow, `<=771` fog, `781`
+  tornado, `800` clear, `801` few clouds, `<=804` overcast.
+- Day/night icon selection by comparing now against `sys.sunrise` and
+  `sys.sunset` from the same response.
+- The Beaufort thresholds for the wind-force icon.
+
+That becomes a table in `data.lua`.
+
+Nothing downstream of the data ports. `%{F...}` and `%{T...}` are polybar
+formatting tokens, meaningless to Cairo; the hardcoded hex colours are replaced
+by UDT roles; the `bc` unit conversions become Lua arithmetic; and the compact
+one-line output becomes a card.
+
+So the script shrinks to fetch-and-cache: curl the endpoint, write the JSON to a
+cache file, nothing else. `data.lua` parses that file and owns the icon mapping.
+OWM's free tier allows 60 calls/minute, so a 15-minute refresh is far inside it.
+
+#### Secrets and personal data stay outside the repo
+
+The reference script hardcodes a **live API key** in plaintext, along with
+`CITY_NAME` and `COUNTRY_CODE`. None of that is copied here.
+
+The key and location are read from `~/.config/udt/weather.env`, outside the
+repo, following the same reasoning as UDT's `~/.config/udt/roles.conf`: local
+state, never committed, and switching machines does not dirty the tree. The
+fetch script exits with a clear message when the file or key is missing, rather
+than silently querying without one.
+
+The key in the backup script must be treated as exposed and rotated: that file
+is mode 755 under a world-readable path. This is flagged for the user; the
+design simply never carries a key in-repo.
 
 ## v1 slice: one card, one widget, end to end
 
@@ -241,12 +281,13 @@ drag-to-place. Click interaction of any kind. The task list and mic button from
 
 ## Open items
 
-Both deferred by design, neither blocks v1.
+Deferred by design, does not block v1.
 
-- Weather source: `wttr.in` versus a keyed API. Decided when the widget is built.
 - Album art via Imlib2 for the media widget, as in `idea2.png`. Needs a check
   that Imlib2 bindings work on a Wayland `conky_surface()`, which was not tested.
 
+Resolved: the weather source is OpenWeatherMap, see "Weather".
+
 ## License
 
 GPLv2 only, matching UDT.