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

package/agent-docs/publish/publications.sections/publish-versions-without-a-product-catalog.md

@@ -0,0 +1,49 @@
+---
+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).
+
+## 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:
+  defaults: { channel: production, version: v1, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    v1: { pathPrefix: /v1 }
+    v2: { pathPrefix: /v2 }
+  enabled:
+    - { channel: production, version: v1, language: en }
+    - { channel: production, version: v2, language: en }
+```
+
+`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`.

package/agent-docs/publish/publications.sections/related-reading.md

@@ -0,0 +1,42 @@
+---
+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).
+
+## Related reading
+
+### Reference while working
+
+- [Configuration reference](https://www.shoalrun.com/config.md) — Look up publication defaults and route prefixes.
+
+### Related topics
+
+- [Use Git branches for separate docs sites](https://www.shoalrun.com/publish/revisions.md) — Distinguish content editions from source revisions and retained builds.
+
+- [Build separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md) — Publish separate sites from one content source using facet selections.

package/agent-docs/publish/publications.sections/version-products-independently.md

@@ -0,0 +1,115 @@
+---
+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).
+
+## 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.

package/agent-docs/publish/publications.sections/what-agents-receive.md

@@ -0,0 +1,38 @@
+---
+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).
+
+## What agents receive
+
+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).

package/agent-docs/publish/revisions.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Use Git branches for separate docs sites
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 A deployment takes the docs files from a Git branch or commit, builds them, and serves the result at an address you choose. Your host or CI service chooses the source and destination. Branch names have no special meaning to Shoalrun.
 
@@ -42,7 +42,7 @@ After the deployment job checks out its chosen source, build it with the full co
 shoalrun build docs.config.yaml site-dist --source-commit "$(git rev-parse HEAD)"
 ```
 
-Deploy all of `site-dist/` to the address assigned to that source. Configure this source-to-address rule in your host or CI service; Shoalrun does not deploy files or infer a branch from `channel`. See [deploy your documentation](https://www.shoalrun.com/publish.md) for hosting options. If two separate domains should both serve `/start`, use an empty channel `pathPrefix` in each site's config.
+Deploy all of `site-dist/` to the address assigned to that source. Configure this source-to-address rule in your host or CI service; Shoalrun doesn't deploy files or infer a branch from `channel`. See [deploy your documentation](https://www.shoalrun.com/publish.md) for hosting options. If two separate domains should both serve `/start`, use an empty channel `pathPrefix` in each site's config.
 
 ## Add another site to the Version menu
 
@@ -73,7 +73,7 @@ A `baseUrl` with a path changes where the menu points. Hosting a *whole standalo
 
 ## What agents receive
 
-Each deployed site has its own Markdown pages, `documents.json`, search index, and agent discovery files, built from that site's selected Git revision. An agent using the stable site reads its stable artifacts; an agent using the next site reads its next artifacts. The external Version menu helps human readers navigate between sites, but it does not combine their manifests or Markdown copies. Preserve a built release or its tagged source if agents must be able to consult it later. See [published outputs](https://www.shoalrun.com/publish/output.md) for the file list.
+Each deployed site has its own Markdown pages, `documents.json`, search index, and agent discovery files, built from that site's selected Git revision. An agent using the stable site reads its stable artifacts; an agent using the next site reads its next artifacts. The external Version menu helps human readers navigate between sites, but it doesn't combine their manifests or Markdown copies. Preserve a built release or its tagged source if agents must be able to consult it later. See [published outputs](https://www.shoalrun.com/publish/output.md) for the file list.
 
 ## Check the deployed source
 
@@ -97,7 +97,7 @@ The checker fails if the address serves a different commit or if its published H
 
 ### Related topics
 
-- [Share pages across documentation versions](https://www.shoalrun.com/publish/publications.md) — Distinguish content editions from source revisions and retained builds.
+- [Share pages across products and documentation versions](https://www.shoalrun.com/publish/publications.md) — Distinguish content editions from source revisions and retained builds.
 
 ### Often confused with
 

package/agent-docs/publish/seo.md

@@ -17,9 +17,9 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > SEO and social previews
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
-When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
+When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you don't need to hand-write Open Graph or Twitter tags.
 
 ## Set the public address
 
@@ -31,7 +31,7 @@ site:
   origin: https://docs.acme.com
 ```
 
-Check the domain in the built `og:image` URL. A page may display in a browser while its social preview cannot load an image from that domain. Preview deployments behind sign-in cannot be unfurled by a public crawler. [Publish on Vercel](https://www.shoalrun.com/publish/vercel.md) explains the production and preview origins for this site's build.
+Check the domain in the built `og:image` URL. A page may display in a browser while its social preview can't load an image from that domain. Preview deployments behind sign-in can't be unfurled by a public crawler. [Publish on Vercel](https://www.shoalrun.com/publish/vercel.md) explains the production and preview origins for this site's build.
 
 ## Write the page title and summary
 
@@ -94,9 +94,9 @@ site:
     history: ./config/content-updates.json
 ```
 
-The history file must be inside the project and its parent directory must already exist. The first successful build seeds each page with its declared `updated`, then `site.updated`, then today's UTC date. Later builds compare the resolved HTML and Markdown content plus displayed page metadata. Unchanged content keeps its recorded Updated date; changed content receives today's UTC date. File touches, AST source positions, and changes to verification dates do not change the content digest. The history is written after a successful build. Commit it with the source so clean CI builds use the same history. Without that file, the next build seeds a new history from declared dates.
+The history file must be inside the project and its parent directory must already exist. The first successful build seeds each page with its declared `updated`, then `site.updated`, then today's UTC date. Later builds compare the resolved HTML and Markdown content plus displayed page metadata. Unchanged content keeps its recorded Updated date; changed content receives today's UTC date. File touches, AST source positions, and changes to verification dates don't change the content digest. The history is written after a successful build. Commit it with the source so clean CI builds use the same history. Without that file, the next build seeds a new history from declared dates.
 
-The manifest records `contentDigest` for this comparison and `digest` for the complete generated Markdown. A Markdown date or metadata edit changes the latter; it does not necessarily change the technical content fingerprint.
+The manifest records `contentDigest` for this comparison and `digest` for the complete generated Markdown. A Markdown date or metadata edit changes the latter; it doesn't necessarily change the technical content fingerprint.
 
 ### Record verification separately
 
@@ -106,9 +106,9 @@ Set native frontmatter `verified` only when someone checks the page's technical
 verified: 2026-10-01
 ```
 
-The standard HTML page header displays `Verified` with a semantic `<time>` element. Markdown and `documents.json` expose the same date independently of `Updated`, which records content revision. A build never assigns `verified`; a build or editorial review alone does not establish technical verification.
+The standard HTML page header displays `Verified` with a semantic `<time>` element. Markdown and `documents.json` expose the same date independently of `Updated`, which records content revision. A build never assigns `verified`; a build or editorial review alone doesn't establish technical verification.
 
-The HTML verification-date display and `showVerified` setting are available since `0.1.0-alpha.13`.
+The HTML verification-date display and `showVerified` setting: Since 0.1.0-alpha.13
 
 Set `showVerified: false` in a page's frontmatter to hide the verification date in HTML only. It remains in Markdown and the manifest. The default is `true`. To hide it throughout a project, set a shared default:
 
@@ -118,15 +118,15 @@ frontmatter:
     showVerified: false
 ```
 
-An individual page can override that default with `showVerified: true`. A page using a Hero replaces the standard header, so its header dates are not displayed.
+An individual page can override that default with `showVerified: true`. A page using a Hero replaces the standard header, so its header dates aren't displayed.
 
 This project also declares private `editorial.lastVerified` and `editorial.verificationNote` fields for internal review notes; use native `verified` when the date should be public. A rebuild or unchanged-content file touch establishes neither a content change nor verification.
 
-Search indexing still depends on the public host and crawler access; metadata alone does not guarantee it. If Slack does not unfurl after a corrected deployment, confirm the page and image are public, then try sharing the link in a new conversation. [Slack may omit a preview](https://slack.com/help/articles/204399343-Share-links-and-set-preview-preferences) when the same link was recently posted in that conversation.
+Search indexing still depends on the public host and crawler access; metadata alone doesn't guarantee it. If Slack doesn't unfurl after a corrected deployment, confirm the page and image are public, then try sharing the link in a new conversation. [Slack may omit a preview](https://slack.com/help/articles/204399343-Share-links-and-set-preview-preferences) when the same link was recently posted in that conversation.
 
 ## What agents receive
 
-The social tags are in HTML, and each generated share card is a public PNG. Agents reading Markdown get the authored title, body, and fields published by your [Markdown metadata settings](https://www.shoalrun.com/author/markdown-metadata.md). The Markdown body does not contain HTML meta tags. `documents.json` and `search-index.json` list the published page and its routes. Changing `seo.title` or the share image does not replace a clear page title or summary for agents that use the Markdown and search index. The [agent-friendly documentation guide](https://www.shoalrun.com/publish/agent-friendliness.md) explains how these public files differ from the documentation bundle shipped inside Shoalrun's CLI.
+The social tags are in HTML, and each generated share card is a public PNG. Agents reading Markdown get the authored title, body, and fields published by your [Markdown metadata settings](https://www.shoalrun.com/author/markdown-metadata.md). The Markdown body doesn't contain HTML meta tags. `documents.json` and `search-index.json` list the published page and its routes. Changing `seo.title` or the share image doesn't replace a clear page title or summary for agents that use the Markdown and search index. The [agent-friendly documentation guide](https://www.shoalrun.com/publish/agent-friendliness.md) explains how these public files differ from the documentation bundle shipped inside Shoalrun's CLI.
 
 ## Related reading
 

package/agent-docs/publish/seo.sections/related-reading.md

@@ -17,11 +17,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > SEO and social previews
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/seo.md)
 
-When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
+When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you don't need to hand-write Open Graph or Twitter tags.
 
 ## Related reading
 

package/agent-docs/publish/seo.sections/set-the-public-address.md

@@ -17,11 +17,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > SEO and social previews
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/seo.md)
 
-When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
+When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you don't need to hand-write Open Graph or Twitter tags.
 
 ## Set the public address
 
@@ -33,4 +33,4 @@ site:
   origin: https://docs.acme.com
 ```
 
-Check the domain in the built `og:image` URL. A page may display in a browser while its social preview cannot load an image from that domain. Preview deployments behind sign-in cannot be unfurled by a public crawler. [Publish on Vercel](https://www.shoalrun.com/publish/vercel.md) explains the production and preview origins for this site's build.
+Check the domain in the built `og:image` URL. A page may display in a browser while its social preview can't load an image from that domain. Preview deployments behind sign-in can't be unfurled by a public crawler. [Publish on Vercel](https://www.shoalrun.com/publish/vercel.md) explains the production and preview origins for this site's build.

package/agent-docs/publish/seo.sections/what-agents-receive.md

@@ -17,12 +17,12 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > SEO and social previews
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/seo.md)
 
-When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
+When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you don't need to hand-write Open Graph or Twitter tags.
 
 ## What agents receive
 
-The social tags are in HTML, and each generated share card is a public PNG. Agents reading Markdown get the authored title, body, and fields published by your [Markdown metadata settings](https://www.shoalrun.com/author/markdown-metadata.md). The Markdown body does not contain HTML meta tags. `documents.json` and `search-index.json` list the published page and its routes. Changing `seo.title` or the share image does not replace a clear page title or summary for agents that use the Markdown and search index. The [agent-friendly documentation guide](https://www.shoalrun.com/publish/agent-friendliness.md) explains how these public files differ from the documentation bundle shipped inside Shoalrun's CLI.
+The social tags are in HTML, and each generated share card is a public PNG. Agents reading Markdown get the authored title, body, and fields published by your [Markdown metadata settings](https://www.shoalrun.com/author/markdown-metadata.md). The Markdown body doesn't contain HTML meta tags. `documents.json` and `search-index.json` list the published page and its routes. Changing `seo.title` or the share image doesn't replace a clear page title or summary for agents that use the Markdown and search index. The [agent-friendly documentation guide](https://www.shoalrun.com/publish/agent-friendliness.md) explains how these public files differ from the documentation bundle shipped inside Shoalrun's CLI.

package/agent-docs/publish/seo.sections/what-the-build-adds.md

@@ -17,11 +17,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > SEO and social previews
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/seo.md)
 
-When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
+When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you don't need to hand-write Open Graph or Twitter tags.
 
 ## What the build adds
 

package/agent-docs/publish/seo.sections/write-the-page-title-and-summary.md

@@ -17,11 +17,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > SEO and social previews
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/seo.md)
 
-When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
+When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you don't need to hand-write Open Graph or Twitter tags.
 
 ## Write the page title and summary
 

package/agent-docs/publish/single-source-sites.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Build separate sites from shared content
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 You can keep one content directory and build separate sites for any configured facet: audience, product, area, subarea, or a custom facet such as region. Each entry config can have its own origin, base path, branding, navigation, and output directory. A developer portal is one example; the same workflow applies to an operations site, a product site, or regional resources.
 
@@ -127,7 +127,7 @@ navigation:
 
 Every selected facet must match. Choices within one facet are alternatives: `{ audience: [developer, operator], region: [eu] }` requires either audience and the European region. A page without a mark for a selected facet is excluded. Mark shared pages with all applicable values rather than leaving them unmarked. Unknown facets or choices, empty selections, and selections with no published pages fail the build.
 
-The selector does not rewrite publication metadata. Public access, enabled publications, and language still determine eligibility. Keep explicit navigation and page links within the selected set; missing targets fail validation rather than copying excluded pages into the output. Separate entry configs can replace inherited navigation lists.
+The selector doesn't rewrite publication metadata. Public access, enabled publications, and language still determine eligibility. Keep explicit navigation and page links within the selected set; missing targets fail validation rather than copying excluded pages into the output. Separate entry configs can replace inherited navigation lists.
 
 ## Build and check each output
 
@@ -141,9 +141,9 @@ shoalrun build europe.config.yaml dist/europe
 
 Check each output's `documents.json` for its page IDs and routes. The main site contains all three pages. The developer site contains the overview and API guide. The European site contains the overview and operations guide beneath `/resources`. Inspect HTML, Markdown, search indexes, `llms.min.txt`, and the sitemap to confirm that excluded pages have no published entries or files. The runnable `faceted-sites` example ships with the framework's example configurations.
 
-Deploy each output separately to its configured host. Building one site does not update the others. After editing shared content, rebuild and deploy every affected site. Keep output directories separate from sources and from one another because a successful build replaces its output directory.
+Deploy each output separately to its configured host. Building one site doesn't update the others. After editing shared content, rebuild and deploy every affected site. Keep output directories separate from sources and from one another because a successful build replaces its output directory.
 
-Selection applies to whole authored and generated pages before rendering. A selected page retains its complete body, including reader-marked sections in HTML and Markdown. Browser reader controls cannot restore excluded pages. Section variants can use [publication blocks](https://www.shoalrun.com/publish/publications.md) where the sites also have distinct publications.
+Selection applies to whole authored and generated pages before rendering. A selected page retains its complete body, including reader-marked sections in HTML and Markdown. Browser reader controls can't restore excluded pages. Section variants can use [publication blocks](https://www.shoalrun.com/publish/publications.md) where the sites also have distinct publications.
 
 Configure API sources and operation selection separately. A published OpenAPI source may contain operations beyond the selected reference pages. Generated references use their resolved facet marks, including `readerFilters.typeDefaults`. This setting is a page publication selector, not authorization for private content; protect private deployments at the host.
 
@@ -163,6 +163,6 @@ For a help drawer or another application surface, [export the shared content](ht
 
 ### Related topics
 
-- [Share pages across documentation versions](https://www.shoalrun.com/publish/publications.md) — Publish separate sites from one content source using facet selections.
+- [Share pages across products and documentation versions](https://www.shoalrun.com/publish/publications.md) — Publish separate sites from one content source using facet selections.
 
 - [Export content into your application](https://www.shoalrun.com/publish/content-export.md) — Reuse the same authored content inside an application.

package/agent-docs/publish/troubleshooting.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Troubleshooting
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Run these commands from your documentation project, with Shoalrun installed as in the [quickstart](https://www.shoalrun.com/start.md). Start by rebuilding so the error names the current source file:
 
@@ -44,7 +44,7 @@ node -e 'const m = require("./dist/documents.json"); console.log(JSON.stringify(
 
 Check the page's resolved `access.policy` is `public` and its channel, version, and language match an entry in `publications.enabled`. `frontmatter.enforced` overrides page values; a draft enforced there keeps even an explicitly public page out of the build. See [versions and languages](https://www.shoalrun.com/publish/publications.md).
 
-If the manifest contains the page but the menu does not, add its exact document ID to `navigation` (or the YAML file included there):
+If the manifest contains the page but the menu doesn't, add its exact document ID to `navigation` (or the YAML file included there):
 
 ```yaml
 navigation:
@@ -52,7 +52,7 @@ navigation:
     doc: guide.my-page
 ```
 
-Append that entry to the existing list. Scaffolding a file does not add it to navigation. A navigation reference to an unavailable page is omitted for that publication.
+Append that entry to the existing list. Scaffolding a file doesn't add it to navigation. A navigation reference to an unavailable page is omitted for that publication.
 
 If publishing instead fails with `unresolved scaffold placeholders cannot be published`, finish every scaffold TODO and replace the draft summary before setting `access: { policy: public }`.
 
@@ -64,19 +64,19 @@ If publishing instead fails with `unresolved scaffold placeholders cannot be pub
 
 ### What to do
 
-Check spelling against the target's `id`, its public access, and its publication fields. A source file in another version or language does not satisfy the link. Add the corresponding variant or link to an available page.
+Check spelling against the target's `id`, its public access, and its publication fields. A source file in another version or language doesn't satisfy the link. Add the corresponding variant or link to an available page.
 
-Use `doc:` plus a document ID for internal links, for example `[Install](doc:guide.install)`. File paths are not document IDs. Rebuild after correcting the source and target.
+Use `doc:` plus a document ID for internal links, for example `[Install](doc:guide.install)`. File paths aren't document IDs. Rebuild after correcting the source and target.
 
 ## Two pages claim one identity or route
 
 `Duplicate document identity` means two files have the same ID and publication combination. Keep one file per variant, or assign a distinct ID to a different page.
 
-`Route collision /install` means different pages produce the same final URL. Check their slugs together with language, channel, and version prefixes. `Output artifact collision` can also mean a page conflicts with a generated resource or another output file. Resolve the source configuration; changing the output directory does not fix conflicting URLs. [Versions and languages](https://www.shoalrun.com/publish/publications.md) shows how prefixes distinguish editions.
+`Route collision /install` means different pages produce the same final URL. Check their slugs together with language, channel, and version prefixes. `Output artifact collision` can also mean a page conflicts with a generated resource or another output file. Resolve the source configuration; changing the output directory doesn't fix conflicting URLs. [Versions and languages](https://www.shoalrun.com/publish/publications.md) shows how prefixes distinguish editions.
 
 ## MDX cannot compile
 
-`dynamic MDX expression has no semantic adapter` means the page contains JavaScript expressions that Shoalrun cannot project into its published formats. Replace executable MDX with Markdown or one of the [supported components](https://www.shoalrun.com/author/components.md). Put code intended for readers inside a fenced code block so it remains literal text.
+`dynamic MDX expression has no semantic adapter` means the page contains JavaScript expressions that Shoalrun can't project into its published formats. Replace executable MDX with Markdown or one of the [supported components](https://www.shoalrun.com/author/components.md). Put code intended for readers inside a fenced code block so it remains literal text.
 
 Component validation errors name the source file and component. Check the component's documented attributes and nesting. Ordinary MDX syntax errors can also come from unescaped braces or angle brackets in prose; use inline code for literal syntax.
 
@@ -89,17 +89,17 @@ API_REVIEW_DIR="$(mktemp -d)"
 npx --no-install shoalrun api review docs.config.yaml --output "$API_REVIEW_DIR"
 ```
 
-Inspect the candidate pages, contracts, source downloads, and input hashes. Copy the reported digest into that API's `publicReview.digest`, then run the normal build again. Source changes, selections, embeds, and source-publication choices can change the digest. Do not copy a digest from another project or bypass the review by publishing the candidate output. See [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md).
+Inspect the candidate pages, contracts, source downloads, and input hashes. Copy the reported digest into that API's `publicReview.digest`, then run the normal build again. Source changes, selections, embeds, and source-publication choices can change the digest. Don't copy a digest from another project or bypass the review by publishing the candidate output. See [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md).
 
 ## A diagram fails to render
 
 `failed to render mermaid diagram "Review flow"` (or `d2`) includes the source file and the renderer's underlying error. If it names diagram syntax, fix the code fence and rebuild. Errors such as `<Diagram> needs exactly one nonempty mermaid code fence` concern component structure; follow the [diagram reference](https://www.shoalrun.com/author/components/diagrams.md).
 
-Mermaid syntax renders with Pele; it does not need Chrome or Mermaid CLI. Check [Pele’s compatibility guide](https://pele.run/compatibility) if source from another Mermaid renderer fails. D2 uses the installed `@d2lang/d2` runtime. Reinstall framework dependencies if either renderer is missing. Include the source file, diagram title, and complete underlying error when reporting a failure.
+Mermaid syntax renders with Pele; it doesn't need Chrome or Mermaid CLI. Check [Pele’s compatibility guide](https://pele.run/compatibility) if source from another Mermaid renderer fails. D2 uses the installed `@d2lang/d2` runtime. Reinstall framework dependencies if either renderer is missing. Include the source file, diagram title, and complete underlying error when reporting a failure.
 
 ## Local output works but the deployed site fails
 
-A successful local build does not check the host's routing or headers. Use [Check a deployed site](https://www.shoalrun.com/publish/deployment-check.md) for wrong Markdown content types, missing negotiation, discovery resources, or 404 responses. The [publishing guide](https://www.shoalrun.com/publish.md) links the supported hosting workflows.
+A successful local build doesn't check the host's routing or headers. Use [Check a deployed site](https://www.shoalrun.com/publish/deployment-check.md) for wrong Markdown content types, missing negotiation, discovery resources, or 404 responses. The [publishing guide](https://www.shoalrun.com/publish.md) links the supported hosting workflows.
 
 ## Related reading
 

package/agent-docs/publish/vercel.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Publish on Vercel
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Shoalrun can produce a [Vercel Build Output API](https://vercel.com/docs/build-output-api) directory. It contains the compiled static site and routing rules for each published page. Vercel serves HTML to browsers and the generated Markdown twin when a request includes `Accept: text/markdown`. The route rules also set `Vary: Accept` and an HTTP `Link` header to the `.md` page. Explicit `.md` URLs remain available.
 
@@ -41,7 +41,7 @@ Set `site.origin` in `docs.config.yaml` to your intended public HTTPS origin bef
 npx --no-install shoalrun vercel build docs.config.yaml .vercel/output
 ```
 
-Generating output does not deploy it.
+Generating output doesn't deploy it.
 
 ## Configure the project
 
@@ -72,7 +72,7 @@ The card cache lives in the previous local `.vercel/output` bundle. The command
 
 ### Deploy without connecting GitHub
 
-You can keep building locally and deploy the Build Output API directory with the [Vercel CLI `--prebuilt` option](https://vercel.com/docs/cli/deploy#prebuilt). Use [`vercel link`](https://vercel.com/docs/cli/link) to connect the local directory to the existing Vercel project; this does not require importing your source repository. From the docs repository root, use `npm run docs:build-all` for Shoalrun's own site when you want fresh embeddings and answer cards. For another site, build its Vercel output as configured:
+You can keep building locally and deploy the Build Output API directory with the [Vercel CLI `--prebuilt` option](https://vercel.com/docs/cli/deploy#prebuilt). Use [`vercel link`](https://vercel.com/docs/cli/link) to connect the local directory to the existing Vercel project; this doesn't require importing your source repository. From the docs repository root, use `npm run docs:build-all` for Shoalrun's own site when you want fresh embeddings and answer cards. For another site, build its Vercel output as configured:
 
 ```sh
 npm run docs:vercel
@@ -80,7 +80,7 @@ vercel link
 vercel deploy --prebuilt --prod
 ```
 
-The command uploads `.vercel/output` and applies its routes and headers. A folder upload of `docs/dist` through Vercel Drop publishes the static files but does not apply Shoalrun's Vercel routing rules. It is suitable for a visual preview; the deployment checker will still report missing Markdown negotiation and response headers. Run it against the final domain after a prebuilt deploy.
+The command uploads `.vercel/output` and applies its routes and headers. A folder upload of `docs/dist` through Vercel Drop publishes the static files but doesn't apply Shoalrun's Vercel routing rules. It's suitable for a visual preview; the deployment checker will still report missing Markdown negotiation and response headers. Run it against the final domain after a prebuilt deploy.
 
 The routes also cover:
 
@@ -93,7 +93,7 @@ Each run of `vercel build` deletes and rewrites `.vercel/output/static/`, so don
 
 Enable `mcp` in your project config before running `shoalrun vercel build`. The output includes a separate Node function for the selected public publication, without requiring Ask or embeddings. See [connect an MCP client](https://www.shoalrun.com/publish/mcp.md) for configuration, host trust, limits, and the current verification status.
 
-MCP analytics remains off unless you also configure its [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md). If enabled, set its credentials on the function’s runtime environment. Browser analytics settings do not collect MCP traffic.
+MCP analytics remains off unless you also configure its [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md). If enabled, set its credentials on the function’s runtime environment. Browser analytics settings don't collect MCP traffic.
 
 ## Check the deployment
 

package/agent-docs/publish/vercel.sections/check-the-deployment.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Publish on Vercel
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/vercel.md)