diff --git a/.gittensory.yml.example b/.gittensory.yml.example
index d76e7049e1..f9812b8073 100644
--- a/.gittensory.yml.example
+++ b/.gittensory.yml.example
@@ -298,7 +298,9 @@ gate:
   # stricter verdict for AI-review blocker mode. It does not disable downstream
   # merge/close planning for failures from already-enforced gates. Bool.
   # Default: false. Config-as-code only — no DB column or dashboard toggle;
-  # this can only be set here.
+  # this can only be set here. Unrelated to settings.agentDryRun below despite
+  # the shared "dry run" name -- this only affects the check-run's display
+  # conclusion; it does NOT stop the agent action layer from real writes.
   dryRun: false
 
   # First-time-contributor grace. RESERVED / currently INERT: this value is
@@ -690,6 +692,7 @@ settings:
 
   # Dry-run / shadow mode: suppresses the terminal GitHub-side write only. AI/LLM review calls still
   # execute and still incur their normal provider cost -- this is NOT a cost-free preview.
+  # Independent of gate.dryRun above -- the two "dry run" fields gate entirely disjoint layers.
   # Bool. Default: false.
   agentDryRun: false
 
diff --git a/config/examples/gittensory.full.yml b/config/examples/gittensory.full.yml
index f89e4d4079..dc779d2c7e 100644
--- a/config/examples/gittensory.full.yml
+++ b/config/examples/gittensory.full.yml
@@ -311,7 +311,9 @@ gate:
   # stricter verdict for AI-review blocker mode. It does not disable downstream
   # merge/close planning for failures from already-enforced gates. Bool.
   # Default: false. Config-as-code only — no DB column or dashboard toggle;
-  # this can only be set here.
+  # this can only be set here. Unrelated to settings.agentDryRun below despite
+  # the shared "dry run" name -- this only affects the check-run's display
+  # conclusion; it does NOT stop the agent action layer from real writes.
   dryRun: false
 
   # First-time-contributor grace. RESERVED / currently INERT: this value is
@@ -703,6 +705,7 @@ settings:
 
   # Dry-run / shadow mode: suppresses the terminal GitHub-side write only. AI/LLM review calls still
   # execute and still incur their normal provider cost -- this is NOT a cost-free preview.
+  # Independent of gate.dryRun above -- the two "dry run" fields gate entirely disjoint layers.
   # Bool. Default: false.
   agentDryRun: false
 
diff --git a/src/types.ts b/src/types.ts
index 85dca132d0..4847bbd944 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -794,7 +794,9 @@ export type RepositorySettings = {
   expectedCiContexts?: ReadonlyArray<string> | null | undefined;
   /** Dry-run disposition (#gate-dryrun). When true, the gate renders the would-be merge/close/manual verdict (every
    *  advisory sub-gate promoted to block) WITHOUT enforcing — the posted check stays non-blocking. Lets advisory mode
-   *  preview exactly what it would do before the maintainer flips to real enforcement. Default off. */
+   *  preview exactly what it would do before the maintainer flips to real enforcement. Default off.
+   *  Unrelated to {@link agentDryRun} despite the shared "dry run" name -- this only affects the check-run's
+   *  DISPLAY conclusion; it does NOT stop the agent action layer from performing real merges/closes/comments. */
   gateDryRun?: boolean | undefined;
   /** Live premerge migrations/** collision recheck (#2550). When true, an agent-driven merge of a PR that
    *  touches migrations/** is preceded by a fresh GitHub Trees-API read of the base branch's CURRENT migration
@@ -1098,7 +1100,8 @@ export type RepositorySettings = {
    *  performing any GitHub mutation -- but this is NOT a cost-free preview: AI/LLM review calls still
    *  execute and still incur their normal provider cost (deliberate design tagged `#token-bleed-spend-gate`
    *  in `ai-review-orchestration.ts`/`agent-orchestrator.ts`/`processors.ts`; every spend gate checks only
-   *  `agentPaused`, never this field). Default false. */
+   *  `agentPaused`, never this field). Default false. Independent of the gate check's own {@link gateDryRun}
+   *  preview -- the two "dry run" fields gate entirely disjoint layers with no shared code path. */
   agentDryRun?: boolean | undefined;
   /** Per-repo override of the global DB-backed agent freeze (#4372): when true, this repo's actions execute
    *  even while `global_agent_controls.frozen` is set, so an operator can re-activate one repo at a time