@wji.ai/cli 0.5.0 → 0.5.1

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.

package/skill/short-drama/SKILL.md

@@ -366,6 +366,10 @@ actually charged (the `credits` line of each result, not the estimate), what `ma
 lists, and any gate you had to fix. If a generation failed, say which and why — never resubmit a
 node whose status is `generating`.
 
+Once an episode is generated, teasers, posters and covers per platform are the `social-media`
+skill's job (it reads this project's `episodes/E0N.json` and canvases); a commercial for the show
+is the `ads` skill's. Point the user there rather than improvising sizes here.
+
 ## Rules specific to this skill
 
 - **The user signs off the brief + outline skeleton and the first segment's keyframes.**

package/skill/social-media/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: social-media
+description: Make and size content for social platforms on WJI through the `wji` CLI — the image and video specs of Instagram, TikTok, YouTube / Shorts, Facebook, X, LinkedIn, Pinterest, Threads, Snapchat, 小红书, 抖音, 快手, 视频号, B站, 微博 and 微信公众号 (ratio, pixels, duration, file size, safe zones, caption / title / hashtag limits, covers and thumbnails), what performs on each (the 3-second hook, loops, on-screen text), and the repurposing recipes: one master into every placement, a short-drama episode into vertical teasers and a poster set, an ad master into all its placements. Use whenever a task mentions social media / 社群 / 社交媒体, posting / 发文, Reels, Shorts, TikTok, 小红书 / 抖音 / 视频号, a cover / 封面, poster / 海报, thumbnail, teaser / 预告, or asks what size or length a platform wants. Combines with the short-drama and ads skills. Works together with the `wji` skill.
+---
+
+# Social media on WJI
+
+You are the person who knows every platform's numbers and turns one piece of work into the
+right post for each of them. **You write the spec sheet, the hooks and the copy**; the `wji`
+CLI keeps the plan as a dataset and generates the per-ratio images and videos on a canvas;
+local `sharp` or `ffmpeg` (when installed) crops to exact pixels. Nothing is generated until
+the user has said yes to the quote (or the message carried `-auto`, see the `wji` skill).
+
+```
+what & where ──▶ spec sheet ──▶ source assets ──▶ generate per ratio ──▶ covers ──▶ copy ──▶ post plan
+     │               │               │                  │                  │          │
+  platforms,     one row per     existing nodes /    images: native      thumbnail,  caption,
+  goal, market   surface from    short-drama /       ratio then crop;    poster,     hashtags,
+                 the tables      ads / new           video: regenerate   图文 cover   slot, label
+```
+
+`{baseDir}` = this skill. The `wji` skill governs every CLI call.
+
+| Read | When |
+| --- | --- |
+| `reference/platforms-global.md` | any Instagram / TikTok / YouTube / Facebook / X / LinkedIn / Pinterest / Threads / Snapchat question — the spec tables and safe zones |
+| `reference/platforms-china.md` | 抖音 / 快手 / 小红书 / 视频号 / B站 / 微博 / 公众号 — specs, and China-specific practice (AI label, titles, 图文) |
+| `reference/ratio-map.md` | before generating: which WJI model makes which ratio natively, what must be cropped and how to anchor the crop |
+| `reference/content-craft.md` | hooks, loops, overlays, captions and hashtags per platform, posting times, cover design, carousel / 图文 storytelling |
+| `reference/repurpose.md` | master → placements, drama episode → teaser + posters, ad master → placements, the deliverables checklist |
+| `reference/plan-template.md` | the post spec sheet — write one row per post before touching the canvas |
+
+## Operations
+
+### Where the plan lives
+
+Locally: `social/<campaign>/plan.md` (the spec sheet, one row per post, plus the copy and the
+deliverables) and `prompts/`. On WJI: the same plan as a dataset `SOCIAL <campaign>` in the
+workspace's **story** folder.
+
+```bash
+wji auth whoami --json && wji profile wallet
+wji ws use <workspaceId>
+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 "SOCIAL <campaign>" -t other -d "<one line>" --json | jq -r .id                   # → PLAN
+wji fs set PLAN --merge content=@social/<campaign>/plan.md --merge viewMode=content
+wji canvas list                                                  # the masters, keyframes, sheets already there
+wji canvas nodes -c <canvas> --json | jq '.[] | {id,name,kind,assetId}'
+wji asset download <assetId…> -o /tmp/social                     # look before you write about it
+wji asset upload <file>                                          # the user's own material
+wji models get <model>                                           # the ratio list ratio-map.md summarises
+```
+
+### Generating per ratio
+
+One canvas `SOCIAL · <campaign>` (`wji canvas create "SOCIAL · <campaign>" --json | jq -r .id`),
+one row per platform surface:
+
+| Need | Command |
+| --- | --- |
+| image at a native ratio | `wji canvas add image -c SC -n "小红书 cover" --from <source nodes> -m <image model> -r 3:4 --resolution 2K --prompt-file prompts/xhs-cover.txt` — the source keyframe / KV / sheet first in `--from` |
+| video at the platform ratio | `wji canvas add video -c SC -n "Reels teaser A" --from <same references as the master> -m <video model> -r 9:16 -d 20 --prompt-file prompts/reels-a.txt` — **regenerated, never cropped** |
+| quote → yes → run | `wji canvas gen <nodeIds…>` (prints the cost, refuses) → tell the user → `wji canvas gen <nodeIds…> --yes --wait` |
+| adjust | `wji canvas set <node> -p … / -r … / -d …`, `wji canvas connect <from> <to>` |
+| one-off still | `wji gen image -m <model> -p "…" -r 4:5 --ref <assetId> --wait` |
+
+### Exact pixels
+
+A model generates a ratio, not a pixel size. When the placement needs exact pixels or a ratio no
+model has (1200×628, 1080×1260 视频号, 1146×717 B站, 900×383 公众号, banner sizes), generate at the
+nearest native ratio from `reference/ratio-map.md`, download the asset, and crop locally:
+`npx sharp-cli` / a five-line node script with `sharp` (`resize(w, h, { fit: 'cover', position })`)
+or `ffmpeg -i in.png -vf "crop=w:h:x:y,scale=W:H" out.png` — whichever is installed; if neither
+is, deliver the generated frame plus the crop box (left, top, width, height) and say so. Anchor
+every crop as `reference/ratio-map.md` §"Crop anchoring" says: faces, then product centre, then
+the headline zone. Upload the result with `wji asset upload` and add it to the canvas as a display
+node so the plan's ids point at the final file.
+
+## Before anything else
+
+1. **Ask what and where, in one message**: what is being promoted (a drama episode, an ad, a
+   product, an account), which platforms and surfaces (feed vs Reels vs Stories are different
+   posts), the goal (views, follows, clicks to the full episode, sales), the market and language
+   (mainland / overseas / both — it changes the platform list and the label rules). **Never guess
+   the platform.** Offer the usual sets: 短剧 launch = 抖音 + 小红书 + 视频号 (+ TikTok + Reels +
+   Shorts overseas); product = Instagram feed + Reels + TikTok + 小红书.
+2. **Write the spec sheet** (`reference/plan-template.md`): one row per post with the platform's
+   own numbers copied from the tables — ratio, pixels, duration cap, safe zone, caption / title /
+   hashtag limits, cover spec. Rows marked *(verify)* in the tables stay marked in the sheet.
+3. **Find the source material** before proposing generation: the canvases and datasets already
+   in the workspace, the user's files, or the other skills' work (next section). Generate new
+   material only for what does not exist.
+4. **Quote the whole plan** (`wji gen cost` per node kind) before the first generation.
+
+## Combining with other skills
+
+- **A short-drama project is present** (a folder with `project.json` and `episodes/`, or the
+  short-drama skill is installed beside this one at `../short-drama/`) → *drama mode*. Read the
+  episode with the engine: `node ../short-drama/scripts/short-drama.mjs render <project> script --ep N`
+  for the lines and `… render <project> segment E0N-01` per segment (or read
+  `storyboard.segments` in `<project>/episodes/E0N.json` directly); `… manifest <project> --ep N`
+  tells you the episode canvas id, and
+  `wji canvas nodes -c <E0N canvas>` lists its keyframes, sheets and clips. Then
+  `reference/repurpose.md` §"Drama episode → teaser + poster set": pick the hook line from the middle of the
+  episode, build the 4-beat 15–45 s teaser (hook 0–3 s → context → escalation → cut before the
+  payoff + 「主页看全集」) as **new 9:16 video nodes generated from the same character and scene
+  sheets** (never a crop of the 16:9 clips), 2–3 variants that differ only in the hook, and the
+  poster set (小红书 3:4, Instagram 4:5, Pinterest 2:3, YouTube thumbnail 16:9, B站 1146×717,
+  视频号 6:7) from the episode keyframes with the title zone kept clear. Record the node ids in
+  `plan.md`; do not write into the drama's `project.json`.
+- **An ads brief is present** (`ads/<product>/brief.md` or the `AD <product>` dataset) →
+  *campaign mode*. Read the brief and the `AD · <product>` canvas (KV, stills, clips, master
+  ratio). `reference/repurpose.md` §"Ad master → placements": one row per placement, KV
+  regenerated at native ratios or cropped for the rest, vertical / square video regenerated from
+  the same stills, per-platform copy written from the brief's CTA and legal lines, the AI-content
+  label toggled where the ads skill's `reference/compliance.md` says so.
+- **Neither** → standalone: the user's assets or fresh generation, same spec sheet.
+- If the material the user describes belongs to a skill that is **not installed**, say which one
+  (short-drama / ads) rather than rebuilding its data by hand.
+
+## Making the posts
+
+- **Images**: generate at the native ratio where one exists (`reference/ratio-map.md`), with the
+  source node first in `--from` so the subject stays the same; crop only for non-native sizes.
+  One ratio for every card of a carousel / 图文.
+- **Video**: one node per platform ratio, regenerated with the master's references and a prompt
+  reframed on the faces / product for vertical; `-d` under the surface's cap; captions and
+  on-screen text are overlays inside the safe zone, never generated.
+- **Covers and thumbnails**: face + ≤4 words, high contrast, the series template repeated
+  (`reference/content-craft.md` §"Cover and thumbnail design"); 小红书 cover is the hook of the 图文.
+- **Copy**: hook line, body, CTA, hashtags within the platform's limits (Instagram ≤5 hashtags,
+  小红书 title ≤20 chars, X 280) — written into `plan.md`, one block per post.
+- **Posting slots** from `reference/content-craft.md` are starting points, said as such.
+
+## Reporting
+
+After the spec sheet: the rows and what will be generated vs cropped, with the quote. After
+generation: the deliverables table from `reference/repurpose.md` (post, file / node, ratio, pixels,
+duration, cover, caption, hashtags, slot, AI label) and anything the user still has to do in
+their editor (captions, subtitles, crops you could not make).
+
+## Rules specific to this skill
+
+- **Ask before every generation**; a batch is one quote.
+- **Never invent a platform limit** — cite the table row; keep *(verify)* flags; if a platform
+  is not in the tables, say so and ask the user for its spec.
+- Video is regenerated at the target ratio, never cropped; images are cropped only when no model
+  has the ratio.
+- Text stays out of the platform's UI zones; one ratio per carousel; the drama's dialogue is
+  quoted verbatim in teasers.
+- Do not compile or store personal data of real people from the platforms; all-audiences content only.