diff --git a/README.md b/README.md
index c0bb419..59de6a4 100644
--- a/README.md
+++ b/README.md
@@ -24,3 +24,25 @@ Commands:
     xy logs <name> [--tail N] [--follow]
 
 Exit codes: 0 success, 1 operational error, 2 daemon unreachable, 3 config invalid.
+
+## Start on login (macOS)
+
+    xy service install     # write the LaunchAgent, load it, start the daemon
+    xy service uninstall   # unload and remove the agent
+    xy service start       # load an installed agent
+    xy service stop        # unload until the next login
+    xy service status      # show agent state
+
+`xy service install` snapshots the current `PATH` into the agent, because a
+launchd agent otherwise inherits only `/usr/bin:/bin:/usr/sbin:/sbin` and
+supervised servers would not find their toolchains. Re-run with `--force`
+after installing a new toolchain to refresh the snapshot.
+
+`xy service stop` lasts until the next login. To disable start-on-login
+permanently, use `xy service uninstall`.
+
+The daemon writes to `$XDG_STATE_HOME/xy/logs/xy.log`. Failures that happen
+before the daemon starts logging — a missing binary, a malformed plist — are
+visible only to launchd:
+
+    launchctl print gui/$UID/se.aceofba.xy