mindforge-cc 11.5.1 → 11.7.0

package/.agent/skills/article-illustrator/references/styles.md

@@ -0,0 +1,224 @@
+# Style Reference
+
+## Core Styles
+
+Simplified style tier for quick selection:
+
+| Core Style | Maps To | Best For |
+|------------|---------|----------|
+| `vector` | vector-illustration | Knowledge articles, tutorials, tech content |
+| `minimal-flat` | notion | General, knowledge sharing, SaaS |
+| `sci-fi` | blueprint | AI, frontier tech, system design |
+| `hand-drawn` | sketch/warm | Relaxed, reflective, casual content |
+| `editorial` | editorial | Processes, data, journalism |
+| `scene` | warm/watercolor | Narratives, emotional, lifestyle |
+| `poster` | screen-print | Opinion, editorial, cultural, cinematic |
+
+Use Core Styles for most cases. See full Style Gallery below for granular control.
+
+---
+
+## Style Gallery
+
+| Style | Description | Best For |
+|-------|-------------|----------|
+| `vector-illustration` | Clean flat vector art with bold shapes | Knowledge articles, tutorials, tech content |
+| `notion` | Minimalist hand-drawn line art | Knowledge sharing, SaaS, productivity |
+| `elegant` | Refined, sophisticated | Business, thought leadership |
+| `warm` | Friendly, approachable | Personal growth, lifestyle, education |
+| `minimal` | Ultra-clean, zen-like | Philosophy, minimalism, core concepts |
+| `blueprint` | Technical schematics | Architecture, system design, engineering |
+| `watercolor` | Soft artistic with natural warmth | Lifestyle, travel, creative |
+| `editorial` | Magazine-style infographic | Tech explainers, journalism |
+| `scientific` | Academic precise diagrams | Biology, chemistry, technical research |
+| `chalkboard` | Classroom chalk drawing style | Education, teaching, explanations |
+| `fantasy-animation` | Ghibli/Disney-inspired hand-drawn | Storybook, magical, emotional |
+| `flat` | Modern bold geometric shapes | Modern digital, contemporary |
+| `flat-doodle` | Cute flat with bold outlines | Cute, friendly, approachable |
+| `intuition-machine` | Technical briefing with aged paper | Technical briefings, academic |
+| `nature` | Organic earthy illustration | Environmental, wellness |
+| `pixel-art` | Retro 8-bit gaming aesthetic | Gaming, retro tech |
+| `playful` | Whimsical pastel doodles | Fun, casual, educational |
+| `retro` | 80s/90s neon geometric | 80s/90s nostalgic, bold |
+| `sketch` | Raw pencil notebook style | Brainstorming, creative exploration |
+| `screen-print` | Bold poster art, halftone textures, limited colors | Opinion, editorial, cultural, cinematic |
+| `sketch-notes` | Soft hand-drawn warm notes | Educational, warm notes |
+| `ink-notes` | Black ink on pure white, sparse semantic accents, hand-lettered (à la Mike Rohde's sketchnoting) | Before/After essays, tech manifestos, framework analogies |
+| `vintage` | Aged parchment historical | Historical, heritage |
+
+Full specifications: `references/styles/<style>.md`
+
+## Type × Style Compatibility Matrix
+
+| | vector-illustration | notion | warm | minimal | blueprint | watercolor | elegant | editorial | scientific | screen-print |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| infographic | ✓✓ | ✓✓ | ✓ | ✓✓ | ✓✓ | ✓ | ✓✓ | ✓✓ | ✓✓ | ✓ |
+| scene | ✓ | ✓ | ✓✓ | ✓ | ✗ | ✓✓ | ✓ | ✓ | ✗ | ✓✓ |
+| flowchart | ✓✓ | ✓✓ | ✓ | ✓ | ✓✓ | ✗ | ✓ | ✓✓ | ✓ | ✗ |
+| comparison | ✓✓ | ✓✓ | ✓ | ✓✓ | ✓ | ✓ | ✓✓ | ✓✓ | ✓ | ✓ |
+| framework | ✓✓ | ✓✓ | ✓ | ✓✓ | ✓✓ | ✗ | ✓✓ | ✓ | ✓✓ | ✓ |
+| timeline | ✓ | ✓✓ | ✓ | ✓ | ✓ | ✓✓ | ✓✓ | ✓✓ | ✓ | ✓ |
+
+✓✓ = highly recommended | ✓ = compatible | ✗ = not recommended
+
+## Auto Selection by Type
+
+| Type | Primary Style | Secondary Styles |
+|------|---------------|------------------|
+| infographic | vector-illustration | notion, blueprint, editorial |
+| scene | warm | watercolor, elegant |
+| flowchart | vector-illustration | notion, blueprint |
+| comparison | vector-illustration | notion, elegant |
+| framework | blueprint | vector-illustration, notion |
+| timeline | elegant | warm, editorial |
+
+## Auto Selection by Content Signals
+
+| Content Signals | Recommended Type | Recommended Style |
+|-----------------|------------------|-------------------|
+| API, metrics, data, comparison, numbers | infographic | blueprint, vector-illustration |
+| Knowledge, concept, tutorial, learning, guide | infographic | vector-illustration, notion |
+| Tech, AI, programming, development, code | infographic | vector-illustration, blueprint |
+| How-to, steps, workflow, process, tutorial | flowchart | vector-illustration, notion |
+| Framework, model, architecture, principles | framework | blueprint, vector-illustration |
+| vs, pros/cons, before/after, alternatives | comparison | vector-illustration, notion |
+| Manifesto, mindset shift, workforce, OS, whiteboard, professional visual note | comparison / framework | ink-notes |
+| Story, emotion, journey, experience, personal | scene | warm, watercolor |
+| History, timeline, progress, evolution | timeline | elegant, warm |
+| Productivity, SaaS, tool, app, software | infographic | notion, vector-illustration |
+| Business, professional, strategy, corporate | framework | elegant |
+| Opinion, editorial, culture, philosophy, cinematic, dramatic, poster | scene | screen-print |
+| Biology, chemistry, medical, scientific | infographic | scientific |
+| Explainer, journalism, magazine, investigation | infographic | editorial |
+
+## Style Characteristics by Type
+
+### infographic + vector-illustration
+- Clean flat vector shapes, bold geometric forms
+- Vibrant but harmonious color palette
+- Clear visual hierarchy with icons and labels
+- Modern, professional, highly readable
+- Perfect for knowledge articles and tutorials
+
+### flowchart + vector-illustration
+- Bold arrows and connectors
+- Distinct step containers with icons
+- Clean progression flow
+- High contrast for readability
+
+### comparison + vector-illustration
+- Split layout with clear visual separation
+- Bold iconography for each side
+- Color-coded distinctions
+- Easy at-a-glance comparison
+
+### framework + vector-illustration
+- Geometric node representations
+- Clear hierarchical structure
+- Bold connecting lines
+- Modern system diagram aesthetic
+
+### infographic + blueprint
+- Technical precision, schematic lines
+- Grid-based layout, clear zones
+- Monospace labels, data-focused
+- Blue/white color scheme
+
+### infographic + notion
+- Hand-drawn feel, approachable
+- Soft icons, rounded elements
+- Neutral palette, clean backgrounds
+- Perfect for SaaS/productivity
+
+### scene + warm
+- Golden hour lighting, cozy atmosphere
+- Soft gradients, natural textures
+- Inviting, personal feeling
+- Great for storytelling
+
+### scene + watercolor
+- Artistic, painterly effect
+- Soft edges, color bleeding
+- Dreamy, creative mood
+- Best for lifestyle/travel
+
+### flowchart + notion
+- Clear step indicators
+- Simple arrow connections
+- Minimal decoration
+- Focus on process clarity
+
+### flowchart + blueprint
+- Technical precision
+- Detailed connection points
+- Engineering aesthetic
+- For complex systems
+
+### comparison + elegant
+- Refined dividers
+- Balanced typography
+- Professional appearance
+- Business comparisons
+
+### framework + blueprint
+- Precise node connections
+- Hierarchical clarity
+- System architecture feel
+- Technical frameworks
+
+### timeline + elegant
+- Sophisticated markers
+- Refined typography
+- Historical gravitas
+- Professional presentations
+
+### timeline + warm
+- Friendly progression
+- Organic flow
+- Personal journey feel
+- Growth narratives
+
+### scene + screen-print
+- Bold silhouettes, symbolic compositions
+- 2-5 flat colors with halftone textures
+- Figure-ground inversion (negative space tells secondary story)
+- Vintage poster aesthetic, conceptual not literal
+- Great for opinion pieces and cultural commentary
+
+### comparison + screen-print
+- Split duotone composition (one color per side)
+- Bold geometric dividers
+- Symbolic icons over detailed rendering
+- High contrast, immediate visual impact
+
+### framework + screen-print
+- Geometric node representations with stencil-cut edges
+- Limited color coding (one color per concept level)
+- Clean silhouette-based iconography
+- Poster-style hierarchy with bold typography
+
+---
+
+## Palette Gallery
+
+Palettes override a style's default colors. Combine any style with any palette (e.g. `style=vector-illustration, palette=macaron`).
+
+| Palette | Description | Best For |
+|---------|-------------|----------|
+| `macaron` | Soft pastel blocks (blue, mint, lavender, peach) on warm cream | Educational, knowledge, tutorials |
+| `warm` | Warm earth tones (orange, terracotta, gold) on soft peach, no cool colors | Brand, product, lifestyle |
+| `neon` | Vibrant neon (pink, cyan, yellow) on dark purple | Gaming, retro, pop culture |
+| `mono-ink` | Black ink on pure white with sparse semantic accents (coral red, muted teal, dusty lavender) | Professional visual notes, Before/After, manifestos |
+
+Full specifications: `references/palettes/<palette>.md`
+
+When no palette is specified, the style's built-in Color Palette is used.
+
+## Palette Override Rules
+
+1. Read style file → rendering rules (Visual Elements, Style Rules)
+2. Read palette file → Colors + Background
+3. Palette colors **replace** style's default Color Palette
+4. Palette Background **replaces** style's default Background color
+5. Style's texture description is preserved
+

package/.agent/skills/article-illustrator/references/usage.md

@@ -0,0 +1,50 @@
+# Usage
+
+This skill is triggered by natural language in this agent — no slash command or CLI flags.
+
+## Trigger Phrases
+
+- "Illustrate this article" / "为文章配图"
+- "Add images to this post"
+- "Generate illustrations for [path/to/article.md]"
+
+## Input Modes
+
+| Mode | How to trigger | Output Directory |
+|------|----------------|------------------|
+| File path | Mention an article path (`path/to/article.md`) | `{article-dir}/imgs/` (default) |
+| Pasted content | Paste the article text in the conversation | `illustrations/{topic-slug}/` (cwd) |
+
+## Specifying Options in Natural Language
+
+The user can specify any of the following directly in their request. If not specified, the skill asks via the `clarify` tool.
+
+| Option | Example phrasing |
+|--------|------------------|
+| Type | "as an infographic", "as a flowchart", "as scenes" |
+| Style | "in blueprint style", "use notion style", "用 watercolor 风格" |
+| Preset | "use the tech-explainer preset", "storytelling preset" |
+| Palette | "with macaron palette", "warm colors only" |
+| Density | "minimal images", "one per section", "rich illustrations" |
+| Language | "images in English" / "图片文字用中文" |
+| Output | "save images alongside the article" / "put them in `illustrations/`" |
+
+## Examples
+
+**Technical article with data**:
+> 帮我为 api-design.md 配图，用 infographic + blueprint 风格
+
+**Preset shortcut**:
+> Illustrate api-design.md with the tech-explainer preset
+
+**Personal story**:
+> Illustrate journey.md using the storytelling preset
+
+**Tutorial with rich images**:
+> Generate illustrations for how-to-deploy.md — tutorial preset, rich density
+
+**Opinion article**:
+> Illustrate opinion.md with the opinion-piece preset
+
+**Preset with style override**:
+> Use the tech-explainer preset for article.md but swap the style for notion

package/.agent/skills/article-illustrator/references/workflow.md

@@ -0,0 +1,332 @@
+# Detailed Workflow Procedures
+
+## Step 1: Detect Reference Images
+
+If the user provides reference images (local path or URL), the goal is to produce **textual descriptions** that can be embedded in prompts — `image_generate` doesn't accept reference-image inputs, and the agent' text file tools can't read or write binaries.
+
+**Tool rules**:
+
+| Task | Tool | Notes |
+|------|------|-------|
+| Analyze a reference image | `vision_analyze` | Accepts URL or local path. Ask for style, palette, composition, subject. |
+| Write the text description | `write_file` | Sidecar `.md` files only — never try to `write_file` a PNG/JPG. |
+| (Optional) Keep a local copy of the binary | `terminal` | `cp "$src" "{output-dir}/references/NN-ref-{slug}.{ext}"` — purely for the record; the skill itself doesn't read the binary. |
+
+| Input Type | Action |
+|------------|--------|
+| Image file path provided | `vision_analyze` → write sidecar `.md`. Optional `terminal cp` for a local record. |
+| Image URL provided | `vision_analyze` with the URL → write sidecar `.md`. |
+| Image in conversation (no path, no URL) | Ask via `clarify` for a path or URL, or for a verbal description. |
+| User can't provide either | Extract style/palette verbally from the user → write `references/extracted-style.md`. Do NOT add `references:` to prompt frontmatter. |
+
+**Procedure** (when a path/URL is available):
+
+1. Call `vision_analyze(image_url=..., question="Describe the style, color palette (with hex approximations), composition, and subject so this can be used as a style/palette reference for another illustration.")`.
+2. Write `{output-dir}/references/NN-ref-{slug}.md` via `write_file` with the description.
+3. (Optional) Run `terminal` with `cp` (or `curl -sSL -o ...` for URLs) to keep a local binary copy. Not required by the skill.
+4. Mark the reference in the outline with usage `direct` / `style` / `palette`. In Step 5.1 the description gets appended to the prompt body.
+
+**Sidecar File Format**:
+```yaml
+---
+ref_id: NN
+source: "<original path or URL>"
+local_copy: "NN-ref-{slug}.png"   # omit if no copy made
+usage_hint: style                 # direct | style | palette
+---
+[vision_analyze description — colors, style, composition, subject]
+```
+
+---
+
+## Step 2: Analyze
+
+### 2.1 Determine Output Directory
+
+| Input | Output Directory | Source-save path |
+|-------|------------------|------------------|
+| Article file path | `{article-dir}/imgs/` (default) | — (read article via `read_file`) |
+| Pasted content | `illustrations/{topic-slug}/` (cwd) | `source-{slug}.{ext}` (save via `write_file`) |
+
+If the user explicitly asked for a different layout (e.g., images in the article's folder, or an `illustrations/` subdirectory), honor that.
+
+### 2.2 Analyze Content
+
+| Analysis | Description |
+|----------|-------------|
+| Content type | Technical / Tutorial / Methodology / Narrative |
+| Illustration purpose | information / visualization / imagination |
+| Core arguments | 2-5 main points to visualize |
+| Visual opportunities | Positions where illustrations add value |
+| Recommended type | Based on content signals and purpose |
+| Recommended density | Based on length and complexity |
+
+Save analysis to `{output-dir}/analysis.md` using `write_file`.
+
+### 2.3 Extract Core Arguments
+
+- Main thesis
+- Key concepts reader needs
+- Comparisons/contrasts
+- Framework/model proposed
+
+**CRITICAL**: If the article uses metaphors (e.g., "电锯切西瓜"), do NOT illustrate literally. Visualize the **underlying concept**.
+
+### 2.4 Identify Positions
+
+**Illustrate**:
+- Core arguments (REQUIRED)
+- Abstract concepts
+- Data comparisons
+- Processes, workflows
+
+**Do NOT Illustrate**:
+- Metaphors literally
+- Decorative scenes
+- Generic illustrations
+
+### 2.5 Plan Reference Image Usage (if analyzed in Step 1)
+
+For each reference image (use the `vision_analyze` description from Step 1):
+
+| 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 | How it's applied in Step 5.1 |
+|-------|-------------|------------------------------|
+| `direct` | Reference matches desired output closely | Paste the description (composition + subject + style + palette) into the prompt body |
+| `style` | Extract visual style characteristics only | Append style traits to prompt body |
+| `palette` | Extract color scheme only | Append extracted hex colors to prompt body |
+
+Note: `image_generate` does not accept reference-image inputs under any usage type. Everything is mediated through the `vision_analyze` description.
+
+---
+
+## Step 3: Confirm Settings
+
+Use the `clarify` tool. Since `clarify` handles one question at a time, ask the most important question first. Skip any question the user already answered in their request.
+
+### Q1: Preset or Type (highest priority)
+
+Based on Step 2 content analysis, recommend a preset first (sets both type & style). Look up [style-presets.md](style-presets.md) "Content Type → Preset Recommendations" table.
+
+- [Recommended preset] — [brief: type + style + why]
+- [Alternative preset] — [brief]
+- Or choose type manually: infographic / scene / flowchart / comparison / framework / timeline / mixed
+
+**If user picks a preset → skip Q3** (type & style both resolved).
+**If user picks a type → Q3 is required.**
+
+### Q2: Density
+
+- minimal (1-2) — Core concepts only
+- balanced (3-5) — Major sections
+- per-section — At least 1 per section/chapter (Recommended)
+- rich (6+) — Comprehensive coverage
+
+### Q3: Style (skip if preset chosen in Q1)
+
+Present Core Styles first:
+
+- [Best compatible core style] (Recommended)
+- [Other compatible core style 1]
+- [Other compatible core style 2]
+- Other (see full Style Gallery)
+
+**Core Styles** (simplified selection):
+
+| Core Style | Maps To | Best For |
+|------------|---------|----------|
+| `minimal-flat` | notion | General, knowledge sharing, SaaS |
+| `sci-fi` | blueprint | AI, frontier tech, system design |
+| `hand-drawn` | sketch/warm | Relaxed, reflective, casual |
+| `editorial` | editorial | Processes, data, journalism |
+| `scene` | warm/watercolor | Narratives, emotional, lifestyle |
+| `poster` | screen-print | Opinion, editorial, cultural, cinematic |
+
+Style selection based on Type × Style compatibility matrix ([styles.md](styles.md)).
+**In Step 5**, read `styles/<style>.md` for visual elements and rendering rules.
+
+### Q4: Palette (optional)
+
+If the preset did not specify a palette, offer:
+
+- Default (use style's built-in colors) (Recommended)
+- `macaron` — soft pastel blocks on warm cream
+- `warm` — warm earth tones, no cool colors
+- `neon` — vibrant neon on dark backgrounds
+
+**Skip if**: preset already resolved palette, or user specified a palette in the request.
+
+See Palette Gallery in [styles.md](styles.md#palette-gallery) and full specs in `palettes/<palette>.md`.
+
+### Q5: Image Text Language (only when ambiguous)
+
+If the article language is different from the user's conversational language, ask which to use:
+- Article language (match article content) (Recommended)
+- User's conversational language
+
+**Skip if**: languages match, or the user already specified in the request.
+
+### Display Reference Usage (if references saved in Step 1)
+
+When presenting the outline preview to the 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
+
+Save as `{output-dir}/outline.md` using `write_file`:
+
+```yaml
+---
+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
+
+**Position**: [section] / [paragraph]
+**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
+...
+```
+
+**Backup rule**: If `outline.md` exists, rename to `outline-backup-YYYYMMDD-HHMMSS.md` before writing.
+
+**Requirements**:
+- Each position justified by content needs
+- Type applied consistently
+- Style reflected in descriptions
+- Count matches density
+- References assigned based on Step 2.5 analysis
+
+---
+
+## Step 5: Generate Prompts
+
+**BLOCKING**: Every illustration must have a saved prompt file before any image is generated.
+
+For each illustration in the outline:
+
+1. **Create prompt file**: `{output-dir}/prompts/NN-{type}-{slug}.md` via `write_file`
+2. **Include YAML frontmatter**:
+   ```yaml
+   ---
+   illustration_id: 01
+   type: infographic
+   style: custom-flat-vector
+   ---
+   ```
+3. **Load style specs**: Read `styles/<style>.md` (via `read_file`) for visual elements, style rules, and rendering instructions
+4. **Load palette specs** (if palette specified): Read `palettes/<palette>.md` for colors and background. Palette colors **replace** the style's default Color Palette. If no palette specified, use the style's built-in colors.
+5. **Follow type-specific template** from [prompt-construction.md](prompt-construction.md), using rendering from style + colors from palette (or style default)
+6. **Prompt quality requirements** (all REQUIRED):
+   - `Layout`: Describe overall composition (grid / radial / hierarchical / left-right / top-down)
+   - `ZONES`: Describe each visual area with specific content, not vague descriptions
+   - `LABELS`: Use **actual numbers, terms, metrics, quotes from the article** — NOT generic placeholders
+   - `COLORS`: Specify hex codes from palette (or style default) with semantic meaning
+   - `STYLE`: Describe line treatment, texture, mood, character rendering per style rules
+   - `ASPECT`: Specify ratio (e.g., `16:9`)
+7. **Apply defaults**: composition requirements, character rendering, text guidelines
+8. **Backup rule**: If a prompt file exists, rename to `prompts/NN-{type}-{slug}-backup-YYYYMMDD-HHMMSS.md`
+
+**CRITICAL - References in Frontmatter**:
+- Only add `references` field if a sidecar `.md` description exists in `{output-dir}/references/`
+- If style/palette was extracted verbally (no description file), append info to prompt BODY only
+- Before writing frontmatter, confirm the sidecar exists (try `read_file` on the `.md`)
+
+### 5.1 Process References (if analyzed in Step 1)
+
+Read the `vision_analyze` description from the sidecar `references/NN-ref-{slug}.md` (via `read_file`) and embed it in the prompt body. `image_generate` never receives the binary.
+
+| Usage | Action |
+|-------|--------|
+| `direct` | Paste the full reference description (composition, subject, style, palette) into the prompt body |
+| `style` | Append only the style traits: "Style: clean lines, gradient backgrounds..." |
+| `palette` | Append only the hex colors: "Colors: #E8756D coral, #7ECFC0 mint..." |
+
+---
+
+## Step 6: Generate Images
+
+`image_generate` returns a JSON blob with a URL (`{"success": true, "image": "<url>"}`). It does NOT save a local file, does NOT accept an output path, and does NOT let the agent pick a backend/model. Treat the URL as a temporary artifact and download it explicitly.
+
+For each prompt file:
+
+1. Read the prompt file (via `read_file`) and extract the assembled prompt
+2. Map the prompt's `ASPECT` to `image_generate`'s enum: `16:9` → `landscape`, `9:16` → `portrait`, `1:1` → `square`. Custom ratios → nearest named aspect.
+3. Call `image_generate(prompt=<assembled>, aspect_ratio=<enum>)` and extract the `image` URL from the returned JSON.
+4. **Backup rule**: If `{output-dir}/NN-{type}-{slug}.png` already exists, rename it via `terminal` (`mv "{output-dir}/NN-{type}-{slug}.png" "{output-dir}/NN-{type}-{slug}-backup-YYYYMMDD-HHMMSS.png"`) before writing.
+5. Download the URL via `terminal`:
+   ```bash
+   curl -sSL -o "{output-dir}/NN-{type}-{slug}.png" "{image_url}"
+   ```
+   If `curl` is unavailable, fall back to `wget -qO "{output-dir}/NN-{type}-{slug}.png" "{image_url}"`.
+6. Verify the file exists and has non-zero size (`terminal`: `test -s "{path}" && echo ok`).
+7. On generation failure, retry `image_generate` once. On download failure, retry `curl` once with a longer timeout. Then log and continue.
+8. After each generation, report "Generated X/N".
+
+---
+
+## Step 7: Finalize
+
+### 7.1 Update Article
+
+Insert after the corresponding paragraph, using the path relative to the article file:
+
+| Input | Insert Path |
+|-------|-------------|
+| Article file path (default `imgs-subdir`) | `![description](imgs/NN-{type}-{slug}.png)` |
+| Article file path (images alongside) | `![description](NN-{type}-{slug}.png)` |
+| Article file path (`illustrations/` subdirectory) | `![description](illustrations/NN-{type}-{slug}.png)` |
+| Pasted content | `![description](illustrations/{topic-slug}/NN-{type}-{slug}.png)` (relative to cwd) |
+
+Alt text: concise description in the article's language.
+
+### 7.2 Output Summary
+
+```
+Article Illustration Complete!
+
+Article: [path]
+Type: [type] | Density: [level] | Style: [style]
+Location: [directory]
+Images: X/N generated
+
+Positions:
+- 01-xxx.png → After "[Section]"
+- 02-yyy.png → After "[Section]"
+
+[If failures]
+Failed:
+- NN-zzz.png: [reason]
+```