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 and CLI 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, 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.
5. Update the configuration reference and affected examples.

Changing CLI Behavior

1. Implement parsing and wiring in internal/cli.
2. Preserve stream and exit contracts unless a change is intentional and documented. Review subprocess integration 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 when changing the command; the adoption decision is recorded in ADR 0001.

Validating Examples

Keep complete copyable files in examples and link to them from their canonical contract documentation. Keep them valid and secret-free. From the repository root, validate the maintained configuration examples:

go run ./cmd/audita config validate --config examples/minimal-config.yml
go run ./cmd/audita config validate --config examples/configkit-inheritance.yml
AUDITA_SERVICE_KEY=synthetic-example go run ./cmd/audita config validate --config examples/production-config.yml
AUDITA_SERVICE_KEY=synthetic-example go run ./cmd/audita config validate --config examples/production-config.yml --overlay testing
go run ./cmd/audita config print-effective --config examples/minimal-config.yml --view profiles
go run ./cmd/audita config print-effective --config examples/configkit-inheritance.yml --view explain

The local and ConfigKit inheritance files select profiles/local; the service file selects profiles/service, including the service testing profiles. Keep these roots separate because PromptKit validates every final definition in a selected root, including definitions that are not selected for a role.

Only referenced credentials read environment values; use a controlled synthetic value when validating the service example. Check affected CLI examples against the parser and use schema tests for maintained transcript/glossary inputs. Example validation should not invoke a live LLM merely to check documentation.

Runtime Change Checks

Select checks according to the testing policy:

• 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 and subprocess guidance, including failures.
• Report or diagnostics changes: review report assembly tests and redaction checks, metadata fields, and artifact paths.
• Schema or serialization changes: review output-schema 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 for baseline commands. These recipes supplement, rather than duplicate, public contracts.