Sources (ConfigSource)
The ConfigSource abstraction — where the config comes from. YAML files, env, future adapters for etcd / Consul / Vault / HTTP / SQL / K8s.
Configuration layers
The three YamlFileSource layers — base + local + environment-specific. Merge order, DAGSTACK_ENV, merge rules for objects and arrays.
Environment variable substitution
The ${VAR} / ${VAR:-default} syntax, interpolation semantics, handling missing variables, the $$ escape.
Secrets
Two layers of the secrets surface — auto-masking by field name (Phase 1) and SecretSource adapters with ${secret:scheme:path} references (Phase 2, ADR-0002). EnvSecretSource, VaultSource, lazy vs eager resolution, refresh, error taxonomy.
Secret sources
Operator guide for SecretSource adapters — install commands per binding, Vault auth methods (Token / AppRole / Kubernetes ServiceAccount), namespace, token renewal boundary, what is deferred to Phase 3.
Hot reload (watch)
Subscribe to your section through onSectionChange, atomic rollback on invalid configs, and the subscription_without_watch fallback.