Add operational troubleshooting documentation

docs/operations.md

@@ -1,8 +1,12 @@
 # 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
 
-The implemented generation workflows are:
+Implemented generation commands:
 
 ```text
 weatherreporter generate daily --date 2026-05-29
@@ -10,22 +14,27 @@ 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:
+
+```text
 weatherreporter run morning
 weatherreporter run evening
 ```
 
-These commands fetch weather data, build a briefing for the resolved valid
+`run morning` generates Daily Today and the 3-Day Outlook, plus Weekend Outlook
-period, build the prompt input data package, run `scriptorium render`, run
+except on Sunday. `run evening` generates the Tomorrow Planning Brief. Batch
-`scriptorium run`, and write inspectable artifacts under the configured
+commands print a JSON summary to stdout, write compact per-report status lines
-workspace. The evening run resolves only the Tomorrow Planning Brief. The
+to stderr, continue independent reports after one report fails, and return
-morning run generates Daily Today and the 3-Day Outlook, plus Weekend Outlook
+nonzero when any report failed. `--out-dir PATH` writes extra Markdown copies
-except on Sunday. Storm Report generation is manual and uses the explicit
+using report default filenames such as `daily.md`, `three-day.md`,
-`--start` and `--end` bounds as its valid period.
+`weekend.md`, and `tomorrow.md`.
-
-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
 
@@ -87,51 +96,37 @@ workspace/
       <run_id>.md
 ```
 
-The Markdown report is written to a RunID-managed report path. When `--out` is
+Managed artifact filenames use the RunID, so repeated runs for the same valid
-provided to `generate daily`, `generate tomorrow`, `generate three-day`,
+period do not overwrite each other.
-`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
+## RunID And Metadata
-copies using each report definition's default filename, such as `daily.md`,
-`three-day.md`, `weekend.md`, or `tomorrow.md`.
 
-## Run Identifiers
+RunIDs are based on generation time plus report ID:
-
-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
+- RunID, report ID, variant, and prompt ID
-- report ID and prompt ID
+- generation time, timezone, and valid period
-- 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
+- managed Markdown report path
 
-Run summaries include each report ID, prompt ID, RunID, status, error text when
+Batch summaries include report status, error text when applicable, valid
-applicable, valid period, and artifact paths known to the application.
+period, and known artifact paths for each attempted report.
 
 ## Inspection
 
-Use `weatherreporter inspect reports` to list recent generated runs from the
+Inspection commands read existing workspace artifacts and emit JSON to stdout.
-configured workspace. The output includes RunID, report ID, valid period,
+They do not fetch weather data or run `scriptorium`.
-metadata path, briefing path, report path, and source warning count.
-
-Run-specific inspection commands emit JSON for a single RunID:
 
 ```text
+weatherreporter inspect reports --limit 10
 weatherreporter inspect metadata RUN_ID
 weatherreporter inspect briefing RUN_ID
 weatherreporter inspect data-package RUN_ID
@@ -139,44 +134,54 @@ weatherreporter inspect prior RUN_ID
 weatherreporter inspect sources RUN_ID
 ```
 
-`inspect prior` shows the prior comparable snapshot selected from stored
+Use `inspect reports` to find recent RunIDs and artifact paths. Use
-metadata, or `null` when none exists. `inspect sources` shows source provenance
+`inspect metadata` to see the artifact links recorded for a run. Use
-and source warnings without dumping full weather payloads.
+`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
 
-When a prior comparable Daily briefing snapshot exists for the same valid local
+Recent Changes are computed from structured briefing snapshots, not rendered
-date, the app compares structured briefing data before writing the prompt input
+Markdown text.
-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
+Daily Today and Daily Tomorrow can compare with each other when they cover the
-snapshot for the same valid local date when one exists.
+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
-Weekend Outlook generation compares against a prior compatible Weekend briefing
+compatible Weekend snapshots for the same weekend window. Storm Report currently
-snapshot for the same weekend window when one exists. Friday evening and
+leaves Recent Changes empty.
-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.
+`recentChanges.items` is empty.
 
 ## Recovery
 
-If render preflight exits nonzero after producing a result, the captured stdout,
+A failed generation run may still leave useful artifacts:
-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
+- If `scriptorium render` returns a result with a nonzero exit code, the
-and metadata remain available for inspection. Exit code `2` is still returned as
+  preflight JSON and metadata are written for inspection.
-an error because it indicates validation failed, even if report output exists.
+- 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 scheduled runs, inspect stdout first for the aggregate JSON summary, then
+For a bad report, start with:
-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
+```text
-remote storage behavior.
+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.

docs/troubleshooting.md

@@ -0,0 +1,235 @@
+# Weatherreporter Troubleshooting
+
+This guide lists recurring failures with likely causes, diagnostics, and safe
+fixes. See [CLI reference](cli.md), [Configuration reference](config.md), and
+[Operations guide](operations.md) for normal usage.
+
+## `weather_api.base_url is required`
+
+Symptom: a generation command fails before fetching weather data.
+
+Likely cause: no Weather API base URL is configured.
+
+Diagnostic:
+
+```sh
+weatherreporter generate daily --config ./config.yml --date 2026-05-29
+```
+
+Safe fix: add `weather_api.base_url` to the config file, or pass the intended
+config path with `--config`.
+
+Relevant docs: [Configuration reference](config.md).
+
+## `weather_api.base_url must be an absolute URL`
+
+Symptom: config loading fails with a base URL validation error.
+
+Likely cause: `weather_api.base_url` is missing a scheme or host.
+
+Diagnostic: inspect the configured value in the file passed to `--config`.
+
+Safe fix: use an absolute URL such as `https://weather.api.example.com/`.
+
+Relevant docs: [Configuration reference](config.md).
+
+## Invalid Timezone
+
+Symptom: config loading fails with `weather_api.timezone` context, or a CLI
+timezone override fails.
+
+Likely cause: `weather_api.timezone` or `--tz` is not recognized.
+
+Diagnostic:
+
+```sh
+weatherreporter generate daily --tz America/Chicago --date 2026-05-29
+```
+
+Safe fix: use an accepted timezone value, such as an IANA timezone name,
+`Chicago`, `Stl`, a US timezone abbreviation, or a UTC offset.
+
+Relevant docs: [Configuration reference](config.md).
+
+## Storm Command Rejects Time Bounds
+
+Symptom: `generate storm` fails with `requires --start`, `requires --end`, or
+`requires --end after --start`.
+
+Likely cause: the manual event window is missing or invalid.
+
+Diagnostic:
+
+```sh
+weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00
+```
+
+Safe fix: provide both bounds. Use `YYYY-MM-DDTHH:MM` in the configured
+timezone, or RFC3339 timestamps with explicit offsets.
+
+Relevant docs: [CLI reference](cli.md).
+
+## Weather API Fetch Fails
+
+Symptom: generation fails with `fetch /...`, an HTTP status, or request context.
+
+Likely cause: the configured Weather API endpoint is unreachable, returned a
+non-2xx response, or returned an invalid response envelope.
+
+Diagnostic:
+
+```sh
+weatherreporter generate daily --config ./config.yml --date 2026-05-29
+```
+
+Safe fix: verify `weather_api.base_url`, network access, and the Weather API
+service response. The adapter fetches `/observations`, `/conditions/current`,
+`/forecast/hourly`, `/forecast/narrative`, `/alerts/active`, and `/discussion`.
+
+Relevant docs: [Configuration reference](config.md).
+
+## Hourly Forecast Is Missing
+
+Symptom: generation fails with hourly forecast context, such as missing hourly
+data or an hourly forecast containing no periods.
+
+Likely cause: hourly forecast data is required for generated reports.
+
+Diagnostic: check the Weather API response for `/forecast/hourly`.
+
+Safe fix: restore hourly forecast data at the Weather API. Missing-source
+policy cannot make hourly optional.
+
+Relevant docs: [Configuration reference](config.md), [Operations guide](operations.md).
+
+## Source Warnings Appear
+
+Symptom: generation succeeds, but metadata or `inspect sources` shows source
+warnings.
+
+Likely cause: an optional source was missing or malformed under a warning
+missing-source policy.
+
+Diagnostic:
+
+```sh
+weatherreporter inspect sources RUN_ID
+weatherreporter inspect metadata RUN_ID
+```
+
+Safe fix: inspect the warning `source`, `code`, `message`, and `endpoint`. Fix
+the upstream optional source, or intentionally change the relevant
+`missing_source` policy.
+
+Relevant docs: [Configuration reference](config.md), [Operations guide](operations.md).
+
+## `scriptorium` Is Not Found Or Cannot Start
+
+Symptom: generation fails with `run scriptorium render` or `run scriptorium`
+and an executable or OS error.
+
+Likely cause: the configured Scriptorium binary is unavailable or not
+executable.
+
+Diagnostic: check `scriptorium.binary` in config and run the same binary outside
+`weatherreporter`.
+
+Safe fix: install Scriptorium, update `scriptorium.binary`, or fix executable
+permissions.
+
+Relevant docs: [Configuration reference](config.md),
+[Scriptorium integration](integrations/scriptorium.md).
+
+## Render Preflight Fails
+
+Symptom: generation fails with `scriptorium render exited with code ...`.
+
+Likely cause: Scriptorium rejected the prompt, config, profile, or
+`data_package` input before report generation.
+
+Diagnostic:
+
+```sh
+weatherreporter inspect metadata RUN_ID
+weatherreporter inspect data-package RUN_ID
+```
+
+Then read the preflight path from metadata. It contains captured stdout, stderr,
+exit code, and command.
+
+Safe fix: fix the Scriptorium configuration, prompt ID, profile, or data package
+input indicated by stderr.
+
+Relevant docs: [Operations guide](operations.md),
+[Scriptorium integration](integrations/scriptorium.md).
+
+## Scriptorium Run Fails
+
+Symptom: generation fails with `scriptorium run exited with code ...`.
+
+Likely cause: Scriptorium failed during report generation or validation.
+
+Diagnostic:
+
+```sh
+weatherreporter inspect metadata RUN_ID
+weatherreporter inspect data-package RUN_ID
+```
+
+If metadata includes a rendered report path, inspect that report as well. A
+nonzero run can still leave a managed report artifact.
+
+Safe fix: use the captured stderr and data package to fix the Scriptorium
+prompt, profile, model configuration, or validation issue.
+
+Relevant docs: [Operations guide](operations.md),
+[Scriptorium integration](integrations/scriptorium.md).
+
+## Batch Command Returns Nonzero
+
+Symptom: `run morning` or `run evening` returns nonzero.
+
+Likely cause: at least one report in the batch failed.
+
+Diagnostic: inspect stdout for the JSON summary and stderr for compact status
+lines.
+
+Safe fix: use the failed report's artifact paths from the summary, then inspect
+metadata, sources, briefing, and data package for that RunID.
+
+Relevant docs: [CLI reference](cli.md), [Operations guide](operations.md).
+
+## Unknown RunID
+
+Symptom: an inspect command fails with `metadata for run id ... was not found`.
+
+Likely cause: the RunID is mistyped or the command is reading a different
+workspace.
+
+Diagnostic:
+
+```sh
+weatherreporter inspect reports --config ./config.yml --limit 20
+```
+
+Safe fix: copy a RunID from `inspect reports`, or use the same `--config` and
+workspace that generated the report.
+
+Relevant docs: [Operations guide](operations.md).
+
+## Workspace Path Error
+
+Symptom: startup or inspection fails with workspace path validation or
+filesystem read/write context.
+
+Likely cause: a workspace subdirectory is absolute, escapes `workspace.root`, or
+the process cannot read or write the configured path.
+
+Diagnostic: review `workspace.root`, `workspace.snapshots_dir`,
+`workspace.reports_dir`, `workspace.data_packages_dir`, and
+`workspace.preflight_dir`.
+
+Safe fix: keep workspace subdirectories relative to `workspace.root`, and grant
+the process appropriate filesystem permissions.
+
+Relevant docs: [Configuration reference](config.md), [Operations guide](operations.md).