Clarify module package documentation

docs/internal/module.md

@@ -1,46 +1,90 @@
 # Module Contract Internals
 
-This document describes the implemented module contract boundary.
+This document describes the module contract in `internal/module`.
 
 ## Purpose
 
-`internal/module` defines stable module IDs, typed configuration items, module
-outputs, and module snapshots. It is a shared contract imported by report
-definitions and module registry code.
+`internal/module` defines the shared identifiers and data envelopes used for
+prompt-facing modules. Report definitions use module IDs for composition,
+module builders produce outputs with stanza names, prompt input packages consume
+snapshots, and Recent Changes compares snapshot stanzas.
 
 ## Inputs And Outputs
 
 Inputs:
 
-- ordered `module.ConfigItem` values from report definitions
-- `module.Output` values assembled by callers
+- ordered `module.ConfigItem` values from report definitions or config
+  overrides
+- `module.Output` values produced by module builders
 
 Outputs:
 
 - stable `module.ID` constants
-- typed option structs for known modules
-- `module.Snapshot` with ordered outputs and schema version
+- typed option structs for registered modules
+- `module.Snapshot` with schema version `weatherreporter.modules.v1`
+- ordered snapshot outputs with module ID, stanza name, and typed value
 - typed stanza lookup through `module.StanzaValue`
 
+## Registered Module IDs
+
+The registry recognizes these IDs:
+
+- `metadata`
+- `current_conditions`
+- `derived_daily_summary`
+- `derived_daypart_summaries`
+- `hourly_table`
+- `precip_timing`
+- `alert_digest`
+- `area_forecast_discussion`
+- `weather_story`
+- `forecast_delta`
+- `outdoor_windows`
+- `tomorrow_planning`
+- `weekend_planning`
+- `storm_window_summary`
+
+Modules with builders emit stanzas into module snapshots. Registered modules
+without builders are valid composition entries but do not emit snapshot stanzas.
+That keeps report composition declarations centralized while limiting prompt
+packages to data the application builds.
+
+## Options
+
+Most modules use an empty options struct. `area_forecast_discussion` accepts:
+
+```yaml
+sections:
+  - product
+  - key_messages
+  - short_term
+  - long_term
+```
+
+An omitted or empty `sections` list includes all available discussion sections.
+Invalid option shapes fail during config normalization or composition
+validation.
+
 ## Boundaries
 
-- This package owns shared module identifiers and output envelope contracts.
-- It does not define report IDs, build prompt stanzas, fetch weather data,
-  derive facts, write state, or invoke Scriptorium.
+- This package owns module identifiers, config item envelopes, output
+  envelopes, snapshot validation, and typed stanza lookup.
+- It does not define report IDs, execute builders, fetch weather data, derive
+  forecast facts, write state, or invoke Scriptorium.
 
 ## State Or Manifest Behavior
 
-`module.Snapshot` uses schema version `weatherreporter.modules.v1`. Snapshot
-validation rejects duplicate module outputs and duplicate stanza names while
-preserving output order.
+`module.Snapshot` values are persisted by `internal/state` as JSON. Snapshot
+validation rejects missing schema version, missing module IDs, missing stanza
+names, duplicate module outputs, and duplicate stanza names while preserving
+output order.
 
 ## Failure Behavior
 
-- Snapshot validation fails when schema version, module ID, or stanza name is
-  missing.
-- Snapshot validation fails on duplicate module IDs or duplicate stanza names.
-- Typed stanza lookup returns `found=false` for missing stanzas and wraps JSON
-  marshal/decode failures with stanza context.
+- Snapshot construction fails for duplicate module outputs or duplicate stanza
+  names.
+- Typed stanza lookup returns `found=false` for missing stanzas.
+- Typed stanza lookup wraps JSON marshal/decode failures with stanza context.
 
 ## Tests
 
@@ -54,5 +98,5 @@ Inspect:
 
 - `internal/module` does not import `internal/report`.
 - Module IDs are stable strings.
-- Each module output has exactly one stanza name and one typed value.
+- Each emitted module output has exactly one stanza name and one typed value.
 - Snapshot output order is caller-owned and preserved.