> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Proyectos y canales

> Crea y administra proyectos (asistentes de IA), sube archivos de conocimiento, conecta canales (Web, WhatsApp, Facebook, Instagram) y sincroniza los workflows de un proyecto entre tu máquina y el servidor.

Un **proyecto** es un asistente de IA con sus archivos de conocimiento, sus
canales y sus workflows. El subcomando `jelou project` administra el ciclo de
vida del proyecto; `jelou channels` conecta el proyecto a canales de
mensajería; y los comandos de sincronización (`link`, `pull`, `status`, `push`,
`incoming`) llevan los workflows del proyecto a archivos locales y de vuelta.

<Note>
  "Brain" es el nombre legacy de "project". `--brain` se acepta como alias de
  `--project` en `jelou link` y `jelou channels`, y varios campos a nivel de API
  conservan el nombre `brain` — pero el nombre canónico es **project**.
</Note>

## `jelou project`

| Subcomando                        | Descripción                                             |
| --------------------------------- | ------------------------------------------------------- |
| `list`                            | Lista todos los proyectos (paginado)                    |
| `show <id>`                       | Muestra detalles del proyecto y conteo de archivos      |
| `create "<nombre>"`               | Crea un proyecto nuevo                                  |
| `update <id>`                     | Actualiza nombre o descripción                          |
| `delete <id>`                     | Elimina un proyecto (en cascada, irreversible)          |
| `publish <id>`                    | Publica el borrador a una rama de producción            |
| `history <id>`                    | Historial de versiones / commits del proyecto           |
| `restore <id> <commit>`           | Restaura a un commit anterior o lo carga en el borrador |
| `knowledge list <id>`             | Lista los archivos de conocimiento                      |
| `knowledge upload <id> <archivo>` | Sube un archivo de conocimiento                         |
| `knowledge delete <id> <file-id>` | Elimina un archivo de conocimiento                      |

```bash theme={null}
jelou project list --page 2 --limit 5 --json
jelou project show 01H2XCEJQTG2H5V5NKCYW3J7Z2
jelou project create "Soporte de Producto" --description "IA de atención al cliente"
jelou project update 01H2XCEJQTG2H5V5NKCYW3J7Z2 --name "Soporte v2"
jelou project delete 01H2XCEJQTG2H5V5NKCYW3J7Z2 --yes
```

### Conocimiento

Sube documentos para que el asistente los use como base de conocimiento.
Formatos soportados: PDF, TXT, CSV (máx. 2 MB por archivo).

```bash theme={null}
jelou project knowledge upload 01H2XCEJQTG2H5V5NKCYW3J7Z2 ./catalogo.pdf
jelou project knowledge upload 01H2XCEJQTG2H5V5NKCYW3J7Z2 ./faq.txt --name "FAQ"
jelou project knowledge list 01H2XCEJQTG2H5V5NKCYW3J7Z2
jelou project knowledge delete 01H2XCEJQTG2H5V5NKCYW3J7Z2 file_01H2XCEJQ --yes
```

### Publicar y restaurar

```bash theme={null}
jelou project publish 01H2XCEJQTG2H5V5NKCYW3J7Z2 --branch master --commit-name "Lanzamiento v2" --yes
jelou project history 01H2XCEJQTG2H5V5NKCYW3J7Z2 --detailed --limit 50
jelou project restore 01H2XCEJQTG2H5V5NKCYW3J7Z2 abc123def456 --into-draft --yes
```

<Warning>
  `project delete` es **en cascada e irreversible**: elimina el proyecto, su
  workspace, su skill por defecto y su canal sandbox. `publish` y `restore`
  afectan producción de inmediato, y borrar un archivo de conocimiento dispara un
  re-entrenamiento (las respuestas pueden cambiar). Ejecuta `project show` y
  confirma antes de operaciones destructivas.
</Warning>

## `jelou channels`

Conecta un proyecto a canales de mensajería.

| Subcomando                                              | Descripción                                                                                          |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `list --project <id>`                                   | Lista los canales de un proyecto (filtra por `--type`)                                               |
| `show <id>`                                             | Muestra el detalle completo de un canal, incluido el `pageId` de Meta para Facebook/Instagram        |
| `activate whatsapp`                                     | Conecta un número de WhatsApp mediante el flujo de inicio de sesión de Meta (sin pegar credenciales) |
| `create --project <id> --type web --name "<n>"`         | Crea un canal (por CLI, solo `--type web`)                                                           |
| `connect <channel-id> --to <bot\|agent\|pma> --id <id>` | Enruta el canal a un bot, agente o PMA                                                               |
| `flows --bot-id <id>`                                   | Lista los WhatsApp Flows disponibles para un bot                                                     |
| `testers`                                               | Administra la whitelist de números de prueba del sandbox de WhatsApp                                 |

Por CLI, `channels create` solo soporta `--type web` (widget web). Los canales
de WhatsApp, Facebook e Instagram requieren OAuth: WhatsApp se conecta con
`jelou channels activate` (inicio de sesión de Meta, sin pegar credenciales),
mientras que Facebook e Instagram solo se pueden crear desde el dashboard.

```bash theme={null}
jelou channels list --project 01H2XCEJQTG2H5V5NKCYW3J7Z2 --exclude-sandbox
jelou channels list --type Facebook_Feed          # bandeja de comentarios de la página, no el Messenger
jelou channels create --project 01H2XCEJQTG2H5V5NKCYW3J7Z2 --type web --name "Widget del sitio"
jelou channels activate whatsapp --project 01H2XCEJQTG2H5V5NKCYW3J7Z2
jelou channels connect 01H2XCEJQTG2H5V5NKCYW3J7Z2 --to bot --id bot_01H2XCEJQ
```

<Note>
  `--type` es exacto: `Facebook` son solo los DMs de Messenger, `Facebook_Feed` es
  la bandeja de comentarios de la página (antes invisible para el CLI); mismo
  patrón para `Instagram`/`Instagram_Feed`. Conectar una página de Facebook es
  solo la mitad del trabajo — cada skill necesita su propio canal de Facebook,
  agregado desde Studio, o el motor no encuentra a qué workflow enrutar ese
  tráfico y nada responde.
</Note>

<Warning>
  `channels connect` **sobrescribe sin avisar**: si el canal ya tenía una
  conexión, re-apuntarlo enruta usuarios reales al nuevo destino en el siguiente
  mensaje entrante. Verifica ambos destinos antes de conectar.
</Warning>

## Sincronizar workflows (local ↔ servidor)

Para editar los workflows de un proyecto como archivos locales, primero vincula
el directorio al proyecto con `jelou link`, luego baja (`pull`), revisa
(`status`), edita y sube (`push`).

### `jelou link`

```bash theme={null}
jelou link                                   # interactivo
jelou link --project 01H2XCEJQTG2H5V5NKCYW3J7Z2
jelou link --project 01H2XCEJQTG2H5V5NKCYW3J7Z2 --authoring ts   # fija el modo de authoring (ts|json) en jelou.yml
jelou link --status --json                   # muestra el vínculo sin llamar a la API
```

Escribe `jelou.yml` (vínculo compartido por el equipo — versiónalo en git) y
`.jelou/state.json` (estado local — añádelo a `.gitignore`, el CLI lo hace
automáticamente).

<Warning>
  `jelou link`, `pull` y `push` escriben archivos locales. Requieren un worktree
  git limpio o un directorio vacío. Si el directorio está sucio o no versionado,
  el CLI se detiene; usa `--allow-dirty` solo tras confirmar.
</Warning>

### `pull`, `status`, `push`

```bash theme={null}
jelou pull                       # baja todos los workflows a workflows/<slug>.<canal>.json
jelou pull --check --json        # dry-run: resumen sin escribir
jelou pull --workflow saludo     # un solo workflow
jelou pull --quiet --json        # sin ruido informativo en stderr (uso por agentes)

jelou status                     # diff local vs lockfile
jelou status --check-remote      # además compara contra el servidor (detecta drift)
jelou status --quiet --json      # solo muestra entradas no-limpias (CI-friendly)

jelou push                       # sube las ediciones locales
jelou push --dry-run --json      # solo muestra el diff, no despacha
jelou push --workflow saludo     # un solo workflow
jelou push --force               # omite la verificación de drift del lockfile (capa 1)
jelou push --repair-from .jelou/journals/2026-05-03T20-45-52-000Z.json   # reintenta un journal incompleto o fallido
```

<Tip>
  ¿Necesitas el panorama completo, no solo el estado de sync? `jelou context --agent`
  entrega en una sola llamada la misma información de drift que `status` más
  identidad, allowlist de modelos de IA, nombres de secretos, inventario de
  bases de datos y el catálogo de tipos de nodo — reemplaza la secuencia
  `status` + `secret list` + `models list` + `databases list` +
  `workflow node-spec --list` para agentes que quieren todo el contexto de
  arranque de una sola vez.
</Tip>

### `jelou incoming` — resolver ediciones concurrentes

Si un `pull` detecta que el servidor cambió un workflow que también editaste
local, preserva la versión del servidor bajo `.jelou/incoming/` y sale con
código 7. Resuelve cada artefacto antes de volver a hacer `pull`:

```bash theme={null}
jelou incoming list
jelou incoming diff --workflow wf_01H2XCEJQ
jelou incoming accept-server --workflow wf_01H2XCEJQ --channel default   # adopta el servidor
jelou incoming accept-local  --workflow wf_01H2XCEJQ --channel default   # sube lo local (force-with-lease)
jelou incoming mark-resolved --workflow wf_01H2XCEJQ                      # limpia sin aplicar ninguno
```

<Note>
  `accept-local` hace una verificación CAS contra el hash del servidor registrado:
  si el servidor divergió desde que se capturó el artefacto, se niega con
  `NEW_REMOTE_DRIFT`. Ejecuta `mark-resolved` y luego `pull` para ver la nueva
  divergencia.
</Note>