@olegkoval/agent-skills 1.59.3 → 1.61.0

package/.github/copilot-instructions.md

@@ -60,6 +60,8 @@ Available reusable prompt files:
 - music-to-plex: .github/prompts/music-to-plex.prompt.md
 - vinted-listing: .github/prompts/vinted-listing.prompt.md
 - wikipedia-uk-editor: .github/prompts/wikipedia-uk-editor.prompt.md
+- shorts-animator: .github/prompts/shorts-animator.prompt.md
+- carousel-maker: .github/prompts/carousel-maker.prompt.md
 - cloudflare-block-countries: .github/prompts/cloudflare-block-countries.prompt.md
 - search-console-indexing-audit: .github/prompts/search-console-indexing-audit.prompt.md
 - docs-index-keeper: .github/prompts/docs-index-keeper.prompt.md

package/.github/prompts/carousel-maker.prompt.md

@@ -0,0 +1,102 @@
+<!-- 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."
+---
+
+Use the olko:carousel-maker skill.
+
+# 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/.github/prompts/self-critique.prompt.md

@@ -1,7 +1,7 @@
 <!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
 
 ---
-description: "Adversarially critique your own last answer: spawn a critic agent that verifies claims against live sources, finds the related issue or pattern you missed, then loop until satisfied and report where you were wrong, iterations-to-satisfy, the numeric improvement, and a final score."
+description: "Adversarially critique 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."
 ---
 
 Use the olko:self-critique skill.
@@ -33,40 +33,102 @@ durable rule has bought every answer after it.
 Do not use for trivial one-shot replies or simple chat. The overhead only pays off on load-bearing
 answers.
 
+**Standalone Cursor installation.** Use the generated Cursor adapter or the full skill package,
+including its `scripts/` directory. Copying only `SKILL.md` is insufficient for this workflow,
+which calls the bundled scripts.
+
 ## Procedure
 
-1. **Snapshot the target.** Capture your last substantial answer verbatim, plus the concrete claims
-   it makes and the source each claim rests on. This is `v1`.
+1. **Snapshot the target.** Capture your last substantial answer verbatim and the original task
+   text. This is `v1`.
 
-   Write the claim list before you re-read the answer's prose, and put a real receipt against each
+   Write your claim list before you re-read the answer's prose, and put a real receipt against each
    claim: a quoted field, a `file:line` whose body you actually opened, a command and its output.
-   A claim you cannot receipt at snapshot time is already a finding - mark it `unverified` yourself
+   A claim you cannot receipt at snapshot time is already a finding - mark it `unverifiable` yourself
    rather than waiting for the critic to find it. Grep output, a file name, a path, an endpoint
    string, or the behaviour of a sibling module are not receipts for what code does; they prove
    those things exist, not what they do.
 
-2. **Spawn the critic.** Launch one independent agent with live-source access (issue tracker, code
-   host, error monitor, the repo). Use the prompt template below. The critic must return: `score`
-   (0-100), `verdict` (AGREE / AGREE-WITH-CAVEATS / DISAGREE), `where_wrong` (list), `missed`
-   (related issues or patterns you failed to surface), `unverifiable` (claims it could not confirm),
-   `fixes` (ranked, actionable), and `shapes` (the reusable class of reasoning behind each
-   `where_wrong` item, which Step 5 turns into the rule).
-
-3. **Decide and loop.** Stop if `score >= 90` OR no actionable `fixes` remain. Otherwise revise the
-   answer using the fixes to produce `v2`, then re-spawn the critic to score `v2`. Repeat.
+   Save the list to `.self-critique/author-claims.json` as an array of
+   `{ id, text, load_bearing, receipt }`. Do NOT show it to the critic in round one.
+
+   **Replay pass.** Before spawning the critic, check the answer against every stored rule. Resolve
+   the memory dir as the auto-memory dir for the current project, else the repo's `.claude/memory`;
+   if neither exists, skip replay, evidence-check, and prune with a one-line note. Run
+   `node <skill>/scripts/rule-store.mjs checklist --dir <memory dir>`, then open each listed rule's
+   memory file and read its body before testing the answer against it. The checklist's names and
+   descriptions alone are insufficient. Tag each hit `(recurring)` in the report and record it with
+   `node <skill>/scripts/rule-store.mjs fire <name> --dir <memory dir> --date <today>`.
+   Fire counters and pruning apply only to rules in this memory directory. Rules routed to
+   `CLAUDE.md`, `AGENTS.md`, or the shared store are neither counted nor pruned.
+
+2. **Spawn the critic (blind).** Launch one independent agent with live-source access (issue tracker,
+   code host, error monitor, the repo). Round one input is the original task text and the answer
+   verbatim, nothing else: the critic extracts the claims itself and never sees your list or sources.
+   Use the prompt template below. The critic must return one fenced JSON block with `claims` (its own
+   list, each `{ text, load_bearing, status, checked_by, receipt }`), `missed`, `where_wrong`,
+   `shapes` and `verdict` (AGREE / AGREE-WITH-CAVEATS / DISAGREE). There is no `score` field: the
+   score is computed in Step 2b.
+
+2b. **Merge into the ledger.** Match the critic's claims to yours by meaning and set `origin` on
+   each: `both`, `author` (only you found it), `critic` (only the critic found it). Every critic
+   finding with `checked_by: inferred` must be re-verified by you before it may become `verified`
+   or `refuted`; if you cannot verify it, it stays `inferred`. Both statuses require
+   `checked_by: command` or `checked_by: read` and a non-empty receipt; validation rejects inferred evidence or a missing
+   receipt. Save `.self-critique/ledger-v1.json`, then run
+   `node <skill>/scripts/claim-ledger.mjs score .self-critique/ledger-v1.json` and
+   `node <skill>/scripts/claim-ledger.mjs summary .self-critique/ledger-v1.json` (an invalid ledger
+   exits 2 and prints the errors as JSON).
+   Claims found by only one side are reported under their own heading, "Asymmetric claims".
+
+   Ledger shape (`version` is always `1`):
+
+   ```json
+   { "version": 1,
+     "claims": [{ "id": "c1", "text": "...", "load_bearing": true, "origin": "both",
+                  "status": "verified", "checked_by": "command", "receipt": "quoted output" }],
+     "missed": [{ "id": "m1", "text": "...", "load_bearing": false, "checked_by": "read" }] }
+   ```
+
+   - `origin`: `author` | `critic` | `both`
+   - `status`: `verified` | `refuted` | `unverifiable` | `inferred`
+   - `checked_by`: `command` (run, output quoted) | `read` (file or record opened, quoted) |
+     `inferred` (reasoning only). Required on `missed` items too; an `inferred` missed item is not
+     penalised. A `verified` or `refuted` claim may not use inferred evidence and requires a
+     non-empty receipt.
+
+3. **Decide and loop.** Accept a score of at least 90 only after all fixable findings are resolved
+   or explicitly qualified in the answer and report; otherwise continue the critique loop. Stop
+   when that condition holds, OR no ledger item is left that a revision could fix, OR 3 rounds have run.
+   Otherwise revise the answer to produce `v2`, write `ledger-v2.json`, and run
+   `node <skill>/scripts/claim-ledger.mjs ratchet .self-critique/ledger-v1.json .self-critique/ledger-v2.json`
+   on the previous and new ledger: a lower re-score discards the revision, and you keep the winner. Round
+   two and later hand the critic your receipts for the still-open claims (it is no longer blind).
    **Hard cap: 3 critic rounds.** (A known ceiling: raise it only if a round is still finding real,
    fixable defects.)
 
-4. **Report, always, even after a single round:**
+   **Cost.** The critic runs on a mid-tier model (Sonnet class) by default. Escalate one tier only
+   when a mid-tier round found nothing and the answer is load-bearing. When the budget is tight,
+   verify load-bearing claims first.
+
+4. **Report, always, even after a single round.** In this order:
+   - **Corrected answer (`v_final`)** - restated in full, not as a diff, so the user can act on it
+     without reading anything else. After a single round with no revision, restate `v1` unchanged.
+   - **Claim ledger** - run `node <skill>/scripts/claim-ledger.mjs summary <ledger for v_final>`
+     and `node <skill>/scripts/claim-ledger.mjs score <ledger for v_final>` using the ledger for
+     whichever version the ratchet accepted (for example, `.self-critique/ledger-v2.json`). Report
+     that table and its computed score.
    - **Where you were wrong** - consolidated, each item with the receipt the critic cited.
-   - **Iterations to satisfy** - how many critic rounds it took to reach the stop condition (1 means
-     it was solid on the first pass).
-   - **Improvement in numbers** - the score trajectory, for example `72 -> 88 -> 94 (+22 pts, +31%)`.
-     If only one round ran, state `no revision needed`.
-   - **Final score** - the critic's last score and verdict.
+   - **Asymmetric claims** - claims only you found, and claims only the critic found.
+   - **Recurring rules fired** - each stored rule the replay pass hit, with its new `fires` count.
+   - **Iterations to satisfy** - how many critic rounds it took (1 means it was solid first pass).
+   - **Score trajectory** - for example `72 -> 88 -> 94 (+22 pts)`, all computed scores. If only one
+     round ran, state `no revision needed`.
    - **Unverifiable** - anything you should not present as fact.
-   - **Declined fixes** - any ranked fix you chose not to take, and the reason. Silently dropping a
-     fix looks identical to missing it.
+   - **Declined findings** - ledger items you chose not to fix, with the reason. Silently dropping
+     one looks identical to missing it.
+   - **Rules written** - where each rule went and what it says (see Step 5).
+   - **Rules proposed for deletion** - the candidates from the prune pass, or `none`.
 
 5. **Convert the outcome into a durable rule.** See below. Skipping this step is what makes the
    same critique necessary again next week.
@@ -117,31 +179,50 @@ Before writing to shared persistence, redact the incident evidence, including wh
 `context-repo` or `shared-knowledge-artifact`, while still including the incident and its dated
 receipt. This redaction requirement does not apply to local agent memory or repository-rule writes.
 
-**Dedupe before writing.** Read the store first. If a rule of the same shape exists, sharpen it and
-add this incident as further evidence rather than creating a second entry. Link related rules
-instead of restating them.
+**Dedupe before writing.** Read the store first. If a rule of the same shape exists, add one dated
+evidence line to it instead of creating a second entry, with at most three evidence lines per rule.
+A fourth incident means the rule named the incident, not the shape: rewrite the rule text and keep
+the three most recent evidence lines. Link related rules instead of restating them. Only when the
+memory directory resolved in Step 1 exists, run
+`node <skill>/scripts/rule-store.mjs evidence-check --dir <memory dir>` before writing and report
+any rule it flags. Skip this command when neither supported memory directory exists.
+
+**Memory rule identity and counters.** Mark each rule stored by this workflow with
+`rule_store: self-critique` under `metadata:` in its memory file's frontmatter. Mark an existing
+rule only after reading it and confirming it belongs to this workflow. Only marked rules are
+pruning candidates; unrelated project and user memories are excluded. A memory rule's `fires` and
+`last_fired` live under `metadata:` and are written only by `fire`. Rules routed to `CLAUDE.md`,
+`AGENTS.md`, or the shared store are neither counted nor pruned.
+
+**Prune pass.** At the end of this step, only when a valid memory directory is available, run
+`node <skill>/scripts/rule-store.mjs prune --dir <memory dir> --idle-days 60`. List the candidates
+in the report under "Rules proposed for deletion". Skip this command when neither supported memory
+directory exists. Never delete a rule without the user's reply.
 
 **Then close the loop.** State in your report where the rule was written and what it says, so the
 user can veto it. A rule the user has not seen is a rule they cannot correct.
 
 ## Critic prompt template
 
-Pass this to the critic agent, filling in the two placeholders. It is deliberately adversarial:
+Pass this to the critic agent, filling in the two placeholders (`{{TASK}}`, `{{ANSWER}}`). It is deliberately adversarial:
 the default stance is that the answer is wrong until a live source proves otherwise.
 
 > You are an adversarial reviewer. Your job is to verify and, where possible, **refute** the answer
 > below. Default to skepticism: assume a claim is wrong until a live source proves it. Address every
 > comment **directly to the author** ("You claimed X; the source says Y").
 >
+> **The task the author was given (verbatim):**
+> {{TASK}}
+>
 > **The answer under review (verbatim):**
 > {{ANSWER}}
 >
-> **Its claims and the source each rests on:**
-> {{CLAIMS_AND_SOURCES}}
+> You are not given the author's claims or sources. Extract the claims yourself.
 >
 > **Do this:**
-> 1. Re-verify every claim against the **live** source (issue tracker / code host / error monitor /
->    the repo) - never trust the answer's own summary. Quote the field, line, PR body, or issue you
+> 1. List every claim the answer makes, marking each `load_bearing` (the user would act on it).
+>    Re-verify each against the **live** source (issue tracker / code host / error monitor / the
+>    repo) - never trust the answer's own summary. Quote the field, line, PR body, or issue you
 >    checked.
 > 2. **Check similar and related issues, and find patterns.** Is this part of a cluster? Is there a
 >    closer sibling, parent epic, or duplicate the answer should have surfaced but did not? Name it
@@ -151,19 +232,62 @@ the default stance is that the answer is wrong until a live source proves otherw
 >    a proven root cause?
 > 4. List exactly **where the author was wrong or imprecise**, and what they **missed**.
 > 5. Flag any claim you **could not verify** so it is not presented as fact.
+> 6. Label every finding with `checked_by`: `command` (you ran it and quote the output), `read` (you
+>    opened the file or record and quote it), `inferred` (reasoning only).
 >
-> **Output, terse, with a receipt for every line:**
-> - `verdict`: AGREE | AGREE-WITH-CAVEATS | DISAGREE
-> - `score`: 0-100 (rubric: 100 = every claim verified, nothing missed, confidence correctly
->   calibrated; subtract for each unverified claim, each missed sibling or pattern, and each
->   over- or under-statement)
-> - `where_wrong`: bullet list, each with its source receipt
-> - `missed`: related issues or patterns the author failed to surface, with IDs
-> - `unverifiable`: claims that need a source you do not have
-> - `fixes`: ranked, actionable - what to change to raise the score
+> **Output, terse, one fenced JSON block, a receipt for every item:**
+> - `claims`: your own list, each `{ text, load_bearing, status, checked_by, receipt }` with `status`
+>   one of `verified` | `refuted` | `unverifiable` | `inferred`
+> - `missed`: related issues or patterns the author failed to surface, each
+>   `{ text, load_bearing, checked_by, receipt }`, with IDs
+> - `where_wrong`: bullet list, each with its source receipt and `checked_by`
 > - `shapes`: for each item in `where_wrong`, the class of reasoning that produced it, stated so it
 >   would apply to a different task ("a conclusion drawn from evidence that does not cover the
 >   claim"), not the incident itself. Say `one-off` when the error has no reusable shape.
+> - `verdict`: AGREE | AGREE-WITH-CAVEATS | DISAGREE
+>
+> Do not output a score. It is computed from your claims.
+
+### Score anchors
+
+The score is `100` minus penalties, floored at 0. Calibrate against these three ledgers (all claims
+`origin: both`; `node <skill>/scripts/claim-ledger.mjs anchors` prints them as JSON).
+
+**Strong, score 95**
+
+| id | load_bearing | status | checked_by |
+| --- | --- | --- | --- |
+| a1 | no | inferred | inferred |
+
+**Middling, score 72**
+
+| id | load_bearing | status | checked_by |
+| --- | --- | --- | --- |
+| b1 | no | refuted | read |
+| b2 | no | refuted | read |
+| b3 | no | unverifiable | read |
+| b4 | no | unverifiable | read |
+
+**Weak, score 40**
+
+| id | load_bearing | status | checked_by |
+| --- | --- | --- | --- |
+| c1 | yes | refuted | read |
+| c2 | yes | refuted | read |
+| c3 | yes | unverifiable | read |
+
+Penalties:
+
+| Finding | Points off |
+| --- | --- |
+| refuted, load-bearing | 25 |
+| refuted | 10 |
+| unverifiable, load-bearing | 10 |
+| unverifiable | 4 |
+| inferred, accepted | 5 |
+| missed, load-bearing | 15 |
+| missed | 5 |
+| verified but found only by the critic | 5 |
 
 ## Optional: auto-offer via a Claude Code Stop hook
 
@@ -209,10 +333,10 @@ message.
   `iterations: 1, no revision needed` and the single score rather than forcing a revision.
 - Diversity beats redundancy: if a claim can fail in more than one way, give the critic distinct
   lenses (correctness, completeness, does-it-reproduce) instead of repeating the same check.
-- The critic verifies against live sources; it does not rewrite the answer. You revise; it re-scores.
-- Re-score by messaging the same critic rather than spawning a fresh one, and hand it the receipts
-  for whatever it could not verify in the earlier round, so round two spends its budget on the
-  claims still standing instead of re-deriving the ones already settled.
+- The critic verifies against live sources; it does not rewrite the answer or score it. You revise;
+  the score is recomputed from the ledger.
+- In round two, hand the critic your receipts for the claims still open, so it spends its budget on
+  the claims still standing instead of re-deriving the ones already settled.
 - A critic finding you disagree with is worth one challenge. Put the reasoning to it and let it rule;
   if it concedes, that is a real answer for the report, and the reasoning is what the user needs to
   see either way.

package/.github/prompts/shorts-animator.prompt.md

@@ -0,0 +1,103 @@
+<!-- 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."
+---
+
+Use the olko:shorts-animator skill.
+
+# 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/.kiro/steering/carousel-maker.md

@@ -0,0 +1,101 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+inclusion: manual
+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>/` |