diff --git a/docs/how-to/update-an-instance.md b/docs/how-to/update-an-instance.md
index 06b6c8f..268f4d0 100644
--- a/docs/how-to/update-an-instance.md
+++ b/docs/how-to/update-an-instance.md
@@ -93,6 +93,15 @@ old form. `doctor` keeps warning until the migration is done, and a later sessio
 `tools/wikitool migrate status`. The agent never records a migration it did not carry out, because
 the content's version would then describe a shape the pages are not in.
 
+**A migration can also be owed per checkout.** Most migrations rewrite pages: they are done once,
+and every other clone of the instance receives the result with its next pull. The 10.0.0 migration
+moves settings instead, out of gitignored files that belong to one checkout, so a pull does not
+carry it. After another clone has pulled the new release, run `tools/wikitool config migrate`
+there too. Until then `doctor` reports each leftover file as a `FAIL`, and a command that needs
+one of those settings stops with exit 42 and names that command. `migrate done` is still recorded
+only once per instance
+([10.0.0-settings-tiers.md](../../instructions/migrations/10.0.0-settings-tiers.md)).
+
 If a step fails for a reason that isn't obvious, the agent stops and offers you a bug report rather
 than improvising ([Troubleshoot](troubleshoot.md)).