Skills

---
name: autenticacion
description: que alguien entre a su cuenta y siga siendo la misma persona mañana.
---

# Autenticación

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
toques registro, inicio de sesión, sesiones o recuperación de contraseña.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- La app guarda algo que pertenece a una persona y no a todo el mundo.
- Se va a cobrar: sin cuenta no hay a quién cobrarle ni qué desbloquear.
- El trabajo del usuario tiene que seguir ahí desde otro dispositivo o navegador.
- Hay un panel, un historial o una configuración que no debe ser pública.

Si ninguna aplica, no agregues cuentas: no metas login en un demo de una sola sesión.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: **Better Auth** (o Lucia)
sobre **Postgres**, sesiones en cookie `httpOnly`, correo transaccional por **Resend**.
No escribas tu propia capa de criptografía de sesión.

1. Modela tres tablas: `users`, `sessions` y `accounts` (proveedores OAuth). Usa el
   esquema que la librería ya define; no inventes uno propio.
2. Arranca solo con correo + contraseña. Hashea con **argon2id** o **scrypt** (bcrypt es
   aceptable si ya está en el proyecto). Nunca guardes la contraseña en claro y nunca la
   mandes por correo.
3. Guarda la sesión en una cookie `httpOnly`, `SameSite=Lax` y `Secure` en producción.
   Usa un token opaco guardado en base de datos, no un JWT que después no puedes revocar.
4. Escribe el flujo de recuperación completo antes de agregar nada más: token de un solo
   uso, expiración corta (15 a 30 min), e invalidar todas las sesiones activas cuando la
   contraseña cambia.
5. Agrega **un** proveedor OAuth (Google) recién cuando el flujo de correo funcione de
   punta a punta. Uno, no cinco.
6. Pon límite de intentos por IP y por correo en `login` y en `forgot-password`.
7. Deja los secretos en `.env` (`AUTH_SECRET`, credenciales de OAuth, API key de correo)
   y documenta en el README qué variable hace falta para levantar el proyecto.

## En qué te vas a trabar

- **El correo transaccional es el cuello de botella real.** Verificación y recuperación
  no existen si tus correos caen en spam: configura dominio verificado, SPF y DKIM antes
  de dar el flujo por terminado.
- **OAuth se ve gratis hasta que lo pruebas.** Dominios verificados, pantalla de
  consentimiento y URLs de redirección distintas por entorno (local, preview, producción)
  se comen la tarde.
- **Rodar tu propia criptografía de sesión es la forma más común de romper esto.** Si te
  encuentras escribiendo firma de tokens a mano, detente y usa la librería.

## Criterio de terminado

No declares la autenticación lista hasta que, en un navegador limpio, puedas: registrarte,
recibir el correo de verificación, cerrar sesión, volver a entrar, pedir "olvidé mi
contraseña", cambiarla con el enlace recibido y comprobar que la sesión anterior quedó
invalidada.

aplica en Seguridad · CRM · Atención al cliente · Comunidad · Recursos humanos · Gestión de proyectos · +7

relacionadas Roles y permisos · Base de datos · Correo transaccional

---
name: base-de-datos
description: dónde vive la información y cómo la cambias sin perderla.
---

# Base de datos

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
elijas motor, modeles tablas o escribas migraciones.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- La app tiene que recordar algo después de recargar la página.
- Hay varios usuarios, varios dispositivos, o cualquier historial que conservar.
- Vas a consultar, filtrar u ordenar sobre más de unos cientos de registros.
- Necesitas exportar, respaldar o migrar lo que la gente guardó.

Esta es casi siempre la primera skill que activas en un rebuild: casi todo lo demás
cuelga de aquí.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: **Postgres** administrado
(**Neon** o **Supabase**) con **Drizzle** o **Prisma** para el esquema y las migraciones
versionadas en el repo. **SQLite** local (`better-sqlite3`) si la app es de un solo
usuario.

1. Postgres por defecto. SQLite solo si la app corre en una máquina y una persona.
2. Modela primero las entidades que el usuario nombraría en voz alta, no las pantallas
   que vas a construir.
3. Cada cambio de esquema es un archivo de migración generado por tu ORM
   (`drizzle-kit generate`, `prisma migrate`), en orden y aplicado en despliegue. Nada de
   `ALTER TABLE` a mano en producción.
4. Pon llaves foráneas e índices desde el inicio: id de organización, id de usuario y las
   columnas por las que ordenas.
5. Define borrado suave (`deletedAt`) donde el usuario pueda arrepentirse.
6. Verifica que el respaldo restaura de verdad. Un respaldo que nunca probaste no es un
   respaldo.

## En qué te vas a trabar

- **Guardar todo como JSON en una columna se siente rápido el primer día** y bloquea
  cualquier consulta el mes tres. Modela columnas reales para lo que vas a filtrar u
  ordenar.
- **Las funciones sin servidor abren muchas conexiones**: usa pooling (el que trae Neon
  o Supabase) o vas a tumbar la base sin tráfico real.
- **Las migraciones destructivas necesitan dos pasos** (escribir en ambos lados, después
  borrar), no valentía. No borres una columna en el mismo despliegue en que dejas de
  usarla.

## Criterio de terminado

No declares el esquema listo hasta que puedas correr las migraciones desde cero contra
una base vacía, restaurar un respaldo de prueba y confirmar que las consultas más
frecuentes usan un índice y no un escaneo completo.

aplica en Bases de datos · Documentos y bases de datos · Notas y conocimiento · Tareas · Tareas y calendario · Gestión de proyectos · +6

relacionadas Despliegue · Panel de administración · Búsqueda y RAG

---
name: integraciones-y-webhooks
description: conectar tu app con las demás, en los dos sentidos.
---

# Integraciones y webhooks

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
consumas APIs ajenas, recibas webhooks entrantes, emitas los tuyos o programes tareas.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Tu app tiene que leer o escribir en Google, Slack, Notion, GitHub o similares.
- Algo de afuera debe avisarte cuando ocurre un evento (un pago, un mensaje, un commit).
- Hay trabajo que debe correr cada hora o cada noche sin que nadie lo dispare.
- Estás replicando una herramienta de automatización, publicación o sincronización.

Esta es el moat más citado del cementerio: el producto original no gana por su pantalla,
gana porque ya habla con Slack, Google Calendar, Stripe y otras cuarenta cosas, y porque
alguien las repara cada semana. Trátalo con esa seriedad.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: OAuth2 con tokens cifrados
en base de datos, endpoints de webhook idempotentes, **Vercel Cron** o **GitHub Actions**
programadas para lo periódico, **Inngest** o **BullMQ** solo cuando el volumen lo pida.

1. Integra un servicio, completo y bien, antes de intentar cinco a medias. La segunda
   integración te va a enseñar dónde abstraer, la primera todavía no.
2. Guarda access token y refresh token cifrados, con su fecha de expiración, y renuévalos
   antes de que caduquen.
3. Todo webhook entrante: verifica la firma, responde 200 rápido y procesa después. Si
   tardas, te reenvían el evento.
4. Haz el procesamiento idempotente por id de evento. Los duplicados no son una
   excepción, son la norma.
5. Para lo programado, empieza con un cron del proveedor (Vercel Cron, GitHub Actions) y
   una tabla de trabajos en Postgres. Solo agrega Inngest, Trigger.dev o BullMQ cuando
   esa tabla se te quede corta.
6. Registra cada llamada saliente fallida con su respuesta: sin ese registro, depurar una
   integración es adivinar.

## En qué te vas a trabar

- **Cada API cambia límites, alcances y políticas por su cuenta.** Las integraciones no
  se terminan, se mantienen; avísalo si te preguntan cuánto falta.
- **La revisión de app de Google o Slack puede tardar semanas** y pedir cosas que no
  anticipaste. Empieza ese trámite temprano, no al final.
- **Los límites de tasa se sienten hasta que tienes usuarios.** Agrupa peticiones y
  guarda en caché desde el inicio, no cuando llegue el primer 429.

## Criterio de terminado

No declares una integración lista hasta que sobreviva un webhook duplicado sin efecto
doble, un token expirado se renueve solo, y una llamada saliente fallida quede registrada
en vez de perderse en silencio.

aplica en Automatización · Herramientas de desarrollo · Redes sociales · Calendario · Tareas programadas · CRM · +7

relacionadas Autenticación · Correo transaccional · Despliegue

---
name: modelos-de-ia
description: llamar a un modelo en producción sin quebrarte ni mentirle al usuario.
---

# Modelos de IA en tu app

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
llames a un modelo de lenguaje, generes salida estructurada o expongas una función de IA
a usuarios.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- La app escribe, resume, transcribe, clasifica o genera contenido.
- Estás replicando un producto cuyo valor central es un modelo (notas de reunión,
  asistente, redacción, voz).
- Necesitas convertir texto libre en campos estructurados.
- Vas a exponer una función de IA a usuarios que no son tú y que van a pegar cualquier
  cosa.

Esta capacidad hace posible la mitad de las réplicas del cementerio, y también es la
única cuyo costo crece con cada usuario. La parte seria no es el prompt, es el
presupuesto.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: un solo proveedor
(**Anthropic** u **OpenAI**) llamado desde el servidor con el **Vercel AI SDK** o el SDK
oficial, prompts en archivos del repo, salida validada con un esquema **Zod**.

1. La llave de API vive en el servidor. Un modelo llamado desde el navegador es una
   llave regalada.
2. Guarda los prompts como archivos versionados, no como cadenas incrustadas: vas a
   iterarlos más que al código.
3. Pide salida estructurada con `generateObject` (Vercel AI SDK) o function calling con
   un esquema Zod, y valida la respuesta. Si no valida, reintenta una vez y después falla
   claro.
4. Transmite en streaming lo que el usuario lee (`streamText` o `streamObject`), y
   encola en segundo plano lo que tarda (transcripción, lotes, video).
5. Guarda tokens y costo por llamada, con límite por usuario y por día. Sin eso, un solo
   usuario curioso se lleva tu mes.
6. Cachea por hash de entrada: mismo documento, misma respuesta, cero costo.

## En qué te vas a trabar

- **El costo por usuario es variable y tu precio no.** Modela el margen antes de abrir el
  registro, no después de la primera factura sorpresa.
- **El modelo va a alucinar en algún porcentaje.** Enseña la fuente, permite editar y no
  automatices lo irreversible.
- **Los modelos cambian y se retiran.** Fija la versión y ten un plan de migración, no un
  nombre de modelo suelto en veinte archivos.
- **Todo texto de usuario es entrada no confiable:** trátalo como dato, nunca como
  instrucción de tu sistema.

## Criterio de terminado

No declares esto listo hasta que la salida estructurada valide contra su esquema en un
conjunto de pruebas reales, exista un límite de gasto por usuario que de verdad corte el
acceso, y el prompt inyectado por un usuario no cambie el comportamiento del sistema.

aplica en Escritura con IA · Asistentes de IA · Notas de reuniones · Voz con IA · Audio con IA · Imágenes con IA · +8

relacionadas Búsqueda y RAG · Archivos y medios · Despliegue

---
name: pagos-y-suscripciones
description: cobrar todos los meses sin perseguir a nadie.
---

# Pagos y suscripciones

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
toques checkout, planes, prueba gratis, cancelaciones o el estado de cuenta que decide
qué puede usar cada quien.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Quieres cobrar por la versión que estás construyendo, no solo usarla tú.
- Hay funciones que solo deben existir en un plan de paga.
- Vendes por asiento, por uso o con prueba gratuita.
- Necesitas facturas, impuestos o comprobantes para tus clientes.

Cobrar una vez es fácil; lo difícil es que tu base de datos y la del proveedor de pagos
digan lo mismo después de un pago fallido, un cambio de plan a medio mes o un reembolso.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: **Stripe Checkout +
Customer Portal**, o **Lemon Squeezy** / **Paddle** si prefieres que ellos sean el
comerciante registrado.

1. No construyas formularios de tarjeta. Redirige a Checkout alojado y vuelve con una
   sesión.
2. Guarda solo tres cosas de tu lado: `customerId`, `subscriptionId` y estado del plan.
   El proveedor es la fuente de la verdad del dinero, no tu tabla.
3. Deriva los permisos del estado (`active`, `trialing`, `past_due`, `canceled`), nunca
   de "pagó una vez".
4. Escucha los webhooks de suscripción y hazlos idempotentes: llegan repetidos y
   desordenados.
5. Manda a Customer Portal para cambios de plan, tarjeta y cancelación. Es la pantalla
   que menos vale la pena rehacer tú mismo.
6. Prueba con tarjetas de fallo: pago rechazado, disputa y reembolso. Ese es el camino
   que rompe la app en producción.

## En qué te vas a trabar

- **Impuestos y facturación son el moat real:** IVA, retenciones y comerciante
  registrado no son código, son cumplimiento. No los subestimes por ser "solo un
  webhook".
- **Si tu webhook falla en silencio, la gente paga y no recibe acceso.** Alerta cuando
  falle, no dejes que lo descubra el cliente.
- **Prorrateos y cambios de plan a medio ciclo son la fuente número uno de facturas
  equivocadas.** Prueba ese camino explícitamente, no solo el flujo feliz.

## Criterio de terminado

No declares esto listo hasta que un pago rechazado, una disputa y un reembolso pasen por
el sistema completo sin dejar al usuario con acceso equivocado, y hasta que el estado de
tu base de datos coincida con el de Stripe después de cada webhook de prueba.

aplica en Comercio para creadores · E-commerce · Finanzas y contabilidad · Apps sin código · Sitios web · Enlace en bio · +4

relacionadas Autenticación · Integraciones y webhooks · Correo transaccional

---
name: archivos-y-medios
description: subir, guardar y servir archivos pesados sin tumbar el servidor.
---

# Archivos y medios

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
toques subida de archivos, imágenes, audio, video o cualquier adjunto.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- El usuario sube imágenes, audio, video, PDF o adjuntos.
- La app genera archivos: exportaciones, reportes, capturas, recortes.
- Vas a mostrar medios que deben cargar rápido en móvil.
- Hay contenido privado que no puede quedar en una URL pública adivinable.

Si ninguna aplica, no agregues almacenamiento de objetos: guardar un archivo pequeño en
base de datos como bytes puede bastar para un demo.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: almacenamiento de objetos
S3-compatible (**Vercel Blob**, **Cloudflare R2** o **Backblaze B2**) con subida directa
firmada.

1. El navegador sube directo al almacenamiento con una URL firmada. Nunca hagas pasar
   200 MB por tu servidor.
2. Guarda en base de datos solo metadatos: clave, tamaño, tipo, dueño, estado. El archivo
   vive en el bucket, no en tu tabla.
3. Valida tipo y tamaño del lado del servidor al pedir la firma, no confíes en la
   extensión que manda el cliente.
4. Procesa en segundo plano: miniaturas con **sharp**, video con **ffmpeg**. La respuesta
   al usuario no espera al transcodificador.
5. Sirve lo público por CDN y lo privado por URL firmada de corta vida.
6. Limpia lo huérfano: subidas que nunca se confirmaron, archivos de cuentas borradas.

## En qué te vas a trabar

- **El egreso es la factura sorpresa.** R2 y B2 existen justo por eso: revisa el precio
  de salida antes de comprometerte con un proveedor.
- **Video es otro deporte.** Transcodificar, generar HLS y servirlo bien es
  infraestructura, no una tarde; no lo prometas a la ligera.
- **Un bucket público mal configurado expone todo lo que subieron tus usuarios**,
  incluidos sus documentos. Revisa los permisos del bucket antes de dar esto por
  terminado.

## Criterio de terminado

No declares esto listo hasta que hayas subido un archivo grande desde móvil con conexión
lenta, confirmado que el archivo privado no es accesible sin firma, y verificado que un
archivo huérfano se limpia solo.

aplica en Almacenamiento en la nube · Documentos y PDF · Edición de foto · Grabación de pantalla · Audio y video · Podcasting · +7

relacionadas Despliegue · Base de datos · Integraciones y webhooks

---
name: correo-transaccional
description: que tu correo llegue a la bandeja de entrada y no a spam.
---

# Correo transaccional

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
mandes verificaciones, recuperación de contraseña, invitaciones, avisos o recibos.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Hay cuentas: verificar correo y recuperar contraseña ya son obligatorios.
- Mandas invitaciones, recibos, alertas o resúmenes.
- Algo pasa mientras el usuario no está mirando la pantalla.
- Estás replicando un producto cuyo valor central es enviar correo a mucha gente.

Mandar un correo es una llamada a una API; que llegue es otra cosa. La entregabilidad
depende de dominio propio, SPF, DKIM, DMARC y reputación acumulada, y es exactamente la
parte que no se puede improvisar.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: **Resend** o **Postmark**
con dominio propio verificado, plantillas en el repo, envío desde una cola.

1. Usa un subdominio dedicado (`mail.tudominio.com`) y verifica SPF, DKIM y DMARC antes
   del primer envío real.
2. Separa transaccional de marketing. Mezclarlos hunde la reputación de tus correos
   importantes.
3. Plantillas con **react-email** o **MJML**, exportadas a HTML con estilos inline y
   versión en texto plano. Nada de CSS moderno: los clientes de correo viven en 2005.
4. Encola los envíos y reintenta con espera creciente. Un correo no debe bloquear la
   respuesta HTTP.
5. Registra el resultado por mensaje (enviado, rebotado, quejado) y deja de escribir a
   direcciones que rebotan duro.
6. Pon un enlace de baja real en todo lo que no sea estrictamente transaccional.

## En qué te vas a trabar

- **La entregabilidad se construye con semanas de envío limpio.** Un dominio nuevo
  empieza sin crédito; no prometas entrega perfecta desde el primer día.
- **Envío masivo desde tu propio servidor SMTP es la manera más rápida de terminar en
  listas negras.** Usa un proveedor con reputación (Resend, Postmark), no tu propio
  servidor.
- **Gmail y Outlook exigen DMARC para remitentes con volumen.** Sin eso, el correo
  simplemente no llega, y no vas a ver un error que lo explique.

## Criterio de terminado

No declares el correo listo hasta que un mensaje de prueba llegue a Gmail y Outlook sin
caer en spam, con SPF, DKIM y DMARC en verde, y hasta que confirmes que un rebote duro
detiene los envíos futuros a esa dirección.

aplica en Correo · Boletines · Formularios · Prospección de ventas · Listas de espera · Monitoreo de disponibilidad · +4

relacionadas Autenticación · Integraciones y webhooks · Pagos y suscripciones

---
name: despliegue
description: que exista en internet, con dominio, y que siga existiendo mañana.
---

# Despliegue

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
pongas la app en línea, configures dominio, variables de entorno o monitoreo.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Alguien que no eres tú tiene que abrir la app.
- Necesitas dominio propio, HTTPS y una URL estable para compartir.
- Hay secretos (llaves de API, base de datos) que no pueden vivir en el repo.
- Quieres enterarte de los errores antes de que te los reporten.

Este es el paso que separa una carpeta en tu máquina de algo que alguien más puede usar,
y también donde una réplica "gratis" empieza a costar dinero de verdad.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: **Vercel** o **Railway**
para la app, Postgres administrado aparte, secretos en el panel del proveedor, un
contenedor propio solo si el trabajo es pesado y constante.

1. Despliegue desde Git: cada push a `main` publica, cada rama abre una vista previa.
2. Variables de entorno en el proveedor, con `.env.example` versionado. Ningún secreto
   en el repo, nunca.
3. Dominio propio y HTTPS desde el inicio: cookies, OAuth y correo dependen del dominio
   final, así que no lo dejes para el último día.
4. Base de datos administrada con respaldos automáticos y restauración probada al menos
   una vez.
5. Agrega registro de errores (**Sentry** o el del proveedor) y una alerta a tu correo o
   Telegram.
6. Deja escrito en el README cómo correrlo en local y cómo desplegarlo. Tu yo de dentro
   de seis meses lo va a necesitar.

## En qué te vas a trabar

- **Las funciones sin servidor tienen tiempo límite:** nada de procesos largos ahí, van a
  segundo plano (cola, cron, worker).
- **Los planes gratuitos duermen, limitan conexiones o cortan ancho de banda** justo
  cuando llega gente. Revisa los límites del plan antes de anunciar el lanzamiento.
- **El costo real de una réplica suma base de datos, almacenamiento, correo y llamadas a
  modelos.** Súmalos antes de prometer que sale gratis.

## Criterio de terminado

No declares el despliegue listo hasta que un push a `main` publique solo, una rama nueva
abra su propia vista previa, y una alerta de error de prueba te llegue de verdad.

aplica en Hosting · Herramientas de desarrollo · Sitios web · Apps sin código · Monitoreo · Monitoreo de disponibilidad · +2

relacionadas Base de datos · Integraciones y webhooks · Analítica de producto

---
name: roles-y-permisos
description: quién puede ver qué, y quién puede borrarlo.
---

# Roles y permisos

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
agregues espacios de trabajo, invitaciones, roles o cualquier verificación de acceso.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Más de una persona comparte el mismo contenido o proyecto.
- Hay algo que un miembro del equipo no debería ver: facturación, datos de clientes,
  exportaciones.
- Vendes por asiento y necesitas invitar, quitar y contar miembros.
- Existe una vista de administrador distinta de la vista normal.

Esta capa separa "tengo cuenta" de "puedo hacer esto". Es lo que casi siempre falta en un
rebuild de fin de semana: el demo funciona con un usuario y filtra datos ajenos en
cuanto entra el segundo.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: **Postgres** con
organizaciones y membresías, verificación centralizada en el servidor, sin lógica de
permisos en el cliente.

1. Agrega organizaciones y membresías: cada recurso cuelga de una organización, nunca
   directamente de un usuario.
2. Empieza con tres roles fijos (`owner`, `member`, `viewer`). Los permisos por recurso
   llegan cuando alguien los pida de verdad, no antes.
3. Escribe una sola función que responda `puedeHacer(usuario, accion, recurso)` y
   llámala en cada endpoint. Una función, no quince `if` sueltos repartidos por el
   código.
4. Filtra siempre por organización en la consulta, no después de traer las filas.
5. Invitaciones por token con correo, expiración y aceptación explícita.
6. Registra quién cambió roles y cuándo: es el primer dato que te van a pedir cuando
   algo salga mal.

## En qué te vas a trabar

- **Ocultar un botón no es un permiso.** Si el endpoint no verifica, el permiso no
  existe, sin importar qué tan bien escondido esté en la UI.
- **El caso difícil es el último dueño:** no dejes que se elimine a sí mismo y deje la
  organización huérfana sin nadie que pueda administrarla.
- **Los permisos por campo (ver el precio pero no el margen) multiplican la
  complejidad.** Evítalos hasta tener clientes que de verdad los pidan.

## Criterio de terminado

No declares esto listo hasta que un usuario de una organización no pueda ver ni un solo
registro de otra, la eliminación del último dueño esté bloqueada, y `puedeHacer` sea el
único lugar donde vive la lógica de permisos.

aplica en Gestión de proyectos · Comunidad · Recursos humanos · CRM · Legal · Atención al cliente · +4

relacionadas Autenticación · Panel de administración · Base de datos

---
name: analitica-de-producto
description: saber qué usa la gente antes de construir lo siguiente.
---

# Analítica de producto

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
agregues registro de eventos, conteo de visitas o cualquier tablero de métricas.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Alguien más que tú ya usa la app y quieres saber si vuelve.
- Necesitas ver dónde abandona la gente el registro o el checkout.
- Vas a decidir qué construir después y no quieres decidirlo por intuición.
- Estás replicando una herramienta cuyo producto es justamente el tablero de métricas.

Si ninguna aplica, no instrumentes nada todavía: medir poco y bien vale más que medir
por si acaso.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: **Plausible** o **Umami**
autoalojado para páginas, más una tabla de eventos propia en **Postgres** para lo que
importa del producto.

1. Escribe primero las cinco preguntas que quieres responder. Los eventos salen de ahí,
   no al revés.
2. Analítica de páginas con una herramienta sin cookies (Plausible o Umami): menos aviso
   legal, menos peso, suficiente para tráfico.
3. Eventos de producto en tu propia tabla: nombre, usuario, organización, propiedades en
   JSON, fecha. Es una tabla, no una plataforma.
4. Fija una convención de nombres (`objeto_accion`) y documéntala en el repo el primer
   día, antes de que existan diez nombres distintos para lo mismo.
5. Arma las vistas agregadas con SQL y guárdalas como consultas versionadas o vistas
   materializadas, no como clics sueltos en un dashboard externo.
6. Nunca guardes datos personales en las propiedades del evento: id de usuario sí, correo
   no.

## En qué te vas a trabar

- **Los bloqueadores de anuncios se comen buena parte de los eventos del cliente.** Lo
  importante se registra en el servidor, no confíes solo en JavaScript del navegador.
- **Un tablero con veinte gráficas es un tablero que nadie lee.** Tres números y un
  embudo bastan; resiste la tentación de agregar una gráfica más.
- **Rastrear sin base legal ni aviso de privacidad es un problema, no una funcionalidad.**
  Revísalo antes de mandar el primer evento a producción.

## Criterio de terminado

No declares la analítica lista hasta que puedas responder, con datos reales y no con
intuición, las cinco preguntas que escribiste al inicio, y hasta que el tablero quepa en
una sola pantalla sin hacer scroll.

aplica en Analítica · SEO y marketing · Redes sociales · Monitoreo · Monitoreo de disponibilidad · Investigación de usuarios · +5

relacionadas Base de datos · Panel de administración · Despliegue

---
name: busqueda-y-rag
description: encontrar la respuesta dentro de tus propios documentos.
---

# Búsqueda y RAG

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
implementes búsqueda de texto completo, embeddings o respuestas con citas sobre
contenido propio.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Hay más contenido del que alguien puede recorrer a mano.
- El usuario quiere preguntar en lenguaje natural sobre documentos propios.
- Necesitas encontrar cosas por significado y no solo por palabra exacta.
- Estás replicando un asistente, un buscador o una base de conocimiento.

No empieces por la base vectorial. Para casi todo lo que vas a construir, la búsqueda
léxica de Postgres es mejor punto de partida que un stack de RAG completo.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: **Postgres** con
`tsvector` para texto completo, **pgvector** para semántica, reordenamiento híbrido
antes de pasarle nada al modelo.

1. Primero búsqueda léxica: `tsvector` con índice GIN y ranking. Resuelve más casos de
   los que crees y cuesta cero por consulta.
2. Trocea los documentos por estructura (encabezados, párrafos), no por número fijo de
   caracteres.
3. Guarda embeddings en pgvector junto a los metadatos. Una base vectorial aparte es un
   servicio más que mantener.
4. Combina ambos rankings (híbrido) y reordena los diez mejores antes de armar el
   prompt.
5. Responde siempre con citas al fragmento de origen y enlace. Sin cita, es una
   alucinación con buena redacción.
6. Reindexa cuando cambie el documento y guarda el hash para no recalcular embeddings de
   lo que no cambió.

## En qué te vas a trabar

- **Los embeddings cuestan por documento y por reindexación.** Un corpus grande deja de
  ser gratis rápido; mide el costo antes de indexar todo de golpe.
- **RAG sin evaluación es fe.** Junta veinte preguntas reales con su respuesta esperada y
  mídelas en cada cambio de prompt o de chunking.
- **Si el usuario ya sabe la palabra exacta que busca, el modelo estorba.** Deja también
  la búsqueda simple como opción, no solo el chat.

## Criterio de terminado

No declares esto listo hasta que la búsqueda léxica funcione sola sin el modelo, las
respuestas con RAG citen la fuente correcta en tus veinte preguntas de prueba, y
reindexar un documento no reprocese los que no cambiaron.

aplica en Búsqueda con IA · Notas y conocimiento · Documentos y bases de datos · Leer más tarde · Lectura · Documentos y PDF · +6

relacionadas Base de datos · Archivos y medios · Scraping y extracción

---
name: panel-de-administracion
description: la pantalla donde tú arreglas lo que el usuario rompió.
---

# Panel de administración

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
construyas listas, filtros, edición de registros o acciones peligrosas con confirmación
para el equipo, no para el usuario final.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Ya tienes usuarios reales y alguien va a escribir pidiendo ayuda.
- Hay estados que a veces se tienen que corregir a mano: pagos, invitaciones, límites.
- Necesitas ver el detalle de una cuenta sin hacer consultas SQL directas.
- Alguien no técnico del equipo tiene que revisar o moderar contenido.

El panel no es el producto, es la herramienta que te permite operar el producto. Sin él
terminas entrando a la base de datos a mano un domingo.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: rutas `/admin` dentro de la
misma app, protegidas por rol, tablas con **TanStack Table** o un componente de datos de
**shadcn/ui**, paginación por cursor.

1. Vive dentro de la app y detrás de un rol admin. Un segundo proyecto (Retool, Forest
   Admin) es un segundo despliegue que nadie mantiene y otra copia de tus permisos que
   sincronizar.
2. Empieza por dos vistas: lista de usuarios con búsqueda, y detalle de un usuario con
   todo lo suyo en una página.
3. Pagina por cursor (`WHERE id > último ORDER BY id LIMIT n`), no por `OFFSET`, y
   limita las columnas. Un panel que carga 50 mil filas es un panel que nadie abre.
4. Cada acción destructiva pide confirmación escrita y queda registrada con autor y
   fecha.
5. Agrega las tres o cuatro acciones que de verdad haces: reenviar invitación, extender
   prueba, cerrar sesiones, exportar datos.
6. Suplantar usuario (impersonate) solo con registro visible y sesión corta.

## En qué te vas a trabar

- **El panel es la superficie más peligrosa de la app:** una ruta admin sin verificación
  de rol entrega todo. Verifica el rol en el servidor, no solo en la UI.
- **Construir un panel genérico configurable cuesta más que las cinco pantallas que
  realmente necesitas.** No lo generalices antes de tiempo.
- **Exportar datos personales desde el panel también es un asunto de privacidad**, no
  solo un botón. Registra quién exportó qué.

## Criterio de terminado

No declares el panel listo hasta que una cuenta sin rol admin reciba 403 al entrar por
URL directa, la paginación aguante una tabla con decenas de miles de filas sin
lentitud, y cada acción destructiva quede registrada con autor y fecha.

aplica en CRM · Atención al cliente · Prospección de ventas · Gestión de proyectos · Recursos humanos · Monitoreo · +5

relacionadas Roles y permisos · Base de datos · Analítica de producto

---
name: scraping-y-extraccion
description: sacar datos de sitios que no te dieron una API.
---

# Scraping y extracción

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
descargues páginas, extraigas datos de HTML o vigiles cambios en sitios ajenos.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Los datos que necesitas están en páginas web y no en un endpoint.
- Vas a vigilar cambios: precios, posiciones, disponibilidad, menciones.
- Estás armando un directorio o un índice a partir de fuentes públicas.
- Necesitas convertir páginas en texto limpio para resumir o indexar.

Esto sostiene a media categoría de herramientas de SEO, prospección e investigación, y
también es lo que más mantenimiento exige: el sitio de enfrente cambia y tu extractor
deja de servir sin avisar.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: `fetch` + **cheerio** para
HTML estático, **Playwright** solo cuando la página necesita JavaScript, todo detrás de
una tabla de trabajos en Postgres (o `p-queue`) con reintentos y backoff.

1. Antes de escribir código busca feed RSS, sitemap, endpoint JSON interno o API
   oficial. Casi siempre existe uno y te ahorra todo lo demás.
2. Respeta `robots.txt` y los términos del sitio. Identifícate con un User-Agent honesto
   y de contacto.
3. Empieza con HTML estático y selectores. El navegador headless cuesta diez veces más
   por página, resérvalo para cuando realmente lo necesites.
4. Separa tres etapas: descargar, guardar el crudo, extraer. Si cambia el selector,
   reprocesas sin volver a descargar.
5. Limita la velocidad y agrega espera creciente ante 429 y 503. Un scraper agresivo se
   gana un bloqueo permanente.
6. Alerta cuando el porcentaje de campos vacíos suba: así te enteras de que el sitio
   cambió antes que tu usuario.

## En qué te vas a trabar

- **Esto se rompe solo, sin que toques nada.** Presupuesta mantenimiento, no solo
  construcción, cuando estimes cuánto tiempo lleva esta skill.
- **Evadir protecciones anti-bot cambia el problema de técnico a legal.** No lo trates
  como un detalle de implementación.
- **Un LLM extrayendo campos página por página es cómodo y carísimo:** úsalo para lo
  raro, no para el volumen.

## Criterio de terminado

No declares esto listo hasta que el extractor sobreviva un cambio menor de HTML sin
tronar por completo, la alerta de campos vacíos dispare de verdad ante un cambio de
sitio, y el ritmo de peticiones respete los límites que ya viste en 429 y 503.

aplica en SEO y marketing · RSS e investigación · Prospección de ventas · Investigación de usuarios · Viajes · Búsqueda con IA · +4

relacionadas Integraciones y webhooks · Base de datos · Búsqueda y RAG

---
name: facturacion-cfdi-mexico
description: emitir, timbrar y cancelar comprobantes sin fingir que un PDF es una factura.
---

# Facturación y CFDI en México

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
emitas CFDI, recibas datos fiscales o conectes un flujo de cobro con un PAC.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Una empresa mexicana debe entregar CFDI por una venta o servicio.
- El cliente captura RFC, razón social, régimen fiscal, código postal y uso de CFDI.
- Hay pagos diferidos que requieren complemento de recepción de pagos.
- La app administra cancelaciones, notas de crédito o descarga de XML fiscal.

Si solo muestras una cotización o recibo interno, no lo llames factura fiscal. Genera un
PDF claramente marcado y mantén el timbrado fuera del alcance.

## Cómo armarla

Usa la versión vigente de **CFDI publicada por el SAT** y timbra mediante un **PAC
autorizado** con API y ambiente de pruebas. No implementes un PAC ni el protocolo del SAT.

1. Pide a contabilidad una matriz de casos antes de escribir código: ingreso, egreso,
   pago, moneda, impuestos, pago en parcialidades y complementos que sí aplican.
2. Encapsula al PAC detrás de una interfaz propia: `crear`, `timbrar`, `consultar`,
   `cancelar` y `descargarAcuse`. Así puedes cambiar proveedor sin reescribir ventas.
3. Valida los datos fiscales contra catálogos vigentes antes del timbrado. Conserva los
   códigos del SAT, no solo sus etiquetas visibles.
4. Calcula importes en decimales, con reglas explícitas de redondeo. Guarda subtotal,
   descuentos, impuestos trasladados y retenidos por concepto y en totales.
5. Envía una llave de idempotencia propia al PAC o registra una por operación. Si vence
   la petición, consulta antes de reintentar para no timbrar dos CFDI.
6. Guarda XML timbrado, UUID, sellos, cadena original, fecha, estado, respuesta del PAC y
   acuses. El XML es el comprobante; el PDF es solo su representación impresa.
7. Modela cancelación como un proceso con estado y acuse, no como borrar una fila. Liga
   sustituciones y notas de crédito al comprobante original.
8. Emite complementos, como recepción de pagos o Carta Porte, solo cuando el caso fiscal
   lo requiera y con revisión de una persona especialista.

## En qué te vas a trabar

- **Los catálogos y reglas cambian.** Versiona la integración y programa una revisión
  fiscal; que el endpoint siga respondiendo no significa que el comprobante sea correcto.
- **Cada PAC tiene errores y sandbox distintos.** Conserva request, response y un id de
  correlación sin registrar certificados, llaves privadas ni datos innecesarios.
- **Cobro y timbrado no son el mismo evento.** Un pago aprobado puede requerir otra fecha,
  moneda, forma o método de pago; no los unas con un `if` improvisado.
- **El costo incluye timbres, soporte y operación.** Cotiza con el PAC elegido según el
  volumen real y anota la tarifa y fecha vigentes en la configuración interna.

## Qué NO hacer

- No fabriques XML a partir de una plantilla copiada de internet ni selles documentos a
  mano si el SDK o API del PAC ya resuelve el estándar vigente.
- No guardes la e.firma, el CSD o sus contraseñas en texto claro ni en el repo.
- No prometas que un CFDI es deducible; eso depende del caso fiscal del receptor.
- No borres comprobantes timbrados ni sobrescribas su XML para corregirlos.

## Checklist

- [ ] La matriz fiscal fue revisada por contabilidad para los casos que sí soportas.
- [ ] El PAC aparece como autorizado y las credenciales de prueba y producción están separadas.
- [ ] Catálogos, decimales e impuestos se validan antes de enviar.
- [ ] Un timeout y un reintento no producen dos UUID para la misma operación.
- [ ] XML, PDF, UUID, estado y acuses se pueden descargar por separado.
- [ ] Cancelación, sustitución y complemento de pagos tienen pruebas de punta a punta.
- [ ] Certificados y llaves están cifrados, rotables y fuera de logs.

aplica en Finanzas y contabilidad · E-commerce · Comercio para creadores · Finanzas personales · Legal

relacionadas Pagos y suscripciones · Integraciones y webhooks · Base de datos

---
name: generacion-de-pdf
description: cotizaciones, facturas y reportes que se imprimen igual en cualquier equipo.
---

# Generación de PDF

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
generes cotizaciones, representaciones de facturas, contratos o reportes descargables.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- El documento se imprime, firma, envía por correo o archiva fuera de la app.
- El diseño necesita encabezados, pies, numeración y saltos de página reproducibles.
- Debes conservar exactamente qué versión vio o aceptó una persona.
- La exportación debe funcionar sin depender del navegador del cliente.

Si el usuario solo necesita leer una tabla en pantalla, ofrece CSV antes de PDF. Un PDF
no vuelve auditable un reporte ni sustituye los datos estructurados.

## Cómo armarla

Usa plantillas **HTML y CSS de impresión** renderizadas en servidor con **Playwright y
Chromium**. Usa **pdf-lib** únicamente para unir, numerar o estampar PDFs existentes.

1. Separa `datos -> plantilla -> render`. La plantilla recibe un objeto validado y nunca
   consulta la base de datos por su cuenta.
2. Versiona cada plantilla. Guarda versión, idioma, zona horaria, moneda y hash de los
   datos junto al archivo generado para poder reproducirlo.
3. Empaqueta las fuentes y logotipos con el proyecto. Espera a que carguen antes de
   imprimir; no dependas de una URL externa que puede fallar mañana.
4. Define tamaño Carta o A4 explícitamente según el mercado. Prueba márgenes, encabezado,
   pie, tablas largas, filas indivisibles y páginas casi vacías.
5. Formatea fechas, monedas, separadores y nombres legales con locale explícito. No uses
   el locale del servidor.
6. Genera documentos pesados en una cola y guarda el resultado en almacenamiento de
   objetos. Devuelve estado de progreso y una URL firmada, no una petición HTTP eterna.
7. Escapa todo texto del usuario y bloquea URLs arbitrarias en el renderizador. Chromium
   no debe poder leer metadatos internos ni archivos locales.
8. Agrega texto seleccionable y orden de lectura razonable. Una captura gigante dentro
   de un PDF no es un documento accesible ni buscable.

## En qué te vas a trabar

- **Los saltos de página aparecen con datos reales.** Prueba nombres largos, miles de
  filas, una sola fila y textos sin espacios, no solo el ejemplo bonito.
- **Chromium pesa y consume memoria.** Usa un proceso controlado o worker compatible con
  tu hosting y limita concurrencia; no abras un navegador nuevo por cada renglón.
- **La representación fiscal no crea validez fiscal.** Para CFDI conserva el XML
  timbrado y etiqueta el PDF como representación impresa.
- **Fuentes y caracteres fallan por región.** Verifica acentos, ñ, portugués y símbolos
  de moneda con las fuentes realmente incrustadas.

## Qué NO hacer

- No construyas el PDF con coordenadas absolutas para cada texto salvo que llenes un
  formulario fijo existente.
- No generes documentos oficiales únicamente en el navegador.
- No cargues HTML proporcionado por el usuario dentro de Chromium sin sanitizar.
- No sobrescribas un documento ya emitido; genera una nueva versión y conserva el vínculo.

## Checklist

- [ ] La plantilla y su esquema de datos están versionados.
- [ ] Carta y A4 se probaron con contenido mínimo, máximo y multilingüe.
- [ ] Las fuentes están incrustadas y el texto se puede seleccionar.
- [ ] La generación pesada corre fuera de la petición principal y limita concurrencia.
- [ ] El renderizador no puede acceder a red interna, archivos locales ni URLs arbitrarias.
- [ ] Cada archivo conserva hash, versión, locale y datos de origen trazables.
- [ ] El PDF de un CFDI se entrega junto al XML, nunca en su lugar.

aplica en Documentos y PDF · Finanzas y contabilidad · Presentaciones · Formularios · Legal · Comercio para creadores

relacionadas Archivos y medios · Base de datos · Panel de administración

---
name: notificaciones-push-y-sms
description: avisar a tiempo sin duplicar mensajes ni convertirte en spam.
---

# Notificaciones push y SMS

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
mandes alertas fuera de la sesión por Web Push, push móvil o SMS.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- El aviso pierde valor si la persona lo ve hasta abrir la app.
- Hay recordatorios de citas, incidentes, entregas o acciones urgentes.
- Necesitas un canal alterno cuando el correo no llega.
- El producto promete alertas configurables por evento y horario.

No agregues tres canales por reflejo. Empieza por el canal que el usuario ya espera y
mide entrega, interacción y bajas antes de sumar otro.

## Cómo armarla

Usa **Web Push con VAPID** para web. Para apps nativas usa **FCM/APNs** mediante Expo si
el proyecto ya usa Expo. Para SMS usa **Twilio** o **Bird** con cobertura comprobada en
cada país objetivo.

1. Modela una notificación lógica separada de sus entregas. Una alerta puede intentar
   push y después SMS, pero conserva un solo `notificationId` para evitar duplicados.
2. Guarda preferencias por tipo de evento, canal, zona horaria y horario silencioso.
   Pide permiso de push después de explicar el valor, no al cargar la primera pantalla.
3. Cifra suscripciones Web Push y tokens móviles; bórralos cuando el proveedor responda
   que expiraron. Nunca uses el token como identificador de usuario.
4. Encola cada entrega con una llave idempotente. Registra proveedor, intento, estado,
   código de error y fecha de entrega cuando exista callback.
5. Para SMS, normaliza a E.164 y verifica que el país y tipo de remitente estén
   soportados. Respeta consentimiento, baja y restricciones A2P locales.
6. Calcula segmentos antes de enviar SMS: Unicode y textos largos pueden multiplicar el
   costo. Manda enlaces cortos bajo tu propio dominio, no acortadores opacos.
7. Consulta precios vigentes por país y operador, incluidos número, remitente y cargos
   del carrier. Guarda un presupuesto diario y corta envíos anómalos.
8. Implementa fallback solo para avisos críticos y después de un timeout definido. Un
   mensaje `delivered` no necesita repetirse por todos los canales.

## En qué te vas a trabar

- **Push no garantiza entrega.** El sistema operativo decide cuándo mostrarlo y puede
  revocar tokens; diseña la app para que el estado correcto también exista adentro.
- **SMS funciona distinto en cada país.** El remitente, registro, contenido permitido y
  recepción de respuestas cambian; verifica México, Brasil, Colombia o el mercado real
  por separado.
- **El fraude por bombeo de SMS genera facturas reales.** Deshabilita destinos que no
  operas, limita intentos por cuenta, IP y número, y alerta ante picos.
- **Los costos no son una tarifa LATAM única.** Usa la API o tabla vigente del proveedor
  y revisa el costo efectivo por mensaje entregado, no una cifra copiada de un blog.

## Qué NO hacer

- No uses SMS para secretos permanentes ni incluyas datos sensibles en la pantalla bloqueada.
- No pidas permiso de notificaciones sin contexto ni lo conviertas en requisito de registro.
- No reintentes un error permanente como número inválido o baja del destinatario.
- No anuncies entrega garantizada cuando el proveedor solo confirmó aceptación.

## Checklist

- [ ] Cada tipo de aviso tiene finalidad, canal y urgencia definidos.
- [ ] Preferencias, consentimiento, baja y horario silencioso funcionan por usuario.
- [ ] Tokens inválidos se eliminan y los webhooks de estado son idempotentes.
- [ ] El fallback no produce avisos dobles cuando el primer canal entrega tarde.
- [ ] Países no usados están bloqueados y existen límites contra bombeo de SMS.
- [ ] Costos por país, segmento y carrier se miden con tarifas vigentes.
- [ ] El contenido sensible no aparece en push ni SMS.

aplica en Redes sociales · Atención al cliente · Monitoreo · Monitoreo de disponibilidad · Calendario · E-commerce · +2

relacionadas Correo transaccional · Integraciones y webhooks · Analítica de producto

---
name: tareas-programadas-y-colas
description: hacer trabajo después, reintentarlo y saber cuándo dejó de funcionar.
---

# Tareas programadas y colas

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando el
trabajo no deba terminar dentro de una petición web o tenga que ocurrir en el futuro.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Generas archivos, importas datos, envías lotes o llamas una API lenta.
- Algo debe correr cada hora, cada noche o en una fecha elegida por el usuario.
- Un fallo temporal debe reintentarse sin que la persona repita la acción.
- Necesitas limitar concurrencia o respetar la tasa de un proveedor externo.

Si el trabajo tarda milisegundos y no tiene efectos externos, ejecútalo en la petición.
Una cola agrega operación; úsala porque necesitas sus garantías, no por arquitectura.

## Cómo armarla

Usa **pg-boss sobre Postgres** con un worker siempre activo. Si el proyecto es totalmente
serverless, usa **Inngest** o **Trigger.dev** y conserva las mismas reglas de idempotencia.

1. El endpoint valida, guarda el cambio de negocio y encola un id de recurso. No metas
   documentos completos ni secretos en el payload.
2. Define por tipo de job: esquema versionado, timeout, máximo de intentos, concurrencia
   y llave de idempotencia. Rechaza payloads con una versión desconocida.
3. Haz cada handler idempotente. Antes de cobrar, enviar o crear, busca el efecto por su
   llave; marca terminado solo después de confirmar el resultado externo.
4. Reintenta errores temporales con espera exponencial y jitter. Manda errores
   permanentes a fallidos de inmediato y conserva una cola muerta operable.
5. Usa leases o visibilidad con vencimiento para recuperar trabajos de un worker caído.
   Asume entrega al menos una vez, nunca exactamente una vez.
6. Haz que el cron solo encole. Usa UTC para disparadores del sistema y guarda la zona
   IANA cuando el horario pertenece a una persona o negocio.
7. Registra espera, duración, intentos, error y correlación. Alerta por edad del job más
   viejo y por crecimiento de fallidos, no solo por CPU.
8. Agrega cancelar y reintentar desde una vista protegida. Reintentar debe conservar la
   llave original o declarar explícitamente una nueva operación.

## En qué te vas a trabar

- **El worker muere a mitad del efecto externo.** Por eso el handler consulta antes de
  repetir y el proveedor recibe una llave de idempotencia cuando la soporta.
- **Un cron puede dispararse dos veces o no dispararse.** Pon un registro único por
  periodo y un reconciliador que encuentre ejecuciones faltantes.
- **Los jobs viejos cambian de forma cuando despliegas código nuevo.** Versiona payloads
  y mantén un adaptador mientras quede trabajo con la versión anterior.
- **La cola también cuesta.** Mide retención, Redis o Postgres, workers encendidos y
  llamadas reintentadas antes de vender procesamiento ilimitado.

## Qué NO hacer

- No uses `setTimeout` en un proceso web para trabajo importante.
- No reintentes sin límite ni a intervalos fijos contra un proveedor caído.
- No guardes tokens, archivos binarios o datos personales innecesarios en el payload.
- No marques el job terminado antes de persistir el efecto que el usuario espera.

## Checklist

- [ ] Cada tipo de job tiene esquema, timeout, intentos, concurrencia e idempotencia.
- [ ] Un worker que muere a mitad del proceso no pierde ni duplica el efecto.
- [ ] Cron duplicado y cron omitido tienen pruebas y reconciliación.
- [ ] Errores permanentes llegan a una cola muerta visible y reintentable.
- [ ] Métricas y alertas cubren espera, duración, fallos y edad del trabajo más viejo.
- [ ] Los horarios del usuario conservan su zona IANA y los del sistema usan UTC.
- [ ] Un despliegue nuevo puede procesar payloads antiguos todavía en cola.

aplica en Automatización · Tareas programadas · Monitoreo · Monitoreo de disponibilidad · Herramientas de desarrollo · Boletines · +2

relacionadas Integraciones y webhooks · Despliegue · Base de datos

---
name: whatsapp-business-api
description: mensajes operativos por el canal que tus clientes en LATAM sí abren.
---

# WhatsApp Business API

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
envíes o recibas mensajes con la plataforma oficial de WhatsApp Business.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- El negocio confirma pedidos, citas, entregas o pagos por WhatsApp.
- Un equipo atiende conversaciones iniciadas por clientes desde un mismo número.
- Necesitas plantillas aprobadas, estados de entrega o respuestas automáticas.
- WhatsApp es parte del flujo principal y un enlace `wa.me` ya no basta.

Si solo necesitas abrir una conversación manual, usa un enlace `wa.me` con texto
precargado. No conectes la API, verificación comercial y webhooks para un botón.

## Cómo armarla

Usa **WhatsApp Cloud API de Meta** directamente. Agrega un BSP oficial solo si necesitas
onboarding administrado de muchos negocios, soporte contractual o una bandeja que no vas
a construir.

1. Crea la app de Meta, la cuenta de WhatsApp Business y un número real. Completa la
   verificación que Meta solicite antes de prometer una fecha de salida.
2. Guarda `phoneNumberId`, `wabaId` y el token de sistema cifrado en el servidor. Nunca
   expongas el token en el navegador ni uses el token temporal del tutorial en producción.
3. Normaliza destinatarios a E.164 y conserva por separado el número que escribió el
   usuario. No inventes códigos de país ni corrijas un número ambiguo en silencio.
4. Registra el consentimiento con fecha, origen y finalidad. Separa soporte, avisos
   operativos y marketing; una aceptación para un pedido no autoriza campañas eternas.
5. Crea pocas plantillas, con variables nombradas y ejemplos reales. Envía texto libre
   solo dentro de la ventana de atención vigente de Meta; fuera de ella usa una plantilla
   aprobada para la categoría correcta.
6. Verifica el challenge inicial y la firma de cada webhook. Responde rápido, encola el
   evento y procesa de forma idempotente por el id de mensaje.
7. Guarda estados `queued`, `sent`, `delivered`, `read` y `failed`, junto con el código
   del proveedor. La respuesta 200 al envío no significa que el teléfono lo recibió.
8. Implementa derivación a una persona: pausa el bot, muestra el contexto y deja una
   marca inequívoca de quién controla la conversación.

## En qué te vas a trabar

- **La aprobación no es instantánea.** El negocio, el nombre visible, el número y las
  plantillas pueden requerir revisión; empieza con el número de prueba, pero no confundas
  esa prueba con producción.
- **El costo cambia por mercado y tipo de plantilla.** Meta y un BSP pueden cobrar por
  separado. Consulta la tarifa vigente para cada país objetivo y registra costo por
  mensaje entregado antes de fijar el precio de tu plan.
- **Los webhooks llegan repetidos, tarde o fuera de orden.** Modela estados monotónicos y
  no dispares dos pedidos porque recibiste dos veces el mismo mensaje.
- **La operación humana sigue existiendo.** Automatizar soporte sin horario, cola y
  responsable solo mueve el caos a otro canal.

## Qué NO hacer

- No automatices WhatsApp Web ni uses librerías que simulan un teléfono. Arriesgas el
  número del negocio y construyes sobre un protocolo no soportado.
- No compres listas ni envíes marketing sin consentimiento y baja efectiva.
- No hagas depender un pedido solo de que el mensaje muestre `sent`.
- No metas reglas comerciales dentro del texto de una plantilla; guarda la lógica en
  código y manda a la plantilla únicamente los valores finales.

## Checklist

- [ ] El número de producción y el nombre visible están aprobados.
- [ ] Los tokens viven cifrados en el servidor y tienen rotación documentada.
- [ ] Cada destinatario tiene consentimiento trazable y mecanismo de baja.
- [ ] Los webhooks validan firma, toleran duplicados y conservan el payload crudo.
- [ ] Una plantilla aprobada funciona fuera de la ventana de atención.
- [ ] Los estados de entrega y los fallos aparecen en una vista operativa.
- [ ] Una conversación puede pasar del bot a una persona sin respuestas dobles.

aplica en CRM · Atención al cliente · E-commerce · Comercio para creadores · Prospección de ventas · Calendario · +1

relacionadas Integraciones y webhooks · Correo transaccional · Panel de administración

---
name: agendas-y-disponibilidad
description: reservar un horario real sin dobles citas ni errores de zona horaria.
---

# Agendas y disponibilidad

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando una
persona publique horarios, reserve citas o sincronice calendarios.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Clientes reservan servicios, consultas, clases, demos o recursos.
- La disponibilidad depende de horario laboral, descansos, buffers o días bloqueados.
- Dos calendarios deben evitar choques.
- Hay recordatorios, reprogramación, cancelación o citas recurrentes.

Si solo eliges una fecha sin disponibilidad limitada, usa un campo de fecha. No modeles
slots, holds y calendarios para una preferencia que nadie puede agotar.

## Cómo armarla

Usa **Postgres** para reglas y reservas, **Luxon** o `date-fns-tz` para zonas IANA y
**Google Calendar API** solo después de que la agenda interna funcione sola.

1. Guarda instantes confirmados en UTC y la zona IANA original, como
   `America/Mexico_City`. Expresa horarios semanales en la zona del negocio, no como UTC.
2. Modela disponibilidad como reglas más excepciones: horario semanal, feriados, bloqueos,
   buffers, anticipación mínima, horizonte máximo, duración, capacidad y recursos.
3. Calcula slots en el servidor para un rango acotado. Convierte a la zona de quien mira
   solo al presentar y muestra ambas zonas cuando organizador e invitado difieren.
4. Al seleccionar, crea un hold corto con expiración. Confirma dentro de una transacción
   con una restricción que impida traslape; volver a consultar antes de insertar no basta.
5. Usa una llave idempotente al confirmar. Un doble clic o reintento debe devolver la
   misma reserva, no ocupar dos espacios.
6. Trata calendario externo como integración, no como base principal: guarda id externo,
   `etag` o token de sincronización, estado y última sincronización. Reconcilia cambios.
7. Genera invitación ICS y recordatorios desde una cola. Cancelar o reprogramar crea un
   historial y actualiza todos los canales, no sobrescribe el pasado.
8. Ofrece enlaces firmados de duración limitada para cancelar o mover una cita sin crear
   cuenta, si el riesgo del servicio lo permite.

## En qué te vas a trabar

- **El horario de verano rompe offsets fijos.** Prueba cambios DST aunque tu ciudad no
  cambie reloj; el cliente, profesional o calendario conectado puede vivir en otra zona.
- **La concurrencia crea dobles reservas.** Dos confirmaciones simultáneas deben competir
  en la base de datos, no en memoria ni en botones deshabilitados.
- **Google y Microsoft envían cambios repetidos y parciales.** Usa tokens incrementales,
  webhooks idempotentes y una reconciliación periódica.
- **Recordatorios cuestan por canal.** Calcula correo, WhatsApp o SMS con la tarifa vigente
  y permite que el negocio elija cuáles justifican el margen.

## Qué NO hacer

- No guardes solo `-06:00`; el offset no contiene reglas futuras de zona horaria.
- No crees todos los slots del año como filas por adelantado.
- No prometas sincronización bidireccional si solo importas eventos una vez.
- No borres citas canceladas ni liberes un hold sin verificar quién lo posee.

## Checklist

- [ ] Reglas, excepciones, buffers, capacidad y recursos producen los slots esperados.
- [ ] UTC y zona IANA sobreviven cambios DST y reservas entre países.
- [ ] Dos confirmaciones simultáneas no crean traslape.
- [ ] Holds vencen solos y confirmar dos veces devuelve la misma reserva.
- [ ] Cancelación y reprogramación conservan historial y actualizan invitaciones.
- [ ] La sincronización externa tolera duplicados, expiración de token y cambios remotos.
- [ ] Recordatorios respetan zona, horario silencioso, consentimiento y presupuesto.

aplica en Calendario · Tareas y calendario · Control de horas · Atención al cliente · Bienestar · Educación · +2

relacionadas Integraciones y webhooks · Base de datos · Correo transaccional

---
name: cumplimiento-y-privacidad-latam
description: recoger menos datos y poder explicar, entregar o borrar los que sí guardas.
---

# Cumplimiento y privacidad en LATAM

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
trates datos personales de clientes, empleados, pacientes, estudiantes o visitantes.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Guardas nombre, correo, teléfono, domicilio, ubicación, identificadores o comportamiento.
- Operas en México bajo LFPDPPP, en Brasil bajo LGPD o en más de un país de LATAM.
- Usas analítica, publicidad, IA o proveedores que reciben datos del usuario.
- Una persona puede pedir acceso, corrección, cancelación, oposición, eliminación o portabilidad.

Esto no sustituye asesoría legal. Implementa controles verificables y pide a una persona
especialista que determine ley aplicable, base jurídica, textos y plazos para tu operación.

## Cómo armarla

Usa **Postgres** para el inventario, consentimiento y solicitudes; cifrado administrado
para datos en reposo y un gestor de secretos. Trata la política como producto, no como PDF.

1. Haz un inventario por campo: dato, finalidad, titular, origen, sistema, proveedor,
   país, acceso, retención y fundamento indicado por asesoría. Si no puedes justificarlo,
   deja de recogerlo.
2. Publica un aviso de privacidad por versión y registra cuál se mostró. En México incluye
   el mecanismo para derechos ARCO; en Brasil implementa los derechos y canales que la
   LGPD vigente exija para tu rol y tratamiento.
3. Registra consentimiento solo donde sea la base elegida: finalidad, texto, versión,
   fecha, fuente y prueba. Retirarlo debe ser tan claro como otorgarlo.
4. Construye un flujo de solicitudes: recepción, verificación proporcional de identidad,
   búsqueda, revisión, respuesta, ejecución y evidencia. Los plazos vienen de la ley y el
   caso vigente, no de una constante copiada sin revisión.
5. Separa borrar, anonimizar, bloquear y retener por obligación. Propaga la acción a
   archivos, buscadores, analítica y proveedores, sin borrar comprobantes que deban
   conservarse legalmente.
6. Minimiza acceso con roles, consultas por tenant y logs de acciones sensibles. Cifra
   datos de alto riesgo y no pongas datos personales en URLs, nombres de archivo o logs.
7. Mantén un registro de encargados y transferencias. Firma acuerdos adecuados y revisa
   región, subencargados, retención y borrado de cada proveedor.
8. Define respuesta a incidentes: detectar, contener, preservar evidencia, evaluar riesgo,
   escalar y notificar según la jurisdicción. Ensáyala antes de una fuga real.

## En qué te vas a trabar

- **LATAM no es una sola ley.** México y Brasil no usan exactamente los mismos conceptos,
  autoridades ni procedimientos; parametriza país y valida cada lanzamiento local.
- **Borrar de producción no borra copias.** Define cómo expiran respaldos y cómo evitas
  que una restauración reactive cuentas o consentimientos eliminados.
- **La IA multiplica destinatarios y finalidades.** Documenta qué sale a cada modelo,
  desactiva entrenamiento cuando el contrato lo permita y no envíes campos que no necesita.
- **Cumplimiento tiene costo operativo.** Incluye revisión legal, atención de solicitudes,
  auditoría de proveedores y respuesta a incidentes; no lo presupuestes como una pantalla.

## Qué NO hacer

- No copies un aviso de otra empresa ni marques todas las casillas por defecto.
- No pidas identificación excesiva para ejercer un derecho.
- No prometas “cumplimos toda LATAM” por alojar datos en una región concreta.
- No uses borrado suave como respuesta final a una solicitud aprobada de eliminación.

## Checklist

- [ ] El inventario cubre campos, finalidades, sistemas, proveedores, países y retención.
- [ ] Un especialista revisó ley aplicable, aviso, bases y plazos vigentes.
- [ ] Consentimiento y retiro conservan evidencia por finalidad y versión.
- [ ] Una solicitud completa se puede localizar, exportar, corregir y ejecutar de punta a punta.
- [ ] Borrado o anonimización se propaga sin violar retenciones obligatorias.
- [ ] Respaldos, logs, modelos de IA y subencargados tienen tratamiento documentado.
- [ ] El simulacro de incidente produce responsables, evidencia y decisión de notificación.

aplica en Seguridad · Legal · Recursos humanos · Bienestar · Finanzas personales · Finanzas y contabilidad · +5

relacionadas Autenticación · Base de datos · Panel de administración

---
name: importar-exportar-csv-excel
description: migrar datos reales sin perder acentos, decimales ni una tarde corrigiendo filas.
---

# Importar y exportar CSV y Excel

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando una
persona migre desde una hoja de cálculo o necesite sacar todos sus datos.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- El cliente ya opera en Excel, Google Sheets o un CSV de otro sistema.
- Cargar registros uno por uno haría inviable el onboarding.
- Finanzas, ventas u operaciones necesitan conciliar datos fuera de la app.
- Debes ofrecer portabilidad o una salida completa de la cuenta.

No construyas un importador genérico universal. Soporta primero una entidad y dos o tres
formatos reales de clientes, con una plantilla descargable.

## Cómo armarla

Usa **csv-parse** para CSV y **ExcelJS** para `.xlsx`. Procesa el archivo en un worker,
con una tabla temporal de filas antes de tocar las tablas del producto.

1. Publica una plantilla con encabezados, ejemplos, campos obligatorios, formatos y una
   versión. Acepta también mapeo manual de columnas para archivos existentes.
2. Detecta BOM, UTF-8, delimitador y encabezados. Si la codificación es ambigua, muestra
   una vista previa y pide confirmación; no adivines acentos rotos.
3. Conserva cada valor crudo y produce un valor normalizado aparte. Fechas `03/04/2026`,
   comas decimales, teléfonos y RFC no se convierten sin locale o regla elegida.
4. Valida por fila y por lote. Muestra antes de importar: válidas, advertencias, errores,
   nuevas, actualizaciones y posibles duplicados.
5. Define la clave de coincidencia con el usuario. Correo, RFC o folio pueden cambiar o
   repetirse; nunca elijas una heurística destructiva en silencio.
6. Importa en transacción por bloques, con `importId` y llave idempotente. Permite
   reanudar y deshacer el lote sin borrar cambios posteriores de otras personas.
7. Devuelve un archivo de errores con número de fila, columna, valor original y motivo
   accionable. “Fila inválida” no ayuda a corregir mil registros.
8. En exportación usa UTF-8, encabezados estables y zona horaria explícita. Neutraliza
   celdas que empiezan con `=`, `+`, `-` o `@` para evitar inyección de fórmulas.

## En qué te vas a trabar

- **Excel mezcla tipos dentro de una columna.** Un folio puede llegar como número, texto
  o notación científica; trata identificadores como texto desde el principio.
- **Las fechas no tienen un significado universal.** Exige formato ISO en tu plantilla y
  pide locale para archivos heredados.
- **Los archivos grandes agotan memoria y timeout.** Haz streaming de CSV, limita tamaño
  y filas, y procesa XLSX pesado fuera de la petición web.
- **La fidelidad de ida y vuelta tiene límites.** Exporta datos, no prometas conservar
  macros, fórmulas, estilos y gráficas de un libro ajeno.

## Qué NO hacer

- No insertes fila por fila directamente en producción sin vista previa ni rollback.
- No aceptes macros ni ejecutes fórmulas del archivo.
- No conviertas teléfonos, códigos postales, CLABE o folios a números.
- No ocultes filas rechazadas ni las omitas silenciosamente de la cuenta final.

## Checklist

- [ ] Existe una plantilla versionada y un mapeo manual de columnas.
- [ ] Acentos, BOM, delimitadores, comas decimales y fechas ambiguas tienen pruebas.
- [ ] La vista previa separa altas, cambios, duplicados, advertencias y errores.
- [ ] Repetir el mismo archivo no duplica registros y el lote se puede deshacer.
- [ ] El archivo de errores señala fila, columna, valor y corrección esperada.
- [ ] CSV grande se procesa en streaming y XLSX tiene límites explícitos.
- [ ] La exportación neutraliza fórmulas y conserva ids como texto.

aplica en Finanzas y contabilidad · CRM · Gestión de proyectos · Tareas · Apps sin código · Bases de datos · +5

relacionadas Base de datos · Panel de administración · Archivos y medios

---
name: mapas-y-geolocalizacion
description: convertir direcciones imperfectas en ubicaciones, rutas y zonas operables.
---

# Mapas y geolocalización

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
captures direcciones, muestres mapas, calcules rutas o delimites zonas de servicio.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Una entrega, visita, propiedad o servicio depende de una ubicación física.
- Necesitas autocompletar o geocodificar direcciones de LATAM.
- El precio o la disponibilidad cambia dentro de una zona dibujada.
- Debes calcular distancia o tiempo real por calles, no en línea recta.

Si el mapa solo decora una ficha, usa una imagen estática o un enlace. No cargues un SDK,
consentimiento de ubicación y facturación por una chincheta sin interacción.

## Cómo armarla

Usa **Google Maps Platform** o **Mapbox** para mapa, lugares y rutas. Usa **PostGIS** para
guardar puntos y polígonos propios; el proveedor resuelve datos, tu base resuelve negocio.

1. Guarda la dirección tal como la escribió la persona y también componentes
   normalizados, coordenadas, id del proveedor, precisión y fecha de geocodificación.
2. Diseña el formulario para LATAM: calle, número exterior e interior, colonia o barrio,
   municipio, estado, código postal, país y referencias. No vuelvas obligatorio un campo
   que el país no usa de forma consistente.
3. Ofrece autocomplete, pero permite mover un pin y confirmar referencias. Una dirección
   aceptada por el proveedor puede caer en el centro del código postal.
4. Geocodifica desde el servidor, restringe las llaves por dominio o app y separa llaves
   públicas de servicios privados. Define cuotas y alertas de gasto.
5. Guarda zonas de entrega como polígonos válidos en PostGIS y consulta con la función
   espacial adecuada. Decide y prueba qué pasa exactamente en el borde.
6. Para distancia y ETA usa una API de rutas. Calcula en línea recta solo como filtro
   barato previo, nunca como promesa de kilómetros o minutos por carretera.
7. Cachea resultados respetando los términos del proveedor y conserva una estrategia de
   regeocodificación. No mezcles ids o datos derivados entre proveedores sin revisar licencias.
8. Pide ubicación del dispositivo solo tras una acción explícita y ofrece captura manual
   equivalente cuando se niegue el permiso.

## En qué te vas a trabar

- **Las direcciones de LATAM son datos humanos, no una clave exacta.** Barrios repetidos,
  calles sin número y referencias son normales; conserva confianza y permite corregir.
- **Mapa, autocomplete, geocoding y rutas se cobran distinto.** Revisa la tabla vigente
  del proveedor, limita llamadas por sesión y registra costo por pedido o búsqueda.
- **Los polígonos se rompen con geometrías inválidas.** Valida cruces, huecos, sentido y
  sistema de coordenadas al guardar, no cuando el checkout falla.
- **Una ubicación precisa es dato personal.** Reduce retención y acceso, especialmente
  para domicilios, menores, salud o ubicación en tiempo real.

## Qué NO hacer

- No uses código postal como coordenada exacta ni municipio como zona de entrega.
- No confíes solo en GPS: interiores, permisos y equipos baratos producen errores grandes.
- No expongas una llave con permisos de servidor dentro del bundle web.
- No prometas ETA con distancia euclidiana ni reutilices datos contra los términos del mapa.

## Checklist

- [ ] El formulario funciona con direcciones reales de al menos dos países objetivo.
- [ ] La persona puede corregir el pin y agregar referencias sin pelear con autocomplete.
- [ ] Llaves, cuotas, restricciones y alertas de gasto están configuradas.
- [ ] Zonas y bordes tienen pruebas espaciales en PostGIS.
- [ ] Distancia y ETA usan rutas cuando afectan precio o promesa de entrega.
- [ ] Denegar geolocalización no bloquea la captura manual.
- [ ] Retención y permisos para coordenadas precisas están documentados.

aplica en Viajes · E-commerce · Comercio para creadores · Calendario · Hogar · CRM · +2

relacionadas Integraciones y webhooks · Base de datos · Analítica de producto

---
name: onboarding-y-limites-por-plan
description: llevar a la primera victoria y cobrar por límites que el servidor sí aplica.
---

# Onboarding y límites por plan

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
armes trial, activación inicial, cuotas, feature flags o pantallas de upgrade.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Una cuenta nueva necesita datos o configuración antes de obtener valor.
- Hay prueba gratuita, plan gratis o más de un plan pagado.
- Cobras por usuarios, proyectos, almacenamiento, uso o funciones.
- Necesitas lanzar una función a un grupo sin desplegar otra versión.

Si todos reciben el mismo producto y no cobras, crea un estado vacío excelente. No
construyas un motor de entitlements porque algún día podría haber planes.

## Cómo armarla

Usa **Postgres** como fuente de verdad para onboarding y entitlements. Mantén flags
operativos en configuración versionada; agrega **PostHog feature flags** solo si ya usas
PostHog y necesitas rollout gradual.

1. Define una sola “primera victoria” medible, como publicar, importar, cobrar o invitar.
   Diseña el onboarding hacia ese evento, no hacia completar un tour.
2. Guarda pasos por cuenta con `completedAt`, versión y actor. Deriva lo que puedas de
   acciones reales; no marques “conectó calendario” porque cerró un modal.
3. Separa tres conceptos: producto contratado, estado de cobro y entitlements efectivos.
   Un webhook actualiza suscripción; una función central resuelve `puedeUsar` y `limiteDe`.
4. Define planes y límites con slugs estables. Guarda nombres y copy aparte para poder
   cambiar marketing sin romper permisos históricos.
5. Aplica límites en una transacción del servidor. Antes de crear, cuenta o reserva uso;
   la UI solo explica el resultado, nunca es la barrera real.
6. Calcula trial con fechas del servidor y una política explícita al vencer. Conserva la
   información en modo lectura cuando sea razonable; no borres trabajo para forzar upgrade.
7. Muestra el consumo antes del límite y explica qué acción lo reduce. Un upgrade modal
   debe decir qué se agotó, cuánto incluye el plan y qué pasa al bajar de plan.
8. Instrumenta inicio, primera victoria, abandono y upgrade. Revisa el embudo por canal y
   plan sin guardar datos personales en eventos.

## En qué te vas a trabar

- **Pago activo no equivale a permiso.** Asientos extra, add-ons, créditos y periodos de
  gracia exigen una capa de entitlements separada del nombre del plan.
- **Los contadores compiten.** Dos peticiones simultáneas pueden rebasar una cuota; usa
  bloqueo, contador atómico o reserva con expiración.
- **Bajar de plan deja exceso existente.** Define por recurso si bloqueas nuevas altas,
  pones solo lectura o programas eliminación; comunícalo antes del cambio.
- **Un trial tiene costo variable.** Limita modelos, SMS, almacenamiento y otros recursos
  medidos aunque la tarjeta todavía no exista.

## Qué NO hacer

- No disperses `plan === "pro"` por componentes y endpoints.
- No confíes en esconder botones para aplicar cuotas.
- No reinicies trials al cambiar correo, organización o proveedor OAuth.
- No bloquees exportación o cancelación para presionar una mejora de plan.

## Checklist

- [ ] La primera victoria tiene evento y se alcanza sin completar pasos decorativos.
- [ ] Onboarding, cobro y entitlements tienen estados separados.
- [ ] Una función central decide funciones y límites para todos los endpoints.
- [ ] Dos peticiones simultáneas no rebasan una cuota.
- [ ] Trial vencido, pago atrasado, upgrade y downgrade tienen pruebas.
- [ ] La persona ve consumo, límite y consecuencia antes de llegar al bloqueo.
- [ ] Exportar, cancelar y recuperar datos no dependen de aceptar un upgrade.

aplica en Apps sin código · Hosting · Comunidad · Comercio para creadores · E-commerce · Sitios web · +3

relacionadas Pagos y suscripciones · Autenticación · Analítica de producto