Document batch distributor uploads

docs/internal/app-orchestration.md

@@ -32,7 +32,7 @@ Outputs:
   result details, generated-text artifact paths when applicable, and
   notification result when attempted
 - batch summaries with per-report status, artifact paths, error text, and
-  notification outcome when attempted
+  one top-level batch notification result when attempted or skipped
 - saved Weather API bundle JSON for explicit bundle collection workflows
 - inspection JSON values for reports, metadata, module snapshots, data
   packages, prior snapshots, and source provenance
@@ -74,7 +74,8 @@ 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
+- `notify.distributor.*` for optional single-report and batch notification
+  after report generation
 
 Output copy flags are command request fields. They are not configuration
 defaults.
@@ -151,10 +152,26 @@ A collection failure stops the batch before planning or report generation.
 After planning succeeds, 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.
+
+Batch report generation suppresses per-report distributor notification. After
+all planned reports finish, app orchestration evaluates batch notification:
+
+1. If distributor notification is disabled, the batch notification result is
+   omitted.
+2. If batch notification is disabled, the batch notification result is omitted
+   and there is no per-report fallback upload.
+3. If any planned report failed, the batch notification result is `skipped`
+   with reason `one or more reports failed`, and distributor is not called.
+4. If every report succeeded, app orchestration renders batch pipeline, bundle
+   ID, and idempotency key templates, renders `report_path_templates` for each
+   included report, validates every managed source path and bundle path, checks
+   duplicate bundle paths across the batch, calls the notifier once with a
+   multi-file request, and saves a batch notification debug artifact.
+
+Batch notification failure records a top-level failed notification, increments
+the aggregate batch failure count, and returns an aggregate batch error without
+marking individual report items failed. `--out-dir` copies are never used as
+notification source files.
 
 ## Inspection Workflow
 
@@ -172,8 +189,10 @@ inspection view.
 - Render and run errors preserve Scriptorium stderr and exit-code context.
 - Generated-text report errors preserve available intermediate artifacts and do
   not create extra output copies.
-- Notification errors are wrapped with report ID, RunID, and managed report path
-  context and are recorded separately in batch results.
+- Single-report notification errors are wrapped with report ID, RunID, and
+  managed report path context.
+- Batch notification errors are recorded on the top-level batch notification
+  result and do not change individual report item status.
 - Metadata and artifact path errors include filesystem context.
 - Batch failures are recorded per report and surfaced through an aggregate
   batch error.
@@ -201,5 +220,9 @@ Inspect:
   a raw data package.
 - Recent Changes are computed from structured module snapshots.
 - Metadata links artifacts produced for a run.
-- Distributor notification maps the managed Markdown report path to configured
-  bundle paths; extra output copies are not upload sources.
+- Single-report distributor notification maps the managed Markdown report path
+  to configured bundle paths.
+- Batch distributor notification maps each included managed Markdown report
+  path to bundle paths rendered for that report and uploads once for the
+  batch.
+- Extra output copies are not upload sources.