Fix HDMI recovery dispatches for Lua Hyprland sessions

docs/troubleshooting.md

@@ -36,6 +36,22 @@ Expected: your numeric UID, `Type=wayland`, `Active=yes`, `Seat=seat0`, a VT fro
 1 to 63, and either a Hyprland desktop or an empty Desktop property. The helper
 also checks these properties when invoked manually.
 
+## Hyprland refresh failed / Lua syntax error
+
+Version 0.2.0 sent legacy dispatch commands even to Lua-configured sessions.
+On Hyprland 0.56.2 this produced `')' expected near 'on'` and aborted recovery
+before the VT switch. Update to 0.2.1 with `./scripts/install.sh --start`.
+
+The helper now reads `hyprctl -j status` to choose the active config provider.
+For Lua it sends `hl.dsp.dpms({ action = "on", monitor = "HDMI-A-2" })` and
+`hl.dsp.focus({ monitor = "HDMI-A-2" })` through `hyprctl dispatch`. The configured
+output replaces `HDMI-A-2`. Legacy hyprlang and older versions remain supported.
+See the official [hyprctl documentation](https://wiki.hypr.land/configuring/core/advanced-configuration/using-hyprctl/)
+and [dispatchers](https://wiki.hypr.land/configuring/core/dispatchers/).
+
+The journal identifies `DPMS` or `focus`, the command's exit status and its error
+response. A zero exit status with an error response is also treated as failure.
+
 ## Invalid runtime directory
 
 `XDG_RUNTIME_DIR` must be your login-managed, user-owned directory with mode 0700