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.