add turnstile info

src/config/services/user-services.md

@@ -2,10 +2,16 @@
 
 Sometimes it can be nice to have user-specific runit services. For example, you
 might want to open an ssh tunnel as the current user, run a virtual machine, or
-regularly run daemons on your behalf. The most common way to do this is to
-create a system-level service that runs
+regularly run daemons on your behalf.
+
+## runsvdir
+
+The most basic way to do this is to create a system-level service that runs
 [runsvdir(8)](https://man.voidlinux.org/runsvdir.8) as your user, in order to
-start and monitor the services in a personal services directory.
+start and monitor the services in a personal services directory. This does have
+limitations and downsides, though, as per-user services are started at boot and
+do not have access to things like the user's graphical session or D-Bus session
+bus.
 
 For example, you could create a service called `/etc/sv/runsvdir-<username>`
 with the following `run` script, which should be executable:
@@ -46,3 +52,48 @@ ok: run: gpg-agent: (pid 19818) 0s
 
 It may be convenient to export the `SVDIR=~/service` variable in your shell
 profile.
+
+## turnstile
+
+[Turnstile](https://github.com/chimera-linux/turnstile) supports running
+per-user services that start with the user session using either runit or
+[dinit(8)](https://man.voidlinux.org/man8/dinit.8).
+
+If using the runit service backend, user services should be placed in
+`~/.config/service/`.
+
+To ensure that a subset of services are started before login can proceed, these
+services can be listed in `~/.config/service/turnstile-ready/conf`, for example:
+
+```
+core_services="dbus foo"
+```
+
+The `turnstile-ready` service is created by turnstile on first login.
+
+To give user services access to important environment variables,
+[chpst(8)](https://man.voidlinux.org/chpst.8)'s envdir functionality can be
+used. Inside user services, the convenience variable `TURNSTILE_ENV_DIR` can be
+used to refer to this directory.
+
+To make a service aware of these variables, wrap the `exec` line with `chpst -e
+"$TURNSTILE_ENV_DIR"`:
+
+```
+exec chpst -e "$TURNSTILE_ENV_DIR" foo
+```
+
+The helper script `turnstile-update-runit-env` can be used to update variables
+in this shared envdir:
+
+```
+$ turnstile-update-runit-env DISPLAY XAUTHORITY FOO=bar BAZ=
+```
+
+To run the [D-Bus session bus](../session-management.md#d-bus) using a
+turnstile-managed user service:
+
+```
+$ mkdir -p ~/.config/service/dbus
+$ ln -s /usr/share/examples/turnstile/dbus.run ~/.config/service/dbus/run
+```

src/config/session-management.md

@@ -37,8 +37,31 @@ to consider before installing elogind.
 To make use of its features, install the `elogind` package and make sure the
 [system D-Bus](#d-bus) is enabled. You might need to log out and in again.
 
-If you're having any issues with elogind, [enable](./services/index.md) its
-service, as waiting for a D-Bus activation can lead to issues.
+If you're having any issues with elogind,
+[enable](./services/index.md#enabling-services) its service, as waiting for a
+D-Bus activation can lead to issues.
+
+## turnstile
+
+[turnstile](https://github.com/chimera-linux/turnstile) is an alternative
+session manager, and can be used with or without [elogind](#elogind).
+
+If using turnstile with elogind, disable rundir (`XDG_RUNTIME_DIR`) management
+in `/etc/turnstile/turnstiled.conf` by setting `manage_rundir` to `no`. Note
+that while elogind and turnstile currently can coexist, this may change in the
+future.
+
+If using turnstile without elogind, consider installing and enabling
+[seatd](#seatd) for seat management and [acpid](./power-management.md#acpid) for
+power management.
+
+To use it, [enable](./services/index.md#enabling-services) the `turnstiled`
+service and re-log in.
+
+Turnstile can also manage [per-user
+services](./services/user-services.md#turnstile) (including running a [D-Bus
+session bus](#d-bus)), removing the need for wrapping graphical sessions with
+`dbus-run-session`.
 
 ## seatd
 
@@ -59,8 +82,8 @@ Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-
 Its value sets the path to the base directory where programs should store
 user-specific runtime files.
 
-Install [elogind](#elogind) as your session manager to automatically set up
-`XDG_RUNTIME_DIR`.
+Install [elogind](#elogind) or [turnstile](#turnstile) as your session manager
+to automatically set up `XDG_RUNTIME_DIR`.
 
 Alternatively, manually set the environment variable through the shell. Make
 sure to create a dedicated user directory and set its permissions to `700`. A