docker · akristen · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026
@@ -22,7 +22,7 @@ By default, only organization
 [owners](/manuals/enterprise/security/roles-and-permissions/core-roles.md) can
 view and manage AI Governance policies. To let someone other than an owner
 manage policies, create a
-[custom role](/manuals/enterprise/security/roles-and-permissions/custom-roles.md)
+[custom role](/manuals/enterprise/security/roles-and-permissions/custom-roles/_index.md)
 with the **Governance** permissions and assign it to a user or team.
 
 > [!NOTE]

@@ -56,12 +56,12 @@ To get started with Docker Build Cloud,
 to get access to Docker Build Cloud:
 
 - Users with a free Personal account can opt-in to a 7-day free trial, with the option
-to subscribe for access. To start your free trial, sign in to [Docker Build Cloud Dashboard](https://app.docker.com/build/) and follow the on-screen instructions.
+  to subscribe for access. To start your free trial, sign in to [Docker Build Cloud Dashboard](https://app.docker.com/build/) and follow the on-screen instructions.
 - All users with a paid Docker subscription have access to Docker Build Cloud included
-with their Docker suite of products. See [Docker subscriptions and features](https://www.docker.com/pricing?ref=Docs&refAction=DocsBuildCloud) for more information.
+  with their Docker suite of products. See [Docker subscriptions and features](https://www.docker.com/pricing?ref=Docs&refAction=DocsBuildCloud) for more information.
 
 Once you've signed up and created a builder, continue by
 [setting up the builder in your local environment](./setup.md).
 
 For information about roles and permissions related to Docker Build Cloud, see
-[Roles and Permissions](/manuals/enterprise/security/roles-and-permissions.md#docker-build-cloud-permissions).
+[Roles and Permissions](/manuals/enterprise/security/roles-and-permissions/core-roles.md#docker-build-cloud).
diff --git a/content/manuals/enterprise/security/roles-and-permissions/_index.md b/content/manuals/enterprise/security/roles-and-permissions/_index.md
@@ -1,75 +1,60 @@
 ---
-title: Roles and permissions
+title: Roles and permissions overview
 linkTitle: Roles and permissions
-description: Control access to content, registry, and organization management with Docker's role system
-keywords: roles, permissions, custom roles, core roles, access control, organization management, docker hub, docker home , security
+description: Choose between core and custom roles to control access to repositories, teams, and organization settings
+keywords: roles, permissions, core roles, custom roles, member, editor, owner, access control, organization, docker hub, docker home, security
 tags: [admin]
 aliases:
   - /admin/organization/roles/
   - /security/for-admins/roles-and-permissions/
   - /docker-hub/roles-and-permissions/
 grid:
-  - title: "Core roles"
-    description: Learn about Docker's built-in Member, Editor, and Owner roles with predefined permissions.
+  - title: Core roles
+    description: Compare the permissions granted by the built-in Member, Editor, and Owner roles.
     icon: shield-check
     link: /enterprise/security/roles-and-permissions/core-roles/
-  - title: "Custom roles"
-    description: Create tailored permission sets that match your organization's specific needs.
+  - title: Custom roles
+    description: Build permission sets that match your organization's access control needs.
     icon: adjustments-horizontal
     link: /enterprise/security/roles-and-permissions/custom-roles/
+  - title: Custom roles permissions
+    description: Reference documentation for every permission you can assign to a custom role.
+    icon: list-bullet
+    link: /enterprise/security/roles-and-permissions/custom-roles/permissions-reference/
 weight: 40
 ---
 
 {{< summary-bar feature_name="General admin" >}}
 
-Roles control what users can do in your Docker organization. When you invite users or create teams, you assign them roles that determine their permissions for repositories, teams, and organization settings.
+Roles determine what members can do in your Docker organization. When you
+invite a user or create a team, you assign a role that grants permissions
+for repositories, teams, and organization settings.
 
-Docker provides two types of roles to meet different organizational needs:
+Docker provides two role types. Users and teams get either a core role or a
+custom role, but not both.
 
-- [Core roles](/manuals/enterprise/security/roles-and-permissions/core-roles.md) with predefined permissions
-- [Custom roles](/manuals/enterprise/security/roles-and-permissions/custom-roles.md) that you can tailor to your specific requirements
+## Core roles
 
-## Docker roles
+Core roles are Docker's built-in Member, Editor, and Owner roles. Their
+permissions are predefined and can't be changed. Use core roles when
+Docker's permission sets match how your organization works and you want
+straightforward role assignments.
 
-### Core roles
+## Custom roles
 
-Core roles are Docker's built-in roles with predefined permission sets:
+Custom roles are permission sets you build by selecting individual
+permissions, such as billing or team management. Use custom roles when you
+need a combination that core roles don't offer, for example a billing
+administrator or a security auditor, or when you want to grant
+least-privilege access. Custom roles require a Docker Business subscription.
 
-- **Member**: Non-administrative role with basic access. Members can view other organization members and pull images from repositories they have access to.
-- **Editor**: Partial administrative access. Editors can create, edit, and delete repositories, and manage team permissions for repositories.
-- **Owner**: Full administrative access. Owners can manage all organization settings, including repositories, teams, members, billing, and security features.
+## Roles and team permissions
 
-### Custom roles
-
-Custom roles allow you to create tailored permission sets by selecting specific permissions from categories like user management, team management, billing, and Hub permissions. Use custom roles when Docker's core roles don't fit your needs.
-
-## When to use each role
-
-Use core roles when:
-
-- Docker's predefined permission sets match your organizational structure
-- You want simple, straightforward role assignments
-- You're getting started with Docker organization management
-- Your access control needs are standard and don't require fine-grained permissions
-
-Use custom roles when:
-
-- You need specific permission combinations not available in core roles
-- You want to create specialized roles like billing administrators, security auditors, or repository managers
-- You need department-specific access control
-- You want to implement the principle of least privilege with precise permission grants
-
-## How roles work together
-
-You can assign users and teams either a core role or a custom role, but not both. However, roles work in combination with team permissions:
-
-1. **Role permissions**: Applied organization-wide (core or custom role). Custom roles can grant permissions to both organization-wide settings and repository access.
-2. **Team permissions**: Additional repository-specific permissions when users are added to teams. This is a separate permission system from role-based permissions.
-
-This layered approach gives you flexibility to provide broad organizational access through roles and specific repository access through team memberships.
+Roles apply organization-wide, and team permissions apply to specific
+repositories. The two systems work together: a user's role sets their
+organization-wide access, and team membership can extend their access to
+individual repositories.
 
 ## Next steps
 
-Choose the role type that best fits your organization's needs:
-
 {{< grid >}}
diff --git a/content/manuals/enterprise/security/roles-and-permissions/core-roles.md b/content/manuals/enterprise/security/roles-and-permissions/core-roles.md
@@ -1,38 +1,41 @@
 ---
 title: Core roles and permissions
 linkTitle: Core roles
-description: Compare Member, Editor, and Owner permissions for content, registry, and organization management.
-keywords: core roles, member, editor, owner, permissions, organization, company, docker hub, docker home, security, oidc connections, teams
-aliases:
-  - /enterprise/security/roles-and-permissions/
+description: Compare Member, Editor, and Owner permissions for content, registry, organization, Scout, and Build Cloud
+keywords: core roles, member, editor, owner, permissions, organization, company, docker hub, docker scout, docker build cloud, oidc, teams, security
+weight: 10
 ---
 
 {{< summary-bar feature_name="General admin" >}}
 
-Core roles are Docker's built-in roles with predefined permission sets.
-This page summarizes permissions for each core role.
+Core roles are Docker's built-in roles with predefined permission sets. This page defines the core roles and compares what each core role can do across Docker products. If you need a
+different combination of permissions, use
+[custom roles](/manuals/enterprise/security/roles-and-permissions/custom-roles/_index.md)
+instead.
 
-## What are core roles?
+## Core roles 
 
 Docker organizations have three core roles:
 
-- **Member**: Non-administrative role with basic access. Members can
-  view other organization members and pull images from repositories
-  they have access to.
-- **Editor**: Partial administrative access. Editors can create, edit,
-  and delete repositories. They can also manage team permissions for
+- Owner provides full administrative access. Owners can manage all organization
+  settings, including repositories, teams, members, billing, and security
+  features.
+- Editor extends partial administrative access. Editors can create, edit, and
+  delete repositories. They can also manage team permissions for
   repositories.
-- **Owner**: Full administrative access. Owners can manage all
-  organization settings, including repositories, teams, members,
-  billing, and security features.
+- Member is a non-administrative role with basic access. Members can view
+  other organization members and pull images from repositories they have
+  access to.
 
 A company owner has the same organization management permissions as an
-organization owner, but there are some content and registry permissions
-that company owners don't have (for example, repository pull/push). For
-more information, see
+organization owner, but some content and registry permissions don't apply
+to company owners (for example, repository pull and push). For more
+information, see
 [Company overview](/manuals/admin/company/_index.md).
 
-### Content and registry permissions
+## Permissions reference
+
+### Content and registry
 
 These permissions apply organization-wide.
 
@@ -57,18 +60,17 @@ These permissions apply organization-wide.
 | Assign team permissions to repositories               | ❌     | ✅     | ✅    |
 | Manage OIDC connections                               | ❌     | ✅     | ✅    |
 
-You can grant repository permissions to members beyond their
-organization role:
+You can grant repository permissions beyond a member's organization role:
 
 - Role permissions: Applied organization-wide (member or editor)
 - Team permissions: Additional permissions for specific repositories
 
 To extend access to private repositories, configure team permissions.
-Custom roles can grant organization-wide permissions to manage
-repositories (create, edit, delete) but do not grant pull access to
-private repositories — use team permissions for that.
+Custom roles can grant organization-wide permissions to manage repositories
+(create, edit, delete) but don't grant pull access to private repositories.
+Use team permissions for that.
 
-### Organization management permissions
+### Organization management
 
 | Permission                                                        | Member | Editor | Owner |
 | :---------------------------------------------------------------- | :----- | :----- | :---- |
@@ -95,13 +97,13 @@ private repositories — use team permissions for that.
 
 > [!TIP]
 >
-> If you want more granular access control, you can
+> For more granular access control,
 > [upgrade to a Docker Business plan](https://www.docker.com/pricing?ref=Docs&refAction=DocsEnterpriseCoreRoles)
-> for custom roles and advanced permissions.
+> to use [custom roles](/manuals/enterprise/security/roles-and-permissions/custom-roles/_index.md).
 
 _\* If not part of a company_
 
-### Docker Scout permissions
+### Docker Scout
 
 | Permission                                            | Member | Editor | Owner |
 | :---------------------------------------------------- | :----- | :----- | :---- |
@@ -111,7 +113,7 @@ _\* If not part of a company_
 | Create environments                                   | ❌     | ❌     | ✅    |
 | Manage registry integrations                          | ❌     | ❌     | ✅    |
 
-### Docker Build Cloud permissions
+### Docker Build Cloud
 
 | Permission                 | Member | Editor | Owner |
 | -------------------------- | :----- | :----- | :---- |
@@ -120,3 +122,12 @@ _\* If not part of a company_
 | Configure builder settings | ✅     | ✅     | ✅    |
 | Buy minutes                | ❌     | ❌     | ✅    |
 | Manage subscription        | ❌     | ❌     | ✅    |
+
+## Next steps
+
+- [Custom roles](/manuals/enterprise/security/roles-and-permissions/custom-roles/_index.md):
+  Create tailored permission sets on a Docker Business plan
+- [Manage organization members](/manuals/admin/organization/manage/members.md):
+  Invite users and assign roles
+- [Company overview](/manuals/admin/company/_index.md): Understand company
+  owner permissions versus organization owner permissions