diff --git a/docs/architecture.md b/docs/architecture.md
index 1c47fd0..5bd252e 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -225,7 +225,7 @@ Today, indexes are built explicitly via `ensure_indices`. Reads degrade graceful
 flowchart LR
     classDef l2 fill:#e8f4fd,stroke:#1e6aa8,color:#000
 
-    cli[omnigraph CLI<br/>13 cmd families]:::l2
+    cli[omnigraph CLI<br/>command families]:::l2
     srv_in[Axum HTTP<br/>REST + OpenAPI]:::l2
     auth[Bearer auth<br/>SHA-256 hashed tokens]:::l2
     pol[Cedar policy gate<br/>per request]:::l2
diff --git a/docs/execution.md b/docs/execution.md
index 7897a9f..6bf55a5 100644
--- a/docs/execution.md
+++ b/docs/execution.md
@@ -141,7 +141,9 @@ sequenceDiagram
 - Run publish: `Omnigraph::publish_run` at `crates/omnigraph/src/db/omnigraph.rs:858`
 - Manifest commit primitive: `ManifestRepo::commit` at `crates/omnigraph/src/db/manifest.rs:280` (called from both per-statement `commit_updates` and the publish path)
 
-Multi-statement mutations don't get atomicity from a single final `commit` — they get it from the **run-branch + publish_run** pattern. Every mutation runs on a fresh `__run__<id>` branch (`begin_run`); each statement individually commits its sub-table updates to that run-branch. After all statements complete, an OCC pre-check verifies the target hasn't moved since the run started, then `publish_run` atomically promotes the run-branch into the target — either via the fast path (direct promotion if the target hasn't moved) or a three-way merge. That final publish is what gives multi-statement mutations their atomicity guarantee (per [`docs/invariants.md`](invariants.md) §VI.26). If anything fails mid-run, the run is failed and the run-branch is dropped without affecting the target. See [runs.md](runs.md) for the full run lifecycle.
+Multi-statement mutations don't get atomicity from a single final `commit` — they get it from the **run-branch + publish_run** pattern. By default a mutation forks a fresh `__run__<id>` branch (`begin_run`); each statement individually commits its sub-table updates to that run-branch. After all statements complete, an OCC pre-check verifies the target hasn't moved since the run started, then `publish_run` atomically promotes the run-branch into the target — either via the fast path (direct promotion if the target hasn't moved) or a three-way merge. That final publish is what gives multi-statement mutations their atomicity guarantee (per [`docs/invariants.md`](invariants.md) §VI.26). If anything fails mid-run, the run is failed and the run-branch is dropped without affecting the target.
+
+One exception: if the caller already targets a `__run__<id>` branch (mutation.rs:555), the mutation runs directly on that branch with no nested run wrapping — the assumption is the caller is managing the surrounding run lifecycle themselves. See [runs.md](runs.md) for the full run lifecycle.
 
 ## Bulk loader (`loader/mod.rs`)