weatherreporter/docs/operations.md

Weatherreporter Operations

This guide covers normal operation, managed workspace state, inspection, recovery, and operational caveats. See the CLI reference for complete command syntax and the configuration reference for fields, defaults, and notification templates. For symptom-based diagnosis, see Troubleshooting.

Normal Operation

After configuring a Weather API endpoint, generate one report:

weatherreporter generate today --out ./today.md

A generation collects weather data, resolves the report period, builds and persists the module snapshot and prompt data package, runs Scriptorium preflight, then produces the managed Markdown report. Daily, Today, Tomorrow, and Hourly reports additionally persist generated-text artifacts, validate the structured generated text, and render Markdown from the validated text and deterministic values.

The managed report and its final metadata are saved before single-report Distributor notification is attempted. --out writes an extra operator copy; it never changes the managed report or upload source. A successful generate command prints its summary to stdout unless --quiet is used.

Run a scheduled batch with the same configured collection:

weatherreporter run morning --out-dir ./reports

Each batch collects once before it plans reports. Morning runs Today, Tomorrow, and every eligible dated Daily Report; evening runs Tomorrow and the same eligible Daily Reports. Eligible Daily dates begin after tomorrow and require complete hourly coverage for their entire local civil day. A batch continues after an individual report fails and returns an aggregate failure when any report or batch notification fails.

--out-dir writes extra copies such as today.md, tomorrow.md, and daily-YYYY-MM-DD.md. These copies are never upload sources. Batch report copies and notification behavior are summarized in the CLI result; use the CLI reference for its exact JSON and stderr contract.

Managed Workspace

The default workspace root is workspace. Artifact paths use the report definition's artifact group, the valid-period start date in the effective timezone, and the RunID:

workspace/
  reports/<artifact_group>/<YYYY-MM-DD>/report.<run_id>.md

  snapshots/<artifact_group>/<YYYY-MM-DD>/modules.<run_id>.json
  snapshots/<artifact_group>/<YYYY-MM-DD>/metadata.<run_id>.json
  snapshots/<artifact_group>/<YYYY-MM-DD>/generated_text_raw.<run_id>.json
  snapshots/<artifact_group>/<YYYY-MM-DD>/generated_text_result.<run_id>.json
  snapshots/<artifact_group>/<YYYY-MM-DD>/generated_text.<run_id>.json
  snapshots/<artifact_group>/<YYYY-MM-DD>/render_context.<run_id>.json

  data-packages/<artifact_group>/<YYYY-MM-DD>/data_package.<run_id>.yaml
  preflight/<artifact_group>/<YYYY-MM-DD>/render.<run_id>.json

  notifications/<artifact_group>/<YYYY-MM-DD>/distributor.<run_id>.json
  notifications/batches/<batch>/<YYYY-MM-DD>/distributor.<batch_run_id>.json

The generated-text and render-context artifacts are written only by Daily, Today, Tomorrow, and Hourly reports. A report's metadata links the module snapshot, data package, preflight artifact, managed report, and any available generated-text or single-report notification artifact. Batch notification artifacts are separate batch-level records under notifications/batches.

RunIDs begin with the UTC generation timestamp and report ID. A Daily RunID also contains its local valid date so multiple Daily reports in one batch have different managed paths. Batch notification RunIDs contain the UTC batch start timestamp and batch name.

Distributor Notification

When notify.distributor.enabled is enabled, a successful generate uploads only the managed Markdown report after final metadata has been saved. The extra copy from --out is never uploaded. A notification attempt writes a redacted debug artifact at notifications/<artifact_group>/<YYYY-MM-DD>/distributor.<run_id>.json; its path is then recorded in report metadata.

Batches suppress per-report notification. When both Distributor and its batch notification are enabled, Weatherreporter submits one multi-report upload after every planned report succeeds. If any report fails, it records a top-level skipped notification with reason one or more reports failed and does not call Distributor. If batch notification is disabled, a batch does not fall back to individual uploads.

A batch notification attempt writes notifications/batches/<batch>/<YYYY-MM-DD>/distributor.<batch_run_id>.json. A notification failure makes the batch fail but does not change successful individual report items into failed items. The debug artifacts contain rendered identifiers, managed source and bundle paths, upload and status results, and redacted errors; they do not contain tokens.

Inspecting Stored Runs

Inspection is read-only: it neither collects weather data nor invokes Scriptorium or Distributor. Start by finding a RunID:

weatherreporter inspect reports --limit 10
weatherreporter inspect metadata RUN_ID

Command	Reads
inspect reports	Metadata files under the workspace snapshots tree.
inspect metadata RUN_ID	Metadata located by RunID.
inspect modules RUN_ID	The module snapshot path recorded in metadata.
inspect data-package RUN_ID	The data-package path recorded in metadata.
inspect prior RUN_ID	The run metadata, then compatible earlier metadata for its comparison policy.
inspect sources RUN_ID	Source provenance and warnings in the run metadata.

A missing snapshots directory produces no listed reports. An unknown or empty RunID is an error; use inspect reports to obtain a valid value.

Recovery

Keep the workspace when a run fails: artifacts reached before the failure remain available where they can be safely persisted.

• A preflight failure can leave the preflight artifact and metadata.
• A report-generation failure can leave the managed report, module snapshot, data package, and metadata.
• A generated-text failure can leave raw text, the structured run result, or a validated generated-text and render-context artifact, depending on where it stopped.
• A single-report notification failure preserves the report and final metadata, including its notification artifact when it was written.
• A batch notification failure preserves each report's artifacts and adds the top-level batch notification artifact.

Use the RunID from the action summary with the inspection commands above. For a batch failure, inspect the summary first, then inspect the affected report RunIDs or the batch notification path. Do not remove the whole workspace as a first response; retain it until the failure is understood.

Operational Caveats

• Workspace files, generated reports, and Scriptorium stderr can contain sensitive operational context. Set appropriate filesystem permissions and do not publish them unintentionally.
• Weatherreporter uses one configured Weather API endpoint and local workspace state.
• It does not provide automatic resume, cleanup, archival, remote state, daemon operation, or automatic storm monitoring.