Document internal component contracts

docs/internal/config.md

@@ -0,0 +1,61 @@
+# Configuration Internals
+
+## Purpose
+
+`internal/config` defines YAML-backed configuration structs, defaulting, and validation for distributor pipelines.
+
+## Inputs and outputs
+
+Input is a YAML file containing `pipelines`. Output is a `Config` value with defaults applied and validation completed. Load failures include the config path and whether the failure occurred during file loading, YAML parsing, or validation.
+
+## Loading flow
+
+`LoadFile` opens the requested path, decodes YAML with known-field checking enabled, applies defaults, and validates the result. The app uses `DefaultConfigPath` when the CLI does not supply a config path.
+
+Known-field checking rejects misspelled or unknown YAML keys before defaults and validation run.
+
+## Defaults
+
+Defaults are applied in `ApplyDefaults`:
+
+- pipeline validation defaults `on_digest_mismatch` to `fail`;
+- destination publish policy defaults to source output only;
+- `transfer.on_destination_same` defaults to `skip`;
+- `transfer.on_destination_older` defaults to `replace`;
+- `transfer.on_destination_newer` defaults to `skip`;
+- `transfer.on_conflict` defaults to `fail`.
+
+## Validation responsibilities
+
+Validation requires at least one pipeline, slug-like unique pipeline ids, one source per pipeline, at least one destination, slug-like unique destination ids within each pipeline, backend-specific required fields, valid validation policy, valid publish and transform combinations, and valid transfer actions.
+
+`ValidatePublishTransformPolicy` is shared with publish planning so destination policy combinations are checked consistently. Publishing HTML requires an enabled Markdown-to-HTML transform in `sidecar` mode. A publish policy must select source output, HTML output, or both.
+
+## Executable support boundary
+
+Config validation accepts `local`, `ssh`, and `s3` backend shapes so config files can be validated as schemas. Runtime execution currently opens only local backends through `internal/app`.
+
+The user-facing configuration reference is `docs/config.md`; this file documents package behavior for maintainers.
+
+## Failure behavior
+
+Load errors wrap the underlying file, YAML, or validation error with context. Validation collects all detected field errors into one error value instead of stopping at the first invalid field.
+
+Unsupported backend names fail validation. Accepted backend names without runtime execution support fail later during app backend opening.
+
+## Tests
+
+Before changing config behavior, inspect:
+
+- `internal/config/load_test.go`
+- `internal/config/validate_test.go`
+- example-loading coverage in `internal/config`
+- user-facing examples under `examples/`
+
+## Invariants
+
+- Defaults are applied before validation.
+- Unknown YAML fields are rejected.
+- `docs/config.md` remains the canonical user-facing config reference.
+- Runtime backend execution support is not inferred from config validation support.
+- New user-visible config behavior must be covered by tests and docs in the same change.