Expose configuration search through the public facade

docs/config.md

@@ -12,6 +12,7 @@ ConfigKit exposes opaque sources through these constructors:
 | Constructor | Current contract |
 | --- | --- |
 | `File(path)` | Requires a nonempty path, opens a regular file for each consumption, and closes only the library-owned file handle. Missing, inaccessible, unreadable, directory, and other nonregular inputs fail. |
+| `SearchConfig(application, search, options...)` | Creates an explicit, reusable search source. Loading selects one host file or follows the absent-input lifecycle when an optional search is exhausted. |
 | `NewFilesystem(label, filesystem).File(name)` | Borrows a caller-owned `fs.FS` under a safe nonempty display label. `name` must be a non-root slash-relative `fs.ValidPath`. Each load reopens the selected regular file; copies of the `Filesystem` preserve namespace identity. Separate constructors create separate namespaces even for the same label or filesystem. |
 | `Bytes(label, data)` | Requires a nonempty, non-secret diagnostic label and snapshots bytes during construction. Later caller mutation cannot affect the source. |
 | `Reader(label, input)` | Requires a nonempty, non-secret label and non-nil reader. The reader is claimed once across all copies of the source, consumed but never closed, and cannot be reused. |
@@ -28,6 +29,79 @@ Keys are sorted for stable provenance, integer decimal spelling stays exact, and
 cycles or unsupported types are rejected without exposing values. Mapping input
 uses the same directive and version rules as YAML, not CLI override restrictions.
 
+### Configuration discovery
+
+Discovery is opt-in. Construct `Search` from literal `Paths`, directory searches,
+or the supported directory presets, then pass it to `SearchConfig`. Search
+descriptions are immutable and reusable; each load resolves dynamic directories
+and checks current candidate files again. `Searches` is ordered concatenation.
+It preserves the supplied description order and does not deduplicate candidates.
+
+`NamedFilenames` selects `<application>.yml`, then `<application>.yaml`.
+`GenericFilenames` selects `config.yml`, `config.yaml`, `main.yml`, then
+`main.yaml`. `SearchDirectory` defaults to `[Named, Generic]` when options are
+omitted or `Filenames` is nil. A non-nil empty filename list contributes no
+candidates and does not resolve its directory. `CustomFilenames` supplies
+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
+components; ConfigKit preserves their case and spelling.
+
+Search expansion is ordered concatenation. For each directory search, ConfigKit
+tries its filename groups and names before advancing to the next directory.
+When multiple directories use the same filename list, candidates follow the
+directory-first Cartesian product: every filename in one directory is tried
+before the next directory. Explicit file candidates stay at their declared
+positions among directory searches.
+
+The presets expand to these ordered directories and filename groups:
+
+| Preset | Directory, in order | Filename groups |
+| --- | --- | --- |
+| `UnixSystemDirectories` | `/usr/local/etc/<application>`, `/etc/<application>` | Named, then Generic |
+| `UnixSystemDirectories` | `/etc` | Named only |
+| `UserConfigDirectory` | Go user-config directory / `<application>` | Named, then Generic |
+| `UserConfigDirectory` | Go user-config directory | Named only |
+| `HomeDirectory` | Go home directory / `.<application>` | Named, then Generic |
+| `HomeDirectory` | Go home directory | Named only |
+| `WorkingDirectory` | Current working directory | Named only |
+
+The Unix system preset is supported on aix, android, darwin, dragonfly, freebsd,
+hurd, illumos, ios, linux, netbsd, openbsd, and solaris; reaching it on another
+platform is an option error. Other presets use Go's user-config, home, and
+working-directory helpers. A reached
+directory-helper error terminates selection. Bases for later searches are not
+resolved after an earlier candidate is selected. Missing candidates continue;
+the first existing candidate is selected and then follows ordinary file loading
+rules. Errors while acquiring or processing a selected file are terminal and do
+not resume the search.
+
+Searches are optional by default. Exhaustion uses the same absent-main lifecycle
+as `NoSource()`: there is no main document, source record, source ID, or explicit
+presence contribution. Imports may be enabled but there are no main declarations
+to traverse. Defaults, version checks, overlays, CLI overrides, resolution, and
+validation retain their normal lifecycle. `SearchOptions{Required: true}` makes
+exhaustion an error; it does not change candidate or selected-file error handling.
+
+For an ordinary active overlay after optional exhaustion, provide an explicit
+filesystem context. A host context with only `Root` is sufficient; ConfigKit
+loads the overlay at its normal root-relative location and does not infer a root
+from attempted search directories. The same root-only context can accompany a
+search that selects a file: the selected file determines its base and must be
+inside `Root`. A selected host file rejects an explicit `BaseDir` or native
+filesystem context. Invalid context fails without resuming selection. Layered
+overlays keep their independent `OverlayFilesystem` requirement.
+
+When a search selects a file, inspection reports that actual file with ordinary
+source IDs, paths, placement, metadata origins, and resource context. Missing
+candidates create no records. `SearchConfig` can be used as the main source of
+ordinary or layered loading, including an underlay input, and does not add a new
+precedence tier.
+
 Each source is limited to 8 MiB. A load using imports or an active overlay is limited
 to 64 MiB across all accepted sources, 1,024 accepted sources, 64 active import
 edges, and 1,000,000 input nodes in aggregate. Glob expansion separately permits