wizz-method 2.17.1 → 2.18.0

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-ig-profile-optimizer/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-ig-profile-optimizer/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: wizz-ig-profile-optimizer
+description: Audits and rewrites an Instagram profile so a visitor decides to follow. Captures the public profile by the @ (photo, NAME field, @, bio, link, first grid rows), scores the nine parts (photo, NAME, @, bio, link, category, highlights, first nine of the grid, pinned posts) against the profile's goal (grow, sell, land clients, authority), and delivers a scorecard, fixes ranked by impact, before and after rewrites inside Instagram's limits (bio 150, NAME 30), a highlights plan and the pins chosen by real metrics when Buffer is connected. Use when someone asks to review, fix or optimise an Instagram profile or bio. Triggers - arruma minha bio, revisa meu perfil do instagram, o que colocar nos destaques, quais posts fixar, meu perfil não converte seguidor. Does not write captions or scripts (that is wizz-social-content) and does not design the highlight covers (that is wizz-canvas-design).
+---
+
+# wizz-ig-profile-optimizer: the header that earns the follow
+
+The follow decision happens on the header and the first rows of the grid: photo, NAME, bio, link, then the grid at a glance. This skill reads that as a stranger would, scores it, and rewrites what fails.
+
+All text delivered is Brazilian Portuguese with "você", and no em dash in anything public (bio, NAME, highlight names, pinned captions).
+
+## Inputs
+
+- The @ (preferred), or a screenshot of the header and the first grid rows.
+- The goal of the profile: **crescer**, **vender**, **conseguir cliente** or **autoridade**. It changes the link, the bio's last line and the pins. Ask once if it is not clear.
+
+## Steps
+
+1. **Read the profile.** `scripts/capture-profile.sh <@> <out_dir>` (out_dir under `_wizz-output/`) saves `profile.png` and `profile.json` (NAME, bio and link as text, follower and post counts). **Open the image.** Logged out, Instagram may hide highlights, the category label and the pin marks: ask for a screenshot of those parts instead of guessing them.
+2. **Pull what the Method already knows**, before judging:
+   - Positioning, audience and tone from the project's Cérebro (`/cerebro ver`).
+   - Highlights already made in the project (for example a `posts/highlights/` folder).
+   - The offer from `wizz-offer-forge`, when one exists: the link and one pin depend on it.
+   - Real performance: with Buffer connected, `get_aggregated_post_metrics` and the post list give the best posts by saves, shares and reach. Without it, ask which posts did best; never pick pins by guess.
+3. **Score the nine parts** (table below): passa / ajustar / reprova, one line of reason each.
+4. **Rewrite what fails**, in order of impact: NAME, bio, pins first.
+   - **NAME** = name + the word people type in search, up to 30 characters ("Ana Souza | Nutrição"). The NAME field is what Instagram search indexes, not the @.
+   - **Bio** up to 150 = who it helps + what it posts about + one proof or specific. Lead with what the follower gets, not the job title. One anchor emoji at most; line breaks are fine.
+   - **Link**: one, matched to the goal (offer, booking, newsletter); a link hub only when several are really needed.
+   - **Category** (business or creator account): one label that reinforces the bio.
+   - **Highlights**: 4 to 6, left to right in the order of the visitor's next question (Comece aqui, Resultados, Oferta, Dúvidas, Sobre), names short enough to show whole, covers in one style.
+   - **First nine**: judged as a set (consistent look, readable at a glance, range without chaos); say which tiles to move or replace.
+   - **Pins** (up to 3), by goal: a top performer, the offer, a "pra quem é" post.
+5. **Check every rewrite**: `node scripts/limits.mjs --bio "..." --name "..." [--handle "..."] [--highlight "..."]`. It fails on bio over 150, NAME over 30, a NAME with no search word, an @ with invalid characters, a highlight name that gets cut, an em dash, or AI words. Nothing is delivered until it passes. Then run bio and NAME through `wizz-humanizer`.
+6. **Header test.** Reading only photo + NAME + bio + link + first grid row: would a stranger know who this is for and follow? Answer yes or no, and why.
+
+## Scorecard
+
+| # | Part | Passes when |
+|---|---|---|
+| 1 | Foto | face (or mark) fills the circle, recent, high contrast, readable small |
+| 2 | NOME | name + search word, up to 30 |
+| 3 | @ | short, matches the brand, no numbers or underscores when avoidable |
+| 4 | Bio | value + topic + proof in up to 150, no cliché opener, no emoji storm |
+| 5 | Link | one, goal-matched; the top link carries the click |
+| 6 | Categoria | set, one niche label that reinforces the bio |
+| 7 | Destaques | 4 to 6, ordered by the visitor's next question, one cover style, names not cut |
+| 8 | 9 primeiras | consistent look, readable, shows range; weak tiles moved or replaced |
+| 9 | Fixados | up to 3, each the best proof for the goal, chosen by metrics |
+
+## Delivery
+
+```
+👤 PERFIL LIDO: @ · seguidores · posts · objetivo · como foi lido (captura / print)
+📊 PLACAR: 9 linhas, passa | ajustar | reprova + motivo
+🔧 CORREÇÕES POR IMPACTO: lista curta
+✍️ ANTES → DEPOIS: NOME, bio, link, categoria (só o que reprovou), com a contagem do limits.mjs
+⭐ DESTAQUES: ordem, nomes, o que vai em cada um
+📌 FIXADOS: 3 posts + por quê (métrica)
+🧪 TESTE DO CABEÇALHO: sim/não + motivo
+```
+
+## Hand-off
+
+- Highlight covers and the pinned posts' art: `wizz-canvas-design`.
+- Captions of the pinned posts: `wizz-social-content`.
+- The offer behind the link: `wizz-offer-forge`.
+
+## Hard rules
+
+- Never ship a bio or NAME that fails `limits.mjs`, and never a truncated highlight name.
+- Never invent proof for the bio (a number, a client count, a result): ask, or leave a slot.
+- Never log in to Instagram on the user's behalf; a logged-out capture plus their screenshots is enough.
+- Highlights and grid are judged as sets: fix order and consistency, not only single items.

package/src/skills-lib/wizz-ig-profile-optimizer/scripts/capture-profile.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Captures a public Instagram profile as a logged-out visitor sees it, with agent-browser.
+# Usage: capture-profile.sh <@handle or handle> <out_dir>
+#   → <out_dir>/profile.png (phone-width, header + first rows of the grid)
+#     <out_dir>/profile.json (page title, meta description with counts, header text: NAME, bio, link)
+# Logged out, Instagram may hide highlights, the category label and the pin marks: ask for a
+# screenshot of those. Exit 2 = usage or missing tool; 1 = page did not load.
+set -euo pipefail
+[ $# -eq 2 ] || { echo "uso: capture-profile.sh <@perfil> <pasta de saída>" >&2; exit 2; }
+handle="${1#@}"; out="$2"
+[[ "$handle" =~ ^[A-Za-z0-9._]{1,30}$ ]] || { echo "@ inválido: $1" >&2; exit 2; }
+command -v agent-browser >/dev/null || { echo "falta agent-browser no PATH (skill wizz-agent-browser)" >&2; exit 2; }
+mkdir -p "$out"
+trap 'agent-browser close >/dev/null 2>&1 || true' EXIT
+
+agent-browser set viewport 430 1400 >/dev/null
+agent-browser open "https://www.instagram.com/$handle/" >/dev/null
+agent-browser wait 3000 >/dev/null
+# Cookie banner (pt or en), then Escape closes the sign-up prompt that covers the grid.
+agent-browser find text "Recusar cookies opcionais" click >/dev/null 2>&1 \
+  || agent-browser find text "Decline optional cookies" click >/dev/null 2>&1 || true
+agent-browser wait 1500 >/dev/null
+agent-browser press Escape >/dev/null 2>&1 || true
+agent-browser wait 800 >/dev/null
+
+agent-browser eval 'JSON.stringify({
+  title: document.title,
+  description: document.querySelector("meta[property=\"og:description\"]")?.content ?? null,
+  header: document.querySelector("header")?.innerText ?? null
+})' > "$out/profile.raw"
+node -e '
+const fs = require("node:fs");
+const [raw, out] = process.argv.slice(1);
+let data = JSON.parse(fs.readFileSync(raw, "utf8"));
+if (typeof data === "string") data = JSON.parse(data);
+if (!data.header) { console.error("perfil não carregou (privado, inexistente ou bloqueado)"); process.exit(1); }
+fs.writeFileSync(out, JSON.stringify(data, null, 1));
+' "$out/profile.raw" "$out/profile.json"
+rm -f "$out/profile.raw"
+agent-browser screenshot "$out/profile.png" >/dev/null
+echo "ok: $out/profile.json + profile.png"

package/src/skills-lib/wizz-ig-profile-optimizer/scripts/limits.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// Checks Instagram profile text against the platform limits and the Wizz text rules.
+//   node limits.mjs --bio "<text>" --name "<text>" [--handle "<text>"] [--highlight "<name>" ...] [--json]
+// Exit 0 = everything fits; 1 = something fails (listed); 2 = usage.
+// Counting is conservative: UTF-16 units, so an emoji counts as 2. Instagram's own counter may be
+// more lenient; a text that passes here fits there.
+
+const LIMITS = { bio: 150, name: 30, handle: 30 };
+// Not a platform limit: above this a highlight name gets cut under the circle on most phones.
+const HIGHLIGHT_VISIBLE = 15;
+const AI_WORDS = /\b(alavanc\w*|fundamentalmente|potencializ\w*|eleve|elevar|revolucion\w*|game[- ]changer|leverage|elevate)\b/i;
+const EM_DASH = /—/;
+const HANDLE_CHARS = /^[A-Za-z0-9._]+$/;
+
+function parse(argv) {
+  const options = { highlights: [], json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === '--json') options.json = true;
+    else if (flag === '--highlight') options.highlights.push(argv[++i] ?? '');
+    else if (['--bio', '--name', '--handle'].includes(flag)) options[flag.slice(2)] = argv[++i] ?? '';
+    else usage(`unknown argument: ${flag}`);
+  }
+  if (options.bio === undefined && options.name === undefined && options.handle === undefined && options.highlights.length === 0) {
+    usage('nothing to check');
+  }
+  return options;
+}
+
+function usage(message) {
+  process.stderr.write(`limits: ${message}\nusage: node limits.mjs --bio "..." --name "..." [--handle "..."] [--highlight "..."] [--json]\n`);
+  process.exit(2);
+}
+
+const graphemes = (text) => [...new Intl.Segmenter('pt-BR', { granularity: 'grapheme' }).segment(text)].length;
+
+function checkField(field, text, limit) {
+  const problems = [];
+  if (text.length > limit) problems.push(`${text.length} caracteres (limite ${limit}, emoji conta 2)`);
+  if (EM_DASH.test(text)) problems.push('travessão (—) em texto público');
+  const ai = text.match(AI_WORDS);
+  if (ai) problems.push(`palavra de IA: "${ai[0]}"`);
+  return { field, text, length: text.length, graphemes: graphemes(text), limit, ok: problems.length === 0, problems };
+}
+
+function check(options) {
+  const results = [];
+  if (options.bio !== undefined) results.push(checkField('bio', options.bio, LIMITS.bio));
+  if (options.name !== undefined) {
+    const name = checkField('nome', options.name, LIMITS.name);
+    if (!/[|·,\-]/.test(options.name) && options.name.trim().split(/\s+/).length < 3) {
+      name.problems.push('NOME sem palavra-chave de busca (ex.: "Ana Souza | Nutrição")');
+      name.ok = false;
+    }
+    results.push(name);
+  }
+  if (options.handle !== undefined) {
+    const handle = checkField('@', options.handle.replace(/^@/, ''), LIMITS.handle);
+    if (!HANDLE_CHARS.test(handle.text)) {
+      handle.problems.push('@ só aceita letras, números, ponto e sublinhado');
+      handle.ok = false;
+    }
+    results.push(handle);
+  }
+  for (const highlight of options.highlights) {
+    const result = checkField('destaque', highlight, HIGHLIGHT_VISIBLE);
+    result.problems = result.problems.map((p) => p.replace(/\(limite \d+, emoji conta 2\)/, `(acima de ${HIGHLIGHT_VISIBLE} corta embaixo do círculo)`));
+    results.push(result);
+  }
+  return results;
+}
+
+const options = parse(process.argv.slice(2));
+const results = check(options);
+if (options.json) process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
+else {
+  for (const r of results) {
+    const mark = r.ok ? 'ok ' : 'ERRO';
+    process.stdout.write(`${mark} ${r.field}: ${r.length}/${r.limit}${r.problems.length ? ' · ' + r.problems.join(' · ') : ''}\n`);
+  }
+}
+process.exit(results.every((r) => r.ok) ? 0 : 1);

package/src/skills-lib/wizz-premium-landing-ui-researcher/SKILL.md

@@ -16,6 +16,10 @@ Check for `{output_folder}/design-state.yaml` (default `_wizz-output/`). Cheap c
 - **It does not exist, and the work is non-trivial:** invoke `skill:wizz-design-needs` first. Mining without a map is how a project ends up depending on the user to name every effect, one request at a time.
 - **It does not exist, and the work is one isolated component the user named:** proceed, and say the map was not created.
 
+## Gate 0.5: open the access (always, before the first search)
+
+Read [web-access-and-evidence](references/web-access-and-evidence.md) and run its Step 0: load the web tools (on Claude Code, WebSearch and WebFetch are deferred and need `ToolSearch`), then fall back to `curl`, `agent-browser` and the local source cache. No web and no cache means BLOCKED, never research from memory. Before delivering, every recommended component passes that file's evidence gate; the rest are UNVERIFIED and are never recommended.
+
 ## Gate 1: Source-First (always, before any UI code)
 
 This skill exists because writing shaders, animations, hovers, and components from scratch is NOT the way. The way is to curate mature components, animations, and shaders from professional sources (the user's `modelos lp/`, React Bits, Cult UI, Ali Imam, Watermelon, StyleUI, Skiper UI, Componentry, and public registries) and adapt them to the brand.
@@ -64,5 +68,6 @@ Classify the project into one of 5 levels (rules, allowed/forbidden motion, and
 | Base prompts (complete landing page and 3D scroll hero) | [prompt-templates](references/prompt-templates.md) |
 | Final response format, Quality Bar, and self-check before closing the delivery | [output-format-and-quality](references/output-format-and-quality.md) |
 | Direct links to every authorized source | [source-links](references/source-links.md) |
+| Opening web access before mining, BLOCKED, and the evidence gate before delivering | [web-access-and-evidence](references/web-access-and-evidence.md) |
 
 Final rule: never put real keys inside the skill (environment variables only), and never deliver a landing page that looks like a template with no positioning.

package/src/skills-lib/wizz-premium-landing-ui-researcher/references/component-sources.md

@@ -11,7 +11,7 @@ Research flow (public sources first; log evidence per [source-first-protocol](so
 3. public shadcn registries;
 4. taste/motion sources (Impeccable, Taste Skill, Design Motion Principles, MotionSites, Vibe Code Components, Refero Styles with a free DESIGN.md);
 5. open visual sources (Landing Love, Godly, Design Spells, Mobbin, Refero, ScreensDesign, DesignVault, Spline, Unicorn Studio);
-6. coherent strategic hypotheses, when there is no external access.
+6. with no web and no local cache: BLOCKED, per [web-access-and-evidence](web-access-and-evidence.md). Strategic hypotheses can shape the direction, never stand in for a component source.
 
 ## Mining Evidence
 

package/src/skills-lib/wizz-premium-landing-ui-researcher/references/source-first-protocol.md

@@ -56,7 +56,7 @@ Log in the existing design artifact (or create `design-research.md` in the proje
 |---|---|---|---|---|---|---|
 | Item actually inspected | Terms used and catalog | Real URLs or paths | SHA/tag; date if there's no version | Verified or pending | Tested / static / unavailable | Accepted/rejected and reason |
 
-Also include searches with no results and unavailable sources. Never fill in component names, paths, license, or test results by assumption.
+Also include searches with no results and unavailable sources. Never fill in component names, paths, license, or test results by assumption. A row missing any of the five fields in [web-access-and-evidence](web-access-and-evidence.md) is UNVERIFIED and cannot be the recommendation.
 
 Show 1-3 compatible candidates per component, with a recommendation and adaptation cost. If the user has already authorized the implementation and defined the direction, choose the best option within that scope and proceed. Only ask when a material decision about direction, paid access, or scope change is missing.
 

package/src/skills-lib/wizz-premium-landing-ui-researcher/references/web-access-and-evidence.md

@@ -0,0 +1,40 @@
+# Web access and evidence gate
+
+Shared by `wizz-premium-landing-ui-researcher` and `wizz-ui-component-curator`. Read it before the first search. It covers two moments: opening access before mining, and checking evidence before delivering.
+
+Mining from memory is the failure this file exists to prevent. Component names, URLs, licenses and APIs the model "remembers" are hypotheses, and a hypothesis delivered as research is worse than no research: the user builds on it without knowing.
+
+## Step 0: open the access (before any query)
+
+A tool you do not see is not a tool you do not have. In a subagent, the web tools often start unloaded.
+
+1. **Load the web tools.** On Claude Code, WebSearch and WebFetch are deferred: load them with `ToolSearch` (`select:WebSearch,WebFetch`) before deciding they are missing. Do the same for an Exa or scrapling MCP if the session lists one. On other platforms, use that platform's native web search and fetch.
+2. **Fallbacks, in order:** `curl -sL <url>` through the shell (raw HTML, registry JSON, `raw.githubusercontent.com` source files), then `agent-browser` (also the tool for watching hover and motion live).
+3. **Local source cache:** `~/.claude/design-sources/` holds real repositories (React Bits, Cult UI, Ali Imam, Watermelon, StyleUI). Reading a file there counts as evidence, as long as you record the path and the revision (`git -C <repo> rev-parse --short HEAD`) and say the cache may be behind the remote.
+4. **Record the outcome** in one line before mining: which access worked (`web`, `curl`, `agent-browser`, `cache only`) and which failed, with the error.
+
+If none of the four works, stop and return:
+
+```text
+BLOCKED: no web access and no local source cache.
+Tried: <tool → error, one per line>
+Unblock: <what the user can do, e.g. enable WebFetch, install agent-browser, clone the sources into ~/.claude/design-sources/>
+```
+
+BLOCKED is a complete, correct answer. Do not deliver component recommendations instead of it, not even marked "(verify)". Direction work that needs no source (site level, motion budget, style read of the project) can still be delivered next to BLOCKED, labelled as such.
+
+## Evidence gate (before delivering)
+
+Every candidate needs all five, collected in this session:
+
+| Field | Counts | Does not count |
+|---|---|---|
+| URL or path | The exact demo and the exact source file or registry item you opened | A catalog homepage, a search snippet, a URL you did not open |
+| Date | Today's date or the repo revision (SHA/tag) | "recent", "current" |
+| License | Read in the repo or registry | Assumed from the catalog's reputation |
+| Dependencies | Read from the actual imports or registry JSON | Guessed from the component's name |
+| Source read | The code file was opened and its imports checked | The demo alone |
+
+A candidate missing any field is **UNVERIFIED**. UNVERIFIED items go in a separate section of the report, with what is missing and why. They are never recommended and never placed in the top 1-3, and the implementation plan never depends on them. If every candidate for a need is UNVERIFIED, the need is reported as `unmet`, not filled.
+
+Before closing, check the delivery against this gate once: every recommended item has its five fields in the research log (`design-research.md` or the project's design artifact), and the access line from Step 0 is in the report.

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

@@ -55,7 +55,7 @@ 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 |
-| Which short-video STYLE to copy, from the inventory of the material (real person, voice only, B-roll, screens, product), with the recipe measured on 99 real shorts; "edit it in the style of", "the video looks amateur" | `wizz-video-styles` (designer registry; picks the style before voice, timing, effects and assembly) | 2 |
+| Which short-video STYLE to copy, from the inventory of the material (real person, voice only, B-roll, screens, product), with the recipe measured on 104 real shorts (lyric video and kinetic typography included); "edit it in the style of", "the video looks amateur" | `wizz-video-styles` (designer registry; picks the style before voice, timing, effects and assembly) | 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 |
@@ -84,6 +84,8 @@ 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 |
+| Tear down ONE viral Instagram post (Reel, carousel, caption) from its link: why it worked, which hook, a mould to do one like it | `wizz-hook-extractor` (social registry; reads the post itself) | 2 |
+| Audit and rewrite an Instagram PROFILE: bio, search NAME, link, highlights, pinned posts | `wizz-ig-profile-optimizer` (social registry) | 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 |

package/src/skills-lib/wizz-ui-component-curator/SKILL.md

@@ -21,7 +21,7 @@ If `{output_folder}/design-state.yaml` exists, the need being worked is already
 
 Not there? Look before deciding it does not exist: `find . -name design-state.yaml -not -path '*/node_modules/*'`. A map found anywhere else is still the map: use it, and tell the user it is off-place (it belongs in `{output_folder}`).
 
-With no state file, continue normally.
+With no state file and more than one need in the request (a polish pass, "effects and animations", a dashboard), run `wizz-design-needs` first and mine against the map it writes. With no state file and one isolated component the user named, continue, and say the map was not created.
 
 ## 1. Read and infer the style DNA
 
@@ -42,7 +42,7 @@ Do not ask the user to describe the style unless the project has no inspectable
 
 Start with existing project components. Then search the public sources. The full authorized list (React Bits, Cult UI, Ali Imam, Watermelon, StyleUI, Skiper UI, Bklit UI, Componentry, shadcn/ui, plus the reference galleries) lives in one place: [component-sources](../wizz-premium-landing-ui-researcher/references/component-sources.md). Read it instead of relying on memory. Compare at least two suitable sources per need.
 
-Use whatever search tools the session has: web search (Exa when configured, WebSearch otherwise), WebFetch, scrapling, and `agent-browser` to watch hover and motion live. A tool that errors or hangs is not the end of the research: record the failure, move to the next tool, and never stop without reporting what was and was not checked.
+Before the first query, open the access as described in [web-access-and-evidence](../wizz-premium-landing-ui-researcher/references/web-access-and-evidence.md): load the web tools (on Claude Code, WebSearch and WebFetch are deferred and need `ToolSearch`), then fall back to `curl`, `agent-browser` and the local source cache. Search with whatever that step opened: web search (Exa when configured, WebSearch otherwise), WebFetch, scrapling, and `agent-browser` to watch hover and motion live. A tool that errors or hangs is not the end of the research: record the failure, move to the next tool, and never stop without reporting what was and was not checked. With no web and no cache, return BLOCKED instead of recommending from memory.
 
 Open the exact demo and source file/registry item. Check the actual imports, license, dependencies, stack variant and revision; use current official documentation (Context7 when available) for API compatibility. Inspect animation/interaction in the available browser; label static-only inspection honestly. If a source fails, record the failure and continue elsewhere.
 
@@ -57,6 +57,8 @@ Use the inferred style DNA as the search filter. Prefer:
 
 Do not present unranked lists. Shortlist internally, then surface only the strongest matches.
 
+Only candidates that pass the evidence gate in [web-access-and-evidence](../wizz-premium-landing-ui-researcher/references/web-access-and-evidence.md) can be shown here. The rest are UNVERIFIED and go to the evidence section.
+
 For each candidate, say briefly:
 - why it fits
 - what role it plays
@@ -131,4 +133,4 @@ Up to 2 backup options only if genuinely different and useful.
 What changes, which files, any dependency or adaptation work.
 
 ## Research evidence
-Exact candidate demo/source links, revision/date, license and dependencies, visual inspection status, decisions and unavailable sources. State what still needs a user decision.
+The access line (what worked, what failed), then exact candidate demo/source links, revision/date, license and dependencies, visual inspection status, decisions and unavailable sources. UNVERIFIED items listed apart, with what is missing. State what still needs a user decision.

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

@@ -10,6 +10,7 @@ A catalogue of effects is easy. What makes a video look professional is the **re
 ## Where it sits in the video pipeline
 
 1. Script and narration exist; `ctc-align` gave word-by-word timestamps.
+   On a music-driven piece (lyric video over a song) the song is the narration: `scenes[]` start on the downbeats from `wizz-video-styles/scripts/beat_grid.py`, and the song's own hits count as the SFX budget already spent.
 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.