Files
weatherreporter/docs/operations.md

93 lines
2.6 KiB
Markdown
Raw Normal View History

2026-05-29 17:40:38 +00:00
# Weatherreporter Operations
## Normal Workflow
2026-05-29 18:00:27 +00:00
The implemented Daily-family generation workflows are:
2026-05-29 17:40:38 +00:00
```text
weatherreporter generate daily --date 2026-05-29
2026-05-29 18:00:27 +00:00
weatherreporter generate tomorrow
weatherreporter run evening
2026-05-29 17:40:38 +00:00
```
2026-05-29 18:00:27 +00:00
These commands fetch weather data, build a Daily briefing for the resolved
valid date, 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.
2026-05-29 17:40:38 +00:00
## Filesystem Layout
The default workspace root is `workspace`.
```text
workspace/
snapshots/
daily/
YYYY-MM-DD/
<run_id>.briefing.json
<run_id>.metadata.json
data-packages/
daily/
YYYY-MM-DD/
<run_id>.data_package.json
preflight/
daily/
YYYY-MM-DD/
<run_id>.render.json
reports/
daily/
<run_id>.md
```
2026-05-29 18:00:27 +00:00
The Markdown report is written to a RunID-managed report path. When `--out` is
provided to `generate daily` or `generate tomorrow`, the managed report is also
copied to that path.
2026-05-29 17:40:38 +00:00
## 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 Daily generation writes metadata that links:
2026-05-29 17:40:38 +00:00
- 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
2026-05-29 17:40:38 +00:00
2026-05-29 17:53:03 +00:00
## 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
2026-05-29 18:00:27 +00:00
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`.
2026-05-29 17:53:03 +00:00
When no prior comparable snapshot exists, or no configured threshold is crossed,
the Recent Changes list is empty.
2026-05-29 17:40:38 +00:00
## 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.
2026-05-29 17:40:38 +00:00
The application does not currently implement resume, cleanup, archive, or
remote storage behavior.