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

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: 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 module 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 controls distributor notification after successful report generation. It is disabled by default and does not add CLI flags. When enabled, weatherreporter uploads one distributor bundle per generated report after report rendering succeeds and final metadata is saved.

• 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.
• pipeline_id_template: template for the distributor pipeline ID. Required when enabled. Default: empty.
• bundle_id_template: template for distributor bundle IDs. Default: weatherreporter.{location_id}.{report_id}.
• idempotency_key_template: template for distributor idempotency keys. Default: {bundle_id}.{run_id}.
• report_path_templates: ordered list of templates for Markdown report paths inside the distributor bundle. Each rendered path maps to the same managed Markdown report source. Default:

  - "{valid_start_date}/{artifact_group}/{valid_start_date}-{artifact_group}-{run_id}.md"
  

Supported template variables are 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, and valid_end_stamp. Date values use YYYY-MM-DD, time values use HHMM, and stamp values use YYYY-MM-DDTHHMM in the effective report timezone. pipeline_id_template and idempotency_key_template may also use bundle_id.

The rendered pipeline ID selects the configured distributor http_upload workflow. The rendered bundle ID is the stable logical source identity for the report stream. The rendered idempotency key is the per-run retry identity.

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

The upload token is read from the environment variable named by token_env after config loading and secrets.directory processing. Config files should name the variable only; they should not contain the token value.

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 use the missing-source policy. Source override keys include observations, current, narrative, alerts, discussion, weather_story, and spc_convective_outlooks.

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: module snapshot 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.
• notifications_dir: distributor notification debug artifact directory under workspace.root. Default: notifications.

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 module snapshot exists and a threshold is crossed.

reports

reports optionally overrides the ordered deterministic modules declared by report definitions. Omit a report entry to use its default module order.

Supported report keys are daily, today, tomorrow, hourly, three_day, weekend, and storm. Canonical report IDs and accepted aliases are also valid, including daily_today, three_day_outlook, weekend_outlook, and storm_report. Hyphens and underscores are treated equivalently in report keys.

reports.today applies only to the Today Report. reports.daily and reports.daily_today apply only to the existing Daily Today report.

Each report entry supports:

• deterministic_modules: ordered module list. Entries may be string module IDs or objects with id and optional options.

Example:

reports:
  daily:
    deterministic_modules:
      - metadata
      - current_conditions
      - narrative_forecast
      - alert_digest
      - spc_convective_outlooks
      - id: area_forecast_discussion
        options:
          sections:
            - short_term
      - spc_convective_discussion
      - hourly_forecast
  today:
    deterministic_modules:
      - metadata
      - current_conditions
      - narrative_forecast
      - derived_daily_summary
      - derived_daypart_summaries
      - precip_timing
      - alert_digest
      - spc_convective_outlooks
      - area_forecast_discussion
      - spc_convective_discussion
      - weather_story
      - outdoor_windows
      - hourly_forecast
      - today_planning
  hourly:
    deterministic_modules:
      - metadata
      - current_conditions
      - hourly_forecast
      - precip_timing
      - alert_digest
      - spc_convective_outlooks
      - id: area_forecast_discussion
        options:
          sections:
            - key_messages
            - short_term
      - spc_convective_discussion
      - weather_story

Unknown reports, unknown modules, duplicate modules, incompatible report/module combinations, duplicate stanza names, and invalid options fail config loading. area_forecast_discussion.options.sections may contain product, key_messages, short_term, and long_term. Empty or omitted sections includes all available AFD sections.

The module registry accepts all module IDs documented in Module Contract Internals. Unknown or unimplemented module IDs fail validation instead of being skipped.

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. Secret file names become environment variable names, and secret file contents become values. For distributor notification, this allows a file such as <secrets.directory>/DISTRIBUTOR_UPLOAD_TOKEN to supply the token referenced by notify.distributor.token_env.

Maintained Examples

• examples/minimal-config.yml: smallest useful config for generation and fetching.
• examples/config.yml: production-oriented config covering maintained fields.

Both example files are loaded by the config test suite.