# 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-variable configuration is not implemented.

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

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