@olegkoval/agent-skills 1.60.0 → 1.61.0

package/adapters/claude/olko-creative/skills/carousel-maker/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: carousel-maker
+description: Use when someone wants Instagram or LinkedIn carousel slides from a topic, a brief or pasted copy. A fixed brand template sets the text on every slide, and an optional library of hand-drawn illustrations, drawn once in code per brand and reused across decks, supplies the pictures. No image models or stock.
+license: MIT
+allowed-tools: Bash, Read, Write, Edit
+compatibility: Codex, Claude Code, Hermes Agent, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Needs Node 22.18+ and Chrome; ffmpeg for the contact sheet. The illustration library needs the shorts-animator skill installed alongside.
+metadata:
+  targets: [_source-only]
+  author: Oleg Koval
+  tags:
+    - instagram
+    - carousel
+    - social
+    - design
+    - slides
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Carousel Maker
+
+A brand and a few lines of copy in, 1080x1350 carousel slides out. The template places the text, so it
+is never garbled and never off-brand. Pictures come from the brand's library: drawings written once as
+canvas code, painted by shorts-animator, and reused by every deck after that. Text-only decks need no
+library at all.
+
+`CM` = `node <this skill's folder>/scripts/cm.ts`. Write the full command each time. One folder per
+brand: `BRAND=./<slug>-carousels`. Decks live in `$BRAND/decks/<deck>.json`.
+
+## 1. Decide the copy
+
+Decide the slides yourself. Ask one question only if the subject or the brand is unclear. A pasted
+script is used word for word.
+
+- 5 to 8 slides: a `cover`, then `point` slides, then one `cta`.
+- The cover is a promise in 8 words or fewer. It is the only slide most people see.
+- One idea per point slide: a title of 7 words or fewer, a body of 22 words or fewer.
+- The cta asks for one thing (save, follow, comment) and carries a `follow` line.
+- `caption` is the post text: two short lines and one question for the comments.
+
+## 2. Set up the brand
+
+```bash
+CM new "$BRAND" --name "Slow Hours" --handle @slowhours --look ink   # brand.json, decks/, art/, library/
+```
+
+`brand.json`: `name`, `handle`, `colors` (`paper`, `ink`, `accent`, `muted`, all `#rrggbb`), `fonts`
+(`head`, `body`, CSS font stacks). Set them from what they told you; the defaults are cream, near-black
+and orange. `--look` picks the paint for the library: `ink`, `gouache`, `watercolor`, `pastel`, `oil`.
+
+A deck:
+
+```json
+{ "title": "mornings", "caption": "...", "slides": [
+  { "kind": "cover", "title": "Slow mornings, in 4 steps", "body": "No 5am club.", "art": "window" },
+  { "kind": "point", "title": "Coffee, outside", "body": "Five minutes on the step.", "art": "coffee" },
+  { "kind": "point", "title": "Their own photo", "art": "photos/desk.jpg" },
+  { "kind": "cta", "title": "Save this for tomorrow", "follow": "Follow @slowhours" } ] }
+```
+
+`art` is a library drawing (a bare name), a file (a path, relative to `$BRAND`), or left out for a
+text-only slide, which gets larger type.
+
+## 3. Draw the library (once per brand)
+
+Skip this for text-only decks. Every bare `art` name needs a function in `$BRAND/art/scenes.js`:
+`window.SCENES = { "window": (k) => { k.sky({...}); ... } }`. Read `../shorts-animator/references/kit.md`
+before writing scenes. Draw objects and places, square, one subject, big simple shapes, strong value
+contrast; the paint pass adds texture. No people's faces close up.
+
+```bash
+CM art "$BRAND"            # every drawing the decks use -> library/<name>.jpg
+CM art "$BRAND" coffee     # only these
+```
+
+Look at the sheet it reports once. Redraw only the drawings that are muddy, empty or look alike. The
+library is the brand's asset: the next deck reuses it and only new names cost a drawing.
+
+## 4. Check, render, look (budgeted)
+
+```bash
+CM check "$BRAND" [deck]   # no browser: unknown kinds, missing drawings or files, deck shape, word counts
+CM render "$BRAND" [deck]  # out/<deck>/slide-N.png, sheet.jpg, caption.txt; measures every slide
+```
+
+Fix every `ERROR` from `check` before rendering. `render` also fails a slide whose text spills out of
+its frame or whose picture did not load. Then read `out/<deck>/sheet.jpg` once. **Budget: at most two
+looks per deck** (the library sheet and the deck sheet). Images are the expensive part of this loop; do
+not reopen a sheet you have already judged.
+
+Tell them in two lines what it is (slides, look) and: "Tell me what to change, one sentence is enough."
+
+## 5. One-sentence changes
+
+Smallest change, `CM check`, render, show.
+
+| they say | change |
+|---|---|
+| shorter, punchier | the slide's `title` or `body` |
+| different colours, our brand | `brand.json` `colors` |
+| serif, sans, our font | `brand.json` `fonts` |
+| a different picture on slide 3 | that slide's `art`, or one new scene plus `CM art "$BRAND" <name>` |
+| no pictures | drop `art` from the slides |
+| another post on the same brand | a new `decks/<deck>.json`; reuse library names |
+
+## When something goes wrong
+
+| symptom | fix |
+|---|---|
+| no Chrome | install Chrome, or set `CHROME` to a Chrome or headless-shell binary |
+| `CM art` cannot find shorts-animator | install it alongside, or set `SHORTS_ANIMATOR` to its `scripts/sa.ts` |
+| "text spills out of the frame" | cut words; `check` warns before this happens |
+| no sheet.jpg | ffmpeg is missing; the slides are still in `out/<deck>/` |

package/adapters/claude/olko-creative/skills/carousel-maker/scripts/cm.ts

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+/*
+ * Carousel Maker: a brand and a few lines of copy in, Instagram carousel slides out.
+ *
+ *   CM new <dir> [--name "Brand"] [--handle @x] [--look ink]   brand.json, decks/example.json, art/
+ *   CM check <dir> [deck]                                        what a render would get wrong, no browser
+ *   CM art <dir> [scene...]                                      draws the library: art/scenes.js -> library/<scene>.jpg
+ *   CM render <dir> [deck]                                       slides -> out/<deck>/slide-N.png, sheet.jpg, caption.txt
+ *
+ * CM = node <skill-dir>/scripts/cm.ts
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { check, fitFindings, report, type Finding, type Fit } from "./domain/check.ts";
+import { contexts, H, MEASURE, page, section } from "./domain/layout.ts";
+import { isMap, parseBrand, parseDeck } from "./domain/schema.ts";
+import type { Art, Brand, Deck, Json, Result } from "./domain/types.ts";
+import { dumpDom, findChrome, mkdir, readJson, screenshot, sheet, url, writeJson, writeNew } from "./edge/io.ts";
+
+type Args = { readonly dir: string | undefined; readonly rest: readonly string[] };
+type Command = (a: Args) => Promise<number>;
+
+const SA = process.env.SHORTS_ANIMATOR ?? path.join(import.meta.dirname, "../../shorts-animator/scripts/sa.ts");
+const ART_LOOKS = ["ink", "gouache", "watercolor", "pastel", "oil"];
+
+const unwrap = <T>(r: Result<T>): T => {
+  if (!r.ok) throw new Error(r.errors.join("\n  "));
+  return r.value;
+};
+const need = (dir: string | undefined, usage: string): string => {
+  if (!dir) throw new Error(`usage: ${usage}`);
+  return dir;
+};
+const opt = (rest: readonly string[], k: string, dflt: string): string => {
+  const i = rest.indexOf(`--${k}`);
+  return (i >= 0 ? rest[i + 1] : undefined) ?? dflt;
+};
+const positional = (rest: readonly string[]): readonly string[] =>
+  rest.filter((a, i) => !a.startsWith("--") && !(rest[i - 1] ?? "").startsWith("--"));
+
+const brandOf = (d: string): Brand => unwrap(parseBrand(readJson(path.join(d, "brand.json"))));
+const deckFiles = (d: string, only?: string): readonly string[] => {
+  const ddir = path.join(d, "decks");
+  const all = fs.existsSync(ddir) ? fs.readdirSync(ddir).filter((f) => f.endsWith(".json")).toSorted() : [];
+  const picked = only ? all.filter((f) => f === `${only.replace(/\.json$/, "")}.json`) : all;
+  if (picked.length === 0) throw new Error(only ? `no deck decks/${only}.json` : `no decks in ${ddir}`);
+  return picked.map((f) => path.join(ddir, f));
+};
+const deckOf = (f: string): Deck => {
+  const r = parseDeck(readJson(f));
+  if (!r.ok) throw new Error(`${path.basename(f)}:\n  ${r.errors.join("\n  ")}`);
+  return r.value;
+};
+const library = (d: string): readonly string[] => {
+  const ldir = path.join(d, "library");
+  return fs.existsSync(ldir) ? fs.readdirSync(ldir).filter((f) => f.endsWith(".jpg")).map((f) => f.slice(0, -4)) : [];
+};
+const artPath = (d: string, a: Art): string | undefined =>
+  a.kind === "library" ? path.join(d, "library", `${a.name}.jpg`) : a.kind === "file" ? path.resolve(d, a.file) : undefined;
+
+const deckFindings = (d: string, deck: Deck): readonly Finding[] =>
+  check({
+    deck, library: library(d),
+    files: deck.slides.flatMap((s) => (s.art.kind === "file" && fs.existsSync(path.resolve(d, s.art.file)) ? [s.art.file] : [])),
+  });
+
+const sa = (args: readonly string[]): number => {
+  if (!fs.existsSync(SA)) throw new Error(`shorts-animator not found at ${SA}; install it next to this skill or set SHORTS_ANIMATOR`);
+  return spawnSync(process.execPath, [SA, ...args], { stdio: "inherit" }).status ?? 1;
+};
+
+const EXAMPLE_DECK = {
+  title: "Example",
+  caption: "The post text under the carousel. Two short lines and one question for the comments.",
+  slides: [
+    { kind: "cover", title: "Five-word promise goes here", body: "One line on who it is for.", art: "cover" },
+    { kind: "point", title: "First step, short", body: "One or two plain sentences that make it concrete." },
+    { kind: "point", title: "Second step, short", body: "One or two plain sentences that make it concrete." },
+    { kind: "cta", title: "Save this for later", body: "Try one step today.", follow: "Follow for more." },
+  ],
+};
+const EXAMPLE_SCENES = `// One function per library drawing, named the way decks refer to it ("art": "cover").
+// k is the shorts-animator kit (../shorts-animator/references/kit.md). One big subject, 1:1, brand colours.
+window.SCENES = {
+  cover: (k) => {
+    k.sky({ stops: ["#f4efe3", "#e8dcc4"] });
+    k.sun({ x: 0.5, y: 0.45, r: 0.18, color: "#e0783a" });
+  },
+};
+`;
+
+const create: Command = async ({ dir, rest }) => {
+  const d = need(dir, "CM new <dir>");
+  mkdir(d, "decks");
+  mkdir(d, "library");
+  const name = opt(rest, "name", "Untitled brand");
+  const look = opt(rest, "look", "ink");
+  if (!ART_LOOKS.includes(look)) throw new Error(`--look must be one of ${ART_LOOKS.join(", ")}`);
+  writeNew(path.join(d, "brand.json"), JSON.stringify({ name, handle: opt(rest, "handle", ""), look,
+    colors: { paper: "#f4efe3", ink: "#1b1712", accent: "#e0783a", muted: "#6b6257" },
+    fonts: { head: "Georgia, serif", body: '"Helvetica Neue", Helvetica, Arial, sans-serif' } }, null, 2) + "\n");
+  writeNew(path.join(d, "decks", "example.json"), JSON.stringify(EXAMPLE_DECK, null, 2) + "\n");
+  const art = path.join(d, "art");
+  if (!fs.existsSync(path.join(art, "short.json")) && fs.existsSync(SA)) {
+    sa(["new", art, "--look", look, "--format", "1:1"]);
+    fs.writeFileSync(path.join(art, "scenes.js"), EXAMPLE_SCENES);
+  }
+  console.log(`✓ ${d}\n  brand.json   name, handle, colours, fonts, art look\n  decks/       one JSON per carousel\n  art/         the drawings (scenes.js), drawn once per brand\n  library/     the drawn pictures decks pick from`);
+  return 0;
+};
+
+const checkCmd: Command = async ({ dir, rest }) => {
+  const d = need(dir, "CM check <dir> [deck]");
+  brandOf(d);
+  const results = deckFiles(d, positional(rest)[0]).map((f) => {
+    const found = deckFindings(d, deckOf(f));
+    console.log(`${path.basename(f, ".json")}: ${report(found)}`);
+    return found;
+  });
+  return results.flat().some((f) => f.level === "error") ? 1 : 0;
+};
+
+/** Every library name any deck asks for, in first-use order. */
+const wanted = (d: string): readonly string[] => [
+  ...new Set(deckFiles(d).flatMap((f) => deckOf(f).slides.flatMap((s) => (s.art.kind === "library" ? [s.art.name] : [])))),
+];
+
+const art: Command = async ({ dir, rest }) => {
+  const d = need(dir, "CM art <dir> [scene...]");
+  const names = positional(rest).length > 0 ? positional(rest) : wanted(d);
+  if (names.length === 0) throw new Error("no deck asks for a library drawing; add \"art\": \"<scene>\" to a slide or name scenes");
+  const adir = path.join(d, "art");
+  const short = fs.existsSync(path.join(adir, "short.json")) ? readJson(path.join(adir, "short.json")) : {};
+  const base: { readonly [k: string]: Json } = isMap(short) ? short : {};
+  // One still line per drawing, so frame N is drawing N; no voice, music or captions to pay for.
+  writeJson(path.join(mkdir(adir), "short.json"), {
+    ...base, title: `${brandOf(d).name} art`, format: "1:1", voice: "none", music: "none", captions: { style: "none" },
+    lines: names.map((n) => ({ say: `the ${n} drawing for a carousel slide`, scene: n, move: "still" })),
+  });
+  if (sa(["check", adir]) !== 0) return 1;
+  if (sa(["frames", adir]) !== 0) return 1;
+  const ldir = mkdir(d, "library");
+  names.forEach((n, i) => fs.copyFileSync(path.join(adir, "frames", `s${String(i).padStart(3, "0")}.jpg`), path.join(ldir, `${n}.jpg`)));
+  console.log(`✓ ${names.length} drawings -> ${ldir}\n  look once at ${path.join(adir, "frames", "sheet.jpg")}`);
+  return 0;
+};
+
+const fitOf = (dom: string): readonly Fit[] => {
+  const m = /<pre id="fit">([^<]*)<\/pre>/.exec(dom);
+  const raw: unknown = m?.[1] ? JSON.parse(m[1].replace(/&quot;/g, '"').replace(/&amp;/g, "&")) : [];
+  return Array.isArray(raw)
+    ? raw.flatMap((x: unknown) => (isMap(x) && typeof x["slide"] === "number"
+      ? [{ slide: x["slide"], overflow: x["overflow"] === true, missingArt: x["missingArt"] === true }] : []))
+    : [];
+};
+
+const renderDeck = (d: string, brand: Brand, f: string): readonly Finding[] => {
+  const deck = deckOf(f);
+  const before = deckFindings(d, deck);
+  if (before.some((x) => x.level === "error")) return before;
+  const chrome = findChrome();
+  if (!chrome) throw new Error("no Chrome found; install Chrome or set CHROME=/path/to/chrome");
+  const out = mkdir(d, "out", path.basename(f, ".json"));
+  const srcs = deck.slides.map((s) => {
+    const p = artPath(d, s.art);
+    return p ? url(p) : undefined;
+  });
+  const ctxs = contexts(brand, deck.slides, srcs);
+  const sections = deck.slides.flatMap((s, i) => {
+    const c = ctxs[i];
+    return c ? [section(s, c)] : [];
+  });
+  const deckHtml = path.join(out, "deck.html");
+  fs.writeFileSync(deckHtml, page(brand, sections.join(""), MEASURE));
+  const fit = fitFindings(fitOf(dumpDom(chrome, deckHtml, H)));
+  sections.forEach((s, i) => {
+    const html = path.join(out, `slide-${i + 1}.html`);
+    fs.writeFileSync(html, page(brand, s));
+    screenshot(chrome, html, path.join(out, `slide-${i + 1}.png`));
+  });
+  fs.writeFileSync(path.join(out, "caption.txt"), (deck.caption ?? "") + "\n");
+  const sheetFile = path.join(out, "sheet.jpg");
+  const made = sheet(path.join(out, "slide-%d.png"), deck.slides.length, sheetFile);
+  console.log(`✓ ${deck.slides.length} slides -> ${out}${made ? `\n  look once at ${sheetFile}` : "\n  (no ffmpeg: no contact sheet)"}`);
+  return [...before, ...fit];
+};
+
+const render: Command = async ({ dir, rest }) => {
+  const d = need(dir, "CM render <dir> [deck]");
+  const brand = brandOf(d);
+  const found = deckFiles(d, positional(rest)[0]).flatMap((f) => {
+    const r = renderDeck(d, brand, f);
+    if (r.length > 0) console.log(`${path.basename(f, ".json")}: ${report(r)}`);
+    return r;
+  });
+  return found.some((f) => f.level === "error") ? 1 : 0;
+};
+
+const COMMANDS: Readonly<Record<string, Command>> = { new: create, check: checkCmd, art, render };
+
+const usage = (): string => fs.readFileSync(import.meta.filename, "utf8").split("\n").slice(2, 11).join("\n").replace(/^ \* ?/gm, "");
+
+process.removeAllListeners("warning");
+process.on("warning", (w) => {
+  if (!(w.name === "ExperimentalWarning" && /stripTypeScriptTypes/.test(w.message))) console.error(`${w.name}: ${w.message}`);
+});
+
+const [cmd = "", dirArg, ...rest] = process.argv.slice(2);
+const command = COMMANDS[cmd];
+if (!command) {
+  console.log(usage());
+  process.exit(cmd ? 1 : 0);
+}
+command({ dir: dirArg ? path.resolve(dirArg) : undefined, rest })
+  .then((code) => process.exit(code))
+  .catch((e: unknown) => {
+    console.error("✗ " + (e instanceof Error ? e.message : String(e)));
+    process.exit(1);
+  });

package/adapters/claude/olko-creative/skills/carousel-maker/scripts/domain/check.ts

@@ -0,0 +1,68 @@
+// `CM check`: catch what a render would get wrong, before paying for one. Each rule is a pure
+// function over plain facts; the edge gathers the facts (the deck, the library, which files exist).
+import { KINDS } from "./layout.ts";
+import type { Deck, Slide } from "./types.ts";
+
+export type Facts = { readonly deck: Deck; readonly library: readonly string[]; readonly files: readonly string[] };
+export type Fit = { readonly slide: number; readonly overflow: boolean; readonly missingArt: boolean };
+export type Finding = { readonly level: "error" | "warn"; readonly where: string; readonly msg: string };
+
+const SLIDES = { min: 3, max: 10 };
+
+const err = (where: string, msg: string): Finding => ({ level: "error", where, msg });
+const warn = (where: string, msg: string): Finding => ({ level: "warn", where, msg });
+const at = (i: number): string => `slide ${i + 1}`;
+const words = (s: string | undefined): number => (s ? s.trim().split(/\s+/).length : 0);
+const each = (deck: Deck, rule: (s: Slide, i: number) => readonly Finding[]): readonly Finding[] => deck.slides.flatMap(rule);
+
+const unknownKinds = ({ deck }: Facts): readonly Finding[] =>
+  each(deck, (s, i) => (KINDS[s.kind] ? [] : [err(at(i), `kind "${s.kind}" is not one of ${Object.keys(KINDS).join(", ")}`)]));
+
+const deckSize = ({ deck: { slides } }: Facts): readonly Finding[] =>
+  slides.length < SLIDES.min || slides.length > SLIDES.max ? [warn("deck", `${slides.length} slides; ${SLIDES.min} to ${SLIDES.max} read best`)] : [];
+
+const shape = ({ deck: { slides } }: Facts): readonly Finding[] => [
+  ...(slides[0]?.kind === "cover" ? [] : [warn(at(0), "the first slide should be a cover: it is the only one most people see")]),
+  ...(slides.length < 2 || slides.at(-1)?.kind === "cta" ? [] : [warn(at(slides.length - 1), "the last slide should be a cta (save, follow, comment)")]),
+];
+
+const lengths = ({ deck }: Facts): readonly Finding[] =>
+  each(deck, (s, i) => {
+    const k = KINDS[s.kind];
+    if (!k) return [];
+    return [
+      ...(words(s.title) > k.titleWords ? [warn(at(i), `title is ${words(s.title)} words; a ${s.kind} title fits ${k.titleWords}`)] : []),
+      ...(words(s.body) > k.bodyWords ? [warn(at(i), `body is ${words(s.body)} words; a ${s.kind} body fits ${k.bodyWords}`)] : []),
+    ];
+  });
+
+const missingArt = ({ deck, library, files }: Facts): readonly Finding[] => {
+  const lib = new Set(library);
+  const have = new Set(files);
+  return each(deck, (s, i) =>
+    s.art.kind === "library" && !lib.has(s.art.name)
+      ? [err(at(i), `no drawing "${s.art.name}" in library/; add it to art/scenes.js and run CM art`)]
+      : s.art.kind === "file" && !have.has(s.art.file)
+        ? [err(at(i), `no file ${s.art.file}`)]
+        : [],
+  );
+};
+
+const repeatedArt = ({ deck }: Facts): readonly Finding[] => {
+  const names = deck.slides.map((s) => (s.art.kind === "library" ? s.art.name : s.art.kind === "file" ? s.art.file : ""));
+  return names.flatMap((n, i) => (n && names.indexOf(n) < i ? [warn(at(i), `repeats the picture of slide ${names.indexOf(n) + 1}`)] : []));
+};
+
+const RULES = [unknownKinds, missingArt, deckSize, shape, lengths, repeatedArt];
+
+export const check = (facts: Facts): readonly Finding[] => RULES.flatMap((rule) => rule(facts));
+
+/** What the browser measured after layout, as findings. */
+export const fitFindings = (fit: readonly Fit[]): readonly Finding[] =>
+  fit.flatMap((f) => [
+    ...(f.overflow ? [err(`slide ${f.slide}`, "text spills out of the frame; shorten the title or body")] : []),
+    ...(f.missingArt ? [err(`slide ${f.slide}`, "its picture did not load")] : []),
+  ]);
+
+export const report = (fs: readonly Finding[]): string =>
+  fs.length === 0 ? "check: clean" : fs.map((f) => `${f.level === "error" ? "ERROR" : "warn "} ${f.where}: ${f.msg}`).join("\n");

package/adapters/claude/olko-creative/skills/carousel-maker/scripts/domain/layout.ts

@@ -0,0 +1,75 @@
+// The brand template: one fixed 1080x1350 layout per slide kind, filled from the deck. Pure strings;
+// the edge decides where the HTML goes and resolves each picture to a URL first.
+import type { Brand, Slide } from "./types.ts";
+
+export const W = 1080;
+export const H = 1350;
+
+export type Ctx = { readonly brand: Brand; readonly n: number; readonly total: number; readonly point: number; readonly src?: string };
+type Kind = { readonly titleWords: number; readonly bodyWords: number; readonly render: (s: Slide, c: Ctx) => string };
+
+export const esc = (s: string): string => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+const img = (c: Ctx): string => (c.src ? `<img class="art" src="${esc(c.src)}">` : "");
+const para = (text: string | undefined, cls = "body"): string => (text ? `<p class="${cls}">${esc(text)}</p>` : "");
+const BOOKMARK = (b: Brand): string =>
+  `<svg class="mark" width="150" height="190" viewBox="0 0 150 190"><path d="M14 10h122v170l-61-44-61 44z" fill="${b.colors.accent}" stroke="${b.colors.ink}" stroke-width="8" stroke-linejoin="round"/></svg>`;
+
+export const KINDS: Readonly<Record<string, Kind>> = {
+  cover: { titleWords: 8, bodyWords: 14, render: (s, c) => `${img(c)}<h1>${esc(s.title)}</h1>${para(s.body)}` },
+  point: {
+    titleWords: 7, bodyWords: 22,
+    render: (s, c) => `<div class="n">${String(c.point).padStart(2, "0")}</div><h1>${esc(s.title)}</h1>${para(s.body)}${img(c)}`,
+  },
+  cta: { titleWords: 6, bodyWords: 14, render: (s, c) => `${c.src ? img(c) : BOOKMARK(c.brand)}<h1>${esc(s.title)}</h1>${para(s.body)}${para(s.follow, "body follow")}` },
+};
+
+export const css = ({ colors: k, fonts: f }: Brand): string => `
+*{margin:0;box-sizing:border-box}
+body{background:${k.paper}}
+.slide{width:${W}px;height:${H}px;background:${k.paper};color:${k.ink};font-family:${f.body};
+  padding:80px 84px 64px;display:flex;flex-direction:column;overflow:hidden;position:relative}
+h1{font-family:${f.head};font-weight:700;letter-spacing:-1.5px;line-height:1.02;text-wrap:balance;overflow-wrap:normal}
+.art{display:block;width:100%;aspect-ratio:1;object-fit:cover;border-radius:28px;border:4px solid ${k.ink}}
+.n{font-family:${f.head};font-weight:700;font-size:56px;color:${k.accent};margin-bottom:12px}
+.body{font-size:34px;line-height:1.35;color:${k.muted};margin-top:18px;text-wrap:pretty}
+.foot{margin-top:auto;display:flex;justify-content:space-between;font-size:26px;font-weight:600;color:${k.muted};padding-top:28px}
+.swipe{color:${k.accent}}
+.cover h1{font-size:92px;margin-top:44px}
+.cover .art{width:760px;margin:0 auto}
+.point h1{font-size:76px}
+.point .art{width:800px;margin:44px auto 0}
+.cta{justify-content:center;text-align:center}
+.cta .mark{margin:auto auto 0}
+.cta .art{width:520px;margin:auto auto 0}
+.cta h1{font-size:104px;margin-top:56px}
+.cta .follow{color:${k.ink};font-weight:600;margin-bottom:auto}
+.noart.cover h1{font-size:128px;margin-top:auto}
+.noart.point h1{font-size:104px;margin-top:40px}
+.noart.point .body{font-size:44px;margin-top:36px}
+`;
+
+const foot = (c: Ctx): string =>
+  `<div class="foot"><span>${esc(c.brand.handle)}</span><span>${c.n === 1 ? '<span class="swipe">swipe &rarr;</span>' : `${c.n}/${c.total}`}</span></div>`;
+
+/** One slide's section; an unknown kind renders as a point so a typo never blanks a slide. */
+export const section = (s: Slide, c: Ctx): string => {
+  const kind = KINDS[s.kind] ? s.kind : "point";
+  const body = (KINDS[kind] ?? KINDS["point"])?.render(s, c) ?? "";
+  return `<section class="slide ${kind}${c.src ? "" : " noart"}">${body}${foot(c)}</section>`;
+};
+
+/** The context of every slide: its place in the deck, its point number, its picture. */
+export const contexts = (brand: Brand, slides: readonly Slide[], srcs: readonly (string | undefined)[]): readonly Ctx[] =>
+  slides.map((s, i) => ({
+    brand, n: i + 1, total: slides.length, src: srcs[i],
+    point: slides.slice(0, i + 1).filter((x) => x.kind === "point" || !KINDS[x.kind]).length,
+  }));
+
+export const page = (brand: Brand, body: string, script = ""): string =>
+  `<!doctype html><meta charset="utf-8"><style>${css(brand)}</style><body>${body}${script}</body>`;
+
+/** Runs in the browser after layout: which slides spill out of their frame or lost their picture. */
+export const MEASURE = `<script>addEventListener("load",()=>{const r=[...document.querySelectorAll(".slide")].map((s,i)=>({slide:i+1,
+overflow:s.scrollHeight>s.clientHeight+1||s.scrollWidth>s.clientWidth+1||[...s.querySelectorAll("h1,p")].some(e=>e.scrollWidth>e.clientWidth+1),
+missingArt:[...s.querySelectorAll("img")].some(i=>!i.complete||i.naturalWidth===0)}));
+const p=document.createElement("pre");p.id="fit";p.textContent=JSON.stringify(r);document.body.append(p)})</script>`;

package/adapters/claude/olko-creative/skills/carousel-maker/scripts/domain/schema.ts

@@ -0,0 +1,54 @@
+// brand.json and decks/*.json arrive as unknown JSON; this is the one place they are narrowed.
+import type { Art, Brand, Deck, Json, JsonMap, Result, Slide } from "./types.ts";
+import { fail, ok } from "./types.ts";
+
+export const isMap = (x: unknown): x is JsonMap => typeof x === "object" && x !== null && !Array.isArray(x);
+
+const str = (o: JsonMap, k: string): string | undefined => {
+  const v = o[k];
+  return typeof v === "string" && v.trim() !== "" ? v : undefined;
+};
+const map = (o: JsonMap, k: string): JsonMap => {
+  const v = o[k];
+  return isMap(v) ? v : {};
+};
+
+const HEX = /^#[0-9a-f]{6}$/i;
+export const DEFAULT_COLORS = { paper: "#f4efe3", ink: "#1b1712", accent: "#e0783a", muted: "#6b6257" };
+export const DEFAULT_FONTS = { head: "Georgia, serif", body: '"Helvetica Neue", Helvetica, Arial, sans-serif' };
+
+export function parseBrand(raw: unknown): Result<Brand> {
+  if (!isMap(raw)) return fail("brand.json is not an object");
+  const c = map(raw, "colors");
+  const f = map(raw, "fonts");
+  const colors = {
+    paper: str(c, "paper") ?? DEFAULT_COLORS.paper, ink: str(c, "ink") ?? DEFAULT_COLORS.ink,
+    accent: str(c, "accent") ?? DEFAULT_COLORS.accent, muted: str(c, "muted") ?? DEFAULT_COLORS.muted,
+  };
+  const bad = Object.entries(colors).filter(([, v]) => !HEX.test(v)).map(([k, v]) => `colors.${k} "${v}" is not a #rrggbb colour`);
+  const name = str(raw, "name");
+  const errors = [...(name ? [] : ["brand.json needs a name"]), ...bad];
+  if (errors.length > 0 || !name) return fail(...errors);
+  return ok({ name, handle: str(raw, "handle") ?? "", colors, fonts: { head: str(f, "head") ?? DEFAULT_FONTS.head, body: str(f, "body") ?? DEFAULT_FONTS.body } });
+}
+
+/** A bare word is a library drawing; anything with a slash or an extension is a file. */
+export const artOf = (x: Json | undefined): Art =>
+  typeof x !== "string" || x.trim() === "" ? { kind: "none" } : /[/.]/.test(x) ? { kind: "file", file: x } : { kind: "library", name: x };
+
+const slideOf = (x: Json, i: number): Result<Slide> => {
+  if (!isMap(x)) return fail(`slides[${i}] is not an object`);
+  const title = str(x, "title");
+  if (!title) return fail(`slides[${i}] needs a title`);
+  return ok({ kind: str(x, "kind") ?? "point", title, body: str(x, "body"), follow: str(x, "follow"), art: artOf(x["art"]) });
+};
+
+export function parseDeck(raw: unknown): Result<Deck> {
+  if (!isMap(raw)) return fail("the deck is not an object");
+  const list = raw["slides"];
+  if (!Array.isArray(list) || list.length === 0) return fail("the deck needs a non-empty slides list");
+  const parsed = list.map(slideOf);
+  const errors = parsed.flatMap((r) => (r.ok ? [] : r.errors));
+  const slides = parsed.flatMap((r) => (r.ok ? [r.value] : []));
+  return errors.length > 0 ? fail(...errors) : ok({ title: str(raw, "title") ?? "carousel", caption: str(raw, "caption"), slides });
+}

package/adapters/claude/olko-creative/skills/carousel-maker/scripts/domain/types.ts

@@ -0,0 +1,33 @@
+// The data a carousel is made of. Maps stay open: unknown keys are ignored, never rejected.
+
+export type Json = null | boolean | number | string | readonly Json[] | { readonly [k: string]: Json };
+export type JsonMap = { readonly [k: string]: Json };
+
+export type Brand = {
+  readonly name: string;
+  readonly handle: string;
+  readonly colors: { readonly paper: string; readonly ink: string; readonly accent: string; readonly muted: string };
+  readonly fonts: { readonly head: string; readonly body: string };
+};
+
+/** Where a slide's picture comes from: a drawing in the brand library, a file, or nothing. */
+export type Art = { readonly kind: "none" } | { readonly kind: "library"; readonly name: string } | { readonly kind: "file"; readonly file: string };
+
+export type Slide = {
+  readonly kind: string;
+  readonly title: string;
+  readonly body?: string;
+  readonly follow?: string;
+  readonly art: Art;
+};
+
+export type Deck = {
+  readonly title: string;
+  readonly caption?: string;
+  readonly slides: readonly Slide[];
+};
+
+export type Result<T> = { readonly ok: true; readonly value: T } | { readonly ok: false; readonly errors: readonly string[] };
+
+export const ok = <T>(value: T): Result<T> => ({ ok: true, value });
+export const fail = <T>(...errors: readonly string[]): Result<T> => ({ ok: false, errors });

package/adapters/claude/olko-creative/skills/carousel-maker/scripts/edge/io.ts

@@ -0,0 +1,87 @@
+// Every process, browser and disk write the tool makes, kept out of the domain.
+import { spawnSync, type SpawnSyncOptions } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { H, W } from "../domain/layout.ts";
+import type { Json } from "../domain/types.ts";
+
+export function run(cmd: string, args: readonly string[], opts: SpawnSyncOptions = {}): string {
+  const r = spawnSync(cmd, args, { encoding: "utf8", maxBuffer: 1 << 26, timeout: 120_000, ...opts });
+  if (r.status !== 0) {
+    const out = String(r.stderr || r.stdout || r.error?.message || "");
+    throw new Error(`${path.basename(cmd)} ${args.slice(0, 2).join(" ")}... failed:\n${out.slice(-1500)}`);
+  }
+  return String(r.stdout ?? "");
+}
+
+export const has = (cmd: string): boolean => spawnSync(cmd, ["-version"], { stdio: "ignore" }).status === 0;
+export const readJson = (f: string): unknown => JSON.parse(fs.readFileSync(f, "utf8"));
+export const writeJson = (f: string, v: Json | object): void => fs.writeFileSync(f, JSON.stringify(v, null, 2) + "\n");
+export const mkdir = (...parts: string[]): string => {
+  const d = path.join(...parts);
+  fs.mkdirSync(d, { recursive: true });
+  return d;
+};
+export const writeNew = (f: string, text: string): boolean => {
+  if (fs.existsSync(f)) return false;
+  fs.writeFileSync(f, text);
+  return true;
+};
+
+export type Chrome = { readonly bin: string; readonly shell: boolean };
+
+const SHELL = process.platform === "win32" ? "chrome-headless-shell.exe" : "chrome-headless-shell";
+const SYSTEM: Readonly<Record<string, readonly string[]>> = {
+  darwin: ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Chromium.app/Contents/MacOS/Chromium", "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"],
+  linux: ["/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium", "/usr/bin/chromium-browser"],
+  win32: [
+    `${process.env["PROGRAMFILES"]}\\Google\\Chrome\\Application\\chrome.exe`,
+    `${process.env["PROGRAMFILES(X86)"]}\\Google\\Chrome\\Application\\chrome.exe`,
+    `${process.env["PROGRAMFILES(X86)"]}\\Microsoft\\Edge\\Application\\msedge.exe`,
+  ],
+};
+
+const dirs = (d: string): readonly string[] =>
+  fs.existsSync(d) ? fs.readdirSync(d, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => path.join(d, e.name)) : [];
+
+/** The headless shell shorts-animator's doctor (via HyperFrames) downloads, newest first. */
+const cachedShell = (): string | undefined =>
+  dirs(path.join(os.homedir(), ".cache/hyperframes/chrome/chrome-headless-shell"))
+    .toSorted()
+    .reverse()
+    .flatMap((v) => dirs(v).map((sub) => path.join(sub, SHELL)))
+    .find((f) => fs.existsSync(f));
+
+export function findChrome(): Chrome | undefined {
+  const env = process.env.CHROME;
+  if (env && fs.existsSync(env)) return { bin: env, shell: /headless-shell/.test(env) };
+  const sys = (SYSTEM[process.platform] ?? []).find((c) => fs.existsSync(c));
+  if (sys) return { bin: sys, shell: false };
+  const shell = cachedShell();
+  return shell ? { bin: shell, shell: true } : undefined;
+}
+
+// One short-lived browser per call: no DevTools socket to manage, and a crash costs one slide.
+const flags = (c: Chrome, height: number): readonly string[] => [
+  ...(c.shell ? [] : ["--headless"]), "--disable-gpu", "--hide-scrollbars", "--allow-file-access-from-files",
+  "--force-device-scale-factor=1", "--no-first-run", "--no-default-browser-check", `--window-size=${W},${height}`,
+];
+
+export const url = (file: string): string => pathToFileURL(path.resolve(file)).href;
+
+export const screenshot = (c: Chrome, html: string, png: string): void =>
+  void run(c.bin, [...flags(c, H), `--screenshot=${png}`, url(html)], { stdio: ["ignore", "ignore", "pipe"] });
+
+/** The DOM after load, images and fonts included (the virtual time budget waits for them). */
+export const dumpDom = (c: Chrome, html: string, height: number): string =>
+  run(c.bin, [...flags(c, height), "--virtual-time-budget=5000", "--dump-dom", url(html)]);
+
+export const sheet = (pattern: string, count: number, out: string): boolean => {
+  if (!has("ffmpeg")) return false;
+  const cols = Math.min(count, 5);
+  run("ffmpeg", ["-v", "error", "-y", "-start_number", "1", "-framerate", "1", "-i", pattern,
+    "-vf", `scale=360:-2,tile=${cols}x${Math.ceil(count / cols)}:padding=8:color=white`, "-frames:v", "1", out]);
+  return true;
+};

package/adapters/claude/olko-creative/skills/carousel-maker/scripts/package.json

@@ -0,0 +1,4 @@
+{
+  "private": true,
+  "type": "module"
+}