RBAC and workspace ops docs ref

src/docs.json

@@ -869,8 +869,15 @@
                           "langsmith/data-purging-compliance"
                         ]
                       },
+                      {
+                       "group": "Access control & Authentication",
+                       "pages": [
+                        "langsmith/rbac",
+                         "langsmith/organization-workspace-operations",
+                         "langsmith/authentication-methods"
+                       ]
+                     },
                       "langsmith/scalability-and-resilience",
-                      "langsmith/authentication-methods",
                       "langsmith/faq",
                       "langsmith/regions-faq",
                       "langsmith/pricing-faq"

src/langsmith/administration-overview.mdx

@@ -3,6 +3,9 @@ title: Overview
 sidebarTitle: Overview
 ---
 
+import OrgWorkspaceRole from '/snippets/langsmith/multi-workspace-org-roles.mdx';
+import PermissionReference from '/snippets/langsmith/permissions-reference.mdx';
+
 This overview covers topics related to managing users, organizations, and workspaces within LangSmith.
 
 ## Resource Hierarchy
@@ -117,21 +120,25 @@ To see how to create a service key or Personal Access Token, see the [setup guid
 
 ### Organization roles
 
-Organization roles are distinct from the Enterprise feature (RBAC) below and are used in the context of multiple [workspaces](#workspaces). Your organization role determines your workspace membership characteristics and your organization-level permissions. See the [organization setup guide](/langsmith/set-up-a-workspace#organization-roles) for more information.
+Organization roles are distinct from the [Enterprise feature workspace RBAC](#workspace-roles-rbac) and are used in the context of multiple [workspaces](#workspaces). Your organization role determines your workspace membership characteristics and your [organization-level permissions](/langsmith/organization-workspace-operations).
 
 The organization role selected also impacts workspace membership as described here:
 
-* `Organization Admin` grants full access to manage all organization configuration, users, billing, and workspaces. **An `Organization Admin` has `Admin` access to all workspaces in an organization**
-* `Organization User` may read organization information but cannot execute any write actions at the organization level. An `Organization User` may create Personal Access Tokens. **An `Organization User` can be added to a subset of workspaces and assigned workspace roles as usual (if RBAC is enabled), which specify permissions at the workspace level.**
-* `Organization Viewer` is equivalent to `Organization User`, but **cannot** create Personal Access Tokens. (for self-hosted, available in Helm chart version 0.11.25+)
+- [Organization Admin](/langsmith/rbac#organization-admin) grants full access to manage all organization configuration, users, billing, and workspaces.
+    - An Organization Admin has `Admin` access to all workspaces in an organization.
+- [Organization User](/langsmith/rbac#organization-user) may read organization information but cannot execute any write actions at the organization level. An Organization User may create [Personal Access Tokens](#personal-access-tokens-pats).
+    - An Organization User can be added to a subset of workspaces and assigned workspace roles as usual (if RBAC is enabled), which specify permissions at the workspace level.
+- [Organization Viewer](/langsmith/rbac#organization-viewer) is equivalent to Organization User, but **cannot** create Personal Access Tokens. (for self-hosted, available in Helm chart version 0.11.25+).
 
 <Info>
-The `Organization User` and `Organization Viewer` roles are only available in organizations on plans with multiple workspaces. In organizations limited to a single workspace, all users are `Organization Admins`. Custom organization-scoped roles are not available yet.
+<OrgWorkspaceRole/>
 
 See [security settings](/langsmith/manage-organization-by-api#security-settings) for instructions on how to disable PAT creation for the entire organization.
 </Info>
 
-See the table below for all organization permissions:
+For more information on setting up organizations and workspaces, refer to the [organization setup guide](/langsmith/set-up-a-workspace#organization-roles) for more information.
+
+The following table provdies an overview of organization level permissions:
 
 |                                             | Organization Viewer | Organization User | Organization Admin |
 | ------------------------------------------- | ------------------- | ----------------- | ------------------ |
@@ -151,6 +158,7 @@ See the table below for all organization permissions:
 | Update data retention settings              | ❌                   | ❌                 | ✅                  |
 | Update usage limits                         | ❌                   | ❌                 | ✅                  |
 
+<PermissionReference/>
 
 ### Workspace roles (RBAC)
 
@@ -160,17 +168,19 @@ RBAC (Role-Based Access Control) is a feature that is only available to Enterpri
 
 Roles are used to define the set of permissions that a user has within a workspace. There are three built-in system roles that cannot be edited:
 
-* `Admin` - has full access to all resources within the workspace
-* `Viewer` - has read-only access to all resources within the workspace
-* `Editor` - has full permissions except for workspace management (adding/removing users, changing roles, configuring service keys)
+- [Workspace Admin](/langsmith/rbac#workspace-admin) has full access to all resources within the workspace.
+- [Workspace Editor](/langsmith/rbac#workspace-editor) has full permissions except for workspace management (adding/removing users, changing roles, configuring service keys).
+- [Workspace Viewer](/langsmith/rbac#workspace-viewer) has read-only access to all resources within the workspace.
 
-Organization admins can also create/edit custom roles with specific permissions for different resources.
+[Organization admins](/langsmith/rbac#organization-admin) can also create/edit custom roles with specific permissions for different resources.
 
-Roles can be managed in organization settings under the `Roles` tab:
+Roles can be managed in **Organization Settings** under the **Roles** tab:
 
-![Roles](/langsmith/images/roles-tab-rbac.png)
+![The Organization members and roles view showing a list of the roles.](/langsmith/images/roles-tab-rbac.png)
 
-For more details on assigning and creating roles, see the [access control setup guide](/langsmith/user-management).
+- For comprehensive documentation on roles and permissions, refer to the [Role-based access control](/langsmith/rbac) guide.
+- For more details on assigning and creating roles, refer to the [User Management](/langsmith/user-management) guide.
+- <PermissionReference/>
 
 ## Best Practices