Remove completed roadmap documents

COPYRIGHT

@@ -18,8 +18,3 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 GNU Lesser General Public License for more details.
 
 Third-party code and assets are subject to their respective license terms.
-
-Policy documents adapted from Standard Repository Policies, the root AGENTS.md
-orientation, and the Policy Reading Guide in docs/development.md remain licensed
-under CC-BY-SA-4.0. See docs/oss/attribution.md for the affected material,
-upstream credit, and license links.

README.md

@@ -1,28 +1,18 @@
 # ConfigKit
 
-An opinionated Go library for applications that use YAML configuration files.
+ConfigKit loads YAML into your application's Go configuration type, combines the
+inputs you choose, and lets you inspect where the final values came from. You
+supply the types, defaults, and application rules; ConfigKit handles loading,
+combination, strict decoding, and inspection.
 
 Linux is release-validated; macOS support is best-effort. See the
-[platform support policy](docs/policy/release.md#platform-support) for details.
+[platform support policy](docs/policy/release.md#platform-support).
 
-ConfigKit's simple `Load` accepts one strict YAML source (or explicit
-defaults-only input). `LoadLayered` additionally combines explicit lower-priority
-source groups with an independently selected main input. Sources can be host
-files, native `fs.FS` files, labeled bytes or readers, or snapshotted mappings.
-Enabled path and glob imports compose strictly within their group; precedence
-between groups combines mappings recursively. Both entry points return a complete,
-validated configuration with detached metadata and safe diagnostics.
-Applications may perform audited defaulting and normalization through a resolver,
-then report domain errors and warnings through read-only semantic validation. Secret
-tags and a path predicate drive deterministic redacted effective YAML. Typed secret
-references resolve environment names before validation, and explicit
-secrets-directory bootstrap is available as a separate startup operation. Explicit
-CLI override records apply above overlays. Value explanation is available through
-detached structured records and deterministic redacted output. Built-in
-`extends` relationships let a mapping inherit from a named sibling during the
-same load, retaining explicit presence and source/derivation history.
+## Load a configuration file
 
 ```go
+import "go.maximumdirect.net/configkit"
+
 type Config struct {
     Enabled bool `yaml:"enabled"`
     Workers int  `yaml:"workers"`
@@ -37,39 +27,57 @@ func ReadConfig(path string) (Config, error) {
 }
 ```
 
+Existing consumers should follow the
+[module-path migration guidance](docs/consumers/README.md#vanity-module-path-migration).
+
+## Add the features you need
+
+Start with one file. Optional features use the same loading and inspection model:
+
+- [Choose inputs](docs/consumers/README.md#choosing-a-loading-entry-point): read
+  files, an application-owned `fs.FS`, bytes, a reader, or a Go mapping. Use
+  explicit search descriptions when the application should look in several places.
+- [Supply lower-priority settings](docs/consumers/README.md#native-filesystem-and-layered-input):
+  use `LoadLayered` for bundled defaults that application configuration can override.
+- [Combine configuration](docs/config.md#explicit-imports): add declared imports,
+  select one overlay, or pass values explicitly set by your CLI parser.
+- [Reuse settings](docs/config.md#sibling-inheritance): let one named entry inherit
+  from a sibling. [Identified lists](docs/config.md#strict-document-composition)
+  also support record inheritance and replace, append, or upsert operations.
+- [Apply application rules](docs/config.md#recorded-application-resolution): derive
+  or normalize values in a resolver, then check the final configuration in a validator.
+- [Handle credentials](docs/config.md#typed-secret-references): use environment-name
+  references and choose which configuration fields to hide in inspection output.
+- [Inspect a load](docs/config.md#layered-metadata): examine sources, presence,
+  history, safe YAML output, or [changes between two loads](docs/config.md#effective-configuration-diffs).
+
+The [consumer guide](docs/consumers/README.md) walks through these tasks and links
+to maintained examples. The [configuration reference](docs/config.md) defines the
+exact YAML, combination, and lifecycle rules.
+
 ## 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.
+ConfigKit favors consistent, predictable rules across applications. A load returns
+the final configuration and metadata that distinguish supplied values such as
+`false` and `0` from omissions. Applications keep their domain rules and runtime
+initialization.
 
-Loading is synchronous and complete on return. Applications normally load once
-near startup and then use the final configuration and metadata; ConfigKit stays
-inactive until explicitly called again. Applications may initiate additional
-loads as needed. See the [loading lifecycle](docs/config.md#completion-and-resource-lifetime)
-for completion and ownership details.
+Within one layer, independent contributions combine strictly: conflicting
+values are errors. Across layers, higher-priority settings can replace
+lower-priority settings, while mappings combine by key. Identified lists have
+their declared combination rules. See the [worked combination
+examples](docs/config.md#strict-document-composition) for the details and
+exceptions.
 
-Within a configuration tier, independent contributions compose strictly: shared
-mappings combine, while overlapping non-mapping definitions are errors. Between
-precedence tiers, mappings combine recursively, retaining omitted lower-priority
-children; other values replace lower-priority values. The main document and its
-imports form one strictly composed tier. Explicit underlay groups sit below it
-and above typed defaults; a selected overlay and explicit CLI overrides sit
-above it. The [configuration contract](docs/config.md#strict-document-composition)
-owns the detailed combination rules and input-specific constraints.
+Loading finishes before the call returns. ConfigKit then stays inactive until you
+call it again; inspection uses the saved result. See
+[completion and resource lifetime](docs/config.md#completion-and-resource-lifetime).
 
-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 simple
-native-filesystem, layered, and sibling-inheritance examples alongside the migration shapes.
-See the [development guide](docs/development.md) for repository orientation and the
-[release procedure](docs/release.md) for maintainer-only candidate and publication
-steps.
+The [architecture goals](docs/policy/architecture.md#success-criteria) and
+[ADRs](docs/adr) explain design decisions, including shared import and inheritance
+ordering. [Future work](docs/roadmap/future.md) lists possible extensions.
+Contributors can start with the [development guide](docs/development.md);
+release maintainers use the [release procedure](docs/release.md).
 
 ConfigKit code is licensed under the [LGPL v3.0 or later](COPYRIGHT).
 

conversion.go

@@ -1,6 +1,6 @@
 package configkit
 
-import "gitea.maximumdirect.net/eric/ConfigKit/internal/engine"
+import "go.maximumdirect.net/configkit/internal/engine"
 
 func fromEngineLocation(value engine.Location) Location {
 	return Location{SourceID: value.SourceID, Line: value.Line, Column: value.Column}
@@ -43,10 +43,61 @@ func toEngineLocations(values []Location) []engine.Location {
 	return result
 }
 func fromEngineSourceInfo(value engine.SourceInfo) SourceInfo {
-	return SourceInfo{ID: value.ID, Label: value.Label, Path: value.Path, Layer: Layer(value.Layer), Kind: SourceKind(value.Kind), UnderlayIndex: value.UnderlayIndex, ImportedFrom: fromEngineLocationPointer(value.ImportedFrom)}
+	return SourceInfo{
+		ID: value.ID, Label: value.Label, Path: value.Path, Destination: fromEnginePath(value.Destination),
+		PlacementMode:         PlacementMode(engine.SourceInfoPlacementModeForFacade(value)),
+		DestinationIsFallback: engine.SourceInfoDestinationUnresolvedForFacade(value),
+		Layer:                 Layer(value.Layer), Kind: SourceKind(value.Kind), UnderlayIndex: value.UnderlayIndex,
+		ImportedFrom: fromEngineLocationPointer(value.ImportedFrom), VersionEvidence: fromEngineSourceVersionEvidence(value.VersionCheck),
+		EmptyImportSelections: fromEngineEmptyImportSelections(engine.SourceInfoImportSelectionsForFacade(value)),
+	}
 }
-func toEngineSourceInfo(value SourceInfo) engine.SourceInfo {
-	return engine.SourceInfo{ID: value.ID, Label: value.Label, Path: value.Path, Layer: engine.Layer(value.Layer), Kind: engine.SourceKind(value.Kind), UnderlayIndex: value.UnderlayIndex, ImportedFrom: toEngineLocationPointer(value.ImportedFrom)}
+func fromEngineEmptyImportSelections(values []engine.ImportSelectionForFacade) []EmptyImportSelection {
+	if values == nil {
+		return nil
+	}
+	result := make([]EmptyImportSelection, len(values))
+	for index, value := range values {
+		result[index] = EmptyImportSelection{
+			Path: fromEnginePath(value.Path), Location: fromEngineLocation(value.Location),
+			Selector: ImportSelector(value.Selector),
+		}
+	}
+	return result
+}
+
+func toEngineOverrides(values []Override) []engine.Override {
+	if values == nil {
+		return nil
+	}
+	result := make([]engine.Override, len(values))
+	for index, value := range values {
+		result[index] = engine.Override{
+			Path: toEnginePath(value.Path), Value: value.Value, Flag: value.Flag,
+		}
+	}
+	return result
+}
+
+func toEngineImportDefaults(value ImportDefaults) engine.ImportDefaults {
+	return engine.ImportDefaults{
+		Required:  value.Required,
+		Follow:    value.FollowSymlinks,
+		Hidden:    value.IncludeHidden,
+		Recursive: value.Recursive,
+		Pattern:   value.Pattern,
+	}
+}
+
+func fromEngineSourceVersionEvidence(value *engine.SourceVersionCheck) *SourceVersionEvidence {
+	if value == nil {
+		return nil
+	}
+	return &SourceVersionEvidence{
+		Path:     fromEnginePath(value.Path),
+		Version:  Version{Present: value.Version.Present, Null: value.Version.Null, Text: value.Version.Text},
+		Location: fromEngineLocationPointer(value.Location), Redacted: value.Redacted,
+	}
 }
 func fromEngineOrigin(value engine.Origin) Origin {
 	result := Origin{Layer: Layer(value.Layer), Locations: fromEngineLocations(value.Locations), Operation: ChangeKind(value.Operation)}
@@ -61,19 +112,6 @@ func fromEngineOrigin(value engine.Origin) Origin {
 	}
 	return result
 }
-func toEngineOrigin(value Origin) engine.Origin {
-	result := engine.Origin{Layer: engine.Layer(value.Layer), Locations: toEngineLocations(value.Locations), Operation: engine.ChangeKind(value.Operation)}
-	if value.Inheritance != nil {
-		result.Inheritance = make([]engine.InheritanceStep, len(value.Inheritance))
-		for index, step := range value.Inheritance {
-			result.Inheritance[index] = engine.InheritanceStep{
-				From: toEnginePath(step.From), To: toEnginePath(step.To), Reference: toEnginePath(step.Reference),
-				Locations: toEngineLocations(step.Locations),
-			}
-		}
-	}
-	return result
-}
 func fromEngineDiagnostic(value engine.Diagnostic) Diagnostic {
 	return Diagnostic{Code: Code(value.Code), Severity: Severity(value.Severity), Path: fromEnginePath(value.Path), Message: value.Message, Primary: fromEngineLocationPointer(value.Primary), Related: fromEngineLocations(value.Related)}
 }

development_check_test.go

@@ -66,7 +66,7 @@ func TestDevelopmentCheckHandlesFilenamesAndStopsOnFailure(t *testing.T) {
 						t.Fatal(err)
 					}
 					cmd := exec.Command("/bin/bash", filepath.Join(root, "scripts", scriptName))
-					cmd.Env = append(os.Environ(), "PATH="+bin+string(os.PathListSeparator)+os.Getenv("PATH"), "CONFIGKIT_BASELINE_TOOLCHAIN=test-baseline", "CONFIGKIT_NEWER_TOOLCHAIN=", "CONFIGKIT_TEST_FMT_LOG="+log, "CONFIGKIT_TEST_GO_LOG="+calls)
+					cmd.Env = append(os.Environ(), "PATH="+bin+string(os.PathListSeparator)+os.Getenv("PATH"), "CONFIGKIT_TEST_FMT_LOG="+log, "CONFIGKIT_TEST_GO_LOG="+calls)
 					// Log only targets selected by the script, not inherited host settings.
 					cmd.Env = append(cmd.Env, "GOOS=", "GOARCH=")
 					if name == "failed-go-check" {
@@ -108,90 +108,3 @@ func TestDevelopmentCheckHandlesFilenamesAndStopsOnFailure(t *testing.T) {
 		})
 	}
 }
-
-func TestCheckScriptsReleaseGates(t *testing.T) {
-	script, err := os.ReadFile("scripts/release-check.sh")
-	if err != nil {
-		t.Fatal(err)
-	}
-	for _, scenario := range []string{"success", "failed-test", "missing-toolchain"} {
-		t.Run(scenario, func(t *testing.T) {
-			root := t.TempDir()
-			bin := t.TempDir()
-			for _, directory := range []string{"scripts", "nested"} {
-				if err := os.Mkdir(filepath.Join(root, directory), 0700); err != nil {
-					t.Fatal(err)
-				}
-			}
-			checker := filepath.Join(root, "scripts", "release-check.sh")
-			if err := os.WriteFile(checker, script, 0700); err != nil {
-				t.Fatal(err)
-			}
-			calls := filepath.Join(bin, "go.calls")
-			goStub := `#!/bin/sh
-printf '%s|%s|%s|%s|%s|%s\n' "$GOTOOLCHAIN" "$GOPROXY" "${CGO_ENABLED-}" "${GOOS-}" "${GOARCH-}" "$*" >> "$CONFIGKIT_TEST_GO_LOG"
-if [ "${CONFIGKIT_TEST_FAIL-}" = toolchain ] && [ "${1-}" = version ]; then exit 37; fi
-if [ "${CONFIGKIT_TEST_FAIL-}" = test ] && [ "${1-}" = test ]; then exit 37; fi
-`
-			if err := os.WriteFile(filepath.Join(bin, "go"), []byte(goStub), 0700); err != nil {
-				t.Fatal(err)
-			}
-			cmd := exec.Command("/bin/bash", checker)
-			cmd.Dir = filepath.Join(root, "nested")
-			cmd.Env = append(os.Environ(),
-				"PATH="+bin+string(os.PathListSeparator)+os.Getenv("PATH"),
-				"CONFIGKIT_BASELINE_TOOLCHAIN=test-baseline",
-				"CONFIGKIT_TEST_GO_LOG="+calls,
-				"GOOS=", "GOARCH=", "CGO_ENABLED=",
-			)
-			switch scenario {
-			case "failed-test":
-				cmd.Env = append(cmd.Env, "CONFIGKIT_TEST_FAIL=test")
-			case "missing-toolchain":
-				cmd.Env = append(cmd.Env, "CONFIGKIT_TEST_FAIL=toolchain")
-			}
-			output, err := cmd.CombinedOutput()
-			if scenario == "success" && err != nil {
-				t.Fatalf("checker: %v\n%s", err, output)
-			}
-			if scenario != "success" && err == nil {
-				t.Fatalf("checker accepted %s", scenario)
-			}
-			data, err := os.ReadFile(calls)
-			if err != nil {
-				t.Fatal(err)
-			}
-			lines := strings.Split(strings.TrimSpace(string(data)), "\n")
-			for _, line := range lines {
-				if !strings.HasPrefix(line, "test-baseline|off|") {
-					t.Fatalf("toolchain or offline setting lost: %q", line)
-				}
-			}
-			if scenario == "missing-toolchain" {
-				if len(lines) != 1 || !strings.HasSuffix(lines[0], "|version") {
-					t.Fatalf("checker ran after unavailable toolchain: %q", lines)
-				}
-				return
-			}
-			if len(lines) < 2 || lines[1] != "test-baseline|off||||test -mod=readonly -vet=off -race -v ./..." {
-				t.Fatalf("release suite command changed: %q", lines)
-			}
-			if scenario == "failed-test" {
-				if len(lines) != 2 {
-					t.Fatalf("checker continued after failure: %q", lines)
-				}
-				return
-			}
-			want := []string{
-				"test-baseline|off||||version",
-				"test-baseline|off||||test -mod=readonly -vet=off -race -v ./...",
-				"test-baseline|off||||vet -mod=readonly ./...",
-				"test-baseline|off|0|linux|amd64|build -mod=readonly ./...",
-				"test-baseline|off|0|linux|arm64|build -mod=readonly ./...",
-			}
-			if strings.Join(lines, "\n") != strings.Join(want, "\n") {
-				t.Fatalf("unexpected release gates:\n%s", data)
-			}
-		})
-	}
-}

diagnostic.go

@@ -3,7 +3,7 @@ package configkit
 import (
 	"io"
 
-	"gitea.maximumdirect.net/eric/ConfigKit/internal/engine"
+	"go.maximumdirect.net/configkit/internal/engine"
 )
 
 // LoadError reports safe structured diagnostics for a failed configuration load.
@@ -50,6 +50,21 @@ func (e *LoadError) Sources() []SourceInfo {
 	return result
 }
 
+// Source returns a detached record from the sanitized source evidence retained
+// before loading failed, including placement evidence available at that point.
+// IDs are local to the failed load. It does not acquire sources or access the
+// filesystem. Empty or unknown IDs return false.
+func (e *LoadError) Source(id string) (SourceInfo, bool) {
+	if e == nil || e.value == nil {
+		return SourceInfo{}, false
+	}
+	value, ok := e.value.Source(id)
+	if !ok {
+		return SourceInfo{}, false
+	}
+	return fromEngineSourceInfo(value), true
+}
+
 // WriteDiagnostics writes diagnostics in canonical order. It escapes terminal
 // control characters and propagates writer errors, including short writes.
 func WriteDiagnostics(output io.Writer, diagnostics []Diagnostic) error {

diff.go

@@ -0,0 +1,53 @@
+package configkit
+
+import "go.maximumdirect.net/configkit/internal/engine"
+
+// Difference describes one changed value or subtree between two successful loads.
+// Left is the earlier value and Right is the later value. Snapshots are copies;
+// Present distinguishes absence from explicit null. Redacted reports hiding
+// based on sensitivity from either load. Mappings compare by key; a changed
+// sequence is reported as a whole value. Records are ordered by canonical JSON
+// pointer. HiddenChanged reports an actual hidden change, without identifying
+// the hidden member. Redaction alone does not set it.
+type Difference struct {
+	Path          Path
+	Left          ValueSnapshot
+	Right         ValueSnapshot
+	HiddenChanged bool
+}
+
+// Diff compares the saved final values of two successful loads of the same
+// configuration type, independently of later changes to Result.Config.
+// It does not reread sources, environment variables,
+// or rerun defaults or resolvers. Equal values produce no records even when
+// their sources, defaults, or resolution histories differ. Credential contents
+// are not compared: typed secret references compare by reference name only.
+//
+// Both results must be non-nil successful loads with inspection state; nil or
+// zero results return an error and no records. Load errors are returned by
+// Load, so callers must handle those before calling Diff. Snapshots are safe
+// for presentation but are not a complete reloadable configuration.
+func Diff[T any](left, right *Result[T]) ([]Difference, error) {
+	var leftInspection, rightInspection *engine.Inspection
+	if left != nil {
+		leftInspection = left.inspection
+	}
+	if right != nil {
+		rightInspection = right.inspection
+	}
+
+	values, err := engine.Diff(leftInspection, rightInspection)
+	if err != nil {
+		return nil, err
+	}
+	differences := make([]Difference, len(values))
+	for index, value := range values {
+		differences[index] = Difference{
+			Path:          fromEnginePath(value.Path),
+			Left:          fromEngineValueSnapshot(value.Left),
+			Right:         fromEngineValueSnapshot(value.Right),
+			HiddenChanged: value.HiddenChanged,
+		}
+	}
+	return differences, nil
+}

discovery.go

@@ -0,0 +1,90 @@
+package configkit
+
+import "go.maximumdirect.net/configkit/internal/engine"
+
+// Search is an immutable ordered description of possible host-file inputs.
+// It is consumed only when passed to SearchConfig and used by a load.
+type Search struct{ value engine.Search }
+
+// FilenameGroup selects filenames in order for a directory search.
+// Construct groups with NamedFilenames, GenericFilenames, or CustomFilenames.
+type FilenameGroup struct{ value engine.FilenameGroup }
+
+// SearchOptions controls whether a search must select a file.
+type SearchOptions struct {
+	// Required reports a missing-source error if the complete search is exhausted.
+	Required bool
+}
+
+// DirectorySearchOptions selects the filename groups used by SearchDirectory.
+type DirectorySearchOptions struct {
+	// Filenames concatenates groups in order. A nil slice uses Named then Generic;
+	// a non-nil empty slice selects no filenames.
+	Filenames []FilenameGroup
+}
+
+// NamedFilenames selects <application>.yml followed by <application>.yaml.
+func NamedFilenames() FilenameGroup { return FilenameGroup{value: engine.NamedFilenames()} }
+
+// GenericFilenames selects config.yml, config.yaml, main.yml, and main.yaml.
+func GenericFilenames() FilenameGroup { return FilenameGroup{value: engine.GenericFilenames()} }
+
+// CustomFilenames selects literal filename components in the supplied order.
+// Names cannot be empty or contain a directory component.
+func CustomFilenames(names ...string) FilenameGroup {
+	return FilenameGroup{value: engine.CustomFilenames(names...)}
+}
+
+// SearchDirectory describes a search within directory. Omitted options or a nil
+// Filenames slice uses Named then Generic groups. Explicitly empty Filenames
+// selects no names and does not resolve the directory base.
+func SearchDirectory(directory string, supplied ...DirectorySearchOptions) Search {
+	options := make([]engine.DirectorySearchOptions, len(supplied))
+	for index, option := range supplied {
+		if option.Filenames == nil {
+			continue
+		}
+		options[index].Filenames = make([]engine.FilenameGroup, len(option.Filenames))
+		for groupIndex, group := range option.Filenames {
+			options[index].Filenames[groupIndex] = group.value
+		}
+	}
+	return Search{value: engine.SearchDirectory(directory, options...)}
+}
+
+// SearchPaths describes literal host-file candidates in the supplied order.
+func SearchPaths(paths ...string) Search { return Search{value: engine.Paths(paths...)} }
+
+// Searches concatenates descriptions in order and snapshots their entries.
+func Searches(searches ...Search) Search {
+	values := make([]engine.Search, len(searches))
+	for index, search := range searches {
+		values[index] = search.value
+	}
+	return Search{value: engine.Searches(values...)}
+}
+
+// UnixSystemDirectories describes the conventional Unix system directories.
+// Loading on an unsupported platform fails if this preset is reached.
+func UnixSystemDirectories() Search { return Search{value: engine.UnixSystemDirectories()} }
+
+// UserConfigDirectory describes searches rooted at the Go user-config directory.
+func UserConfigDirectory() Search { return Search{value: engine.UserConfigDirectory()} }
+
+// HomeDirectory describes searches rooted at the Go home directory.
+func HomeDirectory() Search { return Search{value: engine.HomeDirectory()} }
+
+// WorkingDirectory describes application-named files in the current directory.
+func WorkingDirectory() Search { return Search{value: engine.WorkingDirectory()} }
+
+// SearchConfig creates a source that selects the first matching host file when
+// consumed by Load or LoadLayered. Without Required, exhausting the search uses
+// the absent-input lifecycle. Description and option errors are reported while
+// loading.
+func SearchConfig(application string, search Search, supplied ...SearchOptions) Source {
+	options := make([]engine.SearchOptions, len(supplied))
+	for index, option := range supplied {
+		options[index] = engine.SearchOptions{Required: option.Required}
+	}
+	return Source{value: engine.SearchConfig(application, search.value, options...)}
+}

doc.go

@@ -1,9 +1,17 @@
-// Package configkit provides deterministic, application-owned configuration
-// loading for Go programs.
+// Package configkit loads YAML into an application's Go configuration type and
+// lets the application inspect where the final values came from.
 //
-// Load supports file, byte, reader, and explicit no-input sources with strict YAML,
-// typed defaults, imports, overlays, CLI overrides, schema-version checks, detached
-// metadata, recorded application resolution, typed secret references, safe effective
-// rendering, read-only semantic validation, and structured load errors. The
-// configuration contract is documented in docs/config.md.
+// Start with Load and a File, Bytes, Reader, Mapping, or Filesystem.File source.
+// Use NoSource for deliberately absent input or SearchConfig for an explicitly
+// chosen search. Applications supply types, defaults, version rules, and callbacks
+// for deriving and validating values. LoadLayered adds lower-priority input groups.
+//
+// A successful load returns the final configuration and saved inspection state.
+// Metadata tracks supplied values, including false and zero; explanations retain
+// safe earlier values. WriteEffective and Diff use the saved state even if the
+// application later changes Result.Config. Secret references resolve credentials
+// during loading, while inspection follows the configured hiding rules.
+//
+// The consumer guide is in docs/consumers/README.md. The exact YAML, combination,
+// lifecycle, and ownership rules are documented in docs/config.md.
 package configkit

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

@@ -1,6 +1,8 @@
 # ADR 0005: Record explicit CLI overrides and safe value explanation
 
-Status: accepted
+Status: Partially superseded by
+[ADR 0018](0018-cli-after-structural-resolution.md) for override-before-decoding
+ordering. The remaining ownership and safe explanation decisions remain accepted.
 
 Date: 2026-09-06
 

docs/adr/0007-source-backed-underlays.md

@@ -2,7 +2,9 @@
 
 ## Status
 
-Proposed draft for review. Completed planning and remediation records are
+Proposed draft for review; its whole-sequence precedence replacement rule is
+superseded by [ADR 0017](0017-collection-sequence-policy.md). The remainder
+retains its proposed status. Completed planning and remediation records are
 preserved in Git history at `b604aa1` under `docs/roadmap/`; the
 [configuration contract](../config.md#layered-loading) owns current behavior.
 

docs/adr/0009-sibling-inheritance.md

@@ -2,8 +2,14 @@
 
 ## Status
 
-Accepted and implemented. The [configuration contract](../config.md#sibling-inheritance)
-owns current behavior. The completed implementation plan is preserved in Git
+Partially superseded by [ADR 0017](0017-collection-sequence-policy.md) for
+sequence combination and the addition of identified-sequence sibling scopes,
+and [ADR 0018](0018-cli-after-structural-resolution.md) for CLI-before-inheritance
+ordering. Existing mapping-sibling scopes and the remaining ownership and
+inspection decisions remain accepted.
+
+The [configuration contract](../config.md#sibling-inheritance) owns implemented
+behavior. The completed implementation plan is preserved in Git
 history at `83c59ea`.
 
 ## Date

docs/adr/0010-effective-configuration-diff.md

@@ -0,0 +1,99 @@
+# ADR 0010: Compare Frozen Effective Configuration Snapshots
+
+## Status
+
+Accepted and implemented. The
+[configuration contract](../config.md#effective-configuration-diffs) owns current
+behavior. Completed planning and remediation records are preserved in Git
+history at `1c2610c` under `docs/roadmap/`.
+
+## Date
+
+2026-10-09
+
+## Context
+
+Applications need to inspect how two completed configurations differ, including
+the effective impact of an overlay after defaults and application resolution.
+ConfigKit already retains canonical typed inspection snapshots, semantic paths,
+presence information, and sensitivity classification for successful loads.
+
+Extending this inspection model lets applications share configuration comparison
+and safe disclosure while keeping their presentation and domain interpretation.
+The operation should follow ConfigKit's existing equality, ownership, and secret
+boundaries so consumers can reason about loading and inspection consistently.
+
+## Decision
+
+Provide structured effective-value comparison between successful results of the
+same configuration type. Compare their retained canonical inspection snapshots
+through the root-owned public facade. Each comparison uses the completed load
+state and returns detached records with a semantic path and safe left and right
+value snapshots.
+
+Use canonical value equality and the existing structural comparison rules.
+Mappings compare recursively, sequences report atomic changes, and scalar or
+kind replacements report the affected region. Presence distinguishes additions
+and removals from explicit null. Equal effective values produce an empty diff;
+source attribution, explicit-input status, and history remain separately
+inspectable through each result. Canonical pointer ordering makes reporting
+deterministic.
+
+Detect changes before masking values. Apply sensitivity from both loads to both
+returned sides, including historical and dependency-derived classification.
+Preserve public content where the shapes permit corresponding sensitive regions
+to be identified. When a structural replacement prevents safe correspondence,
+mask the complete reported replacement region on both present sides. Absence
+retains its own representation.
+
+Keep masking and hidden-change information distinct. Each record indicates
+whether an actual change is withheld by redaction, allowing applications to
+display a changed-sensitive-value indicator even when safe snapshots render
+identically. Public-only changes alongside unchanged masked content retain that
+distinction.
+
+Typed secret references participate through their configured environment names.
+Resolved credential bytes remain behind the existing explicit secret accessor.
+The comparison uses the same frozen inspection boundary as effective rendering
+and explanation.
+
+ConfigKit owns comparison and paired safe disclosure. Applications own labels,
+layout, and rendering of the returned changed regions. Reusing the existing
+snapshot representation and engine boundary keeps the extension consistent with
+the library's established inspection model.
+
+## Alternatives considered
+
+- **Compare input text or separately rendered YAML.** Supports familiar textual
+  displays, but input text precedes composition and resolution, and independently
+  redacted output can hide changes or apply different disclosure rules. Canonical
+  comparison with paired masking represents the completed configuration.
+- **Leave comparison to applications using returned Go values.** Offers direct
+  access to application types, but duplicates structural and redaction machinery
+  and observes caller mutation. Retained inspection snapshots preserve the
+  completed load's values and established ownership boundary.
+- **Align sequence elements and return context-rich rendering data.** Enables
+  finer-grained displays, but requires additional correspondence and disclosure
+  rules. Atomic sequence records and existing value snapshots satisfy the
+  selected changed-region workflows with a smaller public model.
+- **Compare resolved credentials or retain credential-derived tokens.** Could
+  detect rotation behind an unchanged reference, but expands retained sensitive
+  state and introduces a separate trusted comparison mechanism. Reference-name
+  comparison preserves the existing inspection boundary.
+
+## Consequences
+
+Applications can compare independently loaded configurations using ConfigKit's
+shared equality, presence, and disclosure rules. Existing composition and load
+semantics continue to determine the values being compared. Caller mutation of a
+returned configuration leaves its retained comparison snapshot unchanged.
+
+Paired redaction can conceal public content within a structurally incompatible
+replacement. The changed region and hidden-change indicator still communicate
+its effective impact. Credential rotation behind an unchanged environment name
+produces equal reference values for comparison.
+
+The implementation requires operation-local disclosure preparation and focused
+coverage for presence, shape changes, historical sensitivity, and detached
+results. Applications retain control of presentation; changed-region records
+supply the safe data needed for that responsibility.

docs/adr/0011-input-destinations.md

@@ -0,0 +1,74 @@
+# ADR 0011: Place Configuration Inputs at Mapping Destinations
+
+## Status
+
+Accepted and implemented. Current placement behavior is owned by the
+[configuration contract](../config.md#input-destinations). The accepted
+relative-import extension is recorded in
+[ADR 0012](0012-relative-import-destinations.md). The completed roadmap, consumer
+request, and review records are preserved at `e4270c9` under `docs/roadmap/` in
+Git history; the original input-destination implementation plan remains at
+`315f464:docs/roadmap/implementation.md`.
+
+## Date
+
+2026-10-14
+
+## Context
+
+Consumers assembling collections of independently authored configuration
+fragments need each source to contribute beneath a selected application path.
+Requiring consumers to rewrite source documents or merge completed values would
+separate placement from ConfigKit's existing composition, precedence, source
+identity, and inspection behavior. Placement should remain part of the ordinary
+loading lifecycle and preserve the root-owned public facade.
+
+## Decision
+
+Add an optional `Destination Path` to root-owned `Input` and expose the effective
+destination on existing `SourceInfo` records. The empty path means the existing
+application root. A non-empty destination is a sequence of literal mapping keys;
+explicit sequence-index segments are invalid. Existing reserved structural keys
+remain reserved, while keys that merely contain their spelling remain ordinary
+keys.
+
+Acquire and interpret each source using its original physical identity and
+source-local directives, then place its application body before strict
+composition and the existing final lifecycle. Imported application bodies
+inherit the input destination. Placement applies to main and underlay inputs;
+ordinary root loading, selected overlays, and CLI inputs retain root placement.
+The main-owned version rule continues to check its effective application path
+at its existing lifecycle point.
+
+Placement preserves authored node locations and source identity. Introduced
+mapping structure belongs to the contributing source and uses that document's
+root location as its source-coordinate fallback. A present empty mapping
+materializes its destination; an absent `NoSource` contributes nothing. The
+result continues through the existing strict composition, overlay, inheritance,
+typed loading, diagnostics, provenance, history, sensitivity, and resource
+context mechanisms.
+
+The added exported fields preserve keyed and zero-value struct use. Callers
+using unkeyed composite literals for `Input` or `SourceInfo` must migrate to
+keyed literals. Treat this feature as minor-release work; select the version and
+document the compatibility impact during separately authorized release
+preparation, consistent with the release policy.
+
+## Alternatives considered
+
+- **Rewrite or merge sources in consumers.** This makes each consumer reproduce
+  placement, strict composition, source attribution, and inspection semantics.
+- **Add a separate loading entry point or public wrapper type.** This creates a
+  parallel API for a behavior that belongs to existing per-input loading.
+- **Load each fragment as a complete application before placement.** This runs
+  defaults, decoding, resolution, and validation on incomplete fragments rather
+  than once on the assembled application.
+
+## Consequences
+
+Consumers can assemble contributions at effective mapping paths in one ordinary
+layered load and inspect each source's placement through existing source
+records. Paths, conflicts, and later application operations use the placed
+structure while source coordinates and relative-resource contexts continue to
+identify their original sources. Public field additions require release-note
+guidance for callers using unkeyed literals.

docs/adr/0012-relative-import-destinations.md

@@ -0,0 +1,78 @@
+# ADR 0012: Place Imported Configuration at Relative Destinations
+
+## Status
+
+Accepted and implemented. The
+[configuration contract](../config.md#input-destinations) owns current behavior.
+The completed roadmap and review records are preserved at `e4270c9` under
+`docs/roadmap/` in Git history; the relative-import implementation plan remains
+at `d9f08ff:docs/roadmap/implementation.md`.
+
+## Date
+
+2026-10-14
+
+## Context
+
+ConfigKit can place an input document at a literal mapping path while retaining
+source identity, composition, and inspection in its normal loading lifecycle.
+An importing document can currently bring in other documents, but those
+contributions inherit only the importing input's destination. Consumers that
+assemble a collection therefore cannot declare the layout of imported
+fragments alongside the import itself without rewriting source documents or
+performing another merge outside ConfigKit.
+
+The extension should reuse input placement and the existing import lifecycle.
+Logical application placement must remain independent from physical path
+resolution, source identity, precedence, and resource ownership.
+
+## Decision
+
+Add an optional `destination` field to each YAML import declaration. Its value
+is a sequence of strings representing literal mapping-key segments. Omission
+and an empty sequence add no segments. A non-empty destination appends to the
+effective destination of the immediately importing document; nested imports
+continue from the resulting child destination. Every match of one glob
+declaration receives the same computed destination.
+
+Use the existing input-destination validation and reserved-key rules. Do not
+interpret destination segments as filesystem paths, separators, sequence
+indices, or root-reset instructions. Physical import paths continue to resolve
+from their declaring source under existing containment rules.
+
+Imports remain in their existing strict-composition group. A destination does
+not grant precedence, bypass cycle or repeated-source rules, or change source
+identity. Existing placement, version ownership, source records, diagnostics,
+resource contexts, inheritance, history, and inspection mechanisms continue to
+govern the placed contributions. No public Go entry point or independent
+specification-header behavior is introduced.
+
+This is additive YAML functionality and is minor-release work. Version
+selection, release notes, roadmap retirement, and publication remain separate
+release-preparation work.
+
+## Alternatives Considered
+
+- **Require complete application-root destinations on every import.** This
+  avoids inherited context but repeats collection prefixes in nested source
+  declarations and does not express placement relative to the importing
+  document.
+- **Encode destinations as dotted or slash-delimited strings.** This introduces
+  separator and escaping rules even though existing paths already represent
+  literal mapping keys as segments.
+- **Rewrite or merge imported documents in consumers.** This duplicates source
+  placement, strict composition, attribution, and inspection behavior outside
+  ConfigKit's loading lifecycle.
+- **Add independent specification headers or collection-specific validation.**
+  These are separate design questions and are not required to declare relative
+  placement.
+
+## Consequences
+
+Import declarations can describe the logical placement of their contributions
+while preserving the physical source and existing composition lifecycle.
+Placement is immediate-parent-relative, so nested imports accumulate their
+declared segments and sibling declarations remain independent. The feature is
+implemented behind the existing public loading surface; detailed validation,
+diagnostic, accounting, and inspection requirements are tracked by the
+implementation roadmap.

docs/adr/0013-shared-source-version-checks.md

@@ -0,0 +1,92 @@
+# ADR 0013: Check Source Versions with One Shared Policy
+
+## Status
+
+Accepted and implemented. The
+[configuration contract](../config.md#shared-source-version-checks) owns current
+behavior. The completed roadmap, implementation plan, consumer request, and
+resolved review findings are preserved at `e4270c9` under `docs/roadmap/` in
+Git history; the [development guide](../development.md#baseline-validation)
+provides retrieval examples.
+
+## Date
+
+2026-10-15
+
+## Context
+
+Applications that assemble one configuration from independently authored
+documents need a way to require that each contributing document declares a
+version accepted by the application's existing `Definition.Version` checker.
+Checking only the eventual composed value lets another source hide a rejected
+declaration, while separate consumer-side parsing duplicates ConfigKit's source
+handling and diagnostics.
+
+The extension must preserve one application-owned acceptance policy and the
+existing loading lifecycle. Source declarations are compatibility evidence, not
+independent fragment schemas or values to compare for equality. Existing
+composition, placement, precedence, source identity, diagnostics, and
+sensitivity rules remain authoritative.
+
+## Decision
+
+Provide a load-wide source-version mode for ordinary and layered loading. The
+zero-value mode preserves current behavior. The enabled modes check declarations
+when present or require them, using the existing `Definition.Version` path and
+checker. Interpret the configured path relative to each participating source
+before placement or composition. Different declarations may be accepted by the
+same checker; ConfigKit adds no equality, SemVer, or expected-version rule.
+
+Apply the selected policy to the actual main document, direct underlays,
+imports, and selected overlays. Missing non-main declarations are skipped in
+if-present mode and rejected in required mode. Existing main absence behavior
+remains, with required mode additionally rejecting an absent declaration on an
+actual main document. `NoSource`, unmatched optional inputs, synthetic field
+operations, and empty groups do not become documents that need declarations.
+
+Reuse the existing version vocabulary and validation boundary: absence, null,
+exact strings, and strict decimal integers retain their established meanings;
+unsupported present values fail version-type validation. Warnings remain
+nonfatal, and source declarations do not replace final application decoding or
+domain validation.
+
+After an accepted non-main declaration is checked, consume exactly that node
+before its remaining application content is composed or overlaid. Preserve the
+main declaration and its value semantics. Keep the declaration, source-local
+path, physical location, and checked absence as detached source evidence,
+separate from effective application values and history. Apply established
+sensitivity rules to that evidence, including original mounted paths and
+ancestors; retain existing safe failure disclosure.
+
+In enabled modes, the main declaration remains source-local while its protected
+application path is derived from the main input's destination. This distinction
+does not change default-mode path interpretation or weaken protection of
+remaining payload and synthetic operations.
+
+Public option-field additions and the enabled-mode interpretation for mounted
+main inputs are compatibility considerations for separately authorized minor-
+release preparation. This decision does not select a release version or
+authorize release notes or publication.
+
+## Alternatives Considered
+
+- **Check only the final composed value.** Later sources can hide an earlier
+  rejected declaration, so this does not validate every contributing document.
+- **Let consumers parse and check each source.** This duplicates acquisition,
+  source attribution, safe diagnostics, and lifecycle coordination in every
+  application.
+- **Require declarations to be equal or impose a universal version grammar.**
+  Consumers already own the acceptance policy; ConfigKit need not invent an
+  expected value or a domain-specific compatibility rule.
+- **Keep accepted non-main declarations in application payload.** A selected
+  source-local declaration is metadata for this policy and cannot also remain
+  an ordinary field at the same path without ambiguity.
+
+## Consequences
+
+Consumers can apply one existing version policy across contributing documents
+and select gradual or required adoption per load. Accepted non-main headers no
+longer participate in application composition; their inspectable evidence is
+kept separate and subject to sensitivity classification. Default callers retain
+current behavior. The implementation plan records the concrete API names,
+integration order, and validation evidence.

docs/adr/0014-sequence-placement-and-composition.md

@@ -0,0 +1,81 @@
+# ADR 0014: Place and Compose Sequence Items Explicitly
+
+## Status
+
+Partially superseded by [ADR 0017](0017-collection-sequence-policy.md) for
+identity ownership and sequence combination. Explicit source placement remains
+accepted.
+
+The [configuration contract](../config.md#strict-document-composition)
+defines implemented behavior, and the [consumer guide](../consumers/README.md#identified-prompt-sequences)
+shows the maintained example. The completed roadmap, implementation plan, and
+resolved remediation record are preserved in Git history at `008d2ba` under
+`docs/roadmap/`; see the [development guide](../development.md) for retrieval
+commands.
+
+## Date
+
+2026-10-16
+
+## Context
+
+ConfigKit strictly composes independent documents by recursively combining
+mappings and rejecting other overlapping values. This makes two independently
+authored sequence fragments conflict, even when their records are distinct.
+Precedence assembly has a different purpose: a higher-priority present sequence
+replaces the lower-priority sequence as one value. Those existing rules are
+predictable, but they do not express the separate operation of collecting
+independent records while rejecting duplicate identities.
+
+Likewise, mapping destinations place a source beneath literal mapping keys, but
+there is no explicit way to state that a source mapping represents one item in a
+sequence. Inferring that intent from document shape or fields would make source
+meaning implicit and change existing placement behavior.
+
+## Decision
+
+Keep mapping placement as the zero-value behavior and add an explicit item
+placement choice for a source whose mapping should become one element at a
+non-root sequence destination. Item placement provides structure only; it does
+not infer or synthesize identity values.
+
+Allow a definition to register literal mapping paths and one literal identity
+field for sequences at those paths. Within each strict composition tier, a
+registered sequence accepts mapping records with a present string identity,
+appends distinct records in contribution order, and rejects repeated exact
+identity strings. Identical registrations coalesce; conflicting identity fields
+for the same path are invalid. Registration does not recursively select paths
+inside sequence records.
+
+Keep precedence assembly unchanged. A present higher-priority sequence replaces
+the lower-priority value wholesale, including at a registered path. Registration
+changes strict composition only; it does not turn precedence into append or
+identity-based merging.
+
+This decision preserves ConfigKit's distinction between independent
+same-priority contributions and intentional precedence. Explicit source
+placement and definition-owned composition policy make the two required choices
+visible while keeping the existing zero-value load behavior.
+
+## Alternatives Considered
+
+- **Infer item placement from a source mapping or identity field.** Shape-based
+  inference would make ordinary mapping placement depend on document contents
+  and would leave the intended destination ambiguous.
+- **Append all overlapping sequences during strict composition.** This would
+  change existing conflict semantics at unregistered paths and would not detect
+  duplicate records.
+- **Merge matching records recursively by identity.** This would add a second
+  recursive merge rule with different conflict and precedence behavior from
+  ConfigKit's existing mapping composition and overlay operations.
+- **Use identity to merge sequences across precedence tiers.** This would
+  change established whole-value replacement semantics and conflate strict
+  composition with precedence.
+
+## Consequences
+
+Consumers can explicitly place mappings as sequence items and opt selected
+sequences into duplicate-rejecting strict composition. Unregistered sequences
+retain their current strict-conflict behavior, and higher-priority sequences
+continue to replace lower-priority ones. The implementation plan owns the exact
+API, YAML syntax, diagnostics, and implementation status.

docs/adr/0015-shared-dependency-ready-ordering.md

@@ -0,0 +1,68 @@
+# ADR 0015: Share Dependency-Ready Ordering Across Imports and Inheritance
+
+## Status
+
+Accepted. Implemented behavior is described in the
+[configuration contract](../config.md#explicit-imports) and
+[internal import overview](../internal/imports.md).
+
+## Date
+
+2026-10-19
+
+## Context
+
+Imports and sibling inheritance both resolve relationships between configuration
+contributions. Their existing resolvers use different traversal rules, making
+ordering depend on which mechanism expresses a dependency. Ordering affects
+sequence contributions, provenance, and diagnostics, so a consistent rule is
+part of ConfigKit's configuration model.
+
+The resolvers also serve distinct purposes. Imports strictly compose sources;
+inheritance overlays a child on its resolved parent after source assembly.
+Item-local contributions and nested inheritance introduce scope boundaries that
+resolution must preserve.
+
+## Decision
+
+ConfigKit owns one shared dependency-ready scheduler for imports and sibling
+inheritance. Both resolvers use Kahn's algorithm with a stable ordering key,
+selecting the smallest currently eligible node after its dependencies have
+completed. The shared scheduler owns eligibility, deterministic tie-breaking,
+and dependency-cycle identification. Each resolver owns construction of its
+dependency relationships and application of its domain operations.
+
+Apply the common scheduling rule within the scopes where dependencies are
+available. Complete item-local contributions before item placement and resolve
+enclosing inheritance before relationships in the resulting nested scopes.
+Source discovery supplies the import graph; the scheduler determines resolution
+order.
+
+Strict composition, inheritance overlay, and precedence tiers retain their
+existing ownership and meanings under [ADR 0001](0001-separate-composition-and-overlay.md).
+The lifecycle and scope decisions in
+[ADR 0009](0009-sibling-inheritance.md) continue to govern inheritance. Import
+admission retains its cycle and repeated-source rules.
+
+## Alternatives Considered
+
+- **Deterministic depth-first postorder.** Keeps dependency branches together,
+  but gives traversal branch selection an additional role in ordering.
+- **Dependency rounds.** Groups nodes by readiness rounds, but delays newly
+  eligible nodes until the current round finishes.
+- **Descending longest-path depth.** Prioritizes the furthest dependencies,
+  but adds distance from the root as an ordering policy.
+- **Separate resolver algorithms.** Allows local specialization, but leaves
+  consumers and maintainers with different rules for analogous dependencies.
+
+## Consequences
+
+Both resolvers follow one deterministic ordering model and share responsibility
+for maintaining that model. Resolver-specific scopes, combination semantics,
+and source-admission rules remain explicit at their integration boundaries.
+
+Independent branches may interleave as nodes become eligible. Adopting this
+rule changes existing traversal-dependent sequence positions and reporting
+order, requiring coordinated review of source assembly, provenance, and
+inheritance behavior. The configuration contract owns the implemented ordering
+details.

docs/adr/0016-independent-import-controls.md

@@ -0,0 +1,83 @@
+# ADR 0016: Separate Import Selection, Traversal, and Presence Requirements
+
+## Status
+
+Accepted. Implemented behavior is described in the
+[configuration contract](../config.md#explicit-imports), the
+[public API declarations](../../lifecycle.go), and the
+[internal import overview](../internal/imports.md).
+
+## Date
+
+2026-10-19
+
+## Context
+
+Consumers assemble configurations from named files and collections whose layout
+varies between installations. Simple imports should require little setup, while
+larger collections need control over discovery, recursion, filtering, and
+required contributions. Combining those choices implicitly makes declarations
+harder to interpret and pushes source-selection work into applications.
+
+Discovery can also reach a candidate through overlapping searches or encounter
+different names for one canonical source. Selection and source admission need
+distinct identities to support useful search unions while preserving ConfigKit's
+existing source-integrity rules.
+
+## Decision
+
+ConfigKit owns import discovery and selection within its source-loading
+lifecycle. Support explicit files, directory searches, and path globs as
+distinct selection forms. Keep traversal, filename filtering, and presence
+requirements independently expressible. Discovery determines the selected
+contributions; the shared scheduler in
+[ADR 0015](0015-shared-dependency-ready-ordering.md) determines their resolution
+order.
+
+Use optional-by-default imports with explicit requiredness controls. Selected
+sources remain subject to ConfigKit's validity, containment, resource, and
+composition contracts. This applies the library's
+[simplicity and defaults principles](../policy/architecture.md#simplicity-defaults-and-explicit-controls)
+to import absence while retaining meaningful errors for invalid contributions.
+
+Applications own their selected import defaults. Authored declaration values
+take precedence over application defaults, which take precedence over library
+defaults. Each declaration resolves applicable controls independently,
+including declarations in imported sources. This gives applications a shared
+baseline while preserving explicit choices in individual declarations.
+
+Keep declaration-local candidate identity separate from canonical source
+identity. Search unions coalesce repeated candidate paths within a source
+namespace before symlink resolution; filename filtering uses the selected or
+discovered name. Source admission continues to use canonical identity and the
+existing repeated-source rules. Distinct aliases retain their separate
+inclusion routes.
+
+## Alternatives Considered
+
+- **Use path globs for all discovery.** Offers one selection form, but makes
+  collection traversal depend on path-pattern structure and complicates
+  independently controlling recursion and filename filtering.
+- **Offer only explicit files and directory searches.** Reduces the selector
+  vocabulary, but moves wildcard directory selection into repeated declarations
+  or application-side discovery.
+- **Require every import by default.** Detects absent contributions immediately,
+  but requires repeated opt-outs for installations with optional components.
+- **Make application settings override authored declarations.** Provides central
+  enforcement, but prevents declarations from expressing local exceptions.
+- **Deduplicate selections globally by canonical source identity.** Coalesces
+  aliases and separate inclusion routes, but changes the existing repeated-source
+  contract and obscures independently authored contributions.
+
+## Consequences
+
+Consumers can express simple imports and more selective collection searches
+through the same loading lifecycle. Applications choose defaults and validate
+their required effective configuration; ConfigKit owns consistent selection,
+source admission, composition, and inspection.
+
+Optional absence can conceal misspelled selectors, so requiredness and
+inspection provide explicit ways to detect and explain missing contributions.
+Declaration-local deduplication requires the loader to preserve candidate
+identity alongside canonical source identity. The configuration and public API
+contracts own the implemented behavior.

docs/adr/0017-collection-sequence-policy.md

@@ -0,0 +1,143 @@
+# ADR 0017: Define Identity and Merge Rules for Each Collection
+
+## Status
+
+Accepted.
+
+This supersedes the decisions about who declares identity and how
+sequences combine in [ADR 0014](0014-sequence-placement-and-composition.md),
+and the rule that inheritance always replaces sequences in
+[ADR 0009](0009-sibling-inheritance.md). It also extends that ADR's sibling
+scopes to identified sequences. Existing mapping-sibling scopes and source
+placement continue to apply. It supersedes the whole-sequence
+precedence replacement rule in the proposed
+[ADR 0007](0007-source-backed-underlays.md).
+
+## Date
+
+2026-10-22
+
+## Context
+
+ConfigKit can load separate files as records in a sequence. Applications can
+register an identity key so records with different identities combine and
+duplicates fail. However, a higher configuration layer or an inheriting mapping
+currently replaces the whole sequence. Applications that need to extend a
+catalog across layers must write their own merging code and keep source and
+history information consistent with its results.
+
+Configuration authors need to choose how records are identified and whether a
+layer adds records, updates records, or replaces the collection. Applications
+also need a way to require unique identities in the final loaded configuration.
+These rules must work consistently for imported records, inline sequences,
+overlays, and inheritance.
+
+Records in a sequence may also share settings. Authors need to reuse those
+settings through inheritance while keeping each record's own identity.
+
+## Decision
+
+ConfigKit manages identity and merge rules for each collection during loading.
+Configuration files can declare those rules for imported and inline sequences,
+including sequences in selected overlays. Applications can require a particular
+identity definition, and configuration declarations must agree with it. Source
+placement determines where each contribution enters the configuration.
+
+Keep the distinction between contributions at the same priority and overrides
+from a higher layer, as established in
+[ADR 0001](0001-separate-composition-and-overlay.md). Within one tier, records
+with distinct identities combine; duplicate identities and conflicting
+declarations fail. Determine the applicable rules before combining those
+contributions, including any identity established in lower tiers.
+
+Across layers, support three operations: replace the whole sequence, append
+records while rejecting duplicate identities, or replace whole records by
+identity (`upsert`). Source layering and sibling inheritance use the same
+operations. For inheritance, the rules at the inheriting destination determine
+which operation applies.
+
+An identified sequence is also a sibling scope for inheritance. A record may
+inherit from one other record in the same sequence, selected by its complete
+identity. Each record supplies its own identity before inheritance. The child
+keeps that identity and combines its settings with the parent's other fields,
+using the existing mapping and collection rules. Parents remain ordinary records
+subject to normal validation.
+
+Resolve these relationships after source assembly, using the same dependency
+ordering as mapping-sibling inheritance. Resolve nested relationships at each
+inheriting destination. Preserve the assembled sequence order. Whole-record
+upsert keeps its existing meaning; inheritance then uses the records that remain.
+Typed defaults, CLI overrides, and application resolution follow the lifecycle
+in [ADR 0018](0018-cli-after-structural-resolution.md).
+
+An explicitly selected operation remains in effect at its destination until a
+higher layer changes it. When no explicit operation applies, use upsert if an
+identity definition is available; otherwise replace the whole sequence. Authors
+can declare identity and an operation before supplying any records. Keep source
+acquisition order separate from layer priority and the dependency ordering
+established by [ADR 0015](0015-shared-dependency-ready-ordering.md).
+
+Rules declared inside a record belong to that record. Retaining the record
+retains its local rules; replacing it discards them. Replacing a whole collection
+can discard its previous YAML identity definition, while application requirements
+still apply. Inheritance can copy collection identity, but the inheriting
+destination chooses its operation. Application registrations continue to govern
+the paths where they were registered. The same ownership rules apply to
+declarations made before a sequence exists.
+
+Check YAML-declared identity when combining collections during source assembly
+and inheritance. Application registrations also require the final loaded
+sequences to satisfy their identity rules, including after typed defaults, CLI
+overrides, and application resolution. This guarantee checks sequences that
+exist; the application schema and validation decide whether a collection must
+exist and which value types are allowed. The guarantee applies when loading
+completes, rather than to every intermediate callback state or changes made by
+the caller afterward.
+
+Preserve explicit presence, source attribution, history, sensitivity, and
+resource context through these operations, following
+[ADR 0003](0003-preserve-presence-and-resolution-history.md). Typed defaults,
+CLI assignments, and application resolution keep their own rules for changing
+values. The public API provides registration and inspection; the implementation
+chooses how to store and track collection rules internally.
+
+## Alternatives Considered
+
+- **Keep identity application-owned and always replace sequences across layers.**
+  Keeps the current design small, but reusable catalogs require application
+  changes or custom merging code.
+- **Put merge rules on each import.** Keeps the rules beside the imported source,
+  but inline sequences and overlays need a separate way to declare them. It also
+  makes rules for a collection spread across several imports harder to reconcile.
+- **Merge individual fields of records with matching identities.** Allows partial
+  record updates, but adds rules for field conflicts and retained values.
+  Replacing the whole record makes the update's scope clear.
+- **Keep inheritance limited to mapping siblings.** Keeps parent lookup simpler,
+  but authors of sequence records must duplicate shared settings or applications
+  must implement inheritance themselves. Collection identity provides a way to
+  select a parent within the existing loading process.
+- **Check every YAML identity again at the end of loading.** Gives YAML declarations
+  authority over values changed by defaults, CLI assignments, and application
+  resolution. This extends the lifetime of those declarations; application
+  registration provides that final guarantee when needed.
+
+## Consequences
+
+Consumers can build and customize catalogs in one load while retaining useful
+inspection information. Configuration authors choose how collections combine
+within application requirements. Duplicate identities among contributions at
+the same priority remain errors.
+
+Existing registered collections use upsert across layers by default unless an
+explicit operation selects otherwise. Correct loading now requires tracking
+which declarations still apply as records are replaced, copied, or moved to new
+positions. Lower-tier identity must be available before combining higher-tier
+contributions.
+
+Record inheritance also requires parent lookup by identity and checking for
+missing parents and cycles. Copied settings retain the same source, history,
+and sensitivity information as mapping-sibling inheritance.
+
+The [configuration contract](../config.md#strict-document-composition) defines
+declaration syntax, identity comparison, omission and empty-value behavior, and
+diagnostics for the implemented feature.

docs/adr/0018-cli-after-structural-resolution.md

@@ -0,0 +1,84 @@
+# ADR 0018: Apply CLI Overrides After Inheritance and Decoding
+
+## Status
+
+Accepted.
+
+This supersedes the rule that CLI overrides apply before decoding in
+[ADR 0005](0005-explicit-overrides-and-safe-explanation.md) and the
+rule that they apply before inheritance in [ADR 0009](0009-sibling-inheritance.md).
+Their remaining ownership, inheritance scope, and safe inspection decisions
+continue to apply.
+
+## Date
+
+2026-10-22
+
+## Context
+
+Explicit command-line values are the operator's highest-priority input. If they
+apply before inheritance, a sequence supplied as a replacement could gain
+inherited records afterward. Its final contents would then differ from the
+operator's assignment.
+
+The application also needs these values when it fills missing settings,
+normalizes values, or computes derived settings. ConfigKit needs a clear loading
+order that preserves both CLI precedence and the application's role in resolving
+the final configuration.
+
+## Decision
+
+ConfigKit uses this loading order:
+
+1. Combine sources within tiers and apply precedence between layers.
+2. Resolve sibling inheritance, apply typed defaults, and decode the configuration
+   into the application's types.
+3. Apply explicit CLI overrides and check them against the application schema.
+4. Run application resolution using the overridden configuration.
+5. Look up effective secret references, validate the final configuration, and
+   return it.
+
+CLI overrides are the highest-priority input to application resolution. A CLI
+sequence replaces the whole sequence; mappings combine recursively. Collection
+merge rules apply during the earlier source and inheritance steps. Inheritance
+and typed defaulting do not run again after CLI overrides.
+
+Keep track of which values were explicitly supplied and which CLI input supplied
+them. Applications continue to parse command-line arguments; ConfigKit applies
+and validates the overrides and makes their effects inspectable. Reject
+structural directives in override paths and values, so instructions such as
+inheritance relationships remain part of source processing.
+
+Application resolution keeps its existing rules for defaults and recorded
+changes under [ADR 0003](0003-preserve-presence-and-resolution-history.md).
+It receives CLI values together with their presence and source information.
+Defaults that only fill missing settings preserve explicit CLI values.
+Application normalization and derived-value calculations can still change them,
+with those changes recorded. Secret lookup and final validation use the resulting
+configuration.
+
+## Alternatives Considered
+
+- **Apply CLI overrides before inheritance.** Preserves existing ordering, but
+  later merging needs special handling to preserve CLI replacement intent while
+  still combining ordinary source contributions.
+- **Apply CLI overrides after inheritance but before typed decoding.** Allows an
+  override to fix a source value that would otherwise fail decoding, but leaves
+  typed defaulting after the operator's assignment. Completing defaulting and
+  decoding first gives CLI overrides an already resolved configuration to modify.
+- **Apply CLI overrides after application resolution.** Applies assignments after
+  the application's changes, but derived settings still reflect earlier values
+  unless resolution runs again.
+
+## Consequences
+
+CLI overrides change a configuration whose inheritance and typed defaults are
+already resolved. The application can then derive settings from the operator's
+values. The final values, source information, history, and sensitivity handling
+must remain consistent throughout loading.
+
+CLI input can no longer add or cancel inheritance relationships or bypass an
+earlier error in source assembly or inheritance. It also cannot fix a value that
+fails the earlier decoding step. Semantic validation still runs after overrides
+and application resolution. The [configuration contract](../config.md#explicit-cli-overrides)
+and [consumer guidance](../consumers/README.md) describe this behavior.

docs/adr/0019-explicit-configuration-discovery.md

@@ -0,0 +1,68 @@
+# ADR 0019: Keep Configuration Discovery Explicit and Inside Loading
+
+## Status
+
+Accepted.
+
+## Date
+
+2026-10-24
+
+## Context
+
+Applications often need a small ordered convention for choosing a main
+configuration file. Keeping that choice entirely in each application repeats
+path selection and file-loading plumbing. Moving the convention into ConfigKit
+without an explicit declaration would make ordinary loads search paths that a
+consumer did not choose, obscuring both precedence and filesystem access.
+
+ConfigKit already owns synchronous source acquisition, parsing, composition,
+decoding, validation, and inspection. A selected host file can therefore enter
+that lifecycle as the existing file source, preserving its source identity,
+resource context, and diagnostics. Optional exhaustion can use the same absent
+main lifecycle as an explicitly absent source.
+
+## Decision
+
+Consumers choose and order the main-file conventions they want to use. They may
+describe literal paths, directory filename groups, and supported directory
+presets, and may mark the complete search as required. Search descriptions are
+explicit inputs to loading; no preset or convention is activated implicitly.
+
+During synchronous loading, ConfigKit resolves the description to one real host
+file or to absence before parsing. The selected file follows the existing source
+acquisition and processing rules. A selected-file access, parse, version,
+composition, decode, or validation failure is terminal and does not resume the
+search. Optional exhaustion shares the absent-main lifecycle; required
+exhaustion reports a missing-source diagnostic. No candidate-attempt history is
+added to public metadata.
+
+This keeps convention choice with applications while moving repeated selection
+and loading plumbing into the library's established lifecycle. It preserves
+explicit control, ordinary source behavior, and complete-on-return ownership.
+
+## Alternatives Considered
+
+- **Keep all search and fallback loading in each application.** This preserves
+  consumer ownership but repeats the file-selection and load coordination that
+  ConfigKit already owns, and risks divergent handling of selected-file errors.
+- **Search conventional locations implicitly during every load.** This reduces
+  setup, but activates filesystem access and precedence the consumer did not
+  select and makes ordinary source behavior less predictable.
+- **Return candidate paths for the application to load one by one.** This keeps
+  selection outside the load lifecycle and encourages repeated complete loads,
+  potentially rerunning defaults, callbacks, and validation during fallback.
+
+## Consequences
+
+The public search description must be immutable and root-owned, with private
+engine conversion and selection. The contract documents candidate ordering,
+selection, exhaustion, context, and provenance; the API declaration documents
+the public symbols. Dynamic bases and file availability are observed when each
+load consumes the description. Applications remain responsible for selecting
+conventions and for their schema and domain requirements.
+
+The [configuration contract](../config.md) owns implemented behavior, and the
+[component overview](../internal/overview.md) describes implementation ownership.
+The completed implementation plan and remediation record are preserved in Git
+history at `0369111` under `docs/roadmap/`.

docs/consumers/README.md

@@ -1,55 +1,167 @@
 # Consumer Adoption Guide
 
-ConfigKit removes parser setup, strict decoding, presence bookkeeping, import and
-selected-overlay traversal, precedence, provenance, secret lookup, and safe inspection from
-applications. Consumers still own their configuration structs, defaults, semantic
-validation, schema-version policy, CLI parsing, runtime matching and conversion,
-resource checks, remote acquisition, and service initialization.
+ConfigKit loads configuration into your application's Go types. You provide
+those types, defaults, and application rules. ConfigKit reads and combines the
+selected inputs, checks their types, and returns values with source information.
+Your application still owns CLI parsing, resource reads, remote acquisition, and
+runtime initialization.
 
-The maintained [`examples/consumers`](../../examples/consumers) package demonstrates
-sanitized shapes using only ConfigKit and the Go standard library:
+Import `"go.maximumdirect.net/configkit"`; the package name is `configkit`.
+Start with one file, then choose the tasks your application needs:
 
-| Shape | Demonstrated fit | Application code deliberately retained |
-| --- | --- | --- |
-| Narratio-like | Fresh defaults, explicit partial imports, artifact maps, recorded inherited defaults, normalization, and source ownership | Artifact meaning and the separate `model_profile` domain field |
-| Notarius-like | Canonical object bindings, a string-backed schema version accepting string or integer YAML, strict dynamic options, and `int64` dynamic integers | Catalog selection, allowed option keys, range-checked conversion to runtime `int` |
-| WeatherReporter-like | Defaults-only loading, report maps, canonical module objects, typed option unions, explicit CLI records, and typed secret startup | Report/module compatibility, rejection of explicitly empty domain lists, CLI parsing, and startup ordering |
-| Seriatim-like | Independent strict ordered speaker and autocorrect rule files | First-match and ordered replacement algorithms; no central application configuration file |
-| Bundled file | Simple native `fs.FS` source through ordinary `Load` | Selection and lifetime of the application-owned embedded filesystem |
-| Layered catalog | Embedded defaults with an import, a mapping underlay, an independent host main file, explicit false/zero input, and source-relative resource access | Domain validation and opening/interpreting the template resource |
-| Named presets | One-load sibling inheritance, explicit false, nested destination resolution, and source/derivation inspection | Choosing and executing a preset |
+| Task | Start here |
+| --- | --- |
+| Load one file | [Happy path](#happy-path) and the [README example](../../README.md#load-a-configuration-file) |
+| Supply fixed defaults and check application rules | [Defaults and application rules](#defaults-and-application-rules) |
+| Add bundled defaults beneath application settings | [Native filesystem and layered input](#native-filesystem-and-layered-input) |
+| Select files or an overlay | [Discovery](#explicit-main-file-discovery), [import defaults](#import-defaults-and-selection-inspection), and the [overlay reference](../config.md#selected-overlays) |
+| Reuse settings or combine record lists | [Inheritance](#named-sibling-inheritance) and [identified sequences](#identified-prompt-sequences) |
+| Handle credentials | [Typed-secret reference](../config.md#typed-secret-references) and the [startup example](../../examples/consumers/consumers_test.go) |
+| Inspect sources, earlier values, or changes | [Inspect a completed load](#inspect-a-completed-load) and [diffs](#effective-configuration-diffs) |
+| Upgrade an existing consumer | [Migration guidance](#intentional-migration-changes) |
 
-The YAML under [`testdata`](../../examples/consumers/testdata) is loaded by the
-executable examples and ordinary tests. It contains no private application data,
-credentials, network calls, or dependency on a sibling checkout.
+## Choosing a loading entry point
 
-The Notarius-shaped fixtures deliberately load both `version: 4` and
-`version: "4"` into the same string-backed application field. Its version checker
-still owns the supported identifier; fractional numeric input and unsupported
-integer identifiers remain negative examples.
+- Use [`Load`](../../lifecycle.go) with one source for an ordinary configuration.
+  [`SearchConfig`](../../discovery.go) is also a source; pass it to `Load` or use
+  it as the main input to [`LoadLayered`](../../layered.go).
+- Use `LoadLayered` when several inputs should supply lower-priority defaults
+  beneath the main source. Each underlay group combines its inputs strictly.
+  Each [`Input`](../../layered.go) owns its source, filesystem, destination, and
+  import choice. The overlay filesystem context is selected independently in
+  [`LayeredOptions`](../../layered.go).
+- Load-wide rules belong to [`Options`](../../lifecycle.go) or
+  [`LayeredOptions`](../../layered.go): the application definition (including
+  version policy), import defaults, and explicit overrides. These do not turn
+  on imports or discovery by themselves. See the
+  [configuration contract](../config.md#layered-loading) and
+  [discovery contract](../config.md#configuration-discovery) for exact rules.
+
+The root [README example](../../README.md) shows the small `Load` path.
+[`layered.go`](../../examples/consumers/layered.go) demonstrates the bundled
+file and layered cases. For import-focused adoption, see the
+[prompt catalog](../../examples/consumers/prompt_catalog.go); for explicit
+discovery composed with sequences, see the
+[sequence catalog](../../examples/consumers/sequence_catalog.go).
 
 ## Happy path
 
-An application defines ordinary types and passes one explicit source. Optional
-features appear only when the application needs them:
+Define the Go configuration type, choose one source, and call `Load`. Handle a
+load error before starting the application with `result.Config`. The
+[README example](../../README.md#load-a-configuration-file) shows this complete
+minimal loading function. An explicitly missing file is an error; use `NoSource`
+when you deliberately want defaults without a main document.
+
+### Defaults and application rules
+
+Using the README's `Config` type, an application can add reusable rules:
 
 ```go
-result, err := configkit.Load[Config](configkit.File(path), configkit.Options[Config]{
-    Definition: rules,
-    Imports:    useDeclaredImports,
-    Overlay:    selectedConfigOverlay,
-    Overrides:  explicitlySetFlags,
-})
-if err != nil {
-    return err
+definition := configkit.Definition[Config]{
+    Defaults: func() Config { return Config{Enabled: true, Workers: 2} },
+    Validate: func(value *Config, validation *configkit.Validation) {
+        if value.Workers < 0 {
+            validation.Error(configkit.Keys("workers"), "must be nonnegative")
+        }
+    },
 }
-return start(result.Config)
 ```
 
-Simple consumers use neither imports nor selected overlays. A complex consumer can opt into
-both without redefining their syntax. ConfigKit overlays are configuration overlays;
-they do not select or replace an application's LLM, model, pipeline, report, or
-execution profile concepts.
+Pass this definition in `Options[Config]{Definition: definition}` when calling
+`Load`. Supplied `enabled: false` or `workers: 0` replaces those defaults.
+Use `Resolve` when a value must be derived or normalized before validation, and
+record that change with the provided helpers. The
+[callback reference](../config.md#recorded-application-resolution) compares the
+helpers; [executable examples](../../example_test.go) show full definitions.
+
+### Inspect a completed load
+
+Keep the result when you need to explain configuration. Use
+`result.Metadata().Lookup(configkit.Keys("workers"))` to inspect whether input
+supplied the value and which source or application step supplied it. Follow an
+origin's source ID with `result.Source(id)` when you need its source record.
+
+Use `Explain` for earlier values, `WriteExplanation` for a readable explanation,
+and `WriteEffective` for safe YAML describing the final saved state. These
+operations describe the completed load even if your application later changes
+`result.Config`. The [inspection reference](../config.md#layered-metadata)
+explains returned values, copies, and hidden information.
+
+Add imports, a selected overlay, or explicitly set CLI values through options
+only when needed. An overlay changes configuration; choosing an LLM, report, or
+execution profile remains application logic.
+
+## Explicit main-file discovery
+
+Applications choose the search conventions and their precedence, then pass the
+resulting `SearchConfig` source to the same `Load` or `LoadLayered` entry
+point. For example, the maintained sequence catalog puts a caller-selected
+file before a custom directory fallback while keeping its underlay and overlay
+choices independent. See
+[`sequence_catalog.go`](../../examples/consumers/sequence_catalog.go) and its
+[behavior tests](../../examples/consumers/sequence_catalog_test.go), plus the
+[working-directory executable
+example](../../examples/consumers/discovery_test.go). Together, the [discovery
+API](../../discovery.go) and [configuration discovery
+contract](../config.md#configuration-discovery) explain the order of attempted
+files, what happens when no file is found, and why a selected-file failure
+stops the search. [ADR 0019](../adr/0019-explicit-configuration-discovery.md)
+records why discovery is explicitly selected.
+
+## Import defaults and selection inspection
+
+`Options.ImportDefaults` and `LayeredOptions.ImportDefaults` apply one
+load-wide policy to enabled main, underlay, and transitive imports. Each field
+is resolved independently: a declaration's explicit value wins, then the
+application default, then the library default. `Required`, `FollowSymlinks`,
+`IncludeHidden`, and `Recursive` use nil pointers for unspecified values.
+`Pattern` applies to
+directory searches: nil leaves filenames unrestricted, while a non-nil empty
+slice selects no files. A declaration's own `pattern` replaces the application
+default. The defaults do not enable imports or change selected-overlay behavior.
+The Go fields `FollowSymlinks` and `IncludeHidden` correspond to the unchanged
+YAML keys `follow` and `hidden`.
+
+`Result.Sources`, `LoadError.Sources`, and `Resolution.Source` expose each
+declaring source's `EmptyImportSelections`. `Result.Source(id)` and
+`LoadError.Source(id)` retrieve one retained record directly when its load-local
+ID is known. These records identify the source-local declaration path, its
+authored location and selector;
+they do not include candidate names or a guessed reason for absence. Returned
+records are detached snapshots. The [configuration contract](../config.md#explicit-imports)
+owns selector applicability and exact absence semantics.
+
+## Shared source-version checks
+
+[`LoadVersionedService`](../../examples/consumers/source_version.go) demonstrates
+if-present and required modes with one `Definition.Version` rule across a mounted
+main input and an underlay. The example reads only sanitized
+`SourceInfo.VersionEvidence` fields; its executable test is in
+[`layered_test.go`](../../examples/consumers/layered_test.go). The
+[configuration contract](../config.md#shared-source-version-checks) defines
+participation, source-local lookup and diagnostics, non-main header consumption,
+main-path protection, default behavior, and evidence disclosure. Accepted
+declarations do not replace final assembled decoding or application validation.
+
+## Effective configuration diffs
+
+[`CompareFiles`](../../examples/consumers/diff.go) loads two caller-selected files
+with one application definition, handles each load error, calls `configkit.Diff`,
+and presents the safe records through consumer-owned `FormatDifferences`.
+[`CompareRolloutOverlay`](../../examples/consumers/diff.go) loads the same base
+once without an overlay and once with the selected overlay, so omitted lower
+priority values remain present. Its resolver records a derived endpoint URL after
+overlay application, and its nested typed secret reference is classified before
+the resulting records are presented.
+
+The maintained [behavior tests and executable
+examples](../../examples/consumers/diff_test.go) use temporary files and
+disposable secret values. Presenters should use `ValueSnapshot.Present` for
+absence, record membership for change, and `HiddenChanged` for a withheld
+change indicator. Do not parse the redaction marker or add separately rendered
+full contexts that lack combined sensitivity. The [configuration
+contract](../config.md#effective-configuration-diffs) owns shared equality,
+granularity, and disclosure semantics.
 
 ## Named sibling inheritance
 
@@ -88,6 +200,79 @@ and may fail independently of the completed configuration load. The
 [configuration contract](../config.md#source-resource-contexts) owns exact
 lifetime and precedence rules.
 
+[`LoadPromptBundle`](../../examples/consumers/layered.go) is the ordinary-root
+counterpart: its entry opts into imports through `Load`, imports metadata at the
+root, and places a prompt beneath `prompts` using YAML. The executable example
+and behavior test are in
+[`layered_test.go`](../../examples/consumers/layered_test.go).
+
+## Input destinations and mounted collections
+
+Main and underlay inputs use the same destination field. An import without a
+`destination` inherits its declaring document's effective destination; an
+explicit sequence of key strings appends a relative suffix. Nested imports
+append to their immediate parent's effective destination, while filesystem
+paths remain relative to the declaring file. Destinations are application
+mapping paths, independent of filesystem context. The configuration contract
+owns the complete behavior and validation rules.
+
+The small [`Example_inputDestination`](../../examples/consumers/destinations_test.go)
+mounts one mapping source beneath literal collection/prompt keys and loads a
+second input without a destination to show that root placement remains the
+default. Consumers pass paths, not filenames or namespace strings for ConfigKit
+to interpret.
+
+[`LoadCollectionBundle`](../../examples/consumers/destinations.go) assembles an
+embedded collection manifest mounted beneath a literal collection path. The
+entry's YAML places nested metadata imports at the collection root and prompt
+and profile peers beneath their own keys. A higher-priority input changes only
+one prompt's ordinary `version` field. The main document alone supplies the
+application schema version. A prompt's local `extends` relationship resolves
+after all tiers, so `custom` inherits the final `brief` content and fields while
+retaining its own profile selection.
+
+The resolver follows each effective `content_file` origin to its declaring
+source context. This also works for `custom`'s inherited resource. The
+application-owned [`ReadCollectionPromptContent`](../../examples/consumers/destinations.go)
+demonstrates the same lookup after loading; ConfigKit does not open or interpret
+the resource. [`destinations_test.go`](../../examples/consumers/destinations_test.go)
+checks source destinations and authored coordinates, presence, inherited values,
+relative resources, and strict peer conflicts. The
+[configuration contract](../config.md#input-destinations) owns shared placement,
+import, source-location, and ownership behavior.
+
+## Identified prompt sequences
+
+[`LoadPromptCatalog`](../../examples/consumers/prompt_catalog.go) shows the
+smaller import-focused adoption path: a registered `prompts.id` identity,
+directory and glob selection, a helper import that supplies an item's ID, and
+resource lookup through the effective source context. Its executable examples
+and tests are in
+[`prompt_catalog_test.go`](../../examples/consumers/prompt_catalog_test.go), with
+complete [catalog](../../examples/consumers/testdata/prompt-catalog/config.yml)
+and [required-file](../../examples/consumers/testdata/prompt-catalog/simple.yml)
+fixtures.
+
+[`LoadSequenceCatalog`](../../examples/consumers/sequence_catalog.go) integrates
+an underlay declaration, imported main fragments, identified-record inheritance,
+selected overlay `append`, `upsert`, and `replace`, a typed CLI override, and
+recorded application resolution. Its tests and runnable example demonstrate
+stable output order, whole-record upsert, provenance/history inspection,
+resource lookup for inherited records, and secret-safe explanation in
+[`sequence_catalog_test.go`](../../examples/consumers/sequence_catalog_test.go).
+[`LoadNamespacedMapCatalog`](../../examples/consumers/sequence_catalog.go) adds
+an exact root registration and a wildcard namespace registration, showing that
+each concrete sequence has an independent identity scope. The same tests show
+that a YAML identity declaration without an application registration does not
+create final-result identity enforcement.
+
+The examples keep prompt meaning and domain checks in the consuming application.
+The [configuration contract](../config.md#strict-document-composition) owns
+declaration, identity, operation, ownership, and final-validation semantics;
+[sibling inheritance](../config.md#sibling-inheritance) defines record
+relationships, and the [CLI contract](../config.md#explicit-cli-overrides) owns
+override ordering.
+
 Known module catalogs should use canonical object entries with a module identifier
 and typed options. A small union struct is sufficient when the available option
 fields are known; validation selects which fields apply to each module. Runtime-
@@ -99,14 +284,13 @@ conversion API.
 ## Source-aware application path policy
 
 [`LoadNotariusPaths`](../../examples/consumers/consumers.go) is the maintained
-path-bearing example. Its application resolver uses `Resolution.InputInfo` and
+path-bearing example. Its application resolver uses `Resolution.EntryInfo` and
 `Resolution.Source` before normalizing: relative CLI input uses an explicitly
 supplied invocation directory, retained defaults use the canonical main source,
 and a file-authored scalar uses its one declaring source. Absolute paths remain
-unchanged. Its executable test covers the matching effective YAML and explanation
-history, source-file ownership, and a symlink opened through an alias; canonical
-target-file directories, rather than the alias directory or process working
-directory, are the selected bases.
+unchanged. Its executable test checks the resulting YAML and explanation
+history. When the configuration filename is a symlink, this example uses the
+actual target file's directory as the base for file-authored paths.
 
 The selected example policy leaves a relative value unchanged and emits a warning
 when a CLI base is absent or file provenance is missing or composite. That is an
@@ -116,7 +300,15 @@ existence checks nor confinement checks.
 
 ## Intentional migration changes
 
-The examples preserve domain meaning while adopting one configuration convention:
+When upgrading, start with the changes relevant to your dependency and inputs:
+
+1. Update the module requirement and Go imports together as described below.
+2. Replace old public names using the old/new table.
+3. Update any layer or diagnostic-code strings stored or compared by your code.
+4. Review YAML and startup changes that apply to your application, then rebuild
+   and run its configuration tests.
+
+The maintained examples illustrate these configuration changes:
 
 - Explicit empty strings, lists, zeroes, false values, and nulls remain intentional.
   ConfigKit accepts an empty list structurally; WeatherReporter-shaped validation
@@ -136,10 +328,70 @@ The examples preserve domain meaning while adopting one configuration convention
   parsers translate only explicitly set configuration flags into `Override` records.
   Separate invocation state remains outside configuration.
 - Credential fields migrate to environment-name `Secret` references. Applications
-  explicitly call `LoadSecretsDir` before `Load` when they choose file bootstrap;
+  explicitly call `LoadSecretsIntoEnvironment` before `Load` when they choose
+  file bootstrap;
   blocked empty variables remain blocked, and ordinary `Load` never changes the
   process environment.
 
+### Vanity module path migration
+
+ConfigKit's module identifier changed from
+`gitea.maximumdirect.net/eric/ConfigKit` to `go.maximumdirect.net/configkit` before
+v1.0.0. Update the dependency requirement in your application's `go.mod` and its
+Go imports together, selecting a revision or release that declares the new module
+path. The package name remains `configkit`; the configuration model and public
+symbol names are unchanged by this identity migration.
+
+Go treats the old and new import paths as different packages, with different
+named types. For example, if another library returns a ConfigKit `Path` or
+`Secret` using the old import, your application cannot use it as the new
+package's type just by changing a module requirement. Coordinate migration
+with dependencies that pass ConfigKit values to or from your application. The
+maintained examples use the new path, but other repositories must manage their
+own migrations.
+
+Historical tags keep their original module declarations and contents. Older
+releases such as v0.10.2 still use the old path and cannot be installed under the
+vanity identifier simply because discovery can find their repository. A matching
+migrated revision is needed; no old-path compatibility module is supplied here.
+
+### Pre-v1 public API cleanup
+
+The pre-v1 API cleanup replaces these names outright; it does not retain
+compatibility aliases:
+
+| Previous API | Current API |
+| --- | --- |
+| `Resolution.InputInfo(path)` | `Resolution.EntryInfo(path)` |
+| `Definition.Secret` | `Definition.Sensitive` |
+| `SourceVersionModeDefault` | `SourceVersionModeMainOnly` |
+| `SourceVersionCheck` | `SourceVersionEvidence` |
+| `SourceInfo.VersionCheck` | `SourceInfo.VersionEvidence` |
+| `ImportSelection` | `EmptyImportSelection` |
+| `SourceInfo.ImportSelections` | `SourceInfo.EmptyImportSelections` |
+| `SourceInfo.DestinationUnresolved` | `SourceInfo.DestinationIsFallback` |
+| `ImportDefaults.Follow` / `.Hidden` | `FollowSymlinks` / `IncludeHidden` |
+| `Paths(paths...)` | `SearchPaths(paths...)` |
+| `LoadSecretsDir(directory)` | `LoadSecretsIntoEnvironment(directory)` |
+| `LayerBase` | `LayerMain` |
+| `CodeExplainLimitExceeded` | `CodeHistoryLimitExceeded` |
+| `CodeResolveInvalidKind` / `CodeOptionsUnavailable` | Removed; no replacement |
+| `ImportSelection.Outcome`, `ImportSelectionOutcome`, `ImportSelectionNone` | Removed; empty-selection records no longer carry an outcome |
+| `Resolution.Record(path, ChangeDerivedDefault, reason, deps...)` | `Resolution.RecordDerivedDefault(path, reason, deps...)` |
+| `Resolution.Record(path, ChangeNormalization, reason, deps...)` | `Resolution.RecordNormalization(path, reason, deps...)` |
+| Enumerating `Result.Sources()` / `LoadError.Sources()` to find one ID | `Result.Source(id)` / `LoadError.Source(id)` |
+| Provenance string `"base"` | `"main"` |
+| History diagnostic string `"explain.limit_exceeded"` | `"history.limit_exceeded"` |
+
+The YAML import keys `follow` and `hidden`, the `configkit:"secret"` tag, and
+typed `Secret` references are unchanged. If your application compares or
+stores layer names or diagnostic codes as strings, update those strings
+alongside Go references. This repository guidance does not claim that
+downstream applications have migrated and does not select a release version
+for this breaking pre-v1 change. `ChangeKind` and its inspection constants
+remain; use `Default` and `Normalize` when the helper should both assign and
+record a value.
+
 ### Selected-overlay migration
 
 To adopt the current selected-overlay API, rename `Options.Profile`,
@@ -150,10 +402,40 @@ The [configuration contract](../config.md#selected-overlays) is the canonical
 behavioral reference. Application-owned profile concepts, such as `model_profile`,
 are unchanged, and any CLI flag rename remains the application's decision.
 
-These examples are migration evidence, not completed changes to Narratio, Notarius,
-WeatherReporter, or Seriatim. Updating those repositories, their deployed YAML, CLI
-wiring, runtime catalogs, and operational documentation remains separate downstream
-work.
+### Background on the examples
+
+These examples demonstrate migration shapes. They do not claim that Narratio,
+Notarius, WeatherReporter, or Seriatim has been migrated. Updating those
+repositories, their deployed YAML, CLI wiring, runtime catalogs, and
+operational documentation remains separate downstream work.
+
+## Example background
+
+The maintained [`examples/consumers`](../../examples/consumers) package demonstrates
+sanitized shapes using only ConfigKit and the Go standard library:
+
+| Shape | Demonstrated fit | Application code deliberately retained |
+| --- | --- | --- |
+| Artifact defaults and normalization (Narratio-like) | Fresh defaults, explicit partial imports, artifact maps, recorded inherited defaults, normalization, and source ownership | Artifact meaning and the separate `model_profile` domain field |
+| Versions and dynamic options (Notarius-like) | Canonical object bindings, a string-backed schema version accepting string or integer YAML, strict dynamic options, and `int64` dynamic integers | Catalog selection, allowed option keys, range-checked conversion to runtime `int` |
+| Module validation and credential startup (WeatherReporter-like) | Defaults-only loading, report maps, canonical module objects, typed option unions, explicit CLI records, and typed secret startup | Report/module compatibility, rejection of explicitly empty domain lists, CLI parsing, and startup ordering |
+| Independent ordered rule files (Seriatim-like) | Independent strict ordered speaker and autocorrect rule files | First-match and ordered replacement algorithms; no central application configuration file |
+| Bundled file | Simple native `fs.FS` source through ordinary `Load` | Selection and lifetime of the application-owned embedded filesystem |
+| Layered catalog | Embedded defaults with an import, a mapping underlay, an independent host main file, explicit false/zero input, and source-relative resource access | Domain validation and opening/interpreting the template resource |
+| Mounted collections | Entry-declared relative destinations, nested metadata/prompt/profile imports, local inheritance, and a version-only higher-tier override | Collection IDs, profile meaning, and opening/interpreting prompt resources |
+| Named presets | One-load sibling inheritance, explicit false, nested destination resolution, and source/derivation inspection | Choosing and executing a preset |
+| Effective configuration diff | Same-type frozen effective comparisons for two selected files or base-versus-overlay impact | Source/options selection and consumer-owned safe presentation |
+| Shared source-version checks | One `Definition.Version` policy for accepted declarations across participating source documents, with optional or required declarations and sanitized evidence | Choosing which declarations the application accepts; final assembled schema and domain validation |
+| Sequence catalogs | Declared collection operations, record inheritance, typed CLI and resolution, inspection, exact and wildcard application registrations | Catalog meaning and final domain validation |
+
+The YAML under [`testdata`](../../examples/consumers/testdata) is loaded by the
+executable examples and ordinary tests. It contains no private application data,
+credentials, network calls, or dependency on a sibling checkout.
+
+The Notarius-shaped fixtures deliberately load both `version: 4` and
+`version: "4"` into the same string-backed application field. Its version checker
+still owns the supported identifier; fractional numeric input and unsupported
+integer identifiers remain negative examples.
 
 ## Maintained API examples
 
@@ -165,9 +447,11 @@ focused behavioral owner:
 | `Load`, `NoSource`, validation, versions, resolution, `SecretEnv`, overrides, and explanation | Executable examples in [`example_test.go`](../../example_test.go) |
 | Source/import/selected-overlay pipeline rules and artifact defaults | Narratio-shaped executable example and fixture |
 | Canonical module objects and dynamic option handling | WeatherReporter- and Notarius-shaped examples and migration tests |
-| `LoadSecretsDir`, bootstrap reporting, typed lookup, CLI explanation | `Example_weatherStartup` |
+| `LoadSecretsIntoEnvironment`, bootstrap reporting, typed lookup, CLI explanation | `Example_weatherStartup` |
 | Native filesystem, grouped underlays, programmatic mapping, retained resource context | `Example_nativeFilesystem`, `Example_layeredCatalog`, and their focused consumer tests |
+| Literal input destinations, root-default compatibility, and mounted peer collections | `Example_inputDestination`, `LoadCollectionBundle`, and `destinations_test.go` |
 | Named sibling inheritance, presence, and derivation | `Example_inheritedPresets` and `TestPresetCatalogOneLoadAndDerivation` |
+| Effective configuration diffs and consumer-owned presentation | `ExampleDiff`, `ExampleCompareFiles`, and `ExampleCompareRolloutOverlay` |
 | Results, metadata, diagnostics, effective output, and writer failures | Focused root-package load, provenance, rendering, and explanation tests |
 
 The package-level import-boundary test covers the consumer examples too: supported

docs/development.md

@@ -39,9 +39,11 @@ public behavior.
 | Task | Read |
 | --- | --- |
 | Repository orientation or component responsibility | [Component overview](internal/overview.md) |
+| Input destinations | [Configuration contract](config.md#input-destinations), [ADR 0011](adr/0011-input-destinations.md), and the destination tests below |
+| Shared source-version checks | [Configuration contract](config.md#shared-source-version-checks), [ADR 0013](adr/0013-shared-source-version-checks.md), and the version/source-version tests below |
 | Documentation changes | The owning document |
 | Licensing, dependencies, attribution, or release-document changes | [Project grant](../COPYRIGHT) and [attribution](oss/attribution.md); release changes also follow the release procedure |
-| Architecture decisions or future work | [Deferred scope](roadmap/deferred.md) and relevant ADRs listed below |
+| Architecture decisions or future work | [Future features](roadmap/future.md) and relevant ADRs listed below |
 | Code and test changes | The owning contract and tests from the map below |
 | Examples or copyable assets | The owning implemented contract and [consumer adoption guide](consumers/README.md) |
 | Release preparation | [Release procedure](release.md) |
@@ -49,11 +51,19 @@ public behavior.
 Accepted decisions:
 
 - [Separate composition and overlay](adr/0001-separate-composition-and-overlay.md)
+- [Check source versions with one shared policy](adr/0013-shared-source-version-checks.md)
 - [Own YAML semantics behind a private parser boundary](adr/0002-own-yaml-semantics.md)
 - [Preserve presence and record application resolution](adr/0003-preserve-presence-and-resolution-history.md)
 - [Secret references and explicit bootstrap](adr/0004-secret-references-and-explicit-bootstrap.md)
 - [Explicit overrides and safe explanation](adr/0005-explicit-overrides-and-safe-explanation.md)
 - [Keep the public facade root-owned](adr/0006-public-facade.md)
+- [Compare frozen effective configuration snapshots](adr/0010-effective-configuration-diff.md)
+- [Place inputs at literal application mapping paths](adr/0011-input-destinations.md)
+- [Share dependency-ready ordering](adr/0015-shared-dependency-ready-ordering.md)
+- [Separate import selection controls](adr/0016-independent-import-controls.md)
+- [Define identity and merge rules for each collection](adr/0017-collection-sequence-policy.md)
+- [Apply CLI overrides after inheritance and decoding](adr/0018-cli-after-structural-resolution.md)
+- [Keep main-file discovery explicit and composable](adr/0019-explicit-configuration-discovery.md)
 
 For cross-cutting changes, follow every applicable row. Completed implementation
 and remediation plans are preserved in Git history at `cb5b435`; use current
@@ -64,8 +74,9 @@ git show cb5b435:docs/roadmap/remediation.md
 ```
 
 Release-candidate, publication, and verification work follows the operational
-[release procedure](release.md). Its single publication command validates the
-committed candidate and publishes only the intended refs.
+[release procedure](release.md). Its module-selected ReleaseKit `publish`
+invocation validates the committed candidate and publishes only the intended
+tag; those release checks remain distinct from the everyday development check.
 
 The completed string-and-integer schema-version implementation and remediation
 records are preserved in Git history at `244104f`. The
@@ -93,9 +104,131 @@ preserved in Git history at `73ce6e9` under `docs/roadmap/`. Current overlay
 behavior belongs to the [configuration contract](config.md#selected-overlays),
 and release operations belong to the [release procedure](release.md).
 
-Install Go 1.25.0 or a supported patched/newer Go toolchain. Acquire declared
-dependencies explicitly before entering an offline development or validation
-environment:
+The completed ReleaseKit adoption, startup performance request and experiments,
+benchmark evidence, performance audit, implementation plan, and remediation
+record are preserved in Git history at `8e91a2b` under `docs/roadmap/`. For example:
+
+```sh
+git show 8e91a2b:docs/roadmap/startup-benchmark.md
+```
+
+Remaining optimization candidates belong to
+[future performance experiments](roadmap/future.md#5-performance-experiments).
+
+The completed effective-configuration diff roadmap, implementation plan, and
+resolved review findings are preserved in Git history at `1c2610c` under
+`docs/roadmap/`. The
+[configuration contract](config.md#effective-configuration-diffs) owns current
+comparison and disclosure behavior, and
+[ADR 0010](adr/0010-effective-configuration-diff.md) records the decision.
+
+The completed input-destination, relative-import-destination, and shared
+source-version roadmaps, associated consumer request, implementation plan, and
+resolved review findings are preserved in Git history at `e4270c9` under
+`docs/roadmap/`. For example:
+
+```sh
+git show e4270c9:docs/roadmap/implementation.md
+git show e4270c9:docs/roadmap/remediation.md
+```
+
+Current behavior belongs to the configuration contract's
+[input destinations](config.md#input-destinations),
+[imports](config.md#explicit-imports), and
+[shared source-version checks](config.md#shared-source-version-checks) sections.
+Explicit sequence-item placement, collection operations, identity registration,
+and final registered-identity validation are owned by the
+[strict composition](config.md#strict-document-composition) section;
+[imports](config.md#explicit-imports) owns acquisition and scheduling. The
+[maintained sequence catalog](consumers/README.md#identified-prompt-sequences)
+shows the consumer boundary, and [ADR 0017](adr/0017-collection-sequence-policy.md)
+records the collection decision.
+
+The completed sequence-composition roadmap, implementation plan, and resolved
+remediation record are preserved in Git history at `008d2ba` under
+`docs/roadmap/`. For example:
+
+```sh
+git show 008d2ba:docs/roadmap/sequence-composition.md
+git show 008d2ba:docs/roadmap/implementation.md
+git show 008d2ba:docs/roadmap/remediation.md
+```
+
+The completed import-discovery roadmap, implementation plan, and resolved
+remediation record are preserved in Git history at `5747ec4` under
+`docs/roadmap/`. For example:
+
+```sh
+git show 5747ec4:docs/roadmap/imports.md
+git show 5747ec4:docs/roadmap/implementation.md
+git show 5747ec4:docs/roadmap/remediation.md
+```
+
+The subsequent import-integration audit and completed remediation record are
+preserved at `6903c9e:docs/roadmap/remediation.md`; retrieve them with
+`git show 6903c9e:docs/roadmap/remediation.md`.
+
+The completed sequence-identity/collection-policy roadmap and implementation
+plan are preserved in Git history at `d0a605a`:
+
+```sh
+git show d0a605a:docs/roadmap/sequences.md
+git show d0a605a:docs/roadmap/implementation.md
+```
+
+Current behavior belongs to the configuration contract's
+[strict composition](config.md#strict-document-composition),
+[sibling inheritance](config.md#sibling-inheritance), and
+[CLI overrides](config.md#explicit-cli-overrides) sections.
+The completed remediation record, including the algorithm-audit findings, is
+preserved at `ea46001:docs/roadmap/remediation.md`.
+
+The completed configuration-discovery roadmap, implementation plan, and
+remediation record are preserved in Git history at `0369111`, for example
+`git show 0369111:docs/roadmap/remediation.md`. Current behavior belongs to
+[configuration discovery](config.md#configuration-discovery); the public
+[discovery declarations](../discovery.go) own the Go API.
+
+The completed consolidation proposal, implementation plan, and resolved audit
+findings are preserved in Git history at `34cbc0d` under `docs/roadmap/`. For
+example:
+
+```sh
+git show 34cbc0d:docs/roadmap/implementation.md
+git show 34cbc0d:docs/roadmap/remediation.md
+```
+
+Potential enhancements are tracked in [future features](roadmap/future.md).
+The completed audit-remediation, internal-boundary simplification, shared-history,
+and public API cleanup roadmaps, reviews, and resolved findings are preserved at
+`68400ff` under `docs/roadmap/`. For example:
+
+```sh
+git show 68400ff:docs/roadmap/api.md
+git show 68400ff:docs/roadmap/remediation.md
+```
+
+Their earlier completed implementation plans are preserved at
+`bb5540b:docs/roadmap/implementation.md` (audit remediation),
+`f6d54a0:docs/roadmap/implementation.md` (internal-boundary simplification), and
+`07e4ae5:docs/roadmap/implementation.md` (shared history). The plan at
+`68400ff:docs/roadmap/implementation.md` records the public API cleanup.
+Current behavior and migration information belong to the
+[configuration contract](config.md), public declaration comments, and
+[consumer guide](consumers/README.md#pre-v1-public-api-cleanup).
+
+The consolidated audit, including
+findings, evidence, and settled scope decisions, is preserved at
+`453da68:docs/roadmap/audit.md`; the original nine reports are preserved at
+`ecd5d5d` under `docs/roadmap/`. Retrieve the consolidated record with:
+
+```sh
+git show 453da68:docs/roadmap/audit.md
+```
+
+Install the Go version required by `go.mod` or a compatible newer toolchain.
+Acquire declared dependencies explicitly before entering an offline
+development or validation environment:
 
 ```sh
 go mod download
@@ -125,11 +258,10 @@ Use focused checks while iterating, with validation proportionate to the change
 under the testing policy. Documentation-only work normally needs the local-link
 check below and whitespace review; behavior-bearing examples and commands also
 need execution. Use `go test -race ./...` for ownership or concurrency changes.
-The [publication command](release.md#4-publish-the-committed-candidate) invokes
-the release checker once. It performs one minimum-toolchain offline race-suite
-run, one full vet pass, and Linux cross-builds using readonly module mode.
-It already covers examples, links, and package boundaries; do not additionally
-run the everyday checker just to repeat those checks. CI never gates a release.
+The [release procedure](release.md#4-publish-the-committed-candidate) performs
+its selected validation through one `publish` invocation. The everyday checker
+remains a development gate and is not a separate release prerequisite. CI never
+gates a release.
 
 ## Task-to-test map
 
@@ -140,22 +272,29 @@ code changes. Use the component overview to find the corresponding implementatio
 | Task | Behavioral test owners | Focused command |
 | --- | --- | --- |
 | YAML syntax, diagnostics, parser limits | [Adapter tests](../internal/yaml/parse_test.go), [source translation](../internal/engine/parse_test.go) | `go test ./internal/yaml` and `go test ./internal/engine -run '^TestParseSource'` |
-| File/reader access, imports, globs, containment | [Sources](../internal/engine/source_test.go), [FIFO](../internal/engine/source_fifo_test.go), [imports](../internal/engine/imports_test.go), [globs](../internal/engine/glob_test.go) | `go test ./internal/engine -run 'Source\|Import\|Glob\|Filesystem\|Nonregular\|RegularFile'` |
+| File/reader access, imports, globs, containment | [Import internals](internal/imports.md), [source acquisition](../internal/engine/source_test.go), [FIFO](../internal/engine/source_fifo_test.go), [import traversal](../internal/engine/imports_test.go), [import evidence](../internal/engine/import_evidence_test.go), [relative destinations](../internal/engine/destination_import_test.go), [globs](../internal/engine/glob_test.go) | `go test ./internal/engine -run 'Source\|Import\|Glob\|Filesystem\|Nonregular\|RegularFile'` |
+| Explicit main-file discovery and absent-input loading | [Candidate selection](../internal/engine/discovery_test.go), [load integration](../internal/engine/discovery_load_test.go), [public facade](../facade_discovery_test.go), and maintained [catalog](../examples/consumers/sequence_catalog_test.go) and [preset](../examples/consumers/discovery_test.go) examples | `go test ./internal/engine -run 'Discovery\|Search'`, `go test . -run 'Search'`, and `go test ./examples/consumers -run 'WorkingDirectoryPreset\|SequenceCatalog'` |
+| Import defaults, empty-selection evidence, and dependency-ready ordering | [Defaults and facade evidence](../facade_import_defaults_test.go), [engine import evidence](../internal/engine/import_evidence_test.go), [scheduler](../internal/engine/dependency_order_test.go), [scheduling integrations](../internal/engine/imports_test.go) | `go test ./internal/engine -run 'Import\|ScheduleDependencies\|Inheritance'`, `go test . -run 'ImportDefaults\|FacadeImport'`, and `go test ./examples/consumers` |
 | Native filesystem and mapping sources | [Native acquisition](../internal/engine/native_filesystem_test.go), [filesystem facade](../facade_filesystem_test.go), [mapping facade](../facade_mapping_test.go) | `go test ./internal/engine -run 'NativeFilesystem'` and `go test . -run 'TestFacade'` |
 | Composition, selected overlays, CLI precedence | [Composition](../internal/engine/compose_test.go), [overlay](../internal/engine/overlay_test.go), [selected overlays](../internal/engine/selected_overlay_test.go), [overrides](../internal/engine/override_test.go) | `go test ./internal/engine -run 'Compose\|Overlay\|Override'` |
-| Sibling inheritance, provenance, history, sensitivity | [Expansion](../internal/engine/inheritance_test.go), [destination scopes](../internal/engine/inheritance_walk_test.go), [origins](../internal/engine/inheritance_origin_test.go), [history](../internal/engine/inheritance_history_test.go), [secrets](../internal/engine/inheritance_secret_test.go), [public loading](../facade_inheritance_test.go) | `go test ./internal/engine -run 'Inheritance\|Inherited'` and `go test . -run '^TestFacadeInheritance\|^TestFacadeInheritedSecrets'` |
+| Sequence identity, declarations, and operations | [Identity](../internal/engine/sequence_identity_test.go), [registrations](../internal/engine/sequence_registration_test.go), [declarations](../internal/engine/sequence_declaration_test.go), [combination](../internal/engine/sequence_combine_test.go), [final facade validation](../facade_final_sequence_identity_test.go), and [consumer catalog](../examples/consumers/sequence_catalog_test.go) | `go test ./internal/engine -run 'Sequence\|Collection'`, `go test . -run 'SequenceIdentity\|SequenceRegistration'`, and `go test ./examples/consumers` |
+| Sibling inheritance, provenance, history, sensitivity | [Implementation flow](internal/overview.md#implementation-flow), [expansion](../internal/engine/inheritance_test.go), [destination scopes](../internal/engine/inheritance_walk_test.go), [origins](../internal/engine/inheritance_origin_test.go), [history](../internal/engine/inheritance_history_test.go), [secrets](../internal/engine/inheritance_secret_test.go), [public loading](../facade_inheritance_test.go) | `go test ./internal/engine -run 'Inheritance\|Inherited'` and `go test . -run '^TestFacadeInheritance\|^TestFacadeInheritedSecrets'` |
 | Layered loading and source equivalence | [Grouped lifecycle](../internal/engine/load_request_test.go), [layered facade](../facade_layered_test.go), [equivalence](../facade_equivalence_test.go) | `go test ./internal/engine -run '^TestGrouped'`, `go test . -run '^TestFacadeLayered'`, and `go test . -run '^TestEquivalentSourceForms'` |
-| Schema, defaults, projection, cloning | [Schema](../internal/engine/schema_test.go), [decoding](../internal/engine/decode_test.go), [projection](../internal/engine/projection_test.go) | `go test ./internal/engine -run 'Schema\|Decode\|Projection\|Clone\|Inline\|CompareDocument'` |
+| Input and relative-import destinations, mounted sources, and source ownership | [Destination engine tests](../internal/engine/destination_test.go), [tier tests](../internal/engine/destination_tiers_test.go), [import traversal and version tests](../internal/engine/destination_import_test.go), [accounting tests](../internal/engine/destination_accounting_test.go), [lifecycle inspection tests](../internal/engine/destination_import_lifecycle_test.go), [public source/error tests](../facade_destination_test.go), [resource contexts](../facade_resource_context_test.go), and [consumer examples](../examples/consumers/destinations_test.go) | `go test ./internal/engine -run 'Destination\|Import\|Glob\|Mounted'`, `go test . -run 'Destination\|Import\|SourceContext\|FacadeMounted'`, and `go test ./examples/consumers` |
+| Shared source-version modes and evidence | [Engine source-version tests](../internal/engine/source_version_test.go), [public facade tests](../facade_source_version_mode_test.go), and [consumer example tests](../examples/consumers/layered_test.go) | `go test ./internal/engine -run 'SourceVersion'`, `go test . -run 'SourceVersion'`, and `go test ./examples/consumers` |
+| Schema, defaults, projection, cloning | [Implementation flow](internal/overview.md#implementation-flow), [schema](../internal/engine/schema_test.go), [decoding](../internal/engine/decode_test.go), [projection and typed cloning](../internal/engine/projection_test.go) | `go test ./internal/engine -run 'Schema\|Decode\|Projection\|Clone\|Inline\|CompareDocument'` |
 | Lifecycle, resolution, validation, callback ownership | [Loading](../internal/engine/load_test.go), [resolution](../internal/engine/resolution_test.go), [validation](../internal/engine/validation_test.go), [ownership](../internal/engine/callback_ownership_test.go), [independence](../internal/engine/independence_test.go) | `go test ./internal/engine -run 'Load\|Resolution\|Validation\|Validator\|Hook\|Callback\|Parallel'` |
 | Paths, metadata, provenance | [Paths](../internal/engine/path_test.go), [metadata](../internal/engine/metadata_test.go), [provenance](../internal/engine/provenance_test.go) | `go test ./internal/engine -run 'Path\|Metadata\|Provenance\|Queries'` |
 | Passive resource contexts | [Engine contexts](../internal/engine/resource_context_test.go), [public contexts](../facade_resource_context_test.go) | `go test ./internal/engine -run 'Resource'` and `go test . -run 'SourceContext'` |
 | Secrets, bootstrap, redaction, explanation | [References](../internal/engine/secret_reference_test.go), [bootstrap](../internal/engine/secrets_test.go), [rendering](../internal/engine/render_test.go), [explanation](../internal/engine/explain_test.go) | `go test ./internal/engine -run 'Secret\|Bootstrap\|Effective\|Explain\|Explanation\|History\|Sensitivity'` |
-| Consumer examples and migration fixtures | [Consumer tests](../examples/consumers/consumers_test.go), [native and layered examples](../examples/consumers/layered_test.go), [API examples](../example_test.go) | `go test ./examples/consumers` and `go test . -run '^Example'` |
+| Effective configuration diff | [Engine comparison and masking tests](../internal/engine/diff_test.go), [engine operation tests](../internal/engine/diff_operation_test.go), [root facade tests](../facade_diff_test.go), and [consumer examples](../examples/consumers/diff_test.go) | `go test ./internal/engine -run 'Diff\|Explain\|History\|Secret\|Independent'`, `go test . -run 'Diff\|FacadeInspection\|PublicFacadeBoundary\|DependencyImportBoundary'`, `go test ./examples/consumers`, and `go test . -run '^ExampleDiff$'` |
+| Consumer examples and migration fixtures | [Consumer tests](../examples/consumers/consumers_test.go), [native, layered, and ordinary relative-import examples](../examples/consumers/layered_test.go), [mounted collection examples](../examples/consumers/destinations_test.go), [API examples](../example_test.go) | `go test ./examples/consumers` and `go test . -run '^Example'` |
 | Assembly and layered scaling evidence | [Assembly benchmarks](../internal/engine/assembly_bench_test.go), [layered benchmarks](../internal/engine/underlay_bench_test.go) | `go test ./internal/engine -run '^$' -bench '^BenchmarkUnderlay' -benchmem`; repeat with `^BenchmarkCompose` and `^BenchmarkOverlay` |
+| Identified-sequence scaling evidence | [Mixed-upsert benchmark](../internal/engine/sequence_combine_bench_test.go) | `go test ./internal/engine -run '^$' -bench '^BenchmarkSequenceMixedUpsert$' -benchmem` |
 | Inheritance scaling evidence | [Expansion benchmarks](../internal/engine/inheritance_bench_test.go) | `go test ./internal/engine -run '^$' -bench '^BenchmarkInheritance' -benchmem` |
 | Documentation links and dependency isolation | [Link checks](../documentation_test.go), [import boundary](../import_boundary_test.go), [public boundary](../public_boundary_test.go) | `go test . -run 'TestLocalDocumentationLinks\|TestDependencyImportBoundary\|TestPublicFacadeBoundary'` |
-| Development and release checker behavior | [Shell regression](../release_check_test.go) | `go test . -run 'TestCheckScripts\|TestDevelopmentCheck'` |
-| Guarded release publication and recovery | [Publication regression](../release_publish_test.go) | `go test . -run '^TestReleasePublication'` |
+| Development check behavior | [Development checker test](../development_check_test.go) | `go test . -run '^TestDevelopmentCheckHandlesFilenamesAndStopsOnFailure$'` |
+| Release profile wiring | [Release profile test](../releasekit_profile_test.go) | `go test . -run '^TestReleaseKitProfile$'` |
 
 ## Fuzz validation
 

docs/internal/imports.md

@@ -0,0 +1,125 @@
+# Import Discovery and Scheduling Internals
+
+The [configuration contract](../config.md#explicit-imports) owns selector syntax,
+defaults, requiredness, placement, inspection evidence, and observable ordering.
+This note records implementation flow and private identities for maintainers.
+
+## Discovery and acquisition
+
+Each source's root directive is parsed into presence-aware declarations and
+resolved against load-wide defaults. `acquisition.go` owns shared acquisition
+policy, load-wide accounting, and tier-scoped repetition/namespace state;
+`import_acquisition.go` owns reading candidate bytes, declaration traversal,
+and import admission. Candidate
+selection in `import_selection.go` preserves a normalized
+namespace path separately from canonical access identity: overlapping roots
+coalesce the same candidate spelling in that namespace, while aliases reached
+through distinct spellings retain separate inclusion routes for admission.
+Directory searches walk each distinct normalized root once, apply all filename
+patterns to discovered names, and form a set union of matching candidates across
+overlapping roots. Exclusions are applied as set difference after discovery and
+candidate normalization. They do not suppress discovery or resource errors.
+
+Directory traversal tracks canonical directories on the active traversal path.
+It adds an identity when descending and removes it when the frame is popped, so
+only a back-edge to an active directory is a traversal cycle; a later alias is
+not mistaken for one. This is separate from import dependency-cycle detection.
+For host sources, discovery uses rooted `Lstat` and canonical containment.
+`filesystem_context.go` owns resolved access facts and live access setup; the
+acquisition operation closes its live handles before composition. Native sources
+use `fs.ReadLinkFS` inspection when supplied; otherwise traversal follows the
+capabilities and behavior of the provided `fs.FS`, without claiming a general
+sandbox guarantee. `source_context.go` derives passive resource contexts from
+resolved sources for later caller-owned reads; those records do not retain live
+acquisition handles.
+
+Host and native link bindings share one iterative link-frame evaluator. It
+tracks active links for cycle detection and reuses successfully completed link
+targets while resolving the remaining path components; each binding retains its
+own namespace and target-containment rules. Directory reads distinguish an
+initial-open failure from failures after opening: only an initial missing
+directory can be treated as optional, while enumeration and close failures
+remain selection errors, including errors from the standard `fs.ReadDir`
+fallback.
+
+Glob selection keeps traversal coordination in `selectGlobImportCandidates`:
+it advances literal and patterned segments, reads directories, unions and sorts
+candidates, validates final targets, then applies exclusions and requiredness.
+For each patterned directory entry, `prepareGlobEntry` handles matching and
+hidden filtering, containment, target and link inspection, intermediate-directory
+eligibility, host/native access-path selection, and candidate identity and label.
+It returns a candidate, an ordinary skip, or a diagnostic without mutating the
+selector's candidate set or traversal state. Directory entry preparation remains
+separate because its matching, absence, recursion, and traversal-state rules
+differ.
+
+Acquisition remains authored: declarations are visited in source order and each
+selected candidate set in namespace-path lexical order. This preserves source
+records, IDs, source-local version checks, and callback ordering. The acquired
+inclusion graph is retained separately from composition scopes so cycles that
+cross item boundaries remain detectable. Source discovery does not itself choose
+sequence assembly order.
+
+## Stable keys and scheduling
+
+The shared scheduler compares immutable tuples component by component using Go's
+bytewise string order; if one tuple is a prefix of another, the shorter tuple
+sorts first. The import key is
+`(namespace-kind, namespace-anchor, resource-kind, resource-path)`:
+
+- Namespace kind is `host` or `native`. Host resource paths are canonical
+  absolute paths rendered with slash separators; native paths retain their
+  namespace-relative identity.
+- Anchors come from explicit input positions, not discovery order: main is
+  `(0,0)` and underlay/input positions are `(group+1,input+1)`, each encoded as
+  fixed-width decimal. Host accesses in one scheduled tier share its host anchor.
+  A native filesystem namespace uses its earliest explicit selecting position
+  in that tier. Filesystem tokens distinguish namespace equality, not sort order,
+  so separately constructed filesystems with the same label remain distinct.
+- Resource kind is `file` or `synthetic`. A synthetic root uses its explicit
+  input anchor and an empty resource path rather than a display label or token
+  address.
+
+Inheritance keys are
+`("definition", scope-pointer, definition-pointer)`, where both pointers use
+canonical escaped semantic path spelling. Source IDs are not part of the key.
+
+Both integrations use the same Kahn scheduler: it deduplicates dependency edges,
+keeps currently ready nodes in a min-heap, and selects the smallest ready key
+after every completion. Its scheduling cost is `O(E + V log V)` time and
+`O(V + E)` additional memory, excluding key construction, tuple copying, and
+tuple comparisons. On a stalled graph, deterministic DFS over the residual graph
+returns a closed cycle rotated to its smallest key; blocked dependents are not
+reported as cycle members.
+
+Import edge preparation builds an importer-to-target adjacency index once for
+an acquisition's outer and item-local scheduling, and once for grouped
+scheduling. Each scope gathers edges from its participating identities and
+retains only edges with both endpoints in its local slots. The retained
+inclusion graph still owns cycle diagnostics and source relationships.
+
+Import composition schedules a main tier or one underlay group as a single
+strict-scope graph. Applicable collection declarations are gathered for the
+scope before peer composition, including identity inherited from lower tiers.
+Identified peer sequences then combine distinct records in assembled source and
+list order; after the strict scope completes, layered assembly applies the
+resolved collection operation against the lower value, as defined by the
+[configuration contract](../config.md#strict-document-composition). Item
+contributions own nested local strict-mapping scopes; their helpers complete
+before the item is placed in its outer scope. Inheritance uses the same
+ready-node rule inside each sibling mapping scope, while preserving the authored
+mapping order in its output.
+These scopes do not flatten into one global graph, and independent precedence
+tiers remain separate.
+
+The owners are [`acquisition.go`](../../internal/engine/acquisition.go),
+[`import_selection.go`](../../internal/engine/import_selection.go),
+[`import_acquisition.go`](../../internal/engine/import_acquisition.go),
+[`directory_walk.go`](../../internal/engine/directory_walk.go),
+[`import_graph.go`](../../internal/engine/import_graph.go),
+[`import_projection.go`](../../internal/engine/import_projection.go),
+[`dependency_order.go`](../../internal/engine/dependency_order.go), and
+[`inheritance_schedule.go`](../../internal/engine/inheritance_schedule.go).
+Their focused behavior is covered by import-selection, acquisition, scheduler,
+and scheduling integration tests under `internal/engine`; see the
+[development test map](../development.md#task-to-test-map).

docs/internal/overview.md

@@ -7,20 +7,44 @@ private state; public signatures and fields do not expose engine types.
 
 Implemented component owners:
 
-- `internal/engine` owns host and native-filesystem source acquisition,
-  grouped strict composition, recursive precedence assembly, and destination-local
-  sibling inheritance before typed decoding. It also owns schema
+- `internal/engine` owns host and native-filesystem source acquisition and
+  explicitly selected configuration discovery. A search resolves once during
+  shared acquisition; the selected concrete file or absent-input state then
+  follows the existing composition, metadata, and resource-context lifecycle.
+  It also owns grouped strict composition, recursive precedence assembly,
+  per-input mapping and sequence-item placement, YAML collection declarations
+  and operations for identified sequences, and application identity registrations for strict
+  composition, inheritance, and final validation. It applies the selected
+  collection operation at precedence boundaries and owns dependency-ready,
+  destination-local inheritance before typed decoding. CLI assignment follows
+  inheritance and decoding, before application resolution. The engine also owns
+  shared source-version checking with sanitized declaration evidence.
+  Explicit import discovery supports declared paths, directory searches, and
+  globs; root-owned defaults are converted to the engine's single defaults input
+  and snapshotted during load preflight before acquisition, while source-local
+  empty-selection evidence crosses the facade without changing acquisition
+  order. The root constructs placement directly on engine options and inputs
+  using explicit enum conversion; public types and fields remain root-owned.
+  Import and inheritance resolution share dependency-ready scheduling within
+  their composition scopes.
+  It retains each source's effective placement alongside physical source
+  identity and owns schema
   inspection, lifecycle coordination, callback auditing,
   provenance/history, passive source-context retention, secret resolution and
-  bootstrap, and safe inspection rendering. It never imports the root package.
+  bootstrap, operation-local secret failure-location attribution, safe
+  inspection rendering, and effective-value comparison over
+  frozen inspection snapshots. It never imports the root package.
 - Root `Source`, `Filesystem`, `Input`, `Underlay`, `Path`, `Secret`, records,
   lifecycle callbacks, results, and bootstrap reports are root-defined wrappers
   or records. Callback wrappers pass only live engine context during a callback;
   `Result.Config` is detached and its private inspection remains frozen
   independently.
-- Root conversion files explicitly cross the path, record, callback, secret, and
-  error boundaries. There are no public aliases, anonymous engine embeddings, or
-  public engine bridge methods.
+- Root conversion files explicitly cross the path, record, callback, secret,
+  search-description, and error boundaries. There are no public aliases,
+  anonymous engine embeddings, or public engine bridge methods.
+- Root `Diff` and `Difference` provide the public comparison boundary and
+  convert detached engine records to root-owned paths and snapshots; consumer
+  examples own presentation of the safe changed regions.
 - `internal/document` owns the parser-independent ordered tree and cloning.
   `internal/yaml` is the sole upstream YAML adapter and parser/dumper boundary.
 - Engine mechanism tests own source, composition, inheritance, decoding,
@@ -37,10 +61,127 @@ these constraints and rejects exported aliases, fields, or signatures involving
 internal types.
 
 The [configuration contract](../config.md) owns implemented YAML and lifecycle
-semantics. The [consumer adoption guide](../consumers/README.md) owns application
-guidance. The [architecture policy](../policy/architecture.md) owns contributor
-boundaries, and [ADR 0006](../adr/0006-public-facade.md) records the facade
+semantics, including
+[configuration discovery](../config.md#configuration-discovery),
+[input destinations](../config.md#input-destinations),
+[shared source-version checks](../config.md#shared-source-version-checks), and
+[effective configuration diffs](../config.md#effective-configuration-diffs).
+The [strict composition contract](../config.md#strict-document-composition)
+owns sequence declarations, identity, operations, ownership, and final
+validation; [CLI overrides](../config.md#explicit-cli-overrides) own override
+ordering. The [consumer guide](../consumers/README.md#identified-prompt-sequences)
+links maintained workflow examples.
+The [consumer adoption guide](../consumers/README.md) owns application guidance.
+The [architecture policy](../policy/architecture.md) owns contributor
+boundaries; [ADR 0006](../adr/0006-public-facade.md) records the facade decision
+and [ADR 0010](../adr/0010-effective-configuration-diff.md) records the diff
+decision; [ADR 0011](../adr/0011-input-destinations.md) records the placement
 decision. See the [development guide](../development.md) for validation commands
 and [release procedure](../release.md) for source-candidate gates. [ADR
 0009](../adr/0009-sibling-inheritance.md) records why inheritance is a built-in
-post-assembly structural operation.
+post-assembly structural operation. [ADR 0012](../adr/0012-relative-import-destinations.md)
+records the relative-import extension; [ADR 0013](../adr/0013-shared-source-version-checks.md)
+records the source-version decision.
+[ADR 0014](../adr/0014-sequence-placement-and-composition.md) records explicit
+sequence placement and composition. [ADR 0015](../adr/0015-shared-dependency-ready-ordering.md)
+records the shared dependency-ready ordering decision; [ADR
+0016](../adr/0016-independent-import-controls.md) records the independent
+selection controls. [ADR 0017](../adr/0017-collection-sequence-policy.md) and
+[ADR 0018](../adr/0018-cli-after-structural-resolution.md) record collection
+operations and CLI ordering. [ADR 0019](../adr/0019-explicit-configuration-discovery.md)
+records explicit main-file discovery. The [import internals](imports.md)
+document candidate and namespace identities, discovery and scheduling, and the
+bounded algorithms.
+
+## Implementation flow
+
+The root facade converts caller-owned values into engine-owned requests. Its
+`ImportDefaults` conversion maps fields without taking ownership; engine load
+preflight snapshots the defaults once before source acquisition or callbacks.
+Ordinary and grouped loading then carry that read-only value through their
+normalized `loadRequest` and acquisition policy, while declaration resolution
+copies values needed by its independently owned effective policy. Placement is
+constructed directly on the engine's options and input records after explicit
+root-to-engine enum conversion. See
+[`lifecycle.go`](../../lifecycle.go), [`layered.go`](../../layered.go), and
+[`load_request.go`](../../internal/engine/load_request.go). Load-wide definition,
+version, default-import, and override policy stays distinct from each input's
+source, filesystem, destination, and import settings.
+
+[`acquisition.go`](../../internal/engine/acquisition.go) defines acquisition
+policy, load-wide accounting, and tier-scoped repetition/namespace state. Each
+input is acquired under that policy; grouped requests retain acquired underlay
+scopes until their tier is composed in
+[`load_request.go`](../../internal/engine/load_request.go). Completed tiers then
+share one assembly handoff that applies collection declarations and projects
+only that tier's source/version evidence; the caller keeps main-version
+protection and its projection explicit. Live
+filesystem access handles are confined to acquisition and closed there. Resolved
+filesystem facts used to authorize access are separate from passively retained
+resource contexts. Non-import validation retains those facts on `assembledInput`
+for passive-context construction and ordinary-overlay handling: see
+[`filesystem_context.go`](../../internal/engine/filesystem_context.go) and
+[`source_context.go`](../../internal/engine/source_context.go).
+
+Import responsibilities are split across candidate selection and path
+normalization in [`import_selection.go`](../../internal/engine/import_selection.go),
+source reading and traversal admission in
+[`import_acquisition.go`](../../internal/engine/import_acquisition.go),
+directory walking in [`directory_walk.go`](../../internal/engine/directory_walk.go),
+dependency graph scheduling in [`import_graph.go`](../../internal/engine/import_graph.go),
+and projection of acquired evidence into final source coordinates in
+[`import_projection.go`](../../internal/engine/import_projection.go). The
+[import internals](imports.md) page describes the boundaries and identities.
+
+After acquisition handles are closed, grouped composition and inheritance run on
+the retained ordered documents. `inheritance.go` coordinates traversal and
+[`inheritance_schedule.go`](../../internal/engine/inheritance_schedule.go) applies
+dependency-ready templates;
+[`inheritance_prepare.go`](../../internal/engine/inheritance_prepare.go)
+prepares child and parent inputs,
+[`inheritance_combine.go`](../../internal/engine/inheritance_combine.go)
+returns the combined value with its origin, policy, sequence, and diagnostic
+evidence, and [`inheritance_finalize.go`](../../internal/engine/inheritance_finalize.go)
+accounts for and finalizes the result. Projection and schema work have separate
+operation owners: [`value_operation.go`](../../internal/engine/value_operation.go)
+holds per-operation state, [`projection.go`](../../internal/engine/projection.go)
+builds projected values, [`schema.go`](../../internal/engine/schema.go) owns
+descriptor caching and type policy, and
+[`schema_fields.go`](../../internal/engine/schema_fields.go) owns ordinary and
+inline field assembly. [`decode.go`](../../internal/engine/decode.go) consumes
+those descriptors for typed decoding.
+
+History and inspection use one private evidence owner. The
+[`history_model.go`](../../internal/engine/history_model.go) builder receives
+baseline, source-composition, inheritance, typed-checkpoint, and CLI evidence
+in [`preparePostDecodeOverrideContext`](../../internal/engine/override_context.go),
+before application resolution begins. The callback retains its separate fixed
+entry view; it does not read a builder that continues to change. After successful
+resolution auditing, [`resolveLoadInput`](../../internal/engine/load_result.go)
+adds the original resolution records and their net replay groups. At the existing
+pre-secret admission boundary, [`prepareInspectionHistory`](../../internal/engine/load_result.go)
+freezes that builder and counts the retained document roots before secret lookup
+and validation.
+
+The frozen model is shared by `Metadata` and `Inspection`. Its shape-aware
+selection in [`history_select.go`](../../internal/engine/history_select.go)
+drives metadata history, explanation, and historical-path membership; the model
+also supplies historical diagnostic locations and sensitivity/dependency
+evidence. `Inspection` replays selected payloads to produce detached, safely
+rendered values, while metadata queries return detached attribution records.
+History and explanation behavior is covered by focused `history_*_test.go`
+tests alongside metadata, secret, inheritance, and facade integration tests.
+
+Behavioral ownership follows the same handoffs: imports and grouped lifetimes are
+covered by `imports_test.go`, `load_request_test.go`, and focused source,
+discovery, and destination tests; inheritance by the inheritance test files;
+reflection behavior by `schema_test.go`, `projection_test.go`, and
+`decode_test.go`. The [development test map](../development.md#task-to-test-map)
+links focused commands. [`clone.go`](../../internal/engine/clone.go) owns typed
+copying, using the shared descriptors and per-operation traversal helpers.
+
+Each schema operation builds its private reflection descriptor graph with
+operation-local caching; there is no global mutable descriptor cache. Decoding,
+projection, and cloning reuse these descriptors so field bindings agree. The
+public reference describes the resulting type, output, and ownership behavior;
+this descriptor storage is an implementation detail.

docs/oss/attribution.md

@@ -2,11 +2,12 @@
 
 ## Standard Repository Policies
 
-Material: `docs/policy/meta.md`, `docs/policy/oss.md`,
+Material: `docs/policy/release.md`, adapted from
+`e833faddf120c789a9b45348edaf75720de16348`; `docs/policy/meta.md`, `docs/policy/oss.md`,
 `docs/policy/documentation.md`, `docs/policy/agents.md`,
-`docs/policy/architecture.md`, `docs/policy/testing.md`, and
-`docs/policy/release.md`; root `AGENTS.md`; and the Policy Reading Guide in
-`docs/development.md`, adapted for this repository.
+`docs/policy/architecture.md`, `docs/policy/testing.md`; root `AGENTS.md`; and the
+Policy Reading Guide in `docs/development.md`, adapted from
+`d84a38ebab26f048cafbe59a2246700c35d29843` for this repository.
 
 Copyright (C) 2026 Eric Rakestraw
 
@@ -14,10 +15,14 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
 [COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/COPYRIGHT) |
-[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE).
+[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE) |
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/COPYRIGHT) |
+[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/LICENSE).
 
 [Source](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843).
 
+[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348).
+
 ## go-yaml v4
 
 Selected module: `go.yaml.in/yaml/v4` at `v4.0.0-rc.6`.

docs/policy/architecture.md

@@ -2,7 +2,7 @@
 
 **Base Policy Version:** 1.3
 
-**Last Updated**: 2026-09-29
+**Last Updated**: 2026-10-22
 
 **Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md)
 
@@ -19,8 +19,8 @@ to ADRs for decision rationale.
 ConfigKit is an opinionated Go library for consistent YAML configuration loading
 and resolution across consuming applications. The [component overview](../internal/overview.md)
 owns implementation inventory, the [configuration contract](../config.md) owns
-implemented behavior, and the [deferred scope](../roadmap/deferred.md) preserves
-deferred scope.
+implemented behavior, and the [future feature list](../roadmap/future.md) preserves
+candidates for future consideration.
 
 ## Adopted Constraints And Implemented Structure
 
@@ -32,6 +32,12 @@ structure as implemented when its changes land.
 Constraints must reflect deliberately selected requirements and decisions.
 Do not promote incidental implementation choices into architectural invariants.
 
+The implemented collection-policy and CLI-ordering constraints below reflect
+accepted [ADR 0017](../adr/0017-collection-sequence-policy.md) and
+[ADR 0018](../adr/0018-cli-after-structural-resolution.md). The configuration
+contract owns their current behavior; these architectural constraints describe
+the system boundaries and guarantees that guide changes to that behavior.
+
 ## Success Criteria
 
 ConfigKit prioritizes a coherent configuration model: consistency and
@@ -91,17 +97,82 @@ boundaries, and keep simple consumers independent of optional composition
 features. The [consumer adoption guide](../consumers/README.md) demonstrates the
 implemented surface against representative simple and complex shapes.
 
+## Simplicity, Defaults, And Explicit Controls
+
+These principles apply throughout ConfigKit: to configuration syntax, the public
+Go API, defaults, and feature design. Evaluate their effects on both configuration
+authors and consuming applications.
+
+**Keep straightforward workflows straightforward.** Common configuration
+workflows should require little configuration text and minimal API setup.
+Support more demanding workflows through explicit, composable options, without
+requiring simple consumers to understand or configure those options.
+
+**Prefer simple, permissive defaults with explicit controls.** Choose predictable
+defaults that minimize required setup and accommodate valid configurations
+without unnecessary restrictions. Provide selectable options for workflows that
+need additional capabilities, narrower behavior, or stronger requirements.
+
+Measure simplicity by what consumers must understand and maintain, including
+configuration text and application-side plumbing. Concise syntax is useful, but
+hidden inference and interacting meanings can make a shorter declaration harder
+to understand. Prefer explicitness where it makes behavior more predictable.
+A terse configuration format that requires substantial application-side
+infrastructure does not satisfy the simplicity principle.
+
+Define what permissiveness means for each behavior. Allowing an optional
+contribution to be absent or accepting valid inputs without an unnecessary
+filename restriction can reduce required setup. Invalid declarations, ambiguous
+composition, and unreadable selected sources must still produce meaningful
+errors under the applicable contracts. Permissiveness does not authorize silent
+recovery from invalid supplied configuration or weaken configuration integrity.
+
+Options should express coherent choices with understandable purposes and fit
+ConfigKit's shared configuration model. Support powerful controls when they
+serve concrete needs; these principles do not require a switch for every
+implementation behavior or conceivable consumer preference.
+
+Defaults require judgment when simplicity and permissiveness pull in different
+directions. Broader discovery can accommodate more layouts while increasing the
+implicit search scope. Evaluate such tradeoffs explicitly; these principles do
+not mechanically select the broadest behavior for every option. Changes to
+existing defaults remain subject to compatibility review, and proposed behavior
+remains in the roadmap until implemented.
+
 ## Responsibility Boundaries
 
 ConfigKit owns configuration input processing and the coordination of decoding,
 resolution, validation, and inspection. Applications own their configuration
 types, field meanings, defaults, normalization, semantic validation, and schema
-version policy. Applications also own main-file search conventions, CLI wiring,
-remote acquisition, runtime initialization, and resource checks.
+version policy. Applications choose and order their main-file search conventions;
+ConfigKit provides explicitly selected search descriptions that resolve during
+loading. Applications also own CLI wiring, remote acquisition, runtime
+initialization, and resource checks. See the [configuration discovery
+contract](../config.md#configuration-discovery) and [ADR
+0019](../adr/0019-explicit-configuration-discovery.md).
+
+The engine applies each input's mapping destination within the existing source
+assembly, applies immediate-parent-relative YAML destinations to imports, and
+retains each effective placement with source identity and inspection records;
+the root facade owns the public fields and conversions. The
+[configuration contract](../config.md#input-destinations) defines the observable
+placement behavior. [ADR 0011](../adr/0011-input-destinations.md) records input
+placement, and [ADR 0012](../adr/0012-relative-import-destinations.md) records
+the import extension.
 
 Library code must not depend on consuming applications or initialize their
-runtime resources. It must not perform implicit network access, discover
-application-specific paths, or change process-global state during ordinary `Load`.
+runtime resources. It must not perform implicit network access, implicitly
+discover application-specific paths, or change process-global state during
+ordinary `Load`.
+Import discovery is available only through declarations in selected sources:
+explicit `path`, `dir`, and `glob` selectors may search their declared scope, but
+ConfigKit does not search conventional application paths unless the application
+explicitly supplies a discovery description, and it never discovers a main
+configuration file implicitly. Imports and sibling inheritance share
+dependency-ready scheduling within their existing scopes; acquisition order and
+precedence-tier boundaries remain distinct. The [configuration contract](../config.md#explicit-imports)
+owns observable behavior; [ADR 0015](../adr/0015-shared-dependency-ready-ordering.md)
+and [ADR 0016](../adr/0016-independent-import-controls.md) record the decisions.
 The explicit secrets-directory bootstrap is a narrow, opt-in exception: applications
 invoke it during startup, and it reports writes, skips and partial failures. It
 must never run implicitly as part of configuration loading.
@@ -124,6 +195,29 @@ The [configuration contract](../config.md#completion-and-resource-lifetime) owns
 the precise completion and ownership behavior. The proposed decision record is
 [ADR 0008](../adr/0008-complete-on-return-loading.md).
 
+### Accepted Processing Order
+
+Complete source composition and precedence, including selected overlays, before
+sibling inheritance. Then apply typed defaults and decode the configuration.
+Apply explicit CLI overrides to that configuration and check their types before
+running application resolution. Effective secret lookup and final validation
+follow resolution, before publication. [ADR 0018](../adr/0018-cli-after-structural-resolution.md)
+records this ordering.
+
+CLI overrides are the highest-priority input to application resolution. Supplied
+sequences replace whole sequences, and mappings combine recursively. Inheritance
+and typed defaulting do not run again after CLI application. CLI paths and values
+must not introduce structural directives; earlier source, inheritance, and
+decoding failures remain errors even if a CLI assignment would replace the value.
+Semantic validation assesses the final configuration after overrides and resolution.
+
+Applications own flag parsing and domain resolution. ConfigKit owns override
+application, validation, and source attribution. Resolution receives CLI values
+with their explicit-presence and source information. Absence-based defaults
+preserve explicit values; recorded normalization and derivation can still change
+them. Typed defaults and application resolution retain their own assignment
+semantics, independently of collection operations during source assembly.
+
 ## Public API And Dependency Direction
 
 Keep one small, coherent public surface for the supported lifecycle. Simple
@@ -152,31 +246,44 @@ framework on this library.
 
 ## Configuration Integrity
 
-Within a configuration tier, independent contributions use strict composition:
-shared mappings combine recursively, while overlapping non-mapping definitions
-are conflicts, including equal values. Between precedence tiers, intentional
-overlay combines mappings recursively, retains omitted lower-priority children,
-and replaces other present values according to the existing overlay rules.
-Tier precedence is explicit; traversal order within a tier establishes stable
-reporting, not permission to override. The distinction and its rationale are
-recorded in [ADR 0001](../adr/0001-separate-composition-and-overlay.md).
+Within a configuration tier, independent contributions use strict composition.
+Shared mappings combine recursively. Sequences with an applicable identity
+combine distinct records and reject duplicate identities, including equal
+records. Other overlapping non-mapping values remain conflicts, including equal
+values. Conflicting identity or operation declarations among peers also fail.
+Traversal order establishes stable reporting and record order; it does not grant
+precedence to peers. [ADR 0001](../adr/0001-separate-composition-and-overlay.md)
+records the distinction between strict composition and intentional overrides.
 
 The main document and its imports form a strictly composed tier. Explicit
-underlay groups compose strictly within each group, then combine recursively
-from lowest to highest beneath the main tier. Source acquisition kind does not
-determine its precedence role. Input-specific constraints, including CLI path
-rules and opt-in version ownership, remain part of the configuration contract. Consistent combination
-semantics do not require identical acquisition or lifetime behavior from every
-source kind.
+underlay groups compose strictly within each group, then combine from lowest to
+highest beneath the main tier. Between tiers, mappings combine recursively and
+retain omitted lower-priority children. Sequence values follow collection policy;
+other present values retain the established replacement rules. Source acquisition
+kind does not determine precedence. Input-specific constraints, including version
+ownership and path protections, remain part of the configuration contract.
+Consistent combination semantics do not require identical acquisition or lifetime
+behavior from every source kind.
 
-After source precedence is complete, built-in sibling `extends` relationships
-resolve structurally in the same parser-independent representation, using the
-existing recursive overlay rules. This adds neither an acquired source nor a
-consumer registration mechanism. Enclosing relationships precede nested
-destination-local resolution; typed defaults, application resolution, and
-secret lookup retain their existing lifecycle roles. The [configuration
-contract](../config.md#sibling-inheritance) owns the exact syntax and presence
-rules, and [ADR 0009](../adr/0009-sibling-inheritance.md) records the rationale.
+Built-in sibling `extends` relationships resolve after source precedence in the
+parser-independent document representation. Preserve existing mapping-sibling
+scopes and allow an identified sequence to provide a sibling scope for its
+records. A record may inherit from one parent in that sequence, selected by
+complete identity. The child supplies and keeps its own identity while inheriting
+the parent's other settings. Parents remain ordinary records subject to normal
+validation.
+
+Use the shared dependency ordering and preserve assembled sequence order.
+Resolve enclosing relationships before nested destination-local relationships.
+Mappings combine recursively; sequences use the inheriting collection's policy.
+Whole-record upsert replaces records during combination; explicit inheritance
+uses the records that remain. Inheritance remains built-in and creates no
+acquired source.
+[ADR 0009](../adr/0009-sibling-inheritance.md) records the
+original scope and continuing ownership decisions, with sequence combination
+and identified-sequence inheritance defined by
+[ADR 0017](../adr/0017-collection-sequence-policy.md) and CLI ordering by
+[ADR 0018](../adr/0018-cli-after-structural-resolution.md).
 
 ConfigKit must define supported YAML semantics explicitly rather than inherit
 parser defaults. Processing order and diagnostics must be deterministic for the
@@ -185,13 +292,14 @@ configuration. Do not run application hooks on invalid typed configuration.
 
 User-controlled precedence is application defaults, ordered underlays, composed
 main input, selected overlay, then explicitly supplied CLI overrides.
-Applications own flag parsing; ConfigKit owns overlay semantics and provenance.
-Domain resolution follows these
-inputs and must remain recorded, not become a hidden override channel.
+This priority order is distinct from processing order: typed defaults are applied
+at decoding, and application resolution follows CLI input under the lifecycle
+rules above.
 
-Preserve node-based composition until the effective input is ready for typed
-decoding. Preserve presence and source information through processing. Ordinary Go zero
-values must not be used to infer whether input was absent. Final configuration,
+Preserve node-based composition through source assembly and inheritance until
+typed decoding. Preserve presence and source information through later CLI and
+application-resolution changes as well. Ordinary Go zero values must not be used
+to infer whether input was absent. Final configuration,
 metadata, and effective inspection must agree, including application resolution
 changes; see [ADR 0003](../adr/0003-preserve-presence-and-resolution-history.md).
 Safe historical values and an explanation renderer are part of the implemented contract,
@@ -201,6 +309,79 @@ See [ADR 0005](../adr/0005-explicit-overrides-and-safe-explanation.md).
 Detailed syntax and operation tables belong to the
 [current configuration contract](../config.md).
 
+The frozen inspection boundary also supports comparing completed same-type
+results without reopening sources or rerunning the load lifecycle. The
+[configuration contract](../config.md#effective-configuration-diffs) owns
+comparison and disclosure behavior, the [component overview](../internal/overview.md)
+owns implementation responsibility, and [ADR 0010](../adr/0010-effective-configuration-diff.md)
+records the accepted decision.
+
+## Collection Identity And Combination
+
+ConfigKit owns a common collection policy for imported records, inline sequences,
+selected overlays, and sibling inheritance. Configuration authors may declare
+identity and combination rules; applications may register authoritative identity
+constraints. Configuration declarations must agree with application constraints.
+Keep source placement explicit and separate from policy, retaining the placement
+decision in [ADR 0014](../adr/0014-sequence-placement-and-composition.md).
+[ADR 0017](../adr/0017-collection-sequence-policy.md) owns the rationale for
+collection policy and its relationship to application authority.
+
+Gather declarations for the relevant destination and source or item-local scope
+before strict composition. Applicable identity from accumulated lower tiers must
+be available when composing higher-tier peers. Higher-tier declarations cannot
+repair invalid lower-tier composition. Preserve the distinction between source
+acquisition, dependency-ready scheduling within scopes, and precedence order.
+
+Strictly compose each tier's contributions before applying one operation for the
+collection against its lower value. Support whole-sequence replacement,
+duplicate-rejecting append, and whole-record replacement by identity (`upsert`).
+Append and upsert require identity; do not infer it from record fields or position.
+Duplicate identities among peers fail under every mode. Source precedence and
+inheritance use the same operations and deterministic ordering rules. Whole-record
+upsert replaces the matching record's fields together; recursive record merging
+and unkeyed sequence concatenation are outside this operation model.
+
+An explicit mode persists at its applicable destination until a higher explicit
+mode changes it. With no explicit mode, effective identity selects upsert and
+its absence selects whole-sequence replacement. Inferred defaults do not become
+persistent instructions. The inheriting destination chooses its operation; copying
+a parent collection does not automatically copy its mode to that destination.
+
+Track YAML identity and explicit modes according to their separate lifetimes.
+Actual whole-value replacement discards lower YAML identity while preserving
+application constraints and any new identity declaration. Item-local policies
+belong to their records: retaining a record retains its rules, and discarding it
+discards those rules. Policies independently applicable at a destination remain
+in effect. Inheritance can copy YAML identity subject to agreement and replacement
+rules; application registrations continue to constrain their registered paths.
+Numeric positions alone do not establish policy ownership.
+
+Allow declarations without accompanying records. A key declaration validates a
+retained sequence immediately or remains pending in its owning scope when no
+sequence exists. A mode-only declaration affects later combinations without
+recombining earlier tiers. Neither declaration alone clears a collection, and
+declaring replace alone does not authorize changing a retained collection's
+identity. These rules do not independently impose path-existence or shape
+requirements.
+
+Enforce YAML identity during source composition, precedence, and identified
+inheritance operations. Application registrations additionally constrain final
+effective sequences after defaults, CLI overrides, and application resolution.
+The application schema and validation own existence, nullability, and allowed
+shape. The final identity guarantee covers actual sequences on successful load;
+it does not cover every intermediate callback state or later caller mutations.
+YAML-only declarations carry no such final guarantee through defaults, CLI
+assignments, or application resolution.
+
+Preserve source attribution, presence, history, sensitivity, and resource context
+as records survive, move, or are replaced. Identity diagnostics use paths and
+available origin information without exposing identity values. The guarantee
+requires no new mutation-history system or exact reconstruction of causes for
+records supplied by defaults or callbacks. Exact identity equality, declaration
+syntax, presence cases, and operation tables belong in the
+[configuration contract](../config.md#strict-document-composition).
+
 ## Ownership And Confidentiality
 
 Returned configuration and metadata must not share mutable state across loads.
@@ -227,7 +408,7 @@ for safe messages supplied by their hooks.
 Do not introduce automatic directory discovery, network providers, arbitrary
 merge strategies, additional configuration languages, or application runtime
 management without concrete consumer evidence and an explicit design decision.
-The [deferred scope](../roadmap/deferred.md#explicit-non-goals-and-deferred-scope)
-owns the deferred-feature inventory. Significant boundary
-changes require an ADR and corresponding policy/contract updates; implementation
-convenience alone is not a reason to broaden the public API.
+Record significant decisions to exclude capabilities, and their rationale, in
+ADRs. Significant boundary changes require an ADR and corresponding
+policy/contract updates; implementation convenience alone is not a reason to
+broaden the public API.

docs/policy/documentation.md

@@ -2,7 +2,7 @@
 
 **Base Policy Version:** 1.11
 
-**Last Updated**: 2026-09-28
+**Last Updated**: 2026-10-16
 
 **Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md)
 
@@ -38,9 +38,10 @@ roadmap owns implementation status and sequencing until the decision is
 implemented. Current architecture, user, operator, integration, and internal
 documentation are updated when the behavior lands.
 
-`docs/roadmap/deferred.md` owns deliberate exclusions; task-specific plans
-own execution order and progress. Completed plans retire during release
-preparation.
+`docs/roadmap/future.md` owns potential enhancements and their open questions;
+task-specific plans own execution order and progress. Record significant
+architectural exclusions and their rationale in ADRs. Do not maintain a roadmap
+inventory of rejected proposals. Completed plans retire during release preparation.
 
 ### Audience And Detail
 
@@ -91,7 +92,7 @@ secret values.
 | Inventory of implemented internal packages | `docs/internal/overview.md` | Implemented packages and components, responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
 | Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
 | Architectural decision records | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. |
-| Deferred scope | `docs/roadmap/deferred.md` | Deliberate exclusions and conditions for reconsideration. | Task execution and current behavior. |
+| Potential future features | `docs/roadmap/future.md` | Candidate enhancements and open questions for future consideration. | Rejected proposals, architectural decisions, task execution, and current behavior. |
 | Future implementation plans | Task-specific files under `docs/roadmap/` | Unfinished work, sequencing, acceptance, and progress; completed plans retire during release preparation. | Implemented behavior and ADR rationale. |
 | Release-note history | `docs/releases/` | One checked-in summary per source release under the procedure; the note at its immutable tag is the release record. | Current commands, behavior, contracts, and compatibility definitions. |
 | Complete examples | `examples/` and executable Go examples | Maintained copyable artifacts and Go API examples. | Configuration reference, symbol contracts, and prose explanation. |
@@ -156,8 +157,10 @@ Use sequentially numbered ADR filenames such as
 
 Treat the decision content of an accepted ADR as immutable. When a decision
 changes, create a new ADR and update the earlier ADR's status to superseded.
-Rejected architectural alternatives belong in the ADR; rejected product ideas
-belong in the roadmap. Routine choices need no ADR.
+Rejected architectural alternatives and significant architectural exclusions
+belong in ADRs. Roadmaps preserve plausible future work, not rejected product
+ideas. Routine choices and rejected suggestions need no ADR unless they
+represent a significant architectural decision.
 
 ## Maintenance
 

docs/policy/release.md

@@ -1,10 +1,10 @@
 # Release Policy
 
-**Base Policy Version:** 1.4
+**Base Policy Version:** 1.6
 
-**Last Updated**: 2026-09-28
+**Last Updated**: 2026-10-09
 
-**Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md)
+**Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/docs/policy/release.md)
 
 ## Purpose
 
@@ -12,6 +12,9 @@ This policy defines a proportionate workflow for validating and publishing an
 intended source revision under a fresh version. Releases should require little
 routine intervention, avoid repeated work, and preserve published contents.
 
+Adopt stronger verification or reproducibility requirements through an explicit
+project-specific decision justified by the intended audience and support needs.
+
 The repository-specific commands belong in `docs/release.md`. Historical release
 summaries belong in `docs/releases/`. The procedure must agree with the adopted
 policy and link to it rather than introduce additional release requirements.
@@ -54,10 +57,11 @@ authoritative primary branch, completes the release. The source commit may be
 pushed before the tag or published together with it through an atomic push.
 The procedure must choose and document the supported approach.
 
-ConfigKit uses sequential explicit pushes: first the captured candidate to
-authoritative `main`, then the annotated tag. Its
-[release procedure](../release.md) names `origin` and checks that its fetch and
-push destinations resolve to the authoritative URL.
+ConfigKit uses sequential publication: first push the committed candidate to
+authoritative `main`, then invoke ReleaseKit once to validate that candidate and
+publish its annotated tag. The [release procedure](../release.md) names
+`origin`; ReleaseKit checks its exact effective push URL before validation and
+tag publication.
 
 Release commands must finish at successful publication. They must not wait for
 or poll CI, require successful CI status, inspect downloadable artifacts, or
@@ -76,8 +80,9 @@ the tagged source. The procedure must identify those deliverables and the
 responsibility of their automation. Published deliverables must be traceable
 to that source and identify the same version.
 
-ConfigKit currently declares no additional deliverables. Its source-tag push
-is the completion point.
+ConfigKit currently declares no additional deliverables. Confirmed publication
+of the intended source tag is the completion point. CI, macOS validation,
+hosted delivery, and consumer retrieval are outside the release gates.
 
 ## Versioning And Compatibility
 
@@ -96,7 +101,8 @@ requires a deliberate update to the policy and procedure where needed.
 For releases at or after `v1.0.0`:
 
 - a major release may make intentional incompatible changes;
-- a minor release may add backward-compatible behavior; and
+- a minor release may add backward-compatible behavior or raise the Go consumer
+  minimum as described below; and
 - a patch release may make backward-compatible fixes.
 
 Before `v1.0.0`, a minor release may change a documented public, operational,
@@ -108,13 +114,53 @@ Additional compatibility promises and deliberate exceptions belong in the
 adopted policy or canonical contract documentation. Release notes explain
 changes; they do not redefine current compatibility contracts.
 
+## Consumer Minimum And Release Toolchain
+
+Distinguish the minimum toolchain supported for consumers from the toolchain
+maintainers use to build and validate a release. Record the consumer minimum in
+the language's standard metadata and explain its support meaning in canonical
+documentation. Define the selected release toolchain and its setup commands in
+`docs/release.md`. Toolchain selection and upgrade cadence are repository-specific
+choices.
+
+For Go repositories, normally declare the initial stable release of the selected
+series as the consumer minimum, such as `go 1.26.0`. Use a higher patch minimum
+when a dependency or an identified correctness fix requires it, and document
+the reason.
+
+For release-policy purposes, successful build and release validation on the
+selected Go patch release are sufficient to presume support across that Go
+series, subject to the declared consumer minimum and concrete evidence of
+incompatibility. Investigate specific compatibility concerns as they arise.
+
+Use the selected release toolchain for candidate validation and release builds,
+including CI jobs performing those tasks. A newer validation patch version alone
+leaves the consumer minimum unchanged.
+
+A minor release may raise the Go consumer minimum, including from one Go series
+to the next, both before and after `v1.0.0`. This is an explicit exception to the
+backward-compatibility requirement for minor releases. Patch releases preserve
+the consumer minimum. Explain an increase's impact and required consumer action
+in the release note. Other incompatible changes remain subject to the versioning
+rules above.
+
+### ConfigKit Toolchain Selection
+
+For minor and major releases, select the newest stable Go series available in
+the development environment. For patch releases, retain the series recorded in
+`go.mod` and its consumer minimum. Use the latest locally available compatible
+patch in the selected series, with `GOTOOLCHAIN=local`, to build the
+module-selected ReleaseKit CLI and validate the candidate. The same Go
+executable builds the tool and runs its validation commands.
+
 ## Release Documentation And Preparation
 
 Every new release must include `docs/releases/<version>.md` in the tagged
 source tree. Use the complete version tag as the filename and begin with a
 title containing the product name and that exact version.
 
-ConfigKit requires the first line `# ConfigKit <version>`.
+ConfigKit requires the first line `# ConfigKit <version>`. ReleaseKit's
+publication guard checks the release-note H1 for the product and version.
 
 Include a short summary and any relevant compatibility impact or upgrade
 instructions. Choose sections suited to the release and keep the note
@@ -146,10 +192,9 @@ checks publication state, and publishes the intended refs. A validation-only
 mode or command may be provided for diagnosis, but must not be a required step
 before publication repeats the same checks.
 
-ConfigKit uses `./scripts/release.sh vMAJOR.MINOR.PATCH`. The separate
-`scripts/release-check.sh` remains an optional diagnostic command; the
-publication command invokes it once and does not use a persistent candidate
-record.
+ConfigKit uses the module-selected ReleaseKit CLI's `publish
+vMAJOR.MINOR.PATCH` command. Its `check` command is optional for diagnosis; it
+is not a required preliminary pass to publication.
 
 Run the complete deterministic, offline default test suite once for the final
 candidate, following the [testing policy](testing.md). For repositories that
@@ -157,13 +202,17 @@ publish builds, verify the required build targets. Select those targets for
 the application's actual support commitments; native testing on each platform
 and access to particular hardware are not default release prerequisites.
 
-ConfigKit's one maintained Go 1.25 baseline runs the full suite with the race
-detector and test-time vet disabled. This protects library behavior, ownership,
-and concurrent use; the suite already includes examples, consumer fixtures,
-documentation links, and package boundaries. One full vet pass adds static
-checks beyond the test-time subset. CGO-disabled Linux amd64 and arm64 builds
-cover supported configurations distinct from native race compilation. macOS
-and newer-toolchain checks are optional.
+Prepare dependencies and build the tool before offline validation; the
+publication command is the required validation run, with no separate successful
+test or CI run required before it.
+
+The selected profile runs the complete deterministic, offline default suite
+once with the race detector and test-time vet disabled. The suite already
+includes examples, consumer fixtures, documentation links, and package
+boundaries. One full vet pass adds static checks beyond the test-time subset.
+CGO-disabled Linux amd64 and arm64 package compilation covers supported
+configurations distinct from native race compilation. macOS and newer-toolchain
+checks are optional.
 
 Additional gates must address a concrete risk that the existing checks do not
 adequately cover. Do not automatically require linting, race testing, module
@@ -172,9 +221,10 @@ expanded platform matrices solely because they are possible. Retain such
 checks when their distinct protection justifies their cost. A one-time migration
 check must not silently become a permanent release requirement.
 
-The selected Go commands use readonly module mode with `GOPROXY=off`; acquire
-the baseline toolchain and dependencies before validation. Formatting and
-whitespace remain ordinary development checks in `scripts/check.sh`.
+ReleaseKit runs its selected Go commands with readonly module mode and
+`GOPROXY=off`; acquire dependencies and build the tool before candidate
+validation. Formatting and whitespace remain ordinary development checks in
+`scripts/check.sh`.
 Review module tidiness when dependencies change, not as a release gate.
 
 Release tests must not require real credentials, mutable application services,
@@ -206,16 +256,19 @@ Automate the checks needed to publish the intended source under a fresh version:
   authoritative remote;
 - the worktree and index are clean on the primary release branch;
 - the source being published is the exact candidate that passed validation,
-  including its matching release note;
+  including its matching release note H1;
 - the remote primary branch can be advanced to that candidate without
   discarding remote history, and is published before the tag; and
 - the tag identifies the validated candidate and only the intended refs are
   published.
 
-ConfigKit also checks that `origin` has exactly the authoritative fetch and
-push destination, including configured push URLs. The command checks the
-candidate and unused version again after validation, and checks local state
-before creating the tag. Ignored local files do not block publication.
+ReleaseKit checks that `origin`'s effective push URL exactly matches the
+authoritative URL before candidate validation. This does not assert the
+configured fetch URL or require the release-note H1 to be the first line; the
+required `# ConfigKit <version>` first-line format remains a content rule. The
+command checks the candidate and unused version again after validation, and
+checks local state before creating the tag. Ignored local files do not block
+publication.
 
 Fetch the authoritative branch and tag state as needed for these checks.
 Do not force branch or tag updates to bypass a failed guard. Publish explicit
@@ -248,10 +301,10 @@ release without replacing its contents or reusing its version.
 ## Repository Release Procedure
 
 Maintain `docs/release.md` as a short, executable maintainer runbook. It must
-identify prerequisites, the primary branch and authoritative remote, version
-and note preparation, one publication command with local checks and guards,
-source-only deliverables, the successful-tag-push completion point, and
-partial or unknown-state recovery.
+identify prerequisites, the selected release toolchain, the primary branch and
+authoritative remote, version and note preparation, one publication command with
+local checks and guards, source-only deliverables, the successful-tag-push
+completion point, and partial or unknown-state recovery.
 
 Use copyable commands where practical. Keep optional diagnostics and consumer
 verification clearly optional. The procedure must not turn preparation work,

docs/release.md

@@ -1,197 +1,271 @@
 # ConfigKit Release Procedure
 
 This is the maintainer runbook for ConfigKit's [release policy](policy/release.md).
-ConfigKit publishes one source-only Go module. The immutable annotated tag and
-matching checked-in release note are the deliverables; there is no binary,
-container image, generated package, or separate registry publication.
+A release publishes the Go source under a new Git tag, with a matching release
+note committed in the repository. The tag is annotated: it includes the release
+note text and points to the released commit. Published tags and contents are
+immutable. There is no binary, container image, generated package, or separate
+registry publication.
+
+A **candidate** is the committed revision you intend to release. The
+**authoritative remote** is the repository where ConfigKit publishes releases;
+its exact push URL is listed below. The **consumer minimum** is the oldest Go
+version supported for applications using ConfigKit.
 
 ## Release identity and support
 
-- Module: `gitea.maximumdirect.net/eric/ConfigKit`
+- Module: `go.maximumdirect.net/configkit`
 - Primary branch: `main`
-- Authoritative remote: `origin`, with fetch and push destination
-  `https://gitea.maximumdirect.net/eric/ConfigKit.git`
+- Authoritative remote: `origin`
+- Authoritative push URL: `ssh://git@forge.maximumdirect.net:22222/base-layer/configkit.git`
 - Tags: stable Semantic Versions such as `v0.5.0`; no prereleases
-- Minimum Go line: Go 1.25, validated with one maintained patch
+- Minimum Go version: the first stable patch of the selected Go series, or a
+  higher patch when required by a dependency or specific correctness fix, as
+  recorded in `go.mod`; see the
+  [consumer minimum policy](policy/release.md#consumer-minimum-and-release-toolchain)
 - Release-gated targets: Linux amd64 and arm64
 - Best-effort targets: macOS amd64 and arm64, under the
   [platform support policy](policy/release.md#platform-support)
 
-The checker runs one offline race suite, one full vet pass, and CGO-disabled
-builds for both Linux targets. It reports skipped filesystem cases. macOS checks
-and newer-toolchain tests are optional. CI is never a readiness or completion
-gate; do not wait for or poll it.
+Release validation runs the offline Go test suite once with the race detector,
+then a full vet pass and package compilation for both Linux targets with cgo
+disabled (`CGO_ENABLED=0`). macOS and CI are
+not release gates; do not wait for or poll CI.
 
-## 1. Prepare access and tools
+The vanity module path is the name applications put in Go imports. Source/tag
+browser links and public Go retrieval use the Forge HTTPS repository
+independently of SSH publication.
 
-Use a clean checkout with Git, Bash 3.2 or newer, a maintained Go 1.25 patch,
-and a native compiler for race tests. Configure private-host access through the
-normal credential manager. Keep credentials and environment dumps outside the
-repository and command transcript.
+## 1. Select Go and prepare the tool
 
-Verify access without displaying credentials:
+Use a clean checkout with Git, Bash 3.2 or newer, and a native compiler for race
+tests. Choose the release type before selecting Go. For a minor or major release,
+select the newest stable Go series available in the development environment.
+For a patch release, retain the series recorded in `go.mod` and leave its consumer
+minimum unchanged. Follow the
+[toolchain selection policy](policy/release.md#configkit-toolchain-selection).
+
+Choose the latest compatible patch installed locally in that Go series. Put
+its `go` executable first on `PATH` and ensure it meets the minimum in
+`go.mod`. The same `go` executable must build ReleaseKit and run its child
+validation commands. Set local toolchain selection and verify it:
 
 ```sh
-git remote get-url origin
-git ls-remote origin HEAD
+export GOTOOLCHAIN=local
+go version
+go env GOVERSION
+command -v go
 ```
 
-The fetch URL and all configured push destinations must resolve to the
-authoritative URL above. The publication command checks this again. Acquire the
-selected toolchain and dependencies explicitly before offline validation:
+Only when a minor or major release advances the consumer minimum to a newer Go
+series, derive that series' initial stable release from the selected executable:
 
 ```sh
-export CONFIGKIT_BASELINE_TOOLCHAIN=go1.25.14
-GOTOOLCHAIN="$CONFIGKIT_BASELINE_TOOLCHAIN" go version
-GOTOOLCHAIN="$CONFIGKIT_BASELINE_TOOLCHAIN" go mod download
+selected_go=$(GOTOOLCHAIN=local go env GOVERSION)
+selected_series=${selected_go#go}
+selected_series=${selected_series%.*}
+release_minimum="$selected_series.0"
+go mod edit -go="$release_minimum"
 ```
 
-A maintained patch may replace the example pin. No per-release latest-version
-survey is required. Dependencies must be cached; the checker sets `GOPROXY=off`.
-Publication requires user authorization. Standing authorization for local
-commits does not authorize a push or release.
+If a dependency or identified correctness fix requires a higher patch minimum,
+use that required version instead and document the reason. When the series is
+unchanged, leave the minimum unchanged unless a minor or major release
+deliberately changes it under the
+[consumer minimum policy](policy/release.md#consumer-minimum-and-release-toolchain).
+For example:
 
-## 2. Select the version and review compatibility
+| Release situation | Go used for validation | Consumer minimum |
+| --- | --- | --- |
+| Patch release in the 1.26 series | Latest compatible patch installed locally, such as 1.26.8 | Keep the existing `go.mod` minimum unchanged. |
+| Minor/major release staying in 1.26 | Latest compatible patch installed locally | Normally retain the minimum; any deliberate change follows the linked policy. |
+| Minor/major release adopting a newer installed stable series | Latest compatible patch installed locally in that series | Normally declare that series' initial stable patch, or the higher patch required by a dependency or identified fix. |
 
-Choose an unused stable version. Compare the candidate with the previous tag.
-Review exported Go signatures and ownership, YAML and scalar semantics,
-precedence, diagnostic codes, minimum Go version, and platform support. A
-signature-preserving change may still affect consumers. Before `v1.0.0`,
-intentional incompatible minor-release changes need a note explaining impact
-and consumer action; patch releases remain compatible within their minor line.
-Review the maintained consumer examples and migration guide.
+Using Go 1.26.8 for validation can therefore leave `go 1.26.0` unchanged. Users
+need the declared minimum, while maintainers validate with their selected patch.
+There is no separate requirement to validate with Go 1.26.0.
 
-When dependencies change, review parser behavior and migration impact as part
-of that change. Module tidiness belongs to dependency-change review, not the
-release checker. Do not repeat a dependency-version survey for every release.
+Prepare dependencies whether or not the minimum changes:
 
-## 3. Write and commit the release note
+```sh
+go mod download
+```
 
-Create `docs/releases/<version>.md` for the selected version. Its first line
-must be `# ConfigKit <version>`. Give a meaningful summary and include
-compatibility impact or upgrade instructions when applicable. Link to current
-contracts for exact behavior. Review the note and affected canonical documents
-as ordinary preparation, then commit the complete candidate.
+Build the ReleaseKit version recorded in `go.mod` into temporary storage outside
+the checkout.
+Ensure `$TMPDIR` names a system temporary location, not the repository. These
+commands never install another ReleaseKit version:
 
-End every new note with these links, replacing `VERSION` with the complete tag:
+```sh
+releasekit_tmp=$(mktemp -d "${TMPDIR:-/tmp}/configkit-releasekit.XXXXXX")
+releasekit_bin="$releasekit_tmp/releasekit"
+go build -o "$releasekit_bin" gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit
+go list -m gitea.maximumdirect.net/eric/ReleaseKit
+"$releasekit_bin" version
+```
+
+This repository selects ReleaseKit v0.4.2. Use the compiled program above for
+publication so its exit status and publication report reach you unchanged.
+`go run` maps a nonzero child exit status to 1. ReleaseKit's child Go commands
+use the `go` found on `PATH` with `GOTOOLCHAIN=local`; keep the selected
+executable first on `PATH` through the publication command.
+
+Verify access to the authoritative remote without displaying credentials:
+
+```sh
+git ls-remote ssh://git@forge.maximumdirect.net:22222/base-layer/configkit.git HEAD refs/heads/main
+```
+
+Publication requires explicit authorization. Local implementation commits do
+not authorize a push or release.
+
+## 2. Prepare and commit the candidate
+
+Choose a stable version that has not been used locally or on the publication
+remote. Compare the candidate with the previous tag. Review public Go APIs and
+value ownership, YAML and resolution rules, diagnostic contracts, the minimum
+Go version, and platform support. Review maintained consumer examples and the
+migration guidance. Explain any consumer-minimum increase and required consumer
+action under the
+[consumer minimum policy](policy/release.md#consumer-minimum-and-release-toolchain).
+
+Create `docs/releases/<version>.md`. Its first line must be exactly
+`# ConfigKit <version>`, and it must end with the license and attribution footer:
 
 ```markdown
-[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/VERSION/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/VERSION/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/VERSION/docs/oss/attribution.md)
+[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/tag/VERSION/COPYRIGHT) | [LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/tag/VERSION/LICENSE) | [ATTRIBUTION](https://forge.maximumdirect.net/base-layer/configkit/src/tag/VERSION/docs/oss/attribution.md)
 ```
 
-Confirm the three target files exist in the candidate and review the version in
-the URLs. The future tag need not resolve remotely yet; this review adds no
-network gate. ConfigKit uses checked-in notes without hosted release objects.
-If a hosted page is used later, reuse the note and preserve its footer. Do not
-rewrite historical notes or add downloadable license assets.
+Replace `VERSION` with the full tag and confirm the three target files exist in
+the candidate. Retire completed roadmaps, preserve unfinished and deferred
+work, and repair affected links. Review the complete candidate for unintended
+files and credentials, then commit it on `main`. These are ordinary preparation
+tasks, not separate approval gates. Any `go.mod` change belongs in this
+candidate.
+
+## 3. Push the candidate to `main`
+
+Push only that committed candidate to the literal authoritative URL. This does
+not follow local tags:
+
+```sh
+git push --no-follow-tags ssh://git@forge.maximumdirect.net:22222/base-layer/configkit.git HEAD:refs/heads/main
+```
+
+ReleaseKit requires authoritative `main` to equal this candidate before it
+validates. A failure before this push means ReleaseKit publication has not
+started. If the push result is uncertain, inspect authoritative `main` and
+continue only when it is confirmed at the candidate. If validation later fails,
+no release tag is published; correct the issue in a new commit, push the new
+candidate to `main`, and invoke validation again.
 
 ## 4. Publish the committed candidate
 
-Before publication, review compatibility, release-note accuracy, and the file
-list for unintended content or credentials. Retire completed roadmaps as part of
-release preparation, preserving unfinished and deferred work and repairing
-links. These are ordinary preparation tasks, not separate human sign-offs.
-
-With the release explicitly authorized, run the one publication command.
-The script resolves the repository root from its own path, so it may be invoked
-from another directory by using its path there. Replace the sample version with
-the selected version:
+Once publication is authorized and the candidate is on the publication remote's
+`main`, run the compiled ReleaseKit program once to validate and publish it:
 
 ```sh
-./scripts/release.sh v0.5.0
+"$releasekit_bin" publish vMAJOR.MINOR.PATCH
 ```
 
-The command requires `main`, a clean index/worktree, an unused version locally
-and on the authoritative remote, and a matching note in the captured commit.
-Ignored local files do not block it. It checks remote ancestry, runs
-[`release-check.sh`](../scripts/release-check.sh) once against that commit,
-rechecks candidate and version state, pushes only that commit to `main`, then
-creates and pushes one annotated tag. The tag message is the checked-in note.
-It never commits or repairs the checkout.
-
-A successful intended tag push completes publication. The command reports the
-version and commit immediately. No CI, module retrieval, remote read-back, or
-hosted release object is required. The checker may be run separately for
-diagnosis, but it is not a prerequisite: a fresh publication invocation
-validates its candidate once.
-
-## 5. Recover from a failed or uncertain push
-
-The command performs one bounded authoritative-state check after a failed push.
-If the main push failed but authoritative main equals the candidate, it proceeds.
-If the tag push failed but its exact tag object reached the remote, it reports
-success. Otherwise it reports branch-only, conflicting, or unknown state and
-retains any local tag.
-
-Inspect exact refs before any retry. Set `release_version` to the attempted
-version and compare main with the candidate from the command's report:
+Replace the placeholder with the selected version. ReleaseKit checks the
+push URL Git will actually use, after URL rewrites, against `expected_push_url`.
+It verifies the candidate on
+`main`, and checks the release-note H1 for the product and version. It then
+runs the selected race-enabled standard suite once with test-time vet disabled,
+one full vet pass, and CGO-disabled package compilation for Linux amd64 and
+arm64. It publishes only the annotated tag for that candidate. Confirmed
+publication of the intended tag completes the release. The tag points to the
+captured commit and uses the complete checked-in note as its annotation message.
+Use the optional `check` command for diagnosis when useful. It validates without
+publishing and is not required before `publish`, which performs its own checks:
 
 ```sh
-release_version=v0.5.0
-authoritative=https://gitea.maximumdirect.net/eric/ConfigKit.git
-if remote_main=$(git ls-remote --refs --exit-code "$authoritative" refs/heads/main); then
-  printf 'remote main: %s\n' "$remote_main"
-else
-  result=$?
-  if [ "$result" -eq 2 ]; then
-    printf 'authoritative main confirmed absent\n' >&2
-  else
-    printf 'remote main state unknown; inspect before retrying\n' >&2
-  fi
-fi
-ref="refs/tags/$release_version"
-if remote_tag=$(git ls-remote --refs --exit-code "$authoritative" "$ref"); then
-  printf 'remote tag: %s\n' "$remote_tag"
-else
-  result=$?
-  if [ "$result" -eq 2 ]; then
-    printf 'remote tag confirmed absent\n'
-  else
-    printf 'remote tag state unknown; do not reuse the version\n' >&2
-  fi
-fi
-if local_tag=$(git rev-parse --verify "refs/tags/$release_version" 2>/dev/null); then
-  printf 'local tag object: %s\n' "$local_tag"
-else
-  printf 'no local tag object\n'
-fi
+"$releasekit_bin" check vMAJOR.MINOR.PATCH
 ```
 
-A query failure is not proof that the tag is absent. Compare the remote tag
-object ID with the local annotated tag object ID; its peeled commit alone is
-insufficient to establish identical publication. A conflicting published tag
-must not be moved or replaced. If remote main advanced but the tag was not
-published, report that partial progress. Only after confirming the local tag
-was never published or used by another channel may a maintainer remove it:
+For `publish`, interpret the program's exit status as follows:
+
+| Status | Meaning | Next action |
+| --- | --- | --- |
+| `0` | Publication succeeded. | The release is complete. Optional verification can follow. |
+| `1` | A known publication failure or conflict was reported. | Read the report and correct the stated problem. Preserve any published tag. |
+| `2` | The command, profile, or version is invalid. | Correct the command or configuration before trying again. |
+| `3` | The tag push outcome is still unknown. | Follow the recovery procedure below before retrying or declaring success. |
+
+Keep both the program's exit status and its diagnostic report. Using `go run`
+would lose the distinction between its nonzero exit statuses.
+
+The command does not push or repair `main`, wait for CI, or publish binaries or
+a hosted release page. A successful intended-tag publication does not require
+remote read-back or consumer retrieval; those checks remain optional.
+
+## 5. Recover from a failed or uncertain tag push
+
+The executable reports the publication state, phase, version, candidate commit,
+tag-object ID, effective endpoint, and error on standard error. After a failed
+tag push, it makes one bounded check of the exact publication remote to find out
+whether the tag arrived. Exit status 3
+means the tag outcome remains unknown; do not blindly retry or move a tag.
+
+An annotated tag is a Git object containing the release note and a pointer to
+the source commit. Its tag-object ID identifies that complete object. Checking
+only the commit ID would not establish that the intended tag object arrived.
+
+For an uncertain result, use the exact endpoint (remote URL), candidate commit,
+version, and tag-object ID from the report. Copy the captured endpoint into the variable
+below using normal shell quoting. Check that Git still resolves it to itself,
+then query the authoritative refs once:
+
+```sh
+authoritative='COPY_CAPTURED_ENDPOINT'
+release_version='vMAJOR.MINOR.PATCH'
+test "$(git ls-remote --get-url -- "$authoritative")" = "$authoritative" &&
+  git ls-remote --refs -- "$authoritative" refs/heads/main "refs/tags/$release_version"
+```
+
+A failed URL-equality check or remote query leaves the outcome unresolved.
+Correct transport configuration before continuing; a rewritten destination
+cannot establish absence at the captured endpoint.
+
+Compare the `main` object ID with the reported candidate commit and the tag
+object ID with the reported tag-object ID. `--refs` returns the annotated tag
+object itself. A peeled commit is the source commit reached by following that
+tag; it is a different identity. If the tag object matches, the
+release is published. If the query fails, the result is conflicting, or the
+endpoint or candidate differs, stop and resolve the state before retrying. If
+the endpoint is reachable, the tag is confirmed absent, and `main` still equals
+the reported candidate, remove a retained local tag only after confirming it
+was not published or used by another channel; then rerun `publish`, which
+revalidates the candidate:
 
 ```sh
 git tag -d "$release_version"
+"$releasekit_bin" publish "$release_version"
 ```
 
-A subsequent invocation revalidates the candidate; a correctly published tag
-needs no rerun. Do not roll back main or automatically delete a tag. Transport
-or authentication failure alone does not require a new version. A defect in
-published source requires a corrected commit, a new semantically appropriate
-version and note, and the release procedure again.
+A validation failure after the candidate reached `main` leaves an untagged
+candidate there. Correct it with a new commit rather than rewriting or rolling
+back `main`. A conflicting published tag must never be moved or reused. A
+defect in published source requires a corrected commit, a new semantically
+appropriate version, and a matching release note.
 
 ## 6. Optional consumer verification
 
-Only when useful or requested, read back the remote tag or retrieve the exact
-version into a new module without a local `replace` directive. These checks
-are optional and non-gating. Do not poll CI or wait for module propagation.
-Private-host credentials must already be configured. For direct-origin
-verification, set the version to the release just published (replace the sample
-below), then use a temporary consumer module and check the exact module path
-and version reported by `go list -m`:
+When useful or requested, read back the remote tag or retrieve the exact
+version into a new module without a local `replace` directive. These checks are
+optional and non-gating. Do not poll CI or wait for module propagation. For
+direct-origin verification, use the exact published version in a temporary
+consumer module:
 
 ```sh
-release_version=v0.5.0
+release_version=vMAJOR.MINOR.PATCH
 consumer_dir=$(mktemp -d)
 (
   cd "$consumer_dir"
   go mod init example.invalid/configkit-release-check
-  GOPRIVATE=gitea.maximumdirect.net GOPROXY=direct go get "gitea.maximumdirect.net/eric/ConfigKit@$release_version"
-  go list -m -f '{{.Path}} {{.Version}}' gitea.maximumdirect.net/eric/ConfigKit
+  GOWORK=off GOPROXY=direct go get "go.maximumdirect.net/configkit@$release_version"
+  GOWORK=off go list -m -f '{{.Path}} {{.Version}}' go.maximumdirect.net/configkit
 )
 ```
 

docs/releases/v0.10.0.md

@@ -0,0 +1,77 @@
+# ConfigKit v0.10.0
+
+This minor release adds explicit, composable discovery of a configuration file.
+Applications choose the search conventions and their order; ConfigKit selects one
+file during loading and returns the final configuration with its normal metadata.
+Optional searches that find no file share the expanded `NoSource()` lifecycle.
+
+## Changes
+
+- Add `SearchConfig`, immutable `Search` and `FilenameGroup` descriptions, and
+  search-wide requiredness through `SearchOptions`. Compose explicit `Paths`,
+  custom `SearchDirectory` descriptions, and built-in Unix system, user-config,
+  home, or working-directory presets with `Searches`. See the
+  [public declarations](../../discovery.go) and
+  [discovery contract](../config.md#configuration-discovery).
+- Expand searches in supplied order, trying a directory's filename groups before
+  moving to the next directory. Named and generic groups provide conventional
+  YAML filenames; custom groups provide literal names. Directory searches
+  distinguish omitted filename selection from an explicitly empty selection.
+  Constructors perform no filesystem access, and each load observes current
+  directory bases and file availability.
+- Select the first existing candidate. Access errors and failures while loading
+  the selected file terminate the load rather than trying another configuration.
+  Selected files retain physical source identity, placement, provenance, imports,
+  and relative-resource context. Discovery works with ordinary loading and
+  layered inputs, including underlays, without adding a precedence tier.
+- Permit enabled imports with an absent main input: there are no main import
+  declarations to traverse, while actual underlay sources retain normal imports.
+  Support ordinary selected overlays with an absent main and explicit filesystem
+  context, including a root-only host context. Layered overlays retain their
+  independent `OverlayFilesystem` requirement. See
+  [single-source loading](../config.md#single-source-loading) and
+  [layered loading](../config.md#layered-loading).
+- Preserve ordinary file-context behavior after discovery and include the
+  failing candidate's file identity in access diagnostics. Use Go's
+  platform-aware Windows component rules and native drive-root-relative path
+  resolution. Isolate user-config tests according to the host Go conventions.
+
+## Compatibility and upgrade
+
+Existing explicit source constructors and loading APIs remain available.
+`File(path)` remains an exclusive selection that fails for a missing file;
+discovery is activated only by explicitly supplying `SearchConfig`.
+
+Searches are optional by default. Set `SearchOptions{Required: true}` when the
+application must find a file. An exhausted optional search contributes no main
+document or source record; application version checks, defaults, resolution,
+and validation still run under their existing rules and may reject incomplete
+configuration. A selected overlay is still required to exist.
+
+The former `NoSource()` rejections of enabled imports and explicit filesystem
+context are relaxed. An active ordinary overlay with no main file now loads
+when explicit context is supplied. Applications that relied on those combinations
+being rejected should review their option handling. Selected host files derive
+their own base directory; do not supply an explicit `BaseDir` or native filesystem
+context for a search that selects a host file.
+
+Applications may replace their own fallback-loading loops with the new search
+descriptions. The maintained [consumer examples](../consumers/README.md#explicit-main-file-discovery)
+show simple preset selection and custom-first discovery alongside existing
+configuration tiers. Composition, collection operations, inheritance, CLI
+precedence, and the complete-on-return ownership model retain their existing
+semantics.
+
+Select this version and rebuild:
+
+```sh
+go get gitea.maximumdirect.net/eric/ConfigKit@v0.10.0
+```
+
+The consumer minimum remains Go 1.26.0. Release validation uses Go 1.26.10.
+The YAML dependency remains `go.yaml.in/yaml/v4 v4.0.0-rc.6`, and the maintainer
+tool remains ReleaseKit v0.4.1. Linux amd64 and arm64 remain release-validated
+targets; macOS remains best-effort. Publication follows the existing
+[release procedure](../release.md).
+
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.10.0/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.10.0/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.10.0/docs/oss/attribution.md)

docs/releases/v0.10.1.md

@@ -0,0 +1,42 @@
+# ConfigKit v0.10.1
+
+This patch release consolidates ConfigKit's internal loading machinery and
+reduces repeated import bookkeeping. Public APIs and configuration semantics
+remain unchanged from v0.10.0.
+
+## Changes
+
+- Consolidate ordinary and layered input acquisition, including import requests
+  and selected-overlay handling, while retaining their distinct context and
+  precedence rules. Remove unused private reverse conversions.
+- Separate import acquisition, scoped composition, and evidence projection;
+  clarify inheritance preparation, combination, and finalization; and simplify
+  reflective projection and schema-field assembly responsibilities.
+- Retain resolved filesystem facts from non-import validation for later passive
+  resource contexts and ordinary overlays. Remove duplicate absent-host context
+  derivation while preserving validation timing and handle cleanup.
+- Record empty optional-import selections directly against their declaring
+  source, avoiding repeated searches through acquired sources. Index import
+  dependencies for scope-local edge preparation instead of scanning the whole
+  inclusion graph for every item scope. Stable dependency-ready ordering,
+  provenance, and source destinations are preserved.
+- Expand regression coverage for import evidence ownership, scope boundaries,
+  and broad main/underlay item imports. Improve
+  [consumer loading guidance](../consumers/README.md) and internal documentation.
+
+## Compatibility and upgrade
+
+No consumer code or configuration migration is required. Composition, collection
+operations, inheritance, discovery, CLI precedence, source-version checks, and
+inspection retain their existing contracts.
+
+Select this version and rebuild:
+
+```sh
+go get gitea.maximumdirect.net/eric/ConfigKit@v0.10.1
+```
+
+The consumer minimum remains Go 1.26.0. Dependencies and platform support are
+unchanged. Publication follows the existing [release procedure](../release.md).
+
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.10.1/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.10.1/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.10.1/docs/oss/attribution.md)

docs/releases/v0.10.2.md

@@ -0,0 +1,70 @@
+# ConfigKit v0.10.2
+
+This patch release fixes edge-case loading failures, resource cleanup, and limit
+accounting, and simplifies ConfigKit's internal loading machinery. Public APIs
+and documented configuration semantics remain unchanged from v0.10.1.
+
+## Fixes
+
+- Terminate pointer-only recursive type traversal safely during decoding and
+  schema-path resolution, preserving nullable values and supported recursive
+  structures. Roll back failed dynamic descriptor construction so subsequent
+  operations do not reuse incomplete state or panic.
+- Accept finite, non-cyclic slice views that share backing storage while
+  retaining cycle detection and detached output.
+- Deactivate resolution, validation, and version-check contexts when callbacks
+  panic, and close library-owned import roots during panic unwinding. The
+  original application panic continues to propagate.
+- Report directory enumeration and close failures instead of treating them as
+  optional absence, including failures reported as not-exist after a successful
+  open. Genuinely missing optional directories retain their existing behavior.
+- Reuse completed symlink dependencies during host and native import discovery,
+  avoiding exponential repeated expansion of finite link graphs while retaining
+  cycle detection and containment checks.
+- Check existing projection budgets before bulk container allocation and account
+  for the complete retained inspection-history graph, including replay and
+  separately copied inheritance evidence.
+- Apply the documented append/upsert sequence requirements to non-sequence
+  contributions at retained collection-policy destinations.
+
+## Internal improvements
+
+- Index collection-policy retirement and prepare sparse incoming policy changes
+  instead of repeatedly scanning or copying unrelated retained policy.
+- Reuse successful dynamic-type eligibility checks within an operation and index
+  tier-history lookups, compound identity restoration, and secret-failure source
+  attribution to avoid repeated scans.
+- Remove unused snapshots, evidence, helpers, fields, and test-only production
+  paths. Clarify acquisition handoffs and separate collection preparation,
+  application, and finalization while sharing sequence-history construction.
+- Separate patterned glob entry preparation from traversal. Consolidate engine
+  import defaults, snapshot them during load preflight, and construct placement
+  directly across the facade while keeping public types root-owned.
+- Add regression coverage for the corrected failures, public historical paths,
+  defaults snapshots, and resource ownership. Strengthen fuzz detachment checks
+  and replace redundant or implementation-coupled assertions.
+- Update release tooling from ReleaseKit v0.4.1 to v0.4.2.
+
+These changes remove redundant work and improve scaling in the identified paths;
+no end-to-end performance improvement has been quantified.
+
+## Compatibility and upgrade
+
+No consumer API or configuration-format migration is required. The
+[configuration contract](../config.md) remains authoritative.
+
+Loads that previously succeeded despite directory acquisition failures, invalid
+append/upsert contributions, or incomplete retained-history accounting may now
+return the documented structured errors. These corrections enforce existing
+requirements and limits rather than introducing new ones.
+
+Select this version and rebuild:
+
+```sh
+go get gitea.maximumdirect.net/eric/ConfigKit@v0.10.2
+```
+
+The consumer minimum remains Go 1.26.0. The YAML dependency and platform support
+are unchanged. Publication follows the existing [release procedure](../release.md).
+
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.10.2/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.10.2/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.10.2/docs/oss/attribution.md)

docs/releases/v0.6.0.md

@@ -0,0 +1,63 @@
+# ConfigKit v0.6.0
+
+This minor release reduces avoidable configuration-loading and inspection work,
+adopts ReleaseKit for source publication, and raises the consumer Go minimum to
+1.26.0. The public configuration model remains unchanged from v0.5.0.
+
+## Changes
+
+- Reduce temporary path allocations by sizing pointer-formatting buffers,
+  combining final metadata traversal, reusing parsed sensitivity paths, and
+  avoiding path construction when detecting inheritance. Effective and
+  historical metadata indexes retain independently owned paths.
+- Replace repeated resolution-coverage, metadata-update, CLI-overlap, and
+  sensitivity-propagation scans with private indexes and incremental processing.
+  Preserve diagnostic ordering, history, contextual path shapes, and redaction.
+- Make presence-only metadata queries avoid materializing provenance. Prepare
+  resolution replay descriptors and immutable mapping and inheritance-history
+  lookups for inspection, and use ordered membership indexes for provenance
+  collections. Returned records remain detached; explanations still replay
+  complete trees and render on demand.
+- Add a maintained public-API startup construction benchmark. The initial path
+  formatting and metadata traversal experiments reproduced allocation reductions
+  across local and downstream workloads. Later algorithmic improvements were
+  validated behaviorally without a new benchmark campaign. Busy-host timings
+  were inconclusive; no fixed speedup or allocation threshold is promised.
+- Replace ConfigKit-owned release scripts with a small profile and the
+  module-selected ReleaseKit v0.3.0 tool. The
+  [release procedure](../release.md) documents candidate preparation, tag-only
+  publication, and failed-push recovery. Existing release checks and the
+  successful-tag-push completion point remain unchanged; CI is not a gate.
+- Adopt release policy 1.6, distinguishing the consumer Go minimum from the
+  validation toolchain. Retire completed planning and measurement records into
+  Git history while preserving [performance candidates](../roadmap/future.md#5-performance-experiments).
+
+## Compatibility and upgrade
+
+The consumer minimum increases from Go 1.25.0 to **Go 1.26.0**. Install Go 1.26.0
+or newer before upgrading, and update application build and CI environments that
+still use Go 1.25. The `go.mod` directive records the consumer minimum; using a
+newer validation patch does not itself raise that minimum. See the
+[consumer minimum policy](../policy/release.md#consumer-minimum-and-release-toolchain).
+
+Select this version and rebuild:
+
+```sh
+go get gitea.maximumdirect.net/eric/ConfigKit@v0.6.0
+```
+
+No application-code or configuration migration is required from v0.5.0. Public
+Go signatures, strict within-tier composition, recursive tier precedence,
+sibling inheritance, presence/null distinctions, provenance, secret handling,
+and synchronous completion retain their existing contracts. See the
+[configuration contract](../config.md) and
+[consumer guide](../consumers/README.md).
+
+The YAML dependency remains `go.yaml.in/yaml/v4 v4.0.0-rc.6`. ReleaseKit is a
+declared Go tool dependency for maintainer commands, not a library runtime
+import; its requirements participate in ConfigKit's module graph. Linux amd64
+and arm64 remain release-validated targets, and macOS remains best-effort.
+Maintainers should use the current release procedure instead of the retired
+`scripts/release.sh` and `scripts/release-check.sh` commands.
+
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.6.0/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.6.0/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.6.0/docs/oss/attribution.md)

docs/releases/v0.7.0.md

@@ -0,0 +1,58 @@
+# ConfigKit v0.7.0
+
+This minor release adds structured comparison of completed configurations.
+Applications can inspect changes between two configuration files or the
+effective impact of a selected overlay, with ConfigKit handling comparison and
+safe value disclosure while applications own presentation.
+
+## Changes
+
+- Add `Diff[T](left, right *Result[T]) ([]Difference, error)` through the public
+  facade. It compares frozen effective inspection values from successful loads,
+  including defaults and recorded application resolution, rather than source
+  text or later mutations of `Result.Config`.
+- Return detached changed-region records containing a semantic path, safe left
+  and right `ValueSnapshot` values, and `HiddenChanged`. Mappings compare
+  recursively, sequences report atomic changes, and records follow canonical
+  pointer order. Presence distinguishes additions and removals from explicit
+  null; equal effective values produce no records regardless of provenance or
+  loading history.
+- Protect both snapshots with sensitivity from both loads, including historical
+  and dependency-derived classification. Compatible regions retain public
+  siblings; incompatible structural replacements use complete-region masking
+  where required. `HiddenChanged` identifies actual changes withheld by masking,
+  rather than merely indicating that a snapshot contains redacted content.
+- Preserve visible public scalar changes when only historical sensitive
+  descendants remain, including additions and removals. Historical explanation
+  redaction and masking of incompatible present shapes remain intact.
+- Add maintained file-comparison and base-versus-overlay examples with
+  consumer-owned formatting, plus an executable public API example. See the
+  [consumer guide](../consumers/README.md#effective-configuration-diffs) and
+  [configuration contract](../config.md#effective-configuration-diffs).
+
+## Compatibility and upgrade
+
+No application-code or configuration migration is required from v0.6.0.
+Adopting the new API is optional. Loading, composition, inheritance, provenance,
+existing inspection, and secret-handling contracts remain unchanged.
+
+Load both configurations successfully before calling `Diff`; nil or
+uninitialized results return an error with no records. Comparison does not
+reopen sources, rerun callbacks, or reread environment variables. Typed secret
+references compare by configured reference name, not resolved credential bytes,
+so credential rotation behind an unchanged name is not reported. Returned
+snapshots describe changed regions, not cross-protected full-document context.
+
+Select this version and rebuild:
+
+```sh
+go get gitea.maximumdirect.net/eric/ConfigKit@v0.7.0
+```
+
+The consumer minimum remains Go 1.26.0. The YAML dependency remains
+`go.yaml.in/yaml/v4 v4.0.0-rc.6`, and the maintainer tool dependency remains
+ReleaseKit v0.3.0. Linux amd64 and arm64 remain release-validated targets;
+macOS remains best-effort. Publication follows the existing
+[release procedure](../release.md).
+
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.0/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.0/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.0/docs/oss/attribution.md)

docs/releases/v0.7.1.md

@@ -0,0 +1,22 @@
+# ConfigKit v0.7.1
+
+This patch updates the maintainer release tool to ReleaseKit v0.4.1. ConfigKit's
+runtime behavior and public API are unchanged.
+
+## Compatibility and upgrade
+
+No application-code or configuration migration is required from v0.7.0. The
+consumer minimum remains Go 1.26.0, and the YAML dependency is unchanged.
+
+Select this version and rebuild:
+
+```sh
+go get gitea.maximumdirect.net/eric/ConfigKit@v0.7.1
+```
+
+ReleaseKit v0.4.1 is a maintainer tool dependency and does not change consumer
+configuration or runtime behavior. Linux amd64 and arm64 remain
+release-validated targets; macOS remains best-effort. Publication follows the
+existing [release procedure](../release.md).
+
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.1/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.1/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.1/docs/oss/attribution.md)

docs/releases/v0.8.0.md

@@ -0,0 +1,70 @@
+# ConfigKit v0.8.0
+
+This minor release adds explicit input placement, relative import destinations,
+shared source-version checking, and opt-in composition of identified sequence
+records. Applications can assemble independently authored configuration fragments
+into one final configuration while retaining source locations, provenance,
+history, and sensitivity information.
+
+## Changes
+
+- Add `Destination` to ordinary load options and layered inputs. A source mapping
+  can contribute beneath literal application keys without being rewritten by the
+  consumer. Imports inherit that destination or append a relative YAML
+  `destination`. Physical import paths and resource contexts remain relative to
+  their declaring sources. See [input destinations](../config.md#input-destinations),
+  [import syntax](../config.md#explicit-imports), and the
+  [mounted collection example](../consumers/README.md#input-destinations-and-mounted-collections).
+- Add `SourceVersionModeIfPresent` and `SourceVersionModeRequired` to apply one
+  application-owned version checker across main, underlay, imported, and selected
+  overlay documents. Enabled modes check source-local declarations and consume
+  accepted non-main headers before composition. Detached, sensitivity-aware
+  evidence is available through `SourceInfo.VersionCheck`. Acceptance remains
+  application policy; ConfigKit does not require declarations to equal the main
+  version. See [shared source-version checks](../config.md#shared-source-version-checks).
+- Add explicit `PlacementModeSequenceItem` placement for ordinary and layered
+  inputs, and `placement: sequence-item` for path and glob imports. A source
+  mapping becomes one item at its destination; ordinary helper imports compose
+  within that item and can supply its identity. See
+  [imports](../config.md#explicit-imports).
+- Add `Definition.SequenceCompositions` registrations for strict composition at
+  selected literal paths using one string identity field. Distinct records append
+  in contribution order, while duplicate identities conflict. Higher-priority
+  sequences still replace lower-priority sequences wholesale. Registration does
+  not add identity-based overlays or final identity validation after defaults and
+  application resolution. See the [composition contract](../config.md#strict-document-composition)
+  and [maintained prompt catalog](../consumers/README.md#identified-prompt-sequences).
+- Extend source inspection with destination and placement evidence, including
+  whether a nested destination is unresolved in an intermediate or failed-load
+  snapshot. Preserve source-specific history, consumed-header sensitivity, and
+  explanations of descendants removed by sequence replacement as records are
+  assembled. Source locations continue to identify authored coordinates.
+
+## Compatibility and upgrade
+
+The new behavior is opt-in: zero-valued destinations retain root placement,
+mapping placement remains the default, unregistered sequences retain strict
+conflict behavior, and the default source-version mode preserves the existing
+main-only version policy. Recursive mapping precedence, whole-sequence
+replacement between tiers, and application-owned final validation remain intact.
+
+Public option, definition, input, and source-information structs gain fields.
+Consumers using unkeyed literals for affected structs must switch to keyed
+literals or update them. `SourceInfo` now contains a `Path` and is no longer
+comparable with `==` or usable directly as a map key; compare the relevant fields
+or select an application-appropriate key instead. Existing keyed literals need
+no changes to retain the previous loading behavior.
+
+Select this version and rebuild:
+
+```sh
+go get gitea.maximumdirect.net/eric/ConfigKit@v0.8.0
+```
+
+The consumer minimum remains Go 1.26.0. The YAML dependency remains
+`go.yaml.in/yaml/v4 v4.0.0-rc.6`, and the maintainer tool dependency remains
+ReleaseKit v0.4.1. Linux amd64 and arm64 remain release-validated targets;
+macOS remains best-effort. Publication follows the existing
+[release procedure](../release.md).
+
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.8.0/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.8.0/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.8.0/docs/oss/attribution.md)

docs/releases/v0.9.0.md

@@ -0,0 +1,111 @@
+# ConfigKit v0.9.0
+
+This minor release expands import selection, adds author-declared collection
+identity and operations, and supports inheritance between identified records.
+It also moves CLI assignments after inheritance and typed decoding. These changes
+include breaking API and configuration behavior changes from v0.8.0; review the
+migration guidance below before upgrading.
+
+## Changes
+
+- Extend imports with named-file and directory lists, directory filename patterns,
+  exclusions, recursion and depth controls, and explicit hidden-file and symlink
+  discovery controls. Add `ImportDefaults` to ordinary and layered options, with
+  authored declarations taking precedence over application defaults. Imports are
+  optional by default. `SourceInfo.ImportSelections` exposes completed optional
+  declarations that selected no sources. See the
+  [import contract](../config.md#explicit-imports) and
+  [consumer guidance](../consumers/README.md#import-defaults-and-selection-inspection).
+- Use shared dependency-ready ordering for import composition and sibling
+  inheritance. Dependencies complete before dependents, with deterministic
+  selection among currently eligible contributions. Source acquisition and
+  callback order remain separate from assembly order. See the
+  [ordering decision](../adr/0015-shared-dependency-ready-ordering.md).
+- Add root `configkit.sequences` declarations for collection identity and
+  `replace`, `append`, or `upsert` operations, including in selected overlays.
+  Strict peers combine distinct identities and reject duplicates; precedence
+  and inheritance apply the destination's collection operation. Upsert replaces
+  a whole matching record at its retained position. Identity supports compound
+  field sets and scalar strings, numbers, booleans, and null. See the
+  [collection contract](../config.md#strict-document-composition).
+- Add `Definition.SequenceIdentities`, exact `SequenceIdentityAt` registrations,
+  and dynamic `SequenceIdentityMatching` selectors. Application registrations
+  govern structural collection operations and check existing matching final
+  typed sequences, including values from defaults, CLI assignments, and
+  application resolution. YAML-only declarations govern structural operations
+  without adding that final-result check.
+- Support record inheritance within an identified sequence using an `extends`
+  mapping containing the parent's complete identity. The child retains its own
+  identity, relationships use surviving assembled records, and output sequence
+  order is preserved. See [sibling inheritance](../config.md#sibling-inheritance)
+  and the maintained [sequence catalog](../consumers/README.md#identified-prompt-sequences).
+- Apply explicit CLI overrides to the decoded configuration before application
+  resolution. Mappings retain omitted fields and their presence metadata;
+  sequences replace whole lists independently of collection operations. See the
+  [CLI contract](../config.md#explicit-cli-overrides).
+- Correct native import alias and contained-symlink handling, source-version
+  path projection, and provenance/history through collection movement,
+  replacement, inheritance, and CLI assignment. Reduce repeated scans,
+  accumulated policy copying, and sparse-projection storage during construction.
+
+## Compatibility and upgrade
+
+This pre-v1 minor release intentionally changes the v0.8.0 contracts:
+
+1. **Migrate import requiredness.** The YAML `optional` field is removed and is
+   rejected. Replace `optional: true` with `required: false`; omission is equivalent
+   when the application does not default imports to required. Replace
+   `optional: false` with `required: true`. Imports that previously relied on
+   implicit requiredness now need `required: true`, or an application
+   `ImportDefaults.Required` default set to true. Review discovery filters:
+   `follow` and `hidden` default to true, and directory searches select all
+   filenames unless a pattern is supplied.
+2. **Replace sequence registrations.** `SequenceComposition` and
+   `Definition.SequenceCompositions` are removed without compatibility aliases.
+   For a previous registration at `prompts` using `id`, use:
+
+   ```go
+   rules.SequenceIdentities = []configkit.SequenceIdentity{
+       configkit.SequenceIdentityAt(configkit.Keys("prompts"), "id"),
+   }
+   ```
+
+   These registrations now also enforce identity in final typed sequences. Fix
+   missing or duplicate identities introduced by defaults, CLI assignments, or
+   application resolution. Registration does not require a collection to exist
+   or determine its allowed shape; schema and application validation retain
+   those responsibilities.
+3. **Review collection precedence and ordering.** An identified collection now
+   defaults to upsert across layers and inheritance when no explicit mode
+   applies, rather than unconditional whole-sequence replacement. Declare
+   `mode: replace` at the relevant destination where replacement is intended.
+   With append or upsert, `[]` contributes no records and does not clear the
+   collection; null is invalid. Use `mode: replace` with `[]` to clear it.
+   An explicit mode persists at its destination until changed; a parent's mode
+   does not transfer to a different inheriting destination. Unidentified
+   sequences retain strict peer conflicts and whole-value precedence
+   replacement. Dependency-ready assembly can change sequence positions and
+   diagnostic or history order compared with the former traversal order.
+4. **Review CLI recovery and inheritance assumptions.** CLI overrides can no
+   longer repair values that fail earlier decoding, bypass source or inheritance
+   errors, or add or cancel inheritance relationships. Supply structural
+   directives in source configuration. Application resolution still receives
+   explicit CLI values and may record subsequent normalization or derivation.
+5. **Update affected Go literals and diagnostic handling.** Use keyed literals
+   for expanded option and source-information structs. Collection validation adds
+   `CodeSequenceInvalid` (`sequence.invalid`) and `CodeSequenceConflict`
+   (`sequence.conflict`); update diagnostic handling where applicable.
+
+Select this version and rebuild:
+
+```sh
+go get gitea.maximumdirect.net/eric/ConfigKit@v0.9.0
+```
+
+The consumer minimum remains Go 1.26.0. The YAML dependency remains
+`go.yaml.in/yaml/v4 v4.0.0-rc.6`, and the maintainer tool dependency remains
+ReleaseKit v0.4.1. Linux amd64 and arm64 remain release-validated targets;
+macOS remains best-effort. Publication follows the existing
+[release procedure](../release.md).
+
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.9.0/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.9.0/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.9.0/docs/oss/attribution.md)

docs/roadmap/deferred.md

@@ -1,34 +0,0 @@
-# Deferred Scope
-
-This document owns intentionally excluded features, not a committed delivery plan.
-The [architecture policy](../policy/architecture.md) governs changes to these
-boundaries. Implemented behavior belongs in the [configuration contract](../config.md)
-and consumer adoption in the [consumer guide](../consumers/README.md).
-
-## Explicit non-goals and deferred scope
-
-General environment-variable configuration overlays are not supported. Typed secret
-references and explicit directory bootstrap are the environment convention. Literal
-credential configuration and implicit secret-directory discovery are unsupported.
-
-The following remain deliberately excluded:
-
-- automatic `conf.d` discovery;
-- remote imports, arbitrary providers, and additional configuration formats;
-- custom merge strategies, sequence merging, reset operators, multiple-parent
-  inheritance, and cross-scope references;
-- named overlay inheritance;
-- parser-specific or custom structural-decoding extension APIs;
-- generic dynamic-subtree conversion and module-registry APIs;
-- automatic schema migrations;
-- hot reload, runtime resource replacement, and remote resource validation;
-- a bundled CLI framework or application commands; and
-- configuration diffs and fingerprints.
-
-Applications may build their own validate, effective-value, source, bootstrap, and
-explanation commands around the library. Broadening these boundaries requires
-concrete consumer evidence, compatibility review, and an explicit design change.
-
-Built-in sibling inheritance using `extends` is implemented as described in the
-[configuration contract](../config.md#sibling-inheritance). It is distinct from
-inheritance between selected overlay files, which remains excluded above.

docs/roadmap/future.md

@@ -0,0 +1,104 @@
+# Potential Future Work
+
+This document lists potential enhancements and maintenance work for consideration
+in future ConfigKit releases. Entries are not accepted contracts, implementation
+plans, or release commitments. Adopting a candidate requires an explicit design
+decision and a separate plan. Significant architectural exclusions and their rationale belong
+in ADRs; this document does not maintain a list of rejected proposals.
+
+## 3. Recursive body merging for identified records
+
+Status: deferred. The implemented
+[collection policy](../config.md#strict-document-composition) uses `upsert` to
+replace a complete matched record. Recursive merging of fields inside matching
+records remains a separate candidate and would revisit the whole-record update
+boundary selected by [ADR 0017](../adr/0017-collection-sequence-policy.md).
+
+Consider this only in response to a concrete consumer need. A proposal would need
+to define conflicts for overlapping body fields, removal of omitted fields,
+presence and ordering, and how provenance, history, sensitivity, and resource
+context follow partially retained records. Any change requires a new decision and
+implementation plan; this entry does not alter current upsert behavior.
+
+## 4. Required version declarations for selected sources
+
+Status: deferred. PromptKit requested a way to require version declarations on
+a selected subset of source files while permitting other fragments to omit them.
+
+### Motivation and proposed behavior
+
+PromptKit could require each collection's root file (for example,
+`collection.yml` or `meta.yml`, with naming still undecided) to declare an
+accepted specification version. Other files would use the existing
+[check-when-present behavior](../config.md#shared-source-version-checks).
+This would enforce a rule that otherwise remains a documentation convention.
+
+All declarations would use the same application-owned `Definition.Version`
+path and acceptance policy. The proposal concerns where declarations are
+required; it does not introduce independently versioned collections or subtrees.
+A root declaration would not prove that headerless descendants declare a
+compatible version or replace final configuration validation.
+
+### Questions to resolve before implementation
+
+- **Selection API:** should callers mark explicit inputs, select sources by
+  path or predicate, or annotate imports? An input-level requirement is simpler,
+  but cannot by itself select a root reached only through an import.
+- **Scope:** does a requirement apply only to the selected document or also to
+  its imports? Applying it only to that document best fits PromptKit's request;
+  imported fragments could still declare versions checked by the shared policy.
+- **Mode interaction:** how should selection interact with disabled source
+  checks? Require an enabled mode, or activate checking for selected sources?
+  Selection would strengthen check-when-present behavior and add no requirement
+  beyond the load-wide required mode.
+- **Source handling and evidence:** how should selection work across file,
+  reader, byte, and mapping inputs, glob matches, and repeated imports? Define
+  behavior for absent optional inputs and preserve source-local diagnostics,
+  inspection evidence, and existing sensitivity handling.
+
+## 5. Performance experiments
+
+Status: deferred pending evidence. The completed performance audit identified
+four internal optimization candidates for separate investigation:
+
+- Branch-local explanation replay instead of the current whole-tree replay.
+- Redesigning the private metadata-copy handoff while preserving detached public
+  records.
+- Caching schema descriptors across loads.
+- Indexing complex contributor-trace membership while preserving its equality
+  rules and compact linked traces.
+
+These are experiments, not committed implementation work or promised speedups.
+Reconsider them with evidence that the benefit justifies the ownership,
+retained-memory, or equivalence risks. The completed audit and implementation
+evidence are preserved in Git history at `8e91a2b` under `docs/roadmap/`.
+
+### Questions to resolve before implementation
+
+- Which representative workloads show enough remaining cost to justify each
+  optimization, and what measurements would establish a useful improvement?
+- Can narrower replay and membership indexes preserve explanation results,
+  ordering, provenance, and sensitivity behavior?
+- Can metadata handoff changes preserve detached public records and ownership
+  across loads without introducing aliasing?
+- What cache lifetime and concurrency design would make schema reuse worthwhile
+  without excessive retained memory?
+
+## 6. Public path comparison
+
+Status: deferred pending a concrete consumer need. This preserves A2 from the
+completed API review at `68400ff:docs/roadmap/review.md`.
+
+`Path.String()` is a JSON Pointer spelling, not a complete semantic identity:
+an explicit numeric mapping key and a sequence index can share it. The public
+type is opaque and currently non-comparable.
+
+If consumers need comparison, consider a small exact-representation operation
+rather than exposing mutable segments or introducing a pattern language. A
+proposal must distinguish exact segment representation, including parsed versus
+explicit segments and invalid state, from resolution against a document. Pointer
+string equality must not be presented as semantic equality.
+
+Keeping `Path` solely as an opaque query/building value remains an alternative.
+No current contract changes or implementation commitment follow from this entry;
+a comparison operation can be added compatibly later.

example_test.go

@@ -6,7 +6,7 @@ import (
 	"os"
 	"strings"
 
-	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	configkit "go.maximumdirect.net/configkit"
 )
 
 func ExampleLoad() {
@@ -19,6 +19,28 @@ func ExampleLoad() {
 	// Output: {true 3} <nil>
 }
 
+func ExampleLoad_sequenceDeclaration() {
+	type Item struct {
+		ID string `yaml:"id"`
+	}
+	type Config struct {
+		Items []Item `yaml:"items"`
+	}
+	result, err := configkit.Load[Config](configkit.Bytes("catalog.yml", []byte(`configkit:
+  sequences:
+    - destination: [items]
+      key: id
+items:
+  - id: prompt
+`)))
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	fmt.Println(result.Config.Items[0].ID)
+	// Output: prompt
+}
+
 func ExampleNoSource() {
 	type Config struct {
 		Workers int `yaml:"workers"`
@@ -30,6 +52,32 @@ func ExampleNoSource() {
 	// Output: 4 0 <nil>
 }
 
+func ExampleDiff() {
+	type Config struct {
+		Workers int `yaml:"workers"`
+	}
+	before, err := configkit.Load[Config](configkit.Mapping("before", map[string]any{"workers": 2}))
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	after, err := configkit.Load[Config](configkit.Mapping("after", map[string]any{"workers": 4}))
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	differences, err := configkit.Diff(before, after)
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	for _, difference := range differences {
+		fmt.Printf("%s: %s -> %s\n", difference.Path.String(),
+			strings.TrimSpace(difference.Left.YAML), strings.TrimSpace(difference.Right.YAML))
+	}
+	// Output: /workers: 2 -> 4
+}
+
 func ExampleValidation_Error() {
 	type Config struct {
 		First  string `yaml:"first"`
@@ -128,10 +176,18 @@ func ExampleOverride() {
 		})
 	}
 	result, err := configkit.Load(configkit.NoSource(), configkit.Options[Config]{
-		Definition: configkit.Definition[Config]{Defaults: func() Config { return Config{Workers: 4} }},
-		Overrides:  overrides,
+		Definition: configkit.Definition[Config]{
+			Defaults: func() Config { return Config{Workers: 4} },
+			Resolve: func(configuration *Config, resolution *configkit.Resolution) error {
+				configkit.Default(resolution, configkit.Keys("workers"), &configuration.Workers, 100,
+					"preserve an explicitly supplied worker count")
+				return nil
+			},
+		},
+		Overrides: overrides,
 	})
-	fmt.Println(result.Config.Workers, result.Sources()[0].Label, err)
+	source, _ := result.Source("source-1")
+	fmt.Println(result.Config.Workers, source.Label, err)
 	// Output: 0 --workers <nil>
 }
 

examples/consumers/consumers.go

@@ -9,7 +9,7 @@ import (
 	"strings"
 	"time"
 
-	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	configkit "go.maximumdirect.net/configkit"
 )
 
 // Artifact is a Narratio-shaped generated output declaration.
@@ -167,7 +167,7 @@ func LoadNotariusPaths(path, invocationDir string, overrides ...configkit.Overri
 				resolveNotariusReference(configuration, resolution, invocationDir)
 				return nil
 			},
-			Secret: func(path configkit.Path) bool { return path.String() == "/sensitive" },
+			Sensitive: func(path configkit.Path) bool { return path.String() == "/sensitive" },
 		},
 	})
 }
@@ -177,7 +177,7 @@ func resolveNotariusReference(configuration *NotariusPathConfig, resolution *con
 	if configuration.Reference == "" || filepath.IsAbs(configuration.Reference) {
 		return
 	}
-	info, found := resolution.InputInfo(path)
+	info, found := resolution.EntryInfo(path)
 	if !found {
 		resolution.Warning(path, "relative reference has no entry provenance")
 		return

examples/consumers/consumers_test.go

@@ -11,8 +11,8 @@ import (
 	"strings"
 	"testing"
 
-	configkit "gitea.maximumdirect.net/eric/ConfigKit"
-	"gitea.maximumdirect.net/eric/ConfigKit/examples/consumers"
+	configkit "go.maximumdirect.net/configkit"
+	"go.maximumdirect.net/configkit/examples/consumers"
 )
 
 func Example_narratio() {
@@ -82,7 +82,7 @@ func Example_weatherStartup() {
 	defer os.RemoveAll(directory)
 	_ = os.WriteFile(filepath.Join(directory, blockedName), []byte("unused-example-value\n"), 0o600)
 	_ = os.WriteFile(filepath.Join(directory, tokenName), []byte("disposable-example-credential\n"), 0o600)
-	report, bootstrapErr := configkit.LoadSecretsDir(directory)
+	report, bootstrapErr := configkit.LoadSecretsIntoEnvironment(directory)
 	var reportOutput bytes.Buffer
 	_, reportWriteErr := report.WriteTo(&reportOutput)
 

examples/consumers/destinations.go

@@ -0,0 +1,154 @@
+package consumers
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"path"
+
+	configkit "go.maximumdirect.net/configkit"
+)
+
+// CollectionBundleConfig is a representative application-owned collection
+// shape. Collection and prompt version labels remain ordinary domain fields.
+type CollectionBundleConfig struct {
+	Version     string                          `yaml:"version"`
+	Collections map[string]CollectionDefinition `yaml:"collections"`
+}
+
+type CollectionDefinition struct {
+	Name        string                       `yaml:"name"`
+	Version     string                       `yaml:"version"`
+	Description string                       `yaml:"description"`
+	Prompts     map[string]CollectionPrompt  `yaml:"prompts"`
+	Profiles    map[string]CollectionProfile `yaml:"profiles"`
+}
+
+type CollectionPrompt struct {
+	Version        string              `yaml:"version"`
+	DefaultProfile string              `yaml:"default_profile"`
+	ContentFile    string              `yaml:"content_file"`
+	ResourceText   string              `yaml:"resource_text"`
+	Messages       []CollectionMessage `yaml:"messages"`
+}
+
+type CollectionMessage struct {
+	Role    string `yaml:"role"`
+	Content string `yaml:"content"`
+}
+
+type CollectionProfile struct {
+	Format      string  `yaml:"format"`
+	Temperature float64 `yaml:"temperature"`
+}
+
+// LoadCollectionBundle demonstrates one layered collection load. Its main
+// document owns the application schema version; the mounted entry declares
+// relative destinations for collection metadata, prompt/profile peers, and
+// their nested imports. The operator version override remains a separate tier.
+func LoadCollectionBundle() (*configkit.Result[CollectionBundleConfig], error) {
+	files, err := fs.Sub(bundledFiles, "testdata/collection-bundle")
+	if err != nil {
+		return nil, err
+	}
+	bundle := configkit.NewFilesystem("collection bundle", files)
+	collectionDestination := configkit.Keys("collections", "weatherreporter")
+	promptDestination := collectionDestination.Key("prompts")
+	return configkit.LoadLayered(
+		configkit.Input{Source: configkit.Bytes("application main", []byte("version: 1\n"))},
+		configkit.LayeredOptions[CollectionBundleConfig]{
+			Definition: configkit.Definition[CollectionBundleConfig]{
+				Version: &configkit.VersionRule{Path: configkit.Keys("version"), Check: func(version configkit.Version, _ *configkit.Validation) error {
+					if !version.Present || version.Text != "1" {
+						return errors.New("unsupported application schema version")
+					}
+					return nil
+				}},
+				Resolve:  resolveCollectionResources,
+				Validate: validateCollectionBundle,
+			},
+			Underlays: []configkit.Underlay{
+				{Inputs: []configkit.Input{{
+					Source: bundle.File("collections/weather/collection.yml"), Imports: true, Destination: collectionDestination,
+				}}},
+				{Inputs: []configkit.Input{{
+					Source: bundle.File("operators/weather-prompt-version.yml"), Destination: promptDestination,
+				}}},
+			},
+		},
+	)
+}
+
+func resolveCollectionResources(configuration *CollectionBundleConfig, resolution *configkit.Resolution) error {
+	for collectionID, collection := range configuration.Collections {
+		for promptID, prompt := range collection.Prompts {
+			if prompt.ContentFile == "" {
+				continue
+			}
+			contentPath := configkit.Keys("collections", collectionID, "prompts", promptID, "content_file")
+			info, found := resolution.EntryInfo(contentPath)
+			if !found || len(info.Origin.Locations) != 1 {
+				return fmt.Errorf("prompt resource has no single declaring source")
+			}
+			resourceSource, found := resolution.Source(info.Origin.Locations[0].SourceID)
+			if !found {
+				return fmt.Errorf("prompt resource source is unavailable")
+			}
+			context, found := resolution.SourceContext(resourceSource.ID)
+			if !found {
+				return fmt.Errorf("prompt resource context is unavailable")
+			}
+			data, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, prompt.ContentFile))
+			if err != nil {
+				return fmt.Errorf("read prompt resource: %w", err)
+			}
+			prompt.ResourceText = string(data)
+			collection.Prompts[promptID] = prompt
+			resolution.RecordNormalization(
+				configkit.Keys("collections", collectionID, "prompts", promptID, "resource_text"),
+				"read source-relative prompt content", contentPath,
+			)
+		}
+		configuration.Collections[collectionID] = collection
+	}
+	return nil
+}
+
+func validateCollectionBundle(configuration *CollectionBundleConfig, validation *configkit.Validation) {
+	for collectionID, collection := range configuration.Collections {
+		for promptID, prompt := range collection.Prompts {
+			if prompt.DefaultProfile == "" {
+				continue
+			}
+			if _, found := collection.Profiles[prompt.DefaultProfile]; !found {
+				validation.Error(configkit.Keys("collections", collectionID, "prompts", promptID, "default_profile"), "must name a profile in this collection")
+			}
+		}
+	}
+}
+
+// ReadCollectionPromptContent follows the effective content field's physical
+// source, including when it was inherited from a peer prompt.
+func ReadCollectionPromptContent(result *configkit.Result[CollectionBundleConfig], collectionID, promptID string) (string, error) {
+	if result == nil {
+		return "", errors.New("collection result is nil")
+	}
+	contentPath := configkit.Keys("collections", collectionID, "prompts", promptID, "content_file")
+	info, found := result.Metadata().Lookup(contentPath)
+	if !found || len(info.Origin.Locations) != 1 {
+		return "", errors.New("prompt resource has no single declaring source")
+	}
+	context, found := result.SourceContext(info.Origin.Locations[0].SourceID)
+	if !found {
+		return "", errors.New("prompt resource context is unavailable")
+	}
+	prompt, found := result.Config.Collections[collectionID].Prompts[promptID]
+	if !found {
+		return "", errors.New("prompt is unavailable")
+	}
+	data, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, prompt.ContentFile))
+	if err != nil {
+		return "", err
+	}
+	return string(data), nil
+}

examples/consumers/destinations_test.go

@@ -0,0 +1,137 @@
+package consumers_test
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+
+	configkit "go.maximumdirect.net/configkit"
+	"go.maximumdirect.net/configkit/examples/consumers"
+)
+
+func Example_inputDestination() {
+	mounted, err := configkit.LoadLayered[map[string]any](configkit.Input{
+		Source: configkit.Mapping("weather prompt", map[string]any{
+			"summarize.alerts": map[string]any{"version": "1"},
+		}),
+		Destination: configkit.Keys("collections", "weather.reporter", "prompts"),
+	})
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	root, err := configkit.LoadLayered[map[string]any](configkit.Input{
+		Source: configkit.Bytes("standalone", []byte("name: standalone\n")),
+	})
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	_, found := mounted.Config["collections"]
+	fmt.Println(found, root.Config["name"])
+	// Output: true standalone
+}
+
+func TestCollectionBundleAssemblesMountedPeersAndResources(t *testing.T) {
+	result, err := consumers.LoadCollectionBundle()
+	if err != nil {
+		t.Fatalf("LoadCollectionBundle: %v", err)
+	}
+	collection := result.Config.Collections["weatherreporter"]
+	if result.Config.Version != "1" || collection.Name != "Weather Reporter" || collection.Version != "2.4.0" {
+		t.Fatalf("main and collection versions = %q, %#v", result.Config.Version, collection)
+	}
+	brief := collection.Prompts["brief"]
+	custom := collection.Prompts["custom"]
+	if brief.Version != "2" || brief.DefaultProfile != "compact" || brief.ContentFile != "welcome.txt" || len(brief.Messages) != 1 {
+		t.Fatalf("version-only override replaced lower prompt fields: %#v", brief)
+	}
+	if custom.Version != "2" || custom.DefaultProfile != "weather" || custom.ContentFile != brief.ContentFile ||
+		len(custom.Messages) != 1 || custom.ResourceText != "Welcome to the weather collection.\n" {
+		t.Fatalf("inherited prompt = %#v", custom)
+	}
+	weatherProfile := collection.Profiles["weather"]
+	if weatherProfile.Format != "text" || weatherProfile.Temperature != 0.4 {
+		t.Fatalf("inherited profile = %#v", weatherProfile)
+	}
+	resource, err := consumers.ReadCollectionPromptContent(result, "weatherreporter", "custom")
+	if err != nil || resource != custom.ResourceText {
+		t.Fatalf("inherited prompt resource = %q, %v", resource, err)
+	}
+
+	versionInfo, ok := result.Metadata().Lookup(configkit.Keys("version"))
+	if !ok || !versionInfo.Explicit || versionInfo.Origin.Layer != configkit.LayerMain || len(versionInfo.Origin.Locations) != 1 {
+		t.Fatalf("main-owned version metadata = %#v, %v", versionInfo, ok)
+	}
+	collectionVersionPath := configkit.Keys("collections", "weatherreporter", "version")
+	collectionVersion, ok := result.Metadata().Lookup(collectionVersionPath)
+	if !ok || !collectionVersion.Explicit || collectionVersion.Origin.Layer != configkit.LayerUnderlay || len(collectionVersion.Origin.Locations) != 1 {
+		t.Fatalf("ordinary collection version metadata = %#v, %v", collectionVersion, ok)
+	}
+	var metadataSource configkit.SourceInfo
+	var collectionEntrySource configkit.SourceInfo
+	var versionSource configkit.SourceInfo
+	var parentPromptSource configkit.SourceInfo
+	var promptIndexSource configkit.SourceInfo
+	var profileIndexSource configkit.SourceInfo
+	var promptVersionSource configkit.SourceInfo
+	for _, source := range result.Sources() {
+		switch source.Path {
+		case "collections/weather/collection.yml":
+			collectionEntrySource = source
+		case "collections/weather/metadata.yml":
+			metadataSource = source
+		case "collections/weather/version.yml":
+			versionSource = source
+		case "collections/weather/prompts/index.yml":
+			promptIndexSource = source
+		case "collections/weather/prompts/brief.yml":
+			parentPromptSource = source
+		case "collections/weather/profiles/index.yml":
+			profileIndexSource = source
+		case "operators/weather-prompt-version.yml":
+			promptVersionSource = source
+		}
+	}
+	collectionVersionLocation := collectionVersion.Origin.Locations[0]
+	if collectionEntrySource.ID != "source-2" || collectionEntrySource.Destination.String() != "/collections/weatherreporter" ||
+		metadataSource.ID == "" || metadataSource.Destination.String() != "/collections/weatherreporter" ||
+		metadataSource.ImportedFrom == nil || metadataSource.ImportedFrom.SourceID != collectionEntrySource.ID ||
+		versionSource.ID == "" || collectionVersionLocation.SourceID != versionSource.ID || versionSource.Destination.String() != "/collections/weatherreporter" ||
+		versionSource.ImportedFrom == nil || versionSource.ImportedFrom.SourceID != metadataSource.ID || collectionVersionLocation.Line != 1 {
+		t.Fatalf("nested collection version provenance = entry %#v, metadata %#v, version %#v, location %#v", collectionEntrySource, metadataSource, versionSource, collectionVersionLocation)
+	}
+	if promptIndexSource.ID == "" || promptIndexSource.Destination.String() != "/collections/weatherreporter/prompts" ||
+		promptIndexSource.ImportedFrom == nil || promptIndexSource.ImportedFrom.SourceID != collectionEntrySource.ID ||
+		profileIndexSource.ID == "" || profileIndexSource.Destination.String() != "/collections/weatherreporter/profiles" ||
+		profileIndexSource.ImportedFrom == nil || profileIndexSource.ImportedFrom.SourceID != collectionEntrySource.ID {
+		t.Fatalf("nested prompt/profile placement = prompt %#v profile %#v", promptIndexSource, profileIndexSource)
+	}
+	if promptVersionSource.ID == "" || promptVersionSource.Destination.String() != "/collections/weatherreporter/prompts" || promptVersionSource.UnderlayIndex != 2 {
+		t.Fatalf("prompt version source = %#v", promptVersionSource)
+	}
+	contentPath := configkit.Keys("collections", "weatherreporter", "prompts", "custom", "content_file")
+	contentInfo, ok := result.Metadata().Lookup(contentPath)
+	if !ok || !contentInfo.Explicit || len(contentInfo.Origin.Inheritance) != 1 || len(contentInfo.Origin.Locations) != 1 {
+		t.Fatalf("inherited content field metadata = %#v, %v", contentInfo, ok)
+	}
+	contentLocation := contentInfo.Origin.Locations[0]
+	if parentPromptSource.ID == "" || contentLocation.SourceID != parentPromptSource.ID || contentLocation.Line != 4 ||
+		parentPromptSource.Destination.String() != "/collections/weatherreporter/prompts" {
+		t.Fatalf("inherited resource source coordinates = %#v, source %#v", contentLocation, parentPromptSource)
+	}
+}
+
+func TestCollectionPeerPromptConflictsRemainStrict(t *testing.T) {
+	destination := configkit.Keys("collections", "weatherreporter", "prompts")
+	_, err := configkit.LoadLayered[map[string]any](configkit.Input{Source: configkit.NoSource()}, configkit.LayeredOptions[map[string]any]{
+		Underlays: []configkit.Underlay{{Inputs: []configkit.Input{
+			{Source: configkit.Bytes("peer-a", []byte("brief: {version: '1'}\n")), Destination: destination},
+			{Source: configkit.Bytes("peer-b", []byte("brief: {version: '1'}\n")), Destination: destination},
+		}}},
+	})
+	var loadError *configkit.LoadError
+	if !errors.As(err, &loadError) || len(loadError.Diagnostics()) == 0 || loadError.Diagnostics()[0].Code != configkit.CodeComposeConflict {
+		t.Fatalf("duplicate peer prompt error = %v", err)
+	}
+}

examples/consumers/diff.go

@@ -0,0 +1,136 @@
+package consumers
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+
+	configkit "go.maximumdirect.net/configkit"
+)
+
+// FileComparisonConfig is a small application-owned shape for comparing
+// caller-selected configuration files.
+type FileComparisonConfig struct {
+	Name    string         `yaml:"name"`
+	Entries map[string]any `yaml:"entries"`
+}
+
+// CompareFiles loads two caller-selected files with the same application
+// definition, then formats only the safe records returned by configkit.Diff.
+func CompareFiles(leftPath, rightPath string) (string, error) {
+	options := configkit.Options[FileComparisonConfig]{
+		Definition: configkit.Definition[FileComparisonConfig]{
+			Defaults: func() FileComparisonConfig {
+				return FileComparisonConfig{Entries: map[string]any{}}
+			},
+		},
+	}
+	left, err := configkit.Load(configkit.File(leftPath), options)
+	if err != nil {
+		return "", fmt.Errorf("load left configuration: %w", err)
+	}
+	right, err := configkit.Load(configkit.File(rightPath), options)
+	if err != nil {
+		return "", fmt.Errorf("load right configuration: %w", err)
+	}
+	differences, err := configkit.Diff(left, right)
+	if err != nil {
+		return "", err
+	}
+	return FormatDifferences(differences), nil
+}
+
+// RolloutConfig models a service endpoint whose URL is derived by the
+// application resolver and whose credential reference is classified.
+type RolloutConfig struct {
+	Service RolloutService `yaml:"service"`
+}
+
+// RolloutService contains endpoint settings and a classified credential.
+type RolloutService struct {
+	Endpoint   RolloutEndpoint   `yaml:"endpoint"`
+	Credential RolloutCredential `yaml:"credential"`
+}
+
+// RolloutEndpoint is the effective destination used by the application.
+type RolloutEndpoint struct {
+	Host string `yaml:"host"`
+	Port int    `yaml:"port"`
+	URL  string `yaml:"url"`
+}
+
+// RolloutCredential holds only a typed secret reference in configuration.
+type RolloutCredential struct {
+	Token configkit.Secret `yaml:"token" configkit:"secret"`
+}
+
+// LoadRollout loads a base file, optionally with one selected configuration
+// overlay. Resolution derives the effective URL after the overlay is applied.
+func LoadRollout(basePath, overlayName string) (*configkit.Result[RolloutConfig], error) {
+	return configkit.Load(configkit.File(basePath), configkit.Options[RolloutConfig]{
+		Overlay: overlayName,
+		Definition: configkit.Definition[RolloutConfig]{
+			Resolve: resolveRollout,
+		},
+	})
+}
+
+// CompareRolloutOverlay compares the effective base configuration with that
+// same file plus one selected overlay. It presents only safe diff records.
+func CompareRolloutOverlay(basePath, overlayName string) (string, error) {
+	base, err := LoadRollout(basePath, "")
+	if err != nil {
+		return "", fmt.Errorf("load base configuration: %w", err)
+	}
+	withOverlay, err := LoadRollout(basePath, overlayName)
+	if err != nil {
+		return "", fmt.Errorf("load overlay configuration: %w", err)
+	}
+	differences, err := configkit.Diff(base, withOverlay)
+	if err != nil {
+		return "", err
+	}
+	return FormatDifferences(differences), nil
+}
+
+func resolveRollout(configuration *RolloutConfig, resolution *configkit.Resolution) error {
+	endpoint := &configuration.Service.Endpoint
+	if endpoint.Host == "" || endpoint.Port <= 0 {
+		return nil
+	}
+	url := fmt.Sprintf("https://%s:%d", endpoint.Host, endpoint.Port)
+	if endpoint.URL != url {
+		endpoint.URL = url
+		resolution.RecordNormalization(configkit.Keys("service", "endpoint", "url"),
+			"derived endpoint URL",
+			configkit.Keys("service", "endpoint", "host"),
+			configkit.Keys("service", "endpoint", "port"))
+	}
+	return nil
+}
+
+// FormatDifferences is consumer-owned presentation. It distinguishes absence
+// through Present and reports withheld changes through HiddenChanged without
+// interpreting redaction marker text.
+func FormatDifferences(differences []configkit.Difference) string {
+	if len(differences) == 0 {
+		return "No effective changes.\n"
+	}
+	var output strings.Builder
+	for _, difference := range differences {
+		fmt.Fprintf(&output, "%s: left=%s right=%s", difference.Path.String(),
+			formatSnapshot(difference.Left), formatSnapshot(difference.Right))
+		if difference.HiddenChanged {
+			output.WriteString(" hidden-change")
+		}
+		output.WriteByte('\n')
+	}
+	return output.String()
+}
+
+func formatSnapshot(snapshot configkit.ValueSnapshot) string {
+	if !snapshot.Present {
+		return "<absent>"
+	}
+	return strconv.Quote(snapshot.YAML)
+}

examples/consumers/diff_test.go

@@ -0,0 +1,187 @@
+package consumers_test
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	configkit "go.maximumdirect.net/configkit"
+	"go.maximumdirect.net/configkit/examples/consumers"
+)
+
+func ExampleCompareFiles() {
+	directory, err := os.MkdirTemp("", "configkit-diff-files-")
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	defer os.RemoveAll(directory)
+	leftPath := filepath.Join(directory, "before.yml")
+	rightPath := filepath.Join(directory, "after.yml")
+	if err := os.WriteFile(leftPath, []byte("name: before\nentries: {}\n"), 0o600); err != nil {
+		fmt.Println(err)
+		return
+	}
+	if err := os.WriteFile(rightPath, []byte("name: after\nentries:\n  added: null\n"), 0o600); err != nil {
+		fmt.Println(err)
+		return
+	}
+	output, err := consumers.CompareFiles(leftPath, rightPath)
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	fmt.Print(output)
+	// Output:
+	// /entries/added: left=<absent> right="null\n"
+	// /name: left="before\n" right="after\n"
+}
+
+func ExampleCompareRolloutOverlay() {
+	const baseToken = "CONFIGKIT_DIFF_EXAMPLE_BASE_TOKEN"
+	const overlayToken = "CONFIGKIT_DIFF_EXAMPLE_OVERLAY_TOKEN"
+	defer preserveEnvironment(baseToken)()
+	defer preserveEnvironment(overlayToken)()
+	_ = os.Setenv(baseToken, "disposable-example-base-credential")
+	_ = os.Setenv(overlayToken, "disposable-example-overlay-credential")
+
+	directory, err := os.MkdirTemp("", "configkit-diff-overlay-")
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	defer os.RemoveAll(directory)
+	basePath := filepath.Join(directory, "config.yml")
+	overlayPath := filepath.Join(directory, "overlays", "canary.yml")
+	if err := os.MkdirAll(filepath.Dir(overlayPath), 0o700); err != nil {
+		fmt.Println(err)
+		return
+	}
+	base := "service:\n  endpoint:\n    host: base.example\n    port: 8443\n  credential:\n    token: " + baseToken + "\n"
+	overlay := "service:\n  endpoint:\n    host: canary.example\n  credential:\n    token: " + overlayToken + "\n"
+	if err := os.WriteFile(basePath, []byte(base), 0o600); err != nil {
+		fmt.Println(err)
+		return
+	}
+	if err := os.WriteFile(overlayPath, []byte(overlay), 0o600); err != nil {
+		fmt.Println(err)
+		return
+	}
+	output, err := consumers.CompareRolloutOverlay(basePath, "canary")
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	fmt.Print(output)
+	// Output:
+	// /service/credential/token: left="'[REDACTED]'\n" right="'[REDACTED]'\n" hidden-change
+	// /service/endpoint/host: left="base.example\n" right="canary.example\n"
+	// /service/endpoint/url: left="https://base.example:8443\n" right="https://canary.example:8443\n"
+}
+
+func TestCompareFilesUsesCallerSelectedSourcesAndSafePresence(t *testing.T) {
+	directory := t.TempDir()
+	leftPath := filepath.Join(directory, "before.yml")
+	rightPath := filepath.Join(directory, "after.yml")
+	writeConfiguration(t, leftPath, "name: before\nentries: {}\n")
+	writeConfiguration(t, rightPath, "name: after\nentries:\n  added: null\n")
+
+	output, err := consumers.CompareFiles(leftPath, rightPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := "/entries/added: left=<absent> right=\"null\\n\"\n" +
+		"/name: left=\"before\\n\" right=\"after\\n\"\n"
+	if output != want {
+		t.Fatalf("comparison output = %q, want %q", output, want)
+	}
+	if again, err := consumers.CompareFiles(leftPath, rightPath); err != nil || again != output {
+		t.Fatalf("repeat output = %q, %v", again, err)
+	}
+}
+
+func TestCompareFilesReturnsEachLoadError(t *testing.T) {
+	directory := t.TempDir()
+	leftPath := filepath.Join(directory, "before.yml")
+	rightPath := filepath.Join(directory, "after.yml")
+	writeConfiguration(t, leftPath, "name: before\n")
+	writeConfiguration(t, rightPath, "unknown: invalid\n")
+
+	output, err := consumers.CompareFiles(leftPath, rightPath)
+	if err == nil || output != "" || !strings.Contains(err.Error(), "load right configuration") {
+		t.Fatalf("right load failure = %q, %v", output, err)
+	}
+	if _, err := consumers.CompareFiles(filepath.Join(directory, "missing.yml"), rightPath); err == nil || !strings.Contains(err.Error(), "load left configuration") {
+		t.Fatalf("left load failure = %v", err)
+	}
+}
+
+func TestCompareRolloutOverlayShowsResolvedSafeChangesAndRetainsSiblings(t *testing.T) {
+	t.Setenv("CONFIGKIT_DIFF_BASE_TOKEN", "disposable-base-credential")
+	t.Setenv("CONFIGKIT_DIFF_OVERLAY_TOKEN", "disposable-overlay-credential")
+	directory := t.TempDir()
+	basePath := filepath.Join(directory, "config.yml")
+	overlayPath := filepath.Join(directory, "overlays", "canary.yml")
+	if err := os.MkdirAll(filepath.Dir(overlayPath), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	writeConfiguration(t, basePath, "service:\n  endpoint:\n    host: base.example\n    port: 8443\n  credential:\n    token: CONFIGKIT_DIFF_BASE_TOKEN\n")
+	writeConfiguration(t, overlayPath, "service:\n  endpoint:\n    host: canary.example\n  credential:\n    token: CONFIGKIT_DIFF_OVERLAY_TOKEN\n")
+
+	base, err := consumers.LoadRollout(basePath, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	withOverlay, err := consumers.LoadRollout(basePath, "canary")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if base.Config.Service.Endpoint.Port != 8443 || withOverlay.Config.Service.Endpoint.Port != 8443 {
+		t.Fatalf("lower-priority port was not retained: base=%#v overlay=%#v", base.Config.Service.Endpoint, withOverlay.Config.Service.Endpoint)
+	}
+	urlInfo, found := withOverlay.Metadata().Lookup(configkit.Keys("service", "endpoint", "url"))
+	if !found || urlInfo.Origin.Layer != configkit.LayerResolution || withOverlay.Config.Service.Endpoint.URL != "https://canary.example:8443" {
+		t.Fatalf("resolved endpoint = %#v, metadata=%#v, %v", withOverlay.Config.Service.Endpoint, urlInfo, found)
+	}
+
+	differences, err := configkit.Diff(base, withOverlay)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(differences) != 3 {
+		t.Fatalf("differences = %#v", differences)
+	}
+	wantPaths := []string{"/service/credential/token", "/service/endpoint/host", "/service/endpoint/url"}
+	for index, difference := range differences {
+		if got := difference.Path.String(); got != wantPaths[index] {
+			t.Errorf("path[%d] = %q, want %q", index, got, wantPaths[index])
+		}
+	}
+	secret := differences[0]
+	if !secret.Left.Redacted || !secret.Right.Redacted || !secret.HiddenChanged || secret.Left.YAML != "'[REDACTED]'\n" || secret.Right.YAML != "'[REDACTED]'\n" {
+		t.Fatalf("classified credential difference = %#v", secret)
+	}
+	if strings.Contains(consumers.FormatDifferences(differences), "disposable-") {
+		t.Fatal("formatted differences exposed credential contents")
+	}
+
+	output, err := consumers.CompareRolloutOverlay(basePath, "canary")
+	if err != nil || output != consumers.FormatDifferences(differences) {
+		t.Fatalf("formatted base/overlay comparison = %q, %v", output, err)
+	}
+}
+
+func TestFormatDifferencesUsesRecordMembershipForNoChange(t *testing.T) {
+	if got := consumers.FormatDifferences(nil); got != "No effective changes.\n" {
+		t.Fatalf("no-change output = %q", got)
+	}
+}
+
+func writeConfiguration(t *testing.T, filename, contents string) {
+	t.Helper()
+	if err := os.WriteFile(filename, []byte(contents), 0o600); err != nil {
+		t.Fatal(err)
+	}
+}

examples/consumers/discovery_test.go

@@ -0,0 +1,46 @@
+package consumers_test
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	configkit "go.maximumdirect.net/configkit"
+)
+
+type workingDirectoryPresetConfig struct {
+	Name string `yaml:"name"`
+}
+
+func Example_workingDirectoryPreset() {
+	original, err := os.Getwd()
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	defer func() { _ = os.Chdir(original) }()
+	root, err := os.MkdirTemp("", "configkit-working-search-")
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	defer os.RemoveAll(root)
+	if err := os.Chdir(root); err != nil {
+		fmt.Println(err)
+		return
+	}
+	if err := os.WriteFile(filepath.Join(root, "service.yml"), []byte("name: example\n"), 0o600); err != nil {
+		fmt.Println(err)
+		return
+	}
+	result, err := configkit.Load[workingDirectoryPresetConfig](
+		configkit.SearchConfig("service", configkit.WorkingDirectory()),
+	)
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	source, _ := result.Source("source-1")
+	fmt.Println(result.Config.Name, filepath.Base(source.Path))
+	// Output: example service.yml
+}

examples/consumers/inheritance.go

@@ -1,6 +1,6 @@
 package consumers
 
-import configkit "gitea.maximumdirect.net/eric/ConfigKit"
+import configkit "go.maximumdirect.net/configkit"
 
 // PresetCatalog is ordinary application data; no inheritance fields or
 // registration hooks are required in the typed configuration.

examples/consumers/inheritance_test.go

@@ -3,8 +3,8 @@ package consumers_test
 import (
 	"testing"
 
-	configkit "gitea.maximumdirect.net/eric/ConfigKit"
-	"gitea.maximumdirect.net/eric/ConfigKit/examples/consumers"
+	configkit "go.maximumdirect.net/configkit"
+	"go.maximumdirect.net/configkit/examples/consumers"
 )
 
 func TestPresetCatalogOneLoadAndDerivation(t *testing.T) {

examples/consumers/layered.go

@@ -6,10 +6,10 @@ import (
 	"io/fs"
 	"path"
 
-	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	configkit "go.maximumdirect.net/configkit"
 )
 
-//go:embed testdata/native-source testdata/layered-bundle
+//go:embed testdata/native-source testdata/layered-bundle testdata/collection-bundle testdata/ordinary-imports testdata/source-version
 var bundledFiles embed.FS
 
 // BundledConfig is a small configuration loaded directly from an embedded file.
@@ -18,6 +18,30 @@ type BundledConfig struct {
 	Enabled bool   `yaml:"enabled"`
 }
 
+type PromptBundleConfig struct {
+	Name        string                  `yaml:"name"`
+	Version     string                  `yaml:"version"`
+	Description string                  `yaml:"description"`
+	Prompts     map[string]BundlePrompt `yaml:"prompts"`
+}
+
+type BundlePrompt struct {
+	Summary string `yaml:"summary"`
+}
+
+// LoadPromptBundle demonstrates ordinary Load with opt-in imports whose
+// destinations are declared relative to the entry document.
+func LoadPromptBundle() (*configkit.Result[PromptBundleConfig], error) {
+	files, err := fs.Sub(bundledFiles, "testdata/ordinary-imports")
+	if err != nil {
+		return nil, err
+	}
+	return configkit.Load[PromptBundleConfig](
+		configkit.NewFilesystem("prompt bundle", files).File("config.yml"),
+		configkit.Options[PromptBundleConfig]{Imports: true},
+	)
+}
+
 // LoadBundled demonstrates a native filesystem source without layered options.
 func LoadBundled() (*configkit.Result[BundledConfig], error) {
 	files, err := fs.Sub(bundledFiles, "testdata/native-source")

examples/consumers/layered_test.go

@@ -6,8 +6,8 @@ import (
 	"strings"
 	"testing"
 
-	configkit "gitea.maximumdirect.net/eric/ConfigKit"
-	"gitea.maximumdirect.net/eric/ConfigKit/examples/consumers"
+	configkit "go.maximumdirect.net/configkit"
+	"go.maximumdirect.net/configkit/examples/consumers"
 )
 
 func Example_nativeFilesystem() {
@@ -20,6 +20,34 @@ func Example_nativeFilesystem() {
 	// Output: embedded false
 }
 
+func Example_rootRelativeImports() {
+	result, err := consumers.LoadPromptBundle()
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	source, _ := result.Source("source-3")
+	fmt.Println(result.Config.Name, result.Config.Version, result.Config.Prompts["brief"].Summary, source.Destination.String(), err)
+	// Output: Root import example 1.0 A root-loaded prompt. /prompts <nil>
+}
+
+func TestPromptBundleUsesRelativeImportDestinations(t *testing.T) {
+	result, err := consumers.LoadPromptBundle()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Config.Name != "Root import example" || result.Config.Version != "1.0" || result.Config.Prompts["brief"].Summary != "A root-loaded prompt." {
+		t.Fatalf("root import result = %#v", result.Config)
+	}
+	sources := result.Sources()
+	if len(sources) != 3 || sources[0].Destination.String() != configkit.Keys().String() ||
+		sources[1].Path != "metadata.yml" || sources[1].Destination.String() != configkit.Keys().String() ||
+		sources[2].Path != "prompts/brief.yml" || sources[2].Destination.String() != "/prompts" ||
+		sources[2].ImportedFrom == nil || sources[2].ImportedFrom.SourceID != sources[0].ID {
+		t.Fatalf("root import sources = %#v", sources)
+	}
+}
+
 func Example_layeredCatalog() {
 	result, err := consumers.LoadCatalog(fixture("layered-main", "config.yml"))
 	if err != nil {
@@ -32,6 +60,58 @@ func Example_layeredCatalog() {
 	// Output: production false 0 bundle example Welcome from the bundle. <nil>
 }
 
+func Example_sourceVersionAdoption() {
+	result, err := consumers.LoadVersionedService(configkit.SourceVersionModeIfPresent)
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	checks, redacted := 0, true
+	for _, source := range result.Sources() {
+		if check := source.VersionEvidence; check != nil {
+			checks++
+			redacted = redacted && check.Redacted && check.Version.Text == ""
+		}
+	}
+	required, requiredErr := consumers.LoadVersionedService(configkit.SourceVersionModeRequired)
+	fmt.Println(result.Config.Service.Version, result.Config.Service.Metadata.Release,
+		checks, redacted, required != nil && requiredErr == nil)
+	// Output: service-v2 application-2026.10 2 true true
+}
+
+func TestVersionedServiceModesAndMountedProtection(t *testing.T) {
+	for _, mode := range []configkit.SourceVersionMode{
+		configkit.SourceVersionModeIfPresent,
+		configkit.SourceVersionModeRequired,
+	} {
+		result, err := consumers.LoadVersionedService(mode)
+		if err != nil || result == nil || result.Config.Service.Version != "service-v2" ||
+			result.Config.Service.Name != "example service" || result.Config.Service.Endpoint != "https://service.example.invalid" ||
+			result.Config.Service.Metadata.Release != "application-2026.10" {
+			t.Fatalf("versioned service mode %d = %#v, %v", mode, result, err)
+		}
+		sources := result.Sources()
+		if len(sources) != 2 {
+			t.Fatalf("versioned service sources = %#v", sources)
+		}
+		for _, source := range sources {
+			check := source.VersionEvidence
+			if check == nil || check.Path.String() != "/version" || !check.Version.Present ||
+				!check.Redacted || check.Version.Text != "" {
+				t.Fatalf("safe source version evidence = %#v", sources)
+			}
+		}
+	}
+	_, err := consumers.LoadVersionedService(configkit.SourceVersionModeIfPresent,
+		configkit.Override{Path: configkit.Keys("service", "version"), Value: "cli-v3", Flag: "--service-version"})
+	var loadError *configkit.LoadError
+	if !errors.As(err, &loadError) || len(loadError.Diagnostics()) != 1 ||
+		loadError.Diagnostics()[0].Code != configkit.CodeOverrideVersion ||
+		loadError.Diagnostics()[0].Path.String() != "/service/version" {
+		t.Fatalf("mounted main version override error = %v", err)
+	}
+}
+
 func TestCatalogRetainsPresenceAndSourceContext(t *testing.T) {
 	result, err := consumers.LoadCatalog(fixture("layered-main", "config.yml"))
 	if err != nil {
@@ -39,7 +119,7 @@ func TestCatalogRetainsPresenceAndSourceContext(t *testing.T) {
 	}
 	for _, key := range []string{"enabled", "workers"} {
 		info, found := result.Metadata().Lookup(configkit.Keys(key))
-		if !found || !info.Explicit || info.Origin.Layer != configkit.LayerBase {
+		if !found || !info.Explicit || info.Origin.Layer != configkit.LayerMain {
 			t.Fatalf("%s presence = %#v, %v", key, info, found)
 		}
 	}

examples/consumers/prompt_catalog.go

@@ -0,0 +1,67 @@
+package consumers
+
+import (
+	"strings"
+
+	configkit "go.maximumdirect.net/configkit"
+)
+
+// PromptCatalogConfig is an application-owned prompt collection shape.
+type PromptCatalogConfig struct {
+	Prompts []PromptRecord `yaml:"prompts"`
+}
+
+// PromptRecord keeps its identity and message meaning in the consumer.
+type PromptRecord struct {
+	ID       string   `yaml:"id"`
+	Name     string   `yaml:"name"`
+	Messages []string `yaml:"messages"`
+	Resource string   `yaml:"resource"`
+}
+
+// LoadPromptCatalog discovers explicitly registered prompt records in the main
+// tier and replaces the lower-priority default collection as a whole.
+func LoadPromptCatalog(mainPath string) (*configkit.Result[PromptCatalogConfig], error) {
+	return configkit.LoadLayered(configkit.Input{
+		Source:  configkit.File(mainPath),
+		Imports: true,
+	}, configkit.LayeredOptions[PromptCatalogConfig]{
+		Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{
+			Source: configkit.Bytes("default prompts", []byte("prompts:\n  - id: default\n    name: Default prompt\n    messages: [Default message]\n")),
+		}}}},
+		ImportDefaults: configkit.ImportDefaults{
+			Pattern: []string{"curated*.yml", "generated-*.yml"},
+		},
+		Definition: promptCatalogDefinition(),
+	})
+}
+
+// LoadRequiredPromptCatalog keeps the common one-file import shape small.
+func LoadRequiredPromptCatalog(mainPath string) (*configkit.Result[PromptCatalogConfig], error) {
+	return configkit.Load(configkit.File(mainPath), configkit.Options[PromptCatalogConfig]{
+		Imports: true, Definition: promptCatalogDefinition(),
+	})
+}
+
+func promptCatalogDefinition() configkit.Definition[PromptCatalogConfig] {
+	return configkit.Definition[PromptCatalogConfig]{
+		SequenceIdentities: []configkit.SequenceIdentity{
+			configkit.SequenceIdentityAt(configkit.Keys("prompts"), "id"),
+		},
+		Validate: validatePromptCatalog,
+	}
+}
+
+func validatePromptCatalog(configuration *PromptCatalogConfig, validation *configkit.Validation) {
+	for index, prompt := range configuration.Prompts {
+		if strings.TrimSpace(prompt.Name) == "" {
+			validation.Error(configkit.Keys("prompts").Index(index).Key("name"), "must not be empty")
+		}
+		if len(prompt.Messages) == 0 {
+			validation.Error(configkit.Keys("prompts").Index(index).Key("messages"), "must contain at least one message")
+		}
+	}
+	if len(configuration.Prompts) == 0 {
+		validation.Error(configkit.Keys("prompts"), "must contain at least one prompt")
+	}
+}

examples/consumers/prompt_catalog_test.go

@@ -0,0 +1,135 @@
+package consumers_test
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	pathpkg "path"
+	"path/filepath"
+	"testing"
+
+	configkit "go.maximumdirect.net/configkit"
+	"go.maximumdirect.net/configkit/examples/consumers"
+)
+
+func Example_identifiedPromptCatalog() {
+	result, err := consumers.LoadPromptCatalog(fixture("prompt-catalog", "config.yml"))
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	ids := make([]string, 0, len(result.Config.Prompts))
+	for _, prompt := range result.Config.Prompts {
+		ids = append(ids, prompt.ID)
+	}
+	emptySearches := 0
+	for _, source := range result.Sources() {
+		for _, selection := range source.EmptyImportSelections {
+			if selection.Selector == configkit.ImportSelectorDirectory {
+				emptySearches++
+			}
+		}
+	}
+	fmt.Println(ids, emptySearches, err)
+	// Output: [weather curated welcome main] 1 <nil>
+}
+
+func Example_requiredPromptCatalog() {
+	result, err := consumers.LoadRequiredPromptCatalog(fixture("prompt-catalog", "simple.yml"))
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	fmt.Println(result.Config.Prompts[0].ID, err)
+	// Output: required <nil>
+}
+
+func TestPromptCatalogImportsRegisteredItemsAndReplacesDefaults(t *testing.T) {
+	result, err := consumers.LoadPromptCatalog(fixture("prompt-catalog", "config.yml"))
+	if err != nil {
+		var loadError *configkit.LoadError
+		if errors.As(err, &loadError) {
+			t.Fatalf("load prompt catalog: %v (%#v)", err, loadError.Diagnostics())
+		}
+		t.Fatal(err)
+	}
+	if len(result.Config.Prompts) != 4 {
+		t.Fatalf("prompt records = %#v", result.Config.Prompts)
+	}
+	ids := []string{"weather", "curated", "welcome", "main"}
+	for index, id := range ids {
+		if result.Config.Prompts[index].ID != id {
+			t.Fatalf("prompt %d ID = %q, want %q", index, result.Config.Prompts[index].ID, id)
+		}
+	}
+	for _, prompt := range result.Config.Prompts {
+		if prompt.ID == "default" {
+			t.Fatalf("lower-priority default survived main sequence replacement: %#v", result.Config.Prompts)
+		}
+		if prompt.ID == "ignored" {
+			t.Fatalf("excluded generated prompt was selected: %#v", result.Config.Prompts)
+		}
+	}
+
+	var itemImports, helperImports int
+	for _, source := range result.Sources() {
+		switch filepath.Base(source.Path) {
+		case "curated.yml", "weather-feature.yml", "generated-welcome.yml":
+			if source.PlacementMode != configkit.PlacementModeSequenceItem || source.Destination.String() != "/prompts" {
+				t.Fatalf("item source placement = %#v", source)
+			}
+			itemImports++
+		case "curated-id.yml":
+			if source.PlacementMode != configkit.PlacementModeMapping || source.ImportedFrom == nil {
+				t.Fatalf("helper source = %#v", source)
+			}
+			helperImports++
+		}
+	}
+	if itemImports != 3 || helperImports != 1 {
+		t.Fatalf("item imports = %d, helper imports = %d, sources = %#v", itemImports, helperImports, result.Sources())
+	}
+	if result.Config.Prompts[1].ID != "curated" {
+		t.Fatalf("helper did not provide prompt ID: %#v", result.Config.Prompts[1])
+	}
+}
+
+func TestPromptCatalogMountsResourceFromScheduledPromptOrigin(t *testing.T) {
+	result, err := consumers.LoadPromptCatalog(fixture("prompt-catalog", "config.yml"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Config.Prompts[2].ID != "welcome" || result.Config.Prompts[2].Resource != "welcome.txt" {
+		t.Fatalf("scheduled resource prompt = %#v", result.Config.Prompts)
+	}
+	resourcePath := configkit.Keys("prompts").Index(2).Key("resource")
+	info, ok := result.Metadata().Lookup(resourcePath)
+	if !ok || len(info.Origin.Locations) != 1 {
+		t.Fatalf("resource origin = %#v, %v", info, ok)
+	}
+	context, ok := result.SourceContext(info.Origin.Locations[0].SourceID)
+	if !ok || context.FS == nil || filepath.Base(context.BaseDir) != "prompts" {
+		t.Fatalf("resource source context = %#v, %v", context, ok)
+	}
+	contents, err := fs.ReadFile(context.FS, pathpkg.Join(context.BaseDir, result.Config.Prompts[2].Resource))
+	if err != nil || string(contents) != "Welcome resource text.\n" {
+		t.Fatalf("mounted resource = %q, %v", contents, err)
+	}
+}
+
+func TestRequiredPromptCatalogUsesOneRequiredFile(t *testing.T) {
+	result, err := consumers.LoadRequiredPromptCatalog(fixture("prompt-catalog", "simple.yml"))
+	if err != nil || len(result.Config.Prompts) != 1 || result.Config.Prompts[0].ID != "required" {
+		t.Fatalf("simple required prompt = %#v, %v", result, err)
+	}
+}
+
+func TestPromptCatalogLeavesDomainValidationWithConsumer(t *testing.T) {
+	_, err := consumers.LoadPromptCatalog(fixture("prompt-catalog", "invalid.yml"))
+	var loadError *configkit.LoadError
+	if !errors.As(err, &loadError) || len(loadError.Diagnostics()) != 1 ||
+		loadError.Diagnostics()[0].Code != configkit.CodeValidateError ||
+		loadError.Diagnostics()[0].Path.String() != "/prompts/0/messages" {
+		t.Fatalf("consumer domain validation error = %v", err)
+	}
+}

examples/consumers/sequence_catalog.go

@@ -0,0 +1,145 @@
+package consumers
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path"
+	"path/filepath"
+	"strings"
+
+	configkit "go.maximumdirect.net/configkit"
+)
+
+// SequenceCatalogConfig is a source-backed prompt catalog with an application
+// supplied run label and a value derived from that label during resolution.
+type SequenceCatalogConfig struct {
+	RunLabel      string                 `yaml:"run_label"`
+	ResolvedLabel string                 `yaml:"resolved_label"`
+	Prompts       []SequenceCatalogEntry `yaml:"prompts"`
+}
+
+// SequenceCatalogEntry keeps prompt meaning, resources, and credentials in the
+// consuming application while ConfigKit handles collection assembly.
+type SequenceCatalogEntry struct {
+	ID          string           `yaml:"id"`
+	Name        string           `yaml:"name"`
+	Description string           `yaml:"description"`
+	Messages    []string         `yaml:"messages"`
+	Resource    string           `yaml:"resource"`
+	Credential  configkit.Secret `yaml:"credential"`
+}
+
+// LoadSequenceCatalog searches its caller-selected main path before a custom
+// fallback directory, assembles imported fragments over a file-backed underlay,
+// applies one selected collection overlay, then resolves and validates once.
+func LoadSequenceCatalog(mainPath, overlayName, runLabel string) (*configkit.Result[SequenceCatalogConfig], error) {
+	absoluteMain, err := filepath.Abs(mainPath)
+	if err != nil {
+		return nil, err
+	}
+	root := filepath.Dir(absoluteMain)
+	filesystem := configkit.NewFilesystem("sequence catalog", os.DirFS(root))
+	filesystemContext := &configkit.FilesystemContext{BaseDir: ".", Root: ".", FS: &filesystem}
+	mainSearch := configkit.SearchConfig("", configkit.Searches(
+		configkit.SearchPaths(absoluteMain),
+		configkit.SearchDirectory(filepath.Join(root, "fallback"), configkit.DirectorySearchOptions{
+			Filenames: []configkit.FilenameGroup{configkit.CustomFilenames(filepath.Base(absoluteMain))},
+		}),
+	), configkit.SearchOptions{Required: true})
+	definition := configkit.Definition[SequenceCatalogConfig]{
+		SequenceIdentities: []configkit.SequenceIdentity{
+			configkit.SequenceIdentityAt(configkit.Keys("prompts"), "id"),
+		},
+		Resolve: func(configuration *SequenceCatalogConfig, resolution *configkit.Resolution) error {
+			configuration.ResolvedLabel = "for:" + configuration.RunLabel
+			resolution.RecordNormalization(configkit.Keys("resolved_label"),
+				"derive the resolved label from the selected run label", configkit.Keys("run_label"))
+			return nil
+		},
+		Validate: validateSequenceCatalog,
+	}
+	return configkit.LoadLayered(configkit.Input{
+		Source:     mainSearch,
+		Imports:    true,
+		Filesystem: &configkit.FilesystemContext{Root: root},
+	}, configkit.LayeredOptions[SequenceCatalogConfig]{
+		Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{
+			Source: filesystem.File("underlay.yml"),
+		}}}},
+		Overlay:           overlayName,
+		OverlayFilesystem: filesystemContext,
+		Overrides: []configkit.Override{{
+			Path: configkit.Keys("run_label"), Value: runLabel, Flag: "--run-label",
+		}},
+		Definition: definition,
+	})
+}
+
+// ReadSequenceCatalogResource follows the final prompt field's source context,
+// including when record inheritance retained a resource from an underlay.
+func ReadSequenceCatalogResource(result *configkit.Result[SequenceCatalogConfig], promptID string) (string, error) {
+	if result == nil {
+		return "", errors.New("sequence catalog result is nil")
+	}
+	for index, prompt := range result.Config.Prompts {
+		if prompt.ID != promptID {
+			continue
+		}
+		resourcePath := configkit.Keys("prompts").Index(index).Key("resource")
+		info, found := result.Metadata().Lookup(resourcePath)
+		if !found || len(info.Origin.Locations) != 1 {
+			return "", errors.New("prompt resource has no single declaring source")
+		}
+		context, found := result.SourceContext(info.Origin.Locations[0].SourceID)
+		if !found {
+			return "", errors.New("prompt resource source context is unavailable")
+		}
+		data, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, prompt.Resource))
+		if err != nil {
+			return "", fmt.Errorf("read prompt resource: %w", err)
+		}
+		return string(data), nil
+	}
+	return "", fmt.Errorf("prompt %q is unavailable", promptID)
+}
+
+func validateSequenceCatalog(configuration *SequenceCatalogConfig, validation *configkit.Validation) {
+	for index, prompt := range configuration.Prompts {
+		if strings.TrimSpace(prompt.Name) == "" {
+			validation.Error(configkit.Keys("prompts").Index(index).Key("name"), "must not be empty")
+		}
+		if len(prompt.Messages) == 0 {
+			validation.Error(configkit.Keys("prompts").Index(index).Key("messages"), "must contain at least one message")
+		}
+	}
+	if len(configuration.Prompts) == 0 {
+		validation.Error(configkit.Keys("prompts"), "must contain at least one prompt")
+	}
+}
+
+// NamespacedMapCatalogConfig demonstrates typed application maps whose
+// independent prompt sequences use root and dynamic namespace registrations.
+type NamespacedMapCatalogConfig struct {
+	Prompts     []map[string]any          `yaml:"prompts"`
+	Collections map[string]map[string]any `yaml:"collections"`
+}
+
+// LoadNamespacedMapCatalog applies the same scalar identity constraint to one
+// root collection and each namespace's independently scoped collection.
+func LoadNamespacedMapCatalog(source configkit.Source) (*configkit.Result[NamespacedMapCatalogConfig], error) {
+	selector := configkit.SequenceSelector{
+		configkit.SequenceLiteralKey("collections"),
+		configkit.SequenceAnyMappingKey(),
+		configkit.SequenceLiteralKey("prompts"),
+	}
+	return configkit.Load(source, configkit.Options[NamespacedMapCatalogConfig]{
+		Definition: configkit.Definition[NamespacedMapCatalogConfig]{
+			SequenceIdentities: []configkit.SequenceIdentity{
+				configkit.SequenceIdentityAt(configkit.Keys("prompts"), "id"),
+				configkit.SequenceIdentityMatching(selector, "id"),
+			},
+		},
+	})
+}

examples/consumers/sequence_catalog_test.go

@@ -0,0 +1,239 @@
+package consumers_test
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"strings"
+	"testing"
+
+	configkit "go.maximumdirect.net/configkit"
+	"go.maximumdirect.net/configkit/examples/consumers"
+)
+
+func Example_sequenceCatalog() {
+	const oldSecret = "CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET"
+	const newSecret = "CONFIGKIT_SEQUENCE_CATALOG_NEW_SECRET"
+	restoreOld, restoreNew := preserveEnvironment(oldSecret), preserveEnvironment(newSecret)
+	defer restoreOld()
+	defer restoreNew()
+	_ = os.Setenv(oldSecret, "disposable-old-example-credential")
+	_ = os.Setenv(newSecret, "disposable-new-example-credential")
+
+	result, err := consumers.LoadSequenceCatalog(fixture("sequence-catalog", "config.yml"), "upsert", "preview")
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	ids := make([]string, 0, len(result.Config.Prompts))
+	for _, prompt := range result.Config.Prompts {
+		ids = append(ids, prompt.ID)
+	}
+	shared := configkit.Keys("prompts").Index(1).Key("name")
+	info, _ := result.Metadata().Lookup(shared)
+	resource, resourceErr := consumers.ReadSequenceCatalogResource(result, "concise")
+	fmt.Println(ids, result.Config.ResolvedLabel, info.Explicit, len(result.Metadata().History(shared)), resource, resourceErr == nil, err)
+	// Output: [foundation shared welcome concise extra] for:preview true 2 Foundation resource text.
+	//  true <nil>
+}
+
+func TestSequenceCatalogSelectedOverlayOperations(t *testing.T) {
+	const oldSecret = "CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET"
+	const newSecret = "CONFIGKIT_SEQUENCE_CATALOG_NEW_SECRET"
+	t.Setenv(oldSecret, "sequence-catalog-old-canary")
+	t.Setenv(newSecret, "sequence-catalog-new-canary")
+
+	tests := []struct {
+		name    string
+		wantIDs []string
+		shared  *consumers.SequenceCatalogEntry
+	}{
+		{name: "append", wantIDs: []string{"foundation", "shared", "welcome", "concise", "extra"}},
+		{name: "upsert", wantIDs: []string{"foundation", "shared", "welcome", "concise", "extra"}, shared: &consumers.SequenceCatalogEntry{ID: "shared", Name: "Shared replacement", Messages: []string{"Replacement message"}, Credential: configkit.SecretEnv(newSecret)}},
+		{name: "replace", wantIDs: []string{"replacement", "last"}},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			result, err := consumers.LoadSequenceCatalog(fixture("sequence-catalog", "config.yml"), test.name, "test")
+			if err != nil {
+				var loadError *configkit.LoadError
+				if errors.As(err, &loadError) {
+					t.Fatalf("load selected overlay: %v (%#v)", err, loadError.Diagnostics())
+				}
+				t.Fatal(err)
+			}
+			gotIDs := make([]string, 0, len(result.Config.Prompts))
+			for _, prompt := range result.Config.Prompts {
+				gotIDs = append(gotIDs, prompt.ID)
+			}
+			if strings.Join(gotIDs, ",") != strings.Join(test.wantIDs, ",") {
+				t.Fatalf("prompt order = %v, want %v", gotIDs, test.wantIDs)
+			}
+			if test.shared == nil {
+				return
+			}
+			shared := result.Config.Prompts[1]
+			if shared.ID != test.shared.ID || shared.Name != test.shared.Name || len(shared.Messages) != 1 ||
+				shared.Messages[0] != test.shared.Messages[0] || shared.Description != "" || shared.Resource != "" || shared.Credential.EnvName() != newSecret {
+				t.Fatalf("upsert did not replace the complete matched record: %#v", shared)
+			}
+		})
+	}
+}
+
+func TestSequenceCatalogInspectionTracksResourcesAndSecretHistory(t *testing.T) {
+	const oldSecret = "CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET"
+	const newSecret = "CONFIGKIT_SEQUENCE_CATALOG_NEW_SECRET"
+	const oldCanary = "sequence-catalog-old-canary"
+	const newCanary = "sequence-catalog-new-canary"
+	t.Setenv(oldSecret, oldCanary)
+	t.Setenv(newSecret, newCanary)
+
+	result, err := consumers.LoadSequenceCatalog(fixture("sequence-catalog", "config.yml"), "upsert", "history")
+	if err != nil {
+		var loadError *configkit.LoadError
+		if errors.As(err, &loadError) {
+			t.Fatalf("load sequence catalog: %v (%#v)", err, loadError.Diagnostics())
+		}
+		t.Fatal(err)
+	}
+	resourcePath := configkit.Keys("prompts").Index(3).Key("resource")
+	resourceInfo, found := result.Metadata().Lookup(resourcePath)
+	if !found || len(resourceInfo.Origin.Locations) != 1 || len(resourceInfo.Origin.Inheritance) != 1 {
+		t.Fatalf("inherited resource inspection = %#v, %v", resourceInfo, found)
+	}
+	resource, err := consumers.ReadSequenceCatalogResource(result, "concise")
+	if err != nil || resource != "Foundation resource text.\n" {
+		t.Fatalf("resource from inherited source context = %q, %v", resource, err)
+	}
+	if len(result.Metadata().History(configkit.Keys("resolved_label"))) == 0 {
+		t.Fatal("recorded CLI-driven resolution was absent from final inspection")
+	}
+	credentialPath := configkit.Keys("prompts").Index(1).Key("credential")
+	credentialHistory := result.Metadata().History(credentialPath)
+	if len(credentialHistory) == 0 {
+		t.Fatal("upsert did not retain the replaced secret reference in history")
+	}
+	var explanation bytes.Buffer
+	if err := result.WriteExplanation(&explanation, credentialPath); err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(explanation.String(), oldCanary) || strings.Contains(explanation.String(), newCanary) {
+		t.Fatalf("secret explanation exposed a credential value: %s", explanation.String())
+	}
+}
+
+func TestNamespacedTypedMapIdentityScopesAreIndependent(t *testing.T) {
+	source := configkit.Bytes("namespaced maps", []byte(`
+prompts:
+  - id: shared
+    text: root prompt
+collections:
+  team:
+    prompts:
+      - id: shared
+        text: team prompt
+  operations:
+    prompts:
+      - id: shared
+        text: operations prompt
+`))
+	result, err := consumers.LoadNamespacedMapCatalog(source)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Config.Prompts[0]["text"] != "root prompt" ||
+		result.Config.Collections["team"]["prompts"].([]any)[0].(map[string]any)["text"] != "team prompt" ||
+		result.Config.Collections["operations"]["prompts"].([]any)[0].(map[string]any)["text"] != "operations prompt" {
+		t.Fatalf("typed map collections = %#v", result.Config)
+	}
+}
+
+func TestNamespacedTypedMapIdentityFindsCollectionsIntroducedByInheritance(t *testing.T) {
+	result, err := consumers.LoadNamespacedMapCatalog(configkit.Bytes("inherited namespace", []byte(`
+collections:
+  source:
+    prompts:
+      - id: shared
+        text: inherited prompt
+  copied:
+    extends: source
+`)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	copied := result.Config.Collections["copied"]["prompts"].([]any)
+	if len(copied) != 1 || copied[0].(map[string]any)["text"] != "inherited prompt" {
+		t.Fatalf("inherited typed-map collection = %#v", result.Config.Collections["copied"])
+	}
+}
+
+func Example_yamlDeclaredIdentityOnly() {
+	result, err := configkit.Load(configkit.Bytes("YAML identity only", []byte(`
+configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+prompts:
+  - id: initial
+`)), configkit.Options[map[string]any]{
+		Overrides: []configkit.Override{{
+			Path: configkit.Keys("prompts"),
+			Value: []any{
+				map[string]any{"id": "same"},
+				map[string]any{"id": "same"},
+			},
+			Flag: "--prompts",
+		}},
+	})
+	fmt.Println(len(result.Config["prompts"].([]any)), err)
+	// Output: 2 <nil>
+}
+
+func TestYAMLDeclaredIdentityDoesNotRegisterFinalTypedConstraint(t *testing.T) {
+	result, err := configkit.Load(configkit.Bytes("YAML identity only", []byte(`
+configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+prompts:
+  - id: initial
+`)), configkit.Options[map[string]any]{
+		Overrides: []configkit.Override{{
+			Path: configkit.Keys("prompts"),
+			Value: []any{
+				map[string]any{"id": "same"},
+				map[string]any{"id": "same"},
+			},
+			Flag: "--prompts",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("YAML-only identity incorrectly became an application constraint: %v", err)
+	}
+	prompts := result.Config["prompts"].([]any)
+	if len(prompts) != 2 || prompts[0].(map[string]any)["id"] != prompts[1].(map[string]any)["id"] {
+		t.Fatalf("CLI result = %#v", result.Config)
+	}
+}
+
+func TestNamespacedTypedMapRejectsDuplicatesWithinOneCollection(t *testing.T) {
+	_, err := consumers.LoadNamespacedMapCatalog(configkit.Bytes("duplicate namespace", []byte(`
+collections:
+  team:
+    prompts:
+      - id: duplicate
+      - id: duplicate
+`)))
+	var loadError *configkit.LoadError
+	if !errors.As(err, &loadError) || len(loadError.Diagnostics()) != 1 ||
+		loadError.Diagnostics()[0].Code != configkit.CodeComposeConflict ||
+		loadError.Diagnostics()[0].Path.String() != "/collections/team/prompts" {
+		diagnostics := []configkit.Diagnostic(nil)
+		if loadError != nil {
+			diagnostics = loadError.Diagnostics()
+		}
+		t.Fatalf("duplicate namespaced identity error = %v (%#v)", err, diagnostics)
+	}
+}

examples/consumers/source_version.go

@@ -0,0 +1,64 @@
+package consumers
+
+import (
+	"errors"
+	"io/fs"
+
+	configkit "go.maximumdirect.net/configkit"
+)
+
+// VersionedServiceConfig demonstrates a mounted main input whose source-local
+// schema version is retained at the effective service path.
+type VersionedServiceConfig struct {
+	Service struct {
+		Version  string `yaml:"version"`
+		Name     string `yaml:"name"`
+		Endpoint string `yaml:"endpoint"`
+		Metadata struct {
+			Release string `yaml:"release"`
+		} `yaml:"metadata"`
+	} `yaml:"service"`
+}
+
+// LoadVersionedService checks the main and underlay declarations with one
+// application policy. The local rule path is "version" for each source; the
+// main input's destination places its protected value at /service/version.
+// Optional CLI overrides are passed through to ConfigKit for normal protection.
+func LoadVersionedService(mode configkit.SourceVersionMode, overrides ...configkit.Override) (*configkit.Result[VersionedServiceConfig], error) {
+	files, err := fs.Sub(bundledFiles, "testdata/source-version")
+	if err != nil {
+		return nil, err
+	}
+	main, err := fs.ReadFile(files, "main.yml")
+	if err != nil {
+		return nil, err
+	}
+	underlay, err := fs.ReadFile(files, "underlay.yml")
+	if err != nil {
+		return nil, err
+	}
+	definition := configkit.Definition[VersionedServiceConfig]{
+		Version: &configkit.VersionRule{
+			Path: configkit.Keys("version"),
+			Check: func(version configkit.Version, _ *configkit.Validation) error {
+				if !version.Present || version.Null || version.Text == "" {
+					return errors.New("a nonempty source version is required")
+				}
+				return nil
+			},
+		},
+		Sensitive: func(path configkit.Path) bool {
+			return path.String() == "/service/version"
+		},
+	}
+	return configkit.LoadLayered(configkit.Input{
+		Source: configkit.Bytes("service main", main), Destination: configkit.Keys("service"),
+	}, configkit.LayeredOptions[VersionedServiceConfig]{
+		Definition:        definition,
+		SourceVersionMode: mode,
+		Overrides:         overrides,
+		Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{
+			Source: configkit.Bytes("service defaults", underlay), Destination: configkit.Keys("service"),
+		}}}},
+	})
+}

examples/consumers/testdata/collection-bundle/collections/weather/collection.yml

@@ -0,0 +1,9 @@
+configkit:
+  imports:
+    - path: metadata.yml
+      destination: []
+    - path: prompts/index.yml
+      destination: [prompts]
+    - path: profiles/index.yml
+      destination: [profiles]
+name: Weather Reporter

examples/consumers/testdata/collection-bundle/collections/weather/metadata.yml

@@ -0,0 +1,4 @@
+configkit:
+  imports:
+    - path: version.yml
+description: Imported collection metadata.

examples/consumers/testdata/collection-bundle/collections/weather/profiles/compact.yml

@@ -0,0 +1,3 @@
+compact:
+  format: text
+  temperature: 0.2

examples/consumers/testdata/collection-bundle/collections/weather/profiles/index.yml

@@ -0,0 +1,4 @@
+configkit:
+  imports:
+    - path: compact.yml
+    - path: weather.yml

examples/consumers/testdata/collection-bundle/collections/weather/profiles/weather.yml

@@ -0,0 +1,3 @@
+weather:
+  extends: compact
+  temperature: 0.4

examples/consumers/testdata/collection-bundle/collections/weather/prompts/brief.yml

@@ -0,0 +1,7 @@
+brief:
+  version: "1"
+  default_profile: compact
+  content_file: welcome.txt
+  messages:
+    - role: user
+      content: Write a concise weather summary.

examples/consumers/testdata/collection-bundle/collections/weather/prompts/custom.yml

@@ -0,0 +1,3 @@
+custom:
+  extends: brief
+  default_profile: weather

examples/consumers/testdata/collection-bundle/collections/weather/prompts/index.yml

@@ -0,0 +1,4 @@
+configkit:
+  imports:
+    - path: brief.yml
+    - path: custom.yml

examples/consumers/testdata/collection-bundle/collections/weather/prompts/welcome.txt

@@ -0,0 +1 @@
+Welcome to the weather collection.

examples/consumers/testdata/collection-bundle/collections/weather/version.yml

@@ -0,0 +1 @@
+version: "2.4.0"

examples/consumers/testdata/collection-bundle/operators/weather-prompt-version.yml

@@ -0,0 +1,2 @@
+brief:
+  version: "2"

examples/consumers/testdata/ordinary-imports/config.yml

@@ -0,0 +1,6 @@
+configkit:
+  imports:
+    - path: metadata.yml
+    - path: prompts/brief.yml
+      destination: [prompts]
+name: Root import example

examples/consumers/testdata/ordinary-imports/metadata.yml

@@ -0,0 +1,2 @@
+version: "1.0"
+description: Metadata imported into the root document.

examples/consumers/testdata/ordinary-imports/prompts/brief.yml

@@ -0,0 +1,2 @@
+brief:
+  summary: A root-loaded prompt.

examples/consumers/testdata/prompt-catalog/config.yml

@@ -0,0 +1,19 @@
+configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+      mode: replace
+  imports:
+    - dir: prompts
+      exclude: [generated-ignored.yml]
+      destination: [prompts]
+      placement: sequence-item
+    - dir: featured
+      pattern: [weather-*.yml]
+      destination: [prompts]
+      placement: sequence-item
+    - dir: optional
+prompts:
+  - id: main
+    name: Main authored prompt
+    messages: [Use the main prompt.]

examples/consumers/testdata/prompt-catalog/featured/weather-feature.yml

@@ -0,0 +1,4 @@
+id: weather
+name: Weather forecast
+messages:
+  - Describe today's forecast.

examples/consumers/testdata/prompt-catalog/invalid.yml

@@ -0,0 +1,9 @@
+configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+      mode: replace
+prompts:
+  - id: invalid
+    name: Invalid prompt
+    messages: []

examples/consumers/testdata/prompt-catalog/optional/ignored.txt

@@ -0,0 +1 @@
+This file does not match the application import defaults.

examples/consumers/testdata/prompt-catalog/prompts/curated.yml

@@ -0,0 +1,6 @@
+configkit:
+  imports:
+    - path: helpers/curated-id.yml
+name: Curated summary
+messages:
+  - Summarize the supplied content.

examples/consumers/testdata/prompt-catalog/prompts/generated-ignored.yml

@@ -0,0 +1,3 @@
+id: ignored
+name: Excluded generated prompt
+messages: [This record is excluded.]

examples/consumers/testdata/prompt-catalog/prompts/generated-welcome.yml

@@ -0,0 +1,5 @@
+id: welcome
+name: Welcome
+messages:
+  - Welcome the user.
+resource: welcome.txt

examples/consumers/testdata/prompt-catalog/prompts/helpers/curated-id.yml

@@ -0,0 +1 @@
+id: curated

examples/consumers/testdata/prompt-catalog/prompts/required.yml

@@ -0,0 +1,3 @@
+id: required
+name: Required prompt
+messages: [Use the required prompt.]

examples/consumers/testdata/prompt-catalog/prompts/welcome.txt

@@ -0,0 +1 @@
+Welcome resource text.

examples/consumers/testdata/prompt-catalog/simple.yml

@@ -0,0 +1,7 @@
+configkit:
+  imports:
+    - path: prompts/required.yml
+      required: true
+      destination: [prompts]
+      placement: sequence-item
+prompts: []

examples/consumers/testdata/sequence-catalog/config.yml

@@ -0,0 +1,7 @@
+run_label: source-default
+configkit:
+  imports:
+    - dir: fragments
+      pattern: '*.yml'
+      destination: [prompts]
+      placement: sequence-item

examples/consumers/testdata/sequence-catalog/foundation.txt

@@ -0,0 +1 @@
+Foundation resource text.

examples/consumers/testdata/sequence-catalog/fragments/01-welcome.yml

@@ -0,0 +1,4 @@
+id: welcome
+name: Welcome
+messages: [Welcome message]
+credential: CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET

examples/consumers/testdata/sequence-catalog/fragments/02-concise.yml

@@ -0,0 +1,3 @@
+id: concise
+extends: {id: foundation}
+name: Concise

examples/consumers/testdata/sequence-catalog/overlays/append.yml

@@ -0,0 +1,10 @@
+configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+      mode: append
+prompts:
+  - id: extra
+    name: Extra
+    messages: [Extra message]
+    credential: CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET

examples/consumers/testdata/sequence-catalog/overlays/replace.yml

@@ -0,0 +1,14 @@
+configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+      mode: replace
+prompts:
+  - id: replacement
+    name: Replacement
+    messages: [Replacement message]
+    credential: CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET
+  - id: last
+    name: Last
+    messages: [Last message]
+    credential: CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET

examples/consumers/testdata/sequence-catalog/overlays/upsert.yml

@@ -0,0 +1,14 @@
+configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+      mode: upsert
+prompts:
+  - id: shared
+    name: Shared replacement
+    messages: [Replacement message]
+    credential: CONFIGKIT_SEQUENCE_CATALOG_NEW_SECRET
+  - id: extra
+    name: Extra
+    messages: [Extra message]
+    credential: CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET

examples/consumers/testdata/sequence-catalog/underlay.yml

@@ -0,0 +1,18 @@
+configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+      mode: append
+prompts:
+  - id: foundation
+    name: Foundation
+    description: Shared foundation instruction
+    messages: [Foundation message]
+    resource: foundation.txt
+    credential: CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET
+  - id: shared
+    name: Shared draft
+    description: This field must not survive a whole-record replacement
+    messages: [Draft message]
+    resource: shared.txt
+    credential: CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET

examples/consumers/testdata/source-version/main.yml

@@ -0,0 +1,4 @@
+version: service-v2
+name: example service
+metadata:
+  release: application-2026.10

examples/consumers/testdata/source-version/underlay.yml

@@ -0,0 +1,2 @@
+version: catalog-v1
+endpoint: https://service.example.invalid

facade_candidate_test.go

@@ -11,7 +11,7 @@ import (
 	"strings"
 	"testing"
 
-	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	configkit "go.maximumdirect.net/configkit"
 )
 
 var (
@@ -23,7 +23,7 @@ var (
 
 func TestFacadeValuesRemainRootOwned(t *testing.T) {
 	t.Parallel()
-	const packagePath = "gitea.maximumdirect.net/eric/ConfigKit"
+	const packagePath = "go.maximumdirect.net/configkit"
 	for _, candidate := range []reflect.Type{
 		reflect.TypeFor[configkit.Path](), reflect.TypeFor[configkit.Source](),
 		reflect.TypeFor[configkit.Secret](), reflect.TypeFor[configkit.Diagnostic](),
@@ -140,7 +140,7 @@ func TestFacadeSecretsBootstrapUsesFacadeRecords(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	report, err := configkit.LoadSecretsDir(directory)
+	report, err := configkit.LoadSecretsIntoEnvironment(directory)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -164,7 +164,7 @@ func TestFacadeSecretsBootstrapUsesFacadeRecords(t *testing.T) {
 		t.Fatalf("report rendering = %q, %v", rendered.String(), err)
 	}
 
-	failedReport, err := configkit.LoadSecretsDir("")
+	failedReport, err := configkit.LoadSecretsIntoEnvironment("")
 	var secretsError *configkit.SecretsError
 	if failedReport == nil || !errors.As(err, &secretsError) || len(secretsError.Diagnostics()) != 1 || secretsError.Diagnostics()[0].Code != configkit.CodeSecretsInvalidPath {
 		t.Fatalf("bootstrap failure = %#v / %#v", failedReport, err)
@@ -203,7 +203,7 @@ func TestFacadeLoadBridgesLifecycleCallbacks(t *testing.T) {
 			if !resolution.IsExplicit(configkit.Keys("input")) {
 				resolution.Error(configkit.Keys("input"), "input is required")
 			}
-			input, ok := resolution.InputInfo(configkit.Keys("input"))
+			input, ok := resolution.EntryInfo(configkit.Keys("input"))
 			if !ok || !input.Explicit {
 				resolution.Error(configkit.Keys("input"), "missing input provenance")
 			}
@@ -245,6 +245,8 @@ func TestFacadeLoadBridgesLifecycleCallbacks(t *testing.T) {
 	}
 	for _, context := range []func(){
 		func() { retainedResolution.IsExplicit(configkit.Keys("input")) },
+		func() { retainedResolution.RecordDerivedDefault(configkit.Keys("input"), "too late") },
+		func() { retainedResolution.RecordNormalization(configkit.Keys("input"), "too late") },
 		func() { retainedValidation.Warning(configkit.Keys("input"), "too late") },
 	} {
 		func() {

facade_compatibility_test.go

@@ -5,10 +5,9 @@ import (
 	"errors"
 	"fmt"
 	"io"
-	"reflect"
 	"testing"
 
-	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	configkit "go.maximumdirect.net/configkit"
 )
 
 var (
@@ -27,23 +26,6 @@ type facadeCompatibilityConfig struct {
 func TestFacadeCompatibility(t *testing.T) {
 	t.Parallel()
 
-	const packagePath = "gitea.maximumdirect.net/eric/ConfigKit"
-	for _, candidate := range []struct {
-		name  string
-		type_ reflect.Type
-	}{
-		{"Path", reflect.TypeFor[configkit.Path]()},
-		{"Source", reflect.TypeFor[configkit.Source]()},
-		{"Secret", reflect.TypeFor[configkit.Secret]()},
-		{"Definition", reflect.TypeFor[configkit.Definition[facadeCompatibilityConfig]]()},
-		{"Options", reflect.TypeFor[configkit.Options[facadeCompatibilityConfig]]()},
-		{"Result", reflect.TypeFor[configkit.Result[facadeCompatibilityConfig]]()},
-	} {
-		if candidate.type_.PkgPath() != packagePath {
-			t.Errorf("%s belongs to %q, want %q", candidate.name, candidate.type_.PkgPath(), packagePath)
-		}
-	}
-
 	constructed := configkit.Options[facadeCompatibilityConfig]{
 		Definition: configkit.Definition[facadeCompatibilityConfig]{},
 		Filesystem: &configkit.FilesystemContext{BaseDir: "configs", Root: "configs"},
@@ -56,11 +38,6 @@ func TestFacadeCompatibility(t *testing.T) {
 	if got := constructed.Overrides[0].Path.String(); got != "/value" {
 		t.Fatalf("constructed override path = %q, want /value", got)
 	}
-	publicResult := configkit.Result[facadeCompatibilityConfig]{Config: facadeCompatibilityConfig{Value: "constructed"}}
-	if publicResult.Config.Value != "constructed" {
-		t.Fatal("constructed result lost its public configuration")
-	}
-
 	result, err := configkit.Load(configkit.Bytes("facade.yml", []byte("value: input\n")), configkit.Options[facadeCompatibilityConfig]{
 		Definition: configkit.Definition[facadeCompatibilityConfig]{
 			Resolve: func(configuration *facadeCompatibilityConfig, resolution *configkit.Resolution) error {

facade_container_origin_test.go

@@ -0,0 +1,41 @@
+package configkit_test
+
+import (
+	"testing"
+	"testing/fstest"
+
+	configkit "go.maximumdirect.net/configkit"
+)
+
+func TestOverlayExplanationUsesQueryScopedOrigin(t *testing.T) {
+	t.Parallel()
+	filesystem := configkit.NewFilesystem("origin", fstest.MapFS{
+		"main.yml":         {Data: []byte("a: base\ngroup: {x: X, y: Y}\n")},
+		"overlays/dev.yml": {Data: []byte("a: overlay\ngroup: {x: O}\n")},
+	})
+	result, err := configkit.Load[map[string]any](filesystem.File("main.yml"), configkit.Options[map[string]any]{Overlay: "dev"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, test := range []struct {
+		path         configkit.Path
+		line, column int
+	}{
+		{configkit.Keys(), 1, 1},
+		{configkit.Keys("group"), 2, 8},
+		{configkit.Keys("group", "x"), 2, 12},
+	} {
+		explanation, found := result.Explain(test.path)
+		if !found || len(explanation.History) == 0 {
+			t.Fatalf("missing explanation for %s", test.path)
+		}
+		origin := explanation.History[len(explanation.History)-1].Origin
+		if origin.Layer != configkit.LayerOverlay || len(origin.Locations) != 1 {
+			t.Fatalf("overlay origin for %s = %#v", test.path, origin)
+		}
+		location := origin.Locations[0]
+		if location.SourceID != "source-2" || location.Line != test.line || location.Column != test.column {
+			t.Fatalf("overlay location for %s = %#v; want line %d column %d", test.path, location, test.line, test.column)
+		}
+	}
+}

facade_context_test.go

@@ -3,7 +3,7 @@ package configkit_test
 import (
 	"testing"
 
-	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	configkit "go.maximumdirect.net/configkit"
 )
 
 func TestFacadeInactiveContextsPreserveClosedFailure(t *testing.T) {
@@ -24,10 +24,11 @@ func TestFacadeInactiveContextsPreserveClosedFailure(t *testing.T) {
 				call func()
 			}{
 				{"IsExplicit", func() { state.resolution.IsExplicit(path) }},
-				{"InputInfo", func() { state.resolution.InputInfo(path) }},
+				{"EntryInfo", func() { state.resolution.EntryInfo(path) }},
 				{"Source", func() { state.resolution.Source("source") }},
 				{"SourceContext", func() { state.resolution.SourceContext("source") }},
-				{"Record", func() { state.resolution.Record(path, configkit.ChangeNormalization, "reason") }},
+				{"RecordDerivedDefault", func() { state.resolution.RecordDerivedDefault(path, "reason") }},
+				{"RecordNormalization", func() { state.resolution.RecordNormalization(path, "reason") }},
 				{"Resolution.Error", func() { state.resolution.Error(path, "message") }},
 				{"Resolution.Warning", func() { state.resolution.Warning(path, "message") }},
 				{"Default", func() { configkit.Default(state.resolution, path, &target, 1, "reason") }},

facade_destination_test.go

@@ -0,0 +1,705 @@
+package configkit_test
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"testing/fstest"
+
+	configkit "go.maximumdirect.net/configkit"
+)
+
+func TestFacadeInputDestinationsAcrossSourceKinds(t *testing.T) {
+	directory := t.TempDir()
+	hostPath := filepath.Join(directory, "host.yml")
+	if err := os.WriteFile(hostPath, []byte("value: host\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	native := configkit.NewFilesystem("native", fstest.MapFS{
+		"main.yml": &fstest.MapFile{Data: []byte("value: native\n")},
+	})
+	const literalValuePath = "/collections/weather.reporter/profiles/a~1b/~0/0"
+	destination := configkit.Keys("collections", "weather.reporter", "profiles", "a/b", "~", "0")
+	for _, test := range []struct {
+		name   string
+		source configkit.Source
+		want   string
+		kind   configkit.SourceKind
+	}{
+		{name: "host file", source: configkit.File(hostPath), want: "host", kind: configkit.SourceKindFile},
+		{name: "native filesystem", source: native.File("main.yml"), want: "native", kind: configkit.SourceKindFilesystem},
+		{name: "bytes", source: configkit.Bytes("bytes", []byte("value: bytes\n")), want: "bytes", kind: configkit.SourceKindBytes},
+		{name: "reader", source: configkit.Reader("reader", strings.NewReader("value: reader\n")), want: "reader", kind: configkit.SourceKindReader},
+		{name: "mapping", source: configkit.Mapping("mapping", map[string]any{"value": "mapping"}), want: "mapping", kind: configkit.SourceKindMapping},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			result, err := configkit.LoadLayered[map[string]any](configkit.Input{Source: test.source, Destination: destination})
+			if err != nil {
+				t.Fatalf("LoadLayered: %v", err)
+			}
+			if got := facadeDestinationValue(t, result.Config, "collections", "weather.reporter", "profiles", "a/b", "~", "0", "value"); got != test.want {
+				t.Fatalf("placed value = %#v, want %q", got, test.want)
+			}
+			sources := result.Sources()
+			if len(sources) != 1 || sources[0].Kind != test.kind || sources[0].Destination.String() != destination.String() || destination.String() != literalValuePath {
+				t.Fatalf("source placement = %#v, destination = %q", sources, destination.String())
+			}
+		})
+	}
+}
+
+func TestFacadeDestinationRootEmptyMappingNoSourceAndInvalidPaths(t *testing.T) {
+	for _, test := range []struct {
+		name        string
+		destination configkit.Path
+	}{
+		{name: "omitted destination"},
+		{name: "explicit empty destination", destination: configkit.Path{}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			result, err := configkit.LoadLayered[map[string]any](configkit.Input{Source: configkit.Bytes("root", []byte("value: root\n")), Destination: test.destination})
+			if err != nil {
+				t.Fatalf("root load: %v", err)
+			}
+			if result.Config["value"] != "root" || len(result.Sources()) != 1 || result.Sources()[0].Destination.String() != "" {
+				t.Fatalf("root placement = %#v, sources %#v", result.Config, result.Sources())
+			}
+		})
+	}
+
+	emptyPath := configkit.Keys("collections", "empty")
+	empty, err := configkit.LoadLayered[map[string]any](configkit.Input{
+		Source: configkit.Mapping("empty", map[string]any{}), Destination: emptyPath,
+	})
+	if err != nil {
+		t.Fatalf("empty mapping load: %v", err)
+	}
+	if value := facadeDestinationMap(t, empty.Config, "collections")["empty"]; value == nil {
+		t.Fatal("empty mapping did not materialize its destination")
+	}
+	if info, ok := empty.Metadata().Lookup(emptyPath); !ok || !info.Explicit {
+		t.Fatalf("empty destination metadata = %#v, %v", info, ok)
+	}
+
+	absentPath := configkit.Keys("collections", "absent")
+	absent, err := configkit.LoadLayered[map[string]any](configkit.Input{Source: configkit.NoSource(), Destination: absentPath})
+	if err != nil {
+		t.Fatalf("NoSource with a destination: %v", err)
+	}
+	if len(absent.Sources()) != 0 {
+		t.Fatalf("NoSource created source records: %#v", absent.Sources())
+	}
+	if _, ok := absent.Metadata().Lookup(absentPath); ok {
+		t.Fatal("NoSource materialized its destination")
+	}
+
+	reader := &destinationCountingReader{}
+	for _, test := range []struct {
+		name        string
+		source      configkit.Source
+		destination configkit.Path
+		wantReads   int
+	}{
+		{name: "index segment", source: configkit.Reader("unread", reader), destination: configkit.Keys("catalog").Index(0)},
+		{name: "reserved configkit key", source: configkit.NoSource(), destination: configkit.Keys("configkit")},
+		{name: "reserved extends key", source: configkit.NoSource(), destination: configkit.Keys("catalog", "extends")},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			_, err := configkit.LoadLayered[map[string]any](configkit.Input{Source: test.source, Destination: test.destination})
+			loadError, ok := err.(*configkit.LoadError)
+			if !ok || len(loadError.Diagnostics()) == 0 || loadError.Diagnostics()[0].Code != configkit.CodeOptionsInvalid {
+				t.Fatalf("invalid destination error = %#v", err)
+			}
+			if reader.reads != test.wantReads {
+				t.Fatalf("reader calls = %d, want %d", reader.reads, test.wantReads)
+			}
+		})
+	}
+}
+
+func TestFacadeImportedSourcesRetainInputDestination(t *testing.T) {
+	directory := t.TempDir()
+	mainPath := filepath.Join(directory, "main.yml")
+	fragmentPath := filepath.Join(directory, "fragment.yml")
+	if err := os.WriteFile(mainPath, []byte("configkit: {imports: [{path: fragment.yml}]}\nmain: present\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(fragmentPath, []byte("imported: present\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	destination := configkit.Keys("collections", "weatherreporter")
+	result, err := configkit.LoadLayered[map[string]any](configkit.Input{
+		Source: configkit.File(mainPath), Imports: true, Destination: destination,
+	})
+	if err != nil {
+		t.Fatalf("mounted import load: %v", err)
+	}
+	collection := facadeDestinationMap(t, result.Config, "collections", "weatherreporter")
+	if collection["main"] != "present" || collection["imported"] != "present" {
+		t.Fatalf("mounted imported values = %#v", collection)
+	}
+	sources := result.Sources()
+	if len(sources) != 2 || sources[0].Destination.String() != destination.String() || sources[1].Destination.String() != destination.String() {
+		t.Fatalf("mounted import source destinations = %#v", sources)
+	}
+	if sources[1].ImportedFrom == nil {
+		t.Fatalf("imported source lacks its authored directive: %#v", sources[1])
+	}
+}
+
+func TestFacadeRelativeImportDestinationsForRootAndMountedLoads(t *testing.T) {
+	directory := t.TempDir()
+	write := func(relative, contents string) string {
+		t.Helper()
+		filename := filepath.Join(directory, filepath.FromSlash(relative))
+		if err := os.MkdirAll(filepath.Dir(filename), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filename, []byte(contents), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		return filename
+	}
+
+	mainPath := write("main.yml", `configkit:
+  imports:
+    - path: metadata.yml
+      destination: [metadata]
+    - glob: prompts/*.yml
+      destination: [prompts]
+    - path: entries/main.yml
+      destination: [profiles]
+    - path: sibling.yml
+      destination: [sibling]
+root: main
+`)
+	write("metadata.yml", "name: imported\n")
+	write("prompts/a.yml", "a: {name: alpha}\n")
+	write("prompts/b.yml", "b: {name: beta}\n")
+	write("entries/main.yml", `configkit:
+  imports:
+    - path: nested/details.yml
+      destination: [details]
+name: profile
+`)
+	write("entries/nested/details.yml", "summary: nested\n")
+	write("sibling.yml", "name: separate\n")
+
+	root, err := configkit.Load(
+		configkit.File(mainPath), configkit.Options[map[string]any]{Imports: true},
+	)
+	if err != nil {
+		if loadError, ok := err.(*configkit.LoadError); ok {
+			t.Fatalf("ordinary root Load: %v, diagnostics %#v", err, loadError.Diagnostics())
+		}
+		t.Fatalf("ordinary root Load: %v", err)
+	}
+	mountedDestination := configkit.Keys("collections", "weatherreporter")
+	mounted, err := configkit.LoadLayered[map[string]any](configkit.Input{
+		Source: configkit.File(mainPath), Imports: true, Destination: mountedDestination,
+	})
+	if err != nil {
+		t.Fatalf("mounted layered Load: %v", err)
+	}
+
+	for _, test := range []struct {
+		name   string
+		result *configkit.Result[map[string]any]
+		prefix []string
+	}{
+		{name: "ordinary root", result: root},
+		{name: "mounted entry", result: mounted, prefix: []string{"collections", "weatherreporter"}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			at := func(keys ...string) []string {
+				return append(append([]string(nil), test.prefix...), keys...)
+			}
+			if got := facadeDestinationValue(t, test.result.Config, at("root")...); got != "main" {
+				t.Fatalf("root value = %#v", got)
+			}
+			if got := facadeDestinationValue(t, test.result.Config, at("metadata", "name")...); got != "imported" {
+				t.Fatalf("metadata value = %#v", got)
+			}
+			if got := facadeDestinationValue(t, test.result.Config, at("prompts", "a", "name")...); got != "alpha" {
+				t.Fatalf("first glob value = %#v", got)
+			}
+			if got := facadeDestinationValue(t, test.result.Config, at("prompts", "b", "name")...); got != "beta" {
+				t.Fatalf("second glob value = %#v", got)
+			}
+			if got := facadeDestinationValue(t, test.result.Config, at("profiles", "name")...); got != "profile" {
+				t.Fatalf("entry value = %#v", got)
+			}
+			if got := facadeDestinationValue(t, test.result.Config, at("profiles", "details", "summary")...); got != "nested" {
+				t.Fatalf("nested import value = %#v", got)
+			}
+			if got := facadeDestinationValue(t, test.result.Config, at("sibling", "name")...); got != "separate" {
+				t.Fatalf("subsequent sibling value = %#v", got)
+			}
+
+			wantPaths := []string{
+				"main.yml", "metadata.yml", "a.yml", "b.yml", "main.yml", "details.yml", "sibling.yml",
+			}
+			wantPhysicalPaths := []string{
+				mainPath,
+				filepath.Join(directory, "metadata.yml"),
+				filepath.Join(directory, "prompts", "a.yml"),
+				filepath.Join(directory, "prompts", "b.yml"),
+				filepath.Join(directory, "entries", "main.yml"),
+				filepath.Join(directory, "entries", "nested", "details.yml"),
+				filepath.Join(directory, "sibling.yml"),
+			}
+			wantImportParents := []string{"", "source-1", "source-1", "source-1", "source-1", "source-5", "source-1"}
+			wantDestinations := []configkit.Path{configkit.Keys(test.prefix...)}
+			for _, suffix := range [][]string{{"metadata"}, {"prompts"}, {"prompts"}, {"profiles"}, {"profiles", "details"}, {"sibling"}} {
+				destination := append([]string(nil), test.prefix...)
+				for _, segment := range suffix {
+					destination = append(destination, segment)
+				}
+				wantDestinations = append(wantDestinations, configkit.Keys(destination...))
+			}
+			sources := test.result.Sources()
+			if len(sources) != len(wantPaths) {
+				t.Fatalf("sources = %#v, want %d", sources, len(wantPaths))
+			}
+			for index, source := range sources {
+				if filepath.Base(source.Path) != wantPaths[index] || source.Path != wantPhysicalPaths[index] || source.Destination.String() != wantDestinations[index].String() {
+					t.Errorf("source %d path/destination = (%q, %q), want physical path %q and destination %q", index, source.Path, source.Destination.String(), wantPhysicalPaths[index], wantDestinations[index].String())
+				}
+				if source.ID != fmt.Sprintf("source-%d", index+1) || source.Kind != configkit.SourceKindFile {
+					t.Errorf("source %d identity/kind = (%q, %q)", index, source.ID, source.Kind)
+				}
+				if wantImportParents[index] == "" {
+					if source.ImportedFrom != nil {
+						t.Errorf("entry source unexpectedly has an import location: %#v", source.ImportedFrom)
+					}
+				} else if source.ImportedFrom == nil || source.ImportedFrom.SourceID != wantImportParents[index] || source.ImportedFrom.Line == 0 || source.ImportedFrom.Column == 0 {
+					t.Errorf("source %d import location = %#v, want declaration in %s", index, source.ImportedFrom, wantImportParents[index])
+				}
+			}
+		})
+	}
+}
+
+func TestFacadeSameFragmentMountsAtSeparateCollectionDestinations(t *testing.T) {
+	weatherDestination := configkit.Keys("collections", "weather", "prompts")
+	homeDestination := configkit.Keys("collections", "homewatch", "prompts")
+	result, err := configkit.LoadLayered(
+		configkit.Input{Source: configkit.NoSource()},
+		configkit.LayeredOptions[map[string]any]{Underlays: []configkit.Underlay{{Inputs: []configkit.Input{
+			{Source: configkit.Bytes("weather", []byte("summarize.alerts: {title: weather}\n")), Destination: weatherDestination},
+			{Source: configkit.Bytes("homewatch", []byte("summarize.alerts: {title: home}\n")), Destination: homeDestination},
+		}}}},
+	)
+	if err != nil {
+		t.Fatalf("LoadLayered: %v", err)
+	}
+	for _, test := range []struct {
+		path []string
+		want string
+	}{
+		{path: []string{"collections", "weather", "prompts", "summarize.alerts", "title"}, want: "weather"},
+		{path: []string{"collections", "homewatch", "prompts", "summarize.alerts", "title"}, want: "home"},
+	} {
+		if got := facadeDestinationValue(t, result.Config, test.path...); got != test.want {
+			t.Errorf("value at %v = %#v, want %q", test.path, got, test.want)
+		}
+	}
+	sources := result.Sources()
+	if len(sources) != 2 || sources[0].Destination.String() != weatherDestination.String() || sources[1].Destination.String() != homeDestination.String() {
+		t.Fatalf("independent collection source placements = %#v", sources)
+	}
+}
+
+type destinationCountingReader struct{ reads int }
+
+func (reader *destinationCountingReader) Read([]byte) (int, error) {
+	reader.reads++
+	return 0, io.EOF
+}
+
+func TestFacadeMountedMainAndUnderlayInspectionResourcesAndDiff(t *testing.T) {
+	t.Parallel()
+
+	filesystem := configkit.NewFilesystem("resources", fstest.MapFS{
+		"assets/summary.md": &fstest.MapFile{Data: []byte("source-relative summary")},
+	})
+	context := &configkit.FilesystemContext{Root: ".", BaseDir: "assets", FS: &filesystem}
+	destination := configkit.Keys("catalog", "entries")
+	tokenPath := configkit.Keys("catalog", "entries", "item", "token")
+	titlePath := configkit.Keys("catalog", "entries", "item", "title")
+	var callbacks struct{ resolve, validate int }
+	load := func(token string) *configkit.Result[map[string]any] {
+		t.Helper()
+		main := configkit.Input{
+			Source:      configkit.Bytes("main", []byte("item:\n  title: main\n  resource: summary.md\n  token: "+token+"\n")),
+			Destination: destination, Filesystem: context,
+		}
+		underlay := configkit.Input{
+			Source:      configkit.Bytes("underlay", []byte("item:\n  title: lower\n  retained: lower-value\n  token: LOWER-TOKEN-CANARY\n")),
+			Destination: destination,
+		}
+		result, err := configkit.LoadLayered(main, configkit.LayeredOptions[map[string]any]{
+			Underlays: []configkit.Underlay{{Inputs: []configkit.Input{underlay}}},
+			Definition: configkit.Definition[map[string]any]{
+				Resolve: func(configuration *map[string]any, resolution *configkit.Resolution) error {
+					callbacks.resolve++
+					resourcePath := configkit.Keys("catalog", "entries", "item", "resource")
+					input, ok := resolution.EntryInfo(resourcePath)
+					if !ok || len(input.Origin.Locations) != 1 {
+						return fmt.Errorf("mounted resource input has no single source origin")
+					}
+					source, ok := resolution.Source(input.Origin.Locations[0].SourceID)
+					if !ok || source.Destination.String() != destination.String() {
+						return fmt.Errorf("resolution source did not retain its destination")
+					}
+					resourceContext, ok := resolution.SourceContext(source.ID)
+					if !ok {
+						return fmt.Errorf("resolution source context is unavailable")
+					}
+					data, err := fs.ReadFile(resourceContext.FS, path.Join(resourceContext.BaseDir, "summary.md"))
+					if err != nil {
+						return fmt.Errorf("read source-relative resource: %w", err)
+					}
+					entry := facadeDestinationMap(t, facadeDestinationMap(t, facadeDestinationMap(t, *configuration, "catalog"), "entries"), "item")
+					entry["resource_text"] = string(data)
+					resolution.RecordNormalization(configkit.Keys("catalog", "entries", "item", "resource_text"), "read source-relative summary", resourcePath)
+					return nil
+				},
+				Validate:  func(*map[string]any, *configkit.Validation) { callbacks.validate++ },
+				Sensitive: func(candidate configkit.Path) bool { return candidate.String() == tokenPath.String() },
+			},
+		})
+		if err != nil {
+			t.Fatalf("mounted load: %v", err)
+		}
+		return result
+	}
+
+	first := load("FIRST-TOKEN-CANARY")
+	second := load("SECOND-TOKEN-CANARY")
+	if callbacks.resolve != 2 || callbacks.validate != 2 {
+		t.Fatalf("lifecycle callbacks = %#v", callbacks)
+	}
+	for _, result := range []*configkit.Result[map[string]any]{first, second} {
+		entry := facadeDestinationMap(t, facadeDestinationMap(t, facadeDestinationMap(t, result.Config, "catalog"), "entries"), "item")
+		if entry["title"] != "main" || entry["retained"] != "lower-value" || entry["resource_text"] != "source-relative summary" {
+			t.Fatalf("mounted main/underlay configuration = %#v", entry)
+		}
+		sources := result.Sources()
+		if len(sources) != 2 || sources[0].Destination.String() != destination.String() || sources[1].Destination.String() != destination.String() {
+			t.Fatalf("public source destinations = %#v", sources)
+		}
+		resource, ok := result.SourceContext(sources[0].ID)
+		if !ok || resource.BaseDir != "assets" {
+			t.Fatalf("completed source context = %#v, %v", resource, ok)
+		}
+		data, err := fs.ReadFile(resource.FS, path.Join(resource.BaseDir, "summary.md"))
+		if err != nil || string(data) != "source-relative summary" {
+			t.Fatalf("completed relative resource = %q, %v", data, err)
+		}
+		if info, ok := result.Metadata().Lookup(titlePath); !ok || info.Origin.Layer != configkit.LayerMain {
+			t.Fatalf("mounted title metadata = %#v, %v", info, ok)
+		}
+		if history := result.Metadata().History(titlePath); len(history) < 2 {
+			t.Fatalf("mounted title history = %#v", history)
+		}
+		if explanation, ok := result.Explain(tokenPath); !ok || !explanation.Effective.Redacted {
+			t.Fatalf("mounted secret explanation = %#v, %v", explanation, ok)
+		}
+		var effective, explanation bytes.Buffer
+		if err := result.WriteEffective(&effective); err != nil {
+			t.Fatal(err)
+		}
+		if err := result.WriteExplanation(&explanation, tokenPath); err != nil {
+			t.Fatal(err)
+		}
+		output := effective.String() + explanation.String()
+		for _, canary := range []string{"FIRST-TOKEN-CANARY", "SECOND-TOKEN-CANARY", "LOWER-TOKEN-CANARY"} {
+			if strings.Contains(output, canary) {
+				t.Fatalf("public inspection leaked %q: %s", canary, output)
+			}
+		}
+	}
+
+	// Mutating published records and query copies must not alter the retained result.
+	returnedSources := first.Sources()
+	returnedSources[0].Destination = configkit.Keys("mutated")
+	if got := first.Sources()[0].Destination.String(); got != destination.String() {
+		t.Fatalf("source destination changed after caller mutation: %q", got)
+	}
+	info, ok := first.Metadata().Lookup(titlePath)
+	if !ok {
+		t.Fatal("mounted metadata lookup failed")
+	}
+	info.Origin.Locations[0].SourceID = "mutated"
+	if fresh, ok := first.Metadata().Lookup(titlePath); !ok || fresh.Origin.Locations[0].SourceID == "mutated" {
+		t.Fatalf("metadata copy mutation escaped: %#v, %v", fresh, ok)
+	}
+	history := first.Metadata().History(titlePath)
+	if len(history) == 0 {
+		t.Fatal("mounted history is empty")
+	}
+	history[0].Path = configkit.Keys("mutated")
+	if fresh := first.Metadata().History(titlePath); len(fresh) == 0 || fresh[0].Path.String() != titlePath.String() {
+		t.Fatalf("history copy mutation escaped: %#v", fresh)
+	}
+
+	differences, err := configkit.Diff(first, second)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(differences) != 1 || differences[0].Path.String() != tokenPath.String() ||
+		!differences[0].Left.Redacted || !differences[0].Right.Redacted ||
+		strings.Contains(differences[0].Left.YAML+differences[0].Right.YAML, "TOKEN-CANARY") {
+		t.Fatalf("public mounted secret diff = %#v", differences)
+	}
+	if callbacks.resolve != 2 || callbacks.validate != 2 {
+		t.Fatalf("inspection reran lifecycle callbacks: %#v", callbacks)
+	}
+}
+
+func TestFacadeFailedLoadExposesDetachedSourceDestination(t *testing.T) {
+	type configuration struct {
+		Tenant struct {
+			Count int `yaml:"count"`
+		} `yaml:"tenant"`
+	}
+	destination := configkit.Keys("tenant")
+	_, err := configkit.LoadLayered[configuration](configkit.Input{
+		Source: configkit.Bytes("invalid", []byte("count: not-an-integer\n")), Destination: destination,
+	})
+	loadError, ok := err.(*configkit.LoadError)
+	if !ok {
+		t.Fatalf("failed load error = %T %v", err, err)
+	}
+	sources := loadError.Sources()
+	if len(sources) != 1 || sources[0].Destination.String() != destination.String() {
+		t.Fatalf("failed source destinations = %#v", sources)
+	}
+	sources[0].Destination = configkit.Keys("caller-change")
+	if fresh := loadError.Sources(); len(fresh) != 1 || fresh[0].Destination.String() != destination.String() {
+		t.Fatalf("failed source destination was not detached: %#v", fresh)
+	}
+}
+
+func TestFacadeRelativeImportFailuresRetainSourceRecordsAndCoordinates(t *testing.T) {
+	directory := t.TempDir()
+	write := func(name, contents string) string {
+		t.Helper()
+		filename := filepath.Join(directory, name)
+		if err := os.MkdirAll(filepath.Dir(filename), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filename, []byte(contents), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		return filename
+	}
+
+	t.Run("imported parse failure retains effective source destination", func(t *testing.T) {
+		mainPath := write("parse/main.yml", "configkit:\n  imports:\n    - path: child.yml\n      destination: [tenant]\n")
+		childPath := write("parse/child.yml", "count: [unterminated\n")
+		_, err := configkit.LoadLayered[map[string]any](configkit.Input{
+			Source: configkit.File(mainPath), Imports: true, Destination: configkit.Keys("mount"),
+		})
+		var loadError *configkit.LoadError
+		if !errors.As(err, &loadError) {
+			t.Fatalf("load error = %T %v", err, err)
+		}
+		diagnostics := loadError.Diagnostics()
+		if len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeYAMLInvalid || diagnostics[0].Primary == nil || diagnostics[0].Primary.SourceID != "source-2" {
+			t.Fatalf("imported parse diagnostic = %#v", diagnostics)
+		}
+		sources := loadError.Sources()
+		if len(sources) != 2 || sources[0].Destination.String() != "/mount" || sources[1].Destination.String() != "/mount/tenant" || sources[1].Path != childPath {
+			t.Fatalf("imported parse failure sources = %#v", sources)
+		}
+	})
+
+	t.Run("directive failure stays source local", func(t *testing.T) {
+		mainPath := write("directive/main.yml", "configkit:\n  imports:\n    - path: parent.yml\n      destination: [tenant]\n")
+		parentPath := write("directive/parent.yml", "configkit:\n  imports:\n    - path: details.yml\n      destination: [3]\n")
+		_, err := configkit.LoadLayered[map[string]any](configkit.Input{
+			Source: configkit.File(mainPath), Imports: true, Destination: configkit.Keys("mount"),
+		})
+		var loadError *configkit.LoadError
+		if !errors.As(err, &loadError) {
+			t.Fatalf("load error = %T %v", err, err)
+		}
+		diagnostics := loadError.Diagnostics()
+		wantPath := configkit.Keys("configkit", "imports").Index(0).Key("destination").Index(0)
+		if len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeImportInvalid || !reflect.DeepEqual(diagnostics[0].Path, wantPath) || diagnostics[0].Primary == nil || diagnostics[0].Primary.SourceID != "source-2" {
+			t.Fatalf("import directive diagnostic = %#v", diagnostics)
+		}
+		sources := loadError.Sources()
+		if len(sources) != 2 || sources[0].Destination.String() != "/mount" || sources[1].Destination.String() != "/mount/tenant" || sources[1].Path != parentPath {
+			t.Fatalf("directive failure sources = %#v", sources)
+		}
+	})
+
+	t.Run("composition failure reports effective path and all sources", func(t *testing.T) {
+		mainPath := write("compose/main.yml", "configkit:\n  imports:\n    - path: left.yml\n      destination: [tenant]\n    - path: right.yml\n      destination: [tenant]\n")
+		write("compose/left.yml", "value: same\n")
+		write("compose/right.yml", "value: same\n")
+		_, err := configkit.LoadLayered[map[string]any](configkit.Input{
+			Source: configkit.File(mainPath), Imports: true, Destination: configkit.Keys("mount"),
+		})
+		var loadError *configkit.LoadError
+		if !errors.As(err, &loadError) {
+			t.Fatalf("load error = %T %v", err, err)
+		}
+		diagnostics := loadError.Diagnostics()
+		if len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeComposeConflict || diagnostics[0].Path.String() != "/mount/tenant/value" {
+			t.Fatalf("composition diagnostic = %#v", diagnostics)
+		}
+		sources := loadError.Sources()
+		if len(sources) != 3 || sources[0].Destination.String() != "/mount" || sources[1].Destination.String() != "/mount/tenant" || sources[2].Destination.String() != "/mount/tenant" {
+			t.Fatalf("composition failure sources = %#v", sources)
+		}
+	})
+
+	t.Run("version failure reports effective path and imported source", func(t *testing.T) {
+		mainPath := write("version/main.yml", "configkit:\n  imports:\n    - path: child.yml\n      destination: [tenant]\n")
+		childPath := write("version/child.yml", "version: forbidden\n")
+		_, err := configkit.LoadLayered[map[string]any](configkit.Input{
+			Source: configkit.File(mainPath), Imports: true, Destination: configkit.Keys("mount"),
+		}, configkit.LayeredOptions[map[string]any]{
+			Definition: configkit.Definition[map[string]any]{Version: &configkit.VersionRule{
+				Path:  configkit.Keys("mount", "tenant", "version"),
+				Check: func(configkit.Version, *configkit.Validation) error { return nil },
+			}},
+		})
+		var loadError *configkit.LoadError
+		if !errors.As(err, &loadError) {
+			t.Fatalf("load error = %T %v", err, err)
+		}
+		diagnostics := loadError.Diagnostics()
+		if len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeImportVersion || diagnostics[0].Path.String() != "/mount/tenant/version" || diagnostics[0].Primary == nil || diagnostics[0].Primary.SourceID != "source-2" {
+			t.Fatalf("version diagnostic = %#v", diagnostics)
+		}
+		sources := loadError.Sources()
+		if len(sources) != 2 || sources[0].Destination.String() != "/mount" || sources[1].Destination.String() != "/mount/tenant" || sources[1].Path != childPath {
+			t.Fatalf("version failure sources = %#v", sources)
+		}
+	})
+
+	t.Run("typed validation reports effective path and authored location", func(t *testing.T) {
+		type configuration struct {
+			Mount struct {
+				Tenant struct {
+					Count int `yaml:"count"`
+				} `yaml:"tenant"`
+			} `yaml:"mount"`
+		}
+		mainPath := write("typed/main.yml", "configkit:\n  imports:\n    - path: child.yml\n      destination: [tenant]\n")
+		childPath := write("typed/child.yml", "count: invalid\n")
+		_, err := configkit.LoadLayered[configuration](configkit.Input{
+			Source: configkit.File(mainPath), Imports: true, Destination: configkit.Keys("mount"),
+		})
+		var loadError *configkit.LoadError
+		if !errors.As(err, &loadError) {
+			t.Fatalf("load error = %T %v", err, err)
+		}
+		diagnostics := loadError.Diagnostics()
+		if len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeDecodeType || diagnostics[0].Path.String() != "/mount/tenant/count" || diagnostics[0].Primary == nil || diagnostics[0].Primary.SourceID != "source-2" || diagnostics[0].Primary.Line != 1 {
+			t.Fatalf("typed validation diagnostic = %#v", diagnostics)
+		}
+		sources := loadError.Sources()
+		if len(sources) != 2 || sources[0].Destination.String() != "/mount" || sources[1].Destination.String() != "/mount/tenant" || sources[1].Path != childPath {
+			t.Fatalf("typed validation sources = %#v", sources)
+		}
+	})
+}
+
+func TestFacadeDestinationMappingFailurePaths(t *testing.T) {
+	t.Parallel()
+
+	cycle := map[string]any{}
+	cycle["self"] = cycle
+	for _, fixture := range []struct {
+		name   string
+		values map[string]any
+		path   func(configkit.Path) configkit.Path
+	}{
+		{
+			name:   "unsupported nested sequence value",
+			values: map[string]any{"a/b": []any{map[string]any{"~": func() {}}}},
+			path:   func(base configkit.Path) configkit.Path { return base.Key("a/b").Index(0).Key("~") },
+		},
+		{
+			name:   "cyclic value",
+			values: map[string]any{"item": cycle},
+			path:   func(base configkit.Path) configkit.Path { return base.Key("item").Key("self") },
+		},
+		{
+			name: "constructor failure keeps source coordinates",
+			path: func(configkit.Path) configkit.Path { return configkit.Path{} },
+		},
+	} {
+		t.Run(fixture.name, func(t *testing.T) {
+			for _, role := range []string{"root", "mounted main", "mounted underlay"} {
+				t.Run(role, func(t *testing.T) {
+					var destination configkit.Path
+					if role != "root" {
+						destination = configkit.Keys("catalog", "entries")
+					}
+					wantPath := fixture.path(destination)
+					input := configkit.Input{Source: configkit.Mapping("invalid mapping", fixture.values), Destination: destination}
+					var result *configkit.Result[map[string]any]
+					var err error
+					if role == "mounted underlay" {
+						result, err = configkit.LoadLayered(configkit.Input{Source: configkit.NoSource()}, configkit.LayeredOptions[map[string]any]{
+							Underlays: []configkit.Underlay{{Inputs: []configkit.Input{input}}},
+						})
+					} else {
+						result, err = configkit.LoadLayered[map[string]any](input)
+					}
+					var loadError *configkit.LoadError
+					if result != nil || !errors.As(err, &loadError) {
+						t.Fatalf("failed load = %#v, %v", result, err)
+					}
+					diagnostics := loadError.Diagnostics()
+					if len(diagnostics) != 1 {
+						t.Fatalf("diagnostics = %#v", diagnostics)
+					}
+					diagnostic := diagnostics[0]
+					if diagnostic.Code != configkit.CodeSourceInvalid || !reflect.DeepEqual(diagnostic.Path, wantPath) {
+						t.Fatalf("diagnostic = %#v; want source.invalid at %q", diagnostic, wantPath.String())
+					}
+					if diagnostic.Primary == nil || *diagnostic.Primary != (configkit.Location{SourceID: "source-1"}) || len(diagnostic.Related) != 0 {
+						t.Fatalf("mapping source locations = %#v, %#v", diagnostic.Primary, diagnostic.Related)
+					}
+					sources := loadError.Sources()
+					if len(sources) != 1 || sources[0].ID != "source-1" || sources[0].Destination.String() != destination.String() {
+						t.Fatalf("error sources = %#v", sources)
+					}
+				})
+			}
+		})
+	}
+}
+
+func facadeDestinationMap(t *testing.T, value map[string]any, keys ...string) map[string]any {
+	t.Helper()
+	for _, key := range keys {
+		child, ok := value[key].(map[string]any)
+		if !ok {
+			t.Fatalf("%q = %#v, want mapping", key, value[key])
+		}
+		value = child
+	}
+	return value
+}
+
+func facadeDestinationValue(t *testing.T, value map[string]any, keys ...string) any {
+	t.Helper()
+	return facadeDestinationMap(t, value, keys[:len(keys)-1]...)[keys[len(keys)-1]]
+}

facade_diagnostic_order_test.go

@@ -0,0 +1,95 @@
+package configkit_test
+
+import (
+	"bytes"
+	"errors"
+	"strings"
+	"testing"
+	"testing/fstest"
+
+	configkit "go.maximumdirect.net/configkit"
+)
+
+func TestFacadeCompositionConflictKeepsClaimantOrder(t *testing.T) {
+	filesystem := configkit.NewFilesystem("bundle", fstest.MapFS{
+		"a.yml": &fstest.MapFile{Data: []byte(`configkit:
+  imports:
+    - path: z.yml
+`)},
+		"b.yml": &fstest.MapFile{Data: []byte("x: b\n")},
+		"c.yml": &fstest.MapFile{Data: []byte("x: c\n")},
+		"z.yml": &fstest.MapFile{Data: []byte("x: z\n")},
+	})
+	main := configkit.Mapping("main", map[string]any{
+		"configkit": map[string]any{"imports": []any{
+			map[string]any{"path": "a.yml"},
+			map[string]any{"path": "b.yml"},
+			map[string]any{"path": "c.yml"},
+		}},
+	})
+	_, err := configkit.Load[map[string]any](main, configkit.Options[map[string]any]{
+		Imports: true,
+		Filesystem: &configkit.FilesystemContext{
+			FS: &filesystem, Root: ".", BaseDir: ".",
+		},
+	})
+	var loadError *configkit.LoadError
+	if !errors.As(err, &loadError) {
+		t.Fatalf("Load error = %v, want composition LoadError", err)
+	}
+	diagnostics := loadError.Diagnostics()
+	if len(diagnostics) != 1 {
+		t.Fatalf("diagnostics = %#v, want one composition conflict", diagnostics)
+	}
+	diagnostic := diagnostics[0]
+	if diagnostic.Code != configkit.CodeComposeConflict || diagnostic.Path.String() != "/x" || diagnostic.Primary == nil {
+		t.Fatalf("composition diagnostic = %#v", diagnostic)
+	}
+
+	pathsByID := make(map[string]string)
+	var acquisitionOrder []string
+	for _, source := range loadError.Sources() {
+		pathsByID[source.ID] = source.Path
+		for _, name := range []string{"z.yml", "b.yml", "c.yml"} {
+			if source.Path == name || strings.HasSuffix(source.Path, "/"+name) {
+				acquisitionOrder = append(acquisitionOrder, strings.TrimSuffix(name, ".yml"))
+				break
+			}
+		}
+	}
+	if strings.Join(acquisitionOrder, ",") != "z,b,c" {
+		t.Fatalf("claimant acquisition order = %v, want z,b,c", acquisitionOrder)
+	}
+	claimant := func(location configkit.Location) string {
+		for _, name := range []string{"b.yml", "c.yml", "z.yml"} {
+			if pathsByID[location.SourceID] == name || strings.HasSuffix(pathsByID[location.SourceID], "/"+name) {
+				return strings.TrimSuffix(name, ".yml")
+			}
+		}
+		return ""
+	}
+	if got := claimant(*diagnostic.Primary); got != "b" {
+		t.Fatalf("primary claimant = %q, want b (sources: %#v)", got, pathsByID)
+	}
+	if len(diagnostic.Related) != 2 || claimant(diagnostic.Related[0]) != "c" || claimant(diagnostic.Related[1]) != "z" {
+		t.Fatalf("related claimants = %#v, want c then z", diagnostic.Related)
+	}
+
+	var output bytes.Buffer
+	if err := configkit.WriteDiagnostics(&output, diagnostics); err != nil {
+		t.Fatal(err)
+	}
+	positions := []int{
+		strings.Index(output.String(), diagnostic.Primary.SourceID),
+		strings.Index(output.String(), diagnostic.Related[0].SourceID),
+		strings.Index(output.String(), diagnostic.Related[1].SourceID),
+	}
+	if positions[0] < 0 || positions[1] <= positions[0] || positions[2] <= positions[1] {
+		t.Fatalf("rendered claimant order = %v in %q", positions, output.String())
+	}
+
+	diagnostics[0].Related[0].SourceID = "mutated"
+	if got := claimant(loadError.Diagnostics()[0].Related[0]); got != "c" {
+		t.Fatalf("LoadError.Diagnostics retained caller mutation; first claimant = %q", got)
+	}
+}

facade_diff_test.go

@@ -0,0 +1,327 @@
+package configkit_test
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	configkit "go.maximumdirect.net/configkit"
+)
+
+type facadeDiffConfig struct {
+	Value   string         `yaml:"value"`
+	Count   int            `yaml:"count"`
+	Items   []string       `yaml:"items"`
+	Dynamic map[string]any `yaml:"dynamic"`
+}
+
+type facadeDiffSecretConfig struct {
+	Secret configkit.Secret `yaml:"secret"`
+}
+
+func TestFacadeDiffKeepsPublicSequenceChangesWithHistoricalDescendants(t *testing.T) {
+	type configuration struct {
+		Items []any `yaml:"items"`
+	}
+	load := func(public string) *configkit.Result[configuration] {
+		t.Helper()
+		result, err := configkit.Load(configkit.Bytes("historical-sequence.yml", []byte("items: [{secret: disposable-canary}, "+public+"]\n")),
+			configkit.Options[configuration]{Definition: configkit.Definition[configuration]{
+				Sensitive: func(path configkit.Path) bool { return path.String() == "/items/0/secret" },
+				Resolve: func(current *configuration, resolution *configkit.Resolution) error {
+					current.Items[0] = "public scalar"
+					resolution.RecordNormalization(configkit.Keys("items"), "normalize first item")
+					return nil
+				},
+			}})
+		if err != nil {
+			t.Fatal(err)
+		}
+		return result
+	}
+	left, right := load("1"), load("2")
+	history, ok := left.Explain(configkit.Keys("items").Index(0).Key("secret"))
+	if !ok || history.Effective.Present || len(history.History) == 0 {
+		t.Fatalf("removed historical secret = %#v, known=%v", history, ok)
+	}
+	maskedHistory := false
+	for _, change := range history.History {
+		maskedHistory = maskedHistory || change.Before.Redacted || change.After.Redacted
+	}
+	if !maskedHistory {
+		t.Fatal("historical sensitivity was not retained")
+	}
+	differences, err := configkit.Diff(left, right)
+	if err != nil || len(differences) != 1 || differences[0].Path.String() != "/items" {
+		t.Fatalf("sequence difference = %#v, %v", differences, err)
+	}
+	difference := differences[0]
+	if !difference.Left.Present || !difference.Right.Present || difference.Left.Redacted || difference.Right.Redacted || difference.HiddenChanged {
+		t.Fatalf("public sequence change was concealed: %#v", difference)
+	}
+	if difference.Left.YAML != "- public scalar\n- 1\n" || difference.Right.YAML != "- public scalar\n- 2\n" {
+		t.Fatalf("public sequence snapshots = %#v", difference)
+	}
+}
+
+func TestFacadeDiffKeepsPublicScalarAcrossHistoricalAbsence(t *testing.T) {
+	type configuration struct {
+		Dynamic map[string]any `yaml:"dynamic"`
+	}
+	options := configkit.Options[configuration]{Definition: configkit.Definition[configuration]{
+		Sensitive: func(path configkit.Path) bool { return path.String() == "/dynamic/entry/token" },
+		Resolve: func(current *configuration, resolution *configkit.Resolution) error {
+			delete(current.Dynamic, "entry")
+			resolution.RecordNormalization(configkit.Keys("dynamic", "entry"), "remove entry")
+			return nil
+		},
+	}}
+	absent, err := configkit.Load(configkit.Bytes("removed-entry.yml", []byte("dynamic: {entry: {token: disposable-canary}}\n")), options)
+	if err != nil {
+		t.Fatal(err)
+	}
+	options.Definition.Resolve = nil
+	present, err := configkit.Load(configkit.Bytes("public-entry.yml", []byte("dynamic: {entry: public}\n")), options)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, test := range []struct {
+		name        string
+		left, right *configkit.Result[configuration]
+		leftPresent bool
+	}{
+		{name: "addition", left: absent, right: present},
+		{name: "removal", left: present, right: absent, leftPresent: true},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			differences, err := configkit.Diff(test.left, test.right)
+			if err != nil || len(differences) != 1 || differences[0].Path.String() != "/dynamic/entry" {
+				t.Fatalf("entry difference = %#v, %v", differences, err)
+			}
+			difference := differences[0]
+			if difference.Left.Present != test.leftPresent || difference.Right.Present == test.leftPresent ||
+				difference.Left.Redacted || difference.Right.Redacted || difference.HiddenChanged {
+				t.Fatalf("public presence change was concealed: %#v", difference)
+			}
+			wantLeft, wantRight := "", "public\n"
+			if test.leftPresent {
+				wantLeft, wantRight = wantRight, wantLeft
+			}
+			if difference.Left.YAML != wantLeft || difference.Right.YAML != wantRight {
+				t.Fatalf("entry snapshots = %#v", difference)
+			}
+		})
+	}
+}
+
+func TestFacadeDiffReturnsDetachedCanonicalRecords(t *testing.T) {
+	left, err := configkit.Load[facadeDiffConfig](configkit.Bytes("left.yml", []byte("value: before\ncount: 0\nitems: [one, two]\ndynamic: {}\n")))
+	if err != nil {
+		t.Fatalf("load left: %v", err)
+	}
+	right, err := configkit.Load[facadeDiffConfig](configkit.Bytes("right.yml", []byte("value: after\ncount: 0\nitems: [one, three]\ndynamic:\n  added: null\n")))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	differences, err := configkit.Diff(left, right)
+	if err != nil {
+		t.Fatal(err)
+	}
+	wantPaths := []string{"/dynamic/added", "/items", "/value"}
+	if len(differences) != len(wantPaths) {
+		t.Fatalf("differences = %#v", differences)
+	}
+	for index, difference := range differences {
+		if got := difference.Path.String(); got != wantPaths[index] {
+			t.Errorf("path[%d] = %q, want %q", index, got, wantPaths[index])
+		}
+	}
+	if differences[0].Left.Present || !differences[0].Right.Present || differences[0].Right.YAML != "null\n" {
+		t.Errorf("null/absence snapshots = %#v / %#v", differences[0].Left, differences[0].Right)
+	}
+	if differences[1].Left.YAML != "- one\n- two\n" || differences[1].Right.YAML != "- one\n- three\n" {
+		t.Errorf("sequence snapshots = %#v / %#v", differences[1].Left, differences[1].Right)
+	}
+
+	left.Config.Value = "caller mutation"
+	left.Config.Items[0] = "caller mutation"
+	right.Config.Dynamic["added"] = "caller mutation"
+	differences[2].Left.YAML = "record mutation"
+	differences[2].Path = configkit.Keys("rewritten")
+
+	again, err := configkit.Diff(left, right)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if again[2].Path.String() != "/value" || again[2].Left.YAML != "before\n" || again[1].Left.YAML != "- one\n- two\n" {
+		t.Fatalf("repeat diff changed = %#v", again)
+	}
+	explanation, ok := left.Explain(configkit.Keys("value"))
+	if !ok || explanation.Effective.YAML != "before\n" {
+		t.Fatalf("frozen explanation = %#v, %v", explanation, ok)
+	}
+}
+
+func TestFacadeDiffRejectsUnavailableResults(t *testing.T) {
+	type config struct {
+		Value string `yaml:"value"`
+	}
+	loaded, err := configkit.Load[config](configkit.Bytes("valid.yml", []byte("value: valid\n")))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var nilResult *configkit.Result[config]
+	zeroResult := &configkit.Result[config]{Config: config{Value: "must not be inspected"}}
+	for name, left := range map[string]*configkit.Result[config]{"nil": nilResult, "zero": zeroResult} {
+		t.Run(name, func(t *testing.T) {
+			if records, err := configkit.Diff(left, loaded); err == nil || records != nil {
+				t.Fatalf("Diff = %#v, %v; want nil records and error", records, err)
+			}
+		})
+	}
+	if records, err := configkit.Diff(loaded, nilResult); err == nil || records != nil {
+		t.Fatalf("right nil Diff = %#v, %v", records, err)
+	}
+}
+
+func TestFacadeDiffIgnoresSourceAndResolutionHistory(t *testing.T) {
+	type config struct {
+		Count int `yaml:"count"`
+	}
+	defaults := configkit.Options[config]{Definition: configkit.Definition[config]{
+		Defaults: func() config { return config{Count: 7} },
+	}}
+	defaulted, err := configkit.Load[config](configkit.NoSource(), defaults)
+	if err != nil {
+		t.Fatal(err)
+	}
+	explicit, err := configkit.Load[config](configkit.Bytes("explicit.yml", []byte("count: 7\n")))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if differences, err := configkit.Diff(defaulted, explicit); err != nil || len(differences) != 0 {
+		t.Fatalf("default/source difference = %#v, %v", differences, err)
+	}
+
+	zeroDefault, err := configkit.Load[config](configkit.NoSource(), configkit.Options[config]{Definition: configkit.Definition[config]{Defaults: func() config { return config{} }}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	explicitZero, err := configkit.Load[config](configkit.Bytes("explicit-zero.yml", []byte("count: 0\n")))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if differences, err := configkit.Diff(zeroDefault, explicitZero); err != nil || len(differences) != 0 {
+		t.Fatalf("explicit/defaulted zero difference = %#v, %v", differences, err)
+	}
+
+	resolve := func(value string) configkit.Options[config] {
+		return configkit.Options[config]{Definition: configkit.Definition[config]{Resolve: func(current *config, resolution *configkit.Resolution) error {
+			current.Count = len(value) + 8
+			resolution.RecordNormalization(configkit.Keys("count"), "set effective count")
+			return nil
+		}}}
+	}
+	resolvedA, err := configkit.Load[config](configkit.Bytes("a.yml", []byte("{}\n")), resolve("a"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	resolvedB, err := configkit.Load[config](configkit.Bytes("b.yml", []byte("{}\n")), resolve("b"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if differences, err := configkit.Diff(resolvedA, resolvedB); err != nil || len(differences) != 0 {
+		t.Fatalf("equal resolved values = %#v, %v", differences, err)
+	}
+}
+
+func TestFacadeDiffUsesFrozenFilesAndRunsCallbacksOnlyDuringLoad(t *testing.T) {
+	type config struct {
+		Value string `yaml:"value"`
+	}
+	calls := 0
+	options := configkit.Options[config]{Definition: configkit.Definition[config]{Defaults: func() config {
+		calls++
+		return config{}
+	}}}
+	dir := t.TempDir()
+	paths := []string{filepath.Join(dir, "left.yml"), filepath.Join(dir, "right.yml")}
+	for index, contents := range []string{"value: left\n", "value: right\n"} {
+		if err := os.WriteFile(paths[index], []byte(contents), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	left, err := configkit.Load[config](configkit.File(paths[0]), options)
+	if err != nil {
+		t.Fatal(err)
+	}
+	right, err := configkit.Load[config](configkit.File(paths[1]), options)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if calls != 2 {
+		t.Fatalf("defaults calls after loads = %d", calls)
+	}
+	for _, path := range paths {
+		if err := os.Remove(path); err != nil {
+			t.Fatal(err)
+		}
+	}
+	differences, err := configkit.Diff(left, right)
+	if err != nil || len(differences) != 1 || differences[0].Path.String() != "/value" {
+		t.Fatalf("Diff after removing files = %#v, %v", differences, err)
+	}
+	if calls != 2 {
+		t.Fatalf("defaults reran during Diff: %d calls", calls)
+	}
+}
+
+func TestFacadeDiffCombinesSecretSensitivityAndLoadErrors(t *testing.T) {
+	t.Setenv("FACADE_DIFF_SECRET", "credential-one")
+	secretOptions := configkit.Options[facadeDiffSecretConfig]{Definition: configkit.Definition[facadeDiffSecretConfig]{Sensitive: func(path configkit.Path) bool {
+		return path.String() == "/secret"
+	}}}
+	left, err := configkit.Load[facadeDiffSecretConfig](configkit.Bytes("left.yml", []byte("secret: FACADE_DIFF_SECRET\n")), secretOptions)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("FACADE_DIFF_SECRET", "credential-two")
+	right, err := configkit.Load[facadeDiffSecretConfig](configkit.Bytes("right.yml", []byte("secret: FACADE_DIFF_SECRET\n")), secretOptions)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if differences, err := configkit.Diff(left, right); err != nil || len(differences) != 0 {
+		t.Fatalf("credential rotation = %#v, %v", differences, err)
+	}
+	t.Setenv("OTHER_FACADE_DIFF_SECRET", "other-credential")
+	otherReference, err := configkit.Load[facadeDiffSecretConfig](configkit.Bytes("other.yml", []byte("secret: OTHER_FACADE_DIFF_SECRET\n")), secretOptions)
+	if err != nil {
+		t.Fatal(err)
+	}
+	differences, err := configkit.Diff(left, otherReference)
+	if err != nil || len(differences) != 1 || !differences[0].HiddenChanged || !differences[0].Left.Redacted || !differences[0].Right.Redacted {
+		t.Fatalf("reference change = %#v, %v", differences, err)
+	}
+	if strings.Contains(differences[0].Left.YAML+differences[0].Right.YAML, "credential") {
+		t.Fatalf("credential leaked: %#v", differences)
+	}
+
+	invalidLeft, leftErr := configkit.Load[facadeDiffSecretConfig](configkit.Bytes("invalid-left.yml", []byte("unknown: true\n")))
+	if invalidLeft != nil || leftErr == nil {
+		t.Fatalf("invalid left load = %#v, %v", invalidLeft, leftErr)
+	}
+	var loadError *configkit.LoadError
+	if !errors.As(leftErr, &loadError) {
+		t.Fatalf("left load error = %T, want *configkit.LoadError", leftErr)
+	}
+	invalidRight, rightErr := configkit.Load[facadeDiffSecretConfig](configkit.Bytes("invalid-right.yml", []byte("unknown: true\n")))
+	if invalidRight != nil || rightErr == nil {
+		t.Fatalf("invalid right load = %#v, %v", invalidRight, rightErr)
+	}
+	if !errors.As(rightErr, &loadError) {
+		t.Fatalf("right load error = %T, want *configkit.LoadError", rightErr)
+	}
+}