@wji.ai/cli 0.4.0 → 0.5.1

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.

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

@@ -0,0 +1,121 @@
+# Video ad formats — length, structure and segment planning
+
+Which ad format to make, how long it is, what happens in every second, and how a finished length
+breaks into clips an AI video model can generate one at a time. Platform rules (a bumper over 6 s
+is rejected, a skippable ad is skippable at 5 s) are marked as such; everything else here is
+trade practice (廣告慣例), not a hard limit. Image deliverables are in `reference/formats-image.md`,
+the per-model duration and ratio facts in `reference/models.md`.
+
+## Formats at a glance
+
+| Format | Length | Master ratio | Structure | Rule or practice |
+| --- | --- | --- | --- | --- |
+| TVC (電視廣告) | 15 / 30 / 60 s | 16:9 (cut 9:16 / 1:1 for social) | hook → setup → product / solution → brand + CTA in the last 3–5 s | practice (broadcast clocks add slate / black; not covered here) |
+| YouTube bumper | ≤ 6 s, non-skippable | 16:9 | one idea; logo or product in frame throughout | platform: > 6 s is rejected |
+| YouTube non-skippable | ≤ 15 s (some markets 20 s *(verify)*) | 16:9 | hook → benefit → brand → CTA | platform cap |
+| YouTube skippable (TrueView) | any; 15 s – 3 min common | 16:9 | brand + hook **before the 5 s skip** → payoff → proof → end card | platform: skip button at 5 s |
+| Social feed / Reels / TikTok ad | 9–34 s (TikTok 21–34 s for conversion) | 9:16 | hook 0–3 s with product on screen, proof, CTA | practice; 63 % of top-CTR TikTok ads show the product in the first 3 s |
+| Product demo | 15–60 s | 16:9 or 9:16 | problem → product in use → 2–3 feature beats → result → CTA | practice |
+| UGC-style (素人風) | 15–45 s | 9:16 | selfie hook → problem → product in hand → before / after → casual CTA | practice; must look native to the feed |
+| Testimonial (見證) | 15–60 s | 9:16 or 16:9 | statement → problem → specific result → brand + CTA | real customers or disclosure, see `reference/compliance.md` |
+| Explainer | 60–120 s, with a 30 s cut | 16:9 | problem → "meet X" → 3 steps → benefit → CTA | practice |
+
+Meta Reels / Stories ads perform best at 15–30 s; a 6 s bumper and a 15 s non-skippable are the
+only formats where the platform, not the brief, fixes the length.
+
+## Timecode skeletons
+
+Seconds are the *latest* point each beat may land; a beat can come earlier, never later.
+
+| Format | 0–3 s | then | then | last seconds |
+| --- | --- | --- | --- | --- |
+| TVC 15 | hook, product visible | 3–8 setup / problem | 8–12 product as the answer | 12–15 brand lock-up + CTA |
+| TVC 30 | hook | 3–10 setup | 10–22 product / solution in 2–3 beats | 22–27 proof or payoff, 27–30 brand + CTA |
+| TVC 60 | hook | 3–15 story setup | 15–40 demonstration in 3–4 beats | 40–52 payoff, 52–60 brand line + CTA hold |
+| Bumper 6 | 0–1 product in frame | 1–5 the one idea | — | 5–6 logo lock; brand never leaves frame |
+| Non-skippable 15 | 0–2 hook | 2–7 benefit | 7–12 proof | 12–15 brand + CTA |
+| Skippable | 0–5 brand **and** hook before the skip | 5–15 payoff of the hook | 15–30 proof, features | end card 5–20 s before the end |
+| Social 9–34 | 0–3 hook + product | 3–10 problem or desire | 10–25 product in use, proof | CTA card 3 s, loop-friendly last frame |
+| Demo | 0–5 the problem, plainly | 5–10 product enters | 10–40 features, one per 5–8 s | result, CTA |
+| UGC | 0–3 selfie hook line | 3–8 problem | 8–20 product in hand | 20–35 before / after, casual CTA |
+| Testimonial | 0–3 the claim in the person's words | 3–12 what was wrong | 12–35 the specific result | brand + CTA |
+| Explainer 120 | 0–10 problem | 10–20 "meet X" | 20–75 three steps, 75–100 benefit | 100–120 CTA; the 30 s cut keeps problem, one step, CTA |
+
+A 9:16 social cut of a TVC is not a crop: it is regenerated from the same stills at 9:16 with
+the product re-centred (see `reference/ai-consistency.md`).
+
+## The three frameworks
+
+| Framework | Beats | Use when | Ad type |
+| --- | --- | --- | --- |
+| AIDA | Attention → Interest → Desire → Action | cold audience, new product, awareness | TVC, skippable, explainer |
+| PAS | Problem → Agitate → Solve | the audience already feels the pain; retargeting, conversion | social ad, UGC, demo |
+| ABCD (Google) | Attention, Branding early and often, Connection, Direction | any YouTube placement; ads following it showed ≈ 30 % higher short-term sales likelihood | bumper, non-skippable, skippable |
+
+The common hybrid is an AIDA hook (a striking image, a question) that drops into PAS at second
+3. Choose one and write the shot list in its beats, so every clip has a job.
+
+## Craft rules
+
+- **Hook in 3 s.** Motion, a face or the product itself in the first frame; no logo intro, no
+  fade-in from black on social. Start mid-action.
+- **Brand by 5 s.** Product, pack or name on screen before the skip point, and again at the end;
+  on a bumper it never leaves.
+- **Sound-off design.** Most feed viewing is muted: burn captions for every spoken line, put the
+  key claim in an overlay, let the picture carry the point. 40 % of the highest-VTR TikTok ads use
+  overlays. Design the audio (voice, music, a product sound) as a bonus layer, never the carrier.
+- **One idea per ad.** A 15 s spot holds one benefit; a 30 s spot one benefit and one proof.
+- **Loop-friendly ending** on social: the last frame can cut back to the first.
+- **CTA as a card, not a line.** The last 3 s (5 s on 60 s) is a still card: product, one line,
+  the CTA verb, the legal line. On placements with a native button the card repeats the same verb.
+
+### Safe zones for burned text (practice, from platform UI overlays)
+
+| Master | Keep clear | Put text |
+| --- | --- | --- |
+| 9:16 (Reels / Stories / TikTok) | top 14 %, bottom 20–35 %, 6 % each side (Meta, unified from Mar 2026); TikTok ≈ 108 px top / 320 px bottom / 60 px left / 120 px right on 1080×1920 | centre band, between 25 % and 65 % of the height |
+| 16:9 (YouTube, TV) | outer 10 % (title-safe); bottom 15 % where captions and the skip button sit; YouTube end screens occupy the last 5–20 s | centre and upper-centre; end-card elements in the last 5–20 s, ≤ 4 |
+| 1:1 / 4:5 (feed) | outer 5 %; the bottom strip where the caption starts | centre |
+
+Full per-platform safe zones belong to the social-media skill; these are the minimum for an ad
+master that will be re-used.
+
+## Segment planning — from a length to clips
+
+An AI ad is a chain of separately generated clips, each 3–8 s, cut together. Plan the clips
+before any generation:
+
+1. Pick the **master ratio** from the primary placement (16:9 for TVC / YouTube, 9:16 for
+   social). Every clip is generated at that one ratio; a second ratio is a second set of clips.
+2. Split the timecode skeleton into clips at beat boundaries. One clip = one beat = one camera
+   idea. A 30 s TVC is typically 5–7 clips; a 15 s social ad 3–4; a bumper 1–2.
+3. Size each clip to the model. What the models accept is in `reference/models.md`; for planning:
+
+| Model family | Plan clips of | Notes for ads |
+| --- | --- | --- |
+| minimax-h3 | 5–15 s | shortest clip is 5 s: plan beats of ≥ 5 s or trim in the edit |
+| seedance-2.5 | 4–30 s, or auto | can carry a whole 15 s social ad in one clip with audio; still better as 2–3 clips for control |
+| wan-3.0 | 2–30 s, or auto | the only family that goes to 2 s: good for bumper stings and cut-aways |
+| veo-3.1 | 4–8 s (8 s fixed with references) | 16:9 / 9:16 only; native audio |
+| kling-3 | 3–15 s | 16:9 / 9:16 / 1:1 |
+| happy-horse | 3–15 s | 5 ratios; 720p / 1080p |
+
+4. Generate **one clip per generation**, each from its approved still with the packshot as a
+   reference, and never ask one generation for two beats ("then it cuts to…"). Generate 1–2 s
+   longer than the beat and trim.
+5. The CTA card and any legal line are made as images (`reference/formats-image.md`) and laid
+   over in the edit; they are never generated inside the clip.
+
+Worked example, 30 s TVC for a bottled tea, 16:9, seedance-2.5:
+
+| Clip | Beat | Seconds | Content |
+| --- | --- | --- | --- |
+| 1 | hook | 0–4 | condensation bead sliding down the bottle, macro, cold backlight |
+| 2 | setup | 4–10 | office at 3 pm, a tired hand reaching past a coffee cup |
+| 3 | product | 10–16 | bottle lifted into a shaft of window light, label to camera |
+| 4 | solution | 16–22 | the first sip, shoulders drop, the room brightens |
+| 5 | proof | 22–27 | slow push on the pack; overlay: the one claim |
+| — | brand + CTA | 27–30 | still card: packshot, brand line, CTA, legal line |
+
+Five generations, one ratio; the card is an image. The 9:16 social version is the same five
+beats regenerated at 9:16 from the same stills, with clip 2 reframed on the hand.

package/skill/ads/reference/models.md

@@ -0,0 +1,90 @@
+# Models for ads — ratios, sizes, durations, references
+
+The image, video and audio models available on the platform (WJI) that matter for ad work, with the parameter values each
+one accepts, checked against the platform's model definitions (Sep 2026). `ratio`, `resolution`
+and `duration` are validated per model, so a placement plan must map onto a value in these
+tables; anything else (1.91:1, 6:7, banner strips) is generated at the nearest ratio and cropped
+(images, see `reference/formats-image.md`) or regenerated (video, see
+`reference/formats-video.md`). Text-in-image and transparency notes are the vendors' published
+strengths, not platform guarantees.
+
+## Image models
+
+| Model | Ratios | Resolution / size | Refs | Text in image | Special |
+| --- | --- | --- | --- | --- | --- |
+| `gpt-image-2` | auto · 1:1 · 4:3 · 3:4 · 16:9 · 9:16 | 1K · 2K · 4K; quality low / medium / high | 16 | strong, short headlines reliable | instruction-following edits |
+| `gpt-image-2.5` (sunburst / flare variants) | auto · 1:1 · 4:3 · 3:4 · 16:9 · 9:16 · **21:9** | auto · 1k · 1080p · 1440p · 4k (long edge ≤ 3840); quality auto → max | 16 | strong | `background: transparent` (PNG) for packshots and logos; flare = change only what is asked, keeps subject / composition / background |
+| `nano-banana` | auto · 1:1 · 2:3 · 3:2 · 3:4 · 4:3 · **4:5** · 5:4 · 9:16 · 16:9 · 21:9 · 9:21 | fixed (≈ 1K) | 8 | good | cheapest 4:5; batch up to 8 |
+| `nano-banana-pro` | same 12 ratios | 1K · 2K · 4K | 8 (fal variant 14) | strongest multilingual text; up to 6 object refs high-fidelity (vendor) | KV with headline drafted in-frame |
+| `nano-banana-2` / `-2-lite` | same 12 ratios (lite: no 9:21) | 0.5K · 1K · 2K · 4K (lite: 1K only) | 8 (fal variant 14) | good | fast iterations; lite for thumbnails of variants |
+| `bytedance-seedream-4.5` | match_input · 1:1 · 4:3 · 3:4 · 16:9 · 9:16 | 2K · 4K | 10 | good, 10+ languages (vendor) | sequential image generation: a numbered series from one prompt |
+| `seedream-5-lite` | + 3:2 · **2:3** · 21:9 | size 2K · 3K | 14 | good | largest ref count of the Seedream family |
+| `seedream-5-pro` | + 3:2 · **2:3** · 21:9 | size 1K · 2K; png / jpeg | 10 | good | `layer_decomposition`: subject split into layers (needs a reference); single output |
+| `flux-2-flex` | match_input · 1:1 · 16:9 · 3:2 · 2:3 · **4:5** · 5:4 · 9:16 · 3:4 · 4:3 | 0.5 · 1 · 2 · 4 MP | 10 | fair; short words | steps / guidance controls; second choice for 4:5 |
+| `marketing-studio-image` | auto · 1:1 · 3:2 · 2:3 · 4:3 · 3:4 · 16:9 · 9:16 · 21:9 | 1k · 2k · 4k | 8 | fair | tuned for a commercial "marketing" look; cheapest 4K |
+| `runninghub-midjourney-v7` | 1:1 · 4:3 · 3:2 · 16:9 · 3:4 · 2:3 · 9:16 | fixed; quality 1 / 2 / 4 | 5 image + 5 omni + 5 style, weighted | weak; do not rely on it for labels | mood boards, style frames; negative prompt |
+| `runninghub-midjourney-v8.1` / `v8.2` | same 7 | native 2K | 8.1: 5; 8.2: 2 (first = image ref, second = style ref) | weak | style exploration only; never the packshot |
+
+Bold ratios are the only sources of 4:5 and 2:3 on the platform. No image model outputs 1.91:1,
+6:7 or any banner strip.
+
+## Video models
+
+| Model | Ratios | Duration | Resolutions | Refs | Audio | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| `minimax-h3` | 21:9 · 16:9 · 4:3 · 1:1 · 3:4 · 9:16 | 5–15 s | 480P · 768P native; 2K · 4K upsampled | none (text only) | no | prompt expansion on by default |
+| `minimax-h3-i2v` | follows the input image | 5–15 s | as above | first / last frame | no | the keyframe route for h3 |
+| `minimax-h3-ref` | adaptive + the six | 5–15 s | as above | 9 images + 3 videos + 3 audios (≤ 12 total) | no | refer as Image 1 / Video 1 / Audio 1 |
+| `seedance-2.5` (first / last frame) | 21:9 · 16:9 · 4:3 · 1:1 · 3:4 · 9:16 | 4–30 s, or `autoDuration` | 480p · 720p · 1080p (Higgsfield route: 480p · 720p) | first / last frame only | `generate_audio` on by default | ratio follows the frames when given; mp4 / mov |
+| `seedance-2.5-ref` | same six | 4–30 s, or auto | as above | 30 images + 10 videos + 10 audios | `generate_audio` | task mode auto / edit / extend; edit and extend need a reference video |
+| `seedance-2.0` family | same six | 4–15 s, or auto | 480p · 720p · 1080p · 4k | ref variants: images + video + audio | `generate_audio` | the 4K option of the family |
+| `wan-3.0` / `-prime` | 16:9 · 4:3 · 1:1 · 3:4 · 9:16 | 2–30 s, or `autoDuration` | 480P · 720P · 1080P | first / last frame | `audio` on by default | optional "AI Generated" watermark; seed for repeatability |
+| `wan-3.0-ref` / `-prime-ref` | same five | 2–30 s, or auto | as above | 10 images + 5 videos + 5 audios (≤ 15 s total) | `audio` | |
+| `veo-3.1` / `-fast` | 16:9 · 9:16 · auto | 4–8 s | 720p · 1080p · 4k | first / last frame | `generate_audio` | negative prompt available |
+| `veo-3.1-ref` | 16:9 · 9:16 | 8 s fixed | 720p · 1080p · 4k | 1–10 images | `generate_audio` | |
+| `kling-3` / `-pro` | 16:9 · 9:16 · 1:1 | 3–15 s | model default | 7 images, plus first / last frame | `generate_audio` (off by default) | pro = higher quality |
+| `happy-horse` | 16:9 · 9:16 · 1:1 · 4:3 · 3:4 | 3–15 s | 720p · 1080p | 9 images, plus first frame | no | |
+
+## Audio
+
+| Model | Length | Refs | Use |
+| --- | --- | --- | --- |
+| `seed-audio-1.0` | ≤ 120 s | 1 image + up to 3 reference audios (≤ 30 s each) for voice cloning | voice-over, product sound beds, a jingle; mp3 / wav / pcm / ogg |
+
+Voice cloning needs the speaker's consent on file; see `reference/compliance.md`.
+
+## Pick by need
+
+- **Packshot on transparent background** → `gpt-image-2.5` with `background: transparent`, 1:1,
+  4k; the result becomes `@image1` for everything after.
+- **KV with a headline rendered in the picture** → `nano-banana-pro` (best text, especially
+  non-Latin scripts), then `gpt-image-2.5`, then `seedream-5-pro`. Still overlay the final,
+  approved copy afterwards; in-frame text is a layout draft.
+- **4:5 feed image** → `nano-banana` / `nano-banana-pro` / `nano-banana-2`, or `flux-2-flex`.
+- **2:3 (Pinterest, posters)** → `nano-banana` family, `seedream-5-lite` / `-pro`,
+  `marketing-studio-image`, Midjourney.
+- **21:9 for banner crops** → `gpt-image-2.5`, `nano-banana` family, `seedream-5`,
+  `marketing-studio-image`.
+- **Many references (product + props + set + model)** → `gpt-image-2` / `2.5` (16),
+  `seedream-5-lite` (14), `nano-banana-pro` (8, or 14 on the fal variant).
+- **Product layers for an animator** → `seedream-5-pro` with `layer_decomposition` on and the
+  packshot as reference.
+- **A cheap "commercial look" first pass** → `marketing-studio-image` at 1k, then re-generate
+  the chosen frame on a text-capable model.
+- **Exact edit of an approved KV (swap the background, keep the pack)** → `gpt-image-2.5` flare
+  variant with the KV as `@image1`.
+- **Video with native audio in one pass** → `seedance-2.5` (30 s cap), `veo-3.1` (8 s),
+  `wan-3.0`, `kling-3` with `generate_audio`.
+- **Clip from an approved still** → any first-frame model: `seedance-2.5`, `wan-3.0`,
+  `veo-3.1`, `kling-3`, `minimax-h3-i2v`, `happy-horse`; add the packshot as a reference on the
+  `-ref` variants when the product turns or is handled.
+- **First-and-last-frame clip (two approved stills)** → `seedance-2.5`, `wan-3.0`, `veo-3.1`,
+  `kling-3`, `minimax-h3-i2v`.
+- **1:1 video** → `seedance`, `wan-3.0`, `kling-3`, `happy-horse`, `minimax-h3`; not `veo-3.1`.
+- **21:9 cinematic video** → `seedance-2.5` / `2.0`, `minimax-h3`.
+- **Extending or editing an existing clip** → `seedance-2.5-ref` with task mode extend / edit.
+- **4K video** → `seedance-2.0`, `veo-3.1`, `minimax-h3` (upsampled).
+- **Voice-over or jingle** → `seed-audio-1.0`.
+
+Duration, resolution and reference counts above are the accepted ranges; cost scales with
+resolution and seconds, so quote the estimate before generating.

package/skill/ads/reference/product-photography.md

@@ -0,0 +1,119 @@
+# Product photography — lighting, shots, backgrounds, camera, grade
+
+The studio vocabulary (棚拍語彙) an image or video model understands, organised as the parts of
+a prompt: lighting setup, shot type, background, camera and lens, colour grade. Each row gives
+the look, what it is for, and the phrase to write. The style presets in `reference/styles.md`
+pick from these tables; `reference/ai-consistency.md` says how to keep the product identical
+between shots.
+
+## Lighting setups (布光)
+
+| Setup | Look | Use for | Prompt phrase |
+| --- | --- | --- | --- |
+| Three-point (三點光) | key from 45°, fill opposite at half power, back light on the edge; even, dimensional, "catalogue" | any product, safe default | `three-point studio lighting, soft key from upper left, gentle fill, thin rim light separating the product from the background` |
+| Large softbox (柔光箱) | wrap-around soft light, broad soft highlight, faint shadow; closer = softer | packaging, skincare, food, anything matte | `single large softbox close above and to the left, soft wrap-around light, one soft highlight, faint shadow` |
+| Rim / backlight (輪廓光 / 逆光) | bright edges, dark centre, glow through liquid | glass, bottles, dark products, anything translucent | `strong backlight through the bottle, glowing rim light on both edges, dark background, no front fill` |
+| Clamshell (蚌殼光) | key above, reflector below, nearly shadow-free, luminous | cosmetics, jewellery, beauty, faces | `clamshell beauty lighting, soft light from above and below, shadowless, dewy highlights` |
+| High-key (高調) | white background lit to pure white, few shadows, airy | pharmacy, tech accessories, e-commerce packshots | `high-key lighting, pure white seamless background, minimal shadow, bright and clean` |
+| Low-key (低調) | one key at 45°, deep shadow, product carved out of black; premium | spirits, watches, luxury, automotive | `low-key lighting, single hard key from the right, deep black shadows, product emerging from darkness` |
+| Hard light (硬光) | small source, crisp shadows, graphic, punchy | fashion, streetwear, retail-loud, editorial | `hard direct light, sharp-edged shadow cast on the wall, high contrast, graphic` |
+| Strip lights (條形光) | long thin highlights that follow the product's curve; gradient reflections | gloss and metal: cans, bottles, cars, phones | `two vertical strip lights either side, long gradient highlights along the glossy surface, controlled reflections` |
+
+Combine at most two (rim + softbox is the standard bottle setup). Name the *direction* and the
+*result on the product* ("soft highlight on the shoulder of the bottle"), not the equipment
+brand; the model renders results, not gear.
+
+## Shot types (景別 / 拍法)
+
+| Shot | What it shows | Use for | Prompt phrase |
+| --- | --- | --- | --- |
+| Packshot (產品照) | the product alone, label to camera, on white / neutral, eye-level, f/8–f/11 sharpness edge to edge | identity reference, e-commerce, end card | `clean product packshot, front label facing camera, centred, white seamless background, evenly lit, sharp throughout` |
+| Hero (主視覺照) | low angle, dramatic light, product as monument | KV, poster, TVC end frame | `hero shot from a low angle, product towering, dramatic rim light, dark gradient background` |
+| Lifestyle (情境照) | product in use in a real setting, natural light, shallow depth | social, feed, testimonial stills | `lifestyle photo, product held at a sunlit kitchen counter, window light, shallow depth of field, candid` |
+| Flat lay (平鋪) | top-down, product with props arranged on a surface | cosmetics, food, stationery, social | `flat lay, top-down view, product centred among a few props on linen, soft even light` |
+| Macro (微距) | texture, condensation, fabric weave, a logo emboss | hooks, cut-aways, quality proof | `extreme macro, 100 mm macro lens, condensation droplets on the label, shallow focus` |
+| In-hand (手持) | a hand holding or opening the product; scale and use | UGC, demo, app / device | `product held in one hand at chest height, natural skin, hand steady, label readable` |
+| Floating (懸浮) | product suspended, slight tilt, ingredients or parts orbiting | tech, beauty, food | `product floating in mid-air, slight tilt, soft shadow beneath, ingredients suspended around it` |
+| Splash / freeze (潑濺) | liquid frozen mid-air around the product | drinks, skincare, cleaning | `high-speed splash, liquid frozen mid-air around the bottle, backlit droplets, dark background` |
+| Knolling (整齊排列) | items laid out at right angles, grid-like | kits, sets, tools, fashion | `knolling arrangement, every item at right angles on a plain surface, top-down, even light` |
+| 360 turntable (轉台) | a video move: the product rotating a full turn on a plinth | demo clip, e-commerce spin | video prompt: `product on a turntable rotating slowly through 360 degrees, camera locked, studio light constant` |
+
+## Backgrounds (背景)
+
+| Background | Reads as | Phrase |
+| --- | --- | --- |
+| Seamless white / grey (無縫背景紙) | e-commerce, clean | `white seamless sweep` / `mid-grey seamless backdrop` |
+| Gradient | studio, premium | `smooth dark-to-charcoal gradient background` |
+| Brand-colour sweep | campaign, retail | `seamless backdrop in the brand colour #hex, no texture` |
+| Acrylic / reflective | tech, beauty, luxury | `product standing on black acrylic with a soft mirror reflection` |
+| Podium / plinth (展台) | luxury, skincare | `on a round stone podium, one step, soft shadow` |
+| Textured natural | food, wellness, craft | `on rough slate` / `on washed linen` / `at the edge of still water` |
+| Environment | lifestyle | name the room, the time of day and the light source |
+
+## Camera and lens language
+
+| Choice | Effect | Phrase |
+| --- | --- | --- |
+| 85 mm | compression, flattering, no distortion; the packshot lens | `85 mm lens` |
+| 100 mm macro | detail and texture | `100 mm macro lens` |
+| 35 mm | environment visible, lifestyle | `35 mm lens, environment in frame` |
+| 16–24 mm | interiors, real estate; keep verticals straight | `24 mm lens, verticals corrected` |
+| f/8–f/11 | packshot sharpness, every letter readable | `f/11, sharp front to back` |
+| f/2.8 or wider | lifestyle, isolates the product | `f/2.8, background softly out of focus` |
+| Eye level | neutral, catalogue | `eye-level camera` |
+| 45° down | shows the top and the front; food, flat objects | `camera at 45 degrees looking down` |
+| Low hero | authority, scale | `low-angle camera, slightly below the product base` |
+
+## Colour-grading vocabulary (調色)
+
+| Grade | Reads as | Phrase |
+| --- | --- | --- |
+| Clean neutral | true product colour, e-commerce | `neutral colour balance, accurate product colours, no colour cast` |
+| Warm golden | comfort, food, lifestyle | `warm golden grade, soft highlights` |
+| Teal-orange | cinematic, tech, automotive | `teal and orange cinematic grade` |
+| High-contrast editorial | fashion, retail-loud | `high-contrast editorial grade, deep blacks, crisp whites` |
+| Pastel matte | beauty, wellness, festive | `pastel matte grade, lifted blacks, soft saturation` |
+| Desaturated luxury | spirits, watches, premium | `desaturated luxury grade, muted tones, rich blacks` |
+
+Always end the grade line with the product exception: "product colours stay exact".
+
+## The prompt template
+
+Write in this order; each slot is one clause. Skip a slot only when the reference image already
+fixes it.
+
+```
+[subject: product, exact state, label to camera] →
+[shot type] → [lighting setup, direction, result on the product] →
+[background] → [camera: lens, aperture, height] → [grade] →
+[constraints: keep label / shape / colour exactly as @image1; no text; no extra objects]
+```
+
+### Worked examples
+
+**Bottled oolong tea** (packshot reference `@image1`, KV at 4:5, 2K)
+
+`A chilled glass bottle of oolong tea exactly as in @image1, label facing camera, beads of
+condensation on the glass. Hero shot from a slightly low angle. Strong backlight glowing through
+the amber tea, thin rim light on both edges, one small soft highlight on the shoulder. Dark
+teal-to-black gradient background, faint mist at the base. 85 mm lens, f/8, product sharp
+throughout. Cool clean grade with the tea's amber kept exact. Keep the label text, bottle shape
+and cap colour exactly as the reference; no added text; nothing else in frame; upper third
+empty for a headline.`
+
+**Trail sneaker** (packshot `@image1`, lifestyle still at 16:9)
+
+`The sneaker exactly as in @image1, worn on a right foot mid-stride on wet asphalt at dusk.
+Low-angle lifestyle shot, 35 mm lens, f/2.8, the shoe sharp and the street softly blurred.
+Hard low sun from behind the shoe as rim light, cool ambient fill, small splash of water from
+the heel frozen mid-air. Teal and orange cinematic grade; the shoe's colours and logo placement
+stay exact. No text, no other people in focus.`
+
+**Skincare jar** (packshot `@image1`, KV at 1:1, 2K)
+
+`The cream jar exactly as in @image1 on a round pale-stone podium, lid off and leaning against
+the jar, a smooth swirl of cream visible. Clamshell beauty lighting, soft light from above and
+below, nearly shadowless, dewy highlights on the glass. Warm off-white seamless background with
+a single soft petal-pink shadow. 85 mm lens, f/11, eye-level. Pastel matte grade, jar and label
+colours exact. Keep the label, jar shape and lid finish exactly as the reference; no text; no
+hands.`

package/skill/ads/reference/styles.md

@@ -0,0 +1,70 @@
+# Visual styles — 13 looks for ads
+
+One style per campaign, chosen from the brief's industry and tone and written into every prompt
+so the KV, the stills and the clips agree. Each row names the visual signifiers, the lighting
+preset it borrows from `reference/product-photography.md`, the phrases to write, and the tone
+of the CTA that fits. Nothing here names a real brand's look; describe the style, never a
+competitor's ad.
+
+## The styles
+
+| Style | Visual signifiers | Light preset | Prompt phrases | CTA tone |
+| --- | --- | --- | --- | --- |
+| Minimal (極簡) | negative space, one product, neutral sweep, thin type, nothing moves fast | large softbox or high-key | `minimal composition, generous negative space, single product, neutral seamless background, soft shadow, quiet` | short, lower-case, one verb: "Try it." |
+| Luxury (奢華) | low-key black, jewel tones, marble or dark stone, gold accents, serif type, slow motion | low-key + rim | `low-key luxury lighting, black gradient, marble surface, gold rim highlights, rich shadows, slow deliberate camera` | restrained, no discount: "Discover the collection" |
+| Retail-loud (促銷) | saturated brand colours, big percentage type, bursts and badges, hard light, fast cuts | hard light | `bold saturated brand colour background, hard direct light, punchy contrast, high energy, graphic` | urgent, numeric: "40 % off. Ends Sunday." |
+| Lifestyle (生活感) | real rooms and streets, window or golden-hour light, candid people, hands, imperfect framing | softbox window light (natural) | `lifestyle photo, natural window light, candid moment, shallow depth of field, warm and lived-in` | conversational: "Made for mornings like this" |
+| Tech (科技) | dark background, neon edge light, glass and brushed metal, particles, HUD lines, orbiting camera | strip lights + low-key | `dark studio, cyan and magenta edge lighting, glass and brushed metal, floating particles, slow orbit camera` | precise, feature-led: "Meet the new X" |
+| Food (食品) | warm backlight, steam, drips, glistening surfaces, macro, shallow depth, wood and linen | rim / backlight + softbox | `warm backlit food shot, rising steam, glossy surface, macro detail, shallow focus, wooden table` | appetite verbs: "Taste it hot" |
+| Beauty (美妝) | clamshell light, dewy skin, water droplets, product swatches, pastel and skin-tone palette | clamshell | `clamshell beauty lighting, dewy luminous skin, water droplets, soft pastel palette, swatch of the product texture` | promise-led, gentle: "Glow by morning" |
+| Fashion (時裝) | editorial pose, hard flash, colour block, fabric in motion, off-centre crop | hard light | `editorial fashion shot, hard on-camera flash look, colour-block background, fabric mid-motion, bold crop` | terse, imperative: "Wear it now" |
+| Automotive (汽車) | wet asphalt, dusk or tunnel light, long strip reflections down the body, low tracking camera | strip lights + low-key | `car on wet asphalt at dusk, tunnel light streaks along the bodywork, low tracking camera, cinematic teal-orange` | aspirational, one line: "Drive further" |
+| Real estate (房地產) | 16–24 mm interiors, verticals corrected, HDR balance of window and room, twilight exteriors | high-key interior, natural | `wide 24 mm interior, verticals straight, balanced window and room exposure, twilight exterior with warm windows` | invitation: "Book a viewing" |
+| App / SaaS (應用 / 軟體) | device mockups, cursor and tap animation, brand gradient, kinetic type, flat clean UI | high-key or gradient sweep | `phone mockup floating on a brand gradient, clean UI on screen, soft shadow, kinetic typography space around it` | outcome + free: "Start free" |
+| Festive (節慶) | seasonal props, warm bokeh lights, gold and red or snow and blue, wrapped gifts | softbox + warm practicals | `festive scene, warm bokeh string lights, seasonal props, gift wrapping, cosy warm grade` | gifting: "Gift the good stuff" |
+| Black Friday (黑五) | black background, neon or acid accents, glitch and scan lines, countdown numerals, bold percentage type | hard light + neon rim | `black background, neon accent rim light, glitch texture, bold oversized sale typography space, high contrast` | countdown, urgency: "24 hours. 50 % off." |
+
+## Choosing by industry
+
+| Industry | First choice | Second choice | Avoid |
+| --- | --- | --- | --- |
+| Beverage, snacks | Food | Lifestyle, Retail-loud | Luxury unless premium spirits |
+| Skincare, cosmetics | Beauty | Minimal, Luxury | Retail-loud (cheapens the product) |
+| Fashion, footwear | Fashion | Lifestyle, Minimal | Tech |
+| Consumer electronics | Tech | Minimal | Food, Festive |
+| Software, apps | App / SaaS | Minimal | Luxury |
+| Cars, e-bikes | Automotive | Tech | Retail-loud except clearance |
+| Property | Real estate | Luxury (high-end) | Everything else |
+| Jewellery, watches, spirits | Luxury | Minimal | Lifestyle unless aspirational |
+| Supermarket, e-commerce promo | Retail-loud | Black Friday (seasonal) | Minimal |
+| Seasonal campaign, any category | Festive | the category's first choice | — |
+| Home, furniture, wellness | Lifestyle | Minimal | Tech |
+
+## Style in motion (video clips)
+
+The same style decides how the camera and the cut behave; write the motion clause of a clip
+prompt from this table and keep it constant through the ad.
+
+| Style | Camera | Cut rhythm | Motion phrases |
+| --- | --- | --- | --- |
+| Minimal, Luxury, Beauty | slow push or slow orbit, locked horizon | 4–8 s per clip | `slow push in`, `slow orbit`, `camera locked, only the light moves` |
+| Retail-loud, Black Friday, Fashion | whip pans, snap zooms, hard cuts | 1–3 s per clip | `fast whip pan`, `snap zoom onto the product`, `hard cut` |
+| Lifestyle, Food, Festive | handheld drift, rack focus, natural pace | 3–5 s | `gentle handheld drift`, `rack focus from the hand to the product` |
+| Tech, Automotive | orbit, low tracking, reveal from dark | 3–6 s | `low tracking shot`, `orbit with edge light sweeping across the surface`, `reveal from darkness` |
+| Real estate, App / SaaS | slow glide, dolly through a door, screen-locked mockup | 4–6 s | `slow glide forward`, `dolly through the doorway`, `tap animation on the screen` |
+
+Clip lengths above are planning values; the accepted ranges per model are in
+`reference/models.md`.
+
+## Applying a style
+
+- Write the style's phrases in **every** prompt of the campaign: KV, stills, clips. A style that
+  appears in the KV and not in the clips reads as two campaigns.
+- The style sets light, background, palette and type feeling. It never changes the product: the
+  packshot reference and the identity clause in `reference/ai-consistency.md` stay in force.
+- Two styles in one ad is a mistake except the deliberate before / after (a Lifestyle "before"
+  cut to a Minimal "after").
+- Brand colours from the brief override the style's palette: a Tech look in a brand's orange is
+  `orange edge lighting`, not cyan.
+- Match the CTA tone column to the copy on the end card; a Luxury visual with "BUY NOW!!!" on
+  the card is the most common mismatch.