Vibecodea tu primera app en una tarde

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

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

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