Finalize the ConfigKit roadmap and implementation plan

docs/adr/0005-explicit-overrides-and-safe-explanation.md

@@ -0,0 +1,41 @@
+# ADR 0005: Record explicit CLI overrides and safe value explanation
+
+Status: accepted
+
+Date: 2026-09-06
+
+## Context
+
+Consumers need deliberate per-invocation configuration changes and an explanation
+of effective values. Presence and origin records alone cannot show which values
+were replaced. Adding CLI parsing or arbitrary environment overlays would broaden
+the library beyond its consistent configuration model.
+
+## Decision
+
+Use parser-neutral explicit path/value/flag records above selected profiles.
+Defaults remain below strictly composed base input. Apply overrides to the owned
+node tree before typed decoding, retaining the existing parser adapter boundary.
+Recorded domain resolution follows input selection. Provide safe structured
+historical values and an explanation renderer in the initial release, building
+on ADR 0003's presence and audited resolution decision. Applications own commands.
+The [feature roadmap](../roadmap/initial.md#cli-overrides) owns the exact override
+contract and [explanation contract](../roadmap/initial.md#historical-value-explanation).
+
+## Alternatives considered
+
+- Retire configuration flags in favor of profiles: smaller API, but removes useful
+  explicit invocation choices that fit a single fixed precedence model.
+- Mutate structs after loading: easy locally, but bypasses validation and leaves
+  metadata and effective inspection inconsistent.
+- Defer historical values: reduces initial implementation scope but cannot answer
+  why an effective value differs from defaults or an earlier file.
+- Publish raw history trees: flexible but couples consumers to internals and risks
+  leaking sensitive values. Detached, redacted snapshots preserve the boundary.
+
+## Consequences
+
+The library owns override validation and source attribution without choosing a
+CLI framework. History requires bounded retained state and tests for replacement,
+deletion, composite origins and sensitivity. Credentials never enter history;
+secret reference names remain explainable unless explicitly classified sensitive.