# Vale — Master Doc (v3)

**Producto**: Vale — el empleado AI que cualquier negocio puede contratar
**Owner**: Franco
**Estado**: Locked — listo para desarrollo
**Fecha de creación**: 29 de mayo de 2026
**Última actualización**: 30 de mayo de 2026
**Versión**: 3.0 — versión definitiva (reemplaza v1.x)

**En una frase**: creás tu empleado AI **conversando** con él. Vale te entrevista, se autoconfigura y se conecta sola a Google para atender, agendar y captar clientes — por WhatsApp y por tu web.

**Marco del concurso (Build with Gemini XPRIZE)**
- Apertura submission: 19 may 2026 · Cierre: 17 ago 2026, 1:00 PM PDT
- Evaluación: 18 ago – 15 sep 2026 · Ganadores: ~25 sep 2026
- Categoría objetivo: Small Business Services

---

## 1. Visión

Vale es el primer empleado que cualquier negocio chico (SMB) puede contratar: atiende a sus clientes 24/7 en español e inglés, los pone en Google, agenda/recibe pedidos y capta la plata que hoy se les escapa. Es un **front desk AI horizontal** — sirve a cualquier rubro y se adapta a lo que el negocio necesita.

Tres ideas centrales:

1. **Configuración conversacional (chat-first).** El dueño no llena formularios aburridos. Le **habla** a Vale —por WhatsApp o por la web— como si armara un asistente a medida hablando. Vale lo entrevista, **se autoconfigura** (personalidad, servicios, horarios, reglas) y **se conecta sola a Google** para operar de verdad. La experiencia de un asistente de chat, pero con acciones reales vía las APIs de Google.

2. **Vale guía desde el principio y automatiza todo lo que se puede.** El agente hace el trabajo (entrevista, redacta el perfil de Google, configura la agenda, arma la web). El humano solo da los toques de **identidad/permiso** que Google exige por diseño (crear su login, autorizar, verificar que el negocio es suyo).

3. **Multicanal.** El mismo cerebro atiende por **WhatsApp** (canal de adquisición principal), por el **widget de chat en la web** del negocio (nuestra plataforma) y por SMS. Una sola bandeja.

La acción concreta se adapta al rubro: barbería/clínica → agenda citas; restaurante → reservas/pedidos; tienda → pedidos/consultas; servicios a domicilio → toma datos del trabajo y pasa el lead; cualquier otro → contesta y no deja escapar a nadie.

---

## 2. Problema y solución

### Problema
Los negocios chicos pierden clientes cada vez que no contestan a tiempo (fuera de horario, ocupados, una sola persona). Cada cliente sin respuesta se va al competidor. Muchos ni aparecen en Google. Y los pocos que prueban "software" abandonan porque configurarlo es complicado y en inglés.

### Solución
Un empleado AI bilingüe que **se configura conversando** y vive donde están los clientes (WhatsApp, web, SMS): contesta al instante, califica, agenda/recibe pedidos, hace follow-up y recupera leads fríos. Se autoconfigura y se conecta a Google sin que el dueño toque una computadora.

### Por qué nosotros
Distribución: llegamos y cerramos al SMB Latino que otros no pueden adquirir (idioma, confianza, red). Ese es el moat real. La configuración conversacional baja la fricción a cero, que es donde el resto pierde al cliente.

---

## 3. Usuarios y roles

| Rol | Quién es | Qué hace | Permisos |
|-----|----------|----------|----------|
| Owner | Dueño del negocio (tenant) | Configura a Vale conversando, ve el panel, toma conversaciones | Todo en su tenant |
| Staff | Empleado del negocio | Atiende la bandeja, ve la agenda | Limitado a su tenant |
| Cliente final | Cliente del negocio | Escribe por WhatsApp/web | No accede al sistema |
| Super-admin | Operación interna | Soporte, métricas globales | Cross-tenant |

---

## 4. Stack técnico

### Canales (las 2 opciones, mismo cerebro)
- **Nuestra plataforma**: widget de chat web embebible + dashboard del dueño. Es la marca propia y el **demo testeable por los jueces** sin necesidad de WhatsApp.
- **WhatsApp** (vía Twilio): canal de adquisición principal en el mercado Latino. + SMS opcional.
- Vale es **channel-agnostic**: ambos canales entran al mismo agente y a la misma bandeja.

### Frontend
- **Interfaz de configuración conversacional** (chat-first): el dueño configura a Vale hablándole; estilo asistente de chat, server-rendered + widget JS.
- Dashboard del dueño: vanilla JS + HTML + CSS (tokens del Brand Kit), desde PHP.
- Justificación: stack liviano y conocido; el chat es la interfaz, no los forms.

### Backend
- **PHP 8.2** para dashboard, admin y APIs internas.
- **Agente conversacional**: servicio en **Google Cloud Run** que recibe mensajes de cualquier canal, llama a Gemini y ejecuta acciones vía **Function Calling**.
- API REST (JSON).

### Inteligencia (IA)
- **Gemini API** (familia 3, modelo Flash) como cerebro de Vale — al menos una llamada en producción.
- **Function Calling**: el agente ejecuta acciones reales (`configurar_negocio()`, `crear_perfil_google()`, `crear_cita()`, `tomar_pedido()`, `enviar_recordatorio()`, `ofrecer_hueco()`). Es el mecanismo por el que Vale **se autoconfigura y opera**.
- Los datos del negocio se inyectan en el contexto del prompt (no requieren base vectorial).

### Base de datos
- **MySQL 8**, InnoDB, utf8mb4_unicode_ci. Multi-tenant (shared DB con `tenant_id`).

### Integraciones (API de Google + otras)
- **Gemini API** → cerebro + Function Calling.
- **Google OAuth** → el dueño autoriza con un toque; Vale opera en su nombre.
- **Google Calendar API** → fuente de verdad de la agenda.
- **Google Business Profile API** → presencia en Maps.
- **Cloud Run / Firebase Hosting** → agente + landing generada.
- **Twilio** → WhatsApp + SMS. **Stripe** → suscripción + setup fee.

### Dependencias críticas
- Gemini, Twilio, MySQL. Sin estos tres no hay producto.

---

## 5. Arquitectura

Monolito PHP (dashboard + config) + microservicio de agente en Cloud Run. Multi-tenant. Chat síncrono; follow-ups async vía cron. El agente usa Function Calling para configurar y operar. La agenda vive en Google Calendar.

```
[Cliente / Dueño]
   |  WhatsApp · Web chat · SMS
   v
[Canal: Twilio / Widget] --> [Agente Vale en Cloud Run] --> [Gemini API + Function Calling]
                                     |
                                     |--> [MySQL en cPanel]            (config, conversaciones, leads, logs)
                                     |--> [Google OAuth / Calendar]    (agenda)
                                     +--> [Google Business Profile]    (presencia)

[Dueño / Staff] --HTTPS--> [Dashboard PHP] --> [MySQL]
                                |--> [Stripe]  (billing)
                                +--> [Cron]    (follow-ups, recuperación)
```

- **Configuración por chat** y **operación** usan el mismo agente + Function Calling.
- **Multi-tenant**: `tenant_id` en toda query. **Sync** para responder; **async** (cron) para follow-ups.

---

## 6. Modelo de datos

Schema ejecutable. Para el repo: extraer a `SCHEMA.sql`.

```sql
CREATE TABLE tenants (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(160) NOT NULL,
    business_type VARCHAR(80) NULL,
    profile_kind ENUM('cita','reserva','pedido','lead','generic') NOT NULL DEFAULT 'generic',
    owner_name VARCHAR(120) NULL,
    phone VARCHAR(32) NULL,
    whatsapp_number VARCHAR(32) NULL,
    timezone VARCHAR(48) NOT NULL DEFAULT 'America/New_York',
    locale VARCHAR(8) NOT NULL DEFAULT 'es',
    google_place_id VARCHAR(255) NULL,
    google_calendar_id VARCHAR(255) NULL,
    is_demo TINYINT(1) NOT NULL DEFAULT 0,
    onboarding_status ENUM('chatting','configuring','live') NOT NULL DEFAULT 'chatting',
    status ENUM('trial','active','past_due','canceled') NOT NULL DEFAULT 'trial',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_status (status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

CREATE TABLE users (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id BIGINT UNSIGNED NOT NULL,
    email VARCHAR(160) NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    name VARCHAR(120) NULL,
    role ENUM('owner','staff') NOT NULL DEFAULT 'owner',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uq_email (email),
    INDEX idx_tenant (tenant_id),
    FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- Config de Vale por tenant: la arma ella conversando
CREATE TABLE vale_config (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id BIGINT UNSIGNED NOT NULL,
    greeting TEXT NULL,
    persona TEXT NULL,
    hours_json JSON NULL,
    faq_json JSON NULL,
    booking_rules_json JSON NULL,
    tone VARCHAR(40) NOT NULL DEFAULT 'calido',
    default_locale VARCHAR(8) NOT NULL DEFAULT 'es',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uq_tenant (tenant_id),
    FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

CREATE TABLE services (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id BIGINT UNSIGNED NOT NULL,
    name VARCHAR(120) NOT NULL,
    duration_min INT UNSIGNED NULL,
    price_min DECIMAL(10,2) NULL,
    price_max DECIMAL(10,2) NULL,
    description VARCHAR(255) NULL,
    active TINYINT(1) NOT NULL DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_tenant (tenant_id),
    FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

CREATE TABLE contacts (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id BIGINT UNSIGNED NOT NULL,
    name VARCHAR(120) NULL,
    phone VARCHAR(32) NULL,
    channel ENUM('whatsapp','sms','web') NOT NULL DEFAULT 'whatsapp',
    locale VARCHAR(8) NULL,
    opted_out TINYINT(1) NOT NULL DEFAULT 0,
    first_seen TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_seen TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_tenant (tenant_id),
    INDEX idx_tenant_phone (tenant_id, phone),
    FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

CREATE TABLE conversations (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id BIGINT UNSIGNED NOT NULL,
    contact_id BIGINT UNSIGNED NOT NULL,
    channel ENUM('whatsapp','sms','web') NOT NULL DEFAULT 'whatsapp',
    status ENUM('open','booked','lost','closed') NOT NULL DEFAULT 'open',
    handled_by ENUM('ai','human') NOT NULL DEFAULT 'ai',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_tenant_status (tenant_id, status),
    FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE,
    FOREIGN KEY (contact_id) REFERENCES contacts(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

CREATE TABLE messages (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id BIGINT UNSIGNED NOT NULL,
    conversation_id BIGINT UNSIGNED NOT NULL,
    direction ENUM('inbound','outbound') NOT NULL,
    sender ENUM('contact','ai','human') NOT NULL,
    body TEXT NULL,
    media_url VARCHAR(512) NULL,
    model_tokens INT UNSIGNED NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_conversation (conversation_id),
    INDEX idx_tenant (tenant_id),
    FOREIGN KEY (conversation_id) REFERENCES conversations(id) ON DELETE CASCADE,
    FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

CREATE TABLE leads (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id BIGINT UNSIGNED NOT NULL,
    contact_id BIGINT UNSIGNED NOT NULL,
    conversation_id BIGINT UNSIGNED NULL,
    status ENUM('new','qualified','booked','won','lost') NOT NULL DEFAULT 'new',
    value_estimate DECIMAL(10,2) NULL,
    source VARCHAR(40) NOT NULL DEFAULT 'ai',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_tenant_status (tenant_id, status),
    FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE,
    FOREIGN KEY (contact_id) REFERENCES contacts(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- Citas / reservas (espejo de Google Calendar)
CREATE TABLE appointments (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id BIGINT UNSIGNED NOT NULL,
    contact_id BIGINT UNSIGNED NOT NULL,
    service_id BIGINT UNSIGNED NULL,
    gcal_event_id VARCHAR(128) NULL,
    scheduled_at DATETIME NOT NULL,
    status ENUM('booked','confirmed','no_show','completed','canceled') NOT NULL DEFAULT 'booked',
    source VARCHAR(40) NOT NULL DEFAULT 'ai',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_tenant_sched (tenant_id, scheduled_at),
    FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE,
    FOREIGN KEY (contact_id) REFERENCES contacts(id) ON DELETE CASCADE,
    FOREIGN KEY (service_id) REFERENCES services(id) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- Pedidos (rubros sin agenda: tienda, etc.)
CREATE TABLE orders (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id BIGINT UNSIGNED NOT NULL,
    contact_id BIGINT UNSIGNED NOT NULL,
    items_json JSON NULL,
    total DECIMAL(10,2) NULL,
    status ENUM('new','confirmed','fulfilled','canceled') NOT NULL DEFAULT 'new',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_tenant (tenant_id),
    FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE,
    FOREIGN KEY (contact_id) REFERENCES contacts(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

CREATE TABLE followups (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id BIGINT UNSIGNED NOT NULL,
    contact_id BIGINT UNSIGNED NOT NULL,
    type ENUM('reminder','recovery','reactivation','review_request') NOT NULL,
    scheduled_for DATETIME NOT NULL,
    status ENUM('pending','sent','done','skipped') NOT NULL DEFAULT 'pending',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_due (status, scheduled_for),
    INDEX idx_tenant (tenant_id),
    FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE,
    FOREIGN KEY (contact_id) REFERENCES contacts(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

CREATE TABLE subscriptions (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id BIGINT UNSIGNED NOT NULL,
    stripe_customer_id VARCHAR(64) NULL,
    stripe_subscription_id VARCHAR(64) NULL,
    tier ENUM('pro','business') NULL,
    status VARCHAR(32) NULL,
    current_period_end DATETIME NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uq_tenant (tenant_id),
    FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- EVIDENCIA: el agente operando (config + operación) en producción
CREATE TABLE agent_logs (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id BIGINT UNSIGNED NULL,
    type VARCHAR(48) NOT NULL,
    decision VARCHAR(255) NULL,
    ai_call TINYINT(1) NOT NULL DEFAULT 0,
    tokens INT UNSIGNED NULL,
    payload JSON NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_type_date (type, created_at),
    INDEX idx_tenant (tenant_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

---

## 7. Módulos MVP

1. **Configuración conversacional** *(corazón del producto)* — el dueño le habla a Vale (WhatsApp o web); Vale detecta el rubro, lo entrevista, define su `vale_config` y `services`, y se conecta a Google. Estilo "armar tu asistente charlando". Tablas: `tenants`, `vale_config`, `services`. Función IA: `configurar_negocio()`. Rol: owner / agente.
2. **Inbox multicanal** — Vale atiende por WhatsApp, web y SMS en una bandeja; la acción se adapta al rubro; el dueño controla por WhatsApp. Tablas: `contacts`, `conversations`, `messages`. Rutas: `/inbox`, `/agent/whatsapp`, `/agent/web`.
3. **Agenda / Pedidos (adaptable)** — citas/reservas en Google Calendar (rubros con agenda) o pedidos/leads en bandeja (rubros sin agenda). Tablas: `appointments`, `orders`, `leads`, `services`.
4. **Follow-up & Recuperación + decisión autónoma** — persigue no-shows y leads fríos; ofrece sola huecos/incentivos. Tablas: `followups`, `leads`. Cron.
5. **Presencia Google** — Vale crea/optimiza el perfil de Business Profile + landing generada. Tablas: `tenants`.
6. **Dashboard, Métricas & Demo** — panel con la métrica norte + evidencia (`agent_logs`); incluye tenant **demo** público para que los jueces prueben sin onboarding. Tablas: `leads`, `appointments`, `orders`, `agent_logs`.
7. **Billing** — Stripe suscripción + setup fee. Tablas: `subscriptions`.

---

## 8. Flujos críticos

```
Flujo 0: Configuración conversacional (el dueño crea a Vale charlando)
Trigger: el dueño inicia el chat (WhatsApp o web)
1. Vale se presenta y pregunta el rubro -> detecta profile_kind
2. Lo entrevista: nombre, servicios/menú/productos, horarios, tono
3. Gemini (Function Calling) llama configurar_negocio() -> crea tenant + vale_config + services
4. Pide conectar Google (OAuth, un toque) -> Calendar + Business Profile
5. crear_perfil_google() redacta y prepara la ficha; el dueño verifica (codigo Google)
6. Genera la landing y la publica; conecta el canal (WhatsApp/web)
7. onboarding_status -> live; Vale manda un mensaje de prueba
Resultado: negocio configurado por la IA, sin formularios
Errores: dato faltante -> repregunta; Gmail inexistente -> guia a crearlo (no la crea)
```

```
Flujo 1: Cliente escribe y Vale lo atiende (operación)
1. El mensaje entra por el canal -> Agente (Cloud Run)
2. Resuelve tenant + busca/crea contact + conversation
3. Gemini decide y ejecuta via Function Calling segun el rubro
   (crear_cita / tomar_pedido / capturar_lead)
4. Guarda message + agent_log (ai_call, tokens); responde por el canal
5. Notifica al dueno; Vale se identifica como asistente
Errores: Gemini down -> encolar + avisar; sin slot -> alternativas
```

```
Flujo 2: Recuperacion + decision autonoma
Cron revisa followups -> Gemini arma el mensaje -> si hay huecos, ofrece incentivo
-> envia -> si responde, reabre conversacion. Opt-out respetado (TCPA).
```

```
Flujo 3: Cobro
Tiers -> Stripe Checkout (sin tarjetas a mano) -> webhook -> status=active.
```

---

## 9. UI/UX guidelines

*(Brand Kit de Vale — ver `vale-brand-kit.md`.)*

- **Interfaz de config = chat.** Estilo asistente conversacional: una sola caja de chat cálida, con respuestas rápidas y acciones (botones de "Conectar Google", "Aprobar perfil"). Nada de wizards de 10 forms.
- **Dashboard** para ver bandeja multicanal, agenda/pedidos, métricas y evidencia.
- Paleta: Barro `#A8331A`, Oro `#E0A33E`, Crema `#FBF6EE`, Tinta `#221C18`, Verde `#1E7A4D`.
- Tipografía: Fraunces (titulares) + Hanken Grotesk (texto), base 16px.
- **Mobile-first** (el dueño vive en el celular). Breakpoints 360/768/1024.
- Tono: cálido, humano; Vale siempre se identifica como asistente.

---

## 10. Monetización

| Tier | Precio | Incluye | Pago |
|------|--------|---------|------|
| Trial | $0 | Todo Pro 7-14 días | — |
| Pro | $149/mo | WhatsApp + web, agenda/pedidos, follow-ups | Stripe |
| Business | $299/mo | + SMS, recuperación full, presencia Google | Stripe |
| Setup | $99-199 | Configuración asistida | Stripe |

Default USD. Anclaje: no-brainer vs answering service humano ($300-1500/mo). Setup fee acelera revenue y filtra serios. Prioridad: recurrente **arms-length** (cuenta para viabilidad); related-party se reporta aparte.

---

## 11. Roadmap por sprints

Hasta el 17 ago, con buffer final. Principio: **lanzar liviano temprano**.

- **Sprint 0 (30 may–1 jun)** — provisión (Gemini, Cloud Run, Firebase, Twilio, Stripe test) + 1 negocio piloto atendido a mano. *Done*: un cliente real recibe respuesta.
- **Sprint 1 (2–8 jun)** — core: webhook → Gemini → respuesta, multi-tenant, `agent_logs`. *Done*: Vale responde sola.
- **Sprint 2 (9–15 jun)** — **configuración conversacional** + Function Calling + agenda Google Calendar + dashboard métrica. Capturar footage para el video. *Done*: el dueño configura a Vale charlando y ella agenda.
- **Sprint 3 (16–22 jun)** — recuperación + presencia Google + **modo demo** + canal web. *Done*: follow-ups, negocio en Maps, demo testeable.
- **Sprint 4 (23–29 jun)** — billing Stripe. *Done*: primer cliente **pago arms-length**.
- **Sprint 5 (30 jun–10 ago)** — growth: adquisición, 10-30 negocios, revenue mes a mes, testimonios y evidencia.
- **Sprint 6 (11–17 ago)** — submission: video 3 min, narrativa 500-1000, evidencia, repo limpio. *Done*: enviado antes del 17 ago 1pm PDT.

---

## 12. Riesgos técnicos

| Riesgo | Prob. | Impacto | Mitigación |
|--------|-------|---------|------------|
| IA alucina al configurar/agendar | Media | Alto | Validación server-side; confirmar antes de cerrar; control por WhatsApp |
| Config conversacional malinterpreta al dueño | Media | Medio | Vale repregunta y muestra resumen para aprobar antes de aplicar |
| Aislamiento multi-tenant | Media | Crítico | `tenant_id` en TODA query; tests de scoping |
| Opt-out / mensajes salientes (TCPA) | Media | Alto | Respetar STOP; `opted_out`; consentimiento al onboarding |
| Verificación Google Business Profile | Alta | Medio | Paso guiado; no prometer 100% automático |
| Jueces no pueden testear | Media | Alto | Tenant demo público `/demo` |
| Dependencia externa cae | Baja | Alto | Encolar + reintentar; degradar elegante |

---

## 13. Decisiones tomadas

**[30 May 2026] - Configuración conversacional (chat-first), no formularios.** Por qué: baja la fricción a cero (donde el resto pierde al SMB) y es la prueba viva de un agente AI que se autoconfigura. Alternativa: wizard de forms (descartado: fricción + no luce AI-native).

**[29 May 2026] - Gemini con Function Calling como núcleo.** El agente ejecuta acciones (config + operación), no solo conversa. Alternativa: agente solo conversacional (descartado: "contestador caro").

**[30 May 2026] - Producto horizontal (cualquier SMB), acción adaptable.** Núcleo universal; acción según rubro. GTM por beachhead para no diluir el demo. Alternativa: vertical de citas (descartado: angosto/solapa con Turno).

**[30 May 2026] - Multicanal: plataforma propia (web + dashboard) + WhatsApp.** Mismo agente; web = demo testeable, WhatsApp = adquisición. Alternativa: solo WhatsApp (descartado).

**[29 May 2026] - Google Calendar fuente de verdad / Multi-tenant / Híbrido Cloud Run + cPanel / Lanzar liviano.** (Ver historial; sin cambios.)

---

## 14. Convenciones de código

- snake_case en DB/PHP, camelCase en JS.
- No localStorage · Clean URLs (.htaccess) · PDO prepared statements · `htmlspecialchars` · `session_regenerate_id()` en login.
- `tenant_id` en toda query de datos de negocio.
- Secretos en variables de entorno, nunca en el repo.
- Vale siempre se identifica como asistente ante el cliente final.
- Estructura: `/public /app(/controllers /models /services /views) /agent /cron /config /docs SCHEMA.sql`

---

## 15. Próximos pasos

1. Provisión Google + 1 negocio piloto atendido a mano — Franco / esta semana (Sprint 0).
2. Repo nuevo + `SCHEMA.sql` + tokens del Brand Kit — Equipo / Sprint 1.
3. Webhook del agente (canal → Cloud Run → Gemini → respuesta) — Equipo / Sprint 1.
4. **Configuración conversacional** con Function Calling (`configurar_negocio`) — Equipo / Sprint 2.
5. Instrumentar `agent_logs` desde el día uno (evidencia) — Equipo / Sprint 1.

---

> **Repo**: partir en `MASTER.md` + `SCHEMA.sql` + `ROADMAP.md`. Este v3 reemplaza versiones anteriores.