Environment Variables Migration

migration-context/link-placeholders/environment-variables-link-placeholders.md

@@ -0,0 +1,19 @@
+# Link Placeholders for Environment Variables
+
+## reference_versioned_docs/version-v4/environment-variables/overview.md
+
+- Line 14: `[Configuration](TODO:reference_versioned_docs/version-v4/configuration/overview.md)`
+  - Context: Intro list item — "Harper configuration via environment variables — see Configuration"
+  - Target should be: Configuration section overview page
+
+- Line 67: `[Resource Extension](TODO:reference_versioned_docs/version-v4/components/overview.md)`
+  - Context: Describing that `loadEnv` is a Resource Extension supporting standard `files`/`urlPath` config options
+  - Target should be: Components overview page (covering the Resource Extension concept)
+
+- Line 79: `[Components Overview](TODO:reference_versioned_docs/version-v4/components/overview.md)`
+  - Context: "Related" section
+  - Target should be: Main components/extensions reference page
+
+- Line 80: `[Configuration](TODO:reference_versioned_docs/version-v4/configuration/overview.md)`
+  - Context: "Related" section — linking to where env var config details live
+  - Target should be: Configuration section overview page

reference_versioned_docs/version-v4/environment-variables/overview.md

@@ -0,0 +1,77 @@
+---
+id: overview
+title: Environment Variables
+---
+
+<!-- Source: versioned_docs/version-4.7/reference/components/built-in-extensions.md (primary - loadEnv section) -->
+<!-- Source: versioned_docs/version-4.5/developers/components/built-in.md (for v4.5 feature introduction) -->
+<!-- Source: release_notes/4.5.0.md (confirmed loadEnv introduction) -->
+
+Harper supports loading environment variables in Harper applications `process.env` using the built-in `loadEnv` plugin. This is the standard way to supply secrets and configuration to your Harper components without hardcoding values. `loadEnv` does **not** need to be installed as it is built into Harper and only needs to be declared in your `config.yaml`.
+
+:::note
+If you are looking for information on how to configure your Harper installation using environment variables, see [Configuration](TODO:reference_versioned_docs/version-v4/configuration/overview.md 'Configuration section overview, including environment variable configuration') section for more information.
+:::
+
+## Basic Usage
+
+```yaml
+loadEnv:
+  files: '.env'
+```
+
+This loads the `.env` file from the root of your component directory into `process.env`.
+
+## Load Order
+
+> **Important:** Specify `loadEnv` first in your `config.yaml` so that environment variables are loaded before any other components start.
+
+```yaml
+# config.yaml — loadEnv must come first
+loadEnv:
+  files: '.env'
+
+rest: true
+
+myApp:
+  files: './src/*.js'
+```
+
+Because Harper is a single-process application, environment variables are loaded onto `process.env` and are shared across all components. As long as `loadEnv` is listed before dependent components, those components will have access to the loaded variables.
+
+## Override Behavior
+
+By default, `loadEnv` follows the standard dotenv convention: **existing environment variables take precedence** over values in `.env` files. This means variables already set in the shell or container environment will not be overwritten.
+
+To override existing environment variables, use the `override` option:
+
+```yaml
+loadEnv:
+  files: '.env'
+  override: true
+```
+
+## Multiple Files
+
+As a Harper plugin, `loadEnv` supports multiple files using either glob patterns or a list of files in the configuration:
+
+```yaml
+loadEnv:
+  files:
+    - '.env'
+    - '.env.local'
+```
+
+or
+
+```yaml
+loadEnv:
+  files: 'env-vars/*'
+```
+
+Files are loaded in the order specified.
+
+## Related
+
+- [Components Overview](TODO:reference_versioned_docs/version-v4/components/overview.md 'Components, Applications, and Extensions overview')
+- [Configuration](TODO:reference_versioned_docs/version-v4/configuration/overview.md 'Configuration section, including environment variable configuration conventions and HARPER_DEFAULT_CONFIG / HARPER_SET_CONFIG')

reference_versioned_sidebars/version-v4-sidebars.json

@@ -33,6 +33,19 @@
 				}
 			]
 		},
+		{
+			"type": "category",
+			"label": "Environment Variables",
+			"collapsible": false,
+			"className": "learn-category-header",
+			"items": [
+				{
+					"type": "doc",
+					"id": "environment-variables/overview",
+					"label": "Overview"
+				}
+			]
+		},
 		{
 			"type": "category",
 			"label": "GraphQL Querying",

v4-docs-migration-map.md

@@ -65,10 +65,19 @@ This document maps existing documentation paths from `versioned_docs/version-4.X
   - Current `reference/configuration.md`
   - `versioned_docs/version-4.1/configuration.md` (baseline)
 - **Status**: Not Started
+- **Notes**: Must include a dedicated section on environment variable configuration. Content researched and ready from the environment-variables migration:
+  - **Naming convention**: YAML keys map to `SCREAMING_SNAKE_CASE` env vars (e.g. `http.port` → `HTTP_PORT`, `operationsApi.network.port` → `OPERATIONSAPI_NETWORK_PORT`). Case-insensitive. Component configuration cannot be set this way.
+  - **`HDB_CONFIG`**: CLI/ENV variable to specify a custom config file path at install time. Source: `versioned_docs/version-4.7/deployments/configuration.md` lines 51-55.
+  - **`HARPER_DEFAULT_CONFIG`**: Added in v4.7.2. Sets default config values as JSON, respects user edits, restores original on key removal. Source: `versioned_docs/version-4.7/deployments/configuration.md` lines 80-116 + `release_notes/4.7.2.md`.
+  - **`HARPER_SET_CONFIG`**: Added in v4.7.2. Forces config values that always win, even over user edits. Deleted (not restored) on key removal. Source: `versioned_docs/version-4.7/deployments/configuration.md` lines 118-145 + `release_notes/4.7.2.md`.
+  - **Configuration precedence**: `HARPER_SET_CONFIG` > user manual edits > `HARPER_DEFAULT_CONFIG` > file defaults.
+  - **State tracking**: Harper maintains `{rootPath}/backup/.harper-config-state.json` for drift detection and restoration.
+  - Full content is in `reference_versioned_docs/version-v4/environment-variables/configuration.md` — this file should be deleted after porting its content here.
 - **Release Notes**:
   - [4.2.0](release-notes/v4-tucker/4.2.0.md) - Major config changes (http section, componentRoot)
   - [4.3.0](release-notes/v4-tucker/4.3.0.md) - Configuration improvements
   - [4.4.0](release-notes/v4-tucker/4.4.0.md) - Developer/production mode
+  - [4.7.2](release-notes/v4-tucker/4.7.2.md) - HARPER_SET_CONFIG and HARPER_DEFAULT_CONFIG added
 
 ### `reference/configuration/options.md`
 
@@ -402,15 +411,11 @@ This document maps existing documentation paths from `versioned_docs/version-4.X
 - **Primary Source**: New content about `loadEnv` plugin
 - **Additional Sources**: Built-in extensions docs, configuration docs
 - **Version Annotations**: loadEnv added in v4.5.0
-- **Status**: Not Started
+- **Status**: In Progress
+- **Notes**: Covers `loadEnv` extension only. Harper-level environment variable configuration (naming conventions, `HDB_CONFIG`, `HARPER_DEFAULT_CONFIG`, `HARPER_SET_CONFIG`) belongs in the Configuration section — see notes there.
 - **Release Notes**:
   - [4.5.0](release-notes/v4-tucker/4.5.0.md) - Built-in loadEnv component
 
-### `reference/environment-variables/configuration.md`
-
-- **Primary Source**: Extract from configuration docs or components docs
-- **Status**: Not Started
-
 ---
 
 ## Static Files Section