feat: add AGENTS.md for project documentation and guidelines

AGENTS.md

@@ -0,0 +1,44 @@
+# 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"`.
+
+## Comandos
+
+- `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:*`.
+
+## Estructura y fronteras
+
+- `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.
+
+## Gotchas operativos
+
+- **Prisma requiere `apps/api/.env`** (con `DATABASE_URL`) para `generate`/`validate`/`migrate`; sin él falla con `P1012`. Está gitignoreado; 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).
+
+## Convenciones repo-específicas
+
+- **Frontend en español**: copy de UI, comentarios y textos en español.
+- **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+`.
+
+## Fuentes de contexto
+
+- `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.