@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/search.sections/read-a-search-result-with-an-agent.md CHANGED
@@ -14,7 +14,7 @@ canonical: /author/search
14
14
 
15
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)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Site search
17
+ Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/search.sections/related-reading.md CHANGED
@@ -14,7 +14,7 @@ canonical: /author/search
14
14
 
15
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)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Site search
17
+ Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/search.sections/reuse-the-lexical-index.md CHANGED
@@ -14,7 +14,7 @@ canonical: /author/search
14
14
 
15
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)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Site search
17
+ Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/search.sections/turn-search-off.md CHANGED
@@ -14,7 +14,7 @@ canonical: /author/search
14
14
 
15
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)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Site search
17
+ Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/search.sections/use-the-search-box.md CHANGED
@@ -14,7 +14,7 @@ canonical: /author/search
14
14
 
15
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)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Site search
17
+ Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/search.sections/write-a-custom-provider.md CHANGED
@@ -14,7 +14,7 @@ canonical: /author/search
14
14
 
15
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)
16
16
 
17
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Site search
17
+ Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
18
18
 
19
19
  **Updated: 2026-10-26.**
20
20
 
package/agent-docs/author/snippets.md CHANGED
@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
16
16
 
17
17
  Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Reusable snippets
18
18
 
19
- **Updated: 2026-10-26.**
19
+ **Updated: 2026-10-27.**
20
20
 
21
21
  A snippet is a shared Markdown or MDX fragment that the build expands into each page that includes it. Use one when the wording must stay in sync across pages. A [template](https://www.shoalrun.com/author/templates.md) creates a draft once; editing a template does not change existing pages.
22
22
 
@@ -107,6 +107,10 @@ The included Markdown and supported MDX components render in both HTML and Markd
107
107
 
108
108
  Build your project and open each page that includes the snippet. Confirm that HTML and Markdown both contain the resolved text and that no variable tags remain. Change the snippet source and rebuild; every including page should receive that change. If validation fails, correct the named variable, include, or type before publishing.
109
109
 
110
+ ## HTML, Markdown, and agents
111
+
112
+ The build expands snippets and variables into the containing page before rendering HTML and Markdown. Agents read the resolved text, not a `Snippet` or `Var` instruction to execute. Components inside a snippet retain their own output behavior; for example, an interactive control can become ordinary text in Markdown. Verify the including page in both formats after changing shared content.
113
+
110
114
  ## Related reading
111
115
 
112
116
  ### Reference while working
package/agent-docs/author/taxonomy.md CHANGED
@@ -15,7 +15,7 @@ canonical: /author/taxonomy
15
15
 
16
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)
17
17
 
18
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Metadata > Design and enforce a page taxonomy
18
+ Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Design and enforce a page taxonomy
19
19
 
20
20
  **Updated: 2026-10-25.**
21
21
 
package/agent-docs/author/templates.md CHANGED
@@ -14,11 +14,11 @@ canonical: /author/templates
14
14
 
15
15
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
16
16
 
17
- 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)
17
+ 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)
18
18
 
19
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Templates
19
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
20
20
 
21
- **Updated: 2026-10-26.**
21
+ **Updated: 2026-10-27.**
22
22
 
23
23
  A template supplies the starting page for a new one: commented frontmatter and a body of prompts. It tells authors and agents what to write, in what order, and what to delete. `scaffold` copies the template once and fills in the draft fields. The result is an ordinary page that authors can change. Editing a template later affects future drafts, not pages already scaffolded.
24
24
 
@@ -90,18 +90,18 @@ The primary Diátaxis templates use these authoring conventions; workflow templa
90
90
 
91
91
  ## Scaffold a page
92
92
 
93
- Use a built-in template, or a template registered by your project. From the project directory, with `SHOALRUN_CLI` set as in the [quickstart](https://www.shoalrun.com/start.md):
93
+ Use a built-in template, or a template registered by your project. From the project directory, with `@shoalrun/cli` installed as in the [quickstart](https://www.shoalrun.com/start.md):
94
94
 
95
95
  ```sh
96
- node "$SHOALRUN_CLI" scaffold how-to -n content/track-parcel.mdx
96
+ npx --no-install shoalrun scaffold how-to -n content/track-parcel.mdx
97
97
  ```
98
98
 
99
99
  Follow [create a page](https://www.shoalrun.com/author/add-page.md) to complete the draft, review it, set public access, and add it to navigation. Register a custom template only when your project needs a different starting structure.
100
100
 
101
- The built-in `api-reference` template needs `--operation`. To scaffold from it, run this explicit form from the **repository root**:
101
+ The built-in `api-reference` template needs `--operation`. To scaffold from it, run this form from your documentation project after [registering the operation](https://www.shoalrun.com/publish/api-references.md):
102
102
 
103
103
  ```sh
104
- node framework/dist/cli.js scaffold api-reference docs/docs.config.yaml docs/content/new-operation.mdx \
104
+ npx --no-install shoalrun scaffold api-reference docs.config.yaml content/new-operation.mdx \
105
105
  --id reference.new --title 'New operation' --summary 'Create a thing.' --slug /reference/new \
106
106
  --operation notes.create
107
107
  ```
package/agent-docs/author/templates.sections/built-in-feature-templates.md CHANGED
@@ -14,11 +14,11 @@ canonical: /author/templates
14
14
 
15
15
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
16
16
 
17
- 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)
17
+ 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)
18
18
 
19
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Templates
19
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
20
20
 
21
- **Updated: 2026-10-26.**
21
+ **Updated: 2026-10-27.**
22
22
 
23
23
  Parent page: [Full Markdown page](/author/templates.md)
24
24
 
package/agent-docs/author/templates.sections/built-in-templates.md CHANGED
@@ -14,11 +14,11 @@ canonical: /author/templates
14
14
 
15
15
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
16
16
 
17
- 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)
17
+ 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)
18
18
 
19
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Templates
19
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
20
20
 
21
- **Updated: 2026-10-26.**
21
+ **Updated: 2026-10-27.**
22
22
 
23
23
  Parent page: [Full Markdown page](/author/templates.md)
24
24
 
package/agent-docs/author/templates.sections/choose-formatting-enforcement-for-your-project.md CHANGED
@@ -14,11 +14,11 @@ canonical: /author/templates
14
14
 
15
15
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
16
16
 
17
- 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)
17
+ 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)
18
18
 
19
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Templates
19
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
20
20
 
21
- **Updated: 2026-10-26.**
21
+ **Updated: 2026-10-27.**
22
22
 
23
23
  Parent page: [Full Markdown page](/author/templates.md)
24
24
 
package/agent-docs/author/templates.sections/create-or-edit-a-project-template.md CHANGED
@@ -14,11 +14,11 @@ canonical: /author/templates
14
14
 
15
15
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
16
16
 
17
- 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)
17
+ 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)
18
18
 
19
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Templates
19
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
20
20
 
21
- **Updated: 2026-10-26.**
21
+ **Updated: 2026-10-27.**
22
22
 
23
23
  Parent page: [Full Markdown page](/author/templates.md)
24
24
 
package/agent-docs/author/templates.sections/keep-the-four-shapes-distinct.md CHANGED
@@ -14,11 +14,11 @@ canonical: /author/templates
14
14
 
15
15
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
16
16
 
17
- 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)
17
+ 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)
18
18
 
19
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Templates
19
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
20
20
 
21
- **Updated: 2026-10-26.**
21
+ **Updated: 2026-10-27.**
22
22
 
23
23
  Parent page: [Full Markdown page](/author/templates.md)
24
24
 
package/agent-docs/author/templates.sections/project-added-templates.md CHANGED
@@ -14,11 +14,11 @@ canonical: /author/templates
14
14
 
15
15
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
16
16
 
17
- 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)
17
+ 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)
18
18
 
19
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Templates
19
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
20
20
 
21
- **Updated: 2026-10-26.**
21
+ **Updated: 2026-10-27.**
22
22
 
23
23
  Parent page: [Full Markdown page](/author/templates.md)
24
24
 
package/agent-docs/author/templates.sections/related-reading.md CHANGED
@@ -14,11 +14,11 @@ canonical: /author/templates
14
14
 
15
15
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
16
16
 
17
- 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)
17
+ 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)
18
18
 
19
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Templates
19
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
20
20
 
21
- **Updated: 2026-10-26.**
21
+ **Updated: 2026-10-27.**
22
22
 
23
23
  Parent page: [Full Markdown page](/author/templates.md)
24
24
 
package/agent-docs/author/templates.sections/scaffold-a-page.md CHANGED
@@ -14,11 +14,11 @@ canonical: /author/templates
14
14
 
15
15
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
16
16
 
17
- 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)
17
+ 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)
18
18
 
19
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Templates
19
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
20
20
 
21
- **Updated: 2026-10-26.**
21
+ **Updated: 2026-10-27.**
22
22
 
23
23
  Parent page: [Full Markdown page](/author/templates.md)
24
24
 
@@ -34,18 +34,18 @@ Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose
34
34
 
35
35
  ## Scaffold a page
36
36
 
37
- Use a built-in template, or a template registered by your project. From the project directory, with `SHOALRUN_CLI` set as in the [quickstart](https://www.shoalrun.com/start.md):
37
+ Use a built-in template, or a template registered by your project. From the project directory, with `@shoalrun/cli` installed as in the [quickstart](https://www.shoalrun.com/start.md):
38
38
 
39
39
  ```sh
40
- node "$SHOALRUN_CLI" scaffold how-to -n content/track-parcel.mdx
40
+ npx --no-install shoalrun scaffold how-to -n content/track-parcel.mdx
41
41
  ```
42
42
 
43
43
  Follow [create a page](https://www.shoalrun.com/author/add-page.md) to complete the draft, review it, set public access, and add it to navigation. Register a custom template only when your project needs a different starting structure.
44
44
 
45
- The built-in `api-reference` template needs `--operation`. To scaffold from it, run this explicit form from the **repository root**:
45
+ The built-in `api-reference` template needs `--operation`. To scaffold from it, run this form from your documentation project after [registering the operation](https://www.shoalrun.com/publish/api-references.md):
46
46
 
47
47
  ```sh
48
- node framework/dist/cli.js scaffold api-reference docs/docs.config.yaml docs/content/new-operation.mdx \
48
+ npx --no-install shoalrun scaffold api-reference docs.config.yaml content/new-operation.mdx \
49
49
  --id reference.new --title 'New operation' --summary 'Create a thing.' --slug /reference/new \
50
50
  --operation notes.create
51
51
  ```
package/agent-docs/author/templates.sections/short-cli-and-derived-values.md CHANGED
@@ -14,11 +14,11 @@ canonical: /author/templates
14
14
 
15
15
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
16
16
 
17
- 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)
17
+ 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)
18
18
 
19
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Templates
19
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
20
20
 
21
- **Updated: 2026-10-26.**
21
+ **Updated: 2026-10-27.**
22
22
 
23
23
  Parent page: [Full Markdown page](/author/templates.md)
24
24
 
package/agent-docs/author/templates.sections/what-every-template-gives-you.md CHANGED
@@ -14,11 +14,11 @@ canonical: /author/templates
14
14
 
15
15
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
16
16
 
17
- 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)
17
+ 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)
18
18
 
19
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Templates
19
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
20
20
 
21
- **Updated: 2026-10-26.**
21
+ **Updated: 2026-10-27.**
22
22
 
23
23
  Parent page: [Full Markdown page](/author/templates.md)
24
24
 
package/agent-docs/author/workspace/commands.md CHANGED
@@ -16,9 +16,9 @@ canonical: /author/workspace/commands
16
16
 
17
17
  > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
18
18
 
19
- 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)
19
+ 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)
20
20
 
21
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Project tools > Commands
21
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > Commands
22
22
 
23
23
  **Updated: 2026-10-27.**
24
24
 
package/agent-docs/author/workspace.md CHANGED
@@ -18,7 +18,7 @@ canonical: /author/workspace
18
18
 
19
19
  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)
20
20
 
21
- Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Project tools > Check edits
21
+ Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Check edits
22
22
 
23
23
  **Updated: 2026-10-27.**
24
24
 
package/agent-docs/author/writing-style.md CHANGED
@@ -13,11 +13,11 @@ canonical: /author/writing-style
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 > Write with agents > Shared writing guidance > Example writing guide
18
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
19
19
 
20
- **Updated: 2026-10-26.**
20
+ **Updated: 2026-10-27.**
21
21
 
22
22
  This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
23
23
 
@@ -44,7 +44,15 @@ Choose the page type by the reader's goal and the actual content. Keep one prima
44
44
  | Cookbook | Choose between complete recipes. | Explain who each path is for, what it needs, and what it produces; link to the published recipe pages. State whether choices are alternatives or can be combined. |
45
45
  | Changelog entry | Understand a dated change. | User-visible behavior, scope, migration when needed, and limitations. Say when a change concerns the private prototype; claim a release only with release evidence. |
46
46
 
47
- These are editorial shapes, not mandatory heading names. Follow the [template rules](https://www.shoalrun.com/author/templates.md) and adapt the outline to the reader's need. Headings in a page body start at level two because the renderer supplies the title. Do not add step numbers to authored headings. For a procedure with titled steps, use the [Steps component](https://www.shoalrun.com/author/components/steps.md); it supplies the numbering in HTML and Markdown.
47
+ Use **Before you begin**, **Check the result**, and **Next steps** for recurring task sections when revising a procedure. Keep action headings specific to the task. Existing tutorials can retain established headings when tools or incoming fragments depend on them. A short procedure may put prerequisites in its introduction; omit sections that add no useful information.
48
+
49
+ Component references use **Syntax**, **Attributes**, and **HTML, Markdown, and agents** for predictable lookup. Document required values, defaults, accepted types, and constraints in Attributes; say when a component takes no attributes. Keep feature-specific examples and errors under descriptive headings. Fenced-code options and configured site features can use their own precise labels. Preserve old fragment IDs when changing a heading.
50
+
51
+ Use **Next steps** to continue a task and **Related reading** for supporting reference or explanation. Describe why to follow each link. Keep demo headings separate from the page's instructional outline where possible.
52
+
53
+ Run customer commands from a project with the pinned npm package installed, using `npx --no-install shoalrun`. Label contributor-only paths and repository scripts explicitly. Do not assume the quickstart compiled a framework checkout. Recipes maintained through composition must declare every required artifact, including a current build before an export.
54
+
55
+ These are editorial shapes, not a reason to add empty boilerplate. Follow the [template rules](https://www.shoalrun.com/author/templates.md) and adapt the outline to the reader's need. Headings in a page body start at level two because the renderer supplies the title. Do not add step numbers to authored headings. For a procedure with titled steps, use the [Steps component](https://www.shoalrun.com/author/components/steps.md); it supplies the numbering in HTML and Markdown.
48
56
 
49
57
  ## Voice and explanations
50
58
 
@@ -97,7 +105,9 @@ Choose the structure that helps readers use the information or complete the task
97
105
 
98
106
  Introduce every table with a sentence explaining what readers should use it for. Never place a table directly after a heading. The formatting check enforces this rule with `DocShape.TableIntroduction`.
99
107
 
100
- Do not hide an essential instruction inside decoration. For component references, include supported syntax, attributes and limits, and an **HTML, Markdown, and agents** section. Explain keyboard behavior when there are controls, behavior without JavaScript, and the content available in Markdown. Check both rendered outputs.
108
+ Do not hide an essential instruction inside decoration. Every page documenting a component or presentation feature needs an **HTML, Markdown, and agents** section, or an existing clearly named equivalent. Explain what HTML shows or lets readers do, what Markdown retains or omits, and how an agent gets the information needed for the task. Include limitations and keyboard or JavaScript behavior when relevant. Check both rendered outputs.
109
+
110
+ A page that merely uses a callout, link, or Steps component needs the section only when that use changes access to information. Avoid generic claims that both formats are identical: explain the actual representation. Cookbook pages must distinguish their recipe links from the complete instructions in the linked recipes or a downloaded selection.
101
111
 
102
112
  ## Evidence and uncertainty
103
113
 
package/agent-docs/author/writing-style.sections/adapt-this-example.md CHANGED
@@ -13,11 +13,11 @@ canonical: /author/writing-style
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 > Write with agents > Shared writing guidance > Example writing guide
18
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
19
19
 
20
- **Updated: 2026-10-26.**
20
+ **Updated: 2026-10-27.**
21
21
 
22
22
  Parent page: [Full Markdown page](/author/writing-style.md)
23
23
 
package/agent-docs/author/writing-style.sections/choose-components-by-reader-need.md CHANGED
@@ -13,11 +13,11 @@ canonical: /author/writing-style
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 > Write with agents > Shared writing guidance > Example writing guide
18
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
19
19
 
20
- **Updated: 2026-10-26.**
20
+ **Updated: 2026-10-27.**
21
21
 
22
22
  Parent page: [Full Markdown page](/author/writing-style.md)
23
23
 
@@ -39,4 +39,6 @@ Choose the structure that helps readers use the information or complete the task
39
39
 
40
40
  Introduce every table with a sentence explaining what readers should use it for. Never place a table directly after a heading. The formatting check enforces this rule with `DocShape.TableIntroduction`.
41
41
 
42
- Do not hide an essential instruction inside decoration. For component references, include supported syntax, attributes and limits, and an **HTML, Markdown, and agents** section. Explain keyboard behavior when there are controls, behavior without JavaScript, and the content available in Markdown. Check both rendered outputs.
42
+ Do not hide an essential instruction inside decoration. Every page documenting a component or presentation feature needs an **HTML, Markdown, and agents** section, or an existing clearly named equivalent. Explain what HTML shows or lets readers do, what Markdown retains or omits, and how an agent gets the information needed for the task. Include limitations and keyboard or JavaScript behavior when relevant. Check both rendered outputs.
43
+
44
+ A page that merely uses a callout, link, or Steps component needs the section only when that use changes access to information. Avoid generic claims that both formats are identical: explain the actual representation. Cookbook pages must distinguish their recipe links from the complete instructions in the linked recipes or a downloaded selection.
package/agent-docs/author/writing-style.sections/evidence-and-uncertainty.md CHANGED
@@ -13,11 +13,11 @@ canonical: /author/writing-style
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 > Write with agents > Shared writing guidance > Example writing guide
18
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
19
19
 
20
- **Updated: 2026-10-26.**
20
+ **Updated: 2026-10-27.**
21
21
 
22
22
  Parent page: [Full Markdown page](/author/writing-style.md)
23
23
 
package/agent-docs/author/writing-style.sections/example-audience-and-scope.md CHANGED
@@ -13,11 +13,11 @@ canonical: /author/writing-style
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 > Write with agents > Shared writing guidance > Example writing guide
18
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
19
19
 
20
- **Updated: 2026-10-26.**
20
+ **Updated: 2026-10-27.**
21
21
 
22
22
  Parent page: [Full Markdown page](/author/writing-style.md)
23
23
 
package/agent-docs/author/writing-style.sections/ingredients-recipes-and-cookbooks.md CHANGED
@@ -13,11 +13,11 @@ canonical: /author/writing-style
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 > Write with agents > Shared writing guidance > Example writing guide
18
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
19
19
 
20
- **Updated: 2026-10-26.**
20
+ **Updated: 2026-10-27.**
21
21
 
22
22
  Parent page: [Full Markdown page](/author/writing-style.md)
23
23
 
package/agent-docs/author/writing-style.sections/page-purpose-and-structure.md CHANGED
@@ -13,11 +13,11 @@ canonical: /author/writing-style
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 > Write with agents > Shared writing guidance > Example writing guide
18
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
19
19
 
20
- **Updated: 2026-10-26.**
20
+ **Updated: 2026-10-27.**
21
21
 
22
22
  Parent page: [Full Markdown page](/author/writing-style.md)
23
23
 
@@ -38,4 +38,12 @@ Choose the page type by the reader's goal and the actual content. Keep one prima
38
38
  | Cookbook | Choose between complete recipes. | Explain who each path is for, what it needs, and what it produces; link to the published recipe pages. State whether choices are alternatives or can be combined. |
39
39
  | Changelog entry | Understand a dated change. | User-visible behavior, scope, migration when needed, and limitations. Say when a change concerns the private prototype; claim a release only with release evidence. |
40
40
 
41
- These are editorial shapes, not mandatory heading names. Follow the [template rules](https://www.shoalrun.com/author/templates.md) and adapt the outline to the reader's need. Headings in a page body start at level two because the renderer supplies the title. Do not add step numbers to authored headings. For a procedure with titled steps, use the [Steps component](https://www.shoalrun.com/author/components/steps.md); it supplies the numbering in HTML and Markdown.
41
+ Use **Before you begin**, **Check the result**, and **Next steps** for recurring task sections when revising a procedure. Keep action headings specific to the task. Existing tutorials can retain established headings when tools or incoming fragments depend on them. A short procedure may put prerequisites in its introduction; omit sections that add no useful information.
42
+
43
+ Component references use **Syntax**, **Attributes**, and **HTML, Markdown, and agents** for predictable lookup. Document required values, defaults, accepted types, and constraints in Attributes; say when a component takes no attributes. Keep feature-specific examples and errors under descriptive headings. Fenced-code options and configured site features can use their own precise labels. Preserve old fragment IDs when changing a heading.
44
+
45
+ Use **Next steps** to continue a task and **Related reading** for supporting reference or explanation. Describe why to follow each link. Keep demo headings separate from the page's instructional outline where possible.
46
+
47
+ Run customer commands from a project with the pinned npm package installed, using `npx --no-install shoalrun`. Label contributor-only paths and repository scripts explicitly. Do not assume the quickstart compiled a framework checkout. Recipes maintained through composition must declare every required artifact, including a current build before an export.
48
+
49
+ These are editorial shapes, not a reason to add empty boilerplate. Follow the [template rules](https://www.shoalrun.com/author/templates.md) and adapt the outline to the reader's need. Headings in a page body start at level two because the renderer supplies the title. Do not add step numbers to authored headings. For a procedure with titled steps, use the [Steps component](https://www.shoalrun.com/author/components/steps.md); it supplies the numbering in HTML and Markdown.
package/agent-docs/author/writing-style.sections/procedures-and-examples.md CHANGED
@@ -13,11 +13,11 @@ canonical: /author/writing-style
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 > Write with agents > Shared writing guidance > Example writing guide
18
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
19
19
 
20
- **Updated: 2026-10-26.**
20
+ **Updated: 2026-10-27.**
21
21
 
22
22
  Parent page: [Full Markdown page](/author/writing-style.md)
23
23
 
package/agent-docs/author/writing-style.sections/related-reading.md CHANGED
@@ -13,11 +13,11 @@ canonical: /author/writing-style
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 > Write with agents > Shared writing guidance > Example writing guide
18
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
19
19
 
20
- **Updated: 2026-10-26.**
20
+ **Updated: 2026-10-27.**
21
21
 
22
22
  Parent page: [Full Markdown page](/author/writing-style.md)
23
23
 
package/agent-docs/author/writing-style.sections/review-a-draft.md CHANGED
@@ -13,11 +13,11 @@ canonical: /author/writing-style
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 > Write with agents > Shared writing guidance > Example writing guide
18
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
19
19
 
20
- **Updated: 2026-10-26.**
20
+ **Updated: 2026-10-27.**
21
21
 
22
22
  Parent page: [Full Markdown page](/author/writing-style.md)
23
23
 
package/agent-docs/author/writing-style.sections/reviewed-writing-examples.md CHANGED
@@ -13,11 +13,11 @@ canonical: /author/writing-style
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 > Write with agents > Shared writing guidance > Example writing guide
18
+ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
19
19
 
20
- **Updated: 2026-10-26.**
20
+ **Updated: 2026-10-27.**
21
21
 
22
22
  Parent page: [Full Markdown page](/author/writing-style.md)
23
23