@shoalrun/cli 0.1.0-alpha.17 → 0.1.0-alpha.18

package/agent-docs/config/site.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Site and theme
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 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.
 
@@ -24,21 +24,22 @@ Configure the site identity, header, footer, agent guidance, colors, and fonts.
 
 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).                                                                                                                                                                                                              |
+| 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's 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`                                   | Legacy productless masthead label: `auto` shows only differing publication values; `always` or `never`. Product catalogs use the publication dropdown described below.                                                                                                                                                               |
+| `publicationSelector.showLanguage` | Automatic                                | Since 0.1.0-alpha.18 Show language labels in the product publication dropdown only when the rendered edition has multiple languages. A boolean forces display on or off.                                                                                                                                                             |
+| `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:
 
@@ -92,6 +93,29 @@ site:
     text: © 2026 Example, Inc.
 ```
 
+### Product publication dropdown
+
+Since 0.1.0-alpha.18
+
+A site with a [product catalog](https://www.shoalrun.com/publish/publications.md) replaces its edition badge with one native **Publication** dropdown. Options are grouped by the product’s configured label and include only releases that produced pages in the selected build. The selected label retains the product, channel, and version. Product versions remain independent; selecting Reporting v1 doesn't imply Payments v1 exists.
+
+The dropdown preserves the current stable page ID when that page exists in the destination publication. Otherwise it opens a published overview, chosen by shortest route with a deterministic tie-breaker. Customer profiles can't expose excluded products through this control. Productless projects keep the existing version menu and edition label behavior.
+
+Language labels appear automatically when the rendered edition contains multiple languages. Set a boolean to override that display:
+
+```yaml title="docs.config.yaml"
+site:
+  title: Product documentation
+  publicationSelector:
+    showLanguage: false
+```
+
+`showLanguage: true` always includes the language. `false` hides it even on multilingual sites. The language remains part of publication identity, routing, and search scope. A customer profile can override this same site setting without changing the shared catalog. Other keys in `publicationSelector`, and non-boolean values for `showLanguage`, are rejected.
+
+### HTML, Markdown, and agents
+
+The publication dropdown is an HTML control. It supports native keyboard selection; its change handler needs JavaScript to navigate. Without JavaScript, a list of ordinary publication links remains available. The header wraps on narrow screens. Markdown retains each published page and its scoped links, without the interactive dropdown. Agents use [MCP publication discovery](https://www.shoalrun.com/publish/mcp.md), publication metadata, or explicit CLI selectors to choose the product release before reading a repeated page ID. Hiding a language label doesn't merge those publications or change access to files.
+
 ### `site.agentDiscovery`
 
 Optional mapping. It controls the early agent guidance in HTML pages.
@@ -129,9 +153,9 @@ The mode controls visual presentation and whether the instruction is included:
 | `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.
+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 doesn't 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.
+This setting affects HTML only. It doesn't 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's hidden in print.
 
 ### Content freshness
 

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

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Site and theme
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/config/site.md)
 

package/agent-docs/config/site.sections/theme.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Site and theme
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/config/site.md)
 

package/agent-docs/config.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Overview
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 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).
 
@@ -62,7 +62,7 @@ These directives compose configuration values. Paths resolve relative to the fil
 
 ### `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.
+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 can't serve another purpose there.
 
 ### `$concat` and `$remove`
 

package/agent-docs/configuration.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 `docs.config.yaml` connects your content, presentation, and publication settings. Start with one file, then extract sections or share defaults when several projects need them. This guide explains how those choices interact and how to inspect the result.
 
@@ -31,7 +31,7 @@ Configuration takes effect in three stages:
 2. **Resolve pages.** Apply configured frontmatter defaults, the page's own metadata, and enforced metadata. Validate the resulting page fields.
 3. **Build publications.** Select public pages for enabled channel/version/language combinations, resolve links and APIs, then produce HTML, Markdown, and discovery files.
 
-A preset changes configuration. A page default changes metadata. An enabled publication selects an edition to build. These mechanisms have separate rules; changing one does not automatically create pages or translations.
+A preset changes configuration. A page default changes metadata. An enabled publication selects an edition to build. These mechanisms have separate rules; changing one doesn't automatically create pages or translations.
 
 ### Find the section you need
 
@@ -48,7 +48,7 @@ Start with the configuration sections that control the behavior you want to chan
 | Style the site and configure rendering         | `theme`, `outputs`                                  |
 | Configure reader views and project checks      | `readerFilters`, `audit`                            |
 
-Every entry config resolves to a YAML mapping with `schemaVersion: 1`. Duplicate YAML keys and unknown top-level settings fail. Nested settings are not all checked for unknown keys, so verify spelling against the reference.
+Every entry config resolves to a YAML mapping with `schemaVersion: 1`. Duplicate YAML keys and unknown top-level settings fail. Nested settings aren't all checked for unknown keys, so verify spelling against the reference.
 
 ## Start with one working file
 
@@ -59,7 +59,7 @@ CONFIG_DEMO="$(mktemp -d)"
 mkdir "$CONFIG_DEMO/site"
 cd "$CONFIG_DEMO/site"
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.11
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
 npx --no-install shoalrun init . --starter minimal
 ```
 
@@ -222,7 +222,7 @@ When a config extends another file, the overlay value determines how each inheri
 | Overlay value            | Result                                                                     |
 | ------------------------ | -------------------------------------------------------------------------- |
 | Mapping over a mapping   | Merge recursively by key. Unchanged keys survive.                          |
-| List                     | Replace the entire inherited list. Items do not merge by ID.               |
+| List                     | Replace the entire inherited list. Items don't merge by ID.                |
 | Scalar, including `null` | Replace the inherited value. The receiving setting must accept that value. |
 | `$concat`                | Append to an inherited list, or create a list if none exists.              |
 | `$remove`                | Remove inherited mapping keys or list entries by `id`.                     |
@@ -231,7 +231,7 @@ This also applies after resolving an include. An included mapping can merge with
 
 To layer a second preset, use `extends: [../shared/base.yaml, ../shared/brand.yaml]`. Only settings in `brand.yaml` override the base; the project's local settings still win.
 
-`extends` is recognized at the top level of each loaded YAML file, including files loaded through `$include`. Avoid using a top-level `extends` key as unrelated data in a fragment. An `extends` nested inside an ordinary mapping is not an inheritance instruction.
+`extends` is recognized at the top level of each loaded YAML file, including files loaded through `$include`. Avoid using a top-level `extends` key as unrelated data in a fragment. An `extends` nested inside an ordinary mapping isn't an inheritance instruction.
 
 ## Change inherited lists deliberately
 
@@ -262,7 +262,7 @@ npx --no-install shoalrun build docs.config.yaml dist
 
 ### Know the directive limits
 
-`$concat` expects a list base when an inherited value exists. It does not append to a mapping. Included lists within `$concat` are flattened one level, so several team navigation fragments can become one list:
+`$concat` expects a list base when an inherited value exists. It doesn't append to a mapping. Included lists within `$concat` are flattened one level, so several team navigation fragments can become one list:
 
 ```yaml
 navigation:
@@ -271,11 +271,11 @@ navigation:
     - { $include: ./config/nav-api.yaml }
 ```
 
-That fragment requires both named files. Each should contain a navigation list. Concatenation preserves order and does not remove duplicates; duplicate navigation IDs still fail during a build.
+That fragment requires both named files. Each should contain a navigation list. Concatenation preserves order and doesn't remove duplicates; duplicate navigation IDs still fail during a build.
 
-`$remove` requires an inherited value. For mappings, its strings name keys. For lists, they match each item's `id`; it does not remove scalar strings or match another field such as `label`. Removing a missing name has no effect. Removing an item does not automatically repair links or other settings that referred to it.
+`$remove` requires an inherited value. For mappings, its strings name keys. For lists, they match each item's `id`; it doesn't remove scalar strings or match another field such as `label`. Removing a missing name has no effect. Removing an item doesn't automatically repair links or other settings that referred to it.
 
-Each directive mapping must contain exactly one directive and no other keys. You cannot combine `$remove` and `$concat` at the same location in one overlay. Use separate preset layers when you need both operations.
+Each directive mapping must contain exactly one directive and no other keys. You can't combine `$remove` and `$concat` at the same location in one overlay. Use separate preset layers when you need both operations.
 
 ## Understand where paths point
 
@@ -292,7 +292,7 @@ Resolution records a source file for every configuration value. Relative paths o
 
 In the running example, `site.customCss: ./brand.css` still finds `shared/brand.css` after the project overrides `site.title`. The two keys keep separate origins.
 
-Moving a path into `config/api.yaml` may require changing `./apis/service.yaml` to `../apis/service.yaml`. Inspect the exact path key with `config explain` after moving it. `config resolve` retains relative strings; it does not rewrite every file path into an absolute path.
+Moving a path into `config/api.yaml` may require changing `./apis/service.yaml` to `../apis/service.yaml`. Inspect the exact path key with `config explain` after moving it. `config resolve` retains relative strings; it doesn't rewrite every file path into an absolute path.
 
 Some grouped settings use the origin of their containing block: custom search uses `outputs.html.search`, fonts use `theme.fonts`, and share images use `outputs.html.shareImages`. Overriding part of such a block can change its path base. Keep a block's relative paths and related overrides together, and inspect that block's source when debugging.
 
@@ -306,19 +306,19 @@ The loader first combines all configured `frontmatter` sections using the config
 frontmatter.defaults → page frontmatter → frontmatter.enforced
 ```
 
-Mappings merge recursively and lists replace at this stage too. Config directives such as `$include`, `$concat`, and `$remove` are not page-frontmatter inheritance instructions.
+Mappings merge recursively and lists replace at this stage too. Config directives such as `$include`, `$concat`, and `$remove` aren't page-frontmatter inheritance instructions.
 
 For example, `frontmatter.defaults.access.policy: public` lets a page set itself to `draft`. Setting `frontmatter.enforced.access.policy: public` overrides that draft choice. Use defaults when authors should control publication access.
 
-`frontmatter.fields` declares field types and requirements; it does not fill in missing values. A metadata provider is an additional advanced input to page resolution. See [page metadata](https://www.shoalrun.com/author/frontmatter.md) and the [configuration reference](https://www.shoalrun.com/config.md) before adding one.
+`frontmatter.fields` declares field types and requirements; it doesn't fill in missing values. A metadata provider is an additional advanced input to page resolution. See [page metadata](https://www.shoalrun.com/author/frontmatter.md) and the [configuration reference](https://www.shoalrun.com/config.md) before adding one.
 
 ### Publication defaults serve a different purpose
 
 `publications.defaults` identifies default publication choices, including which channel and version receive an API's top-level source. It also supplies defaults for scaffolding and API selection. The default language supplies a page language when one is missing.
 
-Existing authored pages still need resolved channel and version fields. The starter provides these through `frontmatter.defaults`. Do not assume that changing `publications.defaults.version` also changes every page's metadata.
+Existing authored pages still need resolved channel and version fields. The starter provides these through `frontmatter.defaults`. Don't assume that changing `publications.defaults.version` also changes every page's metadata.
 
-`publications.enabled` selects combinations to build; it does not clone pages into those combinations. Navigation and `doc:` links resolve against the selected publication. See [versions and languages](https://www.shoalrun.com/publish/publications.md) for complete variant and route examples.
+`publications.enabled` selects combinations to build; it doesn't clone pages into those combinations. Navigation and `doc:` links resolve against the selected publication. See [versions and languages](https://www.shoalrun.com/publish/publications.md) for complete variant and route examples.
 
 ## Inspect and validate changes
 
@@ -334,11 +334,11 @@ Use these commands while reorganizing configuration:
 | `config validate docs.config.yaml`           | Successful configuration loading and theme contrast checks                 |
 | `build docs.config.yaml dist`                | Whether content, navigation, APIs, routes, and output can compile together |
 
-Prefix each command with `npx --no-install shoalrun`. For `explain`, the key comes before the config filename. Use numeric segments to inspect lists, such as `navigation.0.doc`. Dotted names represent traversal, so a literal key containing a dot cannot be addressed unambiguously through this CLI syntax.
+Prefix each command with `npx --no-install shoalrun`. For `explain`, the key comes before the config filename. Use numeric segments to inspect lists, such as `navigation.0.doc`. Dotted names represent traversal, so a literal key containing a dot can't be addressed unambiguously through this CLI syntax.
 
-`graph` reports dependencies, not an edge-by-edge visual graph. Its list covers loaded configuration files, not every content or API input. The resolved digest hashes effective values; it is not a digest of all referenced file contents.
+`graph` reports dependencies, not an edge-by-edge visual graph. Its list covers loaded configuration files, not every content or API input. The resolved digest hashes effective values; it isn't a digest of all referenced file contents.
 
-A successful `config validate` does not establish that document links resolve or that an API review digest is current. Run a full build after structural changes. If a setting looks correct but behaves unexpectedly, inspect its exact key and source before editing another layer.
+A successful `config validate` doesn't establish that document links resolve or that an API review digest is current. Run a full build after structural changes. If a setting looks correct but behaves unexpectedly, inspect its exact key and source before editing another layer.
 
 ### Recover common configuration failures
 
@@ -353,7 +353,7 @@ Match the build message or symptom to the corresponding correction.
 | `$remove has no inherited value`    | Add an actual inherited value or remove the unnecessary directive.               |
 | `Unknown config path`               | Inspect `resolve`, then correct the dotted key or list index.                    |
 | A list unexpectedly lost entries    | Replace a normal overlay list with `$concat` when appending was intended.        |
-| A local file cannot be found        | Inspect the path's source file and the relevant path-base rule.                  |
+| A local file can't be found         | Inspect the path's source file and the relevant path-base rule.                  |
 
 Finish the running example with:
 

package/agent-docs/configuration.sections/build-several-sites-from-shared-content.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/configuration.md)
 

package/agent-docs/configuration.sections/change-inherited-lists-deliberately.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/configuration.md)
 
@@ -60,7 +60,7 @@ npx --no-install shoalrun build docs.config.yaml dist
 
 ### Know the directive limits
 
-`$concat` expects a list base when an inherited value exists. It does not append to a mapping. Included lists within `$concat` are flattened one level, so several team navigation fragments can become one list:
+`$concat` expects a list base when an inherited value exists. It doesn't append to a mapping. Included lists within `$concat` are flattened one level, so several team navigation fragments can become one list:
 
 ```yaml
 navigation:
@@ -69,8 +69,8 @@ navigation:
     - { $include: ./config/nav-api.yaml }
 ```
 
-That fragment requires both named files. Each should contain a navigation list. Concatenation preserves order and does not remove duplicates; duplicate navigation IDs still fail during a build.
+That fragment requires both named files. Each should contain a navigation list. Concatenation preserves order and doesn't remove duplicates; duplicate navigation IDs still fail during a build.
 
-`$remove` requires an inherited value. For mappings, its strings name keys. For lists, they match each item's `id`; it does not remove scalar strings or match another field such as `label`. Removing a missing name has no effect. Removing an item does not automatically repair links or other settings that referred to it.
+`$remove` requires an inherited value. For mappings, its strings name keys. For lists, they match each item's `id`; it doesn't remove scalar strings or match another field such as `label`. Removing a missing name has no effect. Removing an item doesn't automatically repair links or other settings that referred to it.
 
-Each directive mapping must contain exactly one directive and no other keys. You cannot combine `$remove` and `$concat` at the same location in one overlay. Use separate preset layers when you need both operations.
+Each directive mapping must contain exactly one directive and no other keys. You can't combine `$remove` and `$concat` at the same location in one overlay. Use separate preset layers when you need both operations.

package/agent-docs/configuration.sections/extract-a-section-with-include.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/configuration.md)
 

package/agent-docs/configuration.sections/inspect-and-validate-changes.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/configuration.md)
 
@@ -45,11 +45,11 @@ Use these commands while reorganizing configuration:
 | `config validate docs.config.yaml`           | Successful configuration loading and theme contrast checks                 |
 | `build docs.config.yaml dist`                | Whether content, navigation, APIs, routes, and output can compile together |
 
-Prefix each command with `npx --no-install shoalrun`. For `explain`, the key comes before the config filename. Use numeric segments to inspect lists, such as `navigation.0.doc`. Dotted names represent traversal, so a literal key containing a dot cannot be addressed unambiguously through this CLI syntax.
+Prefix each command with `npx --no-install shoalrun`. For `explain`, the key comes before the config filename. Use numeric segments to inspect lists, such as `navigation.0.doc`. Dotted names represent traversal, so a literal key containing a dot can't be addressed unambiguously through this CLI syntax.
 
-`graph` reports dependencies, not an edge-by-edge visual graph. Its list covers loaded configuration files, not every content or API input. The resolved digest hashes effective values; it is not a digest of all referenced file contents.
+`graph` reports dependencies, not an edge-by-edge visual graph. Its list covers loaded configuration files, not every content or API input. The resolved digest hashes effective values; it isn't a digest of all referenced file contents.
 
-A successful `config validate` does not establish that document links resolve or that an API review digest is current. Run a full build after structural changes. If a setting looks correct but behaves unexpectedly, inspect its exact key and source before editing another layer.
+A successful `config validate` doesn't establish that document links resolve or that an API review digest is current. Run a full build after structural changes. If a setting looks correct but behaves unexpectedly, inspect its exact key and source before editing another layer.
 
 ### Recover common configuration failures
 
@@ -64,7 +64,7 @@ Match the build message or symptom to the corresponding correction.
 | `$remove has no inherited value`    | Add an actual inherited value or remove the unnecessary directive.               |
 | `Unknown config path`               | Inspect `resolve`, then correct the dotted key or list index.                    |
 | A list unexpectedly lost entries    | Replace a normal overlay list with `$concat` when appending was intended.        |
-| A local file cannot be found        | Inspect the path's source file and the relevant path-base rule.                  |
+| A local file can't be found         | Inspect the path's source file and the relevant path-base rule.                  |
 
 Finish the running example with:
 

package/agent-docs/configuration.sections/related-reading.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/configuration.md)
 

package/agent-docs/configuration.sections/separate-config-inheritance-from-page-metadata.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/configuration.md)
 
@@ -39,16 +39,16 @@ The loader first combines all configured `frontmatter` sections using the config
 frontmatter.defaults → page frontmatter → frontmatter.enforced
 ```
 
-Mappings merge recursively and lists replace at this stage too. Config directives such as `$include`, `$concat`, and `$remove` are not page-frontmatter inheritance instructions.
+Mappings merge recursively and lists replace at this stage too. Config directives such as `$include`, `$concat`, and `$remove` aren't page-frontmatter inheritance instructions.
 
 For example, `frontmatter.defaults.access.policy: public` lets a page set itself to `draft`. Setting `frontmatter.enforced.access.policy: public` overrides that draft choice. Use defaults when authors should control publication access.
 
-`frontmatter.fields` declares field types and requirements; it does not fill in missing values. A metadata provider is an additional advanced input to page resolution. See [page metadata](https://www.shoalrun.com/author/frontmatter.md) and the [configuration reference](https://www.shoalrun.com/config.md) before adding one.
+`frontmatter.fields` declares field types and requirements; it doesn't fill in missing values. A metadata provider is an additional advanced input to page resolution. See [page metadata](https://www.shoalrun.com/author/frontmatter.md) and the [configuration reference](https://www.shoalrun.com/config.md) before adding one.
 
 ### Publication defaults serve a different purpose
 
 `publications.defaults` identifies default publication choices, including which channel and version receive an API's top-level source. It also supplies defaults for scaffolding and API selection. The default language supplies a page language when one is missing.
 
-Existing authored pages still need resolved channel and version fields. The starter provides these through `frontmatter.defaults`. Do not assume that changing `publications.defaults.version` also changes every page's metadata.
+Existing authored pages still need resolved channel and version fields. The starter provides these through `frontmatter.defaults`. Don't assume that changing `publications.defaults.version` also changes every page's metadata.
 
-`publications.enabled` selects combinations to build; it does not clone pages into those combinations. Navigation and `doc:` links resolve against the selected publication. See [versions and languages](https://www.shoalrun.com/publish/publications.md) for complete variant and route examples.
+`publications.enabled` selects combinations to build; it doesn't clone pages into those combinations. Navigation and `doc:` links resolve against the selected publication. See [versions and languages](https://www.shoalrun.com/publish/publications.md) for complete variant and route examples.

package/agent-docs/configuration.sections/share-defaults-through-extends.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/configuration.md)
 
@@ -109,7 +109,7 @@ When a config extends another file, the overlay value determines how each inheri
 | Overlay value            | Result                                                                     |
 | ------------------------ | -------------------------------------------------------------------------- |
 | Mapping over a mapping   | Merge recursively by key. Unchanged keys survive.                          |
-| List                     | Replace the entire inherited list. Items do not merge by ID.               |
+| List                     | Replace the entire inherited list. Items don't merge by ID.                |
 | Scalar, including `null` | Replace the inherited value. The receiving setting must accept that value. |
 | `$concat`                | Append to an inherited list, or create a list if none exists.              |
 | `$remove`                | Remove inherited mapping keys or list entries by `id`.                     |
@@ -118,4 +118,4 @@ This also applies after resolving an include. An included mapping can merge with
 
 To layer a second preset, use `extends: [../shared/base.yaml, ../shared/brand.yaml]`. Only settings in `brand.yaml` override the base; the project's local settings still win.
 
-`extends` is recognized at the top level of each loaded YAML file, including files loaded through `$include`. Avoid using a top-level `extends` key as unrelated data in a fragment. An `extends` nested inside an ordinary mapping is not an inheritance instruction.
+`extends` is recognized at the top level of each loaded YAML file, including files loaded through `$include`. Avoid using a top-level `extends` key as unrelated data in a fragment. An `extends` nested inside an ordinary mapping isn't an inheritance instruction.

package/agent-docs/configuration.sections/start-with-one-working-file.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/configuration.md)
 
@@ -40,7 +40,7 @@ CONFIG_DEMO="$(mktemp -d)"
 mkdir "$CONFIG_DEMO/site"
 cd "$CONFIG_DEMO/site"
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.11
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
 npx --no-install shoalrun init . --starter minimal
 ```
 

package/agent-docs/configuration.sections/understand-the-three-stages.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/configuration.md)
 
@@ -39,7 +39,7 @@ Configuration takes effect in three stages:
 2. **Resolve pages.** Apply configured frontmatter defaults, the page's own metadata, and enforced metadata. Validate the resulting page fields.
 3. **Build publications.** Select public pages for enabled channel/version/language combinations, resolve links and APIs, then produce HTML, Markdown, and discovery files.
 
-A preset changes configuration. A page default changes metadata. An enabled publication selects an edition to build. These mechanisms have separate rules; changing one does not automatically create pages or translations.
+A preset changes configuration. A page default changes metadata. An enabled publication selects an edition to build. These mechanisms have separate rules; changing one doesn't automatically create pages or translations.
 
 ### Find the section you need
 
@@ -56,4 +56,4 @@ Start with the configuration sections that control the behavior you want to chan
 | Style the site and configure rendering         | `theme`, `outputs`                                  |
 | Configure reader views and project checks      | `readerFilters`, `audit`                            |
 
-Every entry config resolves to a YAML mapping with `schemaVersion: 1`. Duplicate YAML keys and unknown top-level settings fail. Nested settings are not all checked for unknown keys, so verify spelling against the reference.
+Every entry config resolves to a YAML mapping with `schemaVersion: 1`. Duplicate YAML keys and unknown top-level settings fail. Nested settings aren't all checked for unknown keys, so verify spelling against the reference.

package/agent-docs/configuration.sections/understand-where-paths-point.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/configuration.md)
 
@@ -46,7 +46,7 @@ Resolution records a source file for every configuration value. Relative paths o
 
 In the running example, `site.customCss: ./brand.css` still finds `shared/brand.css` after the project overrides `site.title`. The two keys keep separate origins.
 
-Moving a path into `config/api.yaml` may require changing `./apis/service.yaml` to `../apis/service.yaml`. Inspect the exact path key with `config explain` after moving it. `config resolve` retains relative strings; it does not rewrite every file path into an absolute path.
+Moving a path into `config/api.yaml` may require changing `./apis/service.yaml` to `../apis/service.yaml`. Inspect the exact path key with `config explain` after moving it. `config resolve` retains relative strings; it doesn't rewrite every file path into an absolute path.
 
 Some grouped settings use the origin of their containing block: custom search uses `outputs.html.search`, fonts use `theme.fonts`, and share images use `outputs.html.shareImages`. Overriding part of such a block can change its path base. Keep a block's relative paths and related overrides together, and inspect that block's source when debugging.
 

package/agent-docs/connect/mcp.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Use this site's MCP
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Connect an MCP client to Shoalrun's live documentation at **`https://www.shoalrun.com/mcp`**. You need an agent application that supports remote HTTP MCP servers. No Shoalrun account, API key, custom header, or local installation is required.
 
@@ -39,9 +39,9 @@ The setting names vary by client. Use its remote MCP server connection settings:
 
 2. ### Connect and discover the tools
 
-   Save the connection and enable it. Restart or reconnect the client if it does not refresh its tools automatically.
+   Save the connection and enable it. Restart or reconnect the client if it doesn't refresh its tools automatically.
 
-   Look for `search_docs`, `get_page`, `get_outline`, and `get_section` under the connection. Your client may prefix their names with `shoalrun-docs`.
+   Look for `get_publications`, `search_docs`, `get_page`, `get_outline`, and `get_section` under the connection. Your client may prefix their names with `shoalrun-docs`.
 
 3. ### Ask the agent to use the documentation
 
@@ -49,30 +49,39 @@ The setting names vary by client. Use its remote MCP server connection settings:
 
    > Use the Shoalrun docs MCP to find how to configure analytics. Read the relevant documentation and give me the answer with source links.
 
-   Inspect the agent's tool activity. It should call `search_docs` and follow a returned read instruction. Answers and links alone do not prove that it used MCP.
+   Inspect the agent's tool activity. It should call `search_docs` and follow a returned read instruction. Answers and links alone don't prove that it used MCP.
 
 ## What the tools do
 
-These tools only read published documentation. They cannot edit your files, change a project, or deploy a site.
+These tools only read published documentation. They can't edit your files, change a project, or deploy a site.
 
-| Tool          | Use                                                  |
-| ------------- | ---------------------------------------------------- |
-| `search_docs` | Find relevant pages and suggested read instructions. |
-| `get_page`    | Read a Markdown page by its stable document ID.      |
-| `get_outline` | List a page's sections and their exact IDs.          |
-| `get_section` | Read one section by page ID and section ID.          |
+| Tool               | Use                                                                                                                         |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
+| `get_publications` | Discover the endpoint’s published product/channel/version/language scope, with `nextOffset` when another page is available. |
+| `search_docs`      | Find relevant pages and suggested read instructions.                                                                        |
+| `get_page`         | Read a Markdown page by its stable document ID.                                                                             |
+| `get_outline`      | List a page's sections and their exact IDs.                                                                                 |
+| `get_section`      | Read one section by page ID and section ID.                                                                                 |
 
-Use IDs returned by the tools rather than guessing them from a page title or URL. When a tool says the result does not fit its token budget, retry with the recommended `maxTokens` value. Do not treat an incomplete response as the complete documentation.
+Use IDs returned by the tools rather than guessing them from a page title or URL. When a tool says the result doesn't fit its token budget, retry with the recommended `maxTokens` value. Don't treat an incomplete response as the complete documentation.
+
+## Discover available publications
+
+Since 0.1.0-alpha.18
+
+Call `get_publications` before searching when the product release is unknown. Follow `nextOffset` for additional compact pages, then retain the returned product, channel, version, and language in search and read calls. This site’s hosted endpoint remains limited to its configured publication. To browse several products in a local built site, use a stdio server as described in [MCP hosting](https://www.shoalrun.com/publish/mcp.md).
+
+The HTML publication dropdown is a reader convenience. Agents use the discovery tool and generated Markdown for the same published product release. Hiding a language label in HTML doesn't remove it from tool arguments.
 
 ## If the connection fails
 
-Check that your client supports remote HTTP MCP and that the URL ends in `/mcp`. A client that only launches local stdio commands cannot connect directly to this URL.
+Check that your client supports remote HTTP MCP and that the URL ends in `/mcp`. A client that only launches local stdio commands can't connect directly to this URL.
 
-If tools are missing after saving, reconnect the server or restart the client. If the client insists on an API key or OAuth login, check that you selected an unauthenticated remote connection. This endpoint does not provide an OAuth login.
+If tools are missing after saving, reconnect the server or restart the client. If the client insists on an API key or OAuth login, check that you selected an unauthenticated remote connection. This endpoint doesn't provide an OAuth login.
 
 This site's MCP analytics measures tool usage, available harness/model labels, and fixed intent categories. It excludes raw queries, free-text intent, returned content, and request headers. Session grouping uses pseudonymous IDs. Hosting access logs are separate; see the [analytics safeguards](https://www.shoalrun.com/publish/mcp-analytics.md).
 
-No private test settings are needed to use the tools or supply supported metadata. Missing or unrecognized labels remain absent; the server does not guess them.
+No private test settings are needed to use the tools or supply supported metadata. Missing or unrecognized labels remain absent; the server doesn't guess them.
 
 ## Related reading