weatherreporter/docs/config.md

# Weatherreporter Configuration

Weatherreporter reads YAML configuration. The default path is:

```text
/usr/local/etc/weatherreporter/config.yml
```

If the default file is absent, Weatherreporter uses built-in defaults. An
explicit `--config PATH` must exist. Values are applied in this order:

1. built-in defaults;
2. the configuration file, when present; and
3. the `--units` and `--tz` command-line overrides.

Environment variables do not override configuration fields. Output flags select
operator-owned destinations for one command and do not change configuration.

## Maintained Examples

- [minimal-config.yml](../examples/minimal-config.yml) is the smallest useful
  collection and generation configuration.
- [config.yml](../examples/config.yml) is a representative production-oriented
  configuration using synthetic endpoints and no credentials.
- [weather-light-local-profile.yml](../examples/weather-light-local-profile.yml)
  is a complete endpoint-only override for the embedded `weather-light`
  profile.

The configuration examples are loaded by the configuration test suite. The
profile example is inspected through the Promptkit adapter test suite.

## Minimal Configuration

```yaml
weather_api:
  base_url: https://weather.api.example.com/
```

`weather_api.base_url` is required for workflows that collect weather data.
All omitted fields use their built-in defaults.

## Field Reference

### `weather_api`

| Field | Default | Rules |
| --- | --- | --- |
| `base_url` | empty | Absolute HTTP(S) Weather API URL. Required for collection and generation. |
| `timeout` | `10s` | Must be greater than zero. |
| `precision` | `0` | Must be zero or greater. Sent as the Weather API precision query value. |
| `units` | `us` | Required Weather API units query value; `--units` overrides it for one command. |
| `timezone` | `America/Chicago` | Required report and Weather API timezone; `--tz` overrides it for one command. |
| `format` | `json` | Required and must be `json`. |

Timezone values may be IANA names, configured aliases such as `Chicago` and
`Stl`, US timezone abbreviations, or signed UTC offsets such as `-5`, `+0930`,
and `+09:30`. Numeric offsets require a sign, one or two hour digits, and an
optional two-digit minute component with or without a colon. Hours must be
from `00` through `23`, minutes from `00` through `59`, so the largest accepted
offset magnitude is `23:59`.

### `location`

`location` supplies descriptive prompt context; it does not choose a Weather
API endpoint or configure multiple forecast locations.

| Field | Default |
| --- | --- |
| `id` | `home` |
| `name` | `Brentwood` |
| `region` | `St. Louis Metro` |

The prompt-facing location timezone is derived from the effective
`weather_api.timezone` after command-line overrides.

### `secrets`

`secrets.directory` defaults to empty, which disables secret loading. When it
is set, every regular file directly in that directory is staged after the file
and command-line overrides, then applied only after the complete configuration
has validated successfully. A rejected load leaves the existing environment
unchanged. A file basename must match
`[A-Za-z_][A-Za-z0-9_]*`; it becomes an environment variable name, and the
file contents replace any existing value. One trailing LF or CRLF is removed.

Missing directories, unreadable files, subdirectories, symlinks, non-regular
files, and invalid names fail configuration loading. Put only secret values in
this directory, never in the YAML file.

### `output`

`output.directory` selects the ordinary operator-owned publication directory
for individual reports, batches, and the default parent of comparison bundles.

| Field | Default | Rules |
| --- | --- | --- |
| `directory` | empty | An omitted or empty value uses the invocation working directory. A nonempty value must contain at least one non-whitespace character. |

The configured value is preserved while configuration loads: it is not cleaned,
made absolute, inspected, created, or expanded through environment variables or
a home-directory shortcut. At execution, an absolute directory is used as
given; a relative directory resolves from the invocation working directory, not
from the configuration file's location. A missing directory is created when a
report is successfully published. An existing non-directory or an uninspectable
path fails output preflight before prompt inspection, weather collection, or
publication.

For one `generate` command, `--out` is a complete file destination and takes
precedence over `output.directory`. For `run`, `--out-dir` takes precedence.
For `compare`, `--out-dir` selects its exact bundle directory; without it, the
comparison's report-derived directory is placed beneath `output.directory`.
Those explicit flags do not inspect or rebase beneath the configured directory.
See the [CLI reference](cli.md) for command selection and the [operations
guide](operations.md) for publication and failure handling.

### `notify.distributor`

Distributor notification is disabled by default. Its fields are:

| Field | Default | Rules when notification is enabled |
| --- | --- | --- |
| `enabled` | `false` | Activates Distributor notification validation. |
| `endpoint` | `https://distributor.example.com` | Must be an absolute HTTP(S) base URL with a host and no userinfo, query, or fragment. A path prefix is allowed. |
| `token_env` | `DISTRIBUTOR_UPLOAD_TOKEN` | Must name a valid environment variable. |
| `timeout` | `30s` | Must be greater than zero. |
| `failure_policy` | `error` | Must be `error`. |
| `pipeline_id_template` | empty | Required single-report pipeline ID template. |
| `bundle_id_template` | `weatherreporter.{location_id}.{report_id}` | Required single-report bundle ID template. |
| `idempotency_key_template` | `{bundle_id}.{run_id}` | Required single-report idempotency-key template. |
| `batch.enabled` | `true` | Activates batch notification validation when Distributor notification is enabled. |
| `batch.pipeline_id_template` | `weatherreporter` | Required when batch notification is enabled. |
| `batch.bundle_id_template` | `weatherreporter.{location_id}.{batch}` | Required when batch notification is enabled. |
| `batch.idempotency_key_template` | `{bundle_id}.{batch_run_id}` | Required when batch notification is enabled. |

The upload token is read from the environment variable named by `token_env`.
Use `secrets.directory` when a file-backed secret is appropriate.

When notification is enabled, Weatherreporter validates the Distributor endpoint
before prompt inspection, weather collection, or output publication. Use an
HTTP(S) base URL such as `https://distributor.example.com/archive`; do not put
credentials, a query string, or a fragment in the endpoint.

When notification is enabled, each rendered single-report pipeline ID, bundle
ID, and idempotency key must contain at least one non-whitespace character.

Single-report bundle templates accept `location_id`, `report_id`, `run_id`,
`artifact_group`, `batch_output_name`, `valid_start_date`, `valid_end_date`,
`valid_start_time`, `valid_end_time`, `valid_start_stamp`, `valid_end_stamp`,
Pipeline and idempotency-key templates may also use `bundle_id`. Dates use
`YYYY-MM-DD`; times use `HHMM`; and stamps use `YYYY-MM-DDTHHMM` in the
effective report timezone.

Batch bundle and pipeline templates accept `location_id`, `batch`,
`batch_run_id`, and `batch_started_date`; batch idempotency-key templates may
also use `bundle_id`. `batch_started_date` is the batch start date in the
effective report timezone.

`reports.<report>.distributor.path_templates` overrides the default ordered
Distributor paths for that report. Each rendered path must be a unique relative
path with `/` separators. Backslashes, empty segments, `.` and `..` segments,
`manifest.json`, and the reserved Distributor sidecar basename are rejected.
The default paths are:

| Report | Paths |
| --- | --- |
| `hourly` | `hourly/index.md` |
| `daily` | `daily/{valid_start_date}/{run_id}.md`, `daily/{valid_start_date}/index.md` |
| `today` | `daily/{valid_start_date}/{run_id}.md`, `daily/{valid_start_date}/index.md`, `today/index.md` |
| `tomorrow` | `daily/{valid_start_date}/{run_id}.md`, `daily/{valid_start_date}/index.md`, `tomorrow/index.md` |

See the [operations guide](operations.md) for notification timing, uploaded
output selection, and failure handling.

### `missing_source`

`missing_source.default` defaults to `warn` and accepts `error`, `warn`, or
`none`. `missing_source.sources` optionally overrides that policy by source.
Hourly forecast data is required for generated reports and cannot have a
source-specific policy. Supported optional source keys are `observations`,
`current`, `narrative`, `alerts`, `discussion`, `weather_story`, and
`spc_convective_outlooks`; any other key is rejected.

### `promptkit`

Promptkit configuration selects the executor and prompt/profile checks for
every `generate`, `run`, and `compare` command. A top-level `scriptorium:` configuration
key is rejected with a migration error; it is not translated or ignored.

Prompt debug capture has no YAML setting. Use `--llm-debug-dir PATH` on an
individual `generate`, `run`, or `compare` command when explicitly needed.
See [optional prompt debug capture](operations.md#optional-prompt-debug-capture)
for platform availability, security, and retention requirements.

| Field | Default | Rules |
| --- | --- | --- |
| `profile` | empty | Optional global profile selection for every report in one command. When empty, each exact prompt version selects its declared default. |
| `profile_file` | empty | Optional external Promptkit profile file. It cannot be combined with `profile_dir`. A same-ID profile completely replaces Weatherreporter's embedded definition. |
| `profile_dir` | empty | Optional external Promptkit profile directory. It cannot be combined with `profile_file`. A same-ID profile completely replaces Weatherreporter's embedded definition. |
| `timeout` | `2m` | Must be greater than zero. |
| `local.endpoint` | empty | Optional absolute URL for the conventional local backend. A blank endpoint leaves it unregistered. |
| `local.concurrency_limit` | `1` | Maximum local backend concurrency. `0` is unlimited; negative values are invalid. |

`profile` selects an ID; `profile_file` and `profile_dir` supply definitions.
They are separate decisions. An explicit `profile` applies to every selected
report. Otherwise Hourly selects `weather-light`, while Daily, Today, and
Tomorrow select `weather-balanced` through their exact `2.1.0` prompt
definitions.

Promptkit resolves a selected profile definition from a test or embedding
consumer's explicit in-memory profile, then the configured `profile_file` or
`profile_dir`, then Weatherreporter's embedded catalog, and finally Promptkit's
maintained catalog. Weatherreporter's embedded `weather-*` definitions are small
aliases of Promptkit's maintained base profiles, so Promptkit also resolves
their inherited target and settings. A configured definition with the same ID
as either a selected profile or an inherited base takes precedence. A matching
malformed external profile fails rather than using the embedded definition. The
[Promptkit integration guide](integrations/promptkit.md) owns the catalog and
precedence details.

An endpoint-only profile may intentionally have no backend identity. Profiles
that require a direct API key are rejected before collection, while Promptkit
resolves optional environment credential sources during execution.

To replace the default Hourly definition with a local OpenAI-compatible
endpoint, set `profile_file` to a copy of
[weather-light-local-profile.yml](../examples/weather-light-local-profile.yml).
The example has no credential and should be edited for the local endpoint and
model before use. An alternative profile may use `backend: local`; in that
case `promptkit.local.endpoint` supplies the conventional local backend
endpoint.

### `dayparts`

`dayparts` is a non-empty list of named local-time windows used in forecast
derivation. Every item needs `name`, `start`, and `end`; start and end use
`HH:MM`. Defaults are `overnight` (`00:00`–`06:00`), `morning`
(`06:00`–`10:00`), `midday` (`10:00`–`15:00`), `afternoon`
(`15:00`–`17:00`), and `evening` (`17:00`–`24:00`).

Names remain display text, but each name must have a distinct canonical
identity. Canonicalization trims whitespace, lowercases letters, and collapses
punctuation and whitespace to underscores; for example, `Morning`,
`morning!`, and `morning` conflict. Planning recognizes the canonical
identities `morning`, `afternoon`, `evening`, and `overnight` regardless of
their display capitalization or punctuation.

### `reports`

`reports` optionally overrides a report's ordered deterministic modules and
Distributor path templates. Omit a report entry to retain its defaults.

Supported report keys are `daily`, `today`, `tomorrow`, and `hourly`. Keys are
trimmed, case-folded to lowercase, and normalize hyphens to underscores before
lookup.

Each report entry can contain:

- `deterministic_modules`: an ordered list of module IDs, or objects with `id`
  and optional `options`.
- `distributor.path_templates`: an optional, non-empty ordered list of
  Distributor paths for that report.

Unknown reports and modules, duplicate modules, incompatible report-module
combinations, duplicate stanza names, invalid path templates, and invalid
module options fail configuration loading. The accepted module IDs and module
option contracts are documented in the [module contract internals](internal/module.md).