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.
When distributor notification is enabled, weatherreporter uploads the managed
Markdown report after `scriptorium run` succeeds and final metadata is saved.
`--out PATH` writes an extra Markdown copy for the current generated report; it
is not used as the distributor upload source.

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`; these copies are not used as
distributor upload sources.

## 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. Notification fields are `notificationStatus`,
`notificationRunId`, and `notificationError`.

## Distributor Notification

Distributor notification is configured with `notify.distributor` and is disabled
by default. When enabled, weatherreporter uploads exactly one file per
successfully generated report: the managed Markdown report path recorded in the
report result and metadata. Extra copies written by `--out` or `--out-dir` are
operator conveniences only.

The default bundle ID is derived from producer name, location ID, report ID, and
RunID:

```text
weatherreporter.{location_id}.{report_id}.{run_id}
```

The default idempotency key is the rendered bundle ID. The default bundle path
for the Markdown file is the report definition's batch output name, such as
`daily.md`, `tomorrow.md`, `three-day.md`, or `weekend.md`.

Notification happens after final metadata save. Weather API, briefing,
data-package, render preflight, Scriptorium run, and metadata-save failures do
not trigger notification. A notification failure fails that report. In a batch,
other reports continue, the failed report includes notification fields in the
JSON summary, and the batch returns nonzero.

Weatherreporter is responsible for selecting the managed Markdown report,
constructing a source bundle, and submitting it to the configured distributor
HTTP endpoint. Distributor remains responsible for destination routing,
publication, and any downstream Markdown-to-HTML transformation.

## 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.
- If distributor notification fails, report artifacts and final metadata remain
  available, but the report or batch command returns nonzero.
- 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.