Edits

Author: katmayb

src/langsmith/billing.mdx

@@ -182,6 +182,10 @@ The extended data retention limit can cause features other than tracing to stop
 
 Data retention settings are adjustable per tracing project.
 
+<Note>
+This UI requires the `projects:increase-trace-tier` or `projects:decrease-trace-tier` permission (or both). If you lack both, the retention settings UI is hidden entirely. If you have only one, the UI is partially enabled — the disallowed direction is disabled. To grant these permissions separately to a custom role, refer to [custom roles](/langsmith/rbac#custom-roles).
+</Note>
+
 Navigate to **Projects** > ***Your project name*** > Select **Retention** and select the desired default retention. This will only affect retention (and pricing) for **traces going forward**.
 
 ![P1projectretention](/langsmith/images/p1projectretention.png)

src/langsmith/organization-workspace-operations.mdx

@@ -114,8 +114,6 @@ System for Cross-domain Identity Management for user provisioning.
 
 Attribute-based access control (ABAC) policies for fine-grained permissions.
 
-
-
 | Operation | Org Admin | Org Operator | Org User | Org Viewer | Required Permission |
 |-----------|:---------:|:------------:|:--------:|:----------:|---------------------|
 | List access policies | ✓ | ✓ | ✓ | ✓ | `organization:read` |
@@ -197,8 +195,8 @@ Projects organize traces and runs from your LLM applications.
 | View prebuilt dashboard | ✓ | ✓ | ✓ | `projects:read` |
 | View project metadata (top K values) | ✓ | ✓ | ✓ | `projects:read` |
 | Update project metadata (name, description, tags) | ✓ | ✓ | ✗ | `projects:update` |
-| Increase project trace retention (base → extended) | ✓ | ✓ | ✗ | `projects:increase-trace-tier` |
-| Decrease project trace retention (extended → base) | ✓ | ✓ | ✗ | `projects:decrease-trace-tier` |
+| Increase project trace retention (base → extended) | ✓ | ✓ | ✗ | `projects:increase-trace-tier`* |
+| Decrease project trace retention (extended → base) | ✓ | ✓ | ✗ | `projects:decrease-trace-tier`* |
 | Create filter view | ✓ | ✗ | ✗ | `projects:create` |
 | View filter views | ✓ | ✓ | ✓ | `projects:read` |
 | View specific filter view | ✓ | ✓ | ✓ | `projects:read` |
@@ -219,6 +217,10 @@ Projects organize traces and runs from your LLM applications.
 | Get run cluster from insights job (Beta) | ✓ | ✓ | ✓ | `projects:read` |
 | Get runs from insights job (Beta) | ✓ | ✓ | ✓ | `projects:read` |
 
+<Note>
+\* `projects:increase-trace-tier` and `projects:decrease-trace-tier` are independent and can be granted separately in custom roles. For example, you can allow a role to decrease retention without allowing it to increase retention. If a user lacks both permissions, the retention settings UI is hidden entirely. If they have only one, the UI is partially enabled (the disallowed direction is disabled).
+</Note>
+
 ### Runs
 
 Individual execution traces and spans from your LLM applications.

src/langsmith/rbac.mdx

@@ -209,6 +209,9 @@ Note the following details on custom roles:
 - Custom roles cannot have organization-level permissions.
 - Users can have different roles (including custom roles) in different workspaces.
 
-<Warning>
-The `workspaces:manage` permission does **not** include the ability to manage workspace members. To allow a custom role to add, remove, or update workspace members, you must explicitly grant the `workspaces:manage-members` permission. The built-in Workspace Admin role includes both permissions automatically.
-</Warning>
+### Understand permission behavior
+
+Some permissions offer granular control when used in custom roles:
+
+- `workspaces:manage` does **not** include the ability to manage workspace members. To allow a custom role to add, remove, or update workspace members, you must explicitly grant `workspaces:manage-members`. The built-in Workspace Admin role includes both permissions automatically.
+- `projects:increase-trace-tier` and `projects:decrease-trace-tier` are independent and can be granted separately. For example, you can allow a role to decrease retention without allowing it to increase retention. If a user lacks both permissions, the retention settings UI is hidden entirely. If they have only one, the UI is partially enabled (the disallowed direction is disabled).