@shoalrun/cli 0.1.0-alpha.17 → 0.1.0-alpha.19

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 (686) hide show
  1. package/AUTHORING.md +29 -0
  2. package/CHANGELOG.md +54 -0
  3. package/DEPLOYMENT-PROFILES.md +96 -5
  4. package/README.md +106 -25
  5. package/agent-docs/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt +23 -17
  6. package/agent-docs/SNAPSHOT.json +5 -5
  7. package/agent-docs/api-docs/focused-contracts.md +4 -4
  8. package/agent-docs/api-docs/generate.md +11 -11
  9. package/agent-docs/api-docs/generate.sections/add-useful-examples.md +3 -3
  10. package/agent-docs/api-docs/generate.sections/choose-generated-references-or-mdx.md +4 -4
  11. package/agent-docs/api-docs/generate.sections/describe-filters-that-do-not-use-their-openapi-parameter-name.md +1 -1
  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 +1 -1
  14. package/agent-docs/api-docs/generate.sections/map-extension-values-to-shoalrun-status.md +1 -1
  15. package/agent-docs/api-docs/generate.sections/override-generated-reference-order-in-navigation.md +4 -4
  16. package/agent-docs/api-docs/generate.sections/related-reading.md +1 -1
  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 +7 -7
  19. package/agent-docs/author/add-page.md +3 -3
  20. package/agent-docs/author/agent-overview.md +3 -3
  21. package/agent-docs/author/agent-workflow.md +7 -7
  22. package/agent-docs/author/analytics.md +27 -27
  23. package/agent-docs/author/analytics.sections/adapter-exports-and-consent.md +3 -3
  24. package/agent-docs/author/analytics.sections/built-in-events.md +15 -15
  25. package/agent-docs/author/analytics.sections/configure-an-adapter.md +1 -1
  26. package/agent-docs/author/analytics.sections/custom-interactions.md +2 -2
  27. package/agent-docs/author/analytics.sections/event-format.md +2 -2
  28. package/agent-docs/author/analytics.sections/html-markdown-and-agents.md +4 -4
  29. package/agent-docs/author/analytics.sections/inspect-events-locally.md +2 -2
  30. package/agent-docs/author/analytics.sections/map-events-to-your-service.md +3 -3
  31. package/agent-docs/author/analytics.sections/posthog-example.md +3 -3
  32. package/agent-docs/author/analytics.sections/related-reading.md +1 -1
  33. package/agent-docs/author/authoring-agent.md +3 -3
  34. package/agent-docs/author/coding-agent.md +4 -4
  35. package/agent-docs/author/components/api-embeds.md +6 -6
  36. package/agent-docs/author/components/api-embeds.sections/apiexample.md +3 -3
  37. package/agent-docs/author/components/api-embeds.sections/html-markdown-and-agents.md +1 -1
  38. package/agent-docs/author/components/api-embeds.sections/related-reading.md +1 -1
  39. package/agent-docs/author/components/badge.md +2 -2
  40. package/agent-docs/author/components/callout.md +2 -2
  41. package/agent-docs/author/components/cards.md +16 -16
  42. package/agent-docs/author/components/cards.sections/add-a-lucide-icon.md +4 -4
  43. package/agent-docs/author/components/cards.sections/build-a-collection.md +7 -7
  44. package/agent-docs/author/components/cards.sections/curate-a-reading-list.md +9 -9
  45. package/agent-docs/author/components/cards.sections/html-markdown-and-agents.md +3 -3
  46. package/agent-docs/author/components/cards.sections/link-to-one-document.md +3 -3
  47. package/agent-docs/author/components/cards.sections/override-card-text.md +5 -5
  48. package/agent-docs/author/components/cards.sections/related-reading.md +3 -3
  49. package/agent-docs/author/components/code-blocks.md +2 -2
  50. package/agent-docs/author/components/collapsible.md +3 -3
  51. package/agent-docs/author/components/cookbook-chooser.md +5 -5
  52. package/agent-docs/author/components/custom/react.md +8 -8
  53. package/agent-docs/author/components/custom/react.sections/html-markdown-and-agents.md +3 -3
  54. package/agent-docs/author/components/custom/react.sections/interactive-react-example.md +2 -2
  55. package/agent-docs/author/components/custom/react.sections/registration.md +1 -1
  56. package/agent-docs/author/components/custom/react.sections/related-reading.md +1 -1
  57. package/agent-docs/author/components/custom/react.sections/share-the-model-with-the-browser.md +3 -3
  58. package/agent-docs/author/components/custom/react.sections/where-the-content-lives.md +3 -3
  59. package/agent-docs/author/components/custom.md +7 -7
  60. package/agent-docs/author/components/definition-list.md +2 -2
  61. package/agent-docs/author/components/diagrams/d2-gallery.md +2 -2
  62. package/agent-docs/author/components/diagrams/d2-gallery.sections/basic-shapes.md +2 -2
  63. package/agent-docs/author/components/diagrams/d2-gallery.sections/flows-and-structures.md +2 -2
  64. package/agent-docs/author/components/diagrams/d2-gallery.sections/html-markdown-and-agents.md +2 -2
  65. package/agent-docs/author/components/diagrams/d2-gallery.sections/layout-engines.md +2 -2
  66. package/agent-docs/author/components/diagrams/d2-gallery.sections/related-reading.md +2 -2
  67. package/agent-docs/author/components/diagrams/d2-gallery.sections/sequences-and-grids.md +2 -2
  68. package/agent-docs/author/components/diagrams/d2-gallery.sections/styles-and-code.md +2 -2
  69. package/agent-docs/author/components/diagrams/pele-gallery.md +3 -3
  70. package/agent-docs/author/components/diagrams/pele-gallery.sections/charts-and-planning.md +2 -2
  71. package/agent-docs/author/components/diagrams/pele-gallery.sections/flowchart-shapes.md +2 -2
  72. package/agent-docs/author/components/diagrams/pele-gallery.sections/flows-and-behavior.md +2 -2
  73. package/agent-docs/author/components/diagrams/pele-gallery.sections/html-markdown-and-agents.md +3 -3
  74. package/agent-docs/author/components/diagrams/pele-gallery.sections/related-reading.md +2 -2
  75. package/agent-docs/author/components/diagrams/pele-gallery.sections/specialized-diagrams.md +2 -2
  76. package/agent-docs/author/components/diagrams/pele-gallery.sections/systems-and-structures.md +2 -2
  77. package/agent-docs/author/components/diagrams.md +8 -8
  78. package/agent-docs/author/components/doc-link.md +3 -3
  79. package/agent-docs/author/components/fields.md +18 -18
  80. package/agent-docs/author/components/file-tree.md +2 -2
  81. package/agent-docs/author/components/images.md +5 -5
  82. package/agent-docs/author/components/info-hint.md +3 -3
  83. package/agent-docs/author/components/kbd.md +2 -2
  84. package/agent-docs/author/components/math.md +2 -2
  85. package/agent-docs/author/components/only.md +3 -3
  86. package/agent-docs/author/components/progress.md +3 -3
  87. package/agent-docs/author/components/steps.md +2 -2
  88. package/agent-docs/author/components/tables.md +2 -2
  89. package/agent-docs/author/components/tabs.md +5 -5
  90. package/agent-docs/author/components/timeline.md +2 -2
  91. package/agent-docs/author/components/tooltips.md +2 -2
  92. package/agent-docs/author/components/walkthroughs.md +2 -2
  93. package/agent-docs/author/components/walkthroughs.sections/attributes.md +1 -1
  94. package/agent-docs/author/components/walkthroughs.sections/build-up-code.md +1 -1
  95. package/agent-docs/author/components/walkthroughs.sections/choose-a-layout.md +2 -2
  96. package/agent-docs/author/components/walkthroughs.sections/explain-one-file.md +1 -1
  97. package/agent-docs/author/components/walkthroughs.sections/html-markdown-and-agents.md +1 -1
  98. package/agent-docs/author/components/walkthroughs.sections/related-reading.md +1 -1
  99. package/agent-docs/author/components/walkthroughs.sections/syntax.md +1 -1
  100. package/agent-docs/author/components/walkthroughs.sections/take-code-from-a-file.md +1 -1
  101. package/agent-docs/author/components.md +2 -2
  102. package/agent-docs/author/content.md +3 -3
  103. package/agent-docs/author/cookbooks.md +9 -9
  104. package/agent-docs/author/css.md +4 -4
  105. package/agent-docs/author/css.sections/borders-fields-and-navigation-tokens.md +3 -3
  106. package/agent-docs/author/css.sections/core-color-tokens.md +3 -3
  107. package/agent-docs/author/css.sections/html-markdown-and-agents.md +4 -4
  108. package/agent-docs/author/css.sections/page-attributes.md +3 -3
  109. package/agent-docs/author/css.sections/page-transitions.md +3 -3
  110. package/agent-docs/author/css.sections/responsive-behavior.md +3 -3
  111. package/agent-docs/author/css.sections/status-code-and-callout-tokens.md +3 -3
  112. package/agent-docs/author/css.sections/typography-shape-and-width-tokens.md +3 -3
  113. package/agent-docs/author/custom-metadata.md +13 -13
  114. package/agent-docs/author/custom-metadata.sections/add-a-custom-page-field.md +4 -4
  115. package/agent-docs/author/custom-metadata.sections/choose-text-for-each-surface.md +3 -3
  116. package/agent-docs/author/custom-metadata.sections/preview-changes-to-metadata-providers.md +2 -2
  117. package/agent-docs/author/custom-metadata.sections/read-metadata-from-a-project-module.md +3 -3
  118. package/agent-docs/author/custom-metadata.sections/related-reading.md +1 -1
  119. package/agent-docs/author/design-templates.md +3 -3
  120. package/agent-docs/author/design-writing-guides.md +3 -3
  121. package/agent-docs/author/frontmatter-reference.md +45 -6
  122. package/agent-docs/author/frontmatter-reference.sections/categorize-connect-and-present-the-page.md +64 -0
  123. package/agent-docs/author/frontmatter-reference.sections/choose-a-publication-and-visibility.md +2 -2
  124. package/agent-docs/author/frontmatter-reference.sections/control-output-details.md +2 -2
  125. package/agent-docs/author/frontmatter-reference.sections/feature-availability.md +59 -0
  126. package/agent-docs/author/frontmatter-reference.sections/global-defaults-and-enforced-values.md +2 -2
  127. package/agent-docs/author/frontmatter-reference.sections/html-markdown-and-agents.md +3 -3
  128. package/agent-docs/author/frontmatter-reference.sections/identify-and-route-a-page.md +2 -2
  129. package/agent-docs/author/frontmatter-reference.sections/point-agents-to-it.md +2 -2
  130. package/agent-docs/author/frontmatter-reference.sections/product-publication-fields.md +37 -0
  131. package/agent-docs/author/frontmatter-reference.sections/project-defined-fields.md +2 -2
  132. package/agent-docs/author/frontmatter-reference.sections/related-reading.md +2 -2
  133. package/agent-docs/author/frontmatter-reference.sections/use-the-local-files-while-authoring.md +4 -4
  134. package/agent-docs/author/frontmatter-reference.sections/when-the-files-update.md +2 -2
  135. package/agent-docs/author/frontmatter.md +13 -13
  136. package/agent-docs/author/frontmatter.sections/audience-badges.md +3 -3
  137. package/agent-docs/author/frontmatter.sections/give-deprecation-guidance.md +4 -4
  138. package/agent-docs/author/frontmatter.sections/global-defaults-and-enforced-values.md +1 -1
  139. package/agent-docs/author/frontmatter.sections/optional-native-fields.md +4 -4
  140. package/agent-docs/author/frontmatter.sections/publication-fields.md +2 -2
  141. package/agent-docs/author/frontmatter.sections/publishing-policy.md +1 -1
  142. package/agent-docs/author/frontmatter.sections/related-metadata-tasks.md +1 -1
  143. package/agent-docs/author/frontmatter.sections/related-reading.md +1 -1
  144. package/agent-docs/author/frontmatter.sections/required-after-inheritance.md +1 -1
  145. package/agent-docs/author/frontmatter.sections/seo-fields.md +2 -2
  146. package/agent-docs/author/frontmatter.sections/validation-rules.md +3 -3
  147. package/agent-docs/author/markdown-metadata.md +20 -20
  148. package/agent-docs/author/navigation.md +12 -12
  149. package/agent-docs/author/navigation.sections/arrange-authored-pages.md +4 -4
  150. package/agent-docs/author/navigation.sections/fill-an-api-tag-group.md +2 -2
  151. package/agent-docs/author/navigation.sections/hide-group-page-counts.md +4 -4
  152. package/agent-docs/author/navigation.sections/html-markdown-and-agents.md +4 -4
  153. package/agent-docs/author/navigation.sections/local-api-preview.md +2 -2
  154. package/agent-docs/author/navigation.sections/mix-guides-and-api-references.md +3 -3
  155. package/agent-docs/author/navigation.sections/optionally-split-a-large-menu-into-files.md +2 -2
  156. package/agent-docs/author/navigation.sections/reach-navigation-while-reading.md +2 -2
  157. package/agent-docs/author/navigation.sections/related-reading.md +2 -2
  158. package/agent-docs/author/navigation.sections/split-navigation-into-tabs.md +4 -4
  159. package/agent-docs/author/navigation.sections/subject-lifecycle-labels.md +3 -3
  160. package/agent-docs/author/reader-views.md +9 -9
  161. package/agent-docs/author/reader-views.sections/configure-the-choices.md +2 -2
  162. package/agent-docs/author/reader-views.sections/connect-your-own-control.md +1 -1
  163. package/agent-docs/author/reader-views.sections/how-it-works-for-agents.md +3 -3
  164. package/agent-docs/author/reader-views.sections/mark-pages.md +3 -3
  165. package/agent-docs/author/reader-views.sections/mark-sections-and-add-an-entry-choice.md +2 -2
  166. package/agent-docs/author/reader-views.sections/place-filter-controls.md +2 -2
  167. package/agent-docs/author/reader-views.sections/try-the-controls-here.md +2 -2
  168. package/agent-docs/author/recipe-drafts.md +5 -5
  169. package/agent-docs/author/recipe-drafts.sections/1-write-one-reusable-step.md +2 -2
  170. package/agent-docs/author/recipe-drafts.sections/2-list-the-steps-for-one-complete-goal.md +2 -2
  171. package/agent-docs/author/recipe-drafts.sections/3-generate-a-draft-and-review-it.md +1 -1
  172. package/agent-docs/author/recipe-drafts.sections/4-maintain-shoalrun-s-published-recipe-snapshots.md +2 -2
  173. package/agent-docs/author/recipe-drafts.sections/related-reading.md +1 -1
  174. package/agent-docs/author/recipe-drafts.sections/start-an-ingredient-from-an-api-example.md +2 -2
  175. package/agent-docs/author/recipes.md +7 -7
  176. package/agent-docs/author/recipes.sections/how-agents-use-this.md +2 -2
  177. package/agent-docs/author/recipes.sections/one-example-from-shoalrun.md +2 -2
  178. package/agent-docs/author/recipes.sections/related-reading.md +1 -1
  179. package/agent-docs/author/recipes.sections/try-a-complete-workflow.md +1 -1
  180. package/agent-docs/author/recipes.sections/use-recipes-for-task-oriented-how-tos.md +3 -3
  181. package/agent-docs/author/recipes.sections/what-changing-an-ingredient-updates.md +2 -2
  182. package/agent-docs/author/recipes.sections/what-each-file-does.md +1 -1
  183. package/agent-docs/author/recipes.sections/what-happens-and-when.md +2 -2
  184. package/agent-docs/author/related-reading.md +11 -11
  185. package/agent-docs/author/related-reading.sections/automatic-footers.md +3 -3
  186. package/agent-docs/author/related-reading.sections/declare-relationships.md +3 -3
  187. package/agent-docs/author/related-reading.sections/display-related-documents.md +3 -3
  188. package/agent-docs/author/related-reading.sections/html-markdown-and-agents.md +1 -1
  189. package/agent-docs/author/related-reading.sections/inspect-output-and-changes.md +2 -2
  190. package/agent-docs/author/related-reading.sections/reading-paths-in-section-markdown.md +3 -3
  191. package/agent-docs/author/related-reading.sections/related-reading.md +1 -1
  192. package/agent-docs/author/related-reading.sections/where-relationship-explanations-come-from.md +2 -2
  193. package/agent-docs/author/release-notes.md +8 -8
  194. package/agent-docs/author/search.md +43 -39
  195. package/agent-docs/author/search.sections/agent-and-mcp-search-scope.md +12 -8
  196. package/agent-docs/author/search.sections/choose-a-provider.md +8 -8
  197. package/agent-docs/author/search.sections/cli-and-mcp-ranking-details.md +4 -4
  198. package/agent-docs/author/search.sections/enable-included-semantic-search.md +5 -5
  199. package/agent-docs/author/search.sections/hosted-semantic-search-limits.md +3 -3
  200. package/agent-docs/author/search.sections/html-markdown-and-agents.md +3 -3
  201. package/agent-docs/author/search.sections/lexical-search.md +6 -6
  202. package/agent-docs/author/search.sections/local-semantic-preview.md +3 -3
  203. package/agent-docs/author/search.sections/read-a-search-result-with-an-agent.md +2 -2
  204. package/agent-docs/author/search.sections/related-reading.md +2 -2
  205. package/agent-docs/author/search.sections/reuse-the-lexical-index.md +5 -5
  206. package/agent-docs/author/search.sections/turn-search-off.md +3 -3
  207. package/agent-docs/author/search.sections/use-the-search-box.md +2 -2
  208. package/agent-docs/author/search.sections/write-a-custom-provider.md +11 -11
  209. package/agent-docs/author/snippets.md +3 -3
  210. package/agent-docs/author/taxonomy.md +3 -3
  211. package/agent-docs/author/templates.md +16 -14
  212. package/agent-docs/author/templates.sections/built-in-feature-templates.md +2 -2
  213. package/agent-docs/author/templates.sections/built-in-templates.md +2 -2
  214. package/agent-docs/author/templates.sections/choose-formatting-enforcement-for-your-project.md +7 -7
  215. package/agent-docs/author/templates.sections/create-or-edit-a-project-template.md +8 -6
  216. package/agent-docs/author/templates.sections/keep-the-four-shapes-distinct.md +2 -2
  217. package/agent-docs/author/templates.sections/project-added-templates.md +3 -3
  218. package/agent-docs/author/templates.sections/related-reading.md +2 -2
  219. package/agent-docs/author/templates.sections/scaffold-a-page.md +2 -2
  220. package/agent-docs/author/templates.sections/short-cli-and-derived-values.md +3 -3
  221. package/agent-docs/author/templates.sections/what-every-template-gives-you.md +3 -3
  222. package/agent-docs/author/workspace/commands.md +4 -4
  223. package/agent-docs/author/workspace.md +7 -7
  224. package/agent-docs/author/writing-style.md +33 -18
  225. package/agent-docs/author/writing-style.sections/adapt-this-example.md +2 -2
  226. package/agent-docs/author/writing-style.sections/choose-components-by-reader-need.md +3 -3
  227. package/agent-docs/author/writing-style.sections/evidence-and-uncertainty.md +4 -4
  228. package/agent-docs/author/writing-style.sections/example-audience-and-scope.md +2 -2
  229. package/agent-docs/author/writing-style.sections/feature-availability.md +20 -7
  230. package/agent-docs/author/writing-style.sections/ingredients-recipes-and-cookbooks.md +5 -5
  231. package/agent-docs/author/writing-style.sections/page-purpose-and-structure.md +4 -4
  232. package/agent-docs/author/writing-style.sections/procedures-and-examples.md +4 -4
  233. package/agent-docs/author/writing-style.sections/related-reading.md +2 -2
  234. package/agent-docs/author/writing-style.sections/review-a-draft.md +3 -3
  235. package/agent-docs/author/writing-style.sections/reviewed-writing-examples.md +2 -2
  236. package/agent-docs/author/writing-style.sections/voice-and-explanations.md +4 -2
  237. package/agent-docs/changelog/2026-10-14-agent-readiness.md +2 -2
  238. package/agent-docs/changelog/2026-10-15-evaluation-builds.md +9 -9
  239. package/agent-docs/changelog/2026-10-16-navigation-layouts.md +4 -4
  240. package/agent-docs/changelog/2026-10-17-mcp-hosting.md +2 -2
  241. package/agent-docs/changelog/2026-10-18-search-and-tooltips.md +3 -3
  242. package/agent-docs/changelog/2026-10-19-visual-navigation.md +3 -3
  243. package/agent-docs/changelog/2026-10-25.md +2 -2
  244. package/agent-docs/changelog/2026-10-26.md +4 -4
  245. package/agent-docs/changelog/2026-10-27.md +1 -1
  246. package/agent-docs/changelog/2026-10-28.md +3 -3
  247. package/agent-docs/changelog/2026-10-30.md +1 -1
  248. package/agent-docs/changelog/2026-11-03.md +5 -5
  249. package/agent-docs/changelog/2026-11-04-runtime-packaging.md +46 -0
  250. package/agent-docs/changelog/authoring-preview.md +3 -3
  251. package/agent-docs/changelog/authoring-search.md +1 -1
  252. package/agent-docs/changelog/authoring-tools.md +2 -2
  253. package/agent-docs/changelog/branding-security.md +66 -0
  254. package/agent-docs/changelog/product-publications.md +60 -0
  255. package/agent-docs/changelog/working-tree-skill.md +1 -1
  256. package/agent-docs/changelog.md +25 -1
  257. package/agent-docs/chat/checks.md +11 -11
  258. package/agent-docs/chat/checks.sections/answer-ahead-of-time.md +1 -1
  259. package/agent-docs/chat/checks.sections/answer-for-one-audience.md +2 -2
  260. package/agent-docs/chat/checks.sections/answer-without-a-model.md +2 -2
  261. package/agent-docs/chat/checks.sections/follow-up-questions.md +2 -2
  262. package/agent-docs/chat/checks.sections/how-an-answer-is-checked.md +3 -3
  263. package/agent-docs/chat/checks.sections/questions-with-several-parts.md +3 -3
  264. package/agent-docs/chat/checks.sections/related-reading.md +1 -1
  265. package/agent-docs/chat/checks.sections/reuse-answers.md +4 -4
  266. package/agent-docs/chat/host.md +28 -10
  267. package/agent-docs/chat/host.sections/cap-the-daily-spend.md +2 -2
  268. package/agent-docs/chat/host.sections/keep-a-record-of-questions.md +3 -3
  269. package/agent-docs/chat/host.sections/related-reading.md +2 -2
  270. package/agent-docs/chat/passage-index.md +17 -17
  271. package/agent-docs/chat/passage-index.sections/build-the-index.md +2 -2
  272. package/agent-docs/chat/passage-index.sections/embed-passages.md +3 -3
  273. package/agent-docs/chat/passage-index.sections/how-the-default-chunker-splits-a-page.md +2 -2
  274. package/agent-docs/chat/passage-index.sections/limits.md +2 -2
  275. package/agent-docs/chat/passage-index.sections/passage-ids-and-links.md +3 -3
  276. package/agent-docs/chat/passage-index.sections/related-reading.md +2 -2
  277. package/agent-docs/chat/passage-index.sections/what-a-passage-contains.md +15 -15
  278. package/agent-docs/chat/prepared-answers.md +4 -4
  279. package/agent-docs/chat/settings.md +4 -4
  280. package/agent-docs/chat/settings.sections/choose-the-scorer.md +1 -1
  281. package/agent-docs/chat/settings.sections/configure-chat.md +2 -2
  282. package/agent-docs/chat/settings.sections/configure-retrieval.md +1 -1
  283. package/agent-docs/chat/settings.sections/related-reading.md +1 -1
  284. package/agent-docs/chat/settings.sections/send-extra-request-fields.md +2 -2
  285. package/agent-docs/chat/settings.sections/use-more-than-one-model.md +2 -2
  286. package/agent-docs/chat/settings.sections/when-the-scorer-is-down.md +1 -1
  287. package/agent-docs/chat/setup.md +2 -2
  288. package/agent-docs/chat.md +3 -3
  289. package/agent-docs/cli.md +73 -59
  290. package/agent-docs/cli.sections/audit-a-project-and-api-sources.md +11 -7
  291. package/agent-docs/cli.sections/author-pages.md +16 -12
  292. package/agent-docs/cli.sections/build-and-serve.md +30 -18
  293. package/agent-docs/cli.sections/inspect-config-and-operations.md +13 -9
  294. package/agent-docs/cli.sections/npm-scripts-in-this-repository.md +7 -3
  295. package/agent-docs/cli.sections/related-reading.md +6 -2
  296. package/agent-docs/cli.sections/search-and-chat.md +24 -18
  297. package/agent-docs/cli.sections/start-a-project.md +7 -3
  298. package/agent-docs/cli.sections/working-tree-authoring-tools.md +7 -3
  299. package/agent-docs/concepts.md +2 -2
  300. package/agent-docs/config/apis.md +2 -2
  301. package/agent-docs/config/content.md +3 -3
  302. package/agent-docs/config/content.sections/authoring.md +3 -3
  303. package/agent-docs/config/content.sections/badges.md +1 -1
  304. package/agent-docs/config/content.sections/callouts.md +1 -1
  305. package/agent-docs/config/content.sections/cookbooks.md +1 -1
  306. package/agent-docs/config/content.sections/frontmatter.md +1 -1
  307. package/agent-docs/config/content.sections/readerfilters.md +1 -1
  308. package/agent-docs/config/content.sections/related-reading.md +1 -1
  309. package/agent-docs/config/content.sections/relationships.md +1 -1
  310. package/agent-docs/config/content.sections/snippets.md +1 -1
  311. package/agent-docs/config/content.sections/templates.md +1 -1
  312. package/agent-docs/config/content.sections/variables.md +1 -1
  313. package/agent-docs/config/examples.md +4 -4
  314. package/agent-docs/config/examples.sections/feature-showcase.md +4 -4
  315. package/agent-docs/config/examples.sections/minimal-site.md +2 -2
  316. package/agent-docs/config/examples.sections/multilingual-help-center.md +2 -2
  317. package/agent-docs/config/examples.sections/parcel-api-documentation.md +2 -2
  318. package/agent-docs/config/examples.sections/related-reading.md +2 -2
  319. package/agent-docs/config/examples.sections/shared-company-preset.md +2 -2
  320. package/agent-docs/config/integrations.md +4 -4
  321. package/agent-docs/config/outputs.md +22 -16
  322. package/agent-docs/config/outputs.sections/exports.md +19 -13
  323. package/agent-docs/config/outputs.sections/metadata.md +2 -2
  324. package/agent-docs/config/outputs.sections/related-reading.md +1 -1
  325. package/agent-docs/config/publishing.md +29 -19
  326. package/agent-docs/config/publishing.sections/navigation.md +2 -2
  327. package/agent-docs/config/publishing.sections/redirects.md +8 -8
  328. package/agent-docs/config/publishing.sections/related-reading.md +2 -2
  329. package/agent-docs/config/site.md +42 -18
  330. package/agent-docs/config/site.sections/related-reading.md +1 -1
  331. package/agent-docs/config/site.sections/theme.md +1 -1
  332. package/agent-docs/config.md +2 -2
  333. package/agent-docs/configuration.md +19 -19
  334. package/agent-docs/configuration.sections/build-several-sites-from-shared-content.md +1 -1
  335. package/agent-docs/configuration.sections/change-inherited-lists-deliberately.md +5 -5
  336. package/agent-docs/configuration.sections/extract-a-section-with-include.md +1 -1
  337. package/agent-docs/configuration.sections/inspect-and-validate-changes.md +5 -5
  338. package/agent-docs/configuration.sections/related-reading.md +1 -1
  339. package/agent-docs/configuration.sections/separate-config-inheritance-from-page-metadata.md +5 -5
  340. package/agent-docs/configuration.sections/share-defaults-through-extends.md +3 -3
  341. package/agent-docs/configuration.sections/start-with-one-working-file.md +2 -2
  342. package/agent-docs/configuration.sections/understand-the-three-stages.md +3 -3
  343. package/agent-docs/configuration.sections/understand-where-paths-point.md +2 -2
  344. package/agent-docs/connect/mcp.md +24 -15
  345. package/agent-docs/content-delivery/agents.md +6 -6
  346. package/agent-docs/content-delivery/api.md +29 -16
  347. package/agent-docs/content-delivery/client.md +14 -8
  348. package/agent-docs/content-delivery/http-api/operations/get-content-representation-fa1d2e3f.md +10 -2
  349. package/agent-docs/content-delivery/http-api/operations/get-content-representation-head-4052375c.md +10 -2
  350. package/agent-docs/content-delivery/http-api/operations/get-content-resource-849f1c49.md +537 -3
  351. package/agent-docs/content-delivery/http-api/operations/get-content-resource-head-0a352acd.md +10 -2
  352. package/agent-docs/content-delivery/http-api/operations/list-content-resources-8e977ec7.md +545 -3
  353. package/agent-docs/content-delivery/http-api/operations/list-content-resources-head-b67cbad9.md +10 -2
  354. package/agent-docs/content-delivery/http-api.md +21 -7
  355. package/agent-docs/content-delivery/manifest.md +30 -8
  356. package/agent-docs/content-delivery/publish.md +5 -5
  357. package/agent-docs/content-delivery/render.md +6 -6
  358. package/agent-docs/content-delivery/rest.md +16 -8
  359. package/agent-docs/content-delivery/sections.md +11 -11
  360. package/agent-docs/content-delivery/select.md +6 -6
  361. package/agent-docs/content-delivery.md +4 -4
  362. package/agent-docs/contribute/agent-skills.md +3 -3
  363. package/agent-docs/cookbooks/authoring.md +3 -3
  364. package/agent-docs/cookbooks/site-workflows.md +2 -2
  365. package/agent-docs/cookbooks/welcome-email.md +3 -3
  366. package/agent-docs/documents.json +2500 -1927
  367. package/agent-docs/example-api/cedar.md +4 -4
  368. package/agent-docs/features.md +49 -0
  369. package/agent-docs/glossary.md +22 -22
  370. package/agent-docs/index.md +5 -5
  371. package/agent-docs/ingredients/audit-site.md +2 -2
  372. package/agent-docs/ingredients/build-site.md +2 -2
  373. package/agent-docs/ingredients/complete-page.md +2 -2
  374. package/agent-docs/ingredients/refresh-agent-bundle.md +2 -2
  375. package/agent-docs/non-goals.md +4 -4
  376. package/agent-docs/provenance.json +10 -4
  377. package/agent-docs/publish/agent-discovery.md +8 -2
  378. package/agent-docs/publish/agent-friendliness.md +21 -21
  379. package/agent-docs/publish/agent-friendliness.sections/discover-a-page-with-a-small-context-budget.md +5 -5
  380. package/agent-docs/publish/agent-friendliness.sections/distinguish-examples-from-a-real-service.md +5 -5
  381. package/agent-docs/publish/agent-friendliness.sections/evidence-has-a-scope.md +5 -5
  382. package/agent-docs/publish/agent-friendliness.sections/keep-shared-instructions-complete.md +5 -5
  383. package/agent-docs/publish/agent-friendliness.sections/related-reading.md +3 -3
  384. package/agent-docs/publish/agent-friendliness.sections/secret-handshake.md +3 -3
  385. package/agent-docs/publish/agent-friendliness.sections/try-the-page-controls.md +3 -3
  386. package/agent-docs/publish/agent-friendliness.sections/use-the-transport-your-client-supports.md +4 -4
  387. package/agent-docs/publish/agent-friendliness.sections/verify-the-page-and-detect-changes.md +9 -9
  388. package/agent-docs/publish/agent-friendliness.sections/what-an-agent-reads.md +5 -5
  389. package/agent-docs/publish/agent-friendliness.sections/what-happens-to-an-unsupported-component.md +4 -4
  390. package/agent-docs/publish/api-references.md +5 -5
  391. package/agent-docs/publish/api-references.sections/author-the-reference-page.md +2 -2
  392. package/agent-docs/publish/api-references.sections/build-and-verify-the-output.md +3 -3
  393. package/agent-docs/publish/api-references.sections/inspect-the-machine-readable-contract.md +2 -2
  394. package/agent-docs/publish/api-references.sections/next-steps.md +2 -2
  395. package/agent-docs/publish/api-references.sections/preview-a-small-api-reference.md +2 -2
  396. package/agent-docs/publish/api-references.sections/put-the-spec-in-your-project.md +2 -2
  397. package/agent-docs/publish/api-references.sections/register-the-operation.md +2 -2
  398. package/agent-docs/publish/api-references.sections/related-reading.md +2 -2
  399. package/agent-docs/publish/api-references.sections/review-imported-content-before-publishing.md +3 -3
  400. package/agent-docs/publish/api-references.sections/what-readers-get.md +3 -3
  401. package/agent-docs/publish/audit.md +8 -8
  402. package/agent-docs/publish/audit.sections/add-project-tests.md +2 -2
  403. package/agent-docs/publish/audit.sections/check-agent-evaluation-reports.md +2 -2
  404. package/agent-docs/publish/audit.sections/check-before-pushing.md +3 -3
  405. package/agent-docs/publish/audit.sections/connect-a-documentation-test-suite.md +2 -2
  406. package/agent-docs/publish/audit.sections/read-the-report.md +3 -3
  407. package/agent-docs/publish/audit.sections/related-reading.md +1 -1
  408. package/agent-docs/publish/content-export.md +37 -15
  409. package/agent-docs/publish/content-export.sections/assets-downloads-and-notices.md +4 -4
  410. package/agent-docs/publish/content-export.sections/check-the-result.md +2 -2
  411. package/agent-docs/publish/content-export.sections/inspect-the-manifest.md +3 -3
  412. package/agent-docs/publish/content-export.sections/prerequisites.md +4 -4
  413. package/agent-docs/publish/content-export.sections/related-reading.md +2 -2
  414. package/agent-docs/publish/content-export.sections/review-exported-api-material.md +3 -3
  415. package/agent-docs/publish/content-export.sections/try-the-help-drawer-example.md +2 -2
  416. package/agent-docs/publish/content-export.sections/what-the-representations-retain.md +4 -4
  417. package/agent-docs/publish/content-negotiation.md +10 -10
  418. package/agent-docs/publish/content-negotiation.sections/hosting-contract.md +2 -2
  419. package/agent-docs/publish/content-negotiation.sections/missing-pages.md +3 -3
  420. package/agent-docs/publish/content-negotiation.sections/related-reading.md +1 -1
  421. package/agent-docs/publish/content-negotiation.sections/validators-and-manifest-links.md +2 -2
  422. package/agent-docs/publish/content-negotiation.sections/verify-the-deployed-url.md +2 -2
  423. package/agent-docs/publish/content-negotiation.sections/what-if-the-host-cannot-negotiate.md +3 -3
  424. package/agent-docs/publish/content-negotiation.sections/what-shoalrun-builds-and-what-the-host-does.md +2 -2
  425. package/agent-docs/publish/content-negotiation.sections/why-this-matters.md +2 -2
  426. package/agent-docs/publish/deployment-check.md +6 -6
  427. package/agent-docs/publish/deployment-profiles.md +60 -26
  428. package/agent-docs/publish/deployment-profiles.sections/before-you-begin.md +5 -5
  429. package/agent-docs/publish/deployment-profiles.sections/build-and-inspect-the-edition.md +9 -9
  430. package/agent-docs/publish/deployment-profiles.sections/check-the-result.md +7 -7
  431. package/agent-docs/publish/deployment-profiles.sections/choose-navigation-labels.md +6 -6
  432. package/agent-docs/publish/deployment-profiles.sections/current-limits.md +7 -7
  433. package/agent-docs/publish/deployment-profiles.sections/define-the-shared-sku-manifest.md +6 -6
  434. package/agent-docs/publish/deployment-profiles.sections/html-markdown-and-agents.md +7 -7
  435. package/agent-docs/publish/deployment-profiles.sections/mark-pages-and-shared-sections.md +13 -13
  436. package/agent-docs/publish/deployment-profiles.sections/preview-and-edit-a-customer-edition.md +55 -0
  437. package/agent-docs/publish/deployment-profiles.sections/related-reading.md +6 -6
  438. package/agent-docs/publish/deployment-profiles.sections/select-each-product-release.md +55 -0
  439. package/agent-docs/publish/deployment-profiles.sections/supply-the-profile-from-the-deployment.md +6 -6
  440. package/agent-docs/publish/evals.md +16 -16
  441. package/agent-docs/publish/evals.sections/add-the-audit-hook.md +5 -5
  442. package/agent-docs/publish/evals.sections/check-the-report.md +4 -4
  443. package/agent-docs/publish/evals.sections/define-a-task-file.md +5 -5
  444. package/agent-docs/publish/evals.sections/diagnose-a-different-build.md +5 -5
  445. package/agent-docs/publish/evals.sections/prepare-a-report-for-the-built-site.md +5 -5
  446. package/agent-docs/publish/evals.sections/related-reading.md +3 -3
  447. package/agent-docs/publish/evals.sections/run-and-review-the-tasks.md +4 -4
  448. package/agent-docs/publish/evals.sections/shoalrun-s-own-example.md +6 -6
  449. package/agent-docs/publish/host-adapters.md +6 -6
  450. package/agent-docs/publish/manni.md +16 -16
  451. package/agent-docs/publish/manni.sections/check-the-result.md +3 -3
  452. package/agent-docs/publish/manni.sections/how-this-site-uses-manni.md +6 -6
  453. package/agent-docs/publish/manni.sections/optional-custom-policies.md +4 -4
  454. package/agent-docs/publish/manni.sections/prerequisites.md +2 -2
  455. package/agent-docs/publish/mcp-analytics.md +12 -12
  456. package/agent-docs/publish/mcp-analytics.sections/adapter-exports.md +4 -4
  457. package/agent-docs/publish/mcp-analytics.sections/enable-analytics.md +4 -4
  458. package/agent-docs/publish/mcp-analytics.sections/event-fields-and-service-mappings.md +4 -4
  459. package/agent-docs/publish/mcp-analytics.sections/optionally-collect-intent-and-group-calls.md +4 -4
  460. package/agent-docs/publish/mcp-analytics.sections/optionally-identify-the-client-and-model.md +5 -5
  461. package/agent-docs/publish/mcp-analytics.sections/related-reading.md +3 -3
  462. package/agent-docs/publish/mcp-analytics.sections/safeguards-and-limits.md +5 -5
  463. package/agent-docs/publish/mcp.md +56 -29
  464. package/agent-docs/publish/mcp.sections/check-budgets-and-errors.md +8 -8
  465. package/agent-docs/publish/mcp.sections/choose-the-documentation-source.md +4 -4
  466. package/agent-docs/publish/mcp.sections/configure-the-client.md +4 -4
  467. package/agent-docs/publish/mcp.sections/discover-product-releases-before-searching.md +52 -0
  468. package/agent-docs/publish/mcp.sections/generate-a-vercel-endpoint.md +6 -6
  469. package/agent-docs/publish/mcp.sections/html-markdown-and-agents.md +38 -0
  470. package/agent-docs/publish/mcp.sections/related-reading.md +3 -3
  471. package/agent-docs/publish/mcp.sections/search-then-read.md +13 -12
  472. package/agent-docs/publish/mcp.sections/serve-a-public-endpoint-on-node.md +12 -8
  473. package/agent-docs/publish/mcp.sections/verify-the-connection.md +4 -4
  474. package/agent-docs/publish/mcp.sections/why-offer-mcp-for-public-docs.md +4 -4
  475. package/agent-docs/publish/openapi-extension-mappings.md +12 -12
  476. package/agent-docs/publish/output.md +20 -20
  477. package/agent-docs/publish/output.sections/api-contracts.md +1 -1
  478. package/agent-docs/publish/output.sections/code-highlighting.md +1 -1
  479. package/agent-docs/publish/output.sections/current-limits.md +1 -1
  480. package/agent-docs/publish/output.sections/incremental-sync.md +4 -4
  481. package/agent-docs/publish/output.sections/manifest-records-and-sections.md +3 -3
  482. package/agent-docs/publish/output.sections/navigation-section-indexes.md +1 -1
  483. package/agent-docs/publish/output.sections/page-formats.md +2 -2
  484. package/agent-docs/publish/output.sections/published-output-contract.md +5 -5
  485. package/agent-docs/publish/output.sections/reader-appearance-and-controls.md +1 -1
  486. package/agent-docs/publish/output.sections/related-reading.md +1 -1
  487. package/agent-docs/publish/output.sections/response-identity.md +1 -1
  488. package/agent-docs/publish/output.sections/site-files.md +6 -6
  489. package/agent-docs/publish/output.sections/validate-an-existing-build-locally.md +3 -3
  490. package/agent-docs/publish/output.sections/where-files-go.md +3 -3
  491. package/agent-docs/publish/publications.md +108 -19
  492. package/agent-docs/publish/publications.sections/add-a-language.md +60 -0
  493. package/agent-docs/publish/publications.sections/change-just-one-part-of-a-shared-page.md +63 -0
  494. package/agent-docs/publish/publications.sections/give-each-api-version-its-own-contract.md +34 -0
  495. package/agent-docs/publish/publications.sections/keep-an-unchanged-page-in-one-file.md +53 -0
  496. package/agent-docs/publish/publications.sections/publish-versions-without-a-product-catalog.md +49 -0
  497. package/agent-docs/publish/publications.sections/related-reading.md +42 -0
  498. package/agent-docs/publish/publications.sections/version-products-independently.md +115 -0
  499. package/agent-docs/publish/publications.sections/what-agents-receive.md +38 -0
  500. package/agent-docs/publish/revisions.md +4 -4
  501. package/agent-docs/publish/seo.md +10 -10
  502. package/agent-docs/publish/seo.sections/related-reading.md +2 -2
  503. package/agent-docs/publish/seo.sections/set-the-public-address.md +3 -3
  504. package/agent-docs/publish/seo.sections/what-agents-receive.md +3 -3
  505. package/agent-docs/publish/seo.sections/what-the-build-adds.md +2 -2
  506. package/agent-docs/publish/seo.sections/write-the-page-title-and-summary.md +2 -2
  507. package/agent-docs/publish/single-source-sites.md +5 -5
  508. package/agent-docs/publish/troubleshooting.md +10 -10
  509. package/agent-docs/publish/vercel.md +5 -5
  510. package/agent-docs/publish/vercel.sections/check-the-deployment.md +1 -1
  511. package/agent-docs/publish/vercel.sections/include-an-mcp-endpoint.md +2 -2
  512. package/agent-docs/publish/vercel.sections/prepare-your-project.md +2 -2
  513. package/agent-docs/publish/vercel.sections/related-reading.md +1 -1
  514. package/agent-docs/publish.md +2 -2
  515. package/agent-docs/recipes/add-page.md +5 -5
  516. package/agent-docs/recipes/add-page.sections/audit-the-shoalrun-docs-project.md +2 -2
  517. package/agent-docs/recipes/add-page.sections/before-you-start.md +1 -1
  518. package/agent-docs/recipes/add-page.sections/build-the-shoalrun-docs-site.md +2 -2
  519. package/agent-docs/recipes/add-page.sections/check-agent-search-and-page-lookup.md +1 -1
  520. package/agent-docs/recipes/add-page.sections/check-the-built-page-artifacts.md +1 -1
  521. package/agent-docs/recipes/add-page.sections/check-the-outcome.md +1 -1
  522. package/agent-docs/recipes/add-page.sections/complete-the-guide-and-add-navigation.md +2 -2
  523. package/agent-docs/recipes/add-page.sections/install-the-site-dependencies.md +1 -1
  524. package/agent-docs/recipes/add-page.sections/regenerate-the-agent-documentation-bundle.md +2 -2
  525. package/agent-docs/recipes/add-page.sections/related-reading.md +1 -1
  526. package/agent-docs/recipes/add-page.sections/scaffold-a-new-guide.md +1 -1
  527. package/agent-docs/recipes/audit-docs.md +4 -4
  528. package/agent-docs/recipes/build-docs.md +2 -2
  529. package/agent-docs/recipes/preview-hybrid-search.md +5 -5
  530. package/agent-docs/recipes/preview-page.md +2 -2
  531. package/agent-docs/recipes/queue-email.md +2 -2
  532. package/agent-docs/recipes/refresh-agent-docs.md +4 -4
  533. package/agent-docs/recipes/send-welcome-email.md +13 -13
  534. package/agent-docs/reference/agent-skills.md +7 -7
  535. package/agent-docs/search-and-chat.md +4 -4
  536. package/agent-docs/search-index.json +1 -1
  537. package/agent-docs/start.md +5 -5
  538. package/agent-docs/start.sections/add-the-page-to-navigation.md +3 -3
  539. package/agent-docs/start.sections/build-and-check-both-outputs.md +3 -3
  540. package/agent-docs/start.sections/build-this-site.md +2 -2
  541. package/agent-docs/start.sections/check-writing-style.md +2 -2
  542. package/agent-docs/start.sections/create-a-page.md +2 -2
  543. package/agent-docs/start.sections/make-it-yours.md +2 -2
  544. package/agent-docs/start.sections/migrating-from-github-packages.md +2 -2
  545. package/agent-docs/start.sections/prerequisites.md +2 -2
  546. package/agent-docs/start.sections/related-reading.md +2 -2
  547. package/agent-docs/start.sections/start-your-own-project.md +3 -3
  548. package/agent-docs/status.md +14 -4
  549. package/agent-docs/styling/color-modes.md +2 -2
  550. package/agent-docs/styling/footer.md +2 -2
  551. package/agent-docs/styling/header.md +2 -2
  552. package/agent-docs/styling/layouts.md +3 -3
  553. package/agent-docs/styling/layouts.sections/build-a-landing-page.md +1 -1
  554. package/agent-docs/styling/layouts.sections/build-a-splash-page.md +1 -1
  555. package/agent-docs/styling/layouts.sections/control-navigation-tabs.md +2 -2
  556. package/agent-docs/styling/layouts.sections/customize-the-hero.md +1 -1
  557. package/agent-docs/styling/layouts.sections/hero.md +1 -1
  558. package/agent-docs/styling/layouts.sections/hide-the-table-of-contents-or-give-content-more-room.md +1 -1
  559. package/agent-docs/styling/layouts.sections/html-markdown-and-agents.md +2 -2
  560. package/agent-docs/styling/layouts.sections/related-reading.md +1 -1
  561. package/agent-docs/styling/palettes.md +3 -3
  562. package/agent-docs/styling/share-images.md +3 -3
  563. package/agent-docs/styling/themes.md +2 -2
  564. package/agent-docs/styling/try.md +2 -2
  565. package/agent-docs/what-is-shoalrun.md +7 -3
  566. package/assets/ask-widget.js +21 -7
  567. package/assets/navigation.js +5 -0
  568. package/dist/api-materialize.d.ts +2 -1
  569. package/dist/api-materialize.js +21 -9
  570. package/dist/api-publication-plan.d.ts +2 -0
  571. package/dist/api-publication-plan.js +23 -7
  572. package/dist/api-publication-review.js +4 -3
  573. package/dist/api-selection.d.ts +5 -2
  574. package/dist/api-selection.js +18 -11
  575. package/dist/artifact-bundle.js +9 -6
  576. package/dist/ask-function.js +5 -2
  577. package/dist/ask-runtime.d.ts +1 -0
  578. package/dist/ask-runtime.js +7 -2
  579. package/dist/authored-change.js +2 -1
  580. package/dist/authoring-project.js +1 -1
  581. package/dist/cards.js +2 -1
  582. package/dist/chat-config.d.ts +2 -0
  583. package/dist/chat-config.js +10 -2
  584. package/dist/cli-discovery.d.ts +2 -2
  585. package/dist/cli-discovery.js +9 -4
  586. package/dist/cli.js +50 -25
  587. package/dist/compiler-config.d.ts +17 -0
  588. package/dist/compiler-config.js +43 -2
  589. package/dist/compiler.d.ts +21 -0
  590. package/dist/compiler.js +16 -12
  591. package/dist/component-transform.d.ts +2 -4
  592. package/dist/component-transform.js +20 -7
  593. package/dist/config.d.ts +1 -0
  594. package/dist/config.js +2 -1
  595. package/dist/content-delivery-contract.d.ts +2 -1
  596. package/dist/content-delivery-validation.d.ts +2 -2
  597. package/dist/content-delivery-validation.js +6 -4
  598. package/dist/content-export-command.d.ts +1 -1
  599. package/dist/content-export-command.js +4 -4
  600. package/dist/content-export-comparison.js +6 -5
  601. package/dist/content-export-config.js +3 -1
  602. package/dist/content-export.js +9 -8
  603. package/dist/content-rest-client.js +4 -2
  604. package/dist/content-rest-contract.d.ts +2 -2
  605. package/dist/content-rest-server.js +11 -6
  606. package/dist/content-source.d.ts +13 -0
  607. package/dist/content-source.js +5 -2
  608. package/dist/content-workspace.d.ts +12 -0
  609. package/dist/content-workspace.js +2 -1
  610. package/dist/content.js +3 -2
  611. package/dist/cookbook-chooser.js +2 -1
  612. package/dist/deployment-profile.d.ts +2 -1
  613. package/dist/deployment-profile.js +38 -8
  614. package/dist/dev.d.ts +3 -1
  615. package/dist/dev.js +99 -12
  616. package/dist/docs-author.js +2 -1
  617. package/dist/docs-command.js +2 -2
  618. package/dist/docs-eval.d.ts +1 -0
  619. package/dist/docs-eval.js +2 -2
  620. package/dist/docs-mcp.d.ts +1 -0
  621. package/dist/docs-mcp.js +10 -5
  622. package/dist/docs-tool.d.ts +4 -10
  623. package/dist/document-sync.d.ts +1 -0
  624. package/dist/document-sync.js +2 -2
  625. package/dist/documentation-core.d.ts +29 -10
  626. package/dist/documentation-core.js +38 -4
  627. package/dist/freshness.js +2 -2
  628. package/dist/frontmatter.js +13 -7
  629. package/dist/function-runtime.d.ts +1 -0
  630. package/dist/index-build.d.ts +1 -0
  631. package/dist/index-build.js +2 -2
  632. package/dist/ingredient-draft.js +20 -10
  633. package/dist/mcp-analytics.d.ts +1 -0
  634. package/dist/mcp-artifacts.js +13 -4
  635. package/dist/mcp-config.d.ts +1 -0
  636. package/dist/mcp-config.js +3 -1
  637. package/dist/mcp-http.js +1 -1
  638. package/dist/page-materialization.d.ts +3 -4
  639. package/dist/page-materialization.js +15 -8
  640. package/dist/page-renderer.d.ts +6 -0
  641. package/dist/page-renderer.js +16 -5
  642. package/dist/project-navigation.js +2 -1
  643. package/dist/publication-identity.d.ts +12 -0
  644. package/dist/publication-identity.js +17 -0
  645. package/dist/publication-manifest.d.ts +24 -1
  646. package/dist/publication-manifest.js +14 -6
  647. package/dist/publication-plan.js +21 -9
  648. package/dist/publication-render.js +24 -8
  649. package/dist/recipe-draft.js +9 -6
  650. package/dist/scaffold.d.ts +7 -4
  651. package/dist/scaffold.js +16 -16
  652. package/dist/search-query.d.ts +4 -10
  653. package/dist/search-query.js +10 -9
  654. package/dist/server.d.ts +8 -0
  655. package/dist/server.js +14 -3
  656. package/dist/subject-deprecation.js +2 -1
  657. package/dist/turnstile-policy.d.ts +2 -0
  658. package/dist/turnstile-policy.js +23 -0
  659. package/dist/turnstile.d.ts +7 -0
  660. package/dist/turnstile.js +29 -2
  661. package/dist/vercel-function.js +2 -2
  662. package/example-configs/products/README.md +37 -0
  663. package/example-configs/products/content/operations.mdx +50 -0
  664. package/example-configs/products/content/payments-v2.mdx +30 -0
  665. package/example-configs/products/content/payments-v3.mdx +38 -0
  666. package/example-configs/products/content/priority-settlement.mdx +23 -0
  667. package/example-configs/products/content/reporting-v1.mdx +36 -0
  668. package/example-configs/products/content/scheduled-exports.mdx +23 -0
  669. package/example-configs/products/docs.config.yaml +56 -0
  670. package/example-configs/products/profiles/all-releases.yaml +9 -0
  671. package/example-configs/products/profiles/customer-a.yaml +13 -0
  672. package/example-configs/products/profiles/customer-b.yaml +13 -0
  673. package/example-configs/products/skus.yaml +11 -0
  674. package/examples/content-delivery/preview.mjs +1 -1
  675. package/package.json +1 -1
  676. package/schemas/content-export.schema.json +41 -3
  677. package/schemas/content-rest.openapi.json +184 -37
  678. package/skills/shoalrun-author/SKILL.md +6 -2
  679. package/skills/shoalrun-author/references/customer-editions.md +34 -4
  680. package/skills/shoalrun-author/references/publications.md +60 -0
  681. package/skills/shoalrun-brand/SKILL.md +52 -0
  682. package/skills/shoalrun-recipes/SKILL.md +2 -0
  683. package/skills/shoalrun-setup/SKILL.md +3 -1
  684. package/styles/header.css +3 -0
  685. package/styles/site.css +3 -0
  686. package/agent-docs/publish/content-export.sections/export-selected-pages.md +0 -116
@@ -3,7 +3,7 @@
3
3
  "info": {
4
4
  "title": "Shoalrun content REST API",
5
5
  "version": "1.0.0",
6
- "description": "Read-only delivery of reviewed content snapshots. This is HTTP contract v1, independent of the Shoalrun package version. The reference adapter serves one supplied revision per publication. It retains no revision history. Exported HTML/Markdown bytes are unchanged: host their original static asset and link mount alongside the API."
6
+ "description": "Read-only delivery of reviewed content snapshots. The endpoints accept legacy productless publication envelopes (schemaVersion 1) and product-scoped envelopes (schemaVersion 2). This is HTTP contract v1, independent of the Shoalrun package version. The reference adapter serves one supplied revision per publication. It retains no revision history. Exported HTML/Markdown bytes are unchanged: host their original static asset and link mount alongside the API."
7
7
  },
8
8
  "servers": [
9
9
  {
@@ -26,6 +26,9 @@
26
26
  {
27
27
  "$ref": "#/components/parameters/language"
28
28
  },
29
+ {
30
+ "$ref": "#/components/parameters/product"
31
+ },
29
32
  {
30
33
  "$ref": "#/components/parameters/optionalRevision"
31
34
  },
@@ -251,6 +254,9 @@
251
254
  {
252
255
  "$ref": "#/components/parameters/language"
253
256
  },
257
+ {
258
+ "$ref": "#/components/parameters/product"
259
+ },
254
260
  {
255
261
  "$ref": "#/components/parameters/optionalRevision"
256
262
  },
@@ -376,6 +382,9 @@
376
382
  {
377
383
  "$ref": "#/components/parameters/language"
378
384
  },
385
+ {
386
+ "$ref": "#/components/parameters/product"
387
+ },
379
388
  {
380
389
  "$ref": "#/components/parameters/revision"
381
390
  },
@@ -600,6 +609,9 @@
600
609
  {
601
610
  "$ref": "#/components/parameters/language"
602
611
  },
612
+ {
613
+ "$ref": "#/components/parameters/product"
614
+ },
603
615
  {
604
616
  "$ref": "#/components/parameters/revision"
605
617
  },
@@ -728,6 +740,9 @@
728
740
  {
729
741
  "$ref": "#/components/parameters/language"
730
742
  },
743
+ {
744
+ "$ref": "#/components/parameters/product"
745
+ },
731
746
  {
732
747
  "$ref": "#/components/parameters/revision"
733
748
  },
@@ -923,6 +938,9 @@
923
938
  {
924
939
  "$ref": "#/components/parameters/language"
925
940
  },
941
+ {
942
+ "$ref": "#/components/parameters/product"
943
+ },
926
944
  {
927
945
  "$ref": "#/components/parameters/revision"
928
946
  },
@@ -1070,6 +1088,10 @@
1070
1088
  "language": {
1071
1089
  "type": "string",
1072
1090
  "minLength": 1
1091
+ },
1092
+ "product": {
1093
+ "type": "string",
1094
+ "minLength": 1
1073
1095
  }
1074
1096
  }
1075
1097
  },
@@ -1458,69 +1480,65 @@
1458
1480
  }
1459
1481
  }
1460
1482
  },
1461
- "ResourceEntry": {
1483
+ "PublicationV1": {
1462
1484
  "type": "object",
1463
1485
  "additionalProperties": false,
1464
1486
  "required": [
1465
- "key",
1466
- "resource"
1487
+ "channel",
1488
+ "version",
1489
+ "language"
1467
1490
  ],
1468
1491
  "properties": {
1469
- "key": {
1470
- "$ref": "#/components/schemas/ResourceKey"
1492
+ "channel": {
1493
+ "type": "string",
1494
+ "minLength": 1
1471
1495
  },
1472
- "resource": {
1473
- "$ref": "#/components/schemas/ContentResource"
1496
+ "version": {
1497
+ "type": "string",
1498
+ "minLength": 1
1499
+ },
1500
+ "language": {
1501
+ "type": "string",
1502
+ "minLength": 1
1474
1503
  }
1475
1504
  }
1476
1505
  },
1477
- "ResourceList": {
1506
+ "PublicationV2": {
1478
1507
  "type": "object",
1479
1508
  "additionalProperties": false,
1480
1509
  "required": [
1481
- "schemaVersion",
1482
- "revision",
1483
- "publication",
1484
- "resources"
1510
+ "channel",
1511
+ "version",
1512
+ "language",
1513
+ "product"
1485
1514
  ],
1486
1515
  "properties": {
1487
- "schemaVersion": {
1488
- "const": 1
1516
+ "channel": {
1517
+ "type": "string",
1518
+ "minLength": 1
1489
1519
  },
1490
- "revision": {
1491
- "$ref": "#/components/schemas/digest"
1520
+ "version": {
1521
+ "type": "string",
1522
+ "minLength": 1
1492
1523
  },
1493
- "publication": {
1494
- "$ref": "#/components/schemas/publication"
1524
+ "language": {
1525
+ "type": "string",
1526
+ "minLength": 1
1495
1527
  },
1496
- "resources": {
1497
- "type": "array",
1498
- "items": {
1499
- "$ref": "#/components/schemas/ResourceEntry"
1500
- }
1528
+ "product": {
1529
+ "type": "string",
1530
+ "minLength": 1
1501
1531
  }
1502
1532
  }
1503
1533
  },
1504
- "ResourceMetadata": {
1534
+ "ResourceEntry": {
1505
1535
  "type": "object",
1506
1536
  "additionalProperties": false,
1507
1537
  "required": [
1508
- "schemaVersion",
1509
- "revision",
1510
- "publication",
1511
1538
  "key",
1512
1539
  "resource"
1513
1540
  ],
1514
1541
  "properties": {
1515
- "schemaVersion": {
1516
- "const": 1
1517
- },
1518
- "revision": {
1519
- "$ref": "#/components/schemas/digest"
1520
- },
1521
- "publication": {
1522
- "$ref": "#/components/schemas/publication"
1523
- },
1524
1542
  "key": {
1525
1543
  "$ref": "#/components/schemas/ResourceKey"
1526
1544
  },
@@ -1528,6 +1546,124 @@
1528
1546
  "$ref": "#/components/schemas/ContentResource"
1529
1547
  }
1530
1548
  }
1549
+ },
1550
+ "ResourceList": {
1551
+ "oneOf": [
1552
+ {
1553
+ "type": "object",
1554
+ "additionalProperties": false,
1555
+ "required": [
1556
+ "schemaVersion",
1557
+ "revision",
1558
+ "publication",
1559
+ "resources"
1560
+ ],
1561
+ "properties": {
1562
+ "schemaVersion": {
1563
+ "const": 1
1564
+ },
1565
+ "revision": {
1566
+ "$ref": "#/components/schemas/digest"
1567
+ },
1568
+ "publication": {
1569
+ "$ref": "#/components/schemas/PublicationV1"
1570
+ },
1571
+ "resources": {
1572
+ "type": "array",
1573
+ "items": {
1574
+ "$ref": "#/components/schemas/ResourceEntry"
1575
+ }
1576
+ }
1577
+ }
1578
+ },
1579
+ {
1580
+ "type": "object",
1581
+ "additionalProperties": false,
1582
+ "required": [
1583
+ "schemaVersion",
1584
+ "revision",
1585
+ "publication",
1586
+ "resources"
1587
+ ],
1588
+ "properties": {
1589
+ "schemaVersion": {
1590
+ "const": 2
1591
+ },
1592
+ "revision": {
1593
+ "$ref": "#/components/schemas/digest"
1594
+ },
1595
+ "publication": {
1596
+ "$ref": "#/components/schemas/PublicationV2"
1597
+ },
1598
+ "resources": {
1599
+ "type": "array",
1600
+ "items": {
1601
+ "$ref": "#/components/schemas/ResourceEntry"
1602
+ }
1603
+ }
1604
+ }
1605
+ }
1606
+ ]
1607
+ },
1608
+ "ResourceMetadata": {
1609
+ "oneOf": [
1610
+ {
1611
+ "type": "object",
1612
+ "additionalProperties": false,
1613
+ "required": [
1614
+ "schemaVersion",
1615
+ "revision",
1616
+ "publication",
1617
+ "key",
1618
+ "resource"
1619
+ ],
1620
+ "properties": {
1621
+ "schemaVersion": {
1622
+ "const": 1
1623
+ },
1624
+ "revision": {
1625
+ "$ref": "#/components/schemas/digest"
1626
+ },
1627
+ "publication": {
1628
+ "$ref": "#/components/schemas/PublicationV1"
1629
+ },
1630
+ "key": {
1631
+ "$ref": "#/components/schemas/ResourceKey"
1632
+ },
1633
+ "resource": {
1634
+ "$ref": "#/components/schemas/ContentResource"
1635
+ }
1636
+ }
1637
+ },
1638
+ {
1639
+ "type": "object",
1640
+ "additionalProperties": false,
1641
+ "required": [
1642
+ "schemaVersion",
1643
+ "revision",
1644
+ "publication",
1645
+ "key",
1646
+ "resource"
1647
+ ],
1648
+ "properties": {
1649
+ "schemaVersion": {
1650
+ "const": 2
1651
+ },
1652
+ "revision": {
1653
+ "$ref": "#/components/schemas/digest"
1654
+ },
1655
+ "publication": {
1656
+ "$ref": "#/components/schemas/PublicationV2"
1657
+ },
1658
+ "key": {
1659
+ "$ref": "#/components/schemas/ResourceKey"
1660
+ },
1661
+ "resource": {
1662
+ "$ref": "#/components/schemas/ContentResource"
1663
+ }
1664
+ }
1665
+ }
1666
+ ]
1531
1667
  }
1532
1668
  },
1533
1669
  "parameters": {
@@ -1567,6 +1703,17 @@
1567
1703
  "maxLength": 2048
1568
1704
  }
1569
1705
  },
1706
+ "product": {
1707
+ "name": "product",
1708
+ "in": "query",
1709
+ "required": false,
1710
+ "description": "Exact product ID. Required for product-scoped publications; omitted selects only a legacy productless publication. No cross-product fallback.",
1711
+ "schema": {
1712
+ "type": "string",
1713
+ "minLength": 1,
1714
+ "maxLength": 2048
1715
+ }
1716
+ },
1570
1717
  "revision": {
1571
1718
  "name": "revision",
1572
1719
  "in": "query",
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: shoalrun-author
3
- description: Write or revise documentation in an existing Shoalrun project using the agent's own model, native file edits, and provider-free project, validation, and preview tools. Use for pages and their required navigation, relationships, API links, snippets, customer editions, or project checks.
3
+ description: Write or revise documentation in an existing Shoalrun project using the agent's own model, native file edits, and provider-free project, validation, and preview tools. Use for pages and their required navigation, relationships, API links, snippets, product publications, customer editions, or project checks.
4
4
  ---
5
5
 
6
6
  # Author Shoalrun documentation
@@ -21,9 +21,13 @@ When reading a published site through Markdown, follow topic-index links when pr
21
21
 
22
22
  Read `reference.authoring-workspace` for tool contracts and `guide.authoring-workspace` for the working-tree procedure. Before unfamiliar syntax, check the relevant component attributes, configuration structure, or asset-handling contract instead of assuming another tool’s conventions. For MDX components, read their canonical reference; `<Step>` belongs inside `<Steps>` for an ordinary titled procedure, while your harness's task plan is separate. Read implementation/specification evidence with your harness's permitted tools; record the sources for changed claims. Bundled guidance does not establish a consumer project's facts.
23
23
 
24
+ ## Products and availability
25
+
26
+ For independently versioned products, cross-product reuse, product-scoped delivery, or feature availability labels, read [references/publications.md](references/publications.md). Preserve product/channel/version/language identity, distinguish publication membership from feature grants, and check installed-version support before using new fields. Availability labels describe support; they don't filter the published content.
27
+
24
28
  ## Customer editions and feature selection
25
29
 
26
- For SKU-selected or white-label documentation, read [references/customer-editions.md](references/customer-editions.md) before editing requirements, manifests, profiles, branding, or edition validation. Use the deployment's external profile, keep customer records out of shared source, and classify pages by feature IDs. Shared pages can use `<ForFeature>` for product-specific sections. Preserve the project's strict-classification policy and pass the same `--profile` to baseline, validation, build, and export; a default-context pass does not verify a customer edition.
30
+ For SKU-selected or white-label documentation, read [references/customer-editions.md](references/customer-editions.md) before editing requirements, manifests, profiles, branding, or edition validation. Use the deployment's external profile, keep customer records out of shared source, and classify pages by feature IDs. Shared pages can use `<ForFeature>` for feature-specific sections. Preserve the project's strict-classification policy and pass the same `--profile` to baseline, validation, build, export, and development preview; a default-context pass does not verify a customer edition.
27
31
 
28
32
  ## Record scope and edit
29
33
 
@@ -64,6 +64,26 @@ directory and must remain inside it. Branding uses bounded existing `site`, `the
64
64
  and snippet `variables` settings, not arbitrary config merges. Profiles cannot
65
65
  replace content sources, plugins, access policy, or navigation labels.
66
66
 
67
+ ## Select independent product releases
68
+
69
+ For `0.1.0-alpha.18` and later, inspect `publications.products` and read
70
+ [publications.md](publications.md) before selecting releases. A deployment can
71
+ select one product's v3 and another product's v1 independently. These are
72
+ publication choices, separate from SKU revisions and feature grants:
73
+
74
+ ```yaml
75
+ # Profile fragment using fictional products declared in the shared catalog
76
+ publications:
77
+ enabled:
78
+ - { product: payments, channel: production, version: v3, language: en }
79
+ - { product: reporting, channel: production, version: v1, language: en }
80
+ ```
81
+
82
+ Use the selected product when reading a repeated page ID or binding an API
83
+ source. Preserve all publication coordinates in validation evidence, links,
84
+ search reads, and content exports. Without a product catalog, retain existing
85
+ productless coordinates rather than adding a product field to every page.
86
+
67
87
  ## Choose page and section requirements
68
88
 
69
89
  In normal mode, a page with no authored or inherited `requires` is shared after
@@ -94,7 +114,7 @@ Requirements name feature IDs, not SKUs. Use `allOf` when every feature is neede
94
114
  and `anyOf` when one suffices; if both clauses appear, both must pass. Lists are
95
115
  nonempty. Unmet page requirements omit the whole page.
96
116
 
97
- A shared page may contain product-specific sections:
117
+ A shared page may contain feature-specific sections:
98
118
 
99
119
  ```mdx
100
120
  These setup instructions apply to every customer.
@@ -146,9 +166,19 @@ Use explicit `--file`/`--id` selectors if no baseline exists. Apply the authorin
146
166
  skill's applicable project checks, review, preview, and freshness workflow to the
147
167
  returned report. Snapshot capture includes the external profile and its declared
148
168
  assets; changing them invalidates the evidence. Export still needs its normal
149
- publication selection when multiple combinations are enabled. `dev` and
150
- checked-plan authoring do not resolve deployment editions; use build/serve or
151
- snapshot validation/preview. Preview URLs and artifacts may contain customer data.
169
+ publication selection when multiple combinations are enabled. On `0.1.0-alpha.18`
170
+ or later, preview the selected edition while editing with:
171
+
172
+ ```sh
173
+ shoalrun dev docs.config.yaml edition-dist --profile /run/config/docs-profile.yaml
174
+ ```
175
+
176
+ It watches the chosen profile and declared dependencies, keeps the last good
177
+ output on a failed rebuild, and shows that failure in the preview. Correct the
178
+ input and verify recovery. On older releases use a profiled build followed by
179
+ `serve`. Checked-plan authoring doesn't resolve deployment editions; retain
180
+ snapshot validation/preview for those authoring checks. Preview URLs and
181
+ artifacts may contain customer data.
152
182
 
153
183
  Check both included and excluded content in HTML, Markdown, search/discovery,
154
184
  focused API contracts, and exports. Use synthetic no-grant, relevant single-feature,
@@ -0,0 +1,60 @@
1
+ # Author independent product publications
2
+
3
+ Use this reference when a project gives products independent releases, shares
4
+ pages across products, or delivers documentation for a selected product release.
5
+ Product catalogs and product-aware commands require `0.1.0-alpha.18` or later.
6
+ Check the installed version and command help; don't silently upgrade a pin.
7
+ Read `guide.publications` and `reference.config-publishing` when the bundled
8
+ snapshot contains them. The package's `README.md` and `AUTHORING.md` describe
9
+ newer behavior when that snapshot is older.
10
+
11
+ ## Preserve publication identity
12
+
13
+ Inspect `publications.products` before treating `frontmatter.product` as a facet.
14
+ With a catalog, a publication includes product, channel, version, and language.
15
+ Each product has its own versions, default version, and route prefix. An omitted
16
+ product version uses that product's default unless matching
17
+ `publications.defaults.product` and `version` override it. Don't borrow another
18
+ product's release or a global frontmatter version. Without a catalog, existing product
19
+ metadata and productless publication identities retain their meaning.
20
+
21
+ Set `product`, `channel`, and `version` for one page variant, or list complete
22
+ coordinates in `publications` to share one source. Don't combine those two forms.
23
+ Keep language at page level. `shared: true` classifies customer feature eligibility;
24
+ it doesn't copy a page into other products. Use `<ForPublication product="...">`
25
+ for publication-specific content and `<ForFeature>` for purchased features.
26
+
27
+ Ordinary links, navigation, search, and reads stay in the selected publication.
28
+ Name the destination product and version on a deliberate cross-product `DocLink`.
29
+ Retain all coordinates from search results when reading repeated stable page IDs.
30
+ For a built site, supply `--site OUTPUT --product ID --channel CHANNEL --version
31
+ VERSION --language LANGUAGE` to scoped docs reads. MCP `get_publications` is a
32
+ bounded discovery tool: follow `nextOffset` rather than fetching page inventories.
33
+ A hosted endpoint still exposes only its configured publication.
34
+
35
+ ## Preview and delivery
36
+
37
+ For customer editions, read [customer-editions.md](customer-editions.md). A profile
38
+ selects product releases separately from feature grants. On supported releases,
39
+ `shoalrun dev docs.config.yaml edition-dist --profile /path/to/profile.yaml`
40
+ builds, serves, and watches that selection. Reader views and the publication
41
+ dropdown aren't feature gates. Check included and excluded content in HTML,
42
+ Markdown, search, and exports using the same profile.
43
+
44
+ Product-aware content manifests and REST envelopes use schema v2; productless
45
+ exports retain v1. The HTTP path remains `/content/v1`. Preserve exact product
46
+ coordinates and use a compatible client; don't rewrite legacy resource keys or
47
+ silently fall back to another product. Read `guide.content-export` and
48
+ `reference.content-manifest` before changing an application consumer.
49
+
50
+ ## Feature availability
51
+
52
+ On supported releases, use page-specific `availability: { since: VERSION }` and/or
53
+ `through: VERSION` for authored support boundaries. Both are inclusive labels,
54
+ not automatic version comparisons or publication selectors. They use the existing
55
+ release-version text style beside page dates and remain readable in Markdown and
56
+ the document manifest. Use the actual first supported release, backed by release
57
+ evidence or an approved release plan. For a newer section in an older guide, place
58
+ `<Badge variant="neutral">Since VERSION</Badge>` beside that section and keep the
59
+ page's original availability. Don't assign the newest option's version to the
60
+ whole guide.
@@ -0,0 +1,52 @@
1
+ ---
2
+ name: shoalrun-brand
3
+ description: Apply a visual brand to a Shoalrun documentation site or local demo using theme settings, fonts, logos, and scoped CSS. Use for matching a supplied website or brand guide, or refining an existing site's visual identity.
4
+ ---
5
+
6
+ # Brand a documentation site
7
+
8
+ Inspect the target project's configuration, styles, assets, installed package version, and applicable project instructions. Preserve documentation, routes, navigation, publication selection, and existing edits. For a separate demo, copy source into a new directory and keep its build output separate. Visual branding doesn't establish product facts; retain sample-content labels and don't invent product capabilities or release histories.
9
+
10
+ ## Establish the brand
11
+
12
+ Use the supplied website, assets, or brand guide as evidence. Inspect the rendered reference when browser access is available; stylesheets and font declarations can identify exact values. Record the relevant source URLs or file paths with the project, along with colors, font roles and weights, logo variants, spacing, shapes, and intended color modes. Distinguish observed values from approximations. If the reference is unavailable, work from supplied evidence and identify what couldn't be verified.
13
+
14
+ Keep brand-specific values and assets in the customer project. Use available logo and font files with suitable usage rights; preserve notices. Don't copy a reference site's tracking scripts or application bundle into the documentation site.
15
+
16
+ Before editing an existing project, capture a baseline with `shoalrun docs baseline --config docs.config.yaml --out .shoalrun/brand-before.json`. For a customer edition, use the same explicit `--profile FILE` throughout baseline, validation, build, and preview. Read the installed edition guidance before changing profile-owned branding.
17
+
18
+ ## Apply supported configuration first
19
+
20
+ Use the installed CLI's bundled references before choosing unfamiliar keys:
21
+
22
+ ```sh
23
+ shoalrun docs read reference.config-site
24
+ shoalrun docs read guide.themes
25
+ shoalrun docs read guide.palettes
26
+ shoalrun docs read guide.css
27
+ ```
28
+
29
+ Set site identity, logo, favicon, and header links through supported `site` settings. Choose the closest `theme.preset`; use `theme.palette` for checked color pairs, `theme.mode` for the requested color behavior, and `theme.fonts` for local body, heading, and code fonts. Declare static font weights accurately and retain fallback families. Keep source and asset paths relative to the configuration that declares them.
30
+
31
+ Use `site.customCss` for remaining visual changes. Prefer documented tokens for broad adjustments and verified generated selectors for specific regions. Project CSS loads after generated styles. Relative CSS images and imports aren't copied automatically; use the documented asset mechanism or site-root URLs for assets that are actually served.
32
+
33
+ ## Keep each surface readable
34
+
35
+ A dark header can contain light inputs and result panels. Scope foreground and background tokens together for each surface; don't let header text colors leak into inputs, option lists, buttons, or search results. Inspect actual markup and computed styles before choosing selectors. Search selection can be expressed on a result's parent element rather than its link.
36
+
37
+ Check these states where present:
38
+
39
+ - Header links and buttons: normal, hover, focus, and active.
40
+ - Search: typed text, placeholder, shortcut key, results, summaries, matched terms, empty state, hover, and keyboard selection.
41
+ - Publication and product selectors: label, selected value, open options, and focus ring.
42
+ - Navigation, cards, callouts, tables, and code: text, fills, borders, and links.
43
+
44
+ Check every requested color mode. Normal text needs at least 4.5:1 contrast; large text needs 3:1. Required control boundaries and state indicators need 3:1 against adjacent colors. Keep keyboard focus visible. The compiler checks configured palette pairs, but custom CSS and inherited interaction states need separate verification.
45
+
46
+ ## Validate and preview
47
+
48
+ Validate against the baseline with `shoalrun docs validate --baseline .shoalrun/brand-before.json --config docs.config.yaml`, including the selected profile when applicable. Read the report's findings and coverage. Reuse its captured output with `shoalrun docs preview REPORT --port 0`, or follow the project's required build workflow and serve that output. Rebuild when styles, configuration, or assets change.
49
+
50
+ Inspect a landing page and a representative article at desktop and mobile widths. Check font and image loading, overflow, keyboard navigation, dropdown destinations, and search interactions. Confirm HTML navigation and Markdown twins retain the documentation's meaning. A successful build doesn't establish visual correctness; state any browser checks that couldn't run.
51
+
52
+ Present the preview URL, changed files, verified states, and unresolved approximations. Keep the review concise and link to detailed evidence when needed. Follow the user's authorization for commits and publication.
@@ -13,6 +13,8 @@ Read `shoalrun docs read guide.recipes-overview`, then `guide.recipe-drafts` for
13
13
 
14
14
  When recipes or ingredients vary by purchased features, read [the customer-edition workflow](../shoalrun-author/references/customer-editions.md). Apply page classification to the final recipe source, use `<ForFeature>` for feature-specific sections, and validate editions that include each changed conditional branch. Do not assume a shared-page build checks an excluded recipe or ingredient branch.
15
15
 
16
+ When recipes or ingredients vary by product release, read [the publication workflow](../shoalrun-author/references/publications.md). Preserve product/channel/version/language in scaffolding, API selection, and preview. Explicit publication memberships control reuse; `shared: true` doesn't replicate a recipe into other products. Use an availability label for a newer capability without changing an older recipe's first supported version.
17
+
16
18
  Choose only the layers the task needs:
17
19
 
18
20
  - **Recipe:** write a complete page with prerequisites, ordered actions, explicit value handoffs, failure guidance, and a final success check. A recipe can be authored directly; ingredients are optional.
@@ -11,7 +11,9 @@ When adapting existing documentation, start with a connected, representative set
11
11
 
12
12
  Use `shoalrun init <directory> --starter minimal` for a small site or `--starter api-docs` for a parcel API site with guides, generated references, and focused contracts. Use `--starter showcase` for a fuller Cedar Parcel handbook with component examples, diagrams, reader views, a landing page, local-workflow cookbook, and generated API references. All three starters build without provider credentials. The command copies a bundled example without overwriting existing files. From the source checkout, use `node framework/dist/cli.js init <directory> --starter <name>` from the repository root. Replace fixture names, prose, API files, navigation, and example domains. Keep `docs.config.yaml` as the entry point. Consult the Shoalrun config reference for unfamiliar keys; do not invent config fields or assume that a package has been published to npm.
13
13
 
14
- For customer-specific or white-label editions, read [the customer-edition workflow](../shoalrun-author/references/customer-editions.md) before configuring selection. Keep the SKU manifest shared and the selected customer profile in its deployment environment. Check CLI support before using `--profile`, preserve strict-classification choices, and use that profile for validation and build/serve; `dev` does not resolve deployment editions.
14
+ For customer-specific or white-label editions, read [the customer-edition workflow](../shoalrun-author/references/customer-editions.md) before configuring selection. Keep the SKU manifest shared and the selected customer profile in its deployment environment. Check CLI support before using `--profile`, preserve strict-classification choices, and use that profile for validation, build, and export. On `0.1.0-alpha.18` or later, `shoalrun dev docs.config.yaml edition-dist --profile /path/to/profile.yaml` builds, serves, and watches that edition; older releases need a profiled build followed by `serve`.
15
+
16
+ When products need independent releases, read [the publication workflow](../shoalrun-author/references/publications.md). On supported releases, configure `publications.products` with each product's versions, default, and prefix; select exact product coordinates in enabled publications and pages. Don't turn a reader facet into a product catalog unless the task calls for that migration. The package's `example-configs/products` is a fictional multi-product/profile example, not an `init --starter` option.
15
17
 
16
18
  Run scaffolding from the project directory or use an absolute target path. Passing `--config` does not rebase `scaffold -n` against that config's directory. Resolve scaffold placeholders and remove unused optional sections while retaining the page's intended identity and draft access.
17
19
 
package/styles/header.css CHANGED
@@ -2,6 +2,8 @@
2
2
  /* Form fields need a 3:1 boundary (WCAG 1.4.11); this outranks the base navigation filter rule. */
3
3
  .side .nav-search input{border-color:var(--color-field-border)}
4
4
  .mast-tools{display:flex;align-items:center;gap:.75rem;margin-left:auto;min-width:0}
5
+ .publication-picker{flex:0 1 auto;min-width:0;max-width:min(28rem,100%);min-height:2.5rem;padding:.35rem .7rem;border:1px solid var(--color-field-border);border-radius:var(--radius-small);background:var(--color-field-surface);color:var(--color-ink);font:inherit;font-size:.8rem;font-weight:650;cursor:pointer}
6
+ .publication-picker:focus-visible{outline:2px solid var(--color-accent);outline-offset:2px}
5
7
  .publication-switcher{position:relative;flex:none}
6
8
  .publication-switcher summary{display:flex;align-items:center;gap:.45rem;min-height:2.5rem;padding:.35rem .7rem;border:1px solid var(--color-field-border);border-radius:var(--radius-small);background:var(--color-field-surface);color:var(--color-ink);font-size:.8rem;cursor:pointer;list-style:none}
7
9
  .publication-switcher summary::-webkit-details-marker{display:none}
@@ -43,6 +45,7 @@
43
45
  .mode-toggle .mode-icon-dark,.mode-toggle[aria-pressed=true] .mode-icon-light{display:none}
44
46
  .mode-toggle[aria-pressed=true] .mode-icon-dark{display:block}
45
47
  @media(max-width:48rem){
48
+ .publication-picker{max-width:100%;flex:1 1 15rem}
46
49
  .mast-tools{position:relative;order:3;width:100%;flex-wrap:wrap;margin-left:0}
47
50
  .site-search{position:static;flex:1 1 10rem;min-width:0;width:auto}
48
51
  .site-search-results{left:0;right:auto;width:100%}
package/styles/site.css CHANGED
@@ -176,6 +176,9 @@ button{cursor:pointer}
176
176
  .content .summary{font-size:1.1rem;line-height:1.65;color:var(--color-summary);max-width:58ch;margin:0 0 1.25rem}
177
177
  .page-date,.page-version{display:block;font-family:var(--font-code);font-size:.8rem;color:var(--color-muted);margin:-.45rem 0 1.2rem}
178
178
  .page-date+.page-version{margin-top:-.8rem}
179
+ .page-head .page-meta{display:flex;align-items:center;flex-wrap:wrap;gap:.45rem .85rem;margin:-.45rem 0 1.2rem}
180
+ .page-head .page-meta .page-date,.page-head .page-meta .page-version{display:inline;margin:0}
181
+
179
182
  .audience-labels{display:flex;align-items:center;flex-wrap:wrap;gap:.4rem;margin:-.25rem 0 1.25rem;font-size:.78rem}
180
183
  .audience-label-heading{font-weight:650;color:var(--color-muted);margin-right:.1rem}
181
184
  .audience-badge{padding:.2rem .55rem;border:1px solid var(--color-border);border-radius:999px;background:var(--color-surface);color:var(--color-ink);font-weight:600;line-height:1.4;overflow-wrap:anywhere}