hd-garden 0.13.3 → 0.14.2

package/docs/handbook/ai-writing.md

@@ -9,28 +9,27 @@ order: 2
 在 Garden 里写图表、指标或交互组件不用记标签语法。你在正文写一句自然语言想法，Agent 按站点里的 skill 把它编译成组件，提交时再由同一套命令检查。
 
 > [!IMPORTANT] 人和 Agent 用同一套工具
-> Agent 找块用 `npx garden ui scan`，写回用 `npx garden ui apply`，自查用 `npx garden ui check`；作者提交时 pre-commit 钩子运行的也是 `npx garden ui check`。检查失败时打印的提示词，就是发给 Agent 的下一步指令。
+> Agent 找块用 `npx garden ui scan`，写回用 `npx garden ui apply`，自查用 `npx garden ui check`；作者提交时 pre-commit 钩子运行的也是 `npx garden ui check`。检查失败时给出的技能调用短指令，就是发给 Agent 的下一步。
 
 ## 1. 写一句想法
 
-在想放组件的位置写一个不带名字的 `garden` 围栏，只写想让读者做什么、看到什么，不用写组件名：
+在想放组件的位置写一个 `garden compose` 围栏，只写想让读者做什么、看到什么，不用写组件名：
 
 ````markdown
-```garden
+```garden compose
 让读者拖动每天写的字数和每周写几天，看写完一篇 8000 字的长文要几周。
 ```
 ````
 
-草稿（`draft: true`）里可以保留未编译的想法；非草稿文章里还有未编译的想法时，`npx garden ui check` 和 `npx garden check` 都会报 `garden-idea` 错误。Agent 会根据内容把想法编译成 `garden compose`、`card`、`stat`、`compare` 等内置组件，或者在一段话就能说清时直接写回普通段落。
+未编译的想法使用同一个 `garden compose` 入口。`npx garden ui check` 和 `npx garden check` 对草稿与已发布稿件都检查并报告 `compose-uncompiled`。Agent 在 Compose 内组合正文、资源、图形和交互；如果一段普通文字更清楚，也可以直接写回段落。
 
-## 2. 随包安装的三个 skill
+## 2. 随包安装的两个 skill
 
-三个 skill 存放在站点根目录的 `.agents/skills/` 下。`npx hd-garden init` 建站时会自动安装，首次运行 `npx garden sync` 或 `npx garden dev` 时会补齐缺失的 skill，运行 `npx garden skill` 可手动重装。
+两个 skill 存放在站点根目录的 `.agents/skills/` 下。`npx hd-garden init` 建站时会自动安装，首次运行 `npx garden sync` 或 `npx garden dev` 时会递归更新引擎管理的 skill（本地修改先备份到 `.garden/skill-backups/`），运行 `npx garden skill` 可手动重装。
 
 | Skill 名称 | 触发话术示例 | 执行操作 |
 | :--- | :--- | :--- |
-| `garden-ui` | 「编译这篇：content/posts/writing-pace.md」「重编译 writing-pace」或直接粘贴修复提示词 | 扫描 `uncompiled`、`stale`、`error` 状态的块，按规则生成组件并用 `npx garden ui apply` 写回；说「这篇哪里适合交互」则进入只读建议模式，最多挑出 5 处可直接粘贴的想法草稿 |
-| `garden-interactive-chart` | 组件目录表达不了的画布动画或模拟 | 在文章同名目录下编写独立 `.html` 文件，正文中只用 `garden html` 围栏嵌入 |
+| `garden-compose` | 「编译这篇：content/posts/writing-pace.md」「重编译 writing-pace」或直接粘贴修复提示词 | 扫描 `uncompiled`、`error` 状态的块，按规则生成组件并用 `npx garden ui apply` 写回；说「这篇哪里适合交互」则进入只读建议模式，最多挑出 5 处可直接粘贴的想法草稿 |
 | `garden-post-review` | 「审稿：content/posts/writing-pace.md」 | 先修 `npx garden check` 报出的结构错误，再按图表规范修交互块，最后通读全文只给修改建议而不改稿 |
 
 ## 3. `garden ui` 子命令与整篇检查
@@ -49,19 +48,17 @@ order: 2
 
 ## 4. 提交前检查与修复提示词
 
-首次运行 `npx garden sync` 或 `npx garden dev` 时，Garden 会在 `.git/hooks/pre-commit` 写入 `exec npx --no-install garden ui check --staged --quiet`（若已有其他钩子则不覆盖，只提示需添加的命令）。`--staged` 直接通过 `git show :<路径>` 读取暂存区内容，失败时输出文件行号、诊断码和一段修复提示词：
+首次运行 `npx garden sync` 或 `npx garden dev` 时，Garden 会在 `.git/hooks/pre-commit` 写入 `exec npx --no-install garden ui check --staged --quiet`（若已有其他钩子则不覆盖，只提示需添加的命令）。`--staged` 直接通过 `git show :<路径>` 读取暂存区内容，失败时输出文件行号、诊断码和调用项目技能的短指令：
 
 ```console
-content/posts/writing-pace.md:9  -  garden-idea  还有没编译的想法
+content/posts/writing-pace.md:9  -  compose-uncompiled  还有没编译的 compose 想法
 
-──────────────────────── 发给 AI 的修复提示词 ────────────────────────
-请处理下面 Garden 博文里列出的块：没编译的想法要编译，有错误的交互块要修好。
-……
+请调用 garden-compose skill（.agents/skills/garden-compose/SKILL.md），修复以上错误块后重新校验。
 ```
 
-- 提示词同时写入 `.garden/ui-fix-prompt.md`，系统有 `pbcopy`、`wl-copy`、`xclip`、`xsel` 或 `clip` 时自动复制到剪贴板；传入 `--no-copy` 或设置 `GARDEN_UI_NO_COPY=1` 可关闭自动复制。
-- 需要把提示词发给无法读取本地仓库的网页端聊天窗口时，运行 `npx garden ui check <稿件.md> --standalone`，提示词末尾会附上完整的 `npx garden ui prompt` 组件规则（单次最多附 10 个问题块的原文）。
-- 交互块里写错标签名（如把 `<Slider>` 写成 `<Slidr>`）也会报 `ui-component` 并指到具体行号；确实要先带病提交时可用 `git commit --no-verify`。
+- 默认只给出文件、行号、错误码和调用项目 `garden-compose` skill 的短指令。不写提示词文件、不复制剪贴板、不调用模型；已有提示词文件保持不变。
+- 只有确需独立导出时，显式运行 `npx garden ui check <稿件.md> --out .garden/export.md --standalone`。`--standalone` 仅为导出文件附加完整规则，单独使用不会创建文件。
+- 交互块里写错标签名（如把 `<Slider>` 写成 `<Slidr>`）也会报 `ui-component` 并指到具体行号。
 - 需要重装钩子时运行 `npx garden hooks`（加 `--force` 覆盖已有钩子）；不想自动安装钩子时设置 `GARDEN_SKIP_HOOKS=1`。
 
 ## 5. 用一句话生成代码对比
@@ -75,12 +72,12 @@ pages:
     title: "用 Markdown 写丨推送之后网站自己更新"
 ```
 
-```garden
+```garden compose
 和上一版比：标题原来用句号和换行分两行，现在改成用「丨」分行。
 ```
 ````
 
-Agent 按 `garden-ui` skill 会把这个想法块替换成一段紧挨着完整代码的 `diff` 围栏。页面渲染时会把完整代码和 `diff` 合成一个带「代码 / 对比上一版」切换按钮的代码框，手写 `diff` 的规则见 [写文章与随想](/garden/writing)。
+Agent 按 `garden-compose` skill 会把这个想法块替换成一段紧挨着完整代码的 `diff` 围栏。页面渲染时会把完整代码和 `diff` 合成一个带「代码 / 对比上一版」切换按钮的代码框，手写 `diff` 的规则见 [写文章与随想](/garden/writing)。
 
 ## 6. 在编辑器里插入、预览，再交给 skill 编译
 
@@ -95,16 +92,16 @@ npx garden editors install --typora
 
 装好之后，一篇组件通常是这四步：
 
-1. **插入想法。** 在要放组件的位置运行「插入 Garden 块」（VS Code / Cursor 的快捷键是 macOS `Cmd+Alt+I`，Windows / Linux `Ctrl+Alt+I`）。Typora 里输入 `/` 后选 `/garden`，下一层列表每一项有一张小预览图；命令的快捷键在 Windows / Linux 是 `Ctrl+Alt+I`，macOS 需要在「设置 → 快捷键」里自己录。插入的是给 `garden-ui` skill 编译的想法围栏，例如选「资源卡」得到：
+1. **插入想法。** 在要放组件的位置运行「插入 Garden 块」（VS Code / Cursor 的快捷键是 macOS `Cmd+Alt+I`，Windows / Linux `Ctrl+Alt+I`）。Typora 里输入 `/` 后选 `/garden`，下一层列表每一项有一张小预览图；命令的快捷键在 Windows / Linux 是 `Ctrl+Alt+I`，macOS 需要在「设置 → 快捷键」里自己录。插入的是给 `garden-compose` skill 编译的想法围栏，例如选「资源卡」得到：
 
    ````markdown
-   ```garden
+   ```garden compose
    做成资源卡。一篇论文、一个仓库或一本书，读者需要标题、链接和一句说明。请写上链接、标题、一句说明。
    ```
    ````
 2. **预览。** 打开 Markdown 预览，或在 Typora 里把光标移出围栏。`intent` 显示成想法卡片；skill 写回 `ui` 之后，预览画成和博客一样的组件。错误会标在源码上（VS Code / Cursor 的「问题」面板和 CodeLens）。
 3. **看清单。** 命令「查看组件清单」，或在终端运行 `npx garden ui catalog` 打开 `.garden/ui-catalog.html`。清单里的「用它开始」把配方插进当前稿件，适合已经知道要用哪一种组件的时候。
-4. **编译。** 「复制编译提示词」。中文站点得到 `编译这篇：<相对路径>`，英文站点得到 `Compile this post: <相对路径>`。把这句话发给 `garden-ui` skill。Agent 用 `npx garden ui scan` 定位，用 `npx garden ui prompt` 读规则，用 `npx garden ui apply` 写回。插件不调用模型。
+4. **编译。** 「复制编译提示词」。中文站点得到 `编译这篇：<相对路径>`，英文站点得到 `Compile this post: <相对路径>`。把这句话发给 `garden-compose` skill。Agent 用 `npx garden ui scan` 定位，用 `npx garden ui prompt` 读规则，用 `npx garden ui apply` 写回。插件不调用模型。
 
 **Typora 的前提。** 先安装 [typora-community-plugin](https://github.com/typora-community-plugin/typora-community-plugin/blob/main/docs/en-us/user-guide/1a-installation.md)。`npx garden editors install --typora` 把插件复制到 `~/.typora/community-plugins/plugins/hedon954.garden-intelligent-ui/`（macOS 同时写到 `~/Library/Application Support/abnerworks.Typora/plugins/plugins/hedon954.garden-intelligent-ui/`），然后在「设置 → 已安装插件」里勾选 Garden Intelligent UI。升级 Typora 会覆盖社区框架，需要重装框架后再勾选。没找到 `code` 或 `cursor` 时，用扩展视图的 Install from VSIX 选择 `.garden/editors/vscode/` 里的文件。安装细节见 [语法检查与快捷输入](/garden/workflow)。
 
@@ -113,7 +110,7 @@ npx garden editors install --typora
 不借助 AI 手写组件时，可以直接使用包内自带的模板与代码片段：
 
 - `make new` 创建的草稿底部自带一段 `<!-- 组件速查 ... -->` 注释，包含想法块和各个组件的示例，写完可直接删掉。
-- `templates/garden-blocks.md` 汇总了想法块与各个组件的适用场景（`when` / `whenNot`）和可复制示例；macOS 与 Typora / Alfred 用户可导入 `templates/garden-snippets.plist`，输入 `;gidea`（或 `;garden想法`）、`;gcard`、`;gstat`、`;gcompare`、`;gtimeline`、`;gchart`、`;gcompose`、`;ghtml`、`;ginteractive`、`;gfile`、`;grel`、`;glist`、`;gchoice` 即可展开对应围栏。`;gcompose` 展开的是带一句白话的 `garden compose`。
+- `templates/garden-blocks.md` 提供统一 Compose 入口的示例；macOS 与 Typora / Alfred 用户可导入 `templates/garden-snippets.plist`，输入 `;gcompose` 展开带一句白话的 Compose 围栏。
 - 编辑器插件的用法见上一节。`npx garden ui catalog` 在本地生成 `.garden/ui-catalog.html` 离线组件画廊。
 
 ## 8. 可选的独立管理后台

package/docs/handbook/components/compose.md

@@ -1,17 +1,19 @@
 ---
-title: 说明图（compose）
-navTitle: 说明图
-description: 在文章里写几句白话，让 AI 拼出静态说明图。
+title: 内容、布局与交互（compose）
+navTitle: Compose
+description: 在同一个作者入口组合文章内容、布局、资源与交互。
 section: components
 order: 36
 badge: compose
 ---
 
-写文章想画一张结构图时，输入 `/garden` 选「compose（想法）」。文章里会插入一个 `garden compose` 围栏。你在里面用白话写清结构，再对 AI 说「编译这篇」，AI 就会把这句话留在 `<intent>` 里，并用 Markdown 叶子和组件标签拼出静态说明图。
+`garden compose` 是唯一的 Garden 作者入口。在围栏内组合 Markdown、安全 HTML 内容岛、布局、资源、文件、关系图、选择卡与 Play 交互。具体能力、内容边界和默认样式见[组件参考](/garden/reference/compose)，完整可用属性以 `npx garden ui schema` 为准。
+
+需要 AI 生成结构图时，输入 `/garden` 选「compose（想法）」。文章里会插入一个 `garden compose` 围栏。你在里面用白话写清结构，再对 AI 说「编译这篇」，AI 就会把这句话留在 `<intent>` 里，并用 Markdown 叶子和组件标签拼出静态说明图。
 
 ## 怎么写
 
-围栏里只写你想让读者看见的结构，不要写样式。
+先说明读者应当看见的关系和层级，再选择布局与必要样式。也可以直接写组件；不要把通用 HTML/CSS 当成所有组件的属性契约。
 
 把四件事写清楚：
 
@@ -20,7 +22,7 @@ badge: compose
 - **谁连谁**：谁先到谁、从一处散开，还是几处收到一起。没有先后顺序，就直接写「这几块没有先后」。
 - **哪块是重点**：直接点名，比如「中间那列是重点」「下面一行才是重点」。
 
-不要写颜色、圆角、灰胶囊、字重、间距、阴影、要不要撑满。外观由组件默认样式决定，写了反而乱。
+先说明视觉关系与重点，再使用受支持的属性表达必要样式。默认样式不保证复刻参考图，必须检查真实排版。
 
 **完整标签与属性**见 [组件参考 · compose](/garden/reference/compose)；**全部图标名**见 [compose 图标](/garden/reference/compose-icons)。
 
@@ -120,7 +122,7 @@ Role 在中间，把用户和权限接起来。Role 是重点。
 - `{#if …}{:else}{/if}`、`{#each … as item, i}{/each}` 控制流
 - 小写控件：`<slider>`、`<choice>`、`<button>`、`<pie>` / `<chart>`、`<stat>`
 
-旧的 `garden interactive` 与 PascalCase 仅作兼容。完整映射见仓库 `docs/compose-dil.md`。
+作者标签使用小写目录；`@body` 声明状态，不写内部组件 IR。完整语法见仓库 `docs/compose-dil.md`。
 
 ```garden compose #compose-play-demo
 caption: 拧一下席位，看月费。
@@ -202,3 +204,10 @@ intent: |
 <stat label="预测最佳时间" value={best} />
 ```
 
+
+## 自定义文字与背景颜色
+
+`color` 设置文字颜色（子内容继承，可在子级覆盖）；`backgroundColor` 设置当前容器背景（不继承）。支持 CSS 命名色、`transparent`、`currentColor`、#RGB/#RGBA/#RRGGBB/#RRGGBBAA、rgb()/rgba()/hsl()/hsla()（含 alpha）；不接受 url()、var()、calc()、任意 CSS 声明或 style。未指定时保留原 tone / 主题配色。背景可用透明度，不改变字体家族。
+
+静态：box/card、row/stack/columns/grid/grid-item、pill/band、group/field/header/footer/figure、title/text/caption/label/prose/badge、kpi/stat、list、table/tr/th/td/thead/tbody。Play：stack/columns/card/caption/badge/stat/table；两项颜色必须写字面量。静态的 `background` 仍是已有语义 token。图表的 palette/tone API 不变，不能把 color 当系列颜色。显式颜色不会自动切换深色主题，作者需检查对比度。
+

package/docs/handbook/components/image.md

@@ -9,7 +9,7 @@ order: 45
 图片单独成段时会包进图框，并在下方显示图注。
 
 - **什么时候用**：这张图属于文章，读者需要看到图下说明。
-- **什么时候不用**：只是装饰时，把 `alt` 写成以 `image`、`截图` 或 `img` 开头的占位词，这样不会出现图注。要按部分点开说明时用[说明图](/garden/components/compose)；要提供下载时用[文件下载与预览](/garden/components/file)。
+- **什么时候不用**：只是装饰时，把 `alt` 写成以 `image`、`截图` 或 `img` 开头的占位词，这样不会出现图注。要按部分点开说明时用[说明图](/garden/components/compose)；要提供下载时用[文件下载与预览](/garden/components/compose)。
 
 长文 `content/posts/my-post.md` 的配图放在同名目录 `content/posts/my-post/`。正文用 Markdown 图片语法引用，地址写成 `./my-post/diagram.svg`，方括号里的 `alt` 写成图注。
 

package/docs/handbook/components/link-card.md

@@ -9,7 +9,7 @@ order: 43
 单独占一段的网址，或链接末尾紧跟 `{card}`，会渲染成链接卡片（同站与外站同一套逻辑）。正文里带标题的普通链接不会变成卡片，例如 [Typora](https://typora.io/)：外站只在文字前加站点 Favicon，右上角标 `↗`，图标与第一个字留在同一行；同站标题链接仍在站内跳转。
 
 - **什么时候用**：希望读者点开之前先看到网站名、标题和简介。
-- **什么时候不用**：句子里只要标出出处时用[来源胶囊](/garden/components/source)；要自己写几条要点时用[知识卡片](/garden/components/card)。
+- **什么时候不用**：句子里只要标出出处时用[来源胶囊](/garden/components/source)；要自己写几条要点时用[知识卡片](/garden/components/compose)。
 
 ## 单独一行的网址
 
@@ -43,7 +43,7 @@ https://spec.commonmark.org/
 
 `{card}` 写在代码里会原样显示，例如 `[文字](https://example.com){card}`。标记和 `)` 之间有空格时也不会变成卡片。同站与外站的跳链共用同一套卡片路径。
 
-构建时读取正文里的 `{card}` 链接，以及单独成段的网址，把对方页面的标题、简介和封面记入 `link-assets.json`（同站与外站同一套抓取；HTML meta refresh 会跟着跳到目标页再读 OG）。抓取失败就沿用上次的结果，构建不会因此中断。只刷新这些信息时运行 `npx garden links`。离线构建时把 `GARDEN_OFFLINE` 设为 `1` 会跳过拉取。
+构建时读取正文里的 `{card}` 链接，以及单独成段的网址，把对方页面的标题、简介和封面记入 `.garden/link-assets.json`（同站与外站同一套抓取；HTML meta refresh 会跟着跳到目标页再读 OG）。抓取失败就沿用上次的结果，构建不会因此中断。只刷新这些信息时运行 `npx garden links`。离线构建时把 `GARDEN_OFFLINE` 设为 `1` 会跳过拉取。
 
 随想 Front Matter 里的 `type: link` 用你写的 `title`、`description` 和 `image`，字段见[写文章与随想](/garden/writing)。
 

package/docs/handbook/components.md

@@ -1,221 +1,13 @@
 ---
 title: 组件总览
 navTitle: 组件总览
-description: garden 围栏的效果预览，以及链接卡片、来源胶囊和本地图片。
+description: 组件总览
 section: components
 order: 30
 ---
 
-## [知识卡片 · card](/garden/components/card)
+文章布局、富文本、语义场景与交互说明统一使用一个 `garden compose` 围栏。在入口内部选择并组合组件；普通 Markdown 已能表达清楚时不用增加组件。
 
-```garden card
-title: SQLite WAL 写入模式
-url: https://www.sqlite.org/wal.html
-meta: 文档说明 · sqlite.org
-description: 把修改先顺序追加到预写日志，读操作继续访问原数据库页，减少读写互斥等待。
-points:
-  - 写入只追加到 `-wal` 文件末尾，不需要在事务提交时原地覆盖数据页。
-  - 读事务记录当前末尾偏移量即可看到一致快照，不会阻塞并发写入。
-```
-
-## [数字指标 · stat](/garden/components/stat)
-
-```garden stat
-items:
-  - label: 正文列宽
-    value: "740"
-    unit: px
-    caption: 默认阅读列宽度
-  - label: 宽图上限
-    value: "1040"
-    unit: px
-    caption: 左右各最多外扩 150px
-  - label: 宽表上限
-    value: "1340"
-    unit: px
-    caption: 左右各最多外扩 300px
-```
-
-## [并排对比 · compare](/garden/components/compare)
-
-```garden compare
-items:
-  - title: 写一句话说明改了什么
-    text: 想法块紧跟在完整代码下面，AI 把它换成 diff，页面合成「代码 / 对比上一版」。
-  - title: 手写 diff
-    text: 完整代码下面紧跟一段 diff。
-```
-
-## [时间线 · timeline](/garden/components/timeline)
-
-```garden timeline
-items:
-  - date: 步骤 1
-    title: 同步内容与静态资源
-    text: 校验 Front Matter、复制图片附件并生成搜索索引与 RSS。
-  - date: 步骤 2
-    title: 构建静态站点产物
-    text: 把全部路由预渲染到静态目录。
-```
-
-## [条形图表 · chart](/garden/components/chart)
-
-```garden chart
-title: 三种版面区域的宽度上限
-xLabel: 版面区域
-yLabel: 最大宽度
-unit: px
-data:
-  - x: 普通正文列
-    y: 740
-  - x: 宽幅配图区
-    y: 1040
-  - x: 多列宽表格
-    y: 1340
-```
-
-## [说明图 · compose](/garden/components/compose)
-
-```garden compose
-<intent>
-上面一行是交付顺序：理解需求、设计方案、开发上线。下面一行才是要强调的决策循环：提出假设、低成本验证、迭代或放弃。上面是背景，下面是重点。
-</intent>
-<row align="center">
-  <title align="center">理解需求</title>
-  <arrow dir="right"/>
-  <title align="center">设计方案</title>
-  <arrow dir="right"/>
-  <title align="center">开发上线</title>
-</row>
-<divider/>
-<row align="center">
-  <pill tone="muted">提出假设</pill>
-  <arrow dir="right"/>
-  <pill tone="muted">低成本验证</pill>
-  <arrow dir="right"/>
-  <pill tone="muted">迭代或放弃</pill>
-</row>
-```
-
-## [嵌入网页片段 · html](/garden/components/html)
-
-```garden html
-title: 字符长度小工具
-code: |
-  <!doctype html>
-  <html lang="zh-CN">
-  <head>
-    <meta charset="utf-8" />
-    <style>
-      body { margin: 0; padding: 16px 18px; font: 14px/1.6 system-ui, sans-serif; color: #1b1a18; background: #faf9f5; }
-      input { width: 100%; box-sizing: border-box; padding: 8px 10px; border: 1px solid #d5d1c8; border-radius: 6px; font: inherit; background: #fff; color: #1b1a18; }
-      .meta { margin-top: 10px; color: #6e6b64; font-variant-numeric: tabular-nums; }
-      strong { color: #1b1a18; }
-    </style>
-  </head>
-  <body>
-    <input id="txt" value="把文章放在自己的 Git 仓库里，推送后自动构建。" aria-label="输入示例文本" />
-    <div class="meta">当前字符数：<strong id="count">23</strong> 字</div>
-    <script>
-      const input = document.getElementById("txt");
-      const count = document.getElementById("count");
-      input.addEventListener("input", () => { count.textContent = String(input.value.length); });
-    </script>
-  </body>
-  </html>
-```
-
-## [可调公式与参数 · interactive](/garden/components/interactive)
-
-```garden compose #overview-reading
-caption: 示例：按字数和阅读速度估算阅读时间。
----
-<State words={6000} speed={400} />
-<Let minutes={round(words / speed)} />
-
-<Slider bind="words" label="正文字数" min={1000} max={20000} step={500} unit="字" />
-<Slider bind="speed" label="阅读速度" min={200} max={800} step={50} unit="字/分钟" />
-
-<Stat label="预计阅读时间" value={minutes} unit="分钟" />
-```
-
-## [文件下载与预览 · file](/garden/components/file)
-
-```garden file
-src: ./components/file/checklist.md
-title: 发布前检查清单
-note: 可点击「预览」在当前页展开阅读，或直接下载原文件
-```
-
-## [关系图 · relations](/garden/components/relations)
-
-```garden relations
-items:
-  - title: 选书
-    text: 定下这个月读什么
-  - title: 共读
-    text: 每周读完约定的章节
-  - title: 讨论
-    text: 见面聊各自的看法
-  - title: 复盘
-    text: 记下下次要改的地方
-links:
-  - from: 1
-    to: 2
-  - from: 2
-    to: 3
-  - from: 3
-    to: 4
-  - from: 4
-    to: 1
-  - from: 3
-    to: 1
-    style: dashed
-    label: 影响选书
-```
-
-## [图标列表 · list](/garden/components/list)
-
-```garden list
-items:
-  - icon: search
-    text: 搜索这个月的书名
-  - icon: eye
-    text: 看了 3 篇书评
-  - icon: heart
-    text: 收藏了活动页面
-  - icon: chat
-    text: 在群里问能不能只听不说
-```
-
-## [选择卡 · choice](/garden/components/choice)
-
-```garden choice
-title: 下个月在哪里见面？
-items:
-  - icon: idea
-    value: ¥40 / 人
-    text: 街角咖啡馆，含一杯饮料
-    label: 更看重氛围
-    reply: 选了咖啡馆。我们会提前订好靠窗的长桌。
-  - icon: book
-    value: 免费
-    text: 社区图书馆活动室，需提前预约
-    label: 更看重安静
-    reply: 选了图书馆。我们会在月初提交预约。
-none:
-  label: 都不合适 / 说不清
-  reply: 没关系，我们会在群里再列几个场地。
-```
-
-## [链接卡片 · {card}](/garden/components/link-card)
-
-[KaTeX 支持的函数](https://katex.org/docs/supported.html){card}
-
-## [来源胶囊 · {source}](/garden/components/source)
-
-引自维基百科 [wikipedia.org](https://en.wikipedia.org/wiki/Book_discussion_club){source}
-
-## [本地图片](/garden/components/image)
-
-![正文列、宽图区与宽表区](./assets/reading-layout.svg)
+- [Compose](/garden/components/compose)
+- [Compose reference](/garden/reference/compose)
+- [Icons](/garden/reference/compose-icons)

package/docs/handbook/deploy.md

@@ -38,6 +38,17 @@ jobs:
     steps:
       - uses: actions/checkout@v7
 
+      - name: Restore generated Garden caches
+        uses: actions/cache@v4
+        with:
+          path: |
+            .garden/image-sizes.json
+            .garden/link-assets.json
+            public/link-assets
+          key: ${{ runner.os }}-garden-generated-v1-${{ github.ref_name }}-${{ github.run_id }}
+          restore-keys: |
+            ${{ runner.os }}-garden-generated-v1-${{ github.ref_name }}-
+
       - uses: actions/setup-node@v7
         with:
           node-version: 22

package/docs/handbook/en/ai-writing.md

@@ -13,24 +13,23 @@ You do not need to memorize component tags to add charts, metrics, or interactiv
 
 ## 1. Write a One-sentence Idea
 
-Place an unnamed `garden` fence where the component belongs and state what the reader should do and see, without naming a component:
+Place a `garden compose` fence where the component belongs and state what the reader should do and see, without naming a component:
 
 ````markdown
-```garden
+```garden compose
 Let the reader drag daily word count and writing days per week to see how many weeks an 8,000-word article takes.
 ```
 ````
 
-Draft posts (`draft: true`) may keep uncompiled idea fences; in non-draft posts, both `npx garden ui check` and `npx garden check` report a `garden-idea` error. Depending on the content, the Agent compiles the idea into a built-in component (`garden compose`, `card`, `stat`, `compare`, and others) or replaces it with plain prose when a paragraph is clearer.
+Uncompiled requests use the same `garden compose` entry. Both `npx garden ui check` and `npx garden check` report `compose-uncompiled`, including in drafts. The Agent composes prose, resources, graphics and interactions inside Compose, or replaces the request with plain prose when that is clearer.
 
-## 2. Three Bundled Skills
+## 2. Two Bundled Skills
 
-Three skills live in `.agents/skills/` at the root of the site repository. `npx hd-garden init` installs them when creating a site, the first `npx garden sync` or `npx garden dev` fills in any missing skill files, and `npx garden skill` reinstalls them on demand.
+Two skills live in `.agents/skills/` at the root of the site repository. `npx hd-garden init` installs them when creating a site, the first `npx garden sync` or `npx garden dev` recursively updates managed skill files, backing up local edits under `.garden/skill-backups/`, and `npx garden skill` reinstalls them on demand.
 
 | Skill Name | Example Trigger Prompt | What It Does |
 | :--- | :--- | :--- |
-| `garden-ui` | "Compile this post: content/posts/writing-pace.md", "Recompile writing-pace", or pasting a fix prompt | Scans `uncompiled`, `stale`, and `error` blocks, generates components, and writes them back via `npx garden ui apply`; asking where interactive blocks fit runs read-only suggestion mode and returns up to 5 ready-to-paste idea fences |
-| `garden-interactive-chart` | Canvas animations or simulations beyond the built-in component catalog | Writes a standalone `.html` file inside the post's sidecar directory and embeds it in the post with a `garden html` fence |
+| `garden-compose` | "Compile this post: content/posts/writing-pace.md", "Recompile writing-pace", or pasting a fix prompt | Scans `uncompiled` and `error` blocks, generates components, and writes them back via `npx garden ui apply`; asking where interactive blocks fit runs read-only suggestion mode and returns up to 5 ready-to-paste idea fences |
 | `garden-post-review` | "Review post: content/posts/writing-pace.md" | Fixes structural errors reported by `npx garden check`, repairs interactive blocks against the chart rules, and reads the full post to offer editorial suggestions without rewriting prose |
 
 ## 3. `garden ui` Subcommands and Post Checks
@@ -49,19 +48,17 @@ Authors and Agents run the same `garden ui` subcommands; when an idea fence has
 
 ## 4. Pre-commit Hook and Fix Prompts
 
-On the first `npx garden sync` or `npx garden dev` run, Garden writes `exec npx --no-install garden ui check --staged --quiet` to `.git/hooks/pre-commit` (if a custom hook already exists, it leaves the file untouched and prints the line to add). `--staged` reads staged content directly via `git show :<path>` and, on failure, prints the line numbers, diagnostic codes, and a fix prompt:
+On the first `npx garden sync` or `npx garden dev` run, Garden writes `exec npx --no-install garden ui check --staged --quiet` to `.git/hooks/pre-commit` (if a custom hook already exists, it leaves the file untouched and prints the line to add). `--staged` reads staged content directly via `git show :<path>` and, on failure, prints line numbers, diagnostic codes, and a short instruction to load the project skill:
 
 ```console
-content/posts/writing-pace.md:9  -  garden-idea  uncompiled idea remaining
+content/posts/writing-pace.md:9  -  compose-uncompiled  uncompiled compose idea remaining
 
-──────────────────────── Fix prompt for AI ────────────────────────
-Handle the Garden post blocks listed below: compile uncompiled ideas, and fix interactive blocks that have errors.
-……
+Use garden-compose skill (.agents/skills/garden-compose/SKILL.md), fix the failing blocks, then recheck.
 ```
 
-- The prompt is written to `.garden/ui-fix-prompt.md` and copied to the clipboard when `pbcopy`, `wl-copy`, `xclip`, `xsel`, or `clip` is available; pass `--no-copy` or set `GARDEN_UI_NO_COPY=1` to disable clipboard copying.
-- When pasting into a web chat that cannot read your local repository, run `npx garden ui check <post.md> --standalone` to append the full `npx garden ui prompt` rules to the prompt (including source fences for up to 10 failing blocks).
-- A misspelled tag inside an interactive block (such as `<Slidr>` instead of `<Slider>`) reports `ui-component` with its exact line number; to commit anyway, run `git commit --no-verify`.
+- Defaults show file/line/error diagnostics and a short instruction to load the project `garden-compose` skill. No file is written, no clipboard access occurs, and no model is called. Existing prompt files are untouched.
+- Only when a self-contained export is required, run `npx garden ui check <post.md> --out .garden/export.md --standalone`. `--standalone` enriches that explicit export; alone it does not create a file.
+- A misspelled tag inside an interactive block (such as `<Slidr>` instead of `<Slider>`) reports `ui-component` with its exact line number.
 - Run `npx garden hooks` to reinstall the hook (pass `--force` to overwrite an existing hook), or set `GARDEN_SKIP_HOOKS=1` to skip automatic hook installation.
 
 ## 5. Generate a Code Diff from One Sentence
@@ -75,12 +72,12 @@ pages:
     title: "Write in Markdown | Push to Update the Site"
 ```
 
-```garden
+```garden compose
 Compared with the previous version: split the title into two lines with " | " instead of a period and newline.
 ```
 ````
 
-Following the `garden-ui` skill, the Agent replaces that idea fence with a `diff` fence right below the code block. The page merges the adjacent code and `diff` fences into a single code frame with a toggle between the full code and the diff; see [Writing Posts & Thoughts](/garden/en/writing) for the hand-written `diff` format.
+Following the `garden-compose` skill, the Agent replaces that idea fence with a `diff` fence right below the code block. The page merges the adjacent code and `diff` fences into a single code frame with a toggle between the full code and the diff; see [Writing Posts & Thoughts](/garden/en/writing) for the hand-written `diff` format.
 
 ## 6. Insert, Preview, and Compile from the Editor
 
@@ -95,10 +92,10 @@ npx garden editors install --typora
 
 A component then takes four steps:
 
-1. **Insert an idea.** Where the component should go, run the Garden insert command (`Cmd+Alt+I` on macOS, `Ctrl+Alt+I` on Windows and Linux in VS Code / Cursor). In Typora, type `/` and choose `/garden` to open a picker with a small preview image on each row; the command shortcut is `Ctrl+Alt+I` on Windows and Linux, and macOS needs a shortcut recorded under Settings, Keyboard Shortcuts. The insertion is a plain `garden` fence whose body tells the `garden-ui` skill which component to compile and which facts to include.
+1. **Insert an idea.** Where the component should go, run the Garden insert command (`Cmd+Alt+I` on macOS, `Ctrl+Alt+I` on Windows and Linux in VS Code / Cursor). In Typora, type `/` and choose `/garden` to open a picker with a small preview image on each row; the command shortcut is `Ctrl+Alt+I` on Windows and Linux, and macOS needs a shortcut recorded under Settings, Keyboard Shortcuts. The insertion is a plain `garden` fence whose body tells the `garden-compose` skill which component to compile and which facts to include.
 2. **Preview.** Open the Markdown preview, or in Typora move the cursor out of the fence. An `intent` block shows as an idea card. After the skill writes a `ui` block, the preview matches the blog. VS Code / Cursor also report errors in Problems and in the CodeLens above the block.
 3. **Open the catalog.** Use the catalog command, or run `npx garden ui catalog` and open `.garden/ui-catalog.html`. Starting from a recipe inserts it at the cursor when you already know which component you want.
-4. **Compile.** Copy the compile prompt. On an English site the clipboard text is `Compile this post:` plus the post path. Paste it to the `garden-ui` skill. The Agent locates the block with `npx garden ui scan`, reads the rules with `npx garden ui prompt`, and writes it back with `npx garden ui apply`. The plugin does not call a model.
+4. **Compile.** Copy the compile prompt. On an English site the clipboard text is `Compile this post:` plus the post path. Paste it to the `garden-compose` skill. The Agent locates the block with `npx garden ui scan`, reads the rules with `npx garden ui prompt`, and writes it back with `npx garden ui apply`. The plugin does not call a model.
 
 **Typora prerequisite.** Install [typora-community-plugin](https://github.com/typora-community-plugin/typora-community-plugin/blob/main/docs/en-us/user-guide/1a-installation.md) first. `npx garden editors install --typora` copies the plugin to `~/.typora/community-plugins/plugins/hedon954.garden-intelligent-ui/`. On macOS it also copies to `~/Library/Application Support/abnerworks.Typora/plugins/plugins/hedon954.garden-intelligent-ui/`. Enable Garden Intelligent UI under Settings, Installed plugins. A Typora upgrade overwrites the community framework; reinstall the framework, then enable the plugin again. If `code` or `cursor` is not on `PATH`, use Install from VSIX in the Extensions view and select the file under `.garden/editors/vscode/`. Install details are in [Checks & Shortcuts](/garden/en/workflow).
 
@@ -107,7 +104,7 @@ A component then takes four steps:
 When writing components by hand without AI, you can use the templates and snippets shipped in the package:
 
 - Every draft created by `make new` includes an HTML comment at the bottom with copy-ready examples for idea fences and the built-in components; delete the comment whenever you are done.
-- `templates/garden-blocks.md` lists `when` / `whenNot` guidance and copyable templates for every block; macOS, Typora, and Alfred users can import `templates/garden-snippets.plist` to expand `;gidea`, `;gcard`, `;gstat`, `;gcompare`, `;gtimeline`, `;gchart`, `;gcompose`, `;ghtml`, `;ginteractive`, `;gfile`, `;grel`, `;glist`, and `;gchoice`. `;gcompose` expands to a `garden compose` fence with one sentence.
+- `templates/garden-blocks.md` supplies examples for the single Compose entry. macOS, Typora and Alfred users can import `templates/garden-snippets.plist` and expand `;gcompose` to a Compose fence containing one author sentence.
 - Editor plugin usage is in the previous section. `npx garden ui catalog` writes an offline component catalog at `.garden/ui-catalog.html`.
 
 ## 8. Optional Standalone Admin

package/docs/handbook/en/components/compose.md

@@ -1,17 +1,19 @@
 ---
-title: Diagrams (compose)
-navTitle: Diagrams
-description: Write a short plain-language structure; AI compiles it into a static diagram.
+title: Content, layout, and interactions (compose)
+navTitle: Compose
+description: Combine article content, layout, resources, and interactions through one author entry.
 section: components
 order: 36
 badge: compose
 ---
 
-To draw a structure diagram in a post, type `/garden` and pick **compose (idea)**. That inserts a `garden compose` fence. Write the structure in plain language, then ask the AI to compile the post. It keeps your words in `<intent>` and builds the diagram from Markdown leaves plus catalog tags.
+`garden compose` is the single Garden author entry. Inside it, combine Markdown, safe HTML content islands, layout, resources, files, relations, selectable cards, and Play interactions. See the [component reference](/garden/en/reference/compose) for capabilities, content boundaries, and contextual defaults; `npx garden ui schema` is authoritative for supported fields.
+
+To ask AI for a structure diagram, type `/garden` and pick **compose (idea)**. That inserts a `garden compose` fence. Write the structure in plain language, then ask the AI to compile the post. It keeps your words in `<intent>` and builds the diagram from Markdown leaves plus catalog tags.
 
 ## How to write
 
-Describe the structure readers should see. Do not prescribe styles.
+Describe the relationships and hierarchy readers should see before choosing layout and necessary styles. You can also write components directly; do not assume every component accepts arbitrary HTML/CSS properties.
 
 Cover four things:
 
@@ -20,7 +22,7 @@ Cover four things:
 - **What connects to what**: who reaches whom, fans out, or joins. If there is no order, say so.
 - **Which block is the focus**: name it (“the middle column”, “the lower row”).
 
-Do not specify colors, radii, pill chrome, weight, gaps, shadows, or full-bleed. Defaults own appearance.
+Describe the visual relationships and desired emphasis. Defaults are a starting point, not a substitute for checking alignment and hierarchy. Explicit styling must use supported controls.
 
 **Every tag and shared token**: [compose reference](/garden/en/reference/compose). **Every icon name**: [compose icons](/garden/en/reference/compose-icons).
 
@@ -189,3 +191,10 @@ intent: |
 <stat label="Predicted best time" value={best} />
 ```
 
+
+## Custom text and background colors
+
+`color` controls text (inherited; children may override). `backgroundColor` paints only the current surface (not inherited). Both accept literal CSS named colors, transparent/currentColor, 3/4/6/8-digit hex, rgb/rgba/hsl/hsla with optional alpha. URLs, var(), calc(), declarations and arbitrary style are rejected by the same SSR/browser validator. Defaults preserve tone and theme; no font-family change. Explicit colors are not automatically dark-mode adapted: check contrast.
+
+Static primitives: box/card, row/stack/columns/grid/grid-item, pill/band, group/field/header/footer/figure, title/text/caption/label/prose/badge, kpi/stat, list, table/tr/th/td/thead/tbody. Play: stack/columns/card/caption/badge/stat/table. Colors must be literals. Existing static `background` semantic tokens and chart palette/series-tone APIs are unchanged; these props do not set chart series colors.
+

package/docs/handbook/en/components/image.md

@@ -9,7 +9,7 @@ order: 45
 An image that is its own paragraph is wrapped in a figure, with a caption underneath.
 
 - **When to use**: The figure belongs in the article, and the reader should see a caption under it.
-- **When to skip**: For a decorative image, start the alt text with `image` or `img` so there is no caption. Use an [explanation diagram](/garden/en/components/compose) when each step needs its own note, or [file download](/garden/en/components/file) when the reader should download the file.
+- **When to skip**: For a decorative image, start the alt text with `image` or `img` so there is no caption. Use an [explanation diagram](/garden/en/components/compose) when each step needs its own note, or [file download](/garden/en/components/compose) when the reader should download the file.
 
 For a post at `content/posts/my-post.md`, put images in `content/posts/my-post/`. Reference them with Markdown image syntax, with the address `./my-post/diagram.svg` and the caption in the alt text.
 

package/docs/handbook/en/components/link-card.md

@@ -9,7 +9,7 @@ order: 43
 A URL on its own paragraph, or a link followed immediately by `{card}`, renders as a link card (same-site and external share one path). An ordinary titled link in prose stays a link, such as [Typora](https://typora.io/): an external one shows the site favicon before the text and a `↗` at the upper right; a titled same-site link still navigates in place.
 
 - **When to use**: The reader should see the site name, title, and summary before opening the page.
-- **When to skip**: Use a [source chip](/garden/en/components/source) to cite a site inside a sentence, or a [reference card](/garden/en/components/card) when you are writing the takeaways yourself.
+- **When to skip**: Use a [source chip](/garden/en/components/source) to cite a site inside a sentence, or a [reference card](/garden/en/components/compose) when you are writing the takeaways yourself.
 
 ## A URL on its own line
 
@@ -43,7 +43,7 @@ When the paragraph is only the marked link, that line becomes the card:
 
 `{card}` inside code stays as written, for example `[text](https://example.com){card}`. A space between `)` and the marker also leaves an ordinary link. Same-site and external jump links share one card path.
 
-At build time, Garden reads `{card}` links and URLs that stand alone as a paragraph, and stores the page title, summary, and image in `link-assets.json` (same-site and external share one fetch path; HTML meta refresh is followed to the target before reading OG). A failed fetch keeps the previous record, and the build continues. Run `npx garden links` to refresh just these records. Set `GARDEN_OFFLINE` to `1` to skip the fetch during an offline build.
+At build time, Garden reads `{card}` links and URLs that stand alone as a paragraph, and stores the page title, summary, and image in `.garden/link-assets.json` (same-site and external share one fetch path; HTML meta refresh is followed to the target before reading OG). A failed fetch keeps the previous record, and the build continues. Run `npx garden links` to refresh just these records. Set `GARDEN_OFFLINE` to `1` to skip the fetch during an offline build.
 
 A thought can also carry an external link in Front Matter with `type: link`, using the `title`, `description`, and `image` you write. Those fields are in [Writing Posts & Thoughts](/garden/en/writing).