feat(baoyu-article-illustrator): add reference image support

- Add reference image handling with direct/style/palette usage types
- Enhance first-time setup as blocking operation
- Update prompt construction with reference frontmatter format

skills/baoyu-article-illustrator/SKILL.md

@@ -60,10 +60,22 @@ Copy this checklist and track progress:
 ```
 Progress:
 - [ ] Step 1: Pre-check
+  - [ ] 1.5 Check preferences (EXTEND.md) ⛔ BLOCKING
+    - [ ] Found → load preferences → continue
+    - [ ] Not found → run first-time setup → MUST complete before other steps
+  - [ ] 1.0 Reference images ⚠️ (if provided)
+    - [ ] File path given → saved to references/ ✓
+    - [ ] No path → asked user OR extracted verbally
+  - [ ] 1.2-1.4 Config questions (1 AskUserQuestion, max 4 Qs)
 - [ ] Step 2: Setup & Analyze
-- [ ] Step 3: Confirm Settings ⚠️ REQUIRED
+- [ ] Step 3: Confirm Settings (1 AskUserQuestion, max 4 Qs)
+  - [ ] Q1: Type ⚠️
+  - [ ] Q2: Density ⚠️ MUST ASK
+  - [ ] Q3: Style ⚠️
 - [ ] Step 4: Generate Outline
 - [ ] Step 5: Generate Images
+  - [ ] 5.1 Prompts created (references in frontmatter ONLY if files exist)
+  - [ ] 5.3 References verified before generation
 - [ ] Step 6: Finalize
 ```
 
@@ -71,6 +83,55 @@ Progress:
 
 ### Step 1: Pre-check
 
+**1.0 Detect & Save Reference Images** ⚠️ REQUIRED if images provided
+
+Check if user provided reference images. Handle based on input type:
+
+| Input Type | Action |
+|------------|--------|
+| Image file path provided | Copy to `references/` subdirectory → can use `--ref` |
+| Image in conversation (no path) | **ASK user for file path** with AskUserQuestion |
+| User can't provide path | Extract style/palette verbally → append to prompts (NO frontmatter references) |
+
+**CRITICAL**: Only add `references` to prompt frontmatter if files are ACTUALLY SAVED to `references/` directory.
+
+**If user provides file path**:
+1. Copy to `references/NN-ref-{slug}.png`
+2. Create description: `references/NN-ref-{slug}.md`
+3. Verify files exist before proceeding
+
+**If user can't provide path** (extracted verbally):
+1. Analyze image visually, extract: colors, style, composition
+2. Create `references/extracted-style.md` with extracted info
+3. DO NOT add `references` to prompt frontmatter
+4. Instead, append extracted style/colors directly to prompt text
+
+**Description File Format** (only when file saved):
+```yaml
+---
+ref_id: NN
+filename: NN-ref-{slug}.png
+---
+[User's description or auto-generated description]
+```
+
+**Verification** (only for saved files):
+```
+Reference Images Saved:
+- 01-ref-{slug}.png ✓ (can use --ref)
+- 02-ref-{slug}.png ✓ (can use --ref)
+```
+
+**Or 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)
+```
+
+---
+
 **1.1 Determine Input Type**
 
 | Input | Output Directory | Next |
@@ -80,41 +141,30 @@ Progress:
 
 **Backup rule for pasted content**: If `source.md` exists in target directory, rename to `source-backup-YYYYMMDD-HHMMSS.md` before saving.
 
-**1.2 Determine Output Directory** (file path input only)
+**1.2-1.4 Configuration** (file path input only)
 
-Check `default_output_dir` in preferences:
+Check preferences and existing state, then ask ALL needed questions in ONE AskUserQuestion call (max 4 questions).
 
-| Preference Value | Action |
+**Questions to include** (skip if preference exists or not applicable):
-|------------------|--------|
-| `same-dir` | Use `{article-dir}/`, display "Output: {path}" |
-| `imgs-subdir` | Use `{article-dir}/imgs/`, display "Output: {path}" |
-| `illustrations-subdir` | Use `{article-dir}/illustrations/`, display "Output: {path}" |
-| `independent` | Use `illustrations/{topic-slug}/`, display "Output: {path}" |
-| Not configured | **MUST** ask with AskUserQuestion ↓ |
 
-**AskUserQuestion** (when no preference):
+| Question | When to Ask | Options |
-- `{article-dir}/` - Same directory as article
+|----------|-------------|---------|
-- `{article-dir}/imgs/` - Images subdirectory
+| Output directory | No `default_output_dir` in EXTEND.md | `{article-dir}/`, `{article-dir}/imgs/` (Recommended), `{article-dir}/illustrations/`, `illustrations/{topic-slug}/` |
-- `{article-dir}/illustrations/` - Illustrations subdirectory (Recommended)
+| Existing images | Target dir has `.png/.jpg/.webp` files | `supplement`, `overwrite`, `regenerate` |
-- `illustrations/{topic-slug}/` - Independent directory
+| Article update | Always (file path input) | `update`, `copy` |
-- Save as default - Remember this choice for future runs
 
-**1.3 Check Existing Images**
+**Preference Values** (if configured, skip asking):
 
-Scan target directory for `.png/.jpg/.webp` files.
+| `default_output_dir` | Path |
+|----------------------|------|
+| `same-dir` | `{article-dir}/` |
+| `imgs-subdir` | `{article-dir}/imgs/` |
+| `illustrations-subdir` | `{article-dir}/illustrations/` |
+| `independent` | `illustrations/{topic-slug}/` |
 
-If images exist → AskUserQuestion: How to handle?
+**1.5 Load Preferences (EXTEND.md) ⛔ BLOCKING**
-- `supplement` - Keep existing, generate only new positions
-- `overwrite` - Overwrite same-name files
-- `regenerate` - Clear all and regenerate
 
-**1.4 Confirm Article Update Method** (file path input only)
+**CRITICAL**: If EXTEND.md not found, MUST complete first-time setup before ANY other questions or steps. Do NOT proceed to reference images, do NOT ask about content, do NOT ask about type/style — ONLY complete the preferences setup first.
-
-AskUserQuestion: How to update article?
-- `update` - Modify original file directly
-- `copy` - Create `{name}-illustrated.md` copy
-
-**1.5 Load Preferences (EXTEND.md)**
 
 ```bash
 test -f .baoyu-skills/baoyu-article-illustrator/EXTEND.md && echo "project"
@@ -123,8 +173,8 @@ test -f "$HOME/.baoyu-skills/baoyu-article-illustrator/EXTEND.md" && echo "user"
 
 | Result | Action |
 |--------|--------|
-| Found | Read, parse, display summary |
+| Found | Read, parse, display summary → Continue |
-| Not found | Ask with AskUserQuestion (see references/config/first-time-setup.md) |
+| Not found | ⛔ **BLOCKING**: Run first-time setup ONLY ([references/config/first-time-setup.md](references/config/first-time-setup.md)) → Complete and save EXTEND.md → Then continue |
 
 **Supports**: Watermark | Preferred type/style | Custom styles | Language | Output directory
 
@@ -164,22 +214,41 @@ test -f "$HOME/.baoyu-skills/baoyu-article-illustrator/EXTEND.md" && echo "user"
 - Decorative scenes
 - Generic illustrations
 
+**2.4 Analyze Reference Images** (if provided in Step 1.0)
+
+For each reference image:
+
+| Analysis | Description |
+|----------|-------------|
+| Visual characteristics | Style, colors, composition |
+| Content/subject | What the reference depicts |
+| Suitable positions | Which sections match this reference |
+| Style match | Which illustration types/styles align |
+| Usage recommendation | `direct` / `style` / `palette` |
+
+| Usage | When to Use |
+|-------|-------------|
+| `direct` | Reference matches desired output closely |
+| `style` | Extract visual style characteristics only |
+| `palette` | Extract color scheme only |
+
 ---
 
 ### Step 3: Confirm Settings ⚠️
 
-**Do NOT skip.** Use AskUserQuestion with 3-4 questions in ONE call.
+**Do NOT skip.** Use ONE AskUserQuestion call with max 4 questions. **Q1, Q2, Q3 are ALL REQUIRED.**
 
-**Q1: Illustration Type**
+**Q1: Illustration Type** ⚠️ REQUIRED
 - [Recommended based on analysis] (Recommended)
 - infographic / scene / flowchart / comparison / framework / timeline / mixed
 
-**Q2: Density**
+**Q2: Density** ⚠️ REQUIRED - DO NOT SKIP
 - minimal (1-2) - Core concepts only
-- balanced (3-5) (Recommended) - Major sections
+- balanced (3-5) - Major sections
-- rich (6+) - Comprehensive support
+- per-section - At least 1 per section/chapter (Recommended)
+- rich (6+) - Comprehensive coverage
 
-**Q3: Style** (ALWAYS ask, even with preferred_style in EXTEND.md)
+**Q3: Style** ⚠️ REQUIRED (ALWAYS ask, even with preferred_style in EXTEND.md)
 
 If EXTEND.md has `preferred_style`:
 - [Custom style name + brief description] (Recommended)
@@ -199,6 +268,18 @@ Full specs: `references/styles/<style>.md`
 **Q4** (only if source ≠ user language):
 - Language: Source / User language
 
+**Display Reference Usage** (if references detected in Step 1.0):
+
+When presenting outline preview to user, show reference assignments:
+
+```
+Reference Images:
+| Ref | Filename | Recommended Usage |
+|-----|----------|-------------------|
+| 01 | 01-ref-diagram.png | direct → Illustration 1, 3 |
+| 02 | 02-ref-chart.png | palette → Illustration 2 |
+```
+
 ---
 
 ### Step 4: Generate Outline
@@ -211,6 +292,13 @@ type: infographic
 density: balanced
 style: blueprint
 image_count: 4
+references:                    # Only if references provided
+  - ref_id: 01
+    filename: 01-ref-diagram.png
+    description: "Technical diagram showing system architecture"
+  - ref_id: 02
+    filename: 02-ref-chart.png
+    description: "Color chart with brand palette"
 ---
 
 ## Illustration 1
@@ -219,6 +307,8 @@ image_count: 4
 **Purpose**: [why this helps]
 **Visual Content**: [what to show]
 **Type Application**: [how type applies]
+**References**: [01]                    # Optional: list ref_ids used
+**Reference Usage**: direct             # direct | style | palette
 **Filename**: 01-infographic-concept-name.png
 
 ## Illustration 2
@@ -230,6 +320,7 @@ image_count: 4
 - Type applied consistently
 - Style reflected in descriptions
 - Count matches density
+- References assigned based on Step 2.4 analysis
 
 ---
 
@@ -240,18 +331,58 @@ image_count: 4
 Follow [references/prompt-construction.md](references/prompt-construction.md). Save to `prompts/illustration-{slug}.md`.
 - **Backup rule**: If prompt file exists, rename to `prompts/illustration-{slug}-backup-YYYYMMDD-HHMMSS.md`
 
+**CRITICAL - References in Frontmatter**:
+- Only add `references` field if files ACTUALLY EXIST in `references/` directory
+- If style/palette was extracted verbally (no file), append info to prompt BODY instead
+- Before writing frontmatter, verify: `test -f references/NN-ref-{slug}.png`
+
 **5.2 Select Generation Skill**
 
 Check available skills. If multiple, ask user.
 
-**5.3 Apply Watermark** (if enabled)
+**5.3 Process References** ⚠️ REQUIRED if references saved in Step 1.0
+
+**DO NOT SKIP if user provided reference images.** For each illustration with references:
+
+1. **VERIFY files exist first**:
+   ```bash
+   test -f references/NN-ref-{slug}.png && echo "exists" || echo "MISSING"
+   ```
+   - If file MISSING but in frontmatter → ERROR, fix frontmatter or remove references field
+   - If file exists → proceed with processing
+
+2. Read prompt frontmatter for reference info
+3. Process based on usage type:
+
+| Usage | Action | Example |
+|-------|--------|---------|
+| `direct` | Add reference path to `--ref` parameter | `--ref references/01-ref-brand.png` |
+| `style` | Analyze reference, append style traits to prompt | "Style: clean lines, gradient backgrounds..." |
+| `palette` | Extract colors from reference, append to prompt | "Colors: #E8756D coral, #7ECFC0 mint..." |
+
+3. Check image generation skill capability:
+
+| Skill Supports `--ref` | Action |
+|------------------------|--------|
+| Yes (e.g., baoyu-image-gen with Google) | Pass reference images via `--ref` |
+| No | Convert to text description, append to prompt |
+
+**Verification**: Before generating, confirm reference processing:
+```
+Reference Processing:
+- Illustration 1: using 01-ref-brand.png (direct) ✓
+- Illustration 2: extracted palette from 02-ref-style.png ✓
+```
+
+**5.4 Apply Watermark** (if enabled)
 
 Add: `Include a subtle watermark "[content]" at [position].`
 
-**5.4 Generate**
+**5.5 Generate**
 
 1. For each illustration:
    - **Backup rule**: If image file exists, rename to `NN-{type}-{slug}-backup-YYYYMMDD-HHMMSS.png`
+   - If references with `direct` usage: include `--ref` parameter
    - Generate image
 2. After each: "Generated X/N"
 3. On failure: retry once, then log and continue
@@ -295,6 +426,10 @@ Failed:
 ```
 illustrations/{topic-slug}/
 ├── source-{slug}.{ext}
+├── references/                    # Only if references provided
+│   ├── 01-ref-{slug}.png
+│   ├── 01-ref-{slug}.md           # Description file (optional)
+│   └── ...
 ├── outline.md
 ├── prompts/
 │   └── illustration-{slug}.md

skills/baoyu-article-illustrator/references/config/first-time-setup.md

@@ -9,6 +9,14 @@ description: First-time setup flow for baoyu-article-illustrator preferences
 
 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 type or style preferences
+- Proceed to content analysis
+
+ONLY ask the questions in this setup flow, save EXTEND.md, then continue.
+
 ## Setup Flow
 
 ```

skills/baoyu-article-illustrator/references/prompt-construction.md

@@ -1,5 +1,54 @@
 # Prompt Construction
 
+## Prompt File Format
+
+Each prompt file uses YAML frontmatter + content:
+
+```yaml
+---
+illustration_id: 01
+type: infographic
+style: blueprint
+references:                    # ⚠️ ONLY if files EXIST in references/ directory
+  - ref_id: 01
+    filename: 01-ref-diagram.png
+    usage: direct              # direct | style | palette
+---
+
+[Type-specific template content below...]
+```
+
+**⚠️ CRITICAL - When to include `references` field**:
+
+| Situation | Action |
+|-----------|--------|
+| Reference file saved to `references/` | Include in frontmatter ✓ |
+| Style extracted verbally (no file) | DO NOT include in frontmatter, append to prompt body instead |
+| File path in frontmatter but file doesn't exist | ERROR - remove references field |
+
+**Reference Usage Types** (only when file exists):
+
+| Usage | Description | Generation Action |
+|-------|-------------|-------------------|
+| `direct` | Primary visual reference | Pass to `--ref` parameter |
+| `style` | Style characteristics only | Describe style in prompt text |
+| `palette` | Color palette extraction | Include colors in prompt |
+
+**If no reference file but style/palette extracted verbally**, append directly to prompt body:
+```
+COLORS (from reference):
+- Primary: #E8756D coral
+- Secondary: #7ECFC0 mint
+...
+
+STYLE (from reference):
+- Clean lines, minimal shadows
+- Gradient backgrounds
+...
+```
+
+---
+
 ## Principles
 
 Good prompts must include: