# 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, 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: {}
  current_conditions: {}
recent_changes:
  items: []
```

The `briefing` mapping contains named module stanzas. Stanza order follows the
module snapshot output order.

## 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.

## 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 for generated snapshots.
- Recent Changes are provided by `internal/changes`; this package does not
  infer changes from rendered report text.