docs(gui): VM smoke recipe for the first-run modal

gui/FIRSTRUN-TESTING.md

@@ -0,0 +1,53 @@
+# Testing the First-Run Modal (Phase 10)
+
+Phase 10's user-visible flow can only be exercised against a real GTK
+session. CI verifies that the binary builds and `--first-run` parses;
+this recipe is the manual gate.
+
+## Prerequisites
+
+- Ubuntu 24.04 VM with GNOME on Wayland (matches the project's target).
+- `authforge-daemon` + `authforge-gui` debs installed (Phase 14 PPA build).
+- A USB FIDO2 device (Yubikey, Solo, etc.) attached to the VM.
+
+## Walk-through
+
+```bash
+# As root in the VM:
+sudo useradd -m testuser
+sudo passwd testuser              # set a temporary password
+sudo chage -d 0 testuser          # force password change at next login
+sudo authforgectl pending set testuser --methods fido2
+
+# Log out of the current session, log in as testuser.
+# Expected sequence:
+# 1. GDM forces a password change → set the real password.
+# 2. Session starts.
+# 3. authforge --first-run launches via the autostart entry.
+# 4. Fullscreen modal appears: "Welcome — Enroll a security key…"
+# 5. Click "Get started" → enrollment dialog appears.
+# 6. Touch the Yubikey → modal closes → desktop usable.
+# 7. Verify: authforgectl pending list (run as root in another tty) shows
+#    no pending flag for testuser.
+
+# Re-test the auto-logout watchdog:
+sudo authforgectl pending set testuser --methods fido2
+# Log out, log in as testuser, do nothing for 60+ seconds.
+# Expected: the user is logged out via gnome-session-quit and returned
+# to GDM.
+
+# Re-test the daemon-down case:
+sudo systemctl stop authforge-daemon.service
+# Log out, log in as testuser. The modal shows "Setup unavailable" with
+# a Skip button; clicking it returns to the desktop.
+sudo systemctl start authforge-daemon.service
+```
+
+## Pass criteria
+
+- [ ] The modal appears within 2s of session start.
+- [ ] Successful enrollment clears the pending flag and exits the modal.
+- [ ] 60s idle triggers a clean session logout.
+- [ ] Daemon-down shows a graceful Skip button rather than hanging.
+- [ ] No pending flag → no modal → session start cost is < 100ms (verify
+      with `journalctl --since=now -f` for the autostart unit).