diff --git a/reference/environment-variables/overview.md b/reference/environment-variables/overview.md index d30d004b..55fca4a7 100644 --- a/reference/environment-variables/overview.md +++ b/reference/environment-variables/overview.md @@ -78,6 +78,19 @@ loadEnv: Files are loaded in the order specified. +## Config-Shaping Variables + + + +The three configuration env vars — `HARPER_DEFAULT_CONFIG`, `HARPER_CONFIG`, and `HARPER_SET_CONFIG` (see [Configuration](../configuration/overview.md)) — shape Harper's root configuration, which is composed once at startup, before components load. When one of these is delivered through a `loadEnv` `.env` file, Harper applies it before composing the configuration, so `.env` delivery behaves the same as setting a real process environment variable. (Prior to 5.2.0, these variables silently had no effect when delivered via `.env`, because they were read after the configuration had already been composed.) + +Notes and limitations: + +- A real process environment variable still takes precedence over the `.env` value, unless `loadEnv` is configured with `override: true`. +- Encrypted (`enc:v1:`) values cannot shape configuration — secret decryptors are not registered until components load. Such values are skipped with an error log. +- `componentsRoot` cannot be redirected this way: Harper discovers the `.env` files by scanning the components root from the config file, so a `componentsRoot` override delivered via env var or `.env` cannot change where that scan looks. +- Only these three variables are applied early. All other `.env` keys load at component-load time as usual. + ## Related - [Components Overview](../components/overview.md)