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

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

@@ -0,0 +1,147 @@
+---
+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-27.**
+
+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.
+
+## HTML, Markdown, and agents
+
+HTML and Markdown present the declared relationships with their authored reasons and links to available pages. Card layout adds previews; an agent still receives links and explanations without operating a browser control. Markdown destinations point to the corresponding Markdown pages. Section extracts carry eligible prerequisite and next-step links as described below. These links let an agent recover the reading path from part of a page.
+
+## 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-27.**
+
+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-27.**
+
+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-27.**
+
+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/html-markdown-and-agents.md

@@ -0,0 +1,28 @@
+---
+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-27.**
+
+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).
+
+## HTML, Markdown, and agents
+
+HTML and Markdown present the declared relationships with their authored reasons and links to available pages. Card layout adds previews; an agent still receives links and explanations without operating a browser control. Markdown destinations point to the corresponding Markdown pages. Section extracts carry eligible prerequisite and next-step links as described below. These links let an agent recover the reading path from part of a page.

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-27.**
+
+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-27.**
+
+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-27.**
+
+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.

package/agent-docs/author/related-reading.sections/where-relationship-explanations-come-from.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-27.**
+
+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).
+
+## 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`.

package/agent-docs/author/release-notes.md

@@ -0,0 +1,153 @@
+---
+id: guide.release-notes
+title: Write release notes and changelog entries
+summary: Write flexible release summaries and changelog entries identified by
+  date or version.
+type: how-to
+area: project
+subarea: project-releases
+canonical: /author/release-notes
+---
+
+# Write release notes and changelog entries
+
+> 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 release notes
+
+**Updated: 2026-10-26.**
+
+Release notes and changelog entries serve different reading needs. A **release note** summarizes a named release, quarter, or other period. A **changelog entry** records a change identified by date, release version, or both. Both are ordinary Markdown or MDX pages with HTML and Markdown outputs and stable IDs.
+
+## Write a release note
+
+Use `type: release-note`. Its title and content define the scope; neither a date nor a release version is required. This example covers a quarter without claiming one publication day:
+
+```yaml title="content/releases/q3-summary.mdx"
+---
+id: release.q3-summary
+title: Q3 2026 summary
+summary: Changes grouped for the quarter.
+type: release-note
+slug: /releases/q3-summary
+channel: production
+version: current
+access: { policy: public }
+---
+```
+
+`channel` and `version` must name an enabled publication, or come from [global frontmatter](https://www.shoalrun.com/author/frontmatter.md). A note for one release can instead use `releaseVersion: "2.4"` and a version in its title. `releaseVersion` identifies the product release; the ordinary `version` field selects a documentation publication. The two fields are independent. Add `date` only when the note has a meaningful publication date.
+
+## Write a changelog entry
+
+Use `type: changelog-entry` and identify the change with `date`, `releaseVersion`, or both. The project sets which field is required. The default accepts either. A date must be a real `YYYY-MM-DD` calendar date; a release version must be nonempty text.
+
+```yaml title="content/changelog/example.mdx"
+---
+id: change.example
+title: Example change
+summary: A short description of the change.
+type: changelog-entry
+date: 2026-09-24
+slug: /changelog/example
+channel: production
+version: current
+access: { policy: public }
+tags: [api-reference]
+---
+```
+
+The build shows supplied dates and release versions on pages and cards, and includes them in Markdown twins. Dated changelog entries show their publication date without a separate Updated label in the page header or Markdown body. Revision dates remain in the document manifest and configured Markdown metadata. This site's Markdown metadata also projects the date and release version when present.
+
+### Set the identifier rule
+
+Configure `frontmatter.changelogIdentifier` in project config:
+
+```yaml title="docs.config.yaml"
+frontmatter:
+  changelogIdentifier: either
+```
+
+| Value     | Required on each changelog entry             |
+| --------- | -------------------------------------------- |
+| `either`  | A date, a release version, or both. Default. |
+| `date`    | A date. A release version is optional.       |
+| `version` | A release version. A date is optional.       |
+
+This rule does not apply to release notes. It also does not change the documentation publication's `version` axis.
+
+## Describe what changed
+
+On a `changelog-entry`, add an optional `change` block to distinguish an editorial correction from a changed procedure or behavior. This fictional example describes a breaking API change:
+
+```yaml
+change:
+  kind: breaking
+  affects: [reference.create-payment, guide.create-payment]
+  migration: guide.migrate-payments
+```
+
+Replace these IDs with public pages in the entry's channel, version, and language. Use stable IDs without the `doc:` prefix. Targets resolve to their current titles and URLs. Missing, draft, self, and other-publication targets fail the build; external URLs and references to removed pages are not supported in this increment.
+
+| Field       | Required | Meaning                                                                                                       |
+| ----------- | -------- | ------------------------------------------------------------------------------------------------------------- |
+| `kind`      | Yes      | One author-declared classification from the table below.                                                      |
+| `affects`   | Yes      | Nonempty list of unique document IDs that describe the affected subjects or instructions. Order is preserved. |
+| `migration` | No       | Document ID of the guide explaining how to adapt.                                                             |
+
+| Kind        | Use when                                                                                     |
+| ----------- | -------------------------------------------------------------------------------------------- |
+| `editorial` | Correcting wording or presentation without changing the documented instructions or behavior. |
+| `procedure` | Changing instructions, setup steps, or a recommended workflow.                               |
+| `behavior`  | Describing a feature or behavior change that the author has not classified as breaking.      |
+| `breaking`  | Existing clients or workflows need adaptation because of the change.                         |
+
+Choose the kind deliberately and explain scope and limitations in the entry body. `behavior` is not a compiler guarantee of compatibility. A missing migration link does not mean migration is unnecessary. When one release contains several distinct changes, agree on the grouping before drafting: one combined entry with clearly scoped sections, or separate entries collected in a release note. Use one `change` classification only when it accurately describes the combined entry; otherwise leave the entry unclassified and explain each change in its body.
+
+`change` is page-specific: global defaults and enforced metadata cannot set it. It is accepted only on `changelog-entry` pages, not release summaries or ordinary guides. Unknown keys fail. Use the entry's existing `date` and `releaseVersion` fields for its date and release label; this block does not add an effective-date schedule or prove deployment.
+
+HTML, full Markdown, and every published section of the entry show an **Authored change** notice with the kind, affected pages, and migration link when supplied. HTML links open pages; Markdown links open their twins. The corresponding `documents.json` record includes `change.kind`, resolved `change.affects` targets, and optional `change.migration`. Each target has `id`, `title`, `url`, and `markdownUrl`; URLs include the publication and base path. The entry's manifest variant supplies its publication scope.
+
+Entries without `change` remain published and discoverable. Treat them as unclassified, not nonbreaking. The build checks metadata and references; it does not verify the classification or infer a breaking change from a changed digest. There is no separate semantic feed or automatic annotation of affected pages in this increment. Fetch an entry's Markdown to read its explanation.
+
+## Collect updates
+
+For a chronological changelog, put this on an authored page:
+
+```mdx
+<DocCollection type="changelog-entry" orderBy="date" />
+```
+
+For a version-led changelog, use `orderBy="releaseVersion"`. Version ordering compares labels with numeric parts, so keep one consistent version scheme. Either ordered collection fails if a matching entry lacks its sort field. When entries mix dates and versions, curate the sequence with `<DocCards docs={["change.one", "change.two"]} />`.
+
+Collections use the page's channel, documentation version, and language. Draft entries stay out of public builds. Stable IDs break ties. `limit`, `exclude`, and `pin` provide editorial control.
+
+To roll changes into a release note, add a shared tag to entries and filter by it:
+
+```mdx
+<DocCollection type="changelog-entry" tag="api-reference" orderBy="date" />
+```
+
+Release notes can link to entries, include a filtered collection, or stand alone. RSS feeds and blog archives remain future work.
+
+## Check the published entries
+
+Build the site and open the note or changelog page in HTML and Markdown. Confirm its release scope, date or version, and collection links match the change you are documenting. If the page is missing, check its public access and enabled publication. Keep existing IDs and routes when revising an entry, and set `updated` to the edit date.
+
+## Related reading
+
+### Reference while working
+
+- [Cards and collections](https://www.shoalrun.com/author/components/cards.md) — Filter and order a collection of changelog entries.
+
+- [Page metadata](https://www.shoalrun.com/author/frontmatter.md) — Look up the date and releaseVersion fields that order entries.
+
+### Related topics
+
+- [Changelog](https://www.shoalrun.com/changelog.md) — Write dated entries and collect them with the built-in components.
+
+### Often confused with
+
+- [Use Git branches for separate docs sites](https://www.shoalrun.com/publish/revisions.md) — Release notes tell readers what changed; release revisions choose which Git revision of the docs to build and deploy.