diff --git a/readme.md b/readme.md
index c9eb95f..ecb4a0e 100644
--- a/readme.md
+++ b/readme.md
@@ -51,6 +51,52 @@ gtklock -m /usr/lib/gtklock/ahfail-module.so
     gtklock -m ahfail-module.so -- --audio-uri=file:///home/user/custom.mp3
     ```
 
+## macOS (build from source)
+
+### Prerequisites
+
+```bash
+brew install gtk+3 gstreamer gst-plugins-base gst-plugins-good meson ninja rust
+```
+
+### Build
+
+```bash
+meson setup builddir
+meson compile -C builddir
+```
+
+Produces:
+- `builddir/ahfail-module.so` — gtklock module (Wayland/Linux only)
+- `builddir/libahfail_pam.so` — PAM module (macOS + X11 Linux)
+- `builddir/ahfail-display` — display binary (spawned by PAM module)
+
+### Install
+
+```bash
+sudo mkdir -p /usr/local/lib/ahfail
+sudo cp builddir/libahfail_pam.so /usr/local/lib/ahfail/
+sudo cp builddir/ahfail-display /usr/local/lib/ahfail/
+```
+
+### Configure PAM (macOS)
+
+Add to `/etc/pam.d/screensaver` (requires `sudo`):
+
+```
+auth optional /usr/local/lib/ahfail/libahfail_pam.so
+```
+
+Place it after the existing `auth` line(s) so it observes the real auth result.
+
+### Configure PAM (Linux/X11)
+
+Add to `/etc/pam.d/gtklock` (or `i3lock`, `xscreensaver`, etc.):
+
+```
+auth optional ahfail-pam.so
+```
+
 ## Development
 
 *   **Run Tests:** `cargo test`