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

package/agent-docs/publish/output.sections/published-output-contract.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 
@@ -35,11 +35,11 @@ The site also includes a **document manifest**, `documents.json`, which indexes
 
 ## Published-output contract
 
-This page is the consumer reference for Shoalrun's current published output. It describes the existing producer, not a general format that other generators must implement. The manifest and sync snapshot use `schemaVersion: 1`. Editorial revisions to this reference do not change that wire version.
+This page is the consumer reference for Shoalrun's current published output. It describes the existing producer, not a general format that other generators must implement. The manifest and sync snapshot use `schemaVersion: 1`. Editorial revisions to this reference don't change that wire version.
 
-The repository maintains JSON Schema 2020-12 definitions at `framework/schemas/manifest.schema.json` and `framework/schemas/sync.schema.json`. They specify required fields and known value shapes; this reference explains their meaning. Schema identifiers are stable names for local resolution, not a promise that a site hosts the schema files. Register both schemas together when validating a sync snapshot. They remain repository validation resources and are not added to site output.
+The repository maintains JSON Schema 2020-12 definitions at `framework/schemas/manifest.schema.json` and `framework/schemas/sync.schema.json`. They specify required fields and known value shapes; this reference explains their meaning. Schema identifiers are stable names for local resolution, not a promise that a site hosts the schema files. Register both schemas together when validating a sync snapshot. They remain repository validation resources and aren't added to site output.
 
-Consumers must tolerate unknown properties. Optional fields may be absent; absence is not evidence of a negative claim. Removing a required field, changing a field's meaning, or making existing valid output incompatible requires a new wire version. Adding optional fields can retain version 1. Changes to a constrained value set also need compatibility review; accepting unknown properties does not mean a consumer accepts unknown enum values.
+Consumers must tolerate unknown properties. Optional fields may be absent; absence isn't evidence of a negative claim. Removing a required field, changing a field's meaning, or making existing valid output incompatible requires a new wire version. Adding optional fields can retain version 1. Changes to a constrained value set also need compatibility review; accepting unknown properties doesn't mean a consumer accepts unknown enum values.
 
 | Capability                                                                                                        | Availability                                                                                        |
 | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
@@ -55,4 +55,4 @@ Routes include the configured base path and publication prefixes. Start at `llms
 
 A document's identity is `(id, channel, version, language)`, not its title, URL, or array position. The same ID in two publications identifies two records. That tuple must be unique in both the manifest and sync snapshot. Cite it with the resource URL; for sections, also retain section identity and parent/section digests. A manifest array pointer is a link into that snapshot, not a permanent document identifier.
 
-`indexable` describes indexing, not access. `demo: false` means unmarked, not a verified service. Missing or null `subjectLifecycle` does not mean stable. `verified` is an author's review date, not compiler or independent verification. `updated` records content freshness and can be a calendar date or a timestamp with a timezone. Reader filters control presentation, not authorization.
+`indexable` describes indexing, not access. `demo: false` means unmarked, not a verified service. Missing or null `subjectLifecycle` doesn't mean stable. `verified` is an author's review date, not compiler or independent verification. `updated` records content freshness and can be a calendar date or a timestamp with a timezone. Reader filters control presentation, not authorization.

package/agent-docs/publish/output.sections/reader-appearance-and-controls.md

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

package/agent-docs/publish/output.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) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 

package/agent-docs/publish/output.sections/response-identity.md

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

package/agent-docs/publish/output.sections/site-files.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 
@@ -35,11 +35,11 @@ The site also includes a **document manifest**, `documents.json`, which indexes
 
 ## Site files
 
-- `documents.json` is the document manifest. Its top-level keys are `schemaVersion`, `buildId`, `configDigest`, `dependencies`, `documents`, `operations`, `relationships`, `redirects`, and `apiSources`. Each entry in `documents` describes one page variant. `contentDigest` fingerprints resolved article content for freshness; `digest` is the SHA-256 of the complete generated Markdown bytes. Use `digest` to check a fetched Markdown twin for changes, and pair the stable ID with its publication variant when comparing records. A page with an author-set `verified` date exposes it independently of `updated`. It has the stable ID, type, title, summary, subjectLifecycle, publication variant, and HTML and Markdown URLs. Optional `subjectDeprecation` carries author-declared `deprecatedOn` and `sunsetOn` dates and resolved `replacement` and `migration` targets, each with `id`, `title`, `url`, and `markdownUrl`. A changelog entry can also expose optional `change` with an author-declared `kind`, an `affects` target list, and a `migration` target when supplied. Change targets use the same `id`, `title`, `url`, and `markdownUrl` shape; absence means unclassified. Deprecation guidance appears in HTML, full Markdown, and section Markdown; it describes the subject rather than retirement of the documentation resource. Every record has a boolean `demo`, set from `outputs.llms.fictionalPrefixes`. A true value identifies an author-declared fictional example. False means unmarked; it does not verify that an API is live. The full and compact search indexes carry the same flag. Optional `product`, `area`, and `subarea` categories appear when set. It also lists card targets and queries, snippet and API embed uses, focused contract details, and a content digest. When reader views are configured, the manifest also has top-level `readerFacets` and a resolved `readerFilters` map on each page. An empty map means the page is shared. `dependencies` lists the source files the build read, without local paths. Project files are relative to `docs.config.yaml`, framework files start with `shoalrun:`, and installed packages start with `package:`.
+- `documents.json` is the document manifest. Its top-level keys are `schemaVersion`, `buildId`, `configDigest`, `dependencies`, `documents`, `operations`, `relationships`, `redirects`, and `apiSources`. Each entry in `documents` describes one page variant. `contentDigest` fingerprints resolved article content for freshness; `digest` is the SHA-256 of the complete generated Markdown bytes. Use `digest` to check a fetched Markdown twin for changes, and pair the stable ID with its publication variant when comparing records. A page with an author-set `verified` date exposes it independently of `updated`. It has the stable ID, type, title, summary, subjectLifecycle, publication variant, and HTML and Markdown URLs. Optional `subjectDeprecation` carries author-declared `deprecatedOn` and `sunsetOn` dates and resolved `replacement` and `migration` targets, each with `id`, `title`, `url`, and `markdownUrl`. A changelog entry can also expose optional `change` with an author-declared `kind`, an `affects` target list, and a `migration` target when supplied. Change targets use the same `id`, `title`, `url`, and `markdownUrl` shape; absence means unclassified. Deprecation guidance appears in HTML, full Markdown, and section Markdown; it describes the subject rather than retirement of the documentation resource. Every record has a boolean `demo`, set from `outputs.llms.fictionalPrefixes`. A true value identifies an author-declared fictional example. False means unmarked; it doesn't verify that an API is live. The full and compact search indexes carry the same flag. Optional `product`, `area`, and `subarea` categories appear when set. It also lists card targets and queries, snippet and API embed uses, focused contract details, and a content digest. When reader views are configured, the manifest also has top-level `readerFacets` and a resolved `readerFilters` map on each page. An empty map means the page is shared. `dependencies` lists the source files the build read, without local paths. Project files are relative to `docs.config.yaml`, framework files start with `shoalrun:`, and installed packages start with `package:`.
 
 - `documents.sync.json` contains the build ID and compact page signatures for comparing saved snapshots. See **Incremental sync** below.
 
-- `build-info.json` records the build ID, resolved config digest and, when supplied by the build command, the source commit and release label. It is public build provenance, not a version archive. See [use Git branches for separate docs sites](https://www.shoalrun.com/publish/revisions.md).
+- `build-info.json` records the build ID, resolved config digest and, when supplied by the build command, the source commit and release label. It's public build provenance, not a version archive. See [use Git branches for separate docs sites](https://www.shoalrun.com/publish/revisions.md).
 
 - `404.html` and `404.md` provide concise recovery links for missing pages. Node serving and Vercel routing preserve HTTP `404`; another static host needs an error-page rule. These files are omitted from the document manifest, sitemap, and search index.
 
@@ -51,14 +51,14 @@ The site also includes a **document manifest**, `documents.json`, which indexes
 
 - `llms.min.txt` is the compact starting point for agents. Small sites list page variants directly; larger sites link to topic indexes grouped by publication and primary taxonomy area, or page type when no area is declared. Growing topics split automatically. Each index stays within 2,000 `cl100k_base` tokens. Page entries retain stable IDs, titles, summaries, Markdown URLs, and fictional-example labels. Follow index links until you reach a matching page. All published pages remain reachable, including pages outside navigation; the complete catalog and search index remain optional.
 
-- `search-index.min.json` adds page headings to titles, summaries, IDs, types, publication variants, and URLs. It omits article text and reader segments. It is generated whenever the full search index is enabled. Both are static files, not query endpoints.
+- `search-index.min.json` adds page headings to titles, summaries, IDs, types, publication variants, and URLs. It omits article text and reader segments. It's generated whenever the full search index is enabled. Both are static files, not query endpoints.
 
 - `search-index.json` lists page IDs, HTML and Markdown URLs, titles, summaries, headings, and text for the [search box](https://www.shoalrun.com/author/search.md) and local search command. The default lexical provider needs it; a custom provider can opt in.
 
 - `/assets/search-provider.js` is the search provider module, built-in or custom.
 
-When `site.origin` is set and indexing is enabled, the build writes `/sitemap.xml` with canonical HTML page URLs, `/llms.txt`, and optional page `lastmod` values. Markdown twins are alternate representations; their HTTP `Link` header names the HTML page as canonical. They are omitted from the sitemap. `/robots.txt` advertises it. Both derive from the same published pages as `documents.json`; `seo.noindex` pages are omitted. Large sitemaps are split into direct child URL sitemaps under a single index. The manifest records `sitemap`, and each document records `indexable` and optional `updated`.
+When `site.origin` is set and indexing is enabled, the build writes `/sitemap.xml` with canonical HTML page URLs, `/llms.txt`, and optional page `lastmod` values. Markdown twins are alternate representations; their HTTP `Link` header names the HTML page as canonical. They're omitted from the sitemap. `/robots.txt` advertises it. Both derive from the same published pages as `documents.json`; `seo.noindex` pages are omitted. Large sitemaps are split into direct child URL sitemaps under a single index. The manifest records `sitemap`, and each document records `indexable` and optional `updated`.
 
-The local frontmatter inventory and JSON Schema are build outputs in `.shoalrun/` beside `docs.config.yaml`. They are available to authors and agents in the repository. A site can also publish its current field inventory on an authored page with `<FrontmatterReference />`, as [this documentation site does](https://www.shoalrun.com/author/frontmatter-reference.md).
+The local frontmatter inventory and JSON Schema are build outputs in `.shoalrun/` beside `docs.config.yaml`. They're available to authors and agents in the repository. A site can also publish its current field inventory on an authored page with `<FrontmatterReference />`, as [this documentation site does](https://www.shoalrun.com/author/frontmatter-reference.md).
 
 After publishing, run the [deployment checker](https://www.shoalrun.com/publish/deployment-check.md) against the live origin to verify the host serves these formats and discovery files with the expected response headers.

package/agent-docs/publish/output.sections/validate-an-existing-build-locally.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 
@@ -35,7 +35,7 @@ The site also includes a **document manifest**, `documents.json`, which indexes
 
 ## Validate an existing build locally
 
-This checker belongs to Shoalrun’s documentation repository; it is not an installed CLI command. From that repository with its dependencies installed, run:
+This checker belongs to Shoalrun’s documentation repository; it isn't an installed CLI command. From that repository with its dependencies installed, run:
 
 ```sh
 node scripts/check-output-contract.mjs docs/dist
@@ -45,4 +45,4 @@ Replace `docs/dist` with an already-built site's directory. The checker loads bo
 
 The report has `status`, `findings`, and document/section counts. A failure exits nonzero. The command never rebuilds, writes output, evaluates model tasks, or checks live hosting. The existing repository built-site check includes this check, so run either path rather than duplicating it for unchanged output. Use the [deployment checker](https://www.shoalrun.com/publish/deployment-check.md) separately for HTTP behavior.
 
-Passing checks establish the specified structure and consistency, not authored truth, semantic completeness, or a fresh evaluation grade. The build identity is compared across files, not recomputed from final stamped artifacts. This contract does not add `llms-full.txt`, a public evaluation report, signatures, or an offline release archive.
+Passing checks establish the specified structure and consistency, not authored truth, semantic completeness, or a fresh evaluation grade. The build identity is compared across files, not recomputed from final stamped artifacts. This contract doesn't add `llms-full.txt`, a public evaluation report, signatures, or an offline release archive.

package/agent-docs/publish/output.sections/where-files-go.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 
@@ -35,7 +35,7 @@ The site also includes a **document manifest**, `documents.json`, which indexes
 
 ## Where files go
 
-`shoalrun build <config> <output>` writes the site to the output directory. It builds in a temporary directory, then **deletes the output directory and replaces it**, so point it at a directory that holds only build output. To protect other folders, it replaces a directory only when it is new, empty, or an earlier build. Otherwise the build stops before deleting anything.
+`shoalrun build <config> <output>` writes the site to the output directory. It builds in a temporary directory, then **deletes the output directory and replaces it**, so point it at a directory that holds only build output. To protect other folders, it replaces a directory only when it's new, empty, or an earlier build. Otherwise the build stops before deleting anything.
 
 | Output                     | Path                                                                                                                                  |
 | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
@@ -46,4 +46,4 @@ The site also includes a **document manifest**, `documents.json`, which indexes
 | Published OpenAPI source   | `/api/<apiId>/<channel>/<version>/<file>`, plus the local files it references                                                         |
 | Focused contracts          | `/api/operations/<channel>/<version>/<language>/<name>-<hash>.json`                                                                   |
 
-The `/api` and `/.well-known` paths are reserved for these files, so page slugs cannot use them. A [diagram](https://www.shoalrun.com/author/components/diagrams.md) in the Markdown twin keeps its title, summary, a link to the light SVG, and its fenced source.
+The `/api` and `/.well-known` paths are reserved for these files, so page slugs can't use them. A [diagram](https://www.shoalrun.com/author/components/diagrams.md) in the Markdown twin keeps its title, summary, a link to the light SVG, and its fenced source.

package/agent-docs/publish/publications.md

@@ -1,33 +1,120 @@
 ---
 id: guide.publications
-title: Share pages across documentation versions
-summary: "Versioning one docs site without copying every page: share unchanged
-  pages, vary sections, and publish changed pages separately."
+title: Share pages across products and documentation versions
+summary: Configure independent product versioning and reuse pages across
+  releases, channels, and languages.
 type: how-to
 area: publishing
 subarea: publishing-versions
 canonical: /publish/publications
 ---
 
-# Share pages across documentation versions
+# Share pages across products and documentation versions
 
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
 
 Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Share pages across documentation versions
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Products, versions, and languages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
-Say you support v1 and v2. Your setup instructions are mostly the same, but v2 has a new credential and one extra guide. You can keep the common instructions in **one source file**, show the right credential in each version, and publish the extra guide only in v2.
+Publish documentation for different releases, channels, and languages from one content source. Keep common instructions in one file and select the content that changes between publications. If you document multiple products, each can have its own versions and defaults.
 
-Shoalrun calls each channel, version, and language combination a **publication**. You choose which publications a build makes. A Git branch or tag chooses *which revision of the repository to build*; it does not automatically create a docs version. For separate sites such as stable and next, see [publish separate docs sites from Git](https://www.shoalrun.com/publish/revisions.md).
+A **publication** identifies a product, channel, version, and language. For a site without product catalogs, it identifies just channel, version, and language. These coordinates determine which page variant readers and agents receive, including its route, links, and search scope.
 
-For separate sites selected by audience, product, region, or another configured facet, see [build sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md). That workflow shares one content directory and uses a separate entry config and output directory for each site.
+This guide uses two fictional products, Payments and Reporting, to show independent releases. They're example names you replace with your own product IDs and labels.
 
-## Choose which versions exist
+A Git branch or tag chooses *which revision of the repository to build*; it doesn't automatically create a documentation version. See [publish separate docs sites from Git](https://www.shoalrun.com/publish/revisions.md) for that workflow. For audience or region selection using facets, see [build sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md).
 
-This config publishes two versions at `/v1` and `/v2`:
+## Version products independently
+
+Since 0.1.0-alpha.18
+
+Declare each product under `publications.products`. In this example, Payments has v2 and v3, while Reporting has only v1:
+
+```yaml title="docs.config.yaml (fragment)"
+publications:
+  defaults: { channel: production, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  products:
+    payments:
+      label: Payments
+      pathPrefix: /payments
+      defaultVersion: v3
+      versions:
+        v2: { pathPrefix: /v2 }
+        v3: { pathPrefix: /v3 }
+    reporting:
+      label: Reporting
+      pathPrefix: /reporting
+      defaultVersion: v1
+      versions:
+        v1: { pathPrefix: /v1 }
+  enabled:
+    - { product: payments, channel: production, version: v2 }
+    - { product: payments, channel: production, version: v3 }
+    - { product: reporting, channel: production, version: v1 }
+```
+
+A product publication includes `product`, `channel`, `version`, and `language`. Product IDs and version names are separate: Reporting doesn't acquire v3 because Payments has that version. A [customer profile](https://www.shoalrun.com/publish/deployment-profiles.md) can select Payments v3 with Reporting v1; another can select Payments v2 with the same Reporting release.
+
+### Assign a page to a product release
+
+Set the product and version in the page's frontmatter:
+
+```yaml title="content/payments/start.mdx (frontmatter fragment)"
+product: payments
+channel: production
+version: v3
+language: en
+slug: /start
+```
+
+With the catalog above, these page coordinates produce separate routes:
+
+| Product     | Version | Page slug | Published route       |
+| ----------- | ------- | --------- | --------------------- |
+| `payments`  | `v2`    | `/start`  | `/payments/v2/start`  |
+| `payments`  | `v3`    | `/start`  | `/payments/v3/start`  |
+| `reporting` | `v1`    | `/start`  | `/reporting/v1/start` |
+
+The product catalog permits these releases; it doesn't create their pages. Add source pages or explicit memberships for each route you want to publish.
+
+Route prefixes are ordered as site base path, nondefault language, product, channel, version, then slug. Omitting a product page's version uses that product's `defaultVersion`; a valid `publications.defaults.version` overrides it only when `defaults.product` names that same product. An inherited global frontmatter version isn't a product default.
+
+### Share a page across products
+
+To reuse a source across products, list the full memberships explicitly:
+
+```yaml title="Shared page frontmatter (fragment)"
+publications:
+  - { product: payments, channel: production, version: v3 }
+  - { product: reporting, channel: production, version: v1 }
+```
+
+Don't also set page-level `product`, `channel`, or `version`. Keep one stable document ID and document type across these publications. `<ForPublication product="payments" version="v3">` can select a product-specific section. A `shared: true` feature classification doesn't publish a page into other products; it controls [customer feature selection](https://www.shoalrun.com/publish/deployment-profiles.md).
+
+### Link between products
+
+Ordinary `doc:` links, navigation, and version choices stay in the current product publication. To link deliberately across products, name the destination product and version:
+
+```mdx
+<DocLink doc="guide.start" product="reporting" version="v1">Start reporting</DocLink>
+```
+
+The link inherits the current channel and language unless you specify them. Its destination must be included in the selected build. Search and agent reads use product-qualified publications too; they don't substitute another product's similarly named version.
+
+### Migrate existing product metadata
+
+Without `publications.products`, `frontmatter.product` remains category metadata and an optional reader facet. Declaring a product catalog opts into publication identity: existing product values must name declared products, and each product's versions need their own catalog. Root `publications.versions` can remain for productless site pages; omit it when all enabled publications have products. Productless pages aren't automatically copied into product publications.
+
+Review existing product values, move the relevant version definitions into each catalog, and add product coordinates to enabled publications and page memberships. Rebuild and check routes, links, navigation, search, and exports. Product prefixes change URLs; add [redirects](https://www.shoalrun.com/config/publishing.md) for old published paths.
+
+## Publish versions without a product catalog
+
+If your site doesn't need independent products, use a root version catalog. This config publishes two versions at `/v1` and `/v2`:
 
 ```yaml title="docs.config.yaml (fragment)"
 publications:
@@ -42,7 +129,7 @@ publications:
     - { channel: production, version: v2, language: en }
 ```
 
-`enabled` sets the combinations the build may publish. It does not create pages or fill gaps in them. The paths come from the prefixes above plus each page's `slug`.
+`enabled` sets the combinations the build may publish. It doesn't create pages or fill gaps in them. The paths come from the prefixes above plus each page's `slug`.
 
 ## Keep an unchanged page in one file
 
@@ -65,7 +152,7 @@ access: { policy: public }
 Install the client and create a project.
 ```
 
-The `publications` list is explicit: add a version when the page should appear there, and omit it when the page should not. Only enabled combinations are built. Keep the same `id` and `slug` in every publication so links and the Version menu can find the corresponding page. A shared file cannot also set page-level `channel` or `version`.
+The `publications` list is explicit: add a version when the page should appear there, and omit it when the page shouldn't. Only enabled combinations are built. Keep the same `id` and `slug` in every publication so links and the Version menu can find the corresponding page. A shared file can't also set page-level `channel` or `version`; product publications also exclude page-level `product`.
 
 ## Change just one part of a shared page
 
@@ -87,9 +174,9 @@ Use a scoped key. [Set permissions](doc:guide.permissions)
 </ForPublication>
 ```
 
-You can select a `channel`, `version`, `language`, or a combination, such as `<ForPublication channel="sandbox" version="v2">`. Omitted attributes match any value. The block needs at least one attribute and ordinary block content. A `doc:` link inside a block resolves in that publication, so a v2-only target can live in a v2-only block.
+You can select a `product`, `channel`, `version`, `language`, or a combination, such as `<ForPublication product="payments" version="v3">`. Product selection requires a product catalog. Omitted attributes match any value. The block needs at least one attribute and ordinary block content. A `doc:` link inside a block resolves in that publication, so a v2-only target can live in a v2-only block.
 
-If a whole page changes substantially, write separate source files with the same `id` and `slug`, each with its own `channel` and `version`. If a page exists only in v2, write only its v2 file. You do not need a blank v1 copy. The Version menu shows a matching page only where one was published.
+If a whole page changes substantially, write separate source files with the same `id` and `slug`, each with its own `channel` and `version`. If a page exists only in v2, write only its v2 file. You don't need a blank v1 copy. The Version menu shows a matching page only where one was published.
 
 | Source choice                                              | Result                                                                  |
 | ---------------------------------------------------------- | ----------------------------------------------------------------------- |
@@ -102,17 +189,19 @@ Run `shoalrun build docs.config.yaml dist` and inspect `dist/documents.json` for
 
 ## Give each API version its own contract
 
-When API behavior differs by version, bind an OpenAPI file to each publication in `apis.<name>.publications`. The top-level API `source` belongs to `publications.defaults`. A shared guide can refer to the same stable operation ID in both versions; each version resolves that operation against its own API source. The build fails if a page needs an API operation but that publication has no source. See [API references](https://www.shoalrun.com/publish/api-references.md) for the config and [example configs](https://www.shoalrun.com/config/examples.md) for full projects.
+When API behavior differs by version, bind an OpenAPI file to each publication in `apis.<name>.publications`. The top-level API `source` belongs to `publications.defaults`. With product publications in `0.1.0-alpha.18`, add `product` to each API publication binding; a top-level API `product` scopes its default source to that product. OpenAPI sources are shared across documentation languages within a product, channel, and version, and a published full source is emitted once for those translations. A shared guide can refer to the same stable operation ID in both versions; each version resolves that operation against its own API source. The build fails if a page needs an API operation but that publication has no source. See [API references](https://www.shoalrun.com/publish/api-references.md) for the config and [example configs](https://www.shoalrun.com/config/examples.md) for full projects.
 
 ## What agents receive
 
-Each published page has a Markdown copy at its route plus `.md`, such as `/v1/start.md` and `/v2/start.md`. These are separate artifacts built from the same source file. Each copy includes only its own `<ForPublication>` sections, so an agent reading v1 instructions does not see v2-only text. `documents.json`, `search-index.json`, and the site's agent discovery files list the published variants and their Markdown URLs. A missing version of a page has no Markdown copy or search result. [Published outputs](https://www.shoalrun.com/publish/output.md) lists those files.
+Sites with product catalogs provide a native publication dropdown grouped by product in HTML. It includes only published choices; language labels appear only when multiple languages are available. Selecting a choice uses browser JavaScript, with ordinary links available when JavaScript is disabled. Native keyboard interaction follows the browser's select control. Markdown retains each selected page and its links without a dropdown.
+
+Each published page has a Markdown copy at its route plus `.md`, such as `/payments/v3/start.md` and `/reporting/v1/start.md` for the product example above. These are separate artifacts built from the same source file. Each copy includes only its own `<ForPublication>` sections, so an agent reading v1 instructions doesn't see v2-only text. `documents.json`, `search-index.json`, and the site's agent discovery files list the published variants and their Markdown URLs. A missing version of a page has no Markdown copy or search result. [Published outputs](https://www.shoalrun.com/publish/output.md) lists those files.
 
 For channel and prefix rules, see the [publication configuration reference](https://www.shoalrun.com/config.md).
 
 ## Add a language
 
-To add a language such as Japanese, add its combination to `enabled`, then write a translated file for each page with that `language`. The translated file reuses the page's `id` and `slug`, so it is another language of the same page:
+To add a language such as Japanese, add its combination to `enabled`, then write a translated file for each page with that `language`. The translated file reuses the page's `id` and `slug`, so it's another language of the same page:
 
 ```yaml title="docs.config.yaml"
 publications:
@@ -138,7 +227,7 @@ language: ja
 
 The Japanese page publishes at `/ja/install` with `lang="ja"`, and its Markdown copy is `/ja/install.md`. The default language keeps the ordinary route. Pages without a `language` are in the default language.
 
-Shoalrun does not translate text. Your translation pipeline writes the files, one for each page and language. A page with no Japanese file has no Japanese version, and it gets no Markdown copy or search result there. To keep a language out of a build, leave it out of `enabled`.
+Shoalrun doesn't translate text. Your translation pipeline writes the files, one for each page and language. A page with no Japanese file has no Japanese version, and it gets no Markdown copy or search result there. To keep a language out of a build, leave it out of `enabled`.
 
 ## Related reading
 

package/agent-docs/publish/publications.sections/add-a-language.md

@@ -0,0 +1,60 @@
+---
+id: guide.publications
+title: Share pages across products and documentation versions
+summary: Configure independent product versioning and reuse pages across
+  releases, channels, and languages.
+type: how-to
+area: publishing
+subarea: publishing-versions
+canonical: /publish/publications
+---
+
+# Share pages across products and documentation versions
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Products, versions, and languages
+
+**Updated: 2026-11-05.**
+
+Parent page: [Full Markdown page](/publish/publications.md)
+
+Publish documentation for different releases, channels, and languages from one content source. Keep common instructions in one file and select the content that changes between publications. If you document multiple products, each can have its own versions and defaults.
+
+A **publication** identifies a product, channel, version, and language. For a site without product catalogs, it identifies just channel, version, and language. These coordinates determine which page variant readers and agents receive, including its route, links, and search scope.
+
+This guide uses two fictional products, Payments and Reporting, to show independent releases. They're example names you replace with your own product IDs and labels.
+
+A Git branch or tag chooses *which revision of the repository to build*; it doesn't automatically create a documentation version. See [publish separate docs sites from Git](https://www.shoalrun.com/publish/revisions.md) for that workflow. For audience or region selection using facets, see [build sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md).
+
+## Add a language
+
+To add a language such as Japanese, add its combination to `enabled`, then write a translated file for each page with that `language`. The translated file reuses the page's `id` and `slug`, so it's another language of the same page:
+
+```yaml title="docs.config.yaml"
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+    - { channel: production, version: current, language: ja }
+```
+
+```yaml title="content/install.ja.mdx"
+---
+id: guide.install
+title: インストール
+summary: Acme のコマンドラインツールをインストールします。
+slug: /install
+language: ja
+---
+```
+
+The Japanese page publishes at `/ja/install` with `lang="ja"`, and its Markdown copy is `/ja/install.md`. The default language keeps the ordinary route. Pages without a `language` are in the default language.
+
+Shoalrun doesn't translate text. Your translation pipeline writes the files, one for each page and language. A page with no Japanese file has no Japanese version, and it gets no Markdown copy or search result there. To keep a language out of a build, leave it out of `enabled`.

package/agent-docs/publish/publications.sections/change-just-one-part-of-a-shared-page.md

@@ -0,0 +1,63 @@
+---
+id: guide.publications
+title: Share pages across products and documentation versions
+summary: Configure independent product versioning and reuse pages across
+  releases, channels, and languages.
+type: how-to
+area: publishing
+subarea: publishing-versions
+canonical: /publish/publications
+---
+
+# Share pages across products and documentation versions
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Products, versions, and languages
+
+**Updated: 2026-11-05.**
+
+Parent page: [Full Markdown page](/publish/publications.md)
+
+Publish documentation for different releases, channels, and languages from one content source. Keep common instructions in one file and select the content that changes between publications. If you document multiple products, each can have its own versions and defaults.
+
+A **publication** identifies a product, channel, version, and language. For a site without product catalogs, it identifies just channel, version, and language. These coordinates determine which page variant readers and agents receive, including its route, links, and search scope.
+
+This guide uses two fictional products, Payments and Reporting, to show independent releases. They're example names you replace with your own product IDs and labels.
+
+A Git branch or tag chooses *which revision of the repository to build*; it doesn't automatically create a documentation version. See [publish separate docs sites from Git](https://www.shoalrun.com/publish/revisions.md) for that workflow. For audience or region selection using facets, see [build sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md).
+
+## Change just one part of a shared page
+
+Put version-specific content inside `<ForPublication>`. The rest of the page stays shared:
+
+```mdx
+Create a project, then choose a credential.
+
+<ForPublication version="v1">
+
+Use a legacy key.
+
+</ForPublication>
+
+<ForPublication version="v2">
+
+Use a scoped key. [Set permissions](doc:guide.permissions)
+
+</ForPublication>
+```
+
+You can select a `product`, `channel`, `version`, `language`, or a combination, such as `<ForPublication product="payments" version="v3">`. Product selection requires a product catalog. Omitted attributes match any value. The block needs at least one attribute and ordinary block content. A `doc:` link inside a block resolves in that publication, so a v2-only target can live in a v2-only block.
+
+If a whole page changes substantially, write separate source files with the same `id` and `slug`, each with its own `channel` and `version`. If a page exists only in v2, write only its v2 file. You don't need a blank v1 copy. The Version menu shows a matching page only where one was published.
+
+| Source choice                                              | Result                                                                  |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------- |
+| One file listing v1 and v2                                 | The same page appears at both paths.                                    |
+| One file listing v1 and v2, with `<ForPublication>` blocks | Shared text appears in both; each version gets its own selected blocks. |
+| Two files with the same ID, one for each version           | Each version gets different page content.                               |
+| One file assigned only to v2                               | The page appears only in v2.                                            |
+
+Run `shoalrun build docs.config.yaml dist` and inspect `dist/documents.json` for the actual pages and routes. Links, navigation, search, and the Version menu use those published variants. A link to a page missing from the current publication fails the build instead of sending readers to another version.

package/agent-docs/publish/publications.sections/give-each-api-version-its-own-contract.md

@@ -0,0 +1,34 @@
+---
+id: guide.publications
+title: Share pages across products and documentation versions
+summary: Configure independent product versioning and reuse pages across
+  releases, channels, and languages.
+type: how-to
+area: publishing
+subarea: publishing-versions
+canonical: /publish/publications
+---
+
+# Share pages across products and documentation versions
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Products, versions, and languages
+
+**Updated: 2026-11-05.**
+
+Parent page: [Full Markdown page](/publish/publications.md)
+
+Publish documentation for different releases, channels, and languages from one content source. Keep common instructions in one file and select the content that changes between publications. If you document multiple products, each can have its own versions and defaults.
+
+A **publication** identifies a product, channel, version, and language. For a site without product catalogs, it identifies just channel, version, and language. These coordinates determine which page variant readers and agents receive, including its route, links, and search scope.
+
+This guide uses two fictional products, Payments and Reporting, to show independent releases. They're example names you replace with your own product IDs and labels.
+
+A Git branch or tag chooses *which revision of the repository to build*; it doesn't automatically create a documentation version. See [publish separate docs sites from Git](https://www.shoalrun.com/publish/revisions.md) for that workflow. For audience or region selection using facets, see [build sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md).
+
+## Give each API version its own contract
+
+When API behavior differs by version, bind an OpenAPI file to each publication in `apis.<name>.publications`. The top-level API `source` belongs to `publications.defaults`. With product publications in `0.1.0-alpha.18`, add `product` to each API publication binding; a top-level API `product` scopes its default source to that product. OpenAPI sources are shared across documentation languages within a product, channel, and version, and a published full source is emitted once for those translations. A shared guide can refer to the same stable operation ID in both versions; each version resolves that operation against its own API source. The build fails if a page needs an API operation but that publication has no source. See [API references](https://www.shoalrun.com/publish/api-references.md) for the config and [example configs](https://www.shoalrun.com/config/examples.md) for full projects.

package/agent-docs/publish/publications.sections/keep-an-unchanged-page-in-one-file.md

@@ -0,0 +1,53 @@
+---
+id: guide.publications
+title: Share pages across products and documentation versions
+summary: Configure independent product versioning and reuse pages across
+  releases, channels, and languages.
+type: how-to
+area: publishing
+subarea: publishing-versions
+canonical: /publish/publications
+---
+
+# Share pages across products and documentation versions
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Products, versions, and languages
+
+**Updated: 2026-11-05.**
+
+Parent page: [Full Markdown page](/publish/publications.md)
+
+Publish documentation for different releases, channels, and languages from one content source. Keep common instructions in one file and select the content that changes between publications. If you document multiple products, each can have its own versions and defaults.
+
+A **publication** identifies a product, channel, version, and language. For a site without product catalogs, it identifies just channel, version, and language. These coordinates determine which page variant readers and agents receive, including its route, links, and search scope.
+
+This guide uses two fictional products, Payments and Reporting, to show independent releases. They're example names you replace with your own product IDs and labels.
+
+A Git branch or tag chooses *which revision of the repository to build*; it doesn't automatically create a documentation version. See [publish separate docs sites from Git](https://www.shoalrun.com/publish/revisions.md) for that workflow. For audience or region selection using facets, see [build sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md).
+
+## Keep an unchanged page in one file
+
+List the versions that should receive the page in its frontmatter. This one file creates `/v1/start` and `/v2/start`:
+
+```mdx title="content/start.mdx"
+---
+id: guide.start
+title: Get started
+summary: Set up your first request.
+type: guide
+slug: /start
+publications:
+  - { channel: production, version: v1 }
+  - { channel: production, version: v2 }
+language: en
+access: { policy: public }
+---
+
+Install the client and create a project.
+```
+
+The `publications` list is explicit: add a version when the page should appear there, and omit it when the page shouldn't. Only enabled combinations are built. Keep the same `id` and `slug` in every publication so links and the Version menu can find the corresponding page. A shared file can't also set page-level `channel` or `version`; product publications also exclude page-level `product`.