diff --git a/docs/src/content/docs/features/self-upgrade.md b/docs/src/content/docs/features/self-upgrade.md
index fb97f56de..76cf173a0 100644
--- a/docs/src/content/docs/features/self-upgrade.md
+++ b/docs/src/content/docs/features/self-upgrade.md
@@ -121,6 +121,32 @@ squad upgrade --self --skip-repo-upgrade
 
 *(This flag may not exist yet — just showing the pattern. For now, self-upgrade always runs repo upgrade.)*
 
+### Your Customizations Are Backed Up
+
+`squad upgrade` overwrites Squad-owned files with the latest templates. Before it overwrites a file you've edited locally, it saves your version alongside it as `<file>.local-backup` and prints a warning.
+
+This covers `.github/agents/squad.agent.md` and the Squad-managed workflow files in `.github/workflows/`.
+
+```text
+⚠  squad.agent.md has local customizations — backed up to squad.agent.md.local-backup
+   To restore: copy squad.agent.md.local-backup → squad.agent.md
+⚠  squad-ci.yml has local customizations — backed up to squad-ci.yml.local-backup
+```
+
+To restore your version, copy the backup back over the refreshed file:
+
+```bash
+cp .github/agents/squad.agent.md.local-backup .github/agents/squad.agent.md
+```
+
+Three things worth knowing:
+
+- **Version stamps don't count as customizations.** The `<!-- squad-cli vX.Y.Z -->` line in `squad.agent.md` changes on every release, so it's stripped before comparing. A file that differs only by its version stamp is refreshed silently, with no backup.
+- **Only the most recent backup is kept.** Backups are written to a fixed path, so re-customizing a file and upgrading again overwrites the previous `.local-backup`. Move anything you want to keep somewhere safe before your next upgrade.
+- **Backups aren't gitignored.** They show up as untracked files in `git status`. Delete them once you've merged back what you need.
+
+`squad upgrade --dry-run` previews the upgrade and will tell you if `squad.agent.md` would be backed up. It stops short of the workflow files, so it won't flag customized workflows — check those yourself before upgrading if you've edited them.
+
 ---
 
 ## Permission Errors
diff --git a/docs/src/content/docs/reference/cli.md b/docs/src/content/docs/reference/cli.md
index e4810ab70..b7001c7b2 100644
--- a/docs/src/content/docs/reference/cli.md
+++ b/docs/src/content/docs/reference/cli.md
@@ -39,7 +39,7 @@ squad init
 | `squad start [--tunnel] [--port N] [--command cmd]` | Start Copilot with remote phone access via PTY and WebSocket | No |
 | `squad status` | Show which squad is active and why | Yes |
 | `squad doctor` | Validate squad setup integrity and diagnose issues (alias: `heartbeat`) | Yes |
-| `squad upgrade` | Upgrade Squad-owned files to latest version | Yes |
+| `squad upgrade` | Upgrade Squad-owned files to latest version; locally customized files are saved as `<file>.local-backup` | Yes |
 | `squad upgrade --state-backend <type>` | Migrate state backend (`orphan`, `two-layer`); installs git hooks automatically | Yes |
 | `squad upgrade --migrate-directory` | Rename legacy `.ai-team/` directory to `.squad/` | Yes |
 | `squad triage` | Auto-triage issues and assign to team (primary name; `watch` is an alias) | Yes |