diff --git a/manual/31-dotfiles.md b/manual/31-dotfiles.md
index ec148b44..a81a6596 100644
--- a/manual/31-dotfiles.md
+++ b/manual/31-dotfiles.md
@@ -37,12 +37,14 @@ Omarchy fires hooks at a handful of moments, and you can hang your own scripts o
 | Event | When it runs |
 | ----- | ------------ |
 | `post-boot` | Right after the desktop has started |
-| `post-update` | During `omarchy update`, after packages and migrations |
-| `pre-refresh-pacman` | Before `omarchy refresh pacman` re-syncs the package config |
+| `post-update` | Near the end of `omarchy update`, after packages, migrations, and service restarts, before mise tools are updated |
+| `pre-refresh-pacman` | After `omarchy refresh pacman` re-syncs the package config and finishes updating packages; during a channel switch, after the package switch and complete update finish |
 | `theme-set` | After a theme change (theme name in `$1`) |
 | `font-set` | After a font change (font name in `$1`) |
 | `battery-low` | When the battery gets low (percentage in `$1`) |
 
+The `pre-refresh-pacman` name is kept for compatibility. Its edits to the refreshed package config apply to future package operations, after the current transaction has finished. Both update-related hooks run as your user after Omarchy clears its cached sudo authorization, so a hook that uses `sudo` needs its own authorization and may ask for your password.
+
 Each of those directories already holds a `.sample` file showing the shape of a hook — drop the `.sample` from the name to put it to work. To install a script you've written elsewhere, use `omarchy hook install post-boot ~/my-hook`, which copies it in and makes it executable.
 
 ### Adding your own menu entries