weatherreporter/docs/config.md

Weatherreporter Configuration

Weatherreporter reads YAML configuration. The default path is:

/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 write extra report copies for a command and do not change configuration.

Maintained Examples

• minimal-config.yml is the smallest useful collection and generation configuration.
• config.yml is a representative production-oriented configuration using synthetic endpoints and no credentials.

Both files are loaded by the configuration test suite.

Minimal Configuration

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 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 UTC offsets such as -5 and +09:30.

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 loaded after the file and command-line overrides. 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.

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

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, and storm_id. 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. storm_id is {valid_start_stamp}-{valid_end_stamp} for Storm Report and empty otherwise.

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
three_day	three-day/{valid_start_date}/{run_id}.md, three-day/{valid_start_date}/index.md
weekend	weekend/{valid_start_date}/{run_id}.md, weekend/{valid_start_date}/index.md
storm	storm/{storm_id}/{run_id}.md, storm/{storm_id}/index.md

See the operations guide for notification timing, uploaded artifact 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. Supported optional source keys are observations, current, narrative, alerts, discussion, weather_story, and spc_convective_outlooks.

scriptorium

Field	Default	Rules
binary	scriptorium	Required executable name or path.
config_path	empty	Optional Scriptorium configuration path.
profile	empty	Optional Scriptorium profile.
timeout	2m	Must be greater than zero.
extra_args	empty	Optional extra arguments passed to Scriptorium commands.

workspace

Field	Default
root	workspace
snapshots_dir	snapshots
reports_dir	reports
data_packages_dir	data-packages
preflight_dir	preflight
notifications_dir	notifications

workspace.root is required. Each workspace subdirectory must be a relative path that stays within the root. See the operations guide for the managed workspace layout and lifecycle.

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

recent_change

Field	Default
temperature_degrees	5
precip_probability_points	20
wind_gust_miles_per_hour	10
precip_timing_shift_minutes	120

These thresholds control when Recent Changes are included in prompt input for a prior comparable module snapshot.

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, hourly, three_day, weekend, and storm. Configuration also accepts three_day_outlook, weekend_outlook, and storm_report; hyphens and underscores are equivalent.

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.