# Hábitos

URL: https://docs.clatri.com/space/habits/

> Cómo funcionan los hábitos en Clatri: crearlos con frecuencia y días objetivo, registrar completados, el grid de contribución, rachas y cumplimiento.

Un hábito es una práctica que quieres sostener en el tiempo. A diferencia de una tarea (que se completa y desaparece) o de un evento (que tiene una fecha específica), un hábito se registra día a día y lo que importa es la constancia, la racha y la tendencia.

Le dices al agente *"quiero crear un hábito de leer cada día"* y queda creado con la frecuencia que definas.

## Crear un hábito

El agente *Administración y productividad* tiene la tool `create_habit`. Define:

- **Título** — qué quieres hacer ("Meditar", "Correr", "Aprender inglés")
- **Emoji** — ícono visual para el dashboard
- **Descripción** — texto libre, opcional
- **Tipo de actividad** — clasificación (ejercicio, meditación, lectura, idioma, etc.) — afecta el color y las estadísticas agregadas
- **Frecuencia** (`frequency_type`) — tres modos: **diario**, **semanal** o **personalizado**
- **Días objetivo** (`target_days`) — qué días de la semana cuentan, como números del 0 al 6 (0 = domingo, 1 = lunes, …, 6 = sábado). Por defecto los siete. `target_days=[1, 3, 5]` es lunes, miércoles y viernes
- **Veces por período** (`target_times_per_period`) — cuántas veces hay que completarlo en cada período. Por defecto 1
- **Recordatorio** — un push diario opcional, con hora (`08:00`)

La pareja *frecuencia + veces por período* es la que da sentido a todo, y es la parte que más se malinterpreta. "Semanal" por sí solo no significa *una vez por semana*: significa *N veces por semana*, y ese N lo pone `target_times_per_period`.

| Frecuencia | Veces por período | Significa |
|---|---|---|
| `daily` | 1 | Una vez al día |
| `weekly` | 3 | Tres veces por semana |
| `custom` | N | N veces dentro de los días objetivo |

Así, *"quiero ir al gimnasio 3 veces por semana"* es `frequency_type="weekly"` con `target_times_per_period=3` — no un hábito diario que vas a incumplir cuatro días de cada siete.

También puedes crear y configurar hábitos desde la pestaña Hábitos en la UI.

## Registrar completado

El agente tiene `log_habit` para marcar un hábito como cumplido en un día específico. Desde la UI tienes dos caminos:

- **Rápido** — tocas el checkbox del card en el dashboard y queda registrado para hoy
- **Detallado** — abres el diálogo de registro y agregas duración (con selector de horas/minutos) y notas opcionales. Útil si quieres saber no solo si meditaste, sino cuánto tiempo

La **duración** es una propiedad del registro, no del hábito. No defines "45 minutos esperados" al crearlo; anotas los minutos que dedicaste al momento de registrar la sesión (*"hice 45 minutos de ejercicio"*). El hábito responde *si lo hiciste*; el registro responde *cuánto*.

También puedes registrar días pasados tocando la celda correspondiente en el grid de contribución.

## El grid de contribución

La pantalla de detalle de un hábito muestra un **grid estilo GitHub** donde cada celda es un día. El estado es binario — hiciste el hábito o no lo hiciste:

- **Verde** — completaste ese día
- **Neutro** — no lo completaste (o el día aún no llega)

Puedes cambiar la escala entre semana, mes, trimestre y año para ver la tendencia a diferentes resoluciones.

En el chat, el grid que devuelve `read_habit_calendar` distingue además los días que no te tocaban: **■** es un día cumplido, **□** un día objetivo que fallaste, y **·** un día que ni siquiera estaba programado. Fallar un día que no era tuyo no cuenta como fallar.

## Rachas y estadísticas

La tool `read_habit_stats` (y la UI de detalle) muestran:

- **Racha actual** — cuántos días consecutivos llevas cumpliendo
- **Mejor racha** — récord histórico
- **Tasa de cumplimiento** — porcentaje de días objetivo cumplidos en los últimos **30 días** por defecto. La ventana es configurable: puedes pedirle al agente *"¿cómo voy con el gimnasio en los últimos 90 días?"* y la ajusta
- **Total de completados** — todas las veces que has completado el hábito

`read_habit_calendar` devuelve una representación textual del grid — útil cuando le preguntas al chat *"¿cómo va mi hábito de meditación?"*. Su ventana también es configurable: **90 días** por defecto, hasta un máximo de un año.

## Pausa y archivado

Si necesitas pausar un hábito temporalmente — vacaciones, enfermedad, lo que sea — `edit_habit` lo pone en estado `paused`. No se borran las estadísticas ni se rompe la racha acumulada. Cuando lo reactivas (`status=active`), retoma desde donde estaba sin romper el historial.

El estado `archived` lo saca del dashboard sin borrarlo, por si más adelante quieres revisar el histórico.

`delete_habit` es soft-delete: marca un `deleted_at` pero conserva la fila por si la necesitas recuperar.

## Resumen de tools

| Tool | Para qué |
|---|---|
| `read_habits` | Lista hábitos activos/pausados/archivados con su racha actual. |
| `create_habit` | Crea un hábito nuevo con frecuencia, días objetivo, veces por período y tipo. |
| `edit_habit` | Renombra, cambia frecuencia o estado (preserva streaks al pausar). |
| `delete_habit` | Soft-delete. |
| `log_habit` | Marca cumplimiento de un día, con duración y notas opcionales (requiere `habit_id` válido). |
| `read_habit_stats` | Streak actual + mejor + tasa de cumplimiento (30 días por defecto). |
| `read_habit_calendar` | Grid de contribución en texto (90 días por defecto, máximo un año). |