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

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

@@ -1,7 +1,8 @@
 ---
 id: guide.layouts
 title: Page layouts, landing pages, and splash pages
-summary: Configure wide, landing, and splash pages with Hero and Sections.
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
 type: reference
 area: appearance
 subarea: appearance-layouts
@@ -14,11 +15,13 @@ 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-28.**
 
-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.
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
 
 | Layout    | Sidebar | On this page | Use it for                                                                                                               |
 | --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |
@@ -33,6 +36,21 @@ 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"]`.
 
+## Hide the table of contents or give content more room
+
+To remove the right sidebar labeled “On this page” and widen the content area, set `layout: wide`. It keeps the left navigation and gives interactive tools, large tables, and diagrams more space.
+
+To hide the table of contents without choosing a different layout, set `tocDepth: 0`. To keep an outline with fewer heading levels, use `tocDepth: 2`. See [page metadata](https://www.shoalrun.com/author/frontmatter.md) for the supported depths.
+
+These settings serve different goals:
+
+| Goal                                                         | Page frontmatter                      |
+| ------------------------------------------------------------ | ------------------------------------- |
+| Give interactive content more space while keeping navigation | `layout: wide`                        |
+| Hide “On this page” within the current layout                | `tocDepth: 0`                         |
+| Keep “On this page” but list only main sections              | `tocDepth: 2`                         |
+| Remove navigation and the outline for an entry page          | `layout: landing` or `layout: splash` |
+
 ## Control navigation tabs
 
 The built-in layouts are `docs`, `wide`, `landing`, and `splash`. There is no `custom` layout value; use landing or splash for a custom entry page and style it with project CSS.
@@ -104,7 +122,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 +204,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

@@ -1,7 +1,8 @@
 ---
 id: guide.layouts
 title: Page layouts, landing pages, and splash pages
-summary: Configure wide, landing, and splash pages with Hero and Sections.
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
 type: reference
 area: appearance
 subarea: appearance-layouts
@@ -14,13 +15,15 @@ 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-28.**
 
 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.
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
 
 | Layout    | Sidebar | On this page | Use it for                                                                                                               |
 | --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |

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

@@ -1,7 +1,8 @@
 ---
 id: guide.layouts
 title: Page layouts, landing pages, and splash pages
-summary: Configure wide, landing, and splash pages with Hero and Sections.
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
 type: reference
 area: appearance
 subarea: appearance-layouts
@@ -14,13 +15,15 @@ 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-28.**
 
 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.
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
 
 | Layout    | Sidebar | On this page | Use it for                                                                                                               |
 | --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |

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

@@ -1,7 +1,8 @@
 ---
 id: guide.layouts
 title: Page layouts, landing pages, and splash pages
-summary: Configure wide, landing, and splash pages with Hero and Sections.
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
 type: reference
 area: appearance
 subarea: appearance-layouts
@@ -14,13 +15,15 @@ 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-28.**
 
 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.
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
 
 | Layout    | Sidebar | On this page | Use it for                                                                                                               |
 | --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |

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

@@ -1,7 +1,8 @@
 ---
 id: guide.layouts
 title: Page layouts, landing pages, and splash pages
-summary: Configure wide, landing, and splash pages with Hero and Sections.
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
 type: reference
 area: appearance
 subarea: appearance-layouts
@@ -14,13 +15,15 @@ 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-28.**
 
 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.
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
 
 | Layout    | Sidebar | On this page | Use it for                                                                                                               |
 | --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |

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

@@ -1,7 +1,8 @@
 ---
 id: guide.layouts
 title: Page layouts, landing pages, and splash pages
-summary: Configure wide, landing, and splash pages with Hero and Sections.
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
 type: reference
 area: appearance
 subarea: appearance-layouts
@@ -14,13 +15,15 @@ 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-28.**
 
 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.
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
 
 | Layout    | Sidebar | On this page | Use it for                                                                                                               |
 | --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |
@@ -66,7 +69,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/hide-the-table-of-contents-or-give-content-more-room.md

@@ -0,0 +1,54 @@
+---
+id: guide.layouts
+title: Page layouts, landing pages, and splash pages
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
+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-28.**
+
+Parent page: [Full Markdown page](/styling/layouts.md)
+
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. 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"]`.
+
+## Hide the table of contents or give content more room
+
+To remove the right sidebar labeled “On this page” and widen the content area, set `layout: wide`. It keeps the left navigation and gives interactive tools, large tables, and diagrams more space.
+
+To hide the table of contents without choosing a different layout, set `tocDepth: 0`. To keep an outline with fewer heading levels, use `tocDepth: 2`. See [page metadata](https://www.shoalrun.com/author/frontmatter.md) for the supported depths.
+
+These settings serve different goals:
+
+| Goal                                                         | Page frontmatter                      |
+| ------------------------------------------------------------ | ------------------------------------- |
+| Give interactive content more space while keeping navigation | `layout: wide`                        |
+| Hide “On this page” within the current layout                | `tocDepth: 0`                         |
+| Keep “On this page” but list only main sections              | `tocDepth: 2`                         |
+| Remove navigation and the outline for an entry page          | `layout: landing` or `layout: splash` |

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

@@ -0,0 +1,43 @@
+---
+id: guide.layouts
+title: Page layouts, landing pages, and splash pages
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
+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-28.**
+
+Parent page: [Full Markdown page](/styling/layouts.md)
+
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. 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

@@ -1,7 +1,8 @@
 ---
 id: guide.layouts
 title: Page layouts, landing pages, and splash pages
-summary: Configure wide, landing, and splash pages with Hero and Sections.
+summary: Hide the table of contents, give interactive content more space, or
+  build landing and splash pages.
 type: reference
 area: appearance
 subarea: appearance-layouts
@@ -14,13 +15,15 @@ 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-28.**
 
 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.
+Use `layout: wide` to hide “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only want to hide the table of contents within the current layout.
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Choose the page structure first, then adjust individual visibility settings. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
 
 | Layout    | Sidebar | On this page | Use it for                                                                                                               |
 | --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |

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