iron-edge 2.33.1 → 2.34.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Iron Edge — Ecossistema de Agentes para Claude Code
2
2
 
3
- **44 agentes de topo, 18 squads, 25 skills e memória entre sessões.**
3
+ **44 agentes de topo, 18 squads, 26 skills e memória entre sessões.**
4
4
 
5
5
  Uma equipe completa de IA para marketing, vendas, conteúdo, Shopify, vídeo e crescimento — tudo dentro do Claude Code.
6
6
 
@@ -31,7 +31,7 @@ São arquivos `.md` comuns — abrem no Obsidian, no VS Code ou em qualquer edit
31
31
  Existem **duas coisas diferentes** aqui, e elas se chamam de jeitos diferentes. Confundir as duas
32
32
  é o erro mais comum de quem acabou de instalar.
33
33
 
34
- **Skills — essas viram comando de barra.** São 25, e o Claude Code as reconhece por `/nome`:
34
+ **Skills — essas viram comando de barra.** São 26, e o Claude Code as reconhece por `/nome`:
35
35
 
36
36
  ```
37
37
  /gate → auditoria de qualidade antes de entregar
@@ -44,6 +44,7 @@ Existem **duas coisas diferentes** aqui, e elas se chamam de jeitos diferentes.
44
44
  /trilha → a próxima etapa da sua loja, medida (no Iron Office: botão "Pedir ao Iron")
45
45
  /rastreamento-pixel → a Meta recebendo as vendas da loja, sem contar em dobro
46
46
  /anuncios → o retrato dos seus anúncios da Meta e o que corrigir hoje (no Iron Office: aba Anúncios)
47
+ /subir-anuncio → campanha nova no Meta em dois atos: um painel pra você aprovar olhando, e só depois cria tudo pausado
47
48
  /espiar → quem já vende no seu nicho, com o custo e o seu sim antes (no Iron Office: Referências do nicho em Páginas)
48
49
  /imagens → imagem da loja pro feed, story ou banner, com o custo e o seu sim antes (no Iron Office: aba Imagens)
49
50
  /minerar → o que está vendendo no seu país: ranking pelos 3 critérios (DropKiller = prova; Biblioteca de Anúncios = indício)
@@ -271,6 +272,8 @@ O que esperar:
271
272
 
272
273
  **Período Hoje** (desde a 2.26.0): a skill `anuncios` mede só o dia de hoje quando o pedido vem com `· hoje` ou o aluno pergunta "como está hoje"; o site guarda o último retrato de cada período. Desde a 2.30.0, medir 7, 15 ou 30 dias grava os quatro períodos (hoje, 7, 15 e 30): o pedido fica por último e os outros chegam junto.
273
274
 
275
+ **Subir anúncio** (skill `subir-anuncio`, desde a 2.34.0): no chat, "quero subir um anúncio". O Iron mede a sua conta da Meta, pergunta só o que falta, monta a campanha e abre um painel no navegador com a simulação do anúncio pra você aprovar olhando. Nada é criado antes do seu aprovado, tudo nasce pausado (o Iron confere) e nada começa a gastar antes do seu ativa. No dia seguinte, ele mede se cada anúncio apareceu.
276
+
274
277
  **Chrome sozinho** (desde a 2.33.0): o `ironoffice` liga o Chrome sozinho quando a extensão Claude in Chrome está instalada. `--sem-chrome` desliga. Desde a 2.33.1 o cartão Chrome diz por que não ligou.
275
278
 
276
279
  **Outro Iron aberto** (desde a 2.27.0): o `ironoffice` mostra de que conta é a chave e, com outro Iron vivo no computador, não abre outro: diz desde quando e o que fazer (`--em-espera` abre assim mesmo). Antes de atualizar o plugin, atualiza a lista de plugins.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: iron-paidmedia
3
- description: "Tráfego pago: anúncio, campanha, Meta Ads, Google Ads, verba e ROAS. Use quando o usuário disser: 'sobe um anúncio', 'a campanha parou de converter', 'quanto de verba', 'troca o criativo', 'o tráfego caiu'. Não use para: espionar anúncio de concorrente (iron-spy), funil e conversão fora da mídia (iron-growth)."
3
+ description: "Tráfego pago: anúncio, campanha, Meta Ads, Google Ads, verba e ROAS. Use quando o usuário disser: 'a campanha parou de converter', 'quanto de verba', 'troca o criativo', 'o tráfego caiu'. Não use para: espionar anúncio de concorrente (iron-spy), funil e conversão fora da mídia (iron-growth)."
4
4
  tools: [Read, Grep, Glob, Write, Edit, Bash, WebSearch, WebFetch, mcp__meta-ads__ads_account_get_activity_logs, mcp__meta-ads__ads_activate_entity, mcp__meta-ads__ads_boost_ig_post, mcp__meta-ads__ads_catalog_create, mcp__meta-ads__ads_catalog_create_feed_rule, mcp__meta-ads__ads_catalog_create_product_feed, mcp__meta-ads__ads_catalog_create_product_feed_upload_session, mcp__meta-ads__ads_catalog_create_product_set, mcp__meta-ads__ads_catalog_delete_product, mcp__meta-ads__ads_catalog_event_source_connect, mcp__meta-ads__ads_catalog_event_source_disconnect, mcp__meta-ads__ads_catalog_event_source_get, mcp__meta-ads__ads_catalog_event_source_get_catalogs, mcp__meta-ads__ads_catalog_event_source_get_health, mcp__meta-ads__ads_catalog_event_source_get_recommendations, mcp__meta-ads__ads_catalog_get_businesses, mcp__meta-ads__ads_catalog_get_data_sources, mcp__meta-ads__ads_catalog_get_diagnostics, mcp__meta-ads__ads_catalog_get_dynamic_ads_health, mcp__meta-ads__ads_catalog_get_feed_rules, mcp__meta-ads__ads_catalog_get_product_feed_upload_sessions, mcp__meta-ads__ads_catalog_get_suggested_filter, mcp__meta-ads__ads_catalog_list_catalogs, mcp__meta-ads__ads_catalog_list_dpa_eligible_catalogs, mcp__meta-ads__ads_catalog_list_partner_integrations, mcp__meta-ads__ads_catalog_list_product_feeds, mcp__meta-ads__ads_catalog_list_product_sets, mcp__meta-ads__ads_catalog_list_products, mcp__meta-ads__ads_catalog_product_create, mcp__meta-ads__ads_catalog_product_feed_delete, mcp__meta-ads__ads_catalog_product_feed_delete_rule, mcp__meta-ads__ads_catalog_product_set_delete, mcp__meta-ads__ads_catalog_update_catalog, mcp__meta-ads__ads_catalog_update_product, mcp__meta-ads__ads_catalog_update_product_feed, mcp__meta-ads__ads_catalog_update_product_set, mcp__meta-ads__ads_create_ad, mcp__meta-ads__ads_create_ad_set, mcp__meta-ads__ads_create_campaign, mcp__meta-ads__ads_create_creative, mcp__meta-ads__ads_create_custom_audience, mcp__meta-ads__ads_creative_delete, mcp__meta-ads__ads_creative_update, mcp__meta-ads__ads_creative_upload_local_image, mcp__meta-ads__ads_creative_upload_media, mcp__meta-ads__ads_delete_custom_audience, mcp__meta-ads__ads_delete_local_ad_image, mcp__meta-ads__ads_experiment_abtest_create_test, mcp__meta-ads__ads_experiment_abtest_get_test, mcp__meta-ads__ads_experiment_abtest_update_test, mcp__meta-ads__ads_experiment_check_eligibility, mcp__meta-ads__ads_experiment_lift_create_test, mcp__meta-ads__ads_experiment_lift_get_test, mcp__meta-ads__ads_experiment_list_tests, mcp__meta-ads__ads_finalize_local_ad_image_upload, mcp__meta-ads__ads_get_ad_account_custom_audiences, mcp__meta-ads__ads_get_ad_account_pages, mcp__meta-ads__ads_get_ad_accounts, mcp__meta-ads__ads_get_ad_entities, mcp__meta-ads__ads_get_ad_images, mcp__meta-ads__ads_get_ad_preview, mcp__meta-ads__ads_get_ad_preview_screenshot, mcp__meta-ads__ads_get_ad_videos, mcp__meta-ads__ads_get_creative_ads, mcp__meta-ads__ads_get_creatives, mcp__meta-ads__ads_get_custom_audience, mcp__meta-ads__ads_get_custom_audience_adsets, mcp__meta-ads__ads_get_customconversions, mcp__meta-ads__ads_get_dataset_details, mcp__meta-ads__ads_get_dataset_quality, mcp__meta-ads__ads_get_dataset_stats, mcp__meta-ads__ads_get_datasets, mcp__meta-ads__ads_get_errors, mcp__meta-ads__ads_get_field_context, mcp__meta-ads__ads_get_help_article, mcp__meta-ads__ads_get_ig_accounts, mcp__meta-ads__ads_get_ig_media, mcp__meta-ads__ads_get_opportunity_score, mcp__meta-ads__ads_get_pages_for_business, mcp__meta-ads__ads_get_user_pages, mcp__meta-ads__ads_insights_advertiser_context, mcp__meta-ads__ads_insights_anomaly_signal, mcp__meta-ads__ads_insights_auction_ranking_benchmarks, mcp__meta-ads__ads_insights_industry_benchmark, mcp__meta-ads__ads_insights_performance_trend, mcp__meta-ads__ads_library_search, mcp__meta-ads__ads_log_ui_interaction, mcp__meta-ads__ads_pixel_event_create, mcp__meta-ads__ads_pixel_event_delete, mcp__meta-ads__ads_pixel_event_read, mcp__meta-ads__ads_pixel_event_update, mcp__meta-ads__ads_pixel_parameter_create, mcp__meta-ads__ads_pixel_parameter_delete, mcp__meta-ads__ads_pixel_parameter_read, mcp__meta-ads__ads_pixel_parameter_update, mcp__meta-ads__ads_update_custom_audience, mcp__meta-ads__ads_update_custom_audience_users, mcp__meta-ads__ads_update_entity]
5
5
  model: sonnet
6
6
  ---
@@ -24,4 +24,6 @@ Você é o agente de topo do squad de tráfego pago do Iron Edge. Há dois jeito
24
24
 
25
25
  **Ferramentas da Meta:** `mcp__meta-ads__*` (conector oficial da Meta, com o login do próprio aluno). Se não existirem na sessão, ou se responderem que falta login, não invente dado: mande o aluno conectar em Iron Office → Integrações → Meta Ads (ou digitar `/mcp` no Iron e entrar com o Facebook). Só leitura (listar, consultar, medir) é livre. Qualquer ferramenta que muda algo na Meta (criar, ativar, pausar, editar, mudar verba, apagar ou desconectar campanha, anúncio, criativo, público, pixel ou catálogo) só roda depois de você mostrar o que vai mudar e o aluno responder "pode": o login é dele e o dinheiro também. Apagar não tem volta: diga isso antes.
26
26
 
27
+ **Campanha nova na Meta ("sobe um anúncio", "criar campanha"):** use a skill `/subir-anuncio`, que planeja com painel, só cria depois do aprovado e confere se nasceu pausado. Você entra para estratégia, diagnóstico e leitura de resultado.
28
+
27
29
  O caminho principal de entrada continua sendo a palavra `iron` na conversa: o `iron-ceo` decide se o pedido é seu e te aciona com o pedido já formulado.
@@ -102,7 +102,7 @@ Ativadores explicitos por camada:
102
102
  ## 4. Ambiguity Matrix
103
103
 
104
104
  Grupo 1 — Anuncio / trafego
105
- - "anuncio": criar campanha -> iron-paidmedia | espiar concorrente -> iron-spy
105
+ - "anuncio": criar campanha -> skill /subir-anuncio (estrategia e diagnostico -> iron-paidmedia) | espiar concorrente -> iron-spy
106
106
  - "criativo": produzir -> iron-design (estatico) ou iron-video (video) | analisar de concorrente -> iron-spy
107
107
  - "campanha": midia paga -> iron-paidmedia | conteudo organico -> iron-content
108
108
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "iron-edge",
3
- "version": "2.33.1",
4
- "description": "Ecossistema de agentes para Claude Code: 44 agentes de topo, 18 squads e 25 skills, com quality gate, memoria, instalador que nunca sobrescreve o comando office (chat do Iron Office no dashboard; confere a chave com o site antes de abrir o Claude) e o doctor (mede a maquina e acende o Setup do site).",
3
+ "version": "2.34.0",
4
+ "description": "Ecossistema de agentes para Claude Code: 44 agentes de topo, 18 squads e 26 skills, com quality gate, memoria, instalador que nunca sobrescreve o comando office (chat do Iron Office no dashboard; confere a chave com o site antes de abrir o Claude) e o doctor (mede a maquina e acende o Setup do site).",
5
5
  "keywords": [
6
6
  "claude",
7
7
  "claude-code",
@@ -9,7 +9,7 @@ O aluno abre a aba Anúncios do projeto e vê gasto, resultados, custo por resul
9
9
 
10
10
  **Regras que não mudam:**
11
11
  - Nunca invente número. Todo número da resposta e do retrato saiu de uma chamada desta vez.
12
- - Só lê. Pausar peça é UMA pergunta pela `ask` antes, e só no "Sim". Criar campanha, mudar verba ou público não é desta skill: diga que é pelo chat, com aprovação, e pare.
12
+ - Só lê. Pausar peça é UMA pergunta pela `ask` antes, e só no "Sim". Criar campanha, mudar verba ou público não é desta skill: campanha nova é pela skill `subir-anuncio` (peça "quero subir um anúncio"), com aprovação; verba e público, pelo chat, com aprovação. Diga isso e pare.
13
13
  - **Zero alerta é resultado válido.** Diga em 1 linha e grave o retrato do mesmo jeito.
14
14
  - **Pedido `anúncios: atualizar` (o botão) sempre termina em `ads_status`.** Meça tudo do passo 3 ao 5, inclusive o 3f quando há Shopify, e releia a ficha, mesmo que tenha medido há segundos e mesmo com números iguais. Nunca responda 'nada mudou' no lugar de gravar: a aba fica esperando o retrato, e o aluno pode ter mudado a ficha. A única exceção é não conseguir medir (sem Meta, conta que não abre): diga o motivo e pare, sem gravar retrato vazio.
15
15
 
@@ -0,0 +1,307 @@
1
+ ---
2
+ name: subir-anuncio
3
+ description: "Sobe uma campanha nova no Meta Ads em dois atos separados: primeiro PLANEJA (entende o pedido, mede a conta, monta a estrutura e abre um painel no navegador para o dono aprovar), e só depois EXECUTA pelo MCP, com tudo nascendo pausado. Dispara em 'quero subir anúncio', 'subir campanha', 'criar campanha', 'rodar tráfego', 'impulsionar', 'bora anunciar', ou quando a pessoa colar um áudio transcrito descrevendo uma campanha."
4
+ ---
5
+
6
+ # subir-anuncio — planejar junto, executar depois
7
+
8
+ Esta skill é o suporte de tráfego do dono do negócio. Ele diz o que quer, do jeito dele, e você conduz em **dois atos que não se misturam**:
9
+
10
+ 1. **PLANEJAR**: medir a conta, entender o pedido, perguntar só o que falta, montar a estrutura, inventariar os criativos, escrever o plano em arquivo e abrir um **painel no navegador**. Parar e esperar o aprovado.
11
+ 2. **EXECUTAR**: só depois do aprovado: subir a mídia, montar tudo PAUSADO de cima para baixo, gerar a prévia, checar erro, ativar quando ele mandar e medir impressão no dia seguinte.
12
+
13
+ Serve igual para o próprio negócio e para cliente: onde este texto diz "negócio" ou "dono", leia "o negócio dono daquela conta de anúncio".
14
+
15
+ **A ficha do negócio** é o `Projetos/<pasta>/PROJETO.md` que a skill `loja` monta no cofre (o caminho chega na linha `[loja: … · ficha: …]` do pedido). Se a máquina não tiver a skill `loja` nem essa ficha, use a nota do negócio que o dono indicar.
16
+ **"Informação que vence"** é um bloco curto dentro da ficha com o que tem prazo: a promoção que vale agora e até quando, o preço anunciado, o estoque, a URL de destino e o WhatsApp. É o que a campanha não pode contradizer; se o bloco não existir, crie com o que o dono responder.
17
+
18
+ ## Quando NÃO usar esta skill
19
+
20
+ - Trocar a peça de uma campanha que já existe (virou a data, turma nova, arte corrigida): se a skill `troca-criativo` estiver instalada, é ela; se não estiver instalada, faça por aqui a partir da Fase 3, com anúncio novo no conjunto que já existe, e pause o anúncio antigo só depois que o novo tiver impressão.
21
+ - Ver como estão os anúncios, achar peça parada ou data vencida no ar: é a skill `anuncios` (só leitura).
22
+ - Relatório de campanha que já rodou: também é a `anuncios`.
23
+
24
+ ---
25
+
26
+ ## O princípio, antes dos passos
27
+
28
+ **O erro caro em tráfego não é técnico, é de premissa.** Número de WhatsApp errado, página fora do ar, verba no lugar errado, mídia que não subiu: tudo isso se resolve de graça ANTES de existir qualquer objeto no Meta, e caro depois.
29
+
30
+ **Criar não é publicar.** Peça criada e esquecida em PAUSED não é entrega, é dinheiro indo para a peça velha. A sessão desta skill fecha em um de dois estados, e os dois são MEDIDOS: (a) peça nova com impressão maior que zero; ou (b) pendência escrita, com prazo e passo exato, na ficha do negócio. `status ACTIVE` não é nenhum dos dois.
31
+
32
+ **O painel existe porque o dono pensa olhando.** Ele aprova vendo a árvore da campanha e a simulação do anúncio, não lendo tabela.
33
+
34
+ ---
35
+
36
+ ## Meta não conectada
37
+
38
+ Se as ferramentas `mcp__meta-ads__*` não existem nesta sessão, ou respondem que falta login: não diga "não dá" e não invente dado. Uma linha ("pra eu subir o seu anúncio, o Iron precisa estar ligado na sua conta do Facebook; é uma vez só") e os 3 passos:
39
+
40
+ AGORA VOCÊ
41
+ 1. No terminal onde o Iron roda, digite `/mcp` e aperte Enter.
42
+ 2. Com as setas, vá até `meta-ads` e aperte Enter; escolha **Authenticate**. Abre uma página no navegador: entre com o Facebook que anuncia o negócio e autorize.
43
+ 3. Feche o Iron (Ctrl+C duas vezes), abra de novo com `ironoffice` (ou `npx iron-edge@2 office`, se o atalho não existir) e peça "quero subir um anúncio".
44
+
45
+ Pare aqui. Nada de planejar com dado inventado.
46
+
47
+ ## No Iron Office
48
+
49
+ Quando o pedido chega pelo site (mensagem do canal do Iron Office), o aluno não está olhando o terminal:
50
+
51
+ - **Toda pausa desta skill vira UMA pergunta pela `ask`, com botões.** O aprovado do plano (Fase 2), o das peças (Fase 3) e o ativa (Fase 5) são `ask` com opções ("Aprovado, pode criar" / "Quero mudar algo"; "Ativa agora" / "Ainda não"), a última chamada da rodada. Nunca termine um `reply` com "me diz aprovado" ou "escreva ativa".
52
+ - **Briefing que falta é UM formulário** (`ask` com `fields`), não três mensagens.
53
+ - **O painel abre no navegador do computador dele.** Depois de abrir, avise por `reply`: "Abri o painel da campanha no navegador do seu computador. Olhe a simulação do anúncio e responda aqui embaixo."
54
+ - No terminal (fora do Iron Office), as mesmas pausas são uma pergunta no chat, e o dono responde com as palavras dele.
55
+
56
+ ---
57
+
58
+ ## Antes da primeira chamada da sessão
59
+
60
+ - Gerar UM `client_conversation_id` (20 caracteres, letras e dígitos) e enviá-lo em **toda** chamada `ads_*` da sessão, junto com `advertiser_request` preenchido com o pedido literal do dono, nas palavras dele.
61
+ ⚠️ Os dois campos vão para o servidor do Meta e **não podem levar dado pessoal**: nome de gente, telefone, e-mail, endereço. Se o pedido dele (áudio transcrito, print de conversa) contiver isso, tire antes de enviar, mantendo o resto das palavras dele.
62
+ - Olhar a conta antes de mexer: se a skill `ads-check` estiver instalada, rode-a; se não estiver instalada, a leitura da skill `anuncios` cobre o mesmo (peça nova sem aparecer, data vencida no ar, dinheiro na peça errada). Se nenhuma das duas estiver na máquina, diga isso e siga com a Fase 0, que mede o essencial.
63
+
64
+ ---
65
+
66
+ ## FASE 0 · Medir o estado (ainda sem perguntar nada)
67
+
68
+ O pedido descreve o que ele quer VER, não o que falta fazer. Meça antes de perguntar: metade do briefing já está na conta.
69
+
70
+ 1. `ads_get_ad_accounts`: conta usável é `is_ads_mcp_enabled: true` **e** `is_queryable: true` (dois campos diferentes, podem divergir). Anotar moeda, `min_daily_budget_cents` e `business_name`. Se `is_queryable` for false, mostrar `not_queryable_reason`.
71
+ 2. **Permissão de escrita: a API não expõe.** Nenhum campo de `ads_get_ad_accounts` diz se você pode CRIAR nessa conta. Registre no painel como `permissão de escrita a confirmar` e avise o dono na Fase 2 que a primeira criação é também o teste de permissão.
72
+ 3. **Páginas: duas listas, e a boa é a que aparece nas duas.** Sem página não existe criativo.
73
+ - `ads_get_ad_account_pages`: as páginas promovidas NA CONTA. É a única que devolve `leadgen_tos_accepted`, de que a campanha de cadastro depende.
74
+ - `ads_get_user_pages`: as páginas em que o dono tem permissão de criar anúncio.
75
+ 🔴 **Uma página pode estar na primeira lista e não na segunda, e aí o erro só aparece lá na frente**, no `ads_create_creative`, como `Você não tem a permissão necessária para acessar este perfil` (medido em 08/09/2026). Leve para o painel só as que aparecem nas duas. Página que só aparece na primeira vira linha do pré-voo humano: "confirmar acesso a esta Página".
76
+ 4. `ads_get_ig_accounts`: guardar o `instagram_user_id`. **Criativo sem `instagram_user_id` não entrega no Instagram.** Se a conta não tiver Instagram ligado, isso vira linha do pré-voo, não surpresa depois.
77
+ 5. `ads_get_datasets` e `ads_get_dataset_stats`: pixel e se está recebendo evento. Campanha de vendas no site sem pixel maduro muda a recomendação de público.
78
+ 6. Campanhas antigas parecidas: `ads_get_ad_entities` no `level: "campaign"` com `date_preset: "maximum"`. Achar a que mais converteu (menor custo por resultado) e abrir por dentro: formato que ganhou, otimização do conjunto e a copy que converteu (`ads_get_creatives`, campo `body`). Reaproveitar a fórmula vale mais que inventar.
79
+ 7. **Rascunhos esquecidos:** `ads_get_ad_entities` com `object_state: "draft"` e sem `object_ids` lista o que já está montado e não publicado na conta. Se houver, mostre no painel ("já existe um rascunho X") antes de montar outro por cima. Se a chamada falhar, a conta não tem modo rascunho: siga.
80
+ 8. Ler a ficha do negócio, bloco "Informação que vence".
81
+ - Ficha existe mas não tem o bloco → dizer isso no painel em vez de assumir.
82
+ - **Ficha não existe** (primeira campanha do negócio, comum) → não é erro e não trava nada: siga com o que o dono responder na Fase 1, marque no painel que a ficha ainda não existe, e crie a ficha na Fase 2 (com a skill `loja`, se estiver instalada).
83
+
84
+ **Saída:** estado da conta em 6 linhas, mais o que já dá para preencher do briefing sem perguntar.
85
+
86
+ ---
87
+
88
+ ## FASE 1 · Briefing (o pedido dele vira estrutura)
89
+
90
+ Ele explica do jeito dele: texto corrido, áudio transcrito colado, print. Você **extrai** para o esquema abaixo e pergunta **só o que ficou vazio**.
91
+
92
+ ⚠️ **Um bloco de perguntas por vez, no máximo três blocos** (no Iron Office, um formulário só). Nunca despejar onze perguntas. Agrupe assim: (1) oferta e destino, (2) verba e público, (3) criativos. Pule o bloco inteiro que a Fase 0 já respondeu.
93
+
94
+ | Campo | O que é | Se faltar |
95
+ |---|---|---|
96
+ | Negócio e conta | nome do negócio e ID da conta | perguntar |
97
+ | Objetivo | vendas no site, cadastros, mensagens, tráfego | perguntar; mapear para os valores ODAX (ver `references/estrutura-meta.md`) |
98
+ | Destino | URL, WhatsApp ou formulário | perguntar **e conferir**: a URL responde? o número é o mesmo em copy, arte e na Página? |
99
+ | Oferta | produto, preço, promoção, até quando | perguntar; cruzar com a ficha |
100
+ | Verba e duração | valor por dia e por quantos dias | perguntar; conferir o mínimo da conta (`min_daily_budget_cents`) |
101
+ | Estrutura | CBO ou ABO | **sugerir com motivo**: CBO com um público só, ABO para testar públicos separados |
102
+ | Público | país/cidade, idade, Advantage+ ou interesses | perguntar; sugerir Advantage+ quando houver pixel com evento |
103
+ | Criativos | quantos, formatos, em qual pasta | perguntar a PASTA e inventariar |
104
+ | Copy | texto primário, título, descrição, CTA | rascunhar a partir da campanha campeã ou da oferta |
105
+ | Nome | nome da campanha, do conjunto e dos anúncios | propor (ver `references/copy-e-nomes.md`) |
106
+ | Divulgação de IA | o criativo foi feito ou editado com IA generativa de terceiro? | **perguntar sempre, nunca decidir por ele** (ver regra 7 da Fase 4) |
107
+ | Pré-voo | página no ar, pixel disparando, WhatsApp Business ligado à página, forma de pagamento | medir o que a API alcança; o resto vira checklist humano |
108
+
109
+ **O que você propõe entra como `Sugestão · a definir`, nunca como fato.** Nome, copy e público que saíram da sua cabeça ficam marcados assim no painel até ele confirmar.
110
+
111
+ ---
112
+
113
+ ## FASE 2 · Plano e painel (o coração da skill)
114
+
115
+ 1. Escrever, na pasta do negócio (a mesma da ficha). **Se o negócio ainda não tiver pasta nem ficha, pergunte a ele onde quer que isso fique e crie ali**; não invente um caminho nem deixe o arquivo solto na área de trabalho. Arquivos:
116
+ - `campanhas/<slug-da-campanha>/plano-AAAA-MM-DD.md`: legível, para ele ler.
117
+ - `campanhas/<slug-da-campanha>/plano-AAAA-MM-DD.json`: a fonte do painel, no esquema de `templates/plano.json`. O campo `gerado_em` usa o formato `DD/MM/AAAA HH:MM`.
118
+ **A data vai no nome do arquivo.** Rodar a Fase 2 de novo no mesmo dia sobrescreve o arquivo do dia; rodar em outro dia cria o próximo e o anterior fica. Nunca apagar plano antigo.
119
+ 2. **Gerar o painel com UM comando**, que lê o template, codifica o plano inteiro em base64 (a partir dos bytes UTF-8) e escreve `painel.html` e `plano.b64` na pasta do plano. Nunca monte o painel colando texto à mão: um caractere trocado no base64 muda "R$ 40" para "R$ 90" e passa despercebido.
120
+ 🔴 O plano NUNCA entra no painel como JSON cru. Base64 não contém o caractere `<`, então um texto colado pelo dono (copy de uma página, áudio transcrito, nome com HTML dentro) não consegue fechar a tag antes da hora nem injetar nada. O painel decodifica de volta como UTF-8, então acento sobrevive.
121
+ Troque `TEMPLATE` pelo caminho completo de `templates/painel.html` desta skill e `PLANO` pelo caminho completo do `plano-AAAA-MM-DD.json`:
122
+ - Com Python (macOS, Linux, ou Windows com Python; no Windows o comando pode ser `python` ou `py` em vez de `python3`):
123
+ ```
124
+ python3 -c "import base64,sys,os;t,p=sys.argv[1:3];d=os.path.dirname(os.path.abspath(p));b=base64.b64encode(open(p,'rb').read()).decode();h=open(t,encoding='utf-8').read();assert h.count('__PLANO_JSON__')==1,'template sem o marcador';open(os.path.join(d,'plano.b64'),'w').write(b);open(os.path.join(d,'painel.html'),'w',encoding='utf-8',newline='').write(h.replace('__PLANO_JSON__',b));print('painel escrito em',d)" "TEMPLATE" "PLANO"
125
+ ```
126
+ - Windows sem Python (PowerShell):
127
+ ```
128
+ $t='TEMPLATE'; $p='PLANO'; $d=Split-Path -Parent (Resolve-Path $p); $b=[Convert]::ToBase64String([IO.File]::ReadAllBytes((Resolve-Path $p))); $h=[IO.File]::ReadAllText((Resolve-Path $t)); [IO.File]::WriteAllText("$d\plano.b64",$b); [IO.File]::WriteAllText("$d\painel.html",$h.Replace('__PLANO_JSON__',$b)); "painel escrito em $d"
129
+ ```
130
+ ✅ **Três conferências, as três com comando. Não é para ler e achar que está certo.** Rode na pasta do plano.
131
+
132
+ **Primeira, na string:** o que está no `plano.b64` é base64 e nada mais.
133
+ ```
134
+ macOS/Linux: tr -d '\n' < plano.b64 | grep -qE '^[A-Za-z0-9+/=]+$' && echo OK || echo FALHOU
135
+ Windows: if (((Get-Content plano.b64 -Raw) -replace '\s','') -match '^[A-Za-z0-9+/=]+$') {'OK'} else {'FALHOU'}
136
+ ```
137
+
138
+ **Segunda, no arquivo gerado:** conte `<` nos DOIS arquivos, o painel gerado e o template, pelo caminho completo de cada um.
139
+ ```
140
+ macOS/Linux: grep -o '<' <caminho do painel gerado> | wc -l
141
+ grep -o '<' <caminho do template> | wc -l
142
+ Windows: (Select-String -Path <caminho> -Pattern '<' -AllMatches).Matches.Count
143
+ ```
144
+ **Os dois números têm que ser IGUAIS.** Base64 não contém `<`, e o marcador também não: qualquer `<` a mais só pode ter vindo do que foi inserido.
145
+ 📌 **Número de referência: o template desta versão tem `20` ocorrências de `<`.** Sem esse número, comparar o painel consigo mesmo por engano (o mesmo caminho duas vezes) devolve "bate" até num painel invadido; com ele, um painel invadido dá 22 ou mais contra os `20`.
146
+ ⚠️ Se o comando disser que não achou o arquivo, o resultado não vale: `wc -l` devolve `0` calado. Conserte o caminho e rode de novo.
147
+
148
+ **Terceira, no conteúdo:** o bloco que entrou no painel é exatamente o `plano.b64`.
149
+ ```
150
+ macOS/Linux: [ "$(grep -o 'id="plano"[^>]*>[^<]*' painel.html | sed 's/^.*>//')" = "$(tr -d '\n' < plano.b64)" ] && echo OK || echo FALHOU
151
+ Windows: $h=Get-Content painel.html -Raw; $b=(Get-Content plano.b64 -Raw).Trim(); if (($h -match 'id="plano"[^>]*>([^<]*)') -and ($Matches[1] -eq $b)) {'OK'} else {'FALHOU'}
152
+ ```
153
+ Qualquer `FALHOU` ou contagem diferente: **não abra o painel**. Apague, rode o comando de geração de novo e confira outra vez.
154
+ ⛔ Não substitua a contagem por procurar `</script>` no arquivo: o navegador fecha a tag também com `</SCRIPT>`, `</script >` e quebra de linha antes do `>`, e nenhuma dessas grafias aparece numa busca pelo texto literal (medido em 08/09/2026, as três com injeção real).
155
+ ⚠️ **A ordem importa: gerar, conferir, só então abrir.** O estrago de um `<` colado acontece no instante em que o navegador lê o arquivo.
156
+ 3. Abrir: `open painel.html` no Mac, `start painel.html` no Windows, `xdg-open painel.html` no Linux. O arquivo é estático: sem servidor, sem internet, sem biblioteca externa. No Iron Office, avise por `reply` que abriu (bloco "No Iron Office").
157
+ 4. 🗣️ **O painel é lido por quem NÃO sabe tráfego.** Ele abre com a simulação do anúncio no celular, depois quatro respostas (quanto gasta, quem vê, para onde vai o clique, o que conta como resultado), depois as decisões numeradas. Para isso funcionar, o plano.json precisa de:
158
+ - `resumo`: UMA frase de dono de negócio. "4 anúncios em vídeo para donos de clínica do Brasil inteiro, gastando R$ 40 por dia. Quem clica cai no formulário, e cada formulário enviado conta como resultado."
159
+ - **Todo valor em português simples**, termo técnico só entre parênteses: "o Meta divide o dinheiro sozinho (CBO)", "Formulário enviado", "já existe · ligada · vazia". Nunca `OUTCOME_LEADS`, `CBO`, `ACTIVE` ou nome de ferramenta como valor principal. ID fica nos campos de id, que o painel só mostra na gaveta "Detalhes técnicos".
160
+ - `criativos[].miniatura`: imagem ao lado do painel (`mini/ad1.jpg`). Para vídeo, crie a pasta e tire um quadro:
161
+ ```
162
+ mkdir -p mini (Windows: mkdir mini)
163
+ ffmpeg -ss 1.5 -i video.mp4 -frames:v 1 -vf scale=540:-2 mini/ad1.jpg
164
+ ```
165
+ Vídeo com menos de 1,5 s não gera quadro nenhum e o ffmpeg não reclama: confira se o `.jpg` existe e, se não existir, rode de novo com `-ss 0`. Sem ffmpeg, peça uma captura ao dono ou deixe vazio, e a simulação mostra um aviso no lugar. O `anuncios[].criativo` tem que ser igual ao `criativos[].arquivo` (ou ao `nome`) para a peça aparecer dentro da simulação.
166
+ - Cada decisão aberta é UMA pergunta que se responde com sim, não ou uma escolha, e a `sugestao` diz o que você faria e por quê. O dono responde pelo número.
167
+ 5. O painel é o estado, não um print: **regerar a cada fase**, com o `status` atualizado. Os quatro valores são literais e se escrevem exatamente assim: `PLANEJADA`, `CRIADA PAUSADA`, `ATIVA`, `MEDIDA`. Parafrasear apaga a marcação da régua sem avisar. O campo `rotulo_etapa` (opcional) só troca o nome que o dono lê no passo atual; o ramo rascunho da Fase 4 usa isso.
168
+ 6. Enquanto `campanha.divulgacao_ia` estiver em `a definir`, **acrescente também uma entrada em `decisoes_abertas`** com a pergunta exata. A declaração só existe na criação do criativo e nenhuma ferramenta a muda depois.
169
+
170
+ **PAUSE.** Pergunte se pode criar (no Iron Office, pela `ask`). **Nenhum objeto é criado no Meta antes do aprovado.**
171
+
172
+ ---
173
+
174
+ ## FASE 3 · Criativos
175
+
176
+ 1. **Inventariar a pasta que ele indicou**: nome do arquivo, formato (1:1, 4:5, 9:16), peso, tipo. O upload aceita imagem até 30 MiB e vídeo até 100 MiB. Renomear só com aprovação dele.
177
+ 2. **Se faltar peça:** se a skill `criativos-consciencia` estiver instalada, use-a para montar a matriz por nível de consciência. Se não estiver instalada, proponha três ângulos (prova, objeção, oferta) com copy e descrição de arte, e diga que a skill da matriz não está na máquina.
178
+ 3. **Estático:** produza por HTML e converta para imagem se a máquina tiver navegador headless. Se não tiver, entregue o HTML pronto para ele abrir e exportar, **e diga isso com todas as letras**. Nunca afirme que gerou PNG sem o arquivo existir no disco.
179
+ 4. **Vídeo:** o arquivo é dele. Você escreve roteiro e gancho se ele pedir. **Todo vídeo precisa de uma capa (imagem)**: separe a capa junto com o vídeo, porque sem ela o anúncio não publica.
180
+ 5. Peça que vai ao ar passa pelo `gate` antes, se a skill estiver instalada.
181
+ 6. Atualizar a grade de criativos no painel e **PAUSE** para ele aprovar as peças.
182
+
183
+ ---
184
+
185
+ ## FASE 4 · Montar no Meta (só depois do aprovado)
186
+
187
+ ### Regras de ouro
188
+
189
+ 1. **Nunca os dois mexendo ao mesmo tempo.** Enquanto você monta pelo MCP, ele não mexe no Gerenciador, e vice-versa. Reveze em voz alta: "agora sou eu / agora é você".
190
+ 2. **Tudo nasce PAUSADO, e isso se CONFERE.** A criação não garante pausa sozinha: em conta com modo rascunho, o rascunho vem com `status ACTIVE` preparado (medido em 11/11/2026). O passo (f) abaixo põe a pausa e a lê de volta.
191
+ 3. **Objeto arquivado não se edita nem se reativa pelo MCP.** Só recriando.
192
+ 4. **Um só lugar de orçamento.** CBO na campanha ou ABO no conjunto, nunca os dois. `ads_create_ad_set` rejeita orçamento de conjunto quando a campanha já tem orçamento.
193
+ 5. **WhatsApp:** o número é o que está ligado à **Página** (conta WhatsApp Business conectada a ela), não um campo do conjunto nem do criativo. Ligar o número **só o dono resolve na tela**; o MCP não conecta número, e sem ele o anúncio é criado mas a ativação falha com "Reconnect your WhatsApp number…". Receita do criativo de mensagem: `call_to_action_type: "WHATSAPP_MESSAGE"`, **sem `link_url`**, num conjunto com `destination_type: "WHATSAPP"` (detalhes em `references/estrutura-meta.md`, seção 7).
194
+ 6. **Criativo é imutável.** Errou a copy, a imagem ou o CTA? Cria criativo novo e anúncio novo, e apaga o errado.
195
+ 7. **Divulgação de IA é decisão dele, não sua.** Pergunte, mostre as duas respostas possíveis e use a que ele der; nunca preencha por dedução. A regra inteira está em `references/estrutura-meta.md`, seção 7, que é a fonte única.
196
+
197
+ ### A ordem, com as ferramentas
198
+
199
+ **a) Mídia**: uma por vez, nunca em paralelo:
200
+ `ads_creative_upload_local_image` (`media_kind` `"image"` ou `"video"`, mais `mime_type`, `file_size` em bytes exatos e `image_sha256`) → POST dos bytes na `upload_url` devolvida, com **cinco** headers → `ads_finalize_local_ad_image_upload` com o `completion_token`.
201
+
202
+ Tamanho e sha256 do arquivo:
203
+ ```
204
+ macOS: stat -f%z arquivo.mp4 shasum -a 256 arquivo.mp4
205
+ Linux: stat -c%s arquivo.mp4 sha256sum arquivo.mp4
206
+ Windows: (Get-Item arquivo.mp4).Length (Get-FileHash arquivo.mp4 -Algorithm SHA256).Hash.ToLower()
207
+ ```
208
+
209
+ Os cinco headers, todos obrigatórios (medido em 08/09/2026, nas duas mídias):
210
+
211
+ | Header | Valor | Se faltar |
212
+ |---|---|---|
213
+ | `Authorization` | o `upload_authorization` que veio na MESMA resposta, copiado inteiro | HTTP 400 `NotAuthorizedError: User not authorized to perform this request` |
214
+ | `X-Entity-Name` | o nome do arquivo | erro de validação |
215
+ | `X-Entity-Type` | o mesmo `mime_type` | erro de validação |
216
+ | `X-Entity-Length` | o tamanho em bytes | erro de validação |
217
+ | `Offset` | `0` | HTTP 400 `ParameterValidationError: HeaderValuePredicate: Header Offset not convertable to unsigned long` |
218
+
219
+ ⚠️ O `Authorization` é o que se esquece: vem no corpo da resposta ao lado da `upload_url`. Sem ele nenhuma mídia sobe.
220
+ ⚠️ O `completion_token` é longo (mais de 500 caracteres). Copie-o INTEIRO; truncar dá `The upload completion capability is invalid or expired`, que parece expiração e não é.
221
+ Imagem devolve `image_hash`. Vídeo devolve `video_id` ainda em processamento: **confira por `ads_get_ad_videos` antes de montar o anúncio.**
222
+ ⚠️ `image_url` de site externo pode ser recusado ("A imagem não foi baixada", medido em 11/11/2026). Prefira sempre subir o arquivo e usar o `image_hash`.
223
+ Se o upload falhar por outro motivo que não o header, a reserva é o dono subir no Gerenciador, em "Mídia da conta de anúncios" (não em "Mídia da empresa", que o MCP não enxerga), com nome único, e você acha depois por `ads_get_ad_videos` / `ads_get_ad_images`.
224
+
225
+ **b) Campanha**: `ads_create_campaign`: `objective` ODAX, `buying_type: "AUCTION"`, `special_ad_categories: "[]"` (ou a categoria que o dono confirmou), e o orçamento em **centavos** se for CBO.
226
+ ⭐ **A resposta traz `valid_optimization_goals` e `recommended_optimization_goal`. Use essa lista no passo seguinte em vez de adivinhar.** A lista da conta pode ser MAIOR que a tabela de referência (metas liberadas conta a conta); divergiu, a resposta ganha.
227
+ 🔀 **A resposta decide o ramo da sessão inteira**, e você registra qual foi no plano:
228
+ - `status: "DRAFT"` → **ramo rascunho**. Nada existe de verdade no Meta ainda: está tudo no rascunho do Gerenciador da conta. Siga os passos marcados "rascunho".
229
+ - qualquer outro valor → **ramo ao vivo**. Os objetos já existem, em PAUSED. Siga os passos marcados "ao vivo".
230
+ - a resposta não traz `status` → leia a campanha com `ads_get_ad_entities` (sem `object_state`): achou, é ao vivo; não achou, é **rascunho**.
231
+ Nunca escolha o ramo por suposição nem pelo que funcionou na sessão anterior: a mesma conta pode mudar.
232
+
233
+ **c) Conjunto**: `ads_create_ad_set`: `billing_event`, `optimization_goal` (da lista que a campanha devolveu), `targeting`, `destination_type` e `promoted_object` quando o objetivo exigir. Sem orçamento aqui se a campanha for CBO. Detalhes que fazem o create falhar estão em `references/estrutura-meta.md`: pixel em vendas no site, página com termos de cadastro aceitos, DSA na Europa, e o Advantage+ que transforma faixa etária em sugestão.
234
+
235
+ **d) Criativo**: `ads_create_creative`: `page_id` sempre, `instagram_user_id` se quiser entrega no Instagram. O criativo é criado na hora, nos dois ramos (não passa pelo rascunho).
236
+ - Imagem: `link_url` mais `image_hash`.
237
+ - Vídeo: `video_id` mais **capa obrigatória** (`image_hash` da capa). Sem capa não publica (medido em 11/11/2026: erro `1443226 · Seu anúncio precisa de uma miniatura de vídeo`, e o publicar recusa a campanha inteira).
238
+ - Mensagem no WhatsApp: `call_to_action_type: "WHATSAPP_MESSAGE"` sem `link_url` (regra de ouro 5).
239
+ - Carrossel manual: 2 a 10 `cards`.
240
+
241
+ **e) Anúncio**: `ads_create_ad` com `creative: {"creative_id": "..."}`.
242
+
243
+ **f) Pausar e conferir**
244
+ - **Rascunho:** a criação devolve `status DRAFT`, mas o que fica preparado é `status ACTIVE` (medido em 11/11/2026). Se alguém publicar assim, pelo MCP ou pelo botão do Gerenciador, a campanha entra no ar gastando. Por isso, logo depois de criar: `ads_update_entity` com `{"status":"PAUSED"}` na campanha, no conjunto e em cada anúncio (cada um volta `is_draft: true`). Depois leia `ads_get_ad_entities` com `object_state: "draft"` e `object_ids: [<id da campanha>]` e confira, objeto por objeto, `values.status.new = PAUSED` e `active_errors` vazio. Erro listado → corrija com `ads_update_entity` antes de seguir. Na leitura normal (sem `object_state`) a campanha ainda **não aparece**: é o esperado.
245
+ - **Ao vivo:** leia `ads_get_ad_entities` com os ids e confira `status PAUSED` nos três níveis. Veio algum `ACTIVE`? Pause na hora (`{"status":"PAUSED"}`), leia de novo e diga ao dono o que aconteceu.
246
+ - `ads_get_ad_preview` com o `ad_id` (ou o `creative_id`, se o anúncio ainda não materializou) [schema, não medido no rascunho]. **Essa ferramenta não aceita `ad_account_id`: passar rejeita a chamada.** Mostre o `preview_url` ao dono, literal, como link clicável.
247
+ - `ads_get_errors` com os IDs da campanha e dos filhos. Ele **não** cobre reprovação de anúncio, conta restrita nem o erro de WhatsApp: vazio é "não há erro bloqueante desses", não "está tudo certo".
248
+ - Gravar todos os IDs e o ramo no plano, regerar o painel com status `CRIADA PAUSADA`. **No ramo rascunho, com `rotulo_etapa: "Em rascunho, sem gastar"`.**
249
+
250
+ **O que você diz ao dono sai do ramo:**
251
+ - Rascunho: "Está em rascunho no Gerenciador, nada foi criado de verdade ainda e nada gasta. Pode revisar lá, mas **não clique em Publicar**: quem publica sou eu, quando você mandar ativar."
252
+ - Ao vivo: "Tudo criado e pausado. Pode revisar no Gerenciador e fechar a tela de edição."
253
+ Depois, a pausa da Fase 5 (no Iron Office, `ask` "Ativa agora" / "Ainda não"). Se for o caso, lembre de ligar o WhatsApp Business na Página antes.
254
+
255
+ ### Se precisar desfazer
256
+
257
+ - **Rascunho que nunca foi publicado:** `ads_update_entity` com `discard_draft_changes: true` e sem `fields`. A primeira chamada **não apaga nada**: devolve `discard_preview` (tudo o que sairia) e um `confirmation_token`. Mostre a lista ao dono, inclusive qualquer item com `source` diferente de `mcp_campaign_creation` (foi feito à mão no Gerenciador), e só com o sim dele repita a chamada com o `confirmation_token`. A campanha nunca publicada some com os filhos (medido em 11/11/2026).
258
+ - **Já publicado, ramo rascunho:** pausar é direto (`{"status":"PAUSED"}` sozinho volta `is_draft: false` e vale na hora). Já `{"status":"DELETED"}` **não apaga na hora**: fica preparado no rascunho (`is_draft: true`) e o objeto continua como estava, inclusive ACTIVE. Pause primeiro; depois prepare `DELETED` no anúncio, no conjunto e na campanha e publique só eles: `ads_activate_entity` com `entity_id` = a campanha, `entity_type: "campaign"` e `object_ids` = os três ids. Leia de volta até ver `DELETED` (medido em 11/11/2026: a campanha se apaga assim pelo conector).
259
+ - **Ramo ao vivo:** `{"status":"DELETED"}` apaga anúncio e conjunto, mas na campanha o servidor grava `PAUSED` e denuncia em `status_forced_to_paused: true` (medido em 08/09/2026). Campanha se apaga à mão, no Gerenciador.
260
+ - O criativo não passa pelo rascunho e sobra na biblioteca da conta depois de descartar ou apagar o anúncio: se não vai ser usado, `ads_creative_delete` com o `creative_id`.
261
+ - Nos dois ramos: **nunca diga "apaguei" sem ler de volta** com `ads_get_ad_entities` e `time_range` incluindo hoje (gasto e impressão também).
262
+
263
+ ⛔ **Encerrar a sessão aqui, com tudo pausado ou em rascunho, exige o fechamento escrito da Fase 5.** Peça parada esperando um passo humano sem prazo é exatamente o defeito que esta skill existe para não repetir.
264
+
265
+ ---
266
+
267
+ ## FASE 5 · Ativar, medir e fechar
268
+
269
+ 1. **Só com o ativa dele.** Antes de qualquer chamada, lembre o que vai acontecer: "a partir de agora começa a gastar R$ X por dia".
270
+ 2. **Ramo rascunho, publicar primeiro.** Logo antes, releia o rascunho (`object_state: "draft"`, `object_ids: [<id da campanha>]`): todo objeto tem que estar com `values.status.new = PAUSED`, inclusive anúncio criado depois da Fase 4 ou mexido no Gerenciador. Faltou em algum, prepare o `PAUSED` nele antes. Então `ads_activate_entity` com `entity_id` = a campanha e `entity_type: "campaign"`, **sem** `publish_as_active`. Como a Fase 4 preparou `PAUSED` em tudo, o publicar cria os objetos de verdade e PAUSADOS (medido em 11/11/2026). A resposta é `PUBLISHING`, assíncrona: espere alguns segundos e leia `ads_get_ad_entities` (sem `object_state`) até a campanha aparecer, com os três níveis em `PAUSED`. Apareceu algum `ACTIVE` que não devia? Pause na hora e diga ao dono. Confirmado tudo em `PAUSED`, regere o painel com `CRIADA PAUSADA` e **sem** `rotulo_etapa`: agora existe de verdade.
271
+ ⚠️ Publicar sem ter preparado o `PAUSED` põe tudo `ACTIVE` de uma vez (medido em 11/11/2026). `publish_as_active: true` ativa só o objeto do `entity_id`, e os outros publicados junto ficam com o status preparado [schema, não medido]. Não use os dois como atalho.
272
+ Recusa por validação ("Nothing was published because of blocking validation errors") lista os objetos com erro e **nada foi publicado**: corrija com `ads_update_entity` e publique de novo. `ignore_validation_errors: true` publica o resto e deixa os quebrados no rascunho; só com o dono vendo os erros e mandando.
273
+ 3. **Ativar, nos dois ramos, de cima para baixo:** `ads_activate_entity` na campanha, depois no conjunto, depois em cada anúncio. **Ativar o pai não ativa o filho** (medido em 08/09 e de novo em 11/11/2026): os três níveis precisam estar ACTIVE para entregar.
274
+ 4. Ler de volta: os três níveis em `ACTIVE` (anúncio novo costuma aparecer em análise, `IN_PROCESS` ou `PENDING_REVIEW`, por algumas horas). `ads_get_errors` vazio. Painel → `ATIVA` (sem `rotulo_etapa`), com a hora.
275
+ 5. **No dia seguinte: medir.** `ads_get_ad_entities` com `time_range` explícito **incluindo o dia de hoje** (`date_preset: "last_7d"` e `"last_3d"` excluem o dia corrente e produzem falso "peça parada"). Critério: **impressão maior que zero em CADA anúncio**. Campo ausente na resposta significa zero. Painel → `MEDIDA`. Peça em zero vira alerta na skill `anuncios`.
276
+ 6. **Fechamento, sempre:**
277
+ - ficha do negócio, bloco "Informação que vence": a promoção desta campanha, até quando vale, e os IDs da campanha, conjuntos e anúncios, a verba e as datas;
278
+ - estado do que ficou feito e pendente: pela skill `salvar`, se estiver instalada e o dono já tiver cofre;
279
+ - o que se aprendeu e serve de novo (a copy que converteu, o erro que a Meta deu e como passou): pela skill `anotar`, nas mesmas condições;
280
+ - toda pendência com **prazo e passo exato**. "Publicar depois" não é pendência; "ativar os dois anúncios de vídeo depois de ligar o WhatsApp Business, até DD/MM" é.
281
+ ✅ Depois de escrever, **leia os arquivos de volta** e confirme que o texto entrou.
282
+
283
+ ---
284
+
285
+ ## Cuidado com o que a ferramenta responde
286
+
287
+ - `updated_fields` de `ads_update_entity` **ecoa o pedido, não o estado gravado**. Olhe o `is_draft`: `true` quer dizer que a mudança ficou preparada no rascunho e ainda não vale no ar.
288
+ - `PUBLISHING` é "em publicação", não "no ar". Resposta de sucesso não é efeito: o que prova é a leitura seguinte.
289
+ - Rascunho se lê com `object_state: "draft"` (resultado em `ad_drafts`, id em `ad_object_id`); objeto publicado se lê sem esse campo. Um não aparece na leitura do outro.
290
+
291
+ ## O que esta skill NÃO decide
292
+
293
+ Verba, público final, preço, ativar e pausar são do dono. Você mede, sugere com motivo e executa o que ele aprovou.
294
+ Conteúdo de categoria especial (crédito e produtos financeiros, emprego, moradia, temas sociais e eleições, jogos de aposta) exige `special_ad_categories` preenchido e muda o que pode ser segmentado: **avise e pergunte, não decida**. Setor regulado (saúde, estética, finanças, emagrecimento) tem regra de publicidade própria e, às vezes, conselho de classe.
295
+
296
+ ## Dependências opcionais
297
+
298
+ | O que | Para quê | Se não tiver |
299
+ |---|---|---|
300
+ | `anuncios` (ou `ads-check`, se estiver instalada) | olhar a conta no início e medir depois | dizer que não rodou e medir o essencial na Fase 0 |
301
+ | `loja` | a ficha do negócio (`PROJETO.md`) | usar a nota que o dono indicar |
302
+ | `criativos-consciencia` (se estiver instalada) | matriz de 6 criativos por nível de consciência | propor 3 ângulos à mão e dizer que a skill não está instalada |
303
+ | `gate` | auditar a peça antes de publicar | avisar que a peça não passou por auditoria |
304
+ | `salvar` e `anotar` | fechamento | escrever na ficha e dizer que o resto não foi registrado |
305
+ | navegador headless | virar HTML em PNG | entregar o HTML e dizer que a conversão é com ele |
306
+
307
+ Falta de dependência se diz. Nunca simule o resultado de uma ferramenta que não existe na máquina.
@@ -0,0 +1,80 @@
1
+ # copy-e-nomes — como nomear e como escrever a peça
2
+
3
+ Referência de consulta da skill `subir-anuncio`.
4
+
5
+ ---
6
+
7
+ ## 1. Convenção de nome
8
+
9
+ O nome é o único campo que a API lê **e** um humano também. Por isso **o que vence vai no nome**.
10
+
11
+ ```
12
+ campanha: <negócio> - <objetivo> - <oferta> - MM/AA
13
+ conjunto: <público> - <otimização> - <destino>
14
+ anúncio: <produto> - <ângulo> - <formato> - DD/MM
15
+ ```
16
+
17
+ Exemplos:
18
+
19
+ ```
20
+ campanha: Loja X - vendas - coleção verão - 09/26
21
+ conjunto: Brasil 25-45 - conversões - site
22
+ anúncio: Tênis Alfa - prova - vídeo 9x16 - 15/09
23
+ ```
24
+
25
+ Regras:
26
+ - **Data no nome do anúncio quando a peça vence** (atendimento, turma, promoção com prazo). Peça sempre-verde não leva data, e isso é normal.
27
+ - Duas datas no nome ("11 e 12/09") vencem na ÚLTIMA.
28
+ - O nome não substitui a arte: a data no nome pode divergir da data dentro da imagem. Conferir a arte é passo humano.
29
+ - Renomear peça antiga zera o `updated_time` dela e a faz parecer nova para quem lê a conta (a skill `anuncios` inclusive). Renomeie com intenção.
30
+ - Se o negócio já usa outra convenção, **mantenha a dele** e adapte a leitura. Convenção nova se propõe, não se impõe.
31
+
32
+ ---
33
+
34
+ ## 2. Os quatro campos de texto
35
+
36
+ | Campo no MCP | O que é | Tamanho que costuma caber |
37
+ |---|---|---|
38
+ | `message` | texto primário, acima da mídia | as 2 primeiras linhas aparecem antes do "ver mais" |
39
+ | `headline` | título, abaixo da mídia, em negrito | curtíssimo, some rápido no celular |
40
+ | `description` | descrição sob o título | nem sempre aparece; nunca ponha aí o que é essencial |
41
+ | `call_to_action_type` | o botão | valor de lista fechada, não texto livre |
42
+
43
+ O limite exato varia por posicionamento e muda sem aviso. Em vez de decorar número: **escreva o essencial nas duas primeiras linhas do `message`** e trate `headline` e `description` como reforço.
44
+
45
+ CTA mais usados: `SHOP_NOW`, `BUY_NOW`, `LEARN_MORE`, `SIGN_UP`, `GET_QUOTE`, `WHATSAPP_MESSAGE`, `MESSAGE_PAGE`, `BOOK_NOW`, `APPLY_NOW`, `DOWNLOAD`, `CONTACT_US`, `GET_OFFER`, `SUBSCRIBE`. Escolha pelo rótulo que o dono usaria, não pelo que soa mais forte.
46
+
47
+ ⛔ **Valor fora da lista da API é recusado.** Não deduza o nome pelo texto do botão: para mandar mensagem os valores reais são `WHATSAPP_MESSAGE` e `MESSAGE_PAGE` (não existe `SEND_MESSAGE`). Na dúvida, confira a lista de `call_to_action_type` na descrição de `ads_create_creative` antes de usar.
48
+
49
+ ---
50
+
51
+ ## 3. Como escrever
52
+
53
+ - **O que a ficha não diz, o anúncio não promete.** Preço, prazo, garantia, resultado, número de clientes: só entra na peça o que está na ficha do negócio ou o dono confirmou nesta sessão. Faltando, escreva `[PREENCHER: ...]` e leve como decisão aberta no painel. Dado inventado em anúncio é risco jurídico e queima conta.
54
+ - **Específico vence esperto.** "Entrega em 48 h em toda a capital" vale mais que "agilidade que você merece".
55
+ - **Voz ativa, e o botão diz o que acontece.** "Falar no WhatsApp", não "Saiba mais" quando o destino é conversa. O mesmo nome do produto segue até o fim: anúncio, página e checkout.
56
+ - **A primeira linha carrega a oferta.** O resto do texto é para quem já parou.
57
+ - Sem emoji como marcador de lista. Sem travessão. Sem "eleve", "desbloqueie", "transforme", "não perca". Sem caixa alta gritada.
58
+ - Uma promessa por peça. Anúncio que promete três coisas não é lembrado por nenhuma.
59
+
60
+ ---
61
+
62
+ ## 4. Regras que valem em toda peça
63
+
64
+ 1. **Peça permanente não leva data nem preço** que mudam. A peça fica mentindo na tela depois que a promoção acaba, e ninguém lembra de tirar.
65
+ 2. **Data na copy e data na arte mudam no mesmo passo.** Trocar uma e esquecer a outra é o defeito mais comum da troca de criativo.
66
+ 3. **Um destino só, o mesmo em tudo.** O número de WhatsApp escrito na copy, o da arte e o que está ligado à Página têm que ser o mesmo número. Confira os três.
67
+ 4. **Setor regulado tem regra própria** (saúde, estética, finanças, crédito, emagrecimento, emprego), às vezes com conselho de classe. Avise o dono antes de publicar; a responsabilidade é dele, mas o aviso é seu.
68
+ 5. **Palavras proibidas da ficha do negócio** passam por cima de qualquer sugestão sua.
69
+
70
+ ---
71
+
72
+ ## 5. Antes de dar a copy por pronta
73
+
74
+ - [ ] Toda afirmação sai da ficha, do dono ou de uma campanha antiga real?
75
+ - [ ] A oferta está nas duas primeiras linhas do texto primário?
76
+ - [ ] O CTA descreve o que acontece ao clicar, e bate com o destino do conjunto?
77
+ - [ ] Data, preço e número aparecem iguais na copy, na arte e no destino?
78
+ - [ ] Alguma promessa fora do que o negócio entrega hoje?
79
+ - [ ] Trocando o nome do produto, o texto serviria para qualquer concorrente? Então falta o que só este negócio pode dizer.
80
+ - [ ] Restou algum `[PREENCHER: ...]`? Ele vai como decisão aberta no painel, não como texto publicado.