> ## 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.

# Projetos e canais

> Crie e administre projetos (assistentes de IA), suba arquivos de conhecimento, conecte canais (Web, WhatsApp, Facebook, Instagram) e sincronize os workflows de um projeto entre a sua máquina e o servidor.

Um **projeto** é um assistente de IA com seus arquivos de conhecimento, seus
canais e seus workflows. O subcomando `jelou project` administra o ciclo de
vida do projeto; `jelou channels` conecta o projeto a canais de
mensageria; e os comandos de sincronização (`link`, `pull`, `status`, `push`,
`incoming`) levam os workflows do projeto para arquivos locais e de volta.

<Note>
  "Brain" é o nome legado de "project". `--brain` é aceito como alias de
  `--project` em `jelou link` e `jelou channels`, e vários campos a nível de API
  conservam o nome `brain` — mas o nome canônico é **project**.
</Note>

## `jelou project`

| Subcomando                        | Descrição                                                 |
| --------------------------------- | --------------------------------------------------------- |
| `list`                            | Lista todos os projetos (paginado)                        |
| `show <id>`                       | Mostra detalhes do projeto e contagem de arquivos         |
| `create "<nome>"`                 | Cria um projeto novo                                      |
| `update <id>`                     | Atualiza nome ou descrição                                |
| `delete <id>`                     | Exclui um projeto (em cascata, irreversível)              |
| `publish <id>`                    | Publica o rascunho em uma branch de produção              |
| `history <id>`                    | Histórico de versões / commits do projeto                 |
| `restore <id> <commit>`           | Restaura para um commit anterior ou o carrega no rascunho |
| `knowledge list <id>`             | Lista os arquivos de conhecimento                         |
| `knowledge upload <id> <arquivo>` | Sobe um arquivo de conhecimento                           |
| `knowledge delete <id> <file-id>` | Exclui um arquivo de conhecimento                         |

```bash theme={null}
jelou project list --page 2 --limit 5 --json
jelou project show 01H2XCEJQTG2H5V5NKCYW3J7Z2
jelou project create "Suporte de Produto" --description "IA de atendimento ao cliente"
jelou project update 01H2XCEJQTG2H5V5NKCYW3J7Z2 --name "Suporte v2"
jelou project delete 01H2XCEJQTG2H5V5NKCYW3J7Z2 --yes
```

### Conhecimento

Suba documentos para que o assistente os use como base de conhecimento.
Formatos suportados: PDF, TXT, CSV (máx. 2 MB por arquivo).

```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 e restaurar

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

<Warning>
  `project delete` é **em cascata e irreversível**: exclui o projeto, seu
  workspace, sua skill padrão e seu canal sandbox. `publish` e `restore`
  afetam a produção imediatamente, e excluir um arquivo de conhecimento dispara um
  re-treinamento (as respostas podem mudar). Execute `project show` e
  confirme antes de operações destrutivas.
</Warning>

## `jelou channels`

Conecta um projeto a canais de mensageria.

| Subcomando                                              | Descrição                                                                                   |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `list --project <id>`                                   | Lista os canais de um projeto (filtra por `--type`)                                         |
| `show <id>`                                             | Mostra o detalhe completo de um canal, incluindo o `pageId` da Meta para Facebook/Instagram |
| `activate whatsapp`                                     | Conecta um número de WhatsApp pelo fluxo de login da Meta (sem colar credenciais)           |
| `create --project <id> --type web --name "<n>"`         | Cria um canal (pela CLI, apenas `--type web`)                                               |
| `connect <channel-id> --to <bot\|agent\|pma> --id <id>` | Roteia o canal para um bot, agente ou PMA                                                   |
| `flows --bot-id <id>`                                   | Lista os WhatsApp Flows disponíveis para um bot                                             |
| `testers`                                               | Gerencia a whitelist de números de teste do sandbox de WhatsApp                             |

Pela CLI, `channels create` só suporta `--type web` (widget web). Os canais
de WhatsApp, Facebook e Instagram exigem OAuth: o WhatsApp se conecta com
`jelou channels activate` (login da Meta, sem colar credenciais), enquanto
Facebook e Instagram só podem ser criados a partir do dashboard.

```bash theme={null}
jelou channels list --project 01H2XCEJQTG2H5V5NKCYW3J7Z2 --exclude-sandbox
jelou channels list --type Facebook_Feed          # caixa de comentários da página, não o Messenger
jelou channels create --project 01H2XCEJQTG2H5V5NKCYW3J7Z2 --type web --name "Widget do site"
jelou channels activate whatsapp --project 01H2XCEJQTG2H5V5NKCYW3J7Z2
jelou channels connect 01H2XCEJQTG2H5V5NKCYW3J7Z2 --to bot --id bot_01H2XCEJQ
```

<Note>
  `--type` é exato: `Facebook` são só as DMs do Messenger, `Facebook_Feed` é a
  caixa de comentários da página (antes invisível para a CLI); mesmo padrão
  para `Instagram`/`Instagram_Feed`. Conectar uma página do Facebook é só
  metade do trabalho — cada skill precisa do seu próprio canal do Facebook,
  adicionado no Studio, ou o motor não encontra para qual workflow rotear
  esse tráfego e nada responde.
</Note>

<Warning>
  `channels connect` **sobrescreve sem avisar**: se o canal já tinha uma
  conexão, reapontá-lo roteia usuários reais para o novo destino na próxima
  mensagem recebida. Verifique ambos os destinos antes de conectar.
</Warning>

## Sincronizar workflows (local ↔ servidor)

Para editar os workflows de um projeto como arquivos locais, primeiro vincule
o diretório ao projeto com `jelou link`, depois baixe (`pull`), revise
(`status`), edite e suba (`push`).

### `jelou link`

```bash theme={null}
jelou link                                   # interativo
jelou link --project 01H2XCEJQTG2H5V5NKCYW3J7Z2
jelou link --project 01H2XCEJQTG2H5V5NKCYW3J7Z2 --authoring ts   # fixa o modo de authoring (ts|json) no jelou.yml
jelou link --status --json                   # mostra o vínculo sem chamar a API
```

Escreve `jelou.yml` (vínculo compartilhado pela equipe — versione-o no git) e
`.jelou/state.json` (estado local — adicione-o ao `.gitignore`, a CLI faz isso
automaticamente).

<Warning>
  `jelou link`, `pull` e `push` escrevem arquivos locais. Requerem um worktree
  git limpo ou um diretório vazio. Se o diretório estiver sujo ou não versionado,
  a CLI para; use `--allow-dirty` apenas após confirmar.
</Warning>

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

```bash theme={null}
jelou pull                       # baixa todos os workflows para workflows/<slug>.<canal>.json
jelou pull --check --json        # dry-run: resumo sem escrever
jelou pull --workflow saludo     # um único workflow
jelou pull --quiet --json        # sem ruído informativo no stderr (uso por agentes)

jelou status                     # diff local vs lockfile
jelou status --check-remote      # além disso compara contra o servidor (detecta drift)
jelou status --quiet --json      # mostra só as entradas não-limpas (CI-friendly)

jelou push                       # sobe as edições locais
jelou push --dry-run --json      # apenas mostra o diff, não despacha
jelou push --workflow saludo     # um único workflow
jelou push --force               # ignora a verificação de drift do lockfile (camada 1)
jelou push --repair-from .jelou/journals/2026-05-03T20-45-52-000Z.json   # reexecuta um journal incompleto ou com falha
```

<Tip>
  Precisa do panorama completo, não só do status de sync? `jelou context --agent`
  entrega numa única chamada a mesma informação de drift que o `status`, mais
  identidade, allowlist de modelos de IA, nomes de secrets, inventário de bancos
  de dados e o catálogo de tipos de nó — substituindo a sequência `status` +
  `secret list` + `models list` + `databases list` + `workflow node-spec --list`
  para agentes que querem todo o contexto inicial de uma vez.
</Tip>

### `jelou incoming` — resolver edições concorrentes

Se um `pull` detectar que o servidor mudou um workflow que você também editou
localmente, ele preserva a versão do servidor em `.jelou/incoming/` e sai com
código 7. Resolva cada artefato antes de fazer `pull` novamente:

```bash theme={null}
jelou incoming list
jelou incoming diff --workflow wf_01H2XCEJQ
jelou incoming accept-server --workflow wf_01H2XCEJQ --channel default   # adota o servidor
jelou incoming accept-local  --workflow wf_01H2XCEJQ --channel default   # sobe o local (force-with-lease)
jelou incoming mark-resolved --workflow wf_01H2XCEJQ                      # limpa sem aplicar nenhum
```

<Note>
  `accept-local` faz uma verificação CAS contra o hash do servidor registrado:
  se o servidor divergiu desde que o artefato foi capturado, ele recusa com
  `NEW_REMOTE_DRIFT`. Execute `mark-resolved` e depois `pull` para ver a nova
  divergência.
</Note>