docs(orchestration): add multi-agent orchestration pages

src/content/docs/agent-platform/capabilities/agent-notifications.mdx

@@ -99,10 +99,20 @@ For **third-party CLI agents**, each agent requires a one-time setup. The proces
 
 If auto-install doesn't work or you're running an agent over SSH, Warp displays an installation-instructions chip in the terminal with setup steps you can follow directly.
 
+## Notifications in orchestrated runs
+
+In a [multi-agent orchestration](/agent-platform/cloud-agents/orchestration/), each child agent is its own conversation, and notifications fire on the child whose state changes — not aggregated on the parent.
+
+* **Child state transitions** — when a child reaches `SUCCEEDED`, `BLOCKED`, `ERROR`, or `CANCELLED`, the child's conversation generates the matching notification (Complete, Request, or Error). The toast and mailbox identify which child changed state so you can jump to it directly.
+* **Blocked children** — a child that blocks on user input (for example, a command approval request) raises a **Request** notification on the child's own conversation. The parent's transcript reflects the child's `BLOCKED` state separately, so the parent can wait, send a follow-up, or cancel the child.
+
+Notifications from cloud children are delivered to the user account that owns the orchestration. They don't fan out to every member of a team unless the parent run is configured for team-wide notification visibility.
+
 ## Related pages
 
 * [Desktop Notifications](/terminal/more-features/notifications/) - configure system-level notification permissions and troubleshoot delivery
 * [Managing Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - monitor all agent conversations, filter by status, and inspect sessions
+* [Multi-agent orchestration](/agent-platform/cloud-agents/orchestration/) - parent/child model, run state transitions, and messaging between agents
 * [Third-Party CLI Agents](/agent-platform/cli-agents/overview/) - overview of supported CLI agents and Warp features
 * [Claude Code](/agent-platform/cli-agents/claude-code/) - setup and notification plugin installation
 * [Codex](/agent-platform/cli-agents/codex/) - setup and notification configuration

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

@@ -53,7 +53,7 @@ Use this when you already have a system that schedules work (CI, dev boxes, inte
 #### Minimal setup checklist
 
 * A Warp team
-* A service account (recommended for automation)
+* An agent identity for non-interactive auth (use an [API key](/reference/cli/api-keys/) for automation)
 * The Oz CLI installed on the runner / box
 * Any needed credentials (often via secrets + environment variables)
 
@@ -101,12 +101,7 @@ Use this when you want Oz to run agent workloads on Warp-managed infrastructure,
 
 #### Example recipe: fan-out parallel work (sharding)
 
-If a task is naturally divisible:
-
-* Launch multiple cloud agents via oz agent run-cloud, each with:
-  * A shard of the repo (directory/module ownership)
-  * A shard of the prompt (one responsibility)
-* Aggregate results (PRs, notes, plans) in whatever system you prefer.
+When a task is naturally divisible, use [multi-agent orchestration](/agent-platform/cloud-agents/orchestration/) to spawn one child per shard from a single parent run. The parent owns coordination and result aggregation; the children execute in parallel, each with their own repo subset, prompt, and (optionally) model. See [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/) for CLI, API, and slash command examples.
 
 #### Example recipe: same task across multiple models
 

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

@@ -99,3 +99,15 @@ In both _Personal_ and _All_ views, you can open the filter menu and filter by:
 * Status
 
 This is the fastest way to isolate "everything that failed today," "runs from Slack," or "what a specific teammate triggered via integrations."
+
+---
+
+### Orchestrated runs (parent and child)
+
+When a parent agent spawns one or more child agents through [multi-agent orchestration](/agent-platform/cloud-agents/orchestration/), the parent and each child are tracked as separate runs. Where you see them depends on the surface:
+
+* **Local child conversations in the Warp app** — surfaced through a child agent status card rendered above the parent's agent input, with one row per child. Each row shows the child's status icon, name, and title; click a row to reveal that child's conversation. Local child conversations don't appear as separate cards in the management view list.
+* **Cloud child runs in the Warp app** — appear in the management view list as their own rows alongside the parent and other runs. Filter by source, status, or creator to isolate them.
+* **Cloud child runs in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/)** — grouped under the parent's row on the Runs page, and surfaced together inside the parent's detail pane on a **Sub-agents** tab.
+
+The parent's own status reflects only its work — a parent can finish successfully while a child is still running or has failed. To verify that an orchestration completed, check each child individually from the status card (locally) or the **Sub-agents** tab on the Runs page (in the Oz web app).

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

@@ -0,0 +1,103 @@
+---
+title: Multi-agent orchestration
+description: Coordinate parent and child agents across local and cloud runs to build supervisor/worker, fan-out, critic, DAG, and swarm workflows on the Oz Platform.
+sidebar:
+  label: "Orchestration"
+---
+
+Multi-agent orchestration lets one agent spawn and coordinate other agents to parallelize work, delegate specialized tasks, or check each other's output. The same parent/child model works from the Warp app, the [Oz CLI](/reference/cli/), and the [Oz API](/reference/api-and-sdk/).
+
+This page covers the orchestration model and the patterns it supports. For how to start an orchestrated run, see [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/).
+
+## The parent/child model
+
+An orchestrated workflow always has one **parent agent** and one or more **child agents**.
+
+* **Parent agent** — the agent that decides what work needs to be done, spawns child agents, and (optionally) merges their results. Any Oz agent can become a parent the first time it spawns a child.
+* **Child agent** — an Oz agent spawned by a parent with its own prompt, environment, and (optionally) a different model or harness. A child can spawn its own children, so orchestrations are arbitrarily deep.
+
+The parent and child each have an independent **run** with its own lifecycle, transcript, conversation, and credit usage. The management view, web app, and API all surface a parent alongside its children.
+
+### Where each side can run
+
+The parent and child don't have to run in the same place. Orchestration supports three combinations:
+
+* **Local → local** — a [Warp Agent](/agent-platform/local-agents/overview/) conversation in the desktop app spawns child Warp Agent conversations on the same machine. Useful for trying orchestration patterns without spinning up cloud infrastructure.
+* **Local → cloud** — a local parent spawns one or more cloud children that run in [environments](/agent-platform/cloud-agents/environments/) on Warp-hosted or self-hosted infrastructure. The parent keeps working while children execute in parallel.
+* **Cloud → cloud** — a cloud parent spawns cloud children. This is the canonical pattern for review swarms, large fan-outs, and any orchestration triggered from Slack, Linear, a schedule, or the API.
+
+Children can also use a different harness than the parent. A parent running with the default Warp Agent can spawn children that run with [Claude Code](/agent-platform/cli-agents/claude-code/) or [Codex](/agent-platform/cli-agents/codex/), and vice versa.
+
+## Run state transitions
+
+Each run progresses through a small set of states. The parent observes these transitions to decide what to do next — keep waiting, send a follow-up, spawn a replacement, or finish.
+
+The states a child run can reach are:
+
+* **`INPROGRESS`** — the run is actively executing (or has restarted after being blocked).
+* **`SUCCEEDED`** — the run completed successfully.
+* **`FAILED`** — the run hit a terminal failure.
+* **`BLOCKED`** — the run is waiting on a user action (for example, command approval or a permission request).
+* **`ERROR`** — the run encountered an error during startup or execution.
+* **`CANCELLED`** — the run was cancelled before reaching a terminal state.
+
+Observe run state transitions in any of these surfaces:
+
+* **The parent's transcript** — the parent agent receives child state transitions as it runs and reflects them in its own conversation.
+* **The child agent status card** — in the Warp app, local children appear in a status card above the parent's agent input. Each row updates as the child's state changes.
+* **The Oz web app** — cloud children appear under the parent on the Runs page and in the parent's **Sub-agents** tab, with their status updating live.
+* **The Oz API** — `GET /agent/runs/{runId}` returns the latest state of any run, and `GET /agent/runs?ancestor_run_id=PARENT_RUN_ID` lists every descendant in one call.
+
+## Messaging between agents
+
+The parent and children can exchange short, durable messages — handoffs, status updates, and final results. Use messages for coordination signals, not for piping full transcripts around: the parent's prompt to the child and the child's final output carry the work itself.
+
+## Common patterns
+
+Orchestration primitives are general-purpose. Teams typically compose them into a handful of recurring patterns.
+
+### Supervisor / worker
+
+A parent supervisor agent breaks the task into a queue of work items, spawns worker children to claim and complete each item, and writes a summary when the queue is empty. Use this when the task is naturally divisible and you want a single agent to own coordination.
+
+### Fan-out / fan-in
+
+The parent spawns N children in parallel, each with a sharded prompt (one module, one file set, one test target, one model), then waits for all of them to complete and merges their results. Use this for large refactors, repo-wide migrations, or running the same task across multiple targets.
+
+### Critic / verifier
+
+The parent (the "writer") proposes a solution, then spawns a critic child to review it. The critic returns notes; the writer revises; the cycle repeats until the critic approves or a budget is exhausted. Useful when correctness matters more than throughput.
+
+### Review swarm (cloud → cloud)
+
+A scheduled or webhook-triggered parent spawns one cloud child per open pull request to run reviews in parallel. Each child posts its findings as a comment and exits. The parent fans in the results and posts a summary back to the triggering system.
+
+### DAG
+
+The parent encodes a directed acyclic graph of subtasks where some nodes depend on the outputs of others. It spawns ready nodes, waits on their state transitions, and spawns dependents as upstream nodes complete. Use this when the workflow has explicit ordering constraints (build → test → deploy, for example).
+
+### Swarm
+
+A flat group of peer agents discover each other through messaging and coordinate without a strict hierarchy. The parent acts more like a coordinator than a supervisor. Use sparingly — swarms are powerful but harder to debug than hierarchical patterns.
+
+## Approval mode
+
+When an agent runs in `orchestrate` mode (set by the `/orchestrate` slash command or the API's `mode: orchestrate` field), the agent **proposes** an orchestration plan and waits for approval before spawning any children. Use this to review the breakdown — number of children, prompts, environments, parallelism — before any children start. Once you approve, the parent starts spawning children.
+
+`orchestrate` mode is distinct from `plan` mode. A `plan`-mode agent produces a written plan for *itself* to execute. An `orchestrate`-mode agent produces a plan for itself plus a fleet of children.
+
+## Observability
+
+Because every parent and child is a normal Oz run, the existing observability surfaces work without changes:
+
+* **[Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/)** — in the Warp app, local children appear in a child agent status card above the parent's input, while cloud children appear as their own rows in the management view.
+* **[Oz web app](/agent-platform/cloud-agents/oz-web-app/)** — the Runs page groups cloud children under the parent's row, and the parent's detail pane adds a **Sub-agents** tab.
+* **[Oz API](/reference/api-and-sdk/)** — list every descendant of a parent in one call and fetch any run with its conversation, transcript, and artifacts. See [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/#retrieving-conversations-and-artifacts).
+* **[Agent notifications](/agent-platform/capabilities/agent-notifications/)** — each child's state transitions generate notifications on the child's own conversation so you can jump straight to whichever one needs attention.
+
+## Related pages
+
+* [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/) — how to start an orchestrated run from the CLI, slash command, web app, or API.
+* [Oz API and SDK](/reference/api-and-sdk/) — REST endpoints for runs, conversations, and artifacts.
+* [Cloud agents overview](/agent-platform/cloud-agents/overview/) — what a cloud agent run is and how it fits into the Oz Platform.
+* [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns/) — higher-level deployment models that orchestration composes with.