docs: crosslink API error references

src/content/docs/agent-platform/cloud-agents/environments.mdx

@@ -290,12 +290,12 @@ If your setup commands depend on secrets or credentials, configure them through
 
 ### Common issues
 
-* **Setup assumes previous state** – Steps that rely on leftover caches, existing directories, or already-cloned repos can make runs unreliable.
+* **Setup assumes previous state** – Steps that rely on leftover caches, existing directories, or already-cloned repos can make runs unreliable. Setup failures can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/).
   * Solution: Write idempotent setup commands that work on a fresh container.
 * **Missing credentials or secrets** – Builds fail when private repos, package registries, or external services require authorization.
   * Solution: Configure credentials with [Agent Secrets](/agent-platform/cloud-agents/secrets/).
-* **Repo access and GitHub authorization issues** – Runs fail when GitHub doesn't have repo access or the triggering user lacks permissions.
+* **Repo access and GitHub authorization issues** – Runs fail when GitHub doesn't have repo access or the triggering user lacks permissions. Missing external authorization can surface as [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/).
   * Solution: See [Integration setup](/reference/cli/integration-setup/#how-github-authorization-works) for GitHub authorization setup.
 * **Docker image incompatibility** – You see the error: "VM failed before the agent could run. This is likely an issue with your Docker image."
-  * Possible cause: Alpine Linux and other musl-based images are not compatible with the agent runtime, which requires glibc.
+  * Possible cause: Alpine Linux and other musl-based images are not compatible with the agent runtime, which requires glibc. This can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/).
   * Solution: Switch to a glibc-based image such as Debian, Ubuntu, or the default (non-Alpine) variants of official Docker Hub images (e.g. `node`, `python`, `rust`).

src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx

@@ -65,6 +65,12 @@ You can specify a skill using the `skill` input parameter, either instead of or
     warp_api_key: ${{ secrets.WARP_API_KEY }}
 ```
 
+:::tip
+If the action fails, use the returned error code to narrow the fix. Common errors include:
+
+* [`authentication_required`](/reference/api-and-sdk/troubleshooting/errors/authentication-required/) (missing, invalid, or expired `warp_api_key` secret)
+:::
+
 #### Skill format options
 
 The `skill` parameter supports multiple formats for referencing skills:

src/content/docs/agent-platform/cloud-agents/integrations/index.mdx

@@ -23,86 +23,12 @@ All of this is powered by the [Oz CLI](/reference/cli/).
 
 ---
 
-## Quickstart
+## Get started
 
-The fastest way to get agents running from Slack or Linear is to create an environment with the guided flow. An **environment** defines everything the agent needs to run your code remotely, including your Docker image, repos, and setup commands.
+Use the setup walkthrough below for a quick look at how environments connect to integrations, then choose the guide that matches what you want to do next.
 
 <VideoEmbed url="https://www.youtube.com/watch?v=ahFfInVD0HQ" />
 
-#### 1. Run /create-environment
-
-From Warp, run the following slash command:
-
-```
-/create-environment
-```
-
-You can run it inside any repo, or point it at multiple repos:
-
-```
-/create-environment ./frontend ./backend
-/create-environment your-org/repo-name
-/create-environment https://github.com/your-org/api.git
-```
-
-:::note
-Learn more about slash commands and how to use them in the [Slash Commands](/agent-platform/capabilities/slash-commands/) documentation.
-:::
-
-The guided flow will:
-
-* Detect which repos you want the agent to work with
-* Identify languages, frameworks, and tools
-* Suggest a Docker image (or build/push one if needed)
-  * The Docker image can be your own custom image, an official base image (e.g. node, python), or one of Warp's prebuilt dev images (see [repo](https://github.com/warpdotdev/oz-dev-environments)).
-* Recommend setup commands
-* Create the environment and return an environment ID
-
-This produces a ready-to-use environment that Warp can use across Slack, Linear, and terminal triggers.
-
-#### 2. Authorize GitHub
-
-Warp will prompt you to install or update the Warp GitHub app so the agent can read and write to the repos you included. You only need to do this once. Teammates will authorize on their first run as needed.
-
-:::note
-**Using Azure DevOps, GitLab, or Bitbucket?** Native integrations for these platforms are not yet available, but you can connect repositories by storing a personal access token as a Warp-managed secret and cloning via a setup command. See [Azure DevOps](/agent-platform/cloud-agents/integrations/azure-devops/), [GitLab](/agent-platform/cloud-agents/integrations/gitlab/), or [Bitbucket](/agent-platform/cloud-agents/integrations/bitbucket/) for step-by-step instructions.
-:::
-
-#### 3. Create an integration
-
-:::note
-For easier setup, use the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) at [oz.warp.dev](https://oz.warp.dev) to configure integrations with a guided flow. The web app works on mobile devices.
-:::
-
-Alternatively, use the CLI:
-
-For Slack:
-
-```
-oz integration create slack --environment <ENV_ID>
-```
-
-For Linear:
-
-```
-oz integration create linear --environment <ENV_ID>
-```
-
-The CLI opens an authorization page where you install Oz into your Slack workspace or Linear team.
-
-#### 4. Start using agents
-
-In Slack:
-
-* Tag **@Oz** in a message or thread
-* Or DM the bot
-
-In Linear:
-
-* Tag @Oz on an issue
-
-Warp will read the thread/issue, spin up your environment, run the workflow in the cloud, and post progress + PRs back into the same conversation.
-
----
-
-For more details on configuring integrations and environments in Warp, please refer to [Integration setup](/reference/cli/integration-setup/).
+* [Integrations quickstart](/agent-platform/cloud-agents/integrations/quickstart/) - Trigger your first agent from Slack and watch the run from start to finish.
+* [Integration setup](/reference/cli/integration-setup/) - Configure environments, GitHub authorization, CLI flags, and integrations in more detail.
+* [Slack](/agent-platform/cloud-agents/integrations/slack/) and [Linear](/agent-platform/cloud-agents/integrations/linear/) - Learn how each integration behaves, how agents are triggered, and what teammates see in those tools.

src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx

@@ -110,6 +110,13 @@ oz integration create linear --environment <ENV_ID>
 
 The CLI will open a browser window prompting you to install the Oz app into your Linear workspace. After installation, the integration becomes available to all members of your Warp team.
 
+:::tip
+If the integration cannot be created or a Linear-triggered run cannot start, use the returned error code to narrow the fix. Common errors include:
+
+* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) (plan or credit issues)
+* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Linear authorization)
+:::
+
 ---
 
 ### Uninstallation instructions
@@ -124,7 +131,7 @@ To remove the Oz integration from Linear:
 
 <VideoEmbed url="https://www.loom.com/share/2f1648586d8148dc80561c00a09ca334" />
 
-After revoking access, Warp will no longer be able to read issues, receive triggers, or create updates in Linear. If you reinstall later, you’ll need to authorize Warp again during setup.
+After revoking access, Warp will no longer be able to read issues, receive triggers, or create updates in Linear. If you reinstall later, you’ll need to authorize Warp again during setup. Events for a disabled integration can return [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/).
 
 ### Troubleshooting
 

src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx

@@ -43,6 +43,13 @@ oz integration create slack --environment <ENV_ID>
 
 Replace `<ENV_ID>` with your environment ID (see [Environments](/agent-platform/cloud-agents/environments/) if you need to create one). Find it with `oz environment list` on the Oz CLI or in the [Oz web app](https://oz.warp.dev). The CLI opens a browser window to authorize the Oz app in your workspace.
 
+:::tip
+If the integration cannot be created or your first run cannot start, use the returned error code to narrow the fix. Common errors include:
+
+* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) (plan or credit issues)
+* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization)
+:::
+
 To attach a default prompt that applies to every agent run triggered from this integration, add the `--prompt` flag:
 
 ```bash

src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx

@@ -135,6 +135,13 @@ oz integration create slack --environment <ENV_ID>
 
 The CLI will open a browser window to install the Oz app into your Slack workspace. After installation, the integration becomes available to all members of your Warp team.
 
+:::tip
+If the integration cannot be created or a Slack-triggered run cannot start, use the returned error code to narrow the fix. Common errors include:
+
+* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) or [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) (plan or credit issues)
+* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization)
+:::
+
 You can optionally attach a custom prompt that is applied to every agent run:
 
 ```
@@ -170,7 +177,7 @@ To remove the Oz app from your Slack workspace:
 
 ![Confirmation dialog to remove the Oz app from a Slack workspace.](../../../../../assets/agent-platform/remove-slack-app.png)
 
-Once removed, Slack will immediately disable the integration for all teammates.
+Once removed, Slack will immediately disable the integration for all teammates. Events for a disabled integration can return [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/).
 
 ### Troubleshooting
 

src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx

@@ -90,7 +90,7 @@ Where the agent was launched from. Common sources include:
 
 Warp uses a small set of statuses to help you quickly identify what needs attention:
 
-<table><thead><tr><th width="173.375">Status</th><th width="78.41973876953125">Icon</th><th>Description</th></tr></thead><tbody><tr><td><code>Working</code></td><td>N/A</td><td>in progress (may include queued / running states)</td></tr><tr><td><code>Blocked</code></td><td>🟨</td><td><p><em>(interactive only)</em></p><p><br />the conversation is waiting on user input or a required step</p></td></tr><tr><td><code>Canceled</code></td><td>⬜️</td><td>(interactive only)<br /><br />the interactive conversation was canceled before completion</td></tr><tr><td><code>Failed / Errored</code></td><td>🔺</td><td>something went wrong (applies to both interactive and cloud agent runs)</td></tr><tr><td><code>Success</code></td><td>✅</td><td>completed successfully (applies to both interactive and cloud agent runs)</td></tr></tbody></table>
+<table><thead><tr><th width="173.375">Status</th><th width="78.41973876953125">Icon</th><th>Description</th></tr></thead><tbody><tr><td><code>Working</code></td><td>N/A</td><td>in progress (may include queued / running states)</td></tr><tr><td><code>Blocked</code></td><td>🟨</td><td><p><em>(interactive only)</em></p><p><br />the conversation is waiting on user input or a required step</p></td></tr><tr><td><code>Canceled</code></td><td>⬜️</td><td>(interactive only)<br /><br />the interactive conversation was canceled before completion</td></tr><tr><td><a href="/reference/api-and-sdk/troubleshooting/errors/"><code>Failed / Errored</code></a></td><td>🔺</td><td>something went wrong (applies to both interactive and cloud agent runs)</td></tr><tr><td><code>Success</code></td><td>✅</td><td>completed successfully (applies to both interactive and cloud agent runs)</td></tr></tbody></table>
 
 **Duration (for cloud agent tasks)**
 

src/content/docs/agent-platform/cloud-agents/quickstart.mdx

@@ -151,13 +151,13 @@ Use the [Oz API & SDK](/reference/api-and-sdk/) to trigger agents programmatical
 ## Troubleshooting
 
 **Environment creation fails**\
-Use official Docker Hub images like `node`, `python`, or `rust` for best compatibility. Ensure your GitHub repos are accessible. If using a custom image, avoid Alpine/musl-based images—the agent runtime requires glibc. See [Environments](/agent-platform/cloud-agents/environments/) for more guidance on choosing Docker images.
+Use official Docker Hub images like `node`, `python`, or `rust` for best compatibility. Ensure your GitHub repos are accessible. If using a custom image, avoid Alpine/musl-based images—the agent runtime requires glibc. See [Environments](/agent-platform/cloud-agents/environments/) for more guidance on choosing Docker images and [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for the related API error.
 
 **Agent can't access repos**\
-Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works). For automated workflows using team API keys, make sure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get <ENV_ID>`.
+Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works) and [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). For automated workflows using team API keys, make sure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get <ENV_ID>`; permission mismatches can surface as [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/).
 
 **Not enough credits to run cloud agents**\
-Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents.
+Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. If a run is blocked because the billed principal has no remaining credits, see [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/).
 
 **More resources**