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

package/agent-docs/author/recipes.sections/use-recipes-for-task-oriented-how-tos.md

@@ -0,0 +1,52 @@
+---
+id: guide.recipes-overview
+title: Understand ingredients, recipes, and cookbooks
+summary: See how reusable source instructions become complete recipe pages that
+  a cookbook helps readers choose.
+type: explanation
+area: authoring
+subarea: authoring-composition
+canonical: /author/recipes
+---
+
+# Understand ingredients, recipes, and cookbooks
+
+> 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 > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/recipes.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Compose and maintain recipes](https://www.shoalrun.com/author/recipe-drafts.md) — Follow the actual ingredient files and spec that produce Shoalrun's audit recipe.
+
+- [Authoring workflows](https://www.shoalrun.com/cookbooks/authoring.md) — Use complete workflows for Shoalrun documentation work.
+
+- [Welcome email workflows](https://www.shoalrun.com/cookbooks/welcome-email.md) — Try an acceptance check or follow a message ID through delivery and failure handling.
+
+A **recipe** is the complete page someone follows to finish a task. An **ingredient** is a reusable piece of source documentation used to write that page. A **cookbook** is a page that helps readers choose a recipe.
+
+Readers can open a recipe directly. Ingredients help authors maintain instructions shared by several recipes. A cookbook becomes useful when readers need help choosing which complete task to follow.
+
+## Use recipes for task-oriented how-tos
+
+Use the built-in `how-to` template for a task page, or `recipe` when the page should participate in Shoalrun's recipe and cookbook features. Both take a reader from a known starting state to a verifiable result. Give it prerequisites, ordered actions, failure guidance, and a final success check. A recipe can be a short, directly authored page; it does not require ingredients, a YAML composition spec, or a cookbook.
+
+Use the built-in `explanation` template to explain a concept or help readers understand a system. Use a reference page to describe fields, commands, or API behavior. Existing how-tos can keep their current type, stable ID, and route until a deliberate content revision calls for a change. A page's type does not prove its instructions have been tested.
+
+| Writing task                                             | Starting format                          |
+| -------------------------------------------------------- | ---------------------------------------- |
+| Build this site and verify its output                    | A recipe.                                |
+| Explain how the compiler produces HTML and Markdown      | An explanation page.                     |
+| Look up CLI flags or configuration fields                | A reference page.                        |
+| Reuse the same build instructions across several recipes | An ingredient included by those recipes. |
+| Help a reader choose build, audit, or preview            | A cookbook pointing to complete recipes. |
+
+The bundled `shoalrun-recipes` skill follows these choices. See [use the agent skills](https://www.shoalrun.com/contribute/agent-skills.md) for a copyable authoring request.

package/agent-docs/author/recipes.sections/what-changing-an-ingredient-updates.md

@@ -0,0 +1,44 @@
+---
+id: guide.recipes-overview
+title: Understand ingredients, recipes, and cookbooks
+summary: See how reusable source instructions become complete recipe pages that
+  a cookbook helps readers choose.
+type: explanation
+area: authoring
+subarea: authoring-composition
+canonical: /author/recipes
+---
+
+# Understand ingredients, recipes, and cookbooks
+
+> 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 > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/recipes.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Compose and maintain recipes](https://www.shoalrun.com/author/recipe-drafts.md) — Follow the actual ingredient files and spec that produce Shoalrun's audit recipe.
+
+- [Authoring workflows](https://www.shoalrun.com/cookbooks/authoring.md) — Use complete workflows for Shoalrun documentation work.
+
+- [Welcome email workflows](https://www.shoalrun.com/cookbooks/welcome-email.md) — Try an acceptance check or follow a message ID through delivery and failure handling.
+
+A **recipe** is the complete page someone follows to finish a task. An **ingredient** is a reusable piece of source documentation used to write that page. A **cookbook** is a page that helps readers choose a recipe.
+
+Readers can open a recipe directly. Ingredients help authors maintain instructions shared by several recipes. A cookbook becomes useful when readers need help choosing which complete task to follow.
+
+## What changing an ingredient updates
+
+A generated recipe is a snapshot of its ingredients. Editing an ingredient does not immediately change a published recipe. Regenerate the affected recipe, review the changes, and rebuild the site.
+
+Shoalrun's five repository recipes have a maintenance script that updates their snapshots together and a test that detects stale snapshots. The [composition guide](https://www.shoalrun.com/author/recipe-drafts.md) shows that workflow. Other projects can keep generated recipes as drafts and edit them independently.
+
+For example, if the docs build command changes, update the build ingredient once and regenerate the recipes that use it. The cookbook continues pointing to the same published recipe IDs.

package/agent-docs/author/recipes.sections/what-each-file-does.md

@@ -0,0 +1,48 @@
+---
+id: guide.recipes-overview
+title: Understand ingredients, recipes, and cookbooks
+summary: See how reusable source instructions become complete recipe pages that
+  a cookbook helps readers choose.
+type: explanation
+area: authoring
+subarea: authoring-composition
+canonical: /author/recipes
+---
+
+# Understand ingredients, recipes, and cookbooks
+
+> 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 > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/recipes.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Compose and maintain recipes](https://www.shoalrun.com/author/recipe-drafts.md) — Follow the actual ingredient files and spec that produce Shoalrun's audit recipe.
+
+- [Authoring workflows](https://www.shoalrun.com/cookbooks/authoring.md) — Use complete workflows for Shoalrun documentation work.
+
+- [Welcome email workflows](https://www.shoalrun.com/cookbooks/welcome-email.md) — Try an acceptance check or follow a message ID through delivery and failure handling.
+
+A **recipe** is the complete page someone follows to finish a task. An **ingredient** is a reusable piece of source documentation used to write that page. A **cookbook** is a page that helps readers choose a recipe.
+
+Readers can open a recipe directly. Ingredients help authors maintain instructions shared by several recipes. A cookbook becomes useful when readers need help choosing which complete task to follow.
+
+## What each file does
+
+These are real files in this checkout:
+
+| File                                       | What the author puts there                                                              | What it contributes                                                                   |
+| ------------------------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `docs/content/ingredient-build-site.mdx`   | The build command, explanation, required inputs, expected outputs, and a success check. | Reusable source instructions for one step.                                            |
+| `docs/recipe-specs/audit-docs.yaml`        | An ordered list of ingredient files, starting inputs, and the final goal.               | Instructions to the recipe assembler about which steps to copy and how to order them. |
+| `docs/content/recipe-audit-docs.mdx`       | The assembled, reviewed recipe.                                                         | The complete page a person or agent follows.                                          |
+| `docs/config/cookbooks.yaml`               | Choice labels and the published recipe ID for each option.                              | The chooser's options and descriptions.                                               |
+| `docs/content/cookbook-site-workflows.mdx` | An introduction and `<CookbookChooser id="site-checks" />`.                             | The page where readers choose their task.                                             |

package/agent-docs/author/recipes.sections/what-happens-and-when.md

@@ -0,0 +1,45 @@
+---
+id: guide.recipes-overview
+title: Understand ingredients, recipes, and cookbooks
+summary: See how reusable source instructions become complete recipe pages that
+  a cookbook helps readers choose.
+type: explanation
+area: authoring
+subarea: authoring-composition
+canonical: /author/recipes
+---
+
+# Understand ingredients, recipes, and cookbooks
+
+> 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 > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/recipes.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Compose and maintain recipes](https://www.shoalrun.com/author/recipe-drafts.md) — Follow the actual ingredient files and spec that produce Shoalrun's audit recipe.
+
+- [Authoring workflows](https://www.shoalrun.com/cookbooks/authoring.md) — Use complete workflows for Shoalrun documentation work.
+
+- [Welcome email workflows](https://www.shoalrun.com/cookbooks/welcome-email.md) — Try an acceptance check or follow a message ID through delivery and failure handling.
+
+A **recipe** is the complete page someone follows to finish a task. An **ingredient** is a reusable piece of source documentation used to write that page. A **cookbook** is a page that helps readers choose a recipe.
+
+Readers can open a recipe directly. Ingredients help authors maintain instructions shared by several recipes. A cookbook becomes useful when readers need help choosing which complete task to follow.
+
+## What happens, and when
+
+1. **An author prepares ingredients and a recipe spec.** Ingredients contain prose and commands. Their optional `workflow` metadata names the values or artifacts each step needs and produces.
+2. **The author runs `recipe draft`.** The assembler copies ingredient bodies into a new MDX draft, combines identical prerequisites, and writes the declared handoffs and checks. It checks that each named input is available from setup or an earlier step.
+3. **The author reviews and tests the recipe, then publishes it.** A normal site build turns the recipe page into HTML and Markdown. It also builds the cookbook page and its choice list.
+4. **A reader chooses a recipe in the cookbook.** The browser fetches the already-published recipe and displays its instructions. The reader or their agent runs the commands and checks the results.
+
+**Selecting a cookbook option does not assemble ingredients or run a task.** It loads finished recipe content. The cookbook's own introduction and choice descriptions come from its page and configuration.

package/agent-docs/author/related-reading.md

@@ -0,0 +1,143 @@
+---
+id: guide.related-reading
+title: Related reading
+summary: Relationship fields, purposes, ordering, validation, and rendered
+  reading paths.
+type: reference
+area: components
+subarea: components-navigation
+canonical: /author/related-reading
+---
+
+# Related reading
+
+> 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 > Related reading
+
+**Updated: 2026-10-26.**
+
+A relationship is an authored connection between two pages, with a reason to follow the link. Use related reading for prerequisites, next steps, references, and distinctions that help readers choose where to go. The links use stable document IDs and remain in the current publication. For curated cards and filtered collections, see [cards and collections](https://www.shoalrun.com/author/components/cards.md).
+
+## Declare relationships
+
+A **relationship** is an explicit connection between two pages, with a reason to follow the link. For example, a guide can point to the task readers should do next, a prerequisite they should read first, or a useful reference. These connections express your intended reading path; sidebar position and shared operation IDs do not establish that order.
+
+Keep the connections in a central config fragment so pages can display them without repeating the target IDs and reasons in their content:
+
+```yaml title="docs.config.yaml"
+relationships: { $include: ./config/relationships.yaml }
+```
+
+```yaml title="config/relationships.yaml"
+- id: cards-to-output
+  from: guide.related-reading
+  to: guide.output
+  type: next-step
+  reason: Inspect the HTML, Markdown, and manifests produced by the build.
+  order: 10
+```
+
+| Field        | Meaning                                                                                                     |
+| ------------ | ----------------------------------------------------------------------------------------------------------- |
+| `id`         | Unique relationship ID.                                                                                     |
+| `from`, `to` | Stable document IDs.                                                                                        |
+| `type`       | A relationship purpose from the table below.                                                                |
+| `reason`     | Required text explaining why the target is useful.                                                          |
+| `order`      | Optional finite number; smaller values come first, with relationship ID as the tie-breaker. Default is `0`. |
+
+Relationship types describe why a reader should follow the link:
+
+| Type                | Purpose / default group heading                      | Direction              |
+| ------------------- | ---------------------------------------------------- | ---------------------- |
+| `prerequisite`      | Read first — knowledge needed before this page.      | From source to target. |
+| `next-step`         | Next steps — continue the workflow.                  | From source to target. |
+| `reference`         | Reference while working — look up details.           | From source to target. |
+| `advanced`          | Go deeper — explore a more advanced topic.           | From source to target. |
+| `see-also`          | Related topics — parallel or complementary material. | Both directions.       |
+| `not-confused-with` | Often confused with — distinguish two topics.        | Both directions.       |
+
+Declare symmetric pairs only once and write a reason that makes sense from either page. For `not-confused-with`, explain the actual distinction in the reason. A prerequisite target is something to read before the source.
+
+Unknown document IDs, self-links, duplicate IDs, duplicate edges of the same type, and prerequisite cycles within a public publication fail. Different relationship types can connect the same pair. Next-step cycles are allowed for workflows with a return step; provide meaningful reasons.
+
+A relationship is published only where both documents have public variants in the same channel, version, and language. Edges to drafts or unavailable variants are omitted from related reading and the public manifest. A relationship does not publish its target or create a cross-version link.
+
+## Where relationship explanations come from
+
+The **Why they’re connected** text in this site's [documentation explorer](https://www.shoalrun.com/explore.md) comes directly from the relationship's authored `reason` field. Authors maintain that text in `docs/config/relationships.yaml`. The build validates each relationship and publishes its reason in the `relationships` array in `documents.json`. The explorer reads that manifest and displays the explanation.
+
+Opening the graph, selecting a page, or inspecting a matrix cell makes no model calls. The explorer does not infer connections or generate explanations from page content. Relationship types, direction, and reasons come from the declared configuration; page titles and summaries come from document metadata.
+
+Write a reason that tells readers what the connected page helps them do or understand. Prefer a concrete explanation such as “Inspect the HTML, Markdown, and manifests produced by the build” over “These pages are related.” For two-way relationships, write text that works from either page. The `reason` field is required by relationship validation.
+
+To change an explanation, edit its `reason` in the relationship configuration and rebuild the site. The same authored reason is available to humans in related-reading views and to agents through `documents.json`.
+
+## Display related documents
+
+**Related reading** presents centrally maintained connections as lists of links grouped by purpose. **Cards** are a visual presentation for page previews. The same relationship data can drive either presentation; declaring a relationship does not require a card.
+
+Place this under a level-two heading where related reading belongs:
+
+```mdx
+## Related reading
+
+<RelatedReading />
+```
+
+This renders nonempty groups in the order shown in the relationship-type table, with level-three headings. Within each group, links follow `order`, then relationship ID. Each list item uses the target's page title and the relationship reason. Card titles, descriptions, eyebrows, and icons do not change the default link list. Subject lifecycle status remains visible. Titles and URLs come from the target page; maintain only IDs, relationship purposes, and reasons in the central mapping.
+
+To show one kind of relationship under your own heading:
+
+```mdx
+## Next steps
+
+<RelatedReading relation="next-step" />
+```
+
+For optional cards, change the presentation:
+
+```mdx
+<RelatedReading relation="next-step" layout="cards" />
+```
+
+The [RelatedReading component page](https://www.shoalrun.com/author/components/related-reading.md) lists every attribute. `<DocCards relation="next-step" />` remains supported as an explicit card view; `DocCards` also supports curated `docs` arrays. `RelatedReading` accepts relationship queries only.
+
+## Reading paths in section Markdown
+
+A section resource carries the prerequisites and next steps shown in a top-level `<RelatedReading />` view for that page, even when the view appears under a different heading. The added **Page reading path** block names its page-wide scope and retains target titles, reasons, status labels, and Markdown links. Prerequisites come before next steps; each group keeps its configured order. These are authored suggestions, not an inferred linear sequence or proof that prerequisites have been satisfied.
+
+Links already present in the section or repeated page introduction are not copied again. Both list and card views supply the same concise reading-path links. The compiler does not carry other relationship types, views for another `relatedTo` page, or views nested inside tabs, reader sections, or other components into unrelated sections. Nested views remain with their original content and labels. Relationships declared only in config do not appear automatically: display them with `RelatedReading` where readers need them.
+
+Carried links count toward the section's exact byte/token size and its size eligibility. They do not change `standaloneSections` declarations or prove that a section contains every prerequisite. Read the linked prerequisite or full page when the task needs more context.
+
+## Automatic footers
+
+Some links appear without a relationship. The build adds these lists at the end of a page, in HTML and Markdown:
+
+- **Related documentation** links pages that share an operation ID in `operations`.
+- **Related API references** and **Related guides** link a guide or how-to page with the API references named in its `relatedApiReferences`. See [link guides to API references](https://www.shoalrun.com/api-docs/generate.md).
+
+These automatic lists are separate from authored relationships and can appear alongside related reading. They do not establish workflow order.
+
+The current mapping uses explicit document-ID pairs. DITA table imports, external targets, and topic-group shorthand are not supported yet.
+
+## Inspect output and changes
+
+`documents.json` records each page's `cardTargets` (selected stable IDs) and `cardQueries` (collection and relationship selectors, including `RelatedReading` and its layout). Its top-level `relationships` array contains only published edges with their concrete publication variants. There is no separate `relationships.json` artifact in this slice.
+
+A full build re-evaluates every collection and relationship view. Changing a target's title, summary, card metadata, slug, or subjectLifecycle refreshes its referring cards. Adding a matching document changes collection membership on the next build. Card content contributes to the referring page's Markdown digest. The compiler currently rebuilds the whole site; these records are not an incremental build cache.
+
+HTML cards use real links, visible keyboard focus, and responsive columns. The Markdown twin uses a list of links to `.md` targets with equivalent text. Cards need no browser JavaScript. The current scope excludes named collection definitions, relationship frontmatter shorthand, operation/schema graph nodes, inferred relationships, and card images.
+
+## Related reading
+
+### Reference while working
+
+- [RelatedReading](https://www.shoalrun.com/author/components/related-reading.md) — Look up every RelatedReading attribute.
+
+### Often confused with
+
+- [Cards and collections](https://www.shoalrun.com/author/components/cards.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/related-reading.sections/automatic-footers.md

@@ -0,0 +1,35 @@
+---
+id: guide.related-reading
+title: Related reading
+summary: Relationship fields, purposes, ordering, validation, and rendered
+  reading paths.
+type: reference
+area: components
+subarea: components-navigation
+canonical: /author/related-reading
+---
+
+# Related reading
+
+> 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 > Related reading
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/related-reading.md)
+
+A relationship is an authored connection between two pages, with a reason to follow the link. Use related reading for prerequisites, next steps, references, and distinctions that help readers choose where to go. The links use stable document IDs and remain in the current publication. For curated cards and filtered collections, see [cards and collections](https://www.shoalrun.com/author/components/cards.md).
+
+## Automatic footers
+
+Some links appear without a relationship. The build adds these lists at the end of a page, in HTML and Markdown:
+
+- **Related documentation** links pages that share an operation ID in `operations`.
+- **Related API references** and **Related guides** link a guide or how-to page with the API references named in its `relatedApiReferences`. See [link guides to API references](https://www.shoalrun.com/api-docs/generate.md).
+
+These automatic lists are separate from authored relationships and can appear alongside related reading. They do not establish workflow order.
+
+The current mapping uses explicit document-ID pairs. DITA table imports, external targets, and topic-group shorthand are not supported yet.

package/agent-docs/author/related-reading.sections/declare-relationships.md

@@ -0,0 +1,68 @@
+---
+id: guide.related-reading
+title: Related reading
+summary: Relationship fields, purposes, ordering, validation, and rendered
+  reading paths.
+type: reference
+area: components
+subarea: components-navigation
+canonical: /author/related-reading
+---
+
+# Related reading
+
+> 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 > Related reading
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/related-reading.md)
+
+A relationship is an authored connection between two pages, with a reason to follow the link. Use related reading for prerequisites, next steps, references, and distinctions that help readers choose where to go. The links use stable document IDs and remain in the current publication. For curated cards and filtered collections, see [cards and collections](https://www.shoalrun.com/author/components/cards.md).
+
+## Declare relationships
+
+A **relationship** is an explicit connection between two pages, with a reason to follow the link. For example, a guide can point to the task readers should do next, a prerequisite they should read first, or a useful reference. These connections express your intended reading path; sidebar position and shared operation IDs do not establish that order.
+
+Keep the connections in a central config fragment so pages can display them without repeating the target IDs and reasons in their content:
+
+```yaml title="docs.config.yaml"
+relationships: { $include: ./config/relationships.yaml }
+```
+
+```yaml title="config/relationships.yaml"
+- id: cards-to-output
+  from: guide.related-reading
+  to: guide.output
+  type: next-step
+  reason: Inspect the HTML, Markdown, and manifests produced by the build.
+  order: 10
+```
+
+| Field        | Meaning                                                                                                     |
+| ------------ | ----------------------------------------------------------------------------------------------------------- |
+| `id`         | Unique relationship ID.                                                                                     |
+| `from`, `to` | Stable document IDs.                                                                                        |
+| `type`       | A relationship purpose from the table below.                                                                |
+| `reason`     | Required text explaining why the target is useful.                                                          |
+| `order`      | Optional finite number; smaller values come first, with relationship ID as the tie-breaker. Default is `0`. |
+
+Relationship types describe why a reader should follow the link:
+
+| Type                | Purpose / default group heading                      | Direction              |
+| ------------------- | ---------------------------------------------------- | ---------------------- |
+| `prerequisite`      | Read first — knowledge needed before this page.      | From source to target. |
+| `next-step`         | Next steps — continue the workflow.                  | From source to target. |
+| `reference`         | Reference while working — look up details.           | From source to target. |
+| `advanced`          | Go deeper — explore a more advanced topic.           | From source to target. |
+| `see-also`          | Related topics — parallel or complementary material. | Both directions.       |
+| `not-confused-with` | Often confused with — distinguish two topics.        | Both directions.       |
+
+Declare symmetric pairs only once and write a reason that makes sense from either page. For `not-confused-with`, explain the actual distinction in the reason. A prerequisite target is something to read before the source.
+
+Unknown document IDs, self-links, duplicate IDs, duplicate edges of the same type, and prerequisite cycles within a public publication fail. Different relationship types can connect the same pair. Next-step cycles are allowed for workflows with a return step; provide meaningful reasons.
+
+A relationship is published only where both documents have public variants in the same channel, version, and language. Edges to drafts or unavailable variants are omitted from related reading and the public manifest. A relationship does not publish its target or create a cross-version link.

package/agent-docs/author/related-reading.sections/display-related-documents.md

@@ -0,0 +1,54 @@
+---
+id: guide.related-reading
+title: Related reading
+summary: Relationship fields, purposes, ordering, validation, and rendered
+  reading paths.
+type: reference
+area: components
+subarea: components-navigation
+canonical: /author/related-reading
+---
+
+# Related reading
+
+> 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 > Related reading
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/related-reading.md)
+
+A relationship is an authored connection between two pages, with a reason to follow the link. Use related reading for prerequisites, next steps, references, and distinctions that help readers choose where to go. The links use stable document IDs and remain in the current publication. For curated cards and filtered collections, see [cards and collections](https://www.shoalrun.com/author/components/cards.md).
+
+## Display related documents
+
+**Related reading** presents centrally maintained connections as lists of links grouped by purpose. **Cards** are a visual presentation for page previews. The same relationship data can drive either presentation; declaring a relationship does not require a card.
+
+Place this under a level-two heading where related reading belongs:
+
+```mdx
+## Related reading
+
+<RelatedReading />
+```
+
+This renders nonempty groups in the order shown in the relationship-type table, with level-three headings. Within each group, links follow `order`, then relationship ID. Each list item uses the target's page title and the relationship reason. Card titles, descriptions, eyebrows, and icons do not change the default link list. Subject lifecycle status remains visible. Titles and URLs come from the target page; maintain only IDs, relationship purposes, and reasons in the central mapping.
+
+To show one kind of relationship under your own heading:
+
+```mdx
+## Next steps
+
+<RelatedReading relation="next-step" />
+```
+
+For optional cards, change the presentation:
+
+```mdx
+<RelatedReading relation="next-step" layout="cards" />
+```
+
+The [RelatedReading component page](https://www.shoalrun.com/author/components/related-reading.md) lists every attribute. `<DocCards relation="next-step" />` remains supported as an explicit card view; `DocCards` also supports curated `docs` arrays. `RelatedReading` accepts relationship queries only.

package/agent-docs/author/related-reading.sections/inspect-output-and-changes.md

@@ -0,0 +1,32 @@
+---
+id: guide.related-reading
+title: Related reading
+summary: Relationship fields, purposes, ordering, validation, and rendered
+  reading paths.
+type: reference
+area: components
+subarea: components-navigation
+canonical: /author/related-reading
+---
+
+# Related reading
+
+> 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 > Related reading
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/related-reading.md)
+
+A relationship is an authored connection between two pages, with a reason to follow the link. Use related reading for prerequisites, next steps, references, and distinctions that help readers choose where to go. The links use stable document IDs and remain in the current publication. For curated cards and filtered collections, see [cards and collections](https://www.shoalrun.com/author/components/cards.md).
+
+## Inspect output and changes
+
+`documents.json` records each page's `cardTargets` (selected stable IDs) and `cardQueries` (collection and relationship selectors, including `RelatedReading` and its layout). Its top-level `relationships` array contains only published edges with their concrete publication variants. There is no separate `relationships.json` artifact in this slice.
+
+A full build re-evaluates every collection and relationship view. Changing a target's title, summary, card metadata, slug, or subjectLifecycle refreshes its referring cards. Adding a matching document changes collection membership on the next build. Card content contributes to the referring page's Markdown digest. The compiler currently rebuilds the whole site; these records are not an incremental build cache.
+
+HTML cards use real links, visible keyboard focus, and responsive columns. The Markdown twin uses a list of links to `.md` targets with equivalent text. Cards need no browser JavaScript. The current scope excludes named collection definitions, relationship frontmatter shorthand, operation/schema graph nodes, inferred relationships, and card images.

package/agent-docs/author/related-reading.sections/reading-paths-in-section-markdown.md

@@ -0,0 +1,32 @@
+---
+id: guide.related-reading
+title: Related reading
+summary: Relationship fields, purposes, ordering, validation, and rendered
+  reading paths.
+type: reference
+area: components
+subarea: components-navigation
+canonical: /author/related-reading
+---
+
+# Related reading
+
+> 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 > Related reading
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/related-reading.md)
+
+A relationship is an authored connection between two pages, with a reason to follow the link. Use related reading for prerequisites, next steps, references, and distinctions that help readers choose where to go. The links use stable document IDs and remain in the current publication. For curated cards and filtered collections, see [cards and collections](https://www.shoalrun.com/author/components/cards.md).
+
+## Reading paths in section Markdown
+
+A section resource carries the prerequisites and next steps shown in a top-level `<RelatedReading />` view for that page, even when the view appears under a different heading. The added **Page reading path** block names its page-wide scope and retains target titles, reasons, status labels, and Markdown links. Prerequisites come before next steps; each group keeps its configured order. These are authored suggestions, not an inferred linear sequence or proof that prerequisites have been satisfied.
+
+Links already present in the section or repeated page introduction are not copied again. Both list and card views supply the same concise reading-path links. The compiler does not carry other relationship types, views for another `relatedTo` page, or views nested inside tabs, reader sections, or other components into unrelated sections. Nested views remain with their original content and labels. Relationships declared only in config do not appear automatically: display them with `RelatedReading` where readers need them.
+
+Carried links count toward the section's exact byte/token size and its size eligibility. They do not change `standaloneSections` declarations or prove that a section contains every prerequisite. Read the linked prerequisite or full page when the task needs more context.

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

@@ -0,0 +1,34 @@
+---
+id: guide.related-reading
+title: Related reading
+summary: Relationship fields, purposes, ordering, validation, and rendered
+  reading paths.
+type: reference
+area: components
+subarea: components-navigation
+canonical: /author/related-reading
+---
+
+# Related reading
+
+> 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 > Related reading
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/related-reading.md)
+
+A relationship is an authored connection between two pages, with a reason to follow the link. Use related reading for prerequisites, next steps, references, and distinctions that help readers choose where to go. The links use stable document IDs and remain in the current publication. For curated cards and filtered collections, see [cards and collections](https://www.shoalrun.com/author/components/cards.md).
+
+## Related reading
+
+### Reference while working
+
+- [RelatedReading](https://www.shoalrun.com/author/components/related-reading.md) — Look up every RelatedReading attribute.
+
+### Often confused with
+
+- [Cards and collections](https://www.shoalrun.com/author/components/cards.md) — Related reading follows authored relationships with reasons; cards and collections show pages you pick by ID or filter by metadata.