weatherreporter/docs/config.md

# Weatherreporter Configuration

Configuration is YAML. By default, `weatherreporter` reads:

```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 variables do not override configuration fields.

## Minimal Config

See [examples/minimal-config.yml](../examples/minimal-config.yml).

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

## 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`.

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 briefing metadata and
Scriptorium data packages. It does not select a Weather API endpoint or enable
multiple configured forecast locations.

- `id`: short local identifier. Default: `home`.
- `name`: human-readable location name. Default: `Brentwood`.
- `region`: broader forecast area context. Default: `St. Louis Metro`.

The prompt-facing location object also includes `timezone`, derived from the
effective `weather_api.timezone` after CLI overrides such as `--tz`.

### `secrets`

- `directory`: optional directory of file-backed environment secrets. Default:
  empty, which disables secret loading.

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.

### `notify`

`notify.distributor` is validated configuration for distributor notification.
It is disabled by default. This configuration does not add CLI flags.

- `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`.
- `bundle_id_template`: template for distributor bundle IDs. Default:
  `weatherreporter.{location_id}.{report_id}.{run_id}`.
- `idempotency_key_template`: template for distributor idempotency keys.
  Default: `{bundle_id}`.
- `report_path_template`: template for the Markdown report path inside the
  distributor bundle. Default: `{batch_output_name}`.

Supported template variables are `location_id`, `report_id`, `run_id`,
`artifact_group`, and `batch_output_name`. `idempotency_key_template` may also
use `bundle_id`.

Rendered report paths must be relative paths with `/` separators. They must not
contain backslashes, empty path segments, `.`, `..`, `manifest.json`, or
`.distributor.json`.

### `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,
midday, 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 raw secrets. Use `secrets.directory` to
load secret values from files into environment variables for integrations that
read credentials from the environment.

## 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 implemented fields.

Both example files are loaded by the config test suite.