Close docs gaps for repair, AI workflows, and permissions

admin/creating-api-key.mdx

@@ -9,7 +9,7 @@ The Checkly public API and CLI use API keys to authenticate requests. API keys c
 
 ## User API keys
 
-User API keys are tied to one specific user in your account and inherit the access level of that user, i.e. "read only" or "admin".
+User API keys are tied to one specific user in your account and inherit that user's [account role and permissions](/admin/team-management/overview#permissions-and-roles), including [custom roles](/admin/team-management/custom-roles) (beta) when enabled for your account.
 When a user is removed from your account, that user's API keys are no longer able to access your account through the API.
 
 **Steps to create an user API key:** 
@@ -49,15 +49,21 @@ Service API keys allow you to set a role access level on the key itself. Availab
 - **Read & Run** - Can view all resources and trigger checks and tests, but cannot create, edit, or delete. Ideal for CI/CD pipelines that only need to run tests.
 - **Read Only** - View-only access to all resources.
 
+If your account has [custom roles](/admin/team-management/custom-roles) (beta) enabled, you can also select one for a service API key.
+
 Prime use cases for service API keys are:
 
 - Background services like CI pipelines invoke the [Checkly CLI](/cli/overview).
 - Any custom integrations that needs to create, update or delete resources through our public API.
 - Replacing user API keys for customers using our SSO integration and cannot create "service users" in their user directories due to compliance reasons.
 
-**Steps to create a service API key:**
+<Accordion title="Prerequisites">
+You need [**Create API keys** (`api-keys:create`)](/admin/team-management/overview#permissions-and-roles) permission and a plan that includes service API keys. Owner and Admin have this permission by default. If access is missing, ask your account Owner or Admin to assign a suitable role.
 
-Only users with the Admin and Owner role can create service API keys.
+You can only give a key a role whose permissions you hold yourself. The role picker disables roles you cannot give.
+</Accordion>
+
+**Steps to create a service API key:**
 
 1. Go to the API keys section in the [Account Settings](https://app.checklyhq.com/settings/account/api-keys).
 2. Click **Create service API key**.
@@ -74,4 +80,4 @@ curl -H "Authorization: Bearer my_service_api_key" -H "X-Checkly-Account: my_acc
 
 ### Deleting a service API key
 
-Only Admin and Owner users can delete an API key. To delete an API key click on the **Delete** icon in the Service Api Keys section of the [Account Settings](https://app.checklyhq.com/settings/account/api-keys).
+You need [**Delete API keys** (`api-keys:delete`)](/admin/team-management/overview#permissions-and-roles) permission to delete a service API key. Owner and Admin have it by default; a [custom role](/admin/team-management/custom-roles) (beta) can grant it when enabled for your account. Click the **Delete** icon in the Service API Keys section of [Account Settings](https://app.checklyhq.com/settings/account/api-keys). You can revoke an existing key even if your plan no longer includes service API keys.

admin/team-management/custom-roles.mdx

@@ -1,20 +1,20 @@
 ---
 title: "Custom roles"
-description: "Create custom roles with the permissions you pick and give them to members and invitations."
+description: "Beta documentation for creating custom roles and assigning them to members, invitations, and service API keys."
 sidebarTitle: "Custom Roles"
 tag: "Beta"
 canonical: 'https://www.checklyhq.com/docs/admin/team-management/custom-roles/'
 ---
 
 <Note>
-Custom roles are in beta for [Enterprise plans](https://www.checklyhq.com/pricing/). They aren't generally available yet. To take part in the beta, contact your customer success team.
+Custom roles are in beta and are not generally available. This documentation applies only to accounts where custom roles are enabled.
 </Note>
 
-A custom role is a named set of permissions that you pick one by one. Custom roles sit next to the [built-in roles](/admin/team-management/overview#team-member-roles). You give them to members and invitations the same way.
+A custom role is a named set of permissions that you pick one by one. Custom roles sit next to the [built-in roles](/admin/team-management/overview#team-member-roles). You can assign them to members, invitations, and [service API keys](/admin/creating-api-key#service-api-keys).
 
 ## The Roles page
 
-**Account settings > Roles** lists your account's custom roles. It shows once custom roles are turned on for your account. Each row has the role's name and description, how many permissions it grants, and how many members and pending invitations hold it. Click a role's name to open it.
+**Account settings > Roles** lists your account's custom roles. It shows once custom roles are turned on for your account. Each row has the role's name and description, how many permissions it grants, and how many members, pending invitations, and service API keys hold it. Click a role's name to open it.
 
 <Frame>
   <img className="block dark:hidden" src="/images/team-management/custom-roles-list.png" alt="The Roles page with the New role button and a table of custom roles, each showing its name and description, its number of permissions, how many members and invites hold it, and a delete button" />
@@ -26,7 +26,7 @@ A custom role is a named set of permissions that you pick one by one. Custom rol
 | View roles | See the Roles page and open a role to see its permissions | All roles |
 | Create roles | Create custom roles | Owner, Admin |
 | Edit roles | Change a role's name, description and permissions | Owner, Admin |
-| Delete roles | Delete custom roles that no member or invitation holds | Owner, Admin |
+| Delete roles | Delete custom roles and choose a replacement for affected holders | Owner, Admin |
 
 A custom role can hold these permissions too. They're listed under **Roles**.
 
@@ -44,6 +44,8 @@ A custom role can hold these permissions too. They're listed under **Roles**.
 
 ## The permission matrix
 
+The matrix uses permission names such as **Run checks**. If another guide refers to an ID such as `checks:run`, see [Permission names and IDs](/admin/team-management/overview#permissions-and-roles) to find its name, resource row, and how to get access.
+
 <Frame>
   <img className="block dark:hidden" src="/images/team-management/custom-roles-editor.png" alt="The Permissions card of the On-call responder role, with its incident, on-call and alert permissions ticked" />
   <img className="hidden dark:block" src="/images/team-management/custom-roles-editor-dark.png" alt="The Permissions card of the On-call responder role, with its incident, on-call and alert permissions ticked" />
@@ -58,16 +60,16 @@ A custom role can hold these permissions too. They're listed under **Roles**.
 
 ## Edit a role
 
-Click the role's name on the Roles page, make your changes and click **Save role**. The page says how many members and pending invitations hold the role. Changes apply to them right away.
+Click the role's name on the Roles page, make your changes and click **Save role**. The page says how many members, pending invitations, and service API keys hold the role. Changes apply to them right away.
 
 - You can only edit a role when you hold all of its permissions yourself.
 - Without **Edit roles**, the role opens read-only.
 
 ## Delete a role
 
-Click the trash button in the role's row and confirm. Deleting a role can't be undone.
+Click the trash button in the role's row. If the role is assigned, review the affected members, pending invitations, and service API keys, then choose their **Replacement role** before confirming. Their permissions change immediately. Deleting a role can't be undone.
 
-You can only delete a role that no member or pending invitation holds. Until then, the trash button is disabled. Hover it to see how many hold the role. To free the role, [change those members' roles](/admin/team-management/managing-team-members#change-members-roles) and [remove the invitations](/admin/team-management/managing-team-members#pending-invites). An invitation keeps the role it was sent with.
+You must be allowed to assign the replacement to every affected holder. If no suitable replacement is available to you, ask your account owner or an admin to make the change.
 
 ## Give a custom role
 
@@ -87,4 +89,4 @@ The same rules apply as for built-in roles:
 
 ## API keys
 
-[User API keys](/admin/creating-api-key#user-api-keys) act with their member's role. A member with a custom role has the same permissions through the API and the CLI. Changes to the role apply to their keys right away. [Service API keys](/admin/creating-api-key#service-api-keys) take a built-in role.
+[User API keys](/admin/creating-api-key#user-api-keys) act with their member's role. A member with a custom role has the same permissions through the API and the CLI. Changes to the role apply to their keys right away. When the beta is enabled, [service API keys](/admin/creating-api-key#service-api-keys) can also use a custom role whose permissions you hold.

admin/team-management/managing-team-members.mdx

@@ -50,7 +50,7 @@ If your account is managed through the [Vercel native integration](/integrations
 ## Change members' roles
 
 1. Select the members and click **Change role**.
-2. Pick a role: the built-in roles, then any [custom roles](/admin/team-management/custom-roles) (beta). You can type to search the picker. It only offers roles you can give to every member you selected, and shows the description of the one you pick.
+2. Pick a role: the built-in roles, then any [custom roles](/admin/team-management/custom-roles) (beta) enabled for your account. You can type to search the picker. It only offers roles you can give to every member you selected, and shows the description of the one you pick.
 3. Click **Change role**.
 
 <Frame>
@@ -141,4 +141,4 @@ Every role can see the members list. Acting on it needs these permissions:
 | Invite members | Invite people, and resend or remove any invitation | Owner, Admin |
 | Lower your own role | Move yourself to a role whose permissions you already hold | Owner, Admin, Read & Write |
 
-The owner holds **Lower your own role**. The owner's role only changes by transferring ownership. [Custom roles](/admin/team-management/custom-roles) (beta) can grant these permissions one by one. See [Team member roles](/admin/team-management/overview#team-member-roles) for what each role can do.
+The owner holds **Lower your own role**. The owner's role only changes by transferring ownership. If enabled for your account, [custom roles](/admin/team-management/custom-roles) (beta) can grant these permissions one by one. See [Team member roles](/admin/team-management/overview#team-member-roles) for what each role can do.

admin/team-management/overview.mdx

@@ -9,7 +9,7 @@ This section covers all aspects of administering your Checkly account, from mana
 
 ## Team Member Roles
 
-Checkly has five built-in roles: **Owner**, **Admin**, **Read & Write**, **Read & Run**, and **Read Only**. Each role inherits all permissions from the roles below it. On Enterprise plans, you can also create [custom roles](/admin/team-management/custom-roles) (beta) with the permissions you pick.
+Checkly has five built-in roles: **Owner**, **Admin**, **Read & Write**, **Read & Run**, and **Read Only**. Each role inherits all permissions from the roles below it. If [custom roles](/admin/team-management/custom-roles) (beta) are enabled for your account, you can also define roles with the permissions you pick.
 
 Each account has one Owner. The account creator is the Owner until they [transfer ownership](#transferring-ownership). You can invite teammates with any other role. You can [change a member's role](/admin/team-management/managing-team-members#change-members-roles) after they join.
 
@@ -28,6 +28,30 @@ Each account has one Owner. The account creator is the Owner until they [transfe
 | Create service API keys | ✓ | ✓ | ✗ | ✗ | ✗ |
 | Transfer ownership | ✓ | ✗ | ✗ | ✗ | ✗ |
 
+### Permissions and roles
+
+Checkly defines permissions for actions on resources. Your account role grants those permissions. In API and MCP documentation, an ID such as `checks:run` identifies the **Run checks** permission; the format is `resource:action`.
+
+The permissions referenced in these guides use the following names. If [custom roles](/admin/team-management/custom-roles#the-permission-matrix) (beta) are enabled, you can find these names under **Account settings > Roles**, in the listed group and resource row. The editor shows permission names, rather than IDs.
+
+| Permission ID | Name in the role editor | Group and resource |
+| --- | --- | --- |
+| `api-keys:create` | Create API keys | Account > API keys |
+| `api-keys:delete` | Delete API keys | Account > API keys |
+| `members:create` | Invite members | Account > Members |
+| `checks:run` | Run checks | Monitoring > Checks and monitors |
+| `checks:update` | Edit checks | Monitoring > Checks and monitors |
+| `check-repairs:create` | Repair checks with Rocky | Rocky AI > Check repairs |
+| `root-cause-analyses:run` | Start root cause analyses | Rocky AI > Root cause analyses |
+| `environment-variables:create` | Create environment variables | Check resources > Environment variables |
+| `environment-variables:update` | Edit environment variables | Check resources > Environment variables |
+| `incidents:create` | Open incidents | Communicate > Incidents |
+| `incidents:update` | Update incidents | Communicate > Incidents |
+| `status-pages:read` | View status pages | Communicate > Status pages |
+| `usage:read` | View usage | Billing > Usage |
+
+To get access, ask your account owner or an admin to [assign a role](/admin/team-management/managing-team-members#change-members-roles) with the required permissions. Use the built-in role table above to choose a role. On accounts with custom roles enabled, someone who can edit roles can adjust a role's permissions, within the [limits on granting access](/admin/team-management/custom-roles#the-permission-matrix). Custom roles are not generally available, so the Roles page may not appear in your account.
+
 ### Choosing the Right Role
 
 | Role | Best for |

ai/ai-assistant.mdx

@@ -21,10 +21,22 @@ Every check it creates includes an intent: the goal and required outcomes the ch
 
 1. Open **AI Assistant** in the Checkly app and select **New**.
 2. Describe the site, app, or API you want to monitor. Include the starting point, the journey, and the observable outcome that should pass.
-3. Review the proposed monitoring plan. Ask the assistant to adjust the flow, assertions, frequency, locations, or alerting before you approve it.
+3. Review the proposed monitoring plan and linked Test Session results. Ask the assistant to adjust the flow, assertions, frequency, locations, or alerting before you approve it.
 4. Select the checks you want and choose **Create checks**.
-5. Open each new check, run it, and review its behavior and settings. For Browser and Multistep Checks, also review **Check intent** under **Automatic Repair**.
+5. Open each new check, run it, and review its behavior and settings. For Browser and Multistep Checks, also review the **Check intent** section in the check settings.
+
+While preparing your plan, the Assistant tests Browser, Multistep, and API Checks in recorded Test Sessions. URL and Heartbeat Monitors are outside this testing step.
 
 For a browser journey, ask for a Browser Check. For an API endpoint, ask for an API Check; for several related requests, ask for a Multistep Check. Use a URL Monitor for site availability or a Heartbeat Monitor for a scheduled job. If a journey has important negative cases or guardrails, describe them in your request and confirm they appear in the generated intent.
 
 The AI Assistant does not change a check's automatic repair setting when it creates the check. A Browser or Multistep Check inherits the account default until you [set automatic repair for that check](../resolve/automatic-check-repair#enable-automatic-repair). Review its intent and choose **On** if you want to enable repair explicitly.
+
+## Checks that need project files
+
+Standalone creation cannot attach a custom Playwright configuration, visual snapshots, or setup/teardown script files and their helper files. If your check needs these, use a [local Checkly CLI project](../cli/overview) and deploy it.
+
+## Resume a conversation
+
+Open **Conversations** to revisit previous conversations. Choose **All conversations** to search the history. You can continue a conversation you started while its workspace is still available and it has remaining conversation usage.
+
+A conversation becomes read-only when another member owns it, its workspace expires, or it reaches its conversation usage limit. You can still read its history. Only the owner can continue their conversation. For an expired workspace or a conversation usage limit, choose **Start a new conversation** and describe what you want to continue. Its first run uses one invocation from your [account's AI allowance](./rocky-ai#consumption-and-invocations).

ai/mcp-server.mdx

@@ -16,8 +16,7 @@ https://api.checklyhq.com/mcp
 Use it when your agent needs live Checkly account context, check status, check results, test sessions, root cause analyses,
 result assets, status pages, incidents, account environment variables, or when it needs to trigger existing checks.
 
-Use [Checkly Skills](/ai/skills) and the [Checkly CLI](/cli/overview) when your agent needs to create, edit, test, bundle,
-or deploy check code. The MCP server runs remotely and cannot access your local filesystem.
+You can create and update standalone Browser and Multistep Checks through MCP using inline scripts. Use [Checkly Skills](/ai/skills) and the [Checkly CLI](/cli/overview) when your agent needs to work with local project files, bundle code, or deploy a project. The MCP server runs remotely and cannot access your local filesystem.
 
 <Note>
   OAuth is the recommended way to connect. The OAuth flow only supports Checkly-approved clients listed in setup. User and service API keys are available for clients that can send custom headers when OAuth is unavailable or a workflow needs a stable service identity.
@@ -27,7 +26,7 @@ or deploy check code. The MCP server runs remotely and cannot access your local
 ## What you can do
 
 - Inspect account membership, plan, and feature entitlements.
-- Create,read update and delete synthetic & uptime monitors and groups.
+- Create, read, update, and delete synthetic checks, uptime monitors, and groups.
 - Check which checks are passing, failing, muted, or deactivated.
 - Read compact check results and test session results.
 - Fetch normalized result asset manifests and bounded text assets.