/image-compose

name: image-compose
description: >-
  Generates/edits filmmaking canvas images via generate_image.js and
  generate_image_pro.js. Use before image CLIs for character/location design,
  refs, starting frames, storyboards, stills, edits, variations, and downstream
  video anchors. Video-bound characters default to Pattern 7 4-panel sheets;
  one-off static portraits use Pattern 1. Story/script breakdowns should create
  detailed location anchors plus material character/location variants. Storyboards
  use Pattern 6: one pro composite mosaic per clip/<=15s shot note.

CLI shape

Standard tier:

node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." [--aspect-ratio 16:9] [--image-size 2K] [--label "..."] [--subtype <character|location|edit|reference|split|storyboard>] [--name "..."] [--role "..."] [--description "..."] [--source-node-id <id>] [--ref-source-id <id> ...]

Pro tier for storyboard mosaics and video-bound character sheets:

node "$PAI_REPO_ROOT/server/cli/generate_image_pro.js" --prompt "..." --size 2560x1440 [--label "..."] [--subtype <character|location|edit|reference|split|storyboard>] [--name "..."] [--role "..."] [--description "..."] [--source-node-id <id>] [--ref-source-id <id> ...]

Pro accepts `--size` only; no `--aspect-ratio` / `--image-size`. Common sizes: `1024x1024`, `1280x720`, `720x1280`, `1920x1920`, `2560x1440`, `1440x2560`, `3840x2160`, `2160x3840`.

`--label` defaults to the truncated prompt (≤30 chars) if omitted; pass an explicit one when you have a better caption.

Use `@Image1`, `@Image2`, … in `--ref-source-id` order. The CLI emits one `derived` edge per ref.

Mirror external URLs first with `mirror_url.js --url <URL>`, then pass the returned `node_id` via `--ref-source-id`.

If a note authored the image, pass `--source-node-id <note_id>`.

Do not attempt to invent images via ASCII art or markdown embedding — call the CLI.

First-use image mode

For the ask-once flow and per-mode prices, see the project `PROJECT_AGENT.md` § "First-use generation choices".

Mode mapping: `Standard 2K` -> `generate_image.js --image-size 2K`; `Pro 2K` -> pro exact 2K; `Max quality` -> pro exact 4K.

Patterns

Pick the one that fits. For source lookup, follow the project `PROJECT_AGENT.md` § "Choosing context"; this skill only owns image-specific prompt and CLI shape.

**Character pre-flight.** First ask: will this character appear in downstream video (video, clip, promo, 宣传片, 短片, 连续剧, film, scene, 拍片, shot, short film)?

1. Read `workflow.json` for uploaded refs (`subtype:"reference"`, `metadata.source:"user_upload"`, not archived). 2. Video-bound -> Pattern 7, not Pattern 1. Use ≥3 actor refs when available; with 0-2 refs, generate text-only 4-panel sheet. 3. Announce one line before firing; allow redirect to Pattern 1. 4. One-off static art/poster/portrait -> Pattern 1.

This pre-flight is non-negotiable. Pattern 1's single front portrait gives the video model an anchor that's too narrow; identity drifts shot-to-shot. Skipping straight to Pattern 1 for video work is the single most-common mistake.

**Story/script anchor defaults.** When `script-compose` or `story-to-video-workflow` routes a breakdown here:

• One base 4-panel sheet per material character.
• Extra sheets for material character variants: age, wardrobe/uniform/disguise, injury/dirty/wet/bloodied state, transformation, or continuity-significant looks.
• Detailed location anchors for settings that affect shots.
• Same-location variants for framing/scale/time/weather/light/dressing/story state/close-detail coverage changes.
• Prefer reference-to-clip after anchors. Storyboard only if requested, hard to control, or needed for diagnosis.
• Do not drop material variants for budget/speed; caller should adjust video resolution/runtime first.

1. Character portrait (one-off static stills only)

Triggers: character portrait/headshot/hero/villain/lead **only** for one-off static stills. Video-bound -> Pattern 7.

• `node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio 9:16 --image-size 2K --subtype character --name "Detective Morris" --role "..." --description "..."` — **no refs**. A character is an identity anchor, not a derivative.
• Prompt template:

> `[style] character portrait of [NAME], [role]. [age, build, wardrobe, distinguishing features]. Front-facing medium close-up, eye-level, looking directly at camera, neutral expression. Plain neutral background, soft even lighting. No dramatic shadows, no stylized lighting, no side profile, no multiple views.`

• Inherit project style or default to realistic. Name unnamed characters.
• No edges — characters are roots, so no `--ref-source-id`.

2. Location establishing still

Triggers: establish/design/picture a location, or approval of a `script-compose` location offer.

• `node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio 16:9 --image-size 2K --subtype location --name "Causeway" --description "..." [--source-node-id <script_or_shot_note_id>]` — **no refs**. A location is a setting anchor, not a derivative.
• Prompt template:

> `[style] establishing still of [LOCATION NAME]. [visual brief — architecture, lighting, atmosphere]. Wide shot, eye-level, no characters present.`

• Keep frame empty of characters. Include architecture/layout, surfaces, dressing, era, weather, time, light, and story state when relevant.
• Same-location variants preserve place identity while changing wide/close scale, day/night, weather, dressing, damage, or detail coverage.
• No ref edges by default. If the location was derived from a script or shot note, use `--source-node-id` so the authorship edge lands.
• *Follow-on:* after the last scripted location, recommend the next reference-to-clip render. Mention storyboard only if requested/needed.

3. Edit / variation / turnaround of an existing image

Triggers: change/edit/swap/replace/add/remove/tweak/what-if/variation on an existing