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

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

@@ -0,0 +1,53 @@
+---
+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.
+
+## Start your own project
+
+Install an exact version of the alpha and initialize the minimal starter:
+
+```sh
+mkdir my-docs
+cd my-docs
+npm init -y
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.11
+npx --no-install shoalrun init .
+```
+
+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:
+
+```sh
+npx --no-install shoalrun dev docs.config.yaml site-dist --port 8765
+```
+
+Open `http://127.0.0.1:8765/`. You should see the Acme handbook example with a welcome page and an installation page. Press **Ctrl+C** to stop the preview before continuing.

package/agent-docs/status.md

@@ -0,0 +1,75 @@
+---
+id: guide.status
+title: Project status
+summary: Current capabilities, planned features, and known limits.
+type: reference
+area: project
+subarea: project-overview
+canonical: /status
+---
+
+# Project 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](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](https://www.shoalrun.com/status.md) > Project > Project status
+
+**Updated: 2026-10-27.**
+
+Shoalrun is an alpha for publishing documentation for people and agents from the same source. This site is built with it. Install the public `@shoalrun/cli` npm package through [Getting started](https://www.shoalrun.com/start.md). No account or package token is needed.
+
+## What works today
+
+- **One source, two reading formats.** Markdown and supported MDX components produce a browser site and a [Markdown copy of every page](https://www.shoalrun.com/publish/agent-friendliness.md). Generated indexes, manifests, and section resources help agents discover and read the content without running the site’s JavaScript.
+
+- **Structured authoring.** Templates, reusable snippets, custom metadata, and composable configuration support guides and reference pages. Stable page IDs connect links, cards, navigation, and related reading. [Recipes and cookbooks](https://www.shoalrun.com/author/recipes.md) combine reusable instructions into complete workflows. [Agent authoring tools](https://www.shoalrun.com/author/agents.md) provide project discovery, source context, draft previews, and local validation for your existing coding agent.
+
+- **Rich documentation pages.** Built-in [components](https://www.shoalrun.com/author/components.md) include tabs, callouts, tables, code walkthroughs, steps, timelines, and API embeds, with defined Markdown output. [Diagrams](https://www.shoalrun.com/author/components/diagrams.md) render D2 and Mermaid syntax as SVG during the build; Pele renders the Mermaid diagrams. Markdown retains the diagram source and explanation.
+
+- **Reader controls.** [File trees](https://www.shoalrun.com/author/components/file-tree.md) have expandable folders and keyboard navigation. [Collapsible groups](https://www.shoalrun.com/author/components/collapsible.md) join related disclosures without gaps. Authors can synchronize related [tabs](https://www.shoalrun.com/author/components/tabs.md) and add captions or expanded viewing to [images](https://www.shoalrun.com/author/components/images.md).
+
+- **Configurable sites.** Themes, palettes, layouts, headers, and footers shape the presentation. [Navigation tabs](https://www.shoalrun.com/author/navigation.md) organize larger sites into sections. Explicit [versions and languages](https://www.shoalrun.com/publish/publications.md) publish separate page variants, while reader views tailor navigation and marked content to different audiences.
+
+- **API documentation.** [OpenAPI sources](https://www.shoalrun.com/publish/api-references.md) supply reference pages, named examples, request samples, and contracts for individual operations. Authors can combine generated references with guides and review imported API content before publishing it.
+
+- **Search and documentation tools.** Built-in search works in the browser without a model key. Optional [semantic search and cited answers](https://www.shoalrun.com/search-and-chat.md) use your configured providers. Read-only [Model Context Protocol (MCP) tools](https://www.shoalrun.com/publish/mcp.md) let agents search and read pages or sections. They run through a local stdio process or a public HTTP endpoint on Node or Vercel.
+
+- **Publishing and measurement.** Local previews and checks support static publishing, with Node and Vercel serving options. Optional [browser analytics](https://www.shoalrun.com/author/analytics.md) and [HTTP MCP analytics](https://www.shoalrun.com/publish/mcp-analytics.md) send events through adapters to your chosen service. Both are off by default; their guides describe the event fields, filtering, and configuration.
+
+- **Experimental visual navigation.** [Explore the docs](https://www.shoalrun.com/explore.md) offers circles, expandable branches, arcs, a relationship matrix, and a force layout. The views use declared page categories and reading relationships, including authored explanations. Agents can read the same metadata and relationships through the document manifest without running the visualization.
+
+## What I want to add next
+
+- **Optional vector-store connections.** Add adapters for customers’ own vector stores for semantic search. Keep file-based indexes as the default, and preserve document identity, publication filtering, updates, and deletions across storage options. Content exports should remain usable without a vector store.
+- **Improve visual navigation.** Refine layout sizing, label collisions, dense graph views, filtering, relationship explanations, and accessibility as we try the experimental explorer on larger documentation sets.
+- **Custom access control.** Add connectors for customers’ own role-based access control (RBAC) systems, with consistent access decisions across HTML, Markdown, search, downloads, and MCP.
+
+These are intended additions, without a promised release date.
+
+## Current limits
+
+- **Alpha stability.** Configuration, extension points, and output formats can still change. There is no stable release or compatibility promise yet.
+- **Component extensibility.** [Trusted custom components](https://www.shoalrun.com/author/components/custom.md) lower into shared content, with a portable authoring skill. Arbitrary executable MDX remains unsupported. Project CSS, browser modules, and configured build extensions are trusted project code.
+- **API coverage.** OpenAPI and JSON Schema support is partial; check the [support reference](https://www.shoalrun.com/api-docs/support.md) against your source. Request examples are copyable, but Shoalrun does not provide a live API explorer that sends requests.
+- **Private content.** Reader views do not restrict access to published files. Shoalrun has no built-in reader authentication, and its HTTP MCP endpoint currently serves one selected public publication. Host-level authorization is a separate responsibility.
+- **Managed services.** Shoalrun does not provide managed hosting, translation, or chat. Versions and translations need explicit authored variants. Optional model and analytics services need your own configuration and accounts.
+
+Automatic skill generation and general agent orchestration are [deliberate non-goals](https://www.shoalrun.com/non-goals.md). Authors remain responsible for the accuracy and usefulness of their documentation.
+
+## Related reading
+
+### Reference while working
+
+- [Evaluate agent tasks against your docs](https://www.shoalrun.com/publish/evals.md) — Evaluate realistic tasks against the built documentation.
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) — Configure and test the implemented stdio documentation tools.
+
+### Related topics
+
+- [Non-goals](https://www.shoalrun.com/non-goals.md) — Distinguish deliberate scope limits from deferred features.
+
+- [Changelog](https://www.shoalrun.com/changelog.md) — Check implemented capabilities and the remaining release work.
+
+- [Navigation, page layouts, and browser analytics](https://www.shoalrun.com/changelog/2026-10-16-navigation-layouts.md) — Check the alpha's capabilities and current limits.

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

@@ -0,0 +1,89 @@
+---
+id: guide.color-modes
+title: Light and dark mode
+summary: Light, dark, and system modes, toggle behavior, storage, and accessibility.
+type: reference
+area: appearance
+subarea: appearance-themes
+canonical: /styling/color-modes
+---
+
+# Light and dark mode
+
+> 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 > Light and dark mode
+
+**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.
+
+| Mode     | Behavior                                                                              |
+| -------- | ------------------------------------------------------------------------------------- |
+| `light`  | The default. Readers always see light mode.                                           |
+| `dark`   | Readers always see dark mode.                                                         |
+| `system` | Follows the reader's operating system setting. Shows a toggle unless you turn it off. |
+
+## Lock the site to one mode
+
+```yaml title="docs.config.yaml"
+theme:
+  mode: dark
+```
+
+A locked site writes only the colors for that mode and shows no toggle. The build checks contrast for that mode only.
+
+## Follow the reader's setting
+
+```yaml title="docs.config.yaml"
+theme:
+  mode: system
+```
+
+The site starts in the mode the reader's system prefers. A button in the masthead switches between light and dark. The browser stores the choice under the `shoalrun-color-mode` local storage key on that device, and the choice overrides the system setting.
+
+To follow the system setting without a toggle, set `toggle: false`:
+
+```yaml title="docs.config.yaml"
+theme:
+  mode: system
+  toggle: false
+```
+
+`toggle: true` works only with `mode: system`. The build checks contrast for both modes.
+
+Custom callout tones need dark colors before a site can show dark mode. The [callout guide](https://www.shoalrun.com/author/components/callout.md) explains the `dark` block.
+
+## How it works
+
+- `mode: system` writes both color sets to `/assets/palette.css`. The dark set applies inside `@media (prefers-color-scheme: dark)`.
+- The page sets `<meta name="color-scheme">` to `light`, `dark`, or `light dark`, so scrollbars and form controls match.
+- With the toggle on, `/assets/mode.js` loads in the page head before first paint. It reads the saved choice and sets `data-mode="light"` or `data-mode="dark"` on the `html` element, so the page doesn't flash the wrong colors.
+- The toggle is a `button` with `aria-pressed`. Screen readers announce it as "Dark mode", pressed or not pressed.
+- Without JavaScript, the toggle stays hidden and the system setting still applies.
+- If the browser blocks storage, the toggle still works for the current page.
+
+Target a mode in project CSS with `[data-mode="dark"]`, or with `prefers-color-scheme` for readers who have not used the toggle:
+
+```css title="styles/project.css"
+@media (prefers-color-scheme: dark) {
+  :root:not([data-mode="light"]) .doc-card-icon { opacity: .9; }
+}
+:root[data-mode="dark"] .doc-card-icon { opacity: .9; }
+```
+
+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
+
+- [Header links](https://www.shoalrun.com/styling/header.md) — The dark mode toggle appears in the header beside your links.
+
+- [Color palettes](https://www.shoalrun.com/styling/palettes.md) — A palette has one color set for light mode and one for dark mode.

package/agent-docs/styling/footer.md

@@ -0,0 +1,69 @@
+---
+id: guide.footer
+title: Site footer
+summary: Add link columns, a bottom row of links, and a short text line below
+  every page.
+type: reference
+area: appearance
+subarea: appearance-navigation
+canonical: /styling/footer
+---
+
+# Site footer
+
+> 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 > Site footer
+
+**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.
+
+```yaml title="docs.config.yaml"
+site:
+  title: Example documentation
+  footer:
+    columns:
+      - title: Guides
+        links:
+          - { label: Get started, href: /start }
+          - { label: Authentication, href: /guides/auth }
+      - title: Company
+        links:
+          - { label: Status, href: "https://status.example.com" }
+          - { label: Contact support, href: "mailto:support@example.com" }
+    links:
+      - { label: Privacy, href: /legal/privacy }
+      - { label: Terms, href: /legal/terms }
+    text: © 2026 Example, Inc.
+```
+
+Columns appear first, side by side on wide screens and stacked on phones. Below them, a bottom row shows `text` on the left and `links` on the right. Every part is optional, but the footer needs at least one of them.
+
+## Footer settings
+
+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 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:`.
+
+Footer links don't take a `style`. Use [header links](https://www.shoalrun.com/styling/header.md) for buttons and calls to action.
+
+## Layout and themes
+
+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.
+
+## 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
+
+No matching documents.

package/agent-docs/styling/header.md

@@ -0,0 +1,67 @@
+---
+id: guide.header
+title: Header links
+summary: Add links and buttons to the site masthead.
+type: reference
+area: appearance
+subarea: appearance-navigation
+canonical: /styling/header
+---
+
+# Header links
+
+> 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 > Header links
+
+**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`:
+
+```yaml title="docs.config.yaml"
+site:
+  title: Example documentation
+  header:
+    links:
+      - { label: Guides, href: /start }
+      - { label: GitHub, href: "https://github.com/example/project", style: button }
+      - { label: Get started, href: /start, style: primary }
+```
+
+Links appear in list order, after the search box and toggle.
+
+## Link settings
+
+Use these settings to configure each link shown in the header.
+
+| Setting | Required | Value                                                                             |
+| ------- | -------- | --------------------------------------------------------------------------------- |
+| `label` | Yes      | Visible link text.                                                                |
+| `href`  | Yes      | A site-root path such as `/start`, an `http` or `https` URL, or a `mailto:` link. |
+| `style` | No       | `link` (default), `button`, or `primary`.                                         |
+
+`link` renders as plain text. `button` has an outline. `primary` fills with `--color-accent` and uses `--color-accent-contrast` for its text. Use one `primary` link at most, for the action you most want readers to take.
+
+External `http` and `https` links get `rel="noopener"`. The build rejects any other URL scheme, including `javascript:`.
+
+## Layout and themes
+
+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.
+
+## 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
+
+### Reference while working
+
+- [CSS and theme reference](https://www.shoalrun.com/author/css.md) — Look up the header classes each preset styles.
+
+### Related topics
+
+- [Light and dark mode](https://www.shoalrun.com/styling/color-modes.md) — The dark mode toggle appears in the header beside your links.
+
+- [Site search](https://www.shoalrun.com/author/search.md) — The search box sits in the site header, before your header links.

package/agent-docs/styling/layouts.md

@@ -0,0 +1,197 @@
+---
+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.**
+
+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"]`.
+
+## 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.
+
+When the site config defines navigation tabs, docs and wide pages show the section bar by default. Landing and splash pages hide it by default. Override that choice on any page:
+
+```yaml title="Frontmatter"
+layout: splash
+showNavigationTabs: false
+```
+
+Set `showNavigationTabs: true` to include the tab bar on a landing or splash page. Set it to `false` to suppress it on a docs or wide page. The value must be a boolean and can also come from frontmatter defaults or enforced values. With no configured tabs, neither value creates a bar.
+
+This setting affects the HTML section bar only. It does not change the page's sidebar, tab membership, breadcrumbs, Markdown, search records, or agent indexes. An agent can still discover and read every published section without visiting the homepage.
+
+## Build a landing page
+
+Set `layout: landing`, then open the page with a `Hero`. To serve the page at the site root, give it `slug: /`. When a page has `slug: /`, the site title in the masthead links to it. This example is a small landing page:
+
+```mdx title="content/home.mdx"
+---
+id: guide.home
+title: Shoalrun
+summary: Payments for small teams, in five lines of code.
+type: overview
+slug: /
+layout: landing
+access: { policy: public }
+---
+
+<Hero tagline="Take your first payment in five lines of code.">
+  [Start building](doc:guide.overview)
+  [See how it works](doc:guide.concepts)
+</Hero>
+
+## Start here
+
+<DocCards docs={["guide.overview", "guide.concepts", "guide.api-references"]} />
+```
+
+## Hero
+
+`Hero` opens a landing page with a large title, a tagline, and up to three action buttons. It can also show an image or a code block beside the text.
+
+| Attribute  | Required     | Meaning                                                                                     |
+| ---------- | ------------ | ------------------------------------------------------------------------------------------- |
+| `tagline`  | Yes          | One or two sentences under the title.                                                       |
+| `title`    | No           | The large title. Defaults to the page `title`.                                              |
+| `align`    | No           | `center` (default) or `start`, which aligns the title, tagline, and buttons to the left.    |
+| `image`    | No           | An https URL, or a local `.png`, `.jpg`, `.webp`, or `.svg` file relative to the page file. |
+| `imageAlt` | With `image` | What the image shows. Use `imageAlt=""` when the image is decorative.                       |
+
+Put the actions in the body as ordinary Markdown links, one per line or as a list. The first link is the primary button. `doc:` links resolve by page ID, like everywhere else.
+
+### Show an image or code
+
+Add `image` and `imageAlt` to show a picture beside the text. The build copies a local image to `/assets/pages/<page path>/`.
+
+```mdx
+<Hero tagline="Payments in five lines of code." image="./images/dashboard.png" imageAlt="The payments dashboard showing today's volume">
+  [Get started](doc:guide.start)
+</Hero>
+```
+
+Or put one fenced code block in the body. It appears in an editor-style window with its title and a Copy button, and keeps the site's code colors. The home page of this site uses one.
+
+````mdx
+<Hero tagline="Build API documentation from Markdown, MDX, and OpenAPI.">
+  [Start building](doc:guide.overview)
+
+  ```sh title="Build and preview this site"
+  npm ci
+  npm run docs:dev
+  ```
+</Hero>
+````
+
+With an image or code block, the hero splits into two columns, text first, and aligns to the left. Below `60rem` wide, the visual moves under the text. A hero can show an image or a code block, not both.
+
+### Rules
+
+- `Hero` needs `layout: landing` or `layout: splash`, and it replaces the page header, including the **Read as Markdown** link. Put it first on the page.
+- Attributes are literal text. The body can contain only action links and one code block; other content fails the build.
+- In the Markdown twin, `Hero` becomes the tagline, a list of its links, then its image (when `imageAlt` isn't empty) or its code block. A custom `title` that differs from the page title appears in bold before the tagline.
+
+Landing pages are centered and at most `76rem` wide, and the masthead lines up with them. On a phone, the hero stacks its buttons.
+
+## Build a splash page
+
+A splash page is a marketing page. Set `layout: splash`, open with a `Hero`, then build the rest from `Section` blocks. The layout removes the sidebar, the outline, and the content padding, so the hero and each section run edge to edge. This site's home page is a working example.
+
+```mdx title="content/home.mdx"
+---
+id: guide.home
+title: Acme
+summary: Payments for small teams.
+type: overview
+slug: /
+layout: splash
+access: { policy: public }
+---
+
+<Hero tagline="Take your first payment in five lines of code.">
+  [Start building](doc:guide.overview)
+</Hero>
+
+<Section id="features">
+
+## Why Acme
+
+Fast, simple, and built for small teams.
+
+</Section>
+
+<Section id="pricing" variant="raised">
+
+## Pricing
+
+<DocCards docs={["guide.pricing"]} />
+
+</Section>
+```
+
+`Section` wraps ordinary page content, such as headings, paragraphs, cards, tabs, tables, and code blocks. It centers that content in a column at most `--landing-width` wide, and its background runs the full width of the page.
+
+| Attribute | Required | Meaning                                                                                                                                                                                                                                                     |
+| --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`      | No       | An anchor for the section. Use lowercase letters, numbers, and dashes. It can't match a heading anchor on the page.                                                                                                                                         |
+| `variant` | No       | A name for the section's look, in lowercase letters, numbers, and dashes. It becomes `data-variant` in the HTML. `raised` is built in and gives the section a tinted band. Style any other name with [project CSS](https://www.shoalrun.com/author/css.md). |
+
+Two rules keep the page predictable:
+
+- `Section` needs `layout: splash`, and it can't contain another `Section`.
+- Content that sits outside a `Section` runs edge to edge, so put page content in a section.
+
+In the Markdown twin, a `Section` disappears and its content stays in order. Your styling, and any script you add, changes the HTML page only.
+
+Each section is a `section.splash-section` holding a `div.splash-inner`. To restyle a section, target `.splash-section[data-variant="pricing"]` in project CSS. The layout gives you a blank, full-width canvas, so backgrounds, spacing, and motion are yours to design.
+
+## Customize the hero
+
+Each preset styles the hero its own way. `shoal` adds a soft accent glow, and `reef` uses a tinted panel with pill buttons. `ledger` sets it in an inked band, and `vice` in a night sky with a sunset stripe.
+
+To change it for your site, use [project CSS](https://www.shoalrun.com/author/css.md). The hero is a `section.hero` containing `.hero-title`, `.hero-tagline`, and `.hero-actions`. Its buttons are `.hero-primary` and `.hero-secondary`. Set `--landing-width` to change the landing page width:
+
+```css title="styles/project.css"
+:root { --landing-width: 64rem; }
+.content .hero { background: linear-gradient(135deg, #0b3d2e, #14532d); }
+.content .hero-title, .content .hero-tagline { color: #fff; }
+```
+
+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
+
+- [CSS and theme reference](https://www.shoalrun.com/author/css.md) — Look up the width tokens and layout selectors.

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

@@ -0,0 +1,61 @@
+---
+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"]`.
+
+## Build a landing page
+
+Set `layout: landing`, then open the page with a `Hero`. To serve the page at the site root, give it `slug: /`. When a page has `slug: /`, the site title in the masthead links to it. This example is a small landing page:
+
+```mdx title="content/home.mdx"
+---
+id: guide.home
+title: Shoalrun
+summary: Payments for small teams, in five lines of code.
+type: overview
+slug: /
+layout: landing
+access: { policy: public }
+---
+
+<Hero tagline="Take your first payment in five lines of code.">
+  [Start building](doc:guide.overview)
+  [See how it works](doc:guide.concepts)
+</Hero>
+
+## Start here
+
+<DocCards docs={["guide.overview", "guide.concepts", "guide.api-references"]} />
+```