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

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

@@ -0,0 +1,90 @@
+---
+id: guide.coding-agent-authoring
+title: Use your coding agent
+summary: Give your agent project guidance and draft a new documentation page.
+type: how-to
+area: authoring
+subarea: authoring-agent-workflows
+audiences:
+  - authors
+canonical: /author/coding-agent
+---
+
+# Use your coding agent
+
+> 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 > Write with agents > Use your agent > Draft a page
+
+**Updated: 2026-10-26.**
+
+Use an agent that can read project files and run commands. It writes with its own model; Shoalrun requires no additional authoring API key.
+
+## Prepare your agent
+
+Install the [portable authoring skill](https://www.shoalrun.com/contribute/agent-skills.md) using your agent's supported skill setup. If it cannot load skills, give it the same project instructions and commands directly. Tell it where to find `docs.config.yaml`, your writing guide, and reviewed examples. The [example writing guide](https://www.shoalrun.com/author/writing-style.md) is a starting point you can adapt.
+
+The CLI's `docs search` and `docs read` commands read bundled Shoalrun guidance. The [MCP server](https://www.shoalrun.com/cli.md) offers documentation search and reads for agents that support MCP; it does not write project files. Your agent uses its own file tools and the CLI for edits.
+
+## Give a working-tree task
+
+Name the reader outcome and documentation project. Let the agent discover the relevant pages and required supporting changes from project policy. For example:
+
+```text
+Read the installed shoalrun-author/SKILL.md and work in this documentation project.
+Revise the authoring procedure so readers can write titled steps and inspect
+both outputs. Read project policy and supporting evidence first, preserve earlier
+local edits, capture a task baseline, edit files normally, and show the matching
+validation report, preview, and task diff. Do not commit or publish.
+```
+
+This uses the harness's own writer and execution permissions. Required navigation, relationships, and changelog entries come from the project instructions rather than an automatic compiler rule. If evidence is missing or policies conflict, the agent should identify the question for review.
+
+## Draft a new page
+
+1. ## Define the reader's task
+
+   Give your agent the audience, goal, intended page type, and supporting sources. Let it gather and evaluate evidence using its own tools. Ask it to identify missing facts rather than invent examples or behavior.
+
+2. ## Choose and scaffold a template
+
+   Use the project's [templates](https://www.shoalrun.com/author/templates.md). Record the starting state before scaffolding:
+
+   ```sh
+   shoalrun docs baseline --out .shoalrun/task-baseline.json --config docs.config.yaml
+   shoalrun scaffold how-to -n content/publish-a-site.mdx --config docs.config.yaml
+   ```
+
+   The new file is a draft. Replace the prompts, preserve its identity and publication metadata, and add required companions from project policy.
+
+3. ## Check and review the page
+
+   Run the project's style checker and configured checks. Read the draft, verify its examples, and review technical claims against the evidence.
+
+   ```sh
+   shoalrun docs validate --baseline .shoalrun/task-baseline.json --config docs.config.yaml
+   shoalrun docs review /path/from/result/report.json --format markdown
+   shoalrun docs preview /path/from/result/report.json --port 0
+   ```
+
+   Use the actual report path returned by validation. It renders affected drafts in a separate capture while preserving their authored access policy. Review findings, coverage, and skipped checks; use `--run-checks` only for applicable trusted commands under the harness's permissions. A stale, failed, incomplete, or unavailable result is not a pass. After edits, revalidate and restart the preview from the new report. Stop the foreground preview with Ctrl-C when finished.
+
+4. ## Prepare publication
+
+   After the author approves publication, change the page's access policy to public and build to a dedicated output directory. Inspect its HTML, Markdown, navigation, and links before committing or deploying.
+
+   ```sh
+   shoalrun build docs.config.yaml preview-output
+   ```
+
+## Related reading
+
+### Related topics
+
+- [Write with agents](https://www.shoalrun.com/author/agents.md) — Choose the authoring workflow that fits how you work.
+
+- [Use the bundled agent skills](https://www.shoalrun.com/contribute/agent-skills.md) — Give your coding agent the bundled Shoalrun workflow instructions.
+
+- [Apply a checked edit plan](https://www.shoalrun.com/author/authoring-agent.md) — Prepare a checked edit to an existing page. (Status: experimental.)

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

@@ -0,0 +1,41 @@
+---
+id: guide.component.action-link
+title: Action links
+summary: Give a next step a prominent link style while retaining real navigation
+  semantics.
+type: reference
+area: components
+subarea: components-navigation
+canonical: /author/components/action-link
+---
+
+# Action links
+
+> 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 > Action links
+
+**Updated: 2026-10-19.**
+
+`<ActionLink>` styles a navigation link as a prominent action. `<Button>` is an alias for authors migrating button-like links. Both render a real `<a>` element, so they work with keyboard navigation and without JavaScript.
+
+```mdx
+<ActionLink doc="guide.add-page">Create a page</ActionLink>
+<ActionLink href="https://example.com/download" variant="secondary">Download example</ActionLink>
+```
+
+[Create a page](https://www.shoalrun.com/author/add-page.md)
+[Download example](https://example.com/download)
+
+| Attribute       | Required | Meaning                                                                    |
+| --------------- | -------- | -------------------------------------------------------------------------- |
+| `doc` or `href` | Yes, one | A stable document ID, site path, fragment, HTTP(S) URL, or `mailto:` link. |
+| `variant`       | No       | `primary` (default) or `secondary`.                                        |
+
+The body is nonempty inline text, with optional emphasis or inline code.
+
+## HTML, Markdown, and agents
+
+HTML renders a real link with a visible focus state. Markdown retains its label and destination, resolving `doc` IDs to the target Markdown page. An agent can follow the destination without interpreting the visual button style.

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

@@ -0,0 +1,263 @@
+---
+id: guide.component.api-embeds
+title: ApiExample and ApiSchema
+summary: Include named OpenAPI examples and selected schemas in authored pages.
+type: reference
+area:
+  - components
+  - api
+subarea:
+  - components-api
+  - api-contracts
+canonical: /author/components/api-embeds
+---
+
+# ApiExample and ApiSchema
+
+> 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 > ApiExample and ApiSchema
+
+**Updated: 2026-10-26.**
+
+`ApiExample` and `ApiSchema` reuse OpenAPI content in authored pages. Examples stay synchronized with named payloads; schemas expose selected field definitions in HTML and Markdown.
+
+## ApiExample
+
+`<ApiExample>` copies a named example from the OpenAPI source bound to a stable operation ID. Use it in a guide when the full payload should stay synchronized with the reference.
+
+### Syntax
+
+```mdx
+<ApiExample operation="notes.create" kind="response" status="201" mediaType="application/json" example="saved" />
+```
+
+| Attribute   | Required      | Meaning                                          |
+| ----------- | ------------- | ------------------------------------------------ |
+| `operation` | Yes           | Stable operation ID bound to an API source.      |
+| `kind`      | Yes           | `request` or `response`.                         |
+| `mediaType` | Yes           | Exact media type in the source.                  |
+| `example`   | Yes           | Key in that media type's OpenAPI `examples` map. |
+| `status`    | For responses | Response status, such as `201`.                  |
+
+The element is standalone and empty, with literal string attributes. It resolves in the page's publication. HTML and Markdown show the example title, original key, context, description when present, provenance, and value. A missing selector fails the build. API includes cannot be nested inside snippets. See [API references](https://www.shoalrun.com/publish/api-references.md) for source configuration and [example presentation](https://www.shoalrun.com/api-docs/generate.md) in reference pages.
+
+The fictional Notes API returns a saved note with its author, labels, and display metadata. The response includes a required but nullable `archivedAt` field: `null` means the note is active.
+
+### Created release note
+
+OpenAPI response 201; application/json. Example key: saved. Authored in OpenAPI.
+
+An active note with a nested author, two labels, and optional display metadata.
+
+```json
+{
+  "id": "note_123",
+  "text": "Review the release candidate.",
+  "createdAt": "2026-10-18T09:30:00Z",
+  "archivedAt": null,
+  "author": {
+    "id": "usr_42",
+    "displayName": "Morgan Lee"
+  },
+  "tags": [
+    "release",
+    "review"
+  ],
+  "metadata": {
+    "source": "release-checklist",
+    "pinned": true
+  }
+}
+```
+
+### Markdown twin
+
+During the build, Shoalrun selects the named example from the OpenAPI source for this page's publication and replaces `<ApiExample>` with ordinary content. An agent reading the generated `.md` page does not need to resolve the component or fetch the OpenAPI file. The example above renders as:
+
+````md
+### Created release note
+
+OpenAPI response 201; application/json. Example key: saved. Authored in OpenAPI.
+
+An active note with a nested author, two labels, and optional display metadata.
+
+```json
+{
+  "id": "note_123",
+  "text": "Review the release candidate.",
+  "createdAt": "2026-10-18T09:30:00Z",
+  "archivedAt": null,
+  "author": {
+    "id": "usr_42",
+    "displayName": "Morgan Lee"
+  },
+  "tags": [
+    "release",
+    "review"
+  ],
+  "metadata": {
+    "source": "release-checklist",
+    "pinned": true
+  }
+}
+```
+````
+
+An OpenAPI description appears between the context line and payload when present. JSON-compatible values use a `json` fence; string values with a `text/*` media type use a `text` fence. If the source uses `externalValue`, the twin shows an **External example** link instead of an inline payload. A response example's context includes its status, such as `response 201; application/json`.
+
+## ApiSchema
+
+`<ApiSchema>` includes a schema from a configured OpenAPI source. It can select a request or response body, a standalone object, or one field. Use it when readers need the exact source definition alongside task instructions.
+
+### Syntax
+
+```mdx
+<ApiSchema operation="notes.create" kind="response" status="201" mediaType="application/json" />
+```
+
+| Attribute   | Required                | Meaning                                                                                         |
+| ----------- | ----------------------- | ----------------------------------------------------------------------------------------------- |
+| `operation` | For a body              | Stable operation ID bound to an API source.                                                     |
+| `api`       | For a standalone schema | Configured API ID.                                                                              |
+| `kind`      | With `operation`        | `request` or `response`.                                                                        |
+| `mediaType` | With `operation`        | Exact media type.                                                                               |
+| `status`    | For response bodies     | Response status, such as `201`.                                                                 |
+| `schema`    | With `api`              | Local OpenAPI `$ref` selector. With `operation`, omitted uses the selected media type's schema. |
+
+Use `operation`, `kind`, `mediaType`, and `status` for a body schema. To select an object that is not a body, use `api` and `schema` without the operation attributes. A pointer ending in `/properties/<name>` selects a single field. Both forms use the API source for the page's publication.
+
+```mdx
+<ApiSchema api="notes" schema="#/components/schemas/NoteMetadata" />
+<ApiSchema api="notes" schema="#/components/schemas/NoteMetadata/properties/source" />
+```
+
+### Schema · NoteMetadata
+
+object
+
+Optional display information for a note.
+
+2 properties
+
+- `source` `string` **optional**&#x20;
+
+  Where the note came from.
+
+- `pinned` `boolean` **optional**&#x20;
+
+  Whether the note stays at the top.
+
+### Field · source
+
+string
+
+Where the note came from.
+
+The element is standalone and empty, with literal string attributes. A missing or invalid selector fails the build. API includes cannot be nested inside snippets. See [API references](https://www.shoalrun.com/publish/api-references.md) for source setup and focused contracts.
+
+### Response 201 schema · application/json
+
+A saved note with its author, labels, and display metadata.
+
+7 properties
+
+- `id` `string` **always present**&#x20;
+
+  The generated note ID.
+
+- `text` `string` **always present**&#x20;
+
+  maxLength: 280
+
+  The saved text.
+
+- `createdAt` `string` **always present**&#x20;
+
+  format: date-time
+
+  When the note was created.
+
+- `archivedAt` `string` **always present** **nullable**&#x20;
+
+  format: date-time
+
+  When the note was archived, or null while active.
+
+- `author` `object` **always present**&#x20;
+
+  The person who created the note.
+
+  2 properties
+
+  - `id` `string` **always present**&#x20;
+
+    The author's user ID.
+
+  - `displayName` `string` **always present**&#x20;
+
+    The author's display name.
+
+- `tags` `list of string` **may be absent**&#x20;
+
+  Labels used to organize the note.
+
+  Array items:
+
+  string
+
+- `metadata` `object` **may be absent**&#x20;
+
+  Optional display information for a note.
+
+  2 properties
+
+  - `source` `string` **may be absent**&#x20;
+
+    Where the note came from.
+
+  - `pinned` `boolean` **may be absent**&#x20;
+
+    Whether the note stays at the top.
+
+### Markdown twin
+
+The build expands `<ApiSchema>` before writing the `.md` page. It becomes a level-three heading naming the body, standalone schema, or selected field. The schema type follows, then any nested fields with presence rules, types, descriptions, and other authored constraints. HTML field rows have stable anchors; the Markdown lists keep field names readable without raw HTML tags. An agent can read the structure without the HTML presentation or browser scripts.
+
+The standalone object above begins like this in the Markdown twin, before its field list:
+
+```md
+### Schema · NoteMetadata
+
+object
+
+Optional display information for a note.
+```
+
+The selected `source` field above appears in the Markdown twin as:
+
+```md
+### Field · source
+
+string
+
+Where the note came from.
+```
+
+`<ApiSchema>` includes the full selected schema, including nested objects. It does not shorten or collapse large schemas in either output. For a large object, include it in a guide only when readers need the whole field tree there. Otherwise, select a relevant field, use authored [Fields](https://www.shoalrun.com/author/components/fields.md) for a short explanation, or link to the API reference. A field pointer selects its definition; it does not infer whether that field is required by its parent. Recursive references stop with a visible recursive-reference note rather than repeating forever.
+
+## HTML, Markdown, and agents
+
+The build resolves both components against the OpenAPI source for the page's publication. HTML presents examples and schema fields with their labels and context. Markdown expands them into ordinary text, lists, and code. An agent can read that content without fetching the source file or running browser scripts. Both outputs include the complete selected example or schema.
+
+## Related reading
+
+### Read first
+
+- [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md) — Register the OpenAPI source these components read from.
+
+### Related topics
+
+- [Fields](https://www.shoalrun.com/author/components/fields.md) — Write field lists by hand in the same format as generated schemas.

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

@@ -0,0 +1,117 @@
+---
+id: guide.component.api-embeds
+title: ApiExample and ApiSchema
+summary: Include named OpenAPI examples and selected schemas in authored pages.
+type: reference
+area:
+  - components
+  - api
+subarea:
+  - components-api
+  - api-contracts
+canonical: /author/components/api-embeds
+---
+
+# ApiExample and ApiSchema
+
+> 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 > ApiExample and ApiSchema
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/components/api-embeds.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md) — Register the OpenAPI source these components read from.
+
+`ApiExample` and `ApiSchema` reuse OpenAPI content in authored pages. Examples stay synchronized with named payloads; schemas expose selected field definitions in HTML and Markdown.
+
+## ApiExample
+
+`<ApiExample>` copies a named example from the OpenAPI source bound to a stable operation ID. Use it in a guide when the full payload should stay synchronized with the reference.
+
+### Syntax
+
+```mdx
+<ApiExample operation="notes.create" kind="response" status="201" mediaType="application/json" example="saved" />
+```
+
+| Attribute   | Required      | Meaning                                          |
+| ----------- | ------------- | ------------------------------------------------ |
+| `operation` | Yes           | Stable operation ID bound to an API source.      |
+| `kind`      | Yes           | `request` or `response`.                         |
+| `mediaType` | Yes           | Exact media type in the source.                  |
+| `example`   | Yes           | Key in that media type's OpenAPI `examples` map. |
+| `status`    | For responses | Response status, such as `201`.                  |
+
+The element is standalone and empty, with literal string attributes. It resolves in the page's publication. HTML and Markdown show the example title, original key, context, description when present, provenance, and value. A missing selector fails the build. API includes cannot be nested inside snippets. See [API references](https://www.shoalrun.com/publish/api-references.md) for source configuration and [example presentation](https://www.shoalrun.com/api-docs/generate.md) in reference pages.
+
+The fictional Notes API returns a saved note with its author, labels, and display metadata. The response includes a required but nullable `archivedAt` field: `null` means the note is active.
+
+### Created release note
+
+OpenAPI response 201; application/json. Example key: saved. Authored in OpenAPI.
+
+An active note with a nested author, two labels, and optional display metadata.
+
+```json
+{
+  "id": "note_123",
+  "text": "Review the release candidate.",
+  "createdAt": "2026-10-18T09:30:00Z",
+  "archivedAt": null,
+  "author": {
+    "id": "usr_42",
+    "displayName": "Morgan Lee"
+  },
+  "tags": [
+    "release",
+    "review"
+  ],
+  "metadata": {
+    "source": "release-checklist",
+    "pinned": true
+  }
+}
+```
+
+### Markdown twin
+
+During the build, Shoalrun selects the named example from the OpenAPI source for this page's publication and replaces `<ApiExample>` with ordinary content. An agent reading the generated `.md` page does not need to resolve the component or fetch the OpenAPI file. The example above renders as:
+
+````md
+### Created release note
+
+OpenAPI response 201; application/json. Example key: saved. Authored in OpenAPI.
+
+An active note with a nested author, two labels, and optional display metadata.
+
+```json
+{
+  "id": "note_123",
+  "text": "Review the release candidate.",
+  "createdAt": "2026-10-18T09:30:00Z",
+  "archivedAt": null,
+  "author": {
+    "id": "usr_42",
+    "displayName": "Morgan Lee"
+  },
+  "tags": [
+    "release",
+    "review"
+  ],
+  "metadata": {
+    "source": "release-checklist",
+    "pinned": true
+  }
+}
+```
+````
+
+An OpenAPI description appears between the context line and payload when present. JSON-compatible values use a `json` fence; string values with a `text/*` media type use a `text` fence. If the source uses `externalValue`, the twin shows an **External example** link instead of an inline payload. A response example's context includes its status, such as `response 201; application/json`.

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

@@ -0,0 +1,37 @@
+---
+id: guide.component.api-embeds
+title: ApiExample and ApiSchema
+summary: Include named OpenAPI examples and selected schemas in authored pages.
+type: reference
+area:
+  - components
+  - api
+subarea:
+  - components-api
+  - api-contracts
+canonical: /author/components/api-embeds
+---
+
+# ApiExample and ApiSchema
+
+> 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 > ApiExample and ApiSchema
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/components/api-embeds.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md) — Register the OpenAPI source these components read from.
+
+`ApiExample` and `ApiSchema` reuse OpenAPI content in authored pages. Examples stay synchronized with named payloads; schemas expose selected field definitions in HTML and Markdown.
+
+## HTML, Markdown, and agents
+
+The build resolves both components against the OpenAPI source for the page's publication. HTML presents examples and schema fields with their labels and context. Markdown expands them into ordinary text, lists, and code. An agent can read that content without fetching the source file or running browser scripts. Both outputs include the complete selected example or schema.

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

@@ -0,0 +1,37 @@
+---
+id: guide.component.api-embeds
+title: ApiExample and ApiSchema
+summary: Include named OpenAPI examples and selected schemas in authored pages.
+type: reference
+area:
+  - components
+  - api
+subarea:
+  - components-api
+  - api-contracts
+canonical: /author/components/api-embeds
+---
+
+# ApiExample and ApiSchema
+
+> 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 > ApiExample and ApiSchema
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/components/api-embeds.md)
+
+`ApiExample` and `ApiSchema` reuse OpenAPI content in authored pages. Examples stay synchronized with named payloads; schemas expose selected field definitions in HTML and Markdown.
+
+## Related reading
+
+### Read first
+
+- [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md) — Register the OpenAPI source these components read from.
+
+### Related topics
+
+- [Fields](https://www.shoalrun.com/author/components/fields.md) — Write field lists by hand in the same format as generated schemas.

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

@@ -0,0 +1,76 @@
+---
+id: guide.component.badge
+title: Badges
+summary: Put a short, labeled status or platform name inside a sentence.
+type: reference
+area: components
+subarea: components-prose
+canonical: /author/components/badge
+---
+
+# Badges
+
+> 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 > Badges
+
+**Updated: 2026-10-25.**
+
+`<Badge>` adds a compact label inside prose, a heading, or a table cell. Write the state in its text; color and the optional icon only reinforce it.
+
+```mdx
+The API is <Badge variant="success" icon="check">Stable</Badge>.
+```
+
+The API is Stable.
+
+## Built-in variants
+
+These five variants are available in every Shoalrun project. None has a default icon.
+
+| Variant   | Example    | Color source                                                                          |
+| --------- | ---------- | ------------------------------------------------------------------------------------- |
+| `neutral` | Platform   | `--color-field-surface`, `--color-ink`, and `--color-border` from the active palette. |
+| `info`    | Preview    | The active palette's `callout-note` background, text, and line tokens.                |
+| `success` | Stable     | The active palette's `callout-tip` background, text, and line tokens.                 |
+| `warning` | Deprecated | The active palette's `callout-warning` background, text, and line tokens.             |
+| `new`     | New        | The active palette's purple `callout-important` background, text, and line tokens.    |
+
+The built-in variants follow the selected palette and color mode. A project can override a built-in variant or add another in `badges.variants`. Add `icon` only when it helps the reader. The variant changes presentation only; Markdown keeps the label text.
+
+## Add a custom color
+
+For example, this site registers a teal `partner` variant. It is a custom example, not one of the built-in variants. Give a custom variant `background` and `text` hex colors for light mode, and for dark mode if the site shows dark mode. `border` is optional and defaults to the text color. The build rejects unknown variant names and checks badge text against its background at 4.5:1 in each shown mode.
+
+```yaml title="docs.config.yaml"
+badges:
+  variants:
+    partner:
+      light: { background: '#e5f5f3', text: '#175b57', border: '#4c9992' }
+      dark: { background: '#102e2d', text: '#a6e7df', border: '#4caaa1' }
+```
+
+```mdx
+This feature is <Badge variant="partner">Partner</Badge>.
+```
+
+This feature is Partner.
+
+Projects can put this mapping in a separate file with `$include`. To change a built-in variant across a site, register that same name with custom colors. For broad palette changes, edit the [palette tokens](https://www.shoalrun.com/styling/palettes.md); for CSS-level overrides, see the [CSS reference](https://www.shoalrun.com/author/css.md).
+
+## Attributes and output
+
+Badge attributes control its label, appearance, and representation in the published outputs.
+
+| Attribute | Required | Meaning                                                                                         |
+| --------- | -------- | ----------------------------------------------------------------------------------------------- |
+| `variant` | No       | A built-in or registered name. Defaults to `neutral`.                                           |
+| `icon`    | No       | A lowercase [Lucide icon](https://lucide.dev/icons/) name, such as `check`. Decorative in HTML. |
+
+The body must be nonempty plain text.
+
+## HTML, Markdown, and agents
+
+HTML renders a styled `<span>` with the visible label. Markdown keeps the label inline, so an agent receives the status or platform name without relying on color or an icon. There is no JavaScript behavior; the label remains readable without CSS.