Refresh cleanup-related documentation

docs/internal/report-registry.md

@@ -1,59 +1,81 @@
 # Report Registry Internals
 
 This document describes report identity, valid-period resolution, batch
-membership, and comparison declarations in `internal/report`.
+membership, output naming, artifact grouping, and comparison declarations in
+`internal/report`.
 
 ## Purpose
 
-`internal/report` centralizes report definitions so report IDs, prompt IDs,
-artifact groups, batch output names, generated-report eligibility, comparison
-compatibility, comparison strategies, and valid periods are declared in one
-package.
+`internal/report` is the canonical source for report definitions. App, state,
+briefing, and CLI wiring consume resolved definitions instead of owning report
+identity policy themselves.
 
-## Inputs And Outputs
+## Definition Fields
 
-Inputs:
+Each report definition declares:
 
-- report ID or batch name
-- generation time
-- timezone
-- optional Daily date override
-- optional Storm Report start and end times
+- report ID and display name
+- Scriptorium prompt ID
+- valid-period resolver
+- comparison strategy
+- managed artifact group
+- batch output copy filename
+- generated-report eligibility
+- prior-report compatibility list
+- morning or evening batch membership
 
-Outputs:
+## Implemented Reports
 
-- `report.Resolved` values with definition metadata and half-open valid periods
-- `report.Metadata` values used by briefing and persisted metadata builders
+| Report | ID | Prompt | Artifact group | Batch copy | Prior compatibility |
+| --- | --- | --- | --- | --- | --- |
+| Daily Today | `daily_today` | `weather.daily_report` | `daily` | `daily.md` | Daily Today, Daily Tomorrow |
+| Daily Tomorrow | `daily_tomorrow` | `weather.daily_report` | `daily` | `tomorrow.md` | Daily Today, Daily Tomorrow |
+| 3-Day Outlook | `three_day` | `weather.three_day_outlook` | `three-day` | `three-day.md` | 3-Day Outlook |
+| Weekend Outlook | `weekend` | `weather.weekend_outlook` | `weekend` | `weekend.md` | Weekend Outlook |
+| Storm Report | `storm` | `weather.storm_report` | `storm` | `storm.md` | Storm Report |
+
+All implemented report definitions are eligible for generation.
+
+## Valid Periods
+
+- Daily Today covers the selected local civil day, or the current local civil
+  day when no date override is supplied.
+- Daily Tomorrow covers the next local civil day from generation time.
+- 3-Day Outlook covers the interval from generation time through local midnight
+  three days later.
+- Weekend Outlook covers the upcoming weekend window and is not scheduled for
+  Sunday morning batch resolution.
+- Storm Report covers an explicit event window supplied by the caller.
+
+Storm event windows can be parsed from local `YYYY-MM-DDTHH:MM` timestamps in
+the configured timezone or RFC3339 timestamps with explicit offsets. End time
+must be after start time.
 
 ## Boundaries
 
-- This package defines report identity and time coverage only.
-- It does not fetch weather data, build briefings, compare snapshots, write
-  state, parse CLI flags, or invoke Scriptorium.
+`internal/report` defines report metadata and time coverage. It does not fetch
+weather data, build briefings, compare briefing contents, write state, parse CLI
+flags, or invoke Scriptorium.
+
+The CLI owns public command names. The app maps those command names to report
+IDs, then uses the registry for report policy.
 
 ## Config Fields Used
 
 The app supplies `weather_api.timezone` as a loaded `time.Location`. Batch
 output path copying uses batch output names from report definitions.
 
-## External Adapters Used
+## State And App Usage
 
-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. Artifact groups declared by report definitions are used by state path
-construction.
-
-## Skip And Resume Behavior
-
-No resume behavior. Morning batch resolution skips Weekend Outlook on Sunday.
+- State paths use `ArtifactGroup`.
+- Batch output copies use `BatchOutputName`.
+- Generation checks `Generated`.
+- Prior lookup checks `CompatiblePriorIDs` and the comparison strategy.
+- RunIDs include the resolved report ID.
 
 ## Failure Behavior
 
-- Unknown reports and batch names return actionable errors.
+- Unknown report IDs 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.