@cliangdev/conductor 0.36.2 → 0.38.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/assets/claude/agents/conductor-content-art-director.md +12 -3
  2. package/assets/claude/agents/conductor-content-scriptwriter.md +8 -2
  3. package/assets/claude/agents/conductor-content-strategist.md +6 -3
  4. package/assets/claude/skills/conductor-content-studio/SKILL.md +51 -13
  5. package/assets/claude/skills/conductor-content-studio/references/compliance-checklist.md +21 -0
  6. package/assets/claude/skills/conductor-content-studio/references/layout-guide.md +21 -0
  7. package/assets/claude/skills/conductor-content-studio/references/publish-pack-template.md +14 -0
  8. package/assets/claude/skills/conductor-content-studio/references/realism-check.md +70 -28
  9. package/assets/claude/skills/conductor-content-studio/references/slideshow-formats.md +9 -0
  10. package/assets/claude/skills/conductor-creative/SKILL.md +26 -12
  11. package/assets/claude/skills/conductor-creative/references/layout-guide.md +21 -0
  12. package/assets/claude/skills/conductor-creative/references/realism-check.md +70 -28
  13. package/assets/claude/skills/conductor-creative/references/slideshow-formats.md +9 -0
  14. package/dist/lib/codex-image.d.ts +2 -2
  15. package/dist/lib/codex-image.d.ts.map +1 -1
  16. package/dist/lib/codex-image.js +7 -6
  17. package/dist/lib/codex-image.js.map +1 -1
  18. package/dist/lib/image-common.d.ts +54 -3
  19. package/dist/lib/image-common.d.ts.map +1 -1
  20. package/dist/lib/image-common.js +82 -3
  21. package/dist/lib/image-common.js.map +1 -1
  22. package/dist/lib/image-generation.d.ts +3 -1
  23. package/dist/lib/image-generation.d.ts.map +1 -1
  24. package/dist/lib/image-generation.js +7 -3
  25. package/dist/lib/image-generation.js.map +1 -1
  26. package/dist/lib/openai-image.d.ts.map +1 -1
  27. package/dist/lib/openai-image.js +4 -4
  28. package/dist/lib/openai-image.js.map +1 -1
  29. package/dist/mcp/index.d.ts +4 -1
  30. package/dist/mcp/index.d.ts.map +1 -1
  31. package/dist/mcp/index.js +3 -2
  32. package/dist/mcp/index.js.map +1 -1
  33. package/dist/mcp/tools/creative-images.d.ts +7 -1
  34. package/dist/mcp/tools/creative-images.d.ts.map +1 -1
  35. package/dist/mcp/tools/creative-images.js +22 -6
  36. package/dist/mcp/tools/creative-images.js.map +1 -1
  37. package/package.json +1 -1
@@ -14,7 +14,7 @@ send to the draft renderer, so it has to be valid on the first try.
14
14
 
15
15
  - Read only the files you are given: `script.md`, `context/media.json`, `context/brand-kit.json`,
16
16
  `references/shotlist-template.md`, `references/platform-specs.md`, `references/capabilities.md`,
17
- `references/layout-guide.md`, `references/design-critique.md`, `references/slideshow-formats.md` and `references/publish-pack-template.md` when given.
17
+ `references/layout-guide.md`, `references/design-critique.md`, `references/slideshow-formats.md`, `references/realism-check.md`, `context/banned.md` and `references/publish-pack-template.md` when given.
18
18
  - Write only your output files: `direction.md` and, for `RENDER`, `creative-spec.json` (or
19
19
  `slideshow-spec.json` for a slideshow), plus `image-prompts.json` when `media.json` has `generate: true`.
20
20
  - Never call Conductor or any MCP tool.
@@ -81,21 +81,30 @@ A single JSON object whose keys are exactly `preview_creative_draft` inputs, and
81
81
  copy rule. Use an approved line verbatim where the script did.
82
82
  - A story or carousel: `sequenceKind` (`story` 2 to 7 beats, `carousel` 2 to 10 cards, plus
83
83
  `carouselRatio` such as `4x5` or `1x1`) and a `sequence` array of beats, each with `headline`
84
- and optional `body`, `photoId` or `photoPath`, `cta`.
84
+ and optional `body`, `photoId` or `photoPath`, `cta`. Set `cta: false` on every beat unless the
85
+ brief opts in to a CTA; otherwise the logo and claim row lands on the last beat. Add no offer line
86
+ by default.
85
87
  - MOTION: `motion.preset` (`fade-up`, `word-by-word`, `accent-pop` or `none`), `motion.durationSec`
86
88
  (3 to 60), `motion.background` (`{source: "photo", motion: zoom-in|zoom-out|pan-left|pan-right|none}`
87
89
  or `{source: "clip", clipMediaId}`), `motion.endCard`, and optionally top-level `audio`. A MOTION
88
90
  renders one headline and one optional body plus an end card holding the final frame: no timed
89
91
  multi-beat on-screen text (extra beats go in a story or carousel sequence, or the caption). A clip background uses `background.clipMediaId` from `media.json`, or `clipPath` for a
90
92
  user-supplied local file.
93
+ - A STILL or MOTION always shows the kit's `ctaClaim`. If it is banned, or it is an offer line the
94
+ brief did not opt in to, say so in `direction.md` so the orchestrator stops and asks.
91
95
  - Omit any field you do not need. Do not add comments or fields the tool does not take.
92
96
 
93
97
  ## image-prompts.json (only when `generate: true`)
94
98
 
95
99
  `{"photo": "<scene prompt>", "beats": {"2": "<scene prompt>"}}` next to the spec: `photo` for the
96
- main photo, `beats` keyed by sequence position for cards or beats that need their own. Each prompt
100
+ main photo, `beats` keyed by sequence position for cards or beats that need their own. Write each prompt
101
+ by the prompt-writing rules in `references/realism-check.md` (a home cook's phone photo, every
102
+ repeated item different, texture over shine, none of the banned prompt words). Vary the surface,
103
+ angle and light across the batch; one prompt with the subject swapped is a defect. Each prompt
97
104
  describes the scene, subject, light, framing and where the negative space for the headline sits. No
98
105
  text in the image, and no product depiction unless a reference image is listed in `media.json`.
106
+ Never prompt for a visual listed in `context/banned.md`. The orchestrator generates 9:16
107
+ placements with `aspect: "9:16"`; note any placement that needs another aspect.
99
108
 
100
109
  ## Finish
101
110
 
@@ -26,7 +26,10 @@ anything.
26
26
  (animated by preset) plus an end card that holds the final frame. Write one on-screen headline
27
27
  and body, not timed beats of on-screen text; extra beats belong in a story or carousel sequence
28
28
  or the caption.
29
- 4. Respect the brief's must-say and must-avoid lists. Use approved lines verbatim. If the brand kit
29
+ 4. Respect the brief's must-say and must-avoid lists. Approved lines may be used verbatim but are
30
+ never required. A CTA or offer line on a card or in a caption (the kit's `ctaClaim`, a trial,
31
+ price, plan or discount) appears only if the brief opts in; never add one by default. Naming the
32
+ app so it can be searched is not one. Never write a line the brief lists as banned. If the brand kit
30
33
  requires an accent phrase, mark exactly one `*phrase*` in on-screen headlines. Check every line
31
34
  against the copy rules and write the result in the final section.
32
35
  5. Keep captions within each platform's limits as given in `platform-specs.md`; include only the
@@ -39,7 +42,10 @@ anything.
39
42
  each tagged with a hookType (question, bold-claim, pattern-interrupt, relatable-pain, how-to,
40
43
  number, curiosity-gap, story, social-proof) that differs from the main hook's type. The
41
44
  orchestrator merges this section into `publish-pack.md`. Every factual claim must be one the
42
- brief, knowledge or approved lines confirm; soften or drop any other.
45
+ brief, knowledge or approved lines confirm; soften or drop any other. Every number or count on a
46
+ card or in a caption (ingredients, minutes, servings, kcal, macros) must match the record it came
47
+ from. End `script.md` with a "Numbers and sources" list: each number, where it appears, its source
48
+ record and the value there. The orchestrator merges it into `publish-pack.md`.
43
49
  6. For a slideshow, the script is slide by slide: slide 1 the human tension, middle slides the value,
44
50
  slide N-1 the app on a real screenshot with one plain mention ("I keep mine in <App>"), the last
45
51
  slide a save or follow ask. At most 8 words a line and 3 lines a box. No logo, badge or offer on a
@@ -13,7 +13,7 @@ ideas, so be specific and evidence-led.
13
13
  ## Boundaries
14
14
 
15
15
  - Read only the input files you are given (normally `context/brand-kit.json`, `context/knowledge.md`,
16
- `context/performance.md`, `context/learning.md`, `context/media.json` and `request.md` in the run folder, plus
16
+ `context/performance.md`, `context/learning.md`, `context/banned.md`, `context/media.json` and `request.md` in the run folder, plus
17
17
  `references/capabilities.md`). State rendering constraints from that file, not from memory. For
18
18
  example, motion text over a photo is renderable and needs no filming, but every renderable post
19
19
  needs a photo or clip.
@@ -33,8 +33,11 @@ Use these headings, in this order, and keep the whole file under about 500 words
33
33
  3. **Platform(s) and format**: the platform(s) the request names or implies, and the formats that
34
34
  suit them. If the request is silent, choose one and say why.
35
35
  4. **Must-say / must-avoid**: every copy rule from the brand kit (pattern and message), whether an
36
- accent phrase is required, and each approved line, verbatim. List also any must-say line the
37
- request gave.
36
+ accent phrase is required, and any must-say line the request gave. Copy every banned line,
37
+ phrase and visual from `context/banned.md` into must-avoid, verbatim, every one. Approved lines
38
+ are allowed, not required: list them as "may use", never as must-say. A CTA or offer line on a
39
+ card or in a caption (the kit's `ctaClaim`, a trial, price, plan or discount) is must-avoid
40
+ unless the request asks for one. Naming the app so it can be searched is not one.
38
41
  5. **Assets on hand**: a short list from `media.json` (id, kind, label, whether checked), and what
39
42
  is missing. Say plainly whether any video exists, since that decides what can be rendered.
40
43
  6. **What has worked**: from `performance.md`, `learning.md` and the what-works page, the patterns
@@ -34,6 +34,16 @@ Each exists because of a known failure mode (sources are in `references/rubric.m
34
34
  native-looking slideshow built by `compose_slideshow` and posted as a CAROUSEL; see
35
35
  `references/slideshow-formats.md`. STILL and MOTION stay for ideas that really are one still, an
36
36
  ad, or a motion piece. A slideshow never carries a logo, badge or offer.
37
+ - **Rejected copy stays rejected.** A CTA or offer line on a card or in a caption is opt-in per
38
+ request, never a default. That means a sales line: the kit's `ctaClaim`, a trial, price, plan or
39
+ discount. Naming the app so it can be searched is not one. Approved lines in the knowledge pages are allowed, not required. When the
40
+ person rejects a line, phrase or visual during a run, ask once whether to ban it. On a yes:
41
+ `get_brand_kit`, append a rule to `copyRules` with id `banned-<slug>` for a line or phrase (an
42
+ escaped regex `pattern`, `flags: "i"`, `fields: ["headline", "body", "caption"]`, a `message` that
43
+ names it as rejected and the date) or `banned-visual-<slug>` for a visual (the `message`
44
+ describes the visual, the `pattern` matches its name). `update_brand_kit` replaces the whole list,
45
+ so send the full existing list plus the new rule, then verify with `get_brand_kit`. S0 reads these
46
+ rules into `context/banned.md` on every later run.
37
47
 
38
48
  Cost: a run is about 8 subagent calls (strategist 1, ideators 3, director 2, scriptwriter 1, art
39
49
  director 1), and only the strategist and the director use the top model tier. `--quick` runs two
@@ -50,7 +60,7 @@ folder; give subagents absolute paths.
50
60
  request.md run.json brief.md script.md direction.md creative-spec.json decision.md
51
61
  slideshow-spec.json (S5, instead of creative-spec.json, when the winner is a slideshow)
52
62
  image-prompts.json (S5, only when generation is enabled)
53
- context/ brand-kit.json knowledge.md performance.md learning.md media.json
63
+ context/ brand-kit.json knowledge.md performance.md learning.md banned.md media.json
54
64
  ideas/ angle-1.md angle-2.md angle-3.md pool.md winner.md
55
65
  judging/ scores.md
56
66
  drafts/ finalist-<id>/ (contact sheets from the finalist renders)
@@ -113,7 +123,7 @@ Write `request.md` (the request verbatim, `--quick` if given, the platform if st
113
123
  2. Knowledge, for `context/knowledge.md`: `read_knowledge_pages` for the kit's `knowledgePagePath`
114
124
  and `marketing/what-works.md`; `search_knowledge` for persona/audience, campaign and positioning
115
125
  pages and read the best few (at most 6 pages in all). Paste each page under its path heading, trimmed
116
- to what bears on the request; keep approved lines verbatim. List every expected page that was not
126
+ to what bears on the request; keep approved lines verbatim, marked "may use, not required". List every expected page that was not
117
127
  found under "Missing pages". A missing page is a gap to record, never a reason to stop.
118
128
  3. Performance, for `context/performance.md`: `get_marketing_insights` (window `30d`, or `90d` if
119
129
  empty) and `list_top_posts` (limit 10). Summarise what the data says; "no performance data yet"
@@ -127,7 +137,10 @@ Write `request.md` (the request verbatim, `--quick` if given, the platform if st
127
137
  not, using views, engagement rate, average view percentage, 72 h views and any 3-second or
128
138
  completion figure the insights expose, and any experiment result. Name what you could not
129
139
  measure. With no earlier run or no data, write exactly "No data yet".
130
- 6. Every renderable idea needs a photo (or, for MOTION, a clip; for a slideshow's payoff slide, a real
140
+ 6. Banned copy, for `context/banned.md`: list every `copyRules` entry in `context/brand-kit.json`
141
+ whose id starts with `banned-` (the line or visual, the pattern and the message). With none,
142
+ write exactly "No banned copy yet".
143
+ 7. Every renderable idea needs a photo (or, for MOTION, a clip; for a slideshow's payoff slide, a real
131
144
  app screenshot, so ask for one if the media has none); see `references/capabilities.md`. If
132
145
  `media.json` has no unblocked image and no clip, ask once with `AskUserQuestion` before ideating:
133
146
  **Give a photo or two** (local paths; record them in `context/media.json` as `local` entries the
@@ -147,7 +160,7 @@ Write `request.md` (the request verbatim, `--quick` if given, the platform if st
147
160
 
148
161
  ### S1 — Strategist -> `brief.md`
149
162
 
150
- `Agent(subagent_type: "conductor-content-strategist")` with the six context files, `request.md`
163
+ `Agent(subagent_type: "conductor-content-strategist")` with the seven context files (including `context/banned.md`, whose every entry goes into the brief's must-avoid), `request.md`
151
164
  and `references/capabilities.md` (so the brief states rendering constraints correctly: motion text
152
165
  over a photo is renderable and needs no filming).
153
166
 
@@ -187,8 +200,9 @@ text) unless its slides can be composed from photos already on hand. In that cas
187
200
  that folder and judge from the first slide and the `checks`. For every other `RENDER` finalist, call `preview_creative_draft` with that idea's draft spec (map the
188
201
  draft-spec block to the tool's fields) and `draftDir` set to `<run>/drafts/finalist-<id>`. Use
189
202
  `full: false`. Record each draft dir in `run.json`. For a finalist whose draft spec carries an
190
- `imagePrompt`, call `generate_creative_image({prompt})` first, run the realism check
191
- (`references/realism-check.md`, regenerating on a fail), and use its
203
+ `imagePrompt`, write the prompt by the prompt-writing rules in `references/realism-check.md` and
204
+ call `generate_creative_image({prompt, aspect: "9:16"})` (the largest 9:16 size, so the draft is not
205
+ upscaled), run the realism check on 100% crops (regenerating on a fail), and use its
192
206
  path as `photoPath` (generate only for finalists, not the whole pool).
193
207
 
194
208
  - If the validator refuses the copy (accent phrase or a copy rule), fix the copy once yourself and
@@ -220,7 +234,7 @@ which idea to take; show the decision at the gate.
220
234
 
221
235
  First copy the winning idea's block from `ideas/pool.md` to `ideas/winner.md`. Then
222
236
  `Agent(subagent_type: "conductor-content-scriptwriter")` with `brief.md`, `decision.md`, `ideas/winner.md`, `references/script-template.md`, `references/platform-specs.md` and
223
- `references/publish-pack-template.md`. Besides the script it writes the Publish copy section: a
237
+ `references/publish-pack-template.md`. Besides the script it writes the "Numbers and sources" list (every number on a card or in a caption, with its source record) and the Publish copy section: a
224
238
  caption per platform whose call to action names the app so it can be searched, hashtags, a pinned
225
239
  comment and 2 to 3 alternate hooks with a hookType each.
226
240
  For a `MOTION` winner tell it that the render shows one headline and one optional body, animated
@@ -235,11 +249,13 @@ For a slideshow winner the art director writes `slideshow-spec.json` instead of
235
249
  `context/media.json`, `script.md`, `references/platform-specs.md`, `references/design-critique.md` and
236
250
  `references/publish-pack-template.md`. Photos and the app screenshot are paths from `media.json`
237
251
  (download a library image to a local file first) or the person's local files; generated photos go
238
- through `generate_creative_image` and the realism check first, as below. The rest of this stage is
252
+ through `generate_creative_image` and the realism check first, as below. Every photo then goes
253
+ through the resolution gate below. The rest of this stage is
239
254
  the STILL/MOTION path.
240
255
 
241
256
  `Agent(subagent_type: "conductor-content-art-director")` with `script.md`, `context/media.json`,
242
- `context/brand-kit.json`, `references/shotlist-template.md`, `references/platform-specs.md` and
257
+ `context/brand-kit.json`, `context/banned.md`, `references/shotlist-template.md`,
258
+ `references/platform-specs.md`, `references/realism-check.md` and
243
259
  `references/publish-pack-template.md`. Besides the spec it writes the Publish assets section of
244
260
  `direction.md`: cover frame, alt text per card, on-screen text placement and the sound source and
245
261
  licence per platform.
@@ -251,12 +267,22 @@ when 9:16 is enabled. The spec's keys must be exactly
251
267
  `preview_creative_draft` inputs. Give it `references/capabilities.md` too. The spec's `name` is the
252
268
  idea's title only: never include the internal `I<n>` ID, which means nothing outside this run. When
253
269
  `media.json` has `generate: true`, the art director may also write `image-prompts.json`
254
- (`{"photo": "...", "beats": {"2": "..."}}`) next to the spec. Before S6, call
255
- `generate_creative_image` for each prompt, run the realism check (`references/realism-check.md`,
256
- regenerating on a fail) on each image, and set `photoPath` (or
270
+ (`{"photo": "...", "beats": {"2": "..."}}`) next to the spec. Prompts follow the prompt-writing
271
+ rules in `references/realism-check.md` and differ in surface, angle and light across the batch. Before S6, call
272
+ `generate_creative_image` for each prompt with `aspect: "9:16"` for 9:16 placements (`"4:5"` or
273
+ `"1:1"` only when no 9:16 placement is enabled), read the result's `placementFit`, run the realism check
274
+ (`references/realism-check.md`, regenerating on a fail) on each image at 100%, and set `photoPath` (or
257
275
  `sequence[i].photoPath`) in `creative-spec.json` (for a slideshow, the slide's `bg` or `photos[].src` in `slideshow-spec.json`; `beats` keys are slide numbers). A `FILM` winner skips S5 and goes to the shoot
258
276
  script, below.
259
277
 
278
+ **Resolution gate (before S6 renders).** For every photo in the spec, library or generated, compute
279
+ the scale per enabled placement and crop, adding the 1.12 video zoom for MOTION (see
280
+ `references/layout-guide.md`, "Resolution"). Use `placementFit` for a generated photo, and
281
+ `max(W/w, H/h)` from `list_creative_media` dimensions for a library one. Refuse any full-bleed use
282
+ above 1.0x. Fix it before rendering: generate at the largest size in that aspect, use a different
283
+ photo, or pick a layout that shows the photo framed at or below native size. Never carry an
284
+ upscaled photo into S6 with a note.
285
+
260
286
  ### S5b — Publish pack and pre-publish checks (you; RENDER after S5, FILM after the shoot script)
261
287
 
262
288
  Before the gate, so the person sees the settings with the draft. Skip nothing here; a check that
@@ -279,10 +305,22 @@ does not apply is answered "not applicable".
279
305
  4. A claims or trademark check that fails and cannot be fixed by you in one word goes back to the
280
306
  scriptwriter once, with the failing line; re-run S4's merge and S5 only if the copy changed. If
281
307
  it still fails, show it at the gate as a known issue and never hide it.
282
- 5. Set `S5b` to `done`. On any later copy change, redo this stage so the pack matches the draft.
308
+ 5. Fact lint: merge the scriptwriter's "Numbers and sources" into the pack and check each number
309
+ against its source record (checklist item 9). Fix a mismatch before the gate.
310
+ 6. Banned-copy grep: search `creative-spec.json` or `slideshow-spec.json`, `script.md`,
311
+ `image-prompts.json`, every caption and `publish-pack.md` and `.json` for every banned line,
312
+ phrase and visual in `context/banned.md`, case-insensitive. A hit is fixed (then redo the
313
+ affected stage), never shown. Record the result in the pack's "Banned-copy check".
314
+ 7. STILL or MOTION: it always shows the kit's `ctaClaim`. If that claim is banned, or the request
315
+ did not opt in to a CTA and the claim is an offer line, stop and ask the person before S6
316
+ renders. A sequence uses `cta: false` on every beat unless the brief opted in.
317
+ 8. Set `S5b` to `done`. On any later copy change, redo this stage so the pack matches the draft.
283
318
 
284
319
  ### S6 — Preview gate (you; `RENDER` winner)
285
320
 
321
+ Resolution gate first: confirm S5's gate passed for every photo in the spec. A photo above 1.0x at
322
+ any placement is fixed now, not shown.
323
+
286
324
  1. `preview_creative_draft` with the fields from `creative-spec.json`, `full: false`, and no
287
325
  `draftDir` (the default location is cleaned up automatically after the commit). Record the
288
326
  returned `draftDir` as `drafts.final`. Local files (`photoPath`, `clipPath`, `audioPath`) go in
@@ -114,6 +114,27 @@ and the caption.
114
114
  text is preferred over relying on a platform's auto-captions.
115
115
  - Contrast and safe zones are already checked by the renderer; do not repeat them.
116
116
 
117
+ ## 8. Sensitive imagery (Veto)
118
+
119
+ **Does any costume, hooded figure, gesture or symbol resemble a hate symbol?** Check every mascot,
120
+ person, prop and generated image prompt, including shapes that only read that way at a glance.
121
+
122
+ - A white sheet-ghost with a pointed peak reads as a Klan hood. Never use it for a mascot or a
123
+ person.
124
+ - If it resembles one, change the costume, colour or shape and note the change, or drop the image.
125
+ If the idea depends on it, the idea fails.
126
+
127
+ ## 9. Numbers match their source (Veto)
128
+
129
+ **Does every number or count on a card, slide or caption match the record it came from?**
130
+ Ingredients, minutes, servings, kcal and macros all count.
131
+
132
+ - Each number gets a row in the pack's "Numbers and sources" list: the number as written, the
133
+ source record (recipe, knowledge page, brief) and the value there.
134
+ - A mismatch is fixed to the source value or the number is removed. Example: a card said "5
135
+ ingredients" for a 10-ingredient recipe.
136
+ - A number with no source record is removed, as in check 4.
137
+
117
138
  ## Result
118
139
 
119
140
  Write a table: check, answer (yes / no / not applicable), what was done, option set. A check that
@@ -35,6 +35,27 @@ On 1:1 every layout auto-fits the headline small (about 60 px at most). Pin it w
35
35
  e.g. `{"1x1": [88]}`; 92 passed the checks with an eight-word headline. A pinned size is not shrunk to
36
36
  fit, so read `checks` again after pinning.
37
37
 
38
+ ## Resolution
39
+
40
+ Never upscale a photo. Before rendering, compute each photo's scale per placement and crop: the
41
+ full-bleed cover scale is `max(W/w, H/h)` for a placement of W x H and a photo of w x h. Placements
42
+ are 9:16 (1080x1920), 4:5 (1080x1350) and 1:1 (1080x1080). For a MOTION also multiply by the video
43
+ zoom (up to 1.12).
44
+
45
+ - A 1200x1200 photo full-bleed at 9:16 uses 675x1200 source pixels for 1080x1920: 1.6x.
46
+ - A 1024x1536 photo at 9:16 is 1.25x. A 1440x2560 one is 0.75x, and 0.84x with the 1.12 zoom.
47
+ - `bleed` is full-bleed on every placement. Refuse any full-bleed use above 1.0x, and compute the
48
+ scale for the photo's actual crop in `card`, `split` and `stacked` too.
49
+
50
+ Fixes, in order:
51
+
52
+ 1. Generate at the largest size in that placement's aspect (`aspect: "9:16"` for 9:16;
53
+ `placementFit` in the result shows the scale per placement).
54
+ 2. Use a different photo.
55
+ 3. Use a layout that shows the photo framed at or below native size.
56
+
57
+ A photo above 1.0x is fixed before anything is shown, not mentioned.
58
+
38
59
  ## Logo
39
60
 
40
61
  `lockup: "chip"` puts the logo on a white pill. Use it when the photo behind the logo is busy.
@@ -53,6 +53,16 @@ Run: <runId> Creative: <display id, or "not yet committed"> Tags: hook <type
53
53
  ## Compliance
54
54
  <the table from compliance-checklist.md: check, answer, what was done, option set>
55
55
 
56
+ ## Numbers and sources
57
+ | Number as written | Where it appears | Source record | Value in source |
58
+ |---|---|---|---|
59
+ | <"10 ingredients", "25 min", "420 kcal"> | <card or caption> | <recipe, page or brief> | <value there> |
60
+ (Write "none" if the post has no numbers. Every number must match its source.)
61
+
62
+ ## Banned-copy check
63
+ <"clean: no banned line or visual from context/banned.md appears in the specs, script, image
64
+ prompts, captions or this pack", or the hit and how it was fixed>
65
+
56
66
  ## Third-party assets
57
67
  | Asset | Whose | Permission or licence |
58
68
  |---|---|---|
@@ -80,6 +90,8 @@ Run: <runId> Creative: <display id, or "not yet committed"> Tags: hook <type
80
90
  "options": { "altText": "<alt text for a single feed image>" }
81
91
  }
82
92
  ],
93
+ "numbers": [{ "number": "10 ingredients", "appearsIn": "card 2", "source": "<recipe or page>", "sourceValue": "10" }],
94
+ "bannedCopyCheck": "clean",
83
95
  "altText": ["<card 1 alt text>", "<card 2 alt text>"],
84
96
  "alternateHooks": [{ "hook": "<line>", "hookType": "question" }],
85
97
  "tags": { "hookType": "bold-claim", "angle": "utility-education", "format": "carousel" }
@@ -119,6 +131,8 @@ Rules:
119
131
  default. Keys that need a Post's own asset id (`coverAssetId`, `thumbnailAssetId`,
120
132
  `photoCoverIndex`) are not known until media is attached to a Post, so the pack does not carry
121
133
  them; the cover frame is in `publish-pack.md` for the publisher to act on.
134
+ - `numbers` has one item per number on a card, slide or caption (empty array if none), each matching
135
+ its source record. `bannedCopyCheck` is `"clean"` or a short note of the hit and its fix.
122
136
  - `altText` is one string per image or card, in order. It is also the source for the Creative's
123
137
  own `altText` field.
124
138
  - `alternateHooks` and `tags` are for learning and experiments, not for publishing. `tags` is also
@@ -1,53 +1,95 @@
1
1
  <!-- Keep identical to the copy in the other creative skill (conductor-creative / conductor-content-studio references/realism-check.md). Skills install independently and cannot reference each other. -->
2
- # Realism check for generated photos
2
+ # Make it real, then check it
3
3
 
4
4
  This is about image quality, not concealment. The `aiGenerated: true` provenance and the platform's
5
5
  AI label still apply to every generated photo, however real it looks.
6
6
 
7
- ## When
8
-
9
- Every image from `generate_creative_image`, before it is used as `photoPath`. Also glance at library
10
- photos marked `aiGenerated`.
7
+ A realistic photo comes from the prompt first and the check second. Write the prompt with the rules
8
+ below, then check the result at the size it will be seen.
9
+
10
+ ## Write the prompt
11
+
12
+ These rules apply to every `generate_creative_image` call, from the art director and from the
13
+ orchestrator.
14
+
15
+ - **Shoot it like a home cook's phone photo, not an ad.**
16
+ - Light: ordinary kitchen or window light. Normal dynamic range, a slightly off white balance, a
17
+ little sensor noise.
18
+ - Banned prompt words: cinematic, stunning, perfect, hyper-detailed, 8k, award-winning, golden
19
+ hour, dramatic lighting, professional food photography, bokeh, glossy, studio.
20
+ - **Every repeated item is different.** When a dish has several of something (stuffed peppers,
21
+ tacos, cookies, dumplings, slices), the prompt names how they differ:
22
+ - size, shape and lean;
23
+ - how each is cut or carved;
24
+ - char and blistering on one side only, a split skin on one;
25
+ - filling heaped on one and sunk on another;
26
+ - cheese melted unevenly, with one spot browner;
27
+ - one slightly collapsed.
28
+
29
+ Example for jack-o'-lantern stuffed peppers: "four peppers of different sizes and shades of
30
+ orange, one leaning against another, each with a differently carved face (one lopsided, one with a
31
+ missing tooth, one with small round eyes), the tallest has blistered skin on one side, filling
32
+ spilling over the rim of one, cheese melted unevenly."
33
+ - **Texture over shine.** Food that is matte in life stays matte. Sauces are a little broken or
34
+ dried at the edges. There are crumbs, drips and a smear on the dish rim. No steam wisps, no perfect
35
+ cheese pulls, no scattered garnish confetti.
36
+ - **A real setting, lightly used.** Choose things a home has:
37
+ - a sheet pan or baking dish with scorch marks, or a scratched enamel pot;
38
+ - a worn wooden board, a laminate counter, a dish towel, a fork already in it.
39
+ - Do not stage it. Something is slightly cut off at the frame edge.
40
+ - **Off-center and imperfect framing.** No symmetrical hero composition. A slight tilt, an ordinary
41
+ handheld angle (overhead or about 45 degrees, not low and dramatic).
42
+ - **Vary across a batch.** Each image in a set gets its own surface, angle and light; only the
43
+ realism and the absence of on-image text are shared. One prompt with the dish name swapped in is a
44
+ defect.
45
+ - **No people's faces, hands only if needed.** No text, logos or packaging brands in the image.
46
+
47
+ For a subject that is not food, keep the same spirit: ordinary light, a lived-in setting, every
48
+ repeated object different, imperfect framing.
49
+
50
+ ## When to check
51
+
52
+ Every image from `generate_creative_image`, before it is used as `photoPath`. Photos already in a
53
+ library are not exempt: an existing recipe photo gets the same check, whoever made it.
11
54
 
12
55
  ## How to look
13
56
 
14
- Open the full-size file with Read, not only the small inline preview. Look at it twice: at phone
15
- size, as a scrolling viewer would, and zoomed in on the subject.
57
+ Check a 100% crop of the region that will be on screen, at the size and crop of each placement:
58
+ 4:5, 9:16 and, for a MOTION, the video zoom (up to 1.12x). Open the full-size file with Read and
59
+ crop it. Never judge from a contact sheet: it hides exactly the tells below.
16
60
 
17
61
  ## Tells
18
62
 
19
- - **Surface and finish**: waxy or plastic skin, food or fabric; everything glossy; over-smoothed
20
- texture; over-sharpening; HDR glow or halos; colours too saturated.
21
- - **Anatomy**: hands and fingers (count, joints), teeth, eyes and gaze, ears, hair edges merging
22
- into the background.
23
- - **Objects and physics**: duplicated items (the same garnish, mug or prop twice); objects merging or
24
- floating; tools or handles that do not connect to anything; impossible reflections; steam or liquid
25
- that looks painted; wrong scale.
26
- - **Scene and light**: light direction or shadows that disagree; everything perfectly tidy or
27
- symmetrical; a staged stock-photo look; background detail that turns to mush; repeating textures.
28
- - **Text and brand**: pseudo-text, garbled labels, invented logos, a fake product or app screen.
63
+ - **Light**: golden-hour or HDR glow, halos, dramatic or studio lighting, perfect white balance,
64
+ colours too saturated, over-sharpening.
65
+ - **Repeated items**: identical copies of the same item, the same garnish or prop twice.
66
+ - **Objects and physics**: melted or merged objects, floating items, utensils or handles that do not
67
+ connect to anything, impossible reflections, steam or liquid that looks painted, wrong scale.
68
+ - **Text**: pseudo-text, garbled labels, invented logos, a fake product or app screen.
69
+ - **Texture**: plastic or waxy food, skin or fabric; everything glossy; over-smoothed surfaces;
70
+ perfect cheese pulls.
71
+ - **Anatomy**: hands and fingers (count, joints), teeth, eyes, hair edges merging into the
72
+ background.
73
+ - **Detail under zoom**: smeared or mushy detail, repeating textures, a staged stock-photo look.
29
74
 
30
75
  ## Verdict
31
76
 
32
- PASS, or FAIL naming the specific tell(s). A minor issue that will not show at phone size can PASS
33
- with a note.
77
+ Write PASS or FAIL for each placement crop, naming the tell on a FAIL. Any tell above that shows in
78
+ a crop is a FAIL. A flaw that shows in no placement crop can PASS with a note.
34
79
 
35
80
  ## On FAIL
36
81
 
37
- Regenerate with the scene prompt revised to fix the named tell, for example "one bowl of salsa, not
38
- two", "matte surface, soft window light, less sharpening", "hands out of frame", "a worn leather
39
- sofa with a crease, not a showroom set". At most two regenerations per image (each costs about $0.05
40
- on the API, or Codex allowance on the Codex route, which the person has already agreed to). Avoid
41
- hands and faces in close-up unless the idea needs them.
42
-
43
- If the third image still fails, stop. Tell the person what looks generated and offer a library
44
- photo, a reference photo (`referenceImagePaths`), or filming.
82
+ Regenerate with the failed tells named in the new prompt, for example "four different peppers, no
83
+ two alike", "matte sauce, dried at the edges, soft window light", "hands out of frame". At most two
84
+ regenerations per image (larger sizes cost more on the API, and the Codex route spends the allowance
85
+ the person has already agreed to). Then stop. Tell the person what still looks generated and offer a
86
+ library photo, a reference photo (`referenceImagePaths`), or filming. Never ship a FAIL.
45
87
 
46
88
  ## Report
47
89
 
48
90
  When showing the draft for approval, give a one-line realism verdict per generated photo:
49
91
 
50
92
  - "Realism: passed — natural light, believable clutter"
51
- - "Realism: passed with a note — slightly glossy sauce, invisible at phone size"
93
+ - "Realism: passed with a note — a smudge at the far edge, outside every placement crop"
52
94
 
53
95
  The person's approval remains the final check.
@@ -91,6 +91,15 @@ Pick one per post and name it in the idea. Change one thing per post so results
91
91
  - The first text of every slide needs `y`.
92
92
  - Read the composer's `checks`; an `error` severity blocks the preview.
93
93
 
94
+ ## Resolution
95
+
96
+ Slides are 1080x1920 (and 1080x1350 for Instagram). Never upscale a background photo: the full-bleed
97
+ scale is `max(1080/w, 1920/h)` for a photo of w x h (use `max(1080/w, 1350/h)` for the 4:5 cut). A 1200x1200
98
+ photo full-bleed at 9:16 uses 675x1200 source pixels, a 1.6x upscale. Check every `bg` and
99
+ `photos[].src` before composing and refuse a full-bleed use above 1.0x. The fixes are: generate at
100
+ the largest size in that aspect (`aspect: "9:16"`), use a different photo, or use a slide type that
101
+ shows the photo framed at or below native size (such as `grid` or `stack`).
102
+
94
103
  ## Honesty and brand
95
104
 
96
105
  - No logo, badge or offer on the slides. The offer, if any, goes in the caption.
@@ -45,7 +45,13 @@ URLs, the CTA claim, the copy rules (each a regex, a message, and which fields i
45
45
  approved lines, the enabled placements, and `knowledgePagePath` — the wiki page holding this
46
46
  brand's positioning, message hierarchy, approved verbatim lines and voice in prose. Read that page
47
47
  with `read_knowledge_pages` before writing anything. Quote its approved lines rather than
48
- paraphrasing them; they were worded and cleared on purpose.
48
+ paraphrasing them when you use one; they were worded and cleared on purpose, and are allowed, not
49
+ required. A CTA or offer line (a trial, price, plan or discount) is opt-in per request, never a default. Copy rules with ids starting
50
+ `banned-` are lines, phrases or visuals the person rejected earlier: never reuse them. When the person
51
+ rejects one now, ask once whether to ban it; on a yes append a `banned-<slug>` rule (escaped regex
52
+ `pattern`, `flags: "i"`, `fields` headline, body and caption, a `message` naming it as rejected and
53
+ the date) to the full existing `copyRules` list, call `update_brand_kit` (it replaces the whole list),
54
+ and verify with `get_brand_kit`.
49
55
 
50
56
  **If `configured` comes back `false`**, this kit has never been touched — a brand-free stock
51
57
  default, not this workspace's actual brand. Set it up before writing any ad rather than rendering
@@ -100,9 +106,10 @@ the library is used by its id (`photoId`) with no upload at all.
100
106
 
101
107
  **Nothing in the library fits, or the person asks for a generated one?** Call
102
108
  `generate_creative_image` with a scene prompt drawn from the brand's Knowledge page and the angle:
103
- the scene, subject, light, framing and where the headline's negative space sits. The tool adds its own
109
+ the scene, subject, light, framing and where the headline's negative space sits, written by the
110
+ prompt-writing rules in `references/realism-check.md`. The tool adds its own
104
111
  fixed rules (photographic, no text, letters, logos, UI or phone screens) and uses the OpenAI Images API
105
- when a key is set (`conductor config set-openai-api-key`; about $0.05 an image, 20-45 s; `conductor doctor`
112
+ when a key is set (`conductor config set-openai-api-key`; 20-45 s; larger sizes cost more; `conductor doctor`
106
113
  reports the route). With no key it generates nothing and returns `CODEX_CONFIRMATION_REQUIRED`: ask the
107
114
  person whether to set a key, use Codex this time (their ChatGPT Plus weekly allowance, shared with coding;
108
115
  about 40-50 images uses a week), or skip and use a library photo. Only on an explicit yes call again with
@@ -110,20 +117,26 @@ about 40-50 images uses a week), or skip and use a library photo. Only on an exp
110
117
  `sequence[].photoPath`). When the real product must appear, list a real shot in
111
118
  `referenceImagePaths` — never describe an invented product. Each file gets a provenance sidecar
112
119
  (`aiGenerated: true`) that the preview and commit use automatically, so don't ask about it, and the
113
- AI label applies. A 1024x1536 image cropped to 9:16 may draw the "soft, upscaled photo" warning:
114
- mention it, don't fight it.
120
+ AI label applies. `aspect` defaults to `"9:16"` (1440x2560, the largest 9:16 size); `"4:5"`, `"1:1"`,
121
+ `"2:3"`, `"3:2"` and `"16:9"` are the other options and `size` sets an exact `WIDTHxHEIGHT`. Generate in the
122
+ aspect of the placement you will use it full-bleed in. The result's `placementFit` gives each placement's
123
+ scale (9:16, 4:5, 1:1, and with the video zoom). Never use a photo above 1.0x full-bleed: a 1200x1200
124
+ photo at 9:16 is a 1.6x upscale and a 1024x1536 one is 1.25x. Fix it before previewing: generate at the
125
+ largest size in that aspect, use a different photo, or pick a layout that shows the photo framed at or
126
+ below native size (`references/layout-guide.md`, "Resolution").
115
127
 
116
128
  **The photo shows the product doing its job**, or a concrete scene of the problem or the result: a real
117
129
  screen or shot (pass it in `referenceImagePaths`, or use a library photo of the product in use). Stock
118
130
  poses (a person smiling at a phone on a couch, a mug, a generic laptop) and empty decorative scenes (a
119
131
  sunlit counter with nothing happening) are out. A generated still cannot show an invented product
120
132
  screen; real product shots come in as references. Ask for `count: 2` or `3` when you want options
121
- (each image costs about $0.05 on the API route; on the Codex route each uses weekly quota, so ask first).
133
+ (each image bills the API key, more at larger sizes; on the Codex route each uses weekly quota, so ask first).
122
134
 
123
- **Every generated photo gets the realism check** in `references/realism-check.md` before it is used:
124
- it must not look AI-made (waxy surfaces, duplicated objects, warped hands, mushy detail). On a fail,
125
- regenerate with a prompt that names the fix, at most twice; if the third still fails, say what looks
126
- generated and offer a library photo, a reference photo or filming. The check is about quality, not
135
+ **Every generated photo gets the realism check** in `references/realism-check.md` before it is used,
136
+ on a 100% crop at each placement's size and crop, never a contact sheet: it must not look AI-made
137
+ (waxy surfaces, duplicated objects, warped hands, mushy detail). Library photos are checked too. On a
138
+ fail, regenerate with a prompt that names the failed tells, at most twice; if the third still fails,
139
+ say what looks generated and offer a library photo, a reference photo or filming. Never ship a FAIL. The check is about quality, not
127
140
  concealment: the AI label still applies.
128
141
 
129
142
  **Open the photo and look at it before using it** — a generated one most of all (pseudo-text, warped
@@ -166,7 +179,8 @@ safety checks, so the preview also runs them for every placement (and, for a vid
166
179
  and returns them as `checks: [{placementKey, index?, rule, message, severity}]` plus `passed`. An
167
180
  `error` check (`safeZone`, `spill`, `contrast`, `font`, `image`, ...) is exactly what would fail the
168
181
  full render after the person approved: e.g. an App Store badge intruding into the band TikTok/Reels
169
- reserve on 9:16. A `warning` (a soft, upscaled photo) does not block, but mention it.
182
+ reserve on 9:16. A `warning` about a soft, upscaled photo means the resolution gate was missed: fix the
183
+ photo (step 5) before showing the draft. Other warnings do not block, but mention them.
170
184
 
171
185
  When `passed` is false, **do not show the image or ask for approval yet.** Fix the design and
172
186
  preview again, repeating until `passed` is true:
@@ -249,7 +263,7 @@ the Creative and overrides only its own `headline`, and optionally `body`, `phot
249
263
  photo, uploaded on commit) or `photoId`, or `cta`. Structure a story hook, mechanism,
250
264
  payoff — the first beat has to earn the next tap on its own, since that's where the drop-off is
251
265
  worst. A logo lockup and CTA claim land on the last beat only by default; `cta: true` on an earlier
252
- beat overrides that. A story sequence publishes: attach it to an Instagram or Facebook Story
266
+ beat overrides that. Set `cta: false` on every beat unless the request opts in to a CTA. A story sequence publishes: attach it to an Instagram or Facebook Story
253
267
  destination and each beat goes out as its own story, in order. A carousel renders every card at one shared aspect ratio (`carouselRatio`),
254
268
  since the destination platforms require that.
255
269
 
@@ -35,6 +35,27 @@ On 1:1 every layout auto-fits the headline small (about 60 px at most). Pin it w
35
35
  e.g. `{"1x1": [88]}`; 92 passed the checks with an eight-word headline. A pinned size is not shrunk to
36
36
  fit, so read `checks` again after pinning.
37
37
 
38
+ ## Resolution
39
+
40
+ Never upscale a photo. Before rendering, compute each photo's scale per placement and crop: the
41
+ full-bleed cover scale is `max(W/w, H/h)` for a placement of W x H and a photo of w x h. Placements
42
+ are 9:16 (1080x1920), 4:5 (1080x1350) and 1:1 (1080x1080). For a MOTION also multiply by the video
43
+ zoom (up to 1.12).
44
+
45
+ - A 1200x1200 photo full-bleed at 9:16 uses 675x1200 source pixels for 1080x1920: 1.6x.
46
+ - A 1024x1536 photo at 9:16 is 1.25x. A 1440x2560 one is 0.75x, and 0.84x with the 1.12 zoom.
47
+ - `bleed` is full-bleed on every placement. Refuse any full-bleed use above 1.0x, and compute the
48
+ scale for the photo's actual crop in `card`, `split` and `stacked` too.
49
+
50
+ Fixes, in order:
51
+
52
+ 1. Generate at the largest size in that placement's aspect (`aspect: "9:16"` for 9:16;
53
+ `placementFit` in the result shows the scale per placement).
54
+ 2. Use a different photo.
55
+ 3. Use a layout that shows the photo framed at or below native size.
56
+
57
+ A photo above 1.0x is fixed before anything is shown, not mentioned.
58
+
38
59
  ## Logo
39
60
 
40
61
  `lockup: "chip"` puts the logo on a white pill. Use it when the photo behind the logo is busy.