@shoalrun/cli 0.1.0-alpha.17 → 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-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.
 

package/agent-docs/author/frontmatter.md

@@ -23,7 +23,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Page metadata
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-05.**
 
 Frontmatter is the YAML header between the first two `---` lines of a `.md` or `.mdx` page. It gives a page its identity, URL, and publication settings. Start with this complete header, then write the page body below it:
 
@@ -79,7 +79,7 @@ Publication fields identify the channel, version, language, and access policy fo
 | `version`       | string                         | API or documentation version.                                                                                       |
 | `publications`  | list of `{ channel, version }` | Publish one source page in several channel/version combinations. Use instead of page-level `channel` and `version`. |
 | `language`      | string                         | Optional content language; resolved from globals, publication defaults, then `en`.                                  |
-| `locale`        | string                         | Optional conventions used for dates, numbers, and currency in the content; does not select a publication.           |
+| `locale`        | string                         | Optional conventions used for dates, numbers, and currency in the content; doesn't select a publication.            |
 | `access.policy` | string                         | Set to `public` for a public page.                                                                                  |
 
 Channel identifies an environment such as sandbox or production; version identifies an API or documentation edition; language identifies the content language. The resolved combination must be enabled in project config. `channel`, `version`, and `access` can come from global frontmatter. A language on the page overrides the default unless the project enforces one.
@@ -125,10 +125,10 @@ An explicit page policy of `public` publishes a finished page with these default
 The build reads every `.md` and `.mdx` file in the content directory, including drafts, and checks each header:
 
 - The header must start on the first line of the file, and a key may appear only once.
-- `slug` must start with `/` and cannot contain `..`, `?`, `#`, `%2f`, or `%5c`. Slugs under `/api` and `/.well-known` are reserved for published contracts and discovery files. Routes are compared without regard to case, so `/Guide` and `/guide` collide.
+- `slug` must start with `/` and can't contain `..`, `?`, `#`, `%2f`, or `%5c`. Slugs under `/api` and `/.well-known` are reserved for published contracts and discovery files. Routes are compared without regard to case, so `/Guide` and `/guide` collide.
 - Only `access.policy: public` publishes a page. Any other value, such as `draft`, keeps it out of every publication.
 - A public page whose channel, version, and language match no enabled publication is skipped without a warning. If a page is missing from the output, check its publication fields first.
-- A page with `publications` cannot also set page-level `channel` or `version`; a project-wide enforced channel or version must agree with every entry.
+- A page with `publications` can't also set page-level `channel` or `version`; a project-wide enforced channel or version must agree with every entry.
 - A public page fails while it still contains a scaffold placeholder or a scaffolded summary. See [templates](https://www.shoalrun.com/author/templates.md) for the exact patterns.
 
 `type` is free text, but some values change behavior. An `api-reference` page must list exactly one operation. `guide` and `how-to` pages can use `relatedApiReferences`. Any type can get its own Markdown metadata through [`byType` in Markdown metadata](https://www.shoalrun.com/author/markdown-metadata.md). The HTML page header shows the type as words: `api-reference` appears as "API reference".
@@ -141,7 +141,7 @@ These fields categorize pages, add connections, or change presentation. `product
 
 | Field                  | Type                               | Purpose                                                                                                                                                                                      |
 | ---------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `showNavigationTabs`   | boolean                            | Override the HTML navigation tab bar. Defaults to visible for docs and wide layouts, hidden for landing and splash. Does not affect agent discovery.                                         |
+| `showNavigationTabs`   | boolean                            | Override the HTML navigation tab bar. Defaults to visible for docs and wide layouts, hidden for landing and splash. Doesn't affect agent discovery.                                          |
 | `product`              | nonempty string                    | Product category; selects the `product` reader facet if configured.                                                                                                                          |
 | `area`                 | nonempty string or configured list | Area category; selects the `area` reader facet if configured.                                                                                                                                |
 | `subarea`              | nonempty string or configured list | Finer category; selects the `subarea` reader facet if configured.                                                                                                                            |
@@ -162,11 +162,11 @@ These fields categorize pages, add connections, or change presentation. `product
 | `displayText`          | object                             | Page-specific text for cards, the page header, search, HTML description, or social description.                                                                                              |
 | `variables`            | object                             | Page-level public values for registered snippets.                                                                                                                                            |
 
-For example, a page can use `product: payments`, `area: reporting`, and `subarea: settlements`. Those resolved values appear in `documents.json` and `search-index.json`. If the site config defines reader facets with those names, each value must be a configured choice ID and becomes that page's reader filter. Do not also set `readerFilters.product`, `.area`, or `.subarea` for the same field. Without a matching facet, the category is metadata only. A site's Markdown metadata projection can also select `frontmatter.product`, `frontmatter.area`, and `frontmatter.subarea`.
+For example, a page can use `product: payments`, `area: reporting`, and `subarea: settlements`. Those resolved values appear in `documents.json` and `search-index.json`. If the site config defines reader facets with those names, each value must be a configured choice ID and becomes that page's reader filter. Don't also set `readerFilters.product`, `.area`, or `.subarea` for the same field. Without a matching facet, the category is metadata only. A site's Markdown metadata projection can also select `frontmatter.product`, `frontmatter.area`, and `frontmatter.subarea`.
 
 Choose the [page layout](https://www.shoalrun.com/styling/layouts.md) before adjusting the outline. Use `layout: wide` to remove “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only need to hide the outline within the current layout.
 
-The default ToC includes headings through level 3. This page sets `tocDepth: 2`, so its ToC lists only the main sections. Use `tocDepth: 0` to suppress the ToC, or choose a depth from 2 through 6. Headings still appear in the page and Markdown twin when they are left out of the ToC.
+The default ToC includes headings through level 3. This page sets `tocDepth: 2`, so its ToC lists only the main sections. Use `tocDepth: 0` to suppress the ToC, or choose a depth from 2 through 6. Headings still appear in the page and Markdown twin when they're left out of the ToC.
 
 ## Give deprecation guidance
 
@@ -181,7 +181,7 @@ subjectDeprecation:
   migration: guide.migrate-endpoint
 ```
 
-Replace the example IDs with public documents in the same channel, version, and language. Use stable IDs without the `doc:` prefix. Each target must be a different document; external URLs, missing targets, draft targets, and automatic fallback to another publication are not supported.
+Replace the example IDs with public documents in the same channel, version, and language. Use stable IDs without the `doc:` prefix. Each target must be a different document; external URLs, missing targets, draft targets, and automatic fallback to another publication aren't supported.
 
 | Field          | Meaning                                                                   |
 | -------------- | ------------------------------------------------------------------------- |
@@ -190,17 +190,17 @@ Replace the example IDs with public documents in the same channel, version, and
 | `replacement`  | Stable ID of the page documenting the replacement.                        |
 | `migration`    | Stable ID of the page explaining how to migrate.                          |
 
-All four fields are optional, but the object must contain at least one. Unknown fields fail. Dates must be real `YYYY-MM-DD` calendar dates; when both are present, sunset cannot precede deprecation. The object stays page-specific and cannot appear in global defaults or enforced metadata. The resolved `subjectLifecycle` must be `deprecated`, whether authored or inferred from OpenAPI. A date does not change the status automatically or verify that a service has retired.
+All four fields are optional, but the object must contain at least one. Unknown fields fail. Dates must be real `YYYY-MM-DD` calendar dates; when both are present, sunset can't precede deprecation. The object stays page-specific and can't appear in global defaults or enforced metadata. The resolved `subjectLifecycle` must be `deprecated`, whether authored or inferred from OpenAPI. A date doesn't change the status automatically or verify that a service has retired.
 
 HTML, the full Markdown twin, and every published section resource show a subject deprecation notice with the supplied dates and links. HTML links open pages; Markdown links open their Markdown twins. `documents.json` carries the dates and resolved targets as `{ id, title, url, markdownUrl }` under `subjectDeprecation`. The manifest URLs are site paths, including any base path and publication prefix. Fetch-only readers can use the notice without parsing JSON or running JavaScript.
 
-These fields describe the documented subject. They do not retire the documentation resource, emit HTTP `Deprecation` or `Sunset` headers, change access, or establish verification. Fictional-example flags, editorial `lifecycle`, and `verified` remain independent. Omitting lifecycle information does not imply stability or verification.
+These fields describe the documented subject. They don't retire the documentation resource, emit HTTP `Deprecation` or `Sunset` headers, change access, or establish verification. Fictional-example flags, editorial `lifecycle`, and `verified` remain independent. Omitting lifecycle information doesn't imply stability or verification.
 
 ## Audience badges
 
-This page sets `audiences: [authors, maintainers]`, so its HTML header shows an **Intended audience** row with those two badges. Without [reader views](https://www.shoalrun.com/author/reader-views.md), write the labels as you want them displayed; they do not filter content. With an `audience` facet configured, use its choice IDs and Shoalrun displays the configured labels. A page without `audiences` has no audience row. Neither field restricts access; `access.policy` controls whether the page enters the public build.
+This page sets `audiences: [authors, maintainers]`, so its HTML header shows an **Intended audience** row with those two badges. Without [reader views](https://www.shoalrun.com/author/reader-views.md), write the labels as you want them displayed; they don't filter content. With an `audience` facet configured, use its choice IDs and Shoalrun displays the configured labels. A page without `audiences` has no audience row. Neither field restricts access; `access.policy` controls whether the page enters the public build.
 
-The site's Markdown metadata projection also selects `frontmatter.audiences`, so [this page's Markdown twin](https://www.shoalrun.com/author/frontmatter.md) lists the same values in its YAML header. A site can omit that projection field if its Markdown readers do not need audience labels.
+The site's Markdown metadata projection also selects `frontmatter.audiences`, so [this page's Markdown twin](https://www.shoalrun.com/author/frontmatter.md) lists the same values in its YAML header. A site can omit that projection field if its Markdown readers don't need audience labels.
 
 ## SEO fields
 
@@ -219,7 +219,7 @@ seo:
   description: Inspect the payment request and response.
 ```
 
-There are no other supported `seo.*` fields yet. Configure social images separately in [share images](https://www.shoalrun.com/styling/share-images.md). Use global frontmatter for site-wide SEO defaults or enforced values. The compiler now rejects unsupported page-level SEO keys so they cannot silently have no effect.
+There are no other supported `seo.*` fields yet. Configure social images separately in [share images](https://www.shoalrun.com/styling/share-images.md). Use global frontmatter for site-wide SEO defaults or enforced values. The compiler now rejects unsupported page-level SEO keys so they can't silently have no effect.
 
 ## Related metadata tasks
 

package/agent-docs/author/frontmatter.sections/audience-badges.md

@@ -23,7 +23,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Page metadata
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/frontmatter.md)
 
@@ -61,6 +61,6 @@ See the [generated frontmatter reference](https://www.shoalrun.com/author/frontm
 
 ## Audience badges
 
-This page sets `audiences: [authors, maintainers]`, so its HTML header shows an **Intended audience** row with those two badges. Without [reader views](https://www.shoalrun.com/author/reader-views.md), write the labels as you want them displayed; they do not filter content. With an `audience` facet configured, use its choice IDs and Shoalrun displays the configured labels. A page without `audiences` has no audience row. Neither field restricts access; `access.policy` controls whether the page enters the public build.
+This page sets `audiences: [authors, maintainers]`, so its HTML header shows an **Intended audience** row with those two badges. Without [reader views](https://www.shoalrun.com/author/reader-views.md), write the labels as you want them displayed; they don't filter content. With an `audience` facet configured, use its choice IDs and Shoalrun displays the configured labels. A page without `audiences` has no audience row. Neither field restricts access; `access.policy` controls whether the page enters the public build.
 
-The site's Markdown metadata projection also selects `frontmatter.audiences`, so [this page's Markdown twin](https://www.shoalrun.com/author/frontmatter.md) lists the same values in its YAML header. A site can omit that projection field if its Markdown readers do not need audience labels.
+The site's Markdown metadata projection also selects `frontmatter.audiences`, so [this page's Markdown twin](https://www.shoalrun.com/author/frontmatter.md) lists the same values in its YAML header. A site can omit that projection field if its Markdown readers don't need audience labels.