diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..6ea0c3c
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,58 @@
+# =============================================================================
+# Docker Build Context Optimization
+# Excluye archivos innecesarios para mejorar el rendimiento del build
+# =============================================================================
+
+# Control de versiones
+.git/
+.gitignore
+.gitattributes
+.gitmodules
+
+# Archivos de desarrollo y configuración
+.env*
+.vscode/
+.idea/
+.claude/
+*.log
+
+# Dependencias y builds
+node_modules/
+bower_components/
+vendor/
+composer.lock
+package-lock.json
+
+# Archivos temporales y cache
+storage/cache/
+storage/logs/
+tmp/
+*.tmp
+*.swp
+*.swo
+*~
+
+# Archivos de backup y tests
+*.backup
+test/
+wp-test/
+db_data/
+wordpress/
+
+# Archivos comprimidos y releases
+*.zip
+*.tar.gz
+*.rar
+antonella-framework-for-wp.zip
+
+# Archivos del sistema
+.DS_Store
+Thumbs.db
+
+# Documentación de desarrollo (mantener solo esenciales)
+PROBLEMAS_DE_INSTALACION.md
+
+# CLI tools
+wp-cli.phar
+antonella
+antonella2
\ No newline at end of file
diff --git a/.gitattributes b/.gitattributes
index bdb0cab..49c0d8b 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -15,3 +15,4 @@
 *.PDF	 diff=astextplain
 *.rtf	 diff=astextplain
 *.RTF	 diff=astextplain
+*.sh text eol=lf
\ No newline at end of file
diff --git a/docker-compose.yaml b/docker-compose.yaml
index 331d6dd..a038867 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -1,5 +1,24 @@
+# =============================================================================
+# Antonella Framework for WordPress - Docker Compose Configuration
+# 
+# Entorno de desarrollo completo con:
+# - MySQL 8.0 con healthchecks
+# - WordPress con framework preconfigurado
+# - phpMyAdmin para gestión de BD
+# - WP-CLI para automatización
+#
+# Requisitos:
+# - Docker Desktop 4.53.0+ (compatibilidad ARM64/Windows)
+# - Docker Compose v2+
+#
+# Uso: docker compose up -d
+# =============================================================================
+
 services:
-  # Base de datos MySQL
+  # =============================================================================
+  # Base de datos MySQL 8.0
+  # Configurada con healthchecks para dependencias seguras
+  # =============================================================================
   mysql:
     container_name: mysql-antonella
     image: mysql:8.0
@@ -15,11 +34,16 @@ services:
       - mysql_data:/var/lib/mysql
     command: --default-authentication-plugin=mysql_native_password
     healthcheck:
-      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
-      timeout: 20s
-      retries: 10
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "wordpress", "-pwordpress"]
+      interval: 5s
+      timeout: 10s
+      retries: 20
+      start_period: 30s
 
-  # phpMyAdmin para gestión de base de datos
+  # =============================================================================
+  # phpMyAdmin - Gestión visual de base de datos
+  # Acceso: http://localhost:9000 (cambiar puerto si está ocupado)
+  # =============================================================================
   phpmyadmin:
     image: phpmyadmin/phpmyadmin:latest
     container_name: phpmyadmin-antonella
@@ -35,7 +59,12 @@ services:
     ports:
       - "9000:80"
 
-  # WordPress con configuración automática
+  # =============================================================================
+  # WordPress con Antonella Framework
+  # Configuración automática de desarrollo con inicialización completa
+  # Acceso: http://localhost:8080
+  # Admin: http://localhost:8080/wp-admin (test/test)
+  # =============================================================================
   wordpress:
     build:
       context: .
@@ -96,7 +125,10 @@ services:
         // Configuración de papelera
         define('EMPTY_TRASH_DAYS', 7);
 
-  # Servicio para ejecutar WP-CLI commands
+  # =============================================================================
+  # WP-CLI Container - Automatización y comandos WordPress
+  # Uso: docker compose exec wpcli wp <comando>
+  # =============================================================================
   wpcli:
     build:
       context: .
@@ -115,14 +147,22 @@ services:
       WORDPRESS_DB_NAME: wordpress
     command: tail -f /dev/null  # Mantener el contenedor activo
 
+# =============================================================================
 # Volúmenes persistentes
+# Mantienen datos entre reinicios de contenedores
+# =============================================================================
 volumes:
   mysql_data:
     driver: local
+    # Datos de MySQL (base de datos, configuraciones)
   wordpress_data:
     driver: local
+    # Instalación completa de WordPress (core, themes, uploads)
 
+# =============================================================================
 # Red personalizada
+# Permite comunicación entre servicios con nombres de host
+# =============================================================================
 networks:
   default:
     name: antonella-network
\ No newline at end of file
diff --git a/docker/Dockerfile.wordpress b/docker/Dockerfile.wordpress
index dc57df6..64bc285 100644
--- a/docker/Dockerfile.wordpress
+++ b/docker/Dockerfile.wordpress
@@ -1,18 +1,35 @@
+# =============================================================================
+# Antonella Framework - WordPress Development Container
+# 
+# Builds a WordPress environment with:
+# - WP-CLI for automation
+# - Custom initialization scripts
+# - Development tools and dependencies
+#
+# Compatible with: linux/amd64, linux/arm64, windows
+# =============================================================================
+
 FROM wordpress:latest
 
-# Instalar dependencias necesarias
+# =============================================================================
+# Install system dependencies and development tools
+# =============================================================================
 RUN apt-get update && apt-get install -y \
     curl \
     less \
     default-mysql-client \
     && rm -rf /var/lib/apt/lists/*
 
-# Instalar WP-CLI
+# =============================================================================
+# Install WP-CLI for WordPress automation
+# =============================================================================
 RUN curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar \
     && chmod +x wp-cli.phar \
     && mv wp-cli.phar /usr/local/bin/wp
 
-# Crear directorio para scripts
+# =============================================================================
+# Setup custom scripts directory and initialization
+# =============================================================================
 RUN mkdir -p /docker-scripts
 
 # Copiar script de inicialización
@@ -23,5 +40,9 @@ RUN chmod +x /docker-scripts/init-wordpress.sh
 COPY docker/entrypoint.sh /docker-scripts/
 RUN chmod +x /docker-scripts/entrypoint.sh
 
+# =============================================================================
+# Configure container startup
+# =============================================================================
+
 ENTRYPOINT ["/docker-scripts/entrypoint.sh"]
 CMD ["apache2-foreground"]
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
index 8db59aa..d57b692 100644
--- a/docker/entrypoint.sh
+++ b/docker/entrypoint.sh
@@ -1,17 +1,21 @@
 #!/bin/bash
 set -e
 
+echo "🚀 Iniciando contenedor de WordPress..."
+
 # Ejecutar el entrypoint original de WordPress
 docker-entrypoint.sh "$@" &
 
 # Obtener el PID del proceso de WordPress
 WORDPRESS_PID=$!
 
-# Esperar un poco para que WordPress se inicie
-sleep 10
+echo "⏳ Esperando a que WordPress se inicie..."
+# Esperar más tiempo para que WordPress se inicie completamente
+sleep 30
 
-# Ejecutar la inicialización en segundo plano
-/docker-scripts/init-wordpress.sh &
+echo "🔧 Ejecutando script de inicialización de WordPress..."
+# Ejecutar la inicialización en segundo plano con logging
+/docker-scripts/init-wordpress.sh 2>&1 | tee /tmp/init-wordpress.log &
 
 # Esperar a que WordPress termine
 wait $WORDPRESS_PID
diff --git a/docker/init-wordpress.sh b/docker/init-wordpress.sh
index f2fa2fa..c6baa58 100644
--- a/docker/init-wordpress.sh
+++ b/docker/init-wordpress.sh
@@ -1,33 +1,76 @@
 #!/bin/bash
 
 # Script para inicializar WordPress automáticamente
-set -e
+# NO usar 'set -e' para manejar errores manualmente
+set +e
 
 echo "🚀 Iniciando configuración automática de WordPress..."
+echo "📅 $(date)"
 
-# Esperar a que MySQL esté listo
+# Esperar a que MySQL esté listo con timeout
 echo "⏳ Esperando a que MySQL esté disponible..."
-while ! mysqladmin ping -h"mysql" -u"wordpress" -p"wordpress" --silent; do
-    sleep 1
+MYSQL_TIMEOUT=120  # 2 minutos
+MYSQL_COUNTER=0
+MYSQL_READY=false
+
+while [ $MYSQL_COUNTER -lt $MYSQL_TIMEOUT ]; do
+    if mysqladmin ping -h"mysql" -u"wordpress" -p"wordpress" --skip-ssl --silent 2>/dev/null; then
+        MYSQL_READY=true
+        echo "✅ MySQL está listo (después de ${MYSQL_COUNTER} segundos)"
+        break
+    fi
+    
+    if [ $((MYSQL_COUNTER % 10)) -eq 0 ]; then
+        echo "   ⏱️  Esperando MySQL... (${MYSQL_COUNTER}/${MYSQL_TIMEOUT}s)"
+    fi
+    
+    sleep 2
+    MYSQL_COUNTER=$((MYSQL_COUNTER + 2))
 done
-echo "✅ MySQL está listo"
 
-# Esperar a que WordPress esté disponible
+if [ "$MYSQL_READY" = false ]; then
+    echo "❌ ERROR: MySQL no está disponible después de ${MYSQL_TIMEOUT} segundos"
+    echo "❌ Verifica que el contenedor de MySQL esté corriendo correctamente"
+    echo "💡 Ejecuta: docker compose logs mysql"
+    exit 1
+fi
+
+# Esperar a que WordPress esté disponible con timeout
 echo "⏳ Esperando a que WordPress esté disponible..."
-while ! curl -s http://localhost > /dev/null; do
+WP_TIMEOUT=60  # 1 minuto
+WP_COUNTER=0
+WP_READY=false
+
+while [ $WP_COUNTER -lt $WP_TIMEOUT ]; do
+    if curl -s http://localhost > /dev/null 2>&1; then
+        WP_READY=true
+        echo "✅ WordPress está disponible (después de ${WP_COUNTER} segundos)"
+        break
+    fi
+    
+    if [ $((WP_COUNTER % 10)) -eq 0 ]; then
+        echo "   ⏱️  Esperando WordPress... (${WP_COUNTER}/${WP_TIMEOUT}s)"
+    fi
+    
     sleep 2
+    WP_COUNTER=$((WP_COUNTER + 2))
 done
-echo "✅ WordPress está disponible"
+
+if [ "$WP_READY" = false ]; then
+    echo "❌ ERROR: WordPress no está disponible después de ${WP_TIMEOUT} segundos"
+    echo "❌ Verifica que Apache esté corriendo correctamente"
+    exit 1
+fi
 
 # Verificar si WordPress ya está instalado
-if wp core is-installed --allow-root --path=/var/www/html; then
+if wp core is-installed --allow-root --path=/var/www/html --quiet 2>/dev/null; then
     echo "✅ WordPress ya está instalado"
     
     # Actualizar WordPress a la última versión
     echo "🔄 Verificando actualizaciones de WordPress..."
-    if wp core check-update --allow-root --path=/var/www/html --format=count; then
+    if wp core check-update --allow-root --path=/var/www/html --format=count --quiet 2>/dev/null | grep -q "^[1-9]"; then
         echo "📥 Actualizando WordPress a la última versión..."
-        wp core update --allow-root --path=/var/www/html
+        wp core update --allow-root --path=/var/www/html --quiet 2>/dev/null
         echo "✅ WordPress actualizado correctamente"
     else
         echo "✅ WordPress ya está en la última versión"
@@ -43,73 +86,80 @@ else
         --admin_password="test" \
         --admin_email="test@antonella.test" \
         --allow-root \
-        --path=/var/www/html
+        --path=/var/www/html \
+        --quiet 2>/dev/null
     
     echo "✅ WordPress instalado correctamente"
     
     # Actualizar WordPress a la última versión después de la instalación
     echo "🔄 Actualizando WordPress a la última versión..."
-    wp core update --allow-root --path=/var/www/html
+    wp core update --allow-root --path=/var/www/html --quiet 2>/dev/null
     echo "✅ WordPress actualizado a la última versión"
 fi
 
 # Desinstalar plugins por defecto de WordPress
 echo "🗑️  Desinstalando plugins por defecto..."
-wp plugin delete hello-dolly --allow-root --path=/var/www/html || echo "⚠️  Hello Dolly ya no está instalado"
-wp plugin delete akismet --allow-root --path=/var/www/html || echo "⚠️  Akismet ya no está instalado"
+wp plugin delete hello-dolly --allow-root --path=/var/www/html --quiet 2>/dev/null || true
+wp plugin delete akismet --allow-root --path=/var/www/html --quiet 2>/dev/null || true
 echo "✅ Plugins por defecto eliminados"
 
-# Activar el framework Antonella
-echo "🔌 Activando Antonella Framework..."
-wp plugin activate antonella-framework --allow-root --path=/var/www/html || echo "⚠️  Plugin antonella-framework no encontrado, asegúrate de que esté en la carpeta correcta"
+# Activar el framework Antonella (si existe)
+echo "🔌 Verificando Antonella Framework..."
+if wp plugin list --name=antonella-framework --allow-root --path=/var/www/html --format=count 2>/dev/null | grep -q "1"; then
+    wp plugin activate antonella-framework --allow-root --path=/var/www/html 2>/dev/null && echo "✅ Antonella Framework activado" || echo "⚠️  No se pudo activar antonella-framework"
+else
+    echo "ℹ️  Plugin antonella-framework no encontrado (se activará cuando esté disponible)"
+fi
 
 # Instalar y activar Plugin Check
-echo "📥 Instalando Plugin Check..."
-wp plugin install plugin-check --activate --allow-root --path=/var/www/html
-
-# Instalar otros plugins útiles para desarrollo
-echo "📥 Instalando plugins adicionales para desarrollo..."
+echo "📥 Instalando plugins de desarrollo..."
+wp plugin install plugin-check --activate --allow-root --path=/var/www/html --quiet 2>/dev/null || true
 
 # Query Monitor - Para debugging
-wp plugin install query-monitor --activate --allow-root --path=/var/www/html
+wp plugin install query-monitor --activate --allow-root --path=/var/www/html --quiet 2>/dev/null || true
 
 # Debug Bar - Para debugging adicional
-wp plugin install debug-bar --activate --allow-root --path=/var/www/html
+wp plugin install debug-bar --activate --allow-root --path=/var/www/html --quiet 2>/dev/null || true
 
 # Theme Check - Para verificar temas
-wp plugin install theme-check --activate --allow-root --path=/var/www/html
+wp plugin install theme-check --activate --allow-root --path=/var/www/html --quiet 2>/dev/null || true
 
-# Developer - Herramientas de desarrollo
-wp plugin install developer --activate --allow-root --path=/var/www/html
+echo "✅ Plugins de desarrollo instalados"
 
 # Configurar tema por defecto
 echo "🎨 Configurando tema..."
-wp theme activate twentytwentyfour --allow-root --path=/var/www/html
+wp theme activate twentytwentyfour --allow-root --path=/var/www/html --quiet 2>/dev/null || true
+echo "✅ Tema configurado"
 
 # Configurar permalinks
 echo "🔗 Configurando permalinks..."
-wp rewrite structure '/%postname%/' --allow-root --path=/var/www/html
-wp rewrite flush --allow-root --path=/var/www/html
+wp rewrite structure '/%postname%/' --allow-root --path=/var/www/html --quiet 2>/dev/null
+wp rewrite flush --allow-root --path=/var/www/html --quiet 2>/dev/null
 echo "✅ Permalinks configurados"
 
 # Corregir permisos de WordPress para actualizaciones
 echo "🔧 Corrigiendo permisos de WordPress..."
-chown -R www-data:www-data /var/www/html/wp-content/
-chmod -R 755 /var/www/html/wp-content/
-chmod -R 775 /var/www/html/wp-content/uploads/
-chmod -R 775 /var/www/html/wp-content/upgrade/
-echo "✅ Permisos de WordPress corregidos"
+# Excluir directorios montados del host para evitar errores de permisos en Linux
+find /var/www/html/wp-content/ -maxdepth 1 -type d ! -name 'plugins' ! -name 'debug.log' -exec chown -R www-data:www-data {} + 2>/dev/null || true
+find /var/www/html/wp-content/ -maxdepth 1 -type d ! -name 'plugins' ! -name 'debug.log' -exec chmod -R 755 {} + 2>/dev/null || true
+
+# Crear y dar permisos a directorios necesarios
+mkdir -p /var/www/html/wp-content/uploads /var/www/html/wp-content/upgrade 2>/dev/null || true
+chown -R www-data:www-data /var/www/html/wp-content/uploads /var/www/html/wp-content/upgrade 2>/dev/null || true
+chmod -R 775 /var/www/html/wp-content/uploads /var/www/html/wp-content/upgrade 2>/dev/null || true
+echo "✅ Permisos de WordPress configurados"
 
 # Configurar opciones de desarrollo
 echo "⚙️  Configurando opciones de desarrollo..."
-wp option update blog_public 0 --allow-root --path=/var/www/html  # No indexar por motores de búsqueda
-wp option update users_can_register 1 --allow-root --path=/var/www/html  # Permitir registro de usuarios
+wp option update blog_public 0 --allow-root --path=/var/www/html --quiet 2>/dev/null
+wp option update users_can_register 1 --allow-root --path=/var/www/html --quiet 2>/dev/null
+echo "✅ Opciones de desarrollo configuradas"
 
 # Crear contenido de ejemplo
 echo "📝 Creando contenido de ejemplo..."
-wp post create --post_type=page --post_title="Página de Prueba Antonella" --post_content="Esta es una página de prueba para el framework Antonella." --post_status=publish --allow-root --path=/var/www/html
-
-wp post create --post_title="Post de Prueba Antonella" --post_content="Este es un post de prueba para demostrar las funcionalidades del framework Antonella." --post_status=publish --allow-root --path=/var/www/html
+wp post create --post_type=page --post_title="Página de Prueba Antonella" --post_content="Esta es una página de prueba para el framework Antonella." --post_status=publish --allow-root --path=/var/www/html --quiet 2>/dev/null || true
+wp post create --post_title="Post de Prueba Antonella" --post_content="Este es un post de prueba para demostrar las funcionalidades del framework Antonella." --post_status=publish --allow-root --path=/var/www/html --quiet 2>/dev/null || true
+echo "✅ Contenido de ejemplo creado"
 
 echo "🎉 ¡Configuración completada!"
 echo "📍 Accede a tu sitio en: http://localhost:8080"
diff --git a/readme.md b/readme.md
index ab06562..1d08259 100644
--- a/readme.md
+++ b/readme.md
@@ -34,11 +34,20 @@
 ---
 
 ## 📋 Requirements
+
+### **Core Requirements**
 - **PHP**: 8.0 or higher
 - **Composer**: Latest version
 - **Git**: For version control
 - **WordPress**: 5.0 or higher
 
+### **Docker Development Environment**
+- **Docker Desktop**: 4.53.0+ (⚠️ **Required for ARM64/Windows compatibility**)
+- **Docker Compose**: v2.0+ 
+- **Available Ports**: 8080 (WordPress), 3306 (MySQL), 9000 (phpMyAdmin)
+
+> **💡 Note**: For optimal ARM64 compatibility on Windows/Mac, ensure Docker Desktop is updated to version 4.53.0 or higher. Earlier versions may experience container startup issues.
+
 ---
 
 ## 🚀 Quick Installation
@@ -66,8 +75,38 @@ php antonella updateproject
 ```
 
 ### 3. Start Development
+
+#### **Option A: Traditional WordPress Development**
 Your plugin is now ready! Upload to WordPress and start developing.
 
+#### **Option B: Docker Development Environment**
+For a complete development setup with database and admin interface:
+
+```bash
+# Start the development environment
+php antonella serve
+# or manually with Docker Compose
+docker compose up -d
+
+# Access your development site
+# WordPress: http://localhost:8080
+# Admin Panel: http://localhost:8080/wp-admin (test/test)
+# phpMyAdmin: http://localhost:9000
+```
+
+**🐳 Docker Environment Includes:**
+- WordPress with automatic framework activation
+- MySQL 8.0 with persistent data
+- phpMyAdmin for database management
+- WP-CLI for command automation
+- Development plugins (Query Monitor, Debug Bar)
+
+**📋 Default Credentials:**
+- **WordPress Admin**: `test` / `test`
+- **MySQL**: `wordpress` / `wordpress`
+
+> **🔧 Troubleshooting**: If containers fail to start, ensure Docker Desktop is updated to 4.53.0+ and required ports (8080, 3306, 9000) are available.
+
 ---
 
 ## 🎯 Core Features