@fazer-ai/agents 1.0.0

package/dist/skills/agents-onboarding/templates/langfuse/docker-compose.coolify.yml

@@ -0,0 +1,189 @@
+# Langfuse v3 (self-hosted) for fazer.ai: COOLIFY flavor.
+#
+# WHY THIS FILE EXISTS
+# The Langfuse one-click/Coolify template ships the S3 env var NAMES but leaves the
+# credentials + endpoint EMPTY and bundles NO object-storage service. Langfuse v3 REQUIRES an
+# S3-compatible blob store for trace ingestion: every event JSON is uploaded to S3 BEFORE it is
+# queued to ClickHouse. With empty creds the AWS SDK throws "Could not load credentials from any
+# providers", the upload fails, and `POST /api/public/ingestion` returns HTTP 500, so NO trace is
+# ever stored. The trap: `GET /api/public/projects` reads Postgres only, returns 200, and a naive
+# "connection test" PASSES, hiding the broken ingestion. This compose bundles MinIO and wires all
+# three S3 families (event / media / batch-export) to it.
+#
+# MAGIC VARS: Coolify auto-generates every `SERVICE_*` value on first deploy (incl.
+# SERVICE_USER_MINIO / SERVICE_PASSWORD_MINIO) and injects it. Never hardcode a secret here.
+#
+# Generic / Portainer / EasyPanel / Dokploy (manual env): use ./docker-compose.yml + ./.env.example.
+
+x-langfuse-env: &langfuse-env
+  # ── core ──
+  DATABASE_URL: 'postgresql://${SERVICE_USER_POSTGRES}:${SERVICE_PASSWORD_POSTGRES}@postgres:5432/${POSTGRES_DB:-langfuse-db}'
+  SALT: '${SERVICE_PASSWORD_SALT}'
+  ENCRYPTION_KEY: '${SERVICE_PASSWORD_64_LANGFUSE}'
+  NEXTAUTH_SECRET: '${SERVICE_BASE64_NEXTAUTHSECRET}'
+  NEXTAUTH_URL: '${SERVICE_URL_LANGFUSE}'
+  TELEMETRY_ENABLED: 'false'
+  LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES: 'false'
+  # Agent flips this: 'false' for the initial deploy (so the user can self-register in the browser),
+  # then 'true' after the project + keys are seeded, to close signup. Default 'true' (secure) if unset.
+  AUTH_DISABLE_SIGNUP: '${AUTH_DISABLE_SIGNUP:-true}'
+  HOSTNAME: 0.0.0.0
+  # ── clickhouse ──
+  CLICKHOUSE_MIGRATION_URL: 'clickhouse://clickhouse:9000'
+  CLICKHOUSE_URL: 'http://clickhouse:8123'
+  CLICKHOUSE_USER: '${SERVICE_USER_CLICKHOUSE}'
+  CLICKHOUSE_PASSWORD: '${SERVICE_PASSWORD_CLICKHOUSE}'
+  CLICKHOUSE_CLUSTER_ENABLED: 'false'
+  # ── redis ──
+  REDIS_HOST: redis
+  REDIS_PORT: '6379'
+  REDIS_AUTH: '${SERVICE_PASSWORD_REDIS}'
+  # ── blob storage (MinIO): THE PIECE THE ONE-CLICK OMITTED ──
+  LANGFUSE_USE_AZURE_BLOB: 'false'
+  LANGFUSE_S3_EVENT_UPLOAD_BUCKET: langfuse
+  LANGFUSE_S3_EVENT_UPLOAD_REGION: auto
+  LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT: 'http://minio:9000'
+  LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID: '${SERVICE_USER_MINIO}'
+  LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY: '${SERVICE_PASSWORD_MINIO}'
+  LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE: 'true'
+  LANGFUSE_S3_EVENT_UPLOAD_PREFIX: events/
+  LANGFUSE_S3_MEDIA_UPLOAD_BUCKET: langfuse
+  LANGFUSE_S3_MEDIA_UPLOAD_REGION: auto
+  LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: 'http://minio:9000'
+  LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID: '${SERVICE_USER_MINIO}'
+  LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY: '${SERVICE_PASSWORD_MINIO}'
+  LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE: 'true'
+  LANGFUSE_S3_MEDIA_UPLOAD_PREFIX: media/
+  LANGFUSE_S3_BATCH_EXPORT_ENABLED: 'false'
+  LANGFUSE_S3_BATCH_EXPORT_BUCKET: langfuse
+  LANGFUSE_S3_BATCH_EXPORT_REGION: auto
+  LANGFUSE_S3_BATCH_EXPORT_ENDPOINT: 'http://minio:9000'
+  LANGFUSE_S3_BATCH_EXPORT_ACCESS_KEY_ID: '${SERVICE_USER_MINIO}'
+  LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY: '${SERVICE_PASSWORD_MINIO}'
+  LANGFUSE_S3_BATCH_EXPORT_FORCE_PATH_STYLE: 'true'
+  LANGFUSE_S3_BATCH_EXPORT_PREFIX: exports/
+  # ── ingestion tuning (matches the one-click defaults) ──
+  LANGFUSE_INGESTION_QUEUE_DELAY_MS: '1'
+  LANGFUSE_INGESTION_CLICKHOUSE_WRITE_INTERVAL_MS: '1000'
+  # ── email (optional; blank = console only) ──
+  EMAIL_FROM_ADDRESS: admin@example.com
+  SMTP_CONNECTION_URL: ''
+
+services:
+  langfuse:
+    image: 'langfuse/langfuse:3'
+    environment:
+      <<: *langfuse-env
+      # ── headless seed (agent-driven; empty = no seed) ──
+      # The agent provisions EVERYTHING on the first boot: a user (org owner) + org + project + key pair,
+      # with AUTH_DISABLE_SIGNUP=true from the start (default above), so signup is never open. The operator
+      # SIGNS IN (never signs up) with the seeded email + password and changes it; the agent already holds
+      # the keys (it generated them) and wires them into fazer.ai agents. One deploy, no redeploy, no open
+      # signup window; this is Langfuse's own recommended headless-init pattern. See references/05-langfuse.md.
+      # On Coolify the agent sets these via the service env editor / API before the (single) deploy.
+      LANGFUSE_INIT_ORG_ID: '${LANGFUSE_INIT_ORG_ID:-}'
+      LANGFUSE_INIT_ORG_NAME: '${LANGFUSE_INIT_ORG_NAME:-}'
+      LANGFUSE_INIT_PROJECT_ID: '${LANGFUSE_INIT_PROJECT_ID:-}'
+      LANGFUSE_INIT_PROJECT_NAME: '${LANGFUSE_INIT_PROJECT_NAME:-}'
+      LANGFUSE_INIT_PROJECT_PUBLIC_KEY: '${LANGFUSE_INIT_PROJECT_PUBLIC_KEY:-}'
+      LANGFUSE_INIT_PROJECT_SECRET_KEY: '${LANGFUSE_INIT_PROJECT_SECRET_KEY:-}'
+      LANGFUSE_INIT_USER_EMAIL: '${LANGFUSE_INIT_USER_EMAIL:-}'
+      LANGFUSE_INIT_USER_NAME: '${LANGFUSE_INIT_USER_NAME:-}'
+      LANGFUSE_INIT_USER_PASSWORD: '${LANGFUSE_INIT_USER_PASSWORD:-}'
+      # Coolify routes the public FQDN to this container's port 3000 via these magic vars.
+      SERVICE_FQDN_LANGFUSE_3000: '${SERVICE_FQDN_LANGFUSE_3000}'
+      SERVICE_URL_LANGFUSE_3000: '${SERVICE_URL_LANGFUSE_3000}'
+    depends_on:
+      postgres: { condition: service_healthy }
+      redis: { condition: service_healthy }
+      clickhouse: { condition: service_healthy }
+      minio: { condition: service_healthy }
+    healthcheck:
+      test: ['CMD', 'wget', '-q', '--spider', 'http://127.0.0.1:3000/api/public/health']
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    restart: unless-stopped
+
+  langfuse-worker:
+    image: 'langfuse/langfuse-worker:3'
+    environment:
+      <<: *langfuse-env
+    depends_on:
+      postgres: { condition: service_healthy }
+      redis: { condition: service_healthy }
+      clickhouse: { condition: service_healthy }
+      minio: { condition: service_healthy }
+    restart: unless-stopped
+
+  minio:
+    image: 'minio/minio'
+    # Path-style bucket "langfuse" == the /data/langfuse directory; pre-creating it avoids a
+    # separate `mc mb` init container (this is the upstream Langfuse self-host recipe).
+    entrypoint: sh
+    command: -c 'mkdir -p /data/langfuse && minio server --address ":9000" --console-address ":9001" /data'
+    environment:
+      MINIO_ROOT_USER: '${SERVICE_USER_MINIO}'
+      MINIO_ROOT_PASSWORD: '${SERVICE_PASSWORD_MINIO}'
+    volumes:
+      - 'minio-data:/data'
+    healthcheck:
+      test: ['CMD', 'mc', 'ready', 'local']
+      interval: 5s
+      timeout: 5s
+      retries: 10
+      start_period: 5s
+    restart: unless-stopped
+
+  postgres:
+    image: 'postgres:17-alpine'
+    environment:
+      POSTGRES_DB: '${POSTGRES_DB:-langfuse-db}'
+      POSTGRES_USER: '${SERVICE_USER_POSTGRES}'
+      POSTGRES_PASSWORD: '${SERVICE_PASSWORD_POSTGRES}'
+    volumes:
+      - 'langfuse-postgres-data:/var/lib/postgresql/data'
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}']
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    restart: unless-stopped
+
+  redis:
+    image: 'redis:8'
+    command:
+      - sh
+      - '-c'
+      - 'redis-server --requirepass "$SERVICE_PASSWORD_REDIS"'
+    volumes:
+      - 'langfuse-redis-data:/data'
+    healthcheck:
+      test: ['CMD-SHELL', 'redis-cli -a "$SERVICE_PASSWORD_REDIS" ping | grep -q PONG']
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    restart: unless-stopped
+
+  clickhouse:
+    image: 'clickhouse/clickhouse-server:26.2.4.23'
+    environment:
+      CLICKHOUSE_DB: '${CLICKHOUSE_DB:-default}'
+      CLICKHOUSE_USER: '${SERVICE_USER_CLICKHOUSE}'
+      CLICKHOUSE_PASSWORD: '${SERVICE_PASSWORD_CLICKHOUSE}'
+    volumes:
+      - 'langfuse-clickhouse-data:/var/lib/clickhouse'
+      - 'langfuse-clickhouse-logs:/var/log/clickhouse-server'
+    healthcheck:
+      test: 'wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1'
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    restart: unless-stopped
+
+volumes:
+  minio-data:
+  langfuse-postgres-data:
+  langfuse-redis-data:
+  langfuse-clickhouse-data:
+  langfuse-clickhouse-logs:

package/dist/skills/agents-onboarding/templates/langfuse/docker-compose.yml

@@ -0,0 +1,185 @@
+# Langfuse v3 (self-hosted) for fazer.ai: GENERIC flavor (Portainer / EasyPanel / Dokploy / plain Docker).
+#
+# Same topology as ./docker-compose.coolify.yml, but every secret comes from a .env you fill in
+# manually (Coolify generates those automatically; here you don't have that, so see ./.env.example
+# and generate strong values yourself). Read ./README.md first, especially WHY MinIO is mandatory.
+#
+#   cp .env.example .env   # then fill every CHANGE_ME, then:
+#   docker compose up -d
+#
+# Put a reverse proxy (Traefik/Caddy/nginx) in front of the langfuse service (port 3000) for TLS.
+# Portainer: paste this file as a Stack and provide the same variables via the Stack env editor
+# instead of a .env file.
+
+x-langfuse-env: &langfuse-env
+  # ── core ──
+  DATABASE_URL: 'postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}'
+  SALT: '${LANGFUSE_SALT}'
+  ENCRYPTION_KEY: '${LANGFUSE_ENCRYPTION_KEY}'
+  NEXTAUTH_SECRET: '${LANGFUSE_NEXTAUTH_SECRET}'
+  NEXTAUTH_URL: '${LANGFUSE_PUBLIC_URL}'
+  TELEMETRY_ENABLED: 'false'
+  LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES: 'false'
+  # Agent flips this: 'false' for the initial deploy (so the user can self-register in the browser),
+  # then 'true' after the project + keys are seeded, to close signup. Default 'true' (secure) if unset.
+  AUTH_DISABLE_SIGNUP: '${AUTH_DISABLE_SIGNUP:-true}'
+  HOSTNAME: 0.0.0.0
+  # ── clickhouse ──
+  CLICKHOUSE_MIGRATION_URL: 'clickhouse://clickhouse:9000'
+  CLICKHOUSE_URL: 'http://clickhouse:8123'
+  CLICKHOUSE_USER: '${CLICKHOUSE_USER}'
+  CLICKHOUSE_PASSWORD: '${CLICKHOUSE_PASSWORD}'
+  CLICKHOUSE_CLUSTER_ENABLED: 'false'
+  # ── redis ──
+  REDIS_HOST: redis
+  REDIS_PORT: '6379'
+  REDIS_AUTH: '${REDIS_PASSWORD}'
+  # ── blob storage (MinIO): MANDATORY for ingestion; see README ──
+  LANGFUSE_USE_AZURE_BLOB: 'false'
+  LANGFUSE_S3_EVENT_UPLOAD_BUCKET: langfuse
+  LANGFUSE_S3_EVENT_UPLOAD_REGION: auto
+  LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT: 'http://minio:9000'
+  LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID: '${MINIO_ROOT_USER}'
+  LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY: '${MINIO_ROOT_PASSWORD}'
+  LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE: 'true'
+  LANGFUSE_S3_EVENT_UPLOAD_PREFIX: events/
+  LANGFUSE_S3_MEDIA_UPLOAD_BUCKET: langfuse
+  LANGFUSE_S3_MEDIA_UPLOAD_REGION: auto
+  LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: 'http://minio:9000'
+  LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID: '${MINIO_ROOT_USER}'
+  LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY: '${MINIO_ROOT_PASSWORD}'
+  LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE: 'true'
+  LANGFUSE_S3_MEDIA_UPLOAD_PREFIX: media/
+  LANGFUSE_S3_BATCH_EXPORT_ENABLED: 'false'
+  LANGFUSE_S3_BATCH_EXPORT_BUCKET: langfuse
+  LANGFUSE_S3_BATCH_EXPORT_REGION: auto
+  LANGFUSE_S3_BATCH_EXPORT_ENDPOINT: 'http://minio:9000'
+  LANGFUSE_S3_BATCH_EXPORT_ACCESS_KEY_ID: '${MINIO_ROOT_USER}'
+  LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY: '${MINIO_ROOT_PASSWORD}'
+  LANGFUSE_S3_BATCH_EXPORT_FORCE_PATH_STYLE: 'true'
+  LANGFUSE_S3_BATCH_EXPORT_PREFIX: exports/
+  # ── ingestion tuning ──
+  LANGFUSE_INGESTION_QUEUE_DELAY_MS: '1'
+  LANGFUSE_INGESTION_CLICKHOUSE_WRITE_INTERVAL_MS: '1000'
+  # ── email (optional) ──
+  EMAIL_FROM_ADDRESS: '${LANGFUSE_EMAIL_FROM:-admin@example.com}'
+  SMTP_CONNECTION_URL: '${LANGFUSE_SMTP_URL:-}'
+
+services:
+  langfuse:
+    image: 'langfuse/langfuse:3'
+    environment:
+      <<: *langfuse-env
+      # ── headless seed (agent-driven; empty = no seed) ──
+      # The agent provisions EVERYTHING on the first boot: a user (org owner) + org + project + key pair,
+      # with AUTH_DISABLE_SIGNUP=true from the start (default above), so signup is never open. The operator
+      # SIGNS IN (never signs up) with the seeded email + password and changes it; the agent already holds
+      # the keys (it generated them) and wires them into fazer.ai agents. One deploy, no redeploy, no open
+      # signup window; this is Langfuse's own recommended headless-init pattern. See references/05-langfuse.md.
+      LANGFUSE_INIT_ORG_ID: '${LANGFUSE_INIT_ORG_ID:-}'
+      LANGFUSE_INIT_ORG_NAME: '${LANGFUSE_INIT_ORG_NAME:-}'
+      LANGFUSE_INIT_PROJECT_ID: '${LANGFUSE_INIT_PROJECT_ID:-}'
+      LANGFUSE_INIT_PROJECT_NAME: '${LANGFUSE_INIT_PROJECT_NAME:-}'
+      LANGFUSE_INIT_PROJECT_PUBLIC_KEY: '${LANGFUSE_INIT_PROJECT_PUBLIC_KEY:-}'
+      LANGFUSE_INIT_PROJECT_SECRET_KEY: '${LANGFUSE_INIT_PROJECT_SECRET_KEY:-}'
+      LANGFUSE_INIT_USER_EMAIL: '${LANGFUSE_INIT_USER_EMAIL:-}'
+      LANGFUSE_INIT_USER_NAME: '${LANGFUSE_INIT_USER_NAME:-}'
+      LANGFUSE_INIT_USER_PASSWORD: '${LANGFUSE_INIT_USER_PASSWORD:-}'
+    ports:
+      # Expose the web UI / ingestion API. Front it with your own TLS-terminating proxy.
+      - '${LANGFUSE_PORT:-3000}:3000'
+    depends_on:
+      postgres: { condition: service_healthy }
+      redis: { condition: service_healthy }
+      clickhouse: { condition: service_healthy }
+      minio: { condition: service_healthy }
+    healthcheck:
+      test: ['CMD', 'wget', '-q', '--spider', 'http://127.0.0.1:3000/api/public/health']
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    restart: unless-stopped
+
+  langfuse-worker:
+    image: 'langfuse/langfuse-worker:3'
+    environment:
+      <<: *langfuse-env
+    depends_on:
+      postgres: { condition: service_healthy }
+      redis: { condition: service_healthy }
+      clickhouse: { condition: service_healthy }
+      minio: { condition: service_healthy }
+    restart: unless-stopped
+
+  minio:
+    image: 'minio/minio'
+    entrypoint: sh
+    command: -c 'mkdir -p /data/langfuse && minio server --address ":9000" --console-address ":9001" /data'
+    environment:
+      MINIO_ROOT_USER: '${MINIO_ROOT_USER}'
+      MINIO_ROOT_PASSWORD: '${MINIO_ROOT_PASSWORD}'
+    volumes:
+      - 'minio-data:/data'
+    # Uncomment to reach the MinIO console at http://<host>:9001 (optional; keep internal in prod).
+    # ports:
+    #   - '127.0.0.1:9001:9001'
+    healthcheck:
+      test: ['CMD', 'mc', 'ready', 'local']
+      interval: 5s
+      timeout: 5s
+      retries: 10
+      start_period: 5s
+    restart: unless-stopped
+
+  postgres:
+    image: 'postgres:17-alpine'
+    environment:
+      POSTGRES_DB: '${POSTGRES_DB}'
+      POSTGRES_USER: '${POSTGRES_USER}'
+      POSTGRES_PASSWORD: '${POSTGRES_PASSWORD}'
+    volumes:
+      - 'langfuse-postgres-data:/var/lib/postgresql/data'
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}']
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    restart: unless-stopped
+
+  redis:
+    image: 'redis:8'
+    command:
+      - sh
+      - '-c'
+      - 'redis-server --requirepass "$REDIS_PASSWORD"'
+    volumes:
+      - 'langfuse-redis-data:/data'
+    healthcheck:
+      test: ['CMD-SHELL', 'redis-cli -a "$REDIS_PASSWORD" ping | grep -q PONG']
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    restart: unless-stopped
+
+  clickhouse:
+    image: 'clickhouse/clickhouse-server:26.2.4.23'
+    environment:
+      CLICKHOUSE_DB: '${CLICKHOUSE_DB:-default}'
+      CLICKHOUSE_USER: '${CLICKHOUSE_USER}'
+      CLICKHOUSE_PASSWORD: '${CLICKHOUSE_PASSWORD}'
+    volumes:
+      - 'langfuse-clickhouse-data:/var/lib/clickhouse'
+      - 'langfuse-clickhouse-logs:/var/log/clickhouse-server'
+    healthcheck:
+      test: 'wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1'
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    restart: unless-stopped
+
+volumes:
+  minio-data:
+  langfuse-postgres-data:
+  langfuse-redis-data:
+  langfuse-clickhouse-data:
+  langfuse-clickhouse-logs:

package/dist/skills/agents-operation/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: agents-operation
+description: "Modo operação do fazer.ai agents: debugar conversas em produção e corrigir comportamentos inesperados do agente. Investiga (conversa no Chatwoot + ExecutionLog/flowlog + traces no Langfuse), reproduz no playground, ajusta o agente (prompt/ferramentas/behavior/KB) e re-valida, com toda mutação aprovada. Use quando uma instância JÁ em produção se comporta de forma inesperada e precisa de diagnóstico/ajuste, não é onboarding (subir do zero) nem desenvolvimento de código."
+---
+
+# Modo operação do fazer.ai agents
+
+Pega uma instância **já em produção** que está se comportando de forma inesperada e leva de "a conversa do cliente deu errado" até "causa entendida, ajuste validado e aplicado com aprovação". Audiência: **operador de uma instância viva**. Para subir uma instância nova use `agents-onboarding`; para mexer no código-fonte use `agents-dev`.
+
+## ⚠️ Segurança de produção (lê primeiro)
+
+Este modo **inverte** o fence do onboarding: lá o alvo é uma VPS de teste e "nada de produção"; aqui o alvo **é** produção.
+
+- **Investigação read-only é livre** (ler conversas, logs, traces, config do agente, queries de leitura). Mutação **não**.
+- **Toda mudança precisa de OK explícito do usuário para aquela mudança específica.** Autorização a um objetivo (corrigir um comportamento) não é autorização para escolher o método nem para aplicar sozinho. Proponha o diff/ajuste e espere o aval.
+- **Nunca editar o DB de produção direto** para mudar estado da aplicação: use a UI/API/console da própria app (editor de agente, write tools de MCP **dry-run por padrão**). Write direto no DB fura o passo de publish/validação da app.
+- **Sem segredo em log, output ou commit;** mascarar ao exibir.
+
+## O fluxo (references)
+
+Siga em ordem; cada etapa é uma reference. Leia a da etapa antes de executá-la.
+
+1. [`references/00-production-safety.md`](references/00-production-safety.md): a postura invertida: read-only livre, toda mutação aprovada item a item, nunca DB direto, dry-run por padrão. **Lê primeiro.**
+2. [`references/01-diagnose.md`](references/01-diagnose.md): localizar a conversa (`display_id`), ler o `ExecutionLog` (`/logs`), traces no Langfuse, config do agente: isolar **qual estágio** (stt/embed/generate/tts/split/handoff) divergiu.
+3. [`references/02-reproduce.md`](references/02-reproduce.md): reconstituir o turno no **playground** (modelo real, isolado da conversa real).
+4. [`references/03-adjust.md`](references/03-adjust.md): corrigir na camada certa: prompt, grants (replace-the-set), behavior, grounding/KB. Console ou MCP (dry-run primeiro).
+5. [`references/04-validate-and-apply.md`](references/04-validate-and-apply.md): re-validar no playground, conversa de teste controlada (Inbox API) quando fizer sentido, aplicar só com aprovação (audit cobre o write).
+
+Fronteiras duras em [`guardrails.md`](guardrails.md); armadilhas de diagnóstico em [`gotchas.md`](gotchas.md).
+
+## Guardrails
+
+Resumo (detalhe em [`guardrails.md`](guardrails.md)):
+
+- **Produção-first:** read-only livre; toda mutação aprovada item a item; nunca DB de produção direto.
+- **Dry-run:** toda write tool de MCP previewa; aplica só com OK.
+- **Estilo:** PT-BR com acentuação; sem em-dash; `fazer.ai` minúsculo.
+
+## Skills irmãs
+
+- `agents-onboarding`: subir uma instância nova num VPS (do zero ao agente).
+- `agents-dev`: trabalhar no código-fonte (Free/Full, implementar, gerar imagem).

package/dist/skills/agents-operation/gotchas.md

@@ -0,0 +1,61 @@
+# Gotchas: armadilhas de diagnóstico em produção
+
+Cada uma é uma armadilha real (extraída dos docs de subsistema). Leia antes de concluir.
+
+## Leitura / DB
+
+### Query crua no DB sem tenant context retorna ZERO linhas (não "não existe")
+
+O `DATABASE_URL` é a role runtime (não-superuser) e o RLS está ativo. Um `SELECT` em tabela tenant-scoped (ex.: `agents`) **sem** contexto de tenant retorna **zero linhas** em silêncio: a linha existe, o RLS está filtrando. **Não conclua que o registro sumiu.** Para diagnóstico cross-tenant, conecte como superuser via `MIGRATION_DATABASE_URL` (bypassa RLS, **read-only**, nunca mutar prod) ou `SET app.tenant_id = '<id>';` na sessão antes do `SELECT`.
+
+### Transcrição de áudio vive só no Chatwoot, não no nosso DB
+
+A transcrição do STT é escrita de volta no **meta do attachment no Chatwoot** (`transcribed_text`), nunca espelhada no nosso DB (regra anti-PII: não espelhamos corpo de mensagem). Procurar o texto da transcrição no DB do fazer.ai agents não acha nada. Idem para o corpo das mensagens: a thread é lida ao vivo do Chatwoot, sem mirror.
+
+### O ExecutionLog não tem o texto da mensagem
+
+`detail` é só ids/contagens/enums (PII-free, passa por redação); `errorMessage` é sanitizado. Você vê **qual** estágio falhou e **por quê** (enum/erro), não o conteúdo. Para o texto/raciocínio, vá ao **Langfuse** (session = threadId por-conversa).
+
+## Flowlog / estágios
+
+### `embed` não é emitido separado: a falha de embedding aparece em `generate`
+
+`embed` está no vocabulário mas **não está wired** ainda. A busca RAG roda **dentro** do span `generate`, então um erro de embedding/grounding surge como erro de `generate`, não numa linha `embed`. Não espere uma linha `embed` no `/logs`.
+
+### STT é eager e tem `turnId` próprio
+
+O STT roda **antes** do turno (na chegada da mensagem), então tem um `turnId` separado do turno que responde. No `/logs`, correlacione STT ao turno pelo **`threadId`/`conversationId`**, não pelo `turnId`.
+
+### `source` separa inbox de playground
+
+`GET /v1/logs` filtra por `source` (default `inbox`). Erros do **playground** ficam em `source=playground` e **não** disparam alerta (só `inbox` paga alerta). Se você reproduziu no playground e não vê no feed padrão, troque o filtro `source`.
+
+## Memória do agente (checkpointer)
+
+### Duas chaves diferentes: memória (por contato+canal) vs correlação (por conversa)
+
+A memória do grafo é por **contato+canal** (`tenant:instance:ci:<contactInboxId>`): abrange as conversas daquele contato **naquele canal**, então uma conversa nova reusa o histórico anterior, e canais diferentes do mesmo contato têm memórias **separadas**. Debounce, flowlog e a **session do Langfuse** usam a chave **por-conversa** (`tenant:instance:display_id`). "O agente lembrou de algo de outra conversa" pode ser memória de canal reusada (esperado), não bug.
+
+## Behavior (config do agente)
+
+### Sintomas que são config, não bug de código
+
+- Respondeu **balão-a-balão** (uma resposta por mensagem) → **debounce off**.
+- Não respondeu fora de horário / mandou template ou nota num envio proativo → **service-window**/business-hours (a janela de 24h só governa **proativo**; resposta reativa é sempre in-window).
+- Não respondeu em áudio → **tts.mode** (`never` por padrão) ou credencial TTS faltando.
+- Áudio recebido virou "peça texto" → **stt** desabilitado ou sem credencial.
+- Não usou a base → grant **RAG** ausente/vazio (fail-closed) ou embedding do tenant não configurado.
+
+### Embedding é por-tenant (não por-KB nem do modelo do agente)
+
+Sem o embedding configurado no nível do **tenant** (`tenant_settings`), os docs da KB vão para FAILED e o grounding falha. É config de tenant, separada da chave do modelo do agente. Reindexar a base não recupera docs já FAILED: use o **retry por documento** (MCP `knowledge_document_retry`).
+
+### Resposta em áudio só é PTT no WhatsApp se for Ogg/Opus
+
+O TTS emite Ogg/Opus de propósito; mp3/wav chegariam como arquivo comum, não nota de voz. Se "o áudio chegou como arquivo", o formato é o suspeito.
+
+## Mutação
+
+### Write direto no DB pode quebrar no próximo restart
+
+Mudar config da app direto no DB pula o publish/validação: o reader tipado não normaliza/clampa, o audit não registra, e o runtime pode reler do cache. Pode ficar OK agora e quebrar no restart. Sempre via UI/API/MCP da própria app.

package/dist/skills/agents-operation/guardrails.md

@@ -0,0 +1,26 @@
+# Guardrails: fronteiras que NÃO se cruzam
+
+Valem em qualquer execução desta skill. Cruzar qualquer uma é **parar e perguntar**. Detalhe em [`references/00-production-safety.md`](references/00-production-safety.md).
+
+## Produção-first
+
+- O alvo **é** produção. **Investigação read-only é livre** (ler conversas, logs, traces, config do agente, queries de leitura, playground). **Mutação não.**
+- **Toda mudança precisa de OK explícito do usuário para aquela mudança específica.** Autorização a um objetivo (corrigir um comportamento) não é autorização para escolher o método nem para aplicar sozinho. Proponha o ajuste exato (campo, valor antigo → novo, diff) e espere o aval. Aprovação de uma mudança não se estende à próxima.
+- **Nunca editar o DB de produção direto** para mudar estado da app. Use a UI/API/console da própria app (editor do agente, write tools de MCP). Write direto no DB fura o publish/validação e pode quebrar no próximo restart.
+- Confirme que o **alvo é o recurso certo** (a conversa/agente/tenant certo) antes de qualquer mutação ou de postar numa conversa viva.
+
+## Dry-run
+
+- Toda **write tool de MCP é dry-run por padrão**: previewa um diff e não aplica nada sem `dry_run:false` explícito. Rode o dry-run, mostre o diff, aplique só com OK. O apply grava `AuditLog`.
+- As tools `conversation_*` (`reply`/`handoff`/`return`/`status`/`reengage`) têm **efeito externo real** numa conversa do cliente e não são reversíveis: o dry-run mostra o texto exato; aplicar só com OK.
+
+## Segredos
+
+- **Nenhum segredo em log, output, commit ou arquivo plano.** Ao exibir, mascare.
+- O fazer.ai agents referencia segredos por **nome de vault** (`vault:<id>`), nunca o valor; respeite: não tente extrair nem imprimir o plaintext. Credencial faltando → o usuário preenche no console fora de banda.
+
+## Estilo
+
+- PT-BR com acentuação correta (escreva "não"/"ação", nunca "nao"/"acao").
+- Nada de em-dash (—) nem en-dash (–): use vírgula, ponto, dois-pontos, parênteses ou reescreva.
+- `fazer.ai` sempre minúsculo (slugs `fazer-ai` ok).

package/dist/skills/agents-operation/references/00-production-safety.md

@@ -0,0 +1,24 @@
+# 00: Segurança de produção (lê primeiro)
+
+O alvo **é** produção. A postura é o inverso do onboarding (onde nada toca produção).
+
+## O que é livre
+
+**Investigação read-only**, sem pedir: ler conversas no Chatwoot, ler o `ExecutionLog` (`GET /v1/logs`, página `/logs`), ler traces no Langfuse, ler a config do agente (editor ou `agent_get`/`agent_settings_get`/`agent_tools_get`), rodar o **playground** (modelo real, mas isolado da conversa), queries de leitura no DB.
+
+## O que exige OK explícito
+
+**Toda mutação**, item a item. Inclui: editar prompt/modelo/grants/behavior/KB do agente, qualquer write tool de MCP com `dry_run:false`, postar/transferir/resolver numa conversa real (tools `conversation_*`: `reply`/`handoff`/`return`/`status`/`reengage`), mexer em credencial/vault, reindexar KB.
+
+- Autorização a um **objetivo** ("conserta esse comportamento") não autoriza o **método** nem aplicar sozinho. Proponha o ajuste exato (qual campo, valor antigo → novo), mostre o diff, espere o aval.
+- Aprovação de uma mudança não se estende à próxima.
+- **Infra: reiniciar/redeployar/rebuildar serviços** (fazer.ai agents, Chatwoot, Langfuse, orquestrador), rodar **migrations**, ou mudar env/config viva. É mutação de produção, não diagnóstico: pode derrubar estado em voo (um restart do Coolify zera a fila de deploy) e um `migrate` pode ser destrutivo/irreversível. Proponha e espere o OK; nunca como atalho no meio de uma investigação.
+
+## Nunca
+
+- **Editar o DB de produção direto para mudar estado da app.** Use a UI/API/console da própria app: editor do agente, write tools de MCP. Write direto no DB fura o passo de publish/validação (o reader tipado normaliza e faz clamp; o audit registra; o runtime relê) e pode deixar o sistema OK agora e quebrado no próximo restart.
+- **Expor segredo** em log, output ou commit. Ao exibir, mascare. O fazer.ai agents retorna segredos só por referência (nome do vault), nunca o valor; respeite isso.
+
+## Dry-run é o padrão das write tools de MCP
+
+Toda write tool previewa um diff campo-a-campo e **não aplica nada** sem `dry_run:false` explícito. Rode o dry-run primeiro, mostre o diff ao usuário, só então aplique com o OK dele. O apply grava um `AuditLog` (`actorType: "mcp"`).

package/dist/skills/agents-operation/references/01-diagnose.md

@@ -0,0 +1,34 @@
+# 01: Diagnosticar (isolar qual estágio divergiu)
+
+Objetivo: de "a conversa deu errado" até "o estágio X divergiu por causa de Y". Tudo read-only.
+
+## 1. Localizar a conversa
+
+- No Chatwoot, a conversa tem um **`display_id`** (o número visível). É a âncora.
+- Chaves internas correlatas (você não digita, mas aparecem nos logs/traces):
+  - **Por-conversa** `tenant:instance:display_id`: usada por debounce, correlação de flowlog, fence de tenant e como **session no Langfuse**.
+  - **Memória do grafo** `tenant:instance:ci:<contactInboxId>`: o histórico que o agente "lembra" (por contato+canal). Uma conversa nova reusa essa memória; canais diferentes do mesmo contato têm memórias separadas.
+
+## 2. Ler o ExecutionLog do turno
+
+Página **`/logs`** (cards agrupados por turno, paginação keyset) ou `GET /v1/logs` (TENANT_ADMIN) / MCP `logs_query`. Filtros: `conversationId`, `agentId`, `turnId`, `stage`, `level`, `since/until`, `source` (default `inbox`; `playground` é separado).
+
+- **Um `turnId` por turno.** Cada linha é um estágio: `stt`, `embed`, `generate`, `tts`, `split`, `handoff` (+ erros). Filtre pelo `conversationId` e leia os turnos em ordem.
+- O `detail` é livre de PII (ids/contagens/enums); `errorMessage` é sanitizado. Você vê **o que** falhou e **onde**, não o texto da mensagem.
+- Leitura de sintomas:
+  - erro/anomalia em `stt` → transcrição do áudio (provider/credencial).
+  - resposta sem usar a KB, ou erro de embedding → ver `generate` (a busca RAG roda **dentro** do span `generate`; `embed` ainda não é emitido separado).
+  - resposta errada/ferramenta errada → `generate` (prompt, grants, chamadas de tool).
+  - sem áudio quando deveria → `tts`. Balões estranhos → `split`. Não transferiu → `handoff`.
+
+## 3. Trace no Langfuse
+
+Abra o trace do turno (env `production` ou `production-playground`, **session = o threadId por-conversa** `tenant:instance:display_id`). Mostra a sequência de chamadas ao modelo + tools, inputs/outputs, latência. É onde você lê o raciocínio e as tool calls que o flowlog só resume.
+
+## 4. Inspecionar a config do agente
+
+Editor do agente (abas General/Tools/Knowledge/Behavior) ou MCP read: `agent_get`, `agent_settings_get` (blocos `debounce`/`stt`/`tts`/`split`/`serviceWindow`/`grounding`, já normalizados), `agent_tools_get` (grants). Confirme se o comportamento observado bate com a config (ex.: respondeu balão-a-balão → debounce off; não respondeu fora de horário → service-window/business-hours).
+
+## 5. (Se preciso) estado do checkpointer
+
+O grafo persiste o histórico por thread de memória. Se o agente "lembra" algo que não deveria (ou perdeu contexto), a causa pode estar no histórico acumulado naquela thread. Leitura para diagnóstico; **não** edite o checkpointer direto.

package/dist/skills/agents-operation/references/02-reproduce.md

@@ -0,0 +1,22 @@
+# 02: Reproduzir (no playground, sem tocar a conversa real)
+
+Antes de mexer em qualquer config, reproduza o comportamento de forma isolada. O **playground** roda o **mesmo** modelo + system prompt + tools (knowledge/HTTP/MCP/integração) que produção, mas **sem** Chatwoot, webhook, debounce ou auto-reply: nada vaza para a conversa do cliente.
+
+## Como rodar
+
+- **Console:** editor do agente → aba **Playground**. Chat panel (Enter envia, Reset reinicia). Cada resposta expande em `trace` (tool calls/resultados) + `sources` (grounding da KB).
+- **MCP:** `agent_playground` (`mcp:read`; args `agent_id`, `message`, `thread_id?`) → `{ reply, threadId, trace, sources }`.
+- **REST:** `POST /api/v1/agents/:id/playground { message, threadId? }` (TENANT_ADMIN).
+
+O `enabled` do agente é ignorado no playground (você testa antes de ligar). Os toggles por-feature (`stt.enabled`/`vision.enabled`) são respeitados; resposta em áudio é um toggle manual (`forceAudio`).
+
+## Reconstituir o turno
+
+Mande a mesma mensagem (ou a sequência) que disparou o problema. Para multimodal, o playground aceita `attachment` (base64/url). Use o `trace` + `sources` para ver se o agente chamou a tool certa, fez grounding na KB certa, e por que respondeu o que respondeu.
+
+## Limites a ter em mente
+
+- **Não é simulação pura:** as tools de HTTP/integração do agente **executam de verdade** (uma write tool escreve). Se o agente tem tool que muda estado externo, reproduzir pode causar efeito colateral real. Avalie antes.
+- Sem mirror/conversa, as vars de contato/prompt vêm vazias (`instanceId`/`conversationId` dummy). Comportamento que depende de dados da conversa real (nome do contato, atributos, histórico daquela conversa) não reproduz idêntico aqui: o playground isola o **agente**, não o **estado da conversa**.
+- A thread do playground é **fenced** (`tenant:playground:agentId:uuid`): um `threadId` só é aceito se casar essa forma exata; qualquer outra (ex.: a thread de uma conversa real) é rejeitada. Não dá para "abrir" a conversa do cliente pelo playground.
+- Memória multi-turno: o cliente segura o `threadId` retornado entre turnos; Reset começa nova sessão.

package/dist/skills/agents-operation/references/03-adjust.md

@@ -0,0 +1,36 @@
+# 03: Ajustar (corrigir na camada certa)
+
+Achada a causa, ajuste na camada que a explica. Via **console** (editor do agente) ou **MCP** (write tools, **dry-run primeiro**, aplica só com OK). Toda mutação segue o `00-production-safety.md`.
+
+## Em qual camada está o problema
+
+| Sintoma | Camada | Onde | Tool MCP |
+| --- | --- | --- | --- |
+| Tom/conteúdo/decisão da resposta | **Prompt/instruções** | editor → General | `prompt_set` |
+| Modelo errado/caro/lento, temperatura | **Modelo** | editor → General (seção Model, `modelConfig`) | `agent_update` |
+| Usou/não usou a tool certa | **Grants de ferramentas** | editor → Tools | `agent_tools_set` |
+| Resposta sem fundamento na base | **Grounding/KB** | editor → Knowledge | `agent_tools_set` (grant RAG), `knowledge_*` |
+| Cadência/áudio/janela/agrupamento | **Behavior** | editor → Behavior | `agent_settings_set` |
+
+## Grants de ferramentas: replace-the-set
+
+O editor (`Tools` + `Knowledge`) edita **um** working set de grants e faz **PUT do set inteiro** (substitui, não acumula). O `agent_tools_set` segue o mesmo modelo.
+
+- **NATIVE:** sem grant NATIVE (ou allowlist vazia) = **todas** as tools nativas. Restringir = mandar o subconjunto explícito.
+- **RAG:** habilitar = mandar os nomes da tool RAG + os ids das KBs. Vazio = sem RAG (fail-closed).
+- MCP: discover por servidor → allowlist. INTEGRATION: checkboxes por toolpack.
+
+## Behavior: o que cada bloco controla (1 linha)
+
+`agent.settings.*`, ajustável no editor → Behavior e via `agent_settings_set` (patch parcial, merge nas sub-chaves, re-lido pelos readers tipados com clamp):
+
+- **debounce**: agrupa a rajada de mensagens e responde **uma vez** (on por padrão; `windowSeconds`, `maxMessagesPerBurst`, `maxWindowSeconds`).
+- **stt**: transcreve áudios recebidos (on por padrão, efetivo só com credencial; `provider`/`model`/`language`/`credentialRef`).
+- **tts**: responde em áudio: `mode` `never`|`mirror`|`preference` (default `never`).
+- **split**: quebra a resposta em balões com "digitando" (off por padrão; só texto).
+- **serviceWindow**: janela de 24h do WhatsApp para envios **proativos**: dentro = livre, fora = template HSM ou nota (on por padrão). Não afeta a resposta reativa.
+- **grounding**: limiar de distância (`maxDistance`) da busca na KB (distinto do grant RAG da aba Knowledge).
+
+## Credenciais
+
+Nunca passe o segredo cru. Na agents o segredo vive no **vault** e é referenciado por nome (`credentialRef` = `vault:<id>`); MCP traduz nome↔ref na borda, nunca o valor. Credencial faltando não é erro: a tool retorna `needsCredential` + URL do console para o usuário preencher fora de banda.