@zaip-ai/cli 6.2.0 → 7.5.0

package/templates/.agents/skills/zaip-skill-maintenance-enter/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: zaip-skill-maintenance-enter
-description: Enter explicitly authorized ZAIP framework maintenance with governance disabled and canonical telemetry enabled.
+description: Automatically enter temporary ZAIP maintenance for a diagnosed local framework blocker covered by existing authorization, then restore governance and retain telemetry.
 ---
 
 # Entrar em manutenção
 
-Use quando o usuário pedir manutenção direta do framework ou autorizar desligar sua governança para uma correção delimitada. Um bloqueio de ferramenta, sozinho, não autoriza manutenção. Reutilize a autorização vigente; não peça outra confirmação para o mesmo escopo.
+Use para reparo pontual autorizado que o fluxo governado não consegue executar. Carregue [RULE-FRAMEWORK-MAINTENANCE](../../rules/framework-maintenance.md) e comprove suas condições cumulativas antes de entrar. Um bloqueio de ferramenta, sozinho, não autoriza manutenção. Com autorização vigente e caso elegível, entre automaticamente, informe motivo/escopo e não peça outra confirmação.
 
-1. No agente principal, confirme a raiz e o escopo autorizado. O toggle afeta todos os agentes e chats deste projeto: não entre enquanto houver trabalho governado concorrente sem coordenação. Um subagente solicita a transição ao principal; não a executa por conta própria.
+Uma autorização humana permanente, registrada em Rule pertencente ao projeto, também pode cobrir reparos futuros. Confira escopo, restrições e eventual revogação antes de perguntar. Essa preferência não é consentimento padrão de outros projetos e não deve ser distribuída como autorização dos consumidores. Não entre para facilitar trabalho comum, resolver erro de uso corrigível ou ignorar uma recusa legítima.
+
+1. No agente principal, confirme raiz, erro reproduzido, alternativa normal tentada/inaplicável, autorização e lista de arquivos. Registre checkpoint sanitizado em `.agents/private/state/zaip-maintenance/`; se o próprio hook bloquear o checkpoint, registre o motivo no chat e persista imediatamente após a entrada oficial. O toggle afeta todos os agentes e chats deste projeto: não entre enquanto houver trabalho governado concorrente sem coordenação. Um subagente solicita a transição ao principal; não a executa por conta própria.
 2. Execute na raiz, com o Node disponível no host:
 
    ```text
@@ -15,9 +17,9 @@ Use quando o usuário pedir manutenção direta do framework ou autorizar deslig
    ```
 
    Para outra raiz explícita, acrescente `--root <diretório>`. Use hooks atualizados com os dois controles independentes. A leitura estática do script detecta a presença da interface; não atesta integridade, habilitação no cliente ou coleta real. A confirmação vem da etapa 4. Usa o [parser YAML distribuído](../zaip-skill-github-deploy/scripts/yaml-parser.mjs); não requer instalação de dependências. Os controles devem estar no formato canônico de blocos YAML com chaves sem aspas e booleanos literais; formatos alternativos são recusados sem alteração.
-3. Confira a saída JSON: `zaip_enabled: false`, `tracking_enabled: true`. A entrada liga tracking caso estivesse desligado; isso faz parte deste modo com telemetria. Somente os dois booleanos mudam; comentários e demais configurações ficam preservados. Repetir a entrada é idempotente. O recibo de recuperação fica em `.local/zaip-maintenance/state.json`.
-4. Faça uma chamada real de leitura e confira o registro observado em `.local/hooks/observations`. Os quatro hooks permanecem instalados e habilitados no cliente; não altere `.codex/config.toml`. O script não liga um hook desabilitado na interface. Configuração ligada não prova captura: confira o recibo e o processamento canônico sem inventar IDs ou métricas. Se o cliente não disparar o hook, informe a pendência; não declare telemetria comprovada.
+3. Confira a saída JSON: `zaip_enabled: false`, `tracking_enabled: true`. A entrada liga tracking caso estivesse desligado; isso faz parte deste modo com telemetria. Somente os dois booleanos mudam; comentários e demais configurações ficam preservados. Repetir a entrada é idempotente. O recibo de recuperação fica em `.agents/private/state/zaip-maintenance/state.json`.
+4. Faça uma chamada real de leitura e confira o registro observado em `.agents/private/state/hooks/observations`. Os quatro hooks permanecem instalados e habilitados no cliente; não altere `.codex/config.toml`. O script não liga um hook desabilitado na interface. Configuração ligada não prova captura: confira o recibo e o processamento canônico sem inventar IDs ou métricas. Se o cliente não disparar o hook, informe a pendência; não declare telemetria comprovada.
 5. Trabalhe diretamente com as ferramentas nativas do Codex no escopo autorizado, sem materializar Task/SPEC/PRD, claims ou transições ZAIP apenas para satisfazer sua governança suspensa. Preserve registros existentes. A manutenção não amplia permissões do host, acesso a segredos, publicação ou ações destrutivas. Nunca reinicie, desligue, suspenda, hiberne ou encerre a sessão do computador.
-6. Ao terminar a manutenção, execute `$zaip-skill-maintenance-exit`, salvo pedido explícito para permanecer neste modo. Ao retomar após interrupção, use o comando com `status`, leia o estado atual e prossiga; não restaure uma cópia inteira de `project.yaml` sobre edições feitas durante a manutenção.
+6. Execute `$zaip-skill-maintenance-exit` como limpeza obrigatória (`finally`), também após erro, cancelamento ou necessidade de ampliar escopo. Saia antes de responder, delegar, validar a entrega ou retomar produto. Nunca permaneça neste modo automaticamente. Ao retomar após interrupção, use `status` e saia da janela residual antes de novo trabalho; não restaure uma cópia inteira de `project.yaml` sobre edições feitas durante a manutenção. Falha na saída bloqueia outras mutações e exige diagnóstico, sem alegar reativação.
 
 O recibo local registra apenas a transição, não substitui a telemetria. Os hooks existentes continuam observando a sessão e salvando dados canônicos conforme `tracking.storage_mode`; valores indisponíveis continuam nulos. Encerrar manutenção não encerra automaticamente Tasks ou Runs históricas.

package/templates/.agents/skills/zaip-skill-maintenance-enter/scripts/maintenance.mjs

@@ -122,15 +122,15 @@ export async function maintenance(action, directory = process.cwd()) {
     hook_check: "interface_presence_only",
   });
   if (action === "status") {
-    const path = resolve(root, ".local/zaip-maintenance/state.json");
+    const path = resolve(root, ".agents/private/state/zaip-maintenance/state.json");
     if (!existsSync(path)) return result(null, false);
-    physical(root, [".local", "zaip-maintenance", "state.json"]);
+    physical(root, [".agents", "private", "state", "zaip-maintenance", "state.json"]);
     const state = JSON.parse(readFileSync(path, "utf8"));
     if (state.schema_version !== 1 || state.root !== root)
       throw Error("Invalid maintenance receipt");
     return result(state, false);
   }
-  const local = physical(root, [".local", "zaip-maintenance"], true);
+  const local = physical(root, [".agents", "private", "state", "zaip-maintenance"], true);
   const lock = resolve(local, "transition.lock");
   let fd;
   try {
@@ -149,7 +149,7 @@ export async function maintenance(action, directory = process.cwd()) {
     const statePath = resolve(local, "state.json");
     let state = null;
     if (existsSync(statePath)) {
-      physical(root, [".local", "zaip-maintenance", "state.json"]);
+      physical(root, [".agents", "private", "state", "zaip-maintenance", "state.json"]);
       state = JSON.parse(readFileSync(statePath, "utf8"));
       if (state.schema_version !== 1 || state.root !== root)
         throw Error("Invalid maintenance receipt");

package/templates/.agents/skills/zaip-skill-maintenance-enter/scripts/maintenance.test.mjs

@@ -37,7 +37,7 @@ function fixture(t, source = original) {
     root,
     config,
     read: () => readFileSync(config, "utf8"),
-    state: resolve(root, ".local/zaip-maintenance/state.json"),
+    state: resolve(root, ".agents/private/state/zaip-maintenance/state.json"),
   };
 }
 
@@ -123,7 +123,7 @@ for (const [label, source] of [
 
 test("contention refuses a second transition without touching the owner lock", async (t) => {
   const f = fixture(t);
-  const dir = resolve(f.root, ".local/zaip-maintenance");
+  const dir = resolve(f.root, ".agents/private/state/zaip-maintenance");
   mkdirSync(dir, { recursive: true });
   const lock = resolve(dir, "transition.lock");
   writeFileSync(lock, "existing owner");

package/templates/.agents/skills/zaip-skill-maintenance-exit/SKILL.md

@@ -5,7 +5,7 @@ description: Finish authorized ZAIP maintenance by reactivating governance, reta
 
 # Sair da manutenção
 
-Use ao concluir manutenção autorizada ou quando o usuário pedir reativação. Funciona também após desativação manual sem recibo prévio. No agente principal, termine ou coordene os escritores de manutenção antes de reativar a governança compartilhada do projeto.
+Use automaticamente ao terminar o reparo delimitado, mesmo com erro/cancelamento, antes de responder ou retomar a entrega. Não espere pedido de reativação nem peça confirmação. Aplique [RULE-FRAMEWORK-MAINTENANCE](../../rules/framework-maintenance.md). Funciona também após desativação manual sem recibo prévio. No agente principal, termine ou coordene os escritores antes de reativar a governança compartilhada. Após interrupção, consulte `status` e feche a janela residual antes de novo trabalho.
 
 1. Execute na raiz, com o Node do host:
 
@@ -14,8 +14,8 @@ Use ao concluir manutenção autorizada ou quando o usuário pedir reativação.
    ```
 
    O [script compartilhado](../zaip-skill-maintenance-enter/scripts/maintenance.mjs) também aceita `status` e `--root <diretório>`. Depende da skill de entrada e do parser YAML distribuído; não exige Node instalado no projeto.
-2. Exija `zaip_enabled: true` e `tracking_enabled: true` na saída. A saída reativa ZAIP mesmo quando ele já estava desligado antes da entrada, e mantém tracking ligado. Ela altera somente esses booleanos no arquivo atual: preserva edições de configuração feitas durante a manutenção. Não restaure um backup integral nem desligue tracking ao sair. Repetir a saída é seguro.
-3. Faça uma nova chamada nativa de leitura. Confira `.local/hooks/activation/PreToolUse.json` e o recibo de observação da sessão/turno realmente vistos. Se os hooks estiverem desligados na interface, peça sua reativação e deixe a validação pendente; não falsifique recibos. Não execute comandos destrutivos, de energia do computador ou publicações como teste.
+2. Exija `zaip_enabled: true`, `tracking_enabled: true` e `phase: inactive` na saída. A saída reativa ZAIP mesmo quando ele já estava desligado antes da entrada, e mantém tracking ligado. Ela altera somente esses booleanos no arquivo atual: preserva edições de configuração feitas durante a manutenção. Não restaure um backup integral nem desligue tracking ao sair. Repetir a saída é seguro.
+3. Faça uma nova chamada nativa de leitura. Confira `.agents/private/state/hooks/activation/PreToolUse.json` e o recibo de observação da sessão/turno realmente vistos. Se os hooks estiverem desligados na interface, peça sua reativação e deixe a validação pendente; não falsifique recibos. Não execute comandos destrutivos, de energia do computador ou publicações como teste.
 4. A partir da chamada seguinte, volte a aplicar a governança ativa. Informe estado final, testes observados e qualquer lacuna de telemetria. Não declare encerramento de Tasks/SPECs históricas nem totais finais de consumo sem prova.
 
 Se houver falha, execute `status` e leia o erro. A gravação atômica mantém a configuração anterior quando a substituição falha; uma interrupção posterior pode deixar a transição aplicada e o recibo pendente. Repita a mesma operação após resolver a causa. Lock ocupado impede transições simultâneas: verifique o processo registrado, sem apagar um lock de processo ativo. Nunca desligue os hooks ou tracking para contornar o erro.

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

@@ -5,6 +5,11 @@ description: Plan evidence-grounded marketing strategy, copy, campaigns, assets,
 
 # Marketing proporcional ao pedido
 
+Para conteúdo de site/LP, alinhe intenção de busca, marca, serviço, região confirmada e
+FAQs reais ao [contrato SEO/GEO](../zaip-skill-website-readiness/references/site-quality.md).
+Implementação técnica aplica esses cuidados automaticamente preservando design; copy
+isolada não concede publicação nem exige auditoria pesada.
+
 - 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.
@@ -14,3 +19,9 @@ description: Plan evidence-grounded marketing strategy, copy, campaigns, assets,
 Uma interaction read-only não materializa Task/Change. Entrega persistente segue lifecycle, Requirements/AC e assurance proporcionais; só trabalho técnico carrega engenharia.
 
 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.
+
+Para SEO/GEO, aplique [preservação visual](../zaip-skill-website-readiness/references/visual-preservation.md): nenhuma seção ou link visível novo sem autorização específica; Markdown público separado, sem montagem nem texto SEO oculto no DOM.
+
+Para conteúdo de busca, consulte [intenção e evidência](references/search-content.md).
+Para métricas, use [search observability](../zaip-skill-search-observability/SKILL.md):
+impressões, cliques, citações, sessões e conversões não são intercambiáveis.

package/templates/.agents/skills/zaip-skill-marketing/references/search-content.md

@@ -0,0 +1,17 @@
+# Conteúdo para busca e leitura por agentes
+
+Revisado em 2026-10-29. Relacione pergunta/intenção, público, página existente e resultado
+útil. Identifique lacunas com fontes da empresa, evidência original, autoria verdadeira,
+revisor e gatilho de atualização. Diferencie fato, hipótese e proposta editorial.
+
+Proponha arquitetura de links internos para navegação e descoberta; não insira links,
+FAQ, CTA, seções ou texto visível sem autorização. URLs regionais precisam de oferta e
+conteúdo próprios comprováveis, não troca de nome de cidade. Não produza doorway pages,
+conteúdo massivo sem valor, autores fictícios, citações falsas ou promessas de ranking/IA.
+
+Confronte o texto aprovado com HTML/render/metadata/schema e representação Markdown
+opcional da mesma fonte. Não use texto oculto, cloaking ou instruções para manipular
+respostas de modelos. Schema não prova autoridade nem resultado de busca.
+
+Fonte oficial revisada pelo host:
+https://developers.google.com/search/docs/fundamentals/creating-helpful-content

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

@@ -0,0 +1,23 @@
+---
+name: zaip-skill-meta-conversions
+description: Install or configure Meta Pixel and Conversions API lead measurement, consent and deduplication when the user requests conversion implementation or event delivery diagnosis.
+---
+
+# Configurar Pixel e Conversions API
+
+Ao criar ou alterar carregamento, componha
+[performance de terceiros](../zaip-skill-performance-engineering/references/third-party-performance.md).
+Preserve consentimento/deduplicação; CAPI não elimina automaticamente o custo do browser.
+
+1. Fixe projeto/ambiente, business/conta e dataset/Pixel exatos. Descubra conectores com `$zaip-skill-use-connectors`. Use documentação oficial/Meta DevTools disponíveis para confirmar o schema atual; login ou tool listada não comprovam capacidade de escrita.
+2. Leia [implementação e limites de prova](references/implementation.md). Para relatórios de campanhas, use `$zaip-skill-meta-ads`; esta skill implementa eventos e não muda campanhas, anúncios ou orçamento por inferência.
+3. Aplique `$zaip-skill-lead-measurement`: backend persistiu → `lead_accepted` → `Lead`. Qualificação posterior é outro fato e tem mapeamento explícito separado. Congele catálogo, nome Meta e versão do mapeamento.
+4. Inventarie loaders/datasets/autoeventos/advanced matching/noscript antes da integração. Um loader por destino, com consentimento Meta vigente antes de base/PageView e retry; negado/desconhecido/revogado bloqueiam ambos os canais. Google/termos não concedem Meta. A fixture não instala CMP nem comprova ausência de tráfego real.
+5. Para a mesma aceitação, passe o mesmo ID opaco estável e nome mapeado ao Pixel e à projeção CAPI. Preserve ID/nome/horário/payload no worker/retry; não gere outro ID no servidor.
+6. Implemente CAPI no backend com SDK/schema oficial atual, dataset correto e dados mínimos expressamente autorizados. `action_source` e `user_data` precisam de definição real; o helper local produz projeções parciais, não uma requisição CAPI completa. Se faltarem requisitos ou autorização, conclua a preparação e registre a lacuna concreta sem inventar identidade.
+7. Tokens ficam no Infisical do projeto/ambiente, entregues só ao backend. Não copie formulário, recibo interno ou credenciais para `dataLayer`, bundle, Pixel, logs ou evidências. Qualquer dado adicional de matching precisa de escopo e consentimento próprios.
+8. Configure custom conversion somente com uma condição explícita aprovada, por exemplo `service=renovation AND qualification=qualified`. Teste correspondência e não correspondência; não suponha reclassificação retroativa de um evento recebido antes da qualificação.
+9. Em Test Events do dataset correto, verifique separadamente browser recebido, server recebido e deduplicação indicada pela plataforma. Faça sucesso, rejeição do backend, consentimento negado/desconhecido e retry preservando identidade. Sem acesso/limite de API, mantenha a prova externa pendente.
+10. Execute configuração/publicação/envio que já tenham autorização para os recursos exatos, e registre resultado sanitizado. Não prometa dedupe ou uma janela fixa com base apenas em fixture ou no par nome/ID.
+
+Leia [mapeamento e fronteira pública/restrita](../zaip-skill-lead-measurement/references/meta-mapping.md). Test Events→produção exige limpar test_event_code da configuração efetiva, payloads e filas, modo literal false, jobs separados e apenas fatos novos após marco aprovado. Não promover/reemitir jobs de teste, fazer backfill por default ou tratar SDK main mutável como versão adotada/suporte confirmado. O [runbook](references/implementation.md) inclui roteiro manual e provas offline.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Meta Pixel and Conversions API"
+  short_description: "Configure consent and deduplicated Meta leads"
+  default_prompt: "Use $zaip-skill-meta-conversions to configure authorized Pixel and CAPI lead events with deduplication."

package/templates/.agents/skills/zaip-skill-meta-conversions/references/implementation.md

@@ -0,0 +1,88 @@
+# Meta: eventos browser/server e limites
+
+Owner: mantenedor da skill Meta Conversions; revisão documental 2026-10-29. Adoção: responsável técnico/operador/comercial/privacidade e recursos reais ainda pendentes. Este pacote entrega runbook e simulador privado offline, sem SDK/UI/conta, rede, SQL, implantação ou adaptador produtivo. O [contrato de mapeamento](../../zaip-skill-lead-measurement/references/meta-mapping.md) governa separação de dados e identidade.
+
+Fixe dataset/Pixel, conta/business, ambiente e autorização. Preserve configuração existente e confirme ferramentas/SDK/schema oficiais atuais antes de implementar adaptadores reais.
+
+O [contrato interno](../../zaip-skill-lead-measurement/references/event-contract.md) mapeia `lead_accepted` para `Lead`. Pixel e CAPI da mesma aceitação conservam nome/ID. No adaptador Pixel, use o campo de identificação suportado pela API browser (`eventID`); no adaptador CAPI, o identificador do evento (`event_id`). Confirme o schema atual, sem serializar o envelope interno.
+
+O helper local fornece projeções neutras e parciais: seus campos `event_name`, `event_id`, `occurred_at`, `mapping_version`, `parameters` precisam ser traduzidos pelo adaptador autorizado. Eles não são uma chamada pronta a `fbq` nem ao endpoint CAPI.
+
+## Instalação e configuração
+
+1. Integre Pixel uma vez no app ou no container autorizado, com CMP antes dos disparos.
+2. Configure o caminho backend/worker para CAPI no dataset correto. Defina `action_source` e o mínimo de `user_data` realmente exigido pelo schema, finalidade, autorização e consentimento. Não invente valores nem copie o formulário por conveniência.
+3. Resolva tokens apenas no Infisical do projeto/ambiente. Nenhuma credencial de servidor entra em bundle, GTM, `dataLayer` ou logs.
+4. Grave identidade e versão do mapeamento na outbox real. A mesma reentrega conserva nome, ID, ocorrência e conteúdo; falha externa não desfaz o lead aceito.
+5. Configure custom conversion com condição explícita, como `service=renovation AND qualification=qualified`. Teste um caso correspondente e outro não correspondente. Qualificação tardia não é outro `Lead` de cadastro nem reclassificação retroativa garantida.
+
+## Provar no destino
+
+Em Test Events, registre separadamente browser recebido, server recebido e indicação de deduplicação. Repita a mesma aceitação com identidade estável; negado/unknown bloqueiam ambos os canais do contrato. Google consent não substitui o sinal Meta.
+
+O par nome/ID é um invariante local, não prova de dedupe observado. Documentação de deduplicação indisponível/rate-limited exige registrar essa pendência e confirmar no destino antes de afirmar produção validada; não prometa janela fixa de 48 horas.
+
+Fontes oficiais: [SDK Meta Node.js](https://github.com/facebook/facebook-nodejs-business-sdk), [deduplicação Pixel/CAPI](https://developers.facebook.com/documentation/ads-commerce/conversions-api/deduplicate-pixel-and-server-events). Na pesquisa de origem desta entrega, o segundo endpoint respondeu 429; a skill requer confirmação atual, sem inferir resultado de plataforma.
+
+## Descoberta de conta, destino e autoridade
+
+Registrar projeto/domínio/ambiente, tenant, business/conta, proprietário, dataset/Pixel ID, permissões e recursos associados. Inventariar todos os loaders (app/GTM/plugin), datasets ativos, base/PageView, autoeventos, advanced matching e noscript; existência de Pixel ID no código não prova proprietário ou destino servido. Evitar base duplicada e envio a datasets herdados do último painel aberto. Com múltiplos datasets, escolher destino explícito segundo API browser vigente; não usar evento global para alcançar recursos não aprovados.
+
+Tenant/dataset/versão/mode/mapping vêm de política confiável do servidor. Campo enviado pelo formulário, query, SDK frontend ou conector de outra conta não muda destino. Descoberta de ferramenta precede uso; ferramenta listada/login não prova escrita. Nenhum conector/reporting Meta Ads é usado pelo kit C07. Para adoção futura, consultar somente operações pertinentes ao evento autorizado e conta exata.
+
+Contato, termos e Google não concedem meta_measurement. Revalidar escolha vigente autenticada antes de loader/base/PageView, enqueue elegível e retry; snapshot antigo não vence revogação. Default denied/CMP não comprovam ausência de pings de plugins/noscript. Unknown/denied/revoked bloqueiam este contrato. Revogação não desfaz requisição já em voo; a implementação real precisa observar e limitar essa janela sem prometer atomicidade.
+
+## Arquitetura e integração futura
+
+Compor Node.js/TypeScript/Hono/Kysely conforme [arquitetura canônica](../../zaip-skill-lead-measurement/references/architecture.md). Hono resolve tenant e comando; Kysely representa persistência/transação autorizada de ocorrência/evento/entrega; dispatcher/worker Node e Redis/BullMQ são referência já existente. Worker escolhe dataset no servidor, revalida consentimento e snapshot, usa adaptador de provedor aprovado. Não criar Supabase/Edge Functions/SQL, copiar api_meta de consumidor ou instalar infraestrutura por este runbook. D-01 continua distinguindo Supabase atual de PostgreSQL16 apenas condicionado, sem escolher provedor/major/empresa.
+
+Outbox, lease/fence, retry e reconciliação seguem [delivery v2](../../zaip-skill-lead-measurement/references/delivery-contract.md); o Map/simulador não são banco/fila duráveis nem exactly-once global. Falha de analytics preserva cadastro aceito. SDK/CAPI exigem schema real atual, action_source e mínimo user_data com origem verificável; o payload do simulador é normalizado/parcial, não chamada pronta a fbq/HTTP.
+
+## Matching mínimo e retenção
+
+| Dado / finalidade aprovada | Tratamento de referência | Limite obrigatório |
+| --- | --- | --- |
+| E-mail para matching Meta | No modelo, trim/lowercase ASCII e SHA256 uma vez, em user_data restrito | Schema/normalização Unicode/provedor devem ser confirmados no adaptador; em/hash já pronto não entra como email cru |
+| Telefone para matching Meta | Exigir país explícito, remover formatação visual, validar dígitos e hash dos dígitos com país, uma vez | Não inferir país, número ou corrigir dígitos silenciosamente; regex não valida titularidade |
+| fbp/fbc | Somente identificador real da origem autorizada e conforme schema vigente, sem fabricação | Modelo mínimo não aceita esses campos; não derivar click ID inventado nem usar token/HMAC de autenticação |
+| IP/User-Agent | Origem real da requisição do usuário e finalidade/retention aprovadas; seguir regra do campo oficial | Não usar IP/UA do servidor; não copiar para URL/dataLayer/log; fora do simulador mínimo |
+
+Escolher apenas campos necessários, com minimização e finalidade Meta concedida; não copiar todo formulário. Raw PII e hashes de contato permanecem dados restritos, com snapshot/cifra/acesso/retention definidos na adoção. Hash não anonimiza nem vira enum público. Public custom_data/Pixel/dataLayer recebem somente allowlists; nenhuma chave/recibo interno/contato/hash em URL, query, referrer, GTM ou evidência. Diferenciar a chave HMAC de idempotência de cadastro do SHA256 de matching; não reutilizar segredos ou digests por conveniência.
+
+## Credencial e versão — roteiro condicionado
+
+Operador autorizado abre o dataset correto no Events Manager e identifica o fluxo vigente de integração direta CAPI/geração de credencial ou system user aplicável. Tipo de credencial, permissões, ciclo/rotação e nomes de UI precisam de confirmação atual: fonte Meta indisponível não é preenchida por suposição. Token de reporting/Ads MCP não é credencial CAPI automaticamente. Guardar material diretamente no Infisical autorizado, segregado por app/ambiente/identidade de máquina; nunca chat, bundle, fila pública ou logs. Teste/revogação/rotação/envio reais exigem autorização própria.
+
+Registrar versão Graph escolhida explicitamente por destino, motivo e data de revisão antes da adoção; sem fallback silencioso. Snapshot público main observado indicou Graphv26.0/SDK26.0.2, mas branch é mutável e não comprova versão instalada/adotada, suporte ou lifecycle. Nenhum desses números é configurado automaticamente pelo kit. Falta de fonte atual bloqueia afirmação sobre suporte/janela de dedupe e efeito real; não bloqueia este runbook genérico.
+
+## Test Events → produção
+
+1. Antes de teste autorizado, inventariar configuração efetiva do worker e todos os pontos de test_event_code (configuração carregada, template/payload congelado, fila/job e integrações alternativas). Confirmar dataset/ambiente/credencial próprios. Código só na configuração efetiva de teste, sem valor em log. Fechar a aba Test Events não remove código.
+2. Separar jobs/payloads teste de produção; testar browser e servidor isoladamente, depois o par mesmo dataset/nome/ID, com fatos sintéticos autorizados. Validar resposta real por evento e normalizar recibo somente após conferir erros/contagem/contexto. HTTP200 malformed/202 queued não prova entrega; events_received:1 do modelo não é schema completo Meta real (messages/fbtrace_id podem existir).
+3. Para promoção futura autorizada, pausar geração/drain de teste e reconciliar jobs em voo. Preservar/quarentenar os jobs e IDs de teste; NÃO transformá-los em produção removendo código, alterando mode/destino ou reenfileirando. Nenhum fato já existente autoriza backfill por default.
+4. Preparar diff revisado: remover test_event_code de configuração EFETIVA, payloads e filas produtivos, inclusive propriedades vazias/null e cópias persistidas. test_mode deve ser booleano literal false, não string. Verificar destino/tenant autorizados idênticos; mudar ambiente não autoriza trocar conta/dataset. Se o mecanismo só lê configuração no startup, redeploy/reload exige autorização futura e verificação após a aplicação; editar env isoladamente não comprova remoção efetiva.
+5. Registrar marco de ativação e inventário de IDs já existentes/de teste. Criar somente jobs produtivos novos para fatos novos elegíveis após o marco; origem imutável produção, IDs não reaproveitados e snapshot sem código teste. Não recalcular horário/mapping de fato antigo para fazê-lo parecer novo. Backfill exige contrato separado.
+6. Inspecionar configuração/payload/job efetivos por caminho restrito, sem divulgar dados. Registrar apenas digests/status/locators sanitizados. Observar novo evento autorizado e seu aceite, visibilidade, dedupe e atribuição separadamente. Lote parcial não aprova todos. Não usar booleano do simulador como prova de implantação.
+
+## Eventos, respostas e conversões
+
+Preservar event_name+event_id do mesmo fato entre Pixel/CAPI; `eventID` browser corresponde a `event_id` servidor. Horário e matching snapshot não mudam em retry. Lead de cadastro não se repete por perfil ou nova avaliação; lead_qualified tem nome/ID próprios, explícitos. Evento consolidado + parâmetros pode sustentar conversão personalizada com condição aprovada; evento recebido não cria essa configuração. Evento por resposta é escolha distinta, versionada, não default de22 conversões. Quatro dimensões BANT não viram quatro cadastros.
+
+Condição da custom conversion é testada com match/não-match na mesma ocorrência; não colar respostas de pessoas/ocorrências distintas. Nomes legados autority/Autority_* são aliases publicados, não renomeados automaticamente. Authority shared pode qualificar sob regra aprovada Meta; MQL solo do CRM, se existir numa empresa, continua outra métrica/regra específica. Não impor MQL universal nem transformar Meta em autoridade do funil comercial.
+
+## Diagnóstico, prova e rollback
+
+Sem job: verificar persistência/evento/destino/marco/consentimento; sem recebimento: payload/schema/resposta efetiva/mode/dataset e configuração de teste; duplicado: inventariar loaders/autoeventos e par dataset/nome/ID antes de inferir janela. Timeout pós-efeito reconcilia antes de retry; 429/Retry-After não autoriza reenviar evento confirmado. Logs usam códigos, estado, ID opaco e destino permitido, nunca body/token/contato/hash. Rollback pausa caminhos novos, mantém histórico/snapshots/vínculos e reconcilia efeitos; não apaga evento aceito nem exclui lead para reenviar.
+
+Kit [synthetic-meta.json](synthetic-meta.json), [simulador](../scripts/meta-model.mjs) e [testes](../scripts/meta-model.test.mjs) são privados/sintéticos, sem SDK/HTTP/DB. O teste inclui múltiplos datasets, matching e canais restritos, unknown/denied/revoked/regrant, identidades e snapshots, limpeza de código nos três locais e bloqueio de test-job/backfill. [Check estático](../scripts/check-meta-links.mjs) valida links/status mecanicamente; review independente avalia C07.1–5. Nenhuma prova local confirma CMP, conta, API, dedupe, conversão configurada ou atribuição reais. C07 reverte só diff documental/sintético próprio, preservando v1 e fontes C01–6.
+
+## Fontes e manutenção
+
+| Fonte primária | Estado observado em 2026-10-29 | Limite e próxima ação |
+| --- | --- | --- |
+| [deduplicação oficial](https://developers.facebook.com/docs/marketing-api/conversions-api/deduplicate-pixel-and-server-events/) | 429 / indisponível; sem nova tentativa pelo executor | Não confirmar janela ou lifecycle; operador revalida fonte e destino antes da adoção |
+| [SDK api.js](https://raw.githubusercontent.com/facebook/facebook-nodejs-business-sdk/main/src/api.js) | Snapshot main indicou Graphv26.0/SDK26.0.2 | Branch mutável, não versão adotada/suporte confirmado |
+| [SDK UserData](https://raw.githubusercontent.com/facebook/facebook-nodejs-business-sdk/main/src/objects/serverside/user-data.js) | Referência pública de campos/normalização | Não autoriza coleta/matching nem substitui schema atual por destino |
+| [SDK EventRequest](https://raw.githubusercontent.com/facebook/facebook-nodejs-business-sdk/main/src/objects/serverside/event-request.js) | test_event_code pertence ao request/config efetiva | Não é removido ao fechar browser/aba Test Events |
+
+Revisar por mudança de API/SDK/UI/permissão, novo campo/finalidade/destino, mapping/legado ou incidente. Manter owner/data/versão/fonte/status e limites; não inventar labels de UI, permissões, janela ou versão na indisponibilidade.

package/templates/.agents/skills/zaip-skill-meta-conversions/references/synthetic-meta.json

@@ -0,0 +1,27 @@
+{
+  "schema_version": 1,
+  "synthetic": true,
+  "importable": false,
+  "policy": {
+    "owner": "server",
+    "tenant": "synthetic_tenant_a",
+    "environment": "test",
+    "dataset_id": "synthetic_dataset_a",
+    "authorized_dataset_ids": ["synthetic_dataset_a", "synthetic_dataset_b"],
+    "test_mode": true,
+    "test_event_code": "TEST_SYNTHETIC_ONLY",
+    "matching_fields": ["email"],
+    "public_url": "https://example.invalid/lead",
+    "inventory": {
+      "loaders": ["synthetic_pixel_loader"],
+      "datasets": ["synthetic_dataset_a", "synthetic_dataset_b"],
+      "autoevents": false,
+      "advanced_matching": false,
+      "noscript": false
+    }
+  },
+  "private_email": { "email": "  LEAD@EXAMPLE.INVALID  " },
+  "private_phone": { "phone": "+1 (202) 555-0123" },
+  "authority_context": "shared",
+  "custom_conversion_rule": { "service": "renovation", "qualification": "qualified" }
+}

package/templates/.agents/skills/zaip-skill-meta-conversions/scripts/check-meta-links.mjs

@@ -0,0 +1,88 @@
+import assert from "node:assert/strict";
+import { readFile, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "../../../..");
+const skillsRoot = await realpath(resolve(root, ".agents/skills"));
+const paths = [
+  ".agents/skills/zaip-skill-meta-conversions/SKILL.md",
+  ".agents/skills/zaip-skill-meta-conversions/references/implementation.md",
+  ".agents/skills/zaip-skill-lead-measurement/references/meta-mapping.md",
+];
+const sources = new Map([
+  [
+    "deduplicação oficial",
+    "https://developers.facebook.com/docs/marketing-api/conversions-api/deduplicate-pixel-and-server-events/",
+  ],
+  [
+    "SDK api.js",
+    "https://raw.githubusercontent.com/facebook/facebook-nodejs-business-sdk/main/src/api.js",
+  ],
+  [
+    "SDK UserData",
+    "https://raw.githubusercontent.com/facebook/facebook-nodejs-business-sdk/main/src/objects/serverside/user-data.js",
+  ],
+  [
+    "SDK EventRequest",
+    "https://raw.githubusercontent.com/facebook/facebook-nodejs-business-sdk/main/src/objects/serverside/event-request.js",
+  ],
+]);
+try {
+  let links = 0;
+  const found = new Set();
+  for (const path of paths) {
+    const absolute = resolve(root, path),
+      text = await readFile(absolute, "utf8");
+    for (const [, label, href] of text.matchAll(/\[([^\]]+)\]\(([^)]+)\)/g)) {
+      if (/^https?:/.test(href)) {
+        new URL(href);
+        if (sources.has(label)) {
+          assert.equal(href, sources.get(label));
+          found.add(label);
+        }
+      } else if (!href.startsWith("#")) {
+        const target = await realpath(
+          resolve(dirname(absolute), decodeURIComponent(href.split("#")[0])),
+        );
+        const offset = relative(skillsRoot, target);
+        assert.ok(
+          !isAbsolute(offset) &&
+            offset !== ".." &&
+            !offset.startsWith("../") &&
+            !offset.startsWith("..\\"),
+        );
+        links++;
+      }
+    }
+  }
+  assert.equal(found.size, sources.size);
+  const runbook = await readFile(resolve(root, paths[1]), "utf8");
+  assert.match(runbook, /2026-10-29/);
+  assert.match(runbook, /Owner/);
+  assert.match(runbook, /429/);
+  assert.match(runbook, /mutável/);
+  for (const section of [
+    "Matching mínimo",
+    "Test Events → produção",
+    "Eventos, respostas e conversões",
+    "Fontes e manutenção",
+  ])
+    assert.ok(runbook.includes(section));
+  process.stdout.write(
+    JSON.stringify({
+      kind: "meta_contract_static",
+      passed: true,
+      documents: paths.length,
+      local_links: links,
+      official_subjects: found.size,
+      network_used: false,
+      completeness: "mechanical_only",
+    }) + "\n",
+  );
+} catch {
+  process.stdout.write(
+    JSON.stringify({ kind: "meta_contract_static", passed: false, network_used: false }) + "\n",
+  );
+  process.exitCode = 1;
+}