# Prompt Input Internals

This document describes YAML prompt data package construction in
`internal/promptinput`.

## Purpose

`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 from app/state orchestration
- `module.Snapshot`
- optional `[]changes.Change`

Outputs:

- `promptinput.Package` with schema version, RunID, report metadata, named
  module stanzas grouped for prompt presentation, 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: {}
  applicable_risk_products:
    alert_digest: {}
    spc_convective_outlooks: {}
  derived_summaries:
    derived_daily_summary: {}
    derived_daypart_summaries: {}
    precip_timing: {}
    outdoor_windows: {}
  narrative_products:
    narrative_forecast: {}
    area_forecast_discussion: {}
    spc_convective_discussion: {}
    weather_story: {}
  raw_data:
    current_conditions: {}
    hourly_forecast: {}
recent_changes:
  items: []
```

The `briefing` mapping keeps `metadata` directly under `briefing` and groups
weather module stanzas under prompt-facing categories. This grouping is a YAML
presentation concern only: module snapshots remain flat, and loaded
`promptinput.Package` values expose flat stanza names in `Briefing.Values`.
Within each category, stanza order follows the module snapshot output order.
Prompt-facing module intervals use local `period_begins` and `period_ends`
labels; canonical report metadata and source timestamps remain structured
timestamps where applicable.

Near-Term Report uses the same package schema and categories. Its default
package includes `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.

Current categories are:

- `applicable_risk_products`: location-applicable alerts, warnings, outlooks,
  and similar risk products. Current stanzas include `alert_digest` and
  `spc_convective_outlooks`.
- `derived_summaries`: deterministic summaries and calculated report facts.
- `narrative_products`: official narrative text products and forecast stories.
  Current stanzas include `narrative_forecast`,
  `area_forecast_discussion`, `spc_convective_discussion`, and
  `weather_story`.
- `raw_data`: minimally transformed underlying weather data.

## Boundaries

- 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 such as timezone, units, and prompt
location are already present in report metadata and module stanzas before this
package runs.

## External Adapters Used

None.

## State Or Manifest Behavior

`promptinput.Save` writes YAML atomically. Managed workspace paths are owned by
`internal/state`.

## Skip And Resume Behavior

None. Recent Changes is always present as an `items` list and may be empty.
Near-Term Report currently writes an empty `items` list.

## Failure Behavior

Validation fails before render preflight when required top-level fields are
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

Inspect:

- `internal/promptinput/package_test.go`
- `internal/app/app_test.go`

## Invariants

- Scriptorium receives structured YAML through `--input data_package=<path>`.
- Module stanza order is deterministic within each prompt-facing category.
- Every non-metadata module stanza has exactly one prompt-input category.
- Recent Changes are provided by `internal/changes`; this package does not
  infer changes from rendered report text.