Document distributor notification behavior

docs/operations.md

@@ -19,7 +19,10 @@ weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00
 Each command resolves a report period, fetches a Weather API bundle, builds a
 briefing, builds a prompt input data package, runs `scriptorium render`, runs
 `scriptorium run`, and writes managed artifacts under the configured workspace.
-`--out PATH` writes an extra Markdown copy for the current generated report.
+When distributor notification is enabled, weatherreporter uploads the managed
+Markdown report after `scriptorium run` succeeds and final metadata is saved.
+`--out PATH` writes an extra Markdown copy for the current generated report; it
+is not used as the distributor upload source.
 
 Implemented batch commands:
 
@@ -36,7 +39,8 @@ nonzero when any report failed. When notification is configured, the summary and
 status lines include notification status, accepted distributor run ID, or
 notification error fields for each attempted report. `--out-dir PATH` writes
 extra Markdown copies using report default filenames such as `daily.md`,
-`three-day.md`, `weekend.md`, and `tomorrow.md`.
+`three-day.md`, `weekend.md`, and `tomorrow.md`; these copies are not used as
+distributor upload sources.
 
 ## Filesystem Layout
 
@@ -121,7 +125,38 @@ Each generated report writes metadata that links:
 
 Batch summaries include report status, error text when applicable, notification
 outcome when attempted, valid period, and known artifact paths for each
-attempted report.
+attempted report. Notification fields are `notificationStatus`,
+`notificationRunId`, and `notificationError`.
+
+## Distributor Notification
+
+Distributor notification is configured with `notify.distributor` and is disabled
+by default. When enabled, weatherreporter uploads exactly one file per
+successfully generated report: the managed Markdown report path recorded in the
+report result and metadata. Extra copies written by `--out` or `--out-dir` are
+operator conveniences only.
+
+The default bundle ID is derived from producer name, location ID, report ID, and
+RunID:
+
+```text
+weatherreporter.{location_id}.{report_id}.{run_id}
+```
+
+The default idempotency key is the rendered bundle ID. The default bundle path
+for the Markdown file is the report definition's batch output name, such as
+`daily.md`, `tomorrow.md`, `three-day.md`, or `weekend.md`.
+
+Notification happens after final metadata save. Weather API, briefing,
+data-package, render preflight, Scriptorium run, and metadata-save failures do
+not trigger notification. A notification failure fails that report. In a batch,
+other reports continue, the failed report includes notification fields in the
+JSON summary, and the batch returns nonzero.
+
+Weatherreporter is responsible for selecting the managed Markdown report,
+constructing a source bundle, and submitting it to the configured distributor
+HTTP endpoint. Distributor remains responsible for destination routing,
+publication, and any downstream Markdown-to-HTML transformation.
 
 ## Inspection
 
@@ -167,6 +202,8 @@ A failed generation run may still leave useful artifacts:
   preflight JSON and metadata are written for inspection.
 - If `scriptorium run` exits nonzero after writing a report, the managed report
   and metadata remain available.
+- If distributor notification fails, report artifacts and final metadata remain
+  available, but the report or batch command returns nonzero.
 - For batch commands, inspect the stdout JSON summary first, then inspect the
   artifact paths for each failed report.