docs(handoff): add local↔cloud handoff documentation

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

@@ -0,0 +1,66 @@
+---
+title: Handoff from cloud to cloud
+description: >-
+  Send a follow-up to a finished cloud run. The run continues with the prior
+  workspace state restored, so the agent picks up where it left off.
+sidebar:
+  label: "Cloud to cloud"
+---
+
+Hand off a cloud agent run to a fresh cloud session when the original session has ended but you still want to push the same unit of work further. The run continues in the same conversation, with the prior session's workspace state restored, so the agent picks up where it left off instead of starting fresh.
+
+This direction is the right move when:
+
+* A cloud agent finished and you want to send a follow-up after the session has ended.
+* You want to continue an ambient agent run — an agent that runs in the background, such as a scheduled or integration-triggered run — while preserving it as a single unit of work in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/).
+
+## What carries over
+
+When you send a follow-up to a run whose session has ended, the run continues with:
+
+* **The same conversation** - The follow-up is appended to the same conversation. From your perspective, the run is one continuous conversation across sessions.
+* **The prior workspace state** - The prior session's repository changes (tracked and untracked) are restored before the agent answers your follow-up. For git-managed sessions, the new execution runs on the same Git branch as the prior session.
+* **Stable run identity** - The run's ID, task, creator, environment, schedule trigger, and integration source are preserved. Compute usage is recorded per session but rolls up to the same run.
+
+If applying any change fails, the agent reports what couldn't be applied and proceeds with what it could before continuing to your follow-up.
+
+## Prerequisites
+
+* **An ended cloud agent run** - The run must be in a terminal state — for example, succeeded, failed, blocked, or canceled — and have an associated agent conversation. Very old runs that predate the agent conversation model can't be continued via handoff.
+* **A snapshot from the prior session** - Cloud agent runs capture a workspace snapshot at the end of each session. If the prior session couldn't capture one (for example, due to a transient storage error), the run still continues — it just starts without restored workspace state.
+* **Access to the run** - You need permission to submit follow-ups for the run. For team runs, this is typically any team member. Cloud runs that originated from a local-to-cloud handoff can be continued only by the user who created them, not by other team members.
+
+:::caution
+Cloud-to-cloud handoff relies on a snapshot from the prior execution. Older cloud runs that don't have a snapshot on file can't be handed off; start a new run instead.
+:::
+
+## Sending a follow-up
+
+You don't take a separate "hand off" action — you send a follow-up, and the run continues. The handoff happens automatically when the original session has ended. Send-follow-up support is available in the Warp app.
+
+1. **Open the ended cloud run.** Find it in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) or in the conversation panel.
+2. **Send your follow-up.** Type the next message into the conversation's input and submit it.
+
+The run picks up where it left off, with workspace state restored.
+
+### Third-party harnesses
+
+Cloud-to-cloud handoff works for third-party harnesses too, but the affordance is a **Continue** button followed by an input prompt instead of the standard follow-up input. Click **Continue** on the ended run (from the conversation details panel or the end-of-run tombstone) and enter the next message you want the agent to act on.
+
+## Inspecting a run that's been handed off
+
+The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows one row per run, even when the run spans multiple sessions. Click into the run to see the full transcript: each execution appears in order, and you can scan the transcript to see where one execution ended and the next began. Per-execution timestamps aren't currently exposed in the API; the transcript is the source of truth.
+
+## Troubleshooting
+
+**The run continued but no workspace state was restored.**
+The prior session didn't capture a snapshot. This is rare but possible — snapshot capture is best-effort. The run still continues with the same conversation, so the agent has the full transcript context even without the workspace state.
+
+**The run is in a terminal state with no conversation and follow-ups are rejected.**
+Very old runs predate the agent conversation model and can't be continued via handoff. Start a new cloud agent run with the prompt you want and reference the prior run in the prompt if needed.
+
+## Related pages
+
+* [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the directions it supports, and what carries over.
+* [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/) - Promote a local conversation to a cloud run.
+* [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Find runs to send follow-ups to.

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

@@ -0,0 +1,52 @@
+---
+title: Handoff between local and cloud agents
+description: >-
+  Move an agent conversation between your terminal and the cloud, or continue
+  a finished cloud run with workspace state restored, without re-explaining
+  the task.
+sidebar:
+  label: "Handoff overview"
+---
+
+Handoff lets you move a unit of agent work between your local Warp terminal and the cloud, or continue a finished cloud run, without re-explaining the task. The receiving agent picks up the conversation history, your workspace state, and any conversation attachments from the prior session.
+
+## Directions of handoff
+
+Handoff supports three directions:
+
+* **Local to cloud** - Promote a local Warp Agent conversation to a cloud agent run when you need more compute, longer-running work, or to fan out variants in parallel. The cloud agent starts from your conversation history and a snapshot of your uncommitted workspace changes. See [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/).
+* **Cloud to cloud** - Send a follow-up to a cloud run after its session has ended. The run continues in the same conversation, with the prior session's workspace state restored. See [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/).
+* **Cloud to local** - Fork a cloud conversation into your local terminal with **Continue locally** or `/continue-locally`. See [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/#5-fork-the-session-to-your-local-warp).
+
+### Third-party harness coverage
+
+Handoff coverage depends on which agent is running the conversation:
+
+* **Cloud to cloud** works for both the Warp Agent and third-party harnesses. On third-party harnesses, the affordance is a **Continue** button followed by an input prompt, instead of the streamlined follow-up flow you get with the Warp Agent.
+* **Local to cloud** works for the Warp Agent. It isn't available for third-party harnesses.
+
+## What carries over
+
+Handoff preserves enough state that the receiving agent can resume the work, not just read about it.
+
+* **Conversation history** - The receiving agent sees the full transcript of the prior session. Local-to-cloud forks the conversation so the source isn't modified; cloud-to-cloud continues in the same conversation.
+* **Workspace state** - Local-to-cloud and cloud-to-cloud capture the prior session's repository changes (tracked and untracked) and apply them in the receiving run before the agent answers the next prompt. The cloud-to-local direction does not currently apply workspace patches to your local checkout; review the cloud agent's branch or pull request artifact to inspect those changes.
+* **Conversation attachments** - Files attached during the prior session remain available to the receiving agent.
+
+Handoff is best-effort. When the receiving agent can apply the prior session's changes cleanly, it picks up where the prior agent left off. When it can't, the agent reports what failed and proceeds with what it could rather than starting over silently.
+
+## When to use handoff
+
+Each direction has a clear motivating workflow.
+
+* **Local to cloud** - Use when a local conversation has spiraled into work that's better done in the cloud: long-running tasks you don't want to keep your laptop awake for, parallel variants of the same task, or steering work from another device once it's running.
+* **Cloud to cloud** - Use when a cloud agent finished and you want to send a follow-up without losing the prior workspace state. Also useful when a Slack-triggered or scheduled run completes and someone on the team wants to push it further.
+* **Cloud to local** - Use when a cloud agent has done the heavy lifting and you want to take over locally to verify, iterate, or polish before shipping.
+
+## Related pages
+
+* [Cloud agents overview](/agent-platform/cloud-agents/overview/) - What cloud agents are, when to use them, and how they fit into the Oz Platform.
+* [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Inspect handoff runs from the management view alongside local conversations.
+* [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) - Open and continue a cloud run locally with **Continue locally** or `/continue-locally`.
+* [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) - How conversations sync between local and cloud so handoff can find them.
+* [Environments](/agent-platform/cloud-agents/environments/) - The runtime context a cloud agent runs in after a handoff.

src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx

@@ -0,0 +1,67 @@
+---
+title: Handoff from local to cloud
+description: >-
+  Promote a local Warp Agent conversation to a cloud agent run with the full
+  transcript and your uncommitted workspace changes — without re-explaining
+  the task.
+sidebar:
+  label: "Local to cloud"
+---
+
+Hand off a conversation from the Warp terminal to a cloud agent run when the work outgrows your local session. The cloud agent inherits a fork of your local conversation and a snapshot of your uncommitted workspace changes, so it picks up where you left off instead of starting fresh.
+
+This direction is the right move when:
+
+* The task is going to run for a long time and you don't want to keep your laptop awake.
+* You want to fan out variants of the same task across multiple cloud agents in parallel.
+* You want to walk away and check on the agent from a different device.
+* You want the agent to keep working while you start a new conversation locally.
+
+## What the cloud agent receives
+
+When you hand off from local to cloud, the receiving cloud agent inherits:
+
+* **A forked conversation** - Warp forks your local conversation so the cloud agent inherits the full transcript without modifying the source. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) for related sync behavior.
+* **A workspace snapshot** - Warp captures your uncommitted repository changes — both tracked modifications and untracked files — and packages them for the cloud agent. The cloud agent applies them before answering your follow-up.
+* **Conversation attachments** - Files attached to the local conversation remain available in the cloud run.
+
+If applying any change fails in the cloud run, the cloud agent reports what couldn't be applied and proceeds with what it could rather than silently dropping changes.
+
+## Prerequisites
+
+* **An active local conversation** - Have an [Agent](/agent-platform/local-agents/overview/) conversation open in Warp with the work you want to hand off.
+* **A configured environment** - The cloud agent needs an [environment](/agent-platform/cloud-agents/environments/) that includes the same repositories you're working in locally. The environment's repos must match your local checkout so the workspace snapshot applies cleanly.
+* **Cloud conversation storage enabled** - In the Warp app, go to **Settings** > **Privacy** and turn on **Store AI conversations in the cloud** so the conversation can be forked. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/).
+* **Sufficient credits** - Cloud agent runs consume credits. See [Credits](/support-and-community/plans-and-billing/credits/) for how credit usage works, and [Access, billing, and identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for team-specific credit requirements.
+
+## Handing off a conversation to the cloud
+
+1. **Open the handoff flow from your active conversation.** With the local conversation focused, trigger handoff with the `&` shortcut or the `/handoff` slash command. Either entry point opens the handoff flow scoped to the current conversation. The `/cloud-agent` slash command always starts a fresh cloud conversation and isn't an entry point for handoff.
+2. **Choose the environment for the cloud run.** Pick the environment whose repositories match the directories your local conversation has been editing. If you don't have a matching environment yet, create one first and add the repos you've been working in.
+3. **Add a follow-up prompt and submit.** Enter the next message you want the cloud agent to act on.
+
+:::note
+The cloud agent runs with the same model your local conversation was using. Changing the model during handoff isn't supported.
+:::
+
+After submission, the cloud agent applies your workspace snapshot and addresses your follow-up. The local conversation stays untouched — you can keep working in it locally or close it.
+
+To check on the new run, open it from the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) or the conversation panel.
+
+## Troubleshooting
+
+**The cloud agent reports that some changes couldn't be applied.**
+The most common cause is a repository mismatch between your local checkout and the environment. The workspace snapshot is generated against your local repo's current state; the environment must be on a compatible branch and commit for the changes to apply cleanly. Switch the environment's repo to the branch you were on locally and retry the handoff.
+
+**The cloud agent doesn't see my uncommitted changes.**
+Cloud conversation storage must be enabled for handoff to work. In the Warp app, open **Settings** > **Privacy** and confirm **Store AI conversations in the cloud** is on. Without it, the conversation can't be forked and the run falls back to starting fresh.
+
+**The conversation doesn't appear in the cloud run.**
+The source conversation may not have finished syncing to the cloud when you triggered the handoff. Wait a moment and retry. If the problem persists, check the conversation panel to confirm the conversation has a cloud-synced indicator.
+
+## Related pages
+
+* [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the directions it supports, and what carries over.
+* [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/) - Continue a finished cloud run with workspace state restored.
+* [Environments](/agent-platform/cloud-agents/environments/) - Configure the repos, image, and setup commands the cloud agent starts in.
+* [Cloud Agents quickstart](/agent-platform/cloud-agents/quickstart/) - Run your first cloud agent from scratch.