wizz-method 2.20.1 → 2.22.0

package/src/skills-lib/wizz-video-styles/references/styles/desafio-numero.md

@@ -27,6 +27,7 @@ Food, money, products, everyday economics. The highest single reach in the set (
 **Look**
 
 - A visible progress device fixed on screen: time icons (1 s / 1 min / 1 h) changing colour per stage, emoji checklist, price tags on each ingredient.
+  It is measured for this style, so the chrome lint of `wizz-video-effects` takes `chrome_allow: ["P1", "C3"]` in the timeline (progress and stage counter).
 - Close hands, real places (market, street), a reaction at the end.
 
 **Palette:** Warm natural colours; tags in bright yellow with black outline; red/green icons for stages.

package/src/skills-lib/wizz-video-styles/scripts/blind_review.py

@@ -0,0 +1,159 @@
+# -*- coding: utf-8 -*-
+"""Blind A/B review of two or more versions of a piece.
+
+    python3 blind_review.py prepare OUT_DIR a.mp4 b.mp4 [c.mp4 ...]
+    python3 blind_review.py reveal OUT_DIR
+
+prepare: links (or copies) each film to OUT_DIR/A.mp4, B.mp4 ... in a random
+order, writes OUT_DIR/index.html (the films side by side at phone size, one
+play button for all, sound per film) and the answer key in
+OUT_DIR/.answer-key.json (mode 600). Running it again on the same folder and
+films keeps the earlier shuffle, so a verdict already given stays valid.
+reveal: prints which letter is which file. Only after the user picked.
+
+Do not open the key or compare file sizes before judging: both give the
+films away. Judge the picture silent first, then each soundtrack alone. The
+user's pick goes to taste.mjs add.
+
+Idea from motionmaxxing's blind_review.py (Apache-2.0,
+github.com/Tejashmakwana/motionmaxxing); see THIRD-PARTY-NOTICES.md.
+
+Exit code: 0 ok, 2 bad usage (fewer than 2 films, missing file, no key).
+"""
+from __future__ import annotations
+
+import argparse
+import html
+import json
+import os
+import secrets
+import shutil
+import string
+import sys
+from pathlib import Path
+
+KEY_NAME = ".answer-key.json"
+
+PAGE = """<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Blind review</title>
+<style>
+:root {{ color-scheme: light dark; --bg: #f6f5f2; --ink: #1b1b1b; }}
+@media (prefers-color-scheme: dark) {{ :root {{ --bg: #141414; --ink: #ececec; }} }}
+body {{ margin: 0; padding: 16px; background: var(--bg); color: var(--ink); font: 16px/1.4 system-ui, sans-serif; }}
+.row {{ display: flex; gap: 16px; flex-wrap: wrap; justify-content: center; }}
+figure {{ margin: 0; text-align: center; }}
+video {{ width: min(42vw, 360px); aspect-ratio: 9 / 16; background: #000; }}
+button {{ font: inherit; padding: 6px 14px; margin: 4px; }}
+p {{ max-width: 720px; margin: 8px auto 16px; text-align: center; }}
+</style>
+</head>
+<body>
+<p>Watch silent first, then each sound alone. Pick before revealing anything.</p>
+<p><button id="play">Play all</button><button id="restart">Restart</button></p>
+<div class="row">
+{figures}
+</div>
+<script>
+const vids = [...document.querySelectorAll("video")];
+document.getElementById("play").onclick = () => {{
+  const go = vids[0].paused;
+  vids.forEach((v) => (go ? v.play() : v.pause()));
+}};
+document.getElementById("restart").onclick = () => vids.forEach((v) => {{ v.currentTime = 0; }});
+document.querySelectorAll("[data-solo]").forEach((b) => {{
+  b.onclick = () => vids.forEach((v) => {{ v.muted = v.id !== b.dataset.solo; }});
+}});
+</script>
+</body>
+</html>
+"""
+
+FIGURE = """<figure>
+<video id="{letter}" src="{letter}.mp4" muted playsinline preload="auto"></video>
+<figcaption><strong>{letter}</strong> <button data-solo="{letter}">Sound of {letter} only</button></figcaption>
+</figure>"""
+
+
+def assign(films: list[str]) -> dict[str, str]:
+    """Letter -> film, in a random order from the OS random source."""
+    pool = list(films)
+    order = []
+    while pool:
+        order.append(pool.pop(secrets.randbelow(len(pool))))
+    return dict(zip(string.ascii_uppercase, order))
+
+
+def _place(src: str, dst: Path) -> None:
+    if dst.exists():
+        dst.unlink()
+    try:
+        os.link(src, dst)
+    except OSError:
+        shutil.copyfile(src, dst)
+
+
+def prepare(out: Path, films: list[str]) -> int:
+    films = [os.path.abspath(f) for f in films]
+    if len(films) < 2 or len(set(films)) != len(films):
+        print("ERROR: give at least two different films")
+        return 2
+    missing = [f for f in films if not os.path.isfile(f)]
+    if missing:
+        print(f"ERROR: not found: {', '.join(missing)}")
+        return 2
+    if len(films) > len(string.ascii_uppercase):
+        print("ERROR: too many films")
+        return 2
+    out.mkdir(parents=True, exist_ok=True)
+    key_file = out / KEY_NAME
+    key = None
+    if key_file.exists():
+        old = json.loads(key_file.read_text(encoding="utf-8"))
+        if sorted(old.values()) == sorted(films):
+            key = old
+    key = key or assign(films)
+    for letter, film in key.items():
+        _place(film, out / f"{letter}.mp4")
+    key_file.write_text(json.dumps(key, indent=1) + "\n", encoding="utf-8")
+    os.chmod(key_file, 0o600)
+    figures = "\n".join(FIGURE.format(letter=html.escape(letter)) for letter in key)
+    (out / "index.html").write_text(PAGE.format(figures=figures), encoding="utf-8")
+    print(f"open {out / 'index.html'}  ({len(key)} films, letters {', '.join(key)})")
+    print(f"after the pick: python3 blind_review.py reveal {out}")
+    return 0
+
+
+def reveal(out: Path) -> int:
+    key_file = out / KEY_NAME
+    if not key_file.exists():
+        print(f"ERROR: no answer key in {out}")
+        return 2
+    for letter, film in json.loads(key_file.read_text(encoding="utf-8")).items():
+        print(f"{letter}: {film}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Blind A/B review page for versions of a piece.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    p = sub.add_parser("prepare")
+    p.add_argument("out")
+    p.add_argument("films", nargs="+")
+    r = sub.add_parser("reveal")
+    r.add_argument("out")
+    args = ap.parse_args(argv)
+    try:
+        if args.cmd == "prepare":
+            return prepare(Path(args.out), args.films)
+        return reveal(Path(args.out))
+    except (OSError, json.JSONDecodeError) as e:
+        print(f"ERROR: {e}")
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/skills-lib/wizz-video-styles/scripts/taste.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// The user's taste for this project's videos: what they approved and rejected, in their words.
+//
+//   node taste.mjs show [--style <key>] [--project <dir>]
+//   node taste.mjs add --verdict approved|rejected --piece <slug> --quote "<their words>"
+//                      --lesson "<narrowest lesson>" [--about "<what they reacted to>"]
+//                      [--style <key>] [--project <dir>]
+//
+// File: <project>/_wizz-output/video-styles/gosto.md, plain markdown the user can read and
+// edit. Append-only: a new verdict never rewrites an old one; one that contradicts an earlier
+// entry is added as a new entry and the reader trusts the newer date.
+// show --style keeps the entries of that style plus the entries with no style (general taste).
+// Read it before choosing a style (wizz-video-styles) and before deciding effects
+// (wizz-video-effects); append after the user reviews a piece.
+// Idea from motionmaxxing's taste/verdicts.md (Apache-2.0); see THIRD-PARTY-NOTICES.md.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const FILE_REL = path.join('_wizz-output', 'video-styles', 'gosto.md');
+const VERDICTS = new Set(['approved', 'rejected']);
+const HEADER = [
+  '# Video taste',
+  '',
+  "What the user approved and rejected in this project's videos, in their words. Written by",
+  '`taste.mjs add` after each review; read before choosing a style or deciding effects.',
+  'A verdict is about one piece: generalise its lesson only as far as its context goes.',
+  '',
+].join('\n');
+
+function fail(message) {
+  process.stderr.write(`taste: ${message}\n`);
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const options = { command, project: process.cwd() };
+  const flags = ['--verdict', '--piece', '--quote', '--lesson', '--about', '--style', '--project'];
+  for (let i = 0; i < rest.length; i++) {
+    if (!flags.includes(rest[i])) fail(`unknown argument: ${rest[i]}`);
+    if (i + 1 >= rest.length) fail(`${rest[i]} needs a value`);
+    options[rest[i].slice(2)] = rest[++i];
+  }
+  return options;
+}
+
+// One line, no markdown heading or list marker can start inside a value.
+const oneLine = (value) =>
+  String(value ?? '')
+    .replaceAll(/\s+/g, ' ')
+    .trim();
+
+function readEntries(file) {
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    fail(`cannot read ${file}: ${error.message}`);
+  }
+  return text
+    .split(/^(?=## )/m)
+    .filter((chunk) => chunk.startsWith('## '))
+    .map((chunk) => {
+      const [, , , style = ''] = chunk.split('\n')[0].slice(3).split(' · ');
+      return { style: style.trim(), text: chunk.trimEnd() };
+    });
+}
+
+function show(options) {
+  const entries = readEntries(path.join(options.project, FILE_REL));
+  if (entries === null || entries.length === 0) {
+    process.stdout.write(`no verdicts recorded yet (${FILE_REL})\n`);
+    return;
+  }
+  const style = options.style ? oneLine(options.style) : '';
+  const kept = style ? entries.filter((e) => e.style === '' || e.style === style) : entries;
+  process.stdout.write(`${kept.map((e) => e.text).join('\n\n')}\n`);
+}
+
+function add(options) {
+  const verdict = oneLine(options.verdict);
+  if (!VERDICTS.has(verdict)) fail('--verdict must be approved or rejected');
+  const piece = oneLine(options.piece);
+  const quote = oneLine(options.quote);
+  const lesson = oneLine(options.lesson);
+  if (!piece || !quote || !lesson) fail('--piece, --quote and --lesson are required');
+  const style = oneLine(options.style);
+  const about = oneLine(options.about);
+  const date = new Date().toISOString().slice(0, 10);
+  const lines = [
+    `## ${[date, verdict, piece, style].filter(Boolean).join(' · ')}`,
+    '',
+    `- Quote: "${quote}"`,
+    ...(about ? [`- About: ${about}`] : []),
+    `- Lesson: ${lesson}`,
+    '',
+  ];
+  const file = path.join(options.project, FILE_REL);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  if (!fs.existsSync(file)) fs.writeFileSync(file, HEADER);
+  fs.appendFileSync(file, `\n${lines.join('\n')}`);
+  process.stdout.write(`recorded ${verdict} for ${piece} in ${FILE_REL}\n`);
+}
+
+const options = parseArgs(process.argv.slice(2));
+if (options.command === 'show') show(options);
+else if (options.command === 'add') add(options);
+else fail('usage: taste.mjs show|add (see the header of this file)');

package/src/skills-lib/wizz-video-styles/scripts/test_blind_review.py

@@ -0,0 +1,82 @@
+# -*- coding: utf-8 -*-
+"""Tests of blind_review.py: random labels, hidden key, re-run keeps the
+shuffle, reveal, and refusals."""
+import io
+import json
+import os
+import stat
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+
+import blind_review as BR
+
+
+def _films(tmp: str, n: int) -> list[str]:
+    out = []
+    for i in range(n):
+        p = Path(tmp) / f"version-{i}.mp4"
+        p.write_bytes(b"fake mp4 " + bytes([i]))
+        out.append(str(p))
+    return out
+
+
+def _run(argv) -> tuple[int, str]:
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        code = BR.main(argv)
+    return code, buf.getvalue()
+
+
+class TestPrepare(unittest.TestCase):
+    def test_page_key_and_labels(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            films = _films(tmp, 2)
+            out = Path(tmp) / "review"
+            code, _ = _run(["prepare", str(out), *films])
+            self.assertEqual(code, 0)
+            key = json.loads((out / BR.KEY_NAME).read_text(encoding="utf-8"))
+            self.assertEqual(sorted(key), ["A", "B"])
+            self.assertEqual(sorted(key.values()), sorted(os.path.abspath(f) for f in films))
+            self.assertEqual(stat.S_IMODE((out / BR.KEY_NAME).stat().st_mode), 0o600)
+            page = (out / "index.html").read_text(encoding="utf-8")
+            self.assertIn("A.mp4", page)
+            self.assertIn("B.mp4", page)
+            for f in films:   # the page never names the source files
+                self.assertNotIn(Path(f).name, page)
+            self.assertNotIn("—", page)
+
+    def test_rerun_keeps_the_shuffle(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            films = _films(tmp, 3)
+            out = Path(tmp) / "review"
+            _run(["prepare", str(out), *films])
+            first = (out / BR.KEY_NAME).read_text(encoding="utf-8")
+            _run(["prepare", str(out), *films])
+            self.assertEqual((out / BR.KEY_NAME).read_text(encoding="utf-8"), first)
+
+    def test_shuffle_is_random(self):
+        orders = {tuple(BR.assign(["a", "b", "c", "d"]).values()) for _ in range(40)}
+        self.assertGreater(len(orders), 1)
+
+    def test_reveal_prints_the_key(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            films = _films(tmp, 2)
+            out = Path(tmp) / "review"
+            _run(["prepare", str(out), *films])
+            code, text = _run(["reveal", str(out)])
+            self.assertEqual(code, 0)
+            self.assertIn("version-0.mp4", text)
+            self.assertIn("version-1.mp4", text)
+
+    def test_one_film_or_missing_file_is_refused(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            films = _films(tmp, 1)
+            self.assertEqual(_run(["prepare", str(Path(tmp) / "r"), *films])[0], 2)
+            self.assertEqual(_run(["prepare", str(Path(tmp) / "r"), films[0], "/nope.mp4"])[0], 2)
+            self.assertEqual(_run(["reveal", str(Path(tmp) / "empty")])[0], 2)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/src/skills-lib/wizz-vsl/LICENSE

@@ -0,0 +1,49 @@
+wizz-vsl adapts material from two MIT-licensed skills. Their notices follow.
+
+== yuribranco/vsl-skill (https://github.com/yuribranco/vsl-skill), commit fe855c50 ==
+
+MIT License
+
+Copyright (c) 2026 Yuri Branco
+
+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.
+
+== bertrand-do/video-sales-letter (https://github.com/bertrand-do/video-sales-letter), commit f41eec5a ==
+
+MIT License
+
+Copyright (c) 2026 Bertrand Diouly
+
+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-vsl/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: wizz-vsl
+description: Writes a video sales letter (VSL) from the expert's real material to a script ready to record, and plans its production. Interviews in 11 blocks, diagnoses awareness and sophistication, has a human pick one problem and one solution mechanism from a 5x5 document, writes backwards (offer, middle blocks, then 5 leads), never invents proof, and closes with a claims ledger, a beat sheet and a production hand-off with motion anchored to the final audio alignment. Reads the low ticket ruler first when the operation is low ticket. Use when someone wants a VSL written from scratch, wants to rebuild one that does not convert, needs the mechanism of an offer for a sales video, or needs lead variations to test. Triggers - faz a VSL do meu produto, roteiro do vídeo de vendas, a lead da VSL tá fraca, a retenção cai no primeiro minuto, refaz minha VSL. Does not write the sales page around the player (wizz-copywriting), short ad creatives (wizz-ad-creative) or Reels (wizz-social-content), and does not edit the video itself.
+---
+
+# wizz-vsl: from the expert's briefing to a VSL ready to record
+
+**The lead is the last thing written.** A VSL is derived: from what the expert really knows, from the real state of the market, and from the mechanism chosen. An agent that starts at the lead produces pretty, generic copy with no hypothesis, and when it does not convert nobody knows which piece was wrong. This skill imposes the reverse order: interview, diagnose, lock the mechanism, write the offer, climb up to the lead, then plan production.
+
+Everything delivered to the user is in `{communication_language}` (Brazilian Portuguese by default, "você", spoken register). No em dash in anything a third party reads or hears.
+
+## Step 0 · Inputs and the ruler in effect
+
+1. **Resume first.** Look for `{output_folder}/vsl/<slug>/manifest.json`. If it exists, read it and `00-briefing.md`, say in one line where the work stopped, and resume from the first pending phase. Never re-interview someone who already answered.
+2. **Reuse what the method already produced.** An approved offer from the `wizz-offer-forge` skill (`{output_folder}/offers/OFFER-*.md`) is the source for the offer block and for the solution mechanism: record it in the manifest instead of re-deriving it. Audience research from the `wizz-pesquisa-de-publico-do-piva` skill (`{output_folder}/pesquisa-piva/`) is the source for blocks 2, 3, 8 and 10 of the interview: VoC, awareness levels, lexicon and angles come from there, quoted with file and section. When there is no approved offer, say so and invoke the `wizz-offer-forge` skill before Phase 4; when there is no audience research and the expert has no material, offer to invoke the `wizz-pesquisa-de-publico-do-piva` skill first.
+3. **Low ticket ruler.** The low ticket base applies only when BOTH are true: the `wizz-lowticket-metodologia` skill is installed in this project, AND the project context or the request itself establishes that the operation is low ticket (price range, cheap product, direct traffic). Do not presume low ticket because the product is a course or there is a campaign running. When both hold, before Phase 2, read its `knowledge/INDEX.md`, then `knowledge/13-benchmarks-vsl.md` and the VSL entries the INDEX names (`04b` §4.7 and §4.7-A, `18` §18.8). That ruler sets the length, the pitch position and the number of leads to test; where it contradicts this skill (the 16 to 20 minute default below), **the ruler wins**, and say so in the reply. In practice: a product that proves itself on screen stays at 90 s to 2 min, an offer that needs to build mechanism and authority goes to 7 to 9 min, below R$60 the ceiling is 7 to 8 min, the pitch enters at about two thirds of the video, and 3 to 8 leads get tested.
+
+## The six phases
+
+| # | Phase | Read | Done when |
+|---|---|---|---|
+| 0 | Ingest what already exists | [references/intake.md](references/intake.md) §0 | inventory made, briefing pre-filled with sources |
+| 1 | Interview whoever knows | [references/intake.md](references/intake.md) | `00-briefing.md` closed, or its gaps declared and accepted by the human |
+| 2 | Market diagnosis (Schwartz) | [references/diagnosis.md](references/diagnosis.md) | **Gate 1**: human confirms awareness and sophistication |
+| 3 | Mechanisms, 5 problem x 5 solution | [references/mechanisms.md](references/mechanisms.md) | **Gate 2**: human picks 1 + 1 |
+| 4 | Writing, backwards | [references/offer.md](references/offer.md), then [references/blocks-and-leads.md](references/blocks-and-leads.md) | offer, 3 middle blocks and 5 leads written |
+| 5 | Assembly, claims ledger, QA, test plan | [references/assembly-qa.md](references/assembly-qa.md) | checklist closed |
+| 6 | Production plan and hand-off | [references/production.md](references/production.md) | beat sheet delivered, hand-off stated |
+
+The niche changes tone, proof type, price and compliance in every phase: [references/niches.md](references/niches.md).
+
+**Compress, never drop a phase.** When the user says "I already know the mechanism, just write it", Phase 1 shrinks to the mandatory blocks, Phase 2 fits in one screen (your reading plus their confirmation is Gate 1), and Phase 3 records the mechanism they already have, with their explicit confirmation of which one is master on each side (Gate 2). A decision already recorded in the manifest or in an approved offer is not asked again.
+
+## The two gates
+
+**Gate 1 · diagnosis confirmed.** A wrong awareness level or sophistication stage dooms everything after it. Present your reading with the evidence from the briefing that supports it, and wait for the human to confirm or correct.
+
+**Gate 2 · mechanisms approved.** The whole VSL derives from the mechanism; getting it wrong means re-recording the video. Present the 5x5 document; the human picks **one master problem mechanism and one master solution mechanism**, and only then Phase 4 starts.
+
+Record both in `manifest.json` and check the manifest before writing any line of the VSL. An empty field means stop and go back to the missing phase. **A gate reopens when the base changes:** if the briefing, the offer or the price changes after Gate 2, clear `gate2_aprovado_em`, say what changed and present again.
+
+## Never present invented proof as real
+
+Direct response copy that invents gets refunds, lawsuits and platform bans.
+
+- Never invent a testimonial, number, study, student case, credential, date or story and present it as fact. Missing information becomes an explicit marker: `[DEPOIMENTO]`, `[NÚMERO A CONFIRMAR]`, `[A DEFINIR]`, `[LACUNA]`. Missing proof does not block the rest of the script: the marker holds the place.
+- **Traceability.** When the source material (call, questionnaire, the expert's material, the approved offer) already carries the mechanism, the story or the number, it is the master source: cite where it came from (file plus timestamp or line). Your own synthesis never replaces it; it enters at most as a variation marked `🆕 proposta nova (não veio da fonte)`.
+- **The numbers in this skill are not copy.** Benchmarks and percentages in the references (play rate, retention, conversion) are internal calibration ranges, not public facts. Never repeat them inside the VSL, in an ad or to the client as market fact.
+
+| Rationalization | Reality |
+|---|---|
+| "It's just an illustrative testimonial" | It goes into the recorded video as written. Use `[DEPOIMENTO]`. |
+| "This number is plausible for the niche" | Plausible is not verifiable. The expert answers or it stays `[NÚMERO A CONFIRMAR]`. |
+| "My metaphor came out better than theirs" | Maybe. Mark it as a new proposal and let the human choose at Gate 2. |
+| "The expert didn't answer, I'll deduce from the niche" | A niche deduction is a hypothesis, not a briefing. Mark `[LACUNA]`. |
+
+**Stop when:** you are writing a number nobody gave you, telling a story that was not in the material, writing the offer block without knowing the price, or writing the lead before the offer.
+
+## Default length (outside the low ticket ruler)
+
+A front-end VSL runs **16 to 20 minutes**: the four blocks before the pitch add up to 12 to 14 minutes and the pitch takes 4 to 6. When the diagnosis asks for a short VSL (awareness 4 or 5, volume niche), compress proportionally to 6 to 8 minutes with the pitch near the middle; the structure is the same. Treat length as an output of the argument: never pad or cut only to hit a runtime.
+
+## Output
+
+In `{output_folder}/vsl/<slug>/` (slug from the product or expert; if neither has a name yet, the theme). Never rename the folder later. If several `vsl/*` folders exist, ask which one.
+
+```
+00-briefing.md        interview answers, each with its source
+01-diagnostico.md     mass desire, awareness, sophistication + evidence
+02-mecanismos-5x5.md  10 proposals + recommendation (decision document)
+03-vsl-principal.md   the full VSL, in presentation order
+03-leads/             lead-01-<angulo>.md ... lead-05-<angulo>.md
+04-qa.md              claims ledger, checklist, A/B test plan, target metrics
+05-beat-sheet.md      narration, on-screen line, visual evidence and claim per beat
+manifest.json         phase state and both gates
+```
+
+Create `manifest.json` in Phase 0 with what you already know (the rest stays `null`) and update `fases` at each transition:
+
+```json
+{
+  "expert": "<nome>",
+  "produto": "<nome do produto>",
+  "nicho": "financeiro|saude|mudanca-de-vida|profissional|volume",
+  "low_ticket": false,
+  "regua": "default|lowticket",
+  "criado_em": "AAAA-MM-DD",
+  "fontes": { "oferta": null, "pesquisa_publico": null },
+  "fases": { "intake": "pendente", "diagnostico": "pendente", "mecanismos": "pendente",
+             "escrita": "pendente", "qa": "pendente", "producao": "pendente" },
+  "gate1_confirmado_em": null, "consciencia": null, "sofisticacao": null,
+  "gate2_aprovado_em": null, "aprovado_por": null,
+  "mecanismo_problema": null, "mecanismo_solucao": null, "camadas": []
+}
+```
+
+## Writing order versus presentation order
+
+| Written in this order | The viewer sees this order |
+|---|---|
+| 1. Offer (pitch) | 1. Lead |
+| 2. Solution mechanism | 2. Problem mechanism |
+| 3. Problem mechanism | 3. Story |
+| 4. Story | 4. Solution mechanism |
+| 5. **Lead (5 variations)** | 5. Offer (pitch) |
+
+Writing the offer first is what makes the lead promise exactly what the offer delivers.
+
+## Hand-off
+
+- **Review.** For the mechanism (Phase 3) and the lead, ask a different agent than the one that wrote it to judge each proposal as kill, keep with caveat, or keep. A disagreement between maker and checker goes to the human at Gate 2 with both opinions side by side.
+- **Voice pass.** Invoke the `wizz-humanizer` skill on the assembled script after the claims are right, never before.
+- **Production** is not this skill. The beat sheet goes to the designer area (offer `wizz-maestro` when the user wants the video in the same delivery): the TTS or recorded narration comes first, the `wizz-ctc-align` skill turns the final audio into word timings, `hyperframes` draws each silent scene, and the `wizz-remotion-best-practices` skill assembles the film with audio, captions and motion anchored to those timings. Details and the player QA: [references/production.md](references/production.md).
+- **The page around the player** (no headline above the video, delayed button, no coupon) is copy for the `wizz-copywriting` skill with the rules listed in [references/offer.md](references/offer.md).
+
+## When not to use
+
+A standalone ad, an email, a capture page, a post: they have neither the four blocks nor a pitch. Ad creative scripts are `wizz-ad-creative`; Reels and Shorts are `wizz-social-content`; the sales page text is `wizz-copywriting`.
+
+## Credits
+
+Method synthesized and adapted from two MIT skills, with permission notices in [LICENSE](LICENSE) and `THIRD-PARTY-NOTICES.md`: `yuribranco/vsl-skill` (interview, gates, 5x5 mechanisms, backwards writing, leads, niches, QA), whose own lineage is the VSL method taught by Lucas Ramos (Veritas Club), Eugene Schwartz's *Breakthrough Advertising*, *Great Leads* (Masterson and Forde) and Alex Hormozi's value equation; and `bertrand-do/video-sales-letter` (claims ledger, script-only audit, beat sheet, word-timed motion, player QA, OTO and downsell). Read the originals: this skill works far better in the hands of someone who studied them.

package/src/skills-lib/wizz-vsl/references/assembly-qa.md

@@ -0,0 +1,123 @@
+# Phase 5 · Assembly, claims ledger, QA and test plan
+
+## Assembly: from writing order to presentation order
+
+You wrote offer → solution → problem → story → leads. Now reassemble in the order the viewer sees:
+
+```
+[GUARDRAIL · LEI]  (cabeçalho interno, não vai pro vídeo)
+
+LEAD (default: <qual e por quê>)
+MECANISMO DO PROBLEMA
+HISTÓRIA
+MECANISMO DA SOLUÇÃO
+OFERTA / PITCH            ← entra na virada que a régua em vigor define
+```
+
+Check the sum against the ruler in effect. Default: at 140 to 150 words per minute, the 12 to 14 minute window before the pitch asks for **1,750 to 2,000 words** in the first four blocks; below that the pitch falls too early, and the fix is deeper blocks, not an earlier pitch. Under the low ticket ruler, the pitch enters at about two thirds of the runtime it sets.
+
+At the seams, check the **transitions**: each block ends pulling the next. Cut any recap ("como eu falei lá no começo"): in video it is permission to leave.
+
+### Script markers
+
+| Marker | Where |
+|---|---|
+| `[DEPOIMENTO]` | where social proof goes (never write the testimonial) |
+| `[BOTÃO APARECE AQUI]` | step 8 of the pitch, when the price is revealed (once) |
+| `[CRONÔMETRO 60s]` | the urgency bonus, **if it exists** |
+| `[A DEFINIR]` / `[NÚMERO A CONFIRMAR]` | any data the briefing did not bring |
+| `[B-ROLL: …]` / `[TELA: …]` | suggested image or screen; feeds the beat sheet |
+
+### File header
+
+```markdown
+# VSL · <produto> (DRAFT v1)
+
+> **Régua:** <default 16-20 min | lowticket: <duração e posição do pitch, com o shard citado>>
+> **Lead default:** <qual> · testar as de `03-leads/`.
+> **Mecanismos aprovados (GATE 2, <data>):** problema = <P_> · solução = <S_>
+> **Diagnóstico:** consciência N / sofisticação M
+> **GUARDRAIL (LEI):** <proibições do Bloco 9>
+> **Voz:** <resumo do Bloco 10>
+> **Fontes:** `00-briefing.md`, <oferta aprovada>, <pesquisa do Piva>
+```
+
+## Claims ledger
+
+Before QA, list every claim the script makes and check each against the **real product and the real terms**, not against an old handoff or a prior script: price, limits, allowances, speed, results, compatibility, scarcity, refund terms. Historical documents explain decisions but may carry obsolete versions.
+
+| # | Claim (as spoken) | Type | Source that proves it | Status |
+|---|---|---|---|---|
+| 1 | "acesso por 12 meses" | access | checkout config, `00-briefing.md` 1.2 | ✅ confere |
+| 2 | "resultado na primeira semana" | result | `[LACUNA 5.7]` | ⚠️ marcar `[A CONFIRMAR]` ou reescrever |
+
+Separate product behaviour from buyer action: drafting is not sending; finding is not guaranteeing. A guarantee line matches the policy word for word. When a price, date or count changes, remove every stale mention together (script, on-screen lines, captions, page).
+
+## Script-only audit
+
+1. **Narration alone.** Read every spoken line without visuals. Does each beat add meaning?
+2. **On-screen lines alone.** Read only the text that will appear on screen. Does it form a coherent argument and match the narration?
+3. **Vague referents.** Resolve "isso", "ele", "outro", "mais uma parte", "o que vem a seguir" when the referent is not clear. Keep natural fragments and questions when their meaning is clear.
+4. **Proof matches claim.** The demo or proof shown proves the exact claim spoken, not a neighbouring one.
+
+Invoke the `wizz-humanizer` skill as the final voice pass, after the claims are right.
+
+## QA checklist: close all before delivering
+
+**Structure**
+- [ ] Offer written first, the 15 steps covered (the ones that do not apply recorded as absent, not invented)
+- [ ] Solution mechanism gives *what* + *why*, **not** the *how*
+- [ ] Problem mechanism follows the formula (attempts + why they failed = root cause)
+- [ ] Problem block ends with "existe uma saída"
+- [ ] Story in the right format; no rock-bottom hero journey
+- [ ] Leads with different angles, each with a teaser, in the number the ruler asks for
+- [ ] Pitch position and total runtime match the ruler in effect
+
+**Offer**
+- [ ] Triad communicated; a missing layer flagged, never invented
+- [ ] Modules described by benefit
+- [ ] Anchor before price, against a real alternative
+- [ ] Timer bonus, **or** recorded as non-existent and why
+- [ ] Each bonus with its origin story
+- [ ] Express stack with values
+- [ ] Clear guarantee matching the real terms
+- [ ] Emotional close + single CTA
+
+**Integrity**
+- [ ] No testimonial, number, study or case presented as real without a source
+- [ ] Every claim in the ledger with a source or a marker
+- [ ] Third-party names only with recorded authorization
+- [ ] Compliance guardrail respected line by line
+- [ ] No promise the offer does not deliver
+
+**Voice and form**
+- [ ] Spoken language, read aloud without stumbling
+- [ ] The audience's vocabulary
+- [ ] No AI words
+- [ ] Second person, except where compliance requires third
+
+**Page and player** (hand-off to `wizz-copywriting`)
+- [ ] No headline above the video · no form before the VSL · no discount coupon · button delay after the price
+
+## Target metrics (internal calibration, front-end VSL)
+
+> Reference ranges **without an auditable public source**: they decide what to optimize first. Never inside the VSL, an ad, or a client conversation as market fact. Under the low ticket ruler, the numbers in `13-benchmarks-vsl.md` replace these.
+
+| Metric | Target | If below |
+|---|---|---|
+| Play rate | 50-60% | The problem is the page or the traffic source, not the copy |
+| 1st-minute retention | 60-70% | **The lead is weak.** Swap the lead before anything else |
+| Retention up to the pitch | 85-95% **of those still there at minute 1** | A middle block is losing people: find the drop in the chart |
+| Front-end conversion | 3.8-4% typical, 8% exceptional | Offer, price or promise misaligned |
+
+**Mind the denominator:** play rate = plays ÷ **page visits**; 1st-minute retention = reached minute 1 ÷ **plays**; retention to pitch = reached the pitch ÷ **reached minute 1**; conversion = purchases ÷ **page visits**. Read them in that order: optimizing the offer while the lead bleeds is waste.
+
+## Test plan
+
+- Run **control + challengers at the same time**: the control is the best current VSL; challengers are the variations under test.
+- Most variations tested are **in the lead**, the biggest lever.
+- Typical split: 90% control / 10% shared among 2 or 3 challenger leads. Never throw all leads in one round: each would get too little volume to decide.
+- **At least 500 to 1,000 unique views per variant** before declaring a winner. Below that it is noise.
+- A winning challenger becomes the new control. Start again.
+
+Record in `04-qa.md`: what is tested, against what, which metric decides, and the minimum volume. A test without a decision criterion set beforehand becomes an opinion argument afterwards.