Fix HDMI recovery dispatches for Lua Hyprland sessions

docs/architecture.md

@@ -11,7 +11,10 @@ active graphical VT. It is intended for one local Hyprland session on `seat0`.
    timestamps are not read from shared files or affected by wall-clock changes.
 4. The synchronous recovery helper locks, independently identifies the active
    session, waits for HDMI settling, checks the Hyprland IPC output and refreshes
-   DPMS/focus. The instance signature comes from the Hyprland startup hook.
+   DPMS/focus. `hyprctl -j status` selects Lua or legacy hyprlang dispatch syntax;
+   versions without the query use legacy commands. Dispatches must return `ok`
+   with exit status zero, otherwise their error is logged and recovery aborts.
+   The instance signature comes from the Hyprland startup hook.
 5. Before switching, the helper rechecks session identity and VT and checks sudo
    permission for both directions. It rechecks session identity after those calls.
 6. The helper sets an EXIT/signal trap, switches to VT2 (when graphical VT=1) or

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