iron-edge 2.11.0 → 2.12.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, 19 skills e memória entre sessões.**
3
+ **44 agentes de topo, 18 squads, 20 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 19, e o Claude Code as reconhece por `/nome`:
34
+ **Skills — essas viram comando de barra.** São 20, e o Claude Code as reconhece por `/nome`:
35
35
 
36
36
  ```
37
37
  /gate → auditoria de qualidade antes de entregar
@@ -42,6 +42,7 @@ Existem **duas coisas diferentes** aqui, e elas se chamam de jeitos diferentes.
42
42
  /loja → a ficha da sua loja no cofre (lê a Shopify)
43
43
  /trilha → a próxima etapa da sua loja, medida (no Iron Office: botão "Pedir ao Iron")
44
44
  /rastreamento-pixel → a Meta recebendo as vendas da loja, sem contar em dobro
45
+ /anuncios → o retrato dos seus anúncios da Meta e o que corrigir hoje (no Iron Office: aba Anúncios)
45
46
  ```
46
47
  (As outras: `navegador` (regras do Iron no seu Chrome), `anotar`, `faxina`, `conectar-mcp`, `roteiro-video`, `lp-cinematico`, `clone-site`,
47
48
  `clone-inventory`, `clone-distill`, `clone-organize`, `clone-transplant`.)
@@ -247,6 +248,8 @@ O que esperar:
247
248
  4. Abra a página **Iron** do dashboard. Em até 1 minuto aparece "Iron online". Escreva ali e o Iron responde ali.
248
249
  5. **Ficha da loja** (skill `loja`, desde a 2.8.0): no site, "Começar com a loja X" (ou diga "monta a ficha"). O Iron lê a Shopify da loja, aponta o que está errado, pergunta só o que falta e grava `Projetos/<loja>/PROJETO.md` e `brand.json` no seu cofre; pro site vai só um resumo de até 600 caracteres (sem sócio, fornecedor, conta de anúncio nem pedido). Daí em diante todo pedido daquela loja chega com a ficha. Desde a 2.9.0, no site as perguntas vêm uma por vez, com botões.
249
250
  **Trilha da loja** (skill `trilha`, desde a 2.9.0): no chat, o botão da loja mostra "4/13 etapas" e o atalho **Trilha** (o primeiro, acima da caixa de mensagem) abre a lista (marca, idioma, imagens, velocidade, página de obrigado, pixel, WhatsApp, Instagram, conta de anúncio, compra teste…). "Pedir ao Iron" manda a etapa; o Iron mede na loja e na Meta, faz o que dá e grava a prova que mediu. Etapa que só você pode fazer (login, cartão, configuração no admin) vira um passo no AGORA VOCÊ. Desde a 2.10.0 o Iron conduz todas as etapas de quem já tem loja (skills `rastreamento-pixel` e `navegador`). Desde a 2.11.0 conduz também o caminho de quem ainda não tem loja: produto e nicho (com 3 concorrentes que anunciam agora) e nome com domínio e @ livres (medidos); a ficha do projeto nasce no cofre.
251
+
252
+ **Anúncios** (skill `anuncios`, desde a 2.12.0): na aba Anúncios do site, o botão **Atualizar agora** (ou no chat "como estão meus anúncios") faz o Iron medir os últimos 7 dias da sua conta da Meta e mostrar gasto, resultados, custo por resultado e o que corrigir hoje: peça nova que não aparece há mais de 48 h, data vencida ainda no ar, dinheiro indo pra peça vencida e peça recusada. O Iron só lê; pausar uma peça ele pergunta antes. A Meta tem que estar ligada no seu Iron (`/mcp` → `meta-ads` → Authenticate).
250
253
  6. **Deixe essa aba do terminal aberta.** É ela que faz o Iron responder no site.
251
254
  7. **Pra fechar:** Ctrl+C duas vezes ou `/exit`, e o escritório anoitece em 1 a 2 segundos. No **Warp**, fechar a aba pelo X demora cerca de 1 minuto: o Warp guarda a aba fechada pra poder reabrir, e nesse tempo o canal ainda está vivo. Feche com Ctrl+C antes do X, ou desligue a reabertura de abas fechadas nas configurações do Warp.
252
255
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "iron-edge",
3
- "version": "2.11.0",
4
- "description": "Ecossistema de agentes para Claude Code: 44 agentes de topo, 18 squads e 19 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.12.0",
4
+ "description": "Ecossistema de agentes para Claude Code: 44 agentes de topo, 18 squads e 20 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",
@@ -0,0 +1,114 @@
1
+ ---
2
+ name: anuncios
3
+ description: Fotografa a conta de anúncios da Meta do projeto (últimos 7 dias), acha os 3 problemas que a Meta não avisa (peça nova que não aparece, data vencida no ar, dinheiro na peça errada) e mais a peça recusada, e grava o retrato na aba Anúncios do Iron Office. Use quando chegar `anúncios: atualizar` (botão do site) ou o aluno disser "como estão meus anúncios", "meus anúncios", "quanto gastei", "o anúncio parou", "por que meu anúncio não roda".
4
+ ---
5
+
6
+ # anuncios — o retrato da conta da Meta, com o que fazer hoje
7
+
8
+ O aluno abre a aba Anúncios do projeto e vê gasto, resultados, custo por resultado e os alertas. Quem tira esse retrato é você, com a conta dele, no computador dele. O site só guarda o que você mediu (ferramenta `ads_status`): nunca token, nunca login, nunca nome de pessoa nem telefone.
9
+
10
+ **Regras que não mudam:**
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.
13
+ - **Zero alerta é resultado válido.** Diga em 1 linha e grave o retrato do mesmo jeito.
14
+
15
+ Palavras de aluno: "conjunto de anúncios" vira **grupo**; "CPA" vira **custo por resultado**; "impressões" vira **vezes que apareceu**; status técnico (`effective_status`, `ACTIVE`) nunca aparece: diga "no ar" ou "pausada".
16
+
17
+ ## 0. Antes
18
+
19
+ Leia a ficha do projeto (o `PROJETO.md` da linha `[loja: …]`): a linha **Anúncios** (conta de anúncio), país e moeda, e se houver, a data que vale agora (turma, promoção, "vagas preenchidas").
20
+
21
+ ## 1. Sem a Meta nesta sessão
22
+
23
+ Se as ferramentas `mcp__meta-ads__*` não existem: não diga "não dá". Uma linha ("pra eu ler os seus anúncios, o Iron precisa estar ligado na sua conta do Facebook; é uma vez só") e os 3 passos, os mesmos da skill `rastreamento-pixel`:
24
+
25
+ AGORA VOCÊ
26
+ 1. No terminal onde o Iron roda, digite `/mcp` e aperte Enter.
27
+ 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 a loja e autorize.
28
+ 3. Feche o Iron (Ctrl+C duas vezes), abra de novo com `ironoffice` e peça "anúncios: atualizar".
29
+
30
+ Pare aqui. **Não grave retrato** (a aba já mostra esses passos sozinha).
31
+
32
+ ## 2. Qual conta
33
+
34
+ `ads_get_ad_accounts` (a lista vem em páginas de 50: com `next_cursor`, chame de novo com ele até acabar). Só servem as com `is_ads_mcp_enabled: true` **e** `is_queryable: true`; conta do projeto com `is_queryable: false`: diga em 1 linha o `not_queryable_reason` (é a Meta explicando: conta desativada, pagamento pendente…) e pare.
35
+ - A conta da linha Anúncios da ficha, se está na lista: é ela.
36
+ - Sem ficha e uma conta só: é ela. Várias: `ask` "Qual conta anuncia este projeto?" (opções = os nomes, até 6; `skip: true`) e grave a escolha na linha **Anúncios** da tabela da ficha (bloco `<!-- iron:ficha -->`, mesclando, como na skill `loja`).
37
+ - A conta do projeto veio com `is_ads_mcp_enabled: false`: diga em 1 linha que a Meta ainda não liberou a leitura dessa conta pro Iron (está liberando aos poucos) e pare. Nunca troque por outra conta em silêncio.
38
+ - Moeda da conta diferente da moeda da loja: diga em 1 linha (a etapa `conta_anuncio` da trilha trata) e siga medindo.
39
+
40
+ Nas ferramentas, `ad_account_id` é só o número (sem `act_`).
41
+
42
+ **Fuso e "hoje":** `ads_get_ad_entities` com `level: "ad_account"` e `fields: ["timezone_name"]`. "Hoje" é a data **nesse fuso** (calcule no terminal, vale no Mac e no Windows; devolve hoje, hoje − 6 e hoje − 2, em AAAA-MM-DD, sem conta de cabeça na virada do mês: `node -e "const z='<timezone_name>',d=n=>new Date(Date.now()-n*864e5).toLocaleDateString('sv',{timeZone:z});console.log(d(0),d(6),d(2))"`), e todas as janelas abaixo partem dele. Hora pro aluno, sempre nesse fuso e com "há N h".
43
+
44
+ ## 3. Medir (7 dias, com hoje)
45
+
46
+ ⛔ **Nunca `date_preset: "last_7d"` nem `last_3d`.** Eles deixam o dia de hoje de fora: a peça ligada ontem aparece com zero enquanto já está aparecendo, e você acusaria uma peça boa. Sempre `time_range` explícito, como texto JSON: `'{"since":"<hoje − 6 dias>","until":"<hoje>"}'`.
47
+
48
+ Antes de passar um campo novo em `fields`, confira com `ads_get_field_context` (a ferramenta recusa campo que não existe naquele nível). Os desta skill, conferidos em 30/10/2026.
49
+
50
+ **Como os números chegam (medido):** `amount_spent` vem como `{"value": "152.40", "unit": "BRL"}`: texto, já na moeda da conta (não é centavo). `results` vem como `{"indicator": "...", "value": "6"}` e, sem resultado, `"value": "Not available"`. `cost_per_result` igual, às vezes com o texto do tipo entre parênteses. Regra: converta `value` pra número; `"Not available"`, vazio ou campo ausente = **0**. O `indicator` diz o tipo de resultado (ex.: `reach` = alcance, `...messaging_conversation_started...` = conversa iniciada, `...purchase...` = compra).
51
+
52
+ a) **Por peça, 7 dias:** `ads_get_ad_entities` com `level: "ad"`, `time_range` dos 7 dias, `fields: ["name","campaign_name","adset_name","adset_id","effective_status","amount_spent","impressions","clicks","results","updated_time","created_time","creative_id"]`. Siga `pagination.next_cursor` até o fim (repetindo todos os outros parâmetros). **Campo ausente = 0**: peça sem gasto volta sem `amount_spent` e sem `impressions`, não com zero. O **gasto de cada grupo nos 7 dias** é a soma das peças dele (junte por `adset_id`, nunca pelo nome).
53
+ b) **Por campanha, 7 dias:** a mesma chamada com `level: "campaign"` e `fields: ["name","effective_status","objective","amount_spent","impressions","clicks","results","cost_per_result"]`, até a última página. **Os totais do retrato (`spend`, `impressions`, `clicks`, `results`) são a soma de TODAS as campanhas lidas**, não só das 10 que vão pro retrato.
54
+ c) **Por peça, 3 dias** (só pro alerta C): `level: "ad"`, `time_range` `'{"since":"<hoje − 2>","until":"<hoje>"}'`, `fields: ["name","campaign_name","adset_id","effective_status","amount_spent"]`, até a última página. O gasto do grupo nos 3 dias = soma das peças dele por `adset_id`. Pro rótulo do resultado, `level: "adset"` com `fields: ["name","optimization_goal"]` (7 dias).
55
+ d) **Erros:** `ads_get_errors` com `entity_ids: ["<número da conta>"]` (traz os erros das peças dela).
56
+ e) **Texto das peças:** `ads_get_creatives` com `creative_ids` (os do passo a, em lotes) e `fields: ["body","title"]`.
57
+
58
+ **Resultado** = o que a campanha busca (compra, conversa, cadastro): leia o `indicator` do `results`, o `objective` da campanha e o `optimization_goal` do grupo e escreva o rótulo em palavra de aluno ("compras", "conversas no WhatsApp", "cadastros"). Campanhas com tipos de resultado diferentes: some `results` mesmo assim e use "resultados" no rótulo, dizendo na resposta quais tipos entraram. Em dúvida, "resultados".
59
+
60
+ ## 4. Os alertas
61
+
62
+ A, B e C só olham peça no ar (`effective_status` `ACTIVE`). A **recusada** olha qualquer situação: peça recusada aparece como `DISAPPROVED` ou `WITH_ISSUES`, nunca como `ACTIVE`.
63
+
64
+ **A · nova_em_zero (peça nova sem aparecer).** Impressões = 0 nos 7 dias **e** passaram mais de 48 h desde `updated_time` **e** o grupo dela gastou mais que 0 nos 7 dias (a soma do passo 3a). Conta-se do `updated_time`, não do `created_time`: a peça que foi editada volta pra fila de entrega da Meta, então a rampa recomeça na edição. No `detail`, escreva "desde a última mudança, em <data e hora>". Com menos de 48 h a peça está **em rampa**: não é alerta, vai pra lista `ramp` com `until` = `updated_time` + 48 h ("reconferir em"). A Meta leva horas pra distribuir entre peças novas; acusar antes disso ensina o aluno a ignorar o alerta.
65
+ - **recusada:** peça com erro no `ads_get_errors` (reprovação, revisão, texto ou imagem recusados) ou com `effective_status` `DISAPPROVED` entra como `recusada` **com qualquer idade e qualquer situação**: não é rampa, é peça que nunca vai entregar. Rode `ads_get_errors` justamente pra separar as duas.
66
+
67
+ **B · data_vencida (data vencida no ar).** Data no nome da peça ou no texto (`body`/`title`) anterior a hoje. Formatos: `DD/MM`, `DD e DD/MM`, `até DD/MM`, "dia 25 de outubro", e `turma MM/AA` (mês inteiro: só vence depois do último dia do mês). Só conta como data o que é data de verdade: dia de 1 a 31 e mês de 1 a 12, perto de palavra de data ("dia", "até", "turma", "em", um mês por extenso) ou no formato da convenção do nome; "24/7", "50/50", "3/4" e proporção não são data. Com mais de uma data, vale a **última** (se a última ainda não passou, não é alerta). Ano: o corrente; se a data no ano corrente ficou mais de 6 meses pra trás, é do ano seguinte. Em dúvida se é data, não acuse: diga na resposta "a peça X tem '<trecho>', não sei se é data". Antes de acusar, leia `campaign_name`: a mesma data pode ser de turma futura numa campanha e de atendimento passado em outra. Se a ficha tem a data que vale agora ou "vagas preenchidas", cruze com ela. Peça sem data não entra no B (só no A).
68
+
69
+ **C · gasto_na_peca_errada (dinheiro na peça errada).** Nos últimos 3 dias, mais de 80 % do gasto de um grupo foi em peças com data vencida (B). O `detail` diz a porcentagem e o valor.
70
+
71
+ **O que não dá pra ler:** a arte (texto dentro da imagem ou do vídeo) e a mensagem de boas-vindas do WhatsApp. No retrato `checked.art` é sempre `false`, e a resposta diz "conferi o texto de N peças; a arte não".
72
+
73
+ Cada alerta leva a peça, a campanha, o número que o sustenta (`detail`, até 160 caracteres) e o que fazer (`action`, até 160): ex. `detail` "no ar desde 27/10 14h, 0 vezes que apareceu, grupo gastou R$ 48 no período"; `action` "confira se o público do grupo é grande o bastante ou pause e suba a peça num grupo próprio". Nada de nome de pessoa, telefone ou e-mail nesses textos.
74
+
75
+ ## 5. Gravar
76
+
77
+ `ads_status` com o `project_id` (o `id:` da linha `[loja: …]`) e o `snapshot`:
78
+
79
+ ```json
80
+ { "v": 1, "at": "<agora, ISO com fuso>", "account_id": "<número da conta>", "account_name": "<nome da conta, até 60>",
81
+ "currency": "<moeda da conta, 3 letras>", "window_days": 7,
82
+ "spend": 0, "impressions": 0, "clicks": 0, "results": 0, "result_label": "compras", "cpa": null,
83
+ "campaigns": [{ "name": "…", "status": "ACTIVE", "spend": 0, "results": 0 }],
84
+ "top_ads": [{ "name": "…", "campaign": "…", "spend": 0, "impressions": 0, "results": 0 }],
85
+ "alerts": [{ "kind": "data_vencida", "ad": "…", "campaign": "…", "since": "<ISO, opcional>", "detail": "…", "action": "…" }],
86
+ "checked": { "ads": 0, "copy": 0, "art": false },
87
+ "ramp": [{ "ad": "…", "until": "<ISO>" }] }
88
+ ```
89
+
90
+ - `campaigns`: até 10, as que gastaram mais primeiro. `status` = o `effective_status` como veio (`ACTIVE`, `PAUSED`, `ARCHIVED`, `CAMPAIGN_PAUSED`…): o site mostra `ACTIVE` como "no ar" e o resto como "pausada". `top_ads`: as 5 peças que mais gastaram. `alerts` e `ramp`: até 10 cada. `cpa` = gasto ÷ resultados (`null` sem resultado). `checked.ads` = peças medidas; `checked.copy` = peças com texto lido.
91
+ - Até 8 kB: nomes longos, encurte. Nome com telefone, e-mail ou `@perfil` chega no site como `[removido]` (o filtro protege o aluno); é esperado.
92
+ - A ferramenta recusou (`O site recusou o retrato: …`)? Corrija o que ela disse e mande de novo uma vez. Recusou de novo: responda os números no chat e diga que o retrato não foi gravado.
93
+
94
+ Na ficha: a linha Anúncios com a conta (se faltava) e 1 linha no Histórico: `AAAA-MM-DD: anúncios medidos pelo Iron: gasto <valor>, <N> alertas`.
95
+
96
+ ## 6. Responder
97
+
98
+ Até 4 linhas:
99
+ 1. "Últimos 7 dias: <gasto> e <N> <rótulo> (custo por resultado <valor>)."
100
+ 2. "<N> alertas" ou "Nada pra corrigir hoje."
101
+ 3. "Conferi o texto de <N> peças; a arte não."
102
+ 4. "O retrato está na aba Anúncios."
103
+
104
+ Com alerta, termine com o AGORA VOCÊ: o clique certo (no Gerenciador de Anúncios, a peça X → desligar) ou a oferta de pausar:
105
+ - `ask` "Quer que eu pause a peça <nome>?" (opções Sim / Não). Só no **Sim**: `ads_update_entity` com `entity_type: "ad"`, `entity_id` da peça, `fields: '{"status":"PAUSED"}'`. Não chame `ads_activate_entity` depois. Confira lendo de volta (`ads_get_ad_entities` `level: "ad"` com `object_ids` = a peça): só diga "pausada" se o `effective_status` voltou pausado. Depois do sim, tire o retrato de novo (passos 3 a 5) pra aba ficar certa.
106
+ - Uma pergunta por mensagem; uma peça por vez.
107
+
108
+ ## Teste do instrumento (pra quem for mexer nesta skill)
109
+
110
+ Os dois lados, sempre:
111
+ - **Acusa:** peça no ar há mais de 48 h (por `updated_time`), zero vezes que apareceu, grupo gastando → `nova_em_zero`. Peça com data `25/10` no nome, no ar em 30/10 → `data_vencida`.
112
+ - **Não acusa:** peça de 27 h com zero (vai pra `ramp`); peça pausada com data vencida; peça com `— 11 e 12/12` em 30/10 (data futura); `turma 10/26` em 30/10/2026 (o mês ainda não acabou); "atendimento 24/7"; peça ligada ontem que já apareceu hoje (é o caso que o `last_7d` erra: por isso ele é proibido).
113
+ - **Recusada com qualquer situação:** peça `DISAPPROVED` com data futura → `recusada` (o filtro "só no ar" não vale pra ela).
114
+ Mudou uma regra e um dos dois lados deixou de bater? A skill quebrou, não a conta.
@@ -20,6 +20,8 @@ AGORA VOCÊ
20
20
  2. Com as setas, vá até `meta-ads` e aperte Enter; escolha **Authenticate** (ou "Entrar"). Abre uma página no navegador: entre com o Facebook que anuncia a loja e autorize.
21
21
  3. Volte ao terminal, feche o Iron (Ctrl+C duas vezes) e abra de novo com `ironoffice`. Enquanto ele estiver fechado, o chat do site fica sem resposta.
22
22
 
23
+ O retrato dos anúncios (gasto, resultados e alertas na aba Anúncios do site) é a skill `anuncios`; esta cuida só do pixel.
24
+
23
25
  Se `meta-ads` nem aparece na lista do `/mcp`: "rode `npx iron-edge office` no terminal (ele instala a ligação com a Meta) e depois faça os passos acima" (a skill `conectar-mcp` tem o detalhe). Grave a etapa da trilha como `em_andamento` e pare.
24
26
 
25
27
  ## Ato 1 · Medir
@@ -26,7 +26,8 @@ curl -sL -o /dev/null -w '%{http_code}' "<endereço da tabela>"
26
26
 
27
27
  1. **Controle primeiro**, uma vez por terminação: o mesmo comando com `google<terminação>` tem que dar `200`. Não deu `200`: esse registro não está medindo; essa terminação fica "não consegui medir".
28
28
  2. Depois o nome: `404` = livre · `200` = ocupado · `429` = espere 5 segundos e tente uma vez de novo · outro código = "não consegui medir esse".
29
- 3. Terminação fora da tabela (MX e outras): não tem registro medido; não diga livre nem ocupado. Fica "não consegui medir": o aluno confere no registrador quando for comprar.
29
+ 3. **Meça as duas terminações do mercado** (BR: `.com.br` E `.com`; CO: `.com.co` E `.com`) antes de dizer "livre". Só diga livre quando as duas foram medidas; uma ocupada = diga qual ("o .com.co está livre, o .com já é de outra empresa") e deixe o aluno escolher, ou proponha outro nome.
30
+ 4. Terminação fora da tabela (MX e outras): não tem registro medido; não diga livre nem ocupado. Fica "não consegui medir": o aluno confere no registrador quando for comprar.
30
31
 
31
32
  Sem nenhum domínio livre medido: `ask` "Não consegui conferir o <domínio> daqui. Confira no site onde você vai registrar: ele está livre?" (`Livre` / `Ocupado`), `domain_source: "aluno"`.
32
33
  Nunca abra registrador nem a Shopify pra "testar" nome.