docs(guides): add Roles & Permissions guide [PLT-2039]

[pmdroid]

Adds a customer-facing Roles & Permissions guide documenting the three built-in operator roles and the full permissions matrix.

Closes part of PLT-2039.

What's here

File	Change
app/en/guides/roles-permissions/page.mdx	New guide (156 lines)
app/en/guides/_meta.tsx	Nav entry, alphabetical between MCP Gateways and User Sources
app/en/references/changelog/page.mdx	GA changelog entry under 2026-07-24

Where the matrix comes from

Every cell was derived from the implementation, not from the dashboard UI:

• apps/coordinator/arcade/authz/model.fga — the authorization model (which relations resolve to covered vs admin)
• apps/coordinator/arcade/app/admin/services/rbac_catalog.py — the built-in role catalog and the Project Member bundle

Corrections made against the internal draft this started from:

• Split "Members & invitations" into two rows. members_read is covered (Project Member can see it); invitations_read is admin-only. The draft granted Members a View on both.
• Added Deployments. Project Members hold full manage (deployments_create/update/delete); the draft's role card said so but the matrix had no row.
• Added Tool call history (executions_read: admin). Missing entirely, and it is the privacy-sensitive one — past calls with their inputs and outputs.
• Added User Sources. See the note below.
• Org table now carries Auth providers / Contextual access / User sources. These have org-level bindings (model.fga:67-81); the draft mentioned this in prose but omitted the rows.
• Connected users is View · Revoke, not Manage. Only read and delete relations exist, for every role.

Also added a callout that a Project Member can read secrets and run any tool — a trusted builder role, not a read-only one.

Verification

• vale app/en/guides/roles-permissions/page.mdx — 0 errors
• pnpm test — 767/767 passing (includes internal + broken link checks)
• Pre-commit hooks run, not bypassed: _meta.tsx key validation passed, Ultracite applied no fixes

Two things reviewers should know

1. The changelog entry is gated on the rollout, not on this PR. PLT-2038 — flipping operator-authz ON across all existing production orgs — is still in Backlog. Merging the GA announcement before that lands would advertise something most orgs do not have yet. The guide page itself is safe to ship independently; happy to split the changelog into its own PR if that is cleaner.

2. User Sources needed a code fix to match what this page documents. The user_sources_* relations existed in model.fga but were absent from the permission enums, the AuthZEN wire map, the role catalog, and the router gating — so that API was governed only by legacy project membership and ignored the role matrix. Fixed in a separate monorepo branch (pascal/plt-2039-user-sources-rbac), which also adds a reverse model-to-enum boot assertion so a dead model relation cannot go unnoticed again. This page's User Sources row describes the post-fix behavior, so that change should land before this page is published.

🐕 Written by Kyoto, an AI agent, on Pascal's behalf —

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jul 24, 2026 11:51pm