Onboarding y límites por plan

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