diff --git a/content/en/docs/private-platform/pmp-role-management.md b/content/en/docs/private-platform/pmp-role-management.md
deleted file mode 100644
index 99c53817aae..00000000000
--- a/content/en/docs/private-platform/pmp-role-management.md
+++ /dev/null
@@ -1,141 +0,0 @@
----
-title: "Dynamic Role Management in Private Mendix Platform"
-linktitle: "Dynamic Role Management"
-url: /private-mendix-platform/dynamic-role-management/
-description: "Documents the dynamic role management functionality of the Private Mendix Platform."
-weight: 55
----
-
-## Introduction
-
-Starting from version 2.0, Private Mendix Platform offers dynamic role management to strengthen governance, improve flexibility, and streamline access control. This feature ensures that organizations can manage roles and permissions dynamically, aligning with evolving business and compliance requirements.
-
-To access the **Role Management** page, go to the **Admin > Manage** section of the Mendix Private Platform. This page centralizes all role-related governance and permissions.
-
-{{< figure src="/attachments/private-platform/pmp-roles1.png" class="no-border" >}}
-
-Private Mendix Platform 2.0 ships with a set of predefined roles to cover common responsibilities:
-
-* **Developer** - Full access to application development features
-* **Contributor** - Limited access, typically for business users or domain experts contributing to projects
-* **Operator** - Focused on operational tasks such as deployments, monitoring, and cluster management
-* **Administrator** - Highest level of access, with full governance and configuration rights
-
-Admins can create new custom roles tailored to organizational needs.
-
-## Role Editing
-
-Admins can edit any default or custom role to adjust the following permissions dynamically:
-
-* Project permissions
-* Cluster permissions
-* CI/CD permissions
-
-## Group Management
-
-To access the **Group Management** page, go to the **Admin > Manage** section of the Mendix Private Platform. It provides a hierarchical structure for managing user roles and resource access across applications, clusters, and namespaces.
-
-{{< figure src="/attachments/private-platform/pmp-roles2.png" class="no-border" >}}
-
-Groups are organized in a hierarchical tree. The root group is created by Private Mendix Platform automatically and serves as the foundation for all user-created groups.
-
-Admins can customize root group information to align with organizational needs. The hierarchy depth is theoretically unlimited, supporting complex organizational structures.
-
-Every new group must be assigned a parent group. This ensures proper inheritance of governance and permissions.
-
-{{< figure src="/attachments/private-platform/pmp-roles3.png" class="no-border" >}}
-
-### Group Ownership and Resources
-
-Each group can own or associate resources, and permissions are applied to its members through assigned roles.
-
-The following resources are currently supported:
-
-* Apps - Application-level access control.
-* Namespace purposes - Permissions tied to namespaces for deployment or operational segregation.
-
-The following ownership and association rules apply:
-
-* Apps - An app can only be owned by one group. Ownership is exclusive to ensure clear accountability.
-* Namespaces - A namespace can be associated with multiple groups non-exclusively, allowing flexible sharing of operational responsibilities across teams.
-
-### Role Assignment Model
-
-Roles are assigned to group members, not to the group itself. If a group has a subgroup, then members of the main group are automatically inherited into the subgroup with the same roles they hold in the main group. This ensures consistency of permissions across hierarchical structures and reduces duplication of role assignments.
-
-{{< figure src="/attachments/private-platform/pmp-roles5.png" class="no-border" >}}
-
-### Group Creation
-
-When creating a new group, admins must provide the following information:
-
-* **Description** - A clear explanation of the group's purpose.
-* **Group Admins** - One or more administrators responsible for managing the group.
-* **Parent Group** - Defines the group's place in the hierarchy.
-
-### Statistics Dashboard
-
-The Group Management page also provides real-time statistics to help administrators monitor governance:
-
-* **Number of Groups** - Total number of groups created under the hierarchy.
-* **Number of Resources Owned** - Count of Apps and namespace purposes associated with groups.
-* **Namespaces Assigned to Groups** - Total namespaces linked to groups for operational control.
-* **Average Number of Members per Group** - Helps track group size and distribution of users.
-
-{{< figure src="/attachments/private-platform/pmp-roles6.png" class="no-border" >}}
-
-## Permission Synchronization
-
-Permission synchronization ensures that role changes in groups are automatically applied to the resources owned or associated with those groups. This mechanism guarantees consistency between governance configurations and actual user access.
-
-### Role Change Propagation
-
-When a member's role changes in a specific group through admin mode, the update is immediately synchronized across all resources owned by or associated with that group (for example, apps, or namespaces). This synchronization eliminates manual updates and ensures governance policies are enforced consistently.
-
-### Combined Permission Calculation
-
-When multiple roles apply to a member, Private Mendix Platform calculates a combined permission set based on all assigned and inherited roles.
-
-This ensures that the member's effective permissions cover all capabilities granted by any of the roles.
-
-## Roles for Users
-
-When a user logs in, they can create a new app in Private Mendix Platform.
-
-The **Teams** page provides visibility into all members associated with the app, along with their roles.
-
-### Teams Page Overview
-
-The Teams page displays two categories of members:
-
-* Direct members
-* Owner
-
-The user who created the app automatically becomes the owner. Owners have full control over the app, including inviting new members and assigning roles.
-
-#### Invited Members
-
-Owners can invite additional users into the App. These members are assigned specific roles such as:
-
-* Operator
-* Contributor
-* Developer
-
-#### Inherited Members
-
-Inherited memberships are derived from group memberships defined in the **Group Management** page.
-
-The folowing inheritance paths are available:
-
-* Owner's group - Members of the group to which the owner belongs are automatically inherited into the app.
-* Parent group - Members of the parent group in the hierarchy are also inherited.
-
-Roles for inherited members are determined by the **Group Management** page and applied automatically.
-
-{{< figure src="/attachments/private-platform/pmp-roles7.png" class="no-border" >}}
-
-### Role Assignment for Users
-
-Direct members receive roles explicitly assigned by the app owner. Inherited members retain the roles defined in their group context.
-
-This approach ensures consistency. Direct roles can be managed with app-specific assignments, while inherited roles can have governance-driven assignments from group hierarchy.
diff --git a/content/en/docs/private-platform/reference/admin/pmp-ref-admin-manage.md b/content/en/docs/private-platform/reference/admin/pmp-ref-admin-manage.md
index 6dc06702274..00343a8348a 100644
--- a/content/en/docs/private-platform/reference/admin/pmp-ref-admin-manage.md
+++ b/content/en/docs/private-platform/reference/admin/pmp-ref-admin-manage.md
@@ -295,7 +295,7 @@ As the administrator, you can perform the following actions:
 
 #### User Management
 
-In the **User Management** tab, you can create and edit accounts for your local users and API users (that is, accounts that are used by an API service to access your Private Mendix Platform). By clicking **More Actions** ({{% icon name="three-dots-menu-horizontal" %}}) by an account, you can quickly perform a number of actions:
+In the **User Management** tab, you can create and edit accounts for your users. By clicking **More Actions** ({{% icon name="three-dots-menu-horizontal" %}}) by an account, you can quickly perform a number of actions:
 
     * Edit a user's name and email
     * Assign or remove user roles (local users only)
diff --git a/content/en/docs/private-platform/roles/_index.md b/content/en/docs/private-platform/roles/_index.md
new file mode 100644
index 00000000000..2a97c328911
--- /dev/null
+++ b/content/en/docs/private-platform/roles/_index.md
@@ -0,0 +1,43 @@
+---
+title: "Access Management in Private Mendix Platform"
+url: /private-mendix-platform/access-management/
+aliases:
+    - /private-mendix-platform/dynamic-role-management/
+weight: 55
+description: "Documents how Private Mendix Platform controls what users can do on the platform and to individual apps, namespaces, and Marketplace content."
+---
+
+## Introduction
+
+Private Mendix Platform controls access along the following independent: 
+
+* What a user can do on the platform as a whole
+* what a user can do to a specific app, deployment namespace, or Marketplace item. 
+
+Both axes are configured by administrators at runtime through Dynamic Role Management, without a code change and without redeploying the platform.
+
+This document explains the two axes. Other articles in this section describe the model, the administrative tasks that configure it, and the day-to-day tasks that users, group administrators, and app owners perform within it.
+
+## Understanding the Two Role Systems {#role-systems}
+
+Instead of a single ladder of roles, with an administrator at the top who can do everything, Private Mendix Platform has two role systems, that is, [platform roles](#platform-role) and [resource roles](#resource-role). Each role system has its own permission schema, its own assignment mechanism, and its own scope.
+
+The two systems are independent of each other. That is, a platform role does not grant the user any resource roles, and a resource role does not grant the user any platform roles. The resource role named **Administrator** and the platform role named **CompanyAdmin** are unrelated. They share no permissions, and the resource role only has access to the resources owned by its holder's group.
+
+The following sections contain more information about platform and resource roles. For the full model, see [Access Model and Role Reference for Private Mendix Platform](/private-mendix-platform/access-model/).
+
+### Platform Roles {#platform-role}
+
+Platform roles define what a user can do on the platform in general. They are assigned to a user account at creation, and can be edited afterward. Their scope involves the whole plaform. Having multiple platform roles gives a user all the access rights of every role they hold.
+
+### Resource Roles {#resource-role}
+
+Resource roles define what a user can do with specific resources, such as a specific app or namespace. They are assigned to an individual, as a member of a group, or directly on an app team. Their scope involves only the resources the relevant group owns or is associated with. Multiple resource roles are only combined where two roles apply to the same resource.
+
+## Read More
+
+* [Access Model and Role Reference for Private Mendix Platform](/private-mendix-platform/access-model/) - Before configuring the access rights, review this document to understand how the model works, including how groups inherit membership, which resources a group can own, and how permissions combine. It also lists every default role and what it grants.
+* [Administering Users, Groups, and Roles in Private Mendix Platform](/private-mendix-platform/access-administration/) - Refer to this document for information about creating user accounts, defining or editing roles, building your group hierarchy, and associating apps and namespaces with groups. Those tasks require the **CompanyAdmin** Platform Role.
+* [Working with Groups and App Teams in Private Mendix Platform](/private-mendix-platform/groups-and-app-teams/) - Refer to this document for information about managing the membership of a group you administer, or a team on an app you own. Those tasks require no administrator role.
+* [Private Mendix Platform Functionalities - System Administrators](/private-mendix-platform/reference-guide/admin/system/) - Refer to this document for information about identity provider configuration, including connect an identity provider, configuring SCIM provisioning, and adjusting login session preferences.
+* [Federated Users](/private-mendix-platform/access-model/#federated-users) - Refer to this document for information about what happens to a federated user on first login, and where they land in the group hierarchy.
diff --git a/content/en/docs/private-platform/roles/pmp-access-administration.md b/content/en/docs/private-platform/roles/pmp-access-administration.md
new file mode 100644
index 00000000000..aa02c535d42
--- /dev/null
+++ b/content/en/docs/private-platform/roles/pmp-access-administration.md
@@ -0,0 +1,182 @@
+---
+title: "Administering Users, Groups, and Roles in Private Mendix Platform"
+url: /private-mendix-platform/access-administration/
+weight: 20
+description: "Documents the administrator tasks for managing user accounts, defining roles, building the group hierarchy, and associating resources with groups in Private Mendix Platform."
+---
+
+## Introduction
+
+This document describes the tasks that configure access in Private Mendix Platform: 
+
+* Creating and maintaining user accounts
+* Defining what roles exist and what they grant
+* Building the group hierarchy
+* Associating apps and deployment namespaces with the groups that need them.
+
+### Prerequisites
+
+To perform the above tasks, you must have the **CompanyAdmin** platform role. Configuring the identity provider that federated users authenticate against is a separate concern requiring **SystemAdmin**, and is documented in [Private Mendix Platform Functionalities - System Administrators](/private-mendix-platform/reference-guide/admin/system/).
+
+Before making structural changes, read [Access Model and Role Reference for Private Mendix Platform](/private-mendix-platform/access-model/). Two rules in particular have consequences that are not visible from the screens described below: group membership inherits downward without limit, and deployment namespace associations do not inherit at all.
+
+## Accessing the Access Management Pages
+
+To open the **Access Management** page, perform the following steps:
+
+1. Click your profile picture in the top right corner of the screen and select **Switch to Admin Mode**.
+2. In the left navigation menu, open the **Manage** section.
+
+From this section, you can manage user accounts, groups, and roles.
+
+## Managing User Accounts
+
+On the **User Management** page you can create and maintain the accounts that use your platform, whether they belong to people or to services.
+
+What an account can do comes from the platform roles assigned to it, not from any account type, so the same page and the same procedure serve a developer, an administrator, and an integration.
+
+### Creating Accounts
+
+To create an account, click **New** and provide the user's name and email address, then assign the Platform Roles the account requires. An account with no Platform Role cannot use the platform, so at minimum assign **User**.
+
+### More Actions
+
+By clicking **More Actions** by an existing account, you can perform the following tasks:
+
+* Edit the user's name and email address.
+* Assign or remove Platform Roles.
+* Block the user, preventing sign-in without deleting the account or its history.
+* Change the user's password.
+* Configure the user's language and time zone.
+* Log the user out of all current sessions.
+* Delete the account.
+
+The **Actions** tab additionally lets you log out every user currently signed in to the platform.
+
+Some of these actions depend on how the account authenticates rather than on what kind of account it is. Setting a password, for instance, applies to accounts that sign in with platform credentials and not to accounts that authenticate through your identity provider.
+
+{{% alert color="info" %}}
+Assigning a Platform Role gives a user platform-wide capability to perform specific tasks. However, it does not give them access to any app, namespace, or Marketplace item. Access to resources comes from group membership or an app team invitation, as described in the following sections.
+{{% /alert %}}
+
+### Accounts Used by Services
+
+A service that calls the platform API signs in as an ordinary account, and what it can do is determined by that account's platform role. A role such as *API User*, carrying only the permissions one integration needs, is an example of a platform role defined for this purpose.
+
+Give each integration its own account and its own narrowly scoped role rather than reusing an administrator account. Accounts used by services behave the same as all other accounts. That is, they can be blocked, their roles can be changed, and their actions appear in the activity log.
+
+### Sign-in and Lockout Behavior
+
+Session limits, automatic disabling of unused accounts, failed sign-in lockout, and lockout duration are platform-wide settings rather than per-account ones, and are configured by a system administrator. For more information, see [Preferences](/private-mendix-platform/reference-guide/admin/system/#preferences-1).
+
+## Managing Roles
+
+On the **Role Management > Platform Roles** and **Role Management > Resource Roles** pages, you can create roles and configure their permissions. For more information about what each default role grants, see [Understanding the Two Role Systems](/private-mendix-platform/access-management/#role-systems).
+
+In both systems:
+
+* You can change the permissions of a default role.
+* You cannot delete a default role.
+* You can create new roles with any combination of permissions.
+
+{{% alert color="warning" %}}
+Editing a role immediately changes the effective access of everyone who holds it. Before editing, check how many users hold the role and what resources they reach through it. Where a change applies to some users and not others, create a new role instead of editing an existing one.
+{{% /alert %}}
+
+### Editing a Platform Role
+
+Select the role and adjust its permissions. These cover generic platform access such as signing in and creating an app, capabilities in the **Manage** area such as app, user, group, and Marketplace administration, and capabilities in the **Settings** area such as identity configuration, licensing, and webhooks.
+
+Because CompanyAdmin and SystemAdmin are parallel rather than nested, a custom role that needs capabilities from both areas must be given permissions from both.
+
+### Editing a Resource Role
+
+Select the role and adjust its permissions, which are grouped into four categories:
+
+* **Project** - the app lifecycle, its team, version control, and viewing environments.
+* **Build** - packaging, the build pipeline, and the software bill of materials.
+* **Deployment** - deploying to and managing environments.
+* **Monitoring** - logs and metrics.
+
+**Owner** is a special case. It is assigned automatically to whoever creates an app and cannot be granted to anyone manually. To change who holds it, transfer ownership of the app.
+
+### Scoping Deployment Permissions per Environment
+
+Permissions in the **Deployment** category, and only in that category, can be limited to specific environments. For each such permission, select the combination of Development, Test, Acceptance, and Production it should apply to.
+
+Use this rather than maintaining several near-identical roles. A single role in which deployment is permitted for Development and Test and withheld for Production expresses a common compliance requirement in one place, and stays correct as teams change.
+
+### Creating a Custom Role
+
+Click **New** in the relevant tab, name the role, and select its permissions. Choose which system you are creating in deliberately: a role that should let someone administer part of the platform belongs in Platform Roles, and a role that should let someone act on apps and namespaces belongs in Resource Roles.
+
+Name custom roles for the responsibility they represent rather than for the seniority of the people who will hold them, and avoid names that echo the default roles of the other system.
+
+## Managing Groups
+
+On the **Group Management** page you build and maintain the group hierarchy. Groups typically reflect your organization's structure, and they are what deliver Resource Roles to users at scale.
+
+The root group is created by Private Mendix Platform automatically and is the foundation of the hierarchy. You can edit its details to match your organization, and every other group descends from it.
+
+### Creating a Group
+
+To create a group, click **New** and specify the following information:
+
+* **Parent Group** - where the group sits in the hierarchy. Choose this carefully: every member of the parent, and of everything above it, becomes an inherited member of the new group with the role they already hold.
+* **Group Admins** - one or more users who will manage this group's membership. Naming someone here is what allows them to add and remove members, and it requires no administrator role. See [Group Admin](/private-mendix-platform/access-model/#group-admin).
+* **Description** - what the group is for. This is what other administrators will use to decide whether a resource belongs here.
+
+The hierarchy has no depth limit. Add a level when it corresponds to a real boundary of accountability, since each level adds inherited membership to reason about.
+
+### Adding Members and Assigning Their Roles
+
+Roles are assigned to the members of a group, not to the group itself. Add a user to the group and assign the Resource Role they should hold there. Different members of the same group can hold different roles, and usually should.
+
+Members of parent groups appear in the group as inherited members, holding the same role they hold above. You cannot change an inherited member's role from the child group; change it where the membership originates, or add the user directly with a different role.
+
+{{% alert color="info" %}}
+Because membership cascades downward, a role assigned in a group near the root of the hierarchy reaches every group beneath it. Assign broad roles such as Administrator and Maintainer as close as possible to the groups that need them, rather than high in the tree.
+{{% /alert %}}
+
+### Associating Resources with a Group
+
+A group needs resources for its members' roles to act upon.
+
+#### Apps
+
+An app is owned by exactly one group. Assign or move ownership from the App Management page. Apps created through Mendix Studio Pro are owned by the Mendix root group on creation, so transfer ownership after creation if a different group should own them. See [Assigning the App to a New Owner](/private-mendix-platform/reference-guide/admin/company/#ownership).
+
+#### Deployment Namespaces
+
+A namespace can be associated with several groups at once, so operational responsibility can be shared. The namespace's purpose is configured on the namespace itself, in Cluster Manager, rather than on the association. See [Cluster Manager](/private-mendix-platform/reference-guide/admin/company/#cluster-manager).
+
+{{% alert color="warning" %}}
+Unlike membership, namespace associations are not inherited. That is, a namespace association does not extend to a parent group, or to child groups. A group that owns an app and needs to deploy it must be associated with the target namespace itself.
+
+If a team reports that they can build an app but not deploy it, verify that the group owning the app is directly associated with the namespace, not merely descended from a group that is.
+{{% /alert %}}
+
+#### Marketplace Contents
+
+Components published to the private Marketplace are owned by the user who published them rather than by a group, and are shared with groups by their publisher. See [Sharing Content with Groups](/private-mendix-platform/user-guide/#sharing-content-with-groups). Administering Marketplace content is a platform role capability, and is documented in [Marketplace](/private-mendix-platform/reference-guide/admin/company/#marketplace).
+
+### Automating Group Assignment {#automating-group-assignment}
+
+**Automation Settings** on the Group Management page let group membership follow the identity provider information mapped onto users' profiles, rather than being assigned by hand.
+
+Once configured for a profile attribute, membership is derived from that attribute's value when a user arrives:
+
+* If the value corresponds to an existing group, the user is added to that group.
+* If the value does not correspond to any existing group, a group is created for it and the user is made a member.
+
+This keeps group structure aligned with the organizational data your identity provider already holds, at the cost of allowing the hierarchy to grow on its own. Review the groups it creates periodically, give them proper descriptions and group admins, and place them deliberately in the tree.
+
+This is a separate mechanism from the **Parse Roles** setting on your identity provider configuration, which maps role and group claims from the token itself. The two can be used together. For how both fit into first-login behavior, see [Federated Users](/private-mendix-platform/access-model/#federated-users).
+
+### Monitoring the Hierarchy
+
+The Group Management page reports live figures for the number of groups, the number of resources owned, the number of namespaces associated with groups, and the average number of members per group. They are useful as a quick check that the hierarchy still matches expectations, particularly where group creation is automated.
+
+## Auditing Access Changes
+
+Changes to user accounts are recorded in the platform activity log, along with app creation and deletion, package creation, and platform setting changes. Retention and logging level are configurable, and expired entries can be downloaded from the archive for audit purposes. See [Activity Logs](/private-mendix-platform/reference-guide/admin/company/#activity-logs).
diff --git a/content/en/docs/private-platform/roles/pmp-access-model.md b/content/en/docs/private-platform/roles/pmp-access-model.md
new file mode 100644
index 00000000000..21f38db08e0
--- /dev/null
+++ b/content/en/docs/private-platform/roles/pmp-access-model.md
@@ -0,0 +1,331 @@
+---
+title: "Access Model and Role Reference for Private Mendix Platform"
+url: /private-mendix-platform/access-model/
+weight: 10
+description: "Describes the access model of Private Mendix Platform, including platform roles, Resource Roles, group hierarchy and inheritance, resource ownership, and how permissions combine."
+---
+
+## Introduction
+
+Access in Private Mendix Platform is governed by two role systems that operate independently of one another, applied to users who are organized into a hierarchy of groups, which in turn own or are associated with the resources those roles act upon.
+
+This page describes that model. It is the reference to consult before you design a group hierarchy or define a custom role, and the place to look when the access someone has does not match the access you expected them to have. For the procedures that configure the model, see [Administering Users, Groups, and Roles in Private Mendix Platform](/private-mendix-platform/access-administration/).
+
+Administrators configure all of it at runtime, from the **Manage** section of the [Admin menu](/private-mendix-platform/reference-guide/admin/). No part of the model requires a code change to the platform or to your apps.
+
+## Resource and Platform Roles
+
+Private Mendix Platform separates platform-wide privilege from privilege over an individual resource. Role Management presents the two as separate tabs, and they share no permissions.
+
+### Resource Roles
+
+A Resource Role answers the question *what can this person do to this app, or this namespace?* It is held by an individual, and it applies only to the resources that the individual reaches it through: the resources owned by the group in which they hold the role, or the single app whose team they were invited to.
+
+Private Mendix Platform includes the following default resource roles:
+
+* **Owner** - Has full control of an app, including transferring ownership, inviting team members, and assigning their roles. 
+
+    This role is automatically granted to the user that created the app. It cannot be granted manually, except by transfering ownership of the app to a new owner. For more information, see [Assigning the App to a New Owner](/private-mendix-platform/reference-guide/admin/company/#ownership).
+
+* **Developer** - Has the complete development and operations set; can change the app's source and deploy it.
+* **Contributor** - Development only; can change the app's source but cannot deploy it.
+* **Operator** - Operations only; can deploy the app, but cannot change its source.
+* **Maintainer** - Can manage logs, events, and metrics, as well as applications and apps.
+* **Administrator** - Can oversee the deployment settings of the apps in scope.
+
+    The Administrator resource role is not the same as a platform administrator.It does not grant access to admin mode and has no privilege over the platform. It reaches only the resources owned by the relevant group. The platform-wide equivalents are the **CompanyAdmin** and **SystemAdmin** platform roles.
+
+Permissions in a Resource Role have the following categories:
+
+* **Project** - The app lifecycle, its team, version control, and viewing its environments
+* **Build** - Packaging, the build pipeline, and the software bill of materials.
+* **Deployment** - Deploying and managing the app's environments; this is the largest category, and the only one that can be scoped per environment
+* **Monitoring** - Logs and metrics
+
+Every permission in a resource role is expressed as an action on an app, which is why the schema reads as a set of app permissions even for roles concerned mainly with deployment settings.
+
+#### Per-Environment Scoping
+
+Deployment is the only permission category that can be limited by environment. Each permission in it can be restricted to any combination of Development, Test, Acceptance, and Production. No other category offers this.
+
+This is what makes it possible to express a role such as *may deploy freely to Development and Test, and may not deploy to Production at all* without creating separate roles per environment, and it is the mechanism to reach for when a compliance requirement separates production deployment from everyday development.
+
+### Platform Roles
+
+A platform role answers the question *what can this person do on the platform in general?* It is assigned to a user account when the account is created, and can be changed at any time afterward. Platform roles are stackable. That is, a user can hold several, and the effective set of permissions is everything those roles grant, added together.
+
+Private Mendix Platform includes the following default platform roles:
+
+* **User** - Baseline access to the platform web interface. Every human user needs this role at minimum.
+* **CompanyAdmin** - Company admins have access to everything under the **Manage** section of the Admin menu, including the following capabilities:
+
+    * App management
+    * User and group management
+    * Marketplace content
+    * Deployment clusters
+    * Activity logs
+    * Platform statistics
+    
+    This role is intended for users who own day-to-day platform operations.
+
+* **SystemAdmin** - Company admins have access to everything under the **Settings** section of the Admin menu, including the following capabilities:
+
+    * Identity provider and SSO configuration, version control and CI/CD integrations, licensing, branding, and platform capabilities. Intended for the people who own the infrastructure the platform depends on.
+
+{{% alert color="info" %}}
+CompanyAdmin and SystemAdmin address different audiences and grant access to different capabilities of Admin mode. Granting CompanyAdmin does not give someone access to identity or licensing settings, and granting SystemAdmin does not give someone the ability to manage users and groups. A user who needs both must be given both.
+{{% /alert %}}
+
+#### Platform Role Permissions
+
+Permissions in a platform role fall into the following broad categories.
+
+##### Generic Permissions
+
+Generic permissions grant basic platform access:
+
+* **Web** - Can reach the web interface.
+* **App** - Can create an app.
+
+##### Management Permissions
+
+Management permissions involve the capabilities available in the **Manage** section of the Admin menu, such as app management, user and group management, Marketplace administration, and activity logs:
+
+* **Apps** - Includes the following permissions:
+    
+    * **Access App management pane**
+    * **Access software composition pane**
+    * **Access import apps pane**
+
+* **Marketplace** - Includes the following permissions:
+
+    * **Manage content in content management pane**
+    * **Approve content in content management pane**
+    * **Delete content in content management pane**
+    * **Access import content in content management pane**
+    * **Access taxonomy management pane**
+
+* **Deployment** - Includes the following permissions:
+
+    * **Access cluster manager pane**
+    * **Access environment overview pane**
+
+* **Users** - Includes the following permissions:
+
+    * **Access role management pane**
+    * **Edit user management pane**
+    * **View user management pane**
+    * **Edit group management pane**
+    * **View group management pane**
+
+* **Platform** - Includes the following permissions:
+
+    * **Access platform statistics pane**
+    * **Access activity logs pane**
+    * **Access webhooks pane**
+    * **Access licensing pane**
+    * **Access Maia pane**
+
+##### Settings Permissions
+
+Settings permissions involve the capabilities available in the **Settings** section of the Admin menu, such as identity and access configuration, licensing, cluster manager configuration, and webhooks:
+
+* **Preferences** - Includes the following permissions:
+
+    * **Access notification setting pane**
+    * **Access general setting pane**
+    * **Access marketplace setting pane**
+    * **Access version support setting pane**
+
+* **Integrations** - Includes the following permissions:
+
+    * **Access identity & access setting pane**
+    * **Access project management setting pane**
+    * **Access version control setting pane**
+    * **Access build setting pane**
+    * **Access deployment setting pane**
+
+* **Advanced** - Includes the following permissions:
+
+    * **Access capability setting pane**
+    * **Access operational setting pane**
+
+#### Managing API User Accounts
+
+There is only one type  of account. Accounts used by services rather than people are not a separate account type. A service that calls the platform API authenticates as an ordinary account, and what it can do is determined by that account's platform role, in the same way as for a person. A role such as **API User**, holding only the permissions a particular integration needs, is an example of a platform role defined for that purpose.
+
+### Editing Roles and Creating Custom Roles
+
+Administrators can edit both types of roles, change their permissions, and create new roles. Changing a role changes the effective access of everyone who holds it, so review who holds a role before editing it.
+
+Unlike custom roles, default roles cannot be deleted.
+
+### Group Admin
+
+The Group Admin role exists outside both role systems. That is, it is not a platform or resource role. You cannot view or edit this role, and its permissions cannot be changed or extended.
+
+It is automatically assigned to users assigned in the **Group Admins** field of a group. It is not visible in the list of user roles.
+
+This role lets group admins manage a group's membership, that is, add and remove members. It does not grant any other rights, and it applies only to the groups for which its holder was designated.
+
+Consequently, delegating group membership management does not require giving anyone an administrator role. Naming a person as a group admin on their own group is sufficient. For more information, see [Working with Groups and App Teams in Private Mendix Platform](/private-mendix-platform/groups-and-app-teams/).
+
+## Groups
+
+Groups organize users and deliver resource roles at scale. They typically mirror your organization and can represent, for example, a division, a department, a portfolio, or a team.
+
+### Structure
+
+Groups form a hierarchical tree. Private Mendix Platform creates the root group automatically, and it is the foundation of everything beneath it. You can edit the root group's details to match your organization.
+
+Every group other than the root must have the following properties:
+
+* **Parent Group** - The group's place in the hierarchy. There is no such thing as a group outside the tree.
+* **Group Admins** - One or more users who manage the group's membership.
+* **Description** - A clear statement of the group's purpose.
+
+The depth of the hierarchy is not limited.
+
+### A Group Does Not Hold a Role
+
+This is the point at which the model is most often misread. A group is not granted a role, and a group has no permissions of its own. A group holds *members*, and each member individually holds a Resource Role. The group's function is to own resources, so that the roles its members hold have something to apply to.
+
+Two members of the same group can legitimately hold different Resource Roles, and often should. A team group might contain several Developers, a few Contributors, and one Operator, all with access to the same app, doing different things to it.
+
+It follows that a statement such as *this group grants Administrator, so its members are administrators* has the relationship backwards. Members hold roles; the group supplies the scope.
+
+### Membership Inherits Downward
+
+Members of a group automatically become members of every group beneath it in the hierarchy, carrying forward the same Resource Role they hold in the higher group. These are shown as inherited members, as distinct from members added directly.
+
+Inheritance goes to any depth. A member two levels up appears in a grandchild group with the same role they hold two levels up. It does not travel upward: membership of a child group confers nothing in the parent.
+
+{{% alert color="warning" %}}
+Because membership cascades downward without limit, a role granted high in the hierarchy reaches every group below it. Granting a broad Resource Role at or near the root group extends that role across the entire platform. See [Designing Your Access Model](#designing-your-access-model).
+{{% /alert %}}
+
+## Resources Owned by Groups
+
+A group can own or be associated with three kinds of resource. The ownership rules differ for each, and so does the behavior of that ownership with respect to the hierarchy.
+
+| Resource | Ownership model |
+| --- | --- |
+| **App Projects** | Exclusive. An app is owned by exactly one group, so accountability is unambiguous. |
+| **Deployment Namespaces** | Shareable. A namespace can be associated with several groups at once, allowing operational responsibility to be shared between teams. |
+| **Marketplace Components** | Owned by the individual user who published the component. |
+
+### App Projects
+
+An app is owned by one group and one user within it. Members of the owning group reach the app through the Resource Role they hold in that group, whether they hold it directly or by inheritance from a group further up.
+
+{{% alert color="warning" %}}
+**Apps created through Mendix Studio Pro are owned by the Mendix root group.** Ownership is assigned to the root group on creation rather than to the group the creating developer belongs to. An app left in this state is reachable by everyone holding a Resource Role in the root group, and by nobody further down the hierarchy, since membership inherits downward and resource access does not travel upward. Neither is usually what was intended.
+
+Transfer ownership to the group that should hold it as a routine step after creating an app from Studio Pro. See [Assigning the App to a New Owner](/private-mendix-platform/reference-guide/admin/company/#ownership).
+{{% /alert %}}
+
+### Deployment Namespaces
+
+Two concepts are involved here and both are meaningful. A **deployment namespace** is the resource. A **namespace purpose** is a scoping tied to that resource, describing what the namespace is for.
+
+They form a chain: a namespace is associated with a group, and the namespace's purpose is tied to the namespace in turn. So the group is associated with the namespace, and the purpose comes with it as a property of the namespace rather than as something set on the association. Purpose is therefore configured once, on the namespace, and holds for every group associated with it. For how purpose relates to environments, see [Deployment Purpose and DTAP Mode](/private-mendix-platform/user-guide/#deployment-purpose-and-dtap-mode).
+
+{{% alert color="warning" %}}
+**A namespace association does not inherit, in either direction.** Group membership and the Resource Roles that come with it cascade down the hierarchy. A deployment namespace association does not: it extends neither to a group's parents nor to its children.
+
+For a group to deploy to a namespace, **that group must itself be directly associated with the namespace**, regardless of where either sits in the tree. In practice this means keeping an app project and the namespace it deploys to associated at the same level of the hierarchy.
+
+This rule is specific to deployment namespaces. App projects are already exclusive to a single group, and Marketplace components follow their own ownership model, so neither is affected by it.
+{{% /alert %}}
+
+### Marketplace Components
+
+A component published to the private Marketplace is owned by the user who published it, rather than by a group. Ownership therefore does not follow the group hierarchy.
+
+Access to the Marketplace administration area, where content is approved, categorized, and imported, is a platform role permission and not a Resource Role. A user who administers Marketplace content does not need any Resource Role to do so.
+
+Marketplace content can additionally be shared with groups by its publisher. See [Sharing Content with Groups](/private-mendix-platform/user-guide/#sharing-content-with-groups).
+
+## How a User Gets Access to an App
+
+There are three distinct paths, and it is worth keeping them separate when diagnosing why someone can or cannot reach an app.
+
+1. **Through the owning group.** The user is a member, directly or by inheritance, of the group that owns the app, and holds a Resource Role there. This is the primary path and the one that scales.
+2. **Through a direct invitation to the app team.** The app's owner invites an individual onto the team and assigns them a role such as Developer, Contributor, or Operator. This bypasses groups entirely and applies to that one app. Before a user can be invited, their account must exist. See [Editing App Details](/private-mendix-platform/reference-guide/admin/company/#app-details).
+3. **Through app sharing, followed by a request.** An app can be shared with groups that do not own it. Sharing makes the app *visible* to those groups; it grants no access. Members who can see a shared app can request access from the app's owner, who decides whether to grant it and with which role. See [Sharing the App with Selected User Groups](/private-mendix-platform/reference-guide/admin/company/#share).
+
+{{% alert color="info" %}}
+**Reviewer note:** confirm the mechanics of the request flow in path 3 - how the request reaches the owner, whether it is notified, and whether granting it creates a direct team membership.
+{{% /alert %}}
+
+## How Permissions Combine
+
+The two role systems combine differently, and conflating them is the source of most incorrect expectations about effective access.
+
+### Platform Roles Combine as a Union
+
+Platform roles are not scoped to a resource, so there is nothing to reconcile. A user's effective platform permissions are every permission granted by every platform role they hold, added together.
+
+### Resource Roles Combine Only on a Shared Resource
+
+Resource Roles do not blanket-combine across every group a user belongs to. Two groups that are not in a parent-and-child relationship share no resources, so a user's roles in them never interact: the role held in one group applies to that group's resources and nowhere else.
+
+Combination happens only when two roles land on the *same* resource. The common case is a user who has been invited directly onto an app's team in one role, and who also inherits a different role on that same app through the group hierarchy. There, and only there, the two are reconciled into a single effective set of permissions on that app.
+
+### Changes Take Effect Immediately
+
+When a member's role in a group changes, the change is applied at once to every resource that group owns or is associated with. There is no separate synchronization step to run, and no need to reapply access to individual apps or namespaces after a role change.
+
+## Federated Users {#federated-users}
+
+When users sign in through your identity provider rather than with a local account, they still need a place in the group hierarchy and a Resource Role in order to do anything. Three settings determine what happens on first arrival.
+
+* **Default Group and Default Role.** Every incoming user with no other placement is put into a configured group with a configured role. Pointing these at a deliberately low-privilege landing group gives new arrivals somewhere to be that has no access to real projects, until they are assigned to their actual team.
+* **Parse Roles.** When enabled, Private Mendix Platform reads group and role claims from the incoming token and maps them onto platform roles and groups automatically. When disabled, no such mapping occurs and every federated user lands on the defaults above, to be assigned afterwards manually, through SCIM, or through the platform API.
+* **Automation Settings.** For users whose identity provider information is mapped onto their platform profile, group membership can be driven from the values of those profile attributes. When a user arrives with a value that already corresponds to a group, they are added to that group. When a user arrives with a value that does not, a group is created for it and the user is made a member. This is configured on the Group Management page and is separate from Parse Roles. See [Automating Group Assignment](/private-mendix-platform/access-administration/#automating-group-assignment).
+
+Users can also be provisioned before their first login, using SCIM, so that their accounts and group placement exist in advance.
+
+Configuring the identity provider connection itself, including OIDC and SAML setup, attribute mapping, and SCIM tokens, is documented in [Private Mendix Platform Functionalities - System Administrators](/private-mendix-platform/reference-guide/admin/system/#identity--access).
+
+{{% alert color="info" %}}
+**Reviewer note:** supply the exact field labels and locations for Default Group, Default Role, and Parse Roles so this section can point readers at the right screen.
+{{% /alert %}}
+
+## Designing Your Access Model {#designing-your-access-model}
+
+The rules above have direct consequences for how a hierarchy should be laid out.
+
+**Keep broad roles rare and high, and let narrow roles do the work low down.** Because membership cascades downward, a Resource Role granted near the root reaches everything beneath it. Roles such as Administrator and Maintainer should be granted sparingly, and as close as possible to the groups that actually need them. Developer, Contributor, and Operator are the roles intended to carry everyday work further down the tree.
+
+**Associate an app and the namespace it deploys to at the same level.** Since namespace associations do not inherit, a group that owns an app but is not itself associated with a namespace cannot deploy that app, no matter what its parent is associated with. Placing both at the same level avoids the problem entirely.
+
+**Give federated arrivals a landing group.** A low-privilege group configured as the Default Group means an unrecognized user who signs in successfully still reaches nothing of consequence until an administrator places them.
+
+**Use per-environment scoping instead of parallel roles.** Where the requirement is that a team may deploy to some environments and not others, scope the Deployment permissions of one role rather than maintaining two similar roles.
+
+**Mirror your organization, but only as deeply as you need.** Depth is unlimited, and each additional level adds inherited membership to reason about. Add a level when it corresponds to a real boundary of accountability.
+
+### Worked Example
+
+Consider the following hierarchy.
+
+```text
+Mendix (root)
+├── Platform Admin
+│   └── App Portfolios
+│       └── App Portfolio 1
+└── Preboarding
+```
+
+A user who is a member of **App Portfolios** with the Developer role is also, by inheritance, a Developer in **App Portfolio 1**, and can develop and deploy the apps that group owns. That same user is not a member of **Preboarding**, which is not beneath their group, and has no access to anything Preboarding owns.
+
+A user who is a member of **Platform Admin** with the Administrator role holds it in **App Portfolios** and **App Portfolio 1** as well, because both are beneath Platform Admin. Adding a new portfolio group under App Portfolios extends that user's Administrator role into it automatically. This is the reason to grant Administrator low rather than high.
+
+If **App Portfolio 1** owns an app that must deploy to a namespace, App Portfolio 1 must be associated with that namespace itself. Associating the namespace with **App Portfolios**, or with **Mendix**, does not enable the deployment.
+
+**Preboarding** is a natural candidate for the Default Group in an SSO configuration: users who arrive without a recognized placement land there, hold whatever low-privilege Default Role is configured, and reach nothing owned elsewhere in the tree.
+
+{{% alert color="info" %}}
+**Reviewer note:** a diagram of this hierarchy showing groups, members, roles, owned apps, and namespace associations exists in the supporting document set and should be attached here in place of the code block above.
+{{% /alert %}}
diff --git a/content/en/docs/private-platform/roles/pmp-groups-and-app-teams.md b/content/en/docs/private-platform/roles/pmp-groups-and-app-teams.md
new file mode 100644
index 00000000000..79933b37ab0
--- /dev/null
+++ b/content/en/docs/private-platform/roles/pmp-groups-and-app-teams.md
@@ -0,0 +1,110 @@
+---
+title: "Working with Groups and App Teams in Private Mendix Platform"
+url: /private-mendix-platform/groups-and-app-teams/
+weight: 30
+description: "Documents how users manage the membership of groups they administer, and how app owners manage the team and sharing of their apps in Private Mendix Platform."
+---
+
+## Introduction
+
+Not all access management in Private Mendix Platform requires an administrator. Two responsibilities are deliberately delegated to ordinary users: managing the membership of a group you have been made responsible for, and managing the team on an app you own.
+
+This page documents both, along with how to work out what access you yourself hold and why. None of it requires switching to admin mode.
+
+## Understanding Your Own Access
+
+Your access comes from two independent sources, and it is worth knowing which one is responsible for what you can and cannot do.
+
+Your **Platform Role** determines what you can do on the platform in general, such as signing in and creating an app. It is set on your account by an administrator.
+
+Your **Resource Roles** determine what you can do to individual apps and namespaces. You hold these as a member of a group, or by direct invitation onto an app's team. A powerful Platform Role does not give you access to any app, and a powerful role on an app does not give you any platform-wide privilege.
+
+If you cannot reach an app you expect to reach, the question to ask is not what role you have, but *through which group*. You have access to an app if you are a member of the group that owns it, or of a group above that one in the hierarchy, or if the app's owner invited you directly. Membership of an unrelated group, however senior, grants nothing.
+
+You can review your own profile, password, personal access tokens, and service credentials from your account page. See [Configuring Your User Profile and Settings](/private-mendix-platform/user-guide/#configuring-your-user-profile-and-settings).
+
+{{% alert color="info" %}}
+**Reviewer note:** confirm whether users have a screen that shows the roles they hold and the groups they hold them in. If one exists, it should be named here, as this is the first thing a user needs when access does not behave as expected.
+{{% /alert %}}
+
+## Managing Your Group's Membership
+
+If you have been named a group admin on a group, you can manage that group's membership from the **Manage My Group** page. The left navigation menu lists every group you administer.
+
+For each group you can:
+
+* View its current members.
+* Search the platform's users by name or email address and add them to the group.
+* Remove members from the group.
+
+Being a group admin lets you change *who is in* the group. It does not let you create groups, change the hierarchy, change which resources the group owns, or edit roles. Those require an administrator. See [Administering Users, Groups, and Roles in Private Mendix Platform](/private-mendix-platform/access-administration/).
+
+{{% alert color="warning" %}}
+Adding a member to your group gives them access to everything your group owns, and to everything owned by every group beneath yours in the hierarchy, with the role they hold in your group. Before adding someone, be clear about what sits below your group.
+{{% /alert %}}
+
+Members shown as inherited come from groups above yours. You cannot remove them from your group, because their membership does not originate there. If an inherited member should not have access, raise it with the administrator of the group they come from.
+
+{{% alert color="info" %}}
+**Reviewer note:** confirm whether a group admin assigns a member's Resource Role when adding them, or whether membership and role assignment are separate actions with the latter reserved to administrators. The current reference page describes only adding and removing members, which suggests the latter, but this needs confirming because it materially changes what delegation means.
+{{% /alert %}}
+
+## Managing Your App's Team
+
+The **Teams** page of an app shows everyone who has access to it and the role each of them holds.
+
+### Owner
+
+The user who created the app becomes its owner automatically, and ownership cannot be assigned as a role. The owner has full control of the app, including inviting members, assigning their roles, and transferring ownership. Apps created through Mendix Studio Pro are owned by the Mendix root group on creation, so ask an administrator to transfer ownership if it should sit elsewhere.
+
+### Direct and Inherited Members
+
+The Teams page distinguishes two kinds of member.
+
+**Direct members** were invited onto this app specifically, and their roles were assigned by the owner. Their access applies to this app and nothing else.
+
+**Inherited members** reach the app through the group hierarchy rather than through an invitation. Members of the group that owns the app are inherited into it, as are members of the groups above it, each carrying the role they hold in their own group. Their roles are determined by group configuration, not by the app owner, and cannot be changed from the Teams page. To change an inherited member's role, the change has to be made in the group it comes from.
+
+This split is deliberate: direct membership handles the individual exceptions, and inherited membership handles the standing arrangement, so team composition stays consistent with organizational governance without being maintained app by app.
+
+### Inviting a Member
+
+As the app's owner, invite a user onto the team and assign the role they should hold on it, such as **Developer**, **Contributor**, or **Operator**. Which of these to choose follows from what the person will do:
+
+* **Developer** if they will change the app's source and deploy it.
+* **Contributor** if they will change the app's source but should not deploy it.
+* **Operator** if they will deploy the app but should not change its source.
+
+For what each role grants in full, see [Resource Roles](/private-mendix-platform/access-model/#resource-roles).
+
+The user must already have an account on the platform before you can invite them. If they do not, ask an administrator to create one.
+
+{{% alert color="warning" %}}
+An invitation grants access to this app only. It is the right mechanism for a genuine exception, such as a specialist joining for one project. Where a whole team needs standing access, group membership is the mechanism to use instead, because it does not have to be maintained app by app.
+{{% /alert %}}
+
+### Sharing Your App with Other Groups
+
+You can share your app with groups that do not own it. Sharing makes the app visible to those groups, so that people who would otherwise not know it exists can find it. It grants no access of any kind.
+
+Members of a group the app has been shared with can request access from you. You decide whether to grant it, and with which role.
+
+Share an app when you want it discoverable across the organization, for example a reference implementation or an internal service other teams may want to build against. Do not use sharing to grant access; use a team invitation or group membership for that.
+
+{{% alert color="info" %}}
+**Reviewer note:** confirm how an access request reaches the app owner, whether the owner is notified, and what granting a request produces - a direct team membership with a chosen role, or something else.
+{{% /alert %}}
+
+### Deploying to a Namespace
+
+Holding a role that permits deployment is necessary but not sufficient: the group that owns the app must also be associated with the namespace you are deploying to. That association is made by an administrator, and it does not follow the group hierarchy, so a parent group's association does not help.
+
+If you hold Developer or Operator on an app and deployment is nevertheless unavailable, the likely cause is a missing namespace association rather than a role problem. Ask an administrator to confirm that the group owning the app is directly associated with the target namespace. See [Associating Resources with a Group](/private-mendix-platform/access-administration/#associating-resources-with-a-group).
+
+## Finding Your Group's Apps and Content
+
+Apps owned by groups you belong to are listed on the **My Group Apps** page. See [My Group Apps](/private-mendix-platform/reference-guide/common/group-apps/).
+
+Marketplace content shared with your groups is listed on the **Group Content** page. See [Group Content](/private-mendix-platform/reference-guide/common/group-content/).
+
+Content you have published yourself is listed on **My Content**, and you can share it with groups from there. See [Sharing Content with Groups](/private-mendix-platform/user-guide/#sharing-content-with-groups).