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

package/agent-docs/author/components/custom/react.sections/interactive-react-example.md

@@ -0,0 +1,88 @@
+---
+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.
+
+## 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.

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

@@ -0,0 +1,41 @@
+---
+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.
+
+## 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.

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

@@ -0,0 +1,30 @@
+---
+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)
+
+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.
+
+## 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/share-the-model-with-the-browser.md

@@ -0,0 +1,47 @@
+---
+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.
+
+## 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.

package/agent-docs/author/components/custom/react.sections/where-the-content-lives.md

@@ -0,0 +1,100 @@
+---
+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.
+
+## 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.

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

@@ -0,0 +1,183 @@
+---
+id: guide.custom-components
+title: Custom components
+summary: Register trusted component plugins with shared HTML and Markdown content.
+type: reference
+area: components
+subarea: components-custom
+canonical: /author/components/custom
+---
+
+# Custom 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 > Overview
+
+**Updated: 2026-10-26.**
+
+A component package adds a custom component, such as `<CopyText>`, that authors can use in their pages. Its `content()` function produces the content shown in both HTML and Markdown. An optional browser module adds interactive behavior.
+
+## Use a component
+
+Install the component package and add its exported manifest to your configuration. For a local component, register its manifest path:
+
+```yaml
+components:
+  - ./components/copy-text/components.json
+```
+
+An installed package can export its manifest as its entry point, or as a subpath such as `@acme/docs-components/shoalrun`. Replace that illustrative name with your installed package's export. Paths resolve relative to the configuration file that declares them, including includes and presets.
+
+The page supplies the content:
+
+```mdx
+<CopyText>
+Contact support@example.com for help.
+</CopyText>
+```
+
+Contact <support@example.com> for help.
+
+`CopyText` requires child content and accepts no attributes. Its copy button is optional browser behavior. Markdown retains the authored text:
+
+```md
+Contact <support@example.com> for help.
+```
+
+## Develop a component
+
+The package's manifest declares its names and implementation files. Consumers register this manifest once; they do not configure its internal browser files:
+
+```json
+{
+  "apiVersion": 1,
+  "components": {
+    "CopyText": {
+      "module": "./plugin.mjs",
+      "browser": "./browser.jsx"
+    }
+  }
+}
+```
+
+Each component needs `module`. `browser` and a `styles` list are optional. These paths are relative to the manifest. Names start with an uppercase letter, contain only letters and digits, and must be unique across registrations. They cannot replace built-ins.
+
+The complete build module for the small example passes the page's children through unchanged:
+
+```js
+import { defineComponent } from '@shoalrun/cli/components';
+export default defineComponent({
+  children: 'required',
+  content({ children }) { return children; }
+});
+```
+
+A component that generates documentation uses the supported `content` helpers:
+
+```js
+import { defineComponent, content as c } from '@shoalrun/cli/components';
+
+export default defineComponent({
+  attributes: { label: { type: 'string', required: true } },
+  children: 'required',
+  content({ attributes, children }) {
+    return [c.paragraph(c.strong(attributes.label)), children];
+  }
+});
+```
+
+Helpers include `paragraph`, `strong`, `emphasis`, `inlineCode`, `code`, `heading`, `link`, `list`, `table`, `group`, and `component`. They create shared content without requiring compiler-node objects. `component` composes an existing Shoalrun component using its documented attributes. Raw HTML and representation filters are unsupported.
+
+`content()` is required. A missing function or empty result fails with a diagnostic; there is no separate HTML-only renderer. It receives validated attributes and the authored children. It runs once per invocation before either output is rendered.
+
+## Attributes and children
+
+Attribute schemas define the values page authors may supply:
+
+| Setting                 | Meaning                                                       |
+| ----------------------- | ------------------------------------------------------------- |
+| `type`                  | `string`, `boolean`, or `number`.                             |
+| `required`              | Whether the attribute must be present when it has no default. |
+| `default`               | A value matching the declared type and constraints.           |
+| `values`                | Allowed string values.                                        |
+| `min`, `max`, `integer` | Optional numeric constraints.                                 |
+
+Booleans accept a bare attribute or quoted `"true"` and `"false"`. Numbers use quoted literals such as `attempts="4"`. Dynamic expressions are unsupported. Unknown or duplicate attributes fail. The TypeScript API infers attribute types from the schema.
+
+`children` is `none` by default, or `optional` or `required`. Return the supplied children to preserve page-authored content. Use `content.component` to compose built-ins with more specific child rules.
+
+## Browser data and behavior
+
+For an interactive component, resolve its model in `content()` and return both shared documentation and browser data:
+
+```js
+content({ attributes }) {
+  const policy = makePolicy(attributes);
+  return {
+    content: describePolicy(policy),
+    data: policy
+  };
+}
+```
+
+`makePolicy` and `describePolicy` represent your component's model and content functions. `data` must contain only JSON values. Shoalrun snapshots it per invocation and gives that same data to the browser. Do not recover data by parsing tables or matching display labels. Import shared validation and calculation functions into both implementations when they need the same behavior.
+
+The browser module exports an enhancement function:
+
+```js
+export async function enhance({ root, controls, content, data }) {
+  // Mount optional controls into the empty controls element.
+  // Read the instance model from data, not from presentation markup.
+  // Keep the shared documentation in content intact.
+  // Reveal controls after mounting; return when the interface is ready.
+}
+```
+
+`root` contains this component instance; `content` contains its rendered documentation. React can mount into `controls`. Browser behavior enhances the shared documentation; this is not an arbitrary React renderer or an MDX import mechanism. If enhancement fails or JavaScript is disabled, shared content remains readable.
+
+The [data-driven React fixture](https://www.shoalrun.com/author/components/custom/react.md) exercises the explicit model handoff and shared calculation module.
+
+## Dependencies and assets
+
+Write ordinary JavaScript or TypeScript imports in the build module and JavaScript, TypeScript, or JSX in the browser module. Shoalrun compiles them and tracks their imported source, JSON, and package metadata. Component packages declare their own dependencies, including React when used. There is no separate browser-bundle step for consumers.
+
+Imported local JSON supplies build data. Module imports must be statically resolvable; remote plugins and build-time fetching are outside the supported contract. Styles must be self-contained CSS files listed in the manifest. Existing content components such as `Image` retain their own asset rules; local image paths are relative to the authored page.
+
+Browser output uses deduplicated content-based asset URLs. Imported modules, data, manifests, and styles participate in rebuilds and isolated validation. Changes to imports invalidate earlier validation evidence. A failed build preserves the last successful output.
+
+Configured modules execute trusted code with build-process permissions. Browser modules run with the site's page permissions. Neither is sandboxed. Isolated validation compiles the captured dependency graph and executes the build module inside that captured project.
+
+## HTML, Markdown, and agents
+
+Shoalrun renders the same shared documentation into both formats. Authors remain responsible for whether it adequately explains the component. A calculator typically needs its inputs, formula, limits, a default worked example, and qualifications; it does not need every possible numeric state enumerated.
+
+Page content, links, warnings, and code must remain available without browser interaction. Shared content participates in normal search, links, section extraction, digests, and artifact generation. Check the component's own behavior and meaning in both outputs, including keyboard use and no-JavaScript fallback.
+
+## Use the component-authoring skill
+
+`shoalrun-component-author` guides an agent to implement the component's content, optional browser behavior, package manifest, and focused fixtures. The agent uses its own model and normal editing tools. Framework registration and dependency conformance are tested by Shoalrun; the component's tests should focus on its own content and behavior.
+
+From the consumer project, validate a fixture and inspect the returned report:
+
+```sh
+shoalrun docs validate --config docs.config.yaml --file content/component-example.mdx
+shoalrun docs review <report> --format markdown
+shoalrun docs preview <report> --port 0
+```
+
+The skill does not publish the result or infer a static explanation from arbitrary React. See [Use the bundled agent skills](https://www.shoalrun.com/contribute/agent-skills.md) for installation and invocation.
+
+## Related reading
+
+### Next steps
+
+- [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) — Validate component fixtures and review matching HTML and Markdown snapshots. (Status: experimental.)
+
+- [Data-driven React components](https://www.shoalrun.com/author/components/custom/react.md) — Add local data and generated documentation to a React interface.
+
+### Reference while working
+
+- [Publishing and agent representations](https://www.shoalrun.com/publish/output.md) — Check the published content and artifacts available to readers and agents.

package/agent-docs/author/components/definition-list.md

@@ -0,0 +1,54 @@
+---
+id: guide.component.definition-list
+title: Definition lists
+summary: Pair terms with full explanations in semantic HTML and readable Markdown.
+type: reference
+area: components
+subarea: components-prose
+canonical: /author/components/definition-list
+---
+
+# Definition lists
+
+> 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 > Definition lists
+
+**Updated: 2026-10-26.**
+
+Use `<DefinitionList>` for a compact glossary or configuration reference. Put alternating `<Term>` and `<Definition>` children inside it. Add `filter` when readers need to search a long list by term or definition text.
+
+## Syntax
+
+```mdx
+<DefinitionList filter>
+<Term>Publication</Term>
+<Definition>A channel, version, and language combination.</Definition>
+<Term>Slug</Term>
+<Definition>The page's public path. See [Page metadata](doc:guide.frontmatter).</Definition>
+</DefinitionList>
+```
+
+- **Publication**
+
+  A channel, version, and language combination.
+
+- **Slug**
+
+  The page's public path. See [Page metadata](https://www.shoalrun.com/author/frontmatter.md).
+
+`filter` is an optional bare attribute on `<DefinitionList>`. The other tags have no attributes. Terms and definitions must have content; definitions can contain links and rich text. See the [site glossary](https://www.shoalrun.com/glossary.md) for a longer filtered list.
+
+## HTML, Markdown, and agents
+
+HTML uses `<dl>`, `<dt>`, and `<dd>`, with aligned columns on wide screens and stacked pairs on narrow screens. With `filter`, JavaScript adds a labeled search input and a live count above the list. It searches both terms and definitions, hides or shows each pair together, and Escape clears the query. Without JavaScript, every pair remains visible and the filter control stays hidden.
+
+Markdown keeps each term immediately before its full definition in a list, so an agent can read every pair in order. The interactive filter does not appear in Markdown.
+
+## Related reading
+
+### Related topics
+
+- [Glossary](https://www.shoalrun.com/glossary.md) — See a long, filterable definition list in use.