Document internal component boundaries

docs/internal/briefing.md

@@ -5,63 +5,58 @@ This document describes the implemented briefing package boundary.
 ## Purpose
 
 `internal/briefing` builds structured report-specific briefing packages from
-forecast summaries and report metadata. The package currently implements Daily
-Today, Daily Tomorrow, 3-Day Outlook, Weekend Outlook, and Storm Report
-briefing content.
+resolved report metadata, forecast bundles, and derived forecast summaries.
+Briefings are curated inputs for prompt data packages, not rendered report
+prose.
 
-## Inputs and Outputs
+## Inputs And Outputs
 
 Inputs:
 
-- resolved report definition and valid period
-- forecast bundle
-- derived forecast summary or summaries
+- resolved report definition, generation time, timezone, and valid period
+- forecast bundle with source provenance and warnings
+- derived daily or period summaries where required
 - configured units and timezone
 
-Output:
+Outputs:
 
-- `briefing.Package` JSON containing common metadata and report-specific
-  briefing content
+- `briefing.Package` with common metadata and one report-specific content
+  object for Daily, 3-Day, Weekend, or Storm Report
+- optional JSON file written by `briefing.Save`
 
 ## Boundaries
 
-- Briefings are structured weather facts and context for later prompt input.
-- This package does not fetch weather data, compare prior snapshots, build
-  `scriptorium` data packages, or render final report prose.
+- This package selects and shapes weather facts for prompts.
+- It does not fetch weather data, compare prior snapshots, build
+  `data_package` files, invoke Scriptorium, or write workflow metadata.
 
-## Behavior
+## Config Fields Used
 
-- Common metadata includes schema version, RunID, report ID, variant, prompt ID,
-  generation time, units, timezone, valid period, source location, source
-  provenance, hashes, and source warnings.
-- Daily content includes bottom-line inputs, daypart summaries, relevant alerts,
-  outdoor window inputs, narrative periods, discussion context, and weather
-  story context when available.
-- Daily Tomorrow also includes planning inputs for morning readiness,
-  commute/school/workday concerns, and what may change overnight.
-- 3-Day content includes one summary per local day or partial day, with overall
-  character, temperature range, precipitation, wind, risk, outdoor-window, and
-  alert inputs, plus broader discussion and weather-story context when
-  available.
-- Weekend content uses the same daily outlook summaries and adds planning
-  inputs for best outdoor windows, worst weather windows, rain/storm timing,
-  comfort concerns, and confidence or uncertainty context.
-- Storm content uses the explicit event window and includes event headline
-  inputs, hazards, most-likely scenario inputs, reasonable worst-case inputs,
-  confidence and uncertainty inputs, watch items, active alerts, relevant
-  hourly and narrative forecast periods, and available discussion or weather
-  story context.
-- Briefing JSON is written atomically by `briefing.Save`.
+The package receives configured units and timezone from the app layer. Daypart
+configuration is consumed by `internal/forecast` before briefing builders run.
+
+## External Adapters Used
+
+None directly.
+
+## State Or Manifest Behavior
+
+`briefing.Save` writes briefing JSON atomically. Managed workspace placement is
+owned by `internal/state`.
+
+## Skip And Resume Behavior
+
+None. Builders either return a complete briefing package or an error.
 
 ## Failure Behavior
 
-- Daily briefing construction requires a Daily report definition and a derived
-  daily forecast summary.
+- Daily briefing construction requires a Daily report definition and derived
+  daily summary.
 - 3-Day briefing construction requires a 3-Day report definition and at least
-  one derived daily summary in the outlook period.
+  one derived summary.
 - Weekend briefing construction requires a Weekend report definition and at
-  least one derived daily summary in the weekend period.
-- Storm briefing construction requires a Storm Report definition and a forecast
+  least one derived summary.
+- Storm briefing construction requires a Storm Report definition and forecast
   bundle.
 - Save failures include path and operation context.
 
@@ -74,11 +69,11 @@ Inspect:
 - `internal/briefing/weekend_test.go`
 - `internal/briefing/storm_test.go`
 - `internal/app/app_test.go`
-- `internal/cli/root_test.go`
 
 ## Invariants
 
-- Weather facts come from normalized and derived source data.
-- Briefing output remains JSON-inspectable.
-- LLM prompt input packaging and `scriptorium` execution remain outside this
+- Briefings contain structured weather facts and source context.
+- Common metadata includes RunID, report ID, prompt ID, valid period, source
+  provenance, source hashes, and source warnings.
+- LLM prompt input packaging and Scriptorium execution remain outside this
   boundary.