weather-for-grown-ups 0.2.2 → 0.3.0

package/README.md

@@ -1,288 +1,193 @@
 # Weather for Grown Ups
 
-**Everyone builds a weather tool for their first agent. This one grew up.**
+**Weather is the hello-world of agent tools. This is the version for when “temperature tomorrow” stops being enough.**
 
-Weather is the canonical agent tutorial: give the model a tool, ask for tomorrow's forecast, celebrate when it tells you to bring an umbrella.
+Weather for Grown Ups (WFG) gives agents direct, structured access to numerical weather prediction: NOAA **GFS**, **GEFS** and historical GFS data, plus ECMWF **IFS** and **IFS ENS**.
 
-**Weather for Grown Ups (WFG)** goes a bit further. It gives agents direct access to NOAA's GFS/GEFS and ECMWF's deterministic IFS / IFS ENS numerical weather models — pressure profiles, mixed fields, ensemble distributions, diagnostics, parcel physics, time series, transects, area statistics, run comparisons, and more.
+The central idea is deliberately simple:
 
-One TypeScript core powers equal CLI and MCP surfaces. The public contract is deliberately model-neutral: **one query language over weather datasets**, with model-specific cadence, provenance and deterministic/ensemble semantics preserved behind it. No need to teach your agent how to wrestle GRIB files first.
+> **One query language over weather datasets. Native model semantics stay intact.**
 
-## Quick start
+Ask for a point, a time range, several locations, a transect, an area, a pressure profile or a meteorological diagnostic. Change the dataset without learning another API. WFG handles source selection, GRIB message access, decoding, caching and shared physics; the result keeps the model's real cadence, grid, run, member and provenance semantics.
 
-Node.js 20+ is enough. The npm package includes its GRIB2 decoder; native `wgrib2` is optional.
+No weather API key. No model-specific public namespaces. No need to teach the agent GRIB first.
+
+## 30-second start
+
+Node.js 20+ is enough. The npm package includes its GRIB2 decoder.
 
 ```bash
 npx weather-for-grown-ups --help
-npx weather-for-grown-ups catalog --dataset gefs --search wind --json
+npx weather-for-grown-ups catalog --dataset all --search wind --json
 ```
 
-Start either MCP transport from the same package:
+Run the same core as MCP:
 
 ```bash
 npx weather-for-grown-ups mcp
+# or
 npx weather-for-grown-ups mcp-http
 ```
 
-See [installation and deployment](docs/INSTALL.md) for global npm, Docker, stdio MCP, Streamable HTTP MCP, and hosting details.
-
-## What can an agent do with it?
-
-WFG is deliberately a **tool**, not a forecast persona. It returns structured model data, diagnostics, provenance, and explicit ensemble semantics. The consuming agent decides what those data mean for the user's question.
+For global npm, Docker and hosted MCP setup, see [Installation](docs/INSTALL.md).
 
-The examples below are illustrative agent interpretations, not live forecasts and not literal WFG output.
+## The query model
 
-### Scientific meteorology — Prague, Czechia
+Normal atmospheric access is expressed as four orthogonal choices:
 
-**You ask**
-
-> A cold front is forecast to cross Prague tomorrow. How does the vertical structure of the atmosphere change as it passes, and how confident is the ensemble about the timing?
+```text
+dataset × geometry × time × selection
+```
 
-**The agent might use WFG**
+For example:
+
+```json
+{
+  "dataset": "gefs",
+  "geometry": {
+    "type": "point",
+    "latitude": 50.08,
+    "longitude": 14.43
+  },
+  "time": {
+    "at": "2026-08-30T12:00:00Z"
+  },
+  "selection": {
+    "variables": ["temperature", "wind"],
+    "pressureLevelsHpa": [850, 700, 500],
+    "fields": ["temperature_2m", "wind_10m"]
+  },
+  "ensemble": {
+    "quantiles": [0.1, 0.5, 0.9]
+  }
+}
+```
 
-`diagnose_atmosphere` on `gfs` → `diagnose_atmosphere` on `gefs` → `compare_runs` on `gefs`
+The same vocabulary is used for deterministic forecasts, ensembles, archived forecasts and historical analyses. Capability differences are explicit: unsupported combinations fail rather than being coerced into fake symmetry.
 
-**Example agent interpretation**
+The full contract lives in [Unified atmospheric API](docs/UNIFIED_API.md).
 
-> The frontal signal is coherent through the lower and middle troposphere rather than being just a surface temperature change. The pre-frontal inversion erodes, the 850–700 hPa layer cools, and 850–500 hPa shear strengthens as the new air mass arrives. Most GEFS members show the same transition, but they spread it across several native forecast steps. Confidence is therefore higher in the air-mass change itself than in the exact hour it reaches Prague.
+## What can an agent ask?
 
-### Aviation / paragliding — Bassano del Grappa, Italy
+WFG is intentionally a **tool**, not a forecast persona. It supplies atmospheric evidence; the consuming agent supplies interpretation.
 
-**You ask**
+### Synoptic and profile meteorology
 
-> I'm considering an XC flight from Bassano del Grappa tomorrow. What does the atmospheric profile say about the usable convective window, and what is most likely to shut it down?
+> A cold front is crossing Prague. How does the vertical structure change, and how confident is the ensemble about the timing?
 
-**The agent might use WFG**
+An agent can combine GFS/GEFS pressure profiles, inversion and lapse-rate diagnostics, ensemble distributions and run-to-run changes. The useful answer is no longer just a surface temperature—it can reason about the structure and timing of the air-mass transition.
 
-`diagnose_atmosphere` on `gfs` → `diagnose_atmosphere` on `gefs` → `query_atmosphere` time series on `gefs`
+### Aviation and paragliding
 
-**Example agent interpretation**
+> What does the Bassano profile say about tomorrow's usable convective window, and what is most likely to shut it down?
 
-> The profile becomes progressively more convective through late morning as inhibition weakens and the usable mixed layer deepens. The later constraint is not simply a lack of heating: winds through the lower and middle troposphere strengthen and shear increases into the afternoon. The ensemble agrees more strongly on that wind increase than on the exact instability magnitude, so the main robust signal is a narrowing window before the stronger flow arrives.
+An agent can inspect parcel diagnostics, CAPE/CIN, freezing levels, wind shear and the member-by-member GEFS distribution through time. WFG deliberately does not turn those into a “go flying” score; activity-specific judgment stays outside the core.
 
 *Slightly more information than “Bassano: 21 °C, sunny.”*
 
-### Mountaineering — Grossglockner, Austria
-
-**You ask**
-
-> I'm considering a Grossglockner summit attempt tomorrow morning. What conditions should I expect near summit altitude, and when does the weather start deteriorating?
-
-**The agent might use WFG**
-
-`query_atmosphere` on `gfs` → `query_atmosphere` on `gefs` → `diagnose_atmosphere` on `gefs`
-
-**Example agent interpretation**
-
-> The valley-level forecast understates the change aloft. Near the pressure levels representative of the upper mountain, temperatures remain well below freezing while winds strengthen through the morning. Moisture also increases higher in the column later in the period, raising the risk of cloud around the high terrain. Ensemble agreement is tighter on the wind increase than on the moisture timing, making stronger summit-level flow the more robust deterioration signal.
+### Wind energy
 
-WFG supplies atmospheric model evidence; a consuming agent should still treat mountaineering decisions as safety-critical and use appropriate local forecasts and observations.
+> Is tomorrow afternoon's wind ramp near Esbjerg a local grid-point feature or a regional change, and how uncertain is the timing?
 
-### Wind energy — Esbjerg, Denmark
+An agent can combine multi-point queries, transects, area statistics and ensemble evolution to distinguish a spatially coherent flow change from a local signal.
 
-**You ask**
+### Forecast verification
 
-> A wind farm near Esbjerg expects a production ramp tomorrow afternoon. What is driving the change, how spatially uniform is it, and how confident is the forecast?
+> What did the 48-hour GFS forecast predict for this event, and how wrong was it?
 
-**The agent might use WFG**
+Old GFS initializations stay `dataset: "gfs"` and route to the matching archive. WFG can compare them with later GFS analysis or NOAA IGRA radiosondes, and can summarize bias, MAE and RMSE over bounded samples.
 
-`query_atmosphere` with GEFS points/time range → `query_atmosphere` with a GEFS transect → `compare_runs`
+## Datasets
 
-**Example agent interpretation**
+| Public dataset | Meaning | Key semantics |
+| --- | --- | --- |
+| `gfs` | NOAA deterministic GFS | 0.25° default / 0.5° optional; operational data and archived forecasts share one public identity |
+| `gefs` | NOAA GEFS | member-first operational ensemble; explicit `forecast.kind: "reforecast"` selects the GEFSv12 retrospective population |
+| `ifs` | ECMWF deterministic IFS | 0.25° Open Data forecast with native ECMWF run/cadence semantics |
+| `ifs-ens` | ECMWF IFS ENS | 50 perturbations `p01`–`p50`; deterministic IFS is the Cycle-50r1 unperturbed control |
+| `gfs-analysis` | historical GFS Grid 4 analysis | deterministic analyzed state with analysis-time rather than forecast-lead semantics |
 
-> The ramp is associated with a broad strengthening of the low-level flow rather than one isolated grid point. Coastal samples strengthen first and most strongly, while points farther inland lag. Winds aloft increase at the same time, supporting a synoptic-scale interpretation rather than purely local mixing. GEFS spread is larger around the timing of the ramp than around the direction of change, so the bigger uncertainty is *when* the increase arrives rather than *whether* the regional flow strengthens.
+NOAA IGRA is available as a **verification reference**, not as a fake gridded model dataset.
 
-WFG does not contain turbine power curves, wake models, availability assumptions, or a generation model. Converting atmospheric conditions into expected MW belongs to the consuming application.
+For source inventories, cadence, member sets and archive details, start with [the documentation index](docs/README.md).
 
-## Current model support
+## One core, two equal surfaces
 
-WFG exposes deterministic **GFS 0.25° and 0.5°** (`0p25` default), member-first **GEFS**, deterministic **ECMWF IFS 0.25°**, and **ECMWF IFS ENS 0.25°**. Deterministic IFS has the broad spatiotemporal/diagnostic surface; IFS ENS supports member-first point and multi-point distributions, native-cadence point/multi-point time series, member-first diagnostics, and native-cadence diagnostic time series across all 50 perturbations.
+CLI and MCP are adapters over the same schemas and application services. Surface equivalence is tested explicitly.
 
-| Operation | GFS 0.25° / 0.5° | GEFS | IFS 0.25° | IFS ENS 0.25° |
-| --- | --- | --- | --- | --- |
-| Catalog and search | ✅ | ✅ | ✅ | ✅ |
-| Pressure profiles | ✅ deterministic | ✅ member distributions | ✅ deterministic | ✅ member distributions |
-| Mixed pressure/non-isobaric fields | ✅ | ✅ member-first bundles | ✅ point + instant | ✅ member-first point + multi-point bundles |
-| Raw and mixed-field time series | ✅ | ✅ | ✅ deterministic | ✅ member distributions |
-| Layer diagnostics | ✅ | ✅ per member → summarized | ✅ deterministic | ✅ per perturbation → summarized |
-| Whole-profile diagnostics | ✅ | ✅ per member → structural summaries | ✅ deterministic | ✅ structural member summaries |
-| Parcel / LCL / LFC / EL / CAPE / CIN | ✅ | ✅ per member → summarized | ✅ deterministic | ✅ per perturbation → summarized |
-| Diagnostic time series | ✅ layer/profile/parcel | ✅ layer/profile/parcel | ✅ layer/profile/parcel | ✅ compact member-first |
-| Multi-point queries | ✅ | ✅ | ✅ | ✅ member distributions |
-| Multi-point time series | ✅ | ✅ | ✅ | ✅ native 3h/6h cadence |
-| Transects | ✅ deterministic | ✅ ensemble-native mixed fields | ✅ deterministic mixed fields | ✅ member-first mixed fields |
-| Area statistics | ✅ deterministic | ✅ member-first spatial statistics | ✅ deterministic raw scalar | ✅ member-first spatial statistics |
-| Run-to-run comparison | ✅ deterministic deltas | ✅ distribution shifts | ✅ deterministic deltas | ✅ distribution shifts, 6h/12h stride |
-| Scalar ensemble distribution | — | ✅ | — | ✅ 50 perturbations |
-| Aligned GFS-vs-GEFS comparison | ✅ | ✅ | — | — |
-| Aligned GFS-vs-IFS comparison | ✅ deterministic deltas | — | ✅ deterministic deltas | — |
-| Aligned GEFS-vs-IFS ENS comparison | — | ✅ distribution shifts | — | ✅ distribution shifts |
+| Operation | CLI | MCP |
+| --- | --- | --- |
+| Discover capabilities | `catalog` | `search_catalog` |
+| Query atmospheric state | `query` | `query_atmosphere` |
+| Derive meteorology | `diagnose` | `diagnose_atmosphere` |
+| Compare forecast cycles | `compare-runs` | `compare_runs` |
+| Compare datasets | `compare-datasets` | `compare_datasets` |
+| Verify forecasts | `verify` | `verify_forecast` |
+| Search historical analogs | `analogs` | `find_analogs` |
 
-GEFS also supports control `c00` plus perturbed members `p01`–`p30`, native three-hour output through `f384`, mixed pressure/non-isobaric field bundles, and opt-in member payloads for auditability. Field-only requests automatically use NOAA's `pgrb2s` 0.25° selected-field product through `f240`; pressure-level and mixed requests use `pgrb2a` 0.5°, and field ranges extending beyond `f240` stay on 0.5° for the whole range. Result provenance reports the actual product and horizontal grid.
+Administrative index build/backfill remains CLI-only on purpose; it is not part of the normal weather-query surface.
 
-ECMWF **IFS 0.25°** is exposed as `ifs`; **IFS ENS 0.25°** is `ifs-ens`. Both use official Open Data indexed byte-range access with bounded mirror retry/failover. Under Cycle 50r1 the products deliberately have different horizons: deterministic `oper/fc` runs to `f240` at 00/12Z and `f90` at 06/18Z, while perturbed `enfo/ef` runs to `f360` and `f144` respectively. `ifs-ens` represents the 50 perturbed members `p01`–`p50`; the unperturbed control is now identical to deterministic `ifs`, so WFG does not invent a 51st ENS member. See [IFS access](docs/IFS.md).
+## What the engine covers
 
-Historical **GFS Grid 4 0.5° analysis** is exposed as `gfs-analysis`, through the same `query` / `diagnose` CLI operations and `query_atmosphere` / `diagnose_atmosphere` MCP tools. It covers profiles, time series, diagnostics, parcels, multi-point queries, multi-point time series, transects and native bbox area statistics while preserving analysis-time semantics and NCEI provenance.
+The common language composes a fairly broad atmospheric surface:
 
-Historical **GFS forecasts** do not add another public dataset. Keep `dataset: "gfs"`, provide an explicit old forecast run, and select `forecast.grid` when needed. `0p25` routes to the NCAR/GDEX d084001 0.25° archive (`gfs_0p25_forecast_archive`), available from 2015-01-15 with native 3-hour output through +240 h and 12-hour output from +252 h through +384 h. `0p50` routes to NOAA NCEI Grid 4 (`gfs_grid4_forecast_0p5_archive`), beginning 2006-10-10 with native 3-hour output through +192 h. Direct online archive availability can vary. Both paths preserve run, valid time, lead, grid and archive provenance across unified state queries and layer/profile/parcel diagnostics.
+- pressure profiles and mixed pressure/non-isobaric fields;
+- native-cadence time ranges;
+- multi-point queries and multi-point ranges;
+- great-circle transects;
+- bounded area statistics;
+- layer diagnostics such as lapse rate, wind shear and potential-temperature gradient;
+- whole-profile freezing-level and inversion diagnostics;
+- parcel/LCL/LFC/EL/CAPE/CIN diagnostics where the source fields support them;
+- deterministic run deltas and ensemble distribution shifts;
+- aligned GFS↔GEFS, GFS↔IFS, GEFS↔IFS ENS and IFS↔IFS ENS comparisons;
+- historical analog search and archived-forecast verification.
 
-Forecast verification can use either the later `gfs-analysis` model state or a real **NOAA IGRA v2.2 radiosonde** reference. IGRA remains a verification reference rather than a public gridded atmospheric dataset: WFG selects a nearby or explicit sounding station, samples the archived GFS forecast at the sounding location, and compares only pressure levels that were actually observed. No vertical interpolation is hidden inside the verification result.
+Not every dataset implements every line. `catalog` / `search_catalog` is the source of truth for what a particular dataset and forecast population supports.
 
-The same `verify_forecast` operation also supports **bounded forecast-skill summaries** against either reference. Use a time range plus up to three lead times; WFG samples at most eight nominal verification times (24 forecast evaluations maximum), keeps failed cases explicit, and returns count, signed bias, MAE and RMSE by lead × pressure × field. `gfs-analysis` summaries remain same-grid 0.5° analysis-minus-forecast comparisons; IGRA summaries remain observation-minus-forecast and report the radiosonde stations used. Wind-direction errors use shortest signed angular differences.
+## Semantics are part of the API
 
-For larger verification studies, `wfg index verification-backfill` materializes atomic cases into a local JSONL corpus and `wfg index verification-summary` aggregates multi-year or month-filtered seasonal skill with **zero NOAA requests**. Coverage is reported explicitly, so partially materialized periods stay distinguishable from complete samples. This remains CLI-side administration; it does not expand the seven-tool MCP surface.
+WFG is opinionated about a few things that are easy to get subtly wrong:
 
-## The design rule
+- **Ensemble physics is member-first.** Nonlinear diagnostics are computed inside each GEFS/IFS ENS member before aggregation.
+- **Spread is not calibrated uncertainty.** Member fractions and ensemble spread are reported as raw model evidence unless a dedicated calibrated layer says otherwise.
+- **History is not relabeled as “current”.** Archived GFS forecasts retain their old initialization and lead; GFS analysis retains analysis-time semantics; GEFSv12 reforecasts are explicitly retrospective forecasts, not archived operational GEFS.
+- **Provenance stays visible.** Results keep run, valid time, sampled grid, source product and archive/backend information.
+- **Unsupported means unsupported.** The engine fails at capability boundaries instead of silently substituting another model, grid or physical meaning.
 
-> **Unify operations and physics; preserve model semantics.**
+The deeper reasoning is documented in [Architecture](docs/ARCHITECTURE.md).
 
-The same physical kernels are reused where that is scientifically valid. But deterministic GFS values are not forced into ensemble-shaped objects, and GEFS member distributions are not flattened into fake confidence scores.
+## Data access without the plumbing leaking into the query
 
-In particular:
+WFG selects only the upstream messages needed for a request, caches immutable slices and decodes locally.
 
-- nonlinear GEFS diagnostics are calculated **member by member before aggregation**;
-- member fractions and spread are labeled as raw ensemble evidence, not calibrated probability or uncertainty;
-- pressure levels, temporal semantics, valid times, cycles, sampling and provenance stay explicit;
-- unsupported combinations fail explicitly rather than being guessed;
-- WFG does not own activity-specific scores or safety judgments.
+Operational point/profile access favors indexed byte-range reads from NOAA AWS Open Data and ECMWF Open Data. Bounded GFS areas use NOMADS geographic subsetting where that is materially better. Historical products route to NCEI or NCAR/GDEX as appropriate.
 
-The [architecture guide](docs/ARCHITECTURE.md) goes deeper into the shared core, model adapters, member-first computation, source strategy, caching, and public surfaces.
+Provider etiquette is also source-specific: NOMADS retains its courtesy pacing, while AWS, ECMWF, NCEI, GDEX and IGRA use independent bounded-concurrency policies with transient retry/backoff. A slow provider does not impose its policy on unrelated sources.
 
-## Public API
-
-WFG exposes the dataset-oriented query vocabulary documented in [UNIFIED_API.md](docs/UNIFIED_API.md).
-
-Normal atmospheric access is expressed as:
-
-```text
-dataset × geometry × time × selection
-```
-
-with short dataset IDs `gfs`, `gefs`, `ifs`, `ifs-ens`, and `gfs-analysis`. The same query structure therefore works for a deterministic forecast, an ensemble forecast, an archived GFS forecast, or an archived analysis while each result preserves its native deterministic/ensemble and forecast/analysis semantics. An archived forecast remains `gfs`; the explicit old `forecast.run` selects the historical state.
-
-The MCP vocabulary is intentionally small:
-
-- `search_catalog`
-- `query_atmosphere`
-- `diagnose_atmosphere`
-- `compare_runs`
-- `compare_datasets`
-- `verify_forecast`
-- `find_analogs`
-
-The CLI mirrors the same concepts with `catalog --dataset ...`, `query`, `diagnose`, `compare-runs`, `compare-datasets`, `verify`, and `analogs`.
-
-## CLI
-
-The CLI mirrors the same operation vocabulary. Dataset choice is always explicit through `--dataset`.
-
-A deterministic GFS profile:
-
-```bash
-wfg query \
-  --dataset gfs \
-  --lat 50.08 --lon 14.43 \
-  --at 2026-08-24T12:00:00Z \
-  --vars temperature,relative_humidity,wind \
-  --levels 1000,925,850,700,500 \
-  --json
-```
-
-An old forecast keeps `gfs` and selects the historical initialization:
-
-```bash
-wfg query \
-  --dataset gfs \
-  --grid 0p25 \
-  --run 2019-12-24T12:00:00Z \
-  --lat 50.08 --lon 14.43 \
-  --at 2019-12-26T18:00:00Z \
-  --vars temperature,relative_humidity,wind \
-  --levels 1000,925,850,700,500 \
-  --json
-```
-
-The same query against historical analysis only changes the dataset and time:
-
-```bash
-wfg query \
-  --dataset gfs-analysis \
-  --lat 50.08 --lon 14.43 \
-  --at 2019-12-26T18:00:00Z \
-  --vars temperature,relative_humidity,wind \
-  --levels 1000,925,850,700,500 \
-  --json
-```
-
-An ensemble parcel diagnostic:
-
-```bash
-wfg diagnose \
-  --dataset gefs \
-  --lat 45.80 --lon 11.77 \
-  --at 2026-08-24T12:00:00Z \
-  --kind parcel \
-  --parcel surface_2m \
-  --levels 1000,925,850,700,500,250,200 \
-  --quantiles 0.1,0.5,0.9 \
-  --json
-```
-
-Local analog-index maintenance is intentionally separate from weather queries:
-
-```bash
-wfg index build --dataset gfs-analysis ...
-wfg index backfill --dataset gfs-analysis ...
-```
-
-Run `wfg --help` or `npx weather-for-grown-ups --help` for the complete command surface.
-
-## MCP
-
-MCP exposes exactly seven atmospheric tools:
-
-- `search_catalog`
-- `query_atmosphere`
-- `diagnose_atmosphere`
-- `compare_runs`
-- `compare_datasets`
-- `verify_forecast`
-- `find_analogs`
-
-Both transports expose exactly the same tool set:
-
-- **stdio** — `npx weather-for-grown-ups mcp`
-- **Streamable HTTP** — `npx weather-for-grown-ups mcp-http`
-
-The HTTP server defaults to `127.0.0.1:3000`, serves MCP at `/mcp`, and exposes `/healthz`. Read [INSTALL.md](docs/INSTALL.md) before exposing it remotely.
-
-## Data access
-
-WFG selects only the GRIB messages needed for a query, caches immutable upstream slices, decodes locally, and performs physical transforms and aggregation in the TypeScript core.
-
-- GFS source routing is automatic by default: point/profile, time-series, multi-point, transect, and run-comparison access uses NOAA AWS Open Data selected-message byte ranges; bounded area queries use NOAA NOMADS geographic subsetting. `--source` remains an explicit override where that geometry supports it, and result provenance reports the resolved backend.
-- GEFS uses NOAA AWS Open Data `.idx` inventories and byte-range access per member. Pressure/mixed selections use `pgrb2a` 0.5°; eligible field-only selections use `pgrb2s` 0.25° through `f240`.
-- The npm package ships with a GRIB2 decoder; native `wgrib2` remains an optional compatibility/debug path.
-- Historical GFS analysis uses NOAA NCEI THREDDS/NCSS: grid-as-point for point/profile operations and native bbox/grid subsets for area statistics.
-- Historical GFS forecasts keep the public `gfs` identity and route by grid: 0.25° uses NCAR/GDEX d084001 through THREDDS/NCSS, while 0.5° uses NOAA NCEI Grid 4 through THREDDS/NCSS. Direct online availability varies; older Grid 4 files may require NCEI HAS retrieval.
-- Upstream etiquette is provider-specific: NOMADS keeps an 11-second cross-process courtesy interval, NCEI THREDDS/NCSS is bounded to 2 concurrent requests, NCAR/GDEX to 4, and IGRA downloads to 4. NOAA AWS and ECMWF cloud/direct access are bounded separately without inheriting the NOMADS delay. Transient 429/5xx responses use exponential backoff with jitter and honor `Retry-After`.
+Those are implementation and provenance concerns—not new public query dimensions.
 
 ## Documentation
 
-The repository root intentionally stays small. Detailed documentation lives in [`docs/`](docs/README.md).
+The root README is the product overview. Detailed reference material lives under [`docs/`](docs/README.md).
 
-Start with:
+Start here:
 
-- [Installation and distribution](docs/INSTALL.md)
+- [Installation and deployment](docs/INSTALL.md)
+- [Unified atmospheric API](docs/UNIFIED_API.md)
 - [Architecture](docs/ARCHITECTURE.md)
-- [GEFS ensemble access](docs/GEFS_ENSEMBLE.md)
-- [ECMWF IFS and ENS access](docs/IFS.md)
-- [Catalog search](docs/CATALOG_SEARCH.md)
-- [Testing](docs/TESTING.md)
-- [Meteorology validation](docs/METEOROLOGY_VALIDATION.md)
+- [GEFS and GEFSv12 reforecast semantics](docs/GEFS_ENSEMBLE.md)
+- [ECMWF IFS / IFS ENS semantics](docs/IFS.md)
+- [Historical GFS, archives and verification](docs/HISTORY.md)
+- [Testing](docs/TESTING.md) and [meteorology validation](docs/METEOROLOGY_VALIDATION.md)
+- [Release notes](docs/RELEASES.md)
+
+## Scope
+
+WFG exposes numerical-model evidence and meteorological diagnostics. It does **not** own activity-specific scores, turbine power curves, route decisions, flight/summit safety judgments or calibrated probabilities unless such a layer is explicitly designed and validated.
 
-Feature-specific implementation and semantics notes are indexed in [docs/README.md](docs/README.md).
+That separation is intentional: the tool should be reusable by many agents and applications without smuggling one application's judgment into the weather core.
 
 ## License
 
-MIT. NOAA model data and separately distributed decoder components retain their own upstream terms and licenses; see [installation and distribution](docs/INSTALL.md) for packaging details.
+MIT. See [LICENSE](LICENSE).

package/dist/{cache/file-access-policy.d.ts → access/access-policy.d.ts}

@@ -8,6 +8,11 @@ export interface UpstreamAccessPolicyDefinition {
     minIntervalMs: number;
     staleLockMs?: number;
 }
+/**
+ * Provider etiquette and concurrency limits live here, independently of cache
+ * implementation. A source/cache client may reuse these policies, but it must
+ * not invent provider pacing of its own.
+ */
 export declare const UPSTREAM_ACCESS_POLICIES: {
     readonly nomads: {
         readonly id: "nomads";
@@ -58,4 +63,3 @@ export declare class FileAccessPolicy implements UpstreamAccessPolicy {
     private statePath;
     private readState;
 }
-export declare function withLegacyCooldown(definition: UpstreamAccessPolicyDefinition, cooldownMs: number | undefined): UpstreamAccessPolicyDefinition;

package/dist/{cache/file-access-policy.js → access/access-policy.js}

@@ -3,42 +3,19 @@ import { join } from "node:path";
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export const DEFAULT_ACCESS_POLICY_STALE_LOCK_MS = 120_000;
 const DEFAULT_POLL_MS = 100;
+/**
+ * Provider etiquette and concurrency limits live here, independently of cache
+ * implementation. A source/cache client may reuse these policies, but it must
+ * not invent provider pacing of its own.
+ */
 export const UPSTREAM_ACCESS_POLICIES = {
-    nomads: {
-        id: "nomads",
-        maxConcurrency: 1,
-        minIntervalMs: 11_000,
-    },
-    noaaAws: {
-        id: "noaa-aws",
-        maxConcurrency: 8,
-        minIntervalMs: 0,
-    },
-    ecmwfCloud: {
-        id: "ecmwf-cloud",
-        maxConcurrency: 8,
-        minIntervalMs: 0,
-    },
-    ecmwfDirect: {
-        id: "ecmwf-direct",
-        maxConcurrency: 4,
-        minIntervalMs: 0,
-    },
-    nceiThredds: {
-        id: "ncei-thredds",
-        maxConcurrency: 2,
-        minIntervalMs: 0,
-    },
-    gdex: {
-        id: "gdex",
-        maxConcurrency: 4,
-        minIntervalMs: 0,
-    },
-    nceiIgra: {
-        id: "ncei-igra",
-        maxConcurrency: 4,
-        minIntervalMs: 0,
-    },
+    nomads: { id: "nomads", maxConcurrency: 1, minIntervalMs: 11_000 },
+    noaaAws: { id: "noaa-aws", maxConcurrency: 8, minIntervalMs: 0 },
+    ecmwfCloud: { id: "ecmwf-cloud", maxConcurrency: 8, minIntervalMs: 0 },
+    ecmwfDirect: { id: "ecmwf-direct", maxConcurrency: 4, minIntervalMs: 0 },
+    nceiThredds: { id: "ncei-thredds", maxConcurrency: 2, minIntervalMs: 0 },
+    gdex: { id: "gdex", maxConcurrency: 4, minIntervalMs: 0 },
+    nceiIgra: { id: "ncei-igra", maxConcurrency: 4, minIntervalMs: 0 },
 };
 export class FileAccessPolicy {
     rootDir;
@@ -124,10 +101,9 @@ export class FileAccessPolicy {
         }
     }
     slotPath(slot) {
-        if (this.definition.maxConcurrency === 1) {
-            return join(this.rootDir, `${this.definition.id}.lock`);
-        }
-        return join(this.rootDir, `${this.definition.id}.slot-${slot}.lock`);
+        return this.definition.maxConcurrency === 1
+            ? join(this.rootDir, `${this.definition.id}.lock`)
+            : join(this.rootDir, `${this.definition.id}.slot-${slot}.lock`);
     }
     statePath() {
         return join(this.rootDir, `${this.definition.id}-state.json`);
@@ -141,16 +117,7 @@ export class FileAccessPolicy {
         }
     }
 }
-export function withLegacyCooldown(definition, cooldownMs) {
-    if (cooldownMs === undefined)
-        return definition;
-    return {
-        ...definition,
-        maxConcurrency: 1,
-        minIntervalMs: cooldownMs,
-    };
-}
 function isAlreadyExists(error) {
     return error instanceof Error && "code" in error && error.code === "EEXIST";
 }
-//# sourceMappingURL=file-access-policy.js.map
+//# sourceMappingURL=access-policy.js.map

package/dist/access/access-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-policy.js","sourceRoot":"","sources":["../../src/access/access-policy.ts"],"names":[],"mappings":"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"}

package/dist/access/http-fetch.d.ts

@@ -0,0 +1,13 @@
+import type { UpstreamAccessPolicy } from "./access-policy.js";
+import { type HttpRetryExecutionOptions } from "./http-retry.js";
+export interface RetryableFetchOptions extends HttpRetryExecutionOptions {
+    fetchFn?: typeof fetch;
+    accessPolicy?: UpstreamAccessPolicy;
+}
+/**
+ * Shared HTTP execution policy: provider concurrency/pacing is applied to every
+ * attempt, then transient HTTP/transport failures use the common retry policy.
+ * Callers retain responsibility for provider-specific success validation and
+ * response decoding.
+ */
+export declare function fetchWithRetry(input: string | URL, init: RequestInit | undefined, options?: RetryableFetchOptions): Promise<Response>;

package/dist/access/http-fetch.js

@@ -0,0 +1,21 @@
+import { runWithHttpRetry, } from "./http-retry.js";
+/**
+ * Shared HTTP execution policy: provider concurrency/pacing is applied to every
+ * attempt, then transient HTTP/transport failures use the common retry policy.
+ * Callers retain responsibility for provider-specific success validation and
+ * response decoding.
+ */
+export async function fetchWithRetry(input, init, options = {}) {
+    const fetchFn = options.fetchFn ?? globalThis.fetch;
+    const run = (operation) => options.accessPolicy?.run(operation) ?? operation();
+    const result = await runWithHttpRetry(async () => {
+        const response = await run(() => fetchFn(input, init));
+        return {
+            status: response.status,
+            retryAfter: response.headers.get("retry-after"),
+            response,
+        };
+    }, options);
+    return result.response;
+}
+//# sourceMappingURL=http-fetch.js.map

package/dist/access/http-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-fetch.js","sourceRoot":"","sources":["../../src/access/http-fetch.ts"],"names":[],"mappings":"AACA,OAAO,EACL,gBAAgB,GAEjB,MAAM,iBAAiB,CAAC;AAOzB;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,KAAmB,EACnB,IAA6B,EAC7B,UAAiC,EAAE;IAEnC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,UAAU,CAAC,KAAK,CAAC;IACpD,MAAM,GAAG,GAAG,CAAI,SAA2B,EAAE,EAAE,CAC7C,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC,SAAS,CAAC,IAAI,SAAS,EAAE,CAAC;IAEtD,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,KAAK,IAAI,EAAE;QAC/C,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;QACvD,OAAO;YACL,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,UAAU,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;YAC/C,QAAQ;SACT,CAAC;IACJ,CAAC,EAAE,OAAO,CAAC,CAAC;IAEZ,OAAO,MAAM,CAAC,QAAQ,CAAC;AACzB,CAAC"}

package/dist/{sources → access}/http-retry.d.ts

@@ -2,6 +2,13 @@ export declare const DEFAULT_HTTP_RETRY_BASE_DELAY_MS = 500;
 export declare const DEFAULT_HTTP_RETRY_MAX_DELAY_MS = 10000;
 export declare const DEFAULT_HTTP_RETRY_MAX_ATTEMPTS = 3;
 export declare const DEFAULT_HTTP_RETRY_JITTER_RATIO = 0.2;
+export interface HttpRetryAttemptResult {
+    status: number;
+    retryAfter: string | null;
+}
+export interface HttpRetryExecutionOptions extends HttpRetryWaitOptions {
+    maxAttempts?: number;
+}
 export interface HttpRetryWaitOptions {
     baseDelayMs?: number;
     maxDelayMs?: number;
@@ -10,6 +17,8 @@ export interface HttpRetryWaitOptions {
     randomFn?: () => number;
 }
 export declare function isRetryableHttpStatus(status: number): boolean;
+export declare function isRetryableHttpTransportError(error: unknown): boolean;
 export declare function retryAfterMilliseconds(value: string | null, now?: number): number | undefined;
 export declare function exponentialBackoffMilliseconds(attempt: number, options?: Omit<HttpRetryWaitOptions, "sleepFn">): number;
+export declare function runWithHttpRetry<T extends HttpRetryAttemptResult>(operation: () => Promise<T>, options?: HttpRetryExecutionOptions): Promise<T>;
 export declare function waitBeforeHttpRetry(attempt: number, retryAfterHeader: string | null, options?: HttpRetryWaitOptions): Promise<void>;