docs(rbac): split Roles & Permissions into three pages

[abhijaisrivastava15]

What

Splits Roles & Permissions from one 7,400 word page into three, built to the same shape as the billing/ folder you merged in #821.

roles-and-permissions/
  index.mdx                       Overview            the model, and where the boundary sits
  guides/manage-access.mdx        Manage access       setting up, inviting, changing, removing, sharing
  reference/permissions.mdx       Permission reference every grid, plus what to check when access fails

Three pages, about 1,900 words each. /docs/roles-and-permissions keeps working, because the folder index serves the same URL, so no redirect is needed and no inbound link breaks.

Why these three

The page was two subjects and a lookup table interleaved.

Organization and workspace segregation is a question about where a boundary sits. That is the Overview now, with the diagram, what is scoped where, and the four things the boundary does not cover.

What one person can and cannot reach is a lookup. That is the reference: six grids and the troubleshooting table, nothing else.

Doing any of it is a walkthrough. That is the guide: workspaces, roles, invites, keys, role changes, removals, 2FA and share links, in the order they come up.

Page shapes

Copied from billing/, not invented. index opens with a lead and closes on ## Start here. The guide opens with a lead, carries ## Before you start with a reason on each bullet, uses imperative H2s, and closes on ## Dive deeper. The reference opens at its first H2 and closes on ## Keep exploring. Frontmatter descriptions carry a trailing period on the guide and none on the other two, matching yours.

Content

Every claim was derived by driving the live dashboard through nine role combinations, because a customer cannot read our source. Some of what that turned up:

A key silently takes the workspace you have open. The Add API Key dialog asks for a name and nothing else, but the key binds to whichever workspace is active and traces sent with it land there. Build > Keys then lists only that workspace's keys, so a key made in the wrong place shows the empty state until you switch back.

Delete Key is Owner-only, and the button does not say so. An Admin or a Workspace Admin gets the confirmation and then You are not authorized to access this resource. Proved by an A/B on one key, same organization, same coordinates, only the role changed.

The obvious team setup cannot do its own job. A team lead as organization Member plus Workspace Admin fails the moment the people they lead are also Members, because a Workspace Admin can only change or remove people whose organization role is lower than their own.

Four things the boundary does not cover, which anyone promising a customer isolation needs first: the gateway, where a key can send, what a key can be aimed at, and usage.

Chintan's review on #802, carried over

#802 got 43 inline comments from @jedigalt on 12 Aug. This is the answer to them.

• The masking on users-list.png was a blur, flagged twice. Redone the house way: sharp black rectangles with white masked centred, blur ghost wiped back to the table background, Status column untouched
• "Where do we have settings and API keys?" Right, and it settles a conflict. admin-settings/api-keys.mdx said Settings > API Keys; clicking through the app puts it at Build > Keys. Every page now says Build > Keys
• Seat limits and seat counts gone from every page and from the diagram
• The diagram now shows traces inside every workspace and names all three boxes as workspaces
• Java and C# named on the API keys page, since Milestone uses the C# library
• User management is the three sections asked for, and reactivation is named and answered honestly, because the dashboard has no control that brings a removed person back
• The invite flow from the navigation bar, the role ceiling and the invite expiry are all covered

One comment not acted on, and it is yours to call: "we dont have gateway keys and request logs as part of organization." Driving the live app put gateway request logs at the organization and let every role open every gateway page. That is what these pages say. If the product has moved, say so and I will change it everywhere in one pass.

Verification

• npx astro build: 1174 pages, no errors
• node scripts/audit-links.mjs: 0 broken content links, 0 broken nav links, no new orphans
• Word-diffed twice. Once splitting the old page, once merging down to three. Both diffs caught real drops (2FA, billing by role, the queue settings, the scope note, the X-Workspace-Id override order, the reactivation answer) and all are restored
• Links repaired against the current IA: /docs/installation to /docs/sdk, /docs/admin-settings/billing-pricing to /docs/billing, /docs/annotations/features/queues to /docs/annotations/concepts/queues-and-items

Also in this PR

api-keys, user-management and workspace-management rewritten against the same evidence, About and Next Steps replaced with the house headings, titles matched to their sidebar labels.

Route names corrected: Profile is /settings/profile-settings, Org Settings is /settings/org-settings, Workspaces is singular /settings/workspace. The previously documented /settings/profile, /settings/organization and /settings/workspaces are not routes and 404 for an Owner.

Known gaps, left out deliberately

• Whether gateway request logs partition by workspace. No gateway traffic exists in any internal organization, so the logs read 0-0 of 0 everywhere. Untestable, so unclaimed
• Whether a custom evaluation crosses workspaces. The built-in catalog is identical in every workspace, which is stated. No custom evaluation exists in any test organization
• The invite email link expires at 3 days while the invite record lives 7. Documenting it would enshrine a bug; it needs an engineering fix
• invite-modal.png is 1068 wide against users-list.png at 3024. It needs a re-capture at full width to meet the uniform-size rule