Align baseline user documentation

README.md

@@ -1,21 +1,14 @@
 # weatherreporter
 
 `weatherreporter` is a Go application for preparing human-facing weather
-reports from normalized forecast data.
+reports from normalized forecast data. It builds structured briefing packages,
-
+runs them through `scriptorium`, and keeps inspectable artifacts under a local
-The application can currently generate Daily Today, Daily Tomorrow, 3-Day
+workspace.
-Outlook, Weekend Outlook, and manual Storm Report Markdown reports through `scriptorium`, with
-inspectable briefing, prompt input, preflight, report, and metadata artifacts
-under the configured workspace.
 
 ## Quickstart
 
 ```sh
 weatherreporter generate daily --date 2026-05-29 --out ./daily.md
-weatherreporter generate tomorrow --out ./tomorrow.md
-weatherreporter generate three-day --out ./three-day.md
-weatherreporter generate weekend --out ./weekend.md
-weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00 --out ./storm.md
 ```
 
 ## Documentation
@@ -25,4 +18,3 @@ weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00 -
 - [Operations guide](docs/operations.md)
 - [Architecture policy](docs/policy/architecture.md)
 - [Development policy](docs/policy/development.md)
-- [Implementation roadmap](docs/roadmap/initial.md)

docs/cli.md

@@ -1,11 +1,7 @@
 # Weatherreporter CLI
 
-`weatherreporter generate daily`, `weatherreporter generate tomorrow`,
+`weatherreporter` generates Markdown weather reports, runs scheduled report
-`weatherreporter generate three-day`, `weatherreporter generate weekend`,
+batches, and inspects previously generated artifacts.
-`weatherreporter generate storm`,
-`weatherreporter run morning`, and `weatherreporter run evening` currently
-write Markdown reports through `scriptorium`, after writing managed preparation
-artifacts and running `scriptorium render` as a preflight check.
 
 ## Shortest Useful Command
 
@@ -13,82 +9,69 @@ artifacts and running `scriptorium render` as a preflight check.
 weatherreporter generate daily --date 2026-05-29 --out ./daily.md
 ```
 
-The command parses flags, loads configuration, fetches weather data, builds a
+This loads configuration, fetches weather data, writes managed workspace
-Daily briefing, writes workspace artifacts, invokes
+artifacts, runs `scriptorium render` as a preflight check, runs
-`scriptorium render --input data_package=<managed_path> --format json`, then
+`scriptorium run`, and writes an extra Markdown copy to `./daily.md`.
-invokes `scriptorium run --input data_package=<managed_path> --out <managed_report>`.
-When `--out` is supplied, it also writes a copy of the Markdown report to that
-path.
 
-For tomorrow planning:
+## Commands
-
-```sh
-weatherreporter generate tomorrow --out ./tomorrow.md
-weatherreporter run evening
-```
-
-For the 3-Day Outlook:
-
-```sh
-weatherreporter generate three-day --out ./three-day.md
-weatherreporter generate weekend --out ./weekend.md
-```
-
-For a focused manual Storm Report:
-
-```sh
-weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00 --out ./storm.md
-```
-
-## Command Overview
 
 ```text
-weatherreporter generate daily
+weatherreporter --help
-weatherreporter generate tomorrow
+weatherreporter generate daily [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--date YYYY-MM-DD]
-weatherreporter generate three-day
+weatherreporter generate tomorrow [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
-weatherreporter generate weekend
+weatherreporter generate three-day [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
-weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00
+weatherreporter generate weekend [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
-weatherreporter run morning
+weatherreporter generate storm [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] --start TIME --end TIME
-weatherreporter run evening
+weatherreporter run morning [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH]
-weatherreporter inspect reports
+weatherreporter run evening [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH]
-weatherreporter inspect metadata RUN_ID
+weatherreporter inspect reports [--config PATH] [--limit N]
-weatherreporter inspect briefing RUN_ID
+weatherreporter inspect metadata [--config PATH] RUN_ID
-weatherreporter inspect data-package RUN_ID
+weatherreporter inspect briefing [--config PATH] RUN_ID
-weatherreporter inspect prior RUN_ID
+weatherreporter inspect data-package [--config PATH] RUN_ID
-weatherreporter inspect sources RUN_ID
+weatherreporter inspect prior [--config PATH] RUN_ID
+weatherreporter inspect sources [--config PATH] RUN_ID
 ```
 
-`generate daily`, `generate tomorrow`, `generate three-day`,
+`generate` commands write briefing, data package, preflight, report, and
-`generate weekend`, and `generate storm` write a briefing snapshot, prompt
+metadata artifacts under the configured workspace. `generate storm` requires
-input data package, render preflight output, Markdown report, and metadata file
+explicit event-window bounds with `--start` and `--end`.
-under the configured workspace. `generate storm` requires explicit `--start`
+
-and `--end` bounds for the event window. `run evening` generates the Tomorrow
+`run morning` generates Daily Today and the 3-Day Outlook, plus Weekend Outlook
-Planning Brief. `run morning` generates Daily Today and the 3-Day Outlook, plus
+except on Sunday. `run evening` generates the Tomorrow Planning Brief. Batch
-Weekend Outlook except on Sunday. Run commands continue remaining reports after
+runs continue independent reports after a failure, print a JSON summary to
-an independent report failure, print a JSON aggregate summary to stdout, write
+stdout, write compact status lines to stderr, and return nonzero when any report
-compact report status logs to stderr, and return nonzero when any report
 failed.
 
-`inspect` commands read the configured workspace and emit JSON to stdout. They
+`inspect` commands read existing workspace artifacts and emit JSON to stdout.
-do not fetch weather data or invoke `scriptorium`.
+They do not fetch weather data or invoke `scriptorium`.
 
 ## Flags
 
 - `-h`, `--help`: show help.
 - `--config PATH`: load configuration from `PATH` instead of `/usr/local/etc/weatherreporter/config.yml`.
-- `--units VALUE`: override configured Weather API units.
+- `--units VALUE`: override configured Weather API units for `generate` and `run`.
-- `--tz NAME`: override configured Weather API timezone.
+- `--tz NAME`: override configured Weather API timezone for `generate` and `run`.
-- `--out PATH`: optional Markdown report copy for `generate daily`, `generate tomorrow`, `generate three-day`, `generate weekend`, and `generate storm`.
+- `--out PATH`: write an extra Markdown report copy for `generate` commands.
-- `--out-dir PATH`: optional directory for extra Markdown report copies from `run morning` and `run evening`.
+- `--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 report records for `inspect reports`; defaults to 20,
+- `--limit N`: maximum records for `inspect reports`; defaults to `20`, and `0` means no limit.
-  and `0` means no limit.
 
 Storm times accept `YYYY-MM-DDTHH:MM` in the configured timezone or RFC3339
 timestamps with explicit offsets.
 
+## Common Workflows
+
+```sh
+weatherreporter generate tomorrow --out ./tomorrow.md
+weatherreporter generate three-day --out ./three-day.md
+weatherreporter generate weekend --out ./weekend.md
+weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00 --out ./storm.md
+weatherreporter run morning --out-dir ./reports
+weatherreporter run evening --out-dir ./reports
+```
+
 ## Inspection
 
 ```sh
@@ -100,8 +83,8 @@ weatherreporter inspect prior 20260529T100000.000000000Z_daily_today
 weatherreporter inspect sources 20260529T100000.000000000Z_daily_today
 ```
 
-`inspect reports` lists recent generated runs with artifact paths and warning
+`inspect reports` lists recent generated runs with artifact paths and source
-counts. The other commands require a RunID. `inspect prior` returns the prior
+warning counts. The other inspect commands require a RunID. `inspect prior`
-comparable snapshot metadata selected from stored metadata, or `null` when no
+returns the prior comparable snapshot metadata selected from stored metadata, or
-prior comparable snapshot exists. `inspect sources` shows source provenance and
+`null` when none exists. `inspect sources` shows source provenance and source
-source warnings without dumping full weather payloads.
+warnings without dumping full weather payloads.

docs/config.md

@@ -1,10 +1,24 @@
 # Weatherreporter Configuration
 
-Configuration is loaded from `/usr/local/etc/weatherreporter/config.yml` by
+Configuration is YAML. By default, `weatherreporter` reads:
-default. Use `--config PATH` to load a different file. CLI flags override file
-values.
 
-If the default file is absent, built-in defaults are used.
+```text
+/usr/local/etc/weatherreporter/config.yml
+```
+
+Use `--config PATH` to load a different file. If the default file is absent,
+built-in defaults are used. If `--config PATH` points to a missing file, loading
+fails.
+
+Precedence is:
+
+1. CLI flags
+2. configuration file
+3. built-in defaults
+
+The implemented configuration overrides are `--units` and `--tz`. Output flags
+control report copies for the current command but do not change configuration
+files. Environment-variable configuration is not implemented.
 
 ## Minimal Config
 
@@ -13,34 +27,78 @@ 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).
+See [examples/config.yml](../examples/config.yml). The example is loaded by the
+config test suite.
 
-## Reference
+## Field Reference
 
-- `weather_api.base_url`: single Weather API endpoint base URL, required when fetching weather data.
+### `weather_api`
-- `weather_api.timeout`: HTTP timeout duration. Default: `10s`.
+
-- `weather_api.precision`: numeric precision hint. Default: `1`.
+- `base_url`: absolute base URL for the Weather API. Required for generation and fetch workflows.
-- `weather_api.units`: Weather API units. Default: `us`.
+- `timeout`: HTTP timeout duration. Default: `10s`.
-- `weather_api.timezone`: report timezone. Accepts IANA names, configured aliases such as `Chicago` and `Stl`, US timezone abbreviations, and UTC offsets such as `-5` or `+09:30`. Default: `Chicago`.
+- `precision`: numeric precision query value. Default: `1`.
-- `weather_api.format`: Weather API response format. Default: `json`.
+- `units`: Weather API units query value. Default: `us`.
-- `missing_source.default`: one of `error`, `warn`, or `none`. Default: `warn`.
+- `timezone`: report timezone and Weather API timezone query value where supported. Default: `Chicago`.
-- `missing_source.sources`: optional per-source missing-source policy overrides.
+- `format`: Weather API response format. Must be `json`. Default: `json`.
-- `scriptorium.binary`: `scriptorium` executable name. Default: `scriptorium`.
+
-- `scriptorium.config_path`: optional `scriptorium` config path.
+Timezone values may be IANA names, configured aliases such as `Chicago` and
-- `scriptorium.profile`: optional `scriptorium` profile.
+`Stl`, US timezone abbreviations, or UTC offsets such as `-5` and `+09:30`.
-- `scriptorium.timeout`: subprocess timeout. Default: `2m`.
+
-- `scriptorium.extra_args`: optional extra arguments reserved for the adapter.
+### `missing_source`
-- `workspace.root`: workspace root. Default: `workspace`.
+
-- `workspace.snapshots_dir`: snapshot directory under the workspace.
+- `default`: missing-source behavior for optional sources. One of `error`, `warn`, or `none`. Default: `warn`.
-- `workspace.reports_dir`: managed report directory under the workspace.
+- `sources`: optional map of source-specific overrides, using the same policy values.
-- `workspace.data_packages_dir`: prompt input package directory under the workspace.
+
-- `workspace.preflight_dir`: preflight output directory under the workspace.
+Hourly forecast data is required for generated reports. Optional sources and
-- `reports.output_dir`: report output directory. Default: `reports`.
+stub source slots use the missing-source policy.
-- `reports.paths`: optional report-specific output paths.
+
-- `dayparts`: named daypart definitions with `start` and `end` `HH:MM` values.
+### `scriptorium`
-- `recent_change.temperature_degrees`: temperature change threshold.
+
-- `recent_change.precip_probability_points`: precipitation probability threshold.
+- `binary`: `scriptorium` executable name or path. Default: `scriptorium`.
-- `recent_change.wind_gust_miles_per_hour`: wind gust change threshold.
+- `config_path`: optional Scriptorium config path passed to the adapter.
-- `recent_change.precip_timing_shift_minutes`: precipitation timing shift threshold.
+- `profile`: optional Scriptorium profile passed to the adapter.
+- `timeout`: subprocess timeout. Default: `2m`.
+- `extra_args`: optional additional arguments passed to Scriptorium commands.
+
+### `workspace`
+
+- `root`: workspace root for managed artifacts. Default: `workspace`.
+- `snapshots_dir`: briefing and metadata directory under `workspace.root`. Default: `snapshots`.
+- `reports_dir`: managed Markdown report directory under `workspace.root`. Default: `reports`.
+- `data_packages_dir`: prompt input package directory under `workspace.root`. Default: `data-packages`.
+- `preflight_dir`: Scriptorium render output directory under `workspace.root`. Default: `preflight`.
+
+Workspace subdirectories must be relative paths that stay inside
+`workspace.root`.
+
+### `dayparts`
+
+`dayparts` is a list of named local-time windows used by forecast derivation.
+Each entry has:
+
+- `name`
+- `start`
+- `end`
+
+`start` and `end` use `HH:MM`. The default entries are overnight, morning,
+afternoon, and evening.
+
+### `recent_change`
+
+- `temperature_degrees`: temperature change threshold. Default: `5`.
+- `precip_probability_points`: precipitation probability threshold. Default: `20`.
+- `wind_gust_miles_per_hour`: wind gust change threshold. Default: `10`.
+- `precip_timing_shift_minutes`: precipitation timing shift threshold. Default: `120`.
+
+Recent Changes are added to prompt input when a prior comparable briefing
+snapshot exists and a threshold is crossed.
+
+## Secrets
+
+Configuration files should not contain secrets. The current Weather API and
+Scriptorium integration settings do not require secret fields.