Align baseline user documentation

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.