Merge branch 'main' into 'patch-1'

# Conflicts:
#   content/docs/fossvr/envision/_index.md

content/docs/fossvr/envision/_index.md

@@ -15,6 +15,10 @@ Envision is a graphical app that acts as an orchestrator to get a full [Monado](
 
 Envision attempts to construct a working runtime with both a native OpenXR and an OpenVR API, provided by [OpenComposite](/docs/fossvr/opencomposite/), for client aplications to utilize. Please note the OpenVR implementation is incomplete and contains only what's necessary to run most games for compatibility. If you plan to implement software, utilize the OpenXR API, specification [here](https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html).
 
+{{% hint danger %}}
+We recommend **against** using Envision if your distro is NixOS. See [our NixOS page](/docs/distros/nixos/#envision) for more info.
+{{% /hint %}}
+
 You can download the latest AppImage snapshot from [GitLab Pipelines](https://gitlab.com/gabmus/envision/-/pipelines?ref=main&status=success).
 
 If you are on Arch, You can use the [AUR package](https://aur.archlinux.org/packages/envision-xr-git) `envision-xr-git`
@@ -65,6 +69,27 @@ For example, if you installed WlxOverlay-S from AUR or built it from source, you
 
 Now starting the profile will also start your custom or AUR version of WlxOverlay-S.
 
+### Plugin troubleshooting
+
+On some systems, a built-in plugin may not launch. This can happen for a number of reasons, but one in particular is so obtuse that it's worth a mention:
+
+Please *uninstall* AppImageLauncher. It intercepts the normal AppImage starting behavior in a dirty way that we can't predict.
+
+You can tell if you are affected if, when you run the WlxOverlay-S AppImage in terminal (whether in plugin form in `~/.local/share/envision/plugins`, or downloaded directly from GitHub), you only get the output `execv error: No such file or directory`.
+
+## Steam Flatpak
+
+To use Envision with the Flatpak version of Steam, you'll need to add the following filesystem overrides to Steam using an application like Flatseal:
+- `xdg-data/envision:ro`
+- `xdg-run/monado_comp_ipc`
+- `xdg-config/openxr:ro`
+- `xdg-config/openvr:ro`
+
+Alternatively, you can use the following command:
+```shell
+flatpak override --filesystem="xdg-data/envision:ro" --filesystem="xdg-run/monado_comp_ipc" --filesystem="xdg-config/openxr:ro" --filesystem="xdg-config/openvr:ro" com.valvesoftware.Steam
+```
+
 ## Experimental feature settings
 
 The following resources can be entered into your Envision profile repo and branch settings to enable early access to code before it's fully upstream in Monado itself. To enable these feature sets, simply clone your profile, edit it with these settings, then build.

content/docs/fossvr/envision/wmr_controllers_on_arch.md

@@ -67,3 +67,12 @@ paru -S envision-xr-git
     - Leave Monado open.
     - Start the new game.
 - Always turn on the controllers **before** starting Envision.
+
+- Update controller firmware while running Windows. It's necessary for controllers to work in Linux, updating them from Linux is currently impossible.
+- Make sure that you **don't factory-reset the controllers** (performed by long-pressing the pairing button when controllers are off). This action restores the factory firmware version.
+- If monado fails to start with the following error, you likely need to update the firmware in Mixed Reality Portal:
+    ```
+    WARN [wmr_controller_send_fw_cmd] Controller fw read timed out after 250 ms
+    ERROR [wmr_bt_controller_create] WMR Controller (Bluetooth): Failed to create controller
+    ERROR [wmr_create_bt_controller] Failed to create WMR controller (Bluetooth)
+    ```