@cliangdev/conductor 0.25.0 → 0.27.0

package/assets/claude/skills/conductor-content-studio/references/publish-pack-template.md

@@ -0,0 +1,121 @@
+# Publish pack
+
+Two files in the run folder, written by the orchestrator in stage S5b from the scriptwriter's
+`## Publish copy` section in `script.md`, the art director's `## Publish assets` section in
+`direction.md`, and the compliance results (`compliance-checklist.md`). The pack is what the
+publisher uses later to pre-fill the Post, so it holds only what the Post needs. A run never
+creates a Post.
+
+Short-form craft this encodes: the search keyword sits in the caption's opening words, on-screen
+text and speech (TikTok search reads all three); a hook swap is the standard creative iteration;
+hook rate is 3-second plays over impressions and hold rate is completions over 3-second plays;
+posts work with the sound off.
+
+## Hook types
+
+Tag every hook, in ideas and in the pack, with one of: `question`, `bold-claim`,
+`pattern-interrupt`, `relatable-pain`, `how-to`, `number`, `curiosity-gap`, `story`,
+`social-proof`. Use another short kebab-case word only when none fits.
+
+## publish-pack.md (for people)
+
+One section per platform the brief asks for. Omit a platform it does not.
+
+```
+# Publish pack: <title>
+
+Run: <runId>   Creative: <display id, or "not yet committed">   Tags: hook <type>, angle <angle>, format <format>
+
+## <Platform> (<feed | reel | story>, as the destination's formats allow)
+- **Caption:** <final text; the search keyword is in the first line, within the first ~125
+  characters; within the platform's limit>
+- **Hashtags:** <3 to 5>
+- **First comment (post manually):** <text, or "none">. Conductor cannot post comments.
+- **Cover frame:** <video: timestamp in seconds and what is on it; carousel: card 1; still: n/a>
+- **Alt text:** <one line per image or card, in order>
+- **On-screen text placement:** <where each line sits, inside the safe zone>
+- **Sound:** <source and licence: original audio | Commercial Music Library track "<name>" |
+  library track id and its licence | clip's own sound | none>
+- **Posting window:** <best hour and weekday from get_marketing_insights byHour/byWeekday for this
+  platform, with the window it came from, or "no data yet">
+- **Options:** <the option keys and values this platform gets, from publish-pack.json>
+
+## Alternate hooks (for variantOf hook experiments)
+1. <hook line> (<hookType>)
+2. <hook line> (<hookType>)
+3. <optional>
+
+## Compliance
+<the table from compliance-checklist.md: check, answer, what was done, option set>
+
+## Third-party assets
+| Asset | Whose | Permission or licence |
+|---|---|---|
+| <music, footage, logo, meme, likeness, trademark, parody> | ... | ... |
+(Write "none" if the post uses only the brand's own and generated-by-Conductor material.)
+```
+
+## publish-pack.json (for the publisher)
+
+```json
+{
+  "creativeId": null,
+  "platforms": [
+    {
+      "platform": "tiktok",
+      "format": "feed",
+      "captionOverride": "<final caption>",
+      "options": { "brandOrganicToggle": true, "isAigc": false, "videoCoverTimestampMs": 1500 }
+    },
+    {
+      "platform": "instagram",
+      "format": "feed",
+      "captionOverride": "<final caption>",
+      "options": { "altText": "<alt text for a single feed image>" }
+    }
+  ],
+  "altText": ["<card 1 alt text>", "<card 2 alt text>"],
+  "alternateHooks": [{ "hook": "<line>", "hookType": "question" }],
+  "tags": { "hookType": "bold-claim", "angle": "utility-education", "format": "carousel" }
+}
+```
+
+Rules:
+
+- `creativeId` is null until the person approves the commit (S6, On Approve), then it is the
+  Creative's id. A `FILM` run leaves it null: the publisher is pointed at the pack by the person.
+- `platforms[]` items are shaped to drop straight into `create_post` targets or
+  `set_publish_targets` targets: `platform`, `format` (`feed`, `reel` or `story`, and only one the destination's `formats` offers: at the time
+  of writing TikTok and YouTube are feed only, Facebook and Instagram offer all three),
+  `captionOverride`, and `options`. Name `options` `publishOptions` for `set_publish_targets`. They
+  carry no account: the publisher resolves the account (`account` or `connectionId`) from
+  `list_publish_targets`. `captionOverride` is ignored on a story.
+- `captionOverride` is the **complete text that gets posted**: the caption, then a blank line, then that
+  platform's hashtags. The publisher posts it as-is, so hashtags listed only in `publish-pack.md` never
+  reach the platform. The first comment is the one thing that stays out: it is posted by hand.
+- `options` holds real option keys only, in the camelCase the destination reports under
+  `optionKeys`. Never add a key that is not in this table, and never `privacyLevel` (the person
+  picks it from the account's allowed levels at publish time):
+
+  | Platform | Keys the pack may set | Applies to |
+  |---|---|---|
+  | TikTok | `brandContentToggle`, `brandOrganicToggle` | video and photo posts |
+  | TikTok | `isAigc` | video posts only |
+  | TikTok | `videoCoverTimestampMs` (milliseconds, from the cover frame) | video posts only |
+  | TikTok | `disableComment` | video and photo posts |
+  | TikTok | `disableDuet`, `disableStitch` | video posts only |
+  | Instagram | `altText` (at most 1000 characters) | a single feed image only |
+  | Instagram | `audioName`, `shareToFeed`, `collaborators` (at most 3, not on a carousel) | reels only |
+  | YouTube | `containsSyntheticMedia` | video |
+
+  Set only what the compliance check or the plan decided: leave a key out rather than writing a
+  default. Keys that need a Post's own asset id (`coverAssetId`, `thumbnailAssetId`,
+  `photoCoverIndex`) are not known until media is attached to a Post, so the pack does not carry
+  them; the cover frame is in `publish-pack.md` for the publisher to act on.
+- `altText` is one string per image or card, in order. It is also the source for the Creative's
+  own `altText` field.
+- `alternateHooks` and `tags` are for learning and experiments, not for publishing. `tags` is also
+  copied into `run.json`.
+- `tags.angle` is the ideator's angle: `story-emotion`, `utility-education` or `trend-humor`.
+  `tags.format` is the idea's format (`still`, `carousel`, `story`, `motion`, `clip` or `film`).
+- Valid JSON, no comments.

package/assets/claude/skills/conductor-content-studio/references/rubric.md

@@ -0,0 +1,99 @@
+# Judging rubric
+
+Used by the `conductor-content-creative-director` agent in `text-round` and `visual-round`, and by
+the orchestrator when it needs to break a tie. Everything here exists to counter a known judge
+failure mode, so follow it as written.
+
+## Why it is shaped this way
+
+- LLM judges favour longer answers, the first-listed answer and the answer written in their own
+  style (Zheng et al. 2023, MT-Bench). So ideas arrive at the same length, under shuffled neutral
+  IDs, and finalists are compared in both orders.
+- A judge that scores before it reasons anchors on its first impression, and a judge asked to
+  confirm a leader mostly confirms it (Verga et al. 2024 on panels of different models). So:
+  reasoning is written first, the judge is a different model tier from the ideators, and a
+  devil's-advocate pass runs against the leader.
+- Ideas generated by one assisted process converge on the same few mechanics (Doshi & Hauser 2024),
+  and a model asked to debate itself repeats its first stance (Liang et al., degeneration of
+  thought). So novelty is scored explicitly, and the leader must be argued against.
+
+## Criteria and weights
+
+Score each 1 to 5. Weighted total = sum(score x weight) / 5, so the maximum is 100.
+
+| Criterion | Weight | 1 | 3 | 5 |
+|---|---|---|---|---|
+| Hook strength | 25 | Opens on a greeting, a logo or context; nothing makes a stranger stay | A clear promise or question, but generic; could open any account's post | A specific, surprising or tension-filled claim a stranger understands in 1s, spoken and on screen |
+| Audience relevance | 20 | Aimed at "everyone"; ignores the brief's tension | Names the audience's topic but not their actual friction | Opens on a friction the brief names and the audience would recognise as theirs |
+| Brand fit | 15 | Breaks a copy rule or approved-line, or reads off-voice | Within the rules but could be any brand | Uses an approved line or the knowledge page's voice naturally; no rule risk |
+| Feasibility with assets on hand | 15 | Needs assets that do not exist and cannot be made here (and is tagged `RENDER`) | Needs one new photo or clip the user can supply easily | Fully buildable from `media.json` or a render with no photo; or an honest `FILM` with a simple shoot |
+| Novelty | 15 | The mechanic is the most common one for this topic (listicle, "5 tips", before/after) | A familiar mechanic with a fresh angle | A mechanic not seen elsewhere in the pool or in the performance data, still easy to grasp |
+| Shareability | 10 | Nothing to send to a friend; purely informational | Useful or pleasant, but no reason to send | A person would send it to a named other person ("this is you") or save it for later |
+
+## Scoring protocol
+
+1. Read `brief.md`, then every idea in `ideas/pool.md`. Ideas are identified by ID only; ignore the
+   order they appear in and any difference in polish.
+2. For each idea, per criterion, write one or two sentences of reasoning FIRST, citing the idea's
+   own words. Then write the score. Never write a score before its reasoning.
+3. Penalise nothing for length (ideas are length-matched) and reward nothing for confident tone.
+4. Compute the weighted total. Shortlist the top 3. If ties, apply the tie-break rule below.
+5. Any idea that breaks a copy rule or contradicts an approved line is capped at 2 on brand fit
+   and cannot be a finalist unless the fix is a one-word edit you state.
+
+## Pairwise protocol (visual round)
+
+For each pair of finalists (A,B), (A,C), (B,C):
+
+1. Judge the pair twice, once with each order, as two independent comparisons. Write reasoning
+   first, then the verdict "first" or "second", then say which idea won.
+2. If the two orders name different winners (position flipped the result), the pair is a tie.
+3. Tally wins: win = 1, tie = 0.5 each. The leader has the most points.
+
+## Judging a rendered draft
+
+Look at the actual image file, not the text description. Check:
+
+- Readability at phone size: shrink it mentally to a thumbnail. Can the headline be read in a glance?
+- Hook legibility in 1 second: is the first thing seen the hook, in high contrast?
+- Safe zones: text out of the platform UI (see `platform-specs.md`), nothing sitting on a face.
+- Brand look: tokens, font, logo lockup, accent phrase on the words that carry the meaning.
+- Whether the picture and the words do different jobs (photo shows, words claim) rather than
+  repeating each other.
+
+A finalist that could not be rendered keeps its text-round score; say so, and do not treat the
+missing image as a defect of the idea, except when the failure came from copy the validator refused.
+A `FILM` finalist has no image: judge its script and shot description against the same criteria and
+note that the visual round could not test it.
+
+## Devil's-advocate pass
+
+After the tally, and before naming a winner, write the strongest case against the leader in at
+least five sentences: the likeliest way it fails with this audience, the platform risk, the
+brand risk, and what the runner-up does better. Then decide whether the case is strong enough to
+change the winner. State the answer plainly. Do not soften the case to protect the leader.
+
+### Veto questions
+
+The pass must also answer these four about the leader, each yes or no with one line of reasoning.
+They come from `compliance-checklist.md`.
+
+1. Does it rely on an **unsubstantiated claim** (nothing in the brief, knowledge or approved lines
+   confirms it)?
+2. Is there a **trademark or parody risk** (another company's product, brand, logo or likeness)?
+3. Is there a **representation or sensitivity problem**?
+4. Is **disclosure needed** (anyone paid, gifted, an employee or an affiliate) that the brief does
+   not already handle?
+
+A "yes" that a copy edit can fix is fixed or noted for the scriptwriter. A "yes" that cannot be
+fixed in copy disqualifies the idea: record it in `decision.md` under **Veto**, take the next
+leader on the tally and run the same questions on it. Disclosure that only needs a toggle and a
+caption line is not a disqualifier; note it.
+
+## Tie-break rule
+
+If two ideas are within 3 points of weighted total, or tied on the pairwise tally, prefer in order:
+1. the higher hook-strength score;
+2. the idea buildable entirely from assets on hand (`RENDER` over `FILM`);
+3. the higher novelty score;
+4. the lower ID number (an arbitrary but fixed choice, so no one can say the order was chosen).

package/assets/claude/skills/conductor-content-studio/references/script-template.md

@@ -0,0 +1,53 @@
+# Script template
+
+`script.md` for the winning idea. Short-form craft rules this encodes: the hook lands in 0 to 3
+seconds, spoken and on screen; something new happens every 3 to 5 seconds; there is a payoff, then
+a call to action; the piece works with the sound off.
+
+```
+# Script: <title>
+
+Platform: <platform(s)>   Length: <seconds>   Tag: RENDER | FILM
+Idea: <id>   Source decision: decision.md
+
+## Hook (0-3s)
+- Spoken: <line, max 12 words, or "none">
+- On screen: <text, max 12 words>
+- Visual: <what is shown>
+
+## Beats
+| # | Time | Visual | On-screen text | Spoken / audio | What changes |
+|---|------|--------|----------------|----------------|--------------|
+| 1 | 3-6s | ... | ... | ... | <the new beat or pattern interrupt> |
+| 2 | 6-10s | ... | ... | ... | ... |
+
+## Payoff
+<the line or moment that delivers the hook's promise, with time>
+
+## CTA
+<one action; use the kit's CTA claim or an approved line where there is one>
+
+## Publish copy
+Per platform the brief asks for. The keyword the audience would search for sits in the caption's
+opening words (and in the on-screen text and speech); the first line carries the hook.
+- TikTok: <caption; keep the visible part to about 150 characters>
+- Instagram: <caption; first line carries the hook, max 125 characters shown before "more">
+- YouTube Shorts: <title max 100 characters>
+- Facebook: <caption>
+- Hashtags: <3 to 5, no more>
+- First comment: <text, or "none"; posted by hand, because Conductor cannot post comments>
+- Alternate hooks (hook swaps for variantOf experiments):
+  1. <hook line> (<hookType>)
+  2. <hook line> (<hookType>)
+  3. <optional>
+
+Hook types: question, bold-claim, pattern-interrupt, relatable-pain, how-to, number,
+curiosity-gap, story, social-proof.
+
+## Copy-rule check
+<each must-say / must-avoid item from brief.md, and ok or the fix>
+```
+
+Rules: a beat every 3 to 5 seconds; no beat longer than 5 seconds without a visual or text change;
+caption limits are in `platform-specs.md`; alternates differ from the main hook in hook type, not just wording (check current platform guidance); approved lines run
+verbatim; leave out platforms the brief did not ask for.

package/assets/claude/skills/conductor-content-studio/references/shotlist-template.md

@@ -0,0 +1,44 @@
+# Shot list and direction template
+
+`direction.md` (RENDER) and `shoot/shoot-script.md` (FILM) both use this table. A RENDER direction
+has no camera, so "visual" is the layout or frame, and the final section maps the direction onto
+the Creative's own fields.
+
+```
+# Direction: <title>
+
+## Shot list
+| Time | Visual | On-screen text | VO / audio | Asset |
+|------|--------|----------------|------------|-------|
+| 0-3s | ... | ... | ... | <media id, "to film", or none> |
+
+## Safe zones
+- Keep text out of the top ~14%, the bottom ~35% and ~6% at each side (9:16; check current
+  platform guidance).
+- Headline and CTA sit in the middle band. Nothing on a face.
+
+## Sound
+<sound on or off by design; music track id if any; voice-over; captions are always on screen>
+
+## Publish assets
+Per platform the script names:
+- Cover frame: <video: timestamp in seconds and what is on it; carousel: card 1; still: n/a>
+- Alt text: <one line per image or card, in order>
+- On-screen text placement: <where each line sits, inside the safe zone for that platform>
+- Sound source and licence: <original audio | Commercial Music Library track | library track id
+  and licence | clip's own sound | none>. Never a trending track a business account cannot license.
+
+## Capture settings (FILM only)
+9:16 vertical, 1080x1920, 30 fps, sound on, lit from the front, phone steady, shoot extra B-roll.
+
+## Ready-to-paste text (FILM only)
+<on-screen text lines in order, and the captions per platform>
+
+## Mapping to the Creative (RENDER only)
+- kind: STILL | MOTION
+- layout / theme: <from the kit and registry>
+- sequenceKind: story | carousel | none   (carouselRatio for a carousel)
+- motion: preset (fade-up | word-by-word | accent-pop | none), durationSec, background (photo or
+  clip, with its motion)
+- audio: clip | track | none
+```

package/assets/claude/skills/conductor-creative/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conductor-creative
-description: Creates on-brand marketing creative through the Conductor MCP tools — static ads and short videos alike, rendered locally on this machine and checked by eye before it's called done. Covers a photo-plus-headline ad at every enabled placement (e.g. TikTok/Reels 9:16, Instagram feed 4:5, Facebook 1:1); a short video made from a still photo or an existing clip (animated text, zoom/pan, background music, a TikTok/Reels/Shorts-ready cut); posting a finished video as-is; a story or carousel sequence; a lettered headline/hook variant for testing; and, when a workspace's Brand Kit has never been set up, setting one up first (colours, font, logo, copy rules) from a website, a brand doc, or a few direct answers. Use when asked to make, design, write or export a social ad, a promo image, a short-form video, an animated ad, or to configure/update a project's brand.
+description: Creates on-brand marketing creative through the Conductor MCP tools — static ads and short videos alike, rendered locally on this machine as a draft, checked by eye and approved before anything is saved to Conductor. Covers a photo-plus-headline ad at every enabled placement (e.g. TikTok/Reels 9:16, Instagram feed 4:5, Facebook 1:1); a short video made from a still photo or an existing clip (animated text, zoom/pan, background music, a TikTok/Reels/Shorts-ready cut); posting a finished video as-is; a story or carousel sequence; a lettered headline/hook variant for testing; and, when a workspace's Brand Kit has never been set up, setting one up first (colours, font, logo, copy rules) from a website, a brand doc, or a few direct answers. Use when asked to make, design, write or export a social ad, a promo image, a short-form video, an animated ad, or to configure/update a project's brand.
 user-invocable: true
 allowed-tools: mcp__conductor__*, AskUserQuestion, Read, Glob, Grep, WebFetch
 ---
@@ -17,7 +17,13 @@ things that already exist for this workspace — a Brand Kit (data: tokens, copy
 lines) and a Knowledge page (prose: positioning, voice, facts). Read them rather than inventing.
 
 Rendering happens locally, through this MCP server, with a browser on this machine — there is no
-separate render service to wait on. `render_creative` typically finishes in well under a minute.
+separate render service to wait on. A preview typically finishes in well under a minute.
+
+**Draft first, save after approval.** Every Creative here goes draft, look, approve, commit:
+`preview_creative_draft` renders the artwork on this machine and writes **nothing** to Conductor — no
+Creative, no upload — then the person looks at it, and only on their approval does
+`commit_creative_draft` upload the media, save the Creative and do the full render. Never commit a
+draft the person has not seen and approved.
 
 ## How to make a Creative
 
@@ -50,8 +56,8 @@ Prefer an approved line from the Knowledge page verbatim. Otherwise write one th
 real and specific, not a generic claim.
 
 If the Brand Kit's `accentPhraseRequired` is true, mark exactly one phrase per headline with
-asterisks: `Every saved link, *finally usable*.` Never zero, never two — `create_creative` and
-`update_creative` refuse a headline that gets this wrong, naming the rule.
+asterisks: `Every saved link, *finally usable*.` Never zero, never two — `preview_creative_draft`,
+`create_creative` and `update_creative` refuse a headline that gets this wrong, naming the rule.
 
 Keep it short — checked at thumbnail size, not read up close.
 
@@ -69,10 +75,13 @@ uploading a new one — id, dimensions, checked/blocked state and provenance for
 the project's media library. A photo needs `checked: true` and not `blocked` before a Creative can
 go to `READY`.
 
-A new photo goes through `upload_creative_media` (local path or URL), which requires `source` (a
-URL or a short provenance note, e.g. "Generated with a named model on a given date") and `licence`
-(e.g. "Own work", "Unsplash Licence", "Generated, house use"). This closes a real legal exposure: an
-unattributed or unlicensed photo running as paid or organic media.
+A photo that is not in the library yet is previewed straight from its local file (`photoPath` on
+`preview_creative_draft`; a URL is downloaded to a local file first) and is only uploaded when the
+draft is committed — pass `source` (a URL or a short provenance note, e.g. "Generated with a named
+model on a given date") and `licence` (e.g. "Own work", "Unsplash Licence", "Generated, house use")
+to `commit_creative_draft`, which records them on every file it uploads. This closes a real legal
+exposure: an unattributed or unlicensed photo running as paid or organic media. A photo already in
+the library is used by its id (`photoId`) with no upload at all.
 
 **Open the photo and look at it before using it.** A picture can break every copy rule with text,
 a logo or a claim burned into its pixels, and no automated check can see that — this is the first
@@ -83,48 +92,98 @@ Match the crop to the subject: a layout that lays copy over the photo (e.g. `ble
 the top third in collision with the headline — prefer a layout that keeps the photo and copy on
 separate panels (e.g. `stacked`) for those.
 
-### 6. Create, then render
-
-`create_creative` with the Brand Kit (if not the default), layout, theme, photo, headline, body,
-caption and alt text. To test a headline variant of an existing concept, pass `variantOf` with that
-Creative's id instead of starting fresh — it inherits everything else and gets the next letter.
-Then call `get_creative` to verify what was actually stored.
-
-`render_creative` (previewOnly: true first, for a quick contact sheet) runs the render locally and
-returns the render id, state, frame URLs and any warnings. Then `preview_creative` to actually look
-at it — it returns the contact sheet as an image directly, not just a URL to trust.
+### 6. Preview the draft
+
+`preview_creative_draft` with the Brand Kit (if not the default), layout, theme, photo (`photoPath`
+for a local file, `photoId` for one already in the library), headline, body, caption and alt text.
+It renders a contact sheet on this machine and returns it as an image, with the `draftDir` it wrote
+to (`.conductor/drafts/<timestamp>-<slug>/`), the readiness gaps and any render warnings. **Nothing
+has been saved to Conductor.** A copy-rule or accent-phrase violation comes back as an error naming
+the rule and field, without rendering — fix the copy and preview again.
+
+To change an existing Creative's copy, layout or photo, preview the edit first with `baseCreativeId`:
+only the fields you pass change, and the commit then updates that Creative instead of creating one.
+
+To test a headline variant of an existing concept, preview the new headline the same way
+(`baseCreativeId` plus `headline`) so the person sees it on the artwork — but do **not** commit that
+draft, since a commit would update the original. Once they approve, call `create_creative` with
+`variantOf` and the headline instead: it inherits everything else and gets the next letter.
+
+Pass `full: true` to render every placement at full size instead of the contact sheet (slower; the
+image returned is the first placement).
+
+**Read `checks` and `passed` before you show anything.** The contact sheet never runs the render's
+safety checks, so the preview also runs them for every placement (and, for a video, its end card)
+and returns them as `checks: [{placementKey, index?, rule, message, severity}]` plus `passed`. An
+`error` check (`safeZone`, `spill`, `contrast`, `font`, `image`, ...) is exactly what would fail the
+full render after the person approved: e.g. an App Store badge intruding into the band TikTok/Reels
+reserve on 9:16. A `warning` (a soft, upscaled photo) does not block, but mention it.
+
+When `passed` is false, **do not show the image or ask for approval yet.** Fix the design and
+preview again, repeating until `passed` is true:
+
+- the copy collides with a reserved zone: shorten the headline or drop the body;
+- the photo takes too much of a placement: lower its height there with `layoutOverrides.band`
+  (e.g. `{"band": {"9x16": 1100}}`);
+- the bottom row (CTA/badge) does not clear the safe zone: raise the clearance with
+  `layoutOverrides.padBottom`, or pick a layout that keeps it clear;
+- the text is too large or too small for a placement: set it with `typeOverrides` (below).
+
+Tell the person what you changed and why when you do show it. Never offer **Approve & upload**
+while a blocking check fails.
+
+**Bigger or smaller text on one placement: use `typeOverrides`, not a different layout.** It pins
+the headline per placement as `{"<placementKey>": [fontSize, lineHeight?, letterSpacing?]}`, e.g.
+`{"9x16": [96], "1x1": [88]}` for a bigger headline on 9:16 and 1:1. `fontSize` is in artboard px
+(a 9:16 board is 1080 wide), `lineHeight` a multiplier (e.g. `1.0`) and `letterSpacing` in px
+(usually negative); leave the last two out to take the engine's defaults for that size. A placement
+you do not name stays auto-fitted. A pinned size is not shrunk to fit, so re-check `checks` after
+setting one. It works on `preview_creative_draft` and `create_creative`/`update_creative`; changing
+the headline or layout of a saved Creative clears pinned sizes unless you send them again.
 
 ### 7. Look at the result honestly
 
-**A successful render proves the frame is structurally correct, not that the ad is good.** Its
-in-page checks catch text spilling out of a safe zone, a font that failed to load, a photo that
+**Passing checks prove the frame is structurally correct, not that the ad is good.** The checks
+(`passed: true`) catch text spilling out of a safe zone, a font that failed to load, a photo that
 never decoded, or contrast below the accessible minimum — not whether the headline reads at a
 glance, whether the accent phrase falls on the words that carry the meaning, or whether the copy is
-sitting on the subject's face. Judge those yourself from the image `preview_creative` hands back. If
-the copy collides with the photo, switch layout (see step 5) and re-render rather than shrinking
-text until it technically fits.
+sitting on the subject's face. Judge those yourself from the image `preview_creative_draft` hands
+back. If the copy collides with the photo, switch layout (see step 5) and preview again rather than
+shrinking text until it technically fits.
+
+Only once `passed` is true, show the image to the person and ask with `AskUserQuestion` —
+**Approve & upload**, **Request changes**, **Stop**. If `passed` is false you are not at this step
+yet: fix it and re-preview first (step 6). On changes, preview again with the edits (another draft; nothing was saved). On
+Stop, leave it: the draft stays on this machine under `.conductor/drafts/` and is cleaned up
+automatically once it is committed or two weeks old. Only on **Approve & upload**, call
+`commit_creative_draft({draftDir})` with the `draftDir` the approved preview returned.
 
 ### 8. Check readiness before calling it done
 
-`get_creative` includes a `readiness` block: caption, alt text, the photo's checked/blocked state
+The preview already lists the readiness gaps, so fix what you can (caption, alt text, a checked
+photo) before asking for approval. After the commit, `get_creative` includes a `readiness` block: caption, alt text, the photo's checked/blocked state
 and provenance, and the Creative's own state (not `DRAFT`) are blocking; an AI-generation disclosure
 is informational only. Do not call a Creative done while `ready` is false.
 
-### 9. Render for real, then hand off
+### 9. Commit, then hand off
 
-Once the preview looks right, `render_creative` again with `previewOnly: false` (or omitted) for the
-full-size placement frames, then `attach_creative_to_post` with the Post's Work Item id — it maps
-each placement to the right destinations (9:16 to TikTok/Reels, 4:5 to Instagram feed, 1:1 to
-Facebook, story to story targets) for every destination that has not set its own custom media, and
-never touches one that has. Verify with `get_post_status`. From here, use the `conductor-publisher`
-skill for scheduling, review and publishing — this skill's job ends at attaching the artwork.
+`commit_creative_draft` uploads the draft's local files, creates the Creative (or updates
+`baseCreativeId`'s), and runs the full-size render in one call, then returns the Creative id and
+display id, the frames and the readiness. It can be run once per draft; if its render fails the
+Creative is already saved — call `render_creative`, don't commit again. Verify with `get_creative`.
+Then `attach_creative_to_post` with the Post's Work Item id — it maps each placement to the right
+destinations (9:16 to TikTok/Reels, 4:5 to Instagram feed, 1:1 to Facebook, story to story targets)
+for every destination that has not set its own custom media, and never touches one that has. Verify
+with `get_post_status`. From here, use the `conductor-publisher` skill for scheduling, review and
+publishing — this skill's job ends at attaching the artwork.
 
 ## Making a sequence instead of a single ad
 
 For a platform surface that's tapped or swiped through, set `sequenceKind` to `story` (2 to 7
-beats, aim for 3 to 5) or `carousel` (2 to 10 cards, 5 to 7 performs best) on `create_creative` or
-`update_creative`, with a `sequence` array. Each beat inherits the Creative and overrides only its
-own `headline`, and optionally `body`, `photoId` or `cta`. Structure a story hook, mechanism,
+beats, aim for 3 to 5) or `carousel` (2 to 10 cards, 5 to 7 performs best) on
+`preview_creative_draft` (then `commit_creative_draft`), with a `sequence` array. Each beat inherits
+the Creative and overrides only its own `headline`, and optionally `body`, `photoPath` (a local
+photo, uploaded on commit) or `photoId`, or `cta`. Structure a story hook, mechanism,
 payoff — the first beat has to earn the next tap on its own, since that's where the drop-off is
 worst. A logo lockup and CTA claim land on the last beat only by default; `cta: true` on an earlier
 beat overrides that. A carousel renders every card at one shared aspect ratio (`carouselRatio`),
@@ -136,6 +195,9 @@ Not every video needs the brand layout above — a finished clip (a demo recordi
 something a person or another tool already produced) can go up as-is. That's a CLIP Creative: no
 photo, headline or layout, just the video.
 
+A CLIP has no artwork to render, so it is the one flow without a draft preview: open the video
+itself and check it with the person before uploading.
+
 1. Check `list_creative_media({kind: "VIDEO"})` for a clip already in the project before uploading a
    new one. A new one goes through `upload_creative_media` (local path or URL) — same provenance
    fields as a photo (`source`, `licence`, `aiGenerated`). It detects video vs. audio vs. photo
@@ -162,10 +224,11 @@ of a static frame — no separate video tool needed. Use it when a still doesn't
 destination rewards video over an image.
 
 1. Pick a photo (step 5) or, for a moving background, a video — check `list_creative_media({kind:
-   "VIDEO"})` first, then `upload_creative_media` only if nothing already fits — and note its media
-   id. For background music, `list_creative_media({kind: "AUDIO"})` the same way before uploading a
-   new track.
-2. `create_creative`/`update_creative` with `kind: "MOTION"` plus:
+   "VIDEO"})` first and use its media id if something fits; otherwise pass the local file as
+   `clipPath` (previewed from disk, uploaded on commit). For background music,
+   `list_creative_media({kind: "AUDIO"})` the same way, else `audioPath`.
+2. `preview_creative_draft` with `kind: "MOTION"` (to change a saved MOTION Creative, `baseCreativeId`
+   instead) plus:
    - `motion.preset` — how the copy enters: `fade-up` (default), `word-by-word`, `accent-pop`, or
      `none` (everything visible from the first frame).
    - `motion.durationSec` — 3 to 60, default 8.
@@ -177,13 +240,13 @@ destination rewards video over an image.
    - `audio` — `source: "clip"` (the background clip's own recorded sound — the default when there
      is one), `"track"` (a separate library track: `trackId` from `upload_creative_media`, plus
      `volume` and `fadeOutSec`), or `"none"`.
-3. `render_creative` runs a local, ffmpeg-driven encode — roughly 20 seconds per placement for an
-   8-second video. No ffmpeg on this machine fails with a clear message naming how to get one rather
-   than silently producing nothing.
-4. `preview_creative` renders three key moments across the timeline into one sheet image (not the
-   finished video). Judge it the same honest way as step 7 above — does the copy's entrance finish
-   before the next beat, does the end card actually hold long enough to read — before spending a
-   full render on it.
+3. The preview renders three key moments across the timeline into one sheet image (not the finished
+   video). Judge it the same honest way as step 7 above — does the copy's entrance finish before the
+   next beat, does the end card actually hold long enough to read — and get approval before
+   spending a full render on it.
+4. `commit_creative_draft` then uploads the media, saves the Creative and runs the local,
+   ffmpeg-driven encode — roughly 20 seconds per placement for an 8-second video. No ffmpeg on this
+   machine fails with a clear message naming how to get one rather than silently producing nothing.
 5. `attach_creative_to_post`, same as any Creative — one MP4 per placement.
 
 A library music track's `licence` has to be recorded on upload (same as a photo's provenance) — the
@@ -203,6 +266,9 @@ Automated checks are real but incomplete. These are the ones worth remembering t
 - **A Brand Kit with no copy rules, or no accent-phrase requirement, never fails a save on that
   account.** That is permissive by design, not a bug — but it means the model, not the platform, is
   the only check on brand voice for that workspace until someone configures rules.
+- **A draft is not a saved Creative.** `preview_creative_draft` writes nothing to Conductor, so a
+  Creative or media id does not exist until `commit_creative_draft` runs — don't hand a draft's
+  folder to `attach_creative_to_post` or a Post.
 - **A stale write is refused, not silently overwritten.** `update_creative` requires the Creative's
   current `version`; a mismatch comes back as a 409 naming the conflict rather than clobbering a
   concurrent edit — reread with `get_creative` and reapply, don't retry blind.

package/assets/claude/skills/conductor-creative/references/brand-kit-setup.md

@@ -0,0 +1,41 @@
+# Brand Kit check and setup
+
+Shared by `/conductor:creative` and the `conductor-creative` skill: check whether this workspace's
+Brand Kit has been set up, and offer to set it up if not. The text below is the command's Step 1,
+unchanged.
+
+## Step 1 — Check the brand
+
+Call `get_brand_kit` (pass `kitId` only if the person already named a specific brand).
+
+**If `configured` is `false`**, this workspace has no brand set up yet — offer to fix that before
+making anything:
+
+```json
+{
+  "questions": [{
+    "question": "This workspace's Brand Kit hasn't been set up yet (default colours, no font, no logo). Set it up now?",
+    "header": "Brand Kit",
+    "options": [
+      {"label": "From a website", "description": "Fetch a URL and infer colours, voice and name"},
+      {"label": "From a brand doc", "description": "Read a local file (guidelines, style doc)"},
+      {"label": "Answer a few questions", "description": "Name, colours, font, CTA line, approved lines"},
+      {"label": "Skip for now", "description": "Proceed with the default kit as-is"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+- **From a website**: ask for the URL, `WebFetch` it, infer a plausible accent colour, name, CTA
+  claim and a couple of approved lines from the copy on the page. Show what you inferred and confirm
+  before writing.
+- **From a brand doc**: ask for the file path, `Read` it, extract the same fields, confirm before
+  writing.
+- **Answer a few questions**: ask for name, primary/accent colour (hex or a description you convert),
+  font (if any), the CTA claim, and any lines that must run verbatim. Keep it to one AskUserQuestion
+  batch, not a long interview.
+- Once confirmed, call `update_brand_kit` with whatever was gathered. If a logo file or URL is
+  available, `upload_brand_image` for the `mark` slot at least. Verify with `get_brand_kit` —
+  `configured` should now read `true`.
+- **Skip for now**: proceed; the skill below will render against the default kit as given.