diff --git a/AGENTS.md b/AGENTS.md
index b452cff..794fd77 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,6 +18,8 @@ Agent-specific entry files (`CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructi
 
 The Makefile is the only executable contract in this repository. CI calls make targets; customize the Makefile, never the workflows. Two exceptions, neither of which puts adopter values in the YAML: runner selection, which GitHub resolves before any make target exists to be called — set the `RUNNER_LABELS` repository variable instead of editing `runs-on` (see `docs/setup/runners.md`); and event handlers that need the token or payload, whose logic lives in `scripts/*.js` behind a thin `github-script` caller and is tested by `make check` (the issue labeler, the PR lint; ADR-0008).
 
+If this repository deliberately differs from the template it was created from, record each difference in `docs/template-drift.md` — the file, what differs, why — and update it in the PR that adds or removes one. A template sync preserves what that list names. (The template itself has no such file.)
+
 | Level | Name | Command | When required |
 | --- | --- | --- | --- |
 | L0 | static | `make lint` | every PR |
diff --git a/docs/template/upgrading.md b/docs/template/upgrading.md
index 0f17adb..467ad25 100644
--- a/docs/template/upgrading.md
+++ b/docs/template/upgrading.md
@@ -13,7 +13,7 @@ Repositories created from a template share no git history with it, so updates ar
    git remote add template https://github.com/OWNER/TEMPLATE-REPO.git
    git config remote.template.tagOpt --no-tags
    git fetch template '+refs/tags/*:refs/template-tags/*'
-   git diff HEAD refs/template-tags/vX.Y.Z -- .github/ skills/ Makefile scripts/
+   git diff HEAD refs/template-tags/vX.Y.Z -- .github/ skills/ Makefile scripts/ AGENTS.md
    ```
 
    The template's tags go under `refs/template-tags/`, never `refs/tags/`: the
@@ -53,7 +53,7 @@ Repositories created from a template share no git history with it, so updates ar
    `git tag vX.Y.Z <sha>`.
 
 3. Cherry-pick what you want by path. Good candidates: `skills/`, `.github/workflows/` (the labeler workflow only calls code that lives elsewhere — take them together with `scripts/issue-labeler.js`, `scripts/pr-lint.js`, their `*.test.js`, `scripts/check-node-tests.sh`, `scripts/check-label-forms.sh` and the two `check:` lines in the Makefile; `make check` fails if a workflow requires a `scripts/*.js` that is not there; if you graft the `Lint the pull request` step into a customized `ci.yml` instead of taking the file, take the `ci` job's `permissions:` block too — `issues: read` and `pull-requests: read` are what let the lint read the linked issue on a private repository), `scripts/check-*.sh` (rarely customized locally). Careful candidates: `Makefile` (your `test` target lives there), `.github/labels.yml` (your renamed `area:*` labels), `AGENTS.md` (your conventions).
-4. Apply as a normal PR through your own CI. Never bulk-overwrite customized files.
+4. Apply as a normal PR through your own CI. Never bulk-overwrite customized files — see the drift-file rule in [AGENTS.md](../../AGENTS.md#build-and-validation).
 5. Re-run `scripts/bootstrap.sh` if the update changed `labels.yml` or the ruleset — it syncs GitHub-side state to the files.
 
 ## What never gets pulled