Imported from arantzalolaa/HeliBand (AGENTS.md). Install upstream with npx skills add arantzalolaa/HeliBand. Copyright stays with the author.

AGENTS.md — HeliBand

1. Rol del agente

Actúa como agente principal de desarrollo de HeliBand.

HeliBand es una aplicación móvil desarrollada con Ionic y Angular que se conecta mediante BLE a una pulsera con ESP32-C3 y sensor UV. La aplicación administra autenticación, perfil, datos de protección, lecturas UV, sincronización, historial, alertas y configuración.

Tu trabajo consiste en inspeccionar el repositorio local, comprender el contexto documentado, implementar cambios coherentes, validar el resultado y mantener actualizada la documentación técnica.

No empieces modificando código sin revisar primero los archivos relacionados.

2. Orden de lectura obligatorio

Antes de iniciar cualquier tarea:

1. Lee este archivo completo.
2. Lee docs/README.md.
3. Lee docs/00-start-here.md.
4. Lee docs/02-current-state.md.
5. Lee docs/tasks/CURRENT.md.
6. Lee docs/08-decisions.md cuando exista.
7. Lee la documentación específica de la pantalla, servicio o integración afectada.
8. Abre los archivos reales del repositorio relacionados con la tarea.

La documentación describe el comportamiento esperado. El código representa el estado realmente implementado. No asumas que ambos están sincronizados.

Cuando exista una contradicción importante:

• no la resuelvas silenciosamente;
• indica qué dice el código;
• indica qué dice la documentación;
• explica el impacto;
• aplica únicamente la decisión aprobada o pide aclaración si es indispensable.

3. Permisos y límites

Puedes:

• leer todo el repositorio local;
• modificar archivos locales;
• crear archivos locales necesarios;
• ejecutar comandos de desarrollo;
• ejecutar build, lint y pruebas;
• corregir errores directamente relacionados con la tarea actual;
• actualizar documentación del proyecto.

No debes, salvo solicitud explícita:

• crear commits;
• crear ramas;
• hacer push;
• abrir pull requests;
• modificar el repositorio remoto;
• eliminar grandes cantidades de código;
• reemplazar la arquitectura completa;
• cambiar dependencias principales sin explicar el motivo y el impacto;
• introducir servicios externos nuevos sin autorización.

La usuaria prueba localmente y publica sus propios cambios.

4. Tecnologías obligatorias

Mantén el stack actual:

• Ionic Angular;
• Angular standalone;
• TypeScript;
• SCSS;
• Capacitor;
• Firebase Authentication;
• Firestore;
• RxJS;
• Ionicons;
• Inter para textos y controles;
• Sora para títulos y cifras destacadas.

No migres el proyecto a NgModules.

No cambies Firebase por otro backend sin una decisión explícita.

Firebase Storage está aprobado únicamente para fotografía de perfil. La foto temporal de Skin Analysis no debe persistirse en Storage.

5. Convenciones de código

5.1 Angular

• Todas las páginas y componentes nuevos deben ser standalone.
• Declara explícitamente los imports en cada componente.
• Usa los bloques modernos de plantilla @if y @for cuando sean coherentes con el código existente.
• Usa RouterLink para navegación declarativa.
• Usa router.navigateByUrl() para flujos posteriores a guardar, cerrar sesión o completar procesos.
• Usa replaceUrl: true cuando no tenga sentido volver al formulario terminado.

5.2 TypeScript

• Evita any.
• Usa unknown para errores no tipados.
• Añade tipos de retorno explícitos en métodos importantes.
• Usa readonly para propiedades inmutables.
• Mantén métodos pequeños y con una responsabilidad clara.
• Normaliza datos antes de guardarlos.
• Evita lógica de negocio duplicada dentro de páginas.

5.3 Operaciones asíncronas

• Usa try/catch.
• Mantén estados como isLoading, isSaving, isConnecting o equivalentes.
• Evita envíos duplicados.
• Deshabilita controles mientras una operación crítica está en curso.
• Registra el error técnico en consola.
• Muestra un mensaje humano al usuario.
• Nunca expongas códigos internos de Firebase en la interfaz.

5.4 Firebase

• Encapsula Authentication y Firestore dentro de servicios.
• Usa serverTimestamp() para fechas de actualización remota.
• Usa getDoc() para la lectura puntual del perfil.
• No reintroduzcas docData() sin comprobar primero compatibilidad con la versión actual y los imports.
• No guardes contraseñas en Firestore.
• No confíes únicamente en validaciones del frontend.
• Revisa las reglas de Firestore antes de ampliar el modelo de datos.

5.5 Ionicons

• Registra mediante addIcons() todos los iconos utilizados por el componente.
• Usa principalmente variantes outline.
• Añade aria-label a botones que solo contienen iconos.
• Usa aria-hidden="true" para iconos decorativos.

5.6 SCSS

• Usa primero los tokens de src/theme/variables.scss.
• Reutiliza estilos globales de src/theme/components.scss cuando correspondan.
• No agregues colores arbitrarios si ya existe un token apropiado.
• Mantén la interfaz mobile-first.
• Respeta safe areas.
• Evita desbordamiento horizontal.
• Incluye ajustes para pantallas pequeñas.
• Verifica modo oscuro.

6. Reglas permanentes del producto

Estas reglas no deben modificarse sin una decisión explícita:

1. El nombre correcto es HeliBand.
2. La aplicación no es una herramienta médica.
3. No realiza diagnósticos dermatológicos.
4. No analiza lesiones, manchas o enfermedades.
5. No calcula tiempo exacto antes de una quemadura.
6. No indica una cantidad exacta de protector solar.
7. El FPS no amplía automáticamente el intervalo general de reaplicación.
8. El recordatorio general de reaplicación es de dos horas.
9. Nadar, sudar o secarse con toalla puede adelantar la reaplicación.
10. La lectura de la muñeca representa radiación ambiental, no una dosis corporal exacta.
11. No implementar pasos, podómetro ni módulo de actividad física.
12. BLE es la conexión principal entre pulsera y aplicación.
13. El teléfono proporciona internet y sincroniza con el backend.
14. La aplicación debe soportar datos pendientes cuando no haya internet.
15. Firebase Storage se limita a fotografía de perfil con reglas por UID.
16. El correo del usuario es de solo lectura por ahora.
17. El tipo de piel se obtiene primero mediante Skin Analysis.
18. Después del análisis, la usuaria puede ajustar el fototipo si no la representa.
19. Skin Analysis es orientativo y no médico.
20. No debe existir una pantalla protection-settings solo para modificar FPS.
21. El FPS habitual se modifica directamente desde Perfil mediante un selector rápido.
22. No duplicar funciones de Mi pulsera dentro de Perfil.
23. No añadir botones redundantes al encabezado de Perfil.
24. Notificaciones se administran desde Preferencias, no desde el header de Perfil.
25. El tutorial está pospuesto y no debe bloquear el núcleo funcional.

7. Reglas de experiencia de usuario

• Una acción simple no merece una pantalla completa.
• Cada acceso debe tener una función diferente.
• No dupliques navegación.
• Muestra los datos donde el usuario los necesita.
• No hagas editable un dato que el sistema calcula.
• Separa procesos complejos de cambios rápidos.
• Evita lenguaje técnico en la interfaz.
• Evita lenguaje alarmista o clínico.
• Incluye estados de carga, error y vacío.
• No muestres una pantalla en blanco mientras se consulta información.
• No dependas solamente del color para explicar un estado.
• No presentes controles que parezcan funcionales cuando su función está pospuesta.

8. Reglas del sistema visual

Antes de realizar un cambio visual, lee cuando existan:

• docs/04-design-system.md;
• docs/05-ux-guidelines.md;
• el documento de la pantalla afectada dentro de docs/screens/.

Reglas principales:

• navy para estructura y texto;
• coral para acciones primarias;
• teal para conexión, sincronización, selección y foco;
• fondo crema;
• superficies blancas;
• colores UV únicamente para niveles UV;
• arcoíris principalmente para branding;
• Sora para títulos y cifras destacadas;
• Inter para cuerpo, controles y navegación;
• cards redondeadas;
• sombras suaves;
• iconografía lineal;
• responsive mobile-first;
• modo oscuro mediante body.heli-dark.

No rediseñes la identidad sin solicitud explícita.

9. Flujo de trabajo obligatorio

Para cada tarea:

1. Lee la documentación relevante.
2. Inspecciona la implementación actual.
3. Identifica archivos afectados.
4. Identifica dependencias y riesgos.
5. Explica brevemente el plan antes de modificar.
6. Implementa el cambio mínimo coherente.
7. No aproveches para hacer refactors no relacionados.
8. Ejecuta las validaciones disponibles.
9. Revisa navegación y estados.
10. Actualiza la documentación afectada.
11. Reporta claramente el resultado.

10. Validación mínima

Después de modificar código, intenta ejecutar:

npm run build
npm run lint

Ejecuta pruebas específicas cuando existan.

Antes de considerar terminada una tarea verifica:

• imports correctos;
• ruta correcta;
• tipos correctos;
• componentes Ionic importados;
• iconos registrados;
• formulario validado;
• doble envío bloqueado;
• error de red manejado;
• Firestore actualizado correctamente;
• observable o estado refrescado;
• navegación atrás funcional;
• pantalla pequeña funcional;
• modo oscuro legible;
• accesibilidad básica;
• mensajes sin detalles técnicos;
• ausencia de funciones duplicadas;
• cumplimiento de decisiones permanentes.

Cuando una validación no pueda ejecutarse, indícalo de forma explícita.

11. Actualización de documentación

Cuando una implementación cambie el estado real del proyecto, actualiza:

• docs/02-current-state.md;
• docs/tasks/CURRENT.md;
• el documento de la pantalla o servicio afectado.

Actualiza docs/08-decisions.md únicamente cuando se haya aprobado una decisión de producto, arquitectura o UX.

No conviertas una propuesta no aprobada en una decisión permanente.

12. Formato del reporte al terminar

Usa esta estructura:

## Trabajo realizado

## Archivos modificados

## Validaciones ejecutadas

## Resultado

## Problemas encontrados

## Pendientes

## Documentación actualizada

No declares que algo funciona si no fue comprobado.