Import initial Hyprland HDMI recovery implementation

docs/troubleshooting.md

@@ -0,0 +1,139 @@
+# Troubleshooting
+
+## Check the Hyprland output name
+
+```bash
+hyprctl monitors
+```
+
+Update:
+
+```text
+~/.config/revive-monitor/config.env
+```
+
+if the output is not `HDMI-A-2`.
+
+## Check the user service
+
+```bash
+systemctl --user status revive-monitor-drm-watch.service
+```
+
+## Follow logs
+
+```bash
+journalctl --user -u revive-monitor-drm-watch.service -f
+```
+
+For the recovery script tag:
+
+```bash
+journalctl --user -t revive-monitor-fix -f
+```
+
+## Verify DRM hotplug events manually
+
+```bash
+udevadm monitor --kernel --property --subsystem-match=drm
+```
+
+Switch the physical monitor input away and back. Look for:
+
+```text
+HOTPLUG=1
+```
+
+If no DRM hotplug event is emitted, this project has no reliable event to trigger from.
+
+## Verify the active Wayland session
+
+```bash
+loginctl list-sessions
+```
+
+Then:
+
+```bash
+for s in $(loginctl list-sessions --no-legend | awk '{print $1}'); do
+    echo "=== Session $s ==="
+    loginctl show-session "$s" -p Name -p Type -p Active -p VTNr
+done
+```
+
+A normal Hyprland session should look similar to:
+
+```text
+Name=your-user
+VTNr=1
+Type=wayland
+Active=yes
+```
+
+## Display manager appears only after manually switching TTY
+
+Check the boot journal:
+
+```bash
+journalctl -b --no-pager | grep -E 'revive-monitor|COMMAND=/usr/bin/chvt|chvt'
+```
+
+If `chvt` runs before login, verify that you installed the current watcher script. It must ignore hotplug events when there is no active Wayland session.
+
+Expected pre-login behavior:
+
+```text
+No active Wayland session - DRM hotplug ignored
+```
+
+## sudo / chvt fails
+
+Test non-interactively:
+
+```bash
+sudo -n /usr/bin/chvt 2
+```
+
+If sudo asks for a password or exits with an error, verify:
+
+```text
+/etc/sudoers.d/revive-monitor-chvt
+```
+
+Always edit sudoers files with `visudo`.
+
+## Recovery runs multiple times
+
+Increase:
+
+```bash
+DEBOUNCE_SECONDS=30
+```
+
+in:
+
+```text
+~/.config/revive-monitor/config.env
+```
+
+For noisy hardware, `60` may be more appropriate.
+
+## Recovery runs but the monitor still stays black
+
+Increase:
+
+```bash
+HDMI_SETTLE_SECONDS=5
+```
+
+to `7` or `10` and test again.
+
+Also manually verify that a VT switch actually restores the image:
+
+```bash
+sudo chvt 2
+sleep 1
+sudo chvt 1
+```
+
+Adjust the numbers to match the machine's graphical VT.