# Dos rutas a Higgsfield: CLI y MCP

> Este módulo funciona en Cowork, Codex y Antigravity porque detecta qué ruta
> hay disponible antes de generar. El resto del `SKILL.md` — elección de modelo,
> prompt engineering, references — aplica igual a las dos.

---

## Detección — hacer esto primero, siempre

```
1. ¿Hay herramientas MCP de Higgsfield disponibles?
   (nombres tipo `images_generate`, `video_generate`, `creations_show`)
   → SÍ: usar RUTA MCP. Terminar aquí.

2. ¿Está `higgsfield` en el $PATH del shell?
   → SÍ: usar RUTA CLI.

3. Ninguna de las dos
   → Instalar el CLI, o pedirle al usuario que conecte el MCP de Higgsfield.
     No inventar una tercera vía.
```

**Nunca mezclar las dos en un mismo trabajo.** Los IDs de creación no son intercambiables entre rutas.

---

## Ruta MCP — Cowork, Claude Desktop

Ventaja: sin instalación, sin login, y las imágenes se ven en el chat.

### Antes de generar

`account_balance` — confirmar créditos disponibles. Los modelos buenos cuestan.

### Imagen

`images_generate` con el prompt y los parámetros. Devuelve un `identifier`.

- Para que el usuario la vea: `creations_show(identifiers)` — **obligatorio** en clientes con interfaz. Los resultados de `creations_show` no traen `webUrl`.
- Para encadenar a video: pasar el `identifier` (o el `url` de `creations_get` / `creations_wait`), **nunca el `webUrl`**.

### Video

1. `video_plan` primero — resuelve y valida el slug del modelo
2. `video_models_list` si hace falta explorar el catálogo
3. `video_generate` con keyframes o references
4. `creations_wait` sólo si se necesita la URL final para otra herramienta

### Archivos locales del usuario

`creations_upload_show` abre un selector. **Nunca pedirle al usuario que adjunte archivos al chat** — el servidor no los lee.

### Assets reutilizables

`library_show` para que el usuario elija personaje, estilo, elemento o locación.
`library_list` para razonar sin interfaz.

### Consistencia de personaje

Soul: entrenar una vez, luego pasar la referencia en cada generación.
Ver `../higgsfield-soul-id/`.

---

## Ruta CLI — Codex, Antigravity, terminal

Ventaja: scripts, lotes, automatización.

### Bootstrap

```bash
# si no está en $PATH
curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh

# si "Session expired" / "Not authenticated"
higgsfield auth login     # interactivo — esperar confirmación del usuario
```

### Generar

```bash
higgsfield generate create <job_set_type> --prompt "..." [media] [params] --wait
```

`--wait` bloquea hasta terminar e imprime el resultado. Evita el patrón `create` → `wait` en dos pasos.

Tunables: `--wait-timeout 20m` (default 10m), `--wait-interval 5s` (default 3s).

### Descubrir modelos y parámetros

```bash
higgsfield model list --json | jq
higgsfield model get <job_set_type> --json
```

### Retrospectiva

```bash
higgsfield generate list --json
higgsfield generate get <id> --json
```

---

## Equivalencias

| Necesidad | MCP | CLI |
|---|---|---|
| Créditos | `account_balance` | `higgsfield account status` |
| Catálogo | `video_models_list` / `images_models_list` | `higgsfield model list --json` |
| Parámetros de un modelo | `video_plan` | `higgsfield model get <jst>` |
| Generar imagen | `images_generate` | `generate create <jst> --wait` |
| Generar video | `video_plan` → `video_generate` | `generate create <jst> --wait` |
| Subir archivo local | `creations_upload_show` | ruta directa en el flag |
| Esperar resultado | `creations_wait` | `--wait` |
| Mostrar al usuario | `creations_show` | imprimir la URL |

---

## Reglas comunes a ambas rutas

1. **Ser conciso.** Nada de IDs crudos ni volcados de JSON en el chat. Entregar la URL o la vista previa, más una línea de resumen.
2. **Sin jerga interna.** No narrar "consultando el costo", "haciendo polling del job".
3. **Idioma del usuario.** Detectarlo del primer mensaje y responder en él. Los argumentos técnicos (`--aspect_ratio 16:9`) se quedan en inglés.
4. **No preguntar en bloque.** Elegir un modelo por defecto sensato y preguntar una sola cosa, sólo si falta de verdad.
5. **Calidad primero.** No estimar costos ni optimizar hacia modelos baratos salvo que el usuario lo pida.
6. **Un clip generado = 15 segundos máximo.** Videos más largos se arman uniendo clips.

---

## Dónde guardar

Todo output va a la carpeta del cliente, nunca a la raíz:

```
clientes/{cliente}/outputs/imagenes/{campana}/
clientes/{cliente}/outputs/videos/{campana}/
```

Nombre: `{fecha}_{cliente}_{formato}_{tema}_v{n}.{ext}`

Y registrar la combinación producto × escenario × personaje en `outputs/entregas.md`.
