# Briefing Internals

This document describes the implemented briefing package boundary.

## Purpose

`internal/briefing` builds structured report-specific briefing packages from
resolved report metadata, collected weather data, and derived forecast facts.
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
- `weatherdata.Bundle` with source provenance and warnings
- derived daily, period, or storm-window facts where required
- configured units, timezone, and descriptive location context

Outputs:

- `briefing.Package` with common metadata and one report-specific content
  object for Daily, 3-Day, Weekend, or Storm Report
- optional `currentConditions` prompt context from normalized
  `/conditions/current` data when available
- optional structured `weatherStory` context on report-specific briefing
  objects when `/weatherstories/latest` is available
- 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/facts` before briefing builders run.
Configured `location` values are prompt context only; Weather API
`sourceLocationId` and `sourceLocation` remain source provenance.
Current conditions are copied from the normalized `/conditions/current` bundle
source only; observation station and timestamp fields remain provenance.

## 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, source warnings, and configured prompt location.
- LLM prompt input packaging and Scriptorium execution remain outside this
  boundary.