1# Complete Workflow
2 
3Full workflow for generating knowledge comics.
4 
5## Progress Checklist
6 
7Copy and track progress:
8 
9```
10Comic Progress:
11- [ ] Step 1: Setup & Analyze
12  - [ ] 1.1 Load preferences
13  - [ ] 1.2 Analyze content
14  - [ ] 1.3 Check existing ⚠️ REQUIRED
15- [ ] Step 2: Confirmation 1 - Style & options ⚠️ REQUIRED
16- [ ] Step 3: Generate storyboard + characters
17- [ ] Step 4: Review outline (conditional)
18- [ ] Step 5: Generate prompts
19- [ ] Step 6: Review prompts (conditional)
20- [ ] Step 7: Generate images
21  - [ ] 7.1 Character sheet (if needed)
22  - [ ] 7.2 Generate pages
23- [ ] Step 8: Merge to PDF
24- [ ] Step 9: Completion report
25```
26 
27## Flow Diagram
28 
29```
30Input → Preferences → Analyze → [Check Existing?] → [Confirm 1: Style + Reviews] → Storyboard → [Review Outline?] → Prompts → [Review Prompts?] → Images → PDF → Complete
31```
32 
33---
34 
35## Step 1: Setup & Analyze
36 
37### 1.1 Load Preferences (EXTEND.md)
38 
39Check EXTEND.md existence (priority order):
40 
41```bash
42# macOS, Linux, WSL, Git Bash
43test -f .baoyu-skills/baoyu-comic/EXTEND.md && echo "project"
44test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-comic/EXTEND.md" && echo "xdg"
45test -f "$HOME/.baoyu-skills/baoyu-comic/EXTEND.md" && echo "user"
46```
47 
48```powershell
49# PowerShell (Windows)
50if (Test-Path .baoyu-skills/baoyu-comic/EXTEND.md) { "project" }
51$xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
52if (Test-Path "$xdg/baoyu-skills/baoyu-comic/EXTEND.md") { "xdg" }
53if (Test-Path "$HOME/.baoyu-skills/baoyu-comic/EXTEND.md") { "user" }
54```
55 
56| Path | Location |
57|------|----------|
58| `.baoyu-skills/baoyu-comic/EXTEND.md` | Project directory |
59| `$HOME/.baoyu-skills/baoyu-comic/EXTEND.md` | User home |
60 
61**When EXTEND.md Found** → Read, parse, **output summary to user**:
62 
63```
64📋 Loaded preferences from [full path]
65├─ Watermark: [enabled/disabled] [content if enabled]
66├─ Art Style: [style name or "auto-select"]
67├─ Tone: [tone name or "auto-select"]
68├─ Layout: [layout or "auto-select"]
69├─ Language: [language or "auto-detect"]
70└─ Character presets: [count] defined
71```
72 
73**MUST output this summary** so user knows their current configuration. Do not skip or silently load.
74 
75**When EXTEND.md Not Found** → First-time setup:
76 
771. Inform user: "No preferences found. Let's set up your defaults."
782. Use AskUserQuestion to collect preferences (see `config/first-time-setup.md`)
793. Create EXTEND.md at user-chosen location
804. Confirm: "✓ Preferences saved to [path]"
81 
82**EXTEND.md Supports**: Watermark | Preferred art/tone/layout | Custom style definitions | Character presets | Language preference
83 
84Schema: `config/preferences-schema.md`
85 
86**Important**: Once EXTEND.md exists, watermark, language, and style defaults are NOT asked again in Confirmation 1 or 2. These are session-persistent settings.
87 
88### 1.2 Analyze Content → `analysis.md`
89 
90Read source content, save it if needed, and perform deep analysis.
91 
92**Actions**:
931. **Save source content** (if not already a file):
94   - If user provides a file path: use as-is
95   - If user pastes content: save to `source.md` in target directory
96   - **Backup rule**: If `source.md` exists, rename to `source-backup-YYYYMMDD-HHMMSS.md`
972. Read source content
983. **Deep analysis** following `analysis-framework.md`:
99   - Target audience identification
100   - Value proposition for readers
101   - Core themes and narrative potential
102   - Key figures and their story arcs
1034. Detect source language
1045. **Determine language**:
105   - If EXTEND.md has `language` → use it
106   - Else if `--lang` option provided → use it
107   - Else → use detected source language
1086. Determine recommended page count:
109   - Short story: 5-8 pages
110   - Medium complexity: 9-15 pages
111   - Full biography: 16-25 pages
1127. Analyze content signals for art/tone/layout recommendations
1138. **Save to `analysis.md`**
114 
115**analysis.md Format**: YAML front matter (title, topic, time_span, source_language, user_language, aspect_ratio, recommended_page_count, recommended_art, recommended_tone) + sections for Target Audience, Value Proposition, Core Themes, Key Figures & Story Arcs, Content Signals, Recommended Approaches. See `analysis-framework.md` for full template.
116 
117### 1.3 Check Existing Content ⚠️ REQUIRED
118 
119**MUST execute before proceeding to Step 2.**
120 
121Use Bash to check if output directory exists:
122 
123```bash
124test -d "comic/{topic-slug}" && echo "exists"
125```
126 
127**If directory exists**, use AskUserQuestion:
128 
129```
130header: "Existing"
131question: "Existing content found. How to proceed?"
132options:
133  - label: "Regenerate storyboard"
134    description: "Keep images, regenerate storyboard and characters only"
135  - label: "Regenerate images"
136    description: "Keep storyboard, regenerate images only"
137  - label: "Backup and regenerate"
138    description: "Backup to {slug}-backup-{timestamp}, then regenerate all"
139  - label: "Exit"
140    description: "Cancel, keep existing content unchanged"
141```
142 
143Save result and handle accordingly:
144- **Regenerate storyboard**: Skip to Step 3, preserve `prompts/` and images
145- **Regenerate images**: Skip to Step 7, use existing prompts
146- **Backup and regenerate**: Move directory, start fresh from Step 2
147- **Exit**: End workflow immediately
148 
149---
150 
151## Step 2: Confirmation 1 - Style & Options ⚠️
152 
153**Purpose**: Select visual style + decide whether to review outline before generation. **Do NOT skip.**
154 
155**Note**: Watermark and language already configured in EXTEND.md (Step 1).
156 
157**Display summary**:
158- Content type + topic identified
159- Key figures extracted
160- Time span detected
161- Recommended page count
162- Language: [from EXTEND.md or detected]
163- **Recommended style**: [art] + [tone] (based on content signals)
164 
165**Use AskUserQuestion** for:
166 
167### Question 1: Visual Style
168 
169If a preset is recommended (see `auto-selection.md`), show it first:
170 
171```
172header: "Style"
173question: "Which visual style for this comic?"
174options:
175  - label: "[preset name] preset (Recommended)"       # If preset recommended
176    description: "[preset description] - includes special rules"
177  - label: "[recommended art] + [recommended tone] (Recommended)"  # If no preset
178    description: "Best match for your content based on analysis"
179  - label: "ligne-claire + neutral"
180    description: "Classic educational, Logicomix style"
181  - label: "ohmsha preset"
182    description: "Educational manga with visual metaphors, gadgets, NO talking heads"
183  - label: "Custom"
184    description: "Specify your own art + tone or preset"
185```
186 
187**Preset vs Art+Tone**: Presets include special rules beyond art+tone. `ohmsha` = manga + neutral + visual metaphor rules + character roles + NO talking heads. Plain `manga + neutral` does NOT include these rules.
188 
189### Question 2: Narrative Focus (multiSelect: true)
190 
191```
192header: "Focus"
193question: "What should the comic emphasize? (Select all that apply)"
194options:
195  - label: "Biography/life story"
196    description: "Follow a person's journey through key life events"
197  - label: "Concept explanation"
198    description: "Break down complex ideas visually"
199  - label: "Historical event"
200    description: "Dramatize important historical moments"
201  - label: "Tutorial/how-to"
202    description: "Step-by-step educational guide"
203```
204 
205### Question 3: Target Audience
206 
207```
208header: "Audience"
209question: "Who is the primary reader?"
210options:
211  - label: "General readers"
212    description: "Broad appeal, accessible content"
213  - label: "Students/learners"
214    description: "Educational focus, clear explanations"
215  - label: "Industry professionals"
216    description: "Technical depth, domain knowledge"
217  - label: "Children/young readers"
218    description: "Simplified language, engaging visuals"
219```
220 
221### Question 4: Outline Review
222 
223```
224header: "Review"
225question: "Do you want to review the outline before image generation?"
226options:
227  - label: "Yes, let me review (Recommended)"
228    description: "Review storyboard and characters before generating images"
229  - label: "No, generate directly"
230    description: "Skip outline review, start generating immediately"
231```
232 
233### Question 5: Prompt Review
234 
235```
236header: "Prompts"
237question: "Review prompts before generating images?"
238options:
239  - label: "Yes, review prompts (Recommended)"
240    description: "Review image generation prompts before generating"
241  - label: "No, skip prompt review"
242    description: "Proceed directly to image generation"
243```
244 
245**After response**:
2461. Update `analysis.md` with user preferences
2472. **Store `skip_outline_review`** flag based on Question 4 response
2483. **Store `skip_prompt_review`** flag based on Question 5 response
2494. → Step 3
250 
251---
252 
253## Step 3: Generate Storyboard + Characters
254 
255Create storyboard and character definitions using the confirmed style from Step 2.
256 
257**Loading Style References**:
258- Art style: `art-styles/{art}.md`
259- Tone: `tones/{tone}.md`
260- If preset (ohmsha/wuxia/shoujo): also load `presets/{preset}.md`
261 
262**Generate**:
263 
2641. **Storyboard** (`storyboard.md`):
265   - YAML front matter with art_style, tone, layout, aspect_ratio
266   - Cover design
267   - Each page: layout, panel breakdown, visual prompts
268   - **Written in user's preferred language** (from Step 1)
269   - Reference: `storyboard-template.md`
270   - **If using preset**: Load and apply preset rules from `presets/`
271 
2722. **Character definitions** (`characters/characters.md`):
273   - Visual specs matching the art style (in user's preferred language)
274   - Include Reference Sheet Prompt for later image generation
275   - Reference: `character-template.md`
276   - **If using ohmsha preset**: Use default Doraemon characters (see below)
277 
278**Ohmsha Default Characters** (use these unless user specifies `--characters`):
279 
280| Role | Character | Visual Description |
281|------|-----------|-------------------|
282| Student | 大雄 (Nobita) | Japanese boy, 10yo, round glasses, black hair parted in middle, yellow shirt, navy shorts |
283| Mentor | 哆啦 A 梦 (Doraemon) | Round blue robot cat, big white eyes, red nose, whiskers, white belly with 4D pocket, golden bell, no ears |
284| Challenge | 胖虎 (Gian) | Stocky boy, rough features, small eyes, orange shirt |
285| Support | 静香 (Shizuka) | Cute girl, black short hair, pink dress, gentle expression |
286 
287These are the canonical ohmsha-style characters. Do NOT create custom characters for ohmsha unless explicitly requested.
288 
289**After generation**:
290- If `skip_outline_review` is true → Skip Step 4, go directly to Step 5
291- If `skip_outline_review` is false → Continue to Step 4
292 
293---
294 
295## Step 4: Review Outline (Conditional)
296 
297**Skip this step** if user selected "No, generate directly" in Step 2.
298 
299**Purpose**: User reviews and confirms storyboard + characters before generation.
300 
301**Display**:
302- Page count and structure
303- Art style + Tone combination
304- Page-by-page summary (Cover → P1 → P2...)
305- Character list with brief descriptions
306 
307**Use AskUserQuestion**:
308 
309```
310header: "Confirm"
311question: "Ready to generate images with this outline?"
312options:
313  - label: "Yes, proceed (Recommended)"
314    description: "Generate character sheet and comic pages"
315  - label: "Edit storyboard first"
316    description: "I'll modify storyboard.md before continuing"
317  - label: "Edit characters first"
318    description: "I'll modify characters/characters.md before continuing"
319  - label: "Edit both"
320    description: "I'll modify both files before continuing"
321```
322 
323**After response**:
3241. If user wants to edit → Wait for user to finish editing, then ask again
3252. If user confirms → Continue to Step 5
326 
327---
328 
329## Step 5: Generate Prompts
330 
331Create image generation prompts for all pages.
332 
333**Style Reference Loading**:
334- Read `art-styles/{art}.md` for rendering guidelines
335- Read `tones/{tone}.md` for mood/color adjustments
336- If preset: Read `presets/{preset}.md` for special rules
337 
338**For each page (cover + pages)**:
3391. Create prompt following art style + tone guidelines
3402. Include character visual descriptions for consistency
3413. Save to `prompts/NN-{cover|page}-[slug].md`
342   - **Backup rule**: If prompt file exists, rename to `prompts/NN-{cover|page}-[slug]-backup-YYYYMMDD-HHMMSS.md`
343 
344**Prompt File Format**:
345```markdown
346# Page NN: [Title]
347 
348## Visual Style
349Art: [art style] | Tone: [tone] | Layout: [layout type]
350 
351## Character Reference
352[Character descriptions from characters/characters.md]
353 
354## Panel Breakdown
355[From storyboard.md - panel descriptions, actions, dialogue]
356 
357## Generation Prompt
358[Combined prompt for image generation skill]
359```
360 
361**Watermark Application** (if enabled in preferences):
362Add to each prompt:
363```
364Include a subtle watermark "[content]" positioned at [position]. The watermark should
365be legible but not distracting from the comic panels and storytelling.
366Ensure watermark does not overlap speech bubbles or key action.
367```
368Reference: `config/watermark-guide.md`
369 
370**After generation**:
371- If `skip_prompt_review` is true → Skip Step 6, go directly to Step 7
372- If `skip_prompt_review` is false → Continue to Step 6
373 
374---
375 
376## Step 6: Review Prompts (Conditional)
377 
378**Skip this step** if user selected "No, skip prompt review" in Step 2.
379 
380**Purpose**: User reviews and confirms prompts before image generation.
381 
382**Display prompt summary table**:
383 
384| Page | Title | Key Elements |
385|------|-------|--------------|
386| Cover | [title] | [main visual] |
387| P1 | [title] | [key elements] |
388| ... | ... | ... |
389 
390**Use AskUserQuestion**:
391 
392```
393header: "Confirm"
394question: "Ready to generate images with these prompts?"
395options:
396  - label: "Yes, proceed (Recommended)"
397    description: "Generate all comic page images"
398  - label: "Edit prompts first"
399    description: "I'll modify prompts/*.md before continuing"
400  - label: "Regenerate prompts"
401    description: "Regenerate all prompts with different approach"
402```
403 
404**After response**:
4051. If user wants to edit → Wait for user to finish editing, then ask again
4062. If user wants to regenerate → Go back to Step 5
4073. If user confirms → Continue to Step 7
408 
409---
410 
411## Step 7: Generate Images
412 
413With confirmed prompts from Step 5/6:
414 
415### 7.1 Generate Character Reference Sheet (conditional)
416 
417Character sheet is recommended for multi-page comics with recurring characters, but **NOT required** for all presets.
418 
419**When to generate**:
420 
421| Condition | Action |
422|-----------|--------|
423| Multi-page comic with detailed/recurring characters | Generate character sheet (recommended) |
424| Preset with simplified characters (e.g., four-panel minimalist) | Skip — prompt descriptions are sufficient |
425| Single-page comic | Skip unless characters are complex |
426 
427**When generating**:
4281. Use Reference Sheet Prompt from `characters/characters.md`
4292. **Backup rule**: If `characters/characters.png` exists, rename to `characters/characters-backup-YYYYMMDD-HHMMSS.png`
4303. Generate → `characters/characters.png`
4314. **Compress** to reduce API payload size when used as `--ref`:
432   - `sips -s format jpeg -s formatOptions 80 characters.png --out characters-compressed.jpg` (macOS)
433   - Or: `pngquant --quality=65-80 characters.png -o characters-compressed.png`
434 
435### 7.2 Generate Comic Pages
436 
437**Before generating any page**:
4381. Read the image generation skill's SKILL.md
4392. Check if it supports reference image input (`--ref`, `--reference`, etc.)
4403. Determine if character sheet exists
4414. Choose the appropriate strategy below
442 
443**Page Generation Strategy**:
444 
445| Character Sheet | Skill Capability | Strategy |
446|-----------------|------------------|----------|
447| Exists | Supports `--ref` | **A**: Pass character sheet as `--ref` with every page |
448| Exists | No `--ref` support | **B**: Embed character descriptions in every prompt |
449| Skipped | — | **C**: Prompt file contains all descriptions inline |
450 
451**Strategy A: Using `--ref` parameter** (e.g., baoyu-imagine)
452 
453- Read the chosen image generation skill's `SKILL.md`
454- Invoke that installed skill via its documented interface, not by calling its scripts directly
455- For every page, use `prompts/01-page-xxx.md` as the prompt-file input
456- Save output to `01-page-xxx.png`
457- Use aspect ratio from storyboard (default `3:4`, preset may override)
458- Pass `characters/characters.png` (or compressed version) as `--ref`
459 
460**`--ref` failure recovery**:
461If generation fails when using `--ref`:
4621. **Compress/convert** reference image:
463   - `sips -s format jpeg -s formatOptions 70 characters.png --out characters-compressed.jpg`
464   - Or reduce resolution: `sips -Z 1024 characters.png --out characters-small.png`
4652. **Retry** with compressed/converted image as `--ref`
4663. **If still fails**: Fall back to **Strategy C** — generate WITHOUT `--ref`, with character descriptions embedded in prompt text
467 
468**Strategy B: Embedding character descriptions in prompt**
469 
470When skill does NOT support reference images, create combined prompt files:
471 
472```markdown
473# prompts/01-page-xxx.md (with embedded character reference)
474 
475## Character Reference (maintain consistency)
476[Copy relevant sections from characters/characters.md here]
477- 大雄：Japanese boy, round glasses, yellow shirt, navy shorts...
478- 哆啦 A 梦：Round blue robot cat, white belly, red nose, golden bell...
479 
480## Page Content
481[Original page prompt here]
482```
483 
484**Strategy C: Prompt-only (no character sheet)**
485 
486When character sheet was skipped or `--ref` failed:
487- Prompt file already contains all character descriptions inline
488- No `--ref` parameter needed
489- Rely on detailed text descriptions for character consistency
490 
491**For each page (cover + pages)**:
4921. Read prompt from `prompts/NN-{cover|page}-[slug].md`
4932. **Backup rule**: If image file exists, rename to `NN-{cover|page}-[slug]-backup-YYYYMMDD-HHMMSS.png`
4943. Generate image using Strategy A, B, or C
4954. Save to `NN-{cover|page}-[slug].png`
4965. Report progress after each generation: "Generated X/N: [page title]"
497 
498**Session Management**:
499If image generation skill supports `--sessionId`:
5001. Generate unique session ID: `comic-{topic-slug}-{timestamp}`
5012. Use same session ID for all pages
5023. Ensures visual consistency across generated images
503 
504---
505 
506## Step 8: Merge to PDF
507 
508After all images generated:
509 
510```bash
511${BUN_X} {baseDir}/scripts/merge-to-pdf.ts <comic-dir>
512```
513 
514Creates `{topic-slug}.pdf` with all pages as full-page images.
515 
516---
517 
518## Step 9: Completion Report
519 
520```
521Comic Complete!
522Title: [title] | Art: [art] | Tone: [tone] | Pages: [count] | Aspect: [ratio] | Language: [lang]
523Watermark: [enabled/disabled]
524Location: [path]
525✓ analysis.md
526✓ characters.png (if generated)
527✓ 00-cover-[slug].png ... NN-page-[slug].png
528✓ {topic-slug}.pdf
529```
530 
531---
532 
533## Page Modification
534 
535| Action | Steps |
536|--------|-------|
537| **Edit** | Update prompt → Regenerate image → Regenerate PDF |
538| **Add** | Create prompt at position → Generate image → Renumber subsequent (NN+1) → Update storyboard → Regenerate PDF |
539| **Delete** | Remove files → Renumber subsequent (NN-1) → Update storyboard → Regenerate PDF |
540 
541**File naming**: `NN-{cover|page}-[slug].png` (e.g., `03-page-enigma-machine.png`)
542- Slugs: kebab-case, unique, derived from content
543- Renumbering: Update NN prefix only, slugs unchanged
544