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

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,45 @@
 # Changelog
 
+## 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
+  component compiler, icon, syntax-highlighting, math-rendering, and esbuild
+  dependencies. Hosted functions consume resolved settings; local commands
+  retain source-config loading.
+- Build Search from its own dependency closure and private retrieval files,
+  without chat generation, answer cards, or third-party runtime packages.
+  Preserve existing hosted metadata and deep imports for compatibility.
+- Keep prepared search scoring and snippets separate from Markdown preparation,
+  and retain runtime and dependency licenses in function packages.
+- Test isolated function imports and requests, enforce per-runtime file/byte
+  budgets, and reject build-only dependencies in hosted runtime packages.
+
+No configuration migration is required. Upgrade the CLI and rebuild the hosted
+bundle to apply the smaller function packages; existing deployments are unchanged.
+
 ## 0.1.0-alpha.16 — 2026-11-04
 
 - Set `outputs.html.search.provider: semantic` to connect the search box to

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

@@ -9,13 +9,13 @@ 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.15
+npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.18
 ```
 
 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.15 --@shoalrun:registry=https://registry.npmjs.org
+npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.18 --@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.
@@ -38,6 +38,62 @@ 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.
 
+## 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.
+
+Available since `0.1.0-alpha.18`.
+
+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/acme.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:
@@ -69,7 +125,7 @@ npx --no-install shoalrun docs search "Steps" --json
 npx --no-install shoalrun docs read guide.component.steps --json
 ```
 
-Alpha.12 includes the reviewed documentation refresh: clearer organization, installed-package workflows, and consistent explanations of HTML, Markdown, and agent behavior. The bundled snapshot stays fixed until you upgrade the package.
+The bundled documentation is a reviewed, pinned snapshot. Its provenance lives in `agent-docs/SNAPSHOT.json`; it does not automatically follow the live site.
 
 See the [authoring command reference](AUTHORING.md) for project inspection, validation, report schemas, and the public authoring API. Visit [shoalrun.com](https://www.shoalrun.com) for the full documentation; it may describe changes newer than your installed package.
 

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

@@ -4,40 +4,44 @@ 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.
+- [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.
 
-- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 1202 tokens. Compiler, CLI, and reader changes.
+- [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.
 
-- [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.
+- [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.
 
-- [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.
+- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 1337 tokens. Compiler, CLI, and reader changes.
 
-- [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.
+- [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.
 
-- [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.
+- [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.
 
-- [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.
+- [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": "52c055cc160abbcb931bacbd8fcd209ce834cb26",
-  "siteBuildId": "c8c2a551d388148cf830e85bea3a58118a3a935dc91fa043ab2cd2a178ff9c6c",
-  "manifestDigest": "3c6af9a8161232cd4e824e72a427fb2b2a21963939a761a5f0f3557415dba580",
-  "indexDigest": "a6153f8a9a12541db3a6d1608c33da30ad329a6ad1653324f308dbd824bd9c10",
-  "packageIntegrity": "sha512-2Of7hhwylA4zWfoWIISM+0E63RzMhK9yI/NErSoNaUhquYQSD8iED1AWiUzqabnE0hg9rdtxCt82ws5+R9D3bQ=="
+  "sourceCommit": "201a4e562b70414e26ecba7c2488ba899550f06b",
+  "siteBuildId": "41390a172a8dbd578761e016a1c5890718f0b06c37f90b40769f585f75fd71ec",
+  "manifestDigest": "b0996def2c34eaafbb41b5ab5b3ca0e78a370a620ffb4b8bfe53bc6248300d05",
+  "indexDigest": "ed3b6ccce7e13cb3d038707a22430a76367522344d879a166d2764d445c16e06",
+  "packageIntegrity": "sha512-91enZzr2NCzCFo8OXfEZWjI7SQD+FVlFtEwRD30UKaMD3OBjgVY0wBgZyvVULXMUoZkdbyOj/OpdfDw/Tkk1ww=="
 }

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
 

package/agent-docs/api-docs/generate.md

@@ -17,15 +17,15 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Generate and select API pages
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `@shoalrun/cli` installed as in the [quickstart](https://www.shoalrun.com/start.md).
 
 ## Choose generated references or MDX
 
-Use build-time generated references when the OpenAPI contract already gives readers the method, path, parameters, schemas, and examples they need. The pages update whenever the reviewed source changes, and there are no MDX files to maintain. Use an authored MDX reference when an endpoint needs a reviewed introduction, prerequisites, limitations, or task-specific context that the contract cannot express. The compiler still appends the contract details from OpenAPI, so do not copy field tables and example payloads into MDX. Use a guide for a task spanning several endpoints; link its reference pages with `relatedApiReferences`.
+Use build-time generated references when the OpenAPI contract already gives readers the method, path, parameters, schemas, and examples they need. The pages update whenever the reviewed source changes, and there are no MDX files to maintain. Use an authored MDX reference when an endpoint needs a reviewed introduction, prerequisites, limitations, or task-specific context that the contract can't express. The compiler still appends the contract details from OpenAPI, so don't copy field tables and example payloads into MDX. Use a guide for a task spanning several endpoints; link its reference pages with `relatedApiReferences`.
 
-The one-time `api materialize` command creates draft MDX references for every endpoint or selected source operation IDs or method/path routes. It does not change config or navigation and never rewrites an existing page. For example:
+The one-time `api materialize` command creates draft MDX references for every endpoint or selected source operation IDs or method/path routes. It doesn't change config or navigation and never rewrites an existing page. For example:
 
 ```sh
 npx --no-install shoalrun api materialize notes docs.config.yaml --all
@@ -35,7 +35,7 @@ npx --no-install shoalrun api materialize notes docs.config.yaml --route 'GET /n
 
 The default destination is `content/api/<api-id>/`; use `--output` for another directory inside the configured content tree. Selectors use the OpenAPI `operationId` or exact uppercase method and path. Repeating a command reports the existing matching page as skipped. A file with a conflicting identity stops the job before it writes anything. Existing authored references also count as skipped.
 
-Each new page has a stable document ID, slug, operation binding, and `access.policy: draft`. The draft contains an editorial prompt. While it remains a draft, any already selected build-time reference continues to publish. Review the text, replace the prompt, then set access to `public`; that MDX page takes the generated page's place for its publication. This also works when `generateReferences` is off: the authored page binds to the registered API's local OpenAPI source. The command never enables build-time generation, changes the public review digest, or chooses navigation order for you. Run `api review` before publishing changed API content, and place the reference with `operation:` or `doc:` in navigation if it is not already covered by a generator.
+Each new page has a stable document ID, slug, operation binding, and `access.policy: draft`. The draft contains an editorial prompt. While it remains a draft, any already selected build-time reference continues to publish. Review the text, replace the prompt, then set access to `public`; that MDX page takes the generated page's place for its publication. This also works when `generateReferences` is off: the authored page binds to the registered API's local OpenAPI source. The command never enables build-time generation, changes the public review digest, or chooses navigation order for you. Run `api review` before publishing changed API content, and place the reference with `operation:` or `doc:` in navigation if it isn't already covered by a generator.
 
 ## Generate many pages selectively
 
@@ -58,7 +58,7 @@ pathPrefix: /example-api/generated
 include: [getNote]
 ```
 
-`include` lists source `operationId` values to generate; an empty list generates none. You can use `exclude` instead to generate all but named operations, or set `generateReferences: true` to generate every operation without an authored binding. The build rejects unknown selection IDs. Generated IDs and URLs derive from the API ID and source `operationId`, not the operation summary, so editing a title does not move the page. If an `operationId` changes, add an authored binding when the old public identity must remain stable.
+`include` lists source `operationId` values to generate; an empty list generates none. You can use `exclude` instead to generate all but named operations, or set `generateReferences: true` to generate every operation without an authored binding. The build rejects unknown selection IDs. Generated IDs and URLs derive from the API ID and source `operationId`, not the operation summary, so editing a title doesn't move the page. If an `operationId` changes, add an authored binding when the old public identity must remain stable.
 
 For an API `notes` and `operationId: getNote`, the generator creates:
 
@@ -76,7 +76,7 @@ You can place an MDX guide among operation links in `navigation` by adding a `do
 
 ## Override generated reference order in navigation
 
-`generateReferences` chooses which reference pages exist. The `navigation` list chooses where they appear. **You can put a generated reference's stable operation ID in an `operation:` entry to override its OpenAPI tag group and source order. No MDX page is needed.** Write those entries in the exact order readers should see them, then use `generated: tags` to place only the operations you did not list.
+`generateReferences` chooses which reference pages exist. The `navigation` list chooses where they appear. **You can put a generated reference's stable operation ID in an `operation:` entry to override its OpenAPI tag group and source order. No MDX page is needed.** Write those entries in the exact order readers should see them, then use `generated: tags` to place only the operations you didn't list.
 
 ```yaml title="config/nav.yaml"
 - id: widgets
@@ -88,7 +88,7 @@ You can place an MDX guide among operation links in `navigation` by adding a `do
     - { id: other-widgets, api: widgets, generated: tags }
 ```
 
-Here `GET /Query/widgets` may have the OpenAPI tag `Query`, but its generated reference appears second under **Widgets**. The listed operations appear in this YAML order, regardless of their path, tag, or position in the OpenAPI file. They are removed from the `generated: tags` remainder, so each appears once. The `id` fields such as `query-widgets-nav` identify menu entries; `operation` values are the stable IDs that select the reference pages. An authored MDX reference uses the same navigation rule. See [Organize site navigation](https://www.shoalrun.com/author/navigation.md) for the full layout.
+Here `GET /Query/widgets` may have the OpenAPI tag `Query`, but its generated reference appears second under **Widgets**. The listed operations appear in this YAML order, regardless of their path, tag, or position in the OpenAPI file. They're removed from the `generated: tags` remainder, so each appears once. The `id` fields such as `query-widgets-nav` identify menu entries; `operation` values are the stable IDs that select the reference pages. An authored MDX reference uses the same navigation rule. See [Organize site navigation](https://www.shoalrun.com/author/navigation.md) for the full layout.
 
 To review the default publication's spec operation by operation, run:
 
@@ -96,13 +96,13 @@ To review the default publication's spec operation by operation, run:
 npx --no-install shoalrun api select notes docs.config.yaml --output config/notes-pages.yaml
 ```
 
-The command shows the method, path, ID, and summary for each operation and asks **yes** or **no**. It shows operations with authored pages but does not replace them. After the choices are complete, it writes the `pathPrefix` and `include` list to the selection file; `q` cancels without writing. Run `api review` again, inspect the candidate, and update `publicReview.digest` before rebuilding to apply the choices. Add `{ id: notes-generated, api: notes, generated: tags }` under a navigation group to display the generated pages by their first OpenAPI tag, or place selected operations explicitly in navigation. This site's [Example Notes API subnav](https://www.shoalrun.com/author/navigation.md) uses the tag generator.
+The command shows the method, path, ID, and summary for each operation and asks **yes** or **no**. It shows operations with authored pages but doesn't replace them. After the choices are complete, it writes the `pathPrefix` and `include` list to the selection file; `q` cancels without writing. Run `api review` again, inspect the candidate, and update `publicReview.digest` before rebuilding to apply the choices. Add `{ id: notes-generated, api: notes, generated: tags }` under a navigation group to display the generated pages by their first OpenAPI tag, or place selected operations explicitly in navigation. This site's [Example Notes API subnav](https://www.shoalrun.com/author/navigation.md) uses the tag generator.
 
 The digest shown above is a placeholder. Keep your existing review digest while editing. After reviewing the new selection, replace it with the reported value. Selection limits generated pages; `source.publish: true` still publishes the full source, including operations without pages. Use `focused: true` and omit `publish` when you only need individual operation contracts.
 
 ## Use a template for editorial context
 
-Use the built-in `api-reference` template for details OpenAPI cannot supply, such as operational context, task links, prerequisites, and limitations. Keep method, path, field lists, and example values in the spec so generated references have one source for those facts.
+Use the built-in `api-reference` template for details OpenAPI can't supply, such as operational context, task links, prerequisites, and limitations. Keep method, path, field lists, and example values in the spec so generated references have one source for those facts.
 
 ```sh
 shoalrun scaffold api-reference -n content/create-enrollment.mdx \
@@ -113,11 +113,11 @@ No template registration is needed. The scaffold requires exactly one known stab
 
 ## Add useful examples
 
-API reference pages display the examples defined in the OpenAPI file; the build does not invent them. Give each example a clear name and include the fields a reader needs to use it. In this site's Notes spec, [Create a note](https://www.shoalrun.com/example-api/create-note.md) has request and response examples. [Get a note](https://www.shoalrun.com/example-api/generated/get-note-cbedb319.md) has a note ID and a response example.
+API reference pages display the examples defined in the OpenAPI file; the build doesn't invent them. Give each example a clear name and include the fields a reader needs to use it. In this site's Notes spec, [Create a note](https://www.shoalrun.com/example-api/create-note.md) has request and response examples. [Get a note](https://www.shoalrun.com/example-api/generated/get-note-cbedb319.md) has a note ID and a response example.
 
 The right panel offers **Examples** first when the spec provides them, plus a **JSON shape** view built from each JSON request or response schema. Shape values are type placeholders, not a runnable payload. Request and response examples stay in separate groups, with response status and media type in each heading. Groups of three or fewer use native disclosures. Larger groups use a compact selector with one visible preview when JavaScript is available; without JavaScript, every disclosure remains usable. The Create a note request has ten named examples so you can inspect this layout. Direct links still open the selected example.
 
-Local named request examples for ordinary, non-multipart operations also have copyable request samples. In HTML, each sample has a language selector. It offers cURL, JavaScript, Node.js, Python, Go, Java, PHP, Ruby, and C#. Webhooks have no generated request samples. A sample uses the first declared server and security option, required parameters, the example body, and its media type. Replace `YOUR_` credential and parameter placeholders before using it. Ordinary operations without a request body show a general request sample. An operation with a request body but no local named request examples usually shows no sample. A multipart body whose required fields are all binary strings can produce a file-upload sample in cURL only. An `externalValue` example has no example-specific sample. These samples are generated from the OpenAPI source and have not been executed. **The Markdown twin and agent bundle keep only the cURL sample.** Agents can translate cURL; one canonical sample keeps the `.md` output small.
+Local named request examples for ordinary, non-multipart operations also have copyable request samples. In HTML, each sample has a language selector. It offers cURL, JavaScript, Node.js, Python, Go, Java, PHP, Ruby, and C#. Webhooks have no generated request samples. A sample uses the first declared server and security option, required parameters, the example body, and its media type. Replace `YOUR_` credential and parameter placeholders before using it. Ordinary operations without a request body show a general request sample. An operation with a request body but no local named request examples usually shows no sample. A multipart body whose required fields are all binary strings can produce a file-upload sample in cURL only. An `externalValue` example has no example-specific sample. These samples are generated from the OpenAPI source and haven't been executed. **The Markdown twin and agent bundle keep only the cURL sample.** Agents can translate cURL; one canonical sample keeps the `.md` output small.
 
 An OpenAPI `summary` names an example, and `description` adds context. Without a summary, the reader turns its source key into a readable title and still shows the original key. A response without an example still has a shape: Get a note's `404` response shows `code` and `message` as strings. The full field descriptions and presence rules remain in the main reference and its Markdown twin.
 

package/agent-docs/api-docs/generate.sections/add-useful-examples.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Generate and select API pages
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/api-docs/generate.md)
 
@@ -35,11 +35,11 @@ Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun
 
 ## Add useful examples
 
-API reference pages display the examples defined in the OpenAPI file; the build does not invent them. Give each example a clear name and include the fields a reader needs to use it. In this site's Notes spec, [Create a note](https://www.shoalrun.com/example-api/create-note.md) has request and response examples. [Get a note](https://www.shoalrun.com/example-api/generated/get-note-cbedb319.md) has a note ID and a response example.
+API reference pages display the examples defined in the OpenAPI file; the build doesn't invent them. Give each example a clear name and include the fields a reader needs to use it. In this site's Notes spec, [Create a note](https://www.shoalrun.com/example-api/create-note.md) has request and response examples. [Get a note](https://www.shoalrun.com/example-api/generated/get-note-cbedb319.md) has a note ID and a response example.
 
 The right panel offers **Examples** first when the spec provides them, plus a **JSON shape** view built from each JSON request or response schema. Shape values are type placeholders, not a runnable payload. Request and response examples stay in separate groups, with response status and media type in each heading. Groups of three or fewer use native disclosures. Larger groups use a compact selector with one visible preview when JavaScript is available; without JavaScript, every disclosure remains usable. The Create a note request has ten named examples so you can inspect this layout. Direct links still open the selected example.
 
-Local named request examples for ordinary, non-multipart operations also have copyable request samples. In HTML, each sample has a language selector. It offers cURL, JavaScript, Node.js, Python, Go, Java, PHP, Ruby, and C#. Webhooks have no generated request samples. A sample uses the first declared server and security option, required parameters, the example body, and its media type. Replace `YOUR_` credential and parameter placeholders before using it. Ordinary operations without a request body show a general request sample. An operation with a request body but no local named request examples usually shows no sample. A multipart body whose required fields are all binary strings can produce a file-upload sample in cURL only. An `externalValue` example has no example-specific sample. These samples are generated from the OpenAPI source and have not been executed. **The Markdown twin and agent bundle keep only the cURL sample.** Agents can translate cURL; one canonical sample keeps the `.md` output small.
+Local named request examples for ordinary, non-multipart operations also have copyable request samples. In HTML, each sample has a language selector. It offers cURL, JavaScript, Node.js, Python, Go, Java, PHP, Ruby, and C#. Webhooks have no generated request samples. A sample uses the first declared server and security option, required parameters, the example body, and its media type. Replace `YOUR_` credential and parameter placeholders before using it. Ordinary operations without a request body show a general request sample. An operation with a request body but no local named request examples usually shows no sample. A multipart body whose required fields are all binary strings can produce a file-upload sample in cURL only. An `externalValue` example has no example-specific sample. These samples are generated from the OpenAPI source and haven't been executed. **The Markdown twin and agent bundle keep only the cURL sample.** Agents can translate cURL; one canonical sample keeps the `.md` output small.
 
 An OpenAPI `summary` names an example, and `description` adds context. Without a summary, the reader turns its source key into a readable title and still shows the original key. A response without an example still has a shape: Get a note's `404` response shows `code` and `message` as strings. The full field descriptions and presence rules remain in the main reference and its Markdown twin.
 

package/agent-docs/api-docs/generate.sections/choose-generated-references-or-mdx.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Generate and select API pages
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/api-docs/generate.md)
 
@@ -35,9 +35,9 @@ Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun
 
 ## Choose generated references or MDX
 
-Use build-time generated references when the OpenAPI contract already gives readers the method, path, parameters, schemas, and examples they need. The pages update whenever the reviewed source changes, and there are no MDX files to maintain. Use an authored MDX reference when an endpoint needs a reviewed introduction, prerequisites, limitations, or task-specific context that the contract cannot express. The compiler still appends the contract details from OpenAPI, so do not copy field tables and example payloads into MDX. Use a guide for a task spanning several endpoints; link its reference pages with `relatedApiReferences`.
+Use build-time generated references when the OpenAPI contract already gives readers the method, path, parameters, schemas, and examples they need. The pages update whenever the reviewed source changes, and there are no MDX files to maintain. Use an authored MDX reference when an endpoint needs a reviewed introduction, prerequisites, limitations, or task-specific context that the contract can't express. The compiler still appends the contract details from OpenAPI, so don't copy field tables and example payloads into MDX. Use a guide for a task spanning several endpoints; link its reference pages with `relatedApiReferences`.
 
-The one-time `api materialize` command creates draft MDX references for every endpoint or selected source operation IDs or method/path routes. It does not change config or navigation and never rewrites an existing page. For example:
+The one-time `api materialize` command creates draft MDX references for every endpoint or selected source operation IDs or method/path routes. It doesn't change config or navigation and never rewrites an existing page. For example:
 
 ```sh
 npx --no-install shoalrun api materialize notes docs.config.yaml --all
@@ -47,4 +47,4 @@ npx --no-install shoalrun api materialize notes docs.config.yaml --route 'GET /n
 
 The default destination is `content/api/<api-id>/`; use `--output` for another directory inside the configured content tree. Selectors use the OpenAPI `operationId` or exact uppercase method and path. Repeating a command reports the existing matching page as skipped. A file with a conflicting identity stops the job before it writes anything. Existing authored references also count as skipped.
 
-Each new page has a stable document ID, slug, operation binding, and `access.policy: draft`. The draft contains an editorial prompt. While it remains a draft, any already selected build-time reference continues to publish. Review the text, replace the prompt, then set access to `public`; that MDX page takes the generated page's place for its publication. This also works when `generateReferences` is off: the authored page binds to the registered API's local OpenAPI source. The command never enables build-time generation, changes the public review digest, or chooses navigation order for you. Run `api review` before publishing changed API content, and place the reference with `operation:` or `doc:` in navigation if it is not already covered by a generator.
+Each new page has a stable document ID, slug, operation binding, and `access.policy: draft`. The draft contains an editorial prompt. While it remains a draft, any already selected build-time reference continues to publish. Review the text, replace the prompt, then set access to `public`; that MDX page takes the generated page's place for its publication. This also works when `generateReferences` is off: the authored page binds to the registered API's local OpenAPI source. The command never enables build-time generation, changes the public review digest, or chooses navigation order for you. Run `api review` before publishing changed API content, and place the reference with `operation:` or `doc:` in navigation if it isn't already covered by a generator.

package/agent-docs/api-docs/generate.sections/describe-filters-that-do-not-use-their-openapi-parameter-name.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Generate and select API pages
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/api-docs/generate.md)
 

package/agent-docs/api-docs/generate.sections/generate-many-pages-selectively.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Generate and select API pages
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/api-docs/generate.md)
 
@@ -54,7 +54,7 @@ pathPrefix: /example-api/generated
 include: [getNote]
 ```
 
-`include` lists source `operationId` values to generate; an empty list generates none. You can use `exclude` instead to generate all but named operations, or set `generateReferences: true` to generate every operation without an authored binding. The build rejects unknown selection IDs. Generated IDs and URLs derive from the API ID and source `operationId`, not the operation summary, so editing a title does not move the page. If an `operationId` changes, add an authored binding when the old public identity must remain stable.
+`include` lists source `operationId` values to generate; an empty list generates none. You can use `exclude` instead to generate all but named operations, or set `generateReferences: true` to generate every operation without an authored binding. The build rejects unknown selection IDs. Generated IDs and URLs derive from the API ID and source `operationId`, not the operation summary, so editing a title doesn't move the page. If an `operationId` changes, add an authored binding when the old public identity must remain stable.
 
 For an API `notes` and `operationId: getNote`, the generator creates: