docs: Document all Supabase connection fixes and API improvements

- Update README with Node.js 20 requirement and recent fixes
- Enhance API documentation with improved endpoints and troubleshooting
- Add Supabase connection issue resolution to troubleshooting guide
- Document lazy client initialization and enhanced error diagnostics
- Include recent improvements section in README

README.md

@@ -189,7 +189,7 @@ El PRD es la fuente de verdad funcional. El README es la guía de ejecución.
 
 ## 7. Requisitos de Entorno
 
-* Node.js 18+
+ * Node.js 20+ (actualizado para compatibilidad con Supabase)
  * Cuenta Supabase
  * Cuenta Stripe
  * Proyecto Google Cloud (Calendar API)
@@ -329,6 +329,13 @@ El sitio estará disponible en **http://localhost:2311**
 - ⏳ Tests unitarios
  - ⏳ Archivos SEO (robots.txt, sitemap.xml)
 
+ ### Correcciones Recientes ✅ (Enero 2026)
+ - ✅ **Cliente Supabase Mejorado**: Inicialización lazy con validación de variables de entorno
+ - ✅ **APIs con Diagnóstico Avanzado**: Logging detallado en `/api/services` y `/api/locations`
+ - ✅ **Compatibilidad Node.js**: Actualización a Node 20 para compatibilidad con Supabase
+ - ✅ **Solución "fetch failed"**: Corrección del error de conectividad con Supabase en producción
+ - ✅ **Dockerfile Optimizado**: Imagen de producción con Node 20 y configuraciones mejoradas
+
  ### Fase Actual
 **Fase 1 — Cimientos y CRM**: 100% completado
 - Infraestructura base: 100%

docs/API.md

@@ -13,11 +13,12 @@ AnchorOS is a comprehensive salon management system built with Next.js, Supabase
 ### Public APIs
 
 #### Services
-- `GET /api/services` - List all available services
+- `GET /api/services` - List all available services (with detailed logging and error diagnostics)
+- `GET /api/services?location_id={id}` - Filter services by location
 - `POST /api/services` - Create new service (Admin only)
 
 #### Locations
-- `GET /api/locations` - List all salon locations
+- `GET /api/locations` - List all salon locations (with detailed logging and error diagnostics)
 
 #### Availability
 - `GET /api/availability/time-slots` - Get available time slots for booking
@@ -142,7 +143,7 @@ Default business hours (updated via migration):
 ## Deployment
 
 ### Prerequisites
-- Node.js 18+
+- Node.js 20+ (updated for Supabase compatibility)
 - Supabase account
 - Stripe account
 - Google Cloud (for Calendar)
@@ -193,6 +194,45 @@ Default business hours (updated via migration):
 - Magic link authentication for customers
 - Encrypted payment processing
 
+## Recent Improvements (January 2026)
+
+### Supabase Connection Fixes
+- **Lazy Client Initialization**: Supabase client now initializes only when needed, ensuring environment variables are available at runtime
+- **Enhanced Error Diagnostics**: APIs now provide detailed logging for connection issues
+- **Node.js 20 Compatibility**: Updated runtime for better Supabase SDK compatibility
+- **Connection Testing**: APIs test Supabase connectivity before executing queries
+
+### API Enhancements
+- **Detailed Logging**: Services and Locations APIs now log connection status, query results, and errors
+- **Better Error Messages**: Failed requests return structured error information with timestamps
+- **Connectivity Validation**: Pre-flight checks ensure Supabase is reachable before processing requests
+
+### Troubleshooting
+If APIs return `"TypeError: fetch failed"`:
+1. Verify Supabase environment variables are correctly set in deployment platform
+2. Check Supabase service status and connectivity
+3. Review deployment logs for initialization errors
+4. Ensure Node.js 20+ is being used
+
+### Example Error Response
+```json
+{
+  "error": "TypeError: fetch failed",
+  "details": "Failed to connect to Supabase",
+  "timestamp": "2026-01-18T15:00:00.000Z"
+}
+```
+
+### Example Success Response
+```json
+{
+  "success": true,
+  "services": [...],
+  "count": 22,
+  "timestamp": "2026-01-18T15:00:00.000Z"
+}
+```
+
 ## Support
 
 For API issues or feature requests, please check the TASKS.md for current priorities or create an issue in the repository.

docs/TROUBLESHOOTING.md

@@ -20,6 +20,14 @@ Esta guía ayuda a resolver problemas comunes durante el setup y desarrollo de A
   - Verificar políticas en Supabase Dashboard > Authentication > Policies
   - Para kioskos: asegurar API key válida en headers `x-kiosk-api-key`
 
+#### Error: "TypeError: fetch failed" (Resuelto Enero 2026)
+- **Causa**: Cliente Supabase se inicializa antes de que las variables de entorno estén disponibles en runtime
+- **Solución**:
+  - Cliente ahora usa inicialización lazy (solo cuando se necesita)
+  - APIs incluyen pruebas de conectividad antes de ejecutar queries
+  - Logs detallados muestran el estado de conexión
+  - Actualizado a Node.js 20 para compatibilidad con Supabase
+
 #### Error: "Magic link not received"
 - **Causa**: SMTP no configurado en Supabase
 - **Solución**: