From 36172ed20e832b371506d6aceb02dc6c8f50f71b Mon Sep 17 00:00:00 2001
From: Eric Rakestraw <eric@rakestraw.us>
Date: Tue, 29 Sep 2026 16:10:16 +0000
Subject: [PATCH] Clarify ConfigKit design goals and priorities

---
 README.md                   | 15 +++++++++++++--
 docs/policy/architecture.md | 26 +++++++++++++++++++++++---
 2 files changed, 36 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 4193f58..f67d0f7 100644
--- a/README.md
+++ b/README.md
@@ -33,11 +33,22 @@ func ReadConfig(path string) (Config, error) {
 }
 ```
 
+## Design philosophy
+
+ConfigKit favors one coherent, predictable configuration model over flexibility
+for reproducing each consumer's conventions. Its goal is to let applications
+load once, inspect where final values came from, and distinguish explicit values
+from omissions with minimal configuration bookkeeping. Applications retain their
+domain rules and execution responsibilities.
+
+The [architecture goals](docs/policy/architecture.md#success-criteria) explain
+these priorities and how genuine new needs can justify extending the shared
+model. The [deferred scope](docs/roadmap/deferred.md) records deliberate exclusions.
+
 The [configuration contract](docs/config.md) describes implemented behavior. The
 [consumer adoption guide](docs/consumers/README.md) provides maintained Narratio-,
 Notarius-, WeatherReporter-, and Seriatim-shaped examples and migration guidance.
-The [deferred scope](docs/roadmap/deferred.md) records deliberate exclusions. See the
-[development guide](docs/development.md) for repository orientation and the
+See the [development guide](docs/development.md) for repository orientation and the
 [release procedure](docs/release.md) for maintainer-only candidate and publication
 steps.
 
diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md
index a41caee..1a9f4fb 100644
--- a/docs/policy/architecture.md
+++ b/docs/policy/architecture.md
@@ -2,7 +2,7 @@
 
 **Base Policy Version:** 1.3
 
-**Last Updated**: 2026-09-28
+**Last Updated**: 2026-09-29
 
 **Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md)
 
@@ -34,6 +34,23 @@ Do not promote incidental implementation choices into architectural invariants.
 
 ## Success Criteria
 
+ConfigKit prioritizes a coherent configuration model: consistency and
+predictability take precedence over flexibility for accommodating individual
+downstream conventions. Consumers should learn one set of rules, not different
+combination or presence semantics depending on the source format or consuming
+application. Distinct operations such as strict composition and intentional
+overlay express distinct purposes within that model.
+
+Consumers should be able to load once and receive a complete, validated
+configuration with inspectable provenance for its final values, including
+defaults and recorded application-derived values. Configuration and metadata
+together must distinguish explicit zero, false, empty, and null input from
+omission; ordinary Go values alone need not encode those distinctions.
+Application-owned resolution belongs within the recorded loading lifecycle, so
+consumers need no subsequent generic merging, defaulting, or provenance
+reconstruction. This does not transfer domain execution or runtime resource
+management into ConfigKit.
+
 1. **Reduce application infrastructure:** Can applications delete substantial
    configuration infrastructure while retaining clear ownership of their domain
    rules?
@@ -41,8 +58,11 @@ Do not promote incidental implementation choices into architectural invariants.
    configuration model, with only the flexibility needed to express genuine
    application requirements?
 
-Both criteria must hold. ConfigKit should not preserve divergent consumer
-conventions merely for compatibility, nor impose restrictions that prevent useful
+Both criteria must hold. Minimize consumer loading and processing code subject
+to the consistency, presence, and provenance principles above, rather than
+trading those principles for consumer-specific shortcuts. ConfigKit should not
+preserve divergent consumer conventions merely for compatibility, nor impose
+restrictions that prevent useful
 domain information from being expressed. Prefer a canonical representation using
 existing primitives before adding another mechanism. Extend the model when a
 concrete requirement cannot be accommodated cleanly, not simply because a