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

package/agent-docs/start.md

@@ -26,7 +26,7 @@ This quickstart takes you from installing Shoalrun to your own working documenta
 
 Install Node.js 22.12 or newer and npm. Use the npm that comes with Node.js; Shoalrun sets no separate npm version. The commands below use a POSIX shell, such as Bash or Zsh.
 
-The public npm package needs no account or token. If you used the earlier GitHub Packages alpha, run `npm config get @shoalrun:registry`. Remove or replace any `@shoalrun:registry=https://npm.pkg.github.com` entry in your project or user `.npmrc`. To explicitly select npm during migration, add `--@shoalrun:registry=https://registry.npmjs.org` to the install command below. Commit the updated manifest and lockfile together, and check that Shoalrun resolves from `registry.npmjs.org`.
+The public npm package needs no account or token.
 
 ## Start your own project
 
@@ -40,7 +40,7 @@ npm install --save-exact @shoalrun/cli@0.1.0-alpha.11
 npx --no-install shoalrun init .
 ```
 
-[Diagrams](https://www.shoalrun.com/author/components/diagrams.md) build without Chrome. The starter puts `docs.config.yaml` and `content/` in your project. Initialization refuses to overwrite starter files, and preserves unrelated files such as the package manifest and lockfile.
+The starter puts `docs.config.yaml` and `content/` in your project. Initialization refuses to overwrite starter files, and preserves unrelated files such as the package manifest and lockfile.
 
 Preview the starter:
 
@@ -168,9 +168,13 @@ Change `site.title` in `docs.config.yaml`, replace the Acme example content, and
 
 Continue by [adding an OpenAPI API](https://www.shoalrun.com/publish/api-references.md), or [publish your site](https://www.shoalrun.com/publish.md).
 
+## Migrating from GitHub Packages
+
+The public npm package needs no account or token. If you used the earlier GitHub Packages alpha, run `npm config get @shoalrun:registry`. Remove or replace any `@shoalrun:registry=https://npm.pkg.github.com` entry in your project or user `.npmrc`. To explicitly select npm during migration, add `--@shoalrun:registry=https://registry.npmjs.org` to the install command below. Commit the updated manifest and lockfile together, and check that Shoalrun resolves from `registry.npmjs.org`.
+
 ## Build this site
 
-Shoalrun's documentation repository installs the package too. From that repository's root, run `npm ci` and `npm run docs:dev`. It serves these docs at `http://127.0.0.1:8770/`.
+If you maintain Shoalrun’s documentation source, follow [Build this documentation site](https://www.shoalrun.com/recipes/build-docs.md). That workflow uses the docs repository and its npm scripts.
 
 ## Check writing style
 

package/agent-docs/start.sections/build-this-site.md

@@ -32,4 +32,4 @@ This quickstart takes you from installing Shoalrun to your own working documenta
 
 ## Build this site
 
-Shoalrun's documentation repository installs the package too. From that repository's root, run `npm ci` and `npm run docs:dev`. It serves these docs at `http://127.0.0.1:8770/`.
+If you maintain Shoalrun’s documentation source, follow [Build this documentation site](https://www.shoalrun.com/recipes/build-docs.md). That workflow uses the docs repository and its npm scripts.

package/agent-docs/start.sections/migrating-from-github-packages.md

@@ -0,0 +1,35 @@
+---
+id: guide.overview
+title: Getting started
+summary: Create a site, publish a page, and check both formats.
+type: tutorial
+area: project
+subarea: project-overview
+canonical: /start
+---
+
+# Getting started
+
+> 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)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/start.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Create a page](https://www.shoalrun.com/author/add-page.md) — Create another page and add it to navigation.
+
+This quickstart takes you from installing Shoalrun to your own working documentation site. You will scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
+
+> **Alpha:** Pin an exact version and review release notes before upgrading. Configuration and output formats may change between alpha releases.
+
+## Migrating from GitHub Packages
+
+The public npm package needs no account or token. If you used the earlier GitHub Packages alpha, run `npm config get @shoalrun:registry`. Remove or replace any `@shoalrun:registry=https://npm.pkg.github.com` entry in your project or user `.npmrc`. To explicitly select npm during migration, add `--@shoalrun:registry=https://registry.npmjs.org` to the install command below. Commit the updated manifest and lockfile together, and check that Shoalrun resolves from `registry.npmjs.org`.

package/agent-docs/start.sections/prerequisites.md

@@ -34,4 +34,4 @@ This quickstart takes you from installing Shoalrun to your own working documenta
 
 Install Node.js 22.12 or newer and npm. Use the npm that comes with Node.js; Shoalrun sets no separate npm version. The commands below use a POSIX shell, such as Bash or Zsh.
 
-The public npm package needs no account or token. If you used the earlier GitHub Packages alpha, run `npm config get @shoalrun:registry`. Remove or replace any `@shoalrun:registry=https://npm.pkg.github.com` entry in your project or user `.npmrc`. To explicitly select npm during migration, add `--@shoalrun:registry=https://registry.npmjs.org` to the install command below. Commit the updated manifest and lockfile together, and check that Shoalrun resolves from `registry.npmjs.org`.
+The public npm package needs no account or token.

package/agent-docs/start.sections/start-your-own-project.md

@@ -42,7 +42,7 @@ npm install --save-exact @shoalrun/cli@0.1.0-alpha.11
 npx --no-install shoalrun init .
 ```
 
-[Diagrams](https://www.shoalrun.com/author/components/diagrams.md) build without Chrome. The starter puts `docs.config.yaml` and `content/` in your project. Initialization refuses to overwrite starter files, and preserves unrelated files such as the package manifest and lockfile.
+The starter puts `docs.config.yaml` and `content/` in your project. Initialization refuses to overwrite starter files, and preserves unrelated files such as the package manifest and lockfile.
 
 Preview the starter:
 

package/agent-docs/status.md

@@ -12,9 +12,9 @@ canonical: /status
 
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
 
-Navigation section: [Project updates](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Project updates](https://www.shoalrun.com/status.md) > Project > Project status
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Project > Project status
 
 **Updated: 2026-10-27.**
 

package/agent-docs/styling/color-modes.md

@@ -14,9 +14,9 @@ canonical: /styling/color-modes
 
 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)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Light and dark mode
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Light and dark mode
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Every [palette](https://www.shoalrun.com/styling/palettes.md) has a light set and a dark set. `theme.mode` decides which set readers see.
 
@@ -76,6 +76,10 @@ Target a mode in project CSS with `[data-mode="dark"]`, or with `prefers-color-s
 
 Code blocks stay dark in both modes. By default, their syntax colors come from the palette's dark set. The [code block guide](https://www.shoalrun.com/author/components/code-blocks.md) explains how to change it.
 
+## HTML, Markdown, and agents
+
+Light and dark mode change HTML colors, not the authored content. Without JavaScript, system mode follows the operating system preference and the toggle stays hidden. Markdown has no color toggle or saved browser preference; agents receive the same text, code, and links regardless of the chosen mode. Use visible labels for meaning that color reinforces.
+
 ## Related reading
 
 ### Related topics

package/agent-docs/styling/footer.md

@@ -15,9 +15,9 @@ canonical: /styling/footer
 
 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)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Site footer
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Site footer
 
-**Updated: 2026-10-25.**
+**Updated: 2026-10-27.**
 
 The footer sits below every page, after the navigation and article. Configure it under `site.footer`. Without that setting, the site has no footer.
 
@@ -46,11 +46,11 @@ Columns appear first, side by side on wide screens and stacked on phones. Below
 
 These settings configure the footer text and its links.
 
-| Setting   | Required | Value                                                                                                         |
-| --------- | -------- | ------------------------------------------------------------------------------------------------------------- |
-| `columns` | No       | A list of link groups. Each has a `title` and a `links` list with at least one link.                          |
-| `links`   | No       | Links for the bottom row, such as legal pages.                                                                |
-| `text`    | No       | One line of plain text, such as a copyright notice. The build escapes it, so HTML and Markdown show as typed. |
+| Setting   | Required | Value                                                                                                                |
+| --------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
+| `columns` | No       | A list of link groups. Each has a `title` and a `links` list with at least one link.                                 |
+| `links`   | No       | Links for the bottom row, such as legal pages.                                                                       |
+| `text`    | No       | One line of plain text, such as a copyright notice. The build escapes it and displays it as text in the HTML footer. |
 
 Each link takes a `label` and an `href`. An `href` is a site-root path such as `/start`, an `http` or `https` URL, or a `mailto:` link. External `http` and `https` links get `rel="noopener"`. The build rejects any other URL scheme, including `javascript:`.
 
@@ -60,7 +60,9 @@ Footer links don't take a `style`. Use [header links](https://www.shoalrun.com/s
 
 The footer uses the page's theme tokens, so each [theme preset](https://www.shoalrun.com/styling/themes.md) and palette restyles it. On `landing` and `splash` [layouts](https://www.shoalrun.com/styling/layouts.md), it matches the narrower landing width. The [CSS and theme reference](https://www.shoalrun.com/author/css.md) lists its classes.
 
-The footer is part of the HTML page only. Markdown twins, search results, and `/llms.txt` do not include it.
+## HTML, Markdown, and agents
+
+The footer appears in HTML with ordinary links that work without JavaScript. Markdown twins, search results, and `/llms.txt` omit it. An agent reading those files cannot discover a destination from the footer alone. Include links needed to complete a task in the article or its reading relationships.
 
 ## Related reading
 

package/agent-docs/styling/header.md

@@ -14,9 +14,9 @@ canonical: /styling/header
 
 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)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Header links
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Header links
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 The masthead shows the site title, the publication label, the [search box](https://www.shoalrun.com/author/search.md), the [dark mode toggle](https://www.shoalrun.com/styling/color-modes.md) when it's on, and any links you configure. Add links under `site.header.links`:
 
@@ -50,7 +50,9 @@ External `http` and `https` links get `rel="noopener"`. The build rejects any ot
 
 On narrow screens, the search box and links wrap onto their own row below the site title. Each [theme preset](https://www.shoalrun.com/styling/themes.md) restyles them to match its shape. The [CSS and theme reference](https://www.shoalrun.com/author/css.md) lists their classes.
 
-Header links are part of the HTML page only. Markdown twins and `/llms.txt` do not include them.
+## HTML, Markdown, and agents
+
+Header links appear in HTML as ordinary links, including links styled as buttons. They remain usable without JavaScript. Markdown twins and `/llms.txt` omit the masthead, so agents reading those files do not receive its links. Put a task's essential next step in the article or its reading relationships as well as the header.
 
 ## Related reading
 

package/agent-docs/styling/layouts.md

@@ -14,9 +14,9 @@ canonical: /styling/layouts
 
 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)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Page layouts, landing pages, and splash pages
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Page layouts, landing pages, and splash pages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Every page uses the `docs` layout unless its frontmatter sets `layout`. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
 
@@ -104,7 +104,7 @@ Or put one fenced code block in the body. It appears in an editor-style window w
   [Start building](doc:guide.overview)
 
   ```sh title="Build and preview this site"
-  npm ci --prefix framework
+  npm ci
   npm run docs:dev
   ```
 </Hero>
@@ -186,6 +186,10 @@ To change it for your site, use [project CSS](https://www.shoalrun.com/author/cs
 
 Keep text readable against any background you choose. The build checks palette colors for contrast, but not project CSS.
 
+## HTML, Markdown, and agents
+
+Layouts control HTML sidebars, outlines, column widths, and full-width bands. They do not create separate content for agents. In Markdown, a `Hero` retains its tagline, action links, and supported image or code content; `Section` retains its body in source order without the visual wrapper. Agents can follow the links and read the content without interpreting the layout or running browser scripts. Keep essential meaning in the authored text rather than background styling or motion.
+
 ## Related reading
 
 ### Reference while working

package/agent-docs/styling/layouts.sections/build-a-landing-page.md

@@ -14,9 +14,9 @@ canonical: /styling/layouts
 
 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)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Page layouts, landing pages, and splash pages
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Page layouts, landing pages, and splash pages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/styling/layouts.md)
 

package/agent-docs/styling/layouts.sections/build-a-splash-page.md

@@ -14,9 +14,9 @@ canonical: /styling/layouts
 
 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)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Page layouts, landing pages, and splash pages
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Page layouts, landing pages, and splash pages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/styling/layouts.md)
 

package/agent-docs/styling/layouts.sections/control-navigation-tabs.md

@@ -14,9 +14,9 @@ canonical: /styling/layouts
 
 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)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Page layouts, landing pages, and splash pages
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Page layouts, landing pages, and splash pages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/styling/layouts.md)
 

package/agent-docs/styling/layouts.sections/customize-the-hero.md

@@ -14,9 +14,9 @@ canonical: /styling/layouts
 
 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)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Page layouts, landing pages, and splash pages
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Page layouts, landing pages, and splash pages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/styling/layouts.md)
 

package/agent-docs/styling/layouts.sections/hero.md

@@ -14,9 +14,9 @@ canonical: /styling/layouts
 
 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)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Page layouts, landing pages, and splash pages
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Page layouts, landing pages, and splash pages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/styling/layouts.md)
 
@@ -66,7 +66,7 @@ Or put one fenced code block in the body. It appears in an editor-style window w
   [Start building](doc:guide.overview)
 
   ```sh title="Build and preview this site"
-  npm ci --prefix framework
+  npm ci
   npm run docs:dev
   ```
 </Hero>

package/agent-docs/styling/layouts.sections/html-markdown-and-agents.md

@@ -0,0 +1,40 @@
+---
+id: guide.layouts
+title: Page layouts, landing pages, and splash pages
+summary: Configure wide, landing, and splash pages with Hero and Sections.
+type: reference
+area: appearance
+subarea: appearance-layouts
+canonical: /styling/layouts
+---
+
+# Page layouts, landing pages, and splash pages
+
+> 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)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Page layouts, landing pages, and splash pages
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/styling/layouts.md)
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
+
+| Layout    | Sidebar | On this page | Use it for                                                                                                               |
+| --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `docs`    | Yes     | Yes          | Guides and reference pages. This is the default.                                                                         |
+| `wide`    | Yes     | No           | Wide tables, diagrams, and API overviews that need the full content width.                                               |
+| `landing` | No      | No           | Home pages and product entry points. A `Hero` replaces the page header.                                                  |
+| `splash`  | No      | No           | Marketing pages built from full-width bands. A `Hero` replaces the page header, and `Section` blocks stack edge to edge. |
+
+```yaml title="Frontmatter"
+layout: wide
+```
+
+An unknown value fails the build. Each preset styles all four layouts, and project CSS can target one through `html[data-layout="wide"]`, `html[data-layout="landing"]`, or `html[data-layout="splash"]`.
+
+## HTML, Markdown, and agents
+
+Layouts control HTML sidebars, outlines, column widths, and full-width bands. They do not create separate content for agents. In Markdown, a `Hero` retains its tagline, action links, and supported image or code content; `Section` retains its body in source order without the visual wrapper. Agents can follow the links and read the content without interpreting the layout or running browser scripts. Keep essential meaning in the authored text rather than background styling or motion.

package/agent-docs/styling/layouts.sections/related-reading.md

@@ -14,9 +14,9 @@ canonical: /styling/layouts
 
 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)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Page layouts, landing pages, and splash pages
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Page layouts, landing pages, and splash pages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/styling/layouts.md)
 

package/agent-docs/styling/palettes.md

@@ -15,9 +15,9 @@ canonical: /styling/palettes
 
 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)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Color palettes
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Color palettes
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 A palette sets every color token on the site, with one set for light mode and one for dark mode. Choose a built-in palette by name, or extend one with your own colors.
 
@@ -129,6 +129,10 @@ On success, its JSON output includes `"contrast": { "status": "ok", "palette": "
 
 The check covers palette colors only. Colors you set in [project CSS](https://www.shoalrun.com/author/css.md), and syntax colors from a named Shiki theme, are not checked. Test those yourself. The default `site` code theme derives its syntax colors from the palette and replaces any that fall below 4.5:1 with plain code text.
 
+## HTML, Markdown, and agents
+
+Palette tokens style the HTML page in light and dark modes. Markdown retains the content without palette colors, so agents cannot infer a status or distinction from a color choice. Pair color with a text label, such as a badge's status. Palette contrast checks assess the configured color pairs; they do not establish that the page's meaning is complete in either format.
+
 ## Related reading
 
 ### Read first

package/agent-docs/styling/share-images.md

@@ -15,9 +15,9 @@ canonical: /styling/share-images
 
 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)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Share images and favicon
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Share images and favicon
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 When someone pastes a page link into Slack, LinkedIn, or X, the preview shows an image. Shoalrun draws one for every page at build time and adds the tags those apps read. It also generates a favicon. Both follow the site's preset and palette, so they need no setup.
 
@@ -98,6 +98,10 @@ site:
 
 A missing file or another format fails the build.
 
+## HTML, Markdown, and agents
+
+Share images are generated image files referenced by the HTML page's social metadata. The image is not a substitute for the page's authored title, summary, or instructions. Agents reading Markdown receive the text and any metadata selected for that format, without needing to interpret a social preview image. Keep information needed for a task in the page body.
+
 ## Related reading
 
 ### Read first

package/agent-docs/styling/themes.md

@@ -15,9 +15,9 @@ canonical: /styling/themes
 
 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)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Themes
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Themes
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 The `theme` setting controls how the HTML site looks. It has five keys, and each has a default:
 
@@ -96,7 +96,6 @@ Fonts set here become the `--font-body`, `--font-heading`, and `--font-code` [CS
 The HTML page links stylesheets in this order. Later files override earlier ones.
 
 1. `/assets/site.css`, which imports the base tokens and header styles.
-   - `/assets/theme-preview.css` follows it, on pages that use the [theme previewer](https://www.shoalrun.com/styling/try.md).
 2. `/assets/theme.css`, for a preset other than `shoal`.
 3. `/assets/palette.css`, generated for any palette or mode other than `kelp` in light mode.
 4. `/assets/fonts.css`, generated from `theme.fonts`, unless it's `system` and sets nothing.
@@ -108,6 +107,10 @@ When a site uses a non-default preset, palette, or mode, the `html` element carr
 [data-theme="ledger"] .page-head h1 { letter-spacing: 0; }
 ```
 
+## HTML, Markdown, and agents
+
+Presets and fonts style the HTML page through generated stylesheets. They do not change its Markdown text or add font and layout instructions to the Markdown twin. An agent reading Markdown receives the authored content without needing the theme assets. Keep labels, hierarchy, and instructions meaningful without relying on typography or position alone.
+
 ## Related reading
 
 ### Next steps

package/agent-docs/styling/try.md

@@ -13,11 +13,11 @@ canonical: /styling/try
 
 > 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: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Try a theme
+Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Try a theme
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Pick a shape, a palette, and a mode. This page restyles itself as you choose. Scroll down to see how each option styles the sample content, then copy the config into `docs.config.yaml`.
 
@@ -87,18 +87,6 @@ Readers always see the dark set.
 
 The site follows each reader's system setting, with an optional toggle.
 
-## Add the previewer to a page
-
-Place the component on its own line in any MDX page:
-
-```mdx
-<ThemePreview />
-```
-
-The component takes no attributes. The build then publishes every preset and palette under `/assets/themes/`, so the previewer works on a static host. Sites that don't use the component don't publish those files.
-
-Without JavaScript, and in the Markdown twin, the component shows the preset and palette tables and an example config.
-
 ## Related reading
 
 ### Related topics

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoalrun/cli",
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.12",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"

package/agent-docs/.well-known/shoalrun/navigation/changelog-tab-50f26fe22670.txt

@@ -1,33 +0,0 @@
-# Changelog
-
-Full-page token counts use cl100k_base. Navigation section ID: changelog-tab. Publication: production/current/en.
-
-[All sections and published pages](https://www.shoalrun.com/llms.min.txt). This index covers this section only; shared and unlisted pages remain reachable through the global index. Reader views do not remove pages from this index.
-
-- [Agent discovery, verified Markdown, and incremental sync](https://www.shoalrun.com/changelog/2026-10-14-agent-readiness.md) — ID: change.agent-readiness. changelog-entry; 549 tokens. Compact discovery, content verification, and incremental fetching.
-
-- [Agent reading and evaluation](https://www.shoalrun.com/changelog/2026-10-15-evaluation-builds.md) — ID: change.evaluation-builds. changelog-entry; 1699 tokens. Smaller reads, lifecycle guidance, and reproducible evaluations.
-
-- [Content exports and documentation checks](https://www.shoalrun.com/changelog/2026-10-25.md) — ID: change.2026-10-25. changelog-entry; 671 tokens. Content exports and documentation checks.
-
-- [Safer exports and easier discovery for AI assistants](https://www.shoalrun.com/changelog/2026-10-26.md) — ID: change.2026-10-26. changelog-entry; 1291 tokens. Keep exported images and links with their pages, and help AI assistants find docs by topic.
-
-- [Clearer defaults, a feature showcase, and easier navigation](https://www.shoalrun.com/changelog/2026-10-27.md) — ID: change.2026-10-27. changelog-entry; 1226 tokens. Explore a complete starter, read clearer controls, and find focused configuration references alongside the new mobile navigation.
-
-- [Authoring snapshot previews and review reports](https://www.shoalrun.com/changelog/authoring-preview.md) — ID: change.authoring-preview. changelog-entry; 554 tokens. Snapshot previews with coverage and freshness reports.
-
-- [Agent authoring, search, and documentation answers](https://www.shoalrun.com/changelog/authoring-search.md) — ID: change.authoring-search. changelog-entry; 469 tokens. Reviewed agent drafts, search improvements, and answer context.
-
-- [Working-tree authoring tools](https://www.shoalrun.com/changelog/authoring-tools.md) — ID: change.authoring-tools. changelog-entry; 381 tokens. Project discovery and captured working-tree validation.
-
-- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 1002 tokens. Compiler, CLI, and reader changes.
-
-- [MCP hosting, analytics, and component improvements](https://www.shoalrun.com/changelog/2026-10-17-mcp-hosting.md) — ID: change.mcp-hosting. changelog-entry; 1148 tokens. MCP hosting, analytics, and shared component content.
-
-- [Navigation, page layouts, and browser analytics](https://www.shoalrun.com/changelog/2026-10-16-navigation-layouts.md) — ID: change.navigation-layouts. changelog-entry; 1095 tokens. Navigation sections, reader controls, layouts, and browser analytics.
-
-- [Search results and tooltips](https://www.shoalrun.com/changelog/2026-10-18-search-and-tooltips.md) — ID: change.search-and-tooltips. changelog-entry; 671 tokens. Indexed search and hover and focus tooltips.
-
-- [Experimental visual navigation and taxonomy enforcement](https://www.shoalrun.com/changelog/2026-10-19-visual-navigation.md) — ID: change.visual-navigation. changelog-entry; 749 tokens. Visual navigation and taxonomy validation.
-
-- [Portable working-tree authoring workflow](https://www.shoalrun.com/changelog/working-tree-skill.md) — ID: change.working-tree-skill. changelog-entry; 481 tokens. Agent discovery, native editing, validation, and snapshot review.

package/agent-docs/publish/api-references.sections/add-useful-examples.md

@@ -1,36 +0,0 @@
----
-id: guide.api-references
-title: Add an OpenAPI API
-summary: Import a local OpenAPI file, author an operation page, review its
-  public content, and build HTML and Markdown.
-type: how-to
-area: api
-subarea: api-contracts
-canonical: /publish/api-references
----
-
-# Add an OpenAPI API
-
-> 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)
-
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
-
-**Updated: 2026-10-26.**
-
-Parent page: [Full Markdown page](/publish/api-references.md)
-
-**Page reading path** — these links apply to the full page.
-
-**Next steps**
-
-- [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
-
-Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You will register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
-
-Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
-
-## Add useful examples
-
-[Named examples and generated commands](https://www.shoalrun.com/api-docs/generate.md) explains example selection, JSON shapes, and cURL behavior.

package/agent-docs/publish/api-references.sections/describe-filters-that-do-not-use-their-openapi-parameter-name.md

@@ -1,36 +0,0 @@
----
-id: guide.api-references
-title: Add an OpenAPI API
-summary: Import a local OpenAPI file, author an operation page, review its
-  public content, and build HTML and Markdown.
-type: how-to
-area: api
-subarea: api-contracts
-canonical: /publish/api-references
----
-
-# Add an OpenAPI API
-
-> 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)
-
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
-
-**Updated: 2026-10-26.**
-
-Parent page: [Full Markdown page](/publish/api-references.md)
-
-**Page reading path** — these links apply to the full page.
-
-**Next steps**
-
-- [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
-
-Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You will register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
-
-Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
-
-## Describe filters that do not use their OpenAPI parameter name
-
-The [query syntax example](https://www.shoalrun.com/api-docs/generate.md) configures direct query expressions and generated cURL.