Document curated data package exports

docs/internal/module.md

@@ -5,9 +5,9 @@ This document describes the module contract in `internal/module`.
 ## Purpose
 
 `internal/module` defines the shared identifiers and data envelopes used for
-prompt-facing modules. Report definitions use module IDs for composition,
+report modules. Report definitions use module IDs for composition, module
-module builders produce outputs with stanza names, prompt input packages consume
+builders produce rich outputs with stanza names, prompt input packages consume
-snapshots, and Recent Changes compares snapshot stanzas.
+runtime prompt export values, and Recent Changes compares snapshot stanzas.
 
 ## Inputs And Outputs
 
@@ -23,8 +23,38 @@ Outputs:
 - 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
+- runtime-only prompt export values on module outputs
+- `module.Output.DataPackageValue`, which selects the prompt export value and
+  falls back to the rich value for hand-built or loaded snapshots
 - typed stanza lookup through `module.StanzaValue`
 
+## Rich Values And Prompt Exports
+
+Each `module.Output` has two value surfaces:
+
+- `Value`: the rich module value used by templates, module snapshots,
+  inspection, Recent Changes, and render contexts.
+- `PromptValue`: the runtime-only prompt export used when building Scriptorium
+  data packages.
+
+`PromptValue` is deliberately excluded from module snapshot JSON. Persisted
+module snapshots keep only the rich `value` field so inspection and
+render-context reconstruction keep the full deterministic template surface.
+
+The `internal/briefing` module registry attaches prompt export values when it
+builds module outputs. Modules without a custom exporter use default
+pass-through behavior, so their prompt value is the same as their rich value.
+Modules that need cleanup own typed prompt export structs near the module
+builder. Current custom prompt exports are:
+
+- `current_conditions`
+- `hourly_forecast`
+- `derived_daypart_summaries`
+
+Custom exporters remove template-only helpers or confusing duplicates from the
+data package without shrinking the rich module structs used by templates.
+Exporter failures include module ID and stanza context.
+
 ## Registered Module IDs
 
 The registry recognizes these IDs:
@@ -186,7 +216,7 @@ validation.
 
 ## SPC Convective Module Outputs
 
-`spc_convective_outlooks` emits a prompt-facing risk-product stanza with:
+`spc_convective_outlooks` emits a risk-product stanza with:
 
 - `checked`
 - `as_of`
@@ -221,7 +251,8 @@ meet the severity threshold.
 `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.
+output order. Snapshot JSON contains rich module values only; runtime prompt
+export values are not persisted.
 
 ## Failure Behavior
 
@@ -242,5 +273,8 @@ Inspect:
 
 - `internal/module` does not import `internal/report`.
 - Module IDs are stable strings.
-- Each emitted module output has exactly one stanza name and one typed value.
+- Each emitted module output has exactly one stanza name and one rich typed
+  value.
+- Built module outputs have a data-package value, either from a custom prompt
+  exporter or from default pass-through behavior.
 - Snapshot output order is caller-owned and preserved.

docs/internal/prompt-input.md

@@ -5,13 +5,15 @@ This document describes YAML prompt data package construction in
 
 ## Purpose
 
-`internal/promptinput` converts report metadata, an ordered module snapshot,
+`internal/promptinput` converts report metadata, ordered module outputs, Recent
-Recent Changes, and source warnings into the `data_package` file passed to
+Changes, and source warnings into the `data_package` file passed to
 Scriptorium.
 
 The persisted data package is YAML with schema version
-`weatherreporter.data_package.v2`. It is separate from the JSON module snapshot
+`weatherreporter.data_package.v3`. It is separate from the JSON module snapshot
-used for inspection and comparison.
+used for inspection and comparison. Data packages serialize each module
+output's prompt export value, not necessarily the full rich module value saved
+in the module snapshot.
 
 ## Inputs And Outputs
 
@@ -32,7 +34,7 @@ Outputs:
 The YAML shape includes:
 
 ```yaml
-schema_version: weatherreporter.data_package.v2
+schema_version: weatherreporter.data_package.v3
 run_id: <run_id>
 report:
   id: <report_id>
@@ -68,6 +70,32 @@ Prompt-facing module intervals use local `period_begins` and `period_ends`
 labels; canonical report metadata and source timestamps remain structured
 timestamps where applicable.
 
+## Module Export Boundary
+
+Data packages are curated prompt inputs. They are not full template render
+contexts and should not be treated as a dump of every field available to Go
+templates.
+
+When module outputs are built by `internal/briefing`, the registry attaches a
+runtime prompt export value. `internal/promptinput` serializes
+`output.DataPackageValue()` for each stanza. That helper prefers the runtime
+prompt export and falls back to the rich `Value` when no prompt export is set,
+which keeps loaded snapshots and hand-built tests usable.
+
+Modules without custom export policy use pass-through behavior. Modules with
+custom exports currently include:
+
+- `current_conditions`: omits lower-case condition text and duplicate
+  wind-direction text.
+- `hourly_forecast`: omits hour labels, lower-case description text, and the
+  template precipitation-mention helper while keeping forecast facts.
+- `derived_daypart_summaries`: omits deterministic sentence-construction
+  helpers while keeping daypart period, condition, temperature trend,
+  precipitation, wind, notable-condition, hazard, and alert-relevance facts.
+
+The rich module snapshot and generated-template render context still contain
+the helper fields used by deterministic Markdown templates.
+
 Daily Report, Today Report, Tomorrow Report, and Hourly Report module snapshots
 use the same package schema and categories when converted into prompt input.
 The default hourly module list places
@@ -101,8 +129,8 @@ Current categories are:
 - This package owns prompt package schema, YAML marshaling, YAML loading, and
   validation.
 - It does not fetch weather data, derive forecast summaries, execute modules,
-  find prior snapshots, compare changes, choose artifact paths, or invoke
+  choose module prompt export shapes, find prior snapshots, compare changes,
-  Scriptorium.
+  choose artifact paths, or invoke Scriptorium.
 
 ## Config Fields Used
 
@@ -142,5 +170,8 @@ Inspect:
 - Scriptorium receives structured YAML through `--input data_package=<path>`.
 - Module stanza order is deterministic within each prompt-facing category.
 - Every non-metadata module stanza has exactly one prompt-input category.
+- Data-package stanzas use curated module prompt exports when present and rich
+  values only as pass-through or fallback values.
+- Data packages are narrower than generated-template render contexts.
 - Recent Changes are provided by `internal/changes`; this package does not
   infer changes from rendered report text.

docs/operations.md

@@ -19,7 +19,7 @@ weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00
 ```
 
 Generation commands resolve a report period, fetch a Weather API bundle, build
-a JSON module snapshot, build a YAML prompt input data package, run
+a rich JSON module snapshot, build a curated YAML prompt input data package, run
 `scriptorium render`, and write managed artifacts under the configured
 workspace. Markdown-path reports then run `scriptorium run` directly to the
 managed Markdown report path.
@@ -287,11 +287,12 @@ weatherreporter inspect sources RUN_ID
 
 Use `inspect reports` to find RunIDs and artifact paths. Use
 `inspect metadata` to see the artifact links recorded for a run. Use
-`inspect modules` to review the persisted ordered module snapshot, and
+`inspect modules` to review the persisted ordered module snapshot with rich
-`inspect data-package` to review the structured prompt package used for
+template-facing values, and `inspect data-package` to review the curated prompt
-rendering. Use `inspect prior` to see the prior comparable snapshot selected for
+package passed to Scriptorium. Use `inspect prior` to see the prior comparable
-Recent Changes, or `null` when none exists. Use `inspect sources` to review
+snapshot selected for Recent Changes, or `null` when none exists. Use
-source provenance and warnings without dumping full weather payloads.
+`inspect sources` to review source provenance and warnings without dumping full
+weather payloads.
 
 ## Recent Changes
 

docs/roadmap/data-package-exports.md

@@ -6,8 +6,9 @@ This roadmap defines the target state for cleaning up module fields exposed in
 YAML data packages. The goal is to keep report templates composable while making
 LLM prompt inputs concise, readable, and free of template-only helper fields.
 
-This feature is not implemented yet. Current data-package behavior remains
+This feature is implemented. Current data-package behavior is documented in
-documented outside `docs/roadmap/`.
+`docs/internal/prompt-input.md`; the rich module and template boundary is
+documented in `docs/internal/module.md` and `docs/templates.md`.
 
 ## Problem
 

docs/templates.md

@@ -184,6 +184,12 @@ falls back to sorted keys for any unmatched entries.
 prompt data package. Module fields are pointers because missing-data policy may
 omit a stanza.
 
+Templates render from rich module values, not from the curated YAML data
+package. Some fields documented below are deterministic wording helpers for
+Markdown templates and are intentionally omitted from data packages passed to
+Scriptorium. The data package is a prompt input, while the render context is the
+template surface.
+
 | Variable | Type | Description |
 | --- | --- | --- |
 | `.Modules.Metadata` | *briefing.MetadataModule | Report metadata module output, when present. |
@@ -270,6 +276,40 @@ Common fields:
 | `.Modules.PrecipTiming.PrecipitationWindows[].MaxPopHourLabel` | string | Friendly hour label for the window maximum. |
 | `.Modules.PrecipTiming.ThunderMentioned` | bool | Whether thunder is mentioned in the forecast text. |
 
+### Daypart Summaries
+
+Daily, Today, and Tomorrow templates should use `.Modules.Dayparts` for
+ordered daypart rendering. Each item has `Key` and `Summary`; `Summary` is a
+rich `briefing.DerivedDaypartSummaryModule`.
+
+Common rich daypart fields:
+
+| Variable | Type | Description |
+| --- | --- | --- |
+| `.Modules.Dayparts[].Summary.DisplayName` | string | Human-readable daypart label. |
+| `.Modules.Dayparts[].Summary.PeriodBegins` | string | Friendly local daypart start. |
+| `.Modules.Dayparts[].Summary.PeriodEnds` | string | Friendly local daypart end. |
+| `.Modules.Dayparts[].Summary.TempRangeF` | string | Rounded temperature range or single temperature. |
+| `.Modules.Dayparts[].Summary.TemperaturePhraseF` | string | Temperature phrase used for steady template wording. |
+| `.Modules.Dayparts[].Summary.TemperatureTrend` | string | Trend category such as `rising`, `falling`, `peaking`, or `steady`. |
+| `.Modules.Dayparts[].Summary.TemperatureStartPhraseF` | string | Starting temperature phrase for rising/falling wording. |
+| `.Modules.Dayparts[].Summary.TemperatureEndPhraseF` | string | Ending temperature phrase for rising/falling wording. |
+| `.Modules.Dayparts[].Summary.TemperaturePeakPhraseF` | string | Peak temperature phrase for peaking wording. |
+| `.Modules.Dayparts[].Summary.TemperatureSteadyPhraseF` | string | Steady temperature phrase. |
+| `.Modules.Dayparts[].Summary.MaxPopPercent` | *int | Highest precipitation probability in the daypart. |
+| `.Modules.Dayparts[].Summary.MaxPopTime` | string | Friendly local time for the highest precipitation probability. |
+| `.Modules.Dayparts[].Summary.MaxPopTimeLabel` | string | Clock-style label for deterministic precipitation timing text. |
+| `.Modules.Dayparts[].Summary.MentionPrecipitation` | bool | True when precipitation probability should be mentioned by the template. |
+| `.Modules.Dayparts[].Summary.DominantCondition` | string | Dominant condition text. |
+| `.Modules.Dayparts[].Summary.DominantConditionLower` | string | Lower-case condition text for inline sentences. |
+| `.Modules.Dayparts[].Summary.DominantConditionDisplay` | string | Display-case condition text for bullet starts. |
+| `.Modules.Dayparts[].Summary.NotableConditions` | []string | Notable condition labels retained for the daypart. |
+
+Template-only daypart helpers such as `TemperaturePhraseF`,
+`DominantConditionLower`, `DominantConditionDisplay`, and `MaxPopTimeLabel`
+remain available here even though they are not serialized into data-package
+YAML.
+
 ### Alert Digest
 
 | Variable | Type | Description |