refactor(docs): Mover AGENTS.md a un directorio oculto (#16)

Se mueve el archivo `AGENTS.md` al nuevo directorio oculto `.docs` para organizar mejor los archivos de documentación interna del proyecto. Se actualiza el enlace correspondiente en el archivo `Readme.md` para que apunte a la nueva ubicación del archivo. Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
2026-01-13 13:25:16 +00:00 · 2025-11-19 17:16:54 -06:00
parent 4b30ecaffa
commit d85b81dd0e
3 changed files with 256 additions and 593 deletions
--- a/.docs/AGENTS.md
+++ b/.docs/AGENTS.md
@@ -0,0 +1,59 @@
 # AGENTS.md - Guía para Contribuidores y Tareas Pendientes
 Este documento está destinado a los desarrolladores (humanos o agentes de IA) que trabajan en el proyecto Omarchy Setup. Contiene un resumen del estado actual, una lista de tareas pendientes y directrices para el desarrollo futuro.
 ## Análisis del Proyecto
 El proyecto "Omarchy Setup" es un script de post-instalación para Arch Linux, diseñado con un enfoque en la modularidad y la facilidad de uso.
 - **Orquestador Principal (`omarchy-setup.sh`):** Actúa como el punto de entrada. Presenta un menú interactivo al usuario, gestiona las sesiones de `sudo`, y coordina la ejecución de los diferentes módulos.
 - **Módulos (`modules/`):** Cada archivo `.sh` en este directorio encapsula una funcionalidad específica (ej. instalar aplicaciones, configurar Docker, personalizar Zsh). Esta estructura facilita la adición o modificación de tareas sin afectar al resto del sistema.
 - **Funciones Comunes (`modules/common.sh`):** Centraliza el código repetitivo, como las funciones de logging, la instalación de paquetes (pacman y AUR), y la creación de backups. Esto promueve la reutilización de código y la consistencia.
 - **Interactividad:** El sistema está diseñado para ser interactivo, solicitando confirmación del usuario para acciones importantes, pero también soporta ejecuciones en segundo plano para tareas no interactivas.
 ## Tareas Pendientes y Mejoras
 A continuación se detallan las tareas prioritarias para mejorar la funcionalidad y robustez del proyecto.
 ### 1. Implementar un Sistema de Dependencias entre Módulos
 - **Objetivo:** Evitar fallos cuando un módulo requiere que otro se haya ejecutado previamente (por ejemplo, `ssh-keyring.sh` necesita que `apps.sh` instale `gnome-keyring`).
 - **Acción Propuesta:**
    1.  En cada módulo, definir un array o variable que liste sus dependencias. Ejemplo en `ssh-keyring.sh`: `MODULE_DEPS=("apps")`.
    2.  En `omarchy-setup.sh`, antes de ejecutar un módulo, leer esta variable y comprobar si los módulos dependientes ya han sido ejecutados (se podría mantener un registro de módulos completados).
    3.  Si una dependencia no se ha cumplido, informar al usuario y ofrecerle ejecutarla primero.
 ### 2. Crear un Archivo de Configuración Central (`omarchy.conf`)
 - **Objetivo:** Facilitar instalaciones desatendidas y permitir a los usuarios pre-configurar sus preferencias sin modificar los scripts.
 - **Acción Propuesta:**
    1.  Crear un archivo `omarchy.conf.example` con pares clave-valor para las opciones personalizables (ej. `INSTALL_DOCKER="true"`, `ZEROTIER_NETWORK_ID="tu_id_de_red"`).
    2.  En `omarchy-setup.sh`, comprobar si existe `omarchy.conf` y cargarlo.
    3.  Modificar los módulos para que lean estas variables de configuración y actúen en consecuencia, saltándose las preguntas interactivas si la opción está definida.
 ### 3. Añadir Funcionalidad de Desinstalación / Reversión
 - **Objetivo:** Permitir a los usuarios deshacer los cambios realizados por un módulo de forma segura.
 - **Acción Propuesta:**
    1.  Para cada módulo, crear una función `uninstall_<nombre_modulo>`.
    2.  Esta función debe realizar la acción inversa a la instalación: eliminar paquetes, restaurar archivos de configuración a partir de los backups `.bak` y deshabilitar los servicios correspondientes.
    3.  Añadir una nueva opción en el menú principal para acceder a un sub-menú de desinstalación.
 ### 4. Implementar Verificaciones Post-Instalación
 - **Objetivo:** Aumentar la fiabilidad del script confirmando que el software principal de cada módulo se ha instalado y funciona correctamente.
 - **Acción Propuesta:**
    1.  Al final de cada módulo, añadir una pequeña función de `verify_<nombre_modulo>`.
    2.  Esta función debería ejecutar un comando simple para comprobar el estado del software. Ejemplos:
        - **Docker:** `docker --version` y `docker run hello-world`.
        - **Zsh:** `zsh --version` y comprobar que `oh-my-posh` está en el `$PATH`.
        - **ZeroTier:** `sudo zerotier-cli status`.
    3.  Informar al usuario si la verificación ha sido exitosa o ha fallado.
 ## Directrices para Futuros Desarrollos
 - **Modularidad:** Toda nueva funcionalidad debe encapsularse en su propio módulo.
 - **Idempotencia:** Los scripts deben poder ejecutarse múltiples veces sin causar efectos secundarios negativos. Comprueba siempre si un paquete ya está instalado o si una configuración ya existe antes de aplicarla.
 - **Lenguaje y Estilo:** Todo el código y los comentarios deben estar en **español** para mantener la consistencia del proyecto.
 - **Manejo de Errores:** Utiliza las funciones `log_error`, `log_warning` y `log_success` de `common.sh` para proporcionar feedback claro al usuario. Si un comando crítico falla, el script debe salir de forma controlada.
 - **Seguridad:** No almacenes información sensible (contraseñas, claves de API) directamente en los scripts. Utiliza ficheros locales como `.zshrc.local` (que está en `.gitignore`) para estos casos.
--- a/DOCUMENTACION.md
+++ b/DOCUMENTACION.md
@@ -0,0 +1,144 @@
 # DOCUMENTACION.md - Referencia Técnica de Módulos
 Este documento proporciona una descripción técnica detallada de cada script y módulo que forma parte del proyecto Omarchy Setup.
 ## 1. Script Principal: `omarchy-setup.sh`
 Este es el script orquestador y el punto de entrada para el usuario.
 - **Función Principal:** Proporcionar una interfaz de menú interactiva que permite al usuario seleccionar qué módulos de configuración desea ejecutar.
 - **Características Clave:**
    - **Menú Dinámico:** Muestra una lista de todos los módulos disponibles, permitiendo al usuario elegir uno, varios ("Instalar Todo") o salir.
    - **Gestión de `sudo`:** Solicita la contraseña de `sudo` una vez y la mantiene activa en segundo plano para evitar que el usuario tenga que introducirla repetidamente.
    - **Ejecución Modular:** Llama a las funciones principales de los scripts ubicados en el directorio `modules/`.
    - **Feedback Visual:** Implementa un "spinner" (indicador de progreso) para las tareas que se ejecutan en segundo plano, mejorando la experiencia del usuario.
    - **Registro (`Logging`):** Guarda un registro detallado de toda la sesión de instalación en el directorio `logs/`, lo que facilita la depuración en caso de errores.
    - **Verificación del Sistema:** Comprueba que el script se está ejecutando en Arch Linux antes de proceder.
 ## 2. Módulos (`modules/`)
 ### 2.1. `common.sh`
 Este script no es un módulo ejecutable desde el menú, sino una librería de funciones compartidas por todos los demás módulos.
 - **Función Principal:** Centralizar el código común para evitar duplicaciones y mantener la consistencia.
 - **Funciones Proporcionadas:**
    - **Logs con Colores:** Funciones como `log_info`, `log_success`, `log_warning` y `log_error` para mostrar mensajes con un formato estandarizado.
    - **Gestión de Paquetes:**
        - `check_and_install_pkg`: Verifica si un paquete ya está instalado desde los repositorios oficiales y, si no, lo instala con `pacman`.
        - `ensure_aur_helper` y `aur_install_packages`: Detectan un helper de AUR (como `yay` o `paru`), lo instalan si es necesario, y lo utilizan para instalar paquetes desde el Arch User Repository.
    - **Copias de Seguridad:** La función `backup_file` renombra un archivo existente (ej. `.zshrc`) a `.zshrc.bak_FECHA` antes de sobrescribirlo, para prevenir la pérdida de configuraciones del usuario.
    - **Verificaciones:** `command_exists` comprueba si un comando está disponible en el sistema.
 ### 2.2. `apps.sh`
 Es uno de los módulos más extensos y se encarga de la instalación de un conjunto base de aplicaciones y herramientas.
 - **Función Principal:** Instalar software esencial de diversas categorías.
 - **Software Instalado:**
    - **Base del Sistema:** `git`, `curl`, `htop`, `btop`, `stow`, `gnome-keyring`, `openssh`, etc.
    - **Desarrollo:** `python`, `pip`, `nodejs`, `npm`. También instala `nvm` (Node Version Manager) y `Homebrew` para una gestión de paquetes más flexible.
    - **Multimedia:** VLC (y sus codecs), Audacity, Inkscape, `yt-dlp` para descargar vídeos.
    - **Red:** FileZilla, Telegram, `speedtest-cli`.
    - **Drivers para Intel Iris Xe:** Instala todos los paquetes necesarios para el correcto funcionamiento de los gráficos integrados de Intel, incluyendo `mesa`, `vulkan-intel`, y los drivers para la aceleración de vídeo por hardware (VA-API).
 - **Configuraciones Adicionales:**
    - Habilita y configura servicios del sistema como `gnome-keyring-daemon` (para gestión de contraseñas y claves SSH), `keyd` y `logiops` (para teclados y ratones avanzados), `teamviewer` y `tlp` (para la gestión avanzada de energía y optimización de la batería).
 ### 2.3. `zsh-config.sh`
 Este módulo personaliza la experiencia del shell del usuario.
 - **Función Principal:** Configurar Zsh como el shell principal con una apariencia y funcionalidad mejoradas.
 - **Acciones Realizadas:**
    - **Instalación:** Instala `zsh`, `zsh-completions` y otras utilidades.
    - **Oh My Zsh:** Instala el framework "Oh My Zsh" para la gestión de plugins.
    - **Plugins:** Añade plugins populares como `zsh-autosuggestions` (sugiere comandos mientras escribes) y `zsh-syntax-highlighting` (colorea la sintaxis de los comandos).
    - **Oh My Posh:** Instala esta herramienta para crear un prompt de terminal altamente personalizable y descarga un tema predefinido (Catppuccin Frappe).
    - **.zshrc:** Reemplaza el `~/.zshrc` del usuario por una versión pre-configurada que integra todas estas herramientas y añade alias y funciones útiles, incluyendo una función `zsh_help` que muestra una lista de todos los comandos personalizados.
    - **Shell por Defecto:** Cambia el shell de inicio de sesión del usuario a Zsh.
 ### 2.4. `docker.sh`
 Configura un entorno de desarrollo basado en contenedores.
 - **Función Principal:** Instalar y configurar Docker Engine y Docker Compose.
 - **Acciones Realizadas:**
    - **Instalación:** Instala los paquetes `docker` y `docker-compose`.
    - **Servicio:** Habilita e inicia el servicio (`daemon`) de Docker para que se ejecute automáticamente al iniciar el sistema.
    - **Permisos:** Agrega el usuario actual al grupo `docker`, permitiéndole ejecutar comandos de Docker sin necesidad de `sudo`.
    - **Portainer (Opcional):** Pregunta al usuario si desea instalar Portainer, una interfaz gráfica web para gestionar contenedores, imágenes y volúmenes de Docker.
 ### 2.5. `davinci-resolve.sh`
 Módulo especializado para la instalación del software de edición de vídeo DaVinci Resolve.
 - **Función Principal:** Automatizar la compleja instalación de DaVinci Resolve en Arch Linux.
 - **Acciones Realizadas:**
    - **Dependencias:** Instala una larga lista de librerías y dependencias que no vienen por defecto en Arch Linux pero que son requeridas por el software.
    - **Instalador:** Requiere que el usuario haya descargado previamente el archivo `.zip` oficial de DaVinci Resolve en su carpeta de `~/Downloads`. El script lo descomprime y ejecuta el instalador.
    - **Post-Instalación:** Realiza ajustes en el sistema para asegurar que el programa pueda ejecutarse correctamente.
 ### 2.6. `disk-format.sh`
 Añade soporte para sistemas de archivos comunes.
 - **Función Principal:** Instalar las herramientas necesarias para interactuar con particiones y discos formateados en sistemas de archivos no nativos de Linux.
 - **Soporte Añadido:**
    - `ntfs-3g`: Para leer y escribir en particiones NTFS (Windows).
    - `exfatprogs`: Para particiones exFAT, comunes en tarjetas SD y unidades USB.
    - `e2fsprogs`: Herramientas para el sistema de archivos nativo de Linux (ext4).
 ### 2.7. `hyprland-config.sh`
 Configura un entorno de escritorio basado en el gestor de ventanas Hyprland.
 - **Función Principal:** Instalar Hyprland y un conjunto de aplicaciones y configuraciones para tener un entorno de "tiling window manager" funcional y estético.
 - **Software Adicional:** Instala componentes como `waybar` (barra de estado), `wofi` (lanzador de aplicaciones), `swaylock` (bloqueo de pantalla), y `kitty` (emulador de terminal).
 - **Configuración:** Despliega una estructura de archivos de configuración predefinida para todos estos componentes.
 ### 2.8. `icon_manager.sh`
 Permite personalizar la apariencia del sistema.
 - **Función Principal:** Instalar y aplicar diferentes temas de iconos.
 - **Temas Disponibles:** Ofrece una selección de temas populares como Papirus y Tela, instalándolos desde los repositorios de Arch o AUR.
 - **Aplicación:** Utiliza `gsettings` para cambiar el tema de iconos activo en el entorno de escritorio.
 ### 2.9. `mouse_cursor.sh`
 Mejora la apariencia del cursor del ratón.
 - **Función Principal:** Instalar y configurar el tema de cursores Bibata.
 - **Acciones Realizadas:** Descarga e instala el tema, y luego lo establece como el predeterminado para las aplicaciones GTK y el servidor gráfico X11.
 ### 2.10. `printer.sh`
 Configura el sistema para poder utilizar impresoras.
 - **Función Principal:** Instalar el sistema de impresión CUPS y los drivers necesarios.
 - **Acciones Realizadas:**
    - **CUPS:** Instala el servidor de impresión CUPS y sus filtros.
    - **Drivers:** Instala drivers genéricos y específicos para impresoras Epson.
    - **Servicios:** Habilita los servicios de `cups` y `avahi` (para la detección de impresoras en red).
    - **Permisos:** Añade al usuario al grupo `lp` para permitirle administrar impresoras.
 ### 2.11. `ssh-keyring.sh`
 Mejora la gestión de claves SSH.
 - **Función Principal:** Sincronizar las claves SSH del usuario con el agente de GNOME Keyring.
 - **Funcionamiento:**
    1.  Verifica que el agente de `gnome-keyring` esté en ejecución.
    2.  Busca todas las claves SSH privadas en el directorio `~/.ssh/`.
    3.  Utiliza `ssh-add` para añadir cada clave al agente. La primera vez que se use cada clave, GNOME Keyring pedirá la contraseña y la almacenará de forma segura. En usos posteriores, la desbloqueará automáticamente.
    - **Importancia:** Evita tener que escribir la contraseña de la clave SSH cada vez que se establece una conexión.
 ### 2.12. `zerotier.sh`
 Instala una herramienta de VPN.
 - **Función Principal:** Instalar y configurar el cliente de la VPN ZeroTier.
 - **Acciones Realizadas:**
    - **Instalación:** Instala el paquete `zerotier-one`.
    - **Servicio:** Habilita e inicia el servicio de ZeroTier.
    - **Unirse a Red (Opcional):** Pregunta al usuario si desea unirse a una red de ZeroTier y, en caso afirmativo, le pide el ID de la red.
--- a/Readme.md
+++ b/Readme.md
@@ -72,386 +72,46 @@ Selecciona las opciones que deseas instalar:
 ## 📋 Módulos Disponibles
-### 1. 📦 Aplicaciones (`apps.sh`)
+A continuación se detalla lo que hace cada módulo. Para una descripción técnica completa, consulta la [**DOCUMENTACION.md**](./DOCUMENTACION.md).
 - Editores como VS Code y Cursor (desde AUR)
 - Configura GNOME Keyring como agente de contraseñas y SSH, iniciando el daemon y exportando `SSH_AUTH_SOCK`
 - Detecta claves privadas en `~/.ssh` y las registra automáticamente con `ssh-add`
 - Instala y habilita servicios complementarios (keyd, logiops, TeamViewer, etc.)
-### 2. 🐚 Zsh (`zsh-config.sh`)
+- **`1) 📦 Instalar Aplicaciones`**: Instala un conjunto completo de software esencial, incluyendo herramientas de desarrollo (`python`, `nodejs`, `nvm`, `brew`), aplicaciones multimedia (`VLC`, `Audacity`), drivers optimizados para gráficos Intel Iris Xe y herramientas de gestión de energía como `tlp`. También configura servicios clave del sistema.
 - Instala Oh My Zsh y Oh My Posh (Catppuccin Frappe) con autocompletado
 - Clona/actualiza plugins externos como `zsh-autosuggestions` y `zsh-syntax-highlighting` (con fallback al sistema)
 - Modifica `.bashrc` para lanzar Zsh automáticamente
-### 3. 🐳 Docker (`docker.sh`)
+- **`2) 🐚 Configurar Zsh`**: Transforma tu terminal. Instala `Zsh`, el gestor de plugins `Oh My Zsh`, y el prompt visual `Oh My Posh` con el tema Catppuccin. Añade autocompletado, resaltado de sintaxis, una útil función de ayuda (`zsh_help`), y lo establece como tu shell por defecto.
 - Instalación de Docker y Docker Compose
 - Configuración de servicios
 - Instalación de Portainer
 - Agregar usuario al grupo docker
-### 4. 🌐 ZeroTier (`zerotier.sh`)
+- **`3) 🐳 Instalar Docker y Portainer`**: Prepara tu sistema para el desarrollo con contenedores. Instala `Docker` y `Docker Compose`, configura los servicios necesarios y, opcionalmente, despliega `Portainer`, una interfaz web para gestionar tus contenedores fácilmente.
 - Instalación de ZeroTier One
 - Configuración de servicio
 - Instrucciones para unirse a redes
-### 5. 🖨️ Impresoras (`printer.sh`)
+- **`4) 🌐 Instalar ZeroTier VPN`**: Instala el cliente de la VPN `ZeroTier`, una forma sencilla de crear redes virtuales seguras. El módulo te guiará para unirte a una red si lo deseas.
 - Instalación de CUPS
 - Drivers comunes de impresora
-### 6. 🖱️ Tema de Cursor (`mouse_cursor.sh`)
+- **`5) 🖨️ Configurar Impresoras (CUPS)`**: Instala el sistema de impresión de Linux (`CUPS`) y añade drivers para impresoras, con soporte especial para modelos Epson.
 - Instala el tema de cursor `Bibata-Modern-Ice`.
 - Configura el cursor para Hyprland y aplicaciones GTK.
-### 7. 🎨 Gestor de Iconos (`icon_manager.sh`)
+- **`6) 🖱️ Instalar Tema de Cursor (Bibata)`**: Mejora la apariencia de tu escritorio instalando el popular tema de cursores Bibata, dándole un aspecto moderno y pulido.
 - Menú interactivo para instalar y cambiar entre temas de iconos como Papirus, Tela y Candy.
-### K. 🔐 Sincronizar Claves SSH (`ssh-keyring.sh`)
+- **`7) 🎨 Gestionar Temas de Iconos`**: Te permite instalar y cambiar entre diferentes temas de iconos para personalizar la apariencia de tus aplicaciones y carpetas (incluye Papirus, Tela, etc.).
 - Inicia/activa GNOME Keyring para componentes `ssh` y `secrets`
 - Exporta `SSH_AUTH_SOCK` y registra claves desde `~/.ssh` usando `ssh-add`
 - Evita duplicados mediante fingerprints y muestra un resumen al finalizar
-### F. 💾 Soporte de Formatos (`disk-format.sh`)
+- **`K) 🔐 Sincronizar claves SSH con GNOME Keyring`**: Guarda de forma segura las contraseñas de tus claves SSH. Después de introducir la contraseña una vez, el sistema la recordará por ti, facilitando las conexiones a servidores remotos.
 - Instala utilidades para FAT32, exFAT, NTFS y ext4
 - Añade herramientas gráficas (GParted, GNOME Disks) para formateo manual
-### R. 🎬 DaVinci Resolve (`davinci-resolve.sh`)
+- **`F) 💾 Habilitar Formatos de Disco`**: Añade soporte para que tu sistema pueda leer y escribir en discos duros y memorias USB formateadas con sistemas de archivos de otros sistemas operativos como `NTFS` (Windows) o `exFAT`.
- Configuración de librerías y wrapper
+
 - **`H) 🎨 Instalar Configuración de Hyprland`**: Instala y configura el gestor de ventanas `Hyprland` y todas las herramientas necesarias para un entorno de escritorio *tiling* completo y funcional (`waybar`, `wofi`, `kitty`, etc.).
 - **`R) 🎬 Instalar DaVinci Resolve`**: Automatiza la compleja instalación del editor de vídeo profesional DaVinci Resolve. **Nota:** Requiere que descargues el instalador `.zip` oficial manualmente en tu carpeta de `~/Downloads`.
 ---
 ## 📚 Documentación Técnica
 Para una descripción detallada de la implementación de cada módulo, las funciones que utiliza y las configuraciones específicas que aplica, por favor consulta el archivo [**DOCUMENTACION.md**](./DOCUMENTACION.md).
 Este documento es ideal para desarrolladores que deseen extender la funcionalidad del script o para usuarios avanzados que quieran entender a fondo su funcionamiento.
 ---
 ## 🔧 Ejecutar Módulos Individualmente
-Cada módulo puede ejecutarse de forma independiente:
+Cada módulo puede ejecutarse de forma independiente si lo necesitas:
 ```bash
 # Instalar solo aplicaciones
 ./modules/apps.sh
 # Configurar solo Zsh
 ./modules/zsh-config.sh
 # Sincronizar claves SSH con GNOME Keyring
 ./modules/ssh-keyring.sh
 # Instalar Docker
 ./modules/docker.sh
-```
+# etc.
 ## 🌐 Instalación desde URL
 **Nota**: El script requiere que los módulos estén presentes localmente. Se recomienda clonar el repositorio completo.
 ```bash
 # Clonar el repositorio
 git clone https://github.com/marcogll/omarchy_setup.git
 cd omarchy_setup
 ./omarchy-setup.sh
 ```
 ---
 ## ✨ Características de los Módulos
 ### 📦 Aplicaciones
 - **Herramientas base**: git, curl, wget, base-devel, stow
 - **Editores**:
  - VS Code (desde AUR: visual-studio-code-bin)
  - Cursor (desde AUR: cursor-bin)
 - **Multimedia**:
  - VLC con todos los plugins (vlc-plugins-all)
  - Audacity (editor de audio)
  - Inkscape (editor gráfico vectorial)
  - ffmpeg, gstreamer con plugins
  - yt-dlp (descarga de videos)
 - **Red y transferencia**:
  - FileZilla (cliente FTP)
  - Telegram Desktop
  - scrcpy (control Android desde PC)
 - **Utilidades**: neofetch, htop, fastfetch, btop, vim, nano, tmux
 - **Seguridad y sincronización**:
  - GNOME Keyring + libsecret + Seahorse
  - Configuración automática del agente SSH y carga de claves en `~/.ssh`
  - openssh, rsync
 - Recomendado cerrar sesión tras la instalación para que las variables de entorno del keyring se apliquen a nuevas terminales
 - **Flatpak**: Sistema de paquetes universal
 - **Drivers Intel Iris Xe**:
  - Mesa y Vulkan (gráficos 3D)
  - Intel Media Driver (aceleración de video VA-API)
  - OpenCL (Intel Compute Runtime desde AUR)
  - Codecs y herramientas de hardware acceleration
 - **Desde AUR**:
  - keyd (remapeo de teclado)
  - fragments (cliente BitTorrent)
  - logiops (driver Logitech)
  - ltunify (Logitech Unifying Receiver)
  - TeamViewer (acceso remoto, con daemon habilitado)
  - intel-compute-runtime (OpenCL para Intel)
 ### 🐚 Zsh
 - Oh My Zsh + Oh My Posh (tema Catppuccin Frappe)
 - Plugins externos gestionados automáticamente (`zsh-autosuggestions`, `zsh-syntax-highlighting`)
 - Genera el archivo de autocompletado `_oh-my-posh` en `~/.local/share/zsh/site-functions`
 - Modifica `.bashrc` para lanzar Zsh automáticamente
 ### 🔐 GNOME Keyring SSH
 - Arranca el daemon de GNOME Keyring con componentes de `ssh` y `secrets`
 - Garantiza que `SSH_AUTH_SOCK` apunte al socket del keyring (persistido en `~/.config/environment.d`)
 - Busca claves privadas en `~/.ssh` (excluyendo `.pub` y certificados) y las registra con `ssh-add`
 - Evita añadir claves duplicadas y muestra cómo verificar con `ssh-add -l`
 ### 🐳 Docker
 - Portainer (interfaz web de gestión)
 - Usuario agregado al grupo docker
 - Servicios habilitados y configurados
 ### 🌐 ZeroTier
 - ZeroTier One VPN
 - Servicio configurado y habilitado
 - Instrucciones para unirse a redes
 ### 🖨️ Impresoras
 - CUPS (Common Unix Printing System)
 - Drivers comunes de impresora
 - Interfaz web en http://localhost:631
 - Soporte para impresoras de red
 ### 🎬 DaVinci Resolve
 - Instalación para Intel GPU
 - Configuración de OpenCL
 - Ajuste de librerías del sistema
 - Wrapper para ejecución
 ---
 ## 📦 Paquetes instalados
 <details>
 <summary>Ver lista completa (click para expandir)</summary>
 ### Sistema Base
 - **zsh**, **zsh-completions**
 - **oh-my-posh-bin** (desde AUR)
 - **git**, **curl**, **wget**
 - **yay** (AUR helper, compilado desde AUR)
 ### Desarrollo
 - **python**, **python-pip**, **python-virtualenv**
 - **nodejs**, **npm**
 - **go** (Golang)
 - **docker**, **docker-compose**
 - **base-devel** (herramientas de compilación)
 ### Utilidades de Terminal
 - **eza** (ls mejorado)
 - **bat** (cat mejorado)
 - **zoxide** (cd inteligente)
 - **fastfetch** (info del sistema)
 - **htop**, **btop** (monitores del sistema)
 - **tree** (visualización de directorios)
 ### Multimedia y Control
 - **yt-dlp**, **ffmpeg**
 - **playerctl**, **brightnessctl**, **pamixer**
 - **audacity**, **inkscape**
 ### Red y Seguridad
 - **zerotier-one** (desde AUR)
 - **gnome-keyring**, **libsecret**, **seahorse**
 - **lsof**, **net-tools**
 - **teamviewer**
 ### Utilidades del Sistema
 - **nano**, **unzip**, **tar**
 - **p7zip**, **unrar**
 ### Instalaciones Adicionales
 - **speedtest-cli** (vía pip)
 </details>
 ---
 ## 🎯 Durante la instalación
 El script ejecuta los siguientes pasos:
 1. **Verificación de requerimientos** (root, Arch Linux, conexión a Internet)
 2. **Instalación de paquetes base** desde repositorios oficiales
 3. **Instalación de yay** desde AUR (si no está instalado)
 4. **Configuración de Docker** (servicio y permisos de usuario)
 5. **Instalación de Oh My Zsh y plugins**
 6. **Configuración de .zshrc y tema Catppuccin** desde GitHub
 7. **Configuración de TeamViewer** (servicio)
 8. **Instalación de ZeroTier One** desde AUR (opcional)
 9. **Configuración de GNOME Keyring** (opcional)
 10. **Configuración de claves SSH** (opcional)
 ### Preguntas interactivas:
 - **ZeroTier Network ID**: Si deseas unirte a una red ZeroTier (opcional)
 - **GNOME Keyring**: Si deseas configurar el almacén de contraseñas
 - **Claves SSH**: Si deseas añadir claves SSH existentes al agente
 ---
 ## 🔑 GNOME Keyring
 El keyring guarda contraseñas de forma segura:
 - **Git** (credential helper)
 - **SSH keys** (almacenadas de forma segura)
 - **Aplicaciones GNOME**
 ### Configuración automática:
 El script configura automáticamente:
 - PAM para auto-desbloqueo del keyring
 - Inicio automático de gnome-keyring-daemon
 - Integración con SSH agent
 ### Comandos útiles:
 ```bash
 # Abrir gestor de contraseñas
 seahorse
 # Ver estado del keyring
 gnome-keyring-daemon --version
 # Comandos de ZeroTier (aliases en .zshrc)
 zt              # Alias de sudo zerotier-cli
 ztstatus        # Ver redes conectadas (listnetworks)
 ztinfo          # Info del nodo (info)
 ```
 ---
 ## ⚙️ Configuración incluida
 ### Aliases de Arch Linux
 ```bash
 pacu            # Actualizar sistema
 paci <pkg>      # Instalar paquete
 pacr <pkg>      # Remover paquete
 pacs <query>    # Buscar paquete
 yayu            # Actualizar AUR
 yayi <pkg>      # Instalar desde AUR
 ```
 ### Git shortcuts
 ```bash
 gs              # git status
 ga              # git add
 gc              # git commit
 gcm "msg"       # git commit -m
 gp              # git push
 gl              # git pull
 gco <branch>    # git checkout
 gcb <branch>    # git checkout -b
 glog            # git log gráfico
 gac "msg"       # add + commit
 ```
 ### Docker
 ```bash
 dc              # docker compose
 d               # docker
 dps             # docker ps -a
 di              # docker images
 dex <name> sh   # docker exec -it
 dlog <name>     # docker logs -f
 ```
 ### Python
 ```bash
 py              # python
 venv create     # Crear .venv
 venv on         # Activar
 venv off        # Desactivar
 pir             # pip install -r requirements.txt
 pipf            # pip freeze > requirements.txt
 ```
 ### yt-dlp
 ```bash
 ytm <URL>           # Descargar audio MP3 320kbps
 ytm "lofi beats"    # Buscar y descargar
 ytv <URL>           # Descargar video MP4 (calidad por defecto)
 ytv <URL> 1080      # Descargar video en 1080p
 ytv <URL> 720       # Descargar video en 720p
 ytls                # Listar últimos descargas
 ```
 Descargas en: `~/Videos/YouTube/{Music,Videos}/`
 ### NPM
 ```bash
 nrs             # npm run start
 nrd             # npm run dev
 nrb             # npm run build
 nrt             # npm run test
 ni              # npm install
 nid             # npm install --save-dev
 nig             # npm install -g
 ```
 ### Utilidades
 ```bash
 mkcd <dir>          # mkdir + cd
 extract <file>      # Extraer cualquier archivo
 killport <port>     # Matar proceso en puerto
 serve [port]        # Servidor HTTP (default 8000)
 clima               # Ver clima Saltillo
 ```
 ---
 ## 🌐 ZeroTier Network ID
 Tu Network ID tiene formato: `a0cbf4b62a1234567` (16 caracteres hex)
 ### Dónde encontrarlo:
 1. Ve a https://my.zerotier.com
 2. Selecciona tu red
 3. Copia el Network ID
 ### Después de la instalación:
 1. Ve a tu panel de ZeroTier
 2. Busca el nuevo dispositivo
 3. **Autorízalo** marcando el checkbox
 ### Comandos útiles:
 ```bash
 # Ver redes
 ztstatus
 # Unirse a red
 sudo zerotier-cli join <network-id>
 # Salir de red
 sudo zerotier-cli leave <network-id>
 # Info del nodo
 ztinfo
 ```
 ---
 ## 📂 Estructura creada
 ```
 $HOME/
 ├── .zshrc                          # Configuración de Zsh (descargado desde GitHub)
 ├── .zshrc.local                   # Config local (opcional, no creado automáticamente)
 ├── .oh-my-zsh/                    # Oh My Zsh
 │   └── custom/plugins/            # Plugins adicionales
 │       ├── zsh-autosuggestions/
 │       └── zsh-syntax-highlighting/
 ├── .poshthemes/                   # Temas Oh My Posh
 │   └── catppuccin_frappe.omp.json # Tema Catppuccin Frappe
 ├── .zsh_functions/                # Funciones personalizadas (directorio creado)
 ├── Videos/YouTube/                # Descargas de yt-dlp
 │   ├── Music/                     # Audios MP3
 │   └── Videos/                    # Videos MP4
 ├── .ssh/                          # Claves SSH (si existen)
 └── omarchy-setup.log             # Log de instalación
 ```
 ---
@@ -460,261 +120,61 @@ $HOME/
 ### 1. Reiniciar sesión o terminal (IMPORTANTE)
-**⚠️ REINICIO REQUERIDO** si se instalaron servicios como TeamViewer o ZeroTier.
+Para que todos los cambios surtan efecto (nuevo shell, permisos de `docker`, variables de entorno), es fundamental que **cierres sesión y vuelvas a iniciarla** o reinicies el sistema.
 ### 2. Verificar la instalación
 Una vez que hayas vuelto a iniciar sesión, abre una terminal y comprueba que todo funciona como esperas:
 ```bash
-# Cerrar y volver a abrir la terminal para usar Zsh
+# Verifica que tu shell es Zsh y el prompt se ve bien
-# O cerrar sesión y volver a entrar para aplicar:
+echo $SHELL
 # - Cambio de shell a Zsh
 # - Grupos (docker)
 # - Permisos del sistema
 ```
-### 2. Verificar instalación
+# Comprueba que Docker funciona sin sudo
 ```bash
 # Ver versión de Zsh
 zsh --version
 # Ver tema Oh My Posh
 oh-my-posh version
 # Verificar Docker
 docker ps
-# Ver ZeroTier (si se configuró)
+# Lista tus claves SSH gestionadas por el agente
-ztstatus
+ssh-add -l
 # Ver TeamViewer (si se instaló)
 teamviewer info
 # Actualizar sistema
 pacu
 ```
 ### 3. Configuraciones opcionales
 ```bash
 # Crear archivo de configuración local
 nano ~/.zshrc.local
 # Ejemplo de contenido:
 export OPENAI_API_KEY="sk-..."
 export GITHUB_TOKEN="ghp_..."
 alias miproyecto="cd ~/Projects/mi-app && code ."
 ```
 ---
 ## 🛠️ Solución de problemas
-### Docker no funciona sin sudo
+### El prompt de Zsh se ve con caracteres extraños (▯, ?, etc.)
-```bash
+Esto ocurre porque no tienes instalada una **Nerd Font**, que contiene los iconos que usa el prompt.
 # Verificar que estás en el grupo docker
 groups  # Debe incluir 'docker'
-# Si no aparece, reinicia sesión o ejecuta:
+1.  **Instala una Nerd Font.** El propio `oh-my-posh` puede hacerlo por ti:
-newgrp docker
+    ```bash
    oh-my-posh font install meslo
    ```
 2.  **Configura tu terminal.** Abre las preferencias de tu emulador de terminal (GNOME Terminal, Konsole, Kitty, etc.) y cambia la fuente del perfil a la que acabas de instalar (ej. `MesloLGM Nerd Font`).
-# Verificar acceso
+### Docker no funciona sin `sudo`
 docker ps
 ```
-### Git sigue pidiendo contraseña
+Asegúrate de haber **cerrado sesión y vuelto a iniciarla** después de ejecutar el módulo de Docker. Si el problema persiste, verifica que tu usuario pertenece al grupo `docker` con el comando `groups`.
 ```bash
 # Verificar credential helper
 git config --global credential.helper
 # Debe ser: libsecret
 # Si no, configurar:
 git config --global credential.helper libsecret
 # Abrir Seahorse y verificar keyring
 seahorse
 # Verificar que el keyring está corriendo
 pgrep -u "$USER" gnome-keyring-daemon
 ```
 ### ZeroTier no conecta
 ```bash
 # Verificar servicio
 sudo systemctl status zerotier-one
 # Ver logs
 sudo journalctl -u zerotier-one -f
 # Reiniciar servicio
 sudo systemctl restart zerotier-one
 # Verificar que autorizaste el nodo en https://my.zerotier.com
 ztinfo
 ztstatus
 ```
 ### Oh My Posh no se muestra correctamente
 Para que el tema de Oh My Posh se visualice correctamente, es **esencial** tener instalada una "Nerd Font". Estas fuentes incluyen los íconos y símbolos especiales que usa el prompt.
 El script **no** instala fuentes automáticamente, pero puedes hacerlo fácilmente con el siguiente comando:
 ```bash
 # Instalar la fuente recomendada (Meslo LGM Nerd Font)
 oh-my-posh font install meslo
 ```
 Después de instalar la fuente, **debes configurar tu emulador de terminal** para que la use. Este paso es crucial y varía según la terminal que utilices (por ejemplo, en GNOME Terminal, Konsole, Alacritty, etc., deberás ir a sus preferencias y seleccionar "MesloLGM Nerd Font").
 **Verificaciones adicionales:**
 ```bash
 # Verificar que oh-my-posh está instalado
 which oh-my-posh
 # Verificar que el tema existe
 ls ~/.poshthemes/catppuccin_frappe.omp.json
 # Listar fuentes para confirmar que Meslo está instalada
 fc-list | grep -i "meslo"
 ```
 ### El shell no cambió a Zsh
 ```bash
 # Verificar shell actual
 echo $SHELL
 # Cambiar manualmente
 chsh -s $(which zsh)
 # Cerrar y abrir nueva terminal
 ```
 ---
 ## 📚 Recursos
 - **Arch Wiki**: https://wiki.archlinux.org/
 - **Oh My Zsh**: https://ohmyz.sh/
 - **Oh My Posh**: https://ohmyposh.dev/
 - **Catppuccin Theme**: https://github.com/catppuccin/catppuccin
 - **ZeroTier**: https://www.zerotier.com/
 - **yt-dlp**: https://github.com/yt-dlp/yt-dlp
 - **Nerd Fonts**: https://www.nerdfonts.com/ (requerido para iconos del prompt)
 - **yay AUR Helper**: https://github.com/Jguer/yay
 ---
 ## 🆘 Soporte
 Si encuentras problemas:
 1. Revisa los mensajes de error durante la instalación
 2. Verifica que cerraste sesión después de instalar (para aplicar grupos)
 3. Comprueba que los grupos se aplicaron: `groups`
 4. Verifica que los módulos están presentes: `ls modules/`
 5. Ejecuta módulos individualmente para aislar problemas
 6. Abre un issue en: https://github.com/marcogll/scripts_mg/issues
 ### Verificar Instalación de Módulos
 ```bash
 # Verificar que todos los módulos existen
 ls -la modules/
 # Ejecutar un módulo individual para debug
 bash -x modules/apps.sh
 ```
 ---
 ## 🔧 Agregar Nuevos Módulos
-Para agregar un nuevo módulo:
+La estructura modular facilita la adición de nueva funcionalidad.
-1. Crea un archivo en `modules/nombre-modulo.sh`:
+1.  Crea un nuevo script en la carpeta `modules/`. Sigue la plantilla de los módulos existentes.
 2.  Añade una entrada para tu nuevo módulo en el array `MODULES` dentro de `omarchy-setup.sh`.
 3.  ¡Listo! Tu módulo aparecerá en el menú principal.
-```bash
+Para más detalles, consulta la [guía para contribuidores](./.docs/AGENTS.md).
 #!/usr/bin/env bash
 # ===============================================================
 # nombre-modulo.sh - Descripción del módulo
 # ===============================================================
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/common.sh"
 install_nombre_modulo() {
    log_step "Instalación de Nombre Módulo"
    # Tu código aquí
    log_info "Instalando paquetes..."
    sudo pacman -S --noconfirm --needed paquete1 paquete2 || {
        log_error "Error al instalar paquetes"
        return 1
    }
    log_success "Módulo instalado correctamente"
    return 0
 }
 # Ejecutar si se llama directamente
 if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
    install_nombre_modulo "$@"
 fi
 ```
 2. Agrega el módulo al menú en `omarchy-setup.sh`:
 Dentro del script `omarchy-setup.sh`, localiza el array asociativo `MODULES` y añade una nueva línea.
 ```bash
 # --- Definición de Módulos ---
 # Clave: Opción del menú
 # Valor: "Nombre del Fichero;Función Principal;Descripción;Tipo (bg/fg)"
 declare -A MODULES
 MODULES=(
    ["1"]="apps;run_module_main;📦 Instalar Aplicaciones;bg"
    # ... otros módulos ...
    ["N"]="nombre-modulo;install_nombre_modulo;🚀 Mi Nuevo Módulo;fg"
 )
 ```
 - **Clave (`"N"`):** La tecla que el usuario presionará en el menú.
 - **Valor:** Una cadena de texto con 4 partes separadas por punto y coma (`;`):
    1.  `nombre-modulo`: El nombre del fichero `.sh` sin la extensión.
    2.  `install_nombre_modulo`: La función dentro de ese fichero que se debe ejecutar.
    3.  `🚀 Mi Nuevo Módulo`: La descripción que aparecerá en el menú.
    4.  `fg` o `bg`: `fg` (foreground) para scripts interactivos, `bg` (background) para tareas que pueden usar un spinner.
 3. Si quieres incluirlo en la opción "Instalar Todo", añade la clave del menú (en este caso, `"N"`) al array `INSTALL_ALL_CHOICES`.
 ---
 ## 📝 Changelog
-### v3.0.0 (2025-01-XX)
+### v3.0.0
- ✨ **Nueva estructura modular**: Scripts independientes para cada componente
+- ✨ **Reestructuración completa a un sistema modular.**
- 🎨 **Menú interactivo**: Selecciona qué instalar según tus necesidades
+-  interactive menu para seleccionar componentes.
- 🎨 **Interfaz mejorada**: Colores y mensajes claros durante la instalación
+- 📜 **Añadida documentación técnica** (`DOCUMENTACION.md`) y guía para contribuidores (`AGENTS.md`).
- 📦 **Módulos disponibles**:
+- 🎨 **Interfaz de usuario mejorada** con logs claros y un indicador de progreso.
-  - Aplicaciones (apps.sh)
+- 🔧 **Módulos actualizados** y separados por funcionalidad.
  - Zsh (zsh-config.sh)
  - Docker y Portainer (docker.sh)
  - ZeroTier (zerotier.sh)
  - Impresoras CUPS (printer.sh)
  - Tema de Cursor (mouse_cursor.sh)
  - DaVinci Resolve (davinci-resolve.sh)
  - Gestor de Iconos (icon_manager.sh)
 ### v2.8.1 (2025-11-02)
 - Versión unificada con estética Catppuccin
 - Instalación mejorada de paquetes con manejo de errores robusto
 - **oh-my-posh** instalado desde AUR automáticamente
 - Configuración `.zshrc` descargada desde GitHub
 ---