From 3fae21c7a4e4203381da966726b809400521ba84 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Asger=20Geel=20Weirs=C3=B8e?= <github@weircon.dk>
Date: Wed, 6 May 2026 15:31:29 +0200
Subject: [PATCH] docs: add binary install section for Linux, Homebrew section
 for macOS
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Linux x86_64 binary install covers both Wayland and X11 from the same
tarball — clarified with a table showing which file is used by which.

macOS section now leads with Homebrew (brew tap + brew install) as the
recommended path, with script and manual install as fallbacks.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 readme.md | 81 +++++++++++++++++++++++++++++++------------------------
 1 file changed, 46 insertions(+), 35 deletions(-)

diff --git a/readme.md b/readme.md
index 2576f6c..b248141 100644
--- a/readme.md
+++ b/readme.md
@@ -16,19 +16,40 @@ The **gtklock module** is Wayland-only — it uses gtklock's internal window API
 
 ---
 
+## Linux (x86\_64) — binary install
+
+Pre-built binaries for both Wayland and X11 are available on the [releases page](https://gitea.weircon.dk/agw/gtk-ahfail/releases). The tarball contains all three files:
+
+| File | Used by |
+|---|---|
+| `ahfail-module.so` | Wayland — loaded by `gtklock` |
+| `libahfail_pam.so` | X11 — loaded by PAM |
+| `ahfail-display` | X11 — spawned by the PAM module |
+
+```bash
+# Download and extract (replace v0.1.0 with the latest release)
+curl -fsSL https://gitea.weircon.dk/agw/gtk-ahfail/releases/download/v0.1.0/ahfail-linux-x86_64.tar.gz \
+  | sudo tar -xz -C /tmp/ahfail-install
+
+# Wayland (gtklock)
+sudo install -Dm755 /tmp/ahfail-install/ahfail-module.so /usr/lib/gtklock/ahfail-module.so
+
+# X11 (PAM module + display binary)
+sudo install -Dm755 /tmp/ahfail-install/libahfail_pam.so /usr/lib/ahfail/libahfail_pam.so
+sudo install -Dm755 /tmp/ahfail-install/ahfail-display   /usr/lib/ahfail/ahfail-display
+```
+
+Then follow the [Wayland](#linux--wayland-gtklock) or [X11](#linux--x11-i3lock-xscreensaver-etc) configuration below.
+
+---
+
 ## Linux — Wayland (gtklock)
 
-### Install dependencies (Arch)
+### Install dependencies and build from source (Arch)
 
 ```bash
 sudo pacman -S meson ninja rust gtk3 gstreamer gst-plugins-base gst-plugins-good gst-plugins-bad gtklock
-```
-
-### Build and install
-
-```bash
-meson setup builddir
-meson compile -C builddir
+meson setup builddir && meson compile -C builddir
 sudo meson install -C builddir
 ```
 
@@ -87,7 +108,18 @@ auth optional /usr/lib/ahfail/libahfail_pam.so display_path=/usr/lib/ahfail/ahfa
 
 ## macOS
 
-### Quick install (recommended)
+### Homebrew (recommended)
+
+```bash
+brew tap agw/ahfail https://gitea.weircon.dk/agw/homebrew-ahfail
+brew install ahfail
+```
+
+After install, Homebrew prints the PAM line to add to `/etc/pam.d/screensaverui` (macOS 13+) or `/etc/pam.d/screensaver` (macOS 12 and earlier). That one-line edit is the only manual step.
+
+To upgrade: `brew upgrade ahfail`.
+
+### Script install
 
 ```bash
 git clone https://gitea.weircon.dk/agw/gtk-ahfail.git
@@ -95,40 +127,19 @@ cd gtk-ahfail
 bash scripts/install-macos.sh
 ```
 
-The script installs Homebrew dependencies, builds from source, copies binaries to `/usr/local/lib/ahfail/`, and patches the screensaver PAM configuration automatically.
+Installs Homebrew dependencies, builds from source, copies binaries to `/usr/local/lib/ahfail/`, and patches the screensaver PAM configuration automatically.
 
 ### Manual install
 
-#### Prerequisites
-
 ```bash
 brew install gtk+3 gstreamer gst-plugins-base gst-plugins-good meson ninja
-```
-
-Rust: install via [rustup.rs](https://rustup.rs) if not already present.
-
-#### Build
-
-```bash
-meson setup builddir
-meson compile -C builddir
-```
-
-#### Install
-
-```bash
+# install Rust via https://rustup.rs if not present
+meson setup builddir && meson compile -C builddir
 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/
+sudo cp builddir/libahfail_pam.so builddir/ahfail-display /usr/local/lib/ahfail/
 ```
 
-#### Configure PAM
-
-Find the screensaver PAM service file:
-- macOS 13 (Ventura) and later: `/etc/pam.d/screensaverui`
-- macOS 12 and earlier: `/etc/pam.d/screensaver`
-
-Add this line after the existing `auth` entries (requires `sudo`):
+Add to `/etc/pam.d/screensaverui` (macOS 13+) or `/etc/pam.d/screensaver` after the existing `auth` entries:
 
 ```
 auth optional /usr/local/lib/ahfail/libahfail_pam.so