257 lines
9.1 KiB
Markdown
257 lines
9.1 KiB
Markdown
# 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
|
|
notifications/
|
|
daily/
|
|
YYYY-MM-DD/
|
|
<run_id>.distributor.json
|
|
three-day/
|
|
YYYY-MM-DD/
|
|
<run_id>.distributor.json
|
|
weekend/
|
|
YYYY-MM-DD/
|
|
<run_id>.distributor.json
|
|
storm/
|
|
YYYY-MM-DD/
|
|
<run_id>.distributor.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
|
|
- distributor notification debug artifact path, when notification is attempted
|
|
|
|
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 the managed Markdown
|
|
report path recorded in the report result and metadata. That single source file
|
|
can be mapped to multiple configured bundle paths, such as a dated archival path
|
|
and a `latest.md` path. Extra copies written by `--out` or `--out-dir` are
|
|
operator conveniences only.
|
|
|
|
The rendered pipeline ID selects the configured distributor `http_upload`
|
|
workflow. The default bundle ID is a stable logical source identity derived from
|
|
producer name, location ID, and report ID:
|
|
|
|
```text
|
|
weatherreporter.{location_id}.{report_id}
|
|
```
|
|
|
|
The default idempotency key appends RunID to the rendered bundle ID so each
|
|
report generation has a distinct retry identity. Default bundle paths use the
|
|
valid-period start date, artifact group, and RunID, and also publish
|
|
`latest.md` under the same dated artifact-group directory.
|
|
|
|
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.
|
|
|
|
Each notification attempt writes a debug artifact under `notifications/`. The
|
|
artifact records the rendered pipeline ID, bundle ID, idempotency key, managed
|
|
source path, bundle-relative paths, bundle created timestamp, accepted upload
|
|
response, and the latest distributor run status response when available.
|
|
Weatherreporter polls status until distributor reports `succeeded` or `failed`,
|
|
or until the configured notification timeout expires. The run status includes
|
|
the distributor status, error text, and raw run report JSON, which can show
|
|
actions such as `replace_older`, `skip_same`, `skip_destination_newer`, or
|
|
`failed`. Token values are not written.
|
|
|
|
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. Distributor
|
|
leaves destination files alone when they are not tracked by a newly uploaded
|
|
bundle, so previously uploaded dated report paths can remain available.
|
|
|
|
## 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.
|