1# Runbook — el instalador para la laptop del usuario (TigerLake), y los dos muros que tiene delante
2
3> **Estado: ENCARGO, no cerrado.** Las recetas de este runbook se escribieron el 2026-09-16 desde el
4> propio laptop —que no tiene lab ni store— así que **ninguna está sellada**. Lo que sigue es el
5> trabajo para el worker, en orden, con lo que ya está medido separado de lo que hay que averiguar.
6> Hermano de [`kde-qemu-desktop.md`](kde-qemu-desktop.md) y [`cosmic-desktop.md`](cosmic-desktop.md),
7> de los que reusa todo el andamiaje.
8
9## 0. Qué se quiere
10
11Un medio que arranque en la laptop del usuario e **instale takana reemplazando la Artix** que hay
12hoy. No un USB de pruebas —eso ya existe con `mirada-usb.sh`— sino una instalación a disco.
13
14## 1. La máquina, medida
15
16`lspci -nn`, `/proc/cpuinfo` y `lsblk` sobre el metal real, 2026-09-16:
17
18| pieza | qué es | driver | firmware |
19|---|---|---|---|
20| CPU | i7-11370H · family 6 · model 140 (0x8c) · stepping 1 | — | `intel-ucode/06-8c-01` |
21| GPU | TigerLake-LP GT2 [Iris Xe] `[8086:9a49]` | `i915` / `xe` | `i915/tgl_{dmc,guc,huc}*` |
22| WiFi | Intel Wi-Fi 6 AX201 `[8086:a0f0]` | `iwlwifi` | `iwlwifi-{QuZ-a0-hr-b0,cc-a0}-*.ucode` |
23| Audio | 500 Series HD Audio `[8086:a0c8]` | `snd_sof_pci_intel_tgl` | `intel/sof/sof-tgl.ri` |
24| Disco | NVMe 1,8 T | `nvme` | — |
25| Firmware del equipo | **UEFI** (`/sys/firmware/efi` presente) | — | — |
26
27## 2. Lo que se escribió para esto (sin sellar)
28
29Cinco recetas nuevas y un perfil. Todas parsean y `takana hash` las acepta; el grafo de deps cierra.
30
31| receta | qué es | nota |
32|---|---|---|
33| `linux-firmware` | tarball 20260910 pineado (648 MB) | sha256 contrastado contra el `sha256sums.asc` de kernel.org |
34| `sof-firmware` | sof-bin v2025.12.2 | **no está en linux-firmware** — medido, 0 coincidencias |
35| `intel-ucode` | microcode-20260812 | tampoco: Intel lo publica aparte |
36| `firmware-tigerlake` | derivada: recorta ~25 MB de las tres familias de este metal | la única que viaja en la imagen |
37| `zsh` | el shell de login del usuario | seis parches de musl de Alpine |
38| `[perfil.metal-tigerlake]` | la capa de hardware, componible con cualquier escritorio | `firmware-tigerlake` + `intel-ucode` |
39
40Esto cierra el `TODO(soberanía)` que `scripts/metal-firmware.sh` llevaba desde que se escribió: hasta
41hoy el firmware se **copiaba de `/lib/firmware` del host**, o sea de la Artix que veníamos a
42reemplazar. Un instalador que sólo se puede construir desde la distro que viene a sustituir no es un
43instalador.
44
45## 3. La tanda — qué construir, en orden
46
47El orden importa: `firmware-tigerlake` depende de las dos de firmware y falla ruidosa si no las
48encuentra materializadas.
49
50```sh
51cd /opt/takana
52flock -o work/.farm-build.lock bash -c '
53  for r in linux-firmware sof-firmware intel-ucode firmware-tigerlake zsh; do
54    ./target/release/takana --store ./store build "$r" || { echo "FALLÓ: $r"; break; }
55  done'
56```
57
58`flock -o`, no `flock` a secas — CLAUDE.md §1, y está medido: el lock lo sostiene la descripción de
59fichero abierta y los nietos la heredan.
60
61### Lo que puede salir mal, y cómo se ve
62
63- **`zsh` sale dinámico.** Es lo que le pasó a `bash`: si el `configure` mete `-rdynamic`, el wrapper
64  de cc del lab tira el `-static` y el binario queda contra `libncursesw.so.6`, que ningún artefacto
65  del corpus provee. Síntoma: `Error relocating ... symbol not found`. Arreglo conocido:
66  `make LOCAL_LDFLAGS=`. **Comprobar con `file`: debe decir `statically linked`.**
67- **`linux-firmware` tarda y pesa.** 648 MB de fetch, ~2 GB extraídos. El worker tiene 71 G libres.
68- **`firmware-tigerlake` aborta con `0 blobs de SOF`.** Significa que `sof-firmware` no se materializó
69  como dep. No ablandar la aserción: ese contador es la única defensa contra un `/lib/firmware` a
70  medias, que no falla al construir y falla meses después en el metal como «no hay WiFi».
71
72## 4. ⚠ Muro 1 — la rama EFI del instalador es justo la que se cuelga en este firmware
73
74Éste es el hallazgo que ordena el trabajo, y sale de cruzar dos ficheros que nadie había leído juntos.
75
76`scripts/takana-live-install.sh:275-281` detecta el firmware y bifurca:
77
78> `--- Detección de firmware: UEFI ⇒ rama EFI-stub SOBERANA (ADR 0010 paso 5); BIOS ⇒ MBR+GRUB ---`
79
80O sea: en esta laptop, que es UEFI, el instalador tomaría **la rama EFI-stub**. Y
81`scripts/metal-usb-sdboot.sh` dice, en su tercera línea:
82
83> *Alternativa de BRINGUP al boot por EFI-stub directo (que **en el firmware del usuario se cuelga
84> tras 'Measured initrd PCR 9'**, por el quirk de LoadOptions del firmware).*
85
86**Es el mismo firmware.** El lazo completo de instalación EFI está validado en OVMF
87(`scripts/efi-install-test.sh`), y OVMF no tiene ese quirk. Así que el instalador probablemente
88funcione perfecto en la prueba y se cuelgue en el metal de destino.
89
90Las tres salidas, en orden de coste:
91
921. **Llevar el instalador a systemd-boot**, que es el camino ya probado en este metal: pasa una
93   cmdline limpia y entrega el initrd por `LoadFile2`, esquivando el quirk. El precio está escrito y
94   aceptado como deuda: `systemd-bootx64.efi` es un binario ajeno del host — crutch de bringup.
952. **Arrancar el medio por systemd-boot y dejar que instale la rama EFI-stub.** No sirve: el disco
96   instalado arrancaría por EFI-stub y se colgaría igual, sólo que después de borrar Artix.
973. **Loader soberano propio.** Es el `TODO` que ya está anotado y no es trabajo de una sesión.
98
99⇒ **Recomendado: (1).** Y el test de aceptación no es OVMF: es el USB arrancando en el metal.
100
101## 5. ⚠ Muro 2 — el particionado, y una pregunta que es del usuario
102
103`takana-live-install.sh` particiona en **MBR**, incluida su rama EFI (una ESP tipo `0xEF` en tabla
104MBR, que UEFI acepta igual). Sobre el disco de esta laptop eso tiene dos consecuencias:
105
106- El NVMe es de **1,8 T**. MBR direcciona hasta 2 T: entra por poco, pero es el borde exacto del
107  formato y no hay razón para quedarse ahí cuando el disco ya es GPT.
108- El instalador **reparticiona el disco entero**. Hoy ese disco tiene `/home` con **893 G usados de
109  1,1 T** — el trabajo del usuario, incluido `~/tawasuyu` (497 G).
110
111> **Pregunta abierta, y es decisión del usuario, no del runbook:** ¿la instalación conserva `/home`
112> —instalando sólo sobre la raíz de 164 G— o se lleva el disco entero con respaldo previo? El
113> instalador hoy no sabe hacer lo primero: no tiene modo «usar esta partición y no tocar las otras».
114
115Mientras eso no se decida, **no correr el instalador sobre `/dev/nvme0n1`.** El camino sin riesgo es
116el USB: `metal-usb-sdboot.sh` produce una imagen para `dd` a un pendrive y no toca el disco interno.
117
118## 6. Orden de trabajo propuesto
119
1201. Construir la tanda del §3 y verificar que `zsh` sale estático y que `firmware-tigerlake` reporta
121   los tres contadores distintos de cero.
1222. Armar un USB de prueba con el perfil compuesto y **arrancarlo en el metal**:
123   ```sh
124   scripts/targets.py cli metal-tigerlake escritorio-kde      # la lista de la imagen
125   scripts/metal-usb-sdboot.sh                                 # → work/hammer-metal-usb.img
126   ```
127   Lo que se valida acá no es el escritorio: es **el firmware**. Que asocie el WiFi, que el display
128   tome el DMC y que el DSP de audio levante. Son las tres cosas que hoy sólo funcionan porque las
129   presta la Artix instalada.
1303. Recién entonces, el instalador: la rama systemd-boot del §4 y la decisión de particionado del §5.
1314. Y sólo después, KDE/GNOME/COSMIC en metal con GPU real — hoy los tres corren por llvmpipe, que en
132   QEMU es correcto y en una Iris Xe es tirar la GPU a la basura.
133
134## 7. Lo que este runbook NO resuelve
135
136- **La laptop sigue sin poder hidratar.** Su `.dev-fs/alpine` tiene 104 paquetes contra los 110 de
137  `lab-toolchain.lock`, así que calcula `ArtifactHash` distintos y no encuentra nada del store
138  compartido. Hasta que `farm-lab-sync.sh` corra hacia acá, todo lo de este runbook pasa por el
139  worker.
140- **`kitty`, el terminal del usuario, no tiene receta.** `foot` sí está sellada y es el terminal
141  Wayland del proyecto; sirve de puente, pero no es lo que él usa.
142- **Los escritorios en metal con aceleración.** Distinto problema del firmware: es mesa con el driver
143  Iris real en vez de llvmpipe.