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

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

@@ -17,7 +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 > Customer editions
 
-**Updated: 2026-11-03.**
+**Updated: 2026-11-05.**
+
+**Available since: 0.1.0-alpha.15.**
 
 Parent page: [Full Markdown page](/publish/deployment-profiles.md)
 
@@ -31,16 +33,14 @@ Parent page: [Full Markdown page](/publish/deployment-profiles.md)
 
 - [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) — Review the selected edition using captured HTML and Markdown. (Status: experimental.)
 
-Build a documentation edition for each customer from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles do not need to share a repository.
-
-By default, you do not need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
+Build a documentation edition for individual customers from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles don't need to share a repository with the content.
 
-Available since `0.1.0-alpha.15`.
+By default, you don't need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
 
 ## Check the result
 
 Inspect the edition's sidebar, selected pages, and shared sections. Then inspect its Markdown, search indexes, `documents.json`, and exports for the same selections. An excluded feature's content should be absent from the output files, rather than hidden by browser controls.
 
-A normal site build writes a private selection report at `.shoalrun/profile-selection.json`. It lists resolved features, grant sources, and inclusion decisions. Match its `buildId` to the output before treating it as a receipt for that output. The profile itself, its source filenames, and the report are not served as public metadata.
+A normal site build writes a private selection report at `.shoalrun/profile-selection.json`. It lists resolved features, grant sources, and inclusion decisions. Match its `buildId` to the output before treating it as a receipt for that output. The profile itself, its source filenames, and the report aren't served as public metadata.
 
-Affected pages excluded from the selected profile remain listed in validation coverage with a warning that their rendered content was not checked. Validate another profile that includes those pages before accepting their content changes.
+Affected pages excluded from the selected profile remain listed in validation coverage with a warning that their rendered content wasn't checked. Validate another profile that includes those pages before accepting their content changes.

package/agent-docs/publish/deployment-profiles.sections/choose-navigation-labels.md

@@ -17,7 +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 > Customer editions
 
-**Updated: 2026-11-03.**
+**Updated: 2026-11-05.**
+
+**Available since: 0.1.0-alpha.15.**
 
 Parent page: [Full Markdown page](/publish/deployment-profiles.md)
 
@@ -31,11 +33,9 @@ Parent page: [Full Markdown page](/publish/deployment-profiles.md)
 
 - [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) — Review the selected edition using captured HTML and Markdown. (Status: experimental.)
 
-Build a documentation edition for each customer from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles do not need to share a repository.
-
-By default, you do not need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
+Build a documentation edition for individual customers from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles don't need to share a repository with the content.
 
-Available since `0.1.0-alpha.15`.
+By default, you don't need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
 
 ## Choose navigation labels
 
@@ -50,4 +50,4 @@ navigation:
       - { id: connectors, doc: guide.connectors }
 ```
 
-`Product guides` is authored text. You can name this group `Your products`, `Reference`, or another label that suits your readers. The framework does not supply the words “Your products.” Profile selection removes ineligible destinations from the group; it does not rename the group or infer purchases from navigation labels.
+`Product guides` is authored text. You can name this group `Your products`, `Reference`, or another label that suits your readers. The framework doesn't supply the words “Your products.” Profile selection removes ineligible destinations from the group; it doesn't rename the group or infer purchases from navigation labels.

package/agent-docs/publish/deployment-profiles.sections/current-limits.md

@@ -17,7 +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 > Customer editions
 
-**Updated: 2026-11-03.**
+**Updated: 2026-11-05.**
+
+**Available since: 0.1.0-alpha.15.**
 
 Parent page: [Full Markdown page](/publish/deployment-profiles.md)
 
@@ -31,16 +33,14 @@ Parent page: [Full Markdown page](/publish/deployment-profiles.md)
 
 - [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) — Review the selected edition using captured HTML and Markdown. (Status: experimental.)
 
-Build a documentation edition for each customer from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles do not need to share a repository.
-
-By default, you do not need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
+Build a documentation edition for individual customers from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles don't need to share a repository with the content.
 
-Available since `0.1.0-alpha.15`.
+By default, you don't need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
 
 ## Current limits
 
 Profiled API builds reject full OpenAPI source publication. Set `source.publish: false` and `source.focused: true` for focused operation downloads. Generated operations can declare `x-shoalrun-requires`; API definitions and explicit bindings also accept `requires`. Generated references respect inherited frontmatter requirements.
 
-Operation embeds respect the selection. Standalone `<ApiSchema api="..." schema="..." />` embeds are not supported in profiled builds. Static `vercel build --profile FILE` is supported; profiled chat-function builds are not.
+Operation embeds respect the selection. Standalone `<ApiSchema api="..." schema="..." />` embeds aren't supported in profiled builds. Static `vercel build --profile FILE` is supported; profiled chat-function builds aren't.
 
-`dev` and checked-plan authoring do not yet accept deployment profiles. Use build/serve or captured validation/preview. Your deployment supplies the declared purchases and grants; Shoalrun does not query billing systems or expire entitlements. Protect private editions through host authentication.
+Checked-plan authoring doesn't accept deployment profiles. Use captured validation and preview for that workflow. Profile-aware development is described in the preview workflow above. Your deployment supplies the declared purchases and grants; Shoalrun doesn't query billing systems or expire entitlements. Protect private editions through host authentication.

package/agent-docs/publish/deployment-profiles.sections/define-the-shared-sku-manifest.md

@@ -17,7 +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 > Customer editions
 
-**Updated: 2026-11-03.**
+**Updated: 2026-11-05.**
+
+**Available since: 0.1.0-alpha.15.**
 
 Parent page: [Full Markdown page](/publish/deployment-profiles.md)
 
@@ -31,11 +33,9 @@ Parent page: [Full Markdown page](/publish/deployment-profiles.md)
 
 - [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) — Review the selected edition using captured HTML and Markdown. (Status: experimental.)
 
-Build a documentation edition for each customer from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles do not need to share a repository.
-
-By default, you do not need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
+Build a documentation edition for individual customers from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles don't need to share a repository with the content.
 
-Available since `0.1.0-alpha.15`.
+By default, you don't need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
 
 ## Define the shared SKU manifest
 
@@ -56,7 +56,7 @@ skus:
         features: [analytics, connectors]
 ```
 
-Retain historical revisions unchanged when packaging changes. An existing customer can continue using the original revision, or receive an explicit feature grant. Marking a feature `deprecated` or `retired` does not remove its documentation grant.
+Retain historical revisions unchanged when packaging changes. An existing customer can continue using the original revision, or receive an explicit feature grant. Marking a feature `deprecated` or `retired` doesn't remove its documentation grant.
 
 Enable profile selection in the shared configuration:
 

package/agent-docs/publish/deployment-profiles.sections/html-markdown-and-agents.md

@@ -17,7 +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 > Customer editions
 
-**Updated: 2026-11-03.**
+**Updated: 2026-11-05.**
+
+**Available since: 0.1.0-alpha.15.**
 
 Parent page: [Full Markdown page](/publish/deployment-profiles.md)
 
@@ -31,14 +33,12 @@ Parent page: [Full Markdown page](/publish/deployment-profiles.md)
 
 - [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) — Review the selected edition using captured HTML and Markdown. (Status: experimental.)
 
-Build a documentation edition for each customer from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles do not need to share a repository.
-
-By default, you do not need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
+Build a documentation edition for individual customers from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles don't need to share a repository with the content.
 
-Available since `0.1.0-alpha.15`.
+By default, you don't need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
 
 ## HTML, Markdown, and agents
 
-HTML displays the selected documentation with the deployment's title, logo, favicon, theme, and configured links. The masthead keeps the title as its accessible label. Markdown retains the selected instructions and links, without the site's branding controls. Feature selection happens during compilation and does not need browser JavaScript.
+HTML displays the selected documentation with the deployment's title, logo, favicon, theme, and configured links. The masthead keeps the title as its accessible label. Markdown retains the selected instructions and links, without the site's branding controls. Feature selection happens during compilation and doesn't need browser JavaScript.
 
-Agents reading search, discovery, or exported content receive the selected edition. They cannot retrieve excluded instructions from that edition's Markdown twin. Existing browser reader views still affect visibility only; use feature requirements for build-time omission.
+Agents reading search, discovery, or exported content receive the selected edition. They can't retrieve excluded instructions from that edition's Markdown twin. Existing browser reader views still affect visibility only; use feature requirements for build-time omission.

package/agent-docs/publish/deployment-profiles.sections/mark-pages-and-shared-sections.md

@@ -17,7 +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 > Customer editions
 
-**Updated: 2026-11-03.**
+**Updated: 2026-11-05.**
+
+**Available since: 0.1.0-alpha.15.**
 
 Parent page: [Full Markdown page](/publish/deployment-profiles.md)
 
@@ -31,15 +33,13 @@ Parent page: [Full Markdown page](/publish/deployment-profiles.md)
 
 - [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) — Review the selected edition using captured HTML and Markdown. (Status: experimental.)
 
-Build a documentation edition for each customer from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles do not need to share a repository.
-
-By default, you do not need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
+Build a documentation edition for individual customers from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles don't need to share a repository with the content.
 
-Available since `0.1.0-alpha.15`.
+By default, you don't need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
 
 ## Mark pages and shared sections
 
-Pages declare feature requirements with `requires`. They do not name SKU IDs. The profile's SKU mappings and direct grants determine which features are available.
+Pages declare feature requirements with `requires`. They don't name SKU IDs. The profile's SKU mappings and direct grants determine which features are available.
 
 ### Unmarked pages are shared by default
 
@@ -56,7 +56,7 @@ The following table shows feature selection after those other rules pass. Grants
 | `allOf: [analytics, connectors]`      | Omitted             | Omitted        | Included                 |
 | `anyOf: [analytics, connectors]`      | Omitted             | Included       | Included                 |
 
-**Forgetting a requirement makes a feature-specific page shared.** Shoalrun does not infer requirements from its folder, title, product metadata, or navigation label. Enable explicit classification to catch missing page declarations, and review feature-specific content before distributing an edition.
+**Forgetting a requirement makes a feature-specific page shared.** Shoalrun doesn't infer requirements from its folder, title, product metadata, or navigation label. Enable explicit classification to catch missing page declarations, and review feature-specific content before distributing an edition.
 
 ### Require a deliberate page classification
 
@@ -70,7 +70,7 @@ profiles:
   requireClassification: true
 ```
 
-Every public page in the shared project's enabled publications must now explicitly declare `shared: true` or `requires` in its own source frontmatter. An unclassified page fails the build with its source filename; it does not silently disappear. The check runs before customer feature and publication selection, so a later purchase or publication change cannot expose a previously unchecked page. Drafts and pages outside the shared project's enabled publications do not need classification for that build.
+Every public page in the shared project's enabled publications must now explicitly declare `shared: true` or `requires` in its own source frontmatter. An unclassified page fails the build with its source filename; it doesn't silently disappear. The check runs before customer feature and publication selection, so a later purchase or publication change can't expose a previously unchecked page. Drafts and pages outside the shared project's enabled publications don't need classification for that build.
 
 For common instructions, add this page-level declaration:
 
@@ -78,11 +78,11 @@ For common instructions, add this page-level declaration:
 shared: true
 ```
 
-For a product-specific page, use `requires` as shown below. Do not combine `shared: true` and `requires` on the same page. `shared: false` is invalid. `shared` must stay page-specific and cannot appear in frontmatter defaults or enforced settings. Inherited feature requirements still restrict content, but do not satisfy strict classification: each page needs its own declaration.
+For a product-specific page, use `requires` as shown below. Don't combine `shared: true` and `requires` on the same page. `shared: false` is invalid. `shared` must stay page-specific and can't appear in frontmatter defaults or enforced settings. Inherited feature requirements still restrict content, but don't satisfy strict classification: each page needs its own declaration.
 
 To migrate, enable the policy locally and classify the pages named in build errors after reviewing their content. Put the declaration in page templates to make the choice part of creating a page; avoid marking an entire collection shared without reviewing it.
 
-This policy catches missing declarations. It cannot tell whether a declaration is correct or detect an ungated product-specific paragraph inside a shared page. It does not authenticate readers; the deployment still controls access to the resulting edition.
+This policy catches missing declarations. It can't tell whether a declaration is correct or detect an ungated product-specific paragraph inside a shared page. It doesn't authenticate readers; the deployment still controls access to the resulting edition.
 
 ### Restrict a feature-specific page
 
@@ -93,7 +93,7 @@ requires:
   allOf: [analytics, connectors]
 ```
 
-Use `anyOf` when either feature is sufficient. If a requirement contains both clauses, both must pass. When the resolved requirements do not match the profile's grants, the whole page is omitted.
+Use `anyOf` when either feature is sufficient. If a requirement contains both clauses, both must pass. When the resolved requirements don't match the profile's grants, the whole page is omitted.
 
 ### Restrict part of a shared page
 
@@ -113,7 +113,7 @@ Import a dataset through a connector, then select it in your analytics report.
 These troubleshooting tips apply to every customer.
 ```
 
-The page's content outside `<ForFeature>` stays shared. A block appears only when its requirements match; excluding a block does not exclude the rest of the page. If a page-level requirement excludes the whole page, a matching block inside it cannot restore that page.
+The page's content outside `<ForFeature>` stays shared. A block appears only when its requirements match; excluding a block doesn't exclude the rest of the page. If a page-level requirement excludes the whole page, a matching block inside it can't restore that page.
 
 Excluded blocks contribute no text, links, snippet expansions, API embeds, or images to the edition. Put links to optional pages inside matching conditions. A link remaining in selected prose must point to a selected destination.
 
@@ -132,4 +132,4 @@ apis:
     generateReferences: true
 ```
 
-For a feature-specific API, use `requires` instead of `shared`. An individual OpenAPI operation can declare `x-shoalrun-shared: true` or `x-shoalrun-requires: { allOf: [analytics] }`. Its declaration satisfies classification for that generated page; API-level feature requirements still apply. Operations with differing requirements need their own declarations. General frontmatter defaults do not satisfy generated-page classification. Authored API reference pages follow the ordinary page rule.
+For a feature-specific API, use `requires` instead of `shared`. An individual OpenAPI operation can declare `x-shoalrun-shared: true` or `x-shoalrun-requires: { allOf: [analytics] }`. Its declaration satisfies classification for that generated page; API-level feature requirements still apply. Operations with differing requirements need their own declarations. General frontmatter defaults don't satisfy generated-page classification. Authored API reference pages follow the ordinary page rule.

package/agent-docs/publish/deployment-profiles.sections/preview-and-edit-a-customer-edition.md

@@ -0,0 +1,55 @@
+---
+id: guide.deployment-profiles
+title: Build customer documentation editions
+summary: Select purchased and grandfathered features with a deployment-owned
+  profile and apply customer branding.
+type: how-to
+area: publishing
+subarea: publishing-configuration
+canonical: /publish/deployment-profiles
+---
+
+# Build customer documentation editions
+
+> 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 > Customer editions
+
+**Updated: 2026-11-05.**
+
+**Available since: 0.1.0-alpha.15.**
+
+Parent page: [Full Markdown page](/publish/deployment-profiles.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Build separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md) — Understand how separate sites share authored content and configuration.
+
+**Next steps**
+
+- [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) — Review the selected edition using captured HTML and Markdown. (Status: experimental.)
+
+Build a documentation edition for individual customers from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles don't need to share a repository with the content.
+
+By default, you don't need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
+
+## Preview and edit a customer edition
+
+Since 0.1.0-alpha.18
+
+From the configured project directory, start a preview using the deployment's profile:
+
+```sh
+npx --no-install shoalrun dev docs.config.yaml dist/customer \
+  --profile /run/config/docs-profile.yaml --port 8770
+```
+
+The development server compiles the selected edition and watches source files, the chosen profile, SKU manifest, and declared assets. A profile mounted outside the project is watched too. Changing its product releases or feature grants rebuilds the edition through the same selection rules as a static build. Use a separate output directory and port for another customer preview.
+
+The preview banner identifies the selected profile, edition digest, and successful build. An invalid initial profile prevents startup. If an edit fails after startup, the server keeps the last successful output and shows a build-error banner. It doesn't switch to a shared edition. Fix the profile, manifest, or declared asset and save it to trigger recovery. A page removed by a successful edition change returns the browser to a published landing page.
+
+On older releases, build with `--profile` and serve that selected output separately. Reader-view controls aren't a substitute: they change browser visibility, while the profile determines which files and instructions exist in the edition.

package/agent-docs/publish/deployment-profiles.sections/related-reading.md

@@ -17,15 +17,15 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Customer editions
 
-**Updated: 2026-11-03.**
+**Updated: 2026-11-05.**
 
-Parent page: [Full Markdown page](/publish/deployment-profiles.md)
+**Available since: 0.1.0-alpha.15.**
 
-Build a documentation edition for each customer from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles do not need to share a repository.
+Parent page: [Full Markdown page](/publish/deployment-profiles.md)
 
-By default, you do not need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
+Build a documentation edition for individual customers from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles don't need to share a repository with the content.
 
-Available since `0.1.0-alpha.15`.
+By default, you don't need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
 
 ## Related reading
 
@@ -39,4 +39,4 @@ Available since `0.1.0-alpha.15`.
 
 ### Reference while working
 
-- [Share pages across documentation versions](https://www.shoalrun.com/publish/publications.md) — Select older product instructions independently of feature grants.
+- [Share pages across products and documentation versions](https://www.shoalrun.com/publish/publications.md) — Select older product instructions independently of feature grants.

package/agent-docs/publish/deployment-profiles.sections/select-each-product-release.md

@@ -0,0 +1,55 @@
+---
+id: guide.deployment-profiles
+title: Build customer documentation editions
+summary: Select purchased and grandfathered features with a deployment-owned
+  profile and apply customer branding.
+type: how-to
+area: publishing
+subarea: publishing-configuration
+canonical: /publish/deployment-profiles
+---
+
+# Build customer documentation editions
+
+> 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 > Customer editions
+
+**Updated: 2026-11-05.**
+
+**Available since: 0.1.0-alpha.15.**
+
+Parent page: [Full Markdown page](/publish/deployment-profiles.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Build separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md) — Understand how separate sites share authored content and configuration.
+
+**Next steps**
+
+- [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) — Review the selected edition using captured HTML and Markdown. (Status: experimental.)
+
+Build a documentation edition for individual customers from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles don't need to share a repository with the content.
+
+By default, you don't need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
+
+## Select each product release
+
+Since 0.1.0-alpha.18
+
+First declare the [independent product catalogs](https://www.shoalrun.com/publish/publications.md) and enabled product publications in the shared configuration. Then select the customer's exact combination in the profile:
+
+```yaml title="Customer publication selection (profile fragment)"
+publications:
+  enabled:
+    - { product: payments, channel: production, version: v3, language: en }
+    - { product: reporting, channel: production, version: v1, language: en }
+```
+
+Another profile can select Payments v2 with Reporting v1. Selection must remain a nonempty subset of the shared project's enabled coordinates; it can't add an undeclared product or release. Product and version are part of publication identity, so `v1` in one product doesn't select another product's v1.
+
+Feature grants and product releases answer different questions. Publication selection chooses which release's instructions to publish. SKU revisions and direct feature grants choose the functionality those instructions may describe. Selecting Payments v3 doesn't grant a feature, and granting a feature doesn't enable a Payments release. Shared pages need explicit publication memberships; `shared: true` doesn't copy them into every product.

package/agent-docs/publish/deployment-profiles.sections/supply-the-profile-from-the-deployment.md

@@ -17,7 +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 > Customer editions
 
-**Updated: 2026-11-03.**
+**Updated: 2026-11-05.**
+
+**Available since: 0.1.0-alpha.15.**
 
 Parent page: [Full Markdown page](/publish/deployment-profiles.md)
 
@@ -31,11 +33,9 @@ Parent page: [Full Markdown page](/publish/deployment-profiles.md)
 
 - [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) — Review the selected edition using captured HTML and Markdown. (Status: experimental.)
 
-Build a documentation edition for each customer from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles do not need to share a repository.
-
-By default, you do not need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
+Build a documentation edition for individual customers from one shared content project. Keep product definitions in the shared repository and supply each customer's purchases, additional features, and branding through that deployment's own profile file. Customer profiles don't need to share a repository with the content.
 
-Available since `0.1.0-alpha.15`.
+By default, you don't need to mark every page. Pages without feature requirements are shared across customer editions. For customer deployments that need a deliberate decision on each page, enable explicit classification. In either mode, add requirements to pages or sections that depend on specific features.
 
 ## Supply the profile from the deployment
 
@@ -65,4 +65,4 @@ SKU and direct grants combine into a set. Unknown IDs and revisions fail validat
 
 Profile logo and favicon paths resolve from the profile directory and must stay inside it. Shared configuration paths retain their own origins. Shoalrun reads the chosen profile and declared assets without discovering other customers' files in that deployment directory.
 
-Profiles accept selected `site`, `theme`, and existing snippet `variables` settings. They can narrow `publications.enabled` to combinations already enabled by the shared project. They cannot replace content sources, register plugins, change access policy, or override navigation. Profile CSS, custom fonts, and file-backed palettes are not supported.
+Profiles accept selected `site`, `theme`, and existing snippet `variables` settings. They can narrow `publications.enabled` to combinations already enabled by the shared project. They can't replace content sources, register plugins, change access policy, or override navigation. Profile CSS, custom fonts, and file-backed palettes aren't supported.

package/agent-docs/publish/evals.md

@@ -17,15 +17,15 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Evaluate agent tasks against your docs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
-Use evaluation tasks to check whether an agent can accomplish important work using your documentation. Shoalrun defines task and result formats, prepares report templates, and checks those reports during an audit. You run your own agent and arrange human or external review of its answers. Shoalrun does not launch agents, choose a model, or grade prose.
+Use evaluation tasks to check whether an agent can accomplish important work using your documentation. Shoalrun defines task and result formats, prepares report templates, and checks those reports during an audit. You run your own agent and arrange human or external review of its answers. Shoalrun doesn't launch agents, choose a model, or grade prose.
 
-You need a built docs site, a few realistic tasks, and an agent or manual workflow for running them. The ordinary build does not execute evaluations or call a model. Evaluations are opt-in audit checks.
+You need a built docs site, a few realistic tasks, and an agent or manual workflow for running them. The ordinary build doesn't execute evaluations or call a model. Evaluations are opt-in audit checks.
 
 ## Define a task file
 
-Save YAML or JSON with `schemaVersion: 1` and a nonempty `tasks` list. Each task needs a unique lowercase ID, a prompt, an `allowedTools` list, and criteria with unique IDs and descriptions. Tasks are required by default; set `required: false` for an exploratory task that should not block an audit.
+Save YAML or JSON with `schemaVersion: 1` and a nonempty `tasks` list. Each task needs a unique lowercase ID, a prompt, an `allowedTools` list, and criteria with unique IDs and descriptions. Tasks are required by default; set `required: false` for an exploratory task that shouldn't block an audit.
 
 ```yaml title="evals/tasks.yaml"
 schemaVersion: 1
@@ -40,7 +40,7 @@ tasks:
         description: Explain that published Markdown retains reader-marked content.
 ```
 
-Use the same tool names in your task file and runner report, such as `search`, `fetch`, `docs.search`, or `mcp.get_page`. Shoalrun validates the recorded runner tools against each executed task's allowed list. It cannot observe or enforce what tools an external agent actually used. Use a shared allowed tool set within a report; prepare separate suites for runs with different tool permissions.
+Use the same tool names in your task file and runner report, such as `search`, `fetch`, `docs.search`, or `mcp.get_page`. Shoalrun validates the recorded runner tools against each executed task's allowed list. It can't observe or enforce what tools an external agent actually used. Use a shared allowed tool set within a report; prepare separate suites for runs with different tool permissions.
 
 Write criteria that an expert can assess. Valid citations and complete report fields are mechanical checks. Whether the answer correctly explains your product remains a review judgment.
 
@@ -53,9 +53,9 @@ shoalrun eval prepare site-dist --tasks evals/tasks.yaml --out evals/results.jso
 
 Create the `evals` directory first. Preparation refuses to overwrite an existing report; use a new output filename for another run.
 
-The template contains a task-file digest, a documentation-build digest, a per-file `buildFiles` inventory, a timestamp, empty runner details, and each task marked `skipped`. It records no passing results and does not run the tasks. A template with skipped required tasks fails the check until you complete the run and review.
+The template contains a task-file digest, a documentation-build digest, a per-file `buildFiles` inventory, a timestamp, empty runner details, and each task marked `skipped`. It records no passing results and doesn't run the tasks. A template with skipped required tasks fails the check until you complete the run and review.
 
-The task digest uses normalized definitions, so whitespace-only changes do not invalidate a run. Prompt, criteria, tools, or required-status changes do. The build digest covers published output files, including HTML, Markdown, indexes, discovery, and assets. It excludes `build-info.json`, private `ai/` artifacts, and `.shoalrun/` state. File touches do not invalidate otherwise identical output; changed published bytes do. Other published metadata, including build IDs embedded in manifests, remains covered even when it reflects deployment provenance.
+The task digest uses normalized definitions, so whitespace-only changes don't invalidate a run. Prompt, criteria, tools, or required-status changes do. The build digest covers published output files, including HTML, Markdown, indexes, discovery, and assets. It excludes `build-info.json`, private `ai/` artifacts, and `.shoalrun/` state. File touches don't invalidate otherwise identical output; changed published bytes do. Other published metadata, including build IDs embedded in manifests, remains covered even when it reflects deployment provenance.
 
 ## Diagnose a different build
 
@@ -69,15 +69,15 @@ shoalrun eval compare current-build.json --since evaluated-build.json
 
 The comparison lists added, changed, and removed file paths. It exits 0 for identical snapshots and 1 for differences or invalid input. Each inventory binds relative file paths and SHA-256 byte digests to the same build digest used by evaluation reports. It contains no answers or grades.
 
-New report templates include this inventory in `buildFiles`. When a report is stale, `eval check` includes the file comparison in `details.buildChanges`. Older reports still receive the exact-build check, but cannot identify which earlier files differ. Editing the stored digest or deleting changed files is not a new evaluation.
+New report templates include this inventory in `buildFiles`. When a report is stale, `eval check` includes the file comparison in `details.buildChanges`. Older reports still receive the exact-build check, but can't identify which earlier files differ. Editing the stored digest or deleting changed files isn't a new evaluation.
 
-For local review of a hosted build, download and retain that exact output, task file, and report template. Run the tasks against the downloaded site and check the completed report against it. Rebuilding the source on another operating system can change rendered assets; a report about the downloaded build does not automatically cover that rebuild. Archive the source revision and build inventory with the run. A successful build capture records no evaluation pass.
+For local review of a hosted build, download and retain that exact output, task file, and report template. Run the tasks against the downloaded site and check the completed report against it. Rebuilding the source on another operating system can change rendered assets; a report about the downloaded build doesn't automatically cover that rebuild. Archive the source revision and build inventory with the run. A successful build capture records no evaluation pass.
 
 ## Run and review the tasks
 
 Use your own agent with the declared tool access. Record the actual runner name, optional model, available tools, and any limitations in `runner`. Replace `recordedAt` with the run's UTC ISO timestamp.
 
-For each task, record its status (`pass`, `fail`, or `skipped`), answer, citations, and criterion judgments. A passing result needs a nonempty answer, at least one citation, and a passing judgment with a reason for every defined criterion. Identify citations by stable page ID and publication, so editions and languages cannot be confused:
+For each task, record its status (`pass`, `fail`, or `skipped`), answer, citations, and criterion judgments. A passing result needs a nonempty answer, at least one citation, and a passing judgment with a reason for every defined criterion. Identify citations by stable page ID and publication, so editions and languages can't be confused:
 
 ```json
 {
@@ -109,7 +109,7 @@ shoalrun eval check site-dist --tasks evals/tasks.yaml --report evals/results.js
 
 The command prints JSON and exits 1 on failure. It checks schema versions and fields, unique task and criterion IDs, the two digests, timestamps, runner and review details, declared tool access, criterion coverage, and whether each citation identifies a published page in the selected publication. Required tasks must pass. Missing or failed optional tasks appear in the outcomes without blocking, but malformed results, bad citations, or unsupported passing claims still fail validation.
 
-Shoalrun verifies that cited pages exist; it does not verify that their text supports an answer. Reported tool use and grades are assertions supplied by the runner and reviewer. A passing report does not establish broad agent reliability or factual correctness.
+Shoalrun verifies that cited pages exist; it doesn't verify that their text supports an answer. Reported tool use and grades are assertions supplied by the runner and reviewer. A passing report doesn't establish broad agent reliability or factual correctness.
 
 ## Add the audit hook
 
@@ -122,7 +122,7 @@ audit:
     report: ./evals/results.json
 ```
 
-Paths resolve beside the config file declaring each value, including included config files. The audit builds a temporary site, then checks the report against that output. Changes to published output or task definitions require a new evaluation. Reports remain project files; Shoalrun does not publish them into the site automatically.
+Paths resolve beside the config file declaring each value, including included config files. The audit builds a temporary site, then checks the report against that output. Changes to published output or task definitions require a new evaluation. Reports remain project files; Shoalrun doesn't publish them into the site automatically.
 
 If your team already has an evaluator command, configure it as an optional `run` list:
 
@@ -144,17 +144,17 @@ That script belongs to your project. It runs after a successful build, from the
 | `SHOALRUN_EVAL_BUILD_DIGEST` | Digest of the built documentation.  |
 | `SHOALRUN_EVAL_TASKS_DIGEST` | Digest of the normalized tasks.     |
 
-The script must run and assess tasks, write a report, and exit nonzero on execution failure. A successful exit does not bypass report checks. A nonzero exit fails the audit even if an older report still validates. Hook execution and report validation appear separately as `eval-run` and `evals` in the audit results. A failed build prevents the eval hook from running.
+The script must run and assess tasks, write a report, and exit nonzero on execution failure. A successful exit doesn't bypass report checks. A nonzero exit fails the audit even if an older report still validates. Hook execution and report validation appear separately as `eval-run` and `evals` in the audit results. A failed build prevents the eval hook from running.
 
 Configured commands can use your provider keys, make network requests, and write files. Shoalrun supplies the interface; your team owns the execution, costs, review, and credentials. The temporary build is removed after the audit. For longer runs, execute your evaluator separately and import the resulting report.
 
 ## Shoalrun's own example
 
-This repository retains `docs/evals/tasks.yaml` and `docs/evals/results.json` as an example of a small agent self-assessment. Its five questions cover custom search providers, search off, bounded lexical coverage, reader choices, and freshness. This narrow, familiar task set is not a general quality gate. The site's routine audit does not import the report, and ordinary documentation changes do not require rerunning it.
+This repository retains `docs/evals/tasks.yaml` and `docs/evals/results.json` as an example of a small agent self-assessment. Its five questions cover custom search providers, search off, bounded lexical coverage, reader choices, and freshness. This narrow, familiar task set isn't a general quality gate. The site's routine audit doesn't import the report, and ordinary documentation changes don't require rerunning it.
 
 The original October 1 report is preserved unchanged in `docs/evals/history/results-2026-10-01.json`. The October 15 local run retains its actual tool responses, new answers, self-review judgments, and exact-build inventory under `docs/evals/runs/2026-10-15-local/`. The evaluator knew the project and had seen the earlier report; tasks shared retrieved pages. These are historical observations, not blind or independent evidence of general agent reliability. Earlier exploratory results remain in `plans/documentation/agent-docs-eval.json`.
 
-Run a new evaluation when it answers a concrete product question, with relevant tasks and a clearly described runner and reviewer. Preserve older reports rather than changing their dates, digests, or grades. An exact-build report can legitimately fail freshness against a later build; that does not make its original evidence invalid or require routine refreshes.
+Run a new evaluation when it answers a concrete product question, with relevant tasks and a clearly described runner and reviewer. Preserve older reports rather than changing their dates, digests, or grades. An exact-build report can legitimately fail freshness against a later build; that doesn't make its original evidence invalid or require routine refreshes.
 
 Shoalrun's evaluation commands and optional audit hook remain available for projects that choose them. This site's normal validation still covers the build, links, schemas, output consistency, relevant behavior tests, and browser checks. To inspect the archived October 15 evidence without requiring the current site to match its old build, run from the repository root after compiling the framework:
 
@@ -162,7 +162,7 @@ Shoalrun's evaluation commands and optional audit hook remain available for proj
 node docs/evals/runs/2026-10-15-local/verify.mjs
 ```
 
-That command checks the recorded responses and report provenance; it does not rerun tasks, grade answers, or certify the current site.
+That command checks the recorded responses and report provenance; it doesn't rerun tasks, grade answers, or certify the current site.
 
 ## Related reading
 

package/agent-docs/publish/evals.sections/add-the-audit-hook.md

@@ -17,13 +17,13 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Evaluate agent tasks against your docs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/evals.md)
 
-Use evaluation tasks to check whether an agent can accomplish important work using your documentation. Shoalrun defines task and result formats, prepares report templates, and checks those reports during an audit. You run your own agent and arrange human or external review of its answers. Shoalrun does not launch agents, choose a model, or grade prose.
+Use evaluation tasks to check whether an agent can accomplish important work using your documentation. Shoalrun defines task and result formats, prepares report templates, and checks those reports during an audit. You run your own agent and arrange human or external review of its answers. Shoalrun doesn't launch agents, choose a model, or grade prose.
 
-You need a built docs site, a few realistic tasks, and an agent or manual workflow for running them. The ordinary build does not execute evaluations or call a model. Evaluations are opt-in audit checks.
+You need a built docs site, a few realistic tasks, and an agent or manual workflow for running them. The ordinary build doesn't execute evaluations or call a model. Evaluations are opt-in audit checks.
 
 ## Add the audit hook
 
@@ -36,7 +36,7 @@ audit:
     report: ./evals/results.json
 ```
 
-Paths resolve beside the config file declaring each value, including included config files. The audit builds a temporary site, then checks the report against that output. Changes to published output or task definitions require a new evaluation. Reports remain project files; Shoalrun does not publish them into the site automatically.
+Paths resolve beside the config file declaring each value, including included config files. The audit builds a temporary site, then checks the report against that output. Changes to published output or task definitions require a new evaluation. Reports remain project files; Shoalrun doesn't publish them into the site automatically.
 
 If your team already has an evaluator command, configure it as an optional `run` list:
 
@@ -58,6 +58,6 @@ That script belongs to your project. It runs after a successful build, from the
 | `SHOALRUN_EVAL_BUILD_DIGEST` | Digest of the built documentation.  |
 | `SHOALRUN_EVAL_TASKS_DIGEST` | Digest of the normalized tasks.     |
 
-The script must run and assess tasks, write a report, and exit nonzero on execution failure. A successful exit does not bypass report checks. A nonzero exit fails the audit even if an older report still validates. Hook execution and report validation appear separately as `eval-run` and `evals` in the audit results. A failed build prevents the eval hook from running.
+The script must run and assess tasks, write a report, and exit nonzero on execution failure. A successful exit doesn't bypass report checks. A nonzero exit fails the audit even if an older report still validates. Hook execution and report validation appear separately as `eval-run` and `evals` in the audit results. A failed build prevents the eval hook from running.
 
 Configured commands can use your provider keys, make network requests, and write files. Shoalrun supplies the interface; your team owns the execution, costs, review, and credentials. The temporary build is removed after the audit. For longer runs, execute your evaluator separately and import the resulting report.