@olegkoval/agent-skills 1.59.3 → 1.61.0

package/.kiro/steering/shorts-animator.md

@@ -0,0 +1,102 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+inclusion: manual
+description: "Make narrated, painted animated shorts (TikTok, Reels, YouTube Shorts) from a script and a look described in words: scenes drawn in code, GPU-painted, voiced locally, captioned and scored into an MP4."
+---
+
+# Shorts Animator
+
+A script and a look in, an animated short out. You write the lines and draw every shot as canvas code; the
+tool paints it on the GPU on twos, narrates it with a local Kokoro voice, captions it, scores it and
+encodes the MP4. Nothing is filmed, generated by an image model, or licensed.
+
+`SA` = `node <this skill's folder>/scripts/sa.ts`. Write the full command each time. One folder per short:
+`WORK=./<slug>-short`. First run on a machine: `SA doctor` (checks Node, ffmpeg, Chrome, sets up the voice,
+renders a 3-second test).
+
+## 1. Decide, do not interrogate
+
+Decide the lines, shots, look, voice and music yourself. Ask one question only if the subject is unclear.
+A pasted script is used word for word. A topic: write it per `references/writing.md`.
+
+| they say | look |
+|---|---|
+| oil, painterly, Van Gogh, swirly, "like the faith shorts" | `oil` |
+| watercolour, soft, dreamy, children's book | `watercolor` |
+| crayon, pastel, chalk, for kids | `pastel` |
+| ink, comic, graphic novel, line art | `ink` |
+| flat, storybook, gouache, poster, calm | `gouache` |
+
+Custom look: `"look": { "base": "oil", "brush": 16, "palette": {...} }`. Read `references/looks.md` only
+when overriding numbers. Voice `bm_george` (default, scripture and quotes), `am_michael`, `bf_emma`
+(stories), `af_heart` (kids); `speed` 0.85 to 0.95 reads calm. Their recording: `"voice": { "file":
+"assets/voice.m4a" }` with `say` lines matching it in order. `"voice": "none"` for music only. Music
+`mood`: `tender`, `hopeful`, `night`, `wonder`, `playful`, `none`, or a track path. `SA looks` lists all.
+
+## 2. Write the plan and the drawings
+
+```bash
+SA new "$WORK" --look oil      # short.json + scenes.js + assets/
+```
+
+`short.json` lines: `{ "say": "...", "scene": "meadow" | ["a", "b"], "move": "push", "hold": 0.8 }`.
+- A list of scenes cuts on the caption chunks. Cut often: a new picture every 1.5 to 3 s.
+- `move`: push, pull, pan-left, pan-right, rise, fall, drift, still. `transition`: cut, fade, dip (rarely).
+- `caption` shows different words; `/` forces a break. `captions.style`: box, plain, none.
+- `format`: 9:16 (default), 16:9, 1:1, 4:5. `twos`: 2 (hand-drawn), 1 (smooth).
+
+`scenes.js`: `window.SCENES = { "meadow": (k) => { k.sky({...}); k.person({...}); } }`. Read
+`references/kit.md` before writing scenes. Draw like a painter:
+- Big simple shapes, strong value contrast, one subject. The paint pass adds texture; draw nothing fussy.
+- Keep faces out of the caption band (about 77% down).
+- Every shot different: place, scale, day and night, warm and cool. Match the words.
+- Small motion: `pose: "walk"`, `dx`, rain, glints. `k.t` seconds, `k.p` progress 0 to 1.
+- No helper for it (a boat, an animal)? Write a small function with `k.g`, flat shapes in the palette.
+
+## 3. Check, then look (budgeted)
+
+```bash
+SA check "$WORK"     # no browser, about a second: missing scenes, throwing scenes, unknown kit calls,
+                     # figures under the captions, line and total length
+SA frames "$WORK"    # narrates (cached), one painted frame per shot -> frames/sheet.jpg
+SA still "$WORK" 7   # one shot full size, only when the sheet shows a problem you cannot place
+```
+
+Fix every `ERROR` from `check` before spending a browser run. Then read `frames/sheet.jpg` once. Fix muddy
+or empty shots, a figure lost in its background (contrast, `rim`), look-alike shots, a red "no scene"
+frame, and every `⚠ the page said` line. **Budget: at most two frames rounds before the first render.**
+Images are the expensive part of this loop; do not reopen a sheet you have already judged.
+
+## 4. Render and deliver
+
+```bash
+SA render "$WORK"    # about a minute for 40 s -> <title>.mp4, renders/vN.mp4 (+ its short.json), qa/sheet.jpg
+```
+
+Read `qa/sheet.jpg` only if the render printed a warning or they report a problem. Tell them in two
+lines what it is (look, length, shots) and: "Tell me what to change, one sentence is enough."
+
+## 5. One-sentence changes
+
+Smallest change, `SA check`, render, show. `SA set "$WORK" voice.speed=0.85 music.mood=night` edits
+short.json (JSON values; plain text otherwise) and refuses an invalid result.
+
+| they say | change |
+|---|---|
+| more painterly, softer | `look` or its numbers (brush, swirl, wash) |
+| slower, faster | `voice.speed`, `pause` |
+| a woman's voice, American | `voice.id` |
+| no music, more emotional | `music.mood` |
+| bigger captions, no box | `captions.size` 52, `captions.style` plain |
+| for YouTube | `format` 16:9, redraw shots whose layout breaks |
+| change shot 4 | that scene function only |
+
+## When something goes wrong
+
+| symptom | fix |
+|---|---|
+| no Chrome | install Chrome, or `SA doctor` fetches a headless one |
+| "painting on the CPU" | works, about 10x slower |
+| narrator setup fails | needs Python 3.10+ or `uv`; or use `"voice": "none"` or their recording |
+| voice timing off with their recording | `say` lines must match its words, in order |

package/.windsurf/rules/carousel-maker.md

@@ -0,0 +1,100 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Make Instagram or LinkedIn carousel slides from a topic or pasted copy: a brand template sets the text, and a reusable library of hand-drawn illustrations, drawn once in code per brand, supplies the pictures."
+---
+
+# 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/.windsurf/rules/shorts-animator.md

@@ -0,0 +1,101 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Make narrated, painted animated shorts (TikTok, Reels, YouTube Shorts) from a script and a look described in words: scenes drawn in code, GPU-painted, voiced locally, captioned and scored into an MP4."
+---
+
+# Shorts Animator
+
+A script and a look in, an animated short out. You write the lines and draw every shot as canvas code; the
+tool paints it on the GPU on twos, narrates it with a local Kokoro voice, captions it, scores it and
+encodes the MP4. Nothing is filmed, generated by an image model, or licensed.
+
+`SA` = `node <this skill's folder>/scripts/sa.ts`. Write the full command each time. One folder per short:
+`WORK=./<slug>-short`. First run on a machine: `SA doctor` (checks Node, ffmpeg, Chrome, sets up the voice,
+renders a 3-second test).
+
+## 1. Decide, do not interrogate
+
+Decide the lines, shots, look, voice and music yourself. Ask one question only if the subject is unclear.
+A pasted script is used word for word. A topic: write it per `references/writing.md`.
+
+| they say | look |
+|---|---|
+| oil, painterly, Van Gogh, swirly, "like the faith shorts" | `oil` |
+| watercolour, soft, dreamy, children's book | `watercolor` |
+| crayon, pastel, chalk, for kids | `pastel` |
+| ink, comic, graphic novel, line art | `ink` |
+| flat, storybook, gouache, poster, calm | `gouache` |
+
+Custom look: `"look": { "base": "oil", "brush": 16, "palette": {...} }`. Read `references/looks.md` only
+when overriding numbers. Voice `bm_george` (default, scripture and quotes), `am_michael`, `bf_emma`
+(stories), `af_heart` (kids); `speed` 0.85 to 0.95 reads calm. Their recording: `"voice": { "file":
+"assets/voice.m4a" }` with `say` lines matching it in order. `"voice": "none"` for music only. Music
+`mood`: `tender`, `hopeful`, `night`, `wonder`, `playful`, `none`, or a track path. `SA looks` lists all.
+
+## 2. Write the plan and the drawings
+
+```bash
+SA new "$WORK" --look oil      # short.json + scenes.js + assets/
+```
+
+`short.json` lines: `{ "say": "...", "scene": "meadow" | ["a", "b"], "move": "push", "hold": 0.8 }`.
+- A list of scenes cuts on the caption chunks. Cut often: a new picture every 1.5 to 3 s.
+- `move`: push, pull, pan-left, pan-right, rise, fall, drift, still. `transition`: cut, fade, dip (rarely).
+- `caption` shows different words; `/` forces a break. `captions.style`: box, plain, none.
+- `format`: 9:16 (default), 16:9, 1:1, 4:5. `twos`: 2 (hand-drawn), 1 (smooth).
+
+`scenes.js`: `window.SCENES = { "meadow": (k) => { k.sky({...}); k.person({...}); } }`. Read
+`references/kit.md` before writing scenes. Draw like a painter:
+- Big simple shapes, strong value contrast, one subject. The paint pass adds texture; draw nothing fussy.
+- Keep faces out of the caption band (about 77% down).
+- Every shot different: place, scale, day and night, warm and cool. Match the words.
+- Small motion: `pose: "walk"`, `dx`, rain, glints. `k.t` seconds, `k.p` progress 0 to 1.
+- No helper for it (a boat, an animal)? Write a small function with `k.g`, flat shapes in the palette.
+
+## 3. Check, then look (budgeted)
+
+```bash
+SA check "$WORK"     # no browser, about a second: missing scenes, throwing scenes, unknown kit calls,
+                     # figures under the captions, line and total length
+SA frames "$WORK"    # narrates (cached), one painted frame per shot -> frames/sheet.jpg
+SA still "$WORK" 7   # one shot full size, only when the sheet shows a problem you cannot place
+```
+
+Fix every `ERROR` from `check` before spending a browser run. Then read `frames/sheet.jpg` once. Fix muddy
+or empty shots, a figure lost in its background (contrast, `rim`), look-alike shots, a red "no scene"
+frame, and every `⚠ the page said` line. **Budget: at most two frames rounds before the first render.**
+Images are the expensive part of this loop; do not reopen a sheet you have already judged.
+
+## 4. Render and deliver
+
+```bash
+SA render "$WORK"    # about a minute for 40 s -> <title>.mp4, renders/vN.mp4 (+ its short.json), qa/sheet.jpg
+```
+
+Read `qa/sheet.jpg` only if the render printed a warning or they report a problem. Tell them in two
+lines what it is (look, length, shots) and: "Tell me what to change, one sentence is enough."
+
+## 5. One-sentence changes
+
+Smallest change, `SA check`, render, show. `SA set "$WORK" voice.speed=0.85 music.mood=night` edits
+short.json (JSON values; plain text otherwise) and refuses an invalid result.
+
+| they say | change |
+|---|---|
+| more painterly, softer | `look` or its numbers (brush, swirl, wash) |
+| slower, faster | `voice.speed`, `pause` |
+| a woman's voice, American | `voice.id` |
+| no music, more emotional | `music.mood` |
+| bigger captions, no box | `captions.size` 52, `captions.style` plain |
+| for YouTube | `format` 16:9, redraw shots whose layout breaks |
+| change shot 4 | that scene function only |
+
+## When something goes wrong
+
+| symptom | fix |
+|---|---|
+| no Chrome | install Chrome, or `SA doctor` fetches a headless one |
+| "painting on the CPU" | works, about 10x slower |
+| narrator setup fails | needs Python 3.10+ or `uv`; or use `"voice": "none"` or their recording |
+| voice timing off with their recording | `say` lines must match its words, in order |

package/README.md

@@ -3,7 +3,7 @@
   <p><strong>Agent-agnostic skill catalog for Codex, Claude, Cursor, Grok, Copilot, Windsurf, Kiro, Hermes Agent, and other skill-aware tools.</strong></p>
   <p>
     <img src="https://img.shields.io/badge/license-MIT-16a34a" alt="MIT license">
-    <img src="https://img.shields.io/badge/skills-56-2563eb" alt="56 skills">
+    <img src="https://img.shields.io/badge/skills-59-2563eb" alt="59 skills">
     <img src="https://img.shields.io/badge/platforms-Codex%20%7C%20Claude%20%7C%20Cursor%20%7C%20Grok%20%7C%20Copilot%20%7C%20Windsurf%20%7C%20Kiro%20%7C%20Hermes-111827" alt="Codex Claude Cursor Grok Copilot Windsurf Kiro Hermes">
     <img src="https://img.shields.io/badge/status-public%20catalog-16a34a" alt="Public catalog">
   </p>
@@ -300,7 +300,7 @@ Look back and improve: self-critique, retrospectives, performance review, rapid
 
 | Skill | What it does | Use when |
 |-------|-------------|----------|
-| [self-critique](plugins/olko-reflection/skills/self-critique/SKILL.md) | Adversarially critiques your own last answer: spawns a critic agent that verifies claims against live sources, then loops until satisfied and reports where you were wrong | Checking a substantial answer before the user has to |
+| [self-critique](plugins/olko-reflection/skills/self-critique/SKILL.md) | Adversarially critiques your own last answer: a blind critic agent re-derives and verifies every claim against live sources, the score is computed from a labelled claim ledger, you revise under a ratchet, restate the corrected answer, and turn each caught error into a durable rule with a fire counter | Checking a substantial answer before the user has to |
 | [review-past-performance](plugins/olko-reflection/skills/review-past-performance/SKILL.md) | Pulls 24h of ICM memories, git history, and skill analytics; detects repeated mistakes and slow workflows; proposes 1-3 concrete fixes | Daily self-improvement loop or codifying a repeated workflow |
 | [retro-analysis](plugins/olko-reflection/skills/retro-analysis/SKILL.md) | Produces repository, comparison, and cross-project retrospectives from delivery, code-quality, work-pattern, and trend evidence | The user asks for a retro over shipped work ("run a retrospective", "how did this quarter go", "what did we ship") or a scheduled retro job fires; for agent-operations retros use agent-ops-retro, for a single finished change use wrap-up |
 | [agent-ops-retro](plugins/olko-reflection/skills/agent-ops-retro/SKILL.md) | Retrospective on how the agents themselves are being operated: mines local transcripts and reads the reports other jobs already produce to surface what the human keeps repeating, what the guardrails caught, and where delivery leaked, carrying unactioned findings forward | Checking agent usage, delegation cost, or repeating corrections across sessions rather than shipped code |
@@ -334,7 +334,7 @@ Build, test and publish Garmin Connect IQ watch faces.
 |-------|-------------|----------|
 | [garmin-watchface](plugins/olko-garmin-kit/skills/garmin-watchface/SKILL.md) | Designs, builds, tests, screenshots, and publishes Garmin Connect IQ watch faces in Monkey C | Working on a Connect IQ watch face, SVG design proposals, inspiration gathering, layout that clips or overlaps, simulator screenshots, app settings, device support, or store submission |
 
-### olko-creative (5)
+### olko-creative (7)
 
 Creative and personal projects: photo galleries, music players, Plex ingest, listings, wiki editing.
 
@@ -345,6 +345,8 @@ Creative and personal projects: photo galleries, music players, Plex ingest, lis
 | [music-to-plex](plugins/olko-creative/skills/music-to-plex/SKILL.md) | Acquires albums, DJ crates, and YouTube playlists for Plex/Plexamp with verified NAS delivery, Plex visibility, and source-backed Obsidian radio notes | Adding or downloading music to Plex/Plexamp, including an album request, DJ crate, or YouTube playlist |
 | [vinted-listing](plugins/olko-creative/skills/vinted-listing/SKILL.md) | Creates and safely publishes Vinted listings from verified item details and the seller's original photos, with automatic suggestions, duplicate checks, draft verification, and publish confirmation | Listing, selling, relisting, or pricing an item on Vinted, or editing and publishing an existing draft |
 | [wikipedia-uk-editor](plugins/olko-creative/skills/wikipedia-uk-editor/SKILL.md) | Drafts policy-compliant Ukrainian Wikipedia edits, en→uk translation, stub expansion, sourcing, backlog cleanup, returning ready-to-paste wikitext, an edit summary, and a verified source list | Editing, translating, or sourcing a uk.wikipedia.org article, or planning what to contribute next |
+| [shorts-animator](plugins/olko-creative/skills/shorts-animator/SKILL.md) | Makes narrated, painted animated shorts from a script and a look in words: scenes drawn in code, GPU-painted on twos, voiced locally, captioned and scored into an MP4 | Making a TikTok, Reels or YouTube Shorts animation, a painted quote or verse video, or any faceless short that should look drawn |
+| [carousel-maker](plugins/olko-creative/skills/carousel-maker/SKILL.md) | Makes Instagram or LinkedIn carousel slides from a topic or pasted copy: a brand template sets the text, a library of code-drawn illustrations made once per brand supplies the pictures, and every slide is measured for overflow before export | Making a carousel post, a swipeable slide series, or a set of on-brand social slides without image models |
 
 ### olko-web-ops (4)
 

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>/` |