diff --git a/assets/docs/en/PLUGIN_DEV.md b/assets/docs/en/PLUGIN_DEV.md
index bb1dc864..7f59c204 100644
--- a/assets/docs/en/PLUGIN_DEV.md
+++ b/assets/docs/en/PLUGIN_DEV.md
@@ -848,6 +848,14 @@ Internal: records are stored in SQLite `disabled_plugins` table (`name`, `disabl
 > **fails silently**: no error, the tools simply vanish (the LLM cannot see them, which
 > surfaces as "reminders are gone" with nothing in the logs to explain it).
 >
+> ⚠ **Installed is not the same as in effect**: on the **old kernel**, installing the timer
+> plugin still goes through the built-in factory (`loadOne` checks `factories[name]` first and
+> never reaches `plugin.bin`), so the external build is not loaded at all —
+> `plugin_status("timer")` keeps reporting `builtin=true`, `tools=["timer_set"]`. The
+> hand-over only happens **after the kernel upgrade restarts** (the factory is gone, so the
+> external bin finally loads). Correct sequence: install to disk first, then swap the binary
+> and restart — the `plgreload` in between is a no-op.
+>
 > The external version is also a strict superset: the built-in one only had `timer_set`, and
 > in-flight countdowns were lost on restart; the external one adds `timer_list` / `timer_cancel`
 > and persists pending timers across restarts.
diff --git a/assets/docs/zh/PLUGIN_DEV.md b/assets/docs/zh/PLUGIN_DEV.md
index 3bec0242..b9d1f9a6 100644
--- a/assets/docs/zh/PLUGIN_DEV.md
+++ b/assets/docs/zh/PLUGIN_DEV.md
@@ -837,6 +837,12 @@ pmgr.ReloadPlugins()                     // 重载所有插件
 > 工具全部不存在——而且**不会报错**，只是工具悄无声息地消失（LLM 看不到它们，
 > 于是表现为「定时提醒这个功能不见了」，日志里没有任何线索）。
 >
+> ⚠ **「装上去」不等于「生效」**：在**旧内核**上安装 timer 插件时，插件装载会优先走
+> 内置工厂（`loadOne` 先查 `factories[name]`，命中就不再去看 `plugin.bin`），外部版本
+> 根本不会被加载——`plugin_status("timer")` 依然是 `builtin=true`、`tools=["timer_set"]`。
+> 真正的接管发生在**升级内核并重启之后**（内置工厂已不存在，才会动态加载外部 bin）。
+> 所以正确姿势是「先落盘安装 → 再换二进制重启」，中间那次 `plgreload` 是空动作。
+>
 > 顺带说明外部版比原内置版更强：内置版只有 `timer_set`，进程重启即在途倒计时全丢；
 > 外部版额外提供 `timer_list` / `timer_cancel`，且待触发列表跨重启保留。