Document curated data package exports

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.