weatherreporter/docs/config.md

Weatherreporter Configuration

Configuration is YAML. By default, weatherreporter reads:

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

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. 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: smallest useful config for generation and fetching.
• examples/config.yml: production-oriented config covering implemented fields.

Both example files are loaded by the config test suite.