Fast follow 2: refine orchestrate launch docs

[rachaelrenk]

Summary

This PR is a broad fast-follow to the Cloud Agents launch docs. Changes are grouped by file below.

Terminology note

Following team clarification, this PR treats agent identity as an implementation/API detail, not a product-facing concept. The Oz web app article now uses agents for the product surface and removes references to “agent identity/identities” except when linking to the existing Agent identities page. That reference page is left in place for now and will be simplified to agents in follow-up work.

src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx

• Updates the Oz web app quick reference to match the current navigation: removes the stale /dashboard entry, adds /skills, and clarifies the split between Agents and Skills.
• Removes product-facing references to “agent identity/identities” from the Oz web app page, except for links to the existing Agent identities reference while that page awaits follow-up simplification.
• Refines the Runs guidance for Quick run, saved agents, account/team visibility, search wording, and orchestrated parent/child runs.
• Tightens the Agents section around saved agents as reusable cloud agent configurations, with links to Skills as Agents and Agent identities.
• Adds a dedicated Skills section for browsing environment/suggested skills, running skills, and creating skill PRs from the web app.
• Standardizes the numbered procedures for starting a run, creating an agent, creating a skill, creating a schedule, and creating an environment so only UI elements are bolded and steps use direct action language.
• Adds the Skills creation screenshot to match the visual treatment used by the other Oz web app sections.
• Improves readability by removing redundant callouts, incomplete detail tables, extra section dividers, and non-standard procedural formatting.

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

• Keeps the existing Agent identities reference functional for now, while refining wording for Quick run, team-scoped execution, skill spec normalization, service-account terminology, plan limits, and API key binding behavior.
• Improves cross-links and capitalization consistency for API keys, the API reference, secrets, deployment patterns, and the Oz web app.
• Notes for reviewers: broader terminology cleanup is intentionally deferred so this page can be simplified from Agent identities to agents in follow-up work.

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

• Clarifies the harness overview for Warp Agent, Claude Code, and Codex.
• Adds the Warp app harness selector screenshot to show where cloud agent harnesses are selected.

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

• Tightens the Warp Agent harness description, cross-harness orchestration language, and related-page wording.

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

• Tightens Claude Code positioning, model-picker wording, subagent guidance, and related-page language.

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

• Tightens Codex positioning, model-picker wording, and related-page language.

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

• Reorders Claude Code and Codex credential setup so users confirm API credits before creating keys.
• Clarifies Warp app and Oz web app auth-secret flows for Claude Code and Codex.
• Adds the Claude Code auth secret setup screenshot.

src/assets/agent-platform/oz-web-app-runs-view.png

• Replaces the outdated Oz web app Runs screenshot after the quick reference with the current cropped Runs view.

src/assets/agent-platform/oz-web-app-agents.png

• Replaces the Agents section screenshot with the current Oz web app Agents page view.

src/assets/agent-platform/oz-web-app-new-agent.png

• Replaces the Create a new agent section screenshot with the updated New agent side pane.

src/assets/agent-platform/oz-web-app-new-skill.png

• Adds the Skills section screenshot showing the New agent side pane for creating a skill.

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

• Adds the Oz web app screenshot for configuring a Claude Code auth secret.

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

• Adds the Warp app screenshot for selecting a cloud agent harness.

Validation

• git diff --check
• npm run build

Conversation: https://staging.warp.dev/conversation/db4886fb-3576-4fbc-b694-e8f0852e4bb0

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

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	May 21, 2026 8:00pm

[oz-for-oss]

@rachaelrenk

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

This PR refines the cloud agent harness documentation for Warp Agent, Claude Code, Codex, and the harness overview, including clearer credential setup language and two new screenshots. I did not find correctness, security, style, or structure issues that need changes before merge.

Concerns

• No blocking concerns found.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[rachaelrenk]

Pushed a scoped follow-up for the Oz web app launch docs review in afff0fa (Tighten Oz web app docs).

What changed and why:

• Folded orchestrated runs into the Runs section — Moved the parent/child run inspection guidance under ## Runs as ### Inspecting orchestrated runs because this content explains how orchestration appears in the web app’s run-management surface, not a separate top-level product area.
• Removed the “Where to start an orchestration” subsection — Cut the web-app-specific orchestration-starting guidance, including the orchestrate-mode phrasing, because the canonical start flow already lives in the orchestration docs and this page should stay focused on web app orientation.
• Tightened the Agents section around the user goal — Kept the core definition of agents as reusable cloud agent configurations, shortened the skills explanation, and kept a concise mention of the team-scoped identity model so readers understand what saved agents do without re-expanding the full identity model here.
• Removed the Agent details table — Replaced the incomplete list-view table with a sentence explaining that opening an agent shows prompt, skills, harness, model, environment, and secrets. This avoids a mismatch between the table fields and the fuller saved-agent configuration described in the section.
• Updated Quick reference and Runs wording — Changed the Agents row to “saved and suggested agents,” clarified that Runs can cover account and team activity where applicable, and changed search wording from “skill name” to “agent name” to better match the current user-facing model.
• Simplified procedural copy — Removed note callouts that only said which button to click, tightened the new-run explanation to avoid repeating Quick run, shortened the new-agent creation flow, and added punctuation to numbered steps.
• Removed body horizontal dividers — Dropped the repeated --- dividers because they made the article feel fragmented after the scoped edits; headings now carry the structure.

Validation:

• git diff --check passed.
• npm run build passed (334 pages built; existing non-blocking prerender warnings still appear).

[hongyi-chen]

nice, ty for the screenshots!

[hongyi-chen]

i wouldn't specify just two, since we'll be adding support for many others soon!

[hongyi-chen]

can we use simpler language here than "nuanced judgement"?

[hongyi-chen]

I think we can keep this generally high level, I don't think we need to expose this internal implementation detail perhaps?