@zio.dev/zio-blocks 0.0.51 → 0.0.56

package/reference/config/formats.md

@@ -0,0 +1,314 @@
+---
+id: formats
+title: "File Formats"
+sidebar_label: "File Formats"
+---
+
+Three optional modules add file-format support: `config-yaml`, `config-json`, and `config-hocon`. Each contributes one constructor to the `ConfigSource` companion, parses its format into an in-memory tree, and flattens that tree into the dot-separated namespace every `ConfigSource` exposes. Supporting types: `YamlConfigSource`, `HoconValue`, `HoconError`. One constructor per format:
+
+```scala
+// with `import zio.blocks.config.yaml._`
+ConfigSource.fromYaml(yaml: String, sourceId: String = "yaml:string"): Either[ConfigError, ConfigSource]
+
+// with `import zio.blocks.config.json._`
+ConfigSource.fromJson(json: String, sourceId: String = "json:string"): Either[ConfigError, ConfigSource]
+
+// with `import zio.blocks.config.hocon._`
+ConfigSource.fromHocon(hocon: String, sourceId: String = "hocon:string"): Either[ConfigError, ConfigSource]
+```
+
+## Motivation
+
+A decoder that understood YAML, JSON, and HOCON natively would be three decoders with three sets of bugs. Flattening avoids that: each format is parsed by code that knows only that format, and the result is the same flat map of dotted keys the core module already handles.
+
+The consequence is that everything above the source layer is format-blind. `ConfigSource#orElse` layers a YAML file under environment variables. `ConfigDecoder` reads a JSON document with the same rules it uses for a `Map`. Provenance reports `yaml:string` where it would otherwise report `env`. Nothing in the decoding path branches on format.
+
+Keeping the adapters in separate artifacts means a service that only reads environment variables does not pull a YAML parser, and adding HOCON support is a build change rather than a code change.
+
+## Common Flattening Rules
+
+All three adapters agree on how a tree becomes flat keys. Learning the rules once tells you what key any document produces:
+
+| Tree shape                | Flattened form                            | Example                                     |
+| ------------------------- | ----------------------------------------- | ------------------------------------------- |
+| Nested object or mapping  | Keys joined with `.`                       | `db: { host: x }` → `db.host` = `x`          |
+| Array or sequence         | Zero-based numeric segment                 | `hosts: [a, b]` → `hosts.0` = `a`, `hosts.1` = `b` |
+| Scalar                    | The value as a string                      | `port: 8080` → `port` = `"8080"`             |
+| Null                      | **Omitted entirely**                       | `tag: null` → no `tag` key                   |
+
+Two of these have consequences worth stating plainly.
+
+Indexed sequences are exactly the shape `ConfigDecoder` probes for, so a YAML list decodes into a `List` without any extra configuration. See [Config Decoder](./config-decoder.md).
+
+Null omission means an explicit null is indistinguishable from an absent key. A field of type `Option[A]` becomes `None`, a field with a default takes its default, and a required field reports `ConfigError.MissingKey`. There is no way to express "present but null" through a flattened source.
+
+:::warning[Nulls disappear]
+Writing `tag: null` to unset a value from a lower-priority layer does not work. `ConfigSource#orElse` sees no key at all, so the fallback still wins. Override with a real value instead.
+:::
+
+## YAML
+
+`config-yaml` reads YAML through the `zio-blocks-schema-yaml` reader:
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-blocks-config-yaml" % "0.0.56"
+```
+
+Importing the adapter package makes the constructor available on the `ConfigSource` companion:
+
+```scala
+import zio.blocks.config._
+import zio.blocks.config.yaml._
+
+val yamlText =
+  """|db:
+     |  host: localhost
+     |  port: 5432
+     |hosts:
+     |  - alpha
+     |  - beta
+     |""".stripMargin
+```
+
+Nested mappings become dotted keys and the sequence becomes indexed keys, all as strings:
+
+```scala
+ConfigSource.fromYaml(yamlText, "app.yaml")
+// res0: Either[ConfigError, ConfigSource] = Right(
+//   MapSource(
+//     map = Map(
+//       "hosts.0" -> "alpha",
+//       "hosts.1" -> "beta",
+//       "db.port" -> "5432",
+//       "db.host" -> "localhost"
+//     ),
+//     sourceId = "app.yaml"
+//   )
+// )
+```
+
+The resulting source behaves like any other, so decoding a case class needs nothing format-specific:
+
+```scala
+import zio.blocks.schema.Schema
+
+case class Db(host: String, port: Int)
+
+object Db {
+  implicit val schema: Schema[Db] = Schema.derived[Db]
+}
+```
+
+Re-rooting with `ConfigSource#prefix` reads the `db` section:
+
+```scala
+ConfigSource.fromYaml(yamlText, "app.yaml").map(src => Config.load[Db](src.prefix("db")))
+// res1: Either[ConfigError, Either[::[ConfigError], Db]] = Right(
+//   Right(Db(host = "localhost", port = 5432))
+// )
+```
+
+A document that will not parse yields `ConfigError.InvalidValue` whose `value` is the first 100 characters of the input, truncated with an ellipsis, and whose `cause` is the underlying reader exception. `YamlConfigSource.fromString` is the same operation without the syntax import, for code that prefers an explicit call.
+
+Non-scalar mapping keys are skipped rather than rejected, since a dotted key namespace cannot represent them.
+
+## JSON
+
+`config-json` reads JSON through the `zio-blocks-schema-json` parser:
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-blocks-config-json" % "0.0.56"
+```
+
+The import and the constructor mirror the YAML adapter:
+
+```scala
+import zio.blocks.config._
+import zio.blocks.config.json._
+
+val jsonText =
+  """|{
+     |  "db": { "host": "localhost", "port": 5432 },
+     |  "hosts": ["alpha", "beta"],
+     |  "debug": true
+     |}
+     |""".stripMargin
+```
+
+Numbers and booleans are rendered with their `toString`, so every value arrives as a string for the decoder to parse:
+
+```scala
+ConfigSource.fromJson(jsonText, "app.json")
+// res3: Either[ConfigError, ConfigSource] = Right(
+//   MapSource(
+//     map = Map(
+//       "db.port" -> "5432",
+//       "hosts.0" -> "alpha",
+//       "hosts.1" -> "beta",
+//       "debug" -> "true",
+//       "db.host" -> "localhost"
+//     ),
+//     sourceId = "app.json"
+//   )
+// )
+```
+
+A malformed document yields `ConfigError.InvalidValue` with a 100-character excerpt of the input and the parser's `SchemaError` as the cause.
+
+## HOCON
+
+`config-hocon` has its own parser with no external dependency, and it is the only adapter that supports substitutions and includes:
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-blocks-config-hocon" % "0.0.56"
+```
+
+### Parsing a String
+
+The package object mixes in both the shared and platform-specific syntax, so one import brings in every constructor available on the current platform:
+
+```scala
+import zio.blocks.config._
+import zio.blocks.config.hocon._
+
+val hoconText =
+  """|db {
+     |  host = "localhost"
+     |  port = 5432
+     |}
+     |""".stripMargin
+```
+
+Braces nest into dotted keys, and an integral number flattens without a decimal point — `5432`, not `5432.0`:
+
+```scala
+ConfigSource.fromHocon(hoconText, "app.conf")
+// res5: Either[ConfigError, ConfigSource] = Right(
+//   MapSource(
+//     map = Map("db.host" -> "localhost", "db.port" -> "5432"),
+//     sourceId = "app.conf"
+//   )
+// )
+```
+
+That integral-number handling matters because a value rendered as `5432.0` would not parse as an `Int`. Non-integral and infinite values keep their `Double` rendering.
+
+### Substitutions
+
+Parsing runs in two passes: the text is read into a tree that may contain unresolved `${...}` references, then those references are resolved. Substitution therefore happens **before** flattening, so a substituted value reaches the source layer already expanded:
+
+```scala
+import zio.blocks.config._
+import zio.blocks.config.hocon._
+
+val withSubstitution =
+  """|base = "/srv/app"
+     |paths {
+     |  data = ${base}/data
+     |  logs = ${base}/logs
+     |}
+     |""".stripMargin
+```
+
+The flattened keys hold expanded strings, and nothing downstream needs to know a substitution was involved:
+
+```scala
+ConfigSource.fromHocon(withSubstitution, "app.conf")
+// res7: Either[ConfigError, ConfigSource] = Right(
+//   MapSource(
+//     map = Map(
+//       "base" -> "/srv/app",
+//       "paths.data" -> "/srv/app/data",
+//       "paths.logs" -> "/srv/app/logs"
+//     ),
+//     sourceId = "app.conf"
+//   )
+// )
+```
+
+The resolution pass detects circular references and reports them as a parse failure rather than looping.
+
+### Includes
+
+`include "file"` directives are resolved through a callback, because the core parser does not assume a filesystem. `HoconParser.parse` accepts a `String => Option[String]` that returns the contents of a named resource, which lets includes come from a classpath, an archive, or a test fixture.
+
+On the JVM, `ConfigSource.fromFile` wires that callback to the filesystem for you.
+
+### Loading from a File
+
+`ConfigSource.fromFile` is JVM-only and resolves includes relative to the including file's directory:
+
+```scala
+import zio.blocks.config._
+import zio.blocks.config.hocon._
+
+ConfigSource.fromFile("conf/application.conf")
+```
+
+Two parameters guard against a hostile or accidentally-recursive configuration tree:
+
+| Parameter          | Default | Effect                                                                           |
+| ------------------ | ------- | -------------------------------------------------------------------------------- |
+| `allowedBase`      | `None`  | When set, both the file and every include must resolve inside this directory.      |
+| `maxIncludeDepth`  | `10`    | Maximum nesting depth for includes; exceeding it is a parse failure.               |
+
+Pass `allowedBase` whenever the path comes from outside the program. Paths are canonicalized before the check, so `../` sequences cannot escape:
+
+```scala
+import java.io.File
+import zio.blocks.config._
+import zio.blocks.config.hocon._
+
+ConfigSource.fromFile(
+  path = "conf/application.conf",
+  allowedBase = Some(new File("conf"))
+)
+```
+
+Failures are reported as `ConfigError.ParseError`: a missing file expects `"existing file"`, a path outside `allowedBase` expects `"path inside <base>"`, and a malformed document carries the `HoconError` as its cause. The `sourceId` of a file-loaded source is `hocon:` followed by the file's name.
+
+### HoconValue
+
+`HoconValue` is the parsed tree, exposed for code that needs the structure rather than a flat source:
+
+```scala
+sealed trait HoconValue
+
+object HoconValue {
+  final case class Obj(fields: Map[String, HoconValue]) extends HoconValue
+  final case class Arr(elements: Seq[HoconValue])       extends HoconValue
+  final case class Str(value: String)                   extends HoconValue
+  final case class Num(value: Double)                   extends HoconValue
+  final case class Bool(value: Boolean)                 extends HoconValue
+  case object Null                                      extends HoconValue
+}
+```
+
+`HoconValue.flatten` performs the flattening the adapter uses, and `HoconValue.deepMerge` merges two trees recursively with the right side winning on conflict — the operation a layered HOCON setup needs before flattening, as opposed to `ConfigSource#orElse`, which layers after.
+
+`HoconError` carries a message with the line and column where parsing failed, and extends `Exception` so it can be thrown or attached as a cause:
+
+```scala
+final case class HoconError(message: String, line: Int, column: Int)
+```
+
+## Choosing a Format
+
+The adapters differ in capability, not in how their output is consumed:
+
+| Capability                    | YAML | JSON | HOCON |
+| ----------------------------- | ---- | ---- | ----- |
+| Nested objects and arrays      | Yes  | Yes  | Yes   |
+| Comments                       | Yes  | No   | Yes   |
+| Substitutions (`${...}`)       | No   | No   | Yes   |
+| Includes                       | No   | No   | Yes   |
+| Load from a file               | No   | No   | Yes (JVM) |
+| Scala.js                       | Yes  | Yes  | Yes (string only) |
+
+For everything else, prefer the format your deployment already uses. Because all three flatten identically, switching later changes one constructor call.
+
+## Integration Points
+
+Each adapter depends on the core `config` module for `ConfigSource` and `ConfigError`. YAML and JSON additionally depend on `zio-blocks-schema-yaml` and `zio-blocks-schema-json` for parsing; HOCON has no dependency beyond the core module.
+
+Adapters produce nothing but a `ConfigSource`, so see [ConfigSource](./config-source.md) for composition and provenance, and [Config Decoder](./config-decoder.md) for how the flattened keys become typed values.

package/reference/config/index.md

@@ -0,0 +1,304 @@
+---
+id: index
+title: "Configuration & Feature Flags"
+sidebar_label: "Configuration & Feature Flags"
+---
+
+`zio.blocks.config` loads typed configuration from string-keyed sources, tracks where every resolved value came from, and evaluates feature flags with percentage-based rollouts. The module is synchronous and zero-dependency. Core types: `ConfigSource`, `ConfigDecoder`, `ConfigError`, `Provenance`, `FlagSource`, `StaticFlag`, `DynamicFlag`, `Rollout`. The shapes at the center of the module:
+
+```scala
+trait ConfigSource extends FlagSource {
+  def sourceId: String
+  def get(key: String): Maybe[SourceValue[String]]
+  def all(prefix: String): Map[String, SourceValue[String]]
+}
+
+trait ConfigDecoder[A] {
+  def decode(source: ConfigSource, prefix: String): Either[::[ConfigError], A]
+}
+
+final case class SourceValue[A](value: A, provenance: Provenance)
+```
+
+## Introduction
+
+Configuration in this module is a two-layer story. The bottom layer is a flat, string-to-string namespace: a `ConfigSource` answers `get("db.host")` with a raw string plus a record of where that string came from. The top layer turns that namespace into typed values: a `ConfigDecoder[A]`, derived from `Schema[A]`, walks your case class and pulls one key per field.
+
+Everything in between — composing sources, renaming keys to match an environment's conventions, accumulating errors instead of failing on the first one, redacting secrets when you print what was loaded — happens without an effect type. There is no `IO` wrapper: loading configuration is a synchronous function call that returns `Either`.
+
+Feature flags reuse the same source abstraction. `FlagSource` is the scalar half of `ConfigSource`, so one source object can answer both typed config lookups and flag lookups.
+
+## Motivation
+
+Most configuration libraries make you choose between two unpleasant options: a stringly-typed map that compiles but fails at runtime, or a typed API bolted to a specific effect system and a specific file format. This module avoids both.
+
+- **Typed without ceremony.** A `Schema[A]` you already have — or that `Schema.derived` writes for you — is all a decoder needs. There is no separate config-description DSL to learn and keep in sync with the case class.
+- **Errors accumulate.** A five-field config with three bad fields reports three errors, not the first one. `ConfigError.Composite` carries them all.
+- **Provenance is not an afterthought.** Every value arrives paired with the source that produced it, so "why is this port 8080?" has an answer you can print.
+- **Format-agnostic.** YAML, JSON, and HOCON adapters all flatten to the same dot-separated namespace, so decoding, composition, and provenance work identically regardless of where the bytes came from.
+- **No dependencies, both platforms.** The core module runs on the JVM and Scala.js. Only file-based HOCON loading is JVM-only.
+
+## Installation
+
+The core module provides sources, decoding, and flags:
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-blocks-config" % "0.0.56"
+```
+
+Each file format is a separate artifact, so you depend only on the ones you use:
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-blocks-config-yaml"  % "0.0.56"
+libraryDependencies += "dev.zio" %% "zio-blocks-config-json"  % "0.0.56"
+libraryDependencies += "dev.zio" %% "zio-blocks-config-hocon" % "0.0.56"
+```
+
+For Scala.js, use `%%%` instead of `%%`:
+
+```scala
+libraryDependencies += "dev.zio" %%% "zio-blocks-config" % "0.0.56"
+```
+
+Supported Scala versions: 2.13.x and 3.x.
+
+## Overview
+
+The module divides into three groups of types: the source layer that produces raw strings, the decoding layer that produces typed values, and the flag layer that resolves runtime switches.
+
+### The Source Layer
+
+`ConfigSource` is a flat key-value namespace with dot-separated paths. `ConfigSource.fromMap` builds one from a `Map`, `EnvSource` reads environment variables, and `SysPropSource` reads system properties. Sources compose with `ConfigSource#orElse` and can be re-rooted with `ConfigSource#prefix`. See [Config Source](./config-source.md).
+
+`SourceValue` pairs a raw value with a `Provenance` describing its origin, and `ProvenanceMap` lets you query and print those origins after a successful load. Also on that page: `KeyMapper` and `KeyFormat`, which translate between your canonical camelCase field names and whatever casing the environment actually uses.
+
+### The Decoding Layer
+
+`ConfigDecoder[A]` turns a source into an `A`, accumulating every failure. `ConfigDecoderDeriver` is the `Deriver` that builds those decoders from `Schema[A]`, and it defines the mapping rules: how nested case classes become dotted paths, how sealed traits pick a case from a discriminator key, how sequences and maps are keyed. See [Config Decoder](./config-decoder.md).
+
+`ConfigError` is the failure type, split into four category traits so you can match on the kind of problem rather than the specific constructor. See [Errors](./errors.md).
+
+### The Flag Layer
+
+`StaticFlag[A]` resolves once at class-load time and never changes. `DynamicFlag[A]` holds a rollout expression that can be updated or reloaded while the process runs. Both derive their names from the enclosing Scala object and register themselves globally. See [Flags](./flags.md).
+
+`Rollout` is the expression language behind dynamic flags: a semicolon-separated list of choices, each optionally targeted at a path pattern and a percentage bucket. See [Rollout](./rollout.md).
+
+### The Format Adapters
+
+`config-yaml`, `config-json`, and `config-hocon` each add one `ConfigSource` constructor. They differ in what they support — only HOCON has substitutions and includes — but they agree on the flattening rules. See [File Formats](./formats.md).
+
+## How They Work Together
+
+A typed load moves through four stages. The source produces raw strings, the decoder walks the schema requesting one key per field, errors accumulate rather than short-circuit, and the result is either a fully-built value or every problem found along the way:
+
+```
+1. Build a source            ConfigSource.fromMap / fromYaml / EnvSource
+2. Compose and re-root       source.orElse(fallback).prefix("app")
+3. Derive a decoder          ConfigDecoder.derive[A]  (from Schema[A])
+4. Decode                    decoder.decode(source, "")
+                                 │
+                                 ├─ Right(a)      all fields resolved
+                                 └─ Left(errors)  every failure, accumulated
+```
+
+The type relationships behind those stages:
+
+```
+FlagSource ─────────────────┐  get(name): Maybe[SourceValue[String]]
+     ▲                      │
+     │ extends              │
+ConfigSource ───────────────┤  + all(prefix): Map[String, SourceValue[String]]
+     │                      │
+     ├─ MapSource           │
+     ├─ EnvSource           │  DB_HOST  ← db.host
+     ├─ SysPropSource       │
+     └─ (yaml/json/hocon)   │  flattened to dotted keys
+                            │
+                            └─> SourceValue ──> Provenance
+                                                  ├─ Resolved(sourceId, key, rawValue)
+                                                  └─ Default
+
+Schema[A] ──deriving──> ConfigDecoderDeriver ──> ConfigDecoder[A]
+                                                      │
+                                    decode(source, prefix)
+                                                      │
+                                    ┌─────────────────┴──────────────────┐
+                                    ▼                                    ▼
+                              Right(A)                        Left(::[ConfigError])
+                                                                   ├─ MissingKey
+                                                                   ├─ InvalidValue
+                                                                   ├─ ParseError
+                                                                   └─ Composite(all)
+
+StaticFlag[A]   ──resolves once──> Registry → sysprop → env → default
+DynamicFlag[A]  ──evaluates──>   Rollout.Choices x bucket → value
+```
+
+## Common Patterns
+
+Four shapes cover most usage: a straight typed load, a layered load where environment variables win over file defaults, wiring config into a dependency graph, and loading with provenance so you can explain what happened.
+
+### Loading a Typed Value
+
+`Config.load` derives a decoder and runs it, returning every error it found:
+
+```scala
+import zio.blocks.config._
+import zio.blocks.schema.Schema
+
+case class Db(host: String, port: Int)
+
+object Db {
+  implicit val schema: Schema[Db] = Schema.derived[Db]
+}
+
+val source = ConfigSource.fromMap(Map("host" -> "localhost", "port" -> "5432"), "example")
+```
+
+Decoding returns `Either[::[ConfigError], Db]`, where `::` is Scala's non-empty list, so a `Left` always carries at least one error:
+
+```scala
+Config.load[Db](source)
+// res0: Either[::[ConfigError], Db] = Right(
+//   Db(host = "localhost", port = 5432)
+// )
+```
+
+When a key is missing, the error names both the path and the source that was searched:
+
+```scala
+Config.load[Db](ConfigSource.fromMap(Map("host" -> "localhost"), "example"))
+// res1: Either[::[ConfigError], Db] = Left(
+//   List(MissingKey(path = "port", source = "example"))
+// )
+```
+
+### Layering Sources
+
+Production configuration usually comes from more than one place: a file provides defaults and the environment overrides them. `ConfigSource#orElse` consults the receiver first and falls back to the argument, and provenance still records which one actually answered:
+
+```scala
+import zio.blocks.config._
+import zio.blocks.schema.Schema
+
+case class Db(host: String, port: Int)
+
+object Db {
+  implicit val schema: Schema[Db] = Schema.derived[Db]
+}
+
+val defaults = ConfigSource.fromMap(Map("host" -> "localhost", "port" -> "5432"), "defaults")
+val envOverrides = ConfigSource.fromMap(Map("host" -> "db.prod.internal"), "env")
+```
+
+The override wins for `host`, and `port` falls through to the defaults:
+
+```scala
+Config.load[Db](envOverrides.orElse(defaults))
+// res3: Either[::[ConfigError], Db] = Right(
+//   Db(host = "db.prod.internal", port = 5432)
+// )
+```
+
+### Wiring Config into a Dependency Graph
+
+Rather than decoding at startup and threading the result through constructors, `Config.wire` produces a `Wire.Shared[ConfigSource, A]` so decoding becomes a node in the graph. The `ConfigSource` is the injected input; the typed config is the derived output:
+
+```scala
+import zio.blocks.config._
+import zio.blocks.context.Context
+import zio.blocks.schema.Schema
+import zio.blocks.scope.{Resource, Scope, Unscoped, Wire}
+
+case class Db(host: String, port: Int)
+
+object Db {
+  implicit val schema: Schema[Db]     = Schema.derived[Db]
+  implicit val unscoped: Unscoped[Db] = Unscoped.derived[Db]
+}
+
+final class DbService(val config: Db)
+
+val source   = ConfigSource.fromMap(Map("host" -> "localhost", "port" -> "5432"), "graph")
+val resource = Resource.from[DbService](Wire(source), Config.wire[Db])
+
+Scope.global.scoped { scope =>
+  import scope._
+  val service = allocate(resource)
+  $(service)(_.config)
+}
+```
+
+`Config.wire[A](prefix)` re-roots the injected source before decoding, which is how you keep several config sections in one graph without giving each its own source.
+
+### Loading with Provenance
+
+`Config.loadWithProvenance` returns a `ProvenanceMap[A]` alongside the value, which answers per-key origin questions and renders a table for startup logs:
+
+```scala
+import zio.blocks.config._
+import zio.blocks.schema.Schema
+
+case class Db(host: String, port: Int)
+
+object Db {
+  implicit val schema: Schema[Db] = Schema.derived[Db]
+}
+
+val source = ConfigSource.fromMap(Map("host" -> "localhost", "port" -> "5432"), "startup")
+val loaded = Config.loadWithProvenance[Db](source)
+```
+
+Querying a single key reports the source id, the source-facing key, and the raw string:
+
+```scala
+loaded.map(_.provenanceOf("host"))
+// res6: Either[::[ConfigError], Maybe[Provenance]] = Right(
+//   Resolved(sourceId = "startup", key = "host", rawValue = "localhost")
+// )
+```
+
+`ProvenanceMap#dump` renders every visible key as a table, redacting values whose key names look sensitive:
+
+```scala
+loaded.map(_.dump()).foreach(println)
+// ┌──────┬───────────┬─────────┐
+// │ Key  │ Value     │ Source  │
+// ├──────┼───────────┼─────────┤
+// │ host │ localhost │ startup │
+// │ port │ 5432      │ startup │
+// └──────┴───────────┴─────────┘
+```
+
+## Entry Points
+
+`Config` is the front door for typed loading. Which method you want depends on how you handle failure and whether you need provenance:
+
+| Method                        | Returns                              | Use when                                                        |
+| ----------------------------- | ------------------------------------ | --------------------------------------------------------------- |
+| `Config.load[A]`              | `Either[::[ConfigError], A]`          | You want to inspect or report errors yourself.                   |
+| `Config.loadOrThrow[A]`       | `A`                                  | Failure should abort startup; throws `ConfigLoadException`.       |
+| `Config.loadWithProvenance[A]`| `Either[::[ConfigError], ProvenanceMap[A]]` | You need to explain where values came from.               |
+| `Config.wire[A]`              | `Wire.Shared[ConfigSource, A]`       | Decoding belongs inside a dependency graph.                      |
+
+`Config.load` derives a fresh decoder on every call. When you load the same type repeatedly — during reloads, or per request — derive once with `ConfigDecoder.derive[A]` and reuse the result.
+
+:::warning[Derivation is not free]
+`Schema.derived` runs at compile time, but turning a `Schema[A]` into a `ConfigDecoder[A]` happens at runtime and walks the whole schema. Calling `Config.load[A]` in a hot path re-does that walk every time.
+:::
+
+## Integration Points
+
+The module sits on top of three other blocks and hands its output to a fourth:
+
+- **`zio-blocks-schema`** supplies `Schema[A]`, and `ConfigDecoderDeriver` is an ordinary `Deriver[ConfigDecoder]`. Anything the schema layer can describe — records, variants, sequences, maps, wrappers, dynamic values — has a decoding rule.
+- **`zio-blocks-maybe`** supplies `Maybe`, the allocation-free option type returned by every source lookup.
+- **`zio-blocks-scope`** supplies `Wire` and `Resource`, which is what `Config.wire` produces so config can participate in dependency graphs.
+- **`zio-blocks-schema-yaml`** and **`zio-blocks-schema-json`** back the YAML and JSON adapters; the HOCON adapter has its own parser and no external dependency.
+
+Within the module, the dependency direction is one-way: sources know nothing about decoders, decoders know nothing about flags, and flags reuse `FlagSource` without reaching into `ConfigDecoder`.
+
+## Next Steps
+
+Start with [Config Source](./config-source.md) to build and compose sources, then [Config Decoder](./config-decoder.md) for the mapping rules from case classes to keys. [Errors](./errors.md) covers the failure model, [Flags](./flags.md) and [Rollout](./rollout.md) cover runtime switches, and [File Formats](./formats.md) covers YAML, JSON, and HOCON.