docs: explain sync-branch worktree behavior (GH#510)

Add comprehensive documentation about beads-created worktrees:
- New section in WORKTREES.md explaining why and where beads creates worktrees
- Common confusion: 'beads took over main!' with solution
- Troubleshooting entries for 'branch already checked out' errors
- FAQ entry: 'Why did beads create worktrees in my .git directory?'

This addresses user confusion when beads' sync-branch feature creates
internal worktrees that can lock branches users want to checkout.

Closes #510

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs/FAQ.md

@@ -426,7 +426,33 @@ bd ready
 bd create "Fix bug" -p 1
 ```
 
-See [ADVANCED.md#git-worktrees](ADVANCED.md#git-worktrees) for details.
+See [WORKTREES.md](WORKTREES.md) for details.
+
+### Why did beads create worktrees in my .git directory?
+
+Beads automatically creates git worktrees when using the **sync-branch** feature. This happens when you:
+- Run `bd init --branch <name>`
+- Set `bd config set sync.branch <name>`
+
+The worktrees allow beads to commit issue updates to a separate branch without switching your working directory.
+
+**Location:** `.git/beads-worktrees/<sync-branch>/`
+
+**Common issue:** If you see "branch already checked out" errors when switching branches, remove the beads worktrees:
+
+```bash
+rm -rf .git/beads-worktrees
+rm -rf .git/worktrees/beads-*
+git worktree prune
+```
+
+**To disable sync-branch (stop worktree creation):**
+
+```bash
+bd config set sync.branch ""
+```
+
+See [WORKTREES.md#beads-created-worktrees-sync-branch](WORKTREES.md#beads-created-worktrees-sync-branch) for full details.
 
 ### What's the difference between SQLite corruption and ID collisions?
 

docs/TROUBLESHOOTING.md

@@ -342,7 +342,52 @@ chmod +x .git/hooks/post-merge
 chmod +x .git/hooks/post-checkout
 ```
 
-Or use the installer: `cd examples/git-hooks && ./install.sh`
+### "Branch already checked out" when switching branches
+
+**Symptom:**
+```bash
+$ git checkout main
+fatal: 'main' is already checked out at '/path/to/.git/beads-worktrees/beads-sync'
+```
+
+**Cause:** Beads creates git worktrees internally when using the sync-branch feature (configured via `bd init --branch` or `bd config set sync.branch`). These worktrees lock the branches they're checked out to.
+
+**Solution:**
+```bash
+# Remove beads-created worktrees
+rm -rf .git/beads-worktrees
+rm -rf .git/worktrees/beads-*
+git worktree prune
+
+# Now you can checkout the branch
+git checkout main
+```
+
+**Permanent fix (disable sync-branch):**
+```bash
+bd config set sync.branch ""
+```
+
+See [WORKTREES.md#beads-created-worktrees-sync-branch](WORKTREES.md#beads-created-worktrees-sync-branch) for details.
+
+### Unexpected worktree directories in .git/
+
+**Symptom:** You notice `.git/beads-worktrees/` or `.git/worktrees/beads-*` directories you didn't create.
+
+**Explanation:** Beads automatically creates these worktrees when using the sync-branch feature to commit issue updates to a separate branch without switching your working directory.
+
+**If you don't want these:**
+```bash
+# Disable sync-branch feature
+bd config set sync.branch ""
+
+# Clean up existing worktrees
+rm -rf .git/beads-worktrees
+rm -rf .git/worktrees/beads-*
+git worktree prune
+```
+
+See [WORKTREES.md](WORKTREES.md) for details on how beads uses worktrees.
 
 ### Auto-sync not working
 

docs/WORKTREES.md

@@ -8,6 +8,102 @@ Beads now provides **enhanced Git worktree support** with a shared database arch
 
 **Note:** While comprehensively implemented and tested internally, this feature may benefit from real-world usage feedback to identify any remaining edge cases.
 
+---
+
+## Beads-Created Worktrees (Sync Branch)
+
+**Important:** Beads automatically creates git worktrees internally for its sync-branch feature. This is different from user-created worktrees for parallel development.
+
+### Why Beads Creates Worktrees
+
+When you configure a **sync branch** (via `bd init --branch <name>` or `bd config set sync.branch <name>`), beads needs to commit issue updates to that branch without switching your working directory away from your current branch.
+
+**Solution:** Beads creates a lightweight worktree that:
+- Contains only the `.beads/` directory (sparse checkout)
+- Lives in `.git/beads-worktrees/<sync-branch>/`
+- Commits issue changes to the sync branch automatically
+- Leaves your main working directory untouched
+
+### Where to Find These Worktrees
+
+```
+your-project/
+├── .git/
+│   ├── beads-worktrees/          # Beads-created worktrees live here
+│   │   └── beads-sync/           # Default sync branch worktree
+│   │       └── .beads/
+│   │           └── issues.jsonl  # Issue data committed here
+│   └── worktrees/                # Standard git worktrees directory
+├── .beads/                       # Your working copy
+│   ├── beads.db                  # Local SQLite database
+│   └── issues.jsonl              # Local JSONL (may differ from sync branch)
+└── src/                          # Your code (untouched by sync)
+```
+
+### Common Confusion: "Beads took over main!"
+
+If you see worktrees pointing to `main` and can't switch branches normally, this is likely because:
+
+1. Your sync branch was created from `main`
+2. Beads created a worktree for that branch
+3. Git worktrees lock branches they're checked out to
+
+**Symptoms:**
+```bash
+$ git checkout main
+fatal: 'main' is already checked out at '/path/to/.git/beads-worktrees/beads-sync'
+```
+
+**Quick Fix:**
+```bash
+# Remove the beads worktree
+rm -rf .git/beads-worktrees
+
+# Prune stale worktree references
+git worktree prune
+
+# Also remove any stray worktrees in .git/worktrees (older versions)
+rm -rf .git/worktrees/beads-*
+git worktree prune
+```
+
+### Disabling Sync Branch (Remove Worktrees)
+
+If you don't want beads to use a separate sync branch:
+
+```bash
+# Unset the sync branch configuration
+bd config set sync.branch ""
+
+# Stop and restart daemon
+bd daemon stop
+bd daemon start
+
+# Clean up existing worktrees
+rm -rf .git/beads-worktrees
+git worktree prune
+```
+
+### Checking Your Sync Branch Configuration
+
+```bash
+# See current sync branch setting
+bd config get sync.branch
+
+# Check if worktrees exist
+ls -la .git/beads-worktrees/ 2>/dev/null || echo "No beads worktrees"
+ls -la .git/worktrees/ 2>/dev/null || echo "No standard worktrees"
+
+# List all git worktrees
+git worktree list
+```
+
+### See Also
+
+For complete sync-branch documentation, see [PROTECTED_BRANCHES.md](PROTECTED_BRANCHES.md).
+
+---
+
 ## How It Works
 
 ### Shared Database Architecture
@@ -156,6 +252,42 @@ bd create "Fix password validation" -t bug -p 0
 
 ## Troubleshooting
 
+### Issue: "Branch already checked out" error
+
+**Symptoms:**
+```bash
+$ git checkout main
+fatal: 'main' is already checked out at '/path/to/.git/beads-worktrees/beads-sync'
+```
+
+**Cause:** Beads created a worktree for its sync branch feature, and that worktree has your target branch checked out. Git doesn't allow the same branch to be checked out in multiple worktrees.
+
+**Solution:**
+```bash
+# Remove beads worktrees
+rm -rf .git/beads-worktrees
+rm -rf .git/worktrees/beads-*
+
+# Clean up git's worktree registry
+git worktree prune
+
+# Now you can checkout the branch
+git checkout main
+```
+
+**Prevention:** If you use trunk-based development and don't need a separate sync branch, disable it:
+```bash
+bd config set sync.branch ""
+```
+
+### Issue: Unexpected worktree directories appeared
+
+**Symptoms:** You notice `.git/beads-worktrees/` or entries in `.git/worktrees/` that you didn't create.
+
+**Cause:** Beads automatically creates worktrees when using the sync-branch feature (configured via `bd init --branch` or `bd config set sync.branch`).
+
+**Solution:** See [Beads-Created Worktrees](#beads-created-worktrees-sync-branch) section above for details on what these are and how to remove them if unwanted.
+
 ### Issue: Daemon commits to wrong branch
 
 **Symptoms:** Changes appear on unexpected branch in git history