Correct documentation refresh findings

AGENTS.md

@@ -1,4 +1 @@
-Please carefully review the documents in `docs/policy` before making any changes to this repository.
- - `architecture.md` provides the canonical high-level architecture policy for this repository.
- - `development.md` provides more granular development policy for this repository.
- - `documentation.md` provides the canonical documentation policy for this repository.
+Please review `docs/development.md` for initial orientation in this repository and follow its task-specific reading guide.

README.md

@@ -1,22 +1,25 @@
 # weatherreporter
 
-`weatherreporter` is a Go application for preparing human-facing weather
-reports from normalized forecast data. It builds JSON module snapshots, passes
-YAML prompt data packages to `scriptorium`, and keeps inspectable artifacts
-under a local workspace. It can also upload successfully generated managed
-Markdown reports to a configured `distributor` HTTP upload endpoint.
+Weatherreporter is a Go CLI that turns normalized weather data into managed,
+human-facing Markdown reports.
+
+It provides repeatable reports with inspectable local artifacts, so operators
+can review what was collected and generated for every run.
 
 ## Quickstart
 
 ```sh
-weatherreporter generate daily --date 2026-05-29 --out ./daily.md
+weatherreporter generate today --out ./today.md
 ```
 
+Configure a Weather API endpoint first; see the
+[configuration reference](docs/config.md).
+
 ## Documentation
 
 - [CLI reference](docs/cli.md)
 - [Configuration reference](docs/config.md)
 - [Operations guide](docs/operations.md)
 - [Troubleshooting](docs/troubleshooting.md)
+- [Development guide](docs/development.md)
 - [Architecture policy](docs/policy/architecture.md)
-- [Development policy](docs/policy/development.md)

docs/cli.md

@@ -1,31 +1,31 @@
 # Weatherreporter CLI
 
-`weatherreporter` generates Markdown weather reports, runs scheduled report
-batches, and inspects stored artifacts.
+`weatherreporter` generates weather reports, runs report batches, and inspects
+artifacts already stored in its workspace.
 
 ## Shortest Useful Command
 
 ```sh
-weatherreporter generate daily --date 2026-05-29 --out ./daily.md
+weatherreporter generate today --out ./today.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`. If
-distributor notification is enabled in configuration, the command also uploads
-the managed Markdown report after final metadata is saved.
+The command uses the configured Weather API and writes an extra Markdown copy
+at `./today.md`. See the [configuration reference](config.md) to supply the
+required Weather API endpoint.
 
-## Commands
+## Commands And Usage
 
 ```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 generate daily --date YYYY-MM-DD [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
+weatherreporter generate today [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--date YYYY-MM-DD] [--quiet]
+weatherreporter generate tomorrow [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
+weatherreporter generate hourly [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
+weatherreporter generate three-day [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
+weatherreporter generate weekend [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
+weatherreporter generate storm [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet] --start TIME --end TIME
+weatherreporter run morning [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] [--quiet]
+weatherreporter run evening [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] [--quiet]
 weatherreporter inspect reports [--config PATH] [--limit N]
 weatherreporter inspect metadata [--config PATH] RUN_ID
 weatherreporter inspect modules [--config PATH] RUN_ID
@@ -34,69 +34,124 @@ weatherreporter inspect prior [--config PATH] RUN_ID
 weatherreporter inspect sources [--config PATH] RUN_ID
 ```
 
-`generate` commands write a JSON module snapshot, YAML data package, preflight
-artifact, managed Markdown report, and metadata under the configured workspace.
-`--out` writes an extra Markdown copy for the operator; distributor
-notification uses the managed report path, not the extra copy. `generate storm`
-requires explicit event-window bounds with `--start` and `--end`.
+| Command | Contract |
+| --- | --- |
+| `generate daily` | Requires `--date YYYY-MM-DD`; the date is interpreted in the effective report timezone. |
+| `generate today` | Accepts an optional `--date YYYY-MM-DD`; without it, the current local date in the effective report timezone is used. |
+| `generate tomorrow`, `three-day`, `weekend` | Use their report-defined valid period and accept the common generate flags. |
+| `generate hourly` | Covers the next six hours in the effective report timezone. It does not accept `--date`, `--start`, `--end`, `--hours`, or `--duration`. |
+| `generate storm` | Requires both `--start TIME` and `--end TIME`. Each time may be `YYYY-MM-DDTHH:MM` in the effective timezone or an RFC3339 timestamp with an explicit offset. |
+| `run morning` and `run evening` | Run their defined report batches. `--out-dir` writes extra Markdown copies; `--out` is not accepted. |
 
-`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. `--out-dir` writes extra Markdown copies for the operator; distributor
-notification uses each managed report path, not the extra copies. When
-notification is enabled, batch summaries and status lines include notification
-status, accepted distributor run ID, or notification error fields for each
-attempted report.
+`generate` accepts all seven report command names shown above. `run` accepts
+only `morning` and `evening`. Batch membership, workspace artifacts, and
+notification sequencing are described in the [operations guide](operations.md).
 
-`inspect` commands read existing workspace artifacts and emit JSON to stdout.
-They do not fetch weather data or invoke `scriptorium`.
+## Output, Errors, And Quiet Mode
 
-## Flags
+Action commands (`generate` and `run`) write a JSON summary to stdout unless
+`--quiet` is set. `run` also writes compact per-report and batch status lines
+to stderr. A pre-run error, such as an invalid flag, missing required argument,
+or configuration-load failure, produces no partial JSON summary. When an action
+fails after it has produced a result, its summary has `"status": "failed"` and
+an `error` field.
 
-- `-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.
+`--quiet` is supported by action commands only. It suppresses action summaries
+and routine batch status output; it does not suppress command errors.
 
-Storm times accept `YYYY-MM-DDTHH:MM` in the configured timezone or RFC3339
-timestamps with explicit offsets.
+Inspection commands always write their requested JSON value to stdout and do
+not accept `--quiet`.
 
-Distributor notification is configured only through `notify.distributor`; there
-are no distributor-specific CLI flags.
+### Generate Summary
 
-## Common Workflows
+A generate summary always identifies the command, report, run, generation
+time, valid period, and status:
 
-```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
+```json
+{
+  "command": "generate",
+  "reportId": "today",
+  "reportName": "Today Report",
+  "promptId": "weather.today_generated_text",
+  "runId": "20260529T120000.000000000Z_today",
+  "status": "succeeded",
+  "generatedAt": "2026-05-29T12:00:00Z",
+  "validPeriod": {
+    "start": "2026-05-29T00:00:00-05:00",
+    "end": "2026-05-30T00:00:00-05:00"
+  }
+}
 ```
 
-## Inspection
+When available, the summary also includes `reportPath`, `metadataPath`,
+`dataPackagePath`, and `preflightPath`. Generated-text reports additionally
+include `generatedTextRawPath`, `generatedTextResultPath`,
+`generatedTextPath`, and `renderContextPath`. `outputPath` is included only
+when `--out` wrote an extra copy. Distributor notification, when attempted,
+adds `notificationPath` and may add a compact `notification` object.
+
+### Run Summary And Stderr
+
+A run summary contains `command`, `batch`, `status`, `startedAt`, `finishedAt`,
+`total`, `succeeded`, `failed`, and a `reports` array. It may also contain a
+top-level `notification` object and `error`. Batch status is `failed` if any
+report or the batch notification fails.
+
+Without `--quiet`, batch status lines use this form:
+
+```text
+report=today status=succeeded output="reports/today.md"
+batch=morning total=2 succeeded=2 failed=0
+```
+
+## Flag Reference
+
+| Flag | Accepted by | Meaning |
+| --- | --- | --- |
+| `-h`, `--help` | top level | Show help. |
+| `--config PATH` | all commands | Load `PATH` instead of `/usr/local/etc/weatherreporter/config.yml`. |
+| `--units VALUE` | `generate`, `run` | Override `weather_api.units` for this command. |
+| `--tz NAME` | `generate`, `run` | Override `weather_api.timezone` for this command. |
+| `--out PATH` | every `generate` command | Write an extra Markdown report copy. |
+| `--out-dir PATH` | `run morning`, `run evening` | Write extra Markdown report copies in `PATH`. |
+| `--quiet` | `generate`, `run` | Suppress action summaries and routine batch status output. |
+| `--date YYYY-MM-DD` | `generate daily`, `generate today` | Required for Daily; optional for Today. |
+| `--start TIME`, `--end TIME` | `generate storm` | Required storm-event bounds. |
+| `--limit N` | `inspect reports` | Maximum runs to list. Defaults to `20`; `0` means no limit. |
+
+Distributor notification is configured through `notify.distributor`; there are
+no Distributor-specific CLI flags. See the [configuration reference](config.md).
+
+## Invocation Examples
+
+```sh
+weatherreporter generate daily --date 2026-05-29 --out ./daily.md
+weatherreporter generate today --date 2026-05-29 --out ./today.md
+weatherreporter generate hourly --out ./hourly.md
+weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00 --out ./storm.md
+weatherreporter run morning --out-dir ./reports
+```
+
+## Inspection Commands
 
 ```sh
 weatherreporter inspect reports --limit 10
-weatherreporter inspect metadata 20260529T100000.000000000Z_daily_today
-weatherreporter inspect modules 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
+weatherreporter inspect metadata 20260529T100000.000000000Z_today
+weatherreporter inspect modules 20260529T100000.000000000Z_today
+weatherreporter inspect data-package 20260529T100000.000000000Z_today
+weatherreporter inspect prior 20260529T100000.000000000Z_today
+weatherreporter inspect sources 20260529T100000.000000000Z_today
 ```
 
-`inspect reports` lists recent generated runs with artifact paths and source
-warning counts. The other inspect commands require a RunID. `inspect modules`
-returns the persisted ordered module snapshot for a run. `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.
+| Command | JSON returned |
+| --- | --- |
+| `inspect reports` | Recent generated runs, including artifact paths and source-warning counts. |
+| `inspect metadata RUN_ID` | Persisted metadata for the run. |
+| `inspect modules RUN_ID` | The run's persisted ordered module snapshot. |
+| `inspect data-package RUN_ID` | The run's persisted prompt data package. |
+| `inspect prior RUN_ID` | Prior comparable snapshot metadata, or `null` when none exists. |
+| `inspect sources RUN_ID` | Source provenance and source warnings without full weather payloads. |
+
+Inspection is read-only: it does not collect weather data or invoke
+`scriptorium`. See the [operations guide](operations.md) for artifact lifecycle
+and recovery.

docs/config.md

@@ -1,234 +1,206 @@
 # Weatherreporter Configuration
 
-Configuration is YAML. By default, `weatherreporter` reads:
+Weatherreporter reads YAML configuration. The default path is:
 
 ```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.
+If the default file is absent, Weatherreporter uses built-in defaults. An
+explicit `--config PATH` must exist. Values are applied in this order:
 
-Precedence is:
+1. built-in defaults;
+2. the configuration file, when present; and
+3. the `--units` and `--tz` command-line overrides.
 
-1. CLI flags
-2. configuration file
-3. built-in defaults
+Environment variables do not override configuration fields. Output flags write
+extra report copies for a command and do not change configuration.
 
-The CLI configuration overrides are `--units` and `--tz`. Output flags control
-report copies for the current command but do not change configuration files.
-Environment variables do not override configuration fields.
+## Maintained Examples
 
-## Minimal Config
+- [minimal-config.yml](../examples/minimal-config.yml) is the smallest useful
+  collection and generation configuration.
+- [config.yml](../examples/config.yml) is a representative production-oriented
+  configuration using synthetic endpoints and no credentials.
 
-See [examples/minimal-config.yml](../examples/minimal-config.yml).
+Both files are loaded by the configuration test suite.
+
+## Minimal Configuration
 
 ```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.
+`weather_api.base_url` is required for workflows that collect weather data.
+All omitted fields use their built-in defaults.
 
 ## 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`.
+| Field | Default | Rules |
+| --- | --- | --- |
+| `base_url` | empty | Absolute Weather API URL. Required for collection and generation. |
+| `timeout` | `10s` | Must be greater than zero. |
+| `precision` | `0` | Must be zero or greater. Sent as the Weather API precision query value. |
+| `units` | `us` | Required Weather API units query value; `--units` overrides it for one command. |
+| `timezone` | `America/Chicago` | Required report and Weather API timezone; `--tz` overrides it for one command. |
+| `format` | `json` | Required and must be `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 module metadata and
-Scriptorium data packages. It does not select a Weather API endpoint or enable
-multiple configured forecast locations.
+`location` supplies descriptive prompt context; it does not choose a Weather
+API endpoint or configure multiple forecast locations.
 
-- `id`: short local identifier. Default: `home`.
-- `name`: human-readable location name. Default: `Brentwood`.
-- `region`: broader forecast area context. Default: `St. Louis Metro`.
+| Field | Default |
+| --- | --- |
+| `id` | `home` |
+| `name` | `Brentwood` |
+| `region` | `St. Louis Metro` |
 
-The prompt-facing location object also includes `timezone`, derived from the
-effective `weather_api.timezone` after CLI overrides such as `--tz`.
+The prompt-facing location timezone is derived from the effective
+`weather_api.timezone` after command-line overrides.
 
 ### `secrets`
 
-- `directory`: optional directory of file-backed environment secrets. Default:
-  empty, which disables secret loading.
+`secrets.directory` defaults to empty, which disables secret loading. When it
+is set, every regular file directly in that directory is loaded after the file
+and command-line overrides. A file basename must match
+`[A-Za-z_][A-Za-z0-9_]*`; it becomes an environment variable name, and the
+file contents replace any existing value. One trailing LF or CRLF is removed.
 
-When configured, each regular file directly under `secrets.directory` is loaded
-after config file parsing and CLI overrides. The file basename must be a valid
-environment variable name matching `[A-Za-z_][A-Za-z0-9_]*`; the file contents
-become the environment variable value and overwrite any existing value. One
-trailing LF or CRLF is stripped. Subdirectories, symlinks, invalid filenames,
-missing directories, and unreadable files fail config loading.
+Missing directories, unreadable files, subdirectories, symlinks, non-regular
+files, and invalid names fail configuration loading. Put only secret values in
+this directory, never in the YAML file.
 
-### `notify`
+### `notify.distributor`
 
-`notify.distributor` controls distributor notification after successful report
-generation. It is disabled by default and does not add CLI flags. When enabled,
-weatherreporter uploads one distributor bundle per generated report after
-`scriptorium run` succeeds and final metadata is saved.
+Distributor notification is disabled by default. Its fields are:
 
-- `enabled`: whether distributor notification config is active. Default:
-  `false`.
-- `endpoint`: absolute distributor endpoint URL. Required when enabled.
-  Default: `https://distributor.example.com`.
-- `token_env`: environment variable name that will contain the distributor
-  upload token. Required when enabled. Default: `DISTRIBUTOR_UPLOAD_TOKEN`.
-- `timeout`: distributor operation timeout. Must be greater than zero when
-  enabled. Default: `30s`.
-- `failure_policy`: must be `error` when enabled. Default: `error`.
-- `pipeline_id_template`: template for the distributor pipeline ID. Required
-  when enabled. Default: empty.
-- `bundle_id_template`: template for distributor bundle IDs. Default:
-  `weatherreporter.{location_id}.{report_id}`.
-- `idempotency_key_template`: template for distributor idempotency keys.
-  Default: `{bundle_id}.{run_id}`.
-- `report_path_templates`: ordered list of templates for Markdown report paths
-  inside the distributor bundle. Each rendered path maps to the same managed
-  Markdown report source. Default:
-  ```yaml
-  - "{valid_start_date}/{artifact_group}/{valid_start_date}-{artifact_group}-{run_id}.md"
-  ```
+| Field | Default | Rules when notification is enabled |
+| --- | --- | --- |
+| `enabled` | `false` | Activates Distributor notification validation. |
+| `endpoint` | `https://distributor.example.com` | Must be an absolute URL. |
+| `token_env` | `DISTRIBUTOR_UPLOAD_TOKEN` | Must name a valid environment variable. |
+| `timeout` | `30s` | Must be greater than zero. |
+| `failure_policy` | `error` | Must be `error`. |
+| `pipeline_id_template` | empty | Required single-report pipeline ID template. |
+| `bundle_id_template` | `weatherreporter.{location_id}.{report_id}` | Required single-report bundle ID template. |
+| `idempotency_key_template` | `{bundle_id}.{run_id}` | Required single-report idempotency-key template. |
+| `batch.enabled` | `true` | Activates batch notification validation when Distributor notification is enabled. |
+| `batch.pipeline_id_template` | `weatherreporter` | Required when batch notification is enabled. |
+| `batch.bundle_id_template` | `weatherreporter.{location_id}.{batch}` | Required when batch notification is enabled. |
+| `batch.idempotency_key_template` | `{bundle_id}.{batch_run_id}` | Required when batch notification is enabled. |
 
-Supported template variables are `location_id`, `report_id`, `run_id`,
+The upload token is read from the environment variable named by `token_env`.
+Use `secrets.directory` when a file-backed secret is appropriate.
+
+Single-report bundle templates accept `location_id`, `report_id`, `run_id`,
 `artifact_group`, `batch_output_name`, `valid_start_date`, `valid_end_date`,
-`valid_start_time`, `valid_end_time`, `valid_start_stamp`, and
-`valid_end_stamp`. Date values use `YYYY-MM-DD`, time values use `HHMM`, and
-stamp values use `YYYY-MM-DDTHHMM` in the effective report timezone.
-`pipeline_id_template` and `idempotency_key_template` may also use `bundle_id`.
+`valid_start_time`, `valid_end_time`, `valid_start_stamp`, `valid_end_stamp`,
+and `storm_id`. Pipeline and idempotency-key templates may also use
+`bundle_id`. Dates use `YYYY-MM-DD`; times use `HHMM`; and stamps use
+`YYYY-MM-DDTHHMM` in the effective report timezone. `storm_id` is
+`{valid_start_stamp}-{valid_end_stamp}` for Storm Report and empty otherwise.
 
-The rendered pipeline ID selects the configured distributor `http_upload`
-workflow. The rendered bundle ID is the stable logical source identity for the
-report stream. The rendered idempotency key is the per-run retry identity.
+Batch bundle and pipeline templates accept `location_id`, `batch`,
+`batch_run_id`, and `batch_started_date`; batch idempotency-key templates may
+also use `bundle_id`. `batch_started_date` is the batch start date in the
+effective report timezone.
 
-Rendered report paths must be unique relative paths with `/` separators. They
-must not contain backslashes, empty path segments, `.`, `..`, `manifest.json`,
-or `.distributor.json`.
+`reports.<report>.distributor.path_templates` overrides the default ordered
+Distributor paths for that report. Each rendered path must be a unique relative
+path with `/` separators. Backslashes, empty segments, `.` and `..` segments,
+`manifest.json`, and the reserved Distributor sidecar basename are rejected.
+The default paths are:
 
-The upload token is read from the environment variable named by `token_env`
-after config loading and `secrets.directory` processing. Config files should
-name the variable only; they should not contain the token value.
+| Report | Paths |
+| --- | --- |
+| `hourly` | `hourly/index.md` |
+| `daily` | `daily/{valid_start_date}/{run_id}.md`, `daily/{valid_start_date}/index.md` |
+| `today` | `daily/{valid_start_date}/{run_id}.md`, `daily/{valid_start_date}/index.md`, `today/index.md` |
+| `tomorrow` | `daily/{valid_start_date}/{run_id}.md`, `daily/{valid_start_date}/index.md`, `tomorrow/index.md` |
+| `three_day` | `three-day/{valid_start_date}/{run_id}.md`, `three-day/{valid_start_date}/index.md` |
+| `weekend` | `weekend/{valid_start_date}/{run_id}.md`, `weekend/{valid_start_date}/index.md` |
+| `storm` | `storm/{storm_id}/{run_id}.md`, `storm/{storm_id}/index.md` |
+
+See the [operations guide](operations.md) for notification timing, uploaded
+artifact selection, and failure handling.
 
 ### `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 use
-the missing-source policy.
+`missing_source.default` defaults to `warn` and accepts `error`, `warn`, or
+`none`. `missing_source.sources` optionally overrides that policy by source.
+Hourly forecast data is required for generated reports. Supported optional
+source keys are `observations`, `current`, `narrative`, `alerts`, `discussion`,
+`weather_story`, and `spc_convective_outlooks`.
 
 ### `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.
+| Field | Default | Rules |
+| --- | --- | --- |
+| `binary` | `scriptorium` | Required executable name or path. |
+| `config_path` | empty | Optional Scriptorium configuration path. |
+| `profile` | empty | Optional Scriptorium profile. |
+| `timeout` | `2m` | Must be greater than zero. |
+| `extra_args` | empty | Optional extra arguments passed to Scriptorium commands. |
 
 ### `workspace`
 
-- `root`: workspace root for managed artifacts. Default: `workspace`.
-- `snapshots_dir`: module snapshot 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`.
-- `notifications_dir`: distributor notification debug artifact directory under `workspace.root`. Default: `notifications`.
+| Field | Default |
+| --- | --- |
+| `root` | `workspace` |
+| `snapshots_dir` | `snapshots` |
+| `reports_dir` | `reports` |
+| `data_packages_dir` | `data-packages` |
+| `preflight_dir` | `preflight` |
+| `notifications_dir` | `notifications` |
 
-Workspace subdirectories must be relative paths that stay inside
-`workspace.root`.
+`workspace.root` is required. Each workspace subdirectory must be a relative
+path that stays within the root. See the [operations guide](operations.md) for
+the managed workspace layout and lifecycle.
 
 ### `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.
+`dayparts` is a non-empty list of named local-time windows used in forecast
+derivation. Every item needs `name`, `start`, and `end`; start and end use
+`HH:MM`. Defaults are `overnight` (`00:00`–`06:00`), `morning`
+(`06:00`–`10:00`), `midday` (`10:00`–`15:00`), `afternoon`
+(`15:00`–`17:00`), and `evening` (`17:00`–`24:00`).
 
 ### `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`.
+| Field | Default |
+| --- | --- |
+| `temperature_degrees` | `5` |
+| `precip_probability_points` | `20` |
+| `wind_gust_miles_per_hour` | `10` |
+| `precip_timing_shift_minutes` | `120` |
 
-Recent Changes are added to prompt input when a prior comparable module
-snapshot exists and a threshold is crossed.
+These thresholds control when Recent Changes are included in prompt input for a
+prior comparable module snapshot.
 
 ### `reports`
 
-`reports` optionally overrides the ordered deterministic modules declared by
-report definitions. Omit a report entry to use its default module order.
+`reports` optionally overrides a report's ordered deterministic modules and
+Distributor path templates. Omit a report entry to retain its defaults.
 
-Supported report keys are `daily`, `tomorrow`, `three_day`, `weekend`, and
-`storm`. Canonical report IDs such as `daily_today` and `daily_tomorrow` are
-also accepted.
+Supported report keys are `daily`, `today`, `tomorrow`, `hourly`, `three_day`,
+`weekend`, and `storm`. Configuration also accepts `three_day_outlook`,
+`weekend_outlook`, and `storm_report`; hyphens and underscores are equivalent.
 
-Each report entry supports:
+Each report entry can contain:
 
-- `deterministic_modules`: ordered module list. Entries may be string module
-  IDs or objects with `id` and optional `options`.
+- `deterministic_modules`: an ordered list of module IDs, or objects with `id`
+  and optional `options`.
+- `distributor.path_templates`: an optional, non-empty ordered list of
+  Distributor paths for that report.
 
-Example:
-
-```yaml
-reports:
-  daily:
-    deterministic_modules:
-      - metadata
-      - current_conditions
-      - narrative_forecast
-      - id: area_forecast_discussion
-        options:
-          sections:
-            - short_term
-      - hourly_forecast
-```
-
-Unknown reports, unknown modules, duplicate modules, incompatible report/module
-combinations, duplicate stanza names, and invalid options fail config loading.
-`area_forecast_discussion.options.sections` may contain `product`,
-`key_messages`, `short_term`, and `long_term`. Empty or omitted `sections`
-includes all available AFD sections.
-
-The module registry accepts all module IDs documented in
-[Module Contract Internals](internal/module.md). Unknown or unimplemented
-module IDs fail validation instead of being skipped.
-
-## Secrets
-
-Configuration files should not contain raw secrets. Use `secrets.directory` to
-load secret values from files into environment variables for integrations that
-read credentials from the environment. Secret file names become environment
-variable names, and secret file contents become values. For distributor
-notification, this allows a file such as
-`<secrets.directory>/DISTRIBUTOR_UPLOAD_TOKEN` to supply the token referenced by
-`notify.distributor.token_env`.
-
-## 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 maintained fields.
-
-Both example files are loaded by the config test suite.
+Unknown reports and modules, duplicate modules, incompatible report-module
+combinations, duplicate stanza names, invalid path templates, and invalid
+module options fail configuration loading. The accepted module IDs and module
+option contracts are documented in the [module contract internals](internal/module.md).

docs/development.md

@@ -0,0 +1,86 @@
+# Development
+
+This is the first-read guide for people and coding agents working on
+Weatherreporter. It provides a concise repository orientation and routes each
+kind of change to its canonical documentation.
+
+Weatherreporter is a Go CLI that collects normalized weather data, derives
+deterministic report facts and module snapshots, invokes Scriptorium for
+generated text, renders managed Markdown reports, and can upload completed
+reports through Distributor. Start with the [README](../README.md) for product
+context and the [architecture policy](policy/architecture.md) for system
+boundaries and invariants.
+
+## What To Read
+
+| When working on | Read | Why |
+| --- | --- | --- |
+| Product behavior or the shortest useful workflow | [README](../README.md), [CLI reference](cli.md), and [operations guide](operations.md) | These own product orientation, invocation, and normal operation. |
+| Application shape, package boundaries, dependency direction, safety properties, or architectural invariants | [Architecture policy](policy/architecture.md) and relevant ADRs under `docs/adr/`, when present | Architecture defines the intended system; ADRs preserve significant decision rationale. |
+| Any documentation addition, revision, move, or removal | [Documentation policy](policy/documentation.md) | It defines canonical owners, audience boundaries, current-state rules, and document lifecycle. |
+| Adding, changing, reviewing, or deleting tests | [Testing policy](policy/testing.md) and focused package tests | The policy defines risk-based sufficiency, durable test boundaries, doubles, and test-maintenance criteria. |
+| CLI commands, flags, output, quiet mode, or command wiring | [CLI reference](cli.md) and [CLI internals](internal/cli.md) | The reference owns the user contract; the internal guide owns command composition and output flow. |
+| Configuration fields, defaults, loading, overrides, validation, or secrets | [Configuration reference](config.md), [architecture policy](policy/architecture.md), and tests under `internal/config` | These separate the user-visible contract, architectural rules, and executable behavior. |
+| Top-level generation, batch, collection, inspection, or notification workflow | [App orchestration internals](internal/app-orchestration.md) | It owns workflow ordering, persistence points, failure propagation, and orchestration invariants. |
+| Weather API transport, source envelopes, source warnings, or collection | [Weather API integration](integrations/weatherapi.md), [weather-data internals](internal/weather-data.md), and [collection internals](internal/collect.md) | These separate the external contract, normalized source facts, and app-facing collection behavior. |
+| Forecast periods, weather derivation, collected facts, or derived facts | [Forecast derivation internals](internal/forecast-derivation.md) and [fact contracts](internal/facts.md) | They own deterministic derivation and the fact boundaries used by reports. |
+| Report definitions, valid periods, report IDs, output naming, or batch composition | [Report registry internals](internal/report-registry.md) and [app orchestration internals](internal/app-orchestration.md) | Report definitions own selection and period rules; orchestration owns execution. |
+| Module IDs, module composition, briefing values, or prompt-facing exports | [Module contract internals](internal/module.md), [module builder internals](internal/briefing.md), and [prompt-input internals](internal/prompt-input.md) | These own module contracts, value construction, and the curated prompt-package boundary. |
+| Recent Changes comparison | [Changes internals](internal/changes.md) and [operations guide](operations.md) | The internal guide owns structured comparison; operations owns user-visible artifact behavior. |
+| Scriptorium commands, subprocess execution, prompt inputs, or result handling | [Scriptorium integration](integrations/scriptorium.md), [Scriptorium adapter internals](internal/scriptorium-adapter.md), and [prompt-input internals](internal/prompt-input.md) | These separate the external CLI contract, subprocess boundary, and input construction. |
+| Generated-text schemas, validation, render contexts, templates, or Markdown rendering | [Generated-text internals](internal/generatedtext.md), [report-template internals](internal/reporttemplate.md), and [report template guide](templates.md) | These own structured text, renderer implementation, and the maintainer-facing template surface. |
+| Workspace paths, metadata, atomic persistence, lookup, inspection, or recovery | [State internals](internal/state.md), [operations guide](operations.md), and [troubleshooting guide](troubleshooting.md) | These separate implementation, operator workflows, and symptom-based recovery. |
+| Distributor bundles, uploads, notification artifacts, or failures | [Distributor adapter internals](internal/distributor-adapter.md), [Distributor integration contracts](integrations/distributor/), and [operations guide](operations.md) | These separate adapter behavior, external contracts, and operational lifecycle. |
+| Maintained example configuration | [Configuration reference](config.md) and files under `examples/` | The reference owns field meaning; examples own complete copyable files. |
+| Proposed, deferred, or unimplemented work | Documents under `docs/roadmap/` | Future behavior and implementation status belong only in roadmaps until implemented. |
+
+For an existing subsystem, inspect its focused internal document, package-local
+types, and tests before changing behavior. Use the package boundaries already
+present before introducing a new package or abstraction.
+
+## Repository Map
+
+| Area | Responsibility |
+| --- | --- |
+| `cmd/weatherreporter` | Binary entry point. |
+| `internal/cli` | Command parsing, flags, help, output, and command wiring. |
+| `internal/app` | Generation, batches, collection coordination, notification, and inspection orchestration. |
+| `internal/config` | Configuration defaults, loading, precedence, secrets, and validation. |
+| `internal/adapters` | Weather API, Scriptorium, and Distributor boundaries. |
+| `internal/weatherdata`, `internal/forecast`, `internal/facts` | Normalized source facts and deterministic derivation. |
+| `internal/report`, `internal/module`, `internal/briefing`, `internal/changes` | Report registry, module contracts and values, and structured comparison. |
+| `internal/promptinput`, `internal/generatedtext`, `internal/reporttemplate` | Prompt packages, generated-text validation, render contexts, and Markdown templates. |
+| `internal/state`, `internal/fileutil`, `internal/timeutil` | Durable artifacts, atomic file operations, clocks, dates, timezones, and periods. |
+| `docs` | User, operator, integration, internal, policy, and roadmap documentation. |
+| `examples` | Maintained copyable configuration. |
+
+The [architecture policy](policy/architecture.md) is authoritative for
+normative boundaries. Focused documents under `docs/internal/` own detailed
+implemented subsystem behavior.
+
+## Contributor Workflow
+
+1. Read the documents and focused tests identified by the task guide.
+2. Use focused package checks while iterating.
+3. Run `gofmt -w` on changed Go files.
+4. Update the canonical documentation and maintained examples in the same
+   change when behavior changes.
+5. Run repository-wide validation before considering the work complete.
+
+Preserve actionable error context, keep secrets out of logs and fixtures, and
+avoid validation that requires live Weather API, Scriptorium, or Distributor
+services. The architecture and testing policies own the detailed rules.
+
+## Baseline Validation
+
+Run:
+
+```sh
+go test ./...
+go run ./cmd/weatherreporter --help
+git diff --check
+```
+
+Use focused package tests during development and add broader or race-enabled
+checks when required by the [testing policy](policy/testing.md) and the risks of
+the change.

docs/integrations/distributor/api.md

@@ -1,136 +1,70 @@
-# Upstream Producer Integration
+# Distributor HTTP Upload Contract
 
-Audience: developers and LLM coding agents adding `distributor` support to an upstream Go producer application.
+Weatherreporter integrates with the HTTP upload API provided by
+`gitea.maximumdirect.net/eric/distributor v0.5.0`. It submits source bundles to
+a configured pipeline and reads the resulting run status. Configuration fields
+and notification lifecycle are documented in the [configuration reference](../../config.md)
+and [operations guide](../../operations.md).
 
-This document is the copyable implementation guide for submitting producer outputs to a `distributor` pipeline whose source backend is `http_upload`.
+## Upload Admission
 
-## Required Inputs
+Weatherreporter uses an absolute HTTP(S) endpoint as a base URL. The client
+posts a gzip-compressed source bundle to:
 
-The upstream application needs these values from deployment or operator configuration:
-
-- distributor endpoint: the HTTP server base URL, such as `https://distributor.example.com`;
-- upload token: bearer token that authenticates the producer;
-- pipeline id: configured `http_upload` pipeline that should process this upload;
-- generated files: regular local files to include in the source bundle;
-- bundle id: stable identifier for the logical report stream or artifact;
-- idempotency key: unique key for one producer run, reused only when retrying that same run.
-
-Do not put destination routing, public URLs, transform settings, or credentials in the source manifest. Those belong in the `distributor` pipeline configuration.
-
-The token, pipeline id, bundle id, and idempotency key have different jobs. The token authenticates the producer. The pipeline id selects the configured distributor workflow, including destinations and publishing policy. The bundle id tells `distributor` whether a new upload is a newer version of the same source; keep it stable across runs that should replace the same managed destination artifact. The idempotency key tells `distributor` whether an upload request is a retry; change it for each distinct producer run so new content is enqueued.
-
-## Recommended Workflow
-
-Use `gitea.maximumdirect.net/eric/distributor/pkg/upload`.
-
-For most producers, use `UploadFiles`. It accepts producer-generated files, builds a temporary valid source bundle with `pkg/bundle`, uploads a gzip-compressed tar archive, and removes temporary files when the call returns.
-
-Use `UploadBundle` only when the producer already assembled a complete bundle directory containing `manifest.json`.
-
-Add the dependency from the upstream application:
-
-```sh
-go get gitea.maximumdirect.net/eric/distributor
+```text
+POST /v1/pipelines/<pipeline_id>/upload
+Authorization: Bearer <token>
+Content-Type: application/gzip
+Idempotency-Key: <key>
 ```
 
-## Minimal Go Example
+The authenticated token must be allowed to use the selected upload pipeline.
+A successful response is `202 Accepted` with JSON containing `run_id` and
+`status`. Acceptance means Distributor staged and validated the source bundle;
+it does not mean downstream destinations have published it.
 
-```go
-package reports
+The adapter requires a pipeline ID, bundle ID, idempotency key, and at least one
+source-file mapping before calling Distributor. It reads the bearer token from
+the configured environment variable and redacts that value from errors. Request
+construction and timeout handling belong to the [Distributor adapter](../../internal/distributor-adapter.md).
 
-import (
-	"context"
-	"errors"
-	"fmt"
-	"os"
-	"time"
+## Idempotency
 
-	"gitea.maximumdirect.net/eric/distributor/pkg/bundle"
-	"gitea.maximumdirect.net/eric/distributor/pkg/upload"
-)
+Distributor scopes idempotency to the token, pipeline ID, and key. Keys must be
+non-empty ASCII values of at most 128 bytes using letters, digits, `.`, `_`,
+`-`, and `:`. Weatherreporter always supplies a rendered key; it does not rely
+on the client library's generated-key fallback.
 
-func SubmitReport(reportPath, summaryPath string) error {
-	endpoint := os.Getenv("DISTRIBUTOR_UPLOAD_ENDPOINT")
-	token := os.Getenv("DISTRIBUTOR_UPLOAD_TOKEN")
-	if endpoint == "" || token == "" {
-		return fmt.Errorf("distributor endpoint and token are required")
-	}
+Reusing a key for the same normalized source manifest returns the original
+accepted run. Reusing it for different content returns `409 Conflict`, which
+the adapter exposes as a Weatherreporter idempotency-conflict error. A distinct
+report or batch run therefore needs a distinct key; reuse a key only when
+retrying that same upload.
 
-	pipelineID := "weather-hourly"
-	reportID := "weather.hourly.brentwood"
-	runID := time.Now().UTC().Format("20060102T150405.000000000Z")
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	defer cancel()
+## Run Status And Retention
 
-	client, err := upload.NewClient(upload.ClientOptions{
-		Endpoint: endpoint,
-		Token:    token,
-	})
-	if err != nil {
-		return err
-	}
+After acceptance, Weatherreporter reads:
 
-	result, err := client.UploadFiles(ctx, upload.UploadFilesOptions{
-		PipelineID:     pipelineID,
-		ID:             reportID,
-		IdempotencyKey: reportID + "." + runID,
-		Files: []bundle.BundleFile{
-			{SourcePath: reportPath, Path: "report.md"},
-			{SourcePath: summaryPath, Path: "summary.txt"},
-		},
-	})
-	if err != nil {
-		var conflict *upload.IdempotencyConflictError
-		if errors.As(err, &conflict) {
-			return fmt.Errorf("idempotency key was reused for different bundle content: %w", err)
-		}
-		return err
-	}
-
-	fmt.Printf("distributor accepted run %s\n", result.RunID)
-	return nil
-}
+```text
+GET /runs/<run_id>
+Authorization: Bearer <token>
 ```
 
-## Producer Responsibilities
+The status record provides `run_id`, `pipeline_id`, status timestamps, optional
+JSON `report`, and an `error` for failures. Statuses are `accepted`, `queued`,
+`running`, `succeeded`, and `failed`. A terminal `failed` status makes the
+notification fail; the adapter preserves the returned status details for the
+application to record.
 
-- Use a stable bundle id for the logical producer output that should replace the same destination artifact, such as `weather.hourly.brentwood`.
-- Set `PipelineID` to the configured upload pipeline that should process the bundle.
-- Do not include per-run timestamps, random values, or job ids in the bundle id unless each run should be treated as a different source.
-- Use an idempotency key that changes for every distinct producer run, such as `<bundle-id>.<run-id>`.
-- Reuse the same idempotency key only when retrying the exact same producer run with the same source manifest.
-- Map each generated file to a clean slash-separated bundle path, such as `report.md` or `assets/chart.png`.
-- Include only regular files. Symlinks, directories as files, devices, FIFOs, and sockets are rejected.
-- Keep file contents stable after upload inputs are selected. Bundle digests are calculated from file bytes.
-- Treat upload success as admission only. `UploadFiles` and `UploadBundle` return after the server accepts and validates the upload, not after all destinations publish.
+Run and idempotency records are in-memory. Completed records expire according
+to Distributor's `server.http.retention`, and a Distributor restart removes
+retained status and idempotency state. Status polling decisions and persistence
+of notification artifacts are internal orchestration behavior; see the
+[Distributor adapter](../../internal/distributor-adapter.md) and
+[application orchestration](../../internal/app-orchestration.md).
 
-Valid bundle paths are relative slash paths. They must not be empty, absolute, contain backslashes, contain `.` or `..` path segments, contain empty path segments, or use reserved basenames `manifest.json` or `.distributor.json`.
+## Compatibility Reference
 
-## Idempotency And Status
-
-`pkg/upload` sends `Idempotency-Key` on every upload. If the caller omits one, the package generates a random key for that call and reuses it for in-process retries. That is enough for transient network retry within one process, but it does not give cross-process retry identity.
-
-For producer jobs that may retry after process restart, supply a key derived from the producer run, such as `<bundle-id>.<run-id>`. Reusing the same key with the same token, pipeline id, and normalized source manifest returns the original accepted run. Reusing the same key with different source content in that scope returns a conflict. Reusing one key across multiple distinct report generations prevents those generations from being treated as new uploads.
-
-`Status` polls `/runs/<run-id>` while the distributor server retains the in-memory status record. Status values are `accepted`, `queued`, `running`, `succeeded`, and `failed`. Completed records expire according to the server's `server.http.retention` setting, and server restart clears status and idempotency records.
-
-Optional status check:
-
-```go
-status, err := client.Status(ctx, result.RunID)
-if err != nil {
-	return err
-}
-if status.Status == "failed" {
-	return fmt.Errorf("distributor run failed: %s", status.Error)
-}
-```
-
-## References
-
-In the `distributor` source tree:
-
-- `docs/consumers/pkg-upload.md`: Go upload package workflow.
-- `docs/consumers/pkg-bundle.md`: Go bundle package workflow.
-- `docs/integrations/http-upload.md`: canonical HTTP upload wire contract.
-- `docs/integrations/source-bundle.md`: canonical source bundle file-format contract.
+The upstream canonical HTTP wire contract is
+`docs/integrations/http-upload.md` in the Distributor repository. This page
+documents only the portion exercised by Weatherreporter.

docs/integrations/distributor/pkg-bundle.md

@@ -1,90 +1,36 @@
-# `pkg/bundle`
+# Distributor Source Bundle Mapping
 
-Audience: upstream Go producer developers and LLM coding agents using `distributor` source bundle helpers.
+Weatherreporter uses the source-bundle format through Distributor's
+`pkg/upload.UploadFiles` helper. It does not create bundle directories or call
+`pkg/bundle` directly. The helper creates a temporary bundle, writes and
+validates `manifest.json`, archives it, and removes the temporary bundle when
+the upload call returns.
 
-Import path:
+## File Mappings
 
-```go
-import "gitea.maximumdirect.net/eric/distributor/pkg/bundle"
-```
+Every mapping pairs a managed Markdown report source with one bundle-relative
+path. A single-report notification maps its one managed report to each rendered
+path configured for that report. A batch notification combines mappings for
+every included managed report and rejects duplicate bundle paths.
 
-`pkg/bundle` builds, writes, parses, and validates local source bundles. Use it directly when a producer writes bundles for `distributor` to discover, or when a producer wants to assemble and validate a bundle before using another transport.
+The report source is never an `--out` copy or an arbitrary workspace scan. The
+application selects it and renders notification paths; see the [operations guide](../../operations.md)
+for the managed-upload rule and the [Distributor adapter](../../internal/distributor-adapter.md)
+for the adapter boundary.
 
-The canonical source bundle file-format contract is [Source Bundle Contract](../integrations/source-bundle.md).
+Bundle paths must be clean, relative, slash-separated paths. They cannot be
+empty or absolute, contain backslashes, empty segments, `.` or `..`, or use
+`manifest.json` or `.distributor.json` as a basename. The mapped source must be
+a regular file. File mapping order is preserved and affects the bundle digest.
 
-## Preferred Complete-Bundle Workflow
+The bundle manifest uses schema version `1`, carries the rendered bundle ID and
+creation time, and records each mapped file's path, SHA-256 digest, and size.
+Destination routing, publication, and Distributor-managed destination state are
+not source-bundle fields.
 
-Use `WriteBundle` when producer-generated files live outside the final bundle root.
+## Compatibility Reference
 
-```go
-manifest, err := bundle.WriteBundle(bundle.WriteBundleOptions{
-	Root: "/var/spool/distributor/weather/hourly-2026-06-07T15",
-	ID:   "weather.hourly.brentwood",
-	Files: []bundle.BundleFile{
-		{SourcePath: "/tmp/weather/report.md", Path: "report.md"},
-		{SourcePath: "/tmp/weather/summary.txt", Path: "summary.txt"},
-	},
-})
-if err != nil {
-	return err
-}
-_ = manifest
-```
-
-`WriteBundle` copies each source file into a staged bundle root, writes `manifest.json`, validates the staged bundle, and promotes it into place. Set `Overwrite: true` only when the producer intentionally replaces an existing bundle root.
-
-## Existing Bundle Root Workflow
-
-Use `BuildManifest` and `WriteManifest` when files are already staged under the final bundle root.
-
-```go
-root := "/var/spool/distributor/weather/hourly-2026-06-07T15"
-manifest, err := bundle.BuildManifest(bundle.BuildOptions{
-	Root:  root,
-	ID:    "weather.hourly.brentwood",
-	Files: []string{"report.md", "summary.txt"},
-})
-if err != nil {
-	return err
-}
-if err := bundle.WriteManifest(root, manifest, bundle.WriteManifestOptions{}); err != nil {
-	return err
-}
-if err := bundle.ValidateBundle(root, manifest); err != nil {
-	return err
-}
-```
-
-Use `Scan: true` instead of `Files` only when every valid regular file under the root should be included. Scan mode includes dotfiles, skips reserved metadata files, rejects symlinks, and sorts paths lexically.
-
-## Paths And Ordering
-
-Bundle paths are slash-separated paths relative to the bundle root.
-
-Invalid paths include:
-
-- empty paths;
-- absolute paths;
-- paths containing backslashes;
-- `.` or `..` path segments;
-- empty path segments;
-- any basename of `manifest.json` or `.distributor.json`.
-
-Explicit file lists preserve caller order. File order is part of the bundle digest, so producers should choose it deliberately and keep it stable.
-
-The manifest `ID` is the logical source identity used by `distributor` destination comparison. Keep it stable for runs that should replace the same managed destination artifact. If every run uses a different manifest `ID`, `distributor` treats those runs as different sources and may report a destination conflict instead of replacing older output.
-
-## Validation And Digest Helpers
-
-Use `ValidateBundle` before handing an existing local bundle to another process. It verifies manifest semantics, file existence, regular-file type, file size, per-file SHA-256 digests, and bundle digest.
-
-Useful helpers:
-
-- `LoadManifest`: read `manifest.json` from a bundle root.
-- `ParseManifest` and `MarshalManifest`: parse or write manifest bytes.
-- `ValidateManifest`: validate manifest-only semantics.
-- `FileDigest`, `BundleDigest`, and `ValidateDigest`: digest helpers for diagnostics and tests.
-
-## Boundaries
-
-`pkg/bundle` does not upload bundles, publish destinations, transform Markdown, select pipelines, configure credentials, or write destination state. Those concerns belong to `pkg/upload` or the `distributor` application.
+The upstream canonical file-format contract is
+`docs/integrations/source-bundle.md` in the Distributor repository. It defines
+the complete manifest and archive format; this page records only the mapping and
+path constraints Weatherreporter relies on.

docs/integrations/distributor/pkg-upload.md

@@ -1,122 +1,51 @@
-# `pkg/upload`
+# Distributor Upload Client Contract
 
-Audience: upstream Go producer developers and LLM coding agents submitting bundles to `distributor serve`.
+Weatherreporter uses `gitea.maximumdirect.net/eric/distributor/pkg/upload` at
+the pinned module version `v0.5.0`. It constructs one client per notification
+attempt and calls `UploadFiles`, followed by `Status` for the accepted run.
 
-Import path:
+## Client And Upload
 
-```go
-import "gitea.maximumdirect.net/eric/distributor/pkg/upload"
-```
+The adapter constructs the client with the configured endpoint, bearer token,
+and an HTTP client whose timeout is the configured Distributor timeout. It
+passes no custom retry options, so the pinned client's defaults apply: three
+attempts, 100 ms base delay, and one-second maximum delay.
 
-`pkg/upload` is the producer-facing HTTP upload client. It builds on `pkg/bundle`, packages valid source bundles as gzip-compressed tar archives, sends bearer authentication, routes uploads to a configured pipeline, includes idempotency keys, and exposes a status polling helper.
+For each notification, Weatherreporter calls `UploadFiles` with:
 
-`UploadFiles` examples also use:
+- the rendered pipeline ID;
+- the rendered bundle ID as the source manifest ID;
+- the report or batch generation time as `Created`;
+- the managed-report-to-bundle-path mappings described in the
+  [bundle mapping contract](pkg-bundle.md); and
+- a rendered idempotency key.
 
-```go
-import "gitea.maximumdirect.net/eric/distributor/pkg/bundle"
-```
+It leaves bundle validation enabled. `UploadFiles` creates the temporary source
+bundle and sends it as a gzip-compressed tar archive; Weatherreporter does not
+call `UploadBundle` or submit prebuilt bundle roots.
 
-The canonical HTTP wire contract is [HTTP Upload API Contract](../integrations/http-upload.md).
+## Retry, Conflict, And Status
 
-## Client Construction
+The pinned upload client retries only `503 Service Unavailable` and retryable
+network failures. It does not retry successful `202` responses or other HTTP
+errors. Because every Weatherreporter request supplies an idempotency key, a
+retry keeps the same upload identity.
 
-```go
-client, err := upload.NewClient(upload.ClientOptions{
-	Endpoint: "https://distributor.example.com",
-	Token:    token,
-})
-if err != nil {
-	return err
-}
-```
+The client decodes the accepted upload result (`run_id`, `status`) and the run
+status record. A `409` response is an upstream idempotency conflict; the
+adapter translates it to its own conflict error without exposing the token.
 
-`Endpoint` is the distributor server base URL. The client derives `/v1/pipelines/<pipeline-id>/upload` and `/runs/<run-id>`. `Token` is required and is sent as `Authorization: Bearer <token>`. Token values are redacted from client errors.
+The adapter then calls `Status` for the accepted run. A terminal `failed`
+status is a notification failure. A status lookup failure or a timeout before a
+terminal status remains attached to the otherwise accepted upload as diagnostic
+status information. Polling cadence, final failure handling, redaction, and
+notification artifact persistence are internal behavior documented in the
+[Distributor adapter](../../internal/distributor-adapter.md) and
+[application orchestration](../../internal/app-orchestration.md).
 
-`HTTPClient` and `Retry` are optional. Defaults use a 30 second HTTP timeout and safe retry settings.
+## Compatibility Reference
 
-## Upload Producer Files
-
-Use `UploadFiles` when the producer has generated output files but has not assembled a bundle directory.
-
-```go
-result, err := client.UploadFiles(ctx, upload.UploadFilesOptions{
-	PipelineID:     "weather-hourly",
-	ID:             "weather.hourly.brentwood",
-	IdempotencyKey: "weather.hourly.brentwood.20260607T150000Z",
-	Files: []bundle.BundleFile{
-		{SourcePath: "/tmp/weather/report.md", Path: "report.md"},
-		{SourcePath: "/tmp/weather/summary.txt", Path: "summary.txt"},
-	},
-})
-if err != nil {
-	return err
-}
-_ = result.RunID
-```
-
-`PipelineID` is required and selects the configured distributor workflow for this upload. `ID` is the source manifest id and identifies the logical artifact inside that workflow. `UploadFiles` creates a temporary bundle, writes and validates a manifest, uploads the archive, and removes temporary files when the call returns. It does not write into producer source directories.
-
-## Upload An Existing Bundle
-
-Use `UploadBundle` when the producer already has a complete local bundle root containing `manifest.json`.
-
-```go
-result, err := client.UploadBundle(ctx, upload.UploadBundleOptions{
-	PipelineID:     "weather-hourly",
-	Root:           "/var/spool/weather/hourly-2026-06-07T15",
-	IdempotencyKey: "weather.hourly.brentwood.20260607T150000Z",
-})
-if err != nil {
-	return err
-}
-_ = result.RunID
-```
-
-`PipelineID` is required for existing bundles too. `UploadBundle` validates the local bundle by default and uploads only `manifest.json` plus manifest-listed files. Unlisted files are not uploaded.
-
-## Result And Status
-
-Upload success means the server returned `202 Accepted` after staging and validating the upload. It does not mean all configured destinations have published.
-
-Poll status while the server retains the in-memory run record:
-
-```go
-status, err := client.Status(ctx, result.RunID)
-if err != nil {
-	return err
-}
-if status.Status == "failed" {
-	return fmt.Errorf("distributor run failed: %s", status.Error)
-}
-```
-
-Status values are `accepted`, `queued`, `running`, `succeeded`, and `failed`. Completed records expire according to `server.http.retention`; server restart clears run status and idempotency records.
-
-## Idempotency And Retry
-
-Every upload request includes `Idempotency-Key`.
-
-If `IdempotencyKey` is omitted, the client generates a random 128-bit lowercase hexadecimal key for that upload operation and reuses it for retries within the same call. For cross-process retry safety, producers should pass a key derived from the producer run, such as `<bundle-id>.<run-id>`.
-
-Do not reuse the same idempotency key for multiple distinct report generations. Reuse it only when retrying the exact same run with the same token, pipeline id, and source manifest. A repeated key with the same manifest in that scope returns the original accepted run instead of enqueueing another run; a repeated key with different content returns an idempotency conflict.
-
-The client retries only safe cases:
-
-- `503 Service Unavailable`;
-- temporary network errors;
-- ambiguous mid-upload failures.
-
-It does not retry after `202 Accepted` and does not retry `400`, `401`, `403`, `404`, `409`, `413`, or `415`.
-
-Detect conflicting key reuse with `errors.As`:
-
-```go
-var conflict *upload.IdempotencyConflictError
-if errors.As(err, &conflict) {
-	return fmt.Errorf("idempotency key was reused for different bundle content: %w", err)
-}
-```
-
-## Boundaries
-
-`pkg/upload` does not configure server pipelines, choose destinations, wait for publication completion automatically, persist client queues, provide durable idempotency across server restarts, or expose destination state. It submits complete source bundles to the configured HTTP upload API.
+The upstream package workflow is documented in
+`docs/consumers/pkg-upload.md` in the Distributor repository. Weatherreporter
+uses only the client construction, `UploadFiles`, retry/conflict behavior, and
+`Status` operations described here.

docs/integrations/scriptorium.md

@@ -1,98 +1,91 @@
 # Scriptorium Integration
 
-This document describes the external Scriptorium CLI contract used by
-`weatherreporter`.
+`weatherreporter` invokes the Scriptorium executable as a subprocess to
+preflight prompt input and produce report artifacts. This is the limited CLI
+contract Weatherreporter uses, not general Scriptorium documentation.
 
-## Purpose
+## Invocation
 
-`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.
+The configured `scriptorium.binary` is the executable name or path. When it is
+empty, the adapter invokes `scriptorium`. Arguments are passed directly to the
+process, without a shell.
 
-## Commands Used
+For every command, arguments occur in this order:
 
-Render preflight:
+1. The subcommand.
+2. `--config <path>` when `scriptorium.config_path` is set.
+3. `--profile <profile>` when `scriptorium.profile` is set.
+4. The command-specific arguments below.
+5. Each configured `scriptorium.extra_args` item.
 
-```bash
-scriptorium render \
-  --prompt <prompt_id> \
-  --input data_package=<path> \
-  --format json
+The adapter uses these exact command shapes:
+
+```text
+scriptorium render [--config <path>] [--profile <profile>] \
+  --prompt <prompt_id> --input data_package=<data_package_path> --format json \
+  [<extra_arg> ...]
+
+scriptorium run [--config <path>] [--profile <profile>] \
+  --prompt <prompt_id> --input data_package=<data_package_path> --out <output_path> \
+  [<extra_arg> ...]
 ```
 
-Report generation:
+`render` is the preflight command. `run` writes either a Markdown report or a
+raw generated-text artifact to the supplied `--out` path. The structured
+generated-text use of `run` has the same argv as Markdown generation; it does
+not add `--format`, `--schema`, `--schema-path`, or `--json-schema` flags.
+Prompt configuration selected by `<prompt_id>` controls that output.
 
-```bash
-scriptorium run \
-  --prompt <prompt_id> \
-  --input data_package=<path> \
-  --out <artifact_path>
-```
+## Inputs and Outputs
 
-`weatherreporter` always passes prompt input as
-`--input data_package=<path>`. The data package is structured YAML created by
-`internal/promptinput`; module snapshots remain separate JSON artifacts for
-inspection and Recent Changes.
+Weatherreporter always supplies exactly one prompt input:
+`--input data_package=<data_package_path>`. The path identifies the YAML data
+package produced by the [prompt-input builder](../internal/prompt-input.md).
+Its schema and the separate JSON module snapshots are internal artifacts, not
+part of this CLI contract.
 
-## Configured Arguments
+The application supplies an already-managed output path to every `run` call.
+For direct reports it is the Markdown artifact path. For generated-text
+reports it is the raw JSON artifact path; subsequent validation and Markdown
+rendering are owned by [generated-text processing](../internal/generatedtext.md).
 
-The adapter can prepend configured flags before prompt-specific arguments:
+`render` has no output-path argument. Its JSON-formatted stdout remains
+captured output: the adapter records it and does not parse it into a separate
+CLI result type. Likewise, the adapter records `run` output metadata without
+decoding the artifact written at `--out`.
 
-- `--config <path>` from `scriptorium.config_path`
-- `--profile <profile>` from `scriptorium.profile`
+## Execution and Results
 
-It appends `scriptorium.extra_args` after the built-in arguments. Extra
-arguments are passed directly as argv items.
+`scriptorium.timeout`, when greater than zero, creates a timeout for each
+subprocess invocation. Parent-context cancellation and that timeout stop the
+command through the process context.
 
-`scriptorium.binary` selects the executable name or path. If unset inside the
-adapter, it falls back to `scriptorium`.
+Stdout and stderr are captured independently, each up to 1 MiB. Every returned
+result records the complete argv as `command`, the captured `stdout` and
+`stderr`, `exitCode`, and `stdoutTruncated` and `stderrTruncated` when a stream
+was capped. Results from both forms of `run` also record `outputPath`, the
+requested `--out` value.
 
-## Execution Behavior
-
-The adapter runs Scriptorium without shell interpolation. Arguments are passed
-through `exec.CommandContext`.
-
-`scriptorium.timeout` limits each subprocess call when configured. Context
-cancellation or timeout returns an execution error.
-
-Stdout and stderr are captured separately. Each stream is capped at 1 MiB and
-the result records whether truncation occurred.
-
-## Results
-
-Render results include:
-
-- full argv recorded as `command`
-- stdout
-- stderr
-- exit code
-- truncation flags when applicable
-
-Run results include the same fields plus the requested output path.
-
-`weatherreporter` persists render preflight JSON when orchestration reaches the
-preflight save point. The final Markdown artifact is written by Scriptorium to
-the `--out` path.
+The [Scriptorium adapter](../internal/scriptorium-adapter.md) owns process
+execution and result capture. [Application orchestration](../internal/app-orchestration.md)
+owns when preflight output, report artifacts, and generated-text artifacts are
+persisted.
 
 ## Failure Behavior
 
-The adapter validates required request fields before starting Scriptorium:
+Before starting Scriptorium, the adapter requires a prompt ID and data-package
+path for every command, plus an output path for `run`. Missing fields fail
+without executing a subprocess.
 
-- prompt ID
-- data package path
-- output path for `run`
+A nonzero process exit returns the captured result and an error that includes
+the exit code and stderr. An output file written before such an exit does not
+make the request successful. Failures to start the command, context
+cancellation, and timeout return an error rather than a successful result.
 
-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.
+## Operational Notes
 
-Subprocess start failures, context cancellation, and timeouts return errors
-without fabricating a successful result.
-
-## Security Notes
-
-- 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.
+- Extra arguments are argv items; they are not shell-interpreted.
+- Prompt input, generated artifacts, stdout, and stderr can contain
+  operationally sensitive weather data.
+- Provide API keys through the Scriptorium environment or its configuration,
+  not through Weatherreporter CLI arguments.

docs/integrations/weatherapi.md

@@ -1,26 +1,51 @@
 # Weather API Integration
 
-This document describes the external Weather API contract used by
-`weatherreporter`.
+Weatherreporter fetches normalized weather inputs from a configured Weather API
+base URL. This guide defines the HTTP contract the service must satisfy; it is
+not a general Weather API reference. Configuration values are defined in the
+[configuration reference](../config.md). Normalization and collection behavior
+are documented in [Weather data internals](../internal/weather-data.md) and
+[Collection internals](../internal/collect.md).
 
-## Purpose
+## Base URL And Requests
 
-`weatherreporter` uses a configured Weather API base URL to fetch normalized
-weather source data and assemble a `weatherdata.Bundle`. This is an integration
-contract for the project adapter, not a complete public API reference for the
-upstream service.
+`weather_api.base_url` must be an absolute URL. Weatherreporter joins each
+endpoint path to the configured base URL path, so a service hosted under a path
+prefix must keep that prefix available. Requests use `GET` and carry the
+configured timeout on every HTTP attempt.
 
-## Base URL
+Every request sends `format` and, except where noted below, `units`. The
+configured format must be `json`.
 
-`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.
+Before retrieving sources, Weatherreporter warms up
+`/conditions/current` with the same `format`, `units`, and `precision` query
+parameters used for current conditions. The warmup only requires a readable
+2xx response; its body is not decoded. Failure after its internal retry budget
+stops the fetch before source requests begin.
 
-The HTTP client uses `weather_api.timeout`.
+## Endpoints And Query Parameters
+
+The adapter makes one source request for each endpoint after a successful
+warmup, subject to retry on transient failures.
+
+| Source | Endpoint | Query parameters | Availability |
+| --- | --- | --- | --- |
+| Observations | `/observations` | `format`, `units`, `precision` | Optional |
+| Current conditions | `/conditions/current` | `format`, `units`, `precision` | Optional |
+| Hourly forecast | `/forecast/hourly` | `format`, `units`, `precision`, `tz` | Required |
+| Narrative forecast | `/forecast/narrative` | `format`, `units`, `precision`, `tz` | Optional |
+| Active alerts | `/alerts/active` | `format`, `units` | Optional; `data: null` means checked with no active alerts |
+| Forecast discussion | `/discussion` | `format`, `units`, `tz` | Optional |
+| Weather story | `/weatherstories/latest` | `format` | Optional |
+| SPC convective outlooks | `/outlooks/convective` | `format`, `tz` | Optional; non-null empty lists are checked empty data |
+
+`precision` comes from `weather_api.precision`; `tz` comes from
+`weather_api.timezone`. Weatherreporter does not call day-slice forecast or
+discussion-subsection endpoints.
 
 ## Response Envelope
 
-Every response used by the adapter must be JSON with a top-level `data` field:
+Each endpoint response must be JSON with a top-level `data` member:
 
 ```json
 {
@@ -28,105 +53,95 @@ Every response used by the adapter must be JSON with a top-level `data` field:
 }
 ```
 
-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.
+An absent `data` member is treated as a missing source. For ordinary sources,
+`data: null` is also missing. The active-alert exception is listed above: its
+explicit `null` payload represents an empty alert result.
 
-`/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.
+Hourly forecast data must be present and contain at least one `period`; a
+missing, malformed, or empty hourly product fails collection. The remaining
+sources follow the configured missing-source policy. Under `error`, collection
+fails; under `warn`, the source is omitted and an inspectable warning is
+recorded; under `none`, the source is omitted without a warning. A per-source
+policy overrides the default. See [Configuration](../config.md) for policy
+settings and [Weather data internals](../internal/weather-data.md) for recorded
+source metadata.
 
-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.
+Malformed top-level JSON envelopes and HTTP failures are direct request errors.
+Malformed `data` for an optional source follows its missing-source policy.
 
-## Query Parameters
+## Payload Fields Used
 
-The adapter sends these query parameters:
+Weatherreporter decodes only the fields below; additional upstream fields are
+ignored. Timestamps must be JSON values accepted by Go's `time.Time` decoder.
 
-- `format`: from `weather_api.format`; configuration validation 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
+### Observations And Current Conditions
 
-Alerts do not receive `precision` or `tz`. Weather story requests receive only
-`format=json`.
+`/observations` uses `stationId`, `stationName`, `timestamp`, `conditionCode`,
+`isDay`, `textDescription`, `temperatureC`, `temperatureF`, `dewpointC`,
+`dewpointF`, `windSpeedKmh`, `windSpeedMph`, `windGustKmh`, `windGustMph`,
+`windDirectionDegrees`, `barometricPressurePa`, `barometricPressureInHg`,
+`visibilityMeters`, `visibilityMiles`, `relativeHumidityPercent`,
+`apparentTemperatureC`, `apparentTemperatureF`, and `presentWeather`.
 
-## Endpoints Used
+`/conditions/current` uses `conditionText`, `isDay`,
+`relativeHumidityPercent`, `windDirectionDegrees`, `temperatureC`,
+`temperatureF`, `apparentTemperatureC`, `apparentTemperatureF`, `dewpointC`,
+`dewpointF`, `windSpeedKmh`, and `windSpeedMph`.
 
-The adapter fetches these endpoints once per bundle:
+### Hourly And Narrative Forecasts
 
-- `/observations`
-- `/conditions/current`
-- `/forecast/hourly`
-- `/forecast/narrative`
-- `/alerts/active`
-- `/discussion`
-- `/weatherstories/latest`
+Both forecast endpoints use run-level `locationId`, `locationName`, `issuedAt`,
+`updatedAt`, `product`, `latitude`, `longitude`, `elevationMeters`,
+`elevationFeet`, and `periods`.
 
-`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.
+Each `periods` item uses `startTime`, `endTime`, `name`, `isDay`,
+`conditionCode`, `textDescription`, `temperatureC`, `temperatureF`,
+`temperatureCMin`, `temperatureFMin`, `temperatureCMax`, `temperatureFMax`,
+`dewpointC`, `dewpointF`, `windSpeedKmh`, `windSpeedMph`, `windGustKmh`,
+`windGustMph`, `windDirectionDegrees`, `barometricPressurePa`,
+`barometricPressureInHg`, `visibilityMeters`, `visibilityMiles`,
+`apparentTemperatureC`, `apparentTemperatureF`, `cloudCoverPercent`,
+`probabilityOfPrecipitationPercent`, `precipitationAmountMm`,
+`precipitationAmountIn`, `snowfallDepthMM`, `snowfallDepthIn`, `uvIndex`, and
+`relativeHumidityPercent`.
 
-## Required And Optional Sources
+### Alerts, Discussion, And Weather Story
 
-Hourly forecast is required:
+`/alerts/active` uses the `asOf` timestamp and keeps each item in `alerts` as
+an alert payload. Weatherreporter does not require a separate alert-item schema
+at this integration boundary.
 
-- `data: null` for `/forecast/hourly` fails the fetch.
-- an hourly forecast with no `periods` fails the fetch.
-- malformed hourly data fails the fetch.
+`/discussion` uses `officeId`, `officeName`, `product`, `issuedAt`,
+`updatedAt`, `keyMessages`, and the `shortTerm` and `longTerm` sections. Each
+section uses `qualifier`, `text`, and `issuedAt`.
 
-Other fetched sources are optional and follow `missing_source.default` or a
-source-specific `missing_source.sources` policy:
+`/weatherstories/latest` uses `officeId`, `startTime`, `endTime`, `updatedAt`,
+`title`, `description`, `altText`, `priority`, `order`, and `downloadUrl`.
 
-- `observations` for `/observations`
-- `current` for `/conditions/current`
-- `narrative` for `/forecast/narrative`
-- `alerts` for `/alerts/active`
-- `discussion` for `/discussion`
-- `weather_story` for `/weatherstories/latest`
+### SPC Convective Outlooks
 
-Policy behavior:
+`/outlooks/convective` uses run-level `locationId`, `locationName`, `asOf`,
+`issuedAt`, `updatedAt`, `product`, `outlooks`, and `discussions`.
 
-- `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
+Each outlook uses `id`, `provider`, `product`, `day`, `outlookType`, `label`,
+`labelText`, `forecaster`, `severityRank`, `validFrom`, `validTo`, `issuedAt`,
+`expiresAt`, `sourceUrl`, `imageUrl`, `containsLocation`, and GeoJSON
+`geometry`. Each discussion uses `day`, `headline`, `summary`, `discussion`,
+and `updatedAt`.
 
-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.
+## Timeouts, Retries, And Failures
 
-## Source Identity
+The configured Weather API timeout applies to each warmup and source HTTP
+attempt. Weatherreporter retries transient transport and response-read failures
+and these response statuses: `408`, `429`, `500`, `502`, `503`, and `504`.
+It does not retry other HTTP statuses, malformed envelopes, missing data, or
+payload decoding failures. A canceled context also stops an in-progress retry
+delay.
 
-For source payloads accepted into the bundle, including the explicit `null`
-alerts payload, the adapter records:
+The adapter reads at most 10 MiB from one response body. A non-2xx response,
+request construction failure, read failure, or decode failure includes endpoint
+context in its error.
 
-- 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
-
-Warnings are recorded both on the affected source and on the bundle-level
-warnings list.
-
-## Compatibility Assumptions
-
-The adapter expects payload fields compatible with the internal forecast bundle
-types in `internal/forecast/bundle.go`, including:
-
-- 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
-
-The adapter intentionally keeps upstream transport and envelope details inside
-`internal/adapters/weatherapi`; downstream packages consume the normalized
-bundle.
+Retry counts and delays are adapter behavior rather than Weather API request
+parameters. Do not depend on a particular attempt count when implementing the
+service.

docs/internal/app-orchestration.md

@@ -1,148 +1,110 @@
-# App Orchestration Internals
+# Application Orchestration Internals
 
-This document describes the 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 collected and derived facts, builds module snapshots and prompt-input
-artifacts, invokes Scriptorium through the adapter boundary, optionally
-notifies distributor through an app-owned notifier boundary, persists managed
-state, runs batches, and reads existing artifacts for inspection.
+`internal/app` composes top-level generation, batch, collection-save, and
+inspection workflows after CLI parsing and configuration loading. It owns
+workflow ordering, request composition, partial-result handling, and the
+application-facing interfaces used for tests.
 
 ## Inputs And Outputs
 
-Inputs:
+The package accepts generate, resolved-report, batch, explicit-collection, and
+inspection requests. Generation and batch requests may supply collector,
+renderer, store, and notifier implementations for tests; production defaults
+use the focused packages.
 
-- `GenerateRequest` for one report command
-- `BatchRequest` for morning or evening batch commands
-- `FetchBundleRequest` for explicit bundle fetch and save workflows
-- `ReportRequest` for single-report generation
-- resolved report definitions from `internal/report`
-- weather data bundles from `internal/adapters/weatherapi`
-- prior snapshots loaded from `internal/state`
-- optional renderer, notifier, and state-store fakes for tests
+A report result contains the module snapshot, prompt package, available
+Scriptorium results, generated-text artifacts when used, report and metadata
+paths, prior snapshot, Recent Changes, and notification information. A batch
+result contains aggregate counts, per-report outcomes, and an optional batch
+notification. Inspection returns persisted values only.
 
-Outputs:
+Exact public command syntax, configuration fields, workspace layout, external
+protocols, and report definitions belong in [the CLI reference](../cli.md),
+[the configuration reference](../config.md), [operations](../operations.md),
+and their focused integration and internal documents.
 
-- generated report results with JSON module snapshot, YAML data package,
-  preflight, report, metadata, prior snapshot, Recent Changes, Scriptorium
-  result details, and notification result when attempted
-- batch summaries with per-report status, artifact paths, error text, and
-  notification outcome when attempted
-- saved Weather API bundle JSON for fetch workflows
-- inspection JSON values for reports, metadata, module snapshots, data
-  packages, prior snapshots, and source provenance
+## Single-Report Workflow
 
-## Boundaries
+`GenerateDetailed` first collects weather data, then resolves the requested
+report using the configured registry and current time, and finally calls
+`GenerateReport` with that explicit collection. It returns no result when
+collection or resolution fails.
 
-`internal/app` owns workflow order and request composition. It does not parse
-CLI flags, load YAML files directly, implement HTTP transport, own fact
-derivation algorithms, define report periods, compare rendered Markdown, or
-construct Scriptorium argv.
+`GenerateReport` requires a non-nil normalized bundle and then performs this
+ordered work:
 
-Report selection and report identity policy come from `internal/report`.
-Collected and derived fact contracts come from `internal/facts`.
-Weather API transport stays in `internal/adapters/weatherapi`. Scriptorium
-subprocess behavior stays in `internal/adapters/scriptorium`. Distributor
-upload behavior stays in `internal/adapters/distributor`. Filesystem layout and
-persisted metadata stay in `internal/state`.
+1. Select a state store, determine artifact destinations, and locate a prior
+   compatible snapshot.
+2. Build report facts and deterministic module snapshots, then save the module
+   snapshot and calculate Recent Changes.
+3. Build and save the prompt data package, run Scriptorium render preflight,
+   save any preflight result, and save initial metadata.
+4. Produce managed Markdown according to the report generation mode.
+5. Optionally make an output copy, save final metadata, optionally notify
+   Distributor from the managed report path, and save metadata again when a
+   notification path is produced.
 
-## Config Fields Used
+Direct-Markdown reports prepare the managed report and invoke the Scriptorium
+run boundary. Generated-text-template reports look up their catalog definition,
+run structured Scriptorium output to the raw artifact, preserve any structured
+run result, validate and save generated text, build and save a render context,
+then render the embedded Markdown template. Schema, template, and subprocess
+details remain in their [generated-text](generatedtext.md),
+[report-template](reporttemplate.md), and [Scriptorium adapter](scriptorium-adapter.md)
+owners.
 
-- `weather_api.*` for Weather API client construction and module metadata
-- `scriptorium.*` for renderer construction
-- `workspace.*` for filesystem state
-- `dayparts` for daily and outlook summarization
-- `recent_change.*` for structured Recent Changes thresholds
-- `notify.distributor.*` for optional notification after report generation
+If preflight returns a result with an error, the result and initial metadata are
+saved before the error returns. If report generation fails after a managed path
+is prepared, metadata still records that path; output copies and notification
+are skipped. Generated-text failures preserve the latest artifact reached
+before failure when it was saved.
 
-Output copy flags are command request fields. They are not configuration
-defaults.
+## Batch And Inspection Workflows
 
-## Generation Workflow
+`RunBatchDetailed` collects once, asks the report registry to plan the batch
+from that collection, and invokes `GenerateReport` independently for every
+planned report using the same collection and state store. Per-report
+notification is suppressed. A failed report is recorded and does not prevent
+later planned reports from running.
 
-Single-report generation follows this order:
+After report generation, the batch notifier is considered once. It is omitted
+when Distributor or batch notification is disabled, skipped when any report
+failed, and otherwise receives one multi-file request. A batch notification
+failure increments the aggregate failure count but does not rewrite successful
+report items. Notification identities, path mappings, polling, and redaction
+are owned by the [Distributor adapter](distributor-adapter.md).
 
-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 collected and derived facts once.
-6. Execute configured modules and save the module snapshot.
-7. Compute Recent Changes from structured prior and current module snapshots.
-8. Build and save the YAML 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.
-15. If distributor notification is enabled, notify using the managed report
-    path as the source file.
-16. Save a distributor notification debug artifact and update metadata with its
-    path.
+Inspection methods create a state store and load existing report records,
+metadata, module snapshots, prompt packages, prior snapshots, or source
+provenance. They neither collect data nor invoke Scriptorium or Distributor.
 
-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. Notification is not attempted after Weather API,
-module snapshot, prompt input, render, Scriptorium run, or metadata-save
-failures.
-When notification is attempted, the debug artifact records request identity,
-including rendered pipeline ID, bundle paths, accepted upload fields,
-distributor status fields, raw status report JSON when available, and redacted
-failure context.
-`--out` copies are never used as notification source files.
+## Boundaries And Failure Propagation
 
-## Batch Workflow
+The app layer does not parse flags, load configuration files, implement Weather
+API transport, construct Scriptorium argv, or define report registry policy. It
+coordinates the relevant collaborators and preserves their error context.
 
-`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.
-When notification is enabled, each successfully generated report is notified
-independently. Notification failure marks that report failed, records
-notification fields in the batch result, and does not stop later reports.
-`--out-dir` copies are never used as notification source files.
+- Collection failure stops a single report or batch before resolution or
+  planning completes.
+- State, fact, module, prompt-input, or preflight failures stop that report
+  before report generation.
+- A terminal Distributor failure is returned with the saved notification
+  information when available.
+- Batch failures are represented per report and through aggregate batch status.
+- Persisted artifact paths are carried in results so callers can inspect work
+  completed before a later failure.
 
-## Inspection Workflow
+## Tests And Invariants
 
-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.
+Focused tests are in `internal/app/app_test.go` and
+`internal/app/batch_plan_test.go`, with collection coverage in
+`internal/collect/collect_test.go`.
 
-## Failure Behavior
-
-- Resolve errors stop the requested workflow before fetching weather data.
-- Weather API and module execution 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.
-- Notification errors are wrapped with report ID, RunID, and managed report path
-  context and are recorded separately in batch results.
-- 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 module snapshots.
-- Metadata links artifacts produced for a run.
-- Distributor notification maps the managed Markdown report path to configured
-  bundle paths; extra output copies are not upload sources.
+- Production workflows collect through `internal/collect`.
+- A report uses one explicit normalized collection throughout its generation.
+- Render preflight precedes report generation.
+- Recent Changes compare structured module snapshots.
+- Generated-text reports render from a validated typed context, never directly
+  from a raw prompt package.
+- Only managed Markdown reports are notification sources; output copies are
+  never uploaded.

docs/internal/briefing.md

@@ -1,104 +1,69 @@
 # Module Builder Internals
 
-This document describes module builder behavior in `internal/briefing`.
+`internal/briefing` builds typed module outputs from resolved report context,
+collected facts, and derived facts. It owns the module registry, including
+module support, fact requirements, option types, missing-data policy, builders,
+and prompt-export hooks. It does not collect data, derive periods, write a
+snapshot, construct YAML, invoke Scriptorium, or render a report.
 
-## Purpose
+## Registry and construction
 
-`internal/briefing` turns report metadata, collected weather data, and derived
-forecast facts into prompt-facing module outputs. The package also owns the
-module registry used to validate report composition and config overrides.
+Every `ModuleDefinition` declares an ID, stanza name, default option value,
+required collected and derived facts, supported report IDs, missing-data
+behavior, duplicate policy, builder, and optional prompt exporter.
 
-Module outputs are structured prompt inputs. They are not rendered report prose
-and they are not persisted by this package.
+`BuildModule` first verifies the requested module, report compatibility, and
+option shape. It then applies the declared missing-data behavior:
 
-## Inputs And Outputs
+- `omit` returns no output for unavailable optional facts;
+- `error` returns the missing fact requirements; and
+- `empty` allows the builder to emit an explicit checked-empty value.
 
-Inputs:
+Unsupported `warn` behavior, missing builders, duplicate registry IDs or
+stanza names, output ID or stanza mismatches, and exporter failures all return
+errors with module context. A successful builder gets a pass-through prompt
+value unless its definition supplies an exporter.
 
-- resolved report definition, generation time, timezone, and valid period
-- collected facts built from `weatherdata.Bundle`
-- derived daily, daypart, precipitation, alert, and storm-window facts where
-  required
-- configured units, timezone, and descriptive location context
-- typed module options from report defaults or config overrides
+## Built value families
 
-Outputs:
+Source-oriented builders shape report metadata, current conditions, narrative
+and hourly forecasts, alert digest, SPC outlooks and discussion, area forecast
+discussion, and weather story. Derived builders shape daily and daypart
+summaries, precipitation timing, outdoor windows, and the report-specific
+Daily, Today, and Tomorrow planning values.
 
-- `ModuleDefinition` values with module ID, stanza name, option type,
-  supported reports, fact requirements, missing-data behavior, and builder
-- `module.Output` values for source-oriented stanzas:
-  `metadata`, `current_conditions`, `narrative_forecast`, `hourly_forecast`,
-  `alert_digest`, `area_forecast_discussion`, and `weather_story`
-- `module.Output` values for derived stanzas:
-  `derived_daily_summary`, `derived_daypart_summaries`, `precip_timing`,
-  `outdoor_windows`, and `tomorrow_planning`
+The module registry preserves rich values for templates and snapshots while
+curating prompt exports where needed. In particular, source warnings are a
+metadata summary, checked-empty alerts and SPC outlooks remain distinct from
+missing sources, and prompt-safe SPC values omit geometry and other
+template-only or source details. The complete module composition is in
+[module internals](module.md); fact derivation is in [fact contracts](facts.md).
 
-Every registered composition entry has a builder. Unknown or unimplemented
-module IDs fail validation instead of being skipped.
+`area_forecast_discussion` accepts an optional typed section filter. Planning
+modules are report-specific: `daily_planning` supports Daily,
+`today_planning` supports Today, and `tomorrow_planning` supports Tomorrow.
 
-Prompt-facing module values use local, human-readable date and time labels
-where the LLM is expected to reason about report content. Canonical timestamps
-remain in report metadata, source provenance, and integration artifacts.
+## Missing data and boundaries
 
-## Boundaries
+Optional current conditions, narrative products, discussions, and weather
+stories may be omitted. Required derived modules fail when their declared facts
+are unavailable. Empty alert and outlook runs can still produce checked-empty
+modules. SPC discussion is omitted unless a retained categorical outlook meets
+the package's severity criterion and matching discussion text exists.
 
-- This package selects and shapes already-collected weather facts for prompts.
-- It validates module composition against report compatibility and option
-  types.
-- It does not fetch weather data, compare prior snapshots, write module
-  snapshots, build YAML data packages, invoke Scriptorium, or write workflow
-  metadata.
+Effective units, timezone, and location context arrive in `ModuleContext` from
+configuration and resolved report metadata. Field defaults are owned by
+[configuration](../config.md), and prompt-package layout is owned by
+[prompt input](prompt-input.md).
 
-## Config Fields Used
+## Verification and invariants
 
-The app layer passes effective units, timezone, and location context into the
-module context. `internal/facts` consumes daypart configuration before module
-builders run. Configured `location` values are prompt context only; Weather API
-`sourceLocationId` and `sourceLocation` remain source provenance.
+Focused tests cover source and derived values, registry validation, option
+handling, prompt exporters, support rules, and missing-data behavior:
 
-`area_forecast_discussion` uses optional `sections` configuration to include a
-subset of discussion fields.
+```sh
+go test ./internal/briefing
+```
 
-## External Adapters Used
-
-None directly.
-
-## State Or Manifest Behavior
-
-None. `internal/app` collects module outputs into a `module.Snapshot`, and
-`internal/state` persists that snapshot.
-
-## Skip And Resume Behavior
-
-None. Builders either emit a module output, omit optional unavailable data, or
-return an error for invalid required inputs.
-
-## Failure Behavior
-
-- Required derived modules return errors when their dependent facts are not
-  available.
-- Module registry construction rejects duplicate module IDs and duplicate
-  stanza names.
-- Composition validation rejects unknown modules, duplicate modules,
-  incompatible report/module combinations, duplicate stanza names, and invalid
-  option shapes.
-- Source-oriented module builders omit missing optional current conditions,
-  forecast discussion, and weather story stanzas.
-- Alert digest output distinguishes checked empty alert data from missing alert
-  source data.
-
-## Tests
-
-Inspect:
-
-- `internal/briefing/base_modules_test.go`
-- `internal/briefing/derived_modules_test.go`
-- `internal/briefing/modules_test.go`
-- `internal/app/app_test.go`
-
-## Invariants
-
-- Module outputs 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.
-- Prompt input packaging and Scriptorium execution remain outside this package.
+Builders emit structured facts, never report prose. The app collects their
+outputs into a module snapshot, and state persists that snapshot.

docs/internal/changes.md

@@ -1,75 +1,61 @@
 # Changes Internals
 
-This document describes structured Recent Changes comparison.
+`internal/changes` deterministically compares a compatible prior module
+snapshot with the current snapshot. It returns compact structured changes for
+prompt input; it never reads state, finds a prior report, renders Markdown, or
+compares generated text. Snapshot construction belongs to
+[module internals](module.md), and prior-snapshot discovery belongs to
+[state internals](state.md).
 
-## Purpose
+## Comparison inputs and output
 
-`internal/changes` compares current and prior module snapshots and emits
-compact change records for prompt input data packages.
+Each comparator receives a prior snapshot, a current snapshot, and
+`Thresholds`. A `Change` has a stable type and message plus previous and
+current values where useful. Changes are sorted by type and then message, so
+the same inputs always yield the same order.
 
-## Inputs And Outputs
+Threshold values are supplied by application orchestration from the
+[Recent Changes configuration](../config.md#recent_change); this package does
+not load configuration or choose defaults. Numeric changes are emitted when
+the absolute difference meets the configured threshold. Precipitation also
+requires a change between its low, possible, likely, and high categories.
 
-Inputs:
+## Strategies
 
-- prior module snapshot
-- current module snapshot
-- comparison thresholds from configuration
+| Comparator | Required snapshot data | Compared values |
+| --- | --- | --- |
+| `CompareDaily` | `derived_daily_summary`, `derived_daypart_summaries` | Low and high temperature, daily precipitation probability and timing, peak gust, alerts, and aggregate indicators |
+| `CompareThreeDay` | `derived_daypart_summaries` | Per-day temperatures, precipitation probability and timing, peak gust, indicators, and added or removed outlook days |
+| `CompareWeekend` | `derived_daypart_summaries` | The three-day values with weekend-prefixed change types |
 
-Outputs:
+For daily comparison, `alert_digest` and `precip_timing` are optional: alerts
+are compared when present, and timing is compared only when both snapshots
+contain it. The multi-day comparators build their day map from daypart
+summaries. A missing or added day becomes a dedicated change rather than a
+comparison against invented data.
 
-- ordered `changes.Change` items with type, message, previous value, and current
-  value where useful
+The application selects a comparator only after state lookup establishes a
+compatible prior snapshot. Daily, Today, and Tomorrow use the daily comparator;
+Three-day and Weekend use their named comparators. Other report types, such as
+Storm, produce no Recent Changes list.
 
-## Boundaries
+## Missing data and failures
 
-- This package compares structured module snapshot data only.
-- It does not read filesystem state, find prior snapshots, render Markdown,
-  invoke Scriptorium, or compare generated report text.
+Required stanzas that are absent or cannot be decoded return an error with the
+snapshot and stanza context. Optional stanzas may be absent. A snapshot with no
+eligible predecessor is not a comparison failure: the caller supplies an empty
+change list without invoking this package.
 
-## Config Fields Used
+The package has no filesystem, transport, CLI, renderer, or persistence
+behavior. It does not decide report compatibility or retain snapshots.
 
-The app maps these fields into comparison thresholds:
+## Verification and invariants
 
-- `recent_change.temperature_degrees`
-- `recent_change.precip_probability_points`
-- `recent_change.wind_gust_miles_per_hour`
-- `recent_change.precip_timing_shift_minutes`
+Focused tests cover the daily, three-day, and weekend strategies, threshold
+boundaries, indicator and alert changes, and missing required stanzas:
 
-## External Adapters Used
+```sh
+go test ./internal/changes
+```
 
-None.
-
-## State Or Manifest Behavior
-
-None directly. The app loads prior module 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 `derived_daily_summary` and
-  `derived_daypart_summaries` stanzas. It also uses `alert_digest` and
-  `precip_timing` when present.
-- 3-Day comparison requires `derived_daypart_summaries`.
-- Weekend comparison requires `derived_daypart_summaries`.
-- Storm Report comparison returns no changes.
-
-## 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.
+Recent Changes always compare structured snapshot values, never report prose.

docs/internal/cli.md

@@ -0,0 +1,65 @@
+# CLI Internals
+
+`internal/cli` turns process arguments into application requests and translates
+application results into terminal output. The user-facing command, flag, and
+output contract belongs in the [CLI reference](../cli.md).
+
+## Responsibilities
+
+`Runner.Run` dispatches the top-level action or inspection request. For actions,
+the package parses command-specific and common flags, loads configuration with
+CLI overrides, obtains the current time, and constructs either an
+`app.GenerateRequest` or an `app.BatchRequest`. It delegates generation and
+batch execution to `internal/app`.
+
+For inspection, it loads configuration, builds the appropriate app inspection
+request, and writes the returned value. Inspection is read-only; the inspected
+artifact types and user invocation remain owned by the [CLI reference](../cli.md)
+and [operations guide](../operations.md).
+
+## Result Translation
+
+Action results become CLI-safe JSON summaries in `result.go`. Generate summaries
+carry report identity, status, relevant artifact paths, and notification
+summary data. Batch summaries carry aggregate counts, per-report outcomes, and
+the optional batch notification result. The translation deliberately excludes
+full module snapshots, prompt packages, raw generated text, Scriptorium output,
+and complete Distributor payloads.
+
+When an action returns both a result and an error, the CLI writes the failed
+summary before returning that error. Parse, configuration-load, and other
+failures that produce no application result return without a summary.
+
+`writeActionResult` writes action status information to stderr first, then JSON
+to stdout. Batch execution supplies the status writer; single-report generation
+does not emit routine stderr output. Quiet action requests suppress both normal
+streams but still return errors. Inspection writes its JSON value to stdout and
+does not accept quiet mode because stdout is the inspection result.
+
+## Boundaries
+
+The package owns argument parsing, request adaptation, help text, and terminal
+presentation. It does not implement report selection, collection, state
+persistence, external transport, subprocess execution, or notification policy.
+Those concerns remain in [application orchestration](app-orchestration.md) and
+their focused owners.
+
+## Failure Behavior
+
+- Invalid command names, flags, dates, and configuration fail before an app
+  request is executed.
+- Application errors retain their application context; output helpers do not
+  hide or replace them.
+- JSON-encoding errors are returned directly.
+- A failed batch summary causes the CLI to return an aggregate batch error even
+  when the detailed batch call has already returned its result.
+
+## Tests And Invariants
+
+Focused tests are in `internal/cli/root_test.go`, `internal/cli/output_test.go`,
+and `internal/cli/result_test.go`.
+
+- CLI summaries are stable, bounded views of app results.
+- Routine batch status lines precede the batch JSON summary.
+- A quiet action produces no successful or failure summary output.
+- Inspection never invokes action-output helpers.

docs/internal/collect.md

@@ -0,0 +1,43 @@
+# Collection Internals
+
+`internal/collect` is the application-facing boundary for collecting the
+normalized Weather API bundle. The external HTTP contract belongs in the
+[Weather API integration guide](../integrations/weatherapi.md); normalized data
+semantics belong in [weather-data internals](weather-data.md).
+
+## Contract
+
+`Run` accepts a `context.Context` and a `Request` containing effective
+`config.Config`. It constructs the Weather API adapter from that configuration,
+calls `FetchBundle`, and returns `Result{Bundle: *weatherdata.Bundle}`.
+
+The package wraps adapter construction failures as weather-collection setup
+errors and fetch failures as bundle-collection errors. It does not retry,
+persist, select reports, derive facts, build modules, invoke Scriptorium, or
+notify Distributor.
+
+## Application Composition
+
+`internal/app` owns the narrow `Collector` interface used by workflow tests;
+the production implementation delegates to `collect.Run`. Generation, batch
+execution, and explicit bundle fetching all use this boundary. Application
+orchestration rejects a nil collector result or a nil bundle before report work
+can continue.
+
+Single-report generation and a batch each collect once. A batch passes the same
+normalized collection to planning and to every report it generates. Collection
+failure prevents later workflow work for that request.
+
+## Boundaries And Invariants
+
+Collection owns adapter creation and retrieval of one normalized bundle. It
+must not make report, period, batch, prompt, module, filesystem, or notification
+decisions.
+
+- App-facing Weather API collection always passes through this package.
+- The returned value is normalized source data, not facts or prompt input.
+- Context cancellation is passed to the Weather API adapter.
+- Errors retain whether setup or fetching failed.
+
+Focused tests are in `internal/collect/collect_test.go`; orchestration use is
+also covered by `internal/app/app_test.go`.

docs/internal/distributor-adapter.md

@@ -1,123 +1,63 @@
 # Distributor Adapter Internals
 
-This document describes the distributor upload adapter in
-`internal/adapters/distributor`.
+`internal/adapters/distributor` translates a local delivery request into the
+Distributor Go client's upload and status calls, then returns a local delivery
+result. The external API, authentication, and idempotency contract is owned by
+the [Distributor API guide](../integrations/distributor/api.md) and
+[Distributor bundle guide](../integrations/distributor/pkg-bundle.md).
 
-## Purpose
+## Client construction
 
-The adapter submits generated weatherreporter Markdown reports to a configured
-distributor HTTP upload endpoint. It isolates distributor package types,
-token-env lookup, upload client construction, source-bundle file mapping,
-timeout handling, status polling, and upload error wrapping from app
-orchestration.
+`Client` holds the endpoint, the name of the environment variable containing
+the token, an optional timeout, and an injectable upstream-client factory.
+`New` validates its configuration before creating the adapter. For each upload,
+the adapter reads the token from the configured environment variable and builds
+the upstream client with that endpoint, token, and an HTTP client whose timeout
+matches the local positive timeout.
 
-## Inputs And Outputs
+The upstream client is an implementation dependency, not a source of
+application configuration: retry ownership, pipeline selection, path
+templates, and report rendering are defined by
+[configuration](../config.md) and [application orchestration](app-orchestration.md).
 
-Inputs:
+## Upload translation
 
-- distributor endpoint URL
-- token environment variable name
-- upload timeout
-- pipeline ID
-- bundle ID
-- idempotency key
-- source Markdown report path and bundle-relative path mappings
-- bundle created timestamp
-- context for cancellation
+Before calling the dependency, `Upload` validates the endpoint and token
+configuration plus the local pipeline ID, bundle ID, idempotency key, and every
+file's source and bundle paths. It maps the request as follows:
 
-Outputs:
+| Local request | Distributor client value |
+| --- | --- |
+| Pipeline ID | Upload pipeline identifier |
+| Bundle ID | Bundle identifier |
+| Idempotency key | Upload idempotency key |
+| File source and bundle paths | Bundle file entries |
+| Creation timestamp | Bundle creation time |
 
-- accepted distributor run ID
-- accepted distributor upload status
-- distributor run status, status polling error, and raw run report JSON when available
-- weatherreporter-owned idempotency conflict error when applicable
+The call inherits the caller's context and applies the configured positive
+timeout. The adapter does not read report files, construct bundle layouts, or
+persist notification artifacts.
 
-## Boundaries
+## Status and errors
 
-`internal/adapters/distributor` is the only weatherreporter package that imports
-`gitea.maximumdirect.net/eric/distributor/pkg/upload` or
-`gitea.maximumdirect.net/eric/distributor/pkg/bundle`.
+An accepted upload is followed by one status request. When a timeout is
+configured, a nonterminal result is polled until `succeeded` or `failed`, or
+until the context ends. The translated `UploadResult` contains the run ID,
+status, and `RunStatus`, including pipeline ID, lifecycle timestamps, report,
+and remote error details.
 
-The app layer passes weatherreporter-owned request values to the adapter. The
-adapter does not choose report types, render templates, select output copies,
-configure destinations, wait for downstream publication, transform Markdown, or
-persist notification state.
+Status lookup or polling errors are preserved in `UploadResult.StatusError` so
+the caller can record an accepted-but-unconfirmed delivery. A terminal failed
+run returns that result and an error. Upload failures return no result. Upstream
+idempotency conflicts become the local `IdempotencyConflictError`, which adds
+endpoint, pipeline, bundle, idempotency, and file-path context while redacting
+the token.
 
-Full upstream distributor package and HTTP contract details stay under
-`docs/integrations/distributor/`.
+## Verification
 
-## Config Fields Used
+Focused tests cover configuration validation, request mapping, timeouts and
+polling, status translation, conflict handling, and token redaction:
 
-The adapter is built from `notify.distributor` config:
-
-- `endpoint`
-- `token_env`
-- `timeout`
-
-The app layer renders pipeline ID, bundle ID, idempotency key, and bundle paths
-from:
-
-- `pipeline_id_template`
-- `bundle_id_template`
-- `idempotency_key_template`
-- `report_path_templates`
-
-The token value is read from the environment variable named by `token_env`
-after config loading and `secrets.directory` processing.
-
-## Upload Behavior
-
-The adapter calls distributor `UploadFiles` with one or more file mappings:
-
-- pipeline ID: the rendered distributor workflow selector
-- source path: the managed Markdown report path selected by app orchestration
-- bundle paths: rendered bundle-relative report paths
-- created: the report generation timestamp
-
-The adapter creates a distributor upload client with the configured endpoint,
-bearer token, and timeout-backed HTTP client. It also wraps the upload context
-with the configured timeout when the timeout is greater than zero.
-
-After upload acceptance, the adapter polls distributor `Status` for the accepted
-run ID until the run reaches `succeeded` or `failed`, or until the configured
-timeout expires. It returns the latest status, error text, and raw report JSON in
-weatherreporter-owned types so app orchestration can persist them in the
-notification debug artifact. Status lookup failures or timeout before a terminal
-state are kept as debug status errors on an otherwise accepted upload. A
-terminal distributor run status of `failed` is returned as a notification failure
-with the status report preserved.
-
-## Failure Behavior
-
-The adapter validates required endpoint, token env name, token value, pipeline
-ID, bundle ID, idempotency key, upload files, source paths, bundle paths, and
-upload client inputs before uploading.
-
-Upload failures include endpoint, pipeline ID, bundle ID, idempotency key,
-source paths, and bundle paths context. Token values are redacted from adapter
-errors.
-
-Distributor idempotency conflicts are exposed as a weatherreporter-owned
-`IdempotencyConflictError`, so callers do not depend on upstream distributor
-types.
-
-## Tests
-
-Inspect:
-
-- `internal/adapters/distributor/client_test.go`
-- `internal/app/app_test.go`
-- `internal/cli/root_test.go`
-
-Adapter tests use a fake upload client factory and do not require a live
-distributor service.
-
-## Invariants
-
-- Distributor package types do not leak outside the adapter.
-- Only the managed Markdown report is uploaded.
-- The adapter never scans the workspace.
-- Token values are not included in errors, CLI output, metadata, docs, or
-  examples.
-- Destination routing and Markdown-to-HTML transformation belong to
-  distributor, not weatherreporter.
+```sh
+go test ./internal/adapters/distributor
+```

docs/internal/facts.md

@@ -1,72 +1,67 @@
 # Fact Contracts Internals
 
-This document describes the fact contract boundary.
+`internal/facts` is the deterministic boundary between a collected weather
+bundle and report-scoped facts. It preserves normalized source values and then
+selects and summarizes the values needed for one resolved report. Provider
+transport and normalized bundle semantics belong to
+[weather-data internals](weather-data.md); report identity and valid-period
+selection belong to [report registry internals](report-registry.md).
 
-## Purpose
+## Collected facts
 
-`internal/facts` separates normalized upstream facts collected for a report run
-from conservative report-scoped facts derived from them. The package gives app
-orchestration one place to build reusable facts before module execution.
+`BuildCollected` projects a `weatherdata.Bundle` into `CollectedFacts`. It
+retains the fetched timestamp and every normalized product: observations,
+current conditions, hourly, narrative, alerts, discussion, daily, weather
+story, and convective outlook data. Source provenance and warnings are copied
+into their own slices so downstream consumers can inspect data completeness
+without treating it as an ordinary weather fact.
 
-## Inputs And Outputs
+A nil bundle produces an empty collected value. Collection itself, missing
+source policy, and source hashes are outside this package.
 
-Inputs:
+## Report-scoped derivation
 
-- `weatherdata.Bundle` from the Weather API adapter
-- resolved report definition and valid period
-- report timezone
-- configured daypart definitions
+`BuildDerived` requires a valid resolved period and a valid report timezone. It
+uses half-open period overlap to select hourly, narrative, daily, and alert
+data; it also derives precipitation timing. Convective outlooks are retained
+only when their valid interval overlaps the report period, with discussions
+kept for represented outlook days. Both collections are sorted deterministically.
 
-Outputs:
+Report identity controls the summary shape:
 
-- `facts.CollectedFacts` with normalized source facts plus separate source
-  provenance and warnings
-- `facts.DerivedFacts` with valid-period forecast slices, alert overlaps,
-  daily summaries, daypart summaries, and Storm Report window summary
+| Report family | Derived summary |
+| --- | --- |
+| Hourly | Rolling-period selections and precipitation timing; no daily or daypart summary |
+| Daily, Today, Tomorrow | One local civil-day summary and its dayparts |
+| Three-day, Weekend | One clipped daily summary for each overlapping local day |
+| Storm | One summary for the explicit report window |
 
-## Boundaries
+`DaypartSummaries` is collected from the resulting daily or storm summaries.
+The detailed grouping, daypart-window, and alert rules are owned by
+[forecast derivation](forecast-derivation.md).
 
-- This package owns fact assembly and reusable deterministic derivation for a
-  report run.
-- It does not fetch upstream data, build prompt wording, compare prior
-  snapshots, write workflow state, invoke Scriptorium, or define modules.
+## Missing data and failures
 
-## Config Fields Used
+Optional normalized products remain nil or yield empty selections; the package
+does not create substitute values. A present convective-outlook run with no
+matching outlooks produces non-nil empty outlook and discussion slices, while
+a missing run produces nil slices.
 
-- `dayparts[].name`
-- `dayparts[].start`
-- `dayparts[].end`
-- `weather_api.timezone`
+Derivation fails for an invalid report period, invalid timezone, unsupported
+report ID, or when a requested daily summary has no hourly forecast data.
+Invalid daypart definitions surface from forecast derivation. The package does
+not access the CLI, filesystem, subprocesses, or network.
 
-## External Adapters Used
+## Verification and invariants
 
-None directly. Collected facts are built from `weatherdata.Bundle`.
+Focused tests cover collected-fact separation, report-period selection,
+hourly and storm behavior, daily and partial-day summaries, and convective
+outlook selection:
 
-## State Or Manifest Behavior
+```sh
+go test ./internal/facts
+```
 
-None. Source provenance and warnings remain data fields for downstream metadata
-and inspection.
-
-## Failure Behavior
-
-- Invalid or missing report valid periods return an error.
-- Invalid timezone names return an error.
-- Missing required hourly forecast data returns the underlying forecast
-  derivation error for reports that require daily summaries.
-- Missing optional narrative, alert, discussion, daily, or weather story data
-  produces empty or nil derived fields.
-
-## Tests
-
-Inspect:
-
-- `internal/facts/facts_test.go`
-- `internal/app/app_test.go`
-
-## Invariants
-
-- Collected facts are built once from a fetched bundle.
-- Derived facts are scoped to one resolved report.
-- Source provenance and warnings stay separate from ordinary fact fields.
-- Prompt-specific wording and one-off presentation decisions stay outside this
-  package.
+Facts are derived once for a resolved report from already collected data.
+They remain reusable structured values: prompt wording, state persistence,
+prior-report comparison, and template presentation are owned elsewhere.

docs/internal/forecast-derivation.md

@@ -1,76 +1,63 @@
 # Forecast Derivation Internals
 
-This document describes deterministic forecast summarization in
-`internal/forecast`.
+`internal/forecast` deterministically selects and summarizes normalized
+forecast data. It has no transport, filesystem, CLI, subprocess, or report
+registry dependency. Its summaries are consumed by
+[fact contracts](facts.md) and later module builders.
 
-## Purpose
+## Period and daypart semantics
 
-`internal/forecast` converts normalized weather data into daily and period
-summaries used by fact builders and module builders.
+Selections use `timeutil.Period` half-open overlap: a value is selected only
+when both intervals share time. `BuildDailySummary` creates one local civil
+day; `BuildPeriodDailySummaries` intersects every local civil day with the
+requested period, preserving partial first and last days.
 
-## Inputs And Outputs
+`ResolveDayparts` converts each configured name, start clock, and end clock
+into a local window. An end clock at or before its start clock wraps into the
+next civil day. The daypart and timezone defaults are defined in the
+[configuration reference](../config.md), not here.
 
-Inputs:
+## Deterministic summaries
 
-- `weatherdata.Bundle`
-- local date or resolved report period
-- timezone
-- configured daypart definitions
+`BuildDailySummary` requires an hourly run with at least one period. It adds
+the selected narrative periods, discussion, alert overlaps, source provenance,
+source warnings, and one `DaypartSummary` per resolved window. A daypart keeps
+its selected hourly periods and derives temperature and apparent-temperature
+ranges, timed precipitation and wind maxima, dominant and notable conditions,
+and weather indicators.
 
-Outputs:
+Indicators are deterministic checks over normalized values and condition text:
+heat, cold, and wind use package-owned numeric cutoffs; snow, ice, fog, and
+wind text are detected from the forecast description. `BuildPrecipTiming`
+sorts periods, records the maximum and first precipitation, groups contiguous
+periods at or above its package-owned probability threshold, and records
+thunder mentions.
 
-- `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
+Alert overlap parsing supports the normalized alert payload's available timing
+fields. Unparseable alerts and invalid intervals are ignored; valid overlaps
+are clipped to the requested period and ordered by alert start time.
 
-## Boundaries
+## Missing data and failures
 
-- 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.
+Empty selections yield empty summary fields rather than generated prose.
+Direct daily or period-summary calls fail when their required bundle, valid
+period, hourly data, or daypart definitions are invalid. A nil location uses
+UTC when these APIs are called directly. Optional narrative, discussion, and
+alerts remain absent when their normalized products are absent.
 
-## Config Fields Used
+Forecast thresholds used for brief indicators and precipitation timing are
+implementation rules. User-configurable Recent Changes thresholds are applied
+by [changes internals](changes.md), whose defaults are documented in
+[configuration](../config.md).
 
-- `dayparts[].name`
-- `dayparts[].start`
-- `dayparts[].end`
+## Verification and invariants
 
-Threshold constants for basic indicators live in forecast code rather than
-configuration.
+Focused tests cover local civil days, clipped periods, daypart resolution,
+summary metrics, precipitation windows, threshold helpers, and alert overlap:
 
-## External Adapters Used
+```sh
+go test ./internal/forecast ./internal/timeutil
+```
 
-None directly. Forecast data arrives through `weatherdata.Bundle`.
-
-## State Or Manifest Behavior
-
-None. Source warnings and provenance from the bundle are carried into summaries
-for later metadata and module 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.
+The package preserves normalized inputs as inspectable structured values and
+never decides report identity, delivery, or presentation wording.

docs/internal/generatedtext.md

@@ -0,0 +1,51 @@
+# Generated Text Internals
+
+`internal/generatedtext` validates the structured prose produced for generated-
+text reports and turns validated prose plus rich module values into typed render
+contexts. It owns the catalog that pairs a generated-text report definition
+with its validator, schema ID, template ID, and context builder. The complete
+maintainer-facing context fields belong to [report templates](../templates.md).
+
+## Catalog and validation
+
+Only the Daily, Today, Tomorrow, and Hourly report definitions use the
+generated-text-template mode. `LookupDefinition` rejects a direct-Markdown
+definition, unknown schema or template IDs, and unsupported schema/template
+pairs before the run begins. A handler validates raw JSON, returns a typed
+value and canonical normalized JSON, loads its schema, builds a render context,
+and renders through `internal/reporttemplate`.
+
+Daily, Today, and Tomorrow use a day-style value with required trimmed summary
+and one or more nonblank discussion paragraphs. Hourly requires trimmed summary
+and a single trimmed discussion string. Each form permits optional trimmed
+precipitation-timing and confidence prose. Typed decoding rejects unknown JSON
+fields; no general-purpose JSON Schema engine is used at runtime.
+
+## Render contexts
+
+The catalog's report-specific builders receive briefing metadata, a rich module
+snapshot, collected facts, derived facts, and the matching validated generated
+text. They decode the module stanzas needed by the template and build typed
+Daily, Today, Tomorrow, or Hourly contexts. Context construction validates
+metadata and periods, preserves rich module values, and uses ordered slices for
+template iteration rather than maps.
+
+Optional source stanzas become nil or fallback context fields. Missing required
+stanzas, type-decoding failures, invalid metadata, or a generated-text type
+that does not match the chosen handler fail before template execution. Prompt
+packages, raw Scriptorium output, state persistence, and template asset lookup
+remain outside this package.
+
+## Verification and invariants
+
+Focused tests cover the catalog, each report-specific validator, normalization,
+schema/template mismatches, context construction, optional modules, and typed
+stanza errors:
+
+```sh
+go test ./internal/generatedtext
+```
+
+Generated text supplies prose slots only; deterministic weather facts remain in
+module and fact values. Every generated-text definition must resolve to exactly
+one supported catalog pair.

docs/internal/module.md

@@ -1,98 +1,68 @@
 # Module Contract Internals
 
-This document describes the module contract in `internal/module`.
+`internal/module` defines the stable envelope between report composition,
+module builders, snapshots, comparisons, templates, and prompt packages. It
+does not define a report, execute a builder, or choose prompt-export policy;
+those responsibilities belong to [report registry](report-registry.md) and
+[briefing](briefing.md).
 
-## Purpose
+## Outputs and snapshots
 
-`internal/module` defines the shared identifiers and data envelopes used for
-prompt-facing modules. Report definitions use module IDs for composition,
-module builders produce outputs with stanza names, prompt input packages consume
-snapshots, and Recent Changes compares snapshot stanzas.
+Each `Output` has a module ID, stanza name, rich `Value`, and runtime-only
+`PromptValue`. `DataPackageValue` returns the prompt value when present and
+otherwise the rich value. This permits custom prompt exports without shrinking
+the template and inspection value.
 
-## Inputs And Outputs
+`NewSnapshot` builds the ordered `weatherreporter.modules.v1` snapshot and
+validates it. Snapshot JSON persists IDs, stanza names, and rich values only;
+`PromptValue` is deliberately excluded. `StanzaValue` decodes a named rich
+stanza into a caller-supplied type, reporting a missing stanza separately from
+a decoding error.
 
-Inputs:
+Snapshots reject missing schema versions, empty IDs or stanza names, and
+duplicate IDs or stanza names. Output order is caller-owned and preserved.
 
-- ordered `module.ConfigItem` values from report definitions or config
-  overrides
-- `module.Output` values produced by module builders
+## Registered IDs and default composition
 
-Outputs:
+The registered IDs are `metadata`, `current_conditions`,
+`narrative_forecast`, `hourly_forecast`, `derived_daily_summary`,
+`derived_daypart_summaries`, `precip_timing`, `alert_digest`,
+`spc_convective_outlooks`, `area_forecast_discussion`,
+`spc_convective_discussion`, `weather_story`, `outdoor_windows`,
+`today_planning`, `tomorrow_planning`, and `daily_planning`.
 
-- stable `module.ID` constants
-- typed option structs for registered modules
-- `module.Snapshot` with schema version `weatherreporter.modules.v1`
-- ordered snapshot outputs with module ID, stanza name, and typed value
-- typed stanza lookup through `module.StanzaValue`
+The registry declares these ordered default compositions:
 
-## Registered Module IDs
+| Report | Ordered modules |
+| --- | --- |
+| Daily | metadata, current conditions, narrative forecast, daily summary, daypart summaries, precipitation timing, alert digest, SPC outlooks, AFD (long term), SPC discussion, weather story, outdoor windows, daily planning, hourly forecast |
+| Today | metadata, current conditions, narrative forecast, daily summary, daypart summaries, precipitation timing, alert digest, SPC outlooks, AFD, SPC discussion, weather story, outdoor windows, hourly forecast, today planning |
+| Tomorrow | metadata, current conditions, narrative forecast, daily summary, daypart summaries, precipitation timing, alert digest, SPC outlooks, AFD, SPC discussion, weather story, outdoor windows, tomorrow planning, hourly forecast |
+| Hourly | metadata, current conditions, hourly forecast, precipitation timing, alert digest, SPC outlooks, AFD (key messages and short term), SPC discussion, weather story |
+| Three-day and Weekend | metadata, current conditions, daypart summaries, precipitation timing, alert digest, SPC outlooks, AFD, SPC discussion, weather story, outdoor windows |
+| Storm | metadata, current conditions, precipitation timing, alert digest, SPC outlooks, AFD, SPC discussion, weather story |
 
-The registry recognizes these IDs:
+The only non-empty default option is the AFD section selection. It accepts a
+`sections` list; omitted or empty selects all available sections. Report
+definitions may narrow it as shown above. Option shape and report compatibility
+are validated by the briefing registry.
 
-- `metadata`
-- `current_conditions`
-- `narrative_forecast`
-- `hourly_forecast`
-- `derived_daily_summary`
-- `derived_daypart_summaries`
-- `precip_timing`
-- `alert_digest`
-- `area_forecast_discussion`
-- `weather_story`
-- `outdoor_windows`
-- `tomorrow_planning`
+## Rich and prompt-facing values
 
-Every registered module has a builder. Report composition entries that refer to
-unknown or unimplemented module IDs fail validation instead of being skipped.
+Rich values remain available to snapshots, comparisons, and render contexts.
+Briefing attaches custom prompt exports only for current conditions, hourly
+forecast, and derived daypart summaries; all other current builders use
+pass-through values. The prompt package owns how exported stanzas are grouped
+and serialized; see [prompt input](prompt-input.md).
 
-## Options
+## Verification and invariants
 
-Most modules use an empty options struct. `area_forecast_discussion` accepts:
+Focused tests cover snapshot validation and order, typed stanza lookup, and
+prompt-value fallback:
 
-```yaml
-sections:
-  - product
-  - key_messages
-  - short_term
-  - long_term
+```sh
+go test ./internal/module
 ```
 
-An omitted or empty `sections` list includes all available discussion sections.
-Invalid option shapes fail during config normalization or composition
-validation.
-
-## Boundaries
-
-- This package owns module identifiers, config item envelopes, output
-  envelopes, snapshot validation, and typed stanza lookup.
-- It does not define report IDs, execute builders, fetch weather data, derive
-  forecast facts, write state, or invoke Scriptorium.
-
-## State Or Manifest Behavior
-
-`module.Snapshot` values are persisted by `internal/state` as JSON. Snapshot
-validation rejects missing schema version, missing module IDs, missing stanza
-names, duplicate module outputs, and duplicate stanza names while preserving
-output order.
-
-## Failure Behavior
-
-- Snapshot construction fails for duplicate module outputs or duplicate stanza
-  names.
-- Typed stanza lookup returns `found=false` for missing stanzas.
-- Typed stanza lookup wraps JSON marshal/decode failures with stanza context.
-
-## Tests
-
-Inspect:
-
-- `internal/module/module_test.go`
-- `internal/briefing/modules_test.go`
-- `internal/report/period_test.go`
-
-## Invariants
-
-- `internal/module` does not import `internal/report`.
-- Module IDs are stable strings.
-- Each emitted module output has exactly one stanza name and one typed value.
-- Snapshot output order is caller-owned and preserved.
+Module IDs and stanza names are stable, every emitted output has one of each,
+and this package never imports the report registry.

docs/internal/prompt-input.md

@@ -1,121 +1,61 @@
 # Prompt Input Internals
 
-This document describes YAML prompt data package construction in
-`internal/promptinput`.
-
-## Purpose
-
 `internal/promptinput` converts report metadata, an ordered module snapshot,
-Recent Changes, and source warnings into the `data_package` file passed to
-Scriptorium.
+Recent Changes, and source warnings into the YAML `data_package` consumed by
+Scriptorium. It owns this package's schema, grouping, serialization, loading,
+and validation—not weather collection, module construction, path choice, or
+subprocess execution.
 
-The persisted data package is YAML with schema version
-`weatherreporter.data_package.v2`. It is separate from the JSON module snapshot
-used for inspection and comparison.
+## Package construction
 
-## Inputs And Outputs
+`Build` produces `weatherreporter.data_package.v3`. It copies the run ID;
+report ID, variant, prompt ID, generation time, timezone, local current date,
+and valid period; ordered briefing stanzas; Recent Changes; and source
+warnings. A nil Recent Changes slice becomes an empty `items` list.
 
-Inputs:
+Briefing starts as a flat snapshot order and stanza-value map. `Build` uses
+each output's `DataPackageValue`, so runtime prompt exports take precedence and
+rich values are used only as a fallback. Prompt exports are selected by the
+[briefing registry](briefing.md), while the rich-versus-prompt contract is in
+[module internals](module.md).
 
-- report metadata from app/state orchestration
-- `module.Snapshot`
-- optional `[]changes.Change`
+## YAML ordering and grouping
 
-Outputs:
+Serialization keeps `metadata` directly under `briefing`. Every other known
+stanza is placed in exactly one category, emitted in category order and in its
+original snapshot order within that category:
 
-- `promptinput.Package` with schema version, RunID, report metadata, named
-  module stanzas grouped for prompt presentation, Recent Changes, and source
-  warnings
-- YAML bytes from `promptinput.MarshalYAML`
-- YAML file written atomically by `promptinput.Save`
+| Category | Current stanzas |
+| --- | --- |
+| `applicable_risk_products` | alert digest, SPC convective outlooks |
+| `derived_summaries` | deterministic summaries, precipitation timing, outdoor windows, and planning values |
+| `narrative_products` | narrative forecast, discussions, and weather story |
+| `raw_data` | current conditions and hourly forecast |
 
-The YAML shape includes:
+This YAML presentation does not alter the flat snapshot model. `LoadYAML`
+accepts the same category layout and reconstructs flat `Order` and `Values`,
+rejecting misplaced, duplicate, unknown, or uncategorized stanzas.
 
-```yaml
-schema_version: weatherreporter.data_package.v2
-run_id: <run_id>
-report:
-  id: <report_id>
-  prompt_id: <prompt_id>
-briefing:
-  metadata: {}
-  applicable_risk_products:
-    alert_digest: {}
-  derived_summaries:
-    derived_daily_summary: {}
-    derived_daypart_summaries: {}
-    precip_timing: {}
-    outdoor_windows: {}
-  narrative_products:
-    narrative_forecast: {}
-    area_forecast_discussion: {}
-    weather_story: {}
-  raw_data:
-    current_conditions: {}
-    hourly_forecast: {}
-recent_changes:
-  items: []
+## Validation and persistence
+
+`Validate` requires the current schema version, run and report identifiers,
+prompt ID, generation timestamp, timezone, current local date, valid period,
+and at least one ordered briefing stanza. It rejects duplicate stanza names,
+missing values, and a missing category for every non-metadata stanza.
+
+`MarshalYAML` and `LoadYAML` validate their result. `Save` writes the serialized
+YAML atomically; managed workspace paths are owned by [state internals](state.md).
+Generated-text artifacts and template render contexts are later workflow
+artifacts, not members of this package.
+
+## Verification and invariants
+
+Focused tests cover construction, curated exports, category ordering, YAML
+round trips, invalid layout, validation, and atomic saves:
+
+```sh
+go test ./internal/promptinput
 ```
 
-The `briefing` mapping keeps `metadata` directly under `briefing` and groups
-weather module stanzas under prompt-facing categories. This grouping is a YAML
-presentation concern only: module snapshots remain flat, and loaded
-`promptinput.Package` values expose flat stanza names in `Briefing.Values`.
-Within each category, stanza order follows the module snapshot output order.
-
-Current categories are:
-
-- `applicable_risk_products`: location-applicable alerts, warnings, outlooks,
-  discussions, and similar risk products.
-- `derived_summaries`: deterministic summaries and calculated report facts.
-- `narrative_products`: official narrative text products and forecast stories.
-- `raw_data`: minimally transformed underlying weather data.
-
-## Boundaries
-
-- This package owns prompt package schema, YAML marshaling, YAML loading, and
-  validation.
-- It does not fetch weather data, derive forecast summaries, execute modules,
-  find prior snapshots, compare changes, choose artifact paths, or invoke
-  Scriptorium.
-
-## Config Fields Used
-
-None directly. Config-derived values such as timezone, units, and prompt
-location are already present in report metadata and module stanzas before this
-package runs.
-
-## External Adapters Used
-
-None.
-
-## State Or Manifest Behavior
-
-`promptinput.Save` writes YAML 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 fields are
-missing or inconsistent, when the valid period is invalid, or when no module
-stanzas are 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 YAML through `--input data_package=<path>`.
-- Module stanza order is deterministic within each prompt-facing category.
-- Every non-metadata module stanza has exactly one prompt-input category.
-- Recent Changes are provided by `internal/changes`; this package does not
-  infer changes from rendered report text.
+The package is narrower than a template render context and never infers changes
+from report prose.

docs/internal/report-registry.md

@@ -1,99 +1,76 @@
 # Report Registry Internals
 
-This document describes report identity, valid-period resolution, batch
-membership, output naming, artifact grouping, and comparison declarations in
-`internal/report`.
+`internal/report` owns the registry of report identities and the data declared
+for each one: resolution, generation mode, prompt identity, comparison policy,
+artifact group, output-copy name, default module composition, and Distributor
+path declarations. The public command syntax is owned by the
+[CLI reference](../cli.md); configuration aliases and overrides are owned by
+the [configuration reference](../config.md).
 
-## Purpose
+## Definitions and resolution
 
-`internal/report` is the canonical source for report definitions. App, state,
-module building, and CLI wiring consume resolved definitions instead of owning
-report identity policy themselves.
+Each `Definition` declares a stable ID and display name, prompt ID, generation
+mode, optional template and generated-text schema IDs, valid-period resolver,
+comparison strategy, artifact group, batch-copy filename, Distributor path
+templates, generation eligibility, compatible prior IDs, default modules, and
+batch eligibility flags. `Resolved` combines that definition with the valid
+period and run metadata for one invocation.
 
-## 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
-- default ordered module composition
-
-## Reports
-
-| Report | ID | Prompt | Artifact group | Batch copy | Prior compatibility |
+| Report ID | Mode | Period policy | Comparison | Registry batch flag | Output copy |
 | --- | --- | --- | --- | --- | --- |
-| 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 |
+| `daily` | Generated text + template | Explicit local civil day | Same valid date | Dynamic Daily inclusion is app-owned | `daily.md` |
+| `today` | Generated text + template | Selected or current local civil day | Same valid date | Morning | `today.md` |
+| `tomorrow` | Generated text + template | Next local civil day | Same valid date | Evening | `tomorrow.md` |
+| `hourly` | Generated text + template | Rolling six-hour interval | Rolling window | — | `hourly.md` |
+| `three_day` | Scriptorium Markdown | Generation time through the third following local midnight | Same valid date | Morning | `three-day.md` |
+| `weekend` | Scriptorium Markdown | Upcoming weekend window | Weekend window | Morning | `weekend.md` |
+| `storm` | Scriptorium Markdown | Caller-supplied event window | Explicit window | — | `storm.md` |
 
-All report definitions are eligible for generation.
+The four generated-text reports pair their report ID with matching template and
+schema IDs. The three direct-Markdown reports leave both IDs empty. Exact
+template fields and schema assets belong to [report templates](../templates.md)
+and [generated-text internals](generatedtext.md).
 
-## Valid Periods
+All valid periods are half-open. Storm accepts local `YYYY-MM-DDTHH:MM` values
+in the effective report timezone or offset-bearing RFC3339 values; its end
+must follow its start. Resolving Weekend directly on Sunday is rejected.
 
-- 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.
+## Registry collaborators
 
-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.
+`DefaultRegistry` is the only source of the seven report definitions.
+`Lookup`, `Resolve`, and report-name helpers prevent callers from duplicating
+report identity rules. Registry overrides clone a definition and replace its
+module list only after the report ID is recognized.
 
-## Boundaries
+The definition's `DistributorPathTemplates` are internal declarations consumed
+by app orchestration. Their rendered external bundle paths and compatibility
+contract are documented in the [Distributor bundle guide](../integrations/distributor/pkg-bundle.md), not repeated here.
 
-`internal/report` defines report metadata and time coverage. It does not fetch
-weather data, build module values, compare snapshot contents, write state,
-parse CLI flags, or invoke Scriptorium.
+`morning` and `evening` are registry-owned batch names. Registry flags declare
+fixed report eligibility; app orchestration determines data-dependent Daily
+membership and produces the actual batch plan.
 
-The CLI owns public command names. The app maps those command names to report
-IDs, then uses the registry for report policy.
+## Module composition and failures
 
-## Config Fields Used
+Each definition supplies an ordered `[]module.ConfigItem`; the complete
+report-to-module mapping is maintained in [module internals](module.md).
+`ArtifactGroup`, `BatchOutputName`, `Generated`, and comparison compatibility
+are likewise consumed by state and orchestration rather than recomputed there.
 
-The app supplies `weather_api.timezone` as a loaded `time.Location`. Batch
-output path copying uses batch output names from report definitions.
+Unknown report IDs or batch names, an invalid weekend resolution, and invalid
+storm windows return errors. The registry never collects weather data, builds
+modules, parses CLI flags, writes state, executes Scriptorium, or delivers a
+report.
 
-## State And App Usage
+## Verification and invariants
 
-- State paths use `ArtifactGroup`.
-- Batch output copies use `BatchOutputName`.
-- Generation checks `Generated`.
-- Module composition defaults use `Modules`.
-- Prior lookup checks `CompatiblePriorIDs` and the comparison strategy.
-- RunIDs include the resolved report ID.
+Focused tests cover definition completeness, command and alias lookup, period
+resolution, run IDs, path declarations, composition defaults, and override
+validation:
 
-## Failure Behavior
+```sh
+go test ./internal/report
+```
 
-- 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,
-  default module composition, comparison compatibility, and comparison strategy
-  are declared by report definition.
+All report selection goes through the registry, and the registry is the source
+of truth for report identity—not rendered report text or app-local constants.

docs/internal/reporttemplate.md

@@ -0,0 +1,51 @@
+# Report Template Internals
+
+`internal/reporttemplate` embeds and renders the repository's native Markdown
+templates and exposes their companion generated-text schemas. The current asset
+IDs are `daily`, `today`, `tomorrow`, and `hourly`. The template files, partials,
+and complete render-context field reference are maintained in
+[report templates](../templates.md).
+
+## Assets and lookup
+
+The package embeds top-level templates, shared partials, and JSON schemas from
+its asset directories. `Template` and `Schema` return the requested embedded
+asset and fail with the requested ID when it is unknown or unreadable.
+
+Generated-text catalog handlers obtain schema bytes and template source through
+these APIs. Prompt source files are repository assets for prompt registration;
+they are not reporttemplate lookup assets. Report definitions select IDs, while
+[generated-text internals](generatedtext.md) verifies the supported
+schema/template pairing.
+
+## Rendering
+
+`Render` loads the top-level template, creates a `text/template` with helper
+functions and `missingkey=error`, parses the template, parses every shared
+partial, and executes the result against the typed render context. This makes
+missing context fields, bad template syntax, unreadable partials, and execution
+failures actionable with template or partial context.
+
+Top-level templates decide which shared partials they invoke. The current
+partials cover daypart forecast variants, alert digest, and precipitation
+timing. Template code receives curated typed contexts rather than raw data
+packages, and it must not reimplement weather selection or generated-text
+validation.
+
+## Boundaries and verification
+
+This package does not collect weather data, build modules, validate generated
+text, construct contexts, resolve report definitions, write state, execute
+Scriptorium, or upload reports. It produces Markdown bytes for application
+orchestration to persist.
+
+Focused tests cover asset lookup, schema availability, rendering, partial
+behavior, missing keys, and malformed context:
+
+```sh
+go test ./internal/reporttemplate
+```
+
+Embedded assets stay as separate files, shared fragments stay under the partial
+directory, and generated-text schemas describe prose slots rather than
+deterministic weather facts.

docs/internal/scriptorium-adapter.md

@@ -1,101 +1,51 @@
 # Scriptorium Adapter Internals
 
-This document describes the subprocess adapter in
-`internal/adapters/scriptorium`.
+`internal/adapters/scriptorium` translates Weatherreporter render requests to
+Scriptorium process arguments and translates process results back to local
+types. The external CLI and output contract belongs to the
+[Scriptorium integration guide](../integrations/scriptorium.md); prompts,
+template inputs, and report ownership remain outside this adapter.
 
-## Purpose
+## Request-to-command translation
 
-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.
+`Runner` accepts a binary, config path, profile, timeout, extra arguments, and
+an injectable command executor. Its defaults are the `scriptorium` binary and
+the real `ExecRunner`. Optional configuration flags are placed before the
+operation-specific arguments, and extra arguments are appended last.
 
-## Inputs And Outputs
+| Local operation | Required values | Translated arguments |
+| --- | --- | --- |
+| `Render` | prompt ID, data-package path | `render [--config …] [--profile …] --prompt <id> --input data_package=<path> --format json [extra …]` |
+| `Run` | prompt ID, data-package path, output path | `run [--config …] [--profile …] --prompt <id> --input data_package=<path> --out <path> [extra …]` |
+| `StructuredRun` | prompt ID, data-package path, output path | Same translation as `Run` |
 
-Inputs:
+Blank required values fail before a command starts. The adapter does not add
+schema flags or interpret a prompt's payload; it only gives Scriptorium the
+named `data_package` input.
 
-- prompt ID
-- YAML prompt input data package path
-- report output path for `run`
-- configured binary, config path, profile, timeout, and extra arguments
-- context for cancellation
+## Command execution and result translation
 
-Outputs:
+`ExecRunner` uses `exec.CommandContext`, never a shell. A positive configured
+timeout creates a child context. Standard output and standard error are
+captured independently, each with a 1 MiB limit, and the executed command is
+retained for diagnostics.
 
-- argv used for execution
-- captured stdout and stderr
-- truncation flags for captured output
-- exit code
-- report output path for `run`
+`RenderResult`, `RunResult`, and `StructuredRunResult` expose the command,
+captured output, truncation markers, and exit code. Run results also retain the
+requested output path. Exit status zero is successful. A nonzero process exit
+returns its result and an error, while a start failure, cancellation, or
+deadline failure returns no result and the execution error.
 
-## Boundaries
+The adapter does not parse rendered JSON, validate a generated report, write
+state, or upload a report. Those responsibilities sit with
+[application orchestration](app-orchestration.md), [state internals](state.md), and the
+relevant delivery adapter.
 
-`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.
+## Verification
 
-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.
+Focused tests cover argument order, validation, bounded capture, timeout and
+cancellation handling, and exit-status translation:
 
-## 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
+```sh
+go test ./internal/adapters/scriptorium
 ```
-
-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`.
-- The file at the data package path is YAML produced by `internal/promptinput`.
-- Render and run preserve command-specific result structs.
-- Scriptorium-specific flags stay inside adapter and config boundaries.

docs/internal/state.md

@@ -1,124 +1,91 @@
 # State Internals
 
-This document describes filesystem state in `internal/state`.
+The `internal/state` package owns filesystem-backed run state: safe path
+derivation, metadata persistence, prior-report lookup, and read-only report
+inspection. It does not decide which reports to generate or deliver. For the
+operator-facing layout and retention procedures, see the
+[operations guide](../operations.md).
 
-## Purpose
+## Store construction and artifact paths
 
-`internal/state` owns managed workspace paths, atomic JSON writes, persisted
-metadata, prior snapshot lookup, and read-only artifact inspection helpers.
+`NewFilesystemStore` requires a workspace root and rejects absolute or
+escaping values for every configured state directory. `Paths` then validates a
+run ID and artifact group before deriving all paths from the report's valid
+start date (`YYYY-MM-DD`). This keeps a run's artifacts together while making
+the paths safe to use below the configured workspace.
 
-## Inputs And Outputs
+| Artifact | Derived location |
+| --- | --- |
+| Module snapshot | `snapshots/<group>/<date>/modules.<run-id>.json` |
+| Metadata | `snapshots/<group>/<date>/metadata.<run-id>.json` |
+| Data package | `data-packages/<group>/<date>/data_package.<run-id>.yaml` |
+| Render preflight | `preflight/<group>/<date>/render.<run-id>.json` |
+| Notification record | `notifications/<group>/<date>/distributor.<run-id>.json` |
+| Managed report | `reports/<group>/<date>/report.<run-id>.md` |
+| Generated text | `snapshots/<group>/<date>/generated_text.<run-id>.json` |
+| Generated-text source and result | `snapshots/<group>/<date>/generated_text_raw.<run-id>.json` and `generated_text_result.<run-id>.json` |
+| Generated-text render context | `snapshots/<group>/<date>/render_context.<run-id>.json` |
 
-Inputs:
+The configured notification root separates notification artifacts from report
+artifacts; single-report notification paths use the report's valid date. Report
+producers create parent directories as needed and write the report body; state
+is responsible for the surrounding paths and saved run artifacts.
 
-- workspace configuration
-- resolved report definition and valid period
-- module snapshot
-- prompt input data package
-- preflight artifact
-- rendered report path preparation request
-- RunID for inspection lookups
+Batch Distributor notifications are derived separately as
+`notifications/batches/<batch>/<local-date>/distributor.<batch-run-id>.json`.
+Their date is calculated from the batch start in its configured location, and
+the batch identity and run ID receive the same path-segment validation as
+single-report artifact identifiers.
 
-Outputs:
+## Metadata and durable writes
 
-- module snapshot JSON path
-- prompt input data package YAML path
-- render preflight JSON path
-- managed Markdown report path
-- metadata JSON path
-- prior comparable snapshot metadata
-- loaded module snapshot or data package
-- recent report records for inspection
+`Metadata` is the durable inventory for a run. It records its schema version,
+run identity, generated and valid timestamps, artifact group and mode, source
+content and provenance, and the module snapshot, data-package, preflight,
+report, generated-artifact, and notification locations when present.
 
-## Boundaries
+`BuildMetadataFromBriefingMetadata` establishes the common fields; the
+application adds locations as artifacts are produced. `SaveMetadata` requires
+the run ID and the module snapshot, data-package, preflight, and metadata
+paths. The package also saves module snapshots, data packages, preflight
+records, generated-text artifacts, render contexts, and notifications. JSON
+writes use `fileutil.WriteJSONAtomic`, so readers do not observe a partially
+written state file.
 
-`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 module contents,
-invoke Scriptorium, import adapter result types, or parse CLI flags.
+The data package itself follows the shared
+[prompt-input contract](prompt-input.md). Report text, templates, and external
+delivery payloads remain owned by their respective packages and integration
+references.
 
-Preflight persistence uses the state-owned `PreflightArtifact` shape. The app
-converts adapter render results into that shape before saving.
+## Prior reports and inspection
 
-## Config Fields Used
+`FindPriorSnapshot` searches metadata rather than guessing from filenames. It
+only considers an earlier compatible report in the same artifact group and
+supports the comparison strategies defined by the report request:
 
-- `workspace.root`
-- `workspace.snapshots_dir`
-- `workspace.reports_dir`
-- `workspace.data_packages_dir`
-- `workspace.preflight_dir`
-- `workspace.notifications_dir`
+- `same_valid_date` finds an earlier generated report for the same valid day.
+- `weekend_window` finds a prior comparable weekend window.
 
-Workspace subdirectories must be relative paths that stay under
-`workspace.root`.
+The newest eligible metadata record wins; the current run is excluded.
+Unreadable or malformed candidate metadata is ignored so a damaged historical
+record does not block a new run.
 
-## Managed Layout
+`ListReports` walks saved metadata, returns results ordered newest-first by
+generation time, and treats a missing snapshots directory as an empty history.
+`LoadMetadataByRunID` builds on that inspection path. These APIs are read-only;
+repairing or pruning stored state is an operational concern.
 
-Paths are derived from the resolved report definition's artifact group, the
-valid-period start date for dated artifacts, and the RunID.
+## Boundaries and verification
 
-```text
-<workspace.root>/
-  snapshots/<artifact_group>/<YYYY-MM-DD>/<run_id>.modules.json
-  snapshots/<artifact_group>/<YYYY-MM-DD>/<run_id>.metadata.json
-  data-packages/<artifact_group>/<YYYY-MM-DD>/<run_id>.data_package.yaml
-  preflight/<artifact_group>/<YYYY-MM-DD>/<run_id>.render.json
-  notifications/<artifact_group>/<YYYY-MM-DD>/<run_id>.distributor.json
-  reports/<artifact_group>/<run_id>.md
+The package rejects unsafe path components and incomplete metadata before
+writing. Callers must provide a valid report request, artifact group, and
+store configuration. Its focused tests cover path derivation, atomic
+persistence, metadata validation, comparison eligibility, and report listing:
+
+```sh
+go test ./internal/state
 ```
 
-Metadata is stored beside module snapshots and links the module snapshot, data
-package, preflight, report paths, notification path when attempted, 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 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.
-Distributor notification debug artifacts are written atomically when
-notification is attempted and include rendered distributor pipeline ID, bundle
-ID, idempotency key, bundle paths, upload status, latest run status, and
-redacted errors.
-
-Inspection helpers read existing metadata, module snapshot, 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.
+See [application orchestration](app-orchestration.md) for the order in which
+these artifacts are created and [report templates](../templates.md) for the
+user-facing report contract.

docs/internal/weather-data.md

@@ -1,88 +1,69 @@
 # Weather Data Internals
 
-This document describes Weather API ingestion into `weatherdata.Bundle`.
+`internal/weatherdata` owns the normalized, wire-independent weather bundle
+that passes from collection through rendering and persistence. The Weather API
+adapter translates provider responses into these types; its request, response,
+and availability contract is documented in the
+[Weather API integration guide](../integrations/weatherapi.md).
 
-## Purpose
+## Bundle contract
 
-`internal/adapters/weatherapi` fetches normalized weather data from one
-configured Weather API endpoint and assembles the bundle consumed by forecast
-derivation and module builders. Module builders expose normalized current
-conditions and weather story context when those sources are available.
+`Bundle` has a collection timestamp (`FetchedAt`), source provenance
+(`Sources`), and collection-level warnings (`Warnings`). Its product fields are
+optional so an allowed missing source can be represented without manufacturing
+weather data.
 
-## Inputs And Outputs
+| Field | Normalized product |
+| --- | --- |
+| `Observation` | Station observation |
+| `Current` | Current conditions |
+| `Hourly` | Hourly forecast periods |
+| `Narrative` | Narrative forecast |
+| `Alerts` | Active-alert check, including an explicitly empty result |
+| `Discussion` | Forecast discussion and its time-range sections |
+| `Daily` | Daily forecast periods when supplied |
+| `WeatherStory` | Latest weather story |
+| `SPCConvectiveOutlooks` | Convective outlook run, discussions, and GeoJSON geometry |
 
-Inputs:
+The bundle carries values rather than provider request details. Consumers use
+it to construct report facts and data packages; they should not infer a
+provider endpoint or retry policy from the normalized types. See
+[collection](collect.md) for assembly and
+[report templates](../templates.md) for the values exposed to authors.
 
-- `config.Config` with Weather API URL, timeout, format, units, timezone,
-  precision, and missing-source policy
-- HTTP responses using the Weather API `data` envelope
+## Source provenance
 
-Outputs:
+Every checked source is represented by a `Source` entry. The record identifies
+the source (`Name`), request location and query (`Endpoint`, `Query`), fetch
+time, provider issue and update times when available, a SHA-256 digest of the
+source data, and whether the source was unavailable (`Missing`). Its warnings
+stay with that source in addition to the bundle-level warning list.
 
-- `weatherdata.Bundle` with observation, current conditions, hourly forecast,
-  narrative forecast, active alerts, discussion, latest weather story, source
-  records, and source warnings
-- optional saved bundle JSON through app fetch helpers
+An empty product can be meaningful checked data. For example, an explicit
+empty alerts result is not missing and retains its source hash. A source is
+marked missing only when the adapter's missing-source policy treats the
+response or parsing failure as unavailable. The policy itself belongs to the
+[configuration reference](../config.md).
 
-## Boundaries
+## Warning semantics
 
-- 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 module values, compare
-  snapshots, write report state, or invoke Scriptorium.
+`SourceWarning` has a source name, stable code, severity, explanatory message,
+endpoint, and `CompletenessImpact`. When collection proceeds with a warning,
+the same warning appears in `Source.Warnings` and `Bundle.Warnings` so both
+local provenance and whole-run consumers see it. A policy that treats a missing
+source as an error returns no partial bundle.
 
-## Config Fields Used
+Warnings describe data completeness, not rendering or delivery failures.
+Those failures are recorded by the application and state layers; see
+[application orchestration](app-orchestration.md) and [state internals](state.md).
 
-- `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`
+## Boundaries and verification
 
-## External Adapters Used
+This package defines data shapes and has no HTTP client, configuration loader,
+filesystem access, or template behavior. Focused tests cover the normalized
+types and the Weather API adapter verifies translation into them:
 
-- 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 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.
+```sh
+go test ./internal/weatherdata
+go test ./internal/adapters/weatherapi
+```

docs/operations.md

@@ -1,257 +1,156 @@
 # Weatherreporter Operations
 
-This guide covers normal operation, generated artifacts, inspection, recovery,
-and operational caveats. For symptom-specific diagnosis, see
+This guide covers normal operation, managed workspace state, inspection,
+recovery, and operational caveats. See the [CLI reference](cli.md) for complete
+command syntax and the [configuration reference](config.md) for fields,
+defaults, and notification templates. For symptom-based diagnosis, see
 [Troubleshooting](troubleshooting.md).
 
-## Normal Workflow
+## Normal Operation
 
-Generation commands:
+After configuring a Weather API endpoint, generate one report:
 
-```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
+```sh
+weatherreporter generate today --out ./today.md
 ```
 
-Each command resolves a report period, fetches a Weather API bundle, builds a
-JSON module snapshot, builds a YAML prompt input data package, runs
-`scriptorium render`, runs `scriptorium run`, and writes managed artifacts under
-the configured workspace.
-When distributor notification is enabled, weatherreporter uploads the managed
-Markdown report after `scriptorium run` succeeds and final metadata is saved.
-`--out PATH` writes an extra Markdown copy for the current generated report; it
-is not used as the distributor upload source.
+A generation collects weather data, resolves the report period, builds and
+persists the module snapshot and prompt data package, runs Scriptorium
+preflight, then produces the managed Markdown report. Daily, Today, Tomorrow,
+and Hourly reports additionally persist generated-text artifacts, validate the
+structured generated text, and render Markdown from the validated text and
+deterministic values.
 
-Batch commands:
+The managed report and its final metadata are saved before single-report
+Distributor notification is attempted. `--out` writes an extra operator copy;
+it never changes the managed report or upload source. A successful generate
+command prints its summary to stdout unless `--quiet` is used.
 
-```text
-weatherreporter run morning
-weatherreporter run evening
+Run a scheduled batch with the same configured collection:
+
+```sh
+weatherreporter run morning --out-dir ./reports
 ```
 
-`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. When notification is configured, the summary and
-status lines include notification status, accepted distributor run ID, or
-notification error fields for each attempted report. `--out-dir PATH` writes
-extra Markdown copies using report default filenames such as `daily.md`,
-`three-day.md`, `weekend.md`, and `tomorrow.md`; these copies are not used as
-distributor upload sources.
+Each batch collects once before it plans reports. Morning runs Today, Tomorrow,
+and every eligible dated Daily Report; evening runs Tomorrow and the same
+eligible Daily Reports. Eligible Daily dates begin after tomorrow and require
+complete hourly coverage for their entire local civil day. A batch continues
+after an individual report fails and returns an aggregate failure when any
+report or batch notification fails.
 
-## Filesystem Layout
+`--out-dir` writes extra copies such as `today.md`, `tomorrow.md`, and
+`daily-YYYY-MM-DD.md`. These copies are never upload sources. Batch report
+copies and notification behavior are summarized in the CLI result; use the
+[CLI reference](cli.md) for its exact JSON and stderr contract.
 
-The default workspace root is `workspace`.
+## Managed Workspace
+
+The default workspace root is `workspace`. Artifact paths use the report
+definition's artifact group, the valid-period start date in the effective
+timezone, and the RunID:
 
 ```text
 workspace/
-  snapshots/
-    daily/
-      YYYY-MM-DD/
-        <run_id>.modules.json
-        <run_id>.metadata.json
-    three-day/
-      YYYY-MM-DD/
-        <run_id>.modules.json
-        <run_id>.metadata.json
-    weekend/
-      YYYY-MM-DD/
-        <run_id>.modules.json
-        <run_id>.metadata.json
-    storm/
-      YYYY-MM-DD/
-        <run_id>.modules.json
-        <run_id>.metadata.json
-  data-packages/
-    daily/
-      YYYY-MM-DD/
-        <run_id>.data_package.yaml
-    three-day/
-      YYYY-MM-DD/
-        <run_id>.data_package.yaml
-    weekend/
-      YYYY-MM-DD/
-        <run_id>.data_package.yaml
-    storm/
-      YYYY-MM-DD/
-        <run_id>.data_package.yaml
-  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
-  notifications/
-    daily/
-      YYYY-MM-DD/
-        <run_id>.distributor.json
-    three-day/
-      YYYY-MM-DD/
-        <run_id>.distributor.json
-    weekend/
-      YYYY-MM-DD/
-        <run_id>.distributor.json
-    storm/
-      YYYY-MM-DD/
-        <run_id>.distributor.json
-  reports/
-    daily/
-      <run_id>.md
-    three-day/
-      <run_id>.md
-    weekend/
-      <run_id>.md
-    storm/
-      <run_id>.md
+  reports/<artifact_group>/<YYYY-MM-DD>/report.<run_id>.md
+
+  snapshots/<artifact_group>/<YYYY-MM-DD>/modules.<run_id>.json
+  snapshots/<artifact_group>/<YYYY-MM-DD>/metadata.<run_id>.json
+  snapshots/<artifact_group>/<YYYY-MM-DD>/generated_text_raw.<run_id>.json
+  snapshots/<artifact_group>/<YYYY-MM-DD>/generated_text_result.<run_id>.json
+  snapshots/<artifact_group>/<YYYY-MM-DD>/generated_text.<run_id>.json
+  snapshots/<artifact_group>/<YYYY-MM-DD>/render_context.<run_id>.json
+
+  data-packages/<artifact_group>/<YYYY-MM-DD>/data_package.<run_id>.yaml
+  preflight/<artifact_group>/<YYYY-MM-DD>/render.<run_id>.json
+
+  notifications/<artifact_group>/<YYYY-MM-DD>/distributor.<run_id>.json
+  notifications/batches/<batch>/<YYYY-MM-DD>/distributor.<batch_run_id>.json
 ```
 
-Managed artifact filenames use the RunID, so repeated runs for the same valid
-period do not overwrite each other.
+The generated-text and render-context artifacts are written only by Daily,
+Today, Tomorrow, and Hourly reports. A report's metadata links the module
+snapshot, data package, preflight artifact, managed report, and any available
+generated-text or single-report notification artifact. Batch notification
+artifacts are separate batch-level records under `notifications/batches`.
 
-## 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
-- module snapshot path
-- prompt input data package path
-- preflight output path
-- managed Markdown report path
-- distributor notification debug artifact path, when notification is attempted
-
-Batch summaries include report status, error text when applicable, notification
-outcome when attempted, valid period, and known artifact paths for each
-attempted report. Notification fields are `notificationStatus`,
-`notificationRunId`, and `notificationError`.
+RunIDs begin with the UTC generation timestamp and report ID. A Daily RunID
+also contains its local valid date so multiple Daily reports in one batch have
+different managed paths. Batch notification RunIDs contain the UTC batch start
+timestamp and batch name.
 
 ## Distributor Notification
 
-Distributor notification is configured with `notify.distributor` and is
-disabled by default. When enabled, weatherreporter uploads the managed Markdown
-report path recorded in the report result and metadata. That single source file
-can be mapped to one or more configured bundle paths. By default, it is mapped
-to one dated report path. Extra copies written by `--out` or `--out-dir` are
-operator conveniences only.
+When `notify.distributor.enabled` is enabled, a successful `generate`
+uploads only the managed Markdown report after final metadata has been saved.
+The extra copy from `--out` is never uploaded. A notification attempt writes
+a redacted debug artifact at
+`notifications/<artifact_group>/<YYYY-MM-DD>/distributor.<run_id>.json`; its
+path is then recorded in report metadata.
 
-The rendered pipeline ID selects the configured distributor `http_upload`
-workflow. The default bundle ID is a stable logical source identity derived from
-producer name, location ID, and report ID:
+Batches suppress per-report notification. When both Distributor and its batch
+notification are enabled, Weatherreporter submits one multi-report upload after
+every planned report succeeds. If any report fails, it records a top-level
+`skipped` notification with reason `one or more reports failed` and does not
+call Distributor. If batch notification is disabled, a batch does not fall back
+to individual uploads.
 
-```text
-weatherreporter.{location_id}.{report_id}
-```
+A batch notification attempt writes
+`notifications/batches/<batch>/<YYYY-MM-DD>/distributor.<batch_run_id>.json`.
+A notification failure makes the batch fail but does not change successful
+individual report items into failed items. The debug artifacts contain rendered
+identifiers, managed source and bundle paths, upload and status results, and
+redacted errors; they do not contain tokens.
 
-The default idempotency key appends RunID to the rendered bundle ID so each
-report generation has a distinct retry identity. The default bundle path uses
-the valid-period start date, artifact group, and RunID. Distributor owns
-destination merge, retention, and derived snapshot behavior such as `latest`.
+## Inspecting Stored Runs
 
-Notification happens after final metadata save. Weather API, module snapshot,
-data-package, render preflight, Scriptorium run, and metadata-save failures do
-not trigger notification. A notification failure fails that report.
-In a batch, other reports continue, the failed report includes notification
-fields in the JSON summary, and the batch returns nonzero.
+Inspection is read-only: it neither collects weather data nor invokes
+Scriptorium or Distributor. Start by finding a RunID:
 
-Each notification attempt writes a debug artifact under `notifications/`. The
-artifact records the rendered pipeline ID, bundle ID, idempotency key, managed
-source path, bundle-relative paths, bundle created timestamp, accepted upload
-response, and the latest distributor run status response when available.
-Weatherreporter polls status until distributor reports `succeeded` or `failed`,
-or until the configured notification timeout expires. The run status includes
-the distributor status, error text, and raw run report JSON, which can show
-actions such as `replace_older`, `skip_same`, `skip_destination_newer`, or
-`failed`. Token values are not written.
-
-Weatherreporter is responsible for selecting the managed Markdown report,
-constructing a source bundle, and submitting it to the configured distributor
-HTTP endpoint. Distributor remains responsible for destination routing,
-publication, and any downstream Markdown-to-HTML transformation. Distributor
-leaves destination files alone when they are not tracked by a newly uploaded
-bundle, so existing uploaded dated report paths can remain available.
-
-## Inspection
-
-Inspection commands read existing workspace artifacts and emit JSON to stdout.
-They do not fetch weather data or run `scriptorium`.
-
-```text
+```sh
 weatherreporter inspect reports --limit 10
 weatherreporter inspect metadata RUN_ID
-weatherreporter inspect modules RUN_ID
-weatherreporter inspect data-package RUN_ID
-weatherreporter inspect prior RUN_ID
-weatherreporter inspect sources RUN_ID
 ```
 
-Use `inspect reports` to find RunIDs and artifact paths. Use
-`inspect metadata` to see the artifact links recorded for a run. Use
-`inspect modules` to review the persisted ordered module snapshot, and
-`inspect data-package` to review the structured prompt package 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.
+| Command | Reads |
+| --- | --- |
+| `inspect reports` | Metadata files under the workspace snapshots tree. |
+| `inspect metadata RUN_ID` | Metadata located by RunID. |
+| `inspect modules RUN_ID` | The module snapshot path recorded in metadata. |
+| `inspect data-package RUN_ID` | The data-package path recorded in metadata. |
+| `inspect prior RUN_ID` | The run metadata, then compatible earlier metadata for its comparison policy. |
+| `inspect sources RUN_ID` | Source provenance and warnings in the run metadata. |
 
-## Recent Changes
-
-Recent Changes are computed from structured module snapshots, not rendered
-Markdown or YAML 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 leaves
-Recent Changes empty.
-
-When no prior comparable snapshot exists, or no configured threshold is crossed,
-`recentChanges.items` is empty.
+A missing snapshots directory produces no listed reports. An unknown or empty
+RunID is an error; use `inspect reports` to obtain a valid value.
 
 ## Recovery
 
-A failed generation run may still leave useful artifacts:
+Keep the workspace when a run fails: artifacts reached before the failure
+remain available where they can be safely persisted.
 
-- 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.
-- If distributor notification fails, report artifacts and final metadata remain
-  available, but the report or batch command returns nonzero.
-- For batch commands, inspect the stdout JSON summary first, then inspect the
-  artifact paths for each failed report.
+- A preflight failure can leave the preflight artifact and metadata.
+- A report-generation failure can leave the managed report, module snapshot,
+  data package, and metadata.
+- A generated-text failure can leave raw text, the structured run result, or a
+  validated generated-text and render-context artifact, depending on where it
+  stopped.
+- A single-report notification failure preserves the report and final metadata,
+  including its notification artifact when it was written.
+- A batch notification failure preserves each report's artifacts and adds the
+  top-level batch notification artifact.
 
-For a bad report, start with:
-
-```text
-weatherreporter inspect metadata RUN_ID
-weatherreporter inspect sources RUN_ID
-weatherreporter inspect modules RUN_ID
-weatherreporter inspect data-package RUN_ID
-weatherreporter inspect prior RUN_ID
-```
+Use the RunID from the action summary with the inspection commands above. For
+a batch failure, inspect the summary first, then inspect the affected report
+RunIDs or the batch notification path. Do not remove the whole workspace as a
+first response; retain it until the failure is understood.
 
 ## 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.
+- Workspace files, generated reports, and Scriptorium stderr can contain
+  sensitive operational context. Set appropriate filesystem permissions and do
+  not publish them unintentionally.
+- Weatherreporter uses one configured Weather API endpoint and local workspace
+  state.
+- It does not provide automatic resume, cleanup, archival, remote state, daemon
+  operation, or automatic storm monitoring.

docs/policy/architecture.md

@@ -1,125 +1,218 @@
-# Architecture
+# Architecture Policy
 
-This document defines the development principles for this Go project. It is inward-facing: developers and LLM coding agents should use it to preserve the project’s shape, boundaries, and invariants as the code evolves.
+## Purpose
 
-## weatherreporter
-`weatherreporter` is a deterministic weather briefing and report-preparation application. It consumes normalized weather data from the internal weatherfeeder-backed API, derives report-specific module snapshots and prompt packages, compares module snapshots against prior runs, and invokes an external prompt runner to produce human-facing reports.
+This policy defines Weatherreporter's system shape, normative ownership,
+dependency direction, architectural invariants, safety properties, and
+non-goals. Developers and coding agents should use it to preserve the
+application's boundaries as the implementation evolves.
 
-The application should keep meteorological data selection, daypart grouping, threshold detection, forecast-period resolution, and recent-change comparison inside Go domain packages. LLM prompts should receive curated module-based prompt packages rather than raw unbounded source payloads wherever practical.
+The [development guide](../development.md) owns the current package inventory
+and contributor workflow. Focused documents under `docs/internal/` own
+implemented subsystem mechanics. This policy owns the rules those packages and
+mechanics must preserve.
 
-Report types must be defined through a registry or equivalent mechanism. Each report definition should declare its report ID, prompt ID, valid-period resolver, module composition, comparison strategy, and output naming behavior. Avoid scattering report-type conditionals across CLI and orchestration code.
+## System Shape
 
-Generated reports must be associated with explicit metadata, including report type, location, generation time, valid period, source product timestamps or hashes, module snapshot path, and output path. Recent Changes must be based on structured snapshot comparison rather than comparison of rendered Markdown report text.
+Weatherreporter is a deterministic weather briefing and report-preparation CLI.
+It consumes normalized weather data, derives report facts and module snapshots,
+builds curated prompt packages, compares structured snapshots with prior runs,
+and invokes Scriptorium either to produce managed Markdown directly or to
+produce bounded generated-text prose for repository-owned templates. It
+persists inspectable artifacts and can upload completed reports through
+Distributor.
 
-`scriptorium` is an external adapter, not domain logic. Subprocess execution must be isolated under `internal/adapters/scriptorium`, use context-aware execution, avoid shell interpolation, capture actionable stderr, and keep scriptorium-specific flags from leaking into domain packages.
+The application is intentionally a small, explicit, dependency-light Go
+program. Add abstraction only when it protects a real boundary, makes an
+important invariant testable, or supports an implemented extension point.
 
-`distributor` is also an external adapter. Upload behavior must be isolated
-under `internal/adapters/distributor`, dependency types from the distributor
-module must not leak outside that adapter, and the selected upload source must
-be the managed Markdown report rather than optional output copies or broad
-workspace scans.
+The primary flow is:
 
-## Project Shape
+1. CLI parsing and configuration resolution;
+2. report or batch resolution;
+3. normalized weather collection;
+4. deterministic fact derivation and module construction;
+5. structured prior-snapshot comparison;
+6. curated prompt input and report-mode-specific Scriptorium processing;
+7. generated-text validation when applicable, managed Markdown production,
+   and metadata persistence; and
+8. optional notification using managed report artifacts.
 
-Default to a small, explicit, dependency-light Go application. Keep the design modular enough to test and change safely, but do not add abstraction unless it protects a real boundary or enables a real extension point.
+Inspection is a separate read-only flow over persisted state. It must not
+collect weather data, invoke Scriptorium, or upload reports.
 
-Business/domain logic should live outside CLI, transport, and external-adapter packages.
+## Ownership And Dependency Direction
+
+### Entry Point And CLI
+
+The binary entry point should do no business work beyond constructing and
+running the CLI. CLI code owns commands, arguments, flags, help, output
+formatting, and conversion into application requests.
+
+CLI packages must not own meteorological decisions, report composition,
+artifact layout, Recent Changes comparison, external transport, or subprocess
+construction.
+
+### Configuration
+
+Configuration loading, built-in defaults, overrides, secret loading, and
+validation belong to `internal/config`. Operational values shared across
+packages must be explicit configuration or constants owned by the responsible
+package, not hidden in CLI or adapter code.
+
+The exact configuration contract belongs in the
+[configuration reference](../config.md). Other architecture documents should
+state ownership and safety rules rather than repeat fields, defaults, or
+precedence.
+
+### Application Orchestration
+
+`internal/app` owns top-level use cases and workflow order. It composes report
+resolution, collection, domain transformations, state, rendering, and optional
+notification through narrow project-owned contracts.
+
+The application layer may coordinate components and convert between their
+contracts. It must not absorb CLI parsing, HTTP transport, subprocess argument
+construction, filesystem layout, weather derivation algorithms, template
+execution, or adapter-specific dependency types.
+
+### Domain And Report Logic
+
+Meteorological selection, forecast-period resolution, daypart grouping,
+threshold detection, fact derivation, report composition, module construction,
+generated-text validation, and Recent Changes comparison belong in deterministic
+Go domain packages.
+
+Domain packages must not depend on CLI parsing, process execution, remote
+transport, or concrete external-library types. Given the same normalized
+inputs, configuration, valid period, prior snapshot, and clock, domain behavior
+should be reproducible.
+
+Report selection must go through the report registry or an equivalent
+centralized mechanism. A report definition owns its identity, prompt and
+rendering mode, valid-period resolver, module composition, comparison strategy,
+artifact grouping, and output naming. Do not scatter report-ID conditionals
+through CLI, orchestration, or adapters.
+
+### External Adapters
+
+External integrations use adapter boundaries under `internal/adapters`.
+Adapters own transport and protocol mechanics; application and domain packages
+own decisions.
+
+- The Weather API adapter owns HTTP request construction, timeouts, retries,
+  response-envelope handling, decoding, and endpoint compatibility.
+- The Scriptorium adapter owns argument construction, context-aware subprocess
+  execution, stdout and stderr capture, exit interpretation, and result
+  decoding. It must avoid shell interpolation.
+- The Distributor adapter owns dependency-specific bundle and upload types,
+  client construction, request execution, status handling, and redaction.
+
+External dependency types must not leak beyond the adapter that integrates
+them. Adapters should expose narrow project-owned inputs and outputs so an
+integration can be tested or replaced without changing domain logic.
+
+### State And Embedded Assets
+
+`internal/state` owns managed workspace paths, durable metadata, atomic
+artifact persistence, prior lookup, and inspection reads. Other packages should
+request state operations rather than reconstruct managed paths independently.
+
+Schemas, prompts, Markdown templates, and partials should live as separate
+repository assets and be embedded by the package that owns their execution or
+lookup. Keep weather derivation and path construction out of templates.
+
+## Architectural Invariants
+
+### Weather Truth And Generated Text
+
+- Normalized source data and deterministic Go derivation are authoritative for
+  weather facts.
+- LLM prompts receive curated module-based packages rather than raw,
+  unbounded source payloads.
+- For generated-text-template reports, generated text is limited to defined
+  prose slots, validated before use, and rendered through typed or otherwise
+  explicit contexts.
+- Direct-Markdown reports receive the same curated prompt-package boundary but
+  produce managed Markdown directly through Scriptorium rather than the
+  generated-text schema and repository-template workflow.
+- Repository-owned templates arrange validated prose and deterministic facts;
+  they do not perform meteorological derivation.
+
+### Reports And Comparison
+
+- Report behavior is resolved through centralized definitions.
+- Recent Changes is computed from structured module snapshots, never by
+  comparing rendered Markdown.
+- Batch workflows collect normalized weather data once and reuse that
+  collection for planning and report generation.
+- Report metadata links identity, generation time, valid period, source
+  provenance, and the managed artifacts produced for the run.
+
+### Managed State And Notification
+
+- Durable structured writes are atomic where practical.
+- Managed paths remain beneath the configured workspace root.
+- Operations that delete, move, overwrite, or copy files use narrow, explicit
+  paths; destructive cleanup is opt-in.
+- Intermediate artifacts reached before a later failure remain inspectable
+  where practical.
+- Distributor uploads use managed Markdown reports, never optional output
+  copies or broad workspace scans.
+- Notification occurs only after the managed report and required metadata have
+  been successfully produced.
+
+### Security, Errors, And Cancellation
+
+- Secrets must not appear in logs, errors, persisted artifacts, examples, or
+  user-facing output.
+- Errors preserve actionable operation, report, RunID, path, endpoint, or
+  subprocess context without exposing secrets or unnecessarily large payloads.
+- External calls, subprocesses, storage operations, and multi-step workflows
+  accept or propagate `context.Context` where cancellation or timeout is
+  meaningful.
+- Adapter failures preserve useful status, stderr, or response context at the
+  boundary and are translated into project-owned errors before crossing into
+  unrelated packages.
 
 ## Dependency Policy
 
-Prefer the Go standard library where practical.
+Prefer the Go standard library. Add an external dependency only when it
+materially improves correctness, security, interoperability, or
+maintainability. A dependency used for a small convenience does not justify its
+lifetime upgrade and compatibility cost.
 
-Use external dependencies only when justified by correctness, security, interoperability, or substantial complexity reduction. Good reasons include complex security-sensitive behavior, such as HTML sanitization, or widely used de facto standards, such as YAML parsing.
+Keep dependency-specific types inside the package that intentionally adopts
+the dependency. The application should remain understandable and testable
+without requiring framework-wide abstractions or live external services.
 
-Avoid dependencies for small conveniences. Do not let external dependency types leak across internal package boundaries unless the dependency is itself the explicit public contract of that package.
+## Verification And Documentation
 
-## Package Layout
+Core behavior must be testable without live Weather API, Scriptorium, or
+Distributor services. The [testing policy](testing.md) owns test philosophy,
+sufficiency, boundaries, and test-double guidance.
 
-Use this layout unless the project has a documented reason to differ:
+Documentation must follow the
+[documentation policy](documentation.md). Update the canonical user,
+operator, integration, internal, and example documentation in the same change
+as the behavior it describes. Future or proposed behavior belongs under
+`docs/roadmap/`; significant durable decisions may be recorded as ADRs.
 
-- `internal/app`: application orchestration and top-level use cases.
-- `internal/cli`: CLI command definitions, flags, argument parsing, and command wiring.
-- `internal/config`: configuration structs, defaults, loading, precedence, and validation.
-- `internal/adapters/<name>`: adapters for external CLIs, APIs, databases, object stores, or libraries.
-- `internal/api`: HTTP API handlers and request/response types, when the application exposes an HTTP API.
-- `internal/transport/http`: HTTP client code, when the application calls HTTP services.
+## Non-Goals
 
-Package-private implementation constants may live near the package that owns them, preferably in `constants.go` when useful.
+Weatherreporter is not:
 
-## Configuration
+- a source weather-data ingestion or normalization service;
+- a general-purpose LLM orchestration framework;
+- an application in which an LLM selects authoritative weather facts or report
+  policy;
+- a plugin framework with dynamically discovered report or module behavior;
+- an HTTP service or multi-user distributed job system;
+- a replacement for Scriptorium or Distributor protocol ownership; or
+- a system that hides operational state exclusively inside opaque logs or
+  remote services.
 
-Centralize configuration loading, processing, precedence, defaults, and validation in `internal/config`.
-
-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`.
-
-Configuration precedence is:
-
-1. CLI flags
-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`.
-
-Configuration files should not contain raw secrets unless the application is explicitly designed for that. Prefer environment variables or secret files for secrets. File-backed secrets are loaded through `secrets.directory`; secret values must not be logged, persisted, or included in user-facing output.
-
-## Adapters and External Integrations
-
-Use a hexagonal architecture style for external integrations.
-
-External adapters belong under `internal/adapters/<name>`. If an adapter uses an external dependency, that dependency’s interface must not leak outside the adapter package. Other packages should interact only with the adapter’s API, so the dependency can be swapped, upgraded, or removed without touching unrelated code.
-
-Adapters should be thin. Domain decisions belong in application/domain packages, not inside adapter glue.
-
-## Components and Registries
-
-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 compose components in an explicit order using a default
-sequence, dependency graph, or documented orchestration rule.
-
-If users can select components, validators, renderers, or adapters, selection
-should go through a registry or equivalent mechanism rather than scattered
-conditionals.
-
-## Embedded Assets
-
-Store embedded JSON schemas, Markdown prompts, templates, and similar assets as separate files, not inline string literals, unless there is a strong reason otherwise.
-
-## Errors and Logging
-
-Errors should be actionable and preserve context. Wrap errors with operation and path/resource context. CLI code should convert internal errors into concise user-facing messages.
-
-Errors and logs must not expose secrets.
-
-Use structured logging where practical. Logs should describe operations, paths, external calls, retries, and failure causes, but should not include large user data by default.
-
-## Context, Timeouts, and Cancellation
-
-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 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.
-
-## Testing
-
-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. 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 component
-contracts, update the relevant docs and examples in the same change.
+New requirements may justify revisiting a non-goal. A change that alters system
+shape, dependency direction, a safety property, or another architectural
+invariant should be recorded deliberately in this policy or an ADR rather than
+introduced implicitly.

docs/policy/development.md

@@ -1,204 +0,0 @@
-# Development Policy
-
-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`.
-
-## Repository Layout
-
-- `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/distributor`: Distributor upload adapter.
-- `internal/adapters/weatherapi`: Weather API HTTP adapter.
-- `internal/adapters/scriptorium`: Scriptorium subprocess adapter.
-- `internal/weatherdata`: normalized weather source facts, source metadata, and
-  source warnings.
-- `internal/forecast`: deterministic forecast derivation.
-- `internal/facts`: collected and derived report fact contracts.
-- `internal/module`: module IDs, config items, output envelopes, and snapshots.
-- `internal/report`: report definitions, valid periods, batches, output names,
-  and comparison declarations.
-- `internal/briefing`: prompt-facing module value builders and module registry.
-- `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.
-
-## Local Validation
-
-Use focused checks while editing and broader checks before committing:
-
-```bash
-go test ./...
-go run ./cmd/weatherreporter --help
-git diff --check
-```
-
-Useful focused checks:
-
-```bash
-go test ./internal/cli ./internal/config
-go test ./internal/app ./internal/state
-go test ./internal/adapters/distributor ./internal/adapters/weatherapi ./internal/adapters/scriptorium
-go test ./internal/forecast ./internal/report ./internal/briefing ./internal/changes ./internal/promptinput
-```
-
-Run `gofmt -w` on changed Go files before committing.
-
-## Coding Conventions
-
-- 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 distributor package types and upload-client construction inside
-  `internal/adapters/distributor`.
-- Keep Weather API transport and envelope handling inside
-  `internal/adapters/weatherapi`.
-
-## Dependency Policy
-
-Prefer the Go standard library. Add dependencies only when they materially
-improve correctness, interoperability, security, or maintainability.
-
-Current external dependencies:
-
-- `gitea.maximumdirect.net/eric/distributor` for distributor source bundle
-  construction and HTTP upload client behavior.
-- `gopkg.in/yaml.v3` for YAML configuration parsing.
-
-When adding a dependency:
-
-- 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.
-
-## Configuration Changes
-
-Configuration is owned by `internal/config`.
-
-When adding or changing a field:
-
-- 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.
-
-Configuration precedence is:
-
-1. CLI overrides supported by `config.LoadOptions`;
-2. configuration file values;
-3. built-in defaults.
-
-The default config path is `/usr/local/etc/weatherreporter/config.yml`.
-
-## CLI Changes
-
-The CLI is owned by `internal/cli`.
-
-When adding or changing a command or flag:
-
-- 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.
-
-CLI commands should return concise actionable errors and avoid printing partial
-JSON when command construction fails.
-
-## Components And Adapters
-
-Use existing package boundaries before adding a package.
-
-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/`.
-
-Adapters should stay thin:
-
-- 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.
-
-When an external contract changes, update the matching file under
-`docs/integrations/`.
-
-## Tests
-
-Core tests must not require live Weather API, Scriptorium, or distributor
-services.
-
-Preferred test patterns:
-
-- fake command runners for subprocess behavior;
-- `httptest.Server` for Weather API behavior;
-- fake distributor upload clients for notification 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.
-
-Add focused tests near the package that owns the behavior. Use app-level tests
-for workflow ordering, persistence, and cross-package contracts.
-
-## Examples
-
-Examples under `examples/` must be real, maintained, and free of secrets.
-
-When updating examples:
-
-- 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`.
-
-Do not add generated report examples unless they can be kept current without
-live external services.
-
-## Documentation Checklist
-
-Documentation updates are part of behavior changes.
-
-Update:
-
-- `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, Scriptorium, or distributor
-  contract changes;
-- `docs/roadmap/` only for unimplemented or deferred work.
-
-Non-roadmap docs must describe implemented behavior only.

docs/policy/documentation.md

@@ -1,356 +1,207 @@
-# Go Project Documentation Policy
+# Documentation Policy
 
 ## Purpose
 
-Project documentation must help four audiences:
-
-1. users who need to run the application;
-2. administrators/operators who need to configure and operate it;
-3. developers who need to understand and change it safely;
-4. LLM coding agents that need clear scope, boundaries, and invariants.
-
-Docs should be accurate, concise, task-oriented, and organized by audience. Prefer links to canonical docs over repetition.
+This policy assigns each Weatherreporter documentation topic to one canonical
+owner. Its goal is to keep documentation accurate, concise, discoverable, and
+resistant to drift for users, operators, developers, integrators, maintainers,
+and coding agents.
 
 ## Core Rules
 
-### 1. Keep docs concise
-
-Each document should cover a defined scope and only the essentials for that scope.
-
-Avoid:
-- long background explanations;
-- repeated reference material;
-- implementation detail in user-facing docs;
-- aspirational language outside roadmap docs;
-- verbose examples where one minimal example is clearer.
-
-### 2. Document only implemented behavior outside roadmap files
-
-Unimplemented, planned, aspirational, experimental, or future work may be described only under:
-
-- `docs/roadmap/`
-
-No other documentation file, including `README.md`, should describe code, features, modules, stages, commands, config fields, or behaviors that do not currently exist.
-
-If a feature is partial, non-roadmap docs may describe only the implemented portion and its current boundary.
-
-### 3. Use canonical homes
-
-Each type of information should have one canonical location.
-
-Canonical homes:
-
-- project purpose and quickstart: `README.md`
-- development principles: `docs/policy/architecture.md`
-- configuration reference: `docs/config.md`
-- CLI reference: `docs/cli.md`
-- operations and recovery: `docs/operations.md`
-- troubleshooting: `docs/troubleshooting.md`
-- implemented internals: `docs/internal/`
-- future work: `docs/roadmap/`
-- contributor workflow: `docs/policy/development.md`
-- copyable examples: `examples/`
-
-Other files should summarize briefly and link to the canonical source.
-
-### 4. Keep examples real
-
-Examples should be valid, maintained, and free of secrets.
-
-Where practical:
-- example configs should load successfully;
-- example commands should match real CLI syntax;
-- important examples should be covered by tests.
-
-## Documentation Profiles
-
-All projects require:
-
-- `README.md`
-- `docs/policy/architecture.md`
-
-Additional docs depend on the project.
-
-### Small library
-
-Recommended:
-- `docs/policy/development.md`, if contributor conventions are non-obvious
-
-### Simple CLI
-
-Required:
-- `docs/cli.md`
-
-Recommended:
-- `docs/policy/development.md`
-
-### Config-driven CLI
-
-Required:
-- `docs/cli.md`
-- `docs/config.md`
-
-Recommended:
-- `examples/`
-- `docs/policy/development.md`
-
-### Stateful or operator-facing application
-
-Required:
-- `docs/cli.md`, if CLI-based
-- `docs/config.md`, if config-driven
-- `docs/operations.md`
-
-Recommended:
-- `docs/troubleshooting.md`
-- `examples/`
-- `docs/policy/development.md`
-
-### Modular, staged, service-oriented, or orchestration application
-
-Required:
-- `docs/cli.md`, if CLI-based
-- `docs/config.md`, if config-driven
-- `docs/operations.md`
-- `docs/internal/`
-- `docs/policy/development.md`
-
-Recommended:
-- `docs/troubleshooting.md`
-- validated examples under `examples/`
-
-## Required Documents
-
-### README.md
-
-**Audience:** users, administrators, operators
-
-The README is the outward-facing project orientation page.
-
-It should include, in order:
-
-1. concise description;
-2. elevator pitch;
-3. shortest useful command or usage example;
-4. links to targeted docs.
-
-The README should be short. It is not a manual.
-
-The “shortest useful command” means the simplest command that performs the project’s core use case. (It does not mean `app --help`.)
-
-### docs/policy/architecture.md
-
-**Audience:** developers, LLM coding agents
-
-`docs/policy/architecture.md` is required for every project.
-
-It is an inward-facing development policy document. It should describe how the project is intended to be built and changed.
-
-It should include:
-
-- project shape;
-- core design principles;
-- package and boundary philosophy;
-- state/persistence philosophy, if applicable;
-- external integration philosophy, if applicable;
-- error-handling and logging principles;
-- testing expectations;
-- documentation expectations;
-- architectural invariants;
-- explicit non-goals, if useful.
-
-For small projects, this file may be brief. It may simply state that the project is intentionally narrow, monolithic, and dependency-light.
-
-### docs/policy/development.md
-
-**Audience:** developers, LLM coding agents
-
-Required for projects maintained by humans and LLM coding agents.
-
-It should include:
-
-- repository layout;
-- build/test commands;
-- coding conventions;
-- dependency policy;
-- how to add config fields;
-- how to add CLI flags;
-- how to add stages/modules/adapters, if applicable;
-- how to update examples;
-- documentation update expectations.
-
-### docs/config.md
-
-**Audience:** administrators, operators, advanced users
-
-Required for applications with configuration files.
-
-It should include, in order:
-
-1. config file locations and discovery precedence;
-2. minimal working config;
-3. production-oriented config;
-4. full configuration reference;
-5. secrets handling, if applicable;
-6. links to maintained examples.
-
-The full configuration reference should be canonical.
-
-### docs/cli.md
-
-**Audience:** users, administrators, operators
-
-Required for CLI applications.
-
-It should include, in order:
-
-1. shortest useful command;
-2. command overview;
-3. complete flag reference;
-4. common workflows;
-5. diagnostic or recovery commands, if applicable.
-
-Explain when commands are useful, not just their syntax.
-
-### docs/operations.md
-
-**Audience:** administrators, operators
-
-Required for applications that maintain state, support resume behavior, run multiple stages, write durable artifacts, use remote storage, or require recovery procedures.
-
-It should cover:
-
-- normal workflow;
-- filesystem layout;
-- remote storage layout, if applicable;
-- logs and manifests;
-- resume/retry behavior;
-- cleanup behavior;
-- archive/backup behavior;
-- safe recovery procedures;
-- operational caveats.
-
-### docs/troubleshooting.md
-
-**Audience:** administrators, operators
-
-Recommended once recurring failure modes exist.
-
-Each entry should include:
-
-- symptom;
-- likely cause;
-- diagnostic command or inspection step;
-- safe fix;
-- relevant links.
-
-### docs/internal/
-
-**Audience:** developers, LLM coding agents
-
-Required for modular, staged, service-oriented, or orchestration projects.
-
-This directory describes implemented internal components. It is not the roadmap.
-
-Use one file per major component where useful.
-
-Each component doc should include:
-
-1. purpose;
-2. inputs and outputs;
-3. boundaries;
-4. config fields used;
-5. external adapters used;
-6. state or manifest behavior, if applicable;
-7. skip/resume behavior, if applicable;
-8. failure behavior;
-9. tests to inspect before changing;
-10. architectural invariants.
-
-### docs/roadmap/
-
-**Audience:** maintainers, developers, LLM coding agents
-
-This is the only place for planned, future, aspirational, experimental, or unimplemented work.
-
-Roadmap docs should clearly distinguish:
-
-- proposed work;
-- accepted plans;
-- deferred ideas;
-- rejected ideas;
-- implementation prompts or task breakdowns, if useful.
-
-Roadmap docs should not be confused with current behavior.
-
-### docs/integrations/
-
-**Audience:** developers, LLM coding agents
-
-Required for projects that depend on external CLIs, APIs, services, protocols, or file formats where the integration contract is important to maintain.
-
-This directory contains concise, versioned reference notes for external integration contracts. It should document only the parts of the external system that this project actually uses.
-
-Use one file per integration where useful.
-
-## Examples Directory
-
-Projects with non-trivial configuration or workflows should include `examples/`.
-
-Useful examples include:
-
-- minimal working config;
-- production-oriented config;
-- full annotated config;
-- local development config;
-- remote/object-storage config;
-- minimal session/input file.
-
-Examples should be valid, maintained, tested when practical, and linked from relevant docs.
-
-## Security and Privacy
-
-Docs and examples must not include:
-
-- real API keys;
-- tokens;
-- passwords;
-- private keys;
-- private environment dumps;
-- sensitive user data;
-- raw private transcripts;
-- private infrastructure details unless intentionally public.
-
-Document secret-handling mechanisms, not actual secret values.
-
-## Maintenance Rules
-
-When docs change, verify the affected behavior.
-
-Where practical:
-
-- load example config files in tests;
-- test CLI examples or command parser behavior;
-- validate documented flags against real flags;
-- remove stale references;
-- update links after renames;
-- keep roadmap content out of non-roadmap docs.
-
-If documentation and code disagree, fix the documentation and/or open a roadmap item; do not leave aspirational behavior in current-behavior docs.
-
-Documentation is complete only when it matches the current code.
-
-## Documentation Change Checklist
-
-Before merging documentation changes, verify:
-
-- README is concise and orientation-focused.
-- `docs/policy/architecture.md` describes development principles.
-- Future work appears only under `docs/roadmap/`.
-- User-facing docs avoid unnecessary internals.
-- Developer-facing docs preserve boundaries and invariants.
-- Config examples match the schema.
-- CLI examples match real commands and flags.
-- Defaults appear in the canonical config reference.
-- No secrets or private data are included.
-- Links are accurate.
+### One Canonical Documentation Owner
+
+Each authoritative fact belongs in one canonical document or documentation
+area. A non-owning document may give a short, stable summary for orientation,
+but it must link to the canonical owner instead of maintaining a second
+definition.
+
+Volatile details include commands, flags, configuration fields and defaults,
+report and module IDs, schemas, file names, paths, status and exit behavior,
+retry behavior, and runtime guarantees. If readers could reasonably treat a
+statement as a contract, its exact documentation belongs with the owner named
+in this policy.
+
+Executable sources of truth and documentation owners serve different purposes.
+Code, schemas, and embedded assets determine runtime behavior. The canonical
+document owns the corresponding explanation or reference for readers. Both may
+necessarily express the same contract, but other documentation should summarize
+and link rather than create another complete reference. When implementation and
+documentation disagree, verify the intended behavior and update them together.
+
+### Current State, Decisions, And Future Work
+
+Outside `docs/roadmap/`, documentation describes implemented behavior only.
+Partial features may be described only to their implemented boundary.
+
+An accepted architecture decision may describe an approved direction before it
+is implemented, but acceptance is not evidence that the behavior exists.
+Current-state documents change when the implementation lands. Temporary
+roadmaps own future work, sequencing, and implementation status; they do not
+replace durable policies, decisions, or current contracts.
+
+### Audience And Detail
+
+Write for the document's stated audience and include only the detail needed for
+its owned topic. User and operator documentation should not expose incidental
+implementation detail. Developer documentation should link to user-facing and
+external contracts instead of restating them.
+
+### Links
+
+Use descriptive link text and repository-relative links for repository
+documents. Link to the canonical owner rather than to a duplicate summary.
+Check every added or changed link, and repair or remove links when their target
+moves or is retired.
+
+### Examples And Code Fences
+
+Complete copyable files belong in `examples/` when maintained examples exist.
+Documentation may use the smallest illustrative snippet needed for its owned
+topic, but should link to a maintained example instead of embedding a second
+complete copy.
+
+Examples must be valid, secret-free, and tested where practical. Commands,
+flags, configuration, imports, and Go snippets must match implemented behavior.
+Use a language tag on fenced code blocks, and identify fragments that are
+illustrative rather than directly runnable.
+
+### Security And Privacy
+
+Documentation and examples must not contain real credentials, private keys,
+private environment dumps, sensitive source material, or private
+infrastructure details unless intentionally public. Document secret-handling
+mechanisms, not secret values.
+
+## Canonical Ownership
+
+| Topic | Canonical owner | Owned content | Content owned elsewhere |
+| --- | --- | --- | --- |
+| Product orientation and minimal quickstart | `README.md` | What Weatherreporter is, why it is useful, one shortest successful invocation, and links onward. | Complete command reference, configuration reference, operational procedures, architecture, and implementation detail. |
+| Contributor workflow and package inventory | `docs/development.md` | Repository layout, local workflow, validation commands, coding conventions, task-specific change guidance, dependency workflow, and repository hygiene. | Architectural invariants, user-facing contracts, detailed subsystem behavior, and future work. |
+| Current application architecture | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, package boundaries, invariants, safety properties, and non-goals. | Concrete implementation mechanics, contributor procedures, decision history, and future work. |
+| Documentation organization | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and document lifecycle. | Application architecture and runtime behavior. |
+| Testing policy | `docs/policy/testing.md` | Test philosophy, risk-based sufficiency, stable test boundaries, doubles, coverage guidance, regression policy, and criteria for adding, rewriting, or deleting tests. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. |
+| CLI contract | `docs/cli.md` | Commands, arguments, flags, invocation semantics, stdout and stderr behavior, summaries, and exit behavior. | Configuration field definitions, complete operating procedures, runtime filesystem layout, and command implementation. |
+| Configuration contract | `docs/config.md` | Discovery and precedence, fields, defaults, secrets, validation rules, and user-selectable values. | Complete example files, CLI syntax, runtime state lifecycle, and loading implementation. |
+| Operations | `docs/operations.md` | Normal workflows, physical workspace layout, artifacts and metadata, inspection, notification behavior, recovery, cleanup, permissions, and operational caveats. | Complete CLI syntax, configuration field definitions, logical external contracts, and implementation mechanics. |
+| Troubleshooting | `docs/troubleshooting.md` | Recurring symptoms, likely causes, diagnostic steps, safe fixes, and links to normal-operation references. | Complete command and configuration references, routine operating procedures, and implementation detail. |
+| Report template surface | `docs/templates.md` | Implemented template files and partials, render-context fields, editing rules, and maintainer-facing template examples. | Weather derivation, module implementation, generated-text validation internals, and operator procedures. |
+| External and durable integration contracts | `docs/integrations/` | Weather API, Scriptorium, Distributor, external formats and protocols, durable logical paths and schemas, compatibility behavior, and upstream or downstream responsibilities. | Physical runtime placement and lifecycle, internal transformations, CLI syntax, and configuration defaults. |
+| Internal subsystem behavior | `docs/internal/` | Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, user-facing contracts, external schemas, operator procedures, and future package plans. |
+| Architectural decision history | `docs/adr/`, when repository-local decisions require records | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, and task sequencing. |
+| Temporary feature roadmaps | `docs/roadmap/`, while planned work needs coordination | Proposed, accepted, deferred, or rejected work; sequencing; gates; implementation status; and task breakdowns. | Implemented behavior reference and durable decision rationale. |
+| Complete copyable artifacts | `examples/` | Maintained configuration and other files intended to be copied or run. | Field-by-field reference, command reference, and prose explanation. |
+
+Conditional owners do not require placeholder files or directories. If
+Weatherreporter introduces a new public API, consumer interface, release
+process, or other durable documentation responsibility, update this policy to
+assign its canonical owner when that responsibility is introduced.
+
+## Boundary Rules
+
+### Orientation, Architecture, And Internals
+
+The README owns product orientation. The development policy routes contributors
+and owns the concise current package inventory. Architecture owns normative
+structure and invariants. Focused internal documents own implementation
+behavior. These documents may link to one another but must not maintain
+parallel package or behavior references.
+
+### Commands, Configuration, Operations, And Troubleshooting
+
+CLI documentation answers how to invoke Weatherreporter and what its command
+interface does. Configuration documentation answers what settings mean.
+Operations answers what happens to runtime state and how to operate or recover
+the application. Troubleshooting starts from a symptom and leads to diagnosis
+and a safe fix.
+
+When a workflow crosses these topics, place the complete procedure with the
+document that owns the task and link to the other contracts. Do not duplicate
+complete flag, field, or path references to make a workflow self-contained.
+
+### Templates, Integrations, And Implementation
+
+Template documentation defines the maintainer-facing rendering surface.
+Integration documentation defines externally observable shapes, logical paths,
+protocols, and compatibility behavior. Internal documentation explains how
+Weatherreporter produces, transforms, or consumes those contracts.
+
+Internal documents may name a command, field, template value, path, or protocol
+to identify a dependency, but must link to its canonical documentation for the
+complete definition.
+
+### Executable Authority
+
+CLI parsing and help generation are the executable authority for accepted
+commands and flags. Configuration structs, defaults, loading, and validation
+are the executable authority for configuration behavior. Schemas and embedded
+assets are the executable authority for validated formats and template
+execution. Tests protect selected contracts and invariants but do not become a
+second documentation reference merely by asserting them.
+
+Canonical documentation must be checked against these authorities whenever the
+corresponding behavior changes.
+
+### Security Topics
+
+This policy owns what documentation and examples may contain. Architecture owns
+application security boundaries and invariants. Configuration owns
+credential-supply mechanisms. Operations owns permissions and handling of
+sensitive runtime artifacts. Integration documents own consumer-visible
+security contracts. Internal documents own implementation mechanisms only.
+
+## Architecture Decision Records
+
+Use sequentially numbered ADR filenames such as
+`0001-record-architecture-decisions.md`. Follow the lightweight Nygard format:
+
+1. title;
+2. status;
+3. date;
+4. context;
+5. decision;
+6. alternatives considered;
+7. consequences.
+
+Use one of these statuses:
+
+- **Proposed:** the decision is under consideration and may change;
+- **Accepted:** the decision is approved, whether or not implementation is
+  complete;
+- **Rejected:** the proposed decision was considered and not adopted;
+- **Superseded:** a later accepted ADR replaces the accepted decision.
+
+A proposed ADR transitions to Accepted or Rejected. An Accepted ADR transitions
+to Superseded only when a later Accepted ADR replaces it. An ADR may be created
+as Accepted when the decision has already been made.
+
+Treat the decision content of an Accepted ADR as immutable. A changed decision
+requires a later ADR rather than a rewrite of the accepted record. A Superseded
+ADR must link to its replacement, and the replacement must link back. Rejected
+architectural alternatives belong in the ADR; rejected feature ideas belong in
+a roadmap when they need to be retained.
+
+## Document Lifecycle
+
+Create durable current-state documentation with the implementation it
+describes. Update its canonical owner in the same change when behavior changes.
+If ownership moves, remove the old definition and leave a link where navigation
+remains useful.
+
+Roadmaps are temporary coordination documents. When their work is complete,
+record completion, move any still-useful decisions or contracts to their
+durable owners, update incoming links, and archive or remove the roadmap
+according to repository practice. Do not preserve completed roadmaps as a
+second current-state reference.
+
+Before completing documentation work:
+
+- verify affected behavior and examples;
+- check commands, flags, fields, defaults, schemas, paths, and identifiers
+  against their implementation;
+- keep unimplemented behavior in a roadmap, subject to the ADR exception;
+- validate links and fenced examples;
+- confirm non-owning documents summarize and link rather than redefine;
+- remove stale or unsupported claims; and
+- confirm that no secrets or sensitive private data were added.

docs/policy/testing.md

@@ -0,0 +1,337 @@
+# Testing Policy
+
+## Purpose
+
+Our tests exist to make **incorrect changes expensive and correct changes
+cheap**.
+
+We do not optimize for test count, line coverage, exhaustive isolation, or the
+fewest possible tests. We optimize for sufficient confidence in important
+behavior while imposing as little unnecessary friction as possible on future
+development.
+
+## Every Test Has A Cost
+
+Every test has an immediate cost and a continuing lifetime cost. It must be
+written, reviewed, executed, understood, diagnosed when it fails, updated when
+legitimate behavior changes, and maintained as fixtures and dependencies
+evolve.
+
+Tests also create cognitive and architectural friction. They can constrain
+refactoring, duplicate policy, slow feedback, add noise to failures, and cause
+harmless implementation changes to require unrelated suite edits.
+
+A test is warranted when the confidence it provides justifies those costs.
+Apply that judgment at two levels:
+
+1. **Per test:** What realistic defect does this test detect, how consequential
+   would it be, and is that protection worth the test's lifetime cost?
+2. **Across the suite:** Does this collection provide materially more
+   confidence than a smaller, simpler suite would?
+
+Prefer a lean suite that provides sufficient confidence in the risks that
+matter without redundant or low-value tests. Some friction is intentional:
+tests should make dangerous changes, such as corrupting state, breaking
+compatibility, violating security boundaries, or reintroducing subtle defects,
+require deliberate review. They should not make ordinary internal changes
+needlessly expensive.
+
+Maintenance cost is not a reason to omit testing by default. When omitting a
+plausible test, be able to explain why the protected failure is low-risk,
+already covered, obvious, reversible, or cheaper to detect elsewhere. Favor
+testing when failure would be consequential, subtle, or difficult to observe.
+
+## Default Testing Style
+
+Use a classical or Detroit-style approach:
+
+- Test observable behavior, resulting state, contracts, and invariants.
+- Use real internal collaborators when they are fast and deterministic.
+- Use fakes, stubs, or mocks primarily at expensive, nondeterministic,
+  destructive, or external boundaries.
+- Prefer package-level behavioral tests over tests coupled to private helpers
+  or internal call sequences.
+- Test exact collaborator interactions only when the interaction itself is a
+  requirement.
+
+Weatherreporter's important seams include clocks, subprocesses, HTTP services,
+Distributor uploads, filesystem roots, environment-backed secrets, and any
+future source of randomness or nondeterminism.
+
+## Execution Requirements
+
+The [development guide](../development.md) owns baseline repository validation.
+The default test suite is:
+
+```sh
+go test ./...
+```
+
+Run race-enabled tests when a change affects concurrent execution, goroutine
+lifecycle, shared mutable state, or cancellation coordination. Use a focused
+package command while iterating and `go test -race ./...` when the risk crosses
+package boundaries.
+
+Tests in the default suite must be deterministic, offline, and independent of
+real credentials. They must not invoke live Weather API, Scriptorium, or
+Distributor services or depend on other mutable external infrastructure.
+Tests that require live infrastructure must be explicitly opt-in and clearly
+separated from the default suite.
+
+Control clocks, environment variables, filesystem roots, and machine-specific
+state when they affect behavior. Tests must be safe to repeat and must not
+depend on execution order or state left by an earlier test. Tests that modify
+process-global state may remain serial; use `t.Parallel()` only when the test
+and its collaborators are actually safe to run concurrently.
+
+## Test Types And Assets
+
+Use each test type where it protects a distinct risk:
+
+- Unit and package tests protect focused domain behavior and invariants through
+  the narrowest stable boundary.
+- Contract tests protect CLI behavior, configuration, durable artifacts,
+  schemas, templates, integration formats, compatibility, and stable error
+  identity.
+- Integration tests use real deterministic collaborators when correctness
+  depends on their interaction, while replacing live or nondeterministic
+  external boundaries.
+- App and CLI tests protect representative assembled generation, batch,
+  inspection, persistence, and notification workflows.
+- Fixtures must be minimal, synthetic, versioned with the behavior they
+  exercise, and free of credentials or private data.
+- Golden files are appropriate only when the complete output is intentionally
+  stable and semantic review of updates is practical.
+- Failure-path tests should cover consequential malformed input, dependency
+  failure, cancellation, partial results, and recovery behavior.
+
+## What Deserves Tests
+
+Prioritize tests for:
+
+1. CLI, configuration, artifact, template, integration, and package contracts.
+2. Meteorological domain rules and important invariants.
+3. Boundary conditions and malformed input.
+4. Failure handling, cancellation, retries, recovery, and partial success.
+5. Serialization, schemas, compatibility, and round trips.
+6. Previously observed or plausible regressions.
+7. Representative app and CLI workflows.
+
+A package-level contract is behavior relied upon by another package or major
+collaborator, not every observable implementation detail.
+
+For data integrity, destructive operations, compatibility, security,
+concurrency, idempotency, or recovery, presume that durable tests are required
+unless the behavior is already credibly protected at another layer.
+
+Do not add tests merely because a function, branch, or line exists. Do not add
+a test when the same meaningful risk is already adequately protected
+elsewhere.
+
+## Choose The Right Boundary
+
+Test through the narrowest stable boundary that expresses the behavior clearly.
+That may be:
+
+- a small pure function when dense domain logic is clearest there;
+- a package operation when several internal collaborators jointly produce the
+  behavior; or
+- a larger integration or app boundary when correctness emerges from
+  interaction.
+
+Do not force every behavior through oversized workflow tests. Do not test every
+private helper merely because it exists. Choose the boundary that provides
+durable confidence with the least incidental coupling.
+
+## Test Behavior, Not Implementation
+
+A test should protect a decision, contract, or invariant, not memorialize the
+current implementation. Before adding or retaining a test, ask:
+
+> What realistic defect would this test catch?
+
+A test is suspect when its main purpose is to detect that someone changed a
+private constant, renamed or split a helper, reordered equivalent operations,
+changed incidental formatting, replaced one correct algorithm with another, or
+refactored private structure without changing behavior.
+
+Refactoring should normally require no test edits unless the changed structure
+is itself contractual. A test can be factually correct and still have negative
+value when the behavior it protects is too incidental to justify its future
+cost.
+
+Use these expectations when evaluating failures:
+
+| Change | Expected effect on tests |
+| --- | --- |
+| Internal refactor that preserves behavior | Existing tests should normally remain unchanged and pass. |
+| Internal default change with no contractual significance | Tests should normally derive expectations from configuration or relationships rather than duplicate the old value. |
+| Intentional change to user-visible behavior, policy, schema, or compatibility | Relevant tests should be reviewed and changed deliberately. |
+| Accidental contract or invariant violation | Tests should fail; fix production code rather than rewriting tests to accept the defect. |
+
+A failing test is not necessarily a test that should be edited. Many tests may
+correctly fail because of one production defect. The maintenance smell is a
+correct internal change that requires unrelated expectation changes throughout
+the suite.
+
+## Separate Mechanism From Policy
+
+Do not duplicate configurable thresholds and defaults throughout the suite.
+Test mechanisms relationally: a configured valid value is accepted, a value
+outside the permitted relationship is rejected, and runtime behavior respects
+the configured value.
+
+Test an exact default when its literal value is itself a documented user,
+operational, safety, protocol, or compatibility contract. The same distinction
+applies to timeouts, capacities, retry counts, ranges, thresholds, and output
+limits.
+
+When concurrency limits are introduced, distinguish configuration enforcement
+from runtime enforcement. Validate accepted and rejected settings separately
+from measuring whether observed peak concurrency respects the configured
+limit.
+
+## Avoid Semantic Duplication
+
+Each behavior should have a clear test owner:
+
+- CLI parser tests own arguments, flags, and command construction.
+- Config tests own loading, precedence, defaults, secrets, and validation.
+- Domain tests own weather transformations and invariants.
+- Adapter tests own HTTP, subprocess, and upload boundaries.
+- Orchestrator tests own workflow ordering, persistence, partial success, and
+  failure propagation.
+- State tests own path derivation, atomic artifacts, lookup, and round trips.
+- Template and generated-text tests own schemas, render contexts, and rendered
+  output contracts.
+
+Higher-level tests should not repeat every lower-level case. Tests that are
+individually reasonable may still be collectively redundant; assess the
+marginal protection of each additional test.
+
+## Use Test Doubles Deliberately
+
+Choose the least elaborate double that provides the required control or
+observation:
+
+1. Prefer real collaborators when they are fast and deterministic.
+2. Use small in-memory fakes when realistic stateful behavior helps.
+3. Use stubs when a dependency only needs controlled responses.
+4. Use mocks when the interaction itself is contractual.
+
+Mocks are appropriate for requirements such as uploading exactly once, saving
+metadata before notification, propagating cancellation to Scriptorium, or
+avoiding an external call after an earlier workflow failure. Do not use mocks
+merely to isolate every object or reproduce the implementation's call graph.
+
+## Go-Specific Guidance
+
+Use:
+
+- table-driven tests for meaningful behavioral categories and boundaries;
+- `t.TempDir()` for real filesystem behavior;
+- `httptest.Server` for realistic Weather API interactions;
+- test-controlled clocks for periods and RunIDs;
+- fake command runners for Scriptorium behavior;
+- fake upload clients for Distributor behavior;
+- fuzz tests when parsers, normalization, or path handling have a broad and
+  consequential input space;
+- golden files only when complete output stability is intentional; and
+- a small number of representative app and CLI workflow tests.
+
+Avoid exact error-string assertions unless wording is contractual. Prefer
+`errors.Is`, `errors.As`, typed errors, structured fields, or the smallest
+stable semantic fragment that identifies the failure. At CLI boundaries,
+prefer structured summaries, exit behavior, and stable classifications over
+snapshots of complete diagnostic wording.
+
+Golden-file updates must require an explicit local flag. Ordinary validation
+must never update golden files automatically, and maintainers must inspect the
+semantic diff before accepting an update.
+
+Keep tests readable and direct. Helpers and fixture frameworks must earn their
+maintenance cost; do not build elaborate infrastructure for small or isolated
+needs.
+
+## Coverage
+
+Coverage is a diagnostic, not a target. Use it to find untested critical
+branches and unexpectedly weak packages. Do not write low-value tests solely
+to increase a percentage or infer quality from coverage alone.
+
+Pure domain logic will often warrant higher coverage than CLI wiring or thin
+external adapters. Uneven coverage is acceptable when it reflects risk.
+
+## Regression Tests
+
+A bug fix should normally include a regression test that fails before the fix
+and passes afterward. Prefer the narrowest durable test of the violated
+contract or invariant.
+
+Retain the test when the defect could realistically recur and its consequences
+justify the ongoing cost. Remove or consolidate it if the design makes
+recurrence implausible or a stronger invariant test subsumes it.
+
+## Deleting Or Rewriting Tests
+
+Tests are maintained code, not permanent historical artifacts. Delete or
+rewrite a test when its maintenance cost exceeds the confidence it provides.
+Candidates include tests that:
+
+- require edits after harmless internal changes;
+- assert private constants without protecting a real contract;
+- duplicate the same policy across several layers;
+- verify mock choreography rather than outcomes;
+- snapshot large amounts of incidental output;
+- protect risks already covered more effectively elsewhere; or
+- are flaky, misleading, obsolete, or no longer correspond to a plausible
+  failure.
+
+Test removal must be deliberate and within the scope of the change. Identify
+the behavior the test protected and show that the behavior is covered more
+effectively elsewhere or that the failure is no longer plausible enough to
+justify durable coverage. Replace several brittle tests with one stronger
+behavior or invariant test when appropriate.
+
+Do not delete or weaken a test merely because it fails after a production
+change. First determine whether the failure exposes an accidental regression,
+an intentional contract change, or an implementation-coupled assertion.
+
+## Reviewing A Proposed Test
+
+When a proposed test's value or durability is not self-evident, ask:
+
+1. What realistic defect would it catch, and how consequential is that defect?
+2. Is the behavior already protected elsewhere?
+3. Which layer should own the test?
+4. Does it assert a durable contract or incidental implementation detail?
+5. What should cause it to fail, and what legitimate changes should not?
+6. Could a smaller or more direct test protect the same risk?
+7. What ongoing maintenance, execution, and diagnostic cost will it impose?
+
+Written answers are not required for every routine test. Do not add a test when
+its expected lifetime cost exceeds its expected protective value.
+
+## Definition Of Sufficient
+
+A suite is sufficient when:
+
+- important contracts and invariants are protected;
+- meaningful boundaries and failure modes are exercised;
+- consequential regressions are credibly protected against silent recurrence;
+- data integrity, destructive operations, compatibility, security,
+  concurrency, idempotency, and recovery receive risk-appropriate protection;
+- external boundaries have realistic local integration coverage;
+- representative complete workflows are tested;
+- failures provide useful signal rather than redundant noise; and
+- legitimate internal changes usually do not require test edits.
+
+Sufficiency is a risk judgment, not a coverage percentage or test count.
+Reassess it as Weatherreporter, its users, and the consequences of failure
+evolve.
+
+The governing rule is:
+
+> Test heavily where failure is consequential, subtle, or difficult to detect
+> after the fact. Test lightly where failure is obvious, reversible, and
+> inexpensive.

docs/roadmap/future.md

@@ -1,22 +1,23 @@
 # Future Roadmap
 
-This roadmap contains project work that is not implemented. Current behavior is
-documented outside `docs/roadmap/`.
+This roadmap contains future work only. Each section identifies its planning
+status; current behavior is documented outside `docs/roadmap/`.
 
 ## Automatic Storm Monitoring
 
-Manual Storm Report generation is implemented through
-`weatherreporter generate storm --start TIME --end TIME`. Automatic storm-event
-evaluation remains deferred.
+Status: Proposed and unimplemented.
 
-Proposed direction:
+Manual Storm Report generation is implemented; see the [CLI reference](../cli.md).
+Automatic storm-event evaluation remains unimplemented.
 
-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 direction:
+
+1. Detect candidate storm events 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:
 
@@ -27,121 +28,116 @@ Possible lifecycle states:
 - `deescalating`
 - `resolved`
 
-Acceptance criteria before implementation:
+Before implementation, the design must preserve scheduled report behavior,
+manual Storm Report generation, inspectable evaluator failures, and fixture
+coverage for deterministic candidate detection.
 
-- 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.
+## Future Report Types
 
-## Future Report Types And Modules
-
-The module-based prompt package architecture is implemented. Future work should
-add only modules backed by implemented upstream facts and clear report needs.
+Status: Proposed and unimplemented.
 
 Possible future report types:
 
-- `next_6_hours` or another short-fuse planning report;
-- event-specific reports with stable event IDs;
-- storm review or yesterday-style reports using historical observations;
+- a short-fuse planning report distinct from the implemented Hourly Report, if
+  a separate product is needed
+- event-specific reports with stable event IDs
+- storm review or yesterday-style reports using historical observations
 - archive-focused report variants if generated report history becomes a
-  first-class product.
+  first-class product
+
+New reports should preserve the boundaries documented in the [report registry
+internals](../internal/report-registry.md).
+
+## Future Modules
+
+Status: Proposed and unimplemented.
 
 Possible future modules:
 
-- `hourly_table` for compact valid-period hourly facts;
+- `hourly_table` for compact valid-period hourly facts
 - `forecast_delta` if a separate stanza is useful beyond current Recent
-  Changes;
+  Changes
 - `weekend_planning` if weekend-specific planning guidance needs a dedicated
-  deterministic stanza;
+  deterministic stanza
 - `storm_window_summary` if manual or automatic Storm Reports need a dedicated
-  prompt-facing storm-window module;
+  prompt-facing storm-window module
 - separate AFD section aliases, such as `afd_key_messages`,
   `afd_short_term_text`, and `afd_long_term_text`, if separate stanzas prove
-  more useful than `area_forecast_discussion.options.sections`;
+  more useful than `area_forecast_discussion.options.sections`
 - SPC, radar, QPF, snow/rain total, or historical-observation modules once
-  upstream sources and report requirements exist.
+  upstream sources and report requirements exist
 
 QPF fields such as `measurable_qpf_total_in` and `max_hourly_qpf_in` should
 remain omitted until a real upstream quantitative precipitation source is
 represented in `CollectedFacts`.
 
-Future module work should preserve these boundaries:
+Future module work should preserve the boundaries documented in [fact
+contracts](../internal/facts.md), [module internals](../internal/module.md), and
+[briefing internals](../internal/briefing.md):
 
-- collect upstream facts once per report run;
-- keep upstream fetching out of modules;
-- keep broad reusable calculations in `DerivedFacts`;
-- keep prompt-facing field shape inside module builders;
-- use typed options for configurable module behavior;
-- keep module snapshots structured and deterministic for Recent Changes.
+- keep upstream collection in app orchestration
+- keep upstream collection out of modules
+- keep broad reusable calculations in `DerivedFacts`
+- keep prompt-facing field shape inside module builders
+- use typed options for configurable module behavior
+- keep module snapshots structured and deterministic for Recent Changes
 
 ## Distributor Notification Enhancements
 
-Distributor notification currently uploads one managed Markdown report per
-successful generated report through the configured HTTP upload pipeline.
+Status: Proposed and unimplemented.
 
-These enhancements are not current behavior:
+Single-report and batch Distributor notification are implemented. Current
+behavior is documented in the [Distributor adapter guide](../internal/distributor-adapter.md),
+[Distributor integration guides](../integrations/distributor/), and
+[operations guide](../operations.md). The following enhancements remain
+unimplemented:
 
-- `failure_policy: warn`;
-- uploading metadata, module snapshots, data packages, or preflight artifacts;
-- polling distributor status after upload acceptance;
-- durable upload retry queues;
-- distributor-specific CLI flags;
-- making distributor scan the weatherreporter workspace;
-- handling destination routing, Markdown-to-HTML transformation, public URLs,
-  or nginx layout inside weatherreporter.
+- `failure_policy: warn`
+- uploading metadata, module snapshots, data packages, or preflight artifacts
+- durable upload retry queues
+- distributor-specific CLI flags
+- distributor workspace scanning
+- destination routing, Markdown-to-HTML transformation, public URLs, or nginx
+  layout inside weatherreporter
 
-Any distributor enhancement should preserve the existing adapter boundary:
+Any distributor enhancement should preserve the adapter boundary:
 weatherreporter selects explicit generated files and submits source bundles,
 while distributor owns destination routing and publication behavior.
 
 ## Alternate Runtime Integrations
 
-These ideas are not current behavior:
+Status: Proposed and unimplemented.
 
-- native LLM client inside `weatherreporter`;
-- database-backed state;
-- public HTTP API;
-- multi-location selection;
-- daemon mode;
-- multi-user authorization;
-- plugin system;
-- dynamic module loading;
-- user-defined module code;
-- YAML-defined module schemas;
-- module-owned Weather API fetching.
+These ideas remain unimplemented:
+
+- native LLM client inside `weatherreporter`
+- database-backed state
+- public HTTP API
+- multi-location selection
+- daemon mode
+- multi-user authorization
+- plugin system
+- dynamic module loading
+- user-defined module code
+- YAML-defined module schemas
+- module-owned Weather API fetching
 
 Each item needs its own design note before implementation. Non-roadmap docs
 must not describe these as available behavior.
 
-## Cleanup Refactors
+## Deferred Refactors
 
-The initial cleanup pass intentionally left these refactors out because the
-current implementation does not yet make them worth the added abstraction.
+Status: Deferred.
 
-Revisit these only when new source types, report types, operational
-requirements, or recurring maintenance costs make the duplication materially
-more expensive:
+These refactors should remain deferred until new requirements or recurring
+maintenance costs make the added abstraction worthwhile:
 
-- 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 module
-  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.
-- 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.
+- broad briefing weather-signal consolidation
+- generic workflow engine
+- Cobra migration
+- manifest, resume, or progress system
+- global test helper package
+- logging subsystem
 
 Any future implementation should preserve the existing public CLI, artifact
 paths, report identities, module boundaries, and adapter boundaries unless a

docs/roadmap/promptkit.md

@@ -0,0 +1,327 @@
+# Promptkit Migration Roadmap
+
+Status: Accepted migration policy; the migration itself is unimplemented.
+
+## Purpose
+
+This roadmap defines the scope and desired end state for replacing the
+external Scriptorium CLI integration with the Promptkit Go library. The
+migration is not yet implemented. Current Scriptorium behavior remains
+documented in the [Scriptorium integration guide](../integrations/scriptorium.md)
+until the replacement is complete.
+
+A separate staged implementation plan will describe how to move from the
+current code to this target state. That plan should reference this roadmap
+rather than redefine its architectural decisions or scope.
+
+## Desired End State
+
+Status: Accepted target state; unimplemented.
+
+Weatherreporter uses a pinned released version of
+`gitea.maximumdirect.net/eric/promptkit` as its in-process prompt preparation
+and LLM execution engine. The `scriptorium` executable, subprocess adapter,
+configuration, runtime dependency, and integration documentation have been
+removed.
+
+The migration does not change weatherreporter's fundamental product behavior.
+Weather selection, forecast derivation, report periods, module construction,
+Recent Changes, generated-text interpretation, Markdown templates, durable
+state, inspection, output copies, and distributor notification remain owned by
+weatherreporter.
+
+All report prompts and private response schemas are versioned application
+assets. Operators may configure Promptkit execution profiles without replacing
+the report-owned prompt and schema corpus. One Promptkit engine is constructed
+per CLI invocation and shared by every report in that invocation, including
+all reports in a morning or evening batch.
+
+Promptkit is isolated behind a weatherreporter-owned prompt execution contract.
+Promptkit request, result, validation, error, profile, backend, and provider
+types do not leak into application orchestration, report definitions, domain
+packages, CLI summaries, state contracts, or distributor behavior.
+
+## Goals
+
+Status: Accepted migration scope; unimplemented.
+
+- Remove the runtime dependency on the `scriptorium` executable.
+- Replace shell-free subprocess orchestration with typed in-process Promptkit
+  preparation and execution.
+- Preserve the seven report definitions and their existing prompt IDs.
+- Preserve both direct-Markdown and generated-text-template report workflows.
+- Preserve deterministic module snapshots and structured Recent Changes.
+- Preserve context cancellation, actionable errors, secret redaction, and
+  inspectable failures.
+- Improve durable prompt provenance with prompt, input, profile, model,
+  validation, usage, and timing metadata.
+- Keep content-rich prompt and response diagnostics separate from routine
+  metadata and CLI output.
+- Keep tests offline and deterministic through injected Promptkit model
+  clients and fixtures.
+
+## Non-Goals
+
+Status: Accepted migration scope; unimplemented.
+
+The migration will not:
+
+- move meteorological selection, derivation, thresholds, or comparison logic
+  into prompts or Promptkit;
+- send raw unbounded Weather API responses to the model;
+- replace weatherreporter's generated-text domain validation or Markdown
+  template rendering;
+- add a general workflow engine, provider plugin system, or arbitrary backend
+  registry to weatherreporter;
+- add automatic provider, validation, or capacity retries;
+- add concurrent report generation to the existing sequential batch workflow;
+- expose Promptkit types as a weatherreporter component contract;
+- keep a production-selectable Scriptorium/Promptkit dual-run mode; or
+- use an unpublished Promptkit commit, committed Go workspace, or committed
+  local module replacement.
+
+## Locked Decisions
+
+Status: Accepted decisions for the unimplemented migration.
+
+### Dependency And Versioning
+
+- The initial integration will pin Promptkit `v0.3.0`.
+- Coordinated local development may temporarily use the sibling Promptkit
+  checkout, but committed module metadata must reference the tagged release.
+- A future Promptkit upgrade requires an explicit review of the public engine,
+  prompt/profile/schema formats, error identities, validation behavior, and
+  outbound provider contract used by weatherreporter.
+
+### Application Boundary
+
+- Promptkit remains an adapter boundary even though it runs in process.
+- A weatherreporter-owned contract will represent preparation, execution,
+  output formats, validation, usage, provenance, and neutral error categories.
+- The Promptkit adapter will map public Promptkit values into that contract at
+  the boundary.
+- App orchestration and test fakes will depend on the weatherreporter contract,
+  not on Promptkit.
+- Existing Scriptorium-specific generation mode names will be replaced with
+  provider-neutral names.
+
+### Prompt And Schema Ownership
+
+- Weatherreporter will embed all report prompt definitions, prompt content,
+  and private response schemas.
+- Prompt assets will remain separate files rather than inline Go strings.
+- The current Scriptorium prompt corpus will be retrieved before the
+  implementation stage that establishes the embedded Promptkit assets.
+- The retrieved corpus will be reviewed and converted to the pinned Promptkit
+  format without changing report intent or prompt IDs.
+- The four existing generated-text prompt fragments and schemas under
+  `internal/reporttemplate` will be reconciled with that corpus rather than
+  duplicated.
+- Direct-Markdown prompt assets for the three-day, weekend, and storm reports
+  will become weatherreporter-owned assets.
+- Weatherreporter needs one centralized embedded prompt/schema source; it does
+  not need Notarius's multi-module asset-flattening registry.
+
+### Profiles, Backends, And Credentials
+
+- Execution profiles remain operator-configurable rather than embedded report
+  policy.
+- Configuration will support at most one external profile source: a profile
+  directory or a single profile file.
+- Prompt definitions may provide their normal default profile, while
+  weatherreporter may support an explicit configured profile selection.
+- Credential values remain in environment variables or file-backed
+  environment secrets. Configuration contains only credential source names.
+- Provider credentials must not appear in logs, errors, CLI output, durable
+  metadata, preparation artifacts, execution artifacts, or debug summaries.
+- Weatherreporter will not expose Promptkit's general backend registry as
+  arbitrary application configuration.
+
+### Engine Lifetime
+
+- One Promptkit engine will be constructed per CLI invocation at the
+  application composition boundary.
+- Single-report generation will use that engine for preparation and execution.
+- Morning and evening batches will share the same engine across every planned
+  report.
+- Per-report orchestration will not construct its own default Promptkit engine.
+- Promptkit backend capacity state and HTTP transport will therefore be shared
+  consistently for the invocation.
+
+### Prompt Input
+
+- Promptkit will continue to receive the curated `data_package` produced by
+  `internal/promptinput`.
+- Weatherreporter will serialize the data package once, atomically persist
+  those exact bytes, and supply the same bytes as a Promptkit inline artifact.
+- The managed data-package path may be supplied as non-secret artifact
+  provenance.
+- Weatherreporter will not delegate unrestricted path loading to Promptkit's
+  default file artifact reader.
+- The same immutable Promptkit request will be used for preparation and
+  execution so the preflight and run inputs cannot diverge.
+
+### Preparation And Execution
+
+- Promptkit `Prepare` replaces the current Scriptorium render preflight.
+- Promptkit `Run` performs both Markdown and structured generated-text
+  execution.
+- Promptkit basic validation will be used where appropriate for direct
+  Markdown output.
+- Promptkit JSON Schema validation provides the provider-facing and first
+  structured-output check for generated-text reports.
+- Weatherreporter's `internal/generatedtext` validation remains the final
+  report-specific domain boundary.
+- Weatherreporter's `internal/reporttemplate` remains responsible for
+  generated-text Markdown rendering.
+- Weatherreporter will atomically persist Promptkit output rather than asking
+  the dependency to write managed report files.
+- The migration will not rely on Promptkit output repair. Promptkit v0.3.0's
+  public engine validates in a single pass even when a prompt declares repair
+  attempts.
+
+## Durable Artifacts And Observability
+
+Status: Accepted design constraints; unimplemented.
+
+Routine durable artifacts should retain useful non-secret provenance without
+persisting full rendered prompts by default.
+
+The preparation record should contain:
+
+- prompt ID and version;
+- prompt definition hash;
+- rendered prompt hash;
+- input hashes;
+- selected profile and backend identity;
+- effective model identity;
+- output contract summary; and
+- preparation timing.
+
+The execution record and run metadata should contain, when available:
+
+- Promptkit run ID;
+- prompt ID, version, and hashes;
+- input hashes;
+- selected profile, backend, and model identity;
+- generated-content hash;
+- token usage;
+- start, end, and duration;
+- validation status and bounded diagnostics; and
+- the path of any separately persisted raw generated output.
+
+Provider endpoints, full effective model parameter maps, rendered messages,
+schema bodies, data-package contents, and generated content do not belong in
+routine metadata or CLI summaries.
+
+Rendered messages and other content-rich preparation or response diagnostics
+will be available only through an explicitly enabled debug mechanism. Debug
+artifacts must be documented as potentially sensitive, must not contain
+credentials, and must have a clear operator-owned retention policy.
+
+## Failure Contract
+
+Status: Accepted design constraints; unimplemented.
+
+Promptkit returns a completed `RunResult` for output-validation failure but no
+partial result for operational preparation or execution errors. Weatherreporter
+will preserve that distinction.
+
+- A preparation failure produces a redacted weatherreporter-owned failure
+  receipt with report, RunID, prompt, stage, timing, and classified error
+  context. It does not fabricate a Promptkit preparation result.
+- An operational execution failure retains the successful preparation record
+  and adds a redacted execution failure receipt. No partial Promptkit result or
+  model output is invented.
+- A Promptkit validation failure retains the returned result, raw generated
+  output, validation details, and safe provenance before the report fails.
+- A later weatherreporter generated-text decode, domain-validation, or template
+  failure retains every raw and validated artifact reached before that stage.
+- Context cancellation takes precedence when the caller context is canceled.
+- Promptkit capacity rejection maps to a weatherreporter-owned error category.
+  It is an operational report failure, not invalid model output.
+- Single-report commands return the classified failure with available
+  inspectable paths.
+- Batch runs continue independent later reports under the existing batch
+  failure policy.
+- The migration adds no automatic retries. Any future retry policy belongs to
+  app orchestration, not the Promptkit adapter.
+
+## Compatibility Requirements
+
+Status: Accepted design constraints; unimplemented.
+
+- Report IDs, prompt IDs, report selection, valid periods, artifact grouping,
+  output names, and distributor bundle behavior remain stable.
+- Module snapshot and Recent Changes behavior remains deterministic.
+- Promptkit receives only the existing curated prompt-input boundary.
+- Generated reports continue to use the managed Markdown path as the
+  distributor upload source.
+- RunID lookup and inspection remain available for successful and failed runs.
+- Existing managed state paths remain stable where their meaning is unchanged.
+  Scriptorium-specific artifact names or schemas may change when retaining
+  them would misrepresent the new contract.
+- Any artifact or metadata schema change is explicit, documented, and covered
+  by state and inspection tests.
+- Prompt or generated content is not added to routine logs or CLI summaries.
+- Tests do not require live Promptkit providers or credentials.
+
+## Verification And Completion Criteria
+
+Status: Proposed completion criteria for the unimplemented migration.
+
+The migration is complete when:
+
+- all seven reports prepare and execute through Promptkit using embedded
+  report-owned assets;
+- direct-Markdown and generated-text-template paths have deterministic offline
+  adapter and app-level coverage;
+- preparation, provider failure, capacity rejection, cancellation, timeout,
+  Promptkit validation failure, generated-text validation failure, template
+  failure, and successful generation preserve their specified artifacts;
+- morning and evening batches construct one shared engine and preserve current
+  collection, planning, ordering, continuation, output, and notification
+  behavior;
+- configuration examples load and contain no Scriptorium fields;
+- CLI summaries and inspection commands expose the new artifact contract
+  without Promptkit dependency types;
+- Scriptorium code, configuration, tests, and runtime documentation have been
+  removed;
+- non-roadmap documentation describes only the implemented Promptkit
+  integration;
+- `go test ./...`, CLI help validation, and `git diff --check` pass; and
+- no committed `go.work`, local `replace`, live-provider test, or secret-bearing
+  fixture remains.
+
+Fixture-based comparison with the current Scriptorium behavior is sufficient
+for migration verification. A production-selectable dual-run period is not
+required because model calls are nondeterministic, costly, and difficult to
+compare meaningfully.
+
+## External Prerequisite
+
+Status: Required and unimplemented.
+
+Before implementing the embedded asset stage, the current Scriptorium prompt
+corpus must be made available in this repository. It should include the seven
+prompt definitions, referenced content files, private response schemas,
+relevant default-profile declarations, and any shared prompt fragments needed
+to reproduce current report behavior.
+
+## Open Questions
+
+Status: Open; these require decisions before implementation.
+
+- What exact `promptkit.*` configuration fields should replace the current
+  Scriptorium fields, including the name and precedence of an optional explicit
+  profile override?
+- Should weatherreporter expose Promptkit's conventional `local` backend
+  registration as a narrow configuration feature, or rely initially on
+  built-in and endpoint-only profiles?
+- Should report definitions store an explicit Promptkit prompt version, or
+  should each embedded prompt ID be required to have exactly one version?
+- What CLI or configuration control enables sensitive prompt/response debug
+  artifacts, and where should those artifacts live?
+- What final names and schema versions should replace the
+  Scriptorium-specific preflight and run-result artifacts while balancing
+  semantic clarity with existing state-path compatibility?

docs/templates.md

@@ -0,0 +1,179 @@
+# Report Templates
+
+This guide is for maintainers editing Weatherreporter's embedded Markdown
+templates. Templates format already validated report inputs; they do not select
+sources, derive weather facts, or validate generated prose. For those details,
+see [Generated Text internals](internal/generatedtext.md) and [Report Template
+internals](internal/reporttemplate.md).
+
+## Template Assets
+
+Only the generated-text reports use repository-native Markdown templates.
+Each report has one matching template ID, generated-text schema ID, and prompt
+source:
+
+| Report | Template | Schema | Prompt ID and source |
+| --- | --- | --- | --- |
+| Daily | `templates/daily.md.tmpl` (`daily`) | `daily` | `weather.daily_generated_text`; `prompts/daily.generated_text.md` |
+| Today | `templates/today.md.tmpl` (`today`) | `today` | `weather.today_generated_text`; `prompts/today.generated_text.md` |
+| Tomorrow | `templates/tomorrow.md.tmpl` (`tomorrow`) | `tomorrow` | `weather.tomorrow_generated_text`; `prompts/tomorrow.generated_text.md` |
+| Hourly | `templates/hourly.md.tmpl` (`hourly`) | `hourly` | `weather.hourly_generated_text`; `prompts/hourly.generated_text.md` |
+
+The matching schema files are under `internal/reporttemplate/schemas/`. The
+generated-text catalog pairs each schema ID with its template ID; keep the
+matching report prompt source aligned with that pair.
+
+Shared partials are under `internal/reporttemplate/templates/partials/`:
+
+| Partial | Used by |
+| --- | --- |
+| `alert_digest.md.tmpl` | Daily, Today, Tomorrow, and Hourly |
+| `precipitation_timing.md.tmpl` | Daily, Today, Tomorrow, and Hourly |
+| `daypart_forecast.md.tmpl` | Daily and Tomorrow |
+| `today_daypart_forecast.md.tmpl` | Today |
+
+All shared partials are parsed whenever any top-level template is rendered. A
+syntax error in a partial can therefore prevent every generated-text report
+from rendering.
+
+## Editing Rules
+
+- Use Go `text/template` syntax and keep changes to Markdown structure,
+  ordering, and display conditions.
+- Templates use `missingkey=error`; reference only documented fields and guard
+  optional module pointers with `with` or `if`.
+- Prefer `.Modules` for deterministic display values. Do not add weather
+  calculations, source selection, or prompt-input shaping to a template.
+- Keep generated prose in `.GeneratedText`; do not restate deterministic facts
+  in generated prose merely to compensate for a template change.
+- When changing the generated-prose contract, update the matching prompt,
+  schema, validator, render context, and template together. The validation and
+  catalog rules are owned by [Generated Text internals](internal/generatedtext.md).
+- Use `.Modules.Dayparts` for ordered daypart output. Do not range over
+  `.Modules.DerivedDaypartSummaries`, which is a map.
+
+Minimal optional-value pattern:
+
+```gotemplate
+{{ with .Modules.CurrentConditions }}
+Currently, it is {{ with .TemperatureF }}{{ . }}°F{{ end }}.
+{{ else }}
+Current conditions are unavailable.
+{{ end }}
+```
+
+Minimal list pattern:
+
+```gotemplate
+{{ range .GeneratedText.ForecastDiscussion }}
+{{ . }}
+{{ end }}
+```
+
+## Registered Functions
+
+Templates have these helpers in addition to Go template built-ins:
+
+| Function | Accepts | Returns true when |
+| --- | --- | --- |
+| `hasRelevantAlerts` | an alert-digest value or pointer | its `Relevant` slice is nonempty |
+| `hasEnhancedOrHigherSPCRisk` | an SPC outlook value or pointer | its `RiskDigest` contains an Enhanced, Moderate, or High Risk entry |
+| `isEnhancedOrHigherSPCRisk` | one SPC risk-digest entry | its `LabelText`, or fallback `RiskLabel`, is Enhanced, Moderate, or High Risk |
+
+For example, the alert partial uses the first two functions to decide whether
+to render the section:
+
+```gotemplate
+{{ if hasRelevantAlerts .Modules.AlertDigest }}
+## Alert Digest
+{{ end }}
+```
+
+## Render Context
+
+Every rendered template receives one typed context with these five top-level
+fields:
+
+| Field | Purpose |
+| --- | --- |
+| `.Report` | Display labels and canonical report timing metadata. |
+| `.GeneratedText` | Validated prose supplied by Scriptorium. |
+| `.Modules` | Deterministic, typed values prepared for Markdown rendering. |
+| `.Collected` | Normalized upstream facts for advanced use. |
+| `.Derived` | Shared calculated facts for advanced use. |
+
+`.Collected` and `.Derived` are available for an exceptional display need, but
+they are lower-level contracts. Keep reusable weather derivation in Go and use
+the module surface for normal template work.
+
+### Report Metadata
+
+All contexts provide `.Report.Title`, `.Report.GeneratedAt`,
+`.Report.GeneratedAtLabel`, `.Report.ValidPeriod`, and `.Report.Timezone`.
+
+Hourly additionally provides `.Report.LocationName` and
+`.Report.ValidPeriodLabel`.
+
+Daily, Today, and Tomorrow additionally provide `.Report.ForecastDate`,
+`.Report.ForecastDateLabel`, and `.Report.ForecastDayName`. Their valid-period
+field remains canonical timing data; use the supplied display labels instead
+of formatting timestamps in a template.
+
+### Validated GeneratedText Prose
+
+GeneratedText is prose returned by Scriptorium and validated before rendering.
+It is not a source for deterministic weather facts.
+
+| Field | Hourly type | Daily, Today, and Tomorrow type | Notes |
+| --- | --- | --- | --- |
+| `.GeneratedText.Summary` | `string` | `string` | Required. |
+| `.GeneratedText.ForecastDiscussion` | `string` | `[]string` | Required; range over the day-style paragraph slice. |
+| `.GeneratedText.PrecipitationTiming` | `string` | `string` | Optional prose used by the precipitation partial when deterministic windows exist. |
+| `.GeneratedText.Confidence` | `string` | `string` | Optional validated prose; the current templates do not render it. |
+
+The JSON schema rejects unknown properties and defines the required fields, but
+the schema body and validation behavior are documented in [Generated Text
+internals](internal/generatedtext.md).
+
+### Deterministic Module Values
+
+Module values are deterministic outputs built from collected and derived facts.
+Module pointers can be nil when their source or policy permits omission.
+
+| Module field | Available in |
+| --- | --- |
+| `.Modules.Metadata`, `.Modules.CurrentConditions`, `.Modules.HourlyForecast`, `.Modules.PrecipTiming`, `.Modules.AlertDigest`, `.Modules.SPCConvectiveOutlooks`, `.Modules.AreaForecastDiscussion`, `.Modules.SPCConvectiveDiscussion`, `.Modules.WeatherStory` | All four contexts |
+| `.Modules.DerivedDailySummary`, `.Modules.DerivedDaypartSummaries`, `.Modules.Dayparts` | Daily, Today, Tomorrow |
+| `.Modules.OutdoorWindows`, `.Modules.DailyPlanning` | Daily |
+| `.Modules.TodayPlanning` | Today |
+| `.Modules.TomorrowPlanning` | Tomorrow |
+
+The repository templates currently use the following nested display values.
+They are the preferred surface for comparable edits:
+
+| Area | Values |
+| --- | --- |
+| Current conditions | `.TemperatureF`, `.ConditionText`, `.ConditionTextLower`, `.ApparentTemperatureF`, `.RelativeHumidityPercent`, `.WindDirectionText`, `.WindSpeedMph` |
+| Hourly periods | `.Periods`, `.HourLabel`, `.Name`, `.TemperatureF`, `.TextDescription`, `.TextDescriptionLower`, `.MentionPrecipitation`, `.ProbabilityOfPrecipitationPercent` |
+| Dayparts | `.Dayparts[].Key` and `.Dayparts[].Summary` fields `DisplayName`, `DominantCondition`, `DominantConditionDisplay`, `TemperatureTrend`, `TemperatureStartPhraseF`, `TemperatureEndPhraseF`, `TemperaturePeakPhraseF`, `TemperatureSteadyPhraseF`, `TemperaturePhraseF`, `MentionPrecipitation`, and `MaxPopPercent` |
+| Precipitation timing | `.PrecipitationWindows`, plus each window's `PeriodBegins`, `PeriodBeginsHourLabel`, `PeriodEnds`, `PeriodEndsHourLabel`, `ExpectationPhrase`, `MaxPopPercent`, `MaxPopTime`, and `MaxPopHourLabel` |
+| Alert digest | `.AlertDigest.Relevant` entries' `Event`, `Headline`, `PeriodBegins`, and `PeriodEnds` |
+| SPC risk digest | `.SPCConvectiveOutlooks.RiskDigest` entries' `LabelText`, `RiskLabel`, `PeriodBegins`, and `PeriodEnds` |
+
+Other fields on these typed modules remain available when a template has a
+well-defined display need. Their module contracts and weather derivation belong
+to [Module contract internals](internal/module.md), [Module builder
+internals](internal/briefing.md), and [Forecast derivation
+internals](internal/forecast-derivation.md).
+
+## Validate Changes
+
+Run the focused checks after editing templates, partials, prompts, or schemas:
+
+```sh
+go test ./internal/reporttemplate ./internal/generatedtext ./internal/app
+git diff --check
+```
+
+The render-context and template tests cover Daily, Today, Tomorrow, and Hourly
+contexts. Run the repository-wide test suite before merging a broader change.

docs/troubleshooting.md

@@ -1,340 +1,271 @@
-# Weatherreporter Troubleshooting
+# 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.
+Use the error from the command together with the run artifacts when a run ID is
+available. Start with [`inspect metadata`](cli.md#inspection-commands) to identify the
+report and artifact paths, then use the narrower inspection command named
+below. Do not remove a workspace to diagnose a failure: it contains the
+evidence needed to correct it safely.
 
-## `weather_api.base_url is required`
+## A command or configuration is rejected before work starts
 
-Symptom: a generation command fails before fetching weather data.
+Symptom: The command exits before it creates a run, with an unknown-flag,
+missing-argument, invalid date or time bound, invalid timezone, or
+`weather_api.base_url` message.
 
-Likely cause: no Weather API base URL is configured.
+Likely cause: The command does not accept that option for the requested report,
+or required command and configuration values are absent or malformed.
 
-Diagnostic:
+Diagnostic: Compare the command with [`generate` and `run`](cli.md#commands-and-usage)
+and review the configured value named in the error. `generate daily` requires
+`--date`; `generate storm` requires both `--start` and `--end`.
 
-```sh
-weatherreporter generate daily --config ./config.yml --date 2026-05-29
-```
+Safe fix: Correct only the reported option or configuration value. Use an
+absolute Weather API URL and a valid IANA timezone; do not change unrelated
+workspace data.
 
-Safe fix: add `weather_api.base_url` to the config file, or pass the intended
-config path with `--config`.
+See also: [Configuration](config.md) and [Weather API integration](integrations/weatherapi.md).
 
-Relevant docs: [Configuration reference](config.md).
+## Weather data cannot be collected
 
-## `weather_api.base_url must be an absolute URL`
+Symptom: A generation command fails while fetching weather data, or reports
+`hourly forecast data is missing` or `contains no periods`.
 
-Symptom: config loading fails with a base URL validation error.
+Likely cause: The Weather API is unavailable, its configured endpoint or
+credentials are unsuitable, or the response lacks the hourly forecast required
+by the selected report.
 
-Likely cause: `weather_api.base_url` is missing a scheme or host.
+Diagnostic: Check the service status and the configured base URL, then retry
+the same report. If a run ID was produced, run `weatherreporter inspect sources
+RUN_ID` to see the recorded source result.
 
-Diagnostic: inspect the configured value in the file passed to `--config`.
+Safe fix: Restore access to the configured Weather API or choose a reporting
+period supported by the returned forecast. Do not invent missing hourly values
+in local artifacts.
 
-Safe fix: use an absolute URL such as `https://weather.api.example.com/`.
+See also: [Configuration](config.md) and [Weather API integration](integrations/weatherapi.md).
 
-Relevant docs: [Configuration reference](config.md).
+## Optional source warnings appear
 
-## Invalid Timezone
+Symptom: The report succeeds but its output says that a source supplied a
+warning or degraded result.
 
-Symptom: config loading fails with `weather_api.timezone` context, or a CLI
-timezone override fails.
+Likely cause: An optional source did not return usable data; mandatory weather
+collection still completed.
 
-Likely cause: `weather_api.timezone` or `--tz` is not recognized.
+Diagnostic: Run `weatherreporter inspect sources RUN_ID` and identify the
+source and warning recorded for that run.
 
-Diagnostic:
+Safe fix: Correct the affected source configuration or service issue, then
+generate a new report if the missing optional information is needed. Keep the
+existing run for comparison.
 
-```sh
-weatherreporter generate daily --tz America/Chicago --date 2026-05-29
-```
+See also: [Inspecting a run](cli.md#inspection-commands) and [Operations](operations.md).
 
-Safe fix: use an accepted timezone value, such as an IANA timezone name,
-`Chicago`, `Stl`, a US timezone abbreviation, or a UTC offset.
+## Scriptorium cannot be prepared
 
-Relevant docs: [Configuration reference](config.md).
+Symptom: The report fails with a fragment such as `run scriptorium render`, or
+the Scriptorium executable cannot be started.
 
-## Storm Command Rejects Time Bounds
+Likely cause: The configured executable, profile, prompt, or its local runtime
+environment is unavailable to Weatherreporter.
 
-Symptom: `generate storm` fails with `requires --start`, `requires --end`, or
-`requires --end after --start`.
+Diagnostic: Confirm that the configured executable can be run by the same user
+and inspect `weatherreporter inspect metadata RUN_ID` when a run ID is shown.
 
-Likely cause: the manual event window is missing or invalid.
+Safe fix: Repair the executable path or the Scriptorium configuration and retry
+the report. Do not edit generated artifacts to bypass preparation.
 
-Diagnostic:
+See also: [Configuration](config.md) and [Operations](operations.md).
 
-```sh
-weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00
-```
+## Scriptorium preflight fails
 
-Safe fix: provide both bounds. Use `YYYY-MM-DDTHH:MM` in the configured
-timezone, or RFC3339 timestamps with explicit offsets.
+Symptom: A Scriptorium-backed report stops before text generation, often with
+a `scriptorium render exited with code` fragment.
 
-Relevant docs: [CLI reference](cli.md).
+Likely cause: Scriptorium rejected the render request, prompt, profile, or data
+package before it could run the report.
 
-## Weather API Fetch Fails
+Diagnostic: Inspect the run metadata and the saved preflight artifact path it
+references. Compare the reported Scriptorium diagnostic with its configuration.
 
-Symptom: generation fails with `fetch /...`, an HTTP status, or request context.
+Safe fix: Correct the reported Scriptorium input or configuration, then create
+a new run. Preserve the failed preflight artifact for support or comparison.
 
-Likely cause: the configured Weather API endpoint is unreachable, returned a
-non-2xx response, or returned an invalid response envelope.
+See also: [Inspecting a run](cli.md#inspection-commands) and [Operations](operations.md).
 
-Diagnostic:
+## Scriptorium report execution fails
 
-```sh
-weatherreporter generate daily --config ./config.yml --date 2026-05-29
-```
+Symptom: Preparation succeeded, but generation stops with a
+`scriptorium run exited with code` fragment.
 
-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`.
+Likely cause: The Scriptorium run failed after preflight, for example because
+its prompt execution or runtime dependency failed.
 
-Relevant docs: [Configuration reference](config.md).
+Diagnostic: Inspect the run metadata and preflight artifact, then review the
+exit diagnostic from the command. This distinguishes a run failure from a
+preflight failure.
 
-## Hourly Forecast Is Missing
+Safe fix: Correct the Scriptorium issue identified by that diagnostic and run
+the report again; leave the failed run artifacts in place.
 
-Symptom: generation fails with hourly forecast context, such as missing hourly
-data or an hourly forecast containing no periods.
+See also: [Operations](operations.md).
 
-Likely cause: hourly forecast data is required for generated reports.
+## Generated text fails validation
 
-Diagnostic: check the Weather API response for `/forecast/hourly`.
+Symptom: A generated-text report fails after Scriptorium returns text, with a
+message about generated text or required report content.
 
-Safe fix: restore hourly forecast data at the Weather API. Missing-source
-policy cannot make hourly optional.
+Likely cause: Returned text does not meet the report's validation rules.
 
-Relevant docs: [Configuration reference](config.md), [Operations guide](operations.md).
+Diagnostic: Use `weatherreporter inspect metadata RUN_ID` to find the saved raw
+generated-text artifact, and inspect it alongside the reported validation
+message.
 
-## Source Warnings Appear
+Safe fix: Correct the upstream prompt or generation configuration that caused
+the invalid output, then create a new run. Do not hand-edit saved raw text and
+present it as a validated report.
 
-Symptom: generation succeeds, but metadata or `inspect sources` shows source
-warnings.
+See also: [Operations](operations.md).
 
-Likely cause: an optional source was missing or malformed under a warning
-missing-source policy.
+## Report template rendering fails
 
-Diagnostic:
+Symptom: Scriptorium output is available, but the report fails while building
+the final Markdown document.
 
-```sh
-weatherreporter inspect sources RUN_ID
-weatherreporter inspect metadata RUN_ID
-```
+Likely cause: The selected report template or the render context is
+incompatible with the generated or collected data.
 
-Safe fix: inspect the warning `source`, `code`, `message`, and `endpoint`. Fix
-the upstream optional source, or intentionally change the relevant
-`missing_source` policy.
+Diagnostic: Inspect the metadata, generated-text result, and render-context
+artifacts for the run. Note the template or missing-field fragment in the
+error rather than relying on a complete error string.
 
-Relevant docs: [Configuration reference](config.md), [Operations guide](operations.md).
+Safe fix: Correct the template or its supported inputs in source control, test
+the change, and create a new report. Do not alter the saved context merely to
+make one historical run render.
 
-## `scriptorium` Is Not Found Or Cannot Start
+See also: [Operations](operations.md).
 
-Symptom: generation fails with `run scriptorium render` or `run scriptorium`
-and an executable or OS error.
+## A report fails after artifacts are saved
 
-Likely cause: the configured Scriptorium binary is unavailable or not
-executable.
+Symptom: A generation command reports an error after showing a run ID, such as
+an error writing the managed report, copying `--out`, saving metadata, or
+notifying Distributor.
 
-Diagnostic: check `scriptorium.binary` in config and run the same binary outside
-`weatherreporter`.
+Likely cause: A local filesystem permission or path problem, an unavailable
+destination for `--out`, or a later report-delivery failure occurred after
+earlier steps succeeded.
 
-Safe fix: install Scriptorium, update `scriptorium.binary`, or fix executable
+Diagnostic: Run `weatherreporter inspect metadata RUN_ID` and check the exact
+path and operation named in the error. For an `--out` failure, verify only the
+specified destination directory and filename.
+
+Safe fix: Repair access to that exact path or disable the optional delivery
+step only when appropriate, then generate a new report. Keep the existing
+managed artifacts untouched.
+
+See also: [Operations](operations.md) and [Distributor integration](integrations/distributor/pkg-upload.md).
+
+## A batch has partial report failures
+
+Symptom: `run morning` or `run evening` returns nonzero and reports both
+succeeded and failed report items.
+
+Likely cause: A report-level collection, generation, rendering, or local
+output failure affected one or more planned reports; the remaining reports
+continue independently.
+
+Diagnostic: Read the per-report status lines, then inspect the run ID for each
+failed item with `weatherreporter inspect metadata RUN_ID`.
+
+Safe fix: Correct the specific failure and rerun the batch or affected report.
+Do not delete successful reports simply because another item failed.
+
+See also: [Batch commands](cli.md#commands-and-usage) and [Operations](operations.md).
+
+## A batch upload is skipped
+
+Symptom: The batch result says Distributor notification was skipped because
+one or more reports failed.
+
+Likely cause: Batch notification intentionally runs only after every planned
+report succeeds.
+
+Diagnostic: Review the failed report items and their metadata; a skipped batch
+notification is expected while any item is failed.
+
+Safe fix: Resolve the report failures and rerun the batch. Do not upload a
+partial bundle by manually reusing batch artifacts.
+
+See also: [Batch commands](cli.md#commands-and-usage) and [Operations](operations.md).
+
+## Distributor notification fails
+
+Symptom: A completed report or otherwise successful batch reports a Distributor
+error, including a rejected upload, source or idempotency conflict, or service
+unavailability.
+
+Likely cause: Distributor rejected the request identity or bundle, required
+credentials are unavailable, or the remote service cannot be reached.
+
+Diagnostic: Inspect the report metadata or batch result for the notification
+artifact and the error fragment. Verify the configured Distributor endpoint and
+request identity without exposing credentials.
+
+Safe fix: Resolve the reported remote conflict, configuration, or availability
+issue and create a new report or rerun the batch. Do not modify recorded bundle
+or idempotency artifacts to force an upload.
+
+See also: [Configuration](config.md), [Distributor integration](integrations/distributor/pkg-upload.md), and [Operations](operations.md).
+
+## Secrets cannot be loaded
+
+Symptom: Startup reports `read secrets directory`, `secret file`, or a token
+environment-variable error before the affected service can be used.
+
+Likely cause: The configured secrets directory cannot be read, contains a
+non-regular file, or does not supply the environment variable required by an
+enabled integration.
+
+Diagnostic: Check the configured secrets directory path, ownership, and that
+each intended secret is a regular file. Confirm the variable name from
+configuration only; never print or paste its value.
+
+Safe fix: Correct permissions, file type, or the missing secret file, then
+retry. Keep secret values out of commands, logs, tickets, and artifacts.
+
+See also: [Configuration](config.md) and [Operations](operations.md).
+
+## A run ID or saved state cannot be found
+
+Symptom: An inspection command reports that metadata for a run ID was not
+found, or a report cannot use a prior snapshot.
+
+Likely cause: The run ID is wrong, the configured workspace is different from
+the one that created the run, or no compatible prior snapshot exists.
+
+Diagnostic: Use `weatherreporter inspect reports` to list available reports in
+the current workspace, then copy the run ID from that output. Confirm the
+workspace configuration before retrying a prior-snapshot operation.
+
+Safe fix: Use an existing run ID and its original workspace, or generate a new
+compatible report when no prior snapshot is available. Do not fabricate state
+files or run IDs.
+
+See also: [Inspecting a run](cli.md#inspection-commands) and [Operations](operations.md).
+
+## Workspace paths cannot be read or written
+
+Symptom: Startup or report persistence reports a workspace-path, permission,
+or "must be relative to workspace root" error.
+
+Likely cause: A configured artifact directory escapes the workspace, or the
+current user lacks access to the specific workspace location.
+
+Diagnostic: Check the named configuration path against the configured workspace
+root and inspect ownership and permissions of that exact directory.
+
+Safe fix: Set the path to a location within the workspace or repair access to
+the named directory, then rerun. Do not remove the workspace or broadly relax
 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, module snapshot, and data package for that RunID.
-
-Relevant docs: [CLI reference](cli.md), [Operations guide](operations.md).
-
-## Invalid Secrets Directory
-
-Symptom: config loading fails with `read secrets directory`, `secret file`, or
-environment variable name context.
-
-Likely cause: `secrets.directory` points to a missing directory or contains an
-invalid entry. Secret entries must be regular files directly under the
-configured directory, and file basenames must match
-`[A-Za-z_][A-Za-z0-9_]*`.
-
-Diagnostic: list the configured directory and inspect entry names and file
-types. Do not print secret file contents.
-
-Safe fix: create the directory, remove subdirectories or symlinks, fix invalid
-filenames, and ensure the weatherreporter process can read each secret file.
-
-Relevant docs: [Configuration reference](config.md).
-
-## Distributor Token Is Missing
-
-Symptom: notification fails with a message that the distributor token
-environment variable is not set.
-
-Likely cause: `notify.distributor.enabled` is true, but the environment
-variable named by `notify.distributor.token_env` was not populated directly or
-through `secrets.directory`.
-
-Diagnostic: check `notify.distributor.token_env`, then verify a matching secret
-file exists under `secrets.directory` or that the process environment includes
-the variable. Do not print the token value.
-
-Safe fix: create a readable secret file whose basename matches `token_env`, or
-set the environment variable through the service manager.
-
-Relevant docs: [Configuration reference](config.md),
-[Operations guide](operations.md).
-
-## Distributor Upload Conflict
-
-Symptom: notification fails with idempotency conflict context.
-
-Likely cause: the same idempotency key was reused for different bundle content
-within the same distributor token and pipeline. By default the bundle ID is a
-stable report-stream identity and the idempotency key appends RunID.
-
-Diagnostic: inspect the failed batch JSON or stderr line for pipeline, bundle,
-and idempotency context. Compare the configured templates with the report RunID
-and report path.
-
-Also inspect the notification artifact linked from metadata. It records the
-rendered pipeline ID, bundle ID, idempotency key, upload result, distributor run
-status, status error, and raw run report JSON when available.
-
-Safe fix: keep idempotency templates stable for retries of the same generated
-report, but do not reuse the same rendered key for different generated report
-content.
-
-Relevant docs: [Operations guide](operations.md),
-[Distributor adapter internals](internal/distributor-adapter.md).
-
-## Distributor Upload Rejected
-
-Symptom: notification fails with distributor upload rejection, HTTP status, or
-bundle validation context.
-
-Likely cause: the distributor endpoint rejected the token, pipeline ID, bundle
-ID, idempotency key, source file, or one of the rendered bundle paths.
-
-Diagnostic: inspect stdout JSON or stderr status lines for
-`notificationError`. Confirm `notify.distributor.endpoint`,
-`notify.distributor.pipeline_id_template`,
-`notify.distributor.report_path_templates`, and token configuration. Token
-values are redacted from weatherreporter errors.
-
-If the upload was accepted but destination output did not change, inspect the
-notification artifact's `runStatus.report`. Distributor actions such as
-`replace_older`, `skip_same`, `skip_destination_newer`, or `failed` explain how
-the destination handled the uploaded bundle.
-
-Safe fix: fix the endpoint, token, templates, or distributor-side upload
-configuration. The weatherreporter upload source is the managed Markdown report,
-not `--out` or `--out-dir` copies.
-
-Relevant docs: [Configuration reference](config.md),
-[Operations guide](operations.md),
-[Distributor adapter internals](internal/distributor-adapter.md).
-
-## Distributor Unavailable
-
-Symptom: notification fails with network, timeout, or service unavailable
-context.
-
-Likely cause: the configured distributor endpoint is unreachable, slow, or
-temporarily unavailable.
-
-Diagnostic: check network access from the weatherreporter host to
-`notify.distributor.endpoint`. For batch runs, inspect which reports have
-`notificationStatus: "failed"`.
-
-Safe fix: restore distributor service availability and rerun the affected
-report or batch. Stable idempotency keys make retrying the same generated report
-safe unless the distributor reports a conflict.
-
-Relevant docs: [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).
+See also: [Configuration](config.md) and [Operations](operations.md).

examples/config.yml

@@ -1,7 +1,7 @@
 weather_api:
-  base_url: https://weather.api.rakestrawhome.com/
+  base_url: https://weather.api.example.com/
   timeout: 15s
-  precision: 1
+  precision: 0
   units: us
   timezone: "America/Chicago"
   format: json
@@ -21,11 +21,14 @@ notify:
     token_env: DISTRIBUTOR_UPLOAD_TOKEN
     timeout: 30s
     failure_policy: error
-    pipeline_id_template: "weatherreporter.{artifact_group}"
+    pipeline_id_template: "weatherreporter.{report_id}"
     bundle_id_template: "weatherreporter.{location_id}.{report_id}"
     idempotency_key_template: "{bundle_id}.{run_id}"
-    report_path_templates:
-      - "{valid_start_date}/{artifact_group}/{valid_start_date}-{artifact_group}-{run_id}.md"
+    batch:
+      enabled: true
+      pipeline_id_template: "weatherreporter"
+      bundle_id_template: "weatherreporter.{location_id}.{batch}"
+      idempotency_key_template: "{bundle_id}.{batch_run_id}"
 
 missing_source:
   default: warn
@@ -69,6 +72,10 @@ recent_change:
 
 reports:
   daily:
+    distributor:
+      path_templates:
+        - "daily/{valid_start_date}/{run_id}.md"
+        - "daily/{valid_start_date}/index.md"
     deterministic_modules:
       - metadata
       - current_conditions
@@ -77,6 +84,26 @@ reports:
       - derived_daypart_summaries
       - precip_timing
       - alert_digest
+      - spc_convective_outlooks
+      - id: area_forecast_discussion
+        options:
+          sections:
+            - long_term
+      - spc_convective_discussion
+      - weather_story
+      - outdoor_windows
+      - daily_planning
+      - hourly_forecast
+  today:
+    deterministic_modules:
+      - metadata
+      - current_conditions
+      - narrative_forecast
+      - derived_daily_summary
+      - derived_daypart_summaries
+      - precip_timing
+      - alert_digest
+      - spc_convective_outlooks
       - id: area_forecast_discussion
         options:
           sections:
@@ -84,6 +111,23 @@ reports:
             - key_messages
             - short_term
             - long_term
+      - spc_convective_discussion
       - weather_story
       - outdoor_windows
       - hourly_forecast
+      - today_planning
+  hourly:
+    deterministic_modules:
+      - metadata
+      - current_conditions
+      - hourly_forecast
+      - precip_timing
+      - alert_digest
+      - spc_convective_outlooks
+      - id: area_forecast_discussion
+        options:
+          sections:
+            - key_messages
+            - short_term
+      - spc_convective_discussion
+      - weather_story

internal/adapters/scriptorium/runner.go

@@ -79,6 +79,12 @@ type RunRequest struct {
 	OutputPath      string
 }
 
+type StructuredRunRequest struct {
+	PromptID        string
+	DataPackagePath string
+	OutputPath      string
+}
+
 type RenderResult struct {
 	Command         []string `json:"command"`
 	Stdout          string   `json:"stdout"`
@@ -98,6 +104,16 @@ type RunResult struct {
 	OutputPath      string   `json:"outputPath"`
 }
 
+type StructuredRunResult 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")
@@ -124,6 +140,82 @@ func (r Runner) Render(ctx context.Context, req RenderRequest) (*RenderResult, e
 }
 
 func (r Runner) Run(ctx context.Context, req RunRequest) (*RunResult, error) {
+	result, err := r.executeRun(ctx, outputRunRequest{
+		PromptID:        req.PromptID,
+		DataPackagePath: req.DataPackagePath,
+		OutputPath:      req.OutputPath,
+	}, "run scriptorium", "scriptorium run")
+	if err != nil {
+		if result == nil {
+			return nil, err
+		}
+		return result.runResult(), err
+	}
+	return result.runResult(), nil
+}
+
+func (r Runner) StructuredRun(ctx context.Context, req StructuredRunRequest) (*StructuredRunResult, error) {
+	result, err := r.executeRun(ctx, outputRunRequest{
+		PromptID:        req.PromptID,
+		DataPackagePath: req.DataPackagePath,
+		OutputPath:      req.OutputPath,
+	}, "run scriptorium structured output", "scriptorium structured run")
+	if err != nil {
+		if result == nil {
+			return nil, err
+		}
+		return result.structuredRunResult(), err
+	}
+	return result.structuredRunResult(), nil
+}
+
+func (result outputRunResult) runResult() *RunResult {
+	return &RunResult{
+		Command:         result.Command,
+		Stdout:          result.Stdout,
+		Stderr:          result.Stderr,
+		StdoutTruncated: result.StdoutTruncated,
+		StderrTruncated: result.StderrTruncated,
+		ExitCode:        result.ExitCode,
+		OutputPath:      result.OutputPath,
+	}
+}
+
+func (result outputRunResult) structuredRunResult() *StructuredRunResult {
+	return &StructuredRunResult{
+		Command:         result.Command,
+		Stdout:          result.Stdout,
+		Stderr:          result.Stderr,
+		StdoutTruncated: result.StdoutTruncated,
+		StderrTruncated: result.StderrTruncated,
+		ExitCode:        result.ExitCode,
+		OutputPath:      result.OutputPath,
+	}
+}
+
+type execution struct {
+	binary string
+	args   []string
+	result CommandResult
+}
+
+type outputRunRequest struct {
+	PromptID        string
+	DataPackagePath string
+	OutputPath      string
+}
+
+type outputRunResult struct {
+	Command         []string
+	Stdout          string
+	Stderr          string
+	StdoutTruncated bool
+	StderrTruncated bool
+	ExitCode        int
+	OutputPath      string
+}
+
+func (r Runner) executeRun(ctx context.Context, req outputRunRequest, executeContext string, exitContext string) (*outputRunResult, error) {
 	if req.PromptID == "" {
 		return nil, fmt.Errorf("prompt id is required")
 	}
@@ -133,11 +225,15 @@ func (r Runner) Run(ctx context.Context, req RunRequest) (*RunResult, error) {
 	if req.OutputPath == "" {
 		return nil, fmt.Errorf("output path is required")
 	}
-	execution, err := r.execute(ctx, r.runArgs(req))
+	execution, err := r.execute(ctx, r.runArgs(RunRequest{
+		PromptID:        req.PromptID,
+		DataPackagePath: req.DataPackagePath,
+		OutputPath:      req.OutputPath,
+	}))
 	if err != nil {
-		return nil, fmt.Errorf("run scriptorium: %w", err)
+		return nil, fmt.Errorf("%s: %w", executeContext, err)
 	}
-	result := &RunResult{
+	result := &outputRunResult{
 		Command:         execution.argv(),
 		Stdout:          string(execution.result.Stdout),
 		Stderr:          string(execution.result.Stderr),
@@ -147,17 +243,11 @@ func (r Runner) Run(ctx context.Context, req RunRequest) (*RunResult, error) {
 		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, fmt.Errorf("%s exited with code %d: %s", exitContext, 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 == "" {

internal/adapters/scriptorium/runner_test.go

@@ -2,6 +2,7 @@ package scriptorium
 
 import (
 	"context"
+	"fmt"
 	"reflect"
 	"strings"
 	"testing"
@@ -19,7 +20,7 @@ func TestRenderConstructsCommand(t *testing.T) {
 	}
 
 	result, err := runner.Render(context.Background(), RenderRequest{
-		PromptID:        "weather.daily_report",
+		PromptID:        "weather.markdown_report",
 		DataPackagePath: "/tmp/data_package.yaml",
 	})
 	if err != nil {
@@ -30,7 +31,7 @@ func TestRenderConstructsCommand(t *testing.T) {
 		"render",
 		"--config", "/etc/scriptorium.yml",
 		"--profile", "weather",
-		"--prompt", "weather.daily_report",
+		"--prompt", "weather.markdown_report",
 		"--input", "data_package=/tmp/data_package.yaml",
 		"--format", "json",
 	}
@@ -56,7 +57,7 @@ func TestRenderReturnsResultForNonzeroExit(t *testing.T) {
 	}
 
 	result, err := runner.Render(context.Background(), RenderRequest{
-		PromptID:        "weather.daily_report",
+		PromptID:        "weather.markdown_report",
 		DataPackagePath: "/tmp/data_package.yaml",
 	})
 	if err == nil {
@@ -84,7 +85,7 @@ func TestRunConstructsCommand(t *testing.T) {
 	}
 
 	result, err := runner.Run(context.Background(), RunRequest{
-		PromptID:        "weather.daily_report",
+		PromptID:        "weather.markdown_report",
 		DataPackagePath: "/tmp/data_package.yaml",
 		OutputPath:      "/tmp/daily.md",
 	})
@@ -96,7 +97,7 @@ func TestRunConstructsCommand(t *testing.T) {
 		"run",
 		"--config", "/etc/scriptorium.yml",
 		"--profile", "weather",
-		"--prompt", "weather.daily_report",
+		"--prompt", "weather.markdown_report",
 		"--input", "data_package=/tmp/data_package.yaml",
 		"--out", "/tmp/daily.md",
 	}
@@ -129,7 +130,7 @@ func TestRunReturnsResultForValidationExit(t *testing.T) {
 	}
 
 	result, err := runner.Run(context.Background(), RunRequest{
-		PromptID:        "weather.daily_report",
+		PromptID:        "weather.markdown_report",
 		DataPackagePath: "/tmp/data_package.yaml",
 		OutputPath:      "/tmp/daily.md",
 	})
@@ -147,17 +148,397 @@ func TestRunReturnsResultForValidationExit(t *testing.T) {
 	}
 }
 
+func TestStructuredRunConstructsCommandWithoutSchemaFlags(t *testing.T) {
+	commands := &fakeCommands{result: CommandResult{
+		Stdout:          []byte(`{"summary":"ok"}`),
+		Stderr:          []byte("wrote generated text"),
+		StdoutTruncated: true,
+	}}
+	runner := Runner{
+		Binary:     "/usr/local/bin/scriptorium",
+		ConfigPath: "/etc/scriptorium.yml",
+		Profile:    "weather",
+		Timeout:    30 * time.Second,
+		Commands:   commands,
+	}
+
+	result, err := runner.StructuredRun(context.Background(), StructuredRunRequest{
+		PromptID:        "weather.hourly_generated_text",
+		DataPackagePath: "/tmp/data_package.hourly.yaml",
+		OutputPath:      "/tmp/generated_text_raw.hourly.json",
+	})
+	if err != nil {
+		t.Fatalf("StructuredRun() error = %v", err)
+	}
+
+	wantArgs := []string{
+		"run",
+		"--config", "/etc/scriptorium.yml",
+		"--profile", "weather",
+		"--prompt", "weather.hourly_generated_text",
+		"--input", "data_package=/tmp/data_package.hourly.yaml",
+		"--out", "/tmp/generated_text_raw.hourly.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)
+	}
+	for _, disallowed := range []string{"--format", "--schema", "--schema-path", "--json-schema"} {
+		if containsArg(commands.args, disallowed) {
+			t.Fatalf("args = %#v, should not include %q", commands.args, disallowed)
+		}
+	}
+	if commands.timeout != 30*time.Second {
+		t.Fatalf("timeout = %s, want 30s", 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.Stdout != `{"summary":"ok"}` || result.Stderr != "wrote generated text" || !result.StdoutTruncated {
+		t.Fatalf("result = %#v, want captured output and truncation flags", result)
+	}
+	if result.OutputPath != "/tmp/generated_text_raw.hourly.json" {
+		t.Fatalf("OutputPath = %q, want generated text raw path", result.OutputPath)
+	}
+}
+
+func TestStructuredRunReturnsResultForNonzeroExit(t *testing.T) {
+	runner := Runner{
+		Commands: &fakeCommands{
+			result: CommandResult{
+				Stdout:   []byte(`{"summary":"partial"}`),
+				Stderr:   []byte("structured output failed"),
+				ExitCode: 3,
+			},
+		},
+	}
+
+	result, err := runner.StructuredRun(context.Background(), StructuredRunRequest{
+		PromptID:        "weather.hourly_generated_text",
+		DataPackagePath: "/tmp/data_package.hourly.yaml",
+		OutputPath:      "/tmp/generated_text_raw.hourly.json",
+	})
+	if err == nil {
+		t.Fatal("StructuredRun() error = nil, want nonzero exit error")
+	}
+	if result == nil {
+		t.Fatal("StructuredRun() result = nil, want captured result")
+	}
+	if result.ExitCode != 3 {
+		t.Fatalf("ExitCode = %d, want 3", result.ExitCode)
+	}
+	if result.Stdout != `{"summary":"partial"}` || result.OutputPath != "/tmp/generated_text_raw.hourly.json" {
+		t.Fatalf("result = %#v, want captured result fields", result)
+	}
+	if !strings.Contains(err.Error(), "structured output failed") {
+		t.Fatalf("error = %q, want stderr context", err.Error())
+	}
+}
+
+func TestOutputRunsPreserveCapturedResultFields(t *testing.T) {
+	type commonResult struct {
+		Command         []string
+		Stdout          string
+		Stderr          string
+		StdoutTruncated bool
+		StderrTruncated bool
+		ExitCode        int
+		OutputPath      string
+	}
+	tests := []struct {
+		name string
+		run  func(Runner) (*commonResult, error)
+	}{
+		{
+			name: "Run",
+			run: func(runner Runner) (*commonResult, error) {
+				result, err := runner.Run(context.Background(), RunRequest{
+					PromptID:        "weather.markdown_report",
+					DataPackagePath: "/tmp/data_package.yaml",
+					OutputPath:      "/tmp/report.md",
+				})
+				if result == nil {
+					return nil, err
+				}
+				return &commonResult{
+					Command:         result.Command,
+					Stdout:          result.Stdout,
+					Stderr:          result.Stderr,
+					StdoutTruncated: result.StdoutTruncated,
+					StderrTruncated: result.StderrTruncated,
+					ExitCode:        result.ExitCode,
+					OutputPath:      result.OutputPath,
+				}, err
+			},
+		},
+		{
+			name: "StructuredRun",
+			run: func(runner Runner) (*commonResult, error) {
+				result, err := runner.StructuredRun(context.Background(), StructuredRunRequest{
+					PromptID:        "weather.markdown_report",
+					DataPackagePath: "/tmp/data_package.yaml",
+					OutputPath:      "/tmp/report.md",
+				})
+				if result == nil {
+					return nil, err
+				}
+				return &commonResult{
+					Command:         result.Command,
+					Stdout:          result.Stdout,
+					Stderr:          result.Stderr,
+					StdoutTruncated: result.StdoutTruncated,
+					StderrTruncated: result.StderrTruncated,
+					ExitCode:        result.ExitCode,
+					OutputPath:      result.OutputPath,
+				}, err
+			},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			commands := &fakeCommands{result: CommandResult{
+				Stdout:          []byte("captured stdout"),
+				Stderr:          []byte("captured stderr"),
+				StdoutTruncated: true,
+				StderrTruncated: true,
+			}}
+			runner := Runner{
+				Binary:     "/usr/local/bin/scriptorium",
+				ConfigPath: "/etc/scriptorium.yml",
+				Profile:    "weather",
+				Timeout:    15 * time.Second,
+				Commands:   commands,
+			}
+
+			result, err := test.run(runner)
+			if err != nil {
+				t.Fatalf("%s error = %v", test.name, err)
+			}
+			wantArgs := []string{
+				"run",
+				"--config", "/etc/scriptorium.yml",
+				"--profile", "weather",
+				"--prompt", "weather.markdown_report",
+				"--input", "data_package=/tmp/data_package.yaml",
+				"--out", "/tmp/report.md",
+			}
+			if !reflect.DeepEqual(commands.args, wantArgs) {
+				t.Fatalf("args = %#v, want %#v", commands.args, wantArgs)
+			}
+			if commands.timeout != 15*time.Second {
+				t.Fatalf("timeout = %s, want 15s", commands.timeout)
+			}
+			if !reflect.DeepEqual(result.Command, append([]string{"/usr/local/bin/scriptorium"}, wantArgs...)) {
+				t.Fatalf("Command = %#v, want full argv", result.Command)
+			}
+			if result.Stdout != "captured stdout" || result.Stderr != "captured stderr" {
+				t.Fatalf("captured output = %q/%q, want stdout/stderr", result.Stdout, result.Stderr)
+			}
+			if !result.StdoutTruncated || !result.StderrTruncated {
+				t.Fatalf("truncation flags = %t/%t, want both true", result.StdoutTruncated, result.StderrTruncated)
+			}
+			if result.ExitCode != 0 || result.OutputPath != "/tmp/report.md" {
+				t.Fatalf("result = %#v, want exit 0 and output path", result)
+			}
+		})
+	}
+}
+
+func TestOutputRunsReturnCapturedResultForNonzeroExit(t *testing.T) {
+	type commonResult struct {
+		Stdout          string
+		Stderr          string
+		StderrTruncated bool
+		ExitCode        int
+		OutputPath      string
+	}
+	tests := []struct {
+		name    string
+		run     func(Runner) (*commonResult, error)
+		wantErr string
+	}{
+		{
+			name: "Run",
+			run: func(runner Runner) (*commonResult, error) {
+				result, err := runner.Run(context.Background(), RunRequest{
+					PromptID:        "weather.markdown_report",
+					DataPackagePath: "/tmp/data_package.yaml",
+					OutputPath:      "/tmp/report.md",
+				})
+				if result == nil {
+					return nil, err
+				}
+				return &commonResult{
+					Stdout:          result.Stdout,
+					Stderr:          result.Stderr,
+					StderrTruncated: result.StderrTruncated,
+					ExitCode:        result.ExitCode,
+					OutputPath:      result.OutputPath,
+				}, err
+			},
+			wantErr: "scriptorium run exited with code 7: captured stderr",
+		},
+		{
+			name: "StructuredRun",
+			run: func(runner Runner) (*commonResult, error) {
+				result, err := runner.StructuredRun(context.Background(), StructuredRunRequest{
+					PromptID:        "weather.markdown_report",
+					DataPackagePath: "/tmp/data_package.yaml",
+					OutputPath:      "/tmp/report.md",
+				})
+				if result == nil {
+					return nil, err
+				}
+				return &commonResult{
+					Stdout:          result.Stdout,
+					Stderr:          result.Stderr,
+					StderrTruncated: result.StderrTruncated,
+					ExitCode:        result.ExitCode,
+					OutputPath:      result.OutputPath,
+				}, err
+			},
+			wantErr: "scriptorium structured run exited with code 7: captured stderr",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			runner := Runner{
+				Commands: &fakeCommands{result: CommandResult{
+					Stdout:          []byte("captured stdout"),
+					Stderr:          []byte("captured stderr"),
+					StderrTruncated: true,
+					ExitCode:        7,
+				}},
+			}
+
+			result, err := test.run(runner)
+			if err == nil {
+				t.Fatalf("%s error = nil, want nonzero exit error", test.name)
+			}
+			if result == nil {
+				t.Fatalf("%s result = nil, want captured result", test.name)
+			}
+			if err.Error() != test.wantErr {
+				t.Fatalf("%s error = %q, want %q", test.name, err.Error(), test.wantErr)
+			}
+			if result.Stdout != "captured stdout" || result.Stderr != "captured stderr" || !result.StderrTruncated {
+				t.Fatalf("captured result = %#v, want stdout/stderr/truncation", result)
+			}
+			if result.ExitCode != 7 || result.OutputPath != "/tmp/report.md" {
+				t.Fatalf("result = %#v, want exit 7 and output path", result)
+			}
+		})
+	}
+}
+
+func TestOutputRunsValidateRequiredFieldsBeforeExecution(t *testing.T) {
+	tests := []struct {
+		name string
+		run  func(Runner, string, string, string) error
+	}{
+		{
+			name: "Run",
+			run: func(runner Runner, promptID string, dataPackagePath string, outputPath string) error {
+				result, err := runner.Run(context.Background(), RunRequest{
+					PromptID:        promptID,
+					DataPackagePath: dataPackagePath,
+					OutputPath:      outputPath,
+				})
+				if result != nil {
+					return fmt.Errorf("result = %#v, want nil", result)
+				}
+				return err
+			},
+		},
+		{
+			name: "StructuredRun",
+			run: func(runner Runner, promptID string, dataPackagePath string, outputPath string) error {
+				result, err := runner.StructuredRun(context.Background(), StructuredRunRequest{
+					PromptID:        promptID,
+					DataPackagePath: dataPackagePath,
+					OutputPath:      outputPath,
+				})
+				if result != nil {
+					return fmt.Errorf("result = %#v, want nil", result)
+				}
+				return err
+			},
+		},
+	}
+	cases := []struct {
+		name            string
+		promptID        string
+		dataPackagePath string
+		outputPath      string
+		want            string
+	}{
+		{
+			name:            "prompt id",
+			dataPackagePath: "/tmp/data_package.yaml",
+			outputPath:      "/tmp/report.md",
+			want:            "prompt id is required",
+		},
+		{
+			name:       "data package path",
+			promptID:   "weather.markdown_report",
+			outputPath: "/tmp/report.md",
+			want:       "data package path is required",
+		},
+		{
+			name:            "output path",
+			promptID:        "weather.markdown_report",
+			dataPackagePath: "/tmp/data_package.yaml",
+			want:            "output path is required",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			for _, tc := range cases {
+				t.Run(tc.name, func(t *testing.T) {
+					commands := &fakeCommands{}
+					err := test.run(Runner{Commands: commands}, tc.promptID, tc.dataPackagePath, tc.outputPath)
+					if err == nil {
+						t.Fatalf("%s error = nil, want validation error", test.name)
+					}
+					if !strings.Contains(err.Error(), tc.want) {
+						t.Fatalf("%s error = %v, want %q", test.name, err, tc.want)
+					}
+					if commands.calls != 0 {
+						t.Fatalf("commands calls = %d, want no subprocess execution", commands.calls)
+					}
+				})
+			}
+		})
+	}
+}
+
 type fakeCommands struct {
 	name    string
 	args    []string
 	timeout time.Duration
 	result  CommandResult
 	err     error
+	calls   int
 }
 
 func (f *fakeCommands) Run(_ context.Context, name string, args []string, timeout time.Duration) (CommandResult, error) {
+	f.calls++
 	f.name = name
 	f.args = append([]string{}, args...)
 	f.timeout = timeout
 	return f.result, f.err
 }
+
+func containsArg(args []string, want string) bool {
+	for _, arg := range args {
+		if arg == want {
+			return true
+		}
+	}
+	return false
+}

internal/adapters/weatherapi/client.go

@@ -21,6 +21,17 @@ import (
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
 )
 
+const (
+	convectiveOutlooksEndpoint  = "/outlooks/convective"
+	sourceSPCConvectiveOutlooks = "spc_convective_outlooks"
+
+	defaultWarmupEndpoint  = "/conditions/current"
+	defaultWarmupAttempts  = 3
+	defaultWarmupDelay     = time.Second
+	defaultFetchAttempts   = 2
+	defaultFetchRetryDelay = time.Second
+)
+
 type Client struct {
 	baseURL       *url.URL
 	httpClient    *http.Client
@@ -30,6 +41,12 @@ type Client struct {
 	precision     int
 	missingSource config.MissingSourceConfig
 	now           func() time.Time
+
+	warmupEndpoint  string
+	warmupAttempts  int
+	warmupDelay     time.Duration
+	fetchAttempts   int
+	fetchRetryDelay time.Duration
 }
 
 type Option func(*Client)
@@ -75,7 +92,12 @@ func New(cfg config.Config, opts ...Option) (*Client, error) {
 			Default: cfg.MissingSource.Default,
 			Sources: cfg.MissingSource.Sources,
 		},
-		now: time.Now,
+		now:             time.Now,
+		warmupEndpoint:  defaultWarmupEndpoint,
+		warmupAttempts:  defaultWarmupAttempts,
+		warmupDelay:     defaultWarmupDelay,
+		fetchAttempts:   defaultFetchAttempts,
+		fetchRetryDelay: defaultFetchRetryDelay,
 	}
 	for _, opt := range opts {
 		opt(client)
@@ -84,6 +106,10 @@ func New(cfg config.Config, opts ...Option) (*Client, error) {
 }
 
 func (c *Client) FetchBundle(ctx context.Context) (*weatherdata.Bundle, error) {
+	if err := c.warmup(ctx); err != nil {
+		return nil, err
+	}
+
 	fetchedAt := c.now()
 	builder := bundleBuilder{
 		client:    c,
@@ -112,6 +138,9 @@ func (c *Client) FetchBundle(ctx context.Context) (*weatherdata.Bundle, error) {
 	if err := builder.fetchWeatherStory(ctx); err != nil {
 		return nil, err
 	}
+	if err := builder.fetchSPCConvectiveOutlooks(ctx); err != nil {
+		return nil, err
+	}
 
 	return builder.bundle, nil
 }
@@ -122,18 +151,32 @@ type bundleBuilder struct {
 	fetchedAt time.Time
 }
 
+type sourceRequest struct {
+	name           string
+	endpoint       string
+	query          queryOptions
+	missingMessage string
+	required       bool
+	decodeLabel    string
+}
+
+type fetchedSource struct {
+	raw    json.RawMessage
+	source weatherdata.Source
+}
+
 func (b *bundleBuilder) fetchObservation(ctx context.Context) error {
-	raw, source, err := b.client.fetch(ctx, "observations", "/observations", queryOptions{precision: true})
-	if err != nil {
+	var observation weatherdata.Observation
+	fetched, ok, err := b.fetchDecodedSource(ctx, sourceRequest{
+		name:           "observations",
+		endpoint:       "/observations",
+		query:          queryOptions{precision: true},
+		missingMessage: "observation data is missing",
+	}, &observation)
+	if err != nil || !ok {
 		return err
 	}
-	if raw == nil {
-		return b.handleMissing(&source, "observation data is missing", false)
-	}
-	var observation weatherdata.Observation
-	if err := decodeSource(raw, &observation); err != nil {
-		return b.handleMalformed(&source, err, false)
-	}
+	source := fetched.source
 	source.IssuedAt = &observation.Timestamp
 	b.bundle.Observation = &observation
 	b.addSource(source)
@@ -141,34 +184,36 @@ func (b *bundleBuilder) fetchObservation(ctx context.Context) error {
 }
 
 func (b *bundleBuilder) fetchCurrent(ctx context.Context) error {
-	raw, source, err := b.client.fetch(ctx, "current", "/conditions/current", queryOptions{precision: true})
-	if err != nil {
+	var current weatherdata.Current
+	fetched, ok, err := b.fetchDecodedSource(ctx, sourceRequest{
+		name:           "current",
+		endpoint:       "/conditions/current",
+		query:          queryOptions{precision: true},
+		missingMessage: "current conditions data is missing",
+	}, &current)
+	if err != nil || !ok {
 		return err
 	}
-	if raw == nil {
-		return b.handleMissing(&source, "current conditions data is missing", false)
-	}
-	var current weatherdata.Current
-	if err := decodeSource(raw, &current); err != nil {
-		return b.handleMalformed(&source, err, false)
-	}
+	source := fetched.source
 	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 {
+	var hourly weatherdata.ForecastRun
+	fetched, ok, err := b.fetchDecodedSource(ctx, sourceRequest{
+		name:           "hourly",
+		endpoint:       "/forecast/hourly",
+		query:          queryOptions{precision: true, timezone: true},
+		missingMessage: "hourly forecast data is missing",
+		required:       true,
+		decodeLabel:    "hourly forecast",
+	}, &hourly)
+	if err != nil || !ok {
 		return err
 	}
-	if raw == nil {
-		return b.handleMissing(&source, "hourly forecast data is missing", true)
-	}
-	var hourly weatherdata.ForecastRun
-	if err := decodeSource(raw, &hourly); err != nil {
-		return fmt.Errorf("decode hourly forecast from %s: %w", source.Endpoint, err)
-	}
+	source := fetched.source
 	if len(hourly.Periods) == 0 {
 		return fmt.Errorf("hourly forecast from %s contains no periods", source.Endpoint)
 	}
@@ -180,17 +225,17 @@ func (b *bundleBuilder) fetchHourly(ctx context.Context) error {
 }
 
 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 {
+	var narrative weatherdata.ForecastRun
+	fetched, ok, err := b.fetchDecodedSource(ctx, sourceRequest{
+		name:           "narrative",
+		endpoint:       "/forecast/narrative",
+		query:          queryOptions{precision: true, timezone: true},
+		missingMessage: "narrative forecast data is missing",
+	}, &narrative)
+	if err != nil || !ok {
 		return err
 	}
-	if raw == nil {
-		return b.handleMissing(&source, "narrative forecast data is missing", false)
-	}
-	var narrative weatherdata.ForecastRun
-	if err := decodeSource(raw, &narrative); err != nil {
-		return b.handleMalformed(&source, err, false)
-	}
+	source := fetched.source
 	source.IssuedAt = &narrative.IssuedAt
 	source.UpdatedAt = narrative.UpdatedAt
 	b.bundle.Narrative = &narrative
@@ -213,7 +258,7 @@ func (b *bundleBuilder) fetchAlerts(ctx context.Context) error {
 	}
 	var alerts weatherdata.AlertRun
 	if err := decodeSource(raw, &alerts); err != nil {
-		return b.handleMalformed(&source, err, false)
+		return b.handleMalformed(&source, err, sourceRequest{name: "alerts"})
 	}
 	alerts.Raw = append(json.RawMessage(nil), raw...)
 	if alerts.AsOf != nil {
@@ -225,17 +270,17 @@ func (b *bundleBuilder) fetchAlerts(ctx context.Context) error {
 }
 
 func (b *bundleBuilder) fetchDiscussion(ctx context.Context) error {
-	raw, source, err := b.client.fetch(ctx, "discussion", "/discussion", queryOptions{timezone: true})
-	if err != nil {
+	var discussion weatherdata.Discussion
+	fetched, ok, err := b.fetchDecodedSource(ctx, sourceRequest{
+		name:           "discussion",
+		endpoint:       "/discussion",
+		query:          queryOptions{timezone: true},
+		missingMessage: "forecast discussion data is missing",
+	}, &discussion)
+	if err != nil || !ok {
 		return err
 	}
-	if raw == nil {
-		return b.handleMissing(&source, "forecast discussion data is missing", false)
-	}
-	var discussion weatherdata.Discussion
-	if err := decodeSource(raw, &discussion); err != nil {
-		return b.handleMalformed(&source, err, false)
-	}
+	source := fetched.source
 	source.IssuedAt = &discussion.IssuedAt
 	source.UpdatedAt = discussion.UpdatedAt
 	b.bundle.Discussion = &discussion
@@ -244,17 +289,17 @@ func (b *bundleBuilder) fetchDiscussion(ctx context.Context) error {
 }
 
 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 {
+	var story weatherdata.WeatherStory
+	fetched, ok, err := b.fetchDecodedSource(ctx, sourceRequest{
+		name:           "weather_story",
+		endpoint:       "/weatherstories/latest",
+		query:          queryOptions{omitUnits: true},
+		missingMessage: "NWS weather story data is missing",
+	}, &story)
+	if err != nil || !ok {
 		return err
 	}
-	if raw == nil {
-		return b.handleMissing(&source, "NWS weather story data is missing", false)
-	}
-	var story weatherdata.WeatherStory
-	if err := decodeSource(raw, &story); err != nil {
-		return b.handleMalformed(&source, err, false)
-	}
+	source := fetched.source
 	if !story.StartTime.IsZero() {
 		source.IssuedAt = &story.StartTime
 	}
@@ -264,6 +309,51 @@ func (b *bundleBuilder) fetchWeatherStory(ctx context.Context) error {
 	return nil
 }
 
+func (b *bundleBuilder) fetchSPCConvectiveOutlooks(ctx context.Context) error {
+	var run weatherdata.ConvectiveOutlookRun
+	fetched, ok, err := b.fetchDecodedSource(ctx, sourceRequest{
+		name:           sourceSPCConvectiveOutlooks,
+		endpoint:       convectiveOutlooksEndpoint,
+		query:          queryOptions{timezone: true, omitUnits: true},
+		missingMessage: "SPC convective outlook data is missing",
+	}, &run)
+	if err != nil || !ok {
+		return err
+	}
+	source := fetched.source
+	if run.IssuedAt != nil {
+		source.IssuedAt = run.IssuedAt
+	} else {
+		source.IssuedAt = run.AsOf
+	}
+	source.UpdatedAt = run.UpdatedAt
+	b.bundle.SPCConvectiveOutlooks = &run
+	b.addSource(source)
+	return nil
+}
+
+func (b *bundleBuilder) fetchDecodedSource(ctx context.Context, request sourceRequest, target any) (fetchedSource, bool, error) {
+	fetched, ok, err := b.fetchSource(ctx, request)
+	if err != nil || !ok {
+		return fetchedSource{}, false, err
+	}
+	if err := decodeSource(fetched.raw, target); err != nil {
+		return fetchedSource{}, false, b.handleMalformed(&fetched.source, err, request)
+	}
+	return fetched, true, nil
+}
+
+func (b *bundleBuilder) fetchSource(ctx context.Context, request sourceRequest) (fetchedSource, bool, error) {
+	raw, source, err := b.client.fetch(ctx, request.name, request.endpoint, request.query)
+	if err != nil {
+		return fetchedSource{}, false, err
+	}
+	if raw == nil {
+		return fetchedSource{}, false, b.handleMissing(&source, request.missingMessage, request.required)
+	}
+	return fetchedSource{raw: raw, source: source}, true, nil
+}
+
 func (b *bundleBuilder) handleMissing(source *weatherdata.Source, message string, required bool) error {
 	source.Missing = true
 	if required {
@@ -272,9 +362,13 @@ func (b *bundleBuilder) handleMissing(source *weatherdata.Source, message string
 	return b.applyMissingPolicy(source, "missing_source", message)
 }
 
-func (b *bundleBuilder) handleMalformed(source *weatherdata.Source, err error, required bool) error {
-	if required {
-		return fmt.Errorf("decode %s from %s: %w", source.Name, source.Endpoint, err)
+func (b *bundleBuilder) handleMalformed(source *weatherdata.Source, err error, request sourceRequest) error {
+	if request.required {
+		label := request.name
+		if request.decodeLabel != "" {
+			label = request.decodeLabel
+		}
+		return fmt.Errorf("decode %s from %s: %w", label, source.Endpoint, err)
 	}
 	source.Missing = true
 	return b.applyMissingPolicy(source, "malformed_source", fmt.Sprintf("malformed %s data: %v", source.Name, err))
@@ -324,24 +418,9 @@ type envelope struct {
 }
 
 func (c *Client) fetch(ctx context.Context, sourceName string, endpoint string, opts queryOptions) (json.RawMessage, weatherdata.Source, error) {
-	reqURL := c.endpointURL(endpoint, opts)
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, reqURL.String(), nil)
+	reqURL, body, err := c.fetchHTTP(ctx, endpoint, opts)
 	if err != nil {
-		return nil, weatherdata.Source{}, fmt.Errorf("create request for %s: %w", endpoint, err)
-	}
-
-	resp, err := c.httpClient.Do(req)
-	if err != nil {
-		return nil, weatherdata.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, weatherdata.Source{}, fmt.Errorf("read %s response: %w", endpoint, err)
-	}
-	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		return nil, weatherdata.Source{}, fmt.Errorf("fetch %s: unexpected HTTP status %d: %s", endpoint, resp.StatusCode, strings.TrimSpace(string(body)))
+		return nil, weatherdata.Source{}, err
 	}
 
 	var env envelope
@@ -367,6 +446,169 @@ func (c *Client) fetch(ctx context.Context, sourceName string, endpoint string,
 	return env.Data, source, nil
 }
 
+func (c *Client) warmup(ctx context.Context) error {
+	endpoint := c.warmupEndpoint
+	if strings.TrimSpace(endpoint) == "" {
+		endpoint = defaultWarmupEndpoint
+	}
+	attempts := positiveAttemptCount(c.warmupAttempts)
+	var lastErr error
+	for attempt := 1; attempt <= attempts; attempt++ {
+		if err := ctx.Err(); err != nil {
+			return fmt.Errorf("warm up weather API via %s: %w", endpoint, err)
+		}
+		if err := c.warmupOnce(ctx, endpoint); err != nil {
+			lastErr = err
+		} else {
+			return nil
+		}
+		if attempt == attempts {
+			break
+		}
+		if err := waitForRetry(ctx, c.warmupDelay); err != nil {
+			return fmt.Errorf("warm up weather API via %s after %d attempt(s): %w", endpoint, attempt, err)
+		}
+	}
+	return fmt.Errorf("warm up weather API via %s failed after %d attempts: %w", endpoint, attempts, lastErr)
+}
+
+func (c *Client) warmupOnce(ctx context.Context, endpoint string) error {
+	reqURL := c.endpointURL(endpoint, queryOptions{precision: true})
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, reqURL.String(), nil)
+	if err != nil {
+		return fmt.Errorf("create request for %s: %w", endpoint, err)
+	}
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return 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 fmt.Errorf("read %s response: %w", endpoint, err)
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("fetch %s: unexpected HTTP status %d: %s", endpoint, resp.StatusCode, strings.TrimSpace(string(body)))
+	}
+	return nil
+}
+
+func (c *Client) fetchHTTP(ctx context.Context, endpoint string, opts queryOptions) (*url.URL, []byte, error) {
+	attempts := positiveAttemptCount(c.fetchAttempts)
+	var lastErr error
+	var lastRetryable bool
+	for attempt := 1; attempt <= attempts; attempt++ {
+		if err := ctx.Err(); err != nil {
+			return nil, nil, fmt.Errorf("fetch %s: %w", endpoint, err)
+		}
+		reqURL, body, err := c.fetchHTTPOnce(ctx, endpoint, opts)
+		if err == nil {
+			return reqURL, body, nil
+		}
+		lastErr = err
+		lastRetryable = isRetryableRequestError(err)
+		if !lastRetryable || attempt == attempts {
+			break
+		}
+		if err := waitForRetry(ctx, c.fetchRetryDelay); err != nil {
+			return nil, nil, fmt.Errorf("fetch %s retry delay after attempt %d: %w", endpoint, attempt, err)
+		}
+	}
+	if lastRetryable {
+		return nil, nil, fmt.Errorf("fetch %s failed after %d attempts: %w", endpoint, attempts, lastErr)
+	}
+	return nil, nil, lastErr
+}
+
+func (c *Client) fetchHTTPOnce(ctx context.Context, endpoint string, opts queryOptions) (*url.URL, []byte, error) {
+	reqURL := c.endpointURL(endpoint, opts)
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, reqURL.String(), nil)
+	if err != nil {
+		return nil, nil, fmt.Errorf("create request for %s: %w", endpoint, err)
+	}
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		err = fmt.Errorf("fetch %s: %w", endpoint, err)
+		if ctx.Err() != nil {
+			return reqURL, nil, err
+		}
+		return reqURL, nil, retryableRequestError{err: err}
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 10<<20))
+	if err != nil {
+		err = fmt.Errorf("read %s response: %w", endpoint, err)
+		if ctx.Err() != nil {
+			return reqURL, nil, err
+		}
+		return reqURL, nil, retryableRequestError{err: err}
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		err := fmt.Errorf("fetch %s: unexpected HTTP status %d: %s", endpoint, resp.StatusCode, strings.TrimSpace(string(body)))
+		if isRetryableHTTPStatus(resp.StatusCode) {
+			return reqURL, nil, retryableRequestError{err: err}
+		}
+		return reqURL, nil, err
+	}
+	return reqURL, body, nil
+}
+
+type retryableRequestError struct {
+	err error
+}
+
+func (e retryableRequestError) Error() string {
+	return e.err.Error()
+}
+
+func (e retryableRequestError) Unwrap() error {
+	return e.err
+}
+
+func isRetryableRequestError(err error) bool {
+	_, ok := err.(retryableRequestError)
+	return ok
+}
+
+func isRetryableHTTPStatus(status int) bool {
+	switch status {
+	case http.StatusRequestTimeout,
+		http.StatusTooManyRequests,
+		http.StatusInternalServerError,
+		http.StatusBadGateway,
+		http.StatusServiceUnavailable,
+		http.StatusGatewayTimeout:
+		return true
+	default:
+		return false
+	}
+}
+
+func waitForRetry(ctx context.Context, delay time.Duration) error {
+	if delay <= 0 {
+		return ctx.Err()
+	}
+	timer := time.NewTimer(delay)
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}
+
+func positiveAttemptCount(attempts int) int {
+	if attempts < 1 {
+		return 1
+	}
+	return attempts
+}
+
 func isJSONNull(raw json.RawMessage) bool {
 	return bytes.Equal(bytes.TrimSpace(raw), []byte("null"))
 }

internal/adapters/weatherapi/client_test.go

@@ -55,12 +55,42 @@ func TestFetchBundleFromFixtures(t *testing.T) {
 	if bundle.WeatherStory.UpdatedAt == nil {
 		t.Fatalf("WeatherStory.UpdatedAt = nil, want update timestamp")
 	}
-	if len(bundle.Sources) != 7 {
-		t.Fatalf("Sources length = %d, want 7", len(bundle.Sources))
+	if bundle.SPCConvectiveOutlooks == nil || len(bundle.SPCConvectiveOutlooks.Outlooks) != 1 {
+		t.Fatalf("SPCConvectiveOutlooks = %#v, want one outlook", bundle.SPCConvectiveOutlooks)
+	}
+	if len(bundle.SPCConvectiveOutlooks.Outlooks[0].Geometry) == 0 {
+		t.Fatalf("SPCConvectiveOutlooks.Outlooks[0].Geometry is empty, want GeoJSON")
+	}
+	if len(bundle.SPCConvectiveOutlooks.Discussions) != 1 || bundle.SPCConvectiveOutlooks.Discussions[0].Headline != "Severe storms possible" {
+		t.Fatalf("SPCConvectiveOutlooks.Discussions = %#v, want one discussion", bundle.SPCConvectiveOutlooks.Discussions)
+	}
+	if len(bundle.Sources) != 8 {
+		t.Fatalf("Sources length = %d, want 8", len(bundle.Sources))
 	}
 	if len(bundle.Warnings) != 0 {
 		t.Fatalf("Warnings length = %d, want no warnings", len(bundle.Warnings))
 	}
+	wantPaths := []string{
+		"/observations",
+		"/conditions/current",
+		"/forecast/hourly",
+		"/forecast/narrative",
+		"/alerts/active",
+		"/discussion",
+		"/weatherstories/latest",
+		convectiveOutlooksEndpoint,
+	}
+	if len(requested) != len(wantPaths)+1 {
+		t.Fatalf("requested paths = %v, want warmup plus %d source endpoints", requested, len(wantPaths))
+	}
+	if !strings.HasPrefix(requested[0], defaultWarmupEndpoint+"?") && requested[0] != defaultWarmupEndpoint {
+		t.Fatalf("first requested path = %q, want warmup endpoint %s", requested[0], defaultWarmupEndpoint)
+	}
+	for _, want := range wantPaths {
+		if !containsPath(requested, want) {
+			t.Fatalf("requested paths = %v, want %s", requested, want)
+		}
+	}
 	if !containsPath(requested, "/forecast/hourly") || containsPath(requested, "/forecast/hourly/today") {
 		t.Fatalf("requested paths = %v, want full hourly endpoint only", requested)
 	}
@@ -70,6 +100,9 @@ func TestFetchBundleFromFixtures(t *testing.T) {
 	if !containsPath(requested, "/weatherstories/latest") {
 		t.Fatalf("requested paths = %v, want weather story endpoint", requested)
 	}
+	if !containsPath(requested, convectiveOutlooksEndpoint) {
+		t.Fatalf("requested paths = %v, want convective outlook endpoint", requested)
+	}
 }
 
 func TestFetchBundleBuildsExpectedQueries(t *testing.T) {
@@ -92,13 +125,25 @@ func TestFetchBundleBuildsExpectedQueries(t *testing.T) {
 			}
 			continue
 		}
+		if strings.HasPrefix(rawURL, convectiveOutlooksEndpoint) {
+			if strings.Contains(rawURL, "units=") || strings.Contains(rawURL, "precision=") || !strings.Contains(rawURL, "tz=America%2FChicago") {
+				t.Fatalf("convective outlook request %q should use format and tz 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") {
+			if !strings.Contains(rawURL, "precision=0") || !strings.Contains(rawURL, "tz=America%2FChicago") {
 				t.Fatalf("forecast request %q missing precision or tz", rawURL)
 			}
+			continue
+		}
+		if rawURL == defaultWarmupEndpoint || strings.HasPrefix(rawURL, defaultWarmupEndpoint+"?") || strings.HasPrefix(rawURL, "/observations?") {
+			if !strings.Contains(rawURL, "precision=0") {
+				t.Fatalf("request %q missing precision=0", rawURL)
+			}
 		}
 	}
 }
@@ -127,11 +172,30 @@ func TestFetchBundleRecordsSourceHash(t *testing.T) {
 	if story.IssuedAt == nil || story.UpdatedAt == nil {
 		t.Fatalf("weather story source timestamps = issued %#v updated %#v, want both", story.IssuedAt, story.UpdatedAt)
 	}
+	outlooks := sourceByName(t, bundle.Sources, sourceSPCConvectiveOutlooks)
+	if outlooks.Endpoint != convectiveOutlooksEndpoint {
+		t.Fatalf("convective outlook endpoint = %q, want %s", outlooks.Endpoint, convectiveOutlooksEndpoint)
+	}
+	if outlooks.Query["format"] != "json" || outlooks.Query["tz"] != "America/Chicago" || outlooks.Query["units"] != "" || outlooks.Query["precision"] != "" {
+		t.Fatalf("convective outlook query = %#v, want format and tz only", outlooks.Query)
+	}
+	if outlooks.DataSHA256 != hashFixtureData(t, "convective_outlooks.json") {
+		t.Fatalf("convective outlook DataSHA256 = %q, want fixture hash", outlooks.DataSHA256)
+	}
+	if outlooks.Missing {
+		t.Fatal("convective outlook source Missing = true, want false")
+	}
+	if outlooks.IssuedAt == nil || outlooks.IssuedAt.Format(time.RFC3339) != "2026-05-29T15:45:00Z" {
+		t.Fatalf("convective outlook IssuedAt = %#v, want run issuedAt", outlooks.IssuedAt)
+	}
+	if outlooks.UpdatedAt == nil || outlooks.UpdatedAt.Format(time.RFC3339) != "2026-05-29T16:05:00Z" {
+		t.Fatalf("convective outlook UpdatedAt = %#v, want run updatedAt", outlooks.UpdatedAt)
+	}
 }
 
 func TestHTTPErrorIsActionable(t *testing.T) {
 	server := fixtureServer(t, map[string]handlerOverride{
-		"/conditions/current": {status: http.StatusBadGateway, body: `upstream failed`},
+		"/forecast/hourly": {status: http.StatusBadGateway, body: `upstream failed`},
 	}, nil)
 	client := newTestClient(t, server.URL+"/", nil)
 
@@ -139,15 +203,140 @@ func TestHTTPErrorIsActionable(t *testing.T) {
 	if err == nil {
 		t.Fatal("FetchBundle() error = nil, want HTTP error")
 	}
-	if !strings.Contains(err.Error(), "/conditions/current") || !strings.Contains(err.Error(), "502") {
+	if !strings.Contains(err.Error(), "/forecast/hourly") || !strings.Contains(err.Error(), "502") {
 		t.Fatalf("error = %q, want endpoint and status", err.Error())
 	}
 }
 
+func TestWarmupRetriesBeforeFetchBundle(t *testing.T) {
+	var requested []string
+	var warmupCalls int
+	server := fixtureServer(t, map[string]handlerOverride{
+		defaultWarmupEndpoint: {handler: func(w http.ResponseWriter, r *http.Request) {
+			warmupCalls++
+			if warmupCalls == 1 {
+				w.WriteHeader(http.StatusBadGateway)
+				_, _ = w.Write([]byte("vpn waking up"))
+				return
+			}
+			http.ServeFile(w, r, filepath.Join("testdata", "current.json"))
+		}},
+	}, &requested)
+	client := newTestClient(t, server.URL+"/", nil)
+
+	bundle, err := client.FetchBundle(context.Background())
+	if err != nil {
+		t.Fatalf("FetchBundle() error = %v", err)
+	}
+	if bundle.Current == nil {
+		t.Fatal("Current = nil, want successful fetch after warmup retry")
+	}
+	if warmupCalls != 3 {
+		t.Fatalf("conditions/current calls = %d, want failed warmup, successful warmup, and current source fetch", warmupCalls)
+	}
+	if len(requested) < 2 || !containsPath(requested[:2], defaultWarmupEndpoint) {
+		t.Fatalf("initial requests = %v, want warmup endpoint retries", requested)
+	}
+}
+
+func TestWarmupFailureStopsBeforeSourceFetches(t *testing.T) {
+	var requested []string
+	server := fixtureServer(t, map[string]handlerOverride{
+		defaultWarmupEndpoint: {status: http.StatusBadGateway, body: `vpn unavailable`},
+	}, &requested)
+	client := newTestClient(t, server.URL+"/", nil)
+	client.warmupAttempts = 2
+
+	_, err := client.FetchBundle(context.Background())
+	if err == nil {
+		t.Fatal("FetchBundle() error = nil, want warmup failure")
+	}
+	if !strings.Contains(err.Error(), "warm up weather API") ||
+		!strings.Contains(err.Error(), defaultWarmupEndpoint) ||
+		!strings.Contains(err.Error(), "2 attempts") ||
+		!strings.Contains(err.Error(), "502") {
+		t.Fatalf("error = %q, want warmup endpoint, attempts, and status", err.Error())
+	}
+	if got := countPath(requested, defaultWarmupEndpoint); got != 2 {
+		t.Fatalf("warmup requests = %d, want 2; all requests = %v", got, requested)
+	}
+	if containsPath(requested, "/observations") {
+		t.Fatalf("requested paths = %v, want warmup failure before source fetches", requested)
+	}
+}
+
+func TestFetchRetriesRetryableStatus(t *testing.T) {
+	var hourlyCalls int
+	server := fixtureServer(t, map[string]handlerOverride{
+		"/forecast/hourly": {handler: func(w http.ResponseWriter, r *http.Request) {
+			hourlyCalls++
+			if hourlyCalls == 1 {
+				w.WriteHeader(http.StatusBadGateway)
+				_, _ = w.Write([]byte("temporary upstream failure"))
+				return
+			}
+			http.ServeFile(w, r, filepath.Join("testdata", "hourly.json"))
+		}},
+	}, nil)
+	client := newTestClient(t, server.URL+"/", nil)
+
+	bundle, err := client.FetchBundle(context.Background())
+	if err != nil {
+		t.Fatalf("FetchBundle() error = %v", err)
+	}
+	if bundle.Hourly == nil {
+		t.Fatal("Hourly = nil, want successful fetch after retry")
+	}
+	if hourlyCalls != 2 {
+		t.Fatalf("hourly calls = %d, want 2", hourlyCalls)
+	}
+}
+
+func TestFetchDoesNotRetryNonRetryableStatus(t *testing.T) {
+	var hourlyCalls int
+	server := fixtureServer(t, map[string]handlerOverride{
+		"/forecast/hourly": {handler: func(w http.ResponseWriter, r *http.Request) {
+			hourlyCalls++
+			w.WriteHeader(http.StatusNotFound)
+			_, _ = w.Write([]byte("not found"))
+		}},
+	}, nil)
+	client := newTestClient(t, server.URL+"/", nil)
+
+	_, err := client.FetchBundle(context.Background())
+	if err == nil {
+		t.Fatal("FetchBundle() error = nil, want non-retryable status error")
+	}
+	if hourlyCalls != 1 {
+		t.Fatalf("hourly calls = %d, want no retry", hourlyCalls)
+	}
+}
+
+func TestFetchDoesNotRetryMalformedEnvelope(t *testing.T) {
+	var hourlyCalls int
+	server := fixtureServer(t, map[string]handlerOverride{
+		"/forecast/hourly": {handler: func(w http.ResponseWriter, r *http.Request) {
+			hourlyCalls++
+			w.WriteHeader(http.StatusOK)
+			_, _ = w.Write([]byte(`not-json`))
+		}},
+	}, nil)
+	client := newTestClient(t, server.URL+"/", nil)
+
+	_, err := client.FetchBundle(context.Background())
+	if err == nil {
+		t.Fatal("FetchBundle() error = nil, want envelope decode error")
+	}
+	if hourlyCalls != 1 {
+		t.Fatalf("hourly calls = %d, want no retry", hourlyCalls)
+	}
+}
+
 func TestRequiredHourlyForecast(t *testing.T) {
+	var requested []string
 	server := fixtureServer(t, map[string]handlerOverride{
 		"/forecast/hourly": {status: http.StatusOK, body: `{"data": null}`},
-	}, nil)
+	}, &requested)
 	client := newTestClient(t, server.URL+"/", nil)
 
 	_, err := client.FetchBundle(context.Background())
@@ -157,6 +346,9 @@ func TestRequiredHourlyForecast(t *testing.T) {
 	if !strings.Contains(err.Error(), "hourly forecast data") {
 		t.Fatalf("error = %q, want hourly context", err.Error())
 	}
+	if got := countPath(requested, "/forecast/hourly"); got != 1 {
+		t.Fatalf("hourly requests = %d, want no retry; all requests = %v", got, requested)
+	}
 }
 
 func TestNullAlertsMeansNoActiveAlerts(t *testing.T) {
@@ -189,6 +381,59 @@ func TestNullAlertsMeansNoActiveAlerts(t *testing.T) {
 	}
 }
 
+func TestMissingSPCConvectiveOutlooksUsesPolicy(t *testing.T) {
+	server := fixtureServer(t, map[string]handlerOverride{
+		convectiveOutlooksEndpoint: {status: http.StatusOK, body: `{"data": null}`},
+	}, nil)
+	client := newTestClient(t, server.URL+"/", map[string]config.MissingSourcePolicy{
+		sourceSPCConvectiveOutlooks: config.MissingSourceWarn,
+	})
+
+	bundle, err := client.FetchBundle(context.Background())
+	if err != nil {
+		t.Fatalf("FetchBundle() error = %v", err)
+	}
+	if bundle.SPCConvectiveOutlooks != nil {
+		t.Fatalf("SPCConvectiveOutlooks = %#v, want nil for missing source", bundle.SPCConvectiveOutlooks)
+	}
+	source := sourceByName(t, bundle.Sources, sourceSPCConvectiveOutlooks)
+	if !source.Missing || len(source.Warnings) != 1 {
+		t.Fatalf("convective outlook source = %#v, want missing source warning", source)
+	}
+}
+
+func TestEmptySPCConvectiveOutlooksAreCheckedData(t *testing.T) {
+	server := fixtureServer(t, map[string]handlerOverride{
+		convectiveOutlooksEndpoint: {status: http.StatusOK, body: `{"data":{"asOf":"2026-05-29T16:00:00Z","outlooks":[],"discussions":[]}}`},
+	}, nil)
+	client := newTestClient(t, server.URL+"/", map[string]config.MissingSourcePolicy{
+		sourceSPCConvectiveOutlooks: config.MissingSourceWarn,
+	})
+
+	bundle, err := client.FetchBundle(context.Background())
+	if err != nil {
+		t.Fatalf("FetchBundle() error = %v", err)
+	}
+	if bundle.SPCConvectiveOutlooks == nil {
+		t.Fatal("SPCConvectiveOutlooks = nil, want checked empty run")
+	}
+	if len(bundle.SPCConvectiveOutlooks.Outlooks) != 0 || len(bundle.SPCConvectiveOutlooks.Discussions) != 0 {
+		t.Fatalf("SPCConvectiveOutlooks = %#v, want empty arrays", bundle.SPCConvectiveOutlooks)
+	}
+	source := sourceByName(t, bundle.Sources, sourceSPCConvectiveOutlooks)
+	if source.Missing || len(source.Warnings) != 0 {
+		t.Fatalf("convective outlook source = %#v, want non-missing source without warnings", source)
+	}
+	if source.IssuedAt == nil || source.IssuedAt.Format(time.RFC3339) != "2026-05-29T16:00:00Z" {
+		t.Fatalf("convective outlook IssuedAt = %#v, want fallback to asOf", source.IssuedAt)
+	}
+	for _, warning := range bundle.Warnings {
+		if warning.Source == sourceSPCConvectiveOutlooks {
+			t.Fatalf("warnings = %#v, want no convective outlook warning", bundle.Warnings)
+		}
+	}
+}
+
 func TestMissingSourcePolicyWarnNoneError(t *testing.T) {
 	tests := []struct {
 		name       string
@@ -312,6 +557,43 @@ func TestContextCancellation(t *testing.T) {
 	}
 }
 
+func TestRetryDelayRespectsContextCancellation(t *testing.T) {
+	var cancel context.CancelFunc
+	var hourlyCalls int
+	server := fixtureServer(t, map[string]handlerOverride{
+		"/forecast/hourly": {handler: func(w http.ResponseWriter, r *http.Request) {
+			hourlyCalls++
+			if cancel != nil {
+				cancel()
+			}
+			w.WriteHeader(http.StatusBadGateway)
+			_, _ = w.Write([]byte("temporary upstream failure"))
+		}},
+	}, nil)
+	client := newTestClient(t, server.URL+"/", nil)
+	client.fetchRetryDelay = time.Hour
+
+	ctx, cancelFunc := context.WithCancel(context.Background())
+	cancel = cancelFunc
+	defer cancelFunc()
+
+	start := time.Now()
+	_, err := client.FetchBundle(ctx)
+	elapsed := time.Since(start)
+	if err == nil {
+		t.Fatal("FetchBundle() error = nil, want cancellation during retry delay")
+	}
+	if !strings.Contains(err.Error(), context.Canceled.Error()) {
+		t.Fatalf("error = %q, want context cancellation", err.Error())
+	}
+	if elapsed > time.Second {
+		t.Fatalf("FetchBundle() elapsed = %s, want prompt cancellation", elapsed)
+	}
+	if hourlyCalls != 1 {
+		t.Fatalf("hourly calls = %d, want retry delay cancellation before second attempt", hourlyCalls)
+	}
+}
+
 func TestHTTPTimeout(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		time.Sleep(50 * time.Millisecond)
@@ -324,12 +606,14 @@ func TestHTTPTimeout(t *testing.T) {
 	if err != nil {
 		t.Fatalf("New() error = %v", err)
 	}
+	client.warmupDelay = 0
+	client.fetchRetryDelay = 0
 
 	_, err = client.FetchBundle(context.Background())
 	if err == nil {
 		t.Fatal("FetchBundle() error = nil, want timeout error")
 	}
-	if !strings.Contains(err.Error(), "/observations") {
+	if !strings.Contains(err.Error(), defaultWarmupEndpoint) {
 		t.Fatalf("error = %q, want endpoint context", err.Error())
 	}
 }
@@ -356,26 +640,32 @@ func TestSaveBundle(t *testing.T) {
 }
 
 type handlerOverride struct {
-	status int
-	body   string
+	status  int
+	body    string
+	handler http.HandlerFunc
 }
 
 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",
+		"/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",
+		convectiveOutlooksEndpoint: "convective_outlooks.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 {
+			if override.handler != nil {
+				override.handler(w, r)
+				return
+			}
 			w.WriteHeader(override.status)
 			_, _ = w.Write([]byte(override.body))
 			return
@@ -401,6 +691,8 @@ func newTestClient(t *testing.T, baseURL string, sourcePolicies map[string]confi
 	if err != nil {
 		t.Fatalf("New() error = %v", err)
 	}
+	client.warmupDelay = 0
+	client.fetchRetryDelay = 0
 	return client
 }
 
@@ -423,6 +715,16 @@ func containsPath(requested []string, path string) bool {
 	return false
 }
 
+func countPath(requested []string, path string) int {
+	var count int
+	for _, rawURL := range requested {
+		if strings.HasPrefix(rawURL, path+"?") || rawURL == path {
+			count++
+		}
+	}
+	return count
+}
+
 func sourceByName(t *testing.T, sources []weatherdata.Source, name string) weatherdata.Source {
 	t.Helper()
 	for _, source := range sources {

internal/adapters/weatherapi/testdata/convective_outlooks.json

@@ -0,0 +1,50 @@
+{
+  "data": {
+    "locationId": "nws-lsx-grid-90-74",
+    "locationName": "St. Louis, MO",
+    "asOf": "2026-05-29T16:00:00Z",
+    "issuedAt": "2026-05-29T15:45:00Z",
+    "updatedAt": "2026-05-29T16:05:00Z",
+    "product": "convective_outlook",
+    "outlooks": [
+      {
+        "id": "day1-categorical-slight",
+        "provider": "spc",
+        "product": "convective_outlook",
+        "day": 1,
+        "outlookType": "categorical",
+        "label": "SLGT",
+        "labelText": "Slight Risk",
+        "forecaster": "Smith",
+        "severityRank": 3,
+        "validFrom": "2026-05-29T13:00:00-05:00",
+        "validTo": "2026-05-30T07:00:00-05:00",
+        "issuedAt": "2026-05-29T15:45:00Z",
+        "expiresAt": "2026-05-30T07:00:00-05:00",
+        "sourceUrl": "https://www.spc.noaa.gov/products/outlook/day1otlk.html",
+        "imageUrl": "https://www.spc.noaa.gov/products/outlook/day1probotlk_2000_torn.gif",
+        "containsLocation": true,
+        "geometry": {
+          "type": "Polygon",
+          "coordinates": [
+            [
+              [-91.0, 38.0],
+              [-90.0, 38.5],
+              [-89.5, 37.8],
+              [-91.0, 38.0]
+            ]
+          ]
+        }
+      }
+    ],
+    "discussions": [
+      {
+        "day": 1,
+        "headline": "Severe storms possible",
+        "summary": "Scattered severe storms are possible.",
+        "discussion": "A few storms may become severe during the afternoon.",
+        "updatedAt": "2026-05-29T16:05:00Z"
+      }
+    ]
+  }
+}

internal/app/app.go

@@ -10,13 +10,14 @@ import (
 
 	distributoradapter "gitea.maximumdirect.net/eric/weatherreporter/internal/adapters/distributor"
 	"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/collect"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/facts"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/fileutil"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/generatedtext"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/module"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/promptinput"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
@@ -28,18 +29,20 @@ import (
 type ReportKind string
 
 const (
-	ReportDaily    ReportKind = "daily"
-	ReportTomorrow ReportKind = "tomorrow"
-	ReportThreeDay ReportKind = "three-day"
-	ReportWeekend  ReportKind = "weekend"
-	ReportStorm    ReportKind = "storm"
+	ReportDaily    ReportKind = ReportKind(report.CommandNameDaily)
+	ReportToday    ReportKind = ReportKind(report.CommandNameToday)
+	ReportTomorrow ReportKind = ReportKind(report.CommandNameTomorrow)
+	ReportHourly   ReportKind = ReportKind(report.CommandNameHourly)
+	ReportThreeDay ReportKind = ReportKind(report.CommandNameThreeDay)
+	ReportWeekend  ReportKind = ReportKind(report.CommandNameWeekend)
+	ReportStorm    ReportKind = ReportKind(report.CommandNameStorm)
 )
 
 type BatchKind string
 
 const (
-	BatchMorning BatchKind = "morning"
-	BatchEvening BatchKind = "evening"
+	BatchMorning BatchKind = BatchKind(report.BatchNameMorning)
+	BatchEvening BatchKind = BatchKind(report.BatchNameEvening)
 )
 
 type GenerateRequest struct {
@@ -50,6 +53,7 @@ type GenerateRequest struct {
 	Date       time.Time
 	StormStart time.Time
 	StormEnd   time.Time
+	Collector  Collector
 	Notifier   Notifier
 }
 
@@ -58,6 +62,7 @@ type BatchRequest struct {
 	Batch     BatchKind
 	Now       time.Time
 	OutputDir string
+	Collector Collector
 	Renderer  Renderer
 	Store     state.Store
 	Notifier  Notifier
@@ -82,37 +87,64 @@ type ReportRequest struct {
 	Config     config.Config
 	Resolved   report.Resolved
 	OutputPath string
+	Collection collect.Result
 	Renderer   Renderer
 	Store      state.Store
 	Notifier   Notifier
+	noNotify   bool
 }
 
 type ReportResult struct {
-	ModuleSnapshot     module.Snapshot
-	ModuleSnapshotPath string
-	DataPackage        promptinput.Package
-	DataPackagePath    string
-	PreflightPath      string
-	ReportPath         string
-	OutputPath         string
-	NotificationPath   string
-	Metadata           state.Metadata
-	MetadataPath       string
-	PriorSnapshot      *state.PriorSnapshot
-	RecentChanges      []changes.Change
-	RenderResult       *scriptorium.RenderResult
-	RunResult          *scriptorium.RunResult
-	Notification       *NotificationResult
+	ModuleSnapshot          module.Snapshot
+	ModuleSnapshotPath      string
+	DataPackage             promptinput.Package
+	DataPackagePath         string
+	PreflightPath           string
+	ReportPath              string
+	OutputPath              string
+	NotificationPath        string
+	Metadata                state.Metadata
+	MetadataPath            string
+	PriorSnapshot           *state.PriorSnapshot
+	RecentChanges           []changes.Change
+	RenderResult            *scriptorium.RenderResult
+	RunResult               *scriptorium.RunResult
+	StructuredRunResult     *scriptorium.StructuredRunResult
+	GeneratedTextRawPath    string
+	GeneratedTextResultPath string
+	GeneratedTextPath       string
+	RenderContextPath       string
+	Notification            *NotificationResult
 }
 
 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"`
+	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"`
+	Notification *BatchNotificationResult `json:"notification,omitempty"`
+	Reports      []BatchReportResult      `json:"reports"`
+}
+
+type BatchNotificationResult struct {
+	Status          string                    `json:"status"`
+	Reason          string                    `json:"reason,omitempty"`
+	RunID           string                    `json:"runId,omitempty"`
+	PipelineID      string                    `json:"pipelineId,omitempty"`
+	BundleID        string                    `json:"bundleId,omitempty"`
+	IdempotencyKey  string                    `json:"idempotencyKey,omitempty"`
+	Path            string                    `json:"path,omitempty"`
+	IncludedReports []BatchNotificationReport `json:"includedReports,omitempty"`
+	Error           string                    `json:"error,omitempty"`
+}
+
+type BatchNotificationReport struct {
+	ReportID    report.ID `json:"reportId"`
+	RunID       string    `json:"runId"`
+	SourcePath  string    `json:"sourcePath"`
+	BundlePaths []string  `json:"bundlePaths"`
 }
 
 type BatchReportResult struct {
@@ -144,12 +176,46 @@ func (e BatchError) Error() string {
 	if e.Result == nil {
 		return "batch failed"
 	}
+	if batchNotificationFailed(e.Result) && batchReportFailures(e.Result) == 0 {
+		if e.Result.Notification.Error != "" {
+			return fmt.Sprintf("batch %s notification failed: %s", e.Result.Batch, e.Result.Notification.Error)
+		}
+		return fmt.Sprintf("batch %s notification failed", e.Result.Batch)
+	}
 	return fmt.Sprintf("batch %s failed: %d of %d reports failed", e.Result.Batch, e.Result.Failed, e.Result.Total)
 }
 
+func batchNotificationFailed(result *BatchResult) bool {
+	return result != nil && result.Notification != nil && result.Notification.Status == "failed"
+}
+
+func batchReportFailures(result *BatchResult) int {
+	if result == nil {
+		return 0
+	}
+	failures := 0
+	for _, item := range result.Reports {
+		if item.Status == "failed" {
+			failures++
+		}
+	}
+	return failures
+}
+
 type Renderer interface {
 	Render(context.Context, scriptorium.RenderRequest) (*scriptorium.RenderResult, error)
 	Run(context.Context, scriptorium.RunRequest) (*scriptorium.RunResult, error)
+	StructuredRun(context.Context, scriptorium.StructuredRunRequest) (*scriptorium.StructuredRunResult, error)
+}
+
+type Collector interface {
+	Run(context.Context, collect.Request) (*collect.Result, error)
+}
+
+type defaultCollector struct{}
+
+func (defaultCollector) Run(ctx context.Context, req collect.Request) (*collect.Result, error) {
+	return collect.Run(ctx, req)
 }
 
 type Notifier interface {
@@ -202,24 +268,33 @@ func (e *NotificationError) Unwrap() error {
 }
 
 func Generate(ctx context.Context, req GenerateRequest) error {
+	_, err := GenerateDetailed(ctx, req)
+	return err
+}
+
+func GenerateDetailed(ctx context.Context, req GenerateRequest) (*ReportResult, error) {
 	now := req.Now
 	if now.IsZero() {
 		now = time.Now()
 	}
+	collection, err := collectWeather(ctx, req.Config, req.Collector)
+	if err != nil {
+		return nil, err
+	}
 	resolved, err := ResolveGenerate(req, now)
 	if err != nil {
-		return err
+		return nil, err
 	}
 	if resolved.Definition.Generated {
-		_, err := GenerateReport(ctx, ReportRequest{
+		return GenerateReport(ctx, ReportRequest{
 			Config:     req.Config,
 			Resolved:   resolved,
 			OutputPath: req.OutputPath,
+			Collection: *collection,
 			Notifier:   req.Notifier,
 		})
-		return err
 	}
-	return fmt.Errorf("generate is not implemented")
+	return nil, fmt.Errorf("generate is not implemented")
 }
 
 func RunBatch(ctx context.Context, req BatchRequest) error {
@@ -238,7 +313,14 @@ func RunBatchDetailed(ctx context.Context, req BatchRequest) (*BatchResult, erro
 	if now.IsZero() {
 		now = time.Now()
 	}
-	resolvedReports, err := ResolveBatch(req, now)
+	if _, err := report.BatchForCommandName(string(req.Batch)); err != nil {
+		return nil, err
+	}
+	collection, err := collectWeather(ctx, req.Config, req.Collector)
+	if err != nil {
+		return nil, err
+	}
+	plannedReports, err := planBatchRun(req, now, *collection)
 	if err != nil {
 		return nil, err
 	}
@@ -253,27 +335,31 @@ func RunBatchDetailed(ctx context.Context, req BatchRequest) (*BatchResult, erro
 		}
 		startedAt := now
 		result := &BatchResult{Batch: req.Batch, StartedAt: startedAt}
-		for _, resolved := range resolvedReports {
+		for _, planned := range plannedReports {
+			resolved := planned.Resolved
 			if !resolved.Definition.Generated {
 				return nil, fmt.Errorf("run is not implemented")
 			}
 		}
-		for _, resolved := range resolvedReports {
-			item := batchReportResult(resolved)
+		for _, planned := range plannedReports {
+			resolved := planned.Resolved
+			item := batchReportResult(planned)
 			if paths, err := store.Paths(resolved); err == nil {
 				item.DataPackagePath = paths.DataPackage
 				item.PreflightPath = paths.Preflight
 				item.ReportPath = paths.RenderedReport
 				item.MetadataPath = paths.Metadata
 			}
-			outputPath := batchOutputPath(req.OutputDir, resolved.Definition)
+			outputPath := plannedBatchOutputPath(req.OutputDir, planned)
 			reportResult, err := GenerateReport(ctx, ReportRequest{
 				Config:     req.Config,
 				Resolved:   resolved,
 				OutputPath: outputPath,
+				Collection: *collection,
 				Renderer:   req.Renderer,
 				Store:      store,
 				Notifier:   req.Notifier,
+				noNotify:   true,
 			})
 			if err != nil {
 				item.Status = "failed"
@@ -306,13 +392,21 @@ func RunBatchDetailed(ctx context.Context, req BatchRequest) (*BatchResult, erro
 			result.Reports = append(result.Reports, item)
 		}
 		result.Total = len(result.Reports)
+		batchNotification, err := notifyBatch(ctx, req.Config, req.Batch, batchRunID(startedAt, req.Batch), startedAt, result, plannedReports, store, req.Notifier)
+		if batchNotification != nil {
+			result.Notification = batchNotification
+		}
+		if err != nil {
+			result.Failed++
+		}
 		result.FinishedAt = time.Now()
 		return result, nil
 	}
 	return nil, fmt.Errorf("run is not implemented")
 }
 
-func batchReportResult(resolved report.Resolved) BatchReportResult {
+func batchReportResult(planned plannedBatchReport) BatchReportResult {
+	resolved := planned.Resolved
 	metadata := resolved.Metadata()
 	return BatchReportResult{
 		ReportID:    resolved.Definition.ID,
@@ -324,11 +418,18 @@ func batchReportResult(resolved report.Resolved) BatchReportResult {
 	}
 }
 
-func batchOutputPath(outputDir string, definition report.Definition) string {
-	if outputDir == "" || definition.BatchOutputName == "" {
+func plannedBatchOutputPath(outputDir string, planned plannedBatchReport) string {
+	if outputDir == "" {
 		return ""
 	}
-	return filepath.Join(outputDir, definition.BatchOutputName)
+	outputCopyName := planned.OutputCopyName
+	if outputCopyName == "" {
+		outputCopyName = planned.Resolved.Definition.BatchOutputName
+	}
+	if outputCopyName == "" {
+		return ""
+	}
+	return filepath.Join(outputDir, outputCopyName)
 }
 
 func ResolveGenerate(req GenerateRequest, now time.Time) (report.Resolved, error) {
@@ -336,7 +437,7 @@ func ResolveGenerate(req GenerateRequest, now time.Time) (report.Resolved, error
 	if err != nil {
 		return report.Resolved{}, err
 	}
-	id, err := reportIDForCommand(req.Report)
+	id, err := report.IDForCommandName(string(req.Report))
 	if err != nil {
 		return report.Resolved{}, err
 	}
@@ -353,71 +454,41 @@ func ResolveGenerate(req GenerateRequest, now time.Time) (report.Resolved, error
 	})
 }
 
-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
-	}
-	registry, err := reportRegistry(req.Config)
-	if err != nil {
-		return nil, err
-	}
-	return registry.BatchReports(batch, report.ResolveRequest{
-		Now:      now,
-		Location: location,
-	})
-}
-
 func reportRegistry(cfg config.Config) (report.Registry, error) {
-	registry, err := report.DefaultRegistry().WithModuleOverrides(cfg.ReportModuleOverrides())
+	overrides, err := cfg.ReportModuleOverrides()
+	if err != nil {
+		return report.Registry{}, err
+	}
+	registry, err := report.DefaultRegistry().WithModuleOverrides(overrides)
 	if err != nil {
 		return report.Registry{}, err
 	}
 	return registry, nil
 }
 
-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) (*weatherdata.Bundle, error) {
-	client, err := weatherapi.New(req.Config)
+	result, err := collectWeather(ctx, req.Config, nil)
 	if err != nil {
 		return nil, err
 	}
-	bundle, err := client.FetchBundle(ctx)
+	return result.Bundle, nil
+}
+
+func collectWeather(ctx context.Context, cfg config.Config, collector Collector) (*collect.Result, error) {
+	if collector == nil {
+		collector = defaultCollector{}
+	}
+	result, err := collector.Run(ctx, collect.Request{Config: cfg})
 	if err != nil {
 		return nil, err
 	}
-	return bundle, nil
+	if result == nil {
+		return nil, fmt.Errorf("collect weather bundle: collector returned nil result")
+	}
+	if result.Bundle == nil {
+		return nil, fmt.Errorf("collect weather bundle: collector returned nil bundle")
+	}
+	return result, nil
 }
 
 func FetchAndSaveBundle(ctx context.Context, req FetchBundleRequest) (*weatherdata.Bundle, error) {
@@ -428,13 +499,18 @@ func FetchAndSaveBundle(ctx context.Context, req FetchBundleRequest) (*weatherda
 	if err != nil {
 		return nil, err
 	}
-	if err := weatherapi.SaveBundle(req.OutputPath, bundle); err != nil {
-		return nil, err
+	if err := fileutil.WriteJSONAtomic(req.OutputPath, bundle); err != nil {
+		return nil, fmt.Errorf("save bundle: %w", err)
 	}
 	return bundle, nil
 }
 
 func GenerateReport(ctx context.Context, req ReportRequest) (*ReportResult, error) {
+	bundle := req.Collection.Bundle
+	if bundle == nil {
+		return nil, fmt.Errorf("collected weather bundle is required")
+	}
+
 	store := req.Store
 	if store == nil {
 		defaultStore, err := defaultStore(req.Config)
@@ -452,10 +528,6 @@ func GenerateReport(ctx context.Context, req ReportRequest) (*ReportResult, erro
 		return nil, err
 	}
 
-	bundle, err := FetchBundle(ctx, FetchBundleRequest{Config: req.Config})
-	if err != nil {
-		return nil, err
-	}
 	reportFacts, err := BuildReportFacts(ModuleSnapshotRequest{
 		Config:   req.Config,
 		Resolved: req.Resolved,
@@ -482,11 +554,15 @@ func GenerateReport(ctx context.Context, req ReportRequest) (*ReportResult, erro
 	}
 	briefingMetadata := briefing.BuildMetadata(briefingBuildContext(req.Config, req.Resolved, reportFacts.Collected))
 	metadata := state.BuildMetadataFromBriefingMetadata(req.Resolved, briefingMetadata, state.ArtifactPaths{
-		ModuleSnapshot: moduleSnapshotPath,
-		Metadata:       paths.Metadata,
-		DataPackage:    paths.DataPackage,
-		Preflight:      paths.Preflight,
-		RenderedReport: paths.RenderedReport,
+		ModuleSnapshot:      moduleSnapshotPath,
+		Metadata:            paths.Metadata,
+		DataPackage:         paths.DataPackage,
+		Preflight:           paths.Preflight,
+		RenderedReport:      paths.RenderedReport,
+		GeneratedTextRaw:    paths.GeneratedTextRaw,
+		GeneratedTextResult: paths.GeneratedTextResult,
+		GeneratedText:       paths.GeneratedText,
+		RenderContext:       paths.RenderContext,
 	})
 	dataPackage, err := promptinput.Build(promptinput.BuildRequest{
 		Metadata:      promptMetadata(metadata),
@@ -531,9 +607,36 @@ func GenerateReport(ctx context.Context, req ReportRequest) (*ReportResult, erro
 		return nil, metadataErr
 	}
 	if renderErr != nil {
+		if req.Resolved.Definition.GenerationMode == report.GenerationModeGeneratedTextTemplate {
+			return nil, generatedReportError(req.Resolved, metadata.RunID, "render preflight", renderErr)
+		}
 		return nil, renderErr
 	}
 
+	if req.Resolved.Definition.GenerationMode == report.GenerationModeGeneratedTextTemplate {
+		return generateTextTemplateReport(ctx, generatedReportRequest{
+			ReportRequest:      req,
+			store:              store,
+			paths:              paths,
+			moduleSnapshot:     moduleSnapshot,
+			moduleSnapshotPath: moduleSnapshotPath,
+			reportFacts:        reportFacts,
+			dataPackage:        dataPackage,
+			dataPackagePath:    dataPackagePath,
+			briefingMetadata:   briefingMetadata,
+			metadata:           metadata,
+			metadataPath:       metadataPath,
+			preflightPath:      preflightPath,
+			priorSnapshot:      priorSnapshot,
+			recentChanges:      recentChanges,
+			renderResult:       renderResult,
+			renderer:           renderer,
+		})
+	}
+	if req.Resolved.Definition.GenerationMode != report.GenerationModeScriptoriumMarkdown {
+		return nil, fmt.Errorf("generation mode %q is not supported for report %q", req.Resolved.Definition.GenerationMode, req.Resolved.Definition.ID)
+	}
+
 	reportPath, err := store.PrepareRenderedReport(ctx, req.Resolved)
 	if err != nil {
 		return nil, err
@@ -543,53 +646,317 @@ func GenerateReport(ctx context.Context, req ReportRequest) (*ReportResult, erro
 		DataPackagePath: dataPackagePath,
 		OutputPath:      reportPath,
 	})
-	if runErr == nil && req.OutputPath != "" && req.OutputPath != reportPath {
-		if err := fileutil.CopyFileAtomic(reportPath, req.OutputPath); err != nil {
+	finalized, err := finalizeRenderedReport(ctx, finalizeRenderedReportRequest{
+		Config:            req.Config,
+		Store:             store,
+		Resolved:          req.Resolved,
+		Metadata:          metadata,
+		ManagedReportPath: reportPath,
+		OutputPath:        req.OutputPath,
+		Notifier:          req.Notifier,
+		GenerationErr:     runErr,
+		noNotify:          req.noNotify,
+	})
+	if err != nil {
+		if finalizeResultEmpty(finalized) {
+			return nil, err
+		}
+		return renderedReportResult(reportResultRequest{
+			moduleSnapshot:     moduleSnapshot,
+			moduleSnapshotPath: moduleSnapshotPath,
+			dataPackage:        dataPackage,
+			dataPackagePath:    dataPackagePath,
+			preflightPath:      preflightPath,
+			reportPath:         reportPath,
+			finalized:          finalized,
+			priorSnapshot:      priorSnapshot,
+			recentChanges:      recentChanges,
+			renderResult:       renderResult,
+			runResult:          runResult,
+		}), err
+	}
+
+	return renderedReportResult(reportResultRequest{
+		moduleSnapshot:     moduleSnapshot,
+		moduleSnapshotPath: moduleSnapshotPath,
+		dataPackage:        dataPackage,
+		dataPackagePath:    dataPackagePath,
+		preflightPath:      preflightPath,
+		reportPath:         reportPath,
+		finalized:          finalized,
+		priorSnapshot:      priorSnapshot,
+		recentChanges:      recentChanges,
+		renderResult:       renderResult,
+		runResult:          runResult,
+	}), nil
+}
+
+type generatedReportRequest struct {
+	ReportRequest
+	store              state.Store
+	paths              state.ArtifactPaths
+	moduleSnapshot     module.Snapshot
+	moduleSnapshotPath string
+	reportFacts        ReportFacts
+	dataPackage        promptinput.Package
+	dataPackagePath    string
+	briefingMetadata   briefing.Metadata
+	metadata           state.Metadata
+	metadataPath       string
+	preflightPath      string
+	priorSnapshot      *state.PriorSnapshot
+	recentChanges      []changes.Change
+	renderResult       *scriptorium.RenderResult
+	renderer           Renderer
+}
+
+func generateTextTemplateReport(ctx context.Context, req generatedReportRequest) (*ReportResult, error) {
+	handler, err := generatedtext.LookupDefinition(req.Resolved.Definition)
+	if err != nil {
+		return nil, generatedReportError(req.Resolved, req.metadata.RunID, "lookup generated text catalog", err)
+	}
+
+	structuredResult, runErr := req.renderer.StructuredRun(ctx, scriptorium.StructuredRunRequest{
+		PromptID:        req.Resolved.Definition.PromptID,
+		DataPackagePath: req.dataPackagePath,
+		OutputPath:      req.paths.GeneratedTextRaw,
+	})
+	generatedTextResultPath := req.paths.GeneratedTextResult
+	if structuredResult != nil {
+		var err error
+		generatedTextResultPath, err = req.store.SaveGeneratedTextResult(ctx, req.Resolved, structuredResult)
+		if err != nil {
+			return nil, err
+		}
+		req.metadata.GeneratedTextResultPath = generatedTextResultPath
+		req.metadataPath, err = req.store.SaveMetadata(ctx, req.metadata)
+		if 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 nil, generatedReportError(req.Resolved, req.metadata.RunID, "structured generated text", runErr)
 	}
 
-	notification, notificationPath, err := notifyReport(ctx, req.Config, req.Resolved, reportPath, metadata, req.Notifier, store)
-	if notificationPath != "" {
-		metadata.NotificationPath = notificationPath
-		metadataPath, metadataErr = store.SaveMetadata(ctx, metadata)
-		if metadataErr != nil {
-			return nil, metadataErr
-		}
+	rawGeneratedText, err := req.store.LoadGeneratedText(ctx, req.paths.GeneratedTextRaw)
+	if err != nil {
+		return nil, generatedReportError(req.Resolved, req.metadata.RunID, "load raw generated text", err)
 	}
+	generatedText, normalizedGeneratedText, err := handler.Validate(rawGeneratedText)
+	if err != nil {
+		return nil, generatedReportError(req.Resolved, req.metadata.RunID, "validate generated text", err)
+	}
+	generatedTextPath, err := req.store.SaveGeneratedText(ctx, req.Resolved, normalizedGeneratedText)
+	if err != nil {
+		return nil, err
+	}
+	req.metadata.GeneratedTextPath = generatedTextPath
+	req.metadataPath, err = req.store.SaveMetadata(ctx, req.metadata)
 	if err != nil {
 		return nil, err
 	}
 
+	renderContext, err := handler.BuildRenderContext(req.briefingMetadata, req.moduleSnapshot, req.reportFacts.Collected, req.reportFacts.Derived, generatedText)
+	if err != nil {
+		return nil, generatedReportError(req.Resolved, req.metadata.RunID, "build render context", err)
+	}
+	renderContextPath, err := req.store.SaveRenderContext(ctx, req.Resolved, renderContext)
+	if err != nil {
+		return nil, err
+	}
+	req.metadata.RenderContextPath = renderContextPath
+	req.metadataPath, err = req.store.SaveMetadata(ctx, req.metadata)
+	if err != nil {
+		return nil, err
+	}
+
+	rendered, err := handler.Render(renderContext)
+	if err != nil {
+		return nil, generatedReportError(req.Resolved, req.metadata.RunID, "render template", err)
+	}
+	reportPath, err := req.store.PrepareRenderedReport(ctx, req.Resolved)
+	if err != nil {
+		return nil, err
+	}
+	if err := fileutil.WriteFileAtomic(reportPath, rendered); err != nil {
+		return nil, err
+	}
+	finalized, err := finalizeRenderedReport(ctx, finalizeRenderedReportRequest{
+		Config:            req.Config,
+		Store:             req.store,
+		Resolved:          req.Resolved,
+		Metadata:          req.metadata,
+		ManagedReportPath: reportPath,
+		OutputPath:        req.OutputPath,
+		Notifier:          req.Notifier,
+		noNotify:          req.noNotify,
+	})
+	if err != nil {
+		if finalizeResultEmpty(finalized) {
+			return nil, err
+		}
+		return renderedReportResult(reportResultRequest{
+			moduleSnapshot:          req.moduleSnapshot,
+			moduleSnapshotPath:      req.moduleSnapshotPath,
+			dataPackage:             req.dataPackage,
+			dataPackagePath:         req.dataPackagePath,
+			preflightPath:           req.preflightPath,
+			reportPath:              reportPath,
+			finalized:               finalized,
+			priorSnapshot:           req.priorSnapshot,
+			recentChanges:           req.recentChanges,
+			renderResult:            req.renderResult,
+			structuredRunResult:     structuredResult,
+			generatedTextRawPath:    req.paths.GeneratedTextRaw,
+			generatedTextResultPath: generatedTextResultPath,
+			generatedTextPath:       generatedTextPath,
+			renderContextPath:       renderContextPath,
+		}), err
+	}
+
+	return renderedReportResult(reportResultRequest{
+		moduleSnapshot:          req.moduleSnapshot,
+		moduleSnapshotPath:      req.moduleSnapshotPath,
+		dataPackage:             req.dataPackage,
+		dataPackagePath:         req.dataPackagePath,
+		preflightPath:           req.preflightPath,
+		reportPath:              reportPath,
+		finalized:               finalized,
+		priorSnapshot:           req.priorSnapshot,
+		recentChanges:           req.recentChanges,
+		renderResult:            req.renderResult,
+		structuredRunResult:     structuredResult,
+		generatedTextRawPath:    req.paths.GeneratedTextRaw,
+		generatedTextResultPath: generatedTextResultPath,
+		generatedTextPath:       generatedTextPath,
+		renderContextPath:       renderContextPath,
+	}), nil
+}
+
+func finalizeResultEmpty(result finalizeRenderedReportResult) bool {
+	return result.OutputPath == "" &&
+		result.NotificationPath == "" &&
+		result.MetadataPath == "" &&
+		result.Metadata.RunID == "" &&
+		result.Notification == nil
+}
+
+type reportResultRequest struct {
+	moduleSnapshot          module.Snapshot
+	moduleSnapshotPath      string
+	dataPackage             promptinput.Package
+	dataPackagePath         string
+	preflightPath           string
+	reportPath              string
+	finalized               finalizeRenderedReportResult
+	priorSnapshot           *state.PriorSnapshot
+	recentChanges           []changes.Change
+	renderResult            *scriptorium.RenderResult
+	runResult               *scriptorium.RunResult
+	structuredRunResult     *scriptorium.StructuredRunResult
+	generatedTextRawPath    string
+	generatedTextResultPath string
+	generatedTextPath       string
+	renderContextPath       string
+}
+
+func renderedReportResult(req reportResultRequest) *ReportResult {
 	return &ReportResult{
-		ModuleSnapshot:     moduleSnapshot,
-		ModuleSnapshotPath: moduleSnapshotPath,
-		DataPackage:        dataPackage,
-		DataPackagePath:    dataPackagePath,
-		PreflightPath:      preflightPath,
-		ReportPath:         reportPath,
-		OutputPath:         outputPath,
-		NotificationPath:   notificationPath,
-		Metadata:           metadata,
-		MetadataPath:       metadataPath,
-		PriorSnapshot:      priorSnapshot,
-		RecentChanges:      recentChanges,
-		RenderResult:       renderResult,
-		RunResult:          runResult,
-		Notification:       notification,
-	}, nil
+		ModuleSnapshot:          req.moduleSnapshot,
+		ModuleSnapshotPath:      req.moduleSnapshotPath,
+		DataPackage:             req.dataPackage,
+		DataPackagePath:         req.dataPackagePath,
+		PreflightPath:           req.preflightPath,
+		ReportPath:              req.reportPath,
+		OutputPath:              req.finalized.OutputPath,
+		NotificationPath:        req.finalized.NotificationPath,
+		Metadata:                req.finalized.Metadata,
+		MetadataPath:            req.finalized.MetadataPath,
+		PriorSnapshot:           req.priorSnapshot,
+		RecentChanges:           req.recentChanges,
+		RenderResult:            req.renderResult,
+		RunResult:               req.runResult,
+		StructuredRunResult:     req.structuredRunResult,
+		GeneratedTextRawPath:    req.generatedTextRawPath,
+		GeneratedTextResultPath: req.generatedTextResultPath,
+		GeneratedTextPath:       req.generatedTextPath,
+		RenderContextPath:       req.renderContextPath,
+		Notification:            req.finalized.Notification,
+	}
+}
+
+type finalizeRenderedReportRequest struct {
+	Config            config.Config
+	Store             state.Store
+	Resolved          report.Resolved
+	Metadata          state.Metadata
+	ManagedReportPath string
+	OutputPath        string
+	Notifier          Notifier
+	GenerationErr     error
+	noNotify          bool
+}
+
+type finalizeRenderedReportResult struct {
+	OutputPath       string
+	NotificationPath string
+	Metadata         state.Metadata
+	MetadataPath     string
+	Notification     *NotificationResult
+}
+
+func finalizeRenderedReport(ctx context.Context, req finalizeRenderedReportRequest) (finalizeRenderedReportResult, error) {
+	if req.Store == nil {
+		return finalizeRenderedReportResult{}, fmt.Errorf("state store is required")
+	}
+	if req.ManagedReportPath == "" {
+		return finalizeRenderedReportResult{}, fmt.Errorf("managed report path is required for report %q", req.Resolved.Definition.ID)
+	}
+
+	metadata := req.Metadata
+	metadata.RenderedReportPath = req.ManagedReportPath
+	outputPath := req.ManagedReportPath
+	if req.OutputPath != "" {
+		outputPath = req.OutputPath
+		if req.GenerationErr == nil && req.OutputPath != req.ManagedReportPath {
+			if err := fileutil.CopyFileAtomic(req.ManagedReportPath, req.OutputPath); err != nil {
+				return finalizeRenderedReportResult{}, err
+			}
+		}
+	}
+
+	metadataPath, err := req.Store.SaveMetadata(ctx, metadata)
+	if err != nil {
+		return finalizeRenderedReportResult{}, err
+	}
+	result := finalizeRenderedReportResult{
+		OutputPath:   outputPath,
+		Metadata:     metadata,
+		MetadataPath: metadataPath,
+	}
+	if req.GenerationErr != nil {
+		return result, req.GenerationErr
+	}
+	if req.noNotify {
+		return result, nil
+	}
+
+	notification, notificationPath, err := notifyReport(ctx, req.Config, req.Resolved, req.ManagedReportPath, metadata, req.Notifier, req.Store)
+	if notificationPath != "" {
+		metadata.NotificationPath = notificationPath
+		metadataPath, saveErr := req.Store.SaveMetadata(ctx, metadata)
+		if saveErr != nil {
+			return finalizeRenderedReportResult{}, saveErr
+		}
+		result.Metadata = metadata
+		result.MetadataPath = metadataPath
+		result.NotificationPath = notificationPath
+	}
+	result.Notification = notification
+	if err != nil {
+		return result, err
+	}
+	return result, nil
 }
 
 func notifyReport(ctx context.Context, cfg config.Config, resolved report.Resolved, reportPath string, metadata state.Metadata, notifier Notifier, store state.Store) (*NotificationResult, string, error) {
@@ -632,14 +999,8 @@ func reportNotifier(cfg config.Config, notifier Notifier) (Notifier, bool) {
 }
 
 func buildNotificationRequest(cfg config.Config, resolved report.Resolved, reportPath string, metadata state.Metadata) (NotificationRequest, error) {
-	values := config.DistributorTemplateValues{
-		LocationID:      cfg.Location.ID,
-		ReportID:        string(resolved.Definition.ID),
-		RunID:           metadata.RunID,
-		ArtifactGroup:   resolved.Definition.ArtifactGroup,
-		BatchOutputName: resolved.Definition.BatchOutputName,
-	}
-	if err := addDistributorValidPeriodValues(&values, resolved.ValidPeriod, cfg.WeatherAPI.Timezone); err != nil {
+	values, err := distributorTemplateValuesForReport(cfg, resolved, metadata.RunID, resolved.Definition.BatchOutputName)
+	if err != nil {
 		return NotificationRequest{}, err
 	}
 	bundleID, err := config.RenderDistributorBundleID(cfg.Notify.Distributor.BundleIDTemplate, values)
@@ -655,7 +1016,7 @@ func buildNotificationRequest(cfg config.Config, resolved report.Resolved, repor
 	if err != nil {
 		return NotificationRequest{}, err
 	}
-	bundlePaths, err := config.RenderDistributorReportPaths(cfg.Notify.Distributor.ReportPathTemplates, values)
+	bundlePaths, err := renderDistributorReportBundlePaths(cfg, resolved, metadata.RunID, reportPath, values)
 	if err != nil {
 		return NotificationRequest{}, err
 	}
@@ -671,6 +1032,59 @@ func buildNotificationRequest(cfg config.Config, resolved report.Resolved, repor
 	}, nil
 }
 
+func distributorTemplateValuesForReport(cfg config.Config, resolved report.Resolved, runID string, batchOutputName string) (config.DistributorTemplateValues, error) {
+	values := config.DistributorTemplateValues{
+		LocationID:      cfg.Location.ID,
+		ReportID:        string(resolved.Definition.ID),
+		RunID:           runID,
+		ArtifactGroup:   resolved.Definition.ArtifactGroup,
+		BatchOutputName: batchOutputName,
+	}
+	if values.BatchOutputName == "" {
+		values.BatchOutputName = resolved.Definition.BatchOutputName
+	}
+	if err := addDistributorValidPeriodValues(&values, resolved.ValidPeriod, cfg.WeatherAPI.Timezone); err != nil {
+		return config.DistributorTemplateValues{}, err
+	}
+	if resolved.Definition.ID == report.Storm {
+		values.StormID = values.ValidStartStamp + "-" + values.ValidEndStamp
+	}
+	return values, nil
+}
+
+func renderDistributorReportBundlePaths(cfg config.Config, resolved report.Resolved, runID string, sourcePath string, values config.DistributorTemplateValues) ([]string, error) {
+	templates, name, err := distributorPathTemplatesForReport(cfg, resolved.Definition)
+	if err != nil {
+		return nil, distributorReportPathError(resolved.Definition.ID, runID, sourcePath, err)
+	}
+	paths, err := config.RenderDistributorReportPaths(name, templates, values)
+	if err != nil {
+		return nil, distributorReportPathError(resolved.Definition.ID, runID, sourcePath, err)
+	}
+	return paths, nil
+}
+
+func distributorPathTemplatesForReport(cfg config.Config, definition report.Definition) ([]string, string, error) {
+	overrides, err := cfg.ReportDistributorPathOverrides()
+	if err != nil {
+		return nil, "", err
+	}
+	if templates, ok := overrides[definition.ID]; ok {
+		return append([]string(nil), templates...), fmt.Sprintf("reports.%s.distributor.path_templates", definition.ID), nil
+	}
+	if len(definition.DistributorPathTemplates) > 0 {
+		return append([]string(nil), definition.DistributorPathTemplates...), fmt.Sprintf("report.%s.distributor_path_templates", definition.ID), nil
+	}
+	return nil, "", fmt.Errorf("no distributor path templates configured")
+}
+
+func distributorReportPathError(id report.ID, runID string, sourcePath string, err error) error {
+	if sourcePath != "" {
+		return fmt.Errorf("report %q run %q source path %q: %w", id, runID, sourcePath, err)
+	}
+	return fmt.Errorf("report %q run %q: %w", id, runID, err)
+}
+
 func addDistributorValidPeriodValues(values *config.DistributorTemplateValues, period timeutil.Period, timezone string) error {
 	location, err := timeutil.LoadLocation(timezone)
 	if err != nil {
@@ -778,6 +1192,38 @@ func (n distributorNotifier) Notify(ctx context.Context, req NotificationRequest
 	return notification, nil
 }
 
+func (n distributorNotifier) NotifyBatch(ctx context.Context, req batchNotificationRequest) (*NotificationResult, error) {
+	result, err := n.client.Upload(ctx, batchDistributorUploadRequest(req))
+	notification := notificationResultFromUpload(req.PipelineID, req.BundleID, req.IdempotencyKey, result)
+	if err != nil {
+		return notification, err
+	}
+	return notification, nil
+}
+
+func notificationResultFromUpload(pipelineID string, bundleID string, idempotencyKey string, result distributoradapter.UploadResult) *NotificationResult {
+	notification := &NotificationResult{
+		PipelineID:     pipelineID,
+		BundleID:       bundleID,
+		IdempotencyKey: idempotencyKey,
+		RunID:          result.RunID,
+		Status:         result.Status,
+		UploadStatus:   result.UploadStatus,
+		StatusError:    result.StatusError,
+	}
+	if result.RunStatus != nil {
+		if result.RunStatus.PipelineID != "" {
+			notification.PipelineID = result.RunStatus.PipelineID
+		}
+		notification.AcceptedAt = result.RunStatus.AcceptedAt
+		notification.StartedAt = result.RunStatus.StartedAt
+		notification.FinishedAt = result.RunStatus.FinishedAt
+		notification.Report = append([]byte(nil), result.RunStatus.Report...)
+		notification.Error = result.RunStatus.Error
+	}
+	return notification
+}
+
 func distributorUploadFiles(sourcePath string, bundlePaths []string) []distributoradapter.UploadFile {
 	files := make([]distributoradapter.UploadFile, 0, len(bundlePaths))
 	for _, bundlePath := range bundlePaths {
@@ -911,7 +1357,7 @@ func recentChanges(ctx context.Context, store state.Store, priorSnapshot *state.
 		PrecipTimingShiftMinutes: cfg.PrecipTimingShiftMinutes,
 	}
 	switch reportID {
-	case report.DailyToday, report.DailyTomorrow:
+	case report.Daily, report.Today, report.Tomorrow:
 		return changes.CompareDaily(previous, current, thresholds)
 	case report.ThreeDay:
 		return changes.CompareThreeDay(previous, current, thresholds)
@@ -935,3 +1381,10 @@ func preflightArtifact(result *scriptorium.RenderResult) state.PreflightArtifact
 		ExitCode:        result.ExitCode,
 	}
 }
+
+func generatedReportError(resolved report.Resolved, runID string, operation string, err error) error {
+	if err == nil {
+		return nil
+	}
+	return fmt.Errorf("generate report %q run %q: %s: %w", resolved.Definition.ID, runID, operation, err)
+}

internal/app/batch_notification.go

@@ -0,0 +1,379 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	distributoradapter "gitea.maximumdirect.net/eric/weatherreporter/internal/adapters/distributor"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/state"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+const runIDTimestampLayout = "20060102T150405.000000000Z"
+
+type batchNotificationIdentity struct {
+	PipelineID     string
+	BundleID       string
+	IdempotencyKey string
+}
+
+type batchNotificationRequest struct {
+	Batch           BatchKind
+	RunID           string
+	PipelineID      string
+	BundleID        string
+	IdempotencyKey  string
+	Files           []batchNotificationFile
+	IncludedReports []BatchNotificationReport
+	CreatedAt       time.Time
+}
+
+type batchNotificationFile struct {
+	ReportID   report.ID
+	RunID      string
+	SourcePath string
+	BundlePath string
+}
+
+type batchNotifier interface {
+	NotifyBatch(context.Context, batchNotificationRequest) (*NotificationResult, error)
+}
+
+func batchRunID(startedAt time.Time, batch BatchKind) string {
+	return startedAt.UTC().Format(runIDTimestampLayout) + "_" + string(batch)
+}
+
+func notifyBatch(ctx context.Context, cfg config.Config, batch BatchKind, runID string, startedAt time.Time, result *BatchResult, planned []plannedBatchReport, store state.Store, notifier Notifier) (*BatchNotificationResult, error) {
+	if !cfg.Notify.Distributor.Enabled {
+		return nil, nil
+	}
+	if !cfg.Notify.Distributor.Batch.Enabled {
+		return nil, nil
+	}
+	if result == nil {
+		return nil, fmt.Errorf("batch result is required")
+	}
+	if result.Failed > 0 {
+		return &BatchNotificationResult{
+			Status: "skipped",
+			Reason: "one or more reports failed",
+		}, nil
+	}
+
+	req, err := buildBatchNotificationRequest(cfg, batch, runID, startedAt, result.Reports, planned)
+	if err != nil {
+		path, saveErr := saveBatchNotificationArtifact(ctx, store, cfg, batch, runID, startedAt, batchNotificationRequest{}, nil, err)
+		if saveErr != nil {
+			return nil, saveErr
+		}
+		return failedBatchNotificationResult(batchNotificationRequest{}, path, err), err
+	}
+
+	batchNotifier, err := resolveBatchNotifier(cfg, notifier)
+	if err != nil {
+		path, saveErr := saveBatchNotificationArtifact(ctx, store, cfg, batch, runID, startedAt, req, nil, err)
+		if saveErr != nil {
+			return nil, saveErr
+		}
+		return failedBatchNotificationResult(req, path, err), err
+	}
+
+	notification, notifyErr := batchNotifier.NotifyBatch(ctx, req)
+	wrappedErr := notifyErr
+	if notifyErr != nil {
+		wrappedErr = fmt.Errorf("notify batch %q run %q bundle %q: %w", batch, runID, req.BundleID, notifyErr)
+	}
+	path, saveErr := saveBatchNotificationArtifact(ctx, store, cfg, batch, runID, startedAt, req, notification, wrappedErr)
+	if saveErr != nil {
+		return nil, saveErr
+	}
+
+	batchResult := batchNotificationResult(req, notification, path)
+	if wrappedErr != nil {
+		batchResult.Status = "failed"
+		batchResult.Error = wrappedErr.Error()
+		return batchResult, wrappedErr
+	}
+	return batchResult, nil
+}
+
+func resolveBatchNotifier(cfg config.Config, notifier Notifier) (batchNotifier, error) {
+	if notifier != nil {
+		if batchNotifier, ok := notifier.(batchNotifier); ok {
+			return batchNotifier, nil
+		}
+		return nil, fmt.Errorf("batch distributor notifier is required")
+	}
+	return distributorNotifier{
+		client: distributoradapter.New(cfg.Notify.Distributor),
+	}, nil
+}
+
+func buildBatchNotificationRequest(cfg config.Config, batch BatchKind, runID string, startedAt time.Time, reports []BatchReportResult, planned []plannedBatchReport) (batchNotificationRequest, error) {
+	if len(reports) == 0 {
+		return batchNotificationRequest{}, fmt.Errorf("batch notification requires at least one report")
+	}
+
+	identity, err := renderBatchNotificationIdentity(cfg, batch, runID, startedAt)
+	if err != nil {
+		return batchNotificationRequest{}, err
+	}
+	if identity.PipelineID == "" {
+		return batchNotificationRequest{}, fmt.Errorf("batch notification pipeline id is required")
+	}
+	if identity.BundleID == "" {
+		return batchNotificationRequest{}, fmt.Errorf("batch notification bundle id is required")
+	}
+	if identity.IdempotencyKey == "" {
+		return batchNotificationRequest{}, fmt.Errorf("batch notification idempotency key is required for bundle %q", identity.BundleID)
+	}
+
+	plannedByRunID, err := plannedReportsByRunID(planned)
+	if err != nil {
+		return batchNotificationRequest{}, err
+	}
+
+	req := batchNotificationRequest{
+		Batch:          batch,
+		RunID:          runID,
+		PipelineID:     identity.PipelineID,
+		BundleID:       identity.BundleID,
+		IdempotencyKey: identity.IdempotencyKey,
+		CreatedAt:      startedAt,
+	}
+	seenBundlePaths := map[string]batchNotificationFile{}
+	for _, item := range reports {
+		plannedReport, ok := plannedByRunID[item.RunID]
+		if !ok {
+			return batchNotificationRequest{}, fmt.Errorf("batch notification report %q run %q has no matching planned report", item.ReportID, item.RunID)
+		}
+		if item.ReportID != plannedReport.Resolved.Definition.ID {
+			return batchNotificationRequest{}, fmt.Errorf("batch notification report %q run %q does not match planned report %q", item.ReportID, item.RunID, plannedReport.Resolved.Definition.ID)
+		}
+		if item.ReportPath == "" {
+			return batchNotificationRequest{}, fmt.Errorf("batch notification report %q run %q is missing managed report path", item.ReportID, item.RunID)
+		}
+
+		values, err := distributorTemplateValuesForReport(cfg, plannedReport.Resolved, item.RunID, plannedReport.OutputCopyName)
+		if err != nil {
+			return batchNotificationRequest{}, fmt.Errorf("batch notification report %q run %q source path %q: %w", item.ReportID, item.RunID, item.ReportPath, err)
+		}
+		bundlePaths, err := renderDistributorReportBundlePaths(cfg, plannedReport.Resolved, item.RunID, item.ReportPath, values)
+		if err != nil {
+			return batchNotificationRequest{}, err
+		}
+
+		included := BatchNotificationReport{
+			ReportID:    item.ReportID,
+			RunID:       item.RunID,
+			SourcePath:  item.ReportPath,
+			BundlePaths: append([]string(nil), bundlePaths...),
+		}
+		for _, bundlePath := range bundlePaths {
+			file := batchNotificationFile{
+				ReportID:   item.ReportID,
+				RunID:      item.RunID,
+				SourcePath: item.ReportPath,
+				BundlePath: bundlePath,
+			}
+			if previous, ok := seenBundlePaths[bundlePath]; ok {
+				return batchNotificationRequest{}, fmt.Errorf("batch notification duplicate bundle path %q for report %q run %q source path %q; already used by report %q run %q source path %q", bundlePath, item.ReportID, item.RunID, item.ReportPath, previous.ReportID, previous.RunID, previous.SourcePath)
+			}
+			seenBundlePaths[bundlePath] = file
+			req.Files = append(req.Files, file)
+		}
+		req.IncludedReports = append(req.IncludedReports, included)
+	}
+	if len(req.Files) == 0 {
+		return batchNotificationRequest{}, fmt.Errorf("batch notification requires at least one file mapping")
+	}
+	return req, nil
+}
+
+func plannedReportsByRunID(planned []plannedBatchReport) (map[string]plannedBatchReport, error) {
+	byRunID := make(map[string]plannedBatchReport, len(planned))
+	for _, item := range planned {
+		runID := item.Resolved.Metadata().RunID
+		if runID == "" {
+			return nil, fmt.Errorf("planned report %q has empty run id", item.Resolved.Definition.ID)
+		}
+		if previous, ok := byRunID[runID]; ok {
+			return nil, fmt.Errorf("planned reports %q and %q share run id %q", previous.Resolved.Definition.ID, item.Resolved.Definition.ID, runID)
+		}
+		byRunID[runID] = item
+	}
+	return byRunID, nil
+}
+
+func batchDistributorUploadRequest(req batchNotificationRequest) distributoradapter.UploadRequest {
+	files := make([]distributoradapter.UploadFile, 0, len(req.Files))
+	for _, file := range req.Files {
+		files = append(files, distributoradapter.UploadFile{
+			SourcePath: file.SourcePath,
+			BundlePath: file.BundlePath,
+		})
+	}
+	return distributoradapter.UploadRequest{
+		PipelineID:     req.PipelineID,
+		BundleID:       req.BundleID,
+		IdempotencyKey: req.IdempotencyKey,
+		Files:          files,
+		CreatedAt:      req.CreatedAt,
+	}
+}
+
+func batchNotificationResult(req batchNotificationRequest, result *NotificationResult, path string) *BatchNotificationResult {
+	notification := &BatchNotificationResult{
+		Status:          "unknown",
+		PipelineID:      req.PipelineID,
+		BundleID:        req.BundleID,
+		IdempotencyKey:  req.IdempotencyKey,
+		Path:            path,
+		IncludedReports: append([]BatchNotificationReport(nil), req.IncludedReports...),
+	}
+	if result != nil {
+		notification.Status = result.Status
+		notification.RunID = result.RunID
+		if result.PipelineID != "" {
+			notification.PipelineID = result.PipelineID
+		}
+		if result.BundleID != "" {
+			notification.BundleID = result.BundleID
+		}
+		if result.IdempotencyKey != "" {
+			notification.IdempotencyKey = result.IdempotencyKey
+		}
+		if result.Error != "" {
+			notification.Error = result.Error
+		}
+	}
+	if notification.Status == "" {
+		notification.Status = "unknown"
+	}
+	return notification
+}
+
+func failedBatchNotificationResult(req batchNotificationRequest, path string, err error) *BatchNotificationResult {
+	notification := batchNotificationResult(req, nil, path)
+	notification.Status = "failed"
+	if err != nil {
+		notification.Error = err.Error()
+	}
+	return notification
+}
+
+func saveBatchNotificationArtifact(ctx context.Context, store state.Store, cfg config.Config, batch BatchKind, runID string, startedAt time.Time, req batchNotificationRequest, result *NotificationResult, notifyErr error) (string, error) {
+	if store == nil {
+		return "", fmt.Errorf("state store is required")
+	}
+	location, err := timeutil.LoadLocation(cfg.WeatherAPI.Timezone)
+	if err != nil {
+		return "", fmt.Errorf("load batch notification timezone: %w", err)
+	}
+	artifact := state.BatchDistributorNotificationArtifact{
+		SchemaVersion:  state.BatchDistributorNotificationSchemaVersion,
+		Batch:          string(batch),
+		BatchRunID:     runID,
+		AttemptedAt:    time.Now(),
+		Endpoint:       cfg.Notify.Distributor.Endpoint,
+		PipelineID:     req.PipelineID,
+		BundleID:       req.BundleID,
+		IdempotencyKey: req.IdempotencyKey,
+		BundleCreated:  req.CreatedAt,
+		Reports:        batchNotificationReportArtifacts(req.IncludedReports),
+		Status:         "attempted",
+	}
+	if result != nil {
+		artifact.Status = result.Status
+		artifact.Upload = &state.DistributorUploadResult{
+			RunID:  result.RunID,
+			Status: result.UploadStatus,
+		}
+		if result.PipelineID != "" || !result.AcceptedAt.IsZero() || result.StartedAt != nil || result.FinishedAt != nil || len(result.Report) > 0 || result.Error != "" {
+			artifact.RunStatus = &state.DistributorRunStatus{
+				RunID:      result.RunID,
+				PipelineID: result.PipelineID,
+				Status:     result.Status,
+				AcceptedAt: result.AcceptedAt,
+				StartedAt:  result.StartedAt,
+				FinishedAt: result.FinishedAt,
+				Report:     append([]byte(nil), result.Report...),
+				Error:      result.Error,
+			}
+		}
+		artifact.StatusError = result.StatusError
+	}
+	if notifyErr != nil {
+		artifact.Status = "failed"
+		artifact.Error = notifyErr.Error()
+	}
+	if artifact.Status == "" {
+		artifact.Status = "unknown"
+	}
+	return store.SaveBatchDistributorNotification(ctx, state.BatchDistributorNotificationRef{
+		Batch:      string(batch),
+		BatchRunID: runID,
+		StartedAt:  startedAt,
+		Location:   location,
+	}, artifact)
+}
+
+func batchNotificationReportArtifacts(reports []BatchNotificationReport) []state.BatchDistributorNotificationReportArtifact {
+	if len(reports) == 0 {
+		return nil
+	}
+	artifacts := make([]state.BatchDistributorNotificationReportArtifact, 0, len(reports))
+	for _, item := range reports {
+		artifacts = append(artifacts, state.BatchDistributorNotificationReportArtifact{
+			ReportID:    item.ReportID,
+			RunID:       item.RunID,
+			SourcePath:  item.SourcePath,
+			BundlePaths: append([]string(nil), item.BundlePaths...),
+		})
+	}
+	return artifacts
+}
+
+func renderBatchNotificationIdentity(cfg config.Config, batch BatchKind, runID string, startedAt time.Time) (batchNotificationIdentity, error) {
+	values, err := batchNotificationTemplateValues(cfg, batch, runID, startedAt)
+	if err != nil {
+		return batchNotificationIdentity{}, err
+	}
+
+	bundleID, err := config.RenderDistributorBatchBundleID(cfg.Notify.Distributor.Batch.BundleIDTemplate, values)
+	if err != nil {
+		return batchNotificationIdentity{}, err
+	}
+	values.BundleID = bundleID
+
+	pipelineID, err := config.RenderDistributorBatchPipelineID(cfg.Notify.Distributor.Batch.PipelineIDTemplate, values)
+	if err != nil {
+		return batchNotificationIdentity{}, err
+	}
+	idempotencyKey, err := config.RenderDistributorBatchIdempotencyKey(cfg.Notify.Distributor.Batch.IdempotencyKeyTemplate, values)
+	if err != nil {
+		return batchNotificationIdentity{}, err
+	}
+
+	return batchNotificationIdentity{
+		PipelineID:     pipelineID,
+		BundleID:       bundleID,
+		IdempotencyKey: idempotencyKey,
+	}, nil
+}
+
+func batchNotificationTemplateValues(cfg config.Config, batch BatchKind, runID string, startedAt time.Time) (config.DistributorBatchTemplateValues, error) {
+	location, err := timeutil.LoadLocation(cfg.WeatherAPI.Timezone)
+	if err != nil {
+		return config.DistributorBatchTemplateValues{}, fmt.Errorf("load batch notification timezone: %w", err)
+	}
+	return config.DistributorBatchTemplateValues{
+		LocationID:       cfg.Location.ID,
+		Batch:            string(batch),
+		BatchRunID:       runID,
+		BatchStartedDate: startedAt.In(location).Format(timeutil.DateLayout),
+	}, nil
+}

internal/app/batch_plan.go

@@ -0,0 +1,139 @@
+package app
+
+import (
+	"fmt"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/collect"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
+)
+
+type plannedBatchReport struct {
+	Resolved       report.Resolved
+	OutputCopyName string
+}
+
+func planBatchRun(req BatchRequest, now time.Time, collection collect.Result) ([]plannedBatchReport, error) {
+	location, err := timeutil.LoadLocation(req.Config.WeatherAPI.Timezone)
+	if err != nil {
+		return nil, err
+	}
+	batch, err := report.BatchForCommandName(string(req.Batch))
+	if err != nil {
+		return nil, err
+	}
+	registry, err := reportRegistry(req.Config)
+	if err != nil {
+		return nil, err
+	}
+
+	resolveReq := report.ResolveRequest{
+		Now:      now,
+		Location: location,
+	}
+	var planned []plannedBatchReport
+	switch batch {
+	case report.Morning:
+		planned, err = appendPlannedReport(planned, registry, report.Today, resolveReq, "")
+		if err != nil {
+			return nil, err
+		}
+		planned, err = appendPlannedReport(planned, registry, report.Tomorrow, resolveReq, "")
+		if err != nil {
+			return nil, err
+		}
+	case report.Evening:
+		planned, err = appendPlannedReport(planned, registry, report.Tomorrow, resolveReq, "")
+		if err != nil {
+			return nil, err
+		}
+	default:
+		return nil, fmt.Errorf("unknown batch %q", batch)
+	}
+
+	var hourly *weatherdata.ForecastRun
+	if collection.Bundle != nil {
+		hourly = collection.Bundle.Hourly
+	}
+	for _, date := range eligibleDailyDates(hourly, now, location) {
+		dailyReq := resolveReq
+		dailyReq.Date = date
+		outputCopyName := "daily-" + date.In(location).Format(timeutil.DateLayout) + ".md"
+		planned, err = appendPlannedReport(planned, registry, report.Daily, dailyReq, outputCopyName)
+		if err != nil {
+			return nil, err
+		}
+	}
+	return planned, nil
+}
+
+func appendPlannedReport(planned []plannedBatchReport, registry report.Registry, id report.ID, req report.ResolveRequest, outputCopyName string) ([]plannedBatchReport, error) {
+	resolved, err := registry.Resolve(id, req)
+	if err != nil {
+		return nil, err
+	}
+	return append(planned, plannedBatchReport{
+		Resolved:       resolved,
+		OutputCopyName: outputCopyName,
+	}), nil
+}
+
+func eligibleDailyDates(hourly *weatherdata.ForecastRun, now time.Time, location *time.Location) []time.Time {
+	if hourly == nil || location == nil || hourly.Product != "hourly" || len(hourly.Periods) == 0 {
+		return nil
+	}
+
+	hourlyStarts := make(map[time.Time]struct{}, len(hourly.Periods))
+	var maxLocalDate time.Time
+	for _, period := range hourly.Periods {
+		if !isHourlyPeriod(period) {
+			continue
+		}
+		start := period.StartTime
+		hourlyStarts[instantKey(start)] = struct{}{}
+		localDate := localDateStart(start, location)
+		if maxLocalDate.IsZero() || localDate.After(maxLocalDate) {
+			maxLocalDate = localDate
+		}
+	}
+	if len(hourlyStarts) == 0 || maxLocalDate.IsZero() {
+		return nil
+	}
+
+	startDate := localDateStart(now.In(location).AddDate(0, 0, 2), location)
+	var dates []time.Time
+	for candidate := startDate; !candidate.After(maxLocalDate); candidate = candidate.AddDate(0, 0, 1) {
+		if hasFullHourlyCoverage(candidate, location, hourlyStarts) {
+			dates = append(dates, candidate)
+		}
+	}
+	return dates
+}
+
+func isHourlyPeriod(period weatherdata.ForecastPeriod) bool {
+	if period.StartTime.IsZero() || period.EndTime.IsZero() {
+		return false
+	}
+	return period.EndTime.Equal(period.StartTime.Add(time.Hour))
+}
+
+func hasFullHourlyCoverage(date time.Time, location *time.Location, hourlyStarts map[time.Time]struct{}) bool {
+	day := timeutil.CivilDay(date, location)
+	for required := day.Start; required.Before(day.End); required = required.Add(time.Hour) {
+		if _, ok := hourlyStarts[instantKey(required)]; !ok {
+			return false
+		}
+	}
+	return true
+}
+
+func instantKey(value time.Time) time.Time {
+	return value.UTC()
+}
+
+func localDateStart(value time.Time, location *time.Location) time.Time {
+	local := value.In(location)
+	return time.Date(local.Year(), local.Month(), local.Day(), 0, 0, 0, 0, location)
+}

internal/app/batch_plan_test.go

@@ -0,0 +1,352 @@
+package app
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/collect"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
+)
+
+func TestPlanBatchRunMorningOrder(t *testing.T) {
+	location := mustLoadTestLocation(t, "America/Chicago")
+	hourly := hourlyRun(fullDayPeriods(t, "2026-05-31", location)...)
+
+	planned, err := planBatchRun(BatchRequest{Config: planningConfig(), Batch: BatchMorning}, mustParse("2026-05-29T08:00:00-05:00"), collectionWithHourly(hourly))
+	if err != nil {
+		t.Fatalf("planBatchRun() error = %v", err)
+	}
+
+	assertPlannedReportIDs(t, planned, report.Today, report.Tomorrow, report.Daily)
+}
+
+func TestPlanBatchRunEveningOrder(t *testing.T) {
+	location := mustLoadTestLocation(t, "America/Chicago")
+	hourly := hourlyRun(fullDayPeriods(t, "2026-05-31", location)...)
+
+	planned, err := planBatchRun(BatchRequest{Config: planningConfig(), Batch: BatchEvening}, mustParse("2026-05-29T18:00:00-05:00"), collectionWithHourly(hourly))
+	if err != nil {
+		t.Fatalf("planBatchRun() error = %v", err)
+	}
+
+	assertPlannedReportIDs(t, planned, report.Tomorrow, report.Daily)
+}
+
+func TestPlanBatchRunDynamicDailyDatesStartAfterTomorrow(t *testing.T) {
+	location := mustLoadTestLocation(t, "America/Chicago")
+	periods := fullDayPeriods(t, "2026-05-30", location)
+	periods = append(periods, fullDayPeriods(t, "2026-05-31", location)...)
+	periods = append(periods, fullDayPeriods(t, "2026-06-01", location)...)
+
+	planned, err := planBatchRun(BatchRequest{Config: planningConfig(), Batch: BatchMorning}, mustParse("2026-05-29T08:00:00-05:00"), collectionWithHourly(hourlyRun(periods...)))
+	if err != nil {
+		t.Fatalf("planBatchRun() error = %v", err)
+	}
+
+	daily := plannedDailyReports(planned)
+	if len(daily) != 2 {
+		t.Fatalf("daily reports = %#v, want two future Daily reports", daily)
+	}
+	assertPlanningPeriod(t, daily[0].Resolved.ValidPeriod, "2026-05-31T00:00:00-05:00", "2026-06-01T00:00:00-05:00")
+	assertPlanningPeriod(t, daily[1].Resolved.ValidPeriod, "2026-06-01T00:00:00-05:00", "2026-06-02T00:00:00-05:00")
+}
+
+func TestPlanBatchRunMorningExcludesLegacyStaticReports(t *testing.T) {
+	planned, err := planBatchRun(BatchRequest{Config: planningConfig(), Batch: BatchMorning}, mustParse("2026-05-29T08:00:00-05:00"), collect.Result{Bundle: &weatherdata.Bundle{}})
+	if err != nil {
+		t.Fatalf("planBatchRun() error = %v", err)
+	}
+
+	for _, item := range planned {
+		if item.Resolved.Definition.ID == report.ThreeDay || item.Resolved.Definition.ID == report.Weekend {
+			t.Fatalf("morning plan includes %s, want no 3-Day or Weekend", item.Resolved.Definition.ID)
+		}
+	}
+}
+
+func TestPlanBatchRunDynamicDailyOutputCopyNames(t *testing.T) {
+	location := mustLoadTestLocation(t, "America/Chicago")
+	hourly := hourlyRun(fullDayPeriods(t, "2026-05-31", location)...)
+
+	planned, err := planBatchRun(BatchRequest{Config: planningConfig(), Batch: BatchEvening}, mustParse("2026-05-29T18:00:00-05:00"), collectionWithHourly(hourly))
+	if err != nil {
+		t.Fatalf("planBatchRun() error = %v", err)
+	}
+
+	daily := plannedDailyReports(planned)
+	if len(daily) != 1 {
+		t.Fatalf("daily reports = %#v, want one Daily report", daily)
+	}
+	if daily[0].OutputCopyName != "daily-2026-05-31.md" {
+		t.Fatalf("OutputCopyName = %q, want date-qualified Daily name", daily[0].OutputCopyName)
+	}
+	if planned[0].OutputCopyName != "" {
+		t.Fatalf("Tomorrow OutputCopyName = %q, want definition batch output name to apply later", planned[0].OutputCopyName)
+	}
+}
+
+func TestPlanBatchRunRejectsUnknownBatch(t *testing.T) {
+	_, err := planBatchRun(BatchRequest{Config: planningConfig(), Batch: BatchKind("hourly")}, mustParse("2026-05-29T08:00:00-05:00"), collect.Result{Bundle: &weatherdata.Bundle{}})
+	if err == nil || !strings.Contains(err.Error(), `unknown batch command "hourly"`) {
+		t.Fatalf("planBatchRun() error = %v, want unknown batch command", err)
+	}
+}
+
+func TestEligibleDailyDatesRequiresFullOrdinaryLocalDay(t *testing.T) {
+	location := mustLoadTestLocation(t, "America/Chicago")
+	hourly := hourlyRun(fullDayPeriods(t, "2026-05-31", location)...)
+
+	got := eligibleDailyDates(hourly, mustParse("2026-05-29T08:00:00-05:00"), location)
+	assertLocalDates(t, got, location, "2026-05-31")
+}
+
+func TestEligibleDailyDatesMatchesFixedOffsetStartInstants(t *testing.T) {
+	location := mustLoadTestLocation(t, "America/Chicago")
+	hourly := hourlyRun(fixedOffsetPeriods(t, fullDayPeriods(t, "2026-05-31", location))...)
+
+	got := eligibleDailyDates(hourly, mustParse("2026-05-29T08:00:00-05:00"), location)
+	assertLocalDates(t, got, location, "2026-05-31")
+}
+
+func TestEligibleDailyDatesSkipsDayWithMissingRequiredHour(t *testing.T) {
+	location := mustLoadTestLocation(t, "America/Chicago")
+	periods := fullDayPeriods(t, "2026-05-31", location)
+	periods = append(periods[:12], periods[13:]...)
+	hourly := hourlyRun(periods...)
+
+	got := eligibleDailyDates(hourly, mustParse("2026-05-29T08:00:00-05:00"), location)
+	assertLocalDates(t, got, location)
+}
+
+func TestEligibleDailyDatesSkipsPartialFinalDay(t *testing.T) {
+	location := mustLoadTestLocation(t, "America/Chicago")
+	periods := fullDayPeriods(t, "2026-05-31", location)
+	periods = append(periods, partialDayPeriods(t, "2026-06-01", location, 12)...)
+	hourly := hourlyRun(periods...)
+
+	got := eligibleDailyDates(hourly, mustParse("2026-05-29T08:00:00-05:00"), location)
+	assertLocalDates(t, got, location, "2026-05-31")
+}
+
+func TestEligibleDailyDatesStartsAfterTomorrow(t *testing.T) {
+	location := mustLoadTestLocation(t, "America/Chicago")
+	periods := fullDayPeriods(t, "2026-05-29", location)
+	periods = append(periods, fullDayPeriods(t, "2026-05-30", location)...)
+	periods = append(periods, fullDayPeriods(t, "2026-05-31", location)...)
+	hourly := hourlyRun(periods...)
+
+	got := eligibleDailyDates(hourly, mustParse("2026-05-29T08:00:00-05:00"), location)
+	assertLocalDates(t, got, location, "2026-05-31")
+}
+
+func TestEligibleDailyDatesReturnsMultipleFutureDatesInOrder(t *testing.T) {
+	location := mustLoadTestLocation(t, "America/Chicago")
+	periods := fullDayPeriods(t, "2026-05-31", location)
+	periods = append(periods, fullDayPeriods(t, "2026-06-01", location)...)
+	hourly := hourlyRun(periods...)
+
+	got := eligibleDailyDates(hourly, mustParse("2026-05-29T08:00:00-05:00"), location)
+	assertLocalDates(t, got, location, "2026-05-31", "2026-06-01")
+}
+
+func TestEligibleDailyDatesIgnoresNonHourlyAndInvalidPeriods(t *testing.T) {
+	location := mustLoadTestLocation(t, "America/Chicago")
+	day := timeutil.CivilDay(mustParseLocalDate(t, "2026-05-31", location), location)
+	periods := []weatherdata.ForecastPeriod{
+		{StartTime: day.Start, EndTime: day.Start.Add(2 * time.Hour)},
+		{StartTime: day.Start.Add(time.Hour), EndTime: day.Start.Add(time.Hour)},
+		{StartTime: time.Time{}, EndTime: day.Start.Add(3 * time.Hour)},
+	}
+	periods = append(periods, fullDayPeriods(t, "2026-06-01", location)...)
+	hourly := hourlyRun(periods...)
+
+	got := eligibleDailyDates(hourly, mustParse("2026-05-29T08:00:00-05:00"), location)
+	assertLocalDates(t, got, location, "2026-06-01")
+}
+
+func TestEligibleDailyDatesUsesDSTCivilDayInstants(t *testing.T) {
+	location := mustLoadTestLocation(t, "America/New_York")
+	tests := []struct {
+		name string
+		now  string
+		date string
+	}{
+		{
+			name: "spring forward",
+			now:  "2026-03-06T08:00:00-05:00",
+			date: "2026-03-08",
+		},
+		{
+			name: "fall back",
+			now:  "2026-10-30T08:00:00-04:00",
+			date: "2026-11-01",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			hourly := hourlyRun(fullDayPeriods(t, tt.date, location)...)
+
+			got := eligibleDailyDates(hourly, mustParse(tt.now), location)
+			assertLocalDates(t, got, location, tt.date)
+		})
+	}
+}
+
+func TestEligibleDailyDatesReturnsNoneWithoutHourlyForecast(t *testing.T) {
+	location := mustLoadTestLocation(t, "America/Chicago")
+	fullDay := fullDayPeriods(t, "2026-05-31", location)
+
+	tests := []struct {
+		name   string
+		hourly *weatherdata.ForecastRun
+	}{
+		{name: "nil run"},
+		{name: "empty periods", hourly: hourlyRun()},
+		{name: "non-hourly product", hourly: forecastRun("narrative", fullDay...)},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := eligibleDailyDates(tt.hourly, mustParse("2026-05-29T08:00:00-05:00"), location)
+			assertLocalDates(t, got, location)
+		})
+	}
+}
+
+func hourlyRun(periods ...weatherdata.ForecastPeriod) *weatherdata.ForecastRun {
+	return forecastRun("hourly", periods...)
+}
+
+func forecastRun(product string, periods ...weatherdata.ForecastPeriod) *weatherdata.ForecastRun {
+	return &weatherdata.ForecastRun{
+		Product: product,
+		Periods: periods,
+	}
+}
+
+func collectionWithHourly(hourly *weatherdata.ForecastRun) collect.Result {
+	return collect.Result{Bundle: &weatherdata.Bundle{Hourly: hourly}}
+}
+
+func planningConfig() config.Config {
+	cfg := config.Defaults()
+	cfg.WeatherAPI.Timezone = "America/Chicago"
+	return cfg
+}
+
+func assertPlannedReportIDs(t *testing.T, got []plannedBatchReport, want ...report.ID) {
+	t.Helper()
+	gotIDs := make([]string, 0, len(got))
+	for _, item := range got {
+		gotIDs = append(gotIDs, string(item.Resolved.Definition.ID))
+	}
+	wantIDs := make([]string, 0, len(want))
+	for _, id := range want {
+		wantIDs = append(wantIDs, string(id))
+	}
+	if strings.Join(gotIDs, ",") != strings.Join(wantIDs, ",") {
+		t.Fatalf("planned report IDs = [%s], want [%s]", strings.Join(gotIDs, ","), strings.Join(wantIDs, ","))
+	}
+}
+
+func plannedDailyReports(planned []plannedBatchReport) []plannedBatchReport {
+	var daily []plannedBatchReport
+	for _, item := range planned {
+		if item.Resolved.Definition.ID == report.Daily {
+			daily = append(daily, item)
+		}
+	}
+	return daily
+}
+
+func fullDayPeriods(t *testing.T, date string, location *time.Location) []weatherdata.ForecastPeriod {
+	t.Helper()
+	day := timeutil.CivilDay(mustParseLocalDate(t, date, location), location)
+	var periods []weatherdata.ForecastPeriod
+	for start := day.Start; start.Before(day.End); start = start.Add(time.Hour) {
+		periods = append(periods, weatherdata.ForecastPeriod{
+			StartTime: start,
+			EndTime:   start.Add(time.Hour),
+		})
+	}
+	return periods
+}
+
+func partialDayPeriods(t *testing.T, date string, location *time.Location, count int) []weatherdata.ForecastPeriod {
+	t.Helper()
+	periods := fullDayPeriods(t, date, location)
+	if count > len(periods) {
+		count = len(periods)
+	}
+	return periods[:count]
+}
+
+func fixedOffsetPeriods(t *testing.T, periods []weatherdata.ForecastPeriod) []weatherdata.ForecastPeriod {
+	t.Helper()
+	out := make([]weatherdata.ForecastPeriod, 0, len(periods))
+	for _, period := range periods {
+		start, err := time.Parse(time.RFC3339, period.StartTime.Format(time.RFC3339))
+		if err != nil {
+			t.Fatalf("parse fixed-offset start: %v", err)
+		}
+		end, err := time.Parse(time.RFC3339, period.EndTime.Format(time.RFC3339))
+		if err != nil {
+			t.Fatalf("parse fixed-offset end: %v", err)
+		}
+		out = append(out, weatherdata.ForecastPeriod{StartTime: start, EndTime: end})
+	}
+	return out
+}
+
+func assertLocalDates(t *testing.T, got []time.Time, location *time.Location, want ...string) {
+	t.Helper()
+	gotDates := make([]string, 0, len(got))
+	for _, date := range got {
+		gotDates = append(gotDates, date.In(location).Format(timeutil.DateLayout))
+	}
+	if strings.Join(gotDates, ",") != strings.Join(want, ",") {
+		t.Fatalf("eligibleDailyDates() = [%s], want [%s]", strings.Join(gotDates, ","), strings.Join(want, ","))
+	}
+	for _, date := range got {
+		day := timeutil.CivilDay(date, location)
+		if !date.Equal(day.Start) {
+			t.Fatalf("eligible date %s is not local civil day start %s", date, day.Start)
+		}
+	}
+}
+
+func assertPlanningPeriod(t *testing.T, period timeutil.Period, wantStart string, wantEnd string) {
+	t.Helper()
+	if !period.IsValid() {
+		t.Fatalf("period = %#v, want valid", period)
+	}
+	if got := period.Start.Format(time.RFC3339); got != wantStart {
+		t.Fatalf("Start = %s, want %s", got, wantStart)
+	}
+	if got := period.End.Format(time.RFC3339); got != wantEnd {
+		t.Fatalf("End = %s, want %s", got, wantEnd)
+	}
+}
+
+func mustLoadTestLocation(t *testing.T, name string) *time.Location {
+	t.Helper()
+	location, err := time.LoadLocation(name)
+	if err != nil {
+		t.Fatalf("LoadLocation(%q) error = %v", name, err)
+	}
+	return location
+}
+
+func mustParseLocalDate(t *testing.T, value string, location *time.Location) time.Time {
+	t.Helper()
+	parsed, err := timeutil.ParseLocalDate(value, location)
+	if err != nil {
+		t.Fatalf("ParseLocalDate(%q) error = %v", value, err)
+	}
+	return parsed
+}

internal/briefing/alert_digest_module.go

@@ -16,20 +16,24 @@ type AlertDigestModule struct {
 }
 
 type AlertSummary struct {
-	Event    string `json:"event,omitempty"`
-	Headline string `json:"headline,omitempty"`
-	Severity string `json:"severity,omitempty"`
+	Event        string `json:"event,omitempty"`
+	Headline     string `json:"headline,omitempty"`
+	Severity     string `json:"severity,omitempty"`
+	PeriodBegins string `json:"period_begins,omitempty"`
+	PeriodEnds   string `json:"period_ends,omitempty"`
+	Instruction  string `json:"instruction,omitempty"`
+	Description  string `json:"description,omitempty"`
 }
 
 func buildAlertDigestModule(ctx ModuleContext, _ any) (*module.Output, error) {
-	value := alertDigest(ctx.Collected, ctx.Derived.AlertOverlaps)
+	value := alertDigest(ctx.Collected, ctx.Derived.AlertOverlaps, ctx.Timezone)
 	if value == nil {
 		value = &AlertDigestModule{}
 	}
 	return &module.Output{ID: module.AlertDigest, StanzaName: "alert_digest", Value: *value}, nil
 }
 
-func alertDigest(collected facts.CollectedFacts, overlaps []forecast.AlertOverlap) *AlertDigestModule {
+func alertDigest(collected facts.CollectedFacts, overlaps []forecast.AlertOverlap, timezone string) *AlertDigestModule {
 	missing := sourceMissing(collected.SourceProvenance, "alerts")
 	if collected.Alerts == nil && !missing {
 		return nil
@@ -42,9 +46,13 @@ func alertDigest(collected facts.CollectedFacts, overlaps []forecast.AlertOverla
 	value.RelevantCount = len(overlaps)
 	for _, overlap := range overlaps {
 		value.Relevant = append(value.Relevant, AlertSummary{
-			Event:    overlap.Event,
-			Headline: overlap.Headline,
-			Severity: overlap.Severity,
+			Event:        overlap.Event,
+			Headline:     overlap.Headline,
+			Severity:     overlap.Severity,
+			PeriodBegins: friendlyMonthDayTimeLabel(overlap.Period.Start, timezone),
+			PeriodEnds:   friendlyMonthDayTimeLabel(overlap.Period.End, timezone),
+			Instruction:  overlap.Instruction,
+			Description:  overlap.Description,
 		})
 	}
 	return value

internal/briefing/assets/spc_convective_outlook_definitions.json

@@ -0,0 +1,72 @@
+{
+  "categorical:TSTM": {
+    "plain_language": "General or non-severe thunderstorms.",
+    "official_description": "No severe thunderstorms expected.",
+    "relative_level": "0 of 5"
+  },
+  "categorical:MRGL": {
+    "plain_language": "Isolated severe storms possible.",
+    "official_description": "Isolated severe storms may occur within the risk area, but they are expected to be limited in duration, coverage, and intensity.",
+    "relative_level": "1 of 5"
+  },
+  "categorical:SLGT": {
+    "plain_language": "Scattered severe storms possible.",
+    "official_description": "Isolated intense storms are possible within the risk area, but severe weather is generally expected to be short-lived and/or not widespread.",
+    "relative_level": "2 of 5"
+  },
+  "categorical:ENH": {
+    "plain_language": "Numerous severe storms possible.",
+    "official_description": "Numerous severe storms are possible within the risk area, some of which may be intense.",
+    "relative_level": "3 of 5"
+  },
+  "categorical:MDT": {
+    "plain_language": "Widespread severe storms likely.",
+    "official_description": "Widespread severe storms are likely within the risk area. Storms may be long-lived, widespread, and intense. This risk is usually reserved for days with several supercells producing intense tornadoes and/or very large hail, or an intense squall line with widespread damaging winds.",
+    "relative_level": "4 of 5"
+  },
+  "categorical:HIGH": {
+    "plain_language": "Major severe outbreak expected.",
+    "official_description": "A major severe weather outbreak is expected, with long-lived, very widespread, and particularly intense severe storms. This risk is reserved for when high confidence exists in widespread coverage of severe weather with embedded instances of extreme severity (i.e., violent tornadoes or very damaging convective wind events).",
+    "relative_level": "5 of 5"
+  },
+  "tornado:CIG1": {
+    "plain_language": "Conditional potential for significant tornadoes.",
+    "official_description": "Intensity Level 1: Reasonable Max EF2. Note that this product describes the reasonable maximum intensity of a hazard if that hazard occurs. It does not by itself indicate the probability that the hazard will occur.",
+    "relative_level": "1 of 3"
+  },
+  "tornado:CIG2": {
+    "plain_language": "Conditional potential for strong tornadoes.",
+    "official_description": "Intensity Level 2: Reasonable Max EF3. Note that this product describes the reasonable maximum intensity of a hazard if that hazard occurs. It does not by itself indicate the probability that the hazard will occur.",
+    "relative_level": "2 of 3"
+  },
+  "tornado:CIG3": {
+    "plain_language": "Conditional potential for violent tornadoes.",
+    "official_description": "Intensity Level 3: Reasonable Max EF4 or higher. Note that this product describes the reasonable maximum intensity of a hazard if that hazard occurs. It does not by itself indicate the probability that the hazard will occur.",
+    "relative_level": "3 of 3"
+  },
+  "wind:CIG1": {
+    "plain_language": "Conditional potential for significant severe wind.",
+    "official_description": "Intensity Level 1: Reasonable Max wind gusts around 65 kt / 75 mph or higher. Note that this product describes the reasonable maximum intensity of a hazard if that hazard occurs. It does not by itself indicate the probability that the hazard will occur.",
+    "relative_level": "1 of 3"
+  },
+  "wind:CIG2": {
+    "plain_language": "Conditional potential for intense severe wind.",
+    "official_description": "Intensity Level 2: Reasonable Max wind gusts around 75 kt / 85 mph or higher. Note that this product describes the reasonable maximum intensity of a hazard if that hazard occurs. It does not by itself indicate the probability that the hazard will occur.",
+    "relative_level": "2 of 3"
+  },
+  "wind:CIG3": {
+    "plain_language": "Conditional potential for extreme severe wind.",
+    "official_description": "Intensity Level 3: Reasonable Max wind gusts around 100 kt / 115 mph or higher. Note that this product describes the reasonable maximum intensity of a hazard if that hazard occurs. It does not by itself indicate the probability that the hazard will occur.",
+    "relative_level": "3 of 3"
+  },
+  "hail:CIG1": {
+    "plain_language": "Conditional potential for significant hail.",
+    "official_description": "Intensity Level 1: Reasonable Max hail size around 2.00 to 3.75 inches. Note that this product describes the reasonable maximum intensity of a hazard if that hazard occurs. It does not by itself indicate the probability that the hazard will occur.",
+    "relative_level": "1 of 2"
+  },
+  "hail:CIG2": {
+    "plain_language": "Conditional potential for giant hail.",
+    "official_description": "Intensity Level 2: Reasonable Max hail size greater than 3.75 inches. Note that this product describes the reasonable maximum intensity of a hazard if that hazard occurs. It does not by itself indicate the probability that the hazard will occur.",
+    "relative_level": "2 of 2"
+  }
+}

internal/briefing/base_modules_test.go

@@ -59,21 +59,24 @@ func TestHourlyForecastModuleUsesValidPeriodHourlyPeriods(t *testing.T) {
 		t.Fatalf("HourlyForecast = %#v, want hourly metadata and one valid-period period", value)
 	}
 	period := value.Periods[0]
-	if period.TextDescription != "Showers likely." || period.TemperatureF == nil || *period.TemperatureF != 76 {
+	if period.HourLabel != "8:00 AM" || period.TextDescription != "Showers likely." || period.TextDescriptionLower != "showers likely." || period.TemperatureF == nil || *period.TemperatureF != 76 {
 		t.Fatalf("HourlyForecast period = %#v, want hourly period facts", period)
 	}
-	if period.StartTime != "2026-05-29 at 8:00 AM" || period.EndTime != "2026-05-29 at 9:00 AM" {
-		t.Fatalf("HourlyForecast period times = %q/%q, want friendly local time labels", period.StartTime, period.EndTime)
+	if period.PeriodBegins != "2026-05-29 at 8:00 AM" || period.PeriodEnds != "2026-05-29 at 9:00 AM" {
+		t.Fatalf("HourlyForecast period times = %q/%q, want friendly local time labels", period.PeriodBegins, period.PeriodEnds)
 	}
 	if period.WindDirection != "S" || period.ProbabilityOfPrecipitationPercent == nil || *period.ProbabilityOfPrecipitationPercent != 70 {
 		t.Fatalf("HourlyForecast period = %#v, want compass wind and precip chance", period)
 	}
+	if !period.MentionPrecipitation {
+		t.Fatalf("MentionPrecipitation = false, want true for default threshold")
+	}
 	data, err := json.Marshal(output.Value)
 	if err != nil {
 		t.Fatalf("Marshal hourly forecast: %v", err)
 	}
 	jsonText := string(data)
-	for _, field := range []string{"source_location_id", "text_description", "temperature_f", "wind_direction", "probability_of_precipitation_percent", "relative_humidity_percent"} {
+	for _, field := range []string{"source_location_id", "hour_label", "period_begins", "period_ends", "text_description", "text_description_lower", "temperature_f", "wind_direction", "probability_of_precipitation_percent", "mention_precipitation", "relative_humidity_percent"} {
 		if !strings.Contains(jsonText, field) {
 			t.Fatalf("hourly json = %s, want field %s", jsonText, field)
 		}
@@ -81,8 +84,71 @@ func TestHourlyForecastModuleUsesValidPeriodHourlyPeriods(t *testing.T) {
 	if strings.Contains(jsonText, "wind_direction_degrees") || strings.Contains(jsonText, "Tomorrow") {
 		t.Fatalf("hourly json = %s, want valid-period prompt fields only", jsonText)
 	}
-	if strings.Contains(jsonText, `"start_time":"2026-05-29T`) || strings.Contains(jsonText, `"end_time":"2026-05-29T`) {
-		t.Fatalf("hourly json = %s, want friendly local start/end times", jsonText)
+	if strings.Contains(jsonText, `"start_time"`) || strings.Contains(jsonText, `"end_time"`) {
+		t.Fatalf("hourly json = %s, want period_begins/period_ends instead of start_time/end_time", jsonText)
+	}
+}
+
+func TestHourlyForecastPromptExportOmitsTemplateHelpers(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := testModuleContext()
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.HourlyForecast})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	richText := mustMarshalModuleJSON(t, output.Value)
+	for _, field := range []string{"hour_label", "text_description_lower", "mention_precipitation"} {
+		if !strings.Contains(richText, field) {
+			t.Fatalf("rich hourly json = %s, want helper field %s", richText, field)
+		}
+	}
+
+	prompt := moduleDataPackageValue[HourlyForecastPromptExport](t, output)
+	if prompt.Product != "hourly" || prompt.SourceLocationID != "test-grid" || len(prompt.Periods) != 1 {
+		t.Fatalf("hourly prompt export = %#v, want hourly metadata and one period", prompt)
+	}
+	period := prompt.Periods[0]
+	if period.PeriodBegins != "2026-05-29 at 8:00 AM" || period.PeriodEnds != "2026-05-29 at 9:00 AM" || period.TextDescription != "Showers likely." {
+		t.Fatalf("hourly prompt period = %#v, want factual period fields", period)
+	}
+	if period.TemperatureF == nil || *period.TemperatureF != 76 || period.WindSpeedMph == nil || *period.WindSpeedMph != 14 || period.ProbabilityOfPrecipitationPercent == nil || *period.ProbabilityOfPrecipitationPercent != 70 {
+		t.Fatalf("hourly prompt period = %#v, want temperature, wind, and precip fields", period)
+	}
+	if period.WindDirection != "S" || period.RelativeHumidityPercent == nil || *period.RelativeHumidityPercent != 66 {
+		t.Fatalf("hourly prompt period = %#v, want wind direction and humidity", period)
+	}
+	promptText := mustMarshalModuleJSON(t, output.DataPackageValue())
+	for _, field := range []string{"period_begins", "period_ends", "text_description", "temperature_f", "wind_direction", "probability_of_precipitation_percent", "relative_humidity_percent"} {
+		if !strings.Contains(promptText, field) {
+			t.Fatalf("hourly prompt json = %s, want field %s", promptText, field)
+		}
+	}
+	for _, field := range []string{"hour_label", "text_description_lower", "mention_precipitation"} {
+		if strings.Contains(promptText, field) {
+			t.Fatalf("hourly prompt json = %s, want omitted helper field %s", promptText, field)
+		}
+	}
+}
+
+func TestHourlyForecastPrecipMentionThreshold(t *testing.T) {
+	periods := []weatherdata.ForecastPeriod{
+		{StartTime: mustParseModuleTime("2026-05-29T08:00:00-05:00"), ProbabilityOfPrecipitationPercent: floatPtr(19)},
+		{StartTime: mustParseModuleTime("2026-05-29T09:00:00-05:00"), ProbabilityOfPrecipitationPercent: floatPtr(20)},
+		{StartTime: mustParseModuleTime("2026-05-29T10:00:00-05:00")},
+	}
+	value := hourlyForecastPeriodsWithPrecipMentionThreshold(periods, "America/Chicago", DefaultHourlyForecastPrecipMentionProbabilityThreshold)
+	if len(value) != 3 {
+		t.Fatalf("periods length = %d, want 3", len(value))
+	}
+	if value[0].MentionPrecipitation {
+		t.Fatalf("19%% MentionPrecipitation = true, want false")
+	}
+	if !value[1].MentionPrecipitation {
+		t.Fatalf("20%% MentionPrecipitation = false, want true")
+	}
+	if value[2].MentionPrecipitation {
+		t.Fatalf("nil MentionPrecipitation = true, want false")
 	}
 }
 
@@ -97,6 +163,21 @@ func TestHourlyForecastModuleRejectsUnsupportedReports(t *testing.T) {
 	}
 }
 
+func TestHourlyForecastModuleBuildsForHourly(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := testModuleContext()
+	ctx.Resolved.Definition = report.DefaultRegistry().MustLookup(report.Hourly)
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.HourlyForecast})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	value := moduleValue[HourlyForecastModule](t, output)
+	if len(value.Periods) != 1 || value.Periods[0].TextDescription != "Showers likely." {
+		t.Fatalf("HourlyForecast = %#v, want hourly report period", value)
+	}
+}
+
 func TestNarrativeForecastModuleUsesValidPeriodNarrativePeriods(t *testing.T) {
 	registry := MustDefaultModuleRegistry()
 	ctx := testModuleContext()
@@ -113,8 +194,8 @@ func TestNarrativeForecastModuleUsesValidPeriodNarrativePeriods(t *testing.T) {
 	if period.Name != "Today" || period.TextDescription != "Morning storms, then partly sunny." {
 		t.Fatalf("NarrativeForecast period = %#v, want Today narrative", period)
 	}
-	if period.StartTime != "2026-05-29 at 6:00 AM" || period.EndTime != "2026-05-29 at 6:00 PM" {
-		t.Fatalf("NarrativeForecast period times = %q/%q, want friendly local time labels", period.StartTime, period.EndTime)
+	if period.PeriodBegins != "2026-05-29 at 6:00 AM" || period.PeriodEnds != "2026-05-29 at 6:00 PM" {
+		t.Fatalf("NarrativeForecast period times = %q/%q, want friendly local time labels", period.PeriodBegins, period.PeriodEnds)
 	}
 	if period.IsDay == nil || !*period.IsDay || period.TemperatureF == nil || *period.TemperatureF != 81 || period.ProbabilityOfPrecipitationPercent == nil || *period.ProbabilityOfPrecipitationPercent != 60 {
 		t.Fatalf("NarrativeForecast period = %#v, want day, temperature, and precip values", period)
@@ -127,7 +208,7 @@ func TestNarrativeForecastModuleUsesValidPeriodNarrativePeriods(t *testing.T) {
 		t.Fatalf("Marshal narrative forecast: %v", err)
 	}
 	jsonText := string(data)
-	for _, field := range []string{"source_location_id", "text_description", "temperature_f", "wind_speed_mph", "wind_direction", "probability_of_precipitation_percent"} {
+	for _, field := range []string{"source_location_id", "period_begins", "period_ends", "text_description", "temperature_f", "wind_speed_mph", "wind_direction", "probability_of_precipitation_percent"} {
 		if !strings.Contains(jsonText, field) {
 			t.Fatalf("narrative json = %s, want field %s", jsonText, field)
 		}
@@ -135,8 +216,8 @@ func TestNarrativeForecastModuleUsesValidPeriodNarrativePeriods(t *testing.T) {
 	if strings.Contains(jsonText, "wind_direction_degrees") {
 		t.Fatalf("narrative json = %s, want compass wind_direction without degrees field", jsonText)
 	}
-	if strings.Contains(jsonText, `"start_time":"2026-05-29T`) || strings.Contains(jsonText, `"end_time":"2026-05-29T`) {
-		t.Fatalf("narrative json = %s, want friendly local start/end times", jsonText)
+	if strings.Contains(jsonText, `"start_time"`) || strings.Contains(jsonText, `"end_time"`) {
+		t.Fatalf("narrative json = %s, want period_begins/period_ends instead of start_time/end_time", jsonText)
 	}
 	if strings.Contains(jsonText, "Tomorrow night") {
 		t.Fatalf("narrative json = %s, want only valid-period narrative periods", jsonText)
@@ -163,7 +244,7 @@ func TestMetadataModuleUsesPromptSafeSourceWarningSummary(t *testing.T) {
 		t.Fatalf("BuildModule() error = %v", err)
 	}
 	value := moduleValue[MetadataModule](t, output)
-	if value.RunID == "" || value.ReportID != report.DailyToday || value.PromptID != "weather.daily_report" {
+	if value.RunID == "" || value.ReportID != report.Daily || value.PromptID != "weather.daily_generated_text" {
 		t.Fatalf("metadata = %#v, want report identity", value)
 	}
 	if value.Location == nil || value.Location.Name != "Brentwood" {
@@ -172,9 +253,6 @@ func TestMetadataModuleUsesPromptSafeSourceWarningSummary(t *testing.T) {
 	if len(value.SourceWarnings) != 1 || value.SourceWarnings[0].CompletenessImpact != "source omitted" {
 		t.Fatalf("SourceWarnings = %#v, want warning summary", value.SourceWarnings)
 	}
-	if value.Alerts == nil || !value.Alerts.Checked || value.Alerts.ActiveCount != 1 || value.Alerts.RelevantCount != 1 {
-		t.Fatalf("Alerts = %#v, want checked alert status", value.Alerts)
-	}
 	data, err := json.Marshal(output.Value)
 	if err != nil {
 		t.Fatalf("Marshal metadata: %v", err)
@@ -183,6 +261,9 @@ func TestMetadataModuleUsesPromptSafeSourceWarningSummary(t *testing.T) {
 	if !strings.Contains(jsonText, "source_warnings") || strings.Contains(jsonText, "endpoint") || strings.Contains(jsonText, "dataSha256") {
 		t.Fatalf("metadata json = %s, want source warning summary without transport provenance", jsonText)
 	}
+	if strings.Contains(jsonText, `"alerts"`) {
+		t.Fatalf("metadata json = %s, want alert details only in alert_digest", jsonText)
+	}
 }
 
 func TestCurrentConditionsModuleUsesSnakeCaseUnitFields(t *testing.T) {
@@ -194,18 +275,24 @@ func TestCurrentConditionsModuleUsesSnakeCaseUnitFields(t *testing.T) {
 		t.Fatalf("BuildModule() error = %v", err)
 	}
 	value := moduleValue[CurrentConditionsModule](t, output)
-	if value.ConditionText != "Partly cloudy" || value.TemperatureF == nil || *value.TemperatureF != 74 {
-		t.Fatalf("CurrentConditions = %#v, want current condition facts", value)
+	if value.ConditionText != "Partly cloudy" || value.ConditionTextLower != "partly cloudy" || value.TemperatureF == nil || *value.TemperatureF != 74 {
+		t.Fatalf("CurrentConditions = %#v, want rounded current condition facts", value)
+	}
+	if value.ApparentTemperatureF == nil || *value.ApparentTemperatureF != 76 || value.RelativeHumidityPercent == nil || *value.RelativeHumidityPercent != 71 || value.WindSpeedMph == nil || *value.WindSpeedMph != 8 {
+		t.Fatalf("CurrentConditions rounded values = %#v, want apparent 76, humidity 71, wind 8", value)
 	}
 	if value.WindDirection != "S" {
 		t.Fatalf("WindDirection = %q, want S", value.WindDirection)
 	}
+	if value.WindDirectionText != "south" {
+		t.Fatalf("WindDirectionText = %q, want south", value.WindDirectionText)
+	}
 	data, err := json.Marshal(output.Value)
 	if err != nil {
 		t.Fatalf("Marshal current conditions: %v", err)
 	}
 	jsonText := string(data)
-	for _, field := range []string{"condition_text", "temperature_f", "apparent_temperature_f", "relative_humidity_percent", "wind_speed_mph", "wind_direction"} {
+	for _, field := range []string{"condition_text", "condition_text_lower", "temperature_f", "apparent_temperature_f", "relative_humidity_percent", "wind_speed_mph", "wind_direction", "wind_direction_text"} {
 		if !strings.Contains(jsonText, field) {
 			t.Fatalf("current json = %s, want field %s", jsonText, field)
 		}
@@ -215,6 +302,44 @@ func TestCurrentConditionsModuleUsesSnakeCaseUnitFields(t *testing.T) {
 	}
 }
 
+func TestCurrentConditionsPromptExportOmitsTemplateHelpers(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := testModuleContext()
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.CurrentConditions})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	richText := mustMarshalModuleJSON(t, output.Value)
+	for _, field := range []string{"condition_text_lower", "wind_direction_text"} {
+		if !strings.Contains(richText, field) {
+			t.Fatalf("rich current conditions json = %s, want helper field %s", richText, field)
+		}
+	}
+
+	prompt := moduleDataPackageValue[CurrentConditionsPromptExport](t, output)
+	if prompt.ConditionText != "Partly cloudy" || prompt.TemperatureF == nil || *prompt.TemperatureF != 74 {
+		t.Fatalf("current prompt export = %#v, want condition text and temperature", prompt)
+	}
+	if prompt.ApparentTemperatureF == nil || *prompt.ApparentTemperatureF != 76 || prompt.RelativeHumidityPercent == nil || *prompt.RelativeHumidityPercent != 71 || prompt.WindSpeedMph == nil || *prompt.WindSpeedMph != 8 {
+		t.Fatalf("current prompt export = %#v, want apparent temperature, humidity, and wind speed", prompt)
+	}
+	if prompt.WindDirection != "S" {
+		t.Fatalf("current prompt wind direction = %q, want S", prompt.WindDirection)
+	}
+	promptText := mustMarshalModuleJSON(t, output.DataPackageValue())
+	for _, field := range []string{"condition_text", "temperature_f", "apparent_temperature_f", "relative_humidity_percent", "wind_speed_mph", "wind_direction"} {
+		if !strings.Contains(promptText, field) {
+			t.Fatalf("current prompt json = %s, want field %s", promptText, field)
+		}
+	}
+	for _, field := range []string{"condition_text_lower", "wind_direction_text"} {
+		if strings.Contains(promptText, field) {
+			t.Fatalf("current prompt json = %s, want omitted helper field %s", promptText, field)
+		}
+	}
+}
+
 func TestAlertDigestDistinguishesCheckedEmptyAndMissing(t *testing.T) {
 	registry := MustDefaultModuleRegistry()
 	ctx := testModuleContext()
@@ -242,6 +367,39 @@ func TestAlertDigestDistinguishesCheckedEmptyAndMissing(t *testing.T) {
 	}
 }
 
+func TestAlertDigestIncludesPeriodAndGuidance(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := testModuleContext()
+	ctx.Collected.Alerts = &weatherdata.AlertRun{Alerts: []json.RawMessage{json.RawMessage(`{"event":"Wind Advisory"}`)}}
+	ctx.Derived.AlertOverlaps = []forecast.AlertOverlap{{
+		Event:       "Wind Advisory",
+		Headline:    "Wind Advisory until 8 PM",
+		Severity:    "Moderate",
+		Period:      timeutil.Period{Start: mustParseModuleTime("2026-06-17T18:00:00Z"), End: mustParseModuleTime("2026-06-18T01:00:00Z")},
+		Instruction: "Secure outdoor objects.",
+		Description: "Gusty winds may blow around unsecured objects.",
+	}}
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.AlertDigest})
+	if err != nil {
+		t.Fatalf("BuildModule(alert digest) error = %v", err)
+	}
+	value := moduleValue[AlertDigestModule](t, output)
+	if len(value.Relevant) != 1 {
+		t.Fatalf("Relevant length = %d, want 1", len(value.Relevant))
+	}
+	alert := value.Relevant[0]
+	if alert.Event != "Wind Advisory" || alert.Headline != "Wind Advisory until 8 PM" || alert.Severity != "Moderate" {
+		t.Fatalf("alert identity = %#v, want preserved event/headline/severity", alert)
+	}
+	if alert.PeriodBegins != "June 17 at 1:00 PM" || alert.PeriodEnds != "June 17 at 8:00 PM" {
+		t.Fatalf("alert period = %q/%q, want friendly local labels", alert.PeriodBegins, alert.PeriodEnds)
+	}
+	if alert.Instruction != "Secure outdoor objects." || alert.Description != "Gusty winds may blow around unsecured objects." {
+		t.Fatalf("alert guidance = %#v, want instruction and description preserved", alert)
+	}
+}
+
 func TestBaseModulesOmitMissingOptionalOutputs(t *testing.T) {
 	registry := MustDefaultModuleRegistry()
 	ctx := testModuleContext()
@@ -285,13 +443,19 @@ func TestAreaForecastDiscussionAndWeatherStoryModules(t *testing.T) {
 	if !story.Available || story.Title != "Rain Chances" || story.Description != "Scattered showers are possible." {
 		t.Fatalf("WeatherStory = %#v, want structured story fields", story)
 	}
+	if story.PeriodBegins != "2026-05-29 at 6:00 AM" || story.PeriodEnds != "2026-05-29 at 6:00 PM" {
+		t.Fatalf("WeatherStory period = %q/%q, want friendly local period labels", story.PeriodBegins, story.PeriodEnds)
+	}
 	data, err := json.Marshal(storyOutput.Value)
 	if err != nil {
 		t.Fatalf("Marshal weather story: %v", err)
 	}
-	if !strings.Contains(string(data), "download_url") {
+	if !strings.Contains(string(data), "download_url") || !strings.Contains(string(data), "period_begins") || !strings.Contains(string(data), "period_ends") {
 		t.Fatalf("weather story json = %s, want snake_case download_url", string(data))
 	}
+	if strings.Contains(string(data), "start_time") || strings.Contains(string(data), "end_time") {
+		t.Fatalf("weather story json = %s, want period_begins/period_ends instead of start_time/end_time", string(data))
+	}
 }
 
 func TestAreaForecastDiscussionModuleCanSelectSections(t *testing.T) {
@@ -314,9 +478,65 @@ func TestAreaForecastDiscussionModuleCanSelectSections(t *testing.T) {
 	}
 }
 
+func TestAreaForecastDiscussionModuleUsesHourlyDefaultSections(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := testModuleContext()
+	ctx.Resolved.Definition = report.DefaultRegistry().MustLookup(report.Hourly)
+	var item module.ConfigItem
+	for _, candidate := range ctx.Resolved.Definition.Modules {
+		if candidate.ID == module.AreaForecastDiscussion {
+			item = candidate
+			break
+		}
+	}
+	if item.ID == "" {
+		t.Fatal("hourly default modules missing area_forecast_discussion")
+	}
+
+	output, err := registry.BuildModule(ctx, item)
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	afd := moduleValue[AreaForecastDiscussionModule](t, output)
+	if len(afd.KeyMessages) != 1 || afd.ShortTerm != "Showers increase this afternoon." {
+		t.Fatalf("AFD = %#v, want key messages and short term", afd)
+	}
+	if afd.Product != "" || afd.LongTerm != "" {
+		t.Fatalf("AFD = %#v, want product and long term omitted", afd)
+	}
+}
+
+func TestAreaForecastDiscussionModuleUsesDailyDefaultSections(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := testModuleContext()
+	ctx.Resolved.Definition = report.DefaultRegistry().MustLookup(report.Daily)
+	var item module.ConfigItem
+	for _, candidate := range ctx.Resolved.Definition.Modules {
+		if candidate.ID == module.AreaForecastDiscussion {
+			item = candidate
+			break
+		}
+	}
+	if item.ID == "" {
+		t.Fatal("daily default modules missing area_forecast_discussion")
+	}
+
+	output, err := registry.BuildModule(ctx, item)
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	afd := moduleValue[AreaForecastDiscussionModule](t, output)
+	if afd.LongTerm != "Periodic rain chances continue." {
+		t.Fatalf("LongTerm = %q, want selected long term section", afd.LongTerm)
+	}
+	if afd.Product != "" || len(afd.KeyMessages) != 0 || afd.ShortTerm != "" {
+		t.Fatalf("AFD = %#v, want only long term section", afd)
+	}
+}
+
 func testModuleContext() ModuleContext {
 	generatedAt := mustParseModuleTime("2026-05-29T08:00:00-05:00")
-	definition := report.DefaultRegistry().MustLookup(report.DailyToday)
+	definition := report.DefaultRegistry().MustLookup(report.Daily)
 	resolved := report.Resolved{
 		Definition:  definition,
 		GeneratedAt: generatedAt,
@@ -327,10 +547,10 @@ func testModuleContext() ModuleContext {
 		},
 	}
 	isDay := true
-	tempF := 74.0
-	apparentF := 76.0
-	humidity := 71.0
-	windMph := 8.0
+	tempF := 74.4
+	apparentF := 75.6
+	humidity := 70.6
+	windMph := 8.4
 	windDirection := 190.0
 	narrativeTempF := 81.0
 	narrativePop := 60.0
@@ -484,6 +704,28 @@ func moduleValue[T any](t *testing.T, output *module.Output) T {
 	return value
 }
 
+func moduleDataPackageValue[T any](t *testing.T, output *module.Output) T {
+	t.Helper()
+	var value T
+	data, err := json.Marshal(output.DataPackageValue())
+	if err != nil {
+		t.Fatalf("marshal module data package value: %v", err)
+	}
+	if err := json.Unmarshal(data, &value); err != nil {
+		t.Fatalf("decode module data package value: %v", err)
+	}
+	return value
+}
+
+func mustMarshalModuleJSON(t *testing.T, value any) string {
+	t.Helper()
+	data, err := json.Marshal(value)
+	if err != nil {
+		t.Fatalf("marshal module value: %v", err)
+	}
+	return string(data)
+}
+
 func mustParseModuleTime(value string) time.Time {
 	parsed, err := time.Parse(time.RFC3339, value)
 	if err != nil {

internal/briefing/current_conditions_module.go

@@ -1,20 +1,41 @@
 package briefing
 
-import "gitea.maximumdirect.net/eric/weatherreporter/internal/module"
+import (
+	"strings"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/module"
+)
 
 type CurrentConditionsModule struct {
-	ConditionText           string   `json:"condition_text,omitempty"`
-	IsDay                   *bool    `json:"is_day,omitempty"`
-	TemperatureC            *float64 `json:"temperature_c,omitempty"`
-	TemperatureF            *float64 `json:"temperature_f,omitempty"`
-	ApparentTemperatureC    *float64 `json:"apparent_temperature_c,omitempty"`
-	ApparentTemperatureF    *float64 `json:"apparent_temperature_f,omitempty"`
-	DewpointC               *float64 `json:"dewpoint_c,omitempty"`
-	DewpointF               *float64 `json:"dewpoint_f,omitempty"`
-	RelativeHumidityPercent *float64 `json:"relative_humidity_percent,omitempty"`
-	WindSpeedKmh            *float64 `json:"wind_speed_kmh,omitempty"`
-	WindSpeedMph            *float64 `json:"wind_speed_mph,omitempty"`
-	WindDirection           string   `json:"wind_direction,omitempty"`
+	ConditionText           string `json:"condition_text,omitempty"`
+	ConditionTextLower      string `json:"condition_text_lower,omitempty"`
+	IsDay                   *bool  `json:"is_day,omitempty"`
+	TemperatureC            *int   `json:"temperature_c,omitempty"`
+	TemperatureF            *int   `json:"temperature_f,omitempty"`
+	ApparentTemperatureC    *int   `json:"apparent_temperature_c,omitempty"`
+	ApparentTemperatureF    *int   `json:"apparent_temperature_f,omitempty"`
+	DewpointC               *int   `json:"dewpoint_c,omitempty"`
+	DewpointF               *int   `json:"dewpoint_f,omitempty"`
+	RelativeHumidityPercent *int   `json:"relative_humidity_percent,omitempty"`
+	WindSpeedKmh            *int   `json:"wind_speed_kmh,omitempty"`
+	WindSpeedMph            *int   `json:"wind_speed_mph,omitempty"`
+	WindDirection           string `json:"wind_direction,omitempty"`
+	WindDirectionText       string `json:"wind_direction_text,omitempty"`
+}
+
+type CurrentConditionsPromptExport struct {
+	ConditionText           string `json:"condition_text,omitempty"`
+	IsDay                   *bool  `json:"is_day,omitempty"`
+	TemperatureC            *int   `json:"temperature_c,omitempty"`
+	TemperatureF            *int   `json:"temperature_f,omitempty"`
+	ApparentTemperatureC    *int   `json:"apparent_temperature_c,omitempty"`
+	ApparentTemperatureF    *int   `json:"apparent_temperature_f,omitempty"`
+	DewpointC               *int   `json:"dewpoint_c,omitempty"`
+	DewpointF               *int   `json:"dewpoint_f,omitempty"`
+	RelativeHumidityPercent *int   `json:"relative_humidity_percent,omitempty"`
+	WindSpeedKmh            *int   `json:"wind_speed_kmh,omitempty"`
+	WindSpeedMph            *int   `json:"wind_speed_mph,omitempty"`
+	WindDirection           string `json:"wind_direction,omitempty"`
 }
 
 func buildCurrentConditionsModule(ctx ModuleContext, _ any) (*module.Output, error) {
@@ -24,17 +45,19 @@ func buildCurrentConditionsModule(ctx ModuleContext, _ any) (*module.Output, err
 	}
 	value := CurrentConditionsModule{
 		ConditionText:           current.ConditionText,
+		ConditionTextLower:      strings.ToLower(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),
+		TemperatureC:            roundedInt(current.TemperatureC),
+		TemperatureF:            roundedInt(current.TemperatureF),
+		ApparentTemperatureC:    roundedInt(current.ApparentTemperatureC),
+		ApparentTemperatureF:    roundedInt(current.ApparentTemperatureF),
+		DewpointC:               roundedInt(current.DewpointC),
+		DewpointF:               roundedInt(current.DewpointF),
+		RelativeHumidityPercent: roundedInt(current.RelativeHumidityPercent),
+		WindSpeedKmh:            roundedInt(current.WindSpeedKmh),
+		WindSpeedMph:            roundedInt(current.WindSpeedMph),
 		WindDirection:           windDirectionLabel(current.WindDirectionDegrees),
+		WindDirectionText:       windDirectionTextLabel(current.WindDirectionDegrees),
 	}
 	if value.isEmpty() {
 		return nil, nil
@@ -42,8 +65,30 @@ func buildCurrentConditionsModule(ctx ModuleContext, _ any) (*module.Output, err
 	return &module.Output{ID: module.CurrentConditions, StanzaName: "current_conditions", Value: value}, nil
 }
 
+func exportCurrentConditionsPromptValue(value any) (any, error) {
+	rich, ok := value.(CurrentConditionsModule)
+	if !ok {
+		return nil, unexpectedPromptExportValue(value, CurrentConditionsModule{})
+	}
+	return CurrentConditionsPromptExport{
+		ConditionText:           rich.ConditionText,
+		IsDay:                   copyBool(rich.IsDay),
+		TemperatureC:            copyInt(rich.TemperatureC),
+		TemperatureF:            copyInt(rich.TemperatureF),
+		ApparentTemperatureC:    copyInt(rich.ApparentTemperatureC),
+		ApparentTemperatureF:    copyInt(rich.ApparentTemperatureF),
+		DewpointC:               copyInt(rich.DewpointC),
+		DewpointF:               copyInt(rich.DewpointF),
+		RelativeHumidityPercent: copyInt(rich.RelativeHumidityPercent),
+		WindSpeedKmh:            copyInt(rich.WindSpeedKmh),
+		WindSpeedMph:            copyInt(rich.WindSpeedMph),
+		WindDirection:           rich.WindDirection,
+	}, nil
+}
+
 func (v CurrentConditionsModule) isEmpty() bool {
 	return v.ConditionText == "" &&
+		v.ConditionTextLower == "" &&
 		v.IsDay == nil &&
 		v.TemperatureC == nil &&
 		v.TemperatureF == nil &&
@@ -54,5 +99,6 @@ func (v CurrentConditionsModule) isEmpty() bool {
 		v.RelativeHumidityPercent == nil &&
 		v.WindSpeedKmh == nil &&
 		v.WindSpeedMph == nil &&
-		v.WindDirection == ""
+		v.WindDirection == "" &&
+		v.WindDirectionText == ""
 }

internal/briefing/daily_planning_module.go

@@ -0,0 +1,24 @@
+package briefing
+
+import "gitea.maximumdirect.net/eric/weatherreporter/internal/module"
+
+type DailyPlanningModule struct {
+	MorningReadiness             []string `json:"morning_readiness,omitempty"`
+	CommuteSchoolWorkdayConcerns []string `json:"commute_school_workday_concerns,omitempty"`
+	OvernightChangeWatch         []string `json:"overnight_change_watch,omitempty"`
+}
+
+func buildDailyPlanningModule(ctx ModuleContext, _ any) (*module.Output, error) {
+	summary := ctx.Derived.FirstDailySummary()
+	if summary == nil {
+		return &module.Output{ID: module.DailyPlanning, StanzaName: "daily_planning", Value: DailyPlanningModule{}}, nil
+	}
+	planning := buildMorningCommuteOvernightPlanning(summary)
+	value := DailyPlanningModule{}
+	if planning != nil {
+		value.MorningReadiness = append([]string(nil), planning.MorningReadiness...)
+		value.CommuteSchoolWorkdayConcerns = append([]string(nil), planning.CommuteSchoolWorkdayConcerns...)
+		value.OvernightChangeWatch = append([]string(nil), planning.OvernightChangeWatch...)
+	}
+	return &module.Output{ID: module.DailyPlanning, StanzaName: "daily_planning", Value: value}, nil
+}

internal/briefing/derived_daypart_summaries_module.go

@@ -2,32 +2,74 @@ package briefing
 
 import (
 	"fmt"
+	"sort"
 	"strings"
 	"unicode"
 
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/module"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
 )
 
 type DerivedDaypartSummaryModule struct {
-	Date               string   `json:"date,omitempty"`
-	Period             string   `json:"period,omitempty"`
-	TempRangeF         string   `json:"temp_range_f,omitempty"`
-	ApparentTempRangeF string   `json:"apparent_temp_range_f,omitempty"`
-	MaxPopPercent      *int     `json:"max_pop_percent,omitempty"`
-	MaxPopTime         string   `json:"max_pop_time,omitempty"`
-	MaxWindGustMph     *int     `json:"max_wind_gust_mph,omitempty"`
-	MaxWindGustTime    string   `json:"max_wind_gust_time,omitempty"`
-	DominantCondition  string   `json:"dominant_condition,omitempty"`
-	NotableConditions  []string `json:"notable_conditions,omitempty"`
-	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"`
-	RelevantAlertCount int      `json:"relevant_alert_count,omitempty"`
+	Date                     string   `json:"date,omitempty"`
+	DisplayName              string   `json:"display_name,omitempty"`
+	PeriodBegins             string   `json:"period_begins,omitempty"`
+	PeriodEnds               string   `json:"period_ends,omitempty"`
+	TempRangeF               string   `json:"temp_range_f,omitempty"`
+	TemperaturePhraseF       string   `json:"temperature_phrase_f,omitempty"`
+	ApparentTempRangeF       string   `json:"apparent_temp_range_f,omitempty"`
+	MaxPopPercent            *int     `json:"max_pop_percent,omitempty"`
+	MaxPopTime               string   `json:"max_pop_time,omitempty"`
+	MaxPopTimeLabel          string   `json:"max_pop_time_label,omitempty"`
+	MentionPrecipitation     bool     `json:"mention_precipitation,omitempty"`
+	MaxWindGustMph           *int     `json:"max_wind_gust_mph,omitempty"`
+	MaxWindGustTime          string   `json:"max_wind_gust_time,omitempty"`
+	DominantCondition        string   `json:"dominant_condition,omitempty"`
+	DominantConditionLower   string   `json:"dominant_condition_lower,omitempty"`
+	DominantConditionDisplay string   `json:"dominant_condition_display,omitempty"`
+	TemperatureTrend         string   `json:"temperature_trend,omitempty"`
+	TemperatureStartPhraseF  string   `json:"temperature_start_phrase_f,omitempty"`
+	TemperatureEndPhraseF    string   `json:"temperature_end_phrase_f,omitempty"`
+	TemperaturePeakPhraseF   string   `json:"temperature_peak_phrase_f,omitempty"`
+	TemperatureSteadyPhraseF string   `json:"temperature_steady_phrase_f,omitempty"`
+	NotableConditions        []string `json:"notable_conditions,omitempty"`
+	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"`
+	RelevantAlertCount       int      `json:"relevant_alert_count,omitempty"`
+}
+
+type DerivedDaypartSummaryPromptExport struct {
+	Date                     string   `json:"date,omitempty"`
+	DisplayName              string   `json:"display_name,omitempty"`
+	PeriodBegins             string   `json:"period_begins,omitempty"`
+	PeriodEnds               string   `json:"period_ends,omitempty"`
+	TempRangeF               string   `json:"temp_range_f,omitempty"`
+	ApparentTempRangeF       string   `json:"apparent_temp_range_f,omitempty"`
+	MaxPopPercent            *int     `json:"max_pop_percent,omitempty"`
+	MaxPopTime               string   `json:"max_pop_time,omitempty"`
+	MentionPrecipitation     bool     `json:"mention_precipitation,omitempty"`
+	MaxWindGustMph           *int     `json:"max_wind_gust_mph,omitempty"`
+	MaxWindGustTime          string   `json:"max_wind_gust_time,omitempty"`
+	DominantCondition        string   `json:"dominant_condition,omitempty"`
+	TemperatureTrend         string   `json:"temperature_trend,omitempty"`
+	TemperatureStartPhraseF  string   `json:"temperature_start_phrase_f,omitempty"`
+	TemperatureEndPhraseF    string   `json:"temperature_end_phrase_f,omitempty"`
+	TemperaturePeakPhraseF   string   `json:"temperature_peak_phrase_f,omitempty"`
+	TemperatureSteadyPhraseF string   `json:"temperature_steady_phrase_f,omitempty"`
+	NotableConditions        []string `json:"notable_conditions,omitempty"`
+	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"`
+	RelevantAlertCount       int      `json:"relevant_alert_count,omitempty"`
 }
 
 func buildDerivedDaypartSummariesModule(ctx ModuleContext, _ any) (*module.Output, error) {
@@ -43,25 +85,84 @@ func buildDerivedDaypartSummariesModule(ctx ModuleContext, _ any) (*module.Outpu
 	return &module.Output{ID: module.DerivedDaypartSummaries, StanzaName: "derived_daypart_summaries", Value: value}, nil
 }
 
+func exportDerivedDaypartSummariesPromptValue(value any) (any, error) {
+	rich, ok := value.(map[string]DerivedDaypartSummaryModule)
+	if !ok {
+		return nil, unexpectedPromptExportValue(value, map[string]DerivedDaypartSummaryModule{})
+	}
+	out := make(map[string]DerivedDaypartSummaryPromptExport, len(rich))
+	for key, daypart := range rich {
+		out[key] = derivedDaypartSummaryPromptValue(daypart)
+	}
+	return out, nil
+}
+
+func derivedDaypartSummaryPromptValue(rich DerivedDaypartSummaryModule) DerivedDaypartSummaryPromptExport {
+	maxPopTime := rich.MaxPopTime
+	if rich.MaxPopTimeLabel != "" {
+		maxPopTime = rich.MaxPopTimeLabel
+	}
+	return DerivedDaypartSummaryPromptExport{
+		Date:                     rich.Date,
+		DisplayName:              rich.DisplayName,
+		PeriodBegins:             rich.PeriodBegins,
+		PeriodEnds:               rich.PeriodEnds,
+		TempRangeF:               rich.TempRangeF,
+		ApparentTempRangeF:       rich.ApparentTempRangeF,
+		MaxPopPercent:            copyInt(rich.MaxPopPercent),
+		MaxPopTime:               maxPopTime,
+		MentionPrecipitation:     rich.MentionPrecipitation,
+		MaxWindGustMph:           copyInt(rich.MaxWindGustMph),
+		MaxWindGustTime:          rich.MaxWindGustTime,
+		DominantCondition:        rich.DominantCondition,
+		TemperatureTrend:         rich.TemperatureTrend,
+		TemperatureStartPhraseF:  rich.TemperatureStartPhraseF,
+		TemperatureEndPhraseF:    rich.TemperatureEndPhraseF,
+		TemperaturePeakPhraseF:   rich.TemperaturePeakPhraseF,
+		TemperatureSteadyPhraseF: rich.TemperatureSteadyPhraseF,
+		NotableConditions:        append([]string(nil), rich.NotableConditions...),
+		Snow:                     rich.Snow,
+		Ice:                      rich.Ice,
+		Fog:                      rich.Fog,
+		Heat:                     rich.Heat,
+		Cold:                     rich.Cold,
+		Wind:                     rich.Wind,
+		RelevantAlertCount:       rich.RelevantAlertCount,
+	}
+}
+
 func derivedDaypartSummaryValue(daypart forecast.DaypartSummary, timezone string) DerivedDaypartSummaryModule {
+	temperature := daypartTemperatureDisplay(daypart)
 	value := DerivedDaypartSummaryModule{
-		Date:               localDateLabel(daypart.Period.Start, timezone),
-		Period:             friendlyPeriodLabel(daypart.Period, timezone),
-		TempRangeF:         rangeLabel(daypart.Temperature),
-		ApparentTempRangeF: daypartApparentRangeLabel(daypart.ApparentTemperature),
-		DominantCondition:  daypart.DominantCondition,
-		NotableConditions:  append([]string(nil), daypart.NotableConditions...),
-		Snow:               daypart.Indicators.Snow,
-		Ice:                daypart.Indicators.Ice,
-		Fog:                daypart.Indicators.Fog,
-		Heat:               daypart.Indicators.Heat,
-		Cold:               daypart.Indicators.Cold,
-		Wind:               daypart.Indicators.Wind,
-		RelevantAlertCount: len(daypart.AlertOverlaps),
+		Date:                     localDateLabel(daypart.Period.Start, timezone),
+		DisplayName:              titleWord(strings.TrimSpace(daypart.Name)),
+		PeriodBegins:             friendlyPeriodBeginsLabel(daypart.Period, timezone),
+		PeriodEnds:               friendlyPeriodEndsLabel(daypart.Period, timezone),
+		TempRangeF:               rangeLabel(daypart.Temperature),
+		TemperaturePhraseF:       temperaturePhraseF(daypart.Temperature),
+		TemperatureTrend:         temperature.Trend,
+		TemperatureStartPhraseF:  temperature.StartPhrase,
+		TemperatureEndPhraseF:    temperature.EndPhrase,
+		TemperaturePeakPhraseF:   temperature.PeakPhrase,
+		TemperatureSteadyPhraseF: temperature.SteadyPhrase,
+		ApparentTempRangeF:       daypartApparentRangeLabel(daypart.ApparentTemperature),
+		DominantCondition:        daypart.DominantCondition,
+		DominantConditionLower:   strings.ToLower(daypart.DominantCondition),
+		DominantConditionDisplay: sentenceCase(daypart.DominantCondition),
+		NotableConditions:        append([]string(nil), daypart.NotableConditions...),
+		Snow:                     daypart.Indicators.Snow,
+		Ice:                      daypart.Indicators.Ice,
+		Fog:                      daypart.Indicators.Fog,
+		Heat:                     daypart.Indicators.Heat,
+		Cold:                     daypart.Indicators.Cold,
+		Wind:                     daypart.Indicators.Wind,
+		RelevantAlertCount:       len(daypart.AlertOverlaps),
 	}
 	if daypart.MaxPrecipitationProbability != nil {
 		value.MaxPopPercent = roundedInt(&daypart.MaxPrecipitationProbability.Value)
 		value.MaxPopTime = clockLabel(daypart.MaxPrecipitationProbability.Time, timezone)
+		value.MaxPopTimeLabel = hourMinuteLabel(daypart.MaxPrecipitationProbability.Time, timezone)
+		value.MentionPrecipitation = mentionHourlyForecastPrecipitation(&daypart.MaxPrecipitationProbability.Value, DefaultHourlyForecastPrecipMentionProbabilityThreshold)
 	}
 	if daypart.PeakWindGust != nil {
 		value.MaxWindGustMph = roundedInt(&daypart.PeakWindGust.Value)
@@ -70,6 +171,208 @@ func derivedDaypartSummaryValue(daypart forecast.DaypartSummary, timezone string
 	return value
 }
 
+type daypartTemperaturePresentation struct {
+	Trend        string
+	StartPhrase  string
+	EndPhrase    string
+	PeakPhrase   string
+	SteadyPhrase string
+}
+
+type temperaturePoint struct {
+	value     int
+	bandIndex int
+	phrase    string
+}
+
+const (
+	temperatureTrendRising  = "rising"
+	temperatureTrendFalling = "falling"
+	temperatureTrendPeaking = "peaking"
+	temperatureTrendSteady  = "steady"
+)
+
+func daypartTemperatureDisplay(daypart forecast.DaypartSummary) daypartTemperaturePresentation {
+	points := daypartTemperaturePoints(daypart.HourlyPeriods)
+	if len(points) == 0 {
+		return daypartSteadyTemperatureDisplay(temperaturePhraseF(daypart.Temperature))
+	}
+	if len(points) == 1 {
+		return daypartSteadyTemperatureDisplay(points[0].phrase)
+	}
+
+	first := points[0]
+	last := points[len(points)-1]
+	peak, peakIndex := peakTemperaturePoint(points)
+	if peakIndex > 0 && peakIndex < len(points)-1 && peak.bandIndex > first.bandIndex && peak.bandIndex > last.bandIndex {
+		return daypartTemperaturePresentation{
+			Trend:      temperatureTrendPeaking,
+			PeakPhrase: peak.phrase,
+		}
+	}
+	switch {
+	case first.bandIndex < last.bandIndex:
+		return daypartTemperaturePresentation{
+			Trend:       temperatureTrendRising,
+			StartPhrase: first.phrase,
+			EndPhrase:   last.phrase,
+		}
+	case first.bandIndex > last.bandIndex:
+		return daypartTemperaturePresentation{
+			Trend:       temperatureTrendFalling,
+			StartPhrase: first.phrase,
+			EndPhrase:   last.phrase,
+		}
+	default:
+		return daypartSteadyTemperatureDisplay(temperaturePhraseF(daypart.Temperature))
+	}
+}
+
+func daypartSteadyTemperatureDisplay(phrase string) daypartTemperaturePresentation {
+	if phrase == "" {
+		return daypartTemperaturePresentation{}
+	}
+	return daypartTemperaturePresentation{
+		Trend:        temperatureTrendSteady,
+		SteadyPhrase: phrase,
+	}
+}
+
+func daypartTemperaturePoints(periods []weatherdata.ForecastPeriod) []temperaturePoint {
+	sorted := append([]weatherdata.ForecastPeriod(nil), periods...)
+	sort.SliceStable(sorted, func(i int, j int) bool {
+		return sorted[i].StartTime.Before(sorted[j].StartTime)
+	})
+	points := make([]temperaturePoint, 0, len(sorted))
+	for _, period := range sorted {
+		temperature := forecastPeriodTemperatureF(period)
+		if temperature == nil {
+			continue
+		}
+		rounded := roundedInt(temperature)
+		if rounded == nil {
+			continue
+		}
+		points = append(points, temperaturePoint{
+			value:     *rounded,
+			bandIndex: temperatureBandIndex(*rounded),
+			phrase:    temperatureBandPhrase(*rounded),
+		})
+	}
+	return points
+}
+
+func peakTemperaturePoint(points []temperaturePoint) (temperaturePoint, int) {
+	peak := points[0]
+	peakIndex := 0
+	for index, point := range points[1:] {
+		if point.value > peak.value {
+			peak = point
+			peakIndex = index + 1
+		}
+	}
+	return peak, peakIndex
+}
+
+func forecastPeriodTemperatureF(period weatherdata.ForecastPeriod) *float64 {
+	switch {
+	case period.TemperatureF != nil:
+		return period.TemperatureF
+	case period.TemperatureFMax != nil:
+		return period.TemperatureFMax
+	case period.TemperatureFMin != nil:
+		return period.TemperatureFMin
+	case period.TemperatureC != nil:
+		value := celsiusToFahrenheit(*period.TemperatureC)
+		return &value
+	case period.TemperatureCMax != nil:
+		value := celsiusToFahrenheit(*period.TemperatureCMax)
+		return &value
+	case period.TemperatureCMin != nil:
+		value := celsiusToFahrenheit(*period.TemperatureCMin)
+		return &value
+	default:
+		return nil
+	}
+}
+
+func celsiusToFahrenheit(value float64) float64 {
+	return value*9/5 + 32
+}
+
+func temperatureBandIndex(value int) int {
+	decade := (value / 10) * 10
+	remainder := value - decade
+	if remainder < 0 {
+		remainder = -remainder
+	}
+	band := 1
+	switch {
+	case remainder <= 3:
+		band = 0
+	case remainder >= 7:
+		band = 2
+	}
+	return decade*3 + band
+}
+
+func temperaturePhraseF(value forecast.Range) string {
+	if value.Min == nil && value.Max == nil {
+		return ""
+	}
+	if value.Min != nil && value.Max != nil {
+		low := roundedInt(value.Min)
+		high := roundedInt(value.Max)
+		if low == nil || high == nil {
+			return ""
+		}
+		lowPhrase := temperatureBandPhrase(*low)
+		highPhrase := temperatureBandPhrase(*high)
+		if lowPhrase == highPhrase {
+			return lowPhrase
+		}
+		return lowPhrase + " to " + highPhrase
+	}
+	if value.Min != nil {
+		low := roundedInt(value.Min)
+		if low == nil {
+			return ""
+		}
+		return temperatureBandPhrase(*low)
+	}
+	high := roundedInt(value.Max)
+	if high == nil {
+		return ""
+	}
+	return temperatureBandPhrase(*high)
+}
+
+func temperatureBandPhrase(value int) string {
+	decade := (value / 10) * 10
+	remainder := value - decade
+	if remainder < 0 {
+		remainder = -remainder
+	}
+	qualifier := "mid"
+	switch {
+	case remainder <= 3:
+		qualifier = "low"
+	case remainder >= 7:
+		qualifier = "upper"
+	}
+	return fmt.Sprintf("%s %ds", qualifier, decade)
+}
+
+func sentenceCase(value string) string {
+	trimmed := strings.TrimSpace(value)
+	if trimmed == "" {
+		return ""
+	}
+	runes := []rune(trimmed)
+	runes[0] = unicode.ToUpper(runes[0])
+	return string(runes)
+}
+
 func multipleSummaryDates(summaries []forecast.DailySummary) bool {
 	seen := map[string]struct{}{}
 	for _, summary := range summaries {

internal/briefing/derived_modules_test.go

@@ -16,7 +16,7 @@ import (
 
 func TestDerivedDailySummaryModulePackagesOrdinaryForecast(t *testing.T) {
 	registry := MustDefaultModuleRegistry()
-	ctx := derivedModuleContext(report.DailyToday)
+	ctx := derivedModuleContext(report.Daily)
 
 	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.DerivedDailySummary})
 	if err != nil {
@@ -67,7 +67,7 @@ func TestDerivedDailySummaryModulePackagesOrdinaryForecast(t *testing.T) {
 
 func TestDerivedDailySummaryModuleFallsBackWithoutNarrativeFacts(t *testing.T) {
 	registry := MustDefaultModuleRegistry()
-	ctx := derivedModuleContext(report.DailyToday)
+	ctx := derivedModuleContext(report.Daily)
 	ctx.Derived.DailySummaries[0].NarrativePeriods = nil
 
 	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.DerivedDailySummary})
@@ -89,7 +89,7 @@ func TestDerivedDailySummaryModuleFallsBackWithoutNarrativeFacts(t *testing.T) {
 
 func TestPrecipTimingModuleHandlesRainyAndDryForecasts(t *testing.T) {
 	registry := MustDefaultModuleRegistry()
-	ctx := derivedModuleContext(report.DailyToday)
+	ctx := derivedModuleContext(report.Daily)
 
 	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.PrecipTiming})
 	if err != nil {
@@ -102,19 +102,31 @@ func TestPrecipTimingModuleHandlesRainyAndDryForecasts(t *testing.T) {
 	if len(rainy.PrecipitationWindows) != 2 {
 		t.Fatalf("rainy precipitation windows = %#v, want two windows", rainy.PrecipitationWindows)
 	}
-	if rainy.PrecipitationWindows[0].Start != "8 AM" || rainy.PrecipitationWindows[0].End != "9 AM" || rainy.PrecipitationWindows[0].MaxPopPercent == nil || *rainy.PrecipitationWindows[0].MaxPopPercent != 60 {
+	if rainy.PrecipitationWindows[0].PeriodBegins != "2026-05-29 at 8:00 AM" || rainy.PrecipitationWindows[0].PeriodBeginsHourLabel != "8:00 AM" || rainy.PrecipitationWindows[0].PeriodEnds != "2026-05-29 at 9:00 AM" || rainy.PrecipitationWindows[0].PeriodEndsHourLabel != "9:00 AM" || rainy.PrecipitationWindows[0].MaxPopPercent == nil || *rainy.PrecipitationWindows[0].MaxPopPercent != 60 || rainy.PrecipitationWindows[0].MaxPopHourLabel != "8:00 AM" {
 		t.Fatalf("first precipitation window = %#v, want 8-9 AM at 60%%", rainy.PrecipitationWindows[0])
 	}
-	if rainy.PrecipitationWindows[1].Start != "12 PM" || rainy.PrecipitationWindows[1].End != "2 PM" || rainy.PrecipitationWindows[1].MaxPopPercent == nil || *rainy.PrecipitationWindows[1].MaxPopPercent != 80 {
+	if rainy.PrecipitationWindows[0].PrecipitationType != "showers" || rainy.PrecipitationWindows[0].ExpectationPhrase != "Showers likely." {
+		t.Fatalf("first precipitation window phrase = %#v, want showers likely", rainy.PrecipitationWindows[0])
+	}
+	if rainy.PrecipitationWindows[1].PeriodBegins != "2026-05-29 at 12:00 PM" || rainy.PrecipitationWindows[1].PeriodBeginsHourLabel != "12:00 PM" || rainy.PrecipitationWindows[1].PeriodEnds != "2026-05-29 at 2:00 PM" || rainy.PrecipitationWindows[1].PeriodEndsHourLabel != "2:00 PM" || rainy.PrecipitationWindows[1].MaxPopPercent == nil || *rainy.PrecipitationWindows[1].MaxPopPercent != 80 || rainy.PrecipitationWindows[1].MaxPopHourLabel != "12:00 PM" {
 		t.Fatalf("second precipitation window = %#v, want noon-2 PM at 80%%", rainy.PrecipitationWindows[1])
 	}
+	if rainy.PrecipitationWindows[1].PrecipitationType != "showers and thunderstorms" || rainy.PrecipitationWindows[1].ExpectationPhrase != "Expect showers and thunderstorms." {
+		t.Fatalf("second precipitation window phrase = %#v, want expect showers and thunderstorms", rainy.PrecipitationWindows[1])
+	}
 	data, err := json.Marshal(output.Value)
 	if err != nil {
 		t.Fatalf("marshal precip timing: %v", err)
 	}
-	if !strings.Contains(string(data), "precipitation_windows") || !strings.Contains(string(data), "probability_threshold") {
+	if !strings.Contains(string(data), "precipitation_windows") || !strings.Contains(string(data), "probability_threshold") || !strings.Contains(string(data), "period_begins_hour_label") || !strings.Contains(string(data), "max_pop_hour_label") {
 		t.Fatalf("precip timing json = %s, want threshold and windows", string(data))
 	}
+	if !strings.Contains(string(data), "precipitation_type") || !strings.Contains(string(data), "expectation_phrase") {
+		t.Fatalf("precip timing json = %s, want precipitation type and expectation phrase", string(data))
+	}
+	if strings.Contains(string(data), `"start"`) || strings.Contains(string(data), `"end"`) {
+		t.Fatalf("precip timing json = %s, want period_begins/period_ends instead of start/end", string(data))
+	}
 	if strings.Contains(string(data), "first_precip_hour") || strings.Contains(string(data), "last_precip_hour") {
 		t.Fatalf("precip timing json = %s, want no ambiguous first/last fields", string(data))
 	}
@@ -133,9 +145,119 @@ func TestPrecipTimingModuleHandlesRainyAndDryForecasts(t *testing.T) {
 	}
 }
 
+func TestPrecipTimingModuleBuildsExpectationPhrases(t *testing.T) {
+	now := mustParseModuleTime("2026-05-29T08:00:00-05:00")
+	tests := []struct {
+		name         string
+		maxPop       float64
+		descriptions []string
+		wantType     string
+		wantPhrase   string
+	}{
+		{
+			name:         "chance lower bound",
+			maxPop:       40,
+			descriptions: []string{"Scattered showers"},
+			wantType:     "showers",
+			wantPhrase:   "Chance of showers.",
+		},
+		{
+			name:         "chance upper bound",
+			maxPop:       49,
+			descriptions: []string{"Rain possible"},
+			wantType:     "rain",
+			wantPhrase:   "Chance of rain.",
+		},
+		{
+			name:         "likely lower bound",
+			maxPop:       50,
+			descriptions: []string{"Drizzle"},
+			wantType:     "drizzle",
+			wantPhrase:   "Drizzle likely.",
+		},
+		{
+			name:         "likely upper bound",
+			maxPop:       69,
+			descriptions: []string{"Freezing rain"},
+			wantType:     "freezing rain",
+			wantPhrase:   "Freezing rain likely.",
+		},
+		{
+			name:         "expect lower bound",
+			maxPop:       70,
+			descriptions: []string{"Snow"},
+			wantType:     "snow",
+			wantPhrase:   "Expect snow.",
+		},
+		{
+			name:         "showers and thunderstorms preferred",
+			maxPop:       100,
+			descriptions: []string{"Showers likely", "Thunderstorms possible"},
+			wantType:     "showers and thunderstorms",
+			wantPhrase:   "Expect showers and thunderstorms.",
+		},
+		{
+			name:         "thunderstorms only",
+			maxPop:       80,
+			descriptions: []string{"Thunderstorms"},
+			wantType:     "thunderstorms",
+			wantPhrase:   "Expect thunderstorms.",
+		},
+		{
+			name:         "unknown fallback",
+			maxPop:       95,
+			descriptions: []string{"Unsettled conditions"},
+			wantType:     "precipitation",
+			wantPhrase:   "Expect precipitation.",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			value := precipTimingValue(forecast.PrecipTiming{
+				ProbabilityThreshold: forecast.DefaultPrecipWindowProbabilityThreshold,
+				PrecipitationWindows: []forecast.PrecipitationWindow{
+					{
+						Start: now,
+						MaxPrecipitationProbability: forecast.TimedValue{
+							Value: tt.maxPop,
+							Time:  now,
+						},
+						ProbabilityThreshold: forecast.DefaultPrecipWindowProbabilityThreshold,
+						TextDescriptions:     tt.descriptions,
+					},
+				},
+			}, "America/Chicago")
+			if len(value.PrecipitationWindows) != 1 {
+				t.Fatalf("PrecipitationWindows = %#v, want one window", value.PrecipitationWindows)
+			}
+			window := value.PrecipitationWindows[0]
+			if window.PrecipitationType != tt.wantType || window.ExpectationPhrase != tt.wantPhrase {
+				t.Fatalf("window = %#v, want type %q and phrase %q", window, tt.wantType, tt.wantPhrase)
+			}
+		})
+	}
+}
+
+func TestPrecipTimingModuleUsesDerivedTimingWithoutDaypartSummaries(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := derivedModuleContext(report.Hourly)
+	ctx.Derived.DailySummaries = nil
+	ctx.Derived.DaypartSummaries = nil
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.PrecipTiming})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	value := moduleValue[PrecipTimingModule](t, output)
+	if value.MaxPopPercent == nil || *value.MaxPopPercent != 80 || len(value.PrecipitationWindows) != 2 {
+		t.Fatalf("precip timing = %#v, want derived timing without daypart summaries", value)
+	}
+}
+
 func TestDerivedDaypartSummariesExposeConfiguredKeysAndHazards(t *testing.T) {
 	registry := MustDefaultModuleRegistry()
-	ctx := derivedModuleContext(report.DailyToday)
+	ctx := derivedModuleContext(report.Daily)
 
 	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.DerivedDaypartSummaries})
 	if err != nil {
@@ -150,14 +272,20 @@ func TestDerivedDaypartSummariesExposeConfiguredKeysAndHazards(t *testing.T) {
 	if morning.TempRangeF != "58" || morning.MaxPopPercent == nil || *morning.MaxPopPercent != 60 {
 		t.Fatalf("morning = %#v, want temp range and precip peak", morning)
 	}
-	if morning.Date != "2026-05-29" || morning.Period != "2026-05-29 at 6:00 AM to 2026-05-29 at 12:00 PM" {
-		t.Fatalf("morning period = %q/%q, want friendly local date and period labels", morning.Date, morning.Period)
+	if morning.DisplayName != "Morning" || morning.DominantConditionLower != "showers" || morning.DominantConditionDisplay != "Showers" || morning.TemperaturePhraseF != "upper 50s" || morning.TemperatureTrend != "steady" || morning.TemperatureSteadyPhraseF != "upper 50s" || !morning.MentionPrecipitation || morning.MaxPopTimeLabel != "6:00 AM" {
+		t.Fatalf("morning presentation fields = %#v, want display facts for template composition", morning)
+	}
+	if morning.Date != "2026-05-29" || morning.PeriodBegins != "2026-05-29 at 6:00 AM" || morning.PeriodEnds != "2026-05-29 at 12:00 PM" {
+		t.Fatalf("morning period = %q/%q/%q, want friendly local date and period labels", morning.Date, morning.PeriodBegins, morning.PeriodEnds)
+	}
+	overnight := value["overnight"]
+	if overnight.MentionPrecipitation {
+		t.Fatalf("overnight MentionPrecipitation = true, want false below threshold")
 	}
 	afternoon := value["afternoon"]
 	if !afternoon.Heat || !afternoon.Wind || afternoon.MaxWindGustMph == nil || *afternoon.MaxWindGustMph != 42 {
 		t.Fatalf("afternoon = %#v, want heat and wind hazard values", afternoon)
 	}
-	overnight := value["overnight"]
 	if !overnight.Cold {
 		t.Fatalf("overnight = %#v, want cold hazard", overnight)
 	}
@@ -166,19 +294,236 @@ func TestDerivedDaypartSummariesExposeConfiguredKeysAndHazards(t *testing.T) {
 		t.Fatalf("marshal daypart summaries: %v", err)
 	}
 	jsonText := string(data)
-	for _, field := range []string{"date", "period", "temp_range_f", "max_pop_percent", "max_wind_gust_mph", "dominant_condition"} {
+	for _, field := range []string{"date", "display_name", "period_begins", "period_ends", "temp_range_f", "temperature_phrase_f", "temperature_trend", "temperature_steady_phrase_f", "max_pop_percent", "max_pop_time_label", "mention_precipitation", "max_wind_gust_mph", "dominant_condition", "dominant_condition_lower", "dominant_condition_display"} {
 		if !strings.Contains(jsonText, field) {
 			t.Fatalf("daypart json = %s, want field %s", jsonText, field)
 		}
 	}
-	if strings.Contains(jsonText, `"period":{"start"`) || strings.Contains(jsonText, `T06:00:00`) {
+	if strings.Contains(jsonText, `"period":`) || strings.Contains(jsonText, `T06:00:00`) {
 		t.Fatalf("daypart json = %s, want friendly period label instead of raw timestamps", jsonText)
 	}
 }
 
+func TestDerivedDaypartSummariesPromptExportOmitsTemplateHelpers(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := derivedModuleContext(report.Daily)
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.DerivedDaypartSummaries})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	richText := mustMarshalModuleJSON(t, output.Value)
+	for _, field := range []string{"temperature_phrase_f", "dominant_condition_lower", "dominant_condition_display", "max_pop_time_label"} {
+		if !strings.Contains(richText, field) {
+			t.Fatalf("rich daypart json = %s, want helper field %s", richText, field)
+		}
+	}
+
+	prompt := moduleDataPackageValue[map[string]DerivedDaypartSummaryPromptExport](t, output)
+	morning, ok := prompt["morning"]
+	if !ok {
+		t.Fatalf("daypart prompt keys = %#v, want morning", prompt)
+	}
+	if morning.Date != "2026-05-29" || morning.DisplayName != "Morning" || morning.PeriodBegins != "2026-05-29 at 6:00 AM" || morning.PeriodEnds != "2026-05-29 at 12:00 PM" {
+		t.Fatalf("morning prompt period = %#v, want date/display/period labels", morning)
+	}
+	if morning.TempRangeF != "58" || morning.MaxPopPercent == nil || *morning.MaxPopPercent != 60 || morning.MaxPopTime != "6:00 AM" || !morning.MentionPrecipitation {
+		t.Fatalf("morning prompt precip/temp = %#v, want factual prompt fields with friendly max pop time", morning)
+	}
+	if morning.DominantCondition != "Showers" || morning.TemperatureTrend != "steady" || morning.TemperatureSteadyPhraseF != "upper 50s" {
+		t.Fatalf("morning prompt condition/trend = %#v, want condition and trend fields", morning)
+	}
+	if len(morning.NotableConditions) == 0 || morning.NotableConditions[0] != "Showers" {
+		t.Fatalf("morning prompt notable conditions = %#v, want copied conditions", morning.NotableConditions)
+	}
+	afternoon := prompt["afternoon"]
+	if !afternoon.Heat || !afternoon.Wind || afternoon.MaxWindGustMph == nil || *afternoon.MaxWindGustMph != 42 || afternoon.RelevantAlertCount != 1 {
+		t.Fatalf("afternoon prompt = %#v, want hazard, wind, and alert fields", afternoon)
+	}
+
+	promptText := mustMarshalModuleJSON(t, output.DataPackageValue())
+	for _, field := range []string{"date", "display_name", "period_begins", "period_ends", "temp_range_f", "max_pop_percent", "max_pop_time", "mention_precipitation", "max_wind_gust_mph", "dominant_condition", "temperature_trend", "temperature_steady_phrase_f", "notable_conditions", "relevant_alert_count"} {
+		if !strings.Contains(promptText, field) {
+			t.Fatalf("daypart prompt json = %s, want field %s", promptText, field)
+		}
+	}
+	for _, field := range []string{"temperature_phrase_f", "dominant_condition_lower", "dominant_condition_display", "max_pop_time_label"} {
+		if strings.Contains(promptText, field) {
+			t.Fatalf("daypart prompt json = %s, want omitted helper field %s", promptText, field)
+		}
+	}
+}
+
+func TestDerivedDaypartPromptExportTemperatureTrends(t *testing.T) {
+	tests := []struct {
+		name       string
+		temps      []float64
+		wantTrend  string
+		wantStart  string
+		wantEnd    string
+		wantPeak   string
+		wantSteady string
+	}{
+		{
+			name:      "rising",
+			temps:     []float64{58, 68},
+			wantTrend: "rising",
+			wantStart: "upper 50s",
+			wantEnd:   "upper 60s",
+		},
+		{
+			name:      "falling",
+			temps:     []float64{65, 58},
+			wantTrend: "falling",
+			wantStart: "mid 60s",
+			wantEnd:   "upper 50s",
+		},
+		{
+			name:      "peaking",
+			temps:     []float64{62, 78, 65},
+			wantTrend: "peaking",
+			wantPeak:  "upper 70s",
+		},
+		{
+			name:       "steady",
+			temps:      []float64{77, 78},
+			wantTrend:  "steady",
+			wantSteady: "upper 70s",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			rich := derivedDaypartSummaryValue(derivedDaypartWithTemperatures(test.name, "2026-05-29T12:00:00-05:00", "sunny", test.temps...), "America/Chicago")
+			prompt := derivedDaypartSummaryPromptValue(rich)
+			if prompt.TemperatureTrend != test.wantTrend ||
+				prompt.TemperatureStartPhraseF != test.wantStart ||
+				prompt.TemperatureEndPhraseF != test.wantEnd ||
+				prompt.TemperaturePeakPhraseF != test.wantPeak ||
+				prompt.TemperatureSteadyPhraseF != test.wantSteady {
+				t.Fatalf("prompt temperature presentation = %#v", prompt)
+			}
+		})
+	}
+}
+
+func TestDerivedDaypartPromptExportMaxPopTimeFallback(t *testing.T) {
+	withLabel := derivedDaypartSummaryPromptValue(DerivedDaypartSummaryModule{
+		MaxPopTime:      "6 AM",
+		MaxPopTimeLabel: "6:00 AM",
+	})
+	if withLabel.MaxPopTime != "6:00 AM" {
+		t.Fatalf("MaxPopTime with label = %q, want friendly label", withLabel.MaxPopTime)
+	}
+
+	withoutLabel := derivedDaypartSummaryPromptValue(DerivedDaypartSummaryModule{
+		MaxPopTime: "6 AM",
+	})
+	if withoutLabel.MaxPopTime != "6 AM" {
+		t.Fatalf("MaxPopTime without label = %q, want fallback time", withoutLabel.MaxPopTime)
+	}
+}
+
+func TestDerivedDaypartTemperaturePresentationFields(t *testing.T) {
+	tests := []struct {
+		name       string
+		temps      []float64
+		wantTrend  string
+		wantStart  string
+		wantEnd    string
+		wantPeak   string
+		wantSteady string
+	}{
+		{
+			name:      "rising",
+			temps:     []float64{58, 68},
+			wantTrend: "rising",
+			wantStart: "upper 50s",
+			wantEnd:   "upper 60s",
+		},
+		{
+			name:      "falling",
+			temps:     []float64{65, 58},
+			wantTrend: "falling",
+			wantStart: "mid 60s",
+			wantEnd:   "upper 50s",
+		},
+		{
+			name:      "peaking",
+			temps:     []float64{62, 78, 65},
+			wantTrend: "peaking",
+			wantPeak:  "upper 70s",
+		},
+		{
+			name:       "steady same band",
+			temps:      []float64{77, 78},
+			wantTrend:  "steady",
+			wantSteady: "upper 70s",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			summary := derivedDaypartWithTemperatures("afternoon", "2026-05-29T12:00:00-05:00", "sunny", test.temps...)
+			value := derivedDaypartSummaryValue(summary, "America/Chicago")
+			if value.DominantConditionDisplay != "Sunny" {
+				t.Fatalf("DominantConditionDisplay = %q, want Sunny", value.DominantConditionDisplay)
+			}
+			if value.TemperatureTrend != test.wantTrend ||
+				value.TemperatureStartPhraseF != test.wantStart ||
+				value.TemperatureEndPhraseF != test.wantEnd ||
+				value.TemperaturePeakPhraseF != test.wantPeak ||
+				value.TemperatureSteadyPhraseF != test.wantSteady {
+				t.Fatalf("temperature presentation = %#v", value)
+			}
+		})
+	}
+}
+
+func TestTemperaturePhraseF(t *testing.T) {
+	tests := []struct {
+		name  string
+		value forecast.Range
+		want  string
+	}{
+		{
+			name:  "single low band",
+			value: forecast.Range{Min: floatPtr(71), Max: floatPtr(73)},
+			want:  "low 70s",
+		},
+		{
+			name:  "single upper value",
+			value: forecast.Range{Min: floatPtr(68), Max: floatPtr(68)},
+			want:  "upper 60s",
+		},
+		{
+			name:  "range across bands",
+			value: forecast.Range{Min: floatPtr(68), Max: floatPtr(75)},
+			want:  "upper 60s to mid 70s",
+		},
+		{
+			name:  "max only",
+			value: forecast.Range{Max: floatPtr(84)},
+			want:  "mid 80s",
+		},
+		{
+			name:  "empty",
+			value: forecast.Range{},
+			want:  "",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if got := temperaturePhraseF(test.value); got != test.want {
+				t.Fatalf("temperaturePhraseF() = %q, want %q", got, test.want)
+			}
+		})
+	}
+}
+
 func TestOutdoorWindowsAndTomorrowPlanningModulesPreserveDailyContent(t *testing.T) {
 	registry := MustDefaultModuleRegistry()
-	ctx := derivedModuleContext(report.DailyTomorrow)
+	ctx := derivedModuleContext(report.Tomorrow)
 
 	outdoorOutput, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.OutdoorWindows})
 	if err != nil {
@@ -191,6 +536,12 @@ func TestOutdoorWindowsAndTomorrowPlanningModulesPreserveDailyContent(t *testing
 	if outdoor.Best.Daypart != "overnight" || outdoor.Worst.Daypart != "afternoon" {
 		t.Fatalf("outdoor windows = %#v, want quiet overnight and stormy afternoon", outdoor)
 	}
+	if outdoor.Best.PeriodBegins != "2026-05-29 at 12:00 AM" || outdoor.Best.PeriodEnds != "2026-05-29 at 6:00 AM" {
+		t.Fatalf("best outdoor period = %#v, want overnight period labels", outdoor.Best)
+	}
+	if outdoor.Worst.PeriodBegins != "2026-05-29 at 12:00 PM" || outdoor.Worst.PeriodEnds != "2026-05-29 at 6:00 PM" {
+		t.Fatalf("worst outdoor period = %#v, want afternoon period labels", outdoor.Worst)
+	}
 
 	planningOutput, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.TomorrowPlanning})
 	if err != nil {
@@ -209,9 +560,154 @@ func TestOutdoorWindowsAndTomorrowPlanningModulesPreserveDailyContent(t *testing
 	}
 }
 
+func TestDailyPlanningModulePackagesPlanningFields(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := dailyModuleContext()
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.DailyPlanning})
+	if err != nil {
+		t.Fatalf("BuildModule(daily planning) error = %v", err)
+	}
+	if output.ID != module.DailyPlanning || output.StanzaName != "daily_planning" {
+		t.Fatalf("output = %#v, want daily planning stanza", output)
+	}
+	planning := moduleValue[DailyPlanningModule](t, output)
+	if len(planning.MorningReadiness) == 0 ||
+		len(planning.CommuteSchoolWorkdayConcerns) == 0 ||
+		len(planning.OvernightChangeWatch) == 0 {
+		t.Fatalf("daily planning = %#v, want populated planning fields", planning)
+	}
+	if !containsString(planning.MorningReadiness, "Morning precipitation chance peaks near 60%.") {
+		t.Fatalf("MorningReadiness = %#v, want precipitation readiness note", planning.MorningReadiness)
+	}
+	if !containsString(planning.CommuteSchoolWorkdayConcerns, "Afternoon alert overlap needs attention.") {
+		t.Fatalf("CommuteSchoolWorkdayConcerns = %#v, want alert-overlap concern", planning.CommuteSchoolWorkdayConcerns)
+	}
+	if !containsString(planning.OvernightChangeWatch, "Watch for forecast timing or intensity adjustments overnight.") {
+		t.Fatalf("OvernightChangeWatch = %#v, want overnight fallback note", planning.OvernightChangeWatch)
+	}
+	data, err := json.Marshal(output.Value)
+	if err != nil {
+		t.Fatalf("marshal daily planning: %v", err)
+	}
+	jsonText := string(data)
+	for _, field := range []string{"morning_readiness", "commute_school_workday_concerns", "overnight_change_watch"} {
+		if !strings.Contains(jsonText, field) {
+			t.Fatalf("daily planning json = %s, want field %s", jsonText, field)
+		}
+	}
+	if strings.Contains(jsonText, "tomorrow_planning") || strings.Contains(jsonText, "morningReadiness") {
+		t.Fatalf("daily planning json = %s, want daily snake_case fields only", jsonText)
+	}
+}
+
+func TestDailyPlanningModuleRejectsUnsupportedReports(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	for _, id := range []report.ID{report.Today, report.Tomorrow, report.Hourly, report.ThreeDay, report.Weekend, report.Storm} {
+		t.Run(string(id), func(t *testing.T) {
+			ctx := derivedModuleContext(id)
+			_, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.DailyPlanning})
+			if err == nil || !strings.Contains(err.Error(), `module "daily_planning" is not compatible with report`) {
+				t.Fatalf("BuildModule(%s) error = %v, want incompatible report", id, err)
+			}
+		})
+	}
+}
+
+func TestDailyPlanningModuleHandlesMissingDailySummary(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := dailyModuleContext()
+	ctx.Derived.DailySummaries = nil
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.DailyPlanning})
+	if err != nil {
+		t.Fatalf("BuildModule(daily planning) error = %v", err)
+	}
+	planning := moduleValue[DailyPlanningModule](t, output)
+	if len(planning.MorningReadiness) != 0 ||
+		len(planning.CommuteSchoolWorkdayConcerns) != 0 ||
+		len(planning.OvernightChangeWatch) != 0 {
+		t.Fatalf("daily planning = %#v, want empty output without daily summary", planning)
+	}
+}
+
+func TestTodayPlanningModulePackagesPlanningFields(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := todayModuleContext()
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.TodayPlanning})
+	if err != nil {
+		t.Fatalf("BuildModule(today planning) error = %v", err)
+	}
+	if output.ID != module.TodayPlanning || output.StanzaName != "today_planning" {
+		t.Fatalf("output = %#v, want today planning stanza", output)
+	}
+	planning := moduleValue[TodayPlanningModule](t, output)
+	if len(planning.MorningReadiness) == 0 ||
+		len(planning.CommuteSchoolWorkdayConcerns) == 0 ||
+		len(planning.OutdoorPlanning) == 0 ||
+		len(planning.LateDayChangeWatch) == 0 {
+		t.Fatalf("today planning = %#v, want populated planning fields", planning)
+	}
+	if !containsString(planning.MorningReadiness, "Morning precipitation chance peaks near 60%.") {
+		t.Fatalf("MorningReadiness = %#v, want precipitation readiness note", planning.MorningReadiness)
+	}
+	if !containsString(planning.OutdoorPlanning, "Best outdoor window: Overnight (cold risk).") ||
+		!containsString(planning.OutdoorPlanning, "Toughest outdoor window: Afternoon (high precipitation chance, gusty wind, alert overlap, heat risk).") {
+		t.Fatalf("OutdoorPlanning = %#v, want deterministic best and toughest windows", planning.OutdoorPlanning)
+	}
+	if !containsString(planning.LateDayChangeWatch, "Afternoon precipitation timing may shift; current peak is near 80%.") {
+		t.Fatalf("LateDayChangeWatch = %#v, want late-day change note", planning.LateDayChangeWatch)
+	}
+	data, err := json.Marshal(output.Value)
+	if err != nil {
+		t.Fatalf("marshal today planning: %v", err)
+	}
+	jsonText := string(data)
+	for _, field := range []string{"morning_readiness", "commute_school_workday_concerns", "outdoor_planning", "late_day_change_watch"} {
+		if !strings.Contains(jsonText, field) {
+			t.Fatalf("today planning json = %s, want field %s", jsonText, field)
+		}
+	}
+	if strings.Contains(jsonText, "morningReadiness") || strings.Contains(jsonText, "lateDayChangeWatch") {
+		t.Fatalf("today planning json = %s, want snake_case fields", jsonText)
+	}
+}
+
+func TestTodayPlanningModuleRejectsUnsupportedReports(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	for _, id := range []report.ID{report.Tomorrow, report.Daily} {
+		t.Run(string(id), func(t *testing.T) {
+			ctx := derivedModuleContext(id)
+			_, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.TodayPlanning})
+			if err == nil || !strings.Contains(err.Error(), `module "today_planning" is not compatible with report`) {
+				t.Fatalf("BuildModule(%s) error = %v, want incompatible report", id, err)
+			}
+		})
+	}
+}
+
+func TestTodayPlanningModuleHandlesMissingDailySummary(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := todayModuleContext()
+	ctx.Derived.DailySummaries = nil
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.TodayPlanning})
+	if err != nil {
+		t.Fatalf("BuildModule(today planning) error = %v", err)
+	}
+	planning := moduleValue[TodayPlanningModule](t, output)
+	if len(planning.MorningReadiness) != 0 ||
+		len(planning.CommuteSchoolWorkdayConcerns) != 0 ||
+		len(planning.OutdoorPlanning) != 0 ||
+		len(planning.LateDayChangeWatch) != 0 {
+		t.Fatalf("today planning = %#v, want empty output without daily summary", planning)
+	}
+}
+
 func TestDerivedModulesHandleMissingData(t *testing.T) {
 	registry := MustDefaultModuleRegistry()
-	ctx := derivedModuleContext(report.DailyToday)
+	ctx := derivedModuleContext(report.Daily)
 	ctx.Derived.DailySummaries = nil
 	ctx.Derived.DaypartSummaries = nil
 
@@ -302,6 +798,26 @@ func derivedModuleContext(id report.ID) ModuleContext {
 	}
 }
 
+func todayModuleContext() ModuleContext {
+	ctx := derivedModuleContext(report.Daily)
+	ctx.Resolved.Definition = report.Definition{
+		ID:       report.Today,
+		Name:     "Today Report",
+		PromptID: "weather.today_generated_text",
+	}
+	return ctx
+}
+
+func dailyModuleContext() ModuleContext {
+	ctx := derivedModuleContext(report.Tomorrow)
+	ctx.Resolved.Definition = report.Definition{
+		ID:       report.Daily,
+		Name:     "Daily Report",
+		PromptID: "weather.daily_generated_text",
+	}
+	return ctx
+}
+
 func derivedDaypart(name string, start string, end string, text string, temperature float64, apparent *float64, precip float64, gust float64) forecast.DaypartSummary {
 	hour := derivedHour(start, text, precip, temperature, apparent, gust)
 	return forecast.SummarizeDaypart(name, timeutil.Period{
@@ -310,6 +826,24 @@ func derivedDaypart(name string, start string, end string, text string, temperat
 	}, []weatherdata.ForecastPeriod{hour})
 }
 
+func derivedDaypartWithTemperatures(name string, start string, text string, temperatures ...float64) forecast.DaypartSummary {
+	startTime := mustParseModuleTime(start)
+	periods := make([]weatherdata.ForecastPeriod, 0, len(temperatures))
+	for index, temperature := range temperatures {
+		periodStart := startTime.Add(time.Duration(index) * time.Hour)
+		periods = append(periods, weatherdata.ForecastPeriod{
+			StartTime:       periodStart,
+			EndTime:         periodStart.Add(time.Hour),
+			TextDescription: text,
+			TemperatureF:    floatPtr(temperature),
+		})
+	}
+	return forecast.SummarizeDaypart(name, timeutil.Period{
+		Start: startTime,
+		End:   startTime.Add(time.Duration(len(temperatures)) * time.Hour),
+	}, periods)
+}
+
 func derivedHour(start string, text string, precip float64, temperature float64, apparent *float64, gust float64) weatherdata.ForecastPeriod {
 	startTime := mustParseModuleTime(start)
 	endTime := startTime.Add(time.Hour)

internal/briefing/hourly_forecast_module.go

@@ -1,12 +1,16 @@
 package briefing
 
 import (
+	"strings"
 	"time"
 
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/module"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
 )
 
+const DefaultHourlyForecastPrecipMentionProbabilityThreshold = 20
+
 type HourlyForecastModule struct {
 	Product          string                 `json:"product,omitempty"`
 	IssuedAt         time.Time              `json:"issued_at,omitempty"`
@@ -16,9 +20,57 @@ type HourlyForecastModule struct {
 	Periods          []HourlyForecastPeriod `json:"periods,omitempty"`
 }
 
+type HourlyForecastPromptExport struct {
+	Product          string                       `json:"product,omitempty"`
+	IssuedAt         time.Time                    `json:"issued_at,omitempty"`
+	UpdatedAt        *time.Time                   `json:"updated_at,omitempty"`
+	SourceLocation   string                       `json:"source_location,omitempty"`
+	SourceLocationID string                       `json:"source_location_id,omitempty"`
+	Periods          []HourlyForecastPromptPeriod `json:"periods,omitempty"`
+}
+
 type HourlyForecastPeriod struct {
-	StartTime                         string   `json:"start_time,omitempty"`
-	EndTime                           string   `json:"end_time,omitempty"`
+	HourLabel                         string   `json:"hour_label,omitempty"`
+	PeriodBegins                      string   `json:"period_begins,omitempty"`
+	PeriodEnds                        string   `json:"period_ends,omitempty"`
+	Name                              string   `json:"name,omitempty"`
+	IsDay                             *bool    `json:"is_day,omitempty"`
+	ConditionCode                     *int     `json:"condition_code,omitempty"`
+	TextDescription                   string   `json:"text_description,omitempty"`
+	TextDescriptionLower              string   `json:"text_description_lower,omitempty"`
+	TemperatureC                      *float64 `json:"temperature_c,omitempty"`
+	TemperatureF                      *float64 `json:"temperature_f,omitempty"`
+	TemperatureCMin                   *float64 `json:"temperature_c_min,omitempty"`
+	TemperatureFMin                   *float64 `json:"temperature_f_min,omitempty"`
+	TemperatureCMax                   *float64 `json:"temperature_c_max,omitempty"`
+	TemperatureFMax                   *float64 `json:"temperature_f_max,omitempty"`
+	DewpointC                         *float64 `json:"dewpoint_c,omitempty"`
+	DewpointF                         *float64 `json:"dewpoint_f,omitempty"`
+	WindSpeedKmh                      *float64 `json:"wind_speed_kmh,omitempty"`
+	WindSpeedMph                      *float64 `json:"wind_speed_mph,omitempty"`
+	WindGustKmh                       *float64 `json:"wind_gust_kmh,omitempty"`
+	WindGustMph                       *float64 `json:"wind_gust_mph,omitempty"`
+	WindDirection                     string   `json:"wind_direction,omitempty"`
+	BarometricPressurePa              *float64 `json:"barometric_pressure_pa,omitempty"`
+	BarometricPressureInHg            *float64 `json:"barometric_pressure_in_hg,omitempty"`
+	VisibilityMeters                  *float64 `json:"visibility_meters,omitempty"`
+	VisibilityMiles                   *float64 `json:"visibility_miles,omitempty"`
+	ApparentTemperatureC              *float64 `json:"apparent_temperature_c,omitempty"`
+	ApparentTemperatureF              *float64 `json:"apparent_temperature_f,omitempty"`
+	CloudCoverPercent                 *float64 `json:"cloud_cover_percent,omitempty"`
+	ProbabilityOfPrecipitationPercent *float64 `json:"probability_of_precipitation_percent,omitempty"`
+	MentionPrecipitation              bool     `json:"mention_precipitation,omitempty"`
+	PrecipitationAmountMm             *float64 `json:"precipitation_amount_mm,omitempty"`
+	PrecipitationAmountIn             *float64 `json:"precipitation_amount_in,omitempty"`
+	SnowfallDepthMM                   *float64 `json:"snowfall_depth_mm,omitempty"`
+	SnowfallDepthIn                   *float64 `json:"snowfall_depth_in,omitempty"`
+	UVIndex                           *float64 `json:"uv_index,omitempty"`
+	RelativeHumidityPercent           *float64 `json:"relative_humidity_percent,omitempty"`
+}
+
+type HourlyForecastPromptPeriod struct {
+	PeriodBegins                      string   `json:"period_begins,omitempty"`
+	PeriodEnds                        string   `json:"period_ends,omitempty"`
 	Name                              string   `json:"name,omitempty"`
 	IsDay                             *bool    `json:"is_day,omitempty"`
 	ConditionCode                     *int     `json:"condition_code,omitempty"`
@@ -71,12 +123,30 @@ func buildHourlyForecastModule(ctx ModuleContext, _ any) (*module.Output, error)
 	return &module.Output{ID: module.HourlyForecast, StanzaName: "hourly_forecast", Value: value}, nil
 }
 
-func hourlyForecastPeriods(periods []weatherdata.ForecastPeriod, timezone string) []HourlyForecastPeriod {
-	out := make([]HourlyForecastPeriod, 0, len(periods))
+func exportHourlyForecastPromptValue(value any) (any, error) {
+	rich, ok := value.(HourlyForecastModule)
+	if !ok {
+		return nil, unexpectedPromptExportValue(value, HourlyForecastModule{})
+	}
+	return HourlyForecastPromptExport{
+		Product:          rich.Product,
+		IssuedAt:         rich.IssuedAt,
+		UpdatedAt:        copyTime(rich.UpdatedAt),
+		SourceLocation:   rich.SourceLocation,
+		SourceLocationID: rich.SourceLocationID,
+		Periods:          hourlyForecastPromptPeriods(rich.Periods),
+	}, nil
+}
+
+func hourlyForecastPromptPeriods(periods []HourlyForecastPeriod) []HourlyForecastPromptPeriod {
+	if len(periods) == 0 {
+		return nil
+	}
+	out := make([]HourlyForecastPromptPeriod, 0, len(periods))
 	for _, period := range periods {
-		out = append(out, HourlyForecastPeriod{
-			StartTime:                         friendlyDateTimeLabel(period.StartTime, timezone),
-			EndTime:                           friendlyDateTimeLabel(period.EndTime, timezone),
+		out = append(out, HourlyForecastPromptPeriod{
+			PeriodBegins:                      period.PeriodBegins,
+			PeriodEnds:                        period.PeriodEnds,
 			Name:                              period.Name,
 			IsDay:                             copyBool(period.IsDay),
 			ConditionCode:                     copyInt(period.ConditionCode),
@@ -93,6 +163,55 @@ func hourlyForecastPeriods(periods []weatherdata.ForecastPeriod, timezone string
 			WindSpeedMph:                      copyFloat(period.WindSpeedMph),
 			WindGustKmh:                       copyFloat(period.WindGustKmh),
 			WindGustMph:                       copyFloat(period.WindGustMph),
+			WindDirection:                     period.WindDirection,
+			BarometricPressurePa:              copyFloat(period.BarometricPressurePa),
+			BarometricPressureInHg:            copyFloat(period.BarometricPressureInHg),
+			VisibilityMeters:                  copyFloat(period.VisibilityMeters),
+			VisibilityMiles:                   copyFloat(period.VisibilityMiles),
+			ApparentTemperatureC:              copyFloat(period.ApparentTemperatureC),
+			ApparentTemperatureF:              copyFloat(period.ApparentTemperatureF),
+			CloudCoverPercent:                 copyFloat(period.CloudCoverPercent),
+			ProbabilityOfPrecipitationPercent: copyFloat(period.ProbabilityOfPrecipitationPercent),
+			PrecipitationAmountMm:             copyFloat(period.PrecipitationAmountMm),
+			PrecipitationAmountIn:             copyFloat(period.PrecipitationAmountIn),
+			SnowfallDepthMM:                   copyFloat(period.SnowfallDepthMM),
+			SnowfallDepthIn:                   copyFloat(period.SnowfallDepthIn),
+			UVIndex:                           copyFloat(period.UVIndex),
+			RelativeHumidityPercent:           copyFloat(period.RelativeHumidityPercent),
+		})
+	}
+	return out
+}
+
+func hourlyForecastPeriods(periods []weatherdata.ForecastPeriod, timezone string) []HourlyForecastPeriod {
+	return hourlyForecastPeriodsWithPrecipMentionThreshold(periods, timezone, DefaultHourlyForecastPrecipMentionProbabilityThreshold)
+}
+
+func hourlyForecastPeriodsWithPrecipMentionThreshold(periods []weatherdata.ForecastPeriod, timezone string, threshold float64) []HourlyForecastPeriod {
+	out := make([]HourlyForecastPeriod, 0, len(periods))
+	for _, period := range periods {
+		validPeriod := timeutil.Period{Start: period.StartTime, End: period.EndTime}
+		out = append(out, HourlyForecastPeriod{
+			HourLabel:                         hourMinuteLabel(period.StartTime, timezone),
+			PeriodBegins:                      friendlyPeriodBeginsLabel(validPeriod, timezone),
+			PeriodEnds:                        friendlyPeriodEndsLabel(validPeriod, timezone),
+			Name:                              period.Name,
+			IsDay:                             copyBool(period.IsDay),
+			ConditionCode:                     copyInt(period.ConditionCode),
+			TextDescription:                   period.TextDescription,
+			TextDescriptionLower:              strings.ToLower(period.TextDescription),
+			TemperatureC:                      copyFloat(period.TemperatureC),
+			TemperatureF:                      copyFloat(period.TemperatureF),
+			TemperatureCMin:                   copyFloat(period.TemperatureCMin),
+			TemperatureFMin:                   copyFloat(period.TemperatureFMin),
+			TemperatureCMax:                   copyFloat(period.TemperatureCMax),
+			TemperatureFMax:                   copyFloat(period.TemperatureFMax),
+			DewpointC:                         copyFloat(period.DewpointC),
+			DewpointF:                         copyFloat(period.DewpointF),
+			WindSpeedKmh:                      copyFloat(period.WindSpeedKmh),
+			WindSpeedMph:                      copyFloat(period.WindSpeedMph),
+			WindGustKmh:                       copyFloat(period.WindGustKmh),
+			WindGustMph:                       copyFloat(period.WindGustMph),
 			WindDirection:                     windDirectionLabel(period.WindDirectionDegrees),
 			BarometricPressurePa:              copyFloat(period.BarometricPressurePa),
 			BarometricPressureInHg:            copyFloat(period.BarometricPressureInHg),
@@ -102,6 +221,7 @@ func hourlyForecastPeriods(periods []weatherdata.ForecastPeriod, timezone string
 			ApparentTemperatureF:              copyFloat(period.ApparentTemperatureF),
 			CloudCoverPercent:                 copyFloat(period.CloudCoverPercent),
 			ProbabilityOfPrecipitationPercent: copyFloat(period.ProbabilityOfPrecipitationPercent),
+			MentionPrecipitation:              mentionHourlyForecastPrecipitation(period.ProbabilityOfPrecipitationPercent, threshold),
 			PrecipitationAmountMm:             copyFloat(period.PrecipitationAmountMm),
 			PrecipitationAmountIn:             copyFloat(period.PrecipitationAmountIn),
 			SnowfallDepthMM:                   copyFloat(period.SnowfallDepthMM),
@@ -113,6 +233,10 @@ func hourlyForecastPeriods(periods []weatherdata.ForecastPeriod, timezone string
 	return out
 }
 
+func mentionHourlyForecastPrecipitation(probability *float64, threshold float64) bool {
+	return probability != nil && *probability >= threshold
+}
+
 func (v HourlyForecastModule) isEmpty() bool {
 	return v.Product == "" &&
 		v.IssuedAt.IsZero() &&

internal/briefing/metadata_module.go

@@ -20,7 +20,6 @@ type MetadataModule struct {
 	ValidPeriod    timeutil.Period        `json:"valid_period"`
 	Location       *LocationContext       `json:"location,omitempty"`
 	SourceWarnings []SourceWarningSummary `json:"source_warnings,omitempty"`
-	Alerts         *AlertDigestModule     `json:"alerts,omitempty"`
 }
 
 type SourceWarningSummary struct {
@@ -44,7 +43,6 @@ func buildMetadataModule(ctx ModuleContext, _ any) (*module.Output, error) {
 		ValidPeriod:    metadata.ValidPeriod,
 		Location:       copyLocation(ctx.Location),
 		SourceWarnings: sourceWarningSummaries(ctx.Collected.SourceWarnings),
-		Alerts:         alertDigest(ctx.Collected, ctx.Derived.AlertOverlaps),
 	}
 	return &module.Output{ID: module.Metadata, StanzaName: "metadata", Value: value}, nil
 }

internal/briefing/module_format_helpers.go

@@ -60,6 +60,36 @@ func windDirectionLabel(degrees *float64) string {
 	return labels[sector]
 }
 
+func windDirectionTextLabel(degrees *float64) string {
+	if degrees == nil {
+		return ""
+	}
+	labels := []string{
+		"north",
+		"north-northeast",
+		"northeast",
+		"east-northeast",
+		"east",
+		"east-southeast",
+		"southeast",
+		"south-southeast",
+		"south",
+		"south-southwest",
+		"southwest",
+		"west-southwest",
+		"west",
+		"west-northwest",
+		"northwest",
+		"north-northwest",
+	}
+	normalized := math.Mod(*degrees, 360)
+	if normalized < 0 {
+		normalized += 360
+	}
+	sector := int(math.Floor((normalized+11.25)/22.5)) % len(labels)
+	return labels[sector]
+}
+
 func timedClockLabel(value *forecast.TimedValue, timezone string) string {
 	if value == nil {
 		return ""
@@ -67,18 +97,18 @@ func timedClockLabel(value *forecast.TimedValue, timezone string) string {
 	return clockLabel(value.Time, timezone)
 }
 
-func periodClockLabel(period timeutil.Period, timezone string) string {
+func friendlyPeriodBeginsLabel(period timeutil.Period, timezone string) string {
 	if !period.IsValid() {
 		return ""
 	}
-	return clockLabel(period.Start, timezone) + "-" + clockLabel(period.End, timezone)
+	return friendlyDateTimeLabel(period.Start, timezone)
 }
 
-func friendlyPeriodLabel(period timeutil.Period, timezone string) string {
+func friendlyPeriodEndsLabel(period timeutil.Period, timezone string) string {
 	if !period.IsValid() {
 		return ""
 	}
-	return friendlyDateTimeLabel(period.Start, timezone) + " to " + friendlyDateTimeLabel(period.End, timezone)
+	return friendlyDateTimeLabel(period.End, timezone)
 }
 
 func friendlyDateTimeLabel(value time.Time, timezone string) string {
@@ -92,6 +122,17 @@ func friendlyDateTimeLabel(value time.Time, timezone string) string {
 	return value.In(location).Format("2006-01-02 at 3:04 PM")
 }
 
+func friendlyMonthDayTimeLabel(value time.Time, timezone string) string {
+	if value.IsZero() {
+		return ""
+	}
+	location, err := timeutil.LoadLocation(timezone)
+	if err != nil {
+		location = time.UTC
+	}
+	return value.In(location).Format("January 2 at 3:04 PM")
+}
+
 func friendlyDateLabel(date string, timezone string) string {
 	location, err := timeutil.LoadLocation(timezone)
 	if err != nil {
@@ -126,3 +167,11 @@ func clockLabel(value time.Time, timezone string) string {
 	}
 	return label
 }
+
+func hourMinuteLabel(value time.Time, timezone string) string {
+	location, err := timeutil.LoadLocation(timezone)
+	if err != nil {
+		location = time.UTC
+	}
+	return value.In(location).Format("3:04 PM")
+}

internal/briefing/module_format_helpers_test.go

@@ -27,3 +27,25 @@ func TestWindDirectionLabelUsesSixteenPointCompass(t *testing.T) {
 		})
 	}
 }
+
+func TestWindDirectionTextLabelUsesLowercaseCompassText(t *testing.T) {
+	tests := []struct {
+		name    string
+		degrees *float64
+		want    string
+	}{
+		{name: "nil", degrees: nil, want: ""},
+		{name: "north", degrees: floatPtr(0), want: "north"},
+		{name: "north northeast", degrees: floatPtr(11.25), want: "north-northeast"},
+		{name: "northwest", degrees: floatPtr(315), want: "northwest"},
+		{name: "negative normalizes", degrees: floatPtr(-45), want: "northwest"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := windDirectionTextLabel(tt.degrees); got != tt.want {
+				t.Fatalf("windDirectionTextLabel(%v) = %q, want %q", tt.degrees, got, tt.want)
+			}
+		})
+	}
+}

internal/briefing/modules.go

@@ -21,6 +21,8 @@ type ModuleContext struct {
 
 type ModuleBuilder func(ModuleContext, any) (*module.Output, error)
 
+type ModulePromptExporter func(value any) (any, error)
+
 type ModuleDefinition struct {
 	ID                module.ID
 	StanzaName        string
@@ -31,12 +33,17 @@ type ModuleDefinition struct {
 	MissingData       module.MissingDataBehavior
 	AllowDuplicate    bool
 	Builder           ModuleBuilder
+	PromptExporter    ModulePromptExporter
 }
 
 type ModuleRegistry struct {
 	definitions map[module.ID]ModuleDefinition
 }
 
+func unexpectedPromptExportValue(got any, want any) error {
+	return fmt.Errorf("value has type %T, want %T", got, want)
+}
+
 func DefaultModuleRegistry() (ModuleRegistry, error) {
 	return NewModuleRegistry(defaultModuleDefinitions())
 }
@@ -130,6 +137,15 @@ func (r ModuleRegistry) BuildModule(ctx ModuleContext, item module.ConfigItem) (
 	if output.StanzaName != definition.StanzaName {
 		return nil, fmt.Errorf("module %q produced stanza %q, want %q", definition.ID, output.StanzaName, definition.StanzaName)
 	}
+	if definition.PromptExporter == nil {
+		output.PromptValue = output.Value
+		return output, nil
+	}
+	promptValue, err := definition.PromptExporter(output.Value)
+	if err != nil {
+		return nil, fmt.Errorf("module %q stanza %q prompt export: %w", definition.ID, definition.StanzaName, err)
+	}
+	output.PromptValue = promptValue
 	return output, nil
 }
 
@@ -162,6 +178,8 @@ func collectedFactAvailable(requirement module.FactRequirement, ctx ModuleContex
 		return ctx.Collected.Discussion != nil
 	case module.CollectedWeatherStory:
 		return ctx.Collected.WeatherStory != nil
+	case module.CollectedSPCConvectiveOutlooks:
+		return ctx.Collected.SPCConvectiveOutlooks != nil
 	case module.CollectedSourceMetadata:
 		return len(ctx.Collected.SourceProvenance) > 0 || len(ctx.Collected.SourceWarnings) > 0
 	default:
@@ -183,6 +201,8 @@ func derivedFactAvailable(requirement module.FactRequirement, ctx ModuleContext)
 		return len(ctx.Derived.DaypartSummaries) > 0
 	case module.RequiresDerivedPrecipTiming:
 		return true
+	case module.RequiresDerivedSPCConvectiveOutlooks:
+		return ctx.Derived.SPCConvectiveOutlooks != nil
 	default:
 		return false
 	}
@@ -245,8 +265,8 @@ func (d ModuleDefinition) ValidateOptions(options any) error {
 }
 
 func defaultModuleDefinitions() []ModuleDefinition {
-	allReports := []report.ID{report.DailyToday, report.DailyTomorrow, report.ThreeDay, report.Weekend, report.Storm}
-	daypartReports := []report.ID{report.DailyToday, report.DailyTomorrow, report.ThreeDay, report.Weekend}
+	allReports := []report.ID{report.Daily, report.Today, report.Tomorrow, report.Hourly, report.ThreeDay, report.Weekend, report.Storm}
+	daypartReports := []report.ID{report.Daily, report.Today, report.Tomorrow, report.ThreeDay, report.Weekend}
 	return []ModuleDefinition{
 		{
 			ID:                module.Metadata,
@@ -265,6 +285,7 @@ func defaultModuleDefinitions() []ModuleDefinition {
 			SupportedReports:  allReports,
 			MissingData:       module.MissingDataOmit,
 			Builder:           buildCurrentConditionsModule,
+			PromptExporter:    exportCurrentConditionsPromptValue,
 		},
 		{
 			ID:                module.NarrativeForecast,
@@ -272,7 +293,7 @@ func defaultModuleDefinitions() []ModuleDefinition {
 			DefaultOptions:    module.NarrativeForecastOptions{},
 			RequiredCollected: []module.FactRequirement{module.CollectedNarrativeForecast},
 			RequiredDerived:   []module.FactRequirement{module.RequiresDerivedNarrativePeriods},
-			SupportedReports:  []report.ID{report.DailyToday, report.DailyTomorrow},
+			SupportedReports:  []report.ID{report.Daily, report.Today, report.Tomorrow},
 			MissingData:       module.MissingDataOmit,
 			Builder:           buildNarrativeForecastModule,
 		},
@@ -282,16 +303,17 @@ func defaultModuleDefinitions() []ModuleDefinition {
 			DefaultOptions:    module.HourlyForecastOptions{},
 			RequiredCollected: []module.FactRequirement{module.CollectedHourlyForecast},
 			RequiredDerived:   []module.FactRequirement{module.RequiresDerivedHourlyPeriods},
-			SupportedReports:  []report.ID{report.DailyToday, report.DailyTomorrow},
+			SupportedReports:  []report.ID{report.Daily, report.Today, report.Tomorrow, report.Hourly},
 			MissingData:       module.MissingDataOmit,
 			Builder:           buildHourlyForecastModule,
+			PromptExporter:    exportHourlyForecastPromptValue,
 		},
 		{
 			ID:               module.DerivedDailySummary,
 			StanzaName:       "derived_daily_summary",
 			DefaultOptions:   module.DerivedDailySummaryOptions{},
 			RequiredDerived:  []module.FactRequirement{module.RequiresDerivedDailySummaries, module.RequiresDerivedPrecipTiming},
-			SupportedReports: []report.ID{report.DailyToday, report.DailyTomorrow},
+			SupportedReports: []report.ID{report.Daily, report.Today, report.Tomorrow},
 			MissingData:      module.MissingDataError,
 			Builder:          buildDerivedDailySummaryModule,
 		},
@@ -303,12 +325,13 @@ func defaultModuleDefinitions() []ModuleDefinition {
 			SupportedReports: daypartReports,
 			MissingData:      module.MissingDataError,
 			Builder:          buildDerivedDaypartSummariesModule,
+			PromptExporter:   exportDerivedDaypartSummariesPromptValue,
 		},
 		{
 			ID:               module.PrecipTiming,
 			StanzaName:       "precip_timing",
 			DefaultOptions:   module.PrecipTimingOptions{},
-			RequiredDerived:  []module.FactRequirement{module.RequiresDerivedDaypartSummaries},
+			RequiredDerived:  []module.FactRequirement{module.RequiresDerivedPrecipTiming},
 			SupportedReports: allReports,
 			MissingData:      module.MissingDataEmpty,
 			Builder:          buildPrecipTimingModule,
@@ -323,6 +346,16 @@ func defaultModuleDefinitions() []ModuleDefinition {
 			MissingData:       module.MissingDataEmpty,
 			Builder:           buildAlertDigestModule,
 		},
+		{
+			ID:                module.SPCConvectiveOutlooks,
+			StanzaName:        string(module.SPCConvectiveOutlooks),
+			DefaultOptions:    module.SPCConvectiveOutlooksOptions{},
+			RequiredCollected: []module.FactRequirement{module.CollectedSPCConvectiveOutlooks},
+			RequiredDerived:   []module.FactRequirement{module.RequiresDerivedSPCConvectiveOutlooks},
+			SupportedReports:  allReports,
+			MissingData:       module.MissingDataEmpty,
+			Builder:           buildSPCConvectiveOutlooksModule,
+		},
 		{
 			ID:                module.AreaForecastDiscussion,
 			StanzaName:        "area_forecast_discussion",
@@ -332,6 +365,16 @@ func defaultModuleDefinitions() []ModuleDefinition {
 			MissingData:       module.MissingDataOmit,
 			Builder:           buildAreaForecastDiscussionModule,
 		},
+		{
+			ID:                module.SPCConvectiveDiscussion,
+			StanzaName:        string(module.SPCConvectiveDiscussion),
+			DefaultOptions:    module.SPCConvectiveDiscussionOptions{},
+			RequiredCollected: []module.FactRequirement{module.CollectedSPCConvectiveOutlooks},
+			RequiredDerived:   []module.FactRequirement{module.RequiresDerivedSPCConvectiveOutlooks},
+			SupportedReports:  allReports,
+			MissingData:       module.MissingDataOmit,
+			Builder:           buildSPCConvectiveDiscussionModule,
+		},
 		{
 			ID:                module.WeatherStory,
 			StanzaName:        "weather_story",
@@ -350,14 +393,32 @@ func defaultModuleDefinitions() []ModuleDefinition {
 			MissingData:      module.MissingDataEmpty,
 			Builder:          buildOutdoorWindowsModule,
 		},
+		{
+			ID:               module.TodayPlanning,
+			StanzaName:       "today_planning",
+			DefaultOptions:   module.TodayPlanningOptions{},
+			RequiredDerived:  []module.FactRequirement{module.RequiresDerivedDailySummaries},
+			SupportedReports: []report.ID{report.Today},
+			MissingData:      module.MissingDataEmpty,
+			Builder:          buildTodayPlanningModule,
+		},
 		{
 			ID:               module.TomorrowPlanning,
 			StanzaName:       "tomorrow_planning",
 			DefaultOptions:   module.TomorrowPlanningOptions{},
 			RequiredDerived:  []module.FactRequirement{module.RequiresDerivedDailySummaries},
-			SupportedReports: []report.ID{report.DailyTomorrow},
+			SupportedReports: []report.ID{report.Tomorrow},
 			MissingData:      module.MissingDataEmpty,
 			Builder:          buildTomorrowPlanningModule,
 		},
+		{
+			ID:               module.DailyPlanning,
+			StanzaName:       "daily_planning",
+			DefaultOptions:   module.DailyPlanningOptions{},
+			RequiredDerived:  []module.FactRequirement{module.RequiresDerivedDailySummaries},
+			SupportedReports: []report.ID{report.Daily},
+			MissingData:      module.MissingDataEmpty,
+			Builder:          buildDailyPlanningModule,
+		},
 	}
 }

internal/briefing/modules_test.go

@@ -1,11 +1,15 @@
 package briefing
 
 import (
+	"encoding/json"
+	"errors"
 	"strings"
 	"testing"
 
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/facts"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/module"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
 )
 
 func TestDefaultModuleRegistryValidatesReportDefaults(t *testing.T) {
@@ -38,6 +42,9 @@ func TestDefaultReportModulesBuildSnapshots(t *testing.T) {
 					t.Fatalf("BuildModule(%s) error = %v", item.ID, err)
 				}
 				if output != nil {
+					if output.DataPackageValue() == nil {
+						t.Fatalf("BuildModule(%s) data package value = nil", item.ID)
+					}
 					outputs = append(outputs, *output)
 				}
 			}
@@ -52,9 +59,266 @@ func TestDefaultReportModulesBuildSnapshots(t *testing.T) {
 	}
 }
 
+func TestDefaultModuleDefinitionsDeclarePromptExportPolicy(t *testing.T) {
+	customExporters := map[module.ID]struct{}{
+		module.CurrentConditions:       {},
+		module.HourlyForecast:          {},
+		module.DerivedDaypartSummaries: {},
+	}
+	passThroughExporters := map[module.ID]struct{}{
+		module.Metadata:                {},
+		module.NarrativeForecast:       {},
+		module.DerivedDailySummary:     {},
+		module.PrecipTiming:            {},
+		module.AlertDigest:             {},
+		module.SPCConvectiveOutlooks:   {},
+		module.AreaForecastDiscussion:  {},
+		module.SPCConvectiveDiscussion: {},
+		module.WeatherStory:            {},
+		module.OutdoorWindows:          {},
+		module.TodayPlanning:           {},
+		module.TomorrowPlanning:        {},
+		module.DailyPlanning:           {},
+	}
+
+	for _, definition := range defaultModuleDefinitions() {
+		_, custom := customExporters[definition.ID]
+		_, passThrough := passThroughExporters[definition.ID]
+		if custom == passThrough {
+			t.Fatalf("module %q exporter policy custom=%v passThrough=%v, want exactly one policy", definition.ID, custom, passThrough)
+		}
+		if custom && definition.PromptExporter == nil {
+			t.Fatalf("module %q PromptExporter = nil, want custom prompt exporter", definition.ID)
+		}
+		if passThrough && definition.PromptExporter != nil {
+			t.Fatalf("module %q PromptExporter is set, want default pass-through", definition.ID)
+		}
+	}
+}
+
+func TestModuleRegistryAddsPassThroughPromptValue(t *testing.T) {
+	registry, err := NewModuleRegistry([]ModuleDefinition{
+		{
+			ID:         module.Metadata,
+			StanzaName: "metadata",
+			Builder: func(ModuleContext, any) (*module.Output, error) {
+				return &module.Output{
+					ID:         module.Metadata,
+					StanzaName: "metadata",
+					Value:      testRegistryValue{Message: "rich"},
+				}, nil
+			},
+		},
+	})
+	if err != nil {
+		t.Fatalf("NewModuleRegistry() error = %v", err)
+	}
+
+	output, err := registry.BuildModule(testRegistryModuleContext(), module.ConfigItem{ID: module.Metadata})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	if output == nil {
+		t.Fatal("BuildModule() output = nil, want output")
+	}
+	if output.PromptValue != output.Value {
+		t.Fatalf("PromptValue = %#v, want pass-through rich value %#v", output.PromptValue, output.Value)
+	}
+	if output.DataPackageValue() != output.Value {
+		t.Fatalf("DataPackageValue() = %#v, want rich value", output.DataPackageValue())
+	}
+}
+
+func TestModuleRegistryAddsCustomPromptValue(t *testing.T) {
+	registry, err := NewModuleRegistry([]ModuleDefinition{
+		{
+			ID:         module.Metadata,
+			StanzaName: "metadata",
+			Builder: func(ModuleContext, any) (*module.Output, error) {
+				return &module.Output{
+					ID:         module.Metadata,
+					StanzaName: "metadata",
+					Value:      testRegistryValue{Message: "rich"},
+				}, nil
+			},
+			PromptExporter: func(value any) (any, error) {
+				rich, ok := value.(testRegistryValue)
+				if !ok {
+					return nil, errors.New("unexpected rich value type")
+				}
+				return testRegistryValue{Message: rich.Message + " prompt"}, nil
+			},
+		},
+	})
+	if err != nil {
+		t.Fatalf("NewModuleRegistry() error = %v", err)
+	}
+
+	output, err := registry.BuildModule(testRegistryModuleContext(), module.ConfigItem{ID: module.Metadata})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	got, ok := output.PromptValue.(testRegistryValue)
+	if !ok {
+		t.Fatalf("PromptValue type = %T, want testRegistryValue", output.PromptValue)
+	}
+	if got.Message != "rich prompt" {
+		t.Fatalf("PromptValue = %#v, want custom prompt value", got)
+	}
+	if output.DataPackageValue() != output.PromptValue {
+		t.Fatalf("DataPackageValue() = %#v, want custom prompt value", output.DataPackageValue())
+	}
+	if output.Value.(testRegistryValue).Message != "rich" {
+		t.Fatalf("Value = %#v, want rich value unchanged", output.Value)
+	}
+}
+
+func TestModuleRegistryWrapsPromptExporterErrors(t *testing.T) {
+	registry, err := NewModuleRegistry([]ModuleDefinition{
+		{
+			ID:         module.Metadata,
+			StanzaName: "metadata",
+			Builder: func(ModuleContext, any) (*module.Output, error) {
+				return &module.Output{ID: module.Metadata, StanzaName: "metadata", Value: testRegistryValue{Message: "rich"}}, nil
+			},
+			PromptExporter: func(any) (any, error) {
+				return nil, errors.New("unsupported value")
+			},
+		},
+	})
+	if err != nil {
+		t.Fatalf("NewModuleRegistry() error = %v", err)
+	}
+
+	_, err = registry.BuildModule(testRegistryModuleContext(), module.ConfigItem{ID: module.Metadata})
+	if err == nil ||
+		!strings.Contains(err.Error(), `module "metadata" stanza "metadata" prompt export`) ||
+		!strings.Contains(err.Error(), "unsupported value") {
+		t.Fatalf("BuildModule() error = %v, want wrapped exporter error", err)
+	}
+}
+
+func TestModuleRegistryValidatesOutputBeforePromptExport(t *testing.T) {
+	called := false
+	registry, err := NewModuleRegistry([]ModuleDefinition{
+		{
+			ID:         module.Metadata,
+			StanzaName: "metadata",
+			Builder: func(ModuleContext, any) (*module.Output, error) {
+				return &module.Output{ID: module.CurrentConditions, StanzaName: "metadata", Value: testRegistryValue{Message: "rich"}}, nil
+			},
+			PromptExporter: func(any) (any, error) {
+				called = true
+				return testRegistryValue{Message: "prompt"}, nil
+			},
+		},
+	})
+	if err != nil {
+		t.Fatalf("NewModuleRegistry() error = %v", err)
+	}
+
+	_, err = registry.BuildModule(testRegistryModuleContext(), module.ConfigItem{ID: module.Metadata})
+	if err == nil || !strings.Contains(err.Error(), `module "metadata" produced output id "current_conditions"`) {
+		t.Fatalf("BuildModule() error = %v, want output id validation error", err)
+	}
+	if called {
+		t.Fatal("PromptExporter called before output validation")
+	}
+}
+
+func TestModuleRegistryPromptValueIsNotPersistedInSnapshotJSON(t *testing.T) {
+	registry, err := NewModuleRegistry([]ModuleDefinition{
+		{
+			ID:         module.Metadata,
+			StanzaName: "metadata",
+			Builder: func(ModuleContext, any) (*module.Output, error) {
+				return &module.Output{ID: module.Metadata, StanzaName: "metadata", Value: testRegistryValue{Message: "rich"}}, nil
+			},
+			PromptExporter: func(any) (any, error) {
+				return testRegistryValue{Message: "prompt-only"}, nil
+			},
+		},
+	})
+	if err != nil {
+		t.Fatalf("NewModuleRegistry() error = %v", err)
+	}
+	output, err := registry.BuildModule(testRegistryModuleContext(), module.ConfigItem{ID: module.Metadata})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	snapshot, err := module.NewSnapshot([]module.Output{*output})
+	if err != nil {
+		t.Fatalf("NewSnapshot() error = %v", err)
+	}
+	data, err := json.Marshal(snapshot)
+	if err != nil {
+		t.Fatalf("Marshal() error = %v", err)
+	}
+	text := string(data)
+	if !strings.Contains(text, `"message":"rich"`) {
+		t.Fatalf("snapshot JSON missing rich value: %s", text)
+	}
+	if strings.Contains(text, "prompt-only") || strings.Contains(text, "promptValue") || strings.Contains(text, "PromptValue") {
+		t.Fatalf("snapshot JSON includes runtime-only prompt value: %s", text)
+	}
+}
+
+func TestDefaultAreaForecastDiscussionModuleOptions(t *testing.T) {
+	tests := []struct {
+		id           report.ID
+		wantSections string
+	}{
+		{id: report.Daily, wantSections: "long_term"},
+		{id: report.Hourly, wantSections: "key_messages,short_term"},
+	}
+
+	registry := report.DefaultRegistry()
+	for _, tt := range tests {
+		t.Run(string(tt.id), func(t *testing.T) {
+			definition := registry.MustLookup(tt.id)
+			var found bool
+			for _, item := range definition.Modules {
+				if item.ID != module.AreaForecastDiscussion {
+					continue
+				}
+				found = true
+				options, ok := item.Options.(module.AreaForecastDiscussionOptions)
+				if !ok {
+					t.Fatalf("AFD options type = %T, want AreaForecastDiscussionOptions", item.Options)
+				}
+				if strings.Join(options.Sections, ",") != tt.wantSections {
+					t.Fatalf("AFD sections = %#v, want %s", options.Sections, tt.wantSections)
+				}
+			}
+			if !found {
+				t.Fatal("default modules missing area_forecast_discussion")
+			}
+		})
+	}
+
+	for _, id := range []report.ID{report.Today, report.Tomorrow} {
+		t.Run(string(id), func(t *testing.T) {
+			definition := registry.MustLookup(id)
+			var found bool
+			for _, item := range definition.Modules {
+				if item.ID != module.AreaForecastDiscussion {
+					continue
+				}
+				found = true
+				if item.Options != nil {
+					t.Fatalf("AFD options = %#v, want default all sections", item.Options)
+				}
+			}
+			if !found {
+				t.Fatal("default modules missing area_forecast_discussion")
+			}
+		})
+	}
+}
+
 func TestModuleRegistryRejectsUnknownModule(t *testing.T) {
 	registry := MustDefaultModuleRegistry()
-	err := registry.ValidateComposition(report.DailyToday, []module.ConfigItem{{ID: module.ID("unknown")}})
+	err := registry.ValidateComposition(report.Daily, []module.ConfigItem{{ID: module.ID("unknown")}})
 	if err == nil || !strings.Contains(err.Error(), `unknown module "unknown"`) {
 		t.Fatalf("error = %v, want unknown module", err)
 	}
@@ -62,7 +326,7 @@ func TestModuleRegistryRejectsUnknownModule(t *testing.T) {
 
 func TestModuleRegistryRejectsDuplicateModuleIDs(t *testing.T) {
 	registry := MustDefaultModuleRegistry()
-	err := registry.ValidateComposition(report.DailyToday, []module.ConfigItem{
+	err := registry.ValidateComposition(report.Daily, []module.ConfigItem{
 		{ID: module.Metadata},
 		{ID: module.Metadata},
 	})
@@ -83,12 +347,84 @@ func TestModuleRegistryRejectsDuplicateStanzaNames(t *testing.T) {
 
 func TestModuleRegistryRejectsIncompatibleReports(t *testing.T) {
 	registry := MustDefaultModuleRegistry()
-	err := registry.ValidateComposition(report.DailyToday, []module.ConfigItem{{ID: module.TomorrowPlanning}})
-	if err == nil || !strings.Contains(err.Error(), `module "tomorrow_planning" is not compatible with report "daily_today"`) {
+	err := registry.ValidateComposition(report.Daily, []module.ConfigItem{{ID: module.TomorrowPlanning}})
+	if err == nil || !strings.Contains(err.Error(), `module "tomorrow_planning" is not compatible with report "daily"`) {
 		t.Fatalf("error = %v, want incompatible report", err)
 	}
 }
 
+func TestModuleRegistryValidatesTodayPlanningSupport(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	if err := registry.ValidateComposition(report.Today, []module.ConfigItem{{ID: module.TodayPlanning}}); err != nil {
+		t.Fatalf("ValidateComposition(today) error = %v", err)
+	}
+	for _, id := range []report.ID{report.Tomorrow, report.Daily} {
+		t.Run(string(id), func(t *testing.T) {
+			err := registry.ValidateComposition(id, []module.ConfigItem{{ID: module.TodayPlanning}})
+			if err == nil || !strings.Contains(err.Error(), `module "today_planning" is not compatible with report`) {
+				t.Fatalf("ValidateComposition(%s) error = %v, want incompatible report", id, err)
+			}
+		})
+	}
+}
+
+func TestModuleRegistryValidatesDailyPlanningSupport(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	if err := registry.ValidateComposition(report.Daily, []module.ConfigItem{{ID: module.DailyPlanning}}); err != nil {
+		t.Fatalf("ValidateComposition(daily) error = %v", err)
+	}
+	for _, id := range []report.ID{report.Today, report.Tomorrow, report.Hourly, report.ThreeDay, report.Weekend, report.Storm} {
+		t.Run(string(id), func(t *testing.T) {
+			err := registry.ValidateComposition(id, []module.ConfigItem{{ID: module.DailyPlanning}})
+			if err == nil || !strings.Contains(err.Error(), `module "daily_planning" is not compatible with report`) {
+				t.Fatalf("ValidateComposition(%s) error = %v, want incompatible report", id, err)
+			}
+		})
+	}
+}
+
+func TestModuleRegistrySupportsTodayEligibleModules(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	err := registry.ValidateComposition(report.Today, []module.ConfigItem{
+		{ID: module.Metadata},
+		{ID: module.CurrentConditions},
+		{ID: module.NarrativeForecast},
+		{ID: module.HourlyForecast},
+		{ID: module.DerivedDailySummary},
+		{ID: module.DerivedDaypartSummaries},
+		{ID: module.PrecipTiming},
+		{ID: module.AlertDigest},
+		{ID: module.SPCConvectiveOutlooks},
+		{ID: module.AreaForecastDiscussion},
+		{ID: module.SPCConvectiveDiscussion},
+		{ID: module.WeatherStory},
+		{ID: module.OutdoorWindows},
+	})
+	if err != nil {
+		t.Fatalf("ValidateComposition(today eligible modules) error = %v", err)
+	}
+}
+
+func TestModuleRegistryRejectsHourlyIncompatibleModules(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	for _, id := range []module.ID{
+		module.NarrativeForecast,
+		module.DerivedDailySummary,
+		module.DerivedDaypartSummaries,
+		module.OutdoorWindows,
+		module.TodayPlanning,
+		module.TomorrowPlanning,
+		module.DailyPlanning,
+	} {
+		t.Run(string(id), func(t *testing.T) {
+			err := registry.ValidateComposition(report.Hourly, []module.ConfigItem{{ID: id}})
+			if err == nil || !strings.Contains(err.Error(), `not compatible with report "hourly"`) {
+				t.Fatalf("ValidateComposition() error = %v, want incompatible hourly module", err)
+			}
+		})
+	}
+}
+
 func TestModuleRegistryRejectsDefinitionsWithoutBuilders(t *testing.T) {
 	_, err := NewModuleRegistry([]ModuleDefinition{
 		{ID: module.Metadata, StanzaName: "metadata", DefaultOptions: module.MetadataOptions{}},
@@ -109,7 +445,7 @@ func TestModuleRegistryRejectsUnsupportedMissingDataWarn(t *testing.T) {
 
 func TestModuleRegistryRejectsInvalidOptionShapes(t *testing.T) {
 	registry := MustDefaultModuleRegistry()
-	err := registry.ValidateComposition(report.DailyToday, []module.ConfigItem{
+	err := registry.ValidateComposition(report.Daily, []module.ConfigItem{
 		{ID: module.Metadata, Options: module.CurrentConditionsOptions{}},
 	})
 	if err == nil || !strings.Contains(err.Error(), `module "metadata" options have type module.CurrentConditionsOptions, want module.MetadataOptions`) {
@@ -119,7 +455,7 @@ func TestModuleRegistryRejectsInvalidOptionShapes(t *testing.T) {
 
 func TestModuleRegistryAcceptsTypedOptions(t *testing.T) {
 	registry := MustDefaultModuleRegistry()
-	err := registry.ValidateComposition(report.DailyToday, []module.ConfigItem{
+	err := registry.ValidateComposition(report.Daily, []module.ConfigItem{
 		{ID: module.Metadata, Options: module.MetadataOptions{}},
 		{ID: module.CurrentConditions, Options: &module.CurrentConditionsOptions{}},
 	})
@@ -128,6 +464,42 @@ func TestModuleRegistryAcceptsTypedOptions(t *testing.T) {
 	}
 }
 
+func TestSPCConvectiveOutlookCollectedRequirementAvailability(t *testing.T) {
+	ctx := ModuleContext{}
+	if collectedFactAvailable(module.CollectedSPCConvectiveOutlooks, ctx) {
+		t.Fatal("collectedFactAvailable() = true, want false without source")
+	}
+
+	ctx.Collected = facts.CollectedFacts{SPCConvectiveOutlooks: &weatherdata.ConvectiveOutlookRun{}}
+	if !collectedFactAvailable(module.CollectedSPCConvectiveOutlooks, ctx) {
+		t.Fatal("collectedFactAvailable() = false, want true with checked source")
+	}
+}
+
+func TestSPCConvectiveOutlookDerivedRequirementAvailability(t *testing.T) {
+	ctx := ModuleContext{}
+	if derivedFactAvailable(module.RequiresDerivedSPCConvectiveOutlooks, ctx) {
+		t.Fatal("derivedFactAvailable() = true, want false without derived outlooks")
+	}
+
+	ctx.Derived = facts.DerivedFacts{SPCConvectiveOutlooks: []weatherdata.ConvectiveOutlook{}}
+	if !derivedFactAvailable(module.RequiresDerivedSPCConvectiveOutlooks, ctx) {
+		t.Fatal("derivedFactAvailable() = false, want true for checked empty derived outlooks")
+	}
+}
+
 func noopModuleBuilder(ModuleContext, any) (*module.Output, error) {
 	return &module.Output{ID: module.Metadata, StanzaName: "metadata", Value: struct{}{}}, nil
 }
+
+type testRegistryValue struct {
+	Message string `json:"message"`
+}
+
+func testRegistryModuleContext() ModuleContext {
+	return ModuleContext{
+		Resolved: report.Resolved{
+			Definition: report.DefaultRegistry().MustLookup(report.Daily),
+		},
+	}
+}

internal/briefing/narrative_forecast_module.go

@@ -4,6 +4,7 @@ import (
 	"time"
 
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/module"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
 )
 
@@ -18,8 +19,8 @@ type NarrativeForecastModule struct {
 
 type NarrativeForecastPeriod struct {
 	Name                              string   `json:"name,omitempty"`
-	StartTime                         string   `json:"start_time,omitempty"`
-	EndTime                           string   `json:"end_time,omitempty"`
+	PeriodBegins                      string   `json:"period_begins,omitempty"`
+	PeriodEnds                        string   `json:"period_ends,omitempty"`
 	IsDay                             *bool    `json:"is_day,omitempty"`
 	TextDescription                   string   `json:"text_description,omitempty"`
 	TemperatureC                      *float64 `json:"temperature_c,omitempty"`
@@ -58,10 +59,11 @@ func buildNarrativeForecastModule(ctx ModuleContext, _ any) (*module.Output, err
 func narrativeForecastPeriods(periods []weatherdata.ForecastPeriod, timezone string) []NarrativeForecastPeriod {
 	out := make([]NarrativeForecastPeriod, 0, len(periods))
 	for _, period := range periods {
+		validPeriod := timeutil.Period{Start: period.StartTime, End: period.EndTime}
 		out = append(out, NarrativeForecastPeriod{
 			Name:                              period.Name,
-			StartTime:                         friendlyDateTimeLabel(period.StartTime, timezone),
-			EndTime:                           friendlyDateTimeLabel(period.EndTime, timezone),
+			PeriodBegins:                      friendlyPeriodBeginsLabel(validPeriod, timezone),
+			PeriodEnds:                        friendlyPeriodEndsLabel(validPeriod, timezone),
 			IsDay:                             copyBool(period.IsDay),
 			TextDescription:                   period.TextDescription,
 			TemperatureC:                      copyFloat(period.TemperatureC),

internal/briefing/outdoor_windows_module.go

@@ -8,31 +8,31 @@ type OutdoorWindowsModule struct {
 }
 
 type OutdoorWindowModule struct {
-	Daypart string   `json:"daypart"`
-	Start   string   `json:"start"`
-	End     string   `json:"end"`
-	Reasons []string `json:"reasons,omitempty"`
-	Score   float64  `json:"score"`
+	Daypart      string   `json:"daypart"`
+	PeriodBegins string   `json:"period_begins,omitempty"`
+	PeriodEnds   string   `json:"period_ends,omitempty"`
+	Reasons      []string `json:"reasons,omitempty"`
+	Score        float64  `json:"score"`
 }
 
 func buildOutdoorWindowsModule(ctx ModuleContext, _ any) (*module.Output, error) {
 	windows := buildOutdoorWindows(ctx.Derived.DaypartSummaries)
 	value := OutdoorWindowsModule{
-		Best:  outdoorWindowValue(windows.Best),
-		Worst: outdoorWindowValue(windows.Worst),
+		Best:  outdoorWindowValue(windows.Best, ctx.Timezone),
+		Worst: outdoorWindowValue(windows.Worst, ctx.Timezone),
 	}
 	return &module.Output{ID: module.OutdoorWindows, StanzaName: "outdoor_windows", Value: value}, nil
 }
 
-func outdoorWindowValue(window *OutdoorWindow) *OutdoorWindowModule {
+func outdoorWindowValue(window *OutdoorWindow, timezone string) *OutdoorWindowModule {
 	if window == nil {
 		return nil
 	}
 	return &OutdoorWindowModule{
-		Daypart: window.Daypart,
-		Start:   window.Start,
-		End:     window.End,
-		Reasons: append([]string(nil), window.Reasons...),
-		Score:   window.Score,
+		Daypart:      window.Daypart,
+		PeriodBegins: friendlyPeriodBeginsLabel(window.Period, timezone),
+		PeriodEnds:   friendlyPeriodEndsLabel(window.Period, timezone),
+		Reasons:      append([]string(nil), window.Reasons...),
+		Score:        window.Score,
 	}
 }

internal/briefing/package.go

@@ -185,9 +185,9 @@ func alertStatus(bundle *weatherdata.Bundle) *AlertStatus {
 
 func variantForReport(id report.ID) string {
 	switch id {
-	case report.DailyToday:
+	case report.Daily, report.Today:
 		return "today"
-	case report.DailyTomorrow:
+	case report.Tomorrow:
 		return "tomorrow"
 	default:
 		return ""

internal/briefing/precip_timing_module.go

@@ -1,10 +1,19 @@
 package briefing
 
 import (
+	"fmt"
+	"strings"
+
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/module"
 )
 
+const (
+	precipTimingChanceLowerBound = 40
+	precipTimingLikelyLowerBound = 50
+	precipTimingExpectLowerBound = 70
+)
+
 type PrecipTimingModule struct {
 	MaxPopPercent        *int                        `json:"max_pop_percent,omitempty"`
 	MaxPopTime           string                      `json:"max_pop_time,omitempty"`
@@ -14,10 +23,15 @@ type PrecipTimingModule struct {
 }
 
 type PrecipitationWindowModule struct {
-	Start         string `json:"start"`
-	End           string `json:"end,omitempty"`
-	MaxPopPercent *int   `json:"max_pop_percent,omitempty"`
-	MaxPopTime    string `json:"max_pop_time,omitempty"`
+	PeriodBegins          string `json:"period_begins"`
+	PeriodBeginsHourLabel string `json:"period_begins_hour_label,omitempty"`
+	PeriodEnds            string `json:"period_ends,omitempty"`
+	PeriodEndsHourLabel   string `json:"period_ends_hour_label,omitempty"`
+	MaxPopPercent         *int   `json:"max_pop_percent,omitempty"`
+	MaxPopTime            string `json:"max_pop_time,omitempty"`
+	MaxPopHourLabel       string `json:"max_pop_hour_label,omitempty"`
+	PrecipitationType     string `json:"precipitation_type,omitempty"`
+	ExpectationPhrase     string `json:"expectation_phrase,omitempty"`
 }
 
 func buildPrecipTimingModule(ctx ModuleContext, _ any) (*module.Output, error) {
@@ -36,14 +50,60 @@ func precipTimingValue(timing forecast.PrecipTiming, timezone string) PrecipTimi
 	}
 	for _, window := range timing.PrecipitationWindows {
 		item := PrecipitationWindowModule{
-			Start: clockLabel(window.Start, timezone),
+			PeriodBegins:          friendlyDateTimeLabel(window.Start, timezone),
+			PeriodBeginsHourLabel: hourMinuteLabel(window.Start, timezone),
 		}
 		if window.End != nil {
-			item.End = clockLabel(*window.End, timezone)
+			item.PeriodEnds = friendlyDateTimeLabel(*window.End, timezone)
+			item.PeriodEndsHourLabel = hourMinuteLabel(*window.End, timezone)
 		}
 		item.MaxPopPercent = roundedInt(&window.MaxPrecipitationProbability.Value)
 		item.MaxPopTime = clockLabel(window.MaxPrecipitationProbability.Time, timezone)
+		item.MaxPopHourLabel = hourMinuteLabel(window.MaxPrecipitationProbability.Time, timezone)
+		item.PrecipitationType = precipitationWindowType(window.TextDescriptions)
+		if item.MaxPopPercent != nil {
+			item.ExpectationPhrase = precipitationWindowExpectationPhrase(*item.MaxPopPercent, item.PrecipitationType)
+		}
 		value.PrecipitationWindows = append(value.PrecipitationWindows, item)
 	}
 	return value
 }
+
+func precipitationWindowType(descriptions []string) string {
+	combined := strings.ToLower(strings.Join(descriptions, " "))
+	switch {
+	case (strings.Contains(combined, "thunderstorm") || strings.Contains(combined, "t-storm")) &&
+		(strings.Contains(combined, "shower") || strings.Contains(combined, "rain")):
+		return "showers and thunderstorms"
+	case strings.Contains(combined, "freezing rain"):
+		return "freezing rain"
+	case strings.Contains(combined, "thunderstorm") || strings.Contains(combined, "t-storm"):
+		return "thunderstorms"
+	case strings.Contains(combined, "shower"):
+		return "showers"
+	case strings.Contains(combined, "snow"):
+		return "snow"
+	case strings.Contains(combined, "drizzle"):
+		return "drizzle"
+	case strings.Contains(combined, "rain"):
+		return "rain"
+	default:
+		return "precipitation"
+	}
+}
+
+func precipitationWindowExpectationPhrase(maxPopPercent int, precipitationType string) string {
+	if precipitationType == "" {
+		precipitationType = "precipitation"
+	}
+	switch {
+	case maxPopPercent >= precipTimingExpectLowerBound:
+		return fmt.Sprintf("Expect %s.", precipitationType)
+	case maxPopPercent >= precipTimingLikelyLowerBound:
+		return fmt.Sprintf("%s likely.", sentenceCase(precipitationType))
+	case maxPopPercent >= precipTimingChanceLowerBound:
+		return fmt.Sprintf("Chance of %s.", precipitationType)
+	default:
+		return ""
+	}
+}

internal/briefing/spc_convective_discussion_module.go

@@ -0,0 +1,94 @@
+package briefing
+
+import (
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/module"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
+)
+
+const defaultSPCConvectiveDiscussionMinimumSeverityRank = defaultSPCRiskDigestMinimumSeverityRank
+const spcCategoricalOutlookType = defaultSPCRiskDigestOutlookType
+
+type SPCConvectiveDiscussionModule struct {
+	IncludedBecause string                          `json:"included_because"`
+	Discussions     []SPCConvectiveDiscussionRecord `json:"discussions"`
+}
+
+type SPCConvectiveDiscussionRecord struct {
+	Day          int    `json:"day,omitempty"`
+	PeriodBegins string `json:"period_begins,omitempty"`
+	PeriodEnds   string `json:"period_ends,omitempty"`
+	Headline     string `json:"headline,omitempty"`
+	Summary      string `json:"summary,omitempty"`
+	Discussion   string `json:"discussion,omitempty"`
+	UpdatedAt    string `json:"updated_at,omitempty"`
+}
+
+func buildSPCConvectiveDiscussionModule(ctx ModuleContext, _ any) (*module.Output, error) {
+	qualifyingPeriods := spcConvectiveDiscussionQualifyingPeriods(ctx.Derived.SPCConvectiveOutlooks, ctx.Resolved.ValidPeriod)
+	if len(qualifyingPeriods) == 0 {
+		return nil, nil
+	}
+	records := spcConvectiveDiscussionRecords(qualifyingPeriods, ctx.Derived.SPCConvectiveDiscussions, ctx.Timezone)
+	if len(records) == 0 {
+		return nil, nil
+	}
+	value := SPCConvectiveDiscussionModule{
+		IncludedBecause: fmt.Sprintf("%s severity_rank >= %d", spcCategoricalOutlookType, defaultSPCConvectiveDiscussionMinimumSeverityRank),
+		Discussions:     records,
+	}
+	return &module.Output{ID: module.SPCConvectiveDiscussion, StanzaName: string(module.SPCConvectiveDiscussion), Value: value}, nil
+}
+
+func spcConvectiveDiscussionQualifyingPeriods(outlooks []weatherdata.ConvectiveOutlook, reportPeriod timeutil.Period) map[int]timeutil.Period {
+	periods := map[int]timeutil.Period{}
+	for _, outlook := range outlooks {
+		if outlook.OutlookType != spcCategoricalOutlookType {
+			continue
+		}
+		if outlook.SeverityRank == nil || *outlook.SeverityRank < defaultSPCConvectiveDiscussionMinimumSeverityRank {
+			continue
+		}
+		outlookPeriod := timeutil.Period{Start: outlook.ValidFrom, End: outlook.ValidTo}
+		if !outlookPeriod.IsValid() || !outlookPeriod.Overlaps(reportPeriod) {
+			continue
+		}
+		if existing, ok := periods[outlook.Day]; ok {
+			if outlookPeriod.Start.Before(existing.Start) {
+				existing.Start = outlookPeriod.Start
+			}
+			if outlookPeriod.End.After(existing.End) {
+				existing.End = outlookPeriod.End
+			}
+			periods[outlook.Day] = existing
+			continue
+		}
+		periods[outlook.Day] = outlookPeriod
+	}
+	return periods
+}
+
+func spcConvectiveDiscussionRecords(qualifyingPeriods map[int]timeutil.Period, discussions []weatherdata.ConvectiveOutlookDiscussion, timezone string) []SPCConvectiveDiscussionRecord {
+	records := make([]SPCConvectiveDiscussionRecord, 0, len(discussions))
+	for _, discussion := range discussions {
+		period, ok := qualifyingPeriods[discussion.Day]
+		if !ok {
+			continue
+		}
+		if discussion.Discussion == "" {
+			continue
+		}
+		records = append(records, SPCConvectiveDiscussionRecord{
+			Day:          discussion.Day,
+			PeriodBegins: friendlyPeriodBeginsLabel(period, timezone),
+			PeriodEnds:   friendlyPeriodEndsLabel(period, timezone),
+			Headline:     discussion.Headline,
+			Summary:      discussion.Summary,
+			Discussion:   discussion.Discussion,
+			UpdatedAt:    friendlyOptionalTime(discussion.UpdatedAt, timezone),
+		})
+	}
+	return records
+}

internal/briefing/spc_convective_discussion_module_test.go

@@ -0,0 +1,317 @@
+package briefing
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/module"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
+)
+
+func TestSPCConvectiveDiscussionModuleOmitsBelowThresholdButOutlookRemains(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := spcConvectiveDiscussionContext(2, []weatherdata.ConvectiveOutlookDiscussion{
+		spcDiscussion(1, "Lower risk", "General thunderstorms.", "No organized severe weather is expected.", "2026-05-29T08:30:00-05:00"),
+	})
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.SPCConvectiveDiscussion})
+	if err != nil {
+		t.Fatalf("BuildModule(discussion) error = %v", err)
+	}
+	if output != nil {
+		t.Fatalf("discussion output = %#v, want omitted below threshold", output)
+	}
+
+	outlookOutput, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.SPCConvectiveOutlooks})
+	if err != nil {
+		t.Fatalf("BuildModule(outlooks) error = %v", err)
+	}
+	outlookValue := moduleValue[SPCConvectiveOutlooksModule](t, outlookOutput)
+	if !outlookValue.Checked || outlookValue.OutlookCount != 1 {
+		t.Fatalf("outlook value = %#v, want lower-risk outlook still emitted", outlookValue)
+	}
+}
+
+func TestSPCConvectiveDiscussionModuleIncludesEqualThresholdDiscussion(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := spcConvectiveDiscussionContext(3, []weatherdata.ConvectiveOutlookDiscussion{
+		spcDiscussion(1, "Severe storms possible", "Scattered severe storms are possible.", "A few storms may become severe during the afternoon.", "2026-05-29T08:30:00-05:00"),
+	})
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.SPCConvectiveDiscussion})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	if output == nil || output.ID != module.SPCConvectiveDiscussion || output.StanzaName != "spc_convective_discussion" {
+		t.Fatalf("output = %#v, want spc convective discussion stanza", output)
+	}
+	value := moduleValue[SPCConvectiveDiscussionModule](t, output)
+	if value.IncludedBecause != "categorical severity_rank >= 3" || len(value.Discussions) != 1 {
+		t.Fatalf("value = %#v, want threshold reason and one discussion", value)
+	}
+	discussion := value.Discussions[0]
+	if discussion.Day != 1 || discussion.Headline != "Severe storms possible" || discussion.Summary == "" || discussion.Discussion == "" {
+		t.Fatalf("discussion = %#v, want prompt-facing discussion fields", discussion)
+	}
+	if discussion.PeriodBegins != "2026-05-29 at 11:00 AM" || discussion.PeriodEnds != "2026-05-30 at 7:00 AM" {
+		t.Fatalf("Period = %q/%q, want qualifying outlook valid period", discussion.PeriodBegins, discussion.PeriodEnds)
+	}
+	if discussion.UpdatedAt != "2026-05-29 at 8:30 AM" {
+		t.Fatalf("UpdatedAt = %q, want friendly local time", discussion.UpdatedAt)
+	}
+	data, err := json.Marshal(output.Value)
+	if err != nil {
+		t.Fatalf("Marshal() error = %v", err)
+	}
+	text := string(data)
+	for _, field := range []string{"included_because", "discussions", "period_begins", "period_ends", "headline", "summary", "discussion", "updated_at"} {
+		if !strings.Contains(text, field) {
+			t.Fatalf("json = %s, want field %s", text, field)
+		}
+	}
+	if strings.Contains(text, `"period":`) {
+		t.Fatalf("json = %s, want period_begins/period_ends instead of period", text)
+	}
+}
+
+func TestSPCConvectiveDiscussionModuleIncludesAboveThresholdDiscussion(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := spcConvectiveDiscussionContext(4, []weatherdata.ConvectiveOutlookDiscussion{
+		spcDiscussion(1, "Enhanced severe risk", "Numerous severe storms are possible.", "Severe storms may produce damaging winds.", "2026-05-29T09:15:00-05:00"),
+	})
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.SPCConvectiveDiscussion})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	value := moduleValue[SPCConvectiveDiscussionModule](t, output)
+	if len(value.Discussions) != 1 || value.Discussions[0].Headline != "Enhanced severe risk" {
+		t.Fatalf("value = %#v, want above-threshold discussion", value)
+	}
+}
+
+func TestSPCConvectiveDiscussionModuleIgnoresHighRankNonCategoricalOutlook(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	rank := 30
+	ctx := testModuleContext()
+	outlook := weatherdata.ConvectiveOutlook{
+		ID:           "day1-wind-30",
+		Day:          1,
+		OutlookType:  "wind",
+		Label:        "30%",
+		LabelText:    "30% Wind Risk",
+		SeverityRank: &rank,
+		ValidFrom:    mustParseModuleTime("2026-05-29T11:00:00-05:00"),
+		ValidTo:      mustParseModuleTime("2026-05-30T07:00:00-05:00"),
+	}
+	ctx.Collected.SPCConvectiveOutlooks = &weatherdata.ConvectiveOutlookRun{
+		Outlooks: []weatherdata.ConvectiveOutlook{outlook},
+	}
+	ctx.Derived.SPCConvectiveOutlooks = []weatherdata.ConvectiveOutlook{outlook}
+	ctx.Derived.SPCConvectiveDiscussions = []weatherdata.ConvectiveOutlookDiscussion{
+		spcDiscussion(1, "Wind risk discussion", "High wind probabilities.", "This discussion should not be emitted from wind severity rank.", "2026-05-29T08:30:00-05:00"),
+	}
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.SPCConvectiveDiscussion})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	if output != nil {
+		t.Fatalf("output = %#v, want non-categorical outlook ignored for discussion threshold", output)
+	}
+}
+
+func TestSPCConvectiveDiscussionModuleRequiresCategoricalThresholdForMixedSameDayOutlooks(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	rank2 := 2
+	rank30 := 30
+	ctx := testModuleContext()
+	categorical := weatherdata.ConvectiveOutlook{
+		ID:           "day1-marginal",
+		Day:          1,
+		OutlookType:  "categorical",
+		Label:        "MRGL",
+		LabelText:    "Marginal Risk",
+		SeverityRank: &rank2,
+		ValidFrom:    mustParseModuleTime("2026-05-29T11:00:00-05:00"),
+		ValidTo:      mustParseModuleTime("2026-05-30T07:00:00-05:00"),
+	}
+	wind := weatherdata.ConvectiveOutlook{
+		ID:           "day1-wind-30",
+		Day:          1,
+		OutlookType:  "wind",
+		Label:        "30%",
+		LabelText:    "30% Wind Risk",
+		SeverityRank: &rank30,
+		ValidFrom:    mustParseModuleTime("2026-05-29T11:00:00-05:00"),
+		ValidTo:      mustParseModuleTime("2026-05-30T07:00:00-05:00"),
+	}
+	ctx.Collected.SPCConvectiveOutlooks = &weatherdata.ConvectiveOutlookRun{
+		Outlooks: []weatherdata.ConvectiveOutlook{categorical, wind},
+	}
+	ctx.Derived.SPCConvectiveOutlooks = []weatherdata.ConvectiveOutlook{categorical, wind}
+	ctx.Derived.SPCConvectiveDiscussions = []weatherdata.ConvectiveOutlookDiscussion{
+		spcDiscussion(1, "Mixed risk discussion", "Only wind is high.", "This discussion should not be emitted without categorical threshold.", "2026-05-29T08:30:00-05:00"),
+	}
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.SPCConvectiveDiscussion})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	if output != nil {
+		t.Fatalf("output = %#v, want mixed day omitted when categorical outlook is below threshold", output)
+	}
+}
+
+func TestSPCConvectiveDiscussionModuleIncludesOnlyQualifyingDays(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	rank2 := 2
+	rank4 := 4
+	ctx := testModuleContext()
+	ctx.Resolved.ValidPeriod.Start = mustParseModuleTime("2026-05-30T00:00:00-05:00")
+	ctx.Resolved.ValidPeriod.End = mustParseModuleTime("2026-05-31T00:00:00-05:00")
+	day1Outlook := weatherdata.ConvectiveOutlook{
+		ID:           "day1-marginal",
+		Day:          1,
+		OutlookType:  "categorical",
+		Label:        "MRGL",
+		LabelText:    "Marginal Risk",
+		SeverityRank: &rank2,
+		ValidFrom:    mustParseModuleTime("2026-05-29T11:00:00-05:00"),
+		ValidTo:      mustParseModuleTime("2026-05-30T07:00:00-05:00"),
+	}
+	day2Outlook := weatherdata.ConvectiveOutlook{
+		ID:           "day2-enhanced",
+		Day:          2,
+		OutlookType:  "categorical",
+		Label:        "ENH",
+		LabelText:    "Enhanced Risk",
+		SeverityRank: &rank4,
+		ValidFrom:    mustParseModuleTime("2026-05-30T07:00:00-05:00"),
+		ValidTo:      mustParseModuleTime("2026-05-31T07:00:00-05:00"),
+	}
+	ctx.Collected.SPCConvectiveOutlooks = &weatherdata.ConvectiveOutlookRun{
+		Outlooks: []weatherdata.ConvectiveOutlook{day1Outlook, day2Outlook},
+	}
+	ctx.Derived.SPCConvectiveOutlooks = []weatherdata.ConvectiveOutlook{day1Outlook, day2Outlook}
+	ctx.Derived.SPCConvectiveDiscussions = []weatherdata.ConvectiveOutlookDiscussion{
+		spcDiscussion(1, "Day 1 regional discussion", "Marginal risk discussion.", "Day 1 text should not be emitted.", "2026-05-29T08:30:00-05:00"),
+		spcDiscussion(2, "Day 2 regional discussion", "Enhanced risk discussion.", "Day 2 text should be emitted.", "2026-05-30T08:30:00-05:00"),
+	}
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.SPCConvectiveDiscussion})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	value := moduleValue[SPCConvectiveDiscussionModule](t, output)
+	if len(value.Discussions) != 1 {
+		t.Fatalf("Discussions = %#v, want only the qualifying day discussion", value.Discussions)
+	}
+	if value.Discussions[0].Day != 2 || value.Discussions[0].Headline != "Day 2 regional discussion" {
+		t.Fatalf("Discussions[0] = %#v, want day 2 discussion only", value.Discussions[0])
+	}
+	if value.Discussions[0].PeriodBegins != "2026-05-30 at 7:00 AM" || value.Discussions[0].PeriodEnds != "2026-05-31 at 7:00 AM" {
+		t.Fatalf("Period = %q/%q, want qualifying day 2 outlook period", value.Discussions[0].PeriodBegins, value.Discussions[0].PeriodEnds)
+	}
+}
+
+func TestSPCConvectiveDiscussionModuleOmitsNonOverlappingQualifyingOutlook(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	rank := 5
+	ctx := testModuleContext()
+	outlook := weatherdata.ConvectiveOutlook{
+		ID:           "day2-enhanced",
+		Day:          2,
+		OutlookType:  "categorical",
+		Label:        "ENH",
+		LabelText:    "Enhanced Risk",
+		SeverityRank: &rank,
+		ValidFrom:    mustParseModuleTime("2026-05-30T07:00:00-05:00"),
+		ValidTo:      mustParseModuleTime("2026-05-31T07:00:00-05:00"),
+	}
+	ctx.Collected.SPCConvectiveOutlooks = &weatherdata.ConvectiveOutlookRun{
+		Outlooks: []weatherdata.ConvectiveOutlook{outlook},
+	}
+	ctx.Derived.SPCConvectiveOutlooks = []weatherdata.ConvectiveOutlook{outlook}
+	ctx.Derived.SPCConvectiveDiscussions = []weatherdata.ConvectiveOutlookDiscussion{
+		spcDiscussion(2, "Day 2 regional discussion", "Enhanced risk discussion.", "Day 2 text should not be emitted for today.", "2026-05-30T08:30:00-05:00"),
+	}
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.SPCConvectiveDiscussion})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	if output != nil {
+		t.Fatalf("output = %#v, want non-overlapping discussion omitted", output)
+	}
+}
+
+func TestSPCConvectiveDiscussionModuleOmitsMissingDiscussionText(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := spcConvectiveDiscussionContext(3, []weatherdata.ConvectiveOutlookDiscussion{
+		{Day: 1, Headline: "Severe storms possible", Summary: "Scattered severe storms are possible.", UpdatedAt: ptrModuleTime("2026-05-29T08:30:00-05:00")},
+	})
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.SPCConvectiveDiscussion})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	if output != nil {
+		t.Fatalf("output = %#v, want omitted when discussion text is missing", output)
+	}
+}
+
+func TestSPCConvectiveDiscussionModuleOmitsMissingSource(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := testModuleContext()
+	ctx.Collected.SPCConvectiveOutlooks = nil
+	ctx.Derived.SPCConvectiveOutlooks = nil
+	ctx.Derived.SPCConvectiveDiscussions = nil
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.SPCConvectiveDiscussion})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	if output != nil {
+		t.Fatalf("output = %#v, want omitted for missing optional source", output)
+	}
+}
+
+func spcConvectiveDiscussionContext(rank int, discussions []weatherdata.ConvectiveOutlookDiscussion) ModuleContext {
+	ctx := testModuleContext()
+	outlook := weatherdata.ConvectiveOutlook{
+		ID:           "day1-categorical",
+		Day:          1,
+		OutlookType:  "categorical",
+		Label:        "SLGT",
+		LabelText:    "Slight Risk",
+		SeverityRank: &rank,
+		ValidFrom:    mustParseModuleTime("2026-05-29T11:00:00-05:00"),
+		ValidTo:      mustParseModuleTime("2026-05-30T07:00:00-05:00"),
+	}
+	ctx.Collected.SPCConvectiveOutlooks = &weatherdata.ConvectiveOutlookRun{
+		AsOf:     ptrModuleTime("2026-05-29T08:00:00-05:00"),
+		IssuedAt: ptrModuleTime("2026-05-29T07:45:00-05:00"),
+		Outlooks: []weatherdata.ConvectiveOutlook{outlook},
+	}
+	ctx.Derived.SPCConvectiveOutlooks = []weatherdata.ConvectiveOutlook{outlook}
+	ctx.Derived.SPCConvectiveDiscussions = discussions
+	return ctx
+}
+
+func spcDiscussion(day int, headline string, summary string, discussion string, updatedAt string) weatherdata.ConvectiveOutlookDiscussion {
+	return weatherdata.ConvectiveOutlookDiscussion{
+		Day:        day,
+		Headline:   headline,
+		Summary:    summary,
+		Discussion: discussion,
+		UpdatedAt:  ptrModuleTime(updatedAt),
+	}
+}
+
+func ptrModuleTime(value string) *time.Time {
+	parsed := mustParseModuleTime(value)
+	return &parsed
+}

internal/briefing/spc_convective_outlook_definitions.go

@@ -0,0 +1,37 @@
+package briefing
+
+import (
+	"embed"
+	"encoding/json"
+	"fmt"
+	"strings"
+)
+
+//go:embed assets/spc_convective_outlook_definitions.json
+var spcConvectiveOutlookDefinitionAssets embed.FS
+
+var spcOutlookBackgroundDefinitions = mustLoadSPCOutlookBackgroundDefinitions()
+
+func mustLoadSPCOutlookBackgroundDefinitions() map[string]SPCOutlookBackgroundDefinition {
+	data, err := spcConvectiveOutlookDefinitionAssets.ReadFile("assets/spc_convective_outlook_definitions.json")
+	if err != nil {
+		panic(fmt.Sprintf("read embedded SPC outlook definitions: %v", err))
+	}
+	var definitions map[string]SPCOutlookBackgroundDefinition
+	if err := json.Unmarshal(data, &definitions); err != nil {
+		panic(fmt.Sprintf("decode embedded SPC outlook definitions: %v", err))
+	}
+	return definitions
+}
+
+func spcOutlookBackgroundDefinition(outlookType string, label string) *SPCOutlookBackgroundDefinition {
+	definition, ok := spcOutlookBackgroundDefinitions[spcOutlookDefinitionKey(outlookType, label)]
+	if !ok {
+		return nil
+	}
+	return &definition
+}
+
+func spcOutlookDefinitionKey(outlookType string, label string) string {
+	return strings.ToLower(strings.TrimSpace(outlookType)) + ":" + strings.ToUpper(strings.TrimSpace(label))
+}

internal/briefing/spc_convective_outlooks_module.go

@@ -0,0 +1,162 @@
+package briefing
+
+import (
+	"strings"
+	"time"
+	"unicode"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/module"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
+)
+
+const defaultSPCRiskDigestOutlookType = "categorical"
+const defaultSPCRiskDigestMinimumSeverityRank = 3
+
+type SPCConvectiveOutlooksModule struct {
+	Checked      bool                         `json:"checked"`
+	AsOf         string                       `json:"as_of,omitempty"`
+	IssuedAt     string                       `json:"issued_at,omitempty"`
+	LocationID   string                       `json:"location_id,omitempty"`
+	LocationName string                       `json:"location_name,omitempty"`
+	OutlookCount int                          `json:"outlook_count"`
+	Outlooks     []SPCConvectiveOutlookRecord `json:"outlooks,omitempty"`
+	RiskDigest   []SPCConvectiveOutlookDigest `json:"risk_digest,omitempty"`
+}
+
+type SPCConvectiveOutlookRecord struct {
+	Day                  int                             `json:"day,omitempty"`
+	OutlookType          string                          `json:"outlook_type,omitempty"`
+	Label                string                          `json:"label,omitempty"`
+	LabelText            string                          `json:"label_text,omitempty"`
+	BackgroundDefinition *SPCOutlookBackgroundDefinition `json:"background_definition,omitempty"`
+	PeriodBegins         string                          `json:"period_begins,omitempty"`
+	PeriodEnds           string                          `json:"period_ends,omitempty"`
+	IssuedAt             string                          `json:"issued_at,omitempty"`
+	ContainsLocation     bool                            `json:"contains_location"`
+	ImageURL             string                          `json:"image_url,omitempty"`
+}
+
+type SPCOutlookBackgroundDefinition struct {
+	PlainLanguage       string `json:"plain_language,omitempty"`
+	OfficialDescription string `json:"official_description,omitempty"`
+	RelativeLevel       string `json:"relative_level,omitempty"`
+}
+
+type SPCConvectiveOutlookDigest struct {
+	LabelText    string `json:"label_text,omitempty"`
+	RiskLabel    string `json:"risk_label,omitempty"`
+	PeriodBegins string `json:"period_begins,omitempty"`
+	PeriodEnds   string `json:"period_ends,omitempty"`
+}
+
+func buildSPCConvectiveOutlooksModule(ctx ModuleContext, _ any) (*module.Output, error) {
+	value := SPCConvectiveOutlooksModule{}
+	run := ctx.Collected.SPCConvectiveOutlooks
+	if run != nil {
+		value.Checked = true
+		value.AsOf = friendlyOptionalTime(run.AsOf, ctx.Timezone)
+		value.IssuedAt = friendlyOptionalTime(run.IssuedAt, ctx.Timezone)
+		value.LocationID = run.LocationID
+		value.LocationName = run.LocationName
+	}
+	source, ok := sourceByName(ctx.Collected.SourceProvenance, string(module.SPCConvectiveOutlooks))
+	if value.Checked && value.AsOf == "" && ok && !source.FetchedAt.IsZero() {
+		value.AsOf = friendlyDateTimeLabel(source.FetchedAt, ctx.Timezone)
+	}
+	if value.Checked && value.IssuedAt == "" && ok {
+		value.IssuedAt = friendlyOptionalTime(source.IssuedAt, ctx.Timezone)
+	}
+
+	value.Outlooks = spcConvectiveOutlookRecords(ctx.Derived.SPCConvectiveOutlooks, ctx.Resolved.ValidPeriod, ctx.Timezone)
+	value.RiskDigest = spcConvectiveOutlookRiskDigest(ctx.Derived.SPCConvectiveOutlooks, ctx.Resolved.ValidPeriod, ctx.Timezone, defaultSPCRiskDigestPolicy())
+	value.OutlookCount = len(value.Outlooks)
+	return &module.Output{ID: module.SPCConvectiveOutlooks, StanzaName: string(module.SPCConvectiveOutlooks), Value: value}, nil
+}
+
+type spcRiskDigestPolicy struct {
+	OutlookType         string
+	MinimumSeverityRank int
+}
+
+func defaultSPCRiskDigestPolicy() spcRiskDigestPolicy {
+	return spcRiskDigestPolicy{
+		OutlookType:         defaultSPCRiskDigestOutlookType,
+		MinimumSeverityRank: defaultSPCRiskDigestMinimumSeverityRank,
+	}
+}
+
+func spcConvectiveOutlookRecords(outlooks []weatherdata.ConvectiveOutlook, reportPeriod timeutil.Period, timezone string) []SPCConvectiveOutlookRecord {
+	records := make([]SPCConvectiveOutlookRecord, 0, len(outlooks))
+	for _, outlook := range outlooks {
+		outlookPeriod := timeutil.Period{Start: outlook.ValidFrom, End: outlook.ValidTo}
+		if !outlookPeriod.IsValid() || !outlookPeriod.Overlaps(reportPeriod) {
+			continue
+		}
+		records = append(records, SPCConvectiveOutlookRecord{
+			Day:                  outlook.Day,
+			OutlookType:          outlook.OutlookType,
+			Label:                outlook.Label,
+			LabelText:            outlook.LabelText,
+			BackgroundDefinition: spcOutlookBackgroundDefinition(outlook.OutlookType, outlook.Label),
+			PeriodBegins:         friendlyPeriodBeginsLabel(outlookPeriod, timezone),
+			PeriodEnds:           friendlyPeriodEndsLabel(outlookPeriod, timezone),
+			IssuedAt:             friendlyOptionalTime(outlook.IssuedAt, timezone),
+			ContainsLocation:     outlook.ContainsLocation,
+			ImageURL:             outlook.ImageURL,
+		})
+	}
+	return records
+}
+
+func spcConvectiveOutlookRiskDigest(outlooks []weatherdata.ConvectiveOutlook, reportPeriod timeutil.Period, timezone string, policy spcRiskDigestPolicy) []SPCConvectiveOutlookDigest {
+	records := make([]SPCConvectiveOutlookDigest, 0, len(outlooks))
+	for _, outlook := range outlooks {
+		if outlook.OutlookType != policy.OutlookType {
+			continue
+		}
+		if outlook.SeverityRank == nil || *outlook.SeverityRank < policy.MinimumSeverityRank {
+			continue
+		}
+		if !outlook.ContainsLocation {
+			continue
+		}
+		outlookPeriod := timeutil.Period{Start: outlook.ValidFrom, End: outlook.ValidTo}
+		if !outlookPeriod.IsValid() || !outlookPeriod.Overlaps(reportPeriod) {
+			continue
+		}
+		records = append(records, SPCConvectiveOutlookDigest{
+			LabelText:    outlook.LabelText,
+			RiskLabel:    spcRiskDigestLabel(outlook.LabelText),
+			PeriodBegins: friendlyMonthDayTimeLabel(outlookPeriod.Start, timezone),
+			PeriodEnds:   friendlyMonthDayTimeLabel(outlookPeriod.End, timezone),
+		})
+	}
+	return records
+}
+
+func spcRiskDigestLabel(labelText string) string {
+	label := strings.TrimSpace(labelText)
+	if label == "" {
+		return ""
+	}
+	runes := []rune(strings.ToLower(label))
+	runes[0] = unicode.ToUpper(runes[0])
+	return string(runes)
+}
+
+func friendlyOptionalTime(value *time.Time, timezone string) string {
+	if value == nil {
+		return ""
+	}
+	return friendlyDateTimeLabel(*value, timezone)
+}
+
+func sourceByName(sources []weatherdata.Source, name string) (weatherdata.Source, bool) {
+	for _, source := range sources {
+		if source.Name == name {
+			return source, true
+		}
+	}
+	return weatherdata.Source{}, false
+}

internal/briefing/spc_convective_outlooks_module_test.go

@@ -0,0 +1,355 @@
+package briefing
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/module"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
+)
+
+func TestSPCConvectiveOutlooksModuleBuildsPromptSafeRiskProduct(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := testModuleContext()
+	rank := 3
+	asOf := mustParseModuleTime("2026-05-29T14:00:00Z")
+	issuedAt := mustParseModuleTime("2026-05-29T13:45:00Z")
+	expiresAt := mustParseModuleTime("2026-05-30T07:00:00-05:00")
+	outlook := weatherdata.ConvectiveOutlook{
+		ID:               "day1-categorical-slight",
+		Provider:         "spc",
+		Product:          "convective_outlook",
+		Day:              1,
+		OutlookType:      "categorical",
+		Label:            "SLGT",
+		LabelText:        "Slight Risk",
+		Forecaster:       "Smith",
+		SeverityRank:     &rank,
+		ValidFrom:        mustParseModuleTime("2026-05-29T11:00:00-05:00"),
+		ValidTo:          mustParseModuleTime("2026-05-30T07:00:00-05:00"),
+		IssuedAt:         &issuedAt,
+		ExpiresAt:        &expiresAt,
+		SourceURL:        "https://www.spc.noaa.gov/products/outlook/day1otlk.html",
+		ImageURL:         "https://www.spc.noaa.gov/products/outlook/day1probotlk_2000_torn.gif",
+		ContainsLocation: true,
+		Geometry:         json.RawMessage(`{"type":"Polygon","coordinates":[]}`),
+	}
+	ctx.Collected.SPCConvectiveOutlooks = &weatherdata.ConvectiveOutlookRun{
+		LocationID:   "nws-lsx-grid-90-74",
+		LocationName: "St. Louis, MO",
+		AsOf:         &asOf,
+		IssuedAt:     &issuedAt,
+		Outlooks:     []weatherdata.ConvectiveOutlook{outlook},
+	}
+	ctx.Derived.SPCConvectiveOutlooks = []weatherdata.ConvectiveOutlook{outlook}
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.SPCConvectiveOutlooks})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	if output == nil || output.ID != module.SPCConvectiveOutlooks || output.StanzaName != "spc_convective_outlooks" {
+		t.Fatalf("output = %#v, want spc convective outlook output", output)
+	}
+	value := moduleValue[SPCConvectiveOutlooksModule](t, output)
+	if !value.Checked || value.OutlookCount != 1 || value.AsOf != "2026-05-29 at 9:00 AM" || value.IssuedAt != "2026-05-29 at 8:45 AM" {
+		t.Fatalf("SPCConvectiveOutlooksModule = %#v, want checked source timing and one outlook", value)
+	}
+	if value.LocationID != "nws-lsx-grid-90-74" || value.LocationName != "St. Louis, MO" {
+		t.Fatalf("source location = %q/%q, want Weather API location", value.LocationID, value.LocationName)
+	}
+	if len(value.Outlooks) != 1 {
+		t.Fatalf("Outlooks length = %d, want 1", len(value.Outlooks))
+	}
+	got := value.Outlooks[0]
+	if got.Day != 1 || got.OutlookType != "categorical" || got.Label != "SLGT" || got.LabelText != "Slight Risk" {
+		t.Fatalf("outlook = %#v, want categorical slight risk fields", got)
+	}
+	if got.BackgroundDefinition == nil ||
+		got.BackgroundDefinition.PlainLanguage != "Scattered severe storms possible." ||
+		got.BackgroundDefinition.OfficialDescription != "Isolated intense storms are possible within the risk area, but severe weather is generally expected to be short-lived and/or not widespread." ||
+		got.BackgroundDefinition.RelativeLevel != "2 of 5" {
+		t.Fatalf("background definition = %#v, want Slight Risk helper", got.BackgroundDefinition)
+	}
+	if got.PeriodBegins != "2026-05-29 at 11:00 AM" || got.PeriodEnds != "2026-05-30 at 7:00 AM" || got.IssuedAt != "2026-05-29 at 8:45 AM" {
+		t.Fatalf("outlook times = %#v, want friendly local labels", got)
+	}
+	if !got.ContainsLocation || got.ImageURL == "" {
+		t.Fatalf("outlook = %#v, want location flag and image URL", got)
+	}
+	if len(value.RiskDigest) != 1 {
+		t.Fatalf("RiskDigest length = %d, want 1", len(value.RiskDigest))
+	}
+	digest := value.RiskDigest[0]
+	if digest.LabelText != "Slight Risk" || digest.RiskLabel != "Slight risk" || digest.PeriodBegins != "May 29 at 11:00 AM" || digest.PeriodEnds != "May 30 at 7:00 AM" {
+		t.Fatalf("risk digest = %#v, want prompt-facing slight risk record", digest)
+	}
+	data, err := json.Marshal(output.Value)
+	if err != nil {
+		t.Fatalf("Marshal() error = %v", err)
+	}
+	text := string(data)
+	for _, field := range []string{"checked", "as_of", "issued_at", "location_id", "location_name", "outlook_count", "outlooks", "risk_digest", "background_definition", "plain_language", "official_description", "relative_level", "period_begins", "period_ends", "contains_location", "image_url"} {
+		if !strings.Contains(text, field) {
+			t.Fatalf("json = %s, want field %s", text, field)
+		}
+	}
+	for _, omitted := range []string{"geometry", "coordinates", "forecaster", "provider", "severity_rank", "expires_at", "source_url", "valid_start", "valid_end", `"period":`} {
+		if strings.Contains(text, omitted) {
+			t.Fatalf("json = %s, want prompt-safe outlook without %s", text, omitted)
+		}
+	}
+}
+
+func TestSPCOutlookBackgroundDefinitionLookup(t *testing.T) {
+	tests := []struct {
+		name        string
+		outlookType string
+		label       string
+		want        bool
+	}{
+		{name: "exact slight risk", outlookType: "categorical", label: "SLGT", want: true},
+		{name: "normalized slight risk", outlookType: " Categorical ", label: "slgt", want: true},
+		{name: "expanded marginal risk", outlookType: "categorical", label: "MRGL", want: true},
+		{name: "expanded conditional tornado risk", outlookType: "tornado", label: "CIG3", want: true},
+		{name: "unknown risk", outlookType: "categorical", label: "FOO"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			definition := spcOutlookBackgroundDefinition(tt.outlookType, tt.label)
+			if tt.want && definition == nil {
+				t.Fatalf("spcOutlookBackgroundDefinition(%q, %q) = nil, want definition", tt.outlookType, tt.label)
+			}
+			if !tt.want && definition != nil {
+				t.Fatalf("spcOutlookBackgroundDefinition(%q, %q) = %#v, want nil", tt.outlookType, tt.label, definition)
+			}
+		})
+	}
+}
+
+func TestSPCConvectiveOutlooksModuleOmitsUnknownBackgroundDefinition(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := testModuleContext()
+	outlook := spcRiskDigestTestOutlook("categorical", "Unknown Risk", 2, true,
+		"2026-05-29T11:00:00-05:00", "2026-05-30T07:00:00-05:00")
+	outlook.Label = "FOO"
+	ctx.Collected.SPCConvectiveOutlooks = &weatherdata.ConvectiveOutlookRun{
+		Outlooks: []weatherdata.ConvectiveOutlook{outlook},
+	}
+	ctx.Derived.SPCConvectiveOutlooks = []weatherdata.ConvectiveOutlook{outlook}
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.SPCConvectiveOutlooks})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	value := moduleValue[SPCConvectiveOutlooksModule](t, output)
+	if len(value.Outlooks) != 1 {
+		t.Fatalf("Outlooks length = %d, want 1", len(value.Outlooks))
+	}
+	if value.Outlooks[0].BackgroundDefinition != nil {
+		t.Fatalf("BackgroundDefinition = %#v, want nil for undefined risk", value.Outlooks[0].BackgroundDefinition)
+	}
+}
+
+func TestSPCOutlookBackgroundDefinitionsAssetHasUsableEntries(t *testing.T) {
+	wantKeys := []string{
+		"categorical:TSTM",
+		"categorical:MRGL",
+		"categorical:SLGT",
+		"categorical:ENH",
+		"categorical:MDT",
+		"categorical:HIGH",
+		"tornado:CIG1",
+		"tornado:CIG2",
+		"tornado:CIG3",
+		"wind:CIG1",
+		"wind:CIG2",
+		"wind:CIG3",
+		"hail:CIG1",
+		"hail:CIG2",
+	}
+	if len(spcOutlookBackgroundDefinitions) != len(wantKeys) {
+		t.Fatalf("embedded SPC outlook background definitions length = %d, want %d", len(spcOutlookBackgroundDefinitions), len(wantKeys))
+	}
+	for _, key := range wantKeys {
+		if _, ok := spcOutlookBackgroundDefinitions[key]; !ok {
+			t.Fatalf("embedded SPC outlook background definitions missing %q", key)
+		}
+	}
+	for key, definition := range spcOutlookBackgroundDefinitions {
+		if strings.TrimSpace(key) == "" {
+			t.Fatal("embedded SPC outlook background definitions contain empty key")
+		}
+		if definition.PlainLanguage == "" || definition.OfficialDescription == "" || definition.RelativeLevel == "" {
+			t.Fatalf("embedded SPC outlook background definition %q is incomplete: %#v", key, definition)
+		}
+		if strings.Contains(definition.OfficialDescription, ".Note") || strings.Contains(definition.OfficialDescription, "higher.Note") {
+			t.Fatalf("embedded SPC outlook background definition %q has missing sentence spacing: %q", key, definition.OfficialDescription)
+		}
+		if strings.Contains(definition.OfficialDescription, "by themselves") {
+			t.Fatalf("embedded SPC outlook background definition %q has singular grammar issue: %q", key, definition.OfficialDescription)
+		}
+	}
+}
+
+func TestSPCRiskDigestDefaultPolicyConstants(t *testing.T) {
+	if defaultSPCRiskDigestOutlookType != "categorical" {
+		t.Fatalf("defaultSPCRiskDigestOutlookType = %q, want categorical", defaultSPCRiskDigestOutlookType)
+	}
+	if defaultSPCRiskDigestMinimumSeverityRank != 3 {
+		t.Fatalf("defaultSPCRiskDigestMinimumSeverityRank = %d, want 3", defaultSPCRiskDigestMinimumSeverityRank)
+	}
+}
+
+func TestSPCConvectiveOutlooksRiskDigestFilters(t *testing.T) {
+	tests := []struct {
+		name     string
+		outlook  weatherdata.ConvectiveOutlook
+		wantRisk bool
+	}{
+		{
+			name: "categorical slight risk included",
+			outlook: spcRiskDigestTestOutlook("categorical", "Slight Risk", 3, true,
+				"2026-05-29T11:00:00-05:00", "2026-05-30T07:00:00-05:00"),
+			wantRisk: true,
+		},
+		{
+			name: "marginal risk excluded",
+			outlook: spcRiskDigestTestOutlook("categorical", "Marginal Risk", 2, true,
+				"2026-05-29T11:00:00-05:00", "2026-05-30T07:00:00-05:00"),
+		},
+		{
+			name: "non categorical high rank excluded",
+			outlook: spcRiskDigestTestOutlook("wind", "30% Wind Risk", 30, true,
+				"2026-05-29T11:00:00-05:00", "2026-05-30T07:00:00-05:00"),
+		},
+		{
+			name: "non overlapping excluded",
+			outlook: spcRiskDigestTestOutlook("categorical", "Enhanced Risk", 4, true,
+				"2026-05-30T07:00:00-05:00", "2026-05-31T07:00:00-05:00"),
+		},
+		{
+			name: "location miss excluded",
+			outlook: spcRiskDigestTestOutlook("categorical", "Moderate Risk", 5, false,
+				"2026-05-29T11:00:00-05:00", "2026-05-30T07:00:00-05:00"),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			registry := MustDefaultModuleRegistry()
+			ctx := testModuleContext()
+			ctx.Collected.SPCConvectiveOutlooks = &weatherdata.ConvectiveOutlookRun{
+				Outlooks: []weatherdata.ConvectiveOutlook{tt.outlook},
+			}
+			ctx.Derived.SPCConvectiveOutlooks = []weatherdata.ConvectiveOutlook{tt.outlook}
+
+			output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.SPCConvectiveOutlooks})
+			if err != nil {
+				t.Fatalf("BuildModule() error = %v", err)
+			}
+			value := moduleValue[SPCConvectiveOutlooksModule](t, output)
+			gotRisk := len(value.RiskDigest) > 0
+			if gotRisk != tt.wantRisk {
+				t.Fatalf("RiskDigest = %#v, want included=%v", value.RiskDigest, tt.wantRisk)
+			}
+		})
+	}
+}
+
+func TestSPCConvectiveOutlooksModuleSkipsNonOverlappingOutlooks(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := testModuleContext()
+	rank := 5
+	outlook := weatherdata.ConvectiveOutlook{
+		ID:               "tomorrow-enhanced",
+		Day:              2,
+		OutlookType:      "categorical",
+		Label:            "ENH",
+		LabelText:        "Enhanced Risk",
+		SeverityRank:     &rank,
+		ValidFrom:        mustParseModuleTime("2026-05-30T07:00:00-05:00"),
+		ValidTo:          mustParseModuleTime("2026-05-31T07:00:00-05:00"),
+		ContainsLocation: true,
+	}
+	ctx.Collected.SPCConvectiveOutlooks = &weatherdata.ConvectiveOutlookRun{
+		AsOf:     ptrModuleTime("2026-05-29T14:00:00Z"),
+		Outlooks: []weatherdata.ConvectiveOutlook{outlook},
+	}
+	ctx.Derived.SPCConvectiveOutlooks = []weatherdata.ConvectiveOutlook{outlook}
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.SPCConvectiveOutlooks})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	value := moduleValue[SPCConvectiveOutlooksModule](t, output)
+	if value.OutlookCount != 0 || len(value.Outlooks) != 0 {
+		t.Fatalf("value = %#v, want non-overlapping outlook omitted", value)
+	}
+	if len(value.RiskDigest) != 0 {
+		t.Fatalf("RiskDigest = %#v, want non-overlapping outlook omitted", value.RiskDigest)
+	}
+}
+
+func TestSPCConvectiveOutlooksModuleBuildsCheckedEmptyStanza(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := testModuleContext()
+	asOf := mustParseModuleTime("2026-05-29T14:00:00Z")
+	ctx.Collected.SPCConvectiveOutlooks = &weatherdata.ConvectiveOutlookRun{
+		LocationID:   "nws-lsx-grid-90-74",
+		LocationName: "St. Louis, MO",
+		AsOf:         &asOf,
+		Outlooks:     []weatherdata.ConvectiveOutlook{},
+	}
+	ctx.Derived.SPCConvectiveOutlooks = []weatherdata.ConvectiveOutlook{}
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.SPCConvectiveOutlooks})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	value := moduleValue[SPCConvectiveOutlooksModule](t, output)
+	if !value.Checked || value.OutlookCount != 0 || len(value.Outlooks) != 0 {
+		t.Fatalf("checked empty value = %#v, want checked source with no retained outlooks", value)
+	}
+	data, err := json.Marshal(output.Value)
+	if err != nil {
+		t.Fatalf("Marshal() error = %v", err)
+	}
+	if strings.Contains(string(data), "outlooks") {
+		t.Fatalf("json = %s, want empty outlook list omitted", string(data))
+	}
+}
+
+func TestSPCConvectiveOutlooksModuleBuildsUncheckedStanzaForMissingSource(t *testing.T) {
+	registry := MustDefaultModuleRegistry()
+	ctx := testModuleContext()
+	ctx.Collected.SPCConvectiveOutlooks = nil
+	ctx.Collected.SourceProvenance = []weatherdata.Source{{
+		Name:    string(module.SPCConvectiveOutlooks),
+		Missing: true,
+	}}
+	ctx.Derived.SPCConvectiveOutlooks = nil
+
+	output, err := registry.BuildModule(ctx, module.ConfigItem{ID: module.SPCConvectiveOutlooks})
+	if err != nil {
+		t.Fatalf("BuildModule() error = %v", err)
+	}
+	value := moduleValue[SPCConvectiveOutlooksModule](t, output)
+	if value.Checked || value.OutlookCount != 0 || value.AsOf != "" || value.IssuedAt != "" {
+		t.Fatalf("missing source value = %#v, want unchecked empty stanza", value)
+	}
+}
+
+func spcRiskDigestTestOutlook(outlookType string, labelText string, rank int, containsLocation bool, validFrom string, validTo string) weatherdata.ConvectiveOutlook {
+	return weatherdata.ConvectiveOutlook{
+		ID:               labelText,
+		Day:              1,
+		OutlookType:      outlookType,
+		LabelText:        labelText,
+		SeverityRank:     &rank,
+		ValidFrom:        mustParseModuleTime(validFrom),
+		ValidTo:          mustParseModuleTime(validTo),
+		ContainsLocation: containsLocation,
+	}
+}

internal/briefing/summary_helpers.go

@@ -7,6 +7,7 @@ import (
 	"strings"
 
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
 )
 
 type OutdoorWindows struct {
@@ -16,8 +17,7 @@ type OutdoorWindows struct {
 
 type OutdoorWindow struct {
 	Daypart string
-	Start   string
-	End     string
+	Period  timeutil.Period
 	Reasons []string
 	Score   float64
 }
@@ -28,6 +28,19 @@ type TomorrowPlanning struct {
 	OvernightChangeWatch         []string
 }
 
+type morningCommuteOvernightPlanning struct {
+	MorningReadiness             []string
+	CommuteSchoolWorkdayConcerns []string
+	OvernightChangeWatch         []string
+}
+
+type TodayPlanning struct {
+	MorningReadiness             []string
+	CommuteSchoolWorkdayConcerns []string
+	OutdoorPlanning              []string
+	LateDayChangeWatch           []string
+}
+
 func buildOutdoorWindows(dayparts []forecast.DaypartSummary) OutdoorWindows {
 	var best *OutdoorWindow
 	var worst *OutdoorWindow
@@ -48,8 +61,60 @@ func buildOutdoorWindows(dayparts []forecast.DaypartSummary) OutdoorWindows {
 	return OutdoorWindows{Best: best, Worst: worst}
 }
 
+func buildTodayPlanning(summary *forecast.DailySummary) *TodayPlanning {
+	planning := &TodayPlanning{}
+	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.")
+	}
+
+	planning.OutdoorPlanning = append(planning.OutdoorPlanning, outdoorPlanningNotes(summary.Dayparts)...)
+	if len(planning.OutdoorPlanning) == 0 {
+		planning.OutdoorPlanning = append(planning.OutdoorPlanning, "No standout outdoor weather constraints are evident in the available forecast.")
+	}
+
+	for _, name := range []string{"afternoon", "evening"} {
+		daypart := daypartNamed(summary.Dayparts, name)
+		if daypart != nil {
+			planning.LateDayChangeWatch = appendUnique(planning.LateDayChangeWatch, lateDayWatchNotes(*daypart)...)
+		}
+	}
+	if len(planning.LateDayChangeWatch) == 0 {
+		planning.LateDayChangeWatch = append(planning.LateDayChangeWatch, "Watch for forecast timing or intensity adjustments later today.")
+	}
+
+	return planning
+}
+
 func buildTomorrowPlanning(summary *forecast.DailySummary) *TomorrowPlanning {
-	planning := &TomorrowPlanning{}
+	base := buildMorningCommuteOvernightPlanning(summary)
+	return &TomorrowPlanning{
+		MorningReadiness:             append([]string(nil), base.MorningReadiness...),
+		CommuteSchoolWorkdayConcerns: append([]string(nil), base.CommuteSchoolWorkdayConcerns...),
+		OvernightChangeWatch:         append([]string(nil), base.OvernightChangeWatch...),
+	}
+}
+
+func buildMorningCommuteOvernightPlanning(summary *forecast.DailySummary) *morningCommuteOvernightPlanning {
+	planning := &morningCommuteOvernightPlanning{}
 	morning := daypartNamed(summary.Dayparts, "morning")
 	if morning != nil {
 		planning.MorningReadiness = append(planning.MorningReadiness, readinessNotes(*morning)...)
@@ -84,6 +149,18 @@ func buildTomorrowPlanning(summary *forecast.DailySummary) *TomorrowPlanning {
 	return planning
 }
 
+func outdoorPlanningNotes(dayparts []forecast.DaypartSummary) []string {
+	windows := buildOutdoorWindows(dayparts)
+	var notes []string
+	if windows.Best != nil {
+		notes = append(notes, fmt.Sprintf("Best outdoor window: %s (%s).", titleWord(windows.Best.Daypart), strings.Join(windows.Best.Reasons, ", ")))
+	}
+	if windows.Worst != nil && (windows.Best == nil || windows.Worst.Daypart != windows.Best.Daypart) {
+		notes = append(notes, fmt.Sprintf("Toughest outdoor window: %s (%s).", titleWord(windows.Worst.Daypart), strings.Join(windows.Worst.Reasons, ", ")))
+	}
+	return appendUnique(nil, notes...)
+}
+
 func readinessNotes(daypart forecast.DaypartSummary) []string {
 	notes := []string{}
 	if daypart.MaxPrecipitationProbability != nil && daypart.MaxPrecipitationProbability.Value >= 50 {
@@ -104,6 +181,27 @@ func readinessNotes(daypart forecast.DaypartSummary) []string {
 	return appendUnique(nil, notes...)
 }
 
+func lateDayWatchNotes(daypart forecast.DaypartSummary) []string {
+	notes := []string{}
+	prefix := titleWord(daypart.Name)
+	if prefix == "" {
+		prefix = "Late-day"
+	}
+	if daypart.MaxPrecipitationProbability != nil && daypart.MaxPrecipitationProbability.Value >= 30 {
+		notes = append(notes, fmt.Sprintf("%s precipitation timing may shift; current peak is near %.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 could affect late-day travel.")
+	}
+	if len(daypart.AlertOverlaps) > 0 {
+		notes = append(notes, prefix+" alert timing could affect late-day plans.")
+	}
+	return appendUnique(nil, notes...)
+}
+
 func concernNotes(daypart forecast.DaypartSummary) []string {
 	notes := []string{}
 	prefix := titleWord(daypart.Name)
@@ -190,8 +288,7 @@ func scoreOutdoorWindow(daypart forecast.DaypartSummary) OutdoorWindow {
 	}
 	return OutdoorWindow{
 		Daypart: daypart.Name,
-		Start:   daypart.Period.Start.Format("15:04"),
-		End:     daypart.Period.End.Format("15:04"),
+		Period:  daypart.Period,
 		Reasons: dedupe(reasons),
 		Score:   math.Round(score*10) / 10,
 	}

internal/briefing/today_planning_module.go

@@ -0,0 +1,26 @@
+package briefing
+
+import "gitea.maximumdirect.net/eric/weatherreporter/internal/module"
+
+type TodayPlanningModule struct {
+	MorningReadiness             []string `json:"morning_readiness,omitempty"`
+	CommuteSchoolWorkdayConcerns []string `json:"commute_school_workday_concerns,omitempty"`
+	OutdoorPlanning              []string `json:"outdoor_planning,omitempty"`
+	LateDayChangeWatch           []string `json:"late_day_change_watch,omitempty"`
+}
+
+func buildTodayPlanningModule(ctx ModuleContext, _ any) (*module.Output, error) {
+	summary := ctx.Derived.FirstDailySummary()
+	if summary == nil {
+		return &module.Output{ID: module.TodayPlanning, StanzaName: "today_planning", Value: TodayPlanningModule{}}, nil
+	}
+	planning := buildTodayPlanning(summary)
+	value := TodayPlanningModule{}
+	if planning != nil {
+		value.MorningReadiness = append([]string(nil), planning.MorningReadiness...)
+		value.CommuteSchoolWorkdayConcerns = append([]string(nil), planning.CommuteSchoolWorkdayConcerns...)
+		value.OutdoorPlanning = append([]string(nil), planning.OutdoorPlanning...)
+		value.LateDayChangeWatch = append([]string(nil), planning.LateDayChangeWatch...)
+	}
+	return &module.Output{ID: module.TodayPlanning, StanzaName: "today_planning", Value: value}, nil
+}

internal/briefing/weather_story_module.go

@@ -4,20 +4,21 @@ import (
 	"time"
 
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/module"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
 )
 
 type WeatherStoryModule struct {
-	Available   bool       `json:"available"`
-	OfficeID    string     `json:"office_id,omitempty"`
-	StartTime   time.Time  `json:"start_time"`
-	EndTime     time.Time  `json:"end_time"`
-	UpdatedAt   *time.Time `json:"updated_at,omitempty"`
-	Title       string     `json:"title,omitempty"`
-	Description string     `json:"description,omitempty"`
-	AltText     string     `json:"alt_text,omitempty"`
-	Priority    bool       `json:"priority"`
-	Order       int        `json:"order"`
-	DownloadURL string     `json:"download_url,omitempty"`
+	Available    bool       `json:"available"`
+	OfficeID     string     `json:"office_id,omitempty"`
+	PeriodBegins string     `json:"period_begins,omitempty"`
+	PeriodEnds   string     `json:"period_ends,omitempty"`
+	UpdatedAt    *time.Time `json:"updated_at,omitempty"`
+	Title        string     `json:"title,omitempty"`
+	Description  string     `json:"description,omitempty"`
+	AltText      string     `json:"alt_text,omitempty"`
+	Priority     bool       `json:"priority"`
+	Order        int        `json:"order"`
+	DownloadURL  string     `json:"download_url,omitempty"`
 }
 
 func buildWeatherStoryModule(ctx ModuleContext, _ any) (*module.Output, error) {
@@ -25,18 +26,19 @@ func buildWeatherStoryModule(ctx ModuleContext, _ any) (*module.Output, error) {
 	if story == nil {
 		return nil, nil
 	}
+	period := timeutil.Period{Start: story.StartTime, End: story.EndTime}
 	value := WeatherStoryModule{
-		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,
+		Available:    true,
+		OfficeID:     story.OfficeID,
+		PeriodBegins: friendlyPeriodBeginsLabel(period, ctx.Timezone),
+		PeriodEnds:   friendlyPeriodEndsLabel(period, ctx.Timezone),
+		UpdatedAt:    copyTime(story.UpdatedAt),
+		Title:        story.Title,
+		Description:  story.Description,
+		AltText:      story.AltText,
+		Priority:     story.Priority,
+		Order:        story.Order,
+		DownloadURL:  story.DownloadURL,
 	}
 	return &module.Output{ID: module.WeatherStory, StanzaName: "weather_story", Value: value}, nil
 }

internal/changes/daily.go

@@ -84,7 +84,8 @@ type dailySummaryStanza struct {
 
 type daypartSummaryStanza struct {
 	Date           string `json:"date,omitempty"`
-	Period         string `json:"period,omitempty"`
+	PeriodBegins   string `json:"period_begins,omitempty"`
+	PeriodEnds     string `json:"period_ends,omitempty"`
 	TempRangeF     string `json:"temp_range_f,omitempty"`
 	MaxPopPercent  *int   `json:"max_pop_percent,omitempty"`
 	MaxPopTime     string `json:"max_pop_time,omitempty"`

internal/changes/daily_test.go

@@ -96,7 +96,13 @@ func dailySnapshot(t *testing.T, low int, high int, precip int, precipTime strin
 			DailyPrecipitationProbability: &precip,
 		}},
 		module.Output{ID: module.DerivedDaypartSummaries, StanzaName: "derived_daypart_summaries", Value: map[string]daypartSummaryStanza{
-			"morning": {Date: "2026-05-29", Period: "2026-05-29 at 6:00 AM to 2026-05-29 at 10:00 AM", TempRangeF: "60-70", Snow: snow},
+			"morning": {
+				Date:         "2026-05-29",
+				PeriodBegins: "2026-05-29 at 6:00 AM",
+				PeriodEnds:   "2026-05-29 at 10:00 AM",
+				TempRangeF:   "60-70",
+				Snow:         snow,
+			},
 		}},
 		module.Output{ID: module.PrecipTiming, StanzaName: "precip_timing", Value: precipTimingStanza{MaxPopPercent: &precip, MaxPopTime: precipTime}},
 		module.Output{ID: module.AlertDigest, StanzaName: "alert_digest", Value: alertDigestStanza{Relevant: relevant}},

internal/changes/three_day_test.go

@@ -32,7 +32,8 @@ func outlookSnapshot(t *testing.T, date string, tempRange string, precip int, pr
 	return snapshot(t, module.Output{ID: module.DerivedDaypartSummaries, StanzaName: "derived_daypart_summaries", Value: map[string]daypartSummaryStanza{
 		date + "_morning": {
 			Date:          date,
-			Period:        date + " at 6:00 AM to " + date + " at 10:00 AM",
+			PeriodBegins:  date + " at 6:00 AM",
+			PeriodEnds:    date + " at 10:00 AM",
 			TempRangeF:    tempRange,
 			MaxPopPercent: &precip,
 			MaxPopTime:    precipTime,

internal/cli/output.go

@@ -0,0 +1,75 @@
+package cli
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/app"
+)
+
+type outputOptions struct {
+	Quiet bool
+}
+
+func writeActionResult(stdout, stderr io.Writer, value any, opts outputOptions, writeStatus func(io.Writer)) error {
+	if opts.Quiet {
+		return nil
+	}
+	if writeStatus != nil && stderr != nil {
+		writeStatus(stderr)
+	}
+	return writeJSON(stdout, value)
+}
+
+func writeJSON(stdout io.Writer, value any) error {
+	encoder := json.NewEncoder(stdout)
+	encoder.SetIndent("", "  ")
+	return encoder.Encode(value)
+}
+
+func writeBatchStatus(stderr io.Writer, result *app.BatchResult) {
+	if stderr == nil || result == nil {
+		return
+	}
+	for _, item := range result.Reports {
+		notificationFields := ""
+		if item.NotificationStatus != "" {
+			notificationFields += fmt.Sprintf(" notificationStatus=%q", item.NotificationStatus)
+		}
+		if item.NotificationRunID != "" {
+			notificationFields += fmt.Sprintf(" notificationRunId=%q", item.NotificationRunID)
+		}
+		if item.NotificationError != "" {
+			notificationFields += fmt.Sprintf(" notificationError=%q", item.NotificationError)
+		}
+		if item.Status == "failed" {
+			_, _ = fmt.Fprintf(stderr, "report=%s status=failed error=%q%s\n", item.ReportID, item.Error, notificationFields)
+			continue
+		}
+		_, _ = fmt.Fprintf(stderr, "report=%s status=succeeded output=%q%s\n", item.ReportID, item.OutputPath, notificationFields)
+	}
+	if result.Notification != nil {
+		_, _ = fmt.Fprintf(stderr, "batchNotification status=%q", result.Notification.Status)
+		if result.Notification.Reason != "" {
+			_, _ = fmt.Fprintf(stderr, " reason=%q", result.Notification.Reason)
+		}
+		if result.Notification.RunID != "" {
+			_, _ = fmt.Fprintf(stderr, " runId=%q", result.Notification.RunID)
+		}
+		if result.Notification.PipelineID != "" {
+			_, _ = fmt.Fprintf(stderr, " pipelineId=%q", result.Notification.PipelineID)
+		}
+		if result.Notification.BundleID != "" {
+			_, _ = fmt.Fprintf(stderr, " bundleId=%q", result.Notification.BundleID)
+		}
+		if result.Notification.Path != "" {
+			_, _ = fmt.Fprintf(stderr, " path=%q", result.Notification.Path)
+		}
+		if result.Notification.Error != "" {
+			_, _ = fmt.Fprintf(stderr, " error=%q", result.Notification.Error)
+		}
+		_, _ = fmt.Fprintln(stderr)
+	}
+	_, _ = fmt.Fprintf(stderr, "batch=%s total=%d succeeded=%d failed=%d\n", result.Batch, result.Total, result.Succeeded, result.Failed)
+}

internal/cli/output_test.go

@@ -0,0 +1,59 @@
+package cli
+
+import (
+	"bytes"
+	"io"
+	"strings"
+	"testing"
+)
+
+func TestWriteActionResultWritesStatusBeforeJSON(t *testing.T) {
+	var output bytes.Buffer
+
+	err := writeActionResult(&output, &output, map[string]string{"status": "succeeded"}, outputOptions{}, func(w io.Writer) {
+		_, _ = w.Write([]byte("status line\n"))
+	})
+	if err != nil {
+		t.Fatalf("writeActionResult() error = %v", err)
+	}
+	if !strings.HasPrefix(output.String(), "status line\n") {
+		t.Fatalf("output = %q, want status before JSON", output.String())
+	}
+	if !strings.Contains(output.String(), `"status": "succeeded"`) {
+		t.Fatalf("output missing JSON result:\n%s", output.String())
+	}
+}
+
+func TestWriteActionResultQuietSuppressesOutput(t *testing.T) {
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+
+	err := writeActionResult(&stdout, &stderr, map[string]string{"status": "succeeded"}, outputOptions{Quiet: true}, func(w io.Writer) {
+		_, _ = w.Write([]byte("status line\n"))
+	})
+	if err != nil {
+		t.Fatalf("writeActionResult() error = %v", err)
+	}
+	if stdout.Len() != 0 || stderr.Len() != 0 {
+		t.Fatalf("stdout/stderr = %q/%q, want no output", stdout.String(), stderr.String())
+	}
+}
+
+func TestWriteActionResultToleratesNilStderr(t *testing.T) {
+	var stdout bytes.Buffer
+	statusCalled := false
+
+	err := writeActionResult(&stdout, nil, map[string]string{"status": "succeeded"}, outputOptions{}, func(w io.Writer) {
+		statusCalled = true
+		_, _ = w.Write([]byte("status line\n"))
+	})
+	if err != nil {
+		t.Fatalf("writeActionResult() error = %v", err)
+	}
+	if statusCalled {
+		t.Fatal("status writer was called with nil stderr")
+	}
+	if !strings.Contains(stdout.String(), `"status": "succeeded"`) {
+		t.Fatalf("stdout missing JSON result:\n%s", stdout.String())
+	}
+}

internal/cli/result.go

@@ -0,0 +1,162 @@
+package cli
+
+import (
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/app"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+const (
+	commandGenerate = "generate"
+	commandRun      = "run"
+
+	summaryStatusSucceeded = "succeeded"
+	summaryStatusFailed    = "failed"
+)
+
+type generateSummary struct {
+	Command                 string                       `json:"command"`
+	ReportID                report.ID                    `json:"reportId"`
+	ReportName              string                       `json:"reportName"`
+	PromptID                string                       `json:"promptId"`
+	RunID                   string                       `json:"runId"`
+	Status                  string                       `json:"status"`
+	GeneratedAt             time.Time                    `json:"generatedAt"`
+	ValidPeriod             timeutil.Period              `json:"validPeriod"`
+	ReportPath              string                       `json:"reportPath,omitempty"`
+	OutputPath              string                       `json:"outputPath,omitempty"`
+	MetadataPath            string                       `json:"metadataPath,omitempty"`
+	DataPackagePath         string                       `json:"dataPackagePath,omitempty"`
+	PreflightPath           string                       `json:"preflightPath,omitempty"`
+	GeneratedTextRawPath    string                       `json:"generatedTextRawPath,omitempty"`
+	GeneratedTextResultPath string                       `json:"generatedTextResultPath,omitempty"`
+	GeneratedTextPath       string                       `json:"generatedTextPath,omitempty"`
+	RenderContextPath       string                       `json:"renderContextPath,omitempty"`
+	NotificationPath        string                       `json:"notificationPath,omitempty"`
+	Notification            *generateNotificationSummary `json:"notification,omitempty"`
+	Error                   string                       `json:"error,omitempty"`
+}
+
+type generateNotificationSummary struct {
+	Status         string     `json:"status,omitempty"`
+	UploadStatus   string     `json:"uploadStatus,omitempty"`
+	StatusError    string     `json:"statusError,omitempty"`
+	RunID          string     `json:"runId,omitempty"`
+	PipelineID     string     `json:"pipelineId,omitempty"`
+	BundleID       string     `json:"bundleId,omitempty"`
+	IdempotencyKey string     `json:"idempotencyKey,omitempty"`
+	AcceptedAt     *time.Time `json:"acceptedAt,omitempty"`
+	StartedAt      *time.Time `json:"startedAt,omitempty"`
+	FinishedAt     *time.Time `json:"finishedAt,omitempty"`
+	Error          string     `json:"error,omitempty"`
+}
+
+type batchSummary struct {
+	Command      string                       `json:"command"`
+	Batch        app.BatchKind                `json:"batch"`
+	Status       string                       `json:"status"`
+	StartedAt    time.Time                    `json:"startedAt"`
+	FinishedAt   time.Time                    `json:"finishedAt"`
+	Total        int                          `json:"total"`
+	Succeeded    int                          `json:"succeeded"`
+	Failed       int                          `json:"failed"`
+	Notification *app.BatchNotificationResult `json:"notification,omitempty"`
+	Reports      []app.BatchReportResult      `json:"reports"`
+	Error        string                       `json:"error,omitempty"`
+}
+
+func newGenerateSummary(result *app.ReportResult, err error) generateSummary {
+	summary := generateSummary{Command: commandGenerate}
+	if result == nil {
+		return summary
+	}
+
+	metadata := result.Metadata
+	summary.ReportID = metadata.ReportID
+	summary.ReportName = reportName(metadata.ReportID)
+	summary.PromptID = metadata.PromptID
+	summary.RunID = metadata.RunID
+	summary.Status = summaryStatusSucceeded
+	summary.GeneratedAt = metadata.GeneratedAt
+	summary.ValidPeriod = metadata.ValidPeriod
+	summary.ReportPath = result.ReportPath
+	summary.OutputPath = result.OutputPath
+	summary.MetadataPath = result.MetadataPath
+	summary.DataPackagePath = result.DataPackagePath
+	summary.PreflightPath = result.PreflightPath
+	summary.GeneratedTextRawPath = result.GeneratedTextRawPath
+	summary.GeneratedTextResultPath = result.GeneratedTextResultPath
+	summary.GeneratedTextPath = result.GeneratedTextPath
+	summary.RenderContextPath = result.RenderContextPath
+	summary.NotificationPath = result.NotificationPath
+	summary.Notification = newGenerateNotificationSummary(result.Notification)
+	if err != nil {
+		summary.Status = summaryStatusFailed
+		summary.Error = err.Error()
+	}
+	return summary
+}
+
+func newGenerateNotificationSummary(result *app.NotificationResult) *generateNotificationSummary {
+	if result == nil {
+		return nil
+	}
+	summary := &generateNotificationSummary{
+		Status:         result.Status,
+		UploadStatus:   result.UploadStatus,
+		StatusError:    result.StatusError,
+		RunID:          result.RunID,
+		PipelineID:     result.PipelineID,
+		BundleID:       result.BundleID,
+		IdempotencyKey: result.IdempotencyKey,
+		StartedAt:      result.StartedAt,
+		FinishedAt:     result.FinishedAt,
+		Error:          result.Error,
+	}
+	if !result.AcceptedAt.IsZero() {
+		acceptedAt := result.AcceptedAt
+		summary.AcceptedAt = &acceptedAt
+	}
+	return summary
+}
+
+func newBatchSummary(result *app.BatchResult) batchSummary {
+	summary := batchSummary{Command: commandRun}
+	if result == nil {
+		return summary
+	}
+
+	summary.Batch = result.Batch
+	summary.Status = batchSummaryStatus(result)
+	summary.StartedAt = result.StartedAt
+	summary.FinishedAt = result.FinishedAt
+	summary.Total = result.Total
+	summary.Succeeded = result.Succeeded
+	summary.Failed = result.Failed
+	summary.Notification = result.Notification
+	summary.Reports = append([]app.BatchReportResult(nil), result.Reports...)
+	if summary.Status == summaryStatusFailed {
+		summary.Error = app.BatchError{Result: result}.Error()
+	}
+	return summary
+}
+
+func batchSummaryStatus(result *app.BatchResult) string {
+	if result == nil {
+		return ""
+	}
+	if result.Failed > 0 || (result.Notification != nil && result.Notification.Status == summaryStatusFailed) {
+		return summaryStatusFailed
+	}
+	return summaryStatusSucceeded
+}
+
+func reportName(id report.ID) string {
+	definition, err := report.DefaultRegistry().Lookup(id)
+	if err != nil {
+		return string(id)
+	}
+	return definition.Name
+}

internal/cli/result_test.go

@@ -0,0 +1,231 @@
+package cli
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/app"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/state"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/timeutil"
+)
+
+func TestNewGenerateSummaryForGeneratedTextReport(t *testing.T) {
+	generatedAt := time.Date(2026, 5, 29, 13, 30, 0, 0, time.UTC)
+	acceptedAt := generatedAt.Add(time.Minute)
+	startedAt := acceptedAt.Add(time.Minute)
+	finishedAt := startedAt.Add(time.Minute)
+	result := &app.ReportResult{
+		DataPackagePath:         "/runs/hourly/data_package.yaml",
+		PreflightPath:           "/runs/hourly/preflight.json",
+		ReportPath:              "/runs/hourly/report.md",
+		OutputPath:              "/copies/hourly.md",
+		MetadataPath:            "/runs/hourly/metadata.json",
+		GeneratedTextRawPath:    "/runs/hourly/generated_text_raw.json",
+		GeneratedTextResultPath: "/runs/hourly/generated_text_result.json",
+		GeneratedTextPath:       "/runs/hourly/generated_text.json",
+		RenderContextPath:       "/runs/hourly/render_context.json",
+		NotificationPath:        "/runs/hourly/notification.json",
+		Metadata: state.Metadata{
+			ReportID:    report.Hourly,
+			PromptID:    "weather.hourly_generated_text",
+			RunID:       "20260529T133000Z_hourly",
+			GeneratedAt: generatedAt,
+			ValidPeriod: testSummaryPeriod(generatedAt),
+		},
+		Notification: &app.NotificationResult{
+			Status:         "succeeded",
+			UploadStatus:   "accepted",
+			RunID:          "distributor-run",
+			PipelineID:     "weatherreporter.hourly",
+			BundleID:       "weatherreporter.home.hourly",
+			IdempotencyKey: "weatherreporter.home.hourly.20260529T133000Z_hourly",
+			AcceptedAt:     acceptedAt,
+			StartedAt:      &startedAt,
+			FinishedAt:     &finishedAt,
+			Report:         []byte(`{"actions":[{"action":"replace_older"}]}`),
+		},
+	}
+
+	summary := newGenerateSummary(result, nil)
+
+	if summary.Command != "generate" || summary.Status != "succeeded" {
+		t.Fatalf("summary command/status = %q/%q, want generate/succeeded", summary.Command, summary.Status)
+	}
+	if summary.ReportID != report.Hourly || summary.ReportName != "Hourly Report" || summary.PromptID != "weather.hourly_generated_text" || summary.RunID != "20260529T133000Z_hourly" {
+		t.Fatalf("summary identity = %#v, want hourly report identity", summary)
+	}
+	if summary.GeneratedTextRawPath == "" || summary.GeneratedTextResultPath == "" || summary.GeneratedTextPath == "" || summary.RenderContextPath == "" {
+		t.Fatalf("generated-text paths = %#v, want generated-text artifact paths", summary)
+	}
+	if summary.Notification == nil || summary.Notification.RunID != "distributor-run" || summary.Notification.AcceptedAt == nil || !summary.Notification.AcceptedAt.Equal(acceptedAt) {
+		t.Fatalf("notification = %#v, want summarized distributor result", summary.Notification)
+	}
+	data, err := json.Marshal(summary)
+	if err != nil {
+		t.Fatalf("Marshal() error = %v", err)
+	}
+	if strings.Contains(string(data), "replace_older") || strings.Contains(string(data), "actions") {
+		t.Fatalf("summary JSON includes raw distributor report payload:\n%s", string(data))
+	}
+}
+
+func TestNewGenerateSummaryForMarkdownReportOmitsGeneratedTextAndNotification(t *testing.T) {
+	generatedAt := time.Date(2026, 5, 29, 13, 30, 0, 0, time.UTC)
+	result := &app.ReportResult{
+		DataPackagePath: "/runs/three-day/data_package.yaml",
+		PreflightPath:   "/runs/three-day/preflight.json",
+		ReportPath:      "/runs/three-day/report.md",
+		OutputPath:      "/copies/three-day.md",
+		MetadataPath:    "/runs/three-day/metadata.json",
+		Metadata: state.Metadata{
+			ReportID:    report.ThreeDay,
+			PromptID:    "weather.three_day_outlook",
+			RunID:       "20260529T133000Z_three_day",
+			GeneratedAt: generatedAt,
+			ValidPeriod: testSummaryPeriod(generatedAt),
+		},
+	}
+
+	summary := newGenerateSummary(result, nil)
+
+	if summary.ReportID != report.ThreeDay || summary.ReportName != "3-Day Outlook" || summary.Status != "succeeded" {
+		t.Fatalf("summary = %#v, want successful 3-day summary", summary)
+	}
+	if summary.Notification != nil || summary.NotificationPath != "" {
+		t.Fatalf("notification summary/path = %#v/%q, want omitted", summary.Notification, summary.NotificationPath)
+	}
+	data, err := json.Marshal(summary)
+	if err != nil {
+		t.Fatalf("Marshal() error = %v", err)
+	}
+	for _, omitted := range []string{"generatedTextRawPath", "generatedTextResultPath", "generatedTextPath", "renderContextPath", "notification"} {
+		if strings.Contains(string(data), omitted) {
+			t.Fatalf("summary JSON contains %q, want omitted:\n%s", omitted, string(data))
+		}
+	}
+}
+
+func TestNewGenerateSummaryForNotificationFailure(t *testing.T) {
+	generatedAt := time.Date(2026, 5, 29, 13, 30, 0, 0, time.UTC)
+	result := &app.ReportResult{
+		DataPackagePath:  "/runs/hourly/data_package.yaml",
+		PreflightPath:    "/runs/hourly/preflight.json",
+		ReportPath:       "/runs/hourly/report.md",
+		OutputPath:       "/copies/hourly.md",
+		MetadataPath:     "/runs/hourly/metadata.json",
+		NotificationPath: "/runs/hourly/notification.json",
+		Metadata: state.Metadata{
+			ReportID:    report.Hourly,
+			PromptID:    "weather.hourly_generated_text",
+			RunID:       "20260529T133000Z_hourly",
+			GeneratedAt: generatedAt,
+			ValidPeriod: testSummaryPeriod(generatedAt),
+		},
+	}
+	err := errors.New(`notify report "hourly" run "20260529T133000Z_hourly": upload rejected`)
+
+	summary := newGenerateSummary(result, err)
+
+	if summary.Status != "failed" || summary.Error != err.Error() {
+		t.Fatalf("status/error = %q/%q, want failed notification error", summary.Status, summary.Error)
+	}
+	if summary.NotificationPath != "/runs/hourly/notification.json" || summary.ReportPath == "" || summary.MetadataPath == "" {
+		t.Fatalf("artifact paths = report %q metadata %q notification %q, want inspectable paths", summary.ReportPath, summary.MetadataPath, summary.NotificationPath)
+	}
+}
+
+func TestNewBatchSummaryStatusDerivation(t *testing.T) {
+	startedAt := time.Date(2026, 5, 29, 12, 0, 0, 0, time.UTC)
+	finishedAt := startedAt.Add(2 * time.Minute)
+	tests := []struct {
+		name       string
+		result     *app.BatchResult
+		wantStatus string
+		wantError  string
+	}{
+		{
+			name: "success",
+			result: &app.BatchResult{
+				Batch:      app.BatchMorning,
+				StartedAt:  startedAt,
+				FinishedAt: finishedAt,
+				Total:      1,
+				Succeeded:  1,
+				Reports:    []app.BatchReportResult{{ReportID: report.Today, Status: "succeeded"}},
+			},
+			wantStatus: "succeeded",
+		},
+		{
+			name: "report failure",
+			result: &app.BatchResult{
+				Batch:     app.BatchMorning,
+				Total:     2,
+				Succeeded: 1,
+				Failed:    1,
+				Reports: []app.BatchReportResult{
+					{ReportID: report.Today, Status: "succeeded"},
+					{ReportID: report.Tomorrow, Status: "failed", Error: "render failed"},
+				},
+			},
+			wantStatus: "failed",
+			wantError:  "batch morning failed: 1 of 2 reports failed",
+		},
+		{
+			name: "skipped notification",
+			result: &app.BatchResult{
+				Batch:     app.BatchEvening,
+				Total:     2,
+				Succeeded: 1,
+				Failed:    1,
+				Reports:   []app.BatchReportResult{{ReportID: report.Tomorrow, Status: "failed"}},
+				Notification: &app.BatchNotificationResult{
+					Status: "skipped",
+					Reason: "one or more reports failed",
+				},
+			},
+			wantStatus: "failed",
+			wantError:  "batch evening failed: 1 of 2 reports failed",
+		},
+		{
+			name: "failed notification",
+			result: &app.BatchResult{
+				Batch:     app.BatchEvening,
+				Total:     1,
+				Succeeded: 1,
+				Reports:   []app.BatchReportResult{{ReportID: report.Tomorrow, Status: "succeeded"}},
+				Notification: &app.BatchNotificationResult{
+					Status: "failed",
+					Error:  "notify batch evening: upload rejected",
+				},
+			},
+			wantStatus: "failed",
+			wantError:  "batch evening notification failed: notify batch evening: upload rejected",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			summary := newBatchSummary(tt.result)
+			if summary.Command != "run" || summary.Status != tt.wantStatus {
+				t.Fatalf("command/status = %q/%q, want run/%s", summary.Command, summary.Status, tt.wantStatus)
+			}
+			if summary.Error != tt.wantError {
+				t.Fatalf("error = %q, want %q", summary.Error, tt.wantError)
+			}
+			if len(summary.Reports) != len(tt.result.Reports) {
+				t.Fatalf("reports = %#v, want copied report list", summary.Reports)
+			}
+		})
+	}
+}
+
+func testSummaryPeriod(start time.Time) timeutil.Period {
+	return timeutil.Period{
+		Start: start,
+		End:   start.Add(6 * time.Hour),
+	}
+}

internal/cli/root.go

@@ -2,7 +2,6 @@ package cli
 
 import (
 	"context"
-	"encoding/json"
 	"flag"
 	"fmt"
 	"io"
@@ -17,13 +16,15 @@ const helpText = `weatherreporter prepares weather reports from normalized forec
 
 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 generate daily --date YYYY-MM-DD [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
+  weatherreporter generate today [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--date YYYY-MM-DD] [--quiet]
+  weatherreporter generate tomorrow [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
+  weatherreporter generate hourly [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
+  weatherreporter generate three-day [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
+  weatherreporter generate weekend [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
+  weatherreporter generate storm [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet] --start TIME --end TIME
+  weatherreporter run morning [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] [--quiet]
+  weatherreporter run evening [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] [--quiet]
   weatherreporter inspect reports [--config PATH] [--limit N]
   weatherreporter inspect metadata [--config PATH] RUN_ID
   weatherreporter inspect modules [--config PATH] RUN_ID
@@ -36,8 +37,9 @@ Options:
   --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 PATH       Write an extra Markdown report copy where supported by the generate command.
   --out-dir PATH   Write extra Markdown report copies for run commands.
+  --quiet          Suppress successful generate and run output.
 `
 
 type Runner struct {
@@ -49,7 +51,6 @@ func Run(ctx context.Context, args []string, stdout io.Writer, stderr io.Writer)
 }
 
 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{}
 	}
@@ -60,23 +61,32 @@ func (r Runner) Run(ctx context.Context, args []string, stdout io.Writer, stderr
 
 	switch args[0] {
 	case "generate":
-		req, err := r.resolveGenerate(args[1:])
+		req, opts, err := r.resolveGenerateAction(args[1:])
 		if err != nil {
 			return err
 		}
-		return app.Generate(ctx, req)
+		result, err := app.GenerateDetailed(ctx, req)
+		if result != nil {
+			summary := newGenerateSummary(result, err)
+			if encodeErr := writeActionResult(stdout, stderr, summary, outputOptions{Quiet: opts.Quiet}, nil); encodeErr != nil {
+				return encodeErr
+			}
+		}
+		return err
 	case "run":
-		req, err := r.resolveRun(args[1:])
+		req, opts, err := r.resolveRunAction(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 {
+			summary := newBatchSummary(result)
+			if encodeErr := writeActionResult(stdout, stderr, summary, outputOptions{Quiet: opts.Quiet}, func(w io.Writer) {
+				writeBatchStatus(w, result)
+			}); encodeErr != nil {
 				return encodeErr
 			}
-			if result.Failed > 0 {
+			if summary.Status == summaryStatusFailed {
 				return app.BatchError{Result: result}
 			}
 		}
@@ -94,6 +104,7 @@ type commonOptions struct {
 	Timezone   string
 	Output     string
 	OutputDir  string
+	Quiet      bool
 }
 
 type generateOptions struct {
@@ -179,20 +190,25 @@ func runInspectRunCommand(ctx context.Context, stdout io.Writer, command inspect
 }
 
 func (r Runner) resolveGenerate(args []string) (app.GenerateRequest, error) {
+	req, _, err := r.resolveGenerateAction(args)
+	return req, err
+}
+
+func (r Runner) resolveGenerateAction(args []string) (app.GenerateRequest, commonOptions, error) {
 	if r.Clock == nil {
 		r.Clock = timeutil.SystemClock{}
 	}
 	if len(args) == 0 {
-		return app.GenerateRequest{}, fmt.Errorf("generate requires a report name")
+		return app.GenerateRequest{}, commonOptions{}, 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])
+	if _, err := report.IDForCommandName(args[0]); err != nil {
+		return app.GenerateRequest{}, commonOptions{}, fmt.Errorf("unknown generate report %q", args[0])
 	}
+	reportKind := app.ReportKind(args[0])
 
 	opts, err := parseGenerateFlags(reportKind, args[1:])
 	if err != nil {
-		return app.GenerateRequest{}, err
+		return app.GenerateRequest{}, commonOptions{}, err
 	}
 	cfg, err := config.Load(config.LoadOptions{
 		Path:     opts.ConfigPath,
@@ -200,11 +216,11 @@ func (r Runner) resolveGenerate(args []string) (app.GenerateRequest, error) {
 		Timezone: opts.Timezone,
 	})
 	if err != nil {
-		return app.GenerateRequest{}, err
+		return app.GenerateRequest{}, commonOptions{}, err
 	}
 	location, err := timeutil.LoadLocation(cfg.WeatherAPI.Timezone)
 	if err != nil {
-		return app.GenerateRequest{}, err
+		return app.GenerateRequest{}, commonOptions{}, err
 	}
 
 	req := app.GenerateRequest{
@@ -216,46 +232,59 @@ func (r Runner) resolveGenerate(args []string) (app.GenerateRequest, error) {
 
 	switch reportKind {
 	case app.ReportDaily:
+		if opts.Date == "" {
+			return app.GenerateRequest{}, commonOptions{}, fmt.Errorf("generate daily requires --date YYYY-MM-DD")
+		}
+		req.Date, err = timeutil.ParseLocalDate(opts.Date, location)
+		if err != nil {
+			return app.GenerateRequest{}, commonOptions{}, err
+		}
+	case app.ReportToday:
 		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
+				return app.GenerateRequest{}, commonOptions{}, err
 			}
 		}
 	case app.ReportStorm:
 		if opts.Start == "" {
-			return app.GenerateRequest{}, fmt.Errorf("generate storm requires --start")
+			return app.GenerateRequest{}, commonOptions{}, fmt.Errorf("generate storm requires --start")
 		}
 		if opts.End == "" {
-			return app.GenerateRequest{}, fmt.Errorf("generate storm requires --end")
+			return app.GenerateRequest{}, commonOptions{}, fmt.Errorf("generate storm requires --end")
 		}
 		period, err := report.ParseStormPeriod(opts.Start, opts.End, location)
 		if err != nil {
-			return app.GenerateRequest{}, err
+			return app.GenerateRequest{}, commonOptions{}, err
 		}
 		req.StormStart = period.Start
 		req.StormEnd = period.End
 	}
 
-	return req, nil
+	return req, opts.commonOptions, nil
 }
 
 func (r Runner) resolveRun(args []string) (app.BatchRequest, error) {
+	req, _, err := r.resolveRunAction(args)
+	return req, err
+}
+
+func (r Runner) resolveRunAction(args []string) (app.BatchRequest, commonOptions, error) {
 	if r.Clock == nil {
 		r.Clock = timeutil.SystemClock{}
 	}
 	if len(args) == 0 {
-		return app.BatchRequest{}, fmt.Errorf("run requires a batch name")
+		return app.BatchRequest{}, commonOptions{}, 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])
+	if _, err := report.BatchForCommandName(args[0]); err != nil {
+		return app.BatchRequest{}, commonOptions{}, fmt.Errorf("unknown run batch %q", args[0])
 	}
+	batch := app.BatchKind(args[0])
 	opts, err := parseRunFlags(args[1:])
 	if err != nil {
-		return app.BatchRequest{}, err
+		return app.BatchRequest{}, commonOptions{}, err
 	}
 	cfg, err := config.Load(config.LoadOptions{
 		Path:     opts.ConfigPath,
@@ -263,9 +292,9 @@ func (r Runner) resolveRun(args []string) (app.BatchRequest, error) {
 		Timezone: opts.Timezone,
 	})
 	if err != nil {
-		return app.BatchRequest{}, err
+		return app.BatchRequest{}, commonOptions{}, err
 	}
-	return app.BatchRequest{Config: cfg, Batch: batch, Now: r.Clock.Now(), OutputDir: opts.OutputDir}, nil
+	return app.BatchRequest{Config: cfg, Batch: batch, Now: r.Clock.Now(), OutputDir: opts.OutputDir}, opts, nil
 }
 
 func resolveRun(args []string) (app.BatchRequest, error) {
@@ -277,7 +306,8 @@ func parseGenerateFlags(report app.ReportKind, args []string) (generateOptions,
 	fs.SetOutput(io.Discard)
 	opts := generateOptions{}
 	addCommonFlags(fs, &opts.commonOptions, true)
-	if report == app.ReportDaily {
+	fs.BoolVar(&opts.Quiet, "quiet", false, "suppress successful action output")
+	if report == app.ReportDaily || report == app.ReportToday {
 		fs.StringVar(&opts.Date, "date", "", "report date in YYYY-MM-DD")
 	}
 	if report == app.ReportStorm {
@@ -299,6 +329,7 @@ func parseRunFlags(args []string) (commonOptions, error) {
 	opts := commonOptions{}
 	addCommonFlags(fs, &opts, false)
 	fs.StringVar(&opts.OutputDir, "out-dir", "", "extra Markdown report copy directory")
+	fs.BoolVar(&opts.Quiet, "quiet", false, "suppress successful action output")
 	if err := fs.Parse(args); err != nil {
 		return commonOptions{}, err
 	}
@@ -341,36 +372,6 @@ func parseInspectRunFlags(command string, args []string) (inspectOptions, error)
 	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 {
-		notificationFields := ""
-		if item.NotificationStatus != "" {
-			notificationFields += fmt.Sprintf(" notificationStatus=%q", item.NotificationStatus)
-		}
-		if item.NotificationRunID != "" {
-			notificationFields += fmt.Sprintf(" notificationRunId=%q", item.NotificationRunID)
-		}
-		if item.NotificationError != "" {
-			notificationFields += fmt.Sprintf(" notificationError=%q", item.NotificationError)
-		}
-		if item.Status == "failed" {
-			_, _ = fmt.Fprintf(stderr, "report=%s status=failed error=%q%s\n", item.ReportID, item.Error, notificationFields)
-			continue
-		}
-		_, _ = fmt.Fprintf(stderr, "report=%s status=succeeded output=%q%s\n", item.ReportID, item.OutputPath, notificationFields)
-	}
-	_, _ = 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")
@@ -379,31 +380,3 @@ func addCommonFlags(fs *flag.FlagSet, opts *commonOptions, includeOutput bool) {
 		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/collect/collect.go

@@ -0,0 +1,31 @@
+// Package collect owns upstream weather source collection for application use.
+package collect
+
+import (
+	"context"
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/adapters/weatherapi"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/weatherdata"
+)
+
+type Request struct {
+	Config config.Config
+}
+
+type Result struct {
+	Bundle *weatherdata.Bundle
+}
+
+func Run(ctx context.Context, req Request) (*Result, error) {
+	client, err := weatherapi.New(req.Config)
+	if err != nil {
+		return nil, fmt.Errorf("prepare weather collection: %w", err)
+	}
+	bundle, err := client.FetchBundle(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("collect weather bundle: %w", err)
+	}
+	return &Result{Bundle: bundle}, nil
+}

internal/collect/collect_test.go

@@ -0,0 +1,99 @@
+package collect
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/config"
+)
+
+func TestRunFetchesBundle(t *testing.T) {
+	server := collectionTestServer(t, nil)
+	defer server.Close()
+
+	cfg := config.Defaults()
+	cfg.WeatherAPI.BaseURL = server.URL + "/"
+
+	result, err := Run(context.Background(), Request{Config: cfg})
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	if result == nil || result.Bundle == nil {
+		t.Fatal("Run() result bundle = nil, want fetched bundle")
+	}
+	if result.Bundle.Hourly == nil {
+		t.Fatal("Hourly = nil, want fetched hourly forecast")
+	}
+	if result.Bundle.WeatherStory == nil || result.Bundle.WeatherStory.Title != "Several Chances for Rain Through Monday" {
+		t.Fatalf("WeatherStory = %#v, want fetched weather story", result.Bundle.WeatherStory)
+	}
+}
+
+func TestRunWrapsAdapterConstructionError(t *testing.T) {
+	cfg := config.Defaults()
+	cfg.WeatherAPI.BaseURL = ""
+	cfg.Secrets.Directory = "super-secret-directory"
+
+	_, err := Run(context.Background(), Request{Config: cfg})
+	if err == nil {
+		t.Fatal("Run() error = nil, want adapter construction error")
+	}
+	if !strings.Contains(err.Error(), "prepare weather collection") {
+		t.Fatalf("error = %q, want collection setup context", err.Error())
+	}
+	if strings.Contains(err.Error(), cfg.Secrets.Directory) {
+		t.Fatalf("error = %q, want no secret path leakage", err.Error())
+	}
+}
+
+func TestRunWrapsFetchError(t *testing.T) {
+	server := collectionTestServer(t, map[string]int{"/observations": http.StatusBadGateway})
+	defer server.Close()
+
+	cfg := config.Defaults()
+	cfg.WeatherAPI.BaseURL = server.URL + "/"
+
+	_, err := Run(context.Background(), Request{Config: cfg})
+	if err == nil {
+		t.Fatal("Run() error = nil, want fetch error")
+	}
+	if !strings.Contains(err.Error(), "collect weather bundle") {
+		t.Fatalf("error = %q, want collection fetch context", err.Error())
+	}
+	if !strings.Contains(err.Error(), "/observations") {
+		t.Fatalf("error = %q, want source endpoint context", err.Error())
+	}
+}
+
+func collectionTestServer(t *testing.T, statusByPath map[string]int) *httptest.Server {
+	t.Helper()
+	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if status := statusByPath[r.URL.Path]; status != 0 {
+			http.Error(w, "upstream failure", status)
+			return
+		}
+		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":{"issuedAt":"2026-05-29T10:30:00-05:00","product":"hourly","periods":[{"startTime":"2026-05-29T13:00:00-05:00","endTime":"2026-05-29T14:00:00-05:00"}]}}`))
+		case "/forecast/narrative":
+			_, _ = w.Write([]byte(`{"data":{"issuedAt":"2026-05-29T10:30:00-05:00","product":"narrative","periods":[]}}`))
+		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":[],"shortTerm":{"qualifier":"(Short Term)","text":"Short-term AFD narrative for saved bundle."},"longTerm":{"qualifier":"(Long Term)","text":"Long-term AFD narrative for saved bundle."}}}`))
+		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"}}`))
+		case "/outlooks/convective":
+			_, _ = w.Write([]byte(`{"data":{"asOf":"2026-05-29T16:00:00Z","outlooks":[],"discussions":[]}}`))
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+}

internal/config/config.go

@@ -58,15 +58,22 @@ type NotifyConfig struct {
 }
 
 type DistributorNotifyConfig struct {
-	Enabled                bool                `yaml:"enabled"`
-	Endpoint               string              `yaml:"endpoint"`
-	TokenEnv               string              `yaml:"token_env"`
-	Timeout                time.Duration       `yaml:"timeout"`
-	FailurePolicy          NotifyFailurePolicy `yaml:"failure_policy"`
-	PipelineIDTemplate     string              `yaml:"pipeline_id_template"`
-	BundleIDTemplate       string              `yaml:"bundle_id_template"`
-	IdempotencyKeyTemplate string              `yaml:"idempotency_key_template"`
-	ReportPathTemplates    []string            `yaml:"report_path_templates"`
+	Enabled                bool                         `yaml:"enabled"`
+	Endpoint               string                       `yaml:"endpoint"`
+	TokenEnv               string                       `yaml:"token_env"`
+	Timeout                time.Duration                `yaml:"timeout"`
+	FailurePolicy          NotifyFailurePolicy          `yaml:"failure_policy"`
+	PipelineIDTemplate     string                       `yaml:"pipeline_id_template"`
+	BundleIDTemplate       string                       `yaml:"bundle_id_template"`
+	IdempotencyKeyTemplate string                       `yaml:"idempotency_key_template"`
+	Batch                  DistributorBatchNotifyConfig `yaml:"batch"`
+}
+
+type DistributorBatchNotifyConfig struct {
+	Enabled                bool   `yaml:"enabled"`
+	PipelineIDTemplate     string `yaml:"pipeline_id_template"`
+	BundleIDTemplate       string `yaml:"bundle_id_template"`
+	IdempotencyKeyTemplate string `yaml:"idempotency_key_template"`
 }
 
 type MissingSourceConfig struct {
@@ -105,10 +112,16 @@ type RecentChangeConfig struct {
 }
 
 type ReportConfig struct {
-	DeterministicModules    []ModuleConfigItem `yaml:"deterministic_modules"`
+	DeterministicModules    []ModuleConfigItem      `yaml:"deterministic_modules"`
+	Distributor             ReportDistributorConfig `yaml:"distributor"`
 	deterministicModulesSet bool
 }
 
+type ReportDistributorConfig struct {
+	PathTemplates    []string `yaml:"path_templates"`
+	pathTemplatesSet bool
+}
+
 type ModuleConfigItem struct {
 	ID      module.ID `yaml:"id"`
 	Options any       `yaml:"options,omitempty"`
@@ -127,6 +140,10 @@ func (c *ReportConfig) UnmarshalYAML(value *yaml.Node) error {
 				return err
 			}
 			c.deterministicModulesSet = true
+		case "distributor":
+			if err := node.Decode(&c.Distributor); err != nil {
+				return err
+			}
 		default:
 			return fmt.Errorf("unknown report entry field %q", key)
 		}
@@ -134,6 +151,112 @@ func (c *ReportConfig) UnmarshalYAML(value *yaml.Node) error {
 	return nil
 }
 
+func (c *DistributorNotifyConfig) UnmarshalYAML(value *yaml.Node) error {
+	if value.Kind != yaml.MappingNode {
+		return fmt.Errorf("notify distributor entry must be a mapping")
+	}
+	for i := 0; i < len(value.Content); i += 2 {
+		key := value.Content[i].Value
+		node := value.Content[i+1]
+		switch key {
+		case "enabled":
+			if err := node.Decode(&c.Enabled); err != nil {
+				return err
+			}
+		case "endpoint":
+			if err := node.Decode(&c.Endpoint); err != nil {
+				return err
+			}
+		case "token_env":
+			if err := node.Decode(&c.TokenEnv); err != nil {
+				return err
+			}
+		case "timeout":
+			if err := node.Decode(&c.Timeout); err != nil {
+				return err
+			}
+		case "failure_policy":
+			if err := node.Decode(&c.FailurePolicy); err != nil {
+				return err
+			}
+		case "pipeline_id_template":
+			if err := node.Decode(&c.PipelineIDTemplate); err != nil {
+				return err
+			}
+		case "bundle_id_template":
+			if err := node.Decode(&c.BundleIDTemplate); err != nil {
+				return err
+			}
+		case "idempotency_key_template":
+			if err := node.Decode(&c.IdempotencyKeyTemplate); err != nil {
+				return err
+			}
+		case "batch":
+			if err := node.Decode(&c.Batch); err != nil {
+				return err
+			}
+		default:
+			return fmt.Errorf("unknown notify distributor field %q", key)
+		}
+	}
+	return nil
+}
+
+func (c *DistributorBatchNotifyConfig) UnmarshalYAML(value *yaml.Node) error {
+	if value.Kind != yaml.MappingNode {
+		return fmt.Errorf("notify distributor batch entry must be a mapping")
+	}
+	for i := 0; i < len(value.Content); i += 2 {
+		key := value.Content[i].Value
+		node := value.Content[i+1]
+		switch key {
+		case "enabled":
+			if err := node.Decode(&c.Enabled); err != nil {
+				return err
+			}
+		case "pipeline_id_template":
+			if err := node.Decode(&c.PipelineIDTemplate); err != nil {
+				return err
+			}
+		case "bundle_id_template":
+			if err := node.Decode(&c.BundleIDTemplate); err != nil {
+				return err
+			}
+		case "idempotency_key_template":
+			if err := node.Decode(&c.IdempotencyKeyTemplate); err != nil {
+				return err
+			}
+		default:
+			return fmt.Errorf("unknown notify distributor batch field %q", key)
+		}
+	}
+	return nil
+}
+
+func (c *ReportDistributorConfig) UnmarshalYAML(value *yaml.Node) error {
+	if value.Kind != yaml.MappingNode {
+		return fmt.Errorf("report distributor entry must be a mapping")
+	}
+	for i := 0; i < len(value.Content); i += 2 {
+		key := value.Content[i].Value
+		node := value.Content[i+1]
+		switch key {
+		case "path_templates":
+			if err := node.Decode(&c.PathTemplates); err != nil {
+				return err
+			}
+			c.pathTemplatesSet = true
+		default:
+			return fmt.Errorf("unknown report distributor field %q", key)
+		}
+	}
+	return nil
+}
+
+func (c ReportDistributorConfig) PathTemplatesSet() bool {
+	return c.pathTemplatesSet
+}
+
 func (m *ModuleConfigItem) UnmarshalYAML(value *yaml.Node) error {
 	switch value.Kind {
 	case yaml.ScalarNode:

internal/config/defaults.go

@@ -8,7 +8,7 @@ func Defaults() Config {
 	return Config{
 		WeatherAPI: WeatherAPIConfig{
 			Timeout:   10 * time.Second,
-			Precision: 1,
+			Precision: 0,
 			Units:     "us",
 			Timezone:  "America/Chicago",
 			Format:    "json",
@@ -31,8 +31,11 @@ func Defaults() Config {
 				PipelineIDTemplate:     "",
 				BundleIDTemplate:       "weatherreporter.{location_id}.{report_id}",
 				IdempotencyKeyTemplate: "{bundle_id}.{run_id}",
-				ReportPathTemplates: []string{
-					"{valid_start_date}/{artifact_group}/{valid_start_date}-{artifact_group}-{run_id}.md",
+				Batch: DistributorBatchNotifyConfig{
+					Enabled:                true,
+					PipelineIDTemplate:     "weatherreporter",
+					BundleIDTemplate:       "weatherreporter.{location_id}.{batch}",
+					IdempotencyKeyTemplate: "{bundle_id}.{batch_run_id}",
 				},
 			},
 		},

internal/config/notify_templates.go

@@ -18,9 +18,18 @@ type DistributorTemplateValues struct {
 	ValidEndTime    string
 	ValidStartStamp string
 	ValidEndStamp   string
+	StormID         string
 	BundleID        string
 }
 
+type DistributorBatchTemplateValues struct {
+	LocationID       string
+	Batch            string
+	BatchRunID       string
+	BatchStartedDate string
+	BundleID         string
+}
+
 var distributorTemplateVariables = map[string]struct{}{
 	"location_id":       {},
 	"report_id":         {},
@@ -33,6 +42,7 @@ var distributorTemplateVariables = map[string]struct{}{
 	"valid_end_time":    {},
 	"valid_start_stamp": {},
 	"valid_end_stamp":   {},
+	"storm_id":          {},
 }
 
 var distributorIdempotencyTemplateVariables = map[string]struct{}{
@@ -47,11 +57,29 @@ var distributorIdempotencyTemplateVariables = map[string]struct{}{
 	"valid_end_time":    {},
 	"valid_start_stamp": {},
 	"valid_end_stamp":   {},
+	"storm_id":          {},
 	"bundle_id":         {},
 }
 
 var distributorPipelineTemplateVariables = distributorIdempotencyTemplateVariables
 
+var distributorBatchTemplateVariables = map[string]struct{}{
+	"location_id":        {},
+	"batch":              {},
+	"batch_run_id":       {},
+	"batch_started_date": {},
+}
+
+var distributorBatchIdempotencyTemplateVariables = map[string]struct{}{
+	"location_id":        {},
+	"batch":              {},
+	"batch_run_id":       {},
+	"batch_started_date": {},
+	"bundle_id":          {},
+}
+
+var distributorBatchPipelineTemplateVariables = distributorBatchTemplateVariables
+
 func RenderDistributorBundleID(template string, values DistributorTemplateValues) (string, error) {
 	return renderDistributorTemplate("notify.distributor.bundle_id_template", template, values, distributorTemplateVariables)
 }
@@ -71,23 +99,56 @@ func RenderDistributorIdempotencyKey(template string, values DistributorTemplate
 	return renderDistributorTemplate("notify.distributor.idempotency_key_template", template, values, distributorIdempotencyTemplateVariables)
 }
 
-func RenderDistributorReportPaths(templates []string, values DistributorTemplateValues) ([]string, error) {
+func RenderDistributorBatchBundleID(template string, values DistributorBatchTemplateValues) (string, error) {
+	rendered, err := renderDistributorBatchTemplate("notify.distributor.batch.bundle_id_template", template, values, distributorBatchTemplateVariables)
+	if err != nil {
+		return "", err
+	}
+	if strings.TrimSpace(rendered) == "" {
+		return "", fmt.Errorf("notify.distributor.batch.bundle_id_template renders an empty bundle id")
+	}
+	return rendered, nil
+}
+
+func RenderDistributorBatchPipelineID(template string, values DistributorBatchTemplateValues) (string, error) {
+	rendered, err := renderDistributorBatchTemplate("notify.distributor.batch.pipeline_id_template", template, values, distributorBatchPipelineTemplateVariables)
+	if err != nil {
+		return "", err
+	}
+	if strings.TrimSpace(rendered) == "" {
+		return "", fmt.Errorf("notify.distributor.batch.pipeline_id_template renders an empty pipeline id")
+	}
+	return rendered, nil
+}
+
+func RenderDistributorBatchIdempotencyKey(template string, values DistributorBatchTemplateValues) (string, error) {
+	rendered, err := renderDistributorBatchTemplate("notify.distributor.batch.idempotency_key_template", template, values, distributorBatchIdempotencyTemplateVariables)
+	if err != nil {
+		return "", err
+	}
+	if strings.TrimSpace(rendered) == "" {
+		return "", fmt.Errorf("notify.distributor.batch.idempotency_key_template renders an empty idempotency key")
+	}
+	return rendered, nil
+}
+
+func RenderDistributorReportPaths(name string, templates []string, values DistributorTemplateValues) ([]string, error) {
 	if len(templates) == 0 {
-		return nil, fmt.Errorf("notify.distributor.report_path_templates must contain at least one entry")
+		return nil, fmt.Errorf("%s must contain at least one entry", name)
 	}
 	paths := make([]string, 0, len(templates))
 	seen := make(map[string]struct{}, len(templates))
 	for i, template := range templates {
-		name := fmt.Sprintf("notify.distributor.report_path_templates[%d]", i)
-		rendered, err := renderDistributorTemplate(name, template, values, distributorTemplateVariables)
+		itemName := fmt.Sprintf("%s[%d]", name, i)
+		rendered, err := renderDistributorTemplate(itemName, template, values, distributorTemplateVariables)
 		if err != nil {
 			return nil, err
 		}
-		if err := ValidateDistributorReportPath(name, rendered); err != nil {
+		if err := ValidateDistributorReportPath(itemName, rendered); err != nil {
 			return nil, err
 		}
 		if _, ok := seen[rendered]; ok {
-			return nil, fmt.Errorf("notify.distributor.report_path_templates renders duplicate path %q", rendered)
+			return nil, fmt.Errorf("%s renders duplicate path %q", name, rendered)
 		}
 		seen[rendered] = struct{}{}
 		paths = append(paths, rendered)
@@ -100,6 +161,11 @@ func validateDistributorTemplate(name, template string, allowed map[string]struc
 	return err
 }
 
+func validateDistributorBatchTemplate(name, template string, allowed map[string]struct{}) error {
+	_, err := renderDistributorBatchTemplate(name, template, DistributorBatchTemplateValues{}, allowed)
+	return err
+}
+
 func renderDistributorTemplate(name, template string, values DistributorTemplateValues, allowed map[string]struct{}) (string, error) {
 	var rendered strings.Builder
 	for i := 0; i < len(template); {
@@ -128,6 +194,34 @@ func renderDistributorTemplate(name, template string, values DistributorTemplate
 	return rendered.String(), nil
 }
 
+func renderDistributorBatchTemplate(name, template string, values DistributorBatchTemplateValues, allowed map[string]struct{}) (string, error) {
+	var rendered strings.Builder
+	for i := 0; i < len(template); {
+		switch template[i] {
+		case '{':
+			end := strings.IndexByte(template[i+1:], '}')
+			if end < 0 {
+				return "", fmt.Errorf("%s contains an unclosed template variable", name)
+			}
+			variable := template[i+1 : i+1+end]
+			if variable == "" {
+				return "", fmt.Errorf("%s contains an empty template variable", name)
+			}
+			if _, ok := allowed[variable]; !ok {
+				return "", fmt.Errorf("%s contains unknown template variable %q", name, variable)
+			}
+			rendered.WriteString(distributorBatchTemplateValue(variable, values))
+			i += end + 2
+		case '}':
+			return "", fmt.Errorf("%s contains an unopened template variable", name)
+		default:
+			rendered.WriteByte(template[i])
+			i++
+		}
+	}
+	return rendered.String(), nil
+}
+
 func distributorTemplateValue(variable string, values DistributorTemplateValues) string {
 	switch variable {
 	case "location_id":
@@ -152,6 +246,25 @@ func distributorTemplateValue(variable string, values DistributorTemplateValues)
 		return values.ValidStartStamp
 	case "valid_end_stamp":
 		return values.ValidEndStamp
+	case "storm_id":
+		return values.StormID
+	case "bundle_id":
+		return values.BundleID
+	default:
+		return ""
+	}
+}
+
+func distributorBatchTemplateValue(variable string, values DistributorBatchTemplateValues) string {
+	switch variable {
+	case "location_id":
+		return values.LocationID
+	case "batch":
+		return values.Batch
+	case "batch_run_id":
+		return values.BatchRunID
+	case "batch_started_date":
+		return values.BatchStartedDate
 	case "bundle_id":
 		return values.BundleID
 	default:
@@ -178,7 +291,7 @@ func ValidateDistributorReportPath(name, path string) error {
 		if segment == "." || segment == ".." {
 			return fmt.Errorf("%s must not render . or .. path segments", name)
 		}
-		if segment == "manifest.json" || segment == ".distributor.json" {
+		if segment == "manifest.json" || segment == distributorSidecarBasename() {
 			return fmt.Errorf("%s must not render reserved path segment %q", name, segment)
 		}
 	}
@@ -186,6 +299,10 @@ func ValidateDistributorReportPath(name, path string) error {
 	return nil
 }
 
+func distributorSidecarBasename() string {
+	return "." + "distributor.json"
+}
+
 func isDistributorAbsolutePath(path string) bool {
 	if filepath.IsAbs(path) || strings.HasPrefix(path, "/") {
 		return true

internal/config/reports.go

@@ -4,7 +4,6 @@ import (
 	"bytes"
 	"fmt"
 	"reflect"
-	"strings"
 
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/module"
@@ -12,65 +11,163 @@ import (
 	"gopkg.in/yaml.v3"
 )
 
-func (cfg Config) ReportModuleOverrides() map[report.ID][]module.ConfigItem {
-	overrides := map[report.ID][]module.ConfigItem{}
-	for key, reportCfg := range cfg.Reports {
-		if !reportCfg.deterministicModulesSet {
-			continue
-		}
-		id, err := reportIDForConfigKey(key)
-		if err != nil {
-			continue
-		}
-		items := make([]module.ConfigItem, 0, len(reportCfg.DeterministicModules))
-		for _, item := range reportCfg.DeterministicModules {
-			items = append(items, module.ConfigItem{ID: item.ID, Options: item.Options})
-		}
-		overrides[id] = items
-	}
-	return overrides
+func (cfg Config) ReportModuleOverrides() (map[report.ID][]module.ConfigItem, error) {
+	return traverseReportModules(&cfg, reportModuleTraversalOptions{
+		normalizeOptions: true,
+	})
+}
+
+func (cfg Config) ReportDistributorPathOverrides() (map[report.ID][]string, error) {
+	return traverseReportDistributorPathOverrides(cfg)
 }
 
 func normalizeReportModules(cfg *Config) error {
 	if cfg.Reports == nil {
 		cfg.Reports = map[string]ReportConfig{}
 	}
+	_, err := traverseReportModules(cfg, reportModuleTraversalOptions{
+		normalizeOptions: true,
+		updateConfig:     true,
+	})
+	return err
+}
+
+func validateReportModules(cfg Config) error {
+	_, err := traverseReportModules(&cfg, reportModuleTraversalOptions{
+		normalizeOptions: true,
+	})
+	return err
+}
+
+func validateReportDistributorPathOverrides(cfg Config) error {
+	_, err := traverseReportDistributorPathOverrides(cfg)
+	return err
+}
+
+type reportModuleTraversalOptions struct {
+	normalizeOptions bool
+	updateConfig     bool
+}
+
+func traverseReportModules(cfg *Config, opts reportModuleTraversalOptions) (map[report.ID][]module.ConfigItem, error) {
+	overrides := map[report.ID][]module.ConfigItem{}
+	if cfg.Reports == nil {
+		return overrides, nil
+	}
 	moduleRegistry, err := briefing.DefaultModuleRegistry()
 	if err != nil {
-		return fmt.Errorf("initialize module registry: %w", err)
+		return nil, fmt.Errorf("initialize module registry: %w", err)
 	}
 	reportRegistry := report.DefaultRegistry()
 	seenReports := map[report.ID]string{}
 	for key, reportCfg := range cfg.Reports {
-		reportID, err := reportIDForConfigKey(key)
+		reportID, err := report.IDForConfigKey(key)
 		if err != nil {
-			return err
+			return nil, fmt.Errorf("reports.%s: %w", key, err)
 		}
 		if previous, ok := seenReports[reportID]; ok {
-			return fmt.Errorf("reports.%s duplicates report override %q", key, previous)
+			return nil, fmt.Errorf("reports.%s duplicates report override %q", key, previous)
 		}
 		seenReports[reportID] = key
 		if _, err := reportRegistry.Lookup(reportID); err != nil {
-			return fmt.Errorf("reports.%s: %w", key, err)
+			return nil, fmt.Errorf("reports.%s: %w", key, err)
 		}
 		if !reportCfg.deterministicModulesSet {
 			continue
 		}
-		items := make([]module.ConfigItem, 0, len(reportCfg.DeterministicModules))
-		for i, rawItem := range reportCfg.DeterministicModules {
-			options, err := normalizeModuleOptions(moduleRegistry, rawItem.ID, rawItem.Options)
-			if err != nil {
-				return fmt.Errorf("reports.%s.deterministic_modules[%d]: %w", key, i, err)
-			}
-			reportCfg.DeterministicModules[i].Options = options
-			items = append(items, module.ConfigItem{ID: rawItem.ID, Options: options})
+		items, normalized, err := moduleItemsFromConfig(moduleRegistry, key, reportCfg.DeterministicModules, opts.normalizeOptions)
+		if err != nil {
+			return nil, err
 		}
 		if err := moduleRegistry.ValidateComposition(reportID, items); err != nil {
-			return fmt.Errorf("reports.%s.deterministic_modules: %w", key, err)
+			return nil, fmt.Errorf("reports.%s.deterministic_modules: %w", key, err)
+		}
+		overrides[reportID] = items
+		if opts.updateConfig {
+			reportCfg.DeterministicModules = normalized
+			cfg.Reports[key] = reportCfg
 		}
-		cfg.Reports[key] = reportCfg
 	}
-	return nil
+	return overrides, nil
+}
+
+func traverseReportDistributorPathOverrides(cfg Config) (map[report.ID][]string, error) {
+	overrides := map[report.ID][]string{}
+	if cfg.Reports == nil {
+		return overrides, nil
+	}
+	reportRegistry := report.DefaultRegistry()
+	seenReports := map[report.ID]string{}
+	for key, reportCfg := range cfg.Reports {
+		reportID, err := report.IDForConfigKey(key)
+		if err != nil {
+			return nil, fmt.Errorf("reports.%s: %w", key, err)
+		}
+		if previous, ok := seenReports[reportID]; ok {
+			return nil, fmt.Errorf("reports.%s duplicates report override %q", key, previous)
+		}
+		seenReports[reportID] = key
+		if _, err := reportRegistry.Lookup(reportID); err != nil {
+			return nil, fmt.Errorf("reports.%s: %w", key, err)
+		}
+		if !reportCfg.Distributor.pathTemplatesSet {
+			continue
+		}
+		if err := validateReportDistributorPathTemplates(key, reportID, reportCfg.Distributor.PathTemplates); err != nil {
+			return nil, err
+		}
+		overrides[reportID] = append([]string(nil), reportCfg.Distributor.PathTemplates...)
+	}
+	return overrides, nil
+}
+
+func validateReportDistributorPathTemplates(reportKey string, reportID report.ID, templates []string) error {
+	name := fmt.Sprintf("reports.%s.distributor.path_templates", reportKey)
+	_, err := RenderDistributorReportPaths(name, templates, sampleDistributorTemplateValuesForReport(reportID))
+	return err
+}
+
+func sampleDistributorTemplateValues() DistributorTemplateValues {
+	return sampleDistributorTemplateValuesForReport(report.Storm)
+}
+
+func sampleDistributorTemplateValuesForReport(reportID report.ID) DistributorTemplateValues {
+	stormID := ""
+	if reportID == report.Storm {
+		stormID = "2026-05-29T0000-2026-05-30T0000"
+	}
+	return DistributorTemplateValues{
+		LocationID:      "location",
+		ReportID:        "report",
+		RunID:           "run",
+		ArtifactGroup:   "artifact",
+		BatchOutputName: "report.md",
+		ValidStartDate:  "2026-05-29",
+		ValidEndDate:    "2026-05-30",
+		ValidStartTime:  "0000",
+		ValidEndTime:    "0000",
+		ValidStartStamp: "2026-05-29T0000",
+		ValidEndStamp:   "2026-05-30T0000",
+		StormID:         stormID,
+	}
+}
+
+func moduleItemsFromConfig(registry briefing.ModuleRegistry, reportKey string, items []ModuleConfigItem, normalizeOptions bool) ([]module.ConfigItem, []ModuleConfigItem, error) {
+	out := make([]module.ConfigItem, 0, len(items))
+	normalizedItems := append([]ModuleConfigItem(nil), items...)
+	for i, item := range items {
+		options := item.Options
+		if normalizeOptions {
+			var err error
+			options, err = normalizeModuleOptions(registry, item.ID, item.Options)
+			if err != nil {
+				return nil, nil, fmt.Errorf("reports.%s.deterministic_modules[%d]: %w", reportKey, i, err)
+			}
+			normalizedItems[i].Options = options
+		}
+		out = append(out, module.ConfigItem{ID: item.ID, Options: options})
+	}
+	return out, normalizedItems, nil
 }
 
 func normalizeModuleOptions(registry briefing.ModuleRegistry, id module.ID, raw any) (any, error) {
@@ -84,6 +181,9 @@ func normalizeModuleOptions(registry briefing.ModuleRegistry, id module.ID, raw
 	if definition.DefaultOptions == nil {
 		return nil, fmt.Errorf("module %q does not accept options", id)
 	}
+	if err := definition.ValidateOptions(raw); err == nil {
+		return raw, nil
+	}
 	optionType := reflect.TypeOf(definition.DefaultOptions)
 	normalized, err := decodeKnownOptions(raw, optionType)
 	if err != nil {
@@ -105,21 +205,3 @@ func decodeKnownOptions(raw any, optionType reflect.Type) (any, error) {
 	}
 	return target.Elem().Interface(), nil
 }
-
-func reportIDForConfigKey(key string) (report.ID, error) {
-	normalized := strings.ReplaceAll(strings.TrimSpace(strings.ToLower(key)), "-", "_")
-	switch normalized {
-	case "daily", "daily_today":
-		return report.DailyToday, nil
-	case "tomorrow", "daily_tomorrow":
-		return report.DailyTomorrow, nil
-	case "three_day", "three_day_outlook":
-		return report.ThreeDay, nil
-	case "weekend", "weekend_outlook":
-		return report.Weekend, nil
-	case "storm", "storm_report":
-		return report.Storm, nil
-	default:
-		return "", fmt.Errorf("reports.%s is not a known report", key)
-	}
-}

internal/config/validate.go

@@ -9,7 +9,10 @@ import (
 )
 
 func Validate(cfg Config) error {
-	if err := normalizeReportModules(&cfg); err != nil {
+	if err := validateReportModules(cfg); err != nil {
+		return err
+	}
+	if err := validateReportDistributorPathOverrides(cfg); err != nil {
 		return err
 	}
 	if cfg.WeatherAPI.BaseURL != "" {
@@ -121,22 +124,7 @@ func validateDistributorNotify(cfg DistributorNotifyConfig) error {
 	if err := validateDistributorTemplate("notify.distributor.idempotency_key_template", cfg.IdempotencyKeyTemplate, distributorIdempotencyTemplateVariables); err != nil {
 		return err
 	}
-	if len(cfg.ReportPathTemplates) == 0 {
-		return fmt.Errorf("notify.distributor.report_path_templates must contain at least one entry when enabled")
-	}
-	values := DistributorTemplateValues{
-		LocationID:      "location",
-		ReportID:        "report",
-		RunID:           "run",
-		ArtifactGroup:   "artifact",
-		BatchOutputName: "report.md",
-		ValidStartDate:  "2026-05-29",
-		ValidEndDate:    "2026-05-30",
-		ValidStartTime:  "0000",
-		ValidEndTime:    "0000",
-		ValidStartStamp: "2026-05-29T0000",
-		ValidEndStamp:   "2026-05-30T0000",
-	}
+	values := sampleDistributorTemplateValues()
 	bundleID, err := RenderDistributorBundleID(cfg.BundleIDTemplate, values)
 	if err != nil {
 		return err
@@ -145,13 +133,56 @@ func validateDistributorNotify(cfg DistributorNotifyConfig) error {
 	if _, err := RenderDistributorPipelineID(cfg.PipelineIDTemplate, values); err != nil {
 		return err
 	}
-	if _, err := RenderDistributorReportPaths(cfg.ReportPathTemplates, values); err != nil {
+	if err := validateDistributorBatchNotify(cfg.Batch); err != nil {
 		return err
 	}
 
 	return nil
 }
 
+func validateDistributorBatchNotify(cfg DistributorBatchNotifyConfig) error {
+	if !cfg.Enabled {
+		return nil
+	}
+	if cfg.PipelineIDTemplate == "" {
+		return fmt.Errorf("notify.distributor.batch.pipeline_id_template is required when enabled")
+	}
+	if err := validateDistributorBatchTemplate("notify.distributor.batch.pipeline_id_template", cfg.PipelineIDTemplate, distributorBatchPipelineTemplateVariables); err != nil {
+		return err
+	}
+	if cfg.BundleIDTemplate == "" {
+		return fmt.Errorf("notify.distributor.batch.bundle_id_template is required when enabled")
+	}
+	if err := validateDistributorBatchTemplate("notify.distributor.batch.bundle_id_template", cfg.BundleIDTemplate, distributorBatchTemplateVariables); err != nil {
+		return err
+	}
+	if cfg.IdempotencyKeyTemplate == "" {
+		return fmt.Errorf("notify.distributor.batch.idempotency_key_template is required when enabled")
+	}
+	if err := validateDistributorBatchTemplate("notify.distributor.batch.idempotency_key_template", cfg.IdempotencyKeyTemplate, distributorBatchIdempotencyTemplateVariables); err != nil {
+		return err
+	}
+
+	values := DistributorBatchTemplateValues{
+		LocationID:       "location",
+		Batch:            "morning",
+		BatchRunID:       "20260529T100000.000000000Z_morning",
+		BatchStartedDate: "2026-05-29",
+	}
+	bundleID, err := RenderDistributorBatchBundleID(cfg.BundleIDTemplate, values)
+	if err != nil {
+		return err
+	}
+	values.BundleID = bundleID
+	if _, err := RenderDistributorBatchPipelineID(cfg.PipelineIDTemplate, values); err != nil {
+		return err
+	}
+	if _, err := RenderDistributorBatchIdempotencyKey(cfg.IdempotencyKeyTemplate, values); err != nil {
+		return err
+	}
+	return nil
+}
+
 func validatePolicy(name string, policy MissingSourcePolicy) error {
 	switch policy {
 	case MissingSourceError, MissingSourceWarn, MissingSourceNone:

internal/facts/facts.go

@@ -3,6 +3,7 @@ package facts
 
 import (
 	"fmt"
+	"sort"
 	"time"
 
 	"gitea.maximumdirect.net/eric/weatherreporter/internal/forecast"
@@ -12,15 +13,16 @@ import (
 )
 
 type CollectedFacts struct {
-	FetchedAt    time.Time
-	Observation  *weatherdata.Observation
-	Current      *weatherdata.Current
-	Hourly       *weatherdata.ForecastRun
-	Narrative    *weatherdata.ForecastRun
-	Alerts       *weatherdata.AlertRun
-	Discussion   *weatherdata.Discussion
-	Daily        *weatherdata.ForecastRun
-	WeatherStory *weatherdata.WeatherStory
+	FetchedAt             time.Time
+	Observation           *weatherdata.Observation
+	Current               *weatherdata.Current
+	Hourly                *weatherdata.ForecastRun
+	Narrative             *weatherdata.ForecastRun
+	Alerts                *weatherdata.AlertRun
+	Discussion            *weatherdata.Discussion
+	Daily                 *weatherdata.ForecastRun
+	WeatherStory          *weatherdata.WeatherStory
+	SPCConvectiveOutlooks *weatherdata.ConvectiveOutlookRun
 
 	SourceProvenance []weatherdata.Source
 	SourceWarnings   []weatherdata.SourceWarning
@@ -31,33 +33,35 @@ func BuildCollected(bundle *weatherdata.Bundle) CollectedFacts {
 		return CollectedFacts{}
 	}
 	return CollectedFacts{
-		FetchedAt:        bundle.FetchedAt,
-		Observation:      bundle.Observation,
-		Current:          bundle.Current,
-		Hourly:           bundle.Hourly,
-		Narrative:        bundle.Narrative,
-		Alerts:           bundle.Alerts,
-		Discussion:       bundle.Discussion,
-		Daily:            bundle.Daily,
-		WeatherStory:     bundle.WeatherStory,
-		SourceProvenance: append([]weatherdata.Source(nil), bundle.Sources...),
-		SourceWarnings:   append([]weatherdata.SourceWarning(nil), bundle.Warnings...),
+		FetchedAt:             bundle.FetchedAt,
+		Observation:           bundle.Observation,
+		Current:               bundle.Current,
+		Hourly:                bundle.Hourly,
+		Narrative:             bundle.Narrative,
+		Alerts:                bundle.Alerts,
+		Discussion:            bundle.Discussion,
+		Daily:                 bundle.Daily,
+		WeatherStory:          bundle.WeatherStory,
+		SPCConvectiveOutlooks: bundle.SPCConvectiveOutlooks,
+		SourceProvenance:      append([]weatherdata.Source(nil), bundle.Sources...),
+		SourceWarnings:        append([]weatherdata.SourceWarning(nil), bundle.Warnings...),
 	}
 }
 
 func (f CollectedFacts) Bundle() *weatherdata.Bundle {
 	return &weatherdata.Bundle{
-		FetchedAt:    f.FetchedAt,
-		Observation:  f.Observation,
-		Current:      f.Current,
-		Hourly:       f.Hourly,
-		Narrative:    f.Narrative,
-		Alerts:       f.Alerts,
-		Discussion:   f.Discussion,
-		Daily:        f.Daily,
-		WeatherStory: f.WeatherStory,
-		Sources:      append([]weatherdata.Source(nil), f.SourceProvenance...),
-		Warnings:     append([]weatherdata.SourceWarning(nil), f.SourceWarnings...),
+		FetchedAt:             f.FetchedAt,
+		Observation:           f.Observation,
+		Current:               f.Current,
+		Hourly:                f.Hourly,
+		Narrative:             f.Narrative,
+		Alerts:                f.Alerts,
+		Discussion:            f.Discussion,
+		Daily:                 f.Daily,
+		WeatherStory:          f.WeatherStory,
+		SPCConvectiveOutlooks: f.SPCConvectiveOutlooks,
+		Sources:               append([]weatherdata.Source(nil), f.SourceProvenance...),
+		Warnings:              append([]weatherdata.SourceWarning(nil), f.SourceWarnings...),
 	}
 }
 
@@ -73,6 +77,8 @@ type DerivedFacts struct {
 	ValidPeriodNarrativePeriods []weatherdata.ForecastPeriod
 	ValidPeriodDailyPeriods     []weatherdata.ForecastPeriod
 	AlertOverlaps               []forecast.AlertOverlap
+	SPCConvectiveOutlooks       []weatherdata.ConvectiveOutlook
+	SPCConvectiveDiscussions    []weatherdata.ConvectiveOutlookDiscussion
 	DailySummaries              []forecast.DailySummary
 	DaypartSummaries            []forecast.DaypartSummary
 	PrecipTiming                forecast.PrecipTiming
@@ -96,16 +102,20 @@ func BuildDerived(req BuildDerivedRequest) (DerivedFacts, error) {
 	}
 	bundle := req.Collected.Bundle()
 	period := req.Resolved.ValidPeriod
+	spcOutlooks, spcDiscussions := selectSPCConvectiveOutlooks(req.Collected.SPCConvectiveOutlooks, period)
 	derived := DerivedFacts{
 		ValidPeriodHourlyPeriods:    forecast.SelectHourlyPeriods(req.Collected.Hourly, period),
 		ValidPeriodNarrativePeriods: forecast.SelectHourlyPeriods(req.Collected.Narrative, period),
 		ValidPeriodDailyPeriods:     forecast.SelectHourlyPeriods(req.Collected.Daily, period),
 		AlertOverlaps:               forecast.AlertOverlaps(req.Collected.Alerts, period),
+		SPCConvectiveOutlooks:       spcOutlooks,
+		SPCConvectiveDiscussions:    spcDiscussions,
 	}
 	derived.PrecipTiming = forecast.BuildPrecipTiming(derived.ValidPeriodHourlyPeriods)
 
 	switch req.Resolved.Definition.ID {
-	case report.DailyToday, report.DailyTomorrow:
+	case report.Hourly:
+	case report.Daily, report.Today, report.Tomorrow:
 		summary, err := forecast.BuildDailySummary(bundle, period.Start, location, req.Dayparts)
 		if err != nil {
 			return DerivedFacts{}, err
@@ -139,3 +149,81 @@ func collectDaypartSummaries(derived DerivedFacts) []forecast.DaypartSummary {
 	}
 	return out
 }
+
+func selectSPCConvectiveOutlooks(run *weatherdata.ConvectiveOutlookRun, period timeutil.Period) ([]weatherdata.ConvectiveOutlook, []weatherdata.ConvectiveOutlookDiscussion) {
+	if run == nil {
+		return nil, nil
+	}
+
+	outlooks := make([]weatherdata.ConvectiveOutlook, 0, len(run.Outlooks))
+	days := map[int]struct{}{}
+	for _, outlook := range run.Outlooks {
+		outlookPeriod := timeutil.Period{Start: outlook.ValidFrom, End: outlook.ValidTo}
+		if !outlookPeriod.IsValid() || !outlookPeriod.Overlaps(period) {
+			continue
+		}
+		outlooks = append(outlooks, outlook)
+		days[outlook.Day] = struct{}{}
+	}
+	sort.SliceStable(outlooks, func(i, j int) bool {
+		left := outlooks[i]
+		right := outlooks[j]
+		if left.Day != right.Day {
+			return left.Day < right.Day
+		}
+		if left.OutlookType != right.OutlookType {
+			return left.OutlookType < right.OutlookType
+		}
+		leftRank, leftRankOK := severityRank(left)
+		rightRank, rightRankOK := severityRank(right)
+		if leftRankOK != rightRankOK {
+			return leftRankOK
+		}
+		if leftRankOK && leftRank != rightRank {
+			return leftRank > rightRank
+		}
+		if !left.ValidFrom.Equal(right.ValidFrom) {
+			return left.ValidFrom.Before(right.ValidFrom)
+		}
+		if left.Label != right.Label {
+			return left.Label < right.Label
+		}
+		return left.ID < right.ID
+	})
+
+	discussions := make([]weatherdata.ConvectiveOutlookDiscussion, 0, len(run.Discussions))
+	for _, discussion := range run.Discussions {
+		if _, ok := days[discussion.Day]; ok {
+			discussions = append(discussions, discussion)
+		}
+	}
+	sort.SliceStable(discussions, func(i, j int) bool {
+		left := discussions[i]
+		right := discussions[j]
+		if left.Day != right.Day {
+			return left.Day < right.Day
+		}
+		if left.UpdatedAt != nil && right.UpdatedAt != nil && !left.UpdatedAt.Equal(*right.UpdatedAt) {
+			return left.UpdatedAt.Before(*right.UpdatedAt)
+		}
+		if (left.UpdatedAt != nil) != (right.UpdatedAt != nil) {
+			return left.UpdatedAt != nil
+		}
+		if left.Headline != right.Headline {
+			return left.Headline < right.Headline
+		}
+		if left.Summary != right.Summary {
+			return left.Summary < right.Summary
+		}
+		return left.Discussion < right.Discussion
+	})
+
+	return outlooks, discussions
+}
+
+func severityRank(outlook weatherdata.ConvectiveOutlook) (int, bool) {
+	if outlook.SeverityRank == nil {
+		return 0, false
+	}
+	return *outlook.SeverityRank, true
+}

internal/facts/facts_test.go

@@ -2,6 +2,7 @@ package facts
 
 import (
 	"encoding/json"
+	"strings"
 	"testing"
 	"time"
 
@@ -16,14 +17,24 @@ func TestBuildCollectedCopiesBundleFactsAndKeepsSourcesSeparate(t *testing.T) {
 		FetchedAt: fetchedAt,
 		Current:   &weatherdata.Current{ConditionText: "Clear"},
 		Hourly:    &weatherdata.ForecastRun{Product: "hourly"},
-		Sources:   []weatherdata.Source{{Name: "hourly"}},
-		Warnings:  []weatherdata.SourceWarning{{Source: "discussion", Code: "missing_source"}},
+		SPCConvectiveOutlooks: &weatherdata.ConvectiveOutlookRun{
+			Product: "convective_outlook",
+			Outlooks: []weatherdata.ConvectiveOutlook{{
+				ID:    "day1-categorical-slight",
+				Label: "SLGT",
+			}},
+		},
+		Sources:  []weatherdata.Source{{Name: "hourly"}},
+		Warnings: []weatherdata.SourceWarning{{Source: "discussion", Code: "missing_source"}},
 	}
 
 	collected := BuildCollected(bundle)
 	if collected.FetchedAt != fetchedAt || collected.Current.ConditionText != "Clear" || collected.Hourly.Product != "hourly" {
 		t.Fatalf("CollectedFacts = %#v, want source facts copied from bundle", collected)
 	}
+	if collected.SPCConvectiveOutlooks == nil || collected.SPCConvectiveOutlooks.Outlooks[0].Label != "SLGT" {
+		t.Fatalf("SPCConvectiveOutlooks = %#v, want source copied from bundle", collected.SPCConvectiveOutlooks)
+	}
 	if len(collected.SourceProvenance) != 1 || collected.SourceProvenance[0].Name != "hourly" {
 		t.Fatalf("SourceProvenance = %#v, want hourly source", collected.SourceProvenance)
 	}
@@ -36,11 +47,16 @@ func TestBuildCollectedCopiesBundleFactsAndKeepsSourcesSeparate(t *testing.T) {
 	if collected.SourceProvenance[0].Name != "hourly" || collected.SourceWarnings[0].Source != "discussion" {
 		t.Fatalf("collected source slices changed after bundle mutation: %#v %#v", collected.SourceProvenance, collected.SourceWarnings)
 	}
+
+	roundTrip := collected.Bundle()
+	if roundTrip.SPCConvectiveOutlooks == nil || roundTrip.SPCConvectiveOutlooks.Outlooks[0].ID != "day1-categorical-slight" {
+		t.Fatalf("Bundle().SPCConvectiveOutlooks = %#v, want collected source restored", roundTrip.SPCConvectiveOutlooks)
+	}
 }
 
 func TestBuildDerivedDailySlicesDaypartsAndAlerts(t *testing.T) {
 	location := testLocation()
-	resolved := resolveForTest(t, report.DailyToday, mustParse("2026-05-29T08:00:00-05:00"), location)
+	resolved := resolveForTest(t, report.Daily, mustParse("2026-05-29T08:00:00-05:00"), location)
 	derived, err := BuildDerived(BuildDerivedRequest{
 		Resolved:  resolved,
 		Timezone:  location.String(),
@@ -119,7 +135,7 @@ func TestBuildDerivedOutlookBuildsPartialDaySummariesWithMissingOptionalSources(
 
 func TestBuildDerivedWeekendAndTomorrow(t *testing.T) {
 	location := testLocation()
-	for _, id := range []report.ID{report.DailyTomorrow, report.Weekend} {
+	for _, id := range []report.ID{report.Tomorrow, report.Weekend} {
 		resolved := resolveForTest(t, id, mustParse("2026-05-29T08:00:00-05:00"), location)
 		derived, err := BuildDerived(BuildDerivedRequest{
 			Resolved:  resolved,
@@ -136,6 +152,63 @@ func TestBuildDerivedWeekendAndTomorrow(t *testing.T) {
 	}
 }
 
+func TestBuildDerivedHourlyUsesRollingWindowFacts(t *testing.T) {
+	location := testLocation()
+	resolved := resolveForTest(t, report.Hourly, mustParse("2026-05-29T08:30:00-05:00"), location)
+	bundle := testBundle(location)
+	bundle.Alerts = &weatherdata.AlertRun{Alerts: []json.RawMessage{
+		json.RawMessage(`{"event":"Expired Advisory","headline":"Ends at start","severity":"Minor","effective":"2026-05-29T05:00:00-05:00","expires":"2026-05-29T08:30:00-05:00"}`),
+		json.RawMessage(`{"event":"Flood Watch","headline":"Flooding possible","severity":"Moderate","effective":"2026-05-29T11:00:00-05:00","expires":"2026-05-29T15:00:00-05:00"}`),
+		json.RawMessage(`{"event":"Evening Advisory","headline":"Starts at end","severity":"Minor","effective":"2026-05-29T14:30:00-05:00","expires":"2026-05-29T18:00:00-05:00"}`),
+	}}
+	bundle.SPCConvectiveOutlooks = testConvectiveOutlookRun(location)
+
+	derived, err := BuildDerived(BuildDerivedRequest{
+		Resolved:  resolved,
+		Timezone:  location.String(),
+		Dayparts:  testDayparts(),
+		Collected: BuildCollected(bundle),
+	})
+	if err != nil {
+		t.Fatalf("BuildDerived() error = %v", err)
+	}
+
+	if len(derived.ValidPeriodHourlyPeriods) != 4 {
+		t.Fatalf("ValidPeriodHourlyPeriods length = %d, want 4 rolling-window hours", len(derived.ValidPeriodHourlyPeriods))
+	}
+	if derived.ValidPeriodHourlyPeriods[0].StartTime.Format(time.RFC3339) != "2026-05-29T08:00:00-05:00" ||
+		derived.ValidPeriodHourlyPeriods[3].StartTime.Format(time.RFC3339) != "2026-05-29T14:00:00-05:00" {
+		t.Fatalf("ValidPeriodHourlyPeriods = %#v, want only hours overlapping 8:30 AM-2:30 PM", derived.ValidPeriodHourlyPeriods)
+	}
+	if len(derived.ValidPeriodNarrativePeriods) != 1 {
+		t.Fatalf("ValidPeriodNarrativePeriods length = %d, want overlapping narrative period", len(derived.ValidPeriodNarrativePeriods))
+	}
+	if len(derived.DailySummaries) != 0 || len(derived.DaypartSummaries) != 0 || derived.StormWindowSummary != nil {
+		t.Fatalf("hourly summaries daily=%#v daypart=%#v storm=%#v, want none", derived.DailySummaries, derived.DaypartSummaries, derived.StormWindowSummary)
+	}
+	if derived.PrecipTiming.FirstPrecipitation == nil || derived.PrecipTiming.FirstPrecipitation.Time.Format(time.RFC3339) != "2026-05-29T08:00:00-05:00" {
+		t.Fatalf("PrecipTiming.FirstPrecipitation = %#v, want first selected rainy hour", derived.PrecipTiming.FirstPrecipitation)
+	}
+	if derived.PrecipTiming.LastPrecipitation == nil || derived.PrecipTiming.LastPrecipitation.Time.Format(time.RFC3339) != "2026-05-29T14:00:00-05:00" {
+		t.Fatalf("PrecipTiming.LastPrecipitation = %#v, want final selected rainy window end", derived.PrecipTiming.LastPrecipitation)
+	}
+	if len(derived.PrecipTiming.PrecipitationWindows) != 2 {
+		t.Fatalf("PrecipTiming.PrecipitationWindows = %#v, want two hourly windows", derived.PrecipTiming.PrecipitationWindows)
+	}
+	if len(derived.AlertOverlaps) != 1 || derived.AlertOverlaps[0].Event != "Flood Watch" {
+		t.Fatalf("AlertOverlaps = %#v, want only alert overlapping hourly period", derived.AlertOverlaps)
+	}
+	if derived.AlertOverlaps[0].Overlap.End.Format(time.RFC3339) != "2026-05-29T14:30:00-05:00" {
+		t.Fatalf("Alert overlap end = %s, want clipped to hourly end", derived.AlertOverlaps[0].Overlap.End.Format(time.RFC3339))
+	}
+	if got, want := outlookIDs(derived.SPCConvectiveOutlooks), []string{"fri-high", "fri-storm", "fri-low", "fri-missing-rank", "fri-probabilistic"}; strings.Join(got, ",") != strings.Join(want, ",") {
+		t.Fatalf("SPCConvectiveOutlooks IDs = %#v, want %#v", got, want)
+	}
+	if got, want := discussionHeadlines(derived.SPCConvectiveDiscussions), []string{"day1 early", "day1 late"}; strings.Join(got, ",") != strings.Join(want, ",") {
+		t.Fatalf("SPCConvectiveDiscussions = %#v, want retained discussions for overlapping SPC day %#v", got, want)
+	}
+}
+
 func TestBuildDerivedStormBuildsWindowSummary(t *testing.T) {
 	location := testLocation()
 	resolved := resolveStormForTest(t, location)
@@ -166,6 +239,124 @@ func TestBuildDerivedStormBuildsWindowSummary(t *testing.T) {
 	}
 }
 
+func TestBuildDerivedSelectsSPCConvectiveOutlooksByValidPeriod(t *testing.T) {
+	location := testLocation()
+	now := mustParse("2026-05-29T08:00:00-05:00")
+	bundle := testBundle(location)
+	bundle.SPCConvectiveOutlooks = testConvectiveOutlookRun(location)
+
+	tests := []struct {
+		name           string
+		resolved       report.Resolved
+		wantOutlookIDs []string
+		wantDiscussion []string
+	}{
+		{
+			name:           "daily",
+			resolved:       resolveForTest(t, report.Daily, now, location),
+			wantOutlookIDs: []string{"fri-high", "fri-storm", "fri-low", "fri-missing-rank", "fri-probabilistic"},
+			wantDiscussion: []string{"day1 early", "day1 late"},
+		},
+		{
+			name:           "daily tomorrow",
+			resolved:       resolveForTest(t, report.Tomorrow, now, location),
+			wantOutlookIDs: []string{"sat-enhanced"},
+			wantDiscussion: []string{"day2"},
+		},
+		{
+			name:           "three day",
+			resolved:       resolveForTest(t, report.ThreeDay, now, location),
+			wantOutlookIDs: []string{"fri-high", "fri-storm", "fri-low", "fri-missing-rank", "fri-probabilistic", "sat-enhanced", "sun-slight"},
+			wantDiscussion: []string{"day1 early", "day1 late", "day2", "day3"},
+		},
+		{
+			name:           "weekend",
+			resolved:       resolveForTest(t, report.Weekend, now, location),
+			wantOutlookIDs: []string{"sat-enhanced", "sun-slight"},
+			wantDiscussion: []string{"day2", "day3"},
+		},
+		{
+			name:           "storm",
+			resolved:       resolveStormForTest(t, location),
+			wantOutlookIDs: []string{"fri-storm", "fri-low"},
+			wantDiscussion: []string{"day1 early", "day1 late"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			derived, err := BuildDerived(BuildDerivedRequest{
+				Resolved:  tt.resolved,
+				Timezone:  location.String(),
+				Dayparts:  testDayparts(),
+				Collected: BuildCollected(bundle),
+			})
+			if err != nil {
+				t.Fatalf("BuildDerived() error = %v", err)
+			}
+			if got := outlookIDs(derived.SPCConvectiveOutlooks); strings.Join(got, ",") != strings.Join(tt.wantOutlookIDs, ",") {
+				t.Fatalf("SPCConvectiveOutlooks IDs = %#v, want %#v", got, tt.wantOutlookIDs)
+			}
+			if got := discussionHeadlines(derived.SPCConvectiveDiscussions); strings.Join(got, ",") != strings.Join(tt.wantDiscussion, ",") {
+				t.Fatalf("SPCConvectiveDiscussions = %#v, want %#v", got, tt.wantDiscussion)
+			}
+		})
+	}
+}
+
+func TestBuildDerivedUnsupportedReportReturnsActionableError(t *testing.T) {
+	location := testLocation()
+	resolved := resolveForTest(t, report.Hourly, mustParse("2026-05-29T08:00:00-05:00"), location)
+	resolved.Definition.ID = report.ID("future_report")
+
+	_, err := BuildDerived(BuildDerivedRequest{
+		Resolved:  resolved,
+		Timezone:  location.String(),
+		Dayparts:  testDayparts(),
+		Collected: BuildCollected(testBundle(location)),
+	})
+	if err == nil || !strings.Contains(err.Error(), `derived facts are not implemented for report "future_report"`) {
+		t.Fatalf("BuildDerived() error = %v, want actionable unsupported report error", err)
+	}
+}
+
+func TestBuildDerivedSPCConvectiveOutlooksDistinguishesMissingAndCheckedEmpty(t *testing.T) {
+	location := testLocation()
+	resolved := resolveForTest(t, report.Daily, mustParse("2026-05-29T08:00:00-05:00"), location)
+	bundle := testBundle(location)
+	bundle.SPCConvectiveOutlooks = nil
+
+	derived, err := BuildDerived(BuildDerivedRequest{
+		Resolved:  resolved,
+		Timezone:  location.String(),
+		Dayparts:  testDayparts(),
+		Collected: BuildCollected(bundle),
+	})
+	if err != nil {
+		t.Fatalf("BuildDerived(missing source) error = %v", err)
+	}
+	if derived.SPCConvectiveOutlooks != nil || derived.SPCConvectiveDiscussions != nil {
+		t.Fatalf("missing source derived outlooks=%#v discussions=%#v, want nil slices", derived.SPCConvectiveOutlooks, derived.SPCConvectiveDiscussions)
+	}
+
+	bundle.SPCConvectiveOutlooks = &weatherdata.ConvectiveOutlookRun{Outlooks: []weatherdata.ConvectiveOutlook{}, Discussions: []weatherdata.ConvectiveOutlookDiscussion{}}
+	derived, err = BuildDerived(BuildDerivedRequest{
+		Resolved:  resolved,
+		Timezone:  location.String(),
+		Dayparts:  testDayparts(),
+		Collected: BuildCollected(bundle),
+	})
+	if err != nil {
+		t.Fatalf("BuildDerived(checked empty source) error = %v", err)
+	}
+	if derived.SPCConvectiveOutlooks == nil || len(derived.SPCConvectiveOutlooks) != 0 {
+		t.Fatalf("checked empty outlooks = %#v, want non-nil empty slice", derived.SPCConvectiveOutlooks)
+	}
+	if derived.SPCConvectiveDiscussions == nil || len(derived.SPCConvectiveDiscussions) != 0 {
+		t.Fatalf("checked empty discussions = %#v, want non-nil empty slice", derived.SPCConvectiveDiscussions)
+	}
+}
+
 func testBundle(location *time.Location) *weatherdata.Bundle {
 	return &weatherdata.Bundle{
 		FetchedAt: mustParse("2026-05-29T10:00:00Z"),
@@ -193,6 +384,65 @@ func testBundle(location *time.Location) *weatherdata.Bundle {
 	}
 }
 
+func testConvectiveOutlookRun(location *time.Location) *weatherdata.ConvectiveOutlookRun {
+	rank1 := 1
+	rank2 := 2
+	rank3 := 3
+	rank4 := 4
+	rank5 := 5
+	return &weatherdata.ConvectiveOutlookRun{
+		Outlooks: []weatherdata.ConvectiveOutlook{
+			convectiveOutlook(location, "mon-outside", 4, "categorical", "MDT", &rank5, "2026-06-01T00:00:00-05:00", "2026-06-02T00:00:00-05:00"),
+			convectiveOutlook(location, "sun-slight", 3, "categorical", "SLGT", &rank3, "2026-05-31T06:00:00-05:00", "2026-06-01T00:00:00-05:00"),
+			convectiveOutlook(location, "fri-low", 1, "categorical", "MRGL", &rank1, "2026-05-29T06:00:00-05:00", "2026-05-29T12:00:00-05:00"),
+			convectiveOutlook(location, "fri-missing-rank", 1, "categorical", "GEN", nil, "2026-05-29T08:00:00-05:00", "2026-05-29T10:00:00-05:00"),
+			convectiveOutlook(location, "sat-enhanced", 2, "categorical", "ENH", &rank4, "2026-05-30T01:00:00-05:00", "2026-05-30T12:00:00-05:00"),
+			convectiveOutlook(location, "fri-high", 1, "categorical", "SLGT", &rank3, "2026-05-29T07:00:00-05:00", "2026-05-29T11:00:00-05:00"),
+			convectiveOutlook(location, "fri-probabilistic", 1, "probabilistic", "5%", &rank2, "2026-05-29T05:00:00-05:00", "2026-05-29T10:00:00-05:00"),
+			convectiveOutlook(location, "fri-storm", 1, "categorical", "SLGT", &rank2, "2026-05-29T12:00:00-05:00", "2026-05-29T13:00:00-05:00"),
+		},
+		Discussions: []weatherdata.ConvectiveOutlookDiscussion{
+			{Day: 4, Headline: "day4", UpdatedAt: ptrTime(mustParse("2026-05-31T10:00:00-05:00"))},
+			{Day: 1, Headline: "day1 late", UpdatedAt: ptrTime(mustParse("2026-05-29T09:00:00-05:00"))},
+			{Day: 3, Headline: "day3", UpdatedAt: ptrTime(mustParse("2026-05-31T08:00:00-05:00"))},
+			{Day: 1, Headline: "day1 early", UpdatedAt: ptrTime(mustParse("2026-05-29T08:00:00-05:00"))},
+			{Day: 2, Headline: "day2", UpdatedAt: ptrTime(mustParse("2026-05-30T08:00:00-05:00"))},
+		},
+	}
+}
+
+func convectiveOutlook(location *time.Location, id string, day int, outlookType string, label string, rank *int, validFrom string, validTo string) weatherdata.ConvectiveOutlook {
+	return weatherdata.ConvectiveOutlook{
+		ID:           id,
+		Day:          day,
+		OutlookType:  outlookType,
+		Label:        label,
+		SeverityRank: rank,
+		ValidFrom:    mustParse(validFrom).In(location),
+		ValidTo:      mustParse(validTo).In(location),
+	}
+}
+
+func outlookIDs(outlooks []weatherdata.ConvectiveOutlook) []string {
+	out := make([]string, 0, len(outlooks))
+	for _, outlook := range outlooks {
+		out = append(out, outlook.ID)
+	}
+	return out
+}
+
+func discussionHeadlines(discussions []weatherdata.ConvectiveOutlookDiscussion) []string {
+	out := make([]string, 0, len(discussions))
+	for _, discussion := range discussions {
+		out = append(out, discussion.Headline)
+	}
+	return out
+}
+
+func ptrTime(value time.Time) *time.Time {
+	return &value
+}
+
 func hour(location *time.Location, start string, end string, text string, precip float64, gust float64) weatherdata.ForecastPeriod {
 	temperature := 70.0
 	return weatherdata.ForecastPeriod{
@@ -215,7 +465,11 @@ func testDayparts() []forecast.DaypartDefinition {
 
 func resolveForTest(t *testing.T, id report.ID, now time.Time, location *time.Location) report.Resolved {
 	t.Helper()
-	resolved, err := report.Resolve(id, report.ResolveRequest{Now: now, Location: location})
+	req := report.ResolveRequest{Now: now, Location: location}
+	if id == report.Daily {
+		req.Date = now
+	}
+	resolved, err := report.Resolve(id, req)
 	if err != nil {
 		t.Fatalf("resolve %s: %v", id, err)
 	}

internal/forecast/derive.go

@@ -65,6 +65,7 @@ type AlertOverlap struct {
 	Period      timeutil.Period `json:"period"`
 	Overlap     timeutil.Period `json:"overlap"`
 	Description string          `json:"description,omitempty"`
+	Instruction string          `json:"instruction,omitempty"`
 }
 
 type PrecipTiming struct {
@@ -81,6 +82,7 @@ type PrecipitationWindow struct {
 	End                         *time.Time `json:"end,omitempty"`
 	MaxPrecipitationProbability TimedValue `json:"maxPrecipitationProbability"`
 	ProbabilityThreshold        float64    `json:"probabilityThreshold"`
+	TextDescriptions            []string   `json:"textDescriptions,omitempty"`
 }
 
 func BuildPrecipTiming(periods []weatherdata.ForecastPeriod) PrecipTiming {
@@ -114,6 +116,7 @@ func buildPrecipTimingWithThreshold(periods []weatherdata.ForecastPeriod, thresh
 			},
 			ProbabilityThreshold: threshold,
 		}
+		appendActiveTextDescription(active, forecastPeriod.TextDescription)
 		activeLastEnd = forecastPeriod.EndTime
 		if timing.FirstPrecipitation == nil {
 			timing.FirstPrecipitation = &TimedValue{
@@ -135,6 +138,8 @@ func buildPrecipTimingWithThreshold(periods []weatherdata.ForecastPeriod, thresh
 				if forecastPeriod.StartTime.After(activeLastEnd) {
 					closeActive()
 					startActive(forecastPeriod, probability)
+				} else {
+					appendActiveTextDescription(active, forecastPeriod.TextDescription)
 				}
 				if probability > active.MaxPrecipitationProbability.Value {
 					active.MaxPrecipitationProbability = TimedValue{
@@ -166,6 +171,17 @@ func buildPrecipTimingWithThreshold(periods []weatherdata.ForecastPeriod, thresh
 	return timing
 }
 
+func appendActiveTextDescription(window *PrecipitationWindow, text string) {
+	if window == nil {
+		return
+	}
+	text = strings.TrimSpace(text)
+	if text == "" {
+		return
+	}
+	window.TextDescriptions = append(window.TextDescriptions, text)
+}
+
 func BuildDailySummary(bundle *weatherdata.Bundle, date time.Time, location *time.Location, dayparts []DaypartDefinition) (*DailySummary, error) {
 	if bundle == nil {
 		return nil, fmt.Errorf("forecast bundle is required")
@@ -448,6 +464,7 @@ func AlertOverlaps(alertRun *weatherdata.AlertRun, period timeutil.Period) []Ale
 			Period:      alert.Period,
 			Overlap:     intersect(alert.Period, period),
 			Description: alert.Description,
+			Instruction: alert.Instruction,
 		})
 	}
 	sort.SliceStable(overlaps, func(i int, j int) bool {
@@ -461,6 +478,7 @@ type parsedAlert struct {
 	Headline    string
 	Severity    string
 	Description string
+	Instruction string
 	Period      timeutil.Period
 }
 
@@ -473,14 +491,19 @@ func parseAlert(raw json.RawMessage) (parsedAlert, bool) {
 		Event:       stringField(fields, "event"),
 		Headline:    firstStringField(fields, "headline", "title"),
 		Severity:    stringField(fields, "severity"),
-		Description: firstStringField(fields, "description", "instruction"),
+		Description: stringField(fields, "description"),
+		Instruction: collapseWhitespace(stringField(fields, "instruction")),
 	}
-	start, startOK := firstTimeField(fields, "effective", "onset", "startsAt", "startTime", "sent")
-	end, endOK := firstTimeField(fields, "expires", "ends", "endsAt", "endTime")
+	start, startOK := firstTimeField(fields, "onset", "startsAt", "startTime", "effective", "sent")
+	end, endOK := firstTimeField(fields, "ends", "endsAt", "endTime", "expires")
 	if !startOK || !endOK {
 		return parsedAlert{}, false
 	}
-	alert.Period = timeutil.Period{Start: start, End: end}
+	period := timeutil.Period{Start: start, End: end}
+	if !period.IsValid() {
+		return parsedAlert{}, false
+	}
+	alert.Period = period
 	return alert, true
 }
 
@@ -519,6 +542,10 @@ func firstTimeField(fields map[string]json.RawMessage, names ...string) (time.Ti
 	return time.Time{}, false
 }
 
+func collapseWhitespace(value string) string {
+	return strings.Join(strings.Fields(value), " ")
+}
+
 func intersect(left timeutil.Period, right timeutil.Period) timeutil.Period {
 	start := left.Start
 	if right.Start.After(start) {

internal/forecast/derive_test.go

@@ -210,6 +210,115 @@ func TestAlertOverlap(t *testing.T) {
 	}
 }
 
+func TestAlertOverlapUsesOnsetAndEnds(t *testing.T) {
+	raw := json.RawMessage(`{"event":"Wind Advisory","headline":"Wind Advisory issued June 16 at 12:39PM CDT until June 17 at 8:00PM CDT by NWS St Louis MO","severity":"Moderate","description":"Southwest winds 20 to 30 mph with gusts up to 45 mph expected.","instruction":"Secure outdoor objects.\n\nUse  extra\tcaution.","effective":"2026-06-16T17:39:00Z","onset":"2026-06-17T18:00:00Z","ends":"2026-06-18T01:00:00Z","expires":"2026-06-17T08:45:00Z"}`)
+	alertRun := &weatherdata.AlertRun{Alerts: []json.RawMessage{raw}}
+	period := timeutil.Period{
+		Start: mustParse("2026-06-17T12:00:00-05:00"),
+		End:   mustParse("2026-06-17T21:00:00-05:00"),
+	}
+
+	overlaps := AlertOverlaps(alertRun, period)
+	if len(overlaps) != 1 {
+		t.Fatalf("overlaps length = %d, want 1", len(overlaps))
+	}
+	if overlaps[0].Period.Start.Format(time.RFC3339) != "2026-06-17T18:00:00Z" {
+		t.Fatalf("alert period start = %s, want onset", overlaps[0].Period.Start.Format(time.RFC3339))
+	}
+	if overlaps[0].Period.End.Format(time.RFC3339) != "2026-06-18T01:00:00Z" {
+		t.Fatalf("alert period end = %s, want ends", overlaps[0].Period.End.Format(time.RFC3339))
+	}
+	if overlaps[0].Overlap.Start.Format(time.RFC3339) != "2026-06-17T18:00:00Z" {
+		t.Fatalf("overlap start = %s, want onset", overlaps[0].Overlap.Start.Format(time.RFC3339))
+	}
+	if overlaps[0].Overlap.End.Format(time.RFC3339) != "2026-06-18T01:00:00Z" {
+		t.Fatalf("overlap end = %s, want alert ends", overlaps[0].Overlap.End.Format(time.RFC3339))
+	}
+	if overlaps[0].Description != "Southwest winds 20 to 30 mph with gusts up to 45 mph expected." {
+		t.Fatalf("Description = %q, want preserved description", overlaps[0].Description)
+	}
+	if overlaps[0].Instruction != "Secure outdoor objects. Use extra caution." {
+		t.Fatalf("Instruction = %q, want preserved instruction", overlaps[0].Instruction)
+	}
+}
+
+func TestCollapseWhitespace(t *testing.T) {
+	tests := []struct {
+		name  string
+		value string
+		want  string
+	}{
+		{name: "newlines", value: "Secure outdoor objects.\nUse extra caution.", want: "Secure outdoor objects. Use extra caution."},
+		{name: "crlf", value: "Secure outdoor objects.\r\nUse extra caution.", want: "Secure outdoor objects. Use extra caution."},
+		{name: "tabs and repeated spaces", value: "Secure\toutdoor   objects.", want: "Secure outdoor objects."},
+		{name: "leading trailing", value: "  Secure outdoor objects.  ", want: "Secure outdoor objects."},
+		{name: "empty", value: "", want: ""},
+		{name: "all whitespace", value: " \n\t\r\n ", want: ""},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := collapseWhitespace(tt.value); got != tt.want {
+				t.Fatalf("collapseWhitespace(%q) = %q, want %q", tt.value, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestAlertOverlapUsesOnsetAndEndsForLocalDateRelevance(t *testing.T) {
+	location, err := time.LoadLocation("America/Chicago")
+	if err != nil {
+		t.Fatalf("load location: %v", err)
+	}
+	raw := json.RawMessage(`{"event":"Wind Advisory","headline":"Wind Advisory issued June 16 at 12:39PM CDT until June 17 at 8:00PM CDT by NWS St Louis MO","severity":"Moderate","effective":"2026-06-16T17:39:00Z","onset":"2026-06-17T18:00:00Z","ends":"2026-06-18T01:00:00Z","expires":"2026-06-17T08:45:00Z"}`)
+	alertRun := &weatherdata.AlertRun{Alerts: []json.RawMessage{raw}}
+	june16 := timeutil.CivilDay(time.Date(2026, 6, 16, 12, 0, 0, 0, location), location)
+	june17Afternoon := timeutil.Period{
+		Start: time.Date(2026, 6, 17, 12, 0, 0, 0, location),
+		End:   time.Date(2026, 6, 17, 21, 0, 0, 0, location),
+	}
+
+	if overlaps := AlertOverlaps(alertRun, june16); len(overlaps) != 0 {
+		t.Fatalf("June 16 overlaps length = %d, want none: %#v", len(overlaps), overlaps)
+	}
+	if overlaps := AlertOverlaps(alertRun, june17Afternoon); len(overlaps) != 1 {
+		t.Fatalf("June 17 afternoon overlaps length = %d, want 1: %#v", len(overlaps), overlaps)
+	}
+}
+
+func TestAlertOverlapSupportsOlderEffectiveExpiresPayload(t *testing.T) {
+	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 := &weatherdata.AlertRun{Alerts: []json.RawMessage{raw}}
+	period := timeutil.Period{
+		Start: mustParse("2026-05-29T06:00:00-05:00"),
+		End:   mustParse("2026-05-29T11:00:00-05:00"),
+	}
+
+	overlaps := AlertOverlaps(alertRun, period)
+	if len(overlaps) != 1 {
+		t.Fatalf("overlaps length = %d, want 1", len(overlaps))
+	}
+	if overlaps[0].Period.Start.Format(time.RFC3339) != "2026-05-29T07:00:00-05:00" {
+		t.Fatalf("alert period start = %s, want effective fallback", overlaps[0].Period.Start.Format(time.RFC3339))
+	}
+	if overlaps[0].Period.End.Format(time.RFC3339) != "2026-05-29T10:00:00-05:00" {
+		t.Fatalf("alert period end = %s, want expires fallback", overlaps[0].Period.End.Format(time.RFC3339))
+	}
+}
+
+func TestAlertOverlapSkipsInvalidSelectedPeriod(t *testing.T) {
+	raw := json.RawMessage(`{"event":"Wind Advisory","headline":"Invalid event period","severity":"Moderate","onset":"2026-06-17T18:00:00Z","ends":"2026-06-17T08:45:00Z"}`)
+	alertRun := &weatherdata.AlertRun{Alerts: []json.RawMessage{raw}}
+	period := timeutil.Period{
+		Start: mustParse("2026-06-17T00:00:00Z"),
+		End:   mustParse("2026-06-18T00:00:00Z"),
+	}
+
+	if overlaps := AlertOverlaps(alertRun, period); len(overlaps) != 0 {
+		t.Fatalf("overlaps length = %d, want invalid alert skipped: %#v", len(overlaps), overlaps)
+	}
+}
+
 func TestBuildPrecipTimingBuildsThresholdWindows(t *testing.T) {
 	location := time.FixedZone("Test", -5*60*60)
 	periods := []weatherdata.ForecastPeriod{
@@ -245,10 +354,16 @@ func TestBuildPrecipTimingBuildsThresholdWindows(t *testing.T) {
 	if first.MaxPrecipitationProbability.Value != 60 || first.MaxPrecipitationProbability.Time.Format(time.RFC3339) != "2026-05-29T10:00:00-05:00" {
 		t.Fatalf("first window max = %#v, want 60 at 10 AM", first.MaxPrecipitationProbability)
 	}
+	if len(first.TextDescriptions) != 2 || first.TextDescriptions[0] != "Showers" || first.TextDescriptions[1] != "Rain likely" {
+		t.Fatalf("first window text descriptions = %#v, want contributing hourly descriptions", first.TextDescriptions)
+	}
 	second := timing.PrecipitationWindows[1]
 	if second.Start.Format(time.RFC3339) != "2026-05-29T12:00:00-05:00" || second.End == nil || second.End.Format(time.RFC3339) != "2026-05-29T13:00:00-05:00" {
 		t.Fatalf("second window = %#v, want noon-1 PM", second)
 	}
+	if len(second.TextDescriptions) != 1 || second.TextDescriptions[0] != "Thunderstorms" {
+		t.Fatalf("second window text descriptions = %#v, want thunderstorm description", second.TextDescriptions)
+	}
 	if !timing.ThunderMentioned {
 		t.Fatal("ThunderMentioned = false, want true")
 	}

internal/generatedtext/catalog.go

@@ -0,0 +1,195 @@
+package generatedtext
+
+import (
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/briefing"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/facts"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/module"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/reporttemplate"
+)
+
+const (
+	schemaIDHourly   = "hourly"
+	schemaIDDaily    = "daily"
+	schemaIDToday    = "today"
+	schemaIDTomorrow = "tomorrow"
+
+	templateIDHourly   = "hourly"
+	templateIDDaily    = "daily"
+	templateIDToday    = "today"
+	templateIDTomorrow = "tomorrow"
+)
+
+type validator func([]byte) (any, []byte, error)
+
+type renderContextBuilder func(report.ID, string, briefing.Metadata, module.Snapshot, facts.CollectedFacts, facts.DerivedFacts, any) (any, error)
+
+type catalogEntry struct {
+	schemaID             string
+	templateID           string
+	validate             validator
+	renderContextBuilder renderContextBuilder
+}
+
+type Handler struct {
+	reportID             report.ID
+	schemaID             string
+	templateID           string
+	validate             validator
+	renderContextBuilder renderContextBuilder
+}
+
+var catalog = []catalogEntry{
+	{
+		schemaID:             schemaIDHourly,
+		templateID:           templateIDHourly,
+		validate:             validateHourly,
+		renderContextBuilder: buildHourlyContext,
+	},
+	{
+		schemaID:             schemaIDDaily,
+		templateID:           templateIDDaily,
+		validate:             validateDaily,
+		renderContextBuilder: buildDailyContext,
+	},
+	{
+		schemaID:             schemaIDToday,
+		templateID:           templateIDToday,
+		validate:             validateToday,
+		renderContextBuilder: buildTodayContext,
+	},
+	{
+		schemaID:             schemaIDTomorrow,
+		templateID:           templateIDTomorrow,
+		validate:             validateTomorrow,
+		renderContextBuilder: buildTomorrowContext,
+	},
+}
+
+func LookupDefinition(definition report.Definition) (Handler, error) {
+	if definition.GenerationMode != report.GenerationModeGeneratedTextTemplate {
+		return Handler{}, fmt.Errorf("report %q uses generation mode %q, not %q", definition.ID, definition.GenerationMode, report.GenerationModeGeneratedTextTemplate)
+	}
+
+	var schemaKnown, templateKnown bool
+	for _, entry := range catalog {
+		if entry.schemaID == definition.GeneratedTextSchemaID {
+			schemaKnown = true
+		}
+		if entry.templateID == definition.TemplateID {
+			templateKnown = true
+		}
+		if entry.schemaID == definition.GeneratedTextSchemaID && entry.templateID == definition.TemplateID {
+			return Handler{
+				reportID:             definition.ID,
+				schemaID:             entry.schemaID,
+				templateID:           entry.templateID,
+				validate:             entry.validate,
+				renderContextBuilder: entry.renderContextBuilder,
+			}, nil
+		}
+	}
+	if !schemaKnown {
+		return Handler{}, fmt.Errorf("generated text schema %q is not supported for report %q", definition.GeneratedTextSchemaID, definition.ID)
+	}
+	if !templateKnown {
+		return Handler{}, fmt.Errorf("report template %q is not supported for report %q", definition.TemplateID, definition.ID)
+	}
+	return Handler{}, fmt.Errorf("generated text schema %q and report template %q are not supported together for report %q", definition.GeneratedTextSchemaID, definition.TemplateID, definition.ID)
+}
+
+func (h Handler) SchemaID() string {
+	return h.schemaID
+}
+
+func (h Handler) TemplateID() string {
+	return h.templateID
+}
+
+func (h Handler) Schema() ([]byte, error) {
+	data, err := reporttemplate.Schema(h.schemaID)
+	if err != nil {
+		return nil, fmt.Errorf("load generated text schema %q for report %q: %w", h.schemaID, h.reportID, err)
+	}
+	return data, nil
+}
+
+func (h Handler) Template() (string, error) {
+	source, err := reporttemplate.Template(h.templateID)
+	if err != nil {
+		return "", fmt.Errorf("load report template %q for report %q: %w", h.templateID, h.reportID, err)
+	}
+	return source, nil
+}
+
+func (h Handler) Validate(data []byte) (any, []byte, error) {
+	if h.validate == nil {
+		return nil, nil, fmt.Errorf("generated text validator is not registered for schema %q on report %q", h.schemaID, h.reportID)
+	}
+	return h.validate(data)
+}
+
+func (h Handler) BuildRenderContext(metadata briefing.Metadata, snapshot module.Snapshot, collected facts.CollectedFacts, derived facts.DerivedFacts, generated any) (any, error) {
+	if h.renderContextBuilder == nil {
+		return nil, fmt.Errorf("render-context builder is not registered for template %q on report %q", h.templateID, h.reportID)
+	}
+	return h.renderContextBuilder(h.reportID, h.templateID, metadata, snapshot, collected, derived, generated)
+}
+
+func (h Handler) Render(data any) ([]byte, error) {
+	rendered, err := reporttemplate.Render(h.templateID, data)
+	if err != nil {
+		return nil, fmt.Errorf("render report template %q for report %q: %w", h.templateID, h.reportID, err)
+	}
+	return rendered, nil
+}
+
+func validateHourly(data []byte) (any, []byte, error) {
+	return ValidateHourly(data)
+}
+
+func validateDaily(data []byte) (any, []byte, error) {
+	return ValidateDaily(data)
+}
+
+func validateToday(data []byte) (any, []byte, error) {
+	return ValidateToday(data)
+}
+
+func validateTomorrow(data []byte) (any, []byte, error) {
+	return ValidateTomorrow(data)
+}
+
+func buildHourlyContext(reportID report.ID, templateID string, metadata briefing.Metadata, snapshot module.Snapshot, collected facts.CollectedFacts, derived facts.DerivedFacts, generated any) (any, error) {
+	hourly, ok := generated.(Hourly)
+	if !ok {
+		return nil, fmt.Errorf("report template %q requires hourly generated text for report %q", templateID, reportID)
+	}
+	return BuildHourlyRenderContext(metadata, snapshot, hourly, collected, derived)
+}
+
+func buildDailyContext(reportID report.ID, templateID string, metadata briefing.Metadata, snapshot module.Snapshot, collected facts.CollectedFacts, derived facts.DerivedFacts, generated any) (any, error) {
+	daily, ok := generated.(Daily)
+	if !ok {
+		return nil, fmt.Errorf("report template %q requires daily generated text for report %q", templateID, reportID)
+	}
+	return BuildDailyRenderContext(metadata, snapshot, daily, collected, derived)
+}
+
+func buildTodayContext(reportID report.ID, templateID string, metadata briefing.Metadata, snapshot module.Snapshot, collected facts.CollectedFacts, derived facts.DerivedFacts, generated any) (any, error) {
+	today, ok := generated.(Today)
+	if !ok {
+		return nil, fmt.Errorf("report template %q requires today generated text for report %q", templateID, reportID)
+	}
+	return BuildTodayRenderContext(metadata, snapshot, today, collected, derived)
+}
+
+func buildTomorrowContext(reportID report.ID, templateID string, metadata briefing.Metadata, snapshot module.Snapshot, collected facts.CollectedFacts, derived facts.DerivedFacts, generated any) (any, error) {
+	tomorrow, ok := generated.(Tomorrow)
+	if !ok {
+		return nil, fmt.Errorf("report template %q requires tomorrow generated text for report %q", templateID, reportID)
+	}
+	return BuildTomorrowRenderContext(metadata, snapshot, tomorrow, collected, derived)
+}

internal/generatedtext/catalog_test.go

@@ -0,0 +1,324 @@
+package generatedtext
+
+import (
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/weatherreporter/internal/report"
+)
+
+func TestCatalogCompleteForGeneratedTextTemplateReports(t *testing.T) {
+	for _, definition := range report.DefaultRegistry().All() {
+		if definition.GenerationMode != report.GenerationModeGeneratedTextTemplate {
+			continue
+		}
+		t.Run(string(definition.ID), func(t *testing.T) {
+			handler, err := LookupDefinition(definition)
+			if err != nil {
+				t.Fatalf("LookupDefinition() error = %v", err)
+			}
+			if handler.SchemaID() != definition.GeneratedTextSchemaID {
+				t.Fatalf("SchemaID() = %q, want %q", handler.SchemaID(), definition.GeneratedTextSchemaID)
+			}
+			if handler.TemplateID() != definition.TemplateID {
+				t.Fatalf("TemplateID() = %q, want %q", handler.TemplateID(), definition.TemplateID)
+			}
+			if handler.validate == nil {
+				t.Fatal("validator is nil")
+			}
+			if handler.renderContextBuilder == nil {
+				t.Fatal("render-context builder is nil")
+			}
+			if schema, err := handler.Schema(); err != nil {
+				t.Fatalf("Schema() error = %v", err)
+			} else if len(schema) == 0 {
+				t.Fatal("Schema() returned empty asset")
+			}
+			if template, err := handler.Template(); err != nil {
+				t.Fatalf("Template() error = %v", err)
+			} else if template == "" {
+				t.Fatal("Template() returned empty asset")
+			}
+		})
+	}
+}
+
+func TestCatalogLookupRejectsUnsupportedSchemaAndTemplate(t *testing.T) {
+	tests := []struct {
+		name       string
+		definition report.Definition
+		want       []string
+	}{
+		{
+			name: "schema",
+			definition: func() report.Definition {
+				definition := report.DefaultRegistry().MustLookup(report.Hourly)
+				definition.GeneratedTextSchemaID = "missing-schema"
+				return definition
+			}(),
+			want: []string{`generated text schema "missing-schema"`, `report "hourly"`},
+		},
+		{
+			name: "template",
+			definition: func() report.Definition {
+				definition := report.DefaultRegistry().MustLookup(report.Hourly)
+				definition.TemplateID = "missing-template"
+				return definition
+			}(),
+			want: []string{`report template "missing-template"`, `report "hourly"`},
+		},
+		{
+			name: "combination",
+			definition: func() report.Definition {
+				definition := report.DefaultRegistry().MustLookup(report.Hourly)
+				definition.TemplateID = "tomorrow"
+				return definition
+			}(),
+			want: []string{`generated text schema "hourly"`, `report template "tomorrow"`, `report "hourly"`},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			_, err := LookupDefinition(test.definition)
+			if err == nil {
+				t.Fatal("LookupDefinition() error = nil, want error")
+			}
+			for _, want := range test.want {
+				if !strings.Contains(err.Error(), want) {
+					t.Fatalf("LookupDefinition() error = %v, want %q", err, want)
+				}
+			}
+		})
+	}
+}
+
+func TestCatalogLookupSupportsTodayDefinition(t *testing.T) {
+	definition := report.Definition{
+		ID:                    report.Today,
+		GenerationMode:        report.GenerationModeGeneratedTextTemplate,
+		GeneratedTextSchemaID: "today",
+		TemplateID:            "today",
+	}
+	handler, err := LookupDefinition(definition)
+	if err != nil {
+		t.Fatalf("LookupDefinition(today) error = %v", err)
+	}
+	if handler.SchemaID() != "today" || handler.TemplateID() != "today" {
+		t.Fatalf("handler IDs = %q/%q, want today/today", handler.SchemaID(), handler.TemplateID())
+	}
+	if schema, err := handler.Schema(); err != nil {
+		t.Fatalf("Schema() error = %v", err)
+	} else if len(schema) == 0 {
+		t.Fatal("Schema() returned empty asset")
+	}
+	if template, err := handler.Template(); err != nil {
+		t.Fatalf("Template() error = %v", err)
+	} else if !strings.Contains(template, "# {{ .Report.Title }}") {
+		t.Fatalf("Template() = %q, want Today template source", template)
+	}
+}
+
+func TestCatalogLookupSupportsDailyDefinitionAssets(t *testing.T) {
+	definition := report.Definition{
+		ID:                    report.Daily,
+		GenerationMode:        report.GenerationModeGeneratedTextTemplate,
+		GeneratedTextSchemaID: "daily",
+		TemplateID:            "daily",
+	}
+	handler, err := LookupDefinition(definition)
+	if err != nil {
+		t.Fatalf("LookupDefinition(daily) error = %v", err)
+	}
+	if handler.SchemaID() != "daily" || handler.TemplateID() != "daily" {
+		t.Fatalf("handler IDs = %q/%q, want daily/daily", handler.SchemaID(), handler.TemplateID())
+	}
+	if schema, err := handler.Schema(); err != nil {
+		t.Fatalf("Schema() error = %v", err)
+	} else if len(schema) == 0 {
+		t.Fatal("Schema() returned empty asset")
+	}
+	if template, err := handler.Template(); err != nil {
+		t.Fatalf("Template() error = %v", err)
+	} else if !strings.Contains(template, "# {{ .Report.Title }}") {
+		t.Fatalf("Template() = %q, want Daily template source", template)
+	}
+}
+
+func TestCatalogValidationDispatchSupportsKnownSchemas(t *testing.T) {
+	hourlyHandler, err := LookupDefinition(report.DefaultRegistry().MustLookup(report.Hourly))
+	if err != nil {
+		t.Fatalf("LookupDefinition(hourly) error = %v", err)
+	}
+	hourly, normalized, err := hourlyHandler.Validate([]byte(`{
+		"summary": " Storm chances increase. ",
+		"forecast_discussion": " A front will keep the region unsettled. "
+	}`))
+	if err != nil {
+		t.Fatalf("Validate(hourly) error = %v", err)
+	}
+	if _, ok := hourly.(Hourly); !ok {
+		t.Fatalf("hourly generated text type = %T, want generatedtext.Hourly", hourly)
+	}
+	if !strings.Contains(string(normalized), `"summary":"Storm chances increase."`) {
+		t.Fatalf("hourly normalized text = %s, want trimmed summary", normalized)
+	}
+
+	tomorrowHandler, err := LookupDefinition(report.DefaultRegistry().MustLookup(report.Tomorrow))
+	if err != nil {
+		t.Fatalf("LookupDefinition(tomorrow) error = %v", err)
+	}
+	tomorrow, normalized, err := tomorrowHandler.Validate([]byte(`{
+		"summary": " Storms become more likely tomorrow. ",
+		"forecast_discussion": [" A front will keep showers in the forecast. ", ""]
+	}`))
+	if err != nil {
+		t.Fatalf("Validate(tomorrow) error = %v", err)
+	}
+	if _, ok := tomorrow.(Tomorrow); !ok {
+		t.Fatalf("tomorrow generated text type = %T, want generatedtext.Tomorrow", tomorrow)
+	}
+	if !strings.Contains(string(normalized), `"forecast_discussion":["A front will keep showers in the forecast."]`) {
+		t.Fatalf("tomorrow normalized text = %s, want trimmed discussion paragraph", normalized)
+	}
+
+	todayHandler, err := LookupDefinition(report.Definition{
+		ID:                    report.Today,
+		GenerationMode:        report.GenerationModeGeneratedTextTemplate,
+		GeneratedTextSchemaID: "today",
+		TemplateID:            "today",
+	})
+	if err != nil {
+		t.Fatalf("LookupDefinition(today) error = %v", err)
+	}
+	today, normalized, err := todayHandler.Validate([]byte(`{
+		"summary": " Showers are likely today. ",
+		"forecast_discussion": [" A front will keep rain chances elevated. ", ""]
+	}`))
+	if err != nil {
+		t.Fatalf("Validate(today) error = %v", err)
+	}
+	if _, ok := today.(Today); !ok {
+		t.Fatalf("today generated text type = %T, want generatedtext.Today", today)
+	}
+	if !strings.Contains(string(normalized), `"forecast_discussion":["A front will keep rain chances elevated."]`) {
+		t.Fatalf("today normalized text = %s, want trimmed discussion paragraph", normalized)
+	}
+
+	dailyHandler, err := LookupDefinition(report.Definition{
+		ID:                    report.Daily,
+		GenerationMode:        report.GenerationModeGeneratedTextTemplate,
+		GeneratedTextSchemaID: "daily",
+		TemplateID:            "daily",
+	})
+	if err != nil {
+		t.Fatalf("LookupDefinition(daily) error = %v", err)
+	}
+	daily, normalized, err := dailyHandler.Validate([]byte(`{
+		"summary": " Showers are possible during the selected day. ",
+		"forecast_discussion": [" A front will keep rain chances in the forecast. ", ""]
+	}`))
+	if err != nil {
+		t.Fatalf("Validate(daily) error = %v", err)
+	}
+	if _, ok := daily.(Daily); !ok {
+		t.Fatalf("daily generated text type = %T, want generatedtext.Daily", daily)
+	}
+	if !strings.Contains(string(normalized), `"forecast_discussion":["A front will keep rain chances in the forecast."]`) {
+		t.Fatalf("daily normalized text = %s, want trimmed discussion paragraph", normalized)
+	}
+}
+
+func TestCatalogBuildRenderContextRejectsMismatchedGeneratedText(t *testing.T) {
+	hourlyHandler, err := LookupDefinition(report.DefaultRegistry().MustLookup(report.Hourly))
+	if err != nil {
+		t.Fatalf("LookupDefinition(hourly) error = %v", err)
+	}
+	_, err = hourlyHandler.BuildRenderContext(testMetadata(), testSnapshot(t), testCollected(), testDerived(), Tomorrow{
+		Summary:            "Storms become more likely tomorrow.",
+		ForecastDiscussion: []string{"A front will keep showers in the forecast."},
+	})
+	if err == nil {
+		t.Fatal("BuildRenderContext(hourly) error = nil, want type mismatch")
+	}
+	if !strings.Contains(err.Error(), `requires hourly generated text`) {
+		t.Fatalf("BuildRenderContext(hourly) error = %v, want hourly generated text requirement", err)
+	}
+
+	tomorrowHandler, err := LookupDefinition(report.DefaultRegistry().MustLookup(report.Tomorrow))
+	if err != nil {
+		t.Fatalf("LookupDefinition(tomorrow) error = %v", err)
+	}
+	_, err = tomorrowHandler.BuildRenderContext(testTomorrowMetadata(), testTomorrowSnapshot(t), testCollected(), testTomorrowDerived(), Hourly{
+		Summary:            "Storm chances increase.",
+		ForecastDiscussion: "A front will keep showers in the forecast.",
+	})
+	if err == nil {
+		t.Fatal("BuildRenderContext(tomorrow) error = nil, want type mismatch")
+	}
+	if !strings.Contains(err.Error(), `requires tomorrow generated text`) {
+		t.Fatalf("BuildRenderContext(tomorrow) error = %v, want tomorrow generated text requirement", err)
+	}
+
+	todayHandler, err := LookupDefinition(report.Definition{
+		ID:                    report.Today,
+		GenerationMode:        report.GenerationModeGeneratedTextTemplate,
+		GeneratedTextSchemaID: "today",
+		TemplateID:            "today",
+	})
+	if err != nil {
+		t.Fatalf("LookupDefinition(today) error = %v", err)
+	}
+	_, err = todayHandler.BuildRenderContext(testTodayMetadata(), testTodaySnapshot(t), testCollected(), testTodayDerived(), Tomorrow{
+		Summary:            "Storms become more likely tomorrow.",
+		ForecastDiscussion: []string{"A front will keep showers in the forecast."},
+	})
+	if err == nil {
+		t.Fatal("BuildRenderContext(today) error = nil, want type mismatch")
+	}
+	if !strings.Contains(err.Error(), `requires today generated text`) {
+		t.Fatalf("BuildRenderContext(today) error = %v, want today generated text requirement", err)
+	}
+
+	dailyHandler, err := LookupDefinition(report.Definition{
+		ID:                    report.Daily,
+		GenerationMode:        report.GenerationModeGeneratedTextTemplate,
+		GeneratedTextSchemaID: "daily",
+		TemplateID:            "daily",
+	})
+	if err != nil {
+		t.Fatalf("LookupDefinition(daily) error = %v", err)
+	}
+	_, err = dailyHandler.BuildRenderContext(testDailyMetadata(), testDailySnapshot(t), testCollected(), testDailyDerived(), Tomorrow{
+		Summary:            "Storms become more likely tomorrow.",
+		ForecastDiscussion: []string{"A front will keep showers in the forecast."},
+	})
+	if err == nil {
+		t.Fatal("BuildRenderContext(daily) error = nil, want type mismatch")
+	}
+	if !strings.Contains(err.Error(), `requires daily generated text`) {
+		t.Fatalf("BuildRenderContext(daily) error = %v, want daily generated text requirement", err)
+	}
+}
+
+func TestCatalogBuildRenderContextSupportsDaily(t *testing.T) {
+	handler, err := LookupDefinition(report.Definition{
+		ID:                    report.Daily,
+		GenerationMode:        report.GenerationModeGeneratedTextTemplate,
+		GeneratedTextSchemaID: "daily",
+		TemplateID:            "daily",
+	})
+	if err != nil {
+		t.Fatalf("LookupDefinition(daily) error = %v", err)
+	}
+	ctx, err := handler.BuildRenderContext(testDailyMetadata(), testDailySnapshot(t), testCollected(), testDailyDerived(), Daily{
+		Summary:            "Showers are possible during the selected day.",
+		ForecastDiscussion: []string{"A front will keep rain chances in the forecast."},
+	})
+	if err != nil {
+		t.Fatalf("BuildRenderContext(daily) error = %v", err)
+	}
+	if _, ok := ctx.(DailyRenderContext); !ok {
+		t.Fatalf("BuildRenderContext(daily) = %T, want DailyRenderContext", ctx)
+	}
+}

internal/generatedtext/daily.go

@@ -0,0 +1,28 @@
+package generatedtext
+
+type Daily struct {
+	Summary             string   `json:"summary"`
+	ForecastDiscussion  []string `json:"forecast_discussion"`
+	PrecipitationTiming string   `json:"precipitation_timing,omitempty"`
+	Confidence          string   `json:"confidence,omitempty"`
+}
+
+func ValidateDaily(data []byte) (Daily, []byte, error) {
+	return validateDayStyleGeneratedText[Daily, *Daily](data, "daily")
+}
+
+func (d *Daily) dayStyleFields() dayStyleFields {
+	return dayStyleFields{
+		Summary:             d.Summary,
+		ForecastDiscussion:  d.ForecastDiscussion,
+		PrecipitationTiming: d.PrecipitationTiming,
+		Confidence:          d.Confidence,
+	}
+}
+
+func (d *Daily) setDayStyleFields(fields dayStyleFields) {
+	d.Summary = fields.Summary
+	d.ForecastDiscussion = fields.ForecastDiscussion
+	d.PrecipitationTiming = fields.PrecipitationTiming
+	d.Confidence = fields.Confidence
+}

internal/generatedtext/daily_test.go

@@ -0,0 +1,111 @@
+package generatedtext
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestValidateDailyNormalizesJSON(t *testing.T) {
+	value, normalized, err := ValidateDaily([]byte(`{
+		"summary": " Showers are possible during the selected day. ",
+		"forecast_discussion": [
+			"  A front will keep rain chances in the forecast. ",
+			"",
+			"  Temperatures stay seasonable by afternoon. "
+		],
+		"precipitation_timing": " Rain is most likely during the afternoon. ",
+		"confidence": " Medium "
+	}`))
+	if err != nil {
+		t.Fatalf("ValidateDaily() error = %v", err)
+	}
+	if value.Summary != "Showers are possible during the selected day." {
+		t.Fatalf("Summary = %q, want trimmed summary", value.Summary)
+	}
+	if strings.Join(value.ForecastDiscussion, "|") != "A front will keep rain chances in the forecast.|Temperatures stay seasonable by afternoon." {
+		t.Fatalf("ForecastDiscussion = %#v, want trimmed non-empty paragraphs", value.ForecastDiscussion)
+	}
+	if value.PrecipitationTiming != "Rain is most likely during the afternoon." {
+		t.Fatalf("PrecipitationTiming = %q, want trimmed precipitation timing", value.PrecipitationTiming)
+	}
+	want := `{"summary":"Showers are possible during the selected day.","forecast_discussion":["A front will keep rain chances in the forecast.","Temperatures stay seasonable by afternoon."],"precipitation_timing":"Rain is most likely during the afternoon.","confidence":"Medium"}`
+	if string(normalized) != want {
+		t.Fatalf("normalized = %s, want %s", normalized, want)
+	}
+}
+
+func TestValidateDailyOmitsEmptyOptionalFields(t *testing.T) {
+	_, normalized, err := ValidateDaily([]byte(`{
+		"summary": "Showers are possible during the selected day.",
+		"forecast_discussion": ["A front will keep rain chances in the forecast."],
+		"precipitation_timing": "   ",
+		"confidence": "   "
+	}`))
+	if err != nil {
+		t.Fatalf("ValidateDaily() error = %v", err)
+	}
+	want := `{"summary":"Showers are possible during the selected day.","forecast_discussion":["A front will keep rain chances in the forecast."]}`
+	if string(normalized) != want {
+		t.Fatalf("normalized = %s, want %s", normalized, want)
+	}
+}
+
+func TestValidateDailyRejectsInvalidInput(t *testing.T) {
+	tests := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{
+			name: "malformed",
+			in:   `{`,
+			want: "decode daily generated text",
+		},
+		{
+			name: "unknown field",
+			in:   `{"summary":"Showers are possible during the selected day.","forecast_discussion":["A front will keep rain chances in the forecast."],"extra":"value"}`,
+			want: `unknown field "extra"`,
+		},
+		{
+			name: "missing summary",
+			in:   `{"forecast_discussion":["A front will keep rain chances in the forecast."]}`,
+			want: "summary is required",
+		},
+		{
+			name: "blank summary",
+			in:   `{"summary":"  ","forecast_discussion":["A front will keep rain chances in the forecast."]}`,
+			want: "summary is required",
+		},
+		{
+			name: "missing forecast discussion",
+			in:   `{"summary":"Showers are possible during the selected day."}`,
+			want: "forecast discussion is required",
+		},
+		{
+			name: "blank forecast discussion",
+			in:   `{"summary":"Showers are possible during the selected day.","forecast_discussion":["  ",""]}`,
+			want: "forecast discussion is required",
+		},
+		{
+			name: "forecast discussion wrong type",
+			in:   `{"summary":"Showers are possible during the selected day.","forecast_discussion":"A front will keep rain chances in the forecast."}`,
+			want: "cannot unmarshal string",
+		},
+		{
+			name: "multiple values",
+			in:   `{"summary":"Showers are possible during the selected day.","forecast_discussion":["A front will keep rain chances in the forecast."]} {}`,
+			want: "multiple JSON values",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			_, _, err := ValidateDaily([]byte(test.in))
+			if err == nil {
+				t.Fatal("ValidateDaily() error = nil, want error")
+			}
+			if !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("ValidateDaily() error = %v, want %q", err, test.want)
+			}
+		})
+	}
+}

internal/generatedtext/day_style.go

@@ -0,0 +1,63 @@
+package generatedtext
+
+import (
+	"fmt"
+	"strings"
+)
+
+type dayStyleFields struct {
+	Summary             string
+	ForecastDiscussion  []string
+	PrecipitationTiming string
+	Confidence          string
+}
+
+type dayStyleGeneratedText interface {
+	dayStyleFields() dayStyleFields
+	setDayStyleFields(dayStyleFields)
+}
+
+func validateDayStyleGeneratedText[T any, PT interface {
+	*T
+	dayStyleGeneratedText
+}](data []byte, name string) (T, []byte, error) {
+	value, err := decodeGeneratedText[T](data, name)
+	if err != nil {
+		var zero T
+		return zero, nil, err
+	}
+
+	pointer := PT(&value)
+	fields := pointer.dayStyleFields()
+	fields.Summary = strings.TrimSpace(fields.Summary)
+	fields.PrecipitationTiming = strings.TrimSpace(fields.PrecipitationTiming)
+	fields.Confidence = strings.TrimSpace(fields.Confidence)
+	fields.ForecastDiscussion = trimNonEmpty(fields.ForecastDiscussion)
+	if fields.Summary == "" {
+		var zero T
+		return zero, nil, fmt.Errorf("%s generated text summary is required", name)
+	}
+	if len(fields.ForecastDiscussion) == 0 {
+		var zero T
+		return zero, nil, fmt.Errorf("%s generated text forecast discussion is required", name)
+	}
+	pointer.setDayStyleFields(fields)
+
+	normalized, err := normalizeGeneratedText(value, name)
+	if err != nil {
+		var zero T
+		return zero, nil, err
+	}
+	return value, normalized, nil
+}
+
+func trimNonEmpty(values []string) []string {
+	out := make([]string, 0, len(values))
+	for _, value := range values {
+		trimmed := strings.TrimSpace(value)
+		if trimmed != "" {
+			out = append(out, trimmed)
+		}
+	}
+	return out
+}

internal/generatedtext/day_style_test.go

@@ -0,0 +1,131 @@
+package generatedtext
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+)
+
+func TestValidateDayStyleGeneratedTextSharedBehavior(t *testing.T) {
+	reports := []struct {
+		name     string
+		validate func([]byte) (any, []byte, error)
+	}{
+		{
+			name: "daily",
+			validate: func(data []byte) (any, []byte, error) {
+				value, normalized, err := ValidateDaily(data)
+				return value, normalized, err
+			},
+		},
+		{
+			name: "today",
+			validate: func(data []byte) (any, []byte, error) {
+				value, normalized, err := ValidateToday(data)
+				return value, normalized, err
+			},
+		},
+		{
+			name: "tomorrow",
+			validate: func(data []byte) (any, []byte, error) {
+				value, normalized, err := ValidateTomorrow(data)
+				return value, normalized, err
+			},
+		},
+	}
+
+	for _, report := range reports {
+		t.Run(report.name, func(t *testing.T) {
+			t.Run("requires summary", func(t *testing.T) {
+				_, _, err := report.validate([]byte(`{"forecast_discussion":["First paragraph."]}`))
+				want := fmt.Sprintf("%s generated text summary is required", report.name)
+				if err == nil || err.Error() != want {
+					t.Fatalf("validate() error = %v, want %q", err, want)
+				}
+			})
+
+			t.Run("requires non-empty forecast discussion", func(t *testing.T) {
+				_, _, err := report.validate([]byte(`{"summary":"Shared summary.","forecast_discussion":["  ",""]}`))
+				want := fmt.Sprintf("%s generated text forecast discussion is required", report.name)
+				if err == nil || err.Error() != want {
+					t.Fatalf("validate() error = %v, want %q", err, want)
+				}
+			})
+
+			t.Run("trims and normalizes", func(t *testing.T) {
+				value, normalized, err := report.validate([]byte(`{
+					"summary": " Shared summary. ",
+					"forecast_discussion": [
+						" First paragraph. ",
+						"",
+						" Second paragraph. "
+					],
+					"precipitation_timing": " Afternoon. ",
+					"confidence": " Medium "
+				}`))
+				if err != nil {
+					t.Fatalf("validate() error = %v", err)
+				}
+				fields := dayStyleFieldsForTest(t, value)
+				if fields.Summary != "Shared summary." {
+					t.Fatalf("Summary = %q, want trimmed summary", fields.Summary)
+				}
+				if strings.Join(fields.ForecastDiscussion, "|") != "First paragraph.|Second paragraph." {
+					t.Fatalf("ForecastDiscussion = %#v, want trimmed non-empty paragraphs", fields.ForecastDiscussion)
+				}
+				if fields.PrecipitationTiming != "Afternoon." {
+					t.Fatalf("PrecipitationTiming = %q, want trimmed precipitation timing", fields.PrecipitationTiming)
+				}
+				if fields.Confidence != "Medium" {
+					t.Fatalf("Confidence = %q, want trimmed confidence", fields.Confidence)
+				}
+				want := `{"summary":"Shared summary.","forecast_discussion":["First paragraph.","Second paragraph."],"precipitation_timing":"Afternoon.","confidence":"Medium"}`
+				if string(normalized) != want {
+					t.Fatalf("normalized = %s, want %s", normalized, want)
+				}
+			})
+
+			t.Run("omits empty optional fields", func(t *testing.T) {
+				_, normalized, err := report.validate([]byte(`{
+					"summary": "Shared summary.",
+					"forecast_discussion": ["First paragraph."],
+					"precipitation_timing": "   ",
+					"confidence": "   "
+				}`))
+				if err != nil {
+					t.Fatalf("validate() error = %v", err)
+				}
+				want := `{"summary":"Shared summary.","forecast_discussion":["First paragraph."]}`
+				if string(normalized) != want {
+					t.Fatalf("normalized = %s, want %s", normalized, want)
+				}
+			})
+
+			t.Run("rejects unknown fields", func(t *testing.T) {
+				_, _, err := report.validate([]byte(`{"summary":"Shared summary.","forecast_discussion":["First paragraph."],"extra":"value"}`))
+				if err == nil {
+					t.Fatal("validate() error = nil, want error")
+				}
+				if !strings.Contains(err.Error(), `unknown field "extra"`) {
+					t.Fatalf("validate() error = %v, want unknown field error", err)
+				}
+			})
+		})
+	}
+}
+
+func dayStyleFieldsForTest(t *testing.T, value any) dayStyleFields {
+	t.Helper()
+
+	switch value := value.(type) {
+	case Daily:
+		return (&value).dayStyleFields()
+	case Today:
+		return (&value).dayStyleFields()
+	case Tomorrow:
+		return (&value).dayStyleFields()
+	default:
+		t.Fatalf("value type = %T, want day-style generated text", value)
+		return dayStyleFields{}
+	}
+}

internal/generatedtext/hourly.go

@@ -0,0 +1,38 @@
+// Package generatedtext validates structured LLM text and render contexts.
+package generatedtext
+
+import (
+	"fmt"
+	"strings"
+)
+
+type Hourly struct {
+	Summary             string `json:"summary"`
+	ForecastDiscussion  string `json:"forecast_discussion"`
+	PrecipitationTiming string `json:"precipitation_timing,omitempty"`
+	Confidence          string `json:"confidence,omitempty"`
+}
+
+func ValidateHourly(data []byte) (Hourly, []byte, error) {
+	value, err := decodeGeneratedText[Hourly](data, "hourly")
+	if err != nil {
+		return Hourly{}, nil, err
+	}
+
+	value.Summary = strings.TrimSpace(value.Summary)
+	value.ForecastDiscussion = strings.TrimSpace(value.ForecastDiscussion)
+	value.PrecipitationTiming = strings.TrimSpace(value.PrecipitationTiming)
+	value.Confidence = strings.TrimSpace(value.Confidence)
+	if value.Summary == "" {
+		return Hourly{}, nil, fmt.Errorf("hourly generated text summary is required")
+	}
+	if value.ForecastDiscussion == "" {
+		return Hourly{}, nil, fmt.Errorf("hourly generated text forecast discussion is required")
+	}
+
+	normalized, err := normalizeGeneratedText(value, "hourly")
+	if err != nil {
+		return Hourly{}, nil, err
+	}
+	return value, normalized, nil
+}

internal/generatedtext/hourly_test.go

@@ -0,0 +1,102 @@
+package generatedtext
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestValidateHourlyNormalizesJSON(t *testing.T) {
+	value, normalized, err := ValidateHourly([]byte(`{
+		"summary": " Storm chances increase. ",
+		"forecast_discussion": " A front will keep the region unsettled. ",
+		"precipitation_timing": " Showers are most likely early this afternoon. ",
+		"confidence": " Medium "
+	}`))
+	if err != nil {
+		t.Fatalf("ValidateHourly() error = %v", err)
+	}
+	if value.Summary != "Storm chances increase." {
+		t.Fatalf("Summary = %q, want trimmed summary", value.Summary)
+	}
+	if value.ForecastDiscussion != "A front will keep the region unsettled." {
+		t.Fatalf("ForecastDiscussion = %q, want trimmed discussion", value.ForecastDiscussion)
+	}
+	if value.PrecipitationTiming != "Showers are most likely early this afternoon." {
+		t.Fatalf("PrecipitationTiming = %q, want trimmed precipitation timing", value.PrecipitationTiming)
+	}
+	want := `{"summary":"Storm chances increase.","forecast_discussion":"A front will keep the region unsettled.","precipitation_timing":"Showers are most likely early this afternoon.","confidence":"Medium"}`
+	if string(normalized) != want {
+		t.Fatalf("normalized = %s, want %s", normalized, want)
+	}
+}
+
+func TestValidateHourlyOmitsEmptyConfidence(t *testing.T) {
+	_, normalized, err := ValidateHourly([]byte(`{
+		"summary": "Storm chances increase.",
+		"forecast_discussion": "A front will keep the region unsettled.",
+		"precipitation_timing": "   ",
+		"confidence": "   "
+	}`))
+	if err != nil {
+		t.Fatalf("ValidateHourly() error = %v", err)
+	}
+	want := `{"summary":"Storm chances increase.","forecast_discussion":"A front will keep the region unsettled."}`
+	if string(normalized) != want {
+		t.Fatalf("normalized = %s, want %s", normalized, want)
+	}
+}
+
+func TestValidateHourlyRejectsInvalidInput(t *testing.T) {
+	tests := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{
+			name: "malformed",
+			in:   `{`,
+			want: "decode hourly generated text",
+		},
+		{
+			name: "unknown field",
+			in:   `{"summary":"Storm chances increase.","forecast_discussion":"A front will keep the region unsettled.","extra":"value"}`,
+			want: `unknown field "extra"`,
+		},
+		{
+			name: "missing summary",
+			in:   `{"forecast_discussion":"A front will keep the region unsettled."}`,
+			want: "summary is required",
+		},
+		{
+			name: "blank forecast discussion",
+			in:   `{"summary":"Storm chances increase.","forecast_discussion":"  "}`,
+			want: "forecast discussion is required",
+		},
+		{
+			name: "old timing field rejected",
+			in:   `{"summary":"Storm chances increase.","forecast_discussion":"A front will keep the region unsettled.","timing":"Late morning."}`,
+			want: `unknown field "timing"`,
+		},
+		{
+			name: "old impacts field rejected",
+			in:   `{"summary":"Storm chances increase.","forecast_discussion":"A front will keep the region unsettled.","impacts":"Brief downpours."}`,
+			want: `unknown field "impacts"`,
+		},
+		{
+			name: "multiple values",
+			in:   `{"summary":"Storm chances increase.","forecast_discussion":"A front will keep the region unsettled."} {}`,
+			want: "multiple JSON values",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			_, _, err := ValidateHourly([]byte(test.in))
+			if err == nil {
+				t.Fatal("ValidateHourly() error = nil, want error")
+			}
+			if !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("ValidateHourly() error = %v, want %q", err, test.want)
+			}
+		})
+	}
+}