npm - @shoalrun/cli - Versions diffs - 0.1.0-alpha.11 → 0.1.0-alpha.13 - Mend

@shoalrun/cli 0.1.0-alpha.11 → 0.1.0-alpha.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (602) hide show

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

@@ -12,11 +12,11 @@ canonical: /author/components/info-hint
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Short definitions
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Short definitions
-**Updated: 2026-10-26.**
+**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.
@@ -32,6 +32,10 @@ The preferred address for a page when several addresses show the same content.
 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. |

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

@@ -12,11 +12,11 @@ canonical: /author/components/kbd
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Keyboard shortcuts
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Keyboard shortcuts
-**Updated: 2026-10-26.**
+**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.
@@ -30,6 +30,8 @@ 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

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

@@ -12,14 +12,16 @@ canonical: /author/components/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: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Math
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Math
-**Updated: 2026-10-19.**
+**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" />.
@@ -32,6 +34,8 @@ Energy is `E=mc^2`.
 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

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

@@ -12,14 +12,16 @@ canonical: /author/components/only
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Content for one format
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Content for one format
-**Updated: 2026-10-26.**
+**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.
@@ -42,6 +44,10 @@ The same mechanism can hold a larger section. An HTML section might teach throug
 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:
@@ -50,8 +56,6 @@ An agent that fetches the direct `.md` URL, or requests this page with `Accept:
 This sentence appears only in the Markdown twin.
 ```
-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.
 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

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

@@ -12,11 +12,11 @@ canonical: /author/components/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: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Progress
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Progress
-**Updated: 2026-10-26.**
+**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.
@@ -28,6 +28,10 @@ Use `<Progress>` for a published count in a tutorial or migration guide. It show
 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. |

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

@@ -12,11 +12,11 @@ canonical: /author/components/related-reading
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > RelatedReading
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > RelatedReading
-**Updated: 2026-10-26.**
+**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.
@@ -26,6 +26,10 @@ Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write docume
 <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.                        |

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

@@ -13,14 +13,16 @@ canonical: /author/components/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: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Steps
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Steps
-**Updated: 2026-10-25.**
+**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">
@@ -74,6 +76,10 @@ Run `shoalrun build docs.config.yaml dist`, then open the output.
    Build and deploy the site.
+## Attributes
+Use these attributes to configure the component.
 | Attribute      | Where   | Meaning                                                                                               |
 | -------------- | ------- | ----------------------------------------------------------------------------------------------------- |
 | `variant`      | `Steps` | `rail` (default), `cards`, or `plain`.                                                                |

package/agent-docs/author/components/tables.md CHANGED Viewed

@@ -13,14 +13,16 @@ canonical: /author/components/tables
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Tables
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Tables
-**Updated: 2026-10-19.**
+**Updated: 2026-10-27.**
 Ordinary Markdown tables work without a component. For a long table, wrap one table in `<Table>` to add a filter box, sticky column headings, or both in HTML:
+## Syntax
 ```mdx
 <Table filter sticky>
@@ -32,6 +34,8 @@ Ordinary Markdown tables work without a component. For a long table, wrap one ta
 </Table>
 ```
+## Attributes
 `filter` and `sticky` are bare boolean attributes. Use either one alone or both. `<Table>` takes exactly one Markdown table and no other content. Its complete table, without controls, appears in the [Markdown twin](https://www.shoalrun.com/author/components/tables.md).
 ## Try the controls

package/agent-docs/author/components/tabs.md CHANGED Viewed

@@ -12,11 +12,11 @@ canonical: /author/components/tabs
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Tabs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Tabs
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 `<Tabs>` presents alternate views, such as two output formats. Use it only when the choices are truly alternatives; a normal heading sequence is easier to read when readers need every section.
@@ -45,6 +45,10 @@ The page has navigation and controls.
 The page keeps the content as text.
+## Attributes
+Use these attributes to configure the component.
 | Element | Attribute     | Meaning                                                                                                                     |
 | ------- | ------------- | --------------------------------------------------------------------------------------------------------------------------- |
 | `Tabs`  | `label`       | Required literal name for the whole group, used by assistive technology.                                                    |

package/agent-docs/author/components/timeline.md CHANGED Viewed

@@ -12,11 +12,11 @@ canonical: /author/components/timeline
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Timelines
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Timelines
-**Updated: 2026-10-19.**
+**Updated: 2026-10-27.**
 Use `<Timeline>` to show progress through an ordered set of milestones. Set `current` to the `id` of the milestone in progress. Earlier milestones become complete; later milestones become upcoming.
@@ -28,7 +28,9 @@ This is a **read-only progress display**. Readers can see the current stage, but
 - Show where a proposal sits in a draft, review, and approval process.
 - Show progress through a published migration or deprecation plan.
-An optional simulation mode could let readers move through the milestones to see each stage of a process. The current component shows only the published state; it has no next, previous, or reset controls.
+The component shows only the published state; it has no next, previous, or reset controls.
+## Syntax
 ```mdx
 <Timeline current="review">
@@ -60,6 +62,10 @@ Make the approved guide available to readers.
 The bar counts **completed** milestones. In this example it shows 1 of 3 complete; Review is still in progress. The current milestone also has a visible status label, and the HTML list marks it with `aria-current="step"`. The bar uses a native `<progress>` element with an accessible name. Markdown includes the same progress summary and status labels.
+## Attributes
+Use these attributes to configure the component.
 | Attribute | Where       | Required | Meaning                                                                         |
 | --------- | ----------- | -------- | ------------------------------------------------------------------------------- |
 | `current` | `Timeline`  | Yes      | The ID of the milestone in progress.                                            |

package/agent-docs/author/components/tooltips.md CHANGED Viewed

@@ -13,11 +13,11 @@ canonical: /author/components/tooltips
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Tooltips
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Tooltips
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Use `<Tooltip>` for brief supporting text beside a term. The text appears when readers hover over or focus the label. Use [Short definitions](https://www.shoalrun.com/author/components/info-hint.md) for click-to-expand explanations, or a [callout](https://www.shoalrun.com/author/components/callout.md) for warnings and instructions that belong in the reading path.
@@ -29,6 +29,10 @@ Compare the <Tooltip label="build digest">A fingerprint of the published build's
 Compare the build digest (A fingerprint of the published build's content.) before refreshing your cache.
+## Attributes
+Use these attributes to configure the component.
 | Attribute | Required | Meaning                                       |
 | --------- | -------- | --------------------------------------------- |
 | `label`   | Yes      | Nonempty text shown on the focusable trigger. |

package/agent-docs/author/components/walkthroughs.md CHANGED Viewed

@@ -13,11 +13,11 @@ canonical: /author/components/walkthroughs
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Walkthroughs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Use `<Walkthrough>` to explain code step by step. Each step pairs an explanation with code built up across steps or read from a project file.
@@ -230,6 +230,8 @@ deadLetter:
 Code in a fence can drift from the code your project runs and tests. To show the real file instead, set `file` on a `<Step>` in place of its code fence, or on `<Walkthrough>` in place of its shared fence. The path is relative to the page.
+## Syntax
 ```mdx
 <Step title="Check the signature" file="../../examples/webhook.ts" region="verify" highlight="2-4">

package/agent-docs/author/components/walkthroughs.sections/attributes.md CHANGED Viewed

@@ -13,11 +13,11 @@ canonical: /author/components/walkthroughs
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Walkthroughs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/components/walkthroughs.md)

package/agent-docs/author/components/walkthroughs.sections/build-up-code.md CHANGED Viewed

@@ -13,11 +13,11 @@ canonical: /author/components/walkthroughs
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Walkthroughs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/components/walkthroughs.md)

package/agent-docs/author/components/walkthroughs.sections/choose-a-layout.md CHANGED Viewed

@@ -13,11 +13,11 @@ canonical: /author/components/walkthroughs
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Walkthroughs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/components/walkthroughs.md)

package/agent-docs/author/components/walkthroughs.sections/explain-one-file.md CHANGED Viewed

@@ -13,11 +13,11 @@ canonical: /author/components/walkthroughs
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Walkthroughs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/components/walkthroughs.md)

package/agent-docs/author/components/walkthroughs.sections/html-markdown-and-agents.md CHANGED Viewed

@@ -13,11 +13,11 @@ canonical: /author/components/walkthroughs
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Walkthroughs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/components/walkthroughs.md)

package/agent-docs/author/components/walkthroughs.sections/related-reading.md CHANGED Viewed

@@ -13,11 +13,11 @@ canonical: /author/components/walkthroughs
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Walkthroughs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/components/walkthroughs.md)

package/agent-docs/author/components/walkthroughs.sections/syntax.md ADDED Viewed

@@ -0,0 +1,51 @@
+---
+id: guide.component.walkthrough
+title: Walkthroughs
+summary: Build code tutorials that explain code one step at a time, with a
+  scrolling pane in HTML and every step in Markdown.
+type: reference
+area: components
+subarea: components-code
+canonical: /author/components/walkthroughs
+---
+# Walkthroughs
+> 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 > Walkthroughs
+**Updated: 2026-10-27.**
+Parent page: [Full Markdown page](/author/components/walkthroughs.md)
+Use `<Walkthrough>` to explain code step by step. Each step pairs an explanation with code built up across steps or read from a project file.
+When there is room for two columns, explanations scroll on the left and code stays on the right. Scrolling or selecting a step updates the code pane. At either end, scrolling continues through the page. On narrower screens, each step shows its explanation and code in order.
+The [spotlight layout](https://www.shoalrun.com/author/components/walkthroughs.md#choose-a-layout) uses step buttons instead of a scroller. Code that stays the same between steps slides to its new position, so readers can follow the changes.
+Use a walkthrough when readers build up code or study one file in parts. For steps without code, use an ordinary numbered list.
+## Syntax
+```mdx
+<Step title="Check the signature" file="../../examples/webhook.ts" region="verify" highlight="2-4">
+Compare the header with a signature of the body.
+</Step>
+```
+| Attribute | Meaning                                                                                                                                             |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `file`    | Path to the code file, relative to the page. The pane and code toolbar show the file name.                                                          |
+| `region`  | Optional. Takes the lines between a `#region name` comment and its `#endregion` comment, without the markers, and removes their shared indentation. |
+| `lines`   | Optional. Takes one range of lines, such as `12-30`. Use `region` or `lines`, not both.                                                             |
+| `lang`    | Optional. The code language, when the file extension doesn't name one.                                                                              |
+Prefer `region` for files that change. Region comments move with the code, while a `lines` range points at the wrong lines after an edit above it. Line numbers in `highlight` count from the first line shown, not from the top of the file.
+Most languages accept region comments, such as `// #region verify` in TypeScript or `# region verify` in Python and YAML. A marker starts its line, after an optional comment opener, so `#region` inside code or a URL doesn't count. The name is the first word, and text after it, such as `// #region verify: check the signature`, is a description. Regions can nest, and an end marker can repeat its name, such as `// #endregion verify`, to show which region it closes. Give each region its own name. Every marker in the file must pair up. A stray or mismatched `#endregion` fails the build with its line number instead of cutting a region short. A file must be inside the Git repository that holds the page, or inside the project directory when there is no repository. The build refuses other paths, so a docs change can't publish files from elsewhere on the build machine. A missing file, region, or range fails the build. Files the walkthrough reads are listed as build dependencies, and `shoalrun dev` rebuilds when one inside the project changes.

package/agent-docs/author/components/walkthroughs.sections/take-code-from-a-file.md CHANGED Viewed

@@ -13,11 +13,11 @@ canonical: /author/components/walkthroughs
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Walkthroughs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/components/walkthroughs.md)
@@ -32,22 +32,3 @@ Use a walkthrough when readers build up code or study one file in parts. For ste
 ## Take code from a file
 Code in a fence can drift from the code your project runs and tests. To show the real file instead, set `file` on a `<Step>` in place of its code fence, or on `<Walkthrough>` in place of its shared fence. The path is relative to the page.
-```mdx
-<Step title="Check the signature" file="../../examples/webhook.ts" region="verify" highlight="2-4">
-Compare the header with a signature of the body.
-</Step>
-```
-| Attribute | Meaning                                                                                                                                             |
-| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `file`    | Path to the code file, relative to the page. The pane and code toolbar show the file name.                                                          |
-| `region`  | Optional. Takes the lines between a `#region name` comment and its `#endregion` comment, without the markers, and removes their shared indentation. |
-| `lines`   | Optional. Takes one range of lines, such as `12-30`. Use `region` or `lines`, not both.                                                             |
-| `lang`    | Optional. The code language, when the file extension doesn't name one.                                                                              |
-Prefer `region` for files that change. Region comments move with the code, while a `lines` range points at the wrong lines after an edit above it. Line numbers in `highlight` count from the first line shown, not from the top of the file.
-Most languages accept region comments, such as `// #region verify` in TypeScript or `# region verify` in Python and YAML. A marker starts its line, after an optional comment opener, so `#region` inside code or a URL doesn't count. The name is the first word, and text after it, such as `// #region verify: check the signature`, is a description. Regions can nest, and an end marker can repeat its name, such as `// #endregion verify`, to show which region it closes. Give each region its own name. Every marker in the file must pair up. A stray or mismatched `#endregion` fails the build with its line number instead of cutting a region short. A file must be inside the Git repository that holds the page, or inside the project directory when there is no repository. The build refuses other paths, so a docs change can't publish files from elsewhere on the build machine. A missing file, region, or range fails the build. Files the walkthrough reads are listed as build dependencies, and `shoalrun dev` rebuilds when one inside the project changes.

package/agent-docs/author/components.md CHANGED Viewed

@@ -12,11 +12,11 @@ canonical: /author/components
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+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: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Overview
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Overview
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 Shoalrun accepts GitHub Flavored Markdown (tables, task lists, strikethrough, footnotes, and autolinks) and the MDX components below. Each component family has a page with syntax, attributes, HTML and Markdown behavior, and limits. Component names and attributes are case-sensitive. Unknown components, dynamic MDX expressions, and exports fail the build because they have no shared HTML and Markdown representation. The build drops `import` lines, so imported components are not available.
@@ -24,6 +24,18 @@ Shoalrun accepts GitHub Flavored Markdown (tables, task lists, strikethrough, fo
 [Navigation and breadcrumbs](https://www.shoalrun.com/author/navigation.md) are configured site features. Their guides live under Customize.
+## Choose by task
+Start with the reader's task, then open the linked reference before choosing syntax.
+| Task                                                 | Feature                                                                                                                                                 |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Link related pages with a reason for each connection | [Relationships](https://www.shoalrun.com/author/related-reading.md) and [RelatedReading](https://www.shoalrun.com/author/components/related-reading.md) |
+| Explain a procedure with titled steps                | [Steps](https://www.shoalrun.com/author/components/steps.md)                                                                                            |
+| Explain how code changes step by step                | [Walkthrough](https://www.shoalrun.com/author/components/walkthroughs.md)                                                                               |
+| Show configuration fields and their constraints      | [Fields](https://www.shoalrun.com/author/components/fields.md)                                                                                          |
+| Offer alternate views of the same topic              | [Tabs](https://www.shoalrun.com/author/components/tabs.md)                                                                                              |
 ## Reading and layout
 - [Callouts](https://www.shoalrun.com/author/components/callout.md) — notes, tips, important messages, warnings, and cautions.
@@ -48,7 +60,6 @@ Shoalrun accepts GitHub Flavored Markdown (tables, task lists, strikethrough, fo
 - [Walkthroughs](https://www.shoalrun.com/author/components/walkthroughs.md) — code explained step by step beside a scrolling code pane.
 - [Hero](https://www.shoalrun.com/styling/layouts.md) — a landing page opener with a title, tagline, and action buttons.
 - [Section](https://www.shoalrun.com/styling/layouts.md) — a full-width band on a splash page.
-- [ThemePreview](https://www.shoalrun.com/styling/try.md) — a live switcher for trying presets, palettes, and color modes.
 - [ReaderSection, ReaderChoice, and ReaderFilter](https://www.shoalrun.com/author/reader-views.md) — marked sections, choice buttons, and in-page filter controls.
 - [FrontmatterReference](https://www.shoalrun.com/author/frontmatter-reference.md) — publish this project's built-in and declared page fields as a live reference.
@@ -67,6 +78,10 @@ Shoalrun accepts GitHub Flavored Markdown (tables, task lists, strikethrough, fo
 [Code highlighting](https://www.shoalrun.com/author/components/code-blocks.md) explains Shiki, theme selection, plain output, and custom adapters. Tabs and collapsibles accept ordinary Markdown and supported MDX components in their bodies; their subpages explain the exact nesting rules.
+## HTML, Markdown, and agents
+Each supported component has a defined HTML and Markdown representation. Browser controls can reveal or rearrange information, while the Markdown form exposes the content described in that component's reference. Agents can follow document links and read examples without operating those controls. Check each reference's **HTML, Markdown, and agents** section for exceptions, such as content deliberately limited to one format with `Only`.
 ## Related reading
 ### Read first