docs: correct the roles permissions matrix against the code

[AlexKantor87]

Brings the roles permissions matrix in line with what the server allows, using Faye's rebuilt table plus fixes for what has shipped since. The published page disagreed with the code in five places, left out a dozen capabilities, and still warned about a snapshotter gap that kosli-dev/server#7116 has closed.

Closes https://github.com/kosli-dev/server/issues/6751

🤖 Generated with Claude Code

[mintlify]

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

Project	Status	Preview	Updated
kosli	🟢 Ready	View Preview	Oct 13, 2026, 2:19 PM

[AlexKantor87]

@FayeSGW this is your table from https://github.com/kosli-dev/server/issues/6751, so it's yours to review. What I changed from your draft, all checked against server master today:

• Snapshotter re-create. https://github.com/kosli-dev/server/pull/7116 means re-creating an existing environment only succeeds if it changes nothing; any change needs Member or Admin. The old warning is gone and a ‡ footnote explains the new rule.
• Integrations row now reads "(LaunchDarkly, Sonar)". Connecting Slack isn't an org integration: any signed-in user links their own account, whatever their role.
• Approvals row left out. Approvals were removed from the docs in docs: remove retired approvals from the docs #345.
• Overview row for Snapshotter now says service accounts are web UI only, which you flagged as still open.

Checked and left alone: the new notification settings are Admin-only on both the UI and the API, so "Modify organization settings" already covers them. Cloud Capture has its own pages, so I didn't add rows for it here.

Vale isn't installed locally, so spelling is checked by the PR run.

[claude]

Claude finished @AlexKantor87's task in 51s —— View job

---

Doc review: docs: correct the roles permissions matrix against the code

The PR changes no links, navigation entries, or page paths, so no redirect or nav entry is needed. I checked the prose against the other pages that describe what each role can do. Two statements still contradict the corrected matrix.

administration/managing_users/roles_in_kosli.md

Improvement: "Separate concerns" contradicts the new matrix

• Location: administration/managing_users/roles_in_kosli.md:247
• Issue: The best-practices list still says "Snapshotters: Manage environments and policies without affecting build flows". The matrix and the Snapshotter accordion on this page now say a snapshotter can't change an existing environment, can't archive one, and can't create or update policies. A reader who skims to the best-practices section gets the old, wrong scope. The Snapshotter "When to assign" bullet at line 172 ("manage runtime environments") has the same problem.
• Recommendation: Change line 247 to something like - **Snapshotters**: Report environment snapshots and create environments without affecting build flows. Make the same change to the line 172 bullet: "report runtime environment state" instead of "manage runtime environments".

Fix this →

implementation_guide/phase_1/roles_and_responsibilities/overview.md

Improvement: role summaries not updated

• Location: implementation_guide/phase_1/roles_and_responsibilities/overview.md:75-76
• Issue: This page summarizes the roles and links to roles_in_kosli, but it still uses the wording this PR corrects:
  • Snapshotter "can … manage service accounts", with no mention that this works in the web UI only and the API doesn't allow it.
  • Member can "manage service accounts", but members can now manage only the accounts they created.
• Recommendation: Reword both lines to match the new overview table. For example:
  • Member: "create service accounts and manage the ones they created"
  • Snapshotter: "Can report environment snapshots and create environments, and create service accounts in the web UI, with read-only access to other resources"

Fix this →

---

0 Critical · 2 Improvement · 0 Suggestion. Fine to merge once these are fixed. This review is advisory.