# Vale — v0.2 · Cierre pre-código (endurecimiento para el hackathon)

**Owner**: Franco · **Estado**: Locked pre-code · **Fecha**: 29 May 2026
**Acompaña a**: `vale-master-doc.md` (v0.1) y `vale-brand-kit.md`.
**Propósito**: consolidar la validación con Gemini + el endurecimiento para XPRIZE. Esta es la versión que se construye.

---

## A. Adoptado de la validación con Gemini

| # | Cambio | Por qué (lente hackathon) | Afecta |
|---|--------|---------------------------|--------|
| A1 | **Onboarding agéntico** — el agente pide fotos/servicios por WhatsApp, redacta la descripción de Google y se autoconfigura. El humano queda como QA/excepción, no como motor. | El done-for-you manual hace que parezcamos *agencia*, no IA → mata el pilar AI-native. Así mantenemos el moat de servicio Y ganamos el pilar. | Módulo 1, Flujo 3, Decisiones |
| A2 | **Function Calling como arquitectura central** — Gemini ejecuta `crear_cita()`, `actualizar_perfil_google()`, `enviar_recordatorio()`, `ofrecer_hueco()`. | Es la prueba directa de que la IA "toma decisiones clave" (pilar AI-native). Lo vuelve explícito y central. | Stack, Arquitectura, Módulo 2 |
| A3 | **Decisión autónoma visible** — Vale ofrece sola un incentivo/hueco para llenar baches de agenda (ej: "tengo libre hoy 4pm, ¿te sirve?"). | Eleva de "contestador caro" a "agente que optimiza ingresos". Es lo que los jueces quieren VER. | Módulo 4, Flujos |
| A4 | **Google Calendar como fuente de verdad** — Vale lee/escribe en el Google Calendar del dueño; la tabla `appointments` pasa a ser espejo/caché. | Resuelve el problema real del calendario (cuaderno/GCal personal) sin obligar a aprender un dashboard, y suma otro producto Google gratis. | Stack, Módulo 3, Schema |
| A5 | **Control humano vía WhatsApp** (no dashboard) — el dueño aprueba/corrige por WhatsApp. | Evita que la IA confirme sobre el horario de almuerzo del barbero y le hagamos perder confianza. | Módulo 2, Voice |

---

## B. Rechazado de Gemini (y por qué — no seguir a ciegas)

- **Gemini 1.5 Flash** → usar **Gemini 3 Flash** (la familia actual; 1.5 es de 2024). Gemini se dio data vieja de sí mismo.
- **Vertex AI Vector Search / RAG** → *overkill*. Un negocio tiene 5-15 servicios: van directo en el contexto del prompt. No montar base vectorial para datos que caben en un mensaje.
- **Firestore + Firebase Auth** → no abandonar MySQL/PHP/cPanel. El concurso **solo exige Cloud Run + Gemini**. Sumar todo el stack Google es lastre de aprendizaje en 90 días. Sesiones PHP para el panel.
- **North star "citas que terminaron en pago exitoso"** → no medible (cobran por Zelle/cash fuera del sistema; el propio Gemini lo dijo). Mantener **"citas agendadas por Vale por negocio/semana"** como norte; "completadas/cobradas" como secundaria donde se pueda.
- **Lo que Gemini NO cazó**: la trampa del **revenue related-party** (Evergreen/conocidos no cuenta como arms-length). Lo mantenemos en el radar.

---

## C. Endurecimiento propio para el hackathon (lo nuevo)

| # | Mejora | Por qué no ser contraproducente |
|---|--------|--------------------------------|
| C1 | **Modo demo testeable por jueces** — un negocio/número demo al que cualquiera le escriba y vea a Vale operar, sin onboardear un cliente real. | Las reglas exigen acceso libre para testeo hasta fin del judging. Sin esto dependés solo del video. |
| C2 | **Evidencia limpia + honestidad desde día 1** — `agent_logs` + export Stripe + related-party reportado aparte. | Los jueces verifican (piden contactos, demo en vivo, finanzas). Inflar = riesgo de DQ. Evidencia limpia gana contra los que fanfarronean. |
| C3 | **Lanzar liviano en junio, no completo en agosto** — el tiempo en producción ES evidencia. | 2 meses de logs reales + revenue creciente mes a mes pesan más que un producto pulido de última semana. |
| C4 | **Video "money shot" planeado desde ya** — capturar footage de Gemini decidiendo en prod (conversación → function call → cita → cobro). | El video de 3 min es ⅓ real del puntaje. No se improvisa el último día. |
| C5 | **Disclosure de IA al cliente final** — Vale aclara que es un asistente. | Leyes de bot-disclosure + ética. Suma calidez; esconderlo es el riesgo. |
| C6 | **Arms-length recurrente > prepagos anuales de la red** — priorizar mensual recurrente de clientes desconocidos. | Prepagos de conocidos leen como related-party y no construyen la historia de viabilidad. |

---

## D. Cambios concretos al Master Doc (aplicar en v0.2)

- **Sección 4 (Stack)**: modelo = Gemini 3 Flash vía API. Agregar **Function Calling** como patrón. Agregar **Google Calendar API** (fuente de verdad de agenda). Quitar mención a Vector Search/Firestore (no se usan).
- **Sección 5 (Arquitectura)**: el agente en Cloud Run usa Function Calling; Google Calendar entra como dependencia de agenda.
- **Sección 6 (Schema)**: `appointments` pasa a espejo/caché de Google Calendar (agregar `gcal_event_id VARCHAR(128) NULL`). Agregar `is_demo TINYINT(1) DEFAULT 0` en `tenants` para el negocio demo.
- **Sección 7 (Módulos)**: Módulo 1 → **onboarding agéntico**. Módulo 2 → control humano por WhatsApp. Módulo 4 → **decisión autónoma** (ofertas para llenar huecos). Agregar **Módulo 8 (post-MVP o dentro de 6): Modo Demo** para jueces.
- **Sección 8 (Flujos)**: Flujo 1 → explicitar function calls. Flujo 3 → onboarding lo hace el agente. Nuevo sub-flujo: oferta autónoma de hueco.
- **Sección 11 (Roadmap)**: priorizar **launch liviano en junio**; capturar footage del video desde Sprint 2; armar modo demo en Sprint 3-4.
- **Sección 12 (Riesgos)**: agregar "IA confirma sobre horario que el dueño quería" → mitigación: control por WhatsApp. Agregar "jueces no pueden testear" → mitigación: modo demo.
- **Sección 14 (Convenciones)**: Vale siempre se identifica como asistente al cliente final.

---

## E. Decisiones nuevas (log)

**[29 May] - Onboarding agéntico, no manual.** El agente configura la cuenta (fotos/servicios/descripción Google) vía WhatsApp. *Por qué*: el done-for-you manual choca con el pilar AI-native del concurso. *Alternativa descartada*: setup 100% humano (lindo para vender, malo para los jueces).

**[29 May] - Function Calling como núcleo.** Gemini ejecuta acciones, no solo conversa. *Por qué*: es la evidencia de "decisiones clave" que premia el concurso. *Alternativa*: agente solo conversacional (= "contestador caro", descartado).

**[29 May] - Google Calendar como fuente de verdad.** *Por qué*: resuelve el calendario real del dueño + suma producto Google. *Alternativa*: tabla interna como única verdad (descartada: obliga al dueño a un dashboard nuevo).

**[29 May] - Stack mínimo Google (Cloud Run + Gemini + Calendar), MySQL se queda.** *Por qué*: cumple el concurso sin lastre de aprendizaje. *Alternativa*: full Firestore/Vertex/Firebase (descartado por timing de 90 días).

**[29 May] - Lanzar liviano en junio.** *Por qué*: el tiempo en producción es evidencia para los jueces. *Alternativa*: launch completo en agosto (descartado: sin historial operativo).

---

## F. Lo que NO cambia (sigue firme)

- Nicho: SMB Latino de servicios. Distribución = moat.
- Multi-tenant (shared DB con `tenant_id`).
- Híbrido Cloud Run (agente) + cPanel/MySQL (dashboard).
- Monetización: Pro $149 / Business $299 / setup $99-199, Stripe.
- Concepto y marca: "tu negocio también vale" (ver brand kit).

---

> **Siguiente paso**: con esto bloqueado, el próximo artefacto es el **prompt de Sprint 1 para Claude Code** — el webhook Twilio → Cloud Run → Gemini (con function calling) → respuesta, sacado de este doc. Ahí se toca código.
