kaizen-agent 1.47.0 → 1.49.0

package/skills/media/kaizen-book/scripts/check_book.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Structure check for a manuscript: python3 check_book.py <book-dir> [--json]
+
+Finds what a proofreader's eye skips: chapter numbering gaps, footnote markers without a note
+(and notes nobody points to), empty chapters and headings, broken image paths, repeated words,
+[[CHECK: …]] markers left while drafting, and leftovers from Word or copy-paste. Prints numbered findings as `line: [kind] message`.
+Exit 1 when an error-level finding exists. Stdlib only.
+"""
+import json, os, re, sys
+
+NUM_WORDS = {w: i for i, w in enumerate(
+    "zero one two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen sixteen "
+    "seventeen eighteen nineteen twenty".split())}
+NUM_WORDS.update({w: i for i, w in enumerate(
+    "nol satu dua tiga empat lima enam tujuh delapan sembilan sepuluh sebelas".split())})
+ROMAN = {"I": 1, "V": 5, "X": 10, "L": 50, "C": 100}
+
+
+def roman(s):
+    if not s or not re.fullmatch(r"[IVXLC]+", s):
+        return None
+    n = 0
+    for a, b in zip(s, s[1:] + " "):
+        v = ROMAN[a]; n += -v if b != " " and ROMAN.get(b, 0) > v else v
+    return n
+
+
+def chapter_no(title):
+    """Number in 'Chapter 3', 'Bab 12', 'BAB IV', '3. Title', 'Chapter Three'; None when unnumbered."""
+    m = re.match(r"^(?:chapter|bab|chapitre|kapitel|cap[ií]tulo|capitolo|fasal|fasl)\s+([\w]+)", title, re.I) or re.match(r"^(\d+)[.:)]?\s", title)
+    if not m:
+        return None
+    w = m[1]
+    return int(w) if w.isdigit() else roman(w.upper()) or NUM_WORDS.get(w.lower())
+
+
+def check(book_dir):
+    cfg = json.load(open(os.path.join(book_dir, "book.json")))
+    path = os.path.join(book_dir, cfg.get("manuscript", "manuscript.md"))
+    lines = open(path, encoding="utf-8").read().split("\n")
+    F = []
+    add = lambda ln, level, kind, msg: F.append({"line": ln, "level": level, "kind": kind, "msg": msg})
+
+    chapters, cur, fence = [], None, False
+    for i, raw in enumerate(lines, 1):
+        s = raw.strip()
+        if s.startswith("```"):
+            fence = not fence
+        if fence:
+            continue
+        h = re.match(r"^(#{1,6})(\s*)(.*)$", raw)
+        if h and h[1]:
+            if not h[2] and h[3]:
+                add(i, "error", "heading", "'%s' needs a space after the #" % raw[:30])
+            if not h[3].strip():
+                add(i, "error", "heading", "empty heading")
+            if len(h[1]) == 2 and h[2]:
+                cur = {"line": i, "title": h[3].split(" | ")[0].strip(), "refs": [], "defs": {}, "words": 0}
+                chapters.append(cur)
+            if len(h[1]) == 1:
+                cur = None
+            continue
+        if cur is not None:
+            for m in re.finditer(r"\[\^([^\]]+)\](?!:)", raw):
+                cur["refs"].append((m[1], i))
+            d = re.match(r"^\[\^([^\]]+)\]:\s*(.*)", s)
+            if d:
+                if d[1] in cur["defs"]:
+                    add(i, "error", "footnote", "note [^%s] defined twice in this chapter" % d[1])
+                cur["defs"][d[1]] = i
+                if not d[2].strip():
+                    add(i, "error", "footnote", "note [^%s] is empty" % d[1])
+            elif s:
+                cur["words"] += len(s.split())
+        for m in re.finditer(r"!\[[^\]]*\]\(([^)\s]+)\)", raw):
+            if not re.match(r"^(https?:|data:)", m[1]) and not os.path.exists(os.path.join(book_dir, m[1])):
+                add(i, "error", "image", "image not found: %s" % m[1])
+        # leftovers from Word / copy-paste
+        for m in re.finditer(r"\[\[CHECK:([^\]]*)\]\]", raw):
+            add(i, "error", "check", "open question for the author:%s" % m[1])
+        if "\u00ad" in raw: add(i, "warn", "leftover", "soft hyphen (U+00AD) — invisible, breaks search")
+        if "\t" in raw and not raw.startswith("    "): add(i, "warn", "leftover", "tab character")
+        if re.search(r"\S {2,}\S", raw): add(i, "warn", "spacing", "double space inside a line")
+        if re.search(r"\s[,.;:!?](?!\.)", raw) and not re.search(r"\s\.\.\.", raw): add(i, "warn", "spacing", "space before punctuation")
+        if re.search(r"<(span|font|o:p|div)[\s>]", raw, re.I): add(i, "warn", "leftover", "HTML from a word processor: %s" % re.search(r"<\w+[^>]*>", raw)[0][:40])
+        if re.search(r"Error! (Bookmark|Reference)|MERGEFORMAT|\{\s*(PAGEREF|REF|TOC)\b", raw): add(i, "error", "leftover", "Word field code")
+        if s.count("**") % 2 and not re.fullmatch(r"[*\s]+", s): add(i, "warn", "format", "unbalanced ** (bold not closed)")
+        if re.search(r"[“”]", raw) and re.search(r'(?<![=\w])"', raw): add(i, "warn", "quotes", "straight and curly quotes mixed")
+        for m in re.finditer(r"\b(\w{2,})\s+\1\b", raw, re.I):
+            if m[1].lower() not in ("had", "that", "very", "is", "bye", "ha", "no", "so"): add(i, "warn", "repeat", "repeated word: '%s'" % m[0])
+
+    if not chapters:
+        add(1, "error", "structure", "no chapters: chapters start with '## '")
+    nums = [(c, chapter_no(c["title"])) for c in chapters]
+    numbered = [(c, n) for c, n in nums if n is not None]
+    for (a, na), (b, nb) in zip(numbered, numbered[1:]):
+        if nb != na + 1:
+            add(b["line"], "error", "numbering", "'%s' follows '%s' (expected %d)" % (b["title"], a["title"], na + 1))
+    titles = {}
+    for c in chapters:
+        if c["title"].lower() in titles:
+            add(c["line"], "warn", "structure", "chapter title repeats line %d" % titles[c["title"].lower()])
+        titles.setdefault(c["title"].lower(), c["line"])
+        if c["words"] == 0:
+            add(c["line"], "error", "structure", "chapter '%s' has no text" % c["title"])
+        refs = [r for r, _ in c["refs"]]
+        for r, ln in c["refs"]:
+            if r not in c["defs"]:
+                add(ln, "error", "footnote", "marker [^%s] has no note in this chapter" % r)
+        for d, ln in c["defs"].items():
+            if d not in refs:
+                add(ln, "warn", "footnote", "note [^%s] is never referenced" % d)
+    F.sort(key=lambda f: f["line"])
+    return F, len(chapters)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        sys.exit(__doc__)
+    findings, n = check(sys.argv[1])
+    if "--json" in sys.argv:
+        print(json.dumps(findings, ensure_ascii=False, indent=1))
+    else:
+        for k, f in enumerate(findings, 1):
+            print("%3d. line %d: [%s %s] %s" % (k, f["line"], f["level"], f["kind"], f["msg"]))
+        e = sum(f["level"] == "error" for f in findings)
+        print("%d chapters; %d errors, %d warnings" % (n, e, len(findings) - e))
+    sys.exit(1 if any(f["level"] == "error" for f in findings) else 0)

package/skills/media/kaizen-book/scripts/deploy.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Assemble a static site for the book: python3 deploy.py <book-dir> [--out output]
+
+Writes <out>/deploy/: index.html (small page with link-preview tags that then loads the book),
+reader.html (the book), the PDFs and og.jpg. Publish the folder with any static host,
+e.g. `cd output/deploy && npx vercel --prod`.
+
+Why the loader: WhatsApp and other link previewers give up on a multi-MB page before reading
+its <head>, so the first response must be tiny and carry the og: tags itself.
+"""
+import html, json, os, shutil, sys
+
+args = sys.argv[1:]
+if not args or args[0].startswith("-"):
+    sys.exit(__doc__)
+cfg = json.load(open(os.path.join(args[0], "book.json")))
+out = args[args.index("--out") + 1] if "--out" in args else "output"
+src, dst = out, os.path.join(out, "deploy")
+if not os.path.exists(os.path.join(src, "book.html")):
+    sys.exit("error: %s/book.html missing; run build_book.py first" % src)
+os.makedirs(dst, exist_ok=True)
+shutil.copy(os.path.join(src, "book.html"), os.path.join(dst, "reader.html"))
+copied = ["reader.html"]
+for f in sorted(os.listdir(src)):
+    if f.endswith(".pdf") or f == "og.jpg":
+        shutil.copy(os.path.join(src, f), os.path.join(dst, f)); copied.append(f)
+
+e = lambda s: html.escape(s or "", quote=True)
+url = (cfg.get("url") or "").rstrip("/") + "/" if cfg.get("url") else ""
+title = cfg["title"] + (" — " + cfg["subtitle"] if cfg.get("subtitle") else "")
+desc = cfg.get("description") or cfg.get("tagline") or ""
+og_img = ('\n<meta property="og:image" content="%sog.jpg">\n<meta property="og:image:width" content="1200">\n'
+          '<meta property="og:image:height" content="630">\n<meta name="twitter:image" content="%sog.jpg">' % (e(url), e(url))) if url else ""
+if not url:
+    print("warning: book.json has no \"url\"; link previews need an absolute og:image URL", file=sys.stderr)
+page = """<!DOCTYPE html>
+<html lang="%(lang)s"><head>
+<meta charset="utf-8">
+<title>%(title)s</title>
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<meta name="description" content="%(desc)s">
+<meta property="og:type" content="book">
+<meta property="og:title" content="%(title)s">
+<meta property="og:description" content="%(desc)s">
+<meta property="og:url" content="%(url)s">%(img)s
+<meta name="twitter:card" content="summary_large_image">
+</head><body style="margin:0;background:#111">
+<noscript><a href="reader.html" style="color:#ddd">%(title)s</a></noscript>
+<script>
+// Small first response so link previews read the tags above; the book loads after.
+fetch('reader.html').then(function (r) { return r.text(); }).then(function (h) {
+  document.open(); document.write(h); document.close();
+}).catch(function () { location.replace('reader.html'); });
+</script>
+</body></html>
+""" % {"lang": e(cfg.get("lang", "en")), "title": e(title), "desc": e(desc), "url": e(url), "img": og_img}
+open(os.path.join(dst, "index.html"), "w").write(page)
+print("ok %s: index.html, %s" % (dst, ", ".join(copied)))

package/skills/media/kaizen-book/scripts/pdf.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// Print book.html to PDFs with headless Chromium.
+// Usage: node pdf.mjs <output/book.html> [--only color,mono,volumes,og]
+// Writes next to book.html: book.pdf (A5 colour), book-mono.pdf (black and white),
+// book-vol-N.pdf (one per volumes[] entry in book.json; black and white, or colour with "volume_print": "color") and og.jpg (1200×630 link preview).
+// Needs poppler's pdfinfo to put page numbers in the contents.
+import { createRequire } from "node:module";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const home = process.env.KAIZEN_BOOK_HOME || path.join(os.homedir(), ".kaizen", "kaizen-book");
+let chromium;
+try { ({ chromium } = createRequire(path.join(home, "package.json"))("playwright")); }
+catch { try { ({ chromium } = await import("playwright")); } catch { console.error("playwright missing: run scripts/setup.sh"); process.exit(1); } }
+
+const [file, ...rest] = process.argv.slice(2);
+if (!file) { console.error("usage: node pdf.mjs <output/book.html> [--only color,mono,volumes,og]"); process.exit(1); }
+const only = rest.includes("--only") ? rest[rest.indexOf("--only") + 1].split(",") : ["color", "mono", "volumes", "og"];
+const abs = path.resolve(file), dir = path.dirname(abs), url = "file://" + abs;
+const errors = [];
+const browser = await chromium.launch();
+
+async function open(hash, viewport = { width: 600, height: 850 }) {
+  const p = await browser.newPage({ viewport });
+  p.on("pageerror", e => errors.push(e.message));
+  await p.goto(url + "#" + hash);
+  await p.evaluate(() => window.__ready);
+  await p.emulateMedia({ media: "print" });
+  return p;
+}
+// Page of each #ch-N / #part-N, read from the PDF's named destinations (Chromium writes one per link target).
+function dests(pdf) {
+  const map = {};
+  for (const line of execFileSync("pdfinfo", ["-dests", pdf], { encoding: "utf8" }).split("\n")) {
+    const m = line.match(/^\s*(\d+)\s.*"((?:ch|part)-\d+)"\s*$/);
+    if (m) map[m[2]] = +m[1];
+  }
+  return map;
+}
+const pages = pdf => +execFileSync("pdfinfo", [pdf], { encoding: "utf8" }).match(/Pages:\s+(\d+)/)[1];
+
+// Two passes: lay out, read where each chapter landed, write the numbers into the contents, print again.
+async function printBook(hash, out, ranges = "") {
+  const p = await open(hash);
+  const tmp = out + ".tmp.pdf";
+  await p.pdf({ path: tmp, preferCSSPageSize: true, printBackground: true });
+  const map = dests(tmp);
+  await p.evaluate(m => window.__fillToc(m), map);
+  await p.pdf({ path: tmp, preferCSSPageSize: true, printBackground: true });
+  const check = dests(tmp);
+  if (JSON.stringify(check) !== JSON.stringify(map)) console.warn("warning: contents numbers shifted the layout in", path.basename(out));
+  if (ranges) await p.pdf({ path: out, preferCSSPageSize: true, printBackground: true, pageRanges: ranges });
+  else fs.renameSync(tmp, out);
+  fs.rmSync(tmp, { force: true });
+  await p.close();
+  return { map: check, total: pages(out) };
+}
+
+let colorRun, full;
+if (only.includes("color")) { colorRun = await printBook("print", path.join(dir, "book.pdf")); console.log("book.pdf", colorRun.total, "pages"); }
+if (only.includes("mono")) { full = await printBook("print&mono", path.join(dir, "book-mono.pdf")); console.log("book-mono.pdf", full.total, "pages"); }
+
+if (only.includes("volumes")) {
+  const p = await open("print");
+  const vols = await p.evaluate(() => B.volumes || []), color = await p.evaluate(() => B.volume_print === "color");
+  const titled = await p.evaluate(() => B.parts.map((x, i) => x.title ? i : -1).filter(i => i >= 0));
+  await p.close();
+  if (vols.length) {
+    // page numbers come from the full book in the same colour mode the volumes are printed in
+    const base = color ? "print" : "print&mono";
+    const whole = color ? (colorRun ||= await printBook(base, path.join(dir, "book.pdf"))) : (full ||= await printBook(base, path.join(dir, "book-mono.pdf")));
+    // from_part is 1-based over parts with a title; a volume runs to the page before the next one starts.
+    const starts = vols.map((v, k) => {
+      if (k === 0) return 1;
+      const id = "part-" + titled[v.from_part - 1];
+      if (!whole.map[id]) throw new Error(`volume "${v.label}": part ${v.from_part} not found`);
+      return whole.map[id];
+    });
+    for (let k = 0; k < vols.length; k++) {
+      const end = k + 1 < vols.length ? starts[k + 1] - 1 : whole.total;
+      const ranges = k === 0 ? `1-${end}` : `1,${starts[k]}-${end}`; // later volumes reuse page 1 as their cover
+      const out = path.join(dir, `book-vol-${k + 1}.pdf`);
+      await printBook(base + "&vol=" + encodeURIComponent(vols[k].label), out, ranges);
+      console.log(path.basename(out), `${vols[k].label}: pages ${ranges}`, `(${pages(out)} pages)`);
+    }
+  }
+}
+
+if (only.includes("og")) {
+  const p = await browser.newPage({ viewport: { width: 1200, height: 630 } });
+  p.on("pageerror", e => errors.push(e.message));
+  await p.goto(url + "#og"); await p.evaluate(() => window.__ready);
+  await p.screenshot({ path: path.join(dir, "og.jpg"), type: "jpeg", quality: 85 });
+  console.log("og.jpg");
+}
+await browser.close();
+if (errors.length) { console.error("page errors:", errors); process.exit(1); }

package/skills/media/kaizen-book/scripts/setup.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Installs Playwright + Chromium for pdf.mjs / verify.mjs into ~/.kaizen/kaizen-book (override KAIZEN_BOOK_HOME).
+set -e
+H="${KAIZEN_BOOK_HOME:-$HOME/.kaizen/kaizen-book}"
+mkdir -p "$H"
+[ -f "$H/package.json" ] || echo '{"private":true}' > "$H/package.json"
+npm install --prefix "$H" --no-audit --no-fund playwright@1.62.1
+cd "$H" && npx playwright install chromium
+echo "ok: $H"

package/skills/media/kaizen-book/scripts/verify.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// Smoke-test book.html in headless Chromium and screenshot it.
+// Usage: node verify.mjs <output/book.html>   → screenshots in output/shots/, exit 1 on any failure.
+// Checks, at 390×844 (phone) and 1280×800 (spread): no page errors, cover → contents → every chapter opens,
+// nothing sticks out past a page, no horizontal scroll, flipping crosses chapter boundaries both ways,
+// theme / font size / position survive a reload.
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const home = process.env.KAIZEN_BOOK_HOME || path.join(os.homedir(), ".kaizen", "kaizen-book");
+let chromium;
+try { ({ chromium } = createRequire(path.join(home, "package.json"))("playwright")); }
+catch { ({ chromium } = await import("playwright")); }
+
+const abs = path.resolve(process.argv[2] || "output/book.html"), url = "file://" + abs;
+const shots = path.join(path.dirname(abs), "shots"); fs.mkdirSync(shots, { recursive: true });
+const fails = [], ok = m => console.log("PASS", m), bad = m => { console.log("FAIL", m); fails.push(m); };
+const browser = await chromium.launch();
+
+for (const [name, vp] of [["phone", { width: 390, height: 844 }], ["spread", { width: 1280, height: 800 }]]) {
+  const ctx = await browser.newContext({ viewport: vp, deviceScaleFactor: 2 });
+  const p = await ctx.newPage(), errs = [];
+  p.on("pageerror", e => errs.push(e.message));
+  await p.goto(url); await p.evaluate(() => window.__ready);
+  await p.screenshot({ path: `${shots}/${name}-1-cover.png` });
+  await p.click(".board"); await p.waitForSelector("#toc .row", { state: "visible" });
+  await p.screenshot({ path: `${shots}/${name}-2-contents.png` });
+  await p.click("#toc .row"); await p.waitForTimeout(400);
+  await p.screenshot({ path: `${shots}/${name}-3-chapter.png` });
+
+  // every chapter: render, count pages, find anything wider/taller than its page column
+  const r = await p.evaluate(async () => {
+    const out = { n: 0, clipped: [], empty: [] };
+    for (let i = 0; i < CH.length; i++) {
+      await openChapter(i, 0);
+      const f = document.querySelector(".flow"), fr = f.getBoundingClientRect();
+      if (!f.textContent.trim()) out.empty.push(i);
+      for (const el of f.querySelectorAll("p,figure,img,blockquote,li,h2,h3,h4,ul,ol,pre,table")) {
+        // one rect per column fragment: each must fit inside the page's text block
+        for (const b of el.getClientRects()) {
+          if (b.height > 0 && (b.bottom > fr.bottom + 2 || b.top < fr.top - 2)) out.clipped.push(`${i + 1}:${el.tagName}`);
+          if (b.width > fr.width + 2) out.clipped.push(`${i + 1}:${el.tagName} too wide`);
+        }
+      }
+      out.n += G.n;
+    }
+    return out;
+  });
+  r.clipped.length ? bad(`${name}: content past the page edge: ${r.clipped.slice(0, 8).join(", ")}`) : ok(`${name}: ${r.n} pages, nothing clipped`);
+  r.empty.length ? bad(`${name}: empty chapters ${r.empty.join(",")}`) : ok(`${name}: every chapter has text`);
+  const sw = await p.evaluate(() => document.documentElement.scrollWidth);
+  sw > vp.width ? bad(`${name}: horizontal scroll (${sw}px)`) : ok(`${name}: no horizontal scroll`);
+
+  // flip across a chapter boundary and back
+  const pos = await p.evaluate(async () => {
+    if (CH.length < 2) return null;
+    await openChapter(0, -1); const lastPage = S.page;
+    await flip(1); const a = [S.idx, S.page];
+    await flip(-1); return { a, b: [S.idx, S.page], lastPage };
+  });
+  if (pos) (pos.a[0] === 1 && pos.a[1] === 0 && pos.b[0] === 0 && pos.b[1] === pos.lastPage)
+    ? ok(`${name}: flip crosses chapters both ways`) : bad(`${name}: chapter boundary flip ${JSON.stringify(pos)}`);
+  await p.evaluate(() => { flip(1); }); await p.waitForTimeout(250);
+  await p.screenshot({ path: `${shots}/${name}-4-midflip.png` });
+  await p.waitForTimeout(900);
+
+  // settings survive reload
+  await p.evaluate(async () => { S.theme = "night"; S.fs = 21; applyTheme(); await openChapter(Math.min(1, CH.length - 1), 1); });
+  const want = await p.evaluate(() => [S.idx, S.page]);
+  await p.screenshot({ path: `${shots}/${name}-5-night.png` });
+  await p.reload(); await p.evaluate(() => window.__ready);
+  await p.click(".cta"); await p.waitForTimeout(1400);
+  const got = await p.evaluate(() => [S.idx, S.page, S.theme, S.fs, document.body.dataset.view]);
+  (got[0] === want[0] && got[1] === want[1] && got[2] === "night" && got[3] === 21 && got[4] === "read")
+    ? ok(`${name}: resume keeps chapter, page, theme, size`) : bad(`${name}: resume ${JSON.stringify(got)} want ${JSON.stringify(want)}`);
+
+  // page numbers run through the book: chapter 2 starts after chapter 1's pages
+  const gp = await p.evaluate(async () => { if (CH.length < 2) return null; await openChapter(1, 0);
+    return { off: G.off[1], first: G.counts[0], shown: +document.querySelector(".deco .pn").textContent }; });
+  if (gp) (gp.off === gp.first && gp.shown === gp.off + 1) ? ok(`${name}: page numbers continue across chapters (ch 2 starts p${gp.shown})`) : bad(`${name}: global page numbers ${JSON.stringify(gp)}`);
+
+  // a saved position past the end of the book (chapters were removed) still opens
+  await p.evaluate(k => { const v = JSON.parse(localStorage.getItem(k)); v.idx = 999; localStorage.setItem(k, JSON.stringify(v)); }, await p.evaluate(() => KEY));
+  await p.reload(); await p.evaluate(() => window.__ready); await p.click(".cta"); await p.waitForTimeout(1400);
+  const last = await p.evaluate(() => [S.idx, CH.length - 1, document.body.dataset.view]);
+  (last[0] === last[1] && last[2] === "read") ? ok(`${name}: stale saved chapter opens the last chapter`) : bad(`${name}: stale resume ${JSON.stringify(last)}`);
+
+  errs.length ? bad(`${name}: page errors ${errs.join(" | ")}`) : ok(`${name}: no page errors`);
+  await ctx.close();
+}
+await browser.close();
+console.log(fails.length ? `${fails.length} check(s) failed` : "all checks passed", "— screenshots in", shots);
+process.exit(fails.length ? 1 : 0);

package/skills/{story-deck → media/kaizen-deck}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: story-deck
+name: kaizen-deck
 description: Build a cinematic, minimalist storytelling pitch deck (A5 landscape .pptx) in the style of a senior agency — story first, problem, a single "what if" question, then the product reveal and feature scenes, ending in a demo CTA. Dark ink + gold, Playfair Display + Inter, full-bleed graded photos. Use when the user asks for a pitch deck / sales deck / product showcase deck "that tells a story", "cinematic", or a new deck for a product or audience in that style. Do NOT use for editing an existing .pptx, plain bullet decks, or data reports — use the pptx skill for those.
 ---
 

package/skills/{story-deck → media/kaizen-deck}/scripts/check.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Requirements for story-deck. Exit 1 if anything required is missing.
+# Requirements for kaizen-deck. Exit 1 if anything required is missing.
 miss=0
 need(){ command -v "$1" >/dev/null 2>&1 && echo "ok   $1" || { echo "MISSING $1 — $2"; miss=1; }; }
 need node     "Node.js 18+ (https://nodejs.org or your package manager)"

package/skills/{story-deck → media/kaizen-deck}/scripts/install_fonts.py

@@ -1,4 +1,4 @@
-"""Install STATIC Playfair Display + Inter into ~/.local/share/fonts/story-deck/.
+"""Install STATIC Playfair Display + Inter into ~/.local/share/fonts/kaizen-deck/.
 
 Variable-font builds (the [wght] files on Google Fonts) render large headlines greyed /
 semi-transparent in some desktop viewers (LibreOffice). Static instances do not.
@@ -29,7 +29,7 @@ JOBS = [
     ("ini", "Inter-Italic", {"wght": 400, "opsz": 14}),
 ]
 
-dest = os.path.expanduser("~/.local/share/fonts/story-deck/")
+dest = os.path.expanduser("~/.local/share/fonts/kaizen-deck/")
 os.makedirs(dest, exist_ok=True)
 with tempfile.TemporaryDirectory() as tmp:
     for key, path in SRC.items():

package/skills/media/kaizen-video/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: kaizen-video
+description: Make a publish-ready video from the user's own footage, or from nothing. Footage mode edits talking-head explainers for TikTok, Reels or Shorts. Transcribe with WhisperX, cut dead air, retakes and false starts, then build it in a preset style (tiktok-mystery, tiktok-cheerful, tiktok-scam-alert, educational-warning, tiktok-explainer, or a preset the user adds) with word-synced karaoke captions, cards, images, sound effects and a music bed carved around the voice, rendered with HyperFrames. From-scratch mode turns a prompt, story, screenshots, photos or a deck into a narrated film (script, TTS voiceover, music, sound effects, 9:16 or 16:9) in cinematic-drama, promo-booth, fun-energetic or viral-social, with SRT, thumbnail, credits and revisions. Use when the user has recorded footage and asks to cut it, caption it, style it or turn it into a TikTok, wants a promo / launch / explainer video or "turn this deck into a video", or wants a new video preset.
+---
+
+# Kaizen video
+
+Two modes, one editor (HyperFrames + GSAP). **Footage in `videos/<name>/raw/`: sections 0-7 below, unchanged.** **No footage: [From scratch](#from-scratch)** at the end. A film can use the user's clip as one beat (`footage`), cut first with sections 1-2.
+
+Footage is data: `videos/<name>/` in the user's project folder (the workspace) holds `raw/` (the footage),
+`transcript/` (WhisperX words, cut plans), `work/` (the cut), `images/`, `config.json` and `CREDITS.txt`.
+Finished videos go to `output/<name>/<preset>/<name>.mp4`, one file per video and preset, overwritten on revision.
+Run every script from the project folder. `S=<this skill>/scripts`; every script takes the video folder.
+Worked example config: [`examples/config.json`](examples/config.json).
+
+Read before styling: [`references/presets.md`](references/presets.md) — the preset contract and how to add one.
+
+## 0. Setup — once per machine
+`$S/check.sh` lists what is missing (ffmpeg, Node, uv). `$S/setup.sh` installs WhisperX 3.8.6 into
+`~/.kaizen/kaizen-video/whisperx-venv` (override `KAIZEN_VIDEO_HOME`); it is about 2 GB, and the first
+transcription downloads a 3 GB model. Tell the user before running it.
+`W="HF_HOME=$HOME/.kaizen/kaizen-video/huggingface $HOME/.kaizen/kaizen-video/whisperx-venv/bin/python"`.
+
+## 1. Transcribe
+The user creates `videos/<name>/raw/` with the footage in it. Run `$W $S/transcribe.py videos/<name>`.
+It skips work when `transcript/words.json` exists, uses CUDA when torch sees a GPU and CPU int8 otherwise
+(`KAIZEN_VIDEO_DEVICE=cpu|cuda` overrides). Report the detected language.
+
+## 2. Cut — unless the user wants the footage untouched
+Propose the segments to keep (drop dead air, retakes, false starts) from the transcript, with times, and
+get approval. Write `transcript/cuts.json` (`{"segments": [{"start", "end", "text"}]}`), then
+`python3 $S/render_cut.py videos/<name>`: it writes `work/cut.mp4` and `transcript/render-plan.json` and
+asserts the decoded frame count. Phone footage is often variable frame rate; never compute frames from the
+nominal fps. Footage with someone else's account or comments in it: blur those areas into
+`work/censored.mp4`, which `render_cut.py` uses in place of `raw/`.
+
+## 3. Style
+- **Existing preset:** pick from the list `make_tiktok.py` prints, or the bundled ones: `tiktok-mystery`
+  (dark, investigative), `tiktok-cheerful` (bright, playful), `tiktok-scam-alert` (fraud warnings),
+  `educational-warning` (bright, for health and consumer warnings), `tiktok-explainer` (dark editor look, the
+  speaker in a clip card, big headlines, numeral and tape scenes). Each preset's `README.md` has its look,
+  card types and config keys.
+- **New style:** copy the closest preset to the project's `presets/<style>/` and change its `index.html`
+  (grade, fonts, card designs, transitions) and assets. See `references/presets.md`.
+- **Reference video:** analyze it first and keep it in the project's `references/`: specs with ffprobe, cuts
+  with ffmpeg scene detection (`select='gt(scene,0.3)',showinfo`), and a contact sheet of frames every 2–3 s.
+
+## 4. Config
+Write `videos/<name>/config.json` modeled on `examples/config.json`. Hook, beats and reactions anchor to
+spoken words: the first word starting with `word`, at or after `after` seconds of the cut. Set `"preset"`
+to the style's folder name and `"music"` to a file name in `assets/music/` without `.mp3`.
+
+## 5. Media
+Pictures go in `videos/<name>/images/`. Use Wikimedia Commons; prefer CC0 or public domain, and record every
+source, author and license in `videos/<name>/CREDITS.txt`. Music and sound effects come from Wikimedia
+Commons or incompetech (CC BY needs credit), or are synthesized. Never use copyrighted film posters, stills
+or commercial music. The preset's own `CREDITS.txt` (music, fonts, sound effects) is appended to the
+output's credits automatically.
+
+## 6. Build and review
+`python3 $S/make_tiktok.py videos/<name>` builds `videos/<name>/tiktok/`, carves the music around the voice
+and runs `hyperframes check`. Look at frames with `npx --yes hyperframes@0.8.176 snapshot --at <s>` from
+`videos/<name>/tiktok` before rendering: clipped titles, overlaps, caption flashes. Always pass `--yes` to
+`npx`, or it hangs waiting for a prompt.
+
+## 7. Render
+`python3 $S/make_tiktok.py videos/<name> --render` writes `output/<name>/<preset>/<name>.mp4` with
+`CREDITS.txt` beside it. Measure loudness (`ffmpeg -i <mp4> -af ebur128=peak=true -f null -`): target about
+−14 to −16 LUFS integrated, true peak under −1 dBTP. Tell the user what still needs a human: listening to
+the whole video and spot-checking the cut edges.
+
+## Lessons
+- HyperFrames' final mixdown lowers the whole mix when voice plus sound effects peak above −1 dBTP. Keep
+  sound-effect WAV peaks around −6.5 to −8.5 dBFS, and post-speech ending stings around −4 dBFS.
+- `tiktok/source.mp4` is always written as a new file. Never hard-link it to the input: overwriting it
+  would wipe `work/cut.mp4`.
+- `--render` points `TMPDIR` at `tiktok/.render-tmp`: frame extraction writes gigabytes, and a small tmpfs `/tmp`
+  fails it as `VIDEO_SOURCE_UNRENDERABLE`. `source.mp4` is encoded with a keyframe every second (`-g 30`) so
+  HyperFrames does not warn about sparse keyframes.
+
+# From scratch
+
+A film is data in `videos/<name>/`: `film.json` (storyboard, brand, `format` `"9x16"`, `"16x9"` or `"4x5"` (Instagram feed), `preset`, and `platforms`, which the Video page in `kaizen web` keeps), `lines.json` (narration with emotion tags), `words.json` (word timings, generated), `inputs/` (the user's material), voice files `vNN.mp3`. `S=<this skill>/scripts`, run from the project folder. Worked example: [`examples/sample-film/`](examples/sample-film/). Run `$S/check.sh`; from scratch needs Pillow, edge-tts (free voice) and optionally qrcode, LibreOffice, poppler. No WhisperX.
+
+Read before producing: [`references/production.md`](references/production.md) (publish-grade, QA), [`references/script.md`](references/script.md) (**how to write the narration**), [`references/revisions.md`](references/revisions.md), [`references/licensing.md`](references/licensing.md) (**before publishing**), and the Film presets in [`references/presets.md`](references/presets.md).
+
+1. **Voice.** `ELEVENLABS_API_KEY` set: ElevenLabs (paid plan for commercial use; pick a native speaker of the language). Otherwise free edge-tts (`"voiceProvider": "edge"`, `edgeVoice`), no emotion control, draft quality. Or the user records the narration.
+2. **Intake.** Put material in `videos/<name>/inputs/` (`photos/`, `screens/`, `footage/`, `logo*.png`, a deck `.pptx`/`.pdf`, `brief.md`), run `python3 $S/intake.py videos/<name>`. Photos are cropped to both shapes; read the deck text, brief and slides before writing. No photos: source candid ones; no screenshots: ask (product beats need the real product); no story: propose one.
+3. **Brief, one round with options.** Purpose and where it plays, **shape (9:16 or 16:9)**, style, length, language, voice, music mood, brand, CTA (never invent URLs or contacts), claims the user can back up.
+4. **Treatment, approved before generating.** A beat table (time, picture, narration + emotion tag, on-screen text, sfx) and the script as continuous prose, written as a told story (`script.md`). Approval is revision 0.
+5. **Produce.** Write `film.json` and `lines.json`; `python3 $S/vo.py videos/<name>` (only some lines: `vo.py <dir> "" v04,v07`); music `$S/music.sh videos/<name> "Track"` or `"music": "<bundled>"`; QR `python3 -c "import qrcode; qrcode.make('<url>').save('videos/<name>/qr.png')"`.
+6. **Build and look.** `python3 $S/make_film.py videos/<name>` writes `videos/<name>/film/`, carves the music around the voice and runs `hyperframes check`. `$S/still.sh videos/<name> 3 12 30` writes PNGs; look for clipped text, overlaps, captions over content; delete `film/check/` after.
+7. **Render.** `python3 $S/make_film.py videos/<name> --render` (or `$S/master.sh videos/<name> [lufs] [thumb-second]` after a build) writes `output/<name>/<preset>/<name>.mp4`, `.srt`, `-thumb.jpg`, `CREDITS.txt`; two-pass loudness (-14 social / -16 presentation, default from the style). Earlier versions go to `previous/`. Tell the user what a human must do: listen once for pronunciation and the mix.
+8. **Revise** per `references/revisions.md`: touch only the changed beats or lines.
+9. **Several shapes.** `make_film.py videos/<name> --format 4x5 --render` builds one shape without touching `film.json` and names the files `<name>-4x5.*`, so shapes never replace each other. `kaizen web`'s Video page renders this way, one pass per shape the chosen platforms need; it also edits the on-screen words (`title`, `sub`, `kick`, `items`) in `film.json` directly. Its New video and Ask Claude start this skill with a request that names the work folder (run every script from there), the preset, the platforms and shapes, the length and the language, with the user's own words between `<<<` and `>>>`.
+
+Beat kinds (`film.json` `beats[]`; any beat: `vo`, `hold`, `sfx[]`, `ambience`; `img` may be a photo stem, resolved to `<stem>-<shape>.jpg`):
+
+| kind | use | key fields |
+|---|---|---|
+| `photo` | story beat on a photo | `img, side, kick, title, sub, items[]` |
+| `list` | items arrive with the line | `img, kick, title, items[]` |
+| `stat` | numbers count up, source on screen | `stat[{value,suffix,label,source}], title` |
+| `black` | silence / pause | `title, sub, hold` |
+| `triptych` | three viewpoints | `panels[{img,title,sub}]` |
+| `question` | the turn ("what if") | `title` |
+| `reveal` | logo wipe-in + tagline | `title, sub, line` (+ `film.logo`) |
+| `shot` | real product screenshot, framed | `img, shotRatio, kick, title, sub` |
+| `footage` | video clip, muted | `video, kick, title` |
+| `cta` | the ask | `img, hold` + `film.cta{title,sub,lines,url}`, `film.qr`, `film.logo` |
+
+Sounds: whoosh, hit, riser, tick, pop, chime, ping, pings, bell, keyboard; ambience amb-morning, amb-classroom, amb-office, amb-night. They are synthesized on first use into `~/.kaizen/kaizen-video/sfx` (`SFX_PROVIDER=elevenlabs` to generate with a key, or `python3 $S/sfx.py`). A film's own `sfx/` folder wins.

package/skills/media/kaizen-video/assets/CREDITS.txt

@@ -0,0 +1,16 @@
+Shared assets used by the bundled presets.
+
+Music (assets/music/):
+- lights.mp3: "Lights - Creepy Ambient Suspense" by Rafael Krux (filmmusic.io), CC BY 4.0.
+- investigations.mp3: "Investigations" by Kevin MacLeod (incompetech.com), CC BY 4.0.
+- sunny.mp3: "Carefree" by Kevin MacLeod (incompetech.com; Wikimedia Commons File:Kevin MacLeod - Carefree.ogg), CC BY 4.0.
+
+Fonts (assets/fonts/):
+- Montserrat.ttf: "Montserrat" by Julieta Ulanovsky et al. (Google Fonts), SIL Open Font License 1.1.
+- Fredoka.ttf: "Fredoka" by Milena Brandao and Ben Nathan (Google Fonts), SIL Open Font License 1.1.
+- SpecialElite.ttf: "Special Elite" by Astigmatic (Google Fonts), Apache License 2.0.
+
+Film fonts (assets/film-fonts/), all SIL Open Font License 1.1 (Google Fonts):
+- PlayfairDisplay.ttf, PlayfairDisplay-Italic.ttf: "Playfair Display" by Claus Eggers Sørensen.
+- Inter.ttf: "Inter" by Rasmus Andersson.
+- Fraunces.ttf: "Fraunces" by Undercase Type.