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

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

@@ -0,0 +1,88 @@
+---
+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 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.

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

@@ -0,0 +1,51 @@
+---
+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"]`.
+
+## 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.

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

@@ -0,0 +1,50 @@
+---
+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"]`.
+
+## 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.

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

@@ -0,0 +1,83 @@
+---
+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"]`.
+
+## 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.

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

@@ -0,0 +1,42 @@
+---
+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"]`.
+
+## 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/palettes.md

@@ -0,0 +1,144 @@
+---
+id: guide.palettes
+title: Color palettes
+summary: Use a built-in palette or extend one with your brand colors. The build
+  checks every palette against WCAG contrast.
+type: reference
+area: appearance
+subarea: appearance-themes
+canonical: /styling/palettes
+---
+
+# Color palettes
+
+> 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 > Color palettes
+
+**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.
+
+## Built-in palettes
+
+Choose a built-in palette as the starting point for your site colors.
+
+| Palette    | Colors                                                                     |
+| ---------- | -------------------------------------------------------------------------- |
+| `kelp`     | Sea green on white. The light set matches the base tokens in `tokens.css`. |
+| `coral`    | Coral accent over cool blue-gray neutrals.                                 |
+| `ink`      | Black ink on warm paper with a vermilion accent.                           |
+| `harbor`   | Navy ink, blue links, and a yellow callout rule.                           |
+| `amethyst` | Violet accents over lavender neutrals.                                     |
+| `vice`     | Flamingo pink and aqua by day, and neon on a night-purple sky after dark.  |
+
+```yaml title="docs.config.yaml"
+theme:
+  palette: amethyst
+```
+
+Each [preset](https://www.shoalrun.com/styling/themes.md) has a default palette, so you only need `palette` to change it.
+
+## Add brand colors
+
+Extend a built-in palette and override only the tokens you need. Write token names without the `--color-` prefix:
+
+```yaml title="docs.config.yaml"
+theme:
+  palette:
+    extends: harbor
+    light:
+      accent: "#0a6a48"
+      link: "#0a6a48"
+      emphasis: "#0a6a48"
+    dark:
+      accent: "#4fd6a4"
+      accent-contrast: "#06231a"
+      link: "#7fe0bd"
+```
+
+`extends` defaults to the preset's palette. `light` and `dark` are both optional. Values must be three- or six-digit hex colors such as `"#0a6a48"`. Quote them, because YAML treats `#` as the start of a comment.
+
+To keep the colors in their own files, include each mode's token map and keep `extends` in the main config:
+
+```yaml title="docs.config.yaml"
+theme:
+  palette:
+    extends: harbor
+    light: { $include: ./styles/brand-light.yaml }
+    dark: { $include: ./styles/brand-dark.yaml }
+```
+
+```yaml title="styles/brand-light.yaml"
+accent: "#0a6a48"
+link: "#0a6a48"
+```
+
+Don't include a file that sets `extends` at its top level. The config loader reads a top-level `extends` in any config file as a list of [config presets](https://www.shoalrun.com/config.md), so `extends: harbor` there fails the build.
+
+Most brands need four tokens or fewer:
+
+| Token                   | Controls                                                         |
+| ----------------------- | ---------------------------------------------------------------- |
+| `accent`                | Brand mark, primary header button, and active navigation marker. |
+| `accent-contrast`       | Text on `accent`, such as the primary button label.              |
+| `link` and `link-hover` | Links at rest and on hover.                                      |
+| `emphasis`              | Eyebrows, card icons, and search highlights.                     |
+
+The [CSS and theme reference](https://www.shoalrun.com/author/css.md) lists every token.
+
+## Contrast checks
+
+The build checks each palette against WCAG 2.2 before it writes any files. It checks the light set, the dark set, or both, depending on the [mode](https://www.shoalrun.com/styling/color-modes.md). If a pair fails, the build stops and names it:
+
+```text
+Theme colors fail WCAG 2.2 contrast:
+  - light: link #9fe6cc on page #ffffff is 1.40:1; needs 4.5:1
+```
+
+Success criterion 1.4.3 requires 4.5:1 for text against its background.
+
+Success criterion 1.4.11 requires 3:1 for focus rings, form field borders, and the accent fill against the page.
+
+The build checks these pairs:
+
+- Body text, muted text, links, headings, navigation text, and summaries on the page, surface, and field backgrounds.
+- Hovered links, callout text, and inline code on their backgrounds.
+- Body text, links, and labels in each callout type: note, tip, important, warning, and caution.
+- Body text, links, and labels on each custom callout tone from `callouts.tones`.
+- Active navigation, subject lifecycle badges, and required and optional field badges.
+- Code text and code labels on code blocks.
+- `accent-contrast` on `accent`, and `strong-text` on `strong-surface`.
+- `focus`, `field-border`, and `accent` against the page and surface.
+
+Every built-in palette passes in both modes. The framework tests check them on every change.
+
+### Check colors in CI
+
+`shoalrun config validate` runs the same check without building the site. It prints the same messages and exits with status 1 when a pair fails, so a CI step can stop a change before it merges:
+
+```bash
+shoalrun config validate docs.config.yaml
+```
+
+On success, its JSON output includes `"contrast": { "status": "ok", "palette": "kelp", "modes": ["light"] }`.
+
+[`shoalrun audit`](https://www.shoalrun.com/publish/audit.md) also fails on a contrast problem, because it builds the site.
+
+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
+
+- [Themes](https://www.shoalrun.com/styling/themes.md) — Pick the preset that the palette colors.
+
+### Related topics
+
+- [Light and dark mode](https://www.shoalrun.com/styling/color-modes.md) — A palette has one color set for light mode and one for dark mode.

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

@@ -0,0 +1,109 @@
+---
+id: guide.share-images
+title: Share images and favicon
+summary: Generated social images, metadata precedence, SVG placeholders, fonts,
+  and favicon settings.
+type: reference
+area: appearance
+subarea: appearance-branding
+canonical: /styling/share-images
+---
+
+# Share images and favicon
+
+> 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 > Share images and favicon
+
+**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.
+
+For the author workflow around page titles, summaries, public URLs, and social metadata, start with [SEO and social previews](https://www.shoalrun.com/publish/seo.md).
+
+## What the build writes
+
+- A 1200×630 PNG per page at `/assets/share/<page path>.png`, such as `/assets/share/styling/themes.png`. It shows the page type, title, and summary, the site title, and the page URL.
+- `og:title`, `og:description`, and `og:image` tags, plus explicit `twitter:title`, `twitter:description`, `twitter:image`, and `twitter:card` tags. The description uses the same page text as the image.
+- `/favicon.svg`, drawn from the preset's brand mark in the accent color, and a 180×180 `/apple-touch-icon.png`.
+
+Set `site.origin` to the public site address so image and page URLs in the tags are absolute and publicly reachable. A browser can load a page even when a link-preview crawler cannot fetch an image hosted at a different or private address. Run the [deployment checker](https://www.shoalrun.com/publish/deployment-check.md) against the public origin to catch a mismatched `og:image` or a missing image.
+
+```yaml title="docs.config.yaml"
+site:
+  title: Acme API docs
+  origin: https://docs.acme.com
+```
+
+The preview description comes from the page's `displayText.socialCard`, `seo.description`, configured HTML description, or `summary`, in that order. The same text appears in `og:description` and on the generated image. Long titles wrap to three lines and long summaries to two, ending in an ellipsis.
+
+For a short page title such as **Getting started**, the social title adds the site name when the result fits within 70 characters. The page heading and browser title stay as authored. Set `seo.title` on a page when you want to choose its exact social title instead.
+
+The build caches rendered images in `.shoalrun/cache/share-images/` beside the config file and redraws only pages whose card changed. Add `.shoalrun/` to `.gitignore`.
+
+## Use your own image for a page
+
+Set `image` in frontmatter to a local `.png` or `.jpg`, relative to the page file. It replaces the generated card for that page. 1200×630 works best.
+
+```yaml title="Frontmatter"
+image: ./images/launch.png
+```
+
+## Replace the design
+
+Point `outputs.html.shareImages.template` at a 1200×630 SVG file. The build fills these placeholders on each page:
+
+| Placeholder                                 | Value                                                       |
+| ------------------------------------------- | ----------------------------------------------------------- |
+| `{{title}}`, `{{summary}}`                  | The full title and summary.                                 |
+| `{{title.1}}`, `{{title.2}}`, `{{title.3}}` | The title split into lines of about 30 characters.          |
+| `{{summary.1}}`, `{{summary.2}}`            | The summary split into lines of about 60 characters.        |
+| `{{site}}`                                  | `site.title`.                                               |
+| `{{type}}`                                  | The page type as words, such as `API reference`.            |
+| `{{url}}`                                   | The page URL without `https://`, when `site.origin` is set. |
+
+```yaml title="docs.config.yaml"
+outputs:
+  html:
+    shareImages:
+      template: ./share/card.svg
+      fonts: [./share/AcmeSans-Bold.ttf]
+```
+
+```xml title="share/card.svg"
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630">
+  <rect width="1200" height="630" fill="#0b3d2e"/>
+  <text x="80" y="220" font-family="Acme Sans" font-weight="700" font-size="64" fill="#ffffff">{{title.1}}</text>
+  <text x="80" y="296" font-family="Acme Sans" font-weight="700" font-size="64" fill="#ffffff">{{title.2}}</text>
+  <text x="80" y="560" font-family="Inter" font-size="26" fill="#cfe8dd">{{site}}</text>
+</svg>
+```
+
+- An unknown placeholder fails the build, so a typo can't publish raw braces.
+- The renderer doesn't load system fonts. It can use Inter, Figtree, Source Serif 4, JetBrains Mono, and Jost, plus any `.ttf` or `.otf` files listed in `fonts` or in [`theme.fonts`](https://www.shoalrun.com/styling/themes.md).
+- The renderer reads TrueType and OpenType files only. WOFF2 files from `theme.fonts` still work on the site, but not in share images.
+
+To turn generated images off, set `shareImages: false`. Pages with their own `image` keep it.
+
+## Replace the favicon
+
+Set `site.favicon` to a local `.svg` or `.png`. An SVG favicon also becomes the touch icon, placed on the palette's inked surface. A PNG favicon is used as is, with no separate touch icon.
+
+```yaml title="docs.config.yaml"
+site:
+  favicon: ./brand/mark.svg
+```
+
+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
+
+- [Themes](https://www.shoalrun.com/styling/themes.md) — Set the theme that generated share images and the favicon take their look from.