chore: release v1.106.0

Remove single/multi mode split. Skill now analyzes any input material,
recommends diagram types and splitting strategy, confirms once, then generates.

.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Skills shared by Baoyu for improving daily work efficiency",
-    "version": "1.104.0"
+    "version": "1.106.0"
   },
   "plugins": [
     {

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 English | [中文](./CHANGELOG.zh.md)
 
+## 1.106.0 - 2026-04-14
+
+### Features
+- `baoyu-diagram`: add architecture enrichment rules — automatically expand architecture diagrams with multiple client types, per-service tech stacks, database tiers, message buses, and color-coded categories; add full structural layout patterns, architecture-specific pitfalls, network topology templates, and layout math for complex diagrams
+
+## 1.105.0 - 2026-04-13
+
+### Features
+- `baoyu-diagram`: unify to analyze→confirm→generate workflow — remove single/multi mode split; skill now analyzes any input material, recommends diagram types and splitting strategy, confirms once, then generates all diagrams
+
 ## 1.104.0 - 2026-04-13
 
 ### Features

CHANGELOG.zh.md

@@ -2,6 +2,16 @@
 
 [English](./CHANGELOG.md) | 中文
 
+## 1.106.0 - 2026-04-14
+
+### 新功能
+- `baoyu-diagram`：新增架构图丰富化规则 —— 自动扩展架构图，补充多客户端类型、各服务技术栈、数据库分层、消息总线和分色分类；新增完整结构布局模式、架构专用陷阱提示、网络拓扑模板和复杂图表布局计算
+
+## 1.105.0 - 2026-04-13
+
+### 新功能
+- `baoyu-diagram`：统一为分析→确认→生成工作流 —— 移除单图/多图模式区分；技能现在分析任意输入素材，推荐图表类型和拆分策略，一次确认后批量生成所有图表
+
 ## 1.104.0 - 2026-04-13
 
 ### 新功能

CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md
 
-Claude Code marketplace plugin providing AI-powered content generation skills. Version: **1.104.0**.
+Claude Code marketplace plugin providing AI-powered content generation skills. Version: **1.106.0**.
 
 ## Architecture
 

README.md

@@ -274,18 +274,16 @@ Generate professional infographics with 21 layout types and 21 visual styles. An
 
 #### baoyu-diagram
 
-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.
+Generate publication-ready SVG diagrams from source material — flowcharts, sequence/protocol diagrams, structural/architecture diagrams, and illustrative intuition diagrams. Analyzes input material to recommend diagram type(s) and splitting strategy, confirms the plan once, then generates all diagrams. 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
-# Single-diagram mode: auto-route on the verb in the prompt
+# Topic string — skill analyzes and proposes a plan
 /baoyu-diagram "how JWT authentication works"
 /baoyu-diagram "Kubernetes architecture" --type structural
 /baoyu-diagram "OAuth 2.0 flow"          --type sequence
 
-# Multi-diagram mode: analyze article and generate diagrams at identified positions
+# File path — skill reads, analyzes, and proposes a plan
 /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
@@ -295,11 +293,9 @@ Generate publication-ready SVG diagrams — flowcharts, sequence/protocol diagra
 **Options**:
 | Option | Description |
 |--------|-------------|
-| `--type <name>` | `flowchart`, `sequence`, `structural`, `illustrative`, `class`, `auto` (default). Forces single mode. |
+| `--type <name>` | `flowchart`, `sequence`, `structural`, `illustrative`, `class`, `auto` (default). Skips type recommendation. |
 | `--lang <code>` | Output language (en, zh, ja, ...) |
-| `--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) |
+| `--out <path>` | Output file path. Generates exactly one diagram focused on the most important aspect. |
 
 **Diagram types**:
 

README.zh.md

@@ -274,18 +274,16 @@ clawhub install baoyu-markdown-to-html
 
 #### baoyu-diagram
 
-生成可直接发布的 SVG 图表 —— 包括流程图、时序/协议图、架构/结构图、示意图（直觉图解）。支持单图模式（针对一个主题）和多图模式（分析文章内容，在识别出的位置批量生成图表）。Claude 直接输出符合统一设计规范的真实 SVG 代码，产物是自包含的 `.svg` 文件，内嵌样式并自动支持深色模式。
+从源素材生成可直接发布的 SVG 图表 —— 包括流程图、时序/协议图、架构/结构图、示意图（直觉图解）。分析输入素材，推荐图表类型和拆分策略，一次确认后批量生成。Claude 直接输出符合统一设计规范的真实 SVG 代码，产物是自包含的 `.svg` 文件，内嵌样式并自动支持深色模式。
 
 ```bash
-# 单图模式：自动根据提示词中的动词路由类型
+# 主题描述 —— 技能分析并提出方案
 /baoyu-diagram "JWT 认证流程是怎么工作的"
 /baoyu-diagram "Kubernetes 架构" --type structural
 /baoyu-diagram "OAuth 2.0 流程"  --type sequence
 
-# 多图模式：分析文章并在识别出的位置生成图表
+# 文件路径 —— 技能读取、分析并提出方案
 /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
@@ -295,11 +293,9 @@ clawhub install baoyu-markdown-to-html
 **参数**：
 | 参数 | 说明 |
 |------|------|
-| `--type <name>` | `flowchart`、`sequence`、`structural`、`illustrative`、`class`、`auto`（默认）。强制单图模式。 |
+| `--type <name>` | `flowchart`、`sequence`、`structural`、`illustrative`、`class`、`auto`（默认）。跳过类型推荐直接生成。 |
 | `--lang <code>` | 输出语言（en、zh、ja 等） |
-| `--out <path>` | 输出文件路径（默认：`diagram/{slug}/diagram.svg`）。强制单图模式。 |
-| `--density <level>` | 仅多图模式：`minimal`（1-2 张）、`balanced`（3-5 张，默认）、`per-section`、`rich`（6+ 张） |
-| `--mode <mode>` | `single`、`multi`、`auto`（默认，自动根据输入判断） |
+| `--out <path>` | 输出文件路径。生成聚焦于最重要内容的单张图表。 |
 
 **五种图表类型**：
 

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. 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
+description: Generates publication-ready SVG diagrams from source material — flowcharts, sequence/protocol diagrams, structural/architecture diagrams, and illustrative intuition diagrams — by writing real SVG code directly following a cohesive design system. Analyzes input material to recommend diagram type(s), splitting strategy, and optional overview diagram, then generates after one-time confirmation. 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", "draw a diagram for this", "画流程图", "画时序图", "画架构图", "画示意图", "画图", 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.2.0
 metadata:
   openclaw:
     homepage: https://github.com/JimLiu/baoyu-skills#baoyu-diagram
@@ -11,25 +11,23 @@ metadata:
 
 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.
+When given source material (topic descriptions, documents, technical specs, pasted content), the skill analyzes what diagrams would best convey the material, recommends diagram type(s) and whether the content should be split into multiple focused diagrams, confirms the plan once, then generates all diagrams.
 
 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
-
-# Plain-text description
+# Topic string — skill analyzes and proposes a plan
 /baoyu-diagram "how JWT authentication works"
 
-# Path to a markdown file as source content (single diagram about one topic)
-/baoyu-diagram path/to/content.md --mode single
+# File path — skill reads, analyzes, and proposes a plan
+/baoyu-diagram path/to/content.md
 
-# Force a specific diagram type
+# Pasted content — prompts for input if no argument given
+/baoyu-diagram
+
+# Force a specific diagram type (skips type recommendation)
 /baoyu-diagram "transformer attention"    --type illustrative
 /baoyu-diagram "Kubernetes architecture"  --type structural
 /baoyu-diagram "CI/CD pipeline"           --type flowchart
@@ -41,41 +39,13 @@ 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). Forces single-diagram mode. |
+| `--type` | `flowchart`, `sequence`, `structural`, `illustrative`, `class`, `auto` (default — route on verb). When specified, forces this type for all diagrams — skips type recommendation. |
 | `--lang` | `en`, `zh`, `ja`, `ko`, ... (default: match the user's language) |
-| `--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. |
+| `--out` | Output file path. When set, the skill generates exactly one diagram at this path — analysis produces a single-diagram plan focused on the most important aspect of the material. |
 
 ## Diagram types
 
@@ -140,34 +110,47 @@ Cycles, ERDs, and gantt charts are **out of scope for v1**. For cycles, draw the
 
 ## Workflow
 
-### Step 1: Detect mode and capture input
+### Step 1: Capture input
 
-Read the user's prompt, content file, or pasted content. Determine the mode:
+Read the user's prompt, content file, or pasted content. Note any flags (`--type`, `--lang`, `--out`).
 
-| 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 |
+| Input | Action |
+|-------|--------|
+| File path to `.md` / `.txt` | Read the file as source material |
+| Pasted content or topic string | Capture as source material |
+| No input at all | Ask with AskUserQuestion |
 
-**Single mode** → jump to Step 5.
+If `--out` is given, the skill will generate exactly one diagram at that path — the analysis in Step 2 produces a single-diagram plan focused on the most important aspect of the material.
 
-**Multi mode** → continue to Step 2.
+### Step 2: Analyze material and produce plan
 
-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.
+Analyze the source material and make three decisions:
 
-### Step 2: Analyze content (multi-diagram mode)
+#### Decision A: Type routing
 
-Analyze the article or document for diagramming opportunities. For each section or concept cluster, determine:
+For the input material, determine which diagram type(s) are appropriate using the routing table in "Diagram types."
 
-| 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) |
+| Situation | Action |
+|-----------|--------|
+| Only one type makes sense (clear verb signal, or `--type` given) | That type is the recommendation. No choice needed. |
+| Multiple types could each produce a useful diagram from the same material | List the candidates with a one-sentence rationale for each. The user picks in Step 3. |
+
+#### Decision B: Content splitting
+
+Assess whether the material should produce one diagram or multiple sub-diagrams.
+
+**Single diagram** when:
+- Material is focused on one concept, one mechanism, one process
+- Named elements count is manageable (under ~6 for flowchart, under ~4 actors for sequence, under ~3 containers for structural — but architecture diagrams may have 10–20 elements in a single diagram; see Step 5a item 6, "Architecture enrichment")
+- One "After seeing this diagram, the reader understands ___" sentence covers the whole material
+
+**Multiple sub-diagrams** when:
+- Material covers 2+ independent mechanisms or processes
+- Named element count exceeds comfortable limits for one diagram type
+- Material has natural subsections that each deserve visual treatment
+- Different parts of the material map to different diagram types
+
+For each sub-diagram, determine: focus area, recommended type, named elements, and the "reader understands ___" sentence.
 
 **What to diagram:**
 - Core mechanisms the reader needs to *understand* (→ illustrative)
@@ -179,61 +162,106 @@ Analyze the article or document for diagramming opportunities. For each section
 
 **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
+- Concepts already shown in an existing image or figure
 - 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.
+#### Decision C: Overview diagram
 
-### Step 3: Confirm settings (multi-diagram mode)
+When the plan includes multiple sub-diagrams, assess whether an additional overview diagram that shows the big picture is worthwhile.
 
-**ONE AskUserQuestion, max 3 questions. Q1 required. Q2 required unless `--density` given.**
+| Situation | Decision |
+|-----------|----------|
+| Sub-diagrams are parts of a coherent system, seeing how they relate adds value | Include an overview diagram (typically structural or illustrative) |
+| Sub-diagrams cover independent topics that don't form a coherent whole | Skip the overview |
+| Material is simple enough that sub-diagrams already cover everything | Skip the overview |
 
-| 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? |
+#### Plan output
 
-After confirmation, finalize the list of diagrams to generate. If the user adjusts positions or types, update accordingly.
+Save the plan as `outline.md` (for multiple diagrams) or hold in memory (for single diagram).
 
-### Step 4: Generate outline (multi-diagram mode)
+**Single-diagram plan format:**
 
-Save `outline.md` with YAML frontmatter and per-diagram entries:
+```markdown
+## Diagram Plan
+**Material**: [source description]
+**Diagrams**: 1
+**Type**: [type] (rationale)
+**Named elements**: [list]
+**Reader need**: "After seeing this diagram, the reader understands ___"
+**Slug**: [slug]
+```
+
+**Multi-diagram plan format:**
 
 ```yaml
 ---
-article: path/to/article.md    # or "pasted content"
-slug: article-topic-slug
-density: balanced
-diagram_count: 4
+material: [source description]
+slug: [material-slug]
+diagram_count: N
 language: en
 ---
 ```
 
-Per-diagram entry format:
+Per-diagram entry:
 
 ```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]
+## Diagram 1: [focus area]
+**Type**: [type] (rationale)
+**Named elements**: [list]
 **Reader need**: "After seeing this diagram, the reader understands ___"
 **Slug**: [2-4 kebab-case words]
 **Filename**: 01-{type}-{slug}/diagram.svg
+
+## Diagram 2: [focus area]
+...
+
+## Overview diagram (if applicable)
+**Type**: [structural/illustrative]
+**Purpose**: Shows how diagrams 1-N relate as parts of a larger system
+**Named elements**: [high-level elements]
+**Slug**: overview-[slug]
+**Filename**: overview-{type}-{slug}/diagram.svg
 ```
 
-**Requirements**:
-- Each position justified by a concrete reader need (the "After seeing this..." sentence)
+Requirements:
+- Each diagram 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 3: Confirm plan (one-time)
 
-### Step 5: Load shared references
+**Maximum 1 AskUserQuestion call for the entire workflow.** This is the only confirmation step — no further questions during generation.
+
+| Plan shape | Confirmation |
+|------------|-------------|
+| Single diagram, obvious type (`--type` given, or clear verb signal) | **No confirmation.** Announce the type in one sentence and proceed to Step 4. |
+| Single diagram, ambiguous type (multiple types viable) | **Lightweight.** "The material could work as [type A] (rationale) or [type B] (rationale). Which do you prefer?" |
+| Multiple diagrams | **Full plan.** Show the numbered list of all planned diagrams with their types and purposes, plus overview if applicable. User can adjust (add/remove diagrams, change types, toggle overview) in one response. |
+
+Language question: only include if material language differs from user's language and `--lang` is not given.
+
+Example full plan confirmation:
+
+```
+I analyzed the material and recommend N diagrams [+ an overview]:
+
+1. [Focus area] — [type] — "Reader understands ___"
+2. [Focus area] — [type] — "Reader understands ___"
+3. [Focus area] — [type] — "Reader understands ___"
+[Overview: [type] — "Shows how 1-N relate as a system"]
+
+Adjust the plan? (add/remove diagrams, change types, skip/add overview)
+```
+
+After confirmation (or after skipping confirmation for obvious plans), the plan is locked. Proceed to generation.
+
+Save the finalized plan:
+- Multiple diagrams: `diagram/{material-slug}/outline.md`
+- Single diagram: plan is saved as `plan.md` beside the SVG in Step 5g
+
+### Step 4: Load shared references
 
 **Always read**:
 - `references/design-system.md` — philosophy, typography, color palette, hard rules
@@ -241,38 +269,50 @@ Save to `diagram/{article-slug}/outline.md`.
 - `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.
+Per-type reference files are loaded inside the generation loop (Step 5b) since each diagram may have a different type.
 
-### Step 6: Per-diagram generation loop
+### Step 5: Per-diagram generation loop
 
-For each diagram (single iteration in single mode, N iterations in multi mode):
+For each diagram in the confirmed plan (1 to N, overview diagram generated last):
 
-#### 6a: Capture intent
+#### 5a: Capture intent
 
-**Single mode**: Read the user's prompt. Extract these five things from the source:
+Read the current diagram's plan entry. Extract or refine these five things from the source material:
 
-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").
+1. **Named elements** — list every distinct actor, component, service, state, or phase explicitly named. Count them. If the count is 6+ for simple flowcharts, plan multiple diagrams rather than cramming everything into one (see `flowchart.md` → "Planning before you write SVG"). **Exception**: structural architecture diagrams (microservices, cloud topologies, system designs) routinely need 10–20 named elements in a single diagram — services, databases, gateways, message buses, clients. 10 is the minimum where splitting is unnecessary; enriched diagrams (item 6 below) typically reach ≥12. Do not split an architecture diagram just because the element count is high; instead, see "Architecture enrichment" (item 6 below) and `structural.md` → "Full architecture layout".
 
 2. **Relationship type** — for each interaction between elements, classify it:
    - Sequential steps / order of operations → flowchart signal
    - Containment ("X is inside Y", zones, hierarchies) → structural signal
    - Multi-actor message exchange (A sends to B, B replies to C) → sequence signal
    - Mechanism ("how does X produce Y") → illustrative signal
-   More than one type present? Pick the dominant one, or plan two diagrams.
+   More than one type present? Pick the dominant one, or flag for the plan.
 
 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 6d 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 5d uses real labels.
 
-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.
+5. **Language** — CJK vs. Latin. Affects text-width multipliers in Step 5d (15 px/char vs. 8 px/char for titles). Mixed content (CJK labels with some Latin terms) counts as CJK.
 
-**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.
+6. **Architecture enrichment** — when the type is **structural** and the topic is an architecture or infrastructure diagram ("microservices architecture", "Kubernetes cluster", "cloud topology", "system design"), actively expand the named elements beyond what the user literally wrote. The user's prompt is a **seed**, not a complete spec. A bare "microservices architecture" should produce a diagram with ≥12 named elements, not 5 generic boxes. Apply these enrichment rules:
 
-#### 6b: Route type and load type reference
+   - **Multiple client types**: if the system serves end users, show ≥2 clients (Web app + Mobile app, or Browser + CLI). Each with a tech subtitle (React SPA, iOS/Android).
+   - **Gateway details**: technology name (Kong, Nginx, Envoy), responsibilities (rate limiting, auth/routing), port (:443). Not just "API Gateway".
+   - **Per-service specifics**: each microservice gets a technology and port subtitle (Go :8081, Java :8082, Python :8083, Node.js :8084). The reader should learn the tech stack from the diagram.
+   - **Database per service**: each service connects to its own data store. Show the databases as a separate column or tier (PostgreSQL, MongoDB, Elasticsearch, Redis) with role subtitles (Users DB, Orders DB, Cache/Queue).
+   - **Message bus / event bus**: if services communicate asynchronously, show messaging infrastructure (Kafka, RabbitMQ, Event Bus) as small labeled connector pills between the services that use them.
+   - **Auth service**: when JWT/OAuth is mentioned or implied, separate it from business services as a distinct component with protocol subtitle (OAuth 2.0 / JWT).
+   - **Color categories**: architecture diagrams with ≥3 component types trigger the structural architecture exception (see `design-system.md` rule 9). Assign one ramp per category: services=teal, databases=purple, gateways=coral, message buses=amber. Mandatory legend.
+   - **Summary panel** (optional): a bottom section with 2–3 columns summarizing key architecture principles (Client Applications, Microservices, Infrastructure). Add when the diagram has ≥10 named elements.
+   - **Title + subtitle**: architecture diagrams always get a `.title` at the top with the architecture name and a `.ts` subtitle describing the approach (e.g., "Domain-driven design", "Event-driven microservices").
 
-**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.
+   The enrichment principle: **a reader should learn something specific from the diagram**. "User service / Go :8081" teaches more than "User service / Accounts & profiles". Technology choices, ports, and protocols are the details that make an architecture diagram useful rather than decorative.
 
-**Multi mode**: The type was already determined in the outline. Load the matching reference file now.
+   Skip enrichment for non-architecture structural diagrams (biological containment, CPU caches, file systems) — those benefit from simplicity, not tech details.
+
+#### 5b: Load type reference
+
+The type was determined in the plan. Load the matching reference file.
 
 **Read the one that matches the type**:
 - `references/flowchart.md`
@@ -285,33 +325,33 @@ For each diagram (single iteration in single mode, N iterations in multi mode):
 - `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 6d (topic has a short name, named phases, parallel candidates, a loop termination mechanic, overflow annotations, or a footer quote)
+- `references/flowchart-poster.md` — when ≥3 poster-mode triggers fire in Step 5d (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
 
-#### 6c: Check patterns library
+#### 5c: Check patterns library
 
-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 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 5d.
 
-If nothing matches, skip and plan from scratch in Step 6d. Do not force a near-miss.
+If nothing matches, skip and plan from scratch in Step 5d. Do not force a near-miss.
 
-#### 6d: Plan on paper
+#### 5d: 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.
 
-**6d-0. Draft the Mermaid sketch first** — write a Mermaid code block that captures the **structural intent** of the diagram: which nodes exist, how they connect, what direction they flow, and any grouping (subgraphs). This is the single source of truth for *what* to draw; everything after it (coordinates, widths, arrows) answers *how*.
+**5d-0. Draft the Mermaid sketch first** — write a Mermaid code block that captures the **structural intent** of the diagram: which nodes exist, how they connect, what direction they flow, and any grouping (subgraphs). This is the single source of truth for *what* to draw; everything after it (coordinates, widths, arrows) answers *how*.
 
 Rules for the Mermaid sketch:
 - Use the Mermaid dialect that best matches the diagram type: `flowchart TD/LR` for flowcharts, `sequenceDiagram` for sequence, `classDiagram` for class, `flowchart` with subgraphs for structural/illustrative.
 - Include every node, every edge, every label, and every subgraph/container. If a node won't appear in the Mermaid, it won't appear in the SVG.
 - Edge labels must match the final SVG labels — write them now, not later.
-- Keep it concise: the sketch is a structural contract, not a rendering. Mermaid can't express baoyu's visual design (colors, rounded rects, dark mode), so don't try — those come in 6d-ii and 6e.
+- Keep it concise: the sketch is a structural contract, not a rendering. Mermaid can't express baoyu's visual design (colors, rounded rects, dark mode), so don't try — those come in 5d-ii and 5e.
 - For patterns that have a Mermaid reference in `references/patterns/`, start from that reference and adapt it to the specific topic.
 
-Save the Mermaid block in the plan file. When writing SVG in Step 6e, **cross-check every node and edge against this Mermaid sketch** — if the sketch has it, the SVG must have it; if the SVG adds something the sketch doesn't have, update the sketch first.
+Save the Mermaid block in the plan file. When writing SVG in Step 5e, **cross-check every node and edge against this Mermaid sketch** — if the sketch has it, the SVG must have it; if the SVG adds something the sketch doesn't have, update the sketch first.
 
-**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:
+**5d-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? That's a candidate subtitle.
@@ -325,7 +365,7 @@ Save the Mermaid block in the plan file. When writing SVG in Step 6e, **cross-ch
 
 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.
 
-**6d-ii. Draft the layout:**
+**5d-ii. Draft the layout:**
 
 1. **List the nodes / regions / shapes** with their full label text (title + optional subtitle).
    - Simple flowchart: ≤5 nodes.
@@ -344,13 +384,13 @@ 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 (including the Mermaid sketch from 6d-0):
-- **Single mode**: `diagram/{slug}/plan.md`
-- **Multi mode**: `diagram/{article-slug}/NN-{type}-{slug}/plan.md`
+Save this plan (including the Mermaid sketch from 5d-0):
+- One diagram: `diagram/{slug}/plan.md`
+- Multiple diagrams: `diagram/{material-slug}/NN-{type}-{slug}/plan.md`
 
-#### 6e: Write the SVG
+#### 5e: Write the SVG
 
-**Start from the Mermaid sketch in the plan.** Walk the sketch node-by-node, edge-by-edge, and translate each element into SVG using the coordinates and widths computed in 6d-ii. The Mermaid sketch is the structural checklist — every node and edge in it must appear in the SVG. If you find yourself adding an element that isn't in the sketch, stop and update the sketch first so the plan stays authoritative.
+**Start from the Mermaid sketch in the plan.** Walk the sketch node-by-node, edge-by-edge, and translate each element into SVG using the coordinates and widths computed in 5d-ii. The Mermaid sketch is the structural checklist — every node and edge in it must appear in the SVG. If you find yourself adding an element that isn't in the sketch, stop and update the sketch first so the plan stays authoritative.
 
 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:
 
@@ -366,7 +406,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
 
-#### 6f: Run the pre-save checklist
+#### 5f: Run the pre-save checklist
 
 **Mermaid–SVG consistency check** (run before the pitfalls checklist): re-read the Mermaid sketch from the plan. For every node in the sketch, confirm the SVG has a corresponding `<rect>` + `<text>`. For every edge, confirm a `<path>` or `<line>` connects the correct pair. Missing elements are bugs — fix them before continuing.
 
@@ -384,25 +424,19 @@ 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.
 
-#### 6g: Save and report progress
+#### 5g: Save and report progress
 
 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`
+- One diagram: `diagram/{slug}/plan.md` + `diagram.svg`
+- Multiple diagrams: `diagram/{material-slug}/NN-{type}-{slug}/plan.md` + `diagram.svg`
 
 **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.
 
-**Multi mode progress**: after each diagram, report progress: "Generated 2/4: 02-illustrative-jwt-token-structure".
+**Multiple diagrams progress**: after each diagram, report progress: "Generated 2/4: 02-illustrative-jwt-token-structure".
 
-### Step 7: Finalize (multi-diagram mode)
+### Step 6: Report
 
-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
-
-**Single mode** — tell the user in 4-6 lines:
+**One diagram** — tell the user in 4-6 lines:
 - Diagram type picked (and one-sentence why)
 - Node count / complexity
 - viewBox dimensions
@@ -410,49 +444,52 @@ If input was pasted content, skip insertion — the diagrams are generated and t
 - Output file path
 - One suggestion for how to preview it (e.g., "Open in Chrome for light/dark check")
 
-**Multi mode**:
+**Multiple diagrams**:
 
 ```
-Article Diagram Generation Complete!
+Diagram Generation Complete!
 
-Article: [path or "pasted content"]
-Density: [level] | Language: [lang]
-Diagrams: X/N generated
+Material: [source description]
+Language: [lang]
+Diagrams: X 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..."
+Results:
+- 01-sequence-jwt-auth-flow — "Reader understands the auth handshake"
+- 02-illustrative-jwt-token-structure — "Reader understands token anatomy"
+- 03-flowchart-token-refresh — "Reader understands the refresh cycle"
+[- overview-structural-jwt-system — "Reader sees how all parts connect"]
 
-Output: diagram/{article-slug}/
+Output: diagram/{material-slug}/
 Preview: Open any .svg in Chrome for light/dark check
 ```
 
 ## Output structure
 
-### Single-diagram mode
+### One diagram
 
 ```
-diagram/{topic-slug}/
-├── source-{slug}.md          # optional: user's input content if provided
-├── plan.md                   # layout sketch from Step 6d
+diagram/{slug}/
+├── source-{slug}.md          # optional: saved input material
+├── plan.md                   # layout sketch from Step 5d
 └── diagram.svg               # final output
 ```
 
-### Multi-diagram mode
+### Multiple diagrams
 
 ```
-diagram/{article-slug}/
-├── source-{slug}.md          # saved input content (file copy or pasted content)
-├── outline.md                # frontmatter + all diagram entries from Step 4
+diagram/{material-slug}/
+├── source-{slug}.md          # saved input material
+├── outline.md                # plan from Step 2 with all diagram entries
 ├── 01-{type}-{slug}/
 │   ├── plan.md               # layout sketch for this diagram
 │   └── diagram.svg           # final SVG
 ├── 02-{type}-{slug}/
 │   ├── plan.md
 │   └── diagram.svg
-└── 03-{type}-{slug}/
+├── 03-{type}-{slug}/
+│   ├── plan.md
+│   └── diagram.svg
+└── overview-{type}-{slug}/   # optional: overview diagram
     ├── plan.md
     └── diagram.svg
 ```
@@ -461,22 +498,22 @@ diagram/{article-slug}/
 - **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.
+- **Numbering**: NN prefix (01, 02, ...) matches the plan order.
+- **Outline**: when generating multiple diagrams, always save `outline.md` from Step 2 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 |
+| **Regenerate one diagram** | Re-read `outline.md` → find the entry → re-run Step 5 for that diagram only → update the SVG |
+| **Add a diagram** | Identify focus area → add entry to `outline.md` → run Step 5 for the new entry |
+| **Remove a diagram** | Delete the `NN-{type}-{slug}/` directory → remove entry from `outline.md` |
+| **Change type** | Update the plan 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. In multi-diagram mode, all diagrams in a run share the same design system — no per-diagram style overrides.
+- **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. 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.

skills/baoyu-diagram/references/design-system.md

@@ -87,6 +87,7 @@ The template's `@media (prefers-color-scheme: dark)` block handles this automati
 6. **Exception — sequence diagrams may use one ramp per actor, up to 4 ramps total.** Each actor's header, lifeline context, and the arrows *originating* from that actor share a single ramp. Actor identity is a category (not a sequence), so this obeys the "encode meaning" rule — it just allows more categories than the normal ≤2-ramp cap. The legend is implicit: every ramp is anchored by its labeled actor header at the top of the diagram. See `sequence.md`.
 7. **Exception — poster flowcharts may use up to 4 ramps, one per distinct agent/role.** Same principle as the sequence exception: the drafter, the critic, the synthesizer, and the judge are four different *kinds* of operation, not four sequential steps. Each ramp anchors identity. The stage's title box makes the legend implicit. See `flowchart-poster.md`.
 8. **Exception — phase-band diagrams may use up to 3 ramp-colored arrow classes** when each ramp encodes a distinct *path type* (e.g., normal flow vs. exploit path vs. data exfiltration). The path type is the information the arrow carries — the ramp makes it visible at a glance rather than relying on labels on every crossing arrow. **A legend strip is mandatory.** See `flowchart-phase-bands.md`.
+9. **Exception — structural architecture diagrams may use up to 4 ramps, one per component category.** When a structural diagram depicts an infrastructure or software architecture with ≥3 semantically distinct categories of components (e.g., services, databases, gateways, message buses), assign one ramp per category — up to 4 ramps total. The categories are determined by the component's *role* in the system, not its position. A **legend strip is mandatory** (same rule as phase-band diagrams). Typical category→ramp mappings for infrastructure: services=teal, databases=purple, gateways/ingress=coral, message buses/queues=amber. But any 4 ramps work as long as each ramp encodes a distinct component type, not a sequential position. See `structural.md` → "Full architecture layout".
 
 ### If colors or arrow styles encode meaning, add a one-line legend
 

skills/baoyu-diagram/references/layout-math.md

@@ -59,6 +59,33 @@ For CJK content, replace the 8 with 15 and the 7 with 13.
 
 **Round up to the nearest 10px** for cleaner coordinates. A box that "needs" 167px becomes 170px.
 
+### Common spacing failures — Wrong / Right
+
+Three mistakes that produce valid SVG but visually broken diagrams. Use these as a quick sanity check.
+
+**Vertical gap too small (nodes overlap):**
+
+```
+Wrong: Node A ends at y=176, Node B starts at y=180 → 4px gap, labels nearly touching
+Right: Node A ends at y=176, Node B starts at y=236 → 60px gap (the minimum vertical gap)
+```
+
+**Legend inside container boundary:**
+
+```
+Wrong: Container bottom at y=380, legend at y=370 → legend reads as container content
+Right: Container bottom at y=380, legend at y=400 → 20px clear air, legend is diagram metadata
+       (extend viewBox H to 436 to fit)
+```
+
+**Horizontal tier overflow:**
+
+```
+Wrong: 4 boxes × 180 + 3 gaps × 20 = 780 → overflows the 600px usable width by 180px
+Right: 4 boxes × 130 + 3 gaps × 20 = 580 → fits within 600px, centered at x=50
+       (shorten labels or drop subtitles to fit the narrower boxes)
+```
+
 ### Worked examples
 
 - `"JWT authentication"` (18 chars, title) → `18 × 8 + 24 = 168` → round to **170**

skills/baoyu-diagram/references/pitfalls.md

@@ -268,6 +268,40 @@ Pick `ymid` so the horizontal channel runs through empty space between rows.
 
 **Fix**: replace every hardcoded color on a glyph element with the corresponding class. If you need a color that isn't in the 9-ramp palette, you don't need a new color — you're asking the glyph to say something it shouldn't. See `glyphs.md` → "Hard rules" for the full policy.
 
+## 29. Arrow bleeds through semi-transparent fill
+
+**Symptom**: a connector line that passes behind a node is faintly visible *through* the node's fill — especially noticeable on illustrative diagrams with gradient overlays or on nodes where the fill color is very light.
+
+**Check**: does any node use a translucent or very light fill (stop 50 from a ramp) through which a 1.5px stroke behind it would show? The default `c-{ramp}` fills are opaque enough that this rarely matters, but when a plan calls for a translucent overlay (gradient, or a manually lightened fill), the bleed becomes visible.
+
+**Fix**: draw an opaque background rect at the same position *before* the styled rect. The background rect masks the arrow; the styled rect paints on top with the desired appearance:
+
+```svg
+<!-- Opaque mask to hide arrow behind this node -->
+<rect x="200" y="100" width="180" height="56" rx="6" class="box"/>
+<!-- Styled node on top -->
+<g class="c-purple">
+  <rect x="200" y="100" width="180" height="56" rx="6"/>
+  <text class="th" x="290" y="124" text-anchor="middle" dominant-baseline="central">Title</text>
+</g>
+```
+
+The `box` class works as the mask because it uses opaque fill in both light and dark mode. Only add the mask rect when bleed-through is visible — most diagrams don't need it because the z-order rule (connectors drawn before nodes) already handles opaque fills.
+
+## 30. Legend clips into a container boundary
+
+**Symptom**: a legend strip sits inside (or overlaps) a dashed container's bottom edge — the legend text reads as part of the container's content instead of as diagram-level metadata.
+
+**Check**: find the lowest container boundary: `container_y + container_h`. The legend's top edge must be ≥20px below that boundary. If the legend sits inside or touching any container, it's a bug.
+
+**Fix**: move the legend below all container boundaries. Calculate: `legend_y = max(all_container_bottoms) + 20`. Then extend viewBox H to accommodate: `H = legend_y + legend_h + 20`. Never squeeze a legend inside a container to save vertical space — expand the viewBox instead.
+
+```
+Container bottom at y=380
+Legend at y=400 → 20px clear ✓
+viewBox H = 400 + 16 + 20 = 436
+```
+
 ---
 
 ## Quick self-review template
@@ -283,5 +317,7 @@ Before writing the file, mentally run through:
 > 7. Colors: ≤ 2 ramps → ___ and ___ → assigned by category  ✓
 > 8. No hardcoded text fills  ✓
 > 9. No comments in final output  ✓
+> 10. No arrow bleed-through on translucent fills (mask rect if needed)  ✓
+> 11. Legend sits ≥20px below all container boundaries  ✓
 
 If any of these feel fuzzy, the diagram isn't ready.

skills/baoyu-diagram/references/structural-network.md

@@ -4,6 +4,21 @@ Load this file when the prompt asks about **network infrastructure**: "where do
 
 Sub-pattern for diagrams whose subject is **where the wires go** — which devices sit where, which security zones contain them, which links are wired vs wireless. The structural diagram type is the right home for this (devices are containers, zones are outer containers, cables are arrows), but topology drawings have some conventions of their own.
 
+## Domain color conventions
+
+When a structural or network diagram has 3+ component categories, these conventional ramp assignments help the reader parse component types at a glance. These are **suggestions**, not hard rules — the ≤2 ramp constraint from `design-system.md` still applies for simple diagrams with only 1–2 categories.
+
+| Component domain   | Suggested ramp | Rationale                                    |
+|--------------------|---------------|----------------------------------------------|
+| Frontend / Client  | teal          | cool, user-facing                            |
+| Backend / API      | green         | processing, data transformation              |
+| Database / Storage | purple        | depth, persistence                           |
+| Cloud / Infra      | amber         | external boundary, warning-adjacent           |
+| Security / Auth    | coral         | attention, trust boundary                     |
+| External / Generic | gray          | neutral, not categorized                      |
+
+When a diagram uses ≥3 of these, include a one-line legend strip at the bottom mapping colors to categories. When the diagram is simple enough to stay within 2 ramps, prefer the semantic pairing from `design-system.md` over these domain conventions.
+
 ## When to use it
 
 - The reader's question is *"what is connected to what, and across which boundary"*, not *"what happens when a request arrives"* (that's a sequence diagram).
@@ -63,6 +78,23 @@ Two distinct link styles, both already in the template:
 
 Place the legend at the bottom of the canvas, 20px above the bottom edge, aligned with the subject matter above it.
 
+## Security zone containers
+
+When a network diagram includes explicit trust boundaries (security groups, VPNs, firewalls-as-perimeters), use a **coral-tinted dashed container** to distinguish security zones from structural zones. This gives the reader an immediate visual signal: gray dashed = organizational grouping, coral dashed = trust boundary.
+
+```svg
+<rect x="60" y="100" width="560" height="160" rx="12" fill="none"
+      stroke-dasharray="4 4" class="arr-coral"/>
+<rect class="c-coral" x="60" y="92" width="120" height="16" rx="8"/>
+<text class="ts" x="120" y="104" text-anchor="middle">Trust boundary</text>
+```
+
+The coral container uses `class="arr-coral"` instead of `class="arr-alt"` — both are dashed, but `arr-coral` carries the semantic color. The pill label uses `class="c-coral"` for matching fill/stroke.
+
+Typical security zone labels: *Security group*, *Trust boundary*, *VPN tunnel*, *Private subnet*, *Encrypted zone*, *DMZ* (when DMZ is drawn as a security boundary rather than an organizational tier).
+
+When mixing structural zones (gray) and security zones (coral) in the same diagram, add a legend entry for the coral dash: `[- -] Trust boundary` alongside the structural zone entries.
+
 ## Tiered top-down layout
 
 Network topology almost always reads top-down because the conventional mental model is *"traffic flows from the public internet down into the protected core"*. Lay out the zones vertically, one tier per row:

skills/baoyu-diagram/references/structural.md

@@ -137,6 +137,174 @@ Layout:
 
 viewBox: max_y = 40 + 280 = 320 → H = 340
 
+## Full architecture layout
+
+A richer variant for topics like "microservices architecture", "Kubernetes cluster", "cloud topology", or any system design where the reader expects to see **technology choices, data stores, messaging, and client types** — not just generic labeled boxes. This is the most information-dense structural layout in the skill, routinely containing 12–20 named elements and using up to 4 color ramps (see `design-system.md` rule 9).
+
+### When to use
+
+- "Microservices architecture" / "system architecture" / "platform design"
+- Any structural prompt where the user's seed is a broad system name and the reader expects specific technologies
+- The reader needs to learn **what** is in the system (tech stack, ports, protocols), not just **how it's organized**
+
+### When not to use
+
+- Simple containment (VPC with two subnets) — use the basic structural pattern above
+- Two subsystems cooperating — use the subsystem architecture pattern below
+- The user provided detailed source material that already lists every component — follow the source instead of enriching
+
+### Layout structure
+
+The canonical full architecture layout has **5 horizontal tiers** inside an outer container, plus external clients and an optional summary panel below:
+
+```
+Tier 0 (external):  Client boxes — outside the container, top-left
+Tier 1:             API Gateway / Ingress — wide box spanning the top
+Tier 2:             Microservices row — 3–4 service boxes
+Tier 2.5:           Message bus pills — small labeled connectors between services
+Tier 3:             Data stores row — database boxes aligned under their owning services
+Tier 4 (optional):  Shared infrastructure — service discovery, config, monitoring
+```
+
+An auth service sits outside or beside the gateway when it's a cross-cutting concern.
+
+### Color budget (4 ramps)
+
+| Category        | Ramp    | Used on                                              |
+|-----------------|---------|------------------------------------------------------|
+| Services        | teal    | Microservice boxes, auth service                     |
+| Databases       | purple  | PostgreSQL, MongoDB, Elasticsearch, Redis            |
+| Gateway/Ingress | coral   | API Gateway box                                      |
+| Message bus     | amber   | Kafka, RabbitMQ, Event Bus connector pills           |
+| Clients         | gray    | Web app, Mobile app (neutral — not part of the system)|
+| Infrastructure  | gray    | Service discovery, config & secrets (neutral)        |
+
+A **legend strip** is mandatory — place it inside the container at the bottom or just below it.
+
+### Geometry
+
+Starting-point coordinates for a typical 3-service architecture. **Recompute** per diagram using `layout-math.md` formulas — the values below assume 3 services, 3 databases, and standard 56px-tall boxes. Adding a 4th service column or extra tiers requires recalculating x/w/gap to fit within the 600px usable width.
+
+Standard layout at viewBox `680 × H`:
+
+```
+Element                    x      y      w      h    rx
+────────────────────────  ────   ────   ────   ───  ────
+Outer container            40     80     600    var  20     c-blue (or c-gray)
+Title                      60     50     —      —    —     .title
+Subtitle                   60     72     —      —    —     .ts
+
+Client boxes (external)
+  Web App                  40     20     140    56   6     c-gray
+  Mobile App               40     var    140    56   6     c-gray
+
+API Gateway                200    120    280    80   6     c-coral
+  (title + 2–3 subtitle lines: tech, responsibilities, port)
+
+Auth Service               40     var    140    56   6     c-teal
+  (sits left of gateway or below clients)
+
+Services row (inside container)
+  Service 1                100    250    140    56   6     c-teal
+  Service 2                270    250    140    56   6     c-teal
+  Service 3                440    250    140    56   6     c-teal
+  (or 4 services: w=120, gap=16)
+
+Message bus pills
+  (small 90×24 rx=12 amber pills between services, y≈320)
+
+Data stores row
+  DB 1                     100    370    140    56   6     c-purple
+  DB 2                     270    370    140    56   6     c-purple
+  DB 3                     440    370    140    56   6     c-purple
+
+Shared infrastructure (optional)
+  Service discovery        140    460    160    44   6     c-gray
+  Config & secrets         380    460    160    44   6     c-gray
+
+Legend strip               100    var    —      —    —     .ts + swatches
+```
+
+Adjust y coordinates to maintain ≥40px vertical gaps between tiers. viewBox H is typically 560–700 depending on tier count.
+
+### Label enrichment
+
+Every box in a full architecture diagram carries **technology-specific subtitles**:
+
+| Component       | Title (th)         | Subtitle (ts)           |
+|-----------------|--------------------|-------------------------|
+| Client          | Web App            | React SPA               |
+| Client          | Mobile App         | iOS/Android             |
+| Gateway         | API Gateway        | Kong / Nginx            |
+|                 |                    | Rate limiting           |
+|                 |                    | :443                    |
+| Auth            | Auth Service       | OAuth 2.0 / JWT         |
+| Service         | User Service       | Go :8081                |
+| Service         | Order Service      | Java :8082              |
+| Message bus     | Kafka / RabbitMQ   | (pill label only)       |
+| Database        | PostgreSQL         | Users DB                |
+| Database        | MongoDB            | Orders DB               |
+| Database        | Redis              | Cache / Queue           |
+| Infrastructure  | Service discovery  | (single-line)           |
+
+The gateway box is taller (h=80) to hold 3 subtitle lines. Service and database boxes use standard 2-line layout (h=56). Message bus elements are small pills (h=24).
+
+### Message bus connector pills
+
+Small rounded-rect pills sitting on the arrows between services, styled with `c-amber`:
+
+```svg
+<g class="c-amber">
+  <rect x="225" y="316" width="90" height="24" rx="12"/>
+  <text class="ts" x="270" y="328" text-anchor="middle" dominant-baseline="central">Event Bus</text>
+</g>
+```
+
+Place pills at the midpoint of the arrow between two services. The arrow is split into two segments with the pill in between.
+
+### Summary panel (optional)
+
+For diagrams with ≥10 elements, add a summary panel below the outer container. Three columns of bullet points summarizing key architecture principles:
+
+```
+┌─────────────────┬─────────────────┬──────────────────┐
+│ • Client Apps   │ • Microservices │ • Infrastructure │
+│   - React SPA   │   - Polyglot    │   - Kubernetes   │
+│   - iOS/Android │   - Independent │   - Kong Gateway │
+│   - Unified API │   - Event-driven│   - Kafka        │
+│   - JWT auth    │   - DB per svc  │   - Prometheus   │
+└─────────────────┴─────────────────┴──────────────────┘
+```
+
+Each column is a `c-gray` box with a colored bullet (matching its category ramp) as the header indicator. Place at y = container_bottom + 40, spanning the full 600px usable width as three equal boxes (w=186, gap=21, total=186×3+21×2=600).
+
+### Footer caption
+
+Add a `.caption` footer below the summary panel: the architecture name + design philosophy in one line (e.g., "Microservices Architecture · Domain-driven design"). Centered at x=340, y = panel_bottom + 30.
+
+### Worked example — Microservices + K8s + API Gateway
+
+Plan (expanded from a seed prompt "Microservices architecture"):
+
+```
+Clients:           Web App (React SPA), Mobile App (iOS/Android)
+Gateway:           API Gateway (Kong/Nginx, Rate Limiting, Auth/Routing, :443)
+Auth:              Auth Service (OAuth 2.0 / JWT)
+Services:          User Service (Go :8081), Order Service (Java :8082),
+                   Product Service (Python :8083), Notification Svc (Node.js :8084)
+Message bus:       Kafka/RabbitMQ, Event Bus (×2)
+Data stores:       PostgreSQL (Users DB), MongoDB (Orders DB),
+                   Elasticsearch (Products), Redis (Cache/Queue)
+Container:         Kubernetes Cluster (dashed border)
+Legend:            Service, Database, Gateway, Message Bus
+Summary:           3 columns (Client Applications, Microservices, Infrastructure)
+Footer:            "Microservices Architecture · Domain-driven design"
+Color budget:      teal (services), purple (databases), coral (gateway), amber (bus)
+Named elements:    18
+```
+
+viewBox: `680 × 780`. The diagram is tall — that's expected for a full architecture layout.
+
 ## Subsystem architecture pattern
 
 A variant for topics that have **two or three parallel subsystems cooperating** — the canonical shape is "two sibling dashed-border containers, each holding a short internal flow, with a labeled cross-system arrow linking them". Unlike the default structural diagram (outer container + inner regions), this pattern places the subsystems *side by side at the top level* and lets each one carry its own mini-flowchart.

skills/baoyu-diagram/references/svg-template.md

@@ -206,11 +206,50 @@ Or directly to the shape itself if there's no wrapping `<g>`:
 
 **Do not nest `c-*` groups.** The CSS uses direct-child selectors — `<g class="c-blue"><g>...</g></g>` won't apply the fill to the inner shapes. If you need a click handler (future), put it on the same group that carries the color class, not a wrapper.
 
+## Optional background grid
+
+For structural diagrams with a technical/blueprint feel, an optional background grid can reinforce the engineering aesthetic. **This is rare** — most diagrams should keep the transparent background for seamless embedding. Only consider the grid when the diagram shows infrastructure, network topology, or hardware architecture where the grid reads as "engineering paper" rather than decoration.
+
+Add the pattern to `<defs>` and a full-viewport rect as the first visual element:
+
+```svg
+<defs>
+  <!-- arrow marker (always present) -->
+  <marker id="arrow" .../>
+  <!-- grid pattern (optional, structural diagrams only) -->
+  <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
+    <path d="M 40 0 L 0 0 0 40" fill="none" stroke="var(--grid-stroke, rgba(0,0,0,0.06))" stroke-width="0.5"/>
+  </pattern>
+</defs>
+
+<!-- Grid background (first visual element, behind everything) -->
+<rect width="680" height="H" fill="url(#grid)"/>
+```
+
+Define the CSS variable in both modes so the value is explicit and discoverable (not buried in an inline fallback). Add these inside the existing `<style>` block:
+
+```css
+svg { --grid-stroke: rgba(0,0,0,0.06); }
+
+@media (prefers-color-scheme: dark) {
+  svg { --grid-stroke: rgba(255,255,255,0.05); }
+  /* ... existing dark-mode overrides ... */
+}
+```
+
+With the explicit light-mode declaration, the inline fallback in the `<pattern>` stroke is redundant but harmless — keep it as a safety net for renderers that strip `<style>` blocks.
+
+**Rules:**
+- Grid stroke opacity must stay ≤0.08 in both modes — the grid is a texture, not a visual element
+- The grid rect is always the first child after `</defs>`, so every other element paints on top
+- Never use the grid on illustrative, sequence, or class diagrams — it fights with their visual language
+- If the grid competes with the diagram's lines for visual attention, remove it
+
 ## What to emit after the template
 
 Visual elements in this order:
 
-1. Background decorations (dashed frame for a schematic container, for example)
+1. Background decorations (optional grid rect, dashed frame for a schematic container)
 2. Containers (outer group rectangles for structural diagrams)
 3. Connectors and arrows (so they sit behind the boxes they connect, preventing visible overlap) — both solid `.arr`/`.arr-{ramp}` primary flows and `.arr-alt` alternative/optional/weak flows belong in this layer
 4. Nodes (rects with text)