# GESTURES_GUIDE.md — Guía Completa de Gestos (4GatosCoin)

Este documento define los gestos del ecosistema 4GatosCoin, sus reglas, validaciones, límites, impacto en el organismo y su flujo interno.  
Los gestos son la unidad mínima de acción dentro del organismo y el origen de la mayoría de los procesos internos.

---

# 1. ¿Qué es un Gesto?

Un **gesto** es una acción ritual o técnica ejecutada por un usuario.  
Cada gesto:

- se registra en la base de datos  
- genera puntos  
- alimenta energía  
- actualiza el organismo global  
- genera memoria  
- puede activar rituales  
- puede influir en territorio y ciclos  

Los gestos son el **latido individual** que alimenta el **latido global**.

---

# 2. Tipos de Gestos

Los tipos válidos se definen en:

```
types/Gesture.ts
```

Ejemplos comunes:

- `pulso_vocal`
- `pause`
- `walletConnect`
- `clauseTrigger`
- `dropPlay`
- `reflection`
- `mirror`
- `loop`

Cada gesto tiene:

- propósito  
- impacto  
- reglas  
- límites  

---

# 3. Flujo Interno de un Gesto

```
Usuario
  ↓
POST /api/gesture
  ↓
Validación
  ↓
Registro en Gestures
  ↓
Asignación de puntos
  ↓
Actualización del Organismo Global
  ↓
Registro en Logs
  ↓
Respuesta al cliente
```

---

# 4. Validación de Gestos

Todos los gestos pasan por validación estricta:

### 4.1. Validación de wallet
- `toLowerCase()`
- `trim()`
- formato válido
- no vacío

### 4.2. Validación de tipo
El tipo debe existir en `types/Gesture.ts`.

### 4.3. Límites diarios
Cada wallet tiene un límite configurable.

### 4.4. Límites por tipo
Ejemplo:

- `pulso_vocal`: ilimitado pero con cooldown  
- `pause`: limitado  
- `walletConnect`: solo 1 por sesión  

### 4.5. Frecuencia
Prevención de spam:

- cooldown entre gestos  
- control de repetición  
- control de ráfagas  

---

# 5. Registro del Gesto

Cada gesto se inserta en:

```
models/Gesture.ts
```

Campos típicos:

```json
{
  "wallet": "0x123...",
  "gesture": "pulso_vocal",
  "timestamp": 1700000000,
  "metadata": {}
}
```

---

# 6. Impacto del Gesto

Cada gesto puede afectar:

### 6.1. Puntos
- puntos base  
- multiplicadores  
- bonus por racha  
- bonus por temporada  

### 6.2. Energía
- energía global  
- energía por zona  
- energía por ciclo  

### 6.3. Memoria
- eventos narrativos  
- ecos  
- registros significativos  

### 6.4. Latido
- incremento del heartbeat  
- sincronización global  

### 6.5. Territorio
- expansión  
- dominancia  
- zonas activas  

### 6.6. Ciclos
- avance de ciclo  
- activación de umbrales  

### 6.7. Temporadas
- impacto en reglas  
- activación de eventos  

---

# 7. Reglas por Tipo de Gesto

## 7.1. `pulso_vocal`
El gesto base del organismo.

- genera puntos  
- incrementa energía  
- alimenta el latido  
- registra memoria básica  
- sin límite estricto, pero con cooldown  

## 7.2. `pause`
Gesto de silencio ritual.

- no genera puntos  
- estabiliza energía  
- puede activar memoria silenciosa  
- limitado por día  

## 7.3. `walletConnect`
Gesto técnico.

- se ejecuta al conectar wallet  
- genera puntos iniciales  
- solo 1 por sesión  

## 7.4. `clauseTrigger`
Gesto narrativo.

- activa cláusulas rituales  
- genera memoria profunda  
- puede activar eventos  

## 7.5. `dropPlay`
Gesto de interacción con drops.

- genera puntos  
- puede generar semillas  
- limitado por drop  

## 7.6. `reflection`
Gesto introspectivo.

- genera memoria  
- no genera puntos  
- afecta ciclos  

## 7.7. `mirror`
Gesto de eco invertido.

- refleja actividad  
- genera memoria especial  
- puede activar rituales  

## 7.8. `loop`
Gesto de repetición ritual.

- genera puntos reducidos  
- afecta energía  
- limitado por día  

---

# 8. Límites Globales

### 8.1. Por wallet
- límite diario configurable  
- límite por tipo  

### 8.2. Por tipo de gesto
Cada tipo tiene sus propias reglas.

### 8.3. Por temporada
Las temporadas pueden redefinir:

- puntos  
- límites  
- gestos válidos  

---

# 9. Ejemplo de Petición

```bash
curl -X POST https://tudominio.com/api/gesture \
  -H "Content-Type: application/json" \
  -d '{"wallet":"0x123...", "gesture":"pulso_vocal"}'
```

---

# 10. Ejemplo de Respuesta

```json
{
  "success": true,
  "gestureId": "abc123",
  "pointsAdded": 3,
  "organism": {
    "energia": 1200,
    "heartbeat": 88
  }
}
```

---

# 11. Cómo Añadir un Nuevo Gesto

1. Añadir tipo en:
   ```
   types/Gesture.ts
   ```
2. Añadir validación en:
   ```
   app/api/gesture/route.ts
   ```
3. Añadir reglas en:
   ```
   app/api/points
   ```
4. Añadir UI en:
   ```
   app/devweb3/gestos/
   ```
5. Actualizar documentación si aplica.

---

# 12. Licencia
Proyecto interno.  
Acceso restringido a desarrolladores autorizados.