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

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 (513) hide show
  1. package/CHANGELOG.md +7 -0
  2. package/README.md +16 -14
  3. package/agent-docs/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt +22 -0
  4. package/agent-docs/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt +31 -3
  5. package/agent-docs/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt +22 -0
  6. package/agent-docs/SNAPSHOT.json +5 -5
  7. package/agent-docs/api-docs/focused-contracts.md +2 -2
  8. package/agent-docs/api-docs/generate.md +6 -6
  9. package/agent-docs/api-docs/generate.sections/add-useful-examples.md +2 -2
  10. package/agent-docs/api-docs/generate.sections/choose-generated-references-or-mdx.md +5 -5
  11. package/agent-docs/api-docs/generate.sections/describe-filters-that-do-not-use-their-openapi-parameter-name.md +2 -2
  12. package/agent-docs/api-docs/generate.sections/generate-many-pages-selectively.md +2 -2
  13. package/agent-docs/api-docs/generate.sections/link-guides-to-api-references.md +2 -2
  14. package/agent-docs/api-docs/generate.sections/map-extension-values-to-shoalrun-status.md +2 -2
  15. package/agent-docs/api-docs/generate.sections/override-generated-reference-order-in-navigation.md +3 -3
  16. package/agent-docs/api-docs/generate.sections/related-reading.md +2 -2
  17. package/agent-docs/api-docs/generate.sections/use-a-template-for-editorial-context.md +2 -2
  18. package/agent-docs/api-docs/support.md +4 -4
  19. package/agent-docs/author/add-page.md +8 -6
  20. package/agent-docs/author/agent-overview.md +1 -1
  21. package/agent-docs/author/agent-workflow.md +1 -1
  22. package/agent-docs/author/analytics.md +1 -1
  23. package/agent-docs/author/analytics.sections/adapter-exports-and-consent.md +1 -1
  24. package/agent-docs/author/analytics.sections/built-in-events.md +1 -1
  25. package/agent-docs/author/analytics.sections/configure-an-adapter.md +1 -1
  26. package/agent-docs/author/analytics.sections/custom-interactions.md +1 -1
  27. package/agent-docs/author/analytics.sections/event-format.md +1 -1
  28. package/agent-docs/author/analytics.sections/html-markdown-and-agents.md +1 -1
  29. package/agent-docs/author/analytics.sections/inspect-events-locally.md +1 -1
  30. package/agent-docs/author/analytics.sections/map-events-to-your-service.md +1 -1
  31. package/agent-docs/author/analytics.sections/posthog-example.md +1 -1
  32. package/agent-docs/author/analytics.sections/related-reading.md +1 -1
  33. package/agent-docs/author/authoring-agent.md +1 -1
  34. package/agent-docs/author/coding-agent.md +1 -1
  35. package/agent-docs/author/components/action-link.md +9 -3
  36. package/agent-docs/author/components/api-embeds.md +11 -3
  37. package/agent-docs/author/components/api-embeds.sections/apiexample.md +7 -3
  38. package/agent-docs/author/components/api-embeds.sections/html-markdown-and-agents.md +3 -3
  39. package/agent-docs/author/components/api-embeds.sections/related-reading.md +3 -3
  40. package/agent-docs/author/components/badge.md +8 -4
  41. package/agent-docs/author/components/breadcrumbs.md +1 -1
  42. package/agent-docs/author/components/callout.md +8 -4
  43. package/agent-docs/author/components/cards.md +2 -2
  44. package/agent-docs/author/components/cards.sections/add-a-lucide-icon.md +2 -2
  45. package/agent-docs/author/components/cards.sections/build-a-collection.md +2 -2
  46. package/agent-docs/author/components/cards.sections/curate-a-reading-list.md +2 -2
  47. package/agent-docs/author/components/cards.sections/html-markdown-and-agents.md +2 -2
  48. package/agent-docs/author/components/cards.sections/link-to-one-document.md +2 -2
  49. package/agent-docs/author/components/cards.sections/override-card-text.md +2 -2
  50. package/agent-docs/author/components/cards.sections/related-reading.md +2 -2
  51. package/agent-docs/author/components/code-blocks.md +8 -4
  52. package/agent-docs/author/components/collapsible.md +7 -3
  53. package/agent-docs/author/components/cookbook-chooser.md +7 -3
  54. package/agent-docs/author/components/custom/react.md +1 -1
  55. package/agent-docs/author/components/custom/react.sections/html-markdown-and-agents.md +1 -1
  56. package/agent-docs/author/components/custom/react.sections/interactive-react-example.md +1 -1
  57. package/agent-docs/author/components/custom/react.sections/registration.md +1 -1
  58. package/agent-docs/author/components/custom/react.sections/related-reading.md +1 -1
  59. package/agent-docs/author/components/custom/react.sections/share-the-model-with-the-browser.md +1 -1
  60. package/agent-docs/author/components/custom/react.sections/where-the-content-lives.md +1 -1
  61. package/agent-docs/author/components/custom.md +1 -1
  62. package/agent-docs/author/components/definition-list.md +5 -3
  63. package/agent-docs/author/components/diagrams/d2-gallery.md +2 -2
  64. package/agent-docs/author/components/diagrams/d2-gallery.sections/basic-shapes.md +2 -2
  65. package/agent-docs/author/components/diagrams/d2-gallery.sections/flows-and-structures.md +2 -2
  66. package/agent-docs/author/components/diagrams/d2-gallery.sections/html-markdown-and-agents.md +2 -2
  67. package/agent-docs/author/components/diagrams/d2-gallery.sections/layout-engines.md +2 -2
  68. package/agent-docs/author/components/diagrams/d2-gallery.sections/related-reading.md +2 -2
  69. package/agent-docs/author/components/diagrams/d2-gallery.sections/sequences-and-grids.md +2 -2
  70. package/agent-docs/author/components/diagrams/d2-gallery.sections/styles-and-code.md +2 -2
  71. package/agent-docs/author/components/diagrams/pele-gallery.md +2 -2
  72. package/agent-docs/author/components/diagrams/pele-gallery.sections/charts-and-planning.md +2 -2
  73. package/agent-docs/author/components/diagrams/pele-gallery.sections/flowchart-shapes.md +2 -2
  74. package/agent-docs/author/components/diagrams/pele-gallery.sections/flows-and-behavior.md +2 -2
  75. package/agent-docs/author/components/diagrams/pele-gallery.sections/html-markdown-and-agents.md +2 -2
  76. package/agent-docs/author/components/diagrams/pele-gallery.sections/related-reading.md +2 -2
  77. package/agent-docs/author/components/diagrams/pele-gallery.sections/specialized-diagrams.md +2 -2
  78. package/agent-docs/author/components/diagrams/pele-gallery.sections/systems-and-structures.md +2 -2
  79. package/agent-docs/author/components/diagrams.md +13 -5
  80. package/agent-docs/author/components/doc-link.md +7 -3
  81. package/agent-docs/author/components/fields.md +6 -4
  82. package/agent-docs/author/components/file-tree.md +7 -3
  83. package/agent-docs/author/components/images.md +5 -3
  84. package/agent-docs/author/components/info-hint.md +7 -3
  85. package/agent-docs/author/components/kbd.md +5 -3
  86. package/agent-docs/author/components/math.md +7 -3
  87. package/agent-docs/author/components/only.md +9 -5
  88. package/agent-docs/author/components/progress.md +7 -3
  89. package/agent-docs/author/components/related-reading.md +7 -3
  90. package/agent-docs/author/components/steps.md +9 -3
  91. package/agent-docs/author/components/tables.md +7 -3
  92. package/agent-docs/author/components/tabs.md +7 -3
  93. package/agent-docs/author/components/timeline.md +10 -4
  94. package/agent-docs/author/components/tooltips.md +7 -3
  95. package/agent-docs/author/components/walkthroughs.md +5 -3
  96. package/agent-docs/author/components/walkthroughs.sections/attributes.md +3 -3
  97. package/agent-docs/author/components/walkthroughs.sections/build-up-code.md +3 -3
  98. package/agent-docs/author/components/walkthroughs.sections/choose-a-layout.md +3 -3
  99. package/agent-docs/author/components/walkthroughs.sections/explain-one-file.md +3 -3
  100. package/agent-docs/author/components/walkthroughs.sections/html-markdown-and-agents.md +3 -3
  101. package/agent-docs/author/components/walkthroughs.sections/related-reading.md +3 -3
  102. package/agent-docs/author/components/walkthroughs.sections/syntax.md +51 -0
  103. package/agent-docs/author/components/walkthroughs.sections/take-code-from-a-file.md +3 -22
  104. package/agent-docs/author/components.md +7 -4
  105. package/agent-docs/author/css.md +13 -10
  106. package/agent-docs/author/css.sections/borders-fields-and-navigation-tokens.md +3 -3
  107. package/agent-docs/author/css.sections/core-color-tokens.md +3 -3
  108. package/agent-docs/author/css.sections/html-markdown-and-agents.md +54 -0
  109. package/agent-docs/author/css.sections/page-attributes.md +9 -9
  110. package/agent-docs/author/css.sections/page-transitions.md +3 -3
  111. package/agent-docs/author/css.sections/responsive-behavior.md +3 -3
  112. package/agent-docs/author/css.sections/status-code-and-callout-tokens.md +3 -3
  113. package/agent-docs/author/css.sections/typography-shape-and-width-tokens.md +3 -3
  114. package/agent-docs/author/custom-metadata.md +2 -2
  115. package/agent-docs/author/custom-metadata.sections/add-a-custom-page-field.md +2 -2
  116. package/agent-docs/author/custom-metadata.sections/choose-text-for-each-surface.md +2 -2
  117. package/agent-docs/author/custom-metadata.sections/preview-changes-to-metadata-providers.md +2 -2
  118. package/agent-docs/author/custom-metadata.sections/read-metadata-from-a-project-module.md +2 -2
  119. package/agent-docs/author/custom-metadata.sections/related-reading.md +2 -2
  120. package/agent-docs/author/design-templates.md +1 -1
  121. package/agent-docs/author/design-writing-guides.md +1 -1
  122. package/agent-docs/author/frontmatter-reference.md +7 -3
  123. package/agent-docs/author/frontmatter-reference.sections/choose-a-publication-and-visibility.md +3 -3
  124. package/agent-docs/author/frontmatter-reference.sections/control-output-details.md +3 -3
  125. package/agent-docs/author/frontmatter-reference.sections/global-defaults-and-enforced-values.md +3 -3
  126. package/agent-docs/author/frontmatter-reference.sections/html-markdown-and-agents.md +31 -0
  127. package/agent-docs/author/frontmatter-reference.sections/identify-and-route-a-page.md +3 -3
  128. package/agent-docs/author/frontmatter-reference.sections/point-agents-to-it.md +3 -3
  129. package/agent-docs/author/frontmatter-reference.sections/project-defined-fields.md +3 -3
  130. package/agent-docs/author/frontmatter-reference.sections/related-reading.md +3 -3
  131. package/agent-docs/author/frontmatter-reference.sections/use-the-local-files-while-authoring.md +3 -3
  132. package/agent-docs/author/frontmatter-reference.sections/when-the-files-update.md +3 -3
  133. package/agent-docs/author/frontmatter.md +2 -2
  134. package/agent-docs/author/frontmatter.sections/audience-badges.md +2 -2
  135. package/agent-docs/author/frontmatter.sections/give-deprecation-guidance.md +2 -2
  136. package/agent-docs/author/frontmatter.sections/global-defaults-and-enforced-values.md +2 -2
  137. package/agent-docs/author/frontmatter.sections/optional-native-fields.md +2 -2
  138. package/agent-docs/author/frontmatter.sections/publication-fields.md +2 -2
  139. package/agent-docs/author/frontmatter.sections/publishing-policy.md +2 -2
  140. package/agent-docs/author/frontmatter.sections/related-metadata-tasks.md +2 -2
  141. package/agent-docs/author/frontmatter.sections/related-reading.md +2 -2
  142. package/agent-docs/author/frontmatter.sections/required-after-inheritance.md +2 -2
  143. package/agent-docs/author/frontmatter.sections/seo-fields.md +2 -2
  144. package/agent-docs/author/frontmatter.sections/validation-rules.md +2 -2
  145. package/agent-docs/author/markdown-metadata.md +5 -5
  146. package/agent-docs/author/navigation.md +1 -1
  147. package/agent-docs/author/navigation.sections/arrange-authored-pages.md +1 -1
  148. package/agent-docs/author/navigation.sections/fill-an-api-tag-group.md +1 -1
  149. package/agent-docs/author/navigation.sections/hide-group-page-counts.md +1 -1
  150. package/agent-docs/author/navigation.sections/html-markdown-and-agents.md +1 -1
  151. package/agent-docs/author/navigation.sections/local-api-preview.md +1 -1
  152. package/agent-docs/author/navigation.sections/mix-guides-and-api-references.md +1 -1
  153. package/agent-docs/author/navigation.sections/optionally-split-a-large-menu-into-files.md +1 -1
  154. package/agent-docs/author/navigation.sections/reach-navigation-while-reading.md +1 -1
  155. package/agent-docs/author/navigation.sections/related-reading.md +1 -1
  156. package/agent-docs/author/navigation.sections/split-navigation-into-tabs.md +1 -1
  157. package/agent-docs/author/navigation.sections/subject-lifecycle-labels.md +1 -1
  158. package/agent-docs/author/recipe-drafts.md +16 -16
  159. package/agent-docs/author/recipe-drafts.sections/1-write-one-reusable-step.md +5 -5
  160. package/agent-docs/author/recipe-drafts.sections/2-list-the-steps-for-one-complete-goal.md +3 -3
  161. package/agent-docs/author/recipe-drafts.sections/3-generate-a-draft-and-review-it.md +4 -4
  162. package/agent-docs/author/recipe-drafts.sections/4-maintain-shoalrun-s-published-recipe-snapshots.md +3 -3
  163. package/agent-docs/author/recipe-drafts.sections/related-reading.md +1 -1
  164. package/agent-docs/author/recipe-drafts.sections/start-an-ingredient-from-an-api-example.md +5 -5
  165. package/agent-docs/author/recipes.md +4 -4
  166. package/agent-docs/author/recipes.sections/how-agents-use-this.md +1 -1
  167. package/agent-docs/author/recipes.sections/one-example-from-shoalrun.md +4 -4
  168. package/agent-docs/author/recipes.sections/related-reading.md +1 -1
  169. package/agent-docs/author/recipes.sections/try-a-complete-workflow.md +1 -1
  170. package/agent-docs/author/recipes.sections/use-recipes-for-task-oriented-how-tos.md +1 -1
  171. package/agent-docs/author/recipes.sections/what-changing-an-ingredient-updates.md +1 -1
  172. package/agent-docs/author/recipes.sections/what-each-file-does.md +1 -1
  173. package/agent-docs/author/recipes.sections/what-happens-and-when.md +1 -1
  174. package/agent-docs/author/related-reading.md +5 -1
  175. package/agent-docs/author/related-reading.sections/automatic-footers.md +1 -1
  176. package/agent-docs/author/related-reading.sections/declare-relationships.md +1 -1
  177. package/agent-docs/author/related-reading.sections/display-related-documents.md +1 -1
  178. package/agent-docs/author/related-reading.sections/html-markdown-and-agents.md +28 -0
  179. package/agent-docs/author/related-reading.sections/inspect-output-and-changes.md +1 -1
  180. package/agent-docs/author/related-reading.sections/reading-paths-in-section-markdown.md +1 -1
  181. package/agent-docs/author/related-reading.sections/related-reading.md +1 -1
  182. package/agent-docs/author/related-reading.sections/where-relationship-explanations-come-from.md +1 -1
  183. package/agent-docs/author/search.md +1 -1
  184. package/agent-docs/author/search.sections/choose-a-provider.md +1 -1
  185. package/agent-docs/author/search.sections/cli-and-mcp-ranking-details.md +1 -1
  186. package/agent-docs/author/search.sections/hosted-semantic-search-limits.md +1 -1
  187. package/agent-docs/author/search.sections/html-markdown-and-agents.md +1 -1
  188. package/agent-docs/author/search.sections/lexical-search.md +1 -1
  189. package/agent-docs/author/search.sections/local-semantic-preview.md +1 -1
  190. package/agent-docs/author/search.sections/read-a-search-result-with-an-agent.md +1 -1
  191. package/agent-docs/author/search.sections/related-reading.md +1 -1
  192. package/agent-docs/author/search.sections/reuse-the-lexical-index.md +1 -1
  193. package/agent-docs/author/search.sections/turn-search-off.md +1 -1
  194. package/agent-docs/author/search.sections/use-the-search-box.md +1 -1
  195. package/agent-docs/author/search.sections/write-a-custom-provider.md +1 -1
  196. package/agent-docs/author/snippets.md +5 -1
  197. package/agent-docs/author/taxonomy.md +1 -1
  198. package/agent-docs/author/templates.md +7 -7
  199. package/agent-docs/author/templates.sections/built-in-feature-templates.md +3 -3
  200. package/agent-docs/author/templates.sections/built-in-templates.md +3 -3
  201. package/agent-docs/author/templates.sections/choose-formatting-enforcement-for-your-project.md +3 -3
  202. package/agent-docs/author/templates.sections/create-or-edit-a-project-template.md +3 -3
  203. package/agent-docs/author/templates.sections/keep-the-four-shapes-distinct.md +3 -3
  204. package/agent-docs/author/templates.sections/project-added-templates.md +3 -3
  205. package/agent-docs/author/templates.sections/related-reading.md +3 -3
  206. package/agent-docs/author/templates.sections/scaffold-a-page.md +7 -7
  207. package/agent-docs/author/templates.sections/short-cli-and-derived-values.md +3 -3
  208. package/agent-docs/author/templates.sections/what-every-template-gives-you.md +3 -3
  209. package/agent-docs/author/workspace/commands.md +2 -2
  210. package/agent-docs/author/workspace.md +1 -1
  211. package/agent-docs/author/writing-style.md +15 -5
  212. package/agent-docs/author/writing-style.sections/adapt-this-example.md +3 -3
  213. package/agent-docs/author/writing-style.sections/choose-components-by-reader-need.md +6 -4
  214. package/agent-docs/author/writing-style.sections/evidence-and-uncertainty.md +3 -3
  215. package/agent-docs/author/writing-style.sections/example-audience-and-scope.md +3 -3
  216. package/agent-docs/author/writing-style.sections/ingredients-recipes-and-cookbooks.md +3 -3
  217. package/agent-docs/author/writing-style.sections/page-purpose-and-structure.md +12 -4
  218. package/agent-docs/author/writing-style.sections/procedures-and-examples.md +3 -3
  219. package/agent-docs/author/writing-style.sections/related-reading.md +3 -3
  220. package/agent-docs/author/writing-style.sections/review-a-draft.md +3 -3
  221. package/agent-docs/author/writing-style.sections/reviewed-writing-examples.md +3 -3
  222. package/agent-docs/author/writing-style.sections/voice-and-explanations.md +3 -3
  223. package/agent-docs/changelog/2026-10-14-agent-readiness.md +2 -2
  224. package/agent-docs/changelog/2026-10-15-evaluation-builds.md +2 -2
  225. package/agent-docs/changelog/2026-10-16-navigation-layouts.md +2 -2
  226. package/agent-docs/changelog/2026-10-17-mcp-hosting.md +2 -2
  227. package/agent-docs/changelog/2026-10-18-search-and-tooltips.md +2 -2
  228. package/agent-docs/changelog/2026-10-19-visual-navigation.md +2 -2
  229. package/agent-docs/changelog/2026-10-25.md +2 -2
  230. package/agent-docs/changelog/2026-10-26.md +2 -2
  231. package/agent-docs/changelog/2026-10-27.md +2 -2
  232. package/agent-docs/changelog/authoring-preview.md +2 -2
  233. package/agent-docs/changelog/authoring-search.md +3 -3
  234. package/agent-docs/changelog/authoring-tools.md +2 -2
  235. package/agent-docs/changelog/working-tree-skill.md +2 -2
  236. package/agent-docs/changelog.md +2 -2
  237. package/agent-docs/chat/checks.md +1 -1
  238. package/agent-docs/chat/checks.sections/answer-ahead-of-time.md +1 -1
  239. package/agent-docs/chat/checks.sections/answer-for-one-audience.md +1 -1
  240. package/agent-docs/chat/checks.sections/answer-without-a-model.md +1 -1
  241. package/agent-docs/chat/checks.sections/follow-up-questions.md +1 -1
  242. package/agent-docs/chat/checks.sections/how-an-answer-is-checked.md +1 -1
  243. package/agent-docs/chat/checks.sections/questions-with-several-parts.md +1 -1
  244. package/agent-docs/chat/checks.sections/related-reading.md +1 -1
  245. package/agent-docs/chat/checks.sections/reuse-answers.md +1 -1
  246. package/agent-docs/chat/host.md +1 -1
  247. package/agent-docs/chat/host.sections/cap-the-daily-spend.md +1 -1
  248. package/agent-docs/chat/host.sections/keep-a-record-of-questions.md +1 -1
  249. package/agent-docs/chat/host.sections/related-reading.md +1 -1
  250. package/agent-docs/chat/passage-index.md +2 -2
  251. package/agent-docs/chat/passage-index.sections/build-the-index.md +2 -2
  252. package/agent-docs/chat/passage-index.sections/embed-passages.md +2 -2
  253. package/agent-docs/chat/passage-index.sections/how-the-default-chunker-splits-a-page.md +2 -2
  254. package/agent-docs/chat/passage-index.sections/limits.md +2 -2
  255. package/agent-docs/chat/passage-index.sections/passage-ids-and-links.md +2 -2
  256. package/agent-docs/chat/passage-index.sections/related-reading.md +2 -2
  257. package/agent-docs/chat/passage-index.sections/what-a-passage-contains.md +2 -2
  258. package/agent-docs/chat/prepared-answers.md +1 -1
  259. package/agent-docs/chat/settings.md +2 -2
  260. package/agent-docs/chat/settings.sections/choose-the-scorer.md +2 -2
  261. package/agent-docs/chat/settings.sections/configure-chat.md +2 -2
  262. package/agent-docs/chat/settings.sections/configure-retrieval.md +2 -2
  263. package/agent-docs/chat/settings.sections/related-reading.md +2 -2
  264. package/agent-docs/chat/settings.sections/send-extra-request-fields.md +2 -2
  265. package/agent-docs/chat/settings.sections/use-more-than-one-model.md +2 -2
  266. package/agent-docs/chat/settings.sections/when-the-scorer-is-down.md +2 -2
  267. package/agent-docs/chat/setup.md +1 -1
  268. package/agent-docs/chat.md +1 -1
  269. package/agent-docs/cli.md +2 -2
  270. package/agent-docs/cli.sections/audit-a-project-and-api-sources.md +2 -2
  271. package/agent-docs/cli.sections/author-pages.md +2 -2
  272. package/agent-docs/cli.sections/build-and-serve.md +2 -2
  273. package/agent-docs/cli.sections/inspect-config-and-operations.md +2 -2
  274. package/agent-docs/cli.sections/npm-scripts-in-this-repository.md +2 -2
  275. package/agent-docs/cli.sections/related-reading.md +2 -2
  276. package/agent-docs/cli.sections/search-and-chat.md +2 -2
  277. package/agent-docs/cli.sections/start-a-project.md +2 -2
  278. package/agent-docs/cli.sections/working-tree-authoring-tools.md +2 -2
  279. package/agent-docs/config/apis.md +2 -2
  280. package/agent-docs/config/content.md +2 -2
  281. package/agent-docs/config/content.sections/authoring.md +2 -2
  282. package/agent-docs/config/content.sections/badges.md +2 -2
  283. package/agent-docs/config/content.sections/callouts.md +2 -2
  284. package/agent-docs/config/content.sections/cookbooks.md +2 -2
  285. package/agent-docs/config/content.sections/frontmatter.md +2 -2
  286. package/agent-docs/config/content.sections/readerfilters.md +2 -2
  287. package/agent-docs/config/content.sections/related-reading.md +2 -2
  288. package/agent-docs/config/content.sections/relationships.md +2 -2
  289. package/agent-docs/config/content.sections/snippets.md +2 -2
  290. package/agent-docs/config/content.sections/templates.md +2 -2
  291. package/agent-docs/config/content.sections/variables.md +2 -2
  292. package/agent-docs/config/examples.md +22 -14
  293. package/agent-docs/config/examples.sections/feature-showcase.md +21 -13
  294. package/agent-docs/config/examples.sections/minimal-site.md +15 -10
  295. package/agent-docs/config/examples.sections/multilingual-help-center.md +15 -10
  296. package/agent-docs/config/examples.sections/parcel-api-documentation.md +15 -10
  297. package/agent-docs/config/examples.sections/related-reading.md +15 -10
  298. package/agent-docs/config/examples.sections/shared-company-preset.md +16 -11
  299. package/agent-docs/config/integrations.md +2 -2
  300. package/agent-docs/config/outputs.md +2 -2
  301. package/agent-docs/config/outputs.sections/exports.md +2 -2
  302. package/agent-docs/config/outputs.sections/metadata.md +2 -2
  303. package/agent-docs/config/outputs.sections/related-reading.md +2 -2
  304. package/agent-docs/config/publishing.md +2 -2
  305. package/agent-docs/config/publishing.sections/navigation.md +2 -2
  306. package/agent-docs/config/publishing.sections/redirects.md +2 -2
  307. package/agent-docs/config/publishing.sections/related-reading.md +2 -2
  308. package/agent-docs/config/site.md +2 -2
  309. package/agent-docs/config/site.sections/related-reading.md +2 -2
  310. package/agent-docs/config/site.sections/theme.md +2 -2
  311. package/agent-docs/config.md +2 -2
  312. package/agent-docs/configuration.md +22 -20
  313. package/agent-docs/configuration.sections/build-several-sites-from-shared-content.md +2 -2
  314. package/agent-docs/configuration.sections/change-inherited-lists-deliberately.md +5 -5
  315. package/agent-docs/configuration.sections/extract-a-section-with-include.md +4 -4
  316. package/agent-docs/configuration.sections/inspect-and-validate-changes.md +6 -6
  317. package/agent-docs/configuration.sections/related-reading.md +2 -2
  318. package/agent-docs/configuration.sections/separate-config-inheritance-from-page-metadata.md +2 -2
  319. package/agent-docs/configuration.sections/share-defaults-through-extends.md +7 -7
  320. package/agent-docs/configuration.sections/start-with-one-working-file.md +8 -6
  321. package/agent-docs/configuration.sections/understand-the-three-stages.md +2 -2
  322. package/agent-docs/configuration.sections/understand-where-paths-point.md +2 -2
  323. package/agent-docs/connect/mcp.md +1 -1
  324. package/agent-docs/contribute/agent-skills.md +1 -1
  325. package/agent-docs/cookbooks/authoring.md +7 -3
  326. package/agent-docs/cookbooks/site-workflows.md +8 -4
  327. package/agent-docs/cookbooks/welcome-email.md +7 -3
  328. package/agent-docs/documents.json +2789 -3040
  329. package/agent-docs/example-api/cedar/create-enrollment-7af3e5d2.md +2 -2
  330. package/agent-docs/example-api/cedar/get-legacy-parcel-6758d051.md +2 -2
  331. package/agent-docs/example-api/cedar/get-parcel-edee10e6.md +2 -2
  332. package/agent-docs/example-api/cedar/list-parcels-0345fb5f.md +2 -2
  333. package/agent-docs/example-api/cedar/parcel-delivered-7d1ba6db.md +2 -2
  334. package/agent-docs/example-api/cedar/upload-manifest-1af17891.md +2 -2
  335. package/agent-docs/example-api/cedar.md +2 -2
  336. package/agent-docs/example-api/create-note.md +2 -2
  337. package/agent-docs/example-api/generated/get-note-cbedb319.md +2 -2
  338. package/agent-docs/example-api/write-note.md +2 -2
  339. package/agent-docs/explore.md +2 -2
  340. package/agent-docs/glossary.md +3 -7
  341. package/agent-docs/ingredients/audit-site.md +2 -2
  342. package/agent-docs/ingredients/build-site.md +2 -2
  343. package/agent-docs/ingredients/compile-framework.md +2 -2
  344. package/agent-docs/ingredients/complete-page.md +2 -2
  345. package/agent-docs/ingredients/inspect-agent-bundle.md +2 -2
  346. package/agent-docs/ingredients/inspect-build.md +2 -2
  347. package/agent-docs/ingredients/preview-site.md +2 -2
  348. package/agent-docs/ingredients/refresh-agent-bundle.md +2 -2
  349. package/agent-docs/ingredients/scaffold-page.md +2 -2
  350. package/agent-docs/non-goals.md +2 -2
  351. package/agent-docs/provenance.json +4 -4
  352. package/agent-docs/publish/agent-discovery.md +1 -1
  353. package/agent-docs/publish/agent-friendliness.md +1 -1
  354. package/agent-docs/publish/agent-friendliness.sections/discover-a-page-with-a-small-context-budget.md +1 -1
  355. package/agent-docs/publish/agent-friendliness.sections/distinguish-examples-from-a-real-service.md +1 -1
  356. package/agent-docs/publish/agent-friendliness.sections/evidence-has-a-scope.md +1 -1
  357. package/agent-docs/publish/agent-friendliness.sections/keep-shared-instructions-complete.md +1 -1
  358. package/agent-docs/publish/agent-friendliness.sections/related-reading.md +1 -1
  359. package/agent-docs/publish/agent-friendliness.sections/secret-handshake.md +1 -1
  360. package/agent-docs/publish/agent-friendliness.sections/try-the-page-controls.md +1 -1
  361. package/agent-docs/publish/agent-friendliness.sections/use-the-transport-your-client-supports.md +1 -1
  362. package/agent-docs/publish/agent-friendliness.sections/verify-the-page-and-detect-changes.md +1 -1
  363. package/agent-docs/publish/agent-friendliness.sections/what-an-agent-reads.md +1 -1
  364. package/agent-docs/publish/agent-friendliness.sections/what-happens-to-an-unsupported-component.md +1 -1
  365. package/agent-docs/publish/api-references.md +10 -8
  366. package/agent-docs/publish/api-references.sections/author-the-reference-page.md +1 -1
  367. package/agent-docs/publish/api-references.sections/build-and-verify-the-output.md +1 -1
  368. package/agent-docs/publish/api-references.sections/inspect-the-machine-readable-contract.md +1 -1
  369. package/agent-docs/publish/api-references.sections/{generate-many-pages-selectively.md → next-steps.md} +28 -2
  370. package/agent-docs/publish/api-references.sections/preview-a-small-api-reference.md +1 -1
  371. package/agent-docs/publish/api-references.sections/put-the-spec-in-your-project.md +1 -1
  372. package/agent-docs/publish/api-references.sections/register-the-operation.md +1 -1
  373. package/agent-docs/publish/api-references.sections/related-reading.md +1 -1
  374. package/agent-docs/publish/api-references.sections/review-imported-content-before-publishing.md +1 -1
  375. package/agent-docs/publish/api-references.sections/what-readers-get.md +1 -1
  376. package/agent-docs/publish/audit.md +1 -1
  377. package/agent-docs/publish/audit.sections/add-project-tests.md +1 -1
  378. package/agent-docs/publish/audit.sections/check-agent-evaluation-reports.md +1 -1
  379. package/agent-docs/publish/audit.sections/check-before-pushing.md +1 -1
  380. package/agent-docs/publish/audit.sections/connect-a-documentation-test-suite.md +1 -1
  381. package/agent-docs/publish/audit.sections/read-the-report.md +1 -1
  382. package/agent-docs/publish/audit.sections/related-reading.md +1 -1
  383. package/agent-docs/publish/content-export.md +1 -1
  384. package/agent-docs/publish/content-export.sections/assets-downloads-and-notices.md +1 -1
  385. package/agent-docs/publish/content-export.sections/check-the-result.md +1 -1
  386. package/agent-docs/publish/content-export.sections/export-selected-pages.md +1 -1
  387. package/agent-docs/publish/content-export.sections/inspect-the-manifest.md +1 -1
  388. package/agent-docs/publish/content-export.sections/prerequisites.md +1 -1
  389. package/agent-docs/publish/content-export.sections/related-reading.md +1 -1
  390. package/agent-docs/publish/content-export.sections/review-exported-api-material.md +1 -1
  391. package/agent-docs/publish/content-export.sections/try-the-help-drawer-example.md +1 -1
  392. package/agent-docs/publish/content-export.sections/what-the-representations-retain.md +1 -1
  393. package/agent-docs/publish/content-negotiation.md +2 -2
  394. package/agent-docs/publish/content-negotiation.sections/hosting-contract.md +2 -2
  395. package/agent-docs/publish/content-negotiation.sections/missing-pages.md +2 -2
  396. package/agent-docs/publish/content-negotiation.sections/related-reading.md +2 -2
  397. package/agent-docs/publish/content-negotiation.sections/validators-and-manifest-links.md +2 -2
  398. package/agent-docs/publish/content-negotiation.sections/verify-the-deployed-url.md +2 -2
  399. package/agent-docs/publish/content-negotiation.sections/what-if-the-host-cannot-negotiate.md +2 -2
  400. package/agent-docs/publish/content-negotiation.sections/what-shoalrun-builds-and-what-the-host-does.md +2 -2
  401. package/agent-docs/publish/content-negotiation.sections/why-this-matters.md +2 -2
  402. package/agent-docs/publish/deployment-check.md +2 -2
  403. package/agent-docs/publish/evals.md +1 -1
  404. package/agent-docs/publish/evals.sections/add-the-audit-hook.md +1 -1
  405. package/agent-docs/publish/evals.sections/check-the-report.md +1 -1
  406. package/agent-docs/publish/evals.sections/define-a-task-file.md +1 -1
  407. package/agent-docs/publish/evals.sections/diagnose-a-different-build.md +1 -1
  408. package/agent-docs/publish/evals.sections/prepare-a-report-for-the-built-site.md +1 -1
  409. package/agent-docs/publish/evals.sections/related-reading.md +1 -1
  410. package/agent-docs/publish/evals.sections/run-and-review-the-tasks.md +1 -1
  411. package/agent-docs/publish/evals.sections/shoalrun-s-own-example.md +1 -1
  412. package/agent-docs/publish/host-adapters.md +1 -1
  413. package/agent-docs/publish/manni.md +1 -1
  414. package/agent-docs/publish/manni.sections/check-the-result.md +1 -1
  415. package/agent-docs/publish/manni.sections/how-this-site-uses-manni.md +1 -1
  416. package/agent-docs/publish/manni.sections/optional-custom-policies.md +1 -1
  417. package/agent-docs/publish/manni.sections/prerequisites.md +1 -1
  418. package/agent-docs/publish/mcp-analytics.md +1 -1
  419. package/agent-docs/publish/mcp-analytics.sections/adapter-exports.md +1 -1
  420. package/agent-docs/publish/mcp-analytics.sections/enable-analytics.md +1 -1
  421. package/agent-docs/publish/mcp-analytics.sections/event-fields-and-service-mappings.md +1 -1
  422. package/agent-docs/publish/mcp-analytics.sections/optionally-collect-intent-and-group-calls.md +1 -1
  423. package/agent-docs/publish/mcp-analytics.sections/optionally-identify-the-client-and-model.md +1 -1
  424. package/agent-docs/publish/mcp-analytics.sections/related-reading.md +1 -1
  425. package/agent-docs/publish/mcp-analytics.sections/safeguards-and-limits.md +1 -1
  426. package/agent-docs/publish/mcp.md +9 -9
  427. package/agent-docs/publish/mcp.sections/check-budgets-and-errors.md +1 -1
  428. package/agent-docs/publish/mcp.sections/choose-the-documentation-source.md +6 -6
  429. package/agent-docs/publish/mcp.sections/configure-the-client.md +4 -4
  430. package/agent-docs/publish/mcp.sections/generate-a-vercel-endpoint.md +1 -1
  431. package/agent-docs/publish/mcp.sections/related-reading.md +1 -1
  432. package/agent-docs/publish/mcp.sections/search-then-read.md +1 -1
  433. package/agent-docs/publish/mcp.sections/serve-a-public-endpoint-on-node.md +1 -1
  434. package/agent-docs/publish/mcp.sections/verify-the-connection.md +1 -1
  435. package/agent-docs/publish/mcp.sections/why-offer-mcp-for-public-docs.md +1 -1
  436. package/agent-docs/publish/openapi-extension-mappings.md +2 -2
  437. package/agent-docs/publish/output.md +14 -14
  438. package/agent-docs/publish/output.sections/api-contracts.md +3 -3
  439. package/agent-docs/publish/output.sections/code-highlighting.md +3 -3
  440. package/agent-docs/publish/output.sections/current-limits.md +4 -4
  441. package/agent-docs/publish/output.sections/incremental-sync.md +3 -3
  442. package/agent-docs/publish/output.sections/manifest-records-and-sections.md +3 -3
  443. package/agent-docs/publish/output.sections/navigation-section-indexes.md +3 -3
  444. package/agent-docs/publish/output.sections/page-formats.md +3 -3
  445. package/agent-docs/publish/output.sections/published-output-contract.md +3 -3
  446. package/agent-docs/publish/output.sections/reader-appearance-and-controls.md +3 -3
  447. package/agent-docs/publish/output.sections/related-reading.md +3 -3
  448. package/agent-docs/publish/output.sections/response-identity.md +3 -3
  449. package/agent-docs/publish/output.sections/site-files.md +3 -3
  450. package/agent-docs/publish/output.sections/validate-an-existing-build-locally.md +5 -5
  451. package/agent-docs/publish/output.sections/where-files-go.md +11 -11
  452. package/agent-docs/publish/publications.md +1 -1
  453. package/agent-docs/publish/revisions.md +1 -1
  454. package/agent-docs/publish/seo.md +1 -1
  455. package/agent-docs/publish/single-source-sites.md +1 -1
  456. package/agent-docs/publish/troubleshooting.md +1 -1
  457. package/agent-docs/publish/vercel.md +1 -1
  458. package/agent-docs/publish/vercel.sections/check-the-deployment.md +1 -1
  459. package/agent-docs/publish/vercel.sections/include-an-mcp-endpoint.md +1 -1
  460. package/agent-docs/publish/vercel.sections/prepare-your-project.md +1 -1
  461. package/agent-docs/publish/vercel.sections/related-reading.md +1 -1
  462. package/agent-docs/publish.md +1 -1
  463. package/agent-docs/recipes/add-page.md +3 -3
  464. package/agent-docs/recipes/add-page.sections/audit-the-shoalrun-docs-project.md +2 -2
  465. package/agent-docs/recipes/add-page.sections/before-you-start.md +2 -3
  466. package/agent-docs/recipes/add-page.sections/build-the-shoalrun-docs-site.md +2 -2
  467. package/agent-docs/recipes/add-page.sections/check-agent-search-and-page-lookup.md +2 -2
  468. package/agent-docs/recipes/add-page.sections/check-the-built-page-artifacts.md +2 -2
  469. package/agent-docs/recipes/add-page.sections/check-the-outcome.md +2 -2
  470. package/agent-docs/recipes/add-page.sections/complete-the-guide-and-add-navigation.md +2 -2
  471. package/agent-docs/recipes/add-page.sections/install-the-site-dependencies.md +2 -2
  472. package/agent-docs/recipes/add-page.sections/regenerate-the-agent-documentation-bundle.md +3 -2
  473. package/agent-docs/recipes/add-page.sections/related-reading.md +2 -2
  474. package/agent-docs/recipes/add-page.sections/scaffold-a-new-guide.md +2 -2
  475. package/agent-docs/recipes/audit-docs.md +2 -3
  476. package/agent-docs/recipes/build-docs.md +2 -3
  477. package/agent-docs/recipes/preview-hybrid-search.md +2 -2
  478. package/agent-docs/recipes/preview-page.md +2 -3
  479. package/agent-docs/recipes/queue-email.md +2 -2
  480. package/agent-docs/recipes/refresh-agent-docs.md +21 -3
  481. package/agent-docs/recipes/send-welcome-email.md +2 -2
  482. package/agent-docs/reference/agent-skills.md +2 -2
  483. package/agent-docs/search-and-chat.md +1 -1
  484. package/agent-docs/search-index.json +1 -1
  485. package/agent-docs/start.md +7 -3
  486. package/agent-docs/start.sections/build-this-site.md +1 -1
  487. package/agent-docs/start.sections/migrating-from-github-packages.md +35 -0
  488. package/agent-docs/start.sections/prerequisites.md +1 -1
  489. package/agent-docs/start.sections/start-your-own-project.md +1 -1
  490. package/agent-docs/status.md +2 -2
  491. package/agent-docs/styling/color-modes.md +6 -2
  492. package/agent-docs/styling/footer.md +10 -8
  493. package/agent-docs/styling/header.md +5 -3
  494. package/agent-docs/styling/layouts.md +7 -3
  495. package/agent-docs/styling/layouts.sections/build-a-landing-page.md +2 -2
  496. package/agent-docs/styling/layouts.sections/build-a-splash-page.md +2 -2
  497. package/agent-docs/styling/layouts.sections/control-navigation-tabs.md +2 -2
  498. package/agent-docs/styling/layouts.sections/customize-the-hero.md +2 -2
  499. package/agent-docs/styling/layouts.sections/hero.md +3 -3
  500. package/agent-docs/styling/layouts.sections/html-markdown-and-agents.md +40 -0
  501. package/agent-docs/styling/layouts.sections/related-reading.md +2 -2
  502. package/agent-docs/styling/palettes.md +6 -2
  503. package/agent-docs/styling/share-images.md +6 -2
  504. package/agent-docs/styling/themes.md +6 -3
  505. package/agent-docs/styling/try.md +3 -15
  506. package/package.json +1 -1
  507. package/agent-docs/.well-known/shoalrun/navigation/changelog-tab-50f26fe22670.txt +0 -33
  508. package/agent-docs/publish/api-references.sections/add-useful-examples.md +0 -36
  509. package/agent-docs/publish/api-references.sections/describe-filters-that-do-not-use-their-openapi-parameter-name.md +0 -36
  510. package/agent-docs/publish/api-references.sections/link-guides-to-api-references.md +0 -36
  511. package/agent-docs/publish/api-references.sections/map-extension-values-to-shoalrun-status.md +0 -36
  512. package/agent-docs/publish/api-references.sections/publish-several-versions.md +0 -36
  513. package/agent-docs/publish/api-references.sections/use-a-template-for-editorial-context.md +0 -36
package/agent-docs/author/components/diagrams/d2-gallery.sections/basic-shapes.md CHANGED
@@ -12,9 +12,9 @@ canonical: /author/components/diagrams/d2-gallery
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Diagrams > D2 gallery
17
+ Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > D2 gallery
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/components/diagrams/d2-gallery.sections/flows-and-structures.md CHANGED
@@ -12,9 +12,9 @@ canonical: /author/components/diagrams/d2-gallery
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Diagrams > D2 gallery
17
+ Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > D2 gallery
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/components/diagrams/d2-gallery.sections/html-markdown-and-agents.md CHANGED
@@ -12,9 +12,9 @@ canonical: /author/components/diagrams/d2-gallery
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Diagrams > D2 gallery
17
+ Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > D2 gallery
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/components/diagrams/d2-gallery.sections/layout-engines.md CHANGED
@@ -12,9 +12,9 @@ canonical: /author/components/diagrams/d2-gallery
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Diagrams > D2 gallery
17
+ Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > D2 gallery
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/components/diagrams/d2-gallery.sections/related-reading.md CHANGED
@@ -12,9 +12,9 @@ canonical: /author/components/diagrams/d2-gallery
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Diagrams > D2 gallery
17
+ Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > D2 gallery
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/components/diagrams/d2-gallery.sections/sequences-and-grids.md CHANGED
@@ -12,9 +12,9 @@ canonical: /author/components/diagrams/d2-gallery
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Diagrams > D2 gallery
17
+ Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > D2 gallery
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/components/diagrams/d2-gallery.sections/styles-and-code.md CHANGED
@@ -12,9 +12,9 @@ canonical: /author/components/diagrams/d2-gallery
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Diagrams > D2 gallery
17
+ Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > D2 gallery
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/components/diagrams/pele-gallery.md CHANGED
@@ -12,9 +12,9 @@ canonical: /author/components/diagrams/pele-gallery
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Diagrams > Pele gallery
17
+ Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Pele gallery
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/components/diagrams/pele-gallery.sections/charts-and-planning.md CHANGED
@@ -12,9 +12,9 @@ canonical: /author/components/diagrams/pele-gallery
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Diagrams > Pele gallery
17
+ Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Pele gallery
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/components/diagrams/pele-gallery.sections/flowchart-shapes.md CHANGED
@@ -12,9 +12,9 @@ canonical: /author/components/diagrams/pele-gallery
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Diagrams > Pele gallery
17
+ Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Pele gallery
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/components/diagrams/pele-gallery.sections/flows-and-behavior.md CHANGED
@@ -12,9 +12,9 @@ canonical: /author/components/diagrams/pele-gallery
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Diagrams > Pele gallery
17
+ Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Pele gallery
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/components/diagrams/pele-gallery.sections/html-markdown-and-agents.md CHANGED
@@ -12,9 +12,9 @@ canonical: /author/components/diagrams/pele-gallery
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Diagrams > Pele gallery
17
+ Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Pele gallery
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/components/diagrams/pele-gallery.sections/related-reading.md CHANGED
@@ -12,9 +12,9 @@ canonical: /author/components/diagrams/pele-gallery
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Diagrams > Pele gallery
17
+ Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Pele gallery
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/components/diagrams/pele-gallery.sections/specialized-diagrams.md CHANGED
@@ -12,9 +12,9 @@ canonical: /author/components/diagrams/pele-gallery
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Diagrams > Pele gallery
17
+ Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Pele gallery
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/components/diagrams/pele-gallery.sections/systems-and-structures.md CHANGED
@@ -12,9 +12,9 @@ canonical: /author/components/diagrams/pele-gallery
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Diagrams > Pele gallery
17
+ Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Visual examples > Pele gallery
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/components/diagrams.md CHANGED
@@ -13,11 +13,11 @@ canonical: /author/components/diagrams
13
13
 
14
14
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
15
15
 
16
- 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)
16
+ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
17
17
 
18
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Diagrams > Overview
18
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Overview
19
19
 
20
- **Updated: 2026-10-26.**
20
+ **Updated: 2026-10-27.**
21
21
 
22
22
  Use `<Diagram>` for flowcharts, sequence diagrams, charts, and other graphs written as text. D2 is the default engine, with TALA as its default layout. Set `engine="mermaid"` for Mermaid syntax, rendered by [Pele](https://pele.run). Diagrams render to SVG during the build, so readers do not need a diagram script in their browser. Set a literal pixel `width`, such as `width="440"`, to cap the diagram's displayed width while allowing it to shrink on narrow screens.
23
23
 
@@ -25,7 +25,11 @@ For the diagram languages themselves, use the official [D2 tour](https://d2lang.
25
25
 
26
26
  Every diagram needs a short `title` and `summary`. The summary states the point of the diagram; it does not need to repeat every connection. For a complex diagram, add a fuller explanation in nearby prose so readers can understand its meaning without the graphic.
27
27
 
28
- ## D2
28
+ ## Syntax
29
+
30
+ Choose D2 or Mermaid for the source language.
31
+
32
+ ### D2
29
33
 
30
34
  Copy the complete component, including its fenced source:
31
35
 
@@ -67,7 +71,7 @@ Browse the [D2 gallery](https://www.shoalrun.com/author/components/diagrams/d2-g
67
71
 
68
72
  The official [D2 layout guide](https://d2lang.com/tour/layouts/) compares the engines. The [D2 style guide](https://d2lang.com/tour/style/) and [theme guide](https://d2lang.com/tour/themes/) cover source-level shape styles and theme options.
69
73
 
70
- ## Mermaid
74
+ ### Mermaid
71
75
 
72
76
  Set the engine explicitly and keep the fence language `mermaid`:
73
77
 
@@ -95,6 +99,10 @@ flowchart LR
95
99
  review --> publish[Publish]
96
100
  ```
97
101
 
102
+ ## Attributes
103
+
104
+ Use these attributes to configure the component.
105
+
98
106
  | Attribute | Required | Meaning |
99
107
  | --------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
100
108
  | `title` | Yes | Short literal name for the diagram. |
package/agent-docs/author/components/doc-link.md CHANGED
@@ -12,11 +12,11 @@ canonical: /author/components/doc-link
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > DocLink
17
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > DocLink
18
18
 
19
- **Updated: 2026-10-26.**
19
+ **Updated: 2026-10-27.**
20
20
 
21
21
  `<DocLink>` resolves a document ID to its URL in the current publication. It is useful in MDX when the link should use a stable target and optionally inherit the target page's title.
22
22
 
@@ -39,6 +39,10 @@ Prefer `doc:` Markdown for ordinary prose. Both ID-based forms survive a target
39
39
  <DocLink doc="guide.frontmatter">Read the frontmatter guide</DocLink>
40
40
  ```
41
41
 
42
+ ## Attributes
43
+
44
+ Use these attributes to configure the component.
45
+
42
46
  | Attribute | Required | Meaning |
43
47
  | --------- | -------- | --------------------------------------------------------- |
44
48
  | `doc` | Yes | Stable ID of a page available in the current publication. |
package/agent-docs/author/components/fields.md CHANGED
@@ -12,11 +12,11 @@ canonical: /author/components/fields
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Fields
17
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Fields
18
18
 
19
- **Updated: 2026-10-26.**
19
+ **Updated: 2026-10-27.**
20
20
 
21
21
  Use `<Fields>` and `<Field>` to describe fields that are not selected from an OpenAPI schema, or to explain a small task-specific subset in your own words. The list uses the same field styling as generated schemas. If the exact contract already exists in OpenAPI, [ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) can include the source schema or one of its fields.
22
22
 
@@ -69,7 +69,9 @@ Use a shorter layout.
69
69
 
70
70
  `Fields` takes no attributes and needs direct `Field` children. A `Field` body accepts ordinary Markdown and supported MDX, including a nested `Fields` list. A standalone `Field` or other direct child of `Fields` fails the build.
71
71
 
72
- ## Attribute reference
72
+ ## Attributes
73
+
74
+ ### Attribute reference
73
75
 
74
76
  All values are literal MDX attributes. Text and numbers use quoted strings; flags are bare attributes. These declarations describe fields in the published page. They do not validate user input at runtime.
75
77
 
package/agent-docs/author/components/file-tree.md CHANGED
@@ -12,14 +12,16 @@ canonical: /author/components/file-tree
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > File trees
17
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > File trees
18
18
 
19
- **Updated: 2026-10-19.**
19
+ **Updated: 2026-10-27.**
20
20
 
21
21
  `<FileTree>` shows a file layout or other hierarchy. `<Tree>` is an alias. Add `<Folder>` branches and `<File>` leaves; folders may contain more folders or files.
22
22
 
23
+ ## Syntax
24
+
23
25
  ```mdx
24
26
  <FileTree>
25
27
  <Folder name="docs">
@@ -52,6 +54,8 @@ Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write docume
52
54
 
53
55
  - package.json
54
56
 
57
+ ## Attributes
58
+
55
59
  Every node needs a nonempty `name`. Folders and files get icons automatically, and a folder’s icon changes when it opens. Optional `doc` or `href` makes its label a link; use only one. Optional `icon` accepts a lowercase Lucide name to override the default. `<File>` cannot have children.
56
60
 
57
61
  ## Expand and collapse folders
package/agent-docs/author/components/images.md CHANGED
@@ -13,11 +13,11 @@ canonical: /author/components/images
13
13
 
14
14
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
15
15
 
16
- 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)
16
+ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
17
17
 
18
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Images
18
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Images
19
19
 
20
- **Updated: 2026-10-26.**
20
+ **Updated: 2026-10-27.**
21
21
 
22
22
  Use `<Image>` to show an image with optional sizing, a caption, or click-to-expand viewing. Plain Markdown image syntax also works when you only need an image and alt text.
23
23
 
@@ -25,6 +25,8 @@ Use `<Image>` to show an image with optional sizing, a caption, or click-to-expa
25
25
 
26
26
  Provide a source and alt text. Local paths are relative to the page's MDX file; Shoalrun copies the image into the build. HTTPS URLs work too.
27
27
 
28
+ ## Syntax
29
+
28
30
  ```mdx
29
31
  <Image src="./assets/image-example.svg" alt="A documentation page with navigation, content, and a table of contents" />
30
32
  ```
package/agent-docs/author/components/info-hint.md CHANGED
@@ -12,11 +12,11 @@ canonical: /author/components/info-hint
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Short definitions
17
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Short definitions
18
18
 
19
- **Updated: 2026-10-26.**
19
+ **Updated: 2026-10-27.**
20
20
 
21
21
  Use `<InfoHint>` for a short definition that readers can open when they need it. It is a click-to-expand disclosure. Use a [tooltip](https://www.shoalrun.com/author/components/tooltips.md) for brief text that appears on hover or keyboard focus. Put longer explanations in a [callout](https://www.shoalrun.com/author/components/callout.md) or a linked page.
22
22
 
@@ -32,6 +32,10 @@ The preferred address for a page when several addresses show the same content.
32
32
 
33
33
  Canonical URL: The preferred address for a page when several addresses show the same content.
34
34
 
35
+ ## Attributes
36
+
37
+ Use these attributes to configure the component.
38
+
35
39
  | Attribute | Required | Meaning |
36
40
  | --------- | -------- | ---------------------------------------------- |
37
41
  | `label` | Yes | Nonempty text shown on the disclosure control. |
package/agent-docs/author/components/kbd.md CHANGED
@@ -12,11 +12,11 @@ canonical: /author/components/kbd
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Keyboard shortcuts
17
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Keyboard shortcuts
18
18
 
19
- **Updated: 2026-10-26.**
19
+ **Updated: 2026-10-27.**
20
20
 
21
21
  Use `<Kbd>` to name a key or shortcut in a sentence. Include the action in the sentence; key styling alone does not explain what the shortcut does.
22
22
 
@@ -30,6 +30,8 @@ Press <Kbd>⌘</Kbd> + <Kbd>C</Kbd> to copy selected text.
30
30
 
31
31
  Press ⌘ + C to copy selected text.
32
32
 
33
+ ## Attributes
34
+
33
35
  `<Kbd>` takes nonempty plain text and no attributes. It works inside prose, headings, and table cells.
34
36
 
35
37
  ## HTML, Markdown, and agents
package/agent-docs/author/components/math.md CHANGED
@@ -12,14 +12,16 @@ canonical: /author/components/math
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Math
17
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Math
18
18
 
19
- **Updated: 2026-10-19.**
19
+ **Updated: 2026-10-27.**
20
20
 
21
21
  Use `<Math>` with a literal LaTeX expression. It supports the KaTeX math subset and reports invalid expressions during the build.
22
22
 
23
+ ## Syntax
24
+
23
25
  ```mdx
24
26
  Energy is <Math expression="E=mc^2" />.
25
27
 
@@ -32,6 +34,8 @@ Energy is `E=mc^2`.
32
34
  c^2=a^2+b^2
33
35
  ```
34
36
 
37
+ ## Attributes
38
+
35
39
  `expression` is required and nonempty. Add the bare `display` attribute on a block element for centered display math. The component does not parse dollar delimiters in ordinary prose or code fences. Escape quotes in MDX attributes as needed.
36
40
 
37
41
  ## HTML, Markdown, and agents
package/agent-docs/author/components/only.md CHANGED
@@ -12,14 +12,16 @@ canonical: /author/components/only
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Content for one format
17
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Content for one format
18
18
 
19
- **Updated: 2026-10-26.**
19
+ **Updated: 2026-10-27.**
20
20
 
21
21
  Use `<Only>` to author content for one output format. Shared material stays outside the blocks; a block can contain an instruction, explanation, example, or link that serves only one version:
22
22
 
23
+ ## Syntax
24
+
23
25
  ```mdx
24
26
  Shared setup steps appear in both formats.
25
27
 
@@ -42,6 +44,10 @@ The same mechanism can hold a larger section. An HTML section might teach throug
42
44
 
43
45
  This sentence appears only in the Markdown twin.
44
46
 
47
+ ## Attributes
48
+
49
+ The build validates the contents of both blocks, including their links and supported components. `<Only>` needs block content and exactly one literal `format` attribute: `html` or `markdown`. Dynamic expressions and other values fail the build.
50
+
45
51
  ## HTML, Markdown, and agents
46
52
 
47
53
  An agent that fetches the direct `.md` URL, or requests this page with `Accept: text/markdown` on a host that supports [content negotiation](https://www.shoalrun.com/publish/content-negotiation.md), receives the shared text and `format="markdown"` blocks. It does not receive `format="html"` blocks. For the live example above, the relevant Markdown line is:
@@ -50,8 +56,6 @@ An agent that fetches the direct `.md` URL, or requests this page with `Accept:
50
56
  This sentence appears only in the Markdown twin.
51
57
  ```
52
58
 
53
- The build validates the contents of both blocks, including their links and supported components. `<Only>` needs block content and exactly one literal `format` attribute: `html` or `markdown`. Dynamic expressions and other values fail the build.
54
-
55
59
  Keep facts, warnings, and task steps that both readers need outside `<Only>`, or provide suitable versions in both formats. You can add or suppress content in either output when that helps its intended reader. Check that each version remains accurate and usable for its task; see [Shoalrun's position on shared and format-specific content](https://www.shoalrun.com/publish/agent-friendliness.md). The browser search index uses the HTML output, so Markdown-only text is not included in that search. See [publishing and agent representations](https://www.shoalrun.com/publish/output.md) for the full output contract.
56
60
 
57
61
  ## Related reading
package/agent-docs/author/components/progress.md CHANGED
@@ -12,11 +12,11 @@ canonical: /author/components/progress
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Progress
17
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Progress
18
18
 
19
- **Updated: 2026-10-26.**
19
+ **Updated: 2026-10-27.**
20
20
 
21
21
  Use `<Progress>` for a published count in a tutorial or migration guide. It shows the amount completed as text and as a bar. Update the source and rebuild the site when the shared state changes.
22
22
 
@@ -28,6 +28,10 @@ Use `<Progress>` for a published count in a tutorial or migration guide. It show
28
28
 
29
29
  Migration tasks: 3 of 5 complete.
30
30
 
31
+ ## Attributes
32
+
33
+ Use these attributes to configure the component.
34
+
31
35
  | Attribute | Required | Meaning |
32
36
  | --------- | -------- | --------------------------------------------------------------------------- |
33
37
  | `label` | Yes | Nonempty name shown beside the count and used as the bar's accessible name. |
package/agent-docs/author/components/related-reading.md CHANGED
@@ -12,11 +12,11 @@ canonical: /author/components/related-reading
12
12
 
13
13
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
14
14
 
15
- 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)
15
+ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > RelatedReading
17
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > RelatedReading
18
18
 
19
- **Updated: 2026-10-26.**
19
+ **Updated: 2026-10-27.**
20
20
 
21
21
  `<RelatedReading>` presents connections declared in the central `relationships` config. Use it for prerequisites, next steps, references, related topics, and distinctions that need a reason.
22
22
 
@@ -26,6 +26,10 @@ Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write docume
26
26
  <RelatedReading relation="next-step" />
27
27
  ```
28
28
 
29
+ ## Attributes
30
+
31
+ Use these attributes to configure the component.
32
+
29
33
  | Attribute | Meaning |
30
34
  | ----------- | ------------------------------------------------------------------------------------------- |
31
35
  | `relation` | Select one relationship type; omit for all types grouped by purpose. |
package/agent-docs/author/components/steps.md CHANGED
@@ -13,14 +13,16 @@ canonical: /author/components/steps
13
13
 
14
14
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
15
15
 
16
- 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)
16
+ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
17
17
 
18
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Steps
18
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Steps
19
19
 
20
- **Updated: 2026-10-25.**
20
+ **Updated: 2026-10-27.**
21
21
 
22
22
  Use `<Steps>` when each part of a procedure needs a title and supporting content. For a simple sequence with no step titles, an ordinary Markdown numbered list is enough. For code that changes between steps, use a [Walkthrough](https://www.shoalrun.com/author/components/walkthroughs.md).
23
23
 
24
+ ## Syntax
25
+
24
26
  ```mdx
25
27
  <Steps>
26
28
  <Step title="Create a page">
@@ -74,6 +76,10 @@ Run `shoalrun build docs.config.yaml dist`, then open the output.
74
76
 
75
77
  Build and deploy the site.
76
78
 
79
+ ## Attributes
80
+
81
+ Use these attributes to configure the component.
82
+
77
83
  | Attribute | Where | Meaning |
78
84
  | -------------- | ------- | ----------------------------------------------------------------------------------------------------- |
79
85
  | `variant` | `Steps` | `rail` (default), `cards`, or `plain`. |
package/agent-docs/author/components/tables.md CHANGED
@@ -13,14 +13,16 @@ canonical: /author/components/tables
13
13
 
14
14
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
15
15
 
16
- 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)
16
+ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
17
17
 
18
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Components > Tables
18
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Tables
19
19
 
20
- **Updated: 2026-10-19.**
20
+ **Updated: 2026-10-27.**
21
21
 
22
22
  Ordinary Markdown tables work without a component. For a long table, wrap one table in `<Table>` to add a filter box, sticky column headings, or both in HTML:
23
23
 
24
+ ## Syntax
25
+
24
26
  ```mdx
25
27
  <Table filter sticky>
26
28
 
@@ -32,6 +34,8 @@ Ordinary Markdown tables work without a component. For a long table, wrap one ta
32
34
  </Table>
33
35
  ```
34
36
 
37
+ ## Attributes
38
+
35
39
  `filter` and `sticky` are bare boolean attributes. Use either one alone or both. `<Table>` takes exactly one Markdown table and no other content. Its complete table, without controls, appears in the [Markdown twin](https://www.shoalrun.com/author/components/tables.md).
36
40
 
37
41
  ## Try the controls