weatherreporter/docs/operations.md

Weatherreporter Operations

This guide covers normal output handling, Distributor notification, secure prompt diagnostics, and cleanup of legacy application state. See the CLI reference for command syntax and the configuration reference for fields, defaults, and notification templates.

Normal Operation

After configuring a Weather API endpoint, generate one report:

weatherreporter generate today

With no configured output directory, the command writes today.md in the current directory. Set output.directory to use one ordinary publication directory for reports, or choose a one-command operator-owned file with --out; a relative path is resolved from the current directory and an absolute path is used directly. The explicit flag takes precedence over the configured directory. Weatherreporter renders in memory and atomically replaces the selected destination only after generation and rendering succeed. It does not create a default workspace, metadata, receipts, or intermediate output files.

A missing configured directory is created only as part of successful report publication. If its existing path is not a directory or cannot be inspected, the command stops before prompt inspection or weather collection, leaving any existing report unchanged. See the configuration reference for the field definition and validation rules.

Before a destination is published, provider, validation, rendering, write, and cancellation failures leave an existing report unchanged. A notification failure happens after publication, so retain and use the completed Markdown file while resolving the delivery error. The JSON result identifies the absolute output path and active profile, backend, model, warnings, validation, debug, and notification information; see the CLI reference for its exact fields.

Batch Outputs And Distributor Notification

Run a scheduled batch with an explicit output directory when appropriate:

weatherreporter run morning --out-dir ./reports

Without --out-dir, batch reports are written beneath output.directory when configured, otherwise the current directory. The explicit directory applies only to that command and takes precedence over the configured fallback. 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 local civil day. A batch collects once, determines the complete report set, and validates every final output destination before executing its first report prompt. A destination collision, such as a directory named tomorrow.md, stops the batch before any report output is created or replaced. After successful validation, each selected report processes independently and successful outputs remain available if another report fails.

When notify.distributor.enabled and batch notification are enabled, Weatherreporter sends one Distributor upload only after every selected output exists. If an item fails, the batch notification is skipped and successful files remain at their selected destinations. A batch notification failure also leaves all successfully published report files in place. Distributor source files are those operator-owned Markdown outputs; rendered bundle paths and delivery status appear in the result, not in a local notification receipt. Report counters count report items only. A batch notification failure therefore returns a failed batch status even when all report counters show success; the top-level notification result contains the delivery diagnostic.

For a single report, Distributor notification follows the atomic output write. See the configuration reference for pipeline, bundle, idempotency-key, and per-report path templates.

Local Prompt Profile Override

Hourly normally selects the embedded weather-light profile. To use a local OpenAI-compatible model without changing prompts or application code, copy weather-light-local-profile.yml, set its endpoint and model for the local server, and configure the copy as promptkit.profile_file. The profile file's weather-light definition completely replaces the embedded definition; it does not affect a report that selects another profile ID.

Prompt and profile validation occurs before weather collection. A malformed profile file, missing required credential, or unsupported selected backend stops the command before collection. A reachable profile can still fail later if its local model endpoint is unavailable; Weatherreporter does not switch to a remote profile.

Optional Prompt Debug Capture

Use --llm-debug-dir only when content-rich prompt diagnostics are required:

weatherreporter generate today --llm-debug-dir /var/tmp/weatherreporter-debug

The directory must be absolute. Requested captures are written with restrictive permissions beneath the supplied directory, organized by report and run. They can contain rendered prompts and generated output, so limit access to trusted operators and remove the captures when they are no longer needed. Normal output, summaries, and routine logs omit that sensitive content. Debug capture is never created for an ordinary command without --llm-debug-dir.

If capture creation or writing fails, the affected run fails rather than silently continuing without the requested diagnostics.

Diagnosing Failures

Start with the command error and JSON summary. For a report generation failure, the selected destination was not replaced; for a notification failure, inspect the completed destination and the notification result. For a batch failure, use the per-report statuses and retain successful output files. Enable explicit debug capture only when content-rich Promptkit diagnostics are necessary.

Weatherreporter does not retain runs for later inspection, resume failed work, or provide automatic cleanup, archival, remote state, daemon operation, or automatic storm monitoring.

Manual Cleanup Of Legacy Workspaces

Older installations may have a directory named workspace containing reports, snapshots, prompt inputs, or notification records from previous versions. Current commands neither read nor update it. After confirming that no separate retention requirement applies, remove that specific legacy directory manually; do not use a broad cleanup command that could remove current operator outputs.

For example, from the directory that contains the old directory:

rm -rf ./workspace

This removal cannot be recovered by Weatherreporter. Keep or archive any historical files that are still needed before deleting them.