docs: instance groups instance-level role support

docs/advanced/18_instance_settings/index.mdx

@@ -30,6 +30,8 @@ Global Users are users of the Windmill instance. They are not associated with an
 
 From there you can manually add a user to the instance, giving an email and a password. Users can be set to User, [Devops](../../core_concepts/16_roles_and_permissions/index.mdx#devops) or Superadmin [roles](../../core_concepts/16_roles_and_permissions/index.mdx#superadmin).
 
+When a user's role is set by an [instance group](../../core_concepts/8_groups_and_folders/index.mdx#instance-level-roles), a "Set by instance group" indicator appears next to the role toggle. You can still upgrade a user to a higher role manually (e.g. from group-assigned devops to superadmin), but demoting to "User" requires removing the user from the instance group. See [instance-level roles via instance groups](../../core_concepts/16_roles_and_permissions/index.mdx#instance-level-roles-via-instance-groups) for details.
+
 You can also enable automatic username creation from emails. Usernames will be shared accross workspaces. We recommend setting it to avoid duplicated usernames.
 
 A more common way to add users is to use [SSO/OAuth](#authoauth).
@@ -518,4 +520,4 @@ When minimal telemetry is enabled, the following is sent:
 When minimal telemetry is disabled, the following is also collected:
 - job usage (language, total duration, count)
 
-You can "Send usage" to manually send usage data to Windmill and monitor it from the [Customer portal](../../misc/7_plans_details/index.mdx#windmill-customer-portal). You can also "Download usage" to get an encrypted copy of the telemetry data as a `.enc` file. This is useful for air-gapped instances that cannot send telemetry directly — the encrypted file can be sent manually to Windmill.
+You can "Send usage" to manually send usage data to Windmill and monitor it from the [Customer portal](../../misc/7_plans_details/index.mdx#windmill-customer-portal). You can also "Download usage" to get an encrypted copy of the telemetry data as a `.enc` file. This is useful for air-gapped instances that cannot send

docs/core_concepts/16_roles_and_permissions/index.mdx

@@ -55,6 +55,17 @@ The superadmin role has the highest level of access and can manage the entire Wi
 
 The devops role is also set at the instance level. Conceptually, it can be understood as a "readonly Superadmin". Devops users have read rights over what is usually only visible to [superadmins](#superadmin), such as [Service Logs](../36_service_logs/index.mdx) or [Critical Alerts](../37_critical_alerts/index.mdx) while keeping write operations to a minimum. Contrary to the superadmin, this role does not supersede other roles like [workspace admins](#admin).
 
+### Instance-level roles via instance groups
+
+Superadmin and devops roles can also be assigned to [instance groups](../8_groups_and_folders/index.mdx#instance-groups). When an instance group has an instance role, all members of that group automatically receive that role. This is particularly useful with [SCIM](../../misc/14_saml_and_scim/index.md#scim) — for example, an "infrastructure" group in your identity provider can automatically grant devops access to all its members.
+
+**Role precedence rules:**
+- If a user belongs to multiple instance groups with different roles, the highest role wins (superadmin > devops > user).
+- Manually-set elevated roles (superadmin or devops) always take precedence over group-assigned roles. A superadmin manually promoted by another superadmin will not be demoted if their instance group only grants devops.
+- To demote a user whose role is set by an instance group, the user must be removed from the group (or the group's instance role must be changed).
+
+In the [instance settings](../../advanced/18_instance_settings/index.mdx) users list, roles set by instance groups are indicated with a "Set by instance group" label.
+
 ### Admin
 
 At the [workspace](#workspace) level, admins have the ability to manage a specific Windmill workspace and users within that workspace. They can see and edit all scripts, flows, apps, and other entities within the workspace. Admins have the power to create, modify, and delete entities and can manage permissions within the workspace.

docs/core_concepts/8_groups_and_folders/index.mdx

@@ -83,6 +83,14 @@ Instance groups are a special type of group that are automatically managed and s
 3. **User assignment**: When users are added to groups in your identity provider, they automatically gain the corresponding group membership in Windmill
 4. **Permission inheritance**: Instance groups can be assigned to folders and resources just like regular groups, inheriting the same permission levels (Viewer, Writer, Admin)
 
+### Instance-level roles
+
+Instance groups can be assigned an **instance-level role** (superadmin or devops). All members of the group automatically receive that role. This is configured in the instance group editor drawer, accessible from the groups page.
+
+When a user belongs to multiple instance groups with different instance roles, the highest role takes precedence (superadmin > devops > user). Manually elevated roles (set by a superadmin in the instance settings) always take priority over group-assigned roles.
+
+For more details on role precedence, see [Roles and Permissions](../16_roles_and_permissions/index.mdx#instance-level-roles-via-instance-groups).
+
 ### Benefits
 
 - **Reduced administrative overhead**: No need to manually create and manage groups in Windmill

docs/misc/14_saml_and_scim/index.md

@@ -150,6 +150,17 @@ When SCIM is properly configured, groups from your identity provider will be aut
 
 Instance groups appear in your Windmill groups interface with a special designation, and can be assigned permissions to folders and resources just like regular groups. This eliminates the need for manual group management while maintaining full integration with Windmill's permission system.
 
+### Instance-level roles
+
+Instance groups can be assigned an **instance-level role** (superadmin or devops) from the instance group editor. When set, all members of the group automatically receive that role. This allows you to manage instance-level access through your identity provider — for example, assigning devops access to an "infrastructure" group or superadmin access to a "platform-admins" group.
+
+Role changes propagate automatically when:
+- A user is added to or removed from the group via SCIM
+- The group's instance role is changed
+- The group is deleted
+
+Manually elevated roles always take precedence — if a superadmin promotes a user manually, group changes won't demote them. For full precedence rules, see [Roles and Permissions](../../core_concepts/16_roles_and_permissions/index.mdx#instance-level-roles-via-instance-groups).
+
 ### Workspace auto-assignment
 
 Instance groups can be automatically mapped to workspaces with specific role assignments. This powerful feature allows you to: