@zaip-ai/cli 2.0.0 → 2.6.0

package/templates/.agents/skills/zaip-skill-hostinger-cloudflare-terraform/agents/openai.yaml

@@ -1,7 +1,6 @@
 interface:
-  display_name: "Terraform Cloudflare Hostinger"
-  short_description: "Opera DNS Cloudflare e VPS Hostinger delimitados"
-  default_prompt: "Use $zaip-skill-hostinger-cloudflare-terraform para validar alvos, state e uma operacao Terraform Cloudflare/Hostinger com evidencias honestas."
+  display_name: "Terraform Cloudflare Hostinger e AWS"
+  short_description: "Prepara AWS e opera Terraform Cloudflare/Hostinger delimitados"
+  default_prompt: "Use $zaip-skill-hostinger-cloudflare-terraform para validar alvos, state e uma operacao Terraform Cloudflare/Hostinger, ou preparar AWS CLI/Terraform com conta, regiao, profile e roles explicitamente delimitados."
 policy:
   allow_implicit_invocation: true
-

package/templates/.agents/skills/zaip-skill-hostinger-cloudflare-terraform/references/aws-cli-terraform.md

@@ -0,0 +1,62 @@
+# Contrato AWS CLI e Terraform
+
+Use este procedimento somente quando a Task AWS ativa e o contrato de infraestrutura declararem explicitamente a conta AWS, a região, o profile de origem, a role alvo quando aplicável, e os recursos Terraform autorizados. Ele prepara um ambiente e produz um plano revisável. A autorização explícita da Task AWS ativa pode cobrir bootstrap e provisionamento somente dos recursos delimitados com AWS CLI/Terraform e o plano salvo revisado; ela não autoriza publicar aplicação nem ampliar conta, região ou role.
+
+## Identidade e escopo
+
+Registre nomes e ARNs, nunca credenciais, cache SSO, tokens STS, `backend-config`, state, plano binário/JSON ou seu conteúdo. O contrato AWS precisa conter:
+
+| Campo | Exigência |
+| --- | --- |
+| Conta | `account_id` de doze dígitos, correspondente à identidade STS observada para cada principal usado. |
+| Região | Uma região explícita para backend e provider; não herdar o profile ou região padrão do computador. |
+| Profile de origem | Nome explícito do profile configurado por SSO ou credencial local já autorizada. |
+| Principal do backend | Profile/role e conta que executam `terraform init` e acessam o bucket S3 de state. |
+| Principal do provider | Profile/role e conta que o provider AWS usa para ler, planejar ou alterar recursos. |
+| Role assumida | ARN, conta destino, política de menor privilégio, duração de sessão e external ID quando o trust policy exigir. |
+| Backend | Bucket, key, região, versionamento, recuperação e política IAM delimitados. |
+
+Um profile autenticado não autoriza a conta inteira. Um ARN novo, região nova, bucket/state key novo, role nova ou qualquer recurso faturável fora da Task exige escopo atualizado.
+
+## Autenticação AWS CLI
+
+SSO é o método preferível. Quando for o método autorizado, configurar somente o profile declarado:
+
+```text
+aws configure sso --profile PERFIL_ORIGEM
+aws sso login --profile PERFIL_ORIGEM
+aws sts get-caller-identity --profile PERFIL_ORIGEM --region REGIAO
+```
+
+Profile existente, OIDC ou uma role já autorizada também são válidos quando sua identidade STS verificada corresponde ao contrato. Confirme que o `Account` retornado corresponde ao `account_id` e registre somente conta, ARN sanitizado e momento. Não use `default` implicitamente. Para provider ou backend que assumem outra role, prefira profile com `role_arn` e `source_profile`, ou OIDC. Se `aws sts assume-role` for inevitável, declare `--role-arn`, `--role-session-name` e `--duration-seconds`, e nunca imprima, registre ou injete seu stdout de credenciais. Verifique a identidade obtida para cada principal; a credencial de backend não pode ser reutilizada como prova da role do provider, nem o contrário.
+
+O profile e as credenciais de sessão ficam no armazenamento local do AWS CLI, fora do repositório. Nunca copie valores de `~/.aws`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` ou `AWS_SESSION_TOKEN` para `.env`, arquivos Terraform, logs ou evidências.
+
+## Backend remoto S3
+
+Para Terraform >= 1.10, o backend S3 deve declarar bucket, key e região aprovados, `encrypt = true` e `use_lockfile = true`. O bucket deve ter versionamento e recuperação definidos; o principal de backend recebe somente as permissões necessárias ao objeto de state e ao arquivo `.tflock`. Não criar configuração nova com locking DynamoDB.
+
+`backend-config` sem segredo pode ser versionado; passe dados secretos somente por arquivo local ignorado ou variáveis de ambiente efêmeras do processo. Não rastreie segredos, state, lockfile remoto, plano binário ou JSON de plano. O comando `terraform init` deve usar a identidade do backend; a configuração `provider "aws"`/`assume_role` deve usar a identidade do provider, declarada e verificada separadamente.
+
+## Bootstrap AWS de ambiente zero
+
+`terraform init` configura e acessa um backend já existente; ele **não cria o bucket S3**. Quando não houver ambiente AWS anterior, uma Task AWS explicitamente autorizada pode executar um bootstrap separado, com AWS CLI/Terraform e apenas contra o `account_id`, região, principal de backend, bucket e key declarados no contrato. Esse bootstrap não lê nem requer o contrato operacional, runner, conta Cloudflare/Hostinger, VPS ou SSH.
+
+Antes de criar, confirme a identidade STS do principal de backend, a conta, a região e que o bucket aprovado ainda não existe. Crie somente o bucket aprovado e configure: versionamento, recuperação documentada e testável (por exemplo retenção/backup e restauração de versão), criptografia do bucket/state, IAM mínimo para o objeto state e `.tflock`, e `use_lockfile = true` no backend Terraform. Registre apenas os nomes/ARNs sanitizados, configurações não secretas, o resultado e a prova de recuperação; nunca state, tokens ou saída de credenciais. Não use DynamoDB para novo locking.
+
+Depois do bootstrap, inicialize o backend com a identidade de backend, revise o lock gerado e somente então execute `terraform init -lockfile=readonly`. O bootstrap não amplia o contrato para recursos de aplicação ou provider. A Task AWS ativa pode cobrir esses recursos somente quando o contrato os delimita e existe plano salvo revisado; não exija uma Task nova ou confirmação repetida para esse mesmo mandato.
+
+## Ciclo Terraform
+
+1. Verificar profile, conta e região do backend via STS. Sem lockfile, fazer bootstrap com `terraform init`, revisar o lock gerado e só então usar `terraform init -lockfile=readonly`.
+2. Verificar profile, role e conta do provider via STS; rodar `terraform fmt -check`, `terraform validate` e `terraform plan -out` em diretório local ignorado.
+3. Revisar o plano, guardar apenas seu hash, versão do Terraform/providers, conta/região/roles sanitizadas e o resultado da política.
+4. Na Task AWS ativa e explicitamente autorizada, `terraform apply` só consome o plano salvo cuja hash foi revisada. A execução AWS CLI/Terraform deve validar contrato, identidades, targets e hash de plano; o `cloud-runner.mjs` Cloudflare/Hostinger não pode ser apresentado como suporte AWS.
+
+Se autenticação, STS, init ou plano falhar, pare e registre diagnóstico sanitizado. Não faça fallback para outra conta/profile/role, nem repita mutações de provider sem reconciliação.
+
+## Fontes oficiais
+
+- [AWS CLI SSO](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html)
+- [Backend S3 do Terraform](https://developer.hashicorp.com/terraform/language/backend/s3)
+- [Boas práticas AWS para backend Terraform](https://docs.aws.amazon.com/prescriptive-guidance/latest/terraform-aws-provider-best-practices/backend.html)

package/templates/.agents/skills/zaip-skill-hostinger-cloudflare-terraform/references/guia-iniciante-hostinger-vps.md

@@ -0,0 +1,183 @@
+# Guia bem mastigado: VPS Hostinger, SSH, Codex e Terraform
+
+Uma **VPS** é um computador Linux alugado; **CPU**, **RAM** e **disco** são sua velocidade, memória e espaço. **SSH** é a conexão segura do seu computador para esse Linux. **Terraform** descreve infraestrutura em arquivos; seu **state** é o registro privado do que ele já administra.
+
+Este guia escolhe a próxima etapa pelo ponto em que a pessoa está. O Codex pode explicar, preparar arquivos locais e validar leitura autorizada, mas não compra, não cria token, não aplica Terraform e não faz deploy sem o escopo da Task. Quando plano, portas e alvos já forem autorizados, ele segue sem pedir a mesma autorização a cada etapa.
+
+## Primeiro: onde você está agora?
+
+1. **Sem VPS:** comece na etapa 1.
+2. **VPS comprada, sem SSH:** comece na etapa 3.
+3. **SSH funcionou duas vezes e a fingerprint foi conferida:** comece na etapa 5.
+
+Se ainda faltar contexto, faça somente estas perguntas: qual aplicação e público? qual teto mensal e quanto pode pagar agora? é uma prova pequena ou a arquitetura aprovada de duas VPS? Reuse fatos já conhecidos e avance automaticamente quando a próxima ação for do Codex e já estiver autorizada.
+
+## 1. Orçamento, tamanho e desenho
+
+**Você faz:** defina um teto que inclua VPS, domínio, backup, serviços externos, impostos e renovação. No checkout, o preço “por mês” pode ser o total antecipado dividido pelos meses. Anote total debitado hoje, período contratado e renovação.
+
+Exemplo fictício, apenas para aprender a comparar:
+
+| Escolha | Mensal equivalente | Débito agora | Renovação mensal equivalente | Conferir |
+| --- | ---: | ---: | ---: | --- |
+| Teste, 12 meses | R$ 35 | R$ 420 | R$ 70 | imposto, domínio, backup |
+| Serviço pequeno, 24 meses | R$ 60 | R$ 1.440 | R$ 145 | custo de 2 VPS, se aplicável |
+
+Comece com 30–50% de folga de RAM e disco para picos, logs e atualizações. É estimativa, não promessa: meça por alguns dias antes de aumentar.
+
+| Caso | Hipótese | Avaliar primeiro | Aumentar quando |
+| --- | --- | --- | --- |
+| Aplicação simples | site/API leve, sem worker contínuo ou banco pesado local | 1–2 vCPU, 4–8 GB RAM, 50–100 GB NVMe | uso sustentado, disco abaixo de 30% livre ou lentidão medida |
+| App + workers + observabilidade | API, tarefas de fundo, métricas e logs | 2–4 vCPU, 8–16 GB RAM, 100–200 GB NVMe | fila cresce, RAM troca para disco ou volume enche |
+| `autonomous-cloud` aprovado | VPS 1 pública + VPS 2 privada | dimensionar e orçar **cada** VPS | nunca reduzir a uma VPS sem novo contrato |
+
+Uma prova pequena pode propor uma VPS em um contrato futuro próprio. O contrato `autonomous-cloud` deste projeto exige VPS 1 como entrada pública e VPS 2 como aplicação privada; Cloudflare controla DNS/edge e Hostinger apenas as VPS.
+
+**Codex faz:** registra as premissas e compara opções, sem inventar preço/capacidade. **Sucesso:** objetivo, região, teto e desenho estão escritos. **Próxima ação:** abrir a página da VPS e anotar checkout, sem pagar. **Retomar:** “retomar orçamento” com plano, período, total e renovação.
+
+## 2. Comprar no hPanel
+
+**Você faz no navegador:**
+
+1. Abra [VPS da Hostinger](https://www.hostinger.com/br/servidor-vps) e prefira a experiência divulgada como VPS gerenciada por IA: hPanel, Terminal Web e Kodee reduzem o atrito inicial.
+2. Escolha plano e período. Veja o total antes de prosseguir; promoção não é previsão de renovação.
+3. Escolha região próxima ao público e um Linux estável suportado pelo projeto. Sem exigência diferente, Ubuntu LTS é uma escolha comum para Docker.
+4. Revise plano, período, região, SO, total, impostos e renovação. Só então faça o pagamento.
+
+“Gerenciada por IA” não é administração terceirizada: continua uma VPS KVM com root SSH, API e responsabilidade sua por sistema, aplicação e dados. Trocar/reinstalar o SO apaga dados e snapshots; não é recuperação casual.
+
+**Codex faz:** confere escolhas contra a Task; não usa cartão. API/MCP são opcionais e não servem para o primeiro SSH. **Sucesso:** hPanel mostra nome/ID, região, IP e SO. **Próxima ação:** em **VPS > Manage > Overview**, anote usuário, IP e porta SSH. **Retomar:** envie dados não secretos ou um screenshot recortado/sem pagamento e segredos.
+
+## 3. Criar a chave SSH no Windows
+
+**LOCAL** é PowerShell no seu Windows. **SERVIDOR** é Terminal Web confiável do hPanel ou SSH autenticado. Nunca rode comando LOCAL no servidor, nem copie chave privada para ele.
+
+**Você faz no PowerShell normal (LOCAL):**
+
+1. Confirme o cliente SSH:
+
+   ```text
+   ssh -V
+   ```
+
+2. Veja se pasta/chave existem; não sobrescreva uma chave:
+
+   ```text
+   Test-Path "$env:USERPROFILE\.ssh"
+   Test-Path "$env:USERPROFILE\.ssh\zaip_hostinger"
+   ```
+
+   Se a pasta não existir:
+
+   ```text
+   New-Item -ItemType Directory -Path "$env:USERPROFILE\.ssh"
+   ```
+
+3. Somente se o segundo teste for `False`, crie a chave. Quando pedir frase secreta, guarde-a localmente:
+
+   ```text
+   ssh-keygen -t ed25519 -a 64 -f "$env:USERPROFILE\.ssh\zaip_hostinger" -C "zaip-hostinger"
+   ```
+
+4. Exiba **somente** a chave pública; o arquivo sem `.pub` é privado:
+
+   ```text
+   Get-Content "$env:USERPROFILE\.ssh\zaip_hostinger.pub"
+   ```
+
+5. No hPanel: **VPS > Manage > Settings > SSH keys > Add**. Cole a linha pública, dê nome e salve.
+
+6. Só se necessário, em **PowerShell como Administrador**, ative o serviço:
+
+   ```text
+   Get-Service ssh-agent | Set-Service -StartupType Automatic
+   Start-Service ssh-agent
+   ```
+
+   Feche o administrador. No PowerShell normal do mesmo usuário que usará SSH/Codex:
+
+   ```text
+   ssh-add "$env:USERPROFILE\.ssh\zaip_hostinger"
+   ```
+
+**Codex faz:** orienta comandos e guarda no máximo o caminho local, nunca chave privada, frase secreta ou token. O `ssh-agent` deve ser da mesma conta/ambiente: PowerShell não prova WSL, cloud ou outra conta. **Sucesso:** painel mostra a chave pública e a privada continua local. **Próxima ação:** conferir identidade do servidor. **Retomar:** envie status/erro sanitizado; chave pública e fingerprint podem ser compartilhadas, privada/frase/token não.
+
+## 4. Conferir identidade e entrar duas vezes
+
+**Você faz:**
+
+1. Em **VPS > Manage > Overview**, copie usuário, IP e porta. Não adivinhe `root` ou porta 22.
+2. Abra Terminal Web no hPanel. No **SERVIDOR**, rode:
+
+   ```text
+   ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
+   ```
+
+   Anote algoritmo e fingerprint.
+3. No **LOCAL**, substitua os dados observados:
+
+   ```text
+   ssh -p PORTA -i "$env:USERPROFILE\.ssh\zaip_hostinger" USUARIO@IP
+   ```
+
+4. Aceite com `yes` somente se algoritmo e fingerprint coincidirem com o Terminal Web. Se divergir, responda `no` e pare.
+5. Rode `exit` e conecte uma segunda vez antes de alterar firewall, senha ou SSH.
+
+**Codex faz:** só fixa a identidade após comparação por canal confiável; `ssh-keyscan` sozinho não autentica servidor. **Sucesso:** duas conexões com a mesma fingerprint. **Próxima ação:** se o Codex tiver permissão, peça a ele uma verificação de leitura; senão reporte o sucesso. **Retomar:** se a fingerprint mudou, não apague `known_hosts`; investigue primeiro no Terminal Web.
+
+## 5. Preparar o Codex para leitura segura
+
+**Você faz:** abra o projeto local correto no Codex e forneça apenas alvo não secreto: alias SSH ou usuário/IP/porta, caminho local da chave e fingerprint confirmada pelos campos previstos na Task. Peça: “Verifique o executor SSH disponível, a compatibilidade da minha chave e, se compatível e autorizado, faça o teste de leitura permitido sem alterar o servidor”. No popup, confira ferramenta e alvo exatos antes de aprovar. Se for útil, envie erro sanitizado ou screenshot recortado, nunca pagamento, token, chave privada ou frase secreta.
+
+Uma aprovação `never` não libera rede. Permissões gerenciadas não podem ser burladas. Não combine `default_permissions` com `sandbox_mode` ou `sandbox_workspace_write`, não crie acesso global total e não presuma que local, WSL e cloud têm a mesma rede/chave.
+
+**Antes do teste pelo runner:** o SSH humano padrão acima pode usar sua chave criptografada e `ssh-agent`. O runner autônomo é diferente: ele aceita somente caminho de chave dentro da raiz do projeto, desativa `IdentityAgent`, usa modo não interativo e não lê sua chave em `%USERPROFILE%\.ssh`; a operação `hostinger:ssh:read` executa somente `uname -s`. Portanto uma chave criptografada externa que funciona no PowerShell **não** deixa o runner pronto. Primeiro o Codex inspeciona essas capacidades e o contrato. Se não existir uma identidade não interativa, protegida e autorizada dentro da raiz, o pré-requisito do runner está pendente; não copie a chave, não remova a frase secreta e não contorne o contrato.
+
+### Opção avançada: chave exclusiva para o runner
+
+Use isto somente se você aceitar uma credencial sem frase secreta para execução não assistida. Nunca retire a frase da sua chave pessoal nem a copie.
+
+1. O Codex confirma `git check-ignore` para `.local/ssh`, permissões/ACL do disco, o host, usuário de deploy e comandos de leitura permitidos.
+2. Ele cria uma **nova** chave de automação em `.local/ssh`, com ACL limitada ao usuário local e disco local criptografado; ela nunca entra em Git ou chat.
+3. Você adiciona somente a nova `.pub` no hPanel ou em `authorized_keys` do usuário de deploy restrito e mantém seu login humano como recuperação.
+4. O Codex testa o runner em modo somente leitura; só então uma Task autorizada pode ampliar o uso.
+
+Se política do host proibir essa chave ou você não aceitar o risco, registre essa escolha e pare: não há atalho. O bootstrap desse usuário/chave é separado do endurecimento de produção.
+
+**Codex faz:** lê configuração efetiva e relata filesystem, rede e ferramentas disponíveis. Para Hostinger/Cloudflare autorizados, usa somente `node .agents/tools/cloud-runner.mjs`, que valida alvo, credencial de origem e fingerprint; hash de plano é exigido apenas para Terraform e hash de script apenas para configuração SSH. Se bloqueado, devolve a mensagem sanitizada exata e a rota suportada, sem atalho. **Sucesso:** o runner conclui `hostinger:ssh:read` no alvo/fingerprint aprovados; não expõe stdout de `uname` nem comprova hostname, `id` ou aplicação. Bloqueio é diagnóstico, não acesso bem-sucedido. **Próxima ação:** aprove apenas o popup previsto ou resolva o pré-requisito informado. **Retomar:** “verificar prontidão SSH” permanece somente leitura e não conecta sem contrato/autorização.
+
+## 6. API/MCP, firewall e configuração
+
+**Você faz:** token não é necessário para SSH. Apenas se houver Task de automação: **hPanel > API** ou **Dev tools > API > Generate API token**, escolha nome/expiração, gere e guarde localmente em `.env` ignorado. Confirme na interface atual o menor escopo; não suponha token limitado a uma VPS. Nunca cole token no chat, Git, Terraform ou state. Após duas conexões, aprove as portas: web costuma precisar 80/443 no ingress aprovado e SSH administrativo limitado; Redis, banco, filas, exporters e painéis ficam privados.
+
+**Codex faz:** prepara Docker/Compose, volumes, usuários, atualização, firewall, logs, healthchecks, limites e rollback. O padrão é Terraform local/runner aprovado e VPS para aplicação; Terraform remoto é tecnicamente possível quando o contrato o declara, protege e justifica. Na arquitetura de duas VPS, prepara transporte privado autenticado VPS 1 → VPS 2. **Sucesso:** há plano de portas, backup e rollback. **Próxima ação:** aprove portas se ainda não estiverem no escopo. **Retomar:** após queda, reconcilie antes de repetir escrita.
+
+## 7. Terraform sem VPS duplicada
+
+**Você faz:** compra manualmente. Se VPS já existe, forneça ID aprovado para adoção/importação; não peça criação “só para testar”. Pare se plano mostrar VPS/DNS/custo inesperado.
+
+**Codex faz:** bloqueia versões de provider, separa state do Git e usa ambiente local/HCP ou backend já aprovado. Não pede JSON de bucket ao leigo. Para S3, backend usa `bucket`, `key`, `region`, `encrypt = true` e `use_lockfile = true`; `terraform init` conecta ao backend existente, não cria bucket. R2 não tem versionamento nativo e exige snapshots/backup protegido e restauração testada. Antes de escrita: `fmt`, `validate`, `plan -out`, revisão do plano salvo e `apply` apenas do arquivo/hash aprovado. Nunca `-lock=false`. **Sucesso:** plano com hash sem segredo e importação ligada à VPS comprada. **Próxima ação:** aprove mudança no escopo quando necessário. **Retomar:** timeout pode criar recurso; consulte provider/state, reconcilie e só então replaineje.
+
+## 8. Provar que está rodando
+
+**Você faz:** defina domínio, manutenção e responsável por backup. Container iniciado não prova serviço pronto.
+
+**Codex faz:** configura DNS Cloudflare, TLS, imagens/digests aprovados, segredos externos, healthchecks, logs e monitoramento. Na topologia aprovada, verifica VPS 1 → VPS 2, isolamento beta/produção e recusa pública de portas privadas. Faz reboot controlado e lê logs. Restaurar pelo painel sobrescreve servidor: teste em cópia/destino isolado; produção só com manutenção autorizada, backup atual e retorno. **Sucesso:** DNS/TLS, endpoint, reboot, logs, backup/restauração segura e portas privadas estão comprovados. **Próxima ação:** escolha frequência de custo, atualização e restore. **Retomar:** peça health, backup, portas e custo com evidência; sem execução observada, o resultado é local/estático.
+
+## Problemas comuns
+
+| Sintoma | Causa provável | Ação segura |
+| --- | --- | --- |
+| `Permission denied (publickey)` | usuário/chave errados ou agente de outra conta | confira Overview e SSH keys; rode `ssh-add` no PowerShell normal; não envie chave privada |
+| Timeout | IP/porta errados, VPS desligada ou firewall | confira Overview/Terminal Web; não abra portas amplas por tentativa |
+| `REMOTE HOST IDENTIFICATION HAS CHANGED` | host mudou ou há risco | pare e compare fingerprint no Terminal Web antes de remover entrada local |
+| erro do agent | serviço não roda no mesmo usuário | configure serviço se preciso como administrador, depois `ssh-add` no usuário normal |
+| Terraform cria VPS comprada | não está no state | pare, confira ID e importe/adote |
+| lock Terraform | outra execução usa state ou falhou | espere/verifique dono e reconcilie; nunca use `-lock=false` |
+
+## Fontes oficiais
+
+- [VPS Hostinger](https://www.hostinger.com/br/servidor-vps), [dashboard hPanel](https://www.hostinger.com/support/5726606-how-to-use-the-vps-dashboard-in-hostinger/) e [chaves SSH](https://www.hostinger.com/support/4792364-how-to-use-ssh-keys-at-hostinger-vps/)
+- [Conexão SSH](https://support.hostinger.com/en/articles/5723772-how-to-connect-to-your-vps-via-ssh), [troca de SO](https://www.hostinger.com/support/4965922-how-to-change-the-operating-system-of-your-vps-at-hostinger/) e [backup/restauração](https://support.hostinger.com/en/articles/1583232-how-to-back-up-or-restore-a-vps)
+- [Provider Terraform Hostinger](https://raw.githubusercontent.com/hostinger/terraform-provider-hostinger/master/docs/resources/vps.md), [OpenSSH no Windows](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_keymanagement)
+- [Configuração](https://learn.chatgpt.com/docs/config-file/config-reference), [segurança](https://learn.chatgpt.com/docs/agent-approvals-security), [permissões do Codex](https://learn.chatgpt.com/docs/permissions), [backend](https://developer.hashicorp.com/terraform/language/backend) e [locking Terraform](https://developer.hashicorp.com/terraform/language/state/locking)

package/templates/.agents/skills/zaip-skill-marketing/SKILL.md

@@ -3,19 +3,14 @@ name: zaip-skill-marketing
 description: Plan evidence-grounded marketing strategy, copy, campaigns, assets, and image briefs. Use for a declared marketing objective; do not use for generic website, product frontend, or central design-system implementation.
 ---
 
-# Planejar marketing
+# Marketing proporcional ao pedido
 
-## Localização canônica
+- Em pergunta, explicação ou copy curta com contexto suficiente, responda diretamente. Não crie campanha completa, arquivo ou questionário por padrão.
+- Use objetivo, público, oferta e canal fornecidos; pergunte somente pelo dado que muda materialmente a resposta. Preserve fatos, mensagem aprovada e fontes. Rotule hipóteses; não invente público, métricas ou decisões de marca.
+- Brandbook aprovado é referência read-only. Escale Branding somente para decisão de marca ausente ou contraditória; sales-facing vai a Sales, estratégia empresarial/RevOps a Growth, implementação de website/frontend ao especialista técnico.
+- Imagens, briefs visuais e mockups somente quando pedidos no escopo. Meta Ads carrega sua skill e ferramentas somente para trabalho Meta.
+- Para estratégia, planejamento de campanha ou entrega persistente, carregue [o fluxo progressivo](references/extended-workflow.md). Artefatos aprovados vivem em `.agents/marketing/`; `strategy.md` centraliza decisões estratégicas sem duplicação.
 
-Salve estratégias, campanhas, calendários, briefings, copy aprovada e ativos de marketing em `.agents/marketing/`. Não salve entregáveis de marketing em `docs/`, na raiz do repositório ou em diretórios de brand, sales ou growth.
+Uma interaction read-only não materializa Task/Change. Entrega persistente segue lifecycle, Requirements/AC e assurance proporcionais; só trabalho técnico carrega engenharia.
 
-O arquivo central da área é `.agents/marketing/strategy.md`; atualize-o quando uma decisão mudar a estratégia de marketing. Campanhas e planos específicos podem ser arquivos adicionais na mesma pasta.
-
-## Descoberta e entrega progressivas
-
-1. Comece pelas referências acessíveis fornecidas — texto, site, PDF, PPT, planilha, arquivo ou imagem. Para cada uma, registre fonte, locator e classificação: fato, decisão aprovada, hipótese, dado ou lacuna. Trate Brandbook aprovado como input somente-leitura e preserve todos os artefatos aprovados; não recrie nem duplique a fonte central da área.
-2. Se o trabalho começar do zero ou o contexto for insuficiente, faça no máximo cinco perguntas críticas por turno, por até três turnos. Pergunte somente por lacunas materiais: objetivo, ICP, oferta, canal, recursos disponíveis ou métrica. Espere as respostas antes de avançar nas partes que delas dependem; silêncio não é resposta nem aprovação. Após três turnos, mantenha lacunas explícitas e use somente hipóteses delegáveis rotuladas; não invente decisões de marca, autoridade, evidência, métricas ou público.
-3. Pedido pontual com contexto suficiente deve ser executado diretamente, sem questionário obrigatório ou plano completo.
-4. Aplique somente as partes necessárias ao escopo solicitado: `objetivo, ICP, oferta, canal, recursos e métrica` → `estratégia e mensagem` → `campanha e copy` → `ativos no escopo`. Identifique o material em construção e consolide somente decisões estratégicas sustentadas em `.agents/marketing/strategy.md`; campanhas, planos e copies específicos ficam em arquivos complementares sem repetir a estratégia central, sem exigir todos os módulos ou formatos.
-5. Produza estratégia, copy, campanha, conteúdo ou aplicação de marca proporcionais ao objetivo e ao escopo aprovado. Copy de marketing ambígua permanece com Lúcia. Não gere imagens, briefs visuais, mockups ou outros ativos por iniciativa própria; produza-os somente quando forem solicitados e estiverem no escopo.
-6. Escalar Sarah somente se uma decisão de marca estiver ausente, contraditória ou precisar ser criada; um Brandbook aprovado não redireciona a entrega para Branding. Encaminhar script voltado a vendas para Aaron, estratégia empresarial/RevOps para Robert, website para Jonny, frontend de produto para Doug e regra visual central para Manu.
+Para copy pontual, resumo salvo ou organização simples de contexto com fontes fornecidas, use o [perfil editorial `lite`](../zaip-skill-task/SKILL.md#assurance-proporcional): selecione `--risk lite` somente quando o impacto for baixo e não houver código, configuração, ação externa, informação sensível, estratégia crítica ou decisão de marca nova.

package/templates/.agents/skills/zaip-skill-marketing/references/extended-workflow.md

@@ -0,0 +1,16 @@
+# Planejar marketing
+
+## Localização canônica
+
+Salve estratégias, campanhas, calendários, briefings, copy aprovada e ativos de marketing em `.agents/marketing/`. Não salve entregáveis de marketing em `docs/`, na raiz do repositório ou em diretórios de brand, sales ou growth.
+
+O arquivo central da área é `.agents/marketing/strategy.md`; atualize-o quando uma decisão mudar a estratégia de marketing. Campanhas e planos específicos podem ser arquivos adicionais na mesma pasta.
+
+## Descoberta e entrega progressivas
+
+1. Comece pelas referências acessíveis fornecidas — texto, site, PDF, PPT, planilha, arquivo ou imagem. Para cada uma, registre fonte, locator e classificação: fato, decisão aprovada, hipótese, dado ou lacuna. Trate Brandbook aprovado como input somente-leitura e preserve todos os artefatos aprovados; não recrie nem duplique a fonte central da área.
+2. Se o trabalho começar do zero ou o contexto for insuficiente, faça no máximo cinco perguntas críticas por turno, por até três turnos. Pergunte somente por lacunas materiais: objetivo, ICP, oferta, canal, recursos disponíveis ou métrica. Espere as respostas antes de avançar nas partes que delas dependem; silêncio não é resposta nem aprovação. Após três turnos, mantenha lacunas explícitas e use somente hipóteses delegáveis rotuladas; não invente decisões de marca, autoridade, evidência, métricas ou público.
+3. Pedido pontual com contexto suficiente deve ser executado diretamente, sem questionário obrigatório ou plano completo.
+4. Aplique somente as partes necessárias ao escopo solicitado: `objetivo, ICP, oferta, canal, recursos e métrica` → `estratégia e mensagem` → `campanha e copy` → `ativos no escopo`. Identifique o material em construção e consolide somente decisões estratégicas sustentadas em `.agents/marketing/strategy.md`; campanhas, planos e copies específicos ficam em arquivos complementares sem repetir a estratégia central, sem exigir todos os módulos ou formatos.
+5. Produza estratégia, copy, campanha, conteúdo ou aplicação de marca proporcionais ao objetivo e ao escopo aprovado. Copy de marketing ambígua permanece com Lúcia. Não gere imagens, briefs visuais, mockups ou outros ativos por iniciativa própria; produza-os somente quando forem solicitados e estiverem no escopo.
+6. Escalar Sarah somente se uma decisão de marca estiver ausente, contraditória ou precisar ser criada; um Brandbook aprovado não redireciona a entrega para Branding. Encaminhar script voltado a vendas para Aaron, estratégia empresarial/RevOps para Robert, website para Jonny, frontend de produto para Doug e regra visual central para Manu.

package/templates/.agents/skills/zaip-skill-meta-ads-setup/SKILL.md

@@ -7,6 +7,8 @@ description: Configure and connect the official remote Meta Ads MCP for Codex wi
 
 Use esta skill quando o pedido for configurar, conectar ou instalar o Meta Ads MCP. Ela não consulta campanhas; após as tools serem anunciadas, use `$zaip-skill-meta-ads`.
 
+Quando a pessoa pedir teste manual com token Graph ou bearer MCP, encaminhe para `$zaip-skill-meta-token-onboarding`; este fluxo OAuth permanece separado.
+
 1. Execute o precheck no cwd do projeto: `codex --version`, `codex mcp login --help` e `node .agents/skills/zaip-skill-tool-setup/scripts/inspect-tool.mjs meta-ads mcp`. Confirme endpoint e OAuth nas [fontes oficiais verificadas em 2026-09-05](references/official-sources.md). O manifest distribuído permanece `enabled: false`; isso é diferente da configuração local solicitada.
 2. Antes de escrever, confirme que o projeto é trusted no Codex, pois `.codex/config.toml` pode ser ignorado fora de um projeto confiável. Se for ignorado, diagnostique trust e não o altere automaticamente. Preserve o conteúdo de `.codex/config.toml`. Se uma tabela existente usar `url = "https://mcp.facebook.com/ads"`, reutilize seu alias e não duplique a conexão. Se existir `[mcp_servers.meta-ads]` com URL diferente ou configuração incompatível, trate como conflito e não o reescreva. Sem conflito, acrescente uma vez:
 

package/templates/.agents/skills/zaip-skill-meta-token-onboarding/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: zaip-skill-meta-token-onboarding
+description: Orienta teste manual e local da Graph API e do MCP Meta com token temporário, incluindo a validação separada de cada caminho.
+---
+
+# Onboarding de token Meta para iniciantes
+
+Use quando uma pessoa quer testar, com os próprios ativos Meta, a Graph API e uma configuração MCP explicitamente solicitada. Não use para operar campanhas, contornar revisão ou receber segredos no chat.
+
+Explique primeiro o limite: uma conta de desenvolvedor Meta e um app próprio permitem testar ativos aos quais a pessoa já tem acesso e que estão autorizados para o app. Em geral, app review não é necessário apenas para pessoas com papel no app e ativos próprios; a Meta pode exigir verificações, acesso adicional ou impor limites conforme o produto, a conta e a política vigente. Leia o [guia detalhado](references/onboarding-manual.md) antes de orientar execução.
+
+1. Guie a pessoa no Graph API Explorer: escolha o app próprio, `Token do usuário`, as permissões de API `ads_read` e `business_management`, e clique em **Gerar token**. Se o painel atual mostrar dependências, inclua `pages_read_engagement` e `pages_show_list` somente quando exigidas. Ela nunca cola token, App Secret ou URL de autorização no chat.
+2. Somente se a pessoa autorizar explicitamente configurar, trocar ou testar, use `$zaip-skill-local-credentials` para acessar o `.env` ignorado da raiz. Essa autorização cobre os passos locais necessários daquele fluxo. Valide o token temporário com `GET /me` antes de o substituir e faça a troca server-side pelo token de longa duração retornado pela Meta. Não exponha credenciais em argumentos, URLs, logs, records ou evidências.
+3. Faça a prova da API em leituras `GET` paginadas: `/me`, `/me/businesses`, `owned_ad_accounts` e `client_ad_accounts` da BM escolhida, depois `/act_ID/campaigns`. Deduplicate contas pelo ID, peça que a pessoa escolha uma conta `act_...` e declare resultados vazios, limites e escopos insuficientes como tais.
+4. Para afirmar que o MCP foi validado, faça uma prova separada no endpoint `https://mcp.facebook.com/ads`. No ramo bearer explicitamente solicitado, confira o contrato atual, inclua `ads_mcp_management` se exigido e use o mapeamento seguro da variável local no host ou um agente HTTP direto que a mantenha em memória. Inicialize, envie `notifications/initialized`, obtenha `tools/list` e execute uma leitura de campanhas na mesma `act_ID`, preservando os headers de sessão e versão de protocolo solicitados pelo servidor. POST é permitido só para esses métodos MCP e uma ferramenta de leitura. Para o ramo OAuth, use `$zaip-skill-meta-ads-setup`. Esses escopos não autorizam escrita; só declare falha MCP quando uma falha for observada.
+
+Não execute chamadas, grave `.env` ou renove token só porque esta skill foi lida. Um pedido explícito de configurar, trocar ou testar autoriza os passos necessários daquele fluxo, sem ampliar para escrita. Use os prompts sem segredo e as referências de política no guia.

package/templates/.agents/skills/zaip-skill-meta-token-onboarding/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Onboarding de Token Meta"
+  short_description: "Guia local de token para Graph API e MCP Meta"
+  default_prompt: "Use $zaip-skill-meta-token-onboarding para testar Graph API e MCP Meta com token local, sem receber segredos no chat."

package/templates/.agents/skills/zaip-skill-meta-token-onboarding/references/onboarding-manual.md

@@ -0,0 +1,96 @@
+# Teste simplificado: Graph API primeiro, MCP depois
+
+Este roteiro é para a pessoa testar os próprios ativos, sem virar Tech Provider. Ele não cria acesso a uma conta, não publica anúncios e não substitui as políticas atuais da Meta. Pense em três coisas: o **app** é o cadastro da integração, a **BM** é o portfólio empresarial que reúne ou compartilha contas de anúncio, e o **token** é uma chave temporária para a pessoa provar o próprio acesso.
+
+## O que a pessoa precisa preparar
+
+1. Abrir [Meta for Developers](https://developers.facebook.com/), escolher **Entrar** ou **Começar** e usar o próprio login Meta. Concluir as verificações que a tela solicitar.
+2. Abrir **Meus apps** e escolher **Criar app**. Dar um nome, seguir o caso de uso que o painel apresentar para Marketing API ou gerenciamento de anúncios e confirmar o próprio papel no app. O nome e o tipo disponíveis podem mudar; para este teste, o app é só o cadastro da integração e não exige programar ou publicar um software.
+3. Anotar o App ID; o App Secret continua privado.
+4. Confirmar que a própria pessoa tem um papel adequado no app e acesso aos ativos que pretende consultar. Não exija que ela seja administradora de todos os ativos. Para uma prova de leitura de ativos próprios, normalmente não é preciso concluir app review; isso não garante acesso a qualquer BM, conta ou recurso. A Meta pode exigir verificações específicas, aprovações e níveis de acesso conforme o caso.
+5. Abrir o [Graph API Explorer](https://developers.facebook.com/tools/explorer/). Escolher o app, **Token do usuário**, marcar `ads_read` e `business_management` e clicar em **Gerar token**, como no exemplo fornecido. Se o painel atual exigir as dependências `pages_read_engagement` e `pages_show_list`, marque-as para completar o consentimento. Se também for testar o ramo MCP bearer, selecione `ads_mcp_management` nesse momento. Caso adicione esse escopo depois, gere um novo token, conclua o consentimento e repita a troca; escopos não são acrescentados editando `.env`. O token temporário é uma credencial: não envie por chat, e-mail, issue, log ou captura de tela.
+
+`ads_read` permite as leituras de marketing descritas aqui. `business_management` permite descobrir os negócios que o usuário pode administrar. Alguns desses escopos também podem permitir operações de escrita em outros fluxos, mas este roteiro autoriza somente `GET` e ferramentas read-only. Escopos adicionais só devem ser solicitados se a resposta da Meta ou o painel atual mostrar que são necessários para um recurso específico.
+
+## Arquivo local e troca por token de longa duração
+
+O `.env` fica na raiz do repositório, deve estar ignorado pelo Git e só pode ser escrito após a pessoa pedir explicitamente essa ação. É uma persistência local, não um mecanismo automático do host.
+
+| Chave local | Valor que a pessoa preenche | Uso |
+| --- | --- | --- |
+| `META_APP_ID` | ID do app próprio | troca server-side |
+| `META_APP_SECRET` | segredo do mesmo app | troca server-side |
+| `META_GRAPH_API_VERSION` | versão Graph escolhida para o teste | endpoints Graph |
+| `META_GRAPH_ACCESS_TOKEN` | token de usuário temporário ou renovado | leituras Graph |
+
+Use a versão selecionada no painel, por exemplo `vNN.0`; não trate uma versão como universal. Um `.env` local terá somente placeholders neste guia:
+
+```dotenv
+META_APP_ID=PREENCHA_LOCALMENTE
+META_APP_SECRET=PREENCHA_LOCALMENTE
+META_GRAPH_API_VERSION=vNN.0
+META_GRAPH_ACCESS_TOKEN=PREENCHA_LOCALMENTE
+```
+
+Antes de gravar, valide que `.env` é ignorado e não rastreado com `git check-ignore .env` e `git ls-files --error-unmatch .env`; ambos os comandos tratam apenas o caminho, não o valor. Ao atualizar, preserve comentários e chaves não relacionadas.
+
+O App Secret fica em **App Settings > Basic > Show** no painel do app. Antes da troca, o agente autorizado valida o token temporário em `GET /me?fields=id,name`; uma resposta com `id` e `name` mostra quem foi autenticado. A troca é um `GET https://graph.facebook.com/{META_GRAPH_API_VERSION}/oauth/access_token` com os parâmetros `grant_type=fb_exchange_token`, `client_id`, `client_secret` e `fb_exchange_token`. O processo monta os valores somente em memória, usa HTTPS para `graph.facebook.com` e não imprime nem registra a URL completa, argumentos ou logs com credenciais. A troca usa token válido, App ID e App Secret do mesmo app. A Meta normalmente devolve um token de longa duração em torno de 60 dias, mas o retorno, a expiração e a elegibilidade pertencem à resposta atual da Meta. Se o token expirar, é preciso fazer novo login e gerar um novo token temporário; não há renovação infinita garantida.
+
+Após uma troca bem-sucedida, o agente valida de novo `GET /me` usando o token retornado e confirma o mesmo `id` antes de substituir `META_GRAPH_ACCESS_TOKEN` localmente. Quando disponível, também confere metadados redigidos em `debug_token` — `app_id`, `is_valid`, escopos e expiração. A atualização do `.env` é atômica, preserva comentários e chaves não relacionadas e interpreta dotenv como dados, sem `source` ou `eval`. Qualquer erro de escopo, validade, aplicação ou permissão deve ser comunicado sem copiar a credencial.
+
+## Prova de leitura da API
+
+Peça leituras apenas, com campos mínimos, `limit` moderado e paginação até o fim ou até um limite declarado.
+
+1. **Identidade.** `GET /me?fields=id,name`. Guarde apenas os valores de negócio necessários para a resposta; não o token.
+2. **BMs disponíveis.** `GET /me/businesses?fields=id,name`. A pessoa escolhe uma BM à qual tenha acesso. Para um cenário de teste mais representativo, escolha uma BM que tenha pelo menos um conjunto de anúncios ativo e válido; isso é uma verificação adicional do cenário, não requisito de autenticação.
+3. **Contas da BM.** Leia as duas relações, sempre paginando: `GET /BM_ID/owned_ad_accounts?fields=id,name,account_status` e `GET /BM_ID/client_ad_accounts?fields=id,name,account_status`. Una as listas e remova duplicatas pelo `id`. A pessoa escolhe uma conta cujo ID é `act_...`.
+4. **Campanhas.** `GET /act_ID/campaigns?fields=id,name,status,effective_status`, com `ads_read`. A resposta com dados ou uma lista vazia prova a leitura para a conta escolhida; uma lista vazia não significa falha de autorização. Para conferir o cenário de conjunto ativo, a leitura adicional filtra `adsets` por `effective_status=ACTIVE`. Esse status não comprova entrega, validade comercial ou performance e o roteiro nunca ativa anúncios.
+
+Registre para a pessoa somente: endpoint, data/hora, ID selecionado, número de páginas, resultado `dados`, `vazio`, `scope-insufficient` ou `erro`. Não coloque tokens, secrets, headers de autorização, URLs completas ou payloads brutos em evidência.
+
+## Prova da API e prova do MCP
+
+Uma resposta Graph API prova o token e os endpoints Graph; `ads_read` não valida sozinho o MCP. Ela não prova que um MCP foi instalado, autenticado ou autorizou a mesma conta. OAuth é o caminho padrão para o MCP oficial Meta Ads configurado por ZAIP. A metadata atual do recurso Meta Ads anuncia bearer header e inclui `ads_read`, `business_management`, `pages_show_list` e `ads_mcp_management` entre os scopes; isso permite testar o ramo bearer quando ele for explicitamente solicitado, mas não prova antecipadamente que um token de usuário será aceito.
+
+Se `tools/list` ou a documentação atual do MCP exigirem `ads_mcp_management`, peça esse escopo apenas no ramo de teste MCP e respeite suas dependências atuais no painel. Ele não substitui `ads_read` para a consulta Graph de campanhas nem autoriza escrita. O vídeo de operações de escrita citado pela Meta para App Review não é etapa deste tutorial.
+
+No ramo bearer explicitamente solicitado, confira primeiro o contrato de recurso atual em `https://mcp.facebook.com/ads`. Se ele continuar aceitando bearer e exigir `ads_mcp_management`, obtenha o escopo no token, respeitando dependências mostradas no painel. Há duas opções: configurar o host para mapear a variável local de token para `bearer_token_env_var`, sem gravar valor literal; ou usar um agente HTTP direto que mantenha a variável somente em memória. `.env` não é carregado automaticamente: o processo do host precisa receber a variável por um carregamento dotenv local e seguro. Em ambos os casos, envie POST para `initialize`, `notifications/initialized`, `tools/list` e `tools/call` de leitura; mantenha os headers de sessão e da versão de protocolo conforme a resposta do servidor. Chame uma ferramenta de leitura de campanhas para a mesma `act_ID` já escolhida. Não altere TOML ou configuração de host sem esse pedido explícito; se ele existir, a edição é permitida dentro desse escopo. Declare falha apenas pela resposta observada, nunca por suposição. OAuth continua disponível como o caminho padrão, sem forçar uma troca de volta.
+
+Para validar um MCP após configurá-lo, o agente deve: (1) obter `tools/list` e seus schemas; (2) executar uma ferramenta de leitura real; e (3) informar se recebeu dados, vazio, falta de escopo, política bloqueada ou erro de transporte. Descobrir ferramentas ou concluir OAuth não é leitura real. Para o MCP oficial, use `$zaip-skill-meta-ads-setup` e depois `$zaip-skill-meta-ads`.
+
+## Prompts copiáveis, sem segredo
+
+Após salvar as credenciais localmente, fora do chat, a pessoa pode pedir:
+
+> Use esta skill para verificar localmente se as chaves Meta necessárias existem no `.env` da raiz, sem mostrar valores. Valide `GET /me` antes de qualquer troca de token.
+
+> Com minha autorização para trocar o token, use `META_GRAPH_API_VERSION` e faça a troca local do token Graph temporário. Não mostre nem grave segredos em logs, URLs, argumentos, records ou evidências. Valide `/me` com o token retornado antes de atualizar o `.env`.
+
+> Faça somente leituras Graph paginadas: minhas BMs, as contas próprias e de cliente da BM que eu escolher e as campanhas da conta `act_...` que eu escolher. Não altere ativos; informe cobertura e qualquer limitação.
+
+> Com minha autorização para configurar e testar o ramo bearer MCP, confira o contrato atual, mapeie a variável local no host sem valor literal, recarregue, liste as tools e faça uma leitura de campanhas na mesma conta `act_...`. Não escreva nem declare falha sem uma resposta observada.
+
+## Sobre acesso permanente e a Zaip
+
+Este fluxo é intencionalmente temporário e adequado a um teste simples. Acesso duradouro, automação em produção e uso com terceiros dependem do produto Meta, do modelo de token, da revisão, das permissões e das políticas aplicáveis. Para cenários elegíveis, um system user pode ter token sem expiração conforme a documentação atual da Meta no Postman; ele continua revogável e não depende de uma parceria universal.
+
+A [Zaip](https://zaip.com.br/) se apresenta institucionalmente como Parceiro Oficial Tech Provider no contexto WhatsApp. Pode ajudar a estruturar soluções e conformidade com as políticas aplicáveis, sem afirmar auditoria independente, selo de Ads ou MCP, nem token permanente exclusivo de parceiro.
+
+## Referências oficiais e limite de política
+
+- [Meta: tokens de longa duração](https://developers.facebook.com/docs/facebook-login/guides/access-tokens/get-long-lived/) — página verificada em 2026-09-06: troca server-side requer token válido, App ID e App Secret; token de usuário costuma durar cerca de 60 dias.
+- [Meta: autorização da Marketing API](https://developers.facebook.com/docs/marketing-api/overview/authorization/) — página verificada em 2026-09-06: testes de contas próprias têm limites e os níveis Limited e Full Access são avaliados pela Meta; não confunda com acesso garantido a todos os ativos.
+- [Meta Ads MCP: recurso OAuth protegido](https://mcp.facebook.com/.well-known/oauth-protected-resource/ads) — metadata verificada em 2026-09-06; suporta bearer header e anuncia scopes, mas não atesta a aceitação de um token específico.
+- [Meta: permissões](https://developers.facebook.com/docs/permissions/) — consulte para `ads_mcp_management` e dependências atuais antes do ramo bearer.
+- [Meta Graph API: negócios do usuário](https://developers.facebook.com/docs/graph-api/reference/user/businesses/), [contas próprias da BM](https://developers.facebook.com/docs/marketing-api/reference/business/owned_ad_accounts/), [contas de cliente da BM](https://developers.facebook.com/docs/marketing-api/reference/business/client_ad_accounts/) e [campanhas da conta](https://developers.facebook.com/docs/marketing-api/reference/ad-account/campaigns/) — referências das edges usadas nas leituras.
+- [Meta Postman: Facebook Marketing API](https://www.postman.com/meta/facebook-marketing-api/documentation/0zr4mes/facebook-marketing-api-mapi?entity=request-31691153-6b7e9445-1832-42ae-b40a-bdd1b831f714) — coleção direta da Meta sobre tokens de usuário e system user; consulte antes de afirmar elegibilidade ou expiração.
+- [Meta Graph API Explorer](https://developers.facebook.com/tools/explorer/) — a interface e as permissões disponíveis podem mudar; siga a tela atual da Meta.
+
+## Como concluir o teste
+
+- **API validada:** o novo token respondeu o mesmo `id` em `/me`, a BM e uma conta `act_...` foram selecionadas e a leitura de campanhas devolveu dados ou vazio legítimo.
+- **MCP validado:** depois de `initialize` ou reload, `tools/list` e uma ferramenta de leitura de campanhas para a mesma `act_ID` responderam de forma observável.
+- **Cenário ativo confirmado:** a leitura opcional de `adsets` encontrou um conjunto com status ativo e válido. Isso confirma o cenário de teste, não a autenticação.
+
+As políticas e os produtos Meta mudam. Quando a tela ou a resposta da API divergir deste guia, trate a fonte Meta atual como autoridade e reporte a divergência antes de ampliar permissões ou mudar o fluxo.

package/templates/.agents/skills/zaip-skill-module-scaffold/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: zaip-skill-module-scaffold
+description: Scaffold a safe minimal application module from the declared ZAIP profile and preserve existing work.
+---
+
+# Scaffold a module
+
+Use when a capability needs a new module shell, not to overwrite an existing implementation.
+
+1. Read `.agents/config/project.yaml` and verify that the profile declares a supported relative modules path.
+2. Run `node .agents/skills/zaip-skill-module-scaffold/scripts/scaffold.mjs <name> [--root <root>] [--dry-run]`; read its grammar before automation.
+3. The scaffold rejects traversal, absolute paths, Windows reserved names, case collisions, and paths that resolve through a junction outside the root.
+4. It is idempotent for identical generated files and refuses partial or divergent files; resolve those edits manually with their owner.
+5. Keep the generated domain/application shell free of database and framework imports. Add adapters only after a bounded contract exists and validate the module with its declared test command.

package/templates/.agents/skills/zaip-skill-module-scaffold/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Module Scaffold"
+  short_description: "Create a safe minimal module shell"
+  default_prompt: "Use $zaip-skill-module-scaffold to create a minimal module for this capability."

package/templates/.agents/skills/zaip-skill-module-scaffold/references/scaffold-contract.md

@@ -0,0 +1,9 @@
+# Scaffold grammar and output
+
+Run `node .agents/skills/zaip-skill-module-scaffold/scripts/scaffold.mjs <module-name> [--root <directory>] [--dry-run]`.
+
+The module name is lowercase kebab-case. `--root` defaults to the current directory; `--dry-run` writes nothing. Repeated flags are rejected. The helper requires stack id `zaip-aios-stack`, language `typescript`, and a safe relative `stack.layout.modules` path. It emits schema version, stack id, relative module path, dry-run state, and sorted `created` and `unchanged` paths.
+
+The generated shell has a domain type, an application factory, a public index, and a co-located TypeScript behavior check. It deliberately has no database, Hono, Kysely, Supabase, Redis, or BullMQ import.
+
+The consumer must provide TypeScript and `@types/node`. Compile with its project `tsconfig` or a portable temporary tsconfig that sets Node types and emits JavaScript, then run `node --test <emitted>/application.test.js`. This generated check is Node-test compatible; it does not promise automatic Vitest discovery.