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

package/agent-docs/author/components/diagrams/d2-gallery.sections/related-reading.md

@@ -16,13 +16,13 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > D2 gallery
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/diagrams/d2-gallery.md)
 
 These 17 examples cover connected flows, containers, SQL tables, UML classes, sequences, grids, and 18 basic D2 shapes. Each uses Shoalrun’s [Diagram component](https://www.shoalrun.com/author/components/diagrams.md), with a width cap and copyable source. The diagrams illustrate notation rather than live services.
 
-D2 generates separate light and dark SVG images. They follow the site’s color mode, but do not inherit its live palette or fonts. Use [D2 themes](https://d2lang.com/tour/themes/) and [styles](https://d2lang.com/tour/style/) to customize the source. For Mermaid syntax rendered by Pele, see the [Pele gallery](https://www.shoalrun.com/author/components/diagrams/pele-gallery.md).
+D2 generates separate light and dark SVG images. They follow the site’s color mode, but don't inherit its live palette or fonts. Use [D2 themes](https://d2lang.com/tour/themes/) and [styles](https://d2lang.com/tour/style/) to customize the source. For Mermaid syntax rendered by Pele, see the [Pele gallery](https://www.shoalrun.com/author/components/diagrams/pele-gallery.md).
 
 The examples set `vars.d2-config.pad` to 16 pixels to keep the diagram padding compact. Width caps keep smaller examples from filling the page.
 

package/agent-docs/author/components/diagrams/d2-gallery.sections/sequences-and-grids.md

@@ -16,13 +16,13 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > D2 gallery
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/diagrams/d2-gallery.md)
 
 These 17 examples cover connected flows, containers, SQL tables, UML classes, sequences, grids, and 18 basic D2 shapes. Each uses Shoalrun’s [Diagram component](https://www.shoalrun.com/author/components/diagrams.md), with a width cap and copyable source. The diagrams illustrate notation rather than live services.
 
-D2 generates separate light and dark SVG images. They follow the site’s color mode, but do not inherit its live palette or fonts. Use [D2 themes](https://d2lang.com/tour/themes/) and [styles](https://d2lang.com/tour/style/) to customize the source. For Mermaid syntax rendered by Pele, see the [Pele gallery](https://www.shoalrun.com/author/components/diagrams/pele-gallery.md).
+D2 generates separate light and dark SVG images. They follow the site’s color mode, but don't inherit its live palette or fonts. Use [D2 themes](https://d2lang.com/tour/themes/) and [styles](https://d2lang.com/tour/style/) to customize the source. For Mermaid syntax rendered by Pele, see the [Pele gallery](https://www.shoalrun.com/author/components/diagrams/pele-gallery.md).
 
 The examples set `vars.d2-config.pad` to 16 pixels to keep the diagram padding compact. Width caps keep smaller examples from filling the page.
 

package/agent-docs/author/components/diagrams/d2-gallery.sections/styles-and-code.md

@@ -16,13 +16,13 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > D2 gallery
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/diagrams/d2-gallery.md)
 
 These 17 examples cover connected flows, containers, SQL tables, UML classes, sequences, grids, and 18 basic D2 shapes. Each uses Shoalrun’s [Diagram component](https://www.shoalrun.com/author/components/diagrams.md), with a width cap and copyable source. The diagrams illustrate notation rather than live services.
 
-D2 generates separate light and dark SVG images. They follow the site’s color mode, but do not inherit its live palette or fonts. Use [D2 themes](https://d2lang.com/tour/themes/) and [styles](https://d2lang.com/tour/style/) to customize the source. For Mermaid syntax rendered by Pele, see the [Pele gallery](https://www.shoalrun.com/author/components/diagrams/pele-gallery.md).
+D2 generates separate light and dark SVG images. They follow the site’s color mode, but don't inherit its live palette or fonts. Use [D2 themes](https://d2lang.com/tour/themes/) and [styles](https://d2lang.com/tour/style/) to customize the source. For Mermaid syntax rendered by Pele, see the [Pele gallery](https://www.shoalrun.com/author/components/diagrams/pele-gallery.md).
 
 The examples set `vars.d2-config.pad` to 16 pixels to keep the diagram padding compact. Width caps keep smaller examples from filling the page.
 

package/agent-docs/author/components/diagrams/pele-gallery.md

@@ -16,9 +16,9 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Pele gallery
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
-Browse examples of Pele's 33 built-in diagram families, including its version display, and 48 flowchart shapes. Every example uses Shoalrun's [Diagram component](https://www.shoalrun.com/author/components/diagrams.md) with Mermaid syntax. These illustrate notation; they do not describe live services or measured product results.
+Browse examples of Pele's 33 built-in diagram families, including its version display, and 48 flowchart shapes. Every example uses Shoalrun's [Diagram component](https://www.shoalrun.com/author/components/diagrams.md) with Mermaid syntax. These illustrate notation; they don't describe live services or measured product results.
 
 Open **Source** beneath a diagram to copy its syntax. See [Pele's examples](https://pele.run/examples) for more variations and [compatibility notes](https://pele.run/compatibility) for differences from Mermaid.
 
@@ -1304,7 +1304,7 @@ flowchart TB
 
 The diagrams are generated during the build and work without JavaScript. Theme changes update their CSS colors. Markdown retains every title, summary, SVG link, and original source, including examples inside closed disclosures.
 
-This gallery checks one example per diagram family and the listed flowchart shapes. It does not establish support for every syntax variation or external Mermaid plugin. Shoalrun disables diagram links, external images, and JavaScript callbacks. See [styling and compatibility](https://www.shoalrun.com/author/components/diagrams.md) before migrating existing diagrams.
+This gallery checks one example per diagram family and the listed flowchart shapes. It doesn't establish support for every syntax variation or external Mermaid plugin. Shoalrun disables diagram links, external images, and JavaScript callbacks. See [styling and compatibility](https://www.shoalrun.com/author/components/diagrams.md) before migrating existing diagrams.
 
 ## Related reading
 

package/agent-docs/author/components/diagrams/pele-gallery.sections/charts-and-planning.md

@@ -16,11 +16,11 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Pele gallery
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/diagrams/pele-gallery.md)
 
-Browse examples of Pele's 33 built-in diagram families, including its version display, and 48 flowchart shapes. Every example uses Shoalrun's [Diagram component](https://www.shoalrun.com/author/components/diagrams.md) with Mermaid syntax. These illustrate notation; they do not describe live services or measured product results.
+Browse examples of Pele's 33 built-in diagram families, including its version display, and 48 flowchart shapes. Every example uses Shoalrun's [Diagram component](https://www.shoalrun.com/author/components/diagrams.md) with Mermaid syntax. These illustrate notation; they don't describe live services or measured product results.
 
 Open **Source** beneath a diagram to copy its syntax. See [Pele's examples](https://pele.run/examples) for more variations and [compatibility notes](https://pele.run/compatibility) for differences from Mermaid.
 

package/agent-docs/author/components/diagrams/pele-gallery.sections/flowchart-shapes.md

@@ -16,11 +16,11 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Pele gallery
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/diagrams/pele-gallery.md)
 
-Browse examples of Pele's 33 built-in diagram families, including its version display, and 48 flowchart shapes. Every example uses Shoalrun's [Diagram component](https://www.shoalrun.com/author/components/diagrams.md) with Mermaid syntax. These illustrate notation; they do not describe live services or measured product results.
+Browse examples of Pele's 33 built-in diagram families, including its version display, and 48 flowchart shapes. Every example uses Shoalrun's [Diagram component](https://www.shoalrun.com/author/components/diagrams.md) with Mermaid syntax. These illustrate notation; they don't describe live services or measured product results.
 
 Open **Source** beneath a diagram to copy its syntax. See [Pele's examples](https://pele.run/examples) for more variations and [compatibility notes](https://pele.run/compatibility) for differences from Mermaid.
 

package/agent-docs/author/components/diagrams/pele-gallery.sections/flows-and-behavior.md

@@ -16,11 +16,11 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Pele gallery
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/diagrams/pele-gallery.md)
 
-Browse examples of Pele's 33 built-in diagram families, including its version display, and 48 flowchart shapes. Every example uses Shoalrun's [Diagram component](https://www.shoalrun.com/author/components/diagrams.md) with Mermaid syntax. These illustrate notation; they do not describe live services or measured product results.
+Browse examples of Pele's 33 built-in diagram families, including its version display, and 48 flowchart shapes. Every example uses Shoalrun's [Diagram component](https://www.shoalrun.com/author/components/diagrams.md) with Mermaid syntax. These illustrate notation; they don't describe live services or measured product results.
 
 Open **Source** beneath a diagram to copy its syntax. See [Pele's examples](https://pele.run/examples) for more variations and [compatibility notes](https://pele.run/compatibility) for differences from Mermaid.
 

package/agent-docs/author/components/diagrams/pele-gallery.sections/html-markdown-and-agents.md

@@ -16,11 +16,11 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Pele gallery
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/diagrams/pele-gallery.md)
 
-Browse examples of Pele's 33 built-in diagram families, including its version display, and 48 flowchart shapes. Every example uses Shoalrun's [Diagram component](https://www.shoalrun.com/author/components/diagrams.md) with Mermaid syntax. These illustrate notation; they do not describe live services or measured product results.
+Browse examples of Pele's 33 built-in diagram families, including its version display, and 48 flowchart shapes. Every example uses Shoalrun's [Diagram component](https://www.shoalrun.com/author/components/diagrams.md) with Mermaid syntax. These illustrate notation; they don't describe live services or measured product results.
 
 Open **Source** beneath a diagram to copy its syntax. See [Pele's examples](https://pele.run/examples) for more variations and [compatibility notes](https://pele.run/compatibility) for differences from Mermaid.
 
@@ -28,4 +28,4 @@ Open **Source** beneath a diagram to copy its syntax. See [Pele's examples](http
 
 The diagrams are generated during the build and work without JavaScript. Theme changes update their CSS colors. Markdown retains every title, summary, SVG link, and original source, including examples inside closed disclosures.
 
-This gallery checks one example per diagram family and the listed flowchart shapes. It does not establish support for every syntax variation or external Mermaid plugin. Shoalrun disables diagram links, external images, and JavaScript callbacks. See [styling and compatibility](https://www.shoalrun.com/author/components/diagrams.md) before migrating existing diagrams.
+This gallery checks one example per diagram family and the listed flowchart shapes. It doesn't establish support for every syntax variation or external Mermaid plugin. Shoalrun disables diagram links, external images, and JavaScript callbacks. See [styling and compatibility](https://www.shoalrun.com/author/components/diagrams.md) before migrating existing diagrams.

package/agent-docs/author/components/diagrams/pele-gallery.sections/related-reading.md

@@ -16,11 +16,11 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Pele gallery
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/diagrams/pele-gallery.md)
 
-Browse examples of Pele's 33 built-in diagram families, including its version display, and 48 flowchart shapes. Every example uses Shoalrun's [Diagram component](https://www.shoalrun.com/author/components/diagrams.md) with Mermaid syntax. These illustrate notation; they do not describe live services or measured product results.
+Browse examples of Pele's 33 built-in diagram families, including its version display, and 48 flowchart shapes. Every example uses Shoalrun's [Diagram component](https://www.shoalrun.com/author/components/diagrams.md) with Mermaid syntax. These illustrate notation; they don't describe live services or measured product results.
 
 Open **Source** beneath a diagram to copy its syntax. See [Pele's examples](https://pele.run/examples) for more variations and [compatibility notes](https://pele.run/compatibility) for differences from Mermaid.
 

package/agent-docs/author/components/diagrams/pele-gallery.sections/specialized-diagrams.md

@@ -16,11 +16,11 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Pele gallery
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/diagrams/pele-gallery.md)
 
-Browse examples of Pele's 33 built-in diagram families, including its version display, and 48 flowchart shapes. Every example uses Shoalrun's [Diagram component](https://www.shoalrun.com/author/components/diagrams.md) with Mermaid syntax. These illustrate notation; they do not describe live services or measured product results.
+Browse examples of Pele's 33 built-in diagram families, including its version display, and 48 flowchart shapes. Every example uses Shoalrun's [Diagram component](https://www.shoalrun.com/author/components/diagrams.md) with Mermaid syntax. These illustrate notation; they don't describe live services or measured product results.
 
 Open **Source** beneath a diagram to copy its syntax. See [Pele's examples](https://pele.run/examples) for more variations and [compatibility notes](https://pele.run/compatibility) for differences from Mermaid.
 

package/agent-docs/author/components/diagrams/pele-gallery.sections/systems-and-structures.md

@@ -16,11 +16,11 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Pele gallery
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/diagrams/pele-gallery.md)
 
-Browse examples of Pele's 33 built-in diagram families, including its version display, and 48 flowchart shapes. Every example uses Shoalrun's [Diagram component](https://www.shoalrun.com/author/components/diagrams.md) with Mermaid syntax. These illustrate notation; they do not describe live services or measured product results.
+Browse examples of Pele's 33 built-in diagram families, including its version display, and 48 flowchart shapes. Every example uses Shoalrun's [Diagram component](https://www.shoalrun.com/author/components/diagrams.md) with Mermaid syntax. These illustrate notation; they don't describe live services or measured product results.
 
 Open **Source** beneath a diagram to copy its syntax. See [Pele's examples](https://pele.run/examples) for more variations and [compatibility notes](https://pele.run/compatibility) for differences from Mermaid.
 

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

@@ -17,13 +17,13 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Overview
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
-Use `<Diagram>` for flowcharts, sequence diagrams, charts, and other graphs written as text. D2 is the default engine, with TALA as its default layout. Set `engine="mermaid"` for Mermaid syntax, rendered by [Pele](https://pele.run). Diagrams render to SVG during the build, so readers do not need a diagram script in their browser. Set a literal pixel `width`, such as `width="440"`, to cap the diagram's displayed width while allowing it to shrink on narrow screens.
+Use `<Diagram>` for flowcharts, sequence diagrams, charts, and other graphs written as text. D2 is the default engine, with TALA as its default layout. Set `engine="mermaid"` for Mermaid syntax, rendered by [Pele](https://pele.run). Diagrams render to SVG during the build, so readers don't need a diagram script in their browser. Set a literal pixel `width`, such as `width="440"`, to cap the diagram's displayed width while allowing it to shrink on narrow screens.
 
 For the diagram languages themselves, use the official [D2 tour](https://d2lang.com/tour/intro/) and [Mermaid syntax reference](https://mermaid.js.org/intro/syntax-reference.html). Shoalrun's component controls how their source is published; those references cover each language's shapes, connections, and diagram types.
 
-Every diagram needs a short `title` and `summary`. The summary states the point of the diagram; it does not need to repeat every connection. For a complex diagram, add a fuller explanation in nearby prose so readers can understand its meaning without the graphic.
+Every diagram needs a short `title` and `summary`. The summary states the point of the diagram; it doesn't need to repeat every connection. For a complex diagram, add a fuller explanation in nearby prose so readers can understand its meaning without the graphic.
 
 ## Syntax
 
@@ -113,7 +113,7 @@ Use these attributes to configure the component.
 
 Keep the source in one fenced code block inside the component. When quoting a complete example in Markdown, use four backticks around the outer `mdx` block so its inner three-backtick fence stays intact.
 
-See the [diagram gallery](https://www.shoalrun.com/author/components/diagrams/pele-gallery.md) for examples of every built-in Pele diagram family and 48 flowchart shapes. Use [Mermaid’s syntax reference](https://mermaid.js.org/intro/syntax-reference.html) to write the source and [Pele’s compatibility guide](https://pele.run/compatibility) to check rendering differences. External Mermaid plugins are not supported.
+See the [diagram gallery](https://www.shoalrun.com/author/components/diagrams/pele-gallery.md) for examples of every built-in Pele diagram family and 48 flowchart shapes. Use [Mermaid’s syntax reference](https://mermaid.js.org/intro/syntax-reference.html) to write the source and [Pele’s compatibility guide](https://pele.run/compatibility) to check rendering differences. External Mermaid plugins aren't supported.
 
 ## Styling and readability
 
@@ -130,19 +130,19 @@ Override Pele’s variables in [project CSS](https://www.shoalrun.com/author/css
 }
 ```
 
-See [Pele’s styling guide](https://pele.run/theming) for all variables, series colors, and element classes. Its [examples](https://pele.run/examples) show more diagram variations. Fixed source-level colors do not follow the palette; check their contrast in both modes. Custom fonts can change label widths, so inspect long labels after overriding fonts.
+See [Pele’s styling guide](https://pele.run/theming) for all variables, series colors, and element classes. Its [examples](https://pele.run/examples) show more diagram variations. Fixed source-level colors don't follow the palette; check their contrast in both modes. Custom fonts can change label widths, so inspect long labels after overriding fonts.
 
 Without `width`, a diagram fills the available content width. Set `width="520"` to cap one diagram at 520 pixels; it still shrinks on narrower screens. Use `.doc-diagram` and `.doc-diagram figcaption` to style the frame and caption.
 
-D2 still renders separate light and dark SVG images using themes 0 and 200. Project CSS can style their frames and dimensions, but cannot reach individual nodes inside those image files.
+D2 still renders separate light and dark SVG images using themes 0 and 200. Project CSS can style their frames and dimensions, but can't reach individual nodes inside those image files.
 
 ## HTML, Markdown, and agents
 
 Pele generates inline SVG during the build. It needs no browser or client-side renderer, and the diagram works without JavaScript. Each SVG has an accessible name from `title` and a visible caption with the `summary`. Published light/dark SVG files remain available for direct links and Markdown readers.
 
-The `.md` page retains the title, summary, SVG link, and original fenced D2 or Mermaid source. Readers and agents can inspect the structure without running a diagram library. Changing the renderer does not remove the source or explanation.
+The `.md` page retains the title, summary, SVG link, and original fenced D2 or Mermaid source. Readers and agents can inspect the structure without running a diagram library. Changing the renderer doesn't remove the source or explanation.
 
-Shoalrun disables diagram links, external images, and JavaScript callbacks. It rejects active SVG content before publication. Arbitrary HTML labels and Mermaid’s named themes are not supported by this renderer. Keep essential instructions in the summary or surrounding text.
+Shoalrun disables diagram links, external images, and JavaScript callbacks. It rejects active SVG content before publication. Arbitrary HTML labels and Mermaid’s named themes aren't supported by this renderer. Keep essential instructions in the summary or surrounding text.
 
 Keep a diagram in one fenced code block inside `<Diagram>`. The fence language must match the engine: `d2` or `mermaid`. Unknown engines, invalid layouts, missing titles or summaries, and render failures stop the build with the source file and diagram title.
 

package/agent-docs/author/components/doc-link.md

@@ -16,9 +16,9 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > DocLink
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
-`<DocLink>` resolves a document ID to its URL in the current publication. It is useful in MDX when the link should use a stable target and optionally inherit the target page's title.
+`<DocLink>` resolves a document ID to its URL in the current publication. It's useful in MDX when the link should use a stable target and optionally inherit the target page's title.
 
 ## Which link should I use?
 
@@ -31,7 +31,7 @@ Choose a link form based on whether the destination is a document, a section, or
 | `[Open the specification](https://example.test/spec)`       | External sites, downloads, or other URLs without a Shoalrun document ID.       | Keeps the authored URL.                                     |
 | `[Jump to fields](#fields)`                                 | A section on the current page.                                                 | Keeps the fragment link.                                    |
 
-Prefer `doc:` Markdown for ordinary prose. Both ID-based forms survive a target slug change and fail the build if the target is unavailable in this publication. A normal Markdown link to a Shoalrun route can work, but the authored URL must be updated if that route changes. Raw HTML or JSX anchors such as `<a href="...">` do not have a semantic adapter in this prototype and fail the build; use Markdown links instead.
+Prefer `doc:` Markdown for ordinary prose. Both ID-based forms survive a target slug change and fail the build if the target is unavailable in this publication. A normal Markdown link to a Shoalrun route can work, but the authored URL must be updated if that route changes. Raw HTML or JSX anchors such as `<a href="...">` don't have a semantic adapter in this prototype and fail the build; use Markdown links instead.
 
 ## Syntax
 

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

@@ -16,9 +16,9 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Fields
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
-Use `<Fields>` and `<Field>` to describe fields that are not selected from an OpenAPI schema, or to explain a small task-specific subset in your own words. The list uses the same field styling as generated schemas. If the exact contract already exists in OpenAPI, [ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) can include the source schema or one of its fields.
+Use `<Fields>` and `<Field>` to describe fields that aren't selected from an OpenAPI schema, or to explain a small task-specific subset in your own words. The list uses the same field styling as generated schemas. If the exact contract already exists in OpenAPI, [ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) can include the source schema or one of its fields.
 
 ## Syntax
 
@@ -73,22 +73,22 @@ Use a shorter layout.
 
 ### Attribute reference
 
-All values are literal MDX attributes. Text and numbers use quoted strings; flags are bare attributes. These declarations describe fields in the published page. They do not validate user input at runtime.
-
-| `Field` attribute        | Required | Meaning                                                                             |
-| ------------------------ | -------- | ----------------------------------------------------------------------------------- |
-| `name`                   | Yes      | Nonempty field name.                                                                |
-| `type`                   | Yes      | Nonempty type label, such as `string`, `integer`, or `array of objects`.            |
-| `required`, `optional`   | No       | Bare presence flags. Omission means optional; the two flags cannot appear together. |
-| `nullable`               | No       | Bare flag allowing a `null` value. It does not change whether the field is present. |
-| `min`, `max`             | No       | Finite numeric value bounds; `minimum` and `maximum` are equivalent spellings.      |
-| `minLength`, `maxLength` | No       | Nonnegative integer string-length bounds.                                           |
-| `minItems`, `maxItems`   | No       | Nonnegative integer array-size bounds.                                              |
-| `format`, `pattern`      | No       | Nonempty text for a format name or pattern.                                         |
-| `example`, `default`     | No       | Literal text shown as an example or default value.                                  |
-| `deprecated`             | No       | Bare flag marking the field as deprecated.                                          |
-
-Bounds must be numeric, and each minimum must be no greater than its maximum. `min` cannot be combined with `minimum`, nor `max` with `maximum`. Keep the declared type, constraints, and examples consistent with the actual contract.
+All values are literal MDX attributes. Text and numbers use quoted strings; flags are bare attributes. These declarations describe fields in the published page. They don't validate user input at runtime.
+
+| `Field` attribute        | Required | Meaning                                                                            |
+| ------------------------ | -------- | ---------------------------------------------------------------------------------- |
+| `name`                   | Yes      | Nonempty field name.                                                               |
+| `type`                   | Yes      | Nonempty type label, such as `string`, `integer`, or `array of objects`.           |
+| `required`, `optional`   | No       | Bare presence flags. Omission means optional; the two flags can't appear together. |
+| `nullable`               | No       | Bare flag allowing a `null` value. It doesn't change whether the field is present. |
+| `min`, `max`             | No       | Finite numeric value bounds; `minimum` and `maximum` are equivalent spellings.     |
+| `minLength`, `maxLength` | No       | Nonnegative integer string-length bounds.                                          |
+| `minItems`, `maxItems`   | No       | Nonnegative integer array-size bounds.                                             |
+| `format`, `pattern`      | No       | Nonempty text for a format name or pattern.                                        |
+| `example`, `default`     | No       | Literal text shown as an example or default value.                                 |
+| `deprecated`             | No       | Bare flag marking the field as deprecated.                                         |
+
+Bounds must be numeric, and each minimum must be no greater than its maximum. `min` can't be combined with `minimum`, nor `max` with `maximum`. Keep the declared type, constraints, and examples consistent with the actual contract.
 
 ```mdx
 <Fields>

package/agent-docs/author/components/file-tree.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 > File trees
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 `<FileTree>` shows a file layout or other hierarchy. `<Tree>` is an alias. Add `<Folder>` branches and `<File>` leaves; folders may contain more folders or files.
 
@@ -56,7 +56,7 @@ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > File tr
 
 ## Attributes
 
-Every node needs a nonempty `name`. Folders and files get icons automatically, and a folder’s icon changes when it opens. Optional `doc` or `href` makes its label a link; use only one. Optional `icon` accepts a lowercase Lucide name to override the default. `<File>` cannot have children.
+Every node needs a nonempty `name`. Folders and files get icons automatically, and a folder’s icon changes when it opens. Optional `doc` or `href` makes its label a link; use only one. Optional `icon` accepts a lowercase Lucide name to override the default. `<File>` can't have children.
 
 ## Expand and collapse folders
 

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Images
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Use `<Image>` to show an image with optional sizing, a caption, or click-to-expand viewing. Plain Markdown image syntax also works when you only need an image and alt text.
 
@@ -39,7 +39,7 @@ Images fit the content column and shrink on narrow screens. They keep their aspe
 
 ## Set a width
 
-`width` sets a maximum in pixels. It does not force an image to overflow a smaller screen. Leave it out to use the available content width.
+`width` sets a maximum in pixels. It doesn't force an image to overflow a smaller screen. Leave it out to use the available content width.
 
 ```mdx
 <Image src="./assets/image-example.svg" alt="A documentation page layout" width="480" />
@@ -75,7 +75,7 @@ A documentation page has three reading areas.
 
 [View original image](https://www.shoalrun.com/assets/pages/author/components/images/image-example.svg)
 
-The expanded view supports Escape to close and returns focus to the image link. Without JavaScript or modal-dialog support, the link opens the original asset. A larger view cannot add detail that is missing from a low-resolution source.
+The expanded view supports Escape to close and returns focus to the image link. Without JavaScript or modal-dialog support, the link opens the original asset. A larger view can't add detail that's missing from a low-resolution source.
 
 ## Attributes
 
@@ -90,13 +90,13 @@ All attributes use literal values. `expand` is a bare boolean attribute.
 | `caption` | No       | Plain text shown below the image and retained in Markdown.                          |
 | `expand`  | No       | Opens a modal image viewer when supported, with an original-image link as fallback. |
 
-`<Image>` is an empty block component. It does not accept children, HTML strings, or dynamic expressions. Keep essential explanations in nearby prose and meaningful alt text. For generated diagrams, use [Diagram](https://www.shoalrun.com/author/components/diagrams.md).
+`<Image>` is an empty block component. It doesn't accept children, HTML strings, or dynamic expressions. Keep essential explanations in nearby prose and meaningful alt text. For generated diagrams, use [Diagram](https://www.shoalrun.com/author/components/diagrams.md).
 
 ## HTML, Markdown, and agents
 
 HTML contains a normal image with alt text. Captions use `figure` and `figcaption`. Expandable images use a link enhanced by a modal viewer; the image remains usable without scripts. Modified clicks still open the link normally.
 
-Markdown includes the image and alt text, followed by its caption when present. Expandable images also include a link to the original asset. Width, alignment, and modal state do not hide content from agents.
+Markdown includes the image and alt text, followed by its caption when present. Expandable images also include a link to the original asset. Width, alignment, and modal state don't hide content from agents.
 
 ## Related reading
 

package/agent-docs/author/components/info-hint.md

@@ -16,9 +16,9 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Short definitions
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
-Use `<InfoHint>` for a short definition that readers can open when they need it. It is a click-to-expand disclosure. Use a [tooltip](https://www.shoalrun.com/author/components/tooltips.md) for brief text that appears on hover or keyboard focus. Put longer explanations in a [callout](https://www.shoalrun.com/author/components/callout.md) or a linked page.
+Use `<InfoHint>` for a short definition that readers can open when they need it. It's a click-to-expand disclosure. Use a [tooltip](https://www.shoalrun.com/author/components/tooltips.md) for brief text that appears on hover or keyboard focus. Put longer explanations in a [callout](https://www.shoalrun.com/author/components/callout.md) or a linked page.
 
 ## Syntax
 
@@ -40,7 +40,7 @@ Use these attributes to configure the component.
 | --------- | -------- | ---------------------------------------------- |
 | `label`   | Yes      | Nonempty text shown on the disclosure control. |
 
-`<InfoHint>` must be a block element with one plain-text definition. It does not accept links, multiple paragraphs, or other components inside the definition.
+`<InfoHint>` must be a block element with one plain-text definition. It doesn't accept links, multiple paragraphs, or other components inside the definition.
 
 `<Tooltip>` previously named this same disclosure. Use `<InfoHint>` to keep click-to-expand behavior; `<Tooltip>` now provides hover and focus behavior.
 

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

@@ -16,9 +16,9 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Keyboard shortcuts
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
-Use `<Kbd>` to name a key or shortcut in a sentence. Include the action in the sentence; key styling alone does not explain what the shortcut does.
+Use `<Kbd>` to name a key or shortcut in a sentence. Include the action in the sentence; key styling alone doesn't explain what the shortcut does.
 
 ## Syntax
 

package/agent-docs/author/components/math.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 > Math
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Use `<Math>` with a literal LaTeX expression. It supports the KaTeX math subset and reports invalid expressions during the build.
 
@@ -36,7 +36,7 @@ c^2=a^2+b^2
 
 ## Attributes
 
-`expression` is required and nonempty. Add the bare `display` attribute on a block element for centered display math. The component does not parse dollar delimiters in ordinary prose or code fences. Escape quotes in MDX attributes as needed.
+`expression` is required and nonempty. Add the bare `display` attribute on a block element for centered display math. The component doesn't parse dollar delimiters in ordinary prose or code fences. Escape quotes in MDX attributes as needed.
 
 ## HTML, Markdown, and agents
 

package/agent-docs/author/components/only.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 > Content for one format
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Use `<Only>` to author content for one output format. Shared material stays outside the blocks; a block can contain an instruction, explanation, example, or link that serves only one version:
 
@@ -50,13 +50,13 @@ The build validates the contents of both blocks, including their links and suppo
 
 ## HTML, Markdown, and agents
 
-An agent that fetches the direct `.md` URL, or requests this page with `Accept: text/markdown` on a host that supports [content negotiation](https://www.shoalrun.com/publish/content-negotiation.md), receives the shared text and `format="markdown"` blocks. It does not receive `format="html"` blocks. For the live example above, the relevant Markdown line is:
+An agent that fetches the direct `.md` URL, or requests this page with `Accept: text/markdown` on a host that supports [content negotiation](https://www.shoalrun.com/publish/content-negotiation.md), receives the shared text and `format="markdown"` blocks. It doesn't receive `format="html"` blocks. For the live example above, the relevant Markdown line is:
 
 ```md
 This sentence appears only in the Markdown twin.
 ```
 
-Keep facts, warnings, and task steps that both readers need outside `<Only>`, or provide suitable versions in both formats. You can add or suppress content in either output when that helps its intended reader. Check that each version remains accurate and usable for its task; see [Shoalrun's position on shared and format-specific content](https://www.shoalrun.com/publish/agent-friendliness.md). The browser search index uses the HTML output, so Markdown-only text is not included in that search. See [publishing and agent representations](https://www.shoalrun.com/publish/output.md) for the full output contract.
+Keep facts, warnings, and task steps that both readers need outside `<Only>`, or provide suitable versions in both formats. You can add or suppress content in either output when that helps its intended reader. Check that each version remains accurate and usable for its task; see [Shoalrun's position on shared and format-specific content](https://www.shoalrun.com/publish/agent-friendliness.md). The browser search index uses the HTML output, so Markdown-only text isn't included in that search. See [publishing and agent representations](https://www.shoalrun.com/publish/output.md) for the full output contract.
 
 ## Related reading
 

package/agent-docs/author/components/progress.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 > Progress
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Use `<Progress>` for a published count in a tutorial or migration guide. It shows the amount completed as text and as a bar. Update the source and rebuild the site when the shared state changes.
 
@@ -42,13 +42,13 @@ Use these attributes to configure the component.
 
 ## When to use it
 
-Use this component when a count has a known maximum, such as 3 of 5 migration tasks complete. It is a read-only display: readers cannot mark a task complete or move the bar. For a process with named stages and descriptions, use a [timeline](https://www.shoalrun.com/author/components/timeline.md).
+Use this component when a count has a known maximum, such as 3 of 5 migration tasks complete. It's a read-only display: readers can't mark a task complete or move the bar. For a process with named stages and descriptions, use a [timeline](https://www.shoalrun.com/author/components/timeline.md).
 
 ## HTML, Markdown, and agents
 
 HTML shows “Migration tasks: 3 of 5 complete” alongside a native `<progress>` element. The text carries the count even without CSS or color. There is no JavaScript behavior or keyboard control.
 
-Markdown states the same label and count in a sentence. An agent does not need to estimate completion from the bar.
+Markdown states the same label and count in a sentence. An agent doesn't need to estimate completion from the bar.
 
 ## Related reading
 

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Steps
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Use `<Steps>` when each part of a procedure needs a title and supporting content. For a simple sequence with no step titles, an ordinary Markdown numbered list is enough. For code that changes between steps, use a [Walkthrough](https://www.shoalrun.com/author/components/walkthroughs.md).
 
@@ -97,7 +97,7 @@ The same `<Step>` tag is also used in [Walkthrough](https://www.shoalrun.com/aut
 | `<Steps>`       | `title`, optional `icon`                                  | Numbered procedure with configurable heading level and TOC behavior. |
 | `<Walkthrough>` | `title`, optional code source and highlighting attributes | Code walkthrough with synchronized explanations.                     |
 
-Use the attributes documented for the parent you are writing. The two forms do not share rendering or settings.
+Use the attributes documented for the parent you're writing. The two forms don't share rendering or settings.
 
 ## Step headings and the page outline
 

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Tables
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Ordinary Markdown tables work without a component. For a long table, wrap one table in `<Table>` to add a filter box, sticky column headings, or both in HTML:
 
@@ -65,4 +65,4 @@ Filter this table by a name, environment, or status. Several words must all occu
 
 The filter needs JavaScript. Without it, the filter field stays hidden and all rows remain visible. Sticky headings use CSS and still work without JavaScript. On narrow screens the table scrolls horizontally. Keyboard users can focus the scrollable table region.
 
-The Markdown twin contains all 16 rows as a regular table. Agents and text-only readers do not need the filter to find a row. Use an ordinary Markdown table when these HTML controls are unnecessary.
+The Markdown twin contains all 16 rows as a regular table. Agents and text-only readers don't need the filter to find a row. Use an ordinary Markdown table when these HTML controls are unnecessary.

package/agent-docs/author/components/tabs.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 > Tabs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 `<Tabs>` presents alternate views, such as two output formats. Use it only when the choices are truly alternatives; a normal heading sequence is easier to read when readers need every section.
 
@@ -57,7 +57,7 @@ Use these attributes to configure the component.
 | `Tab`   | `value`       | Optional matching key; defaults to the tab label. Values must be unique within a group.                                     |
 | `Tab`   | `label`       | Required nonempty literal name for its control and Markdown heading.                                                        |
 
-Use at least two nonempty, direct `Tab` children. A `Tab` cannot stand alone. Other direct children and attributes fail the build.
+Use at least two nonempty, direct `Tab` children. A `Tab` can't stand alone. Other direct children and attributes fail the build.
 
 ## Keep the height steady
 
@@ -102,13 +102,13 @@ Import the JavaScript client in your application.
 
 Import the Python client in your application.
 
-`sync` names use up to 64 letters, numbers, dashes, or underscores, starting with a letter or number. Synchronization follows reader choices within this page; it does not store a cross-page preference or move focus to another group. Markdown still includes every tab.
+`sync` names use up to 64 letters, numbers, dashes, or underscores, starting with a letter or number. Synchronization follows reader choices within this page; it doesn't store a cross-page preference or move focus to another group. Markdown still includes every tab.
 
 ## HTML, Markdown, and agents
 
 HTML contains every panel before scripts run. Without JavaScript, all panels remain visible. With JavaScript, Left and Right arrows switch tabs, while Home and End choose the first and last.
 
-The build replaces the tab controls with ordinary Markdown sections. Each `Tab` label becomes a level-three heading, followed by that tab's complete body, in source order. The outer `Tabs` label is for the HTML control and does not appear in Markdown. The first example on this page renders like this in the Markdown twin:
+The build replaces the tab controls with ordinary Markdown sections. Each `Tab` label becomes a level-three heading, followed by that tab's complete body, in source order. The outer `Tabs` label is for the HTML control and doesn't appear in Markdown. The first example on this page renders like this in the Markdown twin:
 
 ```md
 ### HTML
@@ -122,7 +122,7 @@ The page keeps the content as text.
 
 An agent reading the `.md` page gets every alternative without choosing a tab. Markdown inside each body stays Markdown; supported MDX components expand to their own Markdown forms during the build.
 
-Each `Tab` body accepts ordinary Markdown, including lists, links, and fenced code, plus supported MDX components such as `Callout`, `DocLink`, and `Collapsible`. Put other content inside a `Tab` body. Dynamic MDX expressions and unknown components are not supported.
+Each `Tab` body accepts ordinary Markdown, including lists, links, and fenced code, plus supported MDX components such as `Callout`, `DocLink`, and `Collapsible`. Put other content inside a `Tab` body. Dynamic MDX expressions and unknown components aren't supported.
 
 ## Related reading
 

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

@@ -16,11 +16,11 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Timelines
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Use `<Timeline>` to show progress through an ordered set of milestones. Set `current` to the `id` of the milestone in progress. Earlier milestones become complete; later milestones become upcoming.
 
-This is a **read-only progress display**. Readers can see the current stage, but they cannot mark milestones complete or move the bar. Update `current` in the source and rebuild the site when the shared process advances. Links inside milestone content work normally.
+This is a **read-only progress display**. Readers can see the current stage, but they can't mark milestones complete or move the bar. Update `current` in the source and rebuild the site when the shared process advances. Links inside milestone content work normally.
 
 ## When to use it