1---
2name: first-time-setup
3description: First-time setup and default model selection flow for baoyu-image-gen
4---
5 
6# First-Time Setup
7 
8## Overview
9 
10Triggered when:
111. No EXTEND.md found → full setup (provider + model + preferences)
122. EXTEND.md found but `default_model.[provider]` is null → model selection only
13 
14## Setup Flow
15 
16```
17No EXTEND.md found          EXTEND.md found, model null
18        │                            │
19        ▼                            ▼
20┌─────────────────────┐    ┌──────────────────────┐
21│ AskUserQuestion     │    │ AskUserQuestion      │
22│ (full setup)        │    │ (model only)         │
23└─────────────────────┘    └──────────────────────┘
24        │                            │
25        ▼                            ▼
26┌─────────────────────┐    ┌──────────────────────┐
27│ Create EXTEND.md    │    │ Update EXTEND.md     │
28└─────────────────────┘    └──────────────────────┘
29        │                            │
30        ▼                            ▼
31    Continue                     Continue
32```
33 
34## Flow 1: No EXTEND.md (Full Setup)
35 
36**Language**: Use user's input language or saved language preference.
37 
38Use AskUserQuestion with ALL questions in ONE call:
39 
40### Question 1: Default Provider
41 
42```yaml
43header: "Provider"
44question: "Default image generation provider?"
45options:
46  - label: "Google (Recommended)"
47    description: "Gemini multimodal - high quality, reference images, flexible sizes"
48  - label: "OpenAI"
49    description: "GPT Image - consistent quality, reliable output"
50  - label: "Azure OpenAI"
51    description: "Azure-hosted GPT Image deployments with resource-specific routing"
52  - label: "OpenRouter"
53    description: "Router for Gemini/FLUX/OpenAI-compatible image models"
54  - label: "DashScope"
55    description: "Alibaba Cloud - Qwen-Image, strong Chinese/English text rendering"
56  - label: "MiniMax"
57    description: "MiniMax image generation with subject-reference character workflows"
58  - label: "Replicate"
59    description: "Community models - nano-banana-pro, flexible model selection"
60  - label: "Z.AI"
61    description: "GLM-Image - text-to-image with recommended aspect sizes"
62```
63 
64### Question 2: Default Google Model
65 
66Only show if user selected Google or auto-detect (no explicit provider).
67 
68```yaml
69header: "Google Model"
70question: "Default Google image generation model?"
71options:
72  - label: "gemini-3-pro-image-preview (Recommended)"
73    description: "Highest quality, best for production use"
74  - label: "gemini-3.1-flash-image-preview"
75    description: "Fast generation, good quality, lower cost"
76  - label: "gemini-3-flash-preview"
77    description: "Fast generation, balanced quality and speed"
78```
79 
80### Question 2b: Default OpenRouter Model
81 
82Only show if user selected OpenRouter.
83 
84```yaml
85header: "OpenRouter Model"
86question: "Default OpenRouter image generation model?"
87options:
88  - label: "google/gemini-3.1-flash-image-preview (Recommended)"
89    description: "Best general-purpose OpenRouter image model with reference-image workflows"
90  - label: "google/gemini-2.5-flash-image-preview"
91    description: "Fast Gemini preview model on OpenRouter"
92  - label: "black-forest-labs/flux.2-pro"
93    description: "Strong text-to-image quality through OpenRouter"
94```
95 
96### Question 2c: Default Azure Deployment
97 
98Only show if user selected Azure OpenAI.
99 
100```yaml
101header: "Azure Deploy"
102question: "Default Azure image deployment name?"
103options:
104  - label: "gpt-image-1.5 (Recommended)"
105    description: "Best default if your Azure deployment uses the same name"
106  - label: "gpt-image-1"
107    description: "Previous GPT Image deployment name"
108```
109 
110### Question 2d: Default MiniMax Model
111 
112Only show if user selected MiniMax.
113 
114```yaml
115header: "MiniMax Model"
116question: "Default MiniMax image generation model?"
117options:
118  - label: "image-01 (Recommended)"
119    description: "Best default, supports aspect ratios and custom width/height"
120  - label: "image-01-live"
121    description: "Faster variant, use aspect ratio instead of custom size"
122```
123 
124### Question 2e: Default Z.AI Model
125 
126Only show if user selected Z.AI.
127 
128```yaml
129header: "Z.AI Model"
130question: "Default Z.AI image generation model?"
131options:
132  - label: "glm-image (Recommended)"
133    description: "Latest GLM-Image, best aspect-ratio coverage and text rendering"
134  - label: "cogview-4-250304"
135    description: "Legacy CogView-4 model with 16-pixel size stepping"
136  - label: "cogview-4"
137    description: "Previous CogView-4 snapshot for compatibility"
138```
139 
140### Question 3: Default Quality
141 
142```yaml
143header: "Quality"
144question: "Default image quality?"
145options:
146  - label: "2k (Recommended)"
147    description: "2048px - covers, illustrations, infographics"
148  - label: "normal"
149    description: "1024px - quick previews, drafts"
150```
151 
152### Question 4: Save Location
153 
154```yaml
155header: "Save"
156question: "Where to save preferences?"
157options:
158  - label: "Project (Recommended)"
159    description: ".baoyu-skills/ (this project only)"
160  - label: "User"
161    description: "~/.baoyu-skills/ (all projects)"
162```
163 
164### Save Locations
165 
166| Choice | Path | Scope |
167|--------|------|-------|
168| Project | `.baoyu-skills/baoyu-image-gen/EXTEND.md` | Current project |
169| User | `$HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md` | All projects |
170 
171### EXTEND.md Template
172 
173```yaml
174---
175version: 1
176default_provider: [selected provider or null]
177default_quality: [selected quality]
178default_aspect_ratio: null
179default_image_size: null
180default_model:
181  google: [selected google model or null]
182  openai: null
183  azure: [selected azure deployment or null]
184  openrouter: [selected openrouter model or null]
185  dashscope: null
186  minimax: [selected minimax model or null]
187  replicate: null
188  zai: [selected zai model or null]
189---
190```
191 
192## Flow 2: EXTEND.md Exists, Model Null
193 
194When EXTEND.md exists but `default_model.[current_provider]` is null, ask ONLY the model question for the current provider.
195 
196### Google Model Selection
197 
198```yaml
199header: "Google Model"
200question: "Choose a default Google image generation model?"
201options:
202  - label: "gemini-3-pro-image-preview (Recommended)"
203    description: "Highest quality, best for production use"
204  - label: "gemini-3.1-flash-image-preview"
205    description: "Fast generation, good quality, lower cost"
206  - label: "gemini-3-flash-preview"
207    description: "Fast generation, balanced quality and speed"
208```
209 
210### OpenAI Model Selection
211 
212```yaml
213header: "OpenAI Model"
214question: "Choose a default OpenAI image generation model?"
215options:
216  - label: "gpt-image-1.5 (Recommended)"
217    description: "Latest GPT Image model, high quality"
218  - label: "gpt-image-1"
219    description: "Previous generation GPT Image model"
220```
221 
222### Azure Deployment Selection
223 
224```yaml
225header: "Azure Deploy"
226question: "Choose a default Azure image deployment name?"
227options:
228  - label: "gpt-image-1.5 (Recommended)"
229    description: "Use when your Azure deployment name matches the GPT-image-1.5 model"
230  - label: "gpt-image-1"
231    description: "Use when your Azure deployment name matches GPT-image-1"
232```
233 
234Notes for Azure setup:
235 
236- In `baoyu-image-gen`, Azure `--model` / `default_model.azure` should be the Azure deployment name, not just the underlying model family.
237- If the deployment name is custom, save that exact deployment name in `default_model.azure`.
238 
239### OpenRouter Model Selection
240 
241```yaml
242header: "OpenRouter Model"
243question: "Choose a default OpenRouter image generation model?"
244options:
245  - label: "google/gemini-3.1-flash-image-preview (Recommended)"
246    description: "Recommended for image output and reference-image edits"
247  - label: "google/gemini-2.5-flash-image-preview"
248    description: "Fast preview-oriented image generation"
249  - label: "black-forest-labs/flux.2-pro"
250    description: "High-quality text-to-image through OpenRouter"
251```
252 
253### DashScope Model Selection
254 
255```yaml
256header: "DashScope Model"
257question: "Choose a default DashScope image generation model?"
258options:
259  - label: "qwen-image-2.0-pro (Recommended)"
260    description: "Best DashScope model for text rendering and custom sizes"
261  - label: "qwen-image-2.0"
262    description: "Faster 2.0 variant with flexible output size"
263  - label: "qwen-image-max"
264    description: "Legacy Qwen model with five fixed output sizes"
265  - label: "qwen-image-plus"
266    description: "Legacy Qwen model, same current capability as qwen-image"
267  - label: "z-image-turbo"
268    description: "Legacy DashScope model for compatibility"
269  - label: "z-image-ultra"
270    description: "Legacy DashScope model, higher quality but slower"
271```
272 
273Notes for DashScope setup:
274 
275- Prefer `qwen-image-2.0-pro` when the user needs custom `--size`, uncommon ratios like `21:9`, or strong Chinese/English text rendering.
276- `qwen-image-max` / `qwen-image-plus` / `qwen-image` only support five fixed sizes: `1664*928`, `1472*1104`, `1328*1328`, `1104*1472`, `928*1664`.
277- In `baoyu-image-gen`, `quality` is a compatibility preset. It is not a native DashScope parameter.
278 
279### Replicate Model Selection
280 
281```yaml
282header: "Replicate Model"
283question: "Choose a default Replicate image generation model?"
284options:
285  - label: "google/nano-banana-pro (Recommended)"
286    description: "Google's fast image model on Replicate"
287  - label: "google/nano-banana"
288    description: "Google's base image model on Replicate"
289```
290 
291### MiniMax Model Selection
292 
293```yaml
294header: "MiniMax Model"
295question: "Choose a default MiniMax image generation model?"
296options:
297  - label: "image-01 (Recommended)"
298    description: "Best general-purpose MiniMax image model with custom width/height support"
299  - label: "image-01-live"
300    description: "Lower-latency MiniMax image model using aspect ratios"
301```
302 
303Notes for MiniMax setup:
304 
305- `image-01` is the safest default. It supports official `aspect_ratio` values and documented custom `width` / `height` output sizes.
306- `image-01-live` is useful when the user prefers faster generation and can work with aspect-ratio-based sizing.
307- MiniMax subject reference currently uses `subject_reference[].type = character`; docs recommend front-facing portrait references in JPG/JPEG/PNG under 10MB.
308 
309### Z.AI Model Selection
310 
311```yaml
312header: "Z.AI Model"
313question: "Choose a default Z.AI image generation model?"
314options:
315  - label: "glm-image (Recommended)"
316    description: "Latest GLM-Image; pixels round to multiples of 32 and cap at 2^22"
317  - label: "cogview-4-250304"
318    description: "Legacy CogView-4 snapshot with 16-pixel size stepping"
319  - label: "cogview-4"
320    description: "Earlier CogView-4 snapshot for compatibility"
321```
322 
323Notes for Z.AI setup:
324 
325- Set `ZAI_API_KEY` (or legacy `BIGMODEL_API_KEY`) from https://docs.z.ai/.
326- `glm-image` supports recommended aspect sizes (1280x1280, 1728x960, 1568x1056, …); uncommon ratios auto-fit to the 2^22 pixel budget on multiples of 32.
327- Legacy CogView models use 16-pixel stepping and cap at 2^21 pixels per image.
328- Z.AI does not accept reference images or `n > 1` in `baoyu-image-gen`; use Google/OpenAI providers for those workflows.
329 
330### Update EXTEND.md
331 
332After user selects a model:
333 
3341. Read existing EXTEND.md
3352. If `default_model:` section exists → update the provider-specific key
3363. If `default_model:` section missing → add the full section:
337 
338```yaml
339default_model:
340  google: [value or null]
341  openai: [value or null]
342  azure: [value or null]
343  openrouter: [value or null]
344  dashscope: [value or null]
345  minimax: [value or null]
346  replicate: [value or null]
347  zai: [value or null]
348```
349 
350Only set the selected provider's model; leave others as their current value or null.
351 
352## After Setup
353 
3541. Create directory if needed
3552. Write/update EXTEND.md with frontmatter
3563. Confirm: "Preferences saved to [path]"
3574. Continue with image generation
358