hd-garden 0.13.3 → 0.14.2

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

@@ -1,49 +0,0 @@
----
-title: Embedded Web Snippet (html)
-navTitle: html
-description: Run a self-contained HTML, CSS, and JavaScript demo inside a sandboxed iframe.
-section: components
-order: 37
-badge: 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>
-```
-
-- **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 of cards and notes (use [`compose`](/garden/en/components/compose)).
-
-You can tell the AI:
-
-````markdown
-```garden
-Embed a small widget where typing in an input box updates the character count in real time.
-```
-````
-
-## Fields
-
-Every field, default, limit and error code is in [Component reference · html](/garden/en/reference/html).

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

@@ -1,44 +0,0 @@
----
-title: Interactive Formula & Parameters (interactive)
-navTitle: interactive
-description: Let readers drag sliders or switches to recalculate formulas and charts in real time.
-section: components
-order: 38
-badge: interactive
----
-
-> **Deprecated.** New posts should use [`compose`](/garden/en/components/compose) with ChatGPT-shaped DIL (`{@body}`, `{expr}`, `{#if}` / `{#each}`, lowercase tags). Old `garden interactive` fences still parse as compose play for compatibility and will be removed like `figure`.
-
-
-```garden compose #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>
-```
-
-- **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.
-
-You can tell the AI:
-
-````markdown
-```garden
-Let readers drag word count, reading speed, and image count sliders to see how estimated reading time changes.
-```
-````
-
-## Fields
-
-Every field, default, limit and error code is in [Component reference · interactive](/garden/en/reference/interactive).

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

@@ -1,65 +0,0 @@
----
-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

@@ -1,95 +0,0 @@
----
-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

@@ -1,39 +0,0 @@
----
-title: Key Figures (stat)
-navTitle: stat
-description: Display 2 to 4 key numbers, units, and short captions side by side.
-section: components
-order: 32
-badge: stat
----
-
-```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
-```
-
-- **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
-Put the three width limits for the reading column, wide figures, and wide tables side by side so they are easy to scan.
-```
-````
-
-## Fields
-
-Every field, default, limit and error code is in [Component reference · stat](/garden/en/reference/stat).

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

@@ -1,37 +0,0 @@
----
-title: Step Timeline (timeline)
-navTitle: timeline
-description: Order release milestones, incident steps, or build stages along a vertical sequence.
-section: components
-order: 34
-badge: timeline
----
-
-```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.
-```
-
-- **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
-List the three stages of static publishing in order as a timeline.
-```
-````
-
-## Fields
-
-Every field, default, limit and error code is in [Component reference · timeline](/garden/en/reference/timeline).

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

@@ -1,85 +0,0 @@
----
-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

@@ -1,68 +0,0 @@
----
-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.

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

@@ -1,69 +0,0 @@
----
-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

@@ -1,59 +0,0 @@
----
-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/file.md

@@ -1,50 +0,0 @@
----
-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.