Clarify module package documentation

docs/internal/prompt-input.md

@@ -1,38 +1,63 @@
 # Prompt Input Internals
 
-This document describes prompt input data package construction.
+This document describes YAML prompt data package construction in
+`internal/promptinput`.
 
 ## Purpose
 
-`internal/promptinput` converts report metadata, module snapshots, and optional
-Recent Changes into the YAML `data_package` passed to Scriptorium prompts.
+`internal/promptinput` converts report metadata, an ordered module snapshot,
+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.
 
 ## Inputs And Outputs
 
 Inputs:
 
-- report metadata
+- report metadata from app/state orchestration
 - `module.Snapshot`
 - optional `[]changes.Change`
 
 Outputs:
 
-- `promptinput.Package` containing schema version, RunID, report metadata,
-  named module stanzas under `briefing`, Recent Changes, and source warnings.
-- report metadata includes `currentLocalDate`, the generation date formatted as
-  `YYYY-MM-DD` in the effective report timezone.
-- optional YAML file written by `promptinput.Save`
+- `promptinput.Package` with schema version, RunID, report metadata, named
+  module stanzas, Recent Changes, and source warnings
+- YAML bytes from `promptinput.MarshalYAML`
+- YAML file written atomically by `promptinput.Save`
+
+The YAML shape includes:
+
+```yaml
+schema_version: weatherreporter.data_package.v2
+run_id: <run_id>
+report:
+  id: <report_id>
+  prompt_id: <prompt_id>
+briefing:
+  metadata: {}
+  current_conditions: {}
+recent_changes:
+  items: []
+```
+
+The `briefing` mapping contains named module stanzas. Stanza order follows the
+module snapshot output order.
 
 ## Boundaries
 
-- This package owns the prompt input schema and validation.
-- It does not fetch weather data, derive forecast summaries, find prior
-  snapshots, compare changes, or invoke Scriptorium.
+- 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.
 
 ## Config Fields Used
 
-None directly. Config-derived values, including timezone and prompt location
-context, are already present in report metadata and module stanzas before this
+None directly. Config-derived values such as timezone, units, and prompt
+location are already present in report metadata and module stanzas before this
 package runs.
 
 ## External Adapters Used
@@ -51,8 +76,9 @@ None. Recent Changes is always present as an `items` list and may be empty.
 ## Failure Behavior
 
 Validation fails before render preflight when required top-level fields are
-missing or inconsistent, or when no named module stanzas are present. Save
-failures include filesystem operation and path context.
+missing or inconsistent, when the valid period is invalid, or when no module
+stanzas are present. Save failures include filesystem operation and path
+context.
 
 ## Tests
 
@@ -63,6 +89,7 @@ Inspect:
 
 ## Invariants
 
-- Scriptorium receives structured `data_package` YAML.
+- Scriptorium receives structured YAML through `--input data_package=<path>`.
 - Module stanza order is deterministic for generated snapshots.
-- Recent Changes are not inferred from rendered report text.
+- Recent Changes are provided by `internal/changes`; this package does not
+  infer changes from rendered report text.