weatherreporter/docs/operations.md

# Weatherreporter Operations

This guide covers normal operation, generated artifacts, inspection, recovery,
and current operational caveats. For symptom-specific diagnosis, see
[Troubleshooting](troubleshooting.md).

## Normal Workflow

Implemented generation commands:

```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
```

Each command resolves a report period, fetches a Weather API bundle, builds a
briefing, builds a prompt input data package, runs `scriptorium render`, runs
`scriptorium run`, and writes managed artifacts under the configured workspace.
`--out PATH` writes an extra Markdown copy for the current generated report.

Implemented batch commands:

```text
weatherreporter run morning
weatherreporter run evening
```

`run morning` generates Daily Today and the 3-Day Outlook, plus Weekend Outlook
except on Sunday. `run evening` generates the Tomorrow Planning Brief. Batch
commands print a JSON summary to stdout, write compact per-report status lines
to stderr, continue independent reports after one report fails, and return
nonzero when any report failed. When notification is configured, the summary and
status lines include notification status, accepted distributor run ID, or
notification error fields for each attempted report. `--out-dir PATH` writes
extra Markdown copies using report default filenames such as `daily.md`,
`three-day.md`, `weekend.md`, and `tomorrow.md`.

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

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

## RunID And Metadata

RunIDs are based on generation time plus report ID:

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

Each generated report writes metadata that links:

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

Batch summaries include report status, error text when applicable, notification
outcome when attempted, valid period, and known artifact paths for each
attempted report.

## Inspection

Inspection commands read existing workspace artifacts and emit JSON to stdout.
They do not fetch weather data or run `scriptorium`.

```text
weatherreporter inspect reports --limit 10
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
```

Use `inspect reports` to find recent RunIDs and artifact paths. Use
`inspect metadata` to see the artifact links recorded for a run. Use
`inspect briefing` and `inspect data-package` to review the exact structured
inputs used for rendering. Use `inspect prior` to see the prior comparable
snapshot selected for Recent Changes, or `null` when none exists. Use
`inspect sources` to review source provenance and warnings without dumping full
weather payloads.

## Recent Changes

Recent Changes are computed from structured briefing snapshots, not rendered
Markdown text.

Daily Today and Daily Tomorrow can compare with each other when they cover the
same valid local date. 3-Day Outlook compares with prior compatible 3-Day
snapshots for the same valid local date. Weekend Outlook compares with prior
compatible Weekend snapshots for the same weekend window. Storm Report currently
leaves Recent Changes empty.

When no prior comparable snapshot exists, or no configured threshold is crossed,
`recentChanges.items` is empty.

## Recovery

A failed generation run may still leave useful artifacts:

- If `scriptorium render` returns a result with a nonzero exit code, the
  preflight JSON and metadata are written for inspection.
- If `scriptorium run` exits nonzero after writing a report, the managed report
  and metadata remain available.
- For batch commands, inspect the stdout JSON summary first, then inspect the
  artifact paths for each failed report.

For a bad report, start with:

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

## Operational Caveats

- The application uses one configured Weather API endpoint.
- The application writes local filesystem state only.
- The application does not implement resume, cleanup, archive, remote storage,
  daemon operation, or automatic storm monitoring.
- Generated reports and Scriptorium stderr can contain sensitive operational
  context. Store workspace artifacts with appropriate filesystem permissions.