docs: document workspace and group roles (access control)

docs/admin/users/access-control.mdx

@@ -0,0 +1,171 @@
+---
+title: "Access control"
+---
+
+import { OwnerBadge, AdminBadge, MemberBadge, ViewerBadge, OperatorBadge, ProvisionerBadge, PublisherBadge, GroupManagerBadge } from '/snippets/components/role-badges.jsx';
+
+There are two access control mechanisms for users in a workspace: **user types** and **roles**.
+
+## User types
+
+User types determine the broad access levels of a user. Below is a summary of the user types and their functions.
+
+<OwnerBadge /> - complete control over the workspace; exactly one per workspace
+
+<AdminBadge /> - complete administrative and application access; is subordinate to the owner
+
+<MemberBadge /> - limited application access to the workspace with no administrative privileges
+
+Owners have unrestricted access to the workspace with the ability to execute any action.  Administrators hold nearly the same access as owners, but are unable to escalate themselves to be the workspace owner.
+
+Members are the only user type that can be granted fine-grained access to the workspace through [roles](#roles). Administrators and owners cannot be given any roles since they already have complete access to the workspace.
+
+### Administrative privileges
+
+There are a variety of privileges which are only available to owners and administrators — no roles exist that can grant members these privileges:
+
+[API Keys](/admin/apikeys)
+- Create a new API key
+- Delete an API key
+
+[Groups](/learn/groups)
+- Create a group
+- Update a group
+- Delete a group
+- Move a device to a different group
+
+[Invites](/admin/users/invites)
+- Send an invite
+- Resend an invite
+- Revoke an invite
+
+[Members](/admin/users/manage)
+- Suspend a member
+- Update another member's role
+
+[Workspace](/admin/workspace)
+- Update the workspace
+
+## Roles
+
+While a user's type determines broad access and administrative capabilities, **roles** grant fine-grained access to the workspace. Because owners and admins already have full access to the workspace, roles can only be granted to members.
+
+A member's roles are defined in two independent sources:
+
+- **Workspace roles** apply across the entire workspace
+- **Group roles** apply to a [group](/learn/groups) and all of its subgroups
+
+A member can hold any combination of both. Permissions are always **additive** — Miru allows an action if any of the member's roles permit it, and one role never removes access granted by another.
+
+### Workspace roles
+
+A workspace role grants a member permissions across the **entire workspace**. Every member is at least a viewer, with read-only access to the entire application.
+
+Beyond viewer, the other roles permit write access to specific resources. A member can hold multiple workspace roles at once.
+
+#### Viewer  <ViewerBadge size="sm" /> 
+
+Viewers hold read-only access to the entire application. It is not possible to restrict read access to specific resources.
+
+#### Operator  <OperatorBadge size="sm" /> 
+
+The operator role allows members to deploy configurations to devices in the workspace. The operator role grants access to the following operations:
+
+[Config editor](/learn/devices/config-editor)
+
+- Deploy configurations to devices
+
+[Release staging area](/learn/releases/staging-area)
+
+- Stage a deployment
+- Patch a deployment
+- Review a deployment
+- Deploy a deployment
+- Archive a deployment
+
+#### Provisioner  <ProvisionerBadge size="sm" /> 
+
+The provisioner role allows members to create and activate devices in the workspace. The provisioner role grants access to the following operations:
+
+[Manage devices](/learn/devices/manage)
+
+- Create a device
+- Edit a device
+- Delete a device
+
+[Provision devices](/learn/devices/provision/dashboard)
+
+- Provision a device
+- Reprovision a device
+
+#### Publisher  <PublisherBadge size="sm" /> 
+
+The publisher role allows members to create and edit config types, schemas, and releases (all the resources needed to publish a release). The publisher role grants access to the following operations:
+
+[Config types](/learn/config-types)
+
+- Create a config type
+- Edit a config type
+
+[Config schemas](/learn/schemas/manage)
+
+- Create a config schema
+
+[Releases](/learn/releases/create)
+
+- Create a release
+- [Duplicate a release](/learn/releases/manage#duplicate-a-release)
+
+### Group roles
+
+A group role grants permissions inside one [group](/learn/groups) **and every group beneath it**. Because a device belongs to every group above it in the tree, a role granted on a group cascades down to all of its subgroups and devices.
+
+Group roles mirror the workspace roles, scoped to a single group. A member can hold multiple group roles at once.
+
+#### Viewer  <ViewerBadge size="sm" /> 
+
+Viewers hold read-only access to all of the group's resources.
+
+#### Operator  <OperatorBadge size="sm" /> 
+
+The operator role allows members to deploy configurations to devices in the group. The operator role grants access to the following operations:
+
+[Config editor](/learn/devices/config-editor)
+
+- Deploy configurations to devices
+
+[Release staging area](/learn/releases/staging-area)
+
+- Stage a deployment
+- Patch a deployment
+- Review a deployment
+- Deploy a deployment
+- Archive a deployment
+
+#### Provisioner  <ProvisionerBadge size="sm" /> 
+
+The provisioner role allows members to create and activate devices in the group. The provisioner role grants access to the following operations:
+
+[Manage devices](/learn/devices/manage)
+
+- Create a device
+- Edit a device
+- Delete a device
+
+[Provision devices](/learn/devices/provision/dashboard)
+
+- Provision a device
+- Reprovision a device
+
+#### Manager  <GroupManagerBadge size="sm" /> 
+
+The manager role allows members to manage a group's members, their grants, and its subgroups. It includes everything the operator and provisioner roles can do, along with the following operations:
+
+[Groups](/learn/groups)
+
+- Create a subgroup
+- Edit a group
+- Move a device
+- Delete a group
+
+A member's effective permissions are the union of their workspace roles and every group role they hold. For example, a member with the workspace viewer role plus the manager role on a `production` group can read everything in the workspace and fully manage `production` and all of its descendants.

docs/admin/users/overview.mdx

@@ -39,7 +39,7 @@ import UserDef from '/snippets/definitions/user.mdx';
 <ParamField path="role" type="enum">
   <MutableBadge />
 
-  The user's [access role](/admin/users/roles) in the workspace.
+  The user's [access role](/admin/users/access-control) in the workspace.
 
   Allowed values: 
   - `member`

docs/docs.json

@@ -162,9 +162,9 @@
                 "group": "Users",
                 "pages": [
                   "admin/users/overview",
-                  "admin/users/roles",
                   "admin/users/invites",
                   "admin/users/profile",
+                  "admin/users/access-control",
                   "admin/users/manage"
                 ]
               }

docs/snippets/components/role-badges.jsx

@@ -3,21 +3,94 @@ export const OwnerBadge = ({ size = "md" }) => {
         <Tooltip 
             tip="You must be the owner to execute this action."
             cta="Workspace roles"
-            href="/admin/users/roles"
+            href="/admin/users/access-control"
         >
             <Badge icon="crown" color="yellow" size={size}>owner</Badge>
         </Tooltip>
     );
 };
 
+export const MemberBadge = ({ size = "md" }) => {
+    return (
+        <Tooltip
+            tip="Every workspace member can execute this action."
+            cta="Workspace roles"
+            href="/admin/users/access-control"
+        >
+            <Badge icon="user" color="gray" size={size}>member</Badge>
+        </Tooltip>
+    );
+};
+
 export const AdminBadge = ({ size = "md" }) => {
     return (
         <Tooltip 
-            tip="You must be the owner or an admin to execute this action."
+            tip="Workspace owners and administrators can execute this action."
             cta="Workspace roles"
-            href="/admin/users/roles"
+            href="/admin/users/access-control"
         >
             <Badge icon="shield-check" color="blue" size={size}>admin</Badge>
         </Tooltip>
     );
-};
+};
+
+export const GroupManagerBadge = ({ size = "md" }) => {
+    return (
+        <Tooltip 
+            tip="Members who are managers of a group that contains this resource can execute this action."
+            cta="Workspace roles"
+            href="/admin/users/access-control"
+        >
+            <Badge icon="group" color="blue" size={size}>group manager</Badge>
+        </Tooltip>
+    );
+};
+
+export const PublisherBadge = ({ size = "md" }) => {
+    return (
+        <Tooltip 
+            tip="Members with the publisher role can execute this action."
+            cta="Workspace roles"
+            href="/admin/users/access-control"
+        >
+            <Badge icon="git-merge" color="green" size={size}>publisher</Badge>
+        </Tooltip>
+    );
+};
+
+export const ProvisionerBadge = ({ size = "md" }) => {
+    return (
+        <Tooltip 
+            tip="Members with the provisioner role can execute this action."
+            cta="Workspace roles"
+            href="/admin/users/access-control"
+        >
+            <Badge icon="bot" color="purple" size={size}>provisioner</Badge>
+        </Tooltip>
+    );
+};
+
+export const OperatorBadge = ({ size = "md" }) => {
+    return (
+        <Tooltip 
+            tip="Members with the operator role can execute this action."
+            cta="Workspace roles"
+            href="/admin/users/access-control"
+        >
+            <Badge icon="wrench" color="orange" size={size}>operator</Badge>
+        </Tooltip>
+    );
+};
+
+export const ViewerBadge = ({ size = "md" }) => {
+    return (
+        <Tooltip 
+            tip="Members with the viewer role can execute this action."
+            cta="Workspace roles"
+            href="/admin/users/access-control"
+        >
+            <Badge icon="eye" color="gray" size={size}>viewer</Badge>
+        </Tooltip>
+    );
+};
+

docs/snippets/components/users/roles.jsx

@@ -1,18 +1,18 @@
 export const ROLE_TOOLTIP = {
     tip: "The access role of the user in the workspace.",
     cta: "Learn more",
-    href: "/admin/users/roles"
+    href: "/admin/users/access-control"
 };
 
 export const ADMIN_TOOLTIP = {
     tip: "A user with administrative and application access to the workspace; subordinate to the owner.",
     cta: "Learn more",
-    href: "/admin/users/roles"
+    href: "/admin/users/access-control"
 };
 
 
 export const OWNER_TOOLTIP = {
     tip: "A user with complete control over the workspace; exactly one per workspace.",
     cta: "Learn more",
-    href: "/admin/users/roles"
+    href: "/admin/users/access-control"
 };