Refine cloud agent harness docs

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: rachaelrenk

src/assets/agent-platform/claude-code-auth-secret-setup.png

@@ -22,21 +22,26 @@ Claude Code is Anthropic's agentic coding tool. For more on Claude Code authenti
 ### Create an Anthropic API key
 
 1. Go to the [Anthropic Console](https://platform.claude.com/login?returnTo=/?) and sign in or create an account.
-2. Navigate to the API keys section, then click **Get API key**.
-3. Create a new API key and copy the value.
-4. Confirm your account has API credits. Claude Code runs are billed against your Anthropic API balance.
+2. Confirm your account has API credits. Claude Code runs are billed against your Anthropic API balance.
+3. Navigate to the API keys section, then click **Get API key**.
+4. Create a new API key and copy the value.
 
 Oz also supports Bedrock-routed credentials (**Anthropic Bedrock API key** and **Anthropic Bedrock access key**) if your team consumes Anthropic models through AWS.
 
 ### Store API key in Oz
 
 #### Warp desktop app
 
-In the Warp app, start a new cloud agent run and choose **Claude Code** from the **Agent harness** dropdown. In the harness auth secret field, add or select your Anthropic credential.
+Start a new cloud agent run and choose **Claude Code** from the **Agent harness** dropdown. In the harness auth secret field, add or select your Anthropic credential.
 
 #### Oz web app
 
-Start a [new run](https://oz.warp.dev/runs/new), choose **Claude Code** as the harness, and add a new key in the harness auth secrets dropdown.
+Start a [new run](https://oz.warp.dev/runs/new), choose **Claude Code** as the harness, and add a new key in the Claude Code auth secret dialog.
+
+<figure style={{ maxWidth: "563px" }}>
+![The Oz web app dialog for adding a new Claude Code auth secret.](../../../../../assets/agent-platform/claude-code-auth-secret-setup.png)
+<figcaption>The Claude Code auth secret dialog.</figcaption>
+</figure>
 
 #### Oz CLI
 
@@ -59,20 +64,20 @@ A ChatGPT subscription (Plus, Pro, Team) does not include API access. You need a
 ### Create an OpenAI API key
 
 1. Go to the [OpenAI Platform](https://platform.openai.com/) and sign in (or create an account).
-2. Click **Create API key**.
-3. In the **Create new secret key** dialog, choose the owner, project, and permissions for the key.
-4. Click **Create secret key**, then copy the value.
-5. Confirm your account has API credits. Codex runs are billed against your OpenAI API balance, not a ChatGPT subscription.
+2. Confirm your account has API credits. Codex runs are billed against your OpenAI API balance, not a ChatGPT subscription.
+3. Navigate to the API keys section, then click **Create API key**.
+4. In the **Create new secret key** dialog, choose the owner, project, and permissions for the key.
+5. Click **Create secret key**, then copy the value.
 
 ### Store API key in Oz
 
 #### Warp desktop app
 
-In the Warp app, start a new cloud agent run and choose **Codex** from the **Agent harness** dropdown. In the harness auth secret field, add or select your OpenAI credential.
+Start a new cloud agent run and choose **Codex** from the **Agent harness** dropdown. In the harness auth secret field, add or select your OpenAI credential.
 
 #### Oz web app
 
-Start a [new run](https://oz.warp.dev/runs/new), choose **Codex** as the harness, and add a new key in the harness auth secrets dropdown.
+Start a [new run](https://oz.warp.dev/runs/new), choose **Codex** as the harness, and add a new key in the Codex auth secret dialog.
 
 #### Oz CLI
 

src/assets/agent-platform/cloud-agent-harness-selector-warp-app.png

@@ -7,7 +7,7 @@ sidebar:
   label: "Claude Code"
 ---
 
-Claude Code is Anthropic's agentic coding tool. Running it with Oz puts Claude Code inside a Warp-managed environment and connects it to the rest of the Oz platform — triggers, environments, secrets, observability, and governance — while still behaving like the Claude Code your team already uses.
+Claude Code is Anthropic's agentic coding tool. Running it with Oz puts Claude Code inside a Warp-managed environment and connects it to the rest of the Oz platform — including triggers, environments, secrets, observability, and governance — while still behaving like the Claude Code your team already uses.
 
 :::note
 This page covers Claude Code as a **cloud** harness, dispatched and orchestrated by Oz. To run Claude Code locally in your Warp terminal, see [Claude Code in Warp](/agent-platform/cli-agents/claude-code/) instead.
@@ -17,11 +17,11 @@ This page covers Claude Code as a **cloud** harness, dispatched and orchestrated
 
 * **Cloud orchestration** - Launch Claude Code from any Oz trigger: the Warp app, the Oz web app, the Oz CLI, the REST API, schedules, Slack mentions, Linear issues, or GitHub Actions.
 * **Claude model picker** - Choose the Claude model the harness uses, including the latest pinned Opus, Sonnet, and Haiku releases, the `best`/`opus`/`sonnet`/`haiku` aliases, and 1M-context variants.
-* **First-class subagent** - A Warp Agent parent can dispatch Claude Code subagents to handle code-review-heavy or judgment-heavy steps within a larger orchestration.
+* **First-class subagent** - A Warp Agent parent can dispatch Claude Code subagents to handle steps that require code review or nuanced judgment within a larger orchestration.
 
 ## Available models
 
-The Claude Code harness exposes Anthropic's coding-tuned model lineup. Common picks:
+The Claude Code harness exposes Anthropic's coding-tuned model lineup. Common choices include:
 
 * `best` - Resolves to the current top-of-line Claude model.
 * `opus`, `sonnet`, `haiku` - Aliases that resolve to the current default for that family.
@@ -48,7 +48,7 @@ For setup steps, see [Connecting Claude Code credentials](/agent-platform/cloud-
 
 ## Related pages
 
-* [Harnesses in Oz](/agent-platform/cloud-agents/harnesses/) — pick between Warp Agent, Claude Code, and Codex.
+* [Harnesses in Oz](/agent-platform/cloud-agents/harnesses/) — choose between Warp Agent, Claude Code, and Codex.
 * [Authentication](/agent-platform/cloud-agents/harnesses/authentication/) — store Anthropic credentials as Warp-managed secrets.
 * [Warp Agent with Oz](/agent-platform/cloud-agents/harnesses/warp-agent/) — Oz's default harness, the only one that can orchestrate Claude Code subagents.
 * [Codex with Oz](/agent-platform/cloud-agents/harnesses/codex/) — Codex as a cloud harness.

src/content/docs/agent-platform/cloud-agents/harnesses/authentication.mdx

@@ -1,13 +1,13 @@
 ---
 title: Codex with Oz
 description: >-
-  Run Codex with Oz. Strong at codebase migrations, release coordination, batch
-  test generation, and backend or DevOps automation.
+  Run Codex with Oz for codebase migrations, release coordination, batch test
+  generation, and backend or DevOps automation.
 sidebar:
   label: "Codex"
 ---
 
-Codex is OpenAI's coding agent. Running it with Oz puts Codex inside a Warp-managed environment and connects it to the rest of the Oz platform — triggers, environments, secrets, observability, and governance — while still behaving like the Codex CLI your team already uses.
+Codex is OpenAI's coding agent. Running it with Oz puts Codex inside a Warp-managed environment and connects it to the rest of the Oz platform — including triggers, environments, secrets, observability, and governance — while still behaving like the Codex CLI your team already uses.
 
 :::note
 This page covers Codex as a **cloud** harness, dispatched and orchestrated by Oz. To run Codex locally in your Warp terminal, see [Codex CLI in Warp](/agent-platform/cli-agents/codex/) instead.
@@ -21,13 +21,13 @@ This page covers Codex as a **cloud** harness, dispatched and orchestrated by Oz
 
 ## Available models
 
-The Codex harness exposes OpenAI's Codex-tuned and general coding models. Common picks:
+The Codex harness exposes OpenAI's Codex-tuned and general coding models. Common choices include:
 
 * `default` - Lets Codex pick its own recommended model based on your OpenAI account access.
 * `gpt-5.5`, `gpt-5.4` - Recent strong coding models from OpenAI with a configurable reasoning level.
 * `gpt-5.4-mini` - A faster, lower-cost option for lighter coding tasks or subagents.
 
-For the full list — including older Codex-tuned and general models — open the model picker on the Oz web app's new-run pane. For details on each model, see [OpenAI's Codex model docs](https://developers.openai.com/codex/models).
+For the full list, including Codex-tuned and general models, open the model picker on the Oz web app's new-run pane. For details on each model, see [OpenAI's Codex model docs](https://developers.openai.com/codex/models).
 
 ## Credentials and billing
 
@@ -47,7 +47,7 @@ For setup steps, see [Connecting Codex credentials](/agent-platform/cloud-agents
 
 ## Related pages
 
-* [Harnesses in Oz](/agent-platform/cloud-agents/harnesses/) — pick between Warp Agent, Claude Code, and Codex.
+* [Harnesses in Oz](/agent-platform/cloud-agents/harnesses/) — choose between Warp Agent, Claude Code, and Codex.
 * [Authentication](/agent-platform/cloud-agents/harnesses/authentication/) — store OpenAI credentials as Warp-managed secrets.
 * [Warp Agent with Oz](/agent-platform/cloud-agents/harnesses/warp-agent/) — Oz's default harness, the only one that can orchestrate Codex subagents.
 * [Claude Code with Oz](/agent-platform/cloud-agents/harnesses/claude-code/) — Claude Code as a cloud harness.

src/content/docs/agent-platform/cloud-agents/harnesses/claude-code.mdx

@@ -7,7 +7,7 @@ sidebar:
   label: "Overview"
 ---
 
-Oz can run third-party agents — [Claude Code](/agent-platform/cloud-agents/harnesses/claude-code/) and [Codex](/agent-platform/cloud-agents/harnesses/codex/) — as cloud agents alongside Warp Agent. You choose the harness (agent runtime) that fits the task; the platform around the run stays the same.
+Oz can run two third-party agents as cloud agents alongside Warp Agent: [Claude Code](/agent-platform/cloud-agents/harnesses/claude-code/) and [Codex](/agent-platform/cloud-agents/harnesses/codex/). You choose the harness (agent runtime) that fits the task; the platform around the run stays the same.
 
 ## What stays the same
 
@@ -28,6 +28,11 @@ Claude Code and Codex each call their provider directly using credentials you su
 
 In Cloud Mode, choose a harness from the **Agent harness** dropdown above the input.
 
+<figure style={{ maxWidth: "375px" }}>
+![The Warp app Agent harness dropdown showing third-party harness options for a cloud agent.](../../../../../assets/agent-platform/cloud-agent-harness-selector-warp-app.png)
+<figcaption>The Agent harness selector.</figcaption>
+</figure>
+
 :::note
 You can enter Cloud Mode by creating a new **Cloud Agent** tab or by using the `/cloud-agent` slash command.
 :::

src/content/docs/agent-platform/cloud-agents/harnesses/codex.mdx

@@ -14,7 +14,7 @@ Warp Agent is the same agent runtime that powers Agent Mode in the Warp terminal
 ## Key features
 
 * **Multi-model auto-routing** - Routes between Anthropic, OpenAI, Google, and Fireworks-hosted models. Choose a specific model, or let Warp pick via `auto`, `auto-efficient`, `auto-genius`, or `auto-open`. See [Model choice](/agent-platform/capabilities/model-choice/) for the full catalog.
-* **Full terminal and tool access** - Runs commands, edits files, reads logs, executes tests, navigates repos, and calls MCP servers — the same toolbelt Warp Agent uses locally.
+* **Full terminal and tool access** - Runs commands, edits files, reads logs, executes tests, navigates repos, and calls MCP servers, giving cloud runs the same toolbelt Warp Agent uses locally.
 * **Platform-native context** - Reads [Codebase Context](/agent-platform/capabilities/codebase-context/), applies [Rules](/agent-platform/capabilities/rules/), reuses saved [Skills](/agent-platform/capabilities/skills/), and respects Memory and Warp Drive context with no extra setup.
 * **Multi-repo execution** - Clones every repo configured on the [environment](/agent-platform/cloud-agents/environments/) and works across them in a single run.
 * **Cross-harness orchestration parent** - A Warp Agent parent run can spawn Claude Code or Codex [subagents](/agent-platform/cloud-agents/overview/) and coordinate their outputs. Other harnesses cannot act as parents in a multi-harness orchestration.
@@ -32,10 +32,10 @@ Warp Agent supports the full Warp model catalog. Configure the model per [Agent
 
 ### Cross-harness orchestration
 
-Warp Agent is the orchestration host for multi-harness runs. A typical pattern:
+Warp Agent is the orchestration host for multi-harness runs. A typical pattern looks like:
 
 1. A Warp Agent parent run analyzes a task and breaks it into subtasks.
-2. The parent dispatches Claude Code subagents for code-review-heavy steps and Codex subagents for high-volume edits.
+2. The parent dispatches Claude Code subagents for steps that require code review or nuanced judgment and Codex subagents for high-volume edits.
 3. The parent collects results, resolves conflicts, and returns a single final output (a PR, a report, a Slack reply).
 
 Subagents run in the same environment as the parent and share the same secrets, MCP servers, and integrations. The transcript shows the full tree, so reviewers can see exactly which subagent did what.
@@ -61,7 +61,7 @@ For a complete walkthrough, see the [Cloud agents quickstart](/agent-platform/cl
 
 ## Related pages
 
-* [Harnesses in Oz](/agent-platform/cloud-agents/harnesses/) — pick between Warp Agent, Claude Code, and Codex.
+* [Harnesses in Oz](/agent-platform/cloud-agents/harnesses/) — choose between Warp Agent, Claude Code, and Codex.
 * [Claude Code with Oz](/agent-platform/cloud-agents/harnesses/claude-code/) — Claude Code as a cloud harness.
 * [Codex with Oz](/agent-platform/cloud-agents/harnesses/codex/) — Codex as a cloud harness.
 * [Model choice](/agent-platform/capabilities/model-choice/) — the model catalog Warp Agent routes across.