hd-garden 0.8.0 → 0.8.2

package/docs/handbook/en/components.md

@@ -1,30 +1,222 @@
 ---
 title: Components Overview
 navTitle: Overview
-description: What each of the 9 built-in garden components is for, its fence name, and its required fields.
+description: Live preview of all 12 built-in components.
 section: components
 order: 30
 ---
 
-You can describe any of these 9 components in a single sentence inside a `garden` idea block and let your Agent generate the block with the `garden-ui` skill (see [Writing with AI](/garden/en/ai-writing)). When writing by hand, open a ```` ```garden <name> ```` code block with the English component name (`card`, `stat`, `compare`, `timeline`, `chart`, `figure`, `html`, `interactive`, or `file`); parameters use YAML, while `interactive` takes declarative tags below `---`.
+## [Reference Card · card](/garden/en/components/card)
 
-## Component Quick Reference
+```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.
+```
 
-| Component | Code Fence | When to Use | Minimum Requirement |
-| :--- | :--- | :--- | :--- |
-| [card](/garden/en/components/card) | ```` ```garden card ```` | Summarize a paper, open-source project, or subsystem | Provide `description` or `points` |
-| [stat](/garden/en/components/stat) | ```` ```garden stat ```` | Place 2 to 4 key numbers and units side by side | Each item requires `label` and `value` |
-| [compare](/garden/en/components/compare) | ```` ```garden compare ```` | Compare 2 or 3 options or before/after tradeoffs side by side | At least 2 `items`, ~60 characters per cell |
-| [timeline](/garden/en/components/timeline) | ```` ```garden timeline ```` | Walk through debugging steps or release stages in order | At least 2 `items` |
-| [chart](/garden/en/components/chart) | ```` ```garden chart ```` | Plot proportional bars from YAML rows (includes an expandable table) | At least 2 rows in `data` |
-| [figure](/garden/en/components/figure) | ```` ```garden figure ```` | Highlight regions of an SVG or image diagram with step buttons | Either `svg` or `image` |
-| [html](/garden/en/components/html) | ```` ```garden html ```` | Run a self-contained HTML/JS demo in a sandboxed `iframe` | Either `src` or `code` |
-| [interactive](/garden/en/components/interactive) | ```` ```garden interactive ```` | Let readers drag sliders or switches to evaluate a non-trivial formula | Must include an input control and a formula beyond a single multiplication |
-| [file](/garden/en/components/file) | ```` ```garden file ```` | Offer local or remote attachments for download and inline preview | Either `src` or `files` |
+## [Key Figures · stat](/garden/en/components/stat)
 
-## Authoring Rules
+```garden stat
+items:
+  - label: Reading Column
+    value: "740"
+    unit: px
+    caption: Default prose column width
+  - label: Wide Figure Limit
+    value: "1040"
+    unit: px
+    caption: Extends up to 150px on each side
+  - label: Wide Table Limit
+    value: "1340"
+    unit: px
+    caption: Extends up to 300px on each side
+```
 
-1. **Use standard Markdown first**: Write regular paragraphs, ordered lists, and comparison tables in plain Markdown, and reach for a `garden` fence only when a structured block makes the point easier to read.
-2. **Do not duplicate the same numbers**: A `chart` block already includes an expandable data table underneath, so do not put a second Markdown table with the same figures in the same section.
-3. **Inline formatting works inside fields**: Text fields such as `text`, `description`, `caption`, and `points` accept inline `**bold**`, `` `code` ``, and `<u>highlighter underline</u>`.
-4. **Preview every component locally**: Run `npx garden ui catalog` to generate `.garden/ui-catalog.html` and open it in your browser.
+## [Side-by-Side Comparison · compare](/garden/en/components/compare)
+
+```garden compare
+items:
+  - title: Describe the change in one sentence
+    text: Idea block under full code; the AI writes the diff.
+  - title: Write the diff by hand
+    text: Place a diff block right below the full code block.
+```
+
+## [Step Timeline · timeline](/garden/en/components/timeline)
+
+```garden timeline
+items:
+  - date: Step 1
+    title: Sync Content and Assets
+    text: Validate Front Matter, copy attachments, and build the search index and RSS feed.
+  - date: Step 2
+    title: Build Static Site Output
+    text: Prerender every route into the static output directory.
+```
+
+## [Bar Chart · chart](/garden/en/components/chart)
+
+```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
+```
+
+## [Annotated Diagram · figure](/garden/en/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)">Parse</text>
+    <text data-p="sync" x="92" y="137" text-anchor="middle" font-size="24" fill="var(--muted)">Markdown &amp;</text>
+    <text data-p="sync" x="92" y="166" text-anchor="middle" font-size="24" fill="var(--muted)">image sizes</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)">Build static</text>
+    <text data-p="build" x="280" y="137" text-anchor="middle" font-size="24" fill="var(--muted)">pages &amp; index</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)">Check</text>
+    <text data-p="validate" x="468" y="137" text-anchor="middle" font-size="24" fill="var(--muted)">exported files</text>
+  </svg>
+parts:
+  - id: sync
+    label: 1. Sync Content
+    text: Scans posts and sidecar assets to generate site data.
+  - id: build
+    label: 2. Build Pages
+    text: Prerenders all routes and outputs RSS, sitemap, and search indexes.
+  - id: validate
+    label: 3. Validate Export
+    text: Checks that the exported static directory is complete.
+```
+
+## [Embedded Web Snippet · html](/garden/en/components/html)
+
+```garden html
+title: Character Count Widget
+code: |
+  <!doctype html>
+  <html lang="en">
+  <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="Keep your posts in a Git repository and push to deploy." aria-label="Sample text input" />
+    <div class="meta">Characters: <strong id="count">55</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 Formula & Parameters · interactive](/garden/en/components/interactive)
+
+```garden interactive #overview-reading
+caption: "Example: estimate reading time from word count and reading speed."
+---
+<State words={6000} speed={400} />
+<Let minutes={round(words / speed)} />
+
+<Slider bind="words" label="Word count" min={1000} max={20000} step={500} unit="words" />
+<Slider bind="speed" label="Reading speed" min={200} max={800} step={50} unit="wpm" />
+
+<Stat label="Estimated reading time" value={minutes} unit="min" />
+```
+
+## [File Download & Preview · file](/garden/en/components/file)
+
+```garden file
+src: ./components/file/checklist.md
+title: Pre-publish Checklist
+note: Click Preview to read inline or Download to save the file
+```
+
+## [Relationship diagram · relations](/garden/en/components/relations)
+
+```garden relations
+items:
+  - title: Pick
+    text: Choose this month's book
+  - title: Read
+    text: Finish the agreed chapters each week
+  - title: Talk
+    text: Meet and share views
+  - title: Review
+    text: Note what to change next time
+links:
+  - from: 1
+    to: 2
+  - from: 2
+    to: 3
+  - from: 3
+    to: 4
+  - from: 4
+    to: 1
+  - from: 3
+    to: 1
+    style: dashed
+    label: shapes the pick
+```
+
+## [Icon List · list](/garden/en/components/list)
+
+```garden list
+items:
+  - icon: search
+    text: Searches for this month's title
+  - icon: eye
+    text: Reads 3 reviews
+  - icon: heart
+    text: Saves the event page
+  - icon: chat
+    text: Asks in the group chat whether listening only is fine
+```
+
+## [Choice Cards · choice](/garden/en/components/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.
+```

package/docs/handbook/en/config.md

@@ -10,16 +10,16 @@ Global site copy and appearance settings live in `site.config.yaml` at the repos
 
 ## 1. Full `site.config.yaml` Structure
 
-Here is the default `site.config.yaml` shipped with the site template:
+Below are the default `site.config.yaml` fields generated for an English site (`npx hd-garden init --locale en_US`):
 
 ```yaml
 name: Garden
-tagline: 写作 · 记录 · 保持好奇
-description: 文章、随想和专栏。
-locale: zh_CN
-# 站点的公开地址。文章里指向这个地址的完整网址会按站内链接显示。
+tagline: Writing · Notes · Staying curious
+description: Posts, short notes, and columns.
+locale: en_US
+# Public address of the site. Full URLs pointing here inside posts render as internal links.
 # url: https://blog.example.com
-# 站点图标，不写时使用 Garden 自带的图标。
+# Site icons; falls back to Garden's built-in icons when omitted.
 # brand:
 #   logo: brand/logo.svg
 #   favicon: /favicon.svg
@@ -28,44 +28,46 @@ locale: zh_CN
 author:
   name: Your Name
   github: your-github-id
-  githubBio: 一句自我介绍。
+  githubBio: A short bio.
   githubPinned: []
 
 pages:
   home:
     title: |-
-      记一些正在做的事，
-      和想清楚的问题。
-    subtitle: 软件、笔记，和偶尔的工作记录。
+      Notes on what I am building,
+      and questions worth thinking through.
+    subtitle: Software, reading notes, and occasional work logs.
   blog:
-    title: 博文
-    subtitle: 写完的长文。
+    title: Posts
+    subtitle: Finished long-form essays.
   thoughts:
-    title: 随想
-    subtitle: 短笔记、图片和链接。
+    title: Thoughts
+    subtitle: Short notes, images, and links.
+    # How many items to show per screen; the next screen loads automatically as you scroll. Default: 10.
+    # pageSize: 10
   columns:
-    title: 专栏
-    subtitle: 按顺序读的一组文章。
+    title: Columns
+    subtitle: Series of posts meant to be read in order.
   about:
-    title: 你好，我是 Your Name。
-    subtitle: 文章和笔记都在这里。
-    heading: 关于
+    title: Hi, I am Your Name.
+    subtitle: Essays and notes live here.
+    heading: About
     paragraphs:
-      - 一名工程师。平时写代码，也把想清楚的问题记下来。
-      - 这里放文章、随想和专栏。
+      - A software engineer writing code and keeping notes on things figured out along the way.
+      - This site holds long-form posts, short thoughts, and columns.
     quote: ""
     focus:
-      - 软件
-      - 笔记
-      - 日常
+      - Software
+      - Notes
+      - Daily
     cta:
       href: /blog
-      label: 浏览博文
+      label: Browse posts
   garden:
-    title: "用 Markdown 写。\n推送之后，网站自己更新。"
+    title: "Write in Markdown.\nPush to update the site."
     subtitle: ""
 
-footer: 持续记录。
+footer: Keep writing.
 ```
 
 ### Top-level and Author Fields
@@ -75,7 +77,7 @@ footer: 持续记录。
 | `name` | Site name shown in the top-left header, browser title suffix, and RSS feed title |
 | `tagline` | Site tagline |
 | `description` | Site summary used for the home page SEO description and RSS channel description |
-| `locale` | Language and region tag (`zh_CN` by default; setting `en_US` switches the site chrome to English at build time) |
+| `locale` | Language and region tag (`zh_CN` by default; setting `en_US` switches all framework-rendered UI strings—navigation, home page, post list, post metadata and permalink label, Giscus prompts, tags, columns, About page, 404 page, pagination, RSS/sitemap, and meta/og—to English at build time) |
 | `url` | Public root URL of the site (such as `https://blog.example.com`). Full URLs pointing to this address inside posts are treated as internal links |
 | `author.name` | Author name displayed in article metadata, the About page, and the footer |
 | `author.github` | GitHub username (without the full URL), used to link your GitHub profile and fetch public activity for the About page |
@@ -107,7 +109,7 @@ Columns group multiple posts from `content/posts/` into an ordered reading serie
 columns:
   - slug: building-in-public
     title: Building in Public
-    status: Ongoing
+    status: ongoing
     description: Notes from initial prototype to production release.
     cover: windowsill-herbs.svg
     posts:
@@ -120,6 +122,6 @@ columns:
 | `slug` | Yes | Column identifier (lowercase letters, digits, and hyphens only), generating routes at `/columns/<slug>/<post>` |
 | `title` | Yes | Column title (also shown beside member posts on `/blog`) |
 | `description` | Yes | Column summary shown on `/columns` cards |
-| `status` | No | Status badge text |
+| `status` | No | Status value: `default` (or omitted, shown as "Active"), `ongoing` ("Ongoing"), or `completed` ("Completed"). Legacy Chinese values are still accepted, and any other text is shown verbatim |
 | `cover` | No | Cover image path relative to `content/covers/` |
 | `posts` | Yes | Ordered array of post paths relative to `content/posts/`, without the `.md` extension |

package/docs/handbook/en/deploy.md

@@ -6,7 +6,7 @@ section: getting-started
 order: 4
 ---
 
-`npx hd-garden init` does not create `.github/workflows/pages.yml` automatically. Add this file to your site repository when you are ready to publish to GitHub Pages. The same workflow supports both a **single public repository** and a **private source repository + public Pages repository**, switching automatically based on whether the `PAGES_REPOSITORY` variable is set.
+Initializing an English site (`npx hd-garden init --locale en` or `--locale en_US`) installs `templates/workflows/pages.en.yml` to `.github/workflows/pages.yml` automatically (default `zh_CN` initialization does not create it automatically). Review or add this file in your site repository when you are ready to publish to GitHub Pages. The same workflow supports both a **single public repository** and a **private source repository + public Pages repository**, switching automatically based on whether the `PAGES_REPOSITORY` variable is set.
 
 The workflow below matches Garden's own `.github/workflows/pages.yml` with two adjustments for a site repo: it omits `paths-ignore`, `npm run lint`, and `npm test` (which only apply to the engine repo), and its `publish-repository` job installs dependencies before running `npx garden pages:prepare static-site pages-repository` (the same `scripts/prepare-pages-output.mjs` script Garden calls directly). Commit `package-lock.json` after your first `npm install` so `npm ci` can run in CI.
 
@@ -71,14 +71,14 @@ jobs:
               GISCUS_REPO_ID=
               GISCUS_CATEGORY=
               GISCUS_CATEGORY_ID=
-              echo "GISCUS_DISABLED=1，本次构建不开放评论。"
+              echo "GISCUS_DISABLED=1; building without comments."
             else
-              echo "评论还没有配置，构建已停止。"
-              echo "1. 准备一个公开 GitHub 仓库，并开启 Discussions。"
-              echo "2. 打开 https://giscus.app/zh-CN ，安装 Giscus App，选中该仓库和分类。"
-              echo "3. 在 Settings → Secrets and variables → Actions → Variables 写入："
-              echo "   GISCUS_REPO、GISCUS_REPO_ID、GISCUS_CATEGORY、GISCUS_CATEGORY_ID"
-              echo "确定不开放评论时，把 GISCUS_DISABLED 设为 1。留空和示例值 owner/repository 都不会通过。"
+              echo "Comments are not configured yet; stopping the build."
+              echo "1. Prepare a public GitHub repository and enable Discussions."
+              echo "2. Open https://giscus.app, install the Giscus App, and pick the repository and category."
+              echo "3. Under Settings -> Secrets and variables -> Actions -> Variables, set:"
+              echo "   GISCUS_REPO, GISCUS_REPO_ID, GISCUS_CATEGORY, GISCUS_CATEGORY_ID"
+              echo "To build without comments, set GISCUS_DISABLED to 1. Empty values and the placeholder owner/repository will not pass."
               exit 1
             fi
           fi
@@ -162,9 +162,9 @@ jobs:
           PAGES_DEPLOY_KEY: ${{ secrets.PAGES_DEPLOY_KEY }}
           TARGET_REPOSITORY: ${{ vars.PAGES_REPOSITORY }}
         run: |
-          test -n "$PAGES_DEPLOY_KEY" || { echo "缺少 PAGES_DEPLOY_KEY Secret"; exit 1; }
+          test -n "$PAGES_DEPLOY_KEY" || { echo "Missing PAGES_DEPLOY_KEY secret"; exit 1; }
           [[ "$TARGET_REPOSITORY" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || {
-            echo "PAGES_REPOSITORY 格式无效"
+            echo "Invalid PAGES_REPOSITORY format"
             exit 1
           }
 
@@ -189,7 +189,7 @@ jobs:
           expected_remote="git@github.com:$TARGET_REPOSITORY.git"
           actual_remote="$(git remote get-url origin)"
           test "$actual_remote" = "$expected_remote" || {
-            echo "拒绝发布到非目标仓库：$actual_remote"
+            echo "Refusing to publish to unexpected repository: $actual_remote"
             exit 1
           }
           echo "PAGES_PREVIOUS_TREE=$(git rev-parse 'HEAD^{tree}')" >> "$GITHUB_ENV"
@@ -207,7 +207,7 @@ jobs:
           git add -A
           new_tree="$(git write-tree)"
           if [ "$new_tree" = "$PAGES_PREVIOUS_TREE" ]; then
-            echo "静态产物没有变化，无需发布"
+            echo "Static output is unchanged; skipping publish"
             exit 0
           fi
           git commit -m "Deploy ${GITHUB_SHA}"

package/docs/handbook/en/design.md

@@ -36,18 +36,25 @@ When `npx garden sync` runs, the build script reads the pixel width and height o
 ```garden figure
 caption: Click the buttons above to inspect the three stages from build to browser render
 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. Build-time Sizing</text>
-    <text data-p="sync" x="110" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">Emit width / height &amp; --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. Client Measurement</text>
-    <text data-p="measure" x="340" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">Fit wide figures &amp; TOC</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. Dark Backing &amp; Zoom</text>
-    <text data-p="dark" x="570" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">Pad #faf9f5 · Click to zoom</text>
+  <svg viewBox="0 0 560 195" 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="187" 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. Build-time</text>
+    <text data-p="sync" x="92" y="72" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">Sizing</text>
+    <text data-p="sync" x="92" y="138" text-anchor="middle" font-size="24" fill="var(--muted)">Emit width /</text>
+    <text data-p="sync" x="92" y="167" text-anchor="middle" font-size="24" fill="var(--muted)">height &amp; --wl</text>
+    <path d="M183.5 97.5 H188.5" stroke="var(--muted)" stroke-width="2.5"/>
+    <rect data-p="measure" x="190" y="4" width="180" height="187" 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. Client</text>
+    <text data-p="measure" x="280" y="72" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">Measurement</text>
+    <text data-p="measure" x="280" y="138" text-anchor="middle" font-size="24" fill="var(--muted)">Fit wide</text>
+    <text data-p="measure" x="280" y="167" text-anchor="middle" font-size="24" fill="var(--muted)">figures &amp; TOC</text>
+    <path d="M371.5 97.5 H376.5" stroke="var(--muted)" stroke-width="2.5"/>
+    <rect data-p="dark" x="378" y="4" width="180" height="187" 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. Dark</text>
+    <text data-p="dark" x="468" y="72" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">Backing &amp;</text>
+    <text data-p="dark" x="468" y="102" text-anchor="middle" font-size="24" font-weight="600" fill="var(--ink)">Zoom</text>
+    <text data-p="dark" x="468" y="138" text-anchor="middle" font-size="24" fill="var(--muted)">Pad #faf9f5 ·</text>
+    <text data-p="dark" x="468" y="167" text-anchor="middle" font-size="24" fill="var(--muted)">Click to zoom</text>
   </svg>
 parts:
   - id: sync

package/docs/handbook/en/index.md

@@ -113,7 +113,7 @@ Write ` | ` (with spaces on both sides) inside a title to split it across two li
 
 Transparent-background line drawings automatically get a warm paper backing in dark mode, so you do not need separate dark assets:
 
-![Diagram of the 740px reading column, 1040px wide figure zone, and 1340px wide table zone (transparent-background dark-line SVG, backed with #faf9f5 in dark mode).](../assets/reading-layout.svg)
+![Diagram of the 740px reading column, 1040px wide figure zone, and 1340px wide table zone (transparent-background dark-line SVG, backed with #faf9f5 in dark mode).](../assets/reading-layout-en.svg)
 
 ## Wide Tables Expand Symmetrically
 
@@ -171,7 +171,7 @@ items:
     caption: Maximum width for wide multi-column tables expanding symmetrically on desktop
 ```
 
-See [Components Overview](/garden/en/components) in the sidebar for all 9 built-in components and their live examples.
+See [Components Overview](/garden/en/components) in the sidebar for all 12 built-in components and their live examples.
 
 <h2 id="garden-admin-title">From Init to Daily Writing</h2>
 

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

@@ -0,0 +1,85 @@
+---
+title: Component reference · card
+navTitle: card
+description: Summarize a paper, repository, or module in a card with metadata and numbered takeaways.
+section: reference
+order: 1
+badge: card
+---
+
+[← Component reference](/garden/en/reference) · [Usage: card](/garden/en/components/card)
+
+## Examples
+
+```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.
+```
+
+```garden card
+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: /images/garden/ref-card-book.svg
+    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: /images/garden/ref-card-lamp.svg
+    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."
+```
+
+## Syntax
+
+````markdown
+```garden card
+title:        # recommended, heading
+url:          # optional, heading link
+meta:         # optional, subtitle
+description:  # summary (or text)
+points:       # key points (or items)
+image:        # optional, thumbnail
+alt:          # optional, alt text
+source:       # optional, source URL
+site:         # optional, site name
+takeaway:     # optional, takeaway
+cards:        # multi-card mode, same keys
+  - url:      # card link
+```
+````
+
+## Fields
+
+Fence header: ` ```garden card ` (snippet trigger `;gcard`). Place fields at the top level for a single card, or pass a `cards` array for multiple horizontal row cards; invalid YAML or unknown top-level keys report `garden-yaml` on the block.
+
+| Field | Required | Default | Allowed Values & Limits | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `title` | Recommended | `url` | string | Card heading; falls back to `url` if omitted |
+| `url` | Optional | `""` | full `https://` or `http://` URL | External link on the heading; renders `title` as plain text if omitted |
+| `meta` | Optional | none | string | Subtitle or metadata line below the heading |
+| `description` | One of `description`, `points`, or `cards` | `""` | string (alias `text`) | Summary paragraph supporting inline bold and code |
+| `points` | One of `points`, `description`, or `cards` | `[]` | string[] or `{ title, text? }[]` (alias `items`; `2` to `4` points recommended, not checked) | Numbered list of takeaways below the summary |
+| `image` | Optional | none | image path or Data URL | Card thumbnail |
+| `alt` | Optional | `title` | string | Thumbnail alt text |
+| `source` | Optional | none | URL, `{ url, site?, icon? }`, or array | Source chip appended to `description`; multiple sources collapse to the first domain plus `+N` (such as `gutenberg.org +1`). `icon` defaults to the build-time downloaded favicon, then the uppercase first letter of the registrable domain's main label (e.g. `en.wikipedia.org` uses `W`, `bbc.co.uk` uses `B`) |
+| `site` | Optional | hostname of `url` without `www.` | string | Display name for the source site |
+| `takeaway` | Optional | none | string | One-line takeaway separated by a top border at the bottom of the card (e.g. `"**Worth borrowing:** ..."`) |
+| `cards` | Required for multi-card mode | none | object[] | Stack of horizontal row cards, each supporting `url`, `title`, `description` (or `text`), `image`, `alt`, `meta`, `source`, and `takeaway` |
+
+## Limits & errors
+
+- Apart from the shared `garden-yaml`, this component has no error codes of its own; values marked "not checked" in the table never report an error.

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

@@ -0,0 +1,68 @@
+---
+title: Component reference · chart
+navTitle: chart
+description: Render proportional horizontal bars with a built-in expandable data table underneath.
+section: reference
+order: 5
+badge: chart
+---
+
+[← Component reference](/garden/en/reference) · [Usage: chart](/garden/en/components/chart)
+
+## Examples
+
+```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.
+```
+
+## Syntax
+
+````markdown
+```garden chart
+type:       # optional, bar only
+title:      # recommended, heading
+data:       # either this or series
+  - x:      # name
+    y:      # value
+    label:  # optional, value label
+x:          # labels for series
+series:     # either this or data
+  - name:   # optional, name
+    data:   # numbers
+unit:       # optional, unit
+xLabel:     # optional, 1st column
+yLabel:     # optional, 2nd column
+caption:    # optional, caption
+```
+````
+
+## Fields
+
+Fence header: ` ```garden chart ` (snippet trigger `;gchart`). Provide rows via `data: [{ x, y, label? }]` or column arrays via `x` + `series`; invalid YAML or unknown top-level keys report `garden-yaml` on the block.
+
+| Field | Required | Default | Allowed Values & Limits | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `title` | Recommended | `"Chart"` for `aria-label` (no visible heading) | string | Heading above the chart |
+| `data` | Either `data` or `series` | `[]` | `{ x, y, label? }[]` (at least `2` rows and `2` to `8` rows recommended, not checked) | Row entries where `x` is the row label, `y` is the numeric value, and `label` defaults to `y` + `unit` |
+| `series` | Either `series` or `data` | none | `{ name?, data: number[] }[]` (at least `2` data points recommended, not checked) | Numeric series paired with an `x` label array (`series[0].data` is rendered) |
+| `x` | Optional | `["1", "2", ...]` (1-based row numbers) | string or string[] | Category labels when using `series`, or first-column header string when `xLabel` is omitted |
+| `type` | Optional | `"bar"` | `"bar"` | Chart type (horizontal bar chart) |
+| `unit` | Optional | `""` | string | Unit suffix appended to values when `data[].label` is omitted |
+| `xLabel` | Optional | string `x` or `"Item"` | string | Header for the first column of the expandable data table |
+| `yLabel` | Optional | `"Value"` | string | Header for the second column of the expandable data table |
+| `caption` | Optional | none | string | Caption below the chart |
+
+## Limits & errors
+
+- Apart from the shared `garden-yaml`, this component has no error codes of its own; values marked "not checked" in the table never report an error.