diff --git a/README.md b/README.md
index 969e47f..1f52b3e 100644
--- a/README.md
+++ b/README.md
@@ -42,10 +42,17 @@ The plugin lands in `~/.config/omarchy/plugins/nerdnation.clockbar/`, and
 To update it later, and to remove it:
 
 ```bash
-omarchy plugin update nerdnation.clockbar
+omarchy plugin update nerdnation.clockbar && omarchy restart shell
 omarchy plugin remove nerdnation.clockbar
 ```
 
+**The `omarchy restart shell` is not optional.** `omarchy plugin update` pulls
+the new files and calls `rescanPlugins`, but that does not reload a
+`keepLoaded` panel plugin: the shell holds the compiled QML it started with, so
+the files on disk change and the bar carries on running the old build. It looks
+exactly like the update silently failing. Restarting the shell is what actually
+applies it.
+
 > Plugins run as unsandboxed QML inside `omarchy-shell`, so `omarchy plugin add`
 > clones disabled by default and wants you to read the code first. `--enable`
 > skips that.