@wji.ai/cli 0.5.0 → 0.5.1

package/README.md

@@ -290,6 +290,21 @@ upgrading the CLI so the skill matches the commands.
 pipeline (outline → characters → scenes/props → script → storyboard) whose
 stages are checked by `skill/short-drama/scripts/short-drama.mjs validate`,
 with the data stored as workspace datasets and the work laid out on canvases.
+
+`skill/ads/` and `skill/social-media/` are two more: `ads` makes commercials
+and ad creative (TVC / bumper / social ad formats and durations, product
+photography and studio lighting, visual styles, product identity across
+generations, banner sizes, AI-disclosure compliance); `social-media` holds
+every platform's image / video specs (Instagram, TikTok, YouTube, Facebook, X,
+LinkedIn, Pinterest, Threads, Snapchat, 小红书, 抖音, 快手, 视频号, B站, 微博,
+公众号) and the repurposing recipes — an episode into 9:16 teasers and posters,
+an ad master into every placement. Install them the same way:
+
+```bash
+cp -r "$(npm root -g)/@wji.ai/cli/skill/short-drama" ~/.claude/skills/short-drama
+cp -r "$(npm root -g)/@wji.ai/cli/skill/ads" ~/.claude/skills/ads
+cp -r "$(npm root -g)/@wji.ai/cli/skill/social-media" ~/.claude/skills/social-media
+```
 Install it the same way (`cp -r skill/short-drama ~/.claude/skills/short-drama`)
 next to `wji`; `node skill/short-drama/scripts/selftest.mjs` runs its self-test.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wji.ai/cli",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Command line interface for the WJI AI platform",
   "license": "UNLICENSED",
   "author": "WJI AI",

package/skill/ads/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: ads
+description: Make commercials and ad creative with AI on WJI through the `wji` CLI — video ads (TVC 15 / 30 / 60 s, 6-second bumpers, skippable and non-skippable pre-roll, 9–34 s social ads, product demos, UGC-style, testimonials, explainers) and ad images (product shots / 产品图, key visuals / 主视觉 KV, display banners), with studio lighting and product-photography vocabulary, visual styles by industry, second-by-second ad structure (hook in 3 s, brand by 5 s, CTA card), product identity locked across every generation, deliverables per placement and AI-disclosure compliance. Use whenever a task mentions an ad / 广告 / 廣告, a commercial, TVC, product shot, packshot, banner, key visual, promo / 宣传片 or brand video. Hands per-platform sizes to the social-media skill. Works together with the `wji` skill.
+---
+
+# Ads on WJI
+
+One brief, one canvas, one master. **You write the brief, the concept and every prompt**; the
+`wji` CLI keeps the brief as a dataset, lays the work out on a canvas and generates the stills
+and clips. Nothing is generated until the brief is complete and the user has said yes to the
+quote (or the message carried `-auto`, see the `wji` skill).
+
+```
+brief ──▶ concept & hooks ──▶ key visual / storyboard ──▶ stills ──▶ clips ──▶ master + deliverables
+  │            │                    │                        │          │            │
+ brief.md   3–5 hooks,           shot list with           product-   image-to-   ratio variants,
+ + story/   framework,           timecodes, one           locked     video,      overlays, end card
+ dataset    CTA & end card       master ratio             KV + keys  3–8 s each  → social-media skill
+```
+
+`{baseDir}` = this skill. Read `{baseDir}/reference/brief-template.md` before asking the user
+anything and `{baseDir}/reference/formats-video.md` or `formats-image.md` before proposing a format.
+The `wji` skill governs every CLI call (auth, confirmations, spending policy, model choice).
+
+| Read | When |
+| --- | --- |
+| `reference/brief-template.md` | before the first question — the fields, and what a complete brief looks like |
+| `reference/formats-video.md` | choosing a video format, its length and second-by-second structure; cutting the ad into clips |
+| `reference/formats-image.md` | a KV, packshot or banner: IAB / Google / Meta sizes, text limits, generate-then-crop |
+| `reference/product-photography.md` | writing any product still: lighting setups, shot types, backgrounds, lens, grade, the prompt template |
+| `reference/styles.md` | picking the look — 13 styles with signifiers and prompt phrases, by industry |
+| `reference/ai-consistency.md` | before generating: how the product stays the same across stills and clips, what never to generate |
+| `reference/models.md` | which WJI model for which need (ratios, resolutions, references, text in image, transparent background) |
+| `reference/compliance.md` | before delivery: AI-content labels per platform / jurisdiction, misleading-depiction rules |
+
+## Operations
+
+### Where the brief lives
+
+Locally: an `ads/<product>/` folder with `brief.md` (the brief, concept, shot list and
+deliverables — one file, sections in that order) and `prompts/` (one text file per still and
+clip, so `--prompt-file` can send them verbatim). On WJI: the same brief as a dataset in the
+workspace's **story** folder, so the canvas and the chat see it.
+
+```bash
+wji auth whoami --json && wji profile wallet            # preflight; an ad is a handful of stills + 4–8 clips
+wji ws use <workspaceId>                                 # or wji ws create "<product> ads" -r 16:9
+wji ws app list                                          # the Dataset app id → DS_APP
+wji --json ws fs --app DS_APP | jq -r '.. | objects | select(.content.semanticKey? == "story") | .id'   # → STORY
+wji dataset new STORY "AD <product>" -t other -d "<one line>" --json | jq -r .id                       # → BRIEF
+wji fs set BRIEF --merge content=@ads/<product>/brief.md --merge viewMode=content                      # the brief text
+wji asset upload ads/<product>/packshot.png              # the user's product photo → PACK asset id
+wji models get <model>                                   # confirm ratios and the reference cap before promising a size
+```
+
+### The canvas
+
+One canvas per ad, `AD · <product>`, rows top to bottom:
+
+| Row | Nodes | Command |
+| --- | --- | --- |
+| 1 references | the packshots and brand assets | `wji canvas add image -c CV -n "packshot" --asset PACK --at 0,0` (display nodes) |
+| 2 key visuals | one image node per style / hook variant | `wji canvas add image -c CV -n "KV minimal" --from P1 -m <image model> -r 1:1 --resolution 2K --prompt-file prompts/kv-minimal.txt --at 0,400` — the packshot node is always **first** in `--from` (`@image1`) |
+| 3 storyboard stills | one per clip, in order | same, `--from P1 KV1` so light and grade carry over |
+| 4 clips | one video node per still | `wji canvas add video -c CV -n "clip 01" --from S1 P1 -m <video model> -r 16:9 -d 5 --prompt-file prompts/clip-01.txt` |
+| 5 copy | headline / CTA / legal lines | `wji canvas add text -c CV --text-file ads/<product>/overlays.md --plain` beside the clip they belong to — overlays are added in the edit, **never generated into the picture** |
+
+`--from` order sets `@imageN`; `wji canvas connect <from> <to>` adds a reference later. Quote
+first — `wji canvas gen <nodeIds…>` prints the cost and refuses — tell the user, then
+`wji canvas gen <nodeIds…> --yes --wait` after the yes. `wji canvas set <node> -p … / -r … / -d …`
+changes a node without rebuilding it; `wji canvas get <node> --json | jq -r .assetId` then
+`wji asset download <asset> -o /tmp/ad` to look at a result before approving it.
+
+For a one-off still with no canvas: `wji gen image -m <model> -p "…" -r 1:1 --ref PACK --wait`
+— it still needs the user's yes first unless the message carried `-auto`.
+
+Take ids from the command's own JSON (`wji --json canvas add … | jq -r .id`), never by searching
+names. Ratio, resolution and duration are validated against the model — copy the spelling from
+`wji models get`.
+
+## Before anything else
+
+1. **Read the brief template**, then **ask for what is missing in one message**: product (and a
+   packshot or product photo — without one the product cannot be kept consistent), audience,
+   objective (awareness / conversion / retargeting), format and length, placements and their
+   ratios, style, brand colours (hex), must-show / must-say, CTA, legal lines, whether the ad
+   will run where AI content must be labelled. Offer defaults where the user has none
+   (`reference/formats-video.md` §"Formats at a glance", `reference/styles.md` §"Choosing by industry"), but
+   **do not generate anything without the product reference and the placement**.
+2. **Write `brief.md`** and push it as the `AD <product>` dataset. Everything later reads from it.
+3. **Confirm the master ratio**: 16:9 when the primary placement is YouTube / TV / display,
+   9:16 when it is Reels / TikTok / Shorts / 抖音, 1:1 or 4:5 for feed-only. One master; the
+   other ratios are made later (stills regenerated or cropped, video regenerated — see
+   `reference/formats-image.md` §"Generate, then crop" and the social-media skill).
+4. **Check the wallet and quote** (`wji gen cost`) before every generation; say what the whole
+   plan will cost before starting row 2.
+
+## Stage 1 — Concept
+
+- Pick the framework (`reference/formats-video.md`): AIDA for cold audiences and launches, PAS
+  for retargeting, ABCD as the checklist for anything on YouTube. Write **3–5 hooks** (first
+  3 seconds), pick one with the user, keep the others as A/B variants.
+- Write the **shot list with timecodes**: hook 0–3 s, product in frame by 3 s, brand by 5 s,
+  proof / demo, CTA card in the last 2–5 s. Sound-off first: every beat must read with captions
+  and no audio.
+- Cut the ad into **clips of 3–8 s**, each one generation, sized to the video model
+  (`reference/models.md`: h3 5–15 s fixed, seedance-2.5 4–30 s auto, wan 2–30 s, veo 4–8 s,
+  kling 3–15 s). A 15-s vertical ad is typically 3 clips + end card; a 30-s TVC 5–7 clips.
+- For an **image-only** job (KV, banner set, packshot variants) the concept is the layout: where
+  the product sits, where the headline zone stays clear, which sizes are needed
+  (`reference/formats-image.md`).
+- Put the concept into `brief.md` (`## Concept`, `## Shot list`, `## Deliverables`) and
+  `wji fs set BRIEF --merge content=@ads/<product>/brief.md`.
+
+## Stage 2 — Key visual and stills
+
+- Build row 1 (packshots, brand refs) and row 2 (one KV per style variant, 2–3 at most). Every
+  prompt follows `reference/product-photography.md` §"The prompt template": subject → shot → lighting
+  → background → camera → grade → constraints, and ends with the identity line from
+  `reference/ai-consistency.md` ("keep the label, shape and colour of @image1 exactly …").
+- Pick the model by need (`reference/models.md`): legible text in the picture → nano-banana-pro /
+  gpt-image-2.5 / seedream-5-pro; transparent background for a logo or cut-out → gpt-image-2.5
+  with `--set background=transparent`; 4:5 or 2:3 placements → nano-banana / flux-2-flex /
+  seedream-5; a marketing look out of the box → marketing-studio-image. Default
+  `--resolution 2K` for a KV, `1K` while exploring.
+- **Never generate** legal text, small print, prices that must be exact, or a real logo — those
+  are text nodes and overlays. Headline text may be generated only to preview a layout.
+- Download and look at the KVs, show the user, take the pick, then generate row 3 (storyboard
+  stills) `--from P1 KV1` so light direction, grade and lens stay the same across the ad.
+- Quality pass before any clip: hands on the product, label text, logo drift, product proportions,
+  impossible physics (`reference/ai-consistency.md` §"Artefact checklist"). Regenerate a still
+  rather than trying to fix it in the clip.
+
+## Stage 3 — Clips
+
+- One video node per approved still, `--from S1 P1`, `-d` from the shot list (whole seconds),
+  master `-r`. Prompts describe **motion and camera only** — the look is already in the still;
+  repeat the product-identity line.
+- Product in frame for the whole clip unless the shot list says otherwise; no text in the video
+  prompt (captions and CTA are overlays).
+- Voice-over and music: `wji canvas add audio -c CV -m seed-audio-1.0 --prompt-file prompts/vo.txt`
+  when the user wants a VO bed; the script lines come from the brief's must-say.
+- Quote the whole row, generate after the yes, download and review every clip against the still
+  it came from (same product, same light), regenerate the ones that drift.
+
+## Stage 4 — Master and deliverables
+
+- The master is the clip sequence + overlay text in order; assembling the cut, captions and
+  overlays happens in the user's editor (or locally with ffmpeg when it is installed and the user
+  asks) — list the timeline explicitly (clip → seconds → overlay text) in `## Deliverables`.
+- **Other ratios**: stills are regenerated at the placement ratio (or cropped when the ratio is
+  not native, `reference/formats-image.md`), video is **regenerated** at the placement ratio
+  from the same stills — never cropped. When the social-media skill is installed, hand it the
+  brief and the canvas; it owns the per-platform spec sheet. Otherwise list the sizes yourself
+  from `reference/formats-image.md`.
+- **Compliance** (`reference/compliance.md`): say whether the ad needs an AI-content label on
+  each placement, and never depict a result the product cannot deliver.
+
+## Reporting
+
+After each stage: what is on the canvas (row, node names), what was spent, what the user must
+decide next (pick a KV, approve the shot list, approve a clip). After delivery: the deliverables
+table (file, ratio, duration, overlay text, label needed) and the A/B variants still unbuilt.
+
+## Rules specific to this skill
+
+- **Ask before every generation**, even one image (the `wji` skill's spending policy is the
+  floor; this skill asks for images too, because an ad's stills are its most expensive mistakes).
+- **The packshot is `@image1` in every generation** — stills and clips. No packshot, no
+  generation; ask for one or generate a packshot first and have the user approve it.
+- One master ratio per ad; variants are separate rows, never reframes of the master.
+- Text, prices, legal lines and logos are overlays, never generated pixels.
+- Do not invent platform limits or sizes — cite the row in `reference/formats-video.md` /
+  `reference/formats-image.md`; rows marked *(verify)* are said as such.
+- All-audiences content only, no real people's likeness without the user's confirmation that they have the
+  rights, no competitor products in frame.

package/skill/ads/reference/ai-consistency.md

@@ -0,0 +1,109 @@
+# Product identity across AI generations
+
+How to make the same product appear in every still and clip of a campaign: which image is the
+reference, what the prompt must say, what must never be generated, how to check the output, and
+how stills and clips stay continuous. Model reference caps and text strengths are in
+`reference/models.md`; the shot vocabulary in `reference/product-photography.md`.
+
+## The identity rule
+
+1. **One approved packshot is the identity.** Photographed or generated once on a clean
+   background (transparent where possible), label to camera, approved by the client. It is the
+   first reference (`@image1`) of every later generation: KV, variant, still, clip.
+2. **Say it in words as well.** Every prompt carries the clause: *"keep the label, shape and
+   colour exactly as @image1"* (or the model's own phrasing: "while maintaining the product
+   exactly as in the reference"). References anchor the look; the clause stops drift.
+3. **Additional references come after the product.** Set, props, a hand model, a colour swatch:
+   `@image2` onward. Name each in the prompt ("the bottle from @image1 on the tray from @image2").
+   Do not exceed the model's cap; if a scene needs more, generate the set first and use that
+   result as one reference.
+4. **Edit, do not regenerate, once approved.** A background swap or a colour change on an
+   approved KV goes through an edit-style model with the KV as `@image1`, so the product pixels
+   are carried over rather than re-imagined.
+5. **A second product angle is a second packshot.** If the ad shows the back label or the cap
+   open, generate and approve that view once, then reference it; do not ask a scene generation to
+   invent the back of the pack.
+
+## What never to generate
+
+| Never in the picture | Because | Do instead |
+| --- | --- | --- |
+| Legal text, small print, ingredients, warnings, prices, terms | garbled letters, wrong numbers; a legal exposure | overlay the approved text in the edit |
+| The real logo re-drawn by the model | logo drift: wrong kerning, weight, colour | keep the supplied logo file; place it as an overlay; on a packshot rely on `@image1` and check every output |
+| Awards, certifications, seals, star ratings | fabricated endorsement | overlay only what the client can prove |
+| Competitor packs, real people who did not consent, other brands' marks | rights and comparison-advertising rules | describe generic "other bottles, unbranded" |
+| Screens with readable UI, QR codes, phone numbers | unreadable or wrong | overlay a real screenshot or code |
+| Before / after results the product cannot deliver | a misleading depiction, see `reference/compliance.md` | show use and feel, not fabricated results |
+
+Headlines generated in-frame are allowed as a **layout draft** only; the approved copy is
+overlaid afterwards.
+
+## Artefact checklist (每張都查)
+
+Check every output before it becomes a reference or a deliverable:
+
+- Label: every word spelt as on the packshot; no extra characters; no mirrored text.
+- Shape: proportions, cap, neck, corners, count of segments (a 6-pack is six).
+- Colour: brand colours against the hex in the brief; the product not tinted by the grade.
+- Logo: placement, size and colour identical to the reference; no second logo.
+- Hands: five fingers, natural grip, the hand does not merge with the pack.
+- Physics: liquid level, condensation, reflections and shadows consistent with the light
+  direction; the product does not float unless the shot is "floating".
+- Impossible behaviour: the pack does not open where it cannot, pour from the wrong end, change
+  size between frames.
+- Background: no stray objects, no invented brand names on props, no text in the set.
+- Crop margin: 10 % around the product so the placement crops never cut it.
+- For video: the label stays readable through the move; no morphing in the last second; the
+  product enters and exits the way the still implies.
+
+One failed line means regenerate or edit; a "nearly right" pack is the most expensive thing to
+ship.
+
+## A/B variant discipline (變體只改一處)
+
+A variant tests one thing. Change exactly one of: the hook (first 3 s or the KV's concept), the
+headline, the CTA, the background / setting, the model of person, the colour way, the music.
+Everything else, including the seed of the stills where the model exposes one, stays the same.
+Label variants by what changed ("hook B: condensation macro") so results can be read. Three
+hook variants and one CTA variant is a normal first round; ten variants that each change three
+things teach nothing.
+
+## Keyframe → clip continuity
+
+A clip is generated from an approved still (the keyframe) with the packshot as reference, so the
+still, not the prompt, carries the product. Keep these constant within a scene:
+
+| Keep the same | How |
+| --- | --- |
+| Light direction and quality | the same lighting clause in the still prompt and the clip prompt ("soft key from upper left, rim from behind") |
+| Lens and height | the same camera clause; a 35 mm still cannot become an 85 mm clip |
+| Seed, where the model has one | reuse the still's seed for sibling stills of the same scene (wan-3.0 and seedance expose `seed`) |
+| Product state | lid on / off, liquid level, condensation: the still fixes it; the clip prompt repeats it |
+| Palette and grade | the grade clause verbatim |
+| The end state | for first-and-last-frame models, the end still is generated from the start still with the same references |
+
+Write the clip prompt as *motion only*: what moves, how fast, where the camera goes. Do not
+re-describe the scene the still already shows, and never ask for a second beat ("then it cuts
+to…"): one clip, one action, one camera idea.
+
+## How many stills per clip
+
+| Clip | Stills to approve first | Why |
+| --- | --- | --- |
+| Product static, camera moves (push, orbit, turntable) | 1 (start) | the model only has to move the camera |
+| Product handled, poured, opened | 2 (start and end state) | first-and-last-frame generation locks both states; the pack cannot drift in between |
+| Person + product, action beat | 2 | the end frame stops hands and pack morphing |
+| Before / after in one clip | 2, and a reference of each state | the change is the story; both ends must be approved |
+| Hook macro (condensation, splash) | 1, plus 1–2 texture references | the reference carries the surface detail |
+| End card | 0; it is an image with overlay text | never a clip |
+
+A 30 s ad of five clips therefore needs roughly 6–9 approved stills before the first clip is
+generated. Approve stills in one pass, then generate clips in one pass; interleaving them is how
+a campaign ends up with three slightly different bottles.
+
+## Cross-ratio versions
+
+A second ratio (9:16 from a 16:9 master) is a regeneration, not a crop: the same stills are
+regenerated at the new ratio with the packshot reference and a reframing clause ("product
+centred in the middle band, headline space above"), then the clips are regenerated from the new
+stills. Keep the same clip count, beats and seconds so the two versions cut to the same audio.

package/skill/ads/reference/brief-template.md

@@ -0,0 +1,103 @@
+# The ad brief — template and a filled example
+
+The brief (創意簡報) is the single document every generation is checked against: what the
+product is, who sees the ad, what it must do, in which sizes, in which style, with which words.
+Fill every field before generating anything; a missing field is a question to the client, not a
+guess. Formats are defined in `reference/formats-video.md` and `reference/formats-image.md`,
+styles in `reference/styles.md`, model choices in `reference/models.md`, disclosure in
+`reference/compliance.md`.
+
+## Fields
+
+| Field | What goes in it | Why it matters |
+| --- | --- | --- |
+| Product | name, variant, size, what it is in one sentence | the subject clause of every prompt |
+| Packshots | the approved product images (front; back / open if shown), file names or references | the identity reference `@image1`; see `reference/ai-consistency.md` |
+| Audience | who, where, what they already know, what they are doing when they see the ad | hook and framework choice |
+| Objective | awareness · consideration · conversion · retargeting, with the one metric | AIDA vs PAS; length; CTA strength |
+| Format and length | from the formats table: e.g. 15 s social ad, 30 s TVC, KV + banners | the timecode skeleton and clip count |
+| Placements and ratios | every surface, its ratio and pixel size | the master ratio and the crop / regeneration list |
+| Style | one of the 13 styles, with any reference mood words | every prompt's look clauses |
+| Brand colours | hex values for primary, secondary, background; type feeling (serif / sans) | palette clauses; overlay design |
+| Must show | product moments that have to be in the ad (the pour, the label, the app screen) | shot list |
+| Must say | the claim, the tagline, the offer, exact wording | overlay copy; substantiation check |
+| Must not | anything forbidden by the client (no ice, no competitor red, no children) | negative constraints in prompts |
+| CTA | the verb and the destination | end card; platform button |
+| Legal lines | small print, offer terms, age or health notices, exact text | overlays; never generated |
+| AI disclosure | which platforms and jurisdictions; whether a synthetic person or voice appears | labels and marks before publishing |
+| Talent and consent | real people, voices, creators involved; consent status | compliance |
+| Budget and credits | credit cap for generation, number of variants, deadline | how many stills and clips to plan |
+| Approval | who approves the packshot, the KV, the stills, the final | the gate before each generation round |
+
+## Template
+
+```
+AD BRIEF — <product>
+Product:            <name · variant · size · one-line description>
+Packshots:          <@image1 front · @image2 back / open · @image3 logo file>
+Audience:           <who · market · language · context of viewing>
+Objective:          <awareness | consideration | conversion | retargeting> — metric: <…>
+Format & length:    <format from formats-video.md / formats-image.md> — <seconds or sizes>
+Placements & ratios:<surface: ratio px> · <surface: ratio px> · …   master ratio: <16:9 | 9:16>
+Style:              <one of the 13> — mood words: <…>
+Brand colours:      primary #… · secondary #… · background #… · type: <serif | sans>
+Must show:          <…>
+Must say:           <claim> · <tagline> · <offer>
+Must not:           <…>
+CTA:                <verb> → <destination>
+Legal lines:        <exact text>
+AI disclosure:      <platforms · jurisdictions · synthetic person / voice: yes | no>
+Talent & consent:   <…>
+Budget & credits:   <credit cap> · <variants> · <deadline>
+Approval:           packshot <who> · KV <who> · stills <who> · final <who>
+```
+
+## Filled example — bottled oolong tea
+
+```
+AD BRIEF — 山青 冷泡烏龍 (Shanqing Cold-Brew Oolong) 500 ml
+Product:            Shanqing cold-brew oolong tea, 500 ml glass bottle, unsweetened, amber
+                    liquid, cream label with a dark-green mountain mark, dark-green cap.
+Packshots:          @image1 front packshot on transparent background (approved 2026-09-28)
+                    @image2 cap-off packshot · @image3 brand logo file (do not regenerate)
+Audience:           office workers 25–40 in Taiwan and Hong Kong, afternoon slump, scrolling
+                    Instagram / 抖音 on the phone; know oolong, do not know cold-brew.
+Objective:          conversion (7-Eleven and online shop) — metric: click-through to shop.
+Format & length:    15 s vertical social ad (PAS, hook in 3 s) + 1080×1080 key visual.
+Placements & ratios:Instagram Reels 9:16 1080×1920 · 抖音 9:16 1080×1920 · Instagram feed KV
+                    1:1 1080×1080 · Facebook link image 1.91:1 1200×628 (crop of a 16:9 KV)
+                    master ratio: 9:16
+Style:              Food, leaning Minimal — mood words: cold, clear, mountain air, 3 pm.
+Brand colours:      primary #1F4D3A (mountain green) · secondary #F3EEE2 (cream) ·
+                    background #0E1F1A (deep green-black) · type: serif headline, sans body
+Must show:          condensation on the bottle · the label readable · the first sip · the cap
+                    twisting open (sound-off: show the twist)
+Must say:           claim "冷泡 12 小時，零糖零卡" (cold-brewed 12 h, zero sugar zero calories)
+                    · tagline "把三點的下午冰一下" · offer none this round
+Must not:           no ice cubes in the bottle · no lemon · no hot tea steam · no children
+CTA:                "現在就冰一瓶" → shop page; Meta button: Shop Now
+Legal lines:        "每 100 ml 熱量 0 kcal。冷藏保存，開封後請盡快飲用。" (overlay, bottom
+                    band, ≥ 24 px at 1080 wide)
+AI disclosure:      Meta AI info label · 抖音 「AI生成」 visible mark + metadata; no synthetic
+                    person speaks; hand only, no face.
+Talent & consent:   none (hand model is AI-generated, no likeness); voice-over is a licensed
+                    human read, not a clone.
+Budget & credits:   cap 600 credits · 3 hook variants for the first 3 s, 1 CTA · final by 10-06
+Approval:           packshot: brand manager · KV: brand manager · stills: creative director ·
+                    final: brand manager + legal
+```
+
+### What the example produces
+
+| Step | Output | Parameters |
+| --- | --- | --- |
+| KV | 1:1 hero, bottle low-angle, backlit amber, condensation, dark green-black gradient, upper third empty | `nano-banana-pro`, ratio 1:1, resolution 2K, `@image1` packshot + `@image3` logo for placement only; headline overlaid after |
+| KV 16:9 | the same composition regenerated wide for the 1200×628 crop | same model, ratio 16:9, 2K |
+| Stills (9:16) | 1 hook macro · 1 desk "before" · 1 bottle lift (start) + 1 cap twist (end) · 1 first sip · end card is an overlay image | `nano-banana-pro` or `gpt-image-2.5`, ratio 9:16, 2K, `@image1` first, identity clause |
+| Clips | 4 clips of 3–4 s from the stills: 0–3 hook, 3–7 before, 7–11 twist (first + last frame), 11–14 sip; 14–15 end card | `seedance-2.5`, ratio 9:16, 720p, duration 4 (trim), `generate_audio` on for ambience; packshot referenced on the twist via the ref variant |
+| Variants | hook A condensation macro · hook B cap twist first · hook C the tired hand | one change each; same seeds, light, lens |
+| Overlays | claim (3–7 s), tagline (11–14 s), CTA + legal line on the end card, inside the 9:16 safe band | approved text, never generated |
+| Disclosure | Meta AI info label · 抖音 「AI生成」 mark | before publishing |
+
+Roughly 9 stills and 4–6 clips, quoted before the first generation and kept under the 600-credit
+cap; the social-media skill turns the master into the remaining placements.

package/skill/ads/reference/compliance.md

@@ -0,0 +1,66 @@
+# Compliance — AI disclosure, truthful depiction, testimonials
+
+What an AI-made ad must disclose, where, and what it must not claim, as of Sep 2026. Platform
+policies change and laws phase in; rows marked *(verify)* were inconsistent between sources
+and should be checked against the primary text before a campaign relies on them. This is a
+working checklist, not legal advice; the client's counsel signs off on the final ad.
+
+## AI-content disclosure by platform
+
+| Platform | What triggers disclosure | How it is done | Notes |
+| --- | --- | --- | --- |
+| YouTube | realistic altered or synthetic content: a real-looking person saying or doing something they did not, a real event or place altered, a realistic scene that did not happen | tick "altered or synthetic content" at upload; YouTube shows a label (more prominent on sensitive topics) | not needed for clearly unreal / animated / stylised content, beauty filters or a script; YouTube may auto-label; repeated non-disclosure is penalised |
+| Meta (Facebook / Instagram) | ads made or edited with Meta's own generative tools get an "AI info" label automatically (Feb 2025) | for other AI content: the "AI info" self-label; political / social-issue ads must disclose photorealistic AI people, events or audio | third-party AI-detection labelling from 1 Jun 2026 |
+| TikTok Ads Manager | realistic AI visuals, cloned voices, synthetic people, photoreal AI product renders | the "contains AI-generated content" toggle on the ad; organic posts use the AI-generated content label | C2PA content credentials auto-label AI uploads since Jan 2025 |
+| Google Ads (display / search) | election ads with synthetic people or events must carry a disclosure *(verify scope)*; other ads have no AI label and fall under the misrepresentation policy | the election-ad disclosure setting | |
+| 抖音 / 快手 / 小红书 / 视频号 / B站 / 微博 | any AI-generated or synthesised content | the platform's 「AI生成」 self-declaration at upload, plus the visible mark below | required by the 标识办法 |
+
+Practice: when in doubt, label. A label costs nothing; a removed ad and a penalised account
+cost the campaign.
+
+## Jurisdictions
+
+| Jurisdiction | Rule | In force | What it requires of an ad |
+| --- | --- | --- | --- |
+| China (mainland) | 《人工智能生成合成内容标识办法》 (Measures for Labelling AI-Generated and Synthetic Content) | 2025-09-01 | **explicit** label: a visible 「AI生成」 / 「人工智能生成」 mark on images and video (start, end or throughout, legible), and audible or text notice on audio; **implicit** label: metadata / watermark carrying producer and content identifiers; platforms must check and add their own; removing or hiding a label is prohibited |
+| European Union | AI Act Article 50 (transparency obligations) | 2026-08-02 *(verify: the "digital omnibus" may shift dates; existing systems referenced to 2026-12-02)* | deepfakes (AI images, audio or video resembling real people, places, events) must be disclosed as artificially generated or manipulated; generative outputs must carry machine-readable marking (metadata / watermark); a clearly artistic or satirical piece needs only a non-intrusive disclosure |
+| United States | FTC Act §5 and "Operation AI Comply" (2024–) | ongoing | no AI-specific label mandate, but AI does not soften the deception rules below; several states have deepfake-in-advertising and political-ad laws |
+| United Kingdom | ASA / CAP Code (practice reading, not researched for this file) | ongoing | ads must not mislead by omission; AI imagery of a product must show the product as sold |
+| Hong Kong / Taiwan / Singapore | general fair-trading and advertising law; platform rules apply (practice reading, not researched for this file) | ongoing | follow the platform label; disclose synthetic people |
+
+## Misleading depiction (FTC standard, applied globally as practice)
+
+- **Show the product as it is.** An AI packshot that thickens the cream, brightens the juice or
+  enlarges the screen is a misrepresentation. The packshot reference exists to prevent this.
+- **No fabricated results.** No before / after the product cannot deliver, no AI-invented "test
+  results", no synthetic "lab" imagery presented as evidence.
+- **No synthetic testimonials without disclosure.** An AI-generated person reading a review is
+  not a customer; it may only appear as an obviously fictional presenter, and never with a claim
+  like "real customer".
+- **Demonstrations must be real.** A demo clip generated by AI must depict something the product
+  does; the AI is the camera, not the proof.
+- **Claims need substantiation** before the ad is made: "clinically proven", "#1", "fastest" each
+  need a file the client holds.
+- **Comparisons** name no competitor's real mark unless the client accepts comparative-advertising
+  law in every market the ad reaches.
+
+## Testimonial and endorsement disclosure
+
+| Case | Requirement |
+| --- | --- |
+| Real customer, real words | keep the record (consent, the original review); typical results or a "results may vary" line where the result is not typical |
+| Real person, AI-generated voice or likeness | written consent for the synthetic use; label as AI on every platform that asks; never imply live footage |
+| Paid creator or influencer | a clear, visible #ad / #sponsored / 「廣告」 / 「合作」 disclosure at the start, not buried in tags |
+| Fictional presenter (AI person) | the presenter makes no first-person claims of having used the product as a customer; AI disclosure on |
+| Expert or professional | the person must hold the qualification; AI cannot dress a stand-in as a doctor |
+| Voice clone | explicit consent from the voice's owner, held on file; disclose where the platform asks |
+
+## Pre-flight checklist
+
+1. Product depicted exactly as sold (label, size, colour, contents) against the packshot.
+2. Every claim on screen or in voice-over has a substantiation file.
+3. No real person, voice or mark used without written consent; no competitor mark.
+4. AI disclosure set on every platform that asks, and the visible 「AI生成」 mark plus metadata
+   for any mainland-China placement; EU deepfake disclosure where a real-looking person appears.
+5. Testimonials are real and on file, or the presenter is clearly fictional and labelled.
+6. Legal lines, small print and prices are overlays of approved text, never generated.

package/skill/ads/reference/formats-image.md

@@ -0,0 +1,108 @@
+# Image ad formats — key visual, packshot, banner
+
+What each static deliverable is for, the exact pixel sizes the ad networks accept, the text and
+safe-zone rules that go with them, and how to get from a generated image (which only comes in
+model ratios) to those sizes by cropping. Lighting and shot vocabulary for making the source
+images is in `reference/product-photography.md`; the model ratios in `reference/models.md`.
+
+## The three deliverables
+
+| Deliverable | What it is | Typical ratio | Made how |
+| --- | --- | --- | --- |
+| Packshot (產品去背圖 / 產品照) | the product alone, clean, label to camera, on white or transparent; the identity reference for every other generation | 1:1, 4:5, or transparent 1:1 | photograph or generate once, approve, then reuse as `@image1` everywhere |
+| Key visual, KV (主視覺) | the campaign's one hero image: product + concept + headline zone; the source of every crop | 4:5 or 16:9 master, 1:1 secondary | generated from the packshot reference; text added as an overlay afterwards |
+| Banner / display asset | the KV re-composed into network sizes with headline, CTA and logo | fixed pixel sizes below | crop of the KV or a re-generation at the nearest ratio, then text overlay |
+
+Rule of thumb: one packshot, one to three KVs (one per hook or style), and every banner is
+derived from a KV, never generated from scratch, so the product looks identical across sizes.
+
+## IAB display sizes
+
+All ten fixed sizes of the IAB portfolio; the five marked ★ cover most inventory and are where a
+campaign starts. Google Display Network static files ≤ 150 KB.
+
+| Size (px) | Name | Ratio | Priority | Note |
+| --- | --- | --- | --- | --- |
+| 300×250 | Medium rectangle | 6:5 | ★ | most inventory; headline + product + button |
+| 728×90 | Leaderboard | ≈ 8:1 | ★ | product small at one end, headline the rest |
+| 300×600 | Half page | 1:2 | ★ | tall; product top, headline, CTA bottom |
+| 160×600 | Wide skyscraper | ≈ 1:4 | ★ | narrow; stacked product, two-word headline |
+| 320×50 | Mobile leaderboard | ≈ 6:1 | ★ | logo + 4 words + button; no product detail survives |
+| 320×100 | Large mobile banner | 3.2:1 | | as 320×50 with room for a product thumbnail |
+| 970×250 | Billboard | ≈ 4:1 | | a landscape KV crop with a headline |
+| 970×90 | Super leaderboard | ≈ 11:1 | | as 728×90 |
+| 336×280 | Large rectangle | 6:5 | | same composition as 300×250 |
+| 250×250 | Square | 1:1 | | small square; product + 2 words |
+
+## Google responsive display assets
+
+Upload assets; Google assembles them. Images must be sharp with the product centred, because any
+of them may be shown in any slot.
+
+| Asset | Ratio | Recommended | Minimum | Limit |
+| --- | --- | --- | --- | --- |
+| Landscape image | 1.91:1 | 1200×628 | 600×314 | ≤ 5120 KB; up to 15 images |
+| Square image | 1:1 | 1200×1200 | 300×300 | |
+| Logo (square) | 1:1 | 1200×1200 | 128×128 | optional but recommended |
+| Logo (landscape) | 4:1 | 1200×300 | 512×128 | transparent background preferred |
+| Headlines | — | up to 5 × 30 characters | | |
+| Long headline | — | 1 × 90 characters | | |
+| Descriptions | — | up to 5 × 90 characters | | |
+| Business name | — | 25 characters | | |
+
+Images with more than ≈ 20 % of their area as text are ranked down; put the words in the
+headline fields, not in the picture. A landscape and a square image are the minimum set.
+
+## Meta (Facebook / Instagram) ad sizes by placement
+
+| Placement | Ratio | Pixels | Notes |
+| --- | --- | --- | --- |
+| Feed (default) | 4:5 | 1080×1350 | tallest feed unit; also accepts 1:1 |
+| Carousel card | 1:1 | 1080×1080 | one ratio for every card |
+| Stories / Reels | 9:16 | 1080×1920 | safe zone: 14 % top, 20–35 % bottom, 6 % sides (unified Mar 2026) |
+| In-stream video | 16:9 | 1920×1080 | |
+| Right column / link | 1.91:1 | 1200×628 | same crop as the Google landscape asset |
+| Files | — | images ≤ 30 MB; video ≤ 4 GB; Reels ads ≤ 90 s *(verify)* | |
+
+The 20 % text rule was retired in 2020, but images under 20 % text still deliver better; keep
+headline and CTA in the ad's text fields and the image mostly picture. Never draw a fake button
+on the image: every Meta and Google placement renders its own CTA button, and a painted one
+looks like a mismatch and is rejected by some review passes.
+
+## CTA conventions
+
+| Platform | Button labels (choose from the platform's list) | Practice |
+| --- | --- | --- |
+| Meta | Shop Now · Learn More · Sign Up · Book Now · Get Offer · Download · Contact Us | one verb, matches the landing page |
+| Google | Learn More · Shop Now · Get Quote · Apply Now · Sign Up · Subscribe | the CTA text field, ≤ 10 characters in some units |
+| TikTok | Shop Now · Learn More · Download · Sign Up · Contact Us · Apply Now | the card's CTA and the burned CTA line say the same thing |
+| YouTube | Learn More · Shop Now · Sign Up (call-to-action extension) | the video's end card repeats it |
+
+On a static KV or end card the CTA is a *line of type* in the headline zone ("Try it cold."),
+not a rounded rectangle. Chinese-market placements (朋友圈, 抖音信息流) use the platform's own
+按鈕 with the same rule.
+
+## Generate, then crop
+
+No image model outputs 1200×628 or 728×90; generate at the nearest model ratio, then crop. Every
+row below is a ratio the platform's models accept (see `reference/models.md`). The crop principle: keep the product
+centre-weighted, keep the headline zone (usually the upper third, or the empty side) clear of
+product, and let background sweep, not product, be what the crop removes.
+
+| Target | Generate at | Crop | Composition rule |
+| --- | --- | --- | --- |
+| 1200×628, 1200×630 (1.91:1) | 16:9 | trim ≈ 6 % height (top and bottom) | product centre or right third; headline left |
+| 300×250, 336×280 (6:5) | 4:3 or 1:1 | 4:3 → trim sides; 1:1 → trim top / bottom | product centred, headline above |
+| 250×250, 1200×1200, 1080×1080 (1:1) | 1:1 | none | product dead centre |
+| 728×90, 970×90 (≈ 8:1 / 11:1) | 21:9 | keep a centre band ≈ 30 % of the height | product at one end, background sweep the rest |
+| 970×250 (≈ 4:1) | 21:9 | keep a centre band ≈ 60 % of the height | as above with room for a two-line headline |
+| 320×50, 320×100 | 21:9 | narrow band; or a logo + colour field instead of the KV | text-only unit |
+| 160×600, 300×600 (1:4, 1:2) | 9:16 | 300×600: trim ≈ 12 % width; 160×600: keep a centre column ≈ 15 % wide | product stacked vertically; headline top |
+| 1080×1350 (4:5) | 4:5 (nano-banana, flux-2-flex) | none; or 3:4 trimmed | |
+| 1080×1920 (9:16) | 9:16 | none | product inside the centre safe band |
+| 1200×300 logo (4:1) | transparent 1:1 (gpt-image-2.5 `background: transparent`) | place on a 4:1 transparent canvas, logo left | never regenerate a real logo; use the supplied file |
+
+Generate at 2K or 4K for anything that will be cropped hard (banners, 160×600): a 21:9 4K frame
+still leaves a sharp 970×250 after the band crop. Keep a 10 % margin around the product in
+every KV so a tighter crop never cuts the pack. Video is never cropped; see
+`reference/formats-video.md` for regenerating at the placement ratio.