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

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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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-27.**
 
 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.
 
@@ -48,7 +48,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 +66,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

package/agent-docs/author/css.md

@@ -13,11 +13,11 @@ canonical: /author/css
 
 > 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) > Customize > CSS and theme reference
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > CSS and theme reference
 
-**Updated: 2026-10-25.**
+**Updated: 2026-10-27.**
 
 The built site loads `/assets/site.css`, which imports `/assets/tokens.css`. To customize a project, set `site.customCss` to a local stylesheet. The build copies it to `/assets/project.css` and links it after the framework CSS on every HTML page. Paths resolve from the config file that declares them, including imported config fragments. The stylesheet is a build dependency, so changes are picked up on rebuild.
 
@@ -194,7 +194,6 @@ Use these selectors when a change needs to target a specific region or component
 | `.walkthrough-step-number`, `.walkthrough-lines`, `.walkthrough-code`, `.line`, `.line.is-highlighted`, `pre[data-focus]`                                                                                                | Step labels, walkthrough code, and highlighted lines. Set `--walkthrough-highlight`, `--walkthrough-highlight-edge`, and `--walkthrough-dim` on `.walkthrough` to change the highlight color, its left edge, and the opacity of other lines. |
 | `.walkthrough.is-split`, `.walkthrough-step.is-active`, `.walkthrough-pane`, `.walkthrough-bar`, `.walkthrough-status`, `.walkthrough-stage`, `[data-k]`, `.walkthrough-ghost`, `.walkthrough-step-button`               | The side-by-side layout the walkthrough script adds on wide screens. It covers the active step, the sticky code pane and its toolbar, the moving tokens, and spotlight step buttons.                                                         |
 | `.related-reading`                                                                                                                                                                                                       | [RelatedReading](https://www.shoalrun.com/author/components/related-reading.md) wrapper.                                                                                                                                                     |
-| `.theme-preview`, `[data-theme-preview]`, `.theme-preview-title`, `.theme-preview-controls`, `.theme-preview-fields`, `.theme-preview-config`, `.theme-preview-status`                                                   | [Theme previewer](https://www.shoalrun.com/styling/try.md) panel. Its styles load from `/assets/theme-preview.css` only on pages that use it.                                                                                                |
 | `.example-choices`                                                                                                                                                                                                       | Example selector in the API panel.                                                                                                                                                                                                           |
 | `.doc-diagram`, `.doc-diagram-svg`, `.pele`, `.diagram-light`, `.diagram-dark`, `.doc-diagram figcaption`                                                                                                                | [Diagram](https://www.shoalrun.com/author/components/diagrams.md) frame, inline Pele SVG, D2 color-mode images, and caption.                                                                                                                 |
 
@@ -204,12 +203,12 @@ The navigation filter appears when JavaScript runs; without it, the navigation t
 
 The `html` element carries attributes that project CSS can use to target one theme, mode, or layout:
 
-| Attribute                    | Set when                                                                                                                                         | Values                         |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
-| `data-theme`, `data-palette` | The site uses a preset, palette, or mode other than the defaults. The [theme previewer](https://www.shoalrun.com/styling/try.md) also sets them. | Preset and palette names.      |
-| `data-mode`                  | A reader chose light or dark with the [mode toggle](https://www.shoalrun.com/styling/color-modes.md).                                            | `light` or `dark`.             |
-| `data-masthead`              | The preset has an inked masthead: `ledger` and `vice`.                                                                                           | `inked`                        |
-| `data-layout`                | The page sets `layout: wide`, `landing`, or `splash`.                                                                                            | `wide`, `landing`, or `splash` |
+| Attribute                    | Set when                                                                                              | Values                         |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------ |
+| `data-theme`, `data-palette` | The site uses a preset, palette, or mode other than the defaults.                                     | Preset and palette names.      |
+| `data-mode`                  | A reader chose light or dark with the [mode toggle](https://www.shoalrun.com/styling/color-modes.md). | `light` or `dark`.             |
+| `data-masthead`              | The preset has an inked masthead: `ledger` and `vice`.                                                | `inked`                        |
+| `data-layout`                | The page sets `layout: wide`, `landing`, or `splash`.                                                 | `wide`, `landing`, or `splash` |
 
 `shoal` is the default preset, so a default site has no `data-theme`. To target `shoal` either way, use `:root:is(:not([data-theme]), [data-theme="shoal"])`:
 
@@ -236,3 +235,7 @@ In browsers that support cross-document view transitions, the reading column fad
 ```
 
 The publication label adjusts automatically. A single channel, version, and language leaves the top-right spot empty. When one dimension varies, only that dimension appears. Set `site.editionBadge: always` to show all three values or `site.editionBadge: never` to hide the label. `auto` is the default.
+
+## HTML, Markdown, and agents
+
+Project CSS changes the HTML presentation. It is not included in Markdown twins, and a text-reading agent does not apply selectors, pseudo-elements, or responsive rules. Put essential instructions and labels in authored content rather than CSS-generated text. Hiding an element with CSS does not remove its content from the published Markdown or protect it from access.

package/agent-docs/author/css.sections/borders-fields-and-navigation-tokens.md

@@ -13,11 +13,11 @@ canonical: /author/css
 
 > 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) > Customize > CSS and theme reference
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > CSS and theme reference
 
-**Updated: 2026-10-25.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/author/css.md)
 

package/agent-docs/author/css.sections/core-color-tokens.md

@@ -13,11 +13,11 @@ canonical: /author/css
 
 > 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) > Customize > CSS and theme reference
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > CSS and theme reference
 
-**Updated: 2026-10-25.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/author/css.md)
 

package/agent-docs/author/css.sections/html-markdown-and-agents.md

@@ -0,0 +1,54 @@
+---
+id: guide.css
+title: CSS and theme reference
+summary: Customize colors, typography, layout, navigation, code, and component
+  styles with one project stylesheet.
+type: reference
+area: appearance
+subarea: appearance-themes
+canonical: /author/css
+---
+
+# CSS and theme reference
+
+> 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) > Output and presentation > CSS and theme reference
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/css.md)
+
+The built site loads `/assets/site.css`, which imports `/assets/tokens.css`. To customize a project, set `site.customCss` to a local stylesheet. The build copies it to `/assets/project.css` and links it after the framework CSS on every HTML page. Paths resolve from the config file that declares them, including imported config fragments. The stylesheet is a build dependency, so changes are picked up on rebuild.
+
+```yaml title="docs.config.yaml"
+site:
+  title: Example documentation
+  customCss: ./styles/project.css
+```
+
+```css title="styles/project.css"
+:root {
+  --font-body: Inter, ui-sans-serif, system-ui, sans-serif;
+  --color-accent: #2458a6;
+  --color-link: #2458a6;
+  --width-site: 92rem;
+}
+.page-head h1 { letter-spacing: -.02em; }
+```
+
+Pages link these stylesheets in order, and later files win: `/assets/site.css` (which imports `tokens.css` and `header.css`), a preset's `/assets/theme.css`, the generated `/assets/palette.css`, the generated `/assets/fonts.css`, then `/assets/project.css`. [Themes](https://www.shoalrun.com/styling/themes.md) lists when each one is present.
+
+To use your own font files, set [`theme.fonts`](https://www.shoalrun.com/styling/themes.md) instead of writing `@font-face` rules here. The build then copies the files, preloads the body font, and sets `--font-body`, `--font-heading`, and `--font-code` for you.
+
+Use tokens for broad changes and the generated classes below for a particular region. The project stylesheet is copied as one file; relative images or `@import` files are not copied automatically. Use site-root URLs for separately hosted assets. Markdown twins contain content, not CSS.
+
+Before writing CSS, check whether a [theme preset](https://www.shoalrun.com/styling/themes.md), [palette](https://www.shoalrun.com/styling/palettes.md), or [color mode](https://www.shoalrun.com/styling/color-modes.md) already covers the change. Project CSS loads after all three, so the tokens below override them. The build checks palette colors for contrast. It does not check colors set here.
+
+Inline [badges](https://www.shoalrun.com/author/components/badge.md) use `--color-field-surface`, `--color-ink`, and `--color-border` for `neutral`; `info`, `success`, `warning`, and `new` use the matching callout note, tip, warning, and important tokens. Register a color in `badges.variants` to add or override a variant with checked light and dark text contrast. The generated `/assets/badges.css` loads after palette CSS and before project CSS.
+
+## HTML, Markdown, and agents
+
+Project CSS changes the HTML presentation. It is not included in Markdown twins, and a text-reading agent does not apply selectors, pseudo-elements, or responsive rules. Put essential instructions and labels in authored content rather than CSS-generated text. Hiding an element with CSS does not remove its content from the published Markdown or protect it from access.

package/agent-docs/author/css.sections/page-attributes.md

@@ -13,11 +13,11 @@ canonical: /author/css
 
 > 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) > Customize > CSS and theme reference
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > CSS and theme reference
 
-**Updated: 2026-10-25.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/author/css.md)
 
@@ -53,12 +53,12 @@ Inline [badges](https://www.shoalrun.com/author/components/badge.md) use `--colo
 
 The `html` element carries attributes that project CSS can use to target one theme, mode, or layout:
 
-| Attribute                    | Set when                                                                                                                                         | Values                         |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
-| `data-theme`, `data-palette` | The site uses a preset, palette, or mode other than the defaults. The [theme previewer](https://www.shoalrun.com/styling/try.md) also sets them. | Preset and palette names.      |
-| `data-mode`                  | A reader chose light or dark with the [mode toggle](https://www.shoalrun.com/styling/color-modes.md).                                            | `light` or `dark`.             |
-| `data-masthead`              | The preset has an inked masthead: `ledger` and `vice`.                                                                                           | `inked`                        |
-| `data-layout`                | The page sets `layout: wide`, `landing`, or `splash`.                                                                                            | `wide`, `landing`, or `splash` |
+| Attribute                    | Set when                                                                                              | Values                         |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------ |
+| `data-theme`, `data-palette` | The site uses a preset, palette, or mode other than the defaults.                                     | Preset and palette names.      |
+| `data-mode`                  | A reader chose light or dark with the [mode toggle](https://www.shoalrun.com/styling/color-modes.md). | `light` or `dark`.             |
+| `data-masthead`              | The preset has an inked masthead: `ledger` and `vice`.                                                | `inked`                        |
+| `data-layout`                | The page sets `layout: wide`, `landing`, or `splash`.                                                 | `wide`, `landing`, or `splash` |
 
 `shoal` is the default preset, so a default site has no `data-theme`. To target `shoal` either way, use `:root:is(:not([data-theme]), [data-theme="shoal"])`:
 

package/agent-docs/author/css.sections/page-transitions.md

@@ -13,11 +13,11 @@ canonical: /author/css
 
 > 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) > Customize > CSS and theme reference
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > CSS and theme reference
 
-**Updated: 2026-10-25.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/author/css.md)
 

package/agent-docs/author/css.sections/responsive-behavior.md

@@ -13,11 +13,11 @@ canonical: /author/css
 
 > 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) > Customize > CSS and theme reference
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > CSS and theme reference
 
-**Updated: 2026-10-25.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/author/css.md)
 

package/agent-docs/author/css.sections/status-code-and-callout-tokens.md

@@ -13,11 +13,11 @@ canonical: /author/css
 
 > 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) > Customize > CSS and theme reference
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > CSS and theme reference
 
-**Updated: 2026-10-25.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/author/css.md)
 

package/agent-docs/author/css.sections/typography-shape-and-width-tokens.md

@@ -13,11 +13,11 @@ canonical: /author/css
 
 > 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) > Customize > CSS and theme reference
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > CSS and theme reference
 
-**Updated: 2026-10-25.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/author/css.md)