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

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

@@ -0,0 +1,57 @@
+---
+id: guide.component.breadcrumbs
+title: Breadcrumbs
+summary: Show where a page sits in the configured navigation hierarchy.
+type: reference
+area: appearance
+subarea: appearance-navigation
+canonical: /author/components/breadcrumbs
+---
+
+# Breadcrumbs
+
+> 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) > Customize > Navigation > Breadcrumbs
+
+**Updated: 2026-10-26.**
+
+Breadcrumbs are built into site navigation. Shoalrun generates them from the [navigation tree](https://www.shoalrun.com/author/navigation.md). Place a page under its intended groups in navigation; there is no `<Breadcrumbs>` tag to repeat in each MDX file.
+
+## Configuration
+
+This abbreviated navigation puts Breadcrumbs under the Customize and Navigation groups. Those labels become part of its trail: **Customize / Navigation / Breadcrumbs**.
+
+```yaml title="docs/config/nav.yaml"
+- id: styling
+  label: Customize
+  items:
+    - id: navigation
+      label: Navigation
+      items:
+        - id: navigation-overview
+          doc: guide.navigation-lifecycle
+          label: Overview
+        - id: breadcrumbs
+          doc: guide.component.breadcrumbs
+```
+
+A group without a document has a plain-text label in the trail. An ancestor with a document becomes a link. The current page is shown as text, never as a link to itself. Top-level pages have no trail.
+
+## HTML, Markdown, and agents
+
+HTML puts a breadcrumb navigation region above the page heading. It uses an ordered list and marks the current page with `aria-current="page"`. Links remain ordinary keyboard-accessible links, and the trail works without JavaScript.
+
+Markdown shows the same path near the title. Ancestors with pages link to their Markdown versions. Each [document manifest](https://www.shoalrun.com/documents.json) entry has a `breadcrumbs` array containing ordered labels and any available URLs. An agent can recover the hierarchy without parsing HTML navigation.
+
+## Related reading
+
+### Reference while working
+
+- [Organize site navigation](https://www.shoalrun.com/author/navigation.md) — Place pages in navigation to generate their breadcrumb trails.
+
+### Related topics
+
+- [Organize site navigation](https://www.shoalrun.com/author/navigation.md) — Understand the breadcrumb trails generated from navigation groups.

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

@@ -0,0 +1,131 @@
+---
+id: guide.component.callout
+title: Callouts
+summary: Use built-in callouts or register a type with its own label, tone, and icon.
+type: reference
+area: components
+subarea: components-prose
+canonical: /author/components/callout
+---
+
+# Callouts
+
+> 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 > Callouts
+
+**Updated: 2026-10-26.**
+
+`<Callout>` highlights a short message in the reading flow. Use a type that matches the message's purpose. The type sets the HTML color and decorative icon, while a visible label carries the meaning in both HTML and Markdown.
+
+## Choose a type
+
+Choose a callout type that matches the information readers need to notice.
+
+| Type        | Use it for                                                    |
+| ----------- | ------------------------------------------------------------- |
+| `note`      | Helpful context or a clarification.                           |
+| `tip`       | A practical suggestion that makes a task easier.              |
+| `important` | Information readers must notice to complete a task correctly. |
+| `warning`   | A possible problem readers can avoid.                         |
+| `caution`   | A higher-risk action or consequence that needs extra care.    |
+
+```mdx
+<Callout type="warning">Use a fresh idempotency key for a new payment.</Callout>
+```
+
+> **Note:** The example API is fictional.
+
+> **Tip:** Keep a copy of the response ID for later checks.
+
+> **Important:** Check the selected API version before copying a request.
+
+> **Warning:** A changed idempotency key can create a second payment.
+
+> **Caution:** Review the target environment before deleting data.
+
+## Attributes and defaults
+
+Use these attributes to set the callout type and its visible title.
+
+| Attribute | Required | Meaning                                                                  |
+| --------- | -------- | ------------------------------------------------------------------------ |
+| `type`    | No       | A built-in or registered type. Omitted with no label defaults to `note`. |
+| `label`   | No       | Nonempty literal text that replaces the visible type name.               |
+
+Set both when the message needs a more specific label:
+
+```mdx
+<Callout type="warning" label="Before retrying">Reuse the original idempotency key.</Callout>
+```
+
+> **Before retrying:** Reuse the original idempotency key.
+
+A `label` without a `type` retains the neutral style used by earlier pages. Its label remains visible in Markdown:
+
+```mdx
+<Callout label="Before you begin">Use a draft page while checking examples.</Callout>
+```
+
+> **Before you begin:** Use a draft page while checking examples.
+
+A bare `<Callout>` uses the `note` label and style. Unknown types, unsupported attributes, and empty labels fail the build.
+
+> **Note:** This uses the default note style and label.
+
+## Register a type
+
+Add `callouts.types` to the project config. Each new type needs a `label` and a `tone`. The tone can be one of the five built-in values or a name registered in `callouts.tones`. An optional `icon` names a [Lucide icon](https://lucide.dev/icons/) in lowercase kebab-case. This site's configuration registers an `experiment` type with its own `laboratory` tone:
+
+```yaml filename="docs.config.yaml"
+callouts: { $include: ./config/callouts.yaml }
+```
+
+```yaml filename="config/callouts.yaml"
+tones:
+  laboratory:
+    line: '#087f8c'
+    background: '#e9f8f8'
+    text: '#075c66'
+    dark:
+      line: '#3cb9c4'
+      background: '#0e2a2d'
+      text: '#8fe3ea'
+types:
+  experiment:
+    label: Experiment
+    tone: laboratory
+    icon: flask-conical
+```
+
+Use the registered name in MDX:
+
+```mdx
+<Callout type="experiment">Try this flow in a test environment first.</Callout>
+```
+
+> **Experiment:** Try this flow in a test environment first.
+
+Each custom tone needs `line` (left rule), `background`, and `text` (label and icon), all as hex colors. Multiple types can share a tone.
+
+A tone's `dark` block sets the same three colors for [dark mode](https://www.shoalrun.com/styling/color-modes.md). It is optional on a light-only site. When `theme.mode` is `dark` or `system`, every tone in use needs `dark`, or the build fails. The build checks each tone against the site's [palette](https://www.shoalrun.com/styling/palettes.md) in every mode the site shows. Body text, links, and the label need 4.5:1 against the tone's background.
+
+You can also use `callouts.tones` to replace a built-in tone's colors. The five built-in types have default labels and Lucide icons; you can override their `label`, `tone`, or `icon` in `callouts.types`. A registered type without an icon displays its label without an icon. Icons are decorative and hidden from assistive technology; the label stays in HTML and Markdown. Invalid names, colors, icons, and definitions fail the build.
+
+## HTML, Markdown, and agents
+
+The body accepts ordinary Markdown and supported MDX components. HTML renders a styled blockquote with the visible label and optional icon; Markdown renders a labeled blockquote with the full body. Colors and icons never carry the only meaning, and no browser script is needed. Keep the message short. Use a normal section heading for longer instructions.
+
+The [CSS reference](https://www.shoalrun.com/author/css.md) lists the color tokens for each type. See the [component index](https://www.shoalrun.com/author/components.md) for other supported elements.
+
+## Related reading
+
+### Reference while working
+
+- [CSS and theme reference](https://www.shoalrun.com/author/css.md) — Restyle callout tones with theme tokens.
+
+### Related topics
+
+- [Short definitions](https://www.shoalrun.com/author/components/info-hint.md) — Choose a short optional definition or an explanation visible in the reading path.

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

@@ -0,0 +1,168 @@
+---
+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.**
+
+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.
+
+## Link to one document
+
+```mdx
+<DocCard doc="guide.frontmatter" />
+```
+
+- [Page metadata](https://www.shoalrun.com/author/frontmatter.md)
+
+  Set page identity, publication, and presentation fields before publishing.
+
+The target must be public and available in the current publication: the channel, API version, and language of the page displaying the card. An unknown, draft, or unavailable target stops the build with a diagnostic. There is no automatic fallback to another publication.
+
+## Curate a reading list
+
+Use a curated list when you want to choose exactly which pages readers see and in what order. `DocCards` displays one card for each document ID you supply. For example, this list offers the content guide followed by the templates guide:
+
+```mdx
+<DocCards docs={["guide.content-identity", "guide.templates"]} />
+```
+
+- [Content and stable IDs](https://www.shoalrun.com/author/content.md)
+
+  Give each page a durable identity and publish explicit variants.
+
+- [Templates](https://www.shoalrun.com/author/templates.md)
+
+  Create and edit page starting points, then scaffold drafts from them.
+
+The array controls the order. Duplicate IDs fail validation. An empty array renders “No matching documents.” Set `empty="Your message"` to replace that text. Add an ordinary Markdown heading before a card group when it needs a section title. Cards themselves use list and link semantics rather than inserting heading levels.
+
+`DocCards` can also show cards from a declared relationship. Supply either `docs` or `relation`:
+
+```mdx
+<DocCards relation="next-step" relatedTo="guide.cards" />
+```
+
+| Attribute   | Required               | Meaning                                                         |
+| ----------- | ---------------------- | --------------------------------------------------------------- |
+| `docs`      | For a curated list     | Literal array of unique document IDs in display order.          |
+| `relation`  | For relationship cards | One declared relationship type; cannot be combined with `docs`. |
+| `relatedTo` | No                     | Source document for `relation`; defaults to this page.          |
+| `empty`     | No                     | Message for no results; default is “No matching documents.”     |
+
+Use [RelatedReading](https://www.shoalrun.com/author/components/related-reading.md) when a plain link list grouped by purpose fits better than cards.
+
+## 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.
+
+## Add a Lucide icon
+
+Choose an icon from the [Lucide icon browser](https://lucide.dev/icons/) and put its lowercase name on the target page:
+
+```yaml
+card:
+  icon: book-open
+```
+
+Names use hyphens, such as `book-open`, `credit-card`, `terminal`, or `sliders-horizontal`. The pinned Lucide package supplies the icons at build time. An unknown name or URL fails with a file-specific diagnostic, so typos never silently produce an empty icon. New icons from a later Lucide release need a dependency update first.
+
+The icon appears in every card for that page, including curated lists, collections, and relationship views. It does not change the page heading or sidebar. Omit `card.icon` for a text-only card. Global `frontmatter.defaults.card.icon` and `frontmatter.enforced.card.icon` use the same precedence rules as other card metadata; a page can override a default with another icon name.
+
+Icons are inline SVGs with `aria-hidden="true"` and `focusable="false"`. The visible card title remains the link's accessible name. Icons are decorative, omitted from Markdown, and require no browser JavaScript, font download, or CDN. Only the selected SVG shapes appear in each page. Adjust their color and size with `.doc-card-icon` in `styles/site.css`.
+
+Lucide is open source under the [ISC license](https://lucide.dev/license), with notices for Feather-derived icons. Builds include the package's complete notice at `/assets/lucide-LICENSE.txt`; retain it when deploying the generated site.
+
+## Build a collection
+
+A **collection** automatically finds pages that match your filters and displays them as cards. Use it when the list should follow the site's content, such as all authoring guides or pages associated with a payment operation. Unlike a curated list, you do not have to maintain an array of every matching page ID.
+
+`DocCollection` re-runs its filters during each build. Adding a matching page adds its card on the next build; removing the tag or making that page a draft removes it. A collection does not create pages, change their metadata, or add them to sidebar navigation.
+
+This example displays up to six other guides tagged `authoring`, sorted by title:
+
+```mdx
+<DocCollection type="guide" tag="authoring" orderBy="title" limit={6} />
+```
+
+No matching documents.
+
+| Attribute   | Behavior                                                                                                                                                                        |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`      | Matches the document kind in frontmatter, such as `guide` or `api-reference`.                                                                                                   |
+| `tag`       | Matches a topic label in the target's `tags` array, such as `authoring`.                                                                                                        |
+| `operation` | Membership in its stable `operations` IDs; unknown operation IDs fail.                                                                                                          |
+| `audience`  | Membership in its `audiences` array; this filters metadata and does not grant access.                                                                                           |
+| `orderBy`   | `title` by default, `id`, `date`, or `releaseVersion`. Date sorts newest first; version uses numeric label ordering. Every match needs the chosen field. Stable IDs break ties. |
+| `pin`       | Promotes selected matching pages to the front of the collection, in the given order. Supply a literal array of document IDs.                                                    |
+| `exclude`   | A literal array of IDs to remove. IDs absent from this publication are ignored.                                                                                                 |
+| `limit`     | A positive integer limiting the total, including pinned entries. Write it as an expression, `limit={6}`; the string `limit="6"` fails.                                          |
+| `empty`     | Text to show when no documents match; defaults to “No matching documents.”                                                                                                      |
+
+All supplied filters must match. The current page is excluded. Collections never pull in another channel, version, language, or a nonpublic page. With no filters, a collection lists all other public documents in the current publication.
+
+For example, in the API fixture:
+
+```mdx
+<DocCollection operation="payments.create" pin={["reference.create-payment"]} />
+```
+
+Pinned documents must be visible and satisfy all filters, including exclusions. Invalid pins stop the build. The `pin` and `exclude` arrays require unique document IDs. Collection ordering is deterministic and does not depend on filenames.
+
+## HTML, Markdown, and agents
+
+HTML renders cards and collections as linked previews, with decorative icons when configured. Markdown expands each result into a readable link with its description, status, and relationship reason when present. An agent receives the same destinations and context without relying on the card layout or icons. Both outputs include only public matches from the current publication.
+
+## 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/cards.sections/add-a-lucide-icon.md

@@ -0,0 +1,50 @@
+---
+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.
+
+## Add a Lucide icon
+
+Choose an icon from the [Lucide icon browser](https://lucide.dev/icons/) and put its lowercase name on the target page:
+
+```yaml
+card:
+  icon: book-open
+```
+
+Names use hyphens, such as `book-open`, `credit-card`, `terminal`, or `sliders-horizontal`. The pinned Lucide package supplies the icons at build time. An unknown name or URL fails with a file-specific diagnostic, so typos never silently produce an empty icon. New icons from a later Lucide release need a dependency update first.
+
+The icon appears in every card for that page, including curated lists, collections, and relationship views. It does not change the page heading or sidebar. Omit `card.icon` for a text-only card. Global `frontmatter.defaults.card.icon` and `frontmatter.enforced.card.icon` use the same precedence rules as other card metadata; a page can override a default with another icon name.
+
+Icons are inline SVGs with `aria-hidden="true"` and `focusable="false"`. The visible card title remains the link's accessible name. Icons are decorative, omitted from Markdown, and require no browser JavaScript, font download, or CDN. Only the selected SVG shapes appear in each page. Adjust their color and size with `.doc-card-icon` in `styles/site.css`.
+
+Lucide is open source under the [ISC license](https://lucide.dev/license), with notices for Feather-derived icons. Builds include the package's complete notice at `/assets/lucide-LICENSE.txt`; retain it when deploying the generated site.

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

@@ -0,0 +1,69 @@
+---
+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.
+
+## Build a collection
+
+A **collection** automatically finds pages that match your filters and displays them as cards. Use it when the list should follow the site's content, such as all authoring guides or pages associated with a payment operation. Unlike a curated list, you do not have to maintain an array of every matching page ID.
+
+`DocCollection` re-runs its filters during each build. Adding a matching page adds its card on the next build; removing the tag or making that page a draft removes it. A collection does not create pages, change their metadata, or add them to sidebar navigation.
+
+This example displays up to six other guides tagged `authoring`, sorted by title:
+
+```mdx
+<DocCollection type="guide" tag="authoring" orderBy="title" limit={6} />
+```
+
+No matching documents.
+
+| Attribute   | Behavior                                                                                                                                                                        |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`      | Matches the document kind in frontmatter, such as `guide` or `api-reference`.                                                                                                   |
+| `tag`       | Matches a topic label in the target's `tags` array, such as `authoring`.                                                                                                        |
+| `operation` | Membership in its stable `operations` IDs; unknown operation IDs fail.                                                                                                          |
+| `audience`  | Membership in its `audiences` array; this filters metadata and does not grant access.                                                                                           |
+| `orderBy`   | `title` by default, `id`, `date`, or `releaseVersion`. Date sorts newest first; version uses numeric label ordering. Every match needs the chosen field. Stable IDs break ties. |
+| `pin`       | Promotes selected matching pages to the front of the collection, in the given order. Supply a literal array of document IDs.                                                    |
+| `exclude`   | A literal array of IDs to remove. IDs absent from this publication are ignored.                                                                                                 |
+| `limit`     | A positive integer limiting the total, including pinned entries. Write it as an expression, `limit={6}`; the string `limit="6"` fails.                                          |
+| `empty`     | Text to show when no documents match; defaults to “No matching documents.”                                                                                                      |
+
+All supplied filters must match. The current page is excluded. Collections never pull in another channel, version, language, or a nonpublic page. With no filters, a collection lists all other public documents in the current publication.
+
+For example, in the API fixture:
+
+```mdx
+<DocCollection operation="payments.create" pin={["reference.create-payment"]} />
+```
+
+Pinned documents must be visible and satisfy all filters, including exclusions. Invalid pins stop the build. The `pin` and `exclude` arrays require unique document IDs. Collection ordering is deterministic and does not depend on filenames.

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

@@ -0,0 +1,66 @@
+---
+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.
+
+## Curate a reading list
+
+Use a curated list when you want to choose exactly which pages readers see and in what order. `DocCards` displays one card for each document ID you supply. For example, this list offers the content guide followed by the templates guide:
+
+```mdx
+<DocCards docs={["guide.content-identity", "guide.templates"]} />
+```
+
+- [Content and stable IDs](https://www.shoalrun.com/author/content.md)
+
+  Give each page a durable identity and publish explicit variants.
+
+- [Templates](https://www.shoalrun.com/author/templates.md)
+
+  Create and edit page starting points, then scaffold drafts from them.
+
+The array controls the order. Duplicate IDs fail validation. An empty array renders “No matching documents.” Set `empty="Your message"` to replace that text. Add an ordinary Markdown heading before a card group when it needs a section title. Cards themselves use list and link semantics rather than inserting heading levels.
+
+`DocCards` can also show cards from a declared relationship. Supply either `docs` or `relation`:
+
+```mdx
+<DocCards relation="next-step" relatedTo="guide.cards" />
+```
+
+| Attribute   | Required               | Meaning                                                         |
+| ----------- | ---------------------- | --------------------------------------------------------------- |
+| `docs`      | For a curated list     | Literal array of unique document IDs in display order.          |
+| `relation`  | For relationship cards | One declared relationship type; cannot be combined with `docs`. |
+| `relatedTo` | No                     | Source document for `relation`; defaults to this page.          |
+| `empty`     | No                     | Message for no results; default is “No matching documents.”     |
+
+Use [RelatedReading](https://www.shoalrun.com/author/components/related-reading.md) when a plain link list grouped by purpose fits better than cards.

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

@@ -0,0 +1,37 @@
+---
+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.
+
+## HTML, Markdown, and agents
+
+HTML renders cards and collections as linked previews, with decorative icons when configured. Markdown expands each result into a readable link with its description, status, and relationship reason when present. An agent receives the same destinations and context without relying on the card layout or icons. Both outputs include only public matches from the current publication.

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

@@ -0,0 +1,45 @@
+---
+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.
+
+## Link to one document
+
+```mdx
+<DocCard doc="guide.frontmatter" />
+```
+
+- [Page metadata](https://www.shoalrun.com/author/frontmatter.md)
+
+  Set page identity, publication, and presentation fields before publishing.
+
+The target must be public and available in the current publication: the channel, API version, and language of the page displaying the card. An unknown, draft, or unavailable target stops the build with a diagnostic. There is no automatic fallback to another publication.