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](cli.md) for command syntax and the [configuration reference](config.md)
for fields, defaults, and notification templates.

## Normal Operation

After configuring a Weather API endpoint, generate one report:

```sh
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](config.md) 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](cli.md) 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:

```sh
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](config.md) 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](cli.md); the durable file contract belongs to the
[comparison bundle contract](integrations/comparison-bundle.md).

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](config.md)
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](../examples/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:

```sh
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`.

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, while the
returned command error reports the retained backup path. Preserve that backup
until it has been inspected and cleaned up manually; do not remove the new
bundle to retry that 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:

```sh
rm -rf ./workspace
```

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