docs(TSP-1152): add RBAC transition guide and legacy permissions note

[claude]

Summary

• Added a new Transitioning to RBAC section to enterprise/rbac.mdx covering:
  • What the legacy permission system looked like (3 roles, no asset-level granularity)
  • How legacy roles map to RBAC roles by default during migration
  • Critical warning about the Viewer role behavior change (legacy Viewers could run agents; RBAC Viewers cannot)
  • What changes after RBAC is enabled (asset-level enforcement, 403 errors without explicit grants, per-tool credential scoping)
  • Admin action items checklist for post-migration access review
• Added a legacy permissions callout to admin/project-management/add-members.mdx directing RBAC-enabled orgs to the RBAC docs

Test plan

• Verify the Transitioning to RBAC section renders correctly in Mintlify preview
• Verify the Info callout on add-members.mdx renders and the link to /enterprise/rbac resolves
• Check all internal links (/get-started/chat/introduction, /enterprise/rbac) are valid
• Confirm sentence case on all headings

Linear: https://linear.app/relevance/issue/TSP-1152/

🤖 Generated with Claude Code

[linear]

TSP-1152 Add RBAC transition documentation - how user permissions change from normal env to RBAC

[mintlify]

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

Project	Status	Preview	Updated (UTC)
relevanceai	🟢 Ready	View Preview	Apr 10, 2026, 5:32 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	7/10	Mixed UI element formatting (backticks vs bold), product term capitalization misses, and one completely misplaced <Warning>.
🟡	Technical clarity	7/10	The misplaced warning about regions (line 76) will actively confuse readers mid-task.
🟡	Non-technical clarity	7/10	Accordion content uses bold headers + bullet lists inside, which CLAUDE.md prohibits.
🟡	Structure	6/10	Accordion bullet lists violate content standards; the rogue region warning breaks the page flow.

---

🔧 Issues

• Line 76: Misplaced <Warning> about region choice — "Your region choice is permanent..." has nothing to do with adding members. This appears to be a copy-paste artifact from a different page (likely an org-creation page). Remove it entirely.

• Lines 19, 65: UI element formatting — Buttons and nav items use backtick code formatting (Settings, + Invite user) instead of bold. Per docs conventions, UI element names should use bold: Settings, + Invite user. (code formatting is for actual code, not button labels.)

• Line 20: "Send invite!" — Exclamation mark is informal for technical documentation. Use a period or rewrite as a complete step: "Click Send invite."

• Lines 34–35, 46, 53, 57, 100: Product term capitalization — "agents", "knowledge sets", and "tools" appear in lowercase when clearly referring to Relevance AI product features (Agent, Knowledge, Tool). Should be capitalized: "All Agents", "Can run Agents and Tools", "Can't see the Agents after being added to a project?"

• Lines 31–46, 49–57: Accordion content uses bullet lists — CLAUDE.md says accordion content must use flowing sentences, not bullet lists. The Editor and Viewer accordions have bold headers + bulleted permission lists inside. Consider converting these to a permissions comparison table outside the accordions, or rewriting each accordion body as prose (e.g., "Editors can read and write all datasets, Knowledge, and Agents, and can run Agents and Tools. They cannot manage users or billing.").

---

🧩 Component suggestions

• Lines 26–59: <AccordionGroup> for user roles — The accordion structure is being used to present structured permission data (who can read/write what). A markdown comparison table would serve this better — it lets readers scan across roles in a single view rather than opening each accordion individually. Pattern the table after the role/permissions tables in enterprise/rbac.mdx.

---

⚠️ Contradiction watch

• "Knowledge sets" vs "Knowledge" — This page uses "knowledge sets" (lines 34, 40, 53) as the product term. enterprise/rbac.mdx uses "Knowledge" (as a proper noun asset type, line 157). The transition section of rbac.mdx (line 222) also uses "knowledge sets" when describing the legacy system — so both uses may be intentional (legacy vs. RBAC terminology). Worth confirming which term is current and using it consistently, or calling out the distinction explicitly.

✨ Overall vibe

The core content is solid — the acceptance flow section in particular is detailed and genuinely useful. The main problems are mechanical: a stray warning that shouldn't be on this page, inconsistent UI element formatting, and accordion content that needs to either become prose or get converted to a table. The RBAC banner at the top is well-placed and appropriately routes RBAC users elsewhere.

---

🎯 Vibe check — enterprise/rbac.mdx

Scores

	Dimension	Score	What's holding it back
🟡	Consistency	6/10	Five heading capitalization errors, two callout structure violations, banned word used twice in accordion titles, and scattered product term capitalization misses.
🟡	Technical clarity	8/10	The permission tables are thorough and the transition guide is genuinely useful. The 403 error callout (line 255) is a good gotcha.
🟡	Non-technical clarity	8/10	The Best practices section up front gives non-technical admins orientation before hitting the tables. The "Action items for admins" section is practical and actionable.
🟡	Structure	8/10	Logical overall flow. Best practices → reference tables → migration guide → FAQ works well. Minor issue: the multi-paragraph <Warning> at the top violates callout rules.

---

🔧 Issues

• Line 23: ## Best Practices — Title case. Should be sentence case: ## Best practices

• Line 27: ### Organization Level — Title case. Should be: ### Organization level

• Line 33: ### Project Level — Title case. Should be: ### Project level

• Line 43: ### Asset Level — Title case. Should be: ### Asset level

• Line 117: ### Chat Role Details — Title case. Should be: ### Chat role details

• Line 185: ## Workforce Permissions — Title case. Should be: ## Workforce permissions

• Lines 142, 146: Banned word "powerful" — <Accordion title="More powerful than Viewer"> and <Accordion title="Less powerful than Member"> both use "powerful", which is on the banned words list. Rewrite as: "What Chat users can do that Viewers cannot" and "What Members can do that Chat users cannot" — or restructure as a brief comparison sentence in the prose below.

• Lines 6–9: Multi-paragraph <Warning> — CLAUDE.md requires callouts to be a single short paragraph. This warning contains two separate paragraphs. Condense to one: "RBAC is being rolled out gradually to Enterprise customers. If you don't have access yet, contact your sales representative. This feature requires an Enterprise subscription."

• Lines 204–206: Bold label inside <Info> — **Note:** inside the callout violates the no-bold-labels-in-callouts rule. Remove the label — the callout itself conveys the "note" framing. Also consider whether this should be a <Warning> since it describes a blocking error (403) that users will hit if they don't act.

• Scattered product term capitalization — "agents", "tools", and "knowledge" appear in lowercase when referring to Relevance AI product features in several places: line 18 ("using agents"), line 38 ("interact with agents through chat"), line 47 ("view agents, tools, and knowledge outputs only"), and throughout table cells (lines 90, 165). These should be Agents, Tools, Knowledge when referring to the product feature. The asset-level section (line 157) gets this right ("An asset is an Agent, Tool, Knowledge or Workforce") — apply that same standard throughout.

---

🧩 Component suggestions

• Lines 185–209: ## Workforce Permissions — The <Info> callout on lines 204–206 warns about a 403 error if permissions aren't set up. This is a blocking failure state, not an informational note. Swap to <Warning>.

---

🏗️ Page structure

The "Transitioning to RBAC" section is a strong addition. One structural note: the "Action items for admins" list (lines 259–267) uses bold labels inside a bullet list (e.g., **Review user roles immediately.**). This is fine — it's not inside a callout, so the rule doesn't apply. The bold labels here actually help scanability. No change needed.

No closing CTA needed — this is a reference page users visit mid-task to look up permissions.

---

⚠️ Contradiction watch

• Viewer role capabilities across files — enterprise/rbac.mdx (line 241) correctly warns that legacy Viewers could run agents but RBAC Viewers cannot. admin/project-management/add-members.mdx (line 57) describes the legacy Viewer as "Can run agents." These are describing different systems (legacy vs. RBAC) so there's no actual contradiction, but only if readers understand the scoping. The <Info> banner on add-members.mdx handles this redirect adequately.

• No other contradictions found between the two changed files and their neighbors.

✨ Overall vibe

The RBAC page is substantive and well-organized — the new Transitioning to RBAC section in particular is a clear improvement that addresses a real reader need (what do I do when we migrate?). The mechanical issues (heading case, callout rules, banned words) are fixable in a single pass. The permission tables are the clearest part of the page and are well-structured. Once the heading capitalization is cleaned up, this will be a solid reference page.

---

🔋 Credit usage

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

Files read:

• admin/project-management/add-members.mdx (110 lines)
• enterprise/rbac.mdx (279 lines)
• admin/project-management/remove-members.mdx (59 lines)
• enterprise/asset-controls.mdx (43 lines)
• enterprise/rbac-groups.mdx (328 lines)