📖 cosmic/metal: el runbook del viaje físico, escrito ANTES de bootear

Qué correr con el USB en la mano, en orden, y —lo que importa— CUÁL ES EL VEREDICTO:
el `[4/4] OpenPipeWireRemote` con su fd, no que el diálogo aparezca (eso ya pasaba en
QEMU). Y el contrafáctico que hace falsable el diagnóstico de hoy: si vuelve a
colgarse en `Start` pero YA NO aparece `Erroneous EGL call` en el log del compositor,
entonces la causa era otra y lo de hoy estaba incompleto.

`ls /dev/dri` con renderD128 es la señal barata de que hay HW: con swrast no existe.

Gotchas del quemado, todos medidos y todos con su porqué:
 · NUNCA a un NVMe y NUNCA POR NOMBRE — hoy mismo, tras el reboot, nvme0n1 y nvme1n1
   se intercambiaron respecto de lo anotado en julio. Identificar por TRAN=usb.
 · el progreso NO se mide con kill -0 (sudo dd corre como root ⇒ EPERM desde el
   usuario y parece que terminó): se mide por /sys/block/sda/stat campo 7.
 · no correr os-prober sobre el device que estás dd-eando.
 · `pkill -f <patrón>` mata su propio shell si el patrón está en su cmdline. Volvió a
   pasar hoy (exit 144), con el gotcha ya escrito. Usar pgrep -x.

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

docs/runbooks/cosmic-desktop.md

@@ -1195,14 +1195,67 @@ error que suena a «falta la librería» cuando lo que falta es la ruta.
 tiempo: ese daemon está sellado y corre. Un comentario viejo manda a buscar un bloqueo que ya no
 existe, y eso cuesta igual que un bug.
 
+## 🔩 EL VIAJE A METAL: qué hacer con el USB en la mano (2026-08-05)
+
+`scripts/cosmic/metal-desktop-image.sh` → `work/hammer-cosmic-metal.img`, quemada a `/dev/sda`.
+**No es «lo mismo pero en metal»**: es la única forma de saber si ScreenCast está bien, porque el
+`mesa` del corpus se construye con `-Dgallium-drivers=iris` y en QEMU ese driver nunca se usaba.
+
+**Validado en OVMF ANTES de quemar, y con PANTALLA** —la regla de oro que costó un USB en el primer
+viaje de KDE—, con `-serial null` para simular un metal sin puerto serie: `arje-zero` PID 1, las
+cuatro particiones montadas, el motd VISIBLE y el prompt `/ #` en pantalla (o sea que el getty de
+`tty1` hace su trabajo). El shell responde: `iris_dri.so` presente, `/dev/dri/card0`, y
+`cosmic-start` / `portal-probe` / `wireplumber` en PATH.
+Evidencia: `docs/evidencia/cosmic-metal-boot-pantalla-2026-08-05.png`.
+
+### La secuencia en la máquina física, en orden
+
+```sh
+ls /dev/dri                       # card0 + renderD128 ⇐ renderD128 es la novedad: NO existe con swrast
+dmesg | grep -iE 'i915|drm'       # que i915 haya hecho modeset, no simpledrm
+cosmic-start                      # el MISMO script que corre en QEMU
+# …y desde cosmic-term, dentro de la sesión:
+portal-probe version              # ScreenCast v5
+portal-probe screencast           # ⇐ LO QUE VINIMOS A VER
+```
+
+**El veredicto es el `[4/4] OpenPipeWireRemote` con su fd**, no que el diálogo aparezca: eso ya
+pasaba en QEMU. Si `Start` devuelve `Response: 0` y la sonda imprime `✓✓ HAY REMOTO DE PIPEWIRE`, el
+frente cierra. Si vuelve a colgarse en `Start`, mirar `/tmp/cosmic-session.log`: si **ya no** aparece
+`Erroneous EGL call`, entonces la causa era otra y el diagnóstico de hoy estaba incompleto.
+
+### 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:
+
+1. **No es un cuelgue, es el prompt invisible.** Ya está arreglado (`tty1-getty`), pero si vuelve:
+   los printk van a las dos consolas y el shell a una sola.
+2. **`ls /usr/lib/dri`** — si sólo hay `iris_dri.so` y la GPU no es Intel, no hay GL. Esta imagen es
+   Intel-only a propósito; para otra máquina va la imagen dual de KDE.
+3. **`cosmic-comp` sin DRM master**: `dmesg | grep -i drm` y `ls -l /dev/dri/card0`. Sin `seatd` o
+   sin el shim de logind el compositor no toma el master.
+
+### Gotchas del quemado, medidos
+
+- **NUNCA a un NVMe**, y **nunca por nombre**: los nombres cambian entre arranques — hoy mismo,
+  después del reboot, `nvme0n1` y `nvme1n1` se intercambiaron respecto de lo anotado en julio.
+  Identificar por `lsblk -dpo NAME,SIZE,TYPE,TRAN,MODEL` y confirmar `TRAN=usb`.
+- **El progreso NO se mide con `kill -0`**: `sudo dd` corre como root, así que desde el usuario da
+  EPERM y parece que terminó. Se mide con `awk '{print $7}' /sys/block/sda/stat` (sectores escritos).
+- **No correr `os-prober` sobre el device que estás dd-eando**: monta la partición con `grub-probe`
+  mientras dd la sobreescribe y el dd cae a KB/s.
+- **`pkill -f <patrón>` mata su propio shell** si el patrón aparece en su cmdline (exit 144). Pasó
+  otra vez hoy. Usar `pgrep -x` o un patrón que no se auto-matchee.
+
 ## Lo que falta, en orden
 
-1. **ScreenCast: DIAGNOSTICADO Y CERRADO como frente de software.** pipewire ✅, cliente persistente
-   ✅ (`portal-probe`, `b3:af49d32d`), `wireplumber` ✅ (`b3:b8f3baf0`) — y **ninguno era el
-   bloqueo**. La causa es **EGL por software en el compositor** (`kms_swrast`, sin dmabuf), medida
-   por correlación de 8 ms entre el `Erroneous EGL call` de smithay y el `Paused` del backend. No es
-   verificable en este QEMU (sin virgl): se cierra **en metal**, donde `iris_dri.so` ya está en la
-   imagen. Falta correr `portal-probe filechooser`, que ya puede capturar la URI.
+1. **ScreenCast: en el USB, esperando el viaje físico.** pipewire ✅, cliente persistente ✅
+   (`portal-probe`, `b3:af49d32d`), `wireplumber` ✅ (`b3:b8f3baf0`) — y **ninguno era el bloqueo**.
+   La causa es **EGL por software en el compositor** (`kms_swrast`, sin dmabuf), medida por
+   correlación de 8 ms entre el `Erroneous EGL call` de smithay y el `Paused` del backend. No es
+   verificable en QEMU (sin virgl), así que **la imagen de metal con `iris` ya está construida,
+   validada en OVMF y quemada** — ver la sección del viaje. Falta bootearla (acción física) y correr
+   `portal-probe screencast`. Y `portal-probe filechooser`, que ya puede capturar la URI.
 2. **Decidir `gvfs`** (ver la corrección de arriba: las piezas ya están selladas, lo que falta es la
    decisión sobre la segunda glib). Destrabaría los montajes remotos de cosmic-files y su applet.
 3. **Enchufar la tienda a `.swm`**: servir `org.freedesktop.PackageKit` y encender la feature