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

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.

package/agent-docs/author/frontmatter.sections/give-deprecation-guidance.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)
 
@@ -72,7 +72,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                                                                   |
 | -------------- | ------------------------------------------------------------------------- |
@@ -81,8 +81,8 @@ 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.

package/agent-docs/author/frontmatter.sections/global-defaults-and-enforced-values.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)
 

package/agent-docs/author/frontmatter.sections/optional-native-fields.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)
 
@@ -65,7 +65,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.                                                                                                                            |
@@ -86,8 +86,8 @@ 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.

package/agent-docs/author/frontmatter.sections/publication-fields.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)
 
@@ -69,7 +69,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.

package/agent-docs/author/frontmatter.sections/publishing-policy.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)
 

package/agent-docs/author/frontmatter.sections/related-metadata-tasks.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)
 

package/agent-docs/author/frontmatter.sections/related-reading.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)
 

package/agent-docs/author/frontmatter.sections/required-after-inheritance.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)
 

package/agent-docs/author/frontmatter.sections/seo-fields.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)
 
@@ -76,4 +76,4 @@ 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.

package/agent-docs/author/frontmatter.sections/validation-rules.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)
 
@@ -64,10 +64,10 @@ See the [generated frontmatter reference](https://www.shoalrun.com/author/frontm
 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".

package/agent-docs/author/markdown-metadata.md

@@ -17,9 +17,9 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Markdown metadata
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-05.**
 
-The build publishes [the page metadata guide as Markdown](https://www.shoalrun.com/author/frontmatter.md) alongside its HTML page. That `.md` file starts with a YAML header containing selected values from the source page header. Source headers can grow long and contain review notes or other details that do not help an agent read the page. Selecting a small set of useful fields keeps the agent's context focused and avoids exposing internal metadata in that header. Compare the two custom values in that guide's source:
+The build publishes [the page metadata guide as Markdown](https://www.shoalrun.com/author/frontmatter.md) alongside its HTML page. That `.md` file starts with a YAML header containing selected values from the source page header. Source headers can grow long and contain review notes or other details that don't help an agent read the page. Selecting a small set of useful fields keeps the agent's context focused and avoids exposing internal metadata in that header. Compare the two custom values in that guide's source:
 
 ```yaml title="docs/content/frontmatter.mdx"
 agent:
@@ -72,7 +72,7 @@ outputs:
 
 Each entry under `fields` names an output key on the left and its source on the right. Here `summary` and `description` stay separate, while `audiences` comes from the page's intended-reader labels. The `byType.reference` rule adds `agent.intent` only for pages whose `type` is `reference`. `subjectLifecycle` is absent from the example output because that guide has no subjectLifecycle value and `omitNull` is true.
 
-The review note is absent because its declaration sets `public: false` and the output config does not select it. This controls only the generated YAML header: text written in the page body still appears in the published Markdown and HTML.
+The review note is absent because its declaration sets `public: false` and the output config doesn't select it. This controls only the generated YAML header: text written in the page body still appears in the published Markdown and HTML.
 
 Keep this header short. Include the fields an agent needs for the page, and leave out long descriptions or notes that take up its context.
 
@@ -82,14 +82,14 @@ Keep this header short. Include the fields an agent needs for the page, and leav
 
 A field source is either `frontmatter.<path>` or one of these publication values:
 
-| Source                     | Value                                                                                    |
-| -------------------------- | ---------------------------------------------------------------------------------------- |
-| `publication.channel`      | The page's publication channel.                                                          |
-| `publication.version`      | The page's publication version.                                                          |
-| `publication.language`     | The page's language.                                                                     |
-| `publication.canonicalUrl` | The page route, such as `/author/frontmatter`. It is site-relative, not an absolute URL. |
+| Source                     | Value                                                                                   |
+| -------------------------- | --------------------------------------------------------------------------------------- |
+| `publication.channel`      | The page's publication channel.                                                         |
+| `publication.version`      | The page's publication version.                                                         |
+| `publication.language`     | The page's language.                                                                    |
+| `publication.canonicalUrl` | The page route, such as `/author/frontmatter`. It's site-relative, not an absolute URL. |
 
-Built-in public fields can be selected directly. A custom field needs a declaration with `public: true`. The protected roots `access`, `seo`, `markdownMetadata`, `variables`, `tocDepth`, `private`, `internal`, `card`, and `displayText` cannot be selected under any name. With `omitNull: false`, a missing value fails the build instead of being skipped.
+Built-in public fields can be selected directly. A custom field needs a declaration with `public: true`. The protected roots `access`, `seo`, `markdownMetadata`, `variables`, `tocDepth`, `private`, `internal`, `card`, and `displayText` can't be selected under any name. With `omitNull: false`, a missing value fails the build instead of being skipped.
 
 Layers apply in order. The base settings come first, then `byType.<type>`, then a named profile, then the page's own override. Each layer accepts `format`, `fields`, `addFields`, `removeFields`, and `omitNull`. `fields` replaces the inherited fields; `addFields` merges into them; `removeFields` drops output names and fails if a name is missing.
 
@@ -149,7 +149,7 @@ agent:
   intent: Help a reader install Acme.
 ```
 
-Every Markdown copy carries the field, one copy for each publication the page is in. Without `required: true`, a page that lacks the value is skipped when `omitNull` is true and fails the build when it is false. A shared default from `frontmatter.defaults` also satisfies `required: true`.
+Every Markdown copy carries the field, one copy for each publication the page is in. Without `required: true`, a page that lacks the value is skipped when `omitNull` is true and fails the build when it's false. A shared default from `frontmatter.defaults` also satisfies `required: true`.
 
 ## Published Markdown size
 
@@ -159,7 +159,7 @@ Use the record's `markdownUrl` and publication coordinates to select the file. T
 
 ## Declare sections that can be read alone
 
-For a section that is complete without the page introduction, use its ID and an explicit context:
+For a section that's complete without the page introduction, use its ID and an explicit context:
 
 ```yaml
 standaloneSections:
@@ -168,23 +168,23 @@ standaloneSections:
 
 This declaration approves the section for contextual discovery and for section-only content export. Exporting it still requires selection in an export target. Review the section alone: its required setup, definitions, warnings, and steps must be present. If it depends on other parts of the page, leave it undeclared and use a full-page read.
 
-Search recommends a declared section only when its heading uniquely matches the query and the section meets size requirements. Discovery files still repeat the page introduction and reading-path context; the object does not change that response format.
+Search recommends a declared section only when its heading uniquely matches the query and the section meets size requirements. Discovery files still repeat the page introduction and reading-path context; the object doesn't change that response format.
 
-This field is page-specific; site defaults and enforced values cannot set it. Each ID must match exactly one root-level H2 heading. Missing or duplicate declarations fail the build, even on short pages. The compiler checks identity and size eligibility; it cannot verify the author's claim about completeness. Re-review declarations when content or prerequisites change.
+This field is page-specific; site defaults and enforced values can't set it. Each ID must match exactly one root-level H2 heading. Missing or duplicate declarations fail the build, even on short pages. The compiler checks identity and size eligibility; it can't verify the author's claim about completeness. Re-review declarations when content or prerequisites change.
 
 ### Compatibility with contextual-only approvals
 
 Older declarations use exact heading titles, such as `standaloneSections: [Try the page controls]`. They approve a discovery read with its repeated page context, not a section-only export. Keep existing declarations when the section depends on that context. The [compatibility guidance](https://www.shoalrun.com/content-delivery/sections.md) explains the review required before changing to an ID-based object.
 
-Omitting the list, using an empty list, or reading an older search index makes search use full pages for those headings. Size eligibility still applies to declared headings. Undeclared resources remain available through outlines and explicit section reads for callers that already have the context. Fetch-only consumers should require `standalone: true` before automatically choosing a section. A declaration does not guarantee relevance to every question; use the full-page fallback for broader tasks.
+Omitting the list, using an empty list, or reading an older search index makes search use full pages for those headings. Size eligibility still applies to declared headings. Undeclared resources remain available through outlines and explicit section reads for callers that already have the context. Fetch-only consumers should require `standalone: true` before automatically choosing a section. A declaration doesn't guarantee relevance to every question; use the full-page fallback for broader tasks.
 
 ## Fetch one section
 
-The section resources described here are contextual agent reads. [Content delivery](https://www.shoalrun.com/content-delivery/agents.md) provides separately approved application fragments. Its ID-based approval does not change the meaning of existing title declarations.
+The section resources described here are contextual agent reads. [Content delivery](https://www.shoalrun.com/content-delivery/agents.md) provides separately approved application fragments. Its ID-based approval doesn't change the meaning of existing title declarations.
 
-Each page record in `documents.json` now includes a `sections` outline. Entries describe top-level level-two headings in the normalized content tree. A section includes its nested headings and components through the next top-level heading of the same or higher level. Headings inside tabs, reader sections, lists, or disclosures do not become separate resources. Section files are generated only when the full page has at least 2,000 `cl100k_base` tokens and the complete section, including repeated context, uses at most half the page’s bytes and tokens. Other pages and sections use the full Markdown page; their outlines can be empty.
+Each page record in `documents.json` now includes a `sections` outline. Entries describe top-level level-two headings in the normalized content tree. A section includes its nested headings and components through the next top-level heading of the same or higher level. Headings inside tabs, reader sections, lists, or disclosures don't become separate resources. Section files are generated only when the full page has at least 2,000 `cl100k_base` tokens and the complete section, including repeated context, uses at most half the page’s bytes and tokens. Other pages and sections use the full Markdown page; their outlines can be empty.
 
-Fetch the entry's `markdownUrl` for a complete section file. For example, the agent-friendliness page has a section at `/publish/agent-friendliness.sections/try-the-page-controls.md`. These are real static resources: adding `#heading` to the full page URL does not make an HTTP request smaller. The compact search index includes eligible section titles, URLs, sizes, and standalone declarations, so fetch-only agents can select them without downloading the full manifest. The short `llms.min.txt` index lists full pages and nests only author-declared standalone section links, with exact sizes and a **Full page** fallback. A fetch-only agent can use those text links without reading JSON or calling a search tool.
+Fetch the entry's `markdownUrl` for a complete section file. For example, the agent-friendliness page has a section at `/publish/agent-friendliness.sections/try-the-page-controls.md`. These are real static resources: adding `#heading` to the full page URL doesn't make an HTTP request smaller. The compact search index includes eligible section titles, URLs, sizes, and standalone declarations, so fetch-only agents can select them without downloading the full manifest. The short `llms.min.txt` index lists full pages and nests only author-declared standalone section links, with exact sizes and a **Full page** fallback. A fetch-only agent can use those text links without reading JSON or calling a search tool.
 
 Each file repeats the parent's projected metadata, title, publication dates, navigation, introductory content, and fictional-content notice when present. It then includes the selected section with all nested reader labels and code fences. Top-level current-page `RelatedReading` prerequisites and next steps omitted by the section boundary are included as a labeled **Page reading path**, without duplicating links already in the selected content. Nested or other-page relationship views remain in their original scope; see [reading paths](https://www.shoalrun.com/author/related-reading.md). Shared reference definitions are retained. Local fragment links point back to the full parent Markdown page. Section files are complete representations, not byte slices of the parent.
 
@@ -197,7 +197,7 @@ Each file repeats the parent's projected metadata, title, publication dates, nav
 | `digest`                                                   | SHA-256 of the complete section file.                                                                                      |
 | `markdownBytes`, `markdownTokens`, `markdownTokenEncoding` | Exact section size, using the same UTF-8 and `cl100k_base` rules as page metadata.                                         |
 
-Section IDs use normalized lowercase title text, ASCII letters and digits, and hyphens, limited to an 80-character stem. A title with no usable characters uses `section`. Collisions receive suffixes beginning with `-2` in document order. These IDs are not permanent: renaming, inserting, or reordering headings can change them. Cite the stable page ID, publication coordinates, section ID, section URL, and both digests. The surrounding manifest supplies the page identity, publication, and build ID.
+Section IDs use normalized lowercase title text, ASCII letters and digits, and hyphens, limited to an 80-character stem. A title with no usable characters uses `section`. Collisions receive suffixes beginning with `-2` in document order. These IDs aren't permanent: renaming, inserting, or reordering headings can change them. Cite the stable page ID, publication coordinates, section ID, section URL, and both digests. The surrounding manifest supplies the page identity, publication, and build ID.
 
 From the repository root, inspect and read the agent-friendliness example's sections with the local CLI:
 
@@ -206,7 +206,7 @@ npx --no-install shoalrun docs outline guide.agent-friendliness --max-tokens 100
 npx --no-install shoalrun docs section guide.agent-friendliness try-the-page-controls --max-tokens 10000
 ```
 
-For ordinary retrieval, start with `docs search` and follow the result’s `read` instruction; the outline command is optional. Search returns a recommended `markdownUrl` and a `pageMarkdownUrl` fallback. Both commands above return JSON. Select `--channel`, `--version`, and `--language` when a page has multiple publications. The outline and section must fit the requested token budget in full; increase `--max-tokens` when they do not. Section reads verify the file digest and its link to the parent record. [MCP clients](https://www.shoalrun.com/publish/mcp.md) can use `get_outline` and `get_section` for the same operations. Rebuild older sites to add section resources.
+For ordinary retrieval, start with `docs search` and follow the result’s `read` instruction; the outline command is optional. Search returns a recommended `markdownUrl` and a `pageMarkdownUrl` fallback. Both commands above return JSON. Select `--channel`, `--version`, and `--language` when a page has multiple publications. The outline and section must fit the requested token budget in full; increase `--max-tokens` when they don't. Section reads verify the file digest and its link to the parent record. [MCP clients](https://www.shoalrun.com/publish/mcp.md) can use `get_outline` and `get_section` for the same operations. Rebuild older sites to add section resources.
 
 ## Related reading
 

package/agent-docs/author/navigation.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Navigation > Overview
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 The `navigation` setting controls the site's left menu. It can be a list in `docs.config.yaml` or import a separate YAML file. Add guides, tutorials, concepts, and reference pages by their stable document IDs. Nodes appear in the order you write them.
 
@@ -27,7 +27,7 @@ Each node has a stable `id` for the menu entry. It needs exactly one of these ta
 - `operation` places an API reference by stable operation ID.
 - `generated` fills in API references from the registered OpenAPI source.
 
-The menu follows document IDs rather than file paths or slugs. Moving a source file or changing a page URL does not require a navigation edit. A `doc` node uses the page title by default; set `label` when the menu needs a shorter name. Pages omitted from navigation can still be built and linked from other pages.
+The menu follows document IDs rather than file paths or slugs. Moving a source file or changing a page URL doesn't require a navigation edit. A `doc` node uses the page title by default; set `label` when the menu needs a shorter name. Pages omitted from navigation can still be built and linked from other pages.
 
 ## Arrange authored pages
 
@@ -51,9 +51,9 @@ The menu follows document IDs rather than file paths or slugs. Moving a source f
       doc: guide.handle-errors
 ```
 
-Each `doc` value must match a page's frontmatter ID. Groups can contain other groups, so a larger site can place task guides under a product area. Use a structure that matches the reader's tasks; the source directory layout does not control the menu. The build rejects missing document IDs and malformed groups. For a publication where a page has no matching channel, version, or language, its menu entry is omitted. An empty group is omitted too.
+Each `doc` value must match a page's frontmatter ID. Groups can contain other groups, so a larger site can place task guides under a product area. Use a structure that matches the reader's tasks; the source directory layout doesn't control the menu. The build rejects missing document IDs and malformed groups. For a publication where a page has no matching channel, version, or language, its menu entry is omitted. An empty group is omitted too.
 
-Use `search` on an individual page or operation node to add terms to the reader's **sidebar menu filter**. The filter also matches the page label and its group labels. For example, `search: refunds returns` helps readers find a page whose title uses different words. This setting does not add terms to the site-wide search index; [site search](https://www.shoalrun.com/author/search.md) uses page content and search metadata. Groups and generators cannot have `search`.
+Use `search` on an individual page or operation node to add terms to the reader's **sidebar menu filter**. The filter also matches the page label and its group labels. For example, `search: refunds returns` helps readers find a page whose title uses different words. This setting doesn't add terms to the site-wide search index; [site search](https://www.shoalrun.com/author/search.md) uses page content and search metadata. Groups and generators can't have `search`.
 
 ## Split navigation into tabs
 
@@ -78,13 +78,13 @@ Use navigation tabs for parallel sections such as Guides, API reference, and Rec
 
 Replace the example IDs and API name with your project's values. A tab ID uses lowercase letters, digits, and hyphens and starts with a letter. Tabs require a label, nonempty items, and a landing document inside those items. Nested tabs fail the build. A published page can belong to only one tab, or to shared navigation; placing it in both fails the build. Tabs whose items have no pages in a publication are omitted. A nonempty tab whose landing page is unavailable in that publication fails the build.
 
-Each tab links to its landing page. The current page's URL selects its tab and sidebar on the server. Opening a direct link, following a search result, or navigating without JavaScript selects the same section. Groups outside tabs remain shared navigation. A page outside every tab shows the shared navigation with no tab selected. Existing navigation lists work without adding tabs. Tab placement does not change page URLs or publication routes.
+Each tab links to its landing page. The current page's URL selects its tab and sidebar on the server. Opening a direct link, following a search result, or navigating without JavaScript selects the same section. Groups outside tabs remain shared navigation. A page outside every tab shows the shared navigation with no tab selected. Existing navigation lists work without adding tabs. Tab placement doesn't change page URLs or publication routes.
 
 The section links appear below the masthead on docs and wide pages. Landing and splash pages hide them by default. Set `showNavigationTabs: true` or `false` in page frontmatter to override the layout default; see [page layouts](https://www.shoalrun.com/styling/layouts.md). On smaller screens, Menu opens a drawer containing these section links and the current sidebar. Closing the drawer restores focus and the article's scroll position. Without JavaScript, Menu links to navigation below the article and section links remain in a native disclosure. They inherit each theme's typography and colors. Site-wide search still includes all sections; the sidebar filter searches only the current sidebar. Reader views can filter that sidebar without changing tab membership or agent discovery.
 
 ### Agent discovery across tabs
 
-Both `/llms.min.txt` and `/llms.txt` keep every published page and add links to a scoped text index for each tab and publication. Follow the published `indexUrl`; do not construct it from the page's URL. Each scoped index links to all of that tab's Markdown pages and back to the global index, which also includes shared pages and pages omitted from navigation.
+Both `/llms.min.txt` and `/llms.txt` keep every published page and add links to a scoped text index for each tab and publication. Follow the published `indexUrl`; don't construct it from the page's URL. Each scoped index links to that tab's Markdown pages and back to the global index. The global index also includes shared pages and pages omitted from navigation.
 
 Each member page's Markdown identifies its navigation section, stable tab ID, and scoped index. Its breadcrumbs include the tab. `documents.json` publishes a `navigationTabs` catalog and a matching `navigationTab` record on each member page. Records contain `id`, `label`, `variant`, `url`, `markdownUrl`, and `indexUrl`. Both search indexes carry page membership too. The generated offline documentation bundle includes the scoped indexes.
 
@@ -98,7 +98,7 @@ On smaller screens, the page outline moves into an **On this page** disclosure b
 
 ## Hide group page counts
 
-To hide the “Explore” heading above the navigation filter, set `outputs.html.navigation.heading` to `false`. Available since `0.1.0-alpha.13`.
+To hide the “Explore” heading above the navigation filter, set `outputs.html.navigation.heading` to `false`. Since 0.1.0-alpha.13
 
 ```yaml
 outputs:
@@ -118,7 +118,7 @@ outputs:
       showCounts: false
 ```
 
-The setting applies to every group, including nested groups and API navigation. The menu filter still finds pages and hides empty groups. Set `showCounts: true`, or omit it, to show counts again. This setting does not change Markdown output.
+The setting applies to every group, including nested groups and API navigation. The menu filter still finds pages and hides empty groups. Set `showCounts: true`, or omit it, to show counts again. This setting doesn't change Markdown output.
 
 ## Optionally split a large menu into files
 
@@ -189,9 +189,9 @@ The Components group shows the two basics first, then Tabs and Fields. Each incl
 
 The build resolves the navigation list before publishing either format. HTML documentation pages show the current tab's hierarchy and shared navigation as links inside expandable groups. Without tabs, the sidebar shows the full hierarchy. The active page is marked `aria-current="page"`. JavaScript adds the sidebar filter; the links and groups remain usable without it. A page's breadcrumb trail also follows its navigation position.
 
-The Markdown twin does **not** repeat the full sidebar on every page. It puts that page's breadcrumb path near the title—for example, `Write documentation > Components > Callouts`. The [document manifest](https://www.shoalrun.com/documents.json) records the same ordered path as a `breadcrumbs` array with labels and URLs where a level has a page. `/llms.txt` lists every published page with a link to its Markdown twin, including pages omitted from the sidebar.
+The Markdown twin **doesn't** repeat the full sidebar on every page. It puts that page's breadcrumb path near the title—for example, `Write documentation > Components > Callouts`. The [document manifest](https://www.shoalrun.com/documents.json) records the same ordered path as a `breadcrumbs` array with labels and URLs where a level has a page. `/llms.txt` lists every published page with a link to its Markdown twin, including pages omitted from the sidebar.
 
-An agent can use `/llms.txt` to discover pages and `/documents.json` to recover their hierarchy, then read the Markdown pages. Changing only how YAML files are split leaves the rendered navigation and breadcrumb paths unchanged; the manifest still records the included files as build dependencies. Moving or relabeling a page changes its HTML navigation, Markdown breadcrumb, and manifest path. The node's `search` words help only the HTML sidebar filter; they do not affect Markdown or agent search.
+An agent can use `/llms.txt` to discover pages and `/documents.json` to recover their hierarchy, then read the Markdown pages. Changing only how YAML files are split leaves the rendered navigation and breadcrumb paths unchanged; the manifest still records the included files as build dependencies. Moving or relabeling a page changes its HTML navigation, Markdown breadcrumb, and manifest path. The node's `search` words help only the HTML sidebar filter; they don't affect Markdown or agent search.
 
 ## Mix guides and API references
 
@@ -210,7 +210,7 @@ An API reference is a document too, so `doc: reference.create-payment` works bes
       generated: tags
 ```
 
-`generated: tags` groups the remaining endpoints by their first OpenAPI tag. Declared tag order and source operation order are retained **only for those remaining endpoints**. To override the position of a generated reference, add its stable operation ID as an explicit `operation:` entry at the desired point in this YAML list. You do not need to create an MDX page. An explicit `doc` or `operation` placement wins regardless of where the generator appears, so the same endpoint appears once. Leave out the generator when you want to choose every menu entry yourself. Navigation resolves separately for each channel, version, and language.
+`generated: tags` groups the remaining endpoints by their first OpenAPI tag. Declared tag order and source operation order are retained **only for those remaining endpoints**. To override the position of a generated reference, add its stable operation ID as an explicit `operation:` entry at the desired point in this YAML list. You don't need to create an MDX page. An explicit `doc` or `operation` placement wins regardless of where the generator appears, so the same endpoint appears once. Leave out the generator when you want to choose every menu entry yourself. Navigation resolves separately for each channel, version, and language.
 
 An API might tag every `/Query/` route as `Query`, while readers look for `GET /Query/widgets` under **Widgets**. Place its stable operation ID among the widget operations:
 
@@ -261,7 +261,7 @@ The preview layout must cover every selected operation directly or through `gene
 
 Set `subjectLifecycle` to `beta`, `in-development`, `experimental`, or `deprecated` in page frontmatter. Navigation and page headers show a text badge. Markdown and the document manifest carry the same status.
 
-OpenAPI `deprecated: true` marks an endpoint as deprecated and cannot be overridden by an editorial label. The preview layout can also assign a label by source operation ID. Labels communicate maturity; they do not control access.
+OpenAPI `deprecated: true` marks an endpoint as deprecated and can't be overridden by an editorial label. The preview layout can also assign a label by source operation ID. Labels communicate maturity; they don't control access.
 
 For a deprecated subject, add [deprecation guidance](https://www.shoalrun.com/author/frontmatter.md) with optional dates, replacement, and migration references. These details appear in the article and Markdown resources; navigation keeps its concise status badge.
 

package/agent-docs/author/navigation.sections/arrange-authored-pages.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Navigation > Overview
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/navigation.md)
 
@@ -29,7 +29,7 @@ Each node has a stable `id` for the menu entry. It needs exactly one of these ta
 - `operation` places an API reference by stable operation ID.
 - `generated` fills in API references from the registered OpenAPI source.
 
-The menu follows document IDs rather than file paths or slugs. Moving a source file or changing a page URL does not require a navigation edit. A `doc` node uses the page title by default; set `label` when the menu needs a shorter name. Pages omitted from navigation can still be built and linked from other pages.
+The menu follows document IDs rather than file paths or slugs. Moving a source file or changing a page URL doesn't require a navigation edit. A `doc` node uses the page title by default; set `label` when the menu needs a shorter name. Pages omitted from navigation can still be built and linked from other pages.
 
 ## Arrange authored pages
 
@@ -53,6 +53,6 @@ The menu follows document IDs rather than file paths or slugs. Moving a source f
       doc: guide.handle-errors
 ```
 
-Each `doc` value must match a page's frontmatter ID. Groups can contain other groups, so a larger site can place task guides under a product area. Use a structure that matches the reader's tasks; the source directory layout does not control the menu. The build rejects missing document IDs and malformed groups. For a publication where a page has no matching channel, version, or language, its menu entry is omitted. An empty group is omitted too.
+Each `doc` value must match a page's frontmatter ID. Groups can contain other groups, so a larger site can place task guides under a product area. Use a structure that matches the reader's tasks; the source directory layout doesn't control the menu. The build rejects missing document IDs and malformed groups. For a publication where a page has no matching channel, version, or language, its menu entry is omitted. An empty group is omitted too.
 
-Use `search` on an individual page or operation node to add terms to the reader's **sidebar menu filter**. The filter also matches the page label and its group labels. For example, `search: refunds returns` helps readers find a page whose title uses different words. This setting does not add terms to the site-wide search index; [site search](https://www.shoalrun.com/author/search.md) uses page content and search metadata. Groups and generators cannot have `search`.
+Use `search` on an individual page or operation node to add terms to the reader's **sidebar menu filter**. The filter also matches the page label and its group labels. For example, `search: refunds returns` helps readers find a page whose title uses different words. This setting doesn't add terms to the site-wide search index; [site search](https://www.shoalrun.com/author/search.md) uses page content and search metadata. Groups and generators can't have `search`.

package/agent-docs/author/navigation.sections/fill-an-api-tag-group.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Navigation > Overview
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/navigation.md)
 
@@ -29,7 +29,7 @@ Each node has a stable `id` for the menu entry. It needs exactly one of these ta
 - `operation` places an API reference by stable operation ID.
 - `generated` fills in API references from the registered OpenAPI source.
 
-The menu follows document IDs rather than file paths or slugs. Moving a source file or changing a page URL does not require a navigation edit. A `doc` node uses the page title by default; set `label` when the menu needs a shorter name. Pages omitted from navigation can still be built and linked from other pages.
+The menu follows document IDs rather than file paths or slugs. Moving a source file or changing a page URL doesn't require a navigation edit. A `doc` node uses the page title by default; set `label` when the menu needs a shorter name. Pages omitted from navigation can still be built and linked from other pages.
 
 ## Fill an API tag group