Finalize the ConfigKit roadmap and implementation plan

docs/adr/0004-secret-references-and-explicit-bootstrap.md

@@ -0,0 +1,43 @@
+# ADR 0004: Use secret references and explicit environment bootstrap
+
+Status: accepted
+
+Date: 2026-09-06
+
+## Context
+
+Consumers need credentials without storing them in YAML and need a consistent
+way to load locally provisioned secret files. WeatherReporter already implements
+useful directory-loading code. Ordinary configuration loading must remain free
+of implicit process mutation, and operators must understand blocked secret files.
+
+## Decision
+
+Represent secrets as ConfigKit-owned typed references to environment-variable
+names. Resolve only surviving references; retain names, never credentials, in
+configuration trees and inspection. Offer directory bootstrap as a separate,
+explicit startup operation, reusing WeatherReporter code where applicable.
+Existing environment variables win even when empty. Report skipped files and
+partial failures without values. Keep bootstrap provenance separate from later
+lookup provenance rather than imply an unchanged environment between calls.
+General environment-variable configuration overlays are not on the roadmap.
+The [feature roadmap](../roadmap/initial.md#secret-references-and-explicit-bootstrap)
+owns the unimplemented contract; stages remain in the implementation plan.
+
+## Alternatives considered
+
+- Literal secrets or interpolated YAML: familiar but allows credentials into
+  configuration artifacts and expands conventions and redaction obligations.
+- Application-only directory loaders: keeps process mutation outside the library
+  but preserves duplicated infrastructure and inconsistent skip/error semantics.
+- Implicit bootstrap during loading: convenient but hides process mutation and
+  makes repeated or concurrent loads difficult to reason about.
+- Directory values overriding existing environment: simple, but defeats explicit
+  deployment environment choices and obscures why a credential was selected.
+
+## Consequences
+
+Applications migrate secret fields, choose startup ordering, and retain bootstrap
+reports. ConfigKit owns bounded loading, reference validation, safe reporting and
+inspection; applications own credential use. No multi-variable transaction or
+protection against concurrent process-environment mutation is promised.

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.