docs(configuration): document HARPER_CONFIG and the $union array directive

[heskew]

Summary

Documents the two config env-var features shipped in HarperFast/harper#1217 ($union) and #1238 (HARPER_CONFIG), both sub-issues of HarperFast/harper#1097. All changes are in reference/configuration/overview.md.

• HARPER_CONFIG — new, documented as the recommended way to set configuration from the environment: merge semantics (sets only the keys it names), reasserts its keys on every restart, yields only to HARPER_SET_CONFIG, with individual env vars/CLI args still winning for the keys they set, and original-value restoration on key removal.
• $union array directive — how to compose an array (idempotent, order-preserving, non-destructive) instead of the default wholesale replace, across all three config env vars; plus the note that only recognized $-directives ($union) are special so JSON-Schema $schema/$ref in component config pass through untouched.
• Updated the intro (two → three variables), the precedence ladder, the "combining" example (platform-pins-via-SET + app-sets-via-CONFIG), and the state-tracking and backup notes to cover all three variables.

Targets v5.1.0 version badges, matching the existing v5.0.0 convention in these docs.

Notes

• Single file touched; prettier --check clean. Built on a worktree off main (not the in-progress docs/models-5.1 branch).
• Closes the documentation deliverable in Add HARPER_CONFIG as the recommended way to set configuration from the environment harper#1097.

---

🤖 Generated with Claude Code (agent: Claude Opus 4.8)

[gemini-code-assist]

Code Review

This pull request updates the configuration overview documentation to introduce the new HARPER_CONFIG environment variable and the $union directive for array composition. The review feedback suggests two key improvements: replacing the undocumented tls.uses example with a standard option like applications.allowedSpawnCommands to prevent user confusion, and correcting a technical inaccuracy regarding drift detection to clarify that HARPER_CONFIG unconditionally reasserts its values on startup.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The example uses tls.uses as an illustration of the $union directive. However, tls.uses is not a documented configuration option in options.md (where only certificate, certificateAuthority, privateKey, and ciphers are listed under tls).

To avoid confusing users, it is recommended to use a standard, documented array option as the example, such as applications.allowedSpawnCommands.

Here is the suggested update:

By default an array in any of these variables **replaces** the existing array wholesale — the same as a plain value. To instead **compose** an array, wrap it in a `$union` directive:

```bash
export HARPER_SET_CONFIG='{"applications":{"allowedSpawnCommands":{"$union":["npm","node"]}}}'

$union guarantees the listed items are present in the target array while preserving any entries already there — the order-preserving union of (existing ∪ listed). It is:

• Idempotent — reapplying the same $union on every restart is a no-op; it never grows duplicates
• Non-destructive — it only adds the items it names and never removes other entries, even under HARPER_SET_CONFIG's drift handling

This lets a platform layer guarantee required array entries (for example applications.allowedSpawnCommands) on every restart without clobbering entries an application adds. $union works in all three variables. A bare array (no $union) still replaces, which remains the default.

[gemini-code-assist]

The phrase (and, for HARPER_CONFIG, reasserting the configured value) under Drift detection is technically inaccurate.

Drift detection is specifically used for HARPER_DEFAULT_CONFIG to identify manual edits so that Harper knows not to overwrite them. In contrast, HARPER_CONFIG unconditionally merges and reasserts its values on startup regardless of any manual edits (it does not need to "detect" drift to do this).

It is recommended to keep the drift detection description focused on HARPER_DEFAULT_CONFIG to avoid confusing the two mechanisms.

Suggested change:

- **Drift detection**: Identifying when users manually edit values set by `HARPER_DEFAULT_CONFIG`

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-529

This preview will update automatically when you push new commits.