Implement support for NWS weather stories

.gitignore

@@ -1,5 +1,6 @@
-# Compiled application binary
-weatherreporter
+# Compiled application binary and testing workspace
+/weatherreporter
+/workspace
 
 # ---> Go
 # If you prefer the allow list template instead of the deny list, see community template:
@@ -71,4 +72,3 @@ Icon
 Network Trash Folder
 Temporary Items
 .apdisk
-

.woodpecker/release.yml

@@ -0,0 +1,50 @@
+when:
+  - event: tag
+
+steps:
+  - name: build-release-assets
+    image: golang:1.25
+    commands:
+      - |
+        set -eu
+
+        version="$CI_COMMIT_TAG"
+        dist="dist"
+        pkg="gitea.maximumdirect.net/eric/weatherreporter/cmd/weatherreporter"
+
+        rm -rf "$dist"
+        mkdir -p "$dist"
+
+        build_binary() {
+          goos="$1"
+          goarch="$2"
+          suffix="$3"
+          output="$dist/weatherreporter-$version-$goos-$goarch$suffix"
+
+          CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" \
+            go build -trimpath -ldflags "-s -w -X gitea.maximumdirect.net/eric/weatherreporter/internal/buildinfo.Version=$version" \
+            -o "$output" "$pkg"
+        }
+
+        build_binary linux amd64 ""
+        build_binary linux arm64 ""
+        build_binary darwin amd64 ""
+        build_binary darwin arm64 ""
+        build_binary windows amd64 ".exe"
+        build_binary windows arm64 ".exe"
+
+  - name: publish-release
+    image: woodpeckerci/plugin-release
+    depends_on:
+      - build-release-assets
+    settings:
+      api_key:
+        from_secret: GITEA_RELEASE_TOKEN
+      files:
+        - dist/weatherreporter-*
+      checksum: sha256
+      checksum-file: SHA256SUMS
+      checksum-flatten: true
+      file-exists: skip
+      overwrite: false
+      prerelease: false

README.md

@@ -1,2 +1,21 @@
 # weatherreporter
 
+`weatherreporter` is a Go application for preparing human-facing weather
+reports from normalized forecast data. It builds structured briefing packages,
+runs them through `scriptorium`, and keeps inspectable artifacts under a local
+workspace.
+
+## Quickstart
+
+```sh
+weatherreporter generate daily --date 2026-05-29 --out ./daily.md
+```
+
+## Documentation
+
+- [CLI reference](docs/cli.md)
+- [Configuration reference](docs/config.md)
+- [Operations guide](docs/operations.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Architecture policy](docs/policy/architecture.md)
+- [Development policy](docs/policy/development.md)

cmd/weatherreporter/main.go

@@ -0,0 +1,16 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/cli"
+)
+
+func main() {
+	if err := cli.Run(context.Background(), os.Args[1:], os.Stdout, os.Stderr); err != nil {
+		fmt.Fprintf(os.Stderr, "weatherreporter: %v\n", err)
+		os.Exit(1)
+	}
+}

docs/cli.md

@@ -0,0 +1,90 @@
+# Weatherreporter CLI
+
+`weatherreporter` generates Markdown weather reports, runs scheduled report
+batches, and inspects previously generated artifacts.
+
+## Shortest Useful Command
+
+```sh
+weatherreporter generate daily --date 2026-05-29 --out ./daily.md
+```
+
+This loads configuration, fetches weather data, writes managed workspace
+artifacts, runs `scriptorium render` as a preflight check, runs
+`scriptorium run`, and writes an extra Markdown copy to `./daily.md`.
+
+## Commands
+
+```text
+weatherreporter --help
+weatherreporter generate daily [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--date YYYY-MM-DD]
+weatherreporter generate tomorrow [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
+weatherreporter generate three-day [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
+weatherreporter generate weekend [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
+weatherreporter generate storm [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] --start TIME --end TIME
+weatherreporter run morning [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH]
+weatherreporter run evening [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH]
+weatherreporter inspect reports [--config PATH] [--limit N]
+weatherreporter inspect metadata [--config PATH] RUN_ID
+weatherreporter inspect briefing [--config PATH] RUN_ID
+weatherreporter inspect data-package [--config PATH] RUN_ID
+weatherreporter inspect prior [--config PATH] RUN_ID
+weatherreporter inspect sources [--config PATH] RUN_ID
+```
+
+`generate` commands write briefing, data package, preflight, report, and
+metadata artifacts under the configured workspace. `generate storm` requires
+explicit event-window bounds with `--start` and `--end`.
+
+`run morning` generates Daily Today and the 3-Day Outlook, plus Weekend Outlook
+except on Sunday. `run evening` generates the Tomorrow Planning Brief. Batch
+runs continue independent reports after a failure, print a JSON summary to
+stdout, write compact status lines to stderr, and return nonzero when any report
+failed.
+
+`inspect` commands read existing workspace artifacts and emit JSON to stdout.
+They do not fetch weather data or invoke `scriptorium`.
+
+## Flags
+
+- `-h`, `--help`: show help.
+- `--config PATH`: load configuration from `PATH` instead of `/usr/local/etc/weatherreporter/config.yml`.
+- `--units VALUE`: override configured Weather API units for `generate` and `run`.
+- `--tz NAME`: override configured Weather API timezone for `generate` and `run`.
+- `--out PATH`: write an extra Markdown report copy for `generate` commands.
+- `--out-dir PATH`: write extra Markdown report copies for `run morning` and `run evening`.
+- `--date YYYY-MM-DD`: optional date for `generate daily`; defaults to the current local date in the configured timezone.
+- `--start TIME`: required start time for `generate storm`.
+- `--end TIME`: required end time for `generate storm`.
+- `--limit N`: maximum records for `inspect reports`; defaults to `20`, and `0` means no limit.
+
+Storm times accept `YYYY-MM-DDTHH:MM` in the configured timezone or RFC3339
+timestamps with explicit offsets.
+
+## Common Workflows
+
+```sh
+weatherreporter generate tomorrow --out ./tomorrow.md
+weatherreporter generate three-day --out ./three-day.md
+weatherreporter generate weekend --out ./weekend.md
+weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00 --out ./storm.md
+weatherreporter run morning --out-dir ./reports
+weatherreporter run evening --out-dir ./reports
+```
+
+## Inspection
+
+```sh
+weatherreporter inspect reports --limit 10
+weatherreporter inspect metadata 20260529T100000.000000000Z_daily_today
+weatherreporter inspect briefing 20260529T100000.000000000Z_daily_today
+weatherreporter inspect data-package 20260529T100000.000000000Z_daily_today
+weatherreporter inspect prior 20260529T100000.000000000Z_daily_today
+weatherreporter inspect sources 20260529T100000.000000000Z_daily_today
+```
+
+`inspect reports` lists recent generated runs with artifact paths and source
+warning counts. The other inspect commands require a RunID. `inspect prior`
+returns the prior comparable snapshot metadata selected from stored metadata, or
+`null` when none exists. `inspect sources` shows source provenance and source
+warnings without dumping full weather payloads.

docs/config.md

@@ -0,0 +1,128 @@
+# Weatherreporter Configuration
+
+Configuration is YAML. By default, `weatherreporter` reads:
+
+```text
+/usr/local/etc/weatherreporter/config.yml
+```
+
+Use `--config PATH` to load a different file. If the default file is absent,
+built-in defaults are used. If `--config PATH` points to a missing file, loading
+fails.
+
+Precedence is:
+
+1. CLI flags
+2. configuration file
+3. built-in defaults
+
+The implemented configuration overrides are `--units` and `--tz`. Output flags
+control report copies for the current command but do not change configuration
+files. Environment-variable configuration is not implemented.
+
+## Minimal Config
+
+See [examples/minimal-config.yml](../examples/minimal-config.yml).
+
+```yaml
+weather_api:
+  base_url: https://weather.api.example.com/
+```
+
+`weather_api.base_url` is required for commands that fetch weather data. Other
+fields fall back to defaults.
+
+## Production-Oriented Config
+
+See [examples/config.yml](../examples/config.yml). The example is loaded by the
+config test suite.
+
+## Field Reference
+
+### `weather_api`
+
+- `base_url`: absolute base URL for the Weather API. Required for generation and fetch workflows.
+- `timeout`: HTTP timeout duration. Default: `10s`.
+- `precision`: numeric precision query value. Default: `1`.
+- `units`: Weather API units query value. Default: `us`.
+- `timezone`: report timezone and Weather API timezone query value where supported. Default: `America/Chicago`.
+- `format`: Weather API response format. Must be `json`. Default: `json`.
+
+Timezone values may be IANA names, configured aliases such as `Chicago` and
+`Stl`, US timezone abbreviations, or UTC offsets such as `-5` and `+09:30`.
+
+### `location`
+
+`location` is descriptive prompt context included in briefing metadata and
+Scriptorium data packages. It does not select a Weather API endpoint or enable
+multiple configured forecast locations.
+
+- `id`: short local identifier. Default: `home`.
+- `name`: human-readable location name. Default: `Brentwood`.
+- `region`: broader forecast area context. Default: `St. Louis Metro`.
+
+The prompt-facing location object also includes `timezone`, derived from the
+effective `weather_api.timezone` after CLI overrides such as `--tz`.
+
+### `missing_source`
+
+- `default`: missing-source behavior for optional sources. One of `error`, `warn`, or `none`. Default: `warn`.
+- `sources`: optional map of source-specific overrides, using the same policy values.
+
+Hourly forecast data is required for generated reports. Optional sources and
+stub source slots use the missing-source policy.
+
+### `scriptorium`
+
+- `binary`: `scriptorium` executable name or path. Default: `scriptorium`.
+- `config_path`: optional Scriptorium config path passed to the adapter.
+- `profile`: optional Scriptorium profile passed to the adapter.
+- `timeout`: subprocess timeout. Default: `2m`.
+- `extra_args`: optional additional arguments passed to Scriptorium commands.
+
+### `workspace`
+
+- `root`: workspace root for managed artifacts. Default: `workspace`.
+- `snapshots_dir`: briefing and metadata directory under `workspace.root`. Default: `snapshots`.
+- `reports_dir`: managed Markdown report directory under `workspace.root`. Default: `reports`.
+- `data_packages_dir`: prompt input package directory under `workspace.root`. Default: `data-packages`.
+- `preflight_dir`: Scriptorium render output directory under `workspace.root`. Default: `preflight`.
+
+Workspace subdirectories must be relative paths that stay inside
+`workspace.root`.
+
+### `dayparts`
+
+`dayparts` is a list of named local-time windows used by forecast derivation.
+Each entry has:
+
+- `name`
+- `start`
+- `end`
+
+`start` and `end` use `HH:MM`. The default entries are overnight, morning,
+midday, afternoon, and evening.
+
+### `recent_change`
+
+- `temperature_degrees`: temperature change threshold. Default: `5`.
+- `precip_probability_points`: precipitation probability threshold. Default: `20`.
+- `wind_gust_miles_per_hour`: wind gust change threshold. Default: `10`.
+- `precip_timing_shift_minutes`: precipitation timing shift threshold. Default: `120`.
+
+Recent Changes are added to prompt input when a prior comparable briefing
+snapshot exists and a threshold is crossed.
+
+## Secrets
+
+Configuration files should not contain secrets. The current Weather API and
+Scriptorium integration settings do not require secret fields.
+
+## Maintained Examples
+
+- [examples/minimal-config.yml](../examples/minimal-config.yml): smallest
+  useful config for generation and fetching.
+- [examples/config.yml](../examples/config.yml): production-oriented config
+  covering implemented fields.
+
+Both example files are loaded by the config test suite.

docs/integrations/scriptorium.md

@@ -1,34 +1,17 @@
-# weatherreporter Subprocess Integration
+# Scriptorium Integration
+
+This document describes the external Scriptorium CLI contract used by
+`weatherreporter`.
 
 ## Purpose
 
-This document defines the supported subprocess contract for weatherreporter invoking Scriptorium through the public CLI.
+`weatherreporter` invokes Scriptorium as a subprocess to preflight prompt input
+and generate Markdown reports. This page documents the CLI surface the adapter
+uses, not the full Scriptorium product.
 
-This is a CLI contract, not an internal Go package integration.
+## Commands Used
 
-## Supported Commands
-
-weatherreporter should invoke:
-
-- `scriptorium run`
-- `scriptorium render`
-
-Use `run` for generation.
-
-Use `render` for preflight/debug output without LLM execution.
-
-## Recommended Invocation Shapes
-
-Run:
-
-```bash
-scriptorium run \
-  --prompt <prompt_id> \
-  --input data_package=<path> \
-  --out <artifact_path>
-```
-
-Render:
+Render preflight:
 
 ```bash
 scriptorium render \
@@ -37,78 +20,78 @@ scriptorium render \
   --format json
 ```
 
-weatherreporter may add:
+Report generation:
 
-- `--config <path>`
-- `--profile <profile_id>`
-- repeatable `--input name=path`
-- repeatable `--var name=value`
-- runtime overrides when explicitly needed (`--model`, `--llm-base-url`, `--timeout`, etc.)
+```bash
+scriptorium run \
+  --prompt <prompt_id> \
+  --input data_package=<path> \
+  --out <artifact_path>
+```
 
-## Config And Directory Behavior
+`weatherreporter` always passes prompt input as
+`--input data_package=<path>`. The data package is structured JSON created by
+`internal/promptinput`.
 
-weatherreporter can rely on resolved app config or pass explicit paths.
+## Configured Arguments
 
-- default config search order:
-  1. `/usr/local/etc/scriptorium/config.yml`
-  2. `/etc/scriptorium/config.yml`
-- explicit `--config` requires file existence and valid syntax
-- CLI flags override config values
+The adapter can prepend configured flags before prompt-specific arguments:
 
-## Profile Selection
+- `--config <path>` from `scriptorium.config_path`
+- `--profile <profile>` from `scriptorium.profile`
 
-Profile selection follows runner behavior:
+It appends `scriptorium.extra_args` after the built-in arguments. Extra
+arguments are passed directly as argv items.
 
-1. explicit `--profile`
-2. prompt `default_profile`
-3. error if neither is available
+`scriptorium.binary` selects the executable name or path. If unset inside the
+adapter, it falls back to `scriptorium`.
 
-weatherreporter should treat prompt/profile IDs as deployment configuration, not hardcoded logic.
+## Execution Behavior
 
-## Input And Variable Contract
+The adapter runs Scriptorium without shell interpolation. Arguments are passed
+through `exec.CommandContext`.
 
-- Inputs use repeated `--input name=path`.
-- Input names must match prompt definition input names.
-- Variables use repeated `--var name=value` for small metadata values.
-- Prefer file inputs for large content.
+`scriptorium.timeout` limits each subprocess call when configured. Context
+cancellation or timeout returns an execution error.
 
-## Environment Contract
+Stdout and stderr are captured separately. Each stream is capped at 1 MiB and
+the result records whether truncation occurred.
 
-- Pass through required API-key environment variables referenced by `api_key_env`.
-- Never pass raw API keys via CLI arguments.
-- Keep subprocess environment scoped to required variables.
+## Results
 
-## Output And Error Handling
+Render results include:
 
-`run`:
+- full argv recorded as `command`
+- stdout
+- stderr
+- exit code
+- truncation flags when applicable
 
-- stdout: artifact body unless `--out` is used
-- `--out`: writes artifact to file
-- stderr: success summary and errors
+Run results include the same fields plus the requested output path.
 
-`render`:
+`weatherreporter` persists render preflight JSON when orchestration reaches the
+preflight save point. The final Markdown artifact is written by Scriptorium to
+the `--out` path.
 
-- stdout: prepared-run output unless `--out` is used
-- stderr: errors
+## Failure Behavior
 
-weatherreporter should capture stdout and stderr separately.
+The adapter validates required request fields before starting Scriptorium:
 
-## Exit Status Contract
+- prompt ID
+- data package path
+- output path for `run`
 
-- `0`: success
-- `1`: parse/config/load/render/generation/IO/runtime error
-- `2`: run completed but validation failed
+Nonzero exits return both the captured result and an error containing the exit
+code and stderr. A `run` exit code such as `2` is still treated as an error by
+the adapter, even if Scriptorium wrote output to the requested artifact path.
 
-A `run` exit code `2` can still produce output (stdout or `--out`).
+Subprocess start failures, context cancellation, and timeouts return errors
+without fabricating a successful result.
 
 ## Security Notes
 
-- Treat generated artifacts and stderr logs as potentially sensitive.
-- Avoid logging full rendered prompts by default in production contexts.
-- Use controlled output paths and access controls for persisted artifacts.
-
-## Canonical References
-
-- CLI behavior: [CLI reference](https://gitea.maximumdirect.net/eric/scriptorium/docs/cli.md)
-- Config behavior: [Configuration reference](https://gitea.maximumdirect.net/eric/scriptorium/docs/config.md)
-- Operations and failure handling: [Operations guide](https://gitea.maximumdirect.net/eric/scriptorium/docs/operations.md), [Troubleshooting](https://gitea.maximumdirect.net/eric/scriptorium/docs/troubleshooting.md)
+- The adapter does not invoke a shell.
+- Generated artifacts, rendered prompt context, stdout, and stderr can contain
+  operationally sensitive data.
+- API keys should be provided through the Scriptorium environment or
+  Scriptorium configuration, not through `weatherreporter` CLI arguments.

docs/integrations/weatherapi.md

@@ -1,354 +1,137 @@
-# weatherapi External API
+# Weather API Integration
 
-This document describes the public HTTP API exposed by `weatherapi` for external consumers.
+This document describes the external Weather API contract used by
+`weatherreporter`.
+
+## Purpose
+
+`weatherreporter` uses a configured Weather API base URL to fetch normalized
+weather source data and assemble a `forecast.Bundle`. This is an integration
+contract for the project adapter, not a complete public API reference for the
+upstream service.
 
 ## Base URL
 
-The service is typically served at your deployment host, for example:
+`weather_api.base_url` must be an absolute URL. Adapter requests join this base
+URL with the endpoint paths listed below. Generation and explicit bundle fetches
+fail before any HTTP request when the base URL is empty or not absolute.
 
-- `https://weather.api.rakestrawhome.com`
+The HTTP client uses `weather_api.timeout`.
 
-All paths below are relative to the service root.
+## Response Envelope
 
-## Common Conventions
-
-### Response envelope
-
-All endpoints return a top-level envelope:
-
-- `data`: endpoint payload or `null` when no current/latest resource is available.
-
-JSON example:
+Every response used by the adapter must be JSON with a top-level `data` field:
 
 ```json
 {
-  "data": {"...": "..."}
+  "data": {}
 }
 ```
 
-### Output format
+For most sources, `data: null` is treated as a missing source. Missing optional
+sources follow the configured missing-source policy. Missing hourly forecast
+data fails bundle fetching because hourly periods are required for report
+generation.
 
-Supported via `format` query parameter (case-insensitive):
+`/alerts/active` is the exception: a successful response with `data: null`
+means the endpoint was checked and there are no current active alerts. The
+adapter records a non-missing alerts source and an empty alert run.
 
-- `json` (default)
-- `xml`
-- `text`
+Malformed JSON envelopes, non-2xx statuses, and response read failures include
+endpoint context in returned errors. Decode errors include source context when
+they fail the fetch; optional malformed sources follow the missing-source policy.
 
-### Units
+## Query Parameters
 
-Supported via `units` query parameter (case-insensitive):
+The adapter sends these query parameters:
 
-- `metric` (default)
-- `us`
+- `format`: from `weather_api.format`; the implemented configuration requires
+  `json`
+- `units`: from `weather_api.units`
+- `precision`: from `weather_api.precision` on observations, current
+  conditions, hourly forecast, and narrative forecast requests
+- `tz`: from `weather_api.timezone` on hourly forecast, narrative forecast, and
+  discussion requests
 
-Endpoints that include unit-based numeric fields return either metric or US field variants depending on this value.
+Alerts do not receive `precision` or `tz`. Weather story requests receive only
+`format=json`.
 
-### Precision
+## Endpoints Used
 
-Supported where documented via `precision` query parameter:
+The adapter fetches these endpoints once per bundle:
 
-- integer range: `0` to `2`
-- controls decimal rounding of numeric output fields
+- `/observations`
+- `/conditions/current`
+- `/forecast/hourly`
+- `/forecast/narrative`
+- `/alerts/active`
+- `/discussion`
+- `/weatherstories/latest`
 
-### Timezone (`tz` / `TZ`)
+`weatherreporter` does not call day-slice forecast endpoints or discussion
+subsection endpoints. Report-period selection and daypart summarization happen
+inside Go after the full hourly and narrative products are fetched.
 
-Supported where documented:
+## Required And Optional Sources
 
-- accepted values include:
-  - IANA timezone names (example: `America/Chicago`)
-  - common US abbreviations (example: `CDT`, `EST`)
-  - UTC offsets in `±H`, `±HH`, or `±HH:MM` (example: `-5`, `+09:30`)
-  - aliases including `Chicago` and `Stl`
-- `tz` and `TZ` are treated equivalently
-- if both are provided, they must match exactly or the request fails
+Hourly forecast is required:
 
-Timezone affects datetime rendering and day-slice filtering for `/today` and `/tomorrow` forecast routes.
+- `data: null` for `/forecast/hourly` fails the fetch.
+- an hourly forecast with no `periods` fails the fetch.
+- malformed hourly data fails the fetch.
 
-### Query validation
+Other fetched sources are optional and follow `missing_source.default` or a
+source-specific `missing_source.sources` policy:
 
-- Unknown query parameters are rejected with `400 Bad Request`.
-- Invalid parameter values are rejected with `400 Bad Request`.
+- `observations` for `/observations`
+- `current` for `/conditions/current`
+- `narrative` for `/forecast/narrative`
+- `alerts` for `/alerts/active`
+- `discussion` for `/discussion`
+- `weather_story` for `/weatherstories/latest`
 
-Error response body follows the service error envelope; exact fields may vary by error type.
+The adapter also creates a missing stub source record for `daily` because that
+source slot exists in the internal bundle but is not fetched from the Weather
+API.
 
-## Endpoints
+Policy behavior:
 
-## `GET /observations`
+- `error`: fail the fetch for that source
+- `warn`: omit the source data, add a warning, and continue
+- `none`: omit the source data and continue without a warning
 
-Returns the latest weather observation.
+For `/alerts/active`, an HTTP error or missing `data` field still fails or
+follows the relevant error path, but explicit `data: null` is not a
+missing-source condition.
 
-Query parameters:
+## Source Identity
 
-- `units`: `metric` | `us`
-- `format`: `json` | `xml` | `text`
-- `precision`: `0..2`
+For source payloads accepted into the bundle, including the explicit `null`
+alerts payload, the adapter records:
 
-Response `data` fields:
+- source name
+- endpoint path
+- query parameters sent
+- fetch time
+- source issue and update timestamps when present in the payload
+- SHA-256 hash of the compact raw `data` JSON
 
-- `stationId` (string, optional)
-- `stationName` (string, optional)
-- `timestamp` (RFC3339 datetime, required)
-- `conditionCode` (integer WMO code, required)
-- `isDay` (boolean, optional)
-- `textDescription` (string, optional)
-- Metric mode fields:
-  - `temperatureC`, `dewpointC`, `windSpeedKmh`, `windGustKmh`, `barometricPressurePa`, `visibilityMeters`, `relativeHumidityPercent`, `apparentTemperatureC` (number, optional)
-  - `windDirectionDegrees` (number, optional)
-- US mode fields:
-  - `temperatureF`, `dewpointF`, `windSpeedMph`, `windGustMph`, `barometricPressureInHg`, `visibilityMiles`, `relativeHumidityPercent`, `apparentTemperatureF` (number, optional)
-  - `windDirectionDegrees` (number, optional)
-- `presentWeather` (array, optional)
+Warnings are recorded both on the affected source and on the bundle-level
+warnings list.
 
-## `GET /alerts/active`
+## Compatibility Assumptions
 
-Returns the latest active alert run.
+The adapter expects payload fields compatible with the internal forecast bundle
+types in `internal/forecast/bundle.go`, including:
 
-Query parameters:
+- observation timestamps and observation values
+- current condition values
+- forecast run metadata and `periods`
+- active alert run data
+- discussion metadata, key messages, and short/long-term section text
+- latest weather story title, description, timing, priority, order, alt text,
+  and download URL
 
-- `units`: `metric` | `us` (accepted; does not materially alter alert payload)
-- `format`: `json` | `xml` | `text`
-
-Response `data` fields:
-
-- Weather alert run object from canonical model (includes run metadata and active alerts list).
-
-## `GET /conditions/current`
-
-Returns current conditions synthesized from latest observation/forecast data.
-
-Query parameters:
-
-- `units`: `metric` | `us`
-- `format`: `json` | `xml` | `text`
-- `precision`: `0..2`
-
-Response `data` fields:
-
-- Common:
-  - `conditionText` (string, optional)
-  - `isDay` (boolean, optional)
-  - `relativeHumidityPercent` (number, optional)
-  - `windDirectionDegrees` (number, optional)
-- Metric mode:
-  - `temperatureC`, `apparentTemperatureC`, `dewpointC`, `windSpeedKmh` (number, optional)
-- US mode:
-  - `temperatureF`, `apparentTemperatureF`, `dewpointF`, `windSpeedMph` (number, optional)
-
-## Forecast endpoints
-
-- `GET /forecast/hourly`
-- `GET /forecast/hourly/today`
-- `GET /forecast/hourly/tomorrow`
-- `GET /forecast/narrative`
-- `GET /forecast/narrative/today`
-- `GET /forecast/narrative/tomorrow`
-
-Query parameters:
-
-- `units`: `metric` | `us`
-- `format`: `json` | `xml` | `text`
-- `precision`: `0..2`
-- `tz` or `TZ`: timezone selector
-
-Day-slice routes:
-
-- `/today` returns periods with `period.startTime` in the current calendar day for the resolved timezone.
-- `/tomorrow` returns periods with `period.startTime` in the next calendar day for the resolved timezone.
-
-Response `data` fields:
-
-- Run-level:
-  - `locationId` (string, optional)
-  - `locationName` (string, optional)
-  - `issuedAt` (RFC3339 datetime, required)
-  - `updatedAt` (RFC3339 datetime, optional)
-  - `product` (string, required; e.g. `hourly`, `narrative`)
-  - `latitude`, `longitude` (number, optional)
-  - Metric mode: `elevationMeters` (number, optional)
-  - US mode: `elevationFeet` (number, optional)
-  - `periods` (array, required)
-- Period fields:
-  - `startTime`, `endTime` (RFC3339 datetime, required)
-  - `name` (string, optional)
-  - `isDay` (boolean, optional)
-  - `conditionCode` (integer WMO code, optional)
-  - `textDescription` (string, optional)
-  - Metric mode (optional):
-    - `temperatureC`, `temperatureCMin`, `temperatureCMax`, `dewpointC`, `windSpeedKmh`, `windGustKmh`, `barometricPressurePa`, `visibilityMeters`, `apparentTemperatureC`, `cloudCoverPercent`, `probabilityOfPrecipitationPercent`, `precipitationAmountMm`, `snowfallDepthMM`, `uvIndex`, `relativeHumidityPercent`, `windDirectionDegrees`
-  - US mode (optional):
-    - `temperatureF`, `temperatureFMin`, `temperatureFMax`, `dewpointF`, `windSpeedMph`, `windGustMph`, `barometricPressureInHg`, `visibilityMiles`, `apparentTemperatureF`, `cloudCoverPercent`, `probabilityOfPrecipitationPercent`, `precipitationAmountIn`, `snowfallDepthIn`, `uvIndex`, `relativeHumidityPercent`, `windDirectionDegrees`
-
-Notes:
-
-- Narrative periods may omit `conditionCode`.
-- Text format uses forecast-specific templates (`hourly` and `narrative`).
-
-## Discussion endpoints
-
-- `GET /discussion`
-- `GET /discussion/key-messages`
-- `GET /discussion/short-term`
-- `GET /discussion/long-term`
-
-Query parameters:
-
-- `units`: `metric` | `us` (accepted; does not materially alter discussion payload)
-- `format`: `json` | `xml` | `text`
-- `tz` or `TZ`: timezone selector
-
-Response `data` fields:
-
-- `/discussion`:
-  - `officeId` (string, optional)
-  - `officeName` (string, optional)
-  - `product` (string, required)
-  - `issuedAt` (RFC3339 datetime, required)
-  - `updatedAt` (RFC3339 datetime, optional)
-  - `keyMessages` (array of string)
-  - `shortTerm` (object, optional)
-  - `longTerm` (object, optional)
-- `/discussion/key-messages`:
-  - `officeId`, `officeName`, `product`, `issuedAt`, `updatedAt`
-  - `keyMessages` (array of string)
-- `/discussion/short-term`:
-  - `officeId`, `officeName`, `product`, `issuedAt`, `updatedAt`
-  - `shortTerm` (object, optional)
-- `/discussion/long-term`:
-  - `officeId`, `officeName`, `product`, `issuedAt`, `updatedAt`
-  - `longTerm` (object, optional)
-
-Discussion section object fields:
-
-- `title` (string, optional)
-- `narrative` (string, optional)
-- `issuedAt` (RFC3339 datetime, optional)
-
-## Examples
-
-### Observation (JSON, metric)
-
-```http
-GET /observations?format=json&units=metric&precision=1
-```
-
-```json
-{
-  "data": {
-    "stationId": "KSTL",
-    "timestamp": "2026-05-29T14:00:00Z",
-    "conditionCode": 3,
-    "isDay": true,
-    "textDescription": "Partly cloudy",
-    "temperatureC": 24.4,
-    "windSpeedKmh": 17.2,
-    "relativeHumidityPercent": 56.0
-  }
-}
-```
-
-### Alerts (JSON)
-
-```http
-GET /alerts/active?format=json
-```
-
-```json
-{
-  "data": {
-    "asOf": "2026-05-29T14:00:00Z",
-    "alerts": []
-  }
-}
-```
-
-### Current conditions (JSON, US)
-
-```http
-GET /conditions/current?format=json&units=us&precision=1
-```
-
-```json
-{
-  "data": {
-    "conditionText": "Partly cloudy",
-    "isDay": true,
-    "temperatureF": 75.9,
-    "apparentTemperatureF": 76.1,
-    "windSpeedMph": 10.7,
-    "relativeHumidityPercent": 56.0
-  }
-}
-```
-
-### Forecast narrative (JSON, optional `conditionCode`)
-
-```http
-GET /forecast/narrative?format=json&units=metric&precision=1&tz=America/Chicago
-```
-
-```json
-{
-  "data": {
-    "locationId": "nws-lsx-grid-90-74",
-    "issuedAt": "2026-05-29T10:30:00-05:00",
-    "product": "narrative",
-    "periods": [
-      {
-        "startTime": "2026-05-29T13:00:00-05:00",
-        "endTime": "2026-05-29T19:00:00-05:00",
-        "name": "Today",
-        "isDay": true,
-        "textDescription": "Partly sunny, with a high near 81.",
-        "temperatureC": 27.2,
-        "windSpeedKmh": 18.0,
-        "probabilityOfPrecipitationPercent": 10.0
-      }
-    ]
-  }
-}
-```
-
-### Forecast hourly today (text)
-
-```http
-GET /forecast/hourly/today?format=text&units=us&precision=1&tz=CDT
-```
-
-```text
-<plain text forecast output>
-```
-
-### Discussion key messages (JSON)
-
-```http
-GET /discussion/key-messages?format=json&tz=Chicago
-```
-
-```json
-{
-  "data": {
-    "officeId": "LSX",
-    "product": "discussion",
-    "issuedAt": "2026-05-29T09:25:00-05:00",
-    "keyMessages": [
-      "Scattered showers possible this evening.",
-      "Warmer temperatures this weekend."
-    ]
-  }
-}
-```
-
-### Invalid timezone error example
-
-```http
-GET /forecast/narrative?tz=not-a-timezone
-```
-
-```json
-{
-  "error": {
-    "code": "invalid_parameter",
-    "message": "tz must be a valid timezone"
-  }
-}
-```
+The adapter intentionally keeps upstream transport and envelope details inside
+`internal/adapters/weatherapi`; downstream packages consume the normalized
+bundle.

docs/internal/app-orchestration.md

@@ -0,0 +1,123 @@
+# App Orchestration Internals
+
+This document describes the implemented workflow coordinator in `internal/app`.
+
+## Purpose
+
+`internal/app` coordinates the top-level use cases after CLI parsing and config
+loading are complete. It resolves report definitions, fetches weather data,
+builds briefing and prompt-input artifacts, invokes Scriptorium through the
+adapter boundary, persists managed state, runs batches, and reads existing
+artifacts for inspection.
+
+## Inputs And Outputs
+
+Inputs:
+
+- `GenerateRequest` for one report command
+- `BatchRequest` for morning or evening batch commands
+- `FetchBundleRequest` for explicit bundle fetch and save workflows
+- `BriefingRequest` and `ReportRequest` for package-level orchestration tests
+  and internal composition
+- resolved report definitions from `internal/report`
+- forecast bundles from `internal/adapters/weatherapi`
+- prior snapshots loaded from `internal/state`
+- optional renderer and state-store fakes for tests
+
+Outputs:
+
+- generated report results with briefing, data package, preflight, report,
+  metadata, prior snapshot, Recent Changes, and Scriptorium result details
+- batch summaries with per-report status, artifact paths, and error text
+- saved Weather API bundle JSON for fetch workflows
+- inspection JSON values for reports, metadata, briefings, data packages, prior
+  snapshots, and source provenance
+
+## Boundaries
+
+`internal/app` owns workflow order and request composition. It does not parse
+CLI flags, load YAML files directly, implement HTTP transport, derive forecast
+facts, define report periods, compare rendered Markdown, or construct
+Scriptorium argv.
+
+Report selection and report identity policy come from `internal/report`.
+Weather API transport stays in `internal/adapters/weatherapi`. Scriptorium
+subprocess behavior stays in `internal/adapters/scriptorium`. Filesystem layout
+and persisted metadata stay in `internal/state`.
+
+## Config Fields Used
+
+- `weather_api.*` for Weather API client construction and briefing metadata
+- `scriptorium.*` for renderer construction
+- `workspace.*` for filesystem state
+- `dayparts` for daily and outlook summarization
+- `recent_change.*` for structured Recent Changes thresholds
+
+Output copy flags are command request fields. They are not configuration
+defaults.
+
+## Generation Workflow
+
+Single-report generation follows this order:
+
+1. Resolve the command report to a `report.Resolved` value.
+2. Create or use a filesystem store.
+3. Locate any prior compatible snapshot through `internal/state`.
+4. Fetch a Weather API bundle.
+5. Build a report-specific briefing package.
+6. Save the briefing snapshot.
+7. Compute Recent Changes from structured prior and current briefings.
+8. Build and save the Scriptorium `data_package`.
+9. Run Scriptorium render preflight.
+10. Save preflight JSON when a render result is available.
+11. Save metadata for inspection.
+12. Run Scriptorium report generation to the managed report path.
+13. Copy the managed report to the requested `--out` path when provided.
+14. Save metadata with the managed report path.
+
+If render preflight returns both a result and an error, preflight JSON and
+metadata are persisted before the error is returned. If Scriptorium report
+generation returns an error after writing output, the managed report and
+metadata remain inspectable.
+
+## Batch Workflow
+
+`run morning` resolves Daily Today, 3-Day Outlook, and Weekend Outlook except
+on Sunday. `run evening` resolves Daily Tomorrow. Batch output copy names come
+from report definitions. Batch generation continues independent reports after a
+failure, records each result, writes compact status lines to stderr, emits a
+JSON summary to stdout, and returns an aggregate error when any report failed.
+
+## Inspection Workflow
+
+Inspection workflows load existing filesystem state only. They do not fetch
+weather data or invoke Scriptorium. Run-specific inspect commands share the same
+store and metadata lookup path, then load the requested artifact or derived
+inspection view.
+
+## Failure Behavior
+
+- Resolve errors stop the requested workflow before fetching weather data.
+- Weather API and briefing errors stop that report before Scriptorium runs.
+- Prompt input validation fails before render preflight.
+- Render and run errors preserve Scriptorium stderr and exit-code context.
+- Metadata and artifact path errors include filesystem context.
+- Batch failures are recorded per report and surfaced through an aggregate
+  batch error.
+
+## Tests
+
+Inspect:
+
+- `internal/app/app_test.go`
+- `internal/cli/root_test.go`
+- `internal/state/filesystem_test.go`
+
+## Invariants
+
+- Report behavior is resolved through `internal/report`.
+- Generated reports use the same app request and result types regardless of
+  report ID.
+- Render preflight precedes Scriptorium report generation.
+- Recent Changes are computed from structured briefing snapshots.
+- Metadata links artifacts produced for a run.

docs/internal/briefing.md

@@ -0,0 +1,87 @@
+# Briefing Internals
+
+This document describes the implemented briefing package boundary.
+
+## Purpose
+
+`internal/briefing` builds structured report-specific briefing packages from
+resolved report metadata, forecast bundles, and derived forecast summaries.
+Briefings are curated inputs for prompt data packages, not rendered report
+prose.
+
+## Inputs And Outputs
+
+Inputs:
+
+- resolved report definition, generation time, timezone, and valid period
+- forecast bundle with source provenance and warnings
+- derived daily or period summaries where required
+- configured units, timezone, and descriptive location context
+
+Outputs:
+
+- `briefing.Package` with common metadata and one report-specific content
+  object for Daily, 3-Day, Weekend, or Storm Report
+- optional `currentConditions` prompt context from normalized
+  `/conditions/current` data when available
+- optional structured `weatherStory` context on report-specific briefing
+  objects when `/weatherstories/latest` is available
+- optional JSON file written by `briefing.Save`
+
+## Boundaries
+
+- This package selects and shapes weather facts for prompts.
+- It does not fetch weather data, compare prior snapshots, build
+  `data_package` files, invoke Scriptorium, or write workflow metadata.
+
+## Config Fields Used
+
+The package receives configured units and timezone from the app layer. Daypart
+configuration is consumed by `internal/forecast` before briefing builders run.
+Configured `location` values are prompt context only; Weather API
+`sourceLocationId` and `sourceLocation` remain source provenance.
+Current conditions are copied from the normalized `/conditions/current` bundle
+source only; observation station and timestamp fields remain provenance.
+
+## External Adapters Used
+
+None directly.
+
+## State Or Manifest Behavior
+
+`briefing.Save` writes briefing JSON atomically. Managed workspace placement is
+owned by `internal/state`.
+
+## Skip And Resume Behavior
+
+None. Builders either return a complete briefing package or an error.
+
+## Failure Behavior
+
+- Daily briefing construction requires a Daily report definition and derived
+  daily summary.
+- 3-Day briefing construction requires a 3-Day report definition and at least
+  one derived summary.
+- Weekend briefing construction requires a Weekend report definition and at
+  least one derived summary.
+- Storm briefing construction requires a Storm Report definition and forecast
+  bundle.
+- Save failures include path and operation context.
+
+## Tests
+
+Inspect:
+
+- `internal/briefing/daily_test.go`
+- `internal/briefing/three_day_test.go`
+- `internal/briefing/weekend_test.go`
+- `internal/briefing/storm_test.go`
+- `internal/app/app_test.go`
+
+## Invariants
+
+- Briefings contain structured weather facts and source context.
+- Common metadata includes RunID, report ID, prompt ID, valid period, source
+  provenance, source hashes, source warnings, and configured prompt location.
+- LLM prompt input packaging and Scriptorium execution remain outside this
+  boundary.

docs/internal/changes.md

@@ -0,0 +1,74 @@
+# Changes Internals
+
+This document describes structured Recent Changes comparison.
+
+## Purpose
+
+`internal/changes` compares current and prior briefing packages and emits
+compact change records for prompt input data packages.
+
+## Inputs And Outputs
+
+Inputs:
+
+- prior briefing package
+- current briefing package
+- comparison thresholds from configuration
+
+Outputs:
+
+- ordered `changes.Change` items with type, message, previous value, and current
+  value where useful
+
+## Boundaries
+
+- This package compares structured briefing data only.
+- It does not read filesystem state, find prior snapshots, render Markdown,
+  invoke Scriptorium, or compare generated report text.
+
+## Config Fields Used
+
+The app maps these fields into comparison thresholds:
+
+- `recent_change.temperature_degrees`
+- `recent_change.precip_probability_points`
+- `recent_change.wind_gust_miles_per_hour`
+- `recent_change.precip_timing_shift_minutes`
+
+## External Adapters Used
+
+None.
+
+## State Or Manifest Behavior
+
+None directly. The app loads prior briefing snapshots through `internal/state`
+before calling comparison functions.
+
+## Skip And Resume Behavior
+
+No resume behavior. When the app has no prior comparable snapshot, it sends an
+empty Recent Changes list without calling a comparison function.
+
+## Failure Behavior
+
+- Daily comparison requires both inputs to contain Daily briefing content.
+- 3-Day comparison requires both inputs to contain 3-Day briefing content.
+- Weekend comparison requires both inputs to contain Weekend briefing content.
+- Storm Report currently has no comparison implementation, so the app leaves
+  Recent Changes empty for Storm reports.
+
+## Tests
+
+Inspect:
+
+- `internal/changes/daily_test.go`
+- `internal/changes/three_day_test.go`
+- `internal/changes/weekend_test.go`
+- `internal/app/app_test.go`
+
+## Invariants
+
+- Recent Changes are based on structured snapshots, not Markdown report text.
+- Report compatibility is determined outside this package by report definitions
+  and state lookup.
+- Output stays compact enough for prompt input.

docs/internal/forecast-derivation.md

@@ -0,0 +1,76 @@
+# Forecast Derivation Internals
+
+This document describes deterministic forecast summarization in
+`internal/forecast`.
+
+## Purpose
+
+`internal/forecast` converts normalized bundle data into daily and period
+summaries used by briefing builders.
+
+## Inputs And Outputs
+
+Inputs:
+
+- `forecast.Bundle`
+- local date or resolved report period
+- timezone
+- configured daypart definitions
+
+Outputs:
+
+- `forecast.DailySummary` for one local civil day
+- one clipped daily summary per local day or partial day from
+  `BuildPeriodDailySummaries`
+- daypart summaries with selected hourly periods, ranges, timed maximums,
+  conditions, indicators, and alert overlaps
+
+## Boundaries
+
+- This package groups, selects, and summarizes already-normalized forecast
+  data.
+- It does not perform HTTP calls, parse CLI flags, resolve report definitions,
+  compare prior snapshots, build prompt input packages, or invoke Scriptorium.
+
+## Config Fields Used
+
+- `dayparts[].name`
+- `dayparts[].start`
+- `dayparts[].end`
+
+Threshold constants for basic indicators live in forecast code rather than
+configuration.
+
+## External Adapters Used
+
+None directly. Forecast data arrives through `forecast.Bundle`.
+
+## State Or Manifest Behavior
+
+None. Source warnings and provenance from the bundle are carried into summaries
+for later metadata and briefing output.
+
+## Skip And Resume Behavior
+
+None. Missing optional source context can produce empty selections, but missing
+required hourly data fails summarization.
+
+## Failure Behavior
+
+- A nil bundle or missing hourly forecast data returns an error.
+- Invalid daypart definitions return parse errors with context.
+- Alert records without parseable RFC3339 timing are skipped.
+- Empty selected periods produce empty summaries rather than generated prose.
+
+## Tests
+
+Inspect:
+
+- `internal/forecast/derive_test.go`
+- `internal/timeutil/periods_test.go`
+
+## Invariants
+
+- Go owns report-period selection and meteorological summarization.
+- Weather facts come from normalized source data.
+- Outputs remain JSON-inspectable and independent of CLI, state, and adapters.

docs/internal/prompt-input.md

@@ -0,0 +1,69 @@
+# Prompt Input Internals
+
+This document describes prompt input data package construction.
+
+## Purpose
+
+`internal/promptinput` converts a structured briefing package and optional
+Recent Changes into the `data_package` JSON passed to Scriptorium prompts.
+
+## Inputs And Outputs
+
+Inputs:
+
+- `briefing.Package`
+- optional `[]changes.Change`
+
+Outputs:
+
+- `promptinput.Package` containing schema version, RunID, report metadata,
+  briefing content, Recent Changes, and source warnings. Briefing content
+  includes configured location context, current conditions when available,
+  structured weather story context when available, discussion key messages, and
+  short/long-term AFD narratives when the Weather API provides them.
+- report metadata includes `currentLocalDate`, the generation date formatted as
+  `YYYY-MM-DD` in the effective report timezone.
+- optional JSON file written by `promptinput.Save`
+
+## Boundaries
+
+- This package owns the prompt input schema and validation.
+- It does not fetch weather data, derive forecast summaries, find prior
+  snapshots, compare changes, or invoke Scriptorium.
+
+## Config Fields Used
+
+None directly. Config-derived values, including timezone and prompt location
+context, are already present in briefing metadata before this package runs.
+
+## External Adapters Used
+
+None.
+
+## State Or Manifest Behavior
+
+`promptinput.Save` writes JSON atomically. Managed workspace paths are owned by
+`internal/state`.
+
+## Skip And Resume Behavior
+
+None. Recent Changes is always present as an `items` list and may be empty.
+
+## Failure Behavior
+
+Validation fails before render preflight when required top-level or briefing
+metadata fields are missing or inconsistent, or when no report content is
+present. Save failures include filesystem operation and path context.
+
+## Tests
+
+Inspect:
+
+- `internal/promptinput/package_test.go`
+- `internal/app/app_test.go`
+
+## Invariants
+
+- Scriptorium receives structured `data_package` JSON.
+- Briefing metadata and top-level report metadata must agree.
+- Recent Changes are not inferred from rendered report text.

docs/internal/report-registry.md

@@ -0,0 +1,97 @@
+# Report Registry Internals
+
+This document describes report identity, valid-period resolution, batch
+membership, output naming, artifact grouping, and comparison declarations in
+`internal/report`.
+
+## Purpose
+
+`internal/report` is the canonical source for report definitions. App, state,
+briefing, and CLI wiring consume resolved definitions instead of owning report
+identity policy themselves.
+
+## Definition Fields
+
+Each report definition declares:
+
+- report ID and display name
+- Scriptorium prompt ID
+- valid-period resolver
+- comparison strategy
+- managed artifact group
+- batch output copy filename
+- generated-report eligibility
+- prior-report compatibility list
+- morning or evening batch membership
+
+## Implemented Reports
+
+| Report | ID | Prompt | Artifact group | Batch copy | Prior compatibility |
+| --- | --- | --- | --- | --- | --- |
+| Daily Today | `daily_today` | `weather.daily_report` | `daily` | `daily.md` | Daily Today, Daily Tomorrow |
+| Daily Tomorrow | `daily_tomorrow` | `weather.daily_report` | `daily` | `tomorrow.md` | Daily Today, Daily Tomorrow |
+| 3-Day Outlook | `three_day` | `weather.three_day_outlook` | `three-day` | `three-day.md` | 3-Day Outlook |
+| Weekend Outlook | `weekend` | `weather.weekend_outlook` | `weekend` | `weekend.md` | Weekend Outlook |
+| Storm Report | `storm` | `weather.storm_report` | `storm` | `storm.md` | Storm Report |
+
+All implemented report definitions are eligible for generation.
+
+## Valid Periods
+
+- Daily Today covers the selected local civil day, or the current local civil
+  day when no date override is supplied.
+- Daily Tomorrow covers the next local civil day from generation time.
+- 3-Day Outlook covers the interval from generation time through local midnight
+  three days later.
+- Weekend Outlook covers the upcoming weekend window and is not scheduled for
+  Sunday morning batch resolution.
+- Storm Report covers an explicit event window supplied by the caller.
+
+Storm event windows can be parsed from local `YYYY-MM-DDTHH:MM` timestamps in
+the configured timezone or RFC3339 timestamps with explicit offsets. End time
+must be after start time.
+
+## Boundaries
+
+`internal/report` defines report metadata and time coverage. It does not fetch
+weather data, build briefings, compare briefing contents, write state, parse CLI
+flags, or invoke Scriptorium.
+
+The CLI owns public command names. The app maps those command names to report
+IDs, then uses the registry for report policy.
+
+## Config Fields Used
+
+The app supplies `weather_api.timezone` as a loaded `time.Location`. Batch
+output path copying uses batch output names from report definitions.
+
+## State And App Usage
+
+- State paths use `ArtifactGroup`.
+- Batch output copies use `BatchOutputName`.
+- Generation checks `Generated`.
+- Prior lookup checks `CompatiblePriorIDs` and the comparison strategy.
+- RunIDs include the resolved report ID.
+
+## Failure Behavior
+
+- Unknown report IDs and batch names return actionable errors.
+- Weekend Outlook resolution returns an error when resolved directly on Sunday.
+- Storm Report resolution requires start and end, with end after start.
+
+## Tests
+
+Inspect:
+
+- `internal/report/period_test.go`
+- `internal/app/app_test.go`
+- `internal/cli/root_test.go`
+
+## Invariants
+
+- Report selection goes through the registry.
+- Daily Today and Daily Tomorrow both use `weather.daily_report`.
+- Valid periods are half-open intervals independent of rendered report text.
+- Artifact grouping, batch output filenames, generated-report eligibility,
+  comparison compatibility, and comparison strategy are declared by report
+  definition.

docs/internal/scriptorium-adapter.md

@@ -0,0 +1,100 @@
+# Scriptorium Adapter Internals
+
+This document describes the subprocess adapter in
+`internal/adapters/scriptorium`.
+
+## Purpose
+
+The adapter runs `scriptorium render` for prompt preflight and `scriptorium run`
+for Markdown report generation. It isolates subprocess execution, argv
+construction, timeout handling, output capture, and exit-code interpretation
+from app and domain packages.
+
+## Inputs And Outputs
+
+Inputs:
+
+- prompt ID
+- prompt input data package path
+- report output path for `run`
+- configured binary, config path, profile, timeout, and extra arguments
+- context for cancellation
+
+Outputs:
+
+- argv used for execution
+- captured stdout and stderr
+- truncation flags for captured output
+- exit code
+- report output path for `run`
+
+## Boundaries
+
+`internal/adapters/scriptorium` owns Scriptorium command construction and
+subprocess execution. It does not choose report types, build prompt input,
+fetch weather data, decide workflow order, or persist workflow metadata.
+
+The adapter exposes request and result structs for render and run operations.
+State persistence uses a state-owned preflight artifact shape; app
+orchestration converts render results before saving.
+
+## Config Fields Used
+
+- `scriptorium.binary`
+- `scriptorium.config_path`
+- `scriptorium.profile`
+- `scriptorium.timeout`
+- `scriptorium.extra_args`
+
+## Commands
+
+Render preflight argv starts with:
+
+```text
+scriptorium render --prompt <prompt_id> --input data_package=<path> --format json
+```
+
+Report generation argv starts with:
+
+```text
+scriptorium run --prompt <prompt_id> --input data_package=<path> --out <path>
+```
+
+Configured `--config` and `--profile` flags are inserted after the subcommand
+and before prompt-specific arguments. Extra arguments are appended after the
+built-in arguments.
+
+## Execution Behavior
+
+The adapter runs commands without shell interpolation. The same private
+execution path is used by render and run after command-specific request
+validation and argv construction.
+
+When `scriptorium.timeout` is greater than zero, each subprocess call uses a
+context with that timeout. Stdout and stderr are captured separately, capped at
+1 MiB each, and marked as truncated when the cap is reached.
+
+## Failure Behavior
+
+- Missing prompt ID or data package path returns an error before subprocess
+  execution.
+- Missing run output path returns an error before subprocess execution.
+- Subprocess start errors, context cancellation, and timeouts are wrapped with
+  operation context by the caller-facing method.
+- Nonzero render and run exits return the captured result plus an error
+  containing the exit code and stderr.
+
+## Tests
+
+Inspect:
+
+- `internal/adapters/scriptorium/runner_test.go`
+- `internal/app/app_test.go`
+- `internal/cli/root_test.go`
+
+## Invariants
+
+- No shell interpolation is used.
+- The Scriptorium input name is `data_package`.
+- Render and run preserve command-specific result structs.
+- Scriptorium-specific flags stay inside adapter and config boundaries.

docs/internal/state.md

@@ -0,0 +1,117 @@
+# State Internals
+
+This document describes filesystem state in `internal/state`.
+
+## Purpose
+
+`internal/state` owns managed workspace paths, atomic JSON writes, persisted
+metadata, prior snapshot lookup, and read-only artifact inspection helpers.
+
+## Inputs And Outputs
+
+Inputs:
+
+- workspace configuration
+- resolved report definition and valid period
+- briefing package
+- prompt input data package
+- preflight artifact
+- rendered report path preparation request
+- RunID for inspection lookups
+
+Outputs:
+
+- briefing snapshot JSON path
+- prompt input data package JSON path
+- render preflight JSON path
+- managed Markdown report path
+- metadata JSON path
+- prior comparable snapshot metadata
+- loaded briefing or data package
+- recent report records for inspection
+
+## Boundaries
+
+`internal/state` owns local filesystem layout, path validation, durable writes,
+metadata reads, prior lookup, and report listing. It does not fetch weather
+data, derive forecasts, build prompt input content, compare briefing contents,
+invoke Scriptorium, import adapter result types, or parse CLI flags.
+
+Preflight persistence uses the state-owned `PreflightArtifact` shape. The app
+converts adapter render results into that shape before saving.
+
+## Config Fields Used
+
+- `workspace.root`
+- `workspace.snapshots_dir`
+- `workspace.reports_dir`
+- `workspace.data_packages_dir`
+- `workspace.preflight_dir`
+
+Workspace subdirectories must be relative paths that stay under
+`workspace.root`.
+
+## Managed Layout
+
+Paths are derived from the resolved report definition's artifact group, the
+valid-period start date for JSON artifacts, and the RunID.
+
+```text
+<workspace.root>/
+  snapshots/<artifact_group>/<YYYY-MM-DD>/<run_id>.briefing.json
+  snapshots/<artifact_group>/<YYYY-MM-DD>/<run_id>.metadata.json
+  data-packages/<artifact_group>/<YYYY-MM-DD>/<run_id>.data_package.json
+  preflight/<artifact_group>/<YYYY-MM-DD>/<run_id>.render.json
+  reports/<artifact_group>/<run_id>.md
+```
+
+Metadata is stored beside briefing snapshots and links the briefing, data
+package, preflight, report paths, and configured prompt location. Report
+listing walks metadata files under the snapshots directory.
+
+## Prior Lookup
+
+Prior snapshot lookup reads stored metadata through the shared lookup path and
+selects the latest earlier snapshot whose report ID is compatible with the
+current report definition.
+
+- Daily Today and Daily Tomorrow are compatible with each other for the same
+  valid local date.
+- 3-Day Outlook compares with prior 3-Day snapshots for the same valid local
+  date.
+- Weekend Outlook compares with prior Weekend snapshots for the same weekend
+  window.
+- Storm Report currently has no prior lookup because explicit event-window
+  comparison is not searched by the filesystem store.
+
+## Writes And Inspection
+
+Durable JSON writes use shared atomic file helpers. Managed Markdown reports are
+prepared by creating their parent directory; Scriptorium writes the report body
+to the prepared path. Extra Markdown copies are handled by app orchestration.
+
+Inspection helpers read existing metadata, briefing, and data package files.
+Missing metadata directories return no inspection records or no prior snapshot
+rather than creating state.
+
+## Failure Behavior
+
+- Invalid workspace paths return validation errors.
+- Missing required metadata fields prevent metadata writes.
+- JSON writes use a temporary file followed by rename where practical.
+- Read and decode failures include path context.
+- Unknown RunIDs produce an actionable lookup error.
+
+## Tests
+
+Inspect:
+
+- `internal/state/filesystem_test.go`
+- `internal/app/app_test.go`
+
+## Invariants
+
+- Managed paths stay under the configured workspace root.
+- Artifact grouping comes from report definitions.
+- Metadata links artifacts produced for a run.
+- Prior lookup is based on structured metadata, not rendered report text.

docs/internal/weather-data.md

@@ -0,0 +1,89 @@
+# Weather Data Internals
+
+This document describes Weather API ingestion into `forecast.Bundle`.
+
+## Purpose
+
+`internal/adapters/weatherapi` fetches normalized weather data from one
+configured Weather API endpoint and assembles the bundle consumed by forecast
+derivation and briefing builders. Briefing builders expose normalized current
+conditions and weather story context when those sources are available.
+
+## Inputs And Outputs
+
+Inputs:
+
+- `config.Config` with Weather API URL, timeout, format, units, timezone,
+  precision, and missing-source policy
+- HTTP responses using the Weather API `data` envelope
+
+Outputs:
+
+- `forecast.Bundle` with observation, current conditions, hourly forecast,
+  narrative forecast, active alerts, discussion, latest weather story, source
+  records, and source warnings
+- stub source record for the daily forecast source slot
+- optional saved bundle JSON through app fetch helpers
+
+## Boundaries
+
+- The adapter owns HTTP calls, response-envelope handling, source hashing, and
+  decoding into internal bundle types.
+- It does not derive dayparts, resolve report periods, build briefings, compare
+  snapshots, write report state, or invoke Scriptorium.
+
+## Config Fields Used
+
+- `weather_api.base_url`
+- `weather_api.timeout`
+- `weather_api.format`
+- `weather_api.units`
+- `weather_api.timezone`
+- `weather_api.precision`
+- `missing_source.default`
+- `missing_source.sources`
+
+## External Adapters Used
+
+- Weather API HTTP service
+
+See [Weather API integration](../integrations/weatherapi.md) for the external
+contract used by this project.
+
+## State Or Manifest Behavior
+
+The adapter records source name, endpoint, query, fetch time, source timestamps
+when available, SHA-256 hash over compact raw `data` JSON, missing status, and
+source warnings. Successful `data: null` responses from `/alerts/active`
+represent a checked empty active-alert list, not a missing source.
+`app.FetchAndSaveBundle` can write bundle JSON atomically for inspection.
+
+## Skip And Resume Behavior
+
+No resume behavior. Optional missing or malformed sources may be omitted,
+warned, or treated as errors according to missing-source policy. Hourly forecast
+data is required and cannot be skipped.
+
+## Failure Behavior
+
+- Missing or invalid `weather_api.base_url` prevents client construction.
+- HTTP errors, response read failures, and envelope decode failures include
+  endpoint context.
+- Missing hourly data or hourly forecasts with no periods fail bundle fetch.
+- Optional and stub sources follow missing-source policy.
+- Explicit `data: null` from `/alerts/active` produces an empty, non-missing
+  alert run.
+
+## Tests
+
+Inspect:
+
+- `internal/adapters/weatherapi/client_test.go`
+- `internal/app/app_test.go`
+
+## Invariants
+
+- Weather facts come from normalized source data.
+- Full hourly and narrative products are fetched; Go owns report-period
+  selection.
+- Source provenance and warnings remain inspectable downstream.

docs/operations.md

@@ -0,0 +1,187 @@
+# Weatherreporter Operations
+
+This guide covers normal operation, generated artifacts, inspection, recovery,
+and current operational caveats. For symptom-specific diagnosis, see
+[Troubleshooting](troubleshooting.md).
+
+## Normal Workflow
+
+Implemented generation commands:
+
+```text
+weatherreporter generate daily --date 2026-05-29
+weatherreporter generate tomorrow
+weatherreporter generate three-day
+weatherreporter generate weekend
+weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00
+```
+
+Each command resolves a report period, fetches a Weather API bundle, builds a
+briefing, builds a prompt input data package, runs `scriptorium render`, runs
+`scriptorium run`, and writes managed artifacts under the configured workspace.
+`--out PATH` writes an extra Markdown copy for the current generated report.
+
+Implemented batch commands:
+
+```text
+weatherreporter run morning
+weatherreporter run evening
+```
+
+`run morning` generates Daily Today and the 3-Day Outlook, plus Weekend Outlook
+except on Sunday. `run evening` generates the Tomorrow Planning Brief. Batch
+commands print a JSON summary to stdout, write compact per-report status lines
+to stderr, continue independent reports after one report fails, and return
+nonzero when any report failed. `--out-dir PATH` writes extra Markdown copies
+using report default filenames such as `daily.md`, `three-day.md`,
+`weekend.md`, and `tomorrow.md`.
+
+## Filesystem Layout
+
+The default workspace root is `workspace`.
+
+```text
+workspace/
+  snapshots/
+    daily/
+      YYYY-MM-DD/
+        <run_id>.briefing.json
+        <run_id>.metadata.json
+    three-day/
+      YYYY-MM-DD/
+        <run_id>.briefing.json
+        <run_id>.metadata.json
+    weekend/
+      YYYY-MM-DD/
+        <run_id>.briefing.json
+        <run_id>.metadata.json
+    storm/
+      YYYY-MM-DD/
+        <run_id>.briefing.json
+        <run_id>.metadata.json
+  data-packages/
+    daily/
+      YYYY-MM-DD/
+        <run_id>.data_package.json
+    three-day/
+      YYYY-MM-DD/
+        <run_id>.data_package.json
+    weekend/
+      YYYY-MM-DD/
+        <run_id>.data_package.json
+    storm/
+      YYYY-MM-DD/
+        <run_id>.data_package.json
+  preflight/
+    daily/
+      YYYY-MM-DD/
+        <run_id>.render.json
+    three-day/
+      YYYY-MM-DD/
+        <run_id>.render.json
+    weekend/
+      YYYY-MM-DD/
+        <run_id>.render.json
+    storm/
+      YYYY-MM-DD/
+        <run_id>.render.json
+  reports/
+    daily/
+      <run_id>.md
+    three-day/
+      <run_id>.md
+    weekend/
+      <run_id>.md
+    storm/
+      <run_id>.md
+```
+
+Managed artifact filenames use the RunID, so repeated runs for the same valid
+period do not overwrite each other.
+
+## RunID And Metadata
+
+RunIDs are based on generation time plus report ID:
+
+```text
+20260529T100000.123456789Z_daily_today
+```
+
+Each generated report writes metadata that links:
+
+- RunID, report ID, variant, and prompt ID
+- generation time, timezone, and valid period
+- source location, source hashes, and source warnings
+- briefing snapshot path
+- prompt input data package path
+- preflight output path
+- managed Markdown report path
+
+Batch summaries include report status, error text when applicable, valid
+period, and known artifact paths for each attempted report.
+
+## Inspection
+
+Inspection commands read existing workspace artifacts and emit JSON to stdout.
+They do not fetch weather data or run `scriptorium`.
+
+```text
+weatherreporter inspect reports --limit 10
+weatherreporter inspect metadata RUN_ID
+weatherreporter inspect briefing RUN_ID
+weatherreporter inspect data-package RUN_ID
+weatherreporter inspect prior RUN_ID
+weatherreporter inspect sources RUN_ID
+```
+
+Use `inspect reports` to find recent RunIDs and artifact paths. Use
+`inspect metadata` to see the artifact links recorded for a run. Use
+`inspect briefing` and `inspect data-package` to review the exact structured
+inputs used for rendering. Use `inspect prior` to see the prior comparable
+snapshot selected for Recent Changes, or `null` when none exists. Use
+`inspect sources` to review source provenance and warnings without dumping full
+weather payloads.
+
+## Recent Changes
+
+Recent Changes are computed from structured briefing snapshots, not rendered
+Markdown text.
+
+Daily Today and Daily Tomorrow can compare with each other when they cover the
+same valid local date. 3-Day Outlook compares with prior compatible 3-Day
+snapshots for the same valid local date. Weekend Outlook compares with prior
+compatible Weekend snapshots for the same weekend window. Storm Report currently
+leaves Recent Changes empty.
+
+When no prior comparable snapshot exists, or no configured threshold is crossed,
+`recentChanges.items` is empty.
+
+## Recovery
+
+A failed generation run may still leave useful artifacts:
+
+- If `scriptorium render` returns a result with a nonzero exit code, the
+  preflight JSON and metadata are written for inspection.
+- If `scriptorium run` exits nonzero after writing a report, the managed report
+  and metadata remain available.
+- For batch commands, inspect the stdout JSON summary first, then inspect the
+  artifact paths for each failed report.
+
+For a bad report, start with:
+
+```text
+weatherreporter inspect metadata RUN_ID
+weatherreporter inspect sources RUN_ID
+weatherreporter inspect briefing RUN_ID
+weatherreporter inspect data-package RUN_ID
+weatherreporter inspect prior RUN_ID
+```
+
+## Operational Caveats
+
+- The application uses one configured Weather API endpoint.
+- The application writes local filesystem state only.
+- The application does not implement resume, cleanup, archive, remote storage,
+  daemon operation, or automatic storm monitoring.
+- Generated reports and Scriptorium stderr can contain sensitive operational
+  context. Store workspace artifacts with appropriate filesystem permissions.

docs/policy/architecture.md

@@ -46,12 +46,11 @@ Centralize configuration loading, processing, precedence, defaults, and validati
 
 The goal is to make configuration discoverable and avoid implicit or hidden operational values. User-visible defaults and cross-package operational defaults should be defined in `internal/config/defaults.go`.
 
-Unless documented otherwise, precedence is:
+Configuration precedence is:
 
 1. CLI flags
-2. environment variables
-3. configuration file
-4. built-in defaults
+2. configuration file
+3. built-in defaults
 
 Prefer YAML configuration unless the project has a strong reason to use another format. Config files should be discovered at `/usr/local/etc/<app_name>/config.yml`, with a CLI override via `--config`.
 
@@ -65,13 +64,17 @@ External adapters belong under `internal/adapters/<name>`. If an adapter uses an
 
 Adapters should be thin. Domain decisions belong in application/domain packages, not inside adapter glue.
 
-## Modules, Stages, and Registries
+## Components and Registries
 
-When the application has stages or modules, each major stage/module should live in its own package and have an explicit input/output contract.
+When the application has major workflow components, each component should live
+near the package that owns its contract and have explicit inputs and outputs.
 
-The orchestrator should be able to compose, skip, resume, or run individual stages/modules when their prerequisites are satisfied. Ordering should be explicit: use a default sequence, dependency graph, or documented orchestration rule.
+The orchestrator should compose components in an explicit order using a default
+sequence, dependency graph, or documented orchestration rule.
 
-If users can select modules, stages, validators, renderers, or adapters, selection should go through a registry or equivalent mechanism rather than scattered conditionals.
+If users can select components, validators, renderers, or adapters, selection
+should go through a registry or equivalent mechanism rather than scattered
+conditionals.
 
 ## Embedded Assets
 
@@ -87,11 +90,15 @@ Use structured logging where practical. Logs should describe operations, paths,
 
 ## Context, Timeouts, and Cancellation
 
-Long-running operations should accept `context.Context`. External calls, subprocesses, HTTP requests, storage operations, and multi-stage workflows should respect cancellation and timeouts.
+Long-running operations should accept `context.Context`. External calls,
+subprocesses, HTTP requests, storage operations, and multi-step workflows should
+respect cancellation and timeouts.
 
 ## State, Files, and Safety
 
-If the application writes durable state, writes should be atomic where practical. Multi-step workflows should preserve enough state to support inspection, retry, or resume after failure.
+If the application writes durable state, writes should be atomic where
+practical. Multi-step workflows should preserve enough state to support
+inspection and retry diagnosis after failure.
 
 Code that deletes, moves, or overwrites files must use narrow, explicit paths. Avoid broad parent-directory operations. Cleanup that can cause data loss must be opt-in.
 
@@ -99,11 +106,14 @@ Code that deletes, moves, or overwrites files must use narrow, explicit paths. A
 
 Core logic should be testable without real external services. Use fakes, fixtures, or local test doubles for adapters where practical.
 
-Config examples should be load-tested. Important CLI workflows should have parser or command tests. Stage/module contracts should have focused tests that do not require running the full application unless end-to-end coverage is intentional.
+Config examples should be load-tested. Important CLI workflows should have
+parser or command tests. Component contracts should have focused tests that do
+not require running the full application unless end-to-end coverage is
+intentional.
 
 ## Documentation
 
 Documentation should follow the project documentation policy. Keep user docs focused on implemented behavior. Put future, planned, or aspirational work only under `docs/roadmap/`.
 
-When changing architecture, config, CLI behavior, adapters, or stage/module contracts, update the relevant docs and examples in the same change.
-
+When changing architecture, config, CLI behavior, adapters, or component
+contracts, update the relevant docs and examples in the same change.

docs/policy/development.md

@@ -1,691 +1,193 @@
-# Weatherreporter Package Layout
+# Development Policy
 
-This document defines the proposed package layout for `weatherreporter`, a Go application that prepares human-facing weather reports from normalized weather data collected by `weatherfeeder` and rendered through `scriptorium`.
+This document is the contributor workflow policy for `weatherreporter`.
+Developers and LLM coding agents should use it with
+`docs/policy/architecture.md` and `docs/policy/documentation.md`.
 
-The application should remain a small, explicit, dependency-light Go program. Domain logic should live outside CLI, transport, and external-adapter packages. External systems should be isolated behind narrow adapters. Report-specific behavior should be selected through a registry or equivalent mechanism rather than scattered conditionals.
+## Repository Layout
 
-## Architectural Summary
+- `cmd/weatherreporter`: binary entry point.
+- `internal/app`: orchestration for generation, batches, fetch helpers, and
+  inspection.
+- `internal/cli`: command parsing, flag handling, help text, and JSON output.
+- `internal/config`: configuration structs, defaults, loading, overrides, and
+  validation.
+- `internal/fileutil`: shared atomic filesystem write and copy helpers.
+- `internal/adapters/weatherapi`: Weather API HTTP adapter.
+- `internal/adapters/scriptorium`: Scriptorium subprocess adapter.
+- `internal/forecast`: normalized bundle types and deterministic forecast
+  derivation.
+- `internal/report`: report definitions, valid periods, batches, output names,
+  and comparison declarations.
+- `internal/briefing`: report-specific briefing package builders.
+- `internal/changes`: structured Recent Changes comparison.
+- `internal/promptinput`: Scriptorium `data_package` construction and
+  validation.
+- `internal/state`: filesystem paths, atomic JSON writes, metadata, lookup, and
+  inspection support.
+- `internal/timeutil`: clock, date, timezone, and period helpers.
+- `docs`: user, operator, developer, integration, internal, policy, and roadmap
+  documentation.
+- `examples`: maintained copyable examples.
 
-`weatherreporter` is a deterministic weather briefing and report-preparation application. It should:
+## Local Validation
 
-1. Fetch normalized weather data from a single configured internal weather API endpoint backed by `weatherfeeder`.
-2. Derive report-specific briefing packages from the normalized forecast bundle.
-3. Compare current briefing snapshots against prior comparable snapshots to produce optional Recent Changes.
-4. Build structured prompt input data packages for a specific report type.
-5. Invoke `scriptorium` as an external prompt runner.
-6. Persist the rendered Markdown report, briefing snapshot, prompt input package, and generation metadata.
+Use focused checks while editing and broader checks before committing:
 
-The preferred data flow is:
-
-```text
-weatherfeeder-backed internal API
-    -> weather API adapter
-    -> forecast bundle
-    -> report-specific briefing builder
-    -> recent-change comparison
-    -> prompt input data package
-    -> scriptorium subprocess adapter
-    -> Markdown report + metadata + stored snapshot
+```bash
+go test ./...
+go run ./cmd/weatherreporter --help
+git diff --check
 ```
 
-The application should not treat the LLM as the source of weather facts. The Go code should select the relevant data, compute daypart and period summaries, attach alerts and NWS context, identify meaningful changes, and send the LLM a curated briefing package. The LLM should synthesize and phrase the report for humans.
+Useful focused checks:
 
-## Proposed Directory Layout
-
-```text
-cmd/weatherreporter/
-  main.go
-
-internal/app/
-  generate.go
-  scheduled.go
-  storm.go
-
-internal/cli/
-  root.go
-  generate.go
-  run.go
-  inspect.go
-
-internal/config/
-  config.go
-  defaults.go
-  load.go
-  validate.go
-
-internal/adapters/weatherapi/
-  client.go
-  types.go
-
-internal/adapters/scriptorium/
-  runner.go
-  types.go
-
-internal/forecast/
-  bundle.go
-  dayparts.go
-  derive.go
-  select.go
-  thresholds.go
-
-internal/report/
-  definition.go
-  registry.go
-  period.go
-  daily.go
-  tomorrow.go
-  three_day.go
-  weekend.go
-  storm.go
-
-internal/briefing/
-  package.go
-  daily.go
-  tomorrow.go
-  three_day.go
-  weekend.go
-  storm.go
-
-internal/changes/
-  compare.go
-  thresholds.go
-  summary.go
-
-internal/state/
-  store.go
-  filesystem.go
-  metadata.go
-
-internal/promptinput/
-  build.go
-  schema.go
-
-internal/timeutil/
-  clock.go
-  periods.go
+```bash
+go test ./internal/cli ./internal/config
+go test ./internal/app ./internal/state
+go test ./internal/adapters/weatherapi ./internal/adapters/scriptorium
+go test ./internal/forecast ./internal/report ./internal/briefing ./internal/changes ./internal/promptinput
 ```
 
-This layout can be simplified during early prototyping if a package has only one file, but the package boundaries should remain conceptually stable.
+Run `gofmt -w` on changed Go files before committing.
 
-## Dependency Direction
+## Coding Conventions
 
-The intended dependency direction is:
+- Keep domain logic out of `cmd`, `internal/cli`, and adapter packages.
+- Prefer small explicit structs and functions over broad framework-style
+  abstractions.
+- Keep package APIs narrow and named around implemented behavior.
+- Return errors with operation, path, endpoint, report, or RunID context.
+- Do not log or expose secrets.
+- Use `context.Context` for external calls, subprocesses, and orchestrated
+  workflows that may be canceled.
+- Use atomic writes for durable JSON artifacts where practical.
+- Keep report selection and prompt IDs centralized in `internal/report`.
+- Keep Scriptorium argv construction inside `internal/adapters/scriptorium`.
+- Keep Weather API transport and envelope handling inside
+  `internal/adapters/weatherapi`.
 
-```text
-cmd/weatherreporter
-    -> internal/cli
-    -> internal/app
-    -> internal/config
-    -> internal/report
-    -> internal/briefing
-    -> internal/forecast
-    -> internal/changes
-    -> internal/state
-    -> internal/adapters/*
-```
+## Dependency Policy
 
-Rules:
+Prefer the Go standard library. Add dependencies only when they materially
+improve correctness, interoperability, security, or maintainability.
 
-- `cmd/weatherreporter` should only bootstrap the CLI.
-- `internal/cli` should parse commands and flags, then call `internal/app`.
-- `internal/app` should orchestrate workflows but avoid embedding detailed forecast logic.
-- `internal/adapters/*` should not contain domain policy.
-- `internal/forecast`, `internal/report`, `internal/briefing`, and `internal/changes` should be testable without real external services.
-- `internal/state` should expose a storage interface so filesystem state can later be replaced or supplemented.
-- `scriptorium` details should not leak outside `internal/adapters/scriptorium`.
+Current external dependency:
 
-## Package Responsibilities
+- `gopkg.in/yaml.v3` for YAML configuration parsing.
 
-### `cmd/weatherreporter`
+When adding a dependency:
 
-Entry point for the compiled binary.
+- explain why the standard library is not enough;
+- keep dependency types from leaking across unrelated package boundaries;
+- add tests for the behavior the dependency supports;
+- update this policy if the dependency becomes part of contributor workflow.
 
-Responsibilities:
+## Configuration Changes
 
-- Construct the root command from `internal/cli`.
-- Execute the command.
-- Handle final process exit behavior.
+Configuration is owned by `internal/config`.
 
-Non-responsibilities:
+When adding or changing a field:
 
-- No configuration loading details.
-- No forecast logic.
-- No direct calls to weather APIs, state stores, or `scriptorium`.
+- update `Config` and the nested config struct in `config.go`;
+- add or adjust defaults in `defaults.go` when the field has a safe default;
+- update loading or CLI override behavior in `load.go` only when needed;
+- validate required values and accepted ranges in `validate.go`;
+- add or update config tests;
+- update `docs/config.md` and maintained examples when the field is user
+  visible;
+- keep secrets out of example config files.
 
-### `internal/cli`
+Configuration precedence is:
 
-Defines the user-facing command tree, flags, arguments, and command wiring.
+1. CLI overrides supported by `config.LoadOptions`;
+2. configuration file values;
+3. built-in defaults.
 
-Responsibilities:
+The default config path is `/usr/local/etc/weatherreporter/config.yml`.
 
-- Define commands such as:
-  - `weatherreporter generate daily`
-  - `weatherreporter generate tomorrow`
-  - `weatherreporter generate three-day`
-  - `weatherreporter generate weekend`
-  - `weatherreporter generate storm`
-  - `weatherreporter run morning`
-  - `weatherreporter run evening`
-  - `weatherreporter inspect snapshot`
-- Use the Go standard library for CLI parsing unless future complexity justifies a dependency.
-- Parse flags such as `--config`, `--units`, `--tz`, `--out`, optional Daily `--date`, and storm `--start`/`--end`, then convert them into app-layer request structs.
-- Load configuration through `internal/config`.
-- Present concise user-facing errors.
+## CLI Changes
 
-Non-responsibilities:
+The CLI is owned by `internal/cli`.
 
-- No report-building logic.
-- No direct subprocess execution.
-- No direct weather API calls.
-- No state comparison logic.
+When adding or changing a command or flag:
 
-Suggested command shape:
+- update help text and parser behavior together;
+- convert parsed values into app-layer request structs;
+- keep domain decisions in `internal/app` or domain packages;
+- add parser or command tests in `internal/cli`;
+- update `docs/cli.md`;
+- update `docs/operations.md` or `docs/troubleshooting.md` when behavior affects
+  operators.
 
-```text
-weatherreporter generate daily --date 2026-05-29 --out ./daily.md
-weatherreporter generate tomorrow --out ./tomorrow.md
-weatherreporter generate three-day --out ./three_day.md
-weatherreporter generate weekend --out ./weekend.md
-weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00 --out ./storm.md
-weatherreporter run morning
-weatherreporter run evening
-```
+CLI commands should return concise actionable errors and avoid printing partial
+JSON when command construction fails.
 
-The MVP should not expose location selection. Source `locationId` and `locationName` values returned by the weather API may be retained as provenance.
+## Components And Adapters
 
-For `generate daily`, `--date` is optional. When provided, it must use `YYYY-MM-DD`; when omitted, it resolves to the current local date in the configured timezone.
+Use existing package boundaries before adding a package.
 
-### `internal/config`
+Add a new internal component only when it owns a distinct implemented contract.
+Define its inputs, outputs, state behavior, failure behavior, tests, and
+invariants in `docs/internal/`.
 
-Owns configuration structures, defaults, loading, precedence, and validation.
+Adapters should stay thin:
 
-Responsibilities:
+- HTTP adapters own transport, request construction, envelope handling, and
+  decode boundaries.
+- subprocess adapters own argv construction, timeout handling, stdout/stderr
+  capture, and exit-code interpretation.
+- adapter packages should not own report selection, forecast summarization,
+  Recent Changes, or prompt input schema decisions.
 
-- Define application configuration structs.
-- Provide built-in defaults in `defaults.go`.
-- Load YAML configuration from `/usr/local/etc/weatherreporter/config.yml` or a CLI-supplied path.
-- Use `gopkg.in/yaml.v3` for YAML parsing.
-- Apply precedence rules.
-- Validate required settings.
-- Normalize paths, durations, report settings, weather API units/timezone, missing-source policy, and daypart definitions.
+When an external contract changes, update the matching file under
+`docs/integrations/`.
 
-Suggested configuration areas:
+## Tests
 
-- Weather API base URL, timeout, units, timezone, precision, and missing-source policy.
-- `scriptorium` binary, config path, profile, timeout, and optional extra arguments.
-- Workspace and output directories.
-- Report enablement and output naming.
-- Daypart definitions.
-- Recent-change thresholds.
+Core tests must not require live Weather API or Scriptorium services.
 
-Initial defaults:
+Preferred test patterns:
 
-- Weather API units: `us`.
-- Weather API timezone: `Chicago`.
-- Weather API format: `json`.
-- Missing-source policy: `warn`.
+- fake command runners for subprocess behavior;
+- `httptest.Server` for Weather API behavior;
+- filesystem temp directories for state behavior;
+- deterministic clocks for report periods and RunIDs;
+- table tests for config validation, CLI parsing, period resolution, and
+  threshold behavior.
 
-Missing-source policy should support a global default and per-source overrides. Valid policy values are `error`, `warn`, and `none`.
+Add focused tests near the package that owns the behavior. Use app-level tests
+for workflow ordering, persistence, and cross-package contracts.
 
-Non-responsibilities:
+## Examples
 
-- No command execution.
-- No HTTP calls.
-- No report-building logic.
+Examples under `examples/` must be real, maintained, and free of secrets.
 
-### `internal/app`
+When updating examples:
 
-Application orchestration and top-level use cases.
+- use implemented config fields only;
+- avoid private endpoints and credentials;
+- keep comments short and operationally useful;
+- add or update validation coverage when a new example file is introduced;
+- link maintained examples from `docs/config.md`.
 
-Responsibilities:
+Do not add generated report examples unless they can be kept current without
+live external services.
 
-- Implement use cases such as:
-  - Generate one report.
-  - Run the morning batch.
-  - Run the evening batch.
-  - Generate a manual storm report.
-- Coordinate config, weather API adapter, report registry, briefing builders, state store, change comparison, prompt input builder, and `scriptorium` runner.
-- Enforce workflow order.
-- Ensure each generation run persists enough artifacts for inspection and future comparison.
+## Documentation Checklist
 
-The core generation workflow should be approximately:
+Documentation updates are part of behavior changes.
 
-```text
-resolve report definition
-resolve valid period
-fetch current weather bundle
-build current briefing package
-load prior comparable briefing snapshot
-compute recent changes
-build prompt input data package
-write data package
-run scriptorium render preflight
-invoke scriptorium run
-persist report metadata, briefing snapshot, data package, preflight output, and rendered report
-```
+Update:
 
-Non-responsibilities:
+- `README.md` for project orientation or quickstart changes;
+- `docs/cli.md` for command and flag changes;
+- `docs/config.md` for config fields, defaults, and precedence changes;
+- `docs/operations.md` for state, artifact, batch, inspection, and recovery
+  behavior;
+- `docs/troubleshooting.md` for recurring operator-facing failure modes;
+- `docs/internal/` for component contracts and invariants;
+- `docs/integrations/` for external Weather API or Scriptorium contract changes;
+- `docs/roadmap/` only for unimplemented or deferred work.
 
-- No detailed daypart calculations.
-- No direct parsing of NWS text unless delegated to domain packages.
-- No direct shell command construction outside the `scriptorium` adapter.
-
-### `internal/adapters/weatherapi`
-
-HTTP adapter for the internal weather API backed by `weatherfeeder`.
-
-Responsibilities:
-
-- Fetch normalized weather data from the configured API base URL.
-- Fan out to multiple weather API endpoints and assemble one internal `forecast.Bundle`.
-- Decode API responses into adapter-owned DTOs or directly into stable internal types if those types are intentionally owned by `weatherreporter`.
-- Apply request timeouts and context cancellation.
-- Apply configured query defaults, including `format=json`, `units=us`, and `tz=Chicago` unless overridden.
-- Fetch full `/forecast/hourly` and `/forecast/narrative` products, not day-slice endpoints, so Go domain code owns report-period selection.
-- Record per-source provenance: endpoint, query, fetch time, issued/updated time when available, SHA-256 over canonical/minified raw `data` JSON, warnings, and missing-source status.
-- Represent source warnings as first-class records with source name, code, severity, message, endpoint, and completeness impact.
-- Require hourly forecast data for normal scheduled reports.
-- Apply missing-source policy for `data:null`, malformed non-required sections, or unavailable upstream products.
-- Return actionable errors containing endpoint and operation context.
-
-Initial data categories:
-
-- Latest observation.
-- Current conditions.
-- Hourly forecast data.
-- NWS narrative forecast periods.
-- NWS alerts.
-- NWS forecast discussion.
-
-Stubbed source slots until upstream support exists:
-
-- Daily forecast data.
-- NWS weather story.
-
-Non-responsibilities:
-
-- No daypart grouping.
-- No Recent Changes comparison.
-- No prompt input construction.
-- No `scriptorium` calls.
-
-### `internal/adapters/scriptorium`
-
-Subprocess adapter for invoking `scriptorium`.
-
-Responsibilities:
-
-- Provide a narrow runner interface, such as:
-
-```go
-type Runner interface {
-    Render(ctx context.Context, req RenderRequest) (*RenderResult, error)
-    Run(ctx context.Context, req RunRequest) (*RunResult, error)
-}
-```
-
-- Execute `scriptorium render` for preflight/debug output without LLM generation.
-- Execute `scriptorium run` for report generation.
-- Run `scriptorium render` as an always-on preflight before `scriptorium run` for MVP generated reports.
-- Pass arguments as an argv slice, not through a shell.
-- Pass large prompt input as `--input data_package=<path>`.
-- Capture stdout/stderr with reasonable size limits.
-- Treat nonzero exits as actionable errors, including exit code `2` from `run`, which may still produce output.
-- Keep all `scriptorium`-specific flag details inside the adapter.
-
-Suggested command forms:
-
-```text
-scriptorium render \
-  --prompt weather.daily_report \
-  --input data_package=./workspace/data-packages/daily/2026-05-29T050000-0500.data_package.json \
-  --format json
-
-scriptorium run \
-  --prompt weather.daily_report \
-  --input data_package=./workspace/data-packages/daily/2026-05-29T050000-0500.data_package.json \
-  --out ./workspace/reports/daily/2026-05-29T050000-0500.md
-```
-
-Non-responsibilities:
-
-- No weather logic.
-- No report registry logic.
-- No decision about which prompt to run.
-
-Future note:
-
-- A native LLM client can later replace or supplement this adapter behind a similar interface.
-
-### `internal/forecast`
-
-Core forecast-domain processing.
-
-Responsibilities:
-
-- Define the normalized `Bundle` consumed by report builders.
-- Group hourly forecast data into configured dayparts.
-- Compute derived facts, including:
-  - Temperature ranges.
-  - Apparent-temperature ranges, if available.
-  - Max precipitation probability.
-  - Peak wind and wind gusts.
-  - Precipitation windows.
-  - Thunder mentions.
-  - Snow/ice/freezing risk indicators.
-  - Alert overlap with relevant periods.
-- Select forecast elements relevant to a report period.
-- Provide threshold helpers for impact detection.
-
-Non-responsibilities:
-
-- No CLI behavior.
-- No external API calls.
-- No rendered prose.
-- No direct `scriptorium` calls.
-
-### `internal/report`
-
-Report definitions, registry, period resolution, and report-level contracts.
-
-Responsibilities:
-
-- Define report IDs and report definition contracts.
-- Register report types and variants.
-- Resolve valid periods for each report.
-- Associate report types with prompt IDs.
-- Define comparison strategies and output naming behavior.
-
-Suggested report definitions:
-
-```text
-daily_today       -> prompt weather.daily_report
-daily_tomorrow    -> prompt weather.daily_report
-three_day         -> prompt weather.three_day_outlook
-weekend           -> prompt weather.weekend_outlook
-storm             -> prompt weather.storm_report
-```
-
-`weather.daily_report` should be the standard prompt for one local civil day, regardless of whether that day is today or tomorrow.
-
-A report definition should describe:
-
-- Report ID.
-- Human-readable name.
-- Prompt ID.
-- Valid-period resolver.
-- Briefing builder ID or function.
-- Recent-change comparison strategy.
-- Default output naming pattern.
-- Whether the report participates in morning or evening scheduled batches.
-
-Non-responsibilities:
-
-- No detailed forecast computation.
-- No state storage.
-- No subprocess execution.
-
-### `internal/briefing`
-
-Builds report-specific briefing packages from forecast bundles and report definitions.
-
-Responsibilities:
-
-- Convert a forecast bundle into a report-specific structured briefing package.
-- Keep each report's briefing shape explicit and testable.
-- Attach relevant NWS narrative periods, alerts, forecast discussion context, and weather story context when available.
-- Include metadata such as schema version, configured units/timezone, source warnings, and source provenance.
-- Provide inputs suitable for `scriptorium` data packages.
-
-Report-specific builders should exist for:
-
-- Daily Report.
-- Tomorrow Planning Brief.
-- 3-Day Outlook.
-- Weekend Outlook.
-- Storm Report.
-
-Non-responsibilities:
-
-- No external API fetching.
-- No final prose rendering.
-- No state persistence, except through app orchestration.
-
-Design note:
-
-- This package is the architectural center of the application. A clean briefing package makes `scriptorium` a renderer rather than a source of weather reasoning.
-
-### `internal/changes`
-
-Structured comparison of current and prior briefing snapshots.
-
-Responsibilities:
-
-- Compare current briefing packages against prior comparable snapshots.
-- Apply meaningful-change thresholds.
-- Produce compact structured change summaries for prompt input data packages.
-- Avoid comparison of rendered Markdown report text.
-
-Comparable snapshot matching should be declared by each report definition. Daily Today, Daily Tomorrow, and compatible date slices from multi-day reports may compare by same valid local date when the report registry marks them compatible. Weekend compares by same weekend window. Storm compares by explicit event window.
-
-Meaningful changes may include:
-
-- Temperature changes crossing configured thresholds.
-- Precipitation probability changes by category.
-- Precipitation timing shifts.
-- New, canceled, extended, upgraded, or expanded alerts.
-- Wind gust threshold crossings.
-- Snow/ice/freezing risk changes.
-- Severe-weather wording or risk changes.
-- Confidence or uncertainty changes, if represented in structured briefing data.
-
-Non-responsibilities:
-
-- No fetching prior state directly unless mediated through app/state contracts.
-- No final report prose.
-- No external calls.
-
-### `internal/state`
-
-Durable state store for reports, snapshots, data packages, preflight output, metadata, and comparison lookup.
-
-Responsibilities:
-
-- Persist generated report metadata.
-- Persist briefing snapshots.
-- Persist prompt input data packages.
-- Persist `scriptorium render` preflight output for generated reports.
-- Locate prior comparable snapshots for Recent Changes.
-- Track RunID as generation timestamp plus report ID.
-- Use timestamped managed report names to avoid overwriting prior runs for the same valid period.
-- Use atomic writes where practical.
-- Keep filesystem layout narrow and predictable.
-
-Initial backend:
-
-- Filesystem state.
-
-Potential future backend:
-
-- SQLite or another state database, behind the same store interface.
-
-Suggested state layout:
-
-```text
-workspace/
-  snapshots/
-    daily/
-      2026-05-30/
-        2026-05-29T050000-0500.briefing.json
-        2026-05-29T050000-0500.metadata.json
-    three-day/
-    weekend/
-    storm/
-  reports/
-    daily/
-      2026-05-29T050000-0500.md
-    three-day/
-    weekend/
-    storm/
-  data-packages/
-    daily/
-      2026-05-29T050000-0500.data_package.json
-  preflight/
-    daily/
-      2026-05-29T050000-0500.render.json
-```
-
-Non-responsibilities:
-
-- No weather derivation.
-- No report prose generation.
-- No CLI formatting decisions.
-
-### `internal/promptinput`
-
-Builds the final data package passed to `scriptorium`.
-
-Responsibilities:
-
-- Combine report metadata, briefing package, Recent Changes, selected source context, and source warnings into a prompt input document.
-- Validate required data package fields before invoking `scriptorium`.
-- Keep data package schemas explicit enough to test.
-- Write data package files to the workspace when requested by the app layer.
-
-Non-responsibilities:
-
-- No weather API calls.
-- No forecast derivation.
-- No subprocess execution.
-
-### `internal/timeutil`
-
-Time, clock, and period helpers.
-
-Responsibilities:
-
-- Provide an injectable clock for deterministic tests.
-- Resolve local dates using the configured report timezone.
-- Handle daypart spans, including overnight windows.
-- Normalize valid periods.
-- Provide helpers for recurring scheduled batches.
-
-Non-responsibilities:
-
-- No report-specific forecast logic unless delegated by `internal/report`.
-- No external calls.
-
-## Report Types and Valid-Period Identity
-
-Each generated report must be associated with explicit metadata:
-
-- RunID.
-- Report type.
-- Report variant, if applicable.
-- Generation time.
-- Configured report timezone.
-- Valid period start.
-- Valid period end.
-- Source location ID/name when provided by upstream.
-- Source product timestamps and/or SHA-256 hashes.
-- Source warnings.
-- Briefing snapshot path.
-- Prompt input data package path.
-- Preflight output path.
-- Rendered report path.
-
-All valid periods should use the configured local timezone, default `Chicago`, and half-open `[start,end)` intervals.
-
-Initial valid-period rules:
-
-- Daily Today: current local civil day, `[00:00, next 00:00)`.
-- Daily Tomorrow: next local civil day.
-- 3-Day Outlook: generation time through local midnight after the second following local civil day.
-- Weekend Outlook: Monday through Thursday covers Saturday 00:00 to Monday 00:00; Friday and Saturday cover `max(generation time, Friday 18:00)` to Monday 00:00; scheduled Sunday morning skips Weekend Outlook.
-- Manual Storm Report: requires explicit `--start` and `--end`; accept `YYYY-MM-DDTHH:MM` interpreted in the configured timezone and RFC3339 timestamps with explicit offsets.
-
-The valid period should identify what weather period the report covers, independent of when the report was generated.
-
-Examples:
-
-- A 5 PM Tomorrow Planning Brief for Saturday and a 5 AM Saturday Daily Report both cover the same valid date.
-- A Saturday Weekend Outlook covers the remaining weekend, while a Friday Weekend Outlook may cover Friday evening through Sunday night.
-- A Storm Report covers an explicit forecast event window, not a fixed calendar day.
-
-This identity is required for reliable Recent Changes behavior.
-
-## Scheduled Batch Semantics
-
-The app should support scheduled batches but should not need to be a daemon in the initial version.
-
-Suggested batches:
-
-```text
-morning:
-  - daily_today
-  - three_day
-  - weekend, except Sunday
-
-evening:
-  - daily_tomorrow
-```
-
-Scheduled batches should continue independent reports after a report failure. The CLI should return nonzero if any report failed and should emit an aggregate run summary.
-
-External scheduling should be handled by systemd timers, cron, or another orchestrator. `weatherreporter` should simply provide deterministic commands that can be scheduled.
-
-## Storm Report Direction
-
-The initial version should support manual Storm Report generation:
-
-```text
-weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00
-```
-
-Future storm monitoring should use a staged design:
-
-```text
-incoming weather data
-    -> deterministic candidate detector
-    -> LLM event evaluator
-    -> storm lifecycle state
-    -> storm report generation or skip decision
-```
-
-Potential storm lifecycle states:
-
-```text
-none -> monitoring -> active_report -> escalated -> deescalating -> resolved
-```
-
-This future behavior should not be built before the core scheduled reports are stable, but the package layout should leave room for it.
-
-## Testing Expectations
-
-Core tests should not require real external services.
-
-Priority test areas:
-
-- Configuration loading and validation, including defaults for `units=us`, `tz=Chicago`, and missing-source policy `warn`.
-- Standard-library CLI command parsing, including `--units`, `--tz`, and storm `--start`/`--end`.
-- Weather API fan-out, source provenance, `data:null`, and missing-source policy behavior.
-- Daypart grouping, especially overnight periods.
-- Valid-period resolution for each report type.
-- Briefing package construction from fixtures.
-- Recent Changes threshold behavior and compatible snapshot matching.
-- Prior snapshot lookup.
-- `scriptorium` adapter behavior using a fake executable or command runner, including both `render` and `run` with `--input data_package=<path>`.
-- Batch partial-failure behavior and aggregate exit status.
-
-## Design Invariants
-
-Preserve these invariants as the project evolves:
-
-- Weather facts come from normalized source data, not from the LLM.
-- The LLM receives curated briefing packages, not unbounded raw weather payloads.
-- Recent Changes are based on structured snapshot comparison, not Markdown diffing.
-- Report types are registered or otherwise centrally defined.
-- External integrations are thin adapters.
-- CLI code wires workflows but does not own domain logic.
-- The first durable state backend is filesystem-based and inspectable.
-- `scriptorium` is an adapter boundary, not an application dependency that leaks across packages.
+Non-roadmap docs must describe implemented behavior only.

docs/roadmap/future.md

@@ -0,0 +1,85 @@
+# Future Roadmap
+
+This roadmap contains project work that is not implemented. Current behavior is
+documented outside `docs/roadmap/`.
+
+## Deferred: Automatic Storm Monitoring
+
+Manual Storm Report generation is implemented through
+`weatherreporter generate storm --start TIME --end TIME`. Automatic storm-event
+evaluation remains deferred.
+
+Proposed direction:
+
+1. detect candidate events deterministically from alerts, forecast discussion,
+   weather story context, hourly thresholds, and material forecast changes;
+2. evaluate candidates through Scriptorium or another narrow evaluator adapter;
+3. persist storm lifecycle state;
+4. generate or update Storm Reports only when a meaningful event is present;
+5. suppress ordinary low-impact thunder or rain chances.
+
+Possible lifecycle states:
+
+- `none`
+- `monitoring`
+- `active_report`
+- `escalated`
+- `deescalating`
+- `resolved`
+
+Acceptance criteria before implementation:
+
+- scheduled reports and manual Storm Reports remain stable;
+- candidate detection has fixture coverage;
+- evaluator failures are inspectable and do not create noisy report output;
+- manual Storm Report generation remains available.
+
+## Deferred: Alternate Runtime Integrations
+
+These ideas are not current behavior:
+
+- native LLM client inside `weatherreporter`;
+- database-backed state;
+- public HTTP API;
+- multi-location selection;
+- daemon mode;
+- multi-user authorization;
+- plugin system.
+
+Each item needs its own design note before implementation. Non-roadmap docs
+must not describe these as available behavior.
+
+## Deferred: Cleanup Refactors
+
+The initial cleanup pass intentionally left these refactors out because the
+current implementation does not yet make them worth the added abstraction.
+
+Revisit these only when new source types, report types, operational
+requirements, or recurring maintenance costs make the duplication materially
+more expensive:
+
+- Weather API optional-source specification/helper refactor: consider when
+  additional Weather API sources make per-source fan-out, policy handling, and
+  provenance wiring repetitive enough to obscure adapter behavior.
+- Broad briefing weather-signal consolidation: consider when multiple briefing
+  builders repeatedly derive the same weather signals and tests begin to need
+  coordinated fixture updates.
+- Generic workflow engine: defer unless generation, inspection, recovery, or
+  future background workflows gain enough shared step semantics to justify a
+  declared execution model.
+- Plugin architecture: defer until there is a concrete external extension
+  contract and at least one implemented extension point.
+- Cobra migration: defer while the standard-library CLI remains small,
+  explicit, and covered by parser tests.
+- Manifest, resume, or progress system: defer until operators need resumable
+  runs, checkpoint recovery, or richer audit trails than the current durable
+  artifacts and metadata provide.
+- Global test helper package: defer while package-local helpers keep tests
+  clear; revisit only if setup duplication starts to hide behavior.
+- Logging subsystem: defer until there are recurring operator diagnostics that
+  cannot be handled with current errors, metadata, inspection commands, and
+  artifact output.
+
+Any future implementation should preserve the existing public CLI, artifact
+paths, report identities, and adapter boundaries unless a separate roadmap
+explicitly changes them.

docs/troubleshooting.md

@@ -0,0 +1,235 @@
+# Weatherreporter Troubleshooting
+
+This guide lists recurring failures with likely causes, diagnostics, and safe
+fixes. See [CLI reference](cli.md), [Configuration reference](config.md), and
+[Operations guide](operations.md) for normal usage.
+
+## `weather_api.base_url is required`
+
+Symptom: a generation command fails before fetching weather data.
+
+Likely cause: no Weather API base URL is configured.
+
+Diagnostic:
+
+```sh
+weatherreporter generate daily --config ./config.yml --date 2026-05-29
+```
+
+Safe fix: add `weather_api.base_url` to the config file, or pass the intended
+config path with `--config`.
+
+Relevant docs: [Configuration reference](config.md).
+
+## `weather_api.base_url must be an absolute URL`
+
+Symptom: config loading fails with a base URL validation error.
+
+Likely cause: `weather_api.base_url` is missing a scheme or host.
+
+Diagnostic: inspect the configured value in the file passed to `--config`.
+
+Safe fix: use an absolute URL such as `https://weather.api.example.com/`.
+
+Relevant docs: [Configuration reference](config.md).
+
+## Invalid Timezone
+
+Symptom: config loading fails with `weather_api.timezone` context, or a CLI
+timezone override fails.
+
+Likely cause: `weather_api.timezone` or `--tz` is not recognized.
+
+Diagnostic:
+
+```sh
+weatherreporter generate daily --tz America/Chicago --date 2026-05-29
+```
+
+Safe fix: use an accepted timezone value, such as an IANA timezone name,
+`Chicago`, `Stl`, a US timezone abbreviation, or a UTC offset.
+
+Relevant docs: [Configuration reference](config.md).
+
+## Storm Command Rejects Time Bounds
+
+Symptom: `generate storm` fails with `requires --start`, `requires --end`, or
+`requires --end after --start`.
+
+Likely cause: the manual event window is missing or invalid.
+
+Diagnostic:
+
+```sh
+weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00
+```
+
+Safe fix: provide both bounds. Use `YYYY-MM-DDTHH:MM` in the configured
+timezone, or RFC3339 timestamps with explicit offsets.
+
+Relevant docs: [CLI reference](cli.md).
+
+## Weather API Fetch Fails
+
+Symptom: generation fails with `fetch /...`, an HTTP status, or request context.
+
+Likely cause: the configured Weather API endpoint is unreachable, returned a
+non-2xx response, or returned an invalid response envelope.
+
+Diagnostic:
+
+```sh
+weatherreporter generate daily --config ./config.yml --date 2026-05-29
+```
+
+Safe fix: verify `weather_api.base_url`, network access, and the Weather API
+service response. The adapter fetches `/observations`, `/conditions/current`,
+`/forecast/hourly`, `/forecast/narrative`, `/alerts/active`, and `/discussion`.
+
+Relevant docs: [Configuration reference](config.md).
+
+## Hourly Forecast Is Missing
+
+Symptom: generation fails with hourly forecast context, such as missing hourly
+data or an hourly forecast containing no periods.
+
+Likely cause: hourly forecast data is required for generated reports.
+
+Diagnostic: check the Weather API response for `/forecast/hourly`.
+
+Safe fix: restore hourly forecast data at the Weather API. Missing-source
+policy cannot make hourly optional.
+
+Relevant docs: [Configuration reference](config.md), [Operations guide](operations.md).
+
+## Source Warnings Appear
+
+Symptom: generation succeeds, but metadata or `inspect sources` shows source
+warnings.
+
+Likely cause: an optional source was missing or malformed under a warning
+missing-source policy.
+
+Diagnostic:
+
+```sh
+weatherreporter inspect sources RUN_ID
+weatherreporter inspect metadata RUN_ID
+```
+
+Safe fix: inspect the warning `source`, `code`, `message`, and `endpoint`. Fix
+the upstream optional source, or intentionally change the relevant
+`missing_source` policy.
+
+Relevant docs: [Configuration reference](config.md), [Operations guide](operations.md).
+
+## `scriptorium` Is Not Found Or Cannot Start
+
+Symptom: generation fails with `run scriptorium render` or `run scriptorium`
+and an executable or OS error.
+
+Likely cause: the configured Scriptorium binary is unavailable or not
+executable.
+
+Diagnostic: check `scriptorium.binary` in config and run the same binary outside
+`weatherreporter`.
+
+Safe fix: install Scriptorium, update `scriptorium.binary`, or fix executable
+permissions.
+
+Relevant docs: [Configuration reference](config.md),
+[Scriptorium integration](integrations/scriptorium.md).
+
+## Render Preflight Fails
+
+Symptom: generation fails with `scriptorium render exited with code ...`.
+
+Likely cause: Scriptorium rejected the prompt, config, profile, or
+`data_package` input before report generation.
+
+Diagnostic:
+
+```sh
+weatherreporter inspect metadata RUN_ID
+weatherreporter inspect data-package RUN_ID
+```
+
+Then read the preflight path from metadata. It contains captured stdout, stderr,
+exit code, and command.
+
+Safe fix: fix the Scriptorium configuration, prompt ID, profile, or data package
+input indicated by stderr.
+
+Relevant docs: [Operations guide](operations.md),
+[Scriptorium integration](integrations/scriptorium.md).
+
+## Scriptorium Run Fails
+
+Symptom: generation fails with `scriptorium run exited with code ...`.
+
+Likely cause: Scriptorium failed during report generation or validation.
+
+Diagnostic:
+
+```sh
+weatherreporter inspect metadata RUN_ID
+weatherreporter inspect data-package RUN_ID
+```
+
+If metadata includes a rendered report path, inspect that report as well. A
+nonzero run can still leave a managed report artifact.
+
+Safe fix: use the captured stderr and data package to fix the Scriptorium
+prompt, profile, model configuration, or validation issue.
+
+Relevant docs: [Operations guide](operations.md),
+[Scriptorium integration](integrations/scriptorium.md).
+
+## Batch Command Returns Nonzero
+
+Symptom: `run morning` or `run evening` returns nonzero.
+
+Likely cause: at least one report in the batch failed.
+
+Diagnostic: inspect stdout for the JSON summary and stderr for compact status
+lines.
+
+Safe fix: use the failed report's artifact paths from the summary, then inspect
+metadata, sources, briefing, and data package for that RunID.
+
+Relevant docs: [CLI reference](cli.md), [Operations guide](operations.md).
+
+## Unknown RunID
+
+Symptom: an inspect command fails with `metadata for run id ... was not found`.
+
+Likely cause: the RunID is mistyped or the command is reading a different
+workspace.
+
+Diagnostic:
+
+```sh
+weatherreporter inspect reports --config ./config.yml --limit 20
+```
+
+Safe fix: copy a RunID from `inspect reports`, or use the same `--config` and
+workspace that generated the report.
+
+Relevant docs: [Operations guide](operations.md).
+
+## Workspace Path Error
+
+Symptom: startup or inspection fails with workspace path validation or
+filesystem read/write context.
+
+Likely cause: a workspace subdirectory is absolute, escapes `workspace.root`, or
+the process cannot read or write the configured path.
+
+Diagnostic: review `workspace.root`, `workspace.snapshots_dir`,
+`workspace.reports_dir`, `workspace.data_packages_dir`, and
+`workspace.preflight_dir`.
+
+Safe fix: keep workspace subdirectories relative to `workspace.root`, and grant
+the process appropriate filesystem permissions.
+
+Relevant docs: [Configuration reference](config.md), [Operations guide](operations.md).

examples/config.yml

@@ -0,0 +1,51 @@
+weather_api:
+  base_url: https://weather.api.rakestrawhome.com/
+  timeout: 15s
+  precision: 1
+  units: us
+  timezone: "America/Chicago"
+  format: json
+
+location:
+  id: home
+  name: Brentwood
+  region: St. Louis Metro
+
+missing_source:
+  default: warn
+  sources:
+    alerts: none
+
+scriptorium:
+  binary: scriptorium
+  timeout: 2m
+
+workspace:
+  root: workspace
+  snapshots_dir: snapshots
+  reports_dir: reports
+  data_packages_dir: data-packages
+  preflight_dir: preflight
+
+dayparts:
+  - name: overnight
+    start: "00:00"
+    end: "06:00"
+  - name: morning
+    start: "06:00"
+    end: "10:00"
+  - name: midday
+    start: "10:00"
+    end: "15:00"
+  - name: afternoon
+    start: "15:00"
+    end: "17:00"
+  - name: evening
+    start: "17:00"
+    end: "24:00"
+
+recent_change:
+  temperature_degrees: 5
+  precip_probability_points: 20
+  wind_gust_miles_per_hour: 10
+  precip_timing_shift_minutes: 120

examples/minimal-config.yml

@@ -0,0 +1,2 @@
+weather_api:
+  base_url: https://weather.api.example.com/

go.mod

@@ -0,0 +1,5 @@
+module gitea.maximumdirect.net/eric/weatherreporter
+
+go 1.26
+
+require gopkg.in/yaml.v3 v3.0.1

go.sum

@@ -0,0 +1,4 @@
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/adapters/scriptorium/runner.go

@@ -0,0 +1,248 @@
+// Package scriptorium adapts the external scriptorium CLI.
+package scriptorium
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os/exec"
+	"time"
+)
+
+const maxCapturedOutputBytes = 1024 * 1024
+
+type CommandRunner interface {
+	Run(ctx context.Context, name string, args []string, timeout time.Duration) (CommandResult, error)
+}
+
+type CommandResult struct {
+	Stdout          []byte
+	Stderr          []byte
+	StdoutTruncated bool
+	StderrTruncated bool
+	ExitCode        int
+}
+
+type ExecRunner struct{}
+
+func (ExecRunner) Run(ctx context.Context, name string, args []string, timeout time.Duration) (CommandResult, error) {
+	runCtx := ctx
+	cancel := func() {}
+	if timeout > 0 {
+		runCtx, cancel = context.WithTimeout(ctx, timeout)
+	}
+	defer cancel()
+
+	cmd := exec.CommandContext(runCtx, name, args...)
+	stdout := &limitedBuffer{limit: maxCapturedOutputBytes}
+	stderr := &limitedBuffer{limit: maxCapturedOutputBytes}
+	cmd.Stdout = stdout
+	cmd.Stderr = stderr
+	err := cmd.Run()
+	result := CommandResult{
+		Stdout:          stdout.Bytes(),
+		Stderr:          stderr.Bytes(),
+		StdoutTruncated: stdout.Truncated(),
+		StderrTruncated: stderr.Truncated(),
+		ExitCode:        0,
+	}
+	if err == nil {
+		return result, nil
+	}
+	if runCtx.Err() != nil {
+		return result, runCtx.Err()
+	}
+	if exitErr, ok := err.(*exec.ExitError); ok {
+		result.ExitCode = exitErr.ExitCode()
+		return result, nil
+	}
+	return result, err
+}
+
+type Runner struct {
+	Binary     string
+	ConfigPath string
+	Profile    string
+	Timeout    time.Duration
+	ExtraArgs  []string
+	Commands   CommandRunner
+}
+
+type RenderRequest struct {
+	PromptID        string
+	DataPackagePath string
+}
+
+type RunRequest struct {
+	PromptID        string
+	DataPackagePath string
+	OutputPath      string
+}
+
+type RenderResult struct {
+	Command         []string `json:"command"`
+	Stdout          string   `json:"stdout"`
+	Stderr          string   `json:"stderr"`
+	StdoutTruncated bool     `json:"stdoutTruncated,omitempty"`
+	StderrTruncated bool     `json:"stderrTruncated,omitempty"`
+	ExitCode        int      `json:"exitCode"`
+}
+
+type RunResult struct {
+	Command         []string `json:"command"`
+	Stdout          string   `json:"stdout"`
+	Stderr          string   `json:"stderr"`
+	StdoutTruncated bool     `json:"stdoutTruncated,omitempty"`
+	StderrTruncated bool     `json:"stderrTruncated,omitempty"`
+	ExitCode        int      `json:"exitCode"`
+	OutputPath      string   `json:"outputPath"`
+}
+
+func (r Runner) Render(ctx context.Context, req RenderRequest) (*RenderResult, error) {
+	if req.PromptID == "" {
+		return nil, fmt.Errorf("prompt id is required")
+	}
+	if req.DataPackagePath == "" {
+		return nil, fmt.Errorf("data package path is required")
+	}
+	execution, err := r.execute(ctx, r.renderArgs(req))
+	if err != nil {
+		return nil, fmt.Errorf("run scriptorium render: %w", err)
+	}
+	result := &RenderResult{
+		Command:         execution.argv(),
+		Stdout:          string(execution.result.Stdout),
+		Stderr:          string(execution.result.Stderr),
+		StdoutTruncated: execution.result.StdoutTruncated,
+		StderrTruncated: execution.result.StderrTruncated,
+		ExitCode:        execution.result.ExitCode,
+	}
+	if execution.result.ExitCode != 0 {
+		return result, fmt.Errorf("scriptorium render exited with code %d: %s", execution.result.ExitCode, result.Stderr)
+	}
+	return result, nil
+}
+
+func (r Runner) Run(ctx context.Context, req RunRequest) (*RunResult, error) {
+	if req.PromptID == "" {
+		return nil, fmt.Errorf("prompt id is required")
+	}
+	if req.DataPackagePath == "" {
+		return nil, fmt.Errorf("data package path is required")
+	}
+	if req.OutputPath == "" {
+		return nil, fmt.Errorf("output path is required")
+	}
+	execution, err := r.execute(ctx, r.runArgs(req))
+	if err != nil {
+		return nil, fmt.Errorf("run scriptorium: %w", err)
+	}
+	result := &RunResult{
+		Command:         execution.argv(),
+		Stdout:          string(execution.result.Stdout),
+		Stderr:          string(execution.result.Stderr),
+		StdoutTruncated: execution.result.StdoutTruncated,
+		StderrTruncated: execution.result.StderrTruncated,
+		ExitCode:        execution.result.ExitCode,
+		OutputPath:      req.OutputPath,
+	}
+	if execution.result.ExitCode != 0 {
+		return result, fmt.Errorf("scriptorium run exited with code %d: %s", execution.result.ExitCode, result.Stderr)
+	}
+	return result, nil
+}
+
+type execution struct {
+	binary string
+	args   []string
+	result CommandResult
+}
+
+func (r Runner) execute(ctx context.Context, args []string) (execution, error) {
+	binary := r.Binary
+	if binary == "" {
+		binary = "scriptorium"
+	}
+	commands := r.Commands
+	if commands == nil {
+		commands = ExecRunner{}
+	}
+	result, err := commands.Run(ctx, binary, args, r.Timeout)
+	if err != nil {
+		return execution{}, err
+	}
+	return execution{binary: binary, args: args, result: result}, nil
+}
+
+func (e execution) argv() []string {
+	return append([]string{e.binary}, e.args...)
+}
+
+func (r Runner) renderArgs(req RenderRequest) []string {
+	args := []string{"render"}
+	if r.ConfigPath != "" {
+		args = append(args, "--config", r.ConfigPath)
+	}
+	if r.Profile != "" {
+		args = append(args, "--profile", r.Profile)
+	}
+	args = append(args,
+		"--prompt", req.PromptID,
+		"--input", "data_package="+req.DataPackagePath,
+		"--format", "json",
+	)
+	args = append(args, r.ExtraArgs...)
+	return args
+}
+
+func (r Runner) runArgs(req RunRequest) []string {
+	args := []string{"run"}
+	if r.ConfigPath != "" {
+		args = append(args, "--config", r.ConfigPath)
+	}
+	if r.Profile != "" {
+		args = append(args, "--profile", r.Profile)
+	}
+	args = append(args,
+		"--prompt", req.PromptID,
+		"--input", "data_package="+req.DataPackagePath,
+		"--out", req.OutputPath,
+	)
+	args = append(args, r.ExtraArgs...)
+	return args
+}
+
+type limitedBuffer struct {
+	data      []byte
+	limit     int
+	truncated bool
+}
+
+func (b *limitedBuffer) Write(p []byte) (int, error) {
+	if b.limit <= 0 {
+		b.truncated = true
+		return len(p), nil
+	}
+	remaining := b.limit - len(b.data)
+	if remaining <= 0 {
+		b.truncated = true
+		return len(p), nil
+	}
+	if len(p) > remaining {
+		b.data = append(b.data, p[:remaining]...)
+		b.truncated = true
+		return len(p), nil
+	}
+	b.data = append(b.data, p...)
+	return len(p), nil
+}
+
+func (b *limitedBuffer) Bytes() []byte {
+	return append([]byte{}, b.data...)
+}
+
+func (b *limitedBuffer) Truncated() bool {
+	return b.truncated
+}
+
+var _ io.Writer = (*limitedBuffer)(nil)

internal/adapters/scriptorium/runner_test.go

@@ -0,0 +1,163 @@
+package scriptorium
+
+import (
+	"context"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestRenderConstructsCommand(t *testing.T) {
+	commands := &fakeCommands{result: CommandResult{Stdout: []byte(`{"ok":true}`)}}
+	runner := Runner{
+		Binary:     "/usr/local/bin/scriptorium",
+		ConfigPath: "/etc/scriptorium.yml",
+		Profile:    "weather",
+		Timeout:    time.Minute,
+		Commands:   commands,
+	}
+
+	result, err := runner.Render(context.Background(), RenderRequest{
+		PromptID:        "weather.daily_report",
+		DataPackagePath: "/tmp/data_package.json",
+	})
+	if err != nil {
+		t.Fatalf("Render() error = %v", err)
+	}
+
+	wantArgs := []string{
+		"render",
+		"--config", "/etc/scriptorium.yml",
+		"--profile", "weather",
+		"--prompt", "weather.daily_report",
+		"--input", "data_package=/tmp/data_package.json",
+		"--format", "json",
+	}
+	if commands.name != "/usr/local/bin/scriptorium" {
+		t.Fatalf("command name = %q, want custom binary", commands.name)
+	}
+	if !reflect.DeepEqual(commands.args, wantArgs) {
+		t.Fatalf("args = %#v, want %#v", commands.args, wantArgs)
+	}
+	if !reflect.DeepEqual(result.Command, append([]string{"/usr/local/bin/scriptorium"}, wantArgs...)) {
+		t.Fatalf("result command = %#v, want full argv", result.Command)
+	}
+}
+
+func TestRenderReturnsResultForNonzeroExit(t *testing.T) {
+	runner := Runner{
+		Commands: &fakeCommands{
+			result: CommandResult{
+				Stderr:   []byte("missing input"),
+				ExitCode: 1,
+			},
+		},
+	}
+
+	result, err := runner.Render(context.Background(), RenderRequest{
+		PromptID:        "weather.daily_report",
+		DataPackagePath: "/tmp/data_package.json",
+	})
+	if err == nil {
+		t.Fatal("Render() error = nil, want nonzero exit error")
+	}
+	if result == nil {
+		t.Fatal("Render() result = nil, want captured result")
+	}
+	if result.ExitCode != 1 {
+		t.Fatalf("ExitCode = %d, want 1", result.ExitCode)
+	}
+	if !strings.Contains(err.Error(), "missing input") {
+		t.Fatalf("error = %q, want stderr context", err.Error())
+	}
+}
+
+func TestRunConstructsCommand(t *testing.T) {
+	commands := &fakeCommands{result: CommandResult{Stderr: []byte("wrote report")}}
+	runner := Runner{
+		Binary:     "/usr/local/bin/scriptorium",
+		ConfigPath: "/etc/scriptorium.yml",
+		Profile:    "weather",
+		Timeout:    45 * time.Second,
+		Commands:   commands,
+	}
+
+	result, err := runner.Run(context.Background(), RunRequest{
+		PromptID:        "weather.daily_report",
+		DataPackagePath: "/tmp/data_package.json",
+		OutputPath:      "/tmp/daily.md",
+	})
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+
+	wantArgs := []string{
+		"run",
+		"--config", "/etc/scriptorium.yml",
+		"--profile", "weather",
+		"--prompt", "weather.daily_report",
+		"--input", "data_package=/tmp/data_package.json",
+		"--out", "/tmp/daily.md",
+	}
+	if commands.name != "/usr/local/bin/scriptorium" {
+		t.Fatalf("command name = %q, want custom binary", commands.name)
+	}
+	if !reflect.DeepEqual(commands.args, wantArgs) {
+		t.Fatalf("args = %#v, want %#v", commands.args, wantArgs)
+	}
+	if commands.timeout != 45*time.Second {
+		t.Fatalf("timeout = %s, want 45s", commands.timeout)
+	}
+	if !reflect.DeepEqual(result.Command, append([]string{"/usr/local/bin/scriptorium"}, wantArgs...)) {
+		t.Fatalf("result command = %#v, want full argv", result.Command)
+	}
+	if result.OutputPath != "/tmp/daily.md" {
+		t.Fatalf("OutputPath = %q, want /tmp/daily.md", result.OutputPath)
+	}
+}
+
+func TestRunReturnsResultForValidationExit(t *testing.T) {
+	runner := Runner{
+		Commands: &fakeCommands{
+			result: CommandResult{
+				Stdout:   []byte("# Daily Report\n"),
+				Stderr:   []byte("validation failed"),
+				ExitCode: 2,
+			},
+		},
+	}
+
+	result, err := runner.Run(context.Background(), RunRequest{
+		PromptID:        "weather.daily_report",
+		DataPackagePath: "/tmp/data_package.json",
+		OutputPath:      "/tmp/daily.md",
+	})
+	if err == nil {
+		t.Fatal("Run() error = nil, want nonzero exit error")
+	}
+	if result == nil {
+		t.Fatal("Run() result = nil, want captured result")
+	}
+	if result.ExitCode != 2 {
+		t.Fatalf("ExitCode = %d, want 2", result.ExitCode)
+	}
+	if !strings.Contains(err.Error(), "validation failed") {
+		t.Fatalf("error = %q, want stderr context", err.Error())
+	}
+}
+
+type fakeCommands struct {
+	name    string
+	args    []string
+	timeout time.Duration
+	result  CommandResult
+	err     error
+}
+
+func (f *fakeCommands) Run(_ context.Context, name string, args []string, timeout time.Duration) (CommandResult, error) {
+	f.name = name
+	f.args = append([]string{}, args...)
+	f.timeout = timeout
+	return f.result, f.err
+}

internal/adapters/weatherapi/client.go

@@ -0,0 +1,438 @@
+// Package weatherapi adapts the internal weather API to forecast bundles.
+package weatherapi
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"path"
+	"strconv"
+	"strings"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/fileutil"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+)
+
+type Client struct {
+	baseURL       *url.URL
+	httpClient    *http.Client
+	units         string
+	format        string
+	timezone      string
+	precision     int
+	missingSource config.MissingSourceConfig
+	now           func() time.Time
+}
+
+type Option func(*Client)
+
+func WithHTTPClient(httpClient *http.Client) Option {
+	return func(c *Client) {
+		if httpClient != nil {
+			c.httpClient = httpClient
+		}
+	}
+}
+
+func WithClock(now func() time.Time) Option {
+	return func(c *Client) {
+		if now != nil {
+			c.now = now
+		}
+	}
+}
+
+func New(cfg config.Config, opts ...Option) (*Client, error) {
+	if strings.TrimSpace(cfg.WeatherAPI.BaseURL) == "" {
+		return nil, fmt.Errorf("weather_api.base_url is required")
+	}
+	baseURL, err := url.Parse(cfg.WeatherAPI.BaseURL)
+	if err != nil || baseURL.Scheme == "" || baseURL.Host == "" {
+		return nil, fmt.Errorf("weather_api.base_url must be an absolute URL")
+	}
+
+	timeout := cfg.WeatherAPI.Timeout
+	if timeout <= 0 {
+		timeout = 10 * time.Second
+	}
+
+	client := &Client{
+		baseURL:    baseURL,
+		httpClient: &http.Client{Timeout: timeout},
+		units:      cfg.WeatherAPI.Units,
+		format:     cfg.WeatherAPI.Format,
+		timezone:   cfg.WeatherAPI.Timezone,
+		precision:  cfg.WeatherAPI.Precision,
+		missingSource: config.MissingSourceConfig{
+			Default: cfg.MissingSource.Default,
+			Sources: cfg.MissingSource.Sources,
+		},
+		now: time.Now,
+	}
+	for _, opt := range opts {
+		opt(client)
+	}
+	return client, nil
+}
+
+func (c *Client) FetchBundle(ctx context.Context) (*forecast.Bundle, error) {
+	fetchedAt := c.now()
+	builder := bundleBuilder{
+		client:    c,
+		bundle:    &forecast.Bundle{FetchedAt: fetchedAt},
+		fetchedAt: fetchedAt,
+	}
+
+	if err := builder.fetchObservation(ctx); err != nil {
+		return nil, err
+	}
+	if err := builder.fetchCurrent(ctx); err != nil {
+		return nil, err
+	}
+	if err := builder.fetchHourly(ctx); err != nil {
+		return nil, err
+	}
+	if err := builder.fetchNarrative(ctx); err != nil {
+		return nil, err
+	}
+	if err := builder.fetchAlerts(ctx); err != nil {
+		return nil, err
+	}
+	if err := builder.fetchDiscussion(ctx); err != nil {
+		return nil, err
+	}
+	if err := builder.fetchWeatherStory(ctx); err != nil {
+		return nil, err
+	}
+	if err := builder.addStub("daily", "daily forecast data is not available from the weather API yet"); err != nil {
+		return nil, err
+	}
+
+	return builder.bundle, nil
+}
+
+type bundleBuilder struct {
+	client    *Client
+	bundle    *forecast.Bundle
+	fetchedAt time.Time
+}
+
+func (b *bundleBuilder) fetchObservation(ctx context.Context) error {
+	raw, source, err := b.client.fetch(ctx, "observations", "/observations", queryOptions{precision: true})
+	if err != nil {
+		return err
+	}
+	if raw == nil {
+		return b.handleMissing(&source, "observation data is missing", false)
+	}
+	var observation forecast.Observation
+	if err := decodeSource(raw, &observation); err != nil {
+		return b.handleMalformed(&source, err, false)
+	}
+	source.IssuedAt = &observation.Timestamp
+	b.bundle.Observation = &observation
+	b.addSource(source)
+	return nil
+}
+
+func (b *bundleBuilder) fetchCurrent(ctx context.Context) error {
+	raw, source, err := b.client.fetch(ctx, "current", "/conditions/current", queryOptions{precision: true})
+	if err != nil {
+		return err
+	}
+	if raw == nil {
+		return b.handleMissing(&source, "current conditions data is missing", false)
+	}
+	var current forecast.Current
+	if err := decodeSource(raw, &current); err != nil {
+		return b.handleMalformed(&source, err, false)
+	}
+	b.bundle.Current = &current
+	b.addSource(source)
+	return nil
+}
+
+func (b *bundleBuilder) fetchHourly(ctx context.Context) error {
+	raw, source, err := b.client.fetch(ctx, "hourly", "/forecast/hourly", queryOptions{precision: true, timezone: true})
+	if err != nil {
+		return err
+	}
+	if raw == nil {
+		return b.handleMissing(&source, "hourly forecast data is missing", true)
+	}
+	var hourly forecast.ForecastRun
+	if err := decodeSource(raw, &hourly); err != nil {
+		return fmt.Errorf("decode hourly forecast from %s: %w", source.Endpoint, err)
+	}
+	if len(hourly.Periods) == 0 {
+		return fmt.Errorf("hourly forecast from %s contains no periods", source.Endpoint)
+	}
+	source.IssuedAt = &hourly.IssuedAt
+	source.UpdatedAt = hourly.UpdatedAt
+	b.bundle.Hourly = &hourly
+	b.addSource(source)
+	return nil
+}
+
+func (b *bundleBuilder) fetchNarrative(ctx context.Context) error {
+	raw, source, err := b.client.fetch(ctx, "narrative", "/forecast/narrative", queryOptions{precision: true, timezone: true})
+	if err != nil {
+		return err
+	}
+	if raw == nil {
+		return b.handleMissing(&source, "narrative forecast data is missing", false)
+	}
+	var narrative forecast.ForecastRun
+	if err := decodeSource(raw, &narrative); err != nil {
+		return b.handleMalformed(&source, err, false)
+	}
+	source.IssuedAt = &narrative.IssuedAt
+	source.UpdatedAt = narrative.UpdatedAt
+	b.bundle.Narrative = &narrative
+	b.addSource(source)
+	return nil
+}
+
+func (b *bundleBuilder) fetchAlerts(ctx context.Context) error {
+	raw, source, err := b.client.fetch(ctx, "alerts", "/alerts/active", queryOptions{allowNull: true})
+	if err != nil {
+		return err
+	}
+	if raw == nil {
+		return b.handleMissing(&source, "active alerts data is missing", false)
+	}
+	if isJSONNull(raw) {
+		b.bundle.Alerts = &forecast.AlertRun{Raw: append(json.RawMessage(nil), raw...)}
+		b.addSource(source)
+		return nil
+	}
+	var alerts forecast.AlertRun
+	if err := decodeSource(raw, &alerts); err != nil {
+		return b.handleMalformed(&source, err, false)
+	}
+	alerts.Raw = append(json.RawMessage(nil), raw...)
+	if alerts.AsOf != nil {
+		source.IssuedAt = alerts.AsOf
+	}
+	b.bundle.Alerts = &alerts
+	b.addSource(source)
+	return nil
+}
+
+func (b *bundleBuilder) fetchDiscussion(ctx context.Context) error {
+	raw, source, err := b.client.fetch(ctx, "discussion", "/discussion", queryOptions{timezone: true})
+	if err != nil {
+		return err
+	}
+	if raw == nil {
+		return b.handleMissing(&source, "forecast discussion data is missing", false)
+	}
+	var discussion forecast.Discussion
+	if err := decodeSource(raw, &discussion); err != nil {
+		return b.handleMalformed(&source, err, false)
+	}
+	source.IssuedAt = &discussion.IssuedAt
+	source.UpdatedAt = discussion.UpdatedAt
+	b.bundle.Discussion = &discussion
+	b.addSource(source)
+	return nil
+}
+
+func (b *bundleBuilder) fetchWeatherStory(ctx context.Context) error {
+	raw, source, err := b.client.fetch(ctx, "weather_story", "/weatherstories/latest", queryOptions{omitUnits: true})
+	if err != nil {
+		return err
+	}
+	if raw == nil {
+		return b.handleMissing(&source, "NWS weather story data is missing", false)
+	}
+	var story forecast.WeatherStory
+	if err := decodeSource(raw, &story); err != nil {
+		return b.handleMalformed(&source, err, false)
+	}
+	if !story.StartTime.IsZero() {
+		source.IssuedAt = &story.StartTime
+	}
+	source.UpdatedAt = story.UpdatedAt
+	b.bundle.WeatherStory = &story
+	b.addSource(source)
+	return nil
+}
+
+func (b *bundleBuilder) addStub(sourceName string, message string) error {
+	source := forecast.Source{
+		Name:      sourceName,
+		FetchedAt: b.fetchedAt,
+		Missing:   true,
+	}
+	return b.applyMissingPolicy(&source, "missing_source", message)
+}
+
+func (b *bundleBuilder) handleMissing(source *forecast.Source, message string, required bool) error {
+	source.Missing = true
+	if required {
+		return fmt.Errorf("%s from %s is required", message, source.Endpoint)
+	}
+	return b.applyMissingPolicy(source, "missing_source", message)
+}
+
+func (b *bundleBuilder) handleMalformed(source *forecast.Source, err error, required bool) error {
+	if required {
+		return fmt.Errorf("decode %s from %s: %w", source.Name, source.Endpoint, err)
+	}
+	source.Missing = true
+	return b.applyMissingPolicy(source, "malformed_source", fmt.Sprintf("malformed %s data: %v", source.Name, err))
+}
+
+func (b *bundleBuilder) applyMissingPolicy(source *forecast.Source, code string, message string) error {
+	policy := b.client.policyFor(source.Name)
+	if policy == config.MissingSourceError {
+		return fmt.Errorf("%s: %s", source.Name, message)
+	}
+	if policy == config.MissingSourceWarn {
+		warning := forecast.SourceWarning{
+			Source:             source.Name,
+			Code:               code,
+			Severity:           "warning",
+			Message:            message,
+			Endpoint:           source.Endpoint,
+			CompletenessImpact: "source omitted from bundle",
+		}
+		source.Warnings = append(source.Warnings, warning)
+		b.bundle.Warnings = append(b.bundle.Warnings, warning)
+	}
+	b.addSource(*source)
+	return nil
+}
+
+func (b *bundleBuilder) addSource(source forecast.Source) {
+	b.bundle.Sources = append(b.bundle.Sources, source)
+}
+
+func (c *Client) policyFor(source string) config.MissingSourcePolicy {
+	if policy, ok := c.missingSource.Sources[source]; ok {
+		return policy
+	}
+	return c.missingSource.Default
+}
+
+type queryOptions struct {
+	precision bool
+	timezone  bool
+	allowNull bool
+	omitUnits bool
+}
+
+type envelope struct {
+	Data json.RawMessage `json:"data"`
+}
+
+func (c *Client) fetch(ctx context.Context, sourceName string, endpoint string, opts queryOptions) (json.RawMessage, forecast.Source, error) {
+	reqURL := c.endpointURL(endpoint, opts)
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, reqURL.String(), nil)
+	if err != nil {
+		return nil, forecast.Source{}, fmt.Errorf("create request for %s: %w", endpoint, err)
+	}
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, forecast.Source{}, fmt.Errorf("fetch %s: %w", endpoint, err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 10<<20))
+	if err != nil {
+		return nil, forecast.Source{}, fmt.Errorf("read %s response: %w", endpoint, err)
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, forecast.Source{}, fmt.Errorf("fetch %s: unexpected HTTP status %d: %s", endpoint, resp.StatusCode, strings.TrimSpace(string(body)))
+	}
+
+	var env envelope
+	if err := json.Unmarshal(body, &env); err != nil {
+		return nil, forecast.Source{}, fmt.Errorf("decode %s envelope: %w", endpoint, err)
+	}
+
+	source := forecast.Source{
+		Name:      sourceName,
+		Endpoint:  endpoint,
+		Query:     queryMap(reqURL.Query()),
+		FetchedAt: c.now(),
+	}
+	if len(env.Data) == 0 || (isJSONNull(env.Data) && !opts.allowNull) {
+		source.Missing = true
+		return nil, source, nil
+	}
+	hash, err := sourceHash(env.Data)
+	if err != nil {
+		return env.Data, source, nil
+	}
+	source.DataSHA256 = hash
+	return env.Data, source, nil
+}
+
+func isJSONNull(raw json.RawMessage) bool {
+	return bytes.Equal(bytes.TrimSpace(raw), []byte("null"))
+}
+
+func (c *Client) endpointURL(endpoint string, opts queryOptions) *url.URL {
+	reqURL := *c.baseURL
+	reqURL.Path = path.Join(c.baseURL.Path, endpoint)
+	query := reqURL.Query()
+	query.Set("format", c.format)
+	if !opts.omitUnits {
+		query.Set("units", c.units)
+	}
+	if opts.precision {
+		query.Set("precision", strconv.Itoa(c.precision))
+	}
+	if opts.timezone {
+		query.Set("tz", c.timezone)
+	}
+	reqURL.RawQuery = query.Encode()
+	return &reqURL
+}
+
+func queryMap(values url.Values) map[string]string {
+	if len(values) == 0 {
+		return nil
+	}
+	out := make(map[string]string, len(values))
+	for key, value := range values {
+		if len(value) > 0 {
+			out[key] = value[0]
+		}
+	}
+	return out
+}
+
+func decodeSource(raw json.RawMessage, target any) error {
+	if err := json.Unmarshal(raw, target); err != nil {
+		return err
+	}
+	return nil
+}
+
+func sourceHash(raw json.RawMessage) (string, error) {
+	var compact bytes.Buffer
+	if err := json.Compact(&compact, raw); err != nil {
+		return "", err
+	}
+	sum := sha256.Sum256(compact.Bytes())
+	return hex.EncodeToString(sum[:]), nil
+}
+
+func SaveBundle(path string, bundle *forecast.Bundle) error {
+	if err := fileutil.WriteJSONAtomic(path, bundle); err != nil {
+		return fmt.Errorf("save bundle: %w", err)
+	}
+	return nil
+}

internal/adapters/weatherapi/client_test.go

@@ -0,0 +1,452 @@
+package weatherapi
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+)
+
+func TestFetchBundleFromFixtures(t *testing.T) {
+	var requested []string
+	server := fixtureServer(t, nil, &requested)
+	client := newTestClient(t, server.URL+"/", nil)
+
+	bundle, err := client.FetchBundle(context.Background())
+	if err != nil {
+		t.Fatalf("FetchBundle() error = %v", err)
+	}
+
+	if bundle.Observation == nil || bundle.Observation.StationID != "KSTL" {
+		t.Fatalf("Observation = %#v, want KSTL observation", bundle.Observation)
+	}
+	if bundle.Current == nil || bundle.Current.ConditionText != "Partly cloudy" {
+		t.Fatalf("Current = %#v, want current conditions", bundle.Current)
+	}
+	if bundle.Hourly == nil || len(bundle.Hourly.Periods) != 1 {
+		t.Fatalf("Hourly = %#v, want one hourly period", bundle.Hourly)
+	}
+	if bundle.Narrative == nil || bundle.Narrative.Product != "narrative" {
+		t.Fatalf("Narrative = %#v, want narrative product", bundle.Narrative)
+	}
+	if bundle.Alerts == nil || bundle.Alerts.AsOf == nil {
+		t.Fatalf("Alerts = %#v, want alert run", bundle.Alerts)
+	}
+	if bundle.Discussion == nil || len(bundle.Discussion.KeyMessages) != 2 {
+		t.Fatalf("Discussion = %#v, want key messages", bundle.Discussion)
+	}
+	if bundle.Discussion.ShortTerm == nil || bundle.Discussion.ShortTerm.Text != "A weak boundary may trigger isolated showers." {
+		t.Fatalf("Discussion.ShortTerm = %#v, want short-term AFD text", bundle.Discussion.ShortTerm)
+	}
+	if bundle.Discussion.LongTerm == nil || bundle.Discussion.LongTerm.Text != "Warmer temperatures and periodic rain chances continue into the weekend." {
+		t.Fatalf("Discussion.LongTerm = %#v, want long-term AFD text", bundle.Discussion.LongTerm)
+	}
+	if bundle.WeatherStory == nil || bundle.WeatherStory.Title != "Several Chances for Rain Through Monday" {
+		t.Fatalf("WeatherStory = %#v, want latest weather story", bundle.WeatherStory)
+	}
+	if bundle.WeatherStory.UpdatedAt == nil {
+		t.Fatalf("WeatherStory.UpdatedAt = nil, want update timestamp")
+	}
+	if len(bundle.Sources) != 8 {
+		t.Fatalf("Sources length = %d, want 8", len(bundle.Sources))
+	}
+	if len(bundle.Warnings) != 1 {
+		t.Fatalf("Warnings length = %d, want daily warning", len(bundle.Warnings))
+	}
+	if !containsPath(requested, "/forecast/hourly") || containsPath(requested, "/forecast/hourly/today") {
+		t.Fatalf("requested paths = %v, want full hourly endpoint only", requested)
+	}
+	if !containsPath(requested, "/forecast/narrative") || containsPath(requested, "/forecast/narrative/today") {
+		t.Fatalf("requested paths = %v, want full narrative endpoint only", requested)
+	}
+	if !containsPath(requested, "/weatherstories/latest") {
+		t.Fatalf("requested paths = %v, want weather story endpoint", requested)
+	}
+}
+
+func TestFetchBundleBuildsExpectedQueries(t *testing.T) {
+	var requested []string
+	server := fixtureServer(t, nil, &requested)
+	client := newTestClient(t, server.URL+"/", nil)
+
+	_, err := client.FetchBundle(context.Background())
+	if err != nil {
+		t.Fatalf("FetchBundle() error = %v", err)
+	}
+
+	for _, rawURL := range requested {
+		if !strings.Contains(rawURL, "format=json") {
+			t.Fatalf("request %q missing format=json", rawURL)
+		}
+		if strings.HasPrefix(rawURL, "/weatherstories/") {
+			if strings.Contains(rawURL, "units=") || strings.Contains(rawURL, "precision=") || strings.Contains(rawURL, "tz=") {
+				t.Fatalf("weather story request %q should use format only", rawURL)
+			}
+			continue
+		}
+		if !strings.Contains(rawURL, "units=us") {
+			t.Fatalf("request %q missing units=us", rawURL)
+		}
+		if strings.HasPrefix(rawURL, "/forecast/") {
+			if !strings.Contains(rawURL, "precision=1") || !strings.Contains(rawURL, "tz=America%2FChicago") {
+				t.Fatalf("forecast request %q missing precision or tz", rawURL)
+			}
+		}
+	}
+}
+
+func TestFetchBundleRecordsSourceHash(t *testing.T) {
+	server := fixtureServer(t, nil, nil)
+	client := newTestClient(t, server.URL+"/", nil)
+
+	bundle, err := client.FetchBundle(context.Background())
+	if err != nil {
+		t.Fatalf("FetchBundle() error = %v", err)
+	}
+
+	observation := sourceByName(t, bundle.Sources, "observations")
+	want := hashFixtureData(t, "observations.json")
+	if observation.DataSHA256 != want {
+		t.Fatalf("DataSHA256 = %q, want %q", observation.DataSHA256, want)
+	}
+	story := sourceByName(t, bundle.Sources, "weather_story")
+	if story.Endpoint != "/weatherstories/latest" {
+		t.Fatalf("weather story endpoint = %q, want /weatherstories/latest", story.Endpoint)
+	}
+	if story.DataSHA256 != hashFixtureData(t, "weather_story.json") {
+		t.Fatalf("weather story DataSHA256 = %q, want fixture hash", story.DataSHA256)
+	}
+	if story.IssuedAt == nil || story.UpdatedAt == nil {
+		t.Fatalf("weather story source timestamps = issued %#v updated %#v, want both", story.IssuedAt, story.UpdatedAt)
+	}
+}
+
+func TestHTTPErrorIsActionable(t *testing.T) {
+	server := fixtureServer(t, map[string]handlerOverride{
+		"/conditions/current": {status: http.StatusBadGateway, body: `upstream failed`},
+	}, nil)
+	client := newTestClient(t, server.URL+"/", nil)
+
+	_, err := client.FetchBundle(context.Background())
+	if err == nil {
+		t.Fatal("FetchBundle() error = nil, want HTTP error")
+	}
+	if !strings.Contains(err.Error(), "/conditions/current") || !strings.Contains(err.Error(), "502") {
+		t.Fatalf("error = %q, want endpoint and status", err.Error())
+	}
+}
+
+func TestRequiredHourlyForecast(t *testing.T) {
+	server := fixtureServer(t, map[string]handlerOverride{
+		"/forecast/hourly": {status: http.StatusOK, body: `{"data": null}`},
+	}, nil)
+	client := newTestClient(t, server.URL+"/", nil)
+
+	_, err := client.FetchBundle(context.Background())
+	if err == nil {
+		t.Fatal("FetchBundle() error = nil, want required hourly error")
+	}
+	if !strings.Contains(err.Error(), "hourly forecast data") {
+		t.Fatalf("error = %q, want hourly context", err.Error())
+	}
+}
+
+func TestNullAlertsMeansNoActiveAlerts(t *testing.T) {
+	server := fixtureServer(t, map[string]handlerOverride{
+		"/alerts/active": {status: http.StatusOK, body: `{"data": null}`},
+	}, nil)
+	client := newTestClient(t, server.URL+"/", nil)
+
+	bundle, err := client.FetchBundle(context.Background())
+	if err != nil {
+		t.Fatalf("FetchBundle() error = %v", err)
+	}
+	if bundle.Alerts == nil {
+		t.Fatal("Alerts = nil, want checked empty alert run")
+	}
+	if len(bundle.Alerts.Alerts) != 0 {
+		t.Fatalf("Alerts length = %d, want no active alerts", len(bundle.Alerts.Alerts))
+	}
+	source := sourceByName(t, bundle.Sources, "alerts")
+	if source.Missing {
+		t.Fatalf("alerts source Missing = true, want false")
+	}
+	if source.DataSHA256 == "" {
+		t.Fatal("alerts DataSHA256 is empty, want hash for explicit null payload")
+	}
+	for _, warning := range bundle.Warnings {
+		if warning.Source == "alerts" {
+			t.Fatalf("warnings = %#v, want no alerts warning", bundle.Warnings)
+		}
+	}
+}
+
+func TestMissingSourcePolicyWarnNoneError(t *testing.T) {
+	tests := []struct {
+		name       string
+		policy     config.MissingSourcePolicy
+		wantErr    bool
+		wantWarns  int
+		wantSource bool
+	}{
+		{name: "warn", policy: config.MissingSourceWarn, wantWarns: 2, wantSource: true},
+		{name: "none", policy: config.MissingSourceNone, wantWarns: 0, wantSource: true},
+		{name: "error", policy: config.MissingSourceError, wantErr: true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			server := fixtureServer(t, map[string]handlerOverride{
+				"/observations": {status: http.StatusOK, body: `{"data": null}`},
+			}, nil)
+			cfg := testConfig(server.URL + "/")
+			cfg.MissingSource.Default = tt.policy
+			cfg.MissingSource.Sources = map[string]config.MissingSourcePolicy{
+				"hourly": tt.policy,
+			}
+			client, err := New(cfg, WithClock(fixedNow))
+			if err != nil {
+				t.Fatalf("New() error = %v", err)
+			}
+
+			bundle, err := client.FetchBundle(context.Background())
+			if tt.wantErr {
+				if err == nil {
+					t.Fatal("FetchBundle() error = nil, want policy error")
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("FetchBundle() error = %v", err)
+			}
+			if len(bundle.Warnings) != tt.wantWarns {
+				t.Fatalf("Warnings length = %d, want %d", len(bundle.Warnings), tt.wantWarns)
+			}
+			if tt.wantSource {
+				source := sourceByName(t, bundle.Sources, "observations")
+				if !source.Missing {
+					t.Fatalf("observations source Missing = false, want true")
+				}
+			}
+		})
+	}
+}
+
+func TestMalformedNonRequiredSourceUsesPolicy(t *testing.T) {
+	server := fixtureServer(t, map[string]handlerOverride{
+		"/conditions/current": {status: http.StatusOK, body: `{"data": {"temperatureF": "hot"}}`},
+	}, nil)
+	client := newTestClient(t, server.URL+"/", map[string]config.MissingSourcePolicy{
+		"current": config.MissingSourceWarn,
+	})
+
+	bundle, err := client.FetchBundle(context.Background())
+	if err != nil {
+		t.Fatalf("FetchBundle() error = %v", err)
+	}
+	source := sourceByName(t, bundle.Sources, "current")
+	if !source.Missing || len(source.Warnings) != 1 {
+		t.Fatalf("current source = %#v, want missing source warning", source)
+	}
+}
+
+func TestMissingWeatherStoryUsesPolicy(t *testing.T) {
+	server := fixtureServer(t, map[string]handlerOverride{
+		"/weatherstories/latest": {status: http.StatusOK, body: `{"data": null}`},
+	}, nil)
+	client := newTestClient(t, server.URL+"/", map[string]config.MissingSourcePolicy{
+		"weather_story": config.MissingSourceWarn,
+	})
+
+	bundle, err := client.FetchBundle(context.Background())
+	if err != nil {
+		t.Fatalf("FetchBundle() error = %v", err)
+	}
+	if bundle.WeatherStory != nil {
+		t.Fatalf("WeatherStory = %#v, want nil for missing source", bundle.WeatherStory)
+	}
+	source := sourceByName(t, bundle.Sources, "weather_story")
+	if !source.Missing || len(source.Warnings) != 1 {
+		t.Fatalf("weather_story source = %#v, want missing source warning", source)
+	}
+}
+
+func TestMalformedWeatherStoryUsesPolicy(t *testing.T) {
+	server := fixtureServer(t, map[string]handlerOverride{
+		"/weatherstories/latest": {status: http.StatusOK, body: `{"data": {"startTime": 123}}`},
+	}, nil)
+	client := newTestClient(t, server.URL+"/", map[string]config.MissingSourcePolicy{
+		"weather_story": config.MissingSourceWarn,
+	})
+
+	bundle, err := client.FetchBundle(context.Background())
+	if err != nil {
+		t.Fatalf("FetchBundle() error = %v", err)
+	}
+	source := sourceByName(t, bundle.Sources, "weather_story")
+	if !source.Missing || len(source.Warnings) != 1 || source.Warnings[0].Code != "malformed_source" {
+		t.Fatalf("weather_story source = %#v, want malformed source warning", source)
+	}
+}
+
+func TestContextCancellation(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		<-r.Context().Done()
+	}))
+	defer server.Close()
+	client := newTestClient(t, server.URL+"/", nil)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	_, err := client.FetchBundle(ctx)
+	if err == nil {
+		t.Fatal("FetchBundle() error = nil, want cancellation error")
+	}
+}
+
+func TestHTTPTimeout(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(50 * time.Millisecond)
+	}))
+	defer server.Close()
+
+	cfg := testConfig(server.URL + "/")
+	cfg.WeatherAPI.Timeout = time.Nanosecond
+	client, err := New(cfg, WithClock(fixedNow))
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+
+	_, err = client.FetchBundle(context.Background())
+	if err == nil {
+		t.Fatal("FetchBundle() error = nil, want timeout error")
+	}
+	if !strings.Contains(err.Error(), "/observations") {
+		t.Fatalf("error = %q, want endpoint context", err.Error())
+	}
+}
+
+func TestSaveBundle(t *testing.T) {
+	server := fixtureServer(t, nil, nil)
+	client := newTestClient(t, server.URL+"/", nil)
+	bundle, err := client.FetchBundle(context.Background())
+	if err != nil {
+		t.Fatalf("FetchBundle() error = %v", err)
+	}
+
+	path := filepath.Join(t.TempDir(), "nested", "bundle.json")
+	if err := SaveBundle(path, bundle); err != nil {
+		t.Fatalf("SaveBundle() error = %v", err)
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read saved bundle: %v", err)
+	}
+	if !strings.Contains(string(data), `"hourly"`) {
+		t.Fatalf("saved bundle missing hourly source:\n%s", string(data))
+	}
+}
+
+type handlerOverride struct {
+	status int
+	body   string
+}
+
+func fixtureServer(t *testing.T, overrides map[string]handlerOverride, requested *[]string) *httptest.Server {
+	t.Helper()
+	fixtures := map[string]string{
+		"/observations":          "observations.json",
+		"/conditions/current":    "current.json",
+		"/forecast/hourly":       "hourly.json",
+		"/forecast/narrative":    "narrative.json",
+		"/alerts/active":         "alerts.json",
+		"/discussion":            "discussion.json",
+		"/weatherstories/latest": "weather_story.json",
+	}
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if requested != nil {
+			*requested = append(*requested, r.URL.String())
+		}
+		if override, ok := overrides[r.URL.Path]; ok {
+			w.WriteHeader(override.status)
+			_, _ = w.Write([]byte(override.body))
+			return
+		}
+		name, ok := fixtures[r.URL.Path]
+		if !ok {
+			http.NotFound(w, r)
+			return
+		}
+		http.ServeFile(w, r, filepath.Join("testdata", name))
+	}))
+	t.Cleanup(server.Close)
+	return server
+}
+
+func newTestClient(t *testing.T, baseURL string, sourcePolicies map[string]config.MissingSourcePolicy) *Client {
+	t.Helper()
+	cfg := testConfig(baseURL)
+	for source, policy := range sourcePolicies {
+		cfg.MissingSource.Sources[source] = policy
+	}
+	client, err := New(cfg, WithClock(fixedNow))
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	return client
+}
+
+func testConfig(baseURL string) config.Config {
+	cfg := config.Defaults()
+	cfg.WeatherAPI.BaseURL = baseURL
+	return cfg
+}
+
+func fixedNow() time.Time {
+	return time.Date(2026, 5, 29, 15, 0, 0, 0, time.UTC)
+}
+
+func containsPath(requested []string, path string) bool {
+	for _, rawURL := range requested {
+		if strings.HasPrefix(rawURL, path+"?") || rawURL == path {
+			return true
+		}
+	}
+	return false
+}
+
+func sourceByName(t *testing.T, sources []forecast.Source, name string) forecast.Source {
+	t.Helper()
+	for _, source := range sources {
+		if source.Name == name {
+			return source
+		}
+	}
+	t.Fatalf("source %q not found in %#v", name, sources)
+	return forecast.Source{}
+}
+
+func hashFixtureData(t *testing.T, fixture string) string {
+	t.Helper()
+	data, err := os.ReadFile(filepath.Join("testdata", fixture))
+	if err != nil {
+		t.Fatalf("read fixture: %v", err)
+	}
+	var env envelope
+	if err := json.Unmarshal(data, &env); err != nil {
+		t.Fatalf("decode fixture envelope: %v", err)
+	}
+	hash, err := sourceHash(env.Data)
+	if err != nil {
+		t.Fatalf("hash fixture data: %v", err)
+	}
+	return hash
+}

internal/adapters/weatherapi/testdata/alerts.json

@@ -0,0 +1,6 @@
+{
+  "data": {
+    "asOf": "2026-05-29T14:00:00Z",
+    "alerts": []
+  }
+}

internal/adapters/weatherapi/testdata/current.json

@@ -0,0 +1,10 @@
+{
+  "data": {
+    "conditionText": "Partly cloudy",
+    "isDay": true,
+    "temperatureF": 75.9,
+    "apparentTemperatureF": 76.1,
+    "windSpeedMph": 10.7,
+    "relativeHumidityPercent": 56
+  }
+}

internal/adapters/weatherapi/testdata/discussion.json

@@ -0,0 +1,20 @@
+{
+  "data": {
+    "officeId": "LSX",
+    "officeName": "St. Louis",
+    "product": "discussion",
+    "issuedAt": "2026-05-29T09:25:00-05:00",
+    "keyMessages": [
+      "Scattered showers possible this evening.",
+      "Warmer temperatures this weekend."
+    ],
+    "shortTerm": {
+      "qualifier": "(Through This Evening)",
+      "text": "A weak boundary may trigger isolated showers."
+    },
+    "longTerm": {
+      "qualifier": "(This Weekend)",
+      "text": "Warmer temperatures and periodic rain chances continue into the weekend."
+    }
+  }
+}

internal/adapters/weatherapi/testdata/hourly.json

@@ -0,0 +1,25 @@
+{
+  "data": {
+    "locationId": "nws-lsx-grid-90-74",
+    "locationName": "St. Louis, MO",
+    "issuedAt": "2026-05-29T10:30:00-05:00",
+    "updatedAt": "2026-05-29T10:45:00-05:00",
+    "product": "hourly",
+    "latitude": 38.63,
+    "longitude": -90.2,
+    "elevationFeet": 466,
+    "periods": [
+      {
+        "startTime": "2026-05-29T13:00:00-05:00",
+        "endTime": "2026-05-29T14:00:00-05:00",
+        "isDay": true,
+        "conditionCode": 3,
+        "textDescription": "Partly sunny",
+        "temperatureF": 81,
+        "windSpeedMph": 12,
+        "windGustMph": 20,
+        "probabilityOfPrecipitationPercent": 10
+      }
+    ]
+  }
+}

internal/adapters/weatherapi/testdata/narrative.json

@@ -0,0 +1,20 @@
+{
+  "data": {
+    "locationId": "nws-lsx-grid-90-74",
+    "locationName": "St. Louis, MO",
+    "issuedAt": "2026-05-29T10:30:00-05:00",
+    "product": "narrative",
+    "periods": [
+      {
+        "startTime": "2026-05-29T13:00:00-05:00",
+        "endTime": "2026-05-29T19:00:00-05:00",
+        "name": "Today",
+        "isDay": true,
+        "textDescription": "Partly sunny, with a high near 81.",
+        "temperatureF": 81,
+        "windSpeedMph": 12,
+        "probabilityOfPrecipitationPercent": 10
+      }
+    ]
+  }
+}

internal/adapters/weatherapi/testdata/observations.json

@@ -0,0 +1,13 @@
+{
+  "data": {
+    "stationId": "KSTL",
+    "stationName": "St. Louis",
+    "timestamp": "2026-05-29T14:00:00Z",
+    "conditionCode": 3,
+    "isDay": true,
+    "textDescription": "Partly cloudy",
+    "temperatureF": 75.9,
+    "windSpeedMph": 10.7,
+    "relativeHumidityPercent": 56
+  }
+}

internal/adapters/weatherapi/testdata/weather_story.json

@@ -0,0 +1,14 @@
+{
+  "data": {
+    "officeId": "LSX",
+    "startTime": "2026-05-30T08:46:00Z",
+    "endTime": "2026-05-31T11:00:00Z",
+    "updatedAt": "2026-05-30T09:00:34Z",
+    "title": "Several Chances for Rain Through Monday",
+    "description": "A stagnant weather pattern with low pressure over the Great Plains and high pressure over the Great Lakes will continue to produce scattered showers and thunderstorms, for areas mainly along and west of the Mississippi River today and Sunday.",
+    "altText": "This slide shows the forecast for today through Tuesday with icons for showers and thunderstorms and a picture of a cumulonimbus cloud on the right side.",
+    "priority": false,
+    "order": 1,
+    "downloadUrl": "https://api.weather.gov/offices/LSX/weatherstories/download/3228e499-2aae-45a8-9ff9-1c060311026f"
+  }
+}

internal/app/app.go

@@ -0,0 +1,616 @@
+// Package app owns application orchestration and top-level use cases.
+package app
+
+import (
+	"context"
+	"fmt"
+	"path/filepath"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/adapters/scriptorium"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/adapters/weatherapi"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/changes"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/fileutil"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptinput"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/state"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+type ReportKind string
+
+const (
+	ReportDaily    ReportKind = "daily"
+	ReportTomorrow ReportKind = "tomorrow"
+	ReportThreeDay ReportKind = "three-day"
+	ReportWeekend  ReportKind = "weekend"
+	ReportStorm    ReportKind = "storm"
+)
+
+type BatchKind string
+
+const (
+	BatchMorning BatchKind = "morning"
+	BatchEvening BatchKind = "evening"
+)
+
+type GenerateRequest struct {
+	Config     config.Config
+	Report     ReportKind
+	OutputPath string
+	Now        time.Time
+	Date       time.Time
+	StormStart time.Time
+	StormEnd   time.Time
+}
+
+type BatchRequest struct {
+	Config    config.Config
+	Batch     BatchKind
+	Now       time.Time
+	OutputDir string
+	Renderer  Renderer
+	Store     state.Store
+}
+
+type FetchBundleRequest struct {
+	Config     config.Config
+	OutputPath string
+}
+
+type BriefingRequest struct {
+	Config     config.Config
+	Resolved   report.Resolved
+	OutputPath string
+}
+
+type ReportRequest struct {
+	Config     config.Config
+	Resolved   report.Resolved
+	OutputPath string
+	Renderer   Renderer
+	Store      state.Store
+}
+
+type BriefingResult struct {
+	Package    briefing.Package
+	OutputPath string
+}
+
+type ReportResult struct {
+	Briefing        briefing.Package
+	BriefingPath    string
+	DataPackage     promptinput.Package
+	DataPackagePath string
+	PreflightPath   string
+	ReportPath      string
+	OutputPath      string
+	Metadata        state.Metadata
+	MetadataPath    string
+	PriorSnapshot   *state.PriorSnapshot
+	RecentChanges   []changes.Change
+	RenderResult    *scriptorium.RenderResult
+	RunResult       *scriptorium.RunResult
+}
+
+type BatchResult struct {
+	Batch      BatchKind           `json:"batch"`
+	StartedAt  time.Time           `json:"startedAt"`
+	FinishedAt time.Time           `json:"finishedAt"`
+	Total      int                 `json:"total"`
+	Succeeded  int                 `json:"succeeded"`
+	Failed     int                 `json:"failed"`
+	Reports    []BatchReportResult `json:"reports"`
+}
+
+type BatchReportResult struct {
+	ReportID        report.ID       `json:"reportId"`
+	ReportName      string          `json:"reportName"`
+	PromptID        string          `json:"promptId"`
+	RunID           string          `json:"runId"`
+	Status          string          `json:"status"`
+	Error           string          `json:"error,omitempty"`
+	GeneratedAt     time.Time       `json:"generatedAt"`
+	ValidPeriod     timeutil.Period `json:"validPeriod"`
+	BriefingPath    string          `json:"briefingPath,omitempty"`
+	DataPackagePath string          `json:"dataPackagePath,omitempty"`
+	PreflightPath   string          `json:"preflightPath,omitempty"`
+	ReportPath      string          `json:"reportPath,omitempty"`
+	OutputPath      string          `json:"outputPath,omitempty"`
+	MetadataPath    string          `json:"metadataPath,omitempty"`
+}
+
+type BatchError struct {
+	Result *BatchResult
+}
+
+func (e BatchError) Error() string {
+	if e.Result == nil {
+		return "batch failed"
+	}
+	return fmt.Sprintf("batch %s failed: %d of %d reports failed", e.Result.Batch, e.Result.Failed, e.Result.Total)
+}
+
+type Renderer interface {
+	Render(context.Context, scriptorium.RenderRequest) (*scriptorium.RenderResult, error)
+	Run(context.Context, scriptorium.RunRequest) (*scriptorium.RunResult, error)
+}
+
+func Generate(ctx context.Context, req GenerateRequest) error {
+	now := req.Now
+	if now.IsZero() {
+		now = time.Now()
+	}
+	resolved, err := ResolveGenerate(req, now)
+	if err != nil {
+		return err
+	}
+	if resolved.Definition.Generated {
+		_, err := GenerateReport(ctx, ReportRequest{
+			Config:     req.Config,
+			Resolved:   resolved,
+			OutputPath: req.OutputPath,
+		})
+		return err
+	}
+	return fmt.Errorf("generate is not implemented")
+}
+
+func RunBatch(ctx context.Context, req BatchRequest) error {
+	result, err := RunBatchDetailed(ctx, req)
+	if err != nil {
+		return err
+	}
+	if result.Failed > 0 {
+		return BatchError{Result: result}
+	}
+	return nil
+}
+
+func RunBatchDetailed(ctx context.Context, req BatchRequest) (*BatchResult, error) {
+	now := req.Now
+	if now.IsZero() {
+		now = time.Now()
+	}
+	resolvedReports, err := ResolveBatch(req, now)
+	if err != nil {
+		return nil, err
+	}
+	if req.Batch == BatchEvening || req.Batch == BatchMorning {
+		store := req.Store
+		if store == nil {
+			defaultStore, err := defaultStore(req.Config)
+			if err != nil {
+				return nil, err
+			}
+			store = defaultStore
+		}
+		startedAt := now
+		result := &BatchResult{Batch: req.Batch, StartedAt: startedAt}
+		for _, resolved := range resolvedReports {
+			if !resolved.Definition.Generated {
+				return nil, fmt.Errorf("run is not implemented")
+			}
+		}
+		for _, resolved := range resolvedReports {
+			item := batchReportResult(resolved)
+			if paths, err := store.Paths(resolved); err == nil {
+				item.BriefingPath = paths.Briefing
+				item.DataPackagePath = paths.DataPackage
+				item.PreflightPath = paths.Preflight
+				item.ReportPath = paths.RenderedReport
+				item.MetadataPath = paths.Metadata
+			}
+			outputPath := batchOutputPath(req.OutputDir, resolved.Definition)
+			reportResult, err := GenerateReport(ctx, ReportRequest{
+				Config:     req.Config,
+				Resolved:   resolved,
+				OutputPath: outputPath,
+				Renderer:   req.Renderer,
+				Store:      store,
+			})
+			if err != nil {
+				item.Status = "failed"
+				item.Error = err.Error()
+				result.Failed++
+			} else {
+				item.Status = "succeeded"
+				item.BriefingPath = reportResult.BriefingPath
+				item.DataPackagePath = reportResult.DataPackagePath
+				item.PreflightPath = reportResult.PreflightPath
+				item.ReportPath = reportResult.ReportPath
+				item.OutputPath = reportResult.OutputPath
+				item.MetadataPath = reportResult.MetadataPath
+				result.Succeeded++
+			}
+			result.Reports = append(result.Reports, item)
+		}
+		result.Total = len(result.Reports)
+		result.FinishedAt = time.Now()
+		return result, nil
+	}
+	return nil, fmt.Errorf("run is not implemented")
+}
+
+func batchReportResult(resolved report.Resolved) BatchReportResult {
+	metadata := resolved.Metadata()
+	return BatchReportResult{
+		ReportID:    resolved.Definition.ID,
+		ReportName:  resolved.Definition.Name,
+		PromptID:    resolved.Definition.PromptID,
+		RunID:       metadata.RunID,
+		GeneratedAt: metadata.GeneratedAt,
+		ValidPeriod: metadata.ValidPeriod,
+	}
+}
+
+func batchOutputPath(outputDir string, definition report.Definition) string {
+	if outputDir == "" || definition.BatchOutputName == "" {
+		return ""
+	}
+	return filepath.Join(outputDir, definition.BatchOutputName)
+}
+
+func ResolveGenerate(req GenerateRequest, now time.Time) (report.Resolved, error) {
+	location, err := timeutil.LoadLocation(req.Config.WeatherAPI.Timezone)
+	if err != nil {
+		return report.Resolved{}, err
+	}
+	id, err := reportIDForCommand(req.Report)
+	if err != nil {
+		return report.Resolved{}, err
+	}
+	return report.DefaultRegistry().Resolve(id, report.ResolveRequest{
+		Now:        now,
+		Location:   location,
+		Date:       req.Date,
+		StormStart: req.StormStart,
+		StormEnd:   req.StormEnd,
+	})
+}
+
+func ResolveBatch(req BatchRequest, now time.Time) ([]report.Resolved, error) {
+	location, err := timeutil.LoadLocation(req.Config.WeatherAPI.Timezone)
+	if err != nil {
+		return nil, err
+	}
+	batch, err := reportBatchForCommand(req.Batch)
+	if err != nil {
+		return nil, err
+	}
+	return report.DefaultRegistry().BatchReports(batch, report.ResolveRequest{
+		Now:      now,
+		Location: location,
+	})
+}
+
+func reportIDForCommand(kind ReportKind) (report.ID, error) {
+	switch kind {
+	case ReportDaily:
+		return report.DailyToday, nil
+	case ReportTomorrow:
+		return report.DailyTomorrow, nil
+	case ReportThreeDay:
+		return report.ThreeDay, nil
+	case ReportWeekend:
+		return report.Weekend, nil
+	case ReportStorm:
+		return report.Storm, nil
+	default:
+		return "", fmt.Errorf("unknown report command %q", kind)
+	}
+}
+
+func reportBatchForCommand(kind BatchKind) (report.Batch, error) {
+	switch kind {
+	case BatchMorning:
+		return report.Morning, nil
+	case BatchEvening:
+		return report.Evening, nil
+	default:
+		return "", fmt.Errorf("unknown batch command %q", kind)
+	}
+}
+
+func FetchBundle(ctx context.Context, req FetchBundleRequest) (*forecast.Bundle, error) {
+	client, err := weatherapi.New(req.Config)
+	if err != nil {
+		return nil, err
+	}
+	bundle, err := client.FetchBundle(ctx)
+	if err != nil {
+		return nil, err
+	}
+	return bundle, nil
+}
+
+func FetchAndSaveBundle(ctx context.Context, req FetchBundleRequest) (*forecast.Bundle, error) {
+	if req.OutputPath == "" {
+		return nil, fmt.Errorf("output path is required")
+	}
+	bundle, err := FetchBundle(ctx, req)
+	if err != nil {
+		return nil, err
+	}
+	if err := weatherapi.SaveBundle(req.OutputPath, bundle); err != nil {
+		return nil, err
+	}
+	return bundle, nil
+}
+
+func GenerateBriefing(ctx context.Context, req BriefingRequest) (*BriefingResult, error) {
+	bundle, err := FetchBundle(ctx, FetchBundleRequest{Config: req.Config})
+	if err != nil {
+		return nil, err
+	}
+	pkg, err := BuildBriefing(req, bundle)
+	if err != nil {
+		return nil, err
+	}
+	outputPath := req.OutputPath
+	if outputPath == "" {
+		store, err := defaultStore(req.Config)
+		if err != nil {
+			return nil, err
+		}
+		paths, err := store.Paths(req.Resolved)
+		if err != nil {
+			return nil, err
+		}
+		outputPath = paths.Briefing
+	}
+	if err := briefing.Save(outputPath, pkg); err != nil {
+		return nil, err
+	}
+	return &BriefingResult{Package: pkg, OutputPath: outputPath}, nil
+}
+
+func GenerateReport(ctx context.Context, req ReportRequest) (*ReportResult, error) {
+	store := req.Store
+	if store == nil {
+		defaultStore, err := defaultStore(req.Config)
+		if err != nil {
+			return nil, err
+		}
+		store = defaultStore
+	}
+	paths, err := store.Paths(req.Resolved)
+	if err != nil {
+		return nil, err
+	}
+	priorSnapshot, err := store.FindPriorSnapshot(ctx, req.Resolved)
+	if err != nil {
+		return nil, err
+	}
+
+	bundle, err := FetchBundle(ctx, FetchBundleRequest{Config: req.Config})
+	if err != nil {
+		return nil, err
+	}
+	briefingPackage, err := BuildBriefing(BriefingRequest{
+		Config:   req.Config,
+		Resolved: req.Resolved,
+	}, bundle)
+	if err != nil {
+		return nil, err
+	}
+
+	briefingPath, err := store.SaveBriefing(ctx, req.Resolved, briefingPackage)
+	if err != nil {
+		return nil, err
+	}
+
+	recentChanges, err := recentChanges(ctx, store, priorSnapshot, briefingPackage, req.Config.RecentChange)
+	if err != nil {
+		return nil, err
+	}
+	dataPackage, err := promptinput.BuildWithRecentChanges(briefingPackage, recentChanges)
+	if err != nil {
+		return nil, err
+	}
+	dataPackagePath, err := store.SaveDataPackage(ctx, req.Resolved, dataPackage)
+	if err != nil {
+		return nil, err
+	}
+
+	renderer := req.Renderer
+	if renderer == nil {
+		renderer = scriptorium.Runner{
+			Binary:     req.Config.Scriptorium.Binary,
+			ConfigPath: req.Config.Scriptorium.ConfigPath,
+			Profile:    req.Config.Scriptorium.Profile,
+			Timeout:    req.Config.Scriptorium.Timeout,
+			ExtraArgs:  req.Config.Scriptorium.ExtraArgs,
+		}
+	}
+	renderResult, renderErr := renderer.Render(ctx, scriptorium.RenderRequest{
+		PromptID:        req.Resolved.Definition.PromptID,
+		DataPackagePath: dataPackagePath,
+	})
+
+	preflightPath := paths.Preflight
+	if renderResult != nil {
+		var err error
+		preflightPath, err = store.SavePreflight(ctx, req.Resolved, preflightArtifact(renderResult))
+		if err != nil {
+			return nil, err
+		}
+	}
+	metadata := state.BuildMetadata(req.Resolved, briefingPackage, state.ArtifactPaths{
+		Briefing:       briefingPath,
+		Metadata:       paths.Metadata,
+		DataPackage:    dataPackagePath,
+		Preflight:      preflightPath,
+		RenderedReport: paths.RenderedReport,
+	})
+	metadataPath, metadataErr := store.SaveMetadata(ctx, metadata)
+	if metadataErr != nil {
+		return nil, metadataErr
+	}
+	if renderErr != nil {
+		return nil, renderErr
+	}
+
+	reportPath, err := store.PrepareRenderedReport(ctx, req.Resolved)
+	if err != nil {
+		return nil, err
+	}
+	runResult, runErr := renderer.Run(ctx, scriptorium.RunRequest{
+		PromptID:        req.Resolved.Definition.PromptID,
+		DataPackagePath: dataPackagePath,
+		OutputPath:      reportPath,
+	})
+	if runErr == nil && req.OutputPath != "" && req.OutputPath != reportPath {
+		if err := fileutil.CopyFileAtomic(reportPath, req.OutputPath); err != nil {
+			return nil, err
+		}
+	}
+	outputPath := reportPath
+	if req.OutputPath != "" {
+		outputPath = req.OutputPath
+	}
+	metadata.RenderedReportPath = reportPath
+	metadataPath, metadataErr = store.SaveMetadata(ctx, metadata)
+	if metadataErr != nil {
+		return nil, metadataErr
+	}
+	if runErr != nil {
+		return nil, runErr
+	}
+
+	return &ReportResult{
+		Briefing:        briefingPackage,
+		BriefingPath:    briefingPath,
+		DataPackage:     dataPackage,
+		DataPackagePath: dataPackagePath,
+		PreflightPath:   preflightPath,
+		ReportPath:      reportPath,
+		OutputPath:      outputPath,
+		Metadata:        metadata,
+		MetadataPath:    metadataPath,
+		PriorSnapshot:   priorSnapshot,
+		RecentChanges:   recentChanges,
+		RenderResult:    renderResult,
+		RunResult:       runResult,
+	}, nil
+}
+
+func BuildBriefing(req BriefingRequest, bundle *forecast.Bundle) (briefing.Package, error) {
+	location, err := timeutil.LoadLocation(req.Config.WeatherAPI.Timezone)
+	if err != nil {
+		return briefing.Package{}, err
+	}
+	dayparts := make([]forecast.DaypartDefinition, 0, len(req.Config.Dayparts))
+	for _, daypart := range req.Config.Dayparts {
+		dayparts = append(dayparts, forecast.DaypartDefinition{
+			Name:  daypart.Name,
+			Start: daypart.Start,
+			End:   daypart.End,
+		})
+	}
+	switch req.Resolved.Definition.ID {
+	case report.DailyToday, report.DailyTomorrow:
+		summary, err := forecast.BuildDailySummary(bundle, req.Resolved.ValidPeriod.Start, location, dayparts)
+		if err != nil {
+			return briefing.Package{}, err
+		}
+		return briefing.BuildDaily(briefing.BuildContext{
+			Resolved: req.Resolved,
+			Bundle:   bundle,
+			Units:    req.Config.WeatherAPI.Units,
+			Timezone: req.Config.WeatherAPI.Timezone,
+			Location: briefingLocation(req.Config),
+		}, summary)
+	case report.ThreeDay, report.Weekend:
+		summaries, err := forecast.BuildPeriodDailySummaries(bundle, req.Resolved.ValidPeriod, location, dayparts)
+		if err != nil {
+			return briefing.Package{}, err
+		}
+		if req.Resolved.Definition.ID == report.Weekend {
+			return briefing.BuildWeekend(briefing.BuildContext{
+				Resolved: req.Resolved,
+				Bundle:   bundle,
+				Units:    req.Config.WeatherAPI.Units,
+				Timezone: req.Config.WeatherAPI.Timezone,
+				Location: briefingLocation(req.Config),
+			}, summaries)
+		}
+		return briefing.BuildThreeDay(briefing.BuildContext{
+			Resolved: req.Resolved,
+			Bundle:   bundle,
+			Units:    req.Config.WeatherAPI.Units,
+			Timezone: req.Config.WeatherAPI.Timezone,
+			Location: briefingLocation(req.Config),
+		}, summaries)
+	case report.Storm:
+		return briefing.BuildStorm(briefing.BuildContext{
+			Resolved: req.Resolved,
+			Bundle:   bundle,
+			Units:    req.Config.WeatherAPI.Units,
+			Timezone: req.Config.WeatherAPI.Timezone,
+			Location: briefingLocation(req.Config),
+		})
+	default:
+		return briefing.Package{}, fmt.Errorf("briefing is not implemented for report %q", req.Resolved.Definition.ID)
+	}
+}
+
+func briefingLocation(cfg config.Config) *briefing.LocationContext {
+	location := briefing.LocationContext{
+		ID:       cfg.Location.ID,
+		Name:     cfg.Location.Name,
+		Region:   cfg.Location.Region,
+		Timezone: cfg.WeatherAPI.Timezone,
+	}
+	if location.ID == "" && location.Name == "" && location.Region == "" && location.Timezone == "" {
+		return nil
+	}
+	return &location
+}
+
+func defaultStore(cfg config.Config) (*state.FilesystemStore, error) {
+	return state.NewFilesystemStore(cfg.Workspace)
+}
+
+func recentChanges(ctx context.Context, store state.Store, priorSnapshot *state.PriorSnapshot, current briefing.Package, cfg config.RecentChangeConfig) ([]changes.Change, error) {
+	if priorSnapshot == nil {
+		return nil, nil
+	}
+	previous, err := store.LoadBriefing(ctx, priorSnapshot.BriefingPath)
+	if err != nil {
+		return nil, err
+	}
+	thresholds := changes.Thresholds{
+		TemperatureDegrees:       cfg.TemperatureDegrees,
+		PrecipProbabilityPoints:  cfg.PrecipProbabilityPoints,
+		WindGustMilesPerHour:     cfg.WindGustMilesPerHour,
+		PrecipTimingShiftMinutes: cfg.PrecipTimingShiftMinutes,
+	}
+	switch current.Metadata.ReportID {
+	case report.DailyToday, report.DailyTomorrow:
+		return changes.CompareDaily(previous, current, thresholds)
+	case report.ThreeDay:
+		return changes.CompareThreeDay(previous, current, thresholds)
+	case report.Weekend:
+		return changes.CompareWeekend(previous, current, thresholds)
+	default:
+		return nil, nil
+	}
+}
+
+func preflightArtifact(result *scriptorium.RenderResult) state.PreflightArtifact {
+	if result == nil {
+		return state.PreflightArtifact{}
+	}
+	return state.PreflightArtifact{
+		Command:         append([]string(nil), result.Command...),
+		Stdout:          result.Stdout,
+		Stderr:          result.Stderr,
+		StdoutTruncated: result.StdoutTruncated,
+		StderrTruncated: result.StderrTruncated,
+		ExitCode:        result.ExitCode,
+	}
+}

internal/app/inspect.go

@@ -0,0 +1,125 @@
+package app
+
+import (
+	"context"
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptinput"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/state"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+type InspectReportsRequest struct {
+	Config config.Config
+	Limit  int
+}
+
+type InspectRunRequest struct {
+	Config config.Config
+	RunID  string
+}
+
+type SourceInspection struct {
+	RunID          string                    `json:"runId"`
+	ReportID       report.ID                 `json:"reportId"`
+	SourceLocation string                    `json:"sourceLocation,omitempty"`
+	Sources        []briefing.SourceMetadata `json:"sources,omitempty"`
+	Warnings       []forecast.SourceWarning  `json:"warnings,omitempty"`
+}
+
+func InspectReports(ctx context.Context, req InspectReportsRequest) ([]state.ReportRecord, error) {
+	store, err := defaultStore(req.Config)
+	if err != nil {
+		return nil, err
+	}
+	return store.ListReports(ctx, req.Limit)
+}
+
+func InspectMetadata(ctx context.Context, req InspectRunRequest) (state.Metadata, error) {
+	inspection, err := inspectRun(ctx, req)
+	return inspection.metadata, err
+}
+
+func InspectBriefing(ctx context.Context, req InspectRunRequest) (briefing.Package, error) {
+	inspection, err := inspectRun(ctx, req)
+	if err != nil {
+		return briefing.Package{}, err
+	}
+	return inspection.store.LoadBriefing(ctx, inspection.metadata.BriefingPath)
+}
+
+func InspectDataPackage(ctx context.Context, req InspectRunRequest) (promptinput.Package, error) {
+	inspection, err := inspectRun(ctx, req)
+	if err != nil {
+		return promptinput.Package{}, err
+	}
+	return inspection.store.LoadDataPackage(ctx, inspection.metadata.DataPackagePath)
+}
+
+func InspectPriorSnapshot(ctx context.Context, req InspectRunRequest) (*state.PriorSnapshot, error) {
+	inspection, err := inspectRun(ctx, req)
+	if err != nil {
+		return nil, err
+	}
+	resolved, err := resolvedFromMetadata(inspection.metadata)
+	if err != nil {
+		return nil, err
+	}
+	return inspection.store.FindPriorSnapshot(ctx, resolved)
+}
+
+func InspectSources(ctx context.Context, req InspectRunRequest) (SourceInspection, error) {
+	inspection, err := inspectRun(ctx, req)
+	if err != nil {
+		return SourceInspection{}, err
+	}
+	metadata := inspection.metadata
+	return SourceInspection{
+		RunID:          metadata.RunID,
+		ReportID:       metadata.ReportID,
+		SourceLocation: metadata.SourceLocation,
+		Sources:        metadata.Sources,
+		Warnings:       metadata.SourceWarnings,
+	}, nil
+}
+
+type runInspection struct {
+	store    *state.FilesystemStore
+	metadata state.Metadata
+}
+
+func inspectRun(ctx context.Context, req InspectRunRequest) (runInspection, error) {
+	store, err := defaultStore(req.Config)
+	if err != nil {
+		return runInspection{}, err
+	}
+	metadata, _, err := store.LoadMetadataByRunID(ctx, req.RunID)
+	if err != nil {
+		return runInspection{}, err
+	}
+	return runInspection{store: store, metadata: metadata}, nil
+}
+
+func resolvedFromMetadata(metadata state.Metadata) (report.Resolved, error) {
+	definition, err := report.DefaultRegistry().Lookup(metadata.ReportID)
+	if err != nil {
+		return report.Resolved{}, err
+	}
+	location, err := timeutil.LoadLocation(metadata.Timezone)
+	if err != nil {
+		return report.Resolved{}, err
+	}
+	if !metadata.ValidPeriod.IsValid() {
+		return report.Resolved{}, fmt.Errorf("metadata valid period for run id %q is invalid", metadata.RunID)
+	}
+	return report.Resolved{
+		Definition:  definition,
+		GeneratedAt: metadata.GeneratedAt,
+		Timezone:    location.String(),
+		ValidPeriod: metadata.ValidPeriod,
+	}, nil
+}

internal/briefing/daily.go

@@ -0,0 +1,445 @@
+package briefing
+
+import (
+	"fmt"
+	"math"
+	"sort"
+	"strings"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+)
+
+type Daily struct {
+	BottomLine          BottomLine                `json:"bottomLine"`
+	Dayparts            []forecast.DaypartSummary `json:"dayparts"`
+	RelevantAlerts      []forecast.AlertOverlap   `json:"relevantAlerts,omitempty"`
+	OutdoorWindows      OutdoorWindows            `json:"outdoorWindows"`
+	Planning            *TomorrowPlanning         `json:"planning,omitempty"`
+	NarrativePeriods    []forecast.ForecastPeriod `json:"narrativePeriods,omitempty"`
+	Discussion          DiscussionContext         `json:"discussion,omitempty"`
+	WeatherStory        *WeatherStoryContext      `json:"weatherStory,omitempty"`
+	ForecastSummaryDate string                    `json:"forecastSummaryDate"`
+}
+
+type BottomLine struct {
+	Summary              string               `json:"summary"`
+	Hazards              []string             `json:"hazards,omitempty"`
+	Temperature          forecast.Range       `json:"temperature,omitempty"`
+	MaxPrecipProbability *forecast.TimedValue `json:"maxPrecipitationProbability,omitempty"`
+	PeakWindGust         *forecast.TimedValue `json:"peakWindGust,omitempty"`
+}
+
+type OutdoorWindows struct {
+	Best  *OutdoorWindow `json:"best,omitempty"`
+	Worst *OutdoorWindow `json:"worst,omitempty"`
+}
+
+type OutdoorWindow struct {
+	Daypart string   `json:"daypart"`
+	Start   string   `json:"start"`
+	End     string   `json:"end"`
+	Reasons []string `json:"reasons,omitempty"`
+	Score   float64  `json:"score"`
+}
+
+type TomorrowPlanning struct {
+	MorningReadiness             []string `json:"morningReadiness,omitempty"`
+	CommuteSchoolWorkdayConcerns []string `json:"commuteSchoolWorkdayConcerns,omitempty"`
+	OvernightChangeWatch         []string `json:"overnightChangeWatch,omitempty"`
+}
+
+type DiscussionContext struct {
+	Product     string   `json:"product,omitempty"`
+	KeyMessages []string `json:"keyMessages,omitempty"`
+	ShortTerm   string   `json:"shortTerm,omitempty"`
+	LongTerm    string   `json:"longTerm,omitempty"`
+}
+
+type WeatherStoryContext struct {
+	Available   bool       `json:"available"`
+	OfficeID    string     `json:"officeId,omitempty"`
+	StartTime   time.Time  `json:"startTime"`
+	EndTime     time.Time  `json:"endTime"`
+	UpdatedAt   *time.Time `json:"updatedAt,omitempty"`
+	Title       string     `json:"title,omitempty"`
+	Description string     `json:"description,omitempty"`
+	AltText     string     `json:"altText,omitempty"`
+	Priority    bool       `json:"priority"`
+	Order       int        `json:"order"`
+	DownloadURL string     `json:"downloadUrl,omitempty"`
+}
+
+func BuildDaily(ctx BuildContext, summary *forecast.DailySummary) (Package, error) {
+	if ctx.Resolved.Definition.ID != report.DailyToday && ctx.Resolved.Definition.ID != report.DailyTomorrow {
+		return Package{}, fmt.Errorf("daily briefing requires a daily report definition")
+	}
+	if summary == nil {
+		return Package{}, fmt.Errorf("daily forecast summary is required")
+	}
+	pkg := buildPackage(ctx)
+	pkg.Daily = &Daily{
+		BottomLine:          buildBottomLine(summary),
+		Dayparts:            summary.Dayparts,
+		RelevantAlerts:      summary.AlertOverlaps,
+		OutdoorWindows:      buildOutdoorWindows(summary.Dayparts),
+		NarrativePeriods:    summary.NarrativePeriods,
+		Discussion:          buildDiscussion(summary.Discussion),
+		WeatherStory:        buildWeatherStory(ctx.Bundle),
+		ForecastSummaryDate: summary.Date,
+	}
+	setRelevantAlertCount(&pkg.Metadata, len(summary.AlertOverlaps))
+	if ctx.Resolved.Definition.ID == report.DailyTomorrow {
+		pkg.Daily.Planning = buildTomorrowPlanning(summary)
+	}
+	return pkg, nil
+}
+
+func buildBottomLine(summary *forecast.DailySummary) BottomLine {
+	bottomLine := BottomLine{}
+	conditions := map[string]struct{}{}
+	hazards := map[string]struct{}{}
+	for _, daypart := range summary.Dayparts {
+		addRange(&bottomLine.Temperature, daypart.Temperature)
+		maxTimedValue(&bottomLine.MaxPrecipProbability, daypart.MaxPrecipitationProbability)
+		maxTimedValue(&bottomLine.PeakWindGust, daypart.PeakWindGust)
+		if daypart.DominantCondition != "" {
+			conditions[daypart.DominantCondition] = struct{}{}
+		}
+		for _, hazard := range hazardsForIndicators(daypart.Indicators) {
+			hazards[hazard] = struct{}{}
+		}
+	}
+	for _, alert := range summary.AlertOverlaps {
+		if alert.Event != "" {
+			hazards[alert.Event] = struct{}{}
+		}
+	}
+	bottomLine.Hazards = sortedSet(hazards)
+	bottomLine.Summary = bottomLineText(sortedSet(conditions), bottomLine.Hazards)
+	return bottomLine
+}
+
+func buildOutdoorWindows(dayparts []forecast.DaypartSummary) OutdoorWindows {
+	var best *OutdoorWindow
+	var worst *OutdoorWindow
+	for _, daypart := range dayparts {
+		if len(daypart.HourlyPeriods) == 0 {
+			continue
+		}
+		window := scoreOutdoorWindow(daypart)
+		if best == nil || window.Score < best.Score {
+			copied := window
+			best = &copied
+		}
+		if worst == nil || window.Score > worst.Score {
+			copied := window
+			worst = &copied
+		}
+	}
+	return OutdoorWindows{Best: best, Worst: worst}
+}
+
+func buildTomorrowPlanning(summary *forecast.DailySummary) *TomorrowPlanning {
+	planning := &TomorrowPlanning{}
+	morning := daypartNamed(summary.Dayparts, "morning")
+	if morning != nil {
+		planning.MorningReadiness = append(planning.MorningReadiness, readinessNotes(*morning)...)
+	}
+	if len(planning.MorningReadiness) == 0 {
+		planning.MorningReadiness = append(planning.MorningReadiness, "Morning weather looks routine based on the available hourly forecast.")
+	}
+
+	for _, daypart := range summary.Dayparts {
+		if daypart.Name == "overnight" || daypart.Name == "evening" {
+			continue
+		}
+		planning.CommuteSchoolWorkdayConcerns = appendUnique(planning.CommuteSchoolWorkdayConcerns, concernNotes(daypart)...)
+	}
+	for _, alert := range summary.AlertOverlaps {
+		if alert.Event != "" {
+			planning.CommuteSchoolWorkdayConcerns = appendUnique(planning.CommuteSchoolWorkdayConcerns, "Active alert to plan around: "+alert.Event+".")
+		}
+	}
+	if len(planning.CommuteSchoolWorkdayConcerns) == 0 {
+		planning.CommuteSchoolWorkdayConcerns = append(planning.CommuteSchoolWorkdayConcerns, "No major commute, school, or workday weather concerns stand out in the available forecast.")
+	}
+
+	overnight := daypartNamed(summary.Dayparts, "overnight")
+	if overnight != nil {
+		planning.OvernightChangeWatch = append(planning.OvernightChangeWatch, overnightWatchNotes(*overnight)...)
+	}
+	if len(planning.OvernightChangeWatch) == 0 {
+		planning.OvernightChangeWatch = append(planning.OvernightChangeWatch, "Watch for forecast timing or intensity adjustments overnight.")
+	}
+
+	return planning
+}
+
+func readinessNotes(daypart forecast.DaypartSummary) []string {
+	notes := []string{}
+	if daypart.MaxPrecipitationProbability != nil && daypart.MaxPrecipitationProbability.Value >= 50 {
+		notes = append(notes, fmt.Sprintf("Morning precipitation chance peaks near %.0f%%.", daypart.MaxPrecipitationProbability.Value))
+	}
+	if daypart.PeakWindGust != nil && daypart.PeakWindGust.Value >= 30 {
+		notes = append(notes, fmt.Sprintf("Morning gusts may reach %.0f mph.", daypart.PeakWindGust.Value))
+	}
+	if daypart.Indicators.Snow || daypart.Indicators.Ice {
+		notes = append(notes, "Morning wintry weather could affect surfaces and travel.")
+	}
+	if daypart.Indicators.Fog {
+		notes = append(notes, "Morning fog could reduce visibility.")
+	}
+	if daypart.Temperature.Min != nil && *daypart.Temperature.Min <= 32 {
+		notes = append(notes, "Morning temperatures may be at or below freezing.")
+	}
+	return appendUnique(nil, notes...)
+}
+
+func concernNotes(daypart forecast.DaypartSummary) []string {
+	notes := []string{}
+	prefix := titleWord(daypart.Name)
+	if prefix == "" {
+		prefix = "Daytime"
+	}
+	if daypart.MaxPrecipitationProbability != nil && daypart.MaxPrecipitationProbability.Value >= 40 {
+		notes = append(notes, fmt.Sprintf("%s precipitation chance reaches %.0f%%.", prefix, daypart.MaxPrecipitationProbability.Value))
+	}
+	if daypart.PeakWindGust != nil && daypart.PeakWindGust.Value >= 30 {
+		notes = append(notes, fmt.Sprintf("%s gusts may reach %.0f mph.", prefix, daypart.PeakWindGust.Value))
+	}
+	if daypart.Indicators.Snow || daypart.Indicators.Ice {
+		notes = append(notes, prefix+" wintry weather may affect travel.")
+	}
+	if daypart.Indicators.Heat {
+		notes = append(notes, prefix+" heat may require extra hydration and breaks.")
+	}
+	if daypart.Indicators.Cold {
+		notes = append(notes, prefix+" cold may require extra layers.")
+	}
+	if len(daypart.AlertOverlaps) > 0 {
+		notes = append(notes, prefix+" alert overlap needs attention.")
+	}
+	return appendUnique(nil, notes...)
+}
+
+func overnightWatchNotes(daypart forecast.DaypartSummary) []string {
+	notes := []string{}
+	if daypart.MaxPrecipitationProbability != nil && daypart.MaxPrecipitationProbability.Value >= 30 {
+		notes = append(notes, fmt.Sprintf("Overnight precipitation timing may shift; current peak is near %.0f%%.", daypart.MaxPrecipitationProbability.Value))
+	}
+	if daypart.PeakWindGust != nil && daypart.PeakWindGust.Value >= 30 {
+		notes = append(notes, fmt.Sprintf("Overnight gusts may reach %.0f mph before morning plans begin.", daypart.PeakWindGust.Value))
+	}
+	if daypart.Indicators.Snow || daypart.Indicators.Ice {
+		notes = append(notes, "Overnight wintry weather could leave morning travel impacts.")
+	}
+	if len(daypart.AlertOverlaps) > 0 {
+		notes = append(notes, "Overnight alert timing could affect the morning setup.")
+	}
+	return appendUnique(nil, notes...)
+}
+
+func daypartNamed(dayparts []forecast.DaypartSummary, name string) *forecast.DaypartSummary {
+	for i := range dayparts {
+		if strings.EqualFold(dayparts[i].Name, name) {
+			return &dayparts[i]
+		}
+	}
+	return nil
+}
+
+func buildDiscussion(discussion *forecast.Discussion) DiscussionContext {
+	if discussion == nil {
+		return DiscussionContext{}
+	}
+	ctx := DiscussionContext{
+		Product:     discussion.Product,
+		KeyMessages: discussion.KeyMessages,
+	}
+	if discussion.ShortTerm != nil {
+		ctx.ShortTerm = discussion.ShortTerm.Text
+	}
+	if discussion.LongTerm != nil {
+		ctx.LongTerm = discussion.LongTerm.Text
+	}
+	return ctx
+}
+
+func buildWeatherStory(bundle *forecast.Bundle) *WeatherStoryContext {
+	if bundle == nil || bundle.WeatherStory == nil {
+		return nil
+	}
+	story := bundle.WeatherStory
+	return &WeatherStoryContext{
+		Available:   true,
+		OfficeID:    story.OfficeID,
+		StartTime:   story.StartTime,
+		EndTime:     story.EndTime,
+		UpdatedAt:   copyTime(story.UpdatedAt),
+		Title:       story.Title,
+		Description: story.Description,
+		AltText:     story.AltText,
+		Priority:    story.Priority,
+		Order:       story.Order,
+		DownloadURL: story.DownloadURL,
+	}
+}
+
+func copyTime(value *time.Time) *time.Time {
+	if value == nil {
+		return nil
+	}
+	copied := *value
+	return &copied
+}
+
+func scoreOutdoorWindow(daypart forecast.DaypartSummary) OutdoorWindow {
+	score := 0.0
+	reasons := []string{}
+	if daypart.MaxPrecipitationProbability != nil {
+		score += daypart.MaxPrecipitationProbability.Value
+		if daypart.MaxPrecipitationProbability.Value >= 50 {
+			reasons = append(reasons, "high precipitation chance")
+		}
+	}
+	if daypart.PeakWindGust != nil {
+		score += daypart.PeakWindGust.Value * 1.5
+		if daypart.PeakWindGust.Value >= 30 {
+			reasons = append(reasons, "gusty wind")
+		}
+	}
+	if len(daypart.AlertOverlaps) > 0 {
+		score += float64(len(daypart.AlertOverlaps)) * 100
+		reasons = append(reasons, "alert overlap")
+	}
+	if daypart.Indicators.Heat || daypart.Indicators.Cold {
+		score += 25
+		if daypart.Indicators.Heat {
+			reasons = append(reasons, "heat risk")
+		}
+		if daypart.Indicators.Cold {
+			reasons = append(reasons, "cold risk")
+		}
+	}
+	if len(reasons) == 0 {
+		reasons = append(reasons, "quiet weather")
+	}
+	return OutdoorWindow{
+		Daypart: daypart.Name,
+		Start:   daypart.Period.Start.Format("15:04"),
+		End:     daypart.Period.End.Format("15:04"),
+		Reasons: dedupe(reasons),
+		Score:   math.Round(score*10) / 10,
+	}
+}
+
+func bottomLineText(conditions []string, hazards []string) string {
+	if len(conditions) == 0 && len(hazards) == 0 {
+		return "Quiet weather is expected."
+	}
+	parts := []string{}
+	if len(conditions) > 0 {
+		parts = append(parts, "Conditions: "+strings.Join(conditions, "; "))
+	}
+	if len(hazards) > 0 {
+		parts = append(parts, "Watch points: "+strings.Join(hazards, "; "))
+	}
+	return strings.Join(parts, ". ") + "."
+}
+
+func hazardsForIndicators(indicators forecast.Indicators) []string {
+	var hazards []string
+	if indicators.Snow {
+		hazards = append(hazards, "snow")
+	}
+	if indicators.Ice {
+		hazards = append(hazards, "ice")
+	}
+	if indicators.Fog {
+		hazards = append(hazards, "fog")
+	}
+	if indicators.Heat {
+		hazards = append(hazards, "heat")
+	}
+	if indicators.Cold {
+		hazards = append(hazards, "cold")
+	}
+	if indicators.Wind {
+		hazards = append(hazards, "wind")
+	}
+	return hazards
+}
+
+func addRange(target *forecast.Range, value forecast.Range) {
+	if value.Min != nil {
+		if target.Min == nil || *value.Min < *target.Min {
+			copied := *value.Min
+			target.Min = &copied
+		}
+	}
+	if value.Max != nil {
+		if target.Max == nil || *value.Max > *target.Max {
+			copied := *value.Max
+			target.Max = &copied
+		}
+	}
+}
+
+func maxTimedValue(target **forecast.TimedValue, value *forecast.TimedValue) {
+	if value == nil {
+		return
+	}
+	if *target == nil || value.Value > (*target).Value {
+		copied := *value
+		*target = &copied
+	}
+}
+
+func sortedSet(values map[string]struct{}) []string {
+	out := make([]string, 0, len(values))
+	for value := range values {
+		out = append(out, value)
+	}
+	sort.Strings(out)
+	return out
+}
+
+func dedupe(values []string) []string {
+	seen := map[string]struct{}{}
+	out := []string{}
+	for _, value := range values {
+		if _, ok := seen[value]; ok {
+			continue
+		}
+		seen[value] = struct{}{}
+		out = append(out, value)
+	}
+	return out
+}
+
+func appendUnique(values []string, candidates ...string) []string {
+	seen := map[string]struct{}{}
+	for _, value := range values {
+		seen[value] = struct{}{}
+	}
+	for _, candidate := range candidates {
+		if candidate == "" {
+			continue
+		}
+		if _, ok := seen[candidate]; ok {
+			continue
+		}
+		seen[candidate] = struct{}{}
+		values = append(values, candidate)
+	}
+	return values
+}
+
+func titleWord(value string) string {
+	if value == "" {
+		return ""
+	}
+	return strings.ToUpper(value[:1]) + value[1:]
+}

internal/briefing/daily_test.go

@@ -0,0 +1,327 @@
+package briefing
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+func TestDailyBriefingFromRepresentativeFixture(t *testing.T) {
+	bundle := loadBundleFixture(t)
+	currentIsDay := true
+	currentTemp := 75.9
+	currentFeelsLike := 76.1
+	currentHumidity := 56.0
+	currentWind := 10.7
+	bundle.Current = &forecast.Current{
+		ConditionText:           "Partly cloudy",
+		IsDay:                   &currentIsDay,
+		TemperatureF:            &currentTemp,
+		ApparentTemperatureF:    &currentFeelsLike,
+		RelativeHumidityPercent: &currentHumidity,
+		WindSpeedMph:            &currentWind,
+	}
+	bundle.Sources[0].DataSHA256 = "abc123"
+	bundle.Warnings = []forecast.SourceWarning{{Source: "daily", Code: "missing_source", Severity: "warning"}}
+	location := mustLocation(t)
+	resolved := mustResolveDaily(t, location)
+	summary, err := forecast.BuildDailySummary(bundle, resolved.ValidPeriod.Start, location, defaultDayparts())
+	if err != nil {
+		t.Fatalf("BuildDailySummary() error = %v", err)
+	}
+
+	pkg, err := BuildDaily(BuildContext{
+		Resolved: resolved,
+		Bundle:   bundle,
+		Units:    "us",
+		Timezone: "America/Chicago",
+		Location: &LocationContext{
+			ID:       "home",
+			Name:     "Brentwood",
+			Region:   "St. Louis Metro",
+			Timezone: "America/Chicago",
+		},
+	}, summary)
+	if err != nil {
+		t.Fatalf("BuildDaily() error = %v", err)
+	}
+
+	if pkg.Metadata.SchemaVersion != SchemaVersion {
+		t.Fatalf("SchemaVersion = %q, want %q", pkg.Metadata.SchemaVersion, SchemaVersion)
+	}
+	if !strings.Contains(pkg.Metadata.RunID, "daily_today") {
+		t.Fatalf("RunID = %q, want report id", pkg.Metadata.RunID)
+	}
+	if pkg.Metadata.ReportID != report.DailyToday {
+		t.Fatalf("ReportID = %q, want daily_today", pkg.Metadata.ReportID)
+	}
+	if pkg.Metadata.Units != "us" || pkg.Metadata.Timezone != "America/Chicago" {
+		t.Fatalf("metadata units/timezone = %q/%q", pkg.Metadata.Units, pkg.Metadata.Timezone)
+	}
+	if pkg.Metadata.Location == nil || pkg.Metadata.Location.ID != "home" || pkg.Metadata.Location.Name != "Brentwood" || pkg.Metadata.Location.Region != "St. Louis Metro" || pkg.Metadata.Location.Timezone != "America/Chicago" {
+		t.Fatalf("metadata location = %#v, want configured prompt location", pkg.Metadata.Location)
+	}
+	if pkg.CurrentConditions == nil || pkg.CurrentConditions.ConditionText != "Partly cloudy" || pkg.CurrentConditions.TemperatureF == nil || *pkg.CurrentConditions.TemperatureF != currentTemp || pkg.CurrentConditions.RelativeHumidityPercent == nil || *pkg.CurrentConditions.RelativeHumidityPercent != currentHumidity {
+		t.Fatalf("CurrentConditions = %#v, want current conditions from bundle", pkg.CurrentConditions)
+	}
+	if len(pkg.Metadata.Sources) != 1 || pkg.Metadata.Sources[0].DataSHA256 != "abc123" {
+		t.Fatalf("Sources = %#v, want source hash", pkg.Metadata.Sources)
+	}
+	if len(pkg.Metadata.SourceWarnings) != 1 {
+		t.Fatalf("SourceWarnings length = %d, want 1", len(pkg.Metadata.SourceWarnings))
+	}
+	if pkg.Daily == nil {
+		t.Fatal("Daily = nil")
+	}
+	if len(pkg.Daily.Dayparts) != 5 {
+		t.Fatalf("Dayparts length = %d, want 5", len(pkg.Daily.Dayparts))
+	}
+	if len(pkg.Daily.RelevantAlerts) != 1 {
+		t.Fatalf("RelevantAlerts length = %d, want 1", len(pkg.Daily.RelevantAlerts))
+	}
+	if len(pkg.Daily.NarrativePeriods) != 1 {
+		t.Fatalf("NarrativePeriods length = %d, want 1", len(pkg.Daily.NarrativePeriods))
+	}
+	if len(pkg.Daily.Discussion.KeyMessages) != 1 {
+		t.Fatalf("Discussion key messages length = %d, want 1", len(pkg.Daily.Discussion.KeyMessages))
+	}
+	if pkg.Daily.Discussion.ShortTerm != "Morning showers taper as a weak boundary shifts east." {
+		t.Fatalf("Discussion.ShortTerm = %q, want short-term AFD narrative", pkg.Daily.Discussion.ShortTerm)
+	}
+	if pkg.Daily.Discussion.LongTerm != "Warmer and more humid conditions return with periodic rain chances." {
+		t.Fatalf("Discussion.LongTerm = %q, want long-term AFD narrative", pkg.Daily.Discussion.LongTerm)
+	}
+	if pkg.Daily.OutdoorWindows.Best == nil || pkg.Daily.OutdoorWindows.Worst == nil {
+		t.Fatalf("OutdoorWindows = %#v, want best and worst", pkg.Daily.OutdoorWindows)
+	}
+	if pkg.Daily.BottomLine.Summary == "" {
+		t.Fatal("BottomLine summary is empty")
+	}
+	if _, err := json.Marshal(pkg); err != nil {
+		t.Fatalf("briefing package is not JSON inspectable: %v", err)
+	}
+}
+
+func TestDailyBriefingQuietWeather(t *testing.T) {
+	location := mustLocation(t)
+	resolved := mustResolveDaily(t, location)
+	bundle := &forecast.Bundle{
+		Hourly: &forecast.ForecastRun{Periods: []forecast.ForecastPeriod{
+			quietHour("2026-05-29T09:00:00-05:00", "2026-05-29T10:00:00-05:00", 72),
+		}},
+		Alerts: &forecast.AlertRun{},
+		Sources: []forecast.Source{
+			{Name: "hourly", FetchedAt: time.Now()},
+			{Name: "alerts", Endpoint: "/alerts/active", FetchedAt: time.Now()},
+			{Name: "current", Endpoint: "/conditions/current", FetchedAt: time.Now(), Missing: true},
+		},
+		Warnings: []forecast.SourceWarning{{Source: "current", Code: "missing_source", Severity: "warning"}},
+	}
+	summary, err := forecast.BuildDailySummary(bundle, resolved.ValidPeriod.Start, location, defaultDayparts())
+	if err != nil {
+		t.Fatalf("BuildDailySummary() error = %v", err)
+	}
+	pkg, err := BuildDaily(BuildContext{Resolved: resolved, Bundle: bundle, Units: "us", Timezone: "America/Chicago"}, summary)
+	if err != nil {
+		t.Fatalf("BuildDaily() error = %v", err)
+	}
+	if pkg.Daily.BottomLine.Summary != "Conditions: Clear." {
+		t.Fatalf("BottomLine summary = %q, want clear conditions", pkg.Daily.BottomLine.Summary)
+	}
+	if pkg.CurrentConditions != nil {
+		t.Fatalf("CurrentConditions = %#v, want nil when current conditions are missing", pkg.CurrentConditions)
+	}
+	if len(pkg.Metadata.SourceWarnings) != 1 || pkg.Metadata.SourceWarnings[0].Source != "current" {
+		t.Fatalf("SourceWarnings = %#v, want current missing-source warning", pkg.Metadata.SourceWarnings)
+	}
+	if len(pkg.Daily.RelevantAlerts) != 0 {
+		t.Fatalf("RelevantAlerts length = %d, want 0", len(pkg.Daily.RelevantAlerts))
+	}
+	if pkg.Metadata.Alerts == nil {
+		t.Fatal("Metadata.Alerts = nil, want checked no-active-alerts status")
+	}
+	if !pkg.Metadata.Alerts.Checked || pkg.Metadata.Alerts.ActiveCount != 0 || pkg.Metadata.Alerts.RelevantCount != 0 || pkg.Metadata.Alerts.Missing {
+		t.Fatalf("Metadata.Alerts = %#v, want checked no-active-alerts status", pkg.Metadata.Alerts)
+	}
+	data, err := json.Marshal(pkg.Metadata.Alerts)
+	if err != nil {
+		t.Fatalf("marshal alert metadata: %v", err)
+	}
+	if strings.Contains(string(data), `"missing"`) {
+		t.Fatalf("alert metadata includes missing for checked empty alerts:\n%s", string(data))
+	}
+}
+
+func TestDailyBriefingAlertExclusion(t *testing.T) {
+	location := mustLocation(t)
+	resolved := mustResolveDaily(t, location)
+	bundle := loadBundleFixture(t)
+	bundle.Alerts = &forecast.AlertRun{Alerts: []json.RawMessage{
+		json.RawMessage(`{"event":"Future Watch","effective":"2026-06-01T00:00:00-05:00","expires":"2026-06-01T06:00:00-05:00"}`),
+	}}
+	summary, err := forecast.BuildDailySummary(bundle, resolved.ValidPeriod.Start, location, defaultDayparts())
+	if err != nil {
+		t.Fatalf("BuildDailySummary() error = %v", err)
+	}
+	pkg, err := BuildDaily(BuildContext{Resolved: resolved, Bundle: bundle, Units: "us", Timezone: "America/Chicago"}, summary)
+	if err != nil {
+		t.Fatalf("BuildDaily() error = %v", err)
+	}
+	if len(pkg.Daily.RelevantAlerts) != 0 {
+		t.Fatalf("RelevantAlerts length = %d, want 0", len(pkg.Daily.RelevantAlerts))
+	}
+}
+
+func TestTomorrowBriefingIncludesPlanningInputs(t *testing.T) {
+	location := mustLocation(t)
+	resolved, err := report.Resolve(report.DailyTomorrow, report.ResolveRequest{
+		Now:      mustParse("2026-05-29T18:00:00-05:00"),
+		Location: location,
+	})
+	if err != nil {
+		t.Fatalf("resolve tomorrow: %v", err)
+	}
+	precip := 70.0
+	wind := 34.0
+	summary := &forecast.DailySummary{
+		Date:   "2026-05-30",
+		Period: resolved.ValidPeriod,
+		Dayparts: []forecast.DaypartSummary{
+			{
+				Name: "overnight",
+				Period: timeutil.Period{
+					Start: mustParse("2026-05-30T00:00:00-05:00"),
+					End:   mustParse("2026-05-30T06:00:00-05:00"),
+				},
+				MaxPrecipitationProbability: &forecast.TimedValue{
+					Value: 40,
+					Time:  mustParse("2026-05-30T03:00:00-05:00"),
+				},
+			},
+			{
+				Name: "morning",
+				Period: timeutil.Period{
+					Start: mustParse("2026-05-30T06:00:00-05:00"),
+					End:   mustParse("2026-05-30T12:00:00-05:00"),
+				},
+				MaxPrecipitationProbability: &forecast.TimedValue{
+					Value: precip,
+					Time:  mustParse("2026-05-30T08:00:00-05:00"),
+				},
+				PeakWindGust: &forecast.TimedValue{
+					Value: wind,
+					Time:  mustParse("2026-05-30T09:00:00-05:00"),
+				},
+				Indicators: forecast.Indicators{Snow: true},
+			},
+		},
+	}
+
+	pkg, err := BuildDaily(BuildContext{
+		Resolved: resolved,
+		Units:    "us",
+		Timezone: "America/Chicago",
+	}, summary)
+	if err != nil {
+		t.Fatalf("BuildDaily() error = %v", err)
+	}
+
+	if pkg.Metadata.ReportID != report.DailyTomorrow || pkg.Metadata.Variant != "tomorrow" {
+		t.Fatalf("metadata report/variant = %q/%q, want tomorrow", pkg.Metadata.ReportID, pkg.Metadata.Variant)
+	}
+	if pkg.Daily.ForecastSummaryDate != "2026-05-30" {
+		t.Fatalf("ForecastSummaryDate = %q, want 2026-05-30", pkg.Daily.ForecastSummaryDate)
+	}
+	if pkg.Daily.Planning == nil {
+		t.Fatal("Planning = nil, want tomorrow planning inputs")
+	}
+	if len(pkg.Daily.Planning.MorningReadiness) == 0 || len(pkg.Daily.Planning.CommuteSchoolWorkdayConcerns) == 0 || len(pkg.Daily.Planning.OvernightChangeWatch) == 0 {
+		t.Fatalf("Planning = %#v, want populated planning inputs", pkg.Daily.Planning)
+	}
+	if !strings.Contains(strings.Join(pkg.Daily.Planning.MorningReadiness, " "), "precipitation") {
+		t.Fatalf("MorningReadiness = %#v, want precipitation note", pkg.Daily.Planning.MorningReadiness)
+	}
+}
+
+func TestSaveBriefingPackage(t *testing.T) {
+	pkg := Package{Metadata: Metadata{SchemaVersion: SchemaVersion}}
+	path := filepath.Join(t.TempDir(), "nested", "briefing.json")
+	if err := Save(path, pkg); err != nil {
+		t.Fatalf("Save() error = %v", err)
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read briefing: %v", err)
+	}
+	if !strings.Contains(string(data), SchemaVersion) {
+		t.Fatalf("saved briefing missing schema version:\n%s", string(data))
+	}
+}
+
+func loadBundleFixture(t *testing.T) *forecast.Bundle {
+	t.Helper()
+	data, err := os.ReadFile(filepath.Join("..", "forecast", "testdata", "daily_bundle.json"))
+	if err != nil {
+		t.Fatalf("read bundle fixture: %v", err)
+	}
+	var bundle forecast.Bundle
+	if err := json.Unmarshal(data, &bundle); err != nil {
+		t.Fatalf("decode bundle fixture: %v", err)
+	}
+	return &bundle
+}
+
+func mustResolveDaily(t *testing.T, location *time.Location) report.Resolved {
+	t.Helper()
+	resolved, err := report.Resolve(report.DailyToday, report.ResolveRequest{
+		Now:      mustParse("2026-05-29T05:00:00-05:00"),
+		Location: location,
+	})
+	if err != nil {
+		t.Fatalf("resolve daily: %v", err)
+	}
+	return resolved
+}
+
+func defaultDayparts() []forecast.DaypartDefinition {
+	return []forecast.DaypartDefinition{
+		{Name: "overnight", Start: "00:00", End: "06:00"},
+		{Name: "morning", Start: "06:00", End: "10:00"},
+		{Name: "midday", Start: "10:00", End: "15:00"},
+		{Name: "afternoon", Start: "15:00", End: "17:00"},
+		{Name: "evening", Start: "17:00", End: "24:00"},
+	}
+}
+
+func quietHour(start string, end string, temperature float64) forecast.ForecastPeriod {
+	return forecast.ForecastPeriod{
+		StartTime:       mustParse(start),
+		EndTime:         mustParse(end),
+		TextDescription: "Clear",
+		TemperatureF:    &temperature,
+	}
+}
+
+func mustLocation(t *testing.T) *time.Location {
+	t.Helper()
+	location, err := time.LoadLocation("America/Chicago")
+	if err != nil {
+		t.Fatalf("load location: %v", err)
+	}
+	return location
+}
+
+func mustParse(value string) time.Time {
+	parsed, err := time.Parse(time.RFC3339, value)
+	if err != nil {
+		panic(err)
+	}
+	return parsed
+}

internal/briefing/package.go

@@ -0,0 +1,269 @@
+// Package briefing builds report-specific structured briefing packages.
+package briefing
+
+import (
+	"fmt"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/fileutil"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+const SchemaVersion = "weatherreporter.briefing.v1"
+
+type Package struct {
+	Metadata          Metadata                  `json:"metadata"`
+	CurrentConditions *CurrentConditionsContext `json:"currentConditions,omitempty"`
+	Daily             *Daily                    `json:"daily,omitempty"`
+	ThreeDay          *ThreeDay                 `json:"threeDay,omitempty"`
+	Weekend           *Weekend                  `json:"weekend,omitempty"`
+	Storm             *Storm                    `json:"storm,omitempty"`
+}
+
+type Metadata struct {
+	SchemaVersion    string                   `json:"schemaVersion"`
+	RunID            string                   `json:"runId"`
+	ReportID         report.ID                `json:"reportId"`
+	Variant          string                   `json:"variant,omitempty"`
+	PromptID         string                   `json:"promptId"`
+	GeneratedAt      time.Time                `json:"generatedAt"`
+	Units            string                   `json:"units"`
+	Timezone         string                   `json:"timezone"`
+	ValidPeriod      timeutil.Period          `json:"validPeriod"`
+	Location         *LocationContext         `json:"location,omitempty"`
+	SourceLocationID string                   `json:"sourceLocationId,omitempty"`
+	SourceLocation   string                   `json:"sourceLocation,omitempty"`
+	Sources          []SourceMetadata         `json:"sources,omitempty"`
+	SourceWarnings   []forecast.SourceWarning `json:"sourceWarnings,omitempty"`
+	Alerts           *AlertStatus             `json:"alerts,omitempty"`
+}
+
+type LocationContext struct {
+	ID       string `json:"id,omitempty"`
+	Name     string `json:"name,omitempty"`
+	Region   string `json:"region,omitempty"`
+	Timezone string `json:"timezone,omitempty"`
+}
+
+type CurrentConditionsContext struct {
+	ConditionText           string   `json:"conditionText,omitempty"`
+	IsDay                   *bool    `json:"isDay,omitempty"`
+	TemperatureC            *float64 `json:"temperatureC,omitempty"`
+	TemperatureF            *float64 `json:"temperatureF,omitempty"`
+	ApparentTemperatureC    *float64 `json:"apparentTemperatureC,omitempty"`
+	ApparentTemperatureF    *float64 `json:"apparentTemperatureF,omitempty"`
+	DewpointC               *float64 `json:"dewpointC,omitempty"`
+	DewpointF               *float64 `json:"dewpointF,omitempty"`
+	RelativeHumidityPercent *float64 `json:"relativeHumidityPercent,omitempty"`
+	WindSpeedKmh            *float64 `json:"windSpeedKmh,omitempty"`
+	WindSpeedMph            *float64 `json:"windSpeedMph,omitempty"`
+	WindDirectionDegrees    *float64 `json:"windDirectionDegrees,omitempty"`
+}
+
+type SourceMetadata struct {
+	Name       string                   `json:"name"`
+	Endpoint   string                   `json:"endpoint,omitempty"`
+	FetchedAt  time.Time                `json:"fetchedAt"`
+	IssuedAt   *time.Time               `json:"issuedAt,omitempty"`
+	UpdatedAt  *time.Time               `json:"updatedAt,omitempty"`
+	DataSHA256 string                   `json:"dataSha256,omitempty"`
+	Missing    bool                     `json:"missing,omitempty"`
+	Warnings   []forecast.SourceWarning `json:"warnings,omitempty"`
+}
+
+type AlertStatus struct {
+	Checked       bool `json:"checked"`
+	ActiveCount   int  `json:"activeCount"`
+	RelevantCount int  `json:"relevantCount"`
+	Missing       bool `json:"missing,omitempty"`
+}
+
+type BuildContext struct {
+	Resolved report.Resolved
+	Bundle   *forecast.Bundle
+	Units    string
+	Timezone string
+	Location *LocationContext
+}
+
+func BuildMetadata(ctx BuildContext) Metadata {
+	metadata := ctx.Resolved.Metadata()
+	sourceLocationID, sourceLocation := sourceLocation(ctx.Bundle)
+	return Metadata{
+		SchemaVersion:    SchemaVersion,
+		RunID:            metadata.RunID,
+		ReportID:         metadata.ReportID,
+		Variant:          variantForReport(metadata.ReportID),
+		PromptID:         metadata.PromptID,
+		GeneratedAt:      metadata.GeneratedAt,
+		Units:            ctx.Units,
+		Timezone:         ctx.Timezone,
+		ValidPeriod:      metadata.ValidPeriod,
+		Location:         copyLocation(ctx.Location),
+		SourceLocationID: sourceLocationID,
+		SourceLocation:   sourceLocation,
+		Sources:          sourceMetadata(ctx.Bundle),
+		SourceWarnings:   sourceWarnings(ctx.Bundle),
+		Alerts:           alertStatus(ctx.Bundle),
+	}
+}
+
+func buildPackage(ctx BuildContext) Package {
+	return Package{
+		Metadata:          BuildMetadata(ctx),
+		CurrentConditions: currentConditions(ctx.Bundle),
+	}
+}
+
+func copyLocation(location *LocationContext) *LocationContext {
+	if location == nil {
+		return nil
+	}
+	copied := *location
+	return &copied
+}
+
+func currentConditions(bundle *forecast.Bundle) *CurrentConditionsContext {
+	if bundle == nil || bundle.Current == nil {
+		return nil
+	}
+	current := bundle.Current
+	context := CurrentConditionsContext{
+		ConditionText:           current.ConditionText,
+		IsDay:                   copyBool(current.IsDay),
+		TemperatureC:            copyFloat(current.TemperatureC),
+		TemperatureF:            copyFloat(current.TemperatureF),
+		ApparentTemperatureC:    copyFloat(current.ApparentTemperatureC),
+		ApparentTemperatureF:    copyFloat(current.ApparentTemperatureF),
+		DewpointC:               copyFloat(current.DewpointC),
+		DewpointF:               copyFloat(current.DewpointF),
+		RelativeHumidityPercent: copyFloat(current.RelativeHumidityPercent),
+		WindSpeedKmh:            copyFloat(current.WindSpeedKmh),
+		WindSpeedMph:            copyFloat(current.WindSpeedMph),
+		WindDirectionDegrees:    copyFloat(current.WindDirectionDegrees),
+	}
+	if context.ConditionText == "" &&
+		context.IsDay == nil &&
+		context.TemperatureC == nil &&
+		context.TemperatureF == nil &&
+		context.ApparentTemperatureC == nil &&
+		context.ApparentTemperatureF == nil &&
+		context.DewpointC == nil &&
+		context.DewpointF == nil &&
+		context.RelativeHumidityPercent == nil &&
+		context.WindSpeedKmh == nil &&
+		context.WindSpeedMph == nil &&
+		context.WindDirectionDegrees == nil {
+		return nil
+	}
+	return &context
+}
+
+func copyBool(value *bool) *bool {
+	if value == nil {
+		return nil
+	}
+	copied := *value
+	return &copied
+}
+
+func copyFloat(value *float64) *float64 {
+	if value == nil {
+		return nil
+	}
+	copied := *value
+	return &copied
+}
+
+func Save(path string, pkg Package) error {
+	if err := fileutil.WriteJSONAtomic(path, pkg); err != nil {
+		return fmt.Errorf("save briefing package: %w", err)
+	}
+	return nil
+}
+
+func sourceLocation(bundle *forecast.Bundle) (string, string) {
+	if bundle == nil {
+		return "", ""
+	}
+	for _, run := range []*forecast.ForecastRun{bundle.Hourly, bundle.Narrative, bundle.Daily} {
+		if run == nil {
+			continue
+		}
+		if run.LocationID != "" || run.LocationName != "" {
+			return run.LocationID, run.LocationName
+		}
+	}
+	return "", ""
+}
+
+func sourceMetadata(bundle *forecast.Bundle) []SourceMetadata {
+	if bundle == nil {
+		return nil
+	}
+	out := make([]SourceMetadata, 0, len(bundle.Sources))
+	for _, source := range bundle.Sources {
+		out = append(out, SourceMetadata{
+			Name:       source.Name,
+			Endpoint:   source.Endpoint,
+			FetchedAt:  source.FetchedAt,
+			IssuedAt:   source.IssuedAt,
+			UpdatedAt:  source.UpdatedAt,
+			DataSHA256: source.DataSHA256,
+			Missing:    source.Missing,
+			Warnings:   source.Warnings,
+		})
+	}
+	return out
+}
+
+func sourceWarnings(bundle *forecast.Bundle) []forecast.SourceWarning {
+	if bundle == nil {
+		return nil
+	}
+	return bundle.Warnings
+}
+
+func alertStatus(bundle *forecast.Bundle) *AlertStatus {
+	if bundle == nil {
+		return nil
+	}
+	status := &AlertStatus{}
+	if bundle.Alerts != nil {
+		status.Checked = true
+		status.ActiveCount = len(bundle.Alerts.Alerts)
+	}
+	for _, source := range bundle.Sources {
+		if source.Name == "alerts" && source.Missing {
+			status.Missing = true
+			break
+		}
+	}
+	if !status.Checked && !status.Missing {
+		return nil
+	}
+	return status
+}
+
+func setRelevantAlertCount(metadata *Metadata, count int) {
+	if metadata.Alerts == nil {
+		if count == 0 {
+			return
+		}
+		metadata.Alerts = &AlertStatus{}
+	}
+	metadata.Alerts.RelevantCount = count
+}
+
+func variantForReport(id report.ID) string {
+	switch id {
+	case report.DailyToday:
+		return "today"
+	case report.DailyTomorrow:
+		return "tomorrow"
+	default:
+		return ""
+	}
+}

internal/briefing/storm.go

@@ -0,0 +1,201 @@
+package briefing
+
+import (
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+type Storm struct {
+	TimingWindow        timeutil.Period           `json:"timingWindow"`
+	EventHeadlines      []string                  `json:"eventHeadlines,omitempty"`
+	Hazards             []string                  `json:"hazards,omitempty"`
+	MostLikelyScenario  []string                  `json:"mostLikelyScenario,omitempty"`
+	ReasonableWorstCase []string                  `json:"reasonableWorstCase,omitempty"`
+	ConfidenceInputs    []string                  `json:"confidenceInputs,omitempty"`
+	WhatToWatchNext     []string                  `json:"whatToWatchNext,omitempty"`
+	RelevantAlerts      []forecast.AlertOverlap   `json:"relevantAlerts,omitempty"`
+	HourlyPeriods       []forecast.ForecastPeriod `json:"hourlyPeriods,omitempty"`
+	DailyPeriods        []forecast.ForecastPeriod `json:"dailyPeriods,omitempty"`
+	NarrativePeriods    []forecast.ForecastPeriod `json:"narrativePeriods,omitempty"`
+	WindowSummary       forecast.DaypartSummary   `json:"windowSummary"`
+	Discussion          DiscussionContext         `json:"discussion,omitempty"`
+	WeatherStory        *WeatherStoryContext      `json:"weatherStory,omitempty"`
+}
+
+func BuildStorm(ctx BuildContext) (Package, error) {
+	if ctx.Resolved.Definition.ID != report.Storm {
+		return Package{}, fmt.Errorf("storm briefing requires a storm report definition")
+	}
+	if ctx.Bundle == nil {
+		return Package{}, fmt.Errorf("forecast bundle is required")
+	}
+	period := ctx.Resolved.ValidPeriod
+	hourly := forecast.SelectHourlyPeriods(ctx.Bundle.Hourly, period)
+	narrative := forecast.SelectNarrativePeriods(ctx.Bundle, period)
+	daily := forecast.SelectHourlyPeriods(ctx.Bundle.Daily, period)
+	alerts := forecast.AlertOverlaps(ctx.Bundle.Alerts, period)
+	summary := forecast.SummarizeDaypart("storm window", period, hourly)
+	summary.AlertOverlaps = alerts
+
+	storm := &Storm{
+		TimingWindow:        period,
+		EventHeadlines:      stormHeadlines(alerts),
+		Hazards:             stormHazards(alerts, summary),
+		MostLikelyScenario:  mostLikelyStormScenario(hourly, narrative, summary),
+		ReasonableWorstCase: reasonableWorstCase(alerts, summary),
+		ConfidenceInputs:    stormConfidenceInputs(ctx.Bundle),
+		WhatToWatchNext:     stormWatchItems(alerts, summary, ctx.Bundle),
+		RelevantAlerts:      alerts,
+		HourlyPeriods:       hourly,
+		DailyPeriods:        daily,
+		NarrativePeriods:    narrative,
+		WindowSummary:       summary,
+		Discussion:          buildDiscussion(ctx.Bundle.Discussion),
+		WeatherStory:        buildWeatherStory(ctx.Bundle),
+	}
+	pkg := buildPackage(ctx)
+	pkg.Storm = storm
+	setRelevantAlertCount(&pkg.Metadata, len(alerts))
+	return pkg, nil
+}
+
+func stormHeadlines(alerts []forecast.AlertOverlap) []string {
+	var headlines []string
+	for _, alert := range alerts {
+		if alert.Headline != "" {
+			headlines = appendUnique(headlines, alert.Headline)
+			continue
+		}
+		if alert.Event != "" {
+			headlines = appendUnique(headlines, alert.Event)
+		}
+	}
+	if len(headlines) == 0 {
+		return []string{"No active alert headline overlaps the selected storm window."}
+	}
+	return headlines
+}
+
+func stormHazards(alerts []forecast.AlertOverlap, summary forecast.DaypartSummary) []string {
+	hazards := map[string]struct{}{}
+	for _, alert := range alerts {
+		if alert.Event != "" {
+			hazards[alert.Event] = struct{}{}
+		}
+	}
+	for _, hazard := range hazardsForIndicators(summary.Indicators) {
+		hazards[hazard] = struct{}{}
+	}
+	if summary.MaxPrecipitationProbability != nil && summary.MaxPrecipitationProbability.Value >= 50 {
+		hazards["precipitation"] = struct{}{}
+	}
+	if summary.PeakWindGust != nil && summary.PeakWindGust.Value >= 30 {
+		hazards["wind"] = struct{}{}
+	}
+	out := sortedSet(hazards)
+	if len(out) == 0 {
+		return []string{"No storm-specific hazard signal stands out in the selected source data."}
+	}
+	return out
+}
+
+func mostLikelyStormScenario(hourly []forecast.ForecastPeriod, narrative []forecast.ForecastPeriod, summary forecast.DaypartSummary) []string {
+	var items []string
+	if summary.DominantCondition != "" {
+		items = append(items, "Dominant hourly condition: "+summary.DominantCondition+".")
+	}
+	if summary.MaxPrecipitationProbability != nil {
+		items = append(items, fmt.Sprintf("Peak precipitation chance is near %.0f%% around %s.", summary.MaxPrecipitationProbability.Value, summary.MaxPrecipitationProbability.Time.Format("15:04")))
+	}
+	if summary.PeakWindGust != nil {
+		items = append(items, fmt.Sprintf("Peak wind gust is near %.0f mph around %s.", summary.PeakWindGust.Value, summary.PeakWindGust.Time.Format("15:04")))
+	}
+	for _, period := range narrative {
+		if period.TextDescription != "" {
+			items = append(items, "Narrative guidance: "+period.TextDescription)
+			break
+		}
+	}
+	if len(items) == 0 && len(hourly) > 0 {
+		items = append(items, "Hourly forecast periods are available, but no focused storm signal is prominent.")
+	}
+	if len(items) == 0 {
+		items = append(items, "No active storm signal is evident from the selected forecast window.")
+	}
+	return items
+}
+
+func reasonableWorstCase(alerts []forecast.AlertOverlap, summary forecast.DaypartSummary) []string {
+	var items []string
+	for _, alert := range alerts {
+		label := alert.Event
+		if label == "" {
+			label = alert.Headline
+		}
+		if label != "" {
+			items = appendUnique(items, "Alert scenario to consider: "+label+".")
+		}
+	}
+	if summary.Indicators.Wind {
+		items = appendUnique(items, "Wind impacts could be higher where stronger gusts occur.")
+	}
+	if summary.Indicators.Snow || summary.Indicators.Ice {
+		items = appendUnique(items, "Wintry precipitation could create travel impacts if it overlaps the event window.")
+	}
+	if len(items) == 0 {
+		items = append(items, "No clear reasonable worst-case signal is represented in the selected data.")
+	}
+	return items
+}
+
+func stormConfidenceInputs(bundle *forecast.Bundle) []string {
+	var items []string
+	if bundle == nil {
+		return []string{"No source bundle was available for confidence context."}
+	}
+	if bundle.Discussion != nil {
+		items = appendUnique(items, bundle.Discussion.KeyMessages...)
+		if bundle.Discussion.ShortTerm != nil && bundle.Discussion.ShortTerm.Text != "" {
+			items = appendUnique(items, "Short-term discussion is available for confidence context.")
+		}
+	}
+	if bundle.WeatherStory != nil {
+		if bundle.WeatherStory.Title != "" {
+			items = appendUnique(items, "Weather story: "+bundle.WeatherStory.Title+".")
+		} else {
+			items = appendUnique(items, "Weather story source is available.")
+		}
+	}
+	for _, warning := range bundle.Warnings {
+		if warning.Code != "" {
+			items = appendUnique(items, "Source warning: "+warning.Code+".")
+		}
+	}
+	if len(items) == 0 {
+		items = append(items, "No explicit confidence or uncertainty signal was available from the selected source context.")
+	}
+	return items
+}
+
+func stormWatchItems(alerts []forecast.AlertOverlap, summary forecast.DaypartSummary, bundle *forecast.Bundle) []string {
+	var items []string
+	if len(alerts) > 0 {
+		items = append(items, "Watch for alert extensions, cancellations, or upgrades.")
+	}
+	if summary.MaxPrecipitationProbability != nil {
+		items = append(items, "Watch precipitation timing and probability trends.")
+	}
+	if summary.PeakWindGust != nil {
+		items = append(items, "Watch wind gust trends.")
+	}
+	if bundle != nil && bundle.Discussion != nil {
+		items = append(items, "Watch the next forecast discussion update for confidence changes.")
+	}
+	if len(items) == 0 {
+		items = append(items, "Watch for new alerts or stronger wording if the weather pattern changes.")
+	}
+	return appendUnique(nil, items...)
+}

internal/briefing/storm_test.go

@@ -0,0 +1,169 @@
+package briefing
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+)
+
+func TestStormBriefingWithActiveAlert(t *testing.T) {
+	location := mustLocation(t)
+	resolved, err := report.Resolve(report.Storm, report.ResolveRequest{
+		Now:        mustParse("2026-05-29T05:00:00-05:00"),
+		Location:   location,
+		StormStart: mustParse("2026-05-29T06:00:00-05:00"),
+		StormEnd:   mustParse("2026-05-29T12:00:00-05:00"),
+	})
+	if err != nil {
+		t.Fatalf("resolve storm: %v", err)
+	}
+	precip := 80.0
+	gust := 42.0
+	bundle := &forecast.Bundle{
+		Hourly: &forecast.ForecastRun{Periods: []forecast.ForecastPeriod{{
+			StartTime:                         mustParse("2026-05-29T07:00:00-05:00"),
+			EndTime:                           mustParse("2026-05-29T08:00:00-05:00"),
+			TextDescription:                   "Severe thunderstorms and gusty wind",
+			ProbabilityOfPrecipitationPercent: &precip,
+			WindGustMph:                       &gust,
+		}}},
+		Daily: &forecast.ForecastRun{Periods: []forecast.ForecastPeriod{{
+			StartTime:       mustParse("2026-05-29T06:00:00-05:00"),
+			EndTime:         mustParse("2026-05-29T18:00:00-05:00"),
+			TextDescription: "Storms likely.",
+		}}},
+		Narrative: &forecast.ForecastRun{Periods: []forecast.ForecastPeriod{{
+			StartTime:       mustParse("2026-05-29T06:00:00-05:00"),
+			EndTime:         mustParse("2026-05-29T18:00:00-05:00"),
+			TextDescription: "Damaging wind possible in stronger storms.",
+		}}},
+		Alerts: &forecast.AlertRun{Alerts: []json.RawMessage{
+			json.RawMessage(`{"event":"Severe Thunderstorm Warning","headline":"Severe storms near Testville","severity":"Severe","effective":"2026-05-29T06:30:00-05:00","expires":"2026-05-29T08:30:00-05:00"}`),
+		}},
+		Discussion: &forecast.Discussion{
+			Product:     "discussion",
+			KeyMessages: []string{"Storms may intensify quickly."},
+			ShortTerm:   &forecast.DiscussionSection{Text: "Short-term storm coverage peaks this morning."},
+			LongTerm:    &forecast.DiscussionSection{Text: "Long-term pattern stays unsettled after the event."},
+		},
+		WeatherStory: &forecast.WeatherStory{
+			OfficeID:    "LSX",
+			StartTime:   mustParse("2026-05-29T06:00:00Z"),
+			EndTime:     mustParse("2026-05-29T18:00:00Z"),
+			Title:       "Storm Risk",
+			Description: "Strong storms are possible.",
+			AltText:     "Weather story graphic showing storm risk.",
+			Order:       1,
+		},
+		Sources: []forecast.Source{{Name: "hourly", FetchedAt: time.Now()}},
+	}
+
+	pkg, err := BuildStorm(BuildContext{Resolved: resolved, Bundle: bundle, Units: "us", Timezone: "America/Chicago"})
+	if err != nil {
+		t.Fatalf("BuildStorm() error = %v", err)
+	}
+
+	if pkg.Metadata.ReportID != report.Storm {
+		t.Fatalf("ReportID = %q, want storm", pkg.Metadata.ReportID)
+	}
+	if pkg.Storm == nil {
+		t.Fatal("Storm = nil")
+	}
+	if len(pkg.Storm.RelevantAlerts) != 1 || len(pkg.Storm.EventHeadlines) != 1 {
+		t.Fatalf("alerts/headlines = %#v/%#v, want alert inputs", pkg.Storm.RelevantAlerts, pkg.Storm.EventHeadlines)
+	}
+	if !pkg.Storm.TimingWindow.Start.Equal(resolved.ValidPeriod.Start) || !pkg.Storm.TimingWindow.End.Equal(resolved.ValidPeriod.End) {
+		t.Fatalf("TimingWindow = %#v, want resolved valid period %#v", pkg.Storm.TimingWindow, resolved.ValidPeriod)
+	}
+	if !strings.Contains(strings.Join(pkg.Storm.Hazards, ","), "Severe Thunderstorm Warning") {
+		t.Fatalf("Hazards = %#v, want alert event", pkg.Storm.Hazards)
+	}
+	if len(pkg.Storm.HourlyPeriods) != 1 || len(pkg.Storm.DailyPeriods) != 1 || len(pkg.Storm.NarrativePeriods) != 1 {
+		t.Fatalf("selected periods hourly/daily/narrative = %d/%d/%d, want selected source periods", len(pkg.Storm.HourlyPeriods), len(pkg.Storm.DailyPeriods), len(pkg.Storm.NarrativePeriods))
+	}
+	if pkg.Storm.WeatherStory == nil {
+		t.Fatal("WeatherStory = nil, want available story context")
+	}
+	if pkg.Storm.WeatherStory.Title != "Storm Risk" || pkg.Storm.WeatherStory.Description != "Strong storms are possible." {
+		t.Fatalf("WeatherStory = %#v, want structured story context", pkg.Storm.WeatherStory)
+	}
+	if pkg.Storm.Discussion.ShortTerm != "Short-term storm coverage peaks this morning." {
+		t.Fatalf("Discussion.ShortTerm = %q, want short-term AFD narrative", pkg.Storm.Discussion.ShortTerm)
+	}
+	if pkg.Storm.Discussion.LongTerm != "Long-term pattern stays unsettled after the event." {
+		t.Fatalf("Discussion.LongTerm = %q, want long-term AFD narrative", pkg.Storm.Discussion.LongTerm)
+	}
+	if len(pkg.Storm.WhatToWatchNext) == 0 {
+		t.Fatal("WhatToWatchNext length = 0, want watch inputs")
+	}
+}
+
+func TestStormBriefingWithDiscussionButNoAlert(t *testing.T) {
+	location := mustLocation(t)
+	resolved, err := report.Resolve(report.Storm, report.ResolveRequest{
+		Now:        mustParse("2026-05-29T05:00:00-05:00"),
+		Location:   location,
+		StormStart: mustParse("2026-05-29T06:00:00-05:00"),
+		StormEnd:   mustParse("2026-05-29T12:00:00-05:00"),
+	})
+	if err != nil {
+		t.Fatalf("resolve storm: %v", err)
+	}
+	bundle := &forecast.Bundle{
+		Hourly:     &forecast.ForecastRun{Periods: []forecast.ForecastPeriod{{StartTime: mustParse("2026-05-29T07:00:00-05:00"), EndTime: mustParse("2026-05-29T08:00:00-05:00"), TextDescription: "Showers"}}},
+		Alerts:     &forecast.AlertRun{},
+		Discussion: &forecast.Discussion{Product: "discussion", KeyMessages: []string{"Confidence is moderate."}},
+		Sources:    []forecast.Source{{Name: "hourly", FetchedAt: time.Now()}},
+	}
+
+	pkg, err := BuildStorm(BuildContext{Resolved: resolved, Bundle: bundle, Units: "us", Timezone: "America/Chicago"})
+	if err != nil {
+		t.Fatalf("BuildStorm() error = %v", err)
+	}
+
+	if len(pkg.Storm.RelevantAlerts) != 0 {
+		t.Fatalf("RelevantAlerts length = %d, want 0", len(pkg.Storm.RelevantAlerts))
+	}
+	if !strings.Contains(strings.Join(pkg.Storm.EventHeadlines, " "), "No active alert") {
+		t.Fatalf("EventHeadlines = %#v, want no-alert fallback", pkg.Storm.EventHeadlines)
+	}
+	if !strings.Contains(strings.Join(pkg.Storm.ConfidenceInputs, " "), "Confidence is moderate") {
+		t.Fatalf("ConfidenceInputs = %#v, want discussion key message", pkg.Storm.ConfidenceInputs)
+	}
+	if len(pkg.Storm.MostLikelyScenario) == 0 {
+		t.Fatal("MostLikelyScenario length = 0, want forecast scenario inputs")
+	}
+}
+
+func TestStormBriefingQuietWindow(t *testing.T) {
+	location := mustLocation(t)
+	resolved, err := report.Resolve(report.Storm, report.ResolveRequest{
+		Now:        mustParse("2026-05-29T05:00:00-05:00"),
+		Location:   location,
+		StormStart: mustParse("2026-05-29T06:00:00-05:00"),
+		StormEnd:   mustParse("2026-05-29T12:00:00-05:00"),
+	})
+	if err != nil {
+		t.Fatalf("resolve storm: %v", err)
+	}
+	bundle := &forecast.Bundle{
+		Hourly:  &forecast.ForecastRun{Periods: []forecast.ForecastPeriod{{StartTime: mustParse("2026-05-29T07:00:00-05:00"), EndTime: mustParse("2026-05-29T08:00:00-05:00"), TextDescription: "Clear"}}},
+		Sources: []forecast.Source{{Name: "hourly", FetchedAt: time.Now()}},
+	}
+
+	pkg, err := BuildStorm(BuildContext{Resolved: resolved, Bundle: bundle, Units: "us", Timezone: "America/Chicago"})
+	if err != nil {
+		t.Fatalf("BuildStorm() error = %v", err)
+	}
+
+	if len(pkg.Storm.Hazards) != 1 || !strings.Contains(pkg.Storm.Hazards[0], "No storm-specific") {
+		t.Fatalf("Hazards = %#v, want quiet hazard fallback", pkg.Storm.Hazards)
+	}
+	if !strings.Contains(strings.Join(pkg.Storm.WhatToWatchNext, " "), "new alerts") {
+		t.Fatalf("WhatToWatchNext = %#v, want watch fallback", pkg.Storm.WhatToWatchNext)
+	}
+}

internal/briefing/three_day.go

@@ -0,0 +1,128 @@
+package briefing
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+type ThreeDay struct {
+	Days           []OutlookDay            `json:"days"`
+	RelevantAlerts []forecast.AlertOverlap `json:"relevantAlerts,omitempty"`
+	Discussion     DiscussionContext       `json:"discussion,omitempty"`
+	WeatherStory   *WeatherStoryContext    `json:"weatherStory,omitempty"`
+}
+
+type OutlookDay struct {
+	Date                        string                    `json:"date"`
+	Period                      timeutil.Period           `json:"period"`
+	OverallCharacter            string                    `json:"overallCharacter"`
+	Temperature                 forecast.Range            `json:"temperature,omitempty"`
+	MaxPrecipitationProbability *forecast.TimedValue      `json:"maxPrecipitationProbability,omitempty"`
+	PeakWindGust                *forecast.TimedValue      `json:"peakWindGust,omitempty"`
+	Risks                       []string                  `json:"risks,omitempty"`
+	OutdoorWindows              OutdoorWindows            `json:"outdoorWindows"`
+	RelevantAlerts              []forecast.AlertOverlap   `json:"relevantAlerts,omitempty"`
+	Dayparts                    []forecast.DaypartSummary `json:"dayparts"`
+}
+
+func BuildThreeDay(ctx BuildContext, summaries []forecast.DailySummary) (Package, error) {
+	if ctx.Resolved.Definition.ID != report.ThreeDay {
+		return Package{}, fmt.Errorf("3-day briefing requires a 3-day report definition")
+	}
+	if len(summaries) == 0 {
+		return Package{}, fmt.Errorf("3-day forecast summaries are required")
+	}
+	pkg := buildPackage(ctx)
+	pkg.ThreeDay = &ThreeDay{
+		Discussion:   buildDiscussion(summaries[0].Discussion),
+		WeatherStory: buildWeatherStory(ctx.Bundle),
+	}
+	for _, summary := range summaries {
+		day := buildOutlookDay(summary)
+		pkg.ThreeDay.Days = append(pkg.ThreeDay.Days, day)
+	}
+	pkg.ThreeDay.RelevantAlerts = collectOutlookAlerts(pkg.ThreeDay.Days)
+	setRelevantAlertCount(&pkg.Metadata, len(pkg.ThreeDay.RelevantAlerts))
+	return pkg, nil
+}
+
+func collectOutlookAlerts(days []OutlookDay) []forecast.AlertOverlap {
+	alerts := map[string]forecast.AlertOverlap{}
+	for _, day := range days {
+		for _, alert := range day.RelevantAlerts {
+			key := alert.Event
+			if key == "" {
+				key = alert.Headline
+			}
+			if key != "" {
+				alerts[key] = alert
+			}
+		}
+	}
+	keys := make([]string, 0, len(alerts))
+	for key := range alerts {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	out := make([]forecast.AlertOverlap, 0, len(keys))
+	for _, key := range keys {
+		out = append(out, alerts[key])
+	}
+	return out
+}
+
+func buildOutlookDay(summary forecast.DailySummary) OutlookDay {
+	day := OutlookDay{
+		Date:           summary.Date,
+		Period:         summary.Period,
+		OutdoorWindows: buildOutdoorWindows(summary.Dayparts),
+		RelevantAlerts: summary.AlertOverlaps,
+		Dayparts:       summary.Dayparts,
+	}
+	conditions := map[string]struct{}{}
+	risks := map[string]struct{}{}
+	for _, daypart := range summary.Dayparts {
+		addRange(&day.Temperature, daypart.Temperature)
+		maxTimedValue(&day.MaxPrecipitationProbability, daypart.MaxPrecipitationProbability)
+		maxTimedValue(&day.PeakWindGust, daypart.PeakWindGust)
+		if daypart.DominantCondition != "" {
+			conditions[daypart.DominantCondition] = struct{}{}
+		}
+		for _, risk := range hazardsForIndicators(daypart.Indicators) {
+			risks[risk] = struct{}{}
+		}
+		if daypart.MaxPrecipitationProbability != nil && daypart.MaxPrecipitationProbability.Value >= 50 {
+			risks["precipitation"] = struct{}{}
+		}
+		if daypart.PeakWindGust != nil && daypart.PeakWindGust.Value >= 30 {
+			risks["wind"] = struct{}{}
+		}
+	}
+	for _, alert := range summary.AlertOverlaps {
+		if alert.Event != "" {
+			risks[alert.Event] = struct{}{}
+		}
+	}
+	day.Risks = sortedSet(risks)
+	day.OverallCharacter = outlookCharacter(sortedSet(conditions), day.Risks)
+	return day
+}
+
+func outlookCharacter(conditions []string, risks []string) string {
+	if len(conditions) == 0 && len(risks) == 0 {
+		return "Quiet weather is expected."
+	}
+	parts := []string{}
+	if len(conditions) > 0 {
+		parts = append(parts, strings.Join(conditions, "; "))
+	}
+	if len(risks) > 0 {
+		parts = append(parts, "risks: "+strings.Join(risks, "; "))
+	}
+	return strings.Join(parts, ". ") + "."
+}

internal/briefing/three_day_test.go

@@ -0,0 +1,94 @@
+package briefing
+
+import (
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+func TestThreeDayBriefingBuildsOutlookDays(t *testing.T) {
+	location := mustLocation(t)
+	resolved, err := report.Resolve(report.ThreeDay, report.ResolveRequest{
+		Now:      mustParse("2026-05-29T06:00:00-05:00"),
+		Location: location,
+	})
+	if err != nil {
+		t.Fatalf("resolve 3-day: %v", err)
+	}
+	precip := 70.0
+	gust := 35.0
+	summaries := []forecast.DailySummary{
+		{
+			Date: "2026-05-29",
+			Period: timeutil.Period{
+				Start: mustParse("2026-05-29T06:00:00-05:00"),
+				End:   mustParse("2026-05-30T00:00:00-05:00"),
+			},
+			Dayparts: []forecast.DaypartSummary{
+				{
+					Name:              "morning",
+					DominantCondition: "Showers and thunderstorms",
+					MaxPrecipitationProbability: &forecast.TimedValue{
+						Value: precip,
+						Time:  mustParse("2026-05-29T09:00:00-05:00"),
+					},
+					PeakWindGust: &forecast.TimedValue{
+						Value: gust,
+						Time:  mustParse("2026-05-29T10:00:00-05:00"),
+					},
+					Indicators: forecast.Indicators{Wind: true},
+				},
+			},
+			AlertOverlaps: []forecast.AlertOverlap{{Event: "Flood Watch"}},
+			Discussion: &forecast.Discussion{
+				Product:     "discussion",
+				KeyMessages: []string{"Unsettled stretch."},
+				ShortTerm:   &forecast.DiscussionSection{Text: "Short-term rain chances remain focused today."},
+				LongTerm:    &forecast.DiscussionSection{Text: "Long-term warmth builds into the weekend."},
+			},
+		},
+		{
+			Date: "2026-05-30",
+			Period: timeutil.Period{
+				Start: mustParse("2026-05-30T00:00:00-05:00"),
+				End:   mustParse("2026-05-31T00:00:00-05:00"),
+			},
+			Dayparts: []forecast.DaypartSummary{{Name: "afternoon", DominantCondition: "Clear"}},
+		},
+	}
+
+	pkg, err := BuildThreeDay(BuildContext{
+		Resolved: resolved,
+		Units:    "us",
+		Timezone: "America/Chicago",
+	}, summaries)
+	if err != nil {
+		t.Fatalf("BuildThreeDay() error = %v", err)
+	}
+
+	if pkg.Metadata.ReportID != report.ThreeDay {
+		t.Fatalf("ReportID = %q, want three_day", pkg.Metadata.ReportID)
+	}
+	if pkg.ThreeDay == nil {
+		t.Fatal("ThreeDay = nil")
+	}
+	if len(pkg.ThreeDay.Days) != 2 {
+		t.Fatalf("Days length = %d, want 2", len(pkg.ThreeDay.Days))
+	}
+	first := pkg.ThreeDay.Days[0]
+	if !strings.Contains(first.OverallCharacter, "Showers") || !strings.Contains(strings.Join(first.Risks, ","), "wind") {
+		t.Fatalf("first day = %#v, want conditions and risks", first)
+	}
+	if len(pkg.ThreeDay.RelevantAlerts) != 1 {
+		t.Fatalf("RelevantAlerts length = %d, want 1", len(pkg.ThreeDay.RelevantAlerts))
+	}
+	if pkg.ThreeDay.Discussion.ShortTerm != "Short-term rain chances remain focused today." {
+		t.Fatalf("Discussion.ShortTerm = %q, want short-term AFD narrative", pkg.ThreeDay.Discussion.ShortTerm)
+	}
+	if pkg.ThreeDay.Discussion.LongTerm != "Long-term warmth builds into the weekend." {
+		t.Fatalf("Discussion.LongTerm = %q, want long-term AFD narrative", pkg.ThreeDay.Discussion.LongTerm)
+	}
+}

internal/briefing/weekend.go

@@ -0,0 +1,121 @@
+package briefing
+
+import (
+	"fmt"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+)
+
+type Weekend struct {
+	Days           []OutlookDay            `json:"days"`
+	Planning       WeekendPlanning         `json:"planning"`
+	RelevantAlerts []forecast.AlertOverlap `json:"relevantAlerts,omitempty"`
+	Discussion     DiscussionContext       `json:"discussion,omitempty"`
+	WeatherStory   *WeatherStoryContext    `json:"weatherStory,omitempty"`
+}
+
+type WeekendPlanning struct {
+	BestOutdoorWindows  []OutdoorWindow `json:"bestOutdoorWindows,omitempty"`
+	WorstWeatherWindows []OutdoorWindow `json:"worstWeatherWindows,omitempty"`
+	RainStormTiming     []string        `json:"rainStormTiming,omitempty"`
+	ComfortConcerns     []string        `json:"comfortConcerns,omitempty"`
+	UncertaintyInputs   []string        `json:"uncertaintyInputs,omitempty"`
+}
+
+func BuildWeekend(ctx BuildContext, summaries []forecast.DailySummary) (Package, error) {
+	if ctx.Resolved.Definition.ID != report.Weekend {
+		return Package{}, fmt.Errorf("weekend briefing requires a weekend report definition")
+	}
+	if len(summaries) == 0 {
+		return Package{}, fmt.Errorf("weekend forecast summaries are required")
+	}
+	pkg := buildPackage(ctx)
+	pkg.Weekend = &Weekend{
+		Discussion:   buildDiscussion(summaries[0].Discussion),
+		WeatherStory: buildWeatherStory(ctx.Bundle),
+	}
+	for _, summary := range summaries {
+		pkg.Weekend.Days = append(pkg.Weekend.Days, buildOutlookDay(summary))
+	}
+	pkg.Weekend.RelevantAlerts = collectOutlookAlerts(pkg.Weekend.Days)
+	setRelevantAlertCount(&pkg.Metadata, len(pkg.Weekend.RelevantAlerts))
+	pkg.Weekend.Planning = buildWeekendPlanning(pkg.Weekend.Days, pkg.Weekend.Discussion, ctx.Bundle)
+	return pkg, nil
+}
+
+func buildWeekendPlanning(days []OutlookDay, discussion DiscussionContext, bundle *forecast.Bundle) WeekendPlanning {
+	planning := WeekendPlanning{}
+	for _, day := range days {
+		if day.OutdoorWindows.Best != nil {
+			window := *day.OutdoorWindows.Best
+			window.Daypart = day.Date + " " + window.Daypart
+			planning.BestOutdoorWindows = append(planning.BestOutdoorWindows, window)
+		}
+		if day.OutdoorWindows.Worst != nil {
+			window := *day.OutdoorWindows.Worst
+			window.Daypart = day.Date + " " + window.Daypart
+			planning.WorstWeatherWindows = append(planning.WorstWeatherWindows, window)
+		}
+		for _, daypart := range day.Dayparts {
+			planning.RainStormTiming = appendUnique(planning.RainStormTiming, weekendRainStormNotes(day.Date, daypart)...)
+			planning.ComfortConcerns = appendUnique(planning.ComfortConcerns, weekendComfortNotes(day.Date, daypart)...)
+		}
+	}
+	planning.UncertaintyInputs = appendUnique(planning.UncertaintyInputs, discussion.KeyMessages...)
+	if discussion.ShortTerm != "" {
+		planning.UncertaintyInputs = appendUnique(planning.UncertaintyInputs, "Short-term discussion available for confidence context.")
+	}
+	if discussion.LongTerm != "" {
+		planning.UncertaintyInputs = appendUnique(planning.UncertaintyInputs, "Long-term discussion available for uncertainty context.")
+	}
+	if bundle != nil {
+		for _, warning := range bundle.Warnings {
+			if warning.Code != "" {
+				planning.UncertaintyInputs = appendUnique(planning.UncertaintyInputs, "Source warning: "+warning.Code+".")
+			}
+		}
+	}
+	if len(planning.RainStormTiming) == 0 {
+		planning.RainStormTiming = append(planning.RainStormTiming, "No focused rain or storm timing stands out in the available weekend forecast.")
+	}
+	if len(planning.ComfortConcerns) == 0 {
+		planning.ComfortConcerns = append(planning.ComfortConcerns, "No major heat, cold, or wind comfort concern stands out in the available weekend forecast.")
+	}
+	if len(planning.UncertaintyInputs) == 0 {
+		planning.UncertaintyInputs = append(planning.UncertaintyInputs, "No explicit confidence or uncertainty signal was available from the selected source context.")
+	}
+	return planning
+}
+
+func weekendRainStormNotes(date string, daypart forecast.DaypartSummary) []string {
+	notes := []string{}
+	label := weekendWindowLabel(date, daypart.Name)
+	if daypart.MaxPrecipitationProbability != nil && daypart.MaxPrecipitationProbability.Value >= 30 {
+		notes = append(notes, fmt.Sprintf("%s precipitation chance peaks near %.0f%%.", label, daypart.MaxPrecipitationProbability.Value))
+	}
+	return notes
+}
+
+func weekendComfortNotes(date string, daypart forecast.DaypartSummary) []string {
+	notes := []string{}
+	label := weekendWindowLabel(date, daypart.Name)
+	if daypart.Indicators.Heat {
+		notes = append(notes, label+" heat may affect outdoor comfort.")
+	}
+	if daypart.Indicators.Cold {
+		notes = append(notes, label+" cold may affect outdoor comfort.")
+	}
+	if daypart.PeakWindGust != nil && daypart.PeakWindGust.Value >= 25 {
+		notes = append(notes, fmt.Sprintf("%s gusts may reach %.0f mph.", label, daypart.PeakWindGust.Value))
+	}
+	return notes
+}
+
+func weekendWindowLabel(date string, daypart string) string {
+	if daypart == "" {
+		return date
+	}
+	return strings.TrimSpace(date + " " + daypart)
+}

internal/briefing/weekend_test.go

@@ -0,0 +1,99 @@
+package briefing
+
+import (
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+func TestWeekendBriefingBuildsPlanningInputs(t *testing.T) {
+	location := mustLocation(t)
+	resolved, err := report.Resolve(report.Weekend, report.ResolveRequest{
+		Now:      mustParse("2026-05-29T08:00:00-05:00"),
+		Location: location,
+	})
+	if err != nil {
+		t.Fatalf("resolve weekend: %v", err)
+	}
+	precip := 70.0
+	gust := 32.0
+	summaries := []forecast.DailySummary{
+		{
+			Date: "2026-05-30",
+			Period: timeutil.Period{
+				Start: mustParse("2026-05-30T00:00:00-05:00"),
+				End:   mustParse("2026-05-31T00:00:00-05:00"),
+			},
+			Dayparts: []forecast.DaypartSummary{
+				{
+					Name:              "afternoon",
+					DominantCondition: "Showers and thunderstorms",
+					Period: timeutil.Period{
+						Start: mustParse("2026-05-30T12:00:00-05:00"),
+						End:   mustParse("2026-05-30T18:00:00-05:00"),
+					},
+					MaxPrecipitationProbability: &forecast.TimedValue{
+						Value: precip,
+						Time:  mustParse("2026-05-30T15:00:00-05:00"),
+					},
+					PeakWindGust: &forecast.TimedValue{
+						Value: gust,
+						Time:  mustParse("2026-05-30T16:00:00-05:00"),
+					},
+					Indicators: forecast.Indicators{Wind: true},
+					HourlyPeriods: []forecast.ForecastPeriod{
+						{
+							StartTime:       mustParse("2026-05-30T15:00:00-05:00"),
+							EndTime:         mustParse("2026-05-30T16:00:00-05:00"),
+							TextDescription: "Showers and thunderstorms",
+						},
+					},
+				},
+			},
+			AlertOverlaps: []forecast.AlertOverlap{{Event: "Flood Watch"}},
+			Discussion: &forecast.Discussion{
+				Product:     "discussion",
+				KeyMessages: []string{"Timing may shift."},
+				ShortTerm:   &forecast.DiscussionSection{Text: "Short-term showers exit before the weekend."},
+				LongTerm:    &forecast.DiscussionSection{Text: "Long-term weekend rain timing remains uncertain."},
+			},
+		},
+	}
+
+	pkg, err := BuildWeekend(BuildContext{
+		Resolved: resolved,
+		Units:    "us",
+		Timezone: "America/Chicago",
+	}, summaries)
+	if err != nil {
+		t.Fatalf("BuildWeekend() error = %v", err)
+	}
+
+	if pkg.Metadata.ReportID != report.Weekend {
+		t.Fatalf("ReportID = %q, want weekend", pkg.Metadata.ReportID)
+	}
+	if pkg.Weekend == nil {
+		t.Fatal("Weekend = nil")
+	}
+	if len(pkg.Weekend.Days) != 1 {
+		t.Fatalf("Days length = %d, want 1", len(pkg.Weekend.Days))
+	}
+	if len(pkg.Weekend.Planning.WorstWeatherWindows) == 0 {
+		t.Fatalf("WorstWeatherWindows = %#v, want weather window", pkg.Weekend.Planning.WorstWeatherWindows)
+	}
+	if !strings.Contains(strings.Join(pkg.Weekend.Planning.RainStormTiming, " "), "precipitation") {
+		t.Fatalf("RainStormTiming = %#v, want precipitation timing", pkg.Weekend.Planning.RainStormTiming)
+	}
+	if len(pkg.Weekend.Planning.UncertaintyInputs) == 0 {
+		t.Fatal("UncertaintyInputs length = 0, want discussion context")
+	}
+	if pkg.Weekend.Discussion.ShortTerm != "Short-term showers exit before the weekend." {
+		t.Fatalf("Discussion.ShortTerm = %q, want short-term AFD narrative", pkg.Weekend.Discussion.ShortTerm)
+	}
+	if pkg.Weekend.Discussion.LongTerm != "Long-term weekend rain timing remains uncertain." {
+		t.Fatalf("Discussion.LongTerm = %q, want long-term AFD narrative", pkg.Weekend.Discussion.LongTerm)
+	}
+}

internal/changes/daily.go

@@ -0,0 +1,199 @@
+// Package changes compares structured briefing snapshots.
+package changes
+
+import (
+	"fmt"
+	"math"
+	"sort"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+)
+
+type Thresholds struct {
+	TemperatureDegrees       float64
+	PrecipProbabilityPoints  int
+	WindGustMilesPerHour     int
+	PrecipTimingShiftMinutes int
+}
+
+type Change struct {
+	Type     string `json:"type"`
+	Message  string `json:"message"`
+	Previous string `json:"previous,omitempty"`
+	Current  string `json:"current,omitempty"`
+}
+
+func CompareDaily(previous briefing.Package, current briefing.Package, thresholds Thresholds) ([]Change, error) {
+	if previous.Daily == nil {
+		return nil, fmt.Errorf("previous daily briefing is required")
+	}
+	if current.Daily == nil {
+		return nil, fmt.Errorf("current daily briefing is required")
+	}
+	var changes []Change
+	changes = append(changes, compareTemperature(previous.Daily.BottomLine.Temperature, current.Daily.BottomLine.Temperature, thresholds.TemperatureDegrees)...)
+	changes = append(changes, comparePrecipitation(previous.Daily.BottomLine.MaxPrecipProbability, current.Daily.BottomLine.MaxPrecipProbability, thresholds)...)
+	changes = append(changes, compareWind(previous.Daily.BottomLine.PeakWindGust, current.Daily.BottomLine.PeakWindGust, float64(thresholds.WindGustMilesPerHour))...)
+	changes = append(changes, compareAlerts(previous.Daily.RelevantAlerts, current.Daily.RelevantAlerts)...)
+	changes = append(changes, compareIndicators(aggregateIndicators(previous.Daily.Dayparts), aggregateIndicators(current.Daily.Dayparts))...)
+	return changes, nil
+}
+
+func compareTemperature(previous forecast.Range, current forecast.Range, threshold float64) []Change {
+	var changes []Change
+	if previous.Min != nil && current.Min != nil && differenceAtLeast(*previous.Min, *current.Min, threshold) {
+		changes = append(changes, Change{
+			Type:     "temperature_shift",
+			Message:  fmt.Sprintf("Low temperature changed from %.0f to %.0f.", *previous.Min, *current.Min),
+			Previous: fmt.Sprintf("%.0f", *previous.Min),
+			Current:  fmt.Sprintf("%.0f", *current.Min),
+		})
+	}
+	if previous.Max != nil && current.Max != nil && differenceAtLeast(*previous.Max, *current.Max, threshold) {
+		changes = append(changes, Change{
+			Type:     "temperature_shift",
+			Message:  fmt.Sprintf("High temperature changed from %.0f to %.0f.", *previous.Max, *current.Max),
+			Previous: fmt.Sprintf("%.0f", *previous.Max),
+			Current:  fmt.Sprintf("%.0f", *current.Max),
+		})
+	}
+	return changes
+}
+
+func comparePrecipitation(previous *forecast.TimedValue, current *forecast.TimedValue, thresholds Thresholds) []Change {
+	if previous == nil || current == nil {
+		return nil
+	}
+	var changes []Change
+	previousCategory := precipitationCategory(previous.Value)
+	currentCategory := precipitationCategory(current.Value)
+	if previousCategory != currentCategory || differenceAtLeast(previous.Value, current.Value, float64(thresholds.PrecipProbabilityPoints)) {
+		changes = append(changes, Change{
+			Type:     "precip_probability_change",
+			Message:  fmt.Sprintf("Peak precipitation chance changed from %.0f%% (%s) to %.0f%% (%s).", previous.Value, previousCategory, current.Value, currentCategory),
+			Previous: fmt.Sprintf("%.0f%% %s", previous.Value, previousCategory),
+			Current:  fmt.Sprintf("%.0f%% %s", current.Value, currentCategory),
+		})
+	}
+	shiftMinutes := int(math.Abs(current.Time.Sub(previous.Time).Minutes()))
+	if thresholds.PrecipTimingShiftMinutes > 0 && shiftMinutes >= thresholds.PrecipTimingShiftMinutes {
+		changes = append(changes, Change{
+			Type:     "precip_timing_shift",
+			Message:  fmt.Sprintf("Peak precipitation timing shifted from %s to %s.", clock(previous.Time), clock(current.Time)),
+			Previous: clock(previous.Time),
+			Current:  clock(current.Time),
+		})
+	}
+	return changes
+}
+
+func compareWind(previous *forecast.TimedValue, current *forecast.TimedValue, threshold float64) []Change {
+	if previous == nil || current == nil || !differenceAtLeast(previous.Value, current.Value, threshold) {
+		return nil
+	}
+	return []Change{{
+		Type:     "wind_gust_change",
+		Message:  fmt.Sprintf("Peak wind gust changed from %.0f mph to %.0f mph.", previous.Value, current.Value),
+		Previous: fmt.Sprintf("%.0f mph", previous.Value),
+		Current:  fmt.Sprintf("%.0f mph", current.Value),
+	}}
+}
+
+func compareAlerts(previous []forecast.AlertOverlap, current []forecast.AlertOverlap) []Change {
+	previousSet := alertSet(previous)
+	currentSet := alertSet(current)
+	var changes []Change
+	for event := range currentSet {
+		if _, ok := previousSet[event]; !ok {
+			changes = append(changes, Change{Type: "alert_added", Message: fmt.Sprintf("Alert added: %s.", event), Current: event})
+		}
+	}
+	for event := range previousSet {
+		if _, ok := currentSet[event]; !ok {
+			changes = append(changes, Change{Type: "alert_removed", Message: fmt.Sprintf("Alert removed: %s.", event), Previous: event})
+		}
+	}
+	sortChanges(changes)
+	return changes
+}
+
+func compareIndicators(previous forecast.Indicators, current forecast.Indicators) []Change {
+	var changes []Change
+	for _, item := range []struct {
+		name     string
+		previous bool
+		current  bool
+	}{
+		{name: "snow", previous: previous.Snow, current: current.Snow},
+		{name: "ice", previous: previous.Ice, current: current.Ice},
+	} {
+		if item.previous == item.current {
+			continue
+		}
+		changeType := item.name + "_risk_change"
+		if item.current {
+			changes = append(changes, Change{Type: changeType, Message: fmt.Sprintf("%s risk is now present.", item.name), Current: "present"})
+		} else {
+			changes = append(changes, Change{Type: changeType, Message: fmt.Sprintf("%s risk is no longer present.", item.name), Previous: "present"})
+		}
+	}
+	return changes
+}
+
+func aggregateIndicators(dayparts []forecast.DaypartSummary) forecast.Indicators {
+	out := forecast.Indicators{}
+	for _, daypart := range dayparts {
+		out.Snow = out.Snow || daypart.Indicators.Snow
+		out.Ice = out.Ice || daypart.Indicators.Ice
+	}
+	return out
+}
+
+func alertSet(alerts []forecast.AlertOverlap) map[string]struct{} {
+	out := map[string]struct{}{}
+	for _, alert := range alerts {
+		event := alert.Event
+		if event == "" {
+			event = alert.Headline
+		}
+		if event != "" {
+			out[event] = struct{}{}
+		}
+	}
+	return out
+}
+
+func precipitationCategory(value float64) string {
+	switch {
+	case value >= 70:
+		return "high"
+	case value >= 50:
+		return "likely"
+	case value >= 20:
+		return "possible"
+	default:
+		return "low"
+	}
+}
+
+func differenceAtLeast(previous float64, current float64, threshold float64) bool {
+	if threshold <= 0 {
+		return previous != current
+	}
+	return math.Abs(current-previous) >= threshold
+}
+
+func clock(t time.Time) string {
+	return t.Format("15:04")
+}
+
+func sortChanges(items []Change) {
+	sort.SliceStable(items, func(i, j int) bool {
+		if items[i].Type == items[j].Type {
+			return items[i].Message < items[j].Message
+		}
+		return items[i].Type < items[j].Type
+	})
+}

internal/changes/daily_test.go

@@ -0,0 +1,123 @@
+package changes
+
+import (
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+)
+
+func TestCompareDailyNoMeaningfulChanges(t *testing.T) {
+	previous := dailyBriefing(60, 70, 30, at("2026-05-29T08:00:00Z"), nil, forecast.Indicators{})
+	current := dailyBriefing(61, 71, 35, at("2026-05-29T08:30:00Z"), nil, forecast.Indicators{})
+
+	changes, err := CompareDaily(previous, current, testThresholds())
+	if err != nil {
+		t.Fatalf("CompareDaily() error = %v", err)
+	}
+	if len(changes) != 0 {
+		t.Fatalf("changes = %#v, want none", changes)
+	}
+}
+
+func TestCompareDailyTemperatureThreshold(t *testing.T) {
+	previous := dailyBriefing(50, 70, 10, at("2026-05-29T08:00:00Z"), nil, forecast.Indicators{})
+	current := dailyBriefing(58, 79, 10, at("2026-05-29T08:00:00Z"), nil, forecast.Indicators{})
+
+	changes, err := CompareDaily(previous, current, testThresholds())
+	if err != nil {
+		t.Fatalf("CompareDaily() error = %v", err)
+	}
+	if countType(changes, "temperature_shift") != 2 {
+		t.Fatalf("changes = %#v, want low and high temperature changes", changes)
+	}
+}
+
+func TestCompareDailyPrecipTimingShift(t *testing.T) {
+	previous := dailyBriefing(60, 70, 60, at("2026-05-29T08:00:00Z"), nil, forecast.Indicators{})
+	current := dailyBriefing(60, 70, 60, at("2026-05-29T11:00:00Z"), nil, forecast.Indicators{})
+
+	changes, err := CompareDaily(previous, current, testThresholds())
+	if err != nil {
+		t.Fatalf("CompareDaily() error = %v", err)
+	}
+	if countType(changes, "precip_timing_shift") != 1 {
+		t.Fatalf("changes = %#v, want timing shift", changes)
+	}
+}
+
+func TestCompareDailyAlertAddedAndRemoved(t *testing.T) {
+	previous := dailyBriefing(60, 70, 10, at("2026-05-29T08:00:00Z"), []string{"Wind Advisory"}, forecast.Indicators{})
+	current := dailyBriefing(60, 70, 10, at("2026-05-29T08:00:00Z"), []string{"Flood Watch"}, forecast.Indicators{})
+
+	changes, err := CompareDaily(previous, current, testThresholds())
+	if err != nil {
+		t.Fatalf("CompareDaily() error = %v", err)
+	}
+	if countType(changes, "alert_added") != 1 || countType(changes, "alert_removed") != 1 {
+		t.Fatalf("changes = %#v, want one alert added and one removed", changes)
+	}
+}
+
+func TestCompareDailyIndicatorChange(t *testing.T) {
+	previous := dailyBriefing(60, 70, 10, at("2026-05-29T08:00:00Z"), nil, forecast.Indicators{})
+	current := dailyBriefing(60, 70, 10, at("2026-05-29T08:00:00Z"), nil, forecast.Indicators{Snow: true})
+
+	changes, err := CompareDaily(previous, current, testThresholds())
+	if err != nil {
+		t.Fatalf("CompareDaily() error = %v", err)
+	}
+	if countType(changes, "snow_risk_change") != 1 {
+		t.Fatalf("changes = %#v, want snow risk change", changes)
+	}
+}
+
+func dailyBriefing(low float64, high float64, precip float64, precipTime time.Time, alerts []string, indicators forecast.Indicators) briefing.Package {
+	alertOverlaps := make([]forecast.AlertOverlap, 0, len(alerts))
+	for _, alert := range alerts {
+		alertOverlaps = append(alertOverlaps, forecast.AlertOverlap{Event: alert})
+	}
+	return briefing.Package{
+		Daily: &briefing.Daily{
+			BottomLine: briefing.BottomLine{
+				Temperature: forecast.Range{Min: &low, Max: &high},
+				MaxPrecipProbability: &forecast.TimedValue{
+					Value: precip,
+					Time:  precipTime,
+				},
+			},
+			RelevantAlerts: alertOverlaps,
+			Dayparts: []forecast.DaypartSummary{
+				{Name: "morning", Indicators: indicators},
+			},
+		},
+	}
+}
+
+func testThresholds() Thresholds {
+	return Thresholds{
+		TemperatureDegrees:       5,
+		PrecipProbabilityPoints:  20,
+		WindGustMilesPerHour:     10,
+		PrecipTimingShiftMinutes: 120,
+	}
+}
+
+func countType(changes []Change, changeType string) int {
+	var count int
+	for _, change := range changes {
+		if change.Type == changeType {
+			count++
+		}
+	}
+	return count
+}
+
+func at(value string) time.Time {
+	parsed, err := time.Parse(time.RFC3339, value)
+	if err != nil {
+		panic(err)
+	}
+	return parsed
+}

internal/changes/three_day.go

@@ -0,0 +1,78 @@
+package changes
+
+import (
+	"fmt"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
+)
+
+func CompareThreeDay(previous briefing.Package, current briefing.Package, thresholds Thresholds) ([]Change, error) {
+	if previous.ThreeDay == nil {
+		return nil, fmt.Errorf("previous 3-day briefing is required")
+	}
+	if current.ThreeDay == nil {
+		return nil, fmt.Errorf("current 3-day briefing is required")
+	}
+	previousDays := outlookDaysByDate(previous.ThreeDay.Days)
+	currentDays := outlookDaysByDate(current.ThreeDay.Days)
+	var changes []Change
+	for date, currentDay := range currentDays {
+		previousDay, ok := previousDays[date]
+		if !ok {
+			changes = append(changes, Change{Type: "outlook_day_added", Message: fmt.Sprintf("Outlook day added: %s.", date), Current: date})
+			continue
+		}
+		changes = append(changes, compareOutlookDay(date, previousDay, currentDay, thresholds)...)
+	}
+	for date := range previousDays {
+		if _, ok := currentDays[date]; !ok {
+			changes = append(changes, Change{Type: "outlook_day_removed", Message: fmt.Sprintf("Outlook day removed: %s.", date), Previous: date})
+		}
+	}
+	sortChanges(changes)
+	return changes, nil
+}
+
+func compareOutlookDay(date string, previous briefing.OutlookDay, current briefing.OutlookDay, thresholds Thresholds) []Change {
+	var changes []Change
+	for _, change := range compareTemperature(previous.Temperature, current.Temperature, thresholds.TemperatureDegrees) {
+		change.Message = date + ": " + change.Message
+		changes = append(changes, change)
+	}
+	for _, change := range comparePrecipitation(previous.MaxPrecipitationProbability, current.MaxPrecipitationProbability, thresholds) {
+		change.Message = date + ": " + change.Message
+		changes = append(changes, change)
+		changes[len(changes)-1].Type = "outlook_" + change.Type
+	}
+	for _, change := range compareWind(previous.PeakWindGust, current.PeakWindGust, float64(thresholds.WindGustMilesPerHour)) {
+		change.Message = date + ": " + change.Message
+		change.Type = "outlook_" + change.Type
+		changes = append(changes, change)
+	}
+	for _, change := range compareAlerts(previous.RelevantAlerts, current.RelevantAlerts) {
+		change.Message = date + ": " + change.Message
+		change.Type = "outlook_" + change.Type
+		changes = append(changes, change)
+	}
+	for _, change := range compareIndicators(aggregateIndicators(previous.Dayparts), aggregateIndicators(current.Dayparts)) {
+		change.Message = date + ": " + change.Message
+		change.Type = "outlook_" + change.Type
+		changes = append(changes, change)
+	}
+	return changes
+}
+
+func outlookDaysByDate(days []briefing.OutlookDay) map[string]briefing.OutlookDay {
+	out := map[string]briefing.OutlookDay{}
+	for _, day := range days {
+		date := day.Date
+		if date == "" && !day.Period.Start.IsZero() {
+			date = day.Period.Start.Format(time.DateOnly)
+		}
+		if date != "" {
+			out[date] = day
+		}
+	}
+	return out
+}

internal/changes/three_day_test.go

@@ -0,0 +1,66 @@
+package changes
+
+import (
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+)
+
+func TestCompareThreeDayDetectsDayChanges(t *testing.T) {
+	previousTemp := 70.0
+	currentTemp := 78.0
+	previousPrecip := 20.0
+	currentPrecip := 70.0
+	previous := briefing.Package{
+		Metadata: briefing.Metadata{ReportID: report.ThreeDay},
+		ThreeDay: &briefing.ThreeDay{Days: []briefing.OutlookDay{{
+			Date:        "2026-05-29",
+			Temperature: forecast.Range{Max: &previousTemp},
+			MaxPrecipitationProbability: &forecast.TimedValue{
+				Value: previousPrecip,
+				Time:  time.Date(2026, 5, 29, 9, 0, 0, 0, time.UTC),
+			},
+		}}},
+	}
+	current := briefing.Package{
+		Metadata: briefing.Metadata{ReportID: report.ThreeDay},
+		ThreeDay: &briefing.ThreeDay{Days: []briefing.OutlookDay{{
+			Date:        "2026-05-29",
+			Temperature: forecast.Range{Max: &currentTemp},
+			MaxPrecipitationProbability: &forecast.TimedValue{
+				Value: currentPrecip,
+				Time:  time.Date(2026, 5, 29, 12, 0, 0, 0, time.UTC),
+			},
+			Dayparts: []forecast.DaypartSummary{{Indicators: forecast.Indicators{Snow: true}}},
+		}}},
+	}
+
+	changes, err := CompareThreeDay(previous, current, Thresholds{
+		TemperatureDegrees:       5,
+		PrecipProbabilityPoints:  20,
+		PrecipTimingShiftMinutes: 120,
+	})
+	if err != nil {
+		t.Fatalf("CompareThreeDay() error = %v", err)
+	}
+
+	if len(changes) == 0 {
+		t.Fatal("changes length = 0, want detected 3-day changes")
+	}
+	var foundPrecip bool
+	var foundSnow bool
+	for _, change := range changes {
+		if change.Type == "outlook_precip_probability_change" {
+			foundPrecip = true
+		}
+		if change.Type == "outlook_snow_risk_change" {
+			foundSnow = true
+		}
+	}
+	if !foundPrecip || !foundSnow {
+		t.Fatalf("changes = %#v, want precipitation and snow changes", changes)
+	}
+}

internal/changes/weekend.go

@@ -0,0 +1,26 @@
+package changes
+
+import (
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
+)
+
+func CompareWeekend(previous briefing.Package, current briefing.Package, thresholds Thresholds) ([]Change, error) {
+	if previous.Weekend == nil {
+		return nil, fmt.Errorf("previous weekend briefing is required")
+	}
+	if current.Weekend == nil {
+		return nil, fmt.Errorf("current weekend briefing is required")
+	}
+	previousOutlook := briefing.Package{ThreeDay: &briefing.ThreeDay{Days: previous.Weekend.Days}}
+	currentOutlook := briefing.Package{ThreeDay: &briefing.ThreeDay{Days: current.Weekend.Days}}
+	changes, err := CompareThreeDay(previousOutlook, currentOutlook, thresholds)
+	if err != nil {
+		return nil, err
+	}
+	for i := range changes {
+		changes[i].Type = "weekend_" + changes[i].Type
+	}
+	return changes, nil
+}

internal/changes/weekend_test.go

@@ -0,0 +1,43 @@
+package changes
+
+import (
+	"testing"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+)
+
+func TestCompareWeekendDetectsOutlookChanges(t *testing.T) {
+	previousTemp := 70.0
+	currentTemp := 78.0
+	previous := briefing.Package{
+		Metadata: briefing.Metadata{ReportID: report.Weekend},
+		Weekend: &briefing.Weekend{Days: []briefing.OutlookDay{{
+			Date:        "2026-05-30",
+			Temperature: forecast.Range{Max: &previousTemp},
+		}}},
+	}
+	current := briefing.Package{
+		Metadata: briefing.Metadata{ReportID: report.Weekend},
+		Weekend: &briefing.Weekend{Days: []briefing.OutlookDay{{
+			Date:        "2026-05-30",
+			Temperature: forecast.Range{Max: &currentTemp},
+			Dayparts:    []forecast.DaypartSummary{{Indicators: forecast.Indicators{Snow: true}}},
+		}}},
+	}
+
+	changes, err := CompareWeekend(previous, current, Thresholds{TemperatureDegrees: 5})
+	if err != nil {
+		t.Fatalf("CompareWeekend() error = %v", err)
+	}
+	if len(changes) == 0 {
+		t.Fatal("changes length = 0, want weekend changes")
+	}
+	for _, change := range changes {
+		if change.Type == "weekend_outlook_snow_risk_change" {
+			return
+		}
+	}
+	t.Fatalf("changes = %#v, want snow risk change", changes)
+}

internal/cli/root.go

@@ -0,0 +1,399 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/app"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+const helpText = `weatherreporter prepares weather reports from normalized forecast data.
+
+Usage:
+  weatherreporter --help
+  weatherreporter generate daily [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--date YYYY-MM-DD]
+  weatherreporter generate tomorrow [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
+  weatherreporter generate three-day [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
+  weatherreporter generate weekend [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
+  weatherreporter generate storm [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] --start TIME --end TIME
+  weatherreporter run morning [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH]
+  weatherreporter run evening [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH]
+  weatherreporter inspect reports [--config PATH] [--limit N]
+  weatherreporter inspect metadata [--config PATH] RUN_ID
+  weatherreporter inspect briefing [--config PATH] RUN_ID
+  weatherreporter inspect data-package [--config PATH] RUN_ID
+  weatherreporter inspect prior [--config PATH] RUN_ID
+  weatherreporter inspect sources [--config PATH] RUN_ID
+
+Options:
+  -h, --help       Show this help message.
+  --config PATH    Load configuration from PATH instead of /usr/local/etc/weatherreporter/config.yml.
+  --units VALUE    Override weather API units.
+  --tz NAME        Override weather API timezone.
+  --out PATH       Write an extra Markdown report copy for generate commands.
+  --out-dir PATH   Write extra Markdown report copies for run commands.
+`
+
+type Runner struct {
+	Clock timeutil.Clock
+}
+
+func Run(ctx context.Context, args []string, stdout io.Writer, stderr io.Writer) error {
+	return Runner{Clock: timeutil.SystemClock{}}.Run(ctx, args, stdout, stderr)
+}
+
+func (r Runner) Run(ctx context.Context, args []string, stdout io.Writer, stderr io.Writer) error {
+	_ = stderr
+	if r.Clock == nil {
+		r.Clock = timeutil.SystemClock{}
+	}
+	if len(args) == 0 || args[0] == "--help" || args[0] == "-h" {
+		_, err := fmt.Fprint(stdout, helpText)
+		return err
+	}
+
+	switch args[0] {
+	case "generate":
+		req, err := r.resolveGenerate(args[1:])
+		if err != nil {
+			return err
+		}
+		return app.Generate(ctx, req)
+	case "run":
+		req, err := r.resolveRun(args[1:])
+		if err != nil {
+			return err
+		}
+		result, err := app.RunBatchDetailed(ctx, req)
+		if result != nil {
+			writeRunLogs(stderr, result)
+			if encodeErr := writeJSON(stdout, result); encodeErr != nil {
+				return encodeErr
+			}
+			if result.Failed > 0 {
+				return app.BatchError{Result: result}
+			}
+		}
+		return err
+	case "inspect":
+		return r.runInspect(ctx, args[1:], stdout)
+	default:
+		return fmt.Errorf("unknown command %q", args[0])
+	}
+}
+
+type commonOptions struct {
+	ConfigPath string
+	Units      string
+	Timezone   string
+	Output     string
+	OutputDir  string
+}
+
+type generateOptions struct {
+	commonOptions
+	Date  string
+	Start string
+	End   string
+}
+
+type inspectOptions struct {
+	ConfigPath string
+	Limit      int
+	RunID      string
+}
+
+type inspectRunCommand struct {
+	Name    string
+	Inspect func(context.Context, app.InspectRunRequest) (any, error)
+}
+
+var inspectRunCommands = []inspectRunCommand{
+	{Name: "metadata", Inspect: func(ctx context.Context, req app.InspectRunRequest) (any, error) {
+		return app.InspectMetadata(ctx, req)
+	}},
+	{Name: "briefing", Inspect: func(ctx context.Context, req app.InspectRunRequest) (any, error) {
+		return app.InspectBriefing(ctx, req)
+	}},
+	{Name: "data-package", Inspect: func(ctx context.Context, req app.InspectRunRequest) (any, error) {
+		return app.InspectDataPackage(ctx, req)
+	}},
+	{Name: "prior", Inspect: func(ctx context.Context, req app.InspectRunRequest) (any, error) {
+		return app.InspectPriorSnapshot(ctx, req)
+	}},
+	{Name: "sources", Inspect: func(ctx context.Context, req app.InspectRunRequest) (any, error) {
+		return app.InspectSources(ctx, req)
+	}},
+}
+
+func (r Runner) runInspect(ctx context.Context, args []string, stdout io.Writer) error {
+	if len(args) == 0 {
+		return fmt.Errorf("inspect requires a command")
+	}
+	command := args[0]
+	switch command {
+	case "reports":
+		opts, err := parseInspectReportsFlags(args[1:])
+		if err != nil {
+			return err
+		}
+		cfg, err := config.Load(config.LoadOptions{Path: opts.ConfigPath})
+		if err != nil {
+			return err
+		}
+		records, err := app.InspectReports(ctx, app.InspectReportsRequest{Config: cfg, Limit: opts.Limit})
+		if err != nil {
+			return err
+		}
+		return writeJSON(stdout, records)
+	default:
+		for _, candidate := range inspectRunCommands {
+			if candidate.Name == command {
+				return runInspectRunCommand(ctx, stdout, candidate, args[1:])
+			}
+		}
+		return fmt.Errorf("unknown inspect command %q", command)
+	}
+}
+
+func runInspectRunCommand(ctx context.Context, stdout io.Writer, command inspectRunCommand, args []string) error {
+	opts, err := parseInspectRunFlags(command.Name, args)
+	if err != nil {
+		return err
+	}
+	cfg, err := config.Load(config.LoadOptions{Path: opts.ConfigPath})
+	if err != nil {
+		return err
+	}
+	value, err := command.Inspect(ctx, app.InspectRunRequest{Config: cfg, RunID: opts.RunID})
+	if err != nil {
+		return err
+	}
+	return writeJSON(stdout, value)
+}
+
+func (r Runner) resolveGenerate(args []string) (app.GenerateRequest, error) {
+	if r.Clock == nil {
+		r.Clock = timeutil.SystemClock{}
+	}
+	if len(args) == 0 {
+		return app.GenerateRequest{}, fmt.Errorf("generate requires a report name")
+	}
+	reportKind, ok := reportKind(args[0])
+	if !ok {
+		return app.GenerateRequest{}, fmt.Errorf("unknown generate report %q", args[0])
+	}
+
+	opts, err := parseGenerateFlags(reportKind, args[1:])
+	if err != nil {
+		return app.GenerateRequest{}, err
+	}
+	cfg, err := config.Load(config.LoadOptions{
+		Path:     opts.ConfigPath,
+		Units:    opts.Units,
+		Timezone: opts.Timezone,
+	})
+	if err != nil {
+		return app.GenerateRequest{}, err
+	}
+	location, err := timeutil.LoadLocation(cfg.WeatherAPI.Timezone)
+	if err != nil {
+		return app.GenerateRequest{}, err
+	}
+
+	req := app.GenerateRequest{
+		Config:     cfg,
+		Report:     reportKind,
+		OutputPath: opts.Output,
+		Now:        r.Clock.Now(),
+	}
+
+	switch reportKind {
+	case app.ReportDaily:
+		if opts.Date == "" {
+			req.Date = timeutil.LocalDate(r.Clock.Now(), location)
+		} else {
+			req.Date, err = timeutil.ParseLocalDate(opts.Date, location)
+			if err != nil {
+				return app.GenerateRequest{}, err
+			}
+		}
+	case app.ReportStorm:
+		if opts.Start == "" {
+			return app.GenerateRequest{}, fmt.Errorf("generate storm requires --start")
+		}
+		if opts.End == "" {
+			return app.GenerateRequest{}, fmt.Errorf("generate storm requires --end")
+		}
+		period, err := report.ParseStormPeriod(opts.Start, opts.End, location)
+		if err != nil {
+			return app.GenerateRequest{}, err
+		}
+		req.StormStart = period.Start
+		req.StormEnd = period.End
+	}
+
+	return req, nil
+}
+
+func (r Runner) resolveRun(args []string) (app.BatchRequest, error) {
+	if r.Clock == nil {
+		r.Clock = timeutil.SystemClock{}
+	}
+	if len(args) == 0 {
+		return app.BatchRequest{}, fmt.Errorf("run requires a batch name")
+	}
+	batch, ok := batchKind(args[0])
+	if !ok {
+		return app.BatchRequest{}, fmt.Errorf("unknown run batch %q", args[0])
+	}
+	opts, err := parseRunFlags(args[1:])
+	if err != nil {
+		return app.BatchRequest{}, err
+	}
+	cfg, err := config.Load(config.LoadOptions{
+		Path:     opts.ConfigPath,
+		Units:    opts.Units,
+		Timezone: opts.Timezone,
+	})
+	if err != nil {
+		return app.BatchRequest{}, err
+	}
+	return app.BatchRequest{Config: cfg, Batch: batch, Now: r.Clock.Now(), OutputDir: opts.OutputDir}, nil
+}
+
+func resolveRun(args []string) (app.BatchRequest, error) {
+	return Runner{Clock: timeutil.SystemClock{}}.resolveRun(args)
+}
+
+func parseGenerateFlags(report app.ReportKind, args []string) (generateOptions, error) {
+	fs := flag.NewFlagSet("generate "+string(report), flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	opts := generateOptions{}
+	addCommonFlags(fs, &opts.commonOptions, true)
+	if report == app.ReportDaily {
+		fs.StringVar(&opts.Date, "date", "", "report date in YYYY-MM-DD")
+	}
+	if report == app.ReportStorm {
+		fs.StringVar(&opts.Start, "start", "", "storm start time")
+		fs.StringVar(&opts.End, "end", "", "storm end time")
+	}
+	if err := fs.Parse(args); err != nil {
+		return generateOptions{}, err
+	}
+	if fs.NArg() > 0 {
+		return generateOptions{}, fmt.Errorf("unexpected argument %q", fs.Arg(0))
+	}
+	return opts, nil
+}
+
+func parseRunFlags(args []string) (commonOptions, error) {
+	fs := flag.NewFlagSet("run", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	opts := commonOptions{}
+	addCommonFlags(fs, &opts, false)
+	fs.StringVar(&opts.OutputDir, "out-dir", "", "extra Markdown report copy directory")
+	if err := fs.Parse(args); err != nil {
+		return commonOptions{}, err
+	}
+	if fs.NArg() > 0 {
+		return commonOptions{}, fmt.Errorf("unexpected argument %q", fs.Arg(0))
+	}
+	return opts, nil
+}
+
+func parseInspectReportsFlags(args []string) (inspectOptions, error) {
+	fs := flag.NewFlagSet("inspect reports", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	opts := inspectOptions{Limit: 20}
+	fs.StringVar(&opts.ConfigPath, "config", "", "configuration file path")
+	fs.IntVar(&opts.Limit, "limit", 20, "maximum reports to list")
+	if err := fs.Parse(args); err != nil {
+		return inspectOptions{}, err
+	}
+	if fs.NArg() > 0 {
+		return inspectOptions{}, fmt.Errorf("unexpected argument %q", fs.Arg(0))
+	}
+	if opts.Limit < 0 {
+		return inspectOptions{}, fmt.Errorf("limit must be zero or greater")
+	}
+	return opts, nil
+}
+
+func parseInspectRunFlags(command string, args []string) (inspectOptions, error) {
+	fs := flag.NewFlagSet("inspect "+command, flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	opts := inspectOptions{}
+	fs.StringVar(&opts.ConfigPath, "config", "", "configuration file path")
+	if err := fs.Parse(args); err != nil {
+		return inspectOptions{}, err
+	}
+	if fs.NArg() != 1 {
+		return inspectOptions{}, fmt.Errorf("inspect %s requires a run id", command)
+	}
+	opts.RunID = fs.Arg(0)
+	return opts, nil
+}
+
+func writeJSON(stdout io.Writer, value any) error {
+	encoder := json.NewEncoder(stdout)
+	encoder.SetIndent("", "  ")
+	return encoder.Encode(value)
+}
+
+func writeRunLogs(stderr io.Writer, result *app.BatchResult) {
+	if stderr == nil || result == nil {
+		return
+	}
+	for _, item := range result.Reports {
+		if item.Status == "failed" {
+			_, _ = fmt.Fprintf(stderr, "report=%s status=failed error=%q\n", item.ReportID, item.Error)
+			continue
+		}
+		_, _ = fmt.Fprintf(stderr, "report=%s status=succeeded output=%q\n", item.ReportID, item.OutputPath)
+	}
+	_, _ = fmt.Fprintf(stderr, "batch=%s total=%d succeeded=%d failed=%d\n", result.Batch, result.Total, result.Succeeded, result.Failed)
+}
+
+func addCommonFlags(fs *flag.FlagSet, opts *commonOptions, includeOutput bool) {
+	fs.StringVar(&opts.ConfigPath, "config", "", "configuration file path")
+	fs.StringVar(&opts.Units, "units", "", "weather API units")
+	fs.StringVar(&opts.Timezone, "tz", "", "weather API timezone")
+	if includeOutput {
+		fs.StringVar(&opts.Output, "out", "", "extra Markdown report copy path")
+	}
+}
+
+func reportKind(value string) (app.ReportKind, bool) {
+	switch value {
+	case string(app.ReportDaily):
+		return app.ReportDaily, true
+	case string(app.ReportTomorrow):
+		return app.ReportTomorrow, true
+	case string(app.ReportThreeDay):
+		return app.ReportThreeDay, true
+	case string(app.ReportWeekend):
+		return app.ReportWeekend, true
+	case string(app.ReportStorm):
+		return app.ReportStorm, true
+	default:
+		return "", false
+	}
+}
+
+func batchKind(value string) (app.BatchKind, bool) {
+	switch value {
+	case string(app.BatchMorning):
+		return app.BatchMorning, true
+	case string(app.BatchEvening):
+		return app.BatchEvening, true
+	default:
+		return "", false
+	}
+}

internal/cli/root_test.go

@@ -0,0 +1,917 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/app"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+func TestRunHelpLongFlag(t *testing.T) {
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+
+	err := Run(context.Background(), []string{"--help"}, &stdout, &stderr)
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+
+	if !strings.Contains(stdout.String(), "generate daily") {
+		t.Fatalf("help output missing generate command:\n%s", stdout.String())
+	}
+}
+
+func TestRunHelpShortFlag(t *testing.T) {
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+
+	err := Run(context.Background(), []string{"-h"}, &stdout, &stderr)
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+
+	if !strings.Contains(stdout.String(), "weatherreporter run evening") {
+		t.Fatalf("help output missing run command:\n%s", stdout.String())
+	}
+}
+
+func TestRunUnknownCommand(t *testing.T) {
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+
+	err := Run(context.Background(), []string{"unknown"}, &stdout, &stderr)
+	if err == nil {
+		t.Fatal("Run() error = nil, want unknown command error")
+	}
+
+	if !strings.Contains(err.Error(), `unknown command "unknown"`) {
+		t.Fatalf("Run() error = %q, want unknown command message", err.Error())
+	}
+}
+
+func TestRunGenerateStormWritesMarkdownReport(t *testing.T) {
+	server := dailyServer(t)
+	tempDir := t.TempDir()
+	scriptoriumPath := writeFakeScriptorium(t, tempDir)
+	workspaceRoot := filepath.Join(tempDir, "workspace")
+	configPath := writeTestConfig(t, server, scriptoriumPath, workspaceRoot)
+	outPath := filepath.Join(tempDir, "storm.md")
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	runner := Runner{Clock: fixedClock()}
+
+	err := runner.Run(context.Background(), []string{
+		"generate", "storm",
+		"--config", configPath,
+		"--start", "2026-05-29T06:00",
+		"--end", "2026-05-29T10:00",
+		"--out", outPath,
+	}, &stdout, &stderr)
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	report, err := os.ReadFile(outPath)
+	if err != nil {
+		t.Fatalf("read report: %v", err)
+	}
+	if !strings.Contains(string(report), "# Daily Report") {
+		t.Fatalf("report output missing markdown:\n%s", string(report))
+	}
+	dataPackagePath := oneArtifact(t, workspaceRoot, "data-packages", "storm", "2026-05-29", "*.data_package.json")
+	data, err := os.ReadFile(dataPackagePath)
+	if err != nil {
+		t.Fatalf("read managed data package: %v", err)
+	}
+	if !strings.Contains(string(data), `"storm"`) || !strings.Contains(string(data), `"weather.storm_report"`) {
+		t.Fatalf("data package output missing storm content:\n%s", string(data))
+	}
+}
+
+func TestRunGenerateTomorrowWritesMarkdownReport(t *testing.T) {
+	server := dailyServer(t)
+	tempDir := t.TempDir()
+	scriptoriumPath := writeFakeScriptorium(t, tempDir)
+	workspaceRoot := filepath.Join(tempDir, "workspace")
+	configPath := writeTestConfig(t, server, scriptoriumPath, workspaceRoot)
+	outPath := filepath.Join(tempDir, "tomorrow.md")
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	runner := Runner{Clock: fixedClock()}
+
+	err := runner.Run(context.Background(), []string{
+		"generate", "tomorrow",
+		"--config", configPath,
+		"--out", outPath,
+	}, &stdout, &stderr)
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	report, err := os.ReadFile(outPath)
+	if err != nil {
+		t.Fatalf("read report: %v", err)
+	}
+	if !strings.Contains(string(report), "# Daily Report") {
+		t.Fatalf("report output missing markdown:\n%s", string(report))
+	}
+	dataPackagePath := oneArtifact(t, workspaceRoot, "data-packages", "daily", "2026-05-30", "*.data_package.json")
+	data, err := os.ReadFile(dataPackagePath)
+	if err != nil {
+		t.Fatalf("read managed data package: %v", err)
+	}
+	if !strings.Contains(string(data), `"daily_tomorrow"`) || !strings.Contains(string(data), `"planning"`) {
+		t.Fatalf("data package output missing tomorrow content:\n%s", string(data))
+	}
+	reportMatches, err := filepath.Glob(filepath.Join(workspaceRoot, "reports", "daily", "*.md"))
+	if err != nil {
+		t.Fatalf("glob managed report: %v", err)
+	}
+	if len(reportMatches) != 1 || !strings.Contains(filepath.Base(reportMatches[0]), "daily_tomorrow") {
+		t.Fatalf("managed reports = %#v, want tomorrow report", reportMatches)
+	}
+}
+
+func TestRunEveningGeneratesTomorrowReport(t *testing.T) {
+	server := dailyServer(t)
+	tempDir := t.TempDir()
+	scriptoriumPath := writeFakeScriptorium(t, tempDir)
+	configPath := filepath.Join(tempDir, "config.yml")
+	workspaceRoot := filepath.Join(tempDir, "workspace")
+	configBody := "weather_api:\n  base_url: " + server.URL + "/\n  timezone: America/Chicago\nscriptorium:\n  binary: " + scriptoriumPath + "\nworkspace:\n  root: " + workspaceRoot + "\n"
+	if err := os.WriteFile(configPath, []byte(configBody), 0o600); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	runner := Runner{Clock: fixedClock()}
+
+	err := runner.Run(context.Background(), []string{
+		"run", "evening",
+		"--config", configPath,
+	}, &stdout, &stderr)
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	dataPackageMatches, err := filepath.Glob(filepath.Join(workspaceRoot, "data-packages", "daily", "2026-05-30", "*.data_package.json"))
+	if err != nil {
+		t.Fatalf("glob data package: %v", err)
+	}
+	if len(dataPackageMatches) != 1 {
+		t.Fatalf("data package files = %#v, want one", dataPackageMatches)
+	}
+	reportMatches, err := filepath.Glob(filepath.Join(workspaceRoot, "reports", "daily", "*.md"))
+	if err != nil {
+		t.Fatalf("glob managed report: %v", err)
+	}
+	if len(reportMatches) != 1 || !strings.Contains(filepath.Base(reportMatches[0]), "daily_tomorrow") {
+		t.Fatalf("managed reports = %#v, want only tomorrow report", reportMatches)
+	}
+}
+
+func TestRunGenerateThreeDayWritesMarkdownReport(t *testing.T) {
+	server := dailyServer(t)
+	tempDir := t.TempDir()
+	scriptoriumPath := writeFakeScriptorium(t, tempDir)
+	configPath := filepath.Join(tempDir, "config.yml")
+	workspaceRoot := filepath.Join(tempDir, "workspace")
+	configBody := "weather_api:\n  base_url: " + server.URL + "/\n  timezone: America/Chicago\nscriptorium:\n  binary: " + scriptoriumPath + "\nworkspace:\n  root: " + workspaceRoot + "\n"
+	if err := os.WriteFile(configPath, []byte(configBody), 0o600); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+	outPath := filepath.Join(tempDir, "three-day.md")
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	runner := Runner{Clock: fixedClock()}
+
+	err := runner.Run(context.Background(), []string{
+		"generate", "three-day",
+		"--config", configPath,
+		"--out", outPath,
+	}, &stdout, &stderr)
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	report, err := os.ReadFile(outPath)
+	if err != nil {
+		t.Fatalf("read report: %v", err)
+	}
+	if !strings.Contains(string(report), "# Daily Report") {
+		t.Fatalf("report output missing markdown:\n%s", string(report))
+	}
+	dataPackageMatches, err := filepath.Glob(filepath.Join(workspaceRoot, "data-packages", "three-day", "2026-05-29", "*.data_package.json"))
+	if err != nil {
+		t.Fatalf("glob data package: %v", err)
+	}
+	if len(dataPackageMatches) != 1 {
+		t.Fatalf("data package files = %#v, want one", dataPackageMatches)
+	}
+	data, err := os.ReadFile(dataPackageMatches[0])
+	if err != nil {
+		t.Fatalf("read managed data package: %v", err)
+	}
+	if !strings.Contains(string(data), `"three_day"`) || !strings.Contains(string(data), `"threeDay"`) {
+		t.Fatalf("data package output missing 3-day content:\n%s", string(data))
+	}
+}
+
+func TestRunGenerateWeekendWritesMarkdownReport(t *testing.T) {
+	server := dailyServer(t)
+	tempDir := t.TempDir()
+	scriptoriumPath := writeFakeScriptorium(t, tempDir)
+	configPath := filepath.Join(tempDir, "config.yml")
+	workspaceRoot := filepath.Join(tempDir, "workspace")
+	configBody := "weather_api:\n  base_url: " + server.URL + "/\n  timezone: America/Chicago\nscriptorium:\n  binary: " + scriptoriumPath + "\nworkspace:\n  root: " + workspaceRoot + "\n"
+	if err := os.WriteFile(configPath, []byte(configBody), 0o600); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+	outPath := filepath.Join(tempDir, "weekend.md")
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	runner := Runner{Clock: fixedClock()}
+
+	err := runner.Run(context.Background(), []string{
+		"generate", "weekend",
+		"--config", configPath,
+		"--out", outPath,
+	}, &stdout, &stderr)
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	report, err := os.ReadFile(outPath)
+	if err != nil {
+		t.Fatalf("read report: %v", err)
+	}
+	if !strings.Contains(string(report), "# Daily Report") {
+		t.Fatalf("report output missing markdown:\n%s", string(report))
+	}
+	dataPackageMatches, err := filepath.Glob(filepath.Join(workspaceRoot, "data-packages", "weekend", "2026-05-29", "*.data_package.json"))
+	if err != nil {
+		t.Fatalf("glob data package: %v", err)
+	}
+	if len(dataPackageMatches) != 1 {
+		t.Fatalf("data package files = %#v, want one", dataPackageMatches)
+	}
+	data, err := os.ReadFile(dataPackageMatches[0])
+	if err != nil {
+		t.Fatalf("read managed data package: %v", err)
+	}
+	if !strings.Contains(string(data), `"weekend"`) || !strings.Contains(string(data), `"planning"`) {
+		t.Fatalf("data package output missing weekend content:\n%s", string(data))
+	}
+}
+
+func TestRunMorningIncludesWeekendExceptSunday(t *testing.T) {
+	server := dailyServer(t)
+	tempDir := t.TempDir()
+	scriptoriumPath := writeFakeScriptorium(t, tempDir)
+	configPath := filepath.Join(tempDir, "config.yml")
+	workspaceRoot := filepath.Join(tempDir, "workspace")
+	configBody := "weather_api:\n  base_url: " + server.URL + "/\n  timezone: America/Chicago\nscriptorium:\n  binary: " + scriptoriumPath + "\nworkspace:\n  root: " + workspaceRoot + "\n"
+	if err := os.WriteFile(configPath, []byte(configBody), 0o600); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	runner := Runner{Clock: fixedClock()}
+
+	err := runner.Run(context.Background(), []string{
+		"run", "morning",
+		"--config", configPath,
+	}, &stdout, &stderr)
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	weekendPackages, err := filepath.Glob(filepath.Join(workspaceRoot, "data-packages", "weekend", "2026-05-29", "*.data_package.json"))
+	if err != nil {
+		t.Fatalf("glob weekend packages: %v", err)
+	}
+	if len(weekendPackages) != 1 {
+		t.Fatalf("weekend packages = %#v, want one", weekendPackages)
+	}
+}
+
+func TestRunMorningReportsPartialFailureAndContinues(t *testing.T) {
+	server := dailyServer(t)
+	tempDir := t.TempDir()
+	scriptoriumPath := writeFailingScriptorium(t, tempDir)
+	configPath := filepath.Join(tempDir, "config.yml")
+	workspaceRoot := filepath.Join(tempDir, "workspace")
+	configBody := "weather_api:\n  base_url: " + server.URL + "/\n  timezone: America/Chicago\nscriptorium:\n  binary: " + scriptoriumPath + "\nworkspace:\n  root: " + workspaceRoot + "\n"
+	if err := os.WriteFile(configPath, []byte(configBody), 0o600); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	runner := Runner{Clock: fixedClock()}
+
+	err := runner.Run(context.Background(), []string{
+		"run", "morning",
+		"--config", configPath,
+	}, &stdout, &stderr)
+	if err == nil {
+		t.Fatal("Run() error = nil, want aggregate failure")
+	}
+	if !strings.Contains(err.Error(), "1 of 3 reports failed") {
+		t.Fatalf("Run() error = %q, want aggregate failure", err.Error())
+	}
+
+	var summary app.BatchResult
+	if decodeErr := json.Unmarshal(stdout.Bytes(), &summary); decodeErr != nil {
+		t.Fatalf("decode summary: %v\n%s", decodeErr, stdout.String())
+	}
+	if summary.Total != 3 || summary.Succeeded != 2 || summary.Failed != 1 {
+		t.Fatalf("summary total/succeeded/failed = %d/%d/%d, want 3/2/1", summary.Total, summary.Succeeded, summary.Failed)
+	}
+	if !strings.Contains(stderr.String(), "status=failed") || !strings.Contains(stderr.String(), "status=succeeded") {
+		t.Fatalf("stderr missing structured report logs:\n%s", stderr.String())
+	}
+	dailyPackages, err := filepath.Glob(filepath.Join(workspaceRoot, "data-packages", "daily", "2026-05-29", "*.data_package.json"))
+	if err != nil {
+		t.Fatalf("glob daily packages: %v", err)
+	}
+	weekendPackages, err := filepath.Glob(filepath.Join(workspaceRoot, "data-packages", "weekend", "2026-05-29", "*.data_package.json"))
+	if err != nil {
+		t.Fatalf("glob weekend packages: %v", err)
+	}
+	if len(dailyPackages) != 1 || len(weekendPackages) != 1 {
+		t.Fatalf("daily packages = %#v, weekend packages = %#v; want successful reports to continue", dailyPackages, weekendPackages)
+	}
+}
+
+func TestRunEveningUsesOutputDirectoryAndSummary(t *testing.T) {
+	server := dailyServer(t)
+	tempDir := t.TempDir()
+	scriptoriumPath := writeFakeScriptorium(t, tempDir)
+	configPath := filepath.Join(tempDir, "config.yml")
+	workspaceRoot := filepath.Join(tempDir, "workspace")
+	outputDir := filepath.Join(tempDir, "copies")
+	configBody := "weather_api:\n  base_url: " + server.URL + "/\n  timezone: America/Chicago\nscriptorium:\n  binary: " + scriptoriumPath + "\nworkspace:\n  root: " + workspaceRoot + "\n"
+	if err := os.WriteFile(configPath, []byte(configBody), 0o600); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	runner := Runner{Clock: fixedClock()}
+
+	err := runner.Run(context.Background(), []string{
+		"run", "evening",
+		"--config", configPath,
+		"--out-dir", outputDir,
+	}, &stdout, &stderr)
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	var summary app.BatchResult
+	if decodeErr := json.Unmarshal(stdout.Bytes(), &summary); decodeErr != nil {
+		t.Fatalf("decode summary: %v\n%s", decodeErr, stdout.String())
+	}
+	if summary.Total != 1 || summary.Failed != 0 {
+		t.Fatalf("summary total/failed = %d/%d, want 1/0", summary.Total, summary.Failed)
+	}
+	if _, err := os.Stat(filepath.Join(outputDir, "tomorrow.md")); err != nil {
+		t.Fatalf("expected copied report: %v", err)
+	}
+	if len(summary.Reports) != 1 || summary.Reports[0].OutputPath != filepath.Join(outputDir, "tomorrow.md") {
+		t.Fatalf("summary reports = %#v, want output path", summary.Reports)
+	}
+}
+
+func TestRunMorningGeneratesDailyAndThreeDayOnSunday(t *testing.T) {
+	server := dailyServer(t)
+	tempDir := t.TempDir()
+	scriptoriumPath := writeFakeScriptorium(t, tempDir)
+	configPath := filepath.Join(tempDir, "config.yml")
+	workspaceRoot := filepath.Join(tempDir, "workspace")
+	configBody := "weather_api:\n  base_url: " + server.URL + "/\n  timezone: America/Chicago\nscriptorium:\n  binary: " + scriptoriumPath + "\nworkspace:\n  root: " + workspaceRoot + "\n"
+	if err := os.WriteFile(configPath, []byte(configBody), 0o600); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	runner := Runner{Clock: timeutil.FixedClock{Time: time.Date(2026, 5, 31, 12, 0, 0, 0, time.UTC)}}
+
+	err := runner.Run(context.Background(), []string{
+		"run", "morning",
+		"--config", configPath,
+	}, &stdout, &stderr)
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	dailyPackages, err := filepath.Glob(filepath.Join(workspaceRoot, "data-packages", "daily", "2026-05-31", "*.data_package.json"))
+	if err != nil {
+		t.Fatalf("glob daily packages: %v", err)
+	}
+	threeDayPackages, err := filepath.Glob(filepath.Join(workspaceRoot, "data-packages", "three-day", "2026-05-31", "*.data_package.json"))
+	if err != nil {
+		t.Fatalf("glob 3-day packages: %v", err)
+	}
+	if len(dailyPackages) != 1 || len(threeDayPackages) != 1 {
+		t.Fatalf("daily packages = %#v, 3-day packages = %#v; want one each", dailyPackages, threeDayPackages)
+	}
+}
+
+func TestRunGenerateDailyWritesMarkdownReport(t *testing.T) {
+	server := dailyServer(t)
+	tempDir := t.TempDir()
+	scriptoriumPath := writeFakeScriptorium(t, tempDir)
+	configPath := filepath.Join(tempDir, "config.yml")
+	workspaceRoot := filepath.Join(tempDir, "workspace")
+	configBody := "weather_api:\n  base_url: " + server.URL + "/\n  timezone: America/Chicago\nscriptorium:\n  binary: " + scriptoriumPath + "\nworkspace:\n  root: " + workspaceRoot + "\n"
+	if err := os.WriteFile(configPath, []byte(configBody), 0o600); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+	outPath := filepath.Join(tempDir, "daily.md")
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	runner := Runner{Clock: fixedClock()}
+
+	err := runner.Run(context.Background(), []string{
+		"generate", "daily",
+		"--config", configPath,
+		"--date", "2026-05-29",
+		"--tz", "UTC",
+		"--out", outPath,
+	}, &stdout, &stderr)
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	report, err := os.ReadFile(outPath)
+	if err != nil {
+		t.Fatalf("read report: %v", err)
+	}
+	if !strings.Contains(string(report), "# Daily Report") {
+		t.Fatalf("report output missing markdown:\n%s", string(report))
+	}
+	dataPackageMatches, err := filepath.Glob(filepath.Join(workspaceRoot, "data-packages", "daily", "2026-05-29", "*.data_package.json"))
+	if err != nil {
+		t.Fatalf("glob data package: %v", err)
+	}
+	if len(dataPackageMatches) != 1 {
+		t.Fatalf("data package files = %#v, want one", dataPackageMatches)
+	}
+	data, err := os.ReadFile(dataPackageMatches[0])
+	if err != nil {
+		t.Fatalf("read managed data package: %v", err)
+	}
+	if !strings.Contains(string(data), `data_package.v1`) || !strings.Contains(string(data), `"daily_today"`) {
+		t.Fatalf("data package output missing expected content:\n%s", string(data))
+	}
+	var decoded struct {
+		Briefing struct {
+			Metadata struct {
+				Location struct {
+					ID       string `json:"id"`
+					Name     string `json:"name"`
+					Region   string `json:"region"`
+					Timezone string `json:"timezone"`
+				} `json:"location"`
+			} `json:"metadata"`
+		} `json:"briefing"`
+	}
+	if err := json.Unmarshal(data, &decoded); err != nil {
+		t.Fatalf("decode data package: %v", err)
+	}
+	if decoded.Briefing.Metadata.Location.ID != "home" || decoded.Briefing.Metadata.Location.Name != "Brentwood" || decoded.Briefing.Metadata.Location.Region != "St. Louis Metro" || decoded.Briefing.Metadata.Location.Timezone != "UTC" {
+		t.Fatalf("location = %#v, want configured location with overridden timezone", decoded.Briefing.Metadata.Location)
+	}
+	preflightMatches, err := filepath.Glob(filepath.Join(workspaceRoot, "preflight", "daily", "2026-05-29", "*.render.json"))
+	if err != nil {
+		t.Fatalf("glob preflight: %v", err)
+	}
+	if len(preflightMatches) != 1 {
+		t.Fatalf("preflight files = %#v, want one render output", preflightMatches)
+	}
+	preflight, err := os.ReadFile(preflightMatches[0])
+	if err != nil {
+		t.Fatalf("read preflight: %v", err)
+	}
+	if !strings.Contains(string(preflight), `ok`) {
+		t.Fatalf("preflight missing fake render output:\n%s", string(preflight))
+	}
+	reportMatches, err := filepath.Glob(filepath.Join(workspaceRoot, "reports", "daily", "*.md"))
+	if err != nil {
+		t.Fatalf("glob managed report: %v", err)
+	}
+	if len(reportMatches) != 1 {
+		t.Fatalf("managed reports = %#v, want one", reportMatches)
+	}
+}
+
+func TestRunInspectGeneratedArtifacts(t *testing.T) {
+	server := dailyServer(t)
+	tempDir := t.TempDir()
+	scriptoriumPath := writeFakeScriptorium(t, tempDir)
+	configPath := filepath.Join(tempDir, "config.yml")
+	workspaceRoot := filepath.Join(tempDir, "workspace")
+	configBody := "weather_api:\n  base_url: " + server.URL + "/\n  timezone: America/Chicago\nscriptorium:\n  binary: " + scriptoriumPath + "\nworkspace:\n  root: " + workspaceRoot + "\n"
+	if err := os.WriteFile(configPath, []byte(configBody), 0o600); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+	runner := Runner{Clock: fixedClock()}
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+
+	err := runner.Run(context.Background(), []string{
+		"generate", "daily",
+		"--config", configPath,
+		"--date", "2026-05-29",
+	}, &stdout, &stderr)
+	if err != nil {
+		t.Fatalf("Run(generate) error = %v", err)
+	}
+	dataPackageMatches, err := filepath.Glob(filepath.Join(workspaceRoot, "data-packages", "daily", "2026-05-29", "*.data_package.json"))
+	if err != nil {
+		t.Fatalf("glob data package: %v", err)
+	}
+	if len(dataPackageMatches) != 1 {
+		t.Fatalf("data package files = %#v, want one", dataPackageMatches)
+	}
+	runID := strings.TrimSuffix(filepath.Base(dataPackageMatches[0]), ".data_package.json")
+
+	stdout.Reset()
+	err = runner.Run(context.Background(), []string{"inspect", "reports", "--config", configPath, "--limit", "1"}, &stdout, &stderr)
+	if err != nil {
+		t.Fatalf("Run(inspect reports) error = %v", err)
+	}
+	if !strings.Contains(stdout.String(), runID) || !strings.Contains(stdout.String(), `"metadataPath"`) {
+		t.Fatalf("inspect reports output missing run:\n%s", stdout.String())
+	}
+
+	for _, command := range []string{"metadata", "briefing", "data-package", "sources"} {
+		stdout.Reset()
+		err = runner.Run(context.Background(), []string{"inspect", command, "--config", configPath, runID}, &stdout, &stderr)
+		if err != nil {
+			t.Fatalf("Run(inspect %s) error = %v", command, err)
+		}
+		if !strings.Contains(stdout.String(), runID) {
+			t.Fatalf("inspect %s output missing run id:\n%s", command, stdout.String())
+		}
+	}
+	if !strings.Contains(stdout.String(), `"warnings"`) {
+		t.Fatalf("inspect sources output missing warnings:\n%s", stdout.String())
+	}
+}
+
+func TestRunInspectMissingMetadata(t *testing.T) {
+	tempDir := t.TempDir()
+	configPath := filepath.Join(tempDir, "config.yml")
+	configBody := "workspace:\n  root: " + filepath.Join(tempDir, "workspace") + "\n"
+	if err := os.WriteFile(configPath, []byte(configBody), 0o600); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	runner := Runner{Clock: fixedClock()}
+
+	err := runner.Run(context.Background(), []string{"inspect", "metadata", "--config", configPath, "missing"}, &stdout, &stderr)
+	if err == nil {
+		t.Fatal("Run(inspect metadata) error = nil, want missing metadata error")
+	}
+	if !strings.Contains(err.Error(), "metadata for run id") {
+		t.Fatalf("error = %q, want missing run id context", err.Error())
+	}
+}
+
+func TestRunInspectRunCommandsParseRunIDAndConfig(t *testing.T) {
+	tempDir := t.TempDir()
+	configPath := filepath.Join(tempDir, "config.yml")
+	configBody := "workspace:\n  root: " + filepath.Join(tempDir, "workspace") + "\n"
+	if err := os.WriteFile(configPath, []byte(configBody), 0o600); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+	runner := Runner{Clock: fixedClock()}
+	commands := []string{"metadata", "briefing", "data-package", "prior", "sources"}
+
+	for _, command := range commands {
+		t.Run(command+" requires run id", func(t *testing.T) {
+			var stdout bytes.Buffer
+			var stderr bytes.Buffer
+
+			err := runner.Run(context.Background(), []string{"inspect", command, "--config", configPath}, &stdout, &stderr)
+			if err == nil {
+				t.Fatal("Run() error = nil, want missing run id error")
+			}
+			if !strings.Contains(err.Error(), "requires a run id") {
+				t.Fatalf("error = %q, want missing run id context", err.Error())
+			}
+		})
+
+		t.Run(command+" accepts config", func(t *testing.T) {
+			var stdout bytes.Buffer
+			var stderr bytes.Buffer
+
+			err := runner.Run(context.Background(), []string{"inspect", command, "--config", configPath, "missing"}, &stdout, &stderr)
+			if err == nil {
+				t.Fatal("Run() error = nil, want missing metadata error")
+			}
+			if !strings.Contains(err.Error(), "metadata for run id") {
+				t.Fatalf("error = %q, want missing metadata context", err.Error())
+			}
+		})
+	}
+}
+
+func TestResolveGenerateCommands(t *testing.T) {
+	runner := Runner{Clock: fixedClock()}
+	tests := []struct {
+		name string
+		args []string
+		want app.ReportKind
+	}{
+		{name: "daily", args: []string{"daily", "--date", "2026-05-29"}, want: app.ReportDaily},
+		{name: "tomorrow", args: []string{"tomorrow"}, want: app.ReportTomorrow},
+		{name: "three-day", args: []string{"three-day"}, want: app.ReportThreeDay},
+		{name: "weekend", args: []string{"weekend"}, want: app.ReportWeekend},
+		{name: "storm", args: []string{"storm", "--start", "2026-05-29T18:00", "--end", "2026-05-30T06:00"}, want: app.ReportStorm},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req, err := runner.resolveGenerate(tt.args)
+			if err != nil {
+				t.Fatalf("resolveGenerate() error = %v", err)
+			}
+			if req.Report != tt.want {
+				t.Fatalf("Report = %q, want %q", req.Report, tt.want)
+			}
+		})
+	}
+}
+
+func TestResolveGenerateDailyDefaultsDateInConfiguredTimezone(t *testing.T) {
+	runner := Runner{Clock: fixedClock()}
+
+	req, err := runner.resolveGenerate([]string{"daily"})
+	if err != nil {
+		t.Fatalf("resolveGenerate() error = %v", err)
+	}
+
+	if got := req.Date.Format(timeutil.DateLayout); got != "2026-05-29" {
+		t.Fatalf("Date = %s, want 2026-05-29", got)
+	}
+}
+
+func TestResolveGenerateAppliesSharedFlags(t *testing.T) {
+	runner := Runner{Clock: fixedClock()}
+
+	req, err := runner.resolveGenerate([]string{"daily", "--units", "metric", "--tz", "UTC", "--out", "./daily.md"})
+	if err != nil {
+		t.Fatalf("resolveGenerate() error = %v", err)
+	}
+
+	if req.Config.WeatherAPI.Units != "metric" {
+		t.Fatalf("Units = %q, want metric", req.Config.WeatherAPI.Units)
+	}
+	if req.Config.WeatherAPI.Timezone != "UTC" {
+		t.Fatalf("Timezone = %q, want UTC", req.Config.WeatherAPI.Timezone)
+	}
+	if req.OutputPath != "./daily.md" {
+		t.Fatalf("OutputPath = %q, want ./daily.md", req.OutputPath)
+	}
+}
+
+func TestResolveGenerateStormRequiresStartAndEnd(t *testing.T) {
+	runner := Runner{Clock: fixedClock()}
+
+	_, err := runner.resolveGenerate([]string{"storm", "--end", "2026-05-29T18:00"})
+	if err == nil {
+		t.Fatal("resolveGenerate() error = nil, want missing start error")
+	}
+	if !strings.Contains(err.Error(), "requires --start") {
+		t.Fatalf("error = %q, want missing start", err.Error())
+	}
+
+	_, err = runner.resolveGenerate([]string{"storm", "--start", "2026-05-29T18:00"})
+	if err == nil {
+		t.Fatal("resolveGenerate() error = nil, want missing end error")
+	}
+	if !strings.Contains(err.Error(), "requires --end") {
+		t.Fatalf("error = %q, want missing end", err.Error())
+	}
+}
+
+func TestResolveGenerateStormParsesLocalTimestamps(t *testing.T) {
+	runner := Runner{Clock: fixedClock()}
+
+	req, err := runner.resolveGenerate([]string{
+		"storm",
+		"--tz", "America/Chicago",
+		"--start", "2026-05-29T18:00",
+		"--end", "2026-05-30T06:00",
+	})
+	if err != nil {
+		t.Fatalf("resolveGenerate() error = %v", err)
+	}
+	if got := req.StormStart.Format(time.RFC3339); got != "2026-05-29T18:00:00-05:00" {
+		t.Fatalf("StormStart = %q, want local Chicago time", got)
+	}
+	if got := req.StormEnd.Format(time.RFC3339); got != "2026-05-30T06:00:00-05:00" {
+		t.Fatalf("StormEnd = %q, want local Chicago time", got)
+	}
+}
+
+func TestResolveGenerateStormParsesRFC3339(t *testing.T) {
+	runner := Runner{Clock: fixedClock()}
+
+	req, err := runner.resolveGenerate([]string{
+		"storm",
+		"--start", "2026-05-29T18:00:00-05:00",
+		"--end", "2026-05-30T06:00:00-05:00",
+	})
+	if err != nil {
+		t.Fatalf("resolveGenerate() error = %v", err)
+	}
+	if !req.StormEnd.After(req.StormStart) {
+		t.Fatalf("StormEnd = %s, want after %s", req.StormEnd, req.StormStart)
+	}
+}
+
+func TestResolveGenerateStormRejectsInvalidBounds(t *testing.T) {
+	runner := Runner{Clock: fixedClock()}
+
+	_, err := runner.resolveGenerate([]string{
+		"storm",
+		"--start", "2026-05-30T06:00",
+		"--end", "2026-05-29T18:00",
+	})
+	if err == nil {
+		t.Fatal("resolveGenerate() error = nil, want invalid bounds error")
+	}
+	if !strings.Contains(err.Error(), "end time after start time") {
+		t.Fatalf("error = %q, want invalid bounds context", err.Error())
+	}
+}
+
+func TestResolveRunCommands(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+		want app.BatchKind
+	}{
+		{name: "morning", args: []string{"morning"}, want: app.BatchMorning},
+		{name: "evening", args: []string{"evening", "--tz", "UTC"}, want: app.BatchEvening},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req, err := resolveRun(tt.args)
+			if err != nil {
+				t.Fatalf("resolveRun() error = %v", err)
+			}
+			if req.Batch != tt.want {
+				t.Fatalf("Batch = %q, want %q", req.Batch, tt.want)
+			}
+		})
+	}
+}
+
+func TestResolveRunRejectsOutputFlag(t *testing.T) {
+	_, err := resolveRun([]string{"morning", "--out", "./report.md"})
+	if err == nil {
+		t.Fatal("resolveRun() error = nil, want flag error")
+	}
+	if !strings.Contains(err.Error(), "flag provided but not defined") {
+		t.Fatalf("error = %q, want undefined flag error", err.Error())
+	}
+}
+
+func TestResolveRunAppliesOutputDirectory(t *testing.T) {
+	req, err := resolveRun([]string{"evening", "--out-dir", "./reports"})
+	if err != nil {
+		t.Fatalf("resolveRun() error = %v", err)
+	}
+	if req.OutputDir != "./reports" {
+		t.Fatalf("OutputDir = %q, want ./reports", req.OutputDir)
+	}
+}
+
+func fixedClock() timeutil.Clock {
+	return timeutil.FixedClock{Time: time.Date(2026, 5, 29, 12, 0, 0, 0, time.UTC)}
+}
+
+func dailyServer(t *testing.T) *httptest.Server {
+	t.Helper()
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/observations":
+			_, _ = w.Write([]byte(`{"data":{"timestamp":"2026-05-29T14:00:00Z","conditionCode":3}}`))
+		case "/conditions/current":
+			_, _ = w.Write([]byte(`{"data":{"conditionText":"Clear"}}`))
+		case "/forecast/hourly":
+			_, _ = w.Write([]byte(`{"data":{"locationId":"test-grid","locationName":"Testville","issuedAt":"2026-05-29T10:30:00-05:00","product":"hourly","periods":[{"startTime":"2026-05-29T06:00:00-05:00","endTime":"2026-05-29T07:00:00-05:00","textDescription":"Showers and thunderstorms","temperatureF":66,"probabilityOfPrecipitationPercent":80,"windGustMph":32},{"startTime":"2026-05-30T06:00:00-05:00","endTime":"2026-05-30T07:00:00-05:00","textDescription":"Showers and thunderstorms","temperatureF":66,"probabilityOfPrecipitationPercent":80,"windGustMph":32}]}}`))
+		case "/forecast/narrative":
+			_, _ = w.Write([]byte(`{"data":{"issuedAt":"2026-05-29T10:30:00-05:00","product":"narrative","periods":[{"startTime":"2026-05-29T06:00:00-05:00","endTime":"2026-05-29T18:00:00-05:00","textDescription":"Morning storms, then partly sunny."},{"startTime":"2026-05-30T06:00:00-05:00","endTime":"2026-05-30T18:00:00-05:00","textDescription":"Tomorrow starts stormy."}]}}`))
+		case "/alerts/active":
+			_, _ = w.Write([]byte(`{"data":{"alerts":[]}}`))
+		case "/discussion":
+			_, _ = w.Write([]byte(`{"data":{"product":"discussion","issuedAt":"2026-05-29T09:25:00-05:00","keyMessages":["Storms are most likely during the morning."]}}`))
+		case "/weatherstories/latest":
+			_, _ = w.Write([]byte(`{"data":{"officeId":"LSX","startTime":"2026-05-30T08:46:00Z","endTime":"2026-05-31T11:00:00Z","updatedAt":"2026-05-30T09:00:34Z","title":"Several Chances for Rain Through Monday","description":"Scattered showers and thunderstorms remain possible.","altText":"Forecast weather story graphic.","priority":false,"order":1,"downloadUrl":"https://api.weather.gov/offices/LSX/weatherstories/download/test"}}`))
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	t.Cleanup(server.Close)
+	return server
+}
+
+func writeTestConfig(t *testing.T, server *httptest.Server, scriptoriumPath string, workspaceRoot string) string {
+	t.Helper()
+	configPath := filepath.Join(t.TempDir(), "config.yml")
+	configBody := "weather_api:\n  base_url: " + server.URL + "/\n  timezone: America/Chicago\nscriptorium:\n  binary: " + scriptoriumPath + "\nworkspace:\n  root: " + workspaceRoot + "\n"
+	if err := os.WriteFile(configPath, []byte(configBody), 0o600); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+	return configPath
+}
+
+func oneArtifact(t *testing.T, root string, parts ...string) string {
+	t.Helper()
+	matches, err := filepath.Glob(filepath.Join(append([]string{root}, parts...)...))
+	if err != nil {
+		t.Fatalf("glob artifact: %v", err)
+	}
+	if len(matches) != 1 {
+		t.Fatalf("artifact matches = %#v, want one", matches)
+	}
+	return matches[0]
+}
+
+func writeFakeScriptorium(t *testing.T, dir string) string {
+	t.Helper()
+	path := filepath.Join(dir, "scriptorium")
+	body := `#!/bin/sh
+if [ "$1" = "render" ]; then
+  printf '{"ok":true,"argv":"%s"}' "$*"
+  exit 0
+fi
+if [ "$1" = "run" ]; then
+  out=""
+  while [ "$#" -gt 0 ]; do
+    if [ "$1" = "--out" ]; then
+      shift
+      out="$1"
+    fi
+    shift
+  done
+  printf '# Daily Report\n\nGenerated by fake scriptorium.\n' > "$out"
+  printf 'wrote report\n' >&2
+  exit 0
+fi
+printf 'unexpected command\n' >&2
+exit 1
+`
+	if err := os.WriteFile(path, []byte(body), 0o700); err != nil {
+		t.Fatalf("write fake scriptorium: %v", err)
+	}
+	return path
+}
+
+func writeFailingScriptorium(t *testing.T, dir string) string {
+	t.Helper()
+	path := filepath.Join(dir, "scriptorium")
+	body := `#!/bin/sh
+if [ "$1" = "render" ]; then
+  prompt=""
+  while [ "$#" -gt 0 ]; do
+    if [ "$1" = "--prompt" ]; then
+      shift
+      prompt="$1"
+    fi
+    shift
+  done
+  if [ "$prompt" = "weather.three_day_outlook" ]; then
+    printf 'render failed\n' >&2
+    exit 1
+  fi
+  printf '{"ok":true,"prompt":"%s"}' "$prompt"
+  exit 0
+fi
+if [ "$1" = "run" ]; then
+  out=""
+  while [ "$#" -gt 0 ]; do
+    if [ "$1" = "--out" ]; then
+      shift
+      out="$1"
+    fi
+    shift
+  done
+  printf '# Batch Report\n\nGenerated by fake scriptorium.\n' > "$out"
+  exit 0
+fi
+printf 'unexpected command\n' >&2
+exit 1
+`
+	if err := os.WriteFile(path, []byte(body), 0o700); err != nil {
+		t.Fatalf("write fake scriptorium: %v", err)
+	}
+	return path
+}

internal/config/config.go

@@ -0,0 +1,72 @@
+// Package config owns application configuration structures, defaults, loading,
+// precedence, and validation.
+package config
+
+import "time"
+
+type MissingSourcePolicy string
+
+const (
+	MissingSourceError MissingSourcePolicy = "error"
+	MissingSourceWarn  MissingSourcePolicy = "warn"
+	MissingSourceNone  MissingSourcePolicy = "none"
+)
+
+type Config struct {
+	WeatherAPI    WeatherAPIConfig    `yaml:"weather_api"`
+	Location      LocationConfig      `yaml:"location"`
+	MissingSource MissingSourceConfig `yaml:"missing_source"`
+	Scriptorium   ScriptoriumConfig   `yaml:"scriptorium"`
+	Workspace     WorkspaceConfig     `yaml:"workspace"`
+	Dayparts      []DaypartConfig     `yaml:"dayparts"`
+	RecentChange  RecentChangeConfig  `yaml:"recent_change"`
+}
+
+type WeatherAPIConfig struct {
+	BaseURL   string        `yaml:"base_url"`
+	Timeout   time.Duration `yaml:"timeout"`
+	Precision int           `yaml:"precision"`
+	Units     string        `yaml:"units"`
+	Timezone  string        `yaml:"timezone"`
+	Format    string        `yaml:"format"`
+}
+
+type LocationConfig struct {
+	ID     string `yaml:"id"`
+	Name   string `yaml:"name"`
+	Region string `yaml:"region"`
+}
+
+type MissingSourceConfig struct {
+	Default MissingSourcePolicy            `yaml:"default"`
+	Sources map[string]MissingSourcePolicy `yaml:"sources"`
+}
+
+type ScriptoriumConfig struct {
+	Binary     string        `yaml:"binary"`
+	ConfigPath string        `yaml:"config_path"`
+	Profile    string        `yaml:"profile"`
+	Timeout    time.Duration `yaml:"timeout"`
+	ExtraArgs  []string      `yaml:"extra_args"`
+}
+
+type WorkspaceConfig struct {
+	Root            string `yaml:"root"`
+	SnapshotsDir    string `yaml:"snapshots_dir"`
+	ReportsDir      string `yaml:"reports_dir"`
+	DataPackagesDir string `yaml:"data_packages_dir"`
+	PreflightDir    string `yaml:"preflight_dir"`
+}
+
+type DaypartConfig struct {
+	Name  string `yaml:"name"`
+	Start string `yaml:"start"`
+	End   string `yaml:"end"`
+}
+
+type RecentChangeConfig struct {
+	TemperatureDegrees       float64 `yaml:"temperature_degrees"`
+	PrecipProbabilityPoints  int     `yaml:"precip_probability_points"`
+	WindGustMilesPerHour     int     `yaml:"wind_gust_miles_per_hour"`
+	PrecipTimingShiftMinutes int     `yaml:"precip_timing_shift_minutes"`
+}

internal/config/config_test.go

@@ -0,0 +1,114 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestDefaults(t *testing.T) {
+	cfg, err := Load(LoadOptions{})
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+
+	if cfg.WeatherAPI.Units != "us" {
+		t.Fatalf("Units = %q, want us", cfg.WeatherAPI.Units)
+	}
+	if cfg.WeatherAPI.Timezone != "America/Chicago" {
+		t.Fatalf("Timezone = %q, want America/Chicago", cfg.WeatherAPI.Timezone)
+	}
+	if cfg.WeatherAPI.Format != "json" {
+		t.Fatalf("Format = %q, want json", cfg.WeatherAPI.Format)
+	}
+	if cfg.Location.ID != "home" || cfg.Location.Name != "Brentwood" || cfg.Location.Region != "St. Louis Metro" {
+		t.Fatalf("Location = %#v, want home/Brentwood/St. Louis Metro", cfg.Location)
+	}
+	if cfg.MissingSource.Default != MissingSourceWarn {
+		t.Fatalf("MissingSource.Default = %q, want warn", cfg.MissingSource.Default)
+	}
+}
+
+func TestLoadExampleConfig(t *testing.T) {
+	cfg, err := LoadFile(filepath.Join("..", "..", "examples", "config.yml"))
+	if err != nil {
+		t.Fatalf("LoadFile() error = %v", err)
+	}
+
+	if cfg.WeatherAPI.BaseURL != "https://weather.api.rakestrawhome.com/" {
+		t.Fatalf("BaseURL = %q, want configured example URL", cfg.WeatherAPI.BaseURL)
+	}
+	if cfg.WeatherAPI.Timeout != 15*time.Second {
+		t.Fatalf("Timeout = %s, want 15s", cfg.WeatherAPI.Timeout)
+	}
+	if cfg.MissingSource.Sources["alerts"] != MissingSourceNone {
+		t.Fatalf("alerts policy = %q, want none", cfg.MissingSource.Sources["alerts"])
+	}
+	if cfg.Location.ID != "home" || cfg.Location.Name != "Brentwood" || cfg.Location.Region != "St. Louis Metro" {
+		t.Fatalf("Location = %#v, want example location", cfg.Location)
+	}
+}
+
+func TestLoadMinimalExampleConfig(t *testing.T) {
+	cfg, err := LoadFile(filepath.Join("..", "..", "examples", "minimal-config.yml"))
+	if err != nil {
+		t.Fatalf("LoadFile() error = %v", err)
+	}
+
+	if cfg.WeatherAPI.BaseURL != "https://weather.api.example.com/" {
+		t.Fatalf("BaseURL = %q, want example URL", cfg.WeatherAPI.BaseURL)
+	}
+	if cfg.WeatherAPI.Units != "us" {
+		t.Fatalf("Units = %q, want default us", cfg.WeatherAPI.Units)
+	}
+	if cfg.Scriptorium.Binary != "scriptorium" {
+		t.Fatalf("Scriptorium.Binary = %q, want default scriptorium", cfg.Scriptorium.Binary)
+	}
+	if cfg.Workspace.Root != "workspace" {
+		t.Fatalf("Workspace.Root = %q, want default workspace", cfg.Workspace.Root)
+	}
+	if cfg.Location.Name != "Brentwood" {
+		t.Fatalf("Location.Name = %q, want default Brentwood", cfg.Location.Name)
+	}
+}
+
+func TestExplicitMissingConfigReturnsError(t *testing.T) {
+	_, err := LoadFile(filepath.Join(t.TempDir(), "missing.yml"))
+	if err == nil {
+		t.Fatal("LoadFile() error = nil, want missing file error")
+	}
+	if !strings.Contains(err.Error(), "read config") {
+		t.Fatalf("error = %q, want read config context", err.Error())
+	}
+}
+
+func TestInvalidConfigProducesActionableError(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.yml")
+	if err := os.WriteFile(path, []byte("missing_source:\n  default: explode\n"), 0o600); err != nil {
+		t.Fatalf("write config fixture: %v", err)
+	}
+
+	_, err := LoadFile(path)
+	if err == nil {
+		t.Fatal("LoadFile() error = nil, want validation error")
+	}
+	if !strings.Contains(err.Error(), "missing_source.default") {
+		t.Fatalf("error = %q, want field path", err.Error())
+	}
+}
+
+func TestLoadAppliesOverrides(t *testing.T) {
+	cfg, err := Load(LoadOptions{Units: "metric", Timezone: "+09:30"})
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+	if cfg.WeatherAPI.Units != "metric" {
+		t.Fatalf("Units = %q, want metric", cfg.WeatherAPI.Units)
+	}
+	if cfg.WeatherAPI.Timezone != "+09:30" {
+		t.Fatalf("Timezone = %q, want +09:30", cfg.WeatherAPI.Timezone)
+	}
+}

internal/config/defaults.go

@@ -0,0 +1,50 @@
+package config
+
+import "time"
+
+const DefaultPath = "/usr/local/etc/weatherreporter/config.yml"
+
+func Defaults() Config {
+	return Config{
+		WeatherAPI: WeatherAPIConfig{
+			Timeout:   10 * time.Second,
+			Precision: 1,
+			Units:     "us",
+			Timezone:  "America/Chicago",
+			Format:    "json",
+		},
+		Location: LocationConfig{
+			ID:     "home",
+			Name:   "Brentwood",
+			Region: "St. Louis Metro",
+		},
+		MissingSource: MissingSourceConfig{
+			Default: MissingSourceWarn,
+			Sources: map[string]MissingSourcePolicy{},
+		},
+		Scriptorium: ScriptoriumConfig{
+			Binary:  "scriptorium",
+			Timeout: 2 * time.Minute,
+		},
+		Workspace: WorkspaceConfig{
+			Root:            "workspace",
+			SnapshotsDir:    "snapshots",
+			ReportsDir:      "reports",
+			DataPackagesDir: "data-packages",
+			PreflightDir:    "preflight",
+		},
+		Dayparts: []DaypartConfig{
+			{Name: "overnight", Start: "00:00", End: "06:00"},
+			{Name: "morning", Start: "06:00", End: "10:00"},
+			{Name: "midday", Start: "10:00", End: "15:00"},
+			{Name: "afternoon", Start: "15:00", End: "17:00"},
+			{Name: "evening", Start: "17:00", End: "24:00"},
+		},
+		RecentChange: RecentChangeConfig{
+			TemperatureDegrees:       5,
+			PrecipProbabilityPoints:  20,
+			WindGustMilesPerHour:     10,
+			PrecipTimingShiftMinutes: 120,
+		},
+	}
+}

internal/config/load.go

@@ -0,0 +1,61 @@
+package config
+
+import (
+	"errors"
+	"fmt"
+	"os"
+
+	"gopkg.in/yaml.v3"
+)
+
+type LoadOptions struct {
+	Path     string
+	Units    string
+	Timezone string
+}
+
+func Load(opts LoadOptions) (Config, error) {
+	cfg := Defaults()
+
+	path := opts.Path
+	if path == "" {
+		path = DefaultPath
+	}
+
+	if err := mergeFile(&cfg, path); err != nil {
+		if opts.Path != "" || !errors.Is(err, os.ErrNotExist) {
+			return Config{}, err
+		}
+	}
+
+	if opts.Units != "" {
+		cfg.WeatherAPI.Units = opts.Units
+	}
+	if opts.Timezone != "" {
+		cfg.WeatherAPI.Timezone = opts.Timezone
+	}
+
+	if err := Validate(cfg); err != nil {
+		return Config{}, err
+	}
+
+	return cfg, nil
+}
+
+func LoadFile(path string) (Config, error) {
+	return Load(LoadOptions{Path: path})
+}
+
+func mergeFile(cfg *Config, path string) error {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return fmt.Errorf("read config %q: %w", path, err)
+	}
+	if err := yaml.Unmarshal(data, cfg); err != nil {
+		return fmt.Errorf("parse config %q: %w", path, err)
+	}
+	if cfg.MissingSource.Sources == nil {
+		cfg.MissingSource.Sources = map[string]MissingSourcePolicy{}
+	}
+	return nil
+}

internal/config/validate.go

@@ -0,0 +1,85 @@
+package config
+
+import (
+	"fmt"
+	"net/url"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+func Validate(cfg Config) error {
+	if cfg.WeatherAPI.BaseURL != "" {
+		parsed, err := url.Parse(cfg.WeatherAPI.BaseURL)
+		if err != nil || parsed.Scheme == "" || parsed.Host == "" {
+			return fmt.Errorf("weather_api.base_url must be an absolute URL")
+		}
+	}
+	if cfg.WeatherAPI.Timeout <= 0 {
+		return fmt.Errorf("weather_api.timeout must be greater than zero")
+	}
+	if cfg.WeatherAPI.Precision < 0 {
+		return fmt.Errorf("weather_api.precision must be zero or greater")
+	}
+	if cfg.WeatherAPI.Units == "" {
+		return fmt.Errorf("weather_api.units is required")
+	}
+	if cfg.WeatherAPI.Timezone == "" {
+		return fmt.Errorf("weather_api.timezone is required")
+	}
+	if _, err := timeutil.LoadLocation(cfg.WeatherAPI.Timezone); err != nil {
+		return fmt.Errorf("weather_api.timezone %q is invalid: %w", cfg.WeatherAPI.Timezone, err)
+	}
+	if cfg.WeatherAPI.Format == "" {
+		return fmt.Errorf("weather_api.format is required")
+	}
+	if cfg.WeatherAPI.Format != "json" {
+		return fmt.Errorf("weather_api.format must be json")
+	}
+
+	if err := validatePolicy("missing_source.default", cfg.MissingSource.Default); err != nil {
+		return err
+	}
+	for source, policy := range cfg.MissingSource.Sources {
+		if strings.TrimSpace(source) == "" {
+			return fmt.Errorf("missing_source.sources contains an empty source name")
+		}
+		if err := validatePolicy("missing_source.sources."+source, policy); err != nil {
+			return err
+		}
+	}
+
+	if cfg.Scriptorium.Binary == "" {
+		return fmt.Errorf("scriptorium.binary is required")
+	}
+	if cfg.Scriptorium.Timeout <= 0 {
+		return fmt.Errorf("scriptorium.timeout must be greater than zero")
+	}
+	if cfg.Workspace.Root == "" {
+		return fmt.Errorf("workspace.root is required")
+	}
+	if len(cfg.Dayparts) == 0 {
+		return fmt.Errorf("dayparts must contain at least one entry")
+	}
+	for i, daypart := range cfg.Dayparts {
+		if strings.TrimSpace(daypart.Name) == "" {
+			return fmt.Errorf("dayparts[%d].name is required", i)
+		}
+		if _, err := timeutil.ParseClock(daypart.Start); err != nil {
+			return fmt.Errorf("dayparts[%d].start is invalid: %w", i, err)
+		}
+		if _, err := timeutil.ParseClock(daypart.End); err != nil {
+			return fmt.Errorf("dayparts[%d].end is invalid: %w", i, err)
+		}
+	}
+	return nil
+}
+
+func validatePolicy(name string, policy MissingSourcePolicy) error {
+	switch policy {
+	case MissingSourceError, MissingSourceWarn, MissingSourceNone:
+		return nil
+	default:
+		return fmt.Errorf("%s must be one of error, warn, or none", name)
+	}
+}

internal/fileutil/fileutil.go

@@ -0,0 +1,48 @@
+// Package fileutil provides narrow filesystem helpers for durable artifacts.
+package fileutil
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+func WriteFileAtomic(path string, data []byte) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return fmt.Errorf("create directory %q: %w", filepath.Dir(path), err)
+	}
+	tmp, err := os.CreateTemp(filepath.Dir(path), "."+filepath.Base(path)+".*.tmp")
+	if err != nil {
+		return fmt.Errorf("create temporary file for %q: %w", path, err)
+	}
+	tmpName := tmp.Name()
+	defer os.Remove(tmpName)
+	if _, err := tmp.Write(data); err != nil {
+		tmp.Close()
+		return fmt.Errorf("write temporary file for %q: %w", path, err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("close temporary file for %q: %w", path, err)
+	}
+	if err := os.Rename(tmpName, path); err != nil {
+		return fmt.Errorf("save %q: %w", path, err)
+	}
+	return nil
+}
+
+func WriteJSONAtomic(path string, value any) error {
+	data, err := json.MarshalIndent(value, "", "  ")
+	if err != nil {
+		return fmt.Errorf("marshal %q: %w", path, err)
+	}
+	return WriteFileAtomic(path, data)
+}
+
+func CopyFileAtomic(source string, target string) error {
+	data, err := os.ReadFile(source)
+	if err != nil {
+		return fmt.Errorf("read %q: %w", source, err)
+	}
+	return WriteFileAtomic(target, data)
+}

internal/fileutil/fileutil_test.go

@@ -0,0 +1,103 @@
+package fileutil
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestWriteFileAtomicCreatesParentDirectory(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "nested", "artifact.txt")
+
+	if err := WriteFileAtomic(path, []byte("artifact")); err != nil {
+		t.Fatalf("WriteFileAtomic() error = %v", err)
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("ReadFile() error = %v", err)
+	}
+	if string(data) != "artifact" {
+		t.Fatalf("data = %q, want artifact", data)
+	}
+}
+
+func TestWriteFileAtomicOverwritesTarget(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "artifact.txt")
+	if err := WriteFileAtomic(path, []byte("old")); err != nil {
+		t.Fatalf("WriteFileAtomic() initial error = %v", err)
+	}
+
+	if err := WriteFileAtomic(path, []byte("new")); err != nil {
+		t.Fatalf("WriteFileAtomic() overwrite error = %v", err)
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("ReadFile() error = %v", err)
+	}
+	if string(data) != "new" {
+		t.Fatalf("data = %q, want new", data)
+	}
+}
+
+func TestWriteFileAtomicCleansTemporaryFileAfterRenameError(t *testing.T) {
+	dir := t.TempDir()
+	target := filepath.Join(dir, "target")
+	if err := os.Mkdir(target, 0o755); err != nil {
+		t.Fatalf("Mkdir() error = %v", err)
+	}
+
+	err := WriteFileAtomic(target, []byte("data"))
+	if err == nil {
+		t.Fatal("WriteFileAtomic() error = nil, want rename error")
+	}
+	if !strings.Contains(err.Error(), "save") {
+		t.Fatalf("error = %q, want save context", err.Error())
+	}
+	matches, err := filepath.Glob(filepath.Join(dir, ".target.*.tmp"))
+	if err != nil {
+		t.Fatalf("Glob() error = %v", err)
+	}
+	if len(matches) != 0 {
+		t.Fatalf("temporary files = %v, want none", matches)
+	}
+}
+
+func TestWriteJSONAtomic(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "artifact.json")
+
+	if err := WriteJSONAtomic(path, map[string]string{"status": "ok"}); err != nil {
+		t.Fatalf("WriteJSONAtomic() error = %v", err)
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("ReadFile() error = %v", err)
+	}
+	if string(data) != "{\n  \"status\": \"ok\"\n}" {
+		t.Fatalf("json = %q, want indented object", data)
+	}
+}
+
+func TestCopyFileAtomic(t *testing.T) {
+	dir := t.TempDir()
+	source := filepath.Join(dir, "source.txt")
+	target := filepath.Join(dir, "nested", "target.txt")
+	if err := os.WriteFile(source, []byte("copied"), 0o600); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+
+	if err := CopyFileAtomic(source, target); err != nil {
+		t.Fatalf("CopyFileAtomic() error = %v", err)
+	}
+
+	data, err := os.ReadFile(target)
+	if err != nil {
+		t.Fatalf("ReadFile() error = %v", err)
+	}
+	if string(data) != "copied" {
+		t.Fatalf("data = %q, want copied", data)
+	}
+}

internal/forecast/bundle.go

@@ -0,0 +1,168 @@
+// Package forecast defines normalized weather data consumed by report builders.
+package forecast
+
+import (
+	"encoding/json"
+	"time"
+)
+
+type Bundle struct {
+	FetchedAt    time.Time       `json:"fetchedAt"`
+	Observation  *Observation    `json:"observation,omitempty"`
+	Current      *Current        `json:"current,omitempty"`
+	Hourly       *ForecastRun    `json:"hourly,omitempty"`
+	Narrative    *ForecastRun    `json:"narrative,omitempty"`
+	Alerts       *AlertRun       `json:"alerts,omitempty"`
+	Discussion   *Discussion     `json:"discussion,omitempty"`
+	Daily        *ForecastRun    `json:"daily,omitempty"`
+	WeatherStory *WeatherStory   `json:"weatherStory,omitempty"`
+	Sources      []Source        `json:"sources"`
+	Warnings     []SourceWarning `json:"warnings,omitempty"`
+}
+
+type Source struct {
+	Name       string            `json:"name"`
+	Endpoint   string            `json:"endpoint,omitempty"`
+	Query      map[string]string `json:"query,omitempty"`
+	FetchedAt  time.Time         `json:"fetchedAt"`
+	IssuedAt   *time.Time        `json:"issuedAt,omitempty"`
+	UpdatedAt  *time.Time        `json:"updatedAt,omitempty"`
+	DataSHA256 string            `json:"dataSha256,omitempty"`
+	Missing    bool              `json:"missing,omitempty"`
+	Warnings   []SourceWarning   `json:"warnings,omitempty"`
+}
+
+type SourceWarning struct {
+	Source             string `json:"source"`
+	Code               string `json:"code"`
+	Severity           string `json:"severity"`
+	Message            string `json:"message"`
+	Endpoint           string `json:"endpoint,omitempty"`
+	CompletenessImpact string `json:"completenessImpact,omitempty"`
+}
+
+type Observation struct {
+	StationID               string            `json:"stationId,omitempty"`
+	StationName             string            `json:"stationName,omitempty"`
+	Timestamp               time.Time         `json:"timestamp"`
+	ConditionCode           *int              `json:"conditionCode,omitempty"`
+	IsDay                   *bool             `json:"isDay,omitempty"`
+	TextDescription         string            `json:"textDescription,omitempty"`
+	TemperatureC            *float64          `json:"temperatureC,omitempty"`
+	TemperatureF            *float64          `json:"temperatureF,omitempty"`
+	DewpointC               *float64          `json:"dewpointC,omitempty"`
+	DewpointF               *float64          `json:"dewpointF,omitempty"`
+	WindSpeedKmh            *float64          `json:"windSpeedKmh,omitempty"`
+	WindSpeedMph            *float64          `json:"windSpeedMph,omitempty"`
+	WindGustKmh             *float64          `json:"windGustKmh,omitempty"`
+	WindGustMph             *float64          `json:"windGustMph,omitempty"`
+	WindDirectionDegrees    *float64          `json:"windDirectionDegrees,omitempty"`
+	BarometricPressurePa    *float64          `json:"barometricPressurePa,omitempty"`
+	BarometricPressureInHg  *float64          `json:"barometricPressureInHg,omitempty"`
+	VisibilityMeters        *float64          `json:"visibilityMeters,omitempty"`
+	VisibilityMiles         *float64          `json:"visibilityMiles,omitempty"`
+	RelativeHumidityPercent *float64          `json:"relativeHumidityPercent,omitempty"`
+	ApparentTemperatureC    *float64          `json:"apparentTemperatureC,omitempty"`
+	ApparentTemperatureF    *float64          `json:"apparentTemperatureF,omitempty"`
+	PresentWeather          []json.RawMessage `json:"presentWeather,omitempty"`
+}
+
+type Current struct {
+	ConditionText           string   `json:"conditionText,omitempty"`
+	IsDay                   *bool    `json:"isDay,omitempty"`
+	RelativeHumidityPercent *float64 `json:"relativeHumidityPercent,omitempty"`
+	WindDirectionDegrees    *float64 `json:"windDirectionDegrees,omitempty"`
+	TemperatureC            *float64 `json:"temperatureC,omitempty"`
+	TemperatureF            *float64 `json:"temperatureF,omitempty"`
+	ApparentTemperatureC    *float64 `json:"apparentTemperatureC,omitempty"`
+	ApparentTemperatureF    *float64 `json:"apparentTemperatureF,omitempty"`
+	DewpointC               *float64 `json:"dewpointC,omitempty"`
+	DewpointF               *float64 `json:"dewpointF,omitempty"`
+	WindSpeedKmh            *float64 `json:"windSpeedKmh,omitempty"`
+	WindSpeedMph            *float64 `json:"windSpeedMph,omitempty"`
+}
+
+type ForecastRun struct {
+	LocationID      string           `json:"locationId,omitempty"`
+	LocationName    string           `json:"locationName,omitempty"`
+	IssuedAt        time.Time        `json:"issuedAt"`
+	UpdatedAt       *time.Time       `json:"updatedAt,omitempty"`
+	Product         string           `json:"product"`
+	Latitude        *float64         `json:"latitude,omitempty"`
+	Longitude       *float64         `json:"longitude,omitempty"`
+	ElevationMeters *float64         `json:"elevationMeters,omitempty"`
+	ElevationFeet   *float64         `json:"elevationFeet,omitempty"`
+	Periods         []ForecastPeriod `json:"periods"`
+}
+
+type ForecastPeriod struct {
+	StartTime                         time.Time `json:"startTime"`
+	EndTime                           time.Time `json:"endTime"`
+	Name                              string    `json:"name,omitempty"`
+	IsDay                             *bool     `json:"isDay,omitempty"`
+	ConditionCode                     *int      `json:"conditionCode,omitempty"`
+	TextDescription                   string    `json:"textDescription,omitempty"`
+	TemperatureC                      *float64  `json:"temperatureC,omitempty"`
+	TemperatureF                      *float64  `json:"temperatureF,omitempty"`
+	TemperatureCMin                   *float64  `json:"temperatureCMin,omitempty"`
+	TemperatureFMin                   *float64  `json:"temperatureFMin,omitempty"`
+	TemperatureCMax                   *float64  `json:"temperatureCMax,omitempty"`
+	TemperatureFMax                   *float64  `json:"temperatureFMax,omitempty"`
+	DewpointC                         *float64  `json:"dewpointC,omitempty"`
+	DewpointF                         *float64  `json:"dewpointF,omitempty"`
+	WindSpeedKmh                      *float64  `json:"windSpeedKmh,omitempty"`
+	WindSpeedMph                      *float64  `json:"windSpeedMph,omitempty"`
+	WindGustKmh                       *float64  `json:"windGustKmh,omitempty"`
+	WindGustMph                       *float64  `json:"windGustMph,omitempty"`
+	WindDirectionDegrees              *float64  `json:"windDirectionDegrees,omitempty"`
+	BarometricPressurePa              *float64  `json:"barometricPressurePa,omitempty"`
+	BarometricPressureInHg            *float64  `json:"barometricPressureInHg,omitempty"`
+	VisibilityMeters                  *float64  `json:"visibilityMeters,omitempty"`
+	VisibilityMiles                   *float64  `json:"visibilityMiles,omitempty"`
+	ApparentTemperatureC              *float64  `json:"apparentTemperatureC,omitempty"`
+	ApparentTemperatureF              *float64  `json:"apparentTemperatureF,omitempty"`
+	CloudCoverPercent                 *float64  `json:"cloudCoverPercent,omitempty"`
+	ProbabilityOfPrecipitationPercent *float64  `json:"probabilityOfPrecipitationPercent,omitempty"`
+	PrecipitationAmountMm             *float64  `json:"precipitationAmountMm,omitempty"`
+	PrecipitationAmountIn             *float64  `json:"precipitationAmountIn,omitempty"`
+	SnowfallDepthMM                   *float64  `json:"snowfallDepthMM,omitempty"`
+	SnowfallDepthIn                   *float64  `json:"snowfallDepthIn,omitempty"`
+	UVIndex                           *float64  `json:"uvIndex,omitempty"`
+	RelativeHumidityPercent           *float64  `json:"relativeHumidityPercent,omitempty"`
+}
+
+type AlertRun struct {
+	AsOf   *time.Time        `json:"asOf,omitempty"`
+	Alerts []json.RawMessage `json:"alerts,omitempty"`
+	Raw    json.RawMessage   `json:"raw,omitempty"`
+}
+
+type Discussion struct {
+	OfficeID    string             `json:"officeId,omitempty"`
+	OfficeName  string             `json:"officeName,omitempty"`
+	Product     string             `json:"product"`
+	IssuedAt    time.Time          `json:"issuedAt"`
+	UpdatedAt   *time.Time         `json:"updatedAt,omitempty"`
+	KeyMessages []string           `json:"keyMessages,omitempty"`
+	ShortTerm   *DiscussionSection `json:"shortTerm,omitempty"`
+	LongTerm    *DiscussionSection `json:"longTerm,omitempty"`
+}
+
+type DiscussionSection struct {
+	Qualifier string     `json:"qualifier,omitempty"`
+	Text      string     `json:"text,omitempty"`
+	IssuedAt  *time.Time `json:"issuedAt,omitempty"`
+}
+
+type WeatherStory struct {
+	OfficeID    string     `json:"officeId,omitempty"`
+	StartTime   time.Time  `json:"startTime"`
+	EndTime     time.Time  `json:"endTime"`
+	UpdatedAt   *time.Time `json:"updatedAt,omitempty"`
+	Title       string     `json:"title,omitempty"`
+	Description string     `json:"description,omitempty"`
+	AltText     string     `json:"altText,omitempty"`
+	Priority    bool       `json:"priority"`
+	Order       int        `json:"order"`
+	DownloadURL string     `json:"downloadUrl,omitempty"`
+}

internal/forecast/dayparts.go

@@ -0,0 +1,53 @@
+package forecast
+
+import (
+	"fmt"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+type DaypartDefinition struct {
+	Name  string `json:"name"`
+	Start string `json:"start"`
+	End   string `json:"end"`
+}
+
+type DaypartWindow struct {
+	Name   string          `json:"name"`
+	Start  time.Time       `json:"start"`
+	End    time.Time       `json:"end"`
+	Period timeutil.Period `json:"period"`
+}
+
+func ResolveDayparts(date time.Time, location *time.Location, definitions []DaypartDefinition) ([]DaypartWindow, error) {
+	if len(definitions) == 0 {
+		return nil, fmt.Errorf("daypart definitions are required")
+	}
+	windows := make([]DaypartWindow, 0, len(definitions))
+	for i, def := range definitions {
+		if def.Name == "" {
+			return nil, fmt.Errorf("daypart[%d].name is required", i)
+		}
+		startClock, err := timeutil.ParseClock(def.Start)
+		if err != nil {
+			return nil, fmt.Errorf("daypart[%d].start: %w", i, err)
+		}
+		endClock, err := timeutil.ParseClock(def.End)
+		if err != nil {
+			return nil, fmt.Errorf("daypart[%d].end: %w", i, err)
+		}
+		period := timeutil.ClockWindow(date, location, startClock, endClock)
+		windows = append(windows, DaypartWindow{
+			Name:   def.Name,
+			Start:  period.Start,
+			End:    period.End,
+			Period: period,
+		})
+	}
+	return windows, nil
+}
+
+func PeriodForForecastPeriod(period ForecastPeriod) timeutil.Period {
+	return timeutil.Period{Start: period.StartTime, End: period.EndTime}
+}

internal/forecast/derive.go

@@ -0,0 +1,437 @@
+package forecast
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+type DailySummary struct {
+	Date             string           `json:"date"`
+	Period           timeutil.Period  `json:"period"`
+	Dayparts         []DaypartSummary `json:"dayparts"`
+	NarrativePeriods []ForecastPeriod `json:"narrativePeriods,omitempty"`
+	AlertOverlaps    []AlertOverlap   `json:"alertOverlaps,omitempty"`
+	Discussion       *Discussion      `json:"discussion,omitempty"`
+	SourceWarnings   []SourceWarning  `json:"sourceWarnings,omitempty"`
+	SourceProvenance []Source         `json:"sourceProvenance,omitempty"`
+}
+
+type DaypartSummary struct {
+	Name                        string           `json:"name"`
+	Period                      timeutil.Period  `json:"period"`
+	HourlyPeriods               []ForecastPeriod `json:"hourlyPeriods"`
+	Temperature                 Range            `json:"temperature,omitempty"`
+	ApparentTemperature         Range            `json:"apparentTemperature,omitempty"`
+	MaxPrecipitationProbability *TimedValue      `json:"maxPrecipitationProbability,omitempty"`
+	PeakWindSpeed               *TimedValue      `json:"peakWindSpeed,omitempty"`
+	PeakWindGust                *TimedValue      `json:"peakWindGust,omitempty"`
+	DominantCondition           string           `json:"dominantCondition,omitempty"`
+	NotableConditions           []string         `json:"notableConditions,omitempty"`
+	Indicators                  Indicators       `json:"indicators"`
+	AlertOverlaps               []AlertOverlap   `json:"alertOverlaps,omitempty"`
+}
+
+type Range struct {
+	Min *float64 `json:"min,omitempty"`
+	Max *float64 `json:"max,omitempty"`
+}
+
+type TimedValue struct {
+	Value float64   `json:"value"`
+	Time  time.Time `json:"time"`
+}
+
+type Indicators struct {
+	Snow bool `json:"snow,omitempty"`
+	Ice  bool `json:"ice,omitempty"`
+	Fog  bool `json:"fog,omitempty"`
+	Heat bool `json:"heat,omitempty"`
+	Cold bool `json:"cold,omitempty"`
+	Wind bool `json:"wind,omitempty"`
+}
+
+type AlertOverlap struct {
+	Event       string          `json:"event,omitempty"`
+	Headline    string          `json:"headline,omitempty"`
+	Severity    string          `json:"severity,omitempty"`
+	Period      timeutil.Period `json:"period"`
+	Overlap     timeutil.Period `json:"overlap"`
+	Description string          `json:"description,omitempty"`
+}
+
+func BuildDailySummary(bundle *Bundle, date time.Time, location *time.Location, dayparts []DaypartDefinition) (*DailySummary, error) {
+	if bundle == nil {
+		return nil, fmt.Errorf("forecast bundle is required")
+	}
+	if location == nil {
+		location = time.UTC
+	}
+	if bundle.Hourly == nil || len(bundle.Hourly.Periods) == 0 {
+		return nil, fmt.Errorf("hourly forecast data is required")
+	}
+	day := timeutil.CivilDay(date, location)
+	windows, err := ResolveDayparts(date, location, dayparts)
+	if err != nil {
+		return nil, err
+	}
+	alerts := AlertOverlaps(bundle.Alerts, day)
+
+	summary := &DailySummary{
+		Date:             day.Start.Format(timeutil.DateLayout),
+		Period:           day,
+		NarrativePeriods: SelectNarrativePeriods(bundle, day),
+		AlertOverlaps:    alerts,
+		Discussion:       SelectDiscussion(bundle),
+		SourceWarnings:   bundle.Warnings,
+		SourceProvenance: bundle.Sources,
+	}
+	for _, window := range windows {
+		periods := SelectHourlyPeriods(bundle.Hourly, window.Period)
+		daypartSummary := SummarizeDaypart(window.Name, window.Period, periods)
+		daypartSummary.AlertOverlaps = overlapsWithin(alerts, window.Period)
+		summary.Dayparts = append(summary.Dayparts, daypartSummary)
+	}
+	return summary, nil
+}
+
+func BuildPeriodDailySummaries(bundle *Bundle, period timeutil.Period, location *time.Location, dayparts []DaypartDefinition) ([]DailySummary, error) {
+	if !period.IsValid() {
+		return nil, fmt.Errorf("valid forecast period is required")
+	}
+	if location == nil {
+		location = time.UTC
+	}
+	var summaries []DailySummary
+	for day := timeutil.CivilDay(period.Start, location); day.Start.Before(period.End); day = timeutil.CivilDay(day.Start.AddDate(0, 0, 1), location) {
+		overlap, ok := day.Intersection(period)
+		if !ok {
+			continue
+		}
+		summary, err := buildDailySummaryForPeriod(bundle, overlap, location, dayparts)
+		if err != nil {
+			return nil, err
+		}
+		summaries = append(summaries, *summary)
+	}
+	return summaries, nil
+}
+
+func buildDailySummaryForPeriod(bundle *Bundle, period timeutil.Period, location *time.Location, dayparts []DaypartDefinition) (*DailySummary, error) {
+	if bundle == nil {
+		return nil, fmt.Errorf("forecast bundle is required")
+	}
+	if bundle.Hourly == nil || len(bundle.Hourly.Periods) == 0 {
+		return nil, fmt.Errorf("hourly forecast data is required")
+	}
+	windows, err := ResolveDayparts(period.Start, location, dayparts)
+	if err != nil {
+		return nil, err
+	}
+	alerts := AlertOverlaps(bundle.Alerts, period)
+	summary := &DailySummary{
+		Date:             period.Start.In(location).Format(timeutil.DateLayout),
+		Period:           period,
+		NarrativePeriods: SelectNarrativePeriods(bundle, period),
+		AlertOverlaps:    alerts,
+		Discussion:       SelectDiscussion(bundle),
+		SourceWarnings:   bundle.Warnings,
+		SourceProvenance: bundle.Sources,
+	}
+	for _, window := range windows {
+		clipped, ok := window.Period.Intersection(period)
+		if !ok {
+			continue
+		}
+		periods := SelectHourlyPeriods(bundle.Hourly, clipped)
+		daypartSummary := SummarizeDaypart(window.Name, clipped, periods)
+		daypartSummary.AlertOverlaps = overlapsWithin(alerts, clipped)
+		summary.Dayparts = append(summary.Dayparts, daypartSummary)
+	}
+	return summary, nil
+}
+
+func SelectHourlyPeriods(run *ForecastRun, period timeutil.Period) []ForecastPeriod {
+	if run == nil {
+		return nil
+	}
+	var selected []ForecastPeriod
+	for _, forecastPeriod := range run.Periods {
+		if PeriodForForecastPeriod(forecastPeriod).Overlaps(period) {
+			selected = append(selected, forecastPeriod)
+		}
+	}
+	sort.SliceStable(selected, func(i int, j int) bool {
+		return selected[i].StartTime.Before(selected[j].StartTime)
+	})
+	return selected
+}
+
+func SelectNarrativePeriods(bundle *Bundle, period timeutil.Period) []ForecastPeriod {
+	if bundle == nil || bundle.Narrative == nil {
+		return nil
+	}
+	return SelectHourlyPeriods(bundle.Narrative, period)
+}
+
+func SelectDiscussion(bundle *Bundle) *Discussion {
+	if bundle == nil {
+		return nil
+	}
+	return bundle.Discussion
+}
+
+func SummarizeDaypart(name string, period timeutil.Period, periods []ForecastPeriod) DaypartSummary {
+	summary := DaypartSummary{
+		Name:          name,
+		Period:        period,
+		HourlyPeriods: periods,
+	}
+	conditionCounts := map[string]int{}
+	conditions := map[string]struct{}{}
+
+	for _, forecastPeriod := range periods {
+		addRangeValue(&summary.Temperature, periodTemperatureValues(forecastPeriod)...)
+		addRangeValue(&summary.ApparentTemperature, valueFromPointers(forecastPeriod.ApparentTemperatureF, forecastPeriod.ApparentTemperatureC)...)
+		setMaxTimedValue(&summary.MaxPrecipitationProbability, forecastPeriod.ProbabilityOfPrecipitationPercent, forecastPeriod.StartTime)
+		setMaxTimedValue(&summary.PeakWindSpeed, firstValue(forecastPeriod.WindSpeedMph, forecastPeriod.WindSpeedKmh), forecastPeriod.StartTime)
+		setMaxTimedValue(&summary.PeakWindGust, firstValue(forecastPeriod.WindGustMph, forecastPeriod.WindGustKmh), forecastPeriod.StartTime)
+
+		text := strings.TrimSpace(forecastPeriod.TextDescription)
+		if text != "" {
+			conditionCounts[text]++
+			conditions[text] = struct{}{}
+			summary.Indicators = mergeIndicators(summary.Indicators, indicatorsForText(text))
+		}
+		summary.Indicators = mergeIndicators(summary.Indicators, numericIndicators(forecastPeriod))
+	}
+
+	summary.DominantCondition = dominantCondition(conditionCounts)
+	summary.NotableConditions = sortedKeys(conditions)
+	return summary
+}
+
+func periodTemperatureValues(period ForecastPeriod) []*float64 {
+	values := []*float64{}
+	values = append(values, valueFromPointers(period.TemperatureF, period.TemperatureC)...)
+	values = append(values, valueFromPointers(period.TemperatureFMin, period.TemperatureCMin)...)
+	values = append(values, valueFromPointers(period.TemperatureFMax, period.TemperatureCMax)...)
+	return values
+}
+
+func valueFromPointers(values ...*float64) []*float64 {
+	for _, value := range values {
+		if value != nil {
+			return []*float64{value}
+		}
+	}
+	return nil
+}
+
+func firstValue(values ...*float64) *float64 {
+	for _, value := range values {
+		if value != nil {
+			return value
+		}
+	}
+	return nil
+}
+
+func addRangeValue(target *Range, values ...*float64) {
+	for _, value := range values {
+		if value == nil {
+			continue
+		}
+		if target.Min == nil || *value < *target.Min {
+			copied := *value
+			target.Min = &copied
+		}
+		if target.Max == nil || *value > *target.Max {
+			copied := *value
+			target.Max = &copied
+		}
+	}
+}
+
+func setMaxTimedValue(target **TimedValue, value *float64, at time.Time) {
+	if value == nil {
+		return
+	}
+	if *target == nil || value != nil && *value > (*target).Value {
+		*target = &TimedValue{Value: *value, Time: at}
+	}
+}
+
+func dominantCondition(counts map[string]int) string {
+	var dominant string
+	var dominantCount int
+	for condition, count := range counts {
+		if count > dominantCount || count == dominantCount && condition < dominant {
+			dominant = condition
+			dominantCount = count
+		}
+	}
+	return dominant
+}
+
+func sortedKeys(values map[string]struct{}) []string {
+	out := make([]string, 0, len(values))
+	for value := range values {
+		out = append(out, value)
+	}
+	sort.Strings(out)
+	return out
+}
+
+func indicatorsForText(text string) Indicators {
+	lower := strings.ToLower(text)
+	return Indicators{
+		Snow: strings.Contains(lower, "snow"),
+		Ice:  strings.Contains(lower, "ice") || strings.Contains(lower, "freezing") || strings.Contains(lower, "sleet"),
+		Fog:  strings.Contains(lower, "fog"),
+		Wind: strings.Contains(lower, "wind") || strings.Contains(lower, "gust"),
+	}
+}
+
+func numericIndicators(period ForecastPeriod) Indicators {
+	windGust := firstValue(period.WindGustMph, period.WindGustKmh)
+	windSpeed := firstValue(period.WindSpeedMph, period.WindSpeedKmh)
+	indicators := Indicators{}
+	if period.TemperatureF != nil {
+		indicators.Heat = *period.TemperatureF >= 95
+		indicators.Cold = *period.TemperatureF <= 32
+	} else if period.TemperatureC != nil {
+		indicators.Heat = *period.TemperatureC >= 35
+		indicators.Cold = *period.TemperatureC <= 0
+	}
+	if windGust != nil && *windGust >= 35 || windSpeed != nil && *windSpeed >= 25 {
+		indicators.Wind = true
+	}
+	return indicators
+}
+
+func mergeIndicators(left Indicators, right Indicators) Indicators {
+	return Indicators{
+		Snow: left.Snow || right.Snow,
+		Ice:  left.Ice || right.Ice,
+		Fog:  left.Fog || right.Fog,
+		Heat: left.Heat || right.Heat,
+		Cold: left.Cold || right.Cold,
+		Wind: left.Wind || right.Wind,
+	}
+}
+
+func AlertOverlaps(alertRun *AlertRun, period timeutil.Period) []AlertOverlap {
+	if alertRun == nil {
+		return nil
+	}
+	var overlaps []AlertOverlap
+	for _, rawAlert := range alertRun.Alerts {
+		alert, ok := parseAlert(rawAlert)
+		if !ok || !alert.Period.IsValid() || !alert.Period.Overlaps(period) {
+			continue
+		}
+		overlaps = append(overlaps, AlertOverlap{
+			Event:       alert.Event,
+			Headline:    alert.Headline,
+			Severity:    alert.Severity,
+			Period:      alert.Period,
+			Overlap:     intersect(alert.Period, period),
+			Description: alert.Description,
+		})
+	}
+	sort.SliceStable(overlaps, func(i int, j int) bool {
+		return overlaps[i].Period.Start.Before(overlaps[j].Period.Start)
+	})
+	return overlaps
+}
+
+type parsedAlert struct {
+	Event       string
+	Headline    string
+	Severity    string
+	Description string
+	Period      timeutil.Period
+}
+
+func parseAlert(raw json.RawMessage) (parsedAlert, bool) {
+	var fields map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &fields); err != nil {
+		return parsedAlert{}, false
+	}
+	alert := parsedAlert{
+		Event:       stringField(fields, "event"),
+		Headline:    firstStringField(fields, "headline", "title"),
+		Severity:    stringField(fields, "severity"),
+		Description: firstStringField(fields, "description", "instruction"),
+	}
+	start, startOK := firstTimeField(fields, "effective", "onset", "startsAt", "startTime", "sent")
+	end, endOK := firstTimeField(fields, "expires", "ends", "endsAt", "endTime")
+	if !startOK || !endOK {
+		return parsedAlert{}, false
+	}
+	alert.Period = timeutil.Period{Start: start, End: end}
+	return alert, true
+}
+
+func stringField(fields map[string]json.RawMessage, name string) string {
+	value, ok := fields[name]
+	if !ok {
+		return ""
+	}
+	var out string
+	if err := json.Unmarshal(value, &out); err != nil {
+		return ""
+	}
+	return out
+}
+
+func firstStringField(fields map[string]json.RawMessage, names ...string) string {
+	for _, name := range names {
+		if value := stringField(fields, name); value != "" {
+			return value
+		}
+	}
+	return ""
+}
+
+func firstTimeField(fields map[string]json.RawMessage, names ...string) (time.Time, bool) {
+	for _, name := range names {
+		value := stringField(fields, name)
+		if value == "" {
+			continue
+		}
+		parsed, err := time.Parse(time.RFC3339, value)
+		if err == nil {
+			return parsed, true
+		}
+	}
+	return time.Time{}, false
+}
+
+func intersect(left timeutil.Period, right timeutil.Period) timeutil.Period {
+	start := left.Start
+	if right.Start.After(start) {
+		start = right.Start
+	}
+	end := left.End
+	if right.End.Before(end) {
+		end = right.End
+	}
+	return timeutil.Period{Start: start, End: end}
+}
+
+func overlapsWithin(alerts []AlertOverlap, period timeutil.Period) []AlertOverlap {
+	var out []AlertOverlap
+	for _, alert := range alerts {
+		if alert.Period.Overlaps(period) {
+			alert.Overlap = intersect(alert.Period, period)
+			out = append(out, alert)
+		}
+	}
+	return out
+}

internal/forecast/derive_test.go

@@ -0,0 +1,280 @@
+package forecast
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+func TestBuildDailySummaryGroupsDaypartsAndComputesMetrics(t *testing.T) {
+	location := time.FixedZone("Test", -5*60*60)
+	bundle := testBundle(location)
+	date := time.Date(2026, 5, 29, 12, 0, 0, 0, location)
+	dayparts := []DaypartDefinition{
+		{Name: "overnight", Start: "00:00", End: "06:00"},
+		{Name: "morning", Start: "06:00", End: "12:00"},
+		{Name: "afternoon", Start: "12:00", End: "18:00"},
+		{Name: "evening", Start: "18:00", End: "24:00"},
+	}
+
+	summary, err := BuildDailySummary(bundle, date, location, dayparts)
+	if err != nil {
+		t.Fatalf("BuildDailySummary() error = %v", err)
+	}
+
+	if len(summary.Dayparts) != 4 {
+		t.Fatalf("Dayparts length = %d, want 4", len(summary.Dayparts))
+	}
+	morning := summary.Dayparts[1]
+	if len(morning.HourlyPeriods) != 2 {
+		t.Fatalf("morning periods = %d, want 2", len(morning.HourlyPeriods))
+	}
+	assertRange(t, "morning temperature", morning.Temperature, 58, 72)
+	if morning.MaxPrecipitationProbability == nil || morning.MaxPrecipitationProbability.Value != 70 {
+		t.Fatalf("morning max precip = %#v, want 70", morning.MaxPrecipitationProbability)
+	}
+	if morning.PeakWindGust == nil || morning.PeakWindGust.Value != 40 {
+		t.Fatalf("morning peak gust = %#v, want 40", morning.PeakWindGust)
+	}
+	if morning.DominantCondition != "Thunderstorms and gusty wind" {
+		t.Fatalf("morning dominant = %q, want raw forecast condition", morning.DominantCondition)
+	}
+	if !morning.Indicators.Wind {
+		t.Fatalf("morning indicators = %#v, want wind", morning.Indicators)
+	}
+
+	afternoon := summary.Dayparts[2]
+	assertRange(t, "afternoon apparent", afternoon.ApparentTemperature, 100, 100)
+	if !afternoon.Indicators.Heat {
+		t.Fatalf("afternoon indicators = %#v, want heat", afternoon.Indicators)
+	}
+	if len(summary.NarrativePeriods) != 1 {
+		t.Fatalf("NarrativePeriods length = %d, want 1", len(summary.NarrativePeriods))
+	}
+	if len(summary.AlertOverlaps) != 1 {
+		t.Fatalf("AlertOverlaps length = %d, want 1", len(summary.AlertOverlaps))
+	}
+	if len(morning.AlertOverlaps) != 1 {
+		t.Fatalf("morning AlertOverlaps length = %d, want 1", len(morning.AlertOverlaps))
+	}
+
+	if _, err := json.Marshal(summary.Dayparts); err != nil {
+		t.Fatalf("daypart summaries are not JSON inspectable: %v", err)
+	}
+}
+
+func TestBuildDailySummaryFromFixtureBundle(t *testing.T) {
+	data, err := os.ReadFile(filepath.Join("testdata", "daily_bundle.json"))
+	if err != nil {
+		t.Fatalf("read fixture bundle: %v", err)
+	}
+	var bundle Bundle
+	if err := json.Unmarshal(data, &bundle); err != nil {
+		t.Fatalf("decode fixture bundle: %v", err)
+	}
+	location := time.FixedZone("Test", -5*60*60)
+	summary, err := BuildDailySummary(&bundle, mustParse("2026-05-29T12:00:00-05:00"), location, []DaypartDefinition{
+		{Name: "morning", Start: "06:00", End: "12:00"},
+		{Name: "afternoon", Start: "12:00", End: "18:00"},
+	})
+	if err != nil {
+		t.Fatalf("BuildDailySummary() error = %v", err)
+	}
+	if len(summary.Dayparts) != 2 {
+		t.Fatalf("Dayparts length = %d, want 2", len(summary.Dayparts))
+	}
+	if summary.Dayparts[0].DominantCondition != "Showers and thunderstorms" {
+		t.Fatalf("morning dominant = %q, want raw forecast condition", summary.Dayparts[0].DominantCondition)
+	}
+	if len(summary.AlertOverlaps) != 1 {
+		t.Fatalf("AlertOverlaps length = %d, want 1", len(summary.AlertOverlaps))
+	}
+}
+
+func TestOvernightGroupingAcrossMidnight(t *testing.T) {
+	location := time.FixedZone("Test", -5*60*60)
+	date := time.Date(2026, 5, 29, 12, 0, 0, 0, location)
+	bundle := &Bundle{Hourly: &ForecastRun{Periods: []ForecastPeriod{
+		hour(location, "2026-05-29T23:00:00-05:00", "2026-05-30T00:00:00-05:00", "Snow", 31, nil, nil, nil, nil),
+		hour(location, "2026-05-30T05:00:00-05:00", "2026-05-30T06:00:00-05:00", "Fog", 30, nil, nil, nil, nil),
+		hour(location, "2026-05-30T06:00:00-05:00", "2026-05-30T07:00:00-05:00", "Clear", 35, nil, nil, nil, nil),
+	}}}
+
+	summary, err := BuildDailySummary(bundle, date, location, []DaypartDefinition{
+		{Name: "night", Start: "22:00", End: "06:00"},
+	})
+	if err != nil {
+		t.Fatalf("BuildDailySummary() error = %v", err)
+	}
+	night := summary.Dayparts[0]
+	if len(night.HourlyPeriods) != 2 {
+		t.Fatalf("night periods = %d, want 2", len(night.HourlyPeriods))
+	}
+	if !night.Indicators.Snow || !night.Indicators.Fog || !night.Indicators.Cold {
+		t.Fatalf("night indicators = %#v, want snow, fog, and cold", night.Indicators)
+	}
+}
+
+func TestBoundaryTimestampsAtDaypartEdges(t *testing.T) {
+	location := time.FixedZone("Test", -5*60*60)
+	date := time.Date(2026, 5, 29, 12, 0, 0, 0, location)
+	bundle := &Bundle{Hourly: &ForecastRun{Periods: []ForecastPeriod{
+		hour(location, "2026-05-29T05:00:00-05:00", "2026-05-29T06:00:00-05:00", "Before", 55, nil, nil, nil, nil),
+		hour(location, "2026-05-29T06:00:00-05:00", "2026-05-29T07:00:00-05:00", "Start", 56, nil, nil, nil, nil),
+		hour(location, "2026-05-29T12:00:00-05:00", "2026-05-29T13:00:00-05:00", "After", 70, nil, nil, nil, nil),
+	}}}
+
+	summary, err := BuildDailySummary(bundle, date, location, []DaypartDefinition{
+		{Name: "morning", Start: "06:00", End: "12:00"},
+	})
+	if err != nil {
+		t.Fatalf("BuildDailySummary() error = %v", err)
+	}
+	morning := summary.Dayparts[0]
+	if len(morning.HourlyPeriods) != 1 {
+		t.Fatalf("morning periods = %d, want only start-boundary period", len(morning.HourlyPeriods))
+	}
+	if morning.HourlyPeriods[0].TextDescription != "Start" {
+		t.Fatalf("selected period = %q, want Start", morning.HourlyPeriods[0].TextDescription)
+	}
+}
+
+func TestBuildDailySummaryRequiresHourlyData(t *testing.T) {
+	location := time.UTC
+	_, err := BuildDailySummary(&Bundle{}, time.Now(), location, []DaypartDefinition{
+		{Name: "morning", Start: "06:00", End: "12:00"},
+	})
+	if err == nil {
+		t.Fatal("BuildDailySummary() error = nil, want missing hourly error")
+	}
+}
+
+func TestBuildPeriodDailySummariesClipsPartialDays(t *testing.T) {
+	location := time.FixedZone("Test", -5*60*60)
+	bundle := &Bundle{Hourly: &ForecastRun{Periods: []ForecastPeriod{
+		hour(location, "2026-05-29T05:00:00-05:00", "2026-05-29T06:00:00-05:00", "Before", 50, nil, nil, nil, nil),
+		hour(location, "2026-05-29T08:00:00-05:00", "2026-05-29T09:00:00-05:00", "Showers", 60, nil, ptr(60), nil, nil),
+		hour(location, "2026-05-30T14:00:00-05:00", "2026-05-30T15:00:00-05:00", "Hot", 95, nil, nil, nil, nil),
+		hour(location, "2026-05-31T20:00:00-05:00", "2026-05-31T21:00:00-05:00", "Wind", 70, nil, nil, nil, ptr(35)),
+	}}}
+	period := timeutil.Period{
+		Start: mustParse("2026-05-29T07:00:00-05:00").In(location),
+		End:   mustParse("2026-06-01T00:00:00-05:00").In(location),
+	}
+
+	summaries, err := BuildPeriodDailySummaries(bundle, period, location, []DaypartDefinition{
+		{Name: "morning", Start: "06:00", End: "12:00"},
+		{Name: "afternoon", Start: "12:00", End: "18:00"},
+		{Name: "evening", Start: "18:00", End: "24:00"},
+	})
+	if err != nil {
+		t.Fatalf("BuildPeriodDailySummaries() error = %v", err)
+	}
+	if len(summaries) != 3 {
+		t.Fatalf("summaries length = %d, want 3", len(summaries))
+	}
+	if summaries[0].Period.Start.Format(time.RFC3339) != "2026-05-29T07:00:00-05:00" {
+		t.Fatalf("first period start = %s, want clipped start", summaries[0].Period.Start.Format(time.RFC3339))
+	}
+	if len(summaries[0].Dayparts[0].HourlyPeriods) != 1 || summaries[0].Dayparts[0].HourlyPeriods[0].TextDescription != "Showers" {
+		t.Fatalf("first morning periods = %#v, want only post-start hour", summaries[0].Dayparts[0].HourlyPeriods)
+	}
+	if summaries[2].Dayparts[2].PeakWindGust == nil || summaries[2].Dayparts[2].PeakWindGust.Value != 35 {
+		t.Fatalf("third evening gust = %#v, want 35", summaries[2].Dayparts[2].PeakWindGust)
+	}
+}
+
+func TestAlertOverlap(t *testing.T) {
+	location := time.FixedZone("Test", -5*60*60)
+	raw := json.RawMessage(`{"event":"Flood Watch","headline":"Flooding possible","severity":"Moderate","effective":"2026-05-29T07:00:00-05:00","expires":"2026-05-29T10:00:00-05:00"}`)
+	alertRun := &AlertRun{Alerts: []json.RawMessage{raw}}
+	period := timeutil.Period{
+		Start: mustParse("2026-05-29T06:00:00-05:00").In(location),
+		End:   mustParse("2026-05-29T09:00:00-05:00").In(location),
+	}
+
+	overlaps := AlertOverlaps(alertRun, period)
+	if len(overlaps) != 1 {
+		t.Fatalf("overlaps length = %d, want 1", len(overlaps))
+	}
+	if overlaps[0].Overlap.Start.Format(time.RFC3339) != "2026-05-29T07:00:00-05:00" {
+		t.Fatalf("overlap start = %s, want alert start", overlaps[0].Overlap.Start.Format(time.RFC3339))
+	}
+	if overlaps[0].Overlap.End.Format(time.RFC3339) != "2026-05-29T09:00:00-05:00" {
+		t.Fatalf("overlap end = %s, want period end", overlaps[0].Overlap.End.Format(time.RFC3339))
+	}
+}
+
+func TestThresholdHelpers(t *testing.T) {
+	if !DifferenceAtLeast(50, 56, 5) {
+		t.Fatal("DifferenceAtLeast = false, want true")
+	}
+	if !CrossesAtOrAbove(29, 32, 32) {
+		t.Fatal("CrossesAtOrAbove = false, want true")
+	}
+	if !CrossesBelow(35, 31, 32) {
+		t.Fatal("CrossesBelow = false, want true")
+	}
+}
+
+func testBundle(location *time.Location) *Bundle {
+	return &Bundle{
+		Hourly: &ForecastRun{Periods: []ForecastPeriod{
+			hour(location, "2026-05-29T05:00:00-05:00", "2026-05-29T06:00:00-05:00", "Cloudy", 55, nil, nil, nil, nil),
+			hour(location, "2026-05-29T06:00:00-05:00", "2026-05-29T07:00:00-05:00", "Thunderstorms and gusty wind", 58, ptr(57), ptr(70), ptr(22), ptr(40)),
+			hour(location, "2026-05-29T11:00:00-05:00", "2026-05-29T12:00:00-05:00", "Thunderstorms and gusty wind", 72, ptr(74), ptr(60), ptr(18), ptr(35)),
+			hour(location, "2026-05-29T14:00:00-05:00", "2026-05-29T15:00:00-05:00", "Hot and sunny", 96, ptr(100), ptr(5), ptr(10), ptr(12)),
+		}},
+		Narrative: &ForecastRun{Periods: []ForecastPeriod{
+			hour(location, "2026-05-29T06:00:00-05:00", "2026-05-29T18:00:00-05:00", "Storms early, hot later.", 96, nil, nil, nil, nil),
+		}},
+		Alerts: &AlertRun{Alerts: []json.RawMessage{
+			json.RawMessage(`{"event":"Severe Thunderstorm Watch","headline":"Storms possible","severity":"Severe","effective":"2026-05-29T06:30:00-05:00","expires":"2026-05-29T11:30:00-05:00"}`),
+		}},
+		Discussion: &Discussion{Product: "discussion", KeyMessages: []string{"Storms possible."}},
+		Sources:    []Source{{Name: "hourly"}},
+		Warnings:   []SourceWarning{{Source: "daily", Code: "missing_source"}},
+	}
+}
+
+func hour(location *time.Location, start string, end string, text string, temperature float64, apparent *float64, precip *float64, wind *float64, gust *float64) ForecastPeriod {
+	startTime := mustParse(start).In(location)
+	endTime := mustParse(end).In(location)
+	temp := temperature
+	return ForecastPeriod{
+		StartTime:                         startTime,
+		EndTime:                           endTime,
+		TextDescription:                   text,
+		TemperatureF:                      &temp,
+		ApparentTemperatureF:              apparent,
+		ProbabilityOfPrecipitationPercent: precip,
+		WindSpeedMph:                      wind,
+		WindGustMph:                       gust,
+	}
+}
+
+func mustParse(value string) time.Time {
+	parsed, err := time.Parse(time.RFC3339, value)
+	if err != nil {
+		panic(err)
+	}
+	return parsed
+}
+
+func ptr(value float64) *float64 {
+	return &value
+}
+
+func assertRange(t *testing.T, name string, got Range, wantMin float64, wantMax float64) {
+	t.Helper()
+	if got.Min == nil || got.Max == nil {
+		t.Fatalf("%s = %#v, want min and max", name, got)
+	}
+	if *got.Min != wantMin || *got.Max != wantMax {
+		t.Fatalf("%s = [%v,%v], want [%v,%v]", name, *got.Min, *got.Max, wantMin, wantMax)
+	}
+}

internal/forecast/testdata/daily_bundle.json

@@ -0,0 +1,74 @@
+{
+  "fetchedAt": "2026-05-29T15:00:00Z",
+  "hourly": {
+    "issuedAt": "2026-05-29T10:30:00-05:00",
+    "product": "hourly",
+    "periods": [
+      {
+        "startTime": "2026-05-29T06:00:00-05:00",
+        "endTime": "2026-05-29T07:00:00-05:00",
+        "textDescription": "Showers and thunderstorms",
+        "temperatureF": 66,
+        "apparentTemperatureF": 67,
+        "probabilityOfPrecipitationPercent": 80,
+        "windSpeedMph": 18,
+        "windGustMph": 32
+      },
+      {
+        "startTime": "2026-05-29T14:00:00-05:00",
+        "endTime": "2026-05-29T15:00:00-05:00",
+        "textDescription": "Mostly sunny",
+        "temperatureF": 88,
+        "apparentTemperatureF": 91,
+        "probabilityOfPrecipitationPercent": 10,
+        "windSpeedMph": 10,
+        "windGustMph": 16
+      }
+    ]
+  },
+  "narrative": {
+    "issuedAt": "2026-05-29T10:30:00-05:00",
+    "product": "narrative",
+    "periods": [
+      {
+        "startTime": "2026-05-29T06:00:00-05:00",
+        "endTime": "2026-05-29T18:00:00-05:00",
+        "name": "Today",
+        "textDescription": "Morning storms, then partly sunny."
+      }
+    ]
+  },
+  "alerts": {
+    "alerts": [
+      {
+        "event": "Flood Watch",
+        "headline": "Flooding possible",
+        "severity": "Moderate",
+        "effective": "2026-05-29T05:00:00-05:00",
+        "expires": "2026-05-29T09:00:00-05:00"
+      }
+    ]
+  },
+  "discussion": {
+    "product": "discussion",
+    "issuedAt": "2026-05-29T09:25:00-05:00",
+    "keyMessages": [
+      "Storms are most likely during the morning."
+    ],
+    "shortTerm": {
+      "qualifier": "(Through This Evening)",
+      "text": "Morning showers taper as a weak boundary shifts east."
+    },
+    "longTerm": {
+      "qualifier": "(This Weekend)",
+      "text": "Warmer and more humid conditions return with periodic rain chances."
+    }
+  },
+  "sources": [
+    {
+      "name": "hourly",
+      "endpoint": "/forecast/hourly",
+      "fetchedAt": "2026-05-29T15:00:00Z"
+    }
+  ]
+}

internal/forecast/thresholds.go

@@ -0,0 +1,20 @@
+package forecast
+
+func DifferenceAtLeast(previous float64, current float64, threshold float64) bool {
+	return abs(current-previous) >= threshold
+}
+
+func CrossesAtOrAbove(previous float64, current float64, threshold float64) bool {
+	return previous < threshold && current >= threshold
+}
+
+func CrossesBelow(previous float64, current float64, threshold float64) bool {
+	return previous >= threshold && current < threshold
+}
+
+func abs(value float64) float64 {
+	if value < 0 {
+		return -value
+	}
+	return value
+}

internal/promptinput/package.go

@@ -0,0 +1,139 @@
+// Package promptinput builds prompt data packages from briefing packages.
+package promptinput
+
+import (
+	"fmt"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/changes"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/fileutil"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+const SchemaVersion = "weatherreporter.data_package.v1"
+
+type Package struct {
+	SchemaVersion  string                   `json:"schemaVersion"`
+	RunID          string                   `json:"runId"`
+	Report         Report                   `json:"report"`
+	Briefing       briefing.Package         `json:"briefing"`
+	RecentChanges  RecentChanges            `json:"recentChanges"`
+	SourceWarnings []forecast.SourceWarning `json:"sourceWarnings,omitempty"`
+}
+
+type Report struct {
+	ID               report.ID       `json:"id"`
+	Variant          string          `json:"variant,omitempty"`
+	PromptID         string          `json:"promptId"`
+	GeneratedAt      time.Time       `json:"generatedAt"`
+	Timezone         string          `json:"timezone"`
+	CurrentLocalDate string          `json:"currentLocalDate"`
+	ValidPeriod      timeutil.Period `json:"validPeriod"`
+}
+
+type RecentChanges struct {
+	Items []changes.Change `json:"items"`
+}
+
+func Build(briefingPackage briefing.Package) (Package, error) {
+	return BuildWithRecentChanges(briefingPackage, nil)
+}
+
+func BuildWithRecentChanges(briefingPackage briefing.Package, recentChanges []changes.Change) (Package, error) {
+	localDate, err := currentLocalDate(briefingPackage.Metadata.GeneratedAt, briefingPackage.Metadata.Timezone)
+	if err != nil {
+		return Package{}, err
+	}
+	items := make([]changes.Change, len(recentChanges))
+	copy(items, recentChanges)
+	if items == nil {
+		items = []changes.Change{}
+	}
+	pkg := Package{
+		SchemaVersion: SchemaVersion,
+		RunID:         briefingPackage.Metadata.RunID,
+		Report: Report{
+			ID:               briefingPackage.Metadata.ReportID,
+			Variant:          briefingPackage.Metadata.Variant,
+			PromptID:         briefingPackage.Metadata.PromptID,
+			GeneratedAt:      briefingPackage.Metadata.GeneratedAt,
+			Timezone:         briefingPackage.Metadata.Timezone,
+			CurrentLocalDate: localDate,
+			ValidPeriod:      briefingPackage.Metadata.ValidPeriod,
+		},
+		Briefing:       briefingPackage,
+		RecentChanges:  RecentChanges{Items: items},
+		SourceWarnings: briefingPackage.Metadata.SourceWarnings,
+	}
+	if err := Validate(pkg); err != nil {
+		return Package{}, err
+	}
+	return pkg, nil
+}
+
+func currentLocalDate(generatedAt time.Time, timezone string) (string, error) {
+	location, err := timeutil.LoadLocation(timezone)
+	if err != nil {
+		return "", fmt.Errorf("load report timezone %q: %w", timezone, err)
+	}
+	return generatedAt.In(location).Format(timeutil.DateLayout), nil
+}
+
+func Validate(pkg Package) error {
+	if pkg.SchemaVersion == "" {
+		return fmt.Errorf("schemaVersion is required")
+	}
+	if pkg.RunID == "" {
+		return fmt.Errorf("runId is required")
+	}
+	if pkg.Report.ID == "" {
+		return fmt.Errorf("report.id is required")
+	}
+	if pkg.Report.PromptID == "" {
+		return fmt.Errorf("report.promptId is required")
+	}
+	if pkg.Report.GeneratedAt.IsZero() {
+		return fmt.Errorf("report.generatedAt is required")
+	}
+	if pkg.Report.Timezone == "" {
+		return fmt.Errorf("report.timezone is required")
+	}
+	if pkg.Report.CurrentLocalDate == "" {
+		return fmt.Errorf("report.currentLocalDate is required")
+	}
+	if !pkg.Report.ValidPeriod.IsValid() {
+		return fmt.Errorf("report.validPeriod must be valid")
+	}
+	if pkg.Briefing.Metadata.RunID == "" {
+		return fmt.Errorf("briefing.metadata.runId is required")
+	}
+	if pkg.Briefing.Metadata.RunID != pkg.RunID {
+		return fmt.Errorf("briefing.metadata.runId must match runId")
+	}
+	if pkg.Briefing.Metadata.SchemaVersion == "" {
+		return fmt.Errorf("briefing.metadata.schemaVersion is required")
+	}
+	if pkg.Briefing.Metadata.PromptID != pkg.Report.PromptID {
+		return fmt.Errorf("briefing.metadata.promptId must match report.promptId")
+	}
+	if pkg.Briefing.Metadata.ReportID != pkg.Report.ID {
+		return fmt.Errorf("briefing.metadata.reportId must match report.id")
+	}
+	if pkg.Briefing.Daily == nil && pkg.Briefing.ThreeDay == nil && pkg.Briefing.Weekend == nil && pkg.Briefing.Storm == nil {
+		return fmt.Errorf("briefing report content is required")
+	}
+	return nil
+}
+
+func Save(path string, pkg Package) error {
+	if err := Validate(pkg); err != nil {
+		return err
+	}
+	if err := fileutil.WriteJSONAtomic(path, pkg); err != nil {
+		return fmt.Errorf("save data package: %w", err)
+	}
+	return nil
+}

internal/promptinput/package_test.go

@@ -0,0 +1,229 @@
+package promptinput
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+func TestBuildDailyDataPackage(t *testing.T) {
+	briefingPackage := validBriefingPackage()
+
+	pkg, err := Build(briefingPackage)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+
+	if pkg.SchemaVersion != SchemaVersion {
+		t.Fatalf("SchemaVersion = %q, want %q", pkg.SchemaVersion, SchemaVersion)
+	}
+	if pkg.RunID != "20260529T100000Z_daily_today" {
+		t.Fatalf("RunID = %q, want briefing run id", pkg.RunID)
+	}
+	if pkg.Report.PromptID != "weather.daily_report" {
+		t.Fatalf("PromptID = %q, want weather.daily_report", pkg.Report.PromptID)
+	}
+	if pkg.Report.CurrentLocalDate != "2026-05-29" {
+		t.Fatalf("CurrentLocalDate = %q, want 2026-05-29", pkg.Report.CurrentLocalDate)
+	}
+	if pkg.Briefing.Daily == nil {
+		t.Fatal("Briefing.Daily = nil")
+	}
+	if pkg.Briefing.Metadata.Location == nil || pkg.Briefing.Metadata.Location.Name != "Brentwood" {
+		t.Fatalf("Briefing.Metadata.Location = %#v, want configured location", pkg.Briefing.Metadata.Location)
+	}
+	if pkg.Briefing.CurrentConditions == nil || pkg.Briefing.CurrentConditions.ConditionText != "Partly cloudy" {
+		t.Fatalf("Briefing.CurrentConditions = %#v, want current conditions", pkg.Briefing.CurrentConditions)
+	}
+	if pkg.RecentChanges.Items == nil || len(pkg.RecentChanges.Items) != 0 {
+		t.Fatalf("RecentChanges.Items = %#v, want empty slice", pkg.RecentChanges.Items)
+	}
+}
+
+func TestBuildCurrentLocalDateUsesReportTimezone(t *testing.T) {
+	briefingPackage := validBriefingPackage()
+	briefingPackage.Metadata.GeneratedAt = time.Date(2026, 5, 30, 2, 30, 0, 0, time.UTC)
+	briefingPackage.Metadata.Timezone = "America/Chicago"
+
+	pkg, err := Build(briefingPackage)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+
+	if pkg.Report.CurrentLocalDate != "2026-05-29" {
+		t.Fatalf("CurrentLocalDate = %q, want local Chicago date 2026-05-29", pkg.Report.CurrentLocalDate)
+	}
+}
+
+func TestBuildRejectsInvalidReportTimezone(t *testing.T) {
+	briefingPackage := validBriefingPackage()
+	briefingPackage.Metadata.Timezone = "Not/AZone"
+
+	_, err := Build(briefingPackage)
+	if err == nil {
+		t.Fatal("Build() error = nil, want invalid timezone error")
+	}
+	if !strings.Contains(err.Error(), "report timezone") {
+		t.Fatalf("error = %q, want report timezone context", err.Error())
+	}
+}
+
+func TestValidateRequiresFields(t *testing.T) {
+	pkg, err := Build(validBriefingPackage())
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+	pkg.RunID = ""
+
+	err = Validate(pkg)
+	if err == nil {
+		t.Fatal("Validate() error = nil, want required field error")
+	}
+	if !strings.Contains(err.Error(), "runId") {
+		t.Fatalf("error = %q, want runId context", err.Error())
+	}
+}
+
+func TestValidateRequiresCurrentLocalDate(t *testing.T) {
+	pkg, err := Build(validBriefingPackage())
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+	pkg.Report.CurrentLocalDate = ""
+
+	err = Validate(pkg)
+	if err == nil {
+		t.Fatal("Validate() error = nil, want required field error")
+	}
+	if !strings.Contains(err.Error(), "currentLocalDate") {
+		t.Fatalf("error = %q, want currentLocalDate context", err.Error())
+	}
+}
+
+func TestBuildThreeDayDataPackage(t *testing.T) {
+	briefingPackage := validBriefingPackage()
+	briefingPackage.Metadata.RunID = "20260529T100000Z_three_day"
+	briefingPackage.Metadata.ReportID = report.ThreeDay
+	briefingPackage.Metadata.PromptID = "weather.three_day_outlook"
+	briefingPackage.Daily = nil
+	briefingPackage.ThreeDay = &briefing.ThreeDay{
+		Days: []briefing.OutlookDay{{Date: "2026-05-29"}},
+	}
+
+	pkg, err := Build(briefingPackage)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+
+	if pkg.Report.ID != report.ThreeDay {
+		t.Fatalf("Report.ID = %q, want three_day", pkg.Report.ID)
+	}
+	if pkg.Briefing.ThreeDay == nil {
+		t.Fatal("Briefing.ThreeDay = nil")
+	}
+}
+
+func TestBuildWeekendDataPackage(t *testing.T) {
+	briefingPackage := validBriefingPackage()
+	briefingPackage.Metadata.RunID = "20260529T100000Z_weekend"
+	briefingPackage.Metadata.ReportID = report.Weekend
+	briefingPackage.Metadata.PromptID = "weather.weekend_outlook"
+	briefingPackage.Daily = nil
+	briefingPackage.Weekend = &briefing.Weekend{
+		Days: []briefing.OutlookDay{{Date: "2026-05-30"}},
+	}
+
+	pkg, err := Build(briefingPackage)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+
+	if pkg.Report.ID != report.Weekend {
+		t.Fatalf("Report.ID = %q, want weekend", pkg.Report.ID)
+	}
+	if pkg.Briefing.Weekend == nil {
+		t.Fatal("Briefing.Weekend = nil")
+	}
+}
+
+func TestBuildStormDataPackage(t *testing.T) {
+	briefingPackage := validBriefingPackage()
+	briefingPackage.Metadata.RunID = "20260529T100000Z_storm"
+	briefingPackage.Metadata.ReportID = report.Storm
+	briefingPackage.Metadata.PromptID = "weather.storm_report"
+	briefingPackage.Daily = nil
+	briefingPackage.Storm = &briefing.Storm{
+		TimingWindow: briefingPackage.Metadata.ValidPeriod,
+		Hazards:      []string{"Thunderstorms"},
+	}
+
+	pkg, err := Build(briefingPackage)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+
+	if pkg.Report.ID != report.Storm {
+		t.Fatalf("Report.ID = %q, want storm", pkg.Report.ID)
+	}
+	if pkg.Report.PromptID != "weather.storm_report" {
+		t.Fatalf("PromptID = %q, want weather.storm_report", pkg.Report.PromptID)
+	}
+	if pkg.Briefing.Storm == nil {
+		t.Fatal("Briefing.Storm = nil")
+	}
+}
+
+func TestMarshalDeterministic(t *testing.T) {
+	pkg, err := Build(validBriefingPackage())
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+
+	first, err := json.MarshalIndent(pkg, "", "  ")
+	if err != nil {
+		t.Fatalf("first marshal: %v", err)
+	}
+	second, err := json.MarshalIndent(pkg, "", "  ")
+	if err != nil {
+		t.Fatalf("second marshal: %v", err)
+	}
+	if string(first) != string(second) {
+		t.Fatalf("JSON output changed between marshals:\n%s\n---\n%s", string(first), string(second))
+	}
+}
+
+func validBriefingPackage() briefing.Package {
+	generatedAt := time.Date(2026, 5, 29, 10, 0, 0, 0, time.UTC)
+	return briefing.Package{
+		Metadata: briefing.Metadata{
+			SchemaVersion: briefing.SchemaVersion,
+			RunID:         "20260529T100000Z_daily_today",
+			ReportID:      report.DailyToday,
+			PromptID:      "weather.daily_report",
+			GeneratedAt:   generatedAt,
+			Units:         "us",
+			Timezone:      "America/Chicago",
+			Location: &briefing.LocationContext{
+				ID:       "home",
+				Name:     "Brentwood",
+				Region:   "St. Louis Metro",
+				Timezone: "America/Chicago",
+			},
+			ValidPeriod: timeutil.Period{
+				Start: time.Date(2026, 5, 29, 5, 0, 0, 0, time.UTC),
+				End:   time.Date(2026, 5, 30, 5, 0, 0, 0, time.UTC),
+			},
+		},
+		CurrentConditions: &briefing.CurrentConditionsContext{
+			ConditionText: "Partly cloudy",
+		},
+		Daily: &briefing.Daily{
+			ForecastSummaryDate: "2026-05-29",
+		},
+	}
+}

internal/report/definition.go

@@ -0,0 +1,99 @@
+// Package report defines report identities, registry metadata, and valid periods.
+package report
+
+import (
+	"fmt"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+type ID string
+
+const (
+	DailyToday    ID = "daily_today"
+	DailyTomorrow ID = "daily_tomorrow"
+	ThreeDay      ID = "three_day"
+	Weekend       ID = "weekend"
+	Storm         ID = "storm"
+)
+
+type ComparisonStrategy string
+
+const (
+	CompareSameValidDate  ComparisonStrategy = "same_valid_date"
+	CompareWeekendWindow  ComparisonStrategy = "same_weekend_window"
+	CompareExplicitWindow ComparisonStrategy = "explicit_event_window"
+)
+
+type Batch string
+
+const (
+	Morning Batch = "morning"
+	Evening Batch = "evening"
+)
+
+type Definition struct {
+	ID                 ID
+	Name               string
+	PromptID           string
+	ComparisonStrategy ComparisonStrategy
+	ArtifactGroup      string
+	BatchOutputName    string
+	Generated          bool
+	CompatiblePriorIDs []ID
+	Morning            bool
+	Evening            bool
+	resolve            func(ResolveRequest) (timeutil.Period, error)
+}
+
+func (d Definition) ResolvePeriod(req ResolveRequest) (timeutil.Period, error) {
+	if d.resolve == nil {
+		return timeutil.Period{}, fmt.Errorf("report %q has no valid-period resolver", d.ID)
+	}
+	return d.resolve(req)
+}
+
+func (d Definition) CompatibleWithPrior(id ID) bool {
+	for _, compatibleID := range d.CompatiblePriorIDs {
+		if id == compatibleID {
+			return true
+		}
+	}
+	return false
+}
+
+type ResolveRequest struct {
+	Now        time.Time
+	Location   *time.Location
+	Date       time.Time
+	StormStart time.Time
+	StormEnd   time.Time
+}
+
+type Resolved struct {
+	Definition  Definition
+	GeneratedAt time.Time
+	Timezone    string
+	ValidPeriod timeutil.Period
+}
+
+type Metadata struct {
+	RunID       string          `json:"runId"`
+	ReportID    ID              `json:"reportId"`
+	PromptID    string          `json:"promptId"`
+	GeneratedAt time.Time       `json:"generatedAt"`
+	Timezone    string          `json:"timezone"`
+	ValidPeriod timeutil.Period `json:"validPeriod"`
+}
+
+func (r Resolved) Metadata() Metadata {
+	return Metadata{
+		RunID:       r.GeneratedAt.UTC().Format("20060102T150405.000000000Z") + "_" + string(r.Definition.ID),
+		ReportID:    r.Definition.ID,
+		PromptID:    r.Definition.PromptID,
+		GeneratedAt: r.GeneratedAt,
+		Timezone:    r.Timezone,
+		ValidPeriod: r.ValidPeriod,
+	}
+}

internal/report/period.go

@@ -0,0 +1,144 @@
+package report
+
+import (
+	"fmt"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+func Resolve(id ID, req ResolveRequest) (Resolved, error) {
+	return DefaultRegistry().Resolve(id, req)
+}
+
+func (r Registry) Resolve(id ID, req ResolveRequest) (Resolved, error) {
+	definition, err := r.Lookup(id)
+	if err != nil {
+		return Resolved{}, err
+	}
+	return r.resolveDefinition(definition, req)
+}
+
+func (r Registry) BatchReports(batch Batch, req ResolveRequest) ([]Resolved, error) {
+	if req.Location == nil {
+		req.Location = time.UTC
+	}
+	if req.Now.IsZero() {
+		req.Now = time.Now()
+	}
+	switch batch {
+	case Morning:
+		ids := []ID{DailyToday, ThreeDay}
+		if req.Now.In(req.Location).Weekday() != time.Sunday {
+			ids = append(ids, Weekend)
+		}
+		return r.resolveIDs(ids, req)
+	case Evening:
+		return r.resolveIDs([]ID{DailyTomorrow}, req)
+	default:
+		return nil, fmt.Errorf("unknown batch %q", batch)
+	}
+}
+
+func (r Registry) resolveIDs(ids []ID, req ResolveRequest) ([]Resolved, error) {
+	resolved := make([]Resolved, 0, len(ids))
+	for _, id := range ids {
+		item, err := r.Resolve(id, req)
+		if err != nil {
+			return nil, err
+		}
+		resolved = append(resolved, item)
+	}
+	return resolved, nil
+}
+
+func (r Registry) resolveDefinition(definition Definition, req ResolveRequest) (Resolved, error) {
+	if req.Location == nil {
+		req.Location = time.UTC
+	}
+	if req.Now.IsZero() {
+		req.Now = time.Now()
+	}
+	period, err := definition.ResolvePeriod(req)
+	if err != nil {
+		return Resolved{}, err
+	}
+	return Resolved{
+		Definition:  definition,
+		GeneratedAt: req.Now,
+		Timezone:    req.Location.String(),
+		ValidPeriod: period,
+	}, nil
+}
+
+func resolveDailyToday(req ResolveRequest) (timeutil.Period, error) {
+	if !req.Date.IsZero() {
+		return timeutil.CivilDay(req.Date, req.Location), nil
+	}
+	return timeutil.CivilDay(req.Now, req.Location), nil
+}
+
+func ParseStormPeriod(start string, end string, location *time.Location) (timeutil.Period, error) {
+	if location == nil {
+		location = time.UTC
+	}
+	startTime, err := timeutil.ParseStormTime(start, location)
+	if err != nil {
+		return timeutil.Period{}, err
+	}
+	endTime, err := timeutil.ParseStormTime(end, location)
+	if err != nil {
+		return timeutil.Period{}, err
+	}
+	period := timeutil.Period{Start: startTime, End: endTime}
+	if !period.IsValid() {
+		return timeutil.Period{}, fmt.Errorf("storm report requires end time after start time")
+	}
+	return period, nil
+}
+
+func resolveDailyTomorrow(req ResolveRequest) (timeutil.Period, error) {
+	return timeutil.CivilDay(req.Now.In(req.Location).AddDate(0, 0, 1), req.Location), nil
+}
+
+func resolveThreeDay(req ResolveRequest) (timeutil.Period, error) {
+	localNow := req.Now.In(req.Location)
+	endDate := localNow.AddDate(0, 0, 3)
+	end := time.Date(endDate.Year(), endDate.Month(), endDate.Day(), 0, 0, 0, 0, req.Location)
+	return timeutil.Period{Start: localNow, End: end}, nil
+}
+
+func resolveWeekend(req ResolveRequest) (timeutil.Period, error) {
+	localNow := req.Now.In(req.Location)
+	weekday := localNow.Weekday()
+	if weekday == time.Sunday {
+		return timeutil.Period{}, fmt.Errorf("weekend outlook is not scheduled on Sunday morning")
+	}
+
+	daysUntilSaturday := (int(time.Saturday) - int(weekday) + 7) % 7
+	saturday := localNow.AddDate(0, 0, daysUntilSaturday)
+	start := time.Date(saturday.Year(), saturday.Month(), saturday.Day(), 0, 0, 0, 0, req.Location)
+	if weekday == time.Friday || weekday == time.Saturday {
+		friday := start.AddDate(0, 0, -1)
+		fridayEvening := time.Date(friday.Year(), friday.Month(), friday.Day(), 18, 0, 0, 0, req.Location)
+		start = fridayEvening
+		if localNow.After(start) {
+			start = localNow
+		}
+	}
+	end := time.Date(saturday.Year(), saturday.Month(), saturday.Day(), 0, 0, 0, 0, req.Location).AddDate(0, 0, 2)
+	return timeutil.Period{Start: start, End: end}, nil
+}
+
+func resolveStorm(req ResolveRequest) (timeutil.Period, error) {
+	if req.StormStart.IsZero() {
+		return timeutil.Period{}, fmt.Errorf("storm report requires a start time")
+	}
+	if req.StormEnd.IsZero() {
+		return timeutil.Period{}, fmt.Errorf("storm report requires an end time")
+	}
+	if !req.StormEnd.After(req.StormStart) {
+		return timeutil.Period{}, fmt.Errorf("storm report requires end time after start time")
+	}
+	return timeutil.Period{Start: req.StormStart, End: req.StormEnd}, nil
+}

internal/report/period_test.go

@@ -0,0 +1,308 @@
+package report
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+func TestDailyValidPeriod(t *testing.T) {
+	location := mustLoadLocation(t)
+	now := mustParse("2026-05-29T17:45:00-05:00")
+
+	resolved, err := Resolve(DailyToday, ResolveRequest{Now: now, Location: location})
+	if err != nil {
+		t.Fatalf("Resolve() error = %v", err)
+	}
+	assertPeriod(t, resolved.ValidPeriod, "2026-05-29T00:00:00-05:00", "2026-05-30T00:00:00-05:00")
+}
+
+func TestDailyValidPeriodCanUseExplicitDate(t *testing.T) {
+	location := mustLoadLocation(t)
+	now := mustParse("2026-05-29T17:45:00-05:00")
+	date := mustParse("2026-05-31T12:00:00-05:00")
+
+	resolved, err := Resolve(DailyToday, ResolveRequest{Now: now, Location: location, Date: date})
+	if err != nil {
+		t.Fatalf("Resolve() error = %v", err)
+	}
+	assertPeriod(t, resolved.ValidPeriod, "2026-05-31T00:00:00-05:00", "2026-06-01T00:00:00-05:00")
+}
+
+func TestTomorrowValidPeriodFromEveningGeneration(t *testing.T) {
+	location := mustLoadLocation(t)
+	now := mustParse("2026-05-29T20:00:00-05:00")
+
+	resolved, err := Resolve(DailyTomorrow, ResolveRequest{Now: now, Location: location})
+	if err != nil {
+		t.Fatalf("Resolve() error = %v", err)
+	}
+	assertPeriod(t, resolved.ValidPeriod, "2026-05-30T00:00:00-05:00", "2026-05-31T00:00:00-05:00")
+	if resolved.Definition.PromptID != "weather.daily_report" {
+		t.Fatalf("PromptID = %q, want weather.daily_report", resolved.Definition.PromptID)
+	}
+}
+
+func TestThreeDayPeriodCalculation(t *testing.T) {
+	location := mustLoadLocation(t)
+	now := mustParse("2026-05-29T05:00:00-05:00")
+
+	resolved, err := Resolve(ThreeDay, ResolveRequest{Now: now, Location: location})
+	if err != nil {
+		t.Fatalf("Resolve() error = %v", err)
+	}
+	assertPeriod(t, resolved.ValidPeriod, "2026-05-29T05:00:00-05:00", "2026-06-01T00:00:00-05:00")
+}
+
+func TestWeekendPeriodCalculation(t *testing.T) {
+	location := mustLoadLocation(t)
+	tests := []struct {
+		name  string
+		now   string
+		start string
+		end   string
+	}{
+		{name: "monday", now: "2026-05-25T05:00:00-05:00", start: "2026-05-30T00:00:00-05:00", end: "2026-06-01T00:00:00-05:00"},
+		{name: "tuesday", now: "2026-05-26T05:00:00-05:00", start: "2026-05-30T00:00:00-05:00", end: "2026-06-01T00:00:00-05:00"},
+		{name: "wednesday", now: "2026-05-27T05:00:00-05:00", start: "2026-05-30T00:00:00-05:00", end: "2026-06-01T00:00:00-05:00"},
+		{name: "thursday", now: "2026-05-28T05:00:00-05:00", start: "2026-05-30T00:00:00-05:00", end: "2026-06-01T00:00:00-05:00"},
+		{name: "friday before evening", now: "2026-05-29T05:00:00-05:00", start: "2026-05-29T18:00:00-05:00", end: "2026-06-01T00:00:00-05:00"},
+		{name: "friday after evening", now: "2026-05-29T19:30:00-05:00", start: "2026-05-29T19:30:00-05:00", end: "2026-06-01T00:00:00-05:00"},
+		{name: "saturday", now: "2026-05-30T08:00:00-05:00", start: "2026-05-30T08:00:00-05:00", end: "2026-06-01T00:00:00-05:00"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			resolved, err := Resolve(Weekend, ResolveRequest{Now: mustParse(tt.now), Location: location})
+			if err != nil {
+				t.Fatalf("Resolve() error = %v", err)
+			}
+			assertPeriod(t, resolved.ValidPeriod, tt.start, tt.end)
+		})
+	}
+}
+
+func TestWeekendSundayErrors(t *testing.T) {
+	location := mustLoadLocation(t)
+	_, err := Resolve(Weekend, ResolveRequest{Now: mustParse("2026-05-31T08:00:00-05:00"), Location: location})
+	if err == nil {
+		t.Fatal("Resolve() error = nil, want Sunday weekend error")
+	}
+	if !strings.Contains(err.Error(), "Sunday") {
+		t.Fatalf("error = %q, want Sunday context", err.Error())
+	}
+}
+
+func TestStormManualPeriodParsingAndValidation(t *testing.T) {
+	location := mustLoadLocation(t)
+	period, err := ParseStormPeriod("2026-05-29T18:00", "2026-05-30T06:00:00-05:00", location)
+	if err != nil {
+		t.Fatalf("ParseStormPeriod() error = %v", err)
+	}
+	assertPeriod(t, period, "2026-05-29T18:00:00-05:00", "2026-05-30T06:00:00-05:00")
+
+	_, err = ParseStormPeriod("2026-05-30T06:00", "2026-05-29T18:00", location)
+	if err == nil {
+		t.Fatal("ParseStormPeriod() error = nil, want invalid period error")
+	}
+}
+
+func TestStormResolve(t *testing.T) {
+	location := mustLoadLocation(t)
+	resolved, err := Resolve(Storm, ResolveRequest{
+		Now:        mustParse("2026-05-29T12:00:00-05:00"),
+		Location:   location,
+		StormStart: mustParse("2026-05-29T18:00:00-05:00"),
+		StormEnd:   mustParse("2026-05-30T06:00:00-05:00"),
+	})
+	if err != nil {
+		t.Fatalf("Resolve() error = %v", err)
+	}
+	assertPeriod(t, resolved.ValidPeriod, "2026-05-29T18:00:00-05:00", "2026-05-30T06:00:00-05:00")
+	if resolved.Definition.ComparisonStrategy != CompareExplicitWindow {
+		t.Fatalf("ComparisonStrategy = %q, want explicit event window", resolved.Definition.ComparisonStrategy)
+	}
+}
+
+func TestMorningBatchSkipsWeekendOnSunday(t *testing.T) {
+	location := mustLoadLocation(t)
+	resolved, err := DefaultRegistry().BatchReports(Morning, ResolveRequest{
+		Now:      mustParse("2026-05-31T06:00:00-05:00"),
+		Location: location,
+	})
+	if err != nil {
+		t.Fatalf("BatchReports() error = %v", err)
+	}
+	ids := resolvedIDs(resolved)
+	if strings.Join(ids, ",") != "daily_today,three_day" {
+		t.Fatalf("ids = %v, want daily_today and three_day", ids)
+	}
+}
+
+func TestEveningBatchIncludesTomorrow(t *testing.T) {
+	location := mustLoadLocation(t)
+	resolved, err := DefaultRegistry().BatchReports(Evening, ResolveRequest{
+		Now:      mustParse("2026-05-29T18:00:00-05:00"),
+		Location: location,
+	})
+	if err != nil {
+		t.Fatalf("BatchReports() error = %v", err)
+	}
+	ids := resolvedIDs(resolved)
+	if strings.Join(ids, ",") != "daily_tomorrow" {
+		t.Fatalf("ids = %v, want daily_tomorrow", ids)
+	}
+}
+
+func TestRegistryLookupErrorIsActionable(t *testing.T) {
+	_, err := DefaultRegistry().Lookup(ID("unknown"))
+	if err == nil {
+		t.Fatal("Lookup() error = nil, want unknown report error")
+	}
+	if !strings.Contains(err.Error(), `unknown report "unknown"`) {
+		t.Fatalf("error = %q, want unknown report context", err.Error())
+	}
+}
+
+func TestRegistryDefinitionsHavePromptIDsAndComparisonStrategies(t *testing.T) {
+	for _, definition := range DefaultRegistry().All() {
+		if definition.PromptID == "" {
+			t.Fatalf("%s PromptID is empty", definition.ID)
+		}
+		if definition.ComparisonStrategy == "" {
+			t.Fatalf("%s ComparisonStrategy is empty", definition.ID)
+		}
+	}
+}
+
+func TestRegistryDefinitionsDeclarePathAndCompatibilityPolicy(t *testing.T) {
+	tests := []struct {
+		id                 ID
+		artifactGroup      string
+		batchOutputName    string
+		generated          bool
+		compatiblePriorIDs []ID
+	}{
+		{
+			id:                 DailyToday,
+			artifactGroup:      "daily",
+			batchOutputName:    "daily.md",
+			generated:          true,
+			compatiblePriorIDs: []ID{DailyToday, DailyTomorrow},
+		},
+		{
+			id:                 DailyTomorrow,
+			artifactGroup:      "daily",
+			batchOutputName:    "tomorrow.md",
+			generated:          true,
+			compatiblePriorIDs: []ID{DailyToday, DailyTomorrow},
+		},
+		{
+			id:                 ThreeDay,
+			artifactGroup:      "three-day",
+			batchOutputName:    "three-day.md",
+			generated:          true,
+			compatiblePriorIDs: []ID{ThreeDay},
+		},
+		{
+			id:                 Weekend,
+			artifactGroup:      "weekend",
+			batchOutputName:    "weekend.md",
+			generated:          true,
+			compatiblePriorIDs: []ID{Weekend},
+		},
+		{
+			id:                 Storm,
+			artifactGroup:      "storm",
+			batchOutputName:    "storm.md",
+			generated:          true,
+			compatiblePriorIDs: []ID{Storm},
+		},
+	}
+
+	registry := DefaultRegistry()
+	for _, tt := range tests {
+		t.Run(string(tt.id), func(t *testing.T) {
+			definition, err := registry.Lookup(tt.id)
+			if err != nil {
+				t.Fatalf("Lookup() error = %v", err)
+			}
+			if definition.ArtifactGroup != tt.artifactGroup {
+				t.Fatalf("ArtifactGroup = %q, want %q", definition.ArtifactGroup, tt.artifactGroup)
+			}
+			if definition.BatchOutputName != tt.batchOutputName {
+				t.Fatalf("BatchOutputName = %q, want %q", definition.BatchOutputName, tt.batchOutputName)
+			}
+			if definition.Generated != tt.generated {
+				t.Fatalf("Generated = %t, want %t", definition.Generated, tt.generated)
+			}
+			if !reflect.DeepEqual(definition.CompatiblePriorIDs, tt.compatiblePriorIDs) {
+				t.Fatalf("CompatiblePriorIDs = %#v, want %#v", definition.CompatiblePriorIDs, tt.compatiblePriorIDs)
+			}
+			for _, id := range tt.compatiblePriorIDs {
+				if !definition.CompatibleWithPrior(id) {
+					t.Fatalf("CompatibleWithPrior(%q) = false, want true", id)
+				}
+			}
+		})
+	}
+}
+
+func TestResolvedMetadata(t *testing.T) {
+	location := mustLoadLocation(t)
+	resolved, err := Resolve(DailyToday, ResolveRequest{Now: mustParse("2026-05-29T05:00:00-05:00"), Location: location})
+	if err != nil {
+		t.Fatalf("Resolve() error = %v", err)
+	}
+	metadata := resolved.Metadata()
+	if metadata.ReportID != DailyToday {
+		t.Fatalf("ReportID = %q, want daily_today", metadata.ReportID)
+	}
+	if metadata.PromptID != "weather.daily_report" {
+		t.Fatalf("PromptID = %q, want weather.daily_report", metadata.PromptID)
+	}
+	if !strings.Contains(metadata.RunID, "daily_today") {
+		t.Fatalf("RunID = %q, want report id", metadata.RunID)
+	}
+}
+
+func assertPeriod(t *testing.T, period timeutil.Period, wantStart string, wantEnd string) {
+	t.Helper()
+	if !period.IsValid() {
+		t.Fatalf("period = %#v, want valid", period)
+	}
+	if period.Start.Format(time.RFC3339) != wantStart {
+		t.Fatalf("Start = %s, want %s", period.Start.Format(time.RFC3339), wantStart)
+	}
+	if period.End.Format(time.RFC3339) != wantEnd {
+		t.Fatalf("End = %s, want %s", period.End.Format(time.RFC3339), wantEnd)
+	}
+}
+
+func resolvedIDs(resolved []Resolved) []string {
+	ids := make([]string, 0, len(resolved))
+	for _, item := range resolved {
+		ids = append(ids, string(item.Definition.ID))
+	}
+	return ids
+}
+
+func mustLoadLocation(t *testing.T) *time.Location {
+	t.Helper()
+	location, err := time.LoadLocation("America/Chicago")
+	if err != nil {
+		t.Fatalf("load location: %v", err)
+	}
+	return location
+}
+
+func mustParse(value string) time.Time {
+	parsed, err := time.Parse(time.RFC3339, value)
+	if err != nil {
+		panic(err)
+	}
+	return parsed
+}

internal/report/registry.go

@@ -0,0 +1,103 @@
+package report
+
+import "fmt"
+
+type Registry struct {
+	definitions map[ID]Definition
+}
+
+func DefaultRegistry() Registry {
+	definitions := []Definition{
+		{
+			ID:                 DailyToday,
+			Name:               "Daily Report",
+			PromptID:           "weather.daily_report",
+			ComparisonStrategy: CompareSameValidDate,
+			ArtifactGroup:      "daily",
+			BatchOutputName:    "daily.md",
+			Generated:          true,
+			CompatiblePriorIDs: []ID{DailyToday, DailyTomorrow},
+			Morning:            true,
+			resolve:            resolveDailyToday,
+		},
+		{
+			ID:                 DailyTomorrow,
+			Name:               "Tomorrow Planning Brief",
+			PromptID:           "weather.daily_report",
+			ComparisonStrategy: CompareSameValidDate,
+			ArtifactGroup:      "daily",
+			BatchOutputName:    "tomorrow.md",
+			Generated:          true,
+			CompatiblePriorIDs: []ID{DailyToday, DailyTomorrow},
+			Evening:            true,
+			resolve:            resolveDailyTomorrow,
+		},
+		{
+			ID:                 ThreeDay,
+			Name:               "3-Day Outlook",
+			PromptID:           "weather.three_day_outlook",
+			ComparisonStrategy: CompareSameValidDate,
+			ArtifactGroup:      "three-day",
+			BatchOutputName:    "three-day.md",
+			Generated:          true,
+			CompatiblePriorIDs: []ID{ThreeDay},
+			Morning:            true,
+			resolve:            resolveThreeDay,
+		},
+		{
+			ID:                 Weekend,
+			Name:               "Weekend Outlook",
+			PromptID:           "weather.weekend_outlook",
+			ComparisonStrategy: CompareWeekendWindow,
+			ArtifactGroup:      "weekend",
+			BatchOutputName:    "weekend.md",
+			Generated:          true,
+			CompatiblePriorIDs: []ID{Weekend},
+			Morning:            true,
+			resolve:            resolveWeekend,
+		},
+		{
+			ID:                 Storm,
+			Name:               "Storm Report",
+			PromptID:           "weather.storm_report",
+			ComparisonStrategy: CompareExplicitWindow,
+			ArtifactGroup:      "storm",
+			BatchOutputName:    "storm.md",
+			Generated:          true,
+			CompatiblePriorIDs: []ID{Storm},
+			resolve:            resolveStorm,
+		},
+	}
+	registry := Registry{definitions: map[ID]Definition{}}
+	for _, definition := range definitions {
+		registry.definitions[definition.ID] = definition
+	}
+	return registry
+}
+
+func (r Registry) Lookup(id ID) (Definition, error) {
+	definition, ok := r.definitions[id]
+	if !ok {
+		return Definition{}, fmt.Errorf("unknown report %q", id)
+	}
+	return definition, nil
+}
+
+func (r Registry) MustLookup(id ID) Definition {
+	definition, err := r.Lookup(id)
+	if err != nil {
+		panic(err)
+	}
+	return definition
+}
+
+func (r Registry) All() []Definition {
+	ids := []ID{DailyToday, DailyTomorrow, ThreeDay, Weekend, Storm}
+	out := make([]Definition, 0, len(ids))
+	for _, id := range ids {
+		if definition, ok := r.definitions[id]; ok {
+			out = append(out, definition)
+		}
+	}
+	return out
+}

internal/state/filesystem.go

@@ -0,0 +1,396 @@
+package state
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/fileutil"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptinput"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+)
+
+type FilesystemStore struct {
+	root            string
+	snapshotsDir    string
+	reportsDir      string
+	dataPackagesDir string
+	preflightDir    string
+}
+
+type ArtifactPaths struct {
+	Briefing       string `json:"briefing"`
+	Metadata       string `json:"metadata"`
+	DataPackage    string `json:"dataPackage"`
+	Preflight      string `json:"preflight"`
+	RenderedReport string `json:"renderedReport,omitempty"`
+}
+
+type ReportRecord struct {
+	RunID        string    `json:"runId"`
+	ReportID     report.ID `json:"reportId"`
+	Variant      string    `json:"variant,omitempty"`
+	PromptID     string    `json:"promptId"`
+	GeneratedAt  string    `json:"generatedAt"`
+	ValidStart   string    `json:"validStart"`
+	ValidEnd     string    `json:"validEnd"`
+	MetadataPath string    `json:"metadataPath"`
+	BriefingPath string    `json:"briefingPath"`
+	ReportPath   string    `json:"reportPath,omitempty"`
+	Warnings     int       `json:"warnings"`
+	metadata     Metadata
+}
+
+func NewFilesystemStore(cfg config.WorkspaceConfig) (*FilesystemStore, error) {
+	if cfg.Root == "" {
+		return nil, fmt.Errorf("workspace root is required")
+	}
+	for name, value := range map[string]string{
+		"snapshots_dir":     cfg.SnapshotsDir,
+		"reports_dir":       cfg.ReportsDir,
+		"data_packages_dir": cfg.DataPackagesDir,
+		"preflight_dir":     cfg.PreflightDir,
+	} {
+		if err := validateRelativeDir(name, value); err != nil {
+			return nil, err
+		}
+	}
+	return &FilesystemStore{
+		root:            filepath.Clean(cfg.Root),
+		snapshotsDir:    filepath.Clean(cfg.SnapshotsDir),
+		reportsDir:      filepath.Clean(cfg.ReportsDir),
+		dataPackagesDir: filepath.Clean(cfg.DataPackagesDir),
+		preflightDir:    filepath.Clean(cfg.PreflightDir),
+	}, nil
+}
+
+func (s *FilesystemStore) Paths(resolved report.Resolved) (ArtifactPaths, error) {
+	if s == nil {
+		return ArtifactPaths{}, fmt.Errorf("state store is required")
+	}
+	metadata := resolved.Metadata()
+	if metadata.RunID == "" {
+		return ArtifactPaths{}, fmt.Errorf("run id is required")
+	}
+	group := resolved.Definition.ArtifactGroup
+	if group == "" {
+		return ArtifactPaths{}, fmt.Errorf("report %q has no artifact group", resolved.Definition.ID)
+	}
+	validDate := resolved.ValidPeriod.Start.Format("2006-01-02")
+	filenameBase := metadata.RunID
+	return ArtifactPaths{
+		Briefing:       s.join(s.snapshotsDir, group, validDate, filenameBase+".briefing.json"),
+		Metadata:       s.join(s.snapshotsDir, group, validDate, filenameBase+".metadata.json"),
+		DataPackage:    s.join(s.dataPackagesDir, group, validDate, filenameBase+".data_package.json"),
+		Preflight:      s.join(s.preflightDir, group, validDate, filenameBase+".render.json"),
+		RenderedReport: s.join(s.reportsDir, group, filenameBase+".md"),
+	}, nil
+}
+
+func (s *FilesystemStore) SaveBriefing(_ context.Context, resolved report.Resolved, pkg briefing.Package) (string, error) {
+	paths, err := s.Paths(resolved)
+	if err != nil {
+		return "", err
+	}
+	if err := fileutil.WriteJSONAtomic(paths.Briefing, pkg); err != nil {
+		return "", err
+	}
+	return paths.Briefing, nil
+}
+
+func (s *FilesystemStore) SaveDataPackage(_ context.Context, resolved report.Resolved, pkg promptinput.Package) (string, error) {
+	paths, err := s.Paths(resolved)
+	if err != nil {
+		return "", err
+	}
+	if err := promptinput.Validate(pkg); err != nil {
+		return "", err
+	}
+	if err := fileutil.WriteJSONAtomic(paths.DataPackage, pkg); err != nil {
+		return "", err
+	}
+	return paths.DataPackage, nil
+}
+
+func (s *FilesystemStore) SavePreflight(_ context.Context, resolved report.Resolved, artifact PreflightArtifact) (string, error) {
+	paths, err := s.Paths(resolved)
+	if err != nil {
+		return "", err
+	}
+	if err := fileutil.WriteJSONAtomic(paths.Preflight, artifact); err != nil {
+		return "", err
+	}
+	return paths.Preflight, nil
+}
+
+func (s *FilesystemStore) PrepareRenderedReport(_ context.Context, resolved report.Resolved) (string, error) {
+	paths, err := s.Paths(resolved)
+	if err != nil {
+		return "", err
+	}
+	if err := os.MkdirAll(filepath.Dir(paths.RenderedReport), 0o755); err != nil {
+		return "", fmt.Errorf("create rendered report directory %q: %w", filepath.Dir(paths.RenderedReport), err)
+	}
+	return paths.RenderedReport, nil
+}
+
+func (s *FilesystemStore) SaveMetadata(_ context.Context, metadata Metadata) (string, error) {
+	if metadata.RunID == "" {
+		return "", fmt.Errorf("metadata run id is required")
+	}
+	if metadata.BriefingPath == "" {
+		return "", fmt.Errorf("metadata briefing path is required")
+	}
+	if metadata.DataPackagePath == "" {
+		return "", fmt.Errorf("metadata data package path is required")
+	}
+	if metadata.PreflightPath == "" {
+		return "", fmt.Errorf("metadata preflight path is required")
+	}
+	if metadata.MetadataPath == "" {
+		return "", fmt.Errorf("metadata path is required")
+	}
+	if err := fileutil.WriteJSONAtomic(metadata.MetadataPath, metadata); err != nil {
+		return "", err
+	}
+	return metadata.MetadataPath, nil
+}
+
+func (s *FilesystemStore) FindPriorSnapshot(_ context.Context, resolved report.Resolved) (*PriorSnapshot, error) {
+	if resolved.Definition.ComparisonStrategy != report.CompareSameValidDate && resolved.Definition.ComparisonStrategy != report.CompareWeekendWindow {
+		return nil, nil
+	}
+	group := resolved.Definition.ArtifactGroup
+	if group == "" {
+		return nil, fmt.Errorf("report %q has no artifact group", resolved.Definition.ID)
+	}
+	dirs, err := s.metadataDirectories(resolved, group)
+	if err != nil {
+		return nil, err
+	}
+
+	var candidates []Metadata
+	for _, dir := range dirs {
+		entries, err := os.ReadDir(dir)
+		if err != nil {
+			if os.IsNotExist(err) {
+				continue
+			}
+			return nil, fmt.Errorf("read snapshot metadata directory %q: %w", dir, err)
+		}
+		for _, entry := range entries {
+			if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".metadata.json") {
+				continue
+			}
+			path := filepath.Join(dir, entry.Name())
+			var metadata Metadata
+			if err := readJSON(path, &metadata); err != nil {
+				return nil, err
+			}
+			if metadata.RunID == resolved.Metadata().RunID {
+				continue
+			}
+			if !resolved.Definition.CompatibleWithPrior(metadata.ReportID) {
+				continue
+			}
+			if !comparablePeriod(metadata, resolved) {
+				continue
+			}
+			if !metadata.GeneratedAt.Before(resolved.GeneratedAt) {
+				continue
+			}
+			candidates = append(candidates, metadata)
+		}
+	}
+	if len(candidates) == 0 {
+		return nil, nil
+	}
+	sort.Slice(candidates, func(i, j int) bool {
+		return candidates[i].GeneratedAt.After(candidates[j].GeneratedAt)
+	})
+	return &PriorSnapshot{
+		Metadata:     candidates[0],
+		BriefingPath: candidates[0].BriefingPath,
+	}, nil
+}
+
+func (s *FilesystemStore) ListReports(_ context.Context, limit int) ([]ReportRecord, error) {
+	if s == nil {
+		return nil, fmt.Errorf("state store is required")
+	}
+	root := s.join(s.snapshotsDir)
+	if _, err := os.Stat(root); err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, fmt.Errorf("inspect %q: %w", root, err)
+	}
+	var records []ReportRecord
+	err := filepath.WalkDir(root, func(path string, entry os.DirEntry, err error) error {
+		if err != nil {
+			return fmt.Errorf("inspect %q: %w", path, err)
+		}
+		if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".metadata.json") {
+			return nil
+		}
+		record, err := s.reportRecord(path)
+		if err != nil {
+			return err
+		}
+		records = append(records, record)
+		return nil
+	})
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	sort.Slice(records, func(i, j int) bool {
+		return records[i].metadata.GeneratedAt.After(records[j].metadata.GeneratedAt)
+	})
+	if limit > 0 && len(records) > limit {
+		records = records[:limit]
+	}
+	return records, nil
+}
+
+func (s *FilesystemStore) LoadMetadataByRunID(ctx context.Context, runID string) (Metadata, string, error) {
+	if strings.TrimSpace(runID) == "" {
+		return Metadata{}, "", fmt.Errorf("run id is required")
+	}
+	records, err := s.ListReports(ctx, 0)
+	if err != nil {
+		return Metadata{}, "", err
+	}
+	for _, record := range records {
+		if record.RunID == runID {
+			return record.metadata, record.MetadataPath, nil
+		}
+	}
+	return Metadata{}, "", fmt.Errorf("metadata for run id %q was not found", runID)
+}
+
+func (s *FilesystemStore) LoadDataPackage(_ context.Context, path string) (promptinput.Package, error) {
+	if path == "" {
+		return promptinput.Package{}, fmt.Errorf("data package path is required")
+	}
+	var pkg promptinput.Package
+	if err := readJSON(path, &pkg); err != nil {
+		return promptinput.Package{}, err
+	}
+	return pkg, nil
+}
+
+func (s *FilesystemStore) reportRecord(path string) (ReportRecord, error) {
+	var metadata Metadata
+	if err := readJSON(path, &metadata); err != nil {
+		return ReportRecord{}, err
+	}
+	return ReportRecord{
+		RunID:        metadata.RunID,
+		ReportID:     metadata.ReportID,
+		Variant:      metadata.Variant,
+		PromptID:     metadata.PromptID,
+		GeneratedAt:  metadata.GeneratedAt.Format(time.RFC3339Nano),
+		ValidStart:   metadata.ValidPeriod.Start.Format(time.RFC3339Nano),
+		ValidEnd:     metadata.ValidPeriod.End.Format(time.RFC3339Nano),
+		MetadataPath: path,
+		BriefingPath: metadata.BriefingPath,
+		ReportPath:   metadata.RenderedReportPath,
+		Warnings:     len(metadata.SourceWarnings),
+		metadata:     metadata,
+	}, nil
+}
+
+func (s *FilesystemStore) metadataDirectories(resolved report.Resolved, group string) ([]string, error) {
+	paths, err := s.Paths(resolved)
+	if err != nil {
+		return nil, err
+	}
+	if resolved.Definition.ComparisonStrategy != report.CompareWeekendWindow {
+		return []string{filepath.Dir(paths.Metadata)}, nil
+	}
+	root := s.join(s.snapshotsDir, group)
+	entries, err := os.ReadDir(root)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, fmt.Errorf("read snapshot group directory %q: %w", root, err)
+	}
+	var dirs []string
+	for _, entry := range entries {
+		if entry.IsDir() {
+			dirs = append(dirs, filepath.Join(root, entry.Name()))
+		}
+	}
+	return dirs, nil
+}
+
+func (s *FilesystemStore) join(parts ...string) string {
+	all := append([]string{s.root}, parts...)
+	return filepath.Join(all...)
+}
+
+func validateRelativeDir(name string, value string) error {
+	if value == "" {
+		return fmt.Errorf("%s is required", name)
+	}
+	if filepath.IsAbs(value) {
+		return fmt.Errorf("%s must be relative to workspace root", name)
+	}
+	cleaned := filepath.Clean(value)
+	if cleaned == "." || cleaned == ".." || strings.HasPrefix(cleaned, ".."+string(filepath.Separator)) {
+		return fmt.Errorf("%s must stay within workspace root", name)
+	}
+	return nil
+}
+
+func readJSON(path string, target any) error {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return fmt.Errorf("read %q: %w", path, err)
+	}
+	if err := json.Unmarshal(data, target); err != nil {
+		return fmt.Errorf("decode %q: %w", path, err)
+	}
+	return nil
+}
+
+func sameValidDate(metadata Metadata, resolved report.Resolved) bool {
+	return metadata.ValidPeriod.Start.Format("2006-01-02") == resolved.ValidPeriod.Start.Format("2006-01-02")
+}
+
+func comparablePeriod(metadata Metadata, resolved report.Resolved) bool {
+	switch resolved.Definition.ComparisonStrategy {
+	case report.CompareSameValidDate:
+		return sameValidDate(metadata, resolved)
+	case report.CompareWeekendWindow:
+		return sameWeekendWindow(metadata, resolved)
+	default:
+		return false
+	}
+}
+
+func sameWeekendWindow(metadata Metadata, resolved report.Resolved) bool {
+	return metadata.ValidPeriod.End.Equal(resolved.ValidPeriod.End) && !metadata.ValidPeriod.Start.After(resolved.ValidPeriod.Start)
+}
+
+func (s *FilesystemStore) LoadBriefing(_ context.Context, path string) (briefing.Package, error) {
+	if path == "" {
+		return briefing.Package{}, fmt.Errorf("briefing path is required")
+	}
+	var pkg briefing.Package
+	if err := readJSON(path, &pkg); err != nil {
+		return briefing.Package{}, err
+	}
+	return pkg, nil
+}

internal/state/filesystem_test.go

@@ -0,0 +1,499 @@
+package state
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptinput"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+func TestPathsUseRunIDAndWorkspace(t *testing.T) {
+	store := newTestStore(t)
+	resolved := resolveDailyAt(t, "2026-05-29T05:00:00-05:00")
+
+	paths, err := store.Paths(resolved)
+	if err != nil {
+		t.Fatalf("Paths() error = %v", err)
+	}
+
+	for _, want := range []string{
+		filepath.Join("snapshots", "daily", "2026-05-29", "20260529T100000.000000000Z_daily_today.briefing.json"),
+		filepath.Join("snapshots", "daily", "2026-05-29", "20260529T100000.000000000Z_daily_today.metadata.json"),
+		filepath.Join("data-packages", "daily", "2026-05-29", "20260529T100000.000000000Z_daily_today.data_package.json"),
+		filepath.Join("preflight", "daily", "2026-05-29", "20260529T100000.000000000Z_daily_today.render.json"),
+		filepath.Join("reports", "daily", "20260529T100000.000000000Z_daily_today.md"),
+	} {
+		if !strings.Contains(pathsString(paths), want) {
+			t.Fatalf("paths = %#v, want component %q", paths, want)
+		}
+	}
+}
+
+func TestSaveArtifactsAndMetadataRoundTrip(t *testing.T) {
+	store := newTestStore(t)
+	resolved := resolveDailyAt(t, "2026-05-29T05:00:00-05:00")
+	briefingPackage := stateBriefingPackage(resolved)
+	dataPackage, err := promptinput.Build(briefingPackage)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+
+	briefingPath, err := store.SaveBriefing(context.Background(), resolved, briefingPackage)
+	if err != nil {
+		t.Fatalf("SaveBriefing() error = %v", err)
+	}
+	dataPackagePath, err := store.SaveDataPackage(context.Background(), resolved, dataPackage)
+	if err != nil {
+		t.Fatalf("SaveDataPackage() error = %v", err)
+	}
+	preflightPath, err := store.SavePreflight(context.Background(), resolved, PreflightArtifact{Stdout: `{"ok":true}`})
+	if err != nil {
+		t.Fatalf("SavePreflight() error = %v", err)
+	}
+	renderedReportPath, err := store.PrepareRenderedReport(context.Background(), resolved)
+	if err != nil {
+		t.Fatalf("PrepareRenderedReport() error = %v", err)
+	}
+	if err := os.WriteFile(renderedReportPath, []byte("# Daily Report\n"), 0o600); err != nil {
+		t.Fatalf("write rendered report: %v", err)
+	}
+	var preflight PreflightArtifact
+	preflightData, err := os.ReadFile(preflightPath)
+	if err != nil {
+		t.Fatalf("read preflight: %v", err)
+	}
+	if err := json.Unmarshal(preflightData, &preflight); err != nil {
+		t.Fatalf("decode preflight: %v", err)
+	}
+	if preflight.Stdout != `{"ok":true}` {
+		t.Fatalf("preflight stdout = %q, want render stdout", preflight.Stdout)
+	}
+	paths, err := store.Paths(resolved)
+	if err != nil {
+		t.Fatalf("Paths() error = %v", err)
+	}
+	metadata := BuildMetadata(resolved, briefingPackage, ArtifactPaths{
+		Briefing:       briefingPath,
+		Metadata:       paths.Metadata,
+		DataPackage:    dataPackagePath,
+		Preflight:      preflightPath,
+		RenderedReport: renderedReportPath,
+	})
+	metadataPath, err := store.SaveMetadata(context.Background(), metadata)
+	if err != nil {
+		t.Fatalf("SaveMetadata() error = %v", err)
+	}
+
+	for _, path := range []string{briefingPath, dataPackagePath, preflightPath, renderedReportPath, metadataPath} {
+		if _, err := os.Stat(path); err != nil {
+			t.Fatalf("expected artifact %q: %v", path, err)
+		}
+	}
+	loadedBriefing, err := store.LoadBriefing(context.Background(), briefingPath)
+	if err != nil {
+		t.Fatalf("LoadBriefing() error = %v", err)
+	}
+	if loadedBriefing.Metadata.RunID != resolved.Metadata().RunID {
+		t.Fatalf("loaded briefing RunID = %q, want %q", loadedBriefing.Metadata.RunID, resolved.Metadata().RunID)
+	}
+	var decoded Metadata
+	data, err := os.ReadFile(metadataPath)
+	if err != nil {
+		t.Fatalf("read metadata: %v", err)
+	}
+	if err := json.Unmarshal(data, &decoded); err != nil {
+		t.Fatalf("decode metadata: %v", err)
+	}
+	if decoded.RunID != resolved.Metadata().RunID {
+		t.Fatalf("RunID = %q, want %q", decoded.RunID, resolved.Metadata().RunID)
+	}
+	if decoded.BriefingPath != briefingPath || decoded.DataPackagePath != dataPackagePath || decoded.PreflightPath != preflightPath {
+		t.Fatalf("metadata paths = %#v, want saved artifact paths", decoded)
+	}
+	if decoded.RenderedReportPath != renderedReportPath {
+		t.Fatalf("RenderedReportPath = %q, want %q", decoded.RenderedReportPath, renderedReportPath)
+	}
+	if decoded.Location == nil || decoded.Location.Name != "Brentwood" || decoded.Location.Timezone != "America/Chicago" {
+		t.Fatalf("metadata location = %#v, want briefing location", decoded.Location)
+	}
+	if strings.Contains(string(data), "MetadataPath") || strings.Contains(string(data), "metadataPath") {
+		t.Fatalf("metadata JSON includes runtime-only MetadataPath:\n%s", string(data))
+	}
+}
+
+func TestSaveMetadataUsesExplicitMetadataPath(t *testing.T) {
+	store := newTestStore(t)
+	resolved := resolveDailyAt(t, "2026-05-29T05:00:00-05:00")
+	briefingPackage := stateBriefingPackage(resolved)
+	paths, err := store.Paths(resolved)
+	if err != nil {
+		t.Fatalf("Paths() error = %v", err)
+	}
+	otherDir := filepath.Join(t.TempDir(), "other-artifacts")
+	otherBriefingPath := filepath.Join(otherDir, resolved.Metadata().RunID+".briefing.json")
+	derivedMetadataPath := filepath.Join(otherDir, resolved.Metadata().RunID+".metadata.json")
+
+	metadata := BuildMetadata(resolved, briefingPackage, ArtifactPaths{
+		Briefing:       otherBriefingPath,
+		Metadata:       paths.Metadata,
+		DataPackage:    paths.DataPackage,
+		Preflight:      paths.Preflight,
+		RenderedReport: paths.RenderedReport,
+	})
+	metadataPath, err := store.SaveMetadata(context.Background(), metadata)
+	if err != nil {
+		t.Fatalf("SaveMetadata() error = %v", err)
+	}
+	if metadataPath != paths.Metadata {
+		t.Fatalf("SaveMetadata() path = %q, want explicit metadata path %q", metadataPath, paths.Metadata)
+	}
+	if _, err := os.Stat(paths.Metadata); err != nil {
+		t.Fatalf("expected explicit metadata path %q: %v", paths.Metadata, err)
+	}
+	if _, err := os.Stat(derivedMetadataPath); !os.IsNotExist(err) {
+		t.Fatalf("derived metadata path stat error = %v, want not exist", err)
+	}
+}
+
+func TestFindPriorSnapshot(t *testing.T) {
+	store := newTestStore(t)
+	first := resolveDailyAt(t, "2026-05-29T05:00:00-05:00")
+	second := resolveDailyAt(t, "2026-05-29T08:00:00-05:00")
+	briefingPackage := stateBriefingPackage(first)
+	briefingPath, err := store.SaveBriefing(context.Background(), first, briefingPackage)
+	if err != nil {
+		t.Fatalf("SaveBriefing() error = %v", err)
+	}
+	paths, err := store.Paths(first)
+	if err != nil {
+		t.Fatalf("Paths() error = %v", err)
+	}
+	_, err = store.SaveMetadata(context.Background(), BuildMetadata(first, briefingPackage, ArtifactPaths{
+		Briefing:       briefingPath,
+		Metadata:       paths.Metadata,
+		DataPackage:    paths.DataPackage,
+		Preflight:      paths.Preflight,
+		RenderedReport: paths.RenderedReport,
+	}))
+	if err != nil {
+		t.Fatalf("SaveMetadata() error = %v", err)
+	}
+
+	prior, err := store.FindPriorSnapshot(context.Background(), second)
+	if err != nil {
+		t.Fatalf("FindPriorSnapshot() error = %v", err)
+	}
+	if prior == nil {
+		t.Fatal("FindPriorSnapshot() = nil, want prior snapshot")
+	}
+	if prior.Metadata.RunID != first.Metadata().RunID {
+		t.Fatalf("RunID = %q, want %q", prior.Metadata.RunID, first.Metadata().RunID)
+	}
+	if prior.BriefingPath != briefingPath {
+		t.Fatalf("BriefingPath = %q, want %q", prior.BriefingPath, briefingPath)
+	}
+}
+
+func TestFindPriorSnapshotUsesValidDate(t *testing.T) {
+	store := newTestStore(t)
+	previousDate := resolveDailyAt(t, "2026-05-28T05:00:00-05:00")
+	currentDate := resolveDailyAt(t, "2026-05-29T05:00:00-05:00")
+	briefingPackage := stateBriefingPackage(previousDate)
+	briefingPath, err := store.SaveBriefing(context.Background(), previousDate, briefingPackage)
+	if err != nil {
+		t.Fatalf("SaveBriefing() error = %v", err)
+	}
+	paths, err := store.Paths(previousDate)
+	if err != nil {
+		t.Fatalf("Paths() error = %v", err)
+	}
+	_, err = store.SaveMetadata(context.Background(), BuildMetadata(previousDate, briefingPackage, ArtifactPaths{
+		Briefing:       briefingPath,
+		Metadata:       paths.Metadata,
+		DataPackage:    paths.DataPackage,
+		Preflight:      paths.Preflight,
+		RenderedReport: paths.RenderedReport,
+	}))
+	if err != nil {
+		t.Fatalf("SaveMetadata() error = %v", err)
+	}
+
+	prior, err := store.FindPriorSnapshot(context.Background(), currentDate)
+	if err != nil {
+		t.Fatalf("FindPriorSnapshot() error = %v", err)
+	}
+	if prior != nil {
+		t.Fatalf("FindPriorSnapshot() = %#v, want nil for different valid date", prior)
+	}
+}
+
+func TestFindPriorSnapshotSupportsThreeDay(t *testing.T) {
+	store := newTestStore(t)
+	first := resolveThreeDayAt(t, "2026-05-29T05:00:00-05:00")
+	second := resolveThreeDayAt(t, "2026-05-29T08:00:00-05:00")
+	briefingPackage := stateThreeDayBriefingPackage(first)
+	briefingPath, err := store.SaveBriefing(context.Background(), first, briefingPackage)
+	if err != nil {
+		t.Fatalf("SaveBriefing() error = %v", err)
+	}
+	paths, err := store.Paths(first)
+	if err != nil {
+		t.Fatalf("Paths() error = %v", err)
+	}
+	_, err = store.SaveMetadata(context.Background(), BuildMetadata(first, briefingPackage, ArtifactPaths{
+		Briefing:       briefingPath,
+		Metadata:       paths.Metadata,
+		DataPackage:    paths.DataPackage,
+		Preflight:      paths.Preflight,
+		RenderedReport: paths.RenderedReport,
+	}))
+	if err != nil {
+		t.Fatalf("SaveMetadata() error = %v", err)
+	}
+
+	prior, err := store.FindPriorSnapshot(context.Background(), second)
+	if err != nil {
+		t.Fatalf("FindPriorSnapshot() error = %v", err)
+	}
+	if prior == nil {
+		t.Fatal("FindPriorSnapshot() = nil, want prior 3-day snapshot")
+	}
+	if prior.Metadata.RunID != first.Metadata().RunID {
+		t.Fatalf("RunID = %q, want %q", prior.Metadata.RunID, first.Metadata().RunID)
+	}
+}
+
+func TestFindPriorSnapshotSupportsWeekend(t *testing.T) {
+	store := newTestStore(t)
+	first := resolveWeekendAt(t, "2026-05-29T05:00:00-05:00")
+	second := resolveWeekendAt(t, "2026-05-29T08:00:00-05:00")
+	briefingPackage := stateWeekendBriefingPackage(first)
+	briefingPath, err := store.SaveBriefing(context.Background(), first, briefingPackage)
+	if err != nil {
+		t.Fatalf("SaveBriefing() error = %v", err)
+	}
+	paths, err := store.Paths(first)
+	if err != nil {
+		t.Fatalf("Paths() error = %v", err)
+	}
+	_, err = store.SaveMetadata(context.Background(), BuildMetadata(first, briefingPackage, ArtifactPaths{
+		Briefing:       briefingPath,
+		Metadata:       paths.Metadata,
+		DataPackage:    paths.DataPackage,
+		Preflight:      paths.Preflight,
+		RenderedReport: paths.RenderedReport,
+	}))
+	if err != nil {
+		t.Fatalf("SaveMetadata() error = %v", err)
+	}
+
+	prior, err := store.FindPriorSnapshot(context.Background(), second)
+	if err != nil {
+		t.Fatalf("FindPriorSnapshot() error = %v", err)
+	}
+	if prior == nil {
+		t.Fatal("FindPriorSnapshot() = nil, want prior weekend snapshot")
+	}
+	if prior.Metadata.RunID != first.Metadata().RunID {
+		t.Fatalf("RunID = %q, want %q", prior.Metadata.RunID, first.Metadata().RunID)
+	}
+}
+
+func TestFindPriorSnapshotSupportsNarrowedWeekendPeriod(t *testing.T) {
+	store := newTestStore(t)
+	first := resolveWeekendAt(t, "2026-05-29T19:00:00-05:00")
+	second := resolveWeekendAt(t, "2026-05-30T08:00:00-05:00")
+	briefingPackage := stateWeekendBriefingPackage(first)
+	briefingPath, err := store.SaveBriefing(context.Background(), first, briefingPackage)
+	if err != nil {
+		t.Fatalf("SaveBriefing() error = %v", err)
+	}
+	paths, err := store.Paths(first)
+	if err != nil {
+		t.Fatalf("Paths() error = %v", err)
+	}
+	_, err = store.SaveMetadata(context.Background(), BuildMetadata(first, briefingPackage, ArtifactPaths{
+		Briefing:       briefingPath,
+		Metadata:       paths.Metadata,
+		DataPackage:    paths.DataPackage,
+		Preflight:      paths.Preflight,
+		RenderedReport: paths.RenderedReport,
+	}))
+	if err != nil {
+		t.Fatalf("SaveMetadata() error = %v", err)
+	}
+
+	prior, err := store.FindPriorSnapshot(context.Background(), second)
+	if err != nil {
+		t.Fatalf("FindPriorSnapshot() error = %v", err)
+	}
+	if prior == nil {
+		t.Fatal("FindPriorSnapshot() = nil, want prior narrowed weekend snapshot")
+	}
+	if prior.Metadata.RunID != first.Metadata().RunID {
+		t.Fatalf("RunID = %q, want %q", prior.Metadata.RunID, first.Metadata().RunID)
+	}
+}
+
+func TestFilesystemStoreRejectsUnsafeDirs(t *testing.T) {
+	cfg := config.Defaults().Workspace
+	cfg.Root = t.TempDir()
+	cfg.SnapshotsDir = "../snapshots"
+
+	_, err := NewFilesystemStore(cfg)
+	if err == nil {
+		t.Fatal("NewFilesystemStore() error = nil, want unsafe path error")
+	}
+	if !strings.Contains(err.Error(), "within workspace root") {
+		t.Fatalf("error = %q, want path safety context", err.Error())
+	}
+}
+
+func newTestStore(t *testing.T) *FilesystemStore {
+	t.Helper()
+	cfg := config.Defaults().Workspace
+	cfg.Root = t.TempDir()
+	store, err := NewFilesystemStore(cfg)
+	if err != nil {
+		t.Fatalf("NewFilesystemStore() error = %v", err)
+	}
+	return store
+}
+
+func resolveDailyAt(t *testing.T, value string) report.Resolved {
+	t.Helper()
+	location, err := timeutil.LoadLocation("America/Chicago")
+	if err != nil {
+		t.Fatalf("LoadLocation() error = %v", err)
+	}
+	now, err := time.Parse(time.RFC3339, value)
+	if err != nil {
+		t.Fatalf("parse time: %v", err)
+	}
+	resolved, err := report.DefaultRegistry().Resolve(report.DailyToday, report.ResolveRequest{
+		Now:      now,
+		Location: location,
+	})
+	if err != nil {
+		t.Fatalf("Resolve() error = %v", err)
+	}
+	return resolved
+}
+
+func resolveThreeDayAt(t *testing.T, value string) report.Resolved {
+	t.Helper()
+	location, err := timeutil.LoadLocation("America/Chicago")
+	if err != nil {
+		t.Fatalf("LoadLocation() error = %v", err)
+	}
+	now, err := time.Parse(time.RFC3339, value)
+	if err != nil {
+		t.Fatalf("parse time: %v", err)
+	}
+	resolved, err := report.DefaultRegistry().Resolve(report.ThreeDay, report.ResolveRequest{
+		Now:      now,
+		Location: location,
+	})
+	if err != nil {
+		t.Fatalf("Resolve() error = %v", err)
+	}
+	return resolved
+}
+
+func resolveWeekendAt(t *testing.T, value string) report.Resolved {
+	t.Helper()
+	location, err := timeutil.LoadLocation("America/Chicago")
+	if err != nil {
+		t.Fatalf("LoadLocation() error = %v", err)
+	}
+	now, err := time.Parse(time.RFC3339, value)
+	if err != nil {
+		t.Fatalf("parse time: %v", err)
+	}
+	resolved, err := report.DefaultRegistry().Resolve(report.Weekend, report.ResolveRequest{
+		Now:      now,
+		Location: location,
+	})
+	if err != nil {
+		t.Fatalf("Resolve() error = %v", err)
+	}
+	return resolved
+}
+
+func stateBriefingPackage(resolved report.Resolved) briefing.Package {
+	return briefing.Package{
+		Metadata: briefing.Metadata{
+			SchemaVersion: briefing.SchemaVersion,
+			RunID:         resolved.Metadata().RunID,
+			ReportID:      resolved.Definition.ID,
+			Variant:       "today",
+			PromptID:      resolved.Definition.PromptID,
+			GeneratedAt:   resolved.GeneratedAt,
+			Units:         "us",
+			Timezone:      resolved.Timezone,
+			Location: &briefing.LocationContext{
+				ID:       "home",
+				Name:     "Brentwood",
+				Region:   "St. Louis Metro",
+				Timezone: resolved.Timezone,
+			},
+			ValidPeriod: resolved.ValidPeriod,
+		},
+		Daily: &briefing.Daily{ForecastSummaryDate: "2026-05-29"},
+	}
+}
+
+func stateThreeDayBriefingPackage(resolved report.Resolved) briefing.Package {
+	return briefing.Package{
+		Metadata: briefing.Metadata{
+			SchemaVersion: briefing.SchemaVersion,
+			RunID:         resolved.Metadata().RunID,
+			ReportID:      resolved.Definition.ID,
+			PromptID:      resolved.Definition.PromptID,
+			GeneratedAt:   resolved.GeneratedAt,
+			Units:         "us",
+			Timezone:      resolved.Timezone,
+			ValidPeriod:   resolved.ValidPeriod,
+		},
+		ThreeDay: &briefing.ThreeDay{
+			Days: []briefing.OutlookDay{{Date: "2026-05-29"}},
+		},
+	}
+}
+
+func stateWeekendBriefingPackage(resolved report.Resolved) briefing.Package {
+	return briefing.Package{
+		Metadata: briefing.Metadata{
+			SchemaVersion: briefing.SchemaVersion,
+			RunID:         resolved.Metadata().RunID,
+			ReportID:      resolved.Definition.ID,
+			PromptID:      resolved.Definition.PromptID,
+			GeneratedAt:   resolved.GeneratedAt,
+			Units:         "us",
+			Timezone:      resolved.Timezone,
+			ValidPeriod:   resolved.ValidPeriod,
+		},
+		Weekend: &briefing.Weekend{
+			Days: []briefing.OutlookDay{{Date: "2026-05-30"}},
+		},
+	}
+}
+
+func pathsString(paths ArtifactPaths) string {
+	return strings.Join([]string{
+		paths.Briefing,
+		paths.Metadata,
+		paths.DataPackage,
+		paths.Preflight,
+		paths.RenderedReport,
+	}, "\n")
+}

internal/state/metadata.go

@@ -0,0 +1,65 @@
+package state
+
+import (
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+const MetadataSchemaVersion = "weatherreporter.metadata.v1"
+
+type Metadata struct {
+	SchemaVersion      string                    `json:"schemaVersion"`
+	RunID              string                    `json:"runId"`
+	MetadataPath       string                    `json:"-"`
+	ReportID           report.ID                 `json:"reportId"`
+	Variant            string                    `json:"variant,omitempty"`
+	PromptID           string                    `json:"promptId"`
+	GeneratedAt        time.Time                 `json:"generatedAt"`
+	Timezone           string                    `json:"timezone"`
+	ValidPeriod        timeutil.Period           `json:"validPeriod"`
+	Location           *briefing.LocationContext `json:"location,omitempty"`
+	SourceLocationID   string                    `json:"sourceLocationId,omitempty"`
+	SourceLocation     string                    `json:"sourceLocation,omitempty"`
+	Sources            []briefing.SourceMetadata `json:"sources,omitempty"`
+	SourceWarnings     []forecast.SourceWarning  `json:"sourceWarnings,omitempty"`
+	BriefingPath       string                    `json:"briefingPath"`
+	DataPackagePath    string                    `json:"dataPackagePath"`
+	PreflightPath      string                    `json:"preflightPath"`
+	RenderedReportPath string                    `json:"renderedReportPath,omitempty"`
+}
+
+func BuildMetadata(resolved report.Resolved, briefingPackage briefing.Package, paths ArtifactPaths) Metadata {
+	metadata := resolved.Metadata()
+	return Metadata{
+		SchemaVersion:      MetadataSchemaVersion,
+		RunID:              metadata.RunID,
+		MetadataPath:       paths.Metadata,
+		ReportID:           metadata.ReportID,
+		Variant:            briefingPackage.Metadata.Variant,
+		PromptID:           metadata.PromptID,
+		GeneratedAt:        metadata.GeneratedAt,
+		Timezone:           metadata.Timezone,
+		ValidPeriod:        metadata.ValidPeriod,
+		Location:           copyLocation(briefingPackage.Metadata.Location),
+		SourceLocationID:   briefingPackage.Metadata.SourceLocationID,
+		SourceLocation:     briefingPackage.Metadata.SourceLocation,
+		Sources:            briefingPackage.Metadata.Sources,
+		SourceWarnings:     briefingPackage.Metadata.SourceWarnings,
+		BriefingPath:       paths.Briefing,
+		DataPackagePath:    paths.DataPackage,
+		PreflightPath:      paths.Preflight,
+		RenderedReportPath: paths.RenderedReport,
+	}
+}
+
+func copyLocation(location *briefing.LocationContext) *briefing.LocationContext {
+	if location == nil {
+		return nil
+	}
+	copied := *location
+	return &copied
+}

internal/state/store.go

@@ -0,0 +1,35 @@
+// Package state persists report artifacts and metadata.
+package state
+
+import (
+	"context"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptinput"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+)
+
+type Store interface {
+	Paths(report.Resolved) (ArtifactPaths, error)
+	SaveBriefing(context.Context, report.Resolved, briefing.Package) (string, error)
+	SaveDataPackage(context.Context, report.Resolved, promptinput.Package) (string, error)
+	SavePreflight(context.Context, report.Resolved, PreflightArtifact) (string, error)
+	PrepareRenderedReport(context.Context, report.Resolved) (string, error)
+	SaveMetadata(context.Context, Metadata) (string, error)
+	FindPriorSnapshot(context.Context, report.Resolved) (*PriorSnapshot, error)
+	LoadBriefing(context.Context, string) (briefing.Package, error)
+}
+
+type PriorSnapshot struct {
+	Metadata     Metadata
+	BriefingPath string
+}
+
+type PreflightArtifact struct {
+	Command         []string `json:"command"`
+	Stdout          string   `json:"stdout"`
+	Stderr          string   `json:"stderr"`
+	StdoutTruncated bool     `json:"stdoutTruncated,omitempty"`
+	StderrTruncated bool     `json:"stderrTruncated,omitempty"`
+	ExitCode        int      `json:"exitCode"`
+}

internal/timeutil/clock.go

@@ -0,0 +1,22 @@
+// Package timeutil provides time-zone, clock, and period helpers.
+package timeutil
+
+import "time"
+
+type Clock interface {
+	Now() time.Time
+}
+
+type SystemClock struct{}
+
+func (SystemClock) Now() time.Time {
+	return time.Now()
+}
+
+type FixedClock struct {
+	Time time.Time
+}
+
+func (c FixedClock) Now() time.Time {
+	return c.Time
+}

internal/timeutil/parse.go

@@ -0,0 +1,103 @@
+package timeutil
+
+import (
+	"fmt"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+)
+
+const DateLayout = "2006-01-02"
+const LocalDateTimeLayout = "2006-01-02T15:04"
+
+func LoadLocation(name string) (*time.Location, error) {
+	if location, ok := timezoneAliases[name]; ok {
+		return location, nil
+	}
+	if location, ok := parseUTCOffset(name); ok {
+		return location, nil
+	}
+	location, err := time.LoadLocation(name)
+	if err == nil {
+		return location, nil
+	}
+	if strings.Contains(name, "/") {
+		return nil, fmt.Errorf("load timezone %q: %w", name, err)
+	}
+	location, chicagoErr := time.LoadLocation("America/" + name)
+	if chicagoErr == nil {
+		return location, nil
+	}
+	return nil, fmt.Errorf("load timezone %q: %w", name, err)
+}
+
+var timezoneAliases = map[string]*time.Location{
+	"Chicago": mustLocation("America/Chicago"),
+	"Stl":     mustLocation("America/Chicago"),
+	"EST":     time.FixedZone("EST", -5*60*60),
+	"EDT":     time.FixedZone("EDT", -4*60*60),
+	"CST":     time.FixedZone("CST", -6*60*60),
+	"CDT":     time.FixedZone("CDT", -5*60*60),
+	"MST":     time.FixedZone("MST", -7*60*60),
+	"MDT":     time.FixedZone("MDT", -6*60*60),
+	"PST":     time.FixedZone("PST", -8*60*60),
+	"PDT":     time.FixedZone("PDT", -7*60*60),
+}
+
+func mustLocation(name string) *time.Location {
+	location, err := time.LoadLocation(name)
+	if err != nil {
+		panic(err)
+	}
+	return location
+}
+
+var utcOffsetPattern = regexp.MustCompile(`^([+-])(\d{1,2})(?::?(\d{2}))?$`)
+
+func parseUTCOffset(value string) (*time.Location, bool) {
+	matches := utcOffsetPattern.FindStringSubmatch(value)
+	if matches == nil {
+		return nil, false
+	}
+	hours, err := strconv.Atoi(matches[2])
+	if err != nil || hours > 23 {
+		return nil, false
+	}
+	minutes := 0
+	if matches[3] != "" {
+		minutes, err = strconv.Atoi(matches[3])
+		if err != nil || minutes > 59 {
+			return nil, false
+		}
+	}
+	offset := (hours*60 + minutes) * 60
+	if matches[1] == "-" {
+		offset = -offset
+	}
+	return time.FixedZone(value, offset), true
+}
+
+func LocalDate(now time.Time, location *time.Location) time.Time {
+	local := now.In(location)
+	return time.Date(local.Year(), local.Month(), local.Day(), 0, 0, 0, 0, location)
+}
+
+func ParseLocalDate(value string, location *time.Location) (time.Time, error) {
+	parsed, err := time.ParseInLocation(DateLayout, value, location)
+	if err != nil {
+		return time.Time{}, fmt.Errorf("parse date %q as YYYY-MM-DD: %w", value, err)
+	}
+	return parsed, nil
+}
+
+func ParseStormTime(value string, location *time.Location) (time.Time, error) {
+	if parsed, err := time.Parse(time.RFC3339, value); err == nil {
+		return parsed, nil
+	}
+	parsed, err := time.ParseInLocation(LocalDateTimeLayout, value, location)
+	if err != nil {
+		return time.Time{}, fmt.Errorf("parse storm time %q as YYYY-MM-DDTHH:MM or RFC3339: %w", value, err)
+	}
+	return parsed, nil
+}

internal/timeutil/parse_test.go

@@ -0,0 +1,60 @@
+package timeutil
+
+import (
+	"testing"
+	"time"
+)
+
+func TestLoadLocationAcceptsChicagoAlias(t *testing.T) {
+	location, err := LoadLocation("Chicago")
+	if err != nil {
+		t.Fatalf("LoadLocation() error = %v", err)
+	}
+	if location.String() != "America/Chicago" {
+		t.Fatalf("location = %q, want America/Chicago", location.String())
+	}
+}
+
+func TestLoadLocationAcceptsWeatherAPITimezones(t *testing.T) {
+	tests := []string{"Stl", "CDT", "-5", "+09:30"}
+	for _, tt := range tests {
+		t.Run(tt, func(t *testing.T) {
+			if _, err := LoadLocation(tt); err != nil {
+				t.Fatalf("LoadLocation(%q) error = %v", tt, err)
+			}
+		})
+	}
+}
+
+func TestParseLocalDate(t *testing.T) {
+	location := time.FixedZone("Test", -5*60*60)
+	got, err := ParseLocalDate("2026-05-29", location)
+	if err != nil {
+		t.Fatalf("ParseLocalDate() error = %v", err)
+	}
+	if got.Format(DateLayout) != "2026-05-29" {
+		t.Fatalf("date = %s, want 2026-05-29", got.Format(DateLayout))
+	}
+	if got.Location() != location {
+		t.Fatalf("location = %v, want test location", got.Location())
+	}
+}
+
+func TestParseStormTime(t *testing.T) {
+	location := time.FixedZone("Test", -5*60*60)
+	local, err := ParseStormTime("2026-05-29T18:00", location)
+	if err != nil {
+		t.Fatalf("ParseStormTime(local) error = %v", err)
+	}
+	if local.Location() != location {
+		t.Fatalf("local location = %v, want test location", local.Location())
+	}
+
+	rfc3339, err := ParseStormTime("2026-05-29T18:00:00-05:00", location)
+	if err != nil {
+		t.Fatalf("ParseStormTime(rfc3339) error = %v", err)
+	}
+	if rfc3339.Format(time.RFC3339) != "2026-05-29T18:00:00-05:00" {
+		t.Fatalf("rfc3339 = %s, want preserved offset time", rfc3339.Format(time.RFC3339))
+	}
+}

internal/timeutil/periods.go

@@ -0,0 +1,81 @@
+package timeutil
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+)
+
+type Period struct {
+	Start time.Time `json:"start"`
+	End   time.Time `json:"end"`
+}
+
+func (p Period) IsValid() bool {
+	return p.End.After(p.Start)
+}
+
+func (p Period) Overlaps(other Period) bool {
+	return p.Start.Before(other.End) && other.Start.Before(p.End)
+}
+
+func (p Period) Contains(t time.Time) bool {
+	return !t.Before(p.Start) && t.Before(p.End)
+}
+
+func (p Period) Intersection(other Period) (Period, bool) {
+	if !p.Overlaps(other) {
+		return Period{}, false
+	}
+	start := p.Start
+	if other.Start.After(start) {
+		start = other.Start
+	}
+	end := p.End
+	if other.End.Before(end) {
+		end = other.End
+	}
+	return Period{Start: start, End: end}, true
+}
+
+func ParseClock(value string) (time.Duration, error) {
+	parts := strings.Split(value, ":")
+	if len(parts) != 2 {
+		return 0, fmt.Errorf("expected HH:MM")
+	}
+	hour, err := strconv.Atoi(parts[0])
+	if err != nil {
+		return 0, fmt.Errorf("invalid hour")
+	}
+	minute, err := strconv.Atoi(parts[1])
+	if err != nil {
+		return 0, fmt.Errorf("invalid minute")
+	}
+	if hour < 0 || hour > 24 {
+		return 0, fmt.Errorf("hour must be between 00 and 24")
+	}
+	if minute < 0 || minute > 59 {
+		return 0, fmt.Errorf("minute must be between 00 and 59")
+	}
+	if hour == 24 && minute != 0 {
+		return 0, fmt.Errorf("24 is only valid as 24:00")
+	}
+	return time.Duration(hour)*time.Hour + time.Duration(minute)*time.Minute, nil
+}
+
+func CivilDay(date time.Time, location *time.Location) Period {
+	local := date.In(location)
+	start := time.Date(local.Year(), local.Month(), local.Day(), 0, 0, 0, 0, location)
+	return Period{Start: start, End: start.AddDate(0, 0, 1)}
+}
+
+func ClockWindow(date time.Time, location *time.Location, startClock time.Duration, endClock time.Duration) Period {
+	day := CivilDay(date, location)
+	start := day.Start.Add(startClock)
+	end := day.Start.Add(endClock)
+	if !end.After(start) {
+		end = end.AddDate(0, 0, 1)
+	}
+	return Period{Start: start, End: end}
+}

internal/timeutil/periods_test.go

@@ -0,0 +1,35 @@
+package timeutil
+
+import (
+	"testing"
+	"time"
+)
+
+func TestPeriodOverlapUsesHalfOpenIntervals(t *testing.T) {
+	start := time.Date(2026, 5, 29, 6, 0, 0, 0, time.UTC)
+	left := Period{Start: start, End: start.Add(time.Hour)}
+	touching := Period{Start: start.Add(time.Hour), End: start.Add(2 * time.Hour)}
+	overlapping := Period{Start: start.Add(30 * time.Minute), End: start.Add(90 * time.Minute)}
+
+	if left.Overlaps(touching) {
+		t.Fatal("touching half-open periods overlap, want false")
+	}
+	if !left.Overlaps(overlapping) {
+		t.Fatal("overlapping periods do not overlap, want true")
+	}
+}
+
+func TestClockWindowHandlesOvernight(t *testing.T) {
+	location := time.FixedZone("Test", -5*60*60)
+	date := time.Date(2026, 5, 29, 12, 0, 0, 0, location)
+	start, _ := ParseClock("22:00")
+	end, _ := ParseClock("06:00")
+
+	window := ClockWindow(date, location, start, end)
+	if got := window.Start.Format("2006-01-02T15:04"); got != "2026-05-29T22:00" {
+		t.Fatalf("Start = %s, want 2026-05-29T22:00", got)
+	}
+	if got := window.End.Format("2006-01-02T15:04"); got != "2026-05-30T06:00" {
+		t.Fatalf("End = %s, want 2026-05-30T06:00", got)
+	}
+}