@fazer-ai/agents 1.0.0

package/dist/skills/agents-onboarding/references/agent-features.md

@@ -0,0 +1,61 @@
+# Pós-import: resolver avisos + ligar features do agente
+
+Depois do import (`08`), o agente entra **disabled + test**. Antes de validar (`10`), **resolva todos os
+avisos de configuração** (não bloqueiam o boot, mas degradam a qualidade) e ligue as features opcionais que
+o agente usa. Trate a seção 1 como **gate**, não como "nice to have".
+
+## 1. Avisos pós-import (gate, obrigatório)
+
+O editor do agente lista "Avisos de configuração". Resolva **cada um** (ou desligue a feature
+conscientemente):
+
+- **KB sem indexar.** Os docs do import entram UNINDEXED e só indexam com o embedding por-tenant ligado
+  + o OpenAI preenchido (sem isso ficam UNINDEXED, não FAILED). Sequência (detalhe em
+  [`08-agent-import.md`](08-agent-import.md) §4-5): setar embedding por-tenant → `knowledge_reindex` da
+  base (devolve `blocked` + `fillAt` se falta preencher a credencial; `include_failed:true` recupera
+  FAILED reais), até **todos READY**.
+  Depois **verifique grounding**: pergunte no playground algo que só a KB sabe e confirme que a resposta usa
+  o conteúdo indexado. KB não-READY = sem grounding = critério de aceite (`10`) não batido.
+- **STT/TTS/visão ligados sem chave.** Conecte a credencial (deeplink) **ou** desligue a feature. Não deixe
+  o aviso aberto.
+
+## 2. Voz (STT/TTS): opcional, por-agente
+
+MCP `agent_settings_set` (dry-run por padrão; `credentialRef` aceita o **nome** da entrada do vault):
+
+```jsonc
+agent_settings_set {
+  "agent_id": "<id>",
+  "stt": { "enabled": true, "provider": "openai", "model": "whisper-1", "language": "pt", "credentialRef": "<nome no vault>" },
+  "tts": { "mode": "mirror", "provider": "openai", "model": "tts-1", "voice": "alloy", "credentialRef": "<nome no vault>" }
+}   // dry_run:false pra aplicar
+```
+
+- Campos (fonte `src/modules/stt/settings.ts`, `src/modules/tts/settings.ts`): STT
+  `enabled/provider/model/language/credentialRef/baseURL`; TTS
+  `mode (never|mirror|preference)/provider/model/voice/credentialRef/normalize`. ElevenLabs exige `voice`.
+- **`agent_settings_set` é tool separada do `agent_update`** (este é nome/enabled/mode/modelConfig). Os
+  blocos de comportamento (stt/tts/split/handoff/etc.) vão pelo `agent_settings_set`.
+- REST equivalente: `PATCH /api/v1/agents/:id { settings: { stt, tts } }` (aqui o `credentialRef` tem que
+  ser `vault:<id>`; REST não resolve por nome).
+- A chave (OpenAI/ElevenLabs) é credencial do vault, preenchida por deeplink como qualquer outra (`08` §2).
+
+## 3. Google (Calendar/Drive): opcional, **fora do MCP por design**
+
+As tools de Google usam uma credencial kind `google_oauth`. **Não há MCP write tool pra conectar o Google**
+(o segredo e o consent nunca cruzam o MCP). É um fluxo de **console** (o usuário faz):
+
+1. Pré: no Google Cloud, um OAuth 2.0 Client ID (Web) com a redirect URI
+   **`${PUBLIC_URL}/api/v1/oauth/google/callback`** registrada.
+2. No console `/resources/vault`: criar credencial kind `google_oauth` com Client ID + Client Secret.
+3. Na `GoogleOAuthSection`: escolher os scopes (Calendar/Drive/...) → "Sign in with Google" → popup de
+   consent → o callback grava os tokens (criptografados) na entrada do vault.
+4. Status: "Connected as <email>". A partir daí, as tools de Calendar/Drive resolvem por `vault:<id>` (token
+   renovado automaticamente).
+
+Endpoints (fonte `src/api/v1/oauth-google.controller.ts`): `POST /api/v1/vault/:id/oauth/google/authorize {scopes}`,
+`GET /api/v1/oauth/google/callback`, `GET .../status`, `POST .../disconnect`. Não confundir com o login
+social do `docs/google-oauth.md` (é outra coisa).
+
+> Princípio: tudo o mais é MCP-first, mas **o connect do Google é console-only por design**. Entregue o
+> link/instrução ao usuário; o agente não vê o segredo.

package/dist/skills/agents-onboarding/references/chatwoot-hub-register.md

@@ -0,0 +1,69 @@
+# Licenciar a instância Chatwoot no hub (Kanban/Pro)
+
+Habilita as features **Pro** (Kanban etc.) numa instância Chatwoot **Pro já deployada**. Duas coisas são
+necessárias e **distintas**:
+
+- A **imagem Pro** (`harbor.fazer.ai/chatwoot/fazer-ai/chatwoot-pro`) traz o **código** (driver de Kanban,
+  Baileys). Sem ela, não há Pro. A edição é escolhida no deploy (ver [`03-chatwoot-pro.md`](03-chatwoot-pro.md)).
+- A **assinatura no hub** dá a habilitação em runtime: **imagem Pro sem assinatura ativa = features
+  travadas.** Por isso existe o passo do Refresh (não é restart de container).
+
+## Quando: happy-path se há licença
+
+A edição é decidida **no deploy** pelo marcador do CLI `~/.fazer-ai/onboarding.json`
+(`chatwootTier` + `chatwootLicenseId`), com fallback pro `hub licenses` se o marcador faltar:
+- **`chatwootTier: "pro"`** (ou, sem marcador, há licença CHATWOOT no hub) → deploy da **imagem Pro** e **estes passos são happy-path**: registrar + atachar (use `chatwootLicenseId`) + Refresh pra ligar o Kanban. Não pule.
+- **`chatwootTier: "community"`** (ou, sem marcador, sem licença) → deploy da imagem **OSS** (sem Kanban) e segue; nada a fazer aqui.
+- **`chatwootSource: "existing"`** (Chatwoot BYO, sem `chatwootTier` no marcador) → detecte Pro/OSS pela **imagem** (etapa 1b); não assuma Pro. Um Pro existente **sem** Kanban pode ser licenciado por estes passos, mas **não é forçado** (só se o usuário quiser); OSS não tem Kanban.
+
+> **Sem licença e o usuário quer Kanban?** Sugira virar membro Pro da comunidade do Lucas Moreira
+> ([lucasmoreira.ai](https://lucasmoreira.ai)): ganha licença grátis do Kanban (1 conta no plano mensal,
+> 2 ilimitadas no anual). Depois é só rodar o CLI de novo e escolher "já me tornei membro" pra a nova
+> licença aparecer; ou seguir em OSS.
+
+> Pré-requisitos: `FRONTEND_URL` setado no container do Chatwoot (vira o host que identifica a instância e
+> gateia o Refresh). As ops do hub saem pelo **proxy do CLI** (`bunx @fazer-ai/agents hub …`), que usa
+> o OAuth do `~/.fazer-ai/oauth.json` do bootstrap (sem hub MCP na sessão); se ele expirou (erro de auth),
+> o operador re-roda o CLI. Writes do hub são **dry-run por padrão** (aplique com `--apply`); mexa só na sua
+> própria licença/instância (ver `guardrails.md`).
+
+## Passos
+
+> **Ao pedir o OK do usuário** para aplicar (passos 2 a 4), fale em linguagem de usuário: "vou ativar o seu plano Pro nesta instalação, o que libera o Kanban no Chatwoot". **Não** cite `attach-license`, "Refresh da assinatura", "idempotente" nem os comandos: são o seu mecanismo. Frases boas × ruins em `guardrails.md`.
+
+1. **Identidade da instância.** Pegue o host/identifier que o hub casa, direto do Chatwoot (read-only, sem hub):
+   ```sh
+   python3 scripts/chatwoot-admin.py installation-id --ssh root@<VPS_IP> --container <chatwoot-rails-container>
+   ```
+   Devolve `frontend_url` (o host) + `installation_identifier`. O `identifier` que o hub usa é o **host** (ex.: `chatwoot.<seu-dominio>`).
+2. **Instância no hub.** Confira se já existe e crie se faltar (dry-run primeiro; `--apply` pra valer):
+   ```sh
+   bunx @fazer-ai/agents hub instances
+   bunx @fazer-ai/agents hub create-instance --identifier chatwoot.<seu-dominio> --apply
+   ```
+3. **Atacha a licença** (uma feature por instância; os tipos têm que bater). O `--instance` é o id que aparece em `hub instances`:
+   ```sh
+   bunx @fazer-ai/agents hub attach-license --license <licença CHATWOOT> --instance <id> --apply
+   ```
+4. **Refresh + verify na instância** (o botão "Refresh" do super admin) via `scripts/chatwoot-admin.py`, que roda o job e reporta os configs da assinatura (NÃO despeja valores crus que poderiam ser segredo):
+   ```sh
+   python3 scripts/chatwoot-admin.py refresh-subscription --ssh root@<VPS_IP> --container <chatwoot-rails-container>
+   ```
+   **`jitter_applied: true` é obrigatório** (o script já passa). Sem ele, o job só se reagenda (janela determinística de até 30 min) e o sync nem roda. A saída traz `config_keys` (deve listar os `FAZER_AI_SUBSCRIPTION_*`) e `diagnostics` (`SYNC_ERROR_MESSAGE` nil = ok; `VERIFIED_AT` recente = ok). No super admin (`/super_admin/settings`), "fazer.ai Subscription" fica ativa e o Kanban aparece.
+
+## Erros comuns
+
+- **`hub …` diz que "o hub não respondeu ao refresh da sessão" / instabilidade:** é **transitório** (a
+  sessão segue válida; o refresh token nem foi consumido): **rode o MESMO comando de novo** em instantes.
+  Só **"sessão expirada/ausente"** (erro de auth real) pede re-rodar o CLI de onboarding pra logar no
+  browser. Em nenhum dos casos contorne o `hub` indo por REST/MCP por fora: ou re-tenta, ou re-loga.
+- **Kanban não aparece com imagem Pro:** faltou o passo 3. A imagem traz o código; a assinatura libera em
+  runtime. Rode o Refresh.
+- **`FRONTEND_URL` vazio:** o controller do Refresh recusa, e o `installation_host` enviado ao hub fica
+  vazio. Sete antes.
+- **403 / inativo no `/api/ping`:** a licença não está atachada à instância certa no hub. Confira
+  `bunx @fazer-ai/agents hub get-license --license <id>` / `hub get-instance --instance <id>` (casamento por identifier/host).
+- **Assinatura "out of sync" > 3 dias:** o job auto-desativa (`auto_deactivate_if_stale`). Rode o Refresh
+  pra re-sincronizar.
+
+OSS não tem nada disso (sem Kanban). Migrar OSS → Pro = re-deploy com a imagem Pro + estes passos.

package/dist/skills/agents-onboarding/references/deploy-b-portainer.md

@@ -0,0 +1,138 @@
+# Deploy Tier B: Portainer
+
+Adapter de deploy **Tier B**. O agente, da máquina do operador, dirige um **Portainer** pela HTTP API:
+gera os secrets, deploya cada stack a partir de uma string de compose, e sobe um **Caddy bundled** que
+termina TLS com certificado real automático (sem labels Traefik, sem polling do socket). É o companion
+por-plataforma do [contrato (1c)](01c-pick-tier.md); os invariantes (duas roles de DB, pgvector, réplica
+única) valem igual. Para BYO-proxy use `templates/docker-compose.prod.yml`; o Tier B usa o Caddy-bundled
+`templates/docker-compose.portainer.yml`.
+
+## Artefatos (incluídos nesta skill, relativos à raiz dela)
+
+| Artefato | Papel |
+| --- | --- |
+| `templates/docker-compose.portainer.yml` | agents + Postgres + **Caddy bundled** (auto-HTTPS). Self-contained (uma string pro Portainer). |
+| `scripts/gen-onboarding-env.ts` | Gera o `.env` (duas roles de DB, JWT/ENCRYPTION, `CADDY_DOMAIN`, `ACME_EMAIL` opcional). |
+| `templates/chatwoot/` | Stack do Chatwoot, Pro (Harbor) ou OSS (público): um compose genérico, edição por env. Ver [`03-chatwoot-pro.md`](03-chatwoot-pro.md). |
+| `templates/langfuse/` | Langfuse opcional (tracing); inclui o MinIO que a ingestion v3 exige. Ver [`05-langfuse.md`](05-langfuse.md). |
+| `scripts/portainer-brownfield.py` | Descoberta brownfield read-only (inventário + decisão por serviço) via a API do Portainer. |
+
+## Por que self-contained + Caddy bundled
+
+A API "deploy from string" do Portainer recebe **um** documento de compose, então o
+`templates/docker-compose.portainer.yml` repete app + postgres e adiciona um serviço `caddy`. O Caddy monta o
+Caddyfile a partir do env no boot (`CADDY_DOMAIN` → o app; `PORTAINER_DOMAIN` opcional → o painel via
+`host.docker.internal:9443`) e obtém certs via ACME (tls-alpn-01 / http-01).
+
+## Pré-requisitos
+
+- **DNS**: A-records pro FQDN do app (ex. `agentes.<domínio>`) e, se quiser o painel num domínio limpo,
+  `portainer.<domínio>` → o IP do VPS. O ACME valida contra eles, então têm que resolver **antes** do deploy.
+- **Credenciais de registry** pras imagens privadas (configure uma vez no Portainer, passe `Registries:[id]`):
+  - `ghcr.io` pra `ghcr.io/fazer-ai/agents` (e pgvector/baileys). Token do GitHub com `read:packages`.
+  - `harbor.fazer.ai` pro Chatwoot **Pro** (e fazer.ai agents Pro): a registry credential **per-user**, provisionada
+    pelo proxy do CLI (`bunx @fazer-ai/agents hub registry-credential --apply --out harbor.secret`; imprime o
+    `username`, grava o secret em `harbor.secret`). Chatwoot OSS não precisa de registry privado.
+
+## 1. Instalar o Portainer
+
+```sh
+docker volume create portainer_data
+docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always \
+  -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data \
+  portainer/portainer-ce:lts
+```
+
+O Portainer 2.39+ exige criar o primeiro admin numa janela que tranca ~5 min após o start (reinicie o container pra reabrir). O **usuário** cria o 1º admin **no browser** em `https://<ip>:9443` (você entrega o link e **espera**) e, em *User settings → Access tokens*, gera uma **API key** (`<api-key>`) que te passa. Nunca crie o admin por conta própria.
+
+Com a API key (header `X-API-Key`), ache o endpoint id (o ambiente Docker local, geralmente `1`; crie se a lista vier vazia):
+
+```sh
+curl -sk https://localhost:9443/api/endpoints -H "X-API-Key: <api-key>"
+# se vazio, crie o endpoint local:
+curl -sk -X POST https://localhost:9443/api/endpoints -H "X-API-Key: <api-key>" -F Name=local -F EndpointCreationType=1
+```
+```
+
+## 2. Registrar os registries privados (uma vez)
+
+```sh
+curl -sk -X POST https://localhost:9443/api/registries -H "X-API-Key: <api-key>" -H 'Content-Type: application/json' \
+  -d '{"Name":"ghcr","Type":3,"URL":"ghcr.io","Authentication":true,"Username":"<gh-user>","Password":"<gh-token>"}'
+# Só Pro:
+curl -sk -X POST https://localhost:9443/api/registries -H "X-API-Key: <api-key>" -H 'Content-Type: application/json' \
+  -d '{"Name":"harbor","Type":3,"URL":"harbor.fazer.ai","Authentication":true,"Username":"robot$...","Password":"<secret>"}'
+```
+
+`Type:3` é registry Custom (serve pra qualquer). Capture cada `Id` e passe no array `Registries` do stack
+pra o `pull_policy: always` autenticar.
+
+## 3. Deploy do stack agents
+
+Gere o env, depois crie o stack a partir da string de compose:
+
+```sh
+bun scripts/gen-onboarding-env.ts --public-url https://agentes.<domínio> --acme-email voce@<domínio>
+# -> .env com CADDY_DOMAIN, as duas URLs de role do DB, JWT_SECRET, ENCRYPTION_KEY. Adicione
+#    PORTAINER_DOMAIN pra também servir o painel pelo mesmo Caddy.
+
+curl -sk -X POST "https://localhost:9443/api/stacks/create/standalone/string?endpointId=1" \
+  -H "X-API-Key: <api-key>" -H 'Content-Type: application/json' \
+  -d "$(jq -n --arg c "$(cat templates/docker-compose.portainer.yml)" --argjson env "$ENV_JSON" \
+        '{Name:"agents", StackFileContent:$c, Env:$env, Registries:[<ghcr-id>]}')"
+```
+
+`Env` é um array de `{name,value}` do `.env` gerado. O entrypoint da imagem roda **db-bootstrap →
+migrate → serve**; o Caddy obtém o(s) cert(s) no primeiro boot. Atualize um stack depois com
+`PUT /api/stacks/{id}?endpointId=1` (`{StackFileContent, Env, PullImage:true, Prune:false}`).
+
+## 4. Verificar
+
+```sh
+curl -sS -o /dev/null -w '%{http_code} verify=%{ssl_verify_result}\n' https://agentes.<domínio>/api/health   # 200 verify=0
+echo | openssl s_client -connect agentes.<domínio>:443 -servername agentes.<domínio> 2>/dev/null \
+  | openssl x509 -noout -issuer   # issuer= ... O=Let's Encrypt
+```
+
+Um "stack deployed" verde no Portainer não basta: confirme que o issuer do cert é Let's Encrypt e que
+`/api/auth/me` retorna JSON (`setupRequired:true` num DB novo). HTTP→HTTPS é um 308 do Caddy.
+
+## 5. Chatwoot + Langfuse
+
+Deploye `templates/chatwoot/` (Pro vs OSS por edição, ver [`03-chatwoot-pro.md`](03-chatwoot-pro.md)) e, se
+selecionado, `templates/langfuse/` (ver [`05-langfuse.md`](05-langfuse.md)) do mesmo jeito (stack-create from
+string + `Env[]` + os `Registries` relevantes). Frontear `chatwoot.<domínio>` / `langfuse.<domínio>` com
+TLS: aponte um site Caddy pra porta publicada de cada um, ou dê a cada um seu stack e deixe o Caddy
+compartilhado fazer o proxy.
+
+## Brownfield: o Portainer já tem serviços
+
+Quando o operador escolheu Portainer mas **já roda Portainer + alguns serviços** (ex. Chatwoot), sonde
+antes de instalar e decida **por serviço**, nunca destrua dados do operador. A sondagem é nativa da API do
+Portainer (o equivalente Coolify é a etapa [`01b-brownfield.md`](01b-brownfield.md)):
+
+```sh
+PORTAINER_API_KEY=$KEY PORTAINER_ENDPOINT_ID=1 python3 scripts/portainer-brownfield.py
+```
+
+Ele lista os stacks, faz fingerprint de cada container por imagem, sinaliza **quem ocupa 80/443** (um
+ingress existente faz o stack Caddy-bundled conflitar → reuse-o ou troque pro `templates/docker-compose.prod.yml`
+BYO-proxy) e imprime uma matriz de decisão: `agents` saudável → reusa; Chatwoot presente → reusa
+(`chatwoot-pro` Harbor e OSS são ambos válidos); Chatwoot ausente → instala Pro se há assinatura no hub,
+senão OSS; Langfuse ausente → instala só se selecionado.
+
+## Gotcha: o header de auth do Chatwoot pelo Caddy bundled
+
+O Chatwoot documenta o header de auth da API como `api_access_token` (underscores), mas reverse proxies
+descartam headers com underscore no nome (nginx tem `underscores_in_headers off`; o Caddy bundled do
+Chatwoot também descarta). Efeito: o mesmo admin token enviado ao Chatwoot **pelo Caddy** como
+`api_access_token` é rejeitado (401), enquanto **direto no puma** (sem proxy) autentica (200). O Rails
+(Rack) mapeia `-` e `_` pra mesma env var, então a grafia com **hífen** `api-access-token` é lida igual
+pelo Chatwoot **e** sobrevive ao Caddy (200). O fazer.ai agents **manda o hífen** por padrão, então `deployment_connect`
+e as tools HTTP do agente funcionam contra a URL pública fronteada pelo Caddy sem workaround. Se você
+escrever uma integração Chatwoot à mão, use `api-access-token`, nunca o underscore.
+
+## O que entrega ao contrato
+
+Os 5 outputs do [contrato (1c)](01c-pick-tier.md): `agentes.`/`chatwoot.`/`langfuse.` em HTTPS, agents com as
+duas roles + token de `/setup`, admin token do Chatwoot, Langfuse+MinIO. → siga pra **etapa 6**.

package/dist/skills/agents-onboarding/references/deploy-c-compose.md

@@ -0,0 +1,64 @@
+# Deploy Tier C: Compose genérico (VM crua ou painel sem trilha dedicada)
+
+O caminho catch-all: tudo que não é Coolify (Tier A) nem Portainer (Tier B). Cobre dois casos com a mesma
+base de artefatos:
+
+- **VM crua**, só Docker + `docker compose`: você sobe cada stack à mão e cuida do TLS.
+- **Painel sem trilha dedicada** (Easypanel, Dokploy, CapRover, etc.): **não há doc específico na skill, por
+  escolha.** Pegue os passos genéricos abaixo e adapte ao painel com o que você já sabe dele (como ele cria
+  um projeto Compose, injeta env, e anexa domínio + emite TLS). O alvo é sempre o
+  [contrato (1c)](01c-pick-tier.md); o painel é só o meio.
+
+## Tem um painel? Adapte, não procure trilha
+
+O padrão de qualquer painel PaaS (Easypanel/Dokploy/CapRover/…) é o mesmo:
+
+- O **proxy do painel** (Traefik/nginx embutido) detém 80/443 e emite Let's Encrypt ao **anexar um domínio**
+  a um serviço. Logo, use o `templates/docker-compose.prod.yml` (BYO-proxy, **sem** o Caddy bundled) e deixe o painel
+  rotear + certificar. Um Caddy nosso brigaria pelas portas.
+- O env vem do **`.env` que você controla** (não há magic vars do Coolify): gere com o
+  `scripts/gen-onboarding-env.ts` e cole as vars no serviço pelo painel.
+- Cada stack (fazer.ai agents, Chatwoot, Langfuse) vira um projeto Compose; anexe `agentes.`/`chatwoot.`/`langfuse.` a
+  cada um. Detalhes de UI/API variam por produto e versão: resolva com seu conhecimento do painel da run.
+
+Daqui em diante os passos são os mesmos da VM crua; só muda o "como" você aplica o compose + env.
+
+## TLS na VM crua: duas opções
+
+- **Caddy bundled** (recomendado se a VM tem 80/443 **livres**): use o `templates/docker-compose.portainer.yml` pra
+  agents. Ele já traz um Caddy que emite Let's Encrypt automático a partir de `CADDY_DOMAIN`/`ACME_EMAIL`
+  (gerados no `.env`).
+- **BYO-proxy** (se já há nginx/Caddy/Traefik na 443, ou é um painel): use o `templates/docker-compose.prod.yml` (sem
+  Caddy) e aponte o proxy pra porta publicada do app. O inventário ([1b](01b-brownfield.md)) diz quem ocupa
+  80/443.
+
+## Passos
+
+1. **DNS primeiro** (A-records resolvendo antes do ACME; ver [1c](01c-pick-tier.md)).
+2. **Env:** `bun scripts/gen-onboarding-env.ts --public-url https://agentes.<domínio> --acme-email
+   voce@<domínio>` gera o `.env` (duas roles, secrets, URLs, `CADDY_DOMAIN`). Chatwoot/Langfuse têm env
+   próprio (ver [`03-chatwoot-pro.md`](03-chatwoot-pro.md) e [`05-langfuse.md`](05-langfuse.md)).
+3. **Suba cada stack** (a partir da raiz desta skill, com o `.env` ao lado; num painel, o equivalente é
+   criar cada projeto Compose):
+   ```sh
+   docker compose -f templates/docker-compose.portainer.yml up -d       # agents + postgres + Caddy (ou .prod.yml + proxy)
+   docker compose -f templates/chatwoot/docker-compose.yml up -d  # Pro vs OSS pelo env (03-chatwoot-pro.md)
+   docker compose -f templates/langfuse/docker-compose.yml up -d  # com MinIO (obrigatório)
+   ```
+4. **Boot do fazer.ai agents:** o CMD da imagem faz `bootstrap → migrate → serve`; **não** sobrescreva `command:`.
+5. **Token do `/setup`** e **admin token do Chatwoot** saem dos logs (`docker compose logs`) / Rails runner,
+   igual aos outros tiers.
+6. **Verifique** (200 + cert Let's Encrypt) e **siga pra etapa 6**.
+
+## Brownfield
+
+Se a VM/painel já roda algum serviço, sonde com a etapa [1b](01b-brownfield.md) (a sondagem via
+`docker ps`/`ss` cobre o caso sem painel; num painel, use a API/UI dele pra inventariar) e **reuse** o que
+estiver saudável.
+
+## O que entrega ao contrato
+
+Os 5 outputs do [1c](01c-pick-tier.md). **Lacuna conhecida:** quando você usa o Caddy bundled só pra agents, o
+fronting TLS de `chatwoot.`/`langfuse.` precisa de um site Caddy/proxy adicional apontando pra porta
+publicada de cada um (a seção "Chatwoot + Langfuse" de [`deploy-b-portainer.md`](deploy-b-portainer.md)
+descreve esse mesmo padrão).

package/dist/skills/agents-onboarding/samples/agents/README.md

@@ -0,0 +1,23 @@
+# Sample agents
+
+Exemplos de agentes no schema de export **`fazer-ai.agent` v1** (o mesmo formato que `POST /v1/agents/import`
+/ a write tool `agent_import` do MCP consomem). Servem para testar o import, o onboarding e a documentação.
+
+| Arquivo | Persona |
+| --- | --- |
+| `maria-clinica-moreira.json` | "Maria", recepção de uma clínica fictícia (Clínica Moreira): agendamento, FAQ, voz, KB. |
+
+## Credenciais são por NOME, não por valor
+
+O export **não carrega segredos**: cada credencial é referenciada por **nome** (`credentialRef`). Ao importar
+num tenant novo, os refs não resolvem automaticamente: crie entradas no vault com os mesmos nomes (ou
+re-aponte via `PATCH /v1/agents/:id`). Os nomes neste sample são genéricos de propósito:
+
+- `OpenAI`: modelo (`gpt-5.4-mini`) + STT.
+- `ElevenLabs`: TTS.
+- `Google Gemini`: visão.
+- `Google OAuth2`: integrações Google Calendar + Drive.
+- `Asaas`: integração de cobrança.
+
+IDs específicos de ambiente foram neutralizados (ex.: o Google Calendar usa `primary`). Não há chaves,
+tokens ou IDs reais no arquivo: pode versionar e publicar à vontade.