docs(cli): cloud handoff and orchestration

src/content/docs/cli/cloud-and-orchestration.mdx

@@ -1,27 +1,99 @@
 ---
-title: "Cloud handoff and orchestration in the {{WARP_CLI}}"
+title: "Cloud handoff and orchestration in the Warp Agent CLI"
 description: >-
-  Hand off {{WARP_CLI}} conversations to cloud agents, resume cloud runs, and
-  run multi-agent orchestration from your terminal.
+  Hand off Warp Agent CLI conversations to cloud agents, resume cloud runs,
+  and run multi-agent orchestration from your terminal.
 ---
 import { VARS } from '@data/vars';
 
-{/* TODO(cli-cloud-orchestration): draft per drafts/warp-cli-launch-plan.md — "cli/cloud-and-orchestration.mdx" section. Feature-doc content type. */}
-
-The {VARS.WARP_CLI} documentation for this page is in progress.
+The {VARS.WARP_CLI} connects your terminal sessions to the Oz Platform. You can hand off a local conversation to a cloud agent, pick a finished cloud run back up in your terminal, and coordinate multiple agents working in parallel, all without leaving the CLI.
 
 ## Hand off to a cloud agent
 
-{/* TODO(cli-cloud-orchestration): /handoff flow, what context carries over; cross-link platform/handoff. */}
+Handoff promotes your current CLI conversation into a cloud agent run. Use it when a task outgrows your machine: long-running work you don't want to keep your laptop awake for, or work you want to check on later from another device. The [Handoff overview](/platform/handoff/) explains the feature across all Warp surfaces; this section covers the CLI flow.
+
+The cloud agent receives the same context as a handoff from the Warp app:
+
+* **Conversation history** - Warp forks the conversation, so the cloud agent sees the full transcript and your local conversation stays untouched.
+* **Workspace changes** - Warp snapshots your uncommitted repository changes, including untracked files, and applies them in the cloud run.
+* **Pending input** - The optional follow-up prompt and any images attached to the input move to the cloud run.
+
+See [what carries over](/platform/handoff/#what-carries-over) for the full behavior, and [Handoff from local to cloud](/platform/handoff/local-to-cloud/) for prerequisites such as cloud conversation storage and an [environment](/platform/environments/) whose repos match your local checkout.
+
+### Hand off a conversation
+
+1. In an active conversation, run `/handoff`, or `/handoff <prompt>` to give the cloud agent a follow-up prompt. The **Hand off to cloud** card replaces the input area while your transcript stays visible.
+2. The card suggests your most recent environment (preferring one that contains the current repository) and keeps your conversation's model when it can run in the cloud; incompatible models are flagged so you can choose another before continuing.
+3. To change either value, press `Ctrl+E` to open the searchable environment and model selectors.
+4. Press `Enter` on the card summary to hand off. The card shows progress, then reports that the cloud run was created along with a link to the run.
+
+From the created card:
+
+* `Enter` opens the cloud run in your browser.
+* `C` continues the conversation locally. The card collapses into a transcript banner with the run link, and the input reopens.
+* `N` starts a new conversation.
+
+Press `Ctrl+C` at any point before confirming to cancel the handoff; your prompt and attachments return to the input.
+
+:::note
+If you have no cloud environments yet, the card prompts you to create one: `Enter` opens the <a href={`${VARS.WEB_APP_URL}/environments`}>Environments page in the {VARS.WEB_APP}</a>, and `R` refreshes the list after you create one.
+:::
+
+Handoff needs the conversation in a state it can fork. You can't hand off while a command the agent started is still running, or while the conversation has child agents that are in progress or blocked. Cancel the command or let the children finish first. Handing off an orchestrator forks only its own conversation; the orchestration and its child agents stay local.
 
 ## Resume cloud conversations
 
-{/* TODO(cli-cloud-orchestration): continuing cloud runs in the CLI (--resume, conversation list). */}
+Finished cloud agent runs appear in the CLI's conversation history alongside local conversations, so you can pull a cloud run into your terminal and keep working on it.
+
+1. Press `←` in an empty input, or run `/conversations`, to open the conversation list.
+2. Select a cloud run. Your next prompt continues the conversation locally.
+
+Two constraints apply:
+
+* **The run must be finished** - Cloud runs that are still in progress or blocked can't be opened in the CLI. Steer those from the browser instead; see [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/).
+* **Warp Agent runs only** - Conversations that ran with a different harness, such as Claude Code or Codex, can't be opened in the CLI.
+
+You can also open a conversation directly at startup with `warp --resume <token>`; [Managing conversations in the CLI](/cli/conversations/) covers conversation history and resume details.
 
 ## Multi-agent orchestration
 
-{/* TODO(cli-cloud-orchestration): orchestrating child agents from the CLI, tab bar navigation; cross-link platform/orchestration. */}
+Orchestration lets one conversation spawn child agents that work in parallel, on your machine or in the cloud. The CLI runs the same parent/child model as the rest of the platform; [Multi-agent orchestration](/platform/orchestration/) covers the model, run states, and common patterns.
+
+To start an orchestration, ask the agent to parallelize the work, for example "split this migration across three agents". When the agent decides to spawn child agents, the CLI shows an approval card titled **Can I start additional agents for this task?** that summarizes the agents it wants to launch and the run-wide configuration. No child agents launch until you approve.
+
+From the approval card:
+
+* `Enter` approves the request and launches the child agents.
+* `Ctrl+E` edits the configuration first: where the agents run (on your machine or in the cloud) and which model they use. Cloud agents add pages for the harness, environment, and host, plus an API key page for harnesses that need one.
+* `Ctrl+C` rejects the request.
+
+After launch, a tab bar labeled **Agents:** appears above the session with one tab for the orchestrator and one tab per child agent. Messages between the parent and child agents appear in each agent's transcript.
+
+* **Local child agents** - Each local child runs on your machine as its own session, starting in the parent's working directory. Local children always run the Warp Agent.
+* **Cloud child agents** - Each cloud child runs in a cloud [environment](/platform/environments/). Its session shows the run's live status and a link; press `Enter` or click the link to open the run in the {VARS.WEB_APP}. If a cloud child can't start because GitHub authentication is required, its session shows the authentication link; authenticate, then ask the agent to run the orchestration again.
+
+:::caution
+Cloud child sessions in the CLI are read-only status views. To send prompts to a cloud child or respond to its approvals, open the run in the {VARS.WEB_APP}.
+:::
 
 ## Managing child agents
 
-{/* TODO(cli-cloud-orchestration): switching between child agents, stopping a child agent. */}
+The **Agents:** tab bar is how you move around an orchestration.
+
+* **Focus the tab bar** - Press `Shift+↑` from the input. The bar highlights the active conversation.
+* **Switch agents** - `Tab` or `→` selects the next agent and `Shift+Tab` or `←` the previous one, wrapping across the orchestrator and all children. `Shift+←` and `Shift+→` jump to the first and last child. Switching keeps the bar focused so you can keep cycling.
+* **Return to the conversation** - `↓` moves focus back to the current session's input. `Esc` jumps back to the orchestrator.
+* **Use the mouse** - Tabs are clickable, and when there are more children than fit, arrows at the ends of the bar page through them without changing your selection.
+
+Each agent keeps its own session. Transcript position, input drafts, and running work are all preserved while you view another agent, and child agents keep working in the background. Tabs reorder as statuses change, moving children that need attention, such as blocked ones, toward the front of the bar.
+
+A focused local child behaves like a regular conversation: send it follow-up prompts, respond to its permission requests, and press `Ctrl+C` to stop its in-progress response. If a child's tab shows a blocked status, switch to that child to respond to its pending request.
+
+## Related pages
+
+* [Handoff overview](/platform/handoff/) - Directions of handoff and what carries over in each.
+* [Handoff from local to cloud](/platform/handoff/local-to-cloud/) - Prerequisites, the Warp app flow, and troubleshooting.
+* [Multi-agent orchestration](/platform/orchestration/) - The parent/child model, run states, and orchestration patterns.
+* [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open, inspect, and continue cloud runs in the {VARS.WEB_APP}.
+* [Managing conversations in the CLI](/cli/conversations/) - Conversation history, `/conversations`, and `--resume`.
+* [Environments](/platform/environments/) - Configure the repos, image, and setup commands cloud agents run with.