docs: document expanded roles and the role permissions table

dashboard/roles.mdx

@@ -49,6 +49,67 @@ Mintlify provides three dashboard access levels: viewer, editor, and admin. With
   Limit admin access to only the people who need to perform admin tasks.
 </Tip>
 
+On Enterprise plans, you can also see what each role can do in the **Role permissions** section of the [Members](https://app.mintlify.com/settings/organization/members) page of your dashboard.
+
+## Expanded roles
+
+If the role picker on your **Members** page offers **Publisher** and **Commenter**, your organization uses six roles instead of three: owner, admin, publisher, editor, commenter, and viewer. The **Role permissions** section shows a column for each.
+
+When your organization switches to expanded roles, existing editors become publishers so they can still publish. Members whose role comes from your identity provider keep their assigned role. Each organization has one owner.
+
+- **Owner**: Everything an admin can do, plus deleting the project, deleting the organization, and transferring ownership.
+- **Admin**: Full control over content, members, roles, and settings, including billing and the custom domain.
+- **Publisher**: Everything an editor can do, plus publishing to the live site and approving reviews.
+- **Editor**: Create and edit content, request reviews, and manage site and workspace settings, integrations, API keys, and the assistant. Can't publish to the live site or approve reviews.
+- **Commenter**: View and comment on content. Can't edit content.
+- **Viewer**: View content and preview unpublished edits.
+
+|                              | Viewer | Commenter | Editor | Publisher | Admin | Owner |
+| ---------------------------- | :----: | :-------: | :----: | :-------: | :---: | :---: |
+| View pages                   |   ✅   |    ✅     |   ✅   |    ✅     |  ✅   |  ✅   |
+| Preview unpublished edits    |   ✅   |    ✅     |   ✅   |    ✅     |  ✅   |  ✅   |
+| Comment on pages             |   ❌   |    ✅     |   ✅   |    ✅     |  ✅   |  ✅   |
+| Create and edit pages        |   ❌   |    ❌     |   ✅   |    ✅     |  ✅   |  ✅   |
+| Reorganize pages             |   ❌   |    ❌     |   ✅   |    ✅     |  ✅   |  ✅   |
+| Delete pages                 |   ❌   |    ❌     |   ✅   |    ✅     |  ✅   |  ✅   |
+| Request review               |   ❌   |    ❌     |   ✅   |    ✅     |  ✅   |  ✅   |
+| Review changes               |   ❌   |    ❌     |   ❌   |    ✅     |  ✅   |  ✅   |
+| Publish to the live site     |   ❌   |    ❌     |   ❌   |    ✅     |  ✅   |  ✅   |
+| Manage site and workspace settings |   ❌   |    ❌     |   ✅   |    ✅     |  ✅   |  ✅   |
+| Invite and remove members    |   ❌   |    ❌     |   ❌   |    ❌     |  ✅   |  ✅   |
+| Assign roles                 |   ❌   |    ❌     |   ❌   |    ❌     |  ✅   |  ✅   |
+| Manage page access           |   ❌   |    ❌     |   ❌   |    ❌     |  ✅   |  ✅   |
+| Manage custom roles          |   ❌   |    ❌     |   ❌   |    ❌     |  ✅   |  ✅   |
+| Manage custom domain         |   ❌   |    ❌     |   ❌   |    ❌     |  ✅   |  ✅   |
+| Manage billing and plan      |   ❌   |    ❌     |   ❌   |    ❌     |  ✅   |  ✅   |
+| Delete the project           |   ❌   |    ❌     |   ❌   |    ❌     |  ❌   |  ✅   |
+| Delete the organization      |   ❌   |    ❌     |   ❌   |    ❌     |  ❌   |  ✅   |
+| Transfer ownership           |   ❌   |    ❌     |   ❌   |    ❌     |  ❌   |  ✅   |
+
+You can only invite members or assign roles up to your own role.
+
+## Custom roles
+
+In organizations that use [expanded roles](#expanded-roles), admins and owners can create custom roles with exactly the permissions a team needs. Custom roles appear in the **Custom roles** section of the [Members](https://app.mintlify.com/settings/organization/members) page.
+
+### Create a custom role
+
+1. Navigate to the [Members](https://app.mintlify.com/settings/organization/members) page of your dashboard.
+2. In the **Custom roles** section, click **New custom role**. You can also select **Create custom role** from a member's or an invite's **Role** dropdown.
+3. Enter a **Label**, which appears in role menus, and an optional **Description** to help admins pick the right role.
+4. In the permissions table, choose a level for each area. Content areas, such as pages, comments, and publishing, use **Read** and **Write**. Project and organization areas use **View** and **Manage**.
+5. Click **Create role**.
+
+You can only grant permissions that you have yourself. Each custom role needs a unique name.
+
+### Change or delete a custom role
+
+1. In the **Custom roles** section, open the role's actions menu.
+2. To change the role, select **Manage role**, edit its label, description, or permissions, and click **Save**.
+3. To delete the role, select **Delete role**, then click **Delete permanently**.
+
+Deleting a custom role cannot be undone. You can't delete a role that is still assigned to members or SSO groups. Reassign them first.
+
 ## Repository contributors and deployments
 
 Anyone with write access to your documentation repository can contribute by pushing changes. Pushes to your deploy branch deploy automatically, whatever the person's dashboard role. Dashboard roles only control what people can do in the Mintlify dashboard.
@@ -77,6 +138,19 @@ Admins can change the role assigned to any member.
 
 The new role takes effect the next time the member loads the dashboard. You can't change your own role. If a member's role comes from [SCIM directory sync](/dashboard/scim#roles-for-provisioned-members), their row shows **Managed by SSO**, and you change their role in your identity provider.
 
+If your organization uses [expanded roles](#expanded-roles), the owner's row shows **Owner**. The owner's role changes only when the owner transfers ownership to another member.
+
+### Transfer ownership
+
+If your organization uses [expanded roles](#expanded-roles), the owner can make another member the owner. You become an admin, and only the new owner can transfer ownership back.
+
+1. Navigate to the [Members](https://app.mintlify.com/settings/organization/members) page of your dashboard.
+2. In the member's row, select **Owner** from the **Role** dropdown.
+3. In the **Transfer ownership?** dialog, type `TRANSFER` to confirm.
+4. Click **Transfer ownership**.
+
+You can only transfer ownership to an active member. You can't transfer it to a pending invite or to a member whose role comes from your identity provider.
+
 ## Remove a member
 
 Admins can remove a member from the organization entirely, which deletes their access and any keys they created.
@@ -85,6 +159,8 @@ Admins can remove a member from the organization entirely, which deletes their a
 2. In the member's row, open the actions menu and select **Remove member**.
 3. Click **Remove** to confirm.
 
+You can't remove the owner of an organization that uses [expanded roles](#expanded-roles). To remove them, [transfer ownership](#transfer-ownership) to another member first.
+
 Removing a member deletes the member from your organization. Revoking a member's credentials signs them out and clears their keys, but keeps their membership.
 
 ## Revoke a member's credentials
@@ -107,4 +183,4 @@ You can revoke any combination of the following credentials:
 | M2M clients | Revokes the member's machine-to-machine client credentials. |
 | Connected apps | Disconnects the apps the member authorized through OAuth. |
 
-Revoking credentials cannot be undone. The member can sign in again and create new keys and tokens unless you also remove them from the organization or block their sign-in method. You cannot revoke your own credentials.
+Revoking credentials cannot be undone. The member can sign in again and create new keys and tokens unless you also remove them from the organization or block their sign-in method. You cannot revoke your own credentials or the owner's credentials.

editor/collaborate.mdx

@@ -10,7 +10,7 @@
 ## Comments
 
 <Info>
-  All [roles](/dashboard/roles) can comment, reply, and resolve threads.
+  All [roles](/dashboard/roles) can comment, reply, and resolve threads. If your organization uses [expanded roles](/dashboard/roles#expanded-roles), commenters and higher roles can comment, but viewers can't.
 </Info>
 
 Comments let you leave feedback on specific text or on a whole page without editing the content.
@@ -19,7 +19,7 @@
 
 To add a comment, highlight text and click the <Icon icon="message-square-text" /> **Comment** icon in the toolbar or press <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>M</kbd> (macOS) or <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>M</kbd> (Windows).
 
 To comment on a whole block, such as a paragraph, code block, image, table, or component, hover over the block, click <Icon icon="grip-vertical" /> **Block actions**, and select **Comment**. You can also place your cursor in the block without selecting any text and press <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>M</kbd> (macOS) or <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>M</kbd> (Windows). If someone deletes a block that has an unresolved comment, the thread moves beside the page title with a note that the commented block was removed.
 
 To comment on the whole page instead of specific text, use either of these options:
 
@@ -30,7 +30,7 @@
 
 Type `@` to mention a teammate in a comment. They must be a member of your organization who has accepted their invitation. When you mention a teammate in a comment, they receive an email notification and an item in their [inbox](/dashboard/inbox). Manage which comment and suggestion emails you receive from the [Notifications](/dashboard/notifications) page of your dashboard.
 
 Replies to threads you started or were mentioned in, and new comments and suggestions on pages you own, also appear in your inbox.
 
 Comment threads appear in both visual and source mode. In source mode, you can read, reply to, and resolve existing threads, but starting a new comment requires visual mode.
 
@@ -91,7 +91,7 @@
 
 The agent edits the page on the thread's branch only when your comment explicitly asks for a change. For questions, feedback, or suggestions, it answers and offers to make the change instead. When it edits the page, its reply says what it changed. The agent doesn't publish, so review its changes and [publish](/editor/publish) them yourself.
 
 For [viewers](/dashboard/roles), the agent replies read-only. It can read pages and their open comments, view images, search and fetch web content, and search Mintlify's documentation, but it can't edit content.
 
 Mentions work on private pages for members who already have access.
 

mint-instructions/access/team.mdx

@@ -8,7 +8,7 @@
 
 If you meant who can read the published docs site (login, password, groups), run `mint instructions access` instead.
 
 Use this to add teammates, set roles, SSO, SCIM, session or IP policies, audit logs, contacts, notifications, or the desktop app. All of it is configured in the dashboard (https://app.mintlify.com). You cannot set any of it from the repo, `docs.json`, or the `mint` CLI. Give the user exact steps and links.
 
 ## Workflow
 
@@ -18,14 +18,15 @@
    - Viewer: view editor content, dashboard and analytics, ask the Slack agent questions, comment. Always in suggesting mode in the editor; cannot accept suggestions.
    - Editor: everything a viewer can, plus edit in the web editor, publish, create/rename/delete pages, reorder navigation, upload media, trigger, roll back and promote deployments, create/delete API keys, configure integrations, assistant and add-ons, make changes with the Slack agent, accept or reject suggestions, invite editors and viewers.
    - Admin: everything, plus update roles, invite admins, delete users, billing, SSO, SCIM, IP allowlist and session lifetimes, audit logs, security contact, custom domain, Git source, custom subpath, delete a project, agent publishing setting, delete organization, delete any comment.
-   - Change a role: **Members** page, **Role** dropdown (saves immediately, applies on next dashboard load). You cannot change your own role. **Managed by SSO** rows change in the IdP.
-4. Offboard: **Members** page, actions menu. **Remove member** deletes membership, access and their keys. **Revoke credentials** keeps membership and revokes any of: Sessions, CLI tokens, API keys, Discovery API keys, M2M clients, Connected apps. Not reversible; you cannot revoke your own.
+   - Expanded roles: if the **Members** role picker offers **Publisher** and **Commenter**, the org has six roles: viewer, commenter, editor, publisher, admin, owner. On the switch, existing editors became publishers (IdP-managed roles unchanged), and each org has one owner. Viewer: view and preview only, cannot comment. Commenter: view and comment, cannot edit. Editor: create, edit, reorganize, and delete pages, comment, request review, and manage site and workspace settings, integrations, API keys and the assistant. Cannot publish or approve reviews. Publisher: editor plus publish and approve reviews. Admin: plus members, roles, page access, custom domain, billing. Owner: admin plus delete the project and the organization, and transfer ownership. Members can only invite or assign roles up to their own. **Role permissions** on the **Members** page (Enterprise) shows each role's permissions. Custom roles (expanded roles, admins and owners): **Members** page, **Custom roles**, **New custom role** (or **Create custom role** in a **Role** dropdown), set **Label**, optional **Description**, and per-area levels (content: Read/Write; project and organization: View/Manage), **Create role**. You can only grant permissions you have. **Manage role** edits; **Delete role** then **Delete permanently** (fails while assigned to members or SSO groups).
+   - Change a role: **Members** page, **Role** dropdown (saves immediately, applies on next dashboard load). You cannot change your own role. The owner's role changes only by transfer: the owner selects **Owner** in another active, non-SSO-managed member's **Role** dropdown, types `TRANSFER`, clicks **Transfer ownership**; they become admin. **Managed by SSO** rows change in the IdP.
+4. Offboard: **Members** page, actions menu. **Remove member** deletes membership, access and their keys. **Revoke credentials** keeps membership and revokes any of: Sessions, CLI tokens, API keys, Discovery API keys, M2M clients, Connected apps. Not reversible; you cannot revoke your own. With expanded roles, you cannot remove the owner (transfer ownership first) or revoke their credentials.
 5. SSO (Enterprise, admin): **Security** page (https://app.mintlify.com/settings/organization/access), **SSO** section. Each button opens the Admin Portal, which has the identity provider steps.
    - First **Verify email domains**: add your team's email domain and its DNS record in the Admin Portal. **Set up SSO** stays disabled until a domain shows **Verified**.
    - Then **Set up SSO** and follow the Admin Portal steps. When connected, the section shows **SAML SSO** with a **Connected** badge. **Manage SSO** reopens the portal.
    - After you connect SSO, Mintlify sends anyone signing in with a verified-domain email to the IdP. Test sign-in from the login page and from the IdP in a private window.
    - First SSO sign-in adds the user to the organization with the role the IdP assigns, or editor if none.
    - Existing SSO or SCIM set up before the Admin Portal: reconnect by November 20, 2026 from the dashboard banner's **Set up now** (admins only). See https://www.mintlify.com/docs/help-center/reconnect-existing-sso-and-scim.
 6. SCIM (Enterprise, admin): **Security** page, **SCIM** section, **Set up directory sync**, follow the Admin Portal steps. **Manage directory** reopens the portal. Roles follow the IdP's role assignments; provisioned members show **Managed by SSO** on **Members**, so change their roles in the IdP.
 7. Session and network policies (Enterprise, admin): **Security** page, **Policies** section.
    - **Idle session timeout** and **Maximum session lifetime**: each 5 minutes to 14 days, own toggle, click **Save**. Session ends at whichever limit hits first. Off: idle timeout falls back to 14 days, max lifetime has no limit. Lowering max lifetime ends older sessions on their next request.
@@ -41,7 +42,7 @@
 
 - Never claim you configured members, roles, SSO, SCIM or policies. Hand the user the steps; an admin must do the admin-only ones.
 - Dashboard roles do not gate Git. Anyone with write access to the repo can push, and pushes to the deploy branch deploy regardless of role. Lock down the repo separately.
 - Before an IP allowlist, confirm the admin's current IP (shown in **Policies**) is on it, or they lock themselves out.
 
 ## Examples
 
@@ -59,6 +60,6 @@
 
 - `mint instructions access` (docs-site reader access)
 - https://www.mintlify.com/docs/dashboard/roles
 - https://www.mintlify.com/docs/dashboard/sso
 - https://www.mintlify.com/docs/dashboard/scim
 - https://www.mintlify.com/docs/dashboard/network-access