diff --git a/README.md b/README.md
index 552cbf5..9737fa8 100644
--- a/README.md
+++ b/README.md
@@ -35,7 +35,7 @@ and nothing to re-apply after somebody else's release.
 | `themes/` | colour themes |
 | `config/` | shipped app configs |
 | `shell.json` | bar layout and idle timings |
-| `hooks/` | event hooks, such as retinting on theme change |
+| `hooks/` | optional user hook templates (`.sample`), copied to `~/.config/blob/hooks` and run by `blob-hook` once renamed |
 | `branding/` | icon, ASCII art, boot splash |
 | `wallpapers/` | 103 wallpapers, previewed in [the gallery](wallpaper-gallery/index.md) |
 | `session/` | wayland session entry and uwsm environment |
@@ -53,6 +53,7 @@ and nothing to re-apply after somebody else's release.
 | [widgets.md](docs/widgets.md) | the ported GTK widgets and where they went |
 | [menu.md](docs/menu.md) | the menu tree and what was trimmed |
 | [install.md](docs/install.md) | what the installer does, step by step |
+| [hooks.md](docs/hooks.md) | the optional user hooks and when each one runs |
 | [packages.md](docs/packages.md) | leaving the Omarchy repository, and updating |
 | [upstream.md](docs/upstream.md) | the fork base, for diffing later |
 
diff --git a/bin/blob-update b/bin/blob-update
index c134f2e..5ea4cb9 100755
--- a/bin/blob-update
+++ b/bin/blob-update
@@ -233,3 +233,5 @@ show_summary
 notify_body="System and AUR packages are up to date"
 [[ $reboot_needed == true ]] && notify_body="$notify_body. Reboot to use the new kernel."
 blob-notify-send "Update complete" "$notify_body"
+
+blob-hook post-update
diff --git a/docs/hooks.md b/docs/hooks.md
new file mode 100644
index 0000000..27fa19c
--- /dev/null
+++ b/docs/hooks.md
@@ -0,0 +1,24 @@
+# Hooks
+
+Hooks are optional scripts you write to run your own commands when something in
+Blob happens. None ship active: `hooks/` holds only `.sample` templates, the
+installer copies them to `~/.config/blob/hooks/`, and `blob-hook` skips any file
+ending in `.sample`. Blob's own behaviour, such as recolouring apps on a theme
+change, is built into its scripts and never depends on a hook.
+
+To use one, copy the sample without the suffix and edit it:
+
+```
+cp ~/.config/blob/hooks/theme-set.sample ~/.config/blob/hooks/theme-set
+```
+
+`blob-hook <name>` runs `~/.config/blob/hooks/<name>` and then every file in
+`~/.config/blob/hooks/<name>.d/`, so several scripts can share one event. A
+failing hook prints a message and never stops the command that called it.
+
+| Hook | Run by | Argument |
+| --- | --- | --- |
+| `theme-set` | `blob-theme-set`, after a theme is applied | theme name |
+| `font-set` | `blob-font-set`, after the font changes | font name |
+| `battery-low` | `blob-battery-low` | battery percentage |
+| `post-update` | `blob-update`, after a successful update | none |
diff --git a/hooks/post-update.sample b/hooks/post-update.sample
index a43ba64..56a9801 100644
--- a/hooks/post-update.sample
+++ b/hooks/post-update.sample
@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# This hook is called after an Blob system update has been performed.
+# This hook is called after `blob update` finishes successfully.
 # To put it into use, remove .sample from the name.
 
 # Example: Show notification after the system has been updated.