Weatherreporter Operations

This guide covers normal operation, generated artifacts, inspection, recovery, and current operational caveats. For symptom-specific diagnosis, see Troubleshooting.

Normal Workflow

Implemented generation commands:

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:

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

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:

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, 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.

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:

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.

5.6 KiB Raw Blame History