## TL;DR
Restore the staging branch from its pre-deploy state, then change preview deploys to target ephemeral preview URLs instead of branches. Protect the staging branch so the agent's deploy role cannot push to it.

## The exact error
```text
docs preview deploy overwrote staging branch
```

## Steps
1. **Recover staging**
   Reset the staging branch to its last good commit from the reflog or the remote's history.
   Success check: Staging is back to its pre-deploy state.
2. **Move previews off branches**
   Point preview deploys at ephemeral preview URLs or a dedicated previews directory, never at a shared branch.
   Success check: Previews no longer touch shared branches.
3. **Protect the branch**
   Enable branch protection on staging denying pushes from the agent's deploy role.
   Success check: The agent physically cannot overwrite staging again.
4. **Verify the deploy flow**
   Run a preview deploy and confirm it lands on the preview target while staging is untouched.
   Success check: Previews work and staging is safe.

## When to use
- Use when an agent's deploy step writes to the wrong branch.
- Use when designing deploy permissions for doc agents.

## When not to use
- Not for content errors in a correctly targeted deploy.
- Not for preview deploys that fail to build.

## Why it happens
Agents treat branches as generic deploy targets; without protection, a misconfigured target overwrites whatever branch is named. Staging branches are especially vulnerable because they look like natural preview targets.

## Edge cases
Branch protection is the durable fix; getting the target right in config is necessary but not sufficient. Ephemeral preview URLs also avoid the branch-naming collisions that shared preview branches create.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_SgRwDqiE6BrrE8D9gMXEGg