veilor-os/docs/research/2026-05-05-agent-wave/02-sddm-firstboot-ux.md

# SDDM + first-boot UX failure modes

**Agent 2 of 9-agent wave, 2026-05-05.**

## Findings

### 1. SDDM has no username prefilled — BLOCKS LOGIN (perceived)

- User sees blank greeter; no signal that the only user is `admin`.
- **Fix:** `/etc/sddm.conf.d/veilor.conf` add
  `[Users]\nRememberLastUser=true` plus seed
  `/var/lib/sddm/state.conf [Last]\nUser=admin\nSession=plasma`.

### 2. chage -d 0 + SDDM autologin race

- With `Relogin=false` (current), single-shot is safe.
- **Fix:** Document `Relogin=false`. Don't combine `Autologin=true`
  with `chage -d 0`.

### 3. PAM expired-pw change inline in SDDM

- Plasma 6 SDDM 0.21+ renders the chain. **But** if password fails
  pwquality (cracklib min=14 + complexity from
  `10-harden-base.sh`), error text shown briefly then form resets —
  user sees no clear reason for rejection.
- **Fix:** `/etc/security/pwquality.conf.d/10-veilor.conf` with
  documented rules + Plasma startup notification showing them.

### 4. Wayland session start failure on virtio-vga — BLOCKS LOGIN

- KWin tries `wlroots`/DRM, fails to acquire `/dev/dri/card0` if
  `virtio_gpu` kernel module not loaded.
- **Fix:** add `plasma-workspace-x11` to `%packages`. SDDM session
  menu shows `Plasma (X11)` fallback.

### 5. Plasma 6 first-run wizards on /etc/skel-empty

- KWin compositor backend pick + Plasma welcome center + accent
  colour wizard — modal stealing focus on first session.
- **Fix:** seed `/etc/skel/.config/`:
  - `kwinrc` `[Compositing]\nBackend=OpenGL`
  - `kdeglobals [General]\nAccentColor=...`
  - `plasma-welcomerc [General]\nLastSeenVersion=99` (suppresses welcome)

### 6. SELinux relabel after first boot — looks like hang

- `touch /.autorelabel` triggers full restore on rootfs; 90s on
  4 GB live install, 3-5min on real disk. User hard-resets thinking
  it crashed → corrupted relabel state.
- **Fix:** replace with `veilor-relabel.service` that prints
  `[veilor] relabeling SELinux file contexts (1/N): %s` to TTY1
  with progress, plus one-time post-relabel KDialog notification.

### 7. USBGuard blocks input at SDDM — BLOCKS LOGIN on desktops

- If `/etc/usbguard/rules.conf` empty/missing, USBGuard
  `ImplicitPolicyTarget=block` (default) blocks USB. SDDM running
  but USB keyboard dead.
- **Fix:** ship a baseline `rules.conf`:
  `allow with-interface equals { 03:00:* 03:01:* }`
  (HID class) so any keyboard/mouse works pre-policy.

### 8. NetworkManager DHCP — LOW severity

- Wired auto-connects fine. Wi-Fi: silent failure unless SSID
  preconfigured. Acceptable; Plasma 6 ships `plasma-nm` widget.
- **Polish:** `/etc/xdg/autostart/veilor-firstboot-net-check.desktop`
  → KDialog "Connect to network?" if `nmcli general` is `disconnected`.

### 9. veilor-firstboot.service ordering — BLOCKS LOGIN on real installs

- **Current:** `WantedBy=multi-user.target` only.
- **Real installs:** default to `graphical.target`, so unit never runs.
- Admin pw stays `veilor` + chage-expired. SDDM PAM bounces to
  chauthtok screen — recoverable but ugly.
- **Fix:** `WantedBy=graphical.target multi-user.target`. Add
  `Before=graphical.target`. Verify `systemctl enable
  veilor-firstboot.service` (in installer line 884) resolves both.
  Add `DefaultDependencies=no` + `Wants=systemd-vconsole-setup.service`.

## Endeavour OS welcome app — design notes for veilor-postinstall

EOS welcome (`endeavouros-team/welcome` on GitHub) is bash + yad,
~3000 LOC. Patterns to lift for veilor:

- **Yad GTK dialog** as runtime (single binary dep). veilor (KDE)
  uses `kdialog` + `qmlscene` instead — native Plasma look.
- **Tabbed layout:** Welcome | Set up apps | Security | System info | Shortcuts.
- **Self-disabling autostart:**
  `~/.config/autostart/veilor-welcome.desktop` removed after user
  clicks "Don't show again".
- **External script dispatch:**
  `/usr/share/veilor-os/postinstall/<step>.sh` per step. Decouples
  UI from actions.
- **Update channel awareness:** pull from
  `github.com/veilor-org/veilor-os` releases atom feed; show CVE
  advisories from `security.atom` we publish.

**Recommended stack:**
- `/usr/bin/veilor-welcome` (bash entrypoint, ≤300 LOC)
- `/usr/share/veilor-os/postinstall/welcome.qml` (QtQuick/Kirigami UI)
- `/usr/share/veilor-os/postinstall/steps/{01-account,02-network,03-usbguard-policy,04-update,05-tour}.sh`
- `/etc/xdg/autostart/veilor-welcome.desktop`
- Replace current `scripts/firstboot.sh` placeholder with
  `step 03-usbguard-policy` (auto-generate-policy is the unfinished
  core item).

## Top three to ship next (highest UX impact, lowest risk)

1. **`WantedBy=graphical.target multi-user.target`** in
   `veilor-firstboot.service` — fixes silent SDDM-PAM-chauthtok
   bounce on real installs.
2. **Username prefill** in `sddm.conf.d/veilor.conf`: add `[Users]
   RememberLastUser=true` + `/var/lib/sddm/state.conf [Last]
   User=admin Session=plasma`.
3. **USBGuard HID baseline `rules.conf`** — un-bricks any desktop
   with USB keyboard.