Document distributor notification behavior

docs/troubleshooting.md

@@ -199,6 +199,101 @@ metadata, sources, briefing, and data package for that RunID.
 
 Relevant docs: [CLI reference](cli.md), [Operations guide](operations.md).
 
+## Invalid Secrets Directory
+
+Symptom: config loading fails with `read secrets directory`, `secret file`, or
+environment variable name context.
+
+Likely cause: `secrets.directory` points to a missing directory or contains an
+invalid entry. Secret entries must be regular files directly under the
+configured directory, and file basenames must match
+`[A-Za-z_][A-Za-z0-9_]*`.
+
+Diagnostic: list the configured directory and inspect entry names and file
+types. Do not print secret file contents.
+
+Safe fix: create the directory, remove subdirectories or symlinks, fix invalid
+filenames, and ensure the weatherreporter process can read each secret file.
+
+Relevant docs: [Configuration reference](config.md).
+
+## Distributor Token Is Missing
+
+Symptom: notification fails with a message that the distributor token
+environment variable is not set.
+
+Likely cause: `notify.distributor.enabled` is true, but the environment
+variable named by `notify.distributor.token_env` was not populated directly or
+through `secrets.directory`.
+
+Diagnostic: check `notify.distributor.token_env`, then verify a matching secret
+file exists under `secrets.directory` or that the process environment includes
+the variable. Do not print the token value.
+
+Safe fix: create a readable secret file whose basename matches `token_env`, or
+set the environment variable through the service manager.
+
+Relevant docs: [Configuration reference](config.md),
+[Operations guide](operations.md).
+
+## Distributor Upload Conflict
+
+Symptom: notification fails with idempotency conflict context.
+
+Likely cause: the same idempotency key was reused for different bundle content.
+By default the key derives from bundle ID, which includes location ID, report
+ID, and RunID.
+
+Diagnostic: inspect the failed batch JSON or stderr line for bundle and
+idempotency context. Compare the configured templates with the report RunID and
+report path.
+
+Safe fix: keep idempotency templates stable for retries of the same generated
+report, but do not reuse the same rendered key for different generated report
+content.
+
+Relevant docs: [Operations guide](operations.md),
+[Distributor adapter internals](internal/distributor-adapter.md).
+
+## Distributor Upload Rejected
+
+Symptom: notification fails with distributor upload rejection, HTTP status, or
+bundle validation context.
+
+Likely cause: the distributor endpoint rejected the token, bundle ID,
+idempotency key, source file, or bundle path.
+
+Diagnostic: inspect stdout JSON or stderr status lines for
+`notificationError`. Confirm `notify.distributor.endpoint`,
+`notify.distributor.report_path_template`, and token configuration. Token values
+are redacted from weatherreporter errors.
+
+Safe fix: fix the endpoint, token, templates, or distributor-side upload
+configuration. The weatherreporter upload source is the managed Markdown report,
+not `--out` or `--out-dir` copies.
+
+Relevant docs: [Configuration reference](config.md),
+[Operations guide](operations.md),
+[Distributor adapter internals](internal/distributor-adapter.md).
+
+## Distributor Unavailable
+
+Symptom: notification fails with network, timeout, or service unavailable
+context.
+
+Likely cause: the configured distributor endpoint is unreachable, slow, or
+temporarily unavailable.
+
+Diagnostic: check network access from the weatherreporter host to
+`notify.distributor.endpoint`. For batch runs, inspect which reports have
+`notificationStatus: "failed"`.
+
+Safe fix: restore distributor service availability and rerun the affected
+report or batch. Stable idempotency keys make retrying the same generated report
+safe unless the distributor reports a conflict.
+
+Relevant docs: [Operations guide](operations.md).
+
 ## Unknown RunID
 
 Symptom: an inspect command fails with `metadata for run id ... was not found`.