image-compose

## 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 image.

- Identify the source node (usually the most recent `image_result`, or one the user named). Grab `source.id` and `source.metadata.aspect_ratio`.
- `node "$PAI_REPO_ROOT/server/cli/generate_image.js" --prompt "..." --aspect-ratio <source ratio> --image-size <source size or 2K> --subtype edit --source-node-id <source.id> --ref-source-id <source.id>`.
- Prompt as a **transformation**, not a full re-description:
  > `<concrete change>. Preserve everything else.`

  ✅ "Change the rain to falling snow. Keep the detective, wardrobe, and camera framing unchanged."
  ✅ "Re