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

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-10-28.**
+**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.
 
@@ -43,16 +43,18 @@ Use the page ID for links and cards that should survive a URL change. The slug s
 
 The project enables specific channel/version/language combinations. A page is built only for combinations matching its resolved values. `audiences` and `readerFilters` select reader views when the site config enables them; `access.policy` determines whether the page enters this public build. A draft page is excluded.
 
-| Field           | Type   | Needed      | What it changes                                                                                                                |
-| --------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `channel`       | string | Public page | Publication environment, such as sandbox or production; selects an enabled publication and API source.                         |
-| `version`       | string | Public page | API or documentation edition, such as v1; selects an enabled publication and API source.                                       |
-| `language`      | string | Optional    | Content language; uses frontmatter defaults/enforced values, then publications.defaults.language, then en.                     |
-| `locale`        | string | Optional    | Formatting conventions used in the content; can inherit a project locale for the page language and can be overridden per page. |
-| `access`        | object | Public page | Controls whether the page enters a public build; this object is not exported to Markdown metadata.                             |
-| `access.policy` | string | With access | Use public to publish this page; draft pages are excluded from the built site.                                                 |
-| `audiences`     | array  | Optional    | Readers this page is intended for; does not control who can access it.                                                         |
-| `readerFilters` | object | Optional    | Configured reader filter choices for this page. Missing facets are shared.                                                     |
+| Field           | Type    | Needed      | What it changes                                                                                                                                                                                                  |
+| --------------- | ------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `channel`       | string  | Public page | Publication environment, such as sandbox or production; selects an enabled publication and API source.                                                                                                           |
+| `version`       | string  | Public page | API or documentation edition, such as v1; selects an enabled publication and API source.                                                                                                                         |
+| `language`      | string  | Optional    | Content language; uses frontmatter defaults/enforced values, then publications.defaults.language, then en.                                                                                                       |
+| `locale`        | string  | Optional    | Formatting conventions used in the content; can inherit a project locale for the page language and can be overridden per page.                                                                                   |
+| `access`        | object  | Public page | Controls whether the page enters a public build; this object is not exported to Markdown metadata.                                                                                                               |
+| `access.policy` | string  | With access | Use public to publish this page; draft pages are excluded from the built site.                                                                                                                                   |
+| `shared`        | boolean | Optional    | Explicitly classify this page as shared across customer editions. Page-specific; cannot combine with requires. Sections may still use ForFeature.                                                                |
+| `requires`      | object  | Optional    | Build-time feature requirements from the shared SKU manifest. Both clauses must pass when present; omitted means shared within existing publication/access eligibility. Requires an explicit deployment profile. |
+| `audiences`     | array   | Optional    | Readers this page is intended for; does not control who can access it.                                                                                                                                           |
+| `readerFilters` | object  | Optional    | Configured reader filter choices for this page. Missing facets are shared.                                                                                                                                       |
 
 Language is the content language and selects a publication. Locale describes formatting conventions in the content and does not select a publication. `frontmatter.locales` can set a project locale for each language; pages may override it.
 
@@ -62,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.                                                                                                                                                                               |
@@ -88,6 +91,8 @@ By default, `product`, `area`, and `subarea` are optional, nonempty string categ
 
 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.
+
 ## Control output details
 
 `seo` changes the browser title or HTML meta description. `displayText` overrides the text chosen for one output surface on this page. `variables` supplies values to registered snippets before they expand into the page body. `markdownMetadata` selects or overrides the YAML preamble of the generated Markdown twin—the machine-readable copy of this page. That generated preamble is separate from the source frontmatter shown above.
@@ -120,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
 
@@ -142,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-10-28.**
+**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.
 
@@ -32,15 +32,17 @@ For section exports, declare `standaloneSections` with `{ id, context: section }
 
 The project enables specific channel/version/language combinations. A page is built only for combinations matching its resolved values. `audiences` and `readerFilters` select reader views when the site config enables them; `access.policy` determines whether the page enters this public build. A draft page is excluded.
 
-| Field           | Type   | Needed      | What it changes                                                                                                                |
-| --------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `channel`       | string | Public page | Publication environment, such as sandbox or production; selects an enabled publication and API source.                         |
-| `version`       | string | Public page | API or documentation edition, such as v1; selects an enabled publication and API source.                                       |
-| `language`      | string | Optional    | Content language; uses frontmatter defaults/enforced values, then publications.defaults.language, then en.                     |
-| `locale`        | string | Optional    | Formatting conventions used in the content; can inherit a project locale for the page language and can be overridden per page. |
-| `access`        | object | Public page | Controls whether the page enters a public build; this object is not exported to Markdown metadata.                             |
-| `access.policy` | string | With access | Use public to publish this page; draft pages are excluded from the built site.                                                 |
-| `audiences`     | array  | Optional    | Readers this page is intended for; does not control who can access it.                                                         |
-| `readerFilters` | object | Optional    | Configured reader filter choices for this page. Missing facets are shared.                                                     |
+| Field           | Type    | Needed      | What it changes                                                                                                                                                                                                  |
+| --------------- | ------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `channel`       | string  | Public page | Publication environment, such as sandbox or production; selects an enabled publication and API source.                                                                                                           |
+| `version`       | string  | Public page | API or documentation edition, such as v1; selects an enabled publication and API source.                                                                                                                         |
+| `language`      | string  | Optional    | Content language; uses frontmatter defaults/enforced values, then publications.defaults.language, then en.                                                                                                       |
+| `locale`        | string  | Optional    | Formatting conventions used in the content; can inherit a project locale for the page language and can be overridden per page.                                                                                   |
+| `access`        | object  | Public page | Controls whether the page enters a public build; this object is not exported to Markdown metadata.                                                                                                               |
+| `access.policy` | string  | With access | Use public to publish this page; draft pages are excluded from the built site.                                                                                                                                   |
+| `shared`        | boolean | Optional    | Explicitly classify this page as shared across customer editions. Page-specific; cannot combine with requires. Sections may still use ForFeature.                                                                |
+| `requires`      | object  | Optional    | Build-time feature requirements from the shared SKU manifest. Both clauses must pass when present; omitted means shared within existing publication/access eligibility. Requires an explicit deployment profile. |
+| `audiences`     | array   | Optional    | Readers this page is intended for; does not control who can access it.                                                                                                                                           |
+| `readerFilters` | object  | Optional    | Configured reader filter choices for this page. Missing facets are shared.                                                                                                                                       |
 
 Language is the content language and selects a publication. Locale describes formatting conventions in the content and does not select a publication. `frontmatter.locales` can set a project locale for each language; pages may override it.

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-10-28.**
+**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-10-28.**
+**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-10-28.**
+**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-10-28.**
+**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-10-28.**
+**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-10-28.**
+**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-10-28.**
+**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-10-28.**
+**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-10-28.**
+**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.