whence 1.0.0__tar.gz

whence-1.0.0/.gitignore

@@ -0,0 +1,66 @@
+# --- Secrets -----------------------------------------------------------
+# Configuration is what this library reads; keep real config and keys out of the repo.
+# The fixtures under examples/ and docker/secrets/ are fake and committed on purpose.
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+secrets.toml
+
+# --- Python ------------------------------------------------------------
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# --- Builds ------------------------------------------------------------
+build/
+dist/
+*.egg
+*.egg-info/
+.eggs/
+
+# --- Environments ------------------------------------------------------
+.venv/
+.venv*/
+venv/
+env/
+.direnv/
+
+# --- Tooling caches ----------------------------------------------------
+.pytest_cache/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+.nox/
+.tox/
+.cache/
+.hypothesis/
+.ipynb_checkpoints/
+
+# --- Coverage ----------------------------------------------------------
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# --- Docs ---------------------------------------------------------------
+# .gitignore has no inline comments - each pattern gets its own line.
+# mkdocs build output
+site/
+
+# --- Logs / scratch ----------------------------------------------------
+*.log
+*.orig
+*.rej
+scratch/
+tmp/
+
+# --- Editors / OS ------------------------------------------------------
+.DS_Store
+.idea/
+.vscode/
+*.swp

whence-1.0.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-09-08
+
+### Added
+
+- Provenance spine: `Origin`, `Tracked`, and a merge that records what each
+  value shadowed.
+- `Source` protocol with a `SourceChain` supporting name-addressed
+  insertion, plus environment, `.env`, file, mapping and secrets-directory
+  sources.
+- Format loaders for TOML, JSON, `.properties` and XML on the standard library,
+  and YAML behind the `whence[yaml]` extra. YAML, `.env` and `.properties`
+  carry exact line and column numbers.
+- `Discovery`: a declarative five-step search chain over explicit paths,
+  `$APP_CONFIG`, project roots, per-user config directories and
+  `pyproject.toml`, with cross-platform directory conventions.
+- `Config` with `get`, `require`, `explain`, `dump`, `bind` and `with_fallback`.
+- Interpolation with `${a.b}`, `${a.b:-default}`, `${?a.b}`, `${env:VAR}` and
+  `${file:/path}`, resolved lazily after the merge.
+- Profiles, profile groups, and the invariant that profiles never reorder
+  sources.
+- Binding to frozen dataclasses (standard library) and to pydantic models when
+  pydantic is installed, with batched errors that carry origins.
+- `Secret`, `unlock_secrets()`, `_FILE` indirection and a sanitizer applied to
+  every dump.
+- `@settings` and `@from_config` decorators.
+- `ArgvSource`, reading `--set key=value` out of `sys.argv`.
+- `RelativePath`, a path resolved against the file that declared it rather than
+  the process working directory -- possible only because values carry origins.
+- A `whence` CLI: `explain`, `dump` and `discovery`.
+
+### Design notes
+
+- **Loading is synchronous, and there is no reload.** Configuration is read once
+  before the application runs, where there is no event loop for an `await` to
+  yield to. Reload was cut with it: a poll loop means whence owning a thread or a
+  loop and mutating a generation other code holds, which is precisely where
+  .NET's `ChangeToken`, viper's `WatchConfig` and koanf's `Watch()` each went
+  wrong. A process that must pick up a change calls `Config.load(...)` again on a
+  schedule it owns.
+
+### Stability
+
+- The public API is whatever `whence.__init__` lists in `__all__`. From this
+  release on it follows semantic versioning: anything else is internal, and a
+  breaking change to the public surface requires a 2.0.0.
+
+[Unreleased]: https://github.com/izmailov-labs/whence/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/izmailov-labs/whence/releases/tag/v1.0.0

whence-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 izmailov-labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

whence-1.0.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: whence
+Version: 1.0.0
+Summary: Typed configuration that remembers where it came from: layered loading with full provenance.
+Project-URL: Homepage, https://github.com/izmailov-labs/whence
+Project-URL: Documentation, https://izmailov-labs.github.io/whence/
+Project-URL: Repository, https://github.com/izmailov-labs/whence
+Project-URL: Changelog, https://github.com/izmailov-labs/whence/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/izmailov-labs/whence/issues
+Author: izmailov-labs
+License-Expression: MIT
+License-File: LICENSE
+Keywords: config,configuration,dotenv,env,provenance,settings
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0.2; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# whence
+
+**Typed configuration that remembers where it came from.**
+
+Every configuration library can tell you a value. `whence` can tell you *why*
+it has that value — which file, which line, which profile, and what it
+overrode.
+
+```console
+$ whence explain db.host --profile prod
+db.host = "db.internal"
+  <- config/app.prod.yaml:4:9 [profile=prod]
+  shadowed:
+      overrides                     - not set
+      MYAPP_DB__HOST                - not set
+      .env                          - not set
+      config/app.yaml:2:9           = "localhost"
+      <defaults>                    = "localhost"
+```
+
+Spring has this (`Origin`, `/actuator/env`), HOCON has it (`ConfigOrigin`), Rust's
+`figment` has it (`Metadata`). Python has not — pydantic-settings' debug output
+is top-level-only and unredacted, dynaconf has history but no line numbers, and
+everything else discards provenance at the first merge.
+
+`whence` is a **complement to pydantic, not a replacement**. Point it at a
+pydantic model or a frozen dataclass; it does the layering, the provenance and
+the diagnostics.
+
+## Install
+
+```console
+pip install whence          # env, .env, TOML, JSON, .properties, XML
+pip install whence[yaml]    # + YAML
+```
+
+The core has **no runtime dependencies**. That is a design constraint, not an
+accident: every format but YAML is parsed on the standard library.
+
+## Use
+
+```python
+from dataclasses import dataclass
+from whence import Config, Secret, settings
+
+
+@settings(prefix="db")
+@dataclass(frozen=True, slots=True)
+class Db:
+    host: str = "localhost"
+    port: int = 5432
+    password: Secret | None = None
+
+
+cfg = Config.load(app="myapp", profiles=["prod"])
+db = cfg.bind(Db)
+
+cfg.explain("db.host")  # the winner, and everything it shadowed
+```
+
+Loading is synchronous, and deliberately so. Configuration is read once,
+before the application runs — there is no event loop at that point, so an
+`await` would have nothing to yield to. A `Source` that reaches the network
+blocks the startup it is already part of, which is exactly what starting up
+means.
+
+## What it does
+
+| | |
+|---|---|
+| **Formats** | env vars, `.env`, TOML, JSON, YAML, Java `.properties`, XML |
+| **Precedence** | seven named layers, `overrides > cli > env > .env > secrets-dir > files > defaults` |
+| **Discovery** | explicit path → `$MYAPP_CONFIG` → project roots → per-user config dir → `pyproject.toml`, all configurable |
+| **Profiles** | `app.prod.yaml` overlays, profile groups, and profiles never reorder sources |
+| **Interpolation** | `${a.b}`, `${a.b:-default}`, `${?a.b}`, `${env:VAR}`, `${file:/run/secrets/x}` |
+| **Secrets** | `Secret`, `_FILE` indirection, a sanitizer on every dump, reads gated by `unlock_secrets()` |
+| **Binding** | frozen dataclasses on the stdlib; pydantic models when pydantic is installed |
+| **Diagnostics** | batched errors carrying origin, and did-you-mean for unknown keys |
+
+Exact `line:column` comes from YAML, `.env` and `.properties`. `tomllib`, `json`
+and `ElementTree` expose no positions, so TOML, JSON and XML get file-level
+origins — stated here rather than implied away.
+
+## Reloading
+
+There isn't any. To change configuration, redeploy.
+
+`Config` is immutable and loaded once. A library that also owns a poll loop owns
+a thread or an event loop, and the generational swap it needs is where every
+prior art went wrong: .NET's `ChangeToken.OnChange` has fired **twice per save**
+since 2017, Go viper's `WatchConfig` carries a documented data race, and koanf's
+`Watch()` is not safe against concurrent reads. Each of those is a property of
+changing an object other code is holding — so whence does not hold one.
+
+What whence does guarantee is that a fresh `Config.load(...)` sees the current
+state of the world, including through a **Kubernetes ConfigMap's `..data`
+symlink**. kubelet republishes by pointing that symlink at a new directory, and
+an inotify watch on the config *file* is bound to the old inode and goes
+permanently deaf; re-reading resolves the symlink afresh. That is covered by a
+test against real symlinks on a real Linux filesystem (`make test-docker`).
+
+If you need a running process to pick up a change, call `Config.load(...)` again
+on a schedule you own and swap your own pointer. It is a handful of lines, it
+lives where your concurrency model already is, and whence stays out of it.
+
+## Cross-platform
+
+Config directories follow each platform's own convention: XDG on Linux,
+`~/Library/Application Support` on macOS (plus XDG when you set it explicitly),
+`%APPDATA%` and `%LOCALAPPDATA%` on Windows. Case-insensitive filesystems do not
+produce phantom ambiguities, CRLF files parse, and every file is read as UTF-8
+regardless of the platform's default encoding.
+
+## Contributing
+
+Pull requests are welcome. Fork the repository, branch off `main`, and open the PR against
+`main`. CI runs on every pull request and every job is required, so run `make all` before
+pushing: it is the local mirror of the CI gate, and a green run here is the cheapest way to
+avoid a red one there.
+
+```bash
+make install     # once: sync the environment, install the pre-commit hooks
+make all         # lint, typecheck, coverage, docs, build
+```
+
+The pre-commit hooks cover ruff and the lockfile on the way in; mypy is deliberately not among
+them and is gated in CI instead, because it is slow enough that people start reaching for
+`--no-verify`.
+
+What CI adds on top of `make all`:
+
+| Job | What it catches |
+| --- | --- |
+| `test` | The real matrix: Linux, macOS and Windows, at both ends of the supported Python range |
+| `encoding` | Any `open()` or `read_text()` missing an explicit `encoding=` |
+| `minimums` | Declared floors that are only ever tested at their latest versions |
+| `no-deps` | A runtime import that quietly breaks the zero-dependency install |
+| `build` | Broken packaging, a missing `py.typed`, a wheel that does not import |
+
+The Python 3.15 leg is advisory until 3.15.0 ships; everything else must be green.
+
+### What a reviewable PR looks like
+
+- **A changelog entry** under `## [Unreleased]` in [CHANGELOG.md](CHANGELOG.md), in the Keep a
+  Changelog sections the file already uses. The version is bumped at release time, not here.
+- **Annotated code, tests and examples included.** mypy runs `strict = true` over `src/`,
+  `tests/` and `examples/` alike, and suppressions are specific: `# type: ignore[code]`, never
+  bare.
+- **Docstrings on public API.** The docs site generates its reference from them, and ruff's `D`
+  rules (google convention) enforce them in `src/`.
+- **A new runtime dependency is a decision, not a detail.** `dependencies = []` is the product
+  claim, not a preference: every format but YAML is parsed on the standard library, and YAML
+  lives behind the `whence[yaml]` extra. Open an issue before the PR. Dev tooling goes in
+  `[dependency-groups]`, which is never published.
+- **`uv.lock` committed** whenever a dependency changes; the `uv-lock` hook fails on drift.
+
+Two rules exist because breaking them fails late and somewhere else. **Probe, never branch on
+`sys.platform`** — case-insensitivity is a property of a directory, not a platform, and a name
+that can be created is not always a name that round-trips. And **pass `encoding=` explicitly on
+every read**: without it a bug appears only on a Windows code page, only for non-ASCII content,
+and only in someone else's CI, which is what `make encoding` exists to prevent.
+
+If a change touches mounts, musl, a read-only root or a non-UTF-8 locale, `make test-docker`
+runs the six Linux scenarios CI cannot reproduce. Tests that need a real mount carry the
+`container` marker and are excluded from the default run.
+
+Anything large enough to have a design is worth an issue before the PR; small fixes can go
+straight to one.
+
+## License
+
+MIT

whence-1.0.0/README.md

@@ -0,0 +1,172 @@
+# whence
+
+**Typed configuration that remembers where it came from.**
+
+Every configuration library can tell you a value. `whence` can tell you *why*
+it has that value — which file, which line, which profile, and what it
+overrode.
+
+```console
+$ whence explain db.host --profile prod
+db.host = "db.internal"
+  <- config/app.prod.yaml:4:9 [profile=prod]
+  shadowed:
+      overrides                     - not set
+      MYAPP_DB__HOST                - not set
+      .env                          - not set
+      config/app.yaml:2:9           = "localhost"
+      <defaults>                    = "localhost"
+```
+
+Spring has this (`Origin`, `/actuator/env`), HOCON has it (`ConfigOrigin`), Rust's
+`figment` has it (`Metadata`). Python has not — pydantic-settings' debug output
+is top-level-only and unredacted, dynaconf has history but no line numbers, and
+everything else discards provenance at the first merge.
+
+`whence` is a **complement to pydantic, not a replacement**. Point it at a
+pydantic model or a frozen dataclass; it does the layering, the provenance and
+the diagnostics.
+
+## Install
+
+```console
+pip install whence          # env, .env, TOML, JSON, .properties, XML
+pip install whence[yaml]    # + YAML
+```
+
+The core has **no runtime dependencies**. That is a design constraint, not an
+accident: every format but YAML is parsed on the standard library.
+
+## Use
+
+```python
+from dataclasses import dataclass
+from whence import Config, Secret, settings
+
+
+@settings(prefix="db")
+@dataclass(frozen=True, slots=True)
+class Db:
+    host: str = "localhost"
+    port: int = 5432
+    password: Secret | None = None
+
+
+cfg = Config.load(app="myapp", profiles=["prod"])
+db = cfg.bind(Db)
+
+cfg.explain("db.host")  # the winner, and everything it shadowed
+```
+
+Loading is synchronous, and deliberately so. Configuration is read once,
+before the application runs — there is no event loop at that point, so an
+`await` would have nothing to yield to. A `Source` that reaches the network
+blocks the startup it is already part of, which is exactly what starting up
+means.
+
+## What it does
+
+| | |
+|---|---|
+| **Formats** | env vars, `.env`, TOML, JSON, YAML, Java `.properties`, XML |
+| **Precedence** | seven named layers, `overrides > cli > env > .env > secrets-dir > files > defaults` |
+| **Discovery** | explicit path → `$MYAPP_CONFIG` → project roots → per-user config dir → `pyproject.toml`, all configurable |
+| **Profiles** | `app.prod.yaml` overlays, profile groups, and profiles never reorder sources |
+| **Interpolation** | `${a.b}`, `${a.b:-default}`, `${?a.b}`, `${env:VAR}`, `${file:/run/secrets/x}` |
+| **Secrets** | `Secret`, `_FILE` indirection, a sanitizer on every dump, reads gated by `unlock_secrets()` |
+| **Binding** | frozen dataclasses on the stdlib; pydantic models when pydantic is installed |
+| **Diagnostics** | batched errors carrying origin, and did-you-mean for unknown keys |
+
+Exact `line:column` comes from YAML, `.env` and `.properties`. `tomllib`, `json`
+and `ElementTree` expose no positions, so TOML, JSON and XML get file-level
+origins — stated here rather than implied away.
+
+## Reloading
+
+There isn't any. To change configuration, redeploy.
+
+`Config` is immutable and loaded once. A library that also owns a poll loop owns
+a thread or an event loop, and the generational swap it needs is where every
+prior art went wrong: .NET's `ChangeToken.OnChange` has fired **twice per save**
+since 2017, Go viper's `WatchConfig` carries a documented data race, and koanf's
+`Watch()` is not safe against concurrent reads. Each of those is a property of
+changing an object other code is holding — so whence does not hold one.
+
+What whence does guarantee is that a fresh `Config.load(...)` sees the current
+state of the world, including through a **Kubernetes ConfigMap's `..data`
+symlink**. kubelet republishes by pointing that symlink at a new directory, and
+an inotify watch on the config *file* is bound to the old inode and goes
+permanently deaf; re-reading resolves the symlink afresh. That is covered by a
+test against real symlinks on a real Linux filesystem (`make test-docker`).
+
+If you need a running process to pick up a change, call `Config.load(...)` again
+on a schedule you own and swap your own pointer. It is a handful of lines, it
+lives where your concurrency model already is, and whence stays out of it.
+
+## Cross-platform
+
+Config directories follow each platform's own convention: XDG on Linux,
+`~/Library/Application Support` on macOS (plus XDG when you set it explicitly),
+`%APPDATA%` and `%LOCALAPPDATA%` on Windows. Case-insensitive filesystems do not
+produce phantom ambiguities, CRLF files parse, and every file is read as UTF-8
+regardless of the platform's default encoding.
+
+## Contributing
+
+Pull requests are welcome. Fork the repository, branch off `main`, and open the PR against
+`main`. CI runs on every pull request and every job is required, so run `make all` before
+pushing: it is the local mirror of the CI gate, and a green run here is the cheapest way to
+avoid a red one there.
+
+```bash
+make install     # once: sync the environment, install the pre-commit hooks
+make all         # lint, typecheck, coverage, docs, build
+```
+
+The pre-commit hooks cover ruff and the lockfile on the way in; mypy is deliberately not among
+them and is gated in CI instead, because it is slow enough that people start reaching for
+`--no-verify`.
+
+What CI adds on top of `make all`:
+
+| Job | What it catches |
+| --- | --- |
+| `test` | The real matrix: Linux, macOS and Windows, at both ends of the supported Python range |
+| `encoding` | Any `open()` or `read_text()` missing an explicit `encoding=` |
+| `minimums` | Declared floors that are only ever tested at their latest versions |
+| `no-deps` | A runtime import that quietly breaks the zero-dependency install |
+| `build` | Broken packaging, a missing `py.typed`, a wheel that does not import |
+
+The Python 3.15 leg is advisory until 3.15.0 ships; everything else must be green.
+
+### What a reviewable PR looks like
+
+- **A changelog entry** under `## [Unreleased]` in [CHANGELOG.md](CHANGELOG.md), in the Keep a
+  Changelog sections the file already uses. The version is bumped at release time, not here.
+- **Annotated code, tests and examples included.** mypy runs `strict = true` over `src/`,
+  `tests/` and `examples/` alike, and suppressions are specific: `# type: ignore[code]`, never
+  bare.
+- **Docstrings on public API.** The docs site generates its reference from them, and ruff's `D`
+  rules (google convention) enforce them in `src/`.
+- **A new runtime dependency is a decision, not a detail.** `dependencies = []` is the product
+  claim, not a preference: every format but YAML is parsed on the standard library, and YAML
+  lives behind the `whence[yaml]` extra. Open an issue before the PR. Dev tooling goes in
+  `[dependency-groups]`, which is never published.
+- **`uv.lock` committed** whenever a dependency changes; the `uv-lock` hook fails on drift.
+
+Two rules exist because breaking them fails late and somewhere else. **Probe, never branch on
+`sys.platform`** — case-insensitivity is a property of a directory, not a platform, and a name
+that can be created is not always a name that round-trips. And **pass `encoding=` explicitly on
+every read**: without it a bug appears only on a Windows code page, only for non-ASCII content,
+and only in someone else's CI, which is what `make encoding` exists to prevent.
+
+If a change touches mounts, musl, a read-only root or a non-UTF-8 locale, `make test-docker`
+runs the six Linux scenarios CI cannot reproduce. Tests that need a real mount carry the
+`container` marker and are excluded from the default run.
+
+Anything large enough to have a design is worth an issue before the PR; small fixes can go
+straight to one.
+
+## License
+
+MIT

whence-1.0.0/docker/secrets/README.md

@@ -0,0 +1,2 @@
+Fixture secrets for the container scenarios. These are fake, committed on
+purpose, and exist so `docker compose` can mount a real `/run/secrets`.

whence-1.0.0/examples/README.md

@@ -0,0 +1,127 @@
+# whence by example
+
+Eight runnable scripts, each adding one idea to the one before it. Read them in
+order and you have seen the whole library; run them and you have seen it work.
+
+| | Script | What it adds |
+| --- | --- | --- |
+| 1 | `01_hello.py` | reading, defaults, coercion, and where a value came from -- no files at all |
+| 2 | `02_files.py` | a real TOML file, discovered rather than named, plus interpolation |
+| 3 | `03_typed.py` | binding onto frozen dataclasses, and what a typo'd key looks like |
+| 4 | `04_layers.py` | the whole precedence stack: cli, env, `.env`, two file roots, defaults |
+| 5 | `05_profiles.py` | `demo.prod.toml` overlays, and profile groups |
+| 6 | `06_secrets.py` | a secrets directory, `Secret`, and the reveal gate |
+| 7 | `07_injection.py` | `@from_config`: a function that declares what it needs |
+| 8 | `08_advanced.py` | `RelativePath`, a source you wrote, `with_fallback`, discovery knobs |
+
+## Running them
+
+Every script imports `whence` and the standard library, nothing else, and finds
+its data files relative to its own path -- so it behaves the same from any
+working directory, under either installer.
+
+```console
+# from a clone of this repository
+$ uv run python examples/01_hello.py
+
+# or with pip, in any virtual environment
+$ python -m venv .venv && source .venv/bin/activate
+$ pip install whence
+$ python examples/01_hello.py
+```
+
+There is no YAML in the examples on purpose: they run on a bare
+`pip install whence`, with no extras. `pip install whence[yaml]` adds the one
+format that needs a third-party parser.
+
+## The data they read
+
+| Path | The layer it is |
+| --- | --- |
+| `config/demo.toml` | the base file: interpolation, a `${...:-default}`, an optional `${?...}`, an `${env:...}`, and values that coerce to `bool`, `timedelta` and `list` |
+| `config/demo.prod.toml` | a profile overlay, carrying only what differs |
+| `config/base/demo.properties` | a **second, lower search root**, in a hand-scanned format that keeps exact `line:column` |
+| `config/ca.crt` | the target of a `RelativePath`, resolved against its own config file |
+| `demo.env` | a dotenv file, named `demo.env` because this repository gitignores `.env` |
+| `secrets/db.password` | a key-per-file secrets directory, which outranks every config file |
+
+`demo` is the application name *and* the file stem: it is what makes
+`demo.toml`, `demo.prod.toml`, the `DEMO_` environment prefix, `$DEMO_CONFIG`,
+`$DEMO_PROFILES` and `[tool.demo]` all line up. Each of those has its own
+override on `Discovery` if you need them decoupled.
+
+## Things to try
+
+Example 4 is the one that reads the real environment and the real command line.
+
+```console
+$ cd examples
+
+# the environment outranks every file; __ nests, so this is db.port
+$ DEMO_DB__PORT=6543 python 04_layers.py
+
+# the command line outranks even that
+$ python 04_layers.py --set db.host=from-the-cli
+
+# an ${env:...} placeholder reads a variable with no prefix at all
+$ AWS_REGION=us-east-1 python 04_layers.py
+
+# the profile switch, from outside the process
+$ DEMO_PROFILES=prod python 05_profiles.py
+```
+
+Two failures are worth causing on purpose.
+
+**A typo'd key.** Add `pool_sze = 1` under `[db]` in `config/demo.toml` and run
+example 3 or 4:
+
+```text
+BindError: 1 error
+
+  Property: db.pool_sze
+     Value: 1
+    Origin: .../config/demo.toml
+    Reason: no such setting - did you mean 'db.pool_size'?
+```
+
+**Two formats in one directory.** `cp config/demo.toml config/demo.json` -- the
+JSON will not parse, but discovery fails first, and says what to do about it:
+
+```text
+AmbiguousConfigError: .../config holds more than one demo configuration file
+(demo.toml, demo.json); remove one, or narrow `formats` to say which wins
+```
+
+A preference order would have quietly picked one. Delete the `.json` again when
+you are done.
+
+## The CLI, without any of them
+
+The bundled `whence` command reads the same files with no application running.
+It uses whence's *default* discovery, which searches the current directory
+rather than `config/`, so point it at the files one of two ways:
+
+```console
+$ cd examples
+
+# step 2 of discovery: name the file outright
+$ DEMO_CONFIG=config/demo.toml whence demo explain db.host
+
+# or just stand in the directory the files are in
+$ cd config
+$ whence demo explain db.host --profile prod
+$ whence demo dump --json
+$ whence demo discovery          # every step, including the ones that found nothing
+```
+
+## What these examples do not reach
+
+Honest scope, so you know where to look next rather than assuming it is all here.
+
+| Not exercised | Where it lives |
+| --- | --- |
+| YAML, JSON, XML files | `Discovery(formats=...)` -- the same loader machinery as the two formats used here |
+| pydantic models | `@settings` on a `BaseModel` instead of a dataclass; same `load_settings` call |
+| `search_parents`, `boundary`, `mode="first"`, `file=` | fields on `Discovery`; example 8 names each and exercises `on_missing` |
+| `Binder`, `Problem`, `render_problems` | the binding API underneath `bind`, for reporting problems yourself |
+| Kubernetes ConfigMap symlink swaps | covered by the container test suite (`make test-docker`), not by an example |