Baoyu Cover Image

Cover Image Generator

Generate elegant cover images for articles with 5-dimensional customization.

User Input Tools

When this skill prompts the user, follow this tool-selection rule (priority order):

1. Prefer built-in user-input tools exposed by the current agent runtime — e.g., AskUserQuestion, request_user_input, clarify, ask_user, or any equivalent. 2. Fallback: if no such tool exists, emit a numbered plain-text message and ask the user to reply with the chosen number/answer for each question. 3. Batching: if the tool supports multiple questions per call, combine all applicable questions into a single call; if only single-question, ask them one at a time in priority order.

Concrete AskUserQuestion references below are examples — substitute the local equivalent in other runtimes.

Image Generation Tools

When this skill needs to render an image, resolve the backend in this order:

1. Current-request override — if the user names a specific backend in the current message, use it. 2. Saved preference — if EXTEND.md sets preferred_image_backend to a backend available right now, use it. 3. Auto-select (when the preference is auto, unset, or the pinned backend isn't available):

• Codex (`imagegen`) — first, inspect your available-skills / tool inventory. If a skill named imagegen is listed, you are running inside Codex and MUST use it: invoke via the Skill tool with skill: "imagegen", passing the saved prompt file's content (plus output path and aspect ratio per Codex imagegen's own args). Codex imagegen is the official raster backend in that runtime and outranks any non-native skill (e.g., baoyu-image-gen) unless the user has explicitly pinned a different preferred_image_backend.
• Codex via `codex exec` (`codex-imagegen`) — if the current runtime exposes no native imagegen skill but the codex CLI is on PATH with an active codex login, route through baoyu-image-gen --provider codex-cli (preferred), or — if baoyu-image-gen is unavailable — invoke the bundled wrapper directly. Details, parameters, and the runtime-discovery procedure live in references/codex-imagegen.md — load that file only when this branch is selected.
• Cursor (`GenerateImage`) — if the runtime exposes a native GenerateImage tool, you are running inside Cursor and it outranks any non-native skill the same way Codex imagegen does. Two hard caveats: (a) it has no aspect-ratio parameter — state the target aspect ratio / dimensions explicitly in the prompt text passed as description; (b) it does not accept an output directory — it saves to a tool-managed location, so after generation copy/move the file to the skill's expected output path (e.g., outputs/.../NN-xxx.png). Reference images go in reference_image_paths.
• Other runtime-native tools — if the runtime exposes a different native image tool (e.g., Hermes image_generate), use it the same way.
• Otherwise, if exactly one non-native backend is installed (e.g., baoyu-image-gen), use it.
• Otherwise (multiple non-native backends with no runtime-native tool), ask the user once — batch with any other initial questions.

4. If none are available, tell the user and ask how to proceed.

⛔ Never substitute SVG, HTML, canvas, or other code-based rendering for raster image generation. Codex imagegen's own description says it should be used "when the output should be a bitmap asset rather than repo-native code or vector." If you cannot resolve a raster backend via step 3, fall through to step 4 and ask the user — do not silently emit SVG, write inline <svg> markup, or produce HTML/CSS art as a substitute. This applies even if the article/section seems "diagram-like": the consumer skill calling this rule has already decided that a raster image is what it needs.

⛔ Never repair rendered text by painting over a generated bitmap. Do not use ImageMagick, Pillow, Canvas, SVG, HTML/CSS, OCR scripts, or any other programmatic overlay to cover, rewrite, erase, stroke, or replace title/subtitle text inside an already generated cover image. If text is wrong or unclear, regenerate from a corrected prompt, switch to a lower-text or no-title variant, or ask the user which imperfect candidate to keep.

Setting preferred_image_backend: ask forces the step-3 prompt every run regardless of available backends. Users change the pinned backend via the ## Changing Preferences section below.

Prompt file requirement (hard): write each image's full, final prompt to a standalone file under prompts/ (naming: NN-{type}-[slug].md) BEFORE invoking any backend. The backend receives the prompt file (or its content); the file is the reproducibility record and lets you switch backends without regenerating prompts.

Concrete tool names (imagegen, GenerateImage, image_generate, baoyu-image-gen) above are examples — substitute the local equivalents under the same rule.

Confirmation Policy

Default behavior: confirm before generation.

• Treat explicit skill invocation, a file path, matched keywords/presets, EXTEND.md defaults, and any documented auto-selection as recommendation inputs only. None of them authorizes skipping confirmation.
• Do not start Step 3 or Step 4 until the user confirms the dimensions / aspect / language / backend choices.
• Skip confirmation only when the current request explicitly says to do so, for example: --quick, "直接生成", "不用确认", "跳过确认", "按默认出图", or equivalent wording. quick_mode: true in EXTEND.md counts as a standing explicit opt-out — set it only when you want every run to skip Step 2.
• If confirmation is skipped explicitly, state the assumed dimensions / aspect / language / backend in the next user-facing update before generating.

Options

Five Dimensions

Auto-selection rules: references/auto-selection.md

Galleries

Types: hero, conceptual, typography, metaphor, scene, minimal → Details: references/types.md

Palettes: warm, elegant, cool, dark, earth, vivid, pastel, mono, retro, duotone, macaron → Details: references/palettes/

Renderings: flat-vector, hand-drawn, painterly, digital, pixel, chalk, screen-print → Details: references/renderings/

Text Levels: none (pure visual) | title-only (default) | title-subtitle | text-rich (with tags) → Details: references/dimensions/text.md

Mood Levels: subtle (low contrast) | balanced (default) | bold (high contrast) → Details: references/dimensions/mood.md

Fonts: clean (sans-serif) | handwritten | serif | display (bold decorative) → Details: references/dimensions/font.md

File Structure

Output directory per default_output_dir preference:

• same-dir: {article-dir}/
• imgs-subdir: {article-dir}/imgs/
• independent (default): cover-image/{topic-slug}/

<output-dir>/
├── source-{slug}.{ext}    # Source files
├── refs/                  # Reference images (if provided)
│   ├── ref-01-{slug}.{ext}
│   └── ref-01-{slug}.md   # Description file
├── prompts/cover.md       # Generation prompt
└── cover.png              # Output image

Slug: 2-4 words, kebab-case. Conflict: append -YYYYMMDD-HHMMSS

Workflow

Progress Checklist

Cover Image Progress:
- [ ] Step 0: Check preferences (EXTEND.md) ⛔ BLOCKING
- [ ] Step 1: Analyze content + save refs + determine output dir
- [ ] Step 2: Confirm options (6 dimensions) ⚠️ unless --quick
- [ ] Step 3: Create prompt
- [ ] Step 4: Generate image
- [ ] Step 5: Completion report

Flow

Input → [Step 0: Preferences] ─┬─ Found → Continue
                               └─ Not found → First-Time Setup ⛔ BLOCKING → Save EXTEND.md → Continue
        ↓
Analyze + Save Refs → [Output Dir] → [Confirm: 6 Dimensions] → Prompt → Generate → Complete
                                              ↓
                                     (skip if --quick or all specified)

Step 0: Load Preferences ⛔ BLOCKING

Check EXTEND.md in priority order — the first one found wins:

CRITICAL: If not found, complete setup BEFORE any other steps or questions.

Step 1: Analyze Content

1. Save reference images (if provided) → references/workflow/reference-images.md 2. Save source content (if pasted, save to source.md) 3. Analyze content: topic, tone, keywords, visual metaphors 4. Deep analyze references ⚠️: Extract specific, concrete elements (see reference-images.md) 5. Detect language: Compare source, user input, EXTEND.md preference 6. Determine output directory: Per File Structure rules

⚠️ People in Reference Images:

If reference images contain people who should appear in the cover:

• Model supports `--ref` (default): Copy image to refs/, pass via --ref at generation. No description file needed — the model sees the face directly.
• Model does NOT support `--ref` (Jimeng, Seedream 3.0): Create refs/ref-NN-{slug}.md with per-character description (hair, glasses, skin tone, clothing). Embed as MUST/REQUIRED instructions in prompt text.

See reference-images.md for full decision table.

Step 2: Confirm Options ⚠️

Hard gate: this step is mandatory per the Confirmation Policy — Steps 3–4 cannot start until the user confirms here (or explicitly opts out with --quick / quick_mode: true / equivalent wording in the current request).

MUST use `AskUserQuestion` tool to present options as interactive selection — NOT plain text tables. Present up to 4 questions in a single AskUserQuestion call (Type, Palette, Rendering, Font + Settings). Each question shows the recommended option first with reason, followed by alternatives.

Full confirmation flow and question format: references/workflow/confirm-options.md

Step 3: Create Prompt

Save to prompts/cover.md. Template: references/workflow/prompt-template.md

CRITICAL - References in Frontmatter:

• Files saved to refs/ → Add to frontmatter references list
• Style extracted verbally (no file) → Omit references, describe in body
• Before writing → Verify: test -f refs/ref-NN-{slug}.{ext}

Reference elements in body MUST be detailed, prefixed with "MUST"/"REQUIRED", with integration approach.

Step 4: Generate Image

1. Backup existing cover.png if regenerating 2. Select backend via the ## Image Generation Tools rule at the top: use whatever is available; if multiple, ask the user once. Do this once per session before any generation. 3. Write the full final prompt to prompts/01-cover-[slug].md (hard requirement) BEFORE invoking the backend. 4. Process references from prompt frontmatter:

• direct usage → pass via --ref (use ref-capable backend)
• style/palette → extract traits, append to prompt

5. Generate: Call the chosen backend with the prompt file, output path, aspect ratio.

• `codex-imagegen`: see references/codex-imagegen.md for the invocation contract (preferred baoyu-image-gen --provider codex-cli path, runtime wrapper discovery, parameter notes, stdout schema, batch semantics).
• Codex `imagegen` (native) or other runtime-native tools / baoyu-image-gen skill: per the rule in ## Image Generation Tools above.

6. On failure: auto-retry once

Step 5: Completion Report

Cover Generated!

Topic: [topic]
Type: [type] | Palette: [palette] | Rendering: [rendering]
Text: [text] | Mood: [mood] | Font: [font] | Aspect: [ratio]
Title: [title or "visual only"]
Language: [lang] | Watermark: [enabled/disabled]
References: [N images or "extracted style" or "none"]
Location: [directory path]

Files:
✓ source-{slug}.{ext}
✓ prompts/cover.md
✓ cover.png

Image Modification

Text correction policy:

• If the title/subtitle is misspelled, garbled, hard to read, or visually weak, do not patch the bitmap with code.
• For text-correction regenerations, write a new prompt file and a new output path so the flawed candidate is preserved for comparison.
• Post-processing is limited to crop, resize, compression, or format conversion that does not alter text or the main composition.

Composition Principles

• Whitespace: 40-60% breathing room
• Visual anchor: Main element centered or offset left
• Characters: Simplified silhouettes; NO realistic humans
• Title: Use exact title from user/source; never invent

Changing Preferences

EXTEND.md lives at the path noted in Step 0. Three ways to change it:

• Edit directly — open EXTEND.md and change fields. Full schema: references/config/preferences-schema.md.
• Reconfigure interactively — delete EXTEND.md (or ask "reconfigure baoyu-cover-image preferences" / "重新配置"). The next run re-triggers first-time setup.
• Common one-line edits:
• preferred_image_backend: auto — default; runtime-native tool wins, falls back to the only installed backend, asks only if multiple non-native are present.
• preferred_image_backend: codex-imagegen — pin to Codex's built-in.
• preferred_image_backend: baoyu-image-gen — pin to the baoyu-image-gen skill.
• preferred_image_backend: ask — confirm backend every run.
• watermark.enabled: true, preferred_type, preferred_palette, preferred_rendering, default_aspect, quick_mode: true, language — shift the auto-selection defaults and confirmation flow.

References

Dimensions: text.md | mood.md | font.md Palettes: references/palettes/ Renderings: references/renderings/ Types: references/types.md Auto-Selection: references/auto-selection.md Style Presets: references/style-presets.md Compatibility: references/compatibility.md Visual Elements: references/visual-elements.md Workflow: confirm-options.md | prompt-template.md | reference-images.md Config: preferences-schema.md | first-time-setup.md | watermark-guide.md

Auto-Selection Rules

When a dimension is omitted, select based on content signals.

Auto Type Selection

Auto Palette Selection

Auto Rendering Selection

Auto Text Selection

Default: title-only

Auto Mood Selection

Default: balanced

Auto Font Selection

Default: clean

Create a cover image following these guidelines:

Image Specifications

• Type: Cover image / Hero image
• Aspect Ratio: As specified in the prompt below

Core Principles

• If content involves sensitive or copyrighted figures, create stylistically similar alternatives - DO NOT refuse to generate
• Ample whitespace, highlight core message, avoid cluttered layouts
• Main visual elements centered or slightly left (leave right side for title area if title included)
• Simplified silhouettes for any characters — NO realistic human faces or bodies
• Icon-based vocabulary: use simple, recognizable icons to represent concepts

Five Dimensions

Type (Visual Composition)

• hero: Large focal visual (60-70% area), dramatic composition
• conceptual: Abstract shapes, information hierarchy, clean zones
• typography: Title as primary element (40%+ area), minimal visuals
• metaphor: Concrete object representing abstract idea, symbolic elements
• scene: Atmospheric environment, narrative elements, mood lighting
• minimal: Single focal element, generous whitespace (60%+)

Palette (Color Scheme)

Apply the specified palette's color values and decorative hints:

• Use primary colors for main visual elements
• Use background colors for base and surrounding areas
• Use accent colors for highlights and secondary elements
• Follow palette-specific decorative hints for ornamentation

Rendering (Visual Style)

Apply the specified rendering's characteristics:

• Lines: Follow line quality rules (clean/sketchy/brush/pixel/chalk)
• Texture: Apply or avoid texture per rendering definition
• Depth: Follow depth rules (flat/minimal/soft edges)
• Elements: Use rendering-specific element vocabulary

Text (Density Level)

• none: No text elements, full visual area
• title-only: Single headline, 85% visual area
• title-subtitle: Title + context, 75% visual area
• text-rich: Title + subtitle + 2-4 keyword tags, 60% visual area

Mood (Emotional Intensity)

• subtle: Low contrast, muted/desaturated colors, light visual weight, calm aesthetic
• balanced: Medium contrast, normal saturation, balanced visual weight
• bold: High contrast, vivid/saturated colors, heavy visual weight, dynamic energy

Text Style (When Title Included)

• Title source: Use the exact title provided by user, or extract from source content. Do NOT invent or modify titles.
• Title text: Large, eye-catching, faithful to source
• Subtitle: Secondary element (if title-subtitle or text-rich)
• Tags: 2-4 keyword badges (if text-rich)
• Font style harmonizes with rendering style

Composition Guidance

Layout Principles

• Generous whitespace: Maintain 40-60% breathing room; avoid cluttered compositions
• Visual anchor placement: Main element centered or offset left (reserve right side for title if included)
• Information hierarchy: One dominant focal point, 1-2 supporting elements, decorative accents
• Clean backgrounds: Solid colors or subtle gradients; no complex textures or patterns

Icon & Symbol Vocabulary

Represent concepts with simple, recognizable icons rather than detailed illustrations:

Use the rendering style to determine icon complexity (flat-vector = geometric, hand-drawn = sketchy, etc.)

Full library: references/visual-elements.md

Character Handling

Default (no reference with people):

• Use simplified silhouettes or abstract stick figures
• Symbolic representations (head + shoulders outline)
• NO realistic faces, detailed anatomy, or photographic representations
• Cartoon/icon style consistent with rendering choice

When reference images contain people:

• Reference image is passed to model (usage: direct) — model must visually reference it to preserve character likeness
• Stylize to match chosen rendering (cartoon/vector), preserving distinctive features (hair, clothing, pose)
• NEVER photorealistic

Mood Application

Apply mood adjustments to the base palette:

Language

• Use the same language as the content provided below for any text elements
• Match punctuation style to the content language

Reference Images

When reference images are provided:

• Style extraction: Identify rendering technique, line quality, texture, and visual vocabulary
• Composition learning: Note layout patterns, whitespace usage, element placement
• Mood matching: Capture the emotional tone and visual weight
• Adaptation: Apply extracted characteristics while respecting the specified Type, Palette, and Rendering dimensions
• Priority: If reference style conflicts with specified dimensions, dimensions take precedence for structural choices; reference influences decorative details

---

Please generate the cover image based on the content provided below:

codex-imagegen Wrapper Invocation

Load this reference only when the Image Generation Tools rule has resolved to codex-imagegen — i.e., the current runtime exposes no native imagegen skill but codex CLI is on PATH with an active codex login.

Preferred path: route through baoyu-image-gen

If the baoyu-image-gen skill is available in this runtime, always invoke through it rather than calling the wrapper directly. It handles retry/cache/batch/EXTEND.md preferences uniformly with every other provider.

${BUN_X} <baoyu-image-gen-base>/scripts/main.ts \
  --provider codex-cli \
  --image <ABSOLUTE_output> \
  --promptfiles <ABSOLUTE_prompts/01-cover-[slug].md> \
  --ar <ratio> \
  [--ref <ABSOLUTE_file>]...

Resolve <baoyu-image-gen-base> the same way you resolve any sibling skill — through your runtime's skill registry (Skill tool, plugin marketplace, or $HOME/.baoyu-skills/baoyu-image-gen/).

Fallback: spawn the wrapper directly

Only when baoyu-image-gen is NOT installed in the current runtime. Discover the wrapper's location at runtime — do NOT hard-code ../../packages/... from this skill:

1. Honor explicit override: if $BAOYU_CODEX_IMAGEGEN_BIN is set and points to a real file, use that path. It may be .ts (spawn bun <path>) or .sh/binary (spawn directly). 2. Search the plugin root: walk up from this skill's directory looking for packages/baoyu-codex-imagegen/src/main.ts. If found, that is the wrapper. Spawn it with bun. 3. Last resort: tell the user that codex-imagegen is not available in this runtime and ask whether to install the baoyu-skills plugin (or set BAOYU_CODEX_IMAGEGEN_BIN) or pick another backend.

Once located, the invocation shape is:

bun <WRAPPER>/main.ts \
  --image <ABSOLUTE_output> \
  --prompt-file <ABSOLUTE_prompts/01-cover-[slug].md> \
  --aspect <ratio> \
  [--ref <ABSOLUTE_file>]... \
  [--timeout <ms>] \
  [--cache-dir ~/.cache/baoyu-codex-imagegen] \
  [--log-file <ABSOLUTE_jsonl_log_path>]

If bun is missing, npx -y bun <WRAPPER>/main.ts ... works as a fallback.

Parameter notes

• All filesystem inputs are auto-resolved against process.cwd() when relative, but agents should pass absolute paths to be robust against cwd drift.
• `--timeout` defaults to 300000 (5 min) per codex exec attempt. Raise (e.g. --timeout 600000 for 10 min) on slow networks or large prompts.
• `--cache-dir` is off by default. Enable for repeatable runs to skip redundant generations of the same prompt+aspect+refs.
• Authentication: the wrapper uses the user's Codex subscription — no OPENAI_API_KEY is read or sent.

Stdout contract

Single JSON line:

• Success: {"status":"ok","path":"...","bytes":N,"elapsed_seconds":N,"thread_id":"...","attempts":N,"cached":bool,...}
• Failure: {"status":"error","path":"...","bytes":0,"error":"...","error_kind":"..."}

error_kind values: codex_not_installed, invalid_args, prompt_file_missing, spawn_failed, timeout, no_image_gen_tool_use, output_missing, invalid_png, agent_refused, lock_busy.

On retryable errors (timeout, spawn_failed, no_image_gen_tool_use, output_missing, invalid_png, agent_refused), ask the user whether to retry or fall back to another backend.

Batch semantics

• Codex image_gen returns one image per call (n=1 only). Multi-image jobs must dispatch one wrapper call per image.
• The wrapper does NOT accept a --sessionId flag. Chain/scene consistency must come from --ref reference images.
• --size and --quality are silently ignored — Codex picks pixel dimensions from --aspect.

Compatibility Matrices

✓✓ = highly recommended | ✓ = compatible | ✗ = not recommended

Palette × Rendering

Type × Rendering

Type × Text

Type × Mood

Font × Rendering

First-Time Setup

Overview

When no EXTEND.md is found, guide user through preference setup.

⛔ BLOCKING OPERATION: This setup MUST complete before ANY other workflow steps. Do NOT:

• Ask about reference images
• Ask about content/article
• Ask about dimensions (type, palette, rendering)
• Proceed to content analysis

ONLY ask the questions in this setup flow, save EXTEND.md, then continue.

Setup Flow

No EXTEND.md found
        │
        ▼
┌─────────────────────┐
│ AskUserQuestion     │
│ (all questions)     │
└─────────────────────┘
        │
        ▼
┌─────────────────────┐
│ Create EXTEND.md    │
└─────────────────────┘
        │
        ▼
    Continue to Step 1

Questions

Language: Use user's input language or saved language preference.

Use AskUserQuestion with ALL questions in ONE call:

Question 1: Watermark

header: "Watermark"
question: "Watermark text for generated cover images?"
options:
  - label: "No watermark (Recommended)"
    description: "Clean covers, can enable later in EXTEND.md"

Question 2: Preferred Type

header: "Type"
question: "Default cover type preference?"
options:
  - label: "Auto-select (Recommended)"
    description: "Choose based on content analysis each time"
  - label: "hero"
    description: "Large visual impact - product launch, announcements"
  - label: "conceptual"
    description: "Concept visualization - technical, architecture"

Question 3: Preferred Palette

header: "Palette"
question: "Default color palette preference?"
options:
  - label: "Auto-select (Recommended)"
    description: "Choose based on content analysis each time"
  - label: "elegant"
    description: "Sophisticated - soft coral, muted teal, dusty rose"
  - label: "warm"
    description: "Friendly - orange, golden yellow, terracotta"
  - label: "cool"
    description: "Technical - engineering blue, navy, cyan"

Question 4: Preferred Rendering

header: "Rendering"
question: "Default rendering style preference?"
options:
  - label: "Auto-select (Recommended)"
    description: "Choose based on content analysis each time"
  - label: "hand-drawn"
    description: "Sketchy organic illustration with personal touch"
  - label: "flat-vector"
    description: "Clean modern vector with geometric shapes"
  - label: "digital"
    description: "Polished precise digital illustration"

Question 5: Default Aspect Ratio

header: "Aspect"
question: "Default aspect ratio for cover images?"
options:
  - label: "16:9 (Recommended)"
    description: "Standard widescreen - YouTube, presentations, versatile"
  - label: "2.35:1"
    description: "Cinematic widescreen - article headers, blog posts"
  - label: "1:1"
    description: "Square - Instagram, WeChat, social cards"
  - label: "3:4"
    description: "Portrait - Xiaohongshu, Pinterest, mobile content"

Note: More ratios (4:3, 3:2) available during generation. This sets the default recommendation.

Question 6: Default Output Directory

header: "Output"
question: "Default output directory for cover images?"
options:
  - label: "Independent (Recommended)"
    description: "cover-image/{topic-slug}/ - separate from article"
  - label: "Same directory"
    description: "{article-dir}/ - alongside the article file"
  - label: "imgs subdirectory"
    description: "{article-dir}/imgs/ - images folder near article"

Question 7: Quick Mode

header: "Quick"
question: "Enable quick mode by default?"
options:
  - label: "No (Recommended)"
    description: "Confirm dimension choices each time"
  - label: "Yes"
    description: "Skip confirmation, use auto-selection"

Question 8: Save Location

header: "Save"
question: "Where to save preferences?"
options:
  - label: "Project (Recommended)"
    description: ".baoyu-skills/ (this project only)"
  - label: "User"
    description: "~/.baoyu-skills/ (all projects)"

Save Locations

After Setup

1. Create directory if needed 2. Write EXTEND.md with frontmatter 3. Confirm: "Preferences saved to [path]" 4. Continue to Step 1

EXTEND.md Template

---
version: 3
watermark:
  enabled: [true/false]
  content: "[user input or empty]"
  position: bottom-right
  opacity: 0.7
preferred_type: [selected type or null]
preferred_palette: [selected palette or null]
preferred_rendering: [selected rendering or null]
preferred_text: title-only
preferred_mood: balanced
default_aspect: [16:9/2.35:1/1:1/3:4]
default_output_dir: [independent/same-dir/imgs-subdir]
quick_mode: [true/false]
language: null
preferred_image_backend: auto
custom_palettes: []
---

preferred_image_backend: auto is the baked-in default — first-time setup does not ask about it. The ## Image Generation Tools rule in SKILL.md then picks the runtime-native tool (Codex imagegen, Hermes image_generate, etc.) when available, and falls back to installed backends.

Modifying Preferences Later

See the ## Changing Preferences section in SKILL.md for the canonical list of common edits (pin backend, change defaults, retrigger setup). Full schema: preferences-schema.md.

EXTEND.md Supports: Watermark | Preferred type | Preferred palette | Preferred rendering | Preferred text | Preferred mood | Default aspect ratio | Default output directory | Quick mode | Image backend preference | Custom palette definitions | Language preference

Preferences Schema

Full Schema

---
version: 3

watermark:
  enabled: false
  content: ""
  position: bottom-right  # bottom-right|bottom-left|bottom-center|top-right

preferred_type: null      # hero|conceptual|typography|metaphor|scene|minimal or null for auto-select

preferred_palette: null   # warm|elegant|cool|dark|earth|vivid|pastel|mono|retro|duotone|macaron or null for auto-select

preferred_rendering: null # flat-vector|hand-drawn|painterly|digital|pixel|chalk or null for auto-select

preferred_text: title-only  # none|title-only|title-subtitle|text-rich

preferred_mood: balanced    # subtle|balanced|bold

default_aspect: "2.35:1"  # 2.35:1|16:9|1:1

quick_mode: false         # Skip confirmation when true

language: null            # zh|en|ja|ko|auto (null = auto-detect)

preferred_image_backend: auto  # auto|ask|<backend-id>

custom_palettes:
  - name: my-palette
    description: "Palette description"
    colors:
      primary: ["#1E3A5F", "#4A90D9"]
      background: "#F5F7FA"
      accents: ["#00B4D8"]
    decorative_hints: "Clean lines, geometric shapes"
    best_for: "Business, tech content"
---

Field Reference

Type Options

Palette Options

Rendering Options

Text Options

Mood Options

Position Options

Aspect Ratio Options

Custom Palette Fields

Example: Minimal Preferences

---
version: 3
watermark:
  enabled: true
  content: "@myhandle"
preferred_type: null
preferred_palette: elegant
preferred_rendering: hand-drawn
preferred_text: title-only
preferred_mood: balanced
quick_mode: false
---

Example: Full Preferences

---
version: 3
watermark:
  enabled: true
  content: "myblog.com"
  position: bottom-right

preferred_type: conceptual

preferred_palette: cool

preferred_rendering: digital

preferred_text: title-subtitle

preferred_mood: subtle

default_aspect: "16:9"

quick_mode: true

language: en

preferred_image_backend: codex-imagegen

custom_palettes:
  - name: corporate-tech
    description: "Professional B2B tech palette"
    colors:
      primary: ["#1E3A5F", "#4A90D9"]
      background: "#F5F7FA"
      accents: ["#00B4D8", "#48CAE4"]
    decorative_hints: "Clean lines, subtle gradients, circuit patterns"
    best_for: "SaaS, enterprise, technical"
---

Migration from v2

When loading v2 schema, auto-upgrade:

Style → Palette + Rendering mapping:

Custom style migration:

Migration from v1

When loading v1 schema, auto-upgrade to v3:

v1 --no-title flag maps to preferred_text: none.

Watermark Guide

Position Diagram

┌─────────────────────────────┐
│                  [top-right]│
│                             │
│                             │
│       COVER IMAGE           │
│                             │
│                             │
│[bottom-left][bottom-center][bottom-right]│
└─────────────────────────────┘

Position Recommendations

Content Format

Best Practices

1. Consistency: Use same watermark across all covers 2. Legibility: Ensure watermark readable on both light/dark areas 3. Size: Keep subtle - should not distract from content

Prompt Integration

When watermark is enabled, add to image generation prompt:

Include a subtle watermark "[content]" positioned at [position].
The watermark should be legible but not distracting from the main content.

Cover-Specific Considerations

Common Issues

Font Dimension

Controls typography style and character feel.

Values

Detail

clean

Modern, universal typography with neutral character.

Characteristics:

• Geometric sans-serif letterforms
• Sharp, uniform line weight
• Clean edges, no flourishes
• High readability at all sizes
• Minimal personality, maximum clarity

Use Cases:

• Technical documentation
• Professional/corporate content
• Minimal design approaches
• Data-driven articles
• Modern brand aesthetics

Prompt Hints:

• Use clean geometric sans-serif typography
• Modern, minimal letterforms
• Sharp edges, uniform stroke weight
• High contrast against background

handwritten

Warm, organic typography with personal character.

Characteristics:

• Hand-lettered or brush style
• Organic, varied line weight
• Natural imperfections
• Approachable, human feel
• Casual yet intentional

Use Cases:

• Personal stories
• Lifestyle content
• Wellness and self-improvement
• Creative tutorials
• Friendly brand voices

Prompt Hints:

• Use warm hand-lettered typography with organic brush strokes
• Friendly, personal feel
• Natural variation in stroke weight
• Approachable, human character

serif

Classic, elegant typography with editorial authority.

Characteristics:

• Traditional serif letterforms
• Refined, structured strokes
• Elegant proportions
• Timeless sophistication
• Formal, trustworthy feel

Use Cases:

• Editorial content
• Academic articles
• Luxury brand content
• Historical topics
• Literary pieces

Prompt Hints:

• Use elegant serif typography with refined letterforms
• Classic, editorial character
• Structured, proportional spacing
• Authoritative, sophisticated feel

display

Bold, decorative typography for maximum impact.

Characteristics:

• Heavy, expressive letterforms
• Decorative elements
• Strong visual presence
• Playful or dramatic character
• Designed for headlines

Use Cases:

• Announcements
• Entertainment content
• Promotional materials
• Event marketing
• Gaming topics

Prompt Hints:

• Use bold decorative display typography
• Heavy, expressive headlines
• Strong visual impact
• Attention-grabbing character

Default

clean — Universal, pairs well with most rendering styles.

Rendering Compatibility

✓✓ = highly recommended | ✓ = compatible | ✗ = not recommended

Type Compatibility

Palette Interaction

Font style adapts to palette characteristics:

Auto Selection

When --font is omitted, select based on signals:

Default: clean

Mood Dimension

Controls emotional intensity and visual weight of cover images.

Values

Detail

subtle

Calm, understated visual presence.

Characteristics:

• Low contrast between elements
• Muted, desaturated colors
• Light visual weight
• Gentle, refined aesthetic
• Soft edges and transitions

Use Cases:

• Thought leadership content
• Professional/corporate communications
• Meditation, wellness topics
• Academic or scholarly articles
• Luxury brand aesthetics

Color Guidance:

• Pastels, earth tones, neutrals
• Low saturation (30-50%)
• Soft gradients
• Minimal color variety (2-3 colors)

balanced

Versatile, harmonious visual presence.

Characteristics:

• Medium contrast
• Natural saturation levels
• Balanced visual weight
• Clear but not aggressive
• Standard aesthetic approach

Use Cases:

• General articles (default)
• Most blog content
• Educational material
• Product documentation
• News and updates

Color Guidance:

• Standard saturation (50-70%)
• Complementary color schemes
• Clear foreground/background separation
• Moderate color variety (3-4 colors)

bold

Dynamic, high-impact visual presence.

Characteristics:

• High contrast between elements
• Vivid, saturated colors
• Heavy visual weight
• Energetic, attention-grabbing
• Sharp edges and strong shapes

Use Cases:

• Product launches
• Promotional announcements
• Event marketing
• Call-to-action content
• Entertainment/gaming topics

Color Guidance:

• High saturation (70-100%)
• Vibrant, primary colors
• Strong contrast ratios
• Dynamic color combinations (4+ colors)

Type Compatibility

✓✓ = highly recommended | ✓ = compatible | ✗ = not recommended

Palette Interaction

Mood modifies the base palette characteristics:

Rendering Interaction

Mood adjusts rendering characteristics:

Auto Selection

When --mood is omitted, select based on signals:

Default: balanced

Text Dimension

Controls text density and information hierarchy on cover images.

Values

Detail

none

Pure visual cover with no text elements.

Use Cases:

• Photography-focused covers
• Abstract art pieces
• Visual-only social sharing
• When title added externally

Composition:

• Full visual area available
• No reserved text zones
• Emphasis on visual metaphor

title-only

Single headline, maximum impact.

Use Cases:

• Most article covers (default)
• Clear single message
• Strong brand recognition

Composition:

• Title: prominent placement
• Reserved zone: top or bottom 15%
• Visual supports title message

Title Guidelines:

• Use exact title from source content or user-provided title
• Do NOT invent or modify titles
• Match content language

title-subtitle

Title with supporting context.

Use Cases:

• Technical articles needing clarification
• Series with episode/part info
• Content with dual messages

Composition:

• Title: primary element
• Subtitle: secondary element
• Reserved zone: 25%
• Clear hierarchy between title/subtitle

Title Guidelines:

• Use exact title from source content or user-provided title
• Do NOT invent or modify titles

Subtitle Guidelines:

• Clarify or contextualize title
• Can include series name, author, date
• Smaller, less prominent than title

text-rich

Information-dense cover with multiple text elements.

Use Cases:

• Infographic-style covers
• Event announcements with details
• Promotional material with features
• Content with multiple key points

Composition:

• Title: primary focus
• Subtitle: supporting info
• Tags: 2-4 keyword labels
• Reserved zone: 40%
• Clear visual hierarchy

Title Guidelines:

• Use exact title from source content or user-provided title
• Do NOT invent or modify titles

Tag Guidelines:

• 2-4 tags maximum
• Short keywords (1-2 words each)
• Positioned as badges/labels
• Can highlight: category, date, author, key features

Type Compatibility

✓✓ = highly recommended | ✓ = compatible | ✗ = not recommended

Auto Selection

When --text is omitted, select based on signals:

Default: title-only

cool

Technical, professional, precise

Color Palette

Decorative Hints

• Grid lines and alignment guides
• Dimension indicators and measurements
• Technical schematics and diagrams
• Geometric precision elements

Semantic Constraint

Do NOT render color names, hex codes, or role labels as visible text in the image.

Best For

Architecture, system design, API, technical documentation, engineering, data analysis

dark

Cinematic, premium, atmospheric

Color Palette

Decorative Hints

• Glowing accent elements and neon highlights
• Atmospheric fog or particle effects
• Silhouettes with backlit edges
• Subtle gradient backgrounds

Semantic Constraint

Do NOT render color names, hex codes, or role labels as visible text in the image.

Best For

Entertainment, premium brands, cinematic storytelling, dark mode, gaming, night themes

duotone

Dramatic, cinematic, two-color high contrast

Color Palette

Duotone Pair Options

Choose ONE pair based on content mood. The two colors dominate the entire image:

Decorative Hints

• Stark two-color separation across entire composition
• Halftone transitions between the two colors
• Silhouettes in one color against the other
• Minimal use of third color (only for small highlights)
• High contrast figure-ground relationships

Semantic Constraint

Do NOT render color names, hex codes, or role labels as visible text in the image.

Best For

Movie posters, album covers, concert prints, dramatic announcements, cinematic content, bold branding, editorial covers, artistic campaigns

earth

Natural, organic, grounded

Color Palette

Decorative Hints

• Leaves, trees, mountains, natural forms
• Sun, clouds, organic flowing lines
• Botanical illustrations
• Earthy textures and natural patterns

Semantic Constraint

Do NOT render color names, hex codes, or role labels as visible text in the image.

Best For

Nature, wellness, eco, organic, travel, sustainability, outdoor topics, slow living

elegant

Sophisticated, refined, understated luxury

Color Palette

Decorative Hints

• Delicate ornamental details
• Subtle gradients and soft transitions
• Refined geometric patterns
• Balanced, symmetrical compositions

Semantic Constraint

Do NOT render color names, hex codes, or role labels as visible text in the image.

Best For

Business, professional, thought leadership, luxury, corporate communications

macaron

Soft macaron pastel color blocks on warm cream

Color Palette

Decorative Hints

• Rounded pastel color blocks
• Subtle warm paper grain texture
• Soft shadows, no hard edges
• Gentle gradient transitions between zones

Semantic Constraint

Do NOT render color names, hex codes, or role labels as visible text in the image.

Best For

Educational content, knowledge sharing, concept explainers, tutorials, tech summaries, onboarding materials

mono

Clean, focused, essential

Color Palette

Decorative Hints

• Maximum negative space
• Thin lines and minimal strokes
• Single focal point emphasis
• Stark contrast between elements

Semantic Constraint

Do NOT render color names, hex codes, or role labels as visible text in the image.

Best For

Zen, focus, essential concepts, pure, simple, minimalist philosophy, clean design

pastel

Gentle, whimsical, soft

Color Palette

Decorative Hints

• Cute rounded proportions
• Stars, sparkles, flowers, decorative flourishes
• Soft shadows and gentle highlights
• Storybook-style elements

Semantic Constraint

Do NOT render color names, hex codes, or role labels as visible text in the image.

Best For

Fantasy, children, gentle content, creative, whimsical, casual, beginner guides

retro

Nostalgic, vintage, classic

Color Palette

Decorative Hints

• Halftone dots and vintage badges
• Aged textures with subtle paper grain
• Sunburst/radiating lines for energy
• Pill-shaped clouds, small dots and stars
• Classic icons and retro motifs

Semantic Constraint

Do NOT render color names, hex codes, or role labels as visible text in the image.

Best For

History, vintage, retro, classic, exploration, retrospectives, throwback content, creative proposals, educational

vivid

Energetic, bold, attention-grabbing

Color Palette

Decorative Hints

• Dynamic diagonal lines and angles
• Bold geometric shapes and color blocks
• Dramatic lighting effects
• High-energy visual compositions

Semantic Constraint

Do NOT render color names, hex codes, or role labels as visible text in the image.

Best For

Product launch, gaming, promotion, event, marketing, announcements, brand showcases

warm

Friendly, approachable, human-centered

Color Palette

Decorative Hints

• Sun rays, warm lighting effects
• Rounded shapes, organic curves
• Hearts, smiling faces, friendly icons
• Warm gradient overlays

Semantic Constraint

Do NOT render color names, hex codes, or role labels as visible text in the image.

Best For

Personal growth, lifestyle, education, human stories, emotion, community

chalk

Educational, authentic, classroom

Core Characteristics

Chalk on blackboard aesthetic with imperfect strokes, dust effects, and authentic classroom feel. Nostalgic educational warmth.

Lines

• Imperfect chalk strokes with variable pressure
• Visible chalk texture and grain
• Slightly wobbly, hand-drawn quality
• Thick strokes for emphasis, thin for details

Texture

• Chalk dust effects around text and elements
• Board surface (dark, slightly worn)
• Eraser smudges and residue
• Grainy chalk quality on all elements

Depth

• None: flat chalk drawings on board surface
• Layering through erasure and redrawing
• No shadows or perspective

Element Vocabulary

• Chalk doodles: stars, arrows, underlines
• Mathematical formulas and diagrams
• Stick figures and simple icons
• Connection lines with chalk feel
• Checkmarks, circles, boxes for lists
• Wooden frame border optional

Typography Approach

• Hand-drawn chalk lettering
• Imperfect baseline, authentic classroom feel
• White or bright colored chalk for emphasis
• Variable sizing for hierarchy

digital

Polished, precise, modern

Core Characteristics

Clean digital illustration with polished finish, precise edges, and subtle modern effects. Feels like a professional UI mockup or corporate illustration.

Lines

• Clean, precise, computer-perfect edges
• Consistent stroke weights
• Sharp corners where appropriate
• Anti-aliased smooth rendering

Texture

• Smooth surfaces with no visible texture
• Subtle gradients permitted (soft, controlled)
• Frosted glass and blur effects
• Clean shadows with consistent direction

Depth

• Subtle gradients and soft drop shadows
• Layered card-based layouts
• Light 3D effects (subtle, not realistic)
• Material Design-inspired elevation

Element Vocabulary

• Polished icons and UI components
• Data visualizations: charts, graphs, metrics
• Card layouts and structured grids
• Tag chips, progress bars, status indicators
• Clean geometric shapes

Typography Approach

• System UI or modern sans-serif (Inter, SF Pro style)
• Clean, functional, high readability
• Structured hierarchy with consistent spacing

flat-vector

Clean, modern, geometric illustration

Core Characteristics

Flat design with clean outlines, uniform fills, and no texture or depth. Think modern app icons, infographic illustrations, and vector-based editorial art.

Lines

• Clean outlines with uniform stroke weight
• Closed shapes (coloring-book style)
• Rounded line endings, avoid sharp corners
• Consistent stroke width throughout

Texture

• None: smooth, flat color fills only
• No gradients, shadows, or noise
• Solid color blocks

Depth

• Flat: no shadows, no perspective
• 2D layering with overlap for depth illusion
• Optional 2.5D isometric layering (front/back occlusion, no atmospheric perspective)
• No 3D effects or bevels

Element Vocabulary

• Geometric icons and simple shapes
• Bold outlined objects with clean fills
• Geometric simplification: complex objects → basic shapes (trees → lollipop/triangle, buildings → rectangles)
• "Toy model" aesthetic: cute, rounded proportions
• Decorative: dots, lines, sunbursts, pill-shaped clouds, small stars
• Isolated elements on clean backgrounds

Typography Approach

• Clean sans-serif or bold geometric lettering
• Strong readability, consistent weight
• Easily scalable at any size

hand-drawn

Sketchy, organic, personal

Core Characteristics

Hand-drawn illustration with visible imperfections, organic line quality, and personal touch. Feels like a skilled artist's sketchbook or whiteboard drawing.

Lines

• Sketchy, organic, slightly imperfect strokes
• Variable line weight (thicker at pressure points)
• Wavy connectors and arrows
• Natural hand tremor visible

Texture

• Paper grain and subtle surface texture
• Pencil/pen/marker texture on strokes
• Casual fills with visible brush direction

Depth

• Minimal: light hand-drawn shadows or hatching
• No realistic depth or perspective
• Simple layering with overlap

Element Vocabulary

• Doodles, organic shapes, hand-lettered labels
• Conceptual icons with sketchy quality
• Connection lines with hand-drawn wavy feel
• Stars, arrows, underlines, circles, checkmarks
• Stick figures and simple characters

Typography Approach

• Hand-lettered or marker-style text
• Bouncy baselines, organic feel
• Variable sizes for emphasis hierarchy

painterly

Soft, artistic, expressive

Core Characteristics

Watercolor or paint-style illustration with visible brush strokes, color bleeds, and artistic texture. Feels like a hand-painted art piece.

Lines

• Soft brush strokes with variable opacity
• No hard outlines; edges defined by color transitions
• Organic flowing strokes with natural blending

Texture

• Visible paint or watercolor wash textures
• Color bleeds and wet-on-wet effects
• Paper texture showing through transparent areas
• Brush stroke patterns visible

Depth

• Soft edges with natural color blending
• Atmospheric depth through color fading
• Layered washes creating depth illusion

Element Vocabulary

• Watercolor washes as backgrounds
• Natural elements: leaves, flowers, organic forms
• Soft gradients and color transitions
• Splatter and drip effects as accents
• Botanical and environmental motifs

Typography Approach

• Elegant brush script or handwritten style
• Organic letterforms with brush texture
• Integrated with paint environment

pixel

Retro 8-bit, nostalgic, chunky

Core Characteristics

Pixel art aesthetic with visible pixel grid, limited color palette, and nostalgic gaming feel. Emulates classic 8-bit and 16-bit era graphics.

Lines

• Pixel grid alignment, no anti-aliasing
• Staircase edges on diagonals
• Single-pixel or double-pixel outlines
• Blocky, angular forms

Texture

• Dithering patterns for gradients
• No smooth transitions
• Cross-hatching with pixel precision
• Limited 16-32 color palette per scene

Depth

• None: flat pixel planes only
• Parallax layering (foreground/background)
• No perspective or 3D effects

Element Vocabulary

• 8-bit sprites and chunky shapes
• Simple iconography: stars, hearts, arrows
• Text bubbles with pixel borders
• Progress bars with chunky segments
• Retro gaming UI elements

Typography Approach

• Pixelated bitmap font style
• Chunky blocky letterforms
• Fixed-width or monospace feel
• All-caps for headers

screen-print

Bold, limited-color poster art with print texture

Core Characteristics

Screen print / silkscreen aesthetic with flat color blocks, halftone textures, and deliberate print imperfections. Think Mondo limited-edition posters, vintage concert prints, and alternative movie poster art.

Lines

• Clean, sharp edges between color blocks
• No outlines — shapes defined by color boundaries
• Stencil-cut quality, bold silhouettes
• Geometric shapes with precise registration

Texture

• Halftone dot patterns within color fills
• Slight color layer misregistration (offset between print layers)
• Paper grain texture beneath colors
• Risograph / screen print imperfections (ink spread, dot gain)

Depth

• Flat color planes layered front to back
• Depth through silhouette overlap and color layering
• No gradients — tonal variation via halftone density
• Negative space as active compositional element

Element Vocabulary

• Bold silhouettes and symbolic shapes
• Geometric framing (circles, arches, triangles)
• Figure-ground inversion (negative space forms secondary image)
• Limited icon vocabulary: key props, symbolic objects
• Typography integrated as design element, not overlay
• Vintage poster border treatments

Typography Approach

• Bold condensed sans-serif or hand-drawn lettering
• Art Deco influences, vintage poster typography
• Typography as integral part of composition (not separate layer)
• Strong readability through high contrast with background

Style Presets

--style X expands to a palette + rendering combination. Users can override either dimension.

Override Examples

• --style blueprint --rendering hand-drawn = cool palette with hand-drawn rendering
• --style elegant --palette warm = warm palette with hand-drawn rendering

Explicit --palette/--rendering flags always override preset values.

Type Composition Guidelines

Type Gallery

Type-Specific Composition

Visual Elements Library

Icon and symbol vocabulary organized by topic. Use these as building blocks for cover compositions.

Tech & Development

Ideas & Innovation

Communication & Collaboration

Nature & Growth

Tools & Actions

Abstract Concepts

Combination Patterns

Create visual metaphors by combining elements:

Rendering-Specific Treatment

Step 2: Confirm Options

Purpose

Validate all 6 dimensions + aspect ratio.

Skip Conditions

Important: Aspect ratio is ALWAYS asked unless explicitly specified via --aspect CLI flag. User presets in EXTEND.md are shown as recommended option, not auto-selected.

Quick Mode Output

When skipping 6 dimensions:

Quick Mode: Auto-selected dimensions
• Type: [type] ([reason])
• Palette: [palette] ([reason])
• Rendering: [rendering] ([reason])
• Text: [text] ([reason])
• Mood: [mood] ([reason])
• Font: [font] ([reason])

[Then ask Question 7: Aspect Ratio]

Confirmation Flow

Language: Auto-determined (user's input language > saved preference > source language). No need to ask.

Present ALL options in a single AskUserQuestion call (4 questions max).

Skip any question where the dimension is already specified via CLI flag or --style preset.

Q1: Type (skip if --type)

header: "Type"
question: "Which cover type?"
multiSelect: false
options:
  - label: "[auto-recommended type] (Recommended)"
    description: "[reason based on content signals]"
  - label: "hero"
    description: "Large visual impact, title overlay - product launch, announcements"
  - label: "conceptual"
    description: "Concept visualization - technical, architecture"
  - label: "typography"
    description: "Text-focused layout - opinions, quotes"

Q2: Palette (skip if --palette or --style)

header: "Palette"
question: "Which color palette?"
multiSelect: false
options:
  - label: "[auto-recommended palette] (Recommended)"
    description: "[reason based on content signals]"
  - label: "warm"
    description: "Friendly - orange, golden yellow, terracotta"
  - label: "elegant"
    description: "Sophisticated - soft coral, muted teal, dusty rose"
  - label: "cool"
    description: "Technical - engineering blue, navy, cyan"

Q3: Rendering (skip if --rendering or --style)

Show compatible renderings (✓✓ first from compatibility matrix):

header: "Rendering"
question: "Which rendering style?"
multiSelect: false
options:
  - label: "[best compatible rendering] (Recommended)"
    description: "[reason based on palette + type + content]"
  - label: "flat-vector"
    description: "Clean outlines, flat fills, geometric icons"
  - label: "hand-drawn"
    description: "Sketchy, organic, imperfect strokes"
  - label: "digital"
    description: "Polished, precise, subtle gradients"

Q4: Font (skip if --font)

header: "Font"
question: "Which font style?"
multiSelect: false
options:
  - label: "[auto-recommended font] (Recommended)"
    description: "[reason based on content signals]"
  - label: "clean"
    description: "Modern geometric sans-serif - tech, professional"
  - label: "handwritten"
    description: "Warm hand-lettered - personal, friendly"
  - label: "serif"
    description: "Classic elegant - editorial, luxury"
  - label: "display"
    description: "Bold decorative - announcements, entertainment"

Q5: Other Settings (skip if all remaining dimensions already specified)

Combine remaining settings into one question. Include: Output Dir (if no preference + file path input), Text, Mood, Aspect. Show auto-selected values as recommended option. User can accept all or type adjustments via "Other".

When output dir needs asking (no default_output_dir preference + file path input):

header: "Settings"
question: "Output / Text / Mood / Aspect?"
multiSelect: false
options:
  - label: "imgs/ / [auto-text] / [auto-mood] / [preset-aspect] (Recommended)"
    description: "{article-dir}/imgs/, [text reason], [mood reason], [aspect source]"
  - label: "same-dir / [auto-text] / [auto-mood] / [preset-aspect]"
    description: "{article-dir}/, same directory as article"
  - label: "independent / [auto-text] / [auto-mood] / [preset-aspect]"
    description: "cover-image/{topic-slug}/, separate from article"

When output dir already set (preference exists or pasted content):

header: "Settings"
question: "Text / Mood / Aspect?"
multiSelect: false
options:
  - label: "[auto-text] / [auto-mood] / [preset-aspect] (Recommended)"
    description: "Auto-selected: [text reason], [mood reason], [aspect source]"
  - label: "[auto-text] / bold / [preset-aspect]"
    description: "High contrast, vivid — matches [content signal]"
  - label: "[auto-text] / subtle / [preset-aspect]"
    description: "Low contrast, muted — calm, professional"

Note: "Other" (auto-added) allows typing custom combo. Parse /-separated values matching the question format.

After Response

Proceed to Step 3 with confirmed dimensions.

Step 3: Prompt Template

Save to prompts/cover.md:

---
type: cover
palette: [confirmed palette]
rendering: [confirmed rendering]
references:
  - ref_id: 01
    filename: refs/ref-01-{slug}.{ext}
    usage: direct | style | palette
  - ref_id: 02
    filename: refs/ref-02-{slug}.{ext}
    usage: direct | style | palette
---

# Content Context
Article title: [full original title from source]
Content summary: [2-3 sentence summary of key points and themes]
Keywords: [5-8 key terms extracted from content]

# Visual Design
Cover theme: [2-3 words visual interpretation]
Type: [confirmed type]
Palette: [confirmed palette]
Rendering: [confirmed rendering]
Font: [confirmed font]
Text level: [confirmed text level]
Mood: [confirmed mood]
Aspect ratio: [confirmed ratio]
Language: [confirmed language]

# Text Elements
[Based on text level:]
- none: "No text elements"
- title-only: "Title: [exact title from source or user]"
- title-subtitle: "Title: [title] / Subtitle: [context]"
- text-rich: "Title: [title] / Subtitle: [context] / Tags: [2-4 keywords]"

# Mood Application
[Based on mood level:]
- subtle: "Use low contrast, muted colors, light visual weight, calm aesthetic"
- balanced: "Use medium contrast, normal saturation, balanced visual weight"
- bold: "Use high contrast, vivid saturated colors, heavy visual weight, dynamic energy"

# Font Application
[Based on font style:]
- clean: "Use clean geometric sans-serif typography. Modern, minimal letterforms."
- handwritten: "Use warm hand-lettered typography with organic brush strokes. Friendly, personal feel."
- serif: "Use elegant serif typography with refined letterforms. Classic, editorial character."
- display: "Use bold decorative display typography. Heavy, expressive headlines."

# Composition
Type composition:
- [Type-specific layout and structure]

Visual composition:
- Main visual: [metaphor derived from content meaning]
- Layout: [positioning based on type and aspect ratio]
- Decorative: [palette-specific elements that reinforce content theme]

Color scheme: [primary, background, accent from palette definition, adjusted by mood]
Color constraint: Color values (#hex) and color names are rendering guidance only — do NOT display color names, hex codes, or palette labels as visible text in the image.
Rendering notes: [key characteristics from rendering definition — lines, texture, depth, element style]
Type notes: [key characteristics from type definition]
Palette notes: [key characteristics from palette definition]

[Watermark section if enabled]

[Reference images section if provided — REQUIRED, see below]

Reference-Driven Design ⚠️ HIGH PRIORITY

When reference images are provided, they are the primary visual input and MUST strongly influence the output. The cover should look like it belongs to the same visual family as the references.

Passing `--ref` alone is NOT enough. Image generation models often ignore reference images unless the prompt text explicitly describes what to reproduce. Always combine --ref with detailed textual instructions.

Content-Driven Design

• Article title and summary inform the visual metaphor choice
• Keywords guide decorative elements and symbols
• The skill controls visual style; the content drives meaning

Visual Element Selection

Match content themes to icon vocabulary:

Full library: ../visual-elements.md

Type-Specific Composition

Title Guidelines

When text level includes title:

• Source: Use the exact title provided by user, or extract from source content
• Do NOT invent titles: Stay faithful to the original
• Match confirmed language

Watermark Application

If enabled in preferences, add to prompt:

Include a subtle watermark "[content]" positioned at [position].
The watermark should be legible but not distracting from the main content.

Reference: config/watermark-guide.md

Reference Image Handling

When user provides reference images (--ref or pasted images):

⚠️ CRITICAL - Frontmatter References

MUST add `references` field in YAML frontmatter when reference files are saved to refs/:

---
type: cover
palette: warm
rendering: flat-vector
references:
  - ref_id: 01
    filename: refs/ref-01-podcast-thumbnail.jpg
    usage: style
---

Omit `references` field entirely if no reference files saved (style extracted verbally only).

When to Include References in Frontmatter

Before writing prompt with references, verify: test -f refs/ref-NN-{slug}.{ext}

Reference Usage Types

Step 1: Analyze References

For each reference image, extract:

• Style: Rendering technique, line quality, texture
• Composition: Layout, visual hierarchy, focal points
• Color mood: Palette characteristics (without specific colors)
• Elements: Key visual elements and symbols used

Step 2: Embed in Prompt ⚠️ CRITICAL

Passing `--ref` alone is NOT enough. Image generation models frequently ignore reference images unless the prompt text explicitly and forcefully describes what to reproduce. You MUST always write detailed textual instructions regardless of whether --ref is used.

If file saved (with or without `--ref` support):

• Pass ref images via --ref parameter if skill supports it
• ALWAYS add a detailed mandatory section in the prompt body:

# Reference Style — MUST INCORPORATE

CRITICAL: The generated cover MUST visually reference the provided images. The cover must feel like it belongs to the same visual family.

## From Ref 1 ([filename]) — REQUIRED elements:
- [Brand element]: [Specific description of logo/wordmark treatment, e.g., "The logo uses vertical parallel lines (|||) for the letter 'm'. Reproduce this exact treatment."]
- [Signature pattern]: [Specific description, e.g., "Woven intersecting curves forming a diamond/lozenge grid pattern. This MUST appear prominently as a banner, border, or background section."]
- [Colors]: [Exact hex values, e.g., "Dark teal #2D4A3E background, cream #F5F0E0 text"]
- [Typography]: [Specific treatment, e.g., "Uppercase text with wide letter-spacing"]
- [Layout element]: [Specific spatial element, e.g., "Bottom banner strip in dark color"]

## From Ref 1 ([filename]) — Characters (if people present):
- **Character 1**: [Appearance, e.g., "Woman, long wavy blonde hair"] → MUST stylize: [e.g., "flat-vector, simplified face, keep blonde hair, label: 'Nicole Forsgren'"]
- **Character 2**: [Appearance, e.g., "Man, short dark hair, stubble"] → MUST stylize: [e.g., "flat-vector, simplified face, keep dark hair, label: 'Gergely Orosz'"]
- **Placement**: [e.g., "Right third, side by side, facing left toward main visual"]
- **Style**: Match rendering style, NOT photorealistic

## From Ref 2 ([filename]) — REQUIRED elements:
[Same detailed breakdown]

## Integration approach:
[Specific layout instruction describing how reference elements combine with the cover content, e.g., "Use a SPLIT LAYOUT: main illustration area (warm cream background) occupies ~65% of the image, while a dark teal BANNER STRIP (with the woven line pattern from Ref 2) runs along the bottom ~35%, containing branding elements from Ref 1."]

Key rules:

• Each visual element gets its own bullet with "MUST" or "REQUIRED"
• Descriptions must be specific enough to reproduce — not vague ("clean style")
• The integration approach must describe exact spatial arrangement
• After generation, verify reference elements are visible; if not, strengthen and regenerate

If style/palette extracted verbally (NO file saved):

• DO NOT add references metadata to prompt
• Append extracted info directly to prompt body using the same MUST INCORPORATE format above:

# Reference Style — MUST INCORPORATE (extracted from visual analysis)

CRITICAL: Apply these specific visual elements extracted from the reference images.

## REQUIRED elements:
- [Same detailed bullet format as above]

## Integration approach:
[Same spatial layout instruction]

Reference Analysis Template

Use this format when analyzing reference images. Extract specific, concrete, reproducible details — not vague summaries.

Output: Each extracted element should be written as a copy-pasteable prompt instruction prefixed with "MUST" or "REQUIRED".

Reference Image Handling

Guide for processing user-provided reference images in cover generation.

Input Detection

CRITICAL: Only add references to prompt frontmatter if files are ACTUALLY SAVED to refs/ directory.

File Saving

If user provides file path: 1. Copy to refs/ref-NN-{slug}.{ext} (NN = 01, 02, ...) 2. Only create description file refs/ref-NN-{slug}.md when model does NOT support --ref (see below) 3. Verify image file exists before proceeding

When to create description file:

Description File Format (only when needed):

---
ref_id: NN
filename: ref-NN-{slug}.{ext}
usage: direct | style | palette
---
[Character or style description to embed in prompt]

Verbal Extraction (No File)

When user can't provide file path: 1. Analyze image visually, extract: colors, style, composition 2. Create refs/extracted-style.md with extracted info 3. DO NOT add references to prompt frontmatter 4. Append extracted style/colors directly to prompt text

Deep Analysis ⚠️ CRITICAL

References are high-priority inputs. Extract specific, concrete, reproducible elements:

Output format: List each element as bullet that can be copy-pasted into prompt as mandatory instruction.

Character Analysis ⚠️ If Reference Contains People

Use usage: direct so model sees the reference image. Additionally describe per character: appearance, pose, clothing → with transformation rules (stylize to match rendering).

Use usage: direct. Output each character as MUST/REQUIRED prompt instruction.

Verification Output

For saved files:

Reference Images Saved:
- ref-01-{slug}.png ✓ (can use --ref)
- ref-02-{slug}.png ✓ (can use --ref)

For extracted style:

Reference Style Extracted (no file):
- Colors: #E8756D coral, #7ECFC0 mint...
- Style: minimal flat vector, clean lines...
→ Will append to prompt text (not --ref)

Priority Rules

When user provides references, they are HIGH PRIORITY:

• References override defaults: If reference conflicts with preferred palette/rendering, reference takes precedence
• Concrete > abstract: Extract specific elements — not vague "clean style"
• Mandatory language: Use "MUST", "REQUIRED" in prompt for reference elements
• Visible in output: Verify elements are present after generation; strengthen prompt if not