@wildo-ai/framework-knowledge 1.1.10 → 1.1.11

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 (1062) hide show
  1. package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
  2. package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
  3. package/dist/claude-marketplace/plugins/wildo/references/derived-artifacts.md +4 -2
  4. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  5. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  6. package/dist/esm/framework-knowledge.definitions.js +459 -76
  7. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  8. package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
  9. package/dist/esm/framework-knowledge.research-provenance.d.ts +88 -0
  10. package/dist/esm/framework-knowledge.research-provenance.d.ts.map +1 -0
  11. package/dist/esm/framework-knowledge.research-provenance.js +140 -0
  12. package/dist/esm/framework-knowledge.research-provenance.js.map +1 -0
  13. package/dist/esm/index.d.ts +2 -0
  14. package/dist/esm/index.d.ts.map +1 -1
  15. package/dist/esm/index.js +2 -0
  16. package/dist/esm/index.js.map +1 -1
  17. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +2 -2
  18. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -1
  19. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +2 -2
  20. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  21. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts.map +1 -1
  22. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +5 -2
  23. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -1
  24. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +11 -6
  25. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
  26. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +1 -1
  27. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
  28. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +1 -1
  29. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
  30. package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.d.ts +1 -1
  31. package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.js +1 -1
  32. package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.js.map +1 -1
  33. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts +9 -5
  34. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts.map +1 -1
  35. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js +11 -7
  36. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js.map +1 -1
  37. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
  38. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +4 -1
  39. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
  40. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts +3 -3
  41. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts.map +1 -1
  42. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js +3 -2
  43. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js.map +1 -1
  44. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts +2 -2
  45. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts.map +1 -1
  46. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js +7 -2
  47. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
  48. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +2 -2
  49. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
  50. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +2 -2
  51. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
  52. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts +26 -7
  53. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts.map +1 -1
  54. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js +23 -6
  55. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js.map +1 -1
  56. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts.map +1 -1
  57. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts.map +1 -1
  58. package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.d.ts.map +1 -1
  59. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts +2 -2
  60. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts.map +1 -1
  61. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.js +9 -3
  62. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.js.map +1 -1
  63. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
  64. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -1
  65. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +1 -1
  66. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
  67. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts.map +1 -1
  68. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.js +1 -1
  69. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.js.map +1 -1
  70. package/dist/esm/playbooks/refinement.governance-document-candidate/playbook.definition.d.ts.map +1 -1
  71. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +1 -1
  72. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
  73. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +6 -4
  74. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
  75. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts.map +1 -1
  76. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js.map +1 -1
  77. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts.map +1 -1
  78. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js.map +1 -1
  79. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts.map +1 -1
  80. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js.map +1 -1
  81. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
  82. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +1 -1
  83. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
  84. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
  85. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +1 -1
  86. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -1
  87. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -1
  88. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +2 -1
  89. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -1
  90. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +2 -1
  91. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -1
  92. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  93. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
  94. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -1
  95. package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts.map +1 -1
  96. package/dist/esm/playbooks/top_down.definition/playbook.definition.js +9 -3
  97. package/dist/esm/playbooks/top_down.definition/playbook.definition.js.map +1 -1
  98. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts +8 -2
  99. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts.map +1 -1
  100. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js +8 -2
  101. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js.map +1 -1
  102. package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.d.ts.map +1 -1
  103. package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.js +1 -1
  104. package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.js.map +1 -1
  105. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
  106. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  107. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -1
  108. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
  109. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +1 -1
  110. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
  111. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
  112. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
  113. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
  114. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
  115. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts.map +1 -1
  116. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
  117. package/dist/esm/playbooks/top_down.service-method/playbook.definition.d.ts +95 -0
  118. package/dist/esm/playbooks/top_down.service-method/playbook.definition.d.ts.map +1 -0
  119. package/dist/esm/playbooks/top_down.service-method/playbook.definition.js +111 -0
  120. package/dist/esm/playbooks/top_down.service-method/playbook.definition.js.map +1 -0
  121. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
  122. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
  123. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +4 -3
  124. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
  125. package/dist/esm/source-anchor-grammar.d.ts +70 -0
  126. package/dist/esm/source-anchor-grammar.d.ts.map +1 -0
  127. package/dist/esm/source-anchor-grammar.js +114 -0
  128. package/dist/esm/source-anchor-grammar.js.map +1 -0
  129. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  130. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  131. package/dist/knowledge/manifest.json +8 -8
  132. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +6 -0
  133. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +3 -3
  134. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-protocol.json +1 -1
  135. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-treatment.json +1 -1
  136. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +350 -23
  137. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +6 -3
  138. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +248 -9
  139. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +2 -2
  140. package/dist/knowledge/playbooks/bottom_up.capability-composition/method.md +2 -2
  141. package/dist/knowledge/playbooks/bottom_up.capability-composition/playbook.json +2 -2
  142. package/dist/knowledge/playbooks/bottom_up.conception/method.md +12 -7
  143. package/dist/knowledge/playbooks/bottom_up.conception/playbook.json +3 -3
  144. package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +12 -1
  145. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +5 -2
  146. package/dist/knowledge/playbooks/bottom_up.experience-plan/method.md +13 -4
  147. package/dist/knowledge/playbooks/bottom_up.experience-plan/playbook.json +4 -3
  148. package/dist/knowledge/playbooks/bottom_up.foundation/method.md +5 -0
  149. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +1 -1
  150. package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +12 -0
  151. package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +4 -3
  152. package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +33 -5
  153. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +3 -3
  154. package/dist/knowledge/playbooks/bottom_up.website-plan/method.md +176 -22
  155. package/dist/knowledge/playbooks/bottom_up.website-plan/playbook.json +20 -3
  156. package/dist/knowledge/playbooks/cross_cutting.refinement/method.md +3 -2
  157. package/dist/knowledge/playbooks/cross_cutting.refinement/playbook.json +6 -2
  158. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +97 -23
  159. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  160. package/dist/knowledge/playbooks/refinement.document-facts/method.md +30 -3
  161. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +2 -2
  162. package/dist/knowledge/playbooks/refinement.feature-contribution/playbook.json +1 -1
  163. package/dist/knowledge/playbooks/refinement.governance-document-candidate/method.md +8 -6
  164. package/dist/knowledge/playbooks/refinement.governance-document-candidate/playbook.json +1 -1
  165. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-protocol.json +1 -1
  166. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-treatment.json +1 -1
  167. package/dist/knowledge/playbooks/top_down.brand-identity/method.md +9 -2
  168. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +2 -2
  169. package/dist/knowledge/playbooks/top_down.business-model/method.md +6 -0
  170. package/dist/knowledge/playbooks/top_down.business-model/playbook.json +2 -2
  171. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +1 -1
  172. package/dist/knowledge/playbooks/top_down.compliance-conception/method.md +12 -2
  173. package/dist/knowledge/playbooks/top_down.compliance-conception/playbook.json +1 -1
  174. package/dist/knowledge/playbooks/top_down.definition/method.md +7 -2
  175. package/dist/knowledge/playbooks/top_down.definition/playbook.json +5 -4
  176. package/dist/knowledge/playbooks/top_down.expert-personas/method.md +10 -3
  177. package/dist/knowledge/playbooks/top_down.expert-personas/playbook.json +3 -3
  178. package/dist/knowledge/playbooks/top_down.feature-drafts/playbook.json +1 -1
  179. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +1 -1
  180. package/dist/knowledge/playbooks/top_down.risk-register/method.md +1 -1
  181. package/dist/knowledge/playbooks/top_down.risk-register/playbook.json +1 -1
  182. package/dist/knowledge/playbooks/top_down.service-method/method.md +198 -0
  183. package/dist/knowledge/playbooks/top_down.service-method/playbook.json +96 -0
  184. package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +4 -0
  185. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +5 -4
  186. package/dist/knowledge/references/acp.execution-profile.md +9 -1
  187. package/dist/knowledge/references/application-maturity.config.md +1 -1
  188. package/dist/knowledge/references/backend.inbound-channels.attachment-adoption.md +55 -0
  189. package/dist/knowledge/references/backend.inbound-channels.handler-definition.md +13 -2
  190. package/dist/knowledge/references/backend.inbound-handlers.agents.md +10 -3
  191. package/dist/knowledge/references/backend.inbound-handlers.definition.md +426 -5
  192. package/dist/knowledge/references/backend.inbound-handlers.pipelines.md +62 -0
  193. package/dist/knowledge/references/blueprint.definition-contract.md +483 -0
  194. package/dist/knowledge/references/brand.visual-tone.config.md +26 -8
  195. package/dist/knowledge/references/build-plan.task-graph.config.md +238 -8
  196. package/dist/knowledge/references/business-model.pricing-plan.config.md +7 -0
  197. package/dist/knowledge/references/business-model.snapshot.validation.md +18 -0
  198. package/dist/knowledge/references/capability-composition.config.md +4 -3
  199. package/dist/knowledge/references/cli.market.generate-command.md +2 -1
  200. package/dist/knowledge/references/companion.technical-doc.service.md +166 -32
  201. package/dist/knowledge/references/engine.client-bundle.allow-list.md +14 -0
  202. package/dist/knowledge/references/engine.saas-technical-doc.config.md +1 -1
  203. package/dist/knowledge/references/engine.saas-website.config.md +16 -44
  204. package/dist/knowledge/references/example.ai-use-declaration.agent.md +37 -0
  205. package/dist/knowledge/references/{example.authorization.service-provider-organization-wide-access.md → example.authorization.relationship-organization-wide-access.md} +2 -2
  206. package/dist/knowledge/references/example.backend.custom-operation.child-line-total.md +4 -3
  207. package/dist/knowledge/references/example.backend.custom-operation.create-related-resource.md +22 -0
  208. package/dist/knowledge/references/example.blueprint.definition.internal-tool.md +45 -0
  209. package/dist/knowledge/references/example.config.app-shell.full.md +6 -3
  210. package/dist/knowledge/references/example.config.app-shell.hosted-components.md +4 -1
  211. package/dist/knowledge/references/example.config.backend.inbound-email.md +4 -2
  212. package/dist/knowledge/references/example.config.backend.required-floors.md +4 -2
  213. package/dist/knowledge/references/example.config.design-system.full.md +40 -116
  214. package/dist/knowledge/references/example.flows-actors.autonomous-agent.reviewed-write.md +10 -0
  215. package/dist/knowledge/references/example.flows-actors.chat-assistant.md +70 -14
  216. package/dist/knowledge/references/example.flows-actors.declared-flow.md +115 -0
  217. package/dist/knowledge/references/example.flows-actors.llm-agent-one-shot.md +12 -0
  218. package/dist/knowledge/references/example.inbound.email-channel-handler.md +10 -1
  219. package/dist/knowledge/references/example.infra.environment-config.local.md +24 -0
  220. package/dist/knowledge/references/example.layout-2d.registration.md +11 -0
  221. package/dist/knowledge/references/example.minion.contained-tick.md +1 -1
  222. package/dist/knowledge/references/example.module.relationships.scope-membership-junction.md +8 -10
  223. package/dist/knowledge/references/example.organizations.relationship-kinds.md +26 -0
  224. package/dist/knowledge/references/example.professional-qualifications.declaration.md +10 -0
  225. package/dist/knowledge/references/example.professional-qualifications.gate.md +25 -0
  226. package/dist/knowledge/references/example.provider.backend-module-shape.md +10 -0
  227. package/dist/knowledge/references/example.provider.frontend-facet.on-demand-sdk.md +41 -0
  228. package/dist/knowledge/references/example.provider.frontend-file-picker.contribution.md +4 -5
  229. package/dist/knowledge/references/example.rate-limit.resource-operation-surface.md +7 -5
  230. package/dist/knowledge/references/example.resource.add-resource.module-factory-map.md +0 -1
  231. package/dist/knowledge/references/example.resource.ui-behavior.enum-badge.md +23 -7
  232. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +52 -22
  233. package/dist/knowledge/references/example.resource.ui-behavior.record-template.md +81 -0
  234. package/dist/knowledge/references/example.resource.ui-behavior.surface-decision.md +19 -20
  235. package/dist/knowledge/references/example.spec.composite-view.workspace.md +10 -2
  236. package/dist/knowledge/references/example.views.composite-view.workspace.md +10 -3
  237. package/dist/knowledge/references/example.website.blocks.section.md +20 -0
  238. package/dist/knowledge/references/example.website.blocks.site-choices.md +78 -0
  239. package/dist/knowledge/references/example.website.blocks.site-configs.md +155 -0
  240. package/dist/knowledge/references/example.website.demo.append.md +57 -0
  241. package/dist/knowledge/references/example.website.demo.approval.md +47 -0
  242. package/dist/knowledge/references/example.website.demo.celebrate.md +39 -0
  243. package/dist/knowledge/references/example.website.demo.complete-items.md +103 -0
  244. package/dist/knowledge/references/example.website.demo.connect.md +45 -0
  245. package/dist/knowledge/references/example.website.demo.dashboard.md +74 -0
  246. package/dist/knowledge/references/example.website.demo.query-answer.md +77 -0
  247. package/dist/knowledge/references/example.website.demo.status-lifecycle.md +71 -0
  248. package/dist/knowledge/references/example.website.demo.transform.md +43 -0
  249. package/dist/knowledge/references/example.website.page.manifest.md +2 -6
  250. package/dist/knowledge/references/example.website.section.bento.md +27 -0
  251. package/dist/knowledge/references/example.website.section.contact-form.md +15 -0
  252. package/dist/knowledge/references/example.website.section.factories.md +82 -0
  253. package/dist/knowledge/references/example.website.section.faq.md +17 -0
  254. package/dist/knowledge/references/example.website.section.footer-cta.md +13 -0
  255. package/dist/knowledge/references/example.website.section.hero.md +16 -0
  256. package/dist/knowledge/references/example.website.section.latest-posts.md +15 -0
  257. package/dist/knowledge/references/example.website.section.marquee.md +26 -0
  258. package/dist/knowledge/references/example.website.section.roadmap.md +25 -0
  259. package/dist/knowledge/references/example.website.section.site-block.md +43 -0
  260. package/dist/knowledge/references/example.website.section.solution-paths.md +17 -0
  261. package/dist/knowledge/references/example.website.section.stats.md +23 -0
  262. package/dist/knowledge/references/example.website.section.steps.md +15 -0
  263. package/dist/knowledge/references/example.website.showcase.tour.md +49 -0
  264. package/dist/knowledge/references/example.website.theme.composed.md +69 -0
  265. package/dist/knowledge/references/experience-plan.config.md +16 -0
  266. package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +6 -0
  267. package/dist/knowledge/references/external-connectors.frontend-provider-sdk-activation-mode.md +27 -0
  268. package/dist/knowledge/references/external-connectors.models.connection-target.md +99 -0
  269. package/dist/knowledge/references/external-connectors.models.file-storage-adapter.md +6 -0
  270. package/dist/knowledge/references/external-connectors.models.hook-inbound-endpoint.md +352 -0
  271. package/dist/knowledge/references/external-connectors.models.hook-signature-algorithms.md +64 -0
  272. package/dist/knowledge/references/external-connectors.models.hook-trigger-strategy.md +97 -0
  273. package/dist/knowledge/references/external-connectors.models.oauth2-audiences.md +61 -2
  274. package/dist/knowledge/references/external-connectors.models.oauth2-incremental-consent.md +70 -0
  275. package/dist/knowledge/references/external-connectors.models.rest-operation-contract.md +253 -0
  276. package/dist/knowledge/references/external-connectors.models.subject-erasure-effect.md +105 -0
  277. package/dist/knowledge/references/integration-plan.config.md +21 -1
  278. package/dist/knowledge/references/market.references.weighted-edges.md +14 -1
  279. package/dist/knowledge/references/minions.tick-contract.md +2 -2
  280. package/dist/knowledge/references/placement-plan.config.md +75 -13
  281. package/dist/knowledge/references/platform.config.environment.deployment.md +9 -1
  282. package/dist/knowledge/references/platform.config.infrastructure-host.md +2 -0
  283. package/dist/knowledge/references/platform.config.platform-key-management.md +206 -0
  284. package/dist/knowledge/references/platform.config.saas.md +106 -14
  285. package/dist/knowledge/references/platform.key-management.vault-custody.md +78 -0
  286. package/dist/knowledge/references/presets.3d.layout-contract.md +4 -30
  287. package/dist/knowledge/references/presets.3d.register-layout.md +14 -36
  288. package/dist/knowledge/references/presets.layouts-2d.authoring.md +157 -0
  289. package/dist/knowledge/references/presets.layouts-2d.register-layout.md +53 -0
  290. package/dist/knowledge/references/presets.layouts-2d.settings.md +53 -0
  291. package/dist/knowledge/references/presets.layouts-2d.vocabulary.md +41 -0
  292. package/dist/knowledge/references/presets.models.palette-contrast.md +183 -0
  293. package/dist/knowledge/references/presets.models.palette-derivation.md +93 -0
  294. package/dist/knowledge/references/presets.models.surface-policy.defaults.md +27 -0
  295. package/dist/knowledge/references/presets.models.surface-variant.md +10 -0
  296. package/dist/knowledge/references/presets.models.theme-contract.md +136 -0
  297. package/dist/knowledge/references/presets.models.theme-personality-lexicon.md +81 -0
  298. package/dist/knowledge/references/presets.models.theme-personality.md +159 -0
  299. package/dist/knowledge/references/presets.themes.compose-theme.md +46 -0
  300. package/dist/knowledge/references/roadmap.phase.config.md +2 -16
  301. package/dist/knowledge/references/saas.approval-seals.admin-endpoints.md +131 -0
  302. package/dist/knowledge/references/saas.backend.a2a.token-budget.md +77 -11
  303. package/dist/knowledge/references/saas.backend.actor-execution-continuation.md +158 -0
  304. package/dist/knowledge/references/saas.backend.application-initialization.assembly.md +3 -1
  305. package/dist/knowledge/references/saas.backend.crypto-keys.application-keys.md +100 -0
  306. package/dist/knowledge/references/saas.backend.custom-operation.commit-outcome-read-back.md +208 -0
  307. package/dist/knowledge/references/saas.backend.custom-operation.target-authority.md +33 -0
  308. package/dist/knowledge/references/saas.backend.custom-operation.transactional-core.md +131 -1
  309. package/dist/knowledge/references/saas.backend.domain-module.md +76 -1
  310. package/dist/knowledge/references/saas.backend.email-template.definition.md +34 -0
  311. package/dist/knowledge/references/saas.backend.email-template.words.md +98 -0
  312. package/dist/knowledge/references/saas.backend.email.send.md +7 -0
  313. package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +9 -1
  314. package/dist/knowledge/references/saas.backend.flows-actors.ask-person-tool.md +79 -0
  315. package/dist/knowledge/references/saas.backend.flows-actors.autonomous-agent-case-selector.md +71 -0
  316. package/dist/knowledge/references/saas.backend.flows-actors.autonomous-agent-declaration.md +21 -10
  317. package/dist/knowledge/references/saas.backend.flows-actors.autonomous-agent-schedule.md +11 -5
  318. package/dist/knowledge/references/saas.backend.flows-actors.chat-agent-declaration.md +51 -0
  319. package/dist/knowledge/references/saas.backend.flows-actors.chat-reply-handler.md +207 -0
  320. package/dist/knowledge/references/saas.backend.flows-actors.decision-notice-handler.md +239 -0
  321. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +300 -3
  322. package/dist/knowledge/references/saas.backend.flows-actors.invoke-agent.md +13 -2
  323. package/dist/knowledge/references/saas.backend.flows-actors.operation-approval-resolvers.md +50 -0
  324. package/dist/knowledge/references/saas.backend.flows-actors.present-records-tool.md +106 -0
  325. package/dist/knowledge/references/saas.backend.flows-actors.resource-read-tool.md +14 -1
  326. package/dist/knowledge/references/saas.backend.flows-actors.retrieval-tool.md +205 -0
  327. package/dist/knowledge/references/saas.backend.flows-actors.tool-dispatch-obligations.md +21 -5
  328. package/dist/knowledge/references/saas.backend.flows.start-flow-method.md +27 -0
  329. package/dist/knowledge/references/saas.backend.flows.start-flow.md +47 -0
  330. package/dist/knowledge/references/saas.backend.pdf-template.collection-definition.md +5 -3
  331. package/dist/knowledge/references/saas.backend.providers.optional-runtime-peers.md +15 -25
  332. package/dist/knowledge/references/saas.backend.rate-limit-service.check-policy.md +3 -2
  333. package/dist/knowledge/references/saas.backend.submission-challenge.md +4 -0
  334. package/dist/knowledge/references/saas.backend.system-access-service.md +242 -107
  335. package/dist/knowledge/references/saas.config.content-security-policy.md +1 -2
  336. package/dist/knowledge/references/saas.data-seeding.run-ledger.md +3 -0
  337. package/dist/knowledge/references/saas.external-data.admin-endpoints.md +70 -3
  338. package/dist/knowledge/references/saas.external-providers.llm.model-configuration.md +3 -0
  339. package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +10 -2
  340. package/dist/knowledge/references/saas.frontend.app-level-component.vocabulary.md +10 -16
  341. package/dist/knowledge/references/saas.frontend.app-shell.building-blocks.md +7 -3
  342. package/dist/knowledge/references/saas.frontend.app-shell.register-shell-layout.md +97 -0
  343. package/dist/knowledge/references/saas.frontend.app-shell.shell-layout-contract.md +60 -0
  344. package/dist/knowledge/references/saas.frontend.app-shell.shell-motion-contract.md +274 -0
  345. package/dist/knowledge/references/saas.frontend.app-shell.use-shell-motion.md +73 -0
  346. package/dist/knowledge/references/saas.frontend.brand-identity.md +6 -0
  347. package/dist/knowledge/references/saas.frontend.chart-view.inserted-declaration.md +13 -0
  348. package/dist/knowledge/references/saas.frontend.chat-sign-in-completion.md +99 -0
  349. package/dist/knowledge/references/saas.frontend.collection-filter-presets.md +18 -16
  350. package/dist/knowledge/references/saas.frontend.display-layout.reading-measure.md +9 -3
  351. package/dist/knowledge/references/saas.frontend.domain-module.md +5 -0
  352. package/dist/knowledge/references/saas.frontend.embedded-resource-descent.md +2 -1
  353. package/dist/knowledge/references/saas.frontend.execution-view.definition.md +17 -3
  354. package/dist/knowledge/references/saas.frontend.field-tiles.md +76 -0
  355. package/dist/knowledge/references/saas.frontend.flows-actors-view.md +10 -2
  356. package/dist/knowledge/references/saas.frontend.focus-indicator.md +119 -0
  357. package/dist/knowledge/references/saas.frontend.launcher.item-refs.md +10 -2
  358. package/dist/knowledge/references/saas.frontend.launcher.merge-rules.md +7 -4
  359. package/dist/knowledge/references/saas.frontend.launcher.runtime-availability.md +17 -16
  360. package/dist/knowledge/references/saas.frontend.operation-key-and-resource-config-like.md +68 -1
  361. package/dist/knowledge/references/saas.frontend.providers.execute-operation.md +14 -24
  362. package/dist/knowledge/references/saas.frontend.related-resource-embeds.md +149 -0
  363. package/dist/knowledge/references/saas.frontend.resource-header-title.md +98 -34
  364. package/dist/knowledge/references/saas.frontend.resource-label-params.md +3 -1
  365. package/dist/knowledge/references/saas.frontend.resource-layout-templates.md +17 -11
  366. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +89 -51
  367. package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +9 -6
  368. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +141 -32
  369. package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +66 -4
  370. package/dist/knowledge/references/saas.models.agent-suspension.md +75 -0
  371. package/dist/knowledge/references/saas.models.agent-work-capture-settings.md +2 -2
  372. package/dist/knowledge/references/saas.models.agent-work-decision-contents-read.md +69 -0
  373. package/dist/knowledge/references/saas.models.agent-work-decision-surface.md +11 -2
  374. package/dist/knowledge/references/saas.models.agent-work-decision-vocabulary.md +20 -3
  375. package/dist/knowledge/references/saas.models.agent-work-output-review.md +3 -3
  376. package/dist/knowledge/references/saas.models.agent-work-override-rate.md +6 -5
  377. package/dist/knowledge/references/saas.models.agent-work-review-config.md +22 -4
  378. package/dist/knowledge/references/saas.models.analytics.value-moments.md +22 -0
  379. package/dist/knowledge/references/saas.models.application-agent-policy.md +28 -0
  380. package/dist/knowledge/references/saas.models.application-entry-points.md +45 -0
  381. package/dist/knowledge/references/saas.models.audit.trail-config.md +18 -5
  382. package/dist/knowledge/references/{saas.models.auth.service-provider-client-authentication.md → saas.models.auth.relationship-grantor-authentication.md} +54 -48
  383. package/dist/knowledge/references/saas.models.authorization.administrative-continuity-codes.md +4 -4
  384. package/dist/knowledge/references/saas.models.chat-identity-link-host.md +38 -0
  385. package/dist/knowledge/references/saas.models.compliance.ai-use-classification.md +179 -0
  386. package/dist/knowledge/references/saas.models.compliance.ai-use-posture.md +121 -0
  387. package/dist/knowledge/references/saas.models.config.organization-types.md +42 -82
  388. package/dist/knowledge/references/saas.models.conversation-threads.md +4 -3
  389. package/dist/knowledge/references/saas.models.crypto-keys.floors.md +22 -0
  390. package/dist/knowledge/references/saas.models.crypto-keys.key-management-config.md +130 -0
  391. package/dist/knowledge/references/saas.models.crypto-keys.local-provider.md +27 -0
  392. package/dist/knowledge/references/saas.models.crypto-keys.purpose-descriptor.md +403 -0
  393. package/dist/knowledge/references/saas.models.crypto-keys.purposes.md +84 -0
  394. package/dist/knowledge/references/saas.models.data-mode-read-list.md +24 -1
  395. package/dist/knowledge/references/saas.models.engine-capabilities.md +28 -0
  396. package/dist/knowledge/references/saas.models.evaluation-dataset-export.md +16 -9
  397. package/dist/knowledge/references/saas.models.evaluation-export-authorization.md +23 -6
  398. package/dist/knowledge/references/saas.models.external-data-conflict-vocabulary.md +53 -0
  399. package/dist/knowledge/references/saas.models.external-data-pipeline.md +81 -18
  400. package/dist/knowledge/references/saas.models.flows-actors.agent-behavior-report-config.md +28 -0
  401. package/dist/knowledge/references/saas.models.flows-actors.agent-behavior-report.md +317 -0
  402. package/dist/knowledge/references/saas.models.flows-actors.agent-content-guardrails.md +150 -0
  403. package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +45 -0
  404. package/dist/knowledge/references/saas.models.flows-actors.agent-operation-record.md +147 -0
  405. package/dist/knowledge/references/saas.models.flows-actors.autonomous-agents-vocabulary.md +49 -7
  406. package/dist/knowledge/references/saas.models.flows-actors.chat-agents-vocabulary.md +26 -0
  407. package/dist/knowledge/references/saas.models.flows-actors.decision-card-wording.md +284 -0
  408. package/dist/knowledge/references/saas.models.flows-actors.decision-notice-recorded-cards.md +93 -0
  409. package/dist/knowledge/references/saas.models.flows-actors.human-decision-decider.md +62 -0
  410. package/dist/knowledge/references/saas.models.flows-actors.human-input-form.md +314 -0
  411. package/dist/knowledge/references/saas.models.flows-actors.operation-approval-pending.md +55 -0
  412. package/dist/knowledge/references/saas.models.flows-actors.operation-approval-requirement.md +62 -0
  413. package/dist/knowledge/references/saas.models.flows-actors.review-deadline-vocabulary.md +6 -0
  414. package/dist/knowledge/references/saas.models.flows-actors.review-deadlines-declaration.md +1 -0
  415. package/dist/knowledge/references/saas.models.flows.run-state.md +49 -0
  416. package/dist/knowledge/references/saas.models.flows.runnable-model.md +255 -0
  417. package/dist/knowledge/references/saas.models.frontend-on-demand-capability-contract.md +54 -0
  418. package/dist/knowledge/references/saas.models.http-api-binding.md +157 -42
  419. package/dist/knowledge/references/saas.models.http-api-binding.rest-write-operations.md +3 -3
  420. package/dist/knowledge/references/saas.models.http-api-population-filter.md +51 -0
  421. package/dist/knowledge/references/saas.models.inbound-channels.md +4 -1
  422. package/dist/knowledge/references/saas.models.inbound-email-domains.md +5 -5
  423. package/dist/knowledge/references/saas.models.inbound-email.md +2 -2
  424. package/dist/knowledge/references/saas.models.m2m-webhook-events.md +73 -0
  425. package/dist/knowledge/references/saas.models.model-cost-summary.md +56 -20
  426. package/dist/knowledge/references/saas.models.notifications.targets.md +25 -2
  427. package/dist/knowledge/references/saas.models.notifications.user-notification-definition.md +58 -6
  428. package/dist/knowledge/references/saas.models.on-demand-provider-capabilities.md +28 -0
  429. package/dist/knowledge/references/saas.models.organization-agent-policy.md +43 -0
  430. package/dist/knowledge/references/saas.models.organization-assigned-rows-declaration.md +73 -0
  431. package/dist/knowledge/references/saas.models.organization-own-rows-declaration.md +48 -0
  432. package/dist/knowledge/references/saas.models.organization-unit-narrowing-containment.md +6 -6
  433. package/dist/knowledge/references/saas.models.organizations.application-owner-codes.md +9 -10
  434. package/dist/knowledge/references/saas.models.organizations.organization-relationships.md +911 -0
  435. package/dist/knowledge/references/saas.models.organizations.professional-qualification-kinds.md +46 -0
  436. package/dist/knowledge/references/saas.models.organizations.professional-qualifications.md +168 -0
  437. package/dist/knowledge/references/{saas.models.organizations.service-provider-capability-grants.md → saas.models.organizations.relationship-capability-grants.md} +56 -35
  438. package/dist/knowledge/references/saas.models.organizations.relationship-grantor-controls.md +62 -0
  439. package/dist/knowledge/references/saas.models.organizations.relationship-invitations.md +224 -0
  440. package/dist/knowledge/references/saas.models.organizations.relationship-kinds.md +277 -0
  441. package/dist/knowledge/references/saas.models.organizations.relationship-record-separation.md +113 -0
  442. package/dist/knowledge/references/saas.models.privacy.legal-holds.md +68 -5
  443. package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +67 -2
  444. package/dist/knowledge/references/saas.models.privacy.redaction-treatments.md +13 -14
  445. package/dist/knowledge/references/saas.models.privacy.subject-data-recipients.md +278 -40
  446. package/dist/knowledge/references/saas.models.provider-capabilities.md +33 -0
  447. package/dist/knowledge/references/saas.models.provider-usage-pricing-authority.md +50 -1
  448. package/dist/knowledge/references/saas.models.providers.capability-activation-policy.md +28 -0
  449. package/dist/knowledge/references/saas.models.providers.capability-resolution-mode.md +8 -0
  450. package/dist/knowledge/references/saas.models.providers.compliance-choice.md +37 -0
  451. package/dist/knowledge/references/saas.models.providers.execute-operation-request.md +25 -0
  452. package/dist/knowledge/references/saas.models.providers.scope-reauthorization.md +1 -1
  453. package/dist/knowledge/references/saas.models.queue.scheduled-recovery.md +13 -1
  454. package/dist/knowledge/references/saas.models.rate-limit-configuration.md +4 -4
  455. package/dist/knowledge/references/saas.models.representative-activity.md +65 -0
  456. package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +58 -2
  457. package/dist/knowledge/references/saas.models.resource-config.metered-usage-recording.md +24 -0
  458. package/dist/knowledge/references/saas.models.resource-config.operation-api-call.md +57 -11
  459. package/dist/knowledge/references/saas.models.resource-config.operation-base.md +20 -3
  460. package/dist/knowledge/references/saas.models.resource-config.operation-bulk.md +37 -0
  461. package/dist/knowledge/references/saas.models.resource-config.operation-chat-command.md +39 -0
  462. package/dist/knowledge/references/saas.models.resource-config.operation-mcp-exposure.md +1 -1
  463. package/dist/knowledge/references/saas.models.resource-config.operation-required-qualifications.md +30 -0
  464. package/dist/knowledge/references/saas.models.resource-config.operation-scope-admissions.md +99 -2
  465. package/dist/knowledge/references/saas.models.resource-config.operation-submission-challenge.md +1 -1
  466. package/dist/knowledge/references/saas.models.resource-config.operation-union.md +0 -1
  467. package/dist/knowledge/references/saas.models.resource-config.operation-variant-client-timeout.md +1 -1
  468. package/dist/knowledge/references/saas.models.resource-config.record-label-fields.md +23 -0
  469. package/dist/knowledge/references/saas.models.resource-config.request-field-offers.md +104 -0
  470. package/dist/knowledge/references/saas.models.resource-config.required-features.md +20 -0
  471. package/dist/knowledge/references/saas.models.resource-config.resource-configuration.md +9 -0
  472. package/dist/knowledge/references/saas.models.resource-config.resources-registry.md +25 -3
  473. package/dist/knowledge/references/saas.models.resource-config.retention-policy.md +25 -0
  474. package/dist/knowledge/references/saas.models.resource-config.system-managed-fields.md +2 -1
  475. package/dist/knowledge/references/saas.models.resource-config.token-generation.md +1 -1
  476. package/dist/knowledge/references/saas.models.resource-operation-variant-runtime.md +3 -2
  477. package/dist/knowledge/references/saas.models.resource-relationship-builder-parameters.md +6 -2
  478. package/dist/knowledge/references/saas.models.roadmap.phase-horizon.md +31 -0
  479. package/dist/knowledge/references/saas.models.roles.organization-defaults.md +6 -6
  480. package/dist/knowledge/references/saas.models.schema-family-builder.md +17 -4
  481. package/dist/knowledge/references/saas.models.scope-membership.md +2 -2
  482. package/dist/knowledge/references/saas.models.system-of-record-capabilities.md +121 -0
  483. package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +3 -2
  484. package/dist/knowledge/references/saas.models.systems-of-record.md +36 -1
  485. package/dist/knowledge/references/saas.models.work-attribution-vocabulary.md +7 -3
  486. package/dist/knowledge/references/saas.models.work-unit-ref.md +17 -2
  487. package/dist/knowledge/references/saas.public-runtime.contract.md +34 -2
  488. package/dist/knowledge/references/saas.specifications.assurance-control-markers.md +3 -2
  489. package/dist/knowledge/references/saas.specifications.assurance-document-blueprint.contract.md +13 -0
  490. package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +275 -13
  491. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.catalog-spec-shared.md +5 -4
  492. package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +9 -0
  493. package/dist/knowledge/references/saas.specifications.governed-document-release.contract.md +16 -2
  494. package/dist/knowledge/references/saas.specifications.processor-register.md +10 -1
  495. package/dist/knowledge/references/saas.specifications.recipient-disclosures.md +111 -2
  496. package/dist/knowledge/references/saas.specifications.recipient-population.md +46 -0
  497. package/dist/knowledge/references/saas.specifications.resource-frontend-configuration-aspect.md +7 -0
  498. package/dist/knowledge/references/saas.specifications.resource-operation-spec.md +24 -2
  499. package/dist/knowledge/references/saas.specifications.resource-spec-config.md +21 -7
  500. package/dist/knowledge/references/saas.specifications.resource-spec-factory.md +19 -5
  501. package/dist/knowledge/references/saas.specifications.subject-data-recipients.md +136 -6
  502. package/dist/knowledge/references/saas.website.astro.bridge.md +51 -14
  503. package/dist/knowledge/references/saas.website.astro.head-renderer.md +63 -27
  504. package/dist/knowledge/references/saas.website.astro.i18n-helper.md +39 -10
  505. package/dist/knowledge/references/saas.website.astro.label-key-collector.md +12 -11
  506. package/dist/knowledge/references/saas.website.astro.label-loader.md +38 -9
  507. package/dist/knowledge/references/saas.website.astro.pick-labels-for-page.md +1 -2
  508. package/dist/knowledge/references/saas.website.astro.runtime-helper.md +48 -17
  509. package/dist/knowledge/references/saas.website.astro.site-context.md +17 -8
  510. package/dist/knowledge/references/saas.website.astro.structured-data-renderer.md +29 -8
  511. package/dist/knowledge/references/saas.website.blocks.actions.md +91 -0
  512. package/dist/knowledge/references/saas.website.blocks.band.md +41 -0
  513. package/dist/knowledge/references/saas.website.blocks.bento.md +70 -0
  514. package/dist/knowledge/references/saas.website.blocks.card-grid.md +115 -0
  515. package/dist/knowledge/references/saas.website.blocks.card.md +77 -0
  516. package/dist/knowledge/references/saas.website.blocks.cta-band.md +94 -0
  517. package/dist/knowledge/references/saas.website.blocks.define-block.md +123 -0
  518. package/dist/knowledge/references/saas.website.blocks.definitions.md +132 -0
  519. package/dist/knowledge/references/saas.website.blocks.faq.md +89 -0
  520. package/dist/knowledge/references/saas.website.blocks.feature-row.md +109 -0
  521. package/dist/knowledge/references/saas.website.blocks.hero.md +140 -0
  522. package/dist/knowledge/references/saas.website.blocks.intro.md +68 -0
  523. package/dist/knowledge/references/saas.website.blocks.latest-posts.md +104 -0
  524. package/dist/knowledge/references/saas.website.blocks.marquee.md +76 -0
  525. package/dist/knowledge/references/saas.website.blocks.pricing.md +395 -0
  526. package/dist/knowledge/references/saas.website.blocks.product-tour.md +158 -0
  527. package/dist/knowledge/references/saas.website.blocks.quote-cards.md +64 -0
  528. package/dist/knowledge/references/saas.website.blocks.roadmap.md +108 -0
  529. package/dist/knowledge/references/saas.website.blocks.section-slots.md +64 -0
  530. package/dist/knowledge/references/saas.website.blocks.solution-paths.md +71 -0
  531. package/dist/knowledge/references/saas.website.blocks.stats.md +183 -0
  532. package/dist/knowledge/references/saas.website.blocks.steps.md +69 -0
  533. package/dist/knowledge/references/saas.website.blocks.stylesheet.md +68 -0
  534. package/dist/knowledge/references/saas.website.blocks.tables.md +153 -0
  535. package/dist/knowledge/references/saas.website.blocks.vocabulary.md +227 -0
  536. package/dist/knowledge/references/saas.website.blog.bridge.md +98 -53
  537. package/dist/knowledge/references/saas.website.blog.collection-config.md +76 -24
  538. package/dist/knowledge/references/saas.website.blog.cover-resolver.md +93 -0
  539. package/dist/knowledge/references/saas.website.blog.frontmatter.md +104 -7
  540. package/dist/knowledge/references/saas.website.blog.head-renderer.md +37 -19
  541. package/dist/knowledge/references/saas.website.blog.index-builder.md +63 -0
  542. package/dist/knowledge/references/saas.website.blog.index.md +43 -0
  543. package/dist/knowledge/references/saas.website.blog.post-cover.md +38 -0
  544. package/dist/knowledge/references/saas.website.blog.post-renderer.md +113 -85
  545. package/dist/knowledge/references/saas.website.blog.react-mdx-integration.md +181 -0
  546. package/dist/knowledge/references/saas.website.blog.react-mdx-query.md +26 -0
  547. package/dist/knowledge/references/saas.website.blog.vocabulary-labels.md +113 -0
  548. package/dist/knowledge/references/saas.website.config.pricing-catalog-loader.md +2 -1
  549. package/dist/knowledge/references/saas.website.config.site-context-loader.md +21 -1
  550. package/dist/knowledge/references/saas.website.consent.banner.md +1 -1
  551. package/dist/knowledge/references/saas.website.consent.context.md +1 -1
  552. package/dist/knowledge/references/saas.website.design-tokens.bundle.md +28 -6
  553. package/dist/knowledge/references/saas.website.design-tokens.colors.md +7 -6
  554. package/dist/knowledge/references/saas.website.design-tokens.compose-function.md +35 -0
  555. package/dist/knowledge/references/saas.website.design-tokens.compose.md +76 -0
  556. package/dist/knowledge/references/saas.website.design-tokens.personality-derivation.md +22 -0
  557. package/dist/knowledge/references/saas.website.design-tokens.personality-lexicon.md +31 -0
  558. package/dist/knowledge/references/saas.website.design-tokens.personality.md +82 -0
  559. package/dist/knowledge/references/saas.website.design-tokens.product.md +122 -0
  560. package/dist/knowledge/references/saas.website.design-tokens.radius.md +12 -1
  561. package/dist/knowledge/references/saas.website.design-tokens.readers.md +58 -0
  562. package/dist/knowledge/references/saas.website.design-tokens.spacing.md +61 -0
  563. package/dist/knowledge/references/saas.website.design-tokens.surface-depth.md +60 -0
  564. package/dist/knowledge/references/saas.website.design-tokens.tones.md +75 -0
  565. package/dist/knowledge/references/saas.website.design-tokens.typography.md +115 -0
  566. package/dist/knowledge/references/saas.website.factories.define-page-manifest.md +23 -21
  567. package/dist/knowledge/references/saas.website.factories.define-section.md +36 -38
  568. package/dist/knowledge/references/saas.website.format.publication-date.md +26 -0
  569. package/dist/knowledge/references/saas.website.label-keys.compose-helper.md +1 -1
  570. package/dist/knowledge/references/saas.website.label-keys.format.md +2 -2
  571. package/dist/knowledge/references/saas.website.label-pack.validator.md +7 -8
  572. package/dist/knowledge/references/saas.website.labels.section-labels.md +34 -0
  573. package/dist/knowledge/references/saas.website.legal.public-document-links.md +19 -4
  574. package/dist/knowledge/references/saas.website.locale-switcher.label-keys.md +35 -0
  575. package/dist/knowledge/references/saas.website.menu.icons.md +123 -0
  576. package/dist/knowledge/references/saas.website.menu.label-keys.md +112 -0
  577. package/dist/knowledge/references/saas.website.menu.schema.md +92 -0
  578. package/dist/knowledge/references/saas.website.menu.vocabulary.md +79 -0
  579. package/dist/knowledge/references/saas.website.motion.demo-player.md +105 -0
  580. package/dist/knowledge/references/saas.website.motion.demo-scenario.md +460 -0
  581. package/dist/knowledge/references/saas.website.motion.demo.md +324 -0
  582. package/dist/knowledge/references/saas.website.motion.element-attributes.md +115 -0
  583. package/dist/knowledge/references/saas.website.motion.reveal-renditions.md +67 -0
  584. package/dist/knowledge/references/saas.website.motion.stylesheet.md +82 -0
  585. package/dist/knowledge/references/saas.website.motion.tempo-table.md +99 -0
  586. package/dist/knowledge/references/saas.website.motion.tokens.md +46 -0
  587. package/dist/knowledge/references/saas.website.motion.vocabulary.md +85 -0
  588. package/dist/knowledge/references/saas.website.page-layout.component.md +34 -8
  589. package/dist/knowledge/references/saas.website.page-manifest.meta-label-keys.md +4 -4
  590. package/dist/knowledge/references/saas.website.page-manifest.route-path.md +1 -1
  591. package/dist/knowledge/references/saas.website.page-manifest.schema.md +25 -29
  592. package/dist/knowledge/references/saas.website.page-manifest.seo.md +1 -1
  593. package/dist/knowledge/references/saas.website.page-navigation.md +44 -0
  594. package/dist/knowledge/references/saas.website.page.context.md +9 -2
  595. package/dist/knowledge/references/saas.website.primitives.button.md +6 -6
  596. package/dist/knowledge/references/saas.website.primitives.heading.md +17 -18
  597. package/dist/knowledge/references/saas.website.primitives.image.md +18 -15
  598. package/dist/knowledge/references/saas.website.primitives.internal-button.md +11 -12
  599. package/dist/knowledge/references/saas.website.primitives.internal-link.md +11 -35
  600. package/dist/knowledge/references/saas.website.primitives.link.md +22 -11
  601. package/dist/knowledge/references/saas.website.primitives.text.md +10 -8
  602. package/dist/knowledge/references/saas.website.product.atoms.md +366 -0
  603. package/dist/knowledge/references/saas.website.product.figures.md +320 -0
  604. package/dist/knowledge/references/saas.website.product.hooks.md +278 -0
  605. package/dist/knowledge/references/saas.website.product.panels.md +324 -0
  606. package/dist/knowledge/references/saas.website.product.stylesheet.md +1086 -0
  607. package/dist/knowledge/references/saas.website.refs.section.md +2 -2
  608. package/dist/knowledge/references/saas.website.root-config.schema.md +34 -17
  609. package/dist/knowledge/references/saas.website.routing.link-target.md +70 -0
  610. package/dist/knowledge/references/saas.website.routing.localized-path.md +15 -8
  611. package/dist/knowledge/references/saas.website.runtime.context.md +44 -17
  612. package/dist/knowledge/references/saas.website.section.component.md +21 -19
  613. package/dist/knowledge/references/saas.website.sections.category-enum.md +21 -2
  614. package/dist/knowledge/references/saas.website.sections.definition-schema.md +47 -39
  615. package/dist/knowledge/references/saas.website.site-footer.menu.md +47 -0
  616. package/dist/knowledge/references/saas.website.site-header.component.md +100 -0
  617. package/dist/knowledge/references/saas.website.site-header.scroll-behavior.md +26 -0
  618. package/dist/knowledge/references/saas.website.stacking.md +86 -0
  619. package/dist/knowledge/references/saas.website.structured-data.payload-shape.md +162 -0
  620. package/dist/knowledge/references/saas.website.use-blog-index.hook.md +27 -0
  621. package/dist/knowledge/references/saas.website.use-label.hook.md +6 -4
  622. package/dist/knowledge/references/service-method.config.md +270 -0
  623. package/dist/knowledge/references/website-plan.config.md +544 -32
  624. package/dist/knowledge/references/website-plan.menu-placement.md +118 -0
  625. package/dist/knowledge/references/website-plan.page-kind-essentials.md +42 -0
  626. package/dist/knowledge/references/website-plan.page-routes.md +39 -0
  627. package/dist/knowledge/references/workers.node.worker-init-contract.md +4 -2
  628. package/dist/knowledge/references/zod.decorators.chainable-runtime.md +73 -9
  629. package/dist/knowledge/references/zod.decorators.chrome-modes.md +92 -0
  630. package/dist/knowledge/references/zod.decorators.data-categories.md +101 -11
  631. package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +75 -6
  632. package/dist/knowledge/references/zod.decorators.display-edit-modes.md +23 -1
  633. package/dist/knowledge/references/zod.decorators.enums.frontend-handling.md +41 -7
  634. package/dist/knowledge/references/zod.decorators.file-schema.md +6 -5
  635. package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +25 -9
  636. package/dist/knowledge/references/zod.decorators.primitive-ui.md +15 -3
  637. package/dist/knowledge/references/zod.decorators.schema-metadata.md +4 -0
  638. package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +32 -4
  639. package/dist/knowledge/references/zod.decorators.shared-structural-params.md +44 -5
  640. package/dist/knowledge/references/zod.decorators.structural-lifecycle-params.md +130 -9
  641. package/dist/knowledge/references/zod.factories.bigdecimal.md +17 -8
  642. package/dist/knowledge/references/zod.factories.code.md +18 -9
  643. package/dist/knowledge/references/zod.factories.duration.md +23 -14
  644. package/dist/knowledge/references/zod.factories.money.md +24 -15
  645. package/dist/knowledge/references/zod.factories.phone.md +23 -14
  646. package/dist/knowledge/references/zod.factories.range.md +5 -1
  647. package/dist/knowledge/registries/assurance-authority-bases.json +3 -3
  648. package/dist/knowledge/registries/framework-topics.json +2411 -139
  649. package/dist/knowledge/registries/playbooks.json +51 -30
  650. package/dist/knowledge/registries/source-tags.json +8500 -4768
  651. package/dist/knowledge/rules/database-migration-obligation.md +11 -5
  652. package/dist/knowledge/skills/INDEX.md +60 -33
  653. package/dist/knowledge/skills/agent-work-review/SKILL.md +86 -23
  654. package/dist/knowledge/skills/agent-work-review/references/framework-actor-execution-continuation-api.md +203 -0
  655. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-capture-settings-api.md +2 -2
  656. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-decision-contents-api.md +79 -0
  657. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-output-review-api.md +4 -4
  658. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-override-rate-api.md +6 -5
  659. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-review-config-api.md +22 -4
  660. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-review-marker-api.md +15 -3
  661. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-vocabulary-api.md +20 -3
  662. package/dist/knowledge/skills/agent-work-review/references/framework-evaluation-dataset-export-api.md +16 -9
  663. package/dist/knowledge/skills/agent-work-review/references/framework-evaluation-export-authorization-api.md +24 -7
  664. package/dist/knowledge/skills/agent-work-review/references/framework-human-input-form-api.md +341 -0
  665. package/dist/knowledge/skills/ai-use-declaration/SKILL.md +192 -0
  666. package/dist/knowledge/skills/ai-use-declaration/references/choosing-the-domain-and-class.md +73 -0
  667. package/dist/knowledge/skills/ai-use-declaration/references/framework-ai-use-classification-api.md +194 -0
  668. package/dist/knowledge/skills/ai-use-declaration/references/framework-ai-use-posture-api.md +136 -0
  669. package/dist/knowledge/skills/application-database-migrations/SKILL.md +27 -9
  670. package/dist/knowledge/skills/application-database-migrations/references/postgresql-vs-mongodb-obligations.md +34 -0
  671. package/dist/knowledge/skills/application-roles-authoring/references/framework-application-roles-api.md +6 -6
  672. package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +124 -3
  673. package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-assigned-rows-declaration-api.md +90 -0
  674. package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-own-rows-declaration-api.md +59 -0
  675. package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-unit-narrowing-declaration-api.md +6 -6
  676. package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +79 -2
  677. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +35 -1
  678. package/dist/knowledge/skills/backend-custom-operation/references/framework-assurance-control-markers.md +3 -2
  679. package/dist/knowledge/skills/backend-custom-operation/references/framework-audit-log-event-api.md +3 -0
  680. package/dist/knowledge/skills/backend-custom-operation/references/framework-operation-base-and-path-api.md +20 -3
  681. package/dist/knowledge/skills/backend-custom-operation/references/framework-target-authority-api.md +61 -0
  682. package/dist/knowledge/skills/backend-custom-operation/references/framework-transactional-core-api.md +368 -1
  683. package/dist/knowledge/skills/blueprint-authoring/SKILL.md +189 -0
  684. package/dist/knowledge/skills/blueprint-authoring/references/blueprint-content-kinds.md +29 -0
  685. package/dist/knowledge/skills/blueprint-authoring/references/framework-blueprint-definition-api.md +490 -0
  686. package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +127 -2
  687. package/dist/knowledge/skills/brand-logo-authoring/references/brand-authoring-decisions.md +15 -3
  688. package/dist/knowledge/skills/brand-logo-authoring/references/framework-brand-snapshot-api.md +26 -8
  689. package/dist/knowledge/skills/brand-logo-authoring/references/framework-style-word-lexicon-api.md +126 -0
  690. package/dist/knowledge/skills/chat-agent-conversations/SKILL.md +163 -0
  691. package/dist/knowledge/skills/chat-agent-conversations/references/framework-chat-conversations-api.md +295 -0
  692. package/dist/knowledge/skills/compliance-document-authoring/SKILL.md +2 -1
  693. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-governance.md +8 -6
  694. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +134 -33
  695. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-service-terms.md +4 -3
  696. package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +13 -0
  697. package/dist/knowledge/skills/compliance-document-authoring/references/framework-governed-document-after-drafting.md +34 -7
  698. package/dist/knowledge/skills/compliance-document-authoring/references/framework-processor-register-authoring.md +10 -1
  699. package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +37 -0
  700. package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +178 -4
  701. package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-population.md +46 -0
  702. package/dist/knowledge/skills/compliance-document-authoring/references/framework-subject-data-recipients.md +485 -61
  703. package/dist/knowledge/skills/config-app-shell/SKILL.md +57 -28
  704. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +20 -18
  705. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-building-blocks-api.md +7 -3
  706. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-hosted-components-api.md +13 -0
  707. package/dist/knowledge/skills/config-app-shell/references/framework-brand-identity-api.md +20 -0
  708. package/dist/knowledge/skills/config-app-shell/references/framework-launcher-items-api.md +17 -6
  709. package/dist/knowledge/skills/config-app-shell/references/framework-launcher-visibility-api.md +24 -22
  710. package/dist/knowledge/skills/config-app-shell/references/framework-shell-layout-api.md +528 -0
  711. package/dist/knowledge/skills/config-design-system/SKILL.md +245 -162
  712. package/dist/knowledge/skills/config-design-system/references/design-system-file.md +5 -1
  713. package/dist/knowledge/skills/config-design-system/references/framework-focus-indicator-api.md +182 -0
  714. package/dist/knowledge/skills/config-design-system/references/framework-palette-contrast-api.md +195 -0
  715. package/dist/knowledge/skills/config-design-system/references/framework-palette-derivation-api.md +108 -0
  716. package/dist/knowledge/skills/config-design-system/references/framework-surface-policy-api.md +37 -0
  717. package/dist/knowledge/skills/config-design-system/references/framework-theme-composition-api.md +235 -0
  718. package/dist/knowledge/skills/config-design-system/references/theme-design-principles.md +202 -0
  719. package/dist/knowledge/skills/config-navigation/references/framework-content-width-api.md +16 -5
  720. package/dist/knowledge/skills/config-navigation/references/how-navigation-resolves.md +1 -1
  721. package/dist/knowledge/skills/config-navigation/references/navigation-configuration-map.md +7 -1
  722. package/dist/knowledge/skills/config-saas/SKILL.md +2 -0
  723. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +11 -3
  724. package/dist/knowledge/skills/config-saas/references/framework-audit-trail-config-api.md +18 -5
  725. package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +314 -0
  726. package/dist/knowledge/skills/config-saas/references/framework-background-work-api.md +29 -1
  727. package/dist/knowledge/skills/config-saas/references/framework-capability-resolution-api.md +8 -0
  728. package/dist/knowledge/skills/config-saas/references/framework-content-security-policy-api.md +1 -2
  729. package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +1182 -0
  730. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +61 -0
  731. package/dist/knowledge/skills/config-saas/references/framework-systems-of-record-api.md +56 -11
  732. package/dist/knowledge/skills/config-saas/references/framework-value-moments-api.md +22 -0
  733. package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +106 -14
  734. package/dist/knowledge/skills/config-saas-backend/SKILL.md +5 -3
  735. package/dist/knowledge/skills/config-saas-backend/references/framework-application-owner-organization-codes-api.md +9 -10
  736. package/dist/knowledge/skills/config-saas-backend/references/framework-federated-identity-provider-private-networks-api.md +6 -4
  737. package/dist/knowledge/skills/config-saas-backend/references/framework-organization-types-api.md +155 -92
  738. package/dist/knowledge/skills/configure-billing/SKILL.md +14 -0
  739. package/dist/knowledge/skills/configure-billing/references/example-backend-provider-module-shape.md +10 -0
  740. package/dist/knowledge/skills/configure-billing/references/framework-metered-usage-recording-api.md +109 -0
  741. package/dist/knowledge/skills/configure-coding-agent/references/framework-acp-execution-profile-api.md +18 -2
  742. package/dist/knowledge/skills/email-add-template/SKILL.md +46 -5
  743. package/dist/knowledge/skills/email-add-template/references/framework-email-send-api.md +7 -0
  744. package/dist/knowledge/skills/email-add-template/references/framework-email-template-api.md +134 -0
  745. package/dist/knowledge/skills/engine-product-definitions/references/framework-metered-usage-recording-api.md +28 -0
  746. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +71 -14
  747. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-a2a-token-budget-api.md +95 -13
  748. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +9 -1
  749. package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +98 -9
  750. package/dist/knowledge/skills/flows-actors-autonomous-agents/references/binding-and-review.md +44 -16
  751. package/dist/knowledge/skills/flows-actors-autonomous-agents/references/framework-autonomous-agent-api.md +160 -23
  752. package/dist/knowledge/skills/flows-actors-autonomous-agents/references/framework-inbound-agents-api.md +10 -3
  753. package/dist/knowledge/skills/flows-actors-autonomous-agents/references/tool-posture.md +14 -2
  754. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +281 -20
  755. package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +70 -14
  756. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-behavior-reports-api.md +451 -0
  757. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-content-guardrails-api.md +406 -0
  758. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-operation-record-api.md +201 -0
  759. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-suspension-api.md +172 -0
  760. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-ask-person-tool-api.md +121 -0
  761. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-decision-deadlines-api.md +7 -0
  762. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-realtime-catalog.md +63 -0
  763. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +324 -7
  764. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +95 -6
  765. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-model-spend-limits-api.md +255 -0
  766. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-present-records-tool-api.md +150 -0
  767. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-retrieval-tool-api.md +251 -0
  768. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-tool-dispatch-obligations-api.md +112 -16
  769. package/dist/knowledge/skills/flows-actors-declared-flow/SKILL.md +339 -0
  770. package/dist/knowledge/skills/flows-actors-declared-flow/references/framework-flow-model-api.md +264 -0
  771. package/dist/knowledge/skills/flows-actors-declared-flow/references/framework-start-flow-api.md +133 -0
  772. package/dist/knowledge/skills/flows-actors-declared-flow/references/step-kinds.md +16 -0
  773. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +91 -5
  774. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +45 -0
  775. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-invocation-api.md +14 -3
  776. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-operation-and-model-api.md +13 -6
  777. package/dist/knowledge/skills/frontend-component-catalog/SKILL.md +5 -4
  778. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +27 -17
  779. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +136 -14
  780. package/dist/knowledge/skills/human-decision-notices/SKILL.md +150 -0
  781. package/dist/knowledge/skills/human-decision-notices/references/framework-decision-card-wording-api.md +292 -0
  782. package/dist/knowledge/skills/human-decision-notices/references/framework-decision-notice-handler-api.md +340 -0
  783. package/dist/knowledge/skills/i18n-label-generation/SKILL.md +17 -1
  784. package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +1 -1
  785. package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +4 -1
  786. package/dist/knowledge/skills/inbound-channels/SKILL.md +66 -8
  787. package/dist/knowledge/skills/inbound-channels/references/email-channel.md +34 -1
  788. package/dist/knowledge/skills/inbound-channels/references/framework-inbound-channel-api.md +78 -6
  789. package/dist/knowledge/skills/inbound-channels/references/framework-inbound-email-api.md +8 -8
  790. package/dist/knowledge/skills/inbound-channels/references/framework-inbound-handler-api.md +434 -6
  791. package/dist/knowledge/skills/inbound-channels/references/framework-inbound-pipelines-api.md +73 -0
  792. package/dist/knowledge/skills/inbound-channels/references/inbound-delivery-lifecycle.md +1 -1
  793. package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +24 -13
  794. package/dist/knowledge/skills/infra-environment-config/SKILL.md +107 -2
  795. package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +9 -1
  796. package/dist/knowledge/skills/infra-environment-config/references/framework-infrastructure-host-api.md +2 -0
  797. package/dist/knowledge/skills/infra-environment-config/references/framework-platform-key-management-api.md +294 -0
  798. package/dist/knowledge/skills/layout-2d-adoption/SKILL.md +158 -0
  799. package/dist/knowledge/skills/layout-2d-adoption/references/choosing-a-layout.md +43 -0
  800. package/dist/knowledge/skills/layout-2d-adoption/references/framework-2d-layout-authoring-api.md +167 -0
  801. package/dist/knowledge/skills/layout-2d-adoption/references/framework-2d-layout-registration-api.md +101 -0
  802. package/dist/knowledge/skills/layout-2d-adoption/references/framework-2d-layout-settings-api.md +59 -0
  803. package/dist/knowledge/skills/layout-2d-adoption/references/framework-shell-motion-api.md +415 -0
  804. package/dist/knowledge/skills/layout-3d-adoption/SKILL.md +1 -0
  805. package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-layout-contract-api.md +65 -32
  806. package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-layout-registration-api.md +14 -36
  807. package/dist/knowledge/skills/layout-3d-adoption/references/framework-shell-building-blocks-api.md +7 -3
  808. package/dist/knowledge/skills/local-environment-bootstrap/references/derived-artifact-currency.md +4 -2
  809. package/dist/knowledge/skills/market-authoring-overview/references/framework-market-references-api.md +14 -1
  810. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +9 -0
  811. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +9 -0
  812. package/dist/knowledge/skills/market-generation-cli/SKILL.md +2 -1
  813. package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +2 -1
  814. package/dist/knowledge/skills/minion-authoring/examples/contained-tick.example.md +1 -1
  815. package/dist/knowledge/skills/minion-authoring/references/framework-minion-tick-contract.md +2 -2
  816. package/dist/knowledge/skills/model-cost-attribution/SKILL.md +40 -10
  817. package/dist/knowledge/skills/model-cost-attribution/references/framework-model-cost-pricing-api.md +57 -2
  818. package/dist/knowledge/skills/model-cost-attribution/references/framework-model-cost-summary-api.md +57 -21
  819. package/dist/knowledge/skills/model-cost-attribution/references/framework-work-attribution-api.md +7 -3
  820. package/dist/knowledge/skills/model-cost-attribution/references/framework-work-unit-api.md +150 -4
  821. package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +9 -0
  822. package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +81 -1
  823. package/dist/knowledge/skills/module-relationships/SKILL.md +50 -27
  824. package/dist/knowledge/skills/module-relationships/references/framework-resource-relationship-authoring-api.md +8 -4
  825. package/dist/knowledge/skills/organization-relationships/SKILL.md +668 -0
  826. package/dist/knowledge/skills/organization-relationships/references/framework-organization-relationships-api.md +1233 -0
  827. package/dist/knowledge/skills/organization-relationships/references/framework-relationship-capability-grants-api.md +243 -0
  828. package/dist/knowledge/skills/organization-relationships/references/framework-relationship-grantor-authentication-api.md +284 -0
  829. package/dist/knowledge/skills/organization-relationships/references/framework-relationship-kinds-api.md +521 -0
  830. package/dist/knowledge/skills/organization-relationships/references/framework-relationship-record-separation-api.md +162 -0
  831. package/dist/knowledge/skills/organization-relationships/references/framework-representative-activity-api.md +145 -0
  832. package/dist/knowledge/skills/pdf-template-authoring/references/framework-pdf-collection-template-api.md +5 -3
  833. package/dist/knowledge/skills/professional-qualifications/SKILL.md +173 -0
  834. package/dist/knowledge/skills/professional-qualifications/references/choosing-who-may-decide.md +53 -0
  835. package/dist/knowledge/skills/professional-qualifications/references/framework-operation-approval-requirement-api.md +67 -0
  836. package/dist/knowledge/skills/professional-qualifications/references/framework-operation-required-qualifications-api.md +39 -0
  837. package/dist/knowledge/skills/professional-qualifications/references/framework-professional-qualifications-api.md +223 -0
  838. package/dist/knowledge/skills/provider-address-lookup/SKILL.md +1 -1
  839. package/dist/knowledge/skills/provider-address-lookup/references/framework-browser-operation-policy-api.md +3 -3
  840. package/dist/knowledge/skills/provider-backend-package/SKILL.md +138 -4
  841. package/dist/knowledge/skills/provider-backend-package/references/framework-optional-runtime-peers.md +32 -28
  842. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-augmentation-api.md +16 -0
  843. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-file-storage-adapter-api.md +6 -0
  844. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-inbound-endpoint-api.md +634 -0
  845. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-incremental-consent-api.md +70 -0
  846. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-shared-connection-api.md +61 -2
  847. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-subject-erasure-effect-api.md +222 -0
  848. package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +9 -5
  849. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +9 -2
  850. package/dist/knowledge/skills/provider-frontend-module/SKILL.md +47 -5
  851. package/dist/knowledge/skills/provider-frontend-module/references/framework-on-demand-capabilities-api.md +306 -0
  852. package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +11 -3
  853. package/dist/knowledge/skills/provider-operation-calls/SKILL.md +26 -14
  854. package/dist/knowledge/skills/provider-operation-calls/references/browser-door-answers.md +56 -18
  855. package/dist/knowledge/skills/provider-operation-calls/references/framework-browser-operation-policy-api.md +1 -1
  856. package/dist/knowledge/skills/provider-operation-calls/references/framework-frontend-execute-operation-api.md +143 -25
  857. package/dist/knowledge/skills/provider-operation-calls/references/framework-provider-operation-executor-api.md +6 -0
  858. package/dist/knowledge/skills/provider-operation-calls/references/framework-provider-scope-reauthorization-api.md +9 -6
  859. package/dist/knowledge/skills/provider-operation-calls/references/framework-rest-operation-contract-api.md +256 -1
  860. package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +71 -35
  861. package/dist/knowledge/skills/rate-limit-authoring/references/framework-rate-limit-policy-api.md +27 -13
  862. package/dist/knowledge/skills/resource-add-field/examples/add-priority-field-to-todos.example.md +32 -12
  863. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +132 -55
  864. package/dist/knowledge/skills/resource-add-resource/SKILL.md +49 -4
  865. package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +58 -2
  866. package/dist/knowledge/skills/resource-chat-commands/SKILL.md +137 -0
  867. package/dist/knowledge/skills/resource-chat-commands/references/framework-resource-chat-command-contract.md +72 -0
  868. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +102 -4
  869. package/dist/knowledge/skills/resource-config-wiring/references/framework-administrative-continuity-codes-api.md +4 -4
  870. package/dist/knowledge/skills/resource-config-wiring/references/framework-authority-audit-interpretation.md +17 -8
  871. package/dist/knowledge/skills/resource-config-wiring/references/framework-collection-operation-declarations.md +6 -0
  872. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-approval-api.md +323 -0
  873. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +18 -0
  874. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-bulk-api.md +159 -0
  875. package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +60 -3
  876. package/dist/knowledge/skills/resource-config-wiring/references/framework-request-field-offers-api.md +168 -0
  877. package/dist/knowledge/skills/resource-config-wiring/references/framework-required-features-api.md +20 -0
  878. package/dist/knowledge/skills/resource-config-wiring/references/framework-retention-policy-operations.md +1 -1
  879. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-operation-scope-enums-api.md +3 -2
  880. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +195 -23
  881. package/dist/knowledge/skills/resource-config-wiring/references/framework-scope-admissions-api.md +108 -2
  882. package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +242 -107
  883. package/dist/knowledge/skills/resource-config-wiring/references/framework-user-notifications-api.md +176 -10
  884. package/dist/knowledge/skills/resource-config-wiring/references/framework-webhook-events-api.md +116 -0
  885. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +88 -50
  886. package/dist/knowledge/skills/resource-external-data/SKILL.md +280 -64
  887. package/dist/knowledge/skills/resource-external-data/references/bidirectional-pipelines.md +335 -0
  888. package/dist/knowledge/skills/resource-external-data/references/declared-expressions.md +18 -6
  889. package/dist/knowledge/skills/resource-external-data/references/erasure-suppression.md +71 -12
  890. package/dist/knowledge/skills/resource-external-data/references/facet-augmentations.md +6 -0
  891. package/dist/knowledge/skills/resource-external-data/references/framework-external-data-pipeline-api.md +81 -18
  892. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +238 -49
  893. package/dist/knowledge/skills/resource-external-data/references/framework-pipeline-admin-endpoints-api.md +111 -11
  894. package/dist/knowledge/skills/resource-external-data/references/framework-system-of-record-capabilities-api.md +145 -0
  895. package/dist/knowledge/skills/resource-external-data/references/incremental-extraction.md +30 -4
  896. package/dist/knowledge/skills/resource-external-data/references/odata-v2-sources.md +21 -9
  897. package/dist/knowledge/skills/resource-external-data/references/outbound-pipelines.md +61 -14
  898. package/dist/knowledge/skills/resource-external-data/references/provenance-cue.md +18 -2
  899. package/dist/knowledge/skills/resource-external-data/references/rate-budgets-and-pacing.md +3 -1
  900. package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +39 -13
  901. package/dist/knowledge/skills/resource-external-data/references/remote-references.md +17 -7
  902. package/dist/knowledge/skills/resource-external-data/references/requested-keys.md +104 -0
  903. package/dist/knowledge/skills/resource-external-data/references/system-of-record-actions.md +1 -1
  904. package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +17 -4
  905. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-resource-mcp-exposure-contract.md +2 -2
  906. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-catalogue-withdrawal-and-verification.md +1 -1
  907. package/dist/knowledge/skills/resource-rag-source-fields/SKILL.md +6 -0
  908. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +31 -1
  909. package/dist/knowledge/skills/resource-retention-binding/SKILL.md +3 -1
  910. package/dist/knowledge/skills/resource-retention-binding/references/framework-legal-holds-api.md +68 -5
  911. package/dist/knowledge/skills/resource-retention-binding/references/framework-statutory-retention-api.md +25 -0
  912. package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +26 -10
  913. package/dist/knowledge/skills/resource-schema-authoring/examples/add-enum-field-with-ui.example.md +23 -7
  914. package/dist/knowledge/skills/resource-schema-authoring/references/computed-totals.md +9 -7
  915. package/dist/knowledge/skills/resource-schema-authoring/references/field-type-selection.md +2 -0
  916. package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +79 -6
  917. package/dist/knowledge/skills/resource-schema-authoring/references/framework-erasure-scrub-treatments-api.md +19 -22
  918. package/dist/knowledge/skills/resource-schema-authoring/references/framework-personal-data-category-api.md +127 -12
  919. package/dist/knowledge/skills/resource-schema-authoring/references/framework-schema-family-api.md +17 -4
  920. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +32 -4
  921. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +44 -5
  922. package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +116 -66
  923. package/dist/knowledge/skills/resource-schema-authoring/references/framework-system-managed-fields-api.md +2 -1
  924. package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +203 -18
  925. package/dist/knowledge/skills/resource-schema-authoring/references/shared-layer-decorator-checklist.md +6 -0
  926. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +155 -76
  927. package/dist/knowledge/skills/resource-ui-behavior/references/framework-collection-filter-presets-api.md +19 -17
  928. package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +120 -1
  929. package/dist/knowledge/skills/resource-ui-behavior/references/framework-enum-frontend-handling-api.md +41 -7
  930. package/dist/knowledge/skills/resource-ui-behavior/references/framework-field-tiles-api.md +114 -0
  931. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +168 -58
  932. package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +25 -9
  933. package/dist/knowledge/skills/resource-ui-behavior/references/framework-primitive-ui-api.md +15 -3
  934. package/dist/knowledge/skills/resource-ui-behavior/references/framework-related-resource-embeds-api.md +151 -1
  935. package/dist/knowledge/skills/resource-ui-behavior/references/framework-resource-layout-templates-api.md +144 -57
  936. package/dist/knowledge/skills/resource-ui-behavior/references/record-page-anatomy.md +131 -0
  937. package/dist/knowledge/skills/resource-ui-behavior/references/surface-decisions.md +57 -31
  938. package/dist/knowledge/skills/resource-ui-behavior/references/visual-quality-rubric.md +56 -0
  939. package/dist/knowledge/skills/seeding-authoring/references/data-seeding-mode-picker.md +16 -1
  940. package/dist/knowledge/skills/seeding-operations/references/data-seeding-admin-runbook.md +15 -8
  941. package/dist/knowledge/skills/seeding-operations/references/framework-data-seeding-operations-api.md +3 -0
  942. package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +42 -11
  943. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +141 -32
  944. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +66 -4
  945. package/dist/knowledge/skills/spec-catalog-authoring/SKILL.md +5 -4
  946. package/dist/knowledge/skills/spec-catalog-authoring/references/catalog-spec-pattern-overview.md +5 -4
  947. package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +9 -0
  948. package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +15 -7
  949. package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +71 -14
  950. package/dist/knowledge/skills/spec-update-after-change/references/framework-spec-factory-api.md +19 -5
  951. package/dist/knowledge/skills/views-add-composite-view/SKILL.md +14 -5
  952. package/dist/knowledge/skills/views-add-custom-view/SKILL.md +10 -1
  953. package/dist/knowledge/skills/views-add-custom-view/references/framework-focus-indicator-api.md +145 -0
  954. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +5 -0
  955. package/dist/knowledge/skills/views-chart-authoring/references/framework-chart-view-contracts-api.md +13 -0
  956. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +11 -4
  957. package/dist/knowledge/skills/views-execution-authoring/SKILL.md +11 -2
  958. package/dist/knowledge/skills/views-execution-authoring/references/framework-execution-view-contracts-api.md +17 -3
  959. package/dist/knowledge/skills/website-anonymous-session/SKILL.md +61 -25
  960. package/dist/knowledge/skills/website-blog-authoring/SKILL.md +251 -78
  961. package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +1064 -192
  962. package/dist/knowledge/skills/website-building-blocks/SKILL.md +337 -0
  963. package/dist/knowledge/skills/website-building-blocks/references/framework-website-blocks-api.md +3050 -0
  964. package/dist/knowledge/skills/website-building-blocks/references/framework-website-demo-examples.md +627 -0
  965. package/dist/knowledge/skills/website-building-blocks/references/framework-website-product-kit-api.md +3309 -0
  966. package/dist/knowledge/skills/website-building-blocks/references/website-visual-quality-rubric.md +75 -0
  967. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +39 -18
  968. package/dist/knowledge/skills/website-bundle-discipline/references/example-website-button-override.md +8 -12
  969. package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +18 -5
  970. package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +84 -28
  971. package/dist/knowledge/skills/website-factory-advanced/SKILL.md +67 -64
  972. package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +58 -23
  973. package/dist/knowledge/skills/website-inbound-contact-forms/references/framework-submission-challenge-api.md +5 -1
  974. package/dist/knowledge/skills/website-label-pack/SKILL.md +24 -17
  975. package/dist/knowledge/skills/website-layout-overrides/SKILL.md +112 -77
  976. package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +24 -13
  977. package/dist/knowledge/skills/website-motion-design/SKILL.md +277 -0
  978. package/dist/knowledge/skills/website-motion-design/references/framework-motion-api.md +1562 -0
  979. package/dist/knowledge/skills/website-motion-design/references/industry-practice.md +28 -0
  980. package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +255 -397
  981. package/dist/knowledge/skills/website-navigation-authoring/references/framework-menu-api.md +712 -0
  982. package/dist/knowledge/skills/website-navigation-authoring/references/framework-public-document-links-api.md +28 -6
  983. package/dist/knowledge/skills/website-navigation-authoring/references/menu-keys-and-styling.md +151 -0
  984. package/dist/knowledge/skills/website-navigation-authoring/references/worked-examples-header-footer.md +131 -326
  985. package/dist/knowledge/skills/website-page-authoring/SKILL.md +160 -67
  986. package/dist/knowledge/skills/website-page-authoring/references/framework-page-kinds-api.md +982 -0
  987. package/dist/knowledge/skills/website-page-authoring/references/framework-site-context-loader-api.md +24 -3
  988. package/dist/knowledge/skills/website-page-authoring/references/homepage-content-and-art-direction.md +19 -0
  989. package/dist/knowledge/skills/website-page-authoring/references/page-kinds.md +118 -0
  990. package/dist/knowledge/skills/website-page-variants/SKILL.md +70 -69
  991. package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +48 -28
  992. package/dist/knowledge/skills/website-section-comparison/SKILL.md +1171 -0
  993. package/dist/knowledge/skills/website-section-comparison/references/define-website-section-api.md +679 -0
  994. package/dist/knowledge/skills/website-section-comparison/references/framework-website-tables-api.md +487 -0
  995. package/dist/knowledge/skills/website-section-contact/SKILL.md +408 -185
  996. package/dist/knowledge/skills/website-section-contact/references/define-website-section-api.md +197 -119
  997. package/dist/knowledge/skills/website-section-cta/SKILL.md +398 -234
  998. package/dist/knowledge/skills/website-section-cta/references/define-website-section-api.md +197 -119
  999. package/dist/knowledge/skills/website-section-faq/SKILL.md +561 -302
  1000. package/dist/knowledge/skills/website-section-faq/references/define-website-section-api.md +197 -119
  1001. package/dist/knowledge/skills/website-section-faq/references/framework-website-faq-api.md +489 -0
  1002. package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +647 -274
  1003. package/dist/knowledge/skills/website-section-feature-benefit-summary/references/define-website-section-api.md +197 -119
  1004. package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +572 -264
  1005. package/dist/knowledge/skills/website-section-feature-detail/references/define-website-section-api.md +197 -119
  1006. package/dist/knowledge/skills/website-section-footer-cta/SKILL.md +532 -233
  1007. package/dist/knowledge/skills/website-section-footer-cta/references/define-website-section-api.md +197 -119
  1008. package/dist/knowledge/skills/website-section-hero/SKILL.md +603 -332
  1009. package/dist/knowledge/skills/website-section-hero/references/define-website-section-api.md +198 -120
  1010. package/dist/knowledge/skills/website-section-how-it-works/SKILL.md +1150 -0
  1011. package/dist/knowledge/skills/website-section-how-it-works/references/define-website-section-api.md +679 -0
  1012. package/dist/knowledge/skills/website-section-how-it-works/references/framework-website-steps-api.md +337 -0
  1013. package/dist/knowledge/skills/website-section-integrations/SKILL.md +974 -0
  1014. package/dist/knowledge/skills/website-section-integrations/references/define-website-section-api.md +679 -0
  1015. package/dist/knowledge/skills/website-section-integrations/references/framework-website-marquee-api.md +825 -0
  1016. package/dist/knowledge/skills/website-section-latest-posts/SKILL.md +928 -0
  1017. package/dist/knowledge/skills/website-section-latest-posts/references/define-website-section-api.md +679 -0
  1018. package/dist/knowledge/skills/website-section-latest-posts/references/framework-website-latest-posts-api.md +465 -0
  1019. package/dist/knowledge/skills/website-section-pricing/SKILL.md +549 -378
  1020. package/dist/knowledge/skills/website-section-pricing/examples/pricing-offers.example.md +77 -0
  1021. package/dist/knowledge/skills/website-section-pricing/references/define-website-section-api.md +197 -119
  1022. package/dist/knowledge/skills/website-section-pricing/references/framework-pricing-catalog-api.md +2 -1
  1023. package/dist/knowledge/skills/website-section-pricing/references/framework-website-pricing-api.md +670 -0
  1024. package/dist/knowledge/skills/website-section-problem/SKILL.md +1150 -0
  1025. package/dist/knowledge/skills/website-section-problem/references/define-website-section-api.md +679 -0
  1026. package/dist/knowledge/skills/website-section-problem/references/framework-website-card-grid-api.md +664 -0
  1027. package/dist/knowledge/skills/website-section-product-showcase/SKILL.md +1322 -0
  1028. package/dist/knowledge/skills/website-section-product-showcase/references/define-website-section-api.md +679 -0
  1029. package/dist/knowledge/skills/website-section-product-showcase/references/framework-website-card-grid-api.md +533 -0
  1030. package/dist/knowledge/skills/website-section-product-showcase/references/framework-website-product-tour-api.md +917 -0
  1031. package/dist/knowledge/skills/website-section-roadmap/SKILL.md +1133 -0
  1032. package/dist/knowledge/skills/website-section-roadmap/references/define-website-section-api.md +679 -0
  1033. package/dist/knowledge/skills/website-section-roadmap/references/framework-website-roadmap-api.md +475 -0
  1034. package/dist/knowledge/skills/website-section-social-proof/SKILL.md +739 -315
  1035. package/dist/knowledge/skills/website-section-social-proof/references/define-website-section-api.md +197 -119
  1036. package/dist/knowledge/skills/website-section-social-proof/references/framework-website-quote-cards-api.md +623 -0
  1037. package/dist/knowledge/skills/website-section-solution-paths/SKILL.md +1057 -0
  1038. package/dist/knowledge/skills/website-section-solution-paths/references/define-website-section-api.md +679 -0
  1039. package/dist/knowledge/skills/website-section-solution-paths/references/framework-website-solution-paths-api.md +477 -0
  1040. package/dist/knowledge/skills/website-section-stats/SKILL.md +1086 -0
  1041. package/dist/knowledge/skills/website-section-stats/references/define-website-section-api.md +679 -0
  1042. package/dist/knowledge/skills/website-section-stats/references/framework-website-stats-api.md +517 -0
  1043. package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +183 -67
  1044. package/dist/knowledge/skills/website-seo-aeo-geo/references/aeo-api.md +575 -57
  1045. package/dist/knowledge/skills/website-seo-aeo-geo/references/geo-api.md +1 -1
  1046. package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +6 -94
  1047. package/dist/knowledge/skills/website-theme-authoring/SKILL.md +226 -0
  1048. package/dist/knowledge/skills/website-theme-authoring/references/framework-website-theme-api.md +893 -0
  1049. package/dist/knowledge/skills/worker-authoring/references/framework-worker-init-contract.md +4 -2
  1050. package/dist/knowledge/topic-index.json +16442 -8572
  1051. package/package.json +4 -4
  1052. package/dist/knowledge/references/example.organizations.serves-as-provider.md +0 -12
  1053. package/dist/knowledge/references/saas.models.organizations.service-provider-activity-feed.md +0 -121
  1054. package/dist/knowledge/references/saas.models.organizations.service-provider-client-controls.md +0 -49
  1055. package/dist/knowledge/references/saas.models.organizations.service-provider-relationships.md +0 -567
  1056. package/dist/knowledge/references/saas.website.root-config.navigation.md +0 -37
  1057. package/dist/knowledge/skills/service-provider-relationships/SKILL.md +0 -455
  1058. package/dist/knowledge/skills/service-provider-relationships/references/framework-organization-types-api.md +0 -270
  1059. package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-activity-feed-api.md +0 -129
  1060. package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-capability-grants-api.md +0 -161
  1061. package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-client-authentication-api.md +0 -224
  1062. package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-relationships-api.md +0 -576
@@ -8,7 +8,7 @@ current contract — never a hand-mirrored copy.
8
8
  ## Frontmatter schema
9
9
 
10
10
  The Zod 4 schema every MDX file's frontmatter is validated against
11
- at render time (Path Z). Field-level rationale (why `title` /
11
+ at render time. Field-level rationale (why `title` /
12
12
  `summary` are raw strings instead of label keys, why `slug` is
13
13
  branded, why `publishedAt` is stored as ISO-string rather than
14
14
  `Date`) lives in the JSDoc.
@@ -21,13 +21,27 @@ branded, why `publishedAt` is stored as ISO-string rather than
21
21
 
22
22
  ### Origin Package: `@wildo-ai/saas-website`
23
23
 
24
+ ```typescript
25
+ /**
26
+ * Where a website's posts live, relative to its root: one folder per locale, named by its segment
27
+ * (`languagePathSegment`: `fr`, `en-gb`), `src/content/blog/<segment>/<file>.mdx`. The blog collection loads from here, and `wildo website look` reads the same
28
+ * folder to open each post, so both find the same posts.
29
+ */
30
+ export const WEBSITE_BLOG_CONTENT_BASE = './src/content/blog';
31
+
32
+ /** The posts the collection loads, relative to `WEBSITE_BLOG_CONTENT_BASE`: an `.mdx` file in a locale folder. */
33
+ export const WEBSITE_BLOG_CONTENT_PATTERN = '*/*.mdx';
34
+ ```
35
+
36
+ ### Origin Package: `@wildo-ai/saas-website`
37
+
24
38
  ```typescript
25
39
  *
26
40
  * `BlogPostFrontmatter` — the YAML frontmatter contract every blog
27
41
  * post MDX file under `examples/<app>/website/src/content/blog/<locale>/`
28
42
  * MUST satisfy.
29
43
  *
30
- * **Q16=B context**: blogs are authored as full per-locale MDX files
44
+ * **Context**: blogs are authored as full per-locale MDX files
31
45
  * (one MDX per (slug, locale) pair), NOT as label-pack-keyed content.
32
46
  * The frontmatter therefore carries strings directly (`title`,
33
47
  * `summary`) rather than label keys — there is no shared
@@ -55,13 +69,41 @@ branded, why `publishedAt` is stored as ISO-string rather than
55
69
  * parsers preserve the original string and the SEO emitters need
56
70
  * the original ISO formatting (no Date.toISOString() round-trip
57
71
  * loss).
58
- * - `authorRef` — REQUIRED. Identifier of the author resolved by the
59
- * consumer's author registry (typically a `src/content/authors/<ref>.ts`
60
- * file). Brand keeps it distinct from page/section refs.
72
+ * - `authorRef` — REQUIRED. Identifier of the author, declared with its
73
+ * kind in the site's blog vocabulary (`WebsiteBlogVocabulary.authors`) and
74
+ * shown by its words, never as the ref. Brand keeps it distinct from
75
+ * page/section refs.
61
76
  * - `tags` — REQUIRED, possibly empty. Lowercase kebab-case tag
62
77
  * identifiers. Drives `og:article:tag` and the listing-page facets.
63
- * - `coverImageUrl` — OPTIONAL. CDN URL for the blog post hero image
64
- * and `og:image`.
78
+ * - `coverImageUrl` — OPTIONAL. The post's cover — its hero image, its
79
+ * index card and its `og:image` — as an absolute URL (a CDN) or as a
80
+ * path on the site itself (`/blog/covers/launch.png`, served from the
81
+ * site's `public/`). Use a raster image (PNG or JPEG): link previews read
82
+ * it through `og:image`, and an SVG there commonly shows no preview. A site path is what most sites have; the head
83
+ * renderer resolves it against the site's public origin wherever an
84
+ * absolute URL is required (`og:image`, the JSON-LD `image`).
85
+ * - `coverImageWidth` / `coverImageHeight` — the size of a cover the build
86
+ * cannot open, so REQUIRED together for an absolute-URL cover and refused
87
+ * for a site path. A cover is rendered through `WebsiteImage`, whose
88
+ * `width` and `height` let the browser reserve its space before it loads,
89
+ * so every cover needs a size. A site-path cover's size is MEASURED from
90
+ * its file in the site's `public/` by `resolveWebsiteBlogPostCover`
91
+ * (`@wildo-ai/saas-website/astro`), so a declared size there would be a
92
+ * second source that drifts the day the image is replaced. A remote image
93
+ * has no file the build can read (and the build does not fetch it), so
94
+ * its author states it. Astro's own `<Image />` infers a size for an image
95
+ * imported from `src/`, and for a remote image when asked to (`inferSize`,
96
+ * `inferRemoteSize()`), and requires `width` and `height` for an image in
97
+ * `public/`, "as Astro is unable to analyze these files". A cover is a
98
+ * `public/` URL in frontmatter that this build can still open, so it
99
+ * measures it rather than asks: one step past Astro.
100
+ * spec-cite: https://docs.astro.build/en/reference/modules/astro-assets/ —
101
+ * `<Image />`, "width and height (required for images in public/)".
102
+ *
103
+ * The schema carries a cross-field refinement, so Zod 4 refuses `.pick()`,
104
+ * `.omit()` and `.partial()` on it, and `.extend()` cannot remove a field: to
105
+ * derive a narrower schema, build a new `z.object` from the fields of
106
+ * `BlogPostFrontmatterSchema.shape` it needs.
65
107
  *
66
108
  * **Why a separate file from the page-manifest**: a blog post is NOT
67
109
  * a `WebsitePageManifest` (no React `pageComponent` to mount — the
@@ -111,6 +153,18 @@ export const BlogPostTagSchema: typeof _BlogPostTagSchema = _BlogPostTagSchema;
111
153
 
112
154
  export type BlogPostTag = z.infer<typeof _BlogPostTagSchema>;
113
155
 
156
+ /**
157
+ * A cover served by the site itself: one leading slash, never two (`//host/x` is a protocol-relative URL to another
158
+ * host). The one definition of "a site path" for a cover — the schema's refinement and the build's measurement both
159
+ * read it, so they cannot disagree about which covers are measured.
160
+ */
161
+ export const BLOG_POST_COVER_SITE_PATH_PATTERN: RegExp = /^\/(?!\/)[^\s]*$/;
162
+
163
+ /** Whether a cover URL names a file on the site (measured at build) rather than a remote image (sized by its author). */
164
+ export function isBlogPostCoverSitePath(coverImageUrl: string): boolean {
165
+ return BLOG_POST_COVER_SITE_PATH_PATTERN.test(coverImageUrl);
166
+ }
167
+
114
168
  const _BlogPostFrontmatterSchema = z.object({
115
169
  title: z.string().min(1, { error: 'title must not be empty' }).max(200, { error: 'title must be at most 200 characters' }),
116
170
  summary: z.string().min(1, { error: 'summary must not be empty' }).max(400, { error: 'summary must be at most 400 characters' }),
@@ -119,7 +173,50 @@ const _BlogPostFrontmatterSchema = z.object({
119
173
  publishedAt: z.iso.datetime({ error: 'publishedAt must be an ISO-8601 datetime string' }),
120
174
  authorRef: _BlogAuthorRefSchema,
121
175
  tags: z.array(_BlogPostTagSchema),
122
- coverImageUrl: z.url({ error: 'coverImageUrl must be a valid URL' }).optional(),
176
+ coverImageUrl: z
177
+ .union([
178
+ z.url(),
179
+ // A path on the site: one leading slash, never two (`//host/x` is a protocol-relative URL to another host).
180
+ z.string().regex(BLOG_POST_COVER_SITE_PATH_PATTERN),
181
+ ], { error: 'coverImageUrl must be an absolute URL or a site path starting with "/"' })
182
+ .optional(),
183
+ coverImageWidth: z.int({ error: 'coverImageWidth must be a whole number of pixels' }).positive().optional(),
184
+ coverImageHeight: z.int({ error: 'coverImageHeight must be a whole number of pixels' }).positive().optional(),
185
+ }).superRefine((frontmatter, ctx) => {
186
+ const declaresSize = frontmatter.coverImageWidth !== undefined || frontmatter.coverImageHeight !== undefined;
187
+ if (frontmatter.coverImageUrl === undefined) {
188
+ if (declaresSize) {
189
+ ctx.addIssue({
190
+ code: 'custom',
191
+ path: ['coverImageWidth'],
192
+ message: 'coverImageWidth / coverImageHeight give the size of a cover, and this post has no coverImageUrl.',
193
+ });
194
+ }
195
+ return;
196
+ }
197
+ if (isBlogPostCoverSitePath(frontmatter.coverImageUrl)) {
198
+ if (declaresSize) {
199
+ ctx.addIssue({
200
+ code: 'custom',
201
+ path: ['coverImageWidth'],
202
+ message:
203
+ `The cover "${frontmatter.coverImageUrl}" is a file on the site, so its size is measured from that file. `
204
+ + 'Remove coverImageWidth / coverImageHeight.',
205
+ });
206
+ }
207
+ return;
208
+ }
209
+ for (const [field, value] of [['coverImageWidth', frontmatter.coverImageWidth], ['coverImageHeight', frontmatter.coverImageHeight]] as const) {
210
+ if (value === undefined) {
211
+ ctx.addIssue({
212
+ code: 'custom',
213
+ path: [field],
214
+ message:
215
+ `The cover "${frontmatter.coverImageUrl}" is not a file on the site, so the build cannot measure it. `
216
+ + 'Give its size in pixels with coverImageWidth and coverImageHeight.',
217
+ });
218
+ }
219
+ }
123
220
  });
124
221
 
125
222
  export const BlogPostFrontmatterSchema: typeof _BlogPostFrontmatterSchema =
@@ -128,6 +225,143 @@ export const BlogPostFrontmatterSchema: typeof _BlogPostFrontmatterSchema =
128
225
  export type BlogPostFrontmatter = z.infer<typeof _BlogPostFrontmatterSchema>;
129
226
  ```
130
227
 
228
+ ## A post's cover and its size — `resolveWebsiteBlogPostCover`
229
+
230
+ A cover is drawn through `WebsiteImage`, which needs its `width` and `height`. A cover the site serves (a site path,
231
+ a file in `public/`) is measured at build time from the file; a remote cover declares `coverImageWidth` /
232
+ `coverImageHeight` in its frontmatter. The route resolves it once in its `.astro` frontmatter
233
+ (`@wildo-ai/saas-website/astro`) and passes the result to the bridge island as `cover`; `<BlogPost>` refuses a cover
234
+ it was given no size for. `buildWebsiteBlogIndex` resolves every listed post's cover the same way.
235
+
236
+ ## Import Origins
237
+
238
+ - `@wildo-ai/saas-website`
239
+
240
+ ## Source Excerpts
241
+
242
+ ### Origin Package: `@wildo-ai/saas-website`
243
+
244
+ ```typescript
245
+ *
246
+ * `WebsiteBlogPostCover` — a post's cover as the page renders it: its source and its size in pixels.
247
+ *
248
+ * The frontmatter names a cover by URL (`coverImageUrl`). Rendering it needs its size too, because a cover is drawn
249
+ * through `WebsiteImage`, whose `width` and `height` let the browser reserve the image's space before it loads. The
250
+ * size is resolved at build time, on the Node side, by `resolveWebsiteBlogPostCover` (`@wildo-ai/saas-website/astro`):
251
+ * measured from the file for a cover the site serves, read from `coverImageWidth` / `coverImageHeight` for a remote
252
+ * one. The resolved cover then reaches every surface that draws it:
253
+ *
254
+ * - the post's own page, through its bridge island's `cover` prop into `<BlogPost>`;
255
+ * - a blog listing, through `WebsiteBlogIndexEntry.cover` (`buildWebsiteBlogIndex` resolves each one).
256
+ *
257
+ * So no site has to assume a ratio for its covers in CSS or in a card.
258
+ */
259
+ const _WebsiteBlogPostCoverSchema = z.strictObject({
260
+ /** The frontmatter's `coverImageUrl`, unchanged: a site path (`/blog/covers/launch.png`) or an absolute URL. */
261
+ src: z.string().min(1, { error: "A cover has a source." }),
262
+ /** The image's width in CSS pixels, as it is displayed (an EXIF-rotated photo is measured upright). */
263
+ width: z.int({ error: "A cover width is a whole number of pixels." }).positive(),
264
+ /** The image's height in CSS pixels, as it is displayed. */
265
+ height: z.int({ error: "A cover height is a whole number of pixels." }).positive(),
266
+ });
267
+
268
+ export const WebsiteBlogPostCoverSchema: typeof _WebsiteBlogPostCoverSchema = _WebsiteBlogPostCoverSchema;
269
+
270
+ export type WebsiteBlogPostCover = z.infer<typeof _WebsiteBlogPostCoverSchema>;
271
+ ```
272
+
273
+ ## Import Origins
274
+
275
+ - `@wildo-ai/saas-website`
276
+
277
+ ## Source Excerpts
278
+
279
+ ### Origin Package: `@wildo-ai/saas-website`
280
+
281
+ ```typescript
282
+ *
283
+ * `resolveWebsiteBlogPostCover(frontmatter, options?)` — a post's cover with its size, at build time.
284
+ *
285
+ * A cover is drawn through `WebsiteImage`, which needs `width` and `height` so the browser reserves its space before
286
+ * the image arrives. Where that size comes from depends on where the image lives:
287
+ *
288
+ * - **A cover the site serves** (`coverImageUrl: /blog/covers/launch.png`, a file in the site's `public/`) is
289
+ * MEASURED from that file, here, with `sharp`. Nobody types its size, so it cannot drift from the image the day the
290
+ * image is replaced; the frontmatter refuses a declared one.
291
+ * - **A remote cover** (`https://cdn.example.com/…`) has no file the build can open, so its author declares
292
+ * `coverImageWidth` and `coverImageHeight` in the frontmatter, and the schema requires both.
293
+ *
294
+ * Astro's own `<Image />` infers a size for an image imported from `src/`, and for a remote image when asked to
295
+ * (`inferSize`, `inferRemoteSize()`, which fetch it), and requires `width` and `height` for an image in `public/`, "as
296
+ * Astro is unable to analyze these files". A cover is named by a `public/` URL in frontmatter, and this build can still
297
+ * open that file, so it measures it rather than asking: one step past Astro. A remote cover is not fetched; its author
298
+ * states its size.
299
+ * spec-cite: https://docs.astro.build/en/reference/modules/astro-assets/ — `<Image />`, "width and height (required
300
+ * for images in public/)".
301
+ *
302
+ * Returns `undefined` for a post without a cover. Call it in the `.astro` frontmatter, which runs on Node during the
303
+ * build, and hand the result on: to the post's bridge island as `cover`, and nowhere else by hand —
304
+ * `buildWebsiteBlogIndex` calls it for every post it lists.
305
+ *
306
+ * @example
307
+ * const frontmatter = parseBlogPostFrontmatter(entry.data, { source: entry.id });
308
+ * const cover = await resolveWebsiteBlogPostCover(frontmatter);
309
+ * <BlogPostEnBridgeIsland client:load … cover={cover} />
310
+ *
311
+ * **The size is the image as displayed**: an EXIF-rotated photo is measured upright and an animated image by one
312
+ * frame, which is how a browser draws them (the same rule as the backend's uploaded-image analyzer).
313
+ *
314
+ * **It refuses rather than guesses.** A site path naming no file, a file outside `public/`, an image whose header
315
+ * gives no size, or a build where `sharp` cannot load all throw a `[blog-post-cover]` error naming the post's cover.
316
+ * A cover drawn at an invented size is the defect this exists to remove.
317
+ *
318
+ * `sharp` is loaded on the first site-path cover and only then, so a site whose covers are all remote never loads
319
+ * the native library.
320
+ */
321
+ export interface ResolveWebsiteBlogPostCoverOptions {
322
+ /**
323
+ * The directory the site serves its own files from, resolved against the build's working directory (the site root,
324
+ * where Astro runs). Defaults to Astro's own default, `WEBSITE_PUBLIC_DIR`. Set it only when the site's Astro config
325
+ * sets `publicDir`.
326
+ */
327
+ readonly publicDir?: string;
328
+ }
329
+
330
+ /** Where an Astro site serves its own files from, relative to the site root: Astro's default `publicDir`. */
331
+ export const WEBSITE_PUBLIC_DIR = "./public";
332
+
333
+ export async function resolveWebsiteBlogPostCover(
334
+ frontmatter: BlogPostFrontmatter,
335
+ options: ResolveWebsiteBlogPostCoverOptions = {},
336
+ ): Promise<WebsiteBlogPostCover | undefined> {
337
+ const src = frontmatter.coverImageUrl;
338
+ if (src === undefined) return undefined;
339
+ if (!isBlogPostCoverSitePath(src)) {
340
+ const { coverImageWidth: width, coverImageHeight: height } = frontmatter;
341
+ if (width === undefined || height === undefined) {
342
+ throw new Error(
343
+ `[blog-post-cover] The remote cover "${src}" of post "${frontmatter.slug}" (${frontmatter.locale}) has no size. ` +
344
+ "Parse the frontmatter with parseBlogPostFrontmatter first: it requires coverImageWidth and coverImageHeight " +
345
+ "for a cover that is not a file on the site.",
346
+ );
347
+ }
348
+ return { src, width, height };
349
+ }
350
+ const file = resolveCoverFile(src, frontmatter, resolve(options.publicDir ?? WEBSITE_PUBLIC_DIR));
351
+ let size: { width: number; height: number };
352
+ try {
353
+ size = await measureImageFile(file);
354
+ } catch (error) {
355
+ // The measurement is shared by every post naming this file, so its error names the file and each post adds itself.
356
+ throw new Error(
357
+ `[blog-post-cover] The cover "${src}" of post "${frontmatter.slug}" (${frontmatter.locale}): ` +
358
+ `${error instanceof Error ? error.message : String(error)}`,
359
+ );
360
+ }
361
+ return { src, width: size.width, height: size.height };
362
+ }
363
+ ```
364
+
131
365
  ## `<BlogPost>` — per-post page renderer
132
366
 
133
367
  The single per-post page renderer the framework ships. Strict-
@@ -153,17 +387,18 @@ every other section uses.
153
387
  * # What it does, end-to-end
154
388
  *
155
389
  * 1. **Strict frontmatter parse.** Reads the raw `entry.data` Astro
156
- * hands the page (passthrough at the content-collection layer per
157
- * Path Z, see `blog-post-collection.config.ts`) and runs it
390
+ * hands the page (passthrough at the content-collection layer, see
391
+ * `blog-post-collection.config.ts`) and runs it
158
392
  * through `BlogPostFrontmatterSchema` (Zod 4) — branded `slug` /
159
393
  * `authorRef` / `tags`, ISO-8601 `publishedAt`, optional
160
- * `coverImageUrl`. A failure throws synchronously with a
394
+ * `coverImageUrl` (sized by `coverImageWidth` / `coverImageHeight`
395
+ * when remote). A failure throws synchronously with a
161
396
  * `[blog-post] (source="…")` message; Astro halts the build and
162
397
  * points the operator to the offending MDX file.
163
398
  * 2. **Renders `<WebsitePageLayout>` with a stable blog-post page
164
399
  * ref.** The framework reserves `'blog-post'` as the
165
- * `WebsitePageRef` for every blog post (see `BLOG_POST_PAGE_REF`
166
- * below for the rationale). All blog posts share one page ref
400
+ * `WebsitePageRef` for every blog post (see `BLOG_POST_PAGE_REF`,
401
+ * in the blog vocabulary, for the rationale). All blog posts share one page ref
167
402
  * because the SECTION ref under that page is what's
168
403
  * blog-author-controlled (see point 3) — the page-level chrome,
169
404
  * label scope, and analytics signal are the same across the entire
@@ -175,12 +410,22 @@ every other section uses.
175
410
  * map for the duration of the render and ONLY the duration of the
176
411
  * render, so two blog posts on the same site can ship different
177
412
  * provider configs without leaking.
178
- * 4. **Emits a hero block (title / summary / publish date / author
179
- * handle / cover image)** from the parsed frontmatter, then yields
180
- * to the MDX body. Hero markup is intentionally minimal — the
181
- * consumer styles it via `WebsiteDesignTokens` custom properties.
182
- * No CSS file ships from this component; everything is inline
183
- * style + design-token references.
413
+ * 4. **Emits a hero block (title / summary / publish date / author /
414
+ * tags / cover image)** from the parsed frontmatter, then yields
415
+ * to the MDX body. The cover is drawn through `WebsiteImage` at the
416
+ * size the route resolved at build time (`cover`, from
417
+ * `resolveWebsiteBlogPostCover`), so the browser reserves its space
418
+ * and a site's image styling reaches it; a post whose frontmatter
419
+ * names a cover and that was handed no size is refused. The date is written for the page's locale
420
+ * (`formatWebsitePublicationDate`); the author and every tag are
421
+ * shown by their WORDS, the chrome labels their refs name
422
+ * (`websiteBlogAuthorLabelKey` / `websiteBlogTagLabelKey`), never
423
+ * as the refs themselves. The engine's blocks stylesheet draws the
424
+ * article from the theme (the reading measure, the title at the
425
+ * section heading's size, the opening, the prose's headings, lists
426
+ * and tables); a site adjusts it through
427
+ * `article[data-website-blog-post-slug]` and the
428
+ * `data-website-blog-post-*` hooks, like any block.
184
429
  *
185
430
  * # Why a blog-specific page renderer (vs. the generic page bridge)
186
431
  *
@@ -215,61 +460,21 @@ every other section uses.
215
460
  *
216
461
  * # Hydration + bundle boundary
217
462
  *
218
- * This component is NOT itself a Bridge factory — it's plain React
219
- * meant to be rendered inside an Astro `.astro` page. The consumer's
220
- * per-post Astro template (typically `src/pages/[locale]/blog/[slug].astro`)
221
- * imports `<BlogPost>` directly and renders it; the surrounding
222
- * `<WebsitePageBridgeIsland>` provides the runtime context. The MDX
223
- * runtime (`@mdx-js/react`) is React-only and pulls into the React
224
- * island bundle — bundle-isolation tests walk `mdx.ts` as their own
463
+ * A site does not render `<BlogPost>` itself. The blog bridge island
464
+ * (`createWebsiteBlogPostBridgeIsland`, `@wildo-ai/saas-website/mdx`)
465
+ * renders it, with the post's compiled MDX body as its children, inside
466
+ * ONE React island, so the `mdxComponents` the body embeds resolve against
467
+ * `<WebsiteMdxProvider>`. Rendering `<BlogPost>` from an `.astro` file with
468
+ * `<Content />` children would lose that provider: Astro renders the
469
+ * children of a React component separately. The factory's preamble shows
470
+ * the per-locale bridge and the `[slug].astro` route shell, which also
471
+ * resolves the cover's size and passes it as the island's `cover`.
472
+ *
473
+ * The MDX runtime (`@mdx-js/react`) is React-only and pulls into the
474
+ * React island bundle — bundle-isolation tests walk `mdx.ts` as their own
225
475
  * entry to keep the browser-facing closure auditable.
226
- *
227
- * Authoring example:
228
- *
229
- * ```astro
230
- * ---
231
- * // src/pages/blog/[slug].astro
232
- * import { getCollection, getEntry } from 'astro:content';
233
- * import { BlogPost } from '@wildo-ai/saas-website/mdx';
234
- * import { BLOG_POST_MDX_COMPONENTS } from '@/blog/mdx-components';
235
- *
236
- * export async function getStaticPaths() {
237
- * const posts = await getCollection('blog');
238
- * return posts
239
- * .filter((p) => p.data.locale === 'en')
240
- * .map((p) => ({ params: { slug: p.data.slug }, props: { entry: p } }));
241
- * }
242
- *
243
- * const { entry } = Astro.props;
244
- * const { Content } = await entry.render();
245
- * ---
246
- * <BlogPost
247
- * rawFrontmatter={entry.data}
248
- * source={entry.id}
249
- * mdxComponents={BLOG_POST_MDX_COMPONENTS}
250
- * client:load
251
- * >
252
- * <Content />
253
- * </BlogPost>
254
- * ```
255
476
  */
256
477
 
257
- /**
258
- * Reserved `WebsitePageRef` for every blog post page. Exported so
259
- * consumers can register a matching `BLOG_POST_PAGE_MANIFEST` in
260
- * their site root config (the page manifest carries the navigation
261
- * + label-pack scope; the renderer carries the structural layout).
262
- *
263
- * Branded as a plain string literal (cast through `unknown`) because:
264
- * - The `WebsitePageRef` brand is enforced via Zod's `.brand<>()`,
265
- * and parsing a string literal at module load time would require
266
- * dragging the Zod runtime into module init — gratuitous when the
267
- * ref is a compile-time constant.
268
- * - `WebsitePageLayout` re-parses any incoming `pageRef` string
269
- * defensively (see `WebsitePageLayoutProps.pageRef` JSDoc), so the
270
- * brand is re-asserted at render time anyway.
271
- */
272
- export const BLOG_POST_PAGE_REF: WebsitePageRef = 'blog-post' as unknown as WebsitePageRef;
273
478
 
274
479
  export interface BlogPostProps {
275
480
  /**
@@ -301,6 +506,11 @@ export interface BlogPostProps {
301
506
  * (no embedded React) needs no overrides.
302
507
  */
303
508
  mdxComponents?: WebsiteMdxComponentsMap;
509
+ /**
510
+ * The post's route, `/blog/<slug>`, forwarded to `<WebsitePageLayout>` so the server-rendered header knows the
511
+ * current page (see `WebsitePageLayoutProps.routePath`).
512
+ */
513
+ routePath?: string;
304
514
  /**
305
515
  * Per-page chrome overrides forwarded straight into
306
516
  * `<WebsitePageLayout>`. `null` suppresses the slot entirely;
@@ -311,10 +521,18 @@ export interface BlogPostProps {
311
521
  header?: ReactNode | null;
312
522
  footer?: ReactNode | null;
313
523
  /**
314
- * The compiled MDX body — typically `<Content />` from Astro's
315
- * `await entry.render()` call. Rendered inside the
316
- * `<WebsiteMdxProvider>` boundary so its inline `<TagName />`
317
- * references resolve against `mdxComponents`.
524
+ * The post's cover with its size, resolved at build time by
525
+ * `resolveWebsiteBlogPostCover` (`@wildo-ai/saas-website/astro`) in the
526
+ * route's `.astro` frontmatter and forwarded by the bridge island.
527
+ * Required exactly when the frontmatter names a cover, and its `src` must
528
+ * be that cover: the renderer refuses a cover it has no size for rather
529
+ * than drawing one at a guessed size.
530
+ */
531
+ cover?: WebsiteBlogPostCover;
532
+ /**
533
+ * The compiled MDX body — the post's MDX module, which the bridge island
534
+ * renders here. Rendered inside the `<WebsiteMdxProvider>` boundary so its
535
+ * inline `<TagName />` references resolve against `mdxComponents`.
318
536
  */
319
537
  children: ReactNode;
320
538
  }
@@ -328,11 +546,52 @@ export interface BlogPostProps {
328
546
  */
329
547
  const EMPTY_MDX_COMPONENTS: WebsiteMdxComponentsMap = Object.freeze({});
330
548
 
549
+ /**
550
+ * The cover to draw, checked against the frontmatter: `undefined` for a post without one; otherwise the resolved
551
+ * cover, whose source must be the frontmatter's. Refuses a cover it has no size for, a size for a post without a cover,
552
+ * and a size for a different image, each naming the remedy, because every one of them would draw a wrong picture.
553
+ */
554
+ function coverToRender(frontmatter: BlogPostFrontmatter, cover: unknown, source: string | undefined): WebsiteBlogPostCover | undefined {
555
+ const sourceSuffix = source !== undefined ? ` (source="${source}")` : '';
556
+ if (frontmatter.coverImageUrl === undefined) {
557
+ if (cover !== undefined) {
558
+ throw new Error(`[blog-post] A cover was passed for a post whose frontmatter names none${sourceSuffix}.`);
559
+ }
560
+ return undefined;
561
+ }
562
+ if (cover === undefined) {
563
+ throw new Error(
564
+ `[blog-post] The frontmatter names the cover "${frontmatter.coverImageUrl}" and no size for it reached the renderer`
565
+ + `${sourceSuffix}. Resolve it in the route's .astro frontmatter with \`await resolveWebsiteBlogPostCover(frontmatter)\``
566
+ + ' (@wildo-ai/saas-website/astro) and pass it to the bridge island as `cover`.',
567
+ );
568
+ }
569
+ const parsed = WebsiteBlogPostCoverSchema.safeParse(cover);
570
+ if (!parsed.success) {
571
+ throw new Error(`[blog-post] The cover passed to the renderer is not a { src, width, height } cover${sourceSuffix}.`);
572
+ }
573
+ if (parsed.data.src !== frontmatter.coverImageUrl) {
574
+ throw new Error(
575
+ `[blog-post] The cover passed to the renderer is "${parsed.data.src}", and the frontmatter names "${frontmatter.coverImageUrl}"`
576
+ + `${sourceSuffix}. Resolve the cover from this post's own frontmatter.`,
577
+ );
578
+ }
579
+ return parsed.data;
580
+ }
581
+
582
+ /** One tag, by its word: a component of its own so each tag reads its label through the hook. */
583
+ function BlogPostTag({ tag }: { tag: string }): ReactNode {
584
+ return <li>{useWebsiteLabelByKey(websiteBlogTagLabelKey(tag))}</li>;
585
+ }
586
+ BlogPostTag.displayName = 'BlogPostTag';
587
+
331
588
  export function BlogPost(props: BlogPostProps): ReactNode {
332
589
  const {
333
590
  rawFrontmatter,
334
591
  source,
335
592
  mdxComponents = EMPTY_MDX_COMPONENTS,
593
+ routePath,
594
+ cover: rawCover,
336
595
  header,
337
596
  footer,
338
597
  children,
@@ -349,30 +608,37 @@ export function BlogPost(props: BlogPostProps): ReactNode {
349
608
  const parseCtx: ParseBlogPostFrontmatterContext =
350
609
  source !== undefined ? { source } : {};
351
610
  const frontmatter = parseBlogPostFrontmatter(rawFrontmatter, parseCtx);
611
+ const cover = coverToRender(frontmatter, rawCover, source);
612
+ const { locale } = useWebsiteRuntime();
613
+ const authorName = useWebsiteLabelByKey(websiteBlogAuthorLabelKey(frontmatter.authorRef));
352
614
 
353
615
  /**
354
616
  * The hero markup intentionally uses semantic HTML5 elements
355
617
  * (`<header>`, `<h1>`, `<time>`, `<address>`) rather than raw
356
618
  * `<div>`s so screen readers and crawlers see the post structure
357
- * without consumer styling intervention. The styling story is:
358
- * design tokens via the surrounding `WebsiteRuntimeContext` +
359
- * the consumer's stylesheet — NO CSS ships from this file.
619
+ * without consumer styling intervention. No CSS ships from this
620
+ * file: the article's look is the engine's blocks stylesheet
621
+ * (`website-blocks.styles.ts`, drawn from the theme), which the
622
+ * page layout renders, and a site's own rules adjust it.
360
623
  */
361
624
  return (
362
625
  <WebsitePageLayout
363
626
  pageRef={BLOG_POST_PAGE_REF}
627
+ {...(routePath !== undefined ? { routePath } : {})}
364
628
  header={header}
365
629
  footer={footer}
366
630
  >
367
- <article data-website-blog-post-slug={frontmatter.slug as unknown as string}>
631
+ <article data-website-blog-post-slug={frontmatter.slug} data-website-prose="">
368
632
  <header>
369
- {frontmatter.coverImageUrl !== undefined ? (
370
- <img
371
- src={frontmatter.coverImageUrl}
372
- alt=""
373
- loading="eager"
374
- data-website-blog-post-cover
375
- />
633
+ {/*
634
+ * The cover is decorative (`alt=""`): the title beside it says what the post is. Eager, because it is the
635
+ * first thing on the page. The wrapper carries the blog's styling hook; the image is the primitive, so a
636
+ * site's `[data-website-primitive="image"]` styling reaches it too.
637
+ */}
638
+ {cover !== undefined ? (
639
+ <div data-website-blog-post-cover>
640
+ <WebsiteImage src={cover.src} alt="" width={cover.width} height={cover.height} loading="eager" />
641
+ </div>
376
642
  ) : null}
377
643
  <h1>{frontmatter.title}</h1>
378
644
  <p data-website-blog-post-summary>{frontmatter.summary}</p>
@@ -386,19 +652,15 @@ export function BlogPost(props: BlogPostProps): ReactNode {
386
652
  */}
387
653
  <div data-website-blog-post-meta>
388
654
  <time dateTime={frontmatter.publishedAt}>
389
- {frontmatter.publishedAt}
655
+ {formatWebsitePublicationDate(frontmatter.publishedAt, locale)}
390
656
  </time>
391
657
  {' · '}
392
- <address data-website-blog-post-author>
393
- {frontmatter.authorRef as unknown as string}
394
- </address>
658
+ <address data-website-blog-post-author>{authorName}</address>
395
659
  </div>
396
660
  {frontmatter.tags.length > 0 ? (
397
661
  <ul data-website-blog-post-tags>
398
662
  {frontmatter.tags.map((tag) => (
399
- <li key={tag as unknown as string}>
400
- {tag as unknown as string}
401
- </li>
663
+ <BlogPostTag key={tag} tag={tag} />
402
664
  ))}
403
665
  </ul>
404
666
  ) : null}
@@ -535,7 +797,7 @@ WebsiteMdxProvider.displayName = 'WebsiteMdxProvider';
535
797
 
536
798
  ## `buildBlogPostCollectionConfig` + `parseBlogPostFrontmatter`
537
799
 
538
- The Path-Z bridge between Astro's bundled Zod 3 (in `astro:content`)
800
+ The bridge between Astro's bundled Zod 3 (in `astro:content`)
539
801
  and the engine's canonical Zod 4 schema. The collection layer
540
802
  accepts any frontmatter (passthrough); the strict validation runs
541
803
  synchronously at render time inside `<BlogPost>` (and at build time
@@ -552,7 +814,7 @@ schema, no double source of truth).
552
814
 
553
815
  ```typescript
554
816
  *
555
- * Astro content-collection bridge for blog posts (Phase 7 D-3 = Path Z).
817
+ * Astro content-collection bridge for blog posts.
556
818
  *
557
819
  * # The Zod-version bridge problem
558
820
  *
@@ -562,21 +824,21 @@ schema, no double source of truth).
562
824
  * a schema instance directly across the version boundary, and shimming
563
825
  * a Zod 4 schema down to a Zod 3 schema would create either:
564
826
  *
565
- * - a hand-mirrored copy (Path X) — maintained in `src/content/config.ts`
827
+ * - a hand-mirrored copy — maintained in `src/content.config.ts`
566
828
  * using Astro's `z`, with silent-drift risk every time a field is
567
829
  * added/removed/refined; or
568
- * - a runtime bridge package (Path C) — a non-trivial maintenance
830
+ * - a runtime bridge package — a non-trivial maintenance
569
831
  * surface for a marginal gain.
570
832
  *
571
- * Path Z (this file) sidesteps the bridge entirely: the consumer's
572
- * `src/content/config.ts` declares a `passthrough` collection schema
833
+ * This file sidesteps the bridge entirely: the consumer's
834
+ * `src/content.config.ts` declares a `passthrough` collection schema
573
835
  * that lets Astro accept any frontmatter shape; the engine then
574
836
  * validates with the canonical Zod 4 schema at render time inside
575
837
  * `<BlogPost>`. Astro's static site generator runs the page render
576
838
  * during the build, so a malformed frontmatter still surfaces as a
577
839
  * BUILD-TIME error (the `.parse()` call throws synchronously and Astro
578
- * reports it with the page URL) — the only practical difference vs.
579
- * Path X is the error-message stack location.
840
+ * reports it with the page URL) — the only practical difference from a
841
+ * hand-mirrored schema is the error-message stack location.
580
842
  *
581
843
  * # Why the engine ships an opaque shape (rather than the consumer
582
844
  * importing the Astro `z` directly)
@@ -588,29 +850,39 @@ schema, no double source of truth).
588
850
  * the wiring in the engine means the framework absorbs the upgrade
589
851
  * cost in ONE place when Astro bumps a major.
590
852
  *
591
- * The shape returned here is `{ schema: <passthrough record> }`. The
592
- * consumer spreads it into their `defineCollection` call:
853
+ * The shape returned here is `{ loader, schema }`. The consumer spreads it
854
+ * into their `defineCollection` call, in `website/src/content.config.ts`
855
+ * (the file Astro 5+ reads; `src/content/config.ts` is the legacy path):
593
856
  *
594
857
  * ```ts
595
- * // examples/<app>/website/src/content/config.ts
858
+ * // website/src/content.config.ts
596
859
  * import { defineCollection, z } from 'astro:content';
860
+ * import { glob } from 'astro/loaders';
597
861
  * import { buildBlogPostCollectionConfig } from '@wildo-ai/saas-website/mdx';
598
862
  *
599
863
  * export const collections = {
600
- * blog: defineCollection({
601
- * type: 'content',
602
- * ...buildBlogPostCollectionConfig({ astroZ: z }),
603
- * }),
864
+ * blog: defineCollection({ ...buildBlogPostCollectionConfig({ astroZ: z, glob }) }),
604
865
  * };
605
866
  * ```
606
867
  *
607
- * The consumer passes Astro's own `z` in (because the engine cannot
608
- * import `astro:content` — that virtual module only exists inside
609
- * the Astro build context, never at the engine package's compile
610
- * time, and importing it would also pull `astro` into the engine's
611
- * walked closure which the bundle-isolation test forbids). The engine
612
- * builds a passthrough `z.object({}).passthrough()` from the supplied
613
- * factory and returns the schema slot.
868
+ * The consumer passes Astro's own `z` and `glob` in, because the engine
869
+ * cannot import `astro:content` (a virtual module that only exists inside
870
+ * the Astro build) nor `astro/loaders` (it would pull `astro` into the
871
+ * engine's walked closure, which the bundle-isolation test forbids). The
872
+ * engine builds the passthrough schema and the loader from them.
873
+ *
874
+ * **The upgrade this exists for happened (#2570).** The recipe used to be a
875
+ * legacy `type: 'content'` collection, and Astro 6 REMOVED legacy
876
+ * collections: the collection loaded empty, `getStaticPaths` emitted no post,
877
+ * and every post answered 404 while `astro check` and `wildo website audit`
878
+ * both passed. The loader is now the engine's, so the next Astro change lands
879
+ * here, once.
880
+ *
881
+ * **The entry id is the post's PATH, `<locale>/<file>`** (`blogPostEntryId`).
882
+ * Astro's default id is the frontmatter `slug` when present, and a post's
883
+ * translations share their slug by design (that is how the language switcher
884
+ * finds them), so the default made one locale's post silently overwrite the
885
+ * other's ("Later items with the same id will overwrite earlier ones").
614
886
  *
615
887
  * # `parseBlogPostFrontmatter`
616
888
  *
@@ -643,18 +915,41 @@ export interface AstroZodFactoryShape {
643
915
  };
644
916
  }
645
917
 
918
+ /**
919
+ * Minimal contract for Astro's `glob` loader factory (`import { glob } from 'astro/loaders'`), typed structurally for
920
+ * the reason `AstroZodFactoryShape` is.
921
+ */
922
+ export type AstroGlobLoaderFactoryShape = (options: {
923
+ readonly pattern: string;
924
+ readonly base: string;
925
+ readonly generateId: (options: { readonly entry: string; readonly data: Record<string, unknown> }) => string;
926
+ }) => unknown;
927
+
928
+ /**
929
+ * A post's collection id: its path under the blog folder without the extension, `en/launching-early-access`. Unique
930
+ * by construction (one file per path), where the frontmatter `slug` Astro would use by default is shared by a post's
931
+ * translations.
932
+ */
933
+ export function blogPostEntryId(entry: string): string {
934
+ return entry.replace(/\.mdx$/u, '');
935
+ }
936
+
646
937
  export interface BuildBlogPostCollectionConfigOptions {
647
938
  /**
648
939
  * Astro's bundled `z` object — pass `import { z } from 'astro:content'`
649
- * from the consumer-side `src/content/config.ts`. The engine cannot
940
+ * from the consumer-side `src/content.config.ts`. The engine cannot
650
941
  * import `astro:content` itself (virtual module, only present inside
651
942
  * the Astro build pipeline; would also bloat the bundle-isolation
652
943
  * walked closure with the `astro` runtime).
653
944
  */
654
945
  astroZ: AstroZodFactoryShape;
946
+ /** Astro's `glob` loader factory — pass `import { glob } from 'astro/loaders'`. */
947
+ glob: AstroGlobLoaderFactoryShape;
655
948
  }
656
949
 
657
950
  export interface BlogPostCollectionConfigShape {
951
+ /** The collection's loader: every post under `WEBSITE_BLOG_CONTENT_BASE`, each with its path as its id. */
952
+ loader: unknown;
658
953
  /**
659
954
  * The schema slot consumed by Astro's `defineCollection({...})`.
660
955
  * A `passthrough` record (no field constraints at this layer) so
@@ -668,12 +963,31 @@ export interface BlogPostCollectionConfigShape {
668
963
  export function buildBlogPostCollectionConfig(
669
964
  opts: BuildBlogPostCollectionConfigOptions,
670
965
  ): BlogPostCollectionConfigShape {
671
- const { astroZ } = opts;
966
+ const { astroZ, glob } = opts;
672
967
  return {
968
+ loader: glob({ pattern: WEBSITE_BLOG_CONTENT_PATTERN, base: WEBSITE_BLOG_CONTENT_BASE, generateId: ({ entry }) => blogPostEntryId(entry) }),
673
969
  schema: astroZ.object({}).passthrough(),
674
970
  };
675
971
  }
676
972
 
973
+ /**
974
+ * A frontmatter whose YAML timestamps arrived as `Date`s, with each one back as the ISO-8601 string its author wrote.
975
+ *
976
+ * Astro's content layer parses frontmatter with YAML 1.1 timestamps, so an unquoted `publishedAt:
977
+ * 2026-04-15T09:00:00.000Z` reaches the page as a `Date` (measured on Astro 6.1.8, #2570), where the legacy collection
978
+ * delivered the string. Both are the same instant, so a top-level `Date` is turned back into its ISO string before the
979
+ * strict schema, whose datetime fields are strings. Nothing else changes: an invalid value still fails, and a value
980
+ * that is not a `Date` is left exactly as it came.
981
+ */
982
+ function withYamlTimestampsAsIsoStrings(raw: unknown): unknown {
983
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return raw;
984
+ const entries = Object.entries(raw as Record<string, unknown>);
985
+ if (!entries.some(([, value]) => value instanceof Date)) return raw;
986
+ return Object.fromEntries(
987
+ entries.map(([key, value]) => [key, value instanceof Date && !Number.isNaN(value.getTime()) ? value.toISOString() : value]),
988
+ );
989
+ }
990
+
677
991
  /**
678
992
  * Strict Zod-4 validator for blog-post frontmatter. Called at the top
679
993
  * of `<BlogPost>` rendering against `entry.data` (whatever Astro's
@@ -701,7 +1015,7 @@ export function parseBlogPostFrontmatter(
701
1015
  raw: unknown,
702
1016
  ctx: ParseBlogPostFrontmatterContext = {},
703
1017
  ): BlogPostFrontmatter {
704
- const result = BlogPostFrontmatterSchema.safeParse(raw);
1018
+ const result = BlogPostFrontmatterSchema.safeParse(withYamlTimestampsAsIsoStrings(raw));
705
1019
  if (result.success) {
706
1020
  return result.data;
707
1021
  }
@@ -721,13 +1035,20 @@ export function parseBlogPostFrontmatter(
721
1035
  }
722
1036
  ```
723
1037
 
724
- ## `renderBlogPostHeadHtml` — per-post `<head>` renderer
1038
+ ## `renderBlogPostHeadHtml` and `buildBlogPostStructuredDataPayload` — per-post `<head>` and JSON-LD
725
1039
 
726
1040
  Sibling of `renderWebsitePageHeadHtml`, but reads its title /
727
1041
  description / OG image / `article:*` metadata from the validated
728
1042
  `BlogPostFrontmatter` instead of the page manifest's
729
1043
  `metaLabelKeys`. Emits `og:type=article` + the `article:published_time`
730
- / `article:author` / `article:tag` (one per tag) block.
1044
+ / `article:author` / `article:tag` (one per tag) block, and the post's
1045
+ `BlogPosting` JSON-LD. Both functions (from `@wildo-ai/saas-website/astro`)
1046
+ REQUIRE `words` — the post's author and tags as words, from
1047
+ `resolveWebsiteBlogPostWords({ authorRef, tags, vocabulary, labelPack })` —
1048
+ because what they publish is indexed by search engines and must never carry
1049
+ a ref. `buildBlogPostStructuredDataPayload` is what a site's
1050
+ `structured-data/page-payloads.ts` calls so `wildo website audit` sees each
1051
+ post's payload.
731
1052
 
732
1053
  ## Import Origins
733
1054
 
@@ -834,7 +1155,12 @@ export interface RenderBlogPostHeadHtmlOptions {
834
1155
  */
835
1156
  frontmatter: BlogPostFrontmatter;
836
1157
  /**
837
- * AI-training opt-out (D-AG3) — when `true`, the renderer emits
1158
+ * The post's author and tags as words — from `resolveWebsiteBlogPostWords` with the page's label pack. Published as
1159
+ * `article:author` / `article:tag` and in the JSON-LD; never the frontmatter's refs.
1160
+ */
1161
+ words: WebsiteBlogPostWords;
1162
+ /**
1163
+ * AI-training opt-out — when `true`, the renderer emits
838
1164
  * `<meta name="robots" content="noai, noimageai">`. The sibling
839
1165
  * `_headers` entry is produced by `renderBlogPostNoaiHeaders()`
840
1166
  * (one knob, two channels — see the page-head renderer's
@@ -854,16 +1180,29 @@ export interface RenderBlogPostHeadHtmlOptions {
854
1180
 
855
1181
  export interface BuildBlogPostStructuredDataPayloadOptions {
856
1182
  frontmatter: BlogPostFrontmatter;
1183
+ /**
1184
+ * The post's author and tags as words, from `resolveWebsiteBlogPostWords`. Never the frontmatter's refs: they are
1185
+ * identifiers, and this payload is published to every search engine.
1186
+ */
1187
+ words: WebsiteBlogPostWords;
857
1188
  canonicalUrl: string;
858
1189
  siteOrigin: string;
859
1190
  siteName: string;
860
1191
  locale: AvailableLanguage;
861
1192
  }
862
1193
 
1194
+ /**
1195
+ * The cover as an absolute URL, for the surfaces that require one (`og:image`, the JSON-LD `image`): a site path
1196
+ * (`/blog/covers/x.png`) is resolved against the site's public origin, an absolute URL is kept.
1197
+ */
1198
+ export function resolveBlogPostCoverImageUrl(coverImageUrl: string, siteOrigin: string): string {
1199
+ return coverImageUrl.startsWith('/') ? `${siteOrigin.replace(/\/$/, '')}${coverImageUrl}` : coverImageUrl;
1200
+ }
1201
+
863
1202
  export function buildBlogPostStructuredDataPayload(
864
1203
  opts: BuildBlogPostStructuredDataPayloadOptions,
865
1204
  ): WebsiteStructuredDataPayload {
866
- const { frontmatter, canonicalUrl, siteOrigin, siteName, locale } = opts;
1205
+ const { frontmatter, words, canonicalUrl, siteOrigin, siteName, locale } = opts;
867
1206
  return {
868
1207
  '@type': 'BlogPosting',
869
1208
  '@id': `${canonicalUrl}#blog-post`,
@@ -871,8 +1210,8 @@ export function buildBlogPostStructuredDataPayload(
871
1210
  description: frontmatter.summary,
872
1211
  datePublished: frontmatter.publishedAt,
873
1212
  author: {
874
- '@type': 'Person',
875
- name: String(frontmatter.authorRef),
1213
+ '@type': words.author.kind,
1214
+ name: words.author.name,
876
1215
  },
877
1216
  publisher: {
878
1217
  '@type': 'Organization',
@@ -882,18 +1221,19 @@ export function buildBlogPostStructuredDataPayload(
882
1221
  mainEntityOfPage: canonicalUrl,
883
1222
  url: canonicalUrl,
884
1223
  inLanguage: String(locale),
885
- ...(frontmatter.coverImageUrl ? { image: frontmatter.coverImageUrl } : {}),
886
- ...(frontmatter.tags.length > 0 ? { keywords: frontmatter.tags.join(', ') } : {}),
1224
+ ...(frontmatter.coverImageUrl ? { image: resolveBlogPostCoverImageUrl(frontmatter.coverImageUrl, siteOrigin) } : {}),
1225
+ ...(words.tags.length > 0 ? { keywords: words.tags.join(', ') } : {}),
887
1226
  };
888
1227
  }
889
1228
 
890
1229
  export function renderBlogPostHeadHtml(opts: RenderBlogPostHeadHtmlOptions): string {
891
- const { siteContext, locale, routePath, frontmatter, noaiOptOut } = opts;
1230
+ const { siteContext, locale, routePath, frontmatter, words, noaiOptOut } = opts;
892
1231
  const { rootConfig, websiteConfig } = siteContext;
893
1232
 
894
1233
  const title = frontmatter.title;
895
1234
  const description = frontmatter.summary;
896
- const ogImageUrl = frontmatter.coverImageUrl;
1235
+ const ogImageUrl =
1236
+ frontmatter.coverImageUrl === undefined ? undefined : resolveBlogPostCoverImageUrl(frontmatter.coverImageUrl, websiteConfig.publicOrigin);
897
1237
  const titleAttr = escapeHtmlAttribute(title);
898
1238
  const descriptionAttr = escapeHtmlAttribute(description);
899
1239
  const titleText = escapeHtmlText(title);
@@ -955,26 +1295,24 @@ export function renderBlogPostHeadHtml(opts: RenderBlogPostHeadHtmlOptions): str
955
1295
  * vertical defines:
956
1296
  * - `article:published_time` (ISO-8601 — already validated by
957
1297
  * the frontmatter schema's `z.iso.datetime`).
958
- * - `article:author` (free text or URL — we emit the author
959
- * ref as a free-text string; a future author-registry
960
- * resolution would emit the author's profile URL instead).
1298
+ * - `article:author` (free text or URL — we emit the author's
1299
+ * name, the words its label holds; a future author profile
1300
+ * page would let it carry that page's URL instead).
961
1301
  * - `article:tag` (one tag per emission; the OG spec uses
962
1302
  * repeated `<meta property="article:tag">` lines, NOT a
963
1303
  * comma-joined list).
964
1304
  *
965
1305
  * `article:section` (the OG "section" field, e.g. "Engineering" /
966
- * "Product") is intentionally NOT emitted — Your Application has no
967
- * blog-section taxonomy yet, and emitting an empty section would
968
- * be worse than omission.
1306
+ * "Product") is intentionally NOT emitted — the frontmatter has no
1307
+ * blog-section field, and emitting an empty section would be worse
1308
+ * than omission.
969
1309
  */
970
1310
  const articleMetaLines: string[] = [
971
1311
  `<meta property="article:published_time" content="${escapeHtmlAttribute(frontmatter.publishedAt)}" />`,
972
- `<meta property="article:author" content="${escapeHtmlAttribute(frontmatter.authorRef as unknown as string)}" />`,
1312
+ `<meta property="article:author" content="${escapeHtmlAttribute(words.author.name)}" />`,
973
1313
  ];
974
- for (const tag of frontmatter.tags) {
975
- articleMetaLines.push(
976
- `<meta property="article:tag" content="${escapeHtmlAttribute(tag as unknown as string)}" />`,
977
- );
1314
+ for (const tag of words.tags) {
1315
+ articleMetaLines.push(`<meta property="article:tag" content="${escapeHtmlAttribute(tag)}" />`);
978
1316
  }
979
1317
 
980
1318
  const siteNameAttr = escapeHtmlAttribute(rootConfig.seo.siteName);
@@ -989,6 +1327,7 @@ export function renderBlogPostHeadHtml(opts: RenderBlogPostHeadHtmlOptions): str
989
1327
  pagePayloads: [
990
1328
  buildBlogPostStructuredDataPayload({
991
1329
  frontmatter,
1330
+ words,
992
1331
  canonicalUrl,
993
1332
  siteOrigin,
994
1333
  siteName: rootConfig.seo.siteName,
@@ -1022,8 +1361,10 @@ export function renderBlogPostHeadHtml(opts: RenderBlogPostHeadHtmlOptions): str
1022
1361
 
1023
1362
  ## `createWebsiteBlogPostBridgeIsland` — per-locale island factory
1024
1363
 
1025
- Phase 7 D-6 Option A — the structural fix for Astro's React-context
1026
- propagation gap. Returns a single React island per locale that
1364
+ Imported from `@wildo-ai/saas-website/mdx`; the `/astro-island` entry point deliberately does not export it.
1365
+ `BLOG_POST_PAGE_REF`, the page ref every post shares, is a plain constant exported from `@wildo-ai/saas-website`.
1366
+
1367
+ The structural fix for Astro's React-context propagation gap. Returns a single React island per locale that
1027
1368
  encapsulates the entire post tree (BlogPost + MDX body + embedded
1028
1369
  sections) inside ONE hydration boundary. Closes over the per-locale
1029
1370
  `slugToMdxBody` map (built from `import.meta.glob`) + the navigation
@@ -1044,7 +1385,7 @@ primitives as island props.
1044
1385
  * React island a consumer's per-locale `*.bridge.tsx` module exports for
1045
1386
  * mounting blog post pages. **Sibling** of `createWebsitePageBridgeIsland`
1046
1387
  * but adapted to the dynamic-routing constraint of the marketing-blog
1047
- * adapter (Phase 7, D-6 = Option A).
1388
+ * adapter.
1048
1389
  *
1049
1390
  * # Why blog posts cannot reuse the page bridge factory
1050
1391
  *
@@ -1056,10 +1397,10 @@ primitives as island props.
1056
1397
  * load time — the page bridge closes over it. A blog post's body
1057
1398
  * is the compiled MDX module, which varies per slug. Closing the
1058
1399
  * MDX body inside the factory at module load time would force one
1059
- * bridge file per post (defeats Q16=B "one MDX file per post").
1400
+ * bridge file per post, where the contract is one MDX file per post.
1060
1401
  * Instead, the factory closes over a `slugToMdxBody: Record<string,
1061
1402
  * ComponentType>` map — typically built from
1062
- * `import.meta.glob('./content/blog/<locale>/*.mdx', { eager: true })`
1403
+ * `import.meta.glob('../content/blog/<segment>/*.mdx', { eager: true, query: '?website-react-mdx' })` (the locale code lower-cased)
1063
1404
  * on the consumer side — and the island accepts the active `slug`
1064
1405
  * as a primitive (JSON-serializable) prop.
1065
1406
  *
@@ -1068,7 +1409,7 @@ primitives as island props.
1068
1409
  * `<BlogPost>` renderer ALREADY wraps its tree in
1069
1410
  * `<WebsitePageLayout pageRef={BLOG_POST_PAGE_REF}>` (the framework
1070
1411
  * reserves the page ref for the entire blog surface — see
1071
- * `BLOG_POST_PAGE_REF` JSDoc in `BlogPost.tsx`). Reusing the page
1412
+ * `BLOG_POST_PAGE_REF`'s JSDoc, exported from `@wildo-ai/saas-website`). Reusing the page
1072
1413
  * bridge would double-wrap the layout. This factory instead
1073
1414
  * provides the runtime context and yields directly to `<BlogPost>`,
1074
1415
  * which owns the layout boundary itself.
@@ -1114,9 +1455,9 @@ primitives as island props.
1114
1455
  *
1115
1456
  * `import.meta.glob({ eager: true })` materializes EVERY post's
1116
1457
  * compiled JS into the per-locale React-island bundle (~5–20 KB per
1117
- * post depending on length and embedded section count). For the
1118
- * Phase 7 dogfood (≤10 posts) this is fine and matches the documented
1119
- * Astro+MDX pattern. Past ~50 posts this becomes a real budget concern.
1458
+ * post depending on length and embedded section count). For a blog of
1459
+ * ten or so posts this is fine and matches the documented Astro+MDX
1460
+ * pattern. Past ~50 posts this becomes a real budget concern.
1120
1461
  * The factory's API is forward-compatible with `{ eager: false }`
1121
1462
  * (lazy loaders): swap the consumer's glob to lazy mode and the
1122
1463
  * `slugToMdxBody[slug]` lookup returns a `() => Promise<{ default:
@@ -1129,37 +1470,35 @@ primitives as island props.
1129
1470
  * **Per-locale bridge file** (consumer side, ONE per locale):
1130
1471
  *
1131
1472
  * ```tsx
1132
- * // examples/<app>/website/src/pages-impl/blog-post-en.bridge.tsx
1473
+ * // website/src/pages-impl/blog-post-en.bridge.tsx
1133
1474
  * import type { ComponentType } from 'react';
1134
1475
  *
1135
- * import { createWebsiteBlogPostBridgeIsland }
1136
- * from '@wildo-ai/saas-website/mdx';
1137
- * import { BLOG_POST_MDX_COMPONENTS }
1138
- * from './blog-post.mdx-components';
1139
- * import { WEBSITE_ROOT_CONFIG } from '../website-root.config';
1140
- *
1141
- * // Static analyzable glob — Vite resolves at build time. The glob
1142
- * // pattern MUST be a single string literal (no concatenation, no
1143
- * // variable interpolation); Vite parses it AST-side. The `as` cast
1144
- * // narrows the unknown record to the per-MDX-file shape Astro's mdx
1145
- * // integration emits (default export = the compiled React component).
1146
- * const rawModules = import.meta.glob('./content/blog/en/*.mdx', {
1476
+ * import { createWebsiteBlogPostBridgeIsland } from '@wildo-ai/saas-website/mdx';
1477
+ *
1478
+ * import { generatedFrontendProviderModules } from '../generated/frontend-providers.generated';
1479
+ * import { FooterComponent } from '../components/FooterComponent';
1480
+ * import { HeaderComponent } from '../components/HeaderComponent';
1481
+ * import { BLOG_POST_MDX_COMPONENTS } from './blog-post.mdx-components';
1482
+ *
1483
+ * // A static glob — Vite resolves it at build time, so the pattern and every option are literals. The query makes
1484
+ * // `websiteBlogReactMdx()` (astro.config) compile these posts for React, so the body renders inside the island.
1485
+ * const rawModules = import.meta.glob('../content/blog/en/*.mdx', {
1147
1486
  * eager: true,
1148
- * }) as Record<string, { default: ComponentType }>;
1487
+ * query: '?website-react-mdx',
1488
+ * }) as Record<string, { default: ComponentType<unknown> }>;
1149
1489
  *
1150
- * const slugToMdxBody: Record<string, ComponentType> = {};
1490
+ * const slugToMdxBody: Record<string, ComponentType<unknown>> = {};
1151
1491
  * for (const [path, mod] of Object.entries(rawModules)) {
1152
- * // './content/blog/en/why-context.mdx' -> 'why-context'
1153
- * const slug = path.split('/').pop()!.replace(/\.mdx$/, '');
1154
- * slugToMdxBody[slug] = mod.default;
1492
+ * // '../content/blog/en/why-context.mdx' -> 'why-context'
1493
+ * slugToMdxBody[path.split('/').pop()!.replace(/\.mdx$/, '')] = mod.default;
1155
1494
  * }
1156
1495
  *
1157
- * export const BlogPostEnBridgeIsland =
1158
- * createWebsiteBlogPostBridgeIsland({
1159
- * slugToMdxBody,
1160
- * navigation: WEBSITE_ROOT_CONFIG.navigation,
1161
- * mdxComponents: BLOG_POST_MDX_COMPONENTS,
1162
- * });
1496
+ * export const BlogPostEnBridgeIsland = createWebsiteBlogPostBridgeIsland({
1497
+ * frontendProviderModules: generatedFrontendProviderModules,
1498
+ * slugToMdxBody,
1499
+ * navigation: { headerComponent: HeaderComponent, footerComponent: FooterComponent },
1500
+ * mdxComponents: BLOG_POST_MDX_COMPONENTS,
1501
+ * });
1163
1502
  * ```
1164
1503
  *
1165
1504
  * **Per-locale `[slug].astro` shell** (consumer side):
@@ -1171,37 +1510,54 @@ primitives as island props.
1171
1510
  * loadWebsitePageRuntime,
1172
1511
  * renderBlogPostHeadHtml,
1173
1512
  * renderWebsiteDesignTokensCss,
1513
+ * resolveWebsiteBlogPostCover,
1174
1514
  * } from '@wildo-ai/saas-website/astro';
1515
+ * import { resolveWebsiteBlogPostWords } from '@wildo-ai/saas-website';
1175
1516
  * import { parseBlogPostFrontmatter } from '@wildo-ai/saas-website/mdx';
1176
1517
  * import { BlogPostEnBridgeIsland } from '@/pages-impl/blog-post-en.bridge';
1177
1518
  * import { BLOG_POST_PAGE_MANIFEST } from '@/pages-impl/blog-post.page';
1519
+ * import { BLOG_VOCABULARY } from '@/blog-vocabulary';
1178
1520
  * import { WEBSITE_SITE_CONTEXT } from '@/website-site-context';
1179
1521
  *
1180
1522
  * export async function getStaticPaths() {
1181
1523
  * const posts = await getCollection('blog');
1182
1524
  * const defaultLocale = WEBSITE_SITE_CONTEXT.websiteConfig.defaultLocale;
1183
- * return posts
1184
- * .filter((p) => p.data.locale === defaultLocale)
1185
- * .map((p) => ({ params: { slug: p.data.slug }, props: { entry: p } }));
1525
+ * // The collection is `passthrough`, so `post.data` is untyped: parse it to read the locale and slug.
1526
+ * const parsed = posts.map((post) => ({ post, frontmatter: parseBlogPostFrontmatter(post.data, { source: post.id }) }));
1527
+ * return parsed
1528
+ * .filter(({ frontmatter }) => frontmatter.locale === defaultLocale)
1529
+ * .map(({ post, frontmatter }) => ({
1530
+ * params: { slug: frontmatter.slug as string },
1531
+ * // The locales this post is translated into, so the switcher sends the others home rather than to a 404.
1532
+ * props: { entry: post, pageLocales: parsed.filter((o) => o.frontmatter.slug === frontmatter.slug).map((o) => o.frontmatter.locale) },
1533
+ * }));
1186
1534
  * }
1187
- * const { entry } = Astro.props;
1535
+ * const { entry, pageLocales } = Astro.props;
1188
1536
  *
1189
1537
  * const runtime = loadWebsitePageRuntime({
1190
1538
  * manifest: BLOG_POST_PAGE_MANIFEST,
1191
1539
  * siteContext: WEBSITE_SITE_CONTEXT,
1192
1540
  * labelPacksDir: './src/i18n',
1193
1541
  * astroLocale: Astro.currentLocale,
1542
+ * routeParams: Astro.params,
1194
1543
  * });
1195
1544
  * const frontmatter = parseBlogPostFrontmatter(entry.data, { source: entry.id });
1545
+ * // The cover with its size: measured from public/ for a site path, from the frontmatter for a remote image.
1546
+ * const cover = await resolveWebsiteBlogPostCover(frontmatter);
1196
1547
  * const headHtml = renderBlogPostHeadHtml({
1197
1548
  * siteContext: WEBSITE_SITE_CONTEXT,
1198
1549
  * locale: runtime.locale,
1199
1550
  * routePath: `/blog/${frontmatter.slug}`,
1200
1551
  * frontmatter,
1552
+ * // The author and tags as words, never their refs: they are published as article metadata and JSON-LD.
1553
+ * words: resolveWebsiteBlogPostWords({
1554
+ * authorRef: frontmatter.authorRef,
1555
+ * tags: frontmatter.tags,
1556
+ * vocabulary: BLOG_VOCABULARY,
1557
+ * labelPack: runtime.labelPack,
1558
+ * }),
1201
1559
  * });
1202
- * const designTokensCss = renderWebsiteDesignTokensCss(
1203
- * WEBSITE_SITE_CONTEXT.rootConfig.designTokens,
1204
- * );
1560
+ * const designTokensCss = renderWebsiteDesignTokensCss(WEBSITE_SITE_CONTEXT.rootConfig.designTokens);
1205
1561
  * ---
1206
1562
  * <!doctype html>
1207
1563
  * <html lang={runtime.locale}>
@@ -1216,14 +1572,18 @@ primitives as island props.
1216
1572
  * client:load
1217
1573
  * slug={frontmatter.slug}
1218
1574
  * rawFrontmatter={entry.data}
1575
+ * cover={cover}
1219
1576
  * source={entry.id}
1220
1577
  * locale={runtime.locale}
1221
1578
  * defaultLocale={runtime.defaultLocale}
1579
+ * locales={WEBSITE_SITE_CONTEXT.websiteConfig.locales.map((entry) => entry.locale)}
1580
+ * pageLocales={pageLocales}
1581
+ * routePath={`/blog/${frontmatter.slug}`}
1582
+ * appOrigin={WEBSITE_SITE_CONTEXT.websiteConfig.appOrigin}
1222
1583
  * labelPack={runtime.labelPack}
1223
1584
  * designTokens={WEBSITE_SITE_CONTEXT.rootConfig.designTokens}
1224
- * skipToMainContentLabelKey={
1225
- * WEBSITE_SITE_CONTEXT.rootConfig.skipToMainContentLabelKey
1226
- * }
1585
+ * skipToMainContentLabelKey={WEBSITE_SITE_CONTEXT.rootConfig.skipToMainContentLabelKey}
1586
+ * frontendProviders={WEBSITE_SITE_CONTEXT.frontendProviders}
1227
1587
  * />
1228
1588
  * </body>
1229
1589
  * </html>
@@ -1260,10 +1620,13 @@ export interface CreateWebsiteBlogPostBridgeIslandDeps {
1260
1620
  /**
1261
1621
  * Per-slug map of compiled MDX bodies (each entry is a React
1262
1622
  * component — the `.default` export of the MDX module). Typically
1263
- * built from `import.meta.glob('./content/blog/<locale>/*.mdx',
1264
- * { eager: true })` with the path-key normalized to the slug. Closed
1623
+ * built from `import.meta.glob('../content/blog/<segment>/*.mdx',
1624
+ * { eager: true, query: '?website-react-mdx' })` with the path-key
1625
+ * normalized to the slug. The query is what makes
1626
+ * `websiteBlogReactMdx()` compile the post for React; without it the
1627
+ * body is Astro's compilation and renders nothing in the island. Closed
1265
1628
  * over at module-load time so the entire MDX body graph for the
1266
- * locale lands inside ONE React island bundle (D-6 Option A) — this
1629
+ * locale lands inside ONE React island bundle — this
1267
1630
  * is the structural fix for Astro's React-children context-propagation
1268
1631
  * gap (see file preamble).
1269
1632
  *
@@ -1327,6 +1690,12 @@ export interface WebsiteBlogPostBridgeIslandProps {
1327
1690
  * by the renderer).
1328
1691
  */
1329
1692
  rawFrontmatter: unknown;
1693
+ /**
1694
+ * The post's cover with its size, from `resolveWebsiteBlogPostCover(frontmatter)` in the route's `.astro`
1695
+ * frontmatter (it reads the site's `public/`, which an island cannot). Forwarded to `<BlogPost>`, which requires it
1696
+ * exactly when the frontmatter names a cover. A plain `{ src, width, height }`, so it crosses the hydration boundary.
1697
+ */
1698
+ cover?: WebsiteBlogPostCover;
1330
1699
  /**
1331
1700
  * Diagnostic source identifier echoed into validation errors —
1332
1701
  * typically `entry.id` from Astro's content collection. Optional
@@ -1341,6 +1710,20 @@ export interface WebsiteBlogPostBridgeIslandProps {
1341
1710
  * island prop).
1342
1711
  */
1343
1712
  defaultLocale: AvailableLanguage;
1713
+ /** Every locale the site publishes, for the header's locale switcher (see the page bridge's `locales`). */
1714
+ locales?: readonly AvailableLanguage[];
1715
+ /**
1716
+ * The locales THIS post exists in — those whose collection holds a post with the same slug. The switcher links
1717
+ * a language the post is not translated into to that language's home rather than to a 404. Absent means every
1718
+ * locale (`WebsiteRuntimeContextValue.pageLocales`).
1719
+ */
1720
+ pageLocales?: readonly AvailableLanguage[];
1721
+ /**
1722
+ * The post's own route, `/blog/<slug>` — the `routePath` the shell already computes for the page runtime. Forwarded
1723
+ * to the page context so the server-rendered header knows the current page: without it the switcher's links point
1724
+ * at each locale's home until the island hydrates.
1725
+ */
1726
+ routePath?: string;
1344
1727
  /** Already-loaded + already-shape-validated label pack. */
1345
1728
  labelPack: LabelPack;
1346
1729
  /** Design-token bundle from `WebsiteRootConfig.designTokens`. */
@@ -1359,6 +1742,8 @@ export interface WebsiteBlogPostBridgeIslandProps {
1359
1742
  appOrigin?: string;
1360
1743
  /** Whether the operator owes a legal notice, from `WEBSITE_SITE_CONTEXT.legalNoticeOwed`, as on ordinary page bridges (#2588). */
1361
1744
  legalNoticeOwed?: boolean;
1745
+ /** The public documents the application serves, from `WEBSITE_SITE_CONTEXT.servedPublicDocumentRefs`, as on ordinary page bridges (#2987). */
1746
+ servedPublicDocumentRefs?: readonly WebsitePublicDocumentRef[];
1362
1747
  }
1363
1748
 
1364
1749
  const EMPTY_MDX_COMPONENTS: WebsiteMdxComponentsMap = Object.freeze({});
@@ -1382,15 +1767,20 @@ export function createWebsiteBlogPostBridgeIsland(
1382
1767
  function WebsiteBlogPostBridgeIsland({
1383
1768
  slug,
1384
1769
  rawFrontmatter,
1770
+ cover,
1385
1771
  source,
1386
1772
  locale,
1387
1773
  defaultLocale,
1774
+ locales,
1775
+ pageLocales,
1776
+ routePath,
1388
1777
  labelPack,
1389
1778
  designTokens,
1390
1779
  skipToMainContentLabelKey,
1391
1780
  frontendProviders,
1392
1781
  appOrigin,
1393
1782
  legalNoticeOwed,
1783
+ servedPublicDocumentRefs,
1394
1784
  }: WebsiteBlogPostBridgeIslandProps): ReactNode {
1395
1785
  const MdxBody = slugToMdxBody[slug];
1396
1786
  if (MdxBody === undefined) {
@@ -1410,7 +1800,7 @@ export function createWebsiteBlogPostBridgeIsland(
1410
1800
  throw new Error(
1411
1801
  `[blog-post-bridge] No MDX body registered for slug="${slug}". ` +
1412
1802
  `The bridge factory's slugToMdxBody map only knows: ${known}. ` +
1413
- `Verify the consumer's import.meta.glob('...content/blog/<locale>/*.mdx') ` +
1803
+ `Verify the consumer's import.meta.glob('...content/blog/<segment>/*.mdx', the locale code lower-cased) ` +
1414
1804
  `pattern matches the source file naming.`,
1415
1805
  );
1416
1806
  }
@@ -1425,12 +1815,15 @@ export function createWebsiteBlogPostBridgeIsland(
1425
1815
  const runtimeValue: WebsiteRuntimeContextValue = {
1426
1816
  locale,
1427
1817
  defaultLocale,
1818
+ ...(locales !== undefined ? { locales } : {}),
1819
+ ...(pageLocales !== undefined ? { pageLocales } : {}),
1428
1820
  labelPack,
1429
1821
  designTokens,
1430
1822
  navigation,
1431
1823
  skipToMainContentLabelKey,
1432
1824
  appOrigin,
1433
1825
  ...(legalNoticeOwed !== undefined ? { legalNoticeOwed } : {}),
1826
+ ...(servedPublicDocumentRefs !== undefined ? { servedPublicDocumentRefs } : {}),
1434
1827
  ...(deps.consentBannerComponent !== undefined ? { consentBannerComponent: deps.consentBannerComponent } : {}),
1435
1828
  frontendProviderRegistry,
1436
1829
  providerComponentRegistry,
@@ -1439,8 +1832,10 @@ export function createWebsiteBlogPostBridgeIsland(
1439
1832
  <WebsiteRuntimeContextProvider value={runtimeValue}>
1440
1833
  <BlogPost
1441
1834
  rawFrontmatter={rawFrontmatter}
1835
+ {...(cover !== undefined ? { cover } : {})}
1442
1836
  source={source}
1443
1837
  mdxComponents={mdxComponents}
1838
+ {...(routePath !== undefined ? { routePath } : {})}
1444
1839
  >
1445
1840
  <MdxBody />
1446
1841
  </BlogPost>
@@ -1451,13 +1846,490 @@ export function createWebsiteBlogPostBridgeIsland(
1451
1846
 
1452
1847
  return WebsiteBlogPostBridgeIsland;
1453
1848
  }
1849
+ ```
1850
+
1851
+ ## `websiteBlogReactMdx()` — post bodies compiled for the React island
1852
+
1853
+ ## Import Origins
1854
+
1855
+ - `@wildo-ai/saas-website`
1856
+
1857
+ ## Source Excerpts
1858
+
1859
+ ### Origin Package: `@wildo-ai/saas-website`
1860
+
1861
+ ```typescript
1862
+ *
1863
+ * `websiteBlogReactMdx()` — the Astro integration that compiles a blog post's body for the React island
1864
+ * that renders it (#2572).
1865
+ *
1866
+ * A post page is ONE React island (the blog bridge), and the body is a React component inside it, so the
1867
+ * body's embedded sections can read the site's labels, tokens and links from the island's context.
1868
+ * `@astrojs/mdx` cannot produce that component: it compiles every `.mdx` module to ASTRO JSX
1869
+ * (`jsxImportSource: "astro"`), which React refuses ("Objects are not valid as a React child"), and it
1870
+ * sets no provider, so the components `BlogPost` hands to `MDXProvider` are never consulted.
1871
+ *
1872
+ * So the bridges import their posts with a query — `import.meta.glob('…/*.mdx', { eager: true, query:
1873
+ * '?website-react-mdx' })`, a literal because Vite takes no other kind there — and this integration compiles exactly those ids with React settings:
1874
+ * `jsxImportSource: 'react'` and `providerImportSource: '@mdx-js/react'`, MDX's own documented React
1875
+ * setup. `@astrojs/mdx` keeps compiling the plain `.mdx` ids (its filter is `/\.mdx$/`, which a
1876
+ * query-suffixed id does not match), so the content collection, its frontmatter and `render()` are
1877
+ * untouched.
1878
+ *
1879
+ * The compiler is the one `@astrojs/mdx` already ships (`@mdx-js/mdx`), resolved from the site's own
1880
+ * `@astrojs/mdx` so the site takes no second MDX dependency to keep in step, with the two remark plugins
1881
+ * `@astrojs/mdx` applies by default: `remark-gfm` (tables, task lists, autolinks) and `remark-smartypants`
1882
+ * (typographic quotes). Nothing else from the site's Markdown setup reaches a post's island body: the site's
1883
+ * own remark and rehype plugins, and Astro's rehype defaults (Shiki code highlighting, heading ids), do not
1884
+ * apply. Style code blocks and link headings in the post's components rather than relying on them.
1885
+ *
1886
+ * Add it beside `mdx()` and `react()`:
1887
+ *
1888
+ * @example
1889
+ * // astro.config.ts
1890
+ * integrations: [mdx(), websiteBlogReactMdx(), react()],
1891
+ *
1892
+ * // a blog bridge (`WEBSITE_REACT_MDX_QUERY`, written as the literal Vite requires)
1893
+ * const rawModules = import.meta.glob('../content/blog/en/*.mdx', { eager: true, query: '?website-react-mdx' });
1894
+ */
1895
+
1896
+ /** The query without its `?`, as it appears in a module id after the path. */
1897
+ const QUERY_NAME = WEBSITE_REACT_MDX_QUERY.slice(1);
1898
+
1899
+ /** The Vite plugin the integration registers: the subset of Vite's `Plugin` it fills in. */
1900
+ export interface WebsiteBlogReactMdxVitePlugin {
1901
+ readonly name: string;
1902
+ readonly enforce: 'pre';
1903
+ transform(code: string, id: string): Promise<{ code: string; map: null } | null>;
1904
+ }
1454
1905
 
1455
1906
  /**
1456
- * Re-export of the framework-reserved blog-post page ref. Consumers
1457
- * authoring `BLOG_POST_PAGE_MANIFEST` need this constant to satisfy
1458
- * the manifest's `ref` field; re-exporting it from the bridge module
1459
- * means the consumer's per-locale bridge file can grab both symbols
1460
- * from the one `@wildo-ai/saas-website/mdx` import it already has.
1907
+ * The subset of an Astro integration this one uses: structural, so the engine takes no type dependency on Astro, and
1908
+ * exact enough that it is assignable to Astro's `AstroIntegration` (its `updateConfig` takes a deep-partial config,
1909
+ * whose `vite.plugins` accepts this plugin shape).
1461
1910
  */
1462
- export { BLOG_POST_PAGE_REF };
1911
+ export interface WebsiteBlogReactMdxIntegration {
1912
+ readonly name: string;
1913
+ readonly hooks: {
1914
+ readonly 'astro:config:setup': (options: {
1915
+ readonly config: { readonly root: URL };
1916
+ readonly updateConfig: (config: {
1917
+ vite: { plugins: WebsiteBlogReactMdxVitePlugin[]; optimizeDeps: { include: string[] } };
1918
+ }) => unknown;
1919
+ }) => void;
1920
+ };
1921
+ }
1922
+
1923
+ /** What the compiler module exports that this integration calls. */
1924
+ interface MdxCompilerModule {
1925
+ compile(
1926
+ source: string,
1927
+ options: {
1928
+ jsxImportSource: string;
1929
+ providerImportSource: string;
1930
+ format: 'mdx';
1931
+ development: boolean;
1932
+ remarkPlugins: unknown[];
1933
+ },
1934
+ ): Promise<{ toString(): string }>;
1935
+ }
1936
+
1937
+ /** A module's default export, or the module itself when it has none (CommonJS interop). */
1938
+ function defaultExport(module: unknown): unknown {
1939
+ return typeof module === 'object' && module !== null && 'default' in module ? (module as { default: unknown }).default : module;
1940
+ }
1941
+
1942
+ /**
1943
+ * The MDX compiler and the two Markdown plugins Astro's own MDX compile uses, resolved through the site's
1944
+ * `@astrojs/mdx`. Refuses with the remedy when the site has no `@astrojs/mdx`: a blog needs it anyway, for
1945
+ * its content collection.
1946
+ */
1947
+ async function loadCompiler(siteRoot: URL): Promise<{ compiler: MdxCompilerModule; remarkPlugins: unknown[] }> {
1948
+ const fromSite = createRequire(new URL('package.json', siteRoot));
1949
+ let astroMdxManifest: string;
1950
+ try {
1951
+ astroMdxManifest = fromSite.resolve('@astrojs/mdx/package.json');
1952
+ } catch {
1953
+ throw new Error(
1954
+ `[saas-website] websiteBlogReactMdx() needs @astrojs/mdx, resolved from ${fileURLToPath(siteRoot)}. `
1955
+ + 'Install it in the website package and add mdx() to its integrations: the blog content collection needs it too.',
1956
+ );
1957
+ }
1958
+ const fromAstroMdx = createRequire(astroMdxManifest);
1959
+ const importFromAstroMdx = (specifier: string): Promise<unknown> => import(fromAstroMdx.resolve(specifier));
1960
+ const [compiler, remarkGfm, remarkSmartypants] = await Promise.all([
1961
+ importFromAstroMdx('@mdx-js/mdx'),
1962
+ importFromAstroMdx('remark-gfm'),
1963
+ importFromAstroMdx('remark-smartypants'),
1964
+ ]);
1965
+ return {
1966
+ compiler: compiler as MdxCompilerModule,
1967
+ remarkPlugins: [defaultExport(remarkGfm), defaultExport(remarkSmartypants)],
1968
+ };
1969
+ }
1970
+
1971
+ /**
1972
+ * The body of a post: the source after its YAML frontmatter. The frontmatter is the collection's (Astro reads
1973
+ * it); the island's component is the body alone.
1974
+ */
1975
+ export function stripBlogPostFrontmatter(source: string): string {
1976
+ const match = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/.exec(source);
1977
+ return match === null ? source : source.slice(match[0].length);
1978
+ }
1979
+
1980
+ /**
1981
+ * The module a compiled post imports for its components. Vite's dependency scan never sees it — it appears only in
1982
+ * the output of this plugin's transform — so without naming it the dev server meets it on the first post a visitor
1983
+ * opens, optimizes it then and reloads, and the page that triggered it fails once with React's "Invalid hook call"
1984
+ * (measured on a real site). Named up front, it is optimized at startup with React.
1985
+ */
1986
+ const MDX_PROVIDER_IMPORT_SOURCE = '@mdx-js/react';
1987
+
1988
+ /** Whether a module id is a post imported for the island: `<path>.mdx?website-react-mdx`. */
1989
+ export function isWebsiteReactMdxId(id: string): boolean {
1990
+ const queryStart = id.indexOf('?');
1991
+ if (queryStart === -1) return false;
1992
+ const path = id.slice(0, queryStart);
1993
+ const query = new URLSearchParams(id.slice(queryStart + 1));
1994
+ return path.endsWith('.mdx') && query.has(QUERY_NAME);
1995
+ }
1996
+
1997
+ export function websiteBlogReactMdx(): WebsiteBlogReactMdxIntegration {
1998
+ return {
1999
+ name: 'wildo:website-blog-react-mdx',
2000
+ hooks: {
2001
+ 'astro:config:setup': ({ config, updateConfig }) => {
2002
+ let loaded: Promise<{ compiler: MdxCompilerModule; remarkPlugins: unknown[] }> | undefined;
2003
+ updateConfig({
2004
+ vite: {
2005
+ optimizeDeps: { include: [MDX_PROVIDER_IMPORT_SOURCE] },
2006
+ plugins: [
2007
+ {
2008
+ name: 'wildo:website-react-mdx',
2009
+ enforce: 'pre',
2010
+ async transform(code: string, id: string): Promise<{ code: string; map: null } | null> {
2011
+ if (!isWebsiteReactMdxId(id)) return null;
2012
+ loaded ??= loadCompiler(config.root);
2013
+ const { compiler, remarkPlugins } = await loaded;
2014
+ const compiled = await compiler.compile(stripBlogPostFrontmatter(code), {
2015
+ jsxImportSource: 'react',
2016
+ providerImportSource: MDX_PROVIDER_IMPORT_SOURCE,
2017
+ format: 'mdx',
2018
+ development: false,
2019
+ remarkPlugins,
2020
+ });
2021
+ return { code: compiled.toString(), map: null };
2022
+ },
2023
+ },
2024
+ ],
2025
+ },
2026
+ });
2027
+ },
2028
+ },
2029
+ };
2030
+ }
2031
+ ```
2032
+
2033
+ The query the bridges write as a literal (`WEBSITE_REACT_MDX_QUERY`, exported from
2034
+ `@wildo-ai/saas-website/mdx`, names it for code that inspects a module id):
2035
+
2036
+ ## Import Origins
2037
+
2038
+ - `@wildo-ai/saas-website`
2039
+
2040
+ ## Source Excerpts
2041
+
2042
+ ### Origin Package: `@wildo-ai/saas-website`
2043
+
2044
+ ```typescript
2045
+ *
2046
+ * The query a blog bridge adds to its post imports so `websiteBlogReactMdx()` compiles them for React (#2572).
2047
+ *
2048
+ * A bridge writes it as a LITERAL — Vite requires every `import.meta.glob` option to be one, so a constant cannot be
2049
+ * passed there:
2050
+ *
2051
+ * @example
2052
+ * const rawModules = import.meta.glob('../content/blog/en/*.mdx', { eager: true, query: '?website-react-mdx' });
2053
+ *
2054
+ * A bridge that omits it imports `@astrojs/mdx`'s module instead, compiled to Astro JSX, which a React island cannot
2055
+ * render (React refuses the object it returns as a child; see `websiteBlogReactMdx`). The constant names the literal
2056
+ * for code that checks a module id; it cannot stand in for the literal in the glob itself.
2057
+ */
2058
+ export const WEBSITE_REACT_MDX_QUERY = '?website-react-mdx';
2059
+ ```
2060
+
2061
+ ## The blog vocabulary — authors and tags by their words
2062
+
2063
+ ## Import Origins
2064
+
2065
+ - `@wildo-ai/saas-website`
2066
+
2067
+ ## Source Excerpts
2068
+
2069
+ ### Origin Package: `@wildo-ai/saas-website`
2070
+
2071
+ ```typescript
2072
+ *
2073
+ * The words for a blog's identifiers. A post's frontmatter names its author and its tags by REF (`founding-team`,
2074
+ * `product`): identifiers, which a reader must never see as text. Each ref's words are a CHROME label — chrome
2075
+ * because they appear on every blog surface (a post's byline and tags, an index card) and are rendered outside any one
2076
+ * page's sections:
2077
+ *
2078
+ * - an author: `website.chrome.blog-author.<authorRef>` — the name a byline shows ("The product team");
2079
+ * - a tag: `website.chrome.blog-tag.<tag>` — the word a tag chip shows ("Security", "Sécurité").
2080
+ *
2081
+ * A site lists the keys its posts use in `WebsiteRootConfig.chromeLabelKeys` through
2082
+ * `websiteBlogVocabularyLabelKeys(...)`, so the label-pack check demands each one in every locale. A ref nobody
2083
+ * authored renders as its key, which is what a missing label must look like.
2084
+ *
2085
+ * Rejected: showing the ref humanized (`founding-team` → "Founding team"). That is display text invented from an
2086
+ * identifier — untranslatable, unworded by whoever owns the words, and silent about the gap.
2087
+ */
2088
+ export function websiteBlogAuthorLabelKey(authorRef: string): WebsiteLabelKey {
2089
+ return WebsiteLabelKeySchema.parse(`website.chrome.blog-author.${authorRef}`);
2090
+ }
2091
+
2092
+ /** The chrome label key of one tag's word. See `websiteBlogAuthorLabelKey`. */
2093
+ export function websiteBlogTagLabelKey(tag: string): WebsiteLabelKey {
2094
+ return WebsiteLabelKeySchema.parse(`website.chrome.blog-tag.${tag}`);
2095
+ }
2096
+
2097
+ /**
2098
+ * What kind of author a ref names: one person, or an organization writing as itself ("The product team"). Its
2099
+ * values are schema.org's types, because that is where the distinction is published: a post's `BlogPosting.author`.
2100
+ * Declared by the site with the ref, never guessed from it — a team written up as a `Person` is a false statement to
2101
+ * every search engine that reads the page.
2102
+ */
2103
+ export enum WebsiteBlogAuthorKind {
2104
+ PERSON = 'Person',
2105
+ ORGANIZATION = 'Organization',
2106
+ }
2107
+
2108
+ /** The refs a site's posts use: each author with its kind, and every tag. */
2109
+ export interface WebsiteBlogVocabulary {
2110
+ readonly authors: Readonly<Record<string, WebsiteBlogAuthorKind>>;
2111
+ readonly tags: readonly string[];
2112
+ }
2113
+
2114
+ /** An author as a page states it: the words its label holds, and its kind. */
2115
+ export interface WebsiteBlogAuthor {
2116
+ readonly name: string;
2117
+ readonly kind: WebsiteBlogAuthorKind;
2118
+ }
2119
+
2120
+ /**
2121
+ * Every chrome key a blog vocabulary needs, once each and in a stable order — what a site adds to its
2122
+ * `chromeLabelKeys`.
2123
+ */
2124
+ export function websiteBlogVocabularyLabelKeys(vocabulary: WebsiteBlogVocabulary): WebsiteLabelKey[] {
2125
+ const keys = new Set<string>([
2126
+ ...Object.keys(vocabulary.authors).map((ref) => websiteBlogAuthorLabelKey(ref)),
2127
+ ...vocabulary.tags.map((tag) => websiteBlogTagLabelKey(tag)),
2128
+ ]);
2129
+ return [...keys].sort().map((key) => WebsiteLabelKeySchema.parse(key));
2130
+ }
2131
+
2132
+ /** A post's author and tags as its metadata publishes them: words, never refs. */
2133
+ export interface WebsiteBlogPostWords {
2134
+ readonly author: WebsiteBlogAuthor;
2135
+ /** Each tag's word, in the frontmatter's order. */
2136
+ readonly tags: readonly string[];
2137
+ }
2138
+
2139
+ /**
2140
+ * The words a server-rendered surface publishes for a post — its head (`article:author`, `article:tag`) and its JSON-LD
2141
+ * (`author`, `keywords`) — from the page's label pack.
2142
+ *
2143
+ * Refuses rather than falling back, unlike a rendered byline (which shows a missing label as its key): what this
2144
+ * returns leaves the site as metadata a search engine indexes, where a key or a ref would be a published falsehood
2145
+ * nobody sees. Each refusal names the place a site fixes it.
2146
+ */
2147
+ export function resolveWebsiteBlogPostWords(input: {
2148
+ readonly authorRef: string;
2149
+ readonly tags: readonly string[];
2150
+ readonly vocabulary: WebsiteBlogVocabulary;
2151
+ readonly labelPack: Readonly<Record<string, string>>;
2152
+ }): WebsiteBlogPostWords {
2153
+ // Own entries only: an inherited name (`constructor`, `toString`) is a valid kebab ref and must not read as declared.
2154
+ const kind = Object.hasOwn(input.vocabulary.authors, input.authorRef) ? input.vocabulary.authors[input.authorRef] : undefined;
2155
+ if (kind === undefined) {
2156
+ throw new Error(`[saas-website] Blog author "${input.authorRef}" is not in the site's blog vocabulary. Declare it there with its kind.`);
2157
+ }
2158
+ const word = (key: string, what: string): string => {
2159
+ const value = input.labelPack[key];
2160
+ if (value === undefined) {
2161
+ throw new Error(`[saas-website] Blog ${what} has no words in this locale's label pack. Author "${key}".`);
2162
+ }
2163
+ return value;
2164
+ };
2165
+ const tags = input.tags.map((tag) => {
2166
+ if (!input.vocabulary.tags.includes(tag)) {
2167
+ throw new Error(`[saas-website] Blog tag "${tag}" is not in the site's blog vocabulary. Declare it there.`);
2168
+ }
2169
+ return word(websiteBlogTagLabelKey(tag), `tag "${tag}"`);
2170
+ });
2171
+ return { author: { name: word(websiteBlogAuthorLabelKey(input.authorRef), `author "${input.authorRef}"`), kind }, tags };
2172
+ }
2173
+ ```
2174
+
2175
+ ## Publication dates in the reader's locale
2176
+
2177
+ ## Import Origins
2178
+
2179
+ - `@wildo-ai/saas-website`
2180
+
2181
+ ## Source Excerpts
2182
+
2183
+ ### Origin Package: `@wildo-ai/saas-website`
2184
+
2185
+ ```typescript
2186
+ *
2187
+ * A publication date as a reader of `locale` writes it ("April 17, 2026", "17 avril 2026"), from the ISO-8601 instant
2188
+ * a post's frontmatter states.
2189
+ *
2190
+ * Formatted in UTC, on purpose: a publication date is a calendar day, and the page is rendered on a server and then
2191
+ * hydrated in the reader's browser. Formatting in the local time zone would let the two disagree — a post published
2192
+ * at 23:30 UTC reads as the next day in Paris — and React would report a hydration mismatch for the day it moved.
2193
+ *
2194
+ * The one formatter for every blog surface (a post's byline, an index card), so the two cannot spell one date
2195
+ * differently.
2196
+ */
2197
+ export function formatWebsitePublicationDate(iso: string, locale: string): string {
2198
+ return new Intl.DateTimeFormat(locale, { year: 'numeric', month: 'long', day: 'numeric', timeZone: 'UTC' }).format(new Date(iso));
2199
+ }
2200
+ ```
2201
+
2202
+ ## The blog index — `buildWebsiteBlogIndex` and `useWebsiteBlogIndex`
2203
+
2204
+ `buildWebsiteBlogIndex` is build-time and ASYNC, on `@wildo-ai/saas-website/astro` (it measures covers); each entry
2205
+ carries its post's `cover` with its size.
2206
+
2207
+ ## Import Origins
2208
+
2209
+ - `@wildo-ai/saas-website`
2210
+
2211
+ ## Source Excerpts
2212
+
2213
+ ### Origin Package: `@wildo-ai/saas-website`
2214
+
2215
+ ```typescript
2216
+ *
2217
+ * `WebsiteBlogIndex` — the site's blog posts in ONE locale, newest first, as a page section needs them to list posts:
2218
+ * a "latest from the blog" strip on the home page, a blog index page. Never the bodies; only what a card shows.
2219
+ *
2220
+ * Built at build time from the blog content collection with `buildWebsiteBlogIndex` (`@wildo-ai/saas-website/astro`),
2221
+ * passed to the page's island as `blogIndex`, and read in a section with `useWebsiteBlogIndex()` — the same shape as
2222
+ * the pricing catalogue. So a post listed on the site is a post that exists, with the title and summary its own
2223
+ * frontmatter carries; nothing is copied into the label pack, where it would go stale the day a post is renamed.
2224
+ */
2225
+ export interface WebsiteBlogIndexEntry {
2226
+ readonly slug: string;
2227
+ readonly title: string;
2228
+ readonly summary: string;
2229
+ /** ISO-8601, as the post's frontmatter states it. Format it for the reader with `Intl.DateTimeFormat`. */
2230
+ readonly publishedAt: string;
2231
+ readonly authorRef: string;
2232
+ readonly tags: readonly string[];
2233
+ /**
2234
+ * The post's cover with its size, resolved at build time (`resolveWebsiteBlogPostCover`), so a card draws it through
2235
+ * `WebsiteImage` at its real ratio. Absent when the post has no cover.
2236
+ */
2237
+ readonly cover?: WebsiteBlogPostCover;
2238
+ /** The post's route, locale-neutral (`/blog/<slug>`); `WebsiteInternalLink` adds the locale prefix. */
2239
+ readonly routePath: string;
2240
+ }
2241
+
2242
+ export interface WebsiteBlogIndex {
2243
+ /** The locale every entry is written in. */
2244
+ readonly locale: string;
2245
+ readonly entries: readonly WebsiteBlogIndexEntry[];
2246
+ }
2247
+ ```
2248
+
2249
+ ## Import Origins
2250
+
2251
+ - `@wildo-ai/saas-website`
2252
+
2253
+ ## Source Excerpts
2254
+
2255
+ ### Origin Package: `@wildo-ai/saas-website`
2256
+
2257
+ ```typescript
2258
+ *
2259
+ * `buildWebsiteBlogIndex` — turns the blog content collection into the `WebsiteBlogIndex` of one locale: every post's
2260
+ * frontmatter validated with `parseBlogPostFrontmatter` (the same validation the post pages run, so a post that would
2261
+ * fail its own page fails the listing too), the locale's posts kept, newest first, optionally the first `limit`, and
2262
+ * each listed post's cover resolved with its size by `resolveWebsiteBlogPostCover` — measured from the file for a cover
2263
+ * the site serves — so a card draws it at its real ratio.
2264
+ *
2265
+ * Build-time and Node-side, because measuring a cover reads the site's `public/`: it lives on the
2266
+ * `@wildo-ai/saas-website/astro` subpath and is ASYNC. Call it in the page's `.astro` frontmatter and pass the result to
2267
+ * the island:
2268
+ *
2269
+ * @example
2270
+ * const blogIndex = await buildWebsiteBlogIndex(await getCollection('blog'), { locale: runtime.locale, limit: 3 });
2271
+ * <LandingBridgeIsland client:idle … blogIndex={blogIndex} />
2272
+ *
2273
+ * `publicDir` is forwarded to the cover resolver; set it only when the site's Astro config moves `publicDir`.
2274
+ */
2275
+ export interface BuildWebsiteBlogIndexOptions extends ResolveWebsiteBlogPostCoverOptions {
2276
+ /** The locale whose posts are listed. */
2277
+ readonly locale: string;
2278
+ /** At most this many posts, the newest ones. Every post when omitted. */
2279
+ readonly limit?: number;
2280
+ }
2281
+
2282
+ export async function buildWebsiteBlogIndex(
2283
+ collectionEntries: ReadonlyArray<{ readonly id: string; readonly data: unknown }>,
2284
+ options: BuildWebsiteBlogIndexOptions,
2285
+ ): Promise<WebsiteBlogIndex> {
2286
+ const listed = collectionEntries
2287
+ .map((entry) => parseBlogPostFrontmatter(entry.data, { source: entry.id }))
2288
+ .filter((frontmatter) => frontmatter.locale === options.locale)
2289
+ .sort((left, right) => right.publishedAt.localeCompare(left.publishedAt))
2290
+ .slice(0, options.limit ?? Number.POSITIVE_INFINITY);
2291
+ const coverOptions = options.publicDir === undefined ? {} : { publicDir: options.publicDir };
2292
+ const entries: WebsiteBlogIndexEntry[] = await Promise.all(
2293
+ listed.map(async (frontmatter) => {
2294
+ const cover = await resolveWebsiteBlogPostCover(frontmatter, coverOptions);
2295
+ return {
2296
+ slug: frontmatter.slug,
2297
+ title: frontmatter.title,
2298
+ summary: frontmatter.summary,
2299
+ publishedAt: frontmatter.publishedAt,
2300
+ authorRef: frontmatter.authorRef,
2301
+ tags: [...frontmatter.tags],
2302
+ ...(cover === undefined ? {} : { cover }),
2303
+ routePath: `/blog/${frontmatter.slug}`,
2304
+ };
2305
+ }),
2306
+ );
2307
+ return { locale: options.locale, entries };
2308
+ }
2309
+ ```
2310
+
2311
+ ## Import Origins
2312
+
2313
+ - `@wildo-ai/saas-website`
2314
+
2315
+ ## Source Excerpts
2316
+
2317
+ ### Origin Package: `@wildo-ai/saas-website`
2318
+
2319
+ ```typescript
2320
+ *
2321
+ * `useWebsiteBlogIndex()` — the posts a section lists, from the page's bridge island. Throws when the page did not pass
2322
+ * one: a "latest posts" section that silently rendered no posts would read as a blog with nothing in it.
2323
+ */
2324
+ export function useWebsiteBlogIndex(): WebsiteBlogIndex {
2325
+ const { blogIndex } = useWebsiteRuntime();
2326
+ if (blogIndex === undefined) {
2327
+ throw new Error(
2328
+ '[useWebsiteBlogIndex] this page did not pass a blog index to its bridge island. In the page\'s `.astro` '
2329
+ + 'frontmatter, build it with `await buildWebsiteBlogIndex(await getCollection(\'blog\'), { locale: runtime.locale })` '
2330
+ + '(the @wildo-ai/saas-website/astro subpath) and pass `blogIndex={blogIndex}` to the island.',
2331
+ );
2332
+ }
2333
+ return blogIndex;
2334
+ }
1463
2335
  ```