163 lines
5.0 KiB
Markdown
163 lines
5.0 KiB
Markdown
# Weatherreporter Operations
|
|
|
|
## Normal Workflow
|
|
|
|
The implemented generation workflows are:
|
|
|
|
```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
|
|
weatherreporter run morning
|
|
weatherreporter run evening
|
|
```
|
|
|
|
These commands fetch weather data, build a briefing for the resolved valid
|
|
period, build the prompt input data package, run `scriptorium render`, run
|
|
`scriptorium run`, and write inspectable artifacts under the configured
|
|
workspace. The evening run resolves only the Tomorrow Planning Brief. The
|
|
morning run generates Daily Today and the 3-Day Outlook, plus Weekend Outlook
|
|
except on Sunday. Storm Report generation is manual and uses the explicit
|
|
`--start` and `--end` bounds as its valid period.
|
|
|
|
Scheduled run commands print a JSON aggregate summary to stdout and compact
|
|
per-report status lines to stderr. If one report fails, remaining independent
|
|
reports are still attempted. The command returns nonzero after the run when any
|
|
report failed.
|
|
|
|
## 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
|
|
```
|
|
|
|
The Markdown report is written to a RunID-managed report path. When `--out` is
|
|
provided to `generate daily`, `generate tomorrow`, `generate three-day`,
|
|
`generate weekend`, or `generate storm`, the managed report is also copied to
|
|
that path.
|
|
|
|
For `run morning` and `run evening`, `--out-dir PATH` writes extra Markdown
|
|
copies using each report definition's default filename, such as `daily.md`,
|
|
`three-day.md`, `weekend.md`, or `tomorrow.md`.
|
|
|
|
## Run Identifiers
|
|
|
|
Run IDs are based on generation time plus report ID, such as:
|
|
|
|
```text
|
|
20260529T100000.123456789Z_daily_today
|
|
```
|
|
|
|
Managed artifact filenames use the RunID so repeated runs for the same valid
|
|
date do not overwrite each other.
|
|
|
|
## Metadata
|
|
|
|
Each generated report writes metadata that links:
|
|
|
|
- RunID
|
|
- report ID and prompt ID
|
|
- generation time and valid period
|
|
- source location, source hashes, and source warnings
|
|
- briefing snapshot path
|
|
- prompt input data package path
|
|
- preflight output path
|
|
- rendered report path
|
|
|
|
Run summaries include each report ID, prompt ID, RunID, status, error text when
|
|
applicable, valid period, and artifact paths known to the application.
|
|
|
|
## Recent Changes
|
|
|
|
When a prior comparable Daily briefing snapshot exists for the same valid local
|
|
date, the app compares structured briefing data before writing the prompt input
|
|
data package. Daily Today and Daily Tomorrow can compare with each other when
|
|
they cover the same valid local date. Meaningful changes are included under
|
|
`recentChanges.items`.
|
|
|
|
3-Day Outlook generation compares against a prior compatible 3-Day briefing
|
|
snapshot for the same valid local date when one exists.
|
|
|
|
Weekend Outlook generation compares against a prior compatible Weekend briefing
|
|
snapshot for the same weekend window when one exists. Friday evening and
|
|
Saturday runs may narrow the valid start while keeping the same Monday endpoint.
|
|
|
|
Storm Report generation currently leaves Recent Changes empty. Its explicit
|
|
event window is still recorded in briefing and metadata artifacts.
|
|
|
|
When no prior comparable snapshot exists, or no configured threshold is crossed,
|
|
the Recent Changes list is empty.
|
|
|
|
## Recovery
|
|
|
|
If render preflight exits nonzero after producing a result, the captured stdout,
|
|
stderr, exit code, and command are still written to the preflight artifact, and
|
|
metadata is still written for inspection.
|
|
|
|
If `scriptorium run` exits nonzero after writing a report, the generated report
|
|
and metadata remain available for inspection. Exit code `2` is still returned as
|
|
an error because it indicates validation failed, even if report output exists.
|
|
|
|
For scheduled runs, inspect stdout first for the aggregate JSON summary, then
|
|
use the per-report artifact paths in that summary to inspect briefing,
|
|
data-package, preflight, metadata, and rendered report files.
|
|
|
|
The application does not currently implement resume, cleanup, archive, or
|
|
remote storage behavior.
|