# Reformix — CLAUDE.md

> Punto de entrada para cualquier agente IA (Claude Code, Cursor, Copilot) o desarrollador humano nuevo en el proyecto. Lee esto **antes** de tocar nada.

---

## Qué es Reformix

SaaS B2B para reformistas en España. El cliente final del reformista deja sus datos en una landing, sube fotos de su cocina o baño, recibe en menos de 2 minutos una **llamada de un agente IA** desde un número fijo de su provincia, y al colgar recibe por **WhatsApp** un render IA del espacio reformado + presupuesto orientativo desglosado con el branding del reformista. El reformista recibe el lead pre-cualificado completo en su panel.

Visión 18 meses: Fase 1 SaaS B2B → Fase 2 marketplace B2C con valorador "Precio Justo".

## Documentos canónicos (la fuente de la verdad)

Antes de implementar nada, lee estos en este orden:

1. [`specs.md`](specs.md) — Requisitos formales (55 RF + 30 RNF en notación EARS, con criterios de aceptación binarios)
2. [`copy/COPY-GUIDE.md`](copy/COPY-GUIDE.md) — TODO el copy del producto. **Cero lorem ipsum permitido** en ningún sitio
3. [`design/design-system.md`](design/design-system.md) — Tokens visuales, identidad verbal, componentes
4. [`docs/dev-strategy.md`](docs/dev-strategy.md) — Orden de implementación, pipeline assets, testing, milestones
5. [`funnel.md`](funnel.md) — Diagrama del funnel punta a punta
6. [`negocio/`](negocio/) — Modelo de negocio, plan financiero, riesgos, compliance legal
7. [`devdocs/plan.md`](devdocs/plan.md) — Plan vivo de implementación
8. [`devdocs/progress.md`](devdocs/progress.md) — Estado actual del proyecto (qué está hecho, qué no)
9. [`devdocs/decisions.md`](devdocs/decisions.md) — Decisiones técnicas tomadas y por qué

## Comandos (cuando el código exista)

```bash
# Setup (una sola vez)
pnpm install
cp .env.example .env.local   # rellenar las claves
pnpm db:migrate              # migraciones Postgres con Drizzle Kit

# Desarrollo
pnpm dev                     # Next.js dev server en :3000

# Build
pnpm build                   # build de producción
pnpm start                   # corre el build en local

# Testing
pnpm test                    # vitest (unit + integration)
pnpm test:e2e                # Playwright (flujos críticos)
pnpm test:watch              # vitest watch mode

# Quality
pnpm lint                    # ESLint + autofix donde sea posible
pnpm typecheck               # tsc --noEmit
pnpm format                  # Prettier sobre todo

# Database
pnpm db:generate             # genera migration desde schema
pnpm db:migrate              # aplica migrations
pnpm db:studio               # Drizzle Studio (DB GUI)
```

> Si alguno de estos comandos no existe o no funciona, **no improvises**. Reporta el problema y arregla el setup antes de seguir.

## Stack técnico (decidido, no cuestionar sin evidencia)

| Capa | Servicio | Por qué |
|---|---|---|
| Framework | **Next.js 14** (App Router + Server Actions + API Routes) | Un único proyecto y deploy |
| Lenguaje | **TypeScript strict** | |
| UI | **Tailwind + shadcn/ui** | |
| Tokens visuales | [`design/design-tokens.css`](design/design-tokens.css) + [`design/tailwind.config.ext.js`](design/tailwind.config.ext.js) | |
| Tipografías | Instrument Serif (display) + Inter (body) + JetBrains Mono | Via `next/font/google` |
| Agente de voz | **Retell.ai** + **ElevenLabs** (voces premium ES) | |
| Telefonía | **Zadarma** (números fijos provinciales España) | |
| WhatsApp | **Evolution API** (primario) o WhatsApp Business API (respaldo) | |
| Render IA | **Nano Banana 2 / Image 2** (Google Gemini) + Replicate SDXL fallback | |
| IA texto + vision | **GPT-4o** (OpenAI) | |
| DB | **Postgres** + **Drizzle ORM** | |
| Storage | **S3** (Cloudflare R2 recomendado) | |
| Email | **SMTP** (genérico) | |
| Deploy | **Vercel** | |
| Analytics | **PostHog** | |
| Forms | react-hook-form + zod | |
| Testing | Vitest (unit + integration) + Playwright (e2e) | |

## Convenciones de código

- **TypeScript strict.** Sin `any` salvo en límites con SDK externos sin tipos.
- **Server Components por defecto.** Client Components solo cuando hace falta interactividad (`'use client'`).
- **API Routes** en `app/api/.../route.ts`. **Server Actions** para mutaciones desde formularios server-rendered.
- **Naming:**
  - Componentes: `PascalCase` (`LeadDetailCard`)
  - Hooks: `camelCase` con prefijo `use` (`useLeadStatus`)
  - Funciones: `camelCase`
  - Tipos: `PascalCase`, sin prefijo `I`
  - Constantes top-level: `SCREAMING_SNAKE_CASE`
  - Archivos componentes: `PascalCase.tsx`
  - Archivos utilidades: `kebab-case.ts`
- **Comentarios:** solo cuando el *porqué* no es obvio. Nada de comentarios que describen *qué* hace el código.
- **Imports:** usar paths absolutos con alias `@/` (configurado en `tsconfig.json`).
- **Tests:** colocados en `tests/` espejando `app/` y `lib/`, no junto al código.

## Estructura del proyecto

Ver detalle completo en [`docs/dev-strategy.md` §3](docs/dev-strategy.md). Resumen:

```
reformix/
├── app/             # Next.js App Router (marketing, app, api)
├── lib/             # Server-side (ai, voice, telephony, whatsapp, budget, db, ...)
├── components/      # Componentes React compartidos (ui, marketing, funnel, panel)
├── design/          # Design system (tokens, config)
├── copy/            # Copy guide
├── docs/            # Documentación técnica
├── devdocs/         # Plan vivo + progreso + decisiones
├── negocio/         # Documentación de negocio
├── public/          # Assets estáticos
├── raw/             # Assets fuente (git-ignored)
└── tests/           # Unit + integration + e2e
```

## Reglas operativas para el agente IA

### Siempre

1. **Lee el documento canónico relevante antes de implementar.** Si vas a tocar el form B2C, lee §RF-B en specs.md y §"Landing B2C" en COPY-GUIDE.md.
2. **Usa copy de COPY-GUIDE.md literal.** No reescribas. Si necesitas un texto que no existe, añádelo primero al copy guide, luego úsalo.
3. **Usa tokens del design system.** No hardcodees colores, espaciados o tipografías. Si falta un token, propón añadirlo en design-system.md primero.
4. **Tests primero (TDD)** para el motor de presupuesto, extracción de entidades, parsers críticos.
5. **Salida mínima:** evita `console.log` verboso. Los tests deben fallar con mensajes accionables, pasar en silencio.
6. **Commit frecuente** cada milestone (≥ 1/día de trabajo activo). Mensaje en imperativo conciso: `Add lead capture form`, no `added lead form`.
7. **Update `devdocs/progress.md`** cada vez que cierres un milestone.

### Nunca

1. **No inventes requisitos.** Si no está en specs.md, pregunta antes de implementar. Si es una mejora obvia, añádela primero a specs.md y luego implementa.
2. **No metas dependencias nuevas sin justificación documentada.** Si añades una librería, justifica en `devdocs/decisions.md`.
3. **No uses ningún proveedor de IA que no esté en el stack decidido** sin abrir una decisión explícita.
4. **No hardcodees secretos.** Todo via `process.env.*` con tipo derivado de `zod` schema.
5. **No optimices prematuramente.** Performance budget en specs.md (FCP < 2s, llamada < 2 min, pipeline < 60s). Si vas dentro de presupuesto, no toques.
6. **No instales paquetes globales** ni modifiques config del editor de otros.
7. **No commits con tests rojos** (salvo en branch personal con flag `--no-verify` documentado en el mensaje).

### Cuando dudes

- Si el specs no es claro → escribe la duda en `devdocs/decisions.md` como "pending" y pregunta.
- Si el copy no encaja → propón nueva versión en `COPY-GUIDE.md` y pide validación.
- Si el design system no cubre un caso → propón añadir token a `design-system.md`.
- Si el plan no contempla algo → updateA `devdocs/plan.md` y notifica.

## Compliance imprescindible (no negociable)

- **HTTPS** forzado siempre.
- **Consentimiento LSSI-CE** separado del RGPD en el form del cliente final (RF-LEG-01).
- **Aviso de grabación** al inicio de la llamada del agente (RF-C-12, RNF-LEG-02).
- **Consulta Lista Robinson** antes de cada llamada saliente (RF-C-03, RNF-LEG-03).
- **Identificación como IA** en la llamada (AI Act, RNF-LEG-05).
- **Horario permitido** lun-vie 9-21, sáb 9-14, no domingos (RNF-LEG-06).
- **Retención grabaciones** máximo 12 meses (RNF-LEG-04).

## Cuando el contexto se llene (reset de sesión)

1. Mata la sesión actual.
2. Inicia nueva sesión.
3. Lee `CLAUDE.md` (este archivo) → `devdocs/plan.md` → `devdocs/progress.md` → `devdocs/decisions.md`.
4. Lee el documento canónico de la superficie en la que estabas trabajando.
5. Continúa donde lo dejaste sin perder el hilo.

## Contacto / responsables

| Área | Owner | Backup |
|---|---|---|
| Producto + Coordinación + Voz | Carlos | Simon |
| Backend + IA + WhatsApp | Simon | Carlos |
| Motor de presupuesto + Dominio | Goyo | Carlos |
| UI/UX + Creativos | Antonio | Simon |