Fast follow 2: refine orchestrate launch docs

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

@@ -18,15 +18,15 @@ Agent identities are useful when you want to:
 
 ## How agent identities work
 
-Each team has one default agent identity. Headless runs (such as team API key runs that don't specify an identity) execute under this default. User-triggered runs default to running as the calling user — surfaced as **Quick run** in the web app — unless you pick a specific agent identity. You can create additional agent identities on top of the default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of agent identities.
+Each team has one default agent identity. Headless runs (such as team API key runs that don't specify an identity) execute under this default. User-triggered runs default to running as the calling user, which is surfaced as **Quick run** in the web app, unless you pick a specific agent identity. You can create additional agent identities on top of the default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of agent identities.
 
 You can attach the following configuration to an agent identity:
 
 * **Description** - A short, human-readable summary teammates see when picking the identity.
 * **Managed secrets** - References (by name) to [team-managed secrets](/agent-platform/cloud-agents/secrets/) the identity should have access to.
 * **Skills** - Skill specs (for example, `org/repo:path/to/SKILL.md`) the identity comes preloaded with. Shorthand specs like `repo:skill_name` are accepted when they resolve unambiguously against the team's cloud environments.
 
-Skill specs are stored in their normalized fully-qualified form, and managed secret references are validated against the team's secret scope at attach time. If a secret is missing or a skill repo is not accessible to the team's GitHub App installation, the request is rejected before anything is saved.
+Warp saves each skill spec with its full repository reference, so shorthand specs like `repo:skill_name` are resolved before they are stored. Managed secret references are validated against the team's secret scope at attach time. If a secret is missing or a skill repo is not accessible to the team's GitHub App installation, the request is rejected before anything is saved.
 
 ## Service accounts and agent identities
 
@@ -35,21 +35,23 @@ Skill specs are stored in their normalized fully-qualified form, and managed sec
 * When `oz whoami` reports a principal of `service_account:<uid>`, that principal is an agent identity on your team.
 * When [`oz federate issue-token`](/reference/cli/federate/) emits a subject component like `service_account:my-sa-id`, the value identifies the agent identity the run is executing as.
 
-You don't need to distinguish the two terms in day-to-day use — pick the agent identity in the UI or pass its UID to the API, and the CLI surfaces the corresponding `service_account:` principal.
+You don't need to distinguish the two terms in day-to-day use. Pick the agent identity in the UI or pass its UID to the API, and the CLI surfaces the corresponding `service_account:` principal.
 
 ## Supporting multiple agent identities
 
-Most teams start with the default agent identity and add more as their automation matures. Creating additional agent identities is worth it when distinct workflows have meaningfully different scopes — for example, a `ci-runner` identity that only needs read-only repo access, an `on-call` identity that holds production deploy credentials and is restricted to incident playbooks, and a `nightly-jobs` identity used by scheduled cleanups. Scoping each identity to a single workflow gives every run the minimum credentials it needs, keeps audit trails attributable to the right bot, and lets you revoke or rotate one workflow's access without touching the rest.
+Most teams start with the default agent identity and add more as their automation matures. Creating additional agent identities is worth it when distinct workflows have meaningfully different scopes — for example, a `ci-runner` identity that only needs read-only repo access, an `on-call` identity that holds production deploy credentials and is restricted to incident playbooks, and a `nightly-jobs` identity used by scheduled cleanups.
+
+Scoping each identity to a single workflow gives every run the minimum credentials it needs, keeps audit trails attributable to the right bot, and lets you revoke or rotate one workflow's access without touching the rest.
 
 ## Plan limits
 
-Every team starts with a default agent identity. Additional identities are subject to plan-based limits — see [warp.dev/pricing](https://warp.dev/pricing) for current limits per plan.
+Every team starts with a default agent identity. Additional identities are subject to plan-based limits. See [warp.dev/pricing](https://warp.dev/pricing) for current limits per plan.
 
 When a team is over its plan limit (for example, after downgrading), the extra identities remain visible in the list but are marked as unavailable. Unavailable identities cannot be used to start runs, cannot have new API keys generated for them, and cannot be edited.
 
 ## Managing agent identities
 
-You can create, list, update, and delete agent identities through the public API. The full request and response shapes — including error codes — live on the [API Reference](/api) page; the operations to look for are `createAgent`, `listAgents`, `updateAgent`, and `deleteAgent` under the **agent** tag.
+You can create, list, update, and delete agent identities through the public API. The full request and response formats, including error codes, live on the [API Reference](/api) page; the operations to look for are `createAgent`, `listAgents`, `updateAgent`, and `deleteAgent` under the **agent** tag.
 
 The endpoints behave as follows:
 
@@ -68,9 +70,9 @@ A few constraints apply across every endpoint:
 
 ## API keys bound to an agent identity
 
-A team API key can be bound to a specific agent identity at creation time. Calls authenticated with that key run as the chosen identity. The team is resolved automatically from the identity — you don't need to specify a team when generating the key.
+A team API key can be bound to a specific agent identity at creation time. Calls authenticated with that key run as the chosen identity. The team is resolved automatically from the identity, so you don't need to specify a team when generating the key.
 
-To create a key bound to an agent identity, choose the identity when creating the team API key. See [API Keys](/reference/cli/api-keys/) for the full key creation flow and for the difference between user-scoped and team-scoped keys.
+To create a key bound to an agent identity, choose the identity when creating the team API key. See [API keys](/reference/cli/api-keys/) for the full key creation flow and for the difference between user-scoped and team-scoped keys.
 
 Once the key exists, the CLI and SDK authenticate as that agent identity for every call. There is no extra flag to set; the binding is on the key itself.
 
@@ -81,7 +83,7 @@ There are two ways to run a cloud agent as a specific agent identity:
 * **Authenticate with a key bound to the identity** - Every run started with that key executes as the bound agent identity. This is the typical path for CI pipelines and scheduled work.
 * **Pass `agent_identity_uid` on `POST /agent/runs`** - For one-off runs, send the agent identity's `uid` in the request body. The field is only valid for team-owned runs.
 
-When neither path is used, headless runs (team API key runs without an identity) execute under the team's default agent identity. User-triggered runs (Warp app, personal API key, Slack, Linear) execute as the calling user — surfaced as **Quick run** in the web app.
+When neither path is used, headless runs (team API key runs without an identity) execute under the team's default agent identity. User-triggered runs (Warp app, personal API key, Slack, Linear) execute as the calling user and are surfaced as **Quick run** in the web app.
 
 ## Where agent identities appear in the product
 
@@ -97,7 +99,7 @@ Agent identities surface across several Oz surfaces:
 * [Cloud agent secrets](/agent-platform/cloud-agents/secrets/) - Manage the team-managed secrets you can attach to an agent identity.
 * [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns/) - When to use an agent identity for automation versus a personal identity.
 * [Oz API & SDK](/reference/api-and-sdk/) - Programmatic access to the agent identity endpoints.
-* [API Keys](/reference/cli/api-keys/) - Create keys bound to a specific agent identity.
+* [API keys](/reference/cli/api-keys/) - Create keys bound to a specific agent identity.
 * [Federated identity tokens](/reference/cli/federate/) - Issue OIDC tokens from inside a run, including ones executing as an agent identity.
 * [Oz web app](/agent-platform/cloud-agents/oz-web-app/) - The web surface where you manage agent identities and inspect their runs.
 * [Admin Panel](/knowledge-and-collaboration/admin-panel/) - Team-level billing and access controls.

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

@@ -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/content/docs/agent-platform/cloud-agents/harnesses/claude-code.mdx

@@ -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/codex.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/index.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.
 :::