AGENTS.md — Gruperly

Monorepo web + API para gestión de cobros grupales. Reglas optimizadas para agentes.

Stack & ejecutables de verdad

Package manager / runtime: Bun (v1.4+, package.json viene con workspaces y packageManager: bun). Usa bun para instalar (bun install), scripts y filtros. No uses npm/yarn/pnpm.
Monorepo: Bun Workspaces orquestado con Turborepo (turbo.json). Dependencias entre paquetes usan workspace:*.
Los paquetes son Node "type": "module".

bun run typecheck — corre tsc --noEmit en todos los paquetes vía turborepo. Es la verificación principal; correlo tras tocar código.
bun run --filter @gruperly/api typecheck / ... @gruperly/web typecheck — verificación de un solo paquete.
bun run dev — levanta API (4000) y web (6173) con turborepo.
No hay script lint en ningún paquete; bun run lint no hace nada útil. No dependas de él.
Base de datos (API): bun run db:generate / db:migrate / db:push / db:studio, o bien bun --filter @gruperly/api db:*.

apps/api — Backend Bun + Hono. Entry point src/index.ts (monta Bun.serve, puerto por defecto 4000 vía PORT). Rutas modulares en src/routes/. Prisma en prisma/schema.prisma.
apps/web — Frontend React 19 + Vite + Tailwind v4. Entry src/main.tsx → src/router.tsx. Puerto 6173 (vite.config.ts).
packages/shared — Esquemas Zod + tipos. Se consume como TS fuente directo (exports apunta a src/index.ts, sin build previo). @gruperly/shared se resuelve vía paths en cada tsconfig de app.
packages/config — tsconfig.base.json; todos los tsconfig lo extienden.

Prisma 7: requiere apps/api/.env (con DATABASE_URL). El CLI lee apps/api/prisma.config.ts (datasource url vía env('DATABASE_URL')); el schema usa provider = "prisma-client" con output en prisma/generated/prisma (gitignoreado; regenera con bun run db:generate). El PrismaClient se importa desde ../../prisma/generated/prisma/client y se instancia con @prisma/adapter-pg. Sin .env el CLI falla; copia desde apps/api/.env.example.
Turborepo solo lee lockfile textual bun.lock (no el binario bun.lockb). Si se regenera, usa bun install --save-text-lockfile. No versiones bun.lockb.
.env, dist/, .turbo/ están gitignoreados (que no te extrañe su ausencia).

Frontend en español: copy de UI, comentarios y textos en español.
Base de datos: todas las tablas usan snake_case vía @@map en prisma/schema.prisma (p. ej. User → users, WaitlistEntry → waitlist_entries). Al agregar un modelo nuevo, incluir siempre @@map("nombre_tabla").
Tailwind v4 con tokens en @theme dentro de apps/web/src/index.css (p. ej. --color-accent: #1e90ff). Se usan como clases auto-generadas: text-accent, bg-success-soft, etc. Radius por defecto 0.75rem (rounded-xl).
Router NO es file-based (aunque stack.md lo diga): las rutas se declaran manualmente en apps/web/src/router.tsx con createRoute + addChildren y se registran vía module augmentation. Cada vista nueva debe añadirse ahí.
Nav (Inicio/Grupos/Cobros/Ajustes) vive en apps/web/src/components/layout/nav-items.ts; es la fuente única para BottomNav (móvil) y Sidebar (desktop) — no dupliques la lista.
UI: primitivos propios en apps/web/src/components/ui/ (avatar, button, badge) más helper cn() en src/lib/utils.ts (clsx + tailwind-merge). Aunque stack.md mencione Shadcn, todavía no está instalado (sin Radix); úsalos directos.
Layout mobile-first: RootLayout usa columna max-w-md en móvil y dos columnas (Sidebar + contenido max-w-6xl) en lg+.

stack.md — arquitectura y spec técnica de referencia (UI tokens exactos, stack por app).
README.md — setup de la base de datos y comandos generales.