tuiweather 0.2.0 → 0.3.1

package/README.md

@@ -4,26 +4,31 @@ Keyboard-driven terminal weather app: Dark Sky-style rain nowcasting, hourly and
 
 ## Features
 
-- **Rain nowcast** — minute-level "umbrella in N min" warnings derived from 15-minute precipitation buckets
-- **Hourly + daily forecast** — sparkline temperature strip, condition glyphs, precipitation probabilities
+- **Rain nowcast** — minute-level "umbrella in N min" warnings derived from 15-minute precipitation buckets (Open-Meteo only; NWS has no minute-level precipitation feed — the nowcast panel hides and the watch bell stays inactive under `provider = "nws"`, nothing renders a false "Dry")
+- **Hourly + daily forecast** — sparkline temperature strip, emoji condition icons, precipitation probabilities, and (md+ widths) a UV/humidity/visibility summary row
 - **Location search** — type `/`, search the Open-Meteo geocoder, enter to add; locations persist to config
 - **Guided first run** — choose units and find a location without editing a config file
 - **Units** — metric/imperial toggle persisted across runs
-- **Themes** — day, night, or auto (follows sunrise/sunset)
+- **Themes** — day/night accent palettes follow the forecast location's sunrise/sunset; text ink adapts to your terminal's background
+- **Air quality** — US AQI with category label in the details grid, from the Open-Meteo Air Quality API
 - **Responsive layout** — four breakpoint tiers down to 32 columns; clamps gracefully below that
 - **One-line mode** — a single status line for tmux bars and prompts
 
 ## Install
 
-The npm bootstrap package is available as `tuiweather@0.0.0` while the first supported release is prepared. Install the preview channel with Bun:
+Install globally with npm:
 
 ```sh
-bun install --global tuiweather@next
+npm install --global tuiweather
 ```
 
-Standalone binaries will be attached beginning with v0.1.0.
+or with Bun:
 
-Download a standalone binary from [GitHub Releases](https://github.com/brndnsh-labs/tuiweather/releases).
+```sh
+bun install --global tuiweather
+```
+
+Standalone binaries for macOS and Linux are attached to each [GitHub release](https://github.com/brndnsh-labs/tuiweather/releases).
 
 ### macOS Gatekeeper
 
@@ -47,14 +52,20 @@ Use `tuiweather --help` for command-line options and `tuiweather --version` to p
 | --- | --- |
 | `r` | Refresh current location (bypasses cache) |
 | `[` / `]` | Previous / next location |
+| `1`–`9` | Jump to location N by sidebar order (1-based; no-op out of range) |
 | `u` | Toggle metric / imperial units |
 | `/` | Search locations |
-| `d` | Delete active location |
+| `d` | Delete active location (press twice to confirm) |
+| `j` / `k` | Move sidebar focus down/up (lg tier only, wraps) |
+| `enter` | Activate focused location (lg tier) |
+| `s` | Set focused (or active when no focus) as default location |
+| `J` / `K` | Move focused location down/up in sidebar order (lg tier) |
+| `↑` / `↓` | Scroll the main panel when content overflows |
 | `?` | Toggle help overlay |
-| `esc` | Close help overlay; quits otherwise |
+| `esc` | Clear sidebar focus if set; otherwise close help overlay or quit |
 | `q` | Quit |
 
-While the search overlay is open it owns the keyboard: type to search, up/down to move the cursor, enter to add the highlighted result, esc to cancel.
+While the search overlay is open it owns the keyboard: type to search, up/down to move the cursor, enter to add the highlighted result, esc to cancel. Number, focus, and reorder keys are ignored while the search input is focused (same as `d`/`r`).
 
 ### One-line mode
 
@@ -89,15 +100,33 @@ tuiweather --one-line --lat 45.52 --lon -122.67 --json | jq .temperatureC
 JSON values are always metric regardless of your configured units; the embedded `line` field
 matches the plain one-line output, which follows configured units.
 
+### Watch mode
+
+`tuiweather watch` polls the nowcast on an interval and rings the terminal bell (`\a`) when rain
+starts — leave it running in a pane and get pinged before you need the umbrella:
+
+```sh
+tuiweather watch                # poll every refresh_minutes
+tuiweather watch --interval 5   # poll every 5 minutes (1–120)
+tuiweather watch --location seattle
+```
+
+Each poll prints the one-line status (prefixed with the location label). The bell rings only on a
+dry → wet transition, not on every poll. Rain already in progress when the watch starts does not
+bell. The bell depends on the minute-level nowcast, which is Open-Meteo only: under
+`provider = "nws"` the nowcast panel hides and the bell stays inactive — nothing renders a false
+"Dry". Desktop notifications are a planned follow-up.
+
 ## Configuration
 
-Config lives at `~/.config/tuiweather/config.toml` (respects `XDG_CONFIG_HOME`). Every field is optional unless marked required; unknown values fail validation with a descriptive error.
+Config lives at `~/.config/tuiweather/config.toml` (respects `XDG_CONFIG_HOME`). Every field is optional unless marked required; unknown fields are ignored.
 
 ```toml
-schema_version = 2
+schema_version = 3
 time_format = "auto"
 refresh_minutes = 10
 theme = "auto"
+provider = "openmeteo"
 daily_days = 7
 hourly_hours = 24
 default_location = "portland"
@@ -123,17 +152,18 @@ longitude = -122.6765
 
 | Field | Type | Default | Constraints |
 | --- | --- | --- | --- |
-| `schema_version` | integer | `2` | Required; currently always `2`. Version 1 files are migrated in place on load |
+| `schema_version` | integer | `3` | Required; currently always `3`. Version 1 and 2 files are migrated in place on load |
 | `time_format` | `12h` / `24h` / `auto` | `"auto"` | `auto` picks 12h when temperature units are imperial, else 24h |
 | `refresh_minutes` | integer | `10` | Minimum `1` |
-| `theme` | `day` / `night` / `auto` | `"auto"` | `auto` follows local sunrise/sunset |
+| `theme` | `day` / `night` / `auto` | `"auto"` | Accent palette; `auto` follows the location's sunrise/sunset. Text ink always adapts to your terminal's background |
+| `provider` | `openmeteo` / `nws` | `"openmeteo"` | Weather data source. Open-Meteo is the default full-feature experience; NWS is the official US source fallback — works: conditions, temperatures, precipitation probabilities; goes quiet: minute-level nowcast (panel hides, watch bell inactive), hourly/daily precip amounts (blank bars/chips), air quality |
 | `daily_days` | integer | `7` | `1`–`16` forecast days |
 | `hourly_hours` | integer | `24` | `12`–`48` forecast hours |
 | `default_location` | string | none | Must match a `[[locations]]` slug |
 | `units.temp` | `metric` / `imperial` | legacy `units` | Display unit for temperatures |
 | `units.wind` | `metric` / `imperial` | legacy `units` | Display unit for wind speed and visibility |
 | `units.precip` | `metric` / `imperial` | legacy `units` | Display unit for precipitation amounts |
-| `units.pressure` | `metric` / `imperial` | legacy `units` | Reserved for future pressure display (pressure currently renders as hPa) |
+| `units.pressure` | `metric` / `imperial` | legacy `units` | Display unit for pressure; `metric` → hPa (rounded), `imperial` → inHg to 2 decimals; defaults via legacy `units` |
 | `panels.nowcast` | boolean | `true` | Show/hide the nowcast banner |
 | `panels.details` | boolean | `true` | Show/hide the details grid |
 | `panels.hourly` | boolean | `true` | Show/hide the hourly strip |
@@ -150,11 +180,11 @@ Each `[[locations]]` entry:
 | `latitude` | number | Required; `-90`–`90` |
 | `longitude` | number | Required; `-180`–`180` |
 
-Locations added through the search overlay are appended here automatically. Writes are atomic (temp file plus rename).
+Locations added through the search overlay are appended here automatically. Press `s` (focused or active) to set `default_location` and `J`/`K` (lg tier, focused) to reorder `[[locations]]`. Writes are atomic (temp file plus rename).
 
 ## Data attribution
 
-Weather data by [Open-Meteo](https://open-meteo.com), licensed [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Open-Meteo's free tier is offered for non-commercial use; see [open-meteo.com/terms](https://open-meteo.com/terms) before relying on it commercially.
+Weather data by [Open-Meteo](https://open-meteo.com), licensed [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Open-Meteo's free tier is offered for non-commercial use; see [open-meteo.com/terms](https://open-meteo.com/terms) before relying on it commercially. When `provider = "nws"` is configured, forecast data comes from the National Weather Service ([api.weather.gov](https://api.weather.gov)).
 
 ## Development