diff --git a/README.md b/README.md
index fad05cb..2dbbd28 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,15 @@
-## User Units
-[Arch Wiki](https://wiki.archlinux.org/index.php/Systemd/User)
+# User systemd configuration
+
+This repository owns user services, timers and session targets. Shell
+configuration may request these units or consume their output, but background
+work and lifecycle management remain here.
+
+See [user/README.md](user/README.md) for unit groups, activation commands and
+cross-repository interfaces. Remote-mount design and operating notes live in
+[MOUNTS.md](MOUNTS.md).
+
+After changing a unit, reload the user manager:
+
+```sh
+systemctl --user daemon-reload
+```
diff --git a/user/README.md b/user/README.md
index eced92f..df6abf4 100644
--- a/user/README.md
+++ b/user/README.md
@@ -1,17 +1,98 @@
-# README
+# User units
 
-## proxy@.service
+This directory contains the user services, timers and targets supervised by
+`systemd --user`. Unit files are the source of truth for exact commands and
+dependencies; this README records their purpose and operational interfaces.
 
+## Package status
+
+`package-status-refresh.timer` becomes due two minutes after boot and then
+every 30 minutes. It runs the static oneshot service
+`package-status-refresh.service`, which calls `package-status-refresh.sh`.
+
+The refresher:
+
+- uses `checkupdates` with a dedicated temporary package database;
+- counts repository updates and local orphan packages;
+- avoids reading while Pacman holds its database lock;
+- discards results if a package transaction overlaps the check;
+- preserves the previous valid cache after network or mirror failures; and
+- atomically replaces `~/.cache/package-status/status` on success.
+
+`~/.cache/package-status/last-attempt` supports the shell's five-minute retry
+backoff. Exit status 75 means Pacman was active or local package state changed
+during the refresh; the service treats that as an expected outcome.
+
+The Bash repository reads the cache without blocking terminal startup. Its
+status module may request a non-blocking refresh when the cache is stale. The
+profile repository's Arch `update` function does the same after a successful
+upgrade.
+
+Enable and inspect the timer with:
+
+```sh
+systemctl --user enable --now package-status-refresh.timer
+systemctl --user list-timers package-status-refresh.timer
+systemctl --user status package-status-refresh.service
+journalctl --user -u package-status-refresh.service
+```
+
+The refresher requires Pacman, Fakeroot and `checkupdates` from
+`pacman-contrib`.
+
+## Mango session
+
+`mango-session.target` groups graphical services that require an initialized
+Wayland session. Mango starts the target after importing its display and D-Bus
+environment into the user manager.
+
+Target members are:
+
+- `waybar.service`
+- `swww.service`
+- `blueman-applet.service`
+- `polkit-gnome-agent.service`
+- `gcr-prompter.service`
+- `gnome-keyring-session.service`
+- `swayidle.service`
+- `mango-tag-osd.service`
+
+Stopping the target stops its `PartOf=` services with the compositor session.
+
+## Audio and speech
+
+- `audio-resume-monitor.service` watches logind for resume events and runs
+  `audio-resume-recover.sh` to rebuild PipeWire/Bluetooth audio state.
+- `kokoro.service` supervises the persistent local Kokoro text-to-speech
+  server and follows the PipeWire lifecycle.
+
+## Mounts and backups
+
+Remote storage units include the Wasabi S3 mounts, encrypted Wasabi data mount
+and Ultra.cc rclone mount. `wasabi-data-crypt.target` keeps the encrypted mount
+available for interactive use. See `../MOUNTS.md` for mount architecture and
+operating details.
+
+`backup-pass.timer` runs at 10:00 and 22:00. Its service requires the encrypted
+Wasabi data mount and copies timestamped KeePass database backups using
+`backup-pass.sh`.
+
+## SSH proxies
+
+`proxy@.service` starts mutually exclusive SOCKS proxy profiles defined in
+`~/.ssh/config`:
+
+```sh
 systemctl --user start proxy@alice
 systemctl --user start proxy@red
+systemctl --user stop proxy@red
+```
 
-`~/.ssh/config` is where the proxy configs are stored.
+Add new mutually exclusive instances to the template unit's `Conflicts=` list.
 
-`Conflicts=` is where to add new proxies to make them mutually exclusive.
+`socks-red.service` is a separate persistent SOCKS proxy on
+`127.0.0.1:1188` using `ray@red.isnet.uk`:
 
-## socks-red.service
-
-systemctl --user daemon-reload
+```sh
 systemctl --user enable --now socks-red.service
-
-This opens a SOCKS proxy on `127.0.0.1:1188` using `ray@red.isnet.uk`.
+```