# 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).