# VillApps — puesta en marcha para la IA del dueño

Eres la IA de un dueño de negocio que quiere usar VillApps
(https://villapps.com): una app de escritorio donde tú le construyes las
pantallas de su negocio, platicando. Esta guía te dice cómo dejarle todo
funcionando. Habla con el dueño en su idioma (this guide is in Spanish;
speak to the owner in whatever language they use). Haz tú todo lo que se
pueda hacer desde la terminal y pídele solo lo que únicamente él puede
hacer: los avisos del sistema y el código que llega a su correo.

Todo esto ocurre en la computadora del dueño, y esta guía la ejecuta
**la IA que quedará conectada a VillApps**: un agente con terminal en la
máquina del dueño, capaz de registrar la conexión MCP para sí mismo
(VillApps soporta hoy Claude Code, OpenAI Codex, Gemini CLI, GitHub
Copilot CLI y VS Code —las cinco probadas contra su herramienta real—,
más Cursor y Grok Build con su configuración documentada; el paso 3 trae
la de cada una). Si tú no eres
un agente así —eres un chat (claude.ai web, la app de chat de Claude,
ChatGPT web) o una tarea en la nube—, no ejecutes esta guía, **aunque tu
entorno pueda correr comandos o leer archivos en su computadora**: la
conexión que registres no te configuraría a ti, tu conversación vive
fuera de su máquina (leer `~/.villapps/mcp.json` o citar su token ahí
los saca de su dispositivo) y cablearla por otra vía
(`claude_desktop_config.json`, `mcp-remote` o equivalentes) queda fuera
de soporte y le deja un arreglo frágil. En ese caso **no hagas nada**:
ni comandos, ni lectura de archivos, ni configuración; tampoco le dictes
los pasos como lista manual, ni le pidas el token, ni lo repitas si él
ya lo pegó en el chat. Respóndele únicamente esto, en sus palabras, y
detente:

> Esto lo hace una IA con terminal en tu computadora, no este chat.
> VillApps funciona con la IA de agente que ya uses —Claude Code, Codex,
> Gemini CLI, Copilot CLI o VS Code—. Ábrela (si no tienes ninguna,
> contrata el plan de la que prefieras e instala su herramienta de
> terminal) y pégale esta
> instrucción: «Lee
> https://villapps.com/primeros-pasos/ia.md y déjame VillApps
> funcionando: conéctate, explícame cómo puedo aprovechar VillApps en mi
> negocio y ayúdame a construir mi primera pantalla. Haz tú todo lo que
> puedas; pídeme solo lo que únicamente yo pueda hacer.»

## 0. ¿Qué falta?

- Si ya tienes conectadas las herramientas MCP `villapps`, salta al paso 4 —
  pero confirma de pasada que el dueño ya tiene su Cuenta VillApps (paso 2);
  si no la tiene, ese pendiente va primero.
- Si en la carpeta del usuario existe `.villapps/mcp.json`, la app ya está
  instalada y abierta al menos una vez: salta al paso 2. Si no sabes si el
  dueño ya tiene cuenta, pregúntaselo («¿ya ligaste tu Cuenta VillApps?»);
  su respuesta decide si sigues en el 2 o directo en el 3.

## 1. Instalar VillApps

Requisitos: macOS 13 o más nuevo (Apple Silicon o Intel), o Windows 10/11
de 64 bits. No hay nada más que instalar: la base de datos viene incluida.

**Mac** — el feed publica la versión vigente:

1. Descarga https://villapps.com/descargas/latest-mac.yml y toma el nombre
   del `.dmg` (campo `url:` o `path:`).
2. Descarga `https://villapps.com/descargas/<ese-archivo>`.
3. Monta el .dmg (`hdiutil attach`), copia `VillApps.app` a
   `/Applications`, desmonta y abre la app (`open -a VillApps`).
4. Si macOS la bloquea al abrirla por primera vez, dile al dueño: Ajustes →
   Privacidad y seguridad → «Abrir de todos modos».

**Windows**:

1. Descarga https://villapps.com/descargas/latest.yml y toma el nombre del
   `.exe` (campo `url:` o `path:`).
2. Descarga `https://villapps.com/descargas/<ese-archivo>` y ejecútalo. Si
   SmartScreen avisa, el dueño elige «Más información → Ejecutar de todas
   formas». La instalación termina sola y VillApps se abre.

## 2. Cuenta VillApps (esto solo lo hace el dueño)

Al abrir VillApps sin proyectos, la pantalla de inicio es **un solo hilo de
cuatro pasos numerados** —① Cuenta, ② Conecta tu IA, ③ ¿Para qué la
usarías?, ④ Tu IA construye— con palomita en lo que ya quedó y retomable si
cierra la app a medias.

Pídele que haga el paso ①: escriba su correo, elija su contraseña ahí mismo
y capture el código de 6 dígitos que le llega al correo (vence en 15
minutos; si no llega, que revise el correo no deseado). La contraseña NO
llega por correo: es la que él eligió en la app. Crear la cuenta no pide
tarjeta: incluye una prueba gratis de 30 días con todo funcionando. La IA
—tú— es suya: su cuenta y su plan los contrata con tu proveedor, no con
VillApps. Espera a que te confirme; la señal de que quedó es que el ①
aparece palomeado con su correo y su prueba gratis, y el hilo pasa solo al
②.

## 3. Conectarte a VillApps

La app sirve en `http://127.0.0.1:<puerto>`, que solo existe en la máquina
del dueño: por eso esta conexión únicamente funciona desde una sesión local
(desde la nube es inalcanzable, y agregar sus carpetas a una sesión en la
nube subiría archivos —incluido el token— fuera de su dispositivo).

1. Con la app abierta, lee `~/.villapps/mcp.json` (en Windows,
   `C:\Users\<usuario>\.villapps\mcp.json`): trae `puerto` y `token`. Si tu
   entorno te pide permiso para leer esa carpeta, es el diálogo normal de
   permisos de tu propio harness, no algo que pida VillApps; solicita
   acceso solo a `~/.villapps`, nunca a carpetas más amplias del dueño.
2. El dueño también puede conectarte **desde la app, con un botón**: es el
   paso ② de su hilo de arranque (y la portada del proyecto, si ya tiene
   apps), donde elige su IA, pulsa Conectar y comprueba. Si él ya lo hizo, tu
   conexión ya está escrita: salta a verificarla. Si no, hazlo tú aquí —
   es más rápido que mandarlo a buscar una pantalla.
3. Pregúntale al dueño en qué carpeta quiere trabajar contigo — nunca
   escojas una por tu cuenta — y trabaja ahí. Avísale que tu harness le
   pedirá aprobar el comando de conexión: es el diálogo normal de tu
   entorno, no algo de VillApps. Ejecuta **el de tu herramienta**,
   sustituyendo `<puerto>` y `<token>` por lo que leíste:

   - **Claude Code**
     ```
     claude mcp add --transport http --scope user villapps http://127.0.0.1:<puerto>/mcp --header "Authorization: Bearer <token>"
     ```
   - **OpenAI Codex** — su comando no admite header, así que la entrada se
     escribe en `~/.codex/config.toml` (el token va literal; **no** uses
     variables de entorno ni `launchctl setenv`):
     ```toml
     [mcp_servers.villapps]
     url = "http://127.0.0.1:<puerto>/mcp"
     http_headers = { Authorization = "Bearer <token>" }
     ```
   - **Gemini CLI**
     ```
     gemini mcp add --scope user --transport http --header "Authorization: Bearer <token>" villapps http://127.0.0.1:<puerto>/mcp
     ```
   - **GitHub Copilot CLI**
     ```
     copilot mcp add --transport http --header "Authorization: Bearer <token>" villapps http://127.0.0.1:<puerto>/mcp
     ```
   - **VS Code**
     ```
     code --add-mcp '{"name":"villapps","type":"http","url":"http://127.0.0.1:<puerto>/mcp","headers":{"Authorization":"Bearer <token>"}}'
     ```
   - **Cursor** — `~/.cursor/mcp.json`; **Grok Build** — `~/.grok/config.toml`.
     Ambas están documentadas por su fabricante pero no probadas por
     VillApps: si algo falla ahí, es un folio nuevo.

   `--scope user` (y su equivalente) deja la conexión disponible desde
   cualquier carpeta, no solo la del proyecto.
4. Verifica que `villapps` aparece: `claude mcp list`, `codex mcp get
   villapps`, `gemini mcp list`, `copilot mcp get villapps`, o la lista de
   servidores MCP de VS Code.
   - Si `villapps` ya existe con puerto o token viejos, retíralo (`… mcp
     remove villapps`) y vuelve a agregarlo con los datos del archivo.
   - Si aparece pero no conecta, casi siempre VillApps está cerrada: pide
     al dueño abrirla y verifica de nuevo. El puerto y el token se
     conservan entre reinicios de la app; si aun así no conecta, relee
     `mcp.json` por si el puerto cambió y re-agrega.
   - En **Gemini CLI**, un `villapps` en `Disabled` con el aviso de carpeta
     no confiable no es un fallo de registro: pídele al dueño `/trust` en la
     carpeta donde trabajen.
   - En **VS Code** y **Copilot CLI**, la herramienta pedirá confirmación
     antes de usar el servidor. Es peaje suyo, no de VillApps: anúnciaselo
     al dueño en vez de dejar que parezca una falla.
5. El token es local y privado: úsalo en el comando y no lo copies a
   archivos del proyecto ni lo repitas en pantalla.
6. Las herramientas cargan al arrancar cada sesión: si la conexión la
   acabas de registrar en esta misma sesión, todavía no las tienes — es lo
   normal, no una falla. Antes de pedir el reinicio, haz la explicación
   del paso 4 (no necesita las herramientas). Luego dile al dueño que
   cierre y vuelva a abrir su IA, y déjale lista la frase para
   retomar: «Ya conectamos VillApps y tengo cuenta. Lee
   https://villapps.com/primeros-pasos/ia.md y ve directo al paso 4:
   ayúdame a construir mi primera pantalla.» La conexión ya quedó guardada
   y no se repite. (Copilot CLI no necesita reinicio.)

## 4. Explicar primero, construir después

Con la conexión activa, lee el recurso MCP `villapps://contrato` y
síguelo: es tu contrato como constructor. Lee también
`villapps://proposito`: si el dueño ya contestó el paso ③ de su hilo de
arranque, ahí está —con sus palabras— para qué quiere VillApps, y esa es tu
entrada a la plática. Si aún no lo contesta, el recurso te lo dice; no
inventes un giro.

Lo primero que el dueño recibe de ti es una **explicación de qué podría
hacer con VillApps y hasta dónde llega**, en los términos de SU negocio —
no un cuestionario («¿a qué te dedicas? ¿retail? ¿quieres un reporte de
Excel?») ni una pantalla construida en frío. Usa lo que ya sepas de él
por la conversación y por `villapps://proposito`; si no sabes a qué se
dedica, esa única pregunta vale, y a su respuesta le sigue la explicación
completa, no otra pregunta. La explicación trae:

- Qué es: tú le construyes las pantallas de su negocio —capturar,
  consultar, reportar— y le aparecen solas en su VillApps, sin que él
  programe ni configure nada.
- Tres o cuatro ejemplos concretos de su giro, no una lista genérica: a
  una tienda, inventario con alertas de mínimos, ventas del día y
  apartados; a quien da servicios, clientes con citas y cobranza
  pendiente; a quien vive en Excel, esos mismos Excel vueltos pantallas
  con captura y reportes.
- El alcance: se empieza por una pantalla, la ajusta contigo hasta que
  quede, y de ahí crecen personas y permisos, compartir la app con su
  equipo y declararla en producción — todo platicando.

Cuando él reaccione y escoja («eso de la cobranza me urge»), crea el
proyecto y constrúyele esa pantalla; le aparece sola en VillApps.

Mientras construyes, su hilo de arranque está en el paso ④ «Tu IA
construye» y palomea solo, con lo que tú hagas por MCP: que hablaste con la
app, que creaste su primer proyecto y que instalaste la primera pantalla.
Pídele que deje VillApps abierta mientras tanto (hablas con la app a través
de ella; cerrada no la encuentras). Cuando el proyecto exista, su portada
dirá «Listo: tu IA creó ⟨proyecto⟩» con el botón para abrirlo: dile que lo
abra cuando la primera pantalla esté — abrirlo termina su arranque y desde
ahí VillApps es la de siempre. No le pidas que cree el proyecto a mano si tú
ya lo creaste (ni al revés): una sola de las dos vías.

## 5. Mensajes entre contactos y el buzón de la red

Los contactos de la red del dueño se escriben, se mandan archivos y sus
IAs se piden cosas (`solicitar`, `villapps://bandeja`), todo cerrado de
extremo a extremo y directo entre computadoras. Si el destinatario no
está, el mensaje espera hasta que los dos coincidan en línea. Cuando el
dueño tenga una computadora dedicada y siempre encendida, ofrécele
ponerla de **buzón de la red**: desde ESA máquina, con su cuenta y sin
proyecto abierto, `buzon_red` con `accion: 'activar'` (o la tarjeta
«Buzón de la red» en Cuenta VillApps). Custodia los sobres cerrados que
no pudieron entregarse y los entrega sola cuando el otro entra; arranca
con el sistema aunque nadie inicie sesión; nunca lee lo que guarda. Un
buzón por cuenta; retirarlo con sobres en custodia pide confirmar.

¿Atorados en algo del servicio? Que el dueño escriba a
cuentas@villapps.com.