# Weatherreporter Operations

## Normal Workflow

The implemented generation workflows are:

```text
weatherreporter generate daily --date 2026-05-29
weatherreporter generate tomorrow
weatherreporter generate three-day
weatherreporter generate weekend
weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00
weatherreporter run morning
weatherreporter run evening
```

These commands fetch weather data, build a briefing for the resolved valid
period, build the prompt input data package, run `scriptorium render`, run
`scriptorium run`, and write inspectable artifacts under the configured
workspace. The evening run resolves only the Tomorrow Planning Brief. The
morning run generates Daily Today and the 3-Day Outlook, plus Weekend Outlook
except on Sunday. Storm Report generation is manual and uses the explicit
`--start` and `--end` bounds as its valid period.

Scheduled run commands print a JSON aggregate summary to stdout and compact
per-report status lines to stderr. If one report fails, remaining independent
reports are still attempted. The command returns nonzero after the run when any
report failed.

## Filesystem Layout

The default workspace root is `workspace`.

```text
workspace/
  snapshots/
    daily/
      YYYY-MM-DD/
        <run_id>.briefing.json
        <run_id>.metadata.json
    three-day/
      YYYY-MM-DD/
        <run_id>.briefing.json
        <run_id>.metadata.json
    weekend/
      YYYY-MM-DD/
        <run_id>.briefing.json
        <run_id>.metadata.json
    storm/
      YYYY-MM-DD/
        <run_id>.briefing.json
        <run_id>.metadata.json
  data-packages/
    daily/
      YYYY-MM-DD/
        <run_id>.data_package.json
    three-day/
      YYYY-MM-DD/
        <run_id>.data_package.json
    weekend/
      YYYY-MM-DD/
        <run_id>.data_package.json
    storm/
      YYYY-MM-DD/
        <run_id>.data_package.json
  preflight/
    daily/
      YYYY-MM-DD/
        <run_id>.render.json
    three-day/
      YYYY-MM-DD/
        <run_id>.render.json
    weekend/
      YYYY-MM-DD/
        <run_id>.render.json
    storm/
      YYYY-MM-DD/
        <run_id>.render.json
  reports/
    daily/
      <run_id>.md
    three-day/
      <run_id>.md
    weekend/
      <run_id>.md
    storm/
      <run_id>.md
```

The Markdown report is written to a RunID-managed report path. When `--out` is
provided to `generate daily`, `generate tomorrow`, `generate three-day`,
`generate weekend`, or `generate storm`, the managed report is also copied to
that path.

For `run morning` and `run evening`, `--out-dir PATH` writes extra Markdown
copies using each report definition's default filename, such as `daily.md`,
`three-day.md`, `weekend.md`, or `tomorrow.md`.

## Run Identifiers

Run IDs are based on generation time plus report ID, such as:

```text
20260529T100000.123456789Z_daily_today
```

Managed artifact filenames use the RunID so repeated runs for the same valid
date do not overwrite each other.

## Metadata

Each generated report writes metadata that links:

- RunID
- report ID and prompt ID
- generation time and valid period
- source location, source hashes, and source warnings
- briefing snapshot path
- prompt input data package path
- preflight output path
- rendered report path

Run summaries include each report ID, prompt ID, RunID, status, error text when
applicable, valid period, and artifact paths known to the application.

## Inspection

Use `weatherreporter inspect reports` to list recent generated runs from the
configured workspace. The output includes RunID, report ID, valid period,
metadata path, briefing path, report path, and source warning count.

Run-specific inspection commands emit JSON for a single RunID:

```text
weatherreporter inspect metadata RUN_ID
weatherreporter inspect briefing RUN_ID
weatherreporter inspect data-package RUN_ID
weatherreporter inspect prior RUN_ID
weatherreporter inspect sources RUN_ID
```

`inspect prior` shows the prior comparable snapshot selected from stored
metadata, or `null` when none exists. `inspect sources` shows source provenance
and source warnings without dumping full weather payloads.

## Recent Changes

When a prior comparable Daily briefing snapshot exists for the same valid local
date, the app compares structured briefing data before writing the prompt input
data package. Daily Today and Daily Tomorrow can compare with each other when
they cover the same valid local date. Meaningful changes are included under
`recentChanges.items`.

3-Day Outlook generation compares against a prior compatible 3-Day briefing
snapshot for the same valid local date when one exists.

Weekend Outlook generation compares against a prior compatible Weekend briefing
snapshot for the same weekend window when one exists. Friday evening and
Saturday runs may narrow the valid start while keeping the same Monday endpoint.

Storm Report generation currently leaves Recent Changes empty. Its explicit
event window is still recorded in briefing and metadata artifacts.

When no prior comparable snapshot exists, or no configured threshold is crossed,
the Recent Changes list is empty.

## Recovery

If render preflight exits nonzero after producing a result, the captured stdout,
stderr, exit code, and command are still written to the preflight artifact, and
metadata is still written for inspection.

If `scriptorium run` exits nonzero after writing a report, the generated report
and metadata remain available for inspection. Exit code `2` is still returned as
an error because it indicates validation failed, even if report output exists.

For scheduled runs, inspect stdout first for the aggregate JSON summary, then
use the per-report artifact paths in that summary to inspect briefing,
data-package, preflight, metadata, and rendered report files.

The application does not currently implement resume, cleanup, archive, or
remote storage behavior.