From 62827cf56dbf2db235d37f81b45fac4e8cd24faa Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 29 May 2026 19:47:01 +0000 Subject: [PATCH] Align baseline user documentation --- README.md | 14 ++---- docs/cli.md | 119 +++++++++++++++++++++--------------------------- docs/config.md | 120 ++++++++++++++++++++++++++++++++++++------------- 3 files changed, 143 insertions(+), 110 deletions(-) diff --git a/README.md b/README.md index d54ab95..b94b007 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,14 @@ # weatherreporter `weatherreporter` is a Go application for preparing human-facing weather -reports from normalized forecast data. - -The application can currently generate Daily Today, Daily Tomorrow, 3-Day -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. +reports from normalized forecast data. It builds structured briefing packages, +runs them through `scriptorium`, and keeps inspectable artifacts under a local +workspace. ## Quickstart ```sh weatherreporter generate daily --date 2026-05-29 --out ./daily.md -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) diff --git a/docs/cli.md b/docs/cli.md index c332796..eaa4a13 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,11 +1,7 @@ # Weatherreporter CLI -`weatherreporter generate daily`, `weatherreporter generate tomorrow`, -`weatherreporter generate three-day`, `weatherreporter generate weekend`, -`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. +`weatherreporter` generates Markdown weather reports, runs scheduled report +batches, and inspects previously generated artifacts. ## 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 -Daily briefing, writes workspace artifacts, invokes -`scriptorium render --input data_package= --format json`, then -invokes `scriptorium run --input data_package= --out `. -When `--out` is supplied, it also writes a copy of the Markdown report to that -path. +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`. -For tomorrow planning: - -```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 +## Commands ```text -weatherreporter generate daily -weatherreporter generate tomorrow -weatherreporter generate three-day -weatherreporter generate weekend -weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00 -weatherreporter run morning -weatherreporter run evening -weatherreporter inspect reports -weatherreporter inspect metadata RUN_ID -weatherreporter inspect briefing RUN_ID -weatherreporter inspect data-package RUN_ID -weatherreporter inspect prior RUN_ID -weatherreporter inspect sources RUN_ID +weatherreporter --help +weatherreporter generate daily [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--date YYYY-MM-DD] +weatherreporter generate tomorrow [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] +weatherreporter generate three-day [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] +weatherreporter generate weekend [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] +weatherreporter generate storm [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] --start TIME --end TIME +weatherreporter run morning [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] +weatherreporter run evening [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] +weatherreporter inspect reports [--config PATH] [--limit N] +weatherreporter inspect metadata [--config PATH] RUN_ID +weatherreporter inspect briefing [--config PATH] RUN_ID +weatherreporter inspect data-package [--config PATH] RUN_ID +weatherreporter inspect prior [--config PATH] RUN_ID +weatherreporter inspect sources [--config PATH] RUN_ID ``` -`generate daily`, `generate tomorrow`, `generate three-day`, -`generate weekend`, and `generate storm` write a briefing snapshot, prompt -input data package, render preflight output, Markdown report, and metadata file -under the configured workspace. `generate storm` requires explicit `--start` -and `--end` bounds for the event window. `run evening` generates the Tomorrow -Planning Brief. `run morning` generates Daily Today and the 3-Day Outlook, plus -Weekend Outlook except on Sunday. Run commands continue remaining reports after -an independent report failure, print a JSON aggregate summary to stdout, write -compact report status logs to stderr, and return nonzero when any report +`generate` commands write briefing, data package, preflight, report, and +metadata artifacts under the configured workspace. `generate storm` requires +explicit event-window bounds with `--start` and `--end`. + +`run morning` generates Daily Today and the 3-Day Outlook, plus Weekend Outlook +except on Sunday. `run evening` generates the Tomorrow Planning Brief. Batch +runs continue independent reports after a failure, print a JSON summary to +stdout, write compact status lines to stderr, and return nonzero when any report failed. -`inspect` commands read the configured workspace and emit JSON to stdout. They -do not fetch weather data or invoke `scriptorium`. +`inspect` commands read existing workspace artifacts and emit JSON to stdout. +They do not fetch weather data or invoke `scriptorium`. ## Flags - `-h`, `--help`: show help. - `--config PATH`: load configuration from `PATH` instead of `/usr/local/etc/weatherreporter/config.yml`. -- `--units VALUE`: override configured Weather API units. -- `--tz NAME`: override configured Weather API timezone. -- `--out PATH`: optional Markdown report copy for `generate daily`, `generate tomorrow`, `generate three-day`, `generate weekend`, and `generate storm`. -- `--out-dir PATH`: optional directory for extra Markdown report copies from `run morning` and `run evening`. +- `--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 report records for `inspect reports`; defaults to 20, - and `0` means no limit. +- `--limit N`: maximum records for `inspect reports`; defaults to `20`, and `0` means no limit. Storm times accept `YYYY-MM-DDTHH:MM` in the configured timezone or RFC3339 timestamps with explicit offsets. +## Common Workflows + +```sh +weatherreporter generate tomorrow --out ./tomorrow.md +weatherreporter generate three-day --out ./three-day.md +weatherreporter generate weekend --out ./weekend.md +weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00 --out ./storm.md +weatherreporter run morning --out-dir ./reports +weatherreporter run evening --out-dir ./reports +``` + ## Inspection ```sh @@ -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 -counts. The other commands require a RunID. `inspect prior` returns the prior -comparable snapshot metadata selected from stored metadata, or `null` when no -prior comparable snapshot exists. `inspect sources` shows source provenance and -source warnings without dumping full weather payloads. +`inspect reports` lists recent generated runs with artifact paths and source +warning counts. The other inspect commands require a RunID. `inspect prior` +returns the prior comparable snapshot metadata selected from stored metadata, or +`null` when none exists. `inspect sources` shows source provenance and source +warnings without dumping full weather payloads. diff --git a/docs/config.md b/docs/config.md index 1addf9d..b296689 100644 --- a/docs/config.md +++ b/docs/config.md @@ -1,10 +1,24 @@ # Weatherreporter Configuration -Configuration is loaded from `/usr/local/etc/weatherreporter/config.yml` by -default. Use `--config PATH` to load a different file. CLI flags override file -values. +Configuration is YAML. By default, `weatherreporter` reads: -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.timeout`: HTTP timeout duration. Default: `10s`. -- `weather_api.precision`: numeric precision hint. Default: `1`. -- `weather_api.units`: Weather API units. Default: `us`. -- `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`. -- `weather_api.format`: Weather API response format. Default: `json`. -- `missing_source.default`: one of `error`, `warn`, or `none`. Default: `warn`. -- `missing_source.sources`: optional per-source missing-source policy overrides. -- `scriptorium.binary`: `scriptorium` executable name. Default: `scriptorium`. -- `scriptorium.config_path`: optional `scriptorium` config path. -- `scriptorium.profile`: optional `scriptorium` profile. -- `scriptorium.timeout`: subprocess timeout. Default: `2m`. -- `scriptorium.extra_args`: optional extra arguments reserved for the adapter. -- `workspace.root`: workspace root. Default: `workspace`. -- `workspace.snapshots_dir`: snapshot directory under the workspace. -- `workspace.reports_dir`: managed report directory under the workspace. -- `workspace.data_packages_dir`: prompt input package directory under the workspace. -- `workspace.preflight_dir`: preflight output directory under the workspace. -- `reports.output_dir`: report output directory. Default: `reports`. -- `reports.paths`: optional report-specific output paths. -- `dayparts`: named daypart definitions with `start` and `end` `HH:MM` values. -- `recent_change.temperature_degrees`: temperature change threshold. -- `recent_change.precip_probability_points`: precipitation probability threshold. -- `recent_change.wind_gust_miles_per_hour`: wind gust change threshold. -- `recent_change.precip_timing_shift_minutes`: precipitation timing shift threshold. +### `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: `Chicago`. +- `format`: Weather API response format. Must be `json`. Default: `json`. + +Timezone values may be IANA names, configured aliases such as `Chicago` and +`Stl`, US timezone abbreviations, or UTC offsets such as `-5` and `+09:30`. + +### `missing_source` + +- `default`: missing-source behavior for optional sources. One of `error`, `warn`, or `none`. Default: `warn`. +- `sources`: optional map of source-specific overrides, using the same policy values. + +Hourly forecast data is required for generated reports. Optional sources and +stub source slots use the missing-source policy. + +### `scriptorium` + +- `binary`: `scriptorium` executable name or path. Default: `scriptorium`. +- `config_path`: optional Scriptorium config path passed to the adapter. +- `profile`: optional Scriptorium profile passed to the adapter. +- `timeout`: subprocess timeout. Default: `2m`. +- `extra_args`: optional additional arguments passed to Scriptorium commands. + +### `workspace` + +- `root`: workspace root for managed artifacts. Default: `workspace`. +- `snapshots_dir`: briefing and metadata directory under `workspace.root`. Default: `snapshots`. +- `reports_dir`: managed Markdown report directory under `workspace.root`. Default: `reports`. +- `data_packages_dir`: prompt input package directory under `workspace.root`. Default: `data-packages`. +- `preflight_dir`: Scriptorium render output directory under `workspace.root`. Default: `preflight`. + +Workspace subdirectories must be relative paths that stay inside +`workspace.root`. + +### `dayparts` + +`dayparts` is a list of named local-time windows used by forecast derivation. +Each entry has: + +- `name` +- `start` +- `end` + +`start` and `end` use `HH:MM`. The default entries are overnight, morning, +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.