diff --git a/images/references/workspace/scope-dependencies.png b/images/references/workspace/scope-dependencies.png
new file mode 100644
index 00000000..489ad1b0
Binary files /dev/null and b/images/references/workspace/scope-dependencies.png differ
diff --git a/references/workspace/custom-roles.mdx b/references/workspace/custom-roles.mdx
index df1076da..d40b0d9f 100644
--- a/references/workspace/custom-roles.mdx
+++ b/references/workspace/custom-roles.mdx
@@ -89,6 +89,23 @@ This approach gives you precise control over what users can do in each project w
 
 ![create-new-role.png](/images/references/workspace/create-new-role.png)
 
+### Scope dependencies
+
+Many scopes depend on other scopes to work correctly — for example, most project scopes require `view:Project`. When building or editing a role, the role builder shows each scope's dependency status:
+
+- **Green check mark** — all dependencies are met.
+- **Orange triangle** — some dependencies are met. The scope will still function, but certain aspects of the permission will not work.
+- **Red circle** — none of the dependencies are met.
+
+A summary in the bottom-left of the role builder shows how many selected scopes have all, some, or none of their dependencies met.
+
+![scope-dependencies.png](/images/references/workspace/scope-dependencies.png)
+
+A couple of things worth knowing:
+
+- Selecting a scope automatically selects its required dependencies.
+- _Deselecting_ a scope does **not** auto-deselect its dependencies. Many scopes (like `view:Project`) are required by lots of other scopes, so Lightdash leaves them in place to avoid silently breaking other selected scopes.
+
 ### Duplicate an Existing Role
 
 If you want to create a role similar to an existing one:
@@ -96,9 +113,10 @@ If you want to create a role similar to an existing one:
 1. Find the role you want to duplicate (system role or custom role)
 2. Click the **⋯** menu next to the role
 3. Select **Duplicate Role**
-4. Enter a new name for the duplicated role
-5. Modify the scopes as needed
-6. Click **Save**
+4. Select the **role type** — **Organization** or **Project**. This determines whether the duplicated role will be applied at the organization level or the project level, and which scopes are available. Once selected, the role type cannot be changed.
+5. Enter a new name for the duplicated role
+6. Modify the scopes as needed
+7. Click **Save**
 
 This is particularly useful when you want to create a role similar to a system role but with some modifications.