weather-for-grown-ups 0.1.0

package/ARCHITECTURE.md

@@ -0,0 +1,295 @@
+# Architecture
+
+Weather for Grown Ups is primarily a **numerical-weather-model data-access product**, not a forecasting or interpretation layer.
+
+```text
+NOAA GFS / GEFS
+      ↓
+model-specific catalogs, run semantics and source adapters
+      ↓
+normalized atmospheric states / profile adapters
+      ↓
+shared meteorological kernels and composition primitives
+      ↓
+deterministic result OR ensemble member aggregation
+      ↓
+model-discriminated shared contracts
+      ↓
+CLI / MCP stdio / MCP Streamable HTTP
+      ↓
+agent interpretation
+```
+
+## Core principles
+
+The core owns:
+
+- explicit model identity, model capabilities and product semantics;
+- canonical variable/field/member names;
+- run, valid-time, forecast-hour and native-cadence semantics;
+- authoritative published pressure levels and explicit non-isobaric vertical semantics;
+- instantaneous / accumulation / average temporal semantics where applicable;
+- query planning and dependency expansion;
+- upstream access, pacing and immutable-slice caching;
+- GRIB decoder abstraction;
+- normalized typed atmospheric values and provenance;
+- model-independent physical transforms;
+- spatial/temporal compositions;
+- explicit ensemble statistics and aggregation semantics.
+
+The core is the product. CLI and MCP are adapters over it, not separate implementations.
+
+The key rule is:
+
+> **Unify operations and physics; preserve model semantics.**
+
+A common operation does not imply identical source inventory or identical result shape. GFS and GEFS can both implement `profile`, `timeseries`, or `layer_diagnostics`, while deterministic GFS returns one state and GEFS returns a member distribution.
+
+## Model capability boundary
+
+`src/catalog/models.ts` is the explicit capability registry for atmospheric model adapters. It records model kind, grid spacing, forecast horizon and supported operations.
+
+This prevents two bad failure modes:
+
+1. mechanically copying every GFS endpoint into a GEFS namespace even when ensemble semantics should differ;
+2. pretending GEFS supports a GFS operation when the required upstream fields are not actually available.
+
+Unsupported capabilities are data in the model catalog, not accidental runtime surprises. Adding a future model such as ICON or ECMWF/AIFS should mean implementing model-specific inventory/source/run adapters behind stable atmospheric operation boundaries rather than creating a new API tree from scratch.
+
+## Normalized pressure-profile boundary
+
+`ProfileLevel` is the normalized pressure-state representation consumed by deterministic meteorology.
+
+`src/core/atmospheric-profile.ts` defines a model-independent `AtmosphericProfileSnapshot` around those levels. Deterministic GFS already naturally produces this shape. GEFS member profiles are adapted into it member-by-member:
+
+```text
+GFS raw/profile service ───────────────┐
+                                      ├─> normalized ProfileLevel[] ─> shared physics
+GEFS ensemble profile ─> member split ┘
+```
+
+The adapter maps GEFS normalized raw values such as temperature, U/V wind and geopotential height to the same typed level fields used by deterministic diagnostics. The physical layer therefore does not need to know whether a level originated in GFS or one GEFS member.
+
+This boundary is intentionally below ensemble aggregation. A nonlinear meteorological diagnostic is evaluated on each ensemble member's atmospheric state first; WFG does not calculate diagnostics from the ensemble-mean profile unless a future operation explicitly defines that different quantity.
+
+## Shared diagnostic kernels
+
+Low-level formulas already live under `src/derived/`. `src/core/pressure-diagnostics.ts` now owns model-independent orchestration over normalized pressure levels for:
+
+- environmental temperature lapse rate;
+- vector wind shear;
+- potential-temperature gradient;
+- freezing-level crossings;
+- sampled temperature-inversion layers.
+
+The deterministic GFS `LayerDiagnosticsService` and `ProfileDiagnosticsService` call these kernels rather than owning parallel formula/traversal logic.
+
+GEFS layer diagnostics call the **same** layer kernel once per requested member. Because geopotential heights differ between members, physical layer depth is member-specific too. Only after each member's calculation is complete are diagnostic outputs and depth summarized across the ensemble.
+
+Parcel mechanics remain model-independent under `derived/parcel-diagnostics.ts`, but the current GEFS product contract does not yet provide the complete dependency parity needed to expose the GFS parcel operation. The model capability catalog therefore marks parcel diagnostics unsupported for GEFS instead of fabricating parity.
+
+## Shared ensemble statistics
+
+`src/core/ensemble-statistics.ts` is the one distribution implementation used by raw scalar GEFS fields, profile cells and diagnostic outputs.
+
+It defines:
+
+- arithmetic mean;
+- population standard deviation;
+- min/max;
+- caller-selected quantiles using linear interpolation over sorted members;
+- raw >= threshold member fractions.
+
+Threshold fractions retain the interpretation marker `raw_member_fraction_not_calibrated_probability`. Calibration, model weighting, climatological correction and decision-specific interpretation remain outside this primitive.
+
+Centralizing these mechanics ensures that “p50” or “population spread” means the same thing whether the distribution contains raw temperature, wind shear, layer depth, or another future member-derived quantity.
+
+## Unified operation dispatch
+
+The canonical internal operation contracts are model-discriminated unions rather than flattened result objects.
+
+Examples:
+
+```text
+AtmosphericProfileRequest
+  ├─ model=gfs_0p25  + GFS profile query
+  └─ model=gefs_0p50 + GEFS ensemble-profile query
+
+AtmosphericProfileResult
+  ├─ deterministic GFS profile
+  └─ GEFS profile distributions/member data
+```
+
+Equivalent dispatch boundaries exist for time series and layer diagnostics.
+
+Services:
+
+- `AtmosphericProfileService`
+- `AtmosphericTimeSeriesService`
+- `AtmosphericLayerDiagnosticsService`
+
+select the model adapter and validate the returned model-specific schema. They intentionally do **not** coerce results into a lowest-common-denominator `value` object.
+
+## Deterministic GFS 0.25°
+
+### Catalog-driven derivation
+
+Derived variables declare raw GFS dependencies in the shared catalog. Query planning expands those dependencies before source access, validates raw completeness, and only then computes the requested value locally. This keeps NOAA access minimal and makes the same derivation automatically available to every compatible GFS composition.
+
+Moist thermodynamic variables remain ordinary per-level derived variables. Wet-bulb temperature and equivalent potential temperature both depend on temperature plus specific humidity, with pressure supplied by the isobaric coordinate. Equivalent potential temperature uses the Bolton (1980) formulation. Wet-bulb temperature is a deterministic same-pressure adiabatic-saturation enthalpy solve.
+
+### Vertical diagnostics
+
+Pressure-layer diagnostics explicitly name a lower-altitude/higher-pressure surface and an upper-altitude/lower-pressure surface. One minimal two-level profile supplies endpoints. Height-normalized quantities use geopotential-height difference rather than treating pressure difference as geometric depth.
+
+Whole-profile diagnostics are explicit about sampling. The caller chooses published pressure levels. WFG fetches the dependency union once, returns sampled levels, and derives freezing-level crossings or inversion structure locally. It does not imply unresolved vertical structure between pressure levels never requested.
+
+### Parcel diagnostics
+
+Parcel choice is part of the physics, so WFG has no ambiguous generic CAPE tool. Callers explicitly select `surface_2m`, `mixed_layer_100hpa`, or `most_unstable_300hpa`.
+
+One profile request obtains pressure-level temperature, specific humidity and geopotential height together with required surface/2 m fields. The surface parcel initializes from GFS surface pressure/geopotential height with 2 m temperature and humidity. The mixed-layer parcel uses pressure-weighted mean potential temperature and mixing ratio over the exact lowest 100 hPa. The most-unstable parcel selects the sampled state with maximum Bolton equivalent potential temperature in the lowest 300 hPa.
+
+Ascent is dry adiabatic to the Bolton LCL and pseudo-adiabatic above it using deterministic numerical integration in log pressure. Environmental values are interpolated in log pressure. Buoyancy compares parcel and environmental **virtual temperature**; zero-buoyancy crossings are inserted before pressure-coordinate CAPE/CIN integration. Raw environmental levels and the complete parcel path remain in the single-time result for auditability.
+
+### Spatial and temporal composition
+
+`BatchPointsService` is the efficient same-time/multi-location primitive. It resolves one GFS run, downloads/reuses one selected-message AWS slice, then samples all requested coordinates locally.
+
+`TransectService` composes that primitive: it generates evenly spaced great-circle coordinates, delegates one batch request, and attaches along-track distance.
+
+`PointsTimeSeriesService` composes batch requests across native GFS forecast steps, reusing one selected-message slice per step. `TimeSeriesService` is the single-point field equivalent. `RunComparisonService` holds valid time constant and compares consecutive six-hour cycles with deterministic delta rules.
+
+`DiagnosticTimeSeriesService` composes existing single-time layer, whole-profile and parcel services across the native GFS time axis. Query-aware `latest` is resolved once against the complete valid-time range and exact raw dependencies; every step then receives that explicit cycle so a series cannot drift between runs.
+
+Area summaries deliberately use a different path. A bounded NOMADS subset is decoded locally and reduced to statistics; the raw grid is never returned.
+
+## GEFS 0.5° ensemble foundation
+
+GEFS remains a separate **model adapter**, not a boolean/member option inside GFS source code.
+
+### Separate inventory and run semantics
+
+`src/catalog/gefs.ts` declares supported control/perturbed members and the current `pgrb2a` variable/pressure combinations. GEFS schemas validate the requested Cartesian selection before source access.
+
+`GefsLatestRunResolver` is query-aware over member availability. Starting from the newest six-hour cycle that could precede the requested valid time, it walks older cycles until every selected member has the required forecast file. Range resolution fixes one cycle across complete ensemble time-series intervals.
+
+The current WFG GEFS contract uses native three-hour output from `f000` through `f384`. Upstream changes/extensions are adopted only by explicit contract changes and tests.
+
+### Member-aware source access
+
+`GefsS3SubsetCache` addresses immutable member-specific GEFS objects in NOAA AWS Open Data. For profile/diagnostic selections it:
+
+1. fetches and caches the member `.idx` inventory;
+2. selects all requested GRIB variable/pressure messages;
+3. downloads only those byte ranges;
+4. stitches and caches one immutable multi-message subset for that selection/member;
+5. decodes the point once with the shared `Wgrib2Decoder`.
+
+Range downloads are bounded within each member and member processing itself is bounded-concurrent. Repeated operations naturally reuse immutable profile slices.
+
+### Ensemble profile and diagnostics
+
+`GefsEnsembleProfileService` produces raw normalized member profiles plus cell-wise distributions. Member profiles are omitted from public responses by default but can be requested for audit/composition.
+
+`GefsLayerDiagnosticsService` is an example of the intended ensemble composition pattern:
+
+```text
+requested layer diagnostic
+        ↓
+expand shared diagnostic dependencies
+        ↓
+fetch one GEFS profile slice per member
+        ↓
+adapt each member to normalized ProfileLevel[]
+        ↓
+run same pressure-diagnostic kernel per member
+        ↓
+summarize member diagnostic outputs and layer depths
+```
+
+This is the template for future ensemble diagnostics.
+
+## Public surfaces
+
+CLI and MCP remain equal public surfaces over the same core, but they optimize for different callers.
+
+### CLI
+
+The CLI is operation-oriented. Shared operations use `--model gfs|gefs`:
+
+- `profile`
+- `timeseries`
+- `layer`
+
+GFS remains the default model for backward compatibility. Existing `ensemble-profile` and `ensemble-timeseries` commands remain explicit GEFS aliases but route through the same unified dispatchers rather than separate business logic.
+
+Other commands remain model-specific until the capability registry says otherwise.
+
+### MCP
+
+MCP intentionally retains explicit wrappers such as:
+
+- `get_gfs_profile`
+- `get_gefs_ensemble_profile`
+- `get_gfs_layer_diagnostics`
+- `get_gefs_layer_diagnostics`
+
+This keeps schemas small and obvious for agents, especially smaller models, while those wrappers delegate to shared underlying profile/diagnostic primitives. A unified core does not require one giant polymorphic MCP tool.
+
+Both MCP transports instantiate the same tool set:
+
+- **stdio** for local process-spawned clients;
+- **Streamable HTTP** for hosted/remote clients.
+
+The HTTP launcher is transport/infrastructure code only. It adds `/mcp`, `/healthz`, safe loopback defaults and Host/Origin protection; it does not define a separate atmospheric API.
+
+## Shared contracts
+
+Zod schemas define public query/result shapes. Shared operation schemas are discriminated unions over model-specific schemas, preserving exact semantics and validation rules for each model.
+
+A new model or operation is incomplete until:
+
+1. capability metadata is correct;
+2. model-specific inventory/source/run validation exists;
+3. normalized state adaptation is defined where physical kernels are reused;
+4. result semantics are explicit;
+5. CLI and MCP adapters are updated where the operation is public;
+6. deterministic tests and appropriate real-upstream smoke coverage exist.
+
+## Source strategy
+
+### NOMADS Grib Filter
+
+Use NOMADS where geographic subsetting materially reduces transfer: deterministic GFS single-point requests and bounded areas. All physical requests share the same cross-process courtesy limiter and cache boundary.
+
+### NOAA AWS Open Data — deterministic GFS
+
+Use GFS AWS `.idx` inventories and HTTP byte ranges where selected messages can be reused across locations or forecast steps: batch points, transects, field time series, diagnostic time series, multi-point time series, run comparison and aligned GFS-vs-GEFS work.
+
+### NOAA AWS Open Data — GEFS
+
+Use member-specific GEFS AWS `pgrb2a` objects and `.idx` byte ranges. Each requested member contributes a selected-message slice; sampling/diagnostics are bounded-concurrent and aggregation happens locally.
+
+AWS paths do not use the NOMADS courtesy limiter because they do not call the NOMADS scripted-filter service.
+
+## GRIB strategy
+
+WFG does not implement a GRIB2 parser in TypeScript. `Wgrib2Decoder` is a narrow adapter around NOAA's `wgrib2` executable. GFS and GEFS source layers produce minimal GRIB subsets; the rest of the codebase deals with typed meteorological values rather than GRIB internals.
+
+Docker is therefore the reproducible distribution boundary: the production image pins Node.js and `wgrib2`; the npm package remains lightweight for environments that already provide the decoder.
+
+## Rate limiting
+
+Every physical NOMADS request goes through `FileRateLimiter`. An atomically-created lock directory coordinates independent CLI and MCP processes on one machine. The completion timestamp is persisted separately, making the default 11-second cooldown apply across process lifetimes.
+
+A future hosted multi-replica deployment can replace this implementation with Redis/Postgres behind the same limiter boundary without changing meteorological services.
+
+## Core does not own
+
+- activity-specific weather scores;
+- subjective forecast interpretation;
+- calibrated probabilities unless an explicit calibration layer is designed and validated;
+- domain-specific safety judgments.
+
+Those belong to the consuming agent or a specialized application.

package/AREA_DISTRIBUTION.md

@@ -0,0 +1,66 @@
+# Rich bounded-area statistics
+
+The default `wfg area` / MCP `summarize_gfs_area` response remains the existing bounded min, max, and unweighted grid-point mean. Rich distribution statistics are opt-in and never return the raw GFS grid.
+
+## Optional outputs
+
+A caller may request:
+
+- percentiles in the range 0-100;
+- fractions of defined grid cells greater than or equal to (`gte`) or less than or equal to (`lte`) one or more thresholds;
+- representative min/max grid coordinates plus the number of cells tied at each extremum.
+
+All calculations use **defined GFS grid cells only** and are unweighted by cell area, matching the existing area mean semantics.
+
+Thresholds and returned percentile/extrema values use WFG's **normalized public output unit**. For example, a `temperature` / `temperature_2m` threshold of `15` means 15 °C, not 15 K.
+
+Percentiles use linear interpolation over the sorted defined grid values with zero-based position `(p / 100) * (n - 1)`. The response names this method explicitly as `linear_interpolation_sorted_defined_grid_points`.
+
+For extrema with ties, WFG returns the first deterministic grid point in wgrib2's output order together with `tiedGridPoints`; it does not imply that the extremum is spatially unique.
+
+## CLI
+
+```bash
+wfg area \
+  --west 12 --east 18 \
+  --south 48 --north 51 \
+  --valid 2026-08-24T12:00:00Z \
+  --var temperature \
+  --level 850 \
+  --percentiles 10,50,90 \
+  --gte 15 \
+  --lte 0 \
+  --extrema-locations \
+  --json
+```
+
+`--gte` and `--lte` are repeatable.
+
+The same options work for raw non-isobaric fields such as `low_cloud_cover_average`. Non-isobaric vertical and temporal semantics remain exact.
+
+## MCP
+
+`summarize_gfs_area` accepts optional structured fields:
+
+```json
+{
+  "percentiles": [10, 50, 90],
+  "thresholds": [
+    { "operator": "gte", "value": 15 },
+    { "operator": "lte", "value": 0 }
+  ],
+  "includeExtremaLocations": true
+}
+```
+
+Up to 20 percentiles and 20 thresholds may be requested in one call. Duplicate percentiles are rejected.
+
+## Execution path
+
+Ordinary area calls continue to use the fast local `wgrib2 -stats` path.
+
+Only when rich statistics are requested does WFG materialize the already geographically bounded field with `wgrib2 -spread -`. The NOMADS request is still cropped first and the existing `maxGridPoints` guard still applies before any network access. For non-isobaric fields, WFG first requires one exact GRIB record matching variable, vertical semantics, and instantaneous/accumulation/average semantics.
+
+The bounded grid values exist only inside the local calculation. WFG returns aggregates and optional extrema coordinates, not the grid itself.
+
+The NOMADS cache and shared 11-second courtesy limiter are unchanged.

package/AREA_SUMMARY.md

@@ -0,0 +1,88 @@
+# Bounded area summaries
+
+WFG exposes bounded geographic statistics without returning the raw GFS grid to the agent. The same primitive is available as CLI `wfg area` and MCP `summarize_gfs_area`.
+
+The result contains the number of defined grid cells plus minimum, maximum, and an **unweighted GFS grid-point mean**. The default request guard is 50,000 estimated 0.25° grid points.
+
+## Pressure-level field
+
+```bash
+wfg area \
+  --west 12 --east 18 \
+  --south 48 --north 51 \
+  --valid 2026-08-24T12:00:00Z \
+  --var temperature \
+  --level 850 \
+  --json
+```
+
+Pressure summaries accept one raw pressure-level variable and one published GFS pressure surface. Derived pressure variables are intentionally not accepted by the area primitive yet.
+
+## Non-isobaric field
+
+```bash
+wfg area \
+  --west 12 --east 18 \
+  --south 48 --north 51 \
+  --valid 2026-08-24T12:00:00Z \
+  --field low_cloud_cover_average \
+  --json
+```
+
+A field request accepts one **raw** non-isobaric catalog field. This includes surface, height-above-ground, named-layer, named-level, column, instantaneous, accumulation, and forecast-window-average products.
+
+The result includes:
+
+- the catalog field ID
+- exact public vertical semantics (`surface`, height AGL, named layer, or named level)
+- exact temporal semantics
+- normalized output field name and unit
+- bounded-area statistics
+
+For accumulation and average products, temporal metadata includes the GFS forecast-hour interval and absolute UTC start/end times.
+
+## Exact GRIB-record selection
+
+NOMADS Grib Filter selects variables and vertical levels, but one filtered response can still contain more than one temporal product for the same code and level. For example, low cloud cover can have both an instantaneous record and a forecast-window-average record.
+
+WFG therefore does not run statistics blindly over the filtered file. For non-isobaric area requests it first inspects the local `wgrib2 -s` inventory and requires exactly one record matching:
+
+1. GFS variable code
+2. exact GRIB vertical level text
+3. temporal semantics: instantaneous, accumulation, or average
+
+Only that record is passed to `wgrib2 -stats`. Missing and ambiguous matches fail explicitly.
+
+This is the same fail-closed philosophy used by point/profile field extraction: an instantaneous request must never silently become an average request simply because both share a variable code and named layer.
+
+## Unit normalization
+
+Statistics are normalized to the field catalog's public output unit after aggregation.
+
+Temperature records published in kelvin and exposed by WFG in degrees Celsius are shifted by 273.15 for mean/min/max. Numerically equivalent conversions such as precipitation `kg/m²` to liquid-water-equivalent `mm` preserve the numeric values.
+
+## Why derived wind is not supported yet
+
+Derived `wind_10m`, `wind_20m`, and similar fields are intentionally rejected for area summaries.
+
+Computing an area mean U and mean V and then deriving wind speed/direction is **not** equivalent to deriving wind at every grid cell and then aggregating those derived values. The latter requires a grid-aware derived-statistics path rather than the scalar `wgrib2 -stats` adapter used here.
+
+Until that path exists, WFG fails rather than returning a mathematically misleading area wind statistic.
+
+## Data access and pacing
+
+Area summaries use NOAA NOMADS because Grib Filter can crop the geographic region before transfer. Every physical download uses the same `NomadsCache` and cross-process `FileRateLimiter` as other NOMADS access.
+
+The default cooldown remains **11 seconds after a request completes**, deliberately conservative relative to NOAA's 10-second scripted-request guidance. Cache hits do not consume a limiter slot.
+
+## Geographic limits
+
+Current area constraints:
+
+- bbox coordinates must be within normal latitude/longitude bounds
+- west must be strictly less than east
+- south must be strictly less than north
+- antimeridian-crossing boxes are not supported yet
+- the default estimated-grid guard is 50,000 cells, raiseable explicitly within the schema maximum
+
+The mean is an unweighted grid-point mean, not an area-weighted spherical mean.

package/CATALOG_SEARCH.md

@@ -0,0 +1,61 @@
+# GFS catalog search
+
+WFG keeps the complete atmospheric catalog available through CLI `wfg catalog` and MCP `get_gfs_catalog`, but agents often need only a small subset of that surface. Catalog search provides a bounded, deterministic discovery path without changing the underlying catalog definitions.
+
+## CLI
+
+With no search/filter options, `wfg catalog` keeps the existing full-catalog behavior.
+
+```bash
+wfg catalog
+wfg catalog --json
+```
+
+Supplying any search/filter option switches the command to compact search/browse mode:
+
+```bash
+wfg catalog \
+  --search "low cloud cover" \
+  --sections fields \
+  --temporal average \
+  --limit 10 \
+  --json
+```
+
+Available filters:
+
+- `--search <text>` — tokenized case-insensitive search across IDs, descriptions, dependencies, output names/descriptions/units, GFS codes, source units, and vertical/temporal semantics.
+- `--sections <list>` — comma-separated subset of `variables`, `fields`, `layer_diagnostics`, `profile_diagnostics`, `parcel_definitions`.
+- `--classification <raw|derived>` — raw NOAA-backed definitions versus deterministic derived definitions/diagnostics.
+- `--temporal <instantaneous|accumulation|average>` — exact non-isobaric temporal semantics.
+- `--limit <number>` — returned matches, 1-100. Compact search defaults to 30.
+
+## MCP
+
+MCP exposes the same shared search core as `search_gfs_catalog`. `get_gfs_catalog` remains unchanged for clients that want the full catalog.
+
+Example structured input:
+
+```json
+{
+  "search": "wet bulb",
+  "sections": ["variables"],
+  "classification": "derived",
+  "limit": 10
+}
+```
+
+## Ranking and matching
+
+Search normalizes case, whitespace, underscores, hyphens, and diacritics. Every search token must occur somewhere in the searchable representation of an entry; WFG does not broaden a zero-result query.
+
+Ranking is deterministic. Exact IDs receive the strongest score, followed by ID prefixes/substrings and then token matches across IDs, descriptions, and structured metadata. Ties are resolved by stable section order and then ID.
+
+The result includes:
+
+- the resolved query and filters;
+- `totalMatches` before limiting;
+- `truncated` when more matches exist;
+- flat matches with section, ID, raw/derived classification, concrete kind, description, vertical semantics, optional temporal semantics/GFS metadata/dependencies, normalized outputs, and score.
+
+Search is local and deterministic. It performs no NOAA request and does not touch the NOMADS courtesy limiter.

package/DIAGNOSTIC_TIME_SERIES.md

@@ -0,0 +1,146 @@
+# Diagnostic time series
+
+WFG can evaluate its existing deterministic diagnostics across the native NOAA GFS 0.25° forecast timeline. This is a composition layer over the single-time diagnostic services, not a second meteorology implementation.
+
+## Why this exists
+
+Single-time diagnostic tools are ideal for inspecting one forecast instant in detail. Agents often need a different question shape:
+
+- when does CAPE peak?
+- how does LCL evolve through the afternoon?
+- when do sampled freezing-level crossings move upward or downward?
+- when do sampled inversion layers appear or disappear?
+- how does lapse rate or vector wind shear evolve between two fixed pressure surfaces?
+
+`diagnostic-timeseries` / `get_gfs_diagnostic_timeseries` answer those questions in one bounded request.
+
+## One diagnostic family per query
+
+The `diagnostic` selection is a discriminated union with three kinds.
+
+### Layer
+
+```json
+{
+  "kind": "layer",
+  "lowerPressureHpa": 850,
+  "upperPressureHpa": 700,
+  "diagnostics": ["temperature_lapse_rate", "wind_shear"]
+}
+```
+
+The pressure surfaces stay fixed for the full series.
+
+### Whole profile
+
+```json
+{
+  "kind": "profile",
+  "pressureLevelsHpa": [1000, 925, 850, 700, 500],
+  "diagnostics": ["freezing_level_crossings", "temperature_inversion_layers"]
+}
+```
+
+The supplied published pressure levels define vertical sampling resolution at every time step. WFG does not imply structure between levels the caller did not request.
+
+### Parcel
+
+```json
+{
+  "kind": "parcel",
+  "pressureLevelsHpa": [1000, 975, 950, 925, 900, 850, 800, 750, 700, 650, 600, 550, 500, 450, 400, 350, 300, 250, 200],
+  "parcel": "surface_2m"
+}
+```
+
+The explicit parcel definition and sampled environmental pressure levels stay fixed for the full series.
+
+## Time semantics
+
+The caller supplies an inclusive `startTime` and `endTime`. WFG returns every native GFS output falling inside that range:
+
+- hourly through forecast hour 120;
+- every three hours after forecast hour 120 through f384.
+
+`maxSteps` bounds the response before any diagnostic data access begins. The default is the same bounded value used by ordinary point time series.
+
+## Run selection
+
+The entire series uses one GFS model cycle.
+
+- `latest` resolves the newest cycle whose already-published data can satisfy the complete requested time range **and the exact raw dependencies required by the chosen diagnostic**;
+- `latest_complete` resolves the newest cycle published through f384;
+- an explicit 00Z/06Z/12Z/18Z run timestamp is reproducible.
+
+After resolution, the explicit run timestamp is passed to every underlying single-time diagnostic call. The model cycle therefore cannot drift halfway through a series.
+
+## Data access
+
+S3 is the default because diagnostic time series require several forecast files and NOAA AWS Open Data is the efficient multi-time path. WFG selects only the required GRIB messages from each forecast file and uses the normal immutable slice cache.
+
+`source: "nomads"` remains available explicitly. Every physical NOMADS request still passes through the shared file-backed 11-second courtesy limiter; diagnostic time series have no bypass.
+
+## Compact parcel steps
+
+The single-time `parcel` / `get_gfs_parcel_diagnostics` surface returns the complete parcel path and raw environmental profile for auditability.
+
+Repeating a full parcel path at every forecast step can make a time-series response unnecessarily large. Parcel time-series steps therefore keep:
+
+- parcel starting state;
+- LCL;
+- optional LFC and EL;
+- CAPE and CIN;
+- CAPE/CIN top semantics;
+
+but omit the repeated `parcelPath` array. Use the single-time parcel tool when a particular step needs the full audit trail.
+
+## CLI
+
+Layer diagnostics:
+
+```bash
+wfg diagnostic-timeseries \
+  --kind layer \
+  --lat 50.08 --lon 14.43 \
+  --start 2026-08-24T09:00:00Z \
+  --end 2026-08-24T18:00:00Z \
+  --lower 850 --upper 700 \
+  --diagnostics temperature_lapse_rate,wind_shear \
+  --json
+```
+
+Parcel diagnostics:
+
+```bash
+wfg diagnostic-timeseries \
+  --kind parcel \
+  --lat 50.08 --lon 14.43 \
+  --start 2026-08-24T09:00:00Z \
+  --end 2026-08-24T18:00:00Z \
+  --levels 1000,975,950,925,900,850,800,750,700,650,600,550,500,450,400,350,300,250,200 \
+  --parcel surface_2m \
+  --json
+```
+
+## MCP
+
+Tool: `get_gfs_diagnostic_timeseries`
+
+Example input:
+
+```json
+{
+  "latitude": 50.08,
+  "longitude": 14.43,
+  "run": "latest",
+  "startTime": "2026-08-24T09:00:00Z",
+  "endTime": "2026-08-24T18:00:00Z",
+  "diagnostic": {
+    "kind": "profile",
+    "pressureLevelsHpa": [1000, 925, 850, 700, 500],
+    "diagnostics": ["freezing_level_crossings", "temperature_inversion_layers"]
+  }
+}
+```
+
+The CLI and MCP adapters call the same core service and validate the same result contract.