wizz-method 2.17.2 → 2.19.0

package/src/modules/wizz/subagents/wizz-exec-standard.md

@@ -2,7 +2,7 @@
 # Gerado por tools/generate-subagents.mjs a partir de src/modules/wizz/subagents/spec.yaml. Não edite este arquivo direto: edite o spec.yaml e rode `npm run generate:subagents`.
 name: wizz-exec-standard
 description: >-
-  Standard Wizz Method executor for day-to-day implementation. Well-defined small/medium features, bug fixes with a known cause, multi-file edits, tests. Same tier as the recommended session model: dispatch it for isolation or parallel work (1 per file/module, up to 4 at once), not to escalate.
+  Standard Wizz Method executor for day-to-day implementation. Well-defined small/medium features, bug fixes with a known cause, multi-file edits, tests. Same tier as the recommended session model: dispatch it for isolation or parallel work (1 per file/module, up to 4 at once), not to escalate. Size, not just difficulty: work crossing more than one layer (database, backend/worker, app/UI, external automation) or ~8 files is split, one dispatch per layer, each brief with max_calls.
 model: sonnet
 effort: medium
 maxTurns: 80

package/src/modules/wizz/subagents/wizz-exec-strong.md

@@ -2,7 +2,7 @@
 # Gerado por tools/generate-subagents.mjs a partir de src/modules/wizz/subagents/spec.yaml. Não edite este arquivo direto: edite o spec.yaml e rode `npm run generate:subagents`.
 name: wizz-exec-strong
 description: >-
-  Strong Wizz Method executor for hard work. Bugs with no known cause after one investigation cycle, cross-module refactors, schema/auth/payment changes, local technical decisions. The session dispatches it when the work is too hard for the session's own tier. If the work turns out to be ultra hard, it returns ESCALAR with its findings; it never dispatches anything itself.
+  Strong Wizz Method executor for hard work. Bugs with no known cause after one investigation cycle, cross-module refactors, schema/auth/payment changes, local technical decisions. Size, not just difficulty: work crossing more than one layer (database, backend/worker, app/UI, external automation) or ~8 files is split, one dispatch per layer, each brief with max_calls. The session dispatches it when the work is too hard for the session's own tier. If the work turns out to be ultra hard, it returns ESCALAR with its findings; it never dispatches anything itself.
 model: opus
 effort: high
 maxTurns: 120

package/src/skills-lib/_shared/complexity-signal.md

@@ -1,16 +1,15 @@
 # Complexity signal (single source)
 
 # Read by wizz-router (SKILL.md), wizz-maestro (SKILL.md) and wizz-quick-dev
-# (SKILL.md) as the CANONICAL SOURCE of the rule paragraph below. The SKILL.md
-# files do not include it automatically (skills are self-contained folders
-# copied verbatim), so editing here does NOT propagate on its own — whoever
-# edits this paragraph has to replicate the change by hand in the 3 SKILL.md
-# files. `test/test-dispatch-rule-consistency.js` compares the block's text
-# (not just the numbers) against the 3 copies and fails on any divergence of
-# wording, not only of threshold.
+# (SKILL.md) as the CANONICAL SOURCE of the counting rules below. The
+# dispatch-rule and decision-order lines are GENERATED from
+# `dispatch-rule.yaml` (next to this file) into here, the 3 SKILL.md files and
+# the router hook by `tools/generate-dispatch-rule.mjs`: edit the yaml and run
+# `npm run generate:dispatch-rule`, never these lines.
+# `test/test-dispatch-rule-generated.js` fails on any drift.
 # ---
 
-Dispatch rule: IF 2+ areas → maestro, always. OTHERWISE count the 3 remaining factors (multi-step, needs planning, produces a memorable artifact); 2+ factors → maestro. The area clause decides on its own, without summing with anything else.
+Dispatch rule: IF 2+ areas → maestro, always. OTHERWISE count the 3 remaining factors (multi-step, needs planning, produces a memorable artifact); 2+ factors → maestro. The area clause decides on its own, without combining with anything else.
 
 **Decision order — capabilities → required relations → areas → shortcuts.** Match the catalogue entries, inspect their `rel`, and include only capabilities needed for the requested deliverable and not already supplied in the context. Resolve their owning areas before applying ANY one-area shortcut. One artifact can require multiple areas; the word "copy" does not prove that only copy is needed. For full sales-page copy, if either the offer or the conversion structure is missing from the supplied context, include the missing capability: `wizz-offer-forge` for the offer and/or `wizz-page-cro` for conversion structure (growth), alongside `wizz-copywriting` (copy); route to maestro. Do not assume those inputs are ready merely because the user did not mention them. If both are already approved and the request is limited to text, keep copy-only work in copy. An isolated headline or CTA does not require redesigning the whole page. Optional neighbours and separate deliverables do not add areas; `pairs_with` alone never escalates.
 
@@ -34,7 +33,7 @@ Written as bare labels, the 3 factors above were true of almost any request, and
 
 **The counterpart, and this is what is left for the maestro:** a request **of open scope, which the request itself does not delimit** — "how do I improve the signup conversion rate", "the sales page gets plenty of visits and almost nobody buys", "my sales page converts badly, improve it". There the scope has to be discovered before anything is delivered, and discovering scope is the Manager's work. The deciding difference is not the size of the request, it is whether **the request already states what the delivery is**.
 
-**And the counterpart has one exception: a single entry already delimits the scope.** If the whole outcome being asked for fits the `when:` of ONE catalogue entry, and what leaves at the end is that entry's own deliverable — a plan, a recommendation, an audit — then the scope is not open, the catalogue delimited it, and the request goes to that entry's area. "A plan to reduce churn" is `wizz-churn-prevention`; "I want ChatGPT and Perplexity to cite us" is `wizz-ai-seo`; "what to check before going live" is `site-launch-kit`. It stops being the exception the moment delivering the outcome means changing what other areas own: "improve the signup conversion rate" ends up in copy, UI and code, so it comes back to the maestro through the area clause. Ask which single entry would deliver it whole — if it takes two, the scope really is open. (Owner's decision, 2026-09-18.)
+**And the counterpart has one exception: a single entry already delimits the scope.** If the whole outcome being asked for fits the `when:` of ONE catalogue entry, and what leaves at the end is that entry's own deliverable — a plan, a recommendation, an audit — then the scope is not open, the catalogue delimited it, and the request goes to that entry's area. "A plan to reduce churn" is `wizz-churn-prevention`; "I want ChatGPT and Perplexity to cite us" is `wizz-ai-seo`; "what to check before going live" is `wizz-site-launch-kit`. It stops being the exception the moment delivering the outcome means changing what other areas own: "improve the signup conversion rate" ends up in copy, UI and code, so it comes back to the maestro through the area clause. Ask which single entry would deliver it whole — if it takes two, the scope really is open. (Owner's decision, 2026-09-18.)
 
 **Changing the product's code is `dev`, even when the subject is visual.** "Adjust the secondary button's colour", "fix the mobile spacing": the delivery is a commit, so it is the dev area — `designer` decides what the look should be, it does not ship the change. Ask which artifact leaves at the end: a file in the repo → dev; a decision, a spec or a piece of art → the area that owns it. **Exception: new or rebuilt screens.** When the request asks to BUILD screens in code (a new app, page, dashboard or panel, or a whole screen rebuilt in the product), the visual decision has not been made yet, so `designer` comes first and the sequence is design → dev (2 areas → maestro): the designer runs its research gate before any screen is coded. A tweak to an existing screen (a price, a label, a spacing) stays dev, and redesigning a section with no build asked for (a hero, a card) stays designer.
 

package/src/skills-lib/_shared/dispatch-rule.yaml

@@ -0,0 +1,21 @@
+# Fonte única da regra de dispatch (2026-10-15).
+#
+# tools/generate-dispatch-rule.mjs reescreve, a partir daqui, a linha da regra e
+# a linha da ordem de decisão em complexity-signal.md e nas SKILL.md do
+# wizz-router, wizz-maestro e wizz-quick-dev, e a dica curta do hook
+# tools/hooks/wizz-router-enforce.js. Não edite essas linhas nos arquivos:
+# edite aqui e rode `npm run generate:dispatch-rule`. O `--check` roda no
+# `npm test` (test/test-dispatch-rule-generated.js) e falha em qualquer drift.
+#
+# `{maestro}` vira o nome que cada arquivo usa para o maestro (ver `targets`
+# no gerador). O texto renderizado na SKILL.md do router entra no prompt do
+# eval de rota: mudar `rule` ou `decision_order` é mudança de rota e exige a
+# prova de eval (linha de base em worktree, 9 amostras nas duas árvores).
+
+rule: "IF 2+ areas → {maestro}, always. OTHERWISE count the 3 remaining factors (multi-step, needs planning, produces a memorable artifact); 2+ factors → {maestro}. The area clause decides on its own, without combining with anything else."
+
+decision_order: "**Decision order — capabilities → required relations → areas → shortcuts.** Match the catalogue entries, inspect their `rel`, and include only capabilities needed for the requested deliverable and not already supplied in the context. Resolve their owning areas before applying ANY one-area shortcut. One artifact can require multiple areas; the word \"copy\" does not prove that only copy is needed. For full sales-page copy, if either the offer or the conversion structure is missing from the supplied context, include the missing capability: `wizz-offer-forge` for the offer and/or `wizz-page-cro` for conversion structure (growth), alongside `wizz-copywriting` (copy); route to maestro. Do not assume those inputs are ready merely because the user did not mention them. If both are already approved and the request is limited to text, keep copy-only work in copy. An isolated headline or CTA does not require redesigning the whole page. Optional neighbours and separate deliverables do not add areas; `pairs_with` alone never escalates."
+
+# Paráfrase curta em PT-BR injetada pelo hook em projeto Wizz (a cada prompt,
+# então fica curta de propósito).
+hook_hint: "🎛️ Wizz: NÃO invoque wizz-router. Capacidades → rel necessário à entrega → áreas → atalhos. 2+ áreas → `wizz-maestro`. 1 área: 2+ fatores (multi-passo, planejar, artefato memorável) → `wizz-maestro`; senão → Skill da área. Auth/pagamento/permissão/migração → maestro. Personas são skills, não subagent_type; Agent usa tipos disponíveis wizz-exec-*; difícil → wizz-exec-strong (ESCALAR → ultra)."

package/src/skills-lib/{cerebro → wizz-cerebro}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: cerebro
+name: wizz-cerebro
 description: >
   Persistent memory system across AI sessions. Use this skill whenever the user types
   /iniciar, /salvar, /ver, /dia, /dump, /decisao, /conteudo, /prospect or /memoria. Also activate when the

package/src/skills-lib/{ctc-align → wizz-ctc-align}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ctc-align
+name: wizz-ctc-align
 description: Reliable word-by-word timestamps for TTS narration via forced alignment (ctc-forced-aligner + anchoring on real silences). ALWAYS use before setting caption timing, scene cuts, animation, or any speech-synchronized element in any video (HyperFrames or other editor). Replaces Whisper as the timing source when the narration script text is known. Triggers - sincronizar legenda, timing de cena, alinhar áudio e texto, palavra a palavra, forced alignment, legenda karaokê, corrigir sync de vídeo. Use when the exact narration script is known and you need to decide caption timing, scene cuts, or speech-synchronized animation.
 ---
 

package/src/skills-lib/{enhance-prompt → wizz-enhance-prompt}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: enhance-prompt
+name: wizz-enhance-prompt
 description: Transforms vague UI ideas into polished, Stitch-optimized prompts. Enhances specificity, adds UI/UX keywords, injects design system context, and structures output for better generation results. Use when the user wants to polish a UI prompt before sending it to Stitch, improve a prompt that produced poor results, or turn a vague UI idea into a structured, design-system-aware prompt.
 allowed-tools:
   - "Read"

package/src/skills-lib/{find-skills → wizz-find-skills}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: find-skills
+name: wizz-find-skills
 description: Helps users discover and install agent skills OR MCP servers when they ask questions like "how do I do X", "find a skill for X", "adicione essa skill", "adicione esse MCP", "is there a skill/mcp that can...", or express interest in extending capabilities. Use when the user is looking for functionality that might exist as an installable skill or MCP server.
 ---
 

package/src/skills-lib/wizz-hook-extractor/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergey Bulaev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/skills-lib/wizz-hook-extractor/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: wizz-hook-extractor
+description: Reverse-engineers the hook of one viral Instagram Reel, carousel or post and hands back a mould ready to fill with the user's own topic. Reads the post itself from the link (caption, metrics, first 3 seconds, local transcription), classifies the hook with the Viral Script Blueprint types (Tipo 01 to 07) plus the post shape, breaks down hook, body and close, names the goal the original chased and why it worked, points the editing style from the wizz-video-styles catalogue, and lists what not to copy. Use when someone shares a viral post and wants to know why it worked or wants to do one like it. Triggers - por que esse reel viralizou, o que tem de bom nesse post, quero fazer um igual a esse, destrincha esse carrossel, extrai o gancho desse vídeo. Does not write the user's own script from scratch (that is wizz-social-content and the Blueprint) and does not study a whole niche (that is the reverse-engineering reference of wizz-social-content).
+---
+
+# wizz-hook-extractor: why that post worked, as a mould
+
+One post in, one teardown out: the hook classified the way the Method already numbers hooks, the structure around it, the goal, and a mould with `{slots}` that drops into a script without rework.
+
+All text delivered to the user is Brazilian Portuguese with "você" (never "tu/teu"), and no em dash in anything a third party reads.
+
+## Inputs
+
+- A link (`instagram.com/reel/...`, `/p/...`, `/tv/...`). Preferred: the skill reads it.
+- Or, when reading is impossible: a screenshot, or the caption plus the text on the slides, or a description of the Reel's first 3 seconds.
+- The user's topic (or project), to aim the mould. If missing, ask once, in the same message as anything else.
+
+## Steps
+
+1. **Read the post yourself.** Run `scripts/read-post.sh <url> <out_dir>` (out_dir under the project's `_wizz-output/`). It writes `post.json` (surface, caption, author, likes, comments, views), and for a Reel `head.png` (first 3 s, 6 frames), `sheet.png` (whole Reel) and `transcript.json` (first 10 s, local Whisper through `npx hyperframes transcribe`, no API key). **Open the images**: the hook of a Reel is usually the text on the first frame. When `post.json` says `speech: suspeita` or `sem fala`, the transcript is Whisper inventing words over music: ignore it and read the hook from the frames.
+   - Exit 3 = Instagram asked for a login. Ask the user, once, whether to use their own logged-in browser for this read (`WIZZ_IG_COOKIES_BROWSER=<browser>`); never do it without that OK. If they decline, ask for a screenshot or the pasted text.
+   - A carousel comes back with the slide count only: capture the slides with `wizz-agent-browser` (one screenshot per slide) or ask for them.
+2. **Classify the hook** with [references/formulas.md](references/formulas.md): the Blueprint type (Tipo 01 to 07, or "fora dos 7") with a confidence from 0 to 1, and the post shape. When two fit, give both with their scores; the tiebreaker is the goal and the surface.
+3. **Break down the structure.** Hook (first ~125 characters of the caption, slide 1, or the first 3 s), body (role of each slide, or the order of the Reel's beats with timestamps from the transcript), close (what earns the save, send, comment or follow).
+4. **Goal and why it worked.** One goal (saves, shares, comments, follows) and two or three reasons tied to what is on the post, not generic psychology. Metrics from `post.json` back the claim when present (comments far above the usual ratio = a comment hook).
+5. **Editing style (Reels).** Compare `sheet.png` with the cards of `wizz-video-styles` and name the closest style. That is what keeps the hook and the edit in one delivery.
+6. **Mould.** The shape's skeleton from formulas.md, slots renamed to the user's topic. For a Reel, write it in the `wizz-social` script format (`[HOOK · Tipo NN]`, `[TUTORIAL]`, `[RESULTADO VISUAL]`, `[CTA triplo]`) so it pastes into a script. For a carousel, slide by slide.
+7. **What not to copy.** Formulas.md section 5, applied to this post.
+
+## Delivery
+
+```
+🔎 POST LIDO: superfície · autor · métricas (curtidas, comentários, views) · como foi lido (link / login / print)
+🎣 GANCHO: Tipo NN · nome (0,x) [+ 2ª opção] · formato: {forma do post}
+🧱 ESTRUTURA: gancho / corpo / fechamento
+🎯 OBJETIVO: salvar | enviar | comentar | seguir · por que funcionou (2 a 3 motivos ligados ao post)
+🎬 ESTILO DE EDIÇÃO: {estilo do wizz-video-styles} (Reels)
+🧩 MOLDE PRO SEU TEMA: {molde com slots}
+⚠️ NÃO COPIAR: {lista}
+```
+
+Worked examples: [references/examples.md](references/examples.md).
+
+## Hand-off
+
+- Turning the mould into a full Reel script: `wizz-social` (RT command, Blueprint) or `wizz-social-content` for a post.
+- The carousel slides themselves: `wizz-canvas-design`.
+- The edit of the Reel: `wizz-video-styles` with the style named in step 5.
+- Text that needs to sound less like AI before publishing: `wizz-humanizer`.
+
+## Hard rules
+
+- Never invent a metric or a number for the mould; a slot stays a slot.
+- Never log in on the user's behalf, and never store cookies or credentials. The browser session is theirs and is used only after their OK, for that read.
+- Delete downloaded media after reading (the script does); keep only the frames, the transcript and `post.json`.
+- One post per teardown. Studying a whole profile or niche is the reverse-engineering reference of `wizz-social-content`.

package/src/skills-lib/wizz-hook-extractor/references/examples.md

@@ -0,0 +1,59 @@
+# Worked teardowns
+
+Three teardowns in the delivery format of [SKILL.md](../SKILL.md). The posts are illustrative, not real.
+
+## Legenda (single image)
+
+**Read:** caption starts "Apaguei 4.000 dos meus 6.000 inscritos da newsletter e a taxa de abertura dobrou."
+
+- **Gancho:** Tipo 03 · O Comando Provocador (0,7), as a contrary action; second: Tipo 01 · A Façanha Pessoal (0,6), pulled by the exact numbers. Shape: Verdade contrária.
+- **Superfície:** single image; the whole idea fits in the first 125 characters.
+- **Estrutura:** hook = the counter-move with two real numbers, no setup. Body = one reason. Close = a "manda pra quem..." prompt.
+- **Objetivo:** shares ("viu, eu falei").
+- **Por que funcionou:** a defensible counter-move plus hard numbers is screenshot-ready; the numbers pre-empt the "prova" comment.
+- **Molde:**
+  ```
+  Eu {ação contrária com número real} e {resultado melhor e inesperado}.
+
+  {a razão em uma linha}.
+
+  {pedido de envio ou de salvar}.
+  ```
+- **Não copiar:** nothing in the hook; confirm the numbers are real before reusing.
+
+## Carrossel (7 slides)
+
+**Read:** slide 1 "5 erros de precificação que estão te fazendo cobrar 40% a menos (o 4º quase ninguém percebe)"; slides 2 to 6 one error each; slide 7 the list on one slide + "salva".
+
+- **Gancho:** Tipo 05 · A Lista Urgente (0,9). Shape: Lista.
+- **Superfície:** carousel; one item per slide earns the save.
+- **Estrutura:** slide 1 = promise + named loss + open loop ("o 4º"). Slides 2 to 6 = one error, one example. Slide 7 = recap, single ask.
+- **Objetivo:** saves.
+- **Por que funcionou:** a specific loss (40%) raises the stakes; the open loop pulls the swipe to slide 5.
+- **Molde:**
+  ```
+  Slide 1: {N} erros de {tema} que estão te fazendo {perda com número} (o {k}º quase ninguém percebe)
+  Slides 2..N+1: erro, por que custa, o que fazer no lugar.
+  Último: a lista num slide só + "salva pra revisar antes de {momento}".
+  ```
+- **Estilo de edição:** static carousel, no video: hand the slides to `wizz-canvas-design`.
+- **Não copiar:** if any slide has 3 lines of text where 1 fits, cut it.
+
+## Reel (32 s, read with scripts/read-post.sh)
+
+**Read:** head.png shows on-screen text "Você está postando Reels no pior horário possível"; transcript starts "Aqui está quando o seu público está online de verdade"; sheet.png shows a talking head with captions 2 to 3 words at a time, cutting to phone screenshots.
+
+- **Gancho:** Tipo 06 · A Revelação de Erro (0,8). Shape: Quebra de padrão.
+- **Superfície:** Reel; text on the first frame gets silent viewers.
+- **Estrutura:** 0 to 3 s = mistake named on screen + first line goes straight to the fix. 3 to 25 s = three steps, each with a screenshot. 25 to 32 s = result on screen, "salva", follow.
+- **Objetivo:** shares (people send it to whoever manages their account).
+- **Estilo de edição (wizz-video-styles):** talking-head-cards (face + full-screen screenshots), captions as in talking-head-legenda.
+- **Molde (pronto pro roteiro):**
+  ```
+  [HOOK · Tipo 06] Texto na tela: "Você está {erro comum} {consequência}."
+  1ª fala: "Aqui está {a correção} de verdade."
+  [TUTORIAL] passo 1 → print / passo 2 → print / passo 3 → print
+  [RESULTADO VISUAL] → mostrar {métrica antes e depois}
+  [CTA triplo]
+  ```
+- **Não copiar:** 25 hashtags in the caption.

package/src/skills-lib/wizz-hook-extractor/references/formulas.md

@@ -0,0 +1,136 @@
+# Hook formulas and post shapes, mapped to the Blueprint types
+
+The Method already numbers hooks: the **7 types** of the Viral Script Blueprint (`wizz-social` agent, `knowledge/blueprint-roteiro-viral.md`, section 1). This skill classifies the hook with **those** types, so an extracted mould drops straight into a script. What the Blueprint does not cover is the **shape of the post** around the hook (a caption cut at the "mais" fold, a carousel slide by slide, a Reel's first seconds). The 10 shapes below cover that; they are adapted from sergebulaev/instagram-skills (MIT, credited in `THIRD-PARTY-NOTICES.md`).
+
+## 1. Hook → Blueprint type
+
+| Type | Name | How to spot it in the first line / slide 1 / first 3 s |
+|---|---|---|
+| Tipo 01 | A Façanha Pessoal | past tense + an absurd or precise result of the author ("eu fiz X em 47 minutos") |
+| Tipo 02 | A Sentença de Morte | a tool, job or company declared dead ("X acabou de matar Y") |
+| Tipo 03 | O Comando Provocador | an order that sounds radical ("pode demitir...", "para de postar...") |
+| Tipo 04 | A Pergunta de Resultado | a question about a specific result the viewer wants |
+| Tipo 05 | A Lista Urgente | a number + things/errors/prompts ("5 erros que...") |
+| Tipo 06 | A Revelação de Erro | points at something the viewer does wrong, with a cost ("se você faz X, está perdendo Y") |
+| Tipo 07 | O Breaking News | a fresh piece of news as a headline, with "a partir de hoje" |
+| fora dos 7 | identificação / confissão | see the equivalence table: two Instagram shapes have no Blueprint type |
+
+## 2. Shape → Blueprint type (equivalence)
+
+The 10 shapes do not map 1 to 1. This table is the single place where they meet; never number hooks with IG1..IG10 in a delivery, use the Tipo and the shape name.
+
+| Shape (surface) | Closest Blueprint type | Note |
+|---|---|---|
+| Resultado com número (legenda) | Tipo 01 | Tipo 01 with an odd, measured number |
+| Verdade contrária (legenda) | Tipo 03, or Tipo 02 when something is declared dead | |
+| Identificação (legenda) | **fora dos 7** (closest: Tipo 06 without the guilt) | a shared moment, no number, no lesson |
+| Confissão curta (legenda ou Reel) | **fora dos 7** (closest: Tipo 01 told from the failure) | a real cost, then the lesson |
+| Lista (carrossel) | Tipo 05 | |
+| Antes e depois (carrossel) | Tipo 01 | Blueprint phase 04 "resultado visual" moved to slide 1 |
+| Mito e verdade (carrossel) | Tipo 06 | |
+| Framework (carrossel) | Tipo 01 + the Blueprint's "Revelação de Sistema" structure | |
+| Quebra de padrão (Reel) | Tipo 02, 03 or 07: the shape is how it is delivered, the type is what is said | |
+| "Como eu fiz" (Reel) | Tipo 01 + the Blueprint's "Tutorial Bombástico" structure | |
+
+Tipo 04 and Tipo 07 have no Instagram shape of their own: they live in any surface.
+
+## 3. The 10 shapes
+
+Moulds use `{slots}` and Brazilian Portuguese with "você". Goal = what the shape tends to earn.
+
+### Legenda (single image or any post): the first ~125 characters, before "mais"
+
+**Resultado com número** · saves
+```
+{resultado com número exato} em {prazo}.
+
+O que eu mudei está aqui embaixo.
+```
+Odd numbers (47 minutos, R$ 873) read as measured. Never invent the number.
+
+**Verdade contrária** · shares
+```
+{conselho que todo mundo repete} está errado.
+
+{o que funciona, dito sem rodeio}.
+```
+Only claims the author would defend in the comments.
+
+**Identificação** · comments
+```
+{um momento específico que todo mundo do nicho conhece, sem contexto}
+```
+Specific beats generic ("abrir o Canva pra fazer uma arte rápida e fechar 90 minutos depois").
+
+**Confissão curta** · comments and follows
+```
+{marcador de tempo}: {o que aconteceu, incluindo a parte feia}.
+
+{a linha de sentido que faz valer a leitura}.
+```
+It has to be true.
+
+### Carrossel: slide 1 promises, the last slide pays
+
+**Lista** · saves
+```
+Slide 1: {N} {coisas} que {resultado grande e específico}. (quase todo mundo erra a {k})
+Slides 2..N-1: um item por slide, com exemplo concreto.
+Último: resumo em uma linha + "salva pra usar depois".
+```
+
+**Antes e depois** · saves and follows
+```
+Slide 1: {o depois, com número ou imagem forte}.
+Slide 2: de onde começou (o antes).
+Slides 3..N-1: os passos, um por slide.
+Último: "segue pra ver o sistema completo de {tema}" + pedido de salvar.
+```
+
+**Mito e verdade** · shares
+```
+Slide 1: {N} mitos de {tema} que estão te custando {perda específica}.
+Slides 2..N-1: "Mito: {crença}." / "Verdade: {o que funciona}."
+Último: a virada em uma linha + "manda pra quem ainda acredita no 1".
+```
+Never invent the myth to knock it down.
+
+**Framework** · saves
+```
+Slide 1: o {nome} que eu uso pra {resultado}.
+Slides 2..N-1: uma parte por slide, com o porquê.
+Último: o framework inteiro num slide só + pedido de salvar.
+```
+
+### Reel: the first 1 to 3 seconds (image + text on screen + first spoken line)
+
+**Quebra de padrão** · shares
+```
+Texto do 1º quadro: {afirmação ou pergunta que faz passar reto parecer perda}.
+1ª fala: {direto ao ponto, sem "e aí, pessoal"}.
+```
+
+**"Como eu fiz"** · saves
+```
+Texto do 1º quadro: como eu {resultado com número} em {prazo}.
+Corpo: passo 1, 2, 3 com rótulo na tela, cortes rápidos, sem enchimento.
+Fim: "salva pra fazer junto" + resumo de uma linha na tela.
+```
+
+## 4. Goal of the original
+
+| Close / structure | Goal |
+|---|---|
+| "salva", list, framework, how-to | saves |
+| "manda pra...", contrary take, myth | shares |
+| identification, question, confession | comments |
+| proof of transformation, "segue pra..." | follows |
+
+## 5. What not to copy from a viral post
+
+- Dashes gluing clauses together, and in text a third party reads, no em dash at all (Wizz rule).
+- An AI-vocabulary cluster ("alavancar", "fundamentalmente", "eleve", "potencialize") in one paragraph.
+- 20 to 30 hashtags at the top of the caption.
+- Engagement bait ("comenta SIM", "marca 3 amigos"): Instagram pushes it down.
+- A hook that only makes sense after the "mais" fold.
+- Images and videos mixed in one carousel.

package/src/skills-lib/wizz-hook-extractor/scripts/read-post.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# Reads one public Instagram post so its hook can be studied without the user pasting anything.
+# Usage: read-post.sh <instagram_url> <out_dir>
+#   → <out_dir>/post.json (caption, author, metrics, surface), head.png (first 3 s, Reels),
+#     sheet.png (whole Reel), transcript.json (first 10 s of speech, local Whisper).
+# Exit 0 = read; 3 = Instagram asked for a login (see the message); 2 = usage or missing tool.
+# Login is never automatic: set WIZZ_IG_COOKIES_BROWSER=<browser> (chrome, opera, safari...) only
+# after the user agreed to use their own logged-in browser session for this read.
+set -euo pipefail
+[ $# -eq 2 ] || { echo "uso: read-post.sh <url do instagram> <pasta de saída>" >&2; exit 2; }
+url="$1"; out="$2"
+[[ "$url" =~ ^https://(www\.)?instagram\.com/([A-Za-z0-9._]+/)?(reel|reels|p|tv)/[A-Za-z0-9_-]+/?(\?.*)?$ ]] \
+  || { echo "url inválida (esperado instagram.com/reel/..., /p/... ou /tv/...): $url" >&2; exit 2; }
+for bin in yt-dlp ffmpeg node; do command -v "$bin" >/dev/null || { echo "falta $bin no PATH" >&2; exit 2; }; done
+mkdir -p "$out"; cd "$out"
+trap 'rm -f ./media.* ./head.wav ./raw.json.part' EXIT
+
+auth=()
+[ -n "${WIZZ_IG_COOKIES_BROWSER:-}" ] && auth=(--cookies-from-browser "$WIZZ_IG_COOKIES_BROWSER")
+if ! yt-dlp -q --no-warnings --socket-timeout 20 ${auth[@]+"${auth[@]}"} -J "$url" > raw.json 2> err.txt; then
+  if grep -qiE "login|cookies|empty media|not available" err.txt; then
+    echo "O Instagram pediu login para este post. Opções: (1) com o OK do usuário, rodar de novo com WIZZ_IG_COOKIES_BROWSER=<navegador logado>; (2) print do post; (3) colar a legenda e o texto da tela." >&2
+    exit 3
+  fi
+  cat err.txt >&2; exit 1
+fi
+
+# Caption, author and metrics; a carousel comes as a playlist of entries.
+node - <<'JS'
+const fs = require('node:fs');
+const raw = JSON.parse(fs.readFileSync('raw.json', 'utf8'));
+const entries = raw._type === 'playlist' ? raw.entries ?? [] : [raw];
+const videos = entries.filter((e) => e && (e.vcodec && e.vcodec !== 'none' || e.duration));
+const surface = raw._type === 'playlist' ? 'carrossel' : videos.length ? 'reel' : 'imagem';
+const pick = (k) => raw[k] ?? entries[0]?.[k] ?? null;
+fs.writeFileSync('post.json', JSON.stringify({
+  url: raw.webpage_url ?? raw.original_url,
+  surface,
+  slides: raw._type === 'playlist' ? entries.length : 1,
+  author: pick('uploader') ?? pick('channel'),
+  handle: pick('channel') ?? pick('uploader_id'),
+  date: pick('upload_date'),
+  caption: pick('description') ?? '',
+  likes: pick('like_count'),
+  comments: pick('comment_count'),
+  views: pick('view_count'),
+  duration_s: pick('duration'),
+}, null, 1));
+JS
+rm -f raw.json err.txt
+
+surface=$(node -p "require('./post.json').surface")
+if [ "$surface" = "reel" ]; then
+  yt-dlp -q --no-warnings --socket-timeout 20 ${auth[@]+"${auth[@]}"} -o "media.%(ext)s" "$url"
+  media=$(ls media.* | head -1)
+  ffmpeg -loglevel error -y -t 3 -i "$media" -vf "fps=2,scale=270:-1,tile=6x1" -frames:v 1 head.png
+  d=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$media")
+  step=$(node -p "Math.max(1, $d / 8)")
+  ffmpeg -loglevel error -y -i "$media" -vf "fps=1/$step,scale=270:-1,tile=8x1" -frames:v 1 sheet.png
+  if ffmpeg -loglevel error -y -t 10 -i "$media" -vn -ac 1 -ar 16000 head.wav 2>/dev/null; then
+    # Local Whisper through the HyperFrames CLI: no API key. Multilingual model, Portuguese by default.
+    npx -y hyperframes transcribe head.wav -d . -m small -l "${WIZZ_IG_LANG:-pt}" --json >/dev/null 2>transcribe.log \
+      || echo "transcrição falhou (ver transcribe.log); siga pelos quadros e pela legenda" >&2
+    # Whisper invents words over music with no speech ("Thank you for watching", "Legendas pela
+    # comunidade"): stretched words or too few words per second mean there was no real speech.
+    [ -f transcript.json ] && node - <<'JS'
+const fs = require('node:fs');
+const raw = JSON.parse(fs.readFileSync('transcript.json', 'utf8'));
+const words = Array.isArray(raw) ? raw : raw.words ?? [];
+const span = words.length ? words.at(-1).end - words[0].start : 0;
+const stretched = words.some((w) => w.end - w.start > 1.2);
+const slow = span > 0 && words.length / span < 0.8;
+const canned = /thank you for watching|obrigad[oa] por assistir|legendas? pela comunidade|inscreva-se/i.test(words.map((w) => w.text).join(' '));
+const post = JSON.parse(fs.readFileSync('post.json', 'utf8'));
+post.speech = words.length === 0 ? 'sem fala' : stretched || slow || canned ? 'suspeita' : 'ok';
+fs.writeFileSync('post.json', JSON.stringify(post, null, 1));
+if (post.speech !== 'ok') console.error(`transcrição ${post.speech}: provavelmente música sem fala; o gancho está nos quadros e no texto da tela`);
+JS
+  else
+    echo "Reel sem áudio: o gancho está só no texto da tela (head.png)" >&2
+  fi
+fi
+echo "ok: $(pwd)/post.json ($surface)"

package/src/skills-lib/wizz-huashu-design/references/sfx-library.md

@@ -12,7 +12,7 @@
 > 仓库和已下载的缓存中）。用某个 SFX 前先 `ls assets/sfx/<category>/` 确认文件存在；
 > 缺失就跑 `npx --yes wizz-method fetch-assets --bundle huashu-audio --dest
 > assets`（路径相对本 skill 根目录）。离线时手动下载
-> `npx wizz-method fetch-assets --bundle huashu-audio` (2 partes em `https://wizz-assets.junior-aec.workers.dev/huashu-audio-1.tar.gz` e `.../huashu-audio-2.tar.gz`)
+> `npx wizz-method fetch-assets --bundle huashu-audio` (2 partes em `https://assets.wizzcomms.com/huashu-audio-1.tar.gz` e `.../huashu-audio-2.tar.gz`)
 > 解压到 `assets/`，能力不受影响，只是首次用要等下载。
 
 ---

package/src/skills-lib/wizz-huashu-design/scripts/add-music.sh

@@ -83,7 +83,7 @@ if [ ! -f "$MUSIC" ]; then
   echo "✗ Music not found: $MUSIC" >&2
   echo "  Available moods: $(ls "$ASSETS_DIR" 2>/dev/null | grep -E '^bgm-.*\.mp3$' | sed 's/^bgm-//;s/\.mp3$//' | tr '\n' ' ')" >&2
   echo "  Offline or npx failed? Download manually:" >&2
-  echo "    npx wizz-method fetch-assets --bundle huashu-audio  (https://wizz-assets.junior-aec.workers.dev/huashu-audio-{1,2}.tar.gz)" >&2
+  echo "    npx wizz-method fetch-assets --bundle huashu-audio  (https://assets.wizzcomms.com/huashu-audio-{1,2}.tar.gz)" >&2
   echo "  and extract it into: $ASSETS_DIR" >&2
   exit 1
 fi

package/src/skills-lib/wizz-huashu-design/scripts/html2pptx.js

@@ -913,43 +913,8 @@ function writeElement(slide, pres, el) {
   }
 }
 
-module.exports = async function html2pptx(htmlFile, pres, options) {
-  options = options || {};
-  const absHtmlPath = path.isAbsolute(htmlFile) ? htmlFile : path.resolve(process.cwd(), htmlFile);
-  const tmpDir = options.tmpDir || process.env.TMPDIR || '/tmp';
-
-  function finalizeError(rawMessage) {
-    let message = rawMessage;
-    if (!message.startsWith(htmlFile)) {
-      message = `${htmlFile}: ${message}`;
-    }
-    return new Error(message);
-  }
-
-  let browser;
-  let extraction;
-  try {
-    const launchOptions = { env: Object.assign({}, process.env, { TMPDIR: tmpDir }) };
-    if (process.platform === 'darwin') launchOptions.channel = 'chrome';
-    browser = await chromium.launch(launchOptions);
-    const page = await browser.newPage();
-    await page.goto('file://' + absHtmlPath);
-
-    const initialBodySize = await page.evaluate(() => {
-      const cs = getComputedStyle(document.body);
-      return { width: parseFloat(cs.width), height: parseFloat(cs.height) };
-    });
-    await page.setViewportSize({
-      width: Math.max(1, Math.round(initialBodySize.width)),
-      height: Math.max(1, Math.round(initialBodySize.height)),
-    });
-
-    extraction = await page.evaluate(extractPageDataInBrowser);
-  } finally {
-    if (browser) await browser.close();
-  }
-
-  // ---- 整页级校验（第 5 节），和提取阶段收集到的错误合并 ----
+// 整页级校验（第 5 节）：和提取阶段收集到的错误合并，返回错误文案数组。纯函数，不碰浏览器。
+function validatePage(extraction, pres) {
   const errors = extraction.errors.slice();
 
   const widthOverflowPx = Math.max(0, extraction.body.scrollWidth - extraction.body.width - 1);
@@ -989,6 +954,46 @@ module.exports = async function html2pptx(htmlFile, pres, options) {
       }
     }
   }
+  return errors;
+}
+
+module.exports = async function html2pptx(htmlFile, pres, options) {
+  options = options || {};
+  const absHtmlPath = path.isAbsolute(htmlFile) ? htmlFile : path.resolve(process.cwd(), htmlFile);
+  const tmpDir = options.tmpDir || process.env.TMPDIR || '/tmp';
+
+  function finalizeError(rawMessage) {
+    let message = rawMessage;
+    if (!message.startsWith(htmlFile)) {
+      message = `${htmlFile}: ${message}`;
+    }
+    return new Error(message);
+  }
+
+  let browser;
+  let extraction;
+  try {
+    const launchOptions = { env: Object.assign({}, process.env, { TMPDIR: tmpDir }) };
+    if (process.platform === 'darwin') launchOptions.channel = 'chrome';
+    browser = await chromium.launch(launchOptions);
+    const page = await browser.newPage();
+    await page.goto('file://' + absHtmlPath);
+
+    const initialBodySize = await page.evaluate(() => {
+      const cs = getComputedStyle(document.body);
+      return { width: parseFloat(cs.width), height: parseFloat(cs.height) };
+    });
+    await page.setViewportSize({
+      width: Math.max(1, Math.round(initialBodySize.width)),
+      height: Math.max(1, Math.round(initialBodySize.height)),
+    });
+
+    extraction = await page.evaluate(extractPageDataInBrowser);
+  } finally {
+    if (browser) await browser.close();
+  }
+
+  const errors = validatePage(extraction, pres);
 
   if (errors.length > 0) {
     let message;
@@ -1017,3 +1022,6 @@ module.exports = async function html2pptx(htmlFile, pres, options) {
 
   return { slide, placeholders: extraction.placeholders };
 };
+
+// Expostos só para teste (funções puras, sem browser).
+module.exports._internals = { toPt, toIn, stripFileProtocol, previewTextOf, writeElement, validatePage };

package/src/skills-lib/wizz-huashu-design/scripts/mix-voiceover.sh

@@ -80,7 +80,7 @@ if [ -n "$BGM" ] && [ ! -f "$BGM" ]; then
   echo "✗ BGM 文件不存在: $BGM" >&2
   echo "  可用 mood: $(ls "$ASSETS_DIR" 2>/dev/null | grep -E '^bgm-.*\.mp3$' | sed 's/^bgm-//;s/\.mp3$//' | tr '\n' ' ')" >&2
   echo "  离线，或 npx 失败？手动下载：" >&2
-  echo "    npx wizz-method fetch-assets --bundle huashu-audio  (https://wizz-assets.junior-aec.workers.dev/huashu-audio-{1,2}.tar.gz)" >&2
+  echo "    npx wizz-method fetch-assets --bundle huashu-audio  (https://assets.wizzcomms.com/huashu-audio-{1,2}.tar.gz)" >&2
   echo "  解压到：$ASSETS_DIR" >&2
   exit 1
 fi

package/src/skills-lib/wizz-huashu-design/scripts/narrate-pipeline.mjs

@@ -308,8 +308,14 @@ async function main() {
   console.error(`  cue 数:    ${totalCues}`);
 }
 
-main().catch((err) => {
-  console.error(`narrate-pipeline 失败：${err.message}`);
-  console.error(err.stack);
-  process.exit(1);
-});
+// Só executa quando chamado como script; importar o módulo (testes) não dispara o pipeline.
+const isMain = process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  main().catch((err) => {
+    console.error(`narrate-pipeline 失败：${err.message}`);
+    console.error(err.stack);
+    process.exit(1);
+  });
+}
+
+export { parseArgs, parseScript, splitByCues };