diff --git a/docs/guide.md b/docs/guide.md
index 816af1d..8ba7143 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -228,7 +228,18 @@ This:
 
 This establishes **shared commit ancestry** between josh's filtered view and the subrepo. Without this, josh-proxy can't compute diffs between the two.
 
-> **Warning:** This is a destructive force-push that replaces the subrepo's history. Back up any important branches or tags in the subrepo beforehand.
+> **Warning:** This is a destructive force-push that replaces the subrepo's history. Back up any important branches or tags in the subrepo beforehand. Merge or close all open pull requests on the subrepo first — they will be invalidated.
+
+After reset, **every developer with a local clone of the subrepo** must update their local copy to match the new history:
+
+```bash
+cd /path/to/local-subrepo
+git fetch origin
+git checkout main && git reset --hard origin/main
+git checkout stage && git reset --hard origin/stage   # repeat for each branch
+```
+
+Or simply delete and re-clone the subrepo. Local-only branches (not pushed to the remote) will be lost either way.
 
 ### 5d. Repeat for each target
 
@@ -471,6 +482,24 @@ The subfolder already contains the same content as the subrepo. This is fine —
 
 Verify `bot.trailer` in config matches what's in commit messages. Check the loop guard in the CI workflow is active.
 
+### "cannot lock ref" or "expected X but got Y"
+
+**After reset (subrepo):** The subrepo's history was replaced by force-push. Local clones still have the old history:
+
+```bash
+cd /path/to/subrepo
+git fetch origin
+git checkout main && git reset --hard origin/main
+```
+
+Or simply delete and re-clone.
+
+**After import/reset cycle (monorepo):** The import and reset steps create and update branches rapidly (`auto-sync/import-*`, `josh-sync-state`). If your local clone fetched partway through, tracking refs go stale:
+
+```bash
+git remote prune origin && git pull
+```
+
 ### State issues
 
 ```bash