diff --git a/README.md b/README.md
index f411a92..53f4ced 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,81 @@
 # zbm-regen-pacman-hook
 
-Arch Linux pacman hook to automatically regenerate ZFSBootMenu image files after upgrades
\ No newline at end of file
+Arch Linux pacman hook to automatically recreate ZFSBootMenu images after upgrades.
+
+# Setup
+
+> Not explicitly listed here as a step but still relevant: This `pacman` hook only makes sense if you're using ZFSBootMenu images and have the homonymous `zfsbootmenu` package installed.
+
+Get started like so:
+
+1. Clone repo into arbitrary path `<repo>`
+1. Symlink to hook file, for example
+    ```
+    sudo ln -s <repo>/pacman-zbm-image-regen.hook /usr/share/libalpm/hooks/pacman-zbm-image-regen.hook
+    ```
+
+# What's it do?
+
+In `pacman` whenever the `zfsbootmenu` package or your kernel are getting updated this hook will regenerate the ZFSBootMenu image via `generate-zbm` which will in turn store a new file in its image path as configured in `/etc/zfsbootmenu/config.yaml`.
+
+This happens as a `PostTransaction` in `pacman`.
+
+# Assumptions
+
+This hook is intended to work with [quico.space/quico-os-setup/arch-zbm](https://quico.space/quico-os-setup/arch-zbm), a root-on-ZFS installation script that uses ZFSBootMenu as its boot loader. Before using this hook for any purpose other than an `arch-zbm` Arch Linux installation please closely review what it does and adapt to your use case as needed.
+
+This hook is working on `arch-zbm` machines that use either UEFI or legacy BIOS.
+
+The `zfsbootmenu` package and `generate-zbm` binary in particular don't care where newly generated images need to be stored. After an `arch-zbm` installation you're left with an `/etc/zfsbootmenu/config.yaml` file that instructs `generate-zbm` to store new image files in a sensible location.
+
+## UEFI vs. legacy BIOS
+
+On a UEFI system new ZFSBootMenu images are named `vmlinuz.EFI` and `vmlinuz-backup.EFI`. EFI boot loader entries can and do remain static to always looks for these two exact EFI image file names.
+
+On a legacy BIOS machine ZFSBootMenu creates split images: One `vmlinuz-bootmenu(-backup)` kernel and one `initramfs-bootmenu(-backup).img` initrd. Here, too, your `/boot/syslinux/syslinux.cfg` config file can and does remain static to always look for these exact file names.
+
+## Triggers
+
+The hook triggers on several `pacman` events:
+1. An upgrade of `zfsbootmenu` package
+1. Upgrades or installation on files that match:
+    ```
+    Target = usr/lib/modules/*/vmlinuz
+    Target = usr/lib/modules/*/extramodules/*
+    ```
+1. All `pacman` operations on files that match:
+    ```
+    Target = boot/*-ucode.img
+    Target = usr/lib/booster/*
+    Target = usr/lib/initcpio/*
+    Target = usr/lib/initcpio/*/*
+    Target = usr/lib/dracut/*
+    Target = usr/lib/dracut/*/*
+    Target = usr/lib/dracut/*/*/*
+    Target = usr/lib/kernel/*
+    Target = usr/lib/kernel/*/*
+    Target = usr/src/*/dkms.conf
+    ```
+
+# Development
+
+## Conventional commits
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/) for its commit messages.
+
+### Commit types
+
+Commit _types_ besides `fix` and `feat` are:
+
+- `build`: Project structure, directory layout, build instructions for roll-out
+- `refactor`: Keeping functionality while streamlining or otherwise improving function flow
+- `test`: Working on test coverage
+- `docs`: Documentation for project or components
+
+### Commit scopes
+
+The following _scopes_ are known for this project. A Conventional Commits commit message may optionally use one of the following scopes or none:
+
+- `script`: Work related to commands triggered by `pacman`
+- `hook`: Configuring the hook(s)
+- `meta`: Affects the project's repo layout, readme content, file names etc.
diff --git a/pacman-zbm-image-regen.hook b/pacman-zbm-image-regen.hook
new file mode 100644
index 0000000..b204692
--- /dev/null
+++ b/pacman-zbm-image-regen.hook
@@ -0,0 +1,34 @@
+[Trigger]
+Operation = Upgrade
+Type = Package
+Target = zfsbootmenu
+
+[Trigger]
+Type = Path
+Operation = Install
+Operation = Upgrade
+Target = usr/lib/modules/*/vmlinuz
+Target = usr/lib/modules/*/extramodules/*
+
+[Trigger]
+Type = Path
+Operation = Install
+Operation = Upgrade
+Operation = Remove
+Target = boot/*-ucode.img
+Target = usr/lib/booster/*
+Target = usr/lib/initcpio/*
+Target = usr/lib/initcpio/*/*
+Target = usr/lib/dracut/*
+Target = usr/lib/dracut/*/*
+Target = usr/lib/dracut/*/*/*
+Target = usr/lib/kernel/*
+Target = usr/lib/kernel/*/*
+Target = usr/src/*/dkms.conf
+
+[Action]
+Description = Regen ZFSBootMenu image
+When = PostTransaction
+Exec = /usr/bin/generate-zbm
+Depends = zfsbootmenu
+AbortOnFail