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

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Content negotiation
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Shoalrun builds two versions of every published page from one authored source. The HTML version is for people using a browser. The generated Markdown version contains shared material in a form agents can read directly. Authors can also add or suppress [format-specific content](https://www.shoalrun.com/author/components/only.md) in either version. The versions share a core but need not contain identical text.
 
@@ -34,13 +34,13 @@ Shoalrun builds two versions of every published page from one authored source. T
 
 An agent reading HTML may receive navigation, styles, scripts, and interactive controls along with the article. It may then have to extract the useful content or convert the HTML to Markdown. Shoalrun's generated Markdown gives it the article directly, including material inside tabs and collapsibles and resolved OpenAPI examples. This can make the page easier to retrieve and less likely to lose content during conversion. [AFDocs checks](https://afdocs.dev/checks/markdown-availability) both `.md` URLs and content negotiation for this reason.
 
-The direct `.md` links in each HTML page and [`/llms.txt`](https://www.shoalrun.com/llms.txt) help agents that know to follow them. Negotiation helps an agent that arrives at the ordinary page URL and requests Markdown without first discovering a second URL. It does not require writers to maintain a separate article.
+The direct `.md` links in each HTML page and [`/llms.txt`](https://www.shoalrun.com/llms.txt) help agents that know to follow them. Negotiation helps an agent that arrives at the ordinary page URL and requests Markdown without first discovering a second URL. It doesn't require writers to maintain a separate article.
 
 ## What Shoalrun builds and what the host does
 
 Shoalrun creates the HTML page, its `.md` twin, and a [`/documents.json`](https://www.shoalrun.com/documents.json) manifest listing both URLs. It also writes [`/resource-headers.json`](https://www.shoalrun.com/resource-headers.json) with content types for Markdown and discovery files.
 
-The host receives each HTTP request. It must read `Accept` and select the right built file. Providers use different names for this step: a server handler, a routing rule, or an edge function. The HTTP behavior is the same. A static file alone cannot read a request header.
+The host receives each HTTP request. It must read `Accept` and select the right built file. Providers use different names for this step: a server handler, a routing rule, or an edge function. The HTTP behavior is the same. A static file alone can't read a request header.
 
 Shoalrun's Node server handles this. The standalone [Vercel build](https://www.shoalrun.com/publish/vercel.md) generates Vercel rules. On another host, use the contract below to configure its routing feature. The [host adapter guide](https://www.shoalrun.com/publish/host-adapters.md) covers adding Shoalrun's files to another build.
 
@@ -52,7 +52,7 @@ For each published page, use the two URLs in `documents.json`. Configure the hos
 2. Keep the URL in the browser unchanged when serving the twin. Use an internal rewrite or server response, not a redirect to `.md`.
 3. On the Markdown response, set `Content-Type: text/markdown; charset=utf-8`, `Vary: Accept`, and `Content-Location` to the `.md` URL.
 4. On both page responses, set `Link: <PAGE.md>; rel="alternate"; type="text/markdown"`. Keep the HTML document's existing alternate link as well.
-5. Serve direct `.md` URLs as `text/markdown`. Apply the content types in [`/resource-headers.json`](https://www.shoalrun.com/resource-headers.json) to discovery files, especially `/.well-known/api-catalog` when it is published.
+5. Serve direct `.md` URLs as `text/markdown`. Apply the content types in [`/resource-headers.json`](https://www.shoalrun.com/resource-headers.json) to discovery files, especially `/.well-known/api-catalog` when it's published.
 6. Limit the negotiation rule to published documentation pages. Leave assets, API contracts, and `/llms.txt` alone. Missing routes use the error responses described below.
 
 The Vercel rule matches the Node server except when `text/markdown` and the HTML or wildcard entry it competes with both have fractional weights. The [Vercel guide](https://www.shoalrun.com/publish/vercel.md) gives the details. The Node server compares the requested HTML and Markdown weights. When the weights tie, Markdown wins. A wildcard such as `text/*` or `*/*` alone never selects Markdown; the request must name `text/markdown`.
@@ -69,23 +69,23 @@ A Markdown response includes its canonical HTML link and a `rel="describedby"` l
 
 Generated hosting metadata specifies a strong `ETag` equal to the quoted SHA-256 Markdown digest and `Cache-Control: public, max-age=0, must-revalidate`. The Node server handles matching `If-None-Match` requests with `304` and no body, including Markdown negotiated at an HTML URL. Negotiated responses retain `Vary: Accept`. Vercel receives the generated headers but can replace the ETag with its own validator, including a weak validator for compressed responses. Send the ETag returned by the host in `If-None-Match`; treat its value as opaque. To verify downloaded Markdown bytes, compare their SHA-256 with `digest` in the document manifest, independently of the HTTP validator.
 
-Focused contracts have content-addressed URLs and a one-year immutable cache policy. Mutable JSON manifests and indexes require revalidation. See [focused contracts](https://www.shoalrun.com/api-docs/focused-contracts.md) for URL identity and retention limits. `resource-headers.json` describes selected hosting headers, including Markdown, JSON metadata, and contracts; it is not an exhaustive inventory of every static asset.
+Focused contracts have content-addressed URLs and a one-year immutable cache policy. Mutable JSON manifests and indexes require revalidation. See [focused contracts](https://www.shoalrun.com/api-docs/focused-contracts.md) for URL identity and retention limits. `resource-headers.json` describes selected hosting headers, including Markdown, JSON metadata, and contracts; it isn't an exhaustive inventory of every static asset.
 
 ## Missing pages
 
-A missing page returns HTTP `404`, with links to the documentation index, the search index when published, and the homepage. The response stays a `404` even though it provides recovery links. It does not redirect to the homepage or return an unrelated article with status `200`.
+A missing page returns HTTP `404`, with links to the documentation index, the search index when published, and the homepage. The response stays a `404` even though it provides recovery links. It doesn't redirect to the homepage or return an unrelated article with status `200`.
 
 Shoalrun's Node server returns Markdown for a missing `.md` URL or a request that prefers `Accept: text/markdown`; other requests receive HTML. Both responses carry `X-Robots-Tag: noindex`. If a known Markdown twin is missing while its HTML page exists, the response links to that HTML page in its body and `Link` header. Unexpected server errors return `500`.
 
 The build generates `404.html` and `404.md` under `site.basePath`. The Vercel adapter applies error routes after checking for existing files and preserves HTTP `404`. A missing known Markdown route includes an HTML alternate in its `Link` header. Its generic error body provides the discovery links.
 
-On another static host, configure missing routes to serve these error files with HTTP `404`. Merely uploading them does not configure the host's error status or content negotiation. Serve `404.md` as `text/markdown; charset=utf-8`, and keep error responses out of search indexes with `X-Robots-Tag: noindex`.
+On another static host, configure missing routes to serve these error files with HTTP `404`. Merely uploading them doesn't configure the host's error status or content negotiation. Serve `404.md` as `text/markdown; charset=utf-8`, and keep error responses out of search indexes with `X-Robots-Tag: noindex`.
 
 ## What if the host cannot negotiate?
 
-GitHub Pages can publish Shoalrun's HTML, `.md` files, and `/llms.txt`. It serves static files and has no request handler for choosing a file from `Accept` or setting the page response headers described above. Agents can still read the `.md` URLs, but a request to the HTML URL cannot negotiate there. A programmable proxy or CDN can add that behavior. You can also publish the same built files on a host with request rules. Bare GitHub Pages cannot pass AFDocs' content-negotiation check.
+GitHub Pages can publish Shoalrun's HTML, `.md` files, and `/llms.txt`. It serves static files and has no request handler for choosing a file from `Accept` or setting the page response headers described above. Agents can still read the `.md` URLs, but a request to the HTML URL can't negotiate there. A programmable proxy or CDN can add that behavior. You can also publish the same built files on a host with request rules. Bare GitHub Pages can't pass AFDocs' content-negotiation check.
 
-`site.basePath` also prefixes assets, API contracts, `/llms.txt`, and discovery files. For a GitHub Pages project site at `/<repository>/`, set `site.basePath: /<repository>` and publish the matching subtree from the build output as the project site's root. GitHub Pages still cannot provide Markdown content negotiation at an HTML URL.
+`site.basePath` also prefixes assets, API contracts, `/llms.txt`, and discovery files. For a GitHub Pages project site at `/<repository>/`, set `site.basePath: /<repository>` and publish the matching subtree from the build output as the project site's root. GitHub Pages still can't provide Markdown content negotiation at an HTML URL.
 
 ## Verify the deployed URL
 
@@ -106,7 +106,7 @@ curl -i -H 'Accept: text/markdown;q=0' https://your-docs.example/publish/output/
 
 Check the status, headers, and body. The first and fourth requests should return HTML. The second and third should return readable Markdown that gives its reader what they need for the intended task. Shared facts and API constraints should stay consistent, while human- and agent-oriented content may differ; see [Shoalrun's authoring position](https://www.shoalrun.com/publish/agent-friendliness.md). The first two responses should include `Vary: Accept` so caches keep the formats separate, and a Markdown `Link` so clients can find the twin. The negotiated Markdown response should include `Content-Location` with its `.md` URL. Also check that a missing page returns 404 and the published discovery files have the types declared in `resource-headers.json`.
 
-Run these checks against the production domain after deployment. Local preview results establish what Shoalrun's Node server does; they do not prove that a CDN applies the same rules. For a whole-site audit, run the [AFDocs scorecard](https://afdocs.dev/) against the deployed site and review its findings against the site's content requirements.
+Run these checks against the production domain after deployment. Local preview results establish what Shoalrun's Node server does; they don't prove that a CDN applies the same rules. For a whole-site audit, run the [AFDocs scorecard](https://afdocs.dev/) against the deployed site and review its findings against the site's content requirements.
 
 ## Related reading
 

package/agent-docs/publish/content-negotiation.sections/hosting-contract.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Content negotiation
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/content-negotiation.md)
 
@@ -48,7 +48,7 @@ For each published page, use the two URLs in `documents.json`. Configure the hos
 2. Keep the URL in the browser unchanged when serving the twin. Use an internal rewrite or server response, not a redirect to `.md`.
 3. On the Markdown response, set `Content-Type: text/markdown; charset=utf-8`, `Vary: Accept`, and `Content-Location` to the `.md` URL.
 4. On both page responses, set `Link: <PAGE.md>; rel="alternate"; type="text/markdown"`. Keep the HTML document's existing alternate link as well.
-5. Serve direct `.md` URLs as `text/markdown`. Apply the content types in [`/resource-headers.json`](https://www.shoalrun.com/resource-headers.json) to discovery files, especially `/.well-known/api-catalog` when it is published.
+5. Serve direct `.md` URLs as `text/markdown`. Apply the content types in [`/resource-headers.json`](https://www.shoalrun.com/resource-headers.json) to discovery files, especially `/.well-known/api-catalog` when it's published.
 6. Limit the negotiation rule to published documentation pages. Leave assets, API contracts, and `/llms.txt` alone. Missing routes use the error responses described below.
 
 The Vercel rule matches the Node server except when `text/markdown` and the HTML or wildcard entry it competes with both have fractional weights. The [Vercel guide](https://www.shoalrun.com/publish/vercel.md) gives the details. The Node server compares the requested HTML and Markdown weights. When the weights tie, Markdown wins. A wildcard such as `text/*` or `*/*` alone never selects Markdown; the request must name `text/markdown`.

package/agent-docs/publish/content-negotiation.sections/missing-pages.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Content negotiation
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/content-negotiation.md)
 
@@ -42,10 +42,10 @@ Shoalrun builds two versions of every published page from one authored source. T
 
 ## Missing pages
 
-A missing page returns HTTP `404`, with links to the documentation index, the search index when published, and the homepage. The response stays a `404` even though it provides recovery links. It does not redirect to the homepage or return an unrelated article with status `200`.
+A missing page returns HTTP `404`, with links to the documentation index, the search index when published, and the homepage. The response stays a `404` even though it provides recovery links. It doesn't redirect to the homepage or return an unrelated article with status `200`.
 
 Shoalrun's Node server returns Markdown for a missing `.md` URL or a request that prefers `Accept: text/markdown`; other requests receive HTML. Both responses carry `X-Robots-Tag: noindex`. If a known Markdown twin is missing while its HTML page exists, the response links to that HTML page in its body and `Link` header. Unexpected server errors return `500`.
 
 The build generates `404.html` and `404.md` under `site.basePath`. The Vercel adapter applies error routes after checking for existing files and preserves HTTP `404`. A missing known Markdown route includes an HTML alternate in its `Link` header. Its generic error body provides the discovery links.
 
-On another static host, configure missing routes to serve these error files with HTTP `404`. Merely uploading them does not configure the host's error status or content negotiation. Serve `404.md` as `text/markdown; charset=utf-8`, and keep error responses out of search indexes with `X-Robots-Tag: noindex`.
+On another static host, configure missing routes to serve these error files with HTTP `404`. Merely uploading them doesn't configure the host's error status or content negotiation. Serve `404.md` as `text/markdown; charset=utf-8`, and keep error responses out of search indexes with `X-Robots-Tag: noindex`.

package/agent-docs/publish/content-negotiation.sections/related-reading.md

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

package/agent-docs/publish/content-negotiation.sections/validators-and-manifest-links.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Content negotiation
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/content-negotiation.md)
 
@@ -46,4 +46,4 @@ A Markdown response includes its canonical HTML link and a `rel="describedby"` l
 
 Generated hosting metadata specifies a strong `ETag` equal to the quoted SHA-256 Markdown digest and `Cache-Control: public, max-age=0, must-revalidate`. The Node server handles matching `If-None-Match` requests with `304` and no body, including Markdown negotiated at an HTML URL. Negotiated responses retain `Vary: Accept`. Vercel receives the generated headers but can replace the ETag with its own validator, including a weak validator for compressed responses. Send the ETag returned by the host in `If-None-Match`; treat its value as opaque. To verify downloaded Markdown bytes, compare their SHA-256 with `digest` in the document manifest, independently of the HTTP validator.
 
-Focused contracts have content-addressed URLs and a one-year immutable cache policy. Mutable JSON manifests and indexes require revalidation. See [focused contracts](https://www.shoalrun.com/api-docs/focused-contracts.md) for URL identity and retention limits. `resource-headers.json` describes selected hosting headers, including Markdown, JSON metadata, and contracts; it is not an exhaustive inventory of every static asset.
+Focused contracts have content-addressed URLs and a one-year immutable cache policy. Mutable JSON manifests and indexes require revalidation. See [focused contracts](https://www.shoalrun.com/api-docs/focused-contracts.md) for URL identity and retention limits. `resource-headers.json` describes selected hosting headers, including Markdown, JSON metadata, and contracts; it isn't an exhaustive inventory of every static asset.

package/agent-docs/publish/content-negotiation.sections/verify-the-deployed-url.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Content negotiation
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/content-negotiation.md)
 
@@ -59,4 +59,4 @@ curl -i -H 'Accept: text/markdown;q=0' https://your-docs.example/publish/output/
 
 Check the status, headers, and body. The first and fourth requests should return HTML. The second and third should return readable Markdown that gives its reader what they need for the intended task. Shared facts and API constraints should stay consistent, while human- and agent-oriented content may differ; see [Shoalrun's authoring position](https://www.shoalrun.com/publish/agent-friendliness.md). The first two responses should include `Vary: Accept` so caches keep the formats separate, and a Markdown `Link` so clients can find the twin. The negotiated Markdown response should include `Content-Location` with its `.md` URL. Also check that a missing page returns 404 and the published discovery files have the types declared in `resource-headers.json`.
 
-Run these checks against the production domain after deployment. Local preview results establish what Shoalrun's Node server does; they do not prove that a CDN applies the same rules. For a whole-site audit, run the [AFDocs scorecard](https://afdocs.dev/) against the deployed site and review its findings against the site's content requirements.
+Run these checks against the production domain after deployment. Local preview results establish what Shoalrun's Node server does; they don't prove that a CDN applies the same rules. For a whole-site audit, run the [AFDocs scorecard](https://afdocs.dev/) against the deployed site and review its findings against the site's content requirements.

package/agent-docs/publish/content-negotiation.sections/what-if-the-host-cannot-negotiate.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Content negotiation
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/content-negotiation.md)
 
@@ -42,6 +42,6 @@ Shoalrun builds two versions of every published page from one authored source. T
 
 ## What if the host cannot negotiate?
 
-GitHub Pages can publish Shoalrun's HTML, `.md` files, and `/llms.txt`. It serves static files and has no request handler for choosing a file from `Accept` or setting the page response headers described above. Agents can still read the `.md` URLs, but a request to the HTML URL cannot negotiate there. A programmable proxy or CDN can add that behavior. You can also publish the same built files on a host with request rules. Bare GitHub Pages cannot pass AFDocs' content-negotiation check.
+GitHub Pages can publish Shoalrun's HTML, `.md` files, and `/llms.txt`. It serves static files and has no request handler for choosing a file from `Accept` or setting the page response headers described above. Agents can still read the `.md` URLs, but a request to the HTML URL can't negotiate there. A programmable proxy or CDN can add that behavior. You can also publish the same built files on a host with request rules. Bare GitHub Pages can't pass AFDocs' content-negotiation check.
 
-`site.basePath` also prefixes assets, API contracts, `/llms.txt`, and discovery files. For a GitHub Pages project site at `/<repository>/`, set `site.basePath: /<repository>` and publish the matching subtree from the build output as the project site's root. GitHub Pages still cannot provide Markdown content negotiation at an HTML URL.
+`site.basePath` also prefixes assets, API contracts, `/llms.txt`, and discovery files. For a GitHub Pages project site at `/<repository>/`, set `site.basePath: /<repository>` and publish the matching subtree from the build output as the project site's root. GitHub Pages still can't provide Markdown content negotiation at an HTML URL.

package/agent-docs/publish/content-negotiation.sections/what-shoalrun-builds-and-what-the-host-does.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Content negotiation
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/content-negotiation.md)
 
@@ -44,6 +44,6 @@ Shoalrun builds two versions of every published page from one authored source. T
 
 Shoalrun creates the HTML page, its `.md` twin, and a [`/documents.json`](https://www.shoalrun.com/documents.json) manifest listing both URLs. It also writes [`/resource-headers.json`](https://www.shoalrun.com/resource-headers.json) with content types for Markdown and discovery files.
 
-The host receives each HTTP request. It must read `Accept` and select the right built file. Providers use different names for this step: a server handler, a routing rule, or an edge function. The HTTP behavior is the same. A static file alone cannot read a request header.
+The host receives each HTTP request. It must read `Accept` and select the right built file. Providers use different names for this step: a server handler, a routing rule, or an edge function. The HTTP behavior is the same. A static file alone can't read a request header.
 
 Shoalrun's Node server handles this. The standalone [Vercel build](https://www.shoalrun.com/publish/vercel.md) generates Vercel rules. On another host, use the contract below to configure its routing feature. The [host adapter guide](https://www.shoalrun.com/publish/host-adapters.md) covers adding Shoalrun's files to another build.

package/agent-docs/publish/content-negotiation.sections/why-this-matters.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Content negotiation
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/content-negotiation.md)
 
@@ -44,4 +44,4 @@ Shoalrun builds two versions of every published page from one authored source. T
 
 An agent reading HTML may receive navigation, styles, scripts, and interactive controls along with the article. It may then have to extract the useful content or convert the HTML to Markdown. Shoalrun's generated Markdown gives it the article directly, including material inside tabs and collapsibles and resolved OpenAPI examples. This can make the page easier to retrieve and less likely to lose content during conversion. [AFDocs checks](https://afdocs.dev/checks/markdown-availability) both `.md` URLs and content negotiation for this reason.
 
-The direct `.md` links in each HTML page and [`/llms.txt`](https://www.shoalrun.com/llms.txt) help agents that know to follow them. Negotiation helps an agent that arrives at the ordinary page URL and requests Markdown without first discovering a second URL. It does not require writers to maintain a separate article.
+The direct `.md` links in each HTML page and [`/llms.txt`](https://www.shoalrun.com/llms.txt) help agents that know to follow them. Negotiation helps an agent that arrives at the ordinary page URL and requests Markdown without first discovering a second URL. It doesn't require writers to maintain a separate article.

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

@@ -16,15 +16,15 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Check a deployed site
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
-A local build verifies the generated files. After deployment, check what the host actually serves. This guide uses `scripts/check-deployment.mjs` from Shoalrun's docs repository; the script is not included in the `@shoalrun/cli` package. From the docs repository root, pass the deployed **site origin** to the checker:
+A local build verifies the generated files. After deployment, check what the host actually serves. This guide uses `scripts/check-deployment.mjs` from Shoalrun's docs repository; the script isn't included in the `@shoalrun/cli` package. From the docs repository root, pass the deployed **site origin** to the checker:
 
 ```sh
 npm run deploy:check -- https://docs.example.com/
 ```
 
-Use the real HTTPS site URL and a trailing slash, including a configured base path such as `https://docs.example.com/docs/`. The command does not change the deployed site.
+Use the real HTTPS site URL and a trailing slash, including a configured base path such as `https://docs.example.com/docs/`. The command doesn't change the deployed site.
 
 For a branch deployment, pass the full hash that the deployment job checked out. The checker reads `/build-info.json` and fails if that domain serves a different revision:
 
@@ -34,7 +34,7 @@ npm run deploy:check -- https://docs.example.com/ --source-commit "$SOURCE_COMMI
 
 `SOURCE_COMMIT` must be a 40- or 64-character Git commit hash. Supply it from the job that deploys this origin, for example `git rev-parse HEAD` after checkout. A missing or mismatched record is a failure.
 
-For a site with hosted chat and search, add `--chat`. It checks the public chat settings and both endpoints: GET returns 405, a foreign origin returns 403, and an invalid same-origin request returns 400. Invalid requests stop before model or embedding calls. If chat is already paused, use `--chat --chat-paused` instead; the checker expects its 503 paused response. It does not change the pause flag.
+For a site with hosted chat and search, add `--chat`. It checks the public chat settings and both endpoints: GET returns 405, a foreign origin returns 403, and an invalid same-origin request returns 400. Invalid requests stop before model or embedding calls. If chat is already paused, use `--chat --chat-paused` instead; the checker expects its 503 paused response. It doesn't change the pause flag.
 
 ```sh
 npm run deploy:check -- https://docs.example.com/ --chat
@@ -51,13 +51,13 @@ The checker reads the deployed `/documents.json` and tests every listed page:
 - Canonical links point to the page being checked, and noindex matches the manifest's indexing choice.
 - `/robots.txt` advertises the sitemap when one exists. Every sitemap URL matches an indexable manifest page, every indexable page is listed once, and `lastmod` matches its metadata. The checker fetches child sitemaps and catches redirects and HTTP errors.
 
-It also checks `/llms.txt`, `/resource-headers.json`, and the API catalog when the resource headers declare one. It verifies discovery content types and that a random missing route returns 404 for both HTML and Markdown requests. This establishes the host's response behavior; it does not judge whether the authored HTML and Markdown prose mean the same thing.
+It also checks `/llms.txt`, `/resource-headers.json`, and the API catalog when the resource headers declare one. It verifies discovery content types and that a random missing route returns 404 for both HTML and Markdown requests. This establishes the host's response behavior; it doesn't judge whether the authored HTML and Markdown prose mean the same thing.
 
 ## Read the result
 
 The command prints a `PASS` or `FAIL` summary with request, document, and failure counts. On failure, each `FAIL` line names the route and the missing or incorrect response. For example, a Markdown response served as HTML is reported as a `Content-Type` failure. Fix the host route or headers, deploy again, and rerun the checker before release.
 
-Exit status `0` means every check passed, `1` means the deployed site failed one or more checks, and `2` means the command input is invalid. A passing result does not replace manual review, accessibility checks, or an external scorecard.
+Exit status `0` means every check passed, `1` means the deployed site failed one or more checks, and `2` means the command input is invalid. A passing result doesn't replace manual review, accessibility checks, or an external scorecard.
 
 The [content negotiation guide](https://www.shoalrun.com/publish/content-negotiation.md) defines the host-independent HTTP contract. The [Vercel guide](https://www.shoalrun.com/publish/vercel.md) shows one hosting recipe. The checker works against any provider that serves the same contract.
 

package/agent-docs/publish/deployment-profiles.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 > Customer editions
 
-**Updated: 2026-11-03.**
+**Updated: 2026-11-05.**
 
-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.
+**Available since: 0.1.0-alpha.15.**
 
-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.
 
 ## Before you begin
 
@@ -50,7 +50,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:
 
@@ -65,7 +65,7 @@ profiles:
 
 ## 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
 
@@ -82,7 +82,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
 
@@ -96,7 +96,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:
 
@@ -104,11 +104,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
 
@@ -119,7 +119,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
 
@@ -139,7 +139,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.
 
@@ -158,7 +158,7 @@ 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.
 
 ## Supply the profile from the deployment
 
@@ -188,21 +188,38 @@ 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.
+
+## 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.
 
 ## 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 \
+npx --no-install 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 \
+npx --no-install shoalrun export docs.config.yaml --out dist/customer-content \
   --profile /run/config/docs-profile.yaml
 ```
 
@@ -211,16 +228,33 @@ If several publications are enabled, an export still needs its normal explicit p
 Use the profile when [validating documentation edits](https://www.shoalrun.com/author/workspace.md):
 
 ```sh
-shoalrun docs baseline --config docs.config.yaml \
+npx --no-install 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 \
+npx --no-install 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.
 
+## 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.
+
 ## Choose navigation labels
 
 Navigation headings come from the shared project's ordinary navigation configuration. For example:
@@ -234,29 +268,29 @@ 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.
 
 ## 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.
 
 ## 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.
 
 ## 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.
 
 ## Related reading
 
@@ -270,4 +304,4 @@ Operation embeds respect the selection. Standalone `<ApiSchema api="..." schema=
 
 ### 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/before-you-begin.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.
 
 ## Before you begin
 

package/agent-docs/publish/deployment-profiles.sections/build-and-inspect-the-edition.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,25 +33,23 @@ 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.
 
 ## 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 \
+npx --no-install 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 \
+npx --no-install shoalrun export docs.config.yaml --out dist/customer-content \
   --profile /run/config/docs-profile.yaml
 ```
 
@@ -58,11 +58,11 @@ If several publications are enabled, an export still needs its normal explicit p
 Use the profile when [validating documentation edits](https://www.shoalrun.com/author/workspace.md):
 
 ```sh
-shoalrun docs baseline --config docs.config.yaml \
+npx --no-install 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 \
+npx --no-install shoalrun docs validate --config docs.config.yaml \
   --baseline .shoalrun/baseline.json --profile /run/config/docs-profile.yaml
 ```