eric/weatherreporter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Align baseline user documentation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-29 19:47:01 +00:00
parent 5c9333feec
commit 62827cf56d
3 changed files with 143 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
README.md
View File

@@ -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)

119
docs/cli.md
View File

@@ -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=<managed_path> --format json`, then
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.
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.

120
docs/config.md
View File

@@ -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.