diff --git a/.changeset/docs-plugin-spec-onupgrade-example.md b/.changeset/docs-plugin-spec-onupgrade-example.md
new file mode 100644
index 0000000000..54dab453c9
--- /dev/null
+++ b/.changeset/docs-plugin-spec-onupgrade-example.md
@@ -0,0 +1,5 @@
+---
+---
+
+docs: fix the plugin-spec CHANGELOG example that still taught the retired
+`onUpgrade` hook as running automatically (#4212 family). Releases nothing.
diff --git a/content/docs/protocol/kernel/plugin-spec.mdx b/content/docs/protocol/kernel/plugin-spec.mdx
index 9fe567b07a..1c420e7d3b 100644
--- a/content/docs/protocol/kernel/plugin-spec.mdx
+++ b/content/docs/protocol/kernel/plugin-spec.mdx
@@ -859,8 +859,8 @@ Always include migration guide in CHANGELOG.md for major versions.
 - `account.owner` field (use `account.owner_id` instead)
 
 ### Migration
-The `onUpgrade` lifecycle hook runs automatically when the package is upgraded
-to v2.0.0 and renames the field on existing records.
+Upgrading to v2.0.0 applies the metadata migration that renames the field on
+existing records (ADR-0087). No plugin code runs at upgrade.
 ```
 
 ### 3. Pin Core Dependencies