audita/docs/internal/cli-config.md

# Configuration and CLI Change Recipes

This document owns contributor editing and validation steps for configuration,
CLI wiring, and maintained examples. Definitions of behavior belong to the
[configuration](../config.md) and [CLI](../cli.md) contracts.

## Changing Configuration

1. Update fields, defaults, loading, and validation in `internal/core/config`.
2. Update file, selected overlay, credential reference, and CLI mapping as
   applicable. Preserve the precedence defined in the
   [configuration contract](../config.md#loading-and-composition), including the
   distinct validation and effective-config commands.
3. Update redaction when secrets are involved.
4. Review configuration tests and related CLI tests for precedence, validation,
   and source-specific behavior. Add or adjust tests for the changed contract
   according to the [testing policy](../policy/testing.md).
5. Update the configuration reference and affected [examples](../../examples/).

## Changing CLI Behavior

1. Implement parsing and wiring in `internal/cli`.
2. Preserve [stream and exit contracts](../cli.md) unless a change is intentional
   and documented. Review [subprocess integration](../integrations/subprocess.md)
   when changing output, error, or report handling.
3. Review `internal/cli` tests and `cmd/audita` subprocess tests; update coverage
   for the changed behavior.
4. Update the CLI reference and affected integration guidance.

The `version` route uses ReleaseKit's public `buildinfo.Version()` accessor and
stays independent of application runtime assembly. Preserve its behavior from
the [CLI contract](../cli.md) when changing the command; the
adoption decision is recorded in [ADR 0001](../adr/0001-releasekit.md).

## Validating Examples

Keep complete copyable files in [examples](../../examples/) and link to them from
their canonical contract documentation. Keep them valid and secret-free.
Run the commands in the [example guide](../../examples/README.md) from each
project's directory. `internal/cli/examples_integration_test.go` exercises the
maintained projects with a controlled provider, and the preview fixture can be
prepared without inference. Review automatic companion sources and overlays in
their actual project directories. Keep service credentials synthetic in tests.

## Runtime Change Checks

Select checks according to the [testing policy](../policy/testing.md):

- Configuration or CLI changes: inspect `internal/core/config` tests,
  `internal/cli` tests, and `cmd/audita` integration tests.
- Process/output changes: verify stdout, stderr, exit, output-file, and report
  behavior against the [CLI contract](../cli.md) and
  [subprocess guidance](../integrations/subprocess.md), including failures.
- Report or diagnostics changes: review [report assembly tests and redaction
  checks](diagnostics-reporting.md#key-tests), metadata fields, and artifact paths.
- Schema or serialization changes: review [output-schema tests](output-schemas.md#key-tests)
  and `internal/core/schema` tests, including supported formats and rejection of
  unsupported schemas.
- Changes affecting assembled output: inspect controlled HTTP subprocess workflows
  and retained report/artifact assertions.

Use the [contributor guide](../development.md#baseline-validation) for baseline
commands. These recipes supplement, rather than duplicate, public contracts.