kaizen-agent 1.19.3 → 1.20.0

package/README.md

@@ -232,6 +232,17 @@ In a terminal: `kaizen` (dashboard), `kaizen web` (board), `kaizen settings`, `k
 
 Stuck on 1.18.0 or older? If `kaizen upgrade` says *could not pull* and stays on the old version, run this once: `bunx kaizen-agent@latest`. Your old install is kept as `~/kaizen.old`; from then on `kaizen upgrade` works by itself.
 
+## Bundled skills
+
+Installed alongside kaizen; your agent uses them when a request fits. Everything they make lives in `~/.kaizen/`.
+
+| Skill | What it makes |
+|---|---|
+| `story-deck` | A cinematic storytelling pitch deck (A5 `.pptx`): story first, the product last. Output in `~/.kaizen/decks/`. |
+| `story-video` | A publish-ready video from a prompt, photos, screenshots, a deck or footage: narration, captions, sound design, music, mastering, 16:9 and 9:16, revisable. Output in `~/.kaizen/videos/`. Works with no accounts (free voice, synthesized sounds); an ElevenLabs key unlocks natural voices. |
+
+Each skill has a `scripts/check.sh` that lists what it needs (Node, Python, ffmpeg, LibreOffice).
+
 ## Learn more
 
 - **[The guide](https://github.com/hfadhlullah/kaizen/blob/main/docs/guide.md)**: the board, request sources, notebook, settings, installer flags, uninstall

package/cli/install.ts

@@ -46,6 +46,9 @@ const c = {
   green: (s: string) => `\x1b[32m${s}\x1b[0m`,
 };
 
+// Skill folders shipped in skills/ and linked into every agent.
+const SKILLS = ["kaizen", "kaizen-help", "story-deck", "story-video"];
+
 // Where each agent reads skills from. The skill folders follow the open Agent
 // Skills standard, so every one of these can run the workflow; agents/ and
 // commands/ are Claude Code's own formats and go nowhere else.
@@ -177,7 +180,7 @@ async function removeEverything() {
 
   for (const root of roots) {
     for (const a of AGENTS) {
-      for (const n of ["kaizen", "kaizen-help"]) drop(join(root, a.dir, "skills", n));
+      for (const n of SKILLS) drop(join(root, a.dir, "skills", n));
       for (const sub of ["agents", "commands"]) {
         const dir = join(root, a.dir, sub);
         try {
@@ -386,7 +389,7 @@ if (interactive && !upgrade && Bun.argv.length === 2) {
   if (!stale) {
     const here = found(home);
     const linked = here.length > 0 && here.every((a) =>
-      ["kaizen", "kaizen-help"].every((n) => existsSync(join(home, a.dir, "skills", n))));
+      SKILLS.every((n) => existsSync(join(home, a.dir, "skills", n))));
     if (linked) {
       const { dashboard } = await import("./dashboard.ts");
       await dashboard(repoDir, here.map((a) => a.name), async (action) => {
@@ -432,8 +435,11 @@ if (upgrade) {
   // failure is printed rather than swallowed.
   const r = await Bun.$`${process.execPath} x --force kaizen-agent@${latest} --yes`.quiet().nothrow();
   const out = clean(r.stdout.toString() + r.stderr.toString()).filter((l) => l.trim());
-  for (const l of out) console.log(l.startsWith("  ") ? l : `  ${l}`);
   const after = versionOf(dest);
+  // The new installer's banner and first-install "Next" steps are noise here: show
+  // its step lines, or everything when it failed so the error is not hidden.
+  const shown = after === latest ? out.filter((l) => /^\s*(\+|skip)\s/.test(l)) : out;
+  for (const l of shown) console.log(l.startsWith("  ") ? l : `  ${l}`);
   // The installer exits 1 when it skipped a link (an agent file the user owns), which
   // is not a failed upgrade: the version on disk is what decides.
   if (after !== latest) {
@@ -676,7 +682,7 @@ function dirEntries(sub: string) {
 }
 
 const links = targets.flatMap((a) => [
-  ...["kaizen", "kaizen-help"].map((n) => [join(repo, "skills", n), join(a.dir, "skills")] as const),
+  ...SKILLS.map((n) => [join(repo, "skills", n), join(a.dir, "skills")] as const),
   ...(a.full ? [
     ...dirEntries("agents").map((f) => [f, join(a.dir, "agents")] as const),
     ...dirEntries("commands").map((f) => [f, join(a.dir, "commands")] as const),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaizen-agent",
-  "version": "1.19.3",
+  "version": "1.20.0",
   "description": "Staged workflow for AI agents — code, writing, research, operations: plan, human approval, build, independent review, bounded fix loop.",
   "type": "module",
   "bin": {

package/skills/story-deck/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: story-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.
+---
+
+# Story deck
+
+A deck that tells a story before it sells. Worked example: [`examples/build-example.js`](examples/build-example.js)
+(every helper on a fictional product, no images needed).
+
+Read before building:
+- [`references/story-arc.md`](references/story-arc.md) — the acts, slide recipes, copy rules, layout facts.
+- [`references/rules.md`](references/rules.md) — truth, images, fonts, files, QA. Every rule there cost a redo.
+
+If the Anthropic `pptx` skill is available, load it once (pptxgenjs gotchas, validator); `qa.sh` works without it.
+Run `scripts/check.sh` first on a new machine.
+
+## Workflow
+
+1. **Brainstorm first.** Propose 2–3 story concepts + an outline (one line per slide) and
+   ask: audience, language, data available, photos, the CTA. Build only after the outline is agreed.
+2. **Deck folder:** `~/.kaizen/decks/<slug>/` — everything a deck needs and produces lives there
+   (never in the user's project folders). Shared dependencies live once in `~/.kaizen/decks/`:
+   `node_modules` (pptxgenjs, resolved upward by Node) and `.venv` (Pillow, defusedxml, lxml,
+   fonttools, qrcode). First time on a machine:
+   `cd ~/.kaizen/decks && npm init -y && npm i pptxgenjs && python3 -m venv .venv && .venv/bin/pip install pillow defusedxml lxml fonttools "qrcode[pil]"`.
+   Copy in `scripts/kit.js`, `scripts/prep_images.py`, `scripts/qa.sh`.
+3. **Research the truth.** Features from the product repos (shipped only — one sub-agent per
+   repo when there are several, if your agent has sub-agents). Stats from official sources with citations.
+4. **Photos.** Find on Unsplash with a web-fetch tool (or ask the user for photos), download to `img/`, contact-sheet, choose.
+   Write `plan.json` (backgrounds + panels), run `python3 prep_images.py plan.json` → `bg/`.
+5. **Fonts.** Run `scripts/install_fonts.py` once per machine (static instances; see rules.md).
+6. **Write `build-<name>.js`** with `kit.js`:
+
+   ```js
+   const { makeDeck } = require("./kit");
+   const d = makeDeck("Deck title", { logo: "logo.png", logoRatio: 199 / 880 }); // branding optional
+   d.story("s01", { kick, title, sub, notes, credit, top });  // photo story beat
+   d.pause(line, sub, notes);                                  // black silence slide
+   d.question(line, notes);                                    // gold "what if" slide
+   d.reveal(name, tagline, line, notes);                       // product name reveal
+   d.scene("f03", { kick, title, features: [[name, desc]], notes, credit, shot, shotRatio }); // shot = UI screenshot, framed right
+   d.cards(kick, title, [[label, name, desc] x3], notes, footnote);
+   d.cta("f16", { title, sub, facts, notes, credit, contact, site, qr }); // qr: PNG path (make with python qrcode), else a [QR] box
+   d.pres.writeFile({ fileName: "Deck.pptx" }).then(console.log);
+   ```
+
+   Branding options on `makeDeck(title, brand)`: `INK, CREAM, MUTED, GOLD, GOLD_BG, cardBg`
+   (hex, no `#`), `SERIF, SANS` (font names), `logo` (light-on-dark PNG path; none = no logo),
+   `logoRatio` (height/width). Defaults are the neutral ink + gold look with no logo.
+   For anything the helpers do not cover (triptych, recap timeline, stat rows) use
+   `d.slide()`, `d.kicker()`, `d.headline()`, `d.body()` and see build.js / build-features.js
+   in the reference project.
+7. **QA:** `./qa.sh build-<name>.js`, look at every printed sheet (or send them to the user), fix, repeat. Clean `qa/` after.
+8. **Report:** file path, the story in one line per slide, every placeholder left, every
+   claim the user must verify, and what was deliberately left out.
+
+## Agent notes (Claude Code, Codex, Gemini CLI, OpenCode, Cursor…)
+Steps name capabilities, not tools. Where your agent lacks one:
+- **web fetch** (finding stock photos, sources): ask the user for photos/links instead.
+- **viewing images** (checking contact sheets / frames): send the image paths to the user and ask them to look.
+- **sub-agents** (reading several repos at once): read them one after another.
+- **structured questions**: ask in plain text with numbered options.

package/skills/story-deck/examples/build-example.js

@@ -0,0 +1,29 @@
+// Worked example: a story deck for a fictional product ("Ledgerly", bookkeeping for small cafés).
+// No photos needed — it uses the image-free helpers. Copy into ~/.kaizen/decks/<slug>/ next to kit.js
+// and run: node build-example.js  (then ./qa.sh build-example.js to check it).
+// In a real deck most beats are photo stories: d.story("bg01", {...}) after prep_images.py made bg/bg01.jpg.
+const { makeDeck } = require("./kit");
+
+const d = makeDeck("Ledgerly — The Closing Hour", {
+  GOLD: "D9A441", GOLD_BG: "D9A441", // brand accent; colours are hex without '#'
+});
+
+d.pause("Every café closes at ten.", "The owner's real work starts after that.",
+  "Open on a feeling, not the product. Pause for two seconds.");
+d.cards("Act II — The pieces", "Three notebooks, one business.", [
+  ["Morning", "Supplier invoices", "Paid from the owner's phone, noted somewhere."],
+  ["Afternoon", "Cash drawer", "Counted twice, written on the back of a receipt."],
+  ["Night", "Spreadsheet", "Retyped from both, after closing."],
+], "Speaker note: numbers only with a source on the slide.", "Each piece is true. None of them talk to each other.");
+d.question("What if the books closed themselves?", "The turn. Say it slowly.");
+d.reveal("Ledgerly", "Bookkeeping that closes with the café.", "Invoices · Cash · Reports",
+  "First time the product is named.");
+d.cta(null, {
+  kick: "Next step", label: "Book a demo",
+  title: "See your own numbers in 20 minutes.",
+  sub: "A demo with a sample of your last month's receipts.",
+  facts: "Web and mobile · English and Bahasa Indonesia",
+  contact: "[Name] · [WhatsApp] · [Email]", site: "[website]",
+  notes: "Fill the contact placeholders before presenting.",
+});
+d.pres.writeFile({ fileName: "Ledgerly-example.pptx" }).then((f) => console.log(f));

package/skills/story-deck/references/rules.md

@@ -0,0 +1,62 @@
+# Rules learned the hard way
+
+## Truth
+- Features: only what has shipped. Verify in the product repo: CHANGELOG released
+  versions + existing pages/routes. "Unreleased", proposals, SPH/quotation docs = not shipped.
+  Note what is missing (e.g. no iOS, no payment gateway) and keep it out of the copy;
+  warn in speaker notes.
+- A requirements/spec doc is not proof of shipping: confirm each feature in the CHANGELOG or in
+  the code itself (content files, pages). Re-read the top of every CHANGELOG right before
+  delivering — products ship while decks are being made (a product changed its login model
+  mid-project once and two slides were already wrong).
+- Stats: never invent. Use official/scientific sources (e.g. Dapodik, BPS, peer-reviewed
+  journals); put a full `Sumber: …` line on the slide and details in notes. If no source
+  exists for a planned stat, swap the stat — do not leave a fake number.
+- Narrative numbers ("140 pesan belum dibaca") are fine but tell the user they are story, not data.
+
+## Images
+- Unsplash blocks curl/napi (bot wall). Use a web-fetch tool on `https://unsplash.com/s/photos/<query>`
+  asking for non-premium image URLs, then download
+  `https://images.unsplash.com/photo-<id>?w=1600&q=80&fm=jpg` with curl (that CDN works).
+- Prefer real local scenes (for Indonesia: query `indonesia-school`, `sekolah`, `pesantren`,
+  `indonesian-teacher`, `indonesia-mechanic`). Build a contact sheet and LOOK before choosing.
+- Never use pptxgenjs `sizing: cover` — Google Slides ignores it and stretches. Crop each
+  image to the exact box ratio in `prep_images.py` (panels: `[w_px, h_px]` = box ratio).
+- Every photo must show the slide's own sentence. Problem slides show the real-world pain
+  (the workshop, the office, the WhatsApp phone); product and feature slides show people
+  USING the kind of tech the product is (students at computers / circuit simulation for a
+  simulator, adults in a training room or on laptops for an LMS). A pretty but unrelated
+  photo (a camera crew, a sermon, kids on a teacher-training slide) gets swapped.
+- Show modern equipment (flat screens, laptops) — never CRT monitors or dated labs when
+  selling software. Mix genders in group shots of students; avoid all-one-gender rooms.
+- For product slides, the product's REAL interface beats any stock photo: look in the repo for
+  screenshots/renders (`public/landing/`, `.preview/`, docs) and use them — framed via
+  `scene({shot, shotRatio})`, or graded as a background if it is a dark render. Never stock
+  photos of program code on screen for a non-coding product.
+- Candid only: people absorbed in what they are doing (teaching, reading, working). No posed
+  portraits — nobody looking into the camera and smiling; it reads as stock and breaks the film.
+  Hands, backs, profiles and wide scenes work best.
+- Photos with readable foreign text (e.g. English survey paper) break the illusion — swap.
+
+## Fonts
+- Default Playfair Display + Inter (both in the Google Slides font menu). Install them locally
+  with `~/.kaizen/decks/.venv/bin/python scripts/install_fonts.py` — it makes STATIC instances. Never install the variable
+  `[wght]` files: some viewers (LibreOffice desktop) draw big headlines greyed out, as if
+  transparent, while the XML colour is correct. A missing font (e.g. Cambria) renders with
+  ugly letter spacing.
+- If a user reports "text not seen": first check the slide XML colour (unzip, look for
+  `srgbClr`/`alpha` on that run). Solid colour there = viewer/font problem, not the deck.
+- Playfair numbers are old-style (low digits); mention it, offer Lora if unwanted.
+
+## Files and tools
+- Output decks as local `.pptx` (user imports into Google Slides). No Artifacts.
+- Everything the skill generates lives in `~/.kaizen/decks/<slug>/`; never write inside the user's
+  project folders. Reading assets (logos, screenshots) from repos is fine.
+- zsh does not word-split `$var` in `for x in $ids` — wrap in `bash -c` or use arrays.
+- `qa.sh` uses the shared `~/.kaizen/decks/.venv` and creates it when missing.
+
+## QA loop
+Run `qa.sh build-x.js`, look at every sheet, fix: text overflowing into the next block
+(headline wrapped to 3 lines), kicker wrapping, labels wrapping in cards, low contrast on
+bright photos (raise gradient strength), page number collisions. Re-run until clean.
+Delete `qa/` and PDFs at the end.

package/skills/story-deck/references/story-arc.md

@@ -0,0 +1,35 @@
+# Story arc and slide recipes
+
+The deck sells a feeling first and the product last. Never open with features.
+
+## The five acts (12–16 slides)
+
+| Act | Slides | Helper | What it does |
+|---|---|---|---|
+| I. World | 1–2 | `story` | Cover line about the audience's world, not the product. Scale or context (sourced stat, or none). |
+| II. One scene | 1–2 | `story`, `pause` | Shrink to one person at one time ("06.45 — Gerbang sekolah"). A black `pause` slide for silence. |
+| III. The pieces | 2–4 | `story`, triptych | Time-stamped scenes of the problem from each viewpoint (admin, teacher, parent…). |
+| IV. The cost | 1–2 | `story` + stats | What is lost (trust, time). Stats only with a source line on the slide. |
+| V. The turn | 1 | `question` | Gold slide, one italic question: "Bagaimana jika …?" |
+| Reveal | 1 | `reveal` | Product name appears for the first time. |
+| Features | 3–6 | `scene`, `cards` | Each scene = kicker (time/place · product), headline, 2–4 feature rows. |
+| CTA | 1 | `cta` | One action (demo), contact placeholders, QR placeholder. |
+
+Follow-up decks (shown after a story deck) skip acts I–V: open with a callback
+cover ("Hari yang sama. Cerita yang berbeda."), revisit the same scenes with a
+`Dulu: "<old headline>"` line (see build-features.js in the reference project), end
+with a recap timeline and the CTA.
+
+## Copy rules
+- One idea per slide. Headline ≤ 2 lines at its size; if it wraps to 3, shorten the words.
+- Kicker = TIME — PLACE or ACT — NAME, uppercase via helper.
+- Body line is the human detail, not a feature list.
+- Name the product only from the reveal onwards.
+- Bahasa Indonesia by default (audience: kepala sekolah/yayasan); English if asked.
+- Speaker notes: delivery cue + caveats + `Foto: <name> / Unsplash.` credit.
+- Placeholders in brackets `[__]`, `[Nama]`, `[QR]` — list them in the final report.
+
+## Layout facts (A5 landscape 8.268 × 5.827 in, margin 0.6)
+- Photo backgrounds: gradient side must match where the text sits (`left` for `scene`, `bottom` for `story`).
+- `scene` rows: 0.7 in pitch, 4 rows max, column width 4.3 in.
+- Source lines: 8 pt at `H - 0.75`, width ≤ 6.2 in (clear of the page number).

package/skills/story-deck/scripts/check.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Requirements for story-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)"
+need npm      "comes with Node.js"
+need python3  "Python 3.9+"
+need soffice  "LibreOffice (renders slides for the visual check)"
+need pdftoppm "poppler-utils (brew install poppler / apt install poppler-utils / pacman -S poppler)"
+[ -d "$HOME/.kaizen/decks/node_modules/pptxgenjs" ] && echo "ok   pptxgenjs" || echo "todo pptxgenjs — cd ~/.kaizen/decks && npm init -y && npm i pptxgenjs"
+fc-list 2>/dev/null | grep -qi "Playfair Display" && echo "ok   fonts" || echo "todo fonts — ~/.kaizen/decks/.venv/bin/python scripts/install_fonts.py"
+exit $miss

package/skills/story-deck/scripts/install_fonts.py

@@ -0,0 +1,42 @@
+"""Install STATIC Playfair Display + Inter into ~/.local/share/fonts/story-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.
+Needs: pip install fonttools (qa.sh's .venv works: .venv/bin/pip install fonttools).
+Usage: python3 install_fonts.py
+"""
+import os
+import subprocess
+import tempfile
+import urllib.request
+
+from fontTools.ttLib import TTFont
+from fontTools.varLib.instancer import instantiateVariableFont
+
+RAW = "https://github.com/google/fonts/raw/main/ofl/"
+SRC = {
+    "pf": "playfairdisplay/PlayfairDisplay%5Bwght%5D.ttf",
+    "pfi": "playfairdisplay/PlayfairDisplay-Italic%5Bwght%5D.ttf",
+    "in": "inter/Inter%5Bopsz,wght%5D.ttf",
+    "ini": "inter/Inter-Italic%5Bopsz,wght%5D.ttf",
+}
+JOBS = [
+    ("pf", "PlayfairDisplay-Regular", {"wght": 400}),
+    ("pf", "PlayfairDisplay-Bold", {"wght": 700}),
+    ("pfi", "PlayfairDisplay-Italic", {"wght": 400}),
+    ("in", "Inter-Regular", {"wght": 400, "opsz": 14}),
+    ("in", "Inter-Bold", {"wght": 700, "opsz": 14}),
+    ("ini", "Inter-Italic", {"wght": 400, "opsz": 14}),
+]
+
+dest = os.path.expanduser("~/.local/share/fonts/story-deck/")
+os.makedirs(dest, exist_ok=True)
+with tempfile.TemporaryDirectory() as tmp:
+    for key, path in SRC.items():
+        urllib.request.urlretrieve(RAW + path, f"{tmp}/{key}.ttf")
+    for key, out, loc in JOBS:
+        font = instantiateVariableFont(TTFont(f"{tmp}/{key}.ttf"), loc, updateFontNames=True, static=True)
+        assert "fvar" not in font
+        font.save(dest + out + ".ttf")
+        print("installed", out)
+subprocess.run(["fc-cache", "-f"], check=False)

package/skills/story-deck/scripts/kit.js

@@ -0,0 +1,174 @@
+// Cinematic story deck helpers: A5 landscape, dark ink + one accent, serif display + sans body.
+// Branding is adjustable: makeDeck(title, { INK, CREAM, MUTED, GOLD, GOLD_BG, SERIF, SANS, logo, logoRatio, cardBg }).
+const pptxgen = require("pptxgenjs");
+
+const W = 8.268, H = 5.827, M = 0.6;
+const DEFAULTS = {
+  INK: "14110F", CREAM: "F3EDE3", MUTED: "B8AFA3", GOLD: "C9A24E", GOLD_BG: "C9A96E", cardBg: "1E1A17",
+  SERIF: "Playfair Display", SANS: "Inter",
+  logo: null,        // path to a light-on-dark logo PNG; null = no logo drawn
+  logoRatio: 0.226,  // logo height / width
+};
+
+function makeDeck(title, brand = {}) {
+  const { INK, CREAM, MUTED, GOLD, GOLD_BG, SERIF, SANS, logo: logoPath, logoRatio, cardBg } = { ...DEFAULTS, ...brand };
+  const pres = new pptxgen();
+  pres.defineLayout({ name: "A5L", width: W, height: H });
+  pres.layout = "A5L";
+  pres.title = title;
+  let page = 0;
+
+  const notesWith = (notes, credit) => notes + (credit ? `\n\nFoto: ${credit} / Unsplash.` : "");
+
+  function slide(bgFile, notes, dark = true) {
+    const s = pres.addSlide();
+    page++;
+    s.background = { color: dark ? INK : GOLD_BG };
+    if (bgFile) s.addImage({ path: `bg/${bgFile}.jpg`, x: 0, y: 0, w: W, h: H });
+    s.addText(String(page).padStart(2, "0"), {
+      x: W - M - 0.6, y: H - 0.45, w: 0.6, h: 0.25, align: "right", margin: 0,
+      fontFace: SANS, fontSize: 8, color: dark ? MUTED : INK, charSpacing: 2, isTextBox: true,
+    });
+    s.addNotes(notes);
+    return s;
+  }
+
+  function kicker(s, text, y, x = M) {
+    s.addText(text.toUpperCase(), {
+      x, y, w: W - x - M, h: 0.3, margin: 0, fontFace: SANS, fontSize: 9, bold: true,
+      color: GOLD, charSpacing: 4, isTextBox: true,
+    });
+  }
+
+  function headline(s, text, y, h, opts = {}) {
+    s.addText(text, {
+      x: opts.x || M, y, w: opts.w || 5.6, h, margin: 0, fontFace: SERIF, fontSize: opts.size || 30,
+      color: opts.color || CREAM, valign: "top", lineSpacingMultiple: 0.95, isTextBox: true, ...opts.extra,
+    });
+  }
+
+  function body(s, text, y, h, opts = {}) {
+    s.addText(text, {
+      x: opts.x || M, y, w: opts.w || 4.6, h, margin: 0, fontFace: SANS, fontSize: opts.size || 12,
+      color: opts.color || MUTED, valign: "top", lineSpacingMultiple: 1.2, isTextBox: true,
+    });
+  }
+
+  function logo(s, x, y, w) {
+    if (logoPath) s.addImage({ path: logoPath, x, y, w, h: w * logoRatio });
+  }
+
+  // Photo story beat: text sits low on the slide (photo gradient is at the bottom or left).
+  function story(bgFile, { kick, title, sub, notes, credit, top = 3.2 }) {
+    const s = slide(bgFile, notesWith(notes, credit));
+    kicker(s, kick, top);
+    headline(s, title, top + 0.35, 1.1, { size: 28, w: 6.2 });
+    if (sub) body(s, sub, top + 1.6, 0.6, { w: 5.2 });
+    return s;
+  }
+
+  // Black pause slide.
+  function pause(line, sub, notes) {
+    const s = slide(null, notes);
+    s.addText(line, {
+      x: 0.8, y: 2.1, w: W - 1.6, h: 0.9, align: "center", valign: "middle", margin: 0,
+      fontFace: SERIF, fontSize: 28, italic: true, color: CREAM, isTextBox: true,
+    });
+    if (sub) s.addText(sub, {
+      x: 0.8, y: 3.1, w: W - 1.6, h: 0.5, align: "center", margin: 0, fontFace: SANS, fontSize: 12,
+      color: MUTED, isTextBox: true,
+    });
+    return s;
+  }
+
+  // Gold statement slide.
+  function question(line, notes) {
+    const s = slide(null, notes, false);
+    s.addText(line, {
+      x: 1.0, y: 1.9, w: W - 2.0, h: 1.8, align: "center", valign: "middle", margin: 0,
+      fontFace: SERIF, fontSize: 32, italic: true, color: INK, isTextBox: true,
+    });
+    return s;
+  }
+
+  // Product name reveal.
+  function reveal(name, tagline, line, notes) {
+    const s = slide(null, notes);
+    s.addText(name, {
+      x: 0, y: 1.75, w: W, h: 1.0, align: "center", margin: 0, fontFace: SERIF, fontSize: 54,
+      color: CREAM, isTextBox: true,
+    });
+    s.addText(tagline, {
+      x: 0, y: 2.85, w: W, h: 0.5, align: "center", margin: 0, fontFace: SERIF, fontSize: 17,
+      italic: true, color: CREAM, isTextBox: true,
+    });
+    s.addText(line.toUpperCase(), {
+      x: 0, y: 3.45, w: W, h: 0.3, align: "center", margin: 0, fontFace: SANS, fontSize: 9,
+      bold: true, color: GOLD, charSpacing: 4, isTextBox: true,
+    });
+    return s;
+  }
+
+  // Feature slide: kicker, headline, feature rows in a left text column.
+  // shot: product screenshot path shown framed on the right (bgFile may be null); shotRatio = w/h.
+  function scene(bgFile, { kick, title, features, notes, credit, shot, shotRatio = 1.6 }) {
+    const s = slide(bgFile, notesWith(notes, credit));
+    if (shot) {
+      const sw = 3.0, sh = sw / shotRatio, sx = W - M - sw, sy = (H - sh) / 2;
+      s.addShape(pres.shapes.RECTANGLE, { x: sx - 0.06, y: sy - 0.06, w: sw + 0.12, h: sh + 0.12, fill: { color: cardBg }, line: { color: GOLD, width: 0.75 } });
+      s.addImage({ path: shot, x: sx, y: sy, w: sw, h: sh });
+    }
+    kicker(s, kick, M);
+    headline(s, title, 0.95, 1.0, { size: 24, w: 4.3 });
+    let y = 2.1;
+    features.forEach(([name, desc]) => {
+      s.addText([
+        { text: name, options: { fontFace: SANS, fontSize: 11, bold: true, color: CREAM, breakLine: true } },
+        { text: desc, options: { fontFace: SANS, fontSize: 9.5, color: MUTED } },
+      ], { x: M, y, w: shot ? 3.85 : 4.3, h: 0.62, margin: 0, valign: "top", lineSpacingMultiple: 1.1, isTextBox: true });
+      y += 0.7;
+    });
+    return s;
+  }
+
+  // Three dark cards.
+  function cards(kick, title, items, notes, footnote) {
+    const s = slide(null, notes);
+    kicker(s, kick, M);
+    headline(s, title, 0.95, 0.9, { size: 26, w: 6.8 });
+    const cw = 2.2, gap = (W - 2 * M - 3 * cw) / 2, cy = 2.3;
+    items.forEach(([label, name, desc], i) => {
+      const x = M + i * (cw + gap);
+      s.addShape(pres.shapes.RECTANGLE, { x, y: cy, w: cw, h: 2.0, fill: { color: cardBg } });
+      s.addText([
+        { text: label.toUpperCase(), options: { fontFace: SANS, fontSize: 8, bold: true, color: GOLD, charSpacing: 1, breakLine: true } },
+        { text: name, options: { fontFace: SERIF, fontSize: 17, color: CREAM, breakLine: true } },
+        { text: desc, options: { fontFace: SANS, fontSize: 10, color: MUTED } },
+      ], { x: x + 0.2, y: cy + 0.2, w: cw - 0.4, h: 1.6, margin: 0, valign: "top", paraSpaceAfter: 6, isTextBox: true });
+    });
+    if (footnote) body(s, footnote, 4.6, 0.3, { size: 10, w: 7.0 });
+    return s;
+  }
+
+  function cta(bgFile, { title, sub, facts, notes, credit, kick = "Langkah berikutnya", label = "Jadwalkan demo",
+    contact = "[Nama]  ·  [WhatsApp]  ·  [Email]", site = "[website]", qr = null }) {
+    const s = slide(bgFile, notesWith(notes, credit));
+    kicker(s, kick, 1.5);
+    headline(s, title, 1.85, 1.0, { size: 30, w: 6.2 }); // room for two lines
+    body(s, sub, 2.95, 0.5, { w: 4.4 });
+    s.addText([
+      { text: label.toUpperCase(), options: { fontFace: SANS, fontSize: 9, bold: true, color: GOLD, charSpacing: 4, breakLine: true } },
+      { text: contact, options: { fontFace: SANS, fontSize: 12, color: CREAM, breakLine: true } },
+      { text: site, options: { fontFace: SANS, fontSize: 12, color: MUTED } },
+    ], { x: M, y: 3.55, w: 4.4, h: 0.9, margin: 0, valign: "top", paraSpaceAfter: 4, isTextBox: true });
+    if (qr) s.addImage({ path: qr, x: W - M - 1.3, y: 3.2, w: 1.3, h: 1.3 });
+    else { s.addShape(pres.shapes.RECTANGLE, { x: W - M - 1.3, y: 3.2, w: 1.3, h: 1.3, fill: { color: CREAM } }); s.addText("[QR]", { x: W - M - 1.3, y: 3.2, w: 1.3, h: 1.3, align: "center", valign: "middle", margin: 0, fontFace: SANS, fontSize: 12, color: INK, isTextBox: true }); }
+    if (facts) body(s, facts, 4.45, 0.3, { size: 9 });
+    logo(s, M, H - 0.55, 1.6);
+    return s;
+  }
+
+  return { pres, slide, kicker, headline, body, logo, story, pause, question, reveal, scene, cards, cta };
+}
+
+module.exports = { makeDeck, W, H, M };

package/skills/story-deck/scripts/prep_images.py

@@ -0,0 +1,70 @@
+"""Crop photos to the slide and bake in the dark cinematic grade.
+
+Usage: python3 prep_images.py plan.json   (run from the deck folder; reads img/, writes bg/)
+
+plan.json:
+  {"backgrounds": {"s01": ["<photo id>", focusY, base, "left|right|bottom", strength]},
+   "panels":      {"p1":  ["<photo id>", focusY, [w_px, h_px]]}}
+  photo id = file name in img/ without .jpg. focusY 0..1 = vertical crop focus.
+  base = overall darkening 0..1. strength = gradient darkness on the text side 0..1.
+  Panel size must have the SAME ratio as its box on the slide (w_in/h_in); pptxgenjs
+  "sizing" is ignored by Google Slides and stretches the photo.
+
+pptxgenjs has no gradient fills, so the text-side shadow lives in the image.
+"""
+import json
+import sys
+from pathlib import Path
+
+from PIL import Image, ImageEnhance
+
+W, H = 1800, 1273  # A5 landscape (210:148)
+INK = (20, 17, 15)
+
+
+def crop(im, w, h, focus_y):
+    r = w / h
+    if im.width / im.height > r:  # too wide: crop sides
+        nw = int(im.height * r)
+        x = (im.width - nw) // 2
+        im = im.crop((x, 0, x + nw, im.height))
+    else:  # too tall: crop around focus
+        nh = int(im.width / r)
+        y = int((im.height - nh) * focus_y)
+        im = im.crop((0, y, im.width, y + nh))
+    out = im.resize((w, h), Image.LANCZOS)
+    assert abs(out.width / out.height - r) < 0.01
+    return out
+
+
+def grade(im):
+    im = ImageEnhance.Color(im).enhance(0.75)  # mute colours, film look
+    return Image.blend(im, Image.new("RGB", im.size, (60, 40, 20)), 0.08)
+
+
+def overlay(im, base, side, strength):
+    ink = Image.new("RGB", im.size, INK)
+    im = Image.blend(im, ink, base)
+    g = Image.linear_gradient("L")  # black top -> white bottom
+    if side == "left":
+        g = g.rotate(-90)
+    elif side == "right":
+        g = g.rotate(90)
+    g = g.resize(im.size).point(lambda v: int(v * strength))
+    return Image.composite(ink, im, g)
+
+
+def main(plan_path):
+    plan = json.loads(Path(plan_path).read_text())
+    Path("bg").mkdir(exist_ok=True)
+    for sid, (pid, fy, base, side, s) in plan.get("backgrounds", {}).items():
+        im = Image.open(f"img/{pid}.jpg").convert("RGB")
+        overlay(grade(crop(im, W, H, fy)), base, side, s).save(f"bg/{sid}.jpg", quality=85)
+    for sid, (pid, fy, (pw, ph)) in plan.get("panels", {}).items():
+        im = grade(crop(Image.open(f"img/{pid}.jpg").convert("RGB"), pw, ph, fy))
+        Image.blend(im, Image.new("RGB", im.size, INK), 0.35).save(f"bg/{sid}.jpg", quality=85)
+    print("ok")
+
+
+if __name__ == "__main__":
+    main(sys.argv[1] if len(sys.argv) > 1 else "plan.json")

package/skills/story-deck/scripts/qa.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Build a deck, check the file, render every slide, and write 2x4 contact sheets to qa/.
+# Usage (from the deck folder): qa.sh build-x.js      -> prints the qa/sheet*.jpg paths to look at
+# Uses the Anthropic pptx skill's validator when installed; otherwise a built-in structural check.
+set -euo pipefail
+BUILD=${1:?usage: qa.sh build-script.js}
+"$(dirname "$0")/check.sh" >/dev/null 2>&1 || { "$(dirname "$0")/check.sh" 2>/dev/null || true; }
+V=$HOME/.kaizen/decks/.venv
+[ -x "$V/bin/python" ] || { python3 -m venv "$V" && "$V/bin/pip" -q install defusedxml lxml pillow fonttools "qrcode[pil]"; }
+PY=$V/bin/python
+F=$(node "$BUILD")
+PPTX_SKILL=$(ls -d ~/.claude/skills/*/pptx/scripts ~/.claude/skills/synced/*/pptx/scripts 2>/dev/null | head -1 || true)
+if [ -n "$PPTX_SKILL" ] && [ -f "$PPTX_SKILL/office/validate.py" ]; then
+  $PY "$PPTX_SKILL/office/validate.py" "$F"
+  $PY "$PPTX_SKILL/office/soffice.py" --headless --convert-to pdf "$F" >/dev/null
+else
+  # structural check: valid zip, every XML part parses, every slide relationship target exists
+  $PY - "$F" <<'PYEOF'
+import sys, zipfile, posixpath
+from lxml import etree
+z = zipfile.ZipFile(sys.argv[1]); bad = z.testzip()
+assert bad is None, f"corrupt part: {bad}"
+names = {n for n in z.namelist() if not n.endswith("/")}  # skip directory entries
+for n in names:
+    if n.endswith(".xml") or n.endswith(".rels"):
+        etree.fromstring(z.read(n))
+for n in names:
+    if n.startswith("ppt/slides/_rels/"):
+        for r in etree.fromstring(z.read(n)):
+            t = r.get("Target")
+            if r.get("TargetMode") == "External" or not t: continue
+            p = posixpath.normpath(posixpath.join("ppt/slides", t))
+            assert p in names, f"{n}: missing {p}"
+print("structure OK:", sum(1 for n in names if n.startswith("ppt/slides/slide")), "slides")
+PYEOF
+  soffice --headless --convert-to pdf --outdir "$(dirname "$F")" "$F" >/dev/null 2>&1
+fi
+rm -rf qa && mkdir qa
+pdftoppm -jpeg -r 70 "${F%.pptx}.pdf" qa/s
+rm -f "${F%.pptx}.pdf"
+$PY - <<'PYEOF'
+from PIL import Image; import glob, os
+ims=[Image.open(f) for f in sorted(glob.glob('qa/s-*.jpg'))]; w,h=ims[0].size
+for p in range(0,len(ims),8):
+    g=ims[p:p+8]; sh=Image.new('RGB',(w*2,h*4),'white')
+    for i,im in enumerate(g): sh.paste(im,((i%2)*w,(i//2)*h))
+    sh.save(f'qa/sheet{p//8}.jpg'); print(f'{os.getcwd()}/qa/sheet{p//8}.jpg')
+PYEOF