wiki: Update Xwayland-related info

3 files changed, 27 insertions, 38 deletions

diff --git a/docs/wiki/FAQ.md b/docs/wiki/FAQ.md
index 4a9c9181..40bacfa4 100644
--- a/docs/wiki/FAQ.md
+++ b/docs/wiki/FAQ.md
@@ -60,9 +60,9 @@ A combination of factors:
 
 All in all, the situation works out in favor of avoiding Xwayland integration.
 
-Also, in the next release niri will have seamless built-in xwayland-satellite integration, that will solve the big rough edge of having to set it up manually.
+<sup>Since: next release</sup> niri has seamless built-in xwayland-satellite integration that by and large works as well as built-in Xwayland in other compositors, solving the hurdle of having to set it up manually.
 
-Besides, I wouldn't be too surprised if, down the road, xwayland-satellite becomes the standard way of integrating Xwayland into new compositors, since it takes on the bulk of the annoying work, and isolates the compositor from misbehaving clients.
+I wouldn't be too surprised if, down the road, xwayland-satellite becomes the standard way of integrating Xwayland into new compositors, since it takes on the bulk of the annoying work, and isolates the compositor from misbehaving clients.
 
 ### Can I enable blur behind semitransparent windows?
 
diff --git a/docs/wiki/Integrating-niri.md b/docs/wiki/Integrating-niri.md
index 5ec2a69f..455e476e 100644
--- a/docs/wiki/Integrating-niri.md
+++ b/docs/wiki/Integrating-niri.md
@@ -20,7 +20,7 @@ Xwayland is required for running X11 apps and games, and also the Orca screen re
 <sup>Since: next release</sup> Niri integrates with [xwayland-satellite](https://github.com/Supreeeme/xwayland-satellite) out of the box.
 The integration requires xwayland-satellite >= 0.7 available in `$PATH`.
 Please consider making niri depend on (or at least recommend) the xwayland-satellite package.
-If you had a custom config which manually started `xwayland-satellite` and set `DISPLAY`, you should remove those customizations for the automatic integration to work.
+If you had a custom config which manually started `xwayland-satellite` and set `$DISPLAY`, you should remove those customizations for the automatic integration to work.
 
 You can change the path where niri looks for xwayland-satellite using the [`xwayland-satellite` top-level option](./Configuration:-Miscellaneous.md#xwayland-satellite).
 
diff --git a/docs/wiki/Xwayland.md b/docs/wiki/Xwayland.md
index b709e283..51cd30af 100644
--- a/docs/wiki/Xwayland.md
+++ b/docs/wiki/Xwayland.md
@@ -1,48 +1,37 @@
-X11 is very cursed, so built-in Xwayland support [is not planned at the moment](./FAQ.md#why-doesnt-niri-integrate-xwayland-like-other-compositors).
-However, there are multiple solutions to running X11 apps in niri.
-
 ## Using xwayland-satellite
 
-[xwayland-satellite] implements rootless Xwayland in a separate application, without the host compositor's involvement.
-It makes X11 windows appear as normal windows, just like a native Xwayland integration.
-xwayland-satellite works well with most applications: Steam, games, Discord, even more exotic things like Ardour with wine Windows VST plugins.
-However, X11 apps that want to position windows or bars at specific screen coordinates won't behave correctly.
+<sup>Since: next release</sup>
 
-> [!NOTE]
-> In the next release, niri will have [built-in xwayland-satellite integration](./Configuration:-Miscellaneous.md#xwayland-satellite).
-> You can try it by installing git versions of both niri and xwayland-satellite.
-> With no further configuration, niri will create X11 sockets, then when an X11 client connects, automatically start xwayland-satellite.
->
-> This matches how other compositors run Xwayland (but in niri's case, it's xwayland-satellite rather than Xwayland itself).
-> It also makes X11 apps work fine in `spawn-at-startup` and in XDG autostart.
+Niri integrates with [xwayland-satellite](https://github.com/Supreeeme/xwayland-satellite) out of the box.
+Ensure xwayland-satellite >= 0.7 is installed and available in `$PATH`.
+With no further configuration, niri will create X11 sockets on disk, export `$DISPLAY`, and spawn xwayland-satellite on-demand when an X11 client connects.
+If xwayland-satellite dies, niri will automatically restart it.
 
-Install it from your package manager, or build it according to instructions from its README, then run the `xwayland-satellite` binary.
-Look for a log message like: `Connected to Xwayland on :0`.
-Now you can start X11 applications on this X11 DISPLAY:
+If you had a custom config which manually started `xwayland-satellite` and set `$DISPLAY`, you should remove those customizations for the automatic integration to work.
 
-```
-env DISPLAY=:0 flatpak run com.valvesoftware.Steam
+To check that the integration works, verify that the niri output says something like `listening on X11 socket: :0`:
+
+```sh
+$ journalctl --user-unit=niri -b
+systemd[2338]: Starting niri.service - A scrollable-tiling Wayland compositor...
+niri[2474]: 2025-08-29T04:07:40.043402Z  INFO niri: starting version 25.05.1 (0.0.git.2345.d9833fc1)
+(...)
+niri[2474]: 2025-08-29T04:07:40.690512Z  INFO niri: listening on Wayland socket: wayland-1
+niri[2474]: 2025-08-29T04:07:40.690520Z  INFO niri: IPC listening on: /run/user/1000/niri.wayland-1.2474.sock
+niri[2474]: 2025-08-29T04:07:40.700137Z  INFO niri: listening on X11 socket: :0
+systemd[2338]: Started niri.service - A scrollable-tiling Wayland compositor.
+$ echo $DISPLAY
+:0
 ```
 
 ![xwayland-satellite running Steam and Half-Life.](https://github.com/user-attachments/assets/57db8f96-40d4-4621-a389-373c169349a4)
 
-You can also automatically run it at startup, and set `DISPLAY` by default for all apps by adding it to the [`environment`](./Configuration:-Miscellaneous.md#environment) section of the niri config:
-
-```kdl
-spawn-at-startup "xwayland-satellite"
-// Or, if you built it by hand:
-// spawn-at-startup "~/path/to/code/target/release/xwayland-satellite"
+We're using xwayland-satellite rather than Xwayland directly because [X11 is very cursed](./FAQ.md#why-doesnt-niri-integrate-xwayland-like-other-compositors).
+xwayland-satellite takes on the bulk of the work dealing with the X11 peculiarities from us, giving niri normal Wayland windows to manage.
 
-environment {
-    DISPLAY ":0"
-}
-```
-
-> [!NOTE]
-> If the `:0` DISPLAY is already taken (for example, by some other Xwayland server like `xwayland-run`), `xwayland-satellite` will try the next DISPLAY numbers in order: `:1`, `:2`, etc. and tell you which one it used in its output.
-> Then, you will need to use that DISPLAY number for the `env` command or for the niri [`environment`](./Configuration:-Miscellaneous.md#environment) section.
->
-> You can also force a specific DISPLAY number like so: `xwayland-satellite :12` will start on `DISPLAY=:12`.
+xwayland-satellite works well with most applications: Steam, games, Discord, even more exotic things like Ardour with wine Windows VST plugins.
+However, X11 apps that want to position windows or bars at specific screen coordinates won't behave correctly and will need a nested compositor to run.
+See sections below for how to do that.
 
 ## Using the labwc Wayland compositor