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

package/agent-docs/config/examples.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 The installed package includes complete projects under `node_modules/@shoalrun/cli/example-configs/`, with their pages and local OpenAPI files. Start with a bundled starter in a new directory:
 
@@ -27,7 +27,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 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
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist
@@ -52,13 +52,13 @@ The `showcase` starter provides 18 connected pages. Its component examples cover
 mkdir my-handbook
 cd my-handbook
 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 showcase
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist
 ```
 
-It needs no provider credentials to build. Replace fictional service names, hostnames, and examples before using it for a real product. Hosted chat, remote search, and analytics need your own services; the starter does not connect to a demonstration account.
+It needs no provider credentials to build. Replace fictional service names, hostnames, and examples before using it for a real product. Hosted chat, remote search, and analytics need your own services; the starter doesn't connect to a demonstration account.
 
 ## Minimal site
 

package/agent-docs/config/examples.sections/feature-showcase.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 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
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist
@@ -54,10 +54,10 @@ The `showcase` starter provides 18 connected pages. Its component examples cover
 mkdir my-handbook
 cd my-handbook
 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 showcase
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist
 ```
 
-It needs no provider credentials to build. Replace fictional service names, hostnames, and examples before using it for a real product. Hosted chat, remote search, and analytics need your own services; the starter does not connect to a demonstration account.
+It needs no provider credentials to build. Replace fictional service names, hostnames, and examples before using it for a real product. Hosted chat, remote search, and analytics need your own services; the starter doesn't connect to a demonstration account.

package/agent-docs/config/examples.sections/minimal-site.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 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
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/multilingual-help-center.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 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
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/parcel-api-documentation.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 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
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

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

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 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
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/shared-company-preset.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 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
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/integrations.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 > Search and integration
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Configure search synonyms, the read-only MCP endpoint, and browser analytics. 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.
 
@@ -36,7 +36,7 @@ mcp:
   publication: { channel: production, version: current, language: en }
 ```
 
-`path` defaults to `/mcp` and is mounted beneath `site.basePath`. The build rejects conflicting output routes. `enabled` must be a boolean, and enabled configurations require `access: public` and all three publication coordinates.
+`path` defaults to `/mcp` and is mounted beneath `site.basePath`. The build rejects conflicting output routes. `enabled` must be a boolean, and enabled configurations require `access: public`, channel, version, and language. The `mcp.publication.product` option Since 0.1.0-alpha.18 selects a product release. It accepts a product ID, for example `{ product: payments, channel: production, version: v3, language: en }`. The endpoint still serves one configured publication; its discovery response can't reveal other products or customer editions.
 
 Optional `allowedHosts` lists exact hostnames without ports or wildcards. Optional `allowedOrigins` lists exact HTTP(S) browser origins. `site.origin` contributes its hostname and origin automatically; the local Node server also permits loopback requests. Unknown settings fail validation.
 
@@ -46,13 +46,13 @@ Optional `mcp.analytics.module` names a local `.js` or `.mjs` server adapter exp
 
 Optional `mcp.analytics.consent` contains `header` and `value`. When configured, only requests with that exact header value can load or call the analytics adapter. Other requests can use the documentation tools without tracking. The header must be a lowercase custom `x-` name; forwarded, Vercel, and MCP protocol headers are reserved. The value is a case-sensitive policy identifier of up to 64 letters, digits, dots, underscores, or hyphens.
 
-The header gate is off when omitted or set to `false`; readers then need no special client configuration for analytics. Use the gate only when your deployment requires explicit caller opt-in. In that mode, removing the header stops collection on future requests. This feature does not determine your privacy obligations. See [analytics safeguards](https://www.shoalrun.com/publish/mcp-analytics.md).
+The header gate is off when omitted or set to `false`; readers then need no special client configuration for analytics. Use the gate only when your deployment requires explicit caller opt-in. In that mode, removing the header stops collection on future requests. This feature doesn't determine your privacy obligations. See [analytics safeguards](https://www.shoalrun.com/publish/mcp-analytics.md).
 
 Optional `mcp.analytics.clientMetadata: true` adds normalized client labels and model labels from a fixed registry when supported request metadata is present. It defaults to `false`. Labels are unverified; raw headers, unrelated metadata, queries, and intent are excluded.
 
 Optional `mcp.analytics.intent` and `mcp.analytics.conversationIds` are booleans that default to `false`. An adapter’s optional `instrument(server, options)` hook implements them. The PostHog example can add context/model arguments and conversation handles while excluding raw queries and results. Its context argument requests a fixed intent category. Free-text or invalid values are replaced with a per-tool category before analytics delivery; raw intent is never stored by that example. Other adapters must implement their own safeguards.
 
-Omit `mcp.analytics` or set it to `false` to disable collection. It is independent of browser analytics and does not instrument stdio. See [measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) for fields, service mappings, and a PostHog example.
+Omit `mcp.analytics` or set it to `false` to disable collection. It's independent of browser analytics and doesn't instrument stdio. See [measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) for fields, service mappings, and a PostHog example.
 
 ## `analytics`
 

package/agent-docs/config/outputs.md

@@ -17,13 +17,13 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Output and export
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 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.
 
 ## `metadata`
 
-`metadata.provider.module` names an optional local module that exports `provideMetadata(context)`. The module can supply owned page fields to the build. The framework does not run an external vocabulary validator or publish supplied fields automatically. See [custom metadata](https://www.shoalrun.com/author/custom-metadata.md) for the return shape and ownership rule.
+`metadata.provider.module` names an optional local module that exports `provideMetadata(context)`. The module can supply owned page fields to the build. The framework doesn't run an external vocabulary validator or publish supplied fields automatically. See [custom metadata](https://www.shoalrun.com/author/custom-metadata.md) for the return shape and ownership rule.
 
 ```yaml title="docs.config.yaml"
 metadata:
@@ -37,21 +37,21 @@ The path is relative to the config file that declares it. `provider` accepts onl
 
 Use [resource selectors](https://www.shoalrun.com/content-delivery/select.md) to select pages, approved sections, and named snippet instances.
 
-Optional named targets for `shoalrun export`. They select portable application content independently of website navigation and `site.contentFilter`. The normal website build does not emit export bundles automatically. See [export content into an application](https://www.shoalrun.com/publish/content-export.md).
+Optional named targets for `shoalrun export`. They select portable application content independently of website navigation and `site.contentFilter`. The normal website build doesn't emit export bundles automatically. See [export content into an application](https://www.shoalrun.com/publish/content-export.md).
 
 Each target accepts these fields:
 
-| Field           | Default                                         | Meaning                                                                                                                  |
-| --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `formats`       | `[markdown, html]`                              | A nonempty unique list of `markdown` and/or `html`.                                                                      |
-| `documents`     | All eligible pages when neither selector is set | Explicit document IDs. Missing, inaccessible, or export-filtered IDs fail. Mutually exclusive with `resources`.          |
-| `resources`     | None                                            | Typed page, section, or snippet selectors. Mutually exclusive with `documents`.                                          |
-| `publication`   | The only enabled publication                    | One complete `{ channel, version, language }` combination. Required when selection is ambiguous.                         |
-| `contentFilter` | None                                            | Optional configured reader facets; every facet must match any listed choice. Unmarked pages do not match.                |
-| `publicBase`    | `/`                                             | Root-relative mount with a trailing slash, such as `/help/`. It locates bundle content and assets in the app.            |
-| `assetRoots`    | Content directory only                          | Extra local asset directories, relative to the declaring config file. Only referenced supported files are copied.        |
-| `notices`       | Renderer notices only                           | Local text or Markdown license/notice files to retain in `NOTICES.txt`. Paths are relative to the declaring config file. |
-| `apiReview`     | Matching API-level approval, if any             | API IDs mapped to reviewed SHA-256 digests for this export selection.                                                    |
+| Field           | Default                                         | Meaning                                                                                                                                            |
+| --------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `formats`       | `[markdown, html]`                              | A nonempty unique list of `markdown` and/or `html`.                                                                                                |
+| `documents`     | All eligible pages when neither selector is set | Explicit document IDs. Missing, inaccessible, or export-filtered IDs fail. Mutually exclusive with `resources`.                                    |
+| `resources`     | None                                            | Typed page, section, or snippet selectors. Mutually exclusive with `documents`.                                                                    |
+| `publication`   | The only enabled publication                    | One complete `{ channel, version, language }` combination. Product-scoped selection also requires `product`. Required when selection is ambiguous. |
+| `contentFilter` | None                                            | Optional configured reader facets; every facet must match any listed choice. Unmarked pages don't match.                                           |
+| `publicBase`    | `/`                                             | Root-relative mount with a trailing slash, such as `/help/`. It locates bundle content and assets in the app.                                      |
+| `assetRoots`    | Content directory only                          | Extra local asset directories, relative to the declaring config file. Only referenced supported files are copied.                                  |
+| `notices`       | Renderer notices only                           | Local text or Markdown license/notice files to retain in `NOTICES.txt`. Paths are relative to the declaring config file.                           |
+| `apiReview`     | Matching API-level approval, if any             | API IDs mapped to reviewed SHA-256 digests for this export selection.                                                                              |
 
 ```yaml
 exports:
@@ -63,6 +63,12 @@ exports:
 
 The export preserves whole-page content, including all reader sections. It flattens interactive components into readable static content and omits website/browser runtimes. Unsupported output, escaping assets, and unavailable document fallbacks fail. `exports` and its target fields are validated for unknown keys.
 
+Since 0.1.0-alpha.18
+
+Upgrade the exporter and content client together to use product-scoped bundles.
+
+For a product release, set `publication: { product: payments, channel: production, version: v3, language: en }`. The complete publication must be enabled by the configuration and any selected customer profile. Each target exports one publication; use separate targets or runs for independent product releases. Product bundles emit v2 manifests; productless bundles keep v1. See the [manifest reference](https://www.shoalrun.com/content-delivery/manifest.md) for the contract.
+
 ## `outputs`
 
 Use `outputs` to configure the HTML, Markdown, discovery, and text artifacts produced by a build.
@@ -72,7 +78,7 @@ Use `outputs` to configure the HTML, Markdown, discovery, and text artifacts pro
 | `markdown.metadata`          | The Markdown twin's YAML header: `format`, `fields`, `addFields`, `removeFields`, `omitNull`, `byType`, and `profiles`. `format` defaults to `none`. See [Markdown metadata](https://www.shoalrun.com/author/markdown-metadata.md). |
 | `html.shareImages`           | `true`: a generated 1200×630 link-preview image per page. `false` turns them off; a mapping with `template` and `fonts` replaces the design. See [share images and favicon](https://www.shoalrun.com/styling/share-images.md).      |
 | `html.highlighting`          | Code highlighting `provider`, `theme`, and `module`. Defaults to Shiki with the `site` theme, which takes code colors from the palette. See [code blocks](https://www.shoalrun.com/author/components/code-blocks.md).               |
-| `html.navigation.heading`    | Heading above the sidebar filter. Defaults to `Explore`; use nonempty text to replace it or `false` to hide it. Available since `0.1.0-alpha.13`.                                                                                   |
+| `html.navigation.heading`    | Heading above the sidebar filter. Defaults to `Explore`; use nonempty text to replace it or `false` to hide it. Since 0.1.0-alpha.13                                                                                                |
 | `html.navigation.showCounts` | Show page counts beside navigation groups. Defaults to `true`; set `false` to omit them. See [navigation](https://www.shoalrun.com/author/navigation.md).                                                                           |
 | `html.search`                | Search `provider`, `module`, and `index`. See [search](https://www.shoalrun.com/author/search.md).                                                                                                                                  |
 | `text`                       | Ordered frontmatter field paths for `card`, `pageHeader`, `search`, `htmlDescription`, and `socialCard`. See [custom metadata](https://www.shoalrun.com/author/custom-metadata.md).                                                 |
@@ -130,7 +136,7 @@ outputs:
 
 ### Agent discovery index
 
-Every published page is included automatically, using its title and frontmatter summary. You do not need to list page IDs. Omit `outputs.llms` for automatic grouping, or choose a bare alphabetical list of links and summaries:
+Every published page is included automatically, using its title and frontmatter summary. You don't need to list page IDs. Omit `outputs.llms` for automatic grouping, or choose a bare alphabetical list of links and summaries:
 
 ```yaml title="docs.config.yaml"
 outputs:

package/agent-docs/config/outputs.sections/exports.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Output and export
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/config/outputs.md)
 
@@ -33,21 +33,21 @@ Configure metadata providers, application exports, Markdown headers, and discove
 
 Use [resource selectors](https://www.shoalrun.com/content-delivery/select.md) to select pages, approved sections, and named snippet instances.
 
-Optional named targets for `shoalrun export`. They select portable application content independently of website navigation and `site.contentFilter`. The normal website build does not emit export bundles automatically. See [export content into an application](https://www.shoalrun.com/publish/content-export.md).
+Optional named targets for `shoalrun export`. They select portable application content independently of website navigation and `site.contentFilter`. The normal website build doesn't emit export bundles automatically. See [export content into an application](https://www.shoalrun.com/publish/content-export.md).
 
 Each target accepts these fields:
 
-| Field           | Default                                         | Meaning                                                                                                                  |
-| --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `formats`       | `[markdown, html]`                              | A nonempty unique list of `markdown` and/or `html`.                                                                      |
-| `documents`     | All eligible pages when neither selector is set | Explicit document IDs. Missing, inaccessible, or export-filtered IDs fail. Mutually exclusive with `resources`.          |
-| `resources`     | None                                            | Typed page, section, or snippet selectors. Mutually exclusive with `documents`.                                          |
-| `publication`   | The only enabled publication                    | One complete `{ channel, version, language }` combination. Required when selection is ambiguous.                         |
-| `contentFilter` | None                                            | Optional configured reader facets; every facet must match any listed choice. Unmarked pages do not match.                |
-| `publicBase`    | `/`                                             | Root-relative mount with a trailing slash, such as `/help/`. It locates bundle content and assets in the app.            |
-| `assetRoots`    | Content directory only                          | Extra local asset directories, relative to the declaring config file. Only referenced supported files are copied.        |
-| `notices`       | Renderer notices only                           | Local text or Markdown license/notice files to retain in `NOTICES.txt`. Paths are relative to the declaring config file. |
-| `apiReview`     | Matching API-level approval, if any             | API IDs mapped to reviewed SHA-256 digests for this export selection.                                                    |
+| Field           | Default                                         | Meaning                                                                                                                                            |
+| --------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `formats`       | `[markdown, html]`                              | A nonempty unique list of `markdown` and/or `html`.                                                                                                |
+| `documents`     | All eligible pages when neither selector is set | Explicit document IDs. Missing, inaccessible, or export-filtered IDs fail. Mutually exclusive with `resources`.                                    |
+| `resources`     | None                                            | Typed page, section, or snippet selectors. Mutually exclusive with `documents`.                                                                    |
+| `publication`   | The only enabled publication                    | One complete `{ channel, version, language }` combination. Product-scoped selection also requires `product`. Required when selection is ambiguous. |
+| `contentFilter` | None                                            | Optional configured reader facets; every facet must match any listed choice. Unmarked pages don't match.                                           |
+| `publicBase`    | `/`                                             | Root-relative mount with a trailing slash, such as `/help/`. It locates bundle content and assets in the app.                                      |
+| `assetRoots`    | Content directory only                          | Extra local asset directories, relative to the declaring config file. Only referenced supported files are copied.                                  |
+| `notices`       | Renderer notices only                           | Local text or Markdown license/notice files to retain in `NOTICES.txt`. Paths are relative to the declaring config file.                           |
+| `apiReview`     | Matching API-level approval, if any             | API IDs mapped to reviewed SHA-256 digests for this export selection.                                                                              |
 
 ```yaml
 exports:
@@ -58,3 +58,9 @@ exports:
 ```
 
 The export preserves whole-page content, including all reader sections. It flattens interactive components into readable static content and omits website/browser runtimes. Unsupported output, escaping assets, and unavailable document fallbacks fail. `exports` and its target fields are validated for unknown keys.
+
+Since 0.1.0-alpha.18
+
+Upgrade the exporter and content client together to use product-scoped bundles.
+
+For a product release, set `publication: { product: payments, channel: production, version: v3, language: en }`. The complete publication must be enabled by the configuration and any selected customer profile. Each target exports one publication; use separate targets or runs for independent product releases. Product bundles emit v2 manifests; productless bundles keep v1. See the [manifest reference](https://www.shoalrun.com/content-delivery/manifest.md) for the contract.

package/agent-docs/config/outputs.sections/metadata.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Output and export
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/config/outputs.md)
 
@@ -31,7 +31,7 @@ Configure metadata providers, application exports, Markdown headers, and discove
 
 ## `metadata`
 
-`metadata.provider.module` names an optional local module that exports `provideMetadata(context)`. The module can supply owned page fields to the build. The framework does not run an external vocabulary validator or publish supplied fields automatically. See [custom metadata](https://www.shoalrun.com/author/custom-metadata.md) for the return shape and ownership rule.
+`metadata.provider.module` names an optional local module that exports `provideMetadata(context)`. The module can supply owned page fields to the build. The framework doesn't run an external vocabulary validator or publish supplied fields automatically. See [custom metadata](https://www.shoalrun.com/author/custom-metadata.md) for the return shape and ownership rule.
 
 ```yaml title="docs.config.yaml"
 metadata:

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

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

package/agent-docs/config/publishing.md

@@ -1,7 +1,7 @@
 ---
 id: reference.config-publishing
 title: Publications and routing settings
-summary: Configure versions, languages, navigation, and redirects.
+summary: Configure product releases, versions, languages, navigation, and redirects.
 type: reference
 area: publishing
 subarea: publishing-configuration
@@ -16,26 +16,36 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Publications and routing
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 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.
+Required. Declares which channel, version, and language combinations to build. Product publications also include a product ID. See [how Shoalrun works](https://www.shoalrun.com/concepts.md) for the concepts.
+
+Since 0.1.0-alpha.18
+
+The product settings below extend publication configuration. Existing productless publications retain their current routes and identities.
 
 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. |
+| Key                                                        | Meaning                                                                                                                                                                                                                                                                                                                     |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`                                                  | At least one publication coordinate. Product publications add `product` to `{ channel, version, language }`. `language` defaults to the default language; a product version can default from its catalog. Unknown coordinates and duplicates fail.                                                                          |
+| `channels.<name>.pathPrefix`                               | Route prefix for a channel. Every channel used in `enabled` must be declared, even with `pathPrefix: ""`.                                                                                                                                                                                                                   |
+| `versions.<name>.pathPrefix`                               | Version prefix for productless publications. May coexist with product catalogs; omit `versions` when every enabled publication has a product.                                                                                                                                                                               |
+| `products.<id>`                                            | Product catalog with required `pathPrefix`, `defaultVersion`, and nonempty `versions`; optional `label`. Product IDs use letters, digits, dots, underscores, and hyphens.                                                                                                                                                   |
+| `products.<id>.pathPrefix`                                 | Required nonempty absolute product prefix, such as `/payments`. Must be unique without regard to case; no trailing slash, repeated slash, or traversal.                                                                                                                                                                     |
+| `products.<id>.defaultVersion`                             | A declared version in this product catalog. Used when a product coordinate omits `version`.                                                                                                                                                                                                                                 |
+| `products.<id>.versions.<version>.pathPrefix`              | Version prefix within the product. Prefixes must be distinct within a product, including the empty prefix.                                                                                                                                                                                                                  |
+| `defaults.product`, `defaults.channel`, `defaults.version` | Scope the default API `source` and authoring commands. A product uses its own `defaultVersion` unless `defaults.product` matches it and `defaults.version` is valid in that catalog. Product source bindings can also declare an API-level `product`. Explicit API publication bindings don't need a global default source. |
+| `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, adding `product` for product publications. 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.
 
-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.
+For independent product catalogs and migration from product metadata, see [share pages across products and versions](https://www.shoalrun.com/publish/publications.md). Product routes combine base path, nondefault language, product prefix, channel prefix, version prefix, and page slug. An undeclared product version fails instead of using a root version with the same name.
 
 A single publication with no prefixes. Pages set `channel: production` and `version: current`:
 
@@ -65,7 +75,7 @@ publications:
     - { 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:
+A sandbox channel, with a version that's 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:
@@ -165,7 +175,7 @@ A list of old URLs to send to a current page. Shoalrun's own docs use redirects
 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 change `site.basePath`, a product, 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.
@@ -200,11 +210,11 @@ Send an old URL to a page in another publication, such as a retired v1 page to i
 
 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`.                                                     |
+| 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. Add `product` for a product publication target. |
+| `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/navigation.md

@@ -1,7 +1,7 @@
 ---
 id: reference.config-publishing
 title: Publications and routing settings
-summary: Configure versions, languages, navigation, and redirects.
+summary: Configure product releases, versions, languages, navigation, and redirects.
 type: reference
 area: publishing
 subarea: publishing-configuration
@@ -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 > Publications and routing
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/config/publishing.md)
 

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

@@ -1,7 +1,7 @@
 ---
 id: reference.config-publishing
 title: Publications and routing settings
-summary: Configure versions, languages, navigation, and redirects.
+summary: Configure product releases, versions, languages, navigation, and redirects.
 type: reference
 area: publishing
 subarea: publishing-configuration
@@ -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 > Publications and routing
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/config/publishing.md)
 
@@ -35,7 +35,7 @@ A list of old URLs to send to a current page. Shoalrun's own docs use redirects
 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 change `site.basePath`, a product, 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.
@@ -70,10 +70,10 @@ Send an old URL to a page in another publication, such as a retired v1 page to i
 
 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`.                                                     |
+| 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. Add `product` for a product publication target. |
+| `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

@@ -1,7 +1,7 @@
 ---
 id: reference.config-publishing
 title: Publications and routing settings
-summary: Configure versions, languages, navigation, and redirects.
+summary: Configure product releases, versions, languages, navigation, and redirects.
 type: reference
 area: publishing
 subarea: publishing-configuration
@@ -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 > Publications and routing
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/config/publishing.md)