wizz-method 2.17.2 → 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-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-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.

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

@@ -20,6 +20,8 @@ It can also run at step 1, so the script is written for the style (room for b-ro
 
 ## Per piece
 
+Scripts live in this skill's `scripts/`; run them from the project root (the history file is written in the current directory, or in `--project <dir>`).
+
 1. **Inventory first, always.** Ask or read from the plan, one line each:
    - Is a real person on camera? Which shots exist (face to camera, podcast, stage, street, hands only)?
    - Voice: the person's own recording, a podcast/interview track, TTS, or none?
@@ -27,16 +29,17 @@ It can also run at step 1, so the script is written for the style (room for b-ro
    - B-roll or stock, a physical product, food, a place?
    - Niche, goal of the piece (follow, comment, save, click), duration.
    Never pick a style the material cannot feed. "Talking head" needs a person on camera; "motion editorial" needs nothing but a voice; "macro / ASMR" needs a physical product filmed close.
-2. **Pick the style** with [references/style-picker.md](references/style-picker.md): material decides which styles are possible, niche and goal rank them. Mixed is allowed and common: person on camera for the hook and the CTA, another style in the middle.
+2. **Pick the style** with [references/style-picker.md](references/style-picker.md): material decides which styles are possible, niche and goal rank them. Mixed is allowed and common: person on camera for the hook and the CTA, another style in the middle. Before deciding, run `node scripts/references.mjs history` in the project: if the last two pieces used the same style, do not pick it a third time unless the user wants a series; choose another style the material allows, or keep it only for the hook and CTA.
 3. **Open the style card** in `references/styles/` and follow it: rhythm, captions, palette, typography, motion, music, SFX, hook, CTA, and its "do not" list.
-4. **Watch two of its references** (links in the card) before editing. Reading a card is not watching a video.
+4. **Get fresh references and watch two** before editing: `node scripts/references.mjs pick --style <key>` returns measured references plus, for styles generated in code, current viral videos from the awesome-opus5-5-videos list, skipping everything this project already used. Reading a card is not watching a video. For how those generated videos were briefed, see [references/generated-prompts.md](references/generated-prompts.md).
 5. **Audio:** music and SFX choices from [references/audio.md](references/audio.md); the redistributable kit is in `assets/audio/` (credits in `assets/audio/CREDITS.md`).
 6. **Hand over** to `wizz-video-effects` with the card's SFX ceiling and music level, then to Remotion.
 7. **Look at the final file**: extract frames and compare them side by side with a contact sheet of one reference.
+8. **Record the piece**: `node scripts/references.mjs record --style <key> --piece <slug> --refs <ids watched>`. It writes `_wizz-output/video-styles/historico.json`, which is what keeps the next piece from repeating the same references and look.
 
 ## What the measurements say across every style
 
-- **SFX are rare.** Across 99 measured shorts, sound effects landed on a cut in a small minority of cuts (per-style counts in each card). Putting a sound on every cut is the most common amateur tell.
+- **SFX are rare.** Across 104 measured shorts, sound effects landed on a cut in a small minority of cuts (per-style counts in each card). Putting a sound on every cut is the most common amateur tell.
 - **Music bed: style-dependent.** Fast montage, animated explainers and travel POV carry a continuous bed; talking heads and podcast clips mostly have none or a faint one.
 - **Captions** in reach-heavy styles are 1 to 3 words at a time, bold, lower-centre, with one keyword in an accent colour; editorial and explainer styles keep them small or drop them.
 - **Rhythm is a style property, not a virtue.** The highest-reach videos in the set range from single takes with no detected cut to a cut every second.
@@ -53,7 +56,10 @@ Details and the per-style table: [references/measured-patterns.md](references/me
 | [references/audio.md](references/audio.md) | music and SFX per style, the kit, libraries and licences |
 | [references/research-method.md](references/research-method.md) | how the catalogue was measured, its limits, how to add a niche or a style |
 | `data/references.json` | every measured short: link, channel, views, niche, style, metrics |
+| [references/generated-prompts.md](references/generated-prompts.md) | prompts of viral code-generated videos, grouped by style, and how they run here |
 | `scripts/analyze.sh` | measures one short (cuts, music bed, SFX heuristics, loudness, contact sheet) |
+| `scripts/references.mjs` | fresh references per style without repeats, and the project's history of styles used |
+| `scripts/beat_grid.py` | BPM, beats and downbeats of a song, so cuts snap to the music (lyric video, kinetic typography) |
 | `assets/remotion/editorial/` | Remotion template of the motion editorial style |
 | `assets/audio/` | licensed music beds and SFX that may ship with a project |
 

package/src/skills-lib/wizz-video-styles/data/recipes.json

@@ -7,7 +7,8 @@
   "e": "health / fitness / nutrition",
   "f": "food / recipes / lifestyle / travel",
   "g": "beauty / fashion / local services (clinic, salon, architecture, real estate)",
-  "h": "education / science / comedy"
+  "h": "education / science / comedy",
+  "i": "music / artists / lyric videos"
  },
  "styles": {
   "motion-editorial": {
@@ -336,6 +337,37 @@
    "dont": [
     "Setup longer than 3 s before the first joke."
    ]
+  },
+  "tipografia-cinetica": {
+   "title": "Kinetic typography and lyric video (mexicat P(doom), PixelValet, Ninh Truong)",
+   "needs": "An audio track with words: a song with its lyrics, or a voice-over with its script. Nobody on camera, no footage. Everything is generated (HyperFrames, three.js, canvas). Word timing from ctc-align; a beat grid when there is music.",
+   "fits": "Music releases and lyric videos, manifestos, a strong opinion read aloud, brand promos built on a slogan, poetry. Shares and rewatches; weak for teaching step by step.",
+   "look": [
+    "The words ARE the image: one keyword huge in the frame, the rest of the line small. No caption strip at the bottom.",
+    "Plain background (black, or a flat colour that changes per section) or one generated world the camera travels through (a map, a grid in perspective, a 3D object the line wraps around).",
+    "Each word is animated by what it means: PAIN breaks, CHEERFUL bounces, LIGHT lights up, a word curves around the object it names.",
+    "Code-rendered pieces add film treatment: bloom, halation, grain, a thin HUD in mono."
+   ],
+   "palette": "Dark base (#0A0A0A or a deep teal #0F3B3A) plus ONE glowing accent (orange #FF6A1A in P(doom), coral in Maps) and off-white text. Flat-colour variant: one saturated background per word or section, text in white or ink.",
+   "type": "Two or three families with high contrast: a heavy grotesk or condensed caps for the keyword (Archivo Black, Bebas Neue), a mono for small lines and HUD (IBM Plex Mono), optionally a serif italic for a soft word (Cormorant Garamond). Mix weights inside the same line.",
+   "motion": [
+    "Words enter on the syllable they are sung or spoken (forced alignment, never guessed); the keyword lands on the beat.",
+    "Scene changes snap to the downbeat. P(doom) changes every ~0.3 s at peaks; the calm variant is a single continuous camera move for a whole verse.",
+    "The camera moves through the type (push, orbit, travel across a map) instead of the text sliding over a still frame.",
+    "Hold the last word of a line a beat longer before it leaves."
+   ],
+   "captions": "None separate: the type is the caption. Keep the full line readable somewhere (small, mono, corner) when the keyword alone would lose the sense.",
+   "hook": "The first sung or spoken word, huge, in the accent colour, landing on the first downbeat (0 to 1 s). No logo intro.",
+   "cta": "The title or slogan locked up big and still for 1 to 2 s, the accent lit; one small line (artist, handle, link) under it.",
+   "music": "The track itself is the whole soundtrack. Lyric videos: song at full level, no extra bed. Voice-over promos: a beat-driven bed under the voice.",
+   "sfx": "Song-driven pieces: almost none (5 of 56 cuts in P(doom), 0 of 2 in Maps). Promo variant: hits on every word change (9/13 and 16/20 cuts), which the heuristic partly confuses with the kick. Never add whooshes over a song.",
+   "dont": [
+    "Karaoke subtitles at the bottom over a static background: that is a lyric 'overlay', not this style.",
+    "Guessing word timing by ear; align it (ctc-align) and snap scenes to the beat grid.",
+    "More than one accent colour, or a different font for every word.",
+    "Shipping 16:9: every measured reference is horizontal; recompose for 9:16 with the keyword in the upper-middle and nothing in the bottom 20%."
+   ],
+   "template": null
   }
  }
 }