@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.11

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

@@ -0,0 +1,58 @@
+---
+id: guide.cards
+title: Cards and collections
+summary: Link to documents by stable ID and build filtered card collections.
+type: reference
+area: components
+subarea: components-navigation
+canonical: /author/components/cards
+---
+
+# Cards and collections
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Cards and collections
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/components/cards.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Publishing and agent representations](https://www.shoalrun.com/publish/output.md) — Inspect the HTML, Markdown, and manifests produced by the build.
+
+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.
+
+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.
+
+## 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”:
+
+```yaml
+title: Create a payment
+summary: Submit a payment and understand the result.
+card:
+  icon: credit-card
+  title: Send your first payment
+  description: Prepare the request and inspect the response.
+  eyebrow: Integration guide
+```
+
+| Field              | What it displays                                  | When omitted                                                        |
+| ------------------ | ------------------------------------------------- | ------------------------------------------------------------------- |
+| `card.title`       | The linked heading inside the card.               | Uses the document `title`.                                          |
+| `card.description` | A short explanation of what the reader will find. | Uses `outputs.text.card`, which defaults to the document `summary`. |
+| `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.

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

@@ -0,0 +1,43 @@
+---
+id: guide.cards
+title: Cards and collections
+summary: Link to documents by stable ID and build filtered card collections.
+type: reference
+area: components
+subarea: components-navigation
+canonical: /author/components/cards
+---
+
+# Cards and collections
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Cards and collections
+
+**Updated: 2026-10-26.**
+
+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.
+
+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.
+
+## Related reading
+
+### Next steps
+
+- [Publishing and agent representations](https://www.shoalrun.com/publish/output.md) — Inspect the HTML, Markdown, and manifests produced by the build.
+
+### Related topics
+
+- [Page metadata](https://www.shoalrun.com/author/frontmatter.md) — Configure shared metadata and optional card text overrides.
+
+- [DocLink](https://www.shoalrun.com/author/components/doc-link.md) — Link to a page inline, or show it as a card with its summary.
+
+### Often confused with
+
+- [Related reading](https://www.shoalrun.com/author/related-reading.md) — Related reading follows authored relationships with reasons; cards and collections show pages you pick by ID or filter by metadata.

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

@@ -0,0 +1,117 @@
+---
+id: guide.component.code-blocks
+title: Code blocks
+summary: Write fenced examples and configure Shiki or another highlighter.
+type: reference
+area: components
+subarea: components-code
+canonical: /author/components/code-blocks
+---
+
+# Code blocks
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Code blocks
+
+**Updated: 2026-10-26.**
+
+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.
+
+## Syntax
+
+````md
+```yaml title="Frontmatter fields" filename="config/frontmatter.yaml"
+fields:
+  agent.intent:
+    type: string
+```
+````
+
+```yaml title="Frontmatter fields" filename="config/frontmatter.yaml"
+fields:
+  agent.intent:
+    type: string
+```
+
+| Fence option                         | Required | Meaning                                                                    |
+| ------------------------------------ | -------- | -------------------------------------------------------------------------- |
+| Language, such as `yaml`             | No       | Chooses a build-time highlighting grammar; unknown languages remain plain. |
+| `title="Frontmatter fields"`         | No       | Shows a descriptive heading above the HTML block.                          |
+| `filename="config/frontmatter.yaml"` | No       | Shows a file path beside the title.                                        |
+
+Use `title`, `filename`, both, or neither. Existing fences that use `title` for a path still display that text. Code, title, and filename are available before browser scripts run. HTML adds a Copy button when clipboard access is available; it copies the original text without syntax markup. Long blocks scroll horizontally. The Markdown twin keeps both options on the original fence. The settings below explain Shiki, themes, plain code, and custom adapters.
+
+## Highlighting with Shiki
+
+Shoalrun highlights fenced code and OpenAPI example panels while building the site. Shiki is the default provider, with the `site` theme. The HTML already contains the colored code before browser scripts run. The Markdown twin keeps the original fenced text. Language labels, filenames, and copy controls are covered above.
+
+### Configure Shiki
+
+Add this to the root config or an imported `outputs` fragment:
+
+```yaml
+outputs:
+  html:
+    highlighting:
+      provider: shiki
+      theme: site
+```
+
+The default is equivalent to that configuration. The `site` theme takes code colors from the site [palette](https://www.shoalrun.com/styling/palettes.md). Keywords use the accent color. Strings, numbers, and functions use the palette's green, amber, and blue. Code colors change with the palette, including in the [theme previewer](https://www.shoalrun.com/styling/try.md). A color below 4.5:1 contrast on the code background falls back to plain code text.
+
+To use a theme you know from your editor, set `theme` to a bundled Shiki theme name, such as `github-dark`, `dracula`, or `one-dark-pro`. A dark theme sets the syntax colors, and the palette still sets the block background so it matches the toolbar. A light theme, such as `github-light`, sets both its colors and its background. [Shiki's theme list](https://shiki.style/themes) shows available names. Site typography and surrounding colors still come from [CSS tokens](https://www.shoalrun.com/author/css.md). An unknown theme fails the build.
+
+The built-in grammars are JSON, YAML, shell, JavaScript, TypeScript, Python, HTML, CSS, MDX, Markdown, HTTP, XML, SQL, Go, Java, Ruby, C#, PHP, and Rust. Shiki also recognizes loaded aliases such as `sh` and `js`. Unknown or unlabeled code stays plain. JSON-compatible API examples use JSON highlighting; text media currently use plain text.
+
+### Choose plain code
+
+```yaml
+outputs:
+  html:
+    highlighting:
+      provider: none
+```
+
+`none` keeps code readable without syntax colors. Shiki is loaded only when its provider is selected. Code titles, scrolling, and copy behavior still work.
+
+### Use a custom highlighter
+
+```yaml
+outputs:
+  html:
+    highlighting:
+      provider: custom
+      module: ./highlight.mjs
+```
+
+The module path is relative to the config fragment that declares it. Export a synchronous function that returns flat text tokens. Each token may have a hexadecimal color:
+
+```javascript
+export function highlight(code, language) {
+  // Replace this with tokens from your preferred highlighter.
+  return [{ text: code, color: "#e4f2e9" }];
+}
+```
+
+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.
+
+## HTML, Markdown, and agents
+
+Highlighted code remains selectable without JavaScript. Blocks scroll horizontally without widening the page. Keyboard users can focus a long block to scroll it. The Copy button appears when the browser supports clipboard access in a secure context such as HTTPS or localhost. It copies the original code text rather than the colored spans. Without clipboard access, readers can select and copy manually.
+
+The Markdown twin keeps the original fenced code, language, title, and filename. An agent reading it receives the complete source text without syntax-color markup or the Copy control.
+
+The [publishing guide](https://www.shoalrun.com/publish/output.md) explains where HTML and Markdown outputs are written.
+
+## Related reading
+
+### Reference while working
+
+- [CSS and theme reference](https://www.shoalrun.com/author/css.md) — Look up the code color tokens and selectors.
+
+### Related topics
+
+- [Walkthroughs](https://www.shoalrun.com/author/components/walkthroughs.md) — Walkthroughs build on code blocks to explain an example one step at a time.

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

@@ -0,0 +1,99 @@
+---
+id: guide.component.collapsible
+title: Collapsibles
+summary: Show optional detail in individual disclosures or compact groups, with
+  full Markdown output.
+type: reference
+area: components
+subarea: components-procedures
+canonical: /author/components/collapsible
+---
+
+# Collapsibles
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Collapsibles
+
+**Updated: 2026-10-26.**
+
+`<Collapsible>` keeps supporting detail near the main instructions. Use it for material readers may need, but do not need to see before taking the next step. Its body is present in the initial HTML even when closed, and fully expanded in the Markdown twin.
+
+## Syntax
+
+```mdx
+<Collapsible title="Why is this page a draft?">
+Pages with draft access stay out of the public build.
+</Collapsible>
+```
+
+### Why is this page a draft?
+
+Pages with draft access stay out of the public build.
+
+| Attribute | Required | Meaning                                                     |
+| --------- | -------- | ----------------------------------------------------------- |
+| `title`   | Yes      | Nonempty literal text for the disclosure summary.           |
+| `open`    | No       | Bare boolean attribute that starts the disclosure expanded. |
+
+The body must contain block content. Dynamic MDX expressions and unknown components fail the build.
+
+## Include Markdown and MDX
+
+The body accepts paragraphs, lists, links, fenced code, and supported MDX components such as `Callout` and `DocLink`. These render inside the disclosure in HTML and in reading order in Markdown.
+
+```mdx
+<Collapsible title="Check the result" open>
+
+- Confirm the response status.
+- Compare the returned ID.
+
+<Callout type="tip">Keep the response for troubleshooting.</Callout>
+
+</Collapsible>
+```
+
+Use a normal section heading when readers should see the content as part of the main path. See the [component index](https://www.shoalrun.com/author/components.md) for other supported elements.
+
+## Group related items
+
+Wrap related disclosures in `<CollapsibleGroup>` to join their borders and remove the gaps between them. Each item opens independently, so readers can compare more than one answer.
+
+The wrapper accepts one or more direct `Collapsible` children and has no attributes. Use each child's `title` and optional `open` attribute as usual.
+
+```mdx
+<CollapsibleGroup>
+<Collapsible title="What gets published?">
+The build includes public pages in the selected publication.
+</Collapsible>
+<Collapsible title="Can I preview first?">
+Yes. Build locally and review the HTML and Markdown before deployment.
+</Collapsible>
+</CollapsibleGroup>
+```
+
+### What gets published?
+
+The build includes public pages in the selected publication.
+
+### Can I preview first?
+
+Yes. Build locally and review the HTML and Markdown before deployment.
+
+Put rich content inside each child. Other direct children fail the build. Groups do not enforce a single open item.
+
+## HTML, Markdown, and agents
+
+Individual disclosures and grouped items use native `details` and `summary`, so they work without JavaScript. Every body is present in the initial HTML even when closed.
+
+Markdown writes every title as a heading followed by its full body in source order. The group wrapper adds no extra heading or repeated text. An agent can read all details without opening a control.
+
+## Related reading
+
+### Often confused with
+
+- [Tabs](https://www.shoalrun.com/author/components/tabs.md) — A collapsible hides optional detail behind one summary; tabs switch between alternate views of the same content.
+
+- [Short definitions](https://www.shoalrun.com/author/components/info-hint.md) — A short definition contains plain text; a collapsible holds longer rich content.

package/agent-docs/author/components/cookbook-chooser.md

@@ -0,0 +1,86 @@
+---
+id: guide.component.cookbook-chooser
+title: CookbookChooser
+summary: Let readers select reviewed recipes and assemble them into one reading path.
+type: reference
+area: components
+subarea: components-procedures
+canonical: /author/components/cookbook-chooser
+---
+
+# CookbookChooser
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > CookbookChooser
+
+**Updated: 2026-10-26.**
+
+Use `<CookbookChooser>` to help a reader choose a complete recipe or combine compatible recipes. The author reviews each recipe and sets its place in the choice list. The browser loads the selected published recipe pages and displays their instructions. The component does not read ingredient files, generate a recipe, or execute commands. Start with [how recipes and cookbooks work](https://www.shoalrun.com/author/recipes.md), then [configure a cookbook](https://www.shoalrun.com/author/cookbooks.md); this page lists the component's exact syntax.
+
+## Syntax
+
+Map each option to a public recipe in project YAML, then place the chooser on a page in the same publication:
+
+```yaml title="config/cookbooks.yaml"
+site-checks:
+  title: How much validation do you need?
+  mode: single
+  options:
+    - { id: build, label: Build, doc: recipe.build-docs }
+    - { id: audit, label: Audit, doc: recipe.audit-docs }
+```
+
+```yaml title="docs.config.yaml"
+cookbooks: { $include: ./config/cookbooks.yaml }
+```
+
+```mdx
+<CookbookChooser id="site-checks" />
+```
+
+Try the live chooser for this documentation project:
+
+How much validation do you need?. Choose one recipe.
+
+- [Build and check page artifacts — Build this documentation site](https://www.shoalrun.com/recipes/build-docs.md)
+
+  Use when: You want to confirm a documentation edit compiles into HTML and Markdown.
+
+  You need: A Shoalrun checkout with dependencies installed and the page's stable ID.
+
+  You will have: A successful build and the checked paths for both page formats.
+
+- [Build and run project audits — Build and audit this documentation site](https://www.shoalrun.com/recipes/audit-docs.md)
+
+  Use when: You are preparing a change for review and need the configured API and project checks too.
+
+  You need: A Shoalrun checkout with dependencies installed and the page's stable ID.
+
+  You will have: A successful build, checked artifacts, and no failed configured audits.
+
+| Value               | Rule                                                                                                                            |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                | Required literal cookbook ID from `cookbooks`. No child content or other attributes.                                            |
+| `options`           | Nonempty ordered list of unique lowercase IDs, visible labels, and recipe document IDs. This order controls the assembled path. |
+| `mode`              | Optional `single` for alternatives or `multiple` (default) for compatible recipes.                                              |
+| Option descriptions | Optional `when`, `needs`, and `outcome` explain the choice in HTML and Markdown. Each is nonempty plain text.                   |
+| Recipe target       | Must be a public `type: recipe` page in the chooser's channel, version, and language.                                           |
+
+The build rejects duplicate IDs, labels, or recipe targets, plus missing, draft, wrong-type, or wrong-publication targets.
+
+## HTML, Markdown, and agents
+
+HTML displays checkboxes, or radio buttons for `mode: single`, after the page script starts. Selecting options loads the published recipe pages and assembles their instructions in configured order under **Your path**. Each section links to its source recipe. If a page cannot load, the source link remains available. The recipe list below the controls works without JavaScript.
+
+The cookbook page and choice list are compiled at build time. Recipe content is fetched when a reader selects it in the browser. The selected option IDs are stored in the page URL. **Link to this path** preserves that selection; **Download Markdown** saves all selected recipe instructions, and **Print this path** prints the loaded path. Downloads fail as a whole if a recipe cannot be fetched. Printing is disabled while any selected recipe failed to load.
+
+Markdown lists every recipe with its choice descriptions and a link to its `.md` page in the same order. An agent can choose a recipe from those descriptions and read its complete Markdown. The cookbook Markdown does not contain the browser-selected recipe bodies. Give an agent the recipe Markdown or downloaded selection to follow a task. A selection URL does not create a published Markdown endpoint.
+
+## Related reading
+
+### Related topics
+
+- [Compose and maintain recipes](https://www.shoalrun.com/author/recipe-drafts.md) — Let readers assemble reviewed recipes into a path in a cookbook.

package/agent-docs/author/components/custom/react.md

@@ -0,0 +1,190 @@
+---
+id: guide.custom-components.react
+title: Data-driven React components
+summary: Follow local data through a component plugin, shared documentation, and
+  a React calculator.
+type: explanation
+area: components
+subarea: components-custom
+canonical: /author/components/custom/react
+---
+
+# Data-driven React components
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Custom components > Data-driven React components
+
+**Updated: 2026-10-26.**
+
+Use a declared data file when a component needs to generate tables, calculations, or other structured documentation. This advanced example adds data and generated explanations to the [small CopyText example](https://www.shoalrun.com/author/components/custom.md). A data file is optional; ordinary component text can stay in MDX.
+
+## Where the content lives
+
+A custom component is a small program that writes part of a documentation page. Its build function produces shared content, which Shoalrun renders as HTML and Markdown. An optional React interface adds browser controls afterward. Shoalrun does not convert React into Markdown.
+
+The retry example splits its work across these files:
+
+| File                   | What you write there                                                        | What readers get                                    |
+| ---------------------- | --------------------------------------------------------------------------- | --------------------------------------------------- |
+| The page's `.mdx` file | Task-specific explanations and the `<RetryBudget />` invocation.            | The surrounding documentation in HTML and Markdown. |
+| `policy.json`          | Retry counts, delays, supported status codes, and the safety warning.       | The configured values and warning in both formats.  |
+| `plugin.mjs`           | Validation, reusable explanatory text, formulas, tables, and code examples. | The component's shared HTML and Markdown content.   |
+| `browser.jsx`          | React controls, state, input validation, and the interactive timeline.      | A browser interface for trying alternative values.  |
+| `style.css`            | Optional styles for the browser interface.                                  | The files the HTML page loads for that interface.   |
+
+`policy.json` is this example's data format, not a Shoalrun requirement. A simpler component can use only MDX attributes and child content. Keep page-specific prose in the page; put recurring explanations and generated content in the plugin.
+
+### Start with data
+
+For example, `policy.json` contains a complete configured policy:
+
+```json
+{
+  "attempts": 4,
+  "baseDelayMs": 500,
+  "maxDelayMs": 30000,
+  "backoff": "exponential",
+  "jitter": "none",
+  "retryableStatuses": [429, 502, 503, 504],
+  "warning": "Retry only idempotent operations, or requests protected by an idempotency key. Honor a server's Retry-After header; it can require a longer wait than this policy."
+}
+```
+
+The plugin's `content()` function imports that data, validates it, and returns shared content nodes. This shortened excerpt shows how a value becomes a paragraph; the complete plugin also generates the tables, warning, formula, schedule, code, and link:
+
+```js
+const policy = validatePolicy(importedPolicy);
+return {
+  content: c.paragraph(`Allow at most ${policy.attempts} attempts, including the first request.`),
+  data: policy
+};
+```
+
+That paragraph becomes `<p>Allow at most 4 attempts, including the first request.</p>` in HTML and the same sentence in Markdown. There is no separate Markdown renderer to write for these shared nodes.
+
+### Use the component in a page
+
+The page author supplies the surrounding context and invokes the registered component:
+
+```mdx
+## Retrying a request
+
+Check whether the operation is safe to repeat before enabling retries.
+The policy below shows the configured wait budget.
+
+<RetryBudget title="Request retry policy" />
+```
+
+With the example policy, the generated Markdown includes this worked schedule:
+
+```md
+| Attempt | Wait before attempt | Cumulative wait |
+| --- | --- | --- |
+| 1 | 0 ms | 0 ms |
+| 2 | 500 ms | 500 ms |
+| 3 | 1000 ms | 1500 ms |
+| 4 | 2000 ms | 3500 ms |
+```
+
+HTML displays the same documented schedule. React receives the same validated policy directly and adds the calculator shown below. Changing a browser control changes that reader's calculation; it does not edit `policy.json`, the documented schedule, or Markdown. To change the documented policy, edit the data file and rebuild.
+
+## Registration
+
+Add registrations to your project configuration:
+
+```yaml
+components:
+  - ./components/retry-budget/components.json
+```
+
+The manifest declares the build module, browser source, and styles relative to the package. Shoalrun compiles the module graph and includes imported JSON and shared functions in dependency tracking. The build module imports `policy.json`; there is no separate `files` registration.
+
+## Interactive React example
+
+A retry policy is a useful documentation component: readers need to understand the safety rules and calculate how repeated attempts affect total wait time. The packaged `examples/components/retry-budget/` folder contains a working plugin, policy data, React source, shared model module, and stylesheet. Copy the whole folder to `components/retry-budget/`, then install its dependencies from your project directory:
+
+```sh
+npm ci --prefix components/retry-budget
+```
+
+Use the registration above to enable the component.
+
+The plugin validates the JSON policy and generates a settings table, formulas, a worked schedule, a warning, a code example, and a specification link. React receives that validated policy as instance data and adds controls for exploring other policies. Both representations start from the same configured values.
+
+```mdx
+<RetryBudget title="Request retry policy" />
+```
+
+**Request retry policy**
+
+> **Before you retry:** Retry only idempotent operations, or requests protected by an idempotency key. Honor a server's Retry-After header; it can require a longer wait than this policy.
+
+Configured policy. Attempts include the first request; only subsequent attempts wait. These are fictional example settings, not a Shoalrun service limit.
+
+| Setting                 | Value              |
+| ----------------------- | ------------------ |
+| Maximum attempts        | 4                  |
+| Base delay (ms)         | 500                |
+| Delay cap (ms)          | 30000              |
+| Backoff                 | exponential        |
+| Jitter                  | none               |
+| Retryable HTTP statuses | 429, 502, 503, 504 |
+
+Supported controls: 1–8 attempts, base delay from 1 to 60000 ms, and a delay cap from the base delay to 60000 ms. Backoff is constant or exponential. Jitter is none or full.
+
+For retry number r starting at 1: constant delay = min(cap, base); exponential delay = min(cap, base × 2^(r − 1)). No jitter waits that delay. Full jitter samples uniformly from zero to that delay; its expected wait is half the delay. The calculator shows bounds, not a random prediction.
+
+The configured schedule follows. Cumulative wait excludes request duration and any longer Retry-After wait.
+
+| Attempt | Wait before attempt | Cumulative wait |
+| ------- | ------------------- | --------------- |
+| 1       | 0 ms                | 0 ms            |
+| 2       | 500 ms              | 500 ms          |
+| 3       | 1000 ms             | 1500 ms         |
+| 4       | 2000 ms             | 3500 ms         |
+
+This JavaScript calculates the delay bounds; your request handler must separately enforce retryable statuses, idempotency, and Retry-After.
+
+```js
+function retryDelayBounds(retry, policy) {
+  const ceiling = Math.min(policy.maxDelayMs, policy.baseDelayMs *
+    (policy.backoff === 'constant' ? 1 : 2 ** (retry - 1)));
+  return policy.jitter === 'full' ? [0, ceiling] : [ceiling, ceiling];
+}
+```
+
+[Read the Retry-After HTTP specification](https://www.rfc-editor.org/rfc/rfc9110.html#name-retry-after)
+
+`title` is an optional nonempty literal string, defaulting to `Retry budget`. The component accepts no children and imports its local `policy.json` file. The policy fields and control limits appear in the fixture above. The browser controls let readers explore alternatives; they do not change the documented policy or its Markdown.
+
+## Share the model with the browser
+
+The build module imports `policy.json` and `validatePolicy` and `retrySchedule` from `model.js`. Its `content()` function returns documentation built with content helpers and `data: policy`. Shoalrun serializes that validated instance data for the browser.
+
+The browser module receives it directly:
+
+```js
+export function enhance({ root, controls, content, data: policy }) {
+  // Mount the optional React calculator using policy.
+  // Preserve the shared documentation in content.
+}
+```
+
+The browser imports the same `retrySchedule` function as the build module. It does not parse table rows, depend on English labels, or maintain a separate calculation implementation. Renaming a documented label does not change the calculator's model.
+
+React and React DOM are dependencies of this component package. Shoalrun compiles its JSX and imports when building the site; component consumers do not run a separate bundler. The interface still enhances shared documentation and does not render arbitrary MDX imports.
+
+## HTML, Markdown, and agents
+
+The calculator uses labeled native form controls, keyboard input, and an announced result. Without JavaScript, the configured settings, supported alternatives, formulas, worked schedule, safety warning, code, and specification link remain visible. Markdown contains that same explanation. Changing browser controls does not change the documented policy.
+
+The author and agent must write the shared explanation deliberately. Shoalrun does not infer it from React. Review the essential content in both outputs, including every meaningful choice and warning. The [component-authoring skill](https://www.shoalrun.com/author/components/custom.md) guides that work.
+
+## Related reading
+
+### Read first
+
+- [Custom components](https://www.shoalrun.com/author/components/custom.md) — Start with a small component whose content stays in MDX.

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

@@ -0,0 +1,36 @@
+---
+id: guide.custom-components.react
+title: Data-driven React components
+summary: Follow local data through a component plugin, shared documentation, and
+  a React calculator.
+type: explanation
+area: components
+subarea: components-custom
+canonical: /author/components/custom/react
+---
+
+# Data-driven React components
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Custom components > Data-driven React components
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/components/custom/react.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Custom components](https://www.shoalrun.com/author/components/custom.md) — Start with a small component whose content stays in MDX.
+
+Use a declared data file when a component needs to generate tables, calculations, or other structured documentation. This advanced example adds data and generated explanations to the [small CopyText example](https://www.shoalrun.com/author/components/custom.md). A data file is optional; ordinary component text can stay in MDX.
+
+## HTML, Markdown, and agents
+
+The calculator uses labeled native form controls, keyboard input, and an announced result. Without JavaScript, the configured settings, supported alternatives, formulas, worked schedule, safety warning, code, and specification link remain visible. Markdown contains that same explanation. Changing browser controls does not change the documented policy.
+
+The author and agent must write the shared explanation deliberately. Shoalrun does not infer it from React. Review the essential content in both outputs, including every meaningful choice and warning. The [component-authoring skill](https://www.shoalrun.com/author/components/custom.md) guides that work.