hd-garden 0.8.0 → 0.8.2

package/bin/garden.mjs

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { createRequire } from "node:module";
 import { gardenPackageRoot, gardenSiteRoot } from "../scripts/garden-paths.mjs";
+import { langOf, siteCliLang } from "../ui/core/cli-locale.mjs";
 
 const siteRoot = gardenSiteRoot();
 const args = process.argv.slice(2);
@@ -90,7 +91,17 @@ function ensurePublic() {
   }
 }
 
-function printGiscusGuide() {
+function printGiscusGuide(lang = siteCliLang(siteRoot)) {
+  if (lang === "en") {
+    process.stdout.write(`Comments are disabled by default. Configure Giscus before publishing, or GitHub Actions builds will fail:
+  1. Prepare a public GitHub repository and enable Discussions. A public source repo works directly; a private source repo needs a separate public repo.
+  2. Open https://giscus.app, install the Giscus App for that repository, and pick a category.
+  3. Set GISCUS_REPO, GISCUS_REPO_ID, GISCUS_CATEGORY, and GISCUS_CATEGORY_ID in .env.local.
+  4. Add the same four variables under Settings -> Secrets and variables -> Actions -> Variables in your source repository.
+Placeholder values do not count as configured. To publish without comments, set the Actions Variable GISCUS_DISABLED to 1.
+`);
+    return;
+  }
   process.stdout.write(`评论默认关闭。发布前要接上自己的 Giscus，留空会让 GitHub Actions 构建失败：
   1. 准备一个公开 GitHub 仓库，并开启 Discussions。公开源码仓库可以直接用；私有源码要另建一个公开仓库。
   2. 打开 https://giscus.app/zh-CN ，安装 Giscus App，只授权这个仓库，并选一个分类。
@@ -104,11 +115,12 @@ function ensureEnv() {
   // CI injects the real values. Copying .env.example there would fill any
   // unset key with a sample, which used to turn comments on for owner/repository.
   if (process.env.GITHUB_ACTIONS === "true") return;
-  const example = path.join(gardenPackageRoot, ".env.example");
+  const lang = siteCliLang(siteRoot);
+  const example = path.join(gardenPackageRoot, lang === "en" ? ".env.en.example" : ".env.example");
   const local = path.join(siteRoot, ".env.local");
   if (!fs.existsSync(local) && fs.existsSync(example)) {
     fs.copyFileSync(example, local);
-    printGiscusGuide();
+    printGiscusGuide(lang);
   }
 }
 
@@ -156,6 +168,16 @@ function vinextRoot() {
     }
   }
 
+  // English sites: the runtime manifest is a copy with the English description, not a link.
+  // Remove the link first so the write never goes through it into the engine's own package.json.
+  if (siteCliLang(siteRoot) === "en") {
+    const target = path.join(runtime, "package.json");
+    const manifest = JSON.parse(fs.readFileSync(path.join(gardenPackageRoot, "package.json"), "utf8"));
+    manifest.description = "A personal blog engine: write in Markdown, publish with GitHub Pages.";
+    fs.rmSync(target, { force: true });
+    fs.writeFileSync(target, `${JSON.stringify(manifest, null, 2)}\n`);
+  }
+
   return runtime;
 }
 
@@ -176,22 +198,27 @@ function copyIfMissing(from, to) {
 
 function ensureSiteKit(destinationRoot = siteRoot) {
   if (samePath(destinationRoot, gardenPackageRoot)) return;
+  const lang = siteCliLang(destinationRoot);
 
   const added = [];
   if (
     copyIfMissing(
-      path.join(gardenPackageRoot, "templates", "site", "Makefile"),
+      path.join(gardenPackageRoot, "templates", "site", lang === "en" ? "Makefile.en" : "Makefile"),
       path.join(destinationRoot, "Makefile"),
     )
   ) {
     added.push("Makefile");
   }
   if (added.length) {
-    process.stdout.write(`已补齐站点文件：${added.join("、")}\n`);
+    process.stdout.write(
+      lang === "en"
+        ? `Added missing site files: ${added.join(", ")}\n`
+        : `已补齐站点文件：${added.join("、")}\n`,
+    );
   }
 
-  installSkill(destinationRoot, { onlyMissing: true });
-  if (process.env.GARDEN_SKIP_HOOKS !== "1") installHook(destinationRoot, { quiet: true });
+  installSkill(destinationRoot, { onlyMissing: true, lang });
+  if (process.env.GARDEN_SKIP_HOOKS !== "1") installHook(destinationRoot, { quiet: true, lang });
 }
 
 const HOOK_MARKER = "# garden: ui check";
@@ -203,30 +230,46 @@ if [ ! -d node_modules/hd-garden ]; then
 fi
 exec npx --no-install garden ui check --staged --quiet
 `;
+const HOOK_SCRIPT_EN = `#!/bin/sh
+${HOOK_MARKER}
+if [ ! -d node_modules/hd-garden ]; then
+  echo "garden is not installed yet (run npm install first); skipping ui check." >&2
+  exit 0
+fi
+exec npx --no-install garden ui check --staged --quiet
+`;
 
 /** Installs the pre-commit hook unless the repository already has one. */
-function installHook(destinationRoot = siteRoot, { quiet = false, force = false } = {}) {
+function installHook(destinationRoot = siteRoot, { quiet = false, force = false, lang = siteCliLang(destinationRoot) } = {}) {
   const result = spawnSync("git", ["rev-parse", "--git-path", "hooks/pre-commit"], { cwd: destinationRoot, encoding: "utf8" });
   if (result.status !== 0) {
-    if (!quiet) process.stdout.write("这里不是 git 仓库，没有安装提交前检查。\n");
+    if (!quiet) process.stdout.write(lang === "en" ? "Not a git repository; skipping pre-commit hook installation.\n" : "这里不是 git 仓库，没有安装提交前检查。\n");
     return;
   }
   const hookPath = path.resolve(destinationRoot, result.stdout.trim());
   if (fs.existsSync(hookPath)) {
     const current = fs.readFileSync(hookPath, "utf8");
     if (current.includes(HOOK_MARKER) && !force) {
-      if (!quiet) process.stdout.write("提交前检查已经装好了。\n");
+      if (!quiet) process.stdout.write(lang === "en" ? "Pre-commit hook is already installed.\n" : "提交前检查已经装好了。\n");
       return;
     }
     if (!current.includes(HOOK_MARKER)) {
-      process.stdout.write(`已有 pre-commit 钩子，没有覆盖。请把这一行加进 ${path.relative(destinationRoot, hookPath)}：\n  npx --no-install garden ui check --staged --quiet\n`);
+      process.stdout.write(
+        lang === "en"
+          ? `Existing pre-commit hook kept. Add this line to ${path.relative(destinationRoot, hookPath)}:\n  npx --no-install garden ui check --staged --quiet\n`
+          : `已有 pre-commit 钩子，没有覆盖。请把这一行加进 ${path.relative(destinationRoot, hookPath)}：\n  npx --no-install garden ui check --staged --quiet\n`,
+      );
       return;
     }
   }
   fs.mkdirSync(path.dirname(hookPath), { recursive: true });
-  fs.writeFileSync(hookPath, HOOK_SCRIPT, { mode: 0o755 });
+  fs.writeFileSync(hookPath, lang === "en" ? HOOK_SCRIPT_EN : HOOK_SCRIPT, { mode: 0o755 });
   fs.chmodSync(hookPath, 0o755);
-  process.stdout.write("已安装提交前检查：提交时会检查暂存稿件里的 ui 块。\n");
+  process.stdout.write(
+    lang === "en"
+      ? "Installed pre-commit hook: staged posts will be checked for valid ui blocks before commit.\n"
+      : "已安装提交前检查：提交时会检查暂存稿件里的 ui 块。\n",
+  );
 }
 
 function prepare() {
@@ -283,10 +326,12 @@ function runVinext(vinextArgs, { copyDist = false } = {}) {
   if (result.status !== 0) process.exit(result.status || 1);
 }
 
+const EN_TEMPLATE_VARIANTS = new Set(["site.config.en.yaml", "Makefile.en", "README.en.md"]);
+
 function copyTemplate(from, to) {
   fs.mkdirSync(to, { recursive: true });
   for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
-    if (entry.name === ".git") continue;
+    if (entry.name === ".git" || EN_TEMPLATE_VARIANTS.has(entry.name)) continue;
     const source = path.join(from, entry.name);
     const destination = path.join(to, entry.name);
     if (entry.isDirectory()) copyTemplate(source, destination);
@@ -294,6 +339,34 @@ function copyTemplate(from, to) {
   }
 }
 
+function parseInitArgs(argv) {
+  let locale = process.env.GARDEN_LOCALE ?? "";
+  const positional = [];
+  const hasLocaleFlag = argv.includes("--locale");
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--locale") {
+      locale = argv[i + 1] ?? "";
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--locale=")) {
+      locale = arg.slice("--locale=".length);
+      continue;
+    }
+    if (/^locale\s*[:=]/iu.test(arg)) {
+      locale = arg.replace(/^locale\s*[:=]\s*/iu, "");
+      continue;
+    }
+    positional.push(arg);
+  }
+  void hasLocaleFlag;
+  return {
+    destination: path.resolve(positional[0] ?? "."),
+    lang: langOf(locale),
+  };
+}
+
 function writeEngineDependency(destination) {
   const engine = JSON.parse(fs.readFileSync(path.join(gardenPackageRoot, "package.json"), "utf8"));
   const sitePkgPath = path.join(destination, "package.json");
@@ -306,14 +379,44 @@ function writeEngineDependency(destination) {
 }
 
 function initSite() {
-  const destination = path.resolve(rest[0] ?? ".");
+  const { destination, lang } = parseInitArgs(rest);
   const template = path.join(gardenPackageRoot, "templates", "site");
   if (!fs.existsSync(template)) fail("Garden 包里缺少 templates/site。");
   if (fs.existsSync(path.join(destination, "site.config.yaml"))) {
-    fail(`目录已是 Garden 站点：${destination}`);
+    fail(lang === "en" ? `Directory is already a Garden site: ${destination}` : `目录已是 Garden 站点：${destination}`);
   }
   copyTemplate(template, destination);
+  if (lang === "en") {
+    for (const [srcName, destName] of [
+      ["site.config.en.yaml", "site.config.yaml"],
+      ["Makefile.en", "Makefile"],
+      ["README.en.md", "README.md"],
+    ]) {
+      const srcFile = path.join(template, srcName);
+      if (fs.existsSync(srcFile)) {
+        fs.copyFileSync(srcFile, path.join(destination, destName));
+      }
+    }
+    const enWorkflow = path.join(gardenPackageRoot, "templates", "workflows", "pages.en.yml");
+    if (fs.existsSync(enWorkflow)) {
+      const workflowDest = path.join(destination, ".github", "workflows", "pages.yml");
+      fs.mkdirSync(path.dirname(workflowDest), { recursive: true });
+      fs.copyFileSync(enWorkflow, workflowDest);
+    }
+  }
   writeEngineDependency(destination);
+  if (lang === "en") {
+    process.stdout.write(`Created site: ${destination}\n`);
+    installSkill(destination, { lang });
+    process.stdout.write("Next steps:\n");
+    process.stdout.write(`  cd ${destination}\n`);
+    process.stdout.write("  npm install\n");
+    process.stdout.write("  Configure comments in four steps below, then start writing\n");
+    process.stdout.write("  make new TITLE=\"Hello, World\" SLUG=hello\n");
+    process.stdout.write("  make dev\n");
+    printGiscusGuide("en");
+    return;
+  }
   process.stdout.write(`已创建站点：${destination}\n`);
   installSkill(destination);
   process.stdout.write("下一步：\n");
@@ -322,7 +425,7 @@ function initSite() {
   process.stdout.write("  按下面四步接上评论，再写文章\n");
   process.stdout.write("  make new TITLE=\"你好，世界\" SLUG=hello\n");
   process.stdout.write("  make dev\n");
-  printGiscusGuide();
+  printGiscusGuide("zh");
 }
 
 function packagedSkills() {
@@ -333,7 +436,7 @@ function packagedSkills() {
     .map((entry) => entry.name);
 }
 
-function installSkill(destinationRoot = siteRoot, { onlyMissing = false } = {}) {
+function installSkill(destinationRoot = siteRoot, { onlyMissing = false, lang = siteCliLang(destinationRoot) } = {}) {
   const names = packagedSkills();
   if (!names.length) fail("Garden 包里没有 skill。");
   const installed = [];
@@ -341,10 +444,17 @@ function installSkill(destinationRoot = siteRoot, { onlyMissing = false } = {})
     const to = path.join(destinationRoot, ".agents", "skills", name);
     if (onlyMissing && fs.existsSync(path.join(to, "SKILL.md"))) continue;
     fs.cpSync(path.join(gardenPackageRoot, ".agents", "skills", name), to, { recursive: true });
+    // English sites get the English skill text; files without a translation keep the packaged copy.
+    const english = path.join(gardenPackageRoot, "templates", "skills-en", name);
+    if (lang === "en" && fs.existsSync(english)) fs.cpSync(english, to, { recursive: true, force: true });
     installed.push(name);
   }
   if (installed.length) {
-    process.stdout.write(`已安装 skill：${installed.join("、")}\n`);
+    process.stdout.write(
+      lang === "en"
+        ? `Installed skills: ${installed.join(", ")}\n`
+        : `已安装 skill：${installed.join("、")}\n`,
+    );
   }
 }
 

package/docs/handbook/ai-writing.md

@@ -86,8 +86,8 @@ Agent 按 `garden-ui` skill 会把这个想法块替换成一段紧挨着完整
 
 不借助 AI 手写组件时，可以直接使用包内自带的模板与代码片段：
 
-- `make new` 创建的草稿底部自带一段 `<!-- 组件速查 ... -->` 注释，包含想法块和 9 个组件的示例，写完可直接删掉。
-- `templates/garden-blocks.md` 汇总了想法块与 9 个组件的适用场景（`when` / `whenNot`）和可复制示例；macOS 与 Typora / Alfred 用户可导入 `templates/garden-snippets.plist`，输入 `;gidea`（或 `;garden想法`）、`;gcard`、`;gstat`、`;gcompare`、`;gtimeline`、`;gchart`、`;gfigure`、`;ghtml`、`;ginteractive`、`;gfile` 即可展开对应围栏。
+- `make new` 创建的草稿底部自带一段 `<!-- 组件速查 ... -->` 注释，包含想法块和 12 个组件的示例，写完可直接删掉。
+- `templates/garden-blocks.md` 汇总了想法块与 12 个组件的适用场景（`when` / `whenNot`）和可复制示例；macOS 与 Typora / Alfred 用户可导入 `templates/garden-snippets.plist`，输入 `;gidea`（或 `;garden想法`）、`;gcard`、`;gstat`、`;gcompare`、`;gtimeline`、`;gchart`、`;gfigure`、`;ghtml`、`;ginteractive`、`;gfile`、`;grel`、`;glist`、`;gchoice` 即可展开对应围栏。
 - 引擎仓库的 `editors/vscode`、`editors/typora` 与 `editors/obsidian` 目录提供了对应的编辑器片段与插件支持，运行 `npx garden ui catalog` 则可在本地生成 `.garden/ui-catalog.html` 离线组件画廊。
 
 ## 7. 可选的独立管理后台

package/docs/handbook/assets/reading-layout-en.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="2080" height="560" viewBox="0 0 1040 280" fill="none" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif">
+  <!-- Outer 1340px wide-table boundary -->
+  <rect x="20" y="20" width="1000" height="240" rx="14" stroke="#6e6b64" stroke-width="1.5" stroke-dasharray="6 5" />
+  <text x="44" y="48" fill="#4a4844" font-size="13" font-weight="600">Wide-table zone &#xB7; up to 1340px on article pages (extends up to 300px per side)</text>
+  <text x="996" y="48" text-anchor="end" fill="#6e6b64" font-size="12" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">max 1340px</text>
+
+  <!-- Middle 1040px wide-figure boundary -->
+  <rect x="110" y="66" width="820" height="174" rx="12" stroke="#2d2c29" stroke-width="1.5" stroke-dasharray="4 4" />
+  <text x="132" y="92" fill="#2d2c29" font-size="13" font-weight="600">Wide-figure zone &#xB7; up to 1040px on article pages (retina screenshots render at half pixel width, expanding past 740px)</text>
+  <text x="908" y="92" text-anchor="end" fill="#6e6b64" font-size="12" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">max 1040px</text>
+
+  <!-- Inner 740px reading column -->
+  <rect x="215" y="110" width="610" height="110" rx="10" fill="#f0eee6" fill-opacity="0.72" stroke="#1b1a18" stroke-width="2" />
+  <text x="520" y="146" text-anchor="middle" fill="#1b1a18" font-size="16" font-weight="700">Reading column &#xB7; 740px (var(--col))</text>
+  <text x="520" y="172" text-anchor="middle" fill="#2d2c29" font-size="13">Paragraphs, lists, blockquotes, code blocks, and formulas stay inside this column</text>
+  <text x="520" y="196" text-anchor="middle" fill="#6e6b64" font-size="12" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">Transparent-background figures get var(--image-backing) #faf9f5 warm backing in dark mode</text>
+
+  <!-- Left & right expansion arrows -->
+  <path d="M210 165 H118" stroke="#2d2c29" stroke-width="1.5" />
+  <path d="M124 160 L116 165 L124 170" stroke="#2d2c29" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" />
+  <text x="164" y="156" text-anchor="middle" fill="#4a4844" font-size="11" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">&#x2264; 150px</text>
+
+  <path d="M830 165 H922" stroke="#2d2c29" stroke-width="1.5" />
+  <path d="M916 160 L924 165 L916 170" stroke="#2d2c29" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" />
+  <text x="876" y="156" text-anchor="middle" fill="#4a4844" font-size="11" font-family="ui-monospace, SFMono-Regular, Menlo, monospace">&#x2264; 150px</text>
+</svg>

package/docs/handbook/components/card.md

@@ -1,14 +1,12 @@
 ---
 title: 知识卡片（card）
 navTitle: 知识卡片
-description: 把论文、项目或模块说明整理成带元数据与编号要点的卡片。
+description: 介绍一篇论文、一个项目或一组值得参考的公开工具。
 section: components
 order: 31
 badge: card
 ---
 
-在 `garden` 想法块里写一句「放一张 `card` 介绍 SQLite 的 WAL 文档，带标题、链接和三条要点」，Agent 会按 `garden-ui` skill 生成下面的 `garden card`（手写格式附后）。
-
 ```garden card
 title: SQLite WAL 写入模式
 url: https://www.sqlite.org/wal.html
@@ -20,27 +18,50 @@ points:
   - 后台 Checkpoint 按阈值将日志页分批写回主库文件。
 ```
 
+- **什么时候用**：介绍一篇论文、一个仓库或一本书，需要标题、链接和几条说明；或者把几项参考资源放在一起，各附一句可借鉴的结论。
+- **什么时候不用**：正文里一两句话已经说清，或者只需要普通外链卡片时，直接写正文段落。
+
+可以这样对 AI 说：
+
 ````markdown
+```garden
+整理一张卡片介绍 SQLite 的 WAL 文档，带链接和三条核心要点。
+```
+````
+
+## 多张资源行卡（`cards`）
+
+需要连续列出几个项目、公开工具或参考资料，并在每张卡片下方附上一句启发时，可以用 `cards` 列表：
+
 ```garden card
-title: SQLite WAL 写入模式
-url: https://www.sqlite.org/wal.html
-meta: 文档说明 · sqlite.org
-description: 把修改先顺序追加到预写日志，读操作继续访问原数据库页，减少读写互斥等待。
-points:
-  - 写入只追加到 `-wal` 文件末尾，不需要在事务提交时原地覆盖数据页。
-  - 读事务记录当前末尾偏移量即可看到一致快照，不会阻塞并发写入。
-  - 后台 Checkpoint 按阈值将日志页分批写回主库文件。
+cards:
+  - url: https://openlibrary.org/
+    title: Open Library：每本书一个页面
+    description: Internet Archive 维护的开放图书目录，可以查版本、借阅电子书。
+    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: 一本合上的书
+    source:
+      - https://openlibrary.org/
+    takeaway: "**可借鉴：** 选书时直接贴书的页面链接，大家看到的是同一个版本。"
+  - url: https://www.gutenberg.org/
+    title: Project Gutenberg：公版电子书
+    description: 收录已进入公有领域的电子书，可以免费下载。
+    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: 一盏台灯
+    source:
+      - https://www.gutenberg.org/
+      - https://en.wikipedia.org/wiki/Project_Gutenberg
+    takeaway: "**可借鉴：** 偶尔选一本公版书，没买书的人也能马上加入。"
+```
+
+可以这样对 AI 说：
+
+````markdown
+```garden
+把 Open Library 和 Project Gutenberg 做成两张资源卡片，附上来源链接和各自可借鉴的地方。
 ```
 ````
 
-- **用**：介绍一篇论文、一个开源项目或某个子系统，需要带出来源链接和 2～4 条关键要点时。
-- **别用**：只有一两句普通说明时直接写正文段落或链接卡片（`{card}`），不要套一层 `card`。
-
-| 字段 | 必填 | 类型 | 说明 |
-| :--- | :--- | :--- | :--- |
-| `title` | 建议 | 字符串 | 卡片标题 |
-| `url` | 否 | 完整链接 | 标题旁显示的外部链接（渲染为 `来源 ↗`） |
-| `meta` | 否 | 字符串 | 标题下方的副标题或元信息说明 |
-| `description` | 与 `points` 二选一 | 字符串 | 卡片主说明段落（支持行内加粗与代码） |
-| `points` | 与 `description` 二选一 | 字符串数组 | 下方带编号的要点列表 |
-| `source` | 否 | 字符串或 `{ title, url }` | 右下角出处角标 |
+## 字段说明
+
+全部字段、默认值、取值限制和报错代码见 [组件参考 · card](/garden/reference/card)。

package/docs/handbook/components/chart.md

@@ -1,14 +1,12 @@
 ---
 title: 条形图表（chart）
 navTitle: 条形图表
-description: 用 YAML 数据直接生成比例条形图，下方自带可展开的数据表格。
+description: 把一组算好的数字画成比例条形图，下方自带可展开的数据表。
 section: components
 order: 35
 badge: chart
 ---
 
-在 `garden` 想法块里写一句「用 `chart` 画条形图比较正文列、宽图区和宽表区的宽度上限」，Agent 会按 `garden-ui` skill 生成下面的 `garden chart`（手写格式附后）。
-
 ```garden chart
 title: 三种版面区域的宽度上限
 xLabel: 版面区域
@@ -24,31 +22,17 @@ data:
 caption: 点击「查看数据表」可展开完整数值表格。
 ```
 
+- **什么时候用**：一组已经算好的同单位数字，想让读者一眼看出长短比例。
+- **什么时候不用**：数字会随读者调整参数而变化时用[可调公式与参数](/garden/components/interactive)；图表下方已经自带可展开的数据表，同一小节里不需要再重复放一张相同数字的表格。
+
+可以这样对 AI 说：
+
 ````markdown
-```garden chart
-title: 三种版面区域的宽度上限
-xLabel: 版面区域
-yLabel: 最大宽度
-unit: px
-data:
-  - x: 普通正文列
-    y: 740
-  - x: 宽幅配图区
-    y: 1040
-  - x: 多列宽表格
-    y: 1340
-caption: 点击「查看数据表」可展开完整数值表格。
+```garden
+画一张条形图比较普通正文列（740px）、宽幅配图区（1040px）和多列宽表格（1340px）的宽度上限。
 ```
 ````
 
-- **用**：对比 2～8 组同量纲数值的长短比例时。
-- **别用**：已经在同一个小节里放了同组数字的 Markdown 表格时不要再画一张 `chart`（图表底部已自带可展开的数据表）。
+## 字段说明
 
-| 字段 | 必填 | 类型 | 说明 |
-| :--- | :--- | :--- | :--- |
-| `title` | 建议 | 字符串 | 图表标题 |
-| `data` | 是 | `{ x, y, label? }[]`（至少 2 项） | 数据行列表，`x` 为名称，`y` 为数值 |
-| `unit` | 否 | 字符串 | 数值后缀单位（当数据项未单独指定 `label` 时自动拼接） |
-| `xLabel` | 否 | 字符串 | 展开数据表第一列的表头名称（默认 `项目`） |
-| `yLabel` | 否 | 字符串 | 展开数据表第二列的表头名称（默认 `数值`） |
-| `caption` | 否 | 字符串 | 图表底部的图注说明 |
+全部字段、默认值、取值限制和报错代码见 [组件参考 · chart](/garden/reference/chart)。

package/docs/handbook/components/choice.md

@@ -0,0 +1,42 @@
+---
+title: 选择卡（choice）
+navTitle: 选择卡
+description: 给出两三个具体选项卡片，读者点选后看到对应的回应。
+section: components
+order: 42
+badge: choice
+---
+
+```garden choice
+title: 下个月在哪里见面？
+items:
+  - icon: idea
+    value: ¥40 / 人
+    text: 街角咖啡馆，含一杯饮料
+    label: 更看重氛围
+    reply: 选了咖啡馆。我们会提前订好靠窗的长桌。
+  - icon: book
+    value: 免费
+    text: 社区图书馆活动室，需提前预约
+    label: 更看重安静
+    reply: 选了图书馆。我们会在月初提交预约。
+none:
+  label: 都不合适 / 说不清
+  reply: 没关系，我们会在群里再列几个场地。
+caption: 示意交互，场地和价格均为虚构。
+```
+
+- **什么时候用**：给读者两三个具体选项让他选一个，每个选项带图标、一个醒目的数字或价格和一句说明。
+- **什么时候不用**：选项会改变后面的公式或图表计算结果时，用[可调公式与参数](/garden/components/interactive)。
+
+可以这样对 AI 说：
+
+````markdown
+```garden
+放一组选择卡让读者在街角咖啡馆（40 元含饮料，重氛围）和社区图书馆（免费，重安静）之间选一个，底部加一个「都不合适」按钮。
+```
+````
+
+## 字段说明
+
+全部字段、默认值、取值限制和报错代码见 [组件参考 · choice](/garden/reference/choice)。

package/docs/handbook/components/compare.md

@@ -1,38 +1,53 @@
 ---
 title: 并排对比（compare）
 navTitle: 并排对比
-description: 把两到三种方案左右并列，对比各自的取舍与属性。
+description: 把两三种方案左右并列，或把不好的做法与更好的做法上下对照。
 section: components
 order: 33
 badge: compare
 ---
 
-在 `garden` 想法块里写一句「用 `compare` 并排比较用一句话描述代码改动和手写 diff 两种做法」，Agent 会按 `garden-ui` skill 生成下面的 `garden compare`（手写格式附后）。
-
 ```garden compare
 items:
   - title: 写一句话说明改了什么
-    text: 想法块紧跟在完整代码下面，garden-ui 把它换成 diff，页面合成「代码 / 对比上一版」。
+    text: 想法块紧跟在完整代码下面，AI 把它换成 diff，页面合成「代码 / 对比上一版」。
   - title: 手写 diff
-    text: 完整代码下面紧跟一段 diff；前面没有完整代码时，garden check 报 diff-orphan。
+    text: 完整代码下面紧跟一段 diff。
 ```
 
+- **什么时候用**：两三件东西并排看差异（并排模式下每格文字不超过约 60 字），或者把一正一反两种做法放在一起对照。
+- **什么时候不用**：每段说明都很长，或者要横向对齐多个参数维度时，直接用列表或表格。
+
+可以这样对 AI 说：
+
 ````markdown
+```garden
+把「用一句话说明改了什么」和「手写 diff」这两种做法并排对比一下。
+```
+````
+
+## 正反做法对照（`verdict: good | bad`）
+
+如果要对比「不好的做法」和「更好的做法」，条目带上 `verdict: bad` 或 `verdict: good` 后会改为上下堆叠，并在标题旁显示红叉或绿勾：
+
 ```garden compare
 items:
-  - title: 写一句话说明改了什么
-    text: 想法块紧跟在完整代码下面，garden-ui 把它换成 diff，页面合成「代码 / 对比上一版」。
-  - title: 手写 diff
-    text: 完整代码下面紧跟一段 diff；前面没有完整代码时，garden check 报 diff-orphan。
+  - title: 不好的提问
+    verdict: bad
+    text: 「你读过这位作者的其他作品吗？能分享一段书评吗？」
+  - title: 更好的提问
+    verdict: good
+    text: 「你平时喜欢在什么时间读书？想先旁听一次吗？」
+```
+
+可以这样对 AI 说：
+
+````markdown
+```garden
+对比一下问新成员时「不好的提问」和「更好的提问」。
 ```
 ````
 
-- **用**：并排对比 2～3 种方案、配置方式或改动前后的行为差异时（每格文字控制在 60 字以内）。
-- **别用**：对比项超过 3 个或需要横向对齐多个参数维度时，直接用 Markdown 表格。
+## 字段说明
 
-| 字段 | 必填 | 类型 | 说明 |
-| :--- | :--- | :--- | :--- |
-| `items` | 是 | 数组（至少 2 项） | 对比项列表；每项也可简写为 `"标题：说明"` 单行字符串 |
-| `items[].title` | 建议 | 字符串 | 该对比列的标题 |
-| `items[].text` | 建议 | 字符串或字符串数组 | 该对比列的正文说明 |
-| `items[].<自定义键>` | 否 | 字符串或数字 | 除 `title` / `text` 外的附加键值会渲染在卡片底部的属性标签行 |
+全部字段、默认值、取值限制和报错代码见 [组件参考 · compare](/garden/reference/compare)。