# Main-relative secrets directories ## Motivation and baseline Applications can use `SearchConfig` to select their main configuration file during a load. They can also call `LoadSecretsIntoEnvironment` during startup, but that helper takes a native directory path before the load begins. A relative argument uses the process working directory. Using a directory beside the discovered file therefore requires the application to take over main-file selection or perform a preliminary load. [Configuration discovery](../config.md#configuration-discovery) · [Secrets bootstrap](../config.md#explicit-secrets-directory-bootstrap) ConfigKit already carries the selected main's filesystem context into layered loading. It resolves effective typed `Secret` references after application resolution and before final validation. Those two points provide the base for the directory and the set of credential names to read. [Main-relative contexts](../adr/0022-main-relative-context.md) · [Typed secret references](../config.md#typed-secret-references) ## Target behavior ### Declaration and path resolution An application opts in through Go when calling `Load` or `LoadLayered`. The selected main document supplies one relative directory through its root control mapping. For example, the following declaration in `/etc/demo/config.yml` selects `/etc/demo/secrets` when discovery selects that main file. ```yaml config: secrets_dir: secrets api_key: DEMO_API_KEY ``` Interpret the declaration at the main document's root before placement and composition. Diagnose a declaration used without opt-in or in an unsupported source-control context. Nested application data follows the existing `config` rules. The location comes from the main document even when an import, overlay, CLI override, default, or application resolution supplies the final credential name. Environment lookup alone applies when there is no declaration, including when an optional search finds no main file. Resolve the directory from the selected main file's canonical base within its existing filesystem root. For a discovered symlink, the base is the selected file's canonical target directory. Parent-relative paths follow the same containment rule as other main-relative inputs. The declaration must be a nonempty relative path and requires a usable main-file context. Keep the declaration and any diagnostics in source-local coordinates. [Document-root controls](../adr/0020-document-root-controls.md) · [Layered loading](../config.md#layered-loading) ### Lookup within a load The usual opt-in mode checks the environment first. A present variable wins, including an empty one, which produces the existing empty-secret failure. For an unset variable, read the file whose name matches the effective typed `Secret` reference. The directory is accessed only if a reference needs a file. An application can also select file-first lookup for a load. An absent file allows environment lookup. A file that is present but unreadable or invalid produces a safe diagnostic, and an empty file follows the existing rule that a resolved credential must be nonempty. If neither source supplies a credential, report the failure at the affected configuration field. Resolve surviving references at the existing secret-resolution step and share the lookup result for repeated names within that load. Use the existing secret-file checks, content rules, and per-file and cumulative byte limits for the files read. Exact-name lookup leaves unrelated directory entries alone. Close library-owned handles during the load. Final validation sees the resolved credentials, with byte access through `Secret.Value()`. Inspection can distinguish the environment and a file as the credential provider while keeping credential bytes outside diagnostics, history, and effective YAML. ### Explicit startup export Applications that start SDKs or subprocesses which read the environment can explicitly request file-first loading and environment export. This is a startup operation distinct from the ordinary load entry points. Go code authorizes writes and overwrites. The main-file declaration selects the directory. Complete configuration loading and validation before writing to the process environment. Export the values of the file-backed effective references used by that successful load, once per name. Each successful write sets the variable to the same value used by the returned configuration. If a file is absent and lookup uses an existing environment value, leave that variable alone. Invoke this operation during startup before starting concurrent work. It runs synchronously and reports successful writes and partial failures without credential bytes, following the existing bootstrap reporting model. ConfigKit does not roll back earlier writes when a later write fails. Ordinary `Load` and `LoadLayered` resolve credentials for their own results without writing to the environment. The existing `LoadSecretsIntoEnvironment(directory)` remains the explicit startup helper for callers supplying a directory independently. [Complete-on-return loading](../adr/0008-complete-on-return-loading.md) · [Secret references and explicit bootstrap](../adr/0004-secret-references-and-explicit-bootstrap.md) ## Work needed - Extend main-document control parsing and the public load options to capture the opted-in declaration and bind it to the main context already obtained during acquisition. Carry the binding into secret resolution without another search or parse. - Reuse the secret-file reading and validation rules for exact-name lookup. Extend the operation-local lookup to report value-free filesystem failures and retain the provider for inspection separately from configuration value provenance. - Add the explicit startup operation around the shared load lifecycle. Use the resolved file values for export and reuse the bootstrap reporting semantics where they fit. - Verify discovery from a different working directory, canonical main paths, declaration scope, both lookup orders, and effective references after composition and application resolution. Cover unused and missing files, empty values, read errors, safe inspection, and startup export after validation, including partial writes and absence of writes on a failed load. Use disposable credential values and deterministic failure seams in line with the [testing policy](../policy/testing.md). - Document the resulting contract and a consumer startup example. Record the architectural decision to add file-backed resolution and explicit startup export alongside ADR 0004, and align the current architecture and component documentation when the feature lands. ## Open Decisions ### Startup API and export failure reporting **Recommendation.** Provide explicit startup entry points corresponding to ordinary and layered loading, backed by the same load implementation. Return the configuration outcome and the export report so callers can distinguish a failed load from a successful load followed by an environment write failure. The successful load's private file values can be handed directly to export within the call, which keeps the application flow short and the lifetime of those values local to the startup operation. **Alternative.** Export from a successfully returned result through a separate explicit call. This gives applications control over when to perform the writes and avoids a parallel pair of load entry points. It requires a result contract for retaining the original file-backed assignments or defining how later application edits to the result affect export. ### Filesystem scope **Recommendation.** Support discovered and explicitly selected host files first, including their existing main-root options. These cover the requested deployment pattern and allow reuse of the existing native secret-file checks. **Alternative.** Support caller-supplied filesystems with a usable main-file context in the same change. This aligns with companion inputs and supports virtual filesystems. It requires an explicit decision about file-type and symlink handling where a caller filesystem exposes different metadata or access capabilities.