@wildo-ai/framework-knowledge 1.1.10 → 1.1.12

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