izanagi-ai 3.21.0 → 3.22.0

package/.claude/skills/conversion-copywriting/SKILL.md

@@ -3,64 +3,64 @@ name: conversion-copywriting
 description: "Copywriting persuasivo e específico para headline, CTA e microcopy: benefício mensurável, prova concreta, verbo de ação, sem clichê de IA. Use ao escrever qualquer texto voltado a conversão (landing, pricing, onboarding, email transacional)."
 ---
 
-# Skill Conversion Copywriting — Izanagi
-
-## Identidade
-
-`anti-ai-slop` diz o que NÃO escrever (clichê genérico). Esta skill ensina o que escrever no lugar: copy que converte porque é específica, concreta e resolve a objeção real do leitor no momento em que ela aparece.
-
-## O Teste da Especificidade
-
-Toda frase de copy passa por uma pergunta: **"essa frase poderia estar em qualquer produto do mundo, ou só faz sentido no meu?"** Se serve pra qualquer produto, é slop.
-
-| Genérico (falha o teste) | Específico (passa o teste) |
-|---|---|
-| "A melhor forma de gerenciar sua equipe" | "Corte 4h/semana de status meeting: cada tarefa atualiza sozinha quando o PR fecha" |
-| "Rápido e confiável" | "P95 de 80ms, 99.95% uptime nos últimos 12 meses (status.exemplo.com)" |
-| "Simplifique seu fluxo de trabalho" | "De 6 ferramentas pra 1: substitui planilha de horas, Slack de aprovação e e-mail de nota fiscal" |
-| "Junte-se a milhares de usuários satisfeitos" | "2.340 times ativos, NPS 71" (ou não usar prova social até ter o número real) |
-
-## Estrutura de Headline (acima da dobra)
-
-1. **Benefício mensurável primeiro**, mecanismo depois: `[resultado com número] + [como]`. Ex: "Reduza custo de API em 63% com cache de resposta" — não "Otimize sua infraestrutura de IA."
-2. **Uma promessa por headline.** Empilhar 3 benefícios na mesma frase dilui todos.
-3. **Verbo de ação concreto**, nunca abstrato: "Corte", "Gere", "Rastreie", "Elimine" — não "Otimize", "Eleve", "Transforme", "Desbloqueie" (tells do catálogo `anti-ai-slop`).
-
-## CTA (Call to Action)
-
-- CTA descreve o que acontece ao clicar, não um comando vago: "Ver preço por time" > "Começar agora"; "Testar com meus dados" > "Saiba mais".
-- Reduza fricção percebida no microcopy abaixo do botão quando o pedido é sensível: "sem cartão de crédito", "cancele quando quiser", "2 minutos de setup" — só se for verdade.
-- Um CTA primário por seção. CTA secundário (se existir) é visualmente subordinado, nunca do mesmo peso.
-
-## Objeção-Resposta (para seções de pricing/FAQ/comparação)
-
-Toda seção de conversão deve responder objeções reais do comprador, não listar features:
-1. Levante a objeção mais provável daquele ponto do funil ("é caro pra time pequeno?", "dá pra migrar sem perder dados?", "e se eu já uso X?").
-2. Responda com fato verificável (número, garantia, comparação direta), não com reafirmação vaga da promessa.
-3. Uma objeção por bloco — não misture 3 respostas num parágrafo só.
-
-## Microcopy (formulários, erros, estados vazios)
-
-- Erro de formulário diz o que corrigir, não que "algo deu errado": "E-mail já cadastrado. Entrar em vez de criar conta?" > "Erro de validação."
-- Estado vazio orienta a próxima ação, não descreve a ausência: "Crie seu primeiro projeto para ver métricas aqui" > "Nenhum dado encontrado."
-- Confirmação de ação irreversível nomeia a consequência real: "Isso cancela a assinatura no fim do ciclo atual (14/03)" > "Tem certeza?"
-
-## Checklist Antes de Entregar
-
-- [ ] Nenhuma frase passa no "serve pra qualquer produto" (o teste da especificidade)
-- [ ] Toda métrica/prova social citada é real ou está marcada como placeholder explícito para o cliente preencher (nunca inventada)
-- [ ] Zero verbo abstrato de catálogo `anti-ai-slop` (Elevate, Unlock, Transform, Empower, Seamless, Cutting-edge...)
-- [ ] CTA descreve a ação real, não um comando genérico
-- [ ] Cada seção de objeção responde UMA pergunta real do comprador
-
-## Skills Relacionadas
-
-- `anti-ai-slop` — catálogo do que evitar (esta skill é o complemento positivo: o que escrever)
-- `ux-reviewer` — heurísticas de usabilidade do fluxo onde a copy vive
-- `design-directions` — tom de voz faz parte da direção de design escolhida
-
-## References
-
+# Skill Conversion Copywriting — Izanagi
+
+## Identidade
+
+`anti-ai-slop` diz o que NÃO escrever (clichê genérico). Esta skill ensina o que escrever no lugar: copy que converte porque é específica, concreta e resolve a objeção real do leitor no momento em que ela aparece.
+
+## O Teste da Especificidade
+
+Toda frase de copy passa por uma pergunta: **"essa frase poderia estar em qualquer produto do mundo, ou só faz sentido no meu?"** Se serve pra qualquer produto, é slop.
+
+| Genérico (falha o teste) | Específico (passa o teste) |
+|---|---|
+| "A melhor forma de gerenciar sua equipe" | "Corte 4h/semana de status meeting: cada tarefa atualiza sozinha quando o PR fecha" |
+| "Rápido e confiável" | "P95 de 80ms, 99.95% uptime nos últimos 12 meses (status.exemplo.com)" |
+| "Simplifique seu fluxo de trabalho" | "De 6 ferramentas pra 1: substitui planilha de horas, Slack de aprovação e e-mail de nota fiscal" |
+| "Junte-se a milhares de usuários satisfeitos" | "2.340 times ativos, NPS 71" (ou não usar prova social até ter o número real) |
+
+## Estrutura de Headline (acima da dobra)
+
+1. **Benefício mensurável primeiro**, mecanismo depois: `[resultado com número] + [como]`. Ex: "Reduza custo de API em 63% com cache de resposta" — não "Otimize sua infraestrutura de IA."
+2. **Uma promessa por headline.** Empilhar 3 benefícios na mesma frase dilui todos.
+3. **Verbo de ação concreto**, nunca abstrato: "Corte", "Gere", "Rastreie", "Elimine" — não "Otimize", "Eleve", "Transforme", "Desbloqueie" (tells do catálogo `anti-ai-slop`).
+
+## CTA (Call to Action)
+
+- CTA descreve o que acontece ao clicar, não um comando vago: "Ver preço por time" > "Começar agora"; "Testar com meus dados" > "Saiba mais".
+- Reduza fricção percebida no microcopy abaixo do botão quando o pedido é sensível: "sem cartão de crédito", "cancele quando quiser", "2 minutos de setup" — só se for verdade.
+- Um CTA primário por seção. CTA secundário (se existir) é visualmente subordinado, nunca do mesmo peso.
+
+## Objeção-Resposta (para seções de pricing/FAQ/comparação)
+
+Toda seção de conversão deve responder objeções reais do comprador, não listar features:
+1. Levante a objeção mais provável daquele ponto do funil ("é caro pra time pequeno?", "dá pra migrar sem perder dados?", "e se eu já uso X?").
+2. Responda com fato verificável (número, garantia, comparação direta), não com reafirmação vaga da promessa.
+3. Uma objeção por bloco — não misture 3 respostas num parágrafo só.
+
+## Microcopy (formulários, erros, estados vazios)
+
+- Erro de formulário diz o que corrigir, não que "algo deu errado": "E-mail já cadastrado. Entrar em vez de criar conta?" > "Erro de validação."
+- Estado vazio orienta a próxima ação, não descreve a ausência: "Crie seu primeiro projeto para ver métricas aqui" > "Nenhum dado encontrado."
+- Confirmação de ação irreversível nomeia a consequência real: "Isso cancela a assinatura no fim do ciclo atual (14/03)" > "Tem certeza?"
+
+## Checklist Antes de Entregar
+
+- [ ] Nenhuma frase passa no "serve pra qualquer produto" (o teste da especificidade)
+- [ ] Toda métrica/prova social citada é real ou está marcada como placeholder explícito para o cliente preencher (nunca inventada)
+- [ ] Zero verbo abstrato de catálogo `anti-ai-slop` (Elevate, Unlock, Transform, Empower, Seamless, Cutting-edge...)
+- [ ] CTA descreve a ação real, não um comando genérico
+- [ ] Cada seção de objeção responde UMA pergunta real do comprador
+
+## Skills Relacionadas
+
+- `anti-ai-slop` — catálogo do que evitar (esta skill é o complemento positivo: o que escrever)
+- `ux-reviewer` — heurísticas de usabilidade do fluxo onde a copy vive
+- `design-directions` — tom de voz faz parte da direção de design escolhida
+
+## References
+
 Veja `references.md` nesta pasta.
 
 > Gerado pelo Izanagi AI: cópia fiel de `skills/conversion-copywriting/SKILL.md` (fonte da verdade).

package/.claude/skills/economia-tokens/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: economia-tokens
-description: "Engenharia de contexto para reduzir consumo de tokens sem perder profundidade: leitura direcionada (grep-first), cache de prompt, higiene de contexto e edição em diff. Use sempre, em toda tarefa, por padrão."
+description: "Engenharia de contexto para reduzir consumo de tokens sem perder profundidade: leitura direcionada (grep-first), cache de prompt, higiene de contexto e edição em diff, incluindo silenciamento de ferramentas (quiet flags), geração orientada a diff e higiene de observação (resumir outputs longos antes de reportar). Use sempre, em toda tarefa, por padrão."
 ---
 
 # Context Engineering — Economia de Tokens (v2)
@@ -13,6 +13,22 @@ Manual operacional denso de **Engenharia de Contexto** para agentes de código.
 
 ---
 
+## Fluxo Zero-Waste de Execução (Passo a Passo)
+
+Diretrizes transversais de execução que valem para toda sessão; os pilares abaixo detalham cada uma.
+
+### Silencie ferramentas por padrão
+
+Comandos cuja saída bruta você não precisa ler integralmente devem rodar com flags quiet: `--quiet`/`--silent`/`-s` quando existirem, `pytest -q --tb=short`, `npm test --silent`, `cargo build 2>&1 | tail -n 20`, `git log -n 5 --oneline`. Saída ruidosa é contexto desperdiçado: filtre na origem em vez de limpar depois. Exceção consciente: debug real, onde o stack trace completo é necessário (Pilar 6).
+
+### Gere código orientado a DIFF
+
+Proibido reescrever um arquivo inteiro para mudança pontual: use edição cirúrgica/unified diff (replace pontual; multi-replace para vários trechos não-adjacentes). Rewrite integral só quando a maioria do arquivo muda de verdade (matriz completa no Pilar 4). Nunca cole o arquivo inteiro de volta "para mostrar o resultado": mostre só o trecho alterado.
+
+### Higiene de observação antes de reportar
+
+Output longo de ferramenta (build, testes, diff) deve ser RESUMIDO antes de entrar no relatório ou no contexto: grep da falha, `--stat`, `| tail`. Reporte o que importa (erro, arquivo, linha), nunca o dump integral. O mesmo vale ao encerrar a sessão: resumo curto, não histórico completo (Pilares 3 e 5).
+
 ## Pilar 1 — Protocolo de Leitura de Arquivos
 
 A leitura de arquivos é o maior consumidor silencioso de tokens. Um arquivo de 500 linhas = ~2.000 tokens. Ler 10 arquivos inteiros por tarefa = ~20.000 tokens desperdiçados quando 3.000 bastariam.
@@ -195,6 +211,8 @@ Comandos de terminal geram saída massiva que polui o contexto (builds, logs, te
 | `git log` completo | 5.000-50.000 tokens | `git log -n 5 --oneline` | ~100-200 tokens |
 | `find . -type f` em projeto | 2.000-20.000 tokens | `find . -type f -name "*.ts" --not -path "*/node_modules/*"` | ~200-500 tokens |
 | Testes falhando (output longo) | 2.000-10.000 tokens | Ler só a seção de falha (grep "FAIL") | ~200-500 tokens |
+| Suíte pytest verbosa | 1.000-8.000 tokens | `pytest -q --tb=short` | ~100-400 tokens |
+| `cargo build`/`cargo test` com warnings | 1.000-10.000 tokens | `2>&1 \| tail -n 20` | ~200-500 tokens |
 | `ls -R` recursivo | 1.000-50.000 tokens | `list_dir` do diretório específico | ~100-300 tokens |
 
 ### Regras rígidas
@@ -243,8 +261,9 @@ Use este checklist mental antes de cada ação na sessão:
 
 - [ ] **Vou ler um arquivo?** → Grep resolve? Se sim, grep. Se não, range mínimo.
 - [ ] **Já li esse arquivo nesta sessão?** → Não releia. Já está no contexto.
-- [ ] **Vou rodar um comando?** → Tem filtro de saída? (--stat, | head, -n 5)
+- [ ] **Vou rodar um comando?** → Tem flag quiet ou filtro de saída? (--quiet/-s, pytest -q --tb=short, --stat, | head)
 - [ ] **Vou editar código?** → Edição pontual (diff) ou preciso reescrever tudo?
+- [ ] **Output longo para reportar?** → Resumo antes (grep da falha, --stat, | tail); nunca colo o dump integral.
 - [ ] **Vou responder ao usuário?** → Sem narração? Sem repetir o pedido? Bullets curtos?
 - [ ] **Sessão está longa (>20 turnos)?** → Hora de compactar. Re-injetar objetivo.
 - [ ] **Vou criar sub-agente?** → Contexto mínimo para a sub-tarefa. Não replique a sessão.

package/.claude/skills/editorial-layout/SKILL.md

@@ -3,85 +3,85 @@ name: editorial-layout
 description: "Layout editorial/revista para web: grid quebrado com propósito, tipografia com peso assimétrico, espaço em branco estrutural, composição não-card. Use para fugir do 'hero + 3 cards' e dar identidade visual a landing pages, portfólios e sites de conteúdo."
 ---
 
-# Skill Editorial Layout — Izanagi
-
-## Identidade
-
-Você projeta layout como um diretor de arte de revista projeta uma página impressa: a grade existe, mas é uma ferramenta de composição, não um atalho de produção. "Quebrar a grade" nunca é aleatório — cada elemento que sangra pela borda, cada citação que atravessa duas colunas, tem uma razão de leitura.
-
-## Por que isso resolve "cara de IA"
-
-O padrão estatístico de IA é grid simétrico perfeito: hero centralizado, 3 cards idênticos, espaçamento uniforme. Layout editorial ataca exatamente esse tell com 4 movimentos:
-
-1. **Peso tipográfico assimétrico**: título gigante (96-200px) ao lado de body text minúsculo (14-16px) na mesma seção — dissonância de escala intencional, não hierarquia "segura".
-2. **Espaço em branco como elemento estrutural**: margem generosa não é "espaço vazio a preencher com mais um card" — é parte da composição (respiração deliberada, não desperdício).
-3. **Grid quebrado com propósito**: uma imagem que sangra até a borda da viewport, uma citação em pull-quote que atravessa 2 colunas, um elemento que ultrapassa o container — sempre ancorado numa grade subjacente (12 colunas, ou editorial de 5-7), nunca solto ao acaso.
-4. **Colapso de hierarquia**: forçar o leitor a desacelerar — nem tudo emite o mesmo sinal visual de importância ao mesmo tempo.
-
-## Padrões de Composição
-
-### Grid Editorial Base
-```css
-.editorial-grid {
-  display: grid;
-  grid-template-columns: repeat(12, 1fr);
-  gap: clamp(1rem, 2vw, 2.5rem);
-}
-/* Elemento que quebra a grade de propósito: sangra até a borda */
-.bleed {
-  grid-column: 1 / -1;
-  margin-inline: calc(-1 * var(--container-padding));
-}
-/* Pull-quote atravessando colunas, deslocado do fluxo normal */
-.pull-quote {
-  grid-column: 3 / 9;
-  font-size: clamp(1.75rem, 4vw, 3.5rem);
-  font-weight: 500;
-  line-height: 1.15;
-}
-```
-
-### Escala Tipográfica Dissonante
-```css
-.display {
-  font-size: clamp(4rem, 14vw, 12rem);   /* título editorial gigante */
-  line-height: 0.9;
-  letter-spacing: -0.02em;
-}
-.caption {
-  font-size: 0.8125rem;                   /* legenda/meta minúscula ao lado */
-  text-transform: uppercase;
-  letter-spacing: 0.08em;
-  opacity: 0.6;
-}
-```
-
-### Composição Não-Card (alternativas ao hero + 3 cards)
-| Padrão | Quando usar |
-|---|---|
-| Lista numerada tipográfica | Portfólio, casos de uso, features (número gigante + descrição curta, sem card/borda) |
-| Tabela editorial | Comparação de planos/specs — linhas finas, tipografia mono para dados, zero sombra |
-| Diagonal/overlay | Seção hero com imagem + texto sobrepostos, não empilhados verticalmente |
-| Timeline horizontal | Histórico/processo — scroll horizontal com marcos, não cards verticais |
-| Full-bleed com texto sobreposto | Estatística/número grande sobre imagem, sem card branco ao redor |
-
-## Checklist Antes de Entregar
-
-- [ ] Pelo menos 1 elemento quebra o grid com propósito (sangra, atravessa colunas, se desloca) — não é decoração, é composição
-- [ ] Há dissonância de escala tipográfica clara (não é tudo H1/H2/body no mesmo ritmo)
-- [ ] Espaço em branco tem função (agrupa, separa, dá ênfase) — não é preenchimento
-- [ ] Zero grid de 3 cards idênticos como padrão default da seção principal
-- [ ] A grade subjacente (12 colunas ou editorial 5-7) está sempre presente, mesmo quando quebrada
-
-## Skills Relacionadas
-
-- `anti-ai-slop` — auditoria final de tells genéricos
-- `design-directions` — direção de design escolhida define paleta/tipografia que este layout usa
-- `ui-ux-pro-max` — tokens de design system consumidos aqui
-- `motion-design` / `animation-web` — motion aplicado sobre a composição editorial
-
-## References
-
+# Skill Editorial Layout — Izanagi
+
+## Identidade
+
+Você projeta layout como um diretor de arte de revista projeta uma página impressa: a grade existe, mas é uma ferramenta de composição, não um atalho de produção. "Quebrar a grade" nunca é aleatório — cada elemento que sangra pela borda, cada citação que atravessa duas colunas, tem uma razão de leitura.
+
+## Por que isso resolve "cara de IA"
+
+O padrão estatístico de IA é grid simétrico perfeito: hero centralizado, 3 cards idênticos, espaçamento uniforme. Layout editorial ataca exatamente esse tell com 4 movimentos:
+
+1. **Peso tipográfico assimétrico**: título gigante (96-200px) ao lado de body text minúsculo (14-16px) na mesma seção — dissonância de escala intencional, não hierarquia "segura".
+2. **Espaço em branco como elemento estrutural**: margem generosa não é "espaço vazio a preencher com mais um card" — é parte da composição (respiração deliberada, não desperdício).
+3. **Grid quebrado com propósito**: uma imagem que sangra até a borda da viewport, uma citação em pull-quote que atravessa 2 colunas, um elemento que ultrapassa o container — sempre ancorado numa grade subjacente (12 colunas, ou editorial de 5-7), nunca solto ao acaso.
+4. **Colapso de hierarquia**: forçar o leitor a desacelerar — nem tudo emite o mesmo sinal visual de importância ao mesmo tempo.
+
+## Padrões de Composição
+
+### Grid Editorial Base
+```css
+.editorial-grid {
+  display: grid;
+  grid-template-columns: repeat(12, 1fr);
+  gap: clamp(1rem, 2vw, 2.5rem);
+}
+/* Elemento que quebra a grade de propósito: sangra até a borda */
+.bleed {
+  grid-column: 1 / -1;
+  margin-inline: calc(-1 * var(--container-padding));
+}
+/* Pull-quote atravessando colunas, deslocado do fluxo normal */
+.pull-quote {
+  grid-column: 3 / 9;
+  font-size: clamp(1.75rem, 4vw, 3.5rem);
+  font-weight: 500;
+  line-height: 1.15;
+}
+```
+
+### Escala Tipográfica Dissonante
+```css
+.display {
+  font-size: clamp(4rem, 14vw, 12rem);   /* título editorial gigante */
+  line-height: 0.9;
+  letter-spacing: -0.02em;
+}
+.caption {
+  font-size: 0.8125rem;                   /* legenda/meta minúscula ao lado */
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  opacity: 0.6;
+}
+```
+
+### Composição Não-Card (alternativas ao hero + 3 cards)
+| Padrão | Quando usar |
+|---|---|
+| Lista numerada tipográfica | Portfólio, casos de uso, features (número gigante + descrição curta, sem card/borda) |
+| Tabela editorial | Comparação de planos/specs — linhas finas, tipografia mono para dados, zero sombra |
+| Diagonal/overlay | Seção hero com imagem + texto sobrepostos, não empilhados verticalmente |
+| Timeline horizontal | Histórico/processo — scroll horizontal com marcos, não cards verticais |
+| Full-bleed com texto sobreposto | Estatística/número grande sobre imagem, sem card branco ao redor |
+
+## Checklist Antes de Entregar
+
+- [ ] Pelo menos 1 elemento quebra o grid com propósito (sangra, atravessa colunas, se desloca) — não é decoração, é composição
+- [ ] Há dissonância de escala tipográfica clara (não é tudo H1/H2/body no mesmo ritmo)
+- [ ] Espaço em branco tem função (agrupa, separa, dá ênfase) — não é preenchimento
+- [ ] Zero grid de 3 cards idênticos como padrão default da seção principal
+- [ ] A grade subjacente (12 colunas ou editorial 5-7) está sempre presente, mesmo quando quebrada
+
+## Skills Relacionadas
+
+- `anti-ai-slop` — auditoria final de tells genéricos
+- `design-directions` — direção de design escolhida define paleta/tipografia que este layout usa
+- `ui-ux-pro-max` — tokens de design system consumidos aqui
+- `motion-design` / `animation-web` — motion aplicado sobre a composição editorial
+
+## References
+
 Veja `references.md` nesta pasta.
 
 > Gerado pelo Izanagi AI: cópia fiel de `skills/editorial-layout/SKILL.md` (fonte da verdade).

package/.claude/skills/payments-billing/SKILL.md

@@ -3,89 +3,89 @@ name: payments-billing
 description: "Integração de pagamentos e cobrança recorrente (Stripe/Paddle/Mercado Pago): checkout, assinaturas, webhooks com verificação de assinatura, idempotência e reconciliação de estado. Use ao implementar cobrança, planos pagos ou checkout em qualquer produto."
 ---
 
-# Skill Payments & Billing — Izanagi
-
-## Identidade
-
-Você projeta cobrança para produção: todo webhook de pagamento chega em rede não confiável, pode chegar duplicado, fora de ordem ou nunca chegar. O padrão "funciona no dev" (marcar como pago direto no retorno do checkout) é a causa raiz mais comum de assinatura fantasma, cobrança duplicada e usuário pago sem acesso liberado.
-
-## Provedores
-
-| Ferramenta | Uso |
-|------------|-----|
-| Stripe | Padrão de mercado para SaaS internacional: Checkout, Billing, Connect |
-| Paddle | Merchant of Record (Paddle é o vendedor legal: cobre VAT/sales tax automaticamente) |
-| Mercado Pago | Padrão para produto focado em Brasil/LatAm (PIX, boleto, cartão local) |
-| LemonSqueezy | Merchant of Record, alternativa mais simples ao Paddle para indie/SaaS pequeno |
-
-Merchant of Record (Paddle/LemonSqueezy) elimina a responsabilidade de calcular/recolher imposto sobre venda digital em múltiplos países; Stripe puro (não Stripe Tax) deixa essa responsabilidade com o vendedor.
-
-## As 3 Garantias Obrigatórias de Todo Webhook de Pagamento
-
-1. **Verificação de assinatura**: valide o header de assinatura (`Stripe-Signature`, `X-Signature`...) contra o webhook secret ANTES de processar qualquer payload. Nunca confie em `req.body` sem essa etapa: qualquer um pode POSTar num endpoint público simulando "pagamento aprovado".
-2. **Idempotência**: grave o `event.id` processado (tabela `processed_events` ou equivalente) e descarte duplicados. O provedor reenvia o mesmo evento se seu endpoint não responder 2xx a tempo (Stripe retenta por até 72h com backoff exponencial) — processar o mesmo evento duas vezes deve produzir o mesmo resultado que processar uma vez.
-3. **Resposta rápida (ack-then-process)**: responda `200` assim que a assinatura for válida e o evento estiver enfileirado; processe a lógica de negócio (liberar acesso, enviar e-mail, atualizar plano) de forma assíncrona. Handler lento demais faz o provedor considerar timeout e reenviar, multiplicando processamento duplicado.
-
-```ts
-// Handler mínimo correto (Next.js Route Handler / Express)
-const sig = req.headers["stripe-signature"];
-const event = stripe.webhooks.constructEvent(rawBody, sig, webhookSecret); // lança se assinatura inválida
-
-const already = await db.processedEvents.findUnique({ where: { id: event.id } });
-if (already) return res.status(200).send("duplicate, ignored");
-
-await db.processedEvents.create({ data: { id: event.id, type: event.type } });
-await queue.enqueue("billing.process", event); // processamento pesado fora do request
-return res.status(200).send("ok");
-```
-
-## Nunca Confiar no Retorno do Frontend
-
-Liberar acesso pago no `success_url` do checkout (redirect do navegador) é a falha mais comum: o usuário pode fechar a aba antes do redirect, o navegador pode falhar, ou o pagamento pode ser recusado depois da tela de "sucesso" (métodos assíncronos: boleto, PIX, débito SEPA). **A única fonte de verdade de que um pagamento foi confirmado é o webhook do provedor no backend.** O `success_url` só melhora a UX (mostra "processando..."); nunca decide o estado do banco.
-
-## Assinaturas: Estados e Eventos Essenciais
-
-| Evento | Ação |
-|--------|------|
-| `checkout.session.completed` | Vincular customer_id do provedor ao usuário; se for assinatura, aguardar `invoice.paid` para liberar (evita liberar em método assíncrono ainda pendente) |
-| `invoice.paid` | Liberar/renovar acesso; resetar contador de falha de cobrança |
-| `invoice.payment_failed` | Iniciar dunning (retry automático do provedor + e-mail); não revogar acesso na primeira falha |
-| `customer.subscription.updated` | Sincronizar plano/quantidade/status local com o provedor (upgrade/downgrade/pausa) |
-| `customer.subscription.deleted` | Revogar acesso ao fim do período já pago (nunca instantaneamente, salvo cancelamento imediato explícito) |
-
-Dunning (retentativa de cobrança falha): configure o provedor para tentar novamente por alguns dias antes de suspender; revogar no primeiro `payment_failed` cancela clientes por falha temporária de cartão, não por decisão real.
-
-## Idempotência do Lado do Cliente (Requisições, Não Só Webhooks)
-
-Ao criar uma cobrança/checkout a partir de uma ação do usuário (ex: clique duplo, retry de rede), envie uma `Idempotency-Key` determinística (ex: hash de `userId + planId + timestamp arredondado`) na chamada à API do provedor. Isso é a segunda camada de proteção contra cobrança duplicada, independente da idempotência de webhook (que protege o lado do recebimento).
-
-## Métricas a Monitorar
-
-| Métrica | Meta |
-|---|---|
-| Taxa de sucesso de entrega de webhook | > 99% |
-| Tempo de processamento por evento | < 500ms até resposta 200 |
-| Lag entre evento gerado e processado | Alertar se > alguns minutos |
-
-## Checklist Antes de Produção
-
-- [ ] Toda rota de webhook verifica assinatura antes de tocar no payload
-- [ ] Tabela de eventos processados com constraint única em `event.id`
-- [ ] Handler responde 2xx rápido; lógica pesada é assíncrona (fila/job)
-- [ ] Liberação de acesso depende do webhook, nunca do retorno de navegador
-- [ ] `Idempotency-Key` em toda chamada de criação de cobrança originada por ação do usuário
-- [ ] Ambiente de teste usa modo sandbox/test do provedor com chaves e webhook secret próprios (nunca live keys em dev)
-- [ ] Segredos do provedor (secret key, webhook secret) vêm de variável de ambiente/secret manager (`automation-security`), nunca hardcoded
-
-## Skills Relacionadas
-
-- `security-privacy` — segredos, LGPD/GDPR para dados de pagamento
-- `automation-security` — gestão de credenciais do provedor
-- `error-recovery` — retry/backoff para chamadas à API do provedor
-- `observability-expert` — tracing do fluxo checkout → webhook → liberação de acesso
-
-## References
-
+# Skill Payments & Billing — Izanagi
+
+## Identidade
+
+Você projeta cobrança para produção: todo webhook de pagamento chega em rede não confiável, pode chegar duplicado, fora de ordem ou nunca chegar. O padrão "funciona no dev" (marcar como pago direto no retorno do checkout) é a causa raiz mais comum de assinatura fantasma, cobrança duplicada e usuário pago sem acesso liberado.
+
+## Provedores
+
+| Ferramenta | Uso |
+|------------|-----|
+| Stripe | Padrão de mercado para SaaS internacional: Checkout, Billing, Connect |
+| Paddle | Merchant of Record (Paddle é o vendedor legal: cobre VAT/sales tax automaticamente) |
+| Mercado Pago | Padrão para produto focado em Brasil/LatAm (PIX, boleto, cartão local) |
+| LemonSqueezy | Merchant of Record, alternativa mais simples ao Paddle para indie/SaaS pequeno |
+
+Merchant of Record (Paddle/LemonSqueezy) elimina a responsabilidade de calcular/recolher imposto sobre venda digital em múltiplos países; Stripe puro (não Stripe Tax) deixa essa responsabilidade com o vendedor.
+
+## As 3 Garantias Obrigatórias de Todo Webhook de Pagamento
+
+1. **Verificação de assinatura**: valide o header de assinatura (`Stripe-Signature`, `X-Signature`...) contra o webhook secret ANTES de processar qualquer payload. Nunca confie em `req.body` sem essa etapa: qualquer um pode POSTar num endpoint público simulando "pagamento aprovado".
+2. **Idempotência**: grave o `event.id` processado (tabela `processed_events` ou equivalente) e descarte duplicados. O provedor reenvia o mesmo evento se seu endpoint não responder 2xx a tempo (Stripe retenta por até 72h com backoff exponencial) — processar o mesmo evento duas vezes deve produzir o mesmo resultado que processar uma vez.
+3. **Resposta rápida (ack-then-process)**: responda `200` assim que a assinatura for válida e o evento estiver enfileirado; processe a lógica de negócio (liberar acesso, enviar e-mail, atualizar plano) de forma assíncrona. Handler lento demais faz o provedor considerar timeout e reenviar, multiplicando processamento duplicado.
+
+```ts
+// Handler mínimo correto (Next.js Route Handler / Express)
+const sig = req.headers["stripe-signature"];
+const event = stripe.webhooks.constructEvent(rawBody, sig, webhookSecret); // lança se assinatura inválida
+
+const already = await db.processedEvents.findUnique({ where: { id: event.id } });
+if (already) return res.status(200).send("duplicate, ignored");
+
+await db.processedEvents.create({ data: { id: event.id, type: event.type } });
+await queue.enqueue("billing.process", event); // processamento pesado fora do request
+return res.status(200).send("ok");
+```
+
+## Nunca Confiar no Retorno do Frontend
+
+Liberar acesso pago no `success_url` do checkout (redirect do navegador) é a falha mais comum: o usuário pode fechar a aba antes do redirect, o navegador pode falhar, ou o pagamento pode ser recusado depois da tela de "sucesso" (métodos assíncronos: boleto, PIX, débito SEPA). **A única fonte de verdade de que um pagamento foi confirmado é o webhook do provedor no backend.** O `success_url` só melhora a UX (mostra "processando..."); nunca decide o estado do banco.
+
+## Assinaturas: Estados e Eventos Essenciais
+
+| Evento | Ação |
+|--------|------|
+| `checkout.session.completed` | Vincular customer_id do provedor ao usuário; se for assinatura, aguardar `invoice.paid` para liberar (evita liberar em método assíncrono ainda pendente) |
+| `invoice.paid` | Liberar/renovar acesso; resetar contador de falha de cobrança |
+| `invoice.payment_failed` | Iniciar dunning (retry automático do provedor + e-mail); não revogar acesso na primeira falha |
+| `customer.subscription.updated` | Sincronizar plano/quantidade/status local com o provedor (upgrade/downgrade/pausa) |
+| `customer.subscription.deleted` | Revogar acesso ao fim do período já pago (nunca instantaneamente, salvo cancelamento imediato explícito) |
+
+Dunning (retentativa de cobrança falha): configure o provedor para tentar novamente por alguns dias antes de suspender; revogar no primeiro `payment_failed` cancela clientes por falha temporária de cartão, não por decisão real.
+
+## Idempotência do Lado do Cliente (Requisições, Não Só Webhooks)
+
+Ao criar uma cobrança/checkout a partir de uma ação do usuário (ex: clique duplo, retry de rede), envie uma `Idempotency-Key` determinística (ex: hash de `userId + planId + timestamp arredondado`) na chamada à API do provedor. Isso é a segunda camada de proteção contra cobrança duplicada, independente da idempotência de webhook (que protege o lado do recebimento).
+
+## Métricas a Monitorar
+
+| Métrica | Meta |
+|---|---|
+| Taxa de sucesso de entrega de webhook | > 99% |
+| Tempo de processamento por evento | < 500ms até resposta 200 |
+| Lag entre evento gerado e processado | Alertar se > alguns minutos |
+
+## Checklist Antes de Produção
+
+- [ ] Toda rota de webhook verifica assinatura antes de tocar no payload
+- [ ] Tabela de eventos processados com constraint única em `event.id`
+- [ ] Handler responde 2xx rápido; lógica pesada é assíncrona (fila/job)
+- [ ] Liberação de acesso depende do webhook, nunca do retorno de navegador
+- [ ] `Idempotency-Key` em toda chamada de criação de cobrança originada por ação do usuário
+- [ ] Ambiente de teste usa modo sandbox/test do provedor com chaves e webhook secret próprios (nunca live keys em dev)
+- [ ] Segredos do provedor (secret key, webhook secret) vêm de variável de ambiente/secret manager (`automation-security`), nunca hardcoded
+
+## Skills Relacionadas
+
+- `security-privacy` — segredos, LGPD/GDPR para dados de pagamento
+- `automation-security` — gestão de credenciais do provedor
+- `error-recovery` — retry/backoff para chamadas à API do provedor
+- `observability-expert` — tracing do fluxo checkout → webhook → liberação de acesso
+
+## References
+
 Veja `references.md` nesta pasta: curadoria das fontes oficiais (Stripe Docs, Paddle Docs) para este tópico.
 
 > Gerado pelo Izanagi AI: cópia fiel de `skills/payments-billing/SKILL.md` (fonte da verdade).

package/.manifest

@@ -1,11 +1,11 @@
 {
   "name": "izanagi-ai",
-  "version": "3.21.0",
+  "version": "3.22.0",
   "description": "Izanagi AI - Modular Skill-Oriented AI Prompt & Agent Framework for Autonomous Software Engineering",
   "author": "Pedro Henrique Sanches Leal",
   "license": "MIT",
   "homepage": "https://github.com/pedrohenriquesanchesleal4-debug/izanagi-ai#readme",
-  "generatedAt": "2026-09-08T13:31:23.174Z",
+  "generatedAt": "2026-09-09T16:41:15.896Z",
   "agents": [
     {
       "id": "adversarial-critic",

package/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md: Izanagi AI Framework Reference
 
-> Version 3.21.0
+> Version 3.22.0
 > Modular Skill-Oriented AI Prompt & Agent Framework for Autonomous Software Engineering
 > Multi-CLI: Opencode · Claude Code · Codex · Cursor · Copilot · Kimi (Smart Auto-Detection & Selective Generation)