npm - @shoalrun/cli - Versions diffs - 0.1.0-alpha.11 → 0.1.0-alpha.13 - Mend

@shoalrun/cli 0.1.0-alpha.11 → 0.1.0-alpha.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (602) hide show

package/agent-docs/author/navigation.sections/reach-navigation-while-reading.md CHANGED Viewed

@@ -14,9 +14,9 @@ canonical: /author/navigation
 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 > Overview
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Navigation > Overview
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 Parent page: [Full Markdown page](/author/navigation.md)

package/agent-docs/author/navigation.sections/related-reading.md CHANGED Viewed

@@ -14,9 +14,9 @@ canonical: /author/navigation
 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 > Overview
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Navigation > Overview
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 Parent page: [Full Markdown page](/author/navigation.md)

package/agent-docs/author/navigation.sections/split-navigation-into-tabs.md CHANGED Viewed

@@ -14,9 +14,9 @@ canonical: /author/navigation
 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 > Overview
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Navigation > Overview
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 Parent page: [Full Markdown page](/author/navigation.md)

package/agent-docs/author/navigation.sections/subject-lifecycle-labels.md CHANGED Viewed

@@ -14,9 +14,9 @@ canonical: /author/navigation
 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 > Overview
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Navigation > Overview
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 Parent page: [Full Markdown page](/author/navigation.md)

package/agent-docs/author/recipe-drafts.md CHANGED Viewed

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Compose and maintain recipes
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Use ingredients when several recipes share instructions you want to maintain in one place. This guide follows Shoalrun's **Build and audit this documentation site** recipe from its source files to its published page.
@@ -49,18 +49,18 @@ language: en
 access: { policy: public }
 workflow:
   inputs:
-    frameworkCli: The CLI compiled from this checkout.
+    frameworkCli: The pinned Shoalrun package installed for this site.
   outputs:
     builtSite: The successful site build at docs/dist.
   prerequisites:
-    - Run commands from the Shoalrun repository root.
+    - Run commands from the documentation repository root.
   check: "The build reports status: ok."
 ---
-Use the compiled CLI to build the documentation:
+Use the installed CLI to build the documentation:
 ```sh
-node framework/dist/cli.js build docs/docs.config.yaml docs/dist
+npx --no-install shoalrun build docs/docs.config.yaml docs/dist
 ```
 If the build fails, fix the named source or configuration issue and rerun it.
@@ -90,7 +90,7 @@ title: Build and audit this documentation site
 summary: Build current documentation and run the configured audits.
 slug: /recipes/audit-docs
 inputs:
-  repositoryCheckout: A local Shoalrun checkout with dependencies installed.
+  repositoryCheckout: The documentation repository and its package lockfile.
   DOC_ID: Set the stable ID of the page you want to check.
 ingredients:
   - ../content/ingredient-compile-framework.mdx
@@ -100,17 +100,17 @@ ingredients:
 outcome: The build succeeds, both page formats exist, and configured audits pass.
 ```
-Paths are relative to this spec file. The initial `inputs` are available before the first ingredient. The compile ingredient produces `frameworkCli`; the build ingredient requires it and produces `builtSite`; the artifact-check ingredient requires that build and `DOC_ID`.
+Paths are relative to this spec file. The initial `inputs` are available before the first ingredient. The installation ingredient produces `frameworkCli`; the build ingredient requires it and produces `builtSite`; the artifact-check ingredient requires that build and `DOC_ID`.
 The assembler rejects a missing input, repeated output name, repeated ingredient ID, or publication mismatch. It does not choose an order for you or verify that an output has the described value. The `outcome` is the final check for the complete recipe; omitting it leaves a prompt for the author to complete.
 ## 3. Generate a draft and review it
-From this repository's root, compile the CLI and preview the draft using the existing spec:
+This example uses Shoalrun's documentation repository and its recipe sources. From that repository's root, install its dependencies and preview a draft:
 ```sh
-npm --prefix framework run build
-node framework/dist/cli.js recipe draft \
+npm ci
+npx --no-install shoalrun recipe draft \
   --config docs/docs.config.yaml \
   --spec docs/recipe-specs/audit-docs.yaml \
   --out /tmp/shoalrun-audit-recipe.mdx --check
@@ -139,7 +139,7 @@ This repository maintains five recipes from specs under `docs/recipe-specs/`. Th
 After reviewing ingredient or spec changes, run:
 ```sh
-node framework/scripts/build-shoalrun-recipes.mjs --write
+node scripts/build-shoalrun-recipes.mjs --write
 git diff -- docs/content/recipe-*.mdx
 npm run docs:build
 npm run agent-docs:build
@@ -150,19 +150,19 @@ The script replaces the five recipe bodies with their compositions and related-r
 To check freshness without changing files:
 ```sh
-node framework/scripts/build-shoalrun-recipes.mjs --check
+node scripts/build-shoalrun-recipes.mjs --check
 ```
 The test suite runs that check too. General `recipe draft` output has no automatic synchronization: it is an editable snapshot. The maintenance script above is this repository's explicit workflow for keeping its published recipes in sync.
 ## Start an ingredient from an API example
-`ingredient draft` creates starting material from one configured outgoing API operation and a named request example. For the included notification fixture:
+`ingredient draft` creates starting material from one configured outgoing API operation and a named request example. From a project with Shoalrun installed, use the bundled notification example:
 ```sh
-node framework/dist/cli.js ingredient draft \
-  --config framework/example-configs/notifications/docs.config.yaml \
-  --spec framework/example-configs/notifications/ingredient-specs/queue-welcome-email.yaml \
+npx --no-install shoalrun ingredient draft \
+  --config node_modules/@shoalrun/cli/example-configs/notifications/docs.config.yaml \
+  --spec node_modules/@shoalrun/cli/example-configs/notifications/ingredient-specs/queue-welcome-email.yaml \
   --out /tmp/shoalrun-email-ingredient.mdx --check
 ```

package/agent-docs/author/recipe-drafts.sections/1-write-one-reusable-step.md CHANGED Viewed

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Compose and maintain recipes
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/recipe-drafts.md)
@@ -51,18 +51,18 @@ language: en
 access: { policy: public }
 workflow:
   inputs:
-    frameworkCli: The CLI compiled from this checkout.
+    frameworkCli: The pinned Shoalrun package installed for this site.
   outputs:
     builtSite: The successful site build at docs/dist.
   prerequisites:
-    - Run commands from the Shoalrun repository root.
+    - Run commands from the documentation repository root.
   check: "The build reports status: ok."
 ---
-Use the compiled CLI to build the documentation:
+Use the installed CLI to build the documentation:
 ```sh
-node framework/dist/cli.js build docs/docs.config.yaml docs/dist
+npx --no-install shoalrun build docs/docs.config.yaml docs/dist
 ```
 If the build fails, fix the named source or configuration issue and rerun it.

package/agent-docs/author/recipe-drafts.sections/2-list-the-steps-for-one-complete-goal.md CHANGED Viewed

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Compose and maintain recipes
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/recipe-drafts.md)
@@ -45,7 +45,7 @@ title: Build and audit this documentation site
 summary: Build current documentation and run the configured audits.
 slug: /recipes/audit-docs
 inputs:
-  repositoryCheckout: A local Shoalrun checkout with dependencies installed.
+  repositoryCheckout: The documentation repository and its package lockfile.
   DOC_ID: Set the stable ID of the page you want to check.
 ingredients:
   - ../content/ingredient-compile-framework.mdx
@@ -55,6 +55,6 @@ ingredients:
 outcome: The build succeeds, both page formats exist, and configured audits pass.
 ```
-Paths are relative to this spec file. The initial `inputs` are available before the first ingredient. The compile ingredient produces `frameworkCli`; the build ingredient requires it and produces `builtSite`; the artifact-check ingredient requires that build and `DOC_ID`.
+Paths are relative to this spec file. The initial `inputs` are available before the first ingredient. The installation ingredient produces `frameworkCli`; the build ingredient requires it and produces `builtSite`; the artifact-check ingredient requires that build and `DOC_ID`.
 The assembler rejects a missing input, repeated output name, repeated ingredient ID, or publication mismatch. It does not choose an order for you or verify that an output has the described value. The `outcome` is the final check for the complete recipe; omitting it leaves a prompt for the author to complete.

package/agent-docs/author/recipe-drafts.sections/3-generate-a-draft-and-review-it.md CHANGED Viewed

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Compose and maintain recipes
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/recipe-drafts.md)
@@ -36,11 +36,11 @@ See [templates](https://www.shoalrun.com/author/templates.md) for their outlines
 ## 3. Generate a draft and review it
-From this repository's root, compile the CLI and preview the draft using the existing spec:
+This example uses Shoalrun's documentation repository and its recipe sources. From that repository's root, install its dependencies and preview a draft:
 ```sh
-npm --prefix framework run build
-node framework/dist/cli.js recipe draft \
+npm ci
+npx --no-install shoalrun recipe draft \
   --config docs/docs.config.yaml \
   --spec docs/recipe-specs/audit-docs.yaml \
   --out /tmp/shoalrun-audit-recipe.mdx --check

package/agent-docs/author/recipe-drafts.sections/4-maintain-shoalrun-s-published-recipe-snapshots.md CHANGED Viewed

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Compose and maintain recipes
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/recipe-drafts.md)
@@ -49,7 +49,7 @@ This repository maintains five recipes from specs under `docs/recipe-specs/`. Th
 After reviewing ingredient or spec changes, run:
 ```sh
-node framework/scripts/build-shoalrun-recipes.mjs --write
+node scripts/build-shoalrun-recipes.mjs --write
 git diff -- docs/content/recipe-*.mdx
 npm run docs:build
 npm run agent-docs:build
@@ -60,7 +60,7 @@ The script replaces the five recipe bodies with their compositions and related-r
 To check freshness without changing files:
 ```sh
-node framework/scripts/build-shoalrun-recipes.mjs --check
+node scripts/build-shoalrun-recipes.mjs --check
 ```
 The test suite runs that check too. General `recipe draft` output has no automatic synchronization: it is an editable snapshot. The maintenance script above is this repository's explicit workflow for keeping its published recipes in sync.

package/agent-docs/author/recipe-drafts.sections/related-reading.md CHANGED Viewed

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Compose and maintain recipes
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/recipe-drafts.md)

package/agent-docs/author/recipe-drafts.sections/start-an-ingredient-from-an-api-example.md CHANGED Viewed

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Compose and maintain recipes
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/recipe-drafts.md)
@@ -36,12 +36,12 @@ See [templates](https://www.shoalrun.com/author/templates.md) for their outlines
 ## Start an ingredient from an API example
-`ingredient draft` creates starting material from one configured outgoing API operation and a named request example. For the included notification fixture:
+`ingredient draft` creates starting material from one configured outgoing API operation and a named request example. From a project with Shoalrun installed, use the bundled notification example:
 ```sh
-node framework/dist/cli.js ingredient draft \
-  --config framework/example-configs/notifications/docs.config.yaml \
-  --spec framework/example-configs/notifications/ingredient-specs/queue-welcome-email.yaml \
+npx --no-install shoalrun ingredient draft \
+  --config node_modules/@shoalrun/cli/example-configs/notifications/docs.config.yaml \
+  --spec node_modules/@shoalrun/cli/example-configs/notifications/ingredient-specs/queue-welcome-email.yaml \
   --out /tmp/shoalrun-email-ingredient.mdx --check
 ```

package/agent-docs/author/recipes.md CHANGED Viewed

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 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.
@@ -43,7 +43,7 @@ The bundled `shoalrun-recipes` skill follows these choices. See [use the agent s
 Suppose you need two sets of instructions:
-- **Build and check a page.** Compile the CLI, build the docs, and check the HTML and Markdown files.
+- **Build and check a page.** Install the dependencies, build the docs, and check the HTML and Markdown files.
 - **Build and audit the site.** Do those same three steps, then run the project audits.
 Both recipes need the same build instructions. We keep those instructions in ingredient files and use them in both recipe specs:
@@ -52,11 +52,11 @@ Both recipes need the same build instructions. We keep those instructions in ing
 The compile, build, and artifact-check ingredients are used in both recipes. The build-and-audit recipe also includes the audit ingredient. These arrows describe authoring reuse; they do not run commands.
-[View Two recipes reuse the same source instructions diagram](https://www.shoalrun.com/assets/diagrams/mermaid-62592d6197a75626c36a-light.svg)
+[View Two recipes reuse the same source instructions diagram](https://www.shoalrun.com/assets/diagrams/mermaid-c05dd546346549597149-light.svg)
 ```mermaid
 flowchart TD
- shared["Shared ingredients<br/>Compile CLI → Build docs → Check artifacts"]
+ shared["Shared ingredients<br/>Install dependencies → Build docs → Check artifacts"]
  audit["Audit ingredient<br/>Run project audits"]
  build_recipe["Recipe page<br/>Build and check a page"]
  audit_recipe["Recipe page<br/>Build and audit the site"]

package/agent-docs/author/recipes.sections/how-agents-use-this.md CHANGED Viewed

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/recipes.md)

package/agent-docs/author/recipes.sections/one-example-from-shoalrun.md CHANGED Viewed

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/recipes.md)
@@ -39,7 +39,7 @@ Readers can open a recipe directly. Ingredients help authors maintain instructio
 Suppose you need two sets of instructions:
-- **Build and check a page.** Compile the CLI, build the docs, and check the HTML and Markdown files.
+- **Build and check a page.** Install the dependencies, build the docs, and check the HTML and Markdown files.
 - **Build and audit the site.** Do those same three steps, then run the project audits.
 Both recipes need the same build instructions. We keep those instructions in ingredient files and use them in both recipe specs:
@@ -48,11 +48,11 @@ Both recipes need the same build instructions. We keep those instructions in ing
 The compile, build, and artifact-check ingredients are used in both recipes. The build-and-audit recipe also includes the audit ingredient. These arrows describe authoring reuse; they do not run commands.
-[View Two recipes reuse the same source instructions diagram](https://www.shoalrun.com/assets/diagrams/mermaid-62592d6197a75626c36a-light.svg)
+[View Two recipes reuse the same source instructions diagram](https://www.shoalrun.com/assets/diagrams/mermaid-c05dd546346549597149-light.svg)
 ```mermaid
 flowchart TD
- shared["Shared ingredients<br/>Compile CLI → Build docs → Check artifacts"]
+ shared["Shared ingredients<br/>Install dependencies → Build docs → Check artifacts"]
  audit["Audit ingredient<br/>Run project audits"]
  build_recipe["Recipe page<br/>Build and check a page"]
  audit_recipe["Recipe page<br/>Build and audit the site"]

package/agent-docs/author/recipes.sections/related-reading.md CHANGED Viewed

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/recipes.md)

package/agent-docs/author/recipes.sections/try-a-complete-workflow.md CHANGED Viewed

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/recipes.md)

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/recipes.md)

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/recipes.md)

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/recipes.md)

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/recipes.md)

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Related reading
-**Updated: 2026-10-26.**
+**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).
@@ -105,6 +105,10 @@ For optional cards, change the presentation:
 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.

package/agent-docs/author/related-reading.sections/automatic-footers.md CHANGED Viewed

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Related reading
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/related-reading.md)

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Related reading
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/related-reading.md)

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Related reading
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/related-reading.md)

package/agent-docs/author/related-reading.sections/html-markdown-and-agents.md ADDED Viewed

@@ -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 CHANGED Viewed

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Related reading
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/related-reading.md)

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Related reading
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/related-reading.md)

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Related reading
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/related-reading.md)

package/agent-docs/author/related-reading.sections/where-relationship-explanations-come-from.md CHANGED Viewed

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Related reading
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 Parent page: [Full Markdown page](/author/related-reading.md)

package/agent-docs/author/search.md CHANGED Viewed

@@ -14,7 +14,7 @@ canonical: /author/search
 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) > Search and chat > Site search
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
 **Updated: 2026-10-26.**

package/agent-docs/author/search.sections/choose-a-provider.md CHANGED Viewed

@@ -14,7 +14,7 @@ canonical: /author/search
 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) > Search and chat > Site search
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
 **Updated: 2026-10-26.**

package/agent-docs/author/search.sections/cli-and-mcp-ranking-details.md CHANGED Viewed

@@ -14,7 +14,7 @@ canonical: /author/search
 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) > Search and chat > Site search
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
 **Updated: 2026-10-26.**

package/agent-docs/author/search.sections/hosted-semantic-search-limits.md CHANGED Viewed

@@ -14,7 +14,7 @@ canonical: /author/search
 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) > Search and chat > Site search
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
 **Updated: 2026-10-26.**

package/agent-docs/author/search.sections/html-markdown-and-agents.md CHANGED Viewed

@@ -14,7 +14,7 @@ canonical: /author/search
 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) > Search and chat > Site search
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
 **Updated: 2026-10-26.**

package/agent-docs/author/search.sections/lexical-search.md CHANGED Viewed

@@ -14,7 +14,7 @@ canonical: /author/search
 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) > Search and chat > Site search
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
 **Updated: 2026-10-26.**