1# Reference Image Handling
2 
3Guide for processing user-provided reference images in cover generation.
4 
5## Input Detection
6 
7| Input Type | Action |
8|------------|--------|
9| Image file path provided | Copy to `refs/` → can use `--ref` |
10| Image in conversation (no path) | **ASK user for file path** with AskUserQuestion |
11| User can't provide path | Extract style/palette verbally → append to prompt (NO frontmatter references) |
12 
13**CRITICAL**: Only add `references` to prompt frontmatter if files are ACTUALLY SAVED to `refs/` directory.
14 
15## File Saving
16 
17**If user provides file path**:
181. Copy to `refs/ref-NN-{slug}.{ext}` (NN = 01, 02, ...)
192. **Only** create description file `refs/ref-NN-{slug}.md` when model does NOT support `--ref` (see below)
203. Verify image file exists before proceeding
21 
22**When to create description file**:
23 
24| Situation | Action |
25|-----------|--------|
26| Model supports `--ref` (Google, OpenAI, OpenRouter, Replicate, Seedream 4.0+) | Copy image only. **No description file needed.** Pass via `--ref` at generation. |
27| Model does NOT support `--ref` (Jimeng, Seedream 3.0) | Copy image + create description file. Embed description in prompt text. |
28 
29**Description File Format** (only when needed):
30```yaml
31---
32ref_id: NN
33filename: ref-NN-{slug}.{ext}
34usage: direct | style | palette
35---
36[Character or style description to embed in prompt]
37```
38 
39| Usage | When to Use |
40|-------|-------------|
41| `direct` | Model sees reference image directly; required if people must appear in output |
42| `style` | Extract visual style only (not for people who must appear) |
43| `palette` | Extract color scheme only |
44 
45## Verbal Extraction (No File)
46 
47When user can't provide file path:
481. Analyze image visually, extract: colors, style, composition
492. Create `refs/extracted-style.md` with extracted info
503. DO NOT add `references` to prompt frontmatter
514. Append extracted style/colors directly to prompt text
52 
53## Deep Analysis ⚠️ CRITICAL
54 
55References are high-priority inputs. Extract **specific, concrete, reproducible** elements:
56 
57| Analysis | Description | Example (good vs bad) |
58|----------|-------------|----------------------|
59| **Brand elements** | Logos, wordmarks, specific typography | Good: "Logo uses vertical parallel lines for 'm'" / Bad: "Has a logo" |
60| **Signature patterns** | Unique decorative motifs, textures | Good: "Woven intersecting curves forming diamond grid" / Bad: "Has patterns" |
61| **Color palette** | Exact hex values for key colors | Good: "#2D4A3E dark teal, #F5F0E0 cream" / Bad: "Dark and light colors" |
62| **Layout structure** | Specific spatial arrangement | Good: "Bottom 30% dark banner with branding" / Bad: "Has a banner" |
63| **Typography** | Font style, weight, spacing, case | Good: "Uppercase, wide letter-spacing" / Bad: "Has text" |
64| **Content/subject** | What the reference depicts | Factual description |
65| **Usage recommendation** | `direct` / `style` / `palette` | Based on analysis |
66 
67**Output format**: List each element as bullet that can be copy-pasted into prompt as mandatory instruction.
68 
69### Character Analysis ⚠️ If Reference Contains People
70 
71Use `usage: direct` so model sees the reference image. Additionally describe per character: **appearance**, **pose**, **clothing** → with **transformation rules** (stylize to match rendering).
72 
73| Extract | Good | Bad |
74|---------|------|-----|
75| Appearance | "Woman: long wavy blonde hair, friendly smile" | "A woman" |
76| Pose | "Standing, facing camera, confident posture" | "Standing" |
77| Clothing | "Dark T-shirt, business casual" | "Formal" |
78| Transform | "Flat-vector cartoon, keep hair color & clothing" | "Make cartoon" |
79 
80Use `usage: direct`. Output each character as MUST/REQUIRED prompt instruction.
81 
82## Verification Output
83 
84**For saved files**:
85```
86Reference Images Saved:
87- ref-01-{slug}.png ✓ (can use --ref)
88- ref-02-{slug}.png ✓ (can use --ref)
89```
90 
91**For extracted style**:
92```
93Reference Style Extracted (no file):
94- Colors: #E8756D coral, #7ECFC0 mint...
95- Style: minimal flat vector, clean lines...
96→ Will append to prompt text (not --ref)
97```
98 
99## Priority Rules
100 
101When user provides references, they are **HIGH PRIORITY**:
102 
103- **References override defaults**: If reference conflicts with preferred palette/rendering, reference takes precedence
104- **Concrete > abstract**: Extract specific elements — not vague "clean style"
105- **Mandatory language**: Use "MUST", "REQUIRED" in prompt for reference elements
106- **Visible in output**: Verify elements are present after generation; strengthen prompt if not
107