add more info, fix formatting, style guide

app/gateway/permissions/roles-and-permissions.md → app/gateway/roles-and-permissions.md

@@ -1,6 +1,6 @@
 ---
-title: Roles and Permissions
-description: This explains Roles and permissions
+title: RBAC Roles and Permissions
+description: With RBAC can you create roles and permissions and assign them to users. These rules can vary across workspaces.
 content_type: reference
 layout: reference
 products:
@@ -16,25 +16,29 @@ related_resources:
 
 ---
 
-Roles and permissions are administered using the {{site.base_gateway}} [RBAC system](/gateway/rbac/). Roles are sets of permissions that can be assigned to admins and users and can be specific to a [Workspace](/gateway/entities/workspace). 
+Roles and permissions are administered using the {{site.base_gateway}} [RBAC system](/gateway/rbac/). Roles are sets of permissions that can be assigned to admins and users and can be specific to a [Workspace](/gateway/entities/workspace). {{site.base_gateway}} uses a precedence model, from most specificity to least specificity, to determine if a user has access to an endpoint.
 
 
 ## Default {{site.base_gateway}}  roles
 
-By default {{site.base_gateway}} comes configured with the following roles: 
+By default, when {{site.base_gateway}} is configured, the starting user is configured as a **Super Admin** in the `default` Workspace. Workspace's by default contain the following roles: 
 
 | Role      | Description |
 | ----------- | ----------- |
-| Admin (default workspace)   | Full access to all endpoints, across all workspaces, except the RBAC Admin API  |
-| super-admin   | Full access to all endpoints, across all workspaces        |
-|read-only| Read access to all endpoints, across all workspaces|
+| Admin | Full access to all endpoints, across all Workspaces, except the RBAC Admin API  |
+| `super-admin`   | Full access to all endpoints, across all Workspaces, ability to assign and modify RBAC permissions.     |
+|`read-only`| Read access to all endpoints, across all Workspaces|
+
+An **Admin** has full permissions to every endpoint in {{site.base_gateway}}, but they can't assign and modify RBAC permissions. An **Admin** can't modify their own permissions, or configure the permissions of the **Super Admin**.   
 
 ## Workspace roles
 
 | Role      | Description |
 | ----------- | ----------- |
-|workspace-admin | Full access to all endpoints in the workspace - except RBAC Admin API (e.g. can not create new admins)| 
-|Workspace-read-only | Read access to all endpoints in the workspace | 
+|`workspace-admin` | Full access to all endpoints in the Workspace, except the RBAC Admin API.| 
+|`Workspace-read-only` | Read access to all endpoints in the Workspace | 
+
+A role assigned in the `default` WorkSpace has permissions across all subsequently created Workspaces unless the roles in the specific Workplace are explicitly assigned. When a Workspace has explicitly assigned roles, they take precedent over the `default` Workspace. 
 
 
 ## Role configuration
@@ -85,4 +89,3 @@ flowchart LR
 
 
 {% endmermaid %}
-