hd-garden 0.8.0 → 0.8.2

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

@@ -0,0 +1,69 @@
+---
+title: Component reference · 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: reference
+order: 12
+badge: choice
+---
+
+[← Component reference](/garden/en/reference) · [Usage: choice](/garden/en/components/choice)
+
+## Examples
+
+```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.
+```
+
+## Syntax
+
+````markdown
+```garden choice
+title:      # optional, question
+items:      # required, 2–3 suggested
+  - icon:   # optional, one of 23 icons
+    value:  # recommended, big value
+    text:   # recommended, short note
+    label:  # optional, preference tag
+    reply:  # optional, reply
+none:       # optional, fallback button
+  label:    # button text
+  reply:    # optional, reply
+caption:    # optional, caption
+```
+````
+
+## Fields
+
+Fence header: ` ```garden choice ` (snippet trigger `;gchoice`). Renders as an accessible `role="radiogroup"` with arrow-key navigation; cards sit side by side on desktop and stack vertically in a single column on narrow screens. Invalid YAML or unknown top-level keys report `garden-yaml` on the block.
+
+| Field | Required | Default | Allowed Values & Limits | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `title` | Optional | `""` | string | Question or heading above the option cards |
+| `items` | Required | `[]` | object[] (`2` to `3` items recommended, not checked) | Option cards |
+| `items[].icon` | Optional | none (draws no icon) | one of the 23 built-in icon names | Line icon at the top of the card (shares the same 23 icon names as `garden list`) |
+| `items[].value` | Recommended | none | string or number | Prominent price, figure, or short headline on the card |
+| `items[].text` | Recommended | none | string | One-sentence description of the option |
+| `items[].label` | Optional | none | string | Preference tag with a dot indicator at the bottom of the card |
+| `items[].reply` | Optional | `""` | string | Response shown below the group when this card is selected |
+| `none` | Optional | none | `{ label: string, reply?: string }` | Full-width single-line fallback button underneath the cards (such as `"Neither / not sure"`) and its selection reply |
+| `caption` | Optional | none | string | Caption below the component |
+
+## 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/compare.md

@@ -0,0 +1,59 @@
+---
+title: Component reference · compare
+navTitle: compare
+description: Place two or three options side by side to contrast tradeoffs, or stack good and bad practices.
+section: reference
+order: 3
+badge: compare
+---
+
+[← Component reference](/garden/en/reference) · [Usage: compare](/garden/en/components/compare)
+
+## Examples
+
+```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.
+```
+
+```garden compare
+items:
+  - 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?”"
+```
+
+## Syntax
+
+````markdown
+```garden compare
+items:        # required, 2–3 items
+  - title:    # option name
+    text:     # description
+    verdict:  # optional, good | bad
+    <key>:    # optional, as a tag
+```
+````
+
+## Fields
+
+Fence header: ` ```garden compare ` (snippet trigger `;gcompare`). Invalid YAML or unknown top-level keys report `garden-yaml` on the block.
+
+| Field | Required | Default | Allowed Values & Limits | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `items` | Required | `[]` | array (at least `2` items and `2` to `3` in side-by-side mode recommended, not checked) | Options to compare; each entry can be an object or a single `"Title: description"` string |
+| `items[].title` | Recommended | `""` (text before `:` in single-line string form) | string | Item heading |
+| `items[].text` | Recommended | `[]` | string or string[]; in side-by-side mode, combined `text` and extra string fields per cell must be at most `60` characters (exceeding this reports `compare-long`) | Item description; in single-line `"Title: description"` form only the text after `:` counts toward the `60`-character limit |
+| `items[].verdict` | Optional | none (side-by-side layout) | `"good"` \| `"bad"` | Marks the item as a recommended practice (green check) or anti-pattern (red cross); when any item has `verdict`, items stack vertically and the `60`-character `compare-long` limit does not apply |
+| `items[].<customKey>` | Optional | none | string or number (in side-by-side mode, string values count toward the `60`-character cell limit and report `compare-long` if exceeded) | In side-by-side mode, extra key-value pairs render as attribute tags at the bottom of the card |
+
+## Limits & errors
+
+- `compare-long`: in side-by-side mode, one cell's `text` plus its other string fields runs past 60 characters. Move that cell back into a list or paragraph.
+- When any item has `verdict: good | bad`, the group stacks vertically and the 60-character check is skipped.

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

@@ -0,0 +1,84 @@
+---
+title: Component reference · figure
+navTitle: figure
+description: Pair an SVG diagram with step buttons that highlight each region and show its explanation.
+section: reference
+order: 6
+badge: figure
+---
+
+[← Component reference](/garden/en/reference) · [Usage: figure](/garden/en/components/figure)
+
+## Examples
+
+```garden figure
+caption: Click the buttons above to highlight each stage
+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)">index.html &amp;</text>
+    <text data-p="validate" x="468" y="166" text-anchor="middle" font-size="24" fill="var(--muted)">files</text>
+  </svg>
+parts:
+  - id: sync
+    label: 1. Sync Content
+    text: Scans `content/` and `docs/handbook/`, copies sidecar assets, and generates `.garden/generated-content.ts`.
+  - id: build
+    label: 2. Build Pages
+    text: Prerenders all routes with `STATIC_EXPORT=1` and outputs RSS, sitemap, and full-text search indexes.
+  - id: validate
+    label: 3. Validate Export
+    text: Runs pages:validate to confirm `index.html` exists and no `.env`, source directories, `.map` or `.md` files, or symlinks are present.
+```
+
+## Syntax
+
+````markdown
+```garden figure
+svg: |      # one of three, inline SVG
+image:      # one of three, image path
+mermaid: |  # one of three, Mermaid
+alt:        # optional, alt text
+parts:      # optional, buttons
+  - id:     # matches data-p
+    label:  # required, button (or name)
+    text:   # required, description
+caption:    # optional, caption
+```
+````
+
+## Fields
+
+Fence header: ` ```garden figure ` (snippet trigger `;gfigure`). Invalid YAML or unknown top-level keys report `garden-yaml` on the block.
+
+| Field | Required | Default | Allowed Values & Limits | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `svg` | One of `svg`, `image`, or `mermaid` | `<svg>` body below `---` or `""` | multiline `<svg>` string | Inline SVG markup; tag elements to highlight with `data-p="<id>"` (use CSS variables such as `var(--card)`, `var(--ink)`, and `var(--muted)` so dark mode works) |
+| `image` | One of `image`, `svg`, or `mermaid` | none | path string | Path to a static diagram image |
+| `alt` | Optional | `caption` (then `""`) | string | Alt text for `image` |
+| `mermaid` | One of `mermaid`, `svg`, or `image` | none | multiline string | Mermaid diagram source |
+| `parts` | Optional | `[]` (initial selection defaults to `parts[0].id` or `"all"`) | object[] | Interactive buttons above the diagram and matching explanations below |
+| `parts[].id` | Recommended | `parts[].name` or `parts[].label` | string | Matches `data-p` on SVG elements (an id of `"all"` highlights every region) |
+| `parts[].label` | Required (or `name`) | `"Part N"` (1-based) | string | Button label |
+| `parts[].text` | Required | `""` | string | Explanation shown below the diagram when the button is active |
+| `caption` | Optional | none | string | Caption below the frame |
+
+## 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/file/checklist.md

@@ -0,0 +1,17 @@
+# Site Pre-publish Checklist
+
+Before running `make update` to push changes, verify the following items:
+
+## 1. Post Front Matter and Paths
+
+- [x] `title`, `date`, and `description` are filled in, and the filename uses only lowercase letters, digits, and hyphens
+- [x] Local images and attachments live in the post's sidecar folder and use `./<slug>/file.ext` relative paths
+- [x] `draft: true` has been removed from posts ready to publish
+
+## 2. Local Validation Commands
+
+| Command | What It Checks |
+| :--- | :--- |
+| `npx garden check content/posts/<slug>.md` | Checks a single post's component fields, code diffs, and local asset paths |
+| `make check` | Runs `npx garden sync && npx garden build` to validate the full site build |
+| `CONTENT_INCLUDE_DRAFTS=1 make dev` | Previews drafts and scheduled posts locally |

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

@@ -0,0 +1,50 @@
+---
+title: Component reference · file
+navTitle: file
+description: Attach one or more files with automatic format and size badges, download links, and inline preview.
+section: reference
+order: 9
+badge: file
+---
+
+[← Component reference](/garden/en/reference) · [Usage: file](/garden/en/components/file)
+
+## Examples
+
+```garden file
+src: ./file/checklist.md
+title: Pre-publish Checklist
+note: Sample Markdown attachment; click Preview to read inline or Download to save the file
+```
+
+## Syntax
+
+````markdown
+```garden file
+src:        # required for one file
+title:      # optional, title
+note:       # optional, short note
+files:      # required for a group
+  - src:    # required, path
+    title:  # optional, file name
+    note:   # optional, note
+```
+````
+
+## Fields
+
+Fence header: ` ```garden file ` (snippet trigger `;gfile`). Use top-level `src` for a single file, or `files` for multiple attachments; invalid YAML or unknown top-level keys report `garden-yaml` on the block.
+
+| Field | Required | Default | Allowed Values & Limits | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `src` | Required for single file | none | relative path, `/public` path, or `https://` URL; missing `src` or combining `src` with `files` reports `garden-file`, local paths outside `content/` report `file-outside`, missing local files report `missing-asset`, and a local file over `5 MB` reports a `file-large` warning | Attachment path |
+| `title` | Optional | decoded filename from `src` (single file) or `""` (multi-file) | string | Display title for a single file, or group heading when using `files` |
+| `note` | Optional | `""` | string (combining top-level `note` with `files` reports `garden-file`) | Short note shown below the filename in single-file mode |
+| `files` | Required for multi-file | none | `{ src, title?, note? }[]` (at least `1` item; empty array, non-array, combining with top-level `src`/`note`, item missing `src`, unknown item keys, or hand-writing `resolved` reports `garden-file`) | List of attachments, each requiring `src` with optional `title` (defaults to filename) and `note` (defaults to `""`) |
+
+## Limits & errors
+
+- `garden-file`: neither `src` nor `files`; `files` empty or not a list; `files` together with a top-level `src` / `note`; an entry without `src` or with unknown keys; a hand-written `resolved`.
+- `file-outside`: a local path leaves the `content/` folder.
+- `missing-asset`: the local file does not exist.
+- `file-large` (warning): a single file is over 5 MB.

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

@@ -0,0 +1,62 @@
+---
+title: Component reference · html
+navTitle: html
+description: Run a self-contained HTML, CSS, and JavaScript demo inside a sandboxed iframe.
+section: reference
+order: 7
+badge: html
+---
+
+[← Component reference](/garden/en/reference) · [Usage: html](/garden/en/components/html)
+
+## Examples
+
+```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>
+```
+
+## Syntax
+
+````markdown
+```garden html
+src:     # either this or code, path
+code: |  # either this or src, HTML
+title:   # recommended, frame title
+```
+````
+
+## Fields
+
+Fence header: ` ```garden html ` (snippet trigger `;ghtml`). Invalid YAML or unknown top-level keys report `garden-yaml` on the block.
+
+| Field | Required | Default | Allowed Values & Limits | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `src` | Either `src` or `code` | none | relative path (e.g. `./demo.html`) | Path to a standalone `.html` file inside the post's sidecar directory |
+| `code` | Either `code` or `src` | HTML body below `---` or `""` | multiline HTML string | Inline HTML markup (runs inside a sandboxed `iframe` and resizes to fit its content when `<script>` is present; HTML can also be placed below a `---` separator) |
+| `title` | Recommended | `"HTML"` | string | Frame header title and accessible `iframe` title |
+
+## 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/interactive.md

@@ -0,0 +1,71 @@
+---
+title: Component reference · interactive
+navTitle: interactive
+description: Let readers drag sliders or switches to recalculate formulas and charts in real time.
+section: reference
+order: 8
+badge: interactive
+---
+
+[← Component reference](/garden/en/reference) · [Usage: interactive](/garden/en/components/interactive)
+
+## Examples
+
+```garden interactive #reading-time
+caption: "Example: estimate reading time from word count, reading speed, and image count. Numbers are illustrative only."
+---
+<State words={6000} speed={400} images={8} />
+<Let textMinutes={round(words / speed)} />
+<Let imageMinutes={round(images * 12 / 60)} />
+<Let parts={[{ part: "Prose", minutes: textMinutes }, { part: "Images", minutes: imageMinutes }]} />
+
+<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" />
+<Slider bind="images" label="Image count" min={0} max={30} step={1} unit="images" />
+
+<Stat label="Example: estimated reading time" value={textMinutes + imageMinutes} unit="min" hint="Counting 12 seconds per image" />
+<Chart data={parts} x={part} yLabel="min">
+  <Bar y={minutes} label="Example" />
+</Chart>
+```
+
+## Syntax
+
+````markdown
+```garden interactive #<id>
+caption:               # required, default reading
+intent: |              # optional, original idea
+expect:                # optional, assertions
+---                    # tags go below
+<State ... />          # required, state
+<Let ... />            # optional, derived values
+<Slider bind="..." />  # input control
+<Stat ... />           # output
+```
+````
+
+## Fields
+
+Fence header: ` ```garden interactive #<id> ` (snippet trigger `;ginteractive`). YAML metadata goes above `---` and declarative UI tags go below `---` (run `npx garden ui catalog` to inspect all internal tags in `.garden/ui-catalog.html`); invalid YAML or unknown top-level keys report `garden-yaml` on the block.
+
+| Field or Tag | Required | Default | Allowed Values & Limits | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `#<id>` / `id` | Required | none | lowercase letters, digits, hyphens `^[a-z0-9]+(?:-[a-z0-9]+)*$`, unique per post; missing or invalid reports `ui-id` | Written on the fence line (such as `#reading-time`) or in the YAML header |
+| `caption` | Required | none | non-empty one-sentence takeaway string; missing or empty reports `ui-caption` | States the conclusion visible in the default state |
+| `intent` | Optional | none | string (non-string reports `ui-header`; modified `intent` without recompiling reports a `ui-stale` warning) | Original natural-language prompt this block was compiled from |
+| `expect` | Optional | none | `{ given: {...}, <name>: <expected> }[]` (non-array reports `ui-header`; malformed or failing assertion reports `ui-expect`) | Numeric assertions verified by `npx garden ui check` (use `{ value, tol }` for approximate values) |
+| `<State />` | Required | none | lowercase-initial prop names with number, string, or boolean literal defaults (invalid name, duplicate name, or non-literal reports `ui-prop`) | Declares mutable state variables and default values, e.g. `<State words={6000} />` |
+| `<Let />` | Optional | none | expression props (unknown identifier or disallowed syntax reports `ui-expr`, cyclic dependency reports `ui-cycle`, evaluation failure reports `ui-eval`, single-multiplication-only block reports `interactive-trivial`) | Computes derived numbers, arrays, or objects from state |
+| `<Data />` | Optional | none | `name` (valid identifier) and `src` (`.csv` or `.json` inside the post's sidecar directory; out-of-bounds, missing, or invalid file reports `ui-data`) | Loads a sidecar data file |
+| `<Slider />` / `<Stepper />` / `<Toggle />` | At least one input control | `Slider`: `scale="linear"`, `snap="none"` (`"pow2"` when `scale="log"` and bounds are powers of 2); `Stepper`: `step={1}` | `bind` must reference a declared state variable of matching type (otherwise `ui-bind`); `max <= min`, `scale="log"` with `min <= 0`, or default outside `min..max` reports `ui-prop` | Input controls bound to numeric or boolean state |
+| `<Choice />` / `<Checklist />` / `<Button />` | Optional input controls | `Button`: `tone="plain"` | `<Choice>` `options` must have `2` to `8` items (outside `2`–`8` reports `ui-limit`, default not in `options` reports `ui-prop`); `<Checklist>` `items` must have `1` to `30` items (outside `1`–`30` reports `ui-limit`); `<Button>` requires exactly one of `set` or `reset` (otherwise `ui-prop`) | Segmented/dropdown selector, interactive checklist, and state button |
+| `<Stack />` / `<Columns />` / `<Tabs />` / `<Steps />` | Optional layout containers | `Stack`: `gap={3}`, `direction="col"`; `Columns`: `gap={3}`, `min={220}`; `Steps`: `autoplay={false}` | `gap` `0`–`4` integer, `Columns.min` `160`–`400`, `Steps.autoplay` `false` or `>= 800` (violation reports `ui-prop`); `<Columns>` max `4` children, `<Tabs>` `2`–`6` `<Tab>` children, `<Steps>` `2`–`24` `<Step>` children (outside limits reports `ui-limit`, wrong child tag reports `ui-children`, prose-only steps with no state changes report `steps-prose`) | Layout containers (for `<Each>` over `200` items, only the first `200` are shown with no `ui-limit`; total expanded elements across the block max `200`, exceeding reports `ui-limit`) |
+| `<Stat />` / `<Meter />` / `<Chart />` / `<Pie />` | At least one output view | `Stat`: `tone="plain"`, `size="md"`; `Meter`: `tone="accent"`; `Chart`: `samples={64}`, `yScale="linear"`, `height={200}` | `<Meter>` `parts` max `5` segments, `<Pie>` `1`–`8` `<Slice>` children, `<Chart>` `1`–`4` series children and `data` max `2000` rows (exceeding reports `ui-limit`); `<Chart>` `samples` `2`–`200` and `height` `120`–`480` (outside range reports `ui-prop`) | Displays computed metrics, progress meters, donut charts, and function/data charts |
+| `<Table />` / `<Grid />` / `<Image />` / `<Code />` / `<Diagram />` / `<Sandbox />` | Optional display views | none | `<Table>` max `50` rows, `<Grid>` `cols` max `16` columns and `1`–`16` `<Row>` children, `<Image>` max `12` `<Hotspot>` children, `<Code>` max `60` lines, `<Sandbox>` `html` max `12000` chars and `css`/`js` max `8000` chars each (exceeding reports `ui-limit`; unknown tag reports `ui-component`; headings, code fences, HTML, or Markdown images in the body report `ui-markdown`; JSX syntax or spread props report `ui-syntax`) | Tables, inspection grids, hotspot images, code walkthroughs, Mermaid state diagrams, and self-contained sandboxes |
+
+## Limits & errors
+
+- Header: `ui-id` (missing or malformed id), `ui-caption` (missing caption), `ui-header` (`intent` not a string or `expect` not a list), `ui-expect` (malformed or failing assertion), `ui-stale` (warning: the idea changed but was not recompiled).
+- Tags: `ui-prop`, `ui-expr`, `ui-cycle`, `ui-eval`, `ui-data`, `ui-bind`, `ui-limit`, `ui-children`, `ui-component`, `ui-markdown`, `ui-syntax`; see the table above for what triggers each.
+- Whole block: `interactive-trivial` (a single simple multiplication), `steps-prose` (steps that are only prose, with no state change).
+- Run `npx garden ui check` to get a fix prompt.

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

@@ -0,0 +1,72 @@
+---
+title: Component reference · list
+navTitle: list
+description: Pair line icons with short observations in a compact card, or add headings and multi-paragraph notes for divided steps.
+section: reference
+order: 11
+badge: list
+---
+
+[← Component reference](/garden/en/reference) · [Usage: list](/garden/en/components/list)
+
+## Examples
+
+```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
+```
+
+```garden list
+items:
+  - icon: flask
+    title: "Experiment 1: is one book a month too much?"
+    text:
+      - Pick a novella and a long novel for the first two meetings, and record how many people finish.
+      - If the share drops clearly, read only the first half next time.
+  - icon: chat
+    title: "Experiment 2: how do we get first-timers talking?"
+    text:
+      - Open half of the meetings with one sentence from each person, and the other half with free discussion.
+      - Compare how often first-timers speak.
+  - icon: bell
+    title: "Experiment 3: how early should the reminder go out?"
+    text:
+      - Send the reminder three days before one meeting and one day before another, and compare turnout.
+```
+
+## Syntax
+
+````markdown
+```garden list
+title:      # optional, heading
+items:      # required, items
+  - icon:   # optional, one of 23 icons
+    title:  # optional, switches layout
+    text:   # recommended, description
+caption:    # optional, caption
+```
+````
+
+## Fields
+
+Fence header: ` ```garden list ` (snippet trigger `;glist`). Invalid YAML or unknown top-level keys report `garden-yaml` on the block.
+
+| Field | Required | Default | Allowed Values & Limits | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `title` | Optional | none | string | Heading above the list |
+| `items` | Required | `[]` | object or string array | List entries; renders as a compact icon card when no item has `title`, or a divided step list when any item has `title` |
+| `items[].icon` | Optional | none (draws no icon) | one of the 23 built-in icon names: `search`, `eye`, `heart`, `chat`, `shield`, `wallet`, `bell`, `check`, `x`, `star`, `flag`, `clock`, `idea`, `book`, `link`, `user`, `chart`, `gear`, `file`, `pin`, `flask`, `target`, `question` | Line icon name (unknown names render nothing) |
+| `items[].title` | Optional | none (compact row layout) | string | Item heading; switches the block to the divided step layout |
+| `items[].text` | Recommended | `[]` | string or string[] | Item body text; each array element renders as its own paragraph |
+| `caption` | Optional | none | string | Caption below the list |
+
+## 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/relations.md

@@ -0,0 +1,113 @@
+---
+title: Component reference · relations
+navTitle: relations
+description: Place 3 to 6 elements on an ellipse or around a center node and connect them with solid or dashed, one-way or two-way labeled links.
+section: reference
+order: 10
+badge: relations
+---
+
+[← Component reference](/garden/en/reference) · [Usage: relations](/garden/en/components/relations)
+
+## Examples
+
+```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
+  - from: 2
+    to: 4
+    style: dashed
+caption: The four steps feed each other instead of running once in a fixed order.
+```
+
+```garden relations
+items:
+  - title: Organiser
+    text: Sends one notice a month
+  - title: Members
+    text: Eight to ten neighbours
+  - title: Venue
+    text: Café or library
+  - title: Reading list
+    text: Members take turns to nominate
+center: Organiser
+links:
+  - from: 1
+    to: 2
+    label: invites
+  - from: 1
+    to: 3
+    label: books
+  - from: 1
+    to: 4
+    label: collects
+  - from: 2
+    to: 4
+    style: dashed
+    direction: both
+    label: nominate
+caption: The organiser sits in the center and links to the other three; members and the list shape each other.
+```
+
+## Syntax
+
+````markdown
+```garden relations
+title:          # optional, aria only
+items:          # required, 3–6
+  - title:      # required, name
+    text:       # optional, short note
+center:         # optional, # or title
+links:          # optional, list
+  - from:       # required, # or title
+    to:         # required, not from
+    style:      # solid | dashed
+    direction:  # one | both
+    label:      # optional, short label
+caption:        # optional, caption
+```
+````
+
+## Fields
+
+Fence header: ` ```garden relations ` (snippet trigger `;grel`). Nodes have no emphasis or accent option—every element carries equal visual weight; ` ```mermaid ` fences are supported for any other diagram, and `garden list` covers one-pass steps. Invalid YAML or unknown top-level keys report `garden-yaml` on the block.
+
+| Field | Required | Default | Allowed Values & Limits | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `title` | Optional | `"Relationship diagram"` for `aria-label` (no visible heading) | string | Heading above the diagram |
+| `items` | Required | none | object[], strictly `3` to `6` items (fewer than `3` or more than `6` items reports `garden-relations`) | Elements in the diagram; when `center` is omitted, all items are spaced evenly on an ellipse starting at the top (12 o'clock), clockwise |
+| `items[].title` | Required | `""` | string | Node heading (`links` and `center` reference items by 1-based number or exact `title`) |
+| `items[].text` | Optional | `""` | string | Short note below the node heading |
+| `center` | Optional | none (all items on the outer ellipse) | `1..N` (1-based number) or exact item `title` (an unknown index or title reports `garden-relations`) | Placed between `items` and `links`: puts that element in the middle and spaces the remaining elements evenly on the outer ring starting at the top, clockwise; no auto-detection |
+| `links` | Optional | `[]` | object[] (non-array or entry with unknown keys reports `garden-relations`) | Directed or bidirectional links between elements; neighbour outer-ring links bow outward while others run straight through the middle; write a repeating loop by listing each step (`1->2`, `2->3`, `3->4`, `4->1`) |
+| `links[].from` | Required | none | `1..N` (1-based number) or exact item `title`, cannot equal `to` (missing, unknown target, or `from === to` reports `garden-relations`) | Source element |
+| `links[].to` | Required | none | `1..N` (1-based number) or exact item `title`, cannot equal `from` (missing, unknown target, or `from === to` reports `garden-relations`) | Target element |
+| `links[].style` | Optional | `"solid"` | `"solid"` \| `"dashed"` (any other value reports `garden-relations`) | Solid line (`→` / `↔`) or dashed line (`⇢` / `⇠⇢`) |
+| `links[].direction` | Optional | `"one"` | `"one"` \| `"both"` (any other value reports `garden-relations`) | One-way arrow toward `to` or arrowheads on both ends |
+| `links[].label` | Optional | `""` | short string (non-string value reports `garden-relations`) | Short label along the line (dodges line crossings; when it does not fit on its line it becomes a circled number listed under the graph, e.g. `① limits: Budget → Venue`) |
+| `caption` | Optional | none | string | Caption below the diagram |
+
+## Limits & errors
+
+- `garden-relations`: fewer than 3 or more than 6 `items`; `center` matches no item; `links` is not a list or an entry has unknown keys; `from` / `to` missing, unknown or equal; a wrong `style` or `direction`; a `label` that is not a string.
+- For more elements or branches, use a ```` ```mermaid ```` flowchart; for one-pass steps, use `garden list`.