Clarify module package documentation

docs/internal/briefing.md

@@ -1,49 +1,60 @@
 # Module Builder Internals
 
-This document describes the implemented module builder boundary in
-`internal/briefing`.
+This document describes module builder behavior in `internal/briefing`.
 
 ## Purpose
 
-`internal/briefing` builds prompt-facing module values from resolved report
-metadata, collected weather data, and derived forecast facts. These values are
-curated prompt inputs, not rendered report prose or durable report snapshots.
+`internal/briefing` turns report metadata, collected weather data, and derived
+forecast facts into prompt-facing module outputs. The package also owns the
+module registry used to validate report composition and config overrides.
+
+Module outputs are structured prompt inputs. They are not rendered report prose
+and they are not persisted by this package.
 
 ## Inputs And Outputs
 
 Inputs:
 
 - resolved report definition, generation time, timezone, and valid period
-- `weatherdata.Bundle` with source provenance and warnings
-- derived daily, period, or storm-window facts where required
+- collected facts built from `weatherdata.Bundle`
+- derived daily, daypart, precipitation, alert, and storm-window facts where
+  required
 - configured units, timezone, and descriptive location context
+- typed module options from report defaults or config overrides
 
 Outputs:
 
-- module registry definitions for known module IDs, stanza names, option
-  shapes, fact requirements, report compatibility, and missing-data behavior
-- source-oriented module outputs for `metadata`, `current_conditions`,
-  `alert_digest`, `area_forecast_discussion`, and `weather_story`
-- derived module outputs such as daily summaries, daypart summaries,
-  precipitation timing, outdoor windows, and tomorrow planning
-- optional current conditions and weather story module outputs when those
-  Weather API sources are available
+- `ModuleDefinition` values with module ID, stanza name, option type,
+  supported reports, fact requirements, missing-data behavior, and builder
+- `module.Output` values for source-oriented stanzas:
+  `metadata`, `current_conditions`, `alert_digest`,
+  `area_forecast_discussion`, and `weather_story`
+- `module.Output` values for derived stanzas:
+  `derived_daily_summary`, `derived_daypart_summaries`, `precip_timing`,
+  `outdoor_windows`, and `tomorrow_planning`
+
+The registry also contains accepted composition entries for modules that do not
+emit stanzas until a builder exists. App orchestration skips those entries when
+constructing snapshots.
 
 ## Boundaries
 
-- This package selects and shapes weather facts for prompts.
-- It owns module registry validation and module builder behavior.
-- It does not fetch weather data, compare prior snapshots, build
-  `data_package` files, invoke Scriptorium, or write workflow metadata.
+- This package selects and shapes already-collected weather facts for prompts.
+- It validates module composition against report compatibility and option
+  types.
+- It does not fetch weather data, compare prior snapshots, write module
+  snapshots, build YAML data packages, invoke Scriptorium, or write workflow
+  metadata.
 
 ## Config Fields Used
 
-The package receives configured units and timezone from the app layer. Daypart
-configuration is consumed by `internal/facts` before module builders run.
-Configured `location` values are prompt context only; Weather API
+The app layer passes effective units, timezone, and location context into the
+module context. `internal/facts` consumes daypart configuration before module
+builders run. Configured `location` values are prompt context only; Weather API
 `sourceLocationId` and `sourceLocation` remain source provenance.
-Current conditions are copied from the normalized `/conditions/current` bundle
-source only; observation station and timestamp fields remain provenance.
+
+`area_forecast_discussion` uses optional `sections` configuration to include a
+subset of discussion fields.
 
 ## External Adapters Used
 
@@ -51,13 +62,13 @@ None directly.
 
 ## State Or Manifest Behavior
 
-None. Module snapshots and prompt input data packages are persisted by
-`internal/state` and composed by `internal/app`.
+None. `internal/app` collects module outputs into a `module.Snapshot`, and
+`internal/state` persists that snapshot.
 
 ## Skip And Resume Behavior
 
-None. Builders either return a module output, omit optional unavailable data,
-or return an error for invalid required inputs.
+None. Builders either emit a module output, omit optional unavailable data, or
+return an error for invalid required inputs.
 
 ## Failure Behavior
 
@@ -65,8 +76,9 @@ or return an error for invalid required inputs.
   available.
 - Module registry construction rejects duplicate module IDs and duplicate
   stanza names.
-- Module composition validation rejects unknown modules, duplicate modules,
-  incompatible report/module combinations, and invalid typed options.
+- Composition validation rejects unknown modules, duplicate modules,
+  incompatible report/module combinations, duplicate stanza names, and invalid
+  option shapes.
 - Source-oriented module builders omit missing optional current conditions,
   forecast discussion, and weather story stanzas.
 - Alert digest output distinguishes checked empty alert data from missing alert
@@ -86,5 +98,4 @@ Inspect:
 - Module outputs contain structured weather facts and source context.
 - Common metadata includes RunID, report ID, prompt ID, valid period, source
   provenance, source hashes, source warnings, and configured prompt location.
-- LLM prompt input packaging and Scriptorium execution remain outside this
-  boundary.
+- Prompt input packaging and Scriptorium execution remain outside this package.