# ADR 0023: Keep Configured Secrets Bootstrap Explicit ## Status Accepted. Supersedes [ADR 0004](0004-secret-references-and-explicit-bootstrap.md). ## Date 2026-11-18 ## Context Applications may discover their main configuration file during startup and keep secret files beside it. Requiring applications to discover and parse that file separately duplicates ConfigKit's work. Some deployments also need secret files to replace environment values that are already set. ## Decision Keep secrets as typed references to environment-variable names. Resolve surviving references and keep credential values out of configuration trees, history, and inspection. Applications own credential use. Directory bootstrap remains a separate startup operation that the application must call explicitly. Ordinary configuration loading never writes the process environment. The application may supply the directory directly or authorize bootstrap from settings in the selected main document. Imports, underlays, overlays, and later application processing do not choose those settings. When bootstrap uses the main document, ConfigKit selects and captures that document and its filesystem context for subsequent loading. This keeps bootstrap and loading tied to the same main contents and location. It does not snapshot later imports, resources, or the environment. Preserve existing environment variables by default, including empty values. Allow an explicit overwrite choice. An application-supplied choice takes precedence over the main document's choice, including an explicit choice to preserve existing values. Keep bootstrap reports separate from later secret-lookup evidence. Report writes, skips, and partial failures without credential values. Bootstrap offers no rollback or transaction across environment variables and no protection against concurrent environment mutation. General environment-variable configuration overlays remain outside this model. ## Alternatives Considered - Leave discovery and parsing to applications. This preserves duplicate startup infrastructure and can select different main contents for bootstrap and loading. - Run bootstrap inside ordinary loading. This hides process mutation in an operation applications may repeat or run concurrently. - Always preserve existing environment values. This keeps one precedence rule but prevents deployments from explicitly choosing provisioned files instead. ## Consequences Applications retain control of startup ordering and environment writes. ConfigKit owns main-source capture, bounded secret-file loading, and safe reporting. A later configuration failure leaves completed bootstrap writes in place. Existing callers retain the preservation default.