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

package/agent-docs/config/outputs.sections/related-reading.md

@@ -0,0 +1,34 @@
+---
+id: reference.config-outputs
+title: Output and export settings
+summary: Configure metadata providers, application exports, Markdown headers,
+  and discovery indexes.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/outputs
+---
+
+# Output and export settings
+
+> 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) > Reference > Configuration reference > Output and export
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/config/outputs.md)
+
+Configure metadata providers, application exports, Markdown headers, and discovery indexes. These keys belong in `docs.config.yaml` or an included configuration file. For file composition and validation commands, see [Configure your project](https://www.shoalrun.com/configuration.md). Use the [configuration index](https://www.shoalrun.com/config.md) to find another setting.
+
+## Related reading
+
+### Read first
+
+- [Organize project configuration](https://www.shoalrun.com/configuration.md) — Learn how files combine and how to validate configuration changes.
+
+### Reference while working
+
+- [Configuration reference](https://www.shoalrun.com/config.md) — Find configuration settings in another topic.

package/agent-docs/config/publishing.md

@@ -0,0 +1,219 @@
+---
+id: reference.config-publishing
+title: Publications and routing settings
+summary: Configure versions, languages, navigation, and redirects.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/publishing
+---
+
+# Publications and routing settings
+
+> 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) > Reference > Configuration reference > Publications and routing
+
+**Updated: 2026-10-27.**
+
+Configure versions, languages, navigation, and redirects. These keys belong in `docs.config.yaml` or an included configuration file. For file composition and validation commands, see [Configure your project](https://www.shoalrun.com/configuration.md). Use the [configuration index](https://www.shoalrun.com/config.md) to find another setting.
+
+## `publications`
+
+Required. Declares which channel, version, and language combinations to build. See [how Shoalrun works](https://www.shoalrun.com/concepts.md) for the concepts.
+
+These settings select page variants within a build. For separate branches and domains, see [use Git branches for separate docs sites](https://www.shoalrun.com/publish/revisions.md).
+
+| Key                                    | Meaning                                                                                                                                                                                                                                               |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`                              | At least one `{ channel, version, language }` entry. `language` is optional and defaults to the default language.                                                                                                                                     |
+| `channels.<name>.pathPrefix`           | Route prefix for a channel. Every channel used in `enabled` must be declared, even with `pathPrefix: ""`.                                                                                                                                             |
+| `versions.<name>.pathPrefix`           | Route prefix for a version. Same rule as channels.                                                                                                                                                                                                    |
+| `defaults.channel`, `defaults.version` | The publication that uses each API's top-level `source`, and the defaults for `scaffold` and `api select`. Required when the project has `apis`.                                                                                                      |
+| `defaults.language`                    | The default language, which gets no route prefix. Global frontmatter can override it. Falls back to `en`.                                                                                                                                             |
+| `externalSites`                        | Optional links in the Version menu. Each entry needs a `label` and HTTP(S) `baseUrl`, which links to that site's root. Add a local `manifest` file containing its built `documents.json` to link only matching document IDs at their published paths. |
+
+For a page in several enabled combinations, set its frontmatter `publications` to a list of `{ channel, version }` pairs. This is separate from `apis.<name>.publications`, which binds API source files. A page without a list uses its resolved single channel and version. A list may include a declared but disabled combination; that copy is omitted from the build. See [share pages across documentation versions](https://www.shoalrun.com/publish/publications.md) for an example with version-specific sections.
+
+A single publication with no prefixes. Pages set `channel: production` and `version: current`:
+
+```yaml title="docs.config.yaml"
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+```
+
+Two API versions side by side. A v1 page at `/guides/start` is published at `/v1/guides/start`:
+
+```yaml title="docs.config.yaml"
+publications:
+  defaults: { channel: production, version: v2 }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    v1: { pathPrefix: /v1 }
+    v2: { pathPrefix: /v2 }
+  enabled:
+    - { channel: production, version: v1 }
+    - { channel: production, version: v2 }
+```
+
+A sandbox channel, with a version that is declared but not yet built. Leave a combination out of `enabled` to stop publishing it without deleting its pages:
+
+```yaml title="docs.config.yaml"
+publications:
+  defaults: { channel: production, version: v1 }
+  channels:
+    production: { pathPrefix: "" }
+    sandbox: { pathPrefix: /sandbox }
+  versions:
+    v1: { pathPrefix: "" }
+    v2: { pathPrefix: /v2 }
+  enabled:
+    - { channel: production, version: v1 }
+    - { channel: sandbox, version: v1 }
+```
+
+English at the root and German under `/de`. Pages without a `language` are English:
+
+```yaml title="docs.config.yaml"
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+    - { channel: production, version: current, language: de }
+```
+
+## `navigation`
+
+A list of sidebar nodes. Each node has a unique `id` and exactly one of `doc`, `operation`, `generated`, or `items`. Unknown node keys fail. See [navigation](https://www.shoalrun.com/author/navigation.md).
+
+| Key         | Meaning                                                                                                                                       |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`        | Unique node ID. Required.                                                                                                                     |
+| `doc`       | A page ID.                                                                                                                                    |
+| `operation` | A stable operation ID; shows that operation's reference page.                                                                                 |
+| `items`     | Child nodes, optionally loaded from another YAML list with `$include`; makes the node a group. Groups need a `label`.                         |
+| `label`     | Menu text. Defaults to the page title for `doc` and `operation` nodes.                                                                        |
+| `search`    | Extra words for the sidebar navigation filter, separate from site-wide search. Allowed on page and operation nodes, not groups or generators. |
+| `api`       | Limits a group or generator to one API. Children inherit it.                                                                                  |
+| `tab`       | Set `true` on a top-level group to give it a navigation tab and sidebar. Requires `landing`; nested tabs are rejected.                        |
+| `landing`   | Stable ID of a page inside the tab's items. The tab links to that page in each publication.                                                   |
+| `tag`       | An OpenAPI tag for a group that uses `generated: remaining`.                                                                                  |
+| `generated` | `tags` or `remaining`. Adds generated reference pages.                                                                                        |
+
+Pages and groups:
+
+```yaml title="config/nav.yaml"
+- id: start
+  doc: guide.overview
+- id: guides
+  label: Guides
+  items:
+    - id: first-payment
+      doc: guide.create-payment
+      label: Your first payment
+      search: checkout charge
+    - id: errors
+      doc: guide.handle-errors
+```
+
+Mix authored pages, a pinned API operation, and generated reference pages grouped by OpenAPI tag:
+
+```yaml title="config/nav.yaml"
+- id: payments
+  label: Payments API
+  api: payments
+  items:
+    - id: payment-guide
+      doc: guide.create-payment
+    - id: create-payment
+      operation: payments.create
+    - id: other-payment-pages
+      generated: tags
+```
+
+Fill one hand-made group with the remaining operations for a tag:
+
+```yaml title="config/nav.yaml"
+- id: reports
+  label: Reports
+  api: payments
+  tag: Reports
+  items:
+    - id: report-guide
+      doc: guide.reports
+    - id: report-operations
+      generated: remaining
+```
+
+## `redirects`
+
+A list of old URLs to send to a current page. Shoalrun's own docs use redirects to preserve links when changelog entries are combined.
+
+Add a redirect when a URL that readers, bookmarks, or other sites already use would stop working:
+
+- You change a page's `slug`. The slug sets the URL, so the old path no longer has a page.
+- You change `site.basePath`, a channel or version `pathPrefix`, or a language prefix. Every route under it moves.
+- You delete a page, merge two pages, or replace a page with one in another version.
+
+You don't need a redirect when a page keeps its `slug`. Moving or renaming the source file doesn't change a URL, and neither does changing navigation. The URL comes from the slug, not the file.
+
+List the redirects under `redirects` in `docs.config.yaml`, or keep them in a file and include it:
+
+```yaml title="docs.config.yaml"
+redirects: { $include: ./config/redirects.yaml }
+```
+
+The [versioned API documentation](https://www.shoalrun.com/config/examples.md) example shows a complete config with a redirect. Each entry looks like this:
+
+```yaml title="config/redirects.yaml"
+- from: /guides/old-payment
+  to: { doc: guide.create-payment, channel: production, version: current, language: en }
+```
+
+Use a different status, such as 301 for clients that don't support 308:
+
+```yaml title="config/redirects.yaml"
+- from: /getting-started
+  to: { doc: guide.overview, channel: production, version: current, language: en }
+  status: 301
+```
+
+Send an old URL to a page in another publication, such as a retired v1 page to its v2 version:
+
+```yaml title="config/redirects.yaml"
+- from: /v1/guides/webhooks
+  to: { doc: guide.webhooks, channel: production, version: v2, language: en }
+```
+
+Because the target is a page ID, the redirect follows the page when its slug changes. Nothing else needs updating.
+
+| Key      | Meaning                                                                                                                   |
+| -------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `from`   | Old path, starting with `/`. Compared without regard to case; a duplicate or a path that belongs to a current page fails. |
+| `to`     | Target page ID and its full publication: `doc`, `channel`, `version`, and `language` are all required.                    |
+| `status` | HTTP status: `301`, `302`, `303`, `307`, or `308`. Defaults to `308`.                                                     |
+
+The build resolves each target to its current route and writes `redirects.json`. `shoalrun serve` and the Vercel build apply the redirects, with or without a trailing slash. The old page's `.md` URL redirects to the target's Markdown twin with the same status.
+
+## Related reading
+
+### Read first
+
+- [Organize project configuration](https://www.shoalrun.com/configuration.md) — Learn how files combine and how to validate configuration changes.
+
+### Reference while working
+
+- [Configuration reference](https://www.shoalrun.com/config.md) — Find configuration settings in another topic.

package/agent-docs/config/publishing.sections/navigation.md

@@ -0,0 +1,92 @@
+---
+id: reference.config-publishing
+title: Publications and routing settings
+summary: Configure versions, languages, navigation, and redirects.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/publishing
+---
+
+# Publications and routing settings
+
+> 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) > Reference > Configuration reference > Publications and routing
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/config/publishing.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Organize project configuration](https://www.shoalrun.com/configuration.md) — Learn how files combine and how to validate configuration changes.
+
+Configure versions, languages, navigation, and redirects. These keys belong in `docs.config.yaml` or an included configuration file. For file composition and validation commands, see [Configure your project](https://www.shoalrun.com/configuration.md). Use the [configuration index](https://www.shoalrun.com/config.md) to find another setting.
+
+## `navigation`
+
+A list of sidebar nodes. Each node has a unique `id` and exactly one of `doc`, `operation`, `generated`, or `items`. Unknown node keys fail. See [navigation](https://www.shoalrun.com/author/navigation.md).
+
+| Key         | Meaning                                                                                                                                       |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`        | Unique node ID. Required.                                                                                                                     |
+| `doc`       | A page ID.                                                                                                                                    |
+| `operation` | A stable operation ID; shows that operation's reference page.                                                                                 |
+| `items`     | Child nodes, optionally loaded from another YAML list with `$include`; makes the node a group. Groups need a `label`.                         |
+| `label`     | Menu text. Defaults to the page title for `doc` and `operation` nodes.                                                                        |
+| `search`    | Extra words for the sidebar navigation filter, separate from site-wide search. Allowed on page and operation nodes, not groups or generators. |
+| `api`       | Limits a group or generator to one API. Children inherit it.                                                                                  |
+| `tab`       | Set `true` on a top-level group to give it a navigation tab and sidebar. Requires `landing`; nested tabs are rejected.                        |
+| `landing`   | Stable ID of a page inside the tab's items. The tab links to that page in each publication.                                                   |
+| `tag`       | An OpenAPI tag for a group that uses `generated: remaining`.                                                                                  |
+| `generated` | `tags` or `remaining`. Adds generated reference pages.                                                                                        |
+
+Pages and groups:
+
+```yaml title="config/nav.yaml"
+- id: start
+  doc: guide.overview
+- id: guides
+  label: Guides
+  items:
+    - id: first-payment
+      doc: guide.create-payment
+      label: Your first payment
+      search: checkout charge
+    - id: errors
+      doc: guide.handle-errors
+```
+
+Mix authored pages, a pinned API operation, and generated reference pages grouped by OpenAPI tag:
+
+```yaml title="config/nav.yaml"
+- id: payments
+  label: Payments API
+  api: payments
+  items:
+    - id: payment-guide
+      doc: guide.create-payment
+    - id: create-payment
+      operation: payments.create
+    - id: other-payment-pages
+      generated: tags
+```
+
+Fill one hand-made group with the remaining operations for a tag:
+
+```yaml title="config/nav.yaml"
+- id: reports
+  label: Reports
+  api: payments
+  tag: Reports
+  items:
+    - id: report-guide
+      doc: guide.reports
+    - id: report-operations
+      generated: remaining
+```

package/agent-docs/config/publishing.sections/redirects.md

@@ -0,0 +1,79 @@
+---
+id: reference.config-publishing
+title: Publications and routing settings
+summary: Configure versions, languages, navigation, and redirects.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/publishing
+---
+
+# Publications and routing settings
+
+> 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) > Reference > Configuration reference > Publications and routing
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/config/publishing.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Organize project configuration](https://www.shoalrun.com/configuration.md) — Learn how files combine and how to validate configuration changes.
+
+Configure versions, languages, navigation, and redirects. These keys belong in `docs.config.yaml` or an included configuration file. For file composition and validation commands, see [Configure your project](https://www.shoalrun.com/configuration.md). Use the [configuration index](https://www.shoalrun.com/config.md) to find another setting.
+
+## `redirects`
+
+A list of old URLs to send to a current page. Shoalrun's own docs use redirects to preserve links when changelog entries are combined.
+
+Add a redirect when a URL that readers, bookmarks, or other sites already use would stop working:
+
+- You change a page's `slug`. The slug sets the URL, so the old path no longer has a page.
+- You change `site.basePath`, a channel or version `pathPrefix`, or a language prefix. Every route under it moves.
+- You delete a page, merge two pages, or replace a page with one in another version.
+
+You don't need a redirect when a page keeps its `slug`. Moving or renaming the source file doesn't change a URL, and neither does changing navigation. The URL comes from the slug, not the file.
+
+List the redirects under `redirects` in `docs.config.yaml`, or keep them in a file and include it:
+
+```yaml title="docs.config.yaml"
+redirects: { $include: ./config/redirects.yaml }
+```
+
+The [versioned API documentation](https://www.shoalrun.com/config/examples.md) example shows a complete config with a redirect. Each entry looks like this:
+
+```yaml title="config/redirects.yaml"
+- from: /guides/old-payment
+  to: { doc: guide.create-payment, channel: production, version: current, language: en }
+```
+
+Use a different status, such as 301 for clients that don't support 308:
+
+```yaml title="config/redirects.yaml"
+- from: /getting-started
+  to: { doc: guide.overview, channel: production, version: current, language: en }
+  status: 301
+```
+
+Send an old URL to a page in another publication, such as a retired v1 page to its v2 version:
+
+```yaml title="config/redirects.yaml"
+- from: /v1/guides/webhooks
+  to: { doc: guide.webhooks, channel: production, version: v2, language: en }
+```
+
+Because the target is a page ID, the redirect follows the page when its slug changes. Nothing else needs updating.
+
+| Key      | Meaning                                                                                                                   |
+| -------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `from`   | Old path, starting with `/`. Compared without regard to case; a duplicate or a path that belongs to a current page fails. |
+| `to`     | Target page ID and its full publication: `doc`, `channel`, `version`, and `language` are all required.                    |
+| `status` | HTTP status: `301`, `302`, `303`, `307`, or `308`. Defaults to `308`.                                                     |
+
+The build resolves each target to its current route and writes `redirects.json`. `shoalrun serve` and the Vercel build apply the redirects, with or without a trailing slash. The old page's `.md` URL redirects to the target's Markdown twin with the same status.

package/agent-docs/config/publishing.sections/related-reading.md

@@ -0,0 +1,33 @@
+---
+id: reference.config-publishing
+title: Publications and routing settings
+summary: Configure versions, languages, navigation, and redirects.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/publishing
+---
+
+# Publications and routing settings
+
+> 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) > Reference > Configuration reference > Publications and routing
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/config/publishing.md)
+
+Configure versions, languages, navigation, and redirects. These keys belong in `docs.config.yaml` or an included configuration file. For file composition and validation commands, see [Configure your project](https://www.shoalrun.com/configuration.md). Use the [configuration index](https://www.shoalrun.com/config.md) to find another setting.
+
+## Related reading
+
+### Read first
+
+- [Organize project configuration](https://www.shoalrun.com/configuration.md) — Learn how files combine and how to validate configuration changes.
+
+### Reference while working
+
+- [Configuration reference](https://www.shoalrun.com/config.md) — Find configuration settings in another topic.

package/agent-docs/config/site.md

@@ -0,0 +1,193 @@
+---
+id: reference.config-site
+title: Site and theme settings
+summary: Configure the site identity, header, footer, agent guidance, colors, and fonts.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/site
+---
+
+# Site and theme settings
+
+> 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) > Reference > Configuration reference > Site and theme
+
+**Updated: 2026-10-27.**
+
+Configure the site identity, header, footer, agent guidance, colors, and fonts. These keys belong in `docs.config.yaml` or an included configuration file. For file composition and validation commands, see [Configure your project](https://www.shoalrun.com/configuration.md). Use the [configuration index](https://www.shoalrun.com/config.md) to find another setting.
+
+## `site`
+
+Required.
+
+| Key              | Default                                  | Meaning                                                                                                                                                                                                                                                                                                                              |
+| ---------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `title`          | None                                     | Site name in the masthead and the heading of `/llms.txt`.                                                                                                                                                                                                                                                                            |
+| `contentDir`     | `content`                                | Page directory, relative to the root config file. Every `.md` and `.mdx` file in it is read.                                                                                                                                                                                                                                         |
+| `contentFilter`  | None                                     | Build-time whole-page selection by configured reader facets. All selected facets must match; any listed choice within a facet matches. Unmarked pages are excluded. Unknown or empty selectors and selections with no pages fail. See [separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md). |
+| `basePath`       | `""`                                     | Mount point for public pages and resources, such as `/docs`. Use URL path segments without escapes or dot segments. Build tools keep internal manifests at the output root; the public site is also complete inside the `docs/` output subtree.                                                                                      |
+| `origin`         | None                                     | The site's HTTPS origin, such as `https://docs.example.com`, with no path or trailing slash. Required to publish the API catalog, and makes link-preview URLs absolute.                                                                                                                                                              |
+| `indexing`       | `true`                                   | Set `false` on previews to add noindex to pages, disallow crawling in `robots.txt`, and omit the XML sitemap.                                                                                                                                                                                                                        |
+| `updated`        | None                                     | Optional YYYY-MM-DD fallback for sitemap `lastmod`, especially on generated API pages. Page `updated` overrides it.                                                                                                                                                                                                                  |
+| `favicon`        | A mark drawn from the preset and palette | A local `.svg` or `.png` file. See [share images and favicon](https://www.shoalrun.com/styling/share-images.md).                                                                                                                                                                                                                     |
+| `customCss`      | None                                     | A local `.css` file linked after the framework styles. See [CSS](https://www.shoalrun.com/author/css.md).                                                                                                                                                                                                                            |
+| `editionBadge`   | `auto`                                   | Masthead publication label: `auto` shows only the channel, version, or language values that differ across publications; `always` or `never`.                                                                                                                                                                                         |
+| `header.links`   | None                                     | Masthead links. See [header](https://www.shoalrun.com/styling/header.md).                                                                                                                                                                                                                                                            |
+| `agentDiscovery` | Visually hidden until focused            | HTML agent guidance, visual presentation, and link labels. See `site.agentDiscovery` below.                                                                                                                                                                                                                                          |
+| `footer`         | None                                     | Footer `columns`, bottom-row `links`, and a `text` line. See [site footer](https://www.shoalrun.com/styling/footer.md).                                                                                                                                                                                                              |
+
+A minimal site needs only a title:
+
+```yaml title="docs.config.yaml"
+site:
+  title: Payments documentation
+```
+
+Keep pages in another directory, add a stylesheet, and always show the publication label:
+
+```yaml title="docs.config.yaml"
+site:
+  title: Payments documentation
+  contentDir: pages
+  customCss: ./styles/project.css
+  editionBadge: always
+```
+
+Publish the API catalog. `origin` is required once any API sets `discovery.endpoint`:
+
+```yaml title="docs.config.yaml"
+site:
+  title: Payments documentation
+  origin: https://docs.example.com
+```
+
+Add masthead links:
+
+```yaml title="docs.config.yaml"
+site:
+  title: Payments documentation
+  header:
+    links:
+      - { label: Guides, href: /start }
+      - { label: GitHub, href: "https://github.com/example/payments", style: button }
+      - { label: Sign up, href: "https://example.com/signup", style: primary }
+```
+
+Add a footer:
+
+```yaml title="docs.config.yaml"
+site:
+  title: Payments documentation
+  footer:
+    columns:
+      - title: Guides
+        links:
+          - { label: Get started, href: /start }
+    links:
+      - { label: Privacy, href: /legal/privacy }
+    text: © 2026 Example, Inc.
+```
+
+### `site.agentDiscovery`
+
+Optional mapping. It controls the early agent guidance in HTML pages.
+
+| Key              | Default                      | Meaning                                                                                                  |
+| ---------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `mode`           | `focus`                      | Controls visual presentation and whether the block is included. See the visual and agent behavior below. |
+| `label`          | `For agents`                 | Nonempty plain text before the message and links. Shoalrun adds the colon.                               |
+| `message`        | None                         | Optional plain-text guidance. HTML tags are escaped; Markdown syntax stays literal.                      |
+| `links.article`  | `Skip to article`            | Label for the generated `#main` link.                                                                    |
+| `links.index`    | `Documentation index`        | Label for the generated `/llms.txt` link, including `site.basePath`.                                     |
+| `links.markdown` | `Read this page as Markdown` | Label for the current page's Markdown twin.                                                              |
+
+```yaml title="docs.config.yaml"
+site:
+  title: Payments documentation
+  agentDiscovery:
+    mode: visible
+    label: For agents
+    message: Use the Markdown version for complete examples and nested schemas.
+    links:
+      article: Jump to the article
+      index: Browse all documentation
+      markdown: Read Markdown
+```
+
+Only link labels are configurable; Shoalrun generates their destinations for each page. Labels must be nonempty strings. Unknown keys and invalid mode values fail validation and builds.
+
+The mode controls visual presentation and whether the instruction is included:
+
+| Value        | Visual presentation                                   | Agent reading HTML                                          |
+| ------------ | ----------------------------------------------------- | ----------------------------------------------------------- |
+| `focus`      | Visually hidden until a link receives keyboard focus. | The instruction and links are present in the HTML.          |
+| `visible`    | Always shown as a banner.                             | The same instruction and links are present in the HTML.     |
+| `disclosure` | A compact header toggle, closed initially.            | Links remain in HTML source; open it for visual navigation. |
+| `off`        | No agent guidance block appears.                      | The instruction and its links are omitted from the HTML.    |
+
+Screen readers and agents parsing raw HTML can encounter the block in all enabled modes. An agent using screenshots sees the same visual presentation as a human. Some HTML extraction tools discard visually hidden elements; the document head also provides discovery links. Visually hiding the block does not make it private.
+
+This setting affects HTML only. It does not change the Markdown index link, generated discovery files, or the standard accessibility skip link. The focus and visible blocks follow that skip link before the header. Disclosure mode places the toggle inside the header. It is hidden in print.
+
+### Content freshness
+
+`site.freshness: { history: ./config/content-updates.json }` opts into persistent content-digest dates. Paths resolve from the root config directory and must stay inside the project. The first build seeds declared dates; changed content later receives today's UTC date while unchanged content retains its date. Commit the history file for reproducible clean builds. Without this setting, declared `updated` and `site.updated` remain authoritative. Native page `verified` is an independent, author-set calendar date. See [revision and verification dates](https://www.shoalrun.com/publish/seo.md).
+
+## `theme`
+
+Accepts `preset`, `palette`, `mode`, `toggle`, and `fonts`. See [themes](https://www.shoalrun.com/styling/themes.md), [palettes](https://www.shoalrun.com/styling/palettes.md), and [color modes](https://www.shoalrun.com/styling/color-modes.md). The build checks palette colors for WCAG contrast.
+
+| Key       | Default                                       | Values                                                                                                                       |
+| --------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `preset`  | `shoal`                                       | `shoal`, `reef`, `ledger`, `vice`                                                                                            |
+| `palette` | The preset's palette                          | `kelp`, `coral`, `ink`, `harbor`, `amethyst`, `vice`, or a custom mapping                                                    |
+| `mode`    | `light`                                       | `light`, `dark`, `system`                                                                                                    |
+| `toggle`  | `true` with `mode: system`, otherwise `false` | `true` or `false`. `true` is allowed only with `mode: system`.                                                               |
+| `fonts`   | The preset's bundled fonts                    | `system`, or a mapping of `body`, `headings`, and `code`. See Fonts in [themes](https://www.shoalrun.com/styling/themes.md). |
+
+Change the layout and keep its colors:
+
+```yaml title="docs.config.yaml"
+theme:
+  preset: ledger
+```
+
+Follow the reader's system setting and let them switch:
+
+```yaml title="docs.config.yaml"
+theme:
+  preset: reef
+  palette: harbor
+  mode: system
+```
+
+Use a built-in palette as a base and change the brand colors:
+
+```yaml title="docs.config.yaml"
+theme:
+  palette:
+    extends: harbor
+    light: { accent: "#0a6a48", link: "#0a6a48" }
+    dark: { accent: "#4fd6a4", link: "#7fe0bd" }
+```
+
+Use dark mode only, without a switch:
+
+```yaml title="docs.config.yaml"
+theme:
+  mode: dark
+```
+
+## Related reading
+
+### Read first
+
+- [Organize project configuration](https://www.shoalrun.com/configuration.md) — Learn how files combine and how to validate configuration changes.
+
+### Reference while working
+
+- [Configuration reference](https://www.shoalrun.com/config.md) — Find configuration settings in another topic.