From b11d65a6f3e07715de4b486c467da06e8268f387 Mon Sep 17 00:00:00 2001
From: sandwich <sandwich@archworks.co>
Date: Wed, 1 Apr 2026 15:07:58 +0200
Subject: [PATCH] docs(bootstrap): document desktop, initramfs, and FDE
 features with SSH keepalive config

---
 README.md   | 30 +++++++++++++++++++++++++++++-
 ansible.cfg |  3 +++
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 858f3f7..a8f0b19 100644
--- a/README.md
+++ b/README.md
@@ -257,7 +257,15 @@ Users must be defined in inventory. The dict format enables additive merging acr
 | Key      | Type          | Default | Description                                    |
 | -------- | ------------- | ------- | ---------------------------------------------- |
 | `device` | string        | `auto`  | TPM2 device selector                           |
-| `pcrs`   | string/list   | --      | PCR binding policy (e.g. `"7"` or `"0+7"`)    |
+| `pcrs`   | string/list   | --      | PCR binding policy (e.g. `"7"` or `"0+7"`); empty = no PCR binding |
+
+**TPM2 auto-unlock:** Uses `systemd-cryptenroll` on all distros. The user-set passphrase
+remains as a backup unlock method. TPM2 enrollment runs in the chroot during bootstrap;
+if it fails (e.g. no TPM2 hardware), the system boots with passphrase-only unlock and
+TPM2 can be enrolled post-deployment via `systemd-cryptenroll --tpm2-device=auto <device>`.
+
+On Debian/Ubuntu, TPM2 auto-unlock requires dracut (initramfs-tools does not support `tpm2-device`).
+The bootstrap auto-switches to dracut when `method: tpm2` is set. Override via `features.initramfs.generator`.
 
 #### `system.features`
 
@@ -274,6 +282,26 @@ Users must be defined in inventory. The dict format enables additive merging acr
 | `banner.motd`      | bool   | `false`        | MOTD banner                          |
 | `banner.sudo`      | bool   | `true`         | Sudo banner                          |
 | `chroot.tool`      | string | `arch-chroot`  | `arch-chroot`, `chroot`, or `systemd-nspawn` |
+| `initramfs.generator` | string | auto-detected | Override initramfs generator (see below) |
+| `desktop.*`        | dict   | see below      | Desktop environment settings (see [4.2.5](#425-systemfeaturesdesktop)) |
+
+**Initramfs generator auto-detection:** RedHat → dracut, Arch → mkinitcpio, Debian/Ubuntu → initramfs-tools.
+Override with `dracut`, `mkinitcpio`, or `initramfs-tools`. When LUKS TPM2 auto-unlock is enabled and the
+native generator does not support `tpm2-device`, the generator is automatically upgraded to dracut.
+On distros with older dracut (no `tpm2-tss` module), clevis is used as a fallback for TPM2 binding.
+
+#### 4.2.5 `system.features.desktop`
+
+| Key               | Type   | Default        | Description                               |
+| ----------------- | ------ | -------------- | ----------------------------------------- |
+| `enabled`         | bool   | `false`        | Install desktop environment               |
+| `environment`     | string | --             | `gnome`, `kde`, `xfce`, `sway`, `hyprland`, `cinnamon`, `mate`, `lxqt`, `budgie` |
+| `display_manager` | string | auto-detected  | Override DM: `gdm`, `sddm`, `lightdm`, `ly`, `greetd` |
+
+When `enabled: true`, the bootstrap installs the desktop environment packages, enables the display manager
+and bluetooth services, and sets the systemd default target to `graphical.target`.
+
+Display manager auto-detection: gnome→gdm, kde→sddm, xfce→lightdm, sway→greetd, hyprland→ly.
 
 ### 4.3 `hypervisor` Dictionary
 
diff --git a/ansible.cfg b/ansible.cfg
index 380bace..83b968b 100644
--- a/ansible.cfg
+++ b/ansible.cfg
@@ -3,3 +3,6 @@ hash_behaviour = merge
 interpreter_python = auto_silent
 deprecation_warnings = False
 host_key_checking = False
+
+[ssh_connection]
+ssh_args = -C -o ControlMaster=auto -o ControlPersist=600s -o ServerAliveInterval=30 -o ServerAliveCountMax=10