@fazer-ai/agents 1.0.0

package/dist/skills/agents-onboarding/references/01b-brownfield.md

@@ -0,0 +1,70 @@
+# 01b: Inventário brownfield (sondar antes de instalar)
+
+A VPS pode chegar vazia (**greenfield**) ou já com Coolify e/ou Chatwoot e/ou Langfuse e/ou a própria agents, em **qualquer combinação** (**brownfield**). Antes de instalar qualquer coisa (etapas 2 a 5), **sonde** o que já existe e decida **por serviço**: reusar, instalar, ou sinalizar incompatibilidade. É isso que torna as etapas de deploy **idempotentes** (só provisionam o que falta) e **não-destrutivas** (nunca apagam o que o usuário já tem).
+
+## 1. Sondagem (read-only, não muta nada)
+
+Rode na VPS via SSH (etapa 0). Tudo aqui é leitura (`docker ps/inspect`, `ss`, `curl`, `df/free`). O probe tem `{{…}}`, `$()`, aspas aninhadas e múltiplas linhas: **não monte isso inline no `ssh <host> '…'`** (no PowerShell as aspas são comidas e a here-string ganha BOM → o bash quebra; ver `gotchas.md`). **Escreva o probe num arquivo `recon.sh`** e rode pelo `scripts/remote.py`, que entrega byte a byte em qualquer SO:
+
+`recon.sh`:
+```sh
+sec(){ printf '\n### %s\n' "$1"; }
+sec OS;        ( . /etc/os-release && echo "$PRETTY_NAME" )
+sec RESOURCES; free -h | awk 'NR==2{print "mem "$2"/"$7" avail"}'; df -h / | awk 'NR==2{print "disk "$2"/"$4" free"}'; echo "cpu $(nproc)"
+sec DOCKER;    docker --version || echo absent
+sec CONTAINERS; docker ps -a --format '{{.Names}}	{{.Image}}	{{.Status}}	[{{.Label "com.docker.compose.project"}}]'
+sec PORTS;     ss -tlnp | awk 'NR>1{n=split($4,a,":");print a[n]}' | sort -un | tr '\n' ' '; echo
+sec COOLIFY;   curl -s -m5 -o /dev/null -w 'api8000=%{http_code}\n' http://localhost:8000/api/health
+sec IMAGES;    docker ps -a --format '{{.Image}}' | sort -u | grep -iE 'coolify|chatwoot|langfuse|agents|pgvector|clickhouse|minio|traefik|caddy|nginx'
+```
+
+```sh
+python3 scripts/remote.py --ssh root@<VPS_IP> --ssh-opts "-i <chave>" --script-file recon.sh
+```
+
+> **Tier B (Portainer):** quando a plataforma é Portainer, a sondagem é **via API do Portainer** (`GET /api/stacks`, `GET /api/endpoints/{id}/docker/containers/json`), não `coolify-db`. A lógica é a mesma (fingerprint por imagem + matriz da seção 3); use `scripts/portainer-brownfield.py` (já detecta quem ocupa 80/443 → se há ingress, o Caddy bundled conflita, reusar ou ir de `templates/docker-compose.prod.yml` BYO-proxy). Ver [`deploy-b-portainer.md`](deploy-b-portainer.md).
+
+## 2. Ler os sinais
+
+**Identifique o serviço pela IMAGEM, não pelo nome do projeto** (é um UUID opaco). Fingerprints:
+
+| Serviço | Imagem (fingerprint) | Saúde = todos healthy | Versão |
+|---|---|---|---|
+| **Coolify** | `coollabsio/coolify` (+ `coolify-db`/`-redis`/`-realtime`, `-proxy`=`traefik`) | container `coolify` + API `:8000`=200 | tag da imagem (ex. `:4.1.2`) |
+| **Chatwoot** | imagem com `chatwoot` (+ `sidekiq`, e `baileys-api` pro WhatsApp) | `chatwoot` + `sidekiq` Up | tag (`:latest` → ver via `/version`) |
+| **Langfuse** | `langfuse/langfuse` (+ `-worker`, `clickhouse`, **`minio`**) | web+worker+clickhouse+minio Up | tag (ex. `:3`) |
+| **fazer.ai agents** | `ghcr.io/fazer-ai/agents` (+ `pgvector`) | container Up + `/api/health` | tag |
+
+As portas das apps **não** ficam expostas no host (atrás do Traefik); só Coolify (`:8000`) e o proxy (`:80`/`:443`) escutam. `curl localhost:80` sem o Host certo dá 404/503 (esperado). Pra health de uma app, use o FQDN dela.
+
+## 3. Matriz de decisão (por serviço)
+
+- **Ausente** (nenhum container com o fingerprint) → **instala** do zero (etapa do serviço).
+- **Presente + saudável + compatível** → **reaproveita**: capture endpoint/UUID/FQDN pro state, NÃO recrie (a etapa do serviço vira no-op + captura).
+- **Presente + não-saudável** (container existe mas não Up/healthy) → **pare e sinalize**: investigar/consertar antes de prosseguir; nunca instalar por cima.
+- **Presente + incompatível** → **pare e sinalize ao usuário** (atualizar / migrar / instalar em paralelo, decisão dele). Ver compatibilidade abaixo.
+
+Greenfield = tudo ausente = instala tudo. O resultado é um inventário por serviço (`ausente | reusar | sinalizar`) que dirige as etapas 2 a 5.
+
+## 4. Compatibilidade (o que torna "presente" em "incompatível")
+
+- **Chatwoot OSS vs Pro:** a imagem revela. `harbor.fazer.ai/chatwoot/fazer-ai/chatwoot-pro` = **Pro** (Kanban + features fazer-ai). `ghcr.io/fazer-ai/chatwoot` (nosso fork OSS), ou o `chatwoot/chatwoot` oficial do Docker Hub num brownfield de terceiro, = **OSS**: o core do agente funciona (Agent Bot é padrão), mas **sem** Kanban/features Pro. Se o usuário quer essas features, sinalize a migração pra Pro.
+- **Langfuse v3 vs v2:** o fazer.ai agents fala com a v3 (arquitetura `clickhouse` + **`minio` obrigatório**, ver `references/05-langfuse.md`). Tag `:2`, ou ausência de `clickhouse`/`minio`, → incompatível/parcial: sinalize.
+- **Coolify:** validado em `4.x`. Versões muito antigas têm API diferente; confirme `:8000/api/health`=200 e cheque a versão pela tag.
+- **Postgres reusado (fora do Coolify, Tier B/C):** o fazer.ai agents exige **pgvector** (extensão `vector`) e um **superuser** pro bootstrap das 2 roles (ver `references/04-agents-image.md`). Um Postgres compartilhado sem pgvector ou sem acesso superuser → sinalize.
+
+## 5. Reaproveitar (capturar pro state, sem recriar)
+
+Pra um serviço que vai reusar, capture o que as etapas seguintes precisam:
+- **No Coolify, do container ao FQDN:** cruze o label `com.docker.compose.project` (= `uuid` do serviço) com o `coolify-db` pra pegar o endpoint público (sub-componentes como `sidekiq`/`minio`/`clickhouse` têm `fqdn` vazio):
+
+  ```sh
+  docker exec -i coolify-db psql -U coolify -d coolify -c \
+    "SELECT s.uuid, s.name, sa.fqdn FROM services s
+     JOIN service_applications sa ON sa.service_id=s.id
+     WHERE sa.fqdn IS NOT NULL AND sa.fqdn<>'' ORDER BY s.id;"
+  ```
+
+  Ou via API: `GET /api/v1/services` (etapa 2). Preserve a porta do FQDN quando houver (ex. Langfuse `:3000`).
+- **Endpoints/creds:** FQDN público + credenciais já existentes (admin token do Chatwoot via Rails runner; chaves do Langfuse) buscadas **transitoriamente** (ver `guardrails.md`), nunca persistidas.
+- **Nunca** recrie um serviço saudável só pra "padronizar": isso destrói dados do usuário. Em brownfield, reusar > reinstalar.

package/dist/skills/agents-onboarding/references/01c-pick-tier.md

@@ -0,0 +1,61 @@
+# 01c: Selecionar o tier de deploy + o contrato
+
+Depois do inventário brownfield (1b) você sabe **o que já existe** na VPS. Agora escolha **a trilha de
+deploy** (qual orquestrador sobe Chatwoot + fazer.ai agents + Langfuse com TLS) e siga só ela. As etapas 6 a 10 (a
+**espinha**: `/setup` → MCP → import → bind → E2E) são **idênticas em qualquer tier**: elas
+consomem o *resultado* do deploy, não se importam com *como* ele foi feito.
+
+## Qual tier
+
+O probe do 1b já revela o orquestrador instalado (fingerprint por imagem). Mapeie:
+
+| Sinal na VPS (1b) | Tier | Trilha de deploy |
+|---|---|---|
+| **Coolify** saudável (ou usuário quer Coolify) | **A** | etapas 2-5 ([`02-coolify.md`](02-coolify.md) → `03` → `04` → `05`) |
+| **Portainer** (ou usuário quer Portainer) | **B** | [`deploy-b-portainer.md`](deploy-b-portainer.md) |
+| **Tudo o mais**: VM crua, ou um painel sem trilha dedicada (Easypanel, Dokploy, CapRover, …) | **C** | [`deploy-c-compose.md`](deploy-c-compose.md) |
+
+Coolify ou Portainer presentes e saudáveis ganham (reusar > instalar; o 1b decide por serviço); **qualquer
+outro painel cai no Tier C** (compose genérico, adaptado ao painel com seu conhecimento dele). Nenhum sinal
+claro → **pergunte ao usuário**, não adivinhe.
+
+> A trilha C (compose genérico) é mais nova que A/B; trate-a como primeira run guiada.
+
+## O contrato de deploy (o que a trilha entrega à espinha)
+
+Qualquer que seja o tier, o segmento de deploy termina quando **entrega exatamente isto**. A espinha
+(6-10) não pede mais nada e não olha pra dentro do orquestrador:
+
+1. **Três URLs HTTPS públicas**, com **DNS resolvido + TLS válido** (Let's Encrypt):
+   - `agentes.<domínio>` → agents (`GET /api/health` = 200).
+   - `chatwoot.<domínio>` → Chatwoot (Pro ou OSS).
+   - `langfuse.<domínio>` → Langfuse (recomendado; o E2E valida traces).
+2. **agents subida com as duas roles de DB** (superuser p/ bootstrap+migrate, runtime **não-superuser**) e o
+   env mínimo: `PUBLIC_URL`, `JWT_SECRET`, `ENCRYPTION_KEY`, os dois pares de URL
+   (`MIGRATION_DATABASE_URL` = superuser; `DATABASE_URL` + `LANGGRAPH_DATABASE_URL` = runtime),
+   `BRANDING_STORAGE_DIR`/`QUOTES_STORAGE_DIR` no volume persistente, **réplica única**. O
+   `scripts/gen-onboarding-env.ts` gera os secrets + URLs; os composes
+   do repo já trazem o resto.
+3. **agents acessível + token do `/setup`** legível nos logs de boot (`${PUBLIC_URL}/setup?token=…`).
+4. **admin token do Chatwoot** obtível (via Rails runner) pro `deployment_connect`/bind da etapa 9.
+5. **Langfuse com MinIO** (a ingestion v3 exige blob storage) + as chaves (public/secret) obtíveis.
+
+Entregou os 5 → vá direto pra **etapa 6** (a mesma pra todos os tiers).
+
+> **Chatwoot existente (`chatwootSource: existing` no marcador):** só **fazer.ai agents + Langfuse** a provisionar: `chatwoot.<domínio>` é a instância que **já está no ar** (não a crie nem lhe mexa; o item 1 e o deploy do Chatwoot da trilha do tier são pulados). O admin token (item 4) vem via **Rails runner** se a instância é on-box/alcançável por SSH; se for **off-box** (Chatwoot Cloud / outro host), o **usuário fornece** um admin API token (Chatwoot → Profile → Access Token). O bind (etapa 9) usa a URL pública + esse token.
+
+## Invariantes (valem em todos os tiers)
+
+- **`pgvector/pgvector:pg17`**, nunca Postgres puro: o schema roda `CREATE EXTENSION vector`.
+- **Réplica única** do fazer.ai agents: os workers (scheduler/debounce/outbound) assumem um único líder; não escale o
+  serviço `agents` pra >1 (ver o aviso no `templates/docker-compose.prod.yml`).
+- **DNS antes do ACME**: o cert só emite com o A-record já resolvendo pro IP da VPS. Crie os A-records
+  (etapa 1) e confirme a resolução **antes** de anexar o domínio no painel / subir o Caddy.
+- **Quem ocupa 80/443**: se já há um proxy/ingress (Traefik do painel, nginx, um Caddy), o Caddy
+  *bundled* do `templates/docker-compose.portainer.yml` **conflita**:
+  reuse o proxy existente com `templates/docker-compose.prod.yml` (BYO-proxy).
+  O 1b já sinaliza quem detém as portas.
+- **Não sobrescreva `command:`** no serviço do fazer.ai agents: o CMD da imagem faz `bootstrap → migrate deploy →
+  serve`. Um `command:` próprio quebra o boot.
+- **agents → Chatwoot pela URL pública**: o `deployment_connect` funciona contra a URL **pública** do Chatwoot,
+  sem gambiarra de rede interna (detalhe na gotcha de [`deploy-b-portainer.md`](deploy-b-portainer.md)).

package/dist/skills/agents-onboarding/references/02-coolify.md

@@ -0,0 +1,109 @@
+# 02: Coolify (reusar/instalar, API, Instance Domain)
+
+> **Avise o usuário onde você está:** o Coolify é o **1º serviço** do deploy (o painel que gerencia tudo; depois vêm Chatwoot, fazer.ai agents e Langfuse). Diga que vai começar por ele, e a instalação leva alguns minutos. Dê sinal de vida durante a espera longa (Docker + imagens baixando) em vez de sumir; ao terminar, confirme e anuncie o próximo. Ver o princípio de narração (e a contagem que se ajusta ao caso real) em `SKILL.md`.
+
+## Brownfield: reusar se já existe e está saudável
+
+A VPS pode já vir com Coolify (brownfield). Nesse caso, reaproveite o existente: **nunca** destrua dados do usuário. O inventário brownfield completo (todos os serviços, com a matriz reusar/instalar/sinalizar) está na etapa 1b (`references/01b-brownfield.md`); aqui é só a parte do Coolify.
+
+### Greenfield: instalar o Coolify se a VPS vier sem ele
+
+VPS nova sem Coolify → rode o instalador oficial. **Como você invoca importa mais que o instalador** (é o passo que mais trava): ele puxa Docker + imagens (minutos), lê o próprio stdin e faz job control. Dois anti-padrões fazem ele sair com exit 1/127 fingindo estar "interativo (Y/N)" (e aí um modelo fraco entra num loop de tweaks):
+
+- **Não** jogue a saída do `curl` direto num shell (baixar-e-canalizar): o `bash` passa a ler o SCRIPT do stdin e colide com os prompts do instalador.
+- **Não** o passe pelo stdin do `remote.py`/`bash -s` (que já usa o stdin pro próprio script): o instalador herda um stdin ocupado/EOF.
+
+Em vez disso, **baixe o instalador pra um arquivo no remoto e rode o arquivo com stdin limpo (`< /dev/null`), detached**, depois faça poll (não bloqueie o terminal por minutos, a chamada pode ser cortada). O `remote.py --script-file` roda este wrapper, que faz o download+run NO remoto (sem canalizar):
+
+`install-coolify.sh`:
+```sh
+curl -fsSL https://cdn.coollabs.io/coolify/install.sh -o /tmp/coolify-install.sh
+setsid bash /tmp/coolify-install.sh < /dev/null > /tmp/coolify-install.log 2>&1 &
+echo "coolify install iniciado (pid $!); log em /tmp/coolify-install.log"
+```
+
+Depois faça **poll não-bloqueante** até ficar pronto: `curl -s -o /dev/null -w '%{http_code}' http://localhost:8000/api/health` = `200` e os containers core `Up (healthy)`. Resultado esperado: `/data/coolify` criado, "Your instance is ready to use!" no log, **6 containers core** Up+healthy (`coolify`, `coolify-db`, `coolify-redis`, `coolify-realtime`, `coolify-proxy`, `coolify-sentinel`). Em brownfield (Coolify já presente e saudável) **reaproveite** (etapa 1b); nunca reinstale por cima de dados do usuário.
+
+## Verifique que o Coolify alcança o próprio servidor (localhost): auto-repare a chave
+
+Assim que o Coolify está de pé (greenfield recém-instalado OU brownfield reaproveitado), **confirme que ele consegue se conectar ao próprio host** antes de qualquer deploy. O Coolify gerencia o servidor `localhost` por SSH, do container `coolify` para o host (`root@host.docker.internal`), com uma chave que o instalador adiciona às **chaves autorizadas do root**. É uma falha silenciosa e recorrente: se a última linha desse arquivo **não terminava em newline** (uma chave colada pelo painel da VPS costuma chegar assim), o `cat >>` do instalador **cola** a chave do Coolify no fim da linha anterior: ela deixa de ser uma entrada válida, o servidor `localhost` fica **Unreachable** e **todo deploy falha depois** (sem erro óbvio; a UI só mostra o servidor inacessível).
+
+Não conserte na mão (editar as chaves autorizadas por SSH→PowerShell é a classe de quoting que mais quebra). Rode o helper: ele normaliza o arquivo (uma chave por linha, sem linhas grudadas, newline no fim, permissões), garante a chave do Coolify como linha própria, e **verifica** o SSH container→host:
+```sh
+python3 scripts/coolify.py heal-localhost --ssh root@<VPS_IP>
+```
+`reachable:true` → o Coolify alcança o próprio host; siga. **Idempotente**: rode sempre (greenfield ou brownfield); se já estava são, não muda nada e confirma `reachable:true`. O flag interno do Coolify (`is_reachable`) fica em cache e **não** revalida sozinho de forma confiável (o job periódico costuma ser pulado por lock); ele só reflete o conserto após um `docker restart coolify` (que o passo do **Instance Domain** já faz antes dos deploys), então um "Unreachable" na UI até lá é cosmético. Se **não** for setar o Instance Domain antes do 1º deploy, rode `docker restart coolify` depois do heal pra revalidar. `reachable:false` → confira que o container `coolify` está `Up` e que o host aceita login root por chave, e re-rode.
+
+## 1º admin (o ÚNICO passo do usuário no Tier A)
+
+O **usuário cria** o 1º admin pelo browser em `http://<VPS_IP>:8000` (gate de conta): **esse é o único passo manual do Tier A**; você entrega o link e **espera** (`wait-admin`), nunca cria por conta própria. Depois do admin, **NÃO peça mais nada ao usuário**: o token e o Instance Domain você faz por SSH (abaixo). **Nunca** mande o usuário abrir "Settings → …".
+
+Em vez de pedir "responda quando criar", **aguarde** o admin aparecer (poll no banco via psql, não trava o operador). **Rode em background, não em foreground**: o poll bloqueia por minutos e não há nada a fazer no meio, então dispare non-blocking e retome quando o comando sair (nunca deixe o poll travar o seu turno). Como o gate depende do usuário criar a conta no browser, dê uma janela larga (`--attempts 120`, ~10 min):
+```sh
+python3 scripts/coolify.py wait-admin --ssh root@<VPS_IP> --attempts 120   # em background, non-blocking
+```
+`ok:true` (com `users>0`) → siga pro token. `ok:false` (timeout) → re-lance ou pergunte ao operador. **Não avance pro token antes do `ok:true`.** Brownfield: se já existe admin, detecta na 1ª tentativa e segue. (O detector é psql, não Tinker: não dá o falso "sem admin" que o Tinker dava ao ecoar o payload.)
+
+## API Access (token): você faz por SSH, não pela UI
+
+Dois passos, ambos por SSH, **sem o usuário**. Os dois (e toda chamada à API daqui pra frente) saem do `scripts/coolify.py` (Python stdlib, embutido nesta skill): ele base64-pipa o payload por SSH, semeia o `currentTeam`, e **mantém o token Sanctum `<id>|<token>` fora de qualquer shell** (o `|` só vive num arquivo `0600` e no header HTTP). Foi um `|` num comando montado à mão que já derrubou uma run. Rode via Bash com sandbox desligado, como todo ssh/curl (ver `00`).
+
+**1. Habilite a API**: vem **desabilitada** por padrão; sem isto todo request dá `403 {"message":"API is disabled."}`:
+```sh
+python3 scripts/coolify.py enable-api --ssh root@<VPS_IP>
+```
+Pega na hora, sem restart, idempotente. `allowed_ips` vazio (default) = sem restrição de origem; **não mexa** (o agente acessa de fora).
+
+**2. Gere o token root.** O `createToken` cru falha com `team_id null`, então o script **semeia a sessão** (`currentTeam`) antes de gerar, extrai o `<id>|<token>` e grava num arquivo `0600` (ability `*` = root; o segredo **não** é impresso):
+```sh
+python3 scripts/coolify.py token --ssh root@<VPS_IP> --out coolify.token   # arquivo no scratchpad, transitório
+```
+Daí toda chamada autenticada lê o token do arquivo, você **nunca** digita o token num `curl`. Valide a API:
+```sh
+python3 scripts/coolify.py api-get --base-url http://<VPS_IP>:8000 --token-file coolify.token --path /servers   # → 200
+```
+`create-service` (deploy de serviço), `api-post` (qualquer POST autenticado) e `set-fqdn` usam o mesmo `--token-file`. O arquivo é transitório (scratchpad); **nunca** em repo/log/commit. **Windows/PowerShell:** no `api-post`, prefira `--json-file` a `--json-stdin`: o pipe do PowerShell manda o stdin em UTF-16 e quebra o JSON (o helper tolera BOM/UTF-16 como rede de segurança, mas `--json-file` é determinístico).
+
+## Instance Domain: você seta por SSH (faça ANTES de deployar os serviços)
+
+Troca o acesso ao **painel** de `http://<VPS_IP>:8000` para `https://coolify.<seu-dominio>` (TLS). O deploy dos serviços não depende disto (rodam pelo IP cru), mas **faça**: é parte do contrato do painel, não item descartável. Duas regras de ordem/confiabilidade que já queimaram runs:
+
+1. **Faça ANTES de deployar os serviços.** O passo termina com `docker restart coolify`, que **zera a fila de deploy** do Coolify (`gotchas.md`: "o `start` da API pode não materializar"). Reiniciar o `coolify` no meio do deploy faz os serviços não subirem. Ordem: token → **Instance Domain** → deploy dos serviços.
+2. **NÃO monte o psql + restart inline no `ssh <host> '…'`**: o `UPDATE …` com aspas e o `; docker restart` quebram no PowerShell (aspas comidas, `\`/BOM; é exatamente onde uma run real falhou e o agente desistiu chamando de "cosmético"). Escreva um `.sh` e rode pelo `remote.py` (entrega byte-exato):
+
+`set-instance-domain.sh`:
+```sh
+docker exec -i coolify-db psql -U coolify -d coolify -c "UPDATE instance_settings SET fqdn='https://coolify.<seu-dominio>';"
+docker restart coolify
+```
+```sh
+python3 scripts/remote.py --ssh root@<VPS_IP> --ssh-opts "-i <chave>" --script-file set-instance-domain.sh
+```
+O `UPDATE` **sozinho não regenera** o proxy; é o **`restart coolify`** (o app, **NÃO** `coolify-proxy`) que reescreve a rota do painel. Derruba painel+API ~30-40s (o token já gerado **sobrevive**). Exige o A-record `coolify.` (etapa 1). Depois **valide**:
+```sh
+curl -so /dev/null -w "%{http_code} ssl=%{ssl_verify_result}\n" https://coolify.<seu-dominio>
+```
+→ `200`/`302` com `ssl=0` (cert válido; o ACME emite quando o A-record resolve). Só siga sem o domínio se ele **falhar de verdade** após este caminho (não como atalho).
+
+## DB do Coolify (acesso direto; ver gotchas)
+
+```sh
+docker exec -i coolify-db psql -U coolify -d coolify
+```
+
+## Projeto + ambiente
+
+Crie (ou reaproveite) um projeto com o **nome de exibição do usuário** (ex.: `clinica-moreira`) e o ambiente `production`. Os UUIDs (server/projeto/env/serviços) são **gerados a cada instalação**: descubra-os pela API/DB; nunca chumbe UUIDs de outra instalação.
+
+## Registry privado do Harbor (só Pro)
+
+Imagens **Pro** (Chatwoot `chatwoot-pro`; fazer.ai agents no projeto `agents`) são privadas no Harbor: o Coolify precisa da credencial registrada **antes** de puxar, senão o deploy falha (pull denied / 401). Só no caminho Pro:
+
+1. Provisione a credencial **per-user** pelo **proxy do hub no CLI** (não há hub MCP na sessão; o CLI tem o OAuth do bootstrap):
+   ```sh
+   bunx @fazer-ai/agents hub registry-credential --apply --out harbor.secret
+   ```
+   Grava o secret em `harbor.secret` (`0600`) e imprime só `username` + caminho (o secret **nunca** sai no output). Idempotente (garante o robot per-user, sem rotação).
+2. Registre no Coolify (Servers → Registries, ou via API) apontando pra `harbor.fazer.ai` com o `username` (do passo 1) e o secret de `harbor.secret`. **Nunca** logue o secret.
+
+No caminho **OSS** (imagem pública), pule isto inteiro.

package/dist/skills/agents-onboarding/references/03-chatwoot-pro.md

@@ -0,0 +1,61 @@
+# 03: Deploy do Chatwoot (Pro ou OSS)
+
+## Antes de tudo: `chatwootSource` (novo vs. existente/BYO)
+
+Leia `~/.fazer-ai/onboarding.json` → `chatwootSource`. Se **`existing`** (Chatwoot BYO), **PULE este doc inteiro**: não há Chatwoot a provisionar, `chatwoot.<seu-dominio>` é a instância que **já está no ar** (não a crie nem lhe mexa). Detecte Pro/OSS pela imagem (etapa 1b), vá direto ao **bind (etapa 9)** e trate a **etapa 9b (licenciar)** como opcional (só se for um Pro sem Kanban e o usuário quiser). Todo o resto abaixo é só pra **`new`**.
+
+> **Avise o usuário onde você está** (quando o Chatwoot é `new`): o Chatwoot é o **2º serviço** do deploy (a plataforma de atendimento onde as conversas acontecem; vem depois do painel, antes do fazer.ai agents e do Langfuse). Diga que vai subir o Chatwoot agora e que leva alguns minutos; dê sinal de vida durante a espera longa (imagem baixando) e confirme ao terminar, anunciando o próximo. Ver o princípio de narração em `SKILL.md`.
+
+## Primeiro (source `new`): leia o marcador e ramifique (Pro vs OSS)
+
+Leia `~/.fazer-ai/onboarding.json` → `chatwootTier`. Eixo **independente** da edição do fazer.ai agents (`edition`, etapa 4). Marcador ausente → fallback pelo hub (`bunx @fazer-ai/agents hub licenses`): licença CHATWOOT disponível → Pro; senão OSS.
+
+- **`community` (OSS)** → imagem **pública** `ghcr.io/fazer-ai/chatwoot:latest` (nosso fork), `COMPOSE_PROFILES` vazio (sem `baileys-api`). **NÃO** rode `docker login` nem provisione credencial do Harbor (não há licença e o pull é público). Deploy pelo compose genérico (`templates/chatwoot/`, ver `templates/chatwoot/README.md`); no Coolify, setar `CHATWOOT_IMAGE=ghcr.io/fazer-ai/chatwoot:latest` no `templates/chatwoot/docker-compose.coolify.yml` e **remover** o `baileys-api`. **Pule a etapa 9b** (licenciar). O resto deste doc é **só Pro**.
+- **`pro`** → siga abaixo (Harbor + Coolify API + `docker login` + etapa 9b).
+
+## Imagem privada (Harbor): credencial per-user via proxy do CLI
+
+Este é passo **seu** de execução, não uma pergunta: a edição (Pro/OSS) já foi decidida no início, então baixar a versão Pro é automático. **Se** você mencionar ao usuário o que está fazendo, diga em linguagem dele ("vou liberar o acesso à versão Pro pra baixar os programas no servidor; usa a sua assinatura, nenhuma senha passa por mim"), **nunca** "provisionar a registry credential per-user do Harbor" nem os comandos. Frases boas × ruins em `guardrails.md`.
+
+`harbor.fazer.ai/chatwoot/fazer-ai/chatwoot-pro:latest`.
+- Credencial do Harbor pelo **proxy do hub no CLI** (não há hub MCP na sessão do agente; o CLI tem o OAuth do bootstrap):
+  ```sh
+  bunx @fazer-ai/agents hub registry-credential --apply --out harbor.secret
+  ```
+  Robot **per-user** (a MESMA cred cobre Chatwoot Pro e fazer.ai agents Pro), idempotente; grava o secret em `harbor.secret` (`0600`) e imprime só o `username`; o secret **nunca** sai no output. **Nunca** logar o secret.
+- O compose é o vendorado `templates/chatwoot/docker-compose.coolify.yml` (não precisa extrair do hub).
+
+## Deploy via API do Coolify
+
+O `scripts/coolify.py create-service` lê o compose, faz o **base64** (raw → 422 "should be base64 encoded") e POSTa em `/api/v1/services` com `instant_deploy:false`; depois você deploya:
+```sh
+python3 scripts/coolify.py create-service --base-url http://<VPS_IP>:8000 --token-file coolify.token \
+  --name chatwoot --project-uuid <PROJ_UUID> --server-uuid <SRV_UUID> --environment-name production \
+  --compose-file templates/chatwoot/docker-compose.coolify.yml   # → {uuid}
+python3 scripts/coolify.py api-post --base-url http://<VPS_IP>:8000 --token-file coolify.token --path /services/<uuid>/start
+```
+- Logue no Harbor com `scripts/harbor-login.py login` **antes** do `start` (o pull da privada precisa do login): roda `docker login --password-stdin` por SSH (secret fora do argv) e protege o `$` do usuário robot. O `username` vem do `hub registry-credential` (acima); o secret está em `harbor.secret` (`0600`):
+```sh
+python3 scripts/harbor-login.py login --ssh root@<VPS_IP> --username '<robot-user>' --secret-file harbor.secret
+```
+
+## Admin + token (Rails runner via SSH)
+
+O **usuário** cria o 1º admin do Chatwoot na própria tela de onboarding do Chatwoot (`https://chatwoot.<seu-dominio>`): você entrega o link e **espera** ele criar a conta + o admin. Quando ele voltar, pergunte **uma vez** qual e-mail ele usou nesse admin (você precisa dele pra ler o token) e **guarde esse e-mail para o resto da run**: é o e-mail do operador em todo o onboarding, inclusive o login do Langfuse (etapa 5). **Não volte a perguntar e-mail depois disso** (nem "qual e-mail pro Langfuse/OWNER?"): reuse este. Com o admin já criado, `scripts/chatwoot-admin.py provision` **lê** esse admin (pelo email) e devolve o `api_access_token` dele: roda o Rails runner **dentro** do container (base64-piped por SSH, então o email e as aspas do script não tocam o shell) e **nunca** cria conta nem usuário. O token é o `AccessToken` polimórfico do usuário (idempotente: reusa o existente ou minta um pelo `AccessToken` do owner, `find_or_create_by!`).
+```sh
+python3 scripts/chatwoot-admin.py provision --ssh root@<VPS_IP> --container <chatwoot-rails-container> \
+  --email <email-do-admin> --out chatwoot-admin.json
+```
+Grava `api_access_token` num arquivo `0600`; só metadados são impressos. Se o email ainda não existe, o helper erra claro (`the user must create the admin … first`) → espere o usuário criar e re-rode. Esse `api_access_token` vai no header `api-access-token: <token>` (hífen: sobrevive a proxies, ver `deploy-b-portainer.md`) das chamadas REST do Chatwoot **e** no `deployment_connect` da etapa 9 (transitório, nunca persistido em repo/log).
+
+## FQDN + 503
+
+Ver `gotchas.md`: setar `service_applications.fqdn` no `coolify-db` + restart (o `SERVICE_FQDN_*` env **não** dirige o Traefik).
+
+## Inbox API (pro E2E)
+
+`POST https://chatwoot.<seu-dominio>/api/v1/accounts/1/inboxes` (header `api-access-token`) body:
+```json
+{"name":"Validação (API)","channel":{"type":"api","webhook_url":""}}
+```
+→ inbox `Channel::Api`. O bind do agente (etapa 9) provisiona o webhook do bot; **não** precisa setar `webhook_url` à mão.

package/dist/skills/agents-onboarding/references/04-agents-image.md

@@ -0,0 +1,46 @@
+# 04: Deploy do fazer.ai agents
+
+> **Avise o usuário onde você está:** o fazer.ai agents vem **depois do painel e do Chatwoot**; em seguida só falta o Langfuse. Diga que vai subir o fazer.ai agents agora e que leva alguns minutos; dê sinal de vida durante a espera longa e confirme ao terminar. Ver o princípio de narração (com a contagem que se ajusta ao caso real) em `SKILL.md`.
+
+## Edição: Free ou Pro (lê o marcador PRIMEIRO)
+
+Leia `~/.fazer-ai/onboarding.json` → `edition` (`free` | `pro`; ausente = `free`). É a escolha **explícita** do CLI; respeite-a. Eixo **independente** do `chatwootTier` (etapa 3).
+
+- **`free`** → imagem **pública** (default do compose). **Sem** `docker login`, não seta `AGENTS_IMAGE`. (Hoje o default é o placeholder `ghcr.io/fazer-ai/agents:latest`; a imagem pública Free ainda não foi publicada.)
+- **`pro`** → imagem **privada** no Harbor: `harbor.fazer.ai/agents/fazer-ai/agents-pro:latest`. Provisione a credencial **per-user** pelo **proxy do CLI** (`bunx @fazer-ai/agents hub registry-credential --apply --out harbor.secret`, robot per-user, grava o secret `0600` e imprime só o `username`), logue com `scripts/harbor-login.py login` (secret via `--secret-file harbor.secret`; protege o `$` do robot), e setar `AGENTS_IMAGE` pra esse path. **Nunca** logar o secret.
+  - **Reuso (per-user):** se o Chatwoot também for Pro (etapa 3), é o **mesmo** `docker login`, não logar duas vezes.
+  - **Tier A (Coolify):** setar a env `AGENTS_IMAGE` no serviço + registrar a Harbor registry credential no Coolify (igual ao Chatwoot Pro).
+  - **Tier B/C (compose):** `export AGENTS_IMAGE=<imagem>` (ou no `.env`) antes do `docker compose up`.
+
+## Compose
+
+Use o `templates/docker-compose.coolify.yml` do repo via `scripts/coolify.py create-service` (lê o compose, base64-encoda, POSTa em `/api/v1/services`). Topologia: `agents` (imagem conforme a **edição** acima; o compose default é a Free) + `postgres` (`pgvector/pgvector:pg17`: NÃO postgres puro: o schema precisa de `CREATE EXTENSION vector`). Volume `storage:/app/storage`. Healthcheck `wget -qO- http://localhost:3000/api/health`.
+
+## Magic vars (Coolify gera; NÃO setar à mão)
+
+- `SERVICE_URL_AGENTS` → `PUBLIC_URL` e `CDN_URL`.
+- `SERVICE_USER_DBUSER` / `SERVICE_PASSWORD_64_DBPASSWORD` → **superuser** (dono do Postgres) → `MIGRATION_DATABASE_URL`.
+- `SERVICE_USER_APPDBUSER` / `SERVICE_PASSWORD_64_APPDBPASSWORD` → **app role** (não-superuser) → `DATABASE_URL` + `LANGGRAPH_DATABASE_URL`.
+- `SERVICE_PASSWORD_64_JWTSECRET` → `JWT_SECRET`; `SERVICE_PASSWORD_64_ENCRYPTIONKEY` → `ENCRYPTION_KEY`.
+
+## Persistência de branding/quotes (fix: já no compose)
+
+```
+BRANDING_STORAGE_DIR=/app/storage/branding
+QUOTES_STORAGE_DIR=/app/storage/quotes
+```
+Sem isso caem em `./data/*` (FS efêmero do container) e logo/favicon (+ PDFs de quote) somem no redeploy. Já corrigido no `templates/docker-compose.coolify.yml`; **confira que está lá** (branding é refino manual opcional depois, em `/admin/branding`, mas a persistência precisa já estar no lugar).
+
+## Boot = CMD da imagem (NÃO sobrescrever `command`)
+
+A sequência `bootstrap → migrate deploy → serve` é o CMD do Dockerfile. **Não** declare `command:` no compose (sobrescrever crash-loopa). Detalhe em `gotchas.md`.
+
+## FQDN + 503 + verificação
+
+O `SERVICE_FQDN_*` não dirige o Traefik; quem roteia é a linha em `service_applications` (ver `gotchas.md`). Ache o id e seta o FQDN:
+```sh
+python3 scripts/coolify.py list-apps --ssh root@<VPS_IP>            # ache o id do agents
+python3 scripts/coolify.py set-fqdn  --ssh root@<VPS_IP> --app-id <id> --fqdn https://agentes.<seu-dominio>
+python3 scripts/coolify.py api-post  --base-url http://<VPS_IP>:8000 --token-file coolify.token --path /services/<uuid>/restart
+```
+Antes do DNS resolver, verifique o routing por sslip.io: `curl http://agents-<service-uuid>.<VPS_IP>.sslip.io/api/health`. Depois do `/setup` (etapa 6) o app responde em `https://agentes.<seu-dominio>`.

package/dist/skills/agents-onboarding/references/05-langfuse.md

@@ -0,0 +1,45 @@
+# 05: Deploy do Langfuse (com MinIO obrigatório)
+
+> **Avise o usuário onde você está:** o Langfuse é o **último serviço** do deploy (o painel que registra as conversas do agente). Diga que vai subir o Langfuse agora, é o último; ao terminar, confirme que o deploy dos serviços acabou e que agora vem a configuração do agente. Ver o princípio de narração em `SKILL.md`.
+
+## NÃO use o one-click do Coolify
+
+O template one-click declara os `LANGFUSE_S3_*` mas sobe **sem MinIO e com creds vazias**. Resultado: `POST /api/public/ingestion` dá **HTTP 500** (`Could not load credentials from any providers` → `Failed to upload events to blob storage`) e os traces **somem em silêncio**. Pior: `GET /api/public/projects` lê só o Postgres e retorna 200, então um "test connection" ingênuo **passa** e mascara a ingestion quebrada.
+
+## Use o compose vendorado do repo
+
+`templates/langfuse/docker-compose.coolify.yml`: topologia `langfuse` (web) + `langfuse-worker` + `postgres` + `redis` + `clickhouse` + **`minio`**, com as 3 famílias S3 (`EVENT_UPLOAD`/`MEDIA_UPLOAD`/`BATCH_EXPORT`) apontando pra `http://minio:9000` via as magic vars `SERVICE_USER_MINIO`/`SERVICE_PASSWORD_MINIO`. Deploy via `scripts/coolify.py create-service` (base64) + `set-fqdn` (abaixo). Detalhes e mapa magic-var↔env genérico: `templates/langfuse/README.md`.
+
+## Fluxo headless-seed (você provisiona TUDO num deploy; o usuário só faz login)
+
+Padrão oficial de headless-init do Langfuse, **validado empiricamente** (stack local com o compose deste template: o `LANGFUSE_INIT_USER` vira **OWNER** da org, o signup fica fechado desde o boot, o user semeado loga com `role:OWNER`, e as keys ingerem `207`). **Não deixe o signup aberto**: o Langfuse **não tem** o gate "primeiro-admin-depois-fecha" do Coolify/agents (`AUTH_DISABLE_SIGNUP=true` devolve `422` sempre, sem exceção pro 1º usuário), então signup aberto seria uma janela real pra qualquer um se cadastrar na instância exposta. Semeie tudo de uma vez:
+
+1. **Gere os valores do seed.** Um par de keys `pk-lf-…`/`sk-lf-…`, um id de org e um de projeto (strings únicas), e uma **senha temporária forte com um símbolo** pro login do operador (a política do Langfuse exige um caractere não-alfanumérico em signup/troca; o seed e o login aceitam sem, mas gere com). O **e-mail é o do operador, e você já o tem: NÃO pergunte.** Reuse **exatamente o mesmo e-mail do admin do Chatwoot** (etapa 3), pra ele ter um login só entre as ferramentas. **Nunca faça uma pergunta do tipo "qual e-mail você quer usar pro Langfuse/pro OWNER?"**: o usuário já criou o admin do Chatwoot com um e-mail, e é esse que vale aqui; perguntar de novo é retrabalho e confunde. Se por algum motivo você ainda não tem o e-mail do admin do Chatwoot em mãos, pegue-o de lá (etapa 3), não do usuário.
+2. **Semeie TUDO num deploy só** (o signup já nasce fechado: `AUTH_DISABLE_SIGNUP=true` é o default do template). Set na env do serviço (Coolify) ou no `.env` (genérico) e **deploy uma vez**:
+   - `LANGFUSE_INIT_USER_EMAIL` (operador), `LANGFUSE_INIT_USER_NAME`, `LANGFUSE_INIT_USER_PASSWORD` (a senha gerada)
+   - `LANGFUSE_INIT_ORG_ID`, `LANGFUSE_INIT_ORG_NAME`
+   - `LANGFUSE_INIT_PROJECT_ID`, `LANGFUSE_INIT_PROJECT_NAME`, `LANGFUSE_INIT_PROJECT_PUBLIC_KEY` (`pk-lf-…`), `LANGFUSE_INIT_PROJECT_SECRET_KEY` (`sk-lf-…`)
+
+   No boot o Langfuse cria o **usuário (OWNER da org) + org + projeto + keys**. O USER exige a ORG (por isso vão juntos); upsert **por id**, então re-deploy não duplica.
+3. **Entregue o login e mostre a senha temporária.** A URL do Langfuse em **`/auth/sign-in`** (login, **não** signup), o **e-mail dele + a senha gerada** (mostre a senha, é o único jeito de ele entrar), e peça pra **trocar no 1º acesso** pela UI. O seed é **create-if-not-exists** (validado: a troca de senha do operador **sobrevive** a redeploys, o `LANGFUSE_INIT_USER_PASSWORD` fica inerte), então a senha definitiva é a dele e nunca passou por você. Ele nunca abre "Settings → API Keys" nem copia key nenhuma.
+
+Como **você gerou** as keys no passo 1, elas já estão na sua mão pra ligar no fazer.ai agents (abaixo). Um deploy, sem redeploy, sem ler `org_id` no Postgres, e o signup **nunca** ficou aberto.
+
+## FQDN (preserve a porta)
+
+`scripts/coolify.py set-fqdn --ssh root@<VPS_IP> --app-id <id> --fqdn https://langfuse.<seu-dominio>:3000` (ache o id com `list-apps`). O template mapeia o FQDN pra porta 3000 do container; **dropar o `:3000` quebra o routing**. Ver `gotchas.md`.
+
+## Verifique a ingestion (health verde NÃO basta)
+
+`scripts/langfuse-verify.py` POSTa um batch em `/api/public/ingestion` e exige **207/200** (não 500); as chaves são o par que você semeou, lidas de um arquivo `0600` (a secret key fora do argv):
+```sh
+echo '{"publicKey":"<pk-lf>","secretKey":"<sk-lf>"}' > langfuse.keys && chmod 600 langfuse.keys
+python3 scripts/langfuse-verify.py ingestion --base-url https://langfuse.<seu-dominio>:3000 --keys-file langfuse.keys
+```
+Status 500 = quase sempre MinIO/S3 ausente.
+
+## Ligue no fazer.ai agents (por MCP, `langfuse_connect`)
+
+O wiring é **por MCP**, num tool só: `langfuse_connect` recebe `public_key`/`secret_key`/`base_url` **inline** (as keys que você semeou), cria a credencial no vault **já preenchida** (`kind:"langfuse"`, `{publicKey, secretKey}` + `baseUrl`) e liga o tracing no tenant-settings. É dry-run por padrão: revise o preview (keys redigidas) e reenvie com `dry_run:false` pra aplicar. Mesmo padrão do `deployment_connect` do Chatwoot (segredo de infra inline). Como as keys já existem, a credencial nasce **preenchida** (NÃO `pending`): uma entry pending não resolve o segredo e o tenant-settings rejeita com `credential ref not found`. (No vault o campo é `baseUrl` camelCase, ver `gotchas.md`; doc do tool em `docs/mcp.md`.)
+
+> **Ao pedir o OK do usuário** pra aplicar, fale do benefício, não do mecanismo: "vou ligar o painel que registra as conversas do agente, pra você acompanhar e depurar depois". **Não** cite `langfuse_connect`/"tracing"/"tenant-settings"/keys. Frases boas × ruins em `guardrails.md`.

package/dist/skills/agents-onboarding/references/06-setup-and-mcp.md

@@ -0,0 +1,47 @@
+# 06: `/setup` do fazer.ai agents + conectar o MCP
+
+## `/setup` (cria o 1º admin = SUPER_ADMIN)
+
+- Quando o banco está sem usuários, o fazer.ai agents abre o `/setup`. No boot ela loga um token único e a URL pronta `${PUBLIC_URL}/setup?token=...` (a menos que `SETUP_TOKEN_REQUIRED=false`).
+- O 1º admin é criado como **SUPER_ADMIN** (`tenant_id` NULL) via `POST /api/auth/setup`.
+- O **usuário** abre a URL `/setup` (com o token do boot) e cria o 1º admin. Você entrega a URL e **espera**; não cria por conta própria.
+- Config de boot relevante (defaults): `setupTokenRequired:true`, `signupEnabled:false`.
+
+### O tenant nasce do `companyName` do `/setup`: confira depois
+
+O `/setup` cria **um** tenant a partir do `companyName` que quem preenche o form digita. No **real**, é o usuário que digita: pode sair diferente do nome combinado (numa run real saiu `fazer.ai`/`fazer-ai` em vez de `Clínica Moreira`). Depois de conectar o MCP, rode **`tenant_list`** e **confira** o `name`/`slug`:
+- bate com o escolhido → siga.
+- divergiu → **NÃO crie outro tenant** (`tenant_create` é proibido, ver abaixo): siga com o que existe e **avise o usuário** da divergência. Renomear, se ele quiser, é `tenant_update` (não um tenant novo).
+
+## Conectar o MCP do fazer.ai agents (OAuth). GATE: sem as tools, PARE, não contorne
+
+Toda a config do fazer.ai agents (import do agente, vault, tenant-settings, KB, deployment/bind) é **exclusivamente via MCP tools**: elas carregam dry-run + audit + o fence de tenant. As tools de MCP só carregam no **boot** da sessão, e a **ordem do reinício muda por harness**: o Claude autentica na TUI (`/mcp`), que exige o server já carregado no boot, então reinicia **antes** de autenticar; Codex/Hermes autenticam por comando de CLI, então reiniciam **depois**. Endpoint do fazer.ai agents: `https://agentes.<seu-dominio>` (discovery/caminho exato em `docs/mcp.md`).
+
+**Claude Code** (reinicie ANTES de autenticar):
+1. **Adicione:** `claude mcp add` (transport HTTP) pro endpoint. O server entra no config, mas **não** aparece na sessão atual nem no `/mcp` (a sessão leu o config no boot).
+2. **Reinicie a sessão** (feche e reabra o `claude` no mesmo dir). Só agora o `/mcp` lista `fazer-ai` como **"Needs authentication"** (esperado, não é falha).
+3. **Autentique:** `/mcp` → `fazer-ai` → **Authenticate** → browser; o usuário loga com o admin do `/setup` (SUPER_ADMIN) e aprova os escopos (`mcp:read/write/admin`). Ao voltar **"Connected"**, as tools carregam **na mesma sessão, sem 2º reinício**.
+
+**Codex / Hermes** (autentique por CLI, depois reinicie):
+1. **Adicione + logue:** `codex mcp add` + `codex mcp login` (ou o equivalente do Hermes), que abre o browser pro mesmo login SUPER_ADMIN.
+2. **Reinicie a sessão.** As tools carregam no boot seguinte.
+
+O access token fica no store de MCP do harness, não conosco (`guardrails.md`).
+
+**GATE DURO. Se as tools `fazer-ai` (`whoami`, `tenant_list`, `agent_import`, …) NÃO estão expostas nesta sessão:**
+
+- **PARE e peça ao usuário pra completar o passo do harness dele** (Claude: **reiniciar → `/mcp` Authenticate**; Codex/Hermes: **`mcp login` → reiniciar**), confirmando o Authenticate/login **e** o reinício. Espere ele voltar. Esse é o **único** caminho.
+- **NUNCA contorne.** É **proibido**, para qualquer config do fazer.ai agents: chamar a **API REST direto** (mintar API key, cookie + `x-tenant-id`); fazer requisições ao endpoint `/mcp` **por fora do harness**; **ler o código-fonte/bundle do fazer.ai agents** (`/app/src`, `/app/dist`) pra descobrir endpoints internos; montar **OAuth manual**. Esses bypasses pulam dry-run/audit/fence, são frágeis, e **não provam o MCP**, que é o produto que esta run existe pra validar.
+- **Sinal de que você entrou no anti-padrão:** se você se pegou grepando `agents.controller.ts`, procurando `POST /api/v1/agents/import`, ou mintando uma API key pra "equivalente REST" porque "a tool não apareceu" → **PARE imediatamente** e peça o reinício. Não existe "fallback REST transitório" para config do fazer.ai agents. **Idem pra achar uma rota/deeplink do console:** não baixe+grepe o bundle da SPA; as rotas que a skill usa estão nas refs (ex.: o deeplink de credencial em `08-agent-import.md` §2), e o bundle é minificado/hasheado (frágil).
+
+## Alvo de tenant nas MCP tools (SUPER_ADMIN)
+
+O admin do `/setup` é **SUPER_ADMIN** (`tenant_id` NULL), então o token MCP é **fleet-level**: `whoami` mostra `tenantId: null`. Ele **não** carrega um tenant embutido; você escolhe o tenant **por chamada**:
+
+1. Logo após conectar, rode **`tenant_list`**: há **um** tenant (o criado pelo `/setup`, a partir do `companyName`). Anote o **slug** (ou o id).
+2. Em **toda tool per-tenant** (`agent_import`, `agent_*`, `vault_*`/`credential_create`, `tenant_settings_*`, `deployment_connect`/`inbox_bind`, `knowledge_*`, …) passe o argumento **`tenant`** com esse slug (ou id). O campo só aparece para tokens SUPER_ADMIN; para um token de tenant (API key) ele nem existe e o tenant é implícito.
+3. **NUNCA chame `tenant_create`.** O tenant já existe (o do `/setup`); criar outro gera um tenant **órfão**, e o agente/credenciais importados cairiam no lugar errado. Se uma per-tenant tool reclamar de *"fleet-level … pass `tenant`"* ou *"no tenant target"*, a causa é **faltar o argumento `tenant`**, não faltar um tenant: rode `tenant_list` e passe o `tenant`.
+
+## Prefixo dos paths (referência factual, NÃO um convite a usar REST)
+
+Onde estas refs citam `/v1/...` (ex.: `/v1/vault`, `/v1/chatwoot/deployment`), o path HTTP real é `/api/v1/...`. Isto é só pra você **ler** as refs corretamente e casar com as MCP tools equivalentes; **não** é autorização pra chamar REST: a config do fazer.ai agents vai por MCP (acima). A API key (`POST /api/v1/api-keys { "displayName": "..." }`, o campo é `displayName` não `name`) existe para integrações externas do usuário, não para a skill contornar o MCP.

package/dist/skills/agents-onboarding/references/08-agent-import.md

@@ -0,0 +1,55 @@
+# 08: Import do agente + credenciais + embedding + KB
+
+> **Ao falar com o usuário** nesta etapa, descreva o resultado, não a mecânica: "vou criar o agente de atendimento (a Maria, uma recepcionista de exemplo); ele nasce desligado e em modo de teste, então não fala com cliente até você liberar". Na hora de pedir as chaves que faltam, diga "faltam algumas chaves (ex.: a da OpenAI) pro agente funcionar; vou te mandar um link direto pra colar cada uma com segurança, elas não passam por mim". **Não** cite `agent_import`/`credential_create`/"pending"/"deeplink"/"vault"/"tenant". Frases boas × ruins em `guardrails.md`.
+
+## 1. Importar (`agent_import`, mcp:write)
+
+A skill traz o **agente padrão** vendorado em `samples/agents/maria-clinica-moreira.json` ("Maria", recepção da Clínica Moreira fictícia: agendamento, FAQ via KB, voz, Asaas). **Importe-o por padrão**; só use outro export se o usuário trouxer o dele. Leia o arquivo e passe o conteúdo como `export`:
+
+```jsonc
+agent_import { "export": <conteúdo de samples/agents/maria-clinica-moreira.json>, "tenant": "<slug do tenant_list>" }   // dry_run:true → preview, depois dry_run:false
+```
+
+- **SUPER_ADMIN:** inclua `tenant` (o slug/id de `tenant_list`); o token é fleet-level. **NUNCA** `tenant_create`: o tenant do `/setup` já existe; criar outro joga o agente no tenant errado (ver etapa 6).
+- O agente é **sempre** criado **disabled + test mode** (nunca vai ao ar pra cliente por acidente); componentes (KB/tools/etc.) recriados/reusados **por nome**.
+- Credenciais faltantes (os nomes não existem no tenant novo): o import cria uma entrada **pending** (mantendo o ref wired) e emite o aviso `credentialPending`; o usuário preenche no vault.
+- **Exceções** que não viram pending no import → `credentialNotFound`: (a) OAuth gerenciado (`google_oauth`, `mcp_oauth`), que nunca pode ser pending (vem de connect flow); (b) kinds que exigem `base_url`/`param_name`, porque o import não tem esses valores pra passar. Pra (b), crie explicitamente com `credential_create` passando `base_url`/`param_name` (ex.: `openai_compatible`); pra (a), trate o OAuth à parte.
+
+## 2. Preencher credenciais (segredo NUNCA passa pelo agente)
+
+- **Sempre entregue o deeplink**, nunca só "vá em Configurações → Credenciais". Cada pending abre direto pelo `fillAt = ${PUBLIC_URL}/resources/vault?fill=<vaultId>` (o `?fill=<id>` abre o modal de preenchimento da entrada). É o caminho canônico das credenciais do **usuário** (OpenAI/ElevenLabs/Gemini/Asaas). O formato está aqui; **não** baixe/grepe o bundle da SPA pra descobrir a rota/deeplink (minificado + hasheado, muda a cada build).
+- **De onde vem o `fillAt`:** um `credential_create` **real** (`dry_run:false`) devolve o `fillAt` na resposta. Mas o **dry-run não devolve**, e re-criar uma que já existe **duplica**. Pra uma pending que **já existe** (import/brownfield/run anterior), **não re-crie**: pegue o `id` no `vault_list` e monte a URL você mesmo (`${PUBLIC_URL}/resources/vault?fill=<id>`).
+- A chave OpenAI e as demais do **usuário** (ElevenLabs/Gemini/Asaas) o usuário preenche por esse deeplink; o segredo nunca passa pelo agente. Acompanhe pelo `vault_list` até o status sair de `pending`. (Exceção: o Langfuse, cujas keys **você** provisiona ao semear o projeto, não é segredo do usuário; ligue no fazer.ai agents via `langfuse_connect` com as keys inline, ver `references/05-langfuse.md`.)
+
+## 3. Religar o modelo + habilitar (`agent_update`)
+
+Habilite o agente **mantendo o test mode** (como ele foi importado). Habilitar liga o bot; o `mode:"test"` faz ele responder só em conversas ativadas com `/teste` (etapa 10) e ficar em silêncio nas demais (com uma nota privada), então ele **não** atende cliente real ainda. Ligar pra produção é o **passo final do usuário** (abaixo).
+
+```jsonc
+agent_update {
+  "agent_id": "<id>", "enabled": true,
+  "model_config": { "provider":"openai", "model":"gpt-5.4-mini", "temperature":0.3, "credentialRef":"<nome da vault entry>" }
+}
+```
+
+- **Não** mande `mode` aqui: o import já criou em `test` e a validação (etapa 10) roda nesse modo via `/teste`. Não promova pra `production` por conta própria.
+- Via MCP, `model_config.credentialRef` aceita o **nome** da entrada do vault (resolvido server-side). Via REST é a forma `"vault:<id>"`.
+- Mande o `model_config` **completo** pra não clobberar campos. (O STT pode reusar a mesma chave.)
+
+### Ir pra produção é decisão do usuário
+
+Depois do E2E aprovado (etapa 10), **o usuário** decide quando o agente vai ao ar pra clientes reais: aí sim `agent_update { "agent_id":"<id>", "mode":"production" }`. Entregue o agente validado em test mode e deixe esse flip pro usuário; não o faça no fluxo automático.
+
+## 4. Embedding é por-tenant (senão a KB falha)
+
+Ligue a credencial de embedding no tenant **via MCP**: `tenant_settings_update { embedding: { credential_ref: "<nome da entry>" } }` (provider/model default a `openai`/`text-embedding-3-small`). Sem isso (ou com a credencial ainda pendente) a KB **não indexa**: os docs ficam `UNINDEXED`, **não** FAILED (pré-requisito faltando não é falha). É no nível do **tenant**, não por-KB. O embedding usa a chave OpenAI, então ligue-o **depois** do usuário preencher o OpenAI (passo 2).
+
+## 5. Indexar a KB (`knowledge_reindex`)
+
+- Os docs do import entram **UNINDEXED**. Com o embedding ligado (passo 4) **e o OpenAI preenchido**, indexe a base inteira numa chamada **via MCP**: `knowledge_reindex { knowledge_base_id }` (dry-run por padrão; `dry_run:false` aplica).
+- **Se o pré-requisito ainda falta** (embedding não configurado, ou credencial pendente), o `knowledge_reindex` **não enfileira nada** e devolve `blocked` + `fillAt` (deeplink pra preencher a credencial); os docs **ficam UNINDEXED**, não FAILED. Entregue o `fillAt` ao usuário, espere preencher, e re-rode.
+- Pra recuperar docs que **de fato** falharam na ingestão (erro real, não pré-requisito), `knowledge_reindex { knowledge_base_id, include_failed:true }` re-enfileira os FAILED em lote (ou `knowledge_document_retry { document_id }` por doc).
+
+## 6. Gate antes de seguir
+
+Não declare o import pronto com aviso aberto: **todos os docs da KB READY** + **grounding verificado** no playground (pergunte algo que só a KB sabe); STT/TTS/visão sinalizados → conectar credencial ou desligar a feature. Detalhe + features opcionais (voz, Google OAuth) em [`agent-features.md`](agent-features.md).

package/dist/skills/agents-onboarding/references/09-chatwoot-bind.md

@@ -0,0 +1,41 @@
+# 09: Plugar o Chatwoot no fazer.ai agents
+
+> **Ao pedir o OK do usuário** para aplicar (cada `dry_run:false` abaixo), descreva o efeito, não a tool: "vou conectar o seu Chatwoot ao agente e ligar o robô na caixa de entrada, pra ele começar a responder as conversas". **Não** cite `deployment_connect`/`inbox_bind`/`webhook`/"Agent Bot". Frases boas × ruins em `guardrails.md`.
+
+Sequência MCP-first. As tools de deployment são `mcp:admin` (SUPER_ADMIN); `inbox_bind` é `mcp:write`. O admin token do Chatwoot **não é credencial de vault** (é guardado encriptado na linha do deployment), então **não** use o fluxo de pending/deeplink dele. Há dois caminhos pra entregá-lo, conforme quem tem o token (o **mesmo** vale para `chatwootSource: existing`, Chatwoot BYO): se a instância é on-box/alcançável por SSH, o agente pega o token via Rails runner (Caso A); se é off-box (Chatwoot Cloud / outro host), o usuário fornece o token (Caso B).
+
+## 1. Conectar o deployment
+
+### Caso A: o agente provisionou o Chatwoot (tem o token)
+
+O agente extraiu o admin token via Rails runner (etapa 3), então registra direto por MCP, em uma chamada:
+
+```jsonc
+deployment_connect { "base_url":"https://chatwoot.<seu-dominio>", "admin_token":"<token cru>" }  // dry_run:false pra aplicar
+```
+
+O token é usado in-band e **redatado no audit** (o audit guarda só metadados). Valida via `/profile`, **persiste o deployment** (URL + token criptografado na linha do deployment) e retorna as contas alcançáveis. Ainda **não** conecta as contas: isso é o passo 2.
+
+### Caso B: traga seu próprio Chatwoot (só o usuário tem o token)
+
+O agente **não** tem o token. Em vez de inventar credencial pending (o token nem é de vault), o agente **linka o usuário pra tela `/channels`**: em "Connect instance" (SUPER_ADMIN), o usuário cola Base URL + Admin access token (validado via `/profile`, guardado encriptado). O usuário pode seguir ali pelo "Manage accounts" e pelo bind de inbox, ou devolver pro agente continuar via MCP.
+
+## 2. Conectar a conta + sincronizar inboxes (`deployment_set_accounts`)
+
+```jsonc
+deployment_set_accounts { "account_ids": [1] }   // dry_run:false pra aplicar
+```
+
+Conecta as contas selecionadas (cria a instância + sincroniza os inboxes pra agents) e soft-desconecta as de-selecionadas. **É este passo que conecta as contas** (o `deployment_connect` só registrou o deployment e listou as contas).
+
+## 3. Bindar o inbox ao agente (`inbox_bind`)
+
+```jsonc
+inbox_bind { "inbox_id":"<id do inbox no fazer.ai agents>", "agent_id":"<id do agente>" }   // dry_run:false pra aplicar
+```
+
+O bind **provisiona/conecta o bot do agente no Chatwoot** (Agent Bot + webhook `/v1/chatwoot/webhook/:routeToken`); o `routeTokenHash`/`inboundSecretRef` ficam encriptados no fazer.ai agents e **nunca** saem no export. Não precisa setar `webhook_url` à mão. Verifique: bot-status do inbox = `active`.
+
+## Só MCP (nada de REST à mão)
+
+O fazer.ai agents expõe endpoints REST equivalentes por baixo (o que a tela `/channels` chama), mas **não os chame à mão**: as tools MCP `deployment_connect`/`inbox_bind` são o único caminho (regra MCP-only, ver `SKILL.md` e `06-setup-and-mcp.md`).

package/dist/skills/agents-onboarding/references/10-validate-e2e.md

@@ -0,0 +1,34 @@
+# 10: Validar E2E
+
+## Pré-condições
+
+- Agente importado e habilitado (`enabled:true`), **em test mode** (`mode:test`, como importado; a validação abaixo roda nesse modo via `/teste`; promover pra produção é decisão do usuário, etapa 8), modelo religado a uma vault key real (etapa 8).
+- KB com docs **READY** (etapa 8).
+- Inbox do Chatwoot bound ao agente, bot `active` (etapa 9).
+- Langfuse com ingestion **207** + wired no fazer.ai agents (etapas 5 e 8).
+
+## 1. Playground (modelo real, sem Chatwoot)
+
+Via MCP (preferido): `agent_playground` (mcp:read; aceita texto ou `attachment` base64/url, e `reply_with_audio`). Via REST: `POST /api/v1/agents/:id/playground`. O agente responde com o modelo real. Cheque **grounding**: pergunte algo coberto pela KB e confirme que a resposta usa o conteúdo indexado (não uma resposta genérica).
+
+## 2. Integração Chatwoot → agents via Inbox API (obrigatório, sem aparelho)
+
+Prova a ponta `incoming → webhook → turn → reply` **sem aparelho**, com um inbox `Channel::Api`:
+- Crie um inbox `Channel::Api` no Chatwoot e benda ao agente (`inbox_bind`, etapa 9), que auto-provisiona o Agent Bot + webhook.
+- Crie uma conversa e **ative o test mode nela**: injete uma mensagem **incoming** com o conteúdo exatamente `/teste`. Em test mode o agente fica em silêncio numa conversa até receber `/teste` (e deixa uma nota privada explicando o porquê); o `/teste` libera as respostas **só nessa conversa**. Sem ele a mensagem chega e espelha, mas o agente **não** responde: é o comportamento correto do test mode, não uma falha.
+- Agora injete a **mensagem real** de teste (incoming, `message_type: incoming`) na mesma conversa. **Monte o JSON da mensagem num arquivo UTF-8** e POSTe apontando pro arquivo (`curl --data @msg.json` ou helper): texto com acento montado inline no PowerShell volta corrompido (`Olá`→`Ol?`), ver `gotchas.md`.
+- Cadeia esperada: incoming → webhook (`/api/v1/chatwoot/webhook/:routeToken`) → **debounce** → turn → modelo real → resposta **outgoing** na conversa. Confirme a resposta + o `ExecutionLog`/trace no Langfuse.
+
+Este é o teste que **não pode ficar pendente**: é o que prova que bind + webhook funcionam. O agente segue em test mode depois disto; **não** promova pra produção (decisão do usuário, etapa 8).
+
+## 2b. WhatsApp real (opcional, confirma o transporte)
+
+Pareie a inbox real (Baileys via QR) com um número que o usuário controle e mande uma mensagem: mesma cadeia do passo 2, exercitando o transporte WhatsApp de verdade. Pode ficar pendente sem invalidar o core (a integração já foi provada no 2).
+
+## 3. Traces no Langfuse
+
+- Confirme que o turn aparece no Langfuse (env `production-playground` ou `production`, session = threadId do fazer.ai agents). A ingestion já foi validada em 207 na etapa 5.
+
+## Critério de aceite
+
+Responde no **playground** (com **KB grounding** confirmado) E na **integração via Inbox API** (conversa ativada com `/teste`, em test mode); **trace** no Langfuse. O **WhatsApp físico** é confirmação opcional (a integração já foi provada via Inbox API). O **Kanban** segue o passo 9b: happy-path quando há licença, ausente no OSS.