hd-garden 0.8.0 → 0.8.2

package/docs/handbook/components.md

@@ -1,30 +1,221 @@
 ---
 title: 组件总览
 navTitle: 组件总览
-description: 9 个内置 garden 组件的用途、围栏名称与使用约束。
+description: 12 个内置组件的效果预览。
 section: components
 order: 30
 ---
 
-这 9 个组件都可以先在 `garden` 想法块里用一句话描述，交给 Agent 按 `garden-ui` skill 生成（详见 [用 AI 写作](/garden/ai-writing)）。手写时使用 ```` ```garden <name> ```` 代码块插入，组件名固定为英文（`card`、`stat`、`compare`、`timeline`、`chart`、`figure`、`html`、`interactive`、`file`），参数采用 YAML 格式，`interactive` 则在 `---` 下方编写声明式标签。
+## [知识卡片 · card](/garden/components/card)
 
-## 9 个组件速查表
+```garden card
+title: SQLite WAL 写入模式
+url: https://www.sqlite.org/wal.html
+meta: 文档说明 · sqlite.org
+description: 把修改先顺序追加到预写日志，读操作继续访问原数据库页，减少读写互斥等待。
+points:
+  - 写入只追加到 `-wal` 文件末尾，不需要在事务提交时原地覆盖数据页。
+  - 读事务记录当前末尾偏移量即可看到一致快照，不会阻塞并发写入。
+```
 
-| 组件名 | 代码块围栏 | 适用场景 | 必填字段或下限 |
-| :--- | :--- | :--- | :--- |
-| [知识卡片](/garden/components/card) | ```` ```garden card ```` | 介绍论文、开源项目或模块要点 | 至少填 `description` 或 `points` |
-| [数字指标](/garden/components/stat) | ```` ```garden stat ```` | 并排展示 2～4 组关键数值与单位 | 每项必填 `label` 与 `value` |
-| [并排对比](/garden/components/compare) | ```` ```garden compare ```` | 左右并列对比 2～3 种方案或改动前后差异 | `items` 至少 2 项，每格不超过约 60 字 |
-| [时间线](/garden/components/timeline) | ```` ```garden timeline ```` | 按先后顺序串联排查记录或演进阶段 | `items` 至少 2 项 |
-| [条形图表](/garden/components/chart) | ```` ```garden chart ```` | 用数据绘制比例条形图（自带可展开数据表） | `data` 至少 2 行 |
-| [分区结构图](/garden/components/figure) | ```` ```garden figure ```` | 带分区按钮高亮与说明的 SVG / 图片结构图 | `svg` 或 `image` 二选一 |
-| [嵌入网页片段](/garden/components/html) | ```` ```garden html ```` | 在沙盒 `iframe` 中运行独立 HTML/JS 演示 | `src` 或 `code` 二选一 |
-| [可调公式与参数](/garden/components/interactive) | ```` ```garden interactive ```` | 提供滑杆或单选控件实时计算非平凡公式 | 含输入控件且公式不能是单次乘法 |
-| [文件下载与预览](/garden/components/file) | ```` ```garden file ```` | 提供本地或远程文件下载与页内预览 | `src` 或 `files` 二选一 |
+## [数字指标 · 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
+```
 
-1. **优先使用标准 Markdown**：普通文字说明、有序列表和常规对比表格直接用 Markdown 编写，只有结构化组件能明显提升可读性时才用 `garden` 围栏。
-2. **不要重复展示同一组数据**：`chart` 组件下方自带「查看数据表」折叠区，同一小节内不需要再重复手写一张相同数据的 Markdown 表格。
-3. **支持行内格式**：各组件的 `text`、`description`、`caption`、`points` 等文本字段均支持行内 `**加粗**`、`` `行内代码` `` 和 `<u>荧光笔下划线</u>`。
-4. **本地预览全部组件样式**：运行 `npx garden ui catalog` 会在 `.garden/ui-catalog.html` 生成组件画廊页面，可在浏览器中直接打开查看。
+## [并排对比 · 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
+```
+
+## [分区结构图 · figure](/garden/components/figure)
+
+```garden figure
+svg: |
+  <svg viewBox="0 0 560 194" xmlns="http://www.w3.org/2000/svg" font-family="var(--sans)" style="max-width: 380px; margin-inline: auto">
+    <rect data-p="sync" x="2" y="4" width="180" height="186" rx="16" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="2.5"/>
+    <text data-p="sync" x="92" y="42" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">1. garden</text>
+    <text data-p="sync" x="92" y="72" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">sync</text>
+    <text data-p="sync" x="92" y="108" text-anchor="middle" font-size="24" fill="var(--muted)">解析</text>
+    <text data-p="sync" x="92" y="137" text-anchor="middle" font-size="24" fill="var(--muted)">Markdown 与</text>
+    <text data-p="sync" x="92" y="166" text-anchor="middle" font-size="24" fill="var(--muted)">图片尺寸</text>
+    <path d="M183.5 97 H188.5" stroke="var(--muted)" stroke-width="2.5"/>
+    <rect data-p="build" x="190" y="4" width="180" height="186" rx="16" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="2.5"/>
+    <text data-p="build" x="280" y="42" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">2. garden</text>
+    <text data-p="build" x="280" y="72" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">build</text>
+    <text data-p="build" x="280" y="108" text-anchor="middle" font-size="24" fill="var(--muted)">生成静态页面</text>
+    <text data-p="build" x="280" y="137" text-anchor="middle" font-size="24" fill="var(--muted)">与搜索索引</text>
+    <path d="M371.5 97 H376.5" stroke="var(--muted)" stroke-width="2.5"/>
+    <rect data-p="validate" x="378" y="4" width="180" height="186" rx="16" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="2.5"/>
+    <text data-p="validate" x="468" y="42" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">3. pages:</text>
+    <text data-p="validate" x="468" y="72" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">validate</text>
+    <text data-p="validate" x="468" y="108" text-anchor="middle" font-size="24" fill="var(--muted)">检查导出目录</text>
+  </svg>
+parts:
+  - id: sync
+    label: 1. 同步内容
+    text: 扫描正文与附件，生成站点数据。
+  - id: build
+    label: 2. 构建页面
+    text: 预渲染所有页面路由，输出 RSS、sitemap 与搜索文件。
+  - id: validate
+    label: 3. 导出校验
+    text: 确认导出目录结构完整。
+```
+
+## [嵌入网页片段 · 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 interactive #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: 没关系，我们会在群里再列几个场地。
+```

package/docs/handbook/config.md

@@ -43,6 +43,8 @@ pages:
   thoughts:
     title: 随想
     subtitle: 短笔记、图片和链接。
+    # 每屏显示多少条，往下读时自动加载下一屏。默认 10。
+    # pageSize: 10
   columns:
     title: 专栏
     subtitle: 按顺序读的一组文章。
@@ -75,7 +77,7 @@ footer: 持续记录。
 | `name` | 站点名称，显示在左上角导航栏、浏览器标题后缀与 RSS 订阅源标题 |
 | `tagline` | 站点副标题 |
 | `description` | 站点简介，用于首页 SEO 描述与 RSS 频道描述 |
-| `locale` | 语言与地区标识，默认写 `zh_CN`（下划线格式） |
+| `locale` | 语言与地区标识，默认写 `zh_CN`（下划线格式）；设为 `en_US` 时，全站框架文案（导航、首页、文章列表、文章元信息与永久链接、Giscus 评论提示、标签、专栏、关于页、404 页面、分页、RSS/sitemap 与 meta/og）会在构建时切换为英文 |
 | `url` | 站点的公开完整网址（如 `https://blog.example.com`）。配置后，文章里指向该地址的完整链接会自动按站内链接处理 |
 | `author.name` | 作者署名，显示在文章元信息栏、关于页和页脚 |
 | `author.github` | GitHub 用户名（不要写完整网址），用于拼接 GitHub 主页链接及拉取关于页的公开动态 |
@@ -107,7 +109,7 @@ footer: 持续记录。
 columns:
   - slug: building-in-public
     title: 一个人造产品
-    status: 连载中
+    status: ongoing
     description: 从最小闭环到验证发布的完整记录。
     cover: windowsill-herbs.svg
     posts:
@@ -120,6 +122,6 @@ columns:
 | `slug` | 是 | 专栏标识，只能包含小写字母、数字和连字符，生成路由 `/columns/<slug>/<post>` |
 | `title` | 是 | 专栏名称（同时会显示在 `/blog` 文章列表对应文章的右侧） |
 | `description` | 是 | 专栏简介，显示在 `/columns` 列表卡片上 |
-| `status` | 否 | 状态文字（如 `连载中` 或 `已完结`） |
+| `status` | 否 | 状态标识：`default`（或不写，显示为「持续更新」）、`ongoing`（「连载中」）、`completed`（「已完结」）；旧写法 `持续更新`、`连载中`、`已完结` 仍可识别，其他文字按原样显示 |
 | `cover` | 否 | 专栏封面图路径（相对 `content/covers/`） |
 | `posts` | 是 | 按阅读顺序排列的文章路径列表（相对于 `content/posts/`，不带 `.md` 后缀） |

package/docs/handbook/deploy.md

@@ -6,7 +6,7 @@ section: getting-started
 order: 4
 ---
 
-`npx hd-garden init` 不会自动创建 `.github/workflows/pages.yml`。发布到 GitHub Pages 时，在站点仓库新建这个文件。同一份工作流同时支持**单个公开仓库**和**私有源码仓库 + 公开页面仓库**两种模式，按 `PAGES_REPOSITORY` 变量是否为空自动切换。
+默认中文初始化（`npx hd-garden init`）不会自动创建 `.github/workflows/pages.yml`（使用 `--locale en` 或 `--locale en_US` 初始化英文站点时会自动安装英文工作流模板）。发布到 GitHub Pages 时，在站点仓库新建或检查这个文件。同一份工作流同时支持**单个公开仓库**和**私有源码仓库 + 公开页面仓库**两种模式，按 `PAGES_REPOSITORY` 变量是否为空自动切换。
 
 下面的工作流和 Garden 仓库自己的 `.github/workflows/pages.yml` 一致，改动只有两处：一是去掉只对 Garden 仓库有用的 `paths-ignore`、`npm run lint` 和 `npm test`；二是 `publish-repository` 任务先装依赖，再用 `npx garden pages:prepare static-site pages-repository` 写入公开仓库（Garden 仓库里直接调用的是同一个脚本 `scripts/prepare-pages-output.mjs`）。`npm ci` 需要仓库里有 `package-lock.json`，第一次 `npm install` 后记得一起提交。
 

package/docs/handbook/design.md

@@ -36,18 +36,26 @@ Garden 的文章页面围绕长文阅读体验做了几项自动化处理。这
 ```garden figure
 caption: 点击上方按钮查看图片从构建到渲染的三个阶段
 svg: |
-  <svg viewBox="0 0 680 110" xmlns="http://www.w3.org/2000/svg" font-family="var(--sans)">
-    <rect data-p="sync" x="12" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
-    <text data-p="sync" x="110" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">1. 构建期读取尺寸</text>
-    <text data-p="sync" x="110" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">写入 width / height 与 --wl</text>
-    <path d="M214 55 H236" stroke="var(--muted)" stroke-width="1.5"/>
-    <rect data-p="measure" x="242" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
-    <text data-p="measure" x="340" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">2. 客户端测量拓宽</text>
-    <text data-p="measure" x="340" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">按当前视口调整宽图与目录</text>
-    <path d="M444 55 H466" stroke="var(--muted)" stroke-width="1.5"/>
-    <rect data-p="dark" x="472" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
-    <text data-p="dark" x="570" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">3. 深色衬底与灯箱</text>
-    <text data-p="dark" x="570" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">深色垫 #faf9f5 · 点击放大</text>
+  <svg viewBox="0 0 560 194" xmlns="http://www.w3.org/2000/svg" font-family="var(--sans)" style="max-width: 380px; margin-inline: auto">
+    <rect data-p="sync" x="2" y="4" width="180" height="186" rx="16" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="2.5"/>
+    <text data-p="sync" x="92" y="42" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">1. 构建期</text>
+    <text data-p="sync" x="92" y="72" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">读取尺寸</text>
+    <text data-p="sync" x="92" y="108" text-anchor="middle" font-size="24" fill="var(--muted)">写入 width /</text>
+    <text data-p="sync" x="92" y="137" text-anchor="middle" font-size="24" fill="var(--muted)">height 与 --wl</text>
+    <path d="M183.5 97 H188.5" stroke="var(--muted)" stroke-width="2.5"/>
+    <rect data-p="measure" x="190" y="4" width="180" height="186" rx="16" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="2.5"/>
+    <text data-p="measure" x="280" y="42" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">2. 客户端</text>
+    <text data-p="measure" x="280" y="72" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">测量拓宽</text>
+    <text data-p="measure" x="280" y="108" text-anchor="middle" font-size="24" fill="var(--muted)">按当前视口</text>
+    <text data-p="measure" x="280" y="137" text-anchor="middle" font-size="24" fill="var(--muted)">调整宽图</text>
+    <text data-p="measure" x="280" y="166" text-anchor="middle" font-size="24" fill="var(--muted)">与目录</text>
+    <path d="M371.5 97 H376.5" stroke="var(--muted)" stroke-width="2.5"/>
+    <rect data-p="dark" x="378" y="4" width="180" height="186" rx="16" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="2.5"/>
+    <text data-p="dark" x="468" y="42" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">3. 深色衬底</text>
+    <text data-p="dark" x="468" y="72" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">与灯箱</text>
+    <text data-p="dark" x="468" y="108" text-anchor="middle" font-size="24" fill="var(--muted)">深色垫</text>
+    <text data-p="dark" x="468" y="137" text-anchor="middle" font-size="24" fill="var(--muted)">#faf9f5 ·</text>
+    <text data-p="dark" x="468" y="166" text-anchor="middle" font-size="24" fill="var(--muted)">点击放大</text>
   </svg>
 parts:
   - id: sync

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

@@ -86,8 +86,8 @@ Following the `garden-ui` skill, the Agent replaces that idea fence with a `diff
 
 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 all 9 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`, `;gfigure`, `;ghtml`, `;ginteractive`, and `;gfile`.
+- Every draft created by `make new` includes an HTML comment at the bottom with copy-ready examples for idea fences and all 12 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`, `;gfigure`, `;ghtml`, `;ginteractive`, `;gfile`, `;grel`, `;glist`, and `;gchoice`.
 - The engine repository also ships editor integrations under `editors/vscode`, `editors/typora`, and `editors/obsidian`, and `npx garden ui catalog` generates an offline component catalog at `.garden/ui-catalog.html`.
 
 ## 7. Optional Standalone Admin

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

@@ -7,8 +7,6 @@ order: 31
 badge: card
 ---
 
-Write "add a `card` summarizing the SQLite WAL documentation with a title, link, and three takeaways" inside a `garden` idea block, and the Agent generates the `garden card` block below via the `garden-ui` skill (hand-written syntax follows).
-
 ```garden card
 title: SQLite Write-Ahead Logging
 url: https://www.sqlite.org/wal.html
@@ -20,27 +18,50 @@ points:
   - Background checkpoints copy log pages back into the main database file in batches once a threshold is reached.
 ```
 
+- **When to use**: Introducing a paper, open-source project, or subsystem where a link and 2 to 4 numbered points belong together, or listing several tools or references with a takeaway line.
+- **When to skip**: A sentence or two of prose or a `[Title](url){card}` link card is enough.
+
+You can tell the AI:
+
 ````markdown
+```garden
+Summarize the SQLite WAL documentation in a card with a link, a one-sentence summary, and three takeaways.
+```
+````
+
+## Multiple Resource Row Cards (`cards`)
+
+When you want to list several projects, tools, or references in one block and attach a takeaway line to each, use `cards`:
+
 ```garden card
-title: SQLite Write-Ahead Logging
-url: https://www.sqlite.org/wal.html
-meta: Documentation · sqlite.org
-description: Appends changes sequentially to a write-ahead log while readers continue reading the original database pages, reducing read-write contention.
-points:
-  - Writes append to the end of the `-wal` file instead of overwriting database pages in place on commit.
-  - Readers record the current end-of-log mark to see a consistent snapshot without blocking concurrent writers.
-  - Background checkpoints copy log pages back into the main database file in batches once a threshold is reached.
+cards:
+  - url: https://openlibrary.org/
+    title: "Open Library: one page per book"
+    description: An open catalogue run by the Internet Archive, with editions and e-book loans.
+    image: "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 132 132'%3E%3Crect width='132' height='132' fill='%23F0EEE6'/%3E%3Crect x='34' y='26' width='64' height='84' rx='6' fill='%23C9B79C'/%3E%3Crect x='34' y='26' width='10' height='84' fill='%238B6A45'/%3E%3Crect x='52' y='44' width='34' height='5' rx='2' fill='%23FAF9F5'/%3E%3Crect x='52' y='54' width='24' height='5' rx='2' fill='%23FAF9F5'/%3E%3C/svg%3E"
+    alt: A closed book
+    source:
+      - https://openlibrary.org/
+    takeaway: "**Worth borrowing:** link the book's page when you pick, so everyone reads the same edition."
+  - url: https://www.gutenberg.org/
+    title: "Project Gutenberg: public-domain e-books"
+    description: E-books that have entered the public domain, free to download.
+    image: "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 132 132'%3E%3Crect width='132' height='132' fill='%23E8EEF0'/%3E%3Ccircle cx='66' cy='60' r='30' fill='%239DB7A8'/%3E%3Crect x='30' y='98' width='72' height='8' rx='4' fill='%233F6B55'/%3E%3Crect x='44' y='112' width='44' height='6' rx='3' fill='%239DB7A8'/%3E%3C/svg%3E"
+    alt: A desk lamp
+    source:
+      - https://www.gutenberg.org/
+      - https://en.wikipedia.org/wiki/Project_Gutenberg
+    takeaway: "**Worth borrowing:** pick a public-domain book now and then, so people without a copy can join at once."
+```
+
+You can tell the AI:
+
+````markdown
+```garden
+List Open Library and Project Gutenberg as two cards, each with a source link and a takeaway line on what is worth borrowing.
 ```
 ````
 
-- **Use when**: Introducing a paper, open-source project, or subsystem where a source link and 2 to 4 numbered points belong together.
-- **Skip when**: A sentence or two of prose or a `[Title](url "{card}")` link card is enough.
-
-| Field | Required | Type | Description |
-| :--- | :--- | :--- | :--- |
-| `title` | Recommended | string | Card heading |
-| `url` | No | full URL | External link shown next to the heading |
-| `meta` | No | string | Subtitle or metadata line below the heading |
-| `description` | Either this or `points` | string | Main summary paragraph (supports inline bold and code) |
-| `points` | Either this or `description` | string[] | Numbered list of takeaways below the summary |
-| `source` | No | string or `{ title, url }` | Source attribution in the bottom-right corner |
+## Fields
+
+Every field, default, limit and error code is in [Component reference · card](/garden/en/reference/card).

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

@@ -1,14 +1,12 @@
 ---
 title: Bar Chart (chart)
 navTitle: chart
-description: Render proportional horizontal bars from YAML data, with a built-in expandable table underneath.
+description: Render proportional horizontal bars with a built-in expandable data table underneath.
 section: components
 order: 35
 badge: chart
 ---
 
-Write "use `chart` to compare the max widths of the prose column, wide figures, and wide tables" inside a `garden` idea block, and the Agent generates the `garden chart` block below via the `garden-ui` skill (hand-written syntax follows).
-
 ```garden chart
 title: Max Width by Layout Zone
 xLabel: Layout Zone
@@ -24,31 +22,17 @@ data:
 caption: Click "View data table" below to expand the full numeric table.
 ```
 
+- **When to use**: Comparing the relative magnitudes of 2 to 8 values that share the same unit.
+- **When to skip**: Numbers change with reader input (use [`interactive`](/garden/en/components/interactive)), or you already have a Markdown table with the same numbers in that section (the chart includes its own expandable table).
+
+You can tell the AI:
+
 ````markdown
-```garden chart
-title: Max Width by Layout Zone
-xLabel: Layout Zone
-yLabel: Max Width
-unit: px
-data:
-  - x: Prose Column
-    y: 740
-  - x: Wide Figure Zone
-    y: 1040
-  - x: Wide Table Zone
-    y: 1340
-caption: Click "View data table" below to expand the full numeric table.
+```garden
+Compare the max widths of the prose column, wide figures, and wide tables with a horizontal bar chart.
 ```
 ````
 
-- **Use when**: Comparing the relative magnitudes of 2 to 8 values that share the same unit.
-- **Skip when**: You already have a Markdown table with the same numbers in that section (`chart` includes its own expandable table).
+## Fields
 
-| Field | Required | Type | Description |
-| :--- | :--- | :--- | :--- |
-| `title` | Recommended | string | Chart heading |
-| `data` | Yes | `{ x, y, label? }[]` (at least 2) | Data rows where `x` is the label and `y` is the numeric value |
-| `unit` | No | string | Unit suffix appended when a row does not specify its own `label` |
-| `xLabel` | No | string | Header for the first column of the expandable table |
-| `yLabel` | No | string | Header for the second column of the expandable table |
-| `caption` | No | string | Caption shown below the chart |
+Every field, default, limit and error code is in [Component reference · chart](/garden/en/reference/chart).

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

@@ -0,0 +1,42 @@
+---
+title: Choice Cards (choice)
+navTitle: choice
+description: Present two or three option cards with an icon, headline value, and preference label, plus an optional fallback button and selection reply.
+section: components
+order: 42
+badge: choice
+---
+
+```garden choice
+title: Where should we meet next month?
+items:
+  - icon: idea
+    value: $6 each
+    text: Corner café, one drink included
+    label: Prefer the atmosphere
+    reply: Café it is. We will book the long table by the window.
+  - icon: book
+    value: Free
+    text: Library meeting room, booking needed
+    label: Prefer the quiet
+    reply: Library it is. We will book the room at the start of the month.
+none:
+  label: Neither / not sure
+  reply: No problem. We will share a few more venues in the group chat.
+caption: Illustrative only. Venues and prices are made up.
+```
+
+- **When to use**: Offering two or three concrete options where each choice has an icon, a prominent number or price, and a short note.
+- **When to skip**: Choosing an option recalculates a formula or updates a chart; use [`interactive`](/garden/en/components/interactive) instead.
+
+You can tell the AI:
+
+````markdown
+```garden
+Give readers two venue cards (corner cafe vs. library meeting room) with cost, preference label, selection reply, and a "neither" button underneath.
+```
+````
+
+## Fields
+
+Every field, default, limit and error code is in [Component reference · choice](/garden/en/reference/choice).

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

@@ -1,14 +1,12 @@
 ---
 title: Side-by-Side Comparison (compare)
 navTitle: compare
-description: Place two or three options side by side to contrast tradeoffs and attributes.
+description: Place two or three options side by side to contrast tradeoffs, or stack good and bad practices.
 section: components
 order: 33
 badge: compare
 ---
 
-Write "use `compare` to contrast describing a code change in one sentence against writing a diff block by hand" inside a `garden` idea block, and the Agent generates the `garden compare` block below via the `garden-ui` skill (hand-written syntax follows).
-
 ```garden compare
 items:
   - title: Describe the change in one sentence
@@ -17,22 +15,39 @@ items:
     text: Place a diff below full code; alone it raises diff-orphan.
 ```
 
+- **When to use**: Comparing 2 or 3 options, configurations, or before/after behaviors side by side (up to ~60 characters per cell in side-by-side mode), or stacking anti-patterns and recommended practices.
+- **When to skip**: Comparing more than 3 items or aligning multiple attributes across rows; use a Markdown list or table instead.
+
+You can tell the AI:
+
 ````markdown
+```garden
+Contrast describing a code change in one sentence against writing a diff block by hand.
+```
+````
+
+## Good vs. Bad Verdicts (`verdict: good | bad`)
+
+When contrasting an anti-pattern with a recommended practice, adding `verdict: bad` or `verdict: good` stacks the items vertically and shows a red cross or green check beside each heading:
+
 ```garden compare
 items:
-  - title: Describe the change in one sentence
-    text: Idea block under full code; garden-ui writes the diff.
-  - title: Write the diff by hand
-    text: Place a diff below full code; alone it raises diff-orphan.
+  - title: A poor question
+    verdict: bad
+    text: "“Have you read this author's other books? Could you share a review?”"
+  - title: A better question
+    verdict: good
+    text: "“When do you usually read? Would you like to sit in once first?”"
+```
+
+You can tell the AI:
+
+````markdown
+```garden
+Contrast a poor question and a better question when welcoming a newcomer, marked as bad and good examples.
 ```
 ````
 
-- **Use when**: Comparing 2 or 3 options, configurations, or before/after behaviors side by side (keep each cell under ~60 characters).
-- **Skip when**: Comparing more than 3 items or aligning multiple attributes across rows; use a Markdown table instead.
+## Fields
 
-| Field | Required | Type | Description |
-| :--- | :--- | :--- | :--- |
-| `items` | Yes | array (at least 2) | Options to compare; each entry can also be a `"Title: description"` shorthand string |
-| `items[].title` | Recommended | string | Column heading |
-| `items[].text` | Recommended | string or string[] | Body description for the column |
-| `items[].<customKey>` | No | string or number | Extra key-value pairs rendered as attribute tags along the bottom of the card |
+Every field, default, limit and error code is in [Component reference · compare](/garden/en/reference/compare).