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

package/agent-docs/author/custom-metadata.sections/choose-text-for-each-surface.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Metadata customization
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/custom-metadata.md)
 
@@ -42,7 +42,7 @@ outputs:
     socialCard: [summary]
 ```
 
-`socialCard` writes an Open Graph description tag when it finds text; it does not generate a card image. Without a `socialCard` rule or page override, Shoalrun writes no Open Graph description. The other surfaces default to `summary` if no rule is set. The search choice becomes the summary in `search-index.json`. A card's existing `card.description` and an HTML page's existing `seo.description` take precedence over these rules.
+`socialCard` writes an Open Graph description tag when it finds text; it doesn't generate a card image. Without a `socialCard` rule or page override, Shoalrun writes no Open Graph description. The other surfaces default to `summary` if no rule is set. The search choice becomes the summary in `search-index.json`. A card's existing `card.description` and an HTML page's existing `seo.description` take precedence over these rules.
 
 Override one surface on a page with literal text:
 
@@ -51,4 +51,4 @@ displayText:
   socialCard: A short introduction for link previews.
 ```
 
-`displayText` is presentation control; it is not exported as Markdown metadata. A configured text rule can also select a custom or provider-supplied string field by path. Selecting it for public HTML or the search index is an explicit publication decision.
+`displayText` is presentation control; it isn't exported as Markdown metadata. A configured text rule can also select a custom or provider-supplied string field by path. Selecting it for public HTML or the search index is an explicit publication decision.

package/agent-docs/author/custom-metadata.sections/preview-changes-to-metadata-providers.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Metadata customization
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/custom-metadata.md)
 
@@ -30,4 +30,4 @@ Use this guide when your project needs shared metadata rules or fields beyond th
 
 ## Preview changes to metadata providers
 
-Restart local preview after editing a custom metadata provider module configured with `metadata.provider`. Node loads the module once, so a watched rebuild does not reload its implementation. Stop `shoalrun dev` and start it again to see changes to the provider code. Changes to ordinary documentation pages still trigger automatic rebuilds. See the [CLI reference](https://www.shoalrun.com/cli.md) for other changes that require a restart.
+Restart local preview after editing a custom metadata provider module configured with `metadata.provider`. Node loads the module once, so a watched rebuild doesn't reload its implementation. Stop `shoalrun dev` and start it again to see changes to the provider code. Changes to ordinary documentation pages still trigger automatic rebuilds. See the [CLI reference](https://www.shoalrun.com/cli.md) for other changes that require a restart.

package/agent-docs/author/custom-metadata.sections/read-metadata-from-a-project-module.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Metadata customization
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/custom-metadata.md)
 
@@ -30,7 +30,7 @@ Use this guide when your project needs shared metadata rules or fields beyond th
 
 ## Read metadata from a project module
 
-A project can opt into a local build-time provider module. Shoalrun does not validate external vocabularies; projects run their own validation separately. A provider can adapt an external metadata manifest to Shoalrun's page model:
+A project can opt into a local build-time provider module. Shoalrun doesn't validate external vocabularies; projects run their own validation separately. A provider can adapt an external metadata manifest to Shoalrun's page model:
 
 ```yaml title="docs.config.yaml"
 metadata:
@@ -50,7 +50,7 @@ export async function provideMetadata({ file, source, projectRoot }) {
 }
 ```
 
-`lookupById` is project code in this example. The provider runs for each authored page before project defaults and normal frontmatter checks. Returned values can be used by Shoalrun's build features. Return nothing to leave a page unchanged. `ownedKeys` names top-level fields the provider owns, including fields with no value on a given page. Every key in `values` must be owned. If `ownedKeys` is omitted, the provider owns exactly the keys in `values`. If an owned field also appears in page frontmatter, the build fails. Providers cannot replace `id`, `slug`, publication selectors, or `access`. `dependencies` lists absolute paths of files the provider read so the build record includes them.
+`lookupById` is project code in this example. The provider runs for each authored page before project defaults and normal frontmatter checks. Returned values can be used by Shoalrun's build features. Return nothing to leave a page unchanged. `ownedKeys` names top-level fields the provider owns, including fields with no value on a given page. Every key in `values` must be owned. If `ownedKeys` is omitted, the provider owns exactly the keys in `values`. If an owned field also appears in page frontmatter, the build fails. Providers can't replace `id`, `slug`, publication selectors, or `access`. `dependencies` lists absolute paths of files the provider read so the build record includes them.
 
 Provider fields stay out of public metadata unless the project selects them. To put a custom provider field in the Markdown header, declare it under `frontmatter.fields` with `public: true`, then select it in `outputs.markdown.metadata.fields`. The project's explicit selection determines what is published.
 

package/agent-docs/author/custom-metadata.sections/related-reading.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Metadata customization
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/custom-metadata.md)
 

package/agent-docs/author/design-templates.md

@@ -18,7 +18,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Advanced workflows > Design templates
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 A template defines the starting structure of a page. Use it for information that belongs in most pages of a particular kind. A writing guide explains how to write that information.
 
@@ -32,11 +32,11 @@ For an ingredient, define one reusable action, its inputs, and its success check
 
 A useful placeholder asks for specific missing information: prerequisites, a tested command, expected output, or a recovery action. Avoid vague prompts such as “add useful details.” Tell the agent to flag missing evidence instead of filling gaps with plausible facts.
 
-Keep required sections small. Make optional sections clearly optional, and provide a reviewed example outside the template. A copied example's technical details are not evidence for a different feature.
+Keep required sections small. Make optional sections clearly optional, and provide a reviewed example outside the template. A copied example's technical details aren't evidence for a different feature.
 
 ## Keep structure and checks separate
 
-Shoalrun's [template overrides](https://www.shoalrun.com/author/templates.md) control scaffold text. They do not automatically change configured lint rules. Match the template to your page-type conventions and configure checks explicitly.
+Shoalrun's [template overrides](https://www.shoalrun.com/author/templates.md) control scaffold text. They don't automatically change configured lint rules. Match the template to your page-type conventions and configure checks explicitly.
 
 Review a template by drafting several real pages with it. Remove sections authors repeatedly leave empty, and add prompts where readers repeatedly lack information. Check both HTML and Markdown so essential instructions survive every representation.
 

package/agent-docs/author/design-writing-guides.md

@@ -19,7 +19,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Advanced workflows > Design a writing guide
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 A project writing guide explains your readers, terminology, and editorial decisions. Give your agent the guide's file path in project instructions so it can read the same rules as human authors.
 
@@ -38,7 +38,7 @@ authoring:
     - content/reviewed-how-to.mdx
 ```
 
-Paths are relative to `docs.config.yaml` and point to files your agent should read. `docs context` returns this guidance and its configuration owner. For a new page, your agent can read it with `config resolve`. Shoalrun validates the field shapes; it does not load these files into a model, run the instructions, or require a provider key. These authoring settings do not configure a model.
+Paths are relative to `docs.config.yaml` and point to files your agent should read. `docs context` returns this guidance and its configuration owner. For a new page, your agent can read it with `config resolve`. Shoalrun validates the field shapes; it doesn't load these files into a model, run the instructions, or require a provider key. These authoring settings don't configure a model.
 
 ## State the decisions that matter
 
@@ -58,7 +58,7 @@ The [example writing guide](https://www.shoalrun.com/author/writing-style.md) sh
 
 Tell the agent to support changed technical claims with sources it has inspected, verify examples when possible, and report missing facts. Your agent handles source discovery and evidence gathering with its own tools. Keep editorial examples separate from factual sources.
 
-Define what the reviewer needs: a diff, changed claims and their sources, check results, and unresolved questions. Do not treat a clean style report as approval to publish.
+Define what the reviewer needs: a diff, changed claims and their sources, check results, and unresolved questions. Don't treat a clean style report as approval to publish.
 
 ## Automate the repeatable rules
 

package/agent-docs/author/frontmatter-reference.md

@@ -16,11 +16,11 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-11-04.**
+**Updated: 2026-11-05.**
 
 This is the field inventory for this documentation site. The tables below are built from Shoalrun's native field definitions and this site's `frontmatter.fields` declarations on each build. They describe source page headers, not the shorter YAML header selected for a published Markdown page.
 
-`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It is **not** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
+`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It **isn't** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 
@@ -64,7 +64,8 @@ By default, `product`, `area`, and `subarea` are optional, nonempty string categ
 
 | Field                  | Type            | Needed       | What it changes                                                                                                                                                                                                                                                             |
 | ---------------------- | --------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `product`              | string          | Optional     | Optional product category. Also selects the product reader facet when that facet is configured.                                                                                                                                                                             |
+| `availability`         | object          | Optional     | Inclusive feature availability labels shown beside page dates and retained in Markdown and the document manifest. Does not select or hide publications; labels are not compared or inferred.                                                                                |
+| `product`              | string          | Optional     | Product publication ID when publications.products is configured; otherwise an optional category and reader facet.                                                                                                                                                           |
 | `area`                 | string or array | On each page | Optional area category. Also selects the area reader facet when that facet is configured.                                                                                                                                                                                   |
 | `subarea`              | string or array | On each page | Optional finer category. Also selects the subarea reader facet when that facet is configured.                                                                                                                                                                               |
 | `operations`           | array           | Optional     | Stable API operation IDs that connect this page to endpoint references and related documents.                                                                                                                                                                               |
@@ -124,11 +125,49 @@ A project can add page fields by declaring them in `frontmatter.fields`. The dec
 
 These are project config settings, not keys in a page header. `frontmatter.defaults` supplies values when a page omits them; `frontmatter.enforced` replaces page values. Resolution follows defaults → page → enforced. Objects merge recursively and arrays replace. IDs and slugs remain page-specific. Required fields and declared types are checked after resolution. Use an access default if authors need to keep individual pages as drafts.
 
+## Feature availability
+
+Since 0.1.0-alpha.18
+
+Set `availability` on a page to show version support beside its dates. This example uses fictional release labels; replace them with your feature's actual supported versions:
+
+```yaml title="Page frontmatter"
+availability:
+  since: v1
+  through: v2
+```
+
+Use either boundary alone or both together. `since` is the first supported version, and `through` is the last supported version; both are inclusive. Omit an unknown boundary. The values are labels and aren't compared automatically. This metadata doesn't select a publication, hide content, or mark a feature as deprecated.
+
+HTML displays “Since v1” and “Through v2” in the same text style as changelog release versions, beside “Updated” when that date is present. Markdown includes readable availability labels even when its configured metadata projection omits the field. The document manifest retains the `availability` object. There is no JavaScript interaction. For a newer option within an older guide, use a [Badge](https://www.shoalrun.com/author/components/badge.md) beside the option instead of changing the page's availability.
+
+### Mark a newer section
+
+Keep the page's original availability when only one section covers a newer capability. Put its label directly below the section heading:
+
+```mdx
+## Product publications
+
+<Badge variant="neutral">Since 0.1.0-alpha.18</Badge>
+
+Give each product its own versions and default release.
+```
+
+This renders the section label as Since 0.1.0-alpha.18. The [publications guide](https://www.shoalrun.com/publish/publications.md) uses this pattern for independent product versions. Markdown retains the label as readable text beside that section's content.
+
+## Product publication fields
+
+Since 0.1.0-alpha.18
+
+The generated inventory above follows the package installed by this site. In alpha.18, configuring `publications.products` makes a page's `product` part of its publication identity. Its `version` is resolved within that product's catalog. Without a product catalog, `product` keeps its existing metadata meaning.
+
+A page's `publications` list can include `product` alongside `channel` and `version` to reuse one source in explicit product releases. Don't combine that list with page-level product, channel, or version fields. `shared: true` classifies content for feature grants; it doesn't copy the page to other product publications. See [independent product publications](https://www.shoalrun.com/publish/publications.md) for the catalog, routes, and examples.
+
 ## Use the local files while authoring
 
-Every project also gets `.shoalrun/frontmatter-reference.md` and `.shoalrun/frontmatter.schema.json` beside `docs.config.yaml`. They contain that project's inventory for authors, editors, and agents working in its repository. For this site, the paths are `docs/.shoalrun/frontmatter-reference.md` and `docs/.shoalrun/frontmatter.schema.json`. These internal files are not published site routes.
+Every project also gets `.shoalrun/frontmatter-reference.md` and `.shoalrun/frontmatter.schema.json` beside `docs.config.yaml`. They contain that project's inventory for authors, editors, and agents working in its repository. For this site, the paths are `docs/.shoalrun/frontmatter-reference.md` and `docs/.shoalrun/frontmatter.schema.json`. These internal files aren't published site routes.
 
-Changing a declaration and rebuilding updates the published table and both local files. Undeclared fields may still appear in source pages, but they have no project type check and do not appear in the field inventory.
+Changing a declaration and rebuilding updates the published table and both local files. Undeclared fields may still appear in source pages, but they have no project type check and don't appear in the field inventory.
 
 ## When the files update
 
@@ -146,7 +185,7 @@ The reference describes source fields. To choose which of them appear in each pa
 
 ## HTML, Markdown, and agents
 
-`FrontmatterReference` writes the project's field definitions into both the HTML page and its Markdown twin. An agent can read those tables without running JavaScript or opening the local schema file. The tables describe accepted source fields; they do not expose each page's private metadata values. The separate `.shoalrun` files are local authoring resources, not public routes.
+`FrontmatterReference` writes the project's field definitions into both the HTML page and its Markdown twin. An agent can read those tables without running JavaScript or opening the local schema file. The tables describe accepted source fields; they don't expose each page's private metadata values. The separate `.shoalrun` files are local authoring resources, not public routes.
 
 ## Related reading
 

package/agent-docs/author/frontmatter-reference.sections/categorize-connect-and-present-the-page.md

@@ -0,0 +1,64 @@
+---
+id: guide.frontmatter-reference
+title: Frontmatter field reference
+summary: Browse the built-in and project-defined page fields this site supports.
+type: reference
+area: authoring
+subarea: authoring-metadata
+canonical: /author/frontmatter-reference
+---
+
+# Frontmatter field reference
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
+
+**Updated: 2026-11-05.**
+
+Parent page: [Full Markdown page](/author/frontmatter-reference.md)
+
+This is the field inventory for this documentation site. The tables below are built from Shoalrun's native field definitions and this site's `frontmatter.fields` declarations on each build. They describe source page headers, not the shorter YAML header selected for a published Markdown page.
+
+`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It **isn't** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
+
+To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
+
+For section exports, declare `standaloneSections` with `{ id, context: section }` objects after reviewing each section without its page introduction. Older heading-title strings remain supported for contextual discovery. See [section identity and compatibility](https://www.shoalrun.com/content-delivery/sections.md) before changing an existing declaration.
+
+## Categorize, connect, and present the page
+
+By default, `product`, `area`, and `subarea` are optional, nonempty string categories. They can come from project defaults and appear in the document manifest and search index. A matching configured reader facet makes each category a page filter; without that facet it remains taxonomy only. `operations` links a guide or reference to stable API operation IDs. On a guide or how-to page, `relatedApiReferences` names API reference page IDs to add cross links in both directions within the same publication. Tags help document collections find the page. Card settings change its preview when another page links to it; they do not change the destination. `subjectLifecycle` displays the status of the documented API or feature; `lifecycle` is available for the document's editorial state. `tocDepth` limits the HTML page table of contents; use 0 to hide it. `layout` picks the HTML page layout: `docs`, `wide`, `landing`, or `splash`. `showNavigationTabs` overrides the navigation tab bar for this page; landing and splash pages hide it by default. `image` replaces the generated link-preview image. `date` and `releaseVersion` can identify a changelog entry under the project's `frontmatter.changelogIdentifier` rule.
+
+| Field                  | Type            | Needed       | What it changes                                                                                                                                                                                                                                                             |
+| ---------------------- | --------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `availability`         | object          | Optional     | Inclusive feature availability labels shown beside page dates and retained in Markdown and the document manifest. Does not select or hide publications; labels are not compared or inferred.                                                                                |
+| `product`              | string          | Optional     | Product publication ID when publications.products is configured; otherwise an optional category and reader facet.                                                                                                                                                           |
+| `area`                 | string or array | On each page | Optional area category. Also selects the area reader facet when that facet is configured.                                                                                                                                                                                   |
+| `subarea`              | string or array | On each page | Optional finer category. Also selects the subarea reader facet when that facet is configured.                                                                                                                                                                               |
+| `operations`           | array           | Optional     | Stable API operation IDs that connect this page to endpoint references and related documents.                                                                                                                                                                               |
+| `relatedApiReferences` | array           | Optional     | API reference page IDs linked automatically from this guide and back from each reference, within the same publication.                                                                                                                                                      |
+| `tags`                 | array           | Optional     | Editorial labels used to select pages in document collections.                                                                                                                                                                                                              |
+| `date`                 | string          | Optional     | Publication date in YYYY-MM-DD format; optional for release notes and one possible changelog identifier.                                                                                                                                                                    |
+| `releaseVersion`       | string          | Optional     | Release label for a note or changelog entry; separate from the documentation publication version.                                                                                                                                                                           |
+| `subjectLifecycle`     | string          | Optional     | Displays a content status badge in the page and navigation.                                                                                                                                                                                                                 |
+| `subjectDeprecation`   | object          | Optional     | Page-specific subject retirement dates and stable document IDs; requires deprecated subjectLifecycle, including OpenAPI inference. Dates do not change status automatically.                                                                                                |
+| `change`               | object          | Optional     | Page-specific authored change meaning on a changelog-entry: kind, affected document IDs, and optional migration guide ID in the same publication. Omission means unclassified, not nonbreaking.                                                                             |
+| `lifecycle`            | string          | Optional     | Editorial lifecycle of the document; validated by an opted-in external vocabulary.                                                                                                                                                                                          |
+| `card`                 | object          | Optional     | Overrides how this page appears when another page includes a document card; its destination still resolves by page ID.                                                                                                                                                      |
+| `card.title`           | string          | Optional     | Card title; defaults to the page title.                                                                                                                                                                                                                                     |
+| `card.description`     | string          | Optional     | Card description; defaults to the page summary.                                                                                                                                                                                                                             |
+| `card.eyebrow`         | string          | Optional     | Short label above a card title.                                                                                                                                                                                                                                             |
+| `card.icon`            | string          | Optional     | Optional Lucide icon name such as book-open. Decorative in HTML; omitted from Markdown.                                                                                                                                                                                     |
+| `standaloneSections`   | array           | Optional     | Page-specific standalone approval: a heading title approves contextual discovery with the page introduction; {id, context: section} approves the root level-two section slice for content export. IDs may be derived or explicitly anchored. Omitted means full-page reads. |
+| `tocDepth`             | integer         | Optional     | Deepest heading shown in the page table of contents; 0 hides it. Defaults to 3.                                                                                                                                                                                             |
+| `layout`               | string          | Optional     | HTML page layout: docs (default), wide (no page outline, full content width), landing (no sidebar or outline; a Hero replaces the page header), or splash (full-bleed marketing page built from Hero and Section blocks).                                                   |
+| `showNavigationTabs`   | boolean         | Optional     | Show the HTML navigation section bar when tabs are configured. Defaults to true for docs and wide layouts, false for landing and splash. Does not change agent discovery or section membership.                                                                             |
+| `showVerified`         | boolean         | Optional     | Show an authored verified date in the HTML page header. Defaults to true. False hides it only in HTML; Markdown and manifest dates remain unchanged. Does not assign a verification date.                                                                                   |
+| `image`                | string          | Optional     | Local .png or .jpg shown in link previews for this page, relative to the page file; replaces the generated share image. Best at 1200×630.                                                                                                                                   |
+
+Projects can opt into built-in category enforcement with `frontmatter.taxonomy`. It declares areas and their allowed subareas, optional required fields, and optional explicit-field requirements for authored pages. Its `multiple` list permits arrays for selected category fields; otherwise each field allows one value. Defaults and enforced values still apply; generated API references use resolved categories. Definitions appear in the document manifest and constrain the generated frontmatter schema. Omit taxonomy or set it to false to preserve optional category behavior.
+
+With `profiles.requireClassification: true`, every public source page in the shared enabled publications needs an explicit `shared: true` or `requires` declaration before customer selection. Defaults do not count. Shared pages may contain feature-specific sections wrapped in `<ForFeature>`; unwrapped text remains shared.

package/agent-docs/author/frontmatter-reference.sections/choose-a-publication-and-visibility.md

@@ -16,13 +16,13 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-11-04.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
 This is the field inventory for this documentation site. The tables below are built from Shoalrun's native field definitions and this site's `frontmatter.fields` declarations on each build. They describe source page headers, not the shorter YAML header selected for a published Markdown page.
 
-`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It is **not** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
+`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It **isn't** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 

package/agent-docs/author/frontmatter-reference.sections/control-output-details.md

@@ -16,13 +16,13 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-11-04.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
 This is the field inventory for this documentation site. The tables below are built from Shoalrun's native field definitions and this site's `frontmatter.fields` declarations on each build. They describe source page headers, not the shorter YAML header selected for a published Markdown page.
 
-`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It is **not** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
+`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It **isn't** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 

package/agent-docs/author/frontmatter-reference.sections/feature-availability.md

@@ -0,0 +1,59 @@
+---
+id: guide.frontmatter-reference
+title: Frontmatter field reference
+summary: Browse the built-in and project-defined page fields this site supports.
+type: reference
+area: authoring
+subarea: authoring-metadata
+canonical: /author/frontmatter-reference
+---
+
+# Frontmatter field reference
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
+
+**Updated: 2026-11-05.**
+
+Parent page: [Full Markdown page](/author/frontmatter-reference.md)
+
+This is the field inventory for this documentation site. The tables below are built from Shoalrun's native field definitions and this site's `frontmatter.fields` declarations on each build. They describe source page headers, not the shorter YAML header selected for a published Markdown page.
+
+`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It **isn't** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
+
+To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
+
+For section exports, declare `standaloneSections` with `{ id, context: section }` objects after reviewing each section without its page introduction. Older heading-title strings remain supported for contextual discovery. See [section identity and compatibility](https://www.shoalrun.com/content-delivery/sections.md) before changing an existing declaration.
+
+## Feature availability
+
+Since 0.1.0-alpha.18
+
+Set `availability` on a page to show version support beside its dates. This example uses fictional release labels; replace them with your feature's actual supported versions:
+
+```yaml title="Page frontmatter"
+availability:
+  since: v1
+  through: v2
+```
+
+Use either boundary alone or both together. `since` is the first supported version, and `through` is the last supported version; both are inclusive. Omit an unknown boundary. The values are labels and aren't compared automatically. This metadata doesn't select a publication, hide content, or mark a feature as deprecated.
+
+HTML displays “Since v1” and “Through v2” in the same text style as changelog release versions, beside “Updated” when that date is present. Markdown includes readable availability labels even when its configured metadata projection omits the field. The document manifest retains the `availability` object. There is no JavaScript interaction. For a newer option within an older guide, use a [Badge](https://www.shoalrun.com/author/components/badge.md) beside the option instead of changing the page's availability.
+
+### Mark a newer section
+
+Keep the page's original availability when only one section covers a newer capability. Put its label directly below the section heading:
+
+```mdx
+## Product publications
+
+<Badge variant="neutral">Since 0.1.0-alpha.18</Badge>
+
+Give each product its own versions and default release.
+```
+
+This renders the section label as Since 0.1.0-alpha.18. The [publications guide](https://www.shoalrun.com/publish/publications.md) uses this pattern for independent product versions. Markdown retains the label as readable text beside that section's content.

package/agent-docs/author/frontmatter-reference.sections/global-defaults-and-enforced-values.md

@@ -16,13 +16,13 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-11-04.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
 This is the field inventory for this documentation site. The tables below are built from Shoalrun's native field definitions and this site's `frontmatter.fields` declarations on each build. They describe source page headers, not the shorter YAML header selected for a published Markdown page.
 
-`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It is **not** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
+`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It **isn't** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 

package/agent-docs/author/frontmatter-reference.sections/html-markdown-and-agents.md

@@ -16,13 +16,13 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-11-04.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
 This is the field inventory for this documentation site. The tables below are built from Shoalrun's native field definitions and this site's `frontmatter.fields` declarations on each build. They describe source page headers, not the shorter YAML header selected for a published Markdown page.
 
-`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It is **not** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
+`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It **isn't** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 
@@ -30,4 +30,4 @@ For section exports, declare `standaloneSections` with `{ id, context: section }
 
 ## HTML, Markdown, and agents
 
-`FrontmatterReference` writes the project's field definitions into both the HTML page and its Markdown twin. An agent can read those tables without running JavaScript or opening the local schema file. The tables describe accepted source fields; they do not expose each page's private metadata values. The separate `.shoalrun` files are local authoring resources, not public routes.
+`FrontmatterReference` writes the project's field definitions into both the HTML page and its Markdown twin. An agent can read those tables without running JavaScript or opening the local schema file. The tables describe accepted source fields; they don't expose each page's private metadata values. The separate `.shoalrun` files are local authoring resources, not public routes.

package/agent-docs/author/frontmatter-reference.sections/identify-and-route-a-page.md

@@ -16,13 +16,13 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-11-04.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
 This is the field inventory for this documentation site. The tables below are built from Shoalrun's native field definitions and this site's `frontmatter.fields` declarations on each build. They describe source page headers, not the shorter YAML header selected for a published Markdown page.
 
-`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It is **not** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
+`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It **isn't** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 

package/agent-docs/author/frontmatter-reference.sections/point-agents-to-it.md

@@ -16,13 +16,13 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-11-04.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
 This is the field inventory for this documentation site. The tables below are built from Shoalrun's native field definitions and this site's `frontmatter.fields` declarations on each build. They describe source page headers, not the shorter YAML header selected for a published Markdown page.
 
-`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It is **not** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
+`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It **isn't** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 

package/agent-docs/author/frontmatter-reference.sections/product-publication-fields.md

@@ -0,0 +1,37 @@
+---
+id: guide.frontmatter-reference
+title: Frontmatter field reference
+summary: Browse the built-in and project-defined page fields this site supports.
+type: reference
+area: authoring
+subarea: authoring-metadata
+canonical: /author/frontmatter-reference
+---
+
+# Frontmatter field reference
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
+
+**Updated: 2026-11-05.**
+
+Parent page: [Full Markdown page](/author/frontmatter-reference.md)
+
+This is the field inventory for this documentation site. The tables below are built from Shoalrun's native field definitions and this site's `frontmatter.fields` declarations on each build. They describe source page headers, not the shorter YAML header selected for a published Markdown page.
+
+`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It **isn't** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
+
+To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
+
+For section exports, declare `standaloneSections` with `{ id, context: section }` objects after reviewing each section without its page introduction. Older heading-title strings remain supported for contextual discovery. See [section identity and compatibility](https://www.shoalrun.com/content-delivery/sections.md) before changing an existing declaration.
+
+## Product publication fields
+
+Since 0.1.0-alpha.18
+
+The generated inventory above follows the package installed by this site. In alpha.18, configuring `publications.products` makes a page's `product` part of its publication identity. Its `version` is resolved within that product's catalog. Without a product catalog, `product` keeps its existing metadata meaning.
+
+A page's `publications` list can include `product` alongside `channel` and `version` to reuse one source in explicit product releases. Don't combine that list with page-level product, channel, or version fields. `shared: true` classifies content for feature grants; it doesn't copy the page to other product publications. See [independent product publications](https://www.shoalrun.com/publish/publications.md) for the catalog, routes, and examples.

package/agent-docs/author/frontmatter-reference.sections/project-defined-fields.md

@@ -16,13 +16,13 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-11-04.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
 This is the field inventory for this documentation site. The tables below are built from Shoalrun's native field definitions and this site's `frontmatter.fields` declarations on each build. They describe source page headers, not the shorter YAML header selected for a published Markdown page.
 
-`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It is **not** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
+`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It **isn't** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 

package/agent-docs/author/frontmatter-reference.sections/related-reading.md

@@ -16,13 +16,13 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-11-04.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
 This is the field inventory for this documentation site. The tables below are built from Shoalrun's native field definitions and this site's `frontmatter.fields` declarations on each build. They describe source page headers, not the shorter YAML header selected for a published Markdown page.
 
-`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It is **not** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
+`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It **isn't** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 

package/agent-docs/author/frontmatter-reference.sections/use-the-local-files-while-authoring.md

@@ -16,13 +16,13 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-11-04.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
 This is the field inventory for this documentation site. The tables below are built from Shoalrun's native field definitions and this site's `frontmatter.fields` declarations on each build. They describe source page headers, not the shorter YAML header selected for a published Markdown page.
 
-`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It is **not** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
+`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It **isn't** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 
@@ -30,6 +30,6 @@ For section exports, declare `standaloneSections` with `{ id, context: section }
 
 ## Use the local files while authoring
 
-Every project also gets `.shoalrun/frontmatter-reference.md` and `.shoalrun/frontmatter.schema.json` beside `docs.config.yaml`. They contain that project's inventory for authors, editors, and agents working in its repository. For this site, the paths are `docs/.shoalrun/frontmatter-reference.md` and `docs/.shoalrun/frontmatter.schema.json`. These internal files are not published site routes.
+Every project also gets `.shoalrun/frontmatter-reference.md` and `.shoalrun/frontmatter.schema.json` beside `docs.config.yaml`. They contain that project's inventory for authors, editors, and agents working in its repository. For this site, the paths are `docs/.shoalrun/frontmatter-reference.md` and `docs/.shoalrun/frontmatter.schema.json`. These internal files aren't published site routes.
 
-Changing a declaration and rebuilding updates the published table and both local files. Undeclared fields may still appear in source pages, but they have no project type check and do not appear in the field inventory.
+Changing a declaration and rebuilding updates the published table and both local files. Undeclared fields may still appear in source pages, but they have no project type check and don't appear in the field inventory.

package/agent-docs/author/frontmatter-reference.sections/when-the-files-update.md

@@ -16,13 +16,13 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-11-04.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
 This is the field inventory for this documentation site. The tables below are built from Shoalrun's native field definitions and this site's `frontmatter.fields` declarations on each build. They describe source page headers, not the shorter YAML header selected for a published Markdown page.
 
-`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It is **not** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
+`agent.intent` in the project-defined table is an optional string. This site's authors use it to describe the task a page helps an agent complete. It **isn't** a required Shoalrun field or an instruction to an agent. `editorial.reviewNote` is another site-specific field for internal review notes. A different project can declare different fields.
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.