Module overlay 

Environment overlay loader (--env, FDL_ENV, first-arg convention) with per-field origin annotations for fdl config show. Multi-environment configuration overlays.

An fdl.yml project manifest can be layered with per-environment files (e.g. fdl.local.yml, fdl.ci.yml, fdl.cloud.yml). When an environment is active, its file is deep-merged on top of the base config before the strongly-typed ProjectConfig / CommandConfig deserialization runs.

Merge rules

• Maps: deep-merge. Recurse into nested maps; overlay keys win.
• Scalars: replace. Overlay value takes over.
• Lists: replace entirely. (Order is contentious — append/prepend modes cause more debugging pain than they save.)
• null deletes: a key set to null in the overlay removes it from the merged map (not “write null”). Useful for “reset to defaults in this env.”

Discovery

Sibling files matching fdl.<env>.{yml,yaml,json} alongside the base config. The <env> token is the first-arg env selector.

Enums

AnnotatedNode

A merged value plus the layer that produced each leaf.

Functions

deep_merge

Deep-merge over onto base. Maps recurse; scalars and lists replace; null values in a map context delete the key from the result.

find_env_file

Find a sibling overlay for env next to base_config.

list_envs

List every environment overlay discoverable beside the base config.

load_value

Load a YAML/JSON file as a Value. Extension-based dispatch on the file suffix (.yml, .yaml, .json).

merge_layers

Merge a chain of layers left-to-right. The first is the base; each subsequent layer is merged on top of the running result.

merge_layers_annotated

Merge a chain of layers left-to-right with provenance tracking. Mirrors merge_layers but returns an AnnotatedNode instead of a flat Value. Layer indices in the result are positions into layers.

render_annotated_yaml

Emit an AnnotatedNode as YAML with a trailing # <label> on each leaf line, column-aligned for legibility.

resolve_chain

Load path and every ancestor reachable via inherit-from:, returning them in merge order (deepest ancestor first, path itself last). The inherit-from key is removed from every returned Value.