Refresh documentation and policies and simplify releases

docs/internal/cli-config.md

@@ -0,0 +1,64 @@
+# 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, environment, and CLI mapping as applicable, including CLI flag
+   extraction. Preserve the source-specific behavior defined in the
+   [configuration contract](../config.md#effective-precedence), 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.
+
+## Validating Examples
+
+Keep complete copyable files in [examples](../../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:
+
+```sh
+go run ./cmd/audita config validate --config examples/minimal-config.yml
+go run ./cmd/audita config validate --config examples/production-config.yml
+go run ./cmd/audita config print-effective --config examples/minimal-config.yml
+```
+
+The effective-config command incorporates environment settings; use a controlled
+environment when comparing its results. 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](../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 CLI parity and release fixtures.
+
+Use the [contributor guide](../development.md#baseline-validation) for baseline
+commands. These recipes supplement, rather than duplicate, public contracts.