From 1af6169999ded7ef8ac66d2c8352efc67d864f1c Mon Sep 17 00:00:00 2001
From: Eric Rakestraw <eric@rakestraw.us>
Date: Tue, 9 Jun 2026 21:37:28 +0000
Subject: [PATCH] Align docs with module prompt packages

---
 README.md                            |  8 ++++----
 docs/config.md                       |  4 ++--
 docs/integrations/scriptorium.md     |  5 +++--
 docs/internal/app-orchestration.md   | 20 +++++++++++---------
 docs/internal/briefing.md            |  7 ++++---
 docs/internal/facts.md               |  2 +-
 docs/internal/forecast-derivation.md |  4 ++--
 docs/internal/module.md              |  4 ++--
 docs/internal/prompt-input.md        |  4 ++--
 docs/internal/scriptorium-adapter.md |  3 ++-
 docs/internal/state.md               |  6 +++---
 examples/config.yml                  | 20 +++++++++++++++++++-
 12 files changed, 55 insertions(+), 32 deletions(-)

diff --git a/README.md b/README.md
index c791359..a8e039e 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,10 @@
 # weatherreporter
 
 `weatherreporter` is a Go application for preparing human-facing weather
-reports from normalized forecast data. It builds structured briefing packages,
-runs them through `scriptorium`, and keeps inspectable artifacts under a local
-workspace. It can also upload successfully generated managed Markdown reports
-to a configured `distributor` HTTP upload endpoint.
+reports from normalized forecast data. It builds JSON module snapshots, passes
+YAML prompt data packages to `scriptorium`, and keeps inspectable artifacts
+under a local workspace. It can also upload successfully generated managed
+Markdown reports to a configured `distributor` HTTP upload endpoint.
 
 ## Quickstart
 
diff --git a/docs/config.md b/docs/config.md
index 9b1d239..88196cf 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -53,7 +53,7 @@ Timezone values may be IANA names, configured aliases such as `Chicago` and
 
 ### `location`
 
-`location` is descriptive prompt context included in briefing metadata and
+`location` is descriptive prompt context included in module metadata and
 Scriptorium data packages. It does not select a Weather API endpoint or enable
 multiple configured forecast locations.
 
@@ -143,7 +143,7 @@ stub source slots use the missing-source policy.
 ### `workspace`
 
 - `root`: workspace root for managed artifacts. Default: `workspace`.
-- `snapshots_dir`: briefing and metadata directory under `workspace.root`. Default: `snapshots`.
+- `snapshots_dir`: module snapshot and metadata directory under `workspace.root`. Default: `snapshots`.
 - `reports_dir`: managed Markdown report directory under `workspace.root`. Default: `reports`.
 - `data_packages_dir`: prompt input package directory under `workspace.root`. Default: `data-packages`.
 - `preflight_dir`: Scriptorium render output directory under `workspace.root`. Default: `preflight`.
diff --git a/docs/integrations/scriptorium.md b/docs/integrations/scriptorium.md
index 0cf04bc..2dfe8aa 100644
--- a/docs/integrations/scriptorium.md
+++ b/docs/integrations/scriptorium.md
@@ -30,8 +30,9 @@ scriptorium run \
 ```
 
 `weatherreporter` always passes prompt input as
-`--input data_package=<path>`. The data package is structured JSON created by
-`internal/promptinput`.
+`--input data_package=<path>`. The data package is structured YAML created by
+`internal/promptinput`; module snapshots remain separate JSON artifacts for
+inspection and Recent Changes.
 
 ## Configured Arguments
 
diff --git a/docs/internal/app-orchestration.md b/docs/internal/app-orchestration.md
index 5f42967..3f9d93a 100644
--- a/docs/internal/app-orchestration.md
+++ b/docs/internal/app-orchestration.md
@@ -6,10 +6,10 @@ This document describes the implemented workflow coordinator in `internal/app`.
 
 `internal/app` coordinates the top-level use cases after CLI parsing and config
 loading are complete. It resolves report definitions, fetches weather data,
-builds collected and derived facts, builds module snapshots and prompt-input artifacts,
-invokes Scriptorium through the adapter boundary, optionally notifies
-distributor through an app-owned notifier boundary, persists managed state, runs
-batches, and reads existing artifacts for inspection.
+builds collected and derived facts, builds module snapshots and prompt-input
+artifacts, invokes Scriptorium through the adapter boundary, optionally
+notifies distributor through an app-owned notifier boundary, persists managed
+state, runs batches, and reads existing artifacts for inspection.
 
 ## Inputs And Outputs
 
@@ -32,8 +32,8 @@ Outputs:
 - batch summaries with per-report status, artifact paths, error text, and
   notification outcome when attempted
 - saved Weather API bundle JSON for fetch workflows
-- inspection JSON values for reports, metadata, module snapshots, data packages, prior
-  snapshots, and source provenance
+- inspection JSON values for reports, metadata, module snapshots, data
+  packages, prior snapshots, and source provenance
 
 ## Boundaries
 
@@ -51,7 +51,7 @@ persisted metadata stay in `internal/state`.
 
 ## Config Fields Used
 
-- `weather_api.*` for Weather API client construction and briefing metadata
+- `weather_api.*` for Weather API client construction and module metadata
 - `scriptorium.*` for renderer construction
 - `workspace.*` for filesystem state
 - `dayparts` for daily and outlook summarization
@@ -88,7 +88,8 @@ If render preflight returns both a result and an error, preflight JSON and
 metadata are persisted before the error is returned. If Scriptorium report
 generation returns an error after writing output, the managed report and
 metadata remain inspectable. Notification is not attempted after Weather API,
-module snapshot, prompt input, render, Scriptorium run, or metadata-save failures.
+module snapshot, prompt input, render, Scriptorium run, or metadata-save
+failures.
 When notification is attempted, the debug artifact records request identity,
 including rendered pipeline ID, bundle paths, accepted upload fields,
 distributor status fields, raw status report JSON when available, and redacted
@@ -117,7 +118,8 @@ inspection view.
 ## Failure Behavior
 
 - Resolve errors stop the requested workflow before fetching weather data.
-- Weather API and briefing errors stop that report before Scriptorium runs.
+- Weather API and module execution errors stop that report before Scriptorium
+  runs.
 - Prompt input validation fails before render preflight.
 - Render and run errors preserve Scriptorium stderr and exit-code context.
 - Notification errors are wrapped with report ID, RunID, and managed report path
diff --git a/docs/internal/briefing.md b/docs/internal/briefing.md
index 85a6298..637b47d 100644
--- a/docs/internal/briefing.md
+++ b/docs/internal/briefing.md
@@ -1,6 +1,7 @@
-# Briefing Internals
+# Module Builder Internals
 
-This document describes the implemented briefing package boundary.
+This document describes the implemented module builder boundary in
+`internal/briefing`.
 
 ## Purpose
 
@@ -38,7 +39,7 @@ Outputs:
 ## Config Fields Used
 
 The package receives configured units and timezone from the app layer. Daypart
-configuration is consumed by `internal/facts` before briefing builders run.
+configuration is consumed by `internal/facts` before module builders run.
 Configured `location` values are prompt context only; Weather API
 `sourceLocationId` and `sourceLocation` remain source provenance.
 Current conditions are copied from the normalized `/conditions/current` bundle
diff --git a/docs/internal/facts.md b/docs/internal/facts.md
index 877ff5f..3064caf 100644
--- a/docs/internal/facts.md
+++ b/docs/internal/facts.md
@@ -6,7 +6,7 @@ This document describes the implemented fact contract boundary.
 
 `internal/facts` separates normalized upstream facts collected for a report run
 from conservative report-scoped facts derived from them. The package gives app
-orchestration one place to build reusable facts before briefing construction.
+orchestration one place to build reusable facts before module execution.
 
 ## Inputs And Outputs
 
diff --git a/docs/internal/forecast-derivation.md b/docs/internal/forecast-derivation.md
index eafa8e5..129be7f 100644
--- a/docs/internal/forecast-derivation.md
+++ b/docs/internal/forecast-derivation.md
@@ -6,7 +6,7 @@ This document describes deterministic forecast summarization in
 ## Purpose
 
 `internal/forecast` converts normalized weather data into daily and period
-summaries used by fact builders and briefing builders.
+summaries used by fact builders and module builders.
 
 ## Inputs And Outputs
 
@@ -48,7 +48,7 @@ None directly. Forecast data arrives through `weatherdata.Bundle`.
 ## State Or Manifest Behavior
 
 None. Source warnings and provenance from the bundle are carried into summaries
-for later metadata and briefing output.
+for later metadata and module output.
 
 ## Skip And Resume Behavior
 
diff --git a/docs/internal/module.md b/docs/internal/module.md
index 2cb87ca..f7d619e 100644
--- a/docs/internal/module.md
+++ b/docs/internal/module.md
@@ -6,7 +6,7 @@ This document describes the implemented module contract boundary.
 
 `internal/module` defines stable module IDs, typed configuration items, module
 outputs, and module snapshots. It is a shared contract imported by report
-definitions and briefing registry code.
+definitions and module registry code.
 
 ## Inputs And Outputs
 
@@ -25,7 +25,7 @@ Outputs:
 ## Boundaries
 
 - This package owns shared module identifiers and output envelope contracts.
-- It does not define report IDs, build briefing stanzas, fetch weather data,
+- It does not define report IDs, build prompt stanzas, fetch weather data,
   derive facts, write state, or invoke Scriptorium.
 
 ## State Or Manifest Behavior
diff --git a/docs/internal/prompt-input.md b/docs/internal/prompt-input.md
index d7896f5..69d5924 100644
--- a/docs/internal/prompt-input.md
+++ b/docs/internal/prompt-input.md
@@ -18,7 +18,7 @@ Inputs:
 Outputs:
 
 - `promptinput.Package` containing schema version, RunID, report metadata,
-  named briefing stanzas, Recent Changes, and source warnings.
+  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`
@@ -51,7 +51,7 @@ 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 briefing stanzas are present. Save
+missing or inconsistent, or when no named module stanzas are present. Save
 failures include filesystem operation and path context.
 
 ## Tests
diff --git a/docs/internal/scriptorium-adapter.md b/docs/internal/scriptorium-adapter.md
index 1e3ea21..53576ca 100644
--- a/docs/internal/scriptorium-adapter.md
+++ b/docs/internal/scriptorium-adapter.md
@@ -15,7 +15,7 @@ from app and domain packages.
 Inputs:
 
 - prompt ID
-- prompt input data package path
+- YAML prompt input data package path
 - report output path for `run`
 - configured binary, config path, profile, timeout, and extra arguments
 - context for cancellation
@@ -96,5 +96,6 @@ Inspect:
 
 - No shell interpolation is used.
 - The Scriptorium input name is `data_package`.
+- The file at the data package path is YAML produced by `internal/promptinput`.
 - Render and run preserve command-specific result structs.
 - Scriptorium-specific flags stay inside adapter and config boundaries.
diff --git a/docs/internal/state.md b/docs/internal/state.md
index a9c66b6..7fe6054 100644
--- a/docs/internal/state.md
+++ b/docs/internal/state.md
@@ -97,9 +97,9 @@ notification is attempted and include rendered distributor pipeline ID, bundle
 ID, idempotency key, bundle paths, upload status, latest run status, and
 redacted errors.
 
-Inspection helpers read existing metadata, module snapshot, and data package files.
-Missing metadata directories return no inspection records or no prior snapshot
-rather than creating state.
+Inspection helpers read existing metadata, module snapshot, and data package
+files. Missing metadata directories return no inspection records or no prior
+snapshot rather than creating state.
 
 ## Failure Behavior
 
diff --git a/examples/config.yml b/examples/config.yml
index 18ed659..50374c7 100644
--- a/examples/config.yml
+++ b/examples/config.yml
@@ -67,4 +67,22 @@ recent_change:
   wind_gust_miles_per_hour: 10
   precip_timing_shift_minutes: 120
 
-reports: {}
+reports:
+  daily:
+    deterministic_modules:
+      - metadata
+      - current_conditions
+      - derived_daily_summary
+      - derived_daypart_summaries
+      - precip_timing
+      - alert_digest
+      - forecast_delta
+      - id: area_forecast_discussion
+        options:
+          sections:
+            - product
+            - key_messages
+            - short_term
+            - long_term
+      - weather_story
+      - outdoor_windows