# Contribuir

JARVIS es software libre (GPL-3.0) y se agradecen los commits. Esta guía dice
cómo está montado, cómo probarlo y cómo añadir lo más común. Las ideas acotadas
están en [ROADMAP.md](ROADMAP.md).

## Cómo está montado

```
nucleo/jarvis.py     el bucle: oír → pensar → hacer → hablar
nucleo/oido/         whisper.cpp (STT) y la captura del micrófono
nucleo/cerebro/      Ollama, tool-calling, el RAG y la elección de modelo
nucleo/boca/         Piper / voz clonada (TTS)
nucleo/manos/        las acciones, el diario, el sudo, la fonética
nucleo/cara/         el panel web (servidor WebSocket + HUD en cara/hud/)
nucleo/saber/        el RAG: indexa, busca, y enriquece/ para mejorarlo
config/              scripts: modelo, voz, whisper, ventanas
```

Nada de esto necesita compilar: es Python, bash y una página web. Se edita y se
prueba en el sitio.

## Probarlo

```bash
./install.sh              # entorno, modelo de Ollama, lanzador de escritorio
./nucleo/arranca.sh       # el asistente y el panel en 127.0.0.1
```

El panel se puede abrir **sin arrancar nada**, para trabajar el diseño:
`nucleo/cara/hud/index.html` en un navegador se llena solo con datos de ejemplo.

Hay dos suites de comprobaciones (`nucleo/pruebas/`) y un eval del RAG
(`nucleo/saber/enriquece/evalua.py`, mide `hit@k`). Si tocas el RAG, corre el
eval y pon los números en el commit.

## Añadir una acción

Una acción es una entrada en `nucleo/datos/acciones.json`:

```json
{
  "id": "brillo_sube",
  "grupo": "sistema",
  "frases": ["sube el brillo", "más brillo", "más luz"],
  "acuse": "Voy, señor.",
  "comando": "brightnessctl set +10%",
  "host": true,
  "respuesta": "Brillo al {campo1}, señor.",
  "confirmar": false,
  "captura": false
}
```

- `frases`: cómo se dice, con variantes. Se emparejan ANTES de llamar al modelo,
  así que una acción del catálogo es instantánea.
- `comando`: shell. `{campoN}` en `respuesta` es el enésimo campo de la salida.
- `confirmar: true` para lo que borra o cambia; `captura: true` si necesita un
  argumento hablado ("busca el fichero **X**").

Si el comando depende de una herramienta que puede no estar, que degrade con
gracia (mira `config/ventanas.sh`).

## Probar con otro modelo

```bash
JARVIS_MODELO=qwen3.5:9b ./nucleo/arranca.sh
```

O, en marcha, dile a JARVIS "usa un modelo más potente" (usa la herramienta
`elegir_modelo`). Para medir si un modelo hace bien el tool-calling, mira el
patrón del eval del RAG y adáptalo.

## Un backend de ventanas nuevo (Wayland u otro)

`config/ventanas-wayland.sh` es el ejemplo: detecta el compositor y traduce los
verbos (maximiza, izquierda, centro...) a sus órdenes. Para KDE, GNOME Wayland u
otro, se copia el patrón. Actúa sobre la ventana ACTIVA (en Wayland no se mueven
ventanas ajenas). Prueba cada orden en tu compositor antes del commit.

## Estilo

- Registro técnico y conciso, en castellano. Los comentarios explican el
  **porqué**, no el qué.
- Los commits describen la decisión, no solo el cambio.
- Sin datos personales en el repo: los apuntes indexados, el diario y la voz de
  referencia son del usuario (ver [PRIVACIDAD.md](PRIVACIDAD.md)).