12 KiB
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.
Weatherreporter validates the final output filename before prompt inspection or weather collection. A valid long filename is published through a short, same-directory temporary sibling, so temporary naming does not shorten the operator-selected destination. A rejected filename does not create a missing parent directory. The final destination itself must be absent or a regular file: symlinks, directories, named pipes, sockets, and other special objects are rejected before prompt inspection or weather collection. The destination is checked again immediately before the atomic replacement; cancellation or a deadline at that point leaves the prior report unchanged and skips notification.
SIGINT and SIGTERM request orderly cancellation of an active action. The
command lets cancellation and related cleanup finish before it exits; use the
usual failed result or error to determine whether an output was published.
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. If cancellation or a deadline is observed during the
sequence, Weatherreporter stops before starting another report. It retains
already published files, marks interrupted and unstarted reports as canceled in
the result, and skips batch notification.
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.
Remote Distributor response text is not included in command output. Instead,
notification failures use stable local diagnostics while retaining the upload
and status identities needed to investigate delivery with Distributor.
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. Enabled notification configuration, including the HTTP(S) endpoint and templates, is validated before report processing. A malformed endpoint does not collect weather data, generate a report, publish output, or invoke Distributor. See the configuration reference for endpoint, pipeline, bundle, idempotency-key, and per-report path templates.
Comparison Bundles
Use compare when an operator needs to evaluate explicit Promptkit profiles
against the same report input. The command writes one flat, operator-owned
bundle directory and never sends a Distributor notification. Command syntax,
profile validation, JSON output, and exit behavior belong to the
CLI reference; the durable file contract belongs to the
comparison bundle contract.
The output destination follows the normal output.directory fallback. An
explicit --out-dir takes precedence and names the exact bundle directory,
not a parent to be combined with another name. The standard names are derived
from the report output name, such as comparison-today and
comparison-daily-2026-05-29; see the configuration reference
for output-directory resolution.
A comparison bundle contains the shared data package, a manifest, and one Markdown file for every successful profile. Treat all of these files as potentially sensitive: the data package and generated reports can contain location or forecast context. Weatherreporter creates no application-owned history, retention store, or cleanup job. Retain, archive, or remove only the specific bundle directories your operating policy permits.
The destination is preflighted before prompt inspection and collection, then
rechecked immediately before an atomic publish. A missing or empty directory
is usable. A nonempty directory can be replaced only when --replace is given
and it is recognized as a current Weatherreporter comparison bundle; ordinary
directories, symlinks, and unsafe destinations are rejected. Cancellation and
all failures before publication preserve an existing bundle, including a
cancellation observed while a replacement is being prepared. If guarded
restoration cannot complete, the error names the retained sibling bundle for
manual recovery. Profile failures are different: the command publishes a
complete partial bundle, with failed profiles represented in the manifest and
no Markdown file for those profiles.
Comparison preflight also checks that private publication siblings can be
formed. An infeasible destination name is rejected before a missing parent
directory is created.
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. Comparison
captures additionally identify each selected profile so concurrent executions
remain distinct. Normal output, summaries, and routine logs omit that sensitive
content. Debug capture is never created for an ordinary command without
--llm-debug-dir.
Secure prompt debug capture is currently available only on Unix hosts, where
Weatherreporter can keep every traversal and write anchored to opened directory
descriptors without following symbolic links. On other platforms, requesting
--llm-debug-dir fails before prompt inspection, weather collection, or
provider execution; ordinary commands without the flag remain available.
Preparation captures retain only the provider endpoint origin and reviewed execution settings. URL user information, paths, queries, fragments, and unrecognized provider parameters are omitted.
Capture writes are confined to the requested root and fail if an unsafe filesystem component prevents secure artifact creation.
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. For a comparison failure, inspect the published manifest when its path is present: individual profile failures retain their safe result and successful Markdown files, while cancellation and pre-publication errors leave the prior destination unchanged.
If a replacement commits but cleanup of its prior sibling backup fails, the new
bundle remains valid and its artifact paths appear in the failed command
summary. The summary records a safe publication_cleanup error that indicates
whether a complete prior bundle remains, only partial remnants remain, or no
prior bundle remains; it also identifies when the sibling cannot be inspected.
The returned command error includes a recovery path only when a sibling remains.
Preserve a complete recognized recovery bundle until it has been inspected and
cleaned up manually; partial remnants are not a rollback artifact. Do not
remove the new bundle to retry cleanup.
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.