sergio/takana

Documenta el diagnóstico del OptiPlex 3060: la GPU estaba perfecta (i915 inicializó,
fbcon en el framebuffer) y lo que fallaba era el hardcodeo de software GL, más la
preparación de sesión que la imagen de metal nunca tuvo.

Deja las dos reglas: un artefacto compartido entre QEMU y metal no puede llevar el
entorno hardcodeado (se detecta), y «llega al prompt» no valida NADA del escritorio
— hay que correr cosmic-start en la imagen que se va a quemar.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

diff --git a/docs/runbooks/cosmic-desktop.md b/docs/runbooks/cosmic-desktop.md
index 89268abc..b792f254 100644
--- a/docs/runbooks/cosmic-desktop.md
+++ b/docs/runbooks/cosmic-desktop.md
@@ -1275,6 +1275,52 @@ De paso: el rebuild avisa `! sin hammer musl` ⇒ **el CLI `hammer` no está en
 `hammer boot menu` nunca corre. Igual lleva `timeout 15`, porque corre ANTES del `exec` de arje-zero
 y colgarse ahí deja un arranque sin PID1 ni pantalla — el `|| true` protege del fallo, no del bloqueo.
 
+### 🖥 2º viaje: la imagen forzaba SOFTWARE — no podía ganar ni en el mejor caso (2026-08-05)
+
+Máquina: **Dell OptiPlex 3060, Coffee Lake, UHD 630**. Arrancó entero (arje-zero PID 1, hammerd,
+sshd escuchando) y `cosmic-start` no levantó el escritorio.
+
+**La GPU estaba perfecta.** Del `dmesg` sacado del propio USB:
+
+```
+[2.570] i915 0000:00:02.0: [drm] Found coffeelake (device ID 3e92) integrated display version 9.00
+[3.179] [drm] Initialized i915 1.6.0 for 0000:00:02.0 on minor 0
+[3.875] fbcon: i915drmfb (fb0) is primary device
+[3.949] Console: switching to colour frame buffer device 240x67
+```
+
+El `Failed to load DMC firmware i915/kbl_dmc_ver1_04.bin` es un *warning*: el propio kernel dice que
+sólo desactiva gestión de energía. No era la causa (se arregló igual, es gratis).
+
+**La causa era el script de arranque.** `cosmic-start-qemu.sh` exportaba, sin condición:
+
+```sh
+export LIBGL_ALWAYS_SOFTWARE=1
+export MESA_LOADER_DRIVER_OVERRIDE=kms_swrast
+```
+
+Correcto sobre virtio-gpu. Letal sobre Intel real: la mesa del corpus va con
+`-Dgallium-drivers=iris -Dllvm=disabled` y **no existe ningún `kms_swrast_dri.so`** ⇒ el override no
+degrada a software, hace fallar EGL. **Y en el mejor caso habría sido peor**: si hubiera arrancado,
+habría compuesto por software y ScreenCast habría fallado por el mismo motivo que en QEMU — o sea que
+**el viaje no podía contestar la pregunta que lo motivaba**.
+
+El origen fue un comentario en `metal-desktop-image.sh` que afirmaba que el script *«no tiene nada
+específico del emulador»*. El nombre del fichero decía lo contrario y se ignoró.
+**Regla: un artefacto que se comparte entre QEMU y metal no puede llevar el entorno hardcodeado —
+se detecta.** Hoy el modo de GL se decide con dos patas (driver DRM del kernel **y** `.so` de mesa
+presente) y la imagen falla el build si el script vuelve a forzar `kms_swrast`.
+
+**Y correr `cosmic-start` sobre la imagen de metal por PRIMERA VEZ destapó lo de fondo**: le faltaba
+entera la preparación de sesión que sólo tenía `qemu-desktop-image.sh`. Sin grupo `video` no arranca
+`seatd`; sin usuario `messagebus` no arranca el **bus de sistema**; y **sin bus de sistema no hay
+portal**, o sea que `portal-probe screencast` no habría tenido con quién hablar ni con el GL perfecto.
+La imagen de metal se armó copiando el *arranque* de la de QEMU pero no su *preparación*.
+
+**Lección de método**: validar que una imagen «llega al prompt» no valida nada del escritorio. Hay que
+correr `cosmic-start` en la imagen que se va a quemar, aunque el GL no se pueda ejercer en QEMU: los
+fallos de sesión (seatd, dbus, logind) sí se ven, y son los que cuestan los viajes.
+
 ### Qué mirar si la pantalla queda negra
 
 Es el fallo que ya nos pasó una vez y tiene una causa aburrida. En orden de probabilidad: