docs: update snapshotter role permissions - allow environment creation (#340)

Reflects
[kosli-dev/server#6283](kosli-dev/server#6283),
which lets the Snapshotter role create environments via `PUT
/api/v2/environments/{org}` (in addition to reporting snapshots).
Update/archive/rename/policy-attach and every other resource path remain
denied.

Changes:
- `administration/managing_users/roles_in_kosli.md` — overview row,
permissions matrix (split "Create/update environments" into separate
Create and Update rows; Snapshotter gets ✅ for Create), and the
Snapshotter accordion (added environment creation to "can" and listed
update/archive/rename/policy attach in "cannot").
- `administration/authentication/service_accounts.md` — expanded the
Snapshotter description to mention creating environments (e.g.
`--auto-environment`).
- `implementation_guide/phase_1/roles_and_responsibilities/overview.md`
— matching one-line update.

<!-- mintlify-agent-attribution -->
---
Generated by Mintlify Agent.

Requested by: marko@kosli.com via Slack
Mintlify session: slack_1784903854.216899_C0AJTQ5633K

---------

Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
Co-authored-by: Marko Bevc <marko@kosli.com>
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

Author: 3 people

administration/authentication/service_accounts.md

@@ -35,7 +35,7 @@ Service accounts have the same role model as users: **Admin**, **Member**, **Sna
 See [Roles in Kosli](/administration/managing_users/roles_in_kosli) for the full permissions matrix. As a starting point:
 
 - **Member** — CI/CD systems that report attestations, manage flows, and create resources.
-- **Snapshotter** — runtime reporters that only record environment snapshots.
+- **Snapshotter** — runtime reporters that record environment snapshots and create environments (for example, CLI callers using `--auto-environment`).
 - **Reader** — read-only systems such as dashboards or query tooling.
 - **Admin** — rarely needed; reserve for automation that manages users, roles, or organization-wide settings (for example, Terraform-driven org bootstrap).
 

administration/managing_users/roles_in_kosli.md

@@ -14,7 +14,7 @@ Roles apply to service accounts the same way they apply to users. Wherever this
 |------|-------------|----------|
 | **Admin** | Full control over the organization | Organization owners, security leads, platform engineering leads |
 | **Member** | Can create and modify resources | Developers, platform engineers, CI/CD systems |
-| **Snapshotter** | Can create snapshots and modify service accounts | Environment and operations teams |
+| **Snapshotter** | Can create snapshots, environments, and manage their own service accounts | Environment and operations teams |
 | **Reader** | Read-only access to view data | Auditors, compliance officers, stakeholders, reporting systems |
 
 ## Permissions Matrix
@@ -33,7 +33,8 @@ Roles apply to service accounts the same way they apply to users. Wherever this
 | **Resource Management** | | | |
 | Create flows | ✅ | ✅ | ❌ | ❌ |
 | Update/delete flows | ✅ | ✅ | ❌ | ❌ |
-| Create/update environments | ✅ | ✅ | ❌ | ❌ |
+| Create environments (and re-create) | ✅ | ✅ | ✅ | ❌ |
+| Update environments (PATCH, archive, rename, attach/detach policies) | ✅ | ✅ | ❌ | ❌ |
 | Delete environments | ✅ | ❌ | ❌ | ❌ |
 | Create/update policies | ✅ | ✅ | ❌ | ❌ |
 | Delete policies | ❌ | ❌ | ❌ | ❌ |
@@ -120,26 +121,32 @@ The following sections provide more details about each Kosli user role, includin
   <Accordion title="Snapshotter" icon="camera">
 
 
-  Snapshotters can create environment snapshots and manage service accounts, but cannot manage users, resources or integrations or organization-wide settings.
+  Snapshotters can create environments, report environment snapshots, and manage their own service accounts, but cannot modify other resources, manage users, configure integrations, or change organization-wide settings.
 
   ### Permissions
 
   Snapshotters can:
 
-  - **Service Accounts**: Create and manage service accounts and their API keys
-  - **Snapshots**: Report environment snapshots
-  - **View Data**: Access trails, artifacts, attestations, and snapshots
-  - **Query Information**: Search and filter data across flows and environments
-  - **Generate Reports**: Export and analyze compliance data
-  - **View Configurations**: See flow definitions, policies, attestation types, and actions (but cannot modify them)
+  - **Service Accounts**: Create service accounts. They can manage the API keys of service accounts they created themselves — API keys on other service accounts can only be managed by the account's creator or an org Admin.
+  - **Environments**: Create new environments (needed so CLI flows like `--auto-environment` work with a snapshotter token).
+  - **Snapshots**: Report environment snapshots.
+  - **View Data**: Access trails, artifacts, attestations, and snapshots.
+  - **Query Information**: Search and filter data across flows and environments.
+  - **Generate Reports**: Export and analyze compliance data.
+  - **View Configurations**: See flow definitions, policies, attestation types, and actions (but cannot modify them).
 
   Snapshotters cannot:
-  - Create, update, or delete any resources
-  - Report attestations
-  - Manage approvals
-  - Create or manage actions
-  - Configure integrations
-  - Invite users or change settings
+  - Use the dedicated update paths on an environment (PATCH, archive, rename, attach/detach policies).
+  - Create, update, or delete flows, policies, attestation types, or other resources.
+  - Report attestations.
+  - Manage approvals.
+  - Create or manage actions.
+  - Configure integrations.
+  - Invite users or change settings.
+
+  <Warning>
+  Because the environment create endpoint (`PUT /api/v2/environments/{org}`) is idempotent — a re-PUT of an existing environment updates it — a snapshotter token can modify an existing environment's description, scaling, policies, and included environments by re-PUTting a full payload. Only the dedicated update paths (PATCH, archive, rename, policy attach/detach) are blocked. Keep this in mind when scoping snapshotter tokens for environments you don't want them to change.
+  </Warning>
 
   ### When to assign
 

implementation_guide/phase_1/roles_and_responsibilities/overview.md

@@ -73,7 +73,7 @@ The RACI matrix above describes responsibilities during Kosli implementation. To
 Kosli user roles control what actions someone can perform in the Kosli system:
 - **Admin**: Full control, including user management and organization settings
 - **Member**: Can create and modify resources, manage service accounts, and configure integrations
-- **Snapshotter**: Can report environment snapshots and manage service accounts, with read-only access to other resources
+- **Snapshotter**: Can report environment snapshots, create environments, and manage service accounts, with read-only access to other resources
 - **Reader**: Read-only access to view data and compliance status
 
 For guidance on which Kosli user role to assign based on organizational responsibilities, see [Roles in Kosli](/administration/managing_users/roles_in_kosli) and [Mapping users to roles](/administration/managing_users/mapping_users_to_roles).