# Briefing Internals

This document describes the implemented briefing package boundary.

## Purpose

`internal/briefing` builds structured report-specific briefing packages from
resolved report metadata, forecast bundles, and derived forecast summaries.
Briefings are curated inputs for prompt data packages, not rendered report
prose.

## Inputs And Outputs

Inputs:

- resolved report definition, generation time, timezone, and valid period
- forecast bundle with source provenance and warnings
- derived daily or period summaries where required
- configured units and timezone

Outputs:

- `briefing.Package` with common metadata and one report-specific content
  object for Daily, 3-Day, Weekend, or Storm Report
- optional JSON file written by `briefing.Save`

## Boundaries

- This package selects and shapes weather facts for prompts.
- It does not fetch weather data, compare prior snapshots, build
  `data_package` files, invoke Scriptorium, or write workflow metadata.

## Config Fields Used

The package receives configured units and timezone from the app layer. Daypart
configuration is consumed by `internal/forecast` before briefing builders run.

## External Adapters Used

None directly.

## State Or Manifest Behavior

`briefing.Save` writes briefing JSON atomically. Managed workspace placement is
owned by `internal/state`.

## Skip And Resume Behavior

None. Builders either return a complete briefing package or an error.

## Failure Behavior

- Daily briefing construction requires a Daily report definition and derived
  daily summary.
- 3-Day briefing construction requires a 3-Day report definition and at least
  one derived summary.
- Weekend briefing construction requires a Weekend report definition and at
  least one derived summary.
- Storm briefing construction requires a Storm Report definition and forecast
  bundle.
- Save failures include path and operation context.

## Tests

Inspect:

- `internal/briefing/daily_test.go`
- `internal/briefing/three_day_test.go`
- `internal/briefing/weekend_test.go`
- `internal/briefing/storm_test.go`
- `internal/app/app_test.go`

## Invariants

- Briefings contain structured weather facts and source context.
- Common metadata includes RunID, report ID, prompt ID, valid period, source
  provenance, source hashes, and source warnings.
- LLM prompt input packaging and Scriptorium execution remain outside this
  boundary.