docs(bootstrap): document firmware/gpu/peripherals/hardware features

README.md

@@ -284,6 +284,10 @@ The bootstrap auto-switches to dracut when `method: tpm2` is set. Override via `
 | `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)) |
+| `firmware.*`       | dict   | see below      | Vendor firmware blobs and CPU microcode (see [4.2.6](#426-systemfeaturesfirmware)) |
+| `gpu.*`            | dict   | see below      | Mesa/Vulkan and per-vendor GPU userspace (see [4.2.7](#427-systemfeaturesgpu)) |
+| `peripherals.*`    | dict   | see below      | Fingerprint readers, webcams, DisplayLink (see [4.2.8](#428-systemfeaturesperipherals)) |
+| `hardware.*`       | dict   | see below      | Hardware-detection profile override (see [4.2.9](#429-systemfeatureshardware)) |
 
 **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
@@ -303,6 +307,80 @@ 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.2.6 `system.features.firmware`
+
+| Key         | Type            | Default | Description                                                       |
+| ----------- | --------------- | ------- | ----------------------------------------------------------------- |
+| `enabled`   | bool \| `auto`  | `auto`  | Install vendor firmware blobs. `auto` = on for `physical`, off for `virtual` |
+| `microcode` | bool \| `auto`  | `auto`  | Install CPU microcode. `auto` follows `firmware.enabled`          |
+
+Defaults are designed so a baremetal install picks up firmware automatically with no inventory entry needed,
+while VMs skip it (the hypervisor handles those). The environment role detects CPU/GPU/wireless vendors from
+the live host (via `lscpu` and `lspci`) and the bootstrap role installs only the matching firmware packages.
+On Arch, this uses the vendor splits (`linux-firmware-amdgpu`, `linux-firmware-realtek`, etc.) so the install
+stays minimal. On Debian, it uses the equivalent `firmware-*` packages. Distros without firmware splits fall
+back to a single meta package.
+
+#### 4.2.7 `system.features.gpu`
+
+| Key             | Type   | Default | Description                                          |
+| --------------- | ------ | ------- | ---------------------------------------------------- |
+| `enabled`       | bool   | `false` | Install Mesa, Vulkan, and per-GPU userspace          |
+| `nvidia_driver` | string | `auto`  | One of `auto`, `open`, `proprietary`, `nouveau`      |
+
+Pair with `desktop.enabled: true` for a working desktop. The package set is determined by the same hardware
+profile as `firmware`. The `nvidia_driver: auto` default picks **`open`** (`nvidia-open` kernel modules) for
+Turing or newer GPUs, falls back to **`proprietary`** for older cards on distros that ship the proprietary
+driver, and falls back to **`nouveau`** elsewhere. Force a specific flavor by setting the value explicitly.
+
+Proprietary and open Nvidia drivers on Fedora require RPMFusion non-free, which the bootstrap enables
+automatically when needed. Debian uses `nvidia-driver` from the `non-free` component (already enabled in the
+managed `sources.list`). Ubuntu uses `restricted`. Arch ships both `nvidia-open-dkms` and `nvidia-dkms` in
+the `extra` repository - no third-party setup required.
+
+#### 4.2.8 `system.features.peripherals`
+
+| Key           | Type            | Default | Description                                                |
+| ------------- | --------------- | ------- | ---------------------------------------------------------- |
+| `enabled`     | bool \| `auto`  | `auto`  | Master switch. `auto` follows `desktop.enabled`            |
+| `fingerprint` | bool \| `auto`  | `auto`  | `fprintd`/`libfprint`. `auto` = install when reader detected |
+| `webcam`      | bool \| `auto`  | `auto`  | `v4l-utils` and userspace tooling. `auto` follows `enabled` |
+| `displaylink` | bool            | `false` | DisplayLink dock support (explicit opt-in; see notes)      |
+
+Fingerprint detection scans `lsusb` for known reader vendor IDs (Synaptics, Validity, Goodix, Elan, Egis,
+Broadcom, AuthenTec, Upek, Futronic). When `fingerprint: auto` and a reader is present, `fprintd` and the
+PAM helper are installed. PAM enrollment must be done post-install (`fprintd-enroll`).
+
+DisplayLink ships proprietary userspace that distros do not package consistently. The bootstrap installs the
+in-tree `evdi-dkms` kernel module on Debian/Ubuntu and the `evdi` module on Fedora, but the userspace blob
+must still be installed manually from DisplayLink's site after first boot. Arch users typically use AUR
+(`displaylink`); this is not wired into the bootstrap.
+
+#### 4.2.9 `system.features.hardware`
+
+| Key       | Type | Default | Description                                                          |
+| --------- | ---- | ------- | -------------------------------------------------------------------- |
+| `profile` | dict | `{}`    | Hardware-detection override; empty means autodetect from live host   |
+
+When empty, hardware is detected at the start of the bootstrap. When set, detection is skipped and the
+supplied profile drives package selection - this is the **golden-image** flow: bake an image with a fixed
+profile, snapshot it, and reuse the same profile on every deploy of that hardware class.
+
+Profile shape:
+
+```yaml
+system:
+  features:
+    hardware:
+      profile:
+        cpu: intel                    # intel | amd
+        gpus: [intel, nvidia]         # any of: intel, amd, nvidia
+        nvidia_supports_open: true    # set false to force proprietary/nouveau
+        wireless: [intel]             # any of: intel, amd, atheros, broadcom,
+                                      # mediatek, marvell, realtek, qcom, cirrus
+        fingerprint: false            # set true to force fprintd install
+```
+
 ### 4.3 `hypervisor` Dictionary
 
 | Key          | Type   | Default | Description                                          |