@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.12

package/agent-docs/author/components/file-tree.md

@@ -0,0 +1,88 @@
+---
+id: guide.component.file-tree
+title: File trees
+summary: Show nested files and folders with links and an indented Markdown equivalent.
+type: reference
+area: components
+subarea: components-code
+canonical: /author/components/file-tree
+---
+
+# File trees
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > File trees
+
+**Updated: 2026-10-27.**
+
+`<FileTree>` shows a file layout or other hierarchy. `<Tree>` is an alias. Add `<Folder>` branches and `<File>` leaves; folders may contain more folders or files.
+
+## Syntax
+
+```mdx
+<FileTree>
+<Folder name="docs">
+<Folder name="content">
+<File name="start.mdx" doc="guide.overview" />
+<File name="configuration.mdx" />
+<Folder name="assets" collapsed>
+<File name="overview.svg" />
+</Folder>
+</Folder>
+<File name="docs.config.yaml" />
+</Folder>
+<File name="package.json" />
+</FileTree>
+```
+
+- docs
+
+  - content
+
+    - [start.mdx](https://www.shoalrun.com/start.md)
+
+    - configuration.mdx
+
+    - assets
+
+      - overview\.svg
+
+  - docs.config.yaml
+
+- package.json
+
+## Attributes
+
+Every node needs a nonempty `name`. Folders and files get icons automatically, and a folder’s icon changes when it opens. Optional `doc` or `href` makes its label a link; use only one. Optional `icon` accepts a lowercase Lucide name to override the default. `<File>` cannot have children.
+
+## Expand and collapse folders
+
+Folders start expanded. Readers can toggle them with a click, tap, Enter, or Space without JavaScript. Add `collapsed` to a folder to start it closed, and `controls` to the tree for optional expand-all and collapse-all buttons:
+
+```mdx
+<FileTree controls>
+<Folder name="project">
+<File name="README.md" />
+<Folder name="content" collapsed>
+<File name="start.mdx" />
+</Folder>
+</Folder>
+</FileTree>
+```
+
+- project
+
+  - README.md
+
+  - content
+
+    - start.mdx
+
+With JavaScript, Up and Down move through visible controls and links; Home and End jump to the first and last. Right opens a folder or moves forward, and Left closes it or moves to its parent. Type a name to jump to a matching visible item, or press `*` to expand sibling folders at the current level. Tab still follows normal focus order. Expand-all and collapse-all buttons appear only when JavaScript is available.
+
+## HTML, Markdown, and agents
+
+HTML uses nested lists and native folder disclosures. Every file is in the initial HTML, including files in closed folders. Links retain normal keyboard behavior. Markdown is a nested list with every node and destination visible, so an agent can follow the hierarchy and links. Icons are decorative, so names must carry the meaning.

package/agent-docs/author/components/images.md

@@ -0,0 +1,105 @@
+---
+id: guide.component.images
+title: Images
+summary: Add responsive images with optional width limits, captions, and
+  expanded viewing.
+type: reference
+area: components
+subarea: components-visuals
+canonical: /author/components/images
+---
+
+# Images
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Images
+
+**Updated: 2026-10-27.**
+
+Use `<Image>` to show an image with optional sizing, a caption, or click-to-expand viewing. Plain Markdown image syntax also works when you only need an image and alt text.
+
+## Basic image
+
+Provide a source and alt text. Local paths are relative to the page's MDX file; Shoalrun copies the image into the build. HTTPS URLs work too.
+
+## Syntax
+
+```mdx
+<Image src="./assets/image-example.svg" alt="A documentation page with navigation, content, and a table of contents" />
+```
+
+Images fit the content column and shrink on narrow screens. They keep their aspect ratio. Plain Markdown has the same default sizing:
+
+```md
+![A documentation page](./assets/image-example.svg)
+```
+
+## Set a width
+
+`width` sets a maximum in pixels. It does not force an image to overflow a smaller screen. Leave it out to use the available content width.
+
+```mdx
+<Image src="./assets/image-example.svg" alt="A documentation page layout" width="480" />
+```
+
+![A documentation page layout](https://www.shoalrun.com/assets/pages/author/components/images/image-example.svg)
+
+## Center an image
+
+Use `align="center"` with a width limit to center an image in the content column. The caption and expanded-view link stay with the image. You can also choose `left` or `right`.
+
+```mdx
+<Image src="./assets/image-example.svg" alt="A documentation page layout" width="480" align="center" caption="A centered image with a width limit." expand />
+```
+
+![A documentation page layout](https://www.shoalrun.com/assets/pages/author/components/images/image-example.svg)
+
+A centered image with a width limit.
+
+[View original image](https://www.shoalrun.com/assets/pages/author/components/images/image-example.svg)
+
+## Add a caption and expanded view
+
+Use `caption` for visible context below the image. Add the bare `expand` attribute to let readers open a larger view. Select the example to try it.
+
+```mdx
+<Image src="./assets/image-example.svg" alt="Navigation beside the main content, with a table of contents on the right" width="480" caption="A documentation page has three reading areas." expand />
+```
+
+![Navigation beside the main content, with a table of contents on the right](https://www.shoalrun.com/assets/pages/author/components/images/image-example.svg)
+
+A documentation page has three reading areas.
+
+[View original image](https://www.shoalrun.com/assets/pages/author/components/images/image-example.svg)
+
+The expanded view supports Escape to close and returns focus to the image link. Without JavaScript or modal-dialog support, the link opens the original asset. A larger view cannot add detail that is missing from a low-resolution source.
+
+## Attributes
+
+All attributes use literal values. `expand` is a bare boolean attribute.
+
+| Attribute | Required | Meaning                                                                             |
+| --------- | -------- | ----------------------------------------------------------------------------------- |
+| `src`     | Yes      | Local `.png`, `.jpg`, `.jpeg`, `.webp`, or `.svg` path, or an HTTPS URL.            |
+| `alt`     | Yes      | Text describing the image's meaning. Use `alt=""` only for decorative images.       |
+| `width`   | No       | Maximum width in pixels, from 1 to 4096.                                            |
+| `align`   | No       | `left`, `center`, or `right`. Default placement follows the surrounding content.    |
+| `caption` | No       | Plain text shown below the image and retained in Markdown.                          |
+| `expand`  | No       | Opens a modal image viewer when supported, with an original-image link as fallback. |
+
+`<Image>` is an empty block component. It does not accept children, HTML strings, or dynamic expressions. Keep essential explanations in nearby prose and meaningful alt text. For generated diagrams, use [Diagram](https://www.shoalrun.com/author/components/diagrams.md).
+
+## HTML, Markdown, and agents
+
+HTML contains a normal image with alt text. Captions use `figure` and `figcaption`. Expandable images use a link enhanced by a modal viewer; the image remains usable without scripts. Modified clicks still open the link normally.
+
+Markdown includes the image and alt text, followed by its caption when present. Expandable images also include a link to the original asset. Width, alignment, and modal state do not hide content from agents.
+
+## Related reading
+
+### Related topics
+
+- [Diagrams](https://www.shoalrun.com/author/components/diagrams.md) — Render a diagram from source with a caption and responsive width.

package/agent-docs/author/components/info-hint.md

@@ -0,0 +1,65 @@
+---
+id: guide.component.info-hint
+title: Short definitions
+summary: Let readers open a brief definition with a click, tap, or keyboard.
+type: reference
+area: components
+subarea: components-prose
+canonical: /author/components/info-hint
+---
+
+# Short definitions
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Short definitions
+
+**Updated: 2026-10-27.**
+
+Use `<InfoHint>` for a short definition that readers can open when they need it. It is a click-to-expand disclosure. Use a [tooltip](https://www.shoalrun.com/author/components/tooltips.md) for brief text that appears on hover or keyboard focus. Put longer explanations in a [callout](https://www.shoalrun.com/author/components/callout.md) or a linked page.
+
+## Syntax
+
+Give the disclosure a visible `label` and one short plain-text definition.
+
+```mdx
+<InfoHint label="Canonical URL">
+The preferred address for a page when several addresses show the same content.
+</InfoHint>
+```
+
+Canonical URL: The preferred address for a page when several addresses show the same content.
+
+## Attributes
+
+Use these attributes to configure the component.
+
+| Attribute | Required | Meaning                                        |
+| --------- | -------- | ---------------------------------------------- |
+| `label`   | Yes      | Nonempty text shown on the disclosure control. |
+
+`<InfoHint>` must be a block element with one plain-text definition. It does not accept links, multiple paragraphs, or other components inside the definition.
+
+`<Tooltip>` previously named this same disclosure. Use `<InfoHint>` to keep click-to-expand behavior; `<Tooltip>` now provides hover and focus behavior.
+
+## HTML, Markdown, and agents
+
+HTML uses native `<details>` and `<summary>` elements. Readers can open the definition with a click, tap, Enter, or Space without JavaScript. The definition is present in the initial HTML even while the disclosure is closed.
+
+Markdown writes the label and definition together in ordinary text. An agent can read the explanation without opening a disclosure.
+
+## Related reading
+
+### Related topics
+
+- [Callouts](https://www.shoalrun.com/author/components/callout.md) — Choose a short optional definition or an explanation visible in the reading path.
+
+- [Keyboard shortcuts](https://www.shoalrun.com/author/components/kbd.md) — Use key styling for shortcuts and a disclosure for optional definitions.
+
+### Often confused with
+
+- [Collapsibles](https://www.shoalrun.com/author/components/collapsible.md) — A short definition contains plain text; a collapsible holds longer rich content.
+
+- [Tooltips](https://www.shoalrun.com/author/components/tooltips.md) — Tooltips open on hover or focus; short definitions use native click-to-expand disclosures.

package/agent-docs/author/components/kbd.md

@@ -0,0 +1,47 @@
+---
+id: guide.component.kbd
+title: Keyboard shortcuts
+summary: Mark up key names and shortcuts inside documentation text.
+type: reference
+area: components
+subarea: components-code
+canonical: /author/components/kbd
+---
+
+# Keyboard shortcuts
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Keyboard shortcuts
+
+**Updated: 2026-10-27.**
+
+Use `<Kbd>` to name a key or shortcut in a sentence. Include the action in the sentence; key styling alone does not explain what the shortcut does.
+
+## Syntax
+
+Put each key in its own `<Kbd>` tag and write any separator as ordinary text.
+
+```mdx
+Press <Kbd>⌘</Kbd> + <Kbd>C</Kbd> to copy selected text.
+```
+
+Press ⌘ + C to copy selected text.
+
+## Attributes
+
+`<Kbd>` takes nonempty plain text and no attributes. It works inside prose, headings, and table cells.
+
+## HTML, Markdown, and agents
+
+HTML renders each key as a semantic `<kbd>` element. There is no interactive behavior or JavaScript requirement.
+
+Markdown keeps the key names as ordinary text. An agent receives the same instruction and shortcut without interpreting the visual key style.
+
+## Related reading
+
+### Related topics
+
+- [Short definitions](https://www.shoalrun.com/author/components/info-hint.md) — Use key styling for shortcuts and a disclosure for optional definitions.

package/agent-docs/author/components/math.md

@@ -0,0 +1,43 @@
+---
+id: guide.component.math
+title: Math
+summary: Render inline and display LaTeX expressions at build time.
+type: reference
+area: components
+subarea: components-visuals
+canonical: /author/components/math
+---
+
+# Math
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Math
+
+**Updated: 2026-10-27.**
+
+Use `<Math>` with a literal LaTeX expression. It supports the KaTeX math subset and reports invalid expressions during the build.
+
+## Syntax
+
+```mdx
+Energy is <Math expression="E=mc^2" />.
+
+<Math display expression="c^2=a^2+b^2" />
+```
+
+Energy is `E=mc^2`.
+
+```latex
+c^2=a^2+b^2
+```
+
+## Attributes
+
+`expression` is required and nonempty. Add the bare `display` attribute on a block element for centered display math. The component does not parse dollar delimiters in ordinary prose or code fences. Escape quotes in MDX attributes as needed.
+
+## HTML, Markdown, and agents
+
+HTML contains build-time MathML with the source expression as an annotation. The expression remains available to assistive technology without client JavaScript. Markdown keeps inline expressions as code and display expressions in a `latex` code block. An agent can read the original LaTeX in either form. Check complicated notation with the screen readers your readers use.

package/agent-docs/author/components/only.md

@@ -0,0 +1,69 @@
+---
+id: guide.component.only
+title: Content for one format
+summary: Use Only to add content to the HTML page or its Markdown twin alone.
+type: reference
+area: components
+subarea: components-procedures
+canonical: /author/components/only
+---
+
+# Content for one format
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Content for one format
+
+**Updated: 2026-10-27.**
+
+Use `<Only>` to author content for one output format. Shared material stays outside the blocks; a block can contain an instruction, explanation, example, or link that serves only one version:
+
+## Syntax
+
+```mdx
+Shared setup steps appear in both formats.
+
+<Only format="html">
+
+Choose a tab below to inspect a response.
+
+</Only>
+
+<Only format="markdown">
+
+The response examples follow as labeled sections.
+
+</Only>
+```
+
+The example below is live. This HTML page shows the first sentence; [its Markdown twin](https://www.shoalrun.com/author/components/only.md) shows the second.
+
+The same mechanism can hold a larger section. An HTML section might teach through a visual walkthrough. Its Markdown counterpart can provide file paths and a command sequence for an agent. Each version should give its reader enough to complete the task, and shared product facts should stay consistent.
+
+This sentence appears only in the Markdown twin.
+
+## Attributes
+
+The build validates the contents of both blocks, including their links and supported components. `<Only>` needs block content and exactly one literal `format` attribute: `html` or `markdown`. Dynamic expressions and other values fail the build.
+
+## HTML, Markdown, and agents
+
+An agent that fetches the direct `.md` URL, or requests this page with `Accept: text/markdown` on a host that supports [content negotiation](https://www.shoalrun.com/publish/content-negotiation.md), receives the shared text and `format="markdown"` blocks. It does not receive `format="html"` blocks. For the live example above, the relevant Markdown line is:
+
+```md
+This sentence appears only in the Markdown twin.
+```
+
+Keep facts, warnings, and task steps that both readers need outside `<Only>`, or provide suitable versions in both formats. You can add or suppress content in either output when that helps its intended reader. Check that each version remains accurate and usable for its task; see [Shoalrun's position on shared and format-specific content](https://www.shoalrun.com/publish/agent-friendliness.md). The browser search index uses the HTML output, so Markdown-only text is not included in that search. See [publishing and agent representations](https://www.shoalrun.com/publish/output.md) for the full output contract.
+
+## Related reading
+
+### Related topics
+
+- [Content negotiation](https://www.shoalrun.com/publish/content-negotiation.md) — Write instructions that apply to only the HTML page or only the Markdown twin.
+
+### Often confused with
+
+- [Tabs](https://www.shoalrun.com/author/components/tabs.md) — Tabs show alternate views to every reader; Only limits content to the HTML page or its Markdown twin.

package/agent-docs/author/components/progress.md

@@ -0,0 +1,57 @@
+---
+id: guide.component.progress
+title: Progress
+summary: Show a bounded count with a visible label and native progress bar.
+type: reference
+area: components
+subarea: components-procedures
+canonical: /author/components/progress
+---
+
+# Progress
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Progress
+
+**Updated: 2026-10-27.**
+
+Use `<Progress>` for a published count in a tutorial or migration guide. It shows the amount completed as text and as a bar. Update the source and rebuild the site when the shared state changes.
+
+## Syntax
+
+```mdx
+<Progress label="Migration tasks" value="3" max="5" />
+```
+
+Migration tasks: 3 of 5 complete.
+
+## Attributes
+
+Use these attributes to configure the component.
+
+| Attribute | Required | Meaning                                                                     |
+| --------- | -------- | --------------------------------------------------------------------------- |
+| `label`   | Yes      | Nonempty name shown beside the count and used as the bar's accessible name. |
+| `value`   | Yes      | A number from zero through `max`.                                           |
+| `max`     | Yes      | A number greater than zero.                                                 |
+
+`<Progress>` is a block element without a body. All three attributes must be literal values. The build rejects a value outside the range or a maximum of zero.
+
+## When to use it
+
+Use this component when a count has a known maximum, such as 3 of 5 migration tasks complete. It is a read-only display: readers cannot mark a task complete or move the bar. For a process with named stages and descriptions, use a [timeline](https://www.shoalrun.com/author/components/timeline.md).
+
+## HTML, Markdown, and agents
+
+HTML shows “Migration tasks: 3 of 5 complete” alongside a native `<progress>` element. The text carries the count even without CSS or color. There is no JavaScript behavior or keyboard control.
+
+Markdown states the same label and count in a sentence. An agent does not need to estimate completion from the bar.
+
+## Related reading
+
+### Often confused with
+
+- [Timelines](https://www.shoalrun.com/author/components/timeline.md) — Progress reports a bounded count; a timeline names and describes stages.

package/agent-docs/author/components/related-reading.md

@@ -0,0 +1,52 @@
+---
+id: guide.component.related-reading
+title: RelatedReading
+summary: Display authored relationships as links or cards.
+type: reference
+area: components
+subarea: components-navigation
+canonical: /author/components/related-reading
+---
+
+# RelatedReading
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > RelatedReading
+
+**Updated: 2026-10-27.**
+
+`<RelatedReading>` presents connections declared in the central `relationships` config. Use it for prerequisites, next steps, references, related topics, and distinctions that need a reason.
+
+## Syntax
+
+```mdx
+<RelatedReading relation="next-step" />
+```
+
+## Attributes
+
+Use these attributes to configure the component.
+
+| Attribute   | Meaning                                                                                     |
+| ----------- | ------------------------------------------------------------------------------------------- |
+| `relation`  | Select one relationship type; omit for all types grouped by purpose.                        |
+| `relatedTo` | Source document ID; defaults to this page. It must be available in the current publication. |
+| `layout`    | `list` by default, or `cards`. Card layout includes card overrides, summaries, and reasons. |
+| `empty`     | Text for no matches; default is “No matching documents.” Empty groups are omitted.          |
+
+This is a standalone empty element. A selected `relation` has no automatic heading, so give that view a page heading when useful. See [related reading](https://www.shoalrun.com/author/related-reading.md) for config fields, relationship types, and ordering.
+
+## HTML, Markdown, and agents
+
+With `layout="list"`, HTML and Markdown show links with the relationship reasons; `layout="cards"` adds previews. Only connections whose endpoints are public in the current publication appear. Both layouts export ordinary links and reasons to Markdown, with `.md` destinations, so agents can follow the same reading paths. The HTML wrapper has the `related-reading` class for [project CSS](https://www.shoalrun.com/author/css.md).
+
+When a top-level view describes the current page, section Markdown also carries its `prerequisite` and `next-step` links if they would otherwise be omitted. A **Page reading path** label explains the scope. Nested views and views with another `relatedTo` source stay in their original context. See [section reading paths](https://www.shoalrun.com/author/related-reading.md) for boundaries and size rules.
+
+## Related reading
+
+### Read first
+
+- [Related reading](https://www.shoalrun.com/author/related-reading.md) — Declare the relationships this component displays.

package/agent-docs/author/components/steps.md

@@ -0,0 +1,127 @@
+---
+id: guide.component.steps
+title: Steps
+summary: Show a short procedure as numbered steps with full instructions in both
+  outputs.
+type: reference
+area: components
+subarea: components-procedures
+canonical: /author/components/steps
+---
+
+# Steps
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Steps
+
+**Updated: 2026-10-27.**
+
+Use `<Steps>` when each part of a procedure needs a title and supporting content. For a simple sequence with no step titles, an ordinary Markdown numbered list is enough. For code that changes between steps, use a [Walkthrough](https://www.shoalrun.com/author/components/walkthroughs.md).
+
+## Syntax
+
+```mdx
+<Steps>
+<Step title="Create a page">
+Add `content/first-page.mdx` with frontmatter and a short body.
+</Step>
+<Step title="Build the site">
+Run `shoalrun build docs.config.yaml dist`, then open the output.
+</Step>
+</Steps>
+```
+
+1. ## Create a page
+
+   Add `content/first-page.mdx` with frontmatter and a short body.
+
+2. ## Build the site
+
+   Run `shoalrun build docs.config.yaml dist`, then open the output.
+
+## Choose a style
+
+`rail` is the default: numbered circles and a connecting line keep a longer procedure easy to scan. Use `cards` to separate steps with substantial examples or decisions. Use `plain` for a quiet numbered list. The style changes HTML presentation; all three produce the same complete ordered list in Markdown.
+
+```mdx
+<Steps variant="cards">
+<Step title="Prepare" icon="file-check-2">Check the draft page.</Step>
+<Step title="Publish" icon="upload">Build and deploy the site.</Step>
+</Steps>
+```
+
+1. ## Prepare
+
+   Check the draft page.
+
+2. ## Publish
+
+   Build and deploy the site.
+
+```mdx
+<Steps variant="plain">
+<Step title="Prepare">Check the draft page.</Step>
+<Step title="Publish">Build and deploy the site.</Step>
+</Steps>
+```
+
+1. ## Prepare
+
+   Check the draft page.
+
+2. ## Publish
+
+   Build and deploy the site.
+
+## Attributes
+
+Use these attributes to configure the component.
+
+| Attribute      | Where   | Meaning                                                                                               |
+| -------------- | ------- | ----------------------------------------------------------------------------------------------------- |
+| `variant`      | `Steps` | `rail` (default), `cards`, or `plain`.                                                                |
+| `toc`          | `Steps` | `ignore` (default) or `include`. Controls whether step headings appear in the page table of contents. |
+| `headingLevel` | `Steps` | Heading level `2` (default) through `6` for every step title in the group.                            |
+| `title`        | `Step`  | Required, nonempty literal title.                                                                     |
+| `icon`         | `Step`  | Optional lowercase Lucide name. Decorative beside the title in HTML.                                  |
+
+`<Steps>` accepts one or more direct `<Step>` children with nonempty bodies. The body accepts ordinary Markdown and supported components.
+
+The same `<Step>` tag is also used in [Walkthrough](https://www.shoalrun.com/author/components/walkthroughs.md). Its parent selects a separate component contract:
+
+| Parent          | `<Step>` attributes                                       | Output                                                               |
+| --------------- | --------------------------------------------------------- | -------------------------------------------------------------------- |
+| `<Steps>`       | `title`, optional `icon`                                  | Numbered procedure with configurable heading level and TOC behavior. |
+| `<Walkthrough>` | `title`, optional code source and highlighting attributes | Code walkthrough with synchronized explanations.                     |
+
+Use the attributes documented for the parent you are writing. The two forms do not share rendering or settings.
+
+## Step headings and the page outline
+
+Each step title renders as a real heading with an anchor ID. It defaults to `<h2>`; set `headingLevel` to match the surrounding page structure. Step headings are omitted from the page table of contents by default, keeping the outline focused when a page contains several procedures. Set `toc="include"` when readers should be able to jump to individual steps:
+
+```mdx
+<Steps toc="include" headingLevel="3">
+<Step title="Install">Install the package.</Step>
+<Step title="Configure">Add the configuration.</Step>
+</Steps>
+```
+
+1. ### Install
+
+   Install the package.
+
+2. ### Configure
+
+   Add the configuration.
+
+The page's `tocDepth` frontmatter still applies. For example, `tocDepth: 2` omits the level-three steps above, while `tocDepth: 0` hides the whole outline. Markdown keeps an ordered list with headings at the chosen level and complete bodies.
+
+## HTML, Markdown, and agents
+
+HTML renders a semantic ordered list. Numbers, titles, and full bodies are visible without JavaScript or animation, including when CSS is unavailable. An icon never carries the only meaning. There are no controls, so ordinary link and code-block keyboard behavior applies.
+
+Markdown keeps the complete ordered list and each step heading at the chosen level. An agent receives every instruction in sequence without needing the visual rail or cards.