Document hourly generated text behavior

docs/internal/app-orchestration.md

@@ -50,6 +50,19 @@ subprocess behavior stays in `internal/adapters/scriptorium`. Distributor
 upload behavior stays in `internal/adapters/distributor`. Filesystem layout and
 persisted metadata stay in `internal/state`.
 
+## Data Flow Terms
+
+- `CollectedFacts` are normalized source facts fetched once from Weather API
+  and made available to derivation and module builders.
+- `DerivedFacts` are deterministic calculations over collected facts, the
+  resolved valid period, daypart configuration, and report-specific windows.
+- `module.Output` values are ordered deterministic stanzas built from collected
+  and derived facts for prompt input and inspection.
+- `GeneratedText` is structured prose returned by Scriptorium for
+  generated-text-template reports and validated by `internal/generatedtext`.
+- `RenderContext` is the typed template input built from report metadata,
+  module outputs, and validated generated text before Markdown rendering.
+
 ## Config Fields Used
 
 - `weather_api.*` for Weather API client construction and module metadata

docs/internal/prompt-input.md

@@ -73,7 +73,9 @@ converted into prompt input. The default hourly module list places
 `precip_timing` under `derived_summaries`, alert and SPC outlooks under
 `applicable_risk_products`, AFD/SPC discussion/weather story under
 `narrative_products`, and current/hourly data under `raw_data`. It does not
-include daily or daypart summary stanzas.
+include civil-day summary stanzas. Generated-text and render context artifacts
+are produced later in app orchestration and are not part of the YAML data
+package.
 
 Current categories are:
 

docs/internal/reporttemplate.md

@@ -0,0 +1,94 @@
+# Report Template Internals
+
+This document describes embedded Markdown templates and GeneratedText schemas
+in `internal/reporttemplate`.
+
+## Purpose
+
+`internal/reporttemplate` owns repository-native report templates and companion
+GeneratedText JSON schemas. The first implemented template contract is the
+Hourly Report.
+
+The package embeds assets from:
+
+- `internal/reporttemplate/templates/*.md.tmpl`
+- `internal/reporttemplate/schemas/*.schema.json`
+
+## Inputs And Outputs
+
+Inputs:
+
+- template ID from a report definition
+- typed render context built by `internal/generatedtext`
+
+Outputs:
+
+- template source for inspection and tests
+- GeneratedText schema bytes for prompt/schema configuration
+- rendered Markdown bytes for app orchestration to persist
+
+The implemented template ID is `hourly`. The implemented schema ID is also
+`hourly`, backed by `hourly.generated_text.schema.json`.
+
+## Boundaries
+
+This package owns embedded asset lookup, Go template parsing, and Markdown
+template execution. It does not fetch weather data, build module outputs,
+validate GeneratedText, construct render contexts, choose report definitions,
+write artifacts, invoke Scriptorium, or notify distributor.
+
+GeneratedText validation is owned by `internal/generatedtext`. App
+orchestration decides which template and schema IDs apply to a report through
+`internal/report` definitions.
+
+## Template Contract
+
+Hourly rendering uses a typed render context with:
+
+- report metadata labels such as title, location, valid period, and generation
+  time
+- validated hourly GeneratedText prose slots
+- deterministic labels derived from module outputs, including current
+  conditions, hourly forecast rows, precipitation timing, alerts, SPC outlooks,
+  forecast discussion, SPC discussion, and weather story
+
+Templates use `text/template` with `missingkey=error`, so missing context fields
+fail rendering instead of producing incomplete Markdown.
+
+## Schema Contract
+
+The hourly GeneratedText schema describes the structured prose Scriptorium is
+expected to write for the prompt. It requires:
+
+- `summary`
+- `timing`
+- `impacts`
+
+It allows optional `confidence` and rejects additional properties. Weather truth
+remains in module outputs; GeneratedText is limited to prose slots consumed by
+the template.
+
+## Failure Behavior
+
+- Unknown template IDs return actionable lookup errors.
+- Unknown schema IDs return actionable lookup errors.
+- Template parse errors include the template ID.
+- Template execution errors include the template ID and usually identify the
+  missing context field.
+
+## Tests
+
+Inspect:
+
+- `internal/reporttemplate/reporttemplate_test.go`
+- `internal/generatedtext/render_context_test.go`
+- `internal/app/app_test.go`
+- `internal/cli/root_test.go`
+
+## Invariants
+
+- Embedded templates and schemas live as separate files, not inline Go strings.
+- Report definitions select templates by ID.
+- Templates render from curated render contexts, not raw data packages.
+- GeneratedText schemas describe LLM prose slots, not deterministic weather
+  facts.

docs/internal/state.md

@@ -97,6 +97,8 @@ current report definition.
   date.
 - Weekend Outlook compares with prior Weekend snapshots for the same weekend
   window.
+- Hourly Report uses the rolling-window comparison strategy and currently
+  returns no prior snapshot from filesystem lookup.
 - Storm Report has no prior lookup because explicit event-window comparison is
   not searched by the filesystem store.