Document when a deploy updates the root config entry

reference/operations-api/operations.md

@@ -878,6 +878,20 @@ Additional parameters:
 
 `urlPath` and `host` both require `package` and are rejected on a payload-only deploy. To mount a payload-deployed component, add `host`/`urlPath` to its entry in the root `harper-config.yaml` instead.
 
+#### How a deploy updates the root config
+
+<VersionBadge type="changed" version="v5.3.0" />
+
+A deploy changes the component's entry in the root `harper-config.yaml` only once the new release is live on that node. A deploy that fails to install or validate leaves the entry exactly as it was, so a restart does not install a release that never went live. If Harper stops partway through the swap, startup settles it before it installs anything from the root config: either the previous release stays live with its entry, or the new release goes live with its entry, including whether the component runs isolated.
+
+- **A `package` deploy replaces the entry.** The new entry is built from the request: `package`, `install`, `credentials`, `urlPath`, `host`, `branchedDatabases`, and `isolated`.
+- **A `payload` deploy removes `package`, `install`, and `credentials`.** Everything else in the entry is kept, such as `host`, `urlPath`, `isolated`, and `branchedDatabases`, and an entry left with no keys is removed. A `package` key left in place would make a node installing from the root config resolve the old package instead of the payload release that is live.
+- **`drop_component` removes the entry.**
+
+These writes are serialized with each other and with `set_configuration`, so concurrent deploys, drops, and configuration changes do not overwrite one another.
+
+A deploy that has to change the entry is refused before anything changes if the root config does not parse, or if Harper cannot write to the directory that holds it. A deploy that leaves the entry as it is, such as a `payload` deploy of a component that has no entry, does not need the root config to be writable.
+
 #### Staging a build and activating it later
 
 <VersionBadge version="v5.3.0" />

release-notes/v5-lincoln/5.3.md

@@ -26,6 +26,12 @@ See [Configuration Options](/reference/v5/configuration/options#node).
 
 `deploy_component` builds each release under `<componentsRoot>/.deploy-staging/<deploymentId>` and validates it before swapping it live. A build that completes but is never activated now survives startup, bounded per component by the new `deployment.stagingRetention.maxCount` setting (default `5`; `0` keeps none). Older builds are removed at the start of the component's next deploy and at startup; anything belonging to an in-flight or unsettled deploy is never touched. Groundwork for deploying from an already-staged build ([harper#2315](https://github.com/HarperFast/harper/issues/2315)). See [Configuration Options](/reference/v5/configuration/options#deployment).
 
+### Root Config Follows the Live Release
+
+A component's entry in the root `harper-config.yaml` now changes only once its new release is live. A `package` deploy used to write the entry before it built, so a deploy that failed to install or validate still left config naming the failed release, and the next restart installed it. The entry is now recorded with the deploy's activation and published after the swap, and startup settles a deploy that was interrupted partway through, so config and the live component agree after a crash, including whether the component runs isolated ([harper#2315](https://github.com/HarperFast/harper/issues/2315)).
+
+**A payload deploy now removes `package`, `install`, and `credentials` from the component's entry**, keeping its other keys such as `host`, `urlPath`, and `isolated`. Previously they stayed, so a node installing the component from its config entry installed the old package instead of the payload release that was live. See [How a deploy updates the root config](/reference/v5/operations-api/operations#how-a-deploy-updates-the-root-config).
+
 ## Security
 
 ### Route-Owned Authentication