2 files changed, 35 insertions, 0 deletions
diff --git a/wiki/Configuration:-Miscellaneous.md b/wiki/Configuration:-Miscellaneous.md
index 1dacb988..3eba0a31 100644
--- a/wiki/Configuration:-Miscellaneous.md
+++ b/wiki/Configuration:-Miscellaneous.md
@@ -36,6 +36,11 @@ overview {
     }
 }
 
+xwayland-satellite {
+    // off
+    path "xwayland-satellite"
+}
+
 clipboard {
     disable-primary
 }
@@ -207,6 +212,28 @@ overview {
 }
 ```
 
+### `xwayland-satellite`
+
+<sup>Since: next release</sup>
+
+Settings for integration with [xwayland-satellite](https://github.com/Supreeeme/xwayland-satellite).
+
+When a recent enough xwayland-satellite is detected, niri will create the X11 sockets and set `DISPLAY`, then automatically spawn `xwayland-satellite` when an X11 client tries to connect.
+If Xwayland dies, niri will keep watching the X11 socket and restart `xwayland-satellite` as needed.
+This is very similar to how built-in Xwayland works in other compositors.
+
+`off` disables the integration: niri won't create an X11 socket and won't set the `DISPLAY` environment variable.
+
+`path` sets the path to the `xwayland-satellite` binary.
+By default, it's just `xwayland-satellite`, so it's looked up like any other non-absolute program name.
+
+```kdl
+// Use a custom build of xwayland-satellite.
+xwayland-satellite {
+    path "~/source/rs/xwayland-satellite/target/release/xwayland-satellite"
+}
+```
+
 ### `clipboard`
 
 <sup>Since: 25.02</sup>
diff --git a/wiki/Xwayland.md b/wiki/Xwayland.md
index 487a882c..1bc6b9ca 100644
--- a/wiki/Xwayland.md
+++ b/wiki/Xwayland.md
@@ -8,6 +8,14 @@ It makes X11 windows appear as normal windows, just like a native Xwayland integ
 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.
 
+> [!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.
+
 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: