# 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 implemented template contracts are Tomorrow
Report and 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 IDs are `tomorrow` and `hourly`. The implemented
schema IDs are also `tomorrow` and `hourly`, backed by
`tomorrow.generated_text.schema.json` and `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 uses `internal/generatedtext` catalog lookup to connect
`internal/report` definition schema/template IDs to the matching validator,
render-context builder, and embedded assets.

## Template Contracts

Tomorrow and Hourly rendering use typed render contexts with:

- report metadata labels such as title, location, valid period, and generation
  time
- validated 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

Tomorrow additionally exposes forecast-date labels, ordered daypart forecast
rows, daily/daypart summaries, tomorrow planning facts, and a multi-paragraph
forecast discussion generated-text slot. The ordered daypart slice is built in
Go so templates do not range over maps.

Templates use `text/template` with `missingkey=error`, so missing context fields
fail rendering instead of producing incomplete Markdown.

## Schema Contract

The GeneratedText schemas describe the structured prose Scriptorium is expected
to write for each generated-text prompt. Hourly requires:

- `summary`
- `forecast_discussion`

Tomorrow requires `summary` and a nonempty `forecast_discussion` array. Both
schemas allow optional `precipitation_timing` and `confidence`, and reject
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.