# Conectar un proyecto a Estiaje (guía para tu IA)

Esta guía es para una IA (Claude, ChatGPT, Cursor, Copilot, Codex…) abierta
en el repositorio de alguien que quiere usar Estiaje. Síguela en orden.
Contesta en el idioma de la persona.

Estiaje vigila que los procesos de un negocio terminen (un pedido pagado que
se surte, un pago que se confirma, un mensaje que se contesta) y agrupa los
errores de la app con su stack. Si algo no termina a tiempo, avisa al
teléfono con el dinero en riesgo. Más contexto: https://estiaje.mx/llms.txt

## Si tienes el conector de Estiaje

Si ves las herramientas de Estiaje (`conectar_repositorio`, `errores`,
`declarar_proceso`…), úsalas: `conectar_repositorio` te da la receta y el
comando, y después puedes verificar con `ultimos_eventos`. El conector se
pone en https://estiaje.mx/mcp. Si no lo tienes, sigue esta guía.

## Reglas

1. **La llave nunca pasa por la conversación.** No la leas, no la muestres,
   no la escribas en el código ni la copies a otro archivo. La escribe
   `npx @estiaje/sdk conectar` en `.env` y el código la lee de ahí
   (`ESTIAJE_TOKEN`).
2. **Nada frena la app.** El SDK nunca lanza ni bloquea. Si emites por HTTP
   en otro lenguaje, hazlo sin esperar la respuesta y atrapa cualquier error.
3. **Primero mira, luego pregunta.** Lo que se deduce del código no se
   pregunta: se propone y se confirma. Una pregunta a la vez.
4. **Lo mínimo.** El SDK al arrancar, capturar errores, y el inicio y el
   final del proceso que elija la persona. Nada de timers ni plazos en el
   código: la vigilancia se declara en Estiaje.

## Paso 1 · Mira el repositorio

- El lenguaje y el framework (package.json, requirements.txt, composer.json,
  pom.xml, go.mod, Gemfile, *.csproj).
- Dónde corre (Vercel, AWS Lambda, Docker, un servidor) y dónde viven sus
  variables de entorno.
- Si ya usa Estiaje: busca `@estiaje/sdk`, `estiajeFromEnv`, `ESTIAJE_TOKEN`.
- Dos o tres procesos del negocio candidatos: dónde empieza cada uno (por
  ejemplo `crearPedido`), dónde termina bien (el webhook del pago) y mal
  (`pago rechazado`), y el identificador que los une (el id del pedido).

## Paso 2 · Pregunta

1. Cómo se llama este servicio. Propón el nombre del paquete en
   minúsculas con guiones (`tienda-api`).
2. A qué proyecto de Estiaje va. Si no tiene, se crea al confirmar.
3. Qué proceso quiere vigilar primero, en sus palabras: «todo pedido pagado
   se surte en 30 minutos». Propón los que encontraste.

## Paso 3 · La llave

Corre en la carpeta del repositorio (necesita Node 18 o más):

```bash
npx @estiaje/sdk conectar --proyecto "<proyecto>" --servicio <servicio>
```

Abre el navegador; la persona revisa que el código coincida y da
«Conectar». El comando escribe `ESTIAJE_TOKEN` en `.env`, agrega `.env` a
`.gitignore` y comprueba que llegue un evento de prueba. Si la máquina no
tiene navegador, imprime la dirección y el código para abrirlos en otro
lado.

Sin Node: la persona crea la llave en https://estiaje.mx/app/cuenta.html
(Organizaciones y llaves) y la pone en `.env` como `ESTIAJE_TOKEN`.

## Paso 4 · El código

La receta de su lenguaje: https://estiaje.mx/docs#tu-stack

- Node.js: https://estiaje.mx/docs#receta-node (el SDK `@estiaje/sdk`)
- Python, Ruby, PHP, Java, C#, Go: `https://estiaje.mx/docs#receta-<lenguaje>`
  (por HTTP, `POST https://estiaje.mx/v1/events`)
- Un sitio web: https://estiaje.mx/docs#receta-navegador
- React Native o Expo: https://estiaje.mx/docs#receta-app
- Sin servidor (Lambda, Vercel): https://estiaje.mx/docs#receta-serverless

En Node, lo mínimo:

```ts
import { estiajeFromEnv } from '@estiaje/sdk';
const estiaje = estiajeFromEnv({ service: 'tienda-api' });
estiaje.capturarErrores();

// donde empieza el proceso
estiaje.event('pedido.creado', { order_id: pedido.id, monto: pedido.total });
// donde termina bien
estiaje.outcome('pedido.pagado', { order_id: pedido.id });
```

El identificador que une el inicio y el final va igual en los dos eventos
(`order_id` en el ejemplo, o `entity`). Si el proceso tiene un valor en
dinero, mándalo en el evento que abre (`monto`).

## Paso 5 · Vigilar el proceso

Con el conector: `declarar_proceso`. Sin él, la persona lo declara en el
panel (Procesos → «declarar una expectativa») con: el evento que abre, los
que cierran, el identificador, el plazo y, si lo hay, el atributo con lo
que vale.

## Paso 6 · Comprobar

Que la app mande un evento real y que aparezca en
https://estiaje.mx/app/#/explorar (o con la herramienta `ultimos_eventos`).
Dile a la persona qué quedó: el servicio, el proceso vigilado y dónde verlo.

## Si algo falla

- 401 al mandar eventos: la llave no es la de este proyecto o se revocó.
  Vuelve a correr `npx @estiaje/sdk conectar`.
- No llega nada: revisa que la app lea `.env` (dotenv o la configuración
  del despliegue) y que `ESTIAJE_TOKEN` exista también donde corre en
  producción.
- Documentación completa: https://estiaje.mx/docs