@shoalrun/cli 0.1.0-alpha.13 → 0.1.0-alpha.15

package/agent-docs/index.md

@@ -12,121 +12,72 @@ canonical: /
 
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-30.**
 
 **Docs for people. Context for agents.**
 
-One source, with control over how each audience reads it. Build interactive docs for people and readable content for agents, with checks before you publish.
+One source, two audiences. Build interactive docs for people and readable content for agents, with checks before you publish.
 
+- [Use your docs in your app](https://www.shoalrun.com/content-delivery.md)
 - [See what an agent gets](https://www.shoalrun.com/publish/agent-friendliness.md)
 - [See what works today](https://www.shoalrun.com/status.md)
 
-> **Try the alpha:** Install `@shoalrun/cli` from npm and build your own site. No account or package token is needed. Pin an exact version while the alpha evolves.
+> **Try the alpha:** Install `@shoalrun/cli` from npm. No account or token is needed, and the normal build makes no model calls or network requests. Pin an exact version while the alpha evolves.
 >
 > [Install Shoalrun →](https://www.shoalrun.com/start.md)
 
-## Readable output, with checks you can inspect
-
-Write Markdown, MDX, and OpenAPI once. People get tabs, disclosures, navigation, and reader views. Agents get the supported content in reading order, with stable page identities and machine-readable contracts.
-
-| What you can inspect                     | What it gives you                                                                                                                 |
-| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| A manifest with byte digests             | Stable page IDs and publication variants, with SHA-256 digests for checking the exact Markdown bytes.                             |
-| Compact discovery and incremental sync   | Find a page without the full search index; compare saved snapshots when a build changes.                                          |
-| Focused per-operation OpenAPI contracts  | One small contract containing an operation and the local schemas it needs, when enabled.                                          |
-| Explicit component representations       | Tabs and disclosures become labeled sections. Snippets expand into their resolved content. Unsupported components fail the build. |
-| Reader views and format-specific content | Choose what people see in the browser and write different explanations for HTML and Markdown when needed.                         |
-
-### A tabbed page, without missing panels
-
-This example has two client choices and a closed disclosure. The Markdown includes both clients and the troubleshooting detail.
-
-### You write
-
-````mdx title="content/check-service.mdx"
-<Tabs label="Client">
-<Tab label="curl">
-
-```sh
-curl -fsS https://api.example.com/health
-```
-
-</Tab>
-<Tab label="JavaScript">
-
-```js
-const response = await fetch('https://api.example.com/health');
-console.log(response.status);
-```
+## Put your docs inside your product
 
-</Tab>
-</Tabs>
+Export pages, single sections, and named snippets from the source that builds your site. Read them as HTML or Markdown in a help drawer, an onboarding screen, or an agent. Static files are enough; no content server or model provider is needed.
 
-<Collapsible title="If the request fails">
-Check the service URL and your network connection.
-</Collapsible>
-````
+```ts
+import { openManifestContentSource } from '@shoalrun/cli/content';
 
-### People get HTML
-
-### curl
-
-```sh
-curl -fsS https://api.example.com/health
+const snapshot = await openManifestContentSource({
+  manifestUrl: '/content/revisions/r1/manifest.json',
+});
+const result = await snapshot.get(
+  { kind: 'section', documentId: 'guide.billing', sectionId: 'refunds' },
+  { format: 'html' },
+);
 ```
 
-### JavaScript
+The client checks each representation against the manifest's digest. A REST adapter serves the same snapshots over HTTP.
 
-```js
-const response = await fetch('https://api.example.com/health');
-console.log(response.status);
-```
+- [Content delivery](https://www.shoalrun.com/content-delivery.md)
 
-### If the request fails
+  Deliver pages, sections, and snippet instances to applications from one reviewed content bundle.
 
-Check the service URL and your network connection.
+- [Read content with a client](https://www.shoalrun.com/content-delivery/client.md)
 
-### Agents get Markdown
+  Open a content revision and read typed resources without depending on generated filenames.
 
-````md title="/check-service.md (body excerpt)"
-### curl
-
-```sh
-curl -fsS https://api.example.com/health
-```
+- [Serve content through REST](https://www.shoalrun.com/content-delivery/rest.md)
 
-### JavaScript
+  Expose reviewed content snapshots over HTTP and read them through the content client.
 
-```js
-const response = await fetch('https://api.example.com/health');
-console.log(response.status);
-```
-
-### If the request fails
+## Readable output, with checks you can inspect
 
-Check the service URL and your network connection.
-````
+Write Markdown, MDX, and OpenAPI once. People get tabs, navigation, and reader views. Agents get the supported content in reading order, with stable page IDs and machine-readable contracts.
 
-### Fetch the published output
+| What you can inspect                     | What it gives you                                                                                          |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| A manifest with byte digests             | Stable page IDs and publication variants, with SHA-256 digests for the exact Markdown bytes.               |
+| Compact discovery and incremental sync   | Find a page without the full search index; compare snapshots when a build changes.                         |
+| Focused per-operation OpenAPI contracts  | One small contract with an operation and the local schemas it needs, when enabled.                         |
+| Explicit component representations       | Tabs and disclosures become labeled sections. Snippets expand. Unsupported components fail the build.      |
+| Reader views and format-specific content | Choose what people see in the browser, and write different explanations for HTML and Markdown when needed. |
 
-Start with the compact page list, choose a page, and fetch its Markdown. The full manifest supplies byte digests when you need verification; build information and sync snapshots let returning clients detect changes. [Try the example on the agent-friendly guide](https://www.shoalrun.com/publish/agent-friendliness.md) to compare live components with tested Markdown output.
+Start with the compact page list, then fetch a page as Markdown. Hosts that support [content negotiation](https://www.shoalrun.com/publish/agent-friendliness.md) also serve it at the HTML route when the request sends `Accept: text/markdown`.
 
 ```sh
 curl -fsSL https://www.shoalrun.com/llms.min.txt
 curl -fsSL https://www.shoalrun.com/publish/agent-friendliness.md
 ```
 
-Hosts that support [content negotiation](https://www.shoalrun.com/publish/agent-friendliness.md) can serve the same Markdown at the HTML route when the request sends `Accept: text/markdown`:
-
-```sh
-curl -fsSL -H 'Accept: text/markdown' https://www.shoalrun.com/author/search
-```
-
 ## Check both audiences before you publish
 
-Shoalrun builds static files for your host. Its audit builds HTML and Markdown, checks links and API contracts, and runs configured project tests. An unsupported component stops the build instead of disappearing from the agent's document.
-
-For example, adding `<UnknownWidget />` to a page makes `shoalrun check` fail with the source path:
+The audit builds HTML and Markdown, checks links and API contracts, and runs your project tests. An unsupported component stops the build instead of disappearing from the agent's document. Adding `<UnknownWidget />` to a page, for example, makes `shoalrun check` fail with the source path:
 
 ```text
 FAIL build
@@ -134,9 +85,9 @@ FAIL build
 Checks failed. Fix the findings above and rerun shoalrun check.
 ```
 
-This is illustrative output, not a failure on the current site. The check catches unsupported representations; it does not establish that every sentence is correct.
+This output is illustrative, not a failure on the current site. The check catches unsupported representations; it does not establish that every sentence is correct.
 
-[Eval reports](https://www.shoalrun.com/publish/evals.md) let you add reviewed task results to the publishing gate. Required failures and reports from an older build fail the audit. You supply the agent run and answer review. Shoalrun's five example tasks are a self-reviewed demonstration, with prior context; they are not an independent measure of agent accuracy or a comparison with other platforms.
+[Eval reports](https://www.shoalrun.com/publish/evals.md) add reviewed agent-task results to the gate. You supply the agent run and the review. Shoalrun's five example tasks are a self-reviewed demonstration, not an independent measure of agent accuracy.
 
 - [Audit a docs project](https://www.shoalrun.com/publish/audit.md)
 
@@ -150,13 +101,31 @@ This is illustrative output, not a failure on the current site. The check catche
 
   Import a local OpenAPI file, author an operation page, review its public content, and build HTML and Markdown.
 
-## Control the reading experience
+## Let agents read your docs, and help write them
+
+Agents search and read built docs through the CLI or a read-only MCP server with four tools: `search_docs`, `get_page`, `get_outline`, and `get_section`. MCP cannot edit files or deploy. Writing and checking use your agent's own file tools, CLI commands such as `docs validate` and `audit`, and five bundled skills.
+
+```sh
+shoalrun docs mcp --site docs/dist
+```
+
+This site's live endpoint is `https://www.shoalrun.com/mcp`.
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md)
+
+  Connect read-only MCP clients over stdio or HTTP to search and read built documentation.
+
+- [Use your coding agent](https://www.shoalrun.com/author/coding-agent.md)
+
+  Give your agent project guidance and draft a new documentation page.
+
+- [Use the bundled agent skills](https://www.shoalrun.com/contribute/agent-skills.md)
 
-[Reader views](https://www.shoalrun.com/author/reader-views.md) use the `readerFilters` configuration to shape browser navigation, search, cards, and marked sections. A UI reader can follow screen actions while a developer sees request examples. The published Markdown retains every reader-marked section with a label.
+  Give an agent the setup and authoring workflows that ship with Shoalrun.
 
-Reader views are visibility controls, not access controls. Hidden browser content remains in published files. Use `access.policy` to exclude pages from a public build and host authorization to protect private content.
+## Control the reading experience
 
-[Format-specific content](https://www.shoalrun.com/author/components/only.md) lets you replace an interactive instruction with a useful written explanation. [Markdown metadata settings](https://www.shoalrun.com/author/markdown-metadata.md) choose which frontmatter fields are published for agents. These are authoring and publication choices; discovery files do not protect private data.
+[Reader views](https://www.shoalrun.com/author/reader-views.md) shape navigation, search, cards, and marked sections in the browser. A UI reader can follow screen actions while a developer sees request examples. The Markdown keeps every marked section, with a label. [Format-specific content](https://www.shoalrun.com/author/components/only.md) swaps an interactive instruction for a written explanation.
 
 - [Reader views](https://www.shoalrun.com/author/reader-views.md)
 
@@ -170,9 +139,21 @@ Reader views are visibility controls, not access controls. Hidden browser conten
 
   Public field projection, source paths, profiles, precedence, and required values.
 
+## Build more than one site from one source
+
+Keep one content directory and give each site its own config, origin, theme, and navigation. `site.contentFilter` selects pages by audience, product, or region at build time. Versions and languages can share unchanged pages.
+
+- [Build separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md)
+
+  Publish separate sites from shared content using optional facet selection.
+
+- [Share pages across documentation versions](https://www.shoalrun.com/publish/publications.md)
+
+  Versioning one docs site without copying every page: share unchanged pages, vary sections, and publish changed pages separately.
+
 ## Make it look like yours
 
-Choose a theme and palette, follow the reader's light or dark setting, and customize brand colors or CSS. The build checks configured palette colors for contrast.
+Pick a theme and palette, follow the reader's light or dark setting, and add brand colors or CSS. The build checks palette contrast.
 
 ```yaml title="docs.config.yaml"
 theme:
@@ -218,23 +199,12 @@ Customize these parts through config, local modules, or a host adapter.
 | ----------------- | --------------------------- | ---------------------------------------------------------------------- |
 | Search            | `outputs.html.search`       | Use the built-in index, supply a provider, or turn browser search off. |
 | Code highlighting | `outputs.html.highlighting` | Choose a Shiki theme or supply a highlighter.                          |
-| Page metadata     | `metadata.provider`         | Define the fields your build can read, with values you supply.         |
-| Reader views      | `readerFilters`             | Define reader choices and mark pages and sections for those choices.   |
+| Page metadata     | `metadata.provider`         | Define the fields your build can read.                                 |
+| Reader views      | `readerFilters`             | Define reader choices and mark pages and sections.                     |
 | Share images      | `outputs.html.shareImages`  | Customize the link-preview design and fonts.                           |
 | Hosting           | Build adapters              | Configure HTTP behavior for Vercel, Node, or your own host.            |
 
-Split config across files with `$include`, share a base with `extends`, and ask `shoalrun config explain` which file set a value.
-
-### Give your coding agent the docs
-
-The prototype bundles four authoring skills: setup, authoring, recipes, and code walkthroughs. It also includes Shoalrun's generated documentation for offline lookup:
-
-```sh
-shoalrun docs search "custom search provider"
-shoalrun docs read guide.search
-```
-
-[Use the bundled skills](https://www.shoalrun.com/contribute/agent-skills.md) or consult the [command reference](https://www.shoalrun.com/reference/agent-skills.md). Shoalrun does not generate reader-side skills for each site it builds. Skills need human expertise to create and maintain; see the [non-goals](https://www.shoalrun.com/non-goals.md).
+Split config across files with `$include`, share a base with `extends`, and run `shoalrun config explain` to see which file set a value.
 
 - [Organize project configuration](https://www.shoalrun.com/configuration.md)
 

package/agent-docs/provenance.json

@@ -2,9 +2,9 @@
   "schemaVersion": 1,
   "siteBuild": {
     "schemaVersion": 1,
-    "configDigest": "31d33ea2d00a4333e120d37f58251238c0698e62f7320dccdaf1c2ace8df78fd",
-    "buildId": "38aac8472fa1fad778acd5b5bdc30067474eca35755706d09f916914326ed2f0"
+    "configDigest": "e6facf6d76a90c838fde73e4bc4a253bc30f7fa0eb67547b4f89386abd3a0378",
+    "buildId": "c8c2a551d388148cf830e85bea3a58118a3a935dc91fa043ab2cd2a178ff9c6c"
   },
-  "packageIntegrity": "sha512-Qs6yv+QFvt6L5huiKFQfIT5FYexxbSokwUVUnxIrXUx2TtY/VTdG0EKAJJuCLLi6FcrYVbnI/mC9uWqJ9nflsw==",
-  "manifestDigest": "c99f0684ea93c4add58ddee1fd19dc82fa1acd9099d6cc2b4b226a0ef85302fe"
+  "packageIntegrity": "sha512-2Of7hhwylA4zWfoWIISM+0E63RzMhK9yI/NErSoNaUhquYQSD8iED1AWiUzqabnE0hg9rdtxCt82ws5+R9D3bQ==",
+  "manifestDigest": "3c6af9a8161232cd4e824e72a427fb2b2a21963939a761a5f0f3557415dba580"
 }

package/agent-docs/publish/content-export.md

@@ -26,7 +26,7 @@ Install Shoalrun `0.1.0-alpha.13` or newer in the documentation project. This gu
 
 Start with a Shoalrun project and public pages assigned to an enabled publication. Navigation, facets, a site title, and a previous website build are optional. A site origin is needed only when links must fall back to pages on the documentation website. The export does not generate embeddings or run documentation chat.
 
-## Upgrade an existing integration
+### Upgrade an existing integration
 
 If an existing bundle contains `manifest.documents`, upgrade the CLI and rebuild the export before using this guide's loader. Update custom consumers to the resource contract:
 

package/agent-docs/publish/content-export.sections/prerequisites.md

@@ -27,3 +27,14 @@ Keep application help and your documentation website in one content source. `sho
 Install Shoalrun `0.1.0-alpha.13` or newer in the documentation project. This guide uses the resource-based export manifest described in the [manifest reference](https://www.shoalrun.com/content-delivery/manifest.md).
 
 Start with a Shoalrun project and public pages assigned to an enabled publication. Navigation, facets, a site title, and a previous website build are optional. A site origin is needed only when links must fall back to pages on the documentation website. The export does not generate embeddings or run documentation chat.
+
+### Upgrade an existing integration
+
+If an existing bundle contains `manifest.documents`, upgrade the CLI and rebuild the export before using this guide's loader. Update custom consumers to the resource contract:
+
+- Read `manifest.resources` instead of `manifest.documents`.
+- Select page resources with `ref.kind === 'page'` and `ref.documentId` instead of a document's `id`.
+- Route links with `kind: resource` through their typed `ref`, rather than `kind: document` and `documentId`.
+- Read file paths from the rebuilt manifest; do not retain paths from the old bundle.
+
+The `documents` configuration selector remains shorthand for whole pages. Use [resource selectors](https://www.shoalrun.com/content-delivery/select.md) when selecting approved sections or named snippet instances.

package/agent-docs/publish/deployment-profiles.md

@@ -0,0 +1,273 @@
+---
+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-03.**
+
+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.
+
+Available since `0.1.0-alpha.15`.
+
+## Before you begin
+
+Start with a [configured documentation project](https://www.shoalrun.com/configuration.md), its authored pages, and CLI `0.1.0-alpha.15` or later. Your deployment must be able to supply one local profile file and any declared branding assets. The fictional names and products below illustrate the format; replace them with your own catalog.
+
+A stock keeping unit (SKU) identifies a product or bundle you sell. A feature ID identifies functionality that documentation describes. A SKU revision grants a set of features; a profile can also grant features directly for standalone purchases or grandfathered agreements.
+
+## Define the shared SKU manifest
+
+Create `sku-manifest.yaml` beside `docs.config.yaml`:
+
+```yaml title="sku-manifest.yaml"
+schemaVersion: 1
+features:
+  analytics: { description: Analytics reports }
+  connectors: { description: External data connectors }
+  reports.classic: { lifecycle: deprecated }
+skus:
+  professional:
+    revisions:
+      "2025-04":
+        features: [analytics, reports.classic]
+      "2026-10":
+        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.
+
+Enable profile selection in the shared configuration:
+
+```yaml title="docs.config.yaml (fragment)"
+profiles:
+  manifest: ./sku-manifest.yaml
+  required: true
+  pruneNavigation: true
+```
+
+`required` defaults to `true`. A missing profile fails the build. `pruneNavigation` defaults to `false`; enabling it removes known excluded destinations and empty groups. Misspelled navigation targets remain errors.
+
+## 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.
+
+### Unmarked pages are shared by default
+
+With `profiles.requireClassification` omitted or `false`, a page with no authored or inherited `requires` is included in every eligible customer edition. Common setup, introductions, and shared troubleshooting can remain unmarked.
+
+Shared content still has to pass the project's access, publication, language, and facet rules. A draft stays excluded from normal builds, and a page for an older version still needs that publication enabled.
+
+The following table shows feature selection after those other rules pass. Grants can come from SKUs or direct feature entries:
+
+| Page requirements                     | No granted features | Analytics only | Analytics and Connectors |
+| ------------------------------------- | ------------------- | -------------- | ------------------------ |
+| No authored or inherited requirements | Included            | Included       | Included                 |
+| `allOf: [analytics]`                  | Omitted             | Included       | Included                 |
+| `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.
+
+### Require a deliberate page classification
+
+Enable strict classification in the shared project configuration:
+
+```yaml title="docs.config.yaml (fragment)"
+profiles:
+  manifest: ./sku-manifest.yaml
+  required: true
+  pruneNavigation: true
+  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.
+
+For common instructions, add this page-level declaration:
+
+```yaml title="Shared page frontmatter (fragment)"
+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.
+
+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.
+
+### Restrict a feature-specific page
+
+Add a requirement to each page that depends on specific functionality. This integration guide needs both features:
+
+```yaml title="Integration guide frontmatter (fragment)"
+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.
+
+### Restrict part of a shared page
+
+A page classified `shared: true` can still contain product-specific sections. Use `<ForFeature>` around each section that depends on features. Its attributes contain whitespace-separated feature IDs:
+
+```mdx
+These setup instructions apply to every customer.
+
+<ForFeature allOf="analytics connectors">
+
+## Connect your reports <Anchor id="connect-reports" />
+
+Import a dataset through a connector, then select it in your analytics report.
+
+</ForFeature>
+
+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.
+
+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.
+
+### Classify generated API references
+
+Generated pages take an explicit classification from their API definition or OpenAPI operation. For an API whose generated references are shared, add `shared: true` beside `generateReferences`:
+
+```yaml title="Shared API definition (fragment)"
+apis:
+  example:
+    shared: true
+    source:
+      kind: file
+      path: ./openapi.yaml
+      focused: true
+    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.
+
+## Supply the profile from the deployment
+
+Mount or generate the customer profile outside the shared docs repository. For example, a deployment could provide `/run/config/docs-profile.yaml` and a `brand` directory beside it:
+
+```yaml title="Deployment-owned docs-profile.yaml"
+schemaVersion: 1
+skus:
+  - { id: professional, revision: "2026-10" }
+features:
+  - reports.classic
+site:
+  title: Example Partner documentation
+  origin: https://docs.partner.example
+  logo: ./brand/logo.svg
+  favicon: ./brand/icon.png
+theme:
+  palette: kelp
+publications:
+  enabled:
+    - { channel: production, version: current, language: en }
+```
+
+This profile grants Analytics and Connectors through the SKU, plus Classic Reports through a direct grant. A customer with only grandfathered functionality can omit `skus` and declare `features: [reports.classic]`. No synthetic SKU is needed.
+
+SKU and direct grants combine into a set. Unknown IDs and revisions fail validation. Declare `features: []` with no SKU grants for a shared-content-only edition; `null` is invalid. That edition still includes eligible shared pages and text outside feature blocks, while pages and blocks requiring a feature are omitted. A missing required profile fails the build rather than selecting this shared-only behavior.
+
+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.
+
+## Build and inspect the edition
+
+From the shared documentation project directory, build into a deployment-specific output:
+
+```sh
+shoalrun build docs.config.yaml dist/customer \
+  --profile /run/config/docs-profile.yaml
+```
+
+To export application content, pass the same profile to `shoalrun export`:
+
+```sh
+shoalrun export docs.config.yaml --out dist/customer-content \
+  --profile /run/config/docs-profile.yaml
+```
+
+If several publications are enabled, an export still needs its normal explicit publication selection. Grandfathered features and older instructions are independent: the feature grant selects functionality, while the [publication version](https://www.shoalrun.com/publish/publications.md) selects the release's instructions.
+
+Use the profile when [validating documentation edits](https://www.shoalrun.com/author/workspace.md):
+
+```sh
+shoalrun docs baseline --config docs.config.yaml \
+  --out .shoalrun/baseline.json --profile /run/config/docs-profile.yaml
+
+# Edit your documentation, then validate the same edition.
+shoalrun docs validate --config docs.config.yaml \
+  --baseline .shoalrun/baseline.json --profile /run/config/docs-profile.yaml
+```
+
+Review and preview use the returned report. The snapshot captures the external profile and declared assets; later changes make the report stale. Treat reports and captured project directories as private build artifacts.
+
+## Choose navigation labels
+
+Navigation headings come from the shared project's ordinary navigation configuration. For example:
+
+```yaml title="Shared navigation (fragment)"
+navigation:
+  - id: product-guides
+    label: Product guides
+    items:
+      - { id: analytics, doc: guide.analytics }
+      - { 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.
+
+## 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.
+
+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.
+
+## 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.
+
+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.
+
+## 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.
+
+`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.
+
+## Related reading
+
+### 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.)
+
+### Reference while working
+
+- [Share pages across documentation versions](https://www.shoalrun.com/publish/publications.md) — Select older product instructions independently of feature grants.

package/agent-docs/publish/deployment-profiles.sections/before-you-begin.md

@@ -0,0 +1,44 @@
+---
+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-03.**
+
+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 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.
+
+Available since `0.1.0-alpha.15`.
+
+## Before you begin
+
+Start with a [configured documentation project](https://www.shoalrun.com/configuration.md), its authored pages, and CLI `0.1.0-alpha.15` or later. Your deployment must be able to supply one local profile file and any declared branding assets. The fictional names and products below illustrate the format; replace them with your own catalog.
+
+A stock keeping unit (SKU) identifies a product or bundle you sell. A feature ID identifies functionality that documentation describes. A SKU revision grants a set of features; a profile can also grant features directly for standalone purchases or grandfathered agreements.