Recetas Rápidas (W1–W10)

Puerta obligatoria. Antes de tocar cualquier archivo del fork, identifica en qué receta encaja tu cambio. Si no encaja en ninguna, es señal de que debes re-preguntar — el modelo upstream es la única verdad (ver Matriz de Decisión).

Referencia Técnica Central: Para una descripción exhaustiva de los comandos de desarrollo, motores de migración y documentos maestros del árbol de Omarchy, consulta la Referencia Canónica de Comandos y Archivos Clave.

Caso 2026-10-05 — espacios Herdr. No se publica session.json ni se aplica el home con omarchy-reinstall-configs. El procedimiento está en Espacios Herdr de la flota.

Índice de recetas

W1 — Agregar o actualizar una webapp / launcher

Cuándo: Quieres añadir un acceso directo (webapp, app nativa o comando TUI) al menú de aplicaciones.

# 1. Crea el archivo .desktop en el fork
vim applications/MiApp.desktop

# 2. Opcionalmente añade el icono (PNG o SVG)
cp mi-icono.png applications/icons/mi-app.png

# 3. Valida localmente
omarchy dev pkg-test
omarchy refresh-applications   # materializa en ~/.local/share/applications/

# 4. Publica cuando estés satisfecho (W7)
gh workflow run release-personal.yml -R robert-flo/omarchy-pkgs \
  --ref personal -f version=v<TAG>

Referencia completa: Guía de Webapps.

W2 — Agregar un ejecutable / comando propio (omarchy-*)

Cuándo: Quieres añadir un nuevo subcomando al CLI de Omarchy (omarchy mi-comando).

# 1. Crea el script con los metadatos obligatorios
cat > bin/omarchy-mi-comando << 'EOF'
#!/usr/bin/env bash
# omarchy:summary=Descripción de una línea
# omarchy:args=
# omarchy:examples=omarchy mi-comando
set -euo pipefail
# ... lógica del comando
EOF
chmod +x bin/omarchy-mi-comando

# 2. Valida localmente
omarchy dev pkg-test
omarchy mi-comando   # prueba directa

# 3. Publica (W7)
gh workflow run release-personal.yml -R robert-flo/omarchy-pkgs \
  --ref personal -f version=v<TAG>

Regla: los scripts en bin/ llevan obligatoriamente los metadatos omarchy:summary=, omarchy:args= y omarchy:examples=.

W3 — Agregar un wrapper de terceros (CLI de IA, mise, npm)

Cuándo: Quieres que un CLI instalado por mise, npm, o un instalador oficial esté disponible en todas las máquinas.

# 1. Agrega la instalación a install/user/mi-tool.sh (siguiendo la
#    estructura de install/user/mise.sh como plantilla)
vim install/user/mi-tool.sh

# 2. Valida localmente
omarchy refresh-applications   # ejecuta install/user/*.sh idempotentemente

# 3. Publica (W7)
gh workflow run release-personal.yml -R robert-flo/omarchy-pkgs \
  --ref personal -f version=v<TAG>

Antipatrón a evitar: scripts sueltos por máquina o instalaciones manuales. Todo debe pasar por install/user/*.sh para viajar por omarchy update.

W4 — Añadir o modificar una config de app (~/.config/)

Cuándo: Quieres integrar una nueva aplicación o modificar una configuración existente en ~/.config/.

Procedimiento Canónico Obligatorio: Consulta la Guía Operativa: Añadir Configuraciones de App a la Flota para evaluar los 4 caminos según las capacidades de la app (Sistema /etc/xdg/, Stub + Include, Symlink gestionado, Semilla estática + Reconciliador).

# 1. Evalúa el camino en operations/06-anadir-config-app/
#    - Camino 1: etc/xdg/<app>/
#    - Camino 2: default/<app>/ (core) + stub
#    - Camino 3: default/<app>/ + symlink en aprovisionamiento
#    - Camino 4: default/<app>/ a /etc/skel/ + hooks/post-update.d/

# 2. Valida localmente con el flujo de doble velocidad
omarchy dev link ~/Work/tries/pj-omarchy/fo-omarchy
omarchy refresh config <app>/config

# 3. Validación pre-flight (obligatoria para /etc/xdg o /etc/skel)
omarchy dev pkg-test omarchy-settings-dev

# 4. Publica cuando esté validado (W7)
gh workflow run release-personal.yml -R robert-flo/omarchy-pkgs \
  --ref personal -f version=v<TAG>

W5 — Modificar o agregar un tema

Cuándo: Quieres añadir o cambiar el tema visual (colores, fuentes, wallpaper).

# 1. Modifica los archivos en themes/
vim themes/mi-tema/

# 2. Valida localmente
omarchy dev pkg-test
omarchy refresh theme   # aplica el tema en el entorno actual

# 3. Publica (W7)
gh workflow run release-personal.yml -R robert-flo/omarchy-pkgs \
  --ref personal -f version=v<TAG>

W6 — Agregar un paquete de Arch o del AUR

Cuándo: El paquete o la app ya existe en los repos de Arch o en el AUR. Un launcher de URL sigue siendo W1. Un PKGBUILD propio del fork sigue siendo Añadir un Paquete Personal.

El mecanismo vive en robert-flo/omarchy#17 (issue #16) y todavía no está mergeado. Esta receta lo describe igual.

Clasifica el origen antes de editar, en el checkout de fo-omarchy:

• Está en los repos de Arch (pacman -Ss): una línea en install/omarchy-base.packages. Ejemplo: meld.
• Es del AUR: una línea en install/omarchy-aur.packages. Ejemplo: elio-bin. Esa línea no va en omarchy-base.packages. omarchy reinstall pkgs y pacman no ven el AUR.
• install/omarchy-other.packages no es esta receta. omarchy-pkg-sync no la lee.

No hagas esto:

• No crees una migración por paquete. Las migraciones quedan para un cambio de estado de una sola vez (W10). migrations/1791260741.sh se queda; no es el camino para el próximo paquete del AUR.
• No uses un hook post-update para instalar paquetes.

gracie es la PC dev. No corre omarchy update. Desde el checkout de fo-omarchy, omarchy dev pkg-test termina llamando omarchy-pkg-sync, que instala solo lo que falta de las dos listas.

# 1. Una línea en la lista que corresponde (Arch o AUR, ver arriba)

# 2. Desde el checkout de fo-omarchy. Corre la secuencia del paquete que agregaste.
cd ~/Work/omarchy/omarchy-installer

# Arch. Ejemplo: meld
sudo pacman -Rns --noconfirm meld
omarchy dev pkg-test
pacman -Q meld

# AUR. Ejemplo: elio-bin
sudo pacman -Rns --noconfirm elio-bin
omarchy dev pkg-test
pacman -Q elio-bin

# 3. Publica (W7). En las hijas, omarchy update.
gh workflow run release-personal.yml -R robert-flo/omarchy-pkgs \
  --ref personal -f version=v<TAG>

En las hijas, después de esa publicación, omarchy update corre omarchy-pkg-sync --repos después de los paquetes del sistema, con sudo todavía autorizado, y omarchy-pkg-sync --aur en la fase fría, sin cachear sudo.

W7 — Publicar un cambio al CDN (dispatch del CI/CD)

Cuándo: Tienes cambios commiteados en la rama personal y quieres distribuirlos a todas las máquinas.

# Siempre desde omarchy-pkgs, siempre --ref personal
# El pkgrel se deriva automáticamente (pkgver nuevo → 99; mismo pkgver → +1)

# Opcional: ensayo sin publicar (recomendado para primeras publicaciones)
gh workflow run release-personal.yml -R robert-flo/omarchy-pkgs \
  --ref personal -f version=v<TAG> -f dry_run=true

# Publicación real
gh workflow run release-personal.yml -R robert-flo/omarchy-pkgs \
  --ref personal -f version=v<TAG>

# Verificar que el run terminó verde
gh run watch --exit-status -R robert-flo/omarchy-pkgs

Regla de oro: dispatch SIEMPRE con --ref personal. Si el guard fail-fast aborta, es porque la rama era incorrecta — re-disparar con --ref personal.

W8 — Onboarding de una máquina nueva

Cuándo: Quieres incorporar una laptop, desktop o VM Arch Linux nueva al sistema personal.

Ver la guía completa: Onboarding de Máquinas (7 pasos).

Script desatendido:

curl -fsSL https://raw.githubusercontent.com/robert-flo/fork-docs/main/scripts/bootstrap-omarchy-machine.sh | bash

W9 — Cadencia / Sync con upstream (nuevo release de Omarchy)

Cuándo: omacom/omarchy publicó un nuevo tag (vX.Y.Z) y quieres actualizar el fork para mantener las personalizaciones sobre la versión más nueva. El fetch sigue viniendo de omacom/omarchy:quattro; el espejo local en el fork es la rama upstream.

# Si el pipeline de las 04:00 AM ya lo detectó y no hubo conflictos,
# el proceso ya fue automático. Verifica:
gh issue list --label cadencia -R robert-flo/omarchy-pkgs

# Si hay conflicto (issue de alerta abierto) o quieres sincronizar manualmente:
cd ~/Work/omarchy/omarchy-installer   # rama personal
git fetch upstream quattro --tags     # remote `upstream` = omacom; rama `quattro` en omacom
git checkout -B upstream upstream/quattro   # Fast-Forward del espejo local
git checkout personal
git rebase upstream                   # rebase sobre el espejo; resolver conflictos si los hay
git push --force-with-lease origin personal

# Publicar con el nuevo pkgver (pkgrel se deriva: pkgver nuevo → 99)
gh workflow run release-personal.yml -R robert-flo/omarchy-pkgs \
  --ref personal -f version=vX.Y.Z

Checklist post-sync:

• Rebase limpio (sin conflictos, o resueltos)
• Push a origin personal
• Dispatch con --ref personal y el pkgver del tag nuevo
• Run verde y validación HTTP 200 en Pages
• omarchy update en la máquina dev confirma versión personal nueva
• No queda issue [Cadencia] abierto

W10 — Agregar una migración para usuarios existentes

Cuándo: El home existente todavía no tiene el stub, o hay que reemplazar una vez un archivo generado viejo. El día a día no entra aquí: va en el archivo que ese home ya lee desde /usr.

La migración es solo el puente de una vez. Sembrar /etc/skel cubre un home que todavía no existe. En pc-gracie o en una PC hija, omarchy update no vuelve a copiar el skel. El día a día no pide una migración por cada edición. ~/.bashrc se queda como stub y carga /usr/share/omarchy/default/bash/rc. Los alias y las rutas de Android viven en default/bash/rc. Tras el update del paquete, un shell nuevo los ve. No hace falta una migración nueva. Un archivo generado en ~/.local/bin, como agy, tiene que ser un stub que hace exec de un script publicado en /usr/share/omarchy/bin, para que un cambio de flags viaje con el paquete. migrations/1791266899.sh es el puente del stub de bashrc y de agy. Cuando la máquina lo marca en ~/.local/state/omarchy/migrations/, omarchy-migrate no lo vuelve a correr. No se edita ese archivo. omarchy-reinstall-configs copia todo el skel encima del home y no es el camino de la flota. La regla vive junto al principio de cero configuración, en Introducción & Filosofía.

# 1. Crea el script de migración con timestamp (idempotente obligatorio)
TIMESTAMP=$(date +%Y%m%d%H%M%S)
cat > migrations/${TIMESTAMP}_mi-migracion.sh << 'EOF'
#!/usr/bin/env bash
# Descripción: qué hace esta migración
set -euo pipefail

# Ejemplo: crear directorio de trabajo si no existe
mkdir -p "$HOME/src"

echo "Migration ${TIMESTAMP}_mi-migracion: done"
EOF
chmod +x migrations/${TIMESTAMP}_mi-migracion.sh

# 2. Valida localmente con el flujo integral (Operations/01 §5):
omarchy dev pkg-test
omarchy-migrate                              # ejecuta scripts pendientes en migrations/
omarchy refresh <componente>                 # recarga el componente afectado en caliente

# 3. Publica (W7) — en el próximo omarchy update de cada máquina,
#    omarchy-migrate ejecutará este script automáticamente
gh workflow run release-personal.yml -R robert-flo/omarchy-pkgs \
  --ref personal -f version=v<TAG>

Regla de idempotencia: el script debe ser seguro de ejecutar múltiples veces sin efectos secundarios. Usa mkdir -p, cp -n, grep -q ... || echo ... >>, etc.