Figure surfaces (Mermaid/SVG/Markdown) in the skill and examples; bundled grill-with-docs

README.ZH.md

@@ -13,11 +13,27 @@
 
 引擎能画的所有控件——滑块、带刻度的范围滑块、分段控件、单选组、开关、
 自定义取色器、条件字段——全部由 schema 提示驱动，skill 也会明确要求 agent 主动
-用起来。完整清单见
-[`schemaui` 控件画廊](https://github.com/YuniqueUnic/schemaui/blob/main/examples/controls-gallery.schema.json)；
+用起来。图形走同一套提示：问题和选项都可以带 **Mermaid 图、内联 SVG 或 Markdown
+说明**（`x-content` / `x-options`），答案本身也可以是一张可编辑的
+实时预览图（`x-control: "mermaid"`）。完整清单见
+[`schemaui` 控件画廊](https://github.com/YuniqueUnic/schemaui/blob/main/examples/controls-gallery.schema.json)
+与
+[富内容画廊](https://github.com/YuniqueUnic/schemaui/blob/main/examples/rich-content.schema.json)；
 [`examples/web-research-brief.schema.json`](./examples/web-research-brief.schema.json)
 是把这些控件全部用上的一份中文范例。
 
+<table>
+  <tr>
+    <td><img src="./docs/controls-gallery.png" alt="控件画廊：滑块、范围、分段、单选、取色器等全部控件" /></td>
+  </tr>
+  <tr>
+    <td><img src="./docs/rich-options.png" alt="选项配图：每个部署拓扑选项自带一张 Mermaid 图" /></td>
+  </tr>
+  <tr>
+    <td><img src="./docs/mermaid-editor.png" alt="Mermaid 编辑器：左侧源码、右侧实时预览" /></td>
+  </tr>
+</table>
+
 ## 为什么需要它
 
 Agent 的工具调用跑在**没有 TTY** 的子进程里——终端提示符根本渲染不出 来，agent
@@ -130,20 +146,28 @@ Windows / PowerShell 7+:`pwsh scripts/ask.ps1 -Schema … -Title …`。没有 P
 - **给每个答案配对的控件** —— 滑块、带刻度的滑块、双柄范围、取色器、分段控件、
   单选组、复选框、条件字段，外加文本、数值、单选/多选、oneOf 组合、嵌套对
   象、记录列表、键值映射。
+- **能看图就别读字** —— 选项差在「形状」上时（拓扑、发布策略、数据模型）， agent
+  给每个选项配一张图，你认图选择;节点级 `x-content` 用图或一段富文本
+  解释字段背景;`mermaid` 控件让答案本身就是一张可编辑、实时预览的图。
+- **访谈纪律内置** —— 开放式设计需要深度访谈时，skill 优先使用你已安装的
+  grilling 类 skill，都没有时回退到内置的
+  [`skills/grill-with-docs`](./skills/grill-with-docs/SKILL.md)：一次一问、
+  每问带推荐答案、每个问题都以项目文档为依据。
 
 ## 示例
 
 [`examples/`](./examples/) 里可直接运行的表单 (每个都带 `.defaults.json`
 推荐答案):
 
-| 示例                                                                                | 场景                                                |
-| ----------------------------------------------------------------------------------- | --------------------------------------------------- |
-| [`env-schema.json`](./examples/env-schema.json)                                     | 最小 4 字段部署表单 —— 首次冒烟测试                 |
-| [`web-research-brief.schema.json`](./examples/web-research-brief.schema.json)       | 调研：联网调研任务确认 —— 用上画廊全部控件 (中文)   |
-| [`feature-brief.schema.json`](./examples/feature-brief.schema.json)                 | 12 问需求简报，覆盖全部控件类型 (英文)              |
-| [`invoice-reimbursement.schema.json`](./examples/invoice-reimbursement.schema.json) | 办公：发票报销处理 (中文，每个选择带「其他」逃生口) |
-| [`ecommerce-main-image.schema.json`](./examples/ecommerce-main-image.schema.json)   | 设计：电商主图 —— 尺寸、字号、颜色、渐变背景 (中文) |
-| [`seo-diagnosis.schema.json`](./examples/seo-diagnosis.schema.json)                 | SEO 排查：站点、问题、关键词、竞品 (中文)           |
+| 示例                                                                                    | 场景                                                |
+| --------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| [`env-schema.json`](./examples/env-schema.json)                                         | 最小 4 字段部署表单 —— 首次冒烟测试                 |
+| [`web-research-brief.schema.json`](./examples/web-research-brief.schema.json)           | 调研：联网调研任务确认 —— 用上画廊全部控件 (中文)   |
+| [`feature-brief.schema.json`](./examples/feature-brief.schema.json)                     | 12 问需求简报，覆盖全部控件类型 (英文)              |
+| [`invoice-reimbursement.schema.json`](./examples/invoice-reimbursement.schema.json)     | 办公：发票报销处理 (中文，每个选择带「其他」逃生口) |
+| [`ecommerce-main-image.schema.json`](./examples/ecommerce-main-image.schema.json)       | 设计：电商主图 —— 尺寸、字号、颜色、渐变背景 (中文) |
+| [`seo-diagnosis.schema.json`](./examples/seo-diagnosis.schema.json)                     | SEO 排查：站点、问题、关键词、竞品 (中文)           |
+| [`deployment-architecture.schema.json`](./examples/deployment-architecture.schema.json) | 架构选型：每个选项自带一张图 (中文，图形界面参考例) |
 
 ## 脚本契约
 

README.md

@@ -16,11 +16,28 @@ you and the agent can re-read later.
 Every control the engine can draw — sliders, range sliders with marks, segmented
 controls, radio groups, switches, a custom color picker, conditional fields —
 driven entirely by schema hints, and the skill tells the agent to reach for
-them. The full set lives in
-[`schemaui`'s controls gallery](https://github.com/YuniqueUnic/schemaui/blob/main/examples/controls-gallery.schema.json);
+them. Figures ride the same hints: a question or an option can carry a **Mermaid
+diagram, an inline SVG, or sanitised Markdown** (`x-content` / `x-options`), and
+an answer can _be_ a diagram via the live-preview `x-control: "mermaid"` editor.
+The full set lives in
+[`schemaui`'s controls gallery](https://github.com/YuniqueUnic/schemaui/blob/main/examples/controls-gallery.schema.json)
+and
+[rich-content gallery](https://github.com/YuniqueUnic/schemaui/blob/main/examples/rich-content.schema.json);
 [`examples/web-research-brief.schema.json`](./examples/web-research-brief.schema.json)
 is the worked example that uses every one of them (中文).
 
+<table>
+  <tr>
+    <td><img src="./docs/controls-gallery.png" alt="The control gallery: sliders, ranges, segmented, radio, color picker and more" /></td>
+  </tr>
+  <tr>
+    <td><img src="./docs/rich-options.png" alt="Figure-bearing options: each deployment topology option ships its own Mermaid diagram" /></td>
+  </tr>
+  <tr>
+    <td><img src="./docs/mermaid-editor.png" alt="The mermaid editor: source on the left, live preview on the right" /></td>
+  </tr>
+</table>
+
 ## Why
 
 Agent tool calls run in subprocesses with **no TTY** — a terminal prompt renders
@@ -138,20 +155,31 @@ without Python: `bash scripts/ask.sh --schema …`.
   ranges, colour pickers, segmented controls, radio groups, checkboxes, and
   conditional fields, alongside text, number, single/multi select, oneOf
   compositions, nested objects, record lists, and key/value maps.
+- **Show, don't tell** — when options differ in _shape_ (topologies, rollout
+  strategies, data models), the agent attaches a diagram to each option and lets
+  you pick by recognising the picture; node-level `x-content` explains a field
+  with a figure or prose; a `mermaid` control makes the answer itself an
+  editable, live-previewed diagram.
+- **Interview discipline built in** — for open-ended designs, the skill defers
+  to whatever grilling skill you already have, and falls back to the bundled
+  [`skills/grill-with-docs`](./skills/grill-with-docs/SKILL.md): one question at
+  a time, every question with a recommended answer, every question grounded in
+  the project's docs.
 
 ## Examples
 
 Runnable forms in [`examples/`](./examples/) (each with recommended answers in
 the matching `.defaults.json`):
 
-| Example                                                                             | Scenario                                                                  |
-| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| [`env-schema.json`](./examples/env-schema.json)                                     | minimal 4-field deploy form — first smoke test                            |
-| [`web-research-brief.schema.json`](./examples/web-research-brief.schema.json)       | research: scope a web-research task — every control in the gallery (中文) |
-| [`feature-brief.schema.json`](./examples/feature-brief.schema.json)                 | 12-question requirements brief using every control type (EN)              |
-| [`invoice-reimbursement.schema.json`](./examples/invoice-reimbursement.schema.json) | office: invoice & expense reimbursement (中文)                            |
-| [`ecommerce-main-image.schema.json`](./examples/ecommerce-main-image.schema.json)   | design: e-commerce hero images — sizes, fonts, colors, backgrounds (中文) |
-| [`seo-diagnosis.schema.json`](./examples/seo-diagnosis.schema.json)                 | SEO triage: site, issues, keywords, competitors (中文)                    |
+| Example                                                                                 | Scenario                                                                           |
+| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| [`env-schema.json`](./examples/env-schema.json)                                         | minimal 4-field deploy form — first smoke test                                     |
+| [`web-research-brief.schema.json`](./examples/web-research-brief.schema.json)           | research: scope a web-research task — every control in the gallery (中文)          |
+| [`feature-brief.schema.json`](./examples/feature-brief.schema.json)                     | 12-question requirements brief using every control type (EN)                       |
+| [`invoice-reimbursement.schema.json`](./examples/invoice-reimbursement.schema.json)     | office: invoice & expense reimbursement (中文)                                     |
+| [`ecommerce-main-image.schema.json`](./examples/ecommerce-main-image.schema.json)       | design: e-commerce hero images — sizes, fonts, colors, backgrounds (中文)          |
+| [`seo-diagnosis.schema.json`](./examples/seo-diagnosis.schema.json)                     | SEO triage: site, issues, keywords, competitors (中文)                             |
+| [`deployment-architecture.schema.json`](./examples/deployment-architecture.schema.json) | architecture choice: every option carries a diagram (中文 — the figures reference) |
 
 ## Script contract