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

package/AUTHORING.md

@@ -4,6 +4,23 @@ Detailed CLI and library contracts for project inspection, isolated validation,
 
 ## Project and reference tools
 
+Available since `0.1.0-alpha.18`. Product-aware publication selection preserves
+the product,
+channel, version, and language when reading a repeated stable page ID. For
+example, `shoalrun docs read guide.start --site site-dist --product payments
+--channel production --version v3 --language en --json` reads one product
+release. MCP clients can call the compact `get_publications` discovery tool
+first and follow its `nextOffset`; hosted endpoints still list only their
+configured publication.
+
+Use `shoalrun scaffold guide -n content/setup.mdx --product payments --version v3`
+to start a page in a selected product release. A product's omitted version uses
+its own configured default rather than another product's release. For customer
+edition review, `shoalrun dev docs.config.yaml site-dist --profile customers/acme.yaml`
+compiles and watches the same profile selection as a customer build. Reader
+views and the HTML publication dropdown do not replace build-time feature
+selection. See the [package README](README.md) for catalogs and preview behavior.
+
 These provider-free commands inspect an existing project without selecting a page:
 
 ```sh
@@ -267,3 +284,15 @@ The public library adds `authoringReview(reportFile)`,
 `review()` and idempotent `close()` plus the connection metadata. Always await
 `close()` in cleanup. API version 1 remains unchanged; capabilities add
 `snapshot-preview` and `authoring-review-report`.
+
+## Feature availability
+
+Use page-specific `availability: { since: VERSION }` frontmatter for the first
+supported release of the feature described by a page. Add `through: VERSION`
+for its last supported release, alone or with `since`; both boundaries are
+inclusive. Available since `0.1.0-alpha.18`. These are authored labels, not
+version comparisons or publication selectors. Do not infer a support boundary.
+HTML shows the labels beside page dates. Markdown retains readable labels and
+`documents.json` retains the object. For an option or section with a different
+availability, use `<Badge variant="neutral">Since VERSION</Badge>` beside it
+rather than changing the whole page's first supported release.

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 0.1.0-alpha.19 — 2026-11-05
+
+- Give your coding agent the `shoalrun-brand` skill to match a documentation
+  site to your brand. It guides the agent through choosing colors and fonts,
+  adding your logo, and applying theme settings and CSS. It also checks search
+  results, menus, buttons, keyboard focus, and mobile layouts for readability.
+  Read it with `shoalrun skills read shoalrun-brand`.
+- Make hosted chat verify where a visitor check came from. Turnstile responses
+  must match a trusted hostname and, when configured, the expected action.
+  A session pass from a different hostname/action policy no longer skips the
+  check, even when the deployments share a secret. Changing the policy
+  invalidates existing passes. Upgrade the CLI, then rebuild and
+  redeploy hosted chat to apply these protections.
+- Keep local and hosted test previews working with Turnstile's published test
+  keys. Local preview checks the actual dummy-token response; the documentation
+  site's hosted preview requires test credentials and a separate usage store.
+- Check development dependencies as well as production dependencies in both
+  repositories during a coordinated release. Update the documentation site's
+  browser tools and affected dependencies to remove the identified security
+  advisories without forcing incompatible package versions.
+- Add security headers to the documentation site that restrict framing to the
+  same origin and set an explicit referrer policy. Deployment checks now reject
+  responses missing the required headers. A broader Content Security Policy
+  starts in report-only mode so browser violations can be reviewed before
+  enforcement; it doesn't yet block scripts. These are site-owned settings,
+  not new defaults imposed on customer sites.
+- Refresh the repository and package READMEs with product versions, customer
+  editions, branding, application content delivery, and agent workflows. Update
+  the hosted-chat guide with hostname checks, optional actions, session passes,
+  and preview configuration.
+
+## 0.1.0-alpha.18 — 2026-11-04
+
+- Add authored page availability ranges with `since` and `through` version
+  labels. Reuse the release-version text style beside page dates, retain labels
+  in Markdown and metadata in the document manifest, and keep availability
+  separate from publication selection.
+
+- Add product publication catalogs with independent versions and default
+  versions. Product-aware publications preserve their identity through routes,
+  links, navigation, APIs, search, and content exports. Existing productless
+  publication identities and routes remain compatible.
+- Select product releases independently in customer deployment profiles,
+  alongside existing SKU revisions and feature grants. Continue to apply
+  `requires` and `<ForFeature>` during compilation across emitted content.
+- Accept `dev --profile FILE` to build, serve, and watch a customer edition in
+  one command. Watch external profile inputs, replace output after successful
+  rebuilds, and disclose failed rebuilds while serving the last successful
+  edition. Reload removed pages at the new edition's landing page.
+
+- Add bounded, paginated MCP `get_publications` discovery and retain product
+  coordinates in search read arguments. Emit v2 product content contracts while
+  preserving legacy v1 exports.
+
 ## 0.1.0-alpha.17 — 2026-11-04
 
 - Package hosted Ask and Search without importing source configuration or its

package/DEPLOYMENT-PROFILES.md

@@ -49,9 +49,76 @@ were never edited. Retain the manifest revision used for each deployment.
 Feature definitions accept optional `description` and `lifecycle` (`active`,
 `deprecated`, or `retired`). Lifecycle labels do not grant or remove features.
 
+## Select independently versioned products
+
+Available since `0.1.0-alpha.18`.
+
+A product catalog owns its versions rather than sharing one global version list:
+
+```yaml
+publications:
+  defaults: { channel: production, language: en }
+  channels:
+    production: {}
+  products:
+    payments:
+      pathPrefix: /payments
+      defaultVersion: v3
+      versions:
+        v2: { pathPrefix: /v2 }
+        v3: { pathPrefix: /v3 }
+    reporting:
+      pathPrefix: /reporting
+      defaultVersion: v1
+      versions:
+        v1: { pathPrefix: /v1 }
+  enabled:
+    - { product: payments, channel: production, version: v2 }
+    - { product: payments, channel: production, version: v3 }
+    - { product: reporting, channel: production, version: v1 }
+```
+
+A customer's profile narrows those exact coordinates independently:
+
+```yaml
+# Profile fragment
+publications:
+  enabled:
+    - { product: payments, channel: production, version: v3, language: en }
+    - { product: reporting, channel: production, version: v1, language: en }
+```
+
+Another customer can select Payments v2 and Reporting v1. A product release does
+not grant features; SKU revisions and direct grants remain independent. Unknown
+products, unknown product-local versions, and selections outside the shared
+`enabled` list fail. No lookup substitutes another product's matching version.
+
+Pages select `product`, `channel`, and `version`, or explicitly list those
+coordinates in `publications` to reuse a source. Do not combine a membership
+list with page-level product/channel/version. A stable document ID keeps the same
+document type across publications. `shared: true` classifies feature eligibility;
+it does not copy a page into other product releases. `<ForPublication>` also
+accepts `product` for sections.
+
+Routes combine site base path, nondefault language, product prefix, channel
+prefix, version prefix, and slug. For example, `/start` in Payments v3 becomes
+`/payments/v3/start`. An omitted product version resolves its `defaultVersion`,
+unless matching `publications.defaults.product` supplies a valid scoped version.
+An inherited global frontmatter version is not a product default.
+
+Without a product catalog, existing `frontmatter.product` remains metadata and an
+optional reader facet. Declaring `publications.products` opts into publication
+identity: review old product values, declare each product's versions, and update
+page and profile memberships. Root `publications.versions` can remain for
+productless pages. Existing productless identities and routes remain unchanged;
+productless pages are not automatically replicated. Add redirects when product
+prefixes move previously published URLs, then rebuild indexes and exports.
+
 ## Supply one profile per deployment
 
-The deployment can mount or generate this file outside the documentation repo:
+The deployment can mount or generate this file outside the documentation repo.
+This example selects a productless `current` publication. For the product catalog
+above, use its product-qualified publication selection instead:
 
 ```yaml
 schemaVersion: 1
@@ -234,6 +301,27 @@ shared and requirements on the same declaration. General frontmatter defaults
 do not count; classify operations individually when their requirements differ.
 Authored API reference pages follow the ordinary source-page rule.
 
+## Preview the selected edition
+
+Available since `0.1.0-alpha.18`.
+
+```sh
+npx --no-install shoalrun dev docs.config.yaml site-dist \
+  --profile /run/config/docs-profile.yaml --port 8770
+```
+
+The preview uses the same compilation and content pruning as `build --profile`.
+It watches the selected profile, manifest, declared branding assets, and content,
+including declared inputs mounted outside the project. Keep separate outputs and
+ports for concurrent customer previews.
+
+The development banner identifies the selected profile, edition digest, and
+successful build. Invalid initial input prevents startup. A later failed rebuild
+keeps the last successful edition and displays its failure; it never falls back
+to unprofiled output. Saving corrected declared inputs triggers recovery. A
+successful profile change that removes the current page navigates to a published
+landing page. On older releases, use a profiled build followed by `serve`.
+
 ## Validate the deployment edition
 
 Use the same profile when recording a baseline and validating:
@@ -272,14 +360,17 @@ requirements inherited through frontmatter defaults.
 
 Profiled builds reject full OpenAPI source publication, because hiding reference
 pages does not remove operations from that source. Use `source.publish: false`
-and `source.focused: true` for focused operation downloads. Operation embeds
+and `source.focused: true` for focused operation downloads. API source bindings
+include product/channel/version; documentation languages reuse that source.
+Full-source publication outside profiled builds writes one source artifact across
+translations. Source availability never falls back to another product or release. Operation embeds
 respect selection. Standalone `<ApiSchema api="..." schema="..." />` embeds are
 not supported in profiled builds; use an eligible operation embed instead.
 
 Static `vercel build --profile FILE` is supported. Profiled chat-function builds
-are not supported. Other commands without a profile option, including `dev` and
-checked-plan authoring, do not yet resolve deployment editions; use build/serve
-or captured validation/preview.
+are not supported. Checked-plan authoring does not resolve deployment editions;
+use captured validation/preview. Profile-aware development is described in the
+preview workflow above.
 
 Shoalrun does not fetch billing records, infer contract terms, expire grants, or
 authenticate customers. The deployment supplies the declared edition and the

package/README.md

@@ -1,6 +1,6 @@
 # Shoalrun
 
-Shoalrun turns Markdown and MDX into a documentation website and Markdown pages from the same content. People can browse the site; agents can read the Markdown. Native components such as steps, tabs, and API references preserve their content in both formats.
+Shoalrun builds a documentation website, Markdown pages, and application content from the same Markdown and MDX source. People can browse the site; applications and agents can read stable documents, sections, and snippet instances. Native components keep essential instructions and API details readable in both HTML and Markdown.
 
 This package provides the `shoalrun` CLI, starter projects, agent skills, and offline documentation. It requires Node.js 22.12 or newer. This alpha is distributed through the public npm registry. Installation requires no npm account or package token.
 
@@ -9,17 +9,9 @@ This package provides the `shoalrun` CLI, starter projects, agent skills, and of
 From the project where you want to keep your documentation:
 
 ```sh
-npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.17
+npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.19
 ```
 
-If you previously used the private GitHub Packages alpha, check `npm config get @shoalrun:registry`. Remove or replace any `@shoalrun:registry=https://npm.pkg.github.com` entry in your project or user `.npmrc`. You can explicitly select the public registry for the upgrade:
-
-```sh
-npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.17 --@shoalrun:registry=https://registry.npmjs.org
-```
-
-Commit the updated package manifest and lockfile together. Check that the lockfile resolves `@shoalrun/cli` from `registry.npmjs.org`. Keep any credentials needed by other private dependencies; Shoalrun itself no longer needs a package token.
-
 ## Create and preview a site
 
 Run these commands from the directory where you installed the package:
@@ -38,9 +30,88 @@ npx --no-install shoalrun dev my-docs/docs.config.yaml my-docs/site-dist --port
 
 Stop the existing preview with Ctrl-C before starting the development server on the same port. Choose **Explore the starter**, the first item in the left navigation, to find component examples, diagrams, reader views, themes, and generated API references. The service and API hosts are fictional; replace them before sending requests. Choose `--starter minimal` for a smaller starting point or `--starter api-docs` for a focused OpenAPI example. All three starters build without provider credentials.
 
+## What you can build
+
+The [features overview](https://www.shoalrun.com/features) describes the complete authoring and delivery workflow. Start with the part you need:
+
+| Need | Capability |
+| --- | --- |
+| A documentation site | Pages, navigation, local preview, themes, palettes, fonts, and project CSS. |
+| Reusable procedures | Recipes, shared ingredients, and cookbooks that help readers choose a complete task. |
+| API reference | OpenAPI operation pages, code examples, focused contracts, and an explicit source-review gate. |
+| Several product releases | Independent product versions and defaults, publication routes, and a header publication selector. |
+| Customer editions | External profiles, SKU revisions, feature grants, and conditional pages or sections. |
+| Application help | HTML and Markdown exports, stable page/section/snippet references, static and REST clients, and instance-safe mounting. |
+| Agent discovery | Markdown twins, compact linked indexes, read-only MCP tools, bundled skills, and offline references. |
+| Search and answers | Browser keyword search, optional semantic retrieval, and hosted documentation chat with shared limits. |
+
+Local builds and keyword search need no provider credentials. Semantic retrieval and generated answers use separately configured services; credentials stay server-side. Reader filters are browsing controls, not authorization. Customer profiles select output during compilation; private-edition hosting remains your responsibility.
+
+## Match your brand
+
+Use `site.logo`, `site.favicon`, and header settings for site identity. Choose a theme preset and configure `theme.palette`, `theme.mode`, and `theme.fonts`. Use `site.customCss` for changes beyond those settings. Customer profiles can supply deployment-owned branding without storing customer records in the shared source.
+
+Check controls and interactive states as well as article text: a dark header can contain light inputs, menus, and search results. Palette validation doesn't check arbitrary project CSS. See [themes and fonts](https://www.shoalrun.com/styling/themes), the [CSS reference](https://www.shoalrun.com/author/css), and [deployment profiles](DEPLOYMENT-PROFILES.md).
+
+## Independently versioned products
+
+Projects can give each product its own version catalog and default version. Product publications carry a product, channel, version, and language; routes, document links, navigation, search, and content exports retain that scope. Existing projects without product catalogs keep their publication identities and routes.
+
+Product catalogs and profile-aware development preview are available since `0.1.0-alpha.18`. The product names and versions below are an example configuration.
+
+The header publication dropdown groups the published releases by product. It hides language labels when the edition has one language; set `site.publicationSelector.showLanguage: true` or `false` to override that display without changing publication identity.
+
+```yaml
+publications:
+  defaults: { channel: production, language: en }
+  channels:
+    production: {}
+  products:
+    payments:
+      label: Payments
+      pathPrefix: /payments
+      defaultVersion: v3
+      versions:
+        v3: { pathPrefix: /v3 }
+        v2: { pathPrefix: /v2 }
+    reporting:
+      label: Reporting
+      pathPrefix: /reporting
+      defaultVersion: v1
+      versions:
+        v1: { pathPrefix: /v1 }
+  enabled:
+    - { product: payments, channel: production, version: v3 }
+    - { product: payments, channel: production, version: v2 }
+    - { product: reporting, channel: production, version: v1 }
+```
+
+Declare a page's product and version in its frontmatter; omitting its version selects that product's `defaultVersion`. To reuse a source across product releases, list explicit product/channel/version entries in `publications` instead of setting those fields at page level. A page with slug `/setup` in the Payments v3 publication above is published at `/payments/v3/setup`. Product selection does not grant feature access: page-level `requires` and section-level `<ForFeature>` still select content from the customer's feature grants.
+
+An existing customer profile can narrow the shared enabled publications independently for each product:
+
+```yaml
+schemaVersion: 1
+features: [] # Or declare SKU revisions and additional feature grants.
+publications:
+  enabled:
+    - { product: payments, channel: production, version: v3 }
+    - { product: reporting, channel: production, version: v1 }
+```
+
+The shared configuration must declare `profiles.manifest`, which defines the known features and SKU revisions. Each selected publication must be enabled by that configuration. Preview the customer edition directly:
+
+```sh
+npx --no-install shoalrun dev docs.config.yaml site-dist --profile customers/example.yaml --port 8770
+```
+
+The development server compiles the selected edition and watches its profile, SKU manifest, and declared assets, including files outside the project. Editing the profile rebuilds the edition and removes output that is no longer selected. The preview identifies the last successful edition. If a rebuild fails, it keeps that output and displays the failure on existing and newly opened pages. Reader views remain browsing controls; customer profile selection applies during compilation to HTML, Markdown, navigation, and indexes.
+
+Agents can discover product scopes through MCP `get_publications` before searching. It returns a short, paginated list (20 publications and a 2,048-token budget by default), with only the relevant product labels and defaults. Search results supply scoped read arguments; catalogs are stored once in `documents.json`, rather than repeated in every page. Product-aware content exports use schema version 2; legacy exports remain version 1.
+
 ## Work with an agent
 
-Shoalrun works with your existing coding agent. Its packaged skills explain how to set up a site, edit pages, and develop components:
+Shoalrun works with your existing coding agent. Its packaged skills cover setup, page authoring, components, recipes, and walkthroughs. Use `skills list` to discover the skills included with your installed version:
 
 ```sh
 npx --no-install shoalrun skills list
@@ -49,7 +120,7 @@ npx --no-install shoalrun skills read shoalrun-setup
 
 Ask your agent to read the skill for the task. `skills list` returns names, descriptions, and local instruction-file paths. These commands read the skills; installing the npm package does not automatically install them into your agent.
 
-The usual editing workflow is to capture a baseline, edit source files, validate the changes, then review a local preview. From your documentation project directory:
+The editing workflow is to capture a baseline, edit source files, validate the changes, then review a local preview. From your documentation project directory:
 
 ```sh
 npx --no-install shoalrun docs baseline --out .shoalrun/task-baseline.json
@@ -57,7 +128,7 @@ npx --no-install shoalrun docs baseline --out .shoalrun/task-baseline.json
 npx --no-install shoalrun docs validate --baseline .shoalrun/task-baseline.json
 ```
 
-Validation returns a report path. Pass that path to `shoalrun docs review` and `shoalrun docs preview`. Snapshot validation can render affected draft pages while preserving their draft access; ordinary site builds exclude drafts. Supply your own project writing and review requirements—the starter does not define them for you.
+Validation returns a report path. Pass that path to `shoalrun docs review` and `shoalrun docs preview`. Snapshot validation can render affected draft pages while preserving their draft access; ordinary site builds exclude drafts. Supply your own project writing and review requirements. Configured checks and custom plugins execute trusted project code; a validation copy is not an operating-system sandbox.
 
 ## Find documentation
 
@@ -241,18 +312,6 @@ The limit applies to each index response, not an entire multi-step reading sessi
 An individual title or summary too large to fit an index produces an explicit
 build error rather than silently dropping content.
 
-## Status and development
-
-This alpha may change configuration and output formats between releases. No compatibility promise or maintained older release line is offered yet. Creating and previewing a basic site does not require a model provider or Chrome. Optional provider-backed features require their own configuration.
-
-Shoalrun is maintainer-led and does not accept unsolicited pull requests at this time. The [repository development instructions](https://github.com/shoalrun/shoalrun#develop-the-framework) explain how to build and test your own checkout or fork.
-
-Pin an exact package version and read the [changelog](CHANGELOG.md) before upgrading. Rebuild and check HTML, Markdown, links, and any application consuming exported content before deploying. See the [contribution policy](https://github.com/shoalrun/shoalrun/blob/main/CONTRIBUTING.md) and [security policy](https://github.com/shoalrun/shoalrun/blob/main/SECURITY.md) for reporting problems and project trust boundaries.
-
-## License
-
-Copyright 2026 Casey Smith. This package is licensed under [Apache-2.0](LICENSE). Your authored site content keeps its own license. Built sites contain runtime assets and may contain copied template text; retain applicable licenses and third-party notices when distributing them.
-
 ## Verification dates
 
 Set `verified` only after checking a page's technical claims. It is separate from
@@ -271,3 +330,25 @@ in HTML only; Markdown and manifest metadata retain it. Set
 `frontmatter.defaults.showVerified: false` in project configuration for a shared
 default, then override it with `showVerified: true` on individual pages. A layout
 with a Hero replaces the standard page header and does not display its dates.
+
+## Upgrade from the earlier private registry
+
+If you previously used the private GitHub Packages alpha, check `npm config get @shoalrun:registry`. Remove or replace any `@shoalrun:registry=https://npm.pkg.github.com` entry in your project or user `.npmrc`. You can explicitly select the public registry for the upgrade:
+
+```sh
+npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.19 --@shoalrun:registry=https://registry.npmjs.org
+```
+
+Commit the updated package manifest and lockfile together. Check that the lockfile resolves `@shoalrun/cli` from `registry.npmjs.org`. Keep any credentials needed by other private dependencies; Shoalrun itself no longer needs a package token.
+
+## Status and development
+
+This alpha may change configuration and output formats between releases. No compatibility promise or maintained older release line is offered yet. Creating and previewing a basic site does not require a model provider or Chrome. Optional provider-backed features require their own configuration.
+
+Shoalrun is maintainer-led and does not accept unsolicited pull requests at this time. The [repository development instructions](https://github.com/shoalrun/shoalrun#develop-the-framework) explain how to build and test your own checkout or fork.
+
+Pin an exact package version and read the [changelog](CHANGELOG.md) before upgrading. Rebuild and check HTML, Markdown, links, and any application consuming exported content before deploying. See the [contribution policy](https://github.com/shoalrun/shoalrun/blob/main/CONTRIBUTING.md) and [security policy](https://github.com/shoalrun/shoalrun/blob/main/SECURITY.md) for reporting problems and project trust boundaries.
+
+## License
+
+Copyright 2026 Casey Smith. This package is licensed under [Apache-2.0](LICENSE). Your authored site content keeps its own license. Built sites contain runtime assets and may contain copied template text; retain applicable licenses and third-party notices when distributing them.

package/agent-docs/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt

@@ -4,40 +4,46 @@ Full-page token counts use cl100k_base. Navigation section ID: project-updates.
 
 [All sections and published pages](https://www.shoalrun.com/llms.min.txt). This index covers this section only; shared and unlisted pages remain reachable through the global index. Reader views do not remove pages from this index.
 
-- [Agent discovery, verified Markdown, and incremental sync](https://www.shoalrun.com/changelog/2026-10-14-agent-readiness.md) — ID: change.agent-readiness. changelog-entry; 546 tokens. Compact discovery, content verification, and incremental fetching.
+- [Agent discovery, verified Markdown, and incremental sync](https://www.shoalrun.com/changelog/2026-10-14-agent-readiness.md) — ID: change.agent-readiness. changelog-entry; 547 tokens. Compact discovery, content verification, and incremental fetching.
 
-- [Agent reading and evaluation](https://www.shoalrun.com/changelog/2026-10-15-evaluation-builds.md) — ID: change.evaluation-builds. changelog-entry; 1696 tokens. Smaller reads, lifecycle guidance, and reproducible evaluations.
+- [Agent reading and evaluation](https://www.shoalrun.com/changelog/2026-10-15-evaluation-builds.md) — ID: change.evaluation-builds. changelog-entry; 1702 tokens. Smaller reads, lifecycle guidance, and reproducible evaluations.
 
-- [Content exports and documentation checks](https://www.shoalrun.com/changelog/2026-10-25.md) — ID: change.2026-10-25. changelog-entry; 668 tokens. Content exports and documentation checks.
+- [Content exports and documentation checks](https://www.shoalrun.com/changelog/2026-10-25.md) — ID: change.2026-10-25. changelog-entry; 669 tokens. Content exports and documentation checks.
 
 - [Safer exports and easier discovery for AI assistants](https://www.shoalrun.com/changelog/2026-10-26.md) — ID: change.2026-10-26. changelog-entry; 1288 tokens. Keep exported images and links with their pages, and help AI assistants find docs by topic.
 
-- [Clearer defaults, a feature showcase, and easier navigation](https://www.shoalrun.com/changelog/2026-10-27.md) — ID: change.2026-10-27. changelog-entry; 1223 tokens. Explore a complete starter, read clearer controls, and find focused configuration references alongside the new mobile navigation.
+- [Clearer defaults, a feature showcase, and easier navigation](https://www.shoalrun.com/changelog/2026-10-27.md) — ID: change.2026-10-27. changelog-entry; 1219 tokens. Explore a complete starter, read clearer controls, and find focused configuration references alongside the new mobile navigation.
 
-- [Content delivery, verification dates, and clearer references](https://www.shoalrun.com/changelog/2026-10-28.md) — ID: change.2026-10-28. changelog-entry; 1393 tokens. Reuse documentation through static bundles or REST, display technical verification dates, and find clearer API and layout guidance.
+- [Content delivery, verification dates, and clearer references](https://www.shoalrun.com/changelog/2026-10-28.md) — ID: change.2026-10-28. changelog-entry; 1390 tokens. Reuse documentation through static bundles or REST, display technical verification dates, and find clearer API and layout guidance.
 
-- [Readable selections and wider layouts](https://www.shoalrun.com/changelog/2026-10-30.md) — ID: change.2026-10-30. changelog-entry; 507 tokens. Keep selected text readable and let paragraphs and lists fill expanded layouts.
+- [Readable selections and wider layouts](https://www.shoalrun.com/changelog/2026-10-30.md) — ID: change.2026-10-30. changelog-entry; 509 tokens. Keep selected text readable and let paragraphs and lists fill expanded layouts.
 
-- [Customer documentation editions](https://www.shoalrun.com/changelog/2026-11-03.md) — ID: change.2026-11-03. changelog-entry; 779 tokens. Build branded customer editions from purchased and grandfathered features without storing customer profiles in the shared repository.
+- [Customer documentation editions](https://www.shoalrun.com/changelog/2026-11-03.md) — ID: change.2026-11-03. changelog-entry; 782 tokens. Build branded customer editions from purchased and grandfathered features without storing customer profiles in the shared repository.
 
-- [Authoring snapshot previews and review reports](https://www.shoalrun.com/changelog/authoring-preview.md) — ID: change.authoring-preview. changelog-entry; 551 tokens. Snapshot previews with coverage and freshness reports.
+- [Independent product versions and customer previews](https://www.shoalrun.com/changelog/product-publications.md) — ID: change.product-publications. changelog-entry; 1042 tokens. Publish independent product releases together and preview each customer's selected edition while editing.
 
-- [Agent authoring, search, and documentation answers](https://www.shoalrun.com/changelog/authoring-search.md) — ID: change.authoring-search. changelog-entry; 466 tokens. Reviewed agent drafts, search improvements, and answer context.
+- [Smaller hosted search and Ask functions](https://www.shoalrun.com/changelog/2026-11-04-runtime-packaging.md) — ID: change.2026-11-04-runtime-packaging. changelog-entry; 647 tokens. Rebuild hosted docs with alpha.17 to reduce deployment files while keeping semantic search and Ask available.
 
-- [Working-tree authoring tools](https://www.shoalrun.com/changelog/authoring-tools.md) — ID: change.authoring-tools. changelog-entry; 378 tokens. Project discovery and captured working-tree validation.
+- [Branding guidance and safer hosted chat](https://www.shoalrun.com/changelog/branding-security.md) — ID: change.branding-security. changelog-entry; 936 tokens. Match your documentation to your brand with an agent skill, and bind hosted-chat visitor checks to the intended site.
 
-- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 1202 tokens. Compiler, CLI, and reader changes.
+- [Authoring snapshot previews and review reports](https://www.shoalrun.com/changelog/authoring-preview.md) — ID: change.authoring-preview. changelog-entry; 554 tokens. Snapshot previews with coverage and freshness reports.
 
-- [MCP hosting, analytics, and component improvements](https://www.shoalrun.com/changelog/2026-10-17-mcp-hosting.md) — ID: change.mcp-hosting. changelog-entry; 1145 tokens. MCP hosting, analytics, and shared component content.
+- [Agent authoring, search, and documentation answers](https://www.shoalrun.com/changelog/authoring-search.md) — ID: change.authoring-search. changelog-entry; 468 tokens. Reviewed agent drafts, search improvements, and answer context.
 
-- [Navigation, page layouts, and browser analytics](https://www.shoalrun.com/changelog/2026-10-16-navigation-layouts.md) — ID: change.navigation-layouts. changelog-entry; 1092 tokens. Navigation sections, reader controls, layouts, and browser analytics.
+- [Working-tree authoring tools](https://www.shoalrun.com/changelog/authoring-tools.md) — ID: change.authoring-tools. changelog-entry; 384 tokens. Project discovery and captured working-tree validation.
 
-- [Search results and tooltips](https://www.shoalrun.com/changelog/2026-10-18-search-and-tooltips.md) — ID: change.search-and-tooltips. changelog-entry; 668 tokens. Indexed search and hover and focus tooltips.
+- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 1407 tokens. Compiler, CLI, and reader changes.
 
-- [Experimental visual navigation and taxonomy enforcement](https://www.shoalrun.com/changelog/2026-10-19-visual-navigation.md) — ID: change.visual-navigation. changelog-entry; 746 tokens. Visual navigation and taxonomy validation.
+- [MCP hosting, analytics, and component improvements](https://www.shoalrun.com/changelog/2026-10-17-mcp-hosting.md) — ID: change.mcp-hosting. changelog-entry; 1147 tokens. MCP hosting, analytics, and shared component content.
 
-- [Portable working-tree authoring workflow](https://www.shoalrun.com/changelog/working-tree-skill.md) — ID: change.working-tree-skill. changelog-entry; 478 tokens. Agent discovery, native editing, validation, and snapshot review.
+- [Navigation, page layouts, and browser analytics](https://www.shoalrun.com/changelog/2026-10-16-navigation-layouts.md) — ID: change.navigation-layouts. changelog-entry; 1095 tokens. Navigation sections, reader controls, layouts, and browser analytics.
+
+- [Search results and tooltips](https://www.shoalrun.com/changelog/2026-10-18-search-and-tooltips.md) — ID: change.search-and-tooltips. changelog-entry; 675 tokens. Indexed search and hover and focus tooltips.
+
+- [Experimental visual navigation and taxonomy enforcement](https://www.shoalrun.com/changelog/2026-10-19-visual-navigation.md) — ID: change.visual-navigation. changelog-entry; 750 tokens. Visual navigation and taxonomy validation.
+
+- [Portable working-tree authoring workflow](https://www.shoalrun.com/changelog/working-tree-skill.md) — ID: change.working-tree-skill. changelog-entry; 483 tokens. Agent discovery, native editing, validation, and snapshot review.
 
 - [Non-goals](https://www.shoalrun.com/non-goals.md) — ID: guide.non-goals. explanation; 821 tokens. Scope limits for skill generation, agent orchestration, and reader-view authorization.
 
-- [Project status](https://www.shoalrun.com/status.md) — ID: guide.status. reference; 1651 tokens. Current capabilities, planned features, and known limits.
+- [Project status](https://www.shoalrun.com/status.md) — ID: guide.status. reference; 1850 tokens. Current capabilities, planned features, and known limits.

package/agent-docs/SNAPSHOT.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "sourceRepository": "https://github.com/shoalrun/docs",
-  "sourceCommit": "8102004b610ce6f6ea772d7c185809618c660f90",
-  "siteBuildId": "60f6dc0eaa4cc7c73333e0bdfdf837bdd83c1636d96a92e98e93b28bbdfcb773",
-  "manifestDigest": "79a5524ecf5a8dfc44207e1d72b7558805cc6545b9178d2b6facdde584e43d37",
-  "indexDigest": "640a2d074122ba753fd3f5ab9bd7200809db7e5c25e0af02927f5b58aafd67c3",
-  "packageIntegrity": "sha512-5N/QcKQJaX3YZ3EUBPWAaBmvIR+bphIJnijgQtIKpYd22MrMGU+gtmB1Ke9Cpw9KgNCtImQsnNKt5gTUID8Mvw=="
+  "sourceCommit": "27e393134027da5587c4102f6d4a4e9598f2bed5",
+  "siteBuildId": "3ca70f64a4b3562b2c51fd6a4a6beceb3578705d2fc545b7788589aebd0e6ff5",
+  "manifestDigest": "2fb2a205cf322384919c7546e0626c42de82c34cfcdc2f5e244c92968993fd03",
+  "indexDigest": "66cbcb506a60f1a1588e76135ab195c1491cb69337526f21979aed936d4478c5",
+  "packageIntegrity": "sha512-UMknmhUPoDv6tSOUlIjfeEuOHANy/+pEouq8wGEXlAxN9uRaVqcO/bSRcXQkLZvWLIolLcqkFDRjAUzVNimFDA=="
 }

package/agent-docs/api-docs/focused-contracts.md

@@ -17,13 +17,13 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > API support > Focused OpenAPI contracts
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 A **focused contract** is a generated OpenAPI JSON file for one operation. It contains that operation's path and method, parameters, request and response definitions, named examples, and the schemas and security schemes those definitions use. The build resolves local references so the file stands on its own. Each API reference page links to its focused contract.
 
 ## Why use one
 
-An API reference page is made for reading. A focused contract gives an agent, test tool, or client generator the exact machine-readable shape of the operation. A large OpenAPI source can contain many unrelated operations and schemas; the focused file keeps the context to what this operation needs. It is also useful when the full source should stay internal but a selected operation can be published.
+An API reference page is made for reading. A focused contract gives an agent, test tool, or client generator the exact machine-readable shape of the operation. A large OpenAPI source can contain many unrelated operations and schemas; the focused file keeps the context to what this operation needs. It's also useful when the full source should stay internal but a selected operation can be published.
 
 ## Generate and inspect it
 
@@ -53,9 +53,9 @@ The focused contract describes the selected operation, not the entire API. Use t
 - It drops every `x-*` extension key, so vendor extensions and internal notes stored there stay out of the public file.
 - It supports local OpenAPI 3.0.x and 3.1.x files with internal and multi-file references. Referenced files must stay inside the main OpenAPI file's directory, including after resolving symlinks. Absolute local paths are rejected. A Path Item `$ref`, or a JSON Schema `$id`, `$anchor`, `$dynamicRef`, or `$dynamicAnchor`, stops the build.
 
-The URL pattern is `/api/operations/<channel>/<version>/<language>/<name>-<sha256>.json`. The suffix is the full SHA-256 of the generated JSON bytes. Changing the contract changes its URL; an unchanged contract keeps the same URL. Earlier prototype filenames hashed the operation ID, which did not provide this property.
+The URL pattern is `/api/operations/<channel>/<version>/<language>/<name>-<sha256>.json`. The suffix is the full SHA-256 of the generated JSON bytes. Changing the contract changes its URL; an unchanged contract keeps the same URL. Earlier prototype filenames hashed the operation ID, which didn't provide this property.
 
-The generated hosting metadata gives these URLs `Cache-Control: public, max-age=31536000, immutable` and a strong ETag containing the same digest. The Node server applies these headers, and the Vercel adapter includes them in its routing configuration. A CDN can replace the ETag with its own validator. Use the returned ETag for conditional requests and the manifest's `focusedContractDigest` to verify downloaded bytes. Mutable Markdown and JSON indexes require revalidation. Other hosts must apply the generated cache policy. Old builds are not archived automatically, so the URL identity does not guarantee permanent availability. To check every contract in a built site, run `shoalrun api focused-audit <site-directory>`. The [CLI reference](https://www.shoalrun.com/cli.md) lists what it checks.
+The generated hosting metadata gives these URLs `Cache-Control: public, max-age=31536000, immutable` and a strong ETag containing the same digest. The Node server applies these headers, and the Vercel adapter includes them in its routing configuration. A CDN can replace the ETag with its own validator. Use the returned ETag for conditional requests and the manifest's `focusedContractDigest` to verify downloaded bytes. Mutable Markdown and JSON indexes require revalidation. Other hosts must apply the generated cache policy. Old builds aren't archived automatically, so the URL identity doesn't guarantee permanent availability. To check every contract in a built site, run `shoalrun api focused-audit <site-directory>`. The [CLI reference](https://www.shoalrun.com/cli.md) lists what it checks.
 
 ## Related reading