diff --git a/README.md b/README.md
index 46048d7..ed3d5b7 100644
--- a/README.md
+++ b/README.md
@@ -38,6 +38,48 @@ Two routes, both on by default:
   announced as `FingerMatched` for the session agent. `--standby-unlock=off`
   disables it.
 
+## Per-finger macros
+
+The trustlet reports *which* finger matched, so a finger can mean more than
+"it was you". Two files, in two trust domains:
+
+- **`~/.config/fingerprintd/fingers.conf`** runs a command as you, in your
+  session. This is how a finger opens an application.
+- **`/etc/fingerprintd/actions.conf`** runs a command as root, and can mark a
+  finger as one that never unlocks.
+
+### In your session: `fingers.conf`
+
+```
+# ~/.config/fingerprintd/fingers.conf
+right-ring-finger    kde-open camera
+left-index-finger    plasma-settings
+left-thumb           sh -c 'notify-send "hello from a finger"'
+```
+
+- using these requires the fingerprintd-agent service to be running.
+
+### As root: `actions.conf`
+
+```
+# /etc/fingerprintd/actions.conf
+# <finger>  [no-unlock]  [absolute command...]
+right-ring-finger    /usr/local/bin/toggle-something
+left-little-finger   no-unlock  /etc/fingerprintd/panic.sh
+left-thumb           no-unlock
+```
+
+- `no-unlock`: the finger matches and the client is told it did not. PAM
+  sees `verify-no-match`, the standby unlock stays locked. The command, if
+  there is one, runs regardless.
+- the command: an absolute path, run by root through `/bin/sh -c` with a
+  fixed `PATH` and `FINGERPRINTD_FINGER` set to the finger's name, detached
+  from the daemon with its stdio on `/dev/null`, so it may block or reboot
+  the phone without stalling the sensor.
+- a line needs at least one of the two, and a finger gets at most one line.
+- editing this file requires a restart of the fingerprintd service before changes take effect.
+
+
 ## Runtime dependencies
 
 The `focal64` trustlet is proprietary and is not in this repo. It is