wizz-method 2.17.2 → 2.19.0

package/src/skills-lib/wizz-video-styles/references/styles/tipografia-cinetica.md

@@ -0,0 +1,68 @@
+# Kinetic typography and lyric video (mexicat P(doom), PixelValet, Ninh Truong)
+
+Measured on 5 shorts (en) in: product / SaaS / marketing / business / law, education / science / comedy, music / artists / lyric videos.
+
+## Measured
+
+| Metric | Value |
+|---|---|
+| Reach (views) | max 1,215,529 · median 353,630 |
+| Cuts per 10 s | min 0.63 · median 3.57 · max 5.54 |
+| Median scene length | 1.54 s |
+| Music bed (continuous / faint / none) | 3 / 0 / 2 |
+| Cuts with a sound effect on them | 31/94 (33%) |
+
+Cuts come from scene detection (it undercounts overlays and cards); music and SFX from an audio heuristic that classifies type, never names the sound ([../research-method.md](../research-method.md)).
+
+## Material it 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.
+
+## When it 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.
+
+## Recipe
+
+**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.
+
+**Typography:** 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 (0 to 3 s):** 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.
+
+## Do not
+
+- 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%.
+
+## Watch before editing
+
+- [PiXeL ARTWORKS](https://www.youtube.com/watch?v=9ngNySFSWWU) · 1,215,529 views
+- [PixelValet](https://www.youtube.com/watch?v=Kt8vGm8_ekQ) · 928,526 views
+- [Cinthya Studios](https://www.youtube.com/watch?v=A0CKFb24MJ8) · 353,630 views
+- [Ninh Truong](https://www.youtube.com/watch?v=FOMWS5pChuA) · 243,944 views
+- [mexicat](https://www.youtube.com/watch?v=5EoO5413dBY) · 120,706 views

package/src/skills-lib/wizz-video-styles/references/styles/ui-morph.md

@@ -0,0 +1,68 @@
+# UI morph: one shape, many UI states (twoclipping, verbove, AnnaCher)
+
+Measured on 6 shorts (en) in: dev / AI / build in public (EN), product / SaaS / marketing / business / law.
+
+## Measured
+
+| Metric | Value |
+|---|---|
+| Reach (views) | max 1,164,424 · median 2,786 |
+| Cuts per 10 s | min 0.0 · median 0.0 · max 0.0 |
+| Median scene length | 17.05 s |
+| Music bed (continuous / faint / none) | 4 / 0 / 2 |
+| Cuts with a sound effect on them | 0/0 |
+
+Cuts come from scene detection (it undercounts overlays and cards); music and SFX from an audio heuristic that classifies type, never names the sound ([../research-method.md](../research-method.md)).
+
+## Material it needs
+
+The product's real screens or a list of 8 to 12 UI states that tell its story (button, loader, player, slider, toggle, tabs, chart, ⌘K, toast), one accent colour and a track around 120 BPM. Nobody on camera, no footage: everything is drawn in code (HyperFrames).
+
+## When it fits
+
+App and SaaS launches, a feature announcement, a product promo for the site or the store page, a portfolio piece. Strong on X and LinkedIn with a product audience; it shows the product working instead of describing it. Weak for teaching step by step or for anything that needs a face.
+
+## Recipe
+
+**Look**
+
+- One shape on screen the whole time, never cut: it becomes button, loader, player, slider, toggle, tabs, chart, ⌘K and toast, changing size, corners and colour (the same language as the iPhone Dynamic Island).
+- Warm light grey canvas (#EDEBE6), components in black and white, at most one accent colour; a dark variant (navy with one yellow) for a product film.
+- Real UI and real data: the product's own labels and numbers, never lorem ipsum or generic components.
+- A cursor drives every change with real clicks and drags; the camera zooms so each state fills the frame.
+
+**Palette:** Warm grey #EDEBE6 or beige #E6E2DA, black #111, white, plus ONE accent (orange, peach or yellow) used only where the eye must go. Dark variant: #0B1020 base, one yellow accent.
+
+**Typography:** One UI sans (Inter, Geist or the product's own font) in regular and semibold; mono only for a URL or a code line. No display fonts.
+
+**Motion**
+
+- Every state grows out of the previous one by a spring (size, corner radius, colour), with at most one small overshoot; content swaps with a short blur.
+- Something happens on every beat; the state changes land on the downbeats of the beat grid (scripts/beat_grid.py), not on a hand-counted 120 BPM.
+- Build it as a pure function of time (seek(t)): closed-form springs, no CSS transitions or timers, so every frame renders the same. HyperFrames does this natively.
+- The last frame equals the first, so the piece loops.
+
+**Captions:** None. The text is the interface's own (button labels, track title, chart numbers). A single short line at most, in the UI font, when the product needs one sentence.
+
+**Hook (0 to 3 s):** The first state already on screen at 0 s (a button or the brand pill) and the cursor arriving on the first beat. No logo intro, no title card.
+
+**CTA:** The shape returns to the first state or closes on the brand pill with the URL in small mono under it, held 1 to 2 s.
+
+**Music:** The track is the whole soundtrack: a continuous bed in 4 of 6 measured pieces, around -14 LUFS. Pick an electronic or lo-fi track with a clear kick so the beat grid is reliable.
+
+**SFX:** Sparse and tied to UI events: a soft click on a press, a low tick on a snap. The measured pieces range from none to a hit on most state changes; never whooshes on every move.
+
+## Do not
+
+- Cutting between screens: the moment it cuts it becomes a screen recording, not this style.
+- Bouncy easing, particles, glow, gradients on the UI chrome, icons with uneven stroke, dead time, template look.
+- Generic components instead of the product's real UI and numbers.
+- Shipping square or 16:9: every measured piece is 1:1 or 16:9; recompose for 9:16 with the shape in the upper-middle and nothing in the bottom 20 %.
+
+## Watch before editing
+
+- [zero](https://x.com/twoclipping/status/2103273003555402193) · 1,164,424 views
+- [Martijn Verbove](https://x.com/verbove/status/2103483957266268381) · 17,438 views
+- [Daniel Haida](https://x.com/daniel_haida/status/2104139720829636937) · 3,968 views
+- [Anna Chernikova](https://x.com/AnnaCher___/status/2103571096549433425) · 1,605 views
+- [Nez](https://x.com/nezbuilds/status/2103487427365294391) · 519 views

package/src/skills-lib/wizz-video-styles/scripts/analyze.sh

@@ -1,25 +1,38 @@
 #!/usr/bin/env bash
-# Measures one public YouTube short: download (720p), cuts (scene detection),
+# Measures one public short: download (720p), cuts (scene detection),
 # audio (music bed, SFX type heuristic, loudness) and a 16-frame contact sheet.
-# Usage: analyze.sh <youtube_id> <out_dir>  →  <out_dir>/<id>.json + <id>-sheet.png
+# Usage: analyze.sh <youtube_id|url> <out_dir>  →  <out_dir>/<id>.json + <id>-sheet.png
+# A URL (an X post, any page yt-dlp reads) is measured the same way; its id is
+# x-<author>-<status> for X and a sanitised slug otherwise (2026-10-15: the
+# code-generated UI pieces of the ui-morph style live on X, not on YouTube).
 # The .mp4 is deleted at the end; read the contact sheet before describing the look.
 set -euo pipefail
-[ $# -eq 2 ] || { echo "uso: analyze.sh <youtube_id> <out_dir>" >&2; exit 2; }
+[ $# -eq 2 ] || { echo "uso: analyze.sh <youtube_id|url> <out_dir>" >&2; exit 2; }
 id="$1"; out="$2"
-[[ "$id" =~ ^[A-Za-z0-9_-]{11}$ ]] || { echo "id inválido: $id" >&2; exit 2; }
+if [[ "$id" =~ ^https?:// ]]; then
+  url="$id"
+  if [[ "$url" =~ (x|twitter)\.com/([A-Za-z0-9_]+)/status/([0-9]+) ]]; then
+    id="x-${BASH_REMATCH[2]}-${BASH_REMATCH[3]}"
+  else
+    id=$(printf '%s' "$url" | sed -E 's#^https?://##; s#[^A-Za-z0-9_-]+#-#g' | cut -c1-60)
+  fi
+else
+  [[ "$id" =~ ^[A-Za-z0-9_-]{11}$ ]] || { echo "id inválido: $id" >&2; exit 2; }
+  url="https://www.youtube.com/shorts/$id"
+fi
 mkdir -p "$out"; cd "$out"
 f="./$id"  # prefixo ./ : ID que começa com hífen não vira opção do ffmpeg
-trap 'rm -f "$f.wav" "$f.mp4"' EXIT
+# .part: a first download that fails (HTTP 403) leaves it behind before the android fallback runs.
+trap 'rm -f "$f.wav" "$f.mp4" "$f".*.part' EXIT
 # Python with librosa + numpy: set VIDEO_STYLES_PY to a venv python, or python3 must have them.
 PY="${VIDEO_STYLES_PY:-python3}"
 "$PY" -c "import librosa, numpy" 2>/dev/null || { echo "precisa de librosa e numpy: pip install librosa numpy (ou VIDEO_STYLES_PY=/caminho/do/python)" >&2; exit 2; }
 for bin in yt-dlp ffmpeg ffprobe; do command -v "$bin" >/dev/null || { echo "falta $bin no PATH" >&2; exit 2; }; done
-url="https://www.youtube.com/shorts/$id"
 fmt="bv*[height<=1280][ext=mp4]+ba[ext=m4a]/b[ext=mp4]/b"
 # When YouTube answers "confirm you're not a bot", the android player client usually still works (no cookies used).
 [ -f "$f.mp4" ] || yt-dlp -q --no-warnings -f "$fmt" --merge-output-format mp4 -o "$f.mp4" "$url" \
   || yt-dlp -q --no-warnings --extractor-args "youtube:player_client=android" -f "$fmt" --merge-output-format mp4 -o "$f.mp4" "$url"
-meta_fmt="%(view_count)s|%(like_count)s|%(channel)s|%(upload_date)s|%(title)s"
+meta_fmt="%(view_count)s|%(like_count)s|%(channel,uploader)s|%(upload_date)s|%(title)s"
 yt-dlp -q --no-warnings --skip-download --print "$meta_fmt" "$url" > "$f.meta" \
   || yt-dlp -q --no-warnings --skip-download --extractor-args "youtube:player_client=android" --print "$meta_fmt" "$url" > "$f.meta" \
   || echo "NA|NA|NA|NA|NA" > "$f.meta"
@@ -31,9 +44,9 @@ lufs=$(ffmpeg -i "$f.mp4" -af ebur128 -f null - 2>&1 | grep -E "^\s+I:" | tail -
 d=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$f.mp4")
 step=$(python3 -c "print(max(1.0, $d/16))")
 ffmpeg -loglevel error -y -i "$f.mp4" -vf "fps=1/$step,scale=200:-1,tile=8x2" -frames:v 1 "$f-sheet.png"
-"$PY" - "$id" "$lufs" <<'PY'
+"$PY" - "$id" "$lufs" "$url" <<'PY'
 import librosa, numpy as np, json, sys
-id, lufs = sys.argv[1], sys.argv[2]
+id, lufs, url = sys.argv[1], sys.argv[2], sys.argv[3]
 y, sr = librosa.load(f"{id}.wav", sr=22050); dur = len(y)/sr
 cuts = [float(x) for x in open(f"{id}.cuts").read().split()]
 H, P = librosa.effects.hpss(y, margin=2.0)
@@ -57,7 +70,7 @@ on_cut = sum(1 for c in cuts if any(abs(t-c) < 0.15 for t,_ in events))
 shots = np.diff([0]+cuts+[dur]) if dur else np.array([0])
 bed = float(np.percentile(rh,15)/(np.percentile(rh,95)+1e-9))
 meta = open(f"{id}.meta").read().strip().split("|", 4)
-json.dump({"id": id, "url": f"https://www.youtube.com/shorts/{id}", "views": meta[0], "likes": meta[1], "channel": meta[2], "upload_date": meta[3], "title": meta[4],
+json.dump({"id": id, "url": url, "views": meta[0], "likes": meta[1], "channel": meta[2], "upload_date": meta[3], "title": meta[4],
   "duration_s": round(dur,1), "cuts": len(cuts), "cuts_per_10s": round(len(cuts)/dur*10,2), "shot_median_s": round(float(np.median(shots)),2), "shot_mean_s": round(float(shots.mean()),2),
   "music_bed_ratio": round(bed,3), "music_bed_guess": "continua" if bed > 0.13 else ("fraca" if bed > 0.07 else "sem"),
   "sfx_counts": kinds, "sfx_per_10s": round(sum(kinds.values())/dur*10,2), "sfx_on_cuts": f"{on_cut}/{len(cuts)}", "sfx_events": events[:40],

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

@@ -0,0 +1,68 @@
+"""Beat grid of a song: tempo, beats and downbeats, so scene cuts can snap to the music.
+
+Usage: python3 beat_grid.py <audio_file> [--meter 4] [--fps 30] > grid.json
+
+Prints JSON: {"bpm", "meter", "duration_s", "beats": [s...], "downbeats": [s...],
+"downbeat_frames": [frame...]}. Needs librosa + numpy (same Python as analyze.sh;
+set VIDEO_STYLES_PY and call it with that interpreter).
+
+Downbeats are estimated, not detected: of the `meter` possible phases, the one
+whose beats carry the most low-frequency onset energy is taken as beat 1. Check
+two or three of them by ear before cutting a whole film on the grid.
+"""
+
+import argparse
+import json
+import sys
+
+import librosa
+import numpy as np
+
+HOP = 512
+LOW_HZ = 150
+
+
+def downbeat_phase(y_perc, sr, beat_frames, meter):
+    spec = np.abs(librosa.stft(y_perc, hop_length=HOP))
+    freqs = librosa.fft_frequencies(sr=sr)
+    low_energy = spec[freqs < LOW_HZ].sum(axis=0)
+    at_beats = low_energy[np.minimum(beat_frames, len(low_energy) - 1)]
+    scores = [at_beats[phase::meter].mean() if len(at_beats[phase::meter]) else 0.0 for phase in range(meter)]
+    return int(np.argmax(scores))
+
+
+def beat_grid(path, meter, fps):
+    y, sr = librosa.load(path, sr=22050, mono=True)
+    _, y_perc = librosa.effects.hpss(y)
+    _, beat_frames = librosa.beat.beat_track(y=y_perc, sr=sr, hop_length=HOP)
+    if len(beat_frames) < meter:
+        sys.exit(f"too few beats found in {path}: {len(beat_frames)} (is there a steady rhythm?)")
+    beats = librosa.frames_to_time(beat_frames, sr=sr, hop_length=HOP)
+    phase = downbeat_phase(y_perc, sr, beat_frames, meter)
+    downbeats = beats[phase::meter]
+    return {
+        # librosa's tempo and single beat intervals are quantised to the hop; the slope of a
+        # line fitted through every beat time averages that out.
+        "bpm": round(60.0 / float(np.polyfit(np.arange(len(beats)), beats, 1)[0]), 3),
+        "meter": meter,
+        "duration_s": round(len(y) / sr, 3),
+        "beats": [round(float(t), 3) for t in beats],
+        "downbeats": [round(float(t), 3) for t in downbeats],
+        "downbeat_frames": [int(round(t * fps)) for t in downbeats],
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("audio")
+    parser.add_argument("--meter", type=int, default=4)
+    parser.add_argument("--fps", type=int, default=30)
+    args = parser.parse_args()
+    if args.meter < 2 or args.fps < 1:
+        sys.exit("--meter must be >= 2 and --fps >= 1")
+    json.dump(beat_grid(args.audio, args.meter, args.fps), sys.stdout, indent=1)
+    print()
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+// Fresh references for a style, without repeating what the project already used.
+//
+//   node references.mjs pick --style <key> [--project <dir>] [--n 4] [--offline] [--json]
+//   node references.mjs record --style <key> --piece <slug> --refs <id,id> [--project <dir>]
+//   node references.mjs history [--project <dir>] [--json]
+//
+// pick: measured references of the style (data/references.json) plus, for styles that are
+// generated in code, viral videos from the awesome-opus5-5-videos list (fetched fresh, cached
+// for 7 days, cache used when offline). Anything already in the project's history is skipped;
+// different channels/authors come first. Also warns when the same style was used in the last
+// pieces, so the edit does not keep coming out with the same look.
+// record: appends the piece to <project>/_wizz-output/video-styles/historico.json.
+// The fetched list is third-party data: only links and a short excerpt are printed, never run.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SKILL_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const LIST_URL = 'https://raw.githubusercontent.com/yihui-dev/awesome-opus5-5-videos/main/data/videos.json';
+const CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 8000;
+const EXCERPT_CHARS = 160;
+const MEASURED_PER_PICK = 2;
+const REPEAT_WINDOW = 2;
+const HISTORY_REL = path.join('_wizz-output', 'video-styles', 'historico.json');
+
+// Which generated videos feed which catalogue style. Styles that are filmed (talking head,
+// tour, macro...) have no entry: a code-generated video is not a reference for them.
+const GENERATED = {
+  'tipografia-cinetica': { categories: ['motion', 'explainer', '3d'], match: /lyric|music video|kinetic typograph|\bMV\b/i },
+  'ui-morph': { categories: ['motion', 'explainer', '3d', 'interactive'], match: /UI states|one shape|morph|UI moments|product film|inside the app/i },
+  'motion-editorial': { categories: ['motion', 'explainer'], match: /\bUI\b|product|launch|saas|\bapp\b|logo|promo|brand/i },
+  'explicador-animado': { categories: ['explainer'], match: /./ },
+  'quadro-branco': { categories: ['explainer', 'motion'], match: /whiteboard|hand-drawn|sketch|doodle/i },
+  'meme-rapido': { categories: ['motion'], match: /brain ?rot|meme|chaotic/i },
+};
+
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const options = { command, project: process.cwd(), n: 4, offline: false, json: false };
+  for (let i = 0; i < rest.length; i++) {
+    const flag = rest[i];
+    if (flag === '--offline') options.offline = true;
+    else if (flag === '--json') options.json = true;
+    else if (['--style', '--project', '--n', '--piece', '--refs'].includes(flag)) options[flag.slice(2)] = rest[++i];
+    else fail(`unknown argument: ${flag}`);
+  }
+  options.n = Number(options.n);
+  if (!Number.isInteger(options.n) || options.n < 1 || options.n > 20) fail('--n must be an integer from 1 to 20');
+  return options;
+}
+
+function fail(message) {
+  process.stderr.write(`references: ${message}\n`);
+  process.exit(2);
+}
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return fallback;
+    fail(`cannot read ${file}: ${error.message}`);
+  }
+}
+
+function writeJsonAtomic(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+  fs.renameSync(tmp, file);
+}
+
+function loadHistory(project) {
+  const history = readJson(path.join(project, HISTORY_REL), []);
+  if (!Array.isArray(history)) fail(`${HISTORY_REL} must be a JSON array`);
+  return history;
+}
+
+function knownStyles() {
+  return Object.keys(readJson(path.join(SKILL_DIR, 'data', 'recipes.json'), { styles: {} }).styles);
+}
+
+function requireStyle(style) {
+  if (!style) fail('--style is required');
+  const styles = knownStyles();
+  if (!styles.includes(style)) fail(`unknown style "${style}". Known: ${styles.join(', ')}`);
+}
+
+const isHttpsUrl = (value) => typeof value === 'string' && value.startsWith('https://');
+
+function validVideos(data) {
+  if (!Array.isArray(data)) return null;
+  return data.filter(
+    (v) => v && typeof v.slug === 'string' && typeof v.category === 'string' && isHttpsUrl(v.post_url) && isHttpsUrl(v.skillry_url),
+  );
+}
+
+function cachePath() {
+  return process.env.WIZZ_VIDEO_STYLES_CACHE || path.join(os.homedir(), '.cache', 'wizz-video-styles', 'opus-videos.json');
+}
+
+async function loadGeneratedList(offline) {
+  const file = cachePath();
+  let cached = null;
+  let age = Infinity;
+  try {
+    age = Date.now() - fs.statSync(file).mtimeMs;
+    cached = validVideos(JSON.parse(fs.readFileSync(file, 'utf8')));
+  } catch {
+    cached = null;
+  }
+  if (cached && (offline || age < CACHE_MAX_AGE_MS)) return { videos: cached, source: `cache (${Math.round(age / 3_600_000)} h old)` };
+  if (offline) return { videos: [], source: 'offline and no cache' };
+  try {
+    const response = await fetch(LIST_URL, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    const videos = validVideos(await response.json());
+    if (!videos) throw new Error('unexpected format');
+    writeJsonAtomic(file, videos);
+    return { videos, source: 'fetched now' };
+  } catch (error) {
+    if (cached) return { videos: cached, source: `cache, refresh failed (${error.message})` };
+    return { videos: [], source: `unavailable (${error.message})` };
+  }
+}
+
+// Greedy pick: unused first, then a new channel/author before repeating one.
+function pickDiverse(items, keyOf, used, count) {
+  const fresh = items.filter((item) => !used.has(item.id));
+  const chosen = [];
+  const seenKeys = new Set();
+  for (const pass of [true, false]) {
+    for (const item of fresh) {
+      if (chosen.length >= count) break;
+      if (chosen.includes(item) || (pass && seenKeys.has(keyOf(item)))) continue;
+      chosen.push(item);
+      seenKeys.add(keyOf(item));
+    }
+  }
+  return { chosen, exhausted: fresh.length === 0 && items.length > 0 };
+}
+
+function measuredFor(style) {
+  return readJson(path.join(SKILL_DIR, 'data', 'references.json'), [])
+    .filter((r) => r.style === style)
+    .sort((a, b) => Number(b.views) - Number(a.views))
+    .map((r) => ({ id: r.id, kind: 'measured', who: r.channel, url: r.url, note: `${Number(r.views).toLocaleString('en-US')} views` }));
+}
+
+const PROMPT_KEY_CHARS = 80;
+const promptKey = (prompt) => String(prompt ?? '').toLowerCase().replaceAll(/[^a-z0-9]+/g, ' ').trim().slice(0, PROMPT_KEY_CHARS);
+
+// Third-party text: one line, no markdown or HTML that could turn into a link or a tag.
+const excerpt = (prompt) =>
+  String(prompt ?? '')
+    .replaceAll(/[`<>[\]()]/g, '')
+    .replaceAll(/\s+/g, ' ')
+    .trim()
+    .slice(0, EXCERPT_CHARS);
+
+function generatedFor(style, videos) {
+  const rule = GENERATED[style];
+  if (!rule) return [];
+  // The same viral prompt was remade by dozens of people: one remake per prompt is enough.
+  const seenPrompts = new Set();
+  return videos
+    .filter((v) => rule.categories.includes(v.category) && rule.match.test(String(v.prompt ?? '')))
+    .sort((a, b) => String(b.added ?? '').localeCompare(String(a.added ?? '')))
+    .filter((v) => {
+      const key = promptKey(v.prompt);
+      if (seenPrompts.has(key)) return false;
+      seenPrompts.add(key);
+      return true;
+    })
+    .map((v) => ({
+      id: v.slug,
+      kind: 'generated',
+      who: String(v.author ?? '?'),
+      url: v.skillry_url,
+      post: v.post_url,
+      note: excerpt(v.prompt),
+    }));
+}
+
+function styleRepeat(history, style) {
+  const recent = history.slice(-REPEAT_WINDOW).map((entry) => entry.style);
+  return recent.length === REPEAT_WINDOW && recent.every((s) => s === style);
+}
+
+async function pick(options) {
+  requireStyle(options.style);
+  const history = loadHistory(options.project);
+  const used = new Set(history.flatMap((entry) => entry.refs ?? []));
+  const measured = pickDiverse(measuredFor(options.style), (r) => r.who, used, Math.min(MEASURED_PER_PICK, options.n));
+  let generated = { chosen: [], exhausted: false };
+  let source = 'not used for this style (filmed style)';
+  if (GENERATED[options.style]) {
+    const list = await loadGeneratedList(options.offline);
+    source = list.source;
+    generated = pickDiverse(generatedFor(options.style, list.videos), (r) => r.who, used, options.n - measured.chosen.length);
+  }
+  return {
+    style: options.style,
+    recentStyles: history.slice(-5).map((entry) => entry.style),
+    styleRepeated: styleRepeat(history, options.style),
+    references: [...measured.chosen, ...generated.chosen],
+    measuredExhausted: measured.exhausted,
+    generatedExhausted: generated.exhausted,
+    generatedSource: source,
+  };
+}
+
+function printPick(result) {
+  const lines = [`# References for ${result.style}`, ''];
+  if (result.recentStyles.length) lines.push(`Last styles in this project: ${result.recentStyles.join(' → ')}`);
+  if (result.styleRepeated) {
+    lines.push(
+      `REPEAT: the last ${REPEAT_WINDOW} pieces already used ${result.style}. Unless this is a deliberate series, pick another style the material allows, or keep it only for the hook/CTA and mix another in the middle.`,
+    );
+  }
+  lines.push(`Generated list: ${result.generatedSource}`, '');
+  for (const ref of result.references) {
+    const post = ref.post ? ` · [post](${ref.post})` : '';
+    lines.push(`- [${ref.kind}] ${ref.who} · [watch](${ref.url})${post} · id \`${ref.id}\` · ${ref.note}`);
+  }
+  if (result.references.length === 0) lines.push('- nothing new left for this style');
+  if (result.measuredExhausted) lines.push('', 'Every measured reference of this style was already used here: measure new ones (research-method.md).');
+  if (result.generatedExhausted) lines.push('', 'Every generated reference of this style was already used here.');
+  lines.push('', 'After delivering the piece: node references.mjs record --style <key> --piece <slug> --refs <ids you watched>');
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+function record(options) {
+  requireStyle(options.style);
+  if (!options.piece) fail('--piece is required');
+  const refs = String(options.refs ?? '')
+    .split(',')
+    .map((id) => id.trim())
+    .filter(Boolean);
+  if (refs.length === 0) fail('--refs is required (ids printed by pick)');
+  const history = loadHistory(options.project);
+  const entry = { date: new Date().toISOString().slice(0, 10), piece: options.piece, style: options.style, refs };
+  writeJsonAtomic(path.join(options.project, HISTORY_REL), [...history, entry]);
+  process.stdout.write(`recorded ${options.piece} (${options.style}, ${refs.length} refs) in ${HISTORY_REL}\n`);
+}
+
+function printHistory(options) {
+  const history = loadHistory(options.project);
+  if (options.json) return process.stdout.write(`${JSON.stringify(history, null, 2)}\n`);
+  if (history.length === 0) return process.stdout.write('no pieces recorded yet\n');
+  for (const entry of history) process.stdout.write(`${entry.date} · ${entry.piece} · ${entry.style} · ${(entry.refs ?? []).join(', ')}\n`);
+}
+
+const options = parseArgs(process.argv.slice(2));
+if (options.command === 'pick') {
+  const result = await pick(options);
+  if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else printPick(result);
+} else if (options.command === 'record') record(options);
+else if (options.command === 'history') printHistory(options);
+else fail('usage: references.mjs pick|record|history (see the header of this file)');

package/src/skills-lib/wizz-web-security/SKILL.md

@@ -32,7 +32,7 @@ The ones that show up most in an audit, with the direct fix. Use as a quick tria
 
 > The first four (SQLi, IDOR, mass assignment, and permissive RLS) are **stop-the-line**: if it shows up, fix it before anything else.
 >
-> For a full adversarial audit (hunting with exploit proof + a prioritized plan), use the `security-audit-pentest` skill. This skill here is for **fixing** a specific finding from the table.
+> For a full adversarial audit (hunting with exploit proof + a prioritized plan), use the `wizz-security-audit-pentest` skill. This skill here is for **fixing** a specific finding from the table.
 
 ## References (load on demand)
 

package/tools/fetch-assets.mjs

@@ -39,7 +39,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 
-export const ASSETS_BASE = 'https://wizz-assets.junior-aec.workers.dev';
+export const ASSETS_BASE = 'https://assets.wizzcomms.com';
 
 // Fonte única dos bundles conhecidos. `dest` é relativo ao root do pacote
 // (repo em dev, node_modules/wizz-method quando instalado via npm — a mesma

package/tools/hooks/README.md

@@ -4,29 +4,33 @@ Os hooks do Claude Code usados pelo Wizz Method vivem AQUI e são instalados em
 `~/.claude/hooks/` via `npm run sync:global`. Nunca edite a cópia global direto:
 ela é substituída no próximo sync.
 
-| Hook                            | Evento             | O que faz                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| ------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `wizz-router-enforce.js`        | UserPromptSubmit   | Gate `isTrivial()` + injeção curta: em projeto Wizz (`_wizz/`) manda delegar direto ao maestro/agente da área (sem router); fora, manda pro `wizz-router`.                                                                                                                                                                                                                                                                          |
-| `session-rules.js`              | SessionStart       | Duas coisas num processo só: injeta as regras de comunicação 1x por sessão (antes era por prompt) e resolve a FEATURE ATIVA sozinho (branch git > `_wizz/bmm/config.yaml` > nada), para ninguém precisar invocar `wizz-set-feature`. Branch de tronco e de release não viram feature. Fora de projeto Wizz e sem branch de feature a linha não é emitida (custo zero); dentro de projeto Wizz sem feature sai o lembrete curto "o primeiro pedido nomeado define uma", e sem `layout:` o lembrete de propor um. A feature também é o `tema` da memória.                                                       |
-| `security-defensive-context.js` | PreToolUse (Skill) | Metodologia defensiva/escopada ao invocar skills de segurança. Genérico por projeto (v2).                                                                                                                                                                                                                                                                                                                                           |
-| `wizz-artifact-guard.js`        | PostToolUse (Write) | Avisa (nunca bloqueia) artefato escrito fora da subpasta da feature ativa, artefato de feature sem feature ativa, frontmatter faltando em `<tipo>-<slug>.md`, e arquivo solto na raiz fora do `layout:`, com o comando que move. Fail-open sem `_wizz/` ou config. |
-| `rtk-rewrite.sh`                | PreToolUse (Bash)  | Reescreve comandos de shell via `rtk rewrite` (token economy). Fork local do hook gerado pelo instalador upstream do rtk, com 3 patches (auditoria 2026-07-07, C4/RT1; e 2026-09-11, RT-H3): reescrita linha a linha em comando multi-linha (o binário só reescrevia a 1ª linha), timeout interno por linha (`RTK_HOOK_TIMEOUT`, default 3s) que não depende do `timeout`/`gtimeout` do GNU coreutils, e cache do version-guard (`RTK_CACHE_TTL_SECONDS`, default 1h, em `${XDG_CACHE_HOME:-$HOME/.cache}/wizz/rtk-version`) pra não rodar `rtk --version` a cada `Bash` tool call da sessão. Requer `rtk` + `jq` no PATH; fail-open em ambos (e no cache: ilegível/corrompido/expirado recomputa em silêncio). |
+| Hook                            | Evento                   | O que faz                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `wizz-router-enforce.js`        | UserPromptSubmit         | Gate `isTrivial()` + injeção curta: em projeto Wizz (`_wizz/`) manda delegar direto ao maestro/agente da área (sem router); fora, manda pro `wizz-router`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `session-rules.js`              | SessionStart             | Duas coisas num processo só: injeta as regras de comunicação 1x por sessão (antes era por prompt) e resolve a FEATURE ATIVA sozinho (branch git > `_wizz/bmm/config.yaml` > nada), para ninguém precisar invocar `wizz-set-feature`. Branch de tronco e de release não viram feature. Fora de projeto Wizz e sem branch de feature a linha não é emitida (custo zero); dentro de projeto Wizz sem feature sai o lembrete curto "o primeiro pedido nomeado define uma", e sem `layout:` o lembrete de propor um. A feature também é o `tema` da memória.                                                                                                                                                         |
+| `security-defensive-context.js` | PreToolUse (Skill)       | Metodologia defensiva/escopada ao invocar skills de segurança. Genérico por projeto (v2).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `wizz-artifact-guard.js`        | PostToolUse (Write/Edit) | Avisa (nunca bloqueia) artefato escrito fora da subpasta da feature ativa, artefato de feature sem feature ativa, frontmatter faltando em `<tipo>-<slug>.md`, e arquivo solto na raiz fora do `layout:`, com o comando que move. Fail-open sem `_wizz/` ou config.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `wizz-close-reminder.js`        | Stop                     | Aviso ao usuário (`systemMessage`, nunca `decision: block`) quando a feature ativa está `implementado`/`no-ar` e o checklist de fechamento do `wizz-feature.js` tem pendência (ou está no ar e segue ativa). Sem subprocesso, sai cedo fora de projeto Wizz e com feature em andamento, não repete o mesmo aviso na sessão, fail-open.                                                                                                                                                                                                                                                                                                                                                                          |
+| `rtk-rewrite.sh`                | PreToolUse (Bash)        | Reescreve comandos de shell via `rtk rewrite` (token economy). Fork local do hook gerado pelo instalador upstream do rtk, com 3 patches (auditoria 2026-07-07, C4/RT1; e 2026-09-11, RT-H3): reescrita linha a linha em comando multi-linha (o binário só reescrevia a 1ª linha), timeout interno por linha (`RTK_HOOK_TIMEOUT`, default 3s) que não depende do `timeout`/`gtimeout` do GNU coreutils, e cache do version-guard (`RTK_CACHE_TTL_SECONDS`, default 1h, em `${XDG_CACHE_HOME:-$HOME/.cache}/wizz/rtk-version`) pra não rodar `rtk --version` a cada `Bash` tool call da sessão. Requer `rtk` + `jq` no PATH; fail-open em ambos (e no cache: ilegível/corrompido/expirado recomputa em silêncio). |
+| `rtk-rewrite.js`                | PreToolUse (Bash)        | Versão Node do `rtk-rewrite.sh`, registrada no lugar dele só no Windows (sem bash e jq garantidos lá), desde 2026-10-15. Mesmo contrato: guard de multi-linha, linha a linha, timeout por linha, piso 0.23.0, fail-open. Sem o cache de versão. `node test/test-rtk-hook-node.js` exige a mesma saída dos dois contra o mesmo `rtk` fake. |
 
 Arquivos de apoio (copiados junto, NUNCA registrados em settings.json; o doctor cobra a presença):
 
-| Arquivo | O que é |
-| --- | --- |
-| `wizz-feature-lib.js` | Funções puras de feature, git, config, pastas de artefato e frontmatter. Usada por todos os hooks acima. |
-| `wizz-layout-lib.js` | O que pode ficar na raiz e para onde vai o resto (tipos `codigo`, `scripts`, `dados`, `docs`, `midia`, `arquivo`). |
-| `wizz-feature.js` | CLI do ciclo de vida da feature: `resolver`, `definir`, `artefato`, `decidir`, `status`, `verificar`, `encerrar`, `listar`. É o passo verificável que router/maestro rodam antes de despachar. |
-| `wizz-arrumar.js` | CLI de arrumação: `layout [--gravar]`, `planejar`, `aplicar` (manifesto .tsv + referências + testes antes/depois + `desfazer.sh`), `mover`, `desfazer`. |
+| Arquivo               | O que é                                                                                                                                                                                                                                                                                                                       |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `wizz-feature-lib.js` | Funções puras de feature, git, config, pastas de artefato e frontmatter. Usada por todos os hooks acima.                                                                                                                                                                                                                      |
+| `wizz-layout-lib.js`  | O que pode ficar na raiz e para onde vai o resto (tipos `codigo`, `scripts`, `dados`, `docs`, `midia`, `arquivo`).                                                                                                                                                                                                            |
+| `wizz-cerebro-lib.js` | Grava o fechamento no Cérebro (`encerrar --cerebro`): acha o vault e `projetos/<projeto>.md`, atualiza a linha da feature e a `Última sessão` do bloco Estado e põe 1 linha em Sessões (teto 15; as antigas vão para `_index/cerebro-archive.md`, lido só por grep). Idempotente, fail-open.                                  |
+| `wizz-debug-lib.js`   | Diagnóstico opt-in dos hooks: com `WIZZ_DEBUG=1` cada erro engolido vira 1 linha em stderr e é anexada a `~/.claude/wizz-debug.log` (`WIZZ_DEBUG_FILE` troca o caminho). Sem a variável: zero saída, zero disco. Os hooks seguem fail-open (exit 0). O `wizz doctor` roda cada hook com esse modo ligado (check `hooks-run`). |
+| `wizz-feature.js`     | CLI do ciclo de vida da feature: `resolver`, `definir`, `artefato`, `decidir`, `status`, `verificar`, `encerrar [--cerebro]`, `listar`. É o passo verificável que router/maestro rodam antes de despachar.                                                                                                                    |
+| `wizz-arrumar.js`     | CLI de arrumação: `layout [--gravar]`, `planejar`, `aplicar` (manifesto .tsv + referências + testes antes/depois + `desfazer.sh`), `mover`, `desfazer`.                                                                                                                                                                       |
 
 Regra completa em `src/modules/wizz/_shared/organizacao.md` (2026-10-02, caso Spider). `session-rules.js` passou a lembrar "nenhuma feature ativa" e "projeto sem layout" dentro de projeto Wizz, e `wizz-router-enforce.js` acrescenta 1 linha de feature por prompt em projeto Wizz.
 
 Removidos em 2026-07 (arquivados em `~/.claude/hooks-archive/`):
 `no-narration-enforce.js` (absorvido pelo session-rules) e `vault-reminder.js`.
 
-Testes: `npm run test:organizacao` (CLIs de feature e arrumação, guard, lembretes nos cenários sem git / main / branch), `npm run eval:feature` (hooks reais + CLI + estado final; `--llm` mede a obediência do modelo), `npm run test:hooks` (isTrivial + contexto por modo), `npm run test:feature-context` (resolução da feature ativa: tronco não vira feature, branch ganha do config, silêncio quando não há feature) e `node test/test-rtk-hook.js` (rewrite básico + multi-linha do `rtk-rewrite.sh`, smoke test que exercita o binário `rtk` real quando disponível, e o cache do version-guard: criado na 1ª chamada e reusado na 2ª, TTL expirado força recompute, path do binário mudou invalida, cache corrompido não quebra e se auto-cura).
+Testes: `node test/test-feature-close.js` (`encerrar --cerebro` e o lembrete do Stop), `npm run test:organizacao` (CLIs de feature e arrumação, guard, lembretes nos cenários sem git / main / branch), `npm run eval:feature` (hooks reais + CLI + estado final; `--llm` mede a obediência do modelo), `npm run test:hooks` (isTrivial + contexto por modo), `npm run test:feature-context` (resolução da feature ativa: tronco não vira feature, branch ganha do config, silêncio quando não há feature) e `node test/test-rtk-hook.js` (rewrite básico + multi-linha do `rtk-rewrite.sh`, smoke test que exercita o binário `rtk` real quando disponível, e o cache do version-guard: criado na 1ª chamada e reusado na 2ª, TTL expirado força recompute, path do binário mudou invalida, cache corrompido não quebra e se auto-cura).
 Evals de roteamento: `node evals/routing/run-routing-eval.mjs [--llm]`.
 
 Drift repo ↔ global: `npm run sync:check` compara hash de cada hook (e skill) entre o repo e `~/.claude`, sem escrever nada — é lembrete (fail-open), não gate; roda no fim do `npm test`. Achou drift? `npm run sync:global` atualiza `~/.claude`.