Update guidance for the cleaned public API

docs/config.md

@@ -46,9 +46,9 @@ literal single filename components; it does not expand application-name
 placeholders. An application slug is required only when a selected directory or
 filename group uses it. Literal custom paths are not expanded for `~`, variables,
 or wildcards; relative paths are resolved from the working directory at load time.
-The zero `Search`, `Searches()`, `Paths()`, and an empty custom filename group
-contribute no candidates. An explicitly supplied empty path or filename is
-invalid. Slugs and custom filenames must be usable single host filename
+The zero `Search`, `Searches()`, `SearchPaths()`, and an empty custom filename
+group contribute no candidates. An explicitly supplied empty path or filename
+is invalid. Slugs and custom filenames must be usable single host filename
 components; ConfigKit preserves their case and spelling.
 
 Search expansion is ordered concatenation. For each directory search, ConfigKit
@@ -290,7 +290,7 @@ the application root and are not moved beneath the main input's destination.
 `SourceInfo.Destination` reports each acquired source's effective mapping or
 sequence-container path, including imports. `PlacementMode` reports how that
 source was placed; mapping is the zero value, and CLI/overlay sources report
-mapping unless item placement was applied. `DestinationUnresolved` is true only
+mapping unless item placement was applied. `DestinationIsFallback` is true only
 when an enclosing item index needed to name the source's destination has not yet
 been assigned. In that case `Destination` reports the nearest resolved enclosing
 collection container and omits the unresolved local suffix. A source's own item
@@ -457,10 +457,10 @@ successful result. Callback panics remain programming failures.
 
 `Options.SourceVersionMode` and `LayeredOptions.SourceVersionMode` select how
 one `Definition.Version` policy applies across source documents. The zero value
-`SourceVersionModeDefault` preserves the existing main-only check at its
-effective path and existing protected-path behavior. `SourceVersionModeIfPresent`
-checks each participating document that declares a version and permits absent
-non-main declarations. `SourceVersionModeRequired` rejects a participating
+`SourceVersionModeMainOnly` (the zero value) preserves the existing main-only
+check at its effective path and existing protected-path behavior.
+`SourceVersionModeIfPresent` checks each participating document that declares a
+version and permits absent non-main declarations. `SourceVersionModeRequired` rejects a participating
 document without a declaration. Enabled modes require a usable `VersionRule`
 and checker; an unknown mode or unusable rule is an options error before source
 access or callbacks.
@@ -497,7 +497,7 @@ declaration locations use source-local coordinates; ordinary payload
 diagnostics continue to use effective paths. Default-mode diagnostics are
 unchanged.
 
-`SourceInfo.VersionCheck` is nil when enabled declaration processing did not
+`SourceInfo.VersionEvidence` is nil when enabled declaration processing did not
 occur. Otherwise it records a source-local `Path`, the observed `Version` state
 (`Present`, `Null`, and, when disclosed, exact `Text`), an actual or nearest
 available `Location`, and whether text was redacted. A non-nil record with
@@ -573,7 +573,7 @@ reports it absent. Queries return detached records.
 ### Secret classification and effective rendering
 
 Secret classification combines `configkit:"secret"` field tags with the optional
-pure `Definition.Secret(Path) bool` predicate. Tags on concrete structs inside
+pure `Definition.Sensitive(Path) bool` predicate. Tags on concrete structs inside
 supported dynamic values are retained in typed projections, including superseded
 defaults and pre-resolution values. A tagged or predicate-classified
 container makes all descendants sensitive. ConfigKit evaluates final and historical
@@ -636,7 +636,7 @@ writes remain visible. When structural replay differs from the pre-CLI typed inp
 a `ChangeDecoding` event records retained defaults and canonical decoding. CLI
 contributions then retain their raw input representation while effective and
 resolution values use the typed projection. This built-in inspection operation is
-not accepted by `Resolution.Record`.
+not exposed as a manual recording method.
 
 Base, overlay, and CLI history preserves the policy-validated input representation,
 including a superseded value that could not have decoded into the final Go field.
@@ -671,11 +671,11 @@ unredacted mode.
 Retained history consists of immutable source applications and audited subtree
 deltas, rather than a full tree copy per field. Shared nodes count once toward a
 4,000,000-node retained-history limit; exceeding it fails loading with
-`explain.limit_exceeded`. Replaying one requested path is performed on demand, and
+`history.limit_exceeded`. Replaying one requested path is performed on demand, and
 the returned YAML strings and nested records cannot mutate later explanations.
 
 Application commands should render the separate `SecretsReport` immediately after
-an explicit `LoadSecretsDir` bootstrap, then use `WriteDiagnostics`,
+an explicit `LoadSecretsIntoEnvironment` bootstrap, then use `WriteDiagnostics`,
 `WriteEffective`, or `WriteExplanation` on the later load result as appropriate.
 ConfigKit does not infer bootstrap outcomes from a secret reference and does not
 bundle these independent reports into a command framework.
@@ -770,11 +770,12 @@ reference state without printing its value.
 
 ## Explicit secrets-directory bootstrap
 
-`LoadSecretsDir(directory)` is a separate, opt-in startup operation. It is never
-called by `Load`, is not a YAML option, and does not participate in configuration
-validation. Applications choose the native directory path and should invoke the
-operation once before starting concurrent work. The selected path may itself be a
-symlink; ConfigKit resolves it to an existing canonical directory before examining
+`LoadSecretsIntoEnvironment(directory)` is a separate, opt-in startup operation.
+It is never called by `Load`, is not a YAML option, and does not participate in
+configuration validation. Applications choose the native directory path and
+should invoke the operation once before starting concurrent work. The selected
+path may itself be a symlink; ConfigKit resolves it to an existing canonical
+directory before examining
 its immediate entries.
 
 The bootstrap enumerates at most 1,024 entries, including dot-prefixed entries.
@@ -814,7 +815,7 @@ per-load `Resolution` context. The context's
 `IsExplicit` query uses surviving input presence, so explicit false, zero, empty, and
 null are never confused with absence or static defaults.
 
-`Resolution.InputInfo(path)` returns detached effective metadata from the fixed
+`Resolution.EntryInfo(path)` returns detached effective metadata from the fixed
 post-decode entry state, including explicit CLI overrides, before application
 resolution runs. It includes retained static defaults, preserves explicit null, and
 uses the same exact semantic path matching as `Metadata.Lookup`; missing,
@@ -837,18 +838,20 @@ exit; changing them cannot affect later queries, results, or another load.
 
 `Default` assigns and records a derived value only when its path is not explicit.
 `Normalize` always assigns and records. For transformations performed directly by
-application code, `Resolution.Record` declares a derived-default or normalization
-operation; a recorded container covers changes to its descendants. Records require
-a schema-valid path, valid kind, safe nonempty reason, and schema-valid dependency
-paths. Repeated records at one path are coalesced: reasons and dependencies retain
-their first occurrence, the last helper value is authoritative, and any normalization
-makes the combined operation a normalization.
+application code, `Resolution.RecordDerivedDefault` and
+`Resolution.RecordNormalization` declare the operation already performed; a
+recorded container covers changes to its descendants. These methods do not assign
+values, and a derived-default record does not suppress work for explicit input.
+Records require a schema-valid path, safe nonempty reason, and schema-valid
+dependency paths. Repeated records at one path are coalesced: reasons and
+dependencies retain their first occurrence, the last helper value is authoritative,
+and any normalization makes the combined operation a normalization.
 
 ConfigKit projects the configuration before and after the callback. Every net change
 must have an exact or ancestor record. Helper-assigned values must agree with the
 final value at their declared path, which supports ordinary map-entry copy/writeback
-while detecting forgotten writeback or unrelated targets. Invalid paths, kinds,
-values, records, helper targets, and unrecorded mutations fail the load. Equal-valued
+while detecting forgotten writeback or unrelated targets. Invalid paths, values,
+records, helper targets, and unrecorded mutations fail the load. Equal-valued
 derived assignments may still record application intent even when there is no
 structural change.
 
@@ -1226,6 +1229,8 @@ replaces rather than extends the default pattern. Nil `Pattern` leaves directory
 filenames unrestricted; a non-nil empty slice selects none. Defaults do not make
 a field applicable to selectors that do not support it, and load calls snapshot
 the supplied pointers and slice before source acquisition.
+The Go fields are named `FollowSymlinks` and `IncludeHidden`; the YAML keys
+remain `follow` and `hidden`.
 
 A source's `configkit.sequences` declarations apply independently of import
 enablement; a `configkit.imports` declaration still requires `Options.Imports`.
@@ -1261,15 +1266,15 @@ or glob selection fail with `import.missing`; it also makes missing named paths
 fail. Requiredness does not suppress invalid paths, containment failures,
 directories selected as files, permissions, parse errors, or composition errors.
 
-For inspection, `SourceInfo.ImportSelections` records one outcome for each
-completed optional declaration whose entire selected set is empty. The record is
-attached to its declaring source, keeps the declaration path local to that source,
-identifies the declaration mapping (including its `SourceID`) and selector, and
-uses outcome `none`. Records remain in declaration order and are available
-through the existing result, load
-error, and callback source snapshots. They do not enumerate candidates, explain
+For inspection, `SourceInfo.EmptyImportSelections` records each completed optional
+declaration whose entire selected set is empty. The record is attached to its
+declaring source, keeps the declaration path local to that source, and identifies
+the declaration mapping (including its `SourceID`) and selector. Records remain
+in declaration order and are available
+through the existing result, load-error, and callback source snapshots. They do
+not enumerate candidates, explain
 why a path was absent, or describe partial omissions. Empty `path: []` succeeds
-regardless of requiredness: it produces a `none` record when effectively optional,
+regardless of requiredness: it produces a record when effectively optional,
 and no record when effectively required. Snapshots detach the record paths and
 slices.