docs: add comprehensive code comments, update README and TASKS, create training and troubleshooting guides

- Add JSDoc comments to API routes and business logic functions
- Update README.md with Phase 2 status and deployment/production notes
- Enhance TASKS.md with estimated timelines and dependencies
- Create docs/STAFF_TRAINING.md for team onboarding
- Create docs/CLIENT_ONBOARDING.md for customer experience
- Create docs/OPERATIONAL_PROCEDURES.md for daily operations
- Create docs/TROUBLESHOOTING.md for common setup issues
- Fix TypeScript errors in hq/page.tsx

docs/CLIENT_ONBOARDING.md

@@ -0,0 +1,152 @@
+# Guía de Onboarding para Clientes — SalonOS
+
+Bienvenido a Anchor23. Esta guía te ayudará a familiarizarte con nuestros sistemas de reserva y servicios.
+
+## Primeros Pasos
+
+### Registro Inicial
+1. Visita `anchor23.mx` para conocer nuestros servicios
+2. Elige membresía según tus necesidades:
+   - **Free**: Acceso básico, invitaciones requeridas
+   - **Gold**: Beneficios premium, descuentos en servicios
+   - **Black**: Servicios prioritarios, acceso VIP
+   - **VIP**: Experiencia exclusiva, concierge personal
+
+### Reserva de Primera Cita
+1. Ir a `booking.anchor23.mx`
+2. Seleccionar servicio deseado
+3. Elegir fecha y hora disponible
+4. Completar información personal
+5. Realizar depósito (50% o $200 máximo)
+
+## Uso de The Boutique (Sistema de Reservas)
+
+### Navegación
+- **Servicios**: Explora catálogo completo
+- **Mi Perfil**: Gestiona información personal
+- **Mis Citas**: Historial y gestión de reservas
+- **Membresías**: Actualiza o mejora tu tier
+
+### Hacer una Reserva
+1. Seleccionar servicio y duración
+2. Elegir location preferida
+3. Ver slots disponibles en calendario
+4. Confirmar datos personales
+5. Pagar depósito requerido
+
+### Modificar Reserva
+- Cambios permitidos hasta 12h antes
+- Penalización por no-show: retención de depósito
+- Contactar staff para cambios especiales
+
+## Sistema de Invitaciones
+
+### Cómo Funciona
+- Sistema de crecimiento controlado
+- Invitaciones semanales por tier
+- Código único por invitado
+- Seguimiento de referrals
+
+### Enviar Invitación
+1. Acceder a sección de invitaciones
+2. Generar código único
+3. Compartir con potencial cliente
+4. Recibir beneficios por conversiones
+
+## Membresías y Beneficios
+
+### Tiers Disponibles
+- **Free**: 1 invitación/semana, servicios estándar
+- **Gold**: 3 invitaciones/semana, 10% descuento
+- **Black**: 5 invitaciones/semana, prioridad en agenda, 20% descuento
+- **VIP**: Invitaciones ilimitadas, concierge, descuentos exclusivos
+
+### Upgrade de Membresía
+- Basado en gasto acumulado
+- Beneficios inmediatos al ascender
+- Renovación automática anual
+
+## Pagos y Depósitos
+
+### Método de Pago
+- Stripe integration segura
+- Tarjetas de crédito/débito
+- Depósito requerido para confirmar
+
+### Política de Depósitos
+- 50% del valor del servicio
+- Máximo $200 por reserva
+- Reembolsable según política de cancelación
+
+## Comunicación y Notificaciones
+
+### Canales
+- Email para confirmaciones
+- WhatsApp para recordatorios (próximamente)
+- SMS para urgencias
+
+### Recordatorios Automáticos
+- 24h antes de cita
+- 2h antes de cita
+- Confirmación de llegada vía kiosko
+
+## Uso del Kiosko
+
+### Llegada al Salón
+1. Acercarse a pantalla táctil en entrada
+2. Ingresar código de 6 dígitos (short ID)
+3. Confirmar llegada
+4. Recibir instrucciones de staff
+
+### Reservas Walk-in
+- Disponible para servicios express
+- Pago en efectivo o tarjeta en recepción
+- Asignación automática de staff y recursos
+
+## Políticas Importantes
+
+### Cancelación
+- Hasta 12h antes: reembolso completo
+- Menos de 12h: retención de depósito
+- No-show: penalización completa
+
+### Puntuación y Privacidad
+- Datos protegidos por RLS
+- Acceso limitado por rol
+- Auditoría completa de cambios
+
+## Soporte al Cliente
+
+### Contacto
+- **Email**: hello@anchor23.mx
+- **Teléfono**: [Número de contacto]
+- **WhatsApp**: [Número de WhatsApp]
+- **Horarios**: Lunes-Domingo, 9AM-8PM
+
+### Problemas Comunes
+- Reserva no aparece: verificar email de confirmación
+- Cambio de horario: contactar 24h antes
+- Problemas técnicos: soporte disponible 24/7
+
+## Consejos para Mejor Experiencia
+
+### Planificación
+- Reservar con anticipación para servicios populares
+- Considerar tiempos de viaje al salón
+- Traer identificación para primera visita
+
+### Preparación
+- Confirmar detalles 24h antes
+- Llegar 15 minutos temprano
+- Comunicar alergias o necesidades especiales
+
+### Post-Servicio
+- Feedback valorado para mejorar
+- Invitar amigos para beneficios adicionales
+- Mantener membresía activa
+
+---
+
+¡Gracias por elegir Anchor23! Tu satisfacción es nuestra prioridad.
+
+*Última actualización: Enero 2026*

docs/OPERATIONAL_PROCEDURES.md

@@ -0,0 +1,174 @@
+# Procedimientos Operativos — SalonOS
+
+Guía interna para operaciones diarias del salón usando el sistema SalonOS.
+
+## Apertura Diaria
+
+### Checklist Matutino
+- [ ] Verificar conexión a internet y sistemas
+- [ ] Revisar bookings del día en Aperture dashboard
+- [ ] Confirmar staff asignado y horarios
+- [ ] Verificar disponibilidad de recursos (estaciones, equipos)
+- [ ] Probar kioskos táctiles
+- [ ] Revisar inventario crítico
+
+### Monitoreo Continuo
+- Monitorear ocupación en tiempo real
+- Gestionar walk-ins según disponibilidad
+- Resolver conflictos de asignación inmediatamente
+
+## Gestión de Reservas
+
+### Flujo Estándar
+1. **Recepción**: Cliente confirmado vía kiosko o staff
+2. **Asignación**: Staff y recurso asignados automáticamente
+3. **Servicio**: Tracking de tiempo y progreso
+4. **Pago**: Procesamiento final si no pagado
+5. **Cierre**: Actualización de status y notas
+
+### Casos Especiales
+- **Sobreasignación**: Reasignar recursos premium
+- **Cancelación última hora**: Liberar slot, notificar siguiente cliente
+- **No-show**: Marcar automáticamente, aplicar penalización
+
+## Manejo de Recursos
+
+### Tipos de Recursos
+- **Stations**: Puestos de trabajo fijos
+- **Rooms**: Salas privadas para servicios premium
+- **Equipment**: Herramientas móviles (secadores, etc.)
+
+### Mantenimiento
+- Limpieza entre clientes
+- Reporte de equipos dañados
+- Programación de mantenimiento preventivo
+
+### Optimización
+- Maximizar uso de recursos premium
+- Balancear carga entre locations
+- Anticipar demanda por temporada
+
+## Gestión de Personal
+
+### Asignación Diaria
+- Revisar schedule semanal
+- Ajustar por ausencias o sobrecarga
+- Comunicar cambios inmediatamente
+
+### Rendimiento
+- Tracking de bookings completados
+- Medición de tiempo por servicio
+- Feedback de clientes por staff
+
+### Capacitación
+- Onboarding para nuevo personal
+- Actualizaciones de procedimientos
+- Certificación en uso de sistemas
+
+## Finanzas y Reportes
+
+### Cierre Diario
+- Verificar todos los pagos procesados
+- Generar reporte de ingresos
+- Revisar depósitos pendientes
+
+### Reportes Semanales
+- Utilización de recursos
+- Rendimiento por staff
+- Tendencias de demanda
+- Análisis de no-shows
+
+### Contabilidad
+- Reconciliación con Stripe
+- Seguimiento de depósitos retenidos
+- Cálculo de comisiones por staff
+
+## Manejo de Clientes VIP
+
+### Protocolo Especial
+- Confirmación personal por manager
+- Asignación de mejores recursos
+- Comunicación premium (WhatsApp, email personalizado)
+- The Vault para fotos privadas
+
+### Seguimiento
+- Historial detallado de preferencias
+- Notas privadas de staff
+- Programa de lealtad personalizado
+
+## Seguridad y Privacidad
+
+### Protección de Datos
+- RLS aplicado estrictamente
+- Acceso limitado por rol
+- Auditoría completa de cambios
+
+### Seguridad Física
+- Control de acceso a sistemas
+- Monitoreo de kioskos
+- Backup de datos crítico
+
+## Contingencias
+
+### Sistema Caído
+1. Comunicación inmediata a todos los staff
+2. Uso de backup manual (libreta, teléfono)
+3. Priorizar clientes VIP y bookings confirmados
+4. Notificar a soporte técnico
+
+### Sobrecarga de Agenda
+1. Evaluar capacidad real vs bookings
+2. Contactar clientes para reagendar
+3. Activar protocolo de espera
+4. Documentar para análisis posterior
+
+### Conflicto con Cliente
+1. Mantener calma y profesionalismo
+2. Escalar a manager si necesario
+3. Documentar incidente completo
+4. Aplicar compensación según política
+
+## Mejores Prácticas
+
+### Eficiencia
+- Minimizar tiempo entre servicios
+- Optimizar rutas de recursos
+- Automatizar tareas repetitivas
+
+### Calidad
+- Verificación de preparación de staff
+- Feedback continuo de clientes
+- Mantenimiento de estándares de servicio
+
+### Innovación
+- Probar nuevas funcionalidades del sistema
+- Recopilar feedback de staff y clientes
+- Implementar mejoras operativas
+
+## Métricas Clave
+
+### KPIs Diarios
+- Ocupación de recursos: >85%
+- Tasa de no-show: <5%
+- Satisfacción cliente: >4.8/5
+
+### KPIs Semanales
+- Ingresos vs presupuesto
+- Utilización por staff
+- Conversion de walk-ins
+
+### KPIs Mensuales
+- Retención de clientes
+- Crecimiento de membresías
+- ROI de inversiones
+
+## Contactos de Emergencia
+
+- **Soporte Técnico**: soporte@anchor23.mx | +52 [tel]
+- **Manager General**: [Nombre] | [tel]
+- **Contabilidad**: [Nombre] | [tel]
+- **Legal**: [Nombre] | [tel]
+
+---
+
+*Revisar y actualizar mensualmente. Última actualización: Enero 2026*

docs/STAFF_TRAINING.md

@@ -0,0 +1,147 @@
+# Guía de Entrenamiento para Staff — SalonOS
+
+Esta guía está diseñada para capacitar al personal del salón en el uso del sistema SalonOS.
+
+## Introducción al Sistema
+
+SalonOS es una plataforma integral de gestión que incluye:
+- Sistema de reservas (The Boutique)
+- Dashboard administrativo (Aperture)
+- Sistema de kiosko para autoservicio
+- Integraciones con pagos y calendario
+
+## Roles y Permisos
+
+### Tipos de Usuario
+- **Admin**: Acceso completo a configuración y gestión
+- **Manager**: Gestión de staff, recursos y reportes
+- **Staff/Artist**: Acceso limitado a sus horarios y asignaciones
+
+### Políticas de Seguridad
+- Nunca compartir credenciales
+- Usar autenticación de dos factores cuando disponible
+- Reportar cualquier acceso sospechoso
+
+## Uso Diario del Sistema
+
+### Acceso al Dashboard (Aperture)
+
+1. Ir a `aperture.anchor23.mx`
+2. Iniciar sesión con credenciales asignadas
+3. Navegar por las pestañas: Dashboard, Staff, Resources, Reports
+
+### Gestión de Horarios
+
+#### Ver Disponibilidad
+- Usar calendario para ver bookings asignados
+- Filtrar por fecha y staff member
+- Colores indican status: confirmado (verde), pendiente (amarillo), cancelado (rojo)
+
+#### Agregar Bloqueos
+- Click derecho en slot vacío
+- Seleccionar "Bloquear tiempo"
+- Elegir motivo: descanso, capacitación, mantenimiento
+
+### Gestión de Clientes
+
+#### Buscar Cliente
+- Usar search por nombre, email o teléfono
+- Ver historial completo de visitas
+- Acceder a notas privadas del cliente
+
+#### Modificar Reserva
+- Buscar booking por short ID o cliente
+- Cambiar horario si hay disponibilidad
+- Notificar cambios al cliente automáticamente
+
+## Sistema de Kiosko
+
+### Configuración Inicial
+- Cada kiosko tiene API key única
+- Configurar en pantalla táctil con enrollment code
+- Probar conexión antes de uso público
+
+### Monitoreo de Actividad
+- Revisar logs de kiosk en admin dashboard
+- Verificar reservas walk-in creadas correctamente
+- Monitorear uso de recursos en tiempo real
+
+## Manejo de Pagos y Depósitos
+
+### Depósitos Dinámicos
+- Automático: 50% del servicio o $200 máximo
+- Verificar pago antes de confirmar servicio
+- Manejar reembolsos según política
+
+### Penalizaciones por No-Show
+- Sistema automático marca después de ventana de 12h
+- Retención de depósito según reglas
+- Comunicación automática al cliente
+
+## Reportes y Analytics
+
+### Reportes Diarios
+- Ingresos por día/servicio
+- Utilización de recursos
+- No-shows y cancelaciones
+
+### Métricas de Rendimiento
+- Por staff member: bookings completados, ingresos generados
+- Por servicio: popularidad, tiempo promedio
+- Por location: ocupación, rentabilidad
+
+## Procedimientos de Emergencia
+
+### Sistema Caído
+- Contactar soporte técnico inmediatamente
+- Usar backup manual para reservas críticas
+- Comunicar a clientes vía teléfono/email
+
+### Reserva Duplicada
+- Verificar con cliente antes de cancelar
+- Mantener la más reciente
+- Documentar en notas del cliente
+
+### Conflicto de Recursos
+- Revisar asignaciones automáticamente
+- Reasignar manualmente si necesario
+- Notificar a staff afectado
+
+## Mejores Prácticas
+
+### Comunicación con Clientes
+- Confirmar cambios inmediatamente
+- Ofrecer alternativas cuando no hay disponibilidad
+- Mantener tono profesional y empático
+
+### Mantenimiento de Datos
+- Actualizar información de contacto regularmente
+- Limpiar bookings cancelados mensualmente
+- Backup semanal de datos críticos
+
+### Optimización de Agenda
+- Maximizar ocupación de recursos premium
+- Balancear carga entre staff members
+- Anticipar demanda por día de la semana
+
+## Capacitación Continua
+
+### Actualizaciones del Sistema
+- Revisar changelog mensual
+- Participar en sesiones de training
+- Reportar bugs o sugerencias
+
+### Certificación
+- Completar módulo básico de onboarding
+- Recertificación anual requerida
+- Bonos por perfect attendance
+
+## Contacto y Soporte
+
+- **Soporte Técnico**: soporte@anchor23.mx
+- **Manager de Location**: [Nombre del manager]
+- **Documentación**: docs/ en repositorio
+
+---
+
+*Última actualización: Enero 2026*

docs/TROUBLESHOOTING.md

@@ -0,0 +1,173 @@
+# Guía de Troubleshooting — SalonOS
+
+Esta guía ayuda a resolver problemas comunes durante el setup y desarrollo de SalonOS.
+
+## Configuración de Entorno
+
+### Supabase Auth Issues
+
+#### Error: "Auth session not found"
+- **Causa**: Variables de entorno de Supabase mal configuradas
+- **Solución**:
+  - Verificar `NEXT_PUBLIC_SUPABASE_URL` y `NEXT_PUBLIC_SUPABASE_ANON_KEY`
+  - Asegurarse que las URLs no tengan trailing slash
+  - Probar conexión: `curl https://your-project.supabase.co/rest/v1/`
+
+#### Error: "RLS policy violation"
+- **Causa**: Políticas de Row Level Security no aplicadas
+- **Solución**:
+  - Ejecutar migraciones: `supabase db push`
+  - Verificar políticas en Supabase Dashboard > Authentication > Policies
+  - Para kioskos: asegurar API key válida en headers `x-kiosk-api-key`
+
+#### Error: "Magic link not received"
+- **Causa**: SMTP no configurado en Supabase
+- **Solución**:
+  - Configurar SMTP en Supabase Dashboard > Authentication > Email Templates
+  - Usar servicio como SendGrid o AWS SES
+  - Probar con email de prueba en dashboard
+
+## Integraciones Externas
+
+### Stripe Webhooks
+
+#### Error: "Webhook signature verification failed"
+- **Causa**: Webhook secret mal configurado
+- **Solución**:
+  - Obtener secret desde Stripe Dashboard > Developers > Webhooks
+  - Configurar `STRIPE_WEBHOOK_SECRET` en variables de entorno
+  - Verificar endpoint URL en Stripe coincida con producción
+
+#### Error: "Payment intent not found"
+- **Causa**: Cliente secret expirado o inválido
+- **Solución**:
+  - Regenerar payment intent en backend
+  - Verificar tiempo de expiración (24h por defecto)
+  - Usar idempotency key para evitar duplicados
+
+#### Error: "Deposit calculation incorrect"
+- **Causa**: Lógica de depósito no actualizada
+- **Solución**:
+  - Verificar regla: MIN(service_price * 0.5, 200)
+  - Probar con diferentes precios de servicio
+  - Revisar logs de webhook para valores
+
+### Google Calendar
+
+#### Error: "Service account authentication failed"
+- **Causa**: Credenciales de Google incorrectas
+- **Solución**:
+  - Descargar JSON de service account desde Google Cloud Console
+  - Configurar `GOOGLE_SERVICE_ACCOUNT_JSON` como string JSON
+  - Verificar permisos: Calendar API enabled, service account tiene acceso al calendar
+
+#### Error: "Calendar sync conflicts"
+- **Causa**: Eventos duplicados o sobrepuestos
+- **Solución**:
+  - Implementar lógica de merge para conflictos
+  - Usar event ID como key para evitar duplicados
+  - Loggear conflictos para resolución manual
+
+## Base de Datos
+
+### Migraciones
+
+#### Error: "Migration failed"
+- **Causa**: Dependencias de migración no resueltas
+- **Solución**:
+  - Ejecutar en orden: `supabase migration up`
+  - Verificar foreign keys existen antes de crear constraints
+  - Backup antes de migrar en producción
+
+#### Error: "Duplicate key value violates unique constraint"
+- **Causa**: Datos existentes violan nueva constraint
+- **Solución**:
+  - Limpiar datos conflictivos antes de migrar
+  - Usar `ON CONFLICT` en inserts
+  - Revisar seeds data
+
+### RPC Functions
+
+#### Error: "Function does not exist"
+- **Causa**: Función no creada en Supabase
+- **Solución**:
+  - Ejecutar SQL de funciones desde migrations
+  - Verificar nombre exacto de función
+  - Probar directamente en Supabase SQL Editor
+
+## Frontend Issues
+
+### Next.js Build
+
+#### Error: "Module not found"
+- **Causa**: Dependencias faltantes
+- **Solución**:
+  - Ejecutar `npm install` o `yarn install`
+  - Verificar package.json versiones compatibles
+  - Limpiar node_modules: `rm -rf node_modules && npm install`
+
+#### Error: "TypeScript errors"
+- **Causa**: Tipos desactualizados
+- **Solución**:
+  - Regenerar types: `supabase gen types typescript --local > lib/db/types.ts`
+  - Verificar imports correctos
+  - Usar `any` temporalmente para debugging
+
+## Kiosko System
+
+#### Error: "Kiosk not authorized"
+- **Causa**: API key inválida o expirada
+- **Solución**:
+  - Generar nueva API key en admin dashboard
+  - Configurar en variables de entorno del kiosko
+  - Verificar headers: `x-kiosk-api-key`
+
+#### Error: "No resources available"
+- **Causa**: Recursos no asignados o bloqueados
+- **Solución**:
+  - Verificar migración de recursos ejecutada
+  - Chequear disponibilidad por horario
+  - Revisar lógica de priority assignment
+
+## Deployment
+
+### Vercel Issues
+
+#### Error: "Build failed"
+- **Causa**: Variables de entorno faltantes
+- **Solución**:
+  - Configurar todas las env vars en Vercel dashboard
+  - Verificar build logs para errores específicos
+  - Usar `--verbose` en build command
+
+#### Error: "Domain configuration failed"
+- **Causa**: Wildcard domains no soportados
+- **Solución**:
+  - Configurar subdominios individuales
+  - Usar proxy reverso para wildcard routing
+  - Verificar DNS settings
+
+## Logs y Debugging
+
+### Verificar Logs
+- **Supabase**: Dashboard > Logs > API/PostgreSQL
+- **Vercel**: Dashboard > Functions > Logs
+- **Stripe**: Dashboard > Developers > Logs
+- **Local**: `npm run dev` con console.log
+
+### Common Debug Steps
+1. Verificar variables de entorno
+2. Probar endpoints con curl/Postman
+3. Revisar network tab en browser dev tools
+4. Chequear logs de errores
+5. Verificar permisos y políticas
+
+## Contacto
+
+Si el problema persiste, documentar:
+- Pasos para reproducir
+- Logs de error completos
+- Configuración del entorno
+- Versiones de dependencias
+
+Crear issue en GitHub con esta información.