diff --git a/src/content/docs/configuration/conditions.mdx b/src/content/docs/configuration/conditions.mdx
index 34cb580325..63ed3cc2d3 100644
--- a/src/content/docs/configuration/conditions.mdx
+++ b/src/content/docs/configuration/conditions.mdx
@@ -90,6 +90,25 @@ into Mergify attributes and a read-only set loaded from GitHub.
 
 <PullRequestAttributesTable />
 
+#### Renamed Files
+
+A rename touches two paths. Mergify treats it the way `git` does with rename detection
+turned off: the file is **removed** at its previous path and **added** at its new one.
+
+For `git mv critical/guard.txt ignored/guard.txt`:
+
+- `files` contains both `critical/guard.txt` and `ignored/guard.txt`
+- `removed-files` contains `critical/guard.txt`
+- `added-files` contains `ignored/guard.txt`
+- `modified-files` contains neither, even when the move also changed the file's content
+- `scope` reports the scopes owning both paths
+
+So `removed-files ~= ^critical/` matches a pull request that moves a file out of
+`critical/`, and a `-files ~= ^critical/` gate is not satisfied by one.
+
+`#files` is GitHub's own changed-file count, which counts a renamed file **once**. It
+therefore does not equal the length of `files` on a pull request containing a rename.
+
 ### GitHub Rulesets and Branch Protection Attributes
 
 Mergify loads these attributes from the GitHub rulesets and branch protection
diff --git a/src/content/docs/merge-queue/scopes.mdx b/src/content/docs/merge-queue/scopes.mdx
index 47e4122af6..897940bd81 100644
--- a/src/content/docs/merge-queue/scopes.mdx
+++ b/src/content/docs/merge-queue/scopes.mdx
@@ -217,6 +217,9 @@ constraints:
   through the API instead (see below), and a configuration with no source has no scopes to impact.
   Mergify rejects `barrier_files` in either case.
 
+A renamed file is matched at both of its paths, so moving a file *out of* a barrier pattern makes
+the pull request a barrier too: the barrier file is gone from the location you declared.
+
 You can also manage these patterns from the dashboard: the **Barrier files** editor in the queue
 configuration **Scopes** section edits the same `barrier_files` filters for file-pattern scopes.
 
diff --git a/src/content/docs/merge-queue/scopes/file-patterns.mdx b/src/content/docs/merge-queue/scopes/file-patterns.mdx
index 86475f307f..f440b61bfd 100644
--- a/src/content/docs/merge-queue/scopes/file-patterns.mdx
+++ b/src/content/docs/merge-queue/scopes/file-patterns.mdx
@@ -108,7 +108,10 @@ scopes:
           - services/users/**/*.go
       frontend:
         include:
-          - apps/web/**/*.{js,jsx,ts,tsx}
+          - apps/web/**/*.js
+          - apps/web/**/*.jsx
+          - apps/web/**/*.ts
+          - apps/web/**/*.tsx
       shared-config:
         include:
           - config/**/*
@@ -139,6 +142,21 @@ the merge queue batch. This ensures:
 - Batching decisions remain consistent even as the queue changes
 - Tests run for the correct scopes regardless of what else is in the batch
 
+### Renamed Files Count at Both Paths
+
+A rename touches two paths: the file disappears from where it was and appears where it
+went. Mergify matches your patterns against **both**, so moving a file out of a scope
+reports that scope just as deleting the file would.
+
+With the multi-language scopes above, `git mv services/api/settings.py config/settings.py`
+reports **both** `python-api` (the path the file left) and `shared-config` (the path it
+arrived at). That matters when a scope guards something: a pull request that moves a file
+out of `services/api/` is a change to `services/api/`, so the `python-api` scope's CI jobs
+and batching rules apply to it.
+
+The same rule applies to `barrier_files`: renaming a file out of a barrier pattern makes
+the pull request a barrier, because the barrier file is gone from its declared location.
+
 ### Path Filtering vs Scopes
 
 GitHub Actions offers path filtering (`on.pull_request.paths`), but it has critical limitations in