Refresh cleanup-related documentation

docs/internal/app-orchestration.md

@@ -4,37 +4,46 @@ This document describes the implemented workflow coordinator in `internal/app`.
 
 ## Purpose
 
-`internal/app` coordinates top-level use cases: generating one report through
-the shared report-generation path, running morning or evening batches, building
-inspectable briefing artifacts, fetching weather bundles, and reading existing
+`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.
 
 ## Inputs And Outputs
 
 Inputs:
 
-- app request structs containing config, report or batch selection, clock time,
-  optional report date, optional Storm Report bounds, output paths, renderer
-  fakes, or state-store fakes
+- `GenerateRequest` for one report command
+- `BatchRequest` for morning or evening batch commands
+- `FetchBundleRequest` for explicit bundle fetch and save workflows
+- `BriefingRequest` and `ReportRequest` for package-level orchestration tests
+  and internal composition
 - resolved report definitions from `internal/report`
-- forecast bundles from the Weather API adapter
-- prior briefing snapshots from `internal/state`
+- forecast bundles from `internal/adapters/weatherapi`
+- prior snapshots loaded from `internal/state`
+- optional renderer and state-store fakes for tests
 
 Outputs:
 
-- report results for generated report definitions with briefing, data package,
-  preflight, report, metadata, prior snapshot, Recent Changes, and Scriptorium
-  results
-- batch summaries with per-report status and artifact paths
+- 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
+- saved Weather API bundle JSON for fetch workflows
 - inspection JSON values for reports, metadata, briefings, data packages, prior
   snapshots, and source provenance
 
 ## Boundaries
 
-- The package coordinates workflow order.
-- It does not parse CLI flags, load YAML files directly, implement HTTP calls,
-  derive forecast facts, define report periods, compare Markdown, or construct
-  Scriptorium argv.
+`internal/app` owns workflow order and request composition. It does not parse
+CLI flags, load YAML files directly, implement HTTP transport, derive forecast
+facts, define report periods, compare rendered Markdown, or construct
+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`.
 
 ## Config Fields Used
 
@@ -44,36 +53,57 @@ Outputs:
 - `dayparts` for daily and outlook summarization
 - `recent_change.*` for structured Recent Changes thresholds
 
-## External Adapters Used
+Output copy flags are command request fields. They are not configuration
+defaults.
 
-- `internal/adapters/weatherapi` for forecast bundle fetching
-- `internal/adapters/scriptorium` for render preflight and report generation
-- `internal/state` filesystem store for persisted artifacts
+## Generation Workflow
 
-## State Or Manifest Behavior
+Single-report generation follows this order:
 
-Generation saves the briefing snapshot, data package, preflight result when
-available, rendered report, and metadata. Metadata links all managed artifact
-paths. Inspection workflows read existing state and do not fetch weather data or
-invoke Scriptorium.
+1. Resolve the command report to a `report.Resolved` value.
+2. Create or use a filesystem store.
+3. Locate any prior compatible snapshot through `internal/state`.
+4. Fetch a Weather API bundle.
+5. Build a report-specific briefing package.
+6. Save the briefing snapshot.
+7. Compute Recent Changes from structured prior and current briefings.
+8. Build and save the Scriptorium `data_package`.
+9. Run Scriptorium render preflight.
+10. Save preflight JSON when a render result is available.
+11. Save metadata for inspection.
+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.
 
-## Skip And Resume Behavior
+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.
 
-There is no resume workflow. Batch generation continues remaining independent
-reports after one report fails, then reports aggregate success and failure
-counts.
+## Batch Workflow
+
+`run morning` resolves Daily Today, 3-Day Outlook, and Weekend Outlook except
+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.
+
+## Inspection Workflow
+
+Inspection workflows load existing filesystem state only. They do not fetch
+weather data or invoke Scriptorium. Run-specific inspect commands share the same
+store and metadata lookup path, then load the requested artifact or derived
+inspection view.
 
 ## Failure Behavior
 
 - Resolve errors stop the requested workflow before fetching weather data.
-- Weather API or briefing errors stop that report before Scriptorium is called.
-- Render preflight runs before Scriptorium report generation.
-- If render preflight returns 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,
-  metadata and the managed report path remain inspectable.
-- Batch failures are recorded per report and surfaced through aggregate batch
-  failure.
+- 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.
+- Metadata and artifact path errors include filesystem context.
+- Batch failures are recorded per report and surfaced through an aggregate
+  batch error.
 
 ## Tests