hd-garden 0.13.3 → 0.14.2

package/docs/handbook/en/reference.md

@@ -1,29 +1,13 @@
 ---
 title: Component reference
-navTitle: Overview
-description: Fields, defaults, limits, and error codes for the garden fences.
+navTitle: Component reference
+description: Component reference
 section: reference
 order: 0
 ---
 
-Each page shows the code on the left and the real rendered result on the right; on narrow screens, switch with Preview / Code. For when to use a component, see its usage page.
+Use one `garden compose` fence for article layouts, rich content, semantic scenes and interactive explanations. Select components inside that entry; use ordinary Markdown when it already communicates the idea.
 
-Link cards, source chips, and local images have no field pages. Their usage pages are linked from [Components Overview](/garden/en/components).
-
-For every component: invalid YAML, or a top-level key the component does not support, reports `garden-yaml` on the whole block; a misspelled fence name reports `garden-name`.
-
-| Component | Use it for |
-| :--- | :--- |
-| [`card`](/garden/en/reference/card) | Summarize a paper, repository, or module in a card with metadata and numbered takeaways. |
-| [`stat`](/garden/en/reference/stat) | Display 2 to 4 key numbers, units, and short captions side by side. |
-| [`compare`](/garden/en/reference/compare) | Place two or three options side by side to contrast tradeoffs, or stack good and bad practices. |
-| [`timeline`](/garden/en/reference/timeline) | Order release milestones, incident steps, or build stages along a vertical sequence. |
-| [`chart`](/garden/en/reference/chart) | Render proportional horizontal bars with a built-in expandable data table underneath. |
-| [`compose`](/garden/en/reference/compose) | Draw an explanation diagram of cards, arrows, and notes. Click a step to open its note. |
-| [`compose icons`](/garden/en/reference/compose-icons) | Every named stroke icon: glyph + name, A–Z. |
-| [`html`](/garden/en/reference/html) | Run a self-contained HTML, CSS, and JavaScript demo inside a sandboxed iframe. |
-| [`interactive`](/garden/en/reference/interactive) | Let readers drag sliders or switches to recalculate formulas and charts in real time. |
-| [`file`](/garden/en/reference/file) | Attach one or more files with automatic format and size badges, download links, and inline preview. |
-| [`relations`](/garden/en/reference/relations) | Place 3 to 6 elements on an ellipse or around a center node and connect them with solid or dashed, one-way or two-way labeled links. |
-| [`list`](/garden/en/reference/list) | Pair line icons with short observations in a compact card, or add headings and multi-paragraph notes for divided steps. |
-| [`choice`](/garden/en/reference/choice) | Present two or three option cards with an icon, headline value, and preference label, plus an optional fallback button and selection reply. |
+- [Compose](/garden/en/components/compose)
+- [Compose reference](/garden/en/reference/compose)
+- [Icons](/garden/en/reference/compose-icons)

package/docs/handbook/en/start.md

@@ -93,7 +93,7 @@ make check
 
 ## 5. Editor Plugins
 
-To write an interactive component, insert an idea in VS Code, Cursor, or Typora, preview it, open the catalog, and let the `garden-ui` skill compile it. The plugins ship inside `hd-garden`. You do not compile them yourself.
+To write an interactive component, insert an idea in VS Code, Cursor, or Typora, preview it, open the catalog, and let the `garden-compose` skill compile it. The plugins ship inside `hd-garden`. You do not compile them yourself.
 
 `npx hd-garden init` copies the files to `.garden/editors/`. An interactive terminal asks whether to install VS Code / Cursor and whether to install Typora. The first `npx garden sync` asks again if that prompt has not happened yet. With no TTY, `CI=1`, or `GARDEN_SKIP_EDITORS=1`, Garden only prints the hint. Install later with:
 

package/docs/handbook/en/workflow.md

@@ -38,25 +38,20 @@ Three commands check your content at different scopes:
 
 | Code | Severity | Cause and Fix |
 | :--- | :--- | :--- |
-| `missing-title` / `missing-description` | Error | Front Matter is missing a non-empty `title` or `description` |
+| `missing-title` / `invalid-description` | Error | The title is missing or empty, or description is neither a string nor null; a blank description is valid |
 | `unexpected-slug` | Error | Front Matter includes a manual `slug` field (remove `slug`; the filename is the slug) |
 | `date-format` | Error | `date` is not a valid `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or ISO timestamp with timezone |
-| `missing-cover` / `missing-asset` | Error | A local file referenced by `cover`, a Markdown image, or `garden file` does not exist |
+| `missing-cover` / `missing-asset` | Error | A local file referenced by `cover`, a Markdown image, or Compose `file` does not exist |
 | `heading-h1` / `heading-skip` | Error | The post body uses an `#` H1 heading or skips a heading level (such as jumping from `##` to `####`) |
 | `reference-heading` | Error | The post body contains a references section heading (move references to the `references` Front Matter list) |
 | `callout-type` | Error | `> [!TYPE]` uses an unsupported callout type |
 | `title-split` | Warning | The title contains a split delimiter with an empty left or right side |
 | `diff-orphan` | Error | A `diff` code fence is not immediately preceded by a complete code block |
-| `legacy-fence` | Error | Uses a legacy fence name (such as `garden:stat`, `widget`, `embed`, or `html garden`); replace with `garden <name>` |
-| `garden-idea` | Error | A non-draft post still contains an uncompiled `garden` idea fence |
 | `compose-uncompiled` | Error | A non-draft `garden compose` fence is still prose, not markup |
 | `compose-invalid` | Error | A `garden compose` document is invalid: unknown tag, unclosed tag, or a YAML slot tree |
-| `garden-name` | Error | Unknown `garden` component name (`card`, `stat`, `compare`, `timeline`, `chart`, `compose`, `html`, `interactive`, `file`, `relations`, `list`, `choice`) |
-| `garden-yaml` | Error | Invalid YAML syntax, wrong top-level shape, or unsupported keys inside a `garden` fence |
-| `garden-relations` | Error | `garden relations` has fewer than 3 or more than 6 elements, or invalid `links` entries (use a `mermaid` flowchart for larger or branching diagrams, or `garden list` for one-pass steps) |
-| `garden-file` / `file-outside` | Error | `garden file` manually sets `resolved`, is missing a valid `src` / `files`, or points outside `content/` |
-| `file-large` | Warning | A local file referenced by `garden file` exceeds `5 MB` |
-| `compare-long` | Error | A single side-by-side cell in `garden compare` exceeds roughly 60 characters (does not apply when `verdict` is used) |
+| `garden-name` | Error | Author component fences must use `garden compose`. |
+| `compose-file` / `file-outside` | Error | Compose `file` manually sets `resolved`, is missing a valid `src` / `files`, or points outside `content/` |
+| `file-large` | Warning | A local file referenced by Compose `file` exceeds `5 MB` |
 | `interactive-trivial` / `steps-prose` | Error | `garden compose` only computes a single multiplication, or `<Steps>` contains only prose without state changes |
 
 ## 3. Git Pre-commit Hook and Component Catalog
@@ -77,15 +72,14 @@ Garden provides three ways to insert or generate components quickly:
 1. **Draft cheat sheet comment**: Running `make new SLUG=xxx TITLE="..."` appends an HTML comment to the bottom of the new `.md` file with examples for idea fences and the built-in components. HTML comments are hidden from the rendered page and can be deleted when finished.
 2. **Snippet template files**: The `templates/` directory inside `hd-garden` includes two template files:
    - `templates/garden-blocks.md`: Copyable Markdown templates for idea fences and the built-in components.
-   - `templates/garden-snippets.plist`: macOS text replacements (drag into **System Settings → Keyboard → Text Replacements**) with triggers `;gidea`, `;gcard`, `;gstat`, `;gcompare`, `;gtimeline`, `;gchart`, `;gcompose`, `;ghtml`, `;ginteractive`, `;gfile`, `;grel`, `;glist`, and `;gchoice`. `;gcompose` expands to a `garden compose` fence with one sentence. The others expand to their fences.
-3. **Install AI Agent skills (`npx garden skill`)**: Running `npx garden skill` in a site repository (also run automatically during `npx hd-garden init`) copies three skills into `.agents/skills/`:
-   - `garden-ui`: Compiles natural-language `garden` idea fences into concrete component blocks.
-   - `garden-interactive-chart`: Authors `interactive`, `chart`, `compose`, and `html` components from article data.
+   - `templates/garden-snippets.plist`: one Compose author entry; choose components inside the scene.
+3. **Install AI Agent skills (`npx garden skill`)**: Running `npx garden skill` in a site repository (also run automatically during `npx hd-garden init`) copies two skills into `.agents/skills/`:
+   - `garden-compose`: Compiles natural-language `garden` idea fences into concrete component blocks.
    - `garden-post-review`: Reviews an entire post against layout and component rules.
 
 ## 5. VS Code, Cursor, and Typora Plugins
 
-The Intelligent UI plugins are the editor entry point for interactive components: insert a one-sentence idea, preview it, open the catalog, then hand compilation to the `garden-ui` skill. They ship inside `hd-garden`. A site does not compile `editors/vscode` or `editors/typora` from source.
+The Intelligent UI plugins are the editor entry point for interactive components: insert a one-sentence idea, preview it, open the catalog, then hand compilation to the `garden-compose` skill. They ship inside `hd-garden`. A site does not compile `editors/vscode` or `editors/typora` from source.
 
 ### Install
 
@@ -110,7 +104,7 @@ The Obsidian plugin is not installed by this command.
 
 ### Use the plugins while writing
 
-1. **Insert an idea.** In VS Code / Cursor, use `Cmd+Alt+I` on macOS or `Ctrl+Alt+I` on Windows and Linux, or the Garden insert command. In Typora, type `/` and choose `/garden` (the next list has a small preview image on each row), or use the insert command to open the component list directly; Windows and Linux default to `Ctrl+Alt+I`. On macOS, record a shortcut under Settings, Keyboard Shortcuts, because Option rewrites the key. The insertion is a plain `garden` fence: a short brief naming the component and the facts to mention, which the `garden-ui` skill compiles later.
+1. **Insert an idea.** In VS Code / Cursor, use `Cmd+Alt+I` on macOS or `Ctrl+Alt+I` on Windows and Linux, or the Garden insert command. In Typora, type `/` and choose `/garden` (the next list has a small preview image on each row), or use the insert command to open the component list directly; Windows and Linux default to `Ctrl+Alt+I`. On macOS, record a shortcut under Settings, Keyboard Shortcuts, because Option rewrites the key. The insertion is a plain `garden` fence: a short brief naming the component and the facts to mention, which the `garden-compose` skill compiles later.
 2. **Preview.** Open the Markdown preview. In Typora, move the cursor out of the fence. A `ui` block renders the same component as the blog. An `intent` block renders as an idea card. Clicks on sliders and buttons stay in the preview.
 3. **Open the catalog.** In VS Code / Cursor, the catalog command inserts a recipe at the cursor. The terminal builds the same page:
 
@@ -119,4 +113,14 @@ The Obsidian plugin is not installed by this command.
    ```
 
    That writes `.garden/ui-catalog.html`.
-4. **Compile with the skill.** Copy compile prompt. On an English site (`locale: en_US`) the clipboard text is `Compile this post:` plus the post path. Paste it to an Agent that has the `garden-ui` skill. The skill runs `npx garden ui scan`, reads `npx garden ui prompt`, and replaces only that fence with `npx garden ui apply`. The plugin does not call a model. Check the result with `npx garden ui check` or the pre-commit hook.
+4. **Compile with the skill.** Copy compile prompt. On an English site (`locale: en_US`) the clipboard text is `Compile this post:` plus the post path. Paste it to an Agent that has the `garden-compose` skill. The skill runs `npx garden ui scan`, reads `npx garden ui prompt`, and replaces only that fence with `npx garden ui apply`. The plugin does not call a model. Check the result with `npx garden ui check` or the pre-commit hook.
+
+
+## Strict local check
+
+Run `make check` to check every article structure and every Compose/UI block in the working tree, including drafts and untracked files. No staging is needed. Both checks run even if structural errors are found, so Compose diagnostics and a short project `garden-compose` skill instruction are still shown. No prompt file is generated by default. No AI call or clipboard copy happens.
+
+`make check FILE=content/posts/post.md` limits the content preflight to that file. After preflight succeeds, the existing full-site sync/build stages still run. The engine repository retains its lint/test stages instead. Failure exits nonzero and skips these later stages. This is compilation/validation, not an automatic formatting or repair command.
+
+
+`make check diff` checks only changed Markdown documents under `content/`: tracked working-tree changes against HEAD (including staged changes) plus untracked files. It reads current working-tree contents, deduplicates paths, uses rename destinations and skips deleted files. It does not run all-site sync/build/lint/tests, even with `make -j check diff`. No changes is a successful no-op; missing Git/HEAD is an explicit error, never an all-content fallback. `garden verify --diff` is the underlying command. Diff mode overrides FILE; plain `make check` is unchanged.

package/docs/handbook/en/writing.md

@@ -36,7 +36,7 @@ references:
 | :--- | :--- | :--- | :--- |
 | `title` | Yes | String | Post title. Write ` \| ` (with spaces on both sides) to split the heading into two lines and scale the font size to fit |
 | `date` | Yes | Date string | Publication date (such as `2026-10-18` or an ISO timestamp with timezone) |
-| `description` | Yes | String | Summary shown in the article deck, archive lists, and search engine descriptions |
+| `description` | No | String | Summary shown in the article deck, archive lists, and search engine descriptions. Empty (`description: ""`), omitted, null, or whitespace-only values hide the summary; Garden does not substitute an excerpt from the body |
 | `updated` | No | Date string | Last updated date, shown in the article meta bar and used for RSS sorting |
 | `publishAt` | No | Date string | Scheduled publish time; included only when earlier than the build time (or when `CONTENT_INCLUDE_DRAFTS=1`) |
 | `tags` | No | String array | Tags for the post; clicking a tag filters `/blog?t=<tag>` |
@@ -62,12 +62,12 @@ func openStore(path string) (*Store, error) {
 }
 ```
 
-```garden
+```garden compose
 Compared with the previous version: open the store with ModeWAL instead of ModeJournal.
 ```
 ````
 
-Following the `garden-ui` skill, the Agent runs `npx garden ui apply` to replace that idea fence with a `diff` fence right below the code block (see [Writing with AI](/garden/en/ai-writing)). The page combines the two adjacent blocks into a single code frame with tabs for the full code and the diff against the previous version, while the copy button always copies the new full code:
+Following the `garden-compose` skill, the Agent runs `npx garden ui apply` to replace that idea fence with a `diff` fence right below the code block (see [Writing with AI](/garden/en/ai-writing)). The page combines the two adjacent blocks into a single code frame with tabs for the full code and the diff against the previous version, while the copy button always copies the new full code:
 
 ```go
 func openStore(path string) (*Store, error) {

package/docs/handbook/index.md

@@ -13,19 +13,19 @@ Garden 是一个 Claude 风格的博客框架，文章用 Markdown 写，组件
 
 ### 1. 作者写一句想法
 
-在想放交互的地方写一个不带名字的 `garden` 围栏，里面写清想让读者做什么、看到什么：
+在需要组件的地方写一个 `garden compose` 围栏，里面写清想让读者做什么、看到什么：
 
 ````markdown
 ## 写作节奏
 
-```garden
+```garden compose
 让读者拖动每天写的字数和每周写几天，看写完一篇 8000 字的长文要几周。
 ```
 ````
 
 ### 2. Agent 扫描并写回组件
 
-对 Agent 说「编译这篇：content/posts/writing-pace.md」。Agent 按站点里的 `garden-ui` skill 先运行 `npx garden ui scan`，拿到这一块的行号、原话和哈希：
+对 Agent 说「编译这篇：content/posts/writing-pace.md」。Agent 按站点里的 `garden-compose` skill 先运行 `npx garden ui scan`，拿到这一块的行号、原话和哈希：
 
 ```console
 $ npx garden ui scan content/posts/writing-pace.md
@@ -34,7 +34,7 @@ $ npx garden ui scan content/posts/writing-pace.md
   "draft": false,
   "blocks": [
     {
-      "lang": "garden-idea",
+      "lang": "garden-compose",
       "status": "uncompiled",
       "startLine": 9,
       "intentHash": "cb3a3569",
@@ -52,31 +52,17 @@ $ npx garden ui apply content/posts/writing-pace.md --intent-hash cb3a3569 --fil
 {"ok":true,"file":"content/posts/writing-pace.md","kind":"garden","line":9}
 ```
 
-### 3. 提交前钩子检查并生成修复提示词
+### 3. 提交前钩子检查并调用修复技能
 
-首次运行 `garden sync` 或 `garden dev` 时，Garden 会在 `.git/hooks/pre-commit` 写入 `exec npx --no-install garden ui check --staged --quiet`。如果作者在第 2 步之前直接提交，钩子会拦下提交，并打印一段可以直接粘贴给 AI 的修复提示词：
+首次运行 `garden sync` 或 `garden dev` 时，Garden 会在 `.git/hooks/pre-commit` 写入 `exec npx --no-install garden ui check --staged --quiet`。如果作者在第 2 步之前直接提交，钩子会拦下提交，并显示诊断和调用项目技能的短指令：
 
 ```console
 $ git commit -m "写作节奏"
-content/posts/writing-pace.md:9  -  garden-idea  还有没编译的想法
-
-──────────────────────── 发给 AI 的修复提示词 ────────────────────────
-请处理下面 Garden 博文里列出的块：没编译的想法要编译，有错误的交互块要修好。
-
-要求：
-- 先运行 npx garden ui prompt，读组件目录和规则；仓库里有 garden-ui skill 时按它的流程做。
-- 只改列出的块，用 npx garden ui apply <稿件> --id <id> 写回（没有 id 的想法用 --intent-hash），不要直接编辑稿件。
-- 不改作者原话的意思。改完运行 npx garden ui check <稿件>，直到通过。
-- 如果你不能访问这个仓库，就只回复每块修好后的完整围栏。
-
-1. content/posts/writing-pace.md，第 9–11 行，intent-hash: cb3a3569
-   - garden-idea：这段想法还没编译，请按原话编译成 garden compose 或其他 garden 组件（或判断后写回正文）。
-（后面附当前围栏原文）
-────────────────────────────────────────────────────────────
-已写入 .garden/ui-fix-prompt.md。确实要先提交，可以用 git commit --no-verify。
+content/posts/writing-pace.md:9  -  compose-uncompiled  还有没编译的 compose 想法
+请调用 garden-compose skill（.agents/skills/garden-compose/SKILL.md），修复以上错误块后重新校验。
 ```
 
-这段提示词同时写入 `.garden/ui-fix-prompt.md`，有剪贴板命令时自动复制。把提示词贴给 Agent 完成转换后再提交，钩子静默通过（退出码 `0`）。
+终端只显示诊断和一条指向项目 `garden-compose` skill 的短指令；默认不写文件、不复制剪贴板、不输出原文或组件目录。修复后钩子静默返回 `0`。
 
 ### 4. 页面渲染结果
 
@@ -87,18 +73,23 @@ caption: 每天多写几百字，比每周多写一天更快。
 intent: |
   让读者拖动每天写的字数和每周写几天，看写完一篇 8000 字的长文要几周。
 ---
-<State daily={500} days={3} />
-<Let weekly={daily * days} />
-<Let weeks={ceil(8000 / weekly)} />
+{@body const [daily, setDaily] = DIL.useState(500)}
+{@body const [days, setDays] = DIL.useState(3)}
+{@body const weekly = daily * days}
+{@body const weeks = ceil(8000 / weekly)}
 
-<Slider bind="daily" label="每天写" min={200} max={2000} step={100} unit="字" />
-<Slider bind="days" label="每周写" min={1} max={7} step={1} unit="天" />
 
-<Stat label="写完 8000 字需要" value={weeks} unit="周" hint="不足一周按一周算" />
+
+
+<slider bind="daily" label="每天写" min={200} max={2000} step={100} unit="字" />
+<slider bind="days" label="每周写" min={1} max={7} step={1} unit="天" />
+
+<stat label="写完 8000 字需要" value={weeks} unit="周" hint="不足一周按一周算" />
+
 ```
 
 > [!IMPORTANT] 人和 Agent 用同一套工具
-> Agent 找块用的 `npx garden ui scan`、写回用的 `npx garden ui apply`、自查用的 `npx garden ui check`，和作者提交时 pre-commit 钩子运行的检查是同一组命令。钩子拦截时打印的提示词，就是发给 Agent 的下一步指令。详见 [用 AI 写作](/garden/ai-writing)。
+> Agent 找块用的 `npx garden ui scan`、写回用的 `npx garden ui apply`、自查用的 `npx garden ui check`，和作者提交时 pre-commit 钩子运行的检查是同一组命令。钩子拦截时给出的技能调用短指令，就是发给 Agent 的下一步。详见 [用 AI 写作](/garden/ai-writing)。
 
 下面几节介绍不用 Agent 也会自动生效的版面与组件规则。
 
@@ -148,25 +139,13 @@ pages:
 
 ## 在文章里嵌入结构化组件
 
-需要数字、对比、时间线或图表时，用 ```` ```garden <name> ```` 围栏插入内置组件。下面是一组 `garden stat`：
-
-```garden stat
-items:
-  - label: 正文阅读列
-    value: "740"
-    unit: px
-    caption: 段落、代码块与列表的默认列宽
-  - label: 宽幅配图区
-    value: "1040"
-    unit: px
-    caption: 截图按像素宽度的一半显示，像素宽度约 2000px 以上时展开到这个宽度
-  - label: 多列宽表区
-    value: "1340"
-    unit: px
-    caption: 宽表格在桌面端向两侧对称外扩上限
+需要数字、对比、时间线或图表时，在 `garden compose` 内组合对应组件。下面是一组数值：
+
+```garden compose
+<stack><metric label="正文阅读列" value="740" unit="px" caption="段落、代码块与列表的默认列宽"></metric><metric label="宽幅配图区" value="1040" unit="px" caption="截图按像素宽度的一半显示，像素宽度约 2000px 以上时展开到这个宽度"></metric><metric label="多列宽表区" value="1340" unit="px" caption="宽表格在桌面端向两侧对称外扩上限"></metric></stack>
 ```
 
-组件页包括各个 `garden` 围栏，以及链接卡片、来源胶囊和本地图片。说明图是 [compose](/garden/components/compose)。效果见左侧导航的 [组件总览](/garden/components)。
+组件页以 `garden compose` 为唯一 Garden 作者入口，另含链接卡片、来源胶囊和本地图片。内容、布局和交互在 [compose](/garden/components/compose) 内组合。效果见左侧导航的 [组件总览](/garden/components)。
 
 <h2 id="garden-admin-title">从初始化到日常写作</h2>
 

package/docs/handbook/reference/compose.md

@@ -1,182 +1,113 @@
 ---
-title: 组件参考 · compose
+title: 组件参考 · Compose
 navTitle: compose
-description: 全部 compose 标签一览、共用 token，以及图标目录入口。
+description: 单一作者入口、可执行渲染契约与验证。
 section: reference
 order: 6
 badge: compose
 ---
 
-[← 组件参考](/garden/reference) · [用法](/garden/components/compose) · [图标目录](/garden/reference/compose-icons)
+ZH: 统一使用 `garden compose`；以下按真实实现解释组合机制、内容边界与检查方法。完整属性按需运行 `npx garden ui schema`，不复制易过期的目录。
 
-围栏写 ` ```garden compose `。作者原话放 `<intent>`（不绘制）。未知标签报 `compose-invalid`。
+## One entry, component selection inside it
 
-当前 **68** 个标签（见下方目录）。图标 **690** 个名字 —— 见 [图标目录](/garden/reference/compose-icons)。
+Use `garden compose`. Select by the reader's task, not by another fence name:
 
-## 共用 token
+| Need | Compose structure |
+| :--- | :--- |
+| Reference material and takeaways | `resources/resource`, nested `point`, `reference` |
+| Key results | `metric` with label, value, unit, caption, paragraphs and references |
+| Time or stages | `timeline/event` |
+| Alternatives and verdicts | `compare/item` |
+| Icon-led editorial paragraphs | `icon-list/entry` or a small `icon` beside one shared text container |
+| Download and preview | `files/file` or one `file src="…"` |
+| Connected concepts | `relations/entity/edge`, stable ids; 3–6 entities |
+| Rich selectable cards and replies | `choices/choice-option`, optional `none` option |
+| Discrete bars and exact values | `plot/datum`; expandable data table |
+| Parameter-dependent results | Play declarations, controls, `chart/bar/line`, `pie`, `table` |
+| Article text and useful HTML | `markdown` and `html` content islands |
+| Independent executable illustration | Play `sandbox` with literal html/css/js; isolated offline iframe |
 
-多数布局标签共用；颜色只走 Garden 主题变量（Claude 纸色）。
+The authoritative, demand-loaded catalog is `npx garden ui schema`: actual semantic fields, Play props/defaults/child contracts, icon names, safe HTML tags/attributes/CSS properties. `npx garden ui prompt` adds working recipes. `styleReference` also extracts current font/layout declarations, selectors, responsive conditions and source order from the installed stylesheets; it reports source defaults, not universal computed values. These are generated from the validators and actual styles; do not maintain a second exhaustive tag list. Static layout normalization is not a universal HTML/CSS API: inspect the normalized tree and output because some unsupported static layout attributes are ignored. Semantic unknown fields fail validation.
 
-| Token | 取值 |
-| :--- | :--- |
-| `padding` / `gap` | `0`–`4`（4px × n） |
-| `background` | `surface` `surface-secondary` `surface-accent` `surface-tip` `surface-muted` `transparent` |
-| `radius` | `none` `sm` `md` `lg` `xl` `full` |
-| `border` | `subtle` `strong`/`true` `none`/`false` |
-| `size` | `sm` `md` `lg` `xl` |
-| `tone` | `plain` `accent` `tip` `muted`（callout 另有 `note`/`warn`） |
-| `align` | `start` `center` `end` `stretch` |
-| `justify`（row） | `start` `center` `end` `between` `around` |
-| `wrap`（row） | `wrap` `nowrap` |
+图表的可运行示例见[Compose 活跃时段图](/garden/components/compose#ui-compose-chart-active-hours)。
 
-## 高频属性
+## Relationships → hierarchy → layout → style → actual output
 
-### `box` / `card`
+First identify what belongs together. A heading and all its paragraphs must share a container. Next choose columns and proportions, then alignments and typography. Only then add surfaces and decorative details.
 
-| 属性 | 说明 |
-| :--- | :--- |
-| `frame` | `card`（默认）`band` `pill` `text`；也可用糖标签 `<band>` / `<pill>` |
-| `padding` `gap` `radius` `border` `background` `size` `align` `tone` `id` `mark` | 共用 token；`mark="shield"` 画盾牌 |
+A static `row` wraps by default. Its direct text/title/stack/card children share available width (`flex: 1 1 0`), whereas an icon is content-sized. A heading placed directly in that row is a sibling column, not the heading of a paragraph below the row. `align="center"` on a row changes more than vertical placement: theme rules also center text. A centered stack propagates text alignment. For an editorial list use explicit start alignment on children of a shared right-hand group; do not center each title independently.
 
-### `row` / `stack` / `grid`
+Direct `row > stack` has 12px top padding in the current theme. A `group` is a width:100%, min-width:0 vertical container that shrinks beside the fixed icon and reads gap without that contextual padding; use it when icon and heading must begin on the same top line. Explicit `align="start"` survives normalization and emits data-align.
 
-| 属性 | 说明 |
-| :--- | :--- |
-| `gap` `align` | 共用 |
-| `justify` `wrap` | 仅 `row` |
-| `cols` | 仅 `grid`，1–6 |
-| `span` | 仅 `grid-item`，1–6 |
+Nested paragraphs need separate `text` leaves or an article content island. Two unrelated top-level leaves do not establish a shared right column. Put a full-width divider **between rows**, not inside the right text container, if the rule must span the icon column too. `divider` and `separator` are real primitives, not text lines.
+
+```garden compose
+<figure frame="none">
+<row wrap="nowrap" align="start" gap="4">
+  <icon name="book-open" size="xl"/>
+  <group gap="2">
+    <title align="start">Test heading — not article content</title>
+    <text align="start">Explicit test paragraph: the heading and this body share the same right column. Keep the author's complete text; do not shrink or summarize it to fit.</text>
+    <text align="start">A second independent test paragraph stays in that column.</text>
+  </group>
+</row>
+<divider/>
+<row wrap="nowrap" align="start" gap="4">
+  <icon name="users" size="xl"/>
+  <group gap="2">
+    <title align="start">Second test heading</title>
+    <text align="start">Another test body, aligned with its heading rather than spanning the icon column.</text>
+  </group>
+</row>
+</figure>
+```
 
-### `text` / `title` / `caption`
+For a native editorial list the same relationship is expressed with `icon-list` containing `entry icon="…" title="…"`, and multiple `text` children per entry. Native paragraph children are lowered to text strings: their nested text size/alignment/layout properties are not carried into the native scene. Use a generic layout with text size controls for such precision; do not assume identical nested styling contracts. Native scenes preserve the app's keyboard/selection/detail/file-preview behavior when rendered by the Garden article host. A standalone static export is a readable fallback, not an identical interactive host.
 
-| 属性 | 说明 |
-| :--- | :--- |
-| `size` `align` | 共用 |
-| `tone` | `text`：`plain` `muted` `accent` `tip`。`caption` 固定 muted。 |
+## Typography and complete-theme context
 
-### `icon`
+Default body text inherits the **actual article's** family, size and line height. There is no universal pixel baseline. This includes ordinary static text, list bodies and native readable prose; changing the article typography configuration must propagate. Semantic headings, graph labels, values, captions and controls intentionally retain their hierarchy.
 
-| 属性 | 说明 |
+| Element/context | Actual source rule / intentional variation |
 | :--- | :--- |
-| `name` | 必填；须在 [图标目录](/garden/reference/compose-icons) |
-| `size` | `sm` `md` `lg` `xl` |
-| `inline` | 与文字同行 |
+| Static `text` and `title` | Inherit body size; title weight 600, line height 1.4. `size="sm"` .875em; `lg` 1.125em; `xl` 1.25em. `md` keeps the baseline. |
+| Static outer figure title/caption | Source defaults 18px/14px, not ordinary body; actual cascade still matters. |
+| Static inline caption | Own semantic style; `sm` 11px, `lg` 16px. Not a body substitute. |
+| Native icon-list entry title/body | Title weight 600; body inherits article. Group heading uses `--fs-small`. |
+| Native choice value | 22px; narrow rule 20px. Option body inherits article. |
+| Native relation ring | Compact/context-dependent labels and line clamps; detail prose inherits article. Do not treat a ring label as a long paragraph. |
+| Play components | Query schema defaults and complete theme. Their controls/KPI/graph semantics are not globally changed to body size. |
 
-## 标签目录
+Use explicit variation only for a meaningful hierarchy. Never shrink body text globally to fit a screenshot or discard facts to avoid wrapping. Inspect actual computed styles with globals → tokens → article theme → shell in the real order, on desktop and narrow widths; base component CSS alone does not prove the final result.
 
-每组一个迷你样例，下面一张一句话表；不写长文。
+## Markdown, safe HTML, and execution
 
-### 布局
-
-```garden compose
-<row gap={2}><box padding={2} radius="md" border="subtle"><title size="sm">甲</title></box><box padding={2} radius="md" background="surface-accent"><title size="sm">乙</title></box></row>
-```
+`text`, `title` and captions are inline contexts: `**bold**`, `_emphasis_`, backticks, `[links](https://example.com)`, `~~strike~~` and safe inline HTML such as `<u>underline</u>`. `<u>` is HTML, not standard Markdown.
 
-| 标签 | 用途 |
-| :--- | :--- |
-| `box` | 通用容器；可设 padding / gap / background / radius |
-| `card` | box 的卡面别名 |
-| `stack` | 竖排 |
-| `row` | 横排 |
-| `columns` | 多列横排（默认可换行） |
-| `grid` | 等分网格；cols 1–6 |
-| `grid-item` | 网格格；span 跨列 |
-| `group` | 语义分组容器 |
-| `field` | 表单项分组 |
-| `header` | 页眉区 |
-| `footer` | 页脚区 |
-| `figure` | 图示区 |
-| `prose` | 长文段落区 |
-| `divider` | 分隔线（自闭合） |
-| `separator` | divider 别名 |
-| `spacer` | 空白间距 |
-| `band` | 通栏强调条（box frame=band） |
-| `pill` | 胶囊（box frame=pill） |
-
-### 文字
+Use `markdown` or `html` islands for full paragraphs, lists, headings, blockquotes, code blocks, tables, images, details/summary and other allowlisted article content. The islands share the article Markdown/GFM and safe-HTML renderer; they are not arbitrary component trees. Static text outside islands is a lightweight layout shorthand, **not** the whole article block grammar. Play islands are literal content, not interpolated expressions. Keep state and expressions in Play component nodes outside them.
 
 ```garden compose
-<stack gap={1}><title size="sm">标题</title><text size="sm">正文</text><caption size="sm">说明</caption><badge>徽标</badge></stack>
-```
+<figure frame="none">
+<markdown>
+### Explicit test content
 
-| 标签 | 用途 |
-| :--- | :--- |
-| `title` | 短标题 |
-| `text` | 正文 |
-| `caption` | 次要说明（默认 muted） |
-| `label` | 控件标签 |
-| `badge` | 胶囊徽标 |
-| `kpi` | 指标数字（自闭合） |
-| `stat` | kpi 别名 |
-| `icon` | 具名描边图标（自闭合） |
-| `callout` | 提示条 |
-| `kbd` | 键盘键帽 |
-| `link` | 行内链接 |
-| `intent` | 作者原话（不绘制） |
-
-### 控件
+**Bold**, _emphasis_, `code`, [link](https://example.com), ~~strike~~ and <u>underline</u>.
 
-```garden compose
-<stack gap={2}><row gap={2}><avatar label="甲" size="sm"/><badge>好</badge><kbd>⌘K</kbd></row><list><list-item>一项</list-item><list-item>二项</list-item></list><progress value={40} max={100} label="40%"/></stack>
+- A full Markdown list
+- Another test item
+
+<details><summary>Safe HTML details</summary><p>Useful article HTML can coexist with Markdown.</p></details>
+</markdown>
+</figure>
 ```
 
-| 标签 | 用途 |
-| :--- | :--- |
-| `button` | 按钮快照 |
-| `slider` | 滑杆快照 / play 可调 |
-| `progress` | 进度条 |
-| `meter` | 计量条 |
-| `checkbox` | 复选框快照 |
-| `radio` | 单选快照 |
-| `toggle` | 开关快照 |
-| `switch` | toggle 别名 |
-| `input` | 单行输入快照 |
-| `textarea` | 多行输入快照 |
-| `select` | 下拉快照 |
-| `tabs` | 选项卡容器 |
-| `tab` | 单个选项卡 |
-| `list` | 列表 |
-| `list-item` | 列表项 |
-| `table` | 表格 |
-| `thead` | 表头 |
-| `tbody` | 表体 |
-| `tr` | 表行 |
-| `th` | 表头格 |
-| `td` | 表数据格 |
-| `image` | 图片 |
-| `avatar` | 头像占位 |
-| `empty` | 空状态 |
-| `option` | 分段选项快照 |
-
-### 连接糖
+Safe HTML supports allowlisted local `style` properties, including useful layout and typography; inspect the generated schema for the actual set. Unsupported tags/properties, events, unsafe URLs, executable scripts and network CSS functions report diagnostics. Do not expand the article allowlist into arbitrary execution. An intentional executable demo uses `sandbox` inside the **same Compose entry**, with literal html/css/js and no parent origin access. Sandbox layout is its own document, not inherited article prose.
 
-```garden compose
-<stack align="center" gap={1}><pill>起点</pill><arrow dir="down"/><band tone="accent" align="center"><title size="sm">枢纽</title></band></stack>
-```
+## Verification levels
 
-| 标签 | 用途 |
-| :--- | :--- |
-| `arrow` | 箭头 |
-| `fan` | 向下分叉箭头 |
-| `join` | V 形汇合 |
-| `lanes` | 泳道图 |
-| `actor` | 泳道角色 |
-| `message` | 泳道消息 |
-| `steps` | 分步容器 |
-| `step` | 一步 |
-| `note` | 步骤展开说明 |
-| `compare` | 对照卡组 |
-| `item` | 对照项 |
-| `code` | 代码快照 |
-| `pre` | 预格式文本 |
-
-
-## 图表示例
-
-玩法级图表示例（静态八柱、融合权重滑杆）见 [说明图 · compose](/garden/components/compose#ui-compose-chart-active-hours)。
-
-## 限制
-
-- 嵌套约 10 层 / 约 220 节点。
-- 只有白话、没有标签时报 `compose-uncompiled`。
-- Play（`{@body}`、`{#if}` …）见仓库 `docs/compose-dil.md`；静态围栏里的控件标签画成默认态快照。
+1. Run `npx garden ui check <file>` (and `npx garden check <file>` for real file paths). Preserve original text/resources and inspect diagnostics.
+2. Parse/render the actual scene; confirm accepted properties survive normalization and meaningful content appears.
+3. Inspect the complete-theme render: icon rail fixed, heading and **all** paragraphs share the same right edge/left edge, no centered headings or full-width body beneath a detached icon row, dividers outside rows, no unintended cards/arrows, no horizontal overflow.
+4. Check desktop and narrow screenshots plus geometry/computed styles; exercise choices, relations, file previews, state updates and sandbox behavior when used.
+5. A hand-authored passing scene proves engine capability, not that an independent model reliably produces it from a short prompt. Report those claims separately.

package/docs/handbook/reference.md

@@ -1,29 +1,13 @@
 ---
 title: 组件参考
-navTitle: 总览
-description: garden 围栏组件的字段、默认值、取值限制和报错代码。
+navTitle: 组件参考
+description: 组件参考
 section: reference
 order: 0
 ---
 
-每页左边是代码，右边是同一段代码渲染出的真实效果；窄屏下用「效果 / 代码」切换。用法和什么时候用，见各组件的用法页。
+文章布局、富文本、语义场景与交互说明统一使用一个 `garden compose` 围栏。在入口内部选择并组合组件；普通 Markdown 已能表达清楚时不用增加组件。
 
-链接卡片、来源胶囊和本地图片没有字段页，用法在 [组件总览](/garden/components)。
-
-所有组件通用：YAML 语法错误，或顶层出现不支持的键名，整块报 `garden-yaml`；围栏名写错报 `garden-name`。
-
-| 组件 | 用途 |
-| :--- | :--- |
-| [`card`](/garden/reference/card) | 介绍一篇论文、一个项目或一组值得参考的公开工具。 |
-| [`stat`](/garden/reference/stat) | 把 2～4 个关键数字、单位与一句说明并排摆出来。 |
-| [`compare`](/garden/reference/compare) | 把两三种方案左右并列，或把不好的做法与更好的做法上下对照。 |
-| [`timeline`](/garden/reference/timeline) | 按时间或阶段顺序排开版本演进、排查经过或关键节点。 |
-| [`chart`](/garden/reference/chart) | 把一组算好的数字画成比例条形图，下方自带可展开的数据表。 |
-| [`compose`](/garden/reference/compose) | 用卡片、箭头和注释画一张说明图；标签全表与共用 token。 |
-| [`compose 图标`](/garden/reference/compose-icons) | 全部具名描边图标：字形 + 名字，按 A–Z 可扫。 |
-| [`html`](/garden/reference/html) | 在沙盒中运行一段独立的网页小工具、画布动画或演示。 |
-| [`interactive`](/garden/reference/interactive) | 让读者拖动滑杆或切换选项，实时看到公式和图表的计算结果。 |
-| [`file`](/garden/reference/file) | 给读者提供一份或一组可下载的文件，支持在当前页展开预览。 |
-| [`relations`](/garden/reference/relations) | 把三到六个要素排成环或中心辐射结构，画出谁影响谁、哪些是双向的。 |
-| [`list`](/garden/reference/list) | 用线条图标配短句列出几条并列动作，或带小标题列出分步做法。 |
-| [`choice`](/garden/reference/choice) | 给出两三个具体选项卡片，读者点选后看到对应的回应。 |
+- [Compose](/garden/components/compose)
+- [Compose reference](/garden/reference/compose)
+- [Icons](/garden/reference/compose-icons)

package/docs/handbook/start.md

@@ -93,7 +93,7 @@ make check
 
 ## 5. 编辑器插件
 
-写交互组件时，可以在 VS Code、Cursor 或 Typora 里插入想法、预览组件、打开清单，再把编译交给 `garden-ui` skill。插件随 `hd-garden` 发布，不用自己编译。
+写交互组件时，可以在 VS Code、Cursor 或 Typora 里插入想法、预览组件、打开清单，再把编译交给 `garden-compose` skill。插件随 `hd-garden` 发布，不用自己编译。
 
 `npx hd-garden init` 会把产物放到 `.garden/editors/`。终端可交互时分别询问是否安装 VS Code / Cursor 和 Typora。第一次 `npx garden sync` 如果还没问过，会再问一次。没有 TTY、`CI=1` 或 `GARDEN_SKIP_EDITORS=1` 时只打印提示。之后运行：