hd-garden 0.8.0 → 0.8.2

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

@@ -7,23 +7,29 @@ order: 36
 badge: figure
 ---
 
-Write "use `figure` to draw the static publishing flow where clicking each step highlights that box and shows what it does" inside a `garden` idea block, and the Agent generates the `garden figure` block below via the `garden-ui` skill (hand-written syntax follows).
-
 ```garden figure
 caption: Click the buttons above to highlight each stage
 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. garden sync</text>
-    <text data-p="sync" x="110" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">Parse Markdown &amp; image sizes</text>
-    <path d="M214 55 H236" stroke="var(--muted)" stroke-width="1.5"/>
-    <rect data-p="build" x="242" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
-    <text data-p="build" x="340" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">2. garden build</text>
-    <text data-p="build" x="340" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">Build static pages &amp; index</text>
-    <path d="M444 55 H466" stroke="var(--muted)" stroke-width="1.5"/>
-    <rect data-p="validate" x="472" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
-    <text data-p="validate" x="570" y="50" text-anchor="middle" font-size="14" font-weight="600" fill="var(--ink)">3. pages:validate</text>
-    <text data-p="validate" x="570" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">Check index.html &amp; files</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. 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
@@ -37,36 +43,17 @@ parts:
     text: Runs pages:validate to confirm `index.html` exists and no `.env`, source directories, `.map` or `.md` files, or symlinks are present.
 ```
 
+- **When to use**: Walking through module boundaries or data flow where clicking each button highlights the matching part of the diagram and explains its role.
+- **When to skip**: A static image or a `mermaid` diagram does not need interactive region highlighting.
+
+You can tell the AI:
+
 ````markdown
-```garden figure
-caption: Click the buttons above to highlight each stage
-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. garden sync</text>
-    <text data-p="sync" x="110" y="72" text-anchor="middle" font-size="12" fill="var(--muted)">Parse Markdown &amp; image sizes</text>
-    <rect data-p="build" x="242" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
-    <rect data-p="validate" x="472" y="18" width="196" height="74" rx="10" fill="var(--card)" stroke="var(--rule-strong)" stroke-width="1.5"/>
-  </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.
+```garden
+Draw a diagram of the three static publishing steps where clicking each step highlights that box and shows what it does.
 ```
 ````
 
-- **Use when**: Walking through module boundaries or data flow where clicking each button highlights the matching SVG elements and explains their role (use theme variables like `var(--well)`, `var(--ink)`, and `var(--muted)` inside SVG so dark mode works).
-- **Skip when**: A static image or a `mermaid` diagram does not need interactive region highlighting.
+## Fields
 
-| Field | Required | Type | Description |
-| :--- | :--- | :--- | :--- |
-| `svg` | Either this or `image` | multiline string | Inline `<svg>` markup; tag elements to highlight with `data-p="<id>"` |
-| `image` | Either this or `svg` | path string | Image path (or `{ src, alt }`) |
-| `parts` | No | `{ id, label, text }[]` | Buttons shown above the diagram and the matching explanation below |
-| `caption` | No | string | Caption below the frame |
+Every field, default, limit and error code is in [Component reference · figure](/garden/en/reference/figure).

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

@@ -7,28 +7,23 @@ order: 39
 badge: file
 ---
 
-Write "use `file` to attach a pre-publish checklist that readers can preview inline or download" inside a `garden` idea block, and the Agent generates the `garden file` block below via the `garden-ui` skill (hand-written syntax follows).
-
 ```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
 ```
 
+- **When to use**: Attaching config files, datasets, PDFs, archives, or Markdown documents for readers to download or preview inline.
+- **When to skip**: Referencing an external web page (use [`card`](/garden/en/components/card)) or showing a regular illustration in the middle of an article (use standard Markdown image syntax `![]()`).
+
+You can tell the AI:
+
 ````markdown
-```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
+```garden
+Attach checklist.md here so readers can preview it inline or download it.
 ```
 ````
 
-- **Use when**: Attaching config files, datasets, PDFs, images, or Markdown documents for readers to download or preview inline (use `files` for multiple attachments).
-- **Skip when**: Showing a regular illustration in the middle of an article; use standard Markdown image syntax `![]()` instead.
+## Fields
 
-| Field | Required | Type | Description |
-| :--- | :--- | :--- | :--- |
-| `src` | Required for single file | path or URL | Relative path (must stay inside the content root), `/public` path, or `https://` URL |
-| `title` | No | string | Display title (defaults to filename; serves as the group heading when using `files`) |
-| `note` | No | string | Short note shown below the filename |
-| `files` | Required for multi-file | `{ src, title?, note? }[]` | List of multiple attachments (mutually exclusive with top-level `src`) |
+Every field, default, limit and error code is in [Component reference · file](/garden/en/reference/file).

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

@@ -7,11 +7,8 @@ order: 37
 badge: html
 ---
 
-Write "use `html` to embed a small widget that counts characters as the reader types" inside a `garden` idea block, and the Agent generates the `garden html` block below via the `garden-ui` skill (hand-written syntax follows).
-
 ```garden html
 title: Character Count Widget
-height: 156
 code: |
   <!doctype html>
   <html lang="en">
@@ -36,34 +33,17 @@ code: |
   </html>
 ```
 
+- **When to use**: Running custom DOM scripts, Canvas animations, physical simulations, or self-contained HTML widgets.
+- **When to skip**: You only need sliders wired to a formula (use [`interactive`](/garden/en/components/interactive)) or a diagram with clickable regions (use [`figure`](/garden/en/components/figure)).
+
+You can tell the AI:
+
 ````markdown
-```garden html
-title: Character Count Widget
-height: 156
-code: |
-  <!doctype html>
-  <html lang="en">
-  <head><meta charset="utf-8" /></head>
-  <body>
-    <input id="txt" value="Keep your posts in a Git repository and push to deploy." />
-    <div>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>
+```garden
+Embed a small widget where typing in an input box updates the character count in real time.
 ```
 ````
 
-- **Use when**: Running custom DOM scripts, Canvas drawings, or self-contained HTML snippets (either inline via `code` or loaded from a sibling `.html` file via `src`).
-- **Skip when**: You only need sliders wired to a formula (use [`interactive`](/garden/en/components/interactive)) or a diagram with clickable regions (use [`figure`](/garden/en/components/figure)).
+## Fields
 
-| Field | Required | Type | Description |
-| :--- | :--- | :--- | :--- |
-| `src` | Either this or `code` | relative path | Path to a `.html` file in the same directory or sibling asset directory |
-| `code` | Either this or `src` | multiline string | Inline HTML markup (alias `html` is also accepted) |
-| `title` | Recommended | string | Header bar title and accessible `iframe` title |
-| `height` | No | number | Initial height in pixels (defaults to `260`; resizes to fit content after load) |
-| `caption` | No | string | Caption shown below the frame |
+Every field, default, limit and error code is in [Component reference · html](/garden/en/reference/html).

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

@@ -7,8 +7,6 @@ order: 38
 badge: interactive
 ---
 
-Write "let readers drag word count, reading speed, and image count sliders to see how estimated reading time changes" inside a `garden` idea block, and the Agent generates the `garden interactive` block below via the `garden-ui` skill (hand-written syntax follows).
-
 ```garden interactive #reading-time
 caption: "Example: estimate reading time from word count, reading speed, and image count. Numbers are illustrative only."
 ---
@@ -27,41 +25,17 @@ caption: "Example: estimate reading time from word count, reading speed, and ima
 </Chart>
 ```
 
-````markdown
-```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 }]} />
+- **When to use**: Explaining a multi-variable formula, capacity estimate, or parameter tradeoff where dragging a slider reveals how the output responds.
+- **When to skip**: A block has only `<Steps>` without any state or input control (fails with `steps-prose`), or every `<Let>` is a single multiplication like `a * b` (fails with `interactive-trivial`). Write plain prose in both cases.
 
-<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" />
+You can tell the AI:
 
-<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>
+````markdown
+```garden
+Let readers drag word count, reading speed, and image count sliders to see how estimated reading time changes.
 ```
 ````
 
-- **Use when**: Explaining a multi-variable formula, capacity estimate, or parameter tradeoff where dragging a slider reveals how the output responds.
-- **Skip when**: A block has only `<Steps>` without any state or input control (fails with `steps-prose`), or every `<Let>` is a single multiplication like `a * b` (fails with `interactive-trivial`). Write plain prose in both cases.
-
-Metadata goes above `---`, and declarative tags go below it:
-
-| Field or Tag | Required | Description |
-| :--- | :--- | :--- |
-| `#reading-time` | Recommended | Block identifier on the fence line (lowercase letters, digits, and hyphens) |
-| `caption` | Yes | One sentence explaining what the reader can observe |
-| `intent` | No | The original natural-language prompt this block was compiled from |
-| `expect` | No | Array of `{ given: {...}, name: expectedValue }` assertions checked by `garden ui check` |
-| `<State />` | Yes | Declares mutable state variables and their initial values, e.g. `<State words={6000} />` |
-| `<Let />` | No | Computes derived values or data arrays from state |
-| `<Slider />` / `<Choice />` / `<Toggle />` | Yes | Input controls bound to a state variable via `bind`; `Slider` requires `label`, `min`, and `max` |
-| `<Stat />` | No | Displays a highlighted computed value; requires `label` and `value` |
-| `<Chart />` | No | Plots a function curve with `sweep` or a bar/line chart with `data` and `<Bar>` / `<Line>` |
+## Fields
 
-Run `npx garden ui catalog` to inspect the full tag and attribute reference in `.garden/ui-catalog.html`.
+Every field, default, limit and error code is in [Component reference · interactive](/garden/en/reference/interactive).

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

@@ -0,0 +1,65 @@
+---
+title: Icon List (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: components
+order: 41
+badge: 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
+```
+
+- **When to use**: Listing parallel actions, signals, or practices paired with an icon, or grouping titled steps with one or more paragraphs each.
+- **When to skip**: Items follow a strict numbered sequence or chronological order; use a standard ordered list or [`timeline`](/garden/en/components/timeline) instead.
+
+You can tell the AI:
+
+````markdown
+```garden
+List the four things a newcomer usually does before signing up, each paired with a small icon.
+```
+````
+
+## Divided Step List with Headings
+
+When any item includes `title`, the component switches to a divided step list where `text` can hold multiple paragraphs:
+
+```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.
+```
+
+You can tell the AI:
+
+````markdown
+```garden
+Organize these three small experiments into an icon list with a heading and two short notes per item.
+```
+````
+
+## Fields
+
+Every field, default, limit and error code is in [Component reference · list](/garden/en/reference/list).

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

@@ -0,0 +1,95 @@
+---
+title: Relationship diagram (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: components
+order: 40
+badge: 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
+  - from: 2
+    to: 4
+    style: dashed
+caption: The four steps feed each other instead of running once in a fixed order.
+```
+
+- **When to use**: Three to six key elements where the reader needs to see what influences what, which links run both ways, how steps form a repeating loop, or how one central element connects to the rest.
+- **When to skip**: There are more elements, branches, or one-pass steps; use a `mermaid` flowchart for larger or branching diagrams, or [`list`](/garden/en/components/list) for one-pass steps.
+
+You can tell the AI:
+
+````markdown
+```garden
+Draw how picking, reading, talking, and reviewing feed into each other as a loop, and show that talking also shapes the next pick.
+```
+````
+
+## Center Node & Outer Ring (`center`)
+
+When one element sits in the middle and holds the others together, set `center: <number|title>` between `items` and `links` (there is no auto-detection; that element goes in the middle while the remaining elements are spaced evenly on the outer ring starting at the top, clockwise):
+
+```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.
+```
+
+You can tell the AI:
+
+````markdown
+```garden
+Put the organiser in the center with members, venue, and reading list around them: the organiser invites members, books the venue, and collects the reading list, while members and the reading list nominate each other.
+```
+````
+
+Elements sit evenly on an ellipse starting at the top (12 o'clock) then clockwise (or with `center` in the middle and the remaining elements spaced evenly on the outer ring starting at the top, clockwise); links between neighbouring outer-ring elements bow gently outward, while non-neighbour or center links go straight through the middle.
+
+## Fields
+
+Every field, default, limit and error code is in [Component reference · relations](/garden/en/reference/relations).

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

@@ -7,8 +7,6 @@ order: 32
 badge: stat
 ---
 
-Write "use `stat` to list the width limits for the prose column, wide figures, and wide tables" inside a `garden` idea block, and the Agent generates the `garden stat` block below via the `garden-ui` skill (hand-written syntax follows).
-
 ```garden stat
 items:
   - label: Reading Column
@@ -25,33 +23,17 @@ items:
     caption: Extends up to 300px on each side
 ```
 
+- **When to use**: Pulling 2 to 4 core numbers, thresholds, or specs out of prose so readers can scan them side by side.
+- **When to skip**: You only have one number (keep it in prose), the number changes with user input (use [`interactive`](/garden/en/components/interactive)), or you have multiple rows and columns (use a Markdown table).
+
+You can tell the AI:
+
 ````markdown
-```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
+```garden
+Put the three width limits for the reading column, wide figures, and wide tables side by side so they are easy to scan.
 ```
 ````
 
-- **Use when**: Pulling 2 to 4 core numbers, thresholds, or specs out of prose so readers can scan them side by side.
-- **Skip when**: You only have one number (keep it in prose) or you have multiple rows and columns (use a Markdown table).
+## Fields
 
-| Field | Required | Type | Description |
-| :--- | :--- | :--- | :--- |
-| `items` | No | object[] | Array of stat items; for a single stat you can place the fields at the top level |
-| `label` | Yes | string | Metric name shown above the number |
-| `value` | Yes | string or number | Primary figure rendered in large tabular type |
-| `unit` | No | string | Unit shown immediately to the right of `value` |
-| `caption` | No | string | Short note below the figure |
-| `text` | No | string | Additional explanatory text |
-| `source` | No | string or `{ title, url }` | Source attribution badge |
+Every field, default, limit and error code is in [Component reference · stat](/garden/en/reference/stat).

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

@@ -7,8 +7,6 @@ order: 34
 badge: timeline
 ---
 
-Write "use `timeline` to list the three stages of the static publishing pipeline in order" inside a `garden` idea block, and the Agent generates the `garden timeline` block below via the `garden-ui` skill (hand-written syntax follows).
-
 ```garden timeline
 title: Static Publishing Pipeline Stages
 items:
@@ -23,30 +21,17 @@ items:
     text: Run `npm run pages:validate` to confirm `index.html` exists and no `.env`, source directories, `.map` or `.md` files, or symlinks were included, then publish to GitHub Pages.
 ```
 
+- **When to use**: Walking through incident timestamps, evolution stages, or pipeline steps in chronological order.
+- **When to skip**: Listing unordered points with no sequence; use a regular bullet list or [`list`](/garden/en/components/list) instead.
+
+You can tell the AI:
+
 ````markdown
-```garden timeline
-title: Static Publishing Pipeline Stages
-items:
-  - date: Step 1
-    title: Sync Content and Assets
-    text: Run `npx garden sync` to validate Front Matter, copy image attachments, and generate the search index and RSS feed.
-  - date: Step 2
-    title: Build Static Site Output
-    text: Run `STATIC_EXPORT=1 npx garden build` to prerender every route into `dist/client/`.
-  - date: Step 3
-    title: Validate Output and Deploy
-    text: Run `npm run pages:validate` to confirm `index.html` exists and no `.env`, source directories, `.map` or `.md` files, or symlinks were included, then publish to GitHub Pages.
+```garden
+List the three stages of static publishing in order as a timeline.
 ```
 ````
 
-- **Use when**: Walking through incident timestamps, evolution stages, or pipeline steps in chronological order (at least 2 items).
-- **Skip when**: Listing unordered points with no sequence; use a regular bullet list instead.
+## Fields
 
-| Field | Required | Type | Description |
-| :--- | :--- | :--- | :--- |
-| `title` | No | string | Heading above the timeline |
-| `items` | Yes | object[] (at least 2) | Ordered list of steps |
-| `items[].date` | No | string | Timestamp, stage label, or step number above the item title |
-| `items[].title` | Yes | string | Step heading |
-| `items[].text` | No | string | Detailed explanation for the step |
-| `items[].source` | No | string or `{ title, url }` | Source attribution badge |
+Every field, default, limit and error code is in [Component reference · timeline](/garden/en/reference/timeline).