# 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 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](../examples/minimal-config.yml). ```yaml weather_api: base_url: https://weather.api.example.com/ ``` `weather_api.base_url` is required for commands that collect 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 collection 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 uploads after successful report rendering. It is disabled by default and does not add CLI flags. When enabled, `generate ` uploads one distributor bundle for the generated report after final metadata is saved. `run morning` and `run evening` use `notify.distributor.batch`: when batch notification is enabled and every planned report succeeds, weatherreporter uploads one distributor bundle that contains all managed Markdown reports from that batch. - `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 single-report distributor pipeline IDs. Required when enabled. Default: empty. - `bundle_id_template`: template for single-report distributor bundle IDs. Default: `weatherreporter.{location_id}.{report_id}`. - `idempotency_key_template`: template for single-report distributor idempotency keys. Default: `{bundle_id}.{run_id}`. - `report_path_templates`: ordered list of templates for Markdown report paths inside distributor bundles. For `generate `, each rendered path maps to the generated report's managed Markdown source. For `run morning` and `run evening`, the templates are rendered once per included report and each rendered path maps that report's managed Markdown source into the one batch bundle. Default: ```yaml - "{valid_start_date}/{artifact_group}/{valid_start_date}-{artifact_group}-{run_id}.md" ``` - `batch.enabled`: whether batch distributor notification config is active when distributor notification is enabled. Default: `true`. - `batch.pipeline_id_template`: template for batch distributor pipeline IDs. Required when distributor notification and batch notification are enabled. Default: `weatherreporter`. - `batch.bundle_id_template`: template for batch distributor bundle IDs. Required when distributor notification and batch notification are enabled. Default: `weatherreporter.{location_id}.{batch}`. - `batch.idempotency_key_template`: template for batch distributor idempotency keys. Required when distributor notification and batch notification are enabled. Default: `{bundle_id}.{batch_run_id}`. Single-report templates support `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. Batch templates support `location_id`, `batch`, `batch_run_id`, and `batch_started_date`. Batch idempotency templates may also use `bundle_id`. `batch_started_date` is the batch start date in the effective report timezone. Batch bundle IDs identify a logical batch stream; batch idempotency keys identify a specific retryable batch attempt. Rendered report paths must be unique relative paths with `/` separators. They must not contain backslashes, empty path segments, `.`, `..`, `manifest.json`, or `.distributor.json`. In a batch upload, uniqueness is checked across every rendered bundle path for every included report before distributor is called. Managed Markdown report paths are the only upload source files; copies written with `--out` or `--out-dir` are never uploaded. 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 `three_day_outlook`, `weekend_outlook`, and `storm_report`. Hyphens and underscores are treated equivalently in report keys. Retired report keys are not supported. `reports.today` applies only to the Today Report. `reports.daily` applies only to the dated Daily Report. Each report entry supports: - `deterministic_modules`: ordered module list. Entries may be string module IDs or objects with `id` and optional `options`. Example: ```yaml 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 - daily_planning - 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](internal/module.md). 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 `/DISTRIBUTOR_UPLOAD_TOKEN` to supply the token referenced by `notify.distributor.token_env`. ## 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 maintained fields. Both example files are loaded by the config test suite.