# 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:

```yaml
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](../config.md). CLI flag syntax and
precedence summaries belong in the [CLI reference](../cli.md). Normal output
handling belongs in the [operations guide](../operations.md), while ownership
and workflow mechanics belong in the [architecture policy](../policy/architecture.md)
and [app-orchestration internals](../internal/app-orchestration.md),
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.