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

package/agent-docs/author/analytics.sections/posthog-example.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Analytics
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/analytics.md)
 
@@ -86,7 +86,7 @@ This example sends native page views and page leaves to PostHog, with custom eve
 
    The adapter maps `page_view` to `$pageview` and keeps other Shoalrun event names. Automatic page views are off to avoid duplicates. PostHog supplies `$pageleave` with scroll depth and duration. Generic click capture, replay, and person profiles are disabled.
 
-   Use custom names in Product Analytics insights and funnels. Do not map them to `$autocapture`, which requires SDK-generated element metadata. PostHog adds properties and manages browser storage; review its [SDK configuration](https://posthog.com/docs/libraries/js/config) for consent and content security policy requirements.
+   Use custom names in Product Analytics insights and funnels. Don't map them to `$autocapture`, which requires SDK-generated element metadata. PostHog adds properties and manages browser storage; review its [SDK configuration](https://posthog.com/docs/libraries/js/config) for consent and content security policy requirements.
 
 3. ### Bundle and configure the module
 
@@ -121,6 +121,6 @@ This example sends native page views and page leaves to PostHog, with custom eve
    | `$prev_pageview_max_content_percentage` | Fraction of document height reached by the viewport, from `0` to `1`. |
    | `$prev_pageview_duration`               | Seconds the page was open.                                            |
 
-   These measure the document, excluding scrolling within code panes. Time open does not prove active reading, and page-leave delivery is best effort. For visual scrollmaps, configure [PostHog heatmaps](https://posthog.com/docs/toolbar/heatmaps) separately; some engagement metrics require generic autocapture.
+   These measure the document, excluding scrolling within code panes. Time open doesn't prove active reading, and page-leave delivery is best effort. For visual scrollmaps, configure [PostHog heatmaps](https://posthog.com/docs/toolbar/heatmaps) separately; some engagement metrics require generic autocapture.
 
    If events are missing, check consent, browser blockers, and network requests. Exclude development traffic from production reports or use a separate development project.

package/agent-docs/author/analytics.sections/related-reading.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Analytics
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/analytics.md)
 

package/agent-docs/author/authoring-agent.md

@@ -19,7 +19,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Advanced workflows > Checked edit plans
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
@@ -71,13 +71,13 @@ Use this optional workflow when your agent needs a digest-checked replacement pl
    shoalrun audit docs.config.yaml
    ```
 
-   Applying repeats freshness and build checks before writing. Inspect the resulting HTML and Markdown. The plan does not run configured audit tests, commit changes, or deploy; those are separate steps.
+   Applying repeats freshness and build checks before writing. Inspect the resulting HTML and Markdown. The plan doesn't run configured audit tests, commit changes, or deploy; those are separate steps.
 
 ## What checks establish
 
 Compiler checks catch problems such as broken document links and invalid components. Vale checks the rules your team configures. Neither establishes factual accuracy or whether a procedure works. Ask your agent to explain what it verified and what still needs review.
 
-Ordinary public builds exclude draft pages. Use the separate working-tree `docs validate` interface to render affected drafts in isolation without changing their authored access policy. This does not change the checked plan/apply contract described above.
+Ordinary public builds exclude draft pages. Use the separate working-tree `docs validate` interface to render affected drafts in isolation without changing their authored access policy. This doesn't change the checked plan/apply contract described above.
 
 ## Related reading
 

package/agent-docs/author/coding-agent.md

@@ -18,15 +18,15 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Draft a page
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Use an agent that can read project files and run commands. It writes with its own model; Shoalrun requires no additional authoring API key.
 
 ## Prepare your agent
 
-Install the [portable authoring skill](https://www.shoalrun.com/contribute/agent-skills.md) using your agent's supported skill setup. If it cannot load skills, give it the same project instructions and commands directly. Tell it where to find `docs.config.yaml`, your writing guide, and reviewed examples. The [example writing guide](https://www.shoalrun.com/author/writing-style.md) is a starting point you can adapt.
+Install the [portable authoring skill](https://www.shoalrun.com/contribute/agent-skills.md) using your agent's supported skill setup. If it can't load skills, give it the same project instructions and commands directly. Tell it where to find `docs.config.yaml`, your writing guide, and reviewed examples. The [example writing guide](https://www.shoalrun.com/author/writing-style.md) is a starting point you can adapt.
 
-The CLI's `docs search` and `docs read` commands read bundled Shoalrun guidance. The [MCP server](https://www.shoalrun.com/cli.md) offers documentation search and reads for agents that support MCP; it does not write project files. Your agent uses its own file tools and the CLI for edits.
+The CLI's `docs search` and `docs read` commands read bundled Shoalrun guidance. The [MCP server](https://www.shoalrun.com/cli.md) offers documentation search and reads for agents that support MCP; it doesn't write project files. Your agent uses its own file tools and the CLI for edits.
 
 ## Give a working-tree task
 
@@ -69,7 +69,7 @@ This uses the harness's own writer and execution permissions. Required navigatio
    shoalrun docs preview /path/from/result/report.json --port 0
    ```
 
-   Use the actual report path returned by validation. It renders affected drafts in a separate capture while preserving their authored access policy. Review findings, coverage, and skipped checks; use `--run-checks` only for applicable trusted commands under the harness's permissions. A stale, failed, incomplete, or unavailable result is not a pass. After edits, revalidate and restart the preview from the new report. Stop the foreground preview with Ctrl-C when finished.
+   Use the actual report path returned by validation. It renders affected drafts in a separate capture while preserving their authored access policy. Review findings, coverage, and skipped checks; use `--run-checks` only for applicable trusted commands under the harness's permissions. A stale, failed, incomplete, or unavailable result isn't a pass. After edits, revalidate and restart the preview from the new report. Stop the foreground preview with Ctrl-C when finished.
 
 4. ## Prepare publication
 

package/agent-docs/author/components/api-embeds.md

@@ -20,7 +20,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > ApiExample and ApiSchema
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 `ApiExample` and `ApiSchema` reuse OpenAPI content in authored pages. Examples stay synchronized with named payloads; schemas expose selected field definitions in HTML and Markdown.
 
@@ -46,7 +46,7 @@ Use these attributes to configure the component.
 | `example`   | Yes           | Key in that media type's OpenAPI `examples` map. |
 | `status`    | For responses | Response status, such as `201`.                  |
 
-The element is standalone and empty, with literal string attributes. It resolves in the page's publication. HTML and Markdown show the example title, original key, context, description when present, provenance, and value. A missing selector fails the build. API includes cannot be nested inside snippets. See [API references](https://www.shoalrun.com/publish/api-references.md) for source configuration and [example presentation](https://www.shoalrun.com/api-docs/generate.md) in reference pages.
+The element is standalone and empty, with literal string attributes. It resolves in the page's publication. HTML and Markdown show the example title, original key, context, description when present, provenance, and value. A missing selector fails the build. API includes can't be nested inside snippets. See [API references](https://www.shoalrun.com/publish/api-references.md) for source configuration and [example presentation](https://www.shoalrun.com/api-docs/generate.md) in reference pages.
 
 The fictional Notes API returns a saved note with its author, labels, and display metadata. The response includes a required but nullable `archivedAt` field: `null` means the note is active.
 
@@ -79,7 +79,7 @@ An active note with a nested author, two labels, and optional display metadata.
 
 ### Markdown twin
 
-During the build, Shoalrun selects the named example from the OpenAPI source for this page's publication and replaces `<ApiExample>` with ordinary content. An agent reading the generated `.md` page does not need to resolve the component or fetch the OpenAPI file. The example above renders as:
+During the build, Shoalrun selects the named example from the OpenAPI source for this page's publication and replaces `<ApiExample>` with ordinary content. An agent reading the generated `.md` page doesn't need to resolve the component or fetch the OpenAPI file. The example above renders as:
 
 ````md
 ### Created release note
@@ -135,7 +135,7 @@ These attributes select the source schema.
 | `status`    | For response bodies     | Response status, such as `201`.                                                                 |
 | `schema`    | With `api`              | Local OpenAPI `$ref` selector. With `operation`, omitted uses the selected media type's schema. |
 
-Use `operation`, `kind`, `mediaType`, and `status` for a body schema. To select an object that is not a body, use `api` and `schema` without the operation attributes. A pointer ending in `/properties/<name>` selects a single field. Both forms use the API source for the page's publication.
+Use `operation`, `kind`, `mediaType`, and `status` for a body schema. To select an object that isn't a body, use `api` and `schema` without the operation attributes. A pointer ending in `/properties/<name>` selects a single field. Both forms use the API source for the page's publication.
 
 ```mdx
 <ApiSchema api="notes" schema="#/components/schemas/NoteMetadata" />
@@ -164,7 +164,7 @@ string
 
 Where the note came from.
 
-The element is standalone and empty, with literal string attributes. A missing or invalid selector fails the build. API includes cannot be nested inside snippets. See [API references](https://www.shoalrun.com/publish/api-references.md) for source setup and focused contracts.
+The element is standalone and empty, with literal string attributes. A missing or invalid selector fails the build. API includes can't be nested inside snippets. See [API references](https://www.shoalrun.com/publish/api-references.md) for source setup and focused contracts.
 
 ### Response 201 schema · application/json
 
@@ -254,7 +254,7 @@ string
 Where the note came from.
 ```
 
-`<ApiSchema>` includes the full selected schema, including nested objects. It does not shorten or collapse large schemas in either output. For a large object, include it in a guide only when readers need the whole field tree there. Otherwise, select a relevant field, use authored [Fields](https://www.shoalrun.com/author/components/fields.md) for a short explanation, or link to the API reference. A field pointer selects its definition; it does not infer whether that field is required by its parent. Recursive references stop with a visible recursive-reference note rather than repeating forever.
+`<ApiSchema>` includes the full selected schema, including nested objects. It doesn't shorten or collapse large schemas in either output. For a large object, include it in a guide only when readers need the whole field tree there. Otherwise, select a relevant field, use authored [Fields](https://www.shoalrun.com/author/components/fields.md) for a short explanation, or link to the API reference. A field pointer selects its definition; it doesn't infer whether that field is required by its parent. Recursive references stop with a visible recursive-reference note rather than repeating forever.
 
 ## HTML, Markdown, and agents
 

package/agent-docs/author/components/api-embeds.sections/apiexample.md

@@ -20,7 +20,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > ApiExample and ApiSchema
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/api-embeds.md)
 
@@ -54,7 +54,7 @@ Use these attributes to configure the component.
 | `example`   | Yes           | Key in that media type's OpenAPI `examples` map. |
 | `status`    | For responses | Response status, such as `201`.                  |
 
-The element is standalone and empty, with literal string attributes. It resolves in the page's publication. HTML and Markdown show the example title, original key, context, description when present, provenance, and value. A missing selector fails the build. API includes cannot be nested inside snippets. See [API references](https://www.shoalrun.com/publish/api-references.md) for source configuration and [example presentation](https://www.shoalrun.com/api-docs/generate.md) in reference pages.
+The element is standalone and empty, with literal string attributes. It resolves in the page's publication. HTML and Markdown show the example title, original key, context, description when present, provenance, and value. A missing selector fails the build. API includes can't be nested inside snippets. See [API references](https://www.shoalrun.com/publish/api-references.md) for source configuration and [example presentation](https://www.shoalrun.com/api-docs/generate.md) in reference pages.
 
 The fictional Notes API returns a saved note with its author, labels, and display metadata. The response includes a required but nullable `archivedAt` field: `null` means the note is active.
 
@@ -87,7 +87,7 @@ An active note with a nested author, two labels, and optional display metadata.
 
 ### Markdown twin
 
-During the build, Shoalrun selects the named example from the OpenAPI source for this page's publication and replaces `<ApiExample>` with ordinary content. An agent reading the generated `.md` page does not need to resolve the component or fetch the OpenAPI file. The example above renders as:
+During the build, Shoalrun selects the named example from the OpenAPI source for this page's publication and replaces `<ApiExample>` with ordinary content. An agent reading the generated `.md` page doesn't need to resolve the component or fetch the OpenAPI file. The example above renders as:
 
 ````md
 ### Created release note

package/agent-docs/author/components/api-embeds.sections/html-markdown-and-agents.md

@@ -20,7 +20,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > ApiExample and ApiSchema
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/api-embeds.md)
 

package/agent-docs/author/components/api-embeds.sections/related-reading.md

@@ -20,7 +20,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > ApiExample and ApiSchema
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/api-embeds.md)
 

package/agent-docs/author/components/badge.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Badges
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 `<Badge>` adds a compact label inside prose, a heading, or a table cell. Write the state in its text; color and the optional icon only reinforce it.
 
@@ -44,7 +44,7 @@ The built-in variants follow the selected palette and color mode. A project can
 
 ## Add a custom color
 
-For example, this site registers a teal `partner` variant. It is a custom example, not one of the built-in variants. Give a custom variant `background` and `text` hex colors for light mode, and for dark mode if the site shows dark mode. `border` is optional and defaults to the text color. The build rejects unknown variant names and checks badge text against its background at 4.5:1 in each shown mode.
+For example, this site registers a teal `partner` variant. It's a custom example, not one of the built-in variants. Give a custom variant `background` and `text` hex colors for light mode, and for dark mode if the site shows dark mode. `border` is optional and defaults to the text color. The build rejects unknown variant names and checks badge text against its background at 4.5:1 in each shown mode.
 
 ```yaml title="docs.config.yaml"
 badges:

package/agent-docs/author/components/callout.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Callouts
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 `<Callout>` highlights a short message in the reading flow. Use a type that matches the message's purpose. The type sets the HTML color and decorative icon, while a visible label carries the meaning in both HTML and Markdown.
 
@@ -114,7 +114,7 @@ Use the registered name in MDX:
 
 Each custom tone needs `line` (left rule), `background`, and `text` (label and icon), all as hex colors. Multiple types can share a tone.
 
-A tone's `dark` block sets the same three colors for [dark mode](https://www.shoalrun.com/styling/color-modes.md). It is optional on a light-only site. When `theme.mode` is `dark` or `system`, every tone in use needs `dark`, or the build fails. The build checks each tone against the site's [palette](https://www.shoalrun.com/styling/palettes.md) in every mode the site shows. Body text, links, and the label need 4.5:1 against the tone's background.
+A tone's `dark` block sets the same three colors for [dark mode](https://www.shoalrun.com/styling/color-modes.md). It's optional on a light-only site. When `theme.mode` is `dark` or `system`, every tone in use needs `dark`, or the build fails. The build checks each tone against the site's [palette](https://www.shoalrun.com/styling/palettes.md) in every mode the site shows. Body text, links, and the label need 4.5:1 against the tone's background.
 
 You can also use `callouts.tones` to replace a built-in tone's colors. The five built-in types have default labels and Lucide icons; you can override their `label`, `tone`, or `icon` in `callouts.types`. A registered type without an icon displays its label without an icon. Icons are decorative and hidden from assistive technology; the label stays in HTML and Markdown. Invalid names, colors, icons, and definitions fail the build.
 

package/agent-docs/author/components/cards.md

@@ -16,13 +16,13 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Cards and collections
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 A card is a linked preview of another documentation page: it shows a title and short preview so readers can decide where to go next. Cards use the target page's title, the project's configured `outputs.text.card` field, and its current URL. The target is the page the reader will open when they select the card.
 
-Authors maintain those details in the target page's frontmatter, the YAML metadata at the top of the file. A card references the page's stable `id`, so renaming its file or changing its URL does not break the card. HTML displays a card layout; Markdown displays the same links, descriptions, subject lifecycle status, and relationship reasons as a readable list.
+Authors maintain those details in the target page's frontmatter, the YAML metadata at the top of the file. A card references the page's stable `id`, so renaming its file or changing its URL doesn't break the card. HTML displays a card layout; Markdown displays the same links, descriptions, subject lifecycle status, and relationship reasons as a readable list.
 
-Use these components as standalone, empty blocks in `.md` or `.mdx` pages or registered snippets. Literal attributes are accepted; arbitrary JavaScript expressions are not evaluated.
+Use these components as standalone, empty blocks in `.md` or `.mdx` pages or registered snippets. Literal attributes are accepted; arbitrary JavaScript expressions aren't evaluated.
 
 ## Link to one document
 
@@ -60,12 +60,12 @@ The array controls the order. Duplicate IDs fail validation. An empty array rend
 <DocCards relation="next-step" relatedTo="guide.cards" />
 ```
 
-| Attribute   | Required               | Meaning                                                         |
-| ----------- | ---------------------- | --------------------------------------------------------------- |
-| `docs`      | For a curated list     | Literal array of unique document IDs in display order.          |
-| `relation`  | For relationship cards | One declared relationship type; cannot be combined with `docs`. |
-| `relatedTo` | No                     | Source document for `relation`; defaults to this page.          |
-| `empty`     | No                     | Message for no results; default is “No matching documents.”     |
+| Attribute   | Required               | Meaning                                                        |
+| ----------- | ---------------------- | -------------------------------------------------------------- |
+| `docs`      | For a curated list     | Literal array of unique document IDs in display order.         |
+| `relation`  | For relationship cards | One declared relationship type; can't be combined with `docs`. |
+| `relatedTo` | No                     | Source document for `relation`; defaults to this page.         |
+| `empty`     | No                     | Message for no results; default is “No matching documents.”    |
 
 Use [RelatedReading](https://www.shoalrun.com/author/components/related-reading.md) when a plain link list grouped by purpose fits better than cards.
 
@@ -73,7 +73,7 @@ Use [RelatedReading](https://www.shoalrun.com/author/components/related-reading.
 
 By default, a card shows the target page's `title` and `summary`. These are the resolved values after global defaults, page frontmatter, and enforced values have been applied. Add an optional `card` object to the target page's frontmatter when its card needs different wording.
 
-An **eyebrow** is a short label above the card title, such as “Integration guide” or “Tutorial.” It helps readers recognize the kind of content before reading the title. It is optional display text; it does not set the document's type, add a tag, or affect collection filters. In this example, “Integration guide” appears above “Send your first payment”:
+An **eyebrow** is a short label above the card title, such as “Integration guide” or “Tutorial.” It helps readers recognize the kind of content before reading the title. It's optional display text; it doesn't set the document's type, add a tag, or affect collection filters. In this example, “Integration guide” appears above “Send your first payment”:
 
 ```yaml
 title: Create a payment
@@ -92,7 +92,7 @@ card:
 | `card.eyebrow`     | A small label above the title.                    | No label.                                                           |
 | `card.icon`        | A decorative Lucide symbol above the text.        | No icon, unless inherited from global frontmatter.                  |
 
-These overrides affect cards only. The page heading, SEO, and navigation keep their existing values. A card's destination always comes from the stable ID; `href` overrides are not supported. Values must be nonempty strings. Images, arbitrary badges, and other card fields are not implemented and fail with a diagnostic. Subject lifecycle status comes from the target document, including authoritative OpenAPI deprecation.
+These overrides affect cards only. The page heading, SEO, and navigation keep their existing values. A card's destination always comes from the stable ID; `href` overrides aren't supported. Values must be nonempty strings. Images, arbitrary badges, and other card fields aren't implemented and fail with a diagnostic. Subject lifecycle status comes from the target document, including authoritative OpenAPI deprecation.
 
 ## Add a Lucide icon
 
@@ -105,7 +105,7 @@ card:
 
 Names use hyphens, such as `book-open`, `credit-card`, `terminal`, or `sliders-horizontal`. The pinned Lucide package supplies the icons at build time. An unknown name or URL fails with a file-specific diagnostic, so typos never silently produce an empty icon. New icons from a later Lucide release need a dependency update first.
 
-The icon appears in every card for that page, including curated lists, collections, and relationship views. It does not change the page heading or sidebar. Omit `card.icon` for a text-only card. Global `frontmatter.defaults.card.icon` and `frontmatter.enforced.card.icon` use the same precedence rules as other card metadata; a page can override a default with another icon name.
+The icon appears in every card for that page, including curated lists, collections, and relationship views. It doesn't change the page heading or sidebar. Omit `card.icon` for a text-only card. Global `frontmatter.defaults.card.icon` and `frontmatter.enforced.card.icon` use the same precedence rules as other card metadata; a page can override a default with another icon name.
 
 Icons are inline SVGs with `aria-hidden="true"` and `focusable="false"`. The visible card title remains the link's accessible name. Icons are decorative, omitted from Markdown, and require no browser JavaScript, font download, or CDN. Only the selected SVG shapes appear in each page. Adjust their color and size with `.doc-card-icon` in `styles/site.css`.
 
@@ -113,9 +113,9 @@ Lucide is open source under the [ISC license](https://lucide.dev/license), with
 
 ## Build a collection
 
-A **collection** automatically finds pages that match your filters and displays them as cards. Use it when the list should follow the site's content, such as all authoring guides or pages associated with a payment operation. Unlike a curated list, you do not have to maintain an array of every matching page ID.
+A **collection** automatically finds pages that match your filters and displays them as cards. Use it when the list should follow the site's content, such as all authoring guides or pages associated with a payment operation. Unlike a curated list, you don't have to maintain an array of every matching page ID.
 
-`DocCollection` re-runs its filters during each build. Adding a matching page adds its card on the next build; removing the tag or making that page a draft removes it. A collection does not create pages, change their metadata, or add them to sidebar navigation.
+`DocCollection` re-runs its filters during each build. Adding a matching page adds its card on the next build; removing the tag or making that page a draft removes it. A collection doesn't create pages, change their metadata, or add them to sidebar navigation.
 
 This example displays up to six other guides tagged `authoring`, sorted by title:
 
@@ -130,7 +130,7 @@ No matching documents.
 | `type`      | Matches the document kind in frontmatter, such as `guide` or `api-reference`.                                                                                                   |
 | `tag`       | Matches a topic label in the target's `tags` array, such as `authoring`.                                                                                                        |
 | `operation` | Membership in its stable `operations` IDs; unknown operation IDs fail.                                                                                                          |
-| `audience`  | Membership in its `audiences` array; this filters metadata and does not grant access.                                                                                           |
+| `audience`  | Membership in its `audiences` array; this filters metadata and doesn't grant access.                                                                                            |
 | `orderBy`   | `title` by default, `id`, `date`, or `releaseVersion`. Date sorts newest first; version uses numeric label ordering. Every match needs the chosen field. Stable IDs break ties. |
 | `pin`       | Promotes selected matching pages to the front of the collection, in the given order. Supply a literal array of document IDs.                                                    |
 | `exclude`   | A literal array of IDs to remove. IDs absent from this publication are ignored.                                                                                                 |
@@ -145,7 +145,7 @@ For example, in the API fixture:
 <DocCollection operation="payments.create" pin={["reference.create-payment"]} />
 ```
 
-Pinned documents must be visible and satisfy all filters, including exclusions. Invalid pins stop the build. The `pin` and `exclude` arrays require unique document IDs. Collection ordering is deterministic and does not depend on filenames.
+Pinned documents must be visible and satisfy all filters, including exclusions. Invalid pins stop the build. The `pin` and `exclude` arrays require unique document IDs. Collection ordering is deterministic and doesn't depend on filenames.
 
 ## HTML, Markdown, and agents
 

package/agent-docs/author/components/cards.sections/add-a-lucide-icon.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Cards and collections
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/cards.md)
 
@@ -28,9 +28,9 @@ Parent page: [Full Markdown page](/author/components/cards.md)
 
 A card is a linked preview of another documentation page: it shows a title and short preview so readers can decide where to go next. Cards use the target page's title, the project's configured `outputs.text.card` field, and its current URL. The target is the page the reader will open when they select the card.
 
-Authors maintain those details in the target page's frontmatter, the YAML metadata at the top of the file. A card references the page's stable `id`, so renaming its file or changing its URL does not break the card. HTML displays a card layout; Markdown displays the same links, descriptions, subject lifecycle status, and relationship reasons as a readable list.
+Authors maintain those details in the target page's frontmatter, the YAML metadata at the top of the file. A card references the page's stable `id`, so renaming its file or changing its URL doesn't break the card. HTML displays a card layout; Markdown displays the same links, descriptions, subject lifecycle status, and relationship reasons as a readable list.
 
-Use these components as standalone, empty blocks in `.md` or `.mdx` pages or registered snippets. Literal attributes are accepted; arbitrary JavaScript expressions are not evaluated.
+Use these components as standalone, empty blocks in `.md` or `.mdx` pages or registered snippets. Literal attributes are accepted; arbitrary JavaScript expressions aren't evaluated.
 
 ## Add a Lucide icon
 
@@ -43,7 +43,7 @@ card:
 
 Names use hyphens, such as `book-open`, `credit-card`, `terminal`, or `sliders-horizontal`. The pinned Lucide package supplies the icons at build time. An unknown name or URL fails with a file-specific diagnostic, so typos never silently produce an empty icon. New icons from a later Lucide release need a dependency update first.
 
-The icon appears in every card for that page, including curated lists, collections, and relationship views. It does not change the page heading or sidebar. Omit `card.icon` for a text-only card. Global `frontmatter.defaults.card.icon` and `frontmatter.enforced.card.icon` use the same precedence rules as other card metadata; a page can override a default with another icon name.
+The icon appears in every card for that page, including curated lists, collections, and relationship views. It doesn't change the page heading or sidebar. Omit `card.icon` for a text-only card. Global `frontmatter.defaults.card.icon` and `frontmatter.enforced.card.icon` use the same precedence rules as other card metadata; a page can override a default with another icon name.
 
 Icons are inline SVGs with `aria-hidden="true"` and `focusable="false"`. The visible card title remains the link's accessible name. Icons are decorative, omitted from Markdown, and require no browser JavaScript, font download, or CDN. Only the selected SVG shapes appear in each page. Adjust their color and size with `.doc-card-icon` in `styles/site.css`.
 

package/agent-docs/author/components/cards.sections/build-a-collection.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Cards and collections
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/cards.md)
 
@@ -28,15 +28,15 @@ Parent page: [Full Markdown page](/author/components/cards.md)
 
 A card is a linked preview of another documentation page: it shows a title and short preview so readers can decide where to go next. Cards use the target page's title, the project's configured `outputs.text.card` field, and its current URL. The target is the page the reader will open when they select the card.
 
-Authors maintain those details in the target page's frontmatter, the YAML metadata at the top of the file. A card references the page's stable `id`, so renaming its file or changing its URL does not break the card. HTML displays a card layout; Markdown displays the same links, descriptions, subject lifecycle status, and relationship reasons as a readable list.
+Authors maintain those details in the target page's frontmatter, the YAML metadata at the top of the file. A card references the page's stable `id`, so renaming its file or changing its URL doesn't break the card. HTML displays a card layout; Markdown displays the same links, descriptions, subject lifecycle status, and relationship reasons as a readable list.
 
-Use these components as standalone, empty blocks in `.md` or `.mdx` pages or registered snippets. Literal attributes are accepted; arbitrary JavaScript expressions are not evaluated.
+Use these components as standalone, empty blocks in `.md` or `.mdx` pages or registered snippets. Literal attributes are accepted; arbitrary JavaScript expressions aren't evaluated.
 
 ## Build a collection
 
-A **collection** automatically finds pages that match your filters and displays them as cards. Use it when the list should follow the site's content, such as all authoring guides or pages associated with a payment operation. Unlike a curated list, you do not have to maintain an array of every matching page ID.
+A **collection** automatically finds pages that match your filters and displays them as cards. Use it when the list should follow the site's content, such as all authoring guides or pages associated with a payment operation. Unlike a curated list, you don't have to maintain an array of every matching page ID.
 
-`DocCollection` re-runs its filters during each build. Adding a matching page adds its card on the next build; removing the tag or making that page a draft removes it. A collection does not create pages, change their metadata, or add them to sidebar navigation.
+`DocCollection` re-runs its filters during each build. Adding a matching page adds its card on the next build; removing the tag or making that page a draft removes it. A collection doesn't create pages, change their metadata, or add them to sidebar navigation.
 
 This example displays up to six other guides tagged `authoring`, sorted by title:
 
@@ -51,7 +51,7 @@ No matching documents.
 | `type`      | Matches the document kind in frontmatter, such as `guide` or `api-reference`.                                                                                                   |
 | `tag`       | Matches a topic label in the target's `tags` array, such as `authoring`.                                                                                                        |
 | `operation` | Membership in its stable `operations` IDs; unknown operation IDs fail.                                                                                                          |
-| `audience`  | Membership in its `audiences` array; this filters metadata and does not grant access.                                                                                           |
+| `audience`  | Membership in its `audiences` array; this filters metadata and doesn't grant access.                                                                                            |
 | `orderBy`   | `title` by default, `id`, `date`, or `releaseVersion`. Date sorts newest first; version uses numeric label ordering. Every match needs the chosen field. Stable IDs break ties. |
 | `pin`       | Promotes selected matching pages to the front of the collection, in the given order. Supply a literal array of document IDs.                                                    |
 | `exclude`   | A literal array of IDs to remove. IDs absent from this publication are ignored.                                                                                                 |
@@ -66,4 +66,4 @@ For example, in the API fixture:
 <DocCollection operation="payments.create" pin={["reference.create-payment"]} />
 ```
 
-Pinned documents must be visible and satisfy all filters, including exclusions. Invalid pins stop the build. The `pin` and `exclude` arrays require unique document IDs. Collection ordering is deterministic and does not depend on filenames.
+Pinned documents must be visible and satisfy all filters, including exclusions. Invalid pins stop the build. The `pin` and `exclude` arrays require unique document IDs. Collection ordering is deterministic and doesn't depend on filenames.

package/agent-docs/author/components/cards.sections/curate-a-reading-list.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Cards and collections
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/cards.md)
 
@@ -28,9 +28,9 @@ Parent page: [Full Markdown page](/author/components/cards.md)
 
 A card is a linked preview of another documentation page: it shows a title and short preview so readers can decide where to go next. Cards use the target page's title, the project's configured `outputs.text.card` field, and its current URL. The target is the page the reader will open when they select the card.
 
-Authors maintain those details in the target page's frontmatter, the YAML metadata at the top of the file. A card references the page's stable `id`, so renaming its file or changing its URL does not break the card. HTML displays a card layout; Markdown displays the same links, descriptions, subject lifecycle status, and relationship reasons as a readable list.
+Authors maintain those details in the target page's frontmatter, the YAML metadata at the top of the file. A card references the page's stable `id`, so renaming its file or changing its URL doesn't break the card. HTML displays a card layout; Markdown displays the same links, descriptions, subject lifecycle status, and relationship reasons as a readable list.
 
-Use these components as standalone, empty blocks in `.md` or `.mdx` pages or registered snippets. Literal attributes are accepted; arbitrary JavaScript expressions are not evaluated.
+Use these components as standalone, empty blocks in `.md` or `.mdx` pages or registered snippets. Literal attributes are accepted; arbitrary JavaScript expressions aren't evaluated.
 
 ## Curate a reading list
 
@@ -56,11 +56,11 @@ The array controls the order. Duplicate IDs fail validation. An empty array rend
 <DocCards relation="next-step" relatedTo="guide.cards" />
 ```
 
-| Attribute   | Required               | Meaning                                                         |
-| ----------- | ---------------------- | --------------------------------------------------------------- |
-| `docs`      | For a curated list     | Literal array of unique document IDs in display order.          |
-| `relation`  | For relationship cards | One declared relationship type; cannot be combined with `docs`. |
-| `relatedTo` | No                     | Source document for `relation`; defaults to this page.          |
-| `empty`     | No                     | Message for no results; default is “No matching documents.”     |
+| Attribute   | Required               | Meaning                                                        |
+| ----------- | ---------------------- | -------------------------------------------------------------- |
+| `docs`      | For a curated list     | Literal array of unique document IDs in display order.         |
+| `relation`  | For relationship cards | One declared relationship type; can't be combined with `docs`. |
+| `relatedTo` | No                     | Source document for `relation`; defaults to this page.         |
+| `empty`     | No                     | Message for no results; default is “No matching documents.”    |
 
 Use [RelatedReading](https://www.shoalrun.com/author/components/related-reading.md) when a plain link list grouped by purpose fits better than cards.

package/agent-docs/author/components/cards.sections/html-markdown-and-agents.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Cards and collections
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/cards.md)
 
@@ -28,9 +28,9 @@ Parent page: [Full Markdown page](/author/components/cards.md)
 
 A card is a linked preview of another documentation page: it shows a title and short preview so readers can decide where to go next. Cards use the target page's title, the project's configured `outputs.text.card` field, and its current URL. The target is the page the reader will open when they select the card.
 
-Authors maintain those details in the target page's frontmatter, the YAML metadata at the top of the file. A card references the page's stable `id`, so renaming its file or changing its URL does not break the card. HTML displays a card layout; Markdown displays the same links, descriptions, subject lifecycle status, and relationship reasons as a readable list.
+Authors maintain those details in the target page's frontmatter, the YAML metadata at the top of the file. A card references the page's stable `id`, so renaming its file or changing its URL doesn't break the card. HTML displays a card layout; Markdown displays the same links, descriptions, subject lifecycle status, and relationship reasons as a readable list.
 
-Use these components as standalone, empty blocks in `.md` or `.mdx` pages or registered snippets. Literal attributes are accepted; arbitrary JavaScript expressions are not evaluated.
+Use these components as standalone, empty blocks in `.md` or `.mdx` pages or registered snippets. Literal attributes are accepted; arbitrary JavaScript expressions aren't evaluated.
 
 ## HTML, Markdown, and agents
 

package/agent-docs/author/components/cards.sections/link-to-one-document.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Cards and collections
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/cards.md)
 
@@ -28,9 +28,9 @@ Parent page: [Full Markdown page](/author/components/cards.md)
 
 A card is a linked preview of another documentation page: it shows a title and short preview so readers can decide where to go next. Cards use the target page's title, the project's configured `outputs.text.card` field, and its current URL. The target is the page the reader will open when they select the card.
 
-Authors maintain those details in the target page's frontmatter, the YAML metadata at the top of the file. A card references the page's stable `id`, so renaming its file or changing its URL does not break the card. HTML displays a card layout; Markdown displays the same links, descriptions, subject lifecycle status, and relationship reasons as a readable list.
+Authors maintain those details in the target page's frontmatter, the YAML metadata at the top of the file. A card references the page's stable `id`, so renaming its file or changing its URL doesn't break the card. HTML displays a card layout; Markdown displays the same links, descriptions, subject lifecycle status, and relationship reasons as a readable list.
 
-Use these components as standalone, empty blocks in `.md` or `.mdx` pages or registered snippets. Literal attributes are accepted; arbitrary JavaScript expressions are not evaluated.
+Use these components as standalone, empty blocks in `.md` or `.mdx` pages or registered snippets. Literal attributes are accepted; arbitrary JavaScript expressions aren't evaluated.
 
 ## Link to one document
 

package/agent-docs/author/components/cards.sections/override-card-text.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Cards and collections
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/cards.md)
 
@@ -28,15 +28,15 @@ Parent page: [Full Markdown page](/author/components/cards.md)
 
 A card is a linked preview of another documentation page: it shows a title and short preview so readers can decide where to go next. Cards use the target page's title, the project's configured `outputs.text.card` field, and its current URL. The target is the page the reader will open when they select the card.
 
-Authors maintain those details in the target page's frontmatter, the YAML metadata at the top of the file. A card references the page's stable `id`, so renaming its file or changing its URL does not break the card. HTML displays a card layout; Markdown displays the same links, descriptions, subject lifecycle status, and relationship reasons as a readable list.
+Authors maintain those details in the target page's frontmatter, the YAML metadata at the top of the file. A card references the page's stable `id`, so renaming its file or changing its URL doesn't break the card. HTML displays a card layout; Markdown displays the same links, descriptions, subject lifecycle status, and relationship reasons as a readable list.
 
-Use these components as standalone, empty blocks in `.md` or `.mdx` pages or registered snippets. Literal attributes are accepted; arbitrary JavaScript expressions are not evaluated.
+Use these components as standalone, empty blocks in `.md` or `.mdx` pages or registered snippets. Literal attributes are accepted; arbitrary JavaScript expressions aren't evaluated.
 
 ## Override card text
 
 By default, a card shows the target page's `title` and `summary`. These are the resolved values after global defaults, page frontmatter, and enforced values have been applied. Add an optional `card` object to the target page's frontmatter when its card needs different wording.
 
-An **eyebrow** is a short label above the card title, such as “Integration guide” or “Tutorial.” It helps readers recognize the kind of content before reading the title. It is optional display text; it does not set the document's type, add a tag, or affect collection filters. In this example, “Integration guide” appears above “Send your first payment”:
+An **eyebrow** is a short label above the card title, such as “Integration guide” or “Tutorial.” It helps readers recognize the kind of content before reading the title. It's optional display text; it doesn't set the document's type, add a tag, or affect collection filters. In this example, “Integration guide” appears above “Send your first payment”:
 
 ```yaml
 title: Create a payment
@@ -55,4 +55,4 @@ card:
 | `card.eyebrow`     | A small label above the title.                    | No label.                                                           |
 | `card.icon`        | A decorative Lucide symbol above the text.        | No icon, unless inherited from global frontmatter.                  |
 
-These overrides affect cards only. The page heading, SEO, and navigation keep their existing values. A card's destination always comes from the stable ID; `href` overrides are not supported. Values must be nonempty strings. Images, arbitrary badges, and other card fields are not implemented and fail with a diagnostic. Subject lifecycle status comes from the target document, including authoritative OpenAPI deprecation.
+These overrides affect cards only. The page heading, SEO, and navigation keep their existing values. A card's destination always comes from the stable ID; `href` overrides aren't supported. Values must be nonempty strings. Images, arbitrary badges, and other card fields aren't implemented and fail with a diagnostic. Subject lifecycle status comes from the target document, including authoritative OpenAPI deprecation.

package/agent-docs/author/components/cards.sections/related-reading.md

@@ -16,15 +16,15 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Cards and collections
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/cards.md)
 
 A card is a linked preview of another documentation page: it shows a title and short preview so readers can decide where to go next. Cards use the target page's title, the project's configured `outputs.text.card` field, and its current URL. The target is the page the reader will open when they select the card.
 
-Authors maintain those details in the target page's frontmatter, the YAML metadata at the top of the file. A card references the page's stable `id`, so renaming its file or changing its URL does not break the card. HTML displays a card layout; Markdown displays the same links, descriptions, subject lifecycle status, and relationship reasons as a readable list.
+Authors maintain those details in the target page's frontmatter, the YAML metadata at the top of the file. A card references the page's stable `id`, so renaming its file or changing its URL doesn't break the card. HTML displays a card layout; Markdown displays the same links, descriptions, subject lifecycle status, and relationship reasons as a readable list.
 
-Use these components as standalone, empty blocks in `.md` or `.mdx` pages or registered snippets. Literal attributes are accepted; arbitrary JavaScript expressions are not evaluated.
+Use these components as standalone, empty blocks in `.md` or `.mdx` pages or registered snippets. Literal attributes are accepted; arbitrary JavaScript expressions aren't evaluated.
 
 ## Related reading
 

package/agent-docs/author/components/code-blocks.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Code blocks
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Fenced code is ordinary Markdown rather than an MDX component. It belongs in the component reference because authors use it beside components to show commands, configuration, and payloads.
 
@@ -100,7 +100,7 @@ export function highlight(code, language) {
 }
 ```
 
-The adapter may import an installed library and initialize it with top-level await. Its `highlight` function must be synchronous. Tokens must reproduce the source code exactly, including whitespace, and colors must use `#rgb`, `#rgba`, `#rrggbb`, or `#rrggbbaa`. The framework validates tokens and escapes HTML; the adapter does not return raw HTML. Invalid tokens or changed text fail the build. The same adapter handles authored fences and API example panels. The entry module appears in the dependency manifest, while its own imports are not tracked individually.
+The adapter may import an installed library and initialize it with top-level await. Its `highlight` function must be synchronous. Tokens must reproduce the source code exactly, including whitespace, and colors must use `#rgb`, `#rgba`, `#rrggbb`, or `#rrggbbaa`. The framework validates tokens and escapes HTML; the adapter doesn't return raw HTML. Invalid tokens or changed text fail the build. The same adapter handles authored fences and API example panels. The entry module appears in the dependency manifest, while its own imports aren't tracked individually.
 
 ## HTML, Markdown, and agents