Document Clerk Dashboard workspace roles (#2833)

Co-authored-by: Michael Novotny <manovotny@gmail.com>
Co-authored-by: Sarah Soutoul <sarah@clerk.dev>

Author: 3 people

docs/guides/dashboard/overview.mdx

@@ -7,28 +7,120 @@ The Clerk Dashboard is where you create your Clerk application and is the centra
 
 At the top of the Clerk Dashboard, you will see a few notable features:
 
-- The workspace dropdown: Allows you to switch between [workspaces](#workspaces).
-- The application dropdown: Allows you to choose which application you want to manage.
+- The workspace dropdown: Allows you to switch between [workspaces](#workspaces) or create a new one.
+- The application dropdown: Allows you to choose which application you want to manage or create a new one.
 - The instance dropdown: Allows you to switch between your [development and production instances](#instances).
 - The [`<UserButton />`](/docs/reference/components/user/user-button): Allows you to manage your account and sign out.
 
 We try to make the Clerk Dashboard as intuitive as possible, but if you ever need help or have any feedback, you can always reach out to our [support team](https://clerk.com/support).
 
 ## Workspaces
 
+Workspaces are a way to group applications and resources together.
+
+When you create a Clerk account in the Clerk Dashboard, you are automatically added to a workspace called your **Personal workspace**. You can edit the name of this workspace, along with other settings, on the Clerk Dashboard's [**Settings**](https://dashboard.clerk.com/settings) page.
+
+When you visit the Clerk Dashboard, a workspace is always selected/active. The last workspace used will be selected by default. You can switch between workspaces or create a new one by selecting the workspace dropdown in the top-left of the Clerk Dashboard.
+
+Each workspace can have a **team** with multiple members. You can invite team members to a workspace by visiting the [**Team**](https://dashboard.clerk.com/team) page and then selecting **Invite user**. Each team member can have a different [role](#roles-in-a-workspace), which determines their access levels and permissions within the workspace.
+
+### Roles in a workspace
+
+Clerk distinguishes between different roles to help manage team members' access levels and permissions within an organization. Each role within Clerk is assigned specific permissions that determine what actions a member can perform. When assigning roles to team members, consider the following:
+
+- What resources does this team member need to access?
+- What actions does this team member need to perform?
+- What level of system configuration access is required?
+
+The available roles are:
+
+- [**Admin**](#admin): Full access to organization management, application configuration, and billing.
+- [**Member**](#member): Manage application configuration, API keys, and billing, cannot impersonate users/organizations or manage organization members.
+- [**Support**](#support): User support with read-only application configuration, can impersonate users/organizations and manage restrictions.
+
+#### Admin
+
+The **Admin** role is the highest level of authority within an organization, possessing comprehensive access and control over all settings and resources.
+
+**Key responsibilities:**
+
+- Oversee and manage all organizational resources and applications
+- Modify organization settings, including billing and member roles
+- Access and modify all applications, including their settings, API keys, and domains
+
+**Access and permissions:**
+
+**Admins** have unrestricted access to all organizational functionalities, can modify all settings, and change other members' roles. Concretely, the **Admin** role:
+
+- Can manage workspace members
+- Can manage applications
+- Can manage application configuration
+- Can impersonate and ban/unban users
+- Can manage API keys
+- Can manage restrictions _(allowlist, blocklist, waitlist)_
+- Can manage billing
+
+#### Member
+
+The **Member** role provides access to application management functions while maintaining separation from user-level operations.
+
+**Key responsibilities:**
+
+- Create and manage applications within the workspace
+- Set up integrations and manage application-specific configurations
+- Handle API keys and adjust application settings
+
+**Access and permissions:**
+
+The **Member** role is for team members who need application access without the ability to interact directly with end users. Concretely, the **Member** role:
+
+- Can manage applications
+- Can manage application configuration
+- Can manage billing
+- Can manage API keys
+- Can ban/unban users
+- Can manage restrictions _(allowlist, blocklist, waitlist)_
+- Cannot manage workspace members
+- Cannot impersonate users
+- Cannot manage billing
+
+#### Support
+
+The **Support** role provides tools to assist users and organizations while preventing modifications to sensitive application configurations.
+
+**Key responsibilities:**
+
+- Provide direct user and organization support and troubleshooting
+- Impersonate users/organizations for issue resolution and debugging
+- Manage restrictions including allowlists, waitlists, and blocklists
+
+**Access and permissions:**
+
+**Support** team members have read-only access to application configurations, ensuring they can view necessary information for troubleshooting without the ability to modify critical settings. They cannot access or modify API keys or billing information. Concretely, **Support** team members:
+
+- Can view application configuration
+- Can impersonate users
+- Can ban/unban users
+- Can manage restrictions _(allowlist, blocklist, waitlist)_
+- Cannot manage workspace members
+- Cannot manage applications
+- Cannot modify application configuration
+- Cannot view API keys
+- Cannot manage billing
+
 ### Create additional workspaces
 
 1. In the top-left of the [Clerk Dashboard](https://dashboard.clerk.com), select the workspace dropdown.
 1. Select **Create workspace**. A modal will open.
 1. Complete the form. Workspace slugs are unique across all instances, so common naming conventions might already be in use by another instance.
 1. Select **Create workspace**. The newly created workspace will be set the active workspace.
 
-### Invite collaborators to your workspace
+### Invite team members to your workspace
 
 1. In the top-left of the [Clerk Dashboard](https://dashboard.clerk.com), select the workspace dropdown.
 1. Select **Manage**. You will be redirected to the Team settings page of the active workspace.
 1. Select **Invite user**.
-1. In the **Invite user** form, enter the email of the user you want to invite and select the role to assign.
+1. In the **Invite user** form, enter the email of the user you want to invite and select the [role](#roles-in-a-workspace) to assign.
 1. Select **Invite**.
 
 ### Transfer ownership of an application
@@ -37,9 +129,8 @@ Transferring an application between two workspaces does not cause disruptions. Y
 
 1. In the top-left of the [Clerk Dashboard](https://dashboard.clerk.com), open the workspace dropdown and select the workspace that contains the application you want to transfer.
 1. Locate and select the application to transfer.
-1. At the top of the Clerk Dashboard, select **Configure**.
-1. In the navigation sidenav, under the **Application** heading, select [**Settings**](https://dashboard.clerk.com/~/settings).
-1. Select **Transfer ownership**. A modal will open.
+1. Navigate to the application's [**Settings**](https://dashboard.clerk.com/~/settings) page.
+1. On the right-hand side of the page, select **Transfer ownership**. A modal will open.
 1. Complete the form and select **Transfer ownership**. The page will redirect to the **Applications** page and show the transferred application.
 
 #### Transfer to a workspace without billing information
@@ -60,4 +151,6 @@ To set up a payment method without being charged:
 
 ## Instances
 
-When creating a new application within Clerk, you are provided with two instances: `Development` and `Production`. The names are self-explanatory, but you can learn more about the differences between the two in the [dedicated guide](/docs/guides/development/managing-environments).
+Each Clerk application can have two different instances: `Development` or `Production`. The names are self-explanatory, but you can learn more about the differences between the two in the [dedicated guide](/docs/guides/development/managing-environments).
+
+When you create a new application, it is automatically provisioned with a `Development` instance. You can switch between instances or provision your `Production` instance by selecting the instance dropdown in the top-left of the Clerk Dashboard.