Apply explicit CLI configuration overrides

docs/config.md

@@ -41,7 +41,8 @@ The current lifecycle is:
 ```text
 validate options → parse the selected source → traverse/compose enabled imports
   → build schema → check the optional application version → apply a selected profile
-  → create and clone defaults → strictly decode → recorded application resolution
+  → apply explicit CLI overrides → create and clone defaults → strictly decode
+  → recorded application resolution
   → resolve typed secret references → semantic validation → classify secrets
   → snapshot configuration and metadata
 ```
@@ -54,11 +55,11 @@ missing file remains an error; it is never interpreted as no input.
 
 The current `Options` boundary accepts a defaults factory, `VersionRule`, resolver,
 semantic validator, explicit path and glob imports, one selected profile, and
-filesystem context. It also accepts static secret tags and a dynamic path predicate.
-Overrides return `options.unavailable` because their lifecycle stage is not
-implemented. `NoSource` rejects imports, active profiles, and filesystem context as
-invalid combinations. Input containing a reserved `_configkit` mapping key is
-rejected while imports are disabled.
+filesystem context. It also accepts explicit CLI override records, static secret
+tags, and a dynamic path predicate. `NoSource` rejects imports, active profiles,
+and filesystem context as invalid combinations but accepts overrides. Input
+containing a reserved `_configkit` mapping key is rejected while imports are
+disabled.
 
 Every source, options, schema, version, defaults, decode, resolution, or validation
 failure returns a nil result and a `*LoadError`. Successful results contain caller-owned `Config`, detached
@@ -106,8 +107,8 @@ by the profile location; an empty mapping is still an explicit container even th
 it contributes no children. Resolution origins are synthetic: they have layer
 `resolution`, no fabricated file location, and a `derived_default` or `normalization`
 operation. Reasons and dependency paths retain first occurrence order with duplicates
-removed. Source records remain ordered as selected source, depth-first imports, then
-the selected profile.
+removed. Source records remain ordered as selected source, depth-first imports, the
+selected profile, then synthetic CLI records in supplied order.
 
 ### Secret classification and effective rendering
 
@@ -354,6 +355,54 @@ version, or replace an ancestor of that version with a scalar or null. These rul
 apply even if the supplied version text would be unchanged. Profiles cannot mask a
 base parse, composition, or version failure because those checks run first.
 
+## Explicit CLI overrides
+
+`Options.Overrides` accepts only records the application knows were explicitly set
+by its CLI parser. Each `Override` supplies a non-root mapping `Path`, a detached
+`Value`, and a required safe display `Flag` such as `--workers`; ConfigKit has no CLI
+parser dependency. Parser defaults must not be submitted as overrides, and `Flag`
+must never contain the raw argument or configured value. General environment
+variable overlays are an explicit non-goal: environment access is reserved for
+typed secret references.
+
+Overrides apply after the selected profile and before typed defaults/decoding, so
+the input precedence is application defaults < composed base < selected profile <
+CLI. Recorded resolution, typed secret lookup, and semantic validation follow the
+effective override tree. Overrides also work with `NoSource`.
+
+Values are converted directly into ConfigKit's owned tree without YAML parsing or
+string coercion. Supported values are `nil`, built-in strings and booleans, all
+built-in signed and unsigned integer widths except `uintptr`, finite `float32` and
+`float64`, and recursive `[]any`/`map[string]any`. Strings stay strings; duration and
+secret fields therefore receive string values. Nil is explicit null; empty strings,
+false, and zero remain intentional; empty sequences replace whole lists; and mapping
+values recursively overlay existing mappings. Map keys are sorted canonically and
+sequence order is preserved.
+
+All records are detached and validated before any is applied. Root and explicit
+sequence-index paths are invalid; parsed numeric tokens remain mapping keys. A path
+may create missing mapping ancestors but cannot traverse an existing scalar, null,
+or sequence. Duplicate and ancestor/descendant-overlapping records are rejected.
+Neither paths nor values may create `_configkit`, and no record may overlap the
+configured schema-version path. Unknown fields and effective type mismatches remain
+ordinary strict-decoder errors.
+
+At most 1,024 records are accepted, and each record creates one synthetic CLI
+source after file/profile sources in supplied order. Override sources share the
+1,024-source ceiling. A record has an 8 MiB string-byte limit; override strings and
+source bytes share the 64 MiB aggregate limit. Synthetic mapping keys and values
+count toward the existing 1,000,000-node and depth-256 ceilings. Cycles, named or
+unsupported types, nonfinite floats, and limit excesses fail with safe `override.*`
+diagnostics. Diagnostics and provenance identify the safe `Flag` source, never raw
+arguments or values.
+
+Override origins are explicit CLI origins. History retains replaced base/profile
+definitions and records equal-value replacements as well as structural changes.
+Caller-owned maps and slices are snapshotted during loading and must not be mutated
+concurrently with the call. The executable `ExampleOverride` shows translating a
+parser's explicit-set state into records while preserving an explicitly supplied
+zero.
+
 ## Explicit imports
 
 Imports are opt-in. With `Options.Imports` enabled, a document may reserve its root