Document distributor notification behavior

docs/internal/app-orchestration.md

@@ -7,8 +7,9 @@ This document describes the implemented workflow coordinator in `internal/app`.
 `internal/app` coordinates the top-level use cases after CLI parsing and config
 loading are complete. It resolves report definitions, fetches weather data,
 builds briefing and prompt-input artifacts, invokes Scriptorium through the
-adapter boundary, persists managed state, runs batches, and reads existing
-artifacts for inspection.
+adapter boundary, optionally notifies distributor through an app-owned notifier
+boundary, persists managed state, runs batches, and reads existing artifacts for
+inspection.
 
 ## Inputs And Outputs
 
@@ -22,13 +23,15 @@ Inputs:
 - resolved report definitions from `internal/report`
 - forecast bundles from `internal/adapters/weatherapi`
 - prior snapshots loaded from `internal/state`
-- optional renderer and state-store fakes for tests
+- optional renderer, notifier, and state-store fakes for tests
 
 Outputs:
 
 - generated report results with briefing, data package, preflight, report,
-  metadata, prior snapshot, Recent Changes, and Scriptorium result details
-- batch summaries with per-report status, artifact paths, and error text
+  metadata, prior snapshot, Recent Changes, Scriptorium result details, and
+  notification result when attempted
+- batch summaries with per-report status, artifact paths, error text, and
+  notification outcome when attempted
 - saved Weather API bundle JSON for fetch workflows
 - inspection JSON values for reports, metadata, briefings, data packages, prior
   snapshots, and source provenance
@@ -42,8 +45,9 @@ Scriptorium argv.
 
 Report selection and report identity policy come from `internal/report`.
 Weather API transport stays in `internal/adapters/weatherapi`. Scriptorium
-subprocess behavior stays in `internal/adapters/scriptorium`. Filesystem layout
-and persisted metadata stay in `internal/state`.
+subprocess behavior stays in `internal/adapters/scriptorium`. Distributor
+upload behavior stays in `internal/adapters/distributor`. Filesystem layout and
+persisted metadata stay in `internal/state`.
 
 ## Config Fields Used
 
@@ -52,6 +56,7 @@ and persisted metadata stay in `internal/state`.
 - `workspace.*` for filesystem state
 - `dayparts` for daily and outlook summarization
 - `recent_change.*` for structured Recent Changes thresholds
+- `notify.distributor.*` for optional notification after report generation
 
 Output copy flags are command request fields. They are not configuration
 defaults.
@@ -74,11 +79,15 @@ Single-report generation follows this order:
 12. Run Scriptorium report generation to the managed report path.
 13. Copy the managed report to the requested `--out` path when provided.
 14. Save metadata with the managed report path.
+15. If distributor notification is enabled, notify using the managed report
+    path as the source file.
 
 If render preflight returns both a result and an error, preflight JSON and
 metadata are persisted before the error is returned. If Scriptorium report
 generation returns an error after writing output, the managed report and
-metadata remain inspectable.
+metadata remain inspectable. Notification is not attempted after Weather API,
+briefing, prompt input, render, Scriptorium run, or metadata-save failures.
+`--out` copies are never used as notification source files.
 
 ## Batch Workflow
 
@@ -87,6 +96,10 @@ on Sunday. `run evening` resolves Daily Tomorrow. Batch output copy names come
 from report definitions. Batch generation continues independent reports after a
 failure, records each result, writes compact status lines to stderr, emits a
 JSON summary to stdout, and returns an aggregate error when any report failed.
+When notification is enabled, each successfully generated report is notified
+independently. Notification failure marks that report failed, records
+notification fields in the batch result, and does not stop later reports.
+`--out-dir` copies are never used as notification source files.
 
 ## Inspection Workflow
 
@@ -101,6 +114,8 @@ inspection view.
 - Weather API and briefing errors stop that report before Scriptorium runs.
 - Prompt input validation fails before render preflight.
 - Render and run errors preserve Scriptorium stderr and exit-code context.
+- Notification errors are wrapped with report ID, RunID, and managed report path
+  context and are recorded separately in batch results.
 - Metadata and artifact path errors include filesystem context.
 - Batch failures are recorded per report and surfaced through an aggregate
   batch error.
@@ -121,3 +136,5 @@ Inspect:
 - Render preflight precedes Scriptorium report generation.
 - Recent Changes are computed from structured briefing snapshots.
 - Metadata links artifacts produced for a run.
+- Distributor notification uses the managed Markdown report path, not extra
+  output copies.