Document hourly generated text behavior

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.