Build reusable schema descriptors

docs/config.md

@@ -69,6 +69,41 @@ boolean/null words are rejected unless quoted.
 Mapping keys use the same scalar classification and must classify as strings. Quote
 keys that otherwise classify as a boolean, number, or null.
 
+## Application schema binding
+
+ConfigKit builds a private reflection descriptor graph for each schema operation;
+it keeps no global mutable descriptor cache. A configuration root must be a struct
+or string-keyed map. Nested supported shapes are:
+
+- booleans, strings, signed and unsigned integers, and finite floating-point types;
+- `time.Duration` and paired `encoding.TextMarshaler`/`TextUnmarshaler` scalars;
+- pointers, structs, string-keyed maps, slices, fixed arrays, and `any`; and
+- recursive type definitions whose eventual application values are acyclic.
+
+Named scalar types retain their Go identity. `uintptr`, complex numbers, functions,
+channels, unsafe pointers, non-string map keys, and nonempty interfaces are not
+configuration types. A custom text scalar must provide both directions on its value
+or pointer method set. Building a descriptor only inspects method sets; it never
+executes application methods or parser-specific hooks.
+
+Exported struct fields use an explicit `yaml` name or the lowercase Go field name.
+Unexported fields and `yaml:"-"` are ignored. `omitempty` is accepted but does not
+change binding or future projection. An explicit `yaml:",inline"` flattens a struct
+or pointer-to-struct, or designates at most one string-keyed inline map for otherwise
+unmatched names. Ambiguous names, named inline fields, multiple inline maps, and
+unsupported or malformed tag options are schema errors. Embedded fields are ordinary
+named fields unless explicitly inlined. `configkit:"secret"` is the only current
+ConfigKit field tag and records sensitivity for later lifecycle work.
+
+Schema path traversal uses these same bindings. Explicit key segments address
+mappings, explicit index segments address sequences, and parsed numeric pointer
+tokens become indices only in a sequence. Sequence indices cannot have leading
+zeroes; fixed-array indices are bounds checked. Dynamic `any` and inline-map entries
+remain schema-valid for application-defined descendants.
+
+Descriptors do not yet decode documents, clone defaults, or project application
+values. Those operations will reuse this graph as their implementation lands.
+
 ## Safe failures
 
 Source failures use stable `source.*` codes and YAML failures use stable `yaml.*`