Document internal component boundaries

docs/internal/report-registry.md

@@ -1,53 +1,59 @@
 # Report Registry Internals
 
-This document describes the implemented report identity and valid-period
-boundary.
+This document describes report identity, valid-period resolution, batch
+membership, and comparison declarations in `internal/report`.
 
 ## Purpose
 
-`internal/report` centralizes report IDs, prompt IDs, comparison strategies,
-valid-period resolution, report metadata, and scheduled batch membership.
+`internal/report` centralizes report definitions so report IDs, prompt IDs,
+default output names, comparison strategies, and valid periods are declared in
+one package.
 
-## Inputs and Outputs
+## Inputs And Outputs
 
 Inputs:
 
 - report ID or batch name
 - generation time
-- configured timezone
+- timezone
 - optional Daily date override
-- optional manual storm start and end times
+- optional Storm Report start and end times
 
 Outputs:
 
 - `report.Resolved` values with definition metadata and half-open valid periods
-- `report.Metadata` values suitable for later persisted run metadata
+- `report.Metadata` values used by briefing and persisted metadata builders
 
 ## Boundaries
 
 - This package defines report identity and time coverage only.
 - It does not fetch weather data, build briefings, compare snapshots, write
-  state, or call `scriptorium`.
+  state, parse CLI flags, or invoke Scriptorium.
 
-## Behavior
+## Config Fields Used
 
-- Daily Today covers one configured local civil day.
-- Daily Tomorrow covers the next configured local civil day.
-- 3-Day Outlook covers generation time through local midnight after the second
-  following local civil day.
-- Weekend Outlook covers Saturday 00:00 to Monday 00:00 Monday through
-  Thursday; Friday and Saturday cover the remaining weekend from Friday 18:00
-  or generation time, whichever is later.
-- Manual Storm Report uses explicit start and end times.
-- Morning batch resolves Daily Today and 3-Day Outlook, plus Weekend Outlook
-  except on Sunday.
-- Evening batch resolves Daily Tomorrow.
+The app supplies `weather_api.timezone` as a loaded `time.Location`. Report
+output path copying uses default output names from report definitions.
+
+## External Adapters Used
+
+None.
+
+## State Or Manifest Behavior
+
+None directly. Resolved metadata contributes RunID, report ID, prompt ID,
+generation time, timezone, and valid period to later briefing and state
+metadata.
+
+## Skip And Resume Behavior
+
+No resume behavior. Morning batch resolution skips Weekend Outlook on Sunday.
 
 ## Failure Behavior
 
-- Unknown report and batch names return actionable errors.
-- Sunday Weekend Outlook resolution returns an error.
-- Storm windows require start and end, with end after start.
+- Unknown reports and batch names return actionable errors.
+- Weekend Outlook resolution returns an error when resolved directly on Sunday.
+- Storm Report resolution requires start and end, with end after start.
 
 ## Tests
 
@@ -55,9 +61,11 @@ Inspect:
 
 - `internal/report/period_test.go`
 - `internal/app/app_test.go`
+- `internal/cli/root_test.go`
 
 ## Invariants
 
 - Report selection goes through the registry.
-- Valid periods are independent of rendered report text.
-- Prompt IDs and comparison strategies are declared with report definitions.
+- Daily Today and Daily Tomorrow both use `weather.daily_report`.
+- Valid periods are half-open intervals independent of rendered report text.
+- Comparison strategy is declared by report definition.