From f3f886217b5e20d006d78c00939aec5bddadf729 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jim=20Liu=20=E5=AE=9D=E7=8E=89?= <junminliu@gmail.com>
Date: Sun, 12 Apr 2026 20:16:36 -0500
Subject: [PATCH] feat(baoyu-diagram): add multi-diagram mode for article-wide
 diagram generation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- New multi-diagram mode: analyze article content and generate diagrams at identified positions
- New options: --density (minimal/balanced/per-section/rich), --mode (single/multi/auto)
- Auto mode detection: file path or multi-paragraph content → multi, short topic → single
- Output structure: diagram/{article-slug}/NN-{type}-{slug}/diagram.svg + outline.md
- Step 7: insert diagram image links into article at identified positions
- Modification guide: regenerate/add/remove individual diagrams
- Version bumped to 1.1.0 in SKILL.md
---
 README.md                     |  23 +--
 README.zh.md                  |  25 +--
 skills/baoyu-diagram/SKILL.md | 306 ++++++++++++++++++++++++++++------
 3 files changed, 278 insertions(+), 76 deletions(-)

diff --git a/README.md b/README.md
index a1a1eb8..1d24f55 100644
--- a/README.md
+++ b/README.md
@@ -274,19 +274,18 @@ Generate professional infographics with 21 layout types and 21 visual styles. An
 
 #### baoyu-diagram
 
-Generate publication-ready SVG diagrams — flowcharts, structural/architecture diagrams, and illustrative intuition diagrams. Claude writes real SVG code directly following a cohesive design system. Output is a single self-contained `.svg` file with embedded styles and auto dark-mode, ready to embed in articles, WeChat posts, slides, Notion, and docs.
+Generate publication-ready SVG diagrams — flowcharts, sequence/protocol diagrams, structural/architecture diagrams, and illustrative intuition diagrams. Supports single-diagram mode (one topic) and multi-diagram mode (analyze article content and generate diagrams at identified positions). Claude writes real SVG code directly following a cohesive design system. Output is self-contained `.svg` files with embedded styles and auto dark-mode.
 
 ```bash
-# Auto-route on the verb in the prompt
+# Single-diagram mode: auto-route on the verb in the prompt
 /baoyu-diagram "how JWT authentication works"
-
-# Force a specific type
 /baoyu-diagram "Kubernetes architecture" --type structural
-/baoyu-diagram "how attention works"     --type illustrative
-/baoyu-diagram "CI/CD pipeline"          --type flowchart
+/baoyu-diagram "OAuth 2.0 flow"          --type sequence
 
-# From a markdown source file
-/baoyu-diagram path/to/content.md
+# Multi-diagram mode: analyze article and generate diagrams at identified positions
+/baoyu-diagram path/to/article.md
+/baoyu-diagram path/to/article.md --density balanced
+/baoyu-diagram path/to/article.md --density per-section --lang zh
 
 # Language and output path
 /baoyu-diagram "微服务架构" --lang zh
@@ -296,17 +295,21 @@ Generate publication-ready SVG diagrams — flowcharts, structural/architecture
 **Options**:
 | Option | Description |
 |--------|-------------|
-| `--type <name>` | `flowchart`, `structural`, `illustrative`, `auto` (default) |
+| `--type <name>` | `flowchart`, `sequence`, `structural`, `illustrative`, `class`, `auto` (default). Forces single mode. |
 | `--lang <code>` | Output language (en, zh, ja, ...) |
-| `--out <path>` | Output file path (default: `diagram/{slug}/diagram.svg`) |
+| `--out <path>` | Output file path (default: `diagram/{slug}/diagram.svg`). Forces single mode. |
+| `--density <level>` | Multi mode only: `minimal` (1-2), `balanced` (3-5, default), `per-section`, `rich` (6+) |
+| `--mode <mode>` | `single`, `multi`, `auto` (default — detect from input) |
 
 **Diagram types**:
 
 | Type | Reader need | Verbs that trigger it |
 |------|-------------|------------------------|
 | `flowchart` | Walk me through the steps in order | walk through, steps, process, lifecycle, workflow, state machine |
+| `sequence` | Who talks to whom, in what order | protocol, handshake, auth flow, OAuth, TCP, request/response |
 | `structural` | Show me what's inside what, how it's organised | architecture, components, topology, layout, what's inside |
 | `illustrative` | Give me the intuition — draw the mechanism | how does X work, explain X, intuition for, why does X do Y |
+| `class` | What are the types and how are they related | class diagram, UML, inheritance, interface, schema |
 
 Not an image-generation skill — no LLM image model is called. Claude writes the SVG by hand with hand-computed layout math, so every diagram honors the design system. Embedded `<style>` block with `@media (prefers-color-scheme: dark)` means the same file renders correctly in both light and dark mode anywhere it's embedded.
 
diff --git a/README.zh.md b/README.zh.md
index 58922f4..281e1a1 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -274,19 +274,18 @@ clawhub install baoyu-markdown-to-html
 
 #### baoyu-diagram
 
-生成可直接发布的 SVG 图表 —— 包括流程图、架构/结构图、示意图（直觉图解）。Claude 直接输出符合统一设计规范的真实 SVG 代码，产物是单个自包含的 `.svg` 文件，内嵌样式并自动支持深色模式，可直接嵌入文章、微信公众号、幻灯片、Notion 和各类文档中。
+生成可直接发布的 SVG 图表 —— 包括流程图、时序/协议图、架构/结构图、示意图（直觉图解）。支持单图模式（针对一个主题）和多图模式（分析文章内容，在识别出的位置批量生成图表）。Claude 直接输出符合统一设计规范的真实 SVG 代码，产物是自包含的 `.svg` 文件，内嵌样式并自动支持深色模式。
 
 ```bash
-# 自动根据提示词中的动词路由类型
+# 单图模式：自动根据提示词中的动词路由类型
 /baoyu-diagram "JWT 认证流程是怎么工作的"
-
-# 强制指定类型
 /baoyu-diagram "Kubernetes 架构" --type structural
-/baoyu-diagram "注意力机制原理"   --type illustrative
-/baoyu-diagram "CI/CD 流水线"     --type flowchart
+/baoyu-diagram "OAuth 2.0 流程"  --type sequence
 
-# 从 Markdown 源文件生成
-/baoyu-diagram path/to/content.md
+# 多图模式：分析文章并在识别出的位置生成图表
+/baoyu-diagram path/to/article.md
+/baoyu-diagram path/to/article.md --density balanced
+/baoyu-diagram path/to/article.md --density per-section --lang zh
 
 # 语言和输出路径
 /baoyu-diagram "微服务架构" --lang zh
@@ -296,17 +295,21 @@ clawhub install baoyu-markdown-to-html
 **参数**：
 | 参数 | 说明 |
 |------|------|
-| `--type <name>` | `flowchart`（流程图）、`structural`（结构/架构图）、`illustrative`（示意图）、`auto`（默认，按动词路由） |
+| `--type <name>` | `flowchart`、`sequence`、`structural`、`illustrative`、`class`、`auto`（默认）。强制单图模式。 |
 | `--lang <code>` | 输出语言（en、zh、ja 等） |
-| `--out <path>` | 输出文件路径（默认：`diagram/{slug}/diagram.svg`） |
+| `--out <path>` | 输出文件路径（默认：`diagram/{slug}/diagram.svg`）。强制单图模式。 |
+| `--density <level>` | 仅多图模式：`minimal`（1-2 张）、`balanced`（3-5 张，默认）、`per-section`、`rich`（6+ 张） |
+| `--mode <mode>` | `single`、`multi`、`auto`（默认，自动根据输入判断） |
 
-**三种图表类型**：
+**五种图表类型**：
 
 | 类型 | 适用场景 | 触发动词 |
 |------|----------|----------|
 | `flowchart` | 按顺序走一遍流程 | 流程、步骤、工作流、生命周期、状态机 |
+| `sequence` | 谁和谁通信、按什么顺序 | 协议、握手、认证流程、OAuth、TCP、请求/响应 |
 | `structural` | 展示什么包含什么、如何组织 | 架构、组件、拓扑、布局、什么在什么里面 |
 | `illustrative` | 建立直觉 —— 画出机制本身 | 怎么工作、原理、为什么、直观解释 |
+| `class` | 类型是什么、它们如何关联 | 类图、UML、继承、接口、数据模型 |
 
 本技能不调用任何图像生成模型 —— Claude 通过手算坐标直接写 SVG 代码，确保每个图表都遵守设计规范。内嵌的 `<style>` 块包含 `@media (prefers-color-scheme: dark)`，同一个文件在浅色和深色模式下均正确渲染，可嵌入到任意支持 SVG 的宿主环境中。
 
diff --git a/skills/baoyu-diagram/SKILL.md b/skills/baoyu-diagram/SKILL.md
index 411e2fa..ea358a7 100644
--- a/skills/baoyu-diagram/SKILL.md
+++ b/skills/baoyu-diagram/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: baoyu-diagram
-description: Generates publication-ready SVG diagrams — flowcharts, sequence/protocol diagrams, structural/architecture diagrams, and illustrative intuition diagrams — by writing real SVG code directly following a cohesive design system. Use whenever the user asks to "draw a flowchart", "draw a sequence diagram", "show the OAuth / TCP / auth protocol", "make an architecture diagram", "explain how X works visually", "画流程图", "画时序图", "画架构图", "画示意图", "画图解", or wants a clean, embeddable vector diagram for articles, WeChat posts, slides, or docs. Output is a single self-contained .svg file that renders correctly in light and dark mode anywhere it is embedded.
-version: 1.0.0
+description: Generates publication-ready SVG diagrams — flowcharts, sequence/protocol diagrams, structural/architecture diagrams, and illustrative intuition diagrams — by writing real SVG code directly following a cohesive design system. Supports both single-diagram mode (topic-based) and multi-diagram mode (analyze article content and generate multiple diagrams at identified positions). Use whenever the user asks to "draw a flowchart", "draw a sequence diagram", "show the OAuth / TCP / auth protocol", "make an architecture diagram", "explain how X works visually", "illustrate this article with diagrams", "为文章画图解", "画流程图", "画时序图", "画架构图", "画示意图", "画图解", or wants clean, embeddable vector diagrams for articles, WeChat posts, slides, or docs. Output is one or more self-contained .svg files that render correctly in light and dark mode anywhere they are embedded.
+version: 1.1.0
 metadata:
   openclaw:
     homepage: https://github.com/JimLiu/baoyu-skills#baoyu-diagram
@@ -9,12 +9,16 @@ metadata:
 
 # Diagram Generator
 
-Write **real SVG code** directly, following a consistent design system, the output is a single `.svg` file that is self-contained (embedded styles, auto dark-mode), editable by humans, scales to any size without quality loss, and embeds cleanly into articles, WeChat posts, slide decks, Notion, and markdown.
+Write **real SVG code** directly, following a consistent design system, the output is self-contained `.svg` files (embedded styles, auto dark-mode), editable by humans, scales to any size without quality loss, and embeds cleanly into articles, WeChat posts, slide decks, Notion, and markdown.
+
+When given article or document content, the skill analyzes structure, identifies concepts that benefit from diagramming, and generates multiple diagrams — each with its own type, layout plan, and SVG. When given a single topic, it generates one diagram.
 
 This is not an image-generation skill — it does not call any LLM image model. Claude writes the SVG node-by-node, doing the layout math by hand so every diagram honors the rules in `references/`.
 
 ## Usage
 
+### Single-diagram mode
+
 ```bash
 # Prompt for the topic if no argument given
 /baoyu-diagram
@@ -22,8 +26,8 @@ This is not an image-generation skill — it does not call any LLM image model.
 # Plain-text description
 /baoyu-diagram "how JWT authentication works"
 
-# Path to a markdown file as source content
-/baoyu-diagram path/to/content.md
+# Path to a markdown file as source content (single diagram about one topic)
+/baoyu-diagram path/to/content.md --mode single
 
 # Force a specific diagram type
 /baoyu-diagram "transformer attention"    --type illustrative
@@ -37,13 +41,41 @@ This is not an image-generation skill — it does not call any LLM image model.
 /baoyu-diagram "build pipeline" --out docs/build-pipeline.svg
 ```
 
+### Multi-diagram mode
+
+```bash
+# Analyze article and generate diagrams at identified positions
+/baoyu-diagram path/to/article.md
+
+# With density control
+/baoyu-diagram path/to/article.md --density balanced
+/baoyu-diagram path/to/article.md --density per-section --lang zh
+
+# Force multi mode on pasted content
+/baoyu-diagram --mode multi
+```
+
+### Mode detection
+
+| Signal | Mode |
+|--------|------|
+| File path to `.md` / `.txt` (unless `--mode single`) | **Multi** |
+| Multi-paragraph pasted content (unless `--mode single`) | **Multi** |
+| Short quoted topic string (under ~100 chars, no markdown structure) | **Single** |
+| `--type` given | **Single** (forces) |
+| `--out` given | **Single** (forces) |
+| `--mode single` or `--mode multi` | Forced by flag |
+| Ambiguous | Ask with AskUserQuestion |
+
 ## Options
 
 | Option | Values |
 |--------|--------|
-| `--type` | `flowchart`, `sequence`, `structural`, `illustrative`, `class`, `auto` (default — route on verb) |
+| `--type` | `flowchart`, `sequence`, `structural`, `illustrative`, `class`, `auto` (default — route on verb). Forces single-diagram mode. |
 | `--lang` | `en`, `zh`, `ja`, `ko`, ... (default: match the user's language) |
-| `--out` | Output file path (default: `diagram/{slug}/diagram.svg`) |
+| `--out` | Output file path (default: `diagram/{slug}/diagram.svg`). Forces single-diagram mode. |
+| `--density` | `minimal` (1-2), `balanced` (3-5, default), `per-section`, `rich` (6+). Multi-diagram mode only. |
+| `--mode` | `single`, `multi`, `auto` (default). Override automatic mode detection. |
 
 ## Diagram types
 
@@ -108,11 +140,116 @@ Cycles, ERDs, and gantt charts are **out of scope for v1**. For cycles, draw the
 
 ## Workflow
 
-### Step 1: Capture intent
+### Step 1: Detect mode and capture input
 
-Read the user's prompt or content file. If the topic is missing, ask for it with AskUserQuestion.
+Read the user's prompt, content file, or pasted content. Determine the mode:
 
-**Before routing, extract these five things from the source:**
+| Signal | Mode |
+|--------|------|
+| Short topic string, `--type` given, or `--out` given | **Single** |
+| File path to `.md` / `.txt`, or multi-paragraph pasted content | **Multi** |
+| `--mode single` or `--mode multi` | Forced by flag |
+| Ambiguous (medium-length text, unclear if topic or content) | Ask with AskUserQuestion |
+
+**Single mode** → jump to Step 5.
+
+**Multi mode** → continue to Step 2.
+
+If input is a file path, read the file. If input is pasted content, note it for saving later. If no input at all, ask for it with AskUserQuestion.
+
+### Step 2: Analyze content (multi-diagram mode)
+
+Analyze the article or document for diagramming opportunities. For each section or concept cluster, determine:
+
+| Analysis | Output |
+|----------|--------|
+| Content structure | Sections, subsections, key transitions |
+| Core concepts | 2-8 concepts that benefit from visual explanation |
+| Diagram positions | Where in the article each diagram belongs (anchored to specific paragraphs or headings) |
+| Per-position type signal | What verb/need drives each diagram (→ routing table in "Diagram types") |
+| Per-position complexity | Simple (3-4 nodes) vs. complex (poster/subsystem) |
+
+**What to diagram:**
+- Core mechanisms the reader needs to *understand* (→ illustrative)
+- Multi-step processes described in prose (→ flowchart)
+- Multi-actor interactions (→ sequence)
+- Architectural descriptions with containment or hierarchy (→ structural)
+- Type hierarchies or data models (→ class)
+- Comparisons between two approaches or systems (→ structural subsystem)
+
+**What NOT to diagram:**
+- Simple lists — a bullet list is already visual enough
+- Concepts already shown in an existing image or figure in the article
+- Purely emotional or narrative passages with no underlying mechanism
+- Content that is a single sentence or trivially simple
+- Decorative filler — every diagram must earn its place with a concrete reader need
+
+**Output**: A list of N candidate diagram positions, each with: section anchor, tentative type, named elements, and the "After seeing this diagram, the reader understands ___" sentence.
+
+### Step 3: Confirm settings (multi-diagram mode)
+
+**ONE AskUserQuestion, max 3 questions. Q1 required. Q2 required unless `--density` given.**
+
+| Q | When to ask | Options |
+|---|-------------|---------|
+| **Q1: Diagram positions** | Always | Show the N candidate positions with tentative types. "I identified N positions for diagrams: [numbered list with section anchor + type + one-line purpose]. Adjust, add, or remove?" |
+| **Q2: Density** | No `--density` flag | minimal (1-2 core concepts only), balanced (3-5 major concepts, Recommended), per-section (one per section/chapter), rich (6+ comprehensive) |
+| **Q3: Language** | Article language ≠ user's language or `--lang` | Which language for diagram labels? |
+
+After confirmation, finalize the list of diagrams to generate. If the user adjusts positions or types, update accordingly.
+
+### Step 4: Generate outline (multi-diagram mode)
+
+Save `outline.md` with YAML frontmatter and per-diagram entries:
+
+```yaml
+---
+article: path/to/article.md    # or "pasted content"
+slug: article-topic-slug
+density: balanced
+diagram_count: 4
+language: en
+---
+```
+
+Per-diagram entry format:
+
+```markdown
+## Diagram 1
+**Position**: [section name / paragraph anchor, e.g. "Section 2, after 'Authentication is the first step...'"]
+**Purpose**: [why this diagram helps the reader]
+**Type**: [flowchart | sequence | structural | illustrative | class]
+**Named elements**: [list of actors, components, states, or concepts]
+**Reader need**: "After seeing this diagram, the reader understands ___"
+**Slug**: [2-4 kebab-case words]
+**Filename**: 01-{type}-{slug}/diagram.svg
+```
+
+**Requirements**:
+- Each position justified by a concrete reader need (the "After seeing this..." sentence)
+- Type chosen per the routing table, not arbitrarily
+- Count matches the confirmed density
+- If input was pasted content, also save it as `source-{slug}.md` in the output directory
+
+Save to `diagram/{article-slug}/outline.md`.
+
+### Step 5: Load shared references
+
+**Always read**:
+- `references/design-system.md` — philosophy, typography, color palette, hard rules
+- `references/svg-template.md` — the `<style>` + `<defs>` boilerplate to copy verbatim
+- `references/layout-math.md` — text-width estimation, viewBox sizing, arrow routing
+- `references/pitfalls.md` — the pre-save checklist
+
+Per-type reference files are loaded inside the generation loop (Step 6b) since each diagram may have a different type.
+
+### Step 6: Per-diagram generation loop
+
+For each diagram (single iteration in single mode, N iterations in multi mode):
+
+#### 6a: Capture intent
+
+**Single mode**: Read the user's prompt. Extract these five things from the source:
 
 1. **Named elements** — list every distinct actor, component, service, state, or phase explicitly named. Count them. If the count is 6+, plan multiple diagrams rather than cramming everything into one (see `flowchart.md` → "Planning before you write SVG").
 
@@ -125,23 +262,17 @@ Read the user's prompt or content file. If the topic is missing, ask for it with
 
 3. **What the reader needs** — complete this sentence before routing: *"After seeing this diagram, the reader understands ___."* If you can't finish it, the topic is underspecified — ask.
 
-4. **Label preview** — for each element name, count the characters. Latin titles >30 chars (CJK >16) will overflow a 180-wide box and need shortening. Draft the abbreviated form now, before layout math, so Step 4 uses real labels.
+4. **Label preview** — for each element name, count the characters. Latin titles >30 chars (CJK >16) will overflow a 180-wide box and need shortening. Draft the abbreviated form now, before layout math, so Step 6d uses real labels.
 
-5. **Language** — CJK vs. Latin. Affects text-width multipliers in Step 4 (15 px/char vs. 8 px/char for titles). Mixed content (CJK labels with some Latin terms) counts as CJK.
+5. **Language** — CJK vs. Latin. Affects text-width multipliers in Step 6d (15 px/char vs. 8 px/char for titles). Mixed content (CJK labels with some Latin terms) counts as CJK.
 
-### Step 2: Route the diagram type
+**Multi mode**: Most of this was already done in Steps 2/4. Read the current diagram's outline entry. Refine the named elements and label preview now, for this specific diagram.
 
-Match the user's phrasing to the table above. If `--type` is given, use it. Otherwise route on the verb. When genuinely ambiguous between flowchart and illustrative, default to **illustrative** — the reader almost always benefits more from intuition than from a list of steps.
+#### 6b: Route type and load type reference
 
-Tell the user which type you picked and why, in one sentence. Do not ask for confirmation — the type can always be changed with `--type` on a rerun.
+**Single mode**: Match the user's phrasing to the routing table in "Diagram types". If `--type` is given, use it. Otherwise route on the verb. When genuinely ambiguous between flowchart and illustrative, default to **illustrative**. Tell the user which type you picked and why, in one sentence.
 
-### Step 3: Load references
-
-**Always read**:
-- `references/design-system.md` — philosophy, typography, color palette, hard rules
-- `references/svg-template.md` — the `<style>` + `<defs>` boilerplate to copy verbatim
-- `references/layout-math.md` — text-width estimation, viewBox sizing, arrow routing
-- `references/pitfalls.md` — the pre-save checklist
+**Multi mode**: The type was already determined in the outline. Load the matching reference file now.
 
 **Read the one that matches the type**:
 - `references/flowchart.md`
@@ -154,36 +285,36 @@ Tell the user which type you picked and why, in one sentence. Do not ask for con
 - `references/glyphs.md` — the shared glyph library, tool card icon set, operator icons, and dark-mode rules
 
 **Read on demand for diagram type extensions:**
-- `references/flowchart-poster.md` — when ≥3 poster-mode triggers fire in Step 4a (topic has a short name, named phases, parallel candidates, a loop termination mechanic, overflow annotations, or a footer quote)
-- `references/flowchart-phase-bands.md` — when the prompt describes a multi-phase sequential operation where each phase contains parallel tools or steps and outcomes propagate between phases ("phase 1/2/3", "attack phases", "phased workflow with tools")
-- `references/structural-network.md` — when drawing network topology: zone containers, wired/wireless device connectivity, security zones (DMZ / VPC / firewall)
-- `references/structural-matrix.md` — when drawing a comparison matrix: feature table, ✓/✗ cells, side-by-side "option × attribute" grid
+- `references/flowchart-poster.md` — when ≥3 poster-mode triggers fire in Step 6d (topic has a short name, named phases, parallel candidates, a loop termination mechanic, overflow annotations, or a footer quote)
+- `references/flowchart-phase-bands.md` — when the prompt describes a multi-phase sequential operation where each phase contains parallel tools or steps and outcomes propagate between phases
+- `references/structural-network.md` — when drawing network topology: zone containers, wired/wireless device connectivity, security zones
+- `references/structural-matrix.md` — when drawing a comparison matrix: feature table, ✓/✗ cells, side-by-side grid
 
-### Step 3.5: Check the patterns library
+#### 6c: Check patterns library
 
-If the user's topic matches a known AI-system pattern (multi-agent research, message bus, shared state, agent with skills, contextual retrieval), there is a pre-cooked starter plan in `references/patterns/`. Scan `references/patterns/README.md` for a pattern name that matches the prompt. If one matches, load that pattern file and use its mermaid reference + baoyu SVG plan as the starting point for Step 4 — the node list, widths, and arrow routing are already drafted, and you only need to adapt labels.
+If the topic matches a known AI-system pattern, there is a pre-cooked starter plan in `references/patterns/`. Scan `references/patterns/README.md` for a pattern name that matches. If one matches, load that pattern file and use its mermaid reference + baoyu SVG plan as the starting point for Step 6d.
 
-If nothing matches, skip this step and plan from scratch in Step 4. Do not force a near-miss: two patterns that share a surface name may have genuinely different topologies, and using the wrong pre-plan is worse than planning from scratch.
+If nothing matches, skip and plan from scratch in Step 6d. Do not force a near-miss.
 
-### Step 4: Plan on paper first
+#### 6d: Plan on paper
 
 Before writing any SVG, draft a short layout plan. Do the math once, correctly, so the SVG comes out right on the first pass.
 
-**4a. Extract structure from the source** — don't just transcribe the user's bullets into boxes. Read the source looking for these elements. Not every element will be present, but every present element should land in the diagram:
+**6d-i. Extract structure from the source** — don't just transcribe bullets into boxes. Read the source looking for these elements. Not every element will be present, but every present element should land in the diagram:
 
 - **Mechanism name** — does the topic have a short, nameable identity (Autoreason, AutoResearch, OAuth, JWT auth, Reflexion loop)? If yes, that's a candidate `.title`.
-- **Framing question** — does the source contain a "why does this exist" sentence? Usually in the form *"Problem X has no Y, so we built Z to …"*. That's a candidate subtitle.
-- **Phases** — do the stages naturally cluster into 2–4 named groups (setup / loop body / judgment / convergence)? Each cluster is a candidate `.eyebrow` section.
+- **Framing question** — does the source contain a "why does this exist" sentence? That's a candidate subtitle.
+- **Phases** — do the stages naturally cluster into 2–4 named groups? Each cluster is a candidate `.eyebrow` section.
 - **Anchor inputs** — is there a constant input (the task prompt, a dataset, a knowledge base) that every stage references? That's a candidate anchor box above the main flow.
-- **Parallel candidates** — at some point, does the process generate N alternatives that are then compared? "Produce A, B, AB and pick the best" is a candidate fan-out + judge pattern. **Watch for the implicit "keep unchanged" candidate** — many iterative methods include "the incumbent wins by default" as one of the options, even when the source doesn't name it explicitly.
-- **Loop scope + termination** — which boxes are inside a loop that repeats? What is the *specific* termination rule — streak counter, convergence check, iteration cap, quality threshold? That's a candidate left-rail loop bracket + a dedicated termination box.
-- **Per-box context that won't fit in a subtitle** — "sees task + A + critique / adversarial / fresh context" is too long for a 5-word subtitle but too important to drop. Those are candidate right-column `.anno` annotations.
+- **Parallel candidates** — at some point, does the process generate N alternatives that are then compared? **Watch for the implicit "keep unchanged" candidate.**
+- **Loop scope + termination** — which boxes are inside a loop that repeats? What is the *specific* termination rule? That's a candidate left-rail loop bracket + a dedicated termination box.
+- **Per-box context that won't fit in a subtitle** — those are candidate right-column `.anno` annotations.
 - **Quotable hook** — does the source end with a test result, a quote, or a memorable framing? That's a candidate footer `.caption`.
-- **Role categories** — how many *distinct kinds* of operation does the process have (draft / critique / synthesize / judge)? This determines the color budget. Identity is a category, not a sequence.
+- **Role categories** — how many *distinct kinds* of operation does the process have? This determines the color budget. Identity is a category, not a sequence.
 
 Write the answers to these in the plan file. If ≥3 of them land, you're building a **poster flowchart** — load `references/flowchart-poster.md` and follow its coordinate budget. Otherwise, it's a simple flowchart and the linear-top-down pattern applies.
 
-**4b. Draft the layout:**
+**6d-ii. Draft the layout:**
 
 1. **List the nodes / regions / shapes** with their full label text (title + optional subtitle).
    - Simple flowchart: ≤5 nodes.
@@ -202,9 +333,11 @@ Write the answers to these in the plan file. If ≥3 of them land, you're buildi
 5. **Map arrows** and verify none cross an unrelated box. Use L-bends where a straight line would collide. (Sequence messages are always straight horizontal lines — no L-bends. Fan-out candidates converge to a common `ymid` channel just above the judge box.)
 6. **Compute viewBox height**: `H = max_y + 20` where `max_y` is the bottom of the lowest element. Poster flowcharts routinely reach H=800–950 — don't force them to be compact.
 
-Save this plan to `diagram/{slug}/plan.md` so iteration runs can re-read it.
+Save this plan:
+- **Single mode**: `diagram/{slug}/plan.md`
+- **Multi mode**: `diagram/{article-slug}/NN-{type}-{slug}/plan.md`
 
-### Step 5: Write the SVG
+#### 6e: Write the SVG
 
 Emit a single `<svg width="100%" viewBox="0 0 680 H">` element. Copy the `<style>` + `<defs>` block from `svg-template.md` **verbatim** — don't abbreviate or edit the color ramp definitions. Then add visual elements in z-order:
 
@@ -220,7 +353,7 @@ Typography rules:
 - Sentence case everywhere — "User login" not "User Login"
 - Every `<text>` element gets a class (`t`, `ts`, or `th`) — never hardcode fill colors on text
 
-### Step 6: Run the pre-save checklist
+#### 6f: Run the pre-save checklist
 
 Walk through every item in `references/pitfalls.md`. The top failures to catch every time:
 
@@ -236,25 +369,25 @@ Walk through every item in `references/pitfalls.md`. The top failures to catch e
 
 If any item fails, fix the SVG before saving. Don't rationalize past a failure — the checklist exists because these bugs are silent: the SVG is valid but looks wrong when rendered.
 
-### Step 7: Save output
+#### 6g: Save and report progress
 
-If `--out` is given, save the SVG there and skip the scaffolded directory. Otherwise use the default layout:
+Save the SVG and plan:
+- **Single mode**: `diagram/{slug}/plan.md` + `diagram.svg`
+- **Multi mode**: `diagram/{article-slug}/NN-{type}-{slug}/plan.md` + `diagram.svg`
 
-```
-diagram/{topic-slug}/
-├── source-{slug}.md          # optional: user's input content if provided
-├── plan.md                   # layout sketch from Step 4
-└── diagram.svg               # final output
-```
+**Backup rule**: if `diagram.svg` already exists at the target path, rename the existing one to `diagram-backup-YYYYMMDD-HHMMSS.svg` before writing the new file — never overwrite prior work silently.
 
-- **Slug**: 2–4 kebab-case words derived from the topic.
-- **Backup rule**: if `diagram.svg` already exists at the target path, rename the existing one to `diagram-backup-YYYYMMDD-HHMMSS.svg` before writing the new file — never overwrite prior work silently.
-- **Plan**: always save `plan.md` from Step 4 beside the SVG so the next iteration can re-read it.
-- **Source**: if the user pasted source content, save it as `source-{slug}.md` in the same directory.
+**Multi mode progress**: after each diagram, report progress: "Generated 2/4: 02-illustrative-jwt-token-structure".
+
+### Step 7: Finalize (multi-diagram mode)
+
+If input was a file path, insert `![description](relative-path/NN-{type}-{slug}/diagram.svg)` at each identified position in the article. Compute the relative path based on the article location vs. the diagram output directory.
+
+If input was pasted content, skip insertion — the diagrams are generated and the outline records positions, but there's no source file to modify.
 
 ### Step 8: Report
 
-Tell the user in 4-6 lines:
+**Single mode** — tell the user in 4-6 lines:
 - Diagram type picked (and one-sentence why)
 - Node count / complexity
 - viewBox dimensions
@@ -262,10 +395,73 @@ Tell the user in 4-6 lines:
 - Output file path
 - One suggestion for how to preview it (e.g., "Open in Chrome for light/dark check")
 
+**Multi mode**:
+
+```
+Article Diagram Generation Complete!
+
+Article: [path or "pasted content"]
+Density: [level] | Language: [lang]
+Diagrams: X/N generated
+
+Positions:
+- 01-sequence-jwt-auth-flow → After "Authentication is the first step..."
+- 02-illustrative-jwt-token-structure → After "The token structure..."
+- 03-flowchart-token-refresh → After "When the token expires..."
+- 04-structural-microservice-auth → After "In a microservices architecture..."
+
+Output: diagram/{article-slug}/
+Preview: Open any .svg in Chrome for light/dark check
+```
+
+## Output structure
+
+### Single-diagram mode
+
+```
+diagram/{topic-slug}/
+├── source-{slug}.md          # optional: user's input content if provided
+├── plan.md                   # layout sketch from Step 6d
+└── diagram.svg               # final output
+```
+
+### Multi-diagram mode
+
+```
+diagram/{article-slug}/
+├── source-{slug}.md          # saved input content (file copy or pasted content)
+├── outline.md                # frontmatter + all diagram entries from Step 4
+├── 01-{type}-{slug}/
+│   ├── plan.md               # layout sketch for this diagram
+│   └── diagram.svg           # final SVG
+├── 02-{type}-{slug}/
+│   ├── plan.md
+│   └── diagram.svg
+└── 03-{type}-{slug}/
+    ├── plan.md
+    └── diagram.svg
+```
+
+- **Slug**: 2–4 kebab-case words derived from the topic or concept.
+- **Backup rule**: if `diagram.svg` already exists at the target path, rename the existing one to `diagram-backup-YYYYMMDD-HHMMSS.svg` before writing the new file.
+- **Plan**: always save `plan.md` beside the SVG so the next iteration can re-read it.
+- **Source**: if the user pasted source content, save it as `source-{slug}.md` in the output directory.
+- **Numbering**: NN prefix (01, 02, ...) matches the outline order, which matches article position order.
+- **Outline**: in multi mode, always save `outline.md` from Step 4 so the generation can be resumed or individual diagrams can be regenerated.
+
+## Modification
+
+| Action | Steps |
+|--------|-------|
+| **Regenerate one diagram** (multi mode) | Re-read `outline.md` → find the entry → re-run Step 6 for that diagram only → update the SVG |
+| **Add a diagram** (multi mode) | Identify position → add entry to `outline.md` → run Step 6 for the new entry → insert into article |
+| **Remove a diagram** (multi mode) | Delete the `NN-{type}-{slug}/` directory → remove entry from `outline.md` → remove `![...]` from article |
+| **Change type** (single or multi) | Update the outline entry or re-run with `--type` → regenerate |
+
 ## Core principles
 
 - **Draw the mechanism, not a diagram about the mechanism** (illustrative). **Draw the sequence, not the architecture** (flowchart). **Draw the containment, not the flow** (structural). **Draw the conversation, not the steps** (sequence). Picking the wrong type is the single biggest failure mode — more harmful than any layout bug.
-- **One design system, always.** No `--style` flag, no alternate themes, no per-topic visual variants. The cohesive look across every diagram is the product — if a reader sees two baoyu diagrams in different articles, they should feel they came from the same hand. Any request to "use a different style" is a request to break this principle; push back and ask what the underlying need is instead.
+- **One design system, always.** No `--style` flag, no alternate themes, no per-topic visual variants. The cohesive look across every diagram is the product — if a reader sees two baoyu diagrams in different articles, they should feel they came from the same hand. Any request to "use a different style" is a request to break this principle; push back and ask what the underlying need is instead. In multi-diagram mode, all diagrams in a run share the same design system — no per-diagram style overrides.
 - **Self-contained output.** Every SVG carries its own styles and dark-mode rules. The reader should never need to edit anything after pasting it into their article.
 - **Math before markup.** SVG has no auto-layout. Every coordinate is hand-computed. A diagram that "almost fits" has a bug — fix the math, don't nudge pixels.
 - **Color encodes meaning, not position.** Five steps in a flowchart are not five colors. All five are gray unless one specific step deserves emphasis — in which case it gets the accent color.