From 15ee4af1a12ce37382be82c1a6e1528b71b4ed26 Mon Sep 17 00:00:00 2001
From: Eric Rakestraw <eric@rakestraw.us>
Date: Sat, 20 Jun 2026 03:00:29 +0000
Subject: [PATCH] Document report-specific distributor paths

---
 docs/config.md                       | 28 +++++++++++++++++++++++++---
 docs/internal/distributor-adapter.md |  4 ++++
 examples/config.yml                  |  4 ++++
 3 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/docs/config.md b/docs/config.md
index ecfebb1..03e8754 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -115,10 +115,13 @@ contains all managed Markdown reports from that batch.
 
 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
+`valid_start_time`, `valid_end_time`, `valid_start_stamp`, `valid_end_stamp`,
+and `storm_id`. 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`.
+`storm_id` is derived from the storm report valid period as
+`{valid_start_stamp}-{valid_end_stamp}`; it renders empty for non-storm
+reports. `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
@@ -137,6 +140,18 @@ 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.
 
+Distributor bundle paths are report-specific. Weatherreporter uses
+`reports.<report>.distributor.path_templates` when that override is configured;
+otherwise it uses the report definition defaults:
+
+- `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`
+
 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.
@@ -211,12 +226,19 @@ Each report entry supports:
 
 - `deterministic_modules`: ordered module list. Entries may be string module
   IDs or objects with `id` and optional `options`.
+- `distributor.path_templates`: optional ordered distributor bundle path
+  templates for this report. If omitted, the report definition defaults are
+  used. If present, the list must contain at least one template.
 
 Example:
 
 ```yaml
 reports:
   daily:
+    distributor:
+      path_templates:
+        - "daily/{valid_start_date}/{run_id}.md"
+        - "daily/{valid_start_date}/index.md"
     deterministic_modules:
       - metadata
       - current_conditions
diff --git a/docs/internal/distributor-adapter.md b/docs/internal/distributor-adapter.md
index edb8c6b..16424d9 100644
--- a/docs/internal/distributor-adapter.md
+++ b/docs/internal/distributor-adapter.md
@@ -68,6 +68,10 @@ idempotency key from `notify.distributor.batch.*`, resolves report-specific
 path templates once per included report, and passes the resulting multi-file
 request to this adapter.
 
+Report-specific path resolution happens entirely in the app layer. Explicit
+`reports.<report>.distributor.path_templates` overrides take precedence over
+report definition defaults.
+
 The token value is read from the environment variable named by `token_env`
 after config loading and `secrets.directory` processing.
 
diff --git a/examples/config.yml b/examples/config.yml
index ec61a10..610dedb 100644
--- a/examples/config.yml
+++ b/examples/config.yml
@@ -72,6 +72,10 @@ recent_change:
 
 reports:
   daily:
+    distributor:
+      path_templates:
+        - "daily/{valid_start_date}/{run_id}.md"
+        - "daily/{valid_start_date}/index.md"
     deterministic_modules:
       - metadata
       - current_conditions