diff --git a/src/content/docs/enterprise/team-management/workspaces.mdx b/src/content/docs/enterprise/team-management/workspaces.mdx
index 9820971b2..819880497 100644
--- a/src/content/docs/enterprise/team-management/workspaces.mdx
+++ b/src/content/docs/enterprise/team-management/workspaces.mdx
@@ -6,6 +6,7 @@ description: >-
   Workspaces group teams under one Enterprise account with shared membership,
   billing, SSO, and company-wide settings.
 ---
+import { VARS } from '@data/vars';
 
 A workspace groups one or more teams under a single Enterprise account. Workspace admins manage membership, billing, and company-wide policies across those teams. Single Sign-On (SSO) is configured at the workspace level.
 
@@ -22,11 +23,18 @@ A workspace provides company-wide administration, while teams organize shared re
 Every workspace member has one of three roles:
 
 * **Member** - Uses Warp within their teams and the policies admins configure.
-* **Admin** - Manages workspace membership, billing, and settings. Admins can view and manage every team, including teams they don't belong to.
+* **Admin** - Manages workspace membership, billing, and settings, with admin-level permissions on every team, including teams they don't belong to. Team admins who aren't workspace admins have admin permissions only on their teams.
 * **Owner** - Has every admin capability and can transfer ownership to another member. Each workspace has one owner.
 
 In team member lists, the **Workspace admin** and **Workspace owner** badges distinguish workspace roles from team roles.
 
+## Workspace admin permissions
+
+Workspace admins can:
+
+* **Manage members** - View everyone in the workspace, promote members to Admin, demote admins, and remove members or other admins. Removing a member also removes them from every team in the workspace.
+* **Manage invitations** - Send email invites, and enable, disable, or reset the workspace invite link and its approved email domains. See [Joining a workspace or team](#joining-a-workspace-or-team).
+
 ## Teams inside a workspace
 
 Workspace admins create teams from the Admin Panel and choose a visibility:
@@ -52,6 +60,26 @@ An unassigned user belongs to the workspace but not to a team. Workspace admins
 
 Unassigned users cannot start cloud agent or factory runs until they join a team. Workspace-level billing and policies still apply to them.
 
+## Cloud agent run visibility
+
+Workspace admins can view and manage each team-owned {VARS.PLATFORM_RUN} in the workspace, including runs that members of other teams started. Their access matches members of the team that owns the run.
+
+Workspace and team roles don't grant access to runs owned by an individual user. Only the user who owns a run can access it by default, though the owner can choose to [share the session](/platform/viewing-cloud-agent-runs/). Other members can access their own runs and runs owned by their teams.
+
+## Changing workspace roles
+
+To promote or demote a workspace admin:
+
+1. In the Warp app, open the [Admin Panel](/enterprise/team-management/admin-panel/) and click **Members**.
+2. On the member's row, click the three-dots menu, then click **Promote to admin** to make them an Admin or **Demote admin** to make them a Member. If you're demoting yourself, click **Demote to member** in the confirmation dialog.
+
+The member's workspace role updates in the list. Use the same menu to remove a member or transfer ownership.
+
+* **Roles are additive** - Changing a workspace role never changes a member's team roles. An admin who is demoted loses workspace admin access immediately but keeps any team admin role they already had.
+* **Only the owner transfers ownership** - The previous owner becomes an Admin.
+* **The owner stays in place** - Admins can't remove the owner or change the owner's role. To step down, the owner transfers ownership first.
+* **Leaving a workspace** - Members can't leave an Enterprise workspace themselves. A workspace admin removes them instead.
+
 ## Workspace settings and team settings
 
 Workspace admins configure company-wide policies in the [Admin Panel](/enterprise/team-management/admin-panel/). For supported settings, they can enforce a value across the workspace or select **Respect Team Setting** to let each team decide.