Vibecodea tu primera app en una tarde

---
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.

---
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.

---
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.

---
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.

---
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.

---
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.

---
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.

---
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.

---
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.