wizz-method 2.11.2 → 2.13.0

package/README.md

@@ -72,7 +72,7 @@ The Wizz layer applies to everyone: standard closing (✅/➡️/🎯), token ec
 npx wizz-method install
 ```
 
-Follow the prompts, then open your AI IDE (Claude Code, Cursor, Codex and others) in the project folder.
+The guided install takes four steps (folder, what you'll use it for, your AI tool, your name) and shows what will be installed before it starts. Choose Português on the first screen or pass `--lang pt`; `--advanced` asks the complete question list. Then open your AI tool (Claude Code, Cursor, Codex and others) in the project folder.
 
 ### 2. Customize the Wizz layer
 
@@ -106,6 +106,7 @@ Without a TTY, the default language is "Português (BR)". Use `--lang` or the `W
 | Command | Does |
 |---|---|
 | `npx wizz-method install` | Installs modules, hooks, skills and MCPs into the project |
+| `npx wizz-method catalog [--area <area>]` | Lists every area, skill and tool, marking what's installed |
 | `npx wizz-method status` | Shows what's installed and each module's version |
 | `npx wizz-method doctor` | Diagnostics: hooks, rtk, jq, optional Python and `_wizz/` drift |
 | `npx wizz-method resolve [--skill <name>]` | Regenerates the customization snapshots in `_wizz/_resolved/` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wizz-method",
-  "version": "2.11.2",
+  "version": "2.13.0",
   "description": "Wizz Method: método de agência orientado por IA em PT-BR",
   "keywords": [
     "agile",

package/skills-registry.yaml

@@ -159,7 +159,7 @@ areas:
       - id: wizz-animate
         entry: true
         door: motion
-        when: "PORTA de motion/assets: executar animação e gerar mídia. Craft de micro-interação (regras do Emil Kowalski: saída > entrada, só transform/opacity, reduced-motion). Puxa: wizz-design-motion-principles (auditar animação existente), wizz-remotion-best-practices (vídeo em React), wizz-canvas-design (PNG/PDF por código) e wizz-algorithmic-art (visual generativo)."
+        when: "PORTA de motion/assets: executar animação e gerar mídia. Craft de micro-interação (regras do Emil Kowalski: saída > entrada, só transform/opacity, reduced-motion). Puxa: wizz-design-motion-principles (auditar animação existente), wizz-remotion-best-practices (vídeo em React), wizz-video-effects (efeitos e SFX de ad/Reels com portões), wizz-canvas-design (PNG/PDF por código) e wizz-algorithmic-art (visual generativo)."
         rel:
           pairs_with: [wizz-design-motion-principles]
       - id: wizz-design-motion-principles
@@ -171,7 +171,7 @@ areas:
         door: motion
         when: "MONTAR o filme: vídeo em React (Remotion) com áudio, SFX, legenda e timing com precisão de frame. No pipeline de vídeo é o Remotion que faz a montagem final; o hyperframes só desenha as telas mudas (regra: HyperFrames desenha, Remotion monta — ver _shared/video-pipeline.md do módulo wizz)."
         rel:
-          after: [buttercut, ctc-align, get-brolls, hyperframes, wizz-motion-3d-director]
+          after: [buttercut, ctc-align, get-brolls, hyperframes, wizz-motion-3d-director, wizz-video-effects]
       - id: wizz-canvas-design
         door: motion
         when: "Gerar PNG/PDF editável por código (carrossel, quote card, infográfico) com fonte/cor/logo sempre certos. Traz canvas-fonts."
@@ -187,13 +187,27 @@ areas:
         when: "Timing por forced alignment: timestamps palavra a palavra de narração TTS para sincronizar legenda, corte de cena e animação com a fala. Fonte única de timing no pipeline de vídeo; substitui Whisper e estimativa manual."
         rel:
           after: [voicebox]
+          before: [wizz-remotion-best-practices, wizz-video-effects]
+      # Motor de decisão de efeitos (Python) portado do sistema de efeitos do
+      # trafego em 2026-09-24: orçamento anti-excesso, som por evento semântico,
+      # efeitos nos respiros, portões de zona segura (ad/orgânico), densidade,
+      # excesso, ritmo e loudness. Não monta o filme: isso é do Remotion.
+      - id: wizz-video-effects
+        door: motion
+        when: "Decidir e conferir os EFEITOS e o SOM de um vídeo curto vertical (ad ou Reels): que efeito entra (punch, flash, shake, transição), onde e quando não entra, que SFX toca em cada acontecimento e a que volume, ducking, loudness do master e portões de zona segura, densidade, excesso e ritmo do gancho. Gatilhos: 'efeitos sonoros do criativo', 'SFX do Reels', 'o vídeo tá com zoom demais', 'conferir zona segura do anúncio', 'LUFS do vídeo'."
+        not_when:
+          - "Montar o filme em React (sequência de cenas, legenda, <Audio>): é wizz-remotion-best-practices; esta skill decide os efeitos que ele monta."
+          - "Filme de lançamento de produto com trilha e direção visual: é wizz-huashu-design."
+        rel:
+          after: [ctc-align, hyperframes]
           before: [wizz-remotion-best-practices]
+          pairs_with: [wizz-ad-creative]
     clis:
       - id: hyperframes
         when: "DESENHAR telas de vídeo em HTML/CSS (HTML→MP4, agent-native, 20+ skills): cena isolada e MUDA — maqueta de WhatsApp/ChatGPT, gráfico animado, título, loop. NÃO usar para montagem com áudio/SFX/legenda sincronizada (posicionador de áudio falhou em produção, ~2,76s de drift; CSS vaza entre telas): a montagem final é do Remotion (regra: HyperFrames desenha, Remotion monta — ver _shared/video-pipeline.md do módulo wizz). Precisa ffmpeg + Node 22 + Chrome headless."
         not_when: "Montagem com áudio/SFX/legenda sincronizada (posicionador de áudio falhou em produção, ~2,76s de drift; CSS vaza entre telas)."
         rel:
-          before: [wizz-remotion-best-practices]
+          before: [wizz-remotion-best-practices, wizz-video-effects]
         platform: [darwin, linux]
         # O check confere o SHA fixado, não só a existência da pasta: o bundle é
         # copiado (não clonado), então o pin é gravado num marcador no install.
@@ -228,7 +242,7 @@ areas:
         not_when:
           - "Analisar/resumir um vídeo que já se tem em mãos: é claude-video."
           - "Cortar/montar footage já captado: é buttercut (corte fino) ou wizz-remotion-best-practices (montagem final)."
-          - "Gerar imagem/vídeo por IA: é fal-video. O get-brolls busca material REAL, não sintético."
+          - "Gerar imagem/vídeo por IA: é wizz-ad-creative, que escreve o prompt para o usuário colar no Flow ou em outra IA. O get-brolls busca material REAL, não sintético."
           - "Desenhar uma tela/cena em HTML: é hyperframes."
           - "Minerar/estudar criativo ou oferta de concorrente (Biblioteca de Anúncios, 'baixa esse anúncio pra eu ver'): é wizz-lowticket-minerador na área ads. O get-brolls capta insert para a SUA edição, com procedência registrada — não é ferramenta de inteligência competitiva, e o fato de saber baixar um Reel não o torna uma."
         rel:
@@ -283,19 +297,11 @@ areas:
         when: "Timestamps palavra a palavra CONFIÁVEIS de narração TTS (texto conhecido): sincronizar legenda, corte de cena, animação e elemento gráfico com a fala. Fonte única de timing em vídeo — substitui timestamps do Whisper e estimativa manual. Skill da lib: ctc-align (instalação + helper align.py + regras de âncora monotônica e duração mínima). Roda em CPU, sem CUDA."
         rel:
           after: [voicebox]
-          before: [wizz-remotion-best-practices]
+          before: [wizz-remotion-best-practices, wizz-video-effects]
         platform: [darwin, linux]
         check: "test -x ./tools/ctc-align/.venv/bin/ctc-forced-aligner"
         install: 'mkdir -p tools/ctc-align && uv venv --python 3.12 tools/ctc-align/.venv && uv pip install --python tools/ctc-align/.venv/bin/python "git+https://github.com/MahmoudAshraf97/ctc-forced-aligner.git"'
         verify: "command -v ffmpeg >/dev/null 2>&1 && command -v uv >/dev/null 2>&1"
-      - id: fal-video
-        when: "GERAR vídeo/imagem por IA (Veo/Kling/Wan e outros modelos via API da fal.ai), estilo UGC/ad-ready. Substitui o arcads: mesmo caso de uso (vídeo gerado por IA), custo 50-95% menor por vídeo, sem clone-and-run pesado. Precisa FAL_KEY em .env. Sem CLI binária oficial: usa o client Node oficial @fal-ai/client como dependência do projeto."
-        rel:
-          pairs_with: [wizz-ad-creative]
-        platform: [darwin, linux]
-        check: "test -f node_modules/@fal-ai/client/package.json"
-        # Pin de supply chain (2026-08-25): versão fixa (client oficial fal.ai); atualizar conscientemente.
-        install: "npm install @fal-ai/client@1.10.1"
       - id: apple-design
         when: "Revisar/auditar UI NATIVA (iOS/macOS: SwiftUI, Flutter, React Native, Tauri, Electron) contra o Apple HIG e o Liquid Glass — compliance com o HIG, acessibilidade, dark mode, navegação. Cobre o gap que o wizz-taste-skill declara fora de escopo ('native mobile: use Apple HIG directly')."
         not_when: "UI web: aí é wizz-ui-ux-pro-max / wizz-impeccable."
@@ -559,9 +565,10 @@ areas:
     # para as CLIs de vídeo quando o roteiro vira vídeo", prometendo um handoff
     # que a área não pode fazer: as CLIs de vídeo (get-brolls, hyperframes,
     # buttercut, claude-video) moram em `designer`, e o único cli daqui é o
-    # postiz. Medido: essa frase puxava pedido de ASSET ("imagens de apoio pro
-    # meu Reel", "carrossel pro Instagram") para social, que não tem a
-    # ferramenta. A fronteira ficou no summary; a nota ficou aqui.
+    # buffer (era o postiz até 2026-09-25). Medido: essa frase puxava pedido
+    # de ASSET ("imagens de apoio pro meu Reel", "carrossel pro Instagram")
+    # para social, que não tem a ferramenta. A fronteira ficou no summary;
+    # a nota ficou aqui.
     summary: "Social e roteiros virais: o TEXTO e o ROTEIRO de Reels/Shorts, hooks, legenda, thread, calendário de conteúdo. Persona Rafa, aplica o Blueprint de Roteiro Viral. Captar, desenhar ou montar o asset em si (b-roll, vídeo, carrossel, imagem) não é desta área."
     skills:
       - id: wizz-social-content
@@ -570,7 +577,7 @@ areas:
           - "Editar/revisar texto de social já escrito: aí é wizz-copy-editing."
           - "Pedir SÓ o asset de um Reel/vídeo — b-roll, 'imagens de apoio', 'cenas de apoio', imagem de corte, footage — sem que o texto ou o roteiro façam parte do pedido: a captação é get-brolls, na área designer. Esta entrada entra quando o TEXTO ou o ROTEIRO é parte do que se pede; se o pedido junta roteiro E captação, são 2 áreas."
         rel:
-          before: [get-brolls, postiz]
+          before: [buffer, get-brolls]
           pairs_with: [wizz-canvas-design, wizz-content-strategy, wizz-copy-editing, wizz-launch-strategy]
       - id: wizz-content-strategy
         when: "Decidir O QUE produzir de conteúdo (topic clusters, calendário, pilares)."
@@ -582,20 +589,22 @@ areas:
           after: [wizz-copywriting]
           pairs_with: [wizz-social-content]
     clis:
-      - id: postiz
-        when: "PUBLICAR/agendar de verdade em redes sociais (30+ integrações) a partir do conteúdo que o wizz-social já gerou. Separa 'gerar' (Wizz) de 'publicar' (Postiz). Precisa autenticar antes (`postiz auth:login` ou env `POSTIZ_API_KEY`); para imagem/vídeo a própria CLI faz o upload."
+      - id: buffer
+        when: "PUBLICAR/agendar de verdade em redes sociais (Instagram, TikTok, YouTube, LinkedIn, Facebook, Threads, X, Pinterest, Bluesky, Mastodon, Google Business) a partir do conteúdo que o wizz-social já gerou. Separa 'gerar' (Wizz) de 'publicar' (Buffer). Precisa de API key (`buffer init` ou env `BUFFER_API_KEY`). Imagem/vídeo NÃO sobe do disco: a mídia precisa estar numa URL pública HTTPS e direta (Cloudinary, Cloudflare R2), estável até o post publicar."
         not_when: "Escrever o roteiro ou a legenda: isso é skill da área (wizz-social-content, wizz-copy-editing)."
         rel:
           after: [wizz-social-content]
-        # Item 30 da auditoria (2026-09-11, Parte 3.7). Pin de supply chain
-        # (2026-09-12): versão publicada fixa no npm, atualizar conscientemente.
+        # Substituiu o postiz em 2026-09-25: a nuvem da Postiz não tem plano
+        # grátis (a partir de US$ 29/mês) e o self-host exige servidor próprio
+        # mais um app de desenvolvedor por rede. O plano grátis do Buffer tem
+        # 3 canais, 10 posts na fila por canal e API/CLI/MCP inclusos.
         # CLI, não MCP: o schema de `mcps:` deste registry só aceita stdio
-        # ({command,args,env}) e o MCP hospedado da Postiz é HTTP+OAuth
-        # (https://mcp.postiz.com/mcp-oauth-dynamic) — não encaixa. Existe uma
-        # skill wrapper (`gitroomhq/postiz-agent`) que só dirige esta mesma CLI;
-        # opcional, não registrada aqui.
-        check: "command -v postiz >/dev/null 2>&1"
-        install: "npm install -g postiz@2.0.16"
+        # ({command,args,env}) e o MCP do Buffer é HTTP com bearer
+        # (https://mcp.buffer.com/mcp) — não encaixa.
+        # Pin de supply chain (2026-09-25): versão publicada fixa no npm,
+        # atualizar conscientemente.
+        check: "command -v buffer >/dev/null 2>&1"
+        install: "npm install -g @bufferapp/cli@1.2.0"
 
   ads:
     agent: wizz-ads
@@ -606,9 +615,9 @@ areas:
         rel:
           pairs_with: [wizz-ad-creative, wizz-tracking-audit]
       - id: wizz-ad-creative
-        when: "Gerar/iterar criativos e headlines de anúncio em escala (RSA, variações)."
+        when: "Gerar/iterar criativos e headlines de anúncio em escala (RSA, variações). Inclui escrever o PROMPT de imagem/vídeo por IA (Veo, Kling, Flow e similares) para o usuário gerar fora do método: nenhuma API de geração está integrada."
         rel:
-          pairs_with: [fal-video, wizz-copywriting, wizz-paid-ads]
+          pairs_with: [wizz-copywriting, wizz-paid-ads, wizz-video-effects]
       - id: wizz-analytics-tracking
         when: "Tracking de conversão pros anúncios (compartilhada com growth)."
         rel:

package/src/bmm-skills/module.yaml

@@ -1,5 +1,5 @@
 code: bmm
-name: "Wizz Method"
+name: "Wizz Product & Code"
 description: "Full-lifecycle AI agile development: analysis, planning, architecture, implementation"
 default_selected: true # This module will be selected by default for new installations
 

package/src/modules/lowticket/skills/wizz-lowticket-metodologia/knowledge/04-criativos.md

@@ -8,7 +8,7 @@
 
 ### 4.1 Creative structure
 
-1. **Hook** (first 3 seconds): captures and filters. *(11.6 puts it at 5 seconds; see [open point 19](pontos-em-aberto.md).)*
+1. **Hook** (first 3 seconds): captures and filters. *(adopted rule, see [open point 19](pontos-em-aberto.md).)*
 2. **Body**: useful content, social validation, an engaging story.
 3. **CTA**: urgent call to action.
 

package/src/modules/lowticket/skills/wizz-lowticket-metodologia/knowledge/11-checklist-roi.md

@@ -30,7 +30,7 @@
 
 ### 11.6 Creative and campaign
 
-- Hook in the first 5 seconds, captions always on, 9:16, no studio look. **Link CTR > 1.5% and CPC < R$2** — outside that range the problem is the creative.
+- Hook in the first 3 seconds (see [open point 19](pontos-em-aberto.md)), captions always on, 9:16, no studio look. **Link CTR > 1.5% and CPC < R$2** — outside that range the problem is the creative.
 - **Rule for reading the two metrics**: CTR below 1.5% = creative (weak hook, nobody clicks). CPC above expected with good CTR = audience or VSL, not creative. While either metric is off, **don't touch the page, order bump, or upsell** — the leak is upstream. Broad audience: **the creative does the segmenting, not the interest targeting**. Found the winner: new variations and angles **within the same campaign**.
 - Campaign: CBO with Advantage on everything (per the source, ABO is going away). **Initial bid cap = break-even × 1.5** (§3.2 and §3.7 of [`03`](03-campanha-bidcap.md), [point 58](pontos-em-aberto.md); the source said "full average ticket, never half"). Inflated budget: a R$30 ticket calls for a R$300-500/day campaign. Zero targeting (age and placement on automatic).
 - Verdict rules: spent almost nothing in the first **17h** = the offer didn't pass (tested for free). A creative is only cut with **all 4 conditions of §3.7** of [`03`](03-campanha-bidcap.md): spend ≥ 3x the Bid Cap, ROAS below break-even, zero sales and no recent structural change (don't touch it before that; [point 59](pontos-em-aberto.md)). **3 days of positive ROI** = offer validated: **don't lower the bid cap** while performance is high (§3.2, [point 57](pontos-em-aberto.md)); scale in the lever order of §3.7 (raise the Bid Cap first) with the step from the ROAS ruler of §3.2 (≥ 2.5 → +50% · 2.0 to 2.5 → +30% · < 2.0 → +20%; [point 54](pontos-em-aberto.md)).

package/src/modules/lowticket/skills/wizz-lowticket-metodologia/knowledge/12-mineracao-ofertas.md

@@ -75,7 +75,7 @@ Self-contained interactive mind map (HTML with the data embedded in a `BLOCKS` a
 | **Encontrar** (Find) | potential market ("if there's no ad running, there's no market"), an offer to model, a specialist | 12.1, 12.2, 9.2 |
 | **Entender** (Understand) | market, audience (pain/desire/awareness, "steal their words" from comments and reviews), a single unified list of the offer's features, a single persona with a name and a routine | 8, 12.5 |
 | **Estruturar** (Structure) | product, irresistible offer, promise, unique mechanisms, deliverables ("the word PDF never appears"), a bonus that knocks down an objection, order bump (3 to 5 active), upsell/downsell | 5, 11.1, 11.4 |
-| **Executar** (Execute) | copy in the order **page, then ad, then VSL**; 9x16 creative with a hook in the first 5 seconds; page with two plans and a cross-sell pop-up; checkout with email only and Pix >75%; Instagram BBF; VSL 90s-2min; ads manager set up before spending | 6.1, 6.2, 11.2, 11.3, 11.4 |
+| **Executar** (Execute) | copy in the order **page, then ad, then VSL**; 9x16 creative with a hook in the first 3 seconds; page with two plans and a cross-sell pop-up; checkout with email only and Pix >75%; Instagram BBF; VSL 90s-2min; ads manager set up before spending | 6.1, 6.2, 11.2, 11.3, 11.4 |
 | **Escalar** (Scale) | separate BM and account; CBO with an initial bid cap = break-even × 1.5 ("ABO is going away"); 17h with no spend = the offer didn't pass; a creative is only cut with all 4 conditions of 3.7 together (spend ≥ 3x the Bid Cap); 3 green days = offer validated, and from there the budget rises by the ROAS ruler of 3.2 | 3.2, 3.7, 11.6 |
 
 **Note:** the source said "bid cap at full ticket", "3x the ticket with ROI<1 kills it" and "3 green days raises up to 50%". Since 2026-09-24 the rulers in [`03`](03-campanha-bidcap.md) apply ([points 56, 58 and 59](pontos-em-aberto.md)).

package/src/modules/lowticket/skills/wizz-lowticket-metodologia/knowledge/pontos-em-aberto.md

@@ -22,7 +22,7 @@ Contradictions and gaps found while distilling this methodology, pulled into thi
 16. **VSL on the page: does it help or hurt?** Section 11.3 mandates a 90s-2min VSL in low ticket and 6.2 mandates a VSL right after the headline. But the funnel data in 6A.9 shows the page **without** a VSL performing better (87→35 vs. 75→32). Likely reading: the VSL helps when the offer needs explaining and hurts when the product explains itself. Confirm with the source.
 17. **"More profitable": training an expert, or closing a co-production deal?** The Instagram source says training an expert is the most profitable path (no prior audience, no bargaining); it also says co-production is the most profitable and sustainable model. The two pieces of material compare against different baselines: co-production wins **against running solo**, and training wins **against co-production**, because it doesn't split the profit. Reading adopted in section 9.2: train > partner > solo, with the partnership winning on execution speed. Neither source compares all three side by side, so confirm with the source.
 18. ~~**VSL length: 90s-2min or 7-9 minutes?**~~ **RULE ADOPTED (2026-08-28, by reading the material; not confirmed with the source.)** What decides it is **what the VSL needs to prove**, not the ticket alone. A product that proves itself on screen (showrun, a recording opening the product from the inside, 11.3): **90s to 2min**. An offer that needs to build a mechanism and authority before reaching the price: **7 to 9 min**, in the 6-block structure (4.7). The 6-block structure holds in both cases: it changes the time per block, not the order or function. **When in doubt, start short:** stretching a short VSL that retained is cheaper than salvaging a long one nobody watched.
-19. **Hook: 3 or 5 seconds?** Section 4.1 and the newer source both say **3 seconds**; section 11.6 (the ROI checklist) says **5 seconds**. In practice: write for 3, tolerate up to 5. Not a real operational conflict, but the numbers diverge in the material.
+19. ~~**Hook: 3 or 5 seconds?**~~ **RULE ADOPTED (2026-09-24, owner's decision): 3 seconds.** Section 4.1 and the newer source said 3 seconds and section 11.6 said 5; 11.6 was corrected. Reason: Meta's hook rate (3-second plays divided by impressions) measures exactly this window, and TikTok recommends stating the proposition in the first 3 seconds. The 5 seconds that remain in §18.13 are a different rule: the **mechanism** comes in by second 5, after the hook, not in the first line.
 20. ~~**Buying engagement (an engagement-buying tool)**~~ **RULE ADOPTED (2026-09-24, the operation owner's decision): allowed with a condition.** Buying engagement is allowed, with the risk noted in the plan (Meta may cut reach or take down the account). Condition in [`guardrails.md` 20](guardrails.md#20--buying-engagement-likes-and-comments).
 21. ~~**Realistic AI profile and platform policy**~~ **RULE ADOPTED (2026-09-24, the operation owner's decision): allowed with a condition.** An AI avatar is allowed with a notice that it is AI; what you don't do is hide that it's AI. Condition in [`guardrails.md` 21](guardrails.md#21--ai-avatar).
 
@@ -136,4 +136,4 @@ Contradictions and gaps found while distilling this methodology, pulled into thi
 
 ---
 
-**Count:** 67 points in total: 25 open, 39 resolved, adopted or closed (8 of them with a condition in guardrails: 20, 21, 23, 32, 44, 45, 48, 49), 0 blocked, and 3 with no publishable content because they're local bookkeeping (5, 6, 13), with the number preserved only so it doesn't break a link from another shard.
+**Count:** 67 points in total: 24 open, 40 resolved, adopted or closed (8 of them with a condition in guardrails: 20, 21, 23, 32, 44, 45, 48, 49), 0 blocked, and 3 with no publishable content because they're local bookkeeping (5, 6, 13), with the number preserved only so it doesn't break a link from another shard.

package/src/modules/wizz/_shared/video-pipeline.md

@@ -22,11 +22,12 @@
 | Assemble the film: sequence of scenes + narration + SFX + captions + frame timing | **Remotion** (skill `wizz-remotion-best-practices`) |
 | Captions passing behind the person on a recorded talking head (matte) | embedded-captions (HyperFrames bundle), then the clip goes to Remotion |
 | Word-by-word timestamps of the TTS narration (sync captions/cuts/animation) | `ctc-align` |
+| Decide which effects and SFX go where (and where not), then gate the render: safe zone (ad or organic), density, excess, rhythm, loudness | `wizz-video-effects` |
 | Narration / voice / TTS / voice cloning | `voicebox` |
 | **Source B-roll / inserts: find real footage of what the script names** | `get-brolls` (darwin) |
 | Edit/cut recorded footage (cuts, selects, roughcut) | `buttercut` (darwin-arm64 only) |
 | Analyze an existing reference video (frames + transcription) | `claude-video` |
-| AI-generated video/image (Veo/Kling/Wan), UGC / ad-ready style | `fal-video` (designer area; needs `FAL_KEY`) |
+| AI-generated video/image (Veo/Kling/Wan), UGC / ad-ready style | `wizz-ad-creative` (ads area) writes the prompt; the user generates it in Flow or another AI tool, outside the method |
 
 ## Full chain (script → publishing)
 
@@ -42,11 +43,18 @@
    with its provenance recorded. Runs in parallel with steps 2–4: it depends on the
    script, not on the voice. **This step has a human gate — the agent never
    self-approves.**
-6. **Assembly** — **Remotion** joins the exported scenes and the approved B-roll,
+6. **Effects and sound** — `wizz-video-effects` turns what happens in the
+   narration into semantic events (a price appears, a verdict lands, a message
+   arrives), maps each to a licensed SFX and a level, anchors punches and flashes
+   on real speech breaths from the ctc-align timestamps, and runs every effect
+   through the anti-excess budget. Output: the timeline JSON the assembly reads.
+7. **Assembly** — **Remotion** joins the exported scenes and the approved B-roll,
    adds audio, SFX, and captions at the ctc-align timestamps, with frame precision.
    Scenes follow the handoff contract below.
-7. **Fine cut** (if there's recorded footage) — `buttercut`.
-8. **Publishing/distribution** — social/ads area.
+8. **Gates on the final file** — `wizz-video-effects` measures the rendered MP4:
+   safe zone for the piece's profile, density, loudness. Then look at frames.
+9. **Fine cut** (if there's recorded footage) — `buttercut`.
+10. **Publishing/distribution** — social/ads area.
 
 **Screens vs. B-roll — they are not interchangeable.** `hyperframes` invents a
 visual (a mockup, a chart, a title); `get-brolls` finds the real thing that the

package/src/modules/wizz/agents/wizz-designer/SKILL.md

@@ -30,7 +30,7 @@ You are Wizz's Designer. It creates high-level interfaces and landing pages, sho
 For every task, **go through the right door via the `Skill` tool** and bring the result in plain language:
 - Decide BEFORE building (brief, visual direction, motion/3D path) → `wizz-decision-maker` (pulls in wizz-design-needs, wizz-taste-skill, wizz-motion-3d-director)
 - Create/improve UI (landing, design system, component, polish) → `wizz-ui-ux-pro-max` (pulls in wizz-premium-landing-ui-researcher, wizz-ui-component-curator, wizz-impeccable, wizz-taste-skill, wizz-huashu-design, wizz-react-components)
-- Run animation and generate media → `wizz-animate` (pulls in wizz-design-motion-principles, wizz-remotion-best-practices, wizz-canvas-design, wizz-algorithmic-art)
+- Run animation and generate media → `wizz-animate` (pulls in wizz-design-motion-principles, wizz-remotion-best-practices, wizz-video-effects, wizz-canvas-design, wizz-algorithmic-art)
 
 Always **show the visual/plan before the code**. Code building is `wizz-agent-dev`'s job; for a one-off tweak, point to `wizz-quick-dev`.
 

package/src/modules/wizz/agents/wizz-maestro/SKILL.md

@@ -76,7 +76,7 @@ The Diretor (`wizz-router`) has already done the triage and handed it to you bec
    - `areas:` — `agent` (must match the menu's) and `skills:` (each with an `id` + short `when`). Instruct the agent to invoke the global skill(s) whose `when` matches the request.
    - `utility:` — cross-cutting skills (find-skills, enhance-prompt, wizz-router). Offer when it fits.
    - `mcps:` (per area) and `mcp_utility:` (cross-cutting) — MCP servers the area uses to actually ACT (e.g. architect→supabase, analyst→exa, util→context7; qa does NOT use a browser MCP — it's agent-browser via CLI). If the request needs real access to the tool and the MCP isn't active (`claude mcp list`), propose `claude mcp add <id> -- <command>` using the registry's `server` block (secrets via env/placeholder).
-   - `clis:` (per area) and `cli_utility:` (cross-cutting) — command-line tools the agent calls directly (neither a skill nor an MCP): e.g. qa→agent-browser; designer→hyperframes/get-brolls/claude-video/buttercut/voicebox/fal-video (video); growth→scrapling; seo→distribb; social→postiz. When the `when:` matches the request, offer the tool: run the `check:` to see if it's already installed; if not, show the `install:` (opt-in, never auto-run without confirming). Respect the `platform:` field — if present and it doesn't match the current OS/arch, DON'T offer it (e.g., `buttercut` is `darwin-arm64`, Apple Silicon only). Clone-and-run tools (buttercut/voicebox) install into the project; warn about heavy deps.
+   - `clis:` (per area) and `cli_utility:` (cross-cutting) — command-line tools the agent calls directly (neither a skill nor an MCP): e.g. qa→agent-browser; designer→hyperframes/get-brolls/claude-video/buttercut/voicebox (video); growth→scrapling; seo→distribb; social→buffer. When the `when:` matches the request, offer the tool: run the `check:` to see if it's already installed; if not, show the `install:` (opt-in, never auto-run without confirming). Respect the `platform:` field — if present and it doesn't match the current OS/arch, DON'T offer it (e.g., `buttercut` is `darwin-arm64`, Apple Silicon only). Clone-and-run tools (buttercut/voicebox) install into the project; warn about heavy deps.
    - `rel:` (on any entry) — **this is where the method knows that a request about A also needs C.** `pairs_with` (they go together), `before`/`after` (mandatory order) and `instead_of` (one or the other, not both). Every edge is reciprocal by construction: the schema validator rejects one-way edges, so the relation shows up whichever side the user enters from. As the multi-area orchestrator you are the biggest beneficiary of this — roughly a third of the edges cross areas (count them in the registry when you need the number; don't quote one from memory). When building the dispatch, follow the same order the area agents follow ([rel protocol](../../_shared/rel-protocol.md)): LIST every id the chosen entry's `rel` names — including the ones you don't recognise, which are exactly the point — resolve each id → area via the `ids:` map in `{project-root}/_wizz/_config/registry/index.yaml`, read that area's slice for its `when:`, and then either bring it in or discard it with a stated reason. A target in another area becomes a dispatch to THAT area's agent, and a `before` target sets the ORDER of the plan, not a parallel item. Never deliver only the half the user named when `rel` says the other half is missing: a related capability you never named is one the method lost.
    - `squads:` — advisory panels (run via `wizz-party-mode`). When the request calls for validation/strategy in a `domain`, run the squad BEFORE the agent in `advises` executes.
 

package/src/modules/wizz/agents/wizz-social/SKILL.md

@@ -65,6 +65,7 @@ When the script becomes a video (you route, you don't do the editing yourself; f
 - **Timing** of the narration (word-by-word timestamps for captions and cuts) → `ctc-align`
 - **Draw the screens** (visual scene changes in HTML/CSS, HTML→MP4) → CLI `hyperframes`
 - **Source the B-roll / inserts** (real footage of the fact, person, product, news item or screen the script names) → CLI `get-brolls` (macOS). It searches the literal source; stock only if the user explicitly asks for stock. Ends in a Storyboard the **human** approves — never approve on their behalf
+- **Effects and sound** (which effect and which SFX go where, and where not; ducking, loudness, safe-zone/density/excess/rhythm gates) → skill `wizz-video-effects`; it writes the timeline the assembly reads
 - **Assemble the film** (audio, SFX, captions, frame timing) → **Remotion** (skill `wizz-remotion-best-practices`); never place audio/captions in hyperframes. Scenes arrive following the handoff contract in `_shared/video-pipeline.md` (same fps and size, silent MP4 or transparent WebM)
 - **Edit/cut** the recorded video (cuts, selects, roughcut) → CLI `buttercut` (Apple Silicon only)
 - **Analyze** a reference video (frames + transcription) → CLI `claude-video`

package/src/skills-lib/wizz-remotion-best-practices/rules/sfx.md

@@ -23,4 +23,6 @@ The following sound effects are available:
 - `https://remotion.media/shutter-modern.wav`
 - `https://remotion.media/shutter-old.wav`
 
-For more sound effects, search the internet. A good resource is https://github.com/kapishdima/soundcn/tree/main/assets.
+For ads and Reels, do not pick sounds by hand and do not search the internet: invoke the `wizz-video-effects` skill. It maps narrative events to a licensed SFX catalogue (cleared for paid ads), sets the level against the voice, computes ducking windows and rejects excess. Trending audio from the Instagram or TikTok picker is never cleared for ads.
+
+Outside ads (personal or internal video), https://github.com/kapishdima/soundcn/tree/main/assets is a starting point; check each file's licence before use.

package/src/skills-lib/wizz-router/references/routing-table-flat.md

@@ -55,9 +55,10 @@ Use this table to map skills/CLIs/MCPs directly **outside a Wizz project** (no `
 | **Video with audio, narration, SFX, or synced captions** (film assembly) | `wizz-remotion-best-practices` (Remotion assembles; frame timing). Pipeline rule: HyperFrames draws the mute screens, Remotion assembles the film — don't use hyperframes to position audio/captions (~2.76s drift and CSS leaking between screens in production) | 1 |
 | Draw a video SCREEN/scene in HTML/CSS, mute visual (app mockup, animated chart, title, loop; HTML→MP4) | CLI `hyperframes` (designer registry; `npx skills add heygen-com/hyperframes`) — mute screens only; assembly with audio goes to Remotion (line above) | 2 |
 | Word-by-word timestamps for TTS narration (sync captions/cuts/animation with speech) | `ctc-align` (designer registry; single source of timing, replaces Whisper) | 2 |
+| Effects and sound of a short vertical video (ad or Reels): which effect goes where and when not, which SFX for each event and at what level, ducking, master loudness, safe-zone/density/excess/rhythm gates | `wizz-video-effects` (designer registry; decides the effects, Remotion assembles them) | 2 |
 | **Find B-roll / inserts / cutaways / supporting footage** for a video or Reel (real footage of the fact, person, product, news item or screen the script names; YouTube/Instagram/TikTok/Pexels/Pixabay/Commons/NASA) | CLI `get-brolls` (designer registry; **macOS**, global `skills add` + its own `install.sh`; needs ffmpeg with drawtext, Node 22+, Python 3.11+). Ends in a Storyboard the HUMAN approves — the agent never self-approves. Stock only when the user explicitly asks for stock | 1 |
 | **Edit/cut video** (cuts, selects, roughcut) | CLI `buttercut` (designer registry; **Apple Silicon only**, clone-and-run in the project, heavy deps) | 1 |
-| Generate an AI video/image (Veo/Kling/Wan), UGC / ad-ready style | CLI `fal-video` (designer registry; official `@fal-ai/client`, needs `FAL_KEY` in `.env`). Replaced the old arcads entry: same use case, 50-95% cheaper per video, no heavy clone-and-run | 1 |
+| Generate an AI video/image (Veo/Kling/Wan), UGC / ad-ready style | `wizz-ad-creative` writes the prompt for the user to paste into Flow or another AI tool. No generation API is integrated in the method | 1 |
 | Analyze/understand an existing video (frames + transcription) | CLI `claude-video` (designer registry; `npx skills add bradautomates/claude-video`) | 2 |
 | Narration / voice / TTS / voice cloning for video | CLI `voicebox` (designer registry; local app with MCP endpoint) | 2 |
 | Research components compatible with the project | `wizz-ui-component-curator` (demos, code, and public registries with evidence) | 1 |
@@ -82,7 +83,7 @@ Use this table to map skills/CLIs/MCPs directly **outside a Wizz project** (no `
 | EXECUTE the SEO distribution: publish articles, build backlinks through the Distribb network, connect Search Console, autopublish news | CLI `distribb` (seo registry) — the doing half; the strategy half is the SEO row above | 2 |
 | Competitor comparison, alternatives page, war room | `wizz-competitor-alternatives` | 2 |
 | Content, social media, newsletter, threads | `wizz-content-strategy` + `wizz-social-content` + `wizz-copy-editing` | 2 |
-| Actually PUBLISH/schedule to social networks (30+ integrations), not write it | CLI `postiz` (social registry; needs auth). Separates "generate" (Wizz skills above) from "publish" | 2 |
+| Actually PUBLISH/schedule to social networks (Instagram, TikTok, YouTube, LinkedIn and more), not write it | CLI `buffer` (social registry; needs `BUFFER_API_KEY`; media must be a public HTTPS URL). Separates "generate" (Wizz skills above) from "publish" | 2 |
 | Cold email, B2B outbound, prospecting | `wizz-cold-email` | 2 |
 | Referral, referrals, affiliate program | `wizz-referral-program` | 2 |
 | Sales material, pitch, deck, proposal | `wizz-sales-enablement` | 2 |

package/src/skills-lib/wizz-video-effects/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: wizz-video-effects
+description: Decision engine and gates for the effects and sound of short vertical video (ads and Reels). Decides which effect enters (punch, flash, shake, transition, interrupt), where, with what strength and when it must NOT enter; maps narrative events to a licensed SFX catalogue at a level set against the voice; anchors effects on real speech breaths; computes ducking; and gates the render on safe zone (ad or organic profile), density, excess, rhythm and loudness (-14 LUFS). Use when a narrated ad or Reel needs its effects and SFX decided or checked, when a video "zooms all the time" or "sounds amateur", when checking an ad's safe zone or loudness, or before handing the timeline to Remotion. Triggers - efeitos sonoros do criativo, SFX do Reels, zoom demais, conferir zona segura, LUFS do vídeo. Does not assemble the film (that is Remotion) and does not draw screens (that is HyperFrames).
+---
+
+# wizz-video-effects: which effect, where, and when not
+
+A catalogue of effects is easy. What makes a video look professional is the **refusal**: every effect competes for a budget, every sound answers to an event in the narration, and every gate measures the final file. This skill is the engine that decides; Remotion assembles what it decides.
+
+## Where it sits in the video pipeline
+
+1. Script and narration exist; `ctc-align` gave word-by-word timestamps.
+2. Screens were drawn silent (HyperFrames) or footage was sourced.
+3. **This skill:** events → SFX and levels → effects anchored on breaths → budget → timeline JSON → (render in Remotion) → gates on the final MP4.
+4. Remotion assembles from the timeline JSON. For the `<Audio>` and `<Sequence>` API, invoke the `wizz-remotion-best-practices` skill.
+
+## Hard rules
+
+- **Every effect goes through the budget** (`scripts/budget.py`). Nothing writes an effect straight into the timeline.
+- **When an effect does not fit, switch effect; do not drop the instant.** Punch where the top has headroom, flash where content sits against the safe zone.
+- **The instant comes from a speech breath, never from the clock** (`scripts/fill_breaths.py`).
+- **The key is semantic.** Ask for `verdict`, `price`, `message`, never for `stamp.mp3`. An unknown event is refused with the list of valid ones; a wrong sound is worse than no sound.
+- **Volume is not strength.** Volume is the mix; strength is who wins an instant when two effects compete. Both live in the config.
+- **SFX never carries critical information.** Most feed video plays muted; every claim that matters is also on screen as text.
+- **No canonical number in documentation.** Numbers live in `effects.config.json` and docs cite the key. A number that exists in two places ends in two versions.
+- **Only licensed sound.** The shipped catalogue is Pixabay only, cleared for paid ads when mixed into a work. Trending picker audio from Instagram or TikTok never goes into an ad.
+- **No gate replaces looking.** Extract frames from the final MP4 and look, every time.
+
+## Setup (once per project)
+
+1. Copy `assets/effects.config.template.json` to the project as `effects.config.json`. Set `offer`, frame size, the default `safe_zone_profile` (`ad` or `organic`) and the SFX folder.
+2. Copy `assets/sfx/` to the folder the config points at (for Remotion, under `public/`). Keep `CREDITS.md` with it.
+3. Run `python3 scripts/config.py --config effects.config.json`. An incoherent config fails with the reason; nothing is assumed.
+4. Run `python3 scripts/sound.py --config effects.config.json coverage` for coverage: sounds no event uses, events pointing at missing files.
+5. Run `python3 scripts/normalize_audio.py --config effects.config.json --check` so every SFX sits on the level contract.
+
+Requires Python 3 (stdlib only) and ffmpeg/ffprobe.
+
+## Per piece
+
+1. **Timeline.** Write the piece's timeline JSON ([references/data-contract.md](references/data-contract.md)): `words[]` from ctc-align, `scenes[]`, `elements[]`, and the safe-zone profile (`ad` or `organic`).
+2. **Events to sounds.** List what happens in the narration as semantic events with their times, from the words: a price appears, a verdict lands, a message arrives. Map them with `res = sound.map_requests([(5.4, "verdict"), (7.1, "element_in")], cfg)` from `scripts/sound.py`; it returns the shots (file and `vol` from the config) plus the refusals, with the reason. Write the accepted shots into `sfx[]` with their `event`. Events that trigger an effect (a `verdict` triggers `shake`): pass `sound.effect_candidates(res)` through `budget.select(...)` from `scripts/budget.py` and write the accepted ones into `shakes[]`; no other step writes them.
+3. **Effects on breaths.** `python3 scripts/fill_breaths.py TIMELINE --narration NARRATION.mp3 --visual LAYOUT_RENDER.mp4 --write` anchors punches and flashes on real speech breaths, runs every candidate through the budget, and sets scene transitions and cut sounds by speech pace. Without `--write` it only reports.
+   - `--narration` is required in practice: ctc-align words touch each other (each ends where the next starts), so `words[]` alone yields almost no breaths.
+   - `--visual` must be a silent render **in the piece's final layout**. It decides punch vs flash by how close content sits to the safe-zone edge; measured on full-screen footage, every breath turns into a flash. Content inside a clipped card can take a punch.
+   - Cut sounds are added here, after step 2: if the report lists sounds that would no longer be accepted together, map everything again. `check_excess.py` checks all sounds together and blocks on collisions.
+4. **Ducking.** `python3 scripts/sound.py duck TIMELINE --write` writes `ducking[]`; the Remotion volume callback is in the data contract.
+5. **Before rendering.** `python3 scripts/check_excess.py TIMELINE` (blocks) and `python3 scripts/check_rhythm.py TIMELINE` (warns).
+6. **Render** in Remotion from the timeline: SFX at their `vol`, narration with the ducking callback. `assets/remotion/` holds a reference `EffectsLayer.tsx` that consumes the timeline (copy it into the project). For the Remotion API itself, invoke `wizz-remotion-best-practices`.
+7. **Gate the final MP4.** Footage (an actor take, b-roll) edge to edge fails the safe zone by construction: the gate measures contrast, not text. Put footage in a frame inside the zone over a plain or darkened background. `check_safe_zone.py FINAL.mp4 --timeline TIMELINE` (the piece's profile; run with `--profile` for the other one if the piece also runs there), `measure_density.py FINAL.mp4 --timeline TIMELINE`, `check_loudness.py FINAL.mp4` (prints the ffmpeg command that fixes it when it fails, and warns when that fix will compress; a quiet narration is better raised before the render).
+8. **Look.** Extract frames of the final file, including one of the CTA block, and read them.
+
+Every script takes `--config PATH`; without it, `VIDEO_EFFECTS_CONFIG`, then `./effects.config.json`.
+
+## Gates
+
+| Gate | Blocks? | Why |
+|---|---|---|
+| `check_excess.py` | yes (unless `--warn`) | an effect that always happens stops marking anything |
+| `check_safe_zone.py` | yes | text under the platform UI is text nobody reads |
+| `measure_density.py` | yes | an empty frame loses the scroll |
+| `check_loudness.py` | yes | platforms normalise to about -14 LUFS; louder only distorts |
+| `check_rhythm.py` | **warns only** | its numbers come from weak sources |
+
+Full table, what each gate cannot see, and escape hatches: [references/gates.md](references/gates.md).
+
+## References
+
+| File | Answers |
+|---|---|
+| [references/when-to-use.md](references/when-to-use.md) | **start here.** Each effect with its trigger, refusal, ceiling and conflict |
+| [references/do-not-use.md](references/do-not-use.md) | what was already decided against, and why |
+| [references/audio.md](references/audio.md) | which sound for which event, levels, ducking, loudness |
+| [references/sfx-licensing.md](references/sfx-licensing.md) | what can run in a paid ad vs an organic post, per library |
+| [references/editing-patterns.md](references/editing-patterns.md) | hook, rhythm, CTA, captions, safe zones, organic reach: what has a source and what does not |
+| [references/gates.md](references/gates.md) | what each gate measures and what it misses |
+| [references/data-contract.md](references/data-contract.md) | the timeline JSON the scripts read and write |
+
+## Out of scope
+
+- Assembling the film, captions layout, `<Audio>` API: `wizz-remotion-best-practices`.
+- Drawing screens: HyperFrames.
+- Word timestamps: `ctc-align`.
+- Script, hook wording and CTA wording: the copy or social area.
+- Launch films with music and art direction: `wizz-huashu-design`.