docs(TSP-1150): fix critical RBAC permission inaccuracies

[claude]

Summary

• Fixes incorrect Viewer permissions in add-members.mdx: removes the false "Can run agents" claim from the Viewer role
• Adds missing Chat role to add-members.mdx (was entirely absent from the page)
• Updates Viewer description to align with enterprise/rbac.mdx: view-only, cannot run or edit
• Adds link from add-members.mdx to the full RBAC reference page

In enterprise/rbac.mdx:

• Editor clarification: Editor is project-level only; Project Editors auto-get Admin on all project assets
• Viewer clarifications (both project-level and asset-level): no field-level redaction — Viewers see full configs or nothing, not partial metadata
• New section: "Permission inheritance and cascading": documents how project roles cascade to assets, and that Members require explicit asset-level grants
• New section: "Technical implementation notes": covers Member/operator naming, OpenFGA usage, and legacy system behavior for embedded agents

Context

Customer confusion traced to two root causes:

1. The add-members.mdx Viewer role incorrectly stated Viewers can run agents (they cannot — can_trigger requires operator/Member minimum)
2. Permission cascading behavior was completely undocumented, causing confusion when project-level Viewer access didn't cascade as expected to "invited users only" agents

Fixes: https://linear.app/relevance/issue/TSP-1150/

Test plan

• Verify add-members.mdx Viewer accordion no longer mentions running agents
• Verify Chat role accordion is present in add-members.mdx
• Verify Info callout links correctly to /enterprise/rbac
• Verify new sections render correctly in Mintlify preview
• Verify Warning callout in permission inheritance section is a single paragraph (CLAUDE.md compliant)
• Verify all headings are in sentence case

🤖 Generated with Claude Code

[linear]

TSP-1150 Fix RBAC Documentation Bugs - Viewer Permissions, Role Cascading, and Member/Operator Confusion

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
relevanceai	🟢 Ready	View Preview	Apr 9, 2026, 7:02 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[github-actions]

🎯 Vibe check — admin/project-management/add-members.mdx

Scores

	Dimension	Score	What's holding it back
🟡	Consistency	6/10	The Member project role is entirely absent from the roles list; multiple product term capitalization issues; "Organization" in a heading should be lowercase.
🟡	Technical clarity	7/10	Step 4 is too vague; Chat role is listed without any mention of its Enterprise-only/gradual rollout status; Editor accordion mentions "datasets" which doesn't match current product terminology in rbac.mdx.
🟢	Non-technical clarity	8/10	Invitation acceptance flow section is well written. Minor point: the misplaced Warning creates a confusing non-sequitur.
🟡	Structure	7/10	The Warning about region permanence sits directly under "Add members to your Organization" but has nothing to do with adding members — it belongs on the org creation or IDs/regions page.

---

🔧 Issues

• Line 20: "Members in your organization can be assigned the following roles: Admin, Editor, Chat, and Viewer." — The Member project role is missing. rbac.mdx lists five project-level roles: Admin, Editor, Member, Chat, Viewer. This is the most significant error on this page.
• Line 22, 42: Accordion heading Admin and its content say nothing about what Admin can't do (e.g. billing management). Compare to rbac.mdx which reserves billing for Owners. Minor gap but creates an incomplete picture.
• Line 42: "Can run agents and tools." → "Can run Agents and Tools." (product terms)
• Line 45–46: The Chat role description has no mention that it's an Enterprise feature with a gradual rollout. rbac.mdx includes a <Warning> for this. Readers who see Chat listed here and can't find it will be confused.
• Line 46: "Requires asset-level permissions to run specific agents." → "Agents"
• Line 48: "View agents, tools, and knowledge outputs only." → "View Agents, Tools, and Knowledge outputs only."
• Line 69: ## Add members to your Organization — "Organization" is not in the capitalized product terms list (Agent, Tool, Workforce, Knowledge, Trigger, Programmatic GTM). Sentence case: ## Add members to your organization
• Line 71: This <Warning> is about region permanence — completely unrelated to adding members to an organization. It would fit on the org creation page or ids.mdx. As placed, it reads as a non-sequitur that will confuse readers mid-task.
• Line 16: "Send invite!" is not a valid UI step instruction — it reads like a cheer, not a direction. → "Click Send invite."

🧩 Component suggestions

• Lines 27–43: The Editor accordion uses bold section headers (**Has read permissions for:**, **Has write permissions for:**, **Other permissions:**) with nested bullet lists. CLAUDE.md specifies accordion content should use flowing sentences. Consider: "Has read and write permissions for all datasets, Knowledge sets, and Agents. Can also run Agents and Tools. Cannot manage users." That conveys the same information more concisely and without the structural complexity.

⚠️ Contradiction watch

• Line 20 vs. rbac.mdx line 16: This page lists project roles as "Admin, Editor, Chat, and Viewer." The RBAC page defines five project roles: Admin, Editor, Member, Chat, Viewer. The Member role is entirely absent here, which will mislead anyone using this page to understand what role to assign.
• Lines 42–43 (Editor accordion): Mentions read/write permissions for "All datasets" — rbac.mdx doesn't categorize permissions by dataset. "Datasets" appears to be legacy or non-standard terminology relative to the current RBAC model which uses "assets."

✨ Overall vibe

The invitation acceptance flow section (lines 79–104) is genuinely useful and well written. The core problem is that the user roles section is outdated — it's missing the Member role and doesn't reflect the enterprise/rollout caveats that rbac.mdx now documents. Someone who reads only this page gets an incomplete and slightly inaccurate picture of the permission model. The misplaced Warning is the other standout issue — it needs to move.

---

🎯 Vibe check — enterprise/rbac.mdx

Scores

	Dimension	Score	What's holding it back
🟡	Consistency	6/10	Six heading case violations, two banned-word violations in accordion titles, and roughly eight instances of product terms (Agents, Tools, Knowledge, Workforce) written lowercase in table cells and prose.
🟡	Technical clarity	7/10	The **Note:** bold label inside an <Info> callout violates component rules; the permission inheritance table is missing the Member row (a meaningful gap); "new" in line 14 will read as stale after rollout.
🟡	Non-technical clarity	7/10	Best Practices appears before the reader knows what the roles are — referencing "Owners" and "Members" in recommendations before they've been defined is disorienting.
🟡	Structure	7/10	Best Practices section is placed before role definitions. The standard for a reference page of this type is overview → definitions → best practices. As-is, a new reader hits recommendations without context.

---

🔧 Issues

Heading case (sentence case required for all headings and component titles):

• Line 22: ## Best Practices → ## Best practices
• Line 26: ### Organization Level → ### Organization level
• Line 33: ### Project Level → ### Project level
• Line 43: ### Asset Level → ### Asset level
• Line 124: ### Chat Role Details → ### Chat role details
• Line 197: ## Workforce Permissions → ## Workforce permissions

Banned words:

• Line 149: <Accordion title="More powerful than Viewer"> — "powerful" is banned. Suggest: <Accordion title="Higher access than Viewer">
• Line 153: <Accordion title="Less powerful than Member"> — "powerful" is banned. Suggest: <Accordion title="More restricted than Member">

Product term capitalization (Agent, Tool, Knowledge, Workforce must be capitalized as product nouns):

• Line 90: "Manage users, agents, tools, knowledge and project-level integrations." → "Agents, Tools, Knowledge"
• Line 93: "Requires asset-level permissions to run agents." → "Agents"
• Line 94: "View agents, tools, and knowledge outputs only" → "Agents, Tools, and Knowledge"
• Line 130: "interact with AI agents through" → "AI Agents"
• Line 158: "pre-built agents through the chat interface" → "Agents"
• Line 170: "Manage asset configuration, tools, knowledge and assign asset-level users" → "Tools, Knowledge"
• Lines 200–201: "access to the workforce itself" / "each agent used within the workforce" → "Workforce" / "Agent" / "Workforce"
• Lines 204–206: "Share the workforce with the user" → "Workforce"
• Lines 211–213: Table cells "workforce" and "agents" → "Workforce", "Agents"

Component violations:

• Line 216: **Note:** bold label inside <Info> — CLAUDE.md prohibits bold labels inside callouts. Remove **Note:** and start with the sentence directly: "If a user has run access to a Workforce but lacks permissions..."

Other:

• Line 14: "These new controls are designed to…" — "new" is relative and will read as stale post-rollout. Drop it: "These controls are designed to…"
• Lines 228–233: The permission inheritance table shows how Admin, Editor, and Viewer project roles cascade to asset access — but the Member row is absent. Given that rbac.mdx line 239 explicitly calls out that Members do not automatically inherit asset access, this gap in the table is a meaningful omission. A "Member → No automatic asset access (must be granted explicitly)" row would complete the picture.

🏗️ Page structure

• The Best Practices section (lines 22–49) appears before any role definitions. A first-time reader will encounter guidance like "Assign Owners to 1–2 people maximum" before they know what an Owner is. Consider moving Best Practices to follow the three-level breakdowns (after Asset level controls, before the FAQ), or converting the opening Best Practices descriptions into a quick-reference summary table that stays near the top but defers depth to the sections below.

✨ Overall vibe

This is a well-structured reference page with genuinely useful content — the permission tables are clear, the Workforce permissions section fills a real gap, and the technical implementation notes section is a nice addition for API users. The main drag is mechanical: heading case and product term capitalization are inconsistent throughout, and the two "powerful" accordion titles are direct policy violations. The structural issue (Best Practices before definitions) is worth fixing but not blocking. Once the capitalization sweep is done, this page will be in solid shape.

---

🔋 Credit usage

Item	Count
Files reviewed	2
Context pages read	3
Total lines processed	~622

Files read:

• admin/project-management/add-members.mdx (105 lines)
• enterprise/rbac.mdx (261 lines)
• admin/project-management/remove-members.mdx (59 lines)
• enterprise/org-project-controls-governance.mdx (154 lines)
• enterprise/asset-controls.mdx (43 lines)