weatherreporter/docs/roadmap/output-directory.md

Configurable Output Directory Roadmap

Status: Implemented; retained temporarily for post-implementation review.

Purpose

Weatherreporter currently writes generated reports beneath the present working directory unless an operator supplies --out for a single report or --out-dir for a batch. Scheduled and packaged deployments should be able to select their ordinary report directory in configuration without repeating a CLI flag on every invocation.

This feature adds one optional nested configuration value:

output:
  directory: /var/lib/weatherreporter/reports

The nested output namespace leaves room for future output-related settings, but this roadmap approves only output.directory.

User Intent

The configured directory is an operator-owned publication destination. It is not an application workspace, history store, cache, or source of input for a later run. The feature must preserve Weatherreporter's stateless execution model and atomic report publication.

Operators should be able to establish a stable default once in config.yml while retaining explicit per-invocation control through the existing CLI flags.

Target Configuration Contract

output.directory is an optional string with an empty default.

• An omitted or empty value preserves the current behavior: default report names are published beneath the process's present working directory.
• A nonempty absolute path selects that directory directly.
• A nonempty relative path is resolved against the process's present working directory, matching the existing relative-path behavior of --out and --out-dir. It is not resolved relative to the configuration file.
• A whitespace-only value is invalid rather than being treated as an implicit current-directory selection.
• A nonexistent directory is allowed and may be created as part of normal atomic output publication.
• An existing path that is not a directory, an inaccessible destination, or any other unsafe output target fails through the existing output preflight and publication contracts.

The configuration remains strict: unknown fields beneath output are rejected in the same way as unknown fields elsewhere in the configuration.

Destination Precedence

Effective output selection follows this precedence, from highest to lowest:

1. An explicit --out path for generate, or an explicit --out-dir path for run.
2. output.directory from the effective configuration.
3. The process's present working directory.

For single-report generation:

• generate <report> without --out publishes the report's existing default filename beneath output.directory when configured.
• generate <report> --out PATH treats PATH as the complete destination and ignores output.directory.
• A relative --out value remains relative to the present working directory; it is not placed beneath output.directory.

For batch generation:

• run <batch> without --out-dir publishes every selected report beneath output.directory when configured.
• run <batch> --out-dir PATH ignores output.directory for that invocation.

Default report filenames, batch membership, summaries, and notification behavior do not change.

Architectural End State

The configuration package owns the output.directory field, its empty default, YAML decoding, normalization, and configuration-level validation. The CLI continues to own flag parsing and the present working directory used for relative CLI values. Application orchestration owns the final precedence decision, output preflight, default filename placement, atomic publication, and the resolved output paths returned in action results.

Single-report and batch paths must use one coherent destination-resolution policy rather than maintaining independent interpretations of the configured directory. Output destinations must still be fully resolved and validated before weather collection or Promptkit execution where the existing workflow provides that guarantee.

The generated Markdown remains the only ordinary durable artifact. No directory scan, prior report lookup, manifest, metadata file, or managed cleanup behavior is introduced.

Scope

The completed feature includes:

• an OutputConfig configuration boundary containing directory;
• an empty default that preserves current installations;
• strict YAML loading and validation for the nested configuration;
• configured-directory fallback for both generate and run;
• explicit CLI-over-configuration precedence;
• consistent absolute and relative path handling;
• preservation of output preflight, atomic replacement, cancellation, and notification ordering guarantees;
• updates to the maintained example configuration;
• updates to the canonical configuration, CLI, operations, architecture, and app-orchestration documentation where their owned contracts change; and
• focused configuration, CLI, and application tests protecting the public behavior and important failure paths.

Compatibility

This is an additive configuration feature. Existing configuration files remain valid, and installations that do not set output.directory retain the current working-directory behavior.

Existing --out and --out-dir syntax and relative-path semantics remain unchanged. The feature does not alter report contents, default filenames, Promptkit execution, Distributor payloads, or exit behavior.

Testing Expectations

Tests should provide durable coverage for:

• the empty default and YAML loading of absolute and relative directories;
• rejection of whitespace-only and unknown output configuration values;
• current-working-directory fallback when the field is omitted;
• configured-directory use by representative single-report and batch actions;
• --out and --out-dir precedence over the configured directory;
• preservation of existing relative CLI path semantics;
• rejection of an existing non-directory destination before expensive work;
• successful publication beneath a directory that does not yet exist; and
• preservation of atomic destination replacement and action-result paths.

Tests must remain deterministic, offline, and independent of machine-specific directories. Filesystem cases should use temporary directories and exercise behavior through the narrowest stable configuration, CLI, or application boundary that owns the contract.

Documentation End State

Once implemented, the exact field definition, default, and path semantics belong in the configuration reference. CLI flag syntax and precedence summaries belong in the CLI reference. Normal output handling belongs in the operations guide, while ownership and workflow mechanics belong in the architecture policy and app-orchestration internals, respectively.

The maintained configuration under examples/ should illustrate the field without turning another document into a duplicate configuration reference. Current-state documentation must not describe this feature as available until the implementation lands.

Non-Goals

This roadmap does not introduce:

• per-report or per-batch configured output directories;
• filename or directory templates;
• a new --out-dir flag for single-report generation;
• environment-variable expansion or home-directory expansion in paths;
• paths resolved relative to the configuration file;
• output retention, rotation, cleanup, indexing, or history;
• configuration-time directory creation;
• multiple output destinations or output format selection; or
• changes to debug artifact placement or Distributor notification routing.

Any future output settings require their own accepted scope and should be added beneath output only when a concrete requirement exists.

Completion Criteria

The feature is complete when operators can set output.directory and obtain the same destination behavior for ordinary single-report and batch generation, explicit CLI destinations reliably take precedence, omitted configuration is fully backward compatible, output safety invariants remain intact, and all affected canonical documentation and maintained examples describe the implemented contract.

Open Questions

None. The target behavior and policy choices are defined above.