diff --git a/docs/approvals.md b/docs/approvals.md
index 4d27167e..2656eb0e 100644
--- a/docs/approvals.md
+++ b/docs/approvals.md
@@ -90,7 +90,7 @@ initial configuration before any container is created.
 
 ### Approval kinds (wire shapes)
 
-`ApprovalKind` carries five variants; each maps to a different
+`ApprovalKind` carries six variants; each maps to a different
 `commit_ref` encoding because that field is overloaded as the
 kind-specific payload carrier.
 
@@ -99,6 +99,16 @@ kind-specific payload carrier.
   proposal fetch lives in `fetched_sha` on the same `Approval`
   row (only `ApplyCommit` populates it). See the End-to-end flow
   above.
+- `MergeConfigPr` — the PR-based config flow's counterpart to
+  `ApplyCommit`. `commit_ref` stores the **PR number** (decimal),
+  and `fetched_sha` is the PR **head sha the operator reviewed**.
+  On approve, `run_merge_config_pr` re-reads the live PR head and
+  aborts if it drifted from `fetched_sha` (re-review), then fetches
+  that head into the applied repo, eval-verifies it, fast-forwards
+  the forge config repo's `main` to it (the merge), marks the PR
+  merged (best-effort — `main` is already there), and runs the same
+  shared deploy tail as `ApplyCommit` (`deploy_applied_target`).
+  Never a first spawn.
 - `Spawn` — direct container creation under the default
   `agent.nix` template. `commit_ref` is empty. Submitted via
   `HostRequest::RequestSpawn` (operator-gated, the
@@ -323,6 +333,7 @@ the approval handler enqueues a `QueueEntry` into the global
 | `ApprovalKind` | `QueueKind` queued | `QueueSource` |
 |---|---|---|
 | `ApplyCommit` | `Rebuild` | `Approval` |
+| `MergeConfigPr` | `Rebuild` | `Approval` |
 | `UpdateMetaInputs` | `MetaUpdate` | `Approval` |
 | `Spawn` | `Spawn` | `Approval` |
 | `InitConfig` | — runs inline (sub-second git seed) | — |
@@ -331,7 +342,8 @@ the approval handler enqueues a `QueueEntry` into the global
 Each queue entry carries the originating `approval_id` so the
 worker can re-fetch the approval row when it dispatches, run the
 kind-specific pipeline (`run_approval_apply_commit` /
-`run_approval_update_meta_inputs` / `run_approval_spawn`), and
+`run_approval_merge_config_pr` / `run_approval_update_meta_inputs` /
+`run_approval_spawn`), and
 fire the matching `HelperEvent::*` on completion via
 `finish_approval`.