diff --git a/astro.config.mjs b/astro.config.mjs
index 97410718..9d28439b 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -78,8 +78,7 @@ export default defineConfig({
       // KloudMate RUM. `init` runs from `onload` so the bundle is fully executed
       // before it is called; the rolling /v2/ path picks up SDK patches without an
       // edit here. Session recording is off, so this collects page performance and
-      // errors only. The `km-rum-ready` event lets UserNav.astro attach the
-      // signed-in user's userId/userEmail even though this bundle loads async.
+      // errors only.
       head: [
         {
           tag: 'script',
@@ -95,7 +94,7 @@ export default defineConfig({
     version: '',
     sampleRate: 1.0,
     sessionRecorder: { enabled: false },
-  }); document.dispatchEvent(new Event('km-rum-ready'))`,
+  })`,
           },
         },
       ],
diff --git a/src/components/UserNav.astro b/src/components/UserNav.astro
index 0818fd95..0622789e 100644
--- a/src/components/UserNav.astro
+++ b/src/components/UserNav.astro
@@ -1,113 +1,14 @@
 ---
 /**
- * Account button for the header: "Log in" by default, "Go to Dashboard" when a
- * KloudMate session exists.
+ * Account button for the header: a link to the app's root. The app sends a
+ * returning user on to the region they last used, a signed-out user to
+ * sign-in, and a signed-in user to their dashboard.
  *
- * The docs share the platform's HTTP-only session cookie (scoped to
- * `.kloudmate.com`), so `GET https://api.<domain>/users/me` with credentials
- * resolves the signed-in user without any auth flow here. The API's CORS
- * allowlist already reflects any `*.<domain>` origin with credentials.
- * The same result is attached to RUM spans as `userId` / `userEmail`, which is
- * what the RUM sessions UI reads (anonymous sessions otherwise).
- *
- * Off-domain (localhost, previews) there is no shared cookie, so the script
- * skips the network call and keeps the static logged-out default.
+ * The docs don't call the API: it answers the web app's origin only.
  */
 ---
 
-<a class="user-cta" data-user-cta href="https://app.kloudmate.com/login">Log in</a>
-
-<script>
-  const CACHE_KEY = 'km-docs-user';
-  // Per-tab cache so plain page navigation doesn't refetch /users/me.
-  const RESULT_TTL = 15 * 60 * 1000;
-  const ERROR_TTL = 5 * 60 * 1000;
-
-  // The API and app live on the docs' own parent domain. No match means no
-  // shared cookie, so don't call the API at all.
-  const parentDomain = ['kloudmate.com', 'kloudmate.dev'].find(
-    (domain) => location.hostname === domain || location.hostname.endsWith(`.${domain}`)
-  );
-  const appOrigin = `https://app.${parentDomain ?? 'kloudmate.com'}`;
-
-  function readCache() {
-    try {
-      const cached = JSON.parse(sessionStorage.getItem(CACHE_KEY) ?? '');
-      if (cached && Date.now() - cached.t < (cached.err ? ERROR_TTL : RESULT_TTL)) {
-        return cached;
-      }
-    } catch {
-      // Absent or malformed cache: fall through to a fresh fetch.
-    }
-    return null;
-  }
-
-  async function fetchUser() {
-    let user = null;
-    let err = false;
-    try {
-      const res = await fetch(`https://api.${parentDomain}/users/me`, {
-        credentials: 'include',
-      });
-      if (res.ok) {
-        const profile = await res.json();
-        if (profile?.id) {
-          user = { id: profile.id, name: profile.name ?? '', email: profile.email ?? '' };
-        }
-      } else if (res.status !== 401 && res.status !== 403) {
-        // 401/403 definitively means logged out; anything else may be transient,
-        // so cache it for a shorter time.
-        err = true;
-      }
-    } catch {
-      err = true;
-    }
-    try {
-      sessionStorage.setItem(CACHE_KEY, JSON.stringify({ t: Date.now(), user, err }));
-    } catch {
-      // Storage full or blocked: skip caching, the next page just refetches.
-    }
-    return user;
-  }
-
-  function render(user) {
-    const cta = document.querySelector<HTMLAnchorElement>('[data-user-cta]');
-    if (!cta) return;
-    if (user) {
-      cta.textContent = 'Go to Dashboard';
-      cta.href = `${appOrigin}/`;
-    } else {
-      cta.textContent = 'Log in';
-      cta.href = `${appOrigin}/login`;
-    }
-  }
-
-  // The RUM bundle loads async from the CDN, so it may not exist yet when the
-  // user resolves. `km-rum-ready` is dispatched by the init snippet in
-  // astro.config.mjs right after KloudMateRum.init(). setUser maps id/email to
-  // the userId/userEmail span attributes the RUM sessions UI reads.
-  function tagRum(user) {
-    if (!user) return;
-    const apply = () =>
-      (window as any).KloudMateRum?.setUser({ id: user.id, email: user.email });
-    if ((window as any).KloudMateRum) {
-      apply();
-    } else {
-      document.addEventListener('km-rum-ready', apply, { once: true });
-    }
-  }
-
-  const cached = readCache();
-  if (cached) {
-    render(cached.user);
-    tagRum(cached.user);
-  } else if (parentDomain) {
-    fetchUser().then((user) => {
-      render(user);
-      tagRum(user);
-    });
-  }
-</script>
+<a class="user-cta" href="https://app.kloudmate.com/">Log in</a>
 
 <style>
   .user-cta {
diff --git a/src/content/docs/docs/aws-integration/account-setup.mdx b/src/content/docs/docs/aws-integration/account-setup.mdx
index 646b7b50..91cb63f5 100644
--- a/src/content/docs/docs/aws-integration/account-setup.mdx
+++ b/src/content/docs/docs/aws-integration/account-setup.mdx
@@ -37,7 +37,7 @@ Each account on the **Data Sources** page has an **Edit** button.
 Click **Edit** to open **Edit Account Details**. It shows the account's AWS account ID and external ID.
 
 - To update the account, change the **AWS Account Name** or paste the **Role ARN**, then click **Update**. If you don't have a role yet, **Click here to add KloudMate CloudFormation stack to AWS** opens the stack in AWS.
-- To remove the account, click **Delete account**. You need the **Owner** role, and the account's data is deleted permanently. See [Remove an AWS Account](../../platform/settings/deleting-your-aws-account-from-kloudmate/) to also remove the stack from AWS.
+- To remove the account, click **Delete account**. You need the **Admin** role, and the account's data is deleted permanently. See [Remove an AWS Account](../../platform/settings/deleting-your-aws-account-from-kloudmate/) to also remove the stack from AWS.
 
 ![The Edit Account Details screen, with the AWS account ID, external ID, account name, Role ARN field, Update button, and Delete account section.](../images/aws-account-setup-edit-details.png)
 
diff --git a/src/content/docs/docs/incident-management/integrations/integrating-with-kloudmate-alerts.mdx b/src/content/docs/docs/incident-management/integrations/integrating-with-kloudmate-alerts.mdx
index fae1c0b5..32795fba 100644
--- a/src/content/docs/docs/incident-management/integrations/integrating-with-kloudmate-alerts.mdx
+++ b/src/content/docs/docs/incident-management/integrations/integrating-with-kloudmate-alerts.mdx
@@ -19,7 +19,7 @@ The **Routing Rule** on this page is an [Alerts routing rule](../../../alerts/ro
 ## Prerequisites
 
 - An [IM service](../../services/) you want incidents to open against.
-- The **Developer** role (you need it to create channels and routing rules).
+- The **Admin** role. You need it to create the channel. A **Developer** can create the routing rule but not the channel.
 
 ## Step 1 — Create a KloudMate Incidents channel
 
diff --git a/src/content/docs/docs/incident-management/status-pages/branding-and-custom-domain.mdx b/src/content/docs/docs/incident-management/status-pages/branding-and-custom-domain.mdx
index 2ea57a45..2579935a 100644
--- a/src/content/docs/docs/incident-management/status-pages/branding-and-custom-domain.mdx
+++ b/src/content/docs/docs/incident-management/status-pages/branding-and-custom-domain.mdx
@@ -38,7 +38,7 @@ This works the moment you publish — no DNS setup required. Use it as-is, or mo
 
 ## Custom domain
 
-A custom domain serves the page from a subdomain of your own — for example `status.example.com`. Custom domains are a paid feature, and only an **organization owner** can set one up.
+A custom domain serves the page from a subdomain of your own, for example `status.example.com`. Custom domains are a paid feature, and you need the **Admin** role to set one up.
 
 <Steps>
 1. In **Settings**, open the custom domain panel and enter your **subdomain** (for example `status.example.com`). It has to be a subdomain — an apex domain like `example.com` isn't supported.
diff --git a/src/content/docs/docs/infrastructure/inventory.mdx b/src/content/docs/docs/infrastructure/inventory.mdx
index 24edea7b..6fb1971b 100644
--- a/src/content/docs/docs/infrastructure/inventory.mdx
+++ b/src/content/docs/docs/infrastructure/inventory.mdx
@@ -69,7 +69,7 @@ When a resource has its own page elsewhere in KloudMate, a button takes you ther
 
 ## When Inventory is empty
 
-If Inventory shows **No resources yet**, nothing has reported to the workspace. [Install the KloudMate agent](../../kloudmate-agent/) to list your hosts, Kubernetes objects, and services, or [connect an AWS account](../../aws-integration/account-setup/) to list its resources. An organization **Owner** can start either one from the empty page with **Install the agent** or **Connect AWS account**.
+If Inventory shows **No resources yet**, nothing has reported to the workspace. [Install the KloudMate agent](../../kloudmate-agent/) to list your hosts, Kubernetes objects, and services, or [connect an AWS account](../../aws-integration/account-setup/) to list its resources. With the **Admin** role, you can start either one from the empty page with **Install the agent** or **Connect AWS account**.
 
 ## Related
 
diff --git a/src/content/docs/docs/issues/index.mdx b/src/content/docs/docs/issues/index.mdx
index db279883..482873bb 100644
--- a/src/content/docs/docs/issues/index.mdx
+++ b/src/content/docs/docs/issues/index.mdx
@@ -126,8 +126,8 @@ Click **Explore Error Patterns** to find recurring error patterns across your se
 
 ## User permissions
 
-- **Owner and Developer**: resolve and ignore issues, one at a time or in bulk, assign issues, create Jira tickets, and comment.
-- **Viewer**: assign issues and comment, but not resolve or ignore them.
+- **Admin and Developer**: resolve and ignore issues, one at a time or in bulk, assign issues, create Jira tickets, and comment.
+- **Viewer**: comment on and watch issues, but not resolve, ignore, or assign them.
 
 ## Related Resources
 
diff --git a/src/content/docs/docs/kloudmate-agent/auto-instrumentation/dotnet.mdx b/src/content/docs/docs/kloudmate-agent/auto-instrumentation/dotnet.mdx
index 744c4cd1..7886ad80 100644
--- a/src/content/docs/docs/kloudmate-agent/auto-instrumentation/dotnet.mdx
+++ b/src/content/docs/docs/kloudmate-agent/auto-instrumentation/dotnet.mdx
@@ -55,6 +55,11 @@ An ASP.NET Core application pool must be set to "No Managed Code" for the profil
 
 On Linux, the agent instruments .NET through the same CLR profiler, loaded through the `CORECLR_*` and `DOTNET_STARTUP_HOOKS` variables in a systemd startup config, then restarts the service. This is less common than .NET on Windows. .NET under PM2 isn't handled automatically; run a .NET service under systemd to instrument it.
 
+The profiler can't load on every Linux host, because it needs a recent glibc:
+
+- **RHEL and CentOS 7 aren't supported.** See [RHEL and CentOS 7](../../installation/linux-agent/#rhel-and-centos-7).
+- **On arm64, the profiler needs glibc 2.35 or later,** so it doesn't load on arm64 RHEL 9 or Amazon Linux 2023.
+
 ## On Kubernetes
 
 Choose **SDK** for the workload and the agent adds the OpenTelemetry Operator annotation `instrumentation.opentelemetry.io/inject-dotnet`. The Operator injects the profiler, and that workload's pods roll to pick it up.
diff --git a/src/content/docs/docs/kloudmate-agent/installation/images/docker-agent-1.png b/src/content/docs/docs/kloudmate-agent/installation/images/docker-agent-1.png
index f89e1310..e6dae0f1 100644
Binary files a/src/content/docs/docs/kloudmate-agent/installation/images/docker-agent-1.png and b/src/content/docs/docs/kloudmate-agent/installation/images/docker-agent-1.png differ
diff --git a/src/content/docs/docs/kloudmate-agent/installation/images/linux-agent-1.png b/src/content/docs/docs/kloudmate-agent/installation/images/linux-agent-1.png
index 532f2bca..d2381464 100644
Binary files a/src/content/docs/docs/kloudmate-agent/installation/images/linux-agent-1.png and b/src/content/docs/docs/kloudmate-agent/installation/images/linux-agent-1.png differ
diff --git a/src/content/docs/docs/kloudmate-agent/installation/images/windows-agent-2.png b/src/content/docs/docs/kloudmate-agent/installation/images/windows-agent-2.png
index bfb03732..d2359575 100644
Binary files a/src/content/docs/docs/kloudmate-agent/installation/images/windows-agent-2.png and b/src/content/docs/docs/kloudmate-agent/installation/images/windows-agent-2.png differ
diff --git a/src/content/docs/docs/kloudmate-agent/installation/linux-agent.mdx b/src/content/docs/docs/kloudmate-agent/installation/linux-agent.mdx
index e262a9b4..99218a73 100644
--- a/src/content/docs/docs/kloudmate-agent/installation/linux-agent.mdx
+++ b/src/content/docs/docs/kloudmate-agent/installation/linux-agent.mdx
@@ -7,7 +7,7 @@ sidebar:
 
 Install the **KloudMate Agent** on a Linux machine.
 
-**Supported Platforms:** Debian/Ubuntu, RHEL/CentOS.
+**Supported Platforms:** Debian/Ubuntu, RHEL/CentOS 7 and later. RHEL and CentOS 7 have [some limits](#rhel-and-centos-7).
 
 If your outbound traffic is restricted, see [Before you start](../before-you-start/) for the URLs and permissions to allow first.
 
@@ -94,6 +94,17 @@ PHP containers get the **SDK** option without a redeploy: the agent injects the
 
 For monitoring containers, a Linux service and a Docker-mode agent are equivalent. Choose between them by how you want to run the agent, not by what they can see. See [Docker mode vs the Linux agent](../../platform-notes/docker/#docker-mode-vs-the-linux-agent).
 
+## RHEL and CentOS 7
+
+RHEL and CentOS 7 need agent version **2.8.1 or later**. Earlier packages fail to install there with a `GLIBC` dependency error.
+
+Host metrics and logs work as usual. The older kernel and glibc on these systems limit the rest:
+
+- **eBPF monitoring isn't available.** It needs kernel 4.14 or later, and these systems run 3.10. The agent skips it and keeps collecting metrics and logs.
+- **.NET auto-instrumentation isn't supported.** The profiler needs a newer glibc, and the .NET versions it supports don't run on these systems. Your .NET applications keep running, without traces from the agent.
+- **PHP 8.2 and later uses the trace extension** instead of the native OpenTelemetry extension, which needs a newer glibc. The agent downloads the trace extension when you turn on instrumentation, so the host needs outbound HTTPS to `github.com` at that point.
+- **Python auto-instrumentation needs Python 3.10 to 3.14,** so it doesn't cover the Python that ships with these systems.
+
 ## Configuration and next checks
 
 New agents start in **managed mode**, with a default of host metrics and eBPF monitoring. You review and change what is collected from the web interface, without editing files on the host. See the [configuration model](../../concepts/config-model/).
diff --git a/src/content/docs/docs/kloudmate-agent/installation/windows-agent.mdx b/src/content/docs/docs/kloudmate-agent/installation/windows-agent.mdx
index 8cec0613..c5e58ad5 100644
--- a/src/content/docs/docs/kloudmate-agent/installation/windows-agent.mdx
+++ b/src/content/docs/docs/kloudmate-agent/installation/windows-agent.mdx
@@ -54,6 +54,30 @@ View all collected data in these KloudMate sections:
 
 ## Install Agent
 
+Install the agent with one PowerShell command. If you'd rather click through the installer, see [Install with the wizard](#install-with-the-wizard).
+
+**Step 1:** On the Windows host, open PowerShell as Administrator. The install stops with an error if PowerShell isn't elevated.
+
+**Step 2:** Run the install command:
+
+```powershell
+irm https://cdn.kloudmate.com/scripts/install_windows.ps1 | iex
+```
+
+**Step 3:** Enter your API key and collector endpoint when asked. You'll find your key under **Settings → Agents & Pipelines → Add Agent → Windows**. Press Enter at the endpoint prompt to use `https://otel.kloudmate.com:4318`.
+
+The script downloads the latest installer, verifies its checksum, and installs the agent in the background, so no wizard opens. It then checks that the `kmagent` service is running and connected to KloudMate. If the agent can't connect, for example because of a wrong API key, the script shows you the error.
+
+To skip the prompts, set your key and endpoint first:
+
+```powershell
+$env:KM_API_KEY="YOUR_API_KEY"; $env:KM_COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318"; irm https://cdn.kloudmate.com/scripts/install_windows.ps1 | iex
+```
+
+On a host that's already configured, the script keeps the existing configuration and ignores `KM_API_KEY`.
+
+### Install with the wizard
+
 **Step 1:** Navigate to the **Settings → Agents & Pipelines** section in your KloudMate account.
 
 **Step 2:** Click **Add Agent**, select **Windows**, and click **Continue**. On the **API key** step, click **Create backend key**, or select **Use existing key** and paste your backend ingest key. Then click **Continue**.
diff --git a/src/content/docs/docs/kloudmate-agent/management.mdx b/src/content/docs/docs/kloudmate-agent/management.mdx
index ff3c72e6..adfc401b 100644
--- a/src/content/docs/docs/kloudmate-agent/management.mdx
+++ b/src/content/docs/docs/kloudmate-agent/management.mdx
@@ -50,6 +50,7 @@ Open the actions menu (⋮) for an agent to manage it:
 
 - **Configure:** Opens the agent's Configuration page, with tabs for **APM**, **Databases**, **Logs**, **Processes**, **Runbook Scripts**, and **Collector Config**. Updates apply automatically wherever the agent is installed.
 - **Restart agent:** Restart the agent when needed.
+- **Uninstall:** Uninstall the agent from its host.
 - **Delete:** Remove the agent from the **Agents & Pipelines** page and clear all of its configuration.
 
 :::caution
@@ -71,7 +72,7 @@ To undo a managed change, turn the toggle back. There is no separate history or
 
 ### Runbook Scripts
 
-The **Runbook Scripts** tab decides whether a [workflow](../../workflows/) can run commands on this host with the [Run Command on Host](../../workflows/actions/#run-command-on-host) step. Scripts are off until someone with the **Developer** role turns on **Allow runbook scripts on this host**. The agent picks up the change within a minute. Only Linux host agents have this setting.
+The **Runbook Scripts** tab decides whether a [workflow](../../workflows/) can run commands on this host with the [Run Command on Host](../../workflows/actions/#run-command-on-host) step. Scripts are off until someone with the **Admin** role turns on **Allow runbook scripts on this host**. The agent picks up the change within a minute. Only Linux host agents have this setting.
 
 ![The Runbook Scripts tab with Allow runbook scripts on this host turned on](./images/agent-runbook-scripts-tab.png)
 
diff --git a/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/agent-groups.png b/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/agent-groups.png
index 6d2c35f9..80bcf70b 100644
Binary files a/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/agent-groups.png and b/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/agent-groups.png differ
diff --git a/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/agent-rules-panel.png b/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/agent-rules-panel.png
index 4baf64f6..fc1fb68c 100644
Binary files a/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/agent-rules-panel.png and b/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/agent-rules-panel.png differ
diff --git a/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/apply-to.png b/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/apply-to.png
index 3fb71856..aa91911e 100644
Binary files a/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/apply-to.png and b/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/apply-to.png differ
diff --git a/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/drop-test.png b/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/drop-test.png
index 351e3e0d..717ab13c 100644
Binary files a/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/drop-test.png and b/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/drop-test.png differ
diff --git a/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/group-page.png b/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/group-page.png
index d31d4341..b0e77e37 100644
Binary files a/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/group-page.png and b/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/group-page.png differ
diff --git a/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/rule-activity.png b/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/rule-activity.png
index 2745a0d4..8f7f175b 100644
Binary files a/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/rule-activity.png and b/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/rule-activity.png differ
diff --git a/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/rules-list.png b/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/rules-list.png
index 1cc61601..1a95295b 100644
Binary files a/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/rules-list.png and b/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/rules-list.png differ
diff --git a/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/sample-record.png b/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/sample-record.png
index 77cc57a8..1b3d7e0a 100644
Binary files a/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/sample-record.png and b/src/content/docs/docs/kloudmate-agent/pipeline-rules/images/sample-record.png differ
diff --git a/src/content/docs/docs/kloudmate-agent/upgrade.mdx b/src/content/docs/docs/kloudmate-agent/upgrade.mdx
index 9c99ad8f..b2b2e7b5 100644
--- a/src/content/docs/docs/kloudmate-agent/upgrade.mdx
+++ b/src/content/docs/docs/kloudmate-agent/upgrade.mdx
@@ -27,6 +27,8 @@ On Kubernetes, Helm rolls the release back if the new pods don't become ready. O
 
 :::note
 One-click upgrade needs agent version **2.5.0 or later**. Upgrade an older agent [manually](#upgrade-manually) once, and later releases can then be applied from the dashboard.
+
+On RHEL or CentOS 7.8 and older, an agent older than 2.8.1 also needs one manual upgrade, because its one-click upgrade can't start on that version of systemd.
 :::
 
 ### When the Upgrade button is disabled
@@ -74,7 +76,15 @@ Your existing `/etc/kmagent/agent.yaml` is kept as it is, including any settings
 
 ### Windows
 
-Download the latest installer from **Settings → Agents & Pipelines → Add Agent → Windows** and run it from an elevated (Administrator) PowerShell prompt:
+Run this in PowerShell as Administrator, and press Enter at the API key prompt to keep your existing configuration:
+
+```powershell
+irm https://cdn.kloudmate.com/scripts/install_windows.ps1 | iex
+```
+
+Your existing `C:\ProgramData\kmagent\agent.yaml` is kept, including any settings you've added by hand. The account-specific command you copy from KloudMate keeps it too, and doesn't ask for a key. If you type a new key at the prompt, the file is replaced with that key and endpoint, and your hand-added settings are lost.
+
+To upgrade with the installer instead, download the latest one from **Settings → Agents & Pipelines → Add Agent → Windows** and run it from an elevated (Administrator) PowerShell prompt:
 
 ```powershell
 .\kmagent-setup.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART
diff --git a/src/content/docs/docs/kloudmate-assistant/mcp-server.mdx b/src/content/docs/docs/kloudmate-assistant/mcp-server.mdx
index 6dd9a0d6..84b51667 100644
--- a/src/content/docs/docs/kloudmate-assistant/mcp-server.mdx
+++ b/src/content/docs/docs/kloudmate-assistant/mcp-server.mdx
@@ -170,7 +170,7 @@ Use a Personal API Key for scripts, and for clients that can't sign in with OAut
 | `Authorization` | `Bearer YOUR_API_KEY` |
 | `x-workspace-id` | `YOUR_WORKSPACE_ID` |
 
-To create a key, open **API keys** from the account menu (top-right) and click **Create Key**. Copy the key when it's shown, because it's shown only once. Any signed-in user can create one, and you don't need the **Developer** role. See [API Keys](../../platform/settings/api-keys/#personal-api-keys) for details.
+To create a key, open **API keys** from the account menu (top-right) and click **Create Key**. Copy the key when it's shown, because it's shown only once. Anyone can create one, whatever their role. See [API Keys](../../platform/settings/api-keys/#personal-api-keys) for details.
 
 A personal key works for every workspace you belong to in your organization, so the `x-workspace-id` header picks the workspace each request reads. Find the workspace ID in the workspace's URL in the KloudMate app.
 
diff --git a/src/content/docs/docs/kloudmate-assistant/settings.mdx b/src/content/docs/docs/kloudmate-assistant/settings.mdx
index aeb97230..3363cd81 100644
--- a/src/content/docs/docs/kloudmate-assistant/settings.mdx
+++ b/src/content/docs/docs/kloudmate-assistant/settings.mdx
@@ -37,7 +37,7 @@ Each skill is defined by the following properties:
 
 - **Title:** The name that users and agents will recognize when referencing or activating the skill.
 - **Content:** The actual skill instructions. Skills are typically written in Markdown and include a short metadata header followed by the detailed steps the Assistant should follow.
-- **Visibility:** When enabled, only you can use or manage the skill. When disabled, the skill is shared with the entire workspace.
+- **Visibility:** When enabled, only you can use or manage the skill. When disabled, the skill is shared with the entire workspace. Sharing a skill needs the **Developer** or **Admin** role.
 - **Enabled:** Turns the skill on or off without deleting it, useful when you want to temporarily pause a skill.
 
 The skills list can be filtered by All, Private, or Shared to help you quickly locate skills by their visibility scope.
@@ -72,7 +72,7 @@ Each tool server is a [connection](/platform/settings/connections/) that can be
 
 ### Connect a tool server
 
-Anyone in the workspace can connect a tool server from this tab. You don't need the **Developer** role.
+You can connect a tool server from this tab with any role that can use the Assistant.
 
 1. Click **Connect** and pick a provider.
 2. Fill in the **Connection name**.
@@ -86,9 +86,9 @@ A tool server you connect here can be used only by the Assistant.
 
 A new tool server is **Private**. Only you can use it, so the Assistant uses it only in your own chats. That fits a personal token, such as your own GitHub account.
 
-To give everyone in the workspace the same server, a **Developer** connects it and then clicks **Share with workspace** in its row menu. A shared server belongs to the workspace, so only Developers can change it. A workflow's [Ask KloudMate Assistant](/workflows/actions/#ask-kloudmate-assistant) step can use only shared servers.
+To give everyone in the workspace the same server, an **Admin** connects it and then clicks **Share with workspace** in its row menu. A shared server belongs to the workspace, so only an Admin can edit or delete it. A workflow's [Ask KloudMate Assistant](/workflows/actions/#ask-kloudmate-assistant) step can use only shared servers.
 
-Without the **Developer** role, you can edit, re-check, and delete your own private tool servers, but you can't share them.
+Without the **Admin** role, you can edit, re-check, and delete your own private tool servers, but you can't share them.
 
 ### One tool server per provider
 
@@ -98,7 +98,7 @@ If you can use two servers of the same provider, the Assistant uses one that you
 
 ### Choose the tools the Assistant can use
 
-Open a server's row menu and click **Tools…** to see the tools the server offers and set how the Assistant uses each one. Click **Save** when you're done.
+Open a server's row menu and click **Tools…** to see the tools the server offers and set how the Assistant uses each one. Click **Save** when you're done. To change the tools of a shared server, you need the **Developer** or **Admin** role.
 
 ![The Tools dialog for a custom MCP server, with quick actions, a search box, and each tool's labels, Enabled switch, and Approval mode](./images/mcp-integrations-tools.png)
 
diff --git a/src/content/docs/docs/platform/settings/api-keys.mdx b/src/content/docs/docs/platform/settings/api-keys.mdx
index c194b1cb..80e2f896 100644
--- a/src/content/docs/docs/platform/settings/api-keys.mdx
+++ b/src/content/docs/docs/platform/settings/api-keys.mdx
@@ -17,7 +17,7 @@ KloudMate has two kinds of API key, each for a different job:
 
 A personal key acts on your behalf. It's tied to **your** account and pinned to your current organization, so it can reach every workspace you belong to in that org, with exactly the permissions you already have, and nothing more.
 
-Find your personal keys in the account menu (top-right) under **API keys**, on the **Personal API Keys** screen in your profile. Any signed-in user can create one; you don't need the **Developer** role, because the key can only do what you can already do.
+Find your personal keys in the account menu (top-right) under **API keys**, on the **Personal API Keys** screen in your profile. Anyone can create one, whatever their [role](../roles/), because the key can only do what you can already do.
 
 Pass it as a bearer token:
 
@@ -39,7 +39,7 @@ A personal key spans every workspace you can reach, so a tool that reads from **
 
 ## Ingest Keys
 
-Ingest keys send telemetry into a single workspace. A key belongs to the workspace it's created in, so create it in the workspace whose data you want to fill. Find them in that workspace under **Settings → Ingest Keys**; adding one requires the **Developer** role.
+Ingest keys send telemetry into a single workspace. A key belongs to the workspace it's created in, so create it in the workspace whose data you want to fill. Find them in that workspace under **Settings → Ingest Keys**. Developers and Admins can see the page, and only an Admin can add a key.
 
 There are two kinds.
 
@@ -81,7 +81,7 @@ A Frontend ingest key is for telemetry sent straight from a browser or mobile ap
 
 <Steps>
 
-1. In the workspace you want to send data to, go to **Settings → Ingest Keys** and click **Add New**. (The button appears only if you have the **Developer** role.)
+1. In the workspace you want to send data to, go to **Settings → Ingest Keys** and click **Add New**. You need the **Admin** role.
 
 2. Choose **Ingest Key – Backend** or **Ingest Key – Frontend**. You can't change the type after the key is created, so pick the one that fits.
 
@@ -101,7 +101,7 @@ Copy it then and store it somewhere safe — a secret manager, your client's con
 
 ## Edit or delete a key
 
-Manage a personal key from the **Personal API Keys** screen, and an ingest key from **Settings → Ingest Keys**. Open the actions menu on a key's row to find both actions. You can edit or delete the personal keys you own. With the **Developer** role, you can do the same to the ingest keys in your workspace.
+Manage a personal key from the **Personal API Keys** screen, and an ingest key from **Settings → Ingest Keys**. Open the actions menu on a key's row to find both actions. You can edit or delete the personal keys you own. With the **Admin** role, you can edit or delete any ingest key in the workspace.
 
 - **Edit** lets you change the note, and for a Frontend ingest key its allowed hosts. The key type is fixed once created.
 - **Delete** is permanent: *this action cannot be undone*. Any agent, collector, app, script, or MCP client using that key stops working the moment you delete it, so swap in a replacement first if the key is in active use.
diff --git a/src/content/docs/docs/platform/settings/cold-storage/archive-logs-to-s3.mdx b/src/content/docs/docs/platform/settings/cold-storage/archive-logs-to-s3.mdx
index 76e59200..e7e1197a 100644
--- a/src/content/docs/docs/platform/settings/cold-storage/archive-logs-to-s3.mdx
+++ b/src/content/docs/docs/platform/settings/cold-storage/archive-logs-to-s3.mdx
@@ -8,7 +8,7 @@ sidebar:
 
 import { Steps } from '@astrojs/starlight/components';
 
-Connect an S3 bucket in your AWS account, and KloudMate exports the workspace's logs to it every hour as Parquet files. You can then [rehydrate](../rehydrate-logs/) any archived range to search it in KloudMate, or query the files directly with your own tools. You need the organization **Owner** role to set this up.
+Connect an S3 bucket in your AWS account, and KloudMate exports the workspace's logs to it every hour as Parquet files. You can then [rehydrate](../rehydrate-logs/) any archived range to search it in KloudMate, or query the files directly with your own tools. You need the **Admin** role in the workspace to set this up.
 
 Archiving is set up per workspace, so connect a bucket for each workspace you want to archive.
 
diff --git a/src/content/docs/docs/platform/settings/cold-storage/index.mdx b/src/content/docs/docs/platform/settings/cold-storage/index.mdx
index d8057d34..c051d152 100644
--- a/src/content/docs/docs/platform/settings/cold-storage/index.mdx
+++ b/src/content/docs/docs/platform/settings/cold-storage/index.mdx
@@ -18,7 +18,7 @@ Cold Storage archives logs only. Traces and metrics aren't archived. It's availa
 
 ## How it works
 
-1. **Archive.** An organization Owner connects an S3 bucket for the workspace. Every hour, KloudMate exports that hour's logs to the bucket as Parquet files. The files belong to you: they stay in your bucket, and you can query them with your own tools, such as Amazon Athena.
+1. **Archive.** An Admin connects an S3 bucket for the workspace. Every hour, KloudMate exports that hour's logs to the bucket as Parquet files. The files belong to you: they stay in your bucket, and you can query them with your own tools, such as Amazon Athena.
 2. **Rehydrate.** When you need logs from the archive, pick a time range and, optionally, the services you're interested in. You see an estimate of the size, load time, and charge before anything starts.
 3. **Search.** In the Log Explorer, switch the source from **Live logs** to the rehydration and search it like any other logs. When it expires, KloudMate removes the rehydrated logs. The files in your bucket aren't affected.
 
@@ -26,21 +26,21 @@ Cold Storage archives logs only. Traces and metrics aren't archived. It's availa
 
 Open **Settings → Cold Storage**.
 
-- **Archive**: connect the bucket, check that exports are working, and see which days are in the archive. Only organization Owners can use this tab.
+- **Archive**: connect the bucket, check that exports are working, and see which days are in the archive. Developers and Admins can see this tab, and only an Admin can change it.
 - **Rehydrations**: start a rehydration, follow its progress, and see when each one expires.
 
 In the Log Explorer, the **Live logs** button switches between live logs and the rehydrations you can search. See [Search a rehydration](./rehydrate-logs/#search-a-rehydration-in-the-log-explorer).
 
 ## Who can do what
 
-| Action | Owner | Developer | Viewer |
+| Action | Admin | Developer | Viewer |
 | --- | --- | --- | --- |
 | Connect, verify, replace, disable, or delete the bucket | Yes | No | No |
-| See the archive status and coverage | Yes | No | No |
+| See the archive status and coverage | Yes | Yes | No |
 | See rehydrations and search them in the Log Explorer | Yes | Yes | Yes |
-| Start, cancel, or delete a rehydration | Yes | Yes | No |
+| Start, cancel, or delete a rehydration | Yes | No | No |
 
-**Owner** is the organization role. **Developer** and **Viewer** are workspace roles.
+An organization Owner is an Admin in every workspace. A [custom role](../roles/custom-roles/) can include **Cold storage** and **Rehydrate** too.
 
 ## Pricing
 
diff --git a/src/content/docs/docs/platform/settings/cold-storage/rehydrate-logs.mdx b/src/content/docs/docs/platform/settings/cold-storage/rehydrate-logs.mdx
index 47e49ef9..1fec4176 100644
--- a/src/content/docs/docs/platform/settings/cold-storage/rehydrate-logs.mdx
+++ b/src/content/docs/docs/platform/settings/cold-storage/rehydrate-logs.mdx
@@ -10,7 +10,7 @@ import { Steps } from '@astrojs/starlight/components';
 
 Rehydration loads a time range from your S3 archive back into KloudMate, so you can search logs that are older than your retention in the Log Explorer. A rehydration stays searchable for 7 or 14 days, then KloudMate removes it.
 
-You need the **Owner** or **Developer** role to start, cancel, or delete a rehydration. Everyone in the workspace, including Viewers, can see rehydrations and search them.
+You need the **Admin** role to start, cancel, or delete a rehydration. Everyone in the workspace, including Viewers, can see rehydrations and search them.
 
 Only hours that have already been [archived](../archive-logs-to-s3/) can be loaded. The **Coverage** table on the **Archive** tab shows which days are in the archive.
 
diff --git a/src/content/docs/docs/platform/settings/connections/connect-an-account.mdx b/src/content/docs/docs/platform/settings/connections/connect-an-account.mdx
index 58494970..506d93c2 100644
--- a/src/content/docs/docs/platform/settings/connections/connect-an-account.mdx
+++ b/src/content/docs/docs/platform/settings/connections/connect-an-account.mdx
@@ -6,7 +6,7 @@ sidebar:
   order: 2
 ---
 
-You need the **Developer** role to connect an account. Open **Settings → Connections** and click **Connect**. To connect a tool server for the Assistant without that role, use [Assistant → MCP Integrations](/kloudmate-assistant/settings/#connect-a-tool-server).
+You need the **Admin** role to connect an account. Open **Settings → Connections** and click **Connect**. To connect a tool server for the Assistant without that role, use [Assistant → MCP Integrations](/kloudmate-assistant/settings/#connect-a-tool-server).
 
 The picker lists only the providers your organization can connect. If a provider you expect is missing, see [Providers](../providers/#providers-in-your-plan).
 
@@ -50,13 +50,13 @@ That matters most for app-event triggers. A Slack account connected from Setting
 
 Every connection is **Workspace** or **Private**. A connection that can be used only for **AI** starts **Private**. Every other connection starts **Workspace**.
 
-A **Workspace** connection belongs to the workspace. Anyone in the workspace can use it, anyone with the **Developer** role can manage it, and it keeps working when whoever connected it leaves.
+A **Workspace** connection belongs to the workspace. Anyone in the workspace can use it, anyone with the **Admin** role can manage it, and it keeps working when whoever connected it leaves.
 
 **Private** restricts a connection to its creator. Only a connection whose one capability is **AI** can be private, so use it for a personal GitHub or Google account that you want the Assistant to use on your behalf and nobody else's.
 
 A private connection is invisible to everyone else: it's absent from their list, and they can't use it even if they know its id.
 
-To make a connection private, set **Visibility** under **Edit**. To share a private connection with the workspace, use **Share with workspace** on its row menu. Only a **Developer** who created the connection can share it.
+To make a connection private, set **Visibility** under **Edit**. To share a private connection with the workspace, use **Share with workspace** on its row menu. Only an **Admin** who created the connection can share it.
 
 ## Related
 
diff --git a/src/content/docs/docs/platform/settings/connections/manage-connections.mdx b/src/content/docs/docs/platform/settings/connections/manage-connections.mdx
index 4981f828..b1acb273 100644
--- a/src/content/docs/docs/platform/settings/connections/manage-connections.mdx
+++ b/src/content/docs/docs/platform/settings/connections/manage-connections.mdx
@@ -6,7 +6,7 @@ sidebar:
   order: 4
 ---
 
-Every action here is on the row menu in **Settings → Connections**. They need the **Developer** role, except on a private connection you created for the Assistant, as [Who can manage a connection](#who-can-manage-a-connection) explains. A row that needs attention also has its fix beside its status: **Authorize**, **Reconnect**, or **Edit**.
+Every action here is on the row menu in **Settings → Connections**. They need the **Admin** role, except on a private connection you created for the Assistant, as [Who can manage a connection](#who-can-manage-a-connection) explains. A row that needs attention also has its fix beside its status: **Authorize**, **Reconnect**, or **Edit**.
 
 ## Edit
 
@@ -75,11 +75,11 @@ When nothing uses the connection, deleting asks for confirmation, and you can't
 
 ## Who can manage a connection
 
-A **workspace** connection belongs to the workspace, so anyone with the **Developer** role can edit, rotate, or delete it, and it keeps working after the person who connected it leaves.
+A **workspace** connection belongs to the workspace, so anyone with the **Admin** role can edit, rotate, or delete it, and it keeps working after the person who connected it leaves.
 
 Only the creator can edit or rotate a **private** connection. An organization **Owner** can still delete one, so a workspace isn't stuck when someone leaves.
 
-You don't need the **Developer** role to manage a private connection you created that's used only for **AI**, such as your own GitHub token for the Assistant. You can edit, re-check, reconnect, and delete it. Sharing it with the workspace, or adding another capability, needs the **Developer** role.
+You don't need the **Admin** role to manage a private connection you created that's used only for **AI**, such as your own GitHub token for the Assistant. You can edit, re-check, reconnect, and delete it. Sharing it with the workspace, or adding another capability, needs the **Admin** role.
 
 When someone leaves the organization or the workspace, their workspace connections keep working and lose their owner. KloudMate deletes their private connections.
 
diff --git a/src/content/docs/docs/platform/settings/connections/zoom.mdx b/src/content/docs/docs/platform/settings/connections/zoom.mdx
index 0569f93e..b2c5188c 100644
--- a/src/content/docs/docs/platform/settings/connections/zoom.mdx
+++ b/src/content/docs/docs/platform/settings/connections/zoom.mdx
@@ -15,7 +15,7 @@ Every meeting is hosted by the Zoom user who installs the app. KloudMate uses th
 ## Before you start
 
 - Your KloudMate plan includes Incident Management.
-- You have the **Developer** role in the KloudMate workspace.
+- You have the **Admin** role in the KloudMate workspace.
 - War rooms are set up for Slack or Microsoft Teams. See [Set up war rooms](/incident-management/war-rooms/setup/).
 - You have a **Licensed** Zoom account to install the app from. Zoom ends meetings hosted by a Basic (free) account after 40 minutes, which would cut an incident call off partway through. Use a shared account such as `incidents@example.com` rather than a person's account, so war room meetings don't depend on one person's Zoom user.
 
diff --git a/src/content/docs/docs/platform/settings/data-sources.mdx b/src/content/docs/docs/platform/settings/data-sources.mdx
index ad795208..048bfa00 100644
--- a/src/content/docs/docs/platform/settings/data-sources.mdx
+++ b/src/content/docs/docs/platform/settings/data-sources.mdx
@@ -50,7 +50,7 @@ Click **Edit** to open **Edit Account Details**.
 
 Sync Settings control what KloudMate inventories for a connected account. Open an account's menu and choose **Sync settings**.
 
-Two account-level controls decide what gets synced: **Primary regions** and an optional **tag allowlist**. The set of resource types KloudMate inventories is platform-managed and the same for every account. See [Covered services](#covered-services). The **Region sync status** section on the same page surfaces any regions that have stopped syncing, and with the **Developer** role you can turn them back on.
+**Primary regions** and an optional **tag allowlist** decide what gets synced for an account. The set of resource types KloudMate inventories is platform-managed and the same for every account. See [Covered services](#covered-services). The **Region sync status** section on the same page surfaces any regions that have stopped syncing, and with the **Admin** role you can turn them back on.
 
 ![The Sync Settings page, showing Region sync status, Primary regions, Tag Filtering, and Covered services](./images/data-sources-3.png)
 
@@ -69,7 +69,7 @@ For each region, the panel shows why it stopped:
 - If a permission error disabled it, the recorded reason appears, for example an `AccessDenied` message naming the missing permission.
 - If it was turned off some other way, it shows **Disabled. No recent error recorded.**
 
-With the **Developer** role, you can select **Re-enable** on a region. That turns the region back on, clears its stored error, and starts a sync right away, so its resources return without waiting for the next cycle. With the **Viewer** role, you can see the status but can't re-enable a region.
+With the **Admin** role, you can select **Re-enable** on a region. That turns the region back on, clears its stored error, and starts a sync right away, so its resources return without waiting for the next cycle. With the **Developer** role, you can see the status but can't re-enable a region.
 
 Most permission problems recover on their own once you fix the underlying access. To find the cause and confirm the fix, see [Troubleshoot AWS sync](../troubleshoot-aws-sync/).
 
diff --git a/src/content/docs/docs/platform/settings/deleting-your-aws-account-from-kloudmate.mdx b/src/content/docs/docs/platform/settings/deleting-your-aws-account-from-kloudmate.mdx
index 98bc92a7..dc37547a 100644
--- a/src/content/docs/docs/platform/settings/deleting-your-aws-account-from-kloudmate.mdx
+++ b/src/content/docs/docs/platform/settings/deleting-your-aws-account-from-kloudmate.mdx
@@ -8,7 +8,7 @@ sidebar:
 
 Use this workflow when you want to disconnect an AWS account from KloudMate and clean up the integration resources in AWS.
 
-- Only users with **Owner** permissions can remove connected AWS accounts.
+- You need the **Admin** role in the workspace to remove a connected AWS account.
 - AWS accounts can always be removed cleanly, even after permissions change on the AWS side.
 
 ## Remove the AWS Account from KloudMate
diff --git a/src/content/docs/docs/platform/settings/images/data-sources-1.png b/src/content/docs/docs/platform/settings/images/data-sources-1.png
index a25db4e4..ac6ce2e0 100644
Binary files a/src/content/docs/docs/platform/settings/images/data-sources-1.png and b/src/content/docs/docs/platform/settings/images/data-sources-1.png differ
diff --git a/src/content/docs/docs/platform/settings/index.mdx b/src/content/docs/docs/platform/settings/index.mdx
index b4c33da1..f45047ab 100644
--- a/src/content/docs/docs/platform/settings/index.mdx
+++ b/src/content/docs/docs/platform/settings/index.mdx
@@ -12,7 +12,8 @@ The Settings area is where you manage workspaces, users, security, billing, and
 - [Organization](./organization/)
 - [Workspaces](./workspaces/)
 - [API Keys](./api-keys/)
-- [Users & Permissions](./users-permissions/)
+- [Users](./users-permissions/)
+- [Roles & Permissions](./roles/)
 - [Single Sign-On (SSO)](./sso/)
 - [Profile & Security](./profile-security/)
 - [Data Sources](./data-sources/)
diff --git a/src/content/docs/docs/platform/settings/notification-channels.mdx b/src/content/docs/docs/platform/settings/notification-channels.mdx
index e93c46e1..f1389ce1 100644
--- a/src/content/docs/docs/platform/settings/notification-channels.mdx
+++ b/src/content/docs/docs/platform/settings/notification-channels.mdx
@@ -87,7 +87,7 @@ Teams channels come from a team connected through the KloudMate app. Connect the
 
 ![image](./images/webhooks-1.png)
 
-KloudMate generates a secret for the channel and uses it to sign every request with an HMAC-SHA256 signature, so you can verify that a request came from KloudMate. With the **Developer** role, you can copy the secret from the channel list with **Copy Secret**.
+KloudMate generates a secret for the channel and uses it to sign every request with an HMAC-SHA256 signature, so you can verify that a request came from KloudMate. With the **Admin** role, you can copy the secret from the channel list with **Copy Secret**.
 
 A webhook channel also sends alerts to a [workflow](../../../workflows/). Set the channel's URL to the workflow's webhook URL, then add the channel to a routing rule. Each notification then starts a run, with the alert group payload as the request body. See [Triggers](../../../workflows/triggers/#start-a-workflow-from-an-alert).
 
diff --git a/src/content/docs/docs/platform/settings/organization.mdx b/src/content/docs/docs/platform/settings/organization.mdx
index 07991029..22595dd7 100644
--- a/src/content/docs/docs/platform/settings/organization.mdx
+++ b/src/content/docs/docs/platform/settings/organization.mdx
@@ -71,5 +71,6 @@ Use **Leave organization** in the **Danger Zone**. Leaving removes your access t
 ## Related
 
 - [Workspaces](../workspaces/)
-- [Users & Permissions](../users-permissions/)
+- [Users](../users-permissions/)
+- [Roles and permissions](../roles/)
 - [Profile & Security](../profile-security/)
diff --git a/src/content/docs/docs/platform/settings/roles/_meta.json b/src/content/docs/docs/platform/settings/roles/_meta.json
new file mode 100644
index 00000000..b7744db0
--- /dev/null
+++ b/src/content/docs/docs/platform/settings/roles/_meta.json
@@ -0,0 +1,4 @@
+{
+  "label": "Roles & Permissions",
+  "order": 3.5
+}
diff --git a/src/content/docs/docs/platform/settings/roles/custom-roles.mdx b/src/content/docs/docs/platform/settings/roles/custom-roles.mdx
new file mode 100644
index 00000000..39674c3d
--- /dev/null
+++ b/src/content/docs/docs/platform/settings/roles/custom-roles.mdx
@@ -0,0 +1,77 @@
+---
+title: "Custom roles"
+description: "Create a workspace role with the permissions a job needs, start from a template, and give it to members in any workspace."
+sidebar:
+  label: "Custom roles"
+  order: 2
+---
+
+import { Steps } from '@astrojs/starlight/components';
+
+A custom role gives a person the permissions their job needs and nothing more. For example, an on-call engineer can acknowledge and resolve incidents without the right to change alert rules or escalation policies. You create the role once for the organization, then give it to members in any workspace.
+
+## Before you start
+
+- Your organization needs a paid plan. The built-in roles work on every plan.
+- Only an organization **Owner** can create, edit, or delete custom roles.
+
+## What a custom role can include
+
+A custom role decides what a person can change, run, or share. It doesn't hide data:
+
+- Every custom role has **Read** on every module except **Workspace settings**. You can't remove it.
+- **Workspace settings** and **AI Assistant** are optional. Without **Workspace settings**, the person doesn't see the workspace settings pages. Without **AI Assistant**, they can't use the Assistant.
+- A custom role holds workspace permissions only. Organization tasks, such as inviting users or managing billing, stay with Owners.
+
+For what each permission lets a person do, see the [permission reference](../permission-reference/).
+
+## Create a custom role
+
+<Steps>
+
+1. Open **Settings → Roles**.
+
+   ![The Roles page, with the built-in roles and the organization's custom roles](./images/roles-list.png)
+
+2. Click **Create role**, then select **Blank role** or a template.
+
+   ![The Create role menu, with Blank role and the Responder, Incident manager, and Platform admin templates](./images/create-role-menu.png)
+
+3. Enter a **Name**, and optionally a **Description**. Each role in the organization needs its own name.
+
+4. Under **Permissions**, tick a module to give all of its permissions. To give single permissions, open the module and tick each one.
+
+   ![A new role with a name and description, and the Dashboards module open to show its permissions](./images/new-role.png)
+
+5. Click **Create role**.
+
+</Steps>
+
+Every **Workspace settings** permission comes with **Read**, and every **AI Assistant** permission comes with **Use**.
+
+## Start from a template
+
+A template is a custom role with permissions already picked for a common job. Select it from **Create role**, then change the name or the permissions before you save. For read-only access, give the built-in **Viewer** role instead.
+
+| Template | For | Permissions added to Read |
+| --- | --- | --- |
+| **Responder** | On-call engineers who handle alerts and incidents | **Operate** on Alerts, Issues, Incidents, Synthetic monitoring, and Workflows. AI Assistant **Use** and **Investigate**. |
+| **Incident manager** | People who run the incident process and talk to customers | **Operate** on Alerts, Issues, Synthetic monitoring, and Workflows. Incidents **Operate** and **Configure**. Status pages **Post** and **Manage**. AI Assistant **Use** and **Investigate**. |
+| **Platform admin** | The team that runs data collection and integrations | Dashboards **Manage**. Logs **Rehydrate**. AI Assistant **Use** and **Investigate**. Every **Workspace settings** permission. |
+
+## Give a custom role to a member
+
+You give a custom role the same way as a built-in role: when you [invite a user](../../users-permissions/#invite-a-user) or [change a user's roles](../../users-permissions/#change-a-users-roles). You can also make a custom role the [default for single sign-on](../../sso/provisioning-and-enforcement/#choose-the-roles-for-new-accounts).
+
+## Edit or delete a custom role
+
+On **Settings → Roles**, open the actions menu on the role's row:
+
+- **Edit**: after you click **Save**, the change applies to every member with the role, in every workspace.
+- **Delete**: the role is removed from every workspace. You can't delete a role that a member still has. Give them another role on [**Settings → Users**](../../users-permissions/) first.
+
+## If your plan no longer includes custom roles
+
+- Members with a custom role get **Viewer** access in that workspace.
+- You can't create or edit custom roles, or give one to another member. A member keeps a custom role they already have, and you can still delete a role.
+- When the plan includes custom roles again, each role applies again with its saved permissions.
diff --git a/src/content/docs/docs/platform/settings/roles/images/create-role-menu.png b/src/content/docs/docs/platform/settings/roles/images/create-role-menu.png
new file mode 100644
index 00000000..b124333f
Binary files /dev/null and b/src/content/docs/docs/platform/settings/roles/images/create-role-menu.png differ
diff --git a/src/content/docs/docs/platform/settings/roles/images/new-role.png b/src/content/docs/docs/platform/settings/roles/images/new-role.png
new file mode 100644
index 00000000..41d0d811
Binary files /dev/null and b/src/content/docs/docs/platform/settings/roles/images/new-role.png differ
diff --git a/src/content/docs/docs/platform/settings/roles/images/roles-list.png b/src/content/docs/docs/platform/settings/roles/images/roles-list.png
new file mode 100644
index 00000000..74bc4564
Binary files /dev/null and b/src/content/docs/docs/platform/settings/roles/images/roles-list.png differ
diff --git a/src/content/docs/docs/platform/settings/roles/index.mdx b/src/content/docs/docs/platform/settings/roles/index.mdx
new file mode 100644
index 00000000..c9e45d44
--- /dev/null
+++ b/src/content/docs/docs/platform/settings/roles/index.mdx
@@ -0,0 +1,100 @@
+---
+title: "Roles and permissions"
+description: "How organization roles and workspace roles decide what each person can see and change in KloudMate."
+sidebar:
+  label: "Overview"
+  order: 1
+---
+
+Roles decide what each person can do in KloudMate. Every member of your organization has an organization role, and a role in each workspace they can open. An Owner assigns both from [**Settings → Users**](../users-permissions/).
+
+## How access works
+
+- The **organization role** is **Owner** or **User**. It decides who manages the organization: its users, workspaces, billing, and sign-in settings.
+- The **workspace role** is **Admin**, **Developer**, **Viewer**, or a [custom role](./custom-roles/). It decides what you can change in that workspace. You can have a different role in each workspace.
+
+An Owner is an Admin in every workspace. A User sees only the workspaces where they have a role.
+
+The workspace is the boundary for data. Everyone with a role in a workspace sees all of that workspace's data, and there's no filter that limits a team to part of it. If a team must see only its own data, give that team its own [workspace](../workspaces/).
+
+## Workspace roles
+
+- **Admin**: Can view and change everything in the workspace.
+- **Developer**: Can view, build and run monitoring, but can't change workspace settings.
+- **Viewer**: Can view, but can't change anything.
+
+Every role can see everything in the workspace, except the workspace settings pages, which a Viewer doesn't see. The roles differ in what you can change, run, or share. Every role can also do its own work in a module without changing it for anyone else. For example, every role can comment on issues, add notes to incidents, star dashboards, save their own queries, and chat with the AI Assistant.
+
+| Module | Viewer | Developer | Admin |
+| --- | --- | --- | --- |
+| Dashboards | Read | Read, Manage | Read, Manage, Share |
+| Reports | Read | Read, Manage | Read, Manage |
+| Alerts | Read | Read, Operate, Configure | Read, Operate, Configure |
+| Issues | Read | Read, Operate, Configure | Read, Operate, Configure |
+| Incidents | Read | Read, Operate, Configure | Read, Operate, Configure |
+| Status pages | Read | Read, Post | Read, Post, Manage |
+| Reliability | Read | Read, Configure | Read, Configure |
+| Synthetic monitoring | Read | Read, Operate, Configure | Read, Operate, Configure |
+| Workflows | Read | Read, Operate, Configure | Read, Operate, Configure, Secrets |
+| AI Assistant | Use, Investigate | Use, Investigate, Configure | Use, Investigate, Configure |
+| Metrics | Read | Read | Read |
+| Traces | Read | Read | Read |
+| Logs | Read | Read | Read, Rehydrate |
+| Real User Monitoring | Read | Read, Configure | Read, Configure |
+| Workspace settings | No access | Read | Every permission |
+
+A Developer builds and runs monitoring: alert rules, incidents, SLOs, monitors, workflows, dashboards, and reports. These tasks need the **Admin** role:
+
+- Change workspace settings.
+- Turn on a public link for a dashboard.
+- Create or brand a status page.
+- Manage secret workflow variables.
+- Rehydrate logs from cold storage.
+
+For what each permission lets you do, see the [permission reference](./permission-reference/).
+
+## Organization roles
+
+- **Owner**: Can do everything in every workspace, including billing. Owners invite users, change roles, create workspaces, set up single sign-on, and create custom roles.
+- **User**: Can see the organization's profile, the member list, usage, credits, and the subscription. What a User can do in a workspace comes from their workspace role.
+
+These rules apply whenever roles change:
+
+- Only an Owner can make someone an Owner, change an Owner's role, or remove an Owner.
+- An organization always has at least one Owner. To change the role of the only Owner, make another member an Owner first.
+- Nobody can change their own roles. Ask another Owner.
+
+### Billing
+
+Every member can see the plan, usage, and credits on [**Subscription & Billing**](../subscription-billing/) and [**Usage Report**](../usage-report/). Only an Owner can see invoices, change the plan, payment method, or billing details, buy credits, or change **Overage Control**.
+
+## Plan limits
+
+Your plan decides which modules your organization can use. If the plan doesn't include a module, the module is closed for everyone in the organization, Owners included. Its pages show an upgrade screen instead of your data, whatever role you have.
+
+These modules and features depend on the plan:
+
+- Incidents, Reliability, Synthetic monitoring, Workflows, and the AI Assistant
+- Smart Alerts, code profiling, and Cold Storage
+- Single sign-on and custom roles
+- Custom domains and branding removal for status pages
+- Access to the AI Assistant from your own AI client through the [MCP server](../../../kloudmate-assistant/mcp-server/)
+
+When a module closes, its background work stops too. Synthetic monitors don't run, SLOs aren't evaluated, workflows don't start from any trigger, and alert sources don't open new incidents. A workflow run that already started runs to the end.
+
+Your data stays. When the plan includes the module again, your data and the background work come back.
+
+:::caution
+Some alert sources turn off a webhook after it's refused many times. After you upgrade, check that your alert sources still send to KloudMate.
+:::
+
+## API keys and AI clients
+
+A [personal API key](../api-keys/#personal-api-keys), an MCP client, or an app that you approve acts as you. It gets your permissions in each workspace, and nothing more.
+
+## Next steps
+
+- [Invite users and assign roles](../users-permissions/)
+- [Create a custom role](./custom-roles/)
+- [Look up a permission](./permission-reference/)
+- [See what changed for existing users](./whats-changed/)
diff --git a/src/content/docs/docs/platform/settings/roles/permission-reference.mdx b/src/content/docs/docs/platform/settings/roles/permission-reference.mdx
new file mode 100644
index 00000000..be876120
--- /dev/null
+++ b/src/content/docs/docs/platform/settings/roles/permission-reference.mdx
@@ -0,0 +1,149 @@
+---
+title: "Permission reference"
+description: "Every permission in KloudMate, by module, with what it lets a person do and which built-in roles have it."
+sidebar:
+  label: "Permission reference"
+  order: 3
+---
+
+A permission lets a person do one kind of task in one module, and a role is a set of permissions. An Owner has every permission in every workspace. For a summary by role, see [Workspace roles](../#workspace-roles).
+
+**Read** is part of every role, built-in or custom, on every module except **Workspace settings**. A [custom role](../custom-roles/) can add any other permission on this page.
+
+A permission works only when your plan includes its module or feature. See [Plan limits](../#plan-limits).
+
+## Workspace permissions
+
+### Dashboards
+
+| Permission | What it lets you do | Built-in roles |
+| --- | --- | --- |
+| **Read** | See dashboards and folders, star them, and email yourself an export. | All roles |
+| **Manage** | Create, import, edit, and delete dashboards and folders. Save a panel from Explore to a dashboard. | Developer, Admin |
+| **Share** | Turn on, change, regenerate, or turn off a dashboard's public link. Anyone with the link sees every panel with the workspace's data. | Admin |
+
+### Reports
+
+| Permission | What it lets you do | Built-in roles |
+| --- | --- | --- |
+| **Read** | See reports and generated reports, and download them. | All roles |
+| **Manage** | Create, edit, and delete scheduled reports. Send a report now. | Developer, Admin |
+
+### Alerts
+
+| Permission | What it lets you do | Built-in roles |
+| --- | --- | --- |
+| **Read** | See alerts, alert rules, history, routing rules, silences, and maintenance windows. Give feedback on how alerts are grouped, and export rules as JSON. | All roles |
+| **Operate** | Create or end a silence. Pause or resume an alert rule. Dismiss an instance that stopped reporting. Manage maintenance windows. Create or unlink a Jira ticket. | Developer, Admin |
+| **Configure** | Create, copy, import, test, edit, move, and delete alert rules. Manage folders and routing rules, and get AI suggestions for routing. Set up Smart Alerts. | Developer, Admin |
+
+To turn on automatic root cause analysis in a routing rule, you also need AI Assistant **Investigate**.
+
+### Issues
+
+| Permission | What it lets you do | Built-in roles |
+| --- | --- | --- |
+| **Read** | See issues. Comment, mention people, and watch an issue. | All roles |
+| **Operate** | Resolve, reopen, ignore, and stop ignoring issues. Assign people. Create or unlink a Jira ticket. | Developer, Admin |
+| **Configure** | Create, edit, turn on or off, and delete issue notification policies. | Developer, Admin |
+
+### Incidents
+
+| Permission | What it lets you do | Built-in roles |
+| --- | --- | --- |
+| **Read** | See incidents, services, and on-call schedules. Add notes to an incident. | All roles |
+| **Operate** | Create an incident. Acknowledge, resolve, or reopen an incident, also from Slack, Microsoft Teams, or a voice call. Change the severity or summary. Add or remove responders. Start or archive a war room. Add or remove on-call overrides. | Developer, Admin |
+| **Configure** | Manage services, alert sources, escalation policies, on-call schedules, and incident routing rules, and test a routing rule. Change the war room settings. Install Slack ChatOps. | Developer, Admin |
+
+### Status pages
+
+| Permission | What it lets you do | Built-in roles |
+| --- | --- | --- |
+| **Read** | See status pages, their components, incidents, and updates. | All roles |
+| **Post** | Publish an incident to a status page. Create, edit, and delete status page incidents, and post updates for customers. | Developer, Admin |
+| **Manage** | Create, edit, brand, publish, unpublish, and delete status pages and their components. Set up, verify, or remove a custom domain. | Admin |
+
+### Reliability
+
+| Permission | What it lets you do | Built-in roles |
+| --- | --- | --- |
+| **Read** | See SLOs and preview them. | All roles |
+| **Configure** | Create, edit, and delete SLOs and burn-rate alerts. Preview an SLO before you save it. | Developer, Admin |
+
+### Synthetic monitoring
+
+| Permission | What it lets you do | Built-in roles |
+| --- | --- | --- |
+| **Read** | See monitors and their results. | All roles |
+| **Operate** | Pause or resume a monitor. Manage maintenance windows for monitors. | Developer, Admin |
+| **Configure** | Create, edit, and delete monitors. Run a test check. | Developer, Admin |
+
+### Workflows
+
+| Permission | What it lets you do | Built-in roles |
+| --- | --- | --- |
+| **Read** | See workflows, runs, versions, templates, and storage. Run, test-run, retrigger, or cancel a workflow that allows runs by anyone in the workspace. | All roles |
+| **Operate** | Run, test-run, retrigger, or cancel any workflow. | Developer, Admin |
+| **Configure** | Create, import, edit, publish, turn on or off, export, and delete workflows, and restore an earlier version. See or rotate webhook and form URLs. Use the builder's test tools. Manage storage and variables that aren't secret. Use a secret variable in a step without seeing its value. | Developer, Admin |
+| **Secrets** | Create, rotate, reveal, and delete secret variables. **Reveal value** shows the value only to the person who created the secret, or to an Owner. | Admin |
+
+### AI Assistant
+
+| Permission | What it lets you do | Built-in roles |
+| --- | --- | --- |
+| **Use** | Chat with the assistant and approve its tool calls. Keep your own private prompts, skills, and tool servers. Connect your own AI client over MCP. | All roles |
+| **Investigate** | Start an investigation, or run a root cause analysis on an alert group or from an incident. These use AI credits. | All roles |
+| **Configure** | Share a skill with the workspace, or edit a shared skill. Choose which tools of a shared tool server are on, and which ones need approval. | Developer, Admin |
+
+### Metrics
+
+| Permission | What it lets you do | Built-in roles |
+| --- | --- | --- |
+| **Read** | See metrics and inventory on every screen, including hosts, Kubernetes, serverless, network monitoring, and the metrics in APM and Databases. | All roles |
+
+### Traces
+
+| Permission | What it lets you do | Built-in roles |
+| --- | --- | --- |
+| **Read** | See traces and profiles on every screen. Save trace queries. | All roles |
+
+### Logs
+
+| Permission | What it lets you do | Built-in roles |
+| --- | --- | --- |
+| **Read** | See logs on every screen. Save log queries and folders. See a cloud account's CloudWatch log groups. | All roles |
+| **Rehydrate** | Estimate, start, cancel, or remove a rehydration from cold storage. A rehydration costs money. | Admin |
+
+### Real User Monitoring
+
+| Permission | What it lets you do | Built-in roles |
+| --- | --- | --- |
+| **Read** | See sessions, session replays, and journeys. Save segments. | All roles |
+| **Configure** | Manage funnels and page groups. Delete an uploaded source map. | Developer, Admin |
+
+### Workspace settings
+
+| Permission | What it lets you do | Built-in roles |
+| --- | --- | --- |
+| **Read** | See the workspace's settings pages. | Developer, Admin |
+| **Data sources** | Connect, set up, and remove cloud accounts. Change what they sync, their regions, and their tags. Manage CloudWatch log groups. Sync inventory now. Ignore a Lambda function. | Admin |
+| **Agents** | Configure agents and their integrations. Preview logs. Upgrade, restart, and remove agents. Allow or block runbook scripts on a host. Manage ingest pipelines. | Admin |
+| **Ingest keys** | Create, edit, and revoke any ingest key in the workspace. | Admin |
+| **Notification channels** | Create, edit, and delete notification channels. Set up the KloudMate app for Microsoft Teams. Preview a webhook body. See a channel's address, secret, and settings, such as webhook headers. | Admin |
+| **Connections** | Create, edit, re-check, share, rotate, and delete shared connections. Share a tool server with the workspace. | Admin |
+| **Cold storage** | Connect, verify, turn on or off, replace, and delete cold storage destinations. | Admin |
+
+Without **Notification channels**, you still see each channel's name and type, and the Slack channel or Jira project it posts to.
+
+## Organization permissions
+
+Organization permissions come with the organization role. A custom role can't include them.
+
+| Task | Owner | User |
+| --- | :---: | :---: |
+| See the organization's profile, your workspaces, the member list, usage, credits, and the subscription | ✓ | ✓ |
+| Edit the organization's name and time zone | ✓ | |
+| Require multi-factor authentication, and set up single sign-on and its domains | ✓ | |
+| Create, rename, and delete workspaces | ✓ | |
+| Invite users, change their roles, and remove them. Create, edit, and delete custom roles. | ✓ | |
+| Change the plan, payment method, and billing details. Buy credits and change **Overage Control**. See invoices. | ✓ | |
diff --git a/src/content/docs/docs/platform/settings/roles/whats-changed.mdx b/src/content/docs/docs/platform/settings/roles/whats-changed.mdx
new file mode 100644
index 00000000..69c4d065
--- /dev/null
+++ b/src/content/docs/docs/platform/settings/roles/whats-changed.mdx
@@ -0,0 +1,46 @@
+---
+title: "What changed for existing users"
+description: "How the new workspace roles, custom roles, and plan limits change access for organizations that used KloudMate before."
+sidebar:
+  label: "What changed"
+  order: 4
+---
+
+If your organization used KloudMate before this release, Viewers can now do less, and some tasks moved between roles. Nobody who had the old Developer role loses access.
+
+## Roles
+
+- The role that was called **Developer** is now called **Admin**. Members who had it keep all of their access.
+- A new **Developer** role builds and runs monitoring. A Developer can't change workspace settings, turn on public links for dashboards, create or brand status pages, manage secret workflow variables, or rehydrate logs.
+- On a paid plan, Owners can create [custom roles](../custom-roles/), and start from a template.
+- Owners and Viewers keep their roles.
+
+## What a Viewer can no longer do
+
+- Assign issues, open Jira tickets, or start, change, or archive a war room.
+- Test or preview a draft alert rule, or ask for routing suggestions.
+- Test a synthetic monitor or an incident routing rule, or preview a draft on-call schedule.
+- Send a report to its recipients.
+- Use a workflow builder's test tools, or see a workflow's webhook or form URL.
+- Cancel a run of a workflow that doesn't allow runs by anyone in the workspace.
+- See the workspace settings pages.
+- Acknowledge or resolve an incident, or undo either, from Slack, Microsoft Teams, or a voice call.
+
+To give a Viewer some of these tasks back, give them the **Developer** role, or a [custom role](../custom-roles/) such as the **Responder** template.
+
+## Tasks that moved from Owners to Admins
+
+These tasks needed an Owner before. Now every Admin can do them, and a custom role can include them in one workspace:
+
+- Connect cloud accounts.
+- Set up cold storage destinations.
+- Set up a custom domain for a status page.
+
+## Other changes
+
+- An Admin can edit and revoke any ingest key in the workspace. Before, only the person who created a key could.
+- Only the author of a saved query can edit it. Before, any member could.
+- If your plan doesn't include a module or feature, it's closed for everyone, its data included, and its background work stops. See [Plan limits](../#plan-limits).
+- Any role with AI Assistant **Use** can create a private skill. Before, only an Admin could.
+- Only an Admin can see a notification channel's address, secret, and settings, such as a webhook's custom headers, or preview a webhook body. Everyone still sees each channel's name and type, and the Slack channel or Jira project it posts to.
+- Only Owners can see invoices. Every member can still see usage, credits, and the subscription.
diff --git a/src/content/docs/docs/platform/settings/sso/index.mdx b/src/content/docs/docs/platform/settings/sso/index.mdx
index d1f399f4..e7561c3c 100644
--- a/src/content/docs/docs/platform/settings/sso/index.mdx
+++ b/src/content/docs/docs/platform/settings/sso/index.mdx
@@ -107,6 +107,7 @@ Secrets are write-only: when you edit, the client secret and signing certificate
 
 ## Related
 
-- [Users & Permissions](../users-permissions/)
+- [Users](../users-permissions/)
+- [Roles and permissions](../roles/)
 - [Profile & Security](../profile-security/)
 - [Subscription & Billing](../subscription-billing/)
diff --git a/src/content/docs/docs/platform/settings/sso/provisioning-and-enforcement.mdx b/src/content/docs/docs/platform/settings/sso/provisioning-and-enforcement.mdx
index 76e60fc3..cd4801da 100644
--- a/src/content/docs/docs/platform/settings/sso/provisioning-and-enforcement.mdx
+++ b/src/content/docs/docs/platform/settings/sso/provisioning-and-enforcement.mdx
@@ -10,7 +10,7 @@ Two settings decide who can sign in through SSO and how their accounts come to e
 
 ## Choose a provisioning mode
 
-In the **User provisioning** card on **Settings → Single Sign-On**, pick one of two modes. The setting takes effect as soon as you select it.
+In the **User provisioning** card on **Settings → Single Sign-On**, pick a mode, then click **Save**.
 
 - **Invite only** *(default)* — only people you've already invited to the organization can sign in through your IdP. Authenticating with the IdP isn't enough on its own; the person also has to have a KloudMate invite.
 - **Just-in-time (JIT)** — KloudMate creates an account the first time someone signs in through your IdP. Anyone your IdP lets through becomes a member automatically, without a separate invite.
@@ -24,9 +24,14 @@ In the **User provisioning** card on **Settings → Single Sign-On**, pick one o
 
 You can switch modes at any time. Switching to JIT doesn't retroactively add anyone — accounts are created as people sign in.
 
-:::note
-JIT adds the person to your **organization**, but it doesn't grant any **workspace** access. Until you assign their workspace permissions, they can sign in but won't see any workspace. As the owner, give them access from [Users & Permissions](../../users-permissions/).
-:::
+### Choose the roles for new accounts
+
+With **Just-in-time (JIT)**, you pick the roles that each new account gets, under **Assign auto-provisioned users role and permissions**:
+
+- Select **Owner** or **User** as the organization role.
+- For **User**, pick a role in each workspace: **Admin**, **Developer**, **Viewer**, or one of your [custom roles](../../roles/custom-roles/). Pick a role in at least one workspace, or you can't save.
+
+To change a person's roles after their first sign-in, edit them on [**Settings → Users**](../../users-permissions/#change-a-users-roles). See [Roles and permissions](../../roles/) for what each role can do.
 
 ## How enforcement works
 
@@ -44,5 +49,6 @@ Before you rely on enforcement, confirm you can complete a full SSO sign-in with
 
 - [SSO overview & setup](../)
 - [Verify your company domain](../domain-verification/)
-- [Users & Permissions](../../users-permissions/)
+- [Users](../../users-permissions/)
+- [Roles and permissions](../../roles/)
 - [Troubleshooting](../troubleshooting/)
diff --git a/src/content/docs/docs/platform/settings/subscription-billing.mdx b/src/content/docs/docs/platform/settings/subscription-billing.mdx
index 69235161..69b6e054 100644
--- a/src/content/docs/docs/platform/settings/subscription-billing.mdx
+++ b/src/content/docs/docs/platform/settings/subscription-billing.mdx
@@ -16,11 +16,15 @@ This page includes:
 
 ![image](./images/subscription-_-billing-1.png)
 
-Organization owners can:
+Every member of the organization can see the plan, usage, and purchased credits. Only an Owner can:
 
+- See invoices
 - Change the subscription plan
 - Add or remove payment methods
 - Update billing contact or billing address information
+- Buy credits or change **Overage Control**
+
+See [Roles and permissions](../roles/#billing).
 
 ## Control Overage Costs
 
diff --git a/src/content/docs/docs/platform/settings/users-permissions.mdx b/src/content/docs/docs/platform/settings/users-permissions.mdx
index 3d9ee9e1..a2234611 100644
--- a/src/content/docs/docs/platform/settings/users-permissions.mdx
+++ b/src/content/docs/docs/platform/settings/users-permissions.mdx
@@ -1,26 +1,76 @@
 ---
-title: "Users & Permissions"
-description: "Invite users and manage access levels across KloudMate workspaces."
+title: "Users"
+description: "Invite people to your organization, give them a role in each workspace, and change or remove their access."
 sidebar:
-  label: "Users & Permissions"
+  label: "Users"
   order: 3
 ---
-User management is available to organization owners. Use this page to invite users, assign workspace permissions, and remove access when needed.
 
-## What You Can Do
+import { Steps } from '@astrojs/starlight/components';
 
-- Add new users
-- Update permissions for existing users
-- Remove users from the organization
+Use **Settings → Users** to invite people to your organization and decide what they can do in each workspace. Every member can see the list of users. Only an Owner can invite, change, or remove users.
 
-## Invite a User
+Each person has an organization role (**Owner** or **User**) and a role in each workspace. For what each role can do, see [Roles and permissions](../roles/).
 
-Open **Settings -> Users** and click **Invite User** or **Add User**.
+## Invite a user
 
-Enter the user's email address and assign the required permissions.
+<Steps>
 
-![image](./images/users-_-permissions-2.png)
+1. Open **Settings → Users** and click **Add User**.
 
-Permissions can be configured separately for each workspace. If no permission is assigned for a workspace, the user will not have access to it.
+2. Enter the person's **Email address**.
 
-![image](./images/users-_-permissions-3.png)
+3. Under **Organization role**, select **Owner** or **User**. An Owner is an Admin in every workspace, so you don't pick workspace roles for an Owner.
+
+4. For a User, pick a role in each workspace they need: **Admin**, **Developer**, **Viewer**, or one of your [custom roles](../roles/custom-roles/). Leave **No access** in the other workspaces. A User needs a role in at least one workspace.
+
+5. Click **Submit**.
+
+</Steps>
+
+The person gets the invitation by email. After they sign in, they can also accept it from **Settings → Pending Invitations**. If your plan doesn't include custom roles, you can't pick one.
+
+## Manage invitations
+
+Invitations that haven't been accepted yet are on the **Invitations** tab. An invitation expires 7 days after you send it.
+
+- To send an invitation again, click **Resend**. This works on an expired invitation too. The person gets the invitation by email again, and it's valid for another 7 days.
+- To change the roles on an invitation, invite the same email address again with the new roles.
+- To cancel an invitation, click its delete icon.
+
+Only an Owner can resend an invitation. You can resend the same invitation once a minute at most.
+
+## Change a user's roles
+
+<Steps>
+
+1. Open **Settings → Users**.
+
+2. Open the actions menu on the user's row and click **Edit**.
+
+3. Change the **Organization role**, or the **Role** in each workspace. Select **No access** to remove the user from a workspace.
+
+4. Click **Save**.
+
+</Steps>
+
+These rules apply to every change:
+
+- Only an Owner can make someone an Owner, change an Owner's role, or remove an Owner.
+- Nobody can change their own roles. Ask another Owner.
+- An organization always has at least one Owner. To change the role of the only Owner, make another member an Owner first.
+
+## Remove a user
+
+Open the actions menu on the user's row, click **Edit**, then click **Remove user from Organization**. The person loses access to the organization and every workspace in it.
+
+## Add users through single sign-on
+
+If your organization uses single sign-on, people can get an account the first time they sign in through your identity provider. You pick the organization role and the workspace roles that those new accounts get. See [Provisioning & enforcement](../sso/provisioning-and-enforcement/).
+
+## Related
+
+- [Roles and permissions](../roles/)
+- [Custom roles](../roles/custom-roles/)
+- [Workspaces](../workspaces/)
+- [Single Sign-On (SSO)](../sso/)
diff --git a/src/content/docs/docs/platform/settings/workspaces.mdx b/src/content/docs/docs/platform/settings/workspaces.mdx
index 19e1903e..40713e23 100644
--- a/src/content/docs/docs/platform/settings/workspaces.mdx
+++ b/src/content/docs/docs/platform/settings/workspaces.mdx
@@ -6,7 +6,7 @@ sidebar:
   order: 2
 ---
 
-Workspaces let you organize data sources, services, and users by environment, team, or ownership boundary.
+Workspaces let you organize data sources, services, and users by environment, team, or ownership boundary. A workspace is also the boundary for access: everyone with a role in a workspace sees all of its data. See [Roles and permissions](../roles/).
 
 ## Manage Workspaces
 
@@ -19,6 +19,8 @@ From this page, you can:
 - Rename a workspace
 - Delete a workspace
 
+Only an Owner can add, rename, or delete a workspace.
+
 ![Workspaces settings page, showing the organization's workspace list, usage against the plan limit, and the Add Workspace button](./images/workspaces-list.png)
 
 ## Create a Workspace
diff --git a/src/content/docs/docs/reports/index.mdx b/src/content/docs/docs/reports/index.mdx
index 1625b91c..ee7fc496 100644
--- a/src/content/docs/docs/reports/index.mdx
+++ b/src/content/docs/docs/reports/index.mdx
@@ -29,7 +29,7 @@ Use the row menu to **Edit** or **Delete** a report.
 
 ## Who can manage reports
 
-You need the **Developer** role in the workspace to create, edit, or delete reports. With the **Viewer** role, you can still open any report, send it now, and download its generated files.
+You need the **Developer** role in the workspace to create, edit, or delete reports. With the **Viewer** role, you can still open any report and download its generated files.
 
 ## Open a report
 
diff --git a/src/content/docs/docs/visualize-data/dashboards/index.mdx b/src/content/docs/docs/visualize-data/dashboards/index.mdx
index f1516163..7233bbb4 100644
--- a/src/content/docs/docs/visualize-data/dashboards/index.mdx
+++ b/src/content/docs/docs/visualize-data/dashboards/index.mdx
@@ -19,7 +19,7 @@ From the more options (⋯) icon on any dashboard or folder, you can **edit**, *
 
 | **Role**      | **Permissions**                                |
 | ------------- | ---------------------------------------------- |
-| **Owner**     | Create, edit, or delete dashboards and folders |
+| **Admin**     | Create, edit, or delete dashboards and folders. Turn a public link on or off. |
 | **Developer** | Create, edit, or delete dashboards and folders |
 | **Viewer**    | View dashboards and folders only |
 
diff --git a/src/content/docs/docs/workflows/actions.mdx b/src/content/docs/docs/workflows/actions.mdx
index 7cabd536..ec12a1ec 100644
--- a/src/content/docs/docs/workflows/actions.mdx
+++ b/src/content/docs/docs/workflows/actions.mdx
@@ -234,7 +234,7 @@ When you test this step on its own, it shows the shape of its output without run
 
 #### Allow runbook scripts on a host
 
-Runbook scripts are off on every host until someone with the **Developer** role allows them, one host at a time:
+Runbook scripts are off on every host until someone with the **Admin** role allows them, one host at a time:
 
 1. Open **Settings → Agents & Pipelines**.
 2. Open the host's actions menu (⋮), select **Configure**, and open the **Runbook Scripts** tab.
diff --git a/src/content/docs/docs/workflows/index.mdx b/src/content/docs/docs/workflows/index.mdx
index 619c1e98..9aed7415 100644
--- a/src/content/docs/docs/workflows/index.mdx
+++ b/src/content/docs/docs/workflows/index.mdx
@@ -15,7 +15,7 @@ A disk-space alert is a good first workflow. It reads the host from the alert an
 ## What a workflow can do
 
 - **Act on cloud resources**: call an AWS API action, such as stopping an EC2 instance, or an Azure Resource Manager operation through a connected account, or run a script on an Azure VM.
-- **Run a command on a host**: use the KloudMate agent to run shell commands on any Linux host where someone with the **Developer** role has [allowed runbook scripts](./actions/#allow-runbook-scripts-on-a-host).
+- **Run a command on a host**: use the KloudMate agent to run shell commands on any Linux host where someone with the **Admin** role has [allowed runbook scripts](./actions/#allow-runbook-scripts-on-a-host).
 - **Work in your tools**: post and edit Slack messages, create and transition Jira issues, call a tool on an MCP server, or send an HTTP request to anything else.
 - **Notify**: send through an existing Slack, Teams, webhook, or SNS channel, or email an address directly.
 - **Transform and decide**: extract a value with JSONPath, parse CSV and XML, run sandboxed JavaScript, choose between several paths by condition, or have a model pull structured fields out of a payload.
diff --git a/src/content/docs/docs/workflows/variables.mdx b/src/content/docs/docs/workflows/variables.mdx
index 2827e283..a2e41822 100644
--- a/src/content/docs/docs/workflows/variables.mdx
+++ b/src/content/docs/docs/workflows/variables.mdx
@@ -8,7 +8,7 @@ sidebar:
 
 Variables hold configuration you set once and reuse across workflows, such as a channel id, a list of regions, or an API token. Open **Workflows → Variables** and click **Add variable**.
 
-Pick **Constant** or **Secret** when you create one. The kind decides how you reference the value, and how KloudMate stores and reads it:
+You need the **Developer** role to manage constants, and the **Admin** role to manage secrets. Pick **Constant** or **Secret** when you create one. The kind decides how you reference the value, and how KloudMate stores and reads it:
 
 |  | Constant | Secret |
 |---|---|---|
@@ -61,7 +61,7 @@ du -xh --max-depth=2 /var | sort -rh | head -{{ vars.report_top_n }}
 
 A secret never enters a workflow definition or run history. KloudMate substitutes it into the step's inputs at the last moment, after everything has been recorded, so run detail shows `secret: stripe_key` where the value would be. If a step's output comes back carrying the secret, KloudMate rewrites it to `••••` before the output is recorded or read downstream, and the step still succeeds.
 
-This keeps the value out of run history and exports, and away from someone looking over your shoulder. It doesn't protect against someone who can edit workflows, because they can send a secret to their own server with an HTTP step. A [connection](/platform/settings/connections/) has the same limit, which is why both need the **Developer** role.
+This keeps the value out of run history and exports, and away from someone looking over your shoulder. It doesn't protect against someone who can edit workflows, because they can send a secret to their own server with an HTTP step. A [connection](/platform/settings/connections/) has the same limit. Anyone with the **Developer** role can use a secret in a step without seeing its value.
 
 KloudMate doesn't mask values shorter than 8 characters in step output, so don't rely on the masking for a short secret.
 
@@ -77,7 +77,7 @@ KloudMate refuses to **Delete** a variable while any workflow still uses it, and
 
 ## Reveal a secret
 
-**Reveal value** shows the plaintext to whoever created the secret, or to an organization **Owner**. Other users with the **Developer** role can't reveal it, even though they can rotate or delete it. KloudMate records each reveal and who made it.
+**Reveal value** needs the **Admin** role, and it shows the plaintext only to whoever created the secret, or to an organization **Owner**. Other Admins can rotate or delete the secret, but can't reveal it.
 
 ## Missing variables