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,
-module builders produce outputs with stanza names, prompt input packages consume
-snapshots, and Recent Changes compares snapshot stanzas.
+report modules. Report definitions use module IDs for composition, module
+builders produce rich outputs with stanza names, prompt input packages consume
+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,
-Recent Changes, and source warnings into the `data_package` file passed to
+`internal/promptinput` converts report metadata, ordered module outputs, Recent
+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
-used for inspection and comparison.
+`weatherreporter.data_package.v3`. It is separate from the JSON module snapshot
+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
-  Scriptorium.
+  choose module prompt export shapes, find prior snapshots, compare changes,
+  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.