Document successful HDMI hardware validation for 0.2.1

docs/hardware-validation.md

@@ -0,0 +1,51 @@
+# Hardware validation
+
+## Confirmed on 2026-09-23
+
+Version 0.2.1 was installed and the systemd user watcher restarted on the
+following setup:
+
+| Component | Tested configuration |
+| --- | --- |
+| Desktop | Arch Linux, Hyprland 0.56.2 |
+| Configuration provider | Lua (`hyprctl -j status`) |
+| Session | Local Wayland session on seat0, graphical VT1 |
+| Display | iiyama PL3288UH, 3840 × 2160 at 60 Hz |
+| Output | `HDMI-A-2` |
+| Timing | 5 s HDMI settle, 1 s temporary VT, 2 s return settle, 30 s cooldown |
+
+The original failure was reproduced: legacy DPMS/focus commands returned Lua
+syntax errors and stopped recovery before the VT switch. Both corrected Lua
+commands returned `ok` on the running compositor.
+
+After installation, a complete manual recovery returned to graphical VT1 and
+reported:
+
+```text
+revive-monitor-fix: Recovery started for HDMI-A-2 on VT 1
+revive-monitor-fix: Using lua dispatch syntax
+revive-monitor-fix: VT refresh: 2 -> 1
+revive-monitor-fix: Recovery completed for HDMI-A-2
+```
+
+The watcher remained active. The operator then tested physical HDMI input
+switching and confirmed that recovery worked successfully.
+
+## Automated validation
+
+- All 30 behavioral tests passed, including Lua and legacy dispatch syntax,
+  refresh failures, session guards, VT return handling and installer behavior.
+- Bash syntax checks and ShellCheck 0.11.0 passed.
+- Installer archive and ZIP contents matched; ZIP integrity, Base64 round-trip
+  and release checksums were verified.
+
+## Scope and remaining checks
+
+This confirms the normal HDMI input-switch path on the setup above. It does
+not establish compatibility with every monitor or GPU.
+
+The operator had reported that the earlier unwanted tty switching was gone.
+A dedicated cold-boot/pre-login check and logout/login cycle after the 0.2.1
+update have not been separately confirmed. Rapid away/back switching inside
+the cooldown also remains a separate test; such events can be suppressed by
+design. See [the hardware acceptance procedure](troubleshooting.md#hardware-acceptance).