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

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: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > 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.

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

@@ -0,0 +1,33 @@
+---
+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: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Site and theme
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/config/site.md)
+
+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.
+
+## 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.sections/theme.md

@@ -0,0 +1,74 @@
+---
+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: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Site and theme
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/config/site.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 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.
+
+## `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
+```

package/agent-docs/config.md

@@ -0,0 +1,195 @@
+---
+id: reference.config
+title: Configuration reference
+summary: Find configuration settings by topic and compose a project configuration.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config
+---
+
+# Configuration reference
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Overview
+
+**Updated: 2026-10-27.**
+
+A project's configuration starts at `docs.config.yaml`. The CLI looks for that name by default, and `shoalrun scaffold -n` searches parent directories for it. For a guided workflow, start with [Configure your project](https://www.shoalrun.com/configuration.md). For complete working projects, see [Example configs](https://www.shoalrun.com/config/examples.md).
+
+## Find a setting
+
+Each reference below contains the field definitions, defaults, validation rules, and examples for its topic.
+
+| Reference                                                                          | Configuration keys                                                                                                                    |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| [Site and theme settings](https://www.shoalrun.com/config/site.md)                 | `site`, `theme`                                                                                                                       |
+| [Publications and routing settings](https://www.shoalrun.com/config/publishing.md) | `publications`, `navigation`, `redirects`                                                                                             |
+| [Authoring and content settings](https://www.shoalrun.com/config/content.md)       | `authoring`, `frontmatter`, `variables`, `snippets`, `templates`, `callouts`, `badges`, `cookbooks`, `relationships`, `readerFilters` |
+| [API and audit settings](https://www.shoalrun.com/config/apis.md)                  | `apis`, `audit`                                                                                                                       |
+| [Search and integration settings](https://www.shoalrun.com/config/integrations.md) | `search`, `mcp`, `analytics`                                                                                                          |
+| [Output and export settings](https://www.shoalrun.com/config/outputs.md)           | `metadata`, `exports`, `outputs`                                                                                                      |
+
+## Start a configuration file
+
+The root file must be a YAML mapping with `schemaVersion: 1`. YAML is parsed strictly: duplicate keys fail. Unknown top-level keys fail with `unknown setting <key>`. See the focused references for validation rules within each setting.
+
+```yaml title="docs.config.yaml"
+schemaVersion: 1
+site:
+  title: Example documentation
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+navigation: { $include: ./config/nav.yaml }
+```
+
+## Split and combine config files
+
+These directives compose configuration values. Paths resolve relative to the file declaring them. For complete examples, merge order, and troubleshooting, follow [Configure your project](https://www.shoalrun.com/configuration.md).
+
+### `$include`
+
+`{ $include: ./path.yaml }` replaces a value at any depth with the contents of another YAML file. The mapping can have no other keys. Included files can include others; a cycle fails with `Configuration cycle` and the chain of files. Normal inheritance rules apply to the resolved value.
+
+### `extends`
+
+A top-level `extends: [./base.yaml]` layers one or more presets in order, followed by the current file. Mappings merge key by key; lists and scalar values replace earlier values. Presets may extend other presets. A top-level `extends` always names config files, including in an included file; it cannot serve another purpose there.
+
+### `$concat` and `$remove`
+
+`{ $concat: [...] }` appends items to an inherited list, or becomes the list when none is inherited. It also accepts included lists. `{ $remove: [name, ...] }` removes inherited mapping keys by name or list items by `id`; it fails when nothing is inherited.
+
+Run `shoalrun config explain <key> docs.config.yaml` to inspect a value's source and overrides. See the [CLI reference](https://www.shoalrun.com/cli.md) for other inspection commands.
+
+## Settings by key
+
+Use these links to jump directly to a setting in its focused reference.
+
+### `search`
+
+See [search settings](https://www.shoalrun.com/config/integrations.md#search).
+
+### `authoring`
+
+See [authoring settings](https://www.shoalrun.com/config/content.md#authoring).
+
+### `site`
+
+See [site settings](https://www.shoalrun.com/config/site.md#site).
+
+#### `site.agentDiscovery`
+
+See [site.agentDiscovery settings](https://www.shoalrun.com/config/site.md#site-agentdiscovery).
+
+#### Content freshness
+
+See [Content freshness settings](https://www.shoalrun.com/config/site.md#content-freshness).
+
+### `theme`
+
+See [theme settings](https://www.shoalrun.com/config/site.md#theme).
+
+### `publications`
+
+See [publications settings](https://www.shoalrun.com/config/publishing.md#publications).
+
+### `navigation`
+
+See [navigation settings](https://www.shoalrun.com/config/publishing.md#navigation).
+
+### `redirects`
+
+See [redirects settings](https://www.shoalrun.com/config/publishing.md#redirects).
+
+### `apis`
+
+See [apis settings](https://www.shoalrun.com/config/apis.md#apis).
+
+### `audit`
+
+See [audit settings](https://www.shoalrun.com/config/apis.md#audit).
+
+#### Agent evaluation reports
+
+See [Agent evaluation reports settings](https://www.shoalrun.com/config/apis.md#agent-evaluation-reports).
+
+### `cookbooks`
+
+See [cookbooks settings](https://www.shoalrun.com/config/content.md#cookbooks).
+
+### `relationships`
+
+See [relationships settings](https://www.shoalrun.com/config/content.md#relationships).
+
+### `variables`
+
+See [variables settings](https://www.shoalrun.com/config/content.md#variables).
+
+### `snippets`
+
+See [snippets settings](https://www.shoalrun.com/config/content.md#snippets).
+
+### `callouts`
+
+See [callouts settings](https://www.shoalrun.com/config/content.md#callouts).
+
+### `badges`
+
+See [badges settings](https://www.shoalrun.com/config/content.md#badges).
+
+### `templates`
+
+See [templates settings](https://www.shoalrun.com/config/content.md#templates).
+
+### `readerFilters`
+
+See [readerFilters settings](https://www.shoalrun.com/config/content.md#readerfilters).
+
+### `frontmatter`
+
+See [frontmatter settings](https://www.shoalrun.com/config/content.md#frontmatter).
+
+### `mcp`
+
+See [mcp settings](https://www.shoalrun.com/config/integrations.md#mcp).
+
+### `analytics`
+
+See [analytics settings](https://www.shoalrun.com/config/integrations.md#analytics).
+
+### `metadata`
+
+See [metadata settings](https://www.shoalrun.com/config/outputs.md#metadata).
+
+### `exports`
+
+See [exports settings](https://www.shoalrun.com/config/outputs.md#exports).
+
+### `outputs`
+
+See [outputs settings](https://www.shoalrun.com/config/outputs.md#outputs).
+
+#### Agent discovery index
+
+See [Agent discovery index settings](https://www.shoalrun.com/config/outputs.md#agent-discovery-index).
+
+## Related reading
+
+### Read first
+
+- [How Shoalrun works](https://www.shoalrun.com/concepts.md) — Understand publications, stable IDs, and config composition before changing settings.
+
+### Related topics
+
+- [CLI reference](https://www.shoalrun.com/cli.md) — Build, serve, and inspect a config from the command line.
+
+- [Example configs](https://www.shoalrun.com/config/examples.md) — The same settings, combined into complete, working files.