@wildo-ai/framework-knowledge 1.1.0

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 (922) hide show
  1. package/LICENSE +34 -0
  2. package/dist/esm/.builder.pid +9 -0
  3. package/dist/esm/framework-knowledge.definitions.d.ts +51 -0
  4. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -0
  5. package/dist/esm/framework-knowledge.definitions.js +1571 -0
  6. package/dist/esm/framework-knowledge.definitions.js.map +1 -0
  7. package/dist/esm/framework-knowledge.loader.d.ts +72 -0
  8. package/dist/esm/framework-knowledge.loader.d.ts.map +1 -0
  9. package/dist/esm/framework-knowledge.loader.js +258 -0
  10. package/dist/esm/framework-knowledge.loader.js.map +1 -0
  11. package/dist/esm/framework-knowledge.schemas.d.ts +236 -0
  12. package/dist/esm/framework-knowledge.schemas.d.ts.map +1 -0
  13. package/dist/esm/framework-knowledge.schemas.js +23 -0
  14. package/dist/esm/framework-knowledge.schemas.js.map +1 -0
  15. package/dist/esm/index.d.ts +4 -0
  16. package/dist/esm/index.d.ts.map +1 -0
  17. package/dist/esm/index.js +4 -0
  18. package/dist/esm/index.js.map +1 -0
  19. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +53 -0
  20. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -0
  21. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +56 -0
  22. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -0
  23. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +200 -0
  24. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -0
  25. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +228 -0
  26. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -0
  27. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +39 -0
  28. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -0
  29. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +39 -0
  30. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -0
  31. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +261 -0
  32. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -0
  33. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +412 -0
  34. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -0
  35. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +61 -0
  36. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -0
  37. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +65 -0
  38. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -0
  39. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +53 -0
  40. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -0
  41. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +54 -0
  42. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -0
  43. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts +43 -0
  44. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -0
  45. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js +73 -0
  46. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js.map +1 -0
  47. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +53 -0
  48. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -0
  49. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +114 -0
  50. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -0
  51. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +95 -0
  52. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -0
  53. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +102 -0
  54. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -0
  55. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +258 -0
  56. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -0
  57. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +241 -0
  58. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -0
  59. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts +241 -0
  60. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -0
  61. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +202 -0
  62. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -0
  63. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +82 -0
  64. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -0
  65. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +89 -0
  66. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -0
  67. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts +56 -0
  68. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -0
  69. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js +76 -0
  70. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js.map +1 -0
  71. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts +30 -0
  72. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -0
  73. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js +27 -0
  74. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js.map +1 -0
  75. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts +31 -0
  76. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -0
  77. package/dist/esm/playbooks/top_down.market-research/playbook.definition.js +26 -0
  78. package/dist/esm/playbooks/top_down.market-research/playbook.definition.js.map +1 -0
  79. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +254 -0
  80. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -0
  81. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +219 -0
  82. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -0
  83. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +180 -0
  84. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -0
  85. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +302 -0
  86. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -0
  87. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +249 -0
  88. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -0
  89. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +286 -0
  90. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -0
  91. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +248 -0
  92. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -0
  93. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +227 -0
  94. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -0
  95. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +45 -0
  96. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -0
  97. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +48 -0
  98. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -0
  99. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +250 -0
  100. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -0
  101. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +218 -0
  102. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -0
  103. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -0
  104. package/dist/knowledge/manifest.json +45 -0
  105. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +407 -0
  106. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +69 -0
  107. package/dist/knowledge/playbooks/bottom_up.build-dispatch/evaluation-protocol.json +1 -0
  108. package/dist/knowledge/playbooks/bottom_up.build-dispatch/evaluation-treatment.json +1 -0
  109. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +556 -0
  110. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +47 -0
  111. package/dist/knowledge/playbooks/bottom_up.build-scale/method.md +344 -0
  112. package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +43 -0
  113. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-protocol.json +1 -0
  114. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-treatment.json +1 -0
  115. package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +259 -0
  116. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +83 -0
  117. package/dist/knowledge/playbooks/bottom_up.domain-plan/structured-artifact-action.json +1 -0
  118. package/dist/knowledge/playbooks/bottom_up.foundation/method.md +321 -0
  119. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +79 -0
  120. package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +185 -0
  121. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +66 -0
  122. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +737 -0
  123. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +44 -0
  124. package/dist/knowledge/playbooks/refinement.document-facts/method.md +261 -0
  125. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +57 -0
  126. package/dist/knowledge/playbooks/top_down.brand-identity/method.md +151 -0
  127. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +124 -0
  128. package/dist/knowledge/playbooks/top_down.business-model/evaluation-protocol.json +1 -0
  129. package/dist/knowledge/playbooks/top_down.business-model/evaluation-treatment.json +1 -0
  130. package/dist/knowledge/playbooks/top_down.business-model/method.md +128 -0
  131. package/dist/knowledge/playbooks/top_down.business-model/playbook.json +102 -0
  132. package/dist/knowledge/playbooks/top_down.business-model/structured-artifact-action.json +1 -0
  133. package/dist/knowledge/playbooks/top_down.capability-map/evaluation-protocol.json +1 -0
  134. package/dist/knowledge/playbooks/top_down.capability-map/evaluation-treatment.json +1 -0
  135. package/dist/knowledge/playbooks/top_down.capability-map/method.md +239 -0
  136. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +73 -0
  137. package/dist/knowledge/playbooks/top_down.capability-map/structured-artifact-action.json +1 -0
  138. package/dist/knowledge/playbooks/top_down.compliance-posture/method.md +177 -0
  139. package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +95 -0
  140. package/dist/knowledge/playbooks/top_down.market-analysis/method.md +64 -0
  141. package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +49 -0
  142. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/method.md +56 -0
  143. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +40 -0
  144. package/dist/knowledge/playbooks/top_down.market-research/method.md +68 -0
  145. package/dist/knowledge/playbooks/top_down.market-research/playbook.json +42 -0
  146. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-protocol.json +1 -0
  147. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-treatment.json +1 -0
  148. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +239 -0
  149. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +69 -0
  150. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/structured-artifact-action.json +1 -0
  151. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-protocol.json +1 -0
  152. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-treatment.json +1 -0
  153. package/dist/knowledge/playbooks/top_down.phase-gate/method.md +96 -0
  154. package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +77 -0
  155. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-protocol.json +1 -0
  156. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-treatment.json +1 -0
  157. package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +53 -0
  158. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +61 -0
  159. package/dist/knowledge/playbooks/top_down.requirements-definition/structured-artifact-action.json +1 -0
  160. package/dist/knowledge/playbooks/top_down.scope-roadmap/evaluation-protocol.json +1 -0
  161. package/dist/knowledge/playbooks/top_down.scope-roadmap/evaluation-treatment.json +1 -0
  162. package/dist/knowledge/playbooks/top_down.scope-roadmap/method.md +280 -0
  163. package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +87 -0
  164. package/dist/knowledge/playbooks/top_down.scope-roadmap/structured-artifact-action.json +1 -0
  165. package/dist/knowledge/playbooks/top_down.value-proposition/method.md +204 -0
  166. package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +54 -0
  167. package/dist/knowledge/playbooks/top_down.vision-elicitation/evaluation-protocol.json +1 -0
  168. package/dist/knowledge/playbooks/top_down.vision-elicitation/evaluation-treatment.json +1 -0
  169. package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +146 -0
  170. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +120 -0
  171. package/dist/knowledge/playbooks/top_down.vision-elicitation/structured-artifact-action.json +1 -0
  172. package/dist/knowledge/references/application.database.migration-change-risk.md +28 -0
  173. package/dist/knowledge/references/assertions.authored-metadata.config.md +90 -0
  174. package/dist/knowledge/references/assertions.behaviors.wire-contracts.md +223 -0
  175. package/dist/knowledge/references/assertions.references.conventions.md +92 -0
  176. package/dist/knowledge/references/assertions.snapshot.validation.md +317 -0
  177. package/dist/knowledge/references/assertions.specification.config.md +287 -0
  178. package/dist/knowledge/references/brand.asset.config.md +167 -0
  179. package/dist/knowledge/references/brand.authored-metadata.config.md +51 -0
  180. package/dist/knowledge/references/brand.logo-direction.config.md +88 -0
  181. package/dist/knowledge/references/brand.name.config.md +46 -0
  182. package/dist/knowledge/references/brand.snapshot.config.md +76 -0
  183. package/dist/knowledge/references/brand.snapshot.validation.md +446 -0
  184. package/dist/knowledge/references/brand.visual-tone.config.md +56 -0
  185. package/dist/knowledge/references/build-plan.task-graph.config.md +198 -0
  186. package/dist/knowledge/references/business-model.authored-metadata.config.md +65 -0
  187. package/dist/knowledge/references/business-model.pricing-plan.config.md +122 -0
  188. package/dist/knowledge/references/business-model.references.conventions.md +99 -0
  189. package/dist/knowledge/references/business-model.snapshot.config.md +121 -0
  190. package/dist/knowledge/references/business-model.snapshot.validation.md +325 -0
  191. package/dist/knowledge/references/cli.market.generate-command.md +230 -0
  192. package/dist/knowledge/references/cli.market.utils.md +147 -0
  193. package/dist/knowledge/references/companion.introspection.behaviors.market.md +90 -0
  194. package/dist/knowledge/references/companion.introspection.handlers.market.md +42 -0
  195. package/dist/knowledge/references/companion.market.generation-service.md +270 -0
  196. package/dist/knowledge/references/companion.market.prompt-renderer.md +244 -0
  197. package/dist/knowledge/references/companion.technical-doc.service.md +809 -0
  198. package/dist/knowledge/references/engine.client-bundle.allow-list.md +125 -0
  199. package/dist/knowledge/references/engine.client-bundle.discipline.md +130 -0
  200. package/dist/knowledge/references/engine.client-bundle.external-connectors-public.discipline.md +55 -0
  201. package/dist/knowledge/references/engine.saas-technical-doc.config.md +215 -0
  202. package/dist/knowledge/references/engine.saas-website.config.md +331 -0
  203. package/dist/knowledge/references/example.authorization.unit-narrowing.declaration.md +24 -0
  204. package/dist/knowledge/references/example.backend.addon-wiring.module.md +55 -0
  205. package/dist/knowledge/references/example.backend.custom-operation.create-postfix.md +35 -0
  206. package/dist/knowledge/references/example.backend.operation.error-throw.md +17 -0
  207. package/dist/knowledge/references/example.config.app-shell.command-menu-items.md +63 -0
  208. package/dist/knowledge/references/example.config.app-shell.full.md +147 -0
  209. package/dist/knowledge/references/example.config.app-shell.hosted-components.md +45 -0
  210. package/dist/knowledge/references/example.config.app-shell.quick-switcher-fields.md +37 -0
  211. package/dist/knowledge/references/example.config.backend.billing-enable.md +20 -0
  212. package/dist/knowledge/references/example.config.backend.required-floors.md +46 -0
  213. package/dist/knowledge/references/example.config.design-system.full.md +162 -0
  214. package/dist/knowledge/references/example.config.navigation.full.md +71 -0
  215. package/dist/knowledge/references/example.config.provider.backend-scope-billing.md +27 -0
  216. package/dist/knowledge/references/example.data-seeding.minimal.md +114 -0
  217. package/dist/knowledge/references/example.email.template.minimal.md +54 -0
  218. package/dist/knowledge/references/example.engine.component-registration.lazy-load.md +16 -0
  219. package/dist/knowledge/references/example.engine.product-definitions.feature-and-profiles.md +146 -0
  220. package/dist/knowledge/references/example.flows-actors.chat-assistant.md +196 -0
  221. package/dist/knowledge/references/example.flows-actors.llm-agent-one-shot.md +174 -0
  222. package/dist/knowledge/references/example.i18n.label-generation.engine-barrel.md +15 -0
  223. package/dist/knowledge/references/example.infra.cdn.cloudflare.md +23 -0
  224. package/dist/knowledge/references/example.infra.cdn.generic.md +17 -0
  225. package/dist/knowledge/references/example.infra.environment-config.local.md +250 -0
  226. package/dist/knowledge/references/example.market.alternative.in-house-build.md +49 -0
  227. package/dist/knowledge/references/example.market.authored-metadata.md +32 -0
  228. package/dist/knowledge/references/example.market.buying-journey.core-icp.md +140 -0
  229. package/dist/knowledge/references/example.market.category.config.md +71 -0
  230. package/dist/knowledge/references/example.market.channel.community.md +39 -0
  231. package/dist/knowledge/references/example.market.feature-benefit.kano-threshold.md +67 -0
  232. package/dist/knowledge/references/example.market.feature-benefit.pain-reliever.md +65 -0
  233. package/dist/knowledge/references/example.market.icp.anti-target.md +47 -0
  234. package/dist/knowledge/references/example.market.icp.individual.md +82 -0
  235. package/dist/knowledge/references/example.market.icp.legal-entity-with-geographies.md +95 -0
  236. package/dist/knowledge/references/example.market.is-benefit-available.composition.md +40 -0
  237. package/dist/knowledge/references/example.market.job.emotional.md +27 -0
  238. package/dist/knowledge/references/example.market.job.functional.md +28 -0
  239. package/dist/knowledge/references/example.market.message-template.seeds.md +106 -0
  240. package/dist/knowledge/references/example.market.objection.pricing.md +39 -0
  241. package/dist/knowledge/references/example.market.persona.dmu-with-inheritance.md +62 -0
  242. package/dist/knowledge/references/example.market.persona.individual-self.md +51 -0
  243. package/dist/knowledge/references/example.market.positioning.per-icp.md +103 -0
  244. package/dist/knowledge/references/example.market.proof.metric.md +39 -0
  245. package/dist/knowledge/references/example.market.scoring.golden-case.md +46 -0
  246. package/dist/knowledge/references/example.market.scoring.no-coverage-zero.md +40 -0
  247. package/dist/knowledge/references/example.market.snapshot-validation.duplicate-journey-stage.md +36 -0
  248. package/dist/knowledge/references/example.market.snapshot-validation.errors-by-kind.md +55 -0
  249. package/dist/knowledge/references/example.market.snapshot-validation.objection-proof-benefit-mismatch.md +74 -0
  250. package/dist/knowledge/references/example.market.snapshot-validation.proof-without-support.md +32 -0
  251. package/dist/knowledge/references/example.market.snapshot-validation.threshold-without-job.md +44 -0
  252. package/dist/knowledge/references/example.market.snapshot.assembled.md +49 -0
  253. package/dist/knowledge/references/example.market.tone-of-voice.config.md +41 -0
  254. package/dist/knowledge/references/example.market.trigger.growth-milestone.md +43 -0
  255. package/dist/knowledge/references/example.module.companion-exports.full.md +142 -0
  256. package/dist/knowledge/references/example.module.registration.shared.md +16 -0
  257. package/dist/knowledge/references/example.module.relationships.actor-edge-back-to-scope-owner.md +47 -0
  258. package/dist/knowledge/references/example.module.relationships.discriminator.md +25 -0
  259. package/dist/knowledge/references/example.module.relationships.scope-membership-junction.md +25 -0
  260. package/dist/knowledge/references/example.provider.backend-module-shape.md +110 -0
  261. package/dist/knowledge/references/example.provider.contribution.backend-billing.md +12 -0
  262. package/dist/knowledge/references/example.provider.frontend-file-picker.contribution.md +30 -0
  263. package/dist/knowledge/references/example.provider.frontend-file-picker.module.md +21 -0
  264. package/dist/knowledge/references/example.rag.source-fields.declaration.md +83 -0
  265. package/dist/knowledge/references/example.rate-limit.custom-controller-surface.md +25 -0
  266. package/dist/knowledge/references/example.rate-limit.resource-operation-surface.md +24 -0
  267. package/dist/knowledge/references/example.resource.add-field.priority-enum.md +19 -0
  268. package/dist/knowledge/references/example.resource.add-resource.module-factory-map.md +21 -0
  269. package/dist/knowledge/references/example.resource.config-wiring.fk-relationship.md +33 -0
  270. package/dist/knowledge/references/example.resource.custom-view.read-host.md +28 -0
  271. package/dist/knowledge/references/example.resource.mcp-exposure.md +65 -0
  272. package/dist/knowledge/references/example.resource.reference-constraints.role-constrained.md +27 -0
  273. package/dist/knowledge/references/example.resource.ui-behavior.enum-badge.md +22 -0
  274. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +43 -0
  275. package/dist/knowledge/references/example.spec.composite-view.workspace.md +72 -0
  276. package/dist/knowledge/references/example.spec.feature.flag-with-codehandling.md +64 -0
  277. package/dist/knowledge/references/example.spec.frontend-component.prop-vocabulary.md +88 -0
  278. package/dist/knowledge/references/example.spec.resource.semantic-field.md +23 -0
  279. package/dist/knowledge/references/example.views.app-level.composite-views-config.md +19 -0
  280. package/dist/knowledge/references/example.views.chart-view.resource-owned.md +69 -0
  281. package/dist/knowledge/references/example.views.composite-view.host-embeds.md +31 -0
  282. package/dist/knowledge/references/example.views.composite-view.workspace.md +65 -0
  283. package/dist/knowledge/references/example.views.custom-view.execution-host.md +41 -0
  284. package/dist/knowledge/references/example.views.execution-view.resource-owned.md +25 -0
  285. package/dist/knowledge/references/external-connectors.app.frontend-provider-module.md +42 -0
  286. package/dist/knowledge/references/market.alternative.config.md +68 -0
  287. package/dist/knowledge/references/market.alternative.kind.md +32 -0
  288. package/dist/knowledge/references/market.authored-metadata.config.md +64 -0
  289. package/dist/knowledge/references/market.buying-journey.config.md +43 -0
  290. package/dist/knowledge/references/market.buying-journey.stage.md +33 -0
  291. package/dist/knowledge/references/market.category.config.md +63 -0
  292. package/dist/knowledge/references/market.channel.config.md +59 -0
  293. package/dist/knowledge/references/market.channel.kind.md +49 -0
  294. package/dist/knowledge/references/market.context-block.builder.md +544 -0
  295. package/dist/knowledge/references/market.context-block.response.md +57 -0
  296. package/dist/knowledge/references/market.feature-benefit.config.md +84 -0
  297. package/dist/knowledge/references/market.feature-benefit.kano.md +41 -0
  298. package/dist/knowledge/references/market.gain.config.md +50 -0
  299. package/dist/knowledge/references/market.generation.response.md +108 -0
  300. package/dist/knowledge/references/market.icp.config.md +162 -0
  301. package/dist/knowledge/references/market.icp.geographic-targeting.md +57 -0
  302. package/dist/knowledge/references/market.inherit-from.md +74 -0
  303. package/dist/knowledge/references/market.is-benefit-available.md +58 -0
  304. package/dist/knowledge/references/market.job.config.md +48 -0
  305. package/dist/knowledge/references/market.message-template.config.md +86 -0
  306. package/dist/knowledge/references/market.objection.config.md +56 -0
  307. package/dist/knowledge/references/market.objection.kind.md +34 -0
  308. package/dist/knowledge/references/market.pain.config.md +50 -0
  309. package/dist/knowledge/references/market.persona.config.md +64 -0
  310. package/dist/knowledge/references/market.positioning.config.md +84 -0
  311. package/dist/knowledge/references/market.proof.config.md +48 -0
  312. package/dist/knowledge/references/market.proof.kind.md +34 -0
  313. package/dist/knowledge/references/market.references.weighted-edges.md +105 -0
  314. package/dist/knowledge/references/market.scoring.fit.md +215 -0
  315. package/dist/knowledge/references/market.snapshot.config.md +34 -0
  316. package/dist/knowledge/references/market.snapshot.validation.md +1171 -0
  317. package/dist/knowledge/references/market.tone-of-voice.config.md +80 -0
  318. package/dist/knowledge/references/market.trigger.config.md +45 -0
  319. package/dist/knowledge/references/market.trigger.kind.md +35 -0
  320. package/dist/knowledge/references/placement-plan.config.md +330 -0
  321. package/dist/knowledge/references/platform.config.application-database.md +74 -0
  322. package/dist/knowledge/references/platform.config.application-modules.md +30 -0
  323. package/dist/knowledge/references/platform.config.backing-services.md +266 -0
  324. package/dist/knowledge/references/platform.config.cdn.md +167 -0
  325. package/dist/knowledge/references/platform.config.environment.deployment.md +263 -0
  326. package/dist/knowledge/references/platform.config.saas.md +405 -0
  327. package/dist/knowledge/references/presets.models.design-system.configuration.md +59 -0
  328. package/dist/knowledge/references/presets.models.design-system.source-config.md +72 -0
  329. package/dist/knowledge/references/presets.models.labelling.sections.md +64 -0
  330. package/dist/knowledge/references/presets.models.material.profile-contract.md +192 -0
  331. package/dist/knowledge/references/presets.models.material.runtime-policy.md +60 -0
  332. package/dist/knowledge/references/presets.models.surface-policy.defaults.md +613 -0
  333. package/dist/knowledge/references/presets.models.surface-policy.md +534 -0
  334. package/dist/knowledge/references/presets.models.surface-variant.md +56 -0
  335. package/dist/knowledge/references/requirements.authored-metadata.config.md +64 -0
  336. package/dist/knowledge/references/requirements.functional-requirement.config.md +68 -0
  337. package/dist/knowledge/references/requirements.non-functional-requirement.config.md +100 -0
  338. package/dist/knowledge/references/requirements.references.conventions.md +125 -0
  339. package/dist/knowledge/references/requirements.snapshot.config.md +73 -0
  340. package/dist/knowledge/references/requirements.snapshot.validation.md +333 -0
  341. package/dist/knowledge/references/roadmap.authored-metadata.config.md +64 -0
  342. package/dist/knowledge/references/roadmap.phase.config.md +149 -0
  343. package/dist/knowledge/references/roadmap.references.conventions.md +89 -0
  344. package/dist/knowledge/references/roadmap.snapshot.config.md +65 -0
  345. package/dist/knowledge/references/roadmap.snapshot.validation.md +325 -0
  346. package/dist/knowledge/references/saas.backend.app-config.backend-authored.md +32 -0
  347. package/dist/knowledge/references/saas.backend.application-initialization.assembly.md +38 -0
  348. package/dist/knowledge/references/saas.backend.billing.resolution-failure-reasons.md +45 -0
  349. package/dist/knowledge/references/saas.backend.custom-operation.authoritative-fields.md +53 -0
  350. package/dist/knowledge/references/saas.backend.custom-operation.transactional-core.md +120 -0
  351. package/dist/knowledge/references/saas.backend.domain-module.md +237 -0
  352. package/dist/knowledge/references/saas.backend.email-template.definition.md +69 -0
  353. package/dist/knowledge/references/saas.backend.flows-actors.a2a-agent-card.md +89 -0
  354. package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +118 -0
  355. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +82 -0
  356. package/dist/knowledge/references/saas.backend.flows-actors.invoke-agent.md +48 -0
  357. package/dist/knowledge/references/saas.backend.flows-actors.resource-read-tool.md +39 -0
  358. package/dist/knowledge/references/saas.backend.flows-actors.resource-write-tool.md +67 -0
  359. package/dist/knowledge/references/saas.backend.pdf-template.bindings.md +52 -0
  360. package/dist/knowledge/references/saas.backend.pdf-template.definition.md +113 -0
  361. package/dist/knowledge/references/saas.backend.rate-limit-service.check-policy.md +75 -0
  362. package/dist/knowledge/references/saas.backend.system-access-service.md +994 -0
  363. package/dist/knowledge/references/saas.data-seeding.admin-endpoints.md +59 -0
  364. package/dist/knowledge/references/saas.data-seeding.bootstrap-wiring.md +184 -0
  365. package/dist/knowledge/references/saas.data-seeding.definition-input.md +95 -0
  366. package/dist/knowledge/references/saas.data-seeding.modes.md +72 -0
  367. package/dist/knowledge/references/saas.data-seeding.run-ledger.md +198 -0
  368. package/dist/knowledge/references/saas.data-seeding.run-status.md +35 -0
  369. package/dist/knowledge/references/saas.data-seeding.schedule.md +91 -0
  370. package/dist/knowledge/references/saas.data-seeding.scope-iteration-strategy.md +46 -0
  371. package/dist/knowledge/references/saas.external-providers.backend-provider-registry.runtime-filter.md +55 -0
  372. package/dist/knowledge/references/saas.external-providers.document-extraction.applicability.md +26 -0
  373. package/dist/knowledge/references/saas.external-providers.embeddings.applicability.md +30 -0
  374. package/dist/knowledge/references/saas.external-providers.llm.model-configuration.md +124 -0
  375. package/dist/knowledge/references/saas.external-providers.llm.operation-key.md +49 -0
  376. package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +265 -0
  377. package/dist/knowledge/references/saas.frontend.app-level-component.vocabulary.md +148 -0
  378. package/dist/knowledge/references/saas.frontend.app-shell.hosted-components.md +145 -0
  379. package/dist/knowledge/references/saas.frontend.chart-view.inserted-declaration.md +80 -0
  380. package/dist/knowledge/references/saas.frontend.command-menu.omnibox.md +88 -0
  381. package/dist/knowledge/references/saas.frontend.command-menu.search-resource.md +109 -0
  382. package/dist/knowledge/references/saas.frontend.component-registration.entry.md +21 -0
  383. package/dist/knowledge/references/saas.frontend.composite-view.authoring.md +102 -0
  384. package/dist/knowledge/references/saas.frontend.composite-view.define-helper.md +31 -0
  385. package/dist/knowledge/references/saas.frontend.domain-module.md +31 -0
  386. package/dist/knowledge/references/saas.frontend.embedded-resource-descent.md +37 -0
  387. package/dist/knowledge/references/saas.frontend.execution-view.action-status-contract.md +172 -0
  388. package/dist/knowledge/references/saas.frontend.execution-view.action-status-contract.per-action-retry-loop.md +115 -0
  389. package/dist/knowledge/references/saas.frontend.execution-view.definition.md +172 -0
  390. package/dist/knowledge/references/saas.frontend.execution-view.dirty-bridge-contract.local-pane.md +109 -0
  391. package/dist/knowledge/references/saas.frontend.execution-view.dirty-bridge-contract.md +55 -0
  392. package/dist/knowledge/references/saas.frontend.execution-view.dirty-state-contract.md +151 -0
  393. package/dist/knowledge/references/saas.frontend.execution-view.failure-handling-contract.md +302 -0
  394. package/dist/knowledge/references/saas.frontend.execution-view.loading-aggregation.md +89 -0
  395. package/dist/knowledge/references/saas.frontend.execution-view.loading-aggregation.participation-prefetch.md +231 -0
  396. package/dist/knowledge/references/saas.frontend.execution-view.loading-aggregation.participation-prefetch.shell-data-hydrator.md +174 -0
  397. package/dist/knowledge/references/saas.frontend.execution-view.navigation-handling-and-embedding.md +96 -0
  398. package/dist/knowledge/references/saas.frontend.execution-view.navigation-handling-and-embedding.resolution.md +45 -0
  399. package/dist/knowledge/references/saas.frontend.execution-view.outcome-emission-contract.md +71 -0
  400. package/dist/knowledge/references/saas.frontend.execution-view.participation-and-anchor.md +80 -0
  401. package/dist/knowledge/references/saas.frontend.execution-view.three-zone-contract.md +147 -0
  402. package/dist/knowledge/references/saas.frontend.flows-actors-view.md +40 -0
  403. package/dist/knowledge/references/saas.frontend.form-fields.file-provider-constraints.md +80 -0
  404. package/dist/knowledge/references/saas.frontend.full-custom-view.definition.md +64 -0
  405. package/dist/knowledge/references/saas.frontend.inserted-view.identity-bindings-descriptor.md +149 -0
  406. package/dist/knowledge/references/saas.frontend.operation-key-and-resource-config-like.md +63 -0
  407. package/dist/knowledge/references/saas.frontend.quick-switcher.scope-field.md +102 -0
  408. package/dist/knowledge/references/saas.frontend.related-resource-embeds.md +86 -0
  409. package/dist/knowledge/references/saas.frontend.related-resource-preview.md +23 -0
  410. package/dist/knowledge/references/saas.frontend.related-resource-sections.md +28 -0
  411. package/dist/knowledge/references/saas.frontend.resource-header-title.md +43 -0
  412. package/dist/knowledge/references/saas.frontend.resource-layout-templates.md +215 -0
  413. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +531 -0
  414. package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +210 -0
  415. package/dist/knowledge/references/saas.frontend.resource-ui-behavior-preset-map.md +39 -0
  416. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +58 -0
  417. package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +118 -0
  418. package/dist/knowledge/references/saas.frontend.view-definition-scope.md +42 -0
  419. package/dist/knowledge/references/saas.market.generation-agent.md +104 -0
  420. package/dist/knowledge/references/saas.models.core-resource-operation.md +86 -0
  421. package/dist/knowledge/references/saas.models.data-mode-read-list.md +395 -0
  422. package/dist/knowledge/references/saas.models.engine-capabilities.md +114 -0
  423. package/dist/knowledge/references/saas.models.error-type.md +45 -0
  424. package/dist/knowledge/references/saas.models.external-data-pipeline.md +162 -0
  425. package/dist/knowledge/references/saas.models.feature-limit-semantic.md +51 -0
  426. package/dist/knowledge/references/saas.models.flows-actors.agent-configuration.md +127 -0
  427. package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +115 -0
  428. package/dist/knowledge/references/saas.models.flows-actors.agent-invocation.md +52 -0
  429. package/dist/knowledge/references/saas.models.flows-actors.agent-prompt-spec.md +188 -0
  430. package/dist/knowledge/references/saas.models.http-api-binding.md +237 -0
  431. package/dist/knowledge/references/saas.models.navigation.layout.md +149 -0
  432. package/dist/knowledge/references/saas.models.organization-unit-narrowing-containment.md +22 -0
  433. package/dist/knowledge/references/saas.models.organization-unit-narrowing-declaration.md +42 -0
  434. package/dist/knowledge/references/saas.models.polymorphism.optout-business-key.md +62 -0
  435. package/dist/knowledge/references/saas.models.polymorphism.variant-definition.md +74 -0
  436. package/dist/knowledge/references/saas.models.provider-capabilities.md +97 -0
  437. package/dist/knowledge/references/saas.models.rate-limit-configuration.md +67 -0
  438. package/dist/knowledge/references/saas.models.relationship-handling-contract.md +30 -0
  439. package/dist/knowledge/references/saas.models.relationship-handling-settings.md +62 -0
  440. package/dist/knowledge/references/saas.models.relationship-nature-and-models.md +112 -0
  441. package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +431 -0
  442. package/dist/knowledge/references/saas.models.resource-config.forwarded-label.md +88 -0
  443. package/dist/knowledge/references/saas.models.resource-config.operation-api-call.md +89 -0
  444. package/dist/knowledge/references/saas.models.resource-config.operation-base.md +79 -0
  445. package/dist/knowledge/references/saas.models.resource-config.operation-mcp-exposure.md +49 -0
  446. package/dist/knowledge/references/saas.models.resource-config.operation-path.md +27 -0
  447. package/dist/knowledge/references/saas.models.resource-config.operation-union.md +26 -0
  448. package/dist/knowledge/references/saas.models.resource-config.operation-variant-for-key.md +62 -0
  449. package/dist/knowledge/references/saas.models.resource-config.resource-configuration.md +124 -0
  450. package/dist/knowledge/references/saas.models.resource-config.resource-relationships-buckets.md +38 -0
  451. package/dist/knowledge/references/saas.models.resource-config.resources-registry.md +69 -0
  452. package/dist/knowledge/references/saas.models.resource-config.searchable-relation.md +89 -0
  453. package/dist/knowledge/references/saas.models.resource-config.system-access-policy.md +121 -0
  454. package/dist/knowledge/references/saas.models.resource-config.token-generation.md +145 -0
  455. package/dist/knowledge/references/saas.models.resource-field-identifier.md +25 -0
  456. package/dist/knowledge/references/saas.models.resource-operation-display-risk.md +77 -0
  457. package/dist/knowledge/references/saas.models.resource-operation-variant-runtime.md +58 -0
  458. package/dist/knowledge/references/saas.models.resource-primary-scope.md +36 -0
  459. package/dist/knowledge/references/saas.models.resource-relationship-access-scope.md +26 -0
  460. package/dist/knowledge/references/saas.models.resource-relationship-builder-parameters.md +100 -0
  461. package/dist/knowledge/references/saas.models.resource-relationship-cardinality.md +57 -0
  462. package/dist/knowledge/references/saas.models.resource-relationship-declaration.md +69 -0
  463. package/dist/knowledge/references/saas.models.resource-relationship-resolved-semantics.md +60 -0
  464. package/dist/knowledge/references/saas.models.resource-relationship-schema.md +172 -0
  465. package/dist/knowledge/references/saas.models.resource-server-instance.md +109 -0
  466. package/dist/knowledge/references/saas.models.resource-type.md +24 -0
  467. package/dist/knowledge/references/saas.models.schema-family-builder.md +242 -0
  468. package/dist/knowledge/references/saas.models.scope-membership.md +143 -0
  469. package/dist/knowledge/references/saas.models.shared-domain-module.md +36 -0
  470. package/dist/knowledge/references/saas.models.shared-saas-module.md +36 -0
  471. package/dist/knowledge/references/saas.public-runtime.contract.md +229 -0
  472. package/dist/knowledge/references/saas.rag.retrieval-bounds.md +106 -0
  473. package/dist/knowledge/references/saas.rag.retrieval-refusals.md +89 -0
  474. package/dist/knowledge/references/saas.rag.retrieval-request.md +130 -0
  475. package/dist/knowledge/references/saas.rag.retrieval-result.md +147 -0
  476. package/dist/knowledge/references/saas.rag.retrieval-scores.md +54 -0
  477. package/dist/knowledge/references/saas.specifications.application-document-fact-specification.contract.md +59 -0
  478. package/dist/knowledge/references/saas.specifications.application-document-publication.contract.md +74 -0
  479. package/dist/knowledge/references/saas.specifications.assurance-document-blueprint.contract.md +1158 -0
  480. package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +2602 -0
  481. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.catalog-spec-shared.md +180 -0
  482. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.discriminated-union.md +138 -0
  483. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-aggregate-offer.md +46 -0
  484. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-aggregate-rating.md +47 -0
  485. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-article.md +49 -0
  486. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-blog-posting.md +62 -0
  487. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-breadcrumb-list.md +46 -0
  488. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-faq-page.md +51 -0
  489. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-offer.md +46 -0
  490. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-organization.md +48 -0
  491. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-product.md +59 -0
  492. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-review.md +46 -0
  493. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-website.md +46 -0
  494. package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +530 -0
  495. package/dist/knowledge/references/saas.specifications.composite-view-specification.md +49 -0
  496. package/dist/knowledge/references/saas.specifications.error-message-specification.md +92 -0
  497. package/dist/knowledge/references/saas.specifications.family-specifications.md +109 -0
  498. package/dist/knowledge/references/saas.specifications.feature-specification.md +93 -0
  499. package/dist/knowledge/references/saas.specifications.frontend-component-spec-factory.md +113 -0
  500. package/dist/knowledge/references/saas.specifications.frontend-component-spec-model.md +366 -0
  501. package/dist/knowledge/references/saas.specifications.resource-frontend-configuration-aspect.md +41 -0
  502. package/dist/knowledge/references/saas.specifications.resource-operation-spec.md +1978 -0
  503. package/dist/knowledge/references/saas.specifications.resource-pdf-template-spec.md +58 -0
  504. package/dist/knowledge/references/saas.specifications.resource-spec-code-handling.md +49 -0
  505. package/dist/knowledge/references/saas.specifications.resource-spec-config.md +156 -0
  506. package/dist/knowledge/references/saas.specifications.resource-spec-factory.md +171 -0
  507. package/dist/knowledge/references/saas.specifications.resource-spec-frontend-config-type.md +54 -0
  508. package/dist/knowledge/references/saas.specifications.resource-spec-frontend-prose.md +171 -0
  509. package/dist/knowledge/references/saas.website.astro.bridge.md +262 -0
  510. package/dist/knowledge/references/saas.website.astro.head-renderer.md +271 -0
  511. package/dist/knowledge/references/saas.website.astro.headers-renderer.md +41 -0
  512. package/dist/knowledge/references/saas.website.astro.i18n-helper.md +121 -0
  513. package/dist/knowledge/references/saas.website.astro.label-key-collector.md +117 -0
  514. package/dist/knowledge/references/saas.website.astro.label-loader.md +377 -0
  515. package/dist/knowledge/references/saas.website.astro.llms-txt-server.md +46 -0
  516. package/dist/knowledge/references/saas.website.astro.pick-labels-for-page.md +90 -0
  517. package/dist/knowledge/references/saas.website.astro.robots-renderer.md +174 -0
  518. package/dist/knowledge/references/saas.website.astro.runtime-helper.md +187 -0
  519. package/dist/knowledge/references/saas.website.astro.site-context.md +141 -0
  520. package/dist/knowledge/references/saas.website.astro.sitemap-coverage.md +188 -0
  521. package/dist/knowledge/references/saas.website.astro.structured-data-renderer.md +174 -0
  522. package/dist/knowledge/references/saas.website.blog.bridge.md +396 -0
  523. package/dist/knowledge/references/saas.website.blog.collection-config.md +180 -0
  524. package/dist/knowledge/references/saas.website.blog.frontmatter.md +116 -0
  525. package/dist/knowledge/references/saas.website.blog.head-renderer.md +292 -0
  526. package/dist/knowledge/references/saas.website.blog.mdx-provider.md +100 -0
  527. package/dist/knowledge/references/saas.website.blog.post-renderer.md +291 -0
  528. package/dist/knowledge/references/saas.website.design-tokens.bundle.md +29 -0
  529. package/dist/knowledge/references/saas.website.design-tokens.colors.md +64 -0
  530. package/dist/knowledge/references/saas.website.design-tokens.radius.md +38 -0
  531. package/dist/knowledge/references/saas.website.factories.define-page-manifest.md +98 -0
  532. package/dist/knowledge/references/saas.website.factories.define-section.md +128 -0
  533. package/dist/knowledge/references/saas.website.label-keys.compose-helper.md +36 -0
  534. package/dist/knowledge/references/saas.website.label-keys.format.md +67 -0
  535. package/dist/knowledge/references/saas.website.label-pack.validator.md +206 -0
  536. package/dist/knowledge/references/saas.website.page-layout.component.md +217 -0
  537. package/dist/knowledge/references/saas.website.page-manifest.meta-label-keys.md +47 -0
  538. package/dist/knowledge/references/saas.website.page-manifest.route-path.md +49 -0
  539. package/dist/knowledge/references/saas.website.page-manifest.schema.md +186 -0
  540. package/dist/knowledge/references/saas.website.page-manifest.seo.md +46 -0
  541. package/dist/knowledge/references/saas.website.page.context.md +57 -0
  542. package/dist/knowledge/references/saas.website.primitives.button.md +123 -0
  543. package/dist/knowledge/references/saas.website.primitives.heading.md +103 -0
  544. package/dist/knowledge/references/saas.website.primitives.image.md +103 -0
  545. package/dist/knowledge/references/saas.website.primitives.internal-button.md +151 -0
  546. package/dist/knowledge/references/saas.website.primitives.internal-link.md +193 -0
  547. package/dist/knowledge/references/saas.website.primitives.link.md +78 -0
  548. package/dist/knowledge/references/saas.website.primitives.text.md +82 -0
  549. package/dist/knowledge/references/saas.website.refs.page.md +56 -0
  550. package/dist/knowledge/references/saas.website.refs.section.md +57 -0
  551. package/dist/knowledge/references/saas.website.root-config.navigation.md +37 -0
  552. package/dist/knowledge/references/saas.website.root-config.schema.md +192 -0
  553. package/dist/knowledge/references/saas.website.root-config.seo.md +98 -0
  554. package/dist/knowledge/references/saas.website.routing.localized-path.md +84 -0
  555. package/dist/knowledge/references/saas.website.runtime.context.md +174 -0
  556. package/dist/knowledge/references/saas.website.section.component.md +138 -0
  557. package/dist/knowledge/references/saas.website.section.context.md +63 -0
  558. package/dist/knowledge/references/saas.website.sections.category-enum.md +72 -0
  559. package/dist/knowledge/references/saas.website.sections.definition-schema.md +121 -0
  560. package/dist/knowledge/references/saas.website.seo.llms-txt-config.md +37 -0
  561. package/dist/knowledge/references/saas.website.seo.robots-config.md +106 -0
  562. package/dist/knowledge/references/saas.website.seo.sitemap-config.md +73 -0
  563. package/dist/knowledge/references/saas.website.structured-data.payload-shape.md +71 -0
  564. package/dist/knowledge/references/saas.website.use-label-by-key.hook.md +45 -0
  565. package/dist/knowledge/references/saas.website.use-label.hook.md +82 -0
  566. package/dist/knowledge/references/saas.website.use-page.hook.md +30 -0
  567. package/dist/knowledge/references/saas.website.use-runtime.hook.md +36 -0
  568. package/dist/knowledge/references/saas.website.use-section.hook.md +30 -0
  569. package/dist/knowledge/references/saas.website.use-tokens.hook.md +32 -0
  570. package/dist/knowledge/references/vision.authored-metadata.config.md +64 -0
  571. package/dist/knowledge/references/vision.constraint.config.md +66 -0
  572. package/dist/knowledge/references/vision.idea.config.md +45 -0
  573. package/dist/knowledge/references/vision.mission.config.md +46 -0
  574. package/dist/knowledge/references/vision.problem.config.md +51 -0
  575. package/dist/knowledge/references/vision.references.conventions.md +115 -0
  576. package/dist/knowledge/references/vision.snapshot.config.md +85 -0
  577. package/dist/knowledge/references/vision.snapshot.validation.md +226 -0
  578. package/dist/knowledge/references/vision.success-criterion.config.md +60 -0
  579. package/dist/knowledge/references/zod.decorators.chainable-runtime.md +550 -0
  580. package/dist/knowledge/references/zod.decorators.conditional-visibility.md +104 -0
  581. package/dist/knowledge/references/zod.decorators.data-categories.md +197 -0
  582. package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +436 -0
  583. package/dist/knowledge/references/zod.decorators.display-edit-modes.md +174 -0
  584. package/dist/knowledge/references/zod.decorators.enums.frontend-handling.md +101 -0
  585. package/dist/knowledge/references/zod.decorators.field-spec-params.md +317 -0
  586. package/dist/knowledge/references/zod.decorators.file-generation.md +36 -0
  587. package/dist/knowledge/references/zod.decorators.file-rag-source.md +56 -0
  588. package/dist/knowledge/references/zod.decorators.file-schema.md +319 -0
  589. package/dist/knowledge/references/zod.decorators.foreign-key-display-mode.md +83 -0
  590. package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +459 -0
  591. package/dist/knowledge/references/zod.decorators.primitive-ui.md +123 -0
  592. package/dist/knowledge/references/zod.decorators.rag-source.md +164 -0
  593. package/dist/knowledge/references/zod.decorators.schema-metadata.md +122 -0
  594. package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +152 -0
  595. package/dist/knowledge/references/zod.decorators.shared-structural-params.md +314 -0
  596. package/dist/knowledge/references/zod.decorators.structural-lifecycle-params.md +529 -0
  597. package/dist/knowledge/references/zod.factories.bigdecimal.md +155 -0
  598. package/dist/knowledge/references/zod.factories.code.md +127 -0
  599. package/dist/knowledge/references/zod.factories.duration.md +246 -0
  600. package/dist/knowledge/references/zod.factories.money.md +166 -0
  601. package/dist/knowledge/references/zod.factories.phone.md +88 -0
  602. package/dist/knowledge/references/zod.factories.range.md +174 -0
  603. package/dist/knowledge/registries/assurance-authority-bases.json +15 -0
  604. package/dist/knowledge/registries/framework-topics.json +5212 -0
  605. package/dist/knowledge/registries/playbooks.json +488 -0
  606. package/dist/knowledge/registries/source-tags.json +7664 -0
  607. package/dist/knowledge/rules/resource-schema-awareness.md +77 -0
  608. package/dist/knowledge/skills/INDEX.md +349 -0
  609. package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +415 -0
  610. package/dist/knowledge/skills/application-consumer-documentation-authoring/examples/domain-use-case-and-admin-task.example.md +49 -0
  611. package/dist/knowledge/skills/application-consumer-documentation-authoring/references/source-and-ownership-routing.md +52 -0
  612. package/dist/knowledge/skills/application-database-migrations/SKILL.md +218 -0
  613. package/dist/knowledge/skills/application-database-migrations/references/framework-application-database-api.md +84 -0
  614. package/dist/knowledge/skills/application-database-migrations/references/framework-migration-change-risk-api.md +37 -0
  615. package/dist/knowledge/skills/application-database-migrations/references/migration-refusals.md +64 -0
  616. package/dist/knowledge/skills/application-database-migrations/references/postgresql-vs-mongodb-obligations.md +34 -0
  617. package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +323 -0
  618. package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-unit-narrowing-declaration-api.md +84 -0
  619. package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +324 -0
  620. package/dist/knowledge/skills/backend-addon-wiring/references/backend-di-routing.md +7 -0
  621. package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +276 -0
  622. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +374 -0
  623. package/dist/knowledge/skills/backend-custom-operation/references/framework-error-handling-api.md +118 -0
  624. package/dist/knowledge/skills/backend-custom-operation/references/framework-operation-base-and-path-api.md +107 -0
  625. package/dist/knowledge/skills/backend-custom-operation/references/framework-transactional-core-api.md +134 -0
  626. package/dist/knowledge/skills/backend-custom-operation/references/operation-file-conventions.md +10 -0
  627. package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +192 -0
  628. package/dist/knowledge/skills/brand-logo-authoring/references/brand-authoring-decisions.md +55 -0
  629. package/dist/knowledge/skills/brand-logo-authoring/references/framework-brand-asset-api.md +184 -0
  630. package/dist/knowledge/skills/brand-logo-authoring/references/framework-brand-snapshot-api.md +279 -0
  631. package/dist/knowledge/skills/compliance-document-authoring/SKILL.md +346 -0
  632. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-governance.md +160 -0
  633. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +518 -0
  634. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-service-terms.md +158 -0
  635. package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-fact-specification-contract.md +95 -0
  636. package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-publication-contract.md +100 -0
  637. package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +1210 -0
  638. package/dist/knowledge/skills/compliance-document-authoring/references/framework-governed-document-after-drafting.md +40 -0
  639. package/dist/knowledge/skills/config-app-shell/SKILL.md +698 -0
  640. package/dist/knowledge/skills/config-app-shell/references/app-shell-surfaces.md +5 -0
  641. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +415 -0
  642. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-hosted-components-api.md +170 -0
  643. package/dist/knowledge/skills/config-app-shell/references/framework-command-menu-omnibox-api.md +212 -0
  644. package/dist/knowledge/skills/config-app-shell/references/framework-quick-switcher-scope-field-api.md +178 -0
  645. package/dist/knowledge/skills/config-design-system/SKILL.md +424 -0
  646. package/dist/knowledge/skills/config-design-system/references/design-system-file.md +10 -0
  647. package/dist/knowledge/skills/config-design-system/references/framework-design-system-configuration-api.md +77 -0
  648. package/dist/knowledge/skills/config-design-system/references/framework-material-profile-api.md +200 -0
  649. package/dist/knowledge/skills/config-design-system/references/framework-material-runtime-policy-api.md +68 -0
  650. package/dist/knowledge/skills/config-design-system/references/framework-surface-policy-api.md +1212 -0
  651. package/dist/knowledge/skills/config-design-system/references/surface-policy-authoring.md +92 -0
  652. package/dist/knowledge/skills/config-navigation/SKILL.md +249 -0
  653. package/dist/knowledge/skills/config-navigation/references/framework-navigation-layout-api.md +152 -0
  654. package/dist/knowledge/skills/config-navigation/references/navigation-zones.md +5 -0
  655. package/dist/knowledge/skills/config-saas/SKILL.md +209 -0
  656. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +221 -0
  657. package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +408 -0
  658. package/dist/knowledge/skills/config-saas/references/saas-config-scope.md +9 -0
  659. package/dist/knowledge/skills/config-saas-backend/SKILL.md +183 -0
  660. package/dist/knowledge/skills/config-saas-backend/references/framework-backend-authored-config-api.md +40 -0
  661. package/dist/knowledge/skills/configure-billing/SKILL.md +261 -0
  662. package/dist/knowledge/skills/configure-billing/references/config-chain-and-failure-map.md +90 -0
  663. package/dist/knowledge/skills/configure-billing/references/example-backend-provider-module-shape.md +122 -0
  664. package/dist/knowledge/skills/configure-billing/references/example-provider-contribution-and-backend-config.md +48 -0
  665. package/dist/knowledge/skills/configure-billing/references/framework-backend-provider-reachability-api.md +69 -0
  666. package/dist/knowledge/skills/configure-billing/references/framework-billing-resolution-failure-api.md +57 -0
  667. package/dist/knowledge/skills/email-add-template/SKILL.md +439 -0
  668. package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +9 -0
  669. package/dist/knowledge/skills/email-add-template/references/framework-email-template-api.md +72 -0
  670. package/dist/knowledge/skills/email-definition-wiring/SKILL.md +62 -0
  671. package/dist/knowledge/skills/email-labels-authoring/SKILL.md +64 -0
  672. package/dist/knowledge/skills/email-template-authoring/SKILL.md +62 -0
  673. package/dist/knowledge/skills/engine-component-registration/SKILL.md +257 -0
  674. package/dist/knowledge/skills/engine-component-registration/references/component-registration-file.md +7 -0
  675. package/dist/knowledge/skills/engine-component-registration/references/framework-component-registration-api.md +24 -0
  676. package/dist/knowledge/skills/engine-product-definitions/SKILL.md +429 -0
  677. package/dist/knowledge/skills/engine-product-definitions/references/framework-engine-product-definitions-api.md +287 -0
  678. package/dist/knowledge/skills/engine-product-definitions/references/product-registry-scope.md +5 -0
  679. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +491 -0
  680. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +227 -0
  681. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-named-a2a-agents-contract.md +143 -0
  682. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +368 -0
  683. package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +226 -0
  684. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +208 -0
  685. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +286 -0
  686. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +376 -0
  687. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +262 -0
  688. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-invocation-api.md +130 -0
  689. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-prompt-spec-api.md +214 -0
  690. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-operation-and-model-api.md +195 -0
  691. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/operation-key-selection.md +60 -0
  692. package/dist/knowledge/skills/frontend-cdn-publish/SKILL.md +237 -0
  693. package/dist/knowledge/skills/frontend-cdn-publish/references/cloudflare-and-operator-setup.md +56 -0
  694. package/dist/knowledge/skills/frontend-cdn-publish/references/framework-cdn-config-api.md +176 -0
  695. package/dist/knowledge/skills/i18n-label-generation/SKILL.md +261 -0
  696. package/dist/knowledge/skills/i18n-label-generation/references/framework-labelling-sections-api.md +67 -0
  697. package/dist/knowledge/skills/i18n-label-generation/references/label-placement.md +7 -0
  698. package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +269 -0
  699. package/dist/knowledge/skills/i18n-rerun-pipeline/references/framework-labelling-sections-api.md +67 -0
  700. package/dist/knowledge/skills/i18n-rerun-pipeline/references/i18n-routing.md +9 -0
  701. package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +245 -0
  702. package/dist/knowledge/skills/i18n-translation-rerun/references/framework-labelling-sections-api.md +67 -0
  703. package/dist/knowledge/skills/i18n-translation-rerun/references/translation-workflow.md +17 -0
  704. package/dist/knowledge/skills/infra-environment-config/SKILL.md +646 -0
  705. package/dist/knowledge/skills/infra-environment-config/references/framework-application-database-api.md +77 -0
  706. package/dist/knowledge/skills/infra-environment-config/references/framework-backing-services-api.md +282 -0
  707. package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +265 -0
  708. package/dist/knowledge/skills/infra-environment-config/references/infra-config-files.md +7 -0
  709. package/dist/knowledge/skills/journey-approve/SKILL.md +43 -0
  710. package/dist/knowledge/skills/journey-bootstrap-scope/SKILL.md +42 -0
  711. package/dist/knowledge/skills/journey-next/SKILL.md +42 -0
  712. package/dist/knowledge/skills/journey-report/SKILL.md +43 -0
  713. package/dist/knowledge/skills/journey-run/SKILL.md +55 -0
  714. package/dist/knowledge/skills/journey-status/SKILL.md +50 -0
  715. package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +370 -0
  716. package/dist/knowledge/skills/local-environment-bootstrap/references/initialization-recovery-recipe.md +50 -0
  717. package/dist/knowledge/skills/local-environment-bootstrap/references/local-environment-troubleshooting.md +409 -0
  718. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +247 -0
  719. package/dist/knowledge/skills/market-add-feature-benefit/SKILL.md +474 -0
  720. package/dist/knowledge/skills/market-add-feature-benefit/references/framework-feature-benefit-api.md +139 -0
  721. package/dist/knowledge/skills/market-alternatives/SKILL.md +543 -0
  722. package/dist/knowledge/skills/market-authoring-overview/SKILL.md +354 -0
  723. package/dist/knowledge/skills/market-authoring-overview/references/framework-market-references-api.md +138 -0
  724. package/dist/knowledge/skills/market-authoring-overview/references/framework-market-snapshot-api.md +129 -0
  725. package/dist/knowledge/skills/market-category/SKILL.md +290 -0
  726. package/dist/knowledge/skills/market-channels/SKILL.md +361 -0
  727. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +2752 -0
  728. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +2443 -0
  729. package/dist/knowledge/skills/market-generation-cli/SKILL.md +1484 -0
  730. package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +1230 -0
  731. package/dist/knowledge/skills/market-icp/SKILL.md +625 -0
  732. package/dist/knowledge/skills/market-jobs-pains-gains/SKILL.md +352 -0
  733. package/dist/knowledge/skills/market-message-templates-authoring/SKILL.md +415 -0
  734. package/dist/knowledge/skills/market-message-templates-authoring/references/framework-message-template-api.md +1439 -0
  735. package/dist/knowledge/skills/market-persona/SKILL.md +407 -0
  736. package/dist/knowledge/skills/market-positioning-authoring/SKILL.md +392 -0
  737. package/dist/knowledge/skills/market-positioning-authoring/references/framework-positioning-api.md +97 -0
  738. package/dist/knowledge/skills/market-proof-and-objection/SKILL.md +665 -0
  739. package/dist/knowledge/skills/market-scoring-interpretation/SKILL.md +620 -0
  740. package/dist/knowledge/skills/market-scoring-interpretation/references/framework-scoring-api.md +291 -0
  741. package/dist/knowledge/skills/market-snapshot-validation/SKILL.md +1706 -0
  742. package/dist/knowledge/skills/market-snapshot-validation/references/framework-snapshot-validation-api.md +1228 -0
  743. package/dist/knowledge/skills/market-tone-of-voice/SKILL.md +260 -0
  744. package/dist/knowledge/skills/market-triggers-and-journey/SKILL.md +579 -0
  745. package/dist/knowledge/skills/module-companion-exports/SKILL.md +318 -0
  746. package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +544 -0
  747. package/dist/knowledge/skills/module-registration/SKILL.md +212 -0
  748. package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +366 -0
  749. package/dist/knowledge/skills/module-registration/references/registry-files.md +9 -0
  750. package/dist/knowledge/skills/module-relationships/SKILL.md +523 -0
  751. package/dist/knowledge/skills/module-relationships/references/cross-resource-fk-checklist.md +7 -0
  752. package/dist/knowledge/skills/module-relationships/references/framework-resource-relationship-authoring-api.md +738 -0
  753. package/dist/knowledge/skills/pdf-template-authoring/SKILL.md +174 -0
  754. package/dist/knowledge/skills/pdf-template-authoring/references/framework-pdf-template-api.md +203 -0
  755. package/dist/knowledge/skills/pdf-template-authoring/references/framework-pdf-template-spec-api.md +62 -0
  756. package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +239 -0
  757. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-file-provider-constraints-api.md +90 -0
  758. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-module-api.md +50 -0
  759. package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +652 -0
  760. package/dist/knowledge/skills/rate-limit-authoring/references/framework-rate-limit-policy-api.md +182 -0
  761. package/dist/knowledge/skills/rate-limit-authoring/references/scope-key-and-bucket-conventions.md +137 -0
  762. package/dist/knowledge/skills/resource-add-field/SKILL.md +272 -0
  763. package/dist/knowledge/skills/resource-add-field/examples/add-priority-field-to-todos.example.md +153 -0
  764. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +845 -0
  765. package/dist/knowledge/skills/resource-add-module/SKILL.md +322 -0
  766. package/dist/knowledge/skills/resource-add-module/references/framework-new-module-wiring-api.md +67 -0
  767. package/dist/knowledge/skills/resource-add-module/references/module-scaffold-layout.md +15 -0
  768. package/dist/knowledge/skills/resource-add-resource/SKILL.md +222 -0
  769. package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +540 -0
  770. package/dist/knowledge/skills/resource-add-resource/references/scaffold-surfaces-checklist.md +25 -0
  771. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +370 -0
  772. package/dist/knowledge/skills/resource-config-wiring/references/config-change-routing.md +11 -0
  773. package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +622 -0
  774. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-operation-scope-enums-api.md +248 -0
  775. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +1769 -0
  776. package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +1209 -0
  777. package/dist/knowledge/skills/resource-custom-view/SKILL.md +228 -0
  778. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +693 -0
  779. package/dist/knowledge/skills/resource-external-data/SKILL.md +349 -0
  780. package/dist/knowledge/skills/resource-external-data/references/framework-external-data-pipeline-api.md +187 -0
  781. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +261 -0
  782. package/dist/knowledge/skills/resource-external-data/references/lane-selection.md +49 -0
  783. package/dist/knowledge/skills/resource-external-data/references/pipeline-destination-schema.md +43 -0
  784. package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +308 -0
  785. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-named-mcp-servers-contract.md +166 -0
  786. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-resource-mcp-exposure-contract.md +63 -0
  787. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-catalogue-withdrawal-and-verification.md +77 -0
  788. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-client-registration-postures.md +90 -0
  789. package/dist/knowledge/skills/resource-rag-source-fields/SKILL.md +424 -0
  790. package/dist/knowledge/skills/resource-rag-source-fields/references/corpus-field-selection.md +90 -0
  791. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +261 -0
  792. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-file-rag-source-api.md +117 -0
  793. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +597 -0
  794. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-source-decorator-api.md +181 -0
  795. package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +318 -0
  796. package/dist/knowledge/skills/resource-schema-authoring/examples/add-enum-field-with-ui.example.md +132 -0
  797. package/dist/knowledge/skills/resource-schema-authoring/examples/basic-resource-schema.example.md +62 -0
  798. package/dist/knowledge/skills/resource-schema-authoring/references/decorator-layer-map.md +63 -0
  799. package/dist/knowledge/skills/resource-schema-authoring/references/field-type-selection.md +70 -0
  800. package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +559 -0
  801. package/dist/knowledge/skills/resource-schema-authoring/references/framework-personal-data-category-api.md +245 -0
  802. package/dist/knowledge/skills/resource-schema-authoring/references/framework-polymorphic-resources-api.md +147 -0
  803. package/dist/knowledge/skills/resource-schema-authoring/references/framework-schema-family-api.md +247 -0
  804. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +164 -0
  805. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +327 -0
  806. package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +1286 -0
  807. package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +1080 -0
  808. package/dist/knowledge/skills/resource-schema-authoring/references/polymorphic-per-scope-resources.md +75 -0
  809. package/dist/knowledge/skills/resource-schema-authoring/references/schema-variants-and-discriminators.md +62 -0
  810. package/dist/knowledge/skills/resource-schema-authoring/references/shared-layer-decorator-checklist.md +69 -0
  811. package/dist/knowledge/skills/resource-schema-authoring/references/special-factories.md +45 -0
  812. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +389 -0
  813. package/dist/knowledge/skills/resource-ui-behavior/references/framework-conditional-visibility-api.md +106 -0
  814. package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +176 -0
  815. package/dist/knowledge/skills/resource-ui-behavior/references/framework-enum-frontend-handling-api.md +103 -0
  816. package/dist/knowledge/skills/resource-ui-behavior/references/framework-foreign-key-ui-api.md +97 -0
  817. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +839 -0
  818. package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +461 -0
  819. package/dist/knowledge/skills/resource-ui-behavior/references/framework-primitive-ui-api.md +125 -0
  820. package/dist/knowledge/skills/resource-ui-behavior/references/framework-related-resource-embeds-api.md +245 -0
  821. package/dist/knowledge/skills/resource-ui-behavior/references/framework-resource-layout-templates-api.md +302 -0
  822. package/dist/knowledge/skills/resource-ui-behavior/references/ui-layer-boundaries.md +13 -0
  823. package/dist/knowledge/skills/seeding-authoring/SKILL.md +569 -0
  824. package/dist/knowledge/skills/seeding-authoring/references/data-seeding-mode-picker.md +154 -0
  825. package/dist/knowledge/skills/seeding-authoring/references/framework-data-seeding-api.md +176 -0
  826. package/dist/knowledge/skills/seeding-operations/SKILL.md +505 -0
  827. package/dist/knowledge/skills/seeding-operations/references/data-seeding-admin-runbook.md +337 -0
  828. package/dist/knowledge/skills/seeding-operations/references/data-seeding-cron-scheduler.md +171 -0
  829. package/dist/knowledge/skills/seeding-operations/references/framework-data-seeding-operations-api.md +662 -0
  830. package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +134 -0
  831. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +65 -0
  832. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +127 -0
  833. package/dist/knowledge/skills/spec-catalog-authoring/SKILL.md +726 -0
  834. package/dist/knowledge/skills/spec-catalog-authoring/references/catalog-spec-pattern-overview.md +242 -0
  835. package/dist/knowledge/skills/spec-companion-exports/SKILL.md +362 -0
  836. package/dist/knowledge/skills/spec-companion-exports/references/companion-export-checklist.md +8 -0
  837. package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +533 -0
  838. package/dist/knowledge/skills/spec-component-update/SKILL.md +315 -0
  839. package/dist/knowledge/skills/spec-component-update/references/component-spec-props.md +8 -0
  840. package/dist/knowledge/skills/spec-component-update/references/framework-frontend-component-spec-api.md +481 -0
  841. package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +283 -0
  842. package/dist/knowledge/skills/spec-composite-view-update/references/composite-spec-sections.md +5 -0
  843. package/dist/knowledge/skills/spec-composite-view-update/references/framework-composite-view-specification-api.md +51 -0
  844. package/dist/knowledge/skills/spec-family-update/SKILL.md +300 -0
  845. package/dist/knowledge/skills/spec-family-update/references/family-spec-routing.md +13 -0
  846. package/dist/knowledge/skills/spec-family-update/references/framework-error-message-specifications-api.md +108 -0
  847. package/dist/knowledge/skills/spec-family-update/references/framework-family-specifications-api.md +111 -0
  848. package/dist/knowledge/skills/spec-feature-update/SKILL.md +306 -0
  849. package/dist/knowledge/skills/spec-feature-update/references/feature-spec-scope.md +5 -0
  850. package/dist/knowledge/skills/spec-feature-update/references/framework-feature-specification-api.md +95 -0
  851. package/dist/knowledge/skills/spec-resource-update/SKILL.md +220 -0
  852. package/dist/knowledge/skills/spec-resource-update/references/framework-field-spec-params-api.md +319 -0
  853. package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +2610 -0
  854. package/dist/knowledge/skills/spec-resource-update/references/resource-spec-field-routing.md +12 -0
  855. package/dist/knowledge/skills/spec-update-after-change/SKILL.md +195 -0
  856. package/dist/knowledge/skills/spec-update-after-change/references/framework-spec-factory-api.md +173 -0
  857. package/dist/knowledge/skills/spec-update-after-change/references/spec-maintenance-by-surface.md +33 -0
  858. package/dist/knowledge/skills/spec-update-after-change/references/surface-to-spec-routing.md +14 -0
  859. package/dist/knowledge/skills/views-add-composite-view/SKILL.md +259 -0
  860. package/dist/knowledge/skills/views-add-composite-view/references/composite-view-routing.md +10 -0
  861. package/dist/knowledge/skills/views-add-composite-view/references/framework-inserted-view-identity-api.md +151 -0
  862. package/dist/knowledge/skills/views-add-custom-view/SKILL.md +225 -0
  863. package/dist/knowledge/skills/views-add-custom-view/references/custom-view-routing.md +10 -0
  864. package/dist/knowledge/skills/views-add-custom-view/references/framework-view-scope-and-full-custom-api.md +107 -0
  865. package/dist/knowledge/skills/views-app-level/SKILL.md +201 -0
  866. package/dist/knowledge/skills/views-app-level/references/app-level-views-routing.md +9 -0
  867. package/dist/knowledge/skills/views-app-level/references/framework-view-scope-and-full-custom-api.md +107 -0
  868. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +264 -0
  869. package/dist/knowledge/skills/views-chart-authoring/references/chart-view-checklist.md +7 -0
  870. package/dist/knowledge/skills/views-chart-authoring/references/framework-chart-view-contracts-api.md +82 -0
  871. package/dist/knowledge/skills/views-chart-authoring/references/framework-inserted-view-identity-api.md +152 -0
  872. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +302 -0
  873. package/dist/knowledge/skills/views-composite-authoring/references/composite-embedding-checklist.md +23 -0
  874. package/dist/knowledge/skills/views-composite-authoring/references/framework-composite-view-contracts-api.md +133 -0
  875. package/dist/knowledge/skills/views-composite-authoring/references/framework-inserted-view-identity-api.md +152 -0
  876. package/dist/knowledge/skills/views-execution-authoring/SKILL.md +209 -0
  877. package/dist/knowledge/skills/views-execution-authoring/references/execution-view-checklist.md +7 -0
  878. package/dist/knowledge/skills/views-execution-authoring/references/framework-execution-view-contracts-api.md +389 -0
  879. package/dist/knowledge/skills/views-execution-authoring/references/framework-inserted-view-identity-api.md +152 -0
  880. package/dist/knowledge/skills/website-anonymous-session/SKILL.md +444 -0
  881. package/dist/knowledge/skills/website-blog-authoring/SKILL.md +587 -0
  882. package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +1426 -0
  883. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +553 -0
  884. package/dist/knowledge/skills/website-bundle-discipline/references/example-website-button-override.md +52 -0
  885. package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +357 -0
  886. package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +511 -0
  887. package/dist/knowledge/skills/website-factory-advanced/SKILL.md +376 -0
  888. package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +304 -0
  889. package/dist/knowledge/skills/website-label-pack/SKILL.md +390 -0
  890. package/dist/knowledge/skills/website-layout-overrides/SKILL.md +461 -0
  891. package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +264 -0
  892. package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +414 -0
  893. package/dist/knowledge/skills/website-navigation-authoring/references/worked-examples-header-footer.md +366 -0
  894. package/dist/knowledge/skills/website-page-authoring/SKILL.md +420 -0
  895. package/dist/knowledge/skills/website-page-variants/SKILL.md +256 -0
  896. package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +302 -0
  897. package/dist/knowledge/skills/website-section-contact/SKILL.md +950 -0
  898. package/dist/knowledge/skills/website-section-contact/references/define-website-section-api.md +579 -0
  899. package/dist/knowledge/skills/website-section-cta/SKILL.md +822 -0
  900. package/dist/knowledge/skills/website-section-cta/references/define-website-section-api.md +579 -0
  901. package/dist/knowledge/skills/website-section-faq/SKILL.md +917 -0
  902. package/dist/knowledge/skills/website-section-faq/references/define-website-section-api.md +579 -0
  903. package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +878 -0
  904. package/dist/knowledge/skills/website-section-feature-benefit-summary/references/define-website-section-api.md +579 -0
  905. package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +895 -0
  906. package/dist/knowledge/skills/website-section-feature-detail/references/define-website-section-api.md +579 -0
  907. package/dist/knowledge/skills/website-section-footer-cta/SKILL.md +814 -0
  908. package/dist/knowledge/skills/website-section-footer-cta/references/define-website-section-api.md +579 -0
  909. package/dist/knowledge/skills/website-section-hero/SKILL.md +944 -0
  910. package/dist/knowledge/skills/website-section-hero/references/define-website-section-api.md +583 -0
  911. package/dist/knowledge/skills/website-section-pricing/SKILL.md +934 -0
  912. package/dist/knowledge/skills/website-section-pricing/references/define-website-section-api.md +579 -0
  913. package/dist/knowledge/skills/website-section-social-proof/SKILL.md +912 -0
  914. package/dist/knowledge/skills/website-section-social-proof/references/define-website-section-api.md +579 -0
  915. package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +624 -0
  916. package/dist/knowledge/skills/website-seo-aeo-geo/references/aeo-api.md +633 -0
  917. package/dist/knowledge/skills/website-seo-aeo-geo/references/geo-api.md +193 -0
  918. package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +790 -0
  919. package/dist/knowledge/topic-index.json +17510 -0
  920. package/dist/tsconfig.build.tsbuildinfo +1 -0
  921. package/dist/tsconfig.tsbuildinfo +1 -0
  922. package/package.json +49 -0
@@ -0,0 +1,1426 @@
1
+ # Blog Adapter — API contract (source-backed)
2
+
3
+ Source-backed excerpts of the marketing-blog adapter every consumer
4
+ calls when wiring blog posts. Pulled in via the framework-knowledge
5
+ anchor system so the compiled skill always reflects the engine's
6
+ current contract — never a hand-mirrored copy.
7
+
8
+ ## Frontmatter schema
9
+
10
+ The Zod 4 schema every MDX file's frontmatter is validated against
11
+ at render time (Path Z). Field-level rationale (why `title` /
12
+ `summary` are raw strings instead of label keys, why `slug` is
13
+ branded, why `publishedAt` is stored as ISO-string rather than
14
+ `Date`) lives in the JSDoc.
15
+
16
+ ## Import Origins
17
+
18
+ - `@wildo-ai/saas-website`
19
+
20
+ ## Source Excerpts
21
+
22
+ ### Origin Package: `@wildo-ai/saas-website`
23
+
24
+ ```typescript
25
+ *
26
+ * `BlogPostFrontmatter` — the YAML frontmatter contract every blog
27
+ * post MDX file under `examples/<app>/website/src/content/blog/<locale>/`
28
+ * MUST satisfy.
29
+ *
30
+ * **Q16=B context**: blogs are authored as full per-locale MDX files
31
+ * (one MDX per (slug, locale) pair), NOT as label-pack-keyed content.
32
+ * The frontmatter therefore carries strings directly (`title`,
33
+ * `summary`) rather than label keys — there is no shared
34
+ * label-pack-driven authoring surface for blog content. This is
35
+ * intentional: blog copy is long-form and locale-divergent; forcing
36
+ * it through a structural label-pack would either inflate the pack
37
+ * or fragment the prose.
38
+ *
39
+ * **Field rationale**:
40
+ *
41
+ * - `title` — REQUIRED. Renders into `<title>`, `og:title`, and the
42
+ * in-page H1. Authored as a direct string, deliberately.
43
+ * - `summary` — REQUIRED. Renders into `<meta name="description">`,
44
+ * `og:description`, and listing-card descriptions. Direct string.
45
+ * - `slug` — REQUIRED. URL slug (lowercase kebab-case). Brand prevents
46
+ * accidental swap with `WebsitePageRef` (same shape, different role).
47
+ * - `locale` — REQUIRED. The post's locale. Drives the URL prefix
48
+ * (`/<locale>/blog/<slug>`) and `<html lang>`. Cross-locale
49
+ * 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).
52
+ * - `publishedAt` — REQUIRED. ISO-8601 date-time string. Renders into
53
+ * `og:article:published_time` and the listing-card date label.
54
+ * Stored as string (not `z.coerce.date`) because YAML frontmatter
55
+ * parsers preserve the original string and the SEO emitters need
56
+ * the original ISO formatting (no Date.toISOString() round-trip
57
+ * 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.
61
+ * - `tags` — REQUIRED, possibly empty. Lowercase kebab-case tag
62
+ * 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`.
65
+ *
66
+ * **Why a separate file from the page-manifest**: a blog post is NOT
67
+ * a `WebsitePageManifest` (no React `pageComponent` to mount — the
68
+ * MDX file IS the content). The Astro adapter emits one MDX route
69
+ * per post via `content collections`, with `BlogPostFrontmatter`
70
+ * driving the route generation and the SEO emission.
71
+ */
72
+ const _BlogPostSlugSchema = z
73
+ .string()
74
+ .min(1, { error: 'BlogPostSlug must not be empty' })
75
+ .max(96, { error: 'BlogPostSlug must be at most 96 characters' })
76
+ .regex(
77
+ /^[a-z][a-z0-9-]*$/,
78
+ { error: 'BlogPostSlug must be lowercase kebab-case starting with a letter' },
79
+ )
80
+ .brand<'BlogPostSlug'>();
81
+
82
+ export const BlogPostSlugSchema: typeof _BlogPostSlugSchema = _BlogPostSlugSchema;
83
+
84
+ export type BlogPostSlug = z.infer<typeof _BlogPostSlugSchema>;
85
+
86
+ const _BlogAuthorRefSchema = z
87
+ .string()
88
+ .min(1, { error: 'BlogAuthorRef must not be empty' })
89
+ .max(64, { error: 'BlogAuthorRef must be at most 64 characters' })
90
+ .regex(
91
+ /^[a-z][a-z0-9-]*$/,
92
+ { error: 'BlogAuthorRef must be lowercase kebab-case starting with a letter' },
93
+ )
94
+ .brand<'BlogAuthorRef'>();
95
+
96
+ export const BlogAuthorRefSchema: typeof _BlogAuthorRefSchema = _BlogAuthorRefSchema;
97
+
98
+ export type BlogAuthorRef = z.infer<typeof _BlogAuthorRefSchema>;
99
+
100
+ const _BlogPostTagSchema = z
101
+ .string()
102
+ .min(1, { error: 'BlogPostTag must not be empty' })
103
+ .max(48, { error: 'BlogPostTag must be at most 48 characters' })
104
+ .regex(
105
+ /^[a-z][a-z0-9-]*$/,
106
+ { error: 'BlogPostTag must be lowercase kebab-case starting with a letter' },
107
+ )
108
+ .brand<'BlogPostTag'>();
109
+
110
+ export const BlogPostTagSchema: typeof _BlogPostTagSchema = _BlogPostTagSchema;
111
+
112
+ export type BlogPostTag = z.infer<typeof _BlogPostTagSchema>;
113
+
114
+ const _BlogPostFrontmatterSchema = z.object({
115
+ title: z.string().min(1, { error: 'title must not be empty' }).max(200, { error: 'title must be at most 200 characters' }),
116
+ summary: z.string().min(1, { error: 'summary must not be empty' }).max(400, { error: 'summary must be at most 400 characters' }),
117
+ slug: _BlogPostSlugSchema,
118
+ locale: z.enum(AvailableLanguage),
119
+ publishedAt: z.iso.datetime({ error: 'publishedAt must be an ISO-8601 datetime string' }),
120
+ authorRef: _BlogAuthorRefSchema,
121
+ tags: z.array(_BlogPostTagSchema),
122
+ coverImageUrl: z.url({ error: 'coverImageUrl must be a valid URL' }).optional(),
123
+ });
124
+
125
+ export const BlogPostFrontmatterSchema: typeof _BlogPostFrontmatterSchema =
126
+ _BlogPostFrontmatterSchema;
127
+
128
+ export type BlogPostFrontmatter = z.infer<typeof _BlogPostFrontmatterSchema>;
129
+ ```
130
+
131
+ ## `<BlogPost>` — per-post page renderer
132
+
133
+ The single per-post page renderer the framework ships. Strict-
134
+ validates `rawFrontmatter` via `parseBlogPostFrontmatter`, mounts
135
+ `<WebsitePageLayout pageRef={BLOG_POST_PAGE_REF}>`, and wraps the
136
+ MDX body in `<WebsiteMdxProvider>` so embedded business sections can
137
+ read their labels and dispatch analytics through the same hooks
138
+ every other section uses.
139
+
140
+ ## Import Origins
141
+
142
+ - `@wildo-ai/saas-website`
143
+
144
+ ## Source Excerpts
145
+
146
+ ### Origin Package: `@wildo-ai/saas-website`
147
+
148
+ ```tsx
149
+ *
150
+ * `<BlogPost>` — engine-owned per-post page renderer for the marketing
151
+ * blog adapter.
152
+ *
153
+ * # What it does, end-to-end
154
+ *
155
+ * 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
158
+ * through `BlogPostFrontmatterSchema` (Zod 4) — branded `slug` /
159
+ * `authorRef` / `tags`, ISO-8601 `publishedAt`, optional
160
+ * `coverImageUrl`. A failure throws synchronously with a
161
+ * `[blog-post] (source="…")` message; Astro halts the build and
162
+ * points the operator to the offending MDX file.
163
+ * 2. **Renders `<WebsitePageLayout>` with a stable blog-post page
164
+ * 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
167
+ * because the SECTION ref under that page is what's
168
+ * blog-author-controlled (see point 3) — the page-level chrome,
169
+ * label scope, and analytics signal are the same across the entire
170
+ * blog surface.
171
+ * 3. **Wraps the MDX body in `<WebsiteMdxProvider>`.** The consumer
172
+ * passes a `mdxComponents` map (typically containing one or two
173
+ * business-section refs they want available inside post bodies —
174
+ * `<CTASection ref="post-cta" />`, etc.). The provider scopes the
175
+ * map for the duration of the render and ONLY the duration of the
176
+ * render, so two blog posts on the same site can ship different
177
+ * 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.
184
+ *
185
+ * # Why a blog-specific page renderer (vs. the generic page bridge)
186
+ *
187
+ * The `createWebsitePageBridgeIsland` factory takes a `PageComponent`
188
+ * — 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
191
+ * would force the consumer to write a ten-line wrapper per post that
192
+ * imports the MDX module, calls `<MdxBody />`, and re-passes the
193
+ * frontmatter — a cold violation of the "every blog post is one MDX
194
+ * file, period" principle. `<BlogPost>` is the framework's
195
+ * single ten-line wrapper, written once.
196
+ *
197
+ * # Why no per-post `pageRef` / per-section `sectionRef` knobs
198
+ *
199
+ * Two reasons:
200
+ *
201
+ * - **Label-key scope semantics.** A blog post's body has no
202
+ * framework-routed labels (the prose IS in the MDX). The section
203
+ * refs that DO need labels are those an MDX file embeds via the
204
+ * `mdxComponents` map — and those sections were already registered
205
+ * in the consumer's `WEBSITE_SECTIONS` registry with their
206
+ * own `expectedLabelKeys`. Letting blog authors pass arbitrary
207
+ * `sectionRef`s would create unbounded label-key surface area that
208
+ * `assertLabelPacksValid` cannot validate at build start.
209
+ * - **Analytics + chrome consistency.** Marketing teams treat "the
210
+ * blog" as one funnel. A single `pageRef='blog-post'` keeps the
211
+ * `data-website-page-ref` attribute on the layout root constant
212
+ * across every post, so the analytics ingest sees one blog-post
213
+ * page event regardless of slug. Per-post overrides would fragment
214
+ * this without buying any operator value.
215
+ *
216
+ * # Hydration + bundle boundary
217
+ *
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
225
+ * 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
+ */
256
+
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
+
274
+ export interface BlogPostProps {
275
+ /**
276
+ * Raw frontmatter object Astro hands the page from `entry.data` (or
277
+ * equivalent). The renderer validates this through
278
+ * `BlogPostFrontmatterSchema` synchronously — invalid shapes throw
279
+ * with a `[blog-post]`-prefixed message. Pass `entry.data` directly;
280
+ * do NOT pre-parse on the consumer side (the framework owns the
281
+ * validation surface so a future schema change lands in ONE place).
282
+ */
283
+ rawFrontmatter: unknown;
284
+ /**
285
+ * Diagnostic source identifier echoed into validation errors —
286
+ * typically `entry.id` from Astro's content collection (`'en/why-context.mdx'`
287
+ * or similar). Optional but strongly recommended; without it,
288
+ * `parseBlogPostFrontmatter` throws with a generic
289
+ * `[blog-post] Frontmatter failed …` message that does not name the
290
+ * offending file.
291
+ */
292
+ source?: string;
293
+ /**
294
+ * MDX-tag → React-component map made available inside the post
295
+ * body via `<WebsiteMdxProvider>`. Typically a small object literal
296
+ * exporting one or two business sections the consumer wants
297
+ * available everywhere in the blog surface
298
+ * (`<CTASection ref="post-cta" />`, `<NewsletterSignup />`, etc.).
299
+ *
300
+ * Empty maps are valid — a post body using only standard markdown
301
+ * (no embedded React) needs no overrides.
302
+ */
303
+ mdxComponents?: WebsiteMdxComponentsMap;
304
+ /**
305
+ * Per-page chrome overrides forwarded straight into
306
+ * `<WebsitePageLayout>`. `null` suppresses the slot entirely;
307
+ * `undefined` (the default) inherits the runtime navigation
308
+ * config's header/footer components. Most blog posts leave both
309
+ * unset to inherit the site-wide chrome.
310
+ */
311
+ header?: ReactNode | null;
312
+ footer?: ReactNode | null;
313
+ /**
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`.
318
+ */
319
+ children: ReactNode;
320
+ }
321
+
322
+ /**
323
+ * Empty default for `mdxComponents` — defined at module scope (NOT
324
+ * inline in the destructure default) so the object identity is
325
+ * stable across re-renders. Stable identity matters here because
326
+ * `<MDXProvider>`'s internal context value is `useMemo`-derived from
327
+ * the `components` prop; inline `{}` would invalidate every render.
328
+ */
329
+ const EMPTY_MDX_COMPONENTS: WebsiteMdxComponentsMap = Object.freeze({});
330
+
331
+ export function BlogPost(props: BlogPostProps): ReactNode {
332
+ const {
333
+ rawFrontmatter,
334
+ source,
335
+ mdxComponents = EMPTY_MDX_COMPONENTS,
336
+ header,
337
+ footer,
338
+ children,
339
+ } = props;
340
+
341
+ /**
342
+ * Build the diagnostic context once per render. We do not memoize
343
+ * (one object literal per render is cheaper than the `useMemo`
344
+ * accounting), but we also do not pass `source: undefined`
345
+ * unconditionally because `parseBlogPostFrontmatter` switches on
346
+ * `ctx.source !== undefined` for the error-suffix; passing `{}`
347
+ * when undefined keeps the suffix absent in that case.
348
+ */
349
+ const parseCtx: ParseBlogPostFrontmatterContext =
350
+ source !== undefined ? { source } : {};
351
+ const frontmatter = parseBlogPostFrontmatter(rawFrontmatter, parseCtx);
352
+
353
+ /**
354
+ * The hero markup intentionally uses semantic HTML5 elements
355
+ * (`<header>`, `<h1>`, `<time>`, `<address>`) rather than raw
356
+ * `<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.
360
+ */
361
+ return (
362
+ <WebsitePageLayout
363
+ pageRef={BLOG_POST_PAGE_REF}
364
+ header={header}
365
+ footer={footer}
366
+ >
367
+ <article data-website-blog-post-slug={frontmatter.slug as unknown as string}>
368
+ <header>
369
+ {frontmatter.coverImageUrl !== undefined ? (
370
+ <img
371
+ src={frontmatter.coverImageUrl}
372
+ alt=""
373
+ loading="eager"
374
+ data-website-blog-post-cover
375
+ />
376
+ ) : null}
377
+ <h1>{frontmatter.title}</h1>
378
+ <p data-website-blog-post-summary>{frontmatter.summary}</p>
379
+ {/*
380
+ * Meta line is a `<div>`, not a `<p>` — `<address>` is a flow-
381
+ * content element and cannot be a descendant of `<p>` per HTML5
382
+ * (browsers auto-close the `<p>` on `<address>`, which produces
383
+ * a hydration mismatch in React 19). The `<div>` keeps the
384
+ * semantic `<time>` + `<address>` landmarks intact for screen
385
+ * readers + crawlers without violating the parsing rules.
386
+ */}
387
+ <div data-website-blog-post-meta>
388
+ <time dateTime={frontmatter.publishedAt}>
389
+ {frontmatter.publishedAt}
390
+ </time>
391
+ {' · '}
392
+ <address data-website-blog-post-author>
393
+ {frontmatter.authorRef as unknown as string}
394
+ </address>
395
+ </div>
396
+ {frontmatter.tags.length > 0 ? (
397
+ <ul data-website-blog-post-tags>
398
+ {frontmatter.tags.map((tag) => (
399
+ <li key={tag as unknown as string}>
400
+ {tag as unknown as string}
401
+ </li>
402
+ ))}
403
+ </ul>
404
+ ) : null}
405
+ </header>
406
+ <WebsiteMdxProvider components={mdxComponents}>
407
+ {children}
408
+ </WebsiteMdxProvider>
409
+ </article>
410
+ </WebsitePageLayout>
411
+ );
412
+ }
413
+ BlogPost.displayName = 'BlogPost';
414
+
415
+ /**
416
+ * Type alias re-export so consumers writing `BLOG_POST_MDX_COMPONENTS:
417
+ * BlogPostMdxComponents = { … }` have a stable name (the underlying
418
+ * type is the same `WebsiteMdxComponentsMap` from the provider).
419
+ */
420
+ export type BlogPostMdxComponents = WebsiteMdxComponentsMap;
421
+
422
+ /**
423
+ * Convenience type — the Astro `ComponentType` consumers write inline
424
+ * inside a `mdxComponents` map. Re-exported so consumer authoring
425
+ * doesn't need to import from `react` directly.
426
+ */
427
+ export type BlogPostMdxComponent = ComponentType<any>;
428
+ ```
429
+
430
+ ## `<WebsiteMdxProvider>` — `@mdx-js/react` boundary
431
+
432
+ The engine's wrapper around `@mdx-js/react`'s `MDXProvider`. The
433
+ framework owns this boundary so the upstream package can be swapped
434
+ for an alternative without consumer churn (a future migration to
435
+ e.g. `mdx-bundler` would land in this file only).
436
+
437
+ ## Import Origins
438
+
439
+ - `@wildo-ai/saas-website`
440
+
441
+ ## Source Excerpts
442
+
443
+ ### Origin Package: `@wildo-ai/saas-website`
444
+
445
+ ```tsx
446
+ *
447
+ * `WebsiteMdxProvider` — thin wrapper around `@mdx-js/react`'s
448
+ * `MDXProvider` that scopes a consumer-supplied `components` map for
449
+ * the entire MDX subtree it wraps.
450
+ *
451
+ * # Why a framework wrapper at all (vs. consumers using `MDXProvider` directly)
452
+ *
453
+ * Three application-facing reasons:
454
+ *
455
+ * 1. **Single API surface for embedded business sections.** The framework
456
+ * owns the provider boundary so consumers
457
+ * never directly import from `@mdx-js/react` — they ship a single
458
+ * `mdxComponents` object literal and the framework picks the
459
+ * provider implementation. If `@mdx-js/react` ever splits its
460
+ * package or changes its provider semantics (it has shipped
461
+ * breaking changes between major versions before), the swap
462
+ * lands in this file with zero consumer churn.
463
+ * 2. **Bundle-isolation discipline.** `@mdx-js/react` is browser-safe
464
+ * but heavy (`mdx/types.js`, `react-context` propagation). Walling
465
+ * it behind a single re-export keeps the import surface auditable
466
+ * through the package's client-bundle boundary: the `mdx` public entry is
467
+ * checked separately and lists `@mdx-js/react` exactly once.
468
+ * 3. **`disableParentContext: false` (default) is the right default.**
469
+ * MDX 3 lets a nested `MDXProvider` inherit components from the
470
+ * parent provider, which is what we want when the per-blog-post
471
+ * provider sits inside a site-wide MDX provider used by landing-page
472
+ * islands.
473
+ * Pinning the option here makes the framework's posture explicit;
474
+ * a future change documents itself as a breaking framework decision
475
+ * rather than a silent `@mdx-js/react` default flip.
476
+ *
477
+ * # The `components` map shape
478
+ *
479
+ * The map is `Record<string, ComponentType<any>>` — every key is the
480
+ * tag name an MDX file uses (`<CTASection ref="post-cta" />` resolves
481
+ * via the `CTASection` key). Values are React components the consumer
482
+ * authored under their own `src/sections/blog.sections.tsx` and
483
+ * wrapped in `<WebsiteSection sectionRef={…} category={…}>` so the
484
+ * label-key context is established before the section's
485
+ * `useWebsiteLabel(slot)` calls fire. The framework does NOT inspect
486
+ * the shape — discipline lives in the consumer's section registry
487
+ * + the label-pack validation boundary (which proves the locale pack covers
488
+ * each section's expected keys).
489
+ *
490
+ * # Why a `ComponentType<any>` value type and not a stricter generic
491
+ *
492
+ * MDX components receive their own props (children, plus whatever the
493
+ * MDX author writes inline as JSX attributes). The type system cannot
494
+ * narrow this through the provider boundary because the MDX compiler
495
+ * does the routing at compile time. `ComponentType<any>` is the
496
+ * convention `@mdx-js/react` itself uses (`MDXComponents` in
497
+ * `mdx/types.js`) — staying compatible with the upstream type avoids
498
+ * a wrap/unwrap dance at every consumer call site.
499
+ *
500
+ * # Bundle boundary
501
+ *
502
+ * Ships into the React-island bundle (consumed transitively from
503
+ * `BlogPost.tsx` which itself sits behind the consumer's per-page
504
+ * bridge file). MUST stay clear of `node:*` and SSR-tier specifiers
505
+ * — the bundle-isolation test walks `mdx.ts` as one of its entries.
506
+ */
507
+ export interface WebsiteMdxComponentsMap {
508
+ /**
509
+ * Tag-name → component map. The MDX compiler resolves each
510
+ * `<TagName />` in a blog post's body against this object.
511
+ */
512
+ readonly [tagName: string]: ComponentType<any>;
513
+ }
514
+
515
+ export interface WebsiteMdxProviderProps {
516
+ /**
517
+ * Consumer-supplied component overrides. Keys are MDX tag names;
518
+ * values are the React components those tags resolve to.
519
+ */
520
+ components: WebsiteMdxComponentsMap;
521
+ /**
522
+ * MDX subtree (typically the compiled `<MdxBody/>` from a content
523
+ * collection entry). May render any number of provider-scoped
524
+ * components.
525
+ */
526
+ children: ReactNode;
527
+ }
528
+
529
+ export function WebsiteMdxProvider(props: WebsiteMdxProviderProps): ReactNode {
530
+ const { components, children } = props;
531
+ return <MDXProvider components={components}>{children}</MDXProvider>;
532
+ }
533
+ WebsiteMdxProvider.displayName = 'WebsiteMdxProvider';
534
+ ```
535
+
536
+ ## `buildBlogPostCollectionConfig` + `parseBlogPostFrontmatter`
537
+
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
540
+ accepts any frontmatter (passthrough); the strict validation runs
541
+ synchronously at render time inside `<BlogPost>` (and at build time
542
+ inside `getStaticPaths` for typed locale/slug filtering — same
543
+ schema, no double source of truth).
544
+
545
+ ## Import Origins
546
+
547
+ - `@wildo-ai/saas-website`
548
+
549
+ ## Source Excerpts
550
+
551
+ ### Origin Package: `@wildo-ai/saas-website`
552
+
553
+ ```typescript
554
+ *
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
576
+ * during the build, so a malformed frontmatter still surfaces as a
577
+ * 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.
580
+ *
581
+ * # Why the engine ships an opaque shape (rather than the consumer
582
+ * importing the Astro `z` directly)
583
+ *
584
+ * Astro's content-collection API has churned across Astro 4 → 5
585
+ * (loaders moved from string-keyed `type` to a callable `loader`
586
+ * factory; the `glob()` loader's signature changed). Every consumer
587
+ * touching `defineCollection` directly inherits that churn; centralizing
588
+ * the wiring in the engine means the framework absorbs the upgrade
589
+ * cost in ONE place when Astro bumps a major.
590
+ *
591
+ * The shape returned here is `{ schema: <passthrough record> }`. The
592
+ * consumer spreads it into their `defineCollection` call:
593
+ *
594
+ * ```ts
595
+ * // examples/<app>/website/src/content/config.ts
596
+ * import { defineCollection, z } from 'astro:content';
597
+ * import { buildBlogPostCollectionConfig } from '@wildo-ai/saas-website/mdx';
598
+ *
599
+ * export const collections = {
600
+ * blog: defineCollection({
601
+ * type: 'content',
602
+ * ...buildBlogPostCollectionConfig({ astroZ: z }),
603
+ * }),
604
+ * };
605
+ * ```
606
+ *
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.
614
+ *
615
+ * # `parseBlogPostFrontmatter`
616
+ *
617
+ * Companion render-time validator. Called at the top of `<BlogPost>`
618
+ * with the raw `entry.data` Astro hands the page; returns the
619
+ * branded, validated `BlogPostFrontmatter` (Zod 4) or throws with
620
+ * the standard Zod-4 issue formatting + a `[blog-post]` prefix that
621
+ * tells the SSG operator which file to fix.
622
+ *
623
+ * # Boundary
624
+ *
625
+ * This file is React-runtime-safe: it only imports the (also
626
+ * React-safe) `BlogPostFrontmatterSchema` from `schemas/blog/`. It
627
+ * ships into the React-island bundle via the `mdx.ts` barrel, which
628
+ * the bundle-isolation test walks as a dedicated entry. Helpers that
629
+ * parse raw MDX source live in `blog-post-frontmatter-source.ts` so the
630
+ * `yaml` package stays on the build-time/Node side of the boundary.
631
+ */
632
+
633
+ /**
634
+ * Minimal contract for the Astro-side Zod factory we accept. Typed
635
+ * structurally (rather than imported from `astro:content`) so the
636
+ * 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
638
+ * just the `.passthrough()` call we make below.
639
+ */
640
+ export interface AstroZodFactoryShape {
641
+ object: (shape: Record<string, never>) => {
642
+ passthrough: () => unknown;
643
+ };
644
+ }
645
+
646
+ export interface BuildBlogPostCollectionConfigOptions {
647
+ /**
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).
653
+ */
654
+ astroZ: AstroZodFactoryShape;
655
+ }
656
+
657
+ export interface BlogPostCollectionConfigShape {
658
+ /**
659
+ * The schema slot consumed by Astro's `defineCollection({...})`.
660
+ * A `passthrough` record (no field constraints at this layer) so
661
+ * Astro accepts any frontmatter; the strict Zod-4 validation runs
662
+ * at render time inside `<BlogPost>` via
663
+ * `parseBlogPostFrontmatter(...)`.
664
+ */
665
+ schema: unknown;
666
+ }
667
+
668
+ export function buildBlogPostCollectionConfig(
669
+ opts: BuildBlogPostCollectionConfigOptions,
670
+ ): BlogPostCollectionConfigShape {
671
+ const { astroZ } = opts;
672
+ return {
673
+ schema: astroZ.object({}).passthrough(),
674
+ };
675
+ }
676
+
677
+ /**
678
+ * Strict Zod-4 validator for blog-post frontmatter. Called at the top
679
+ * of `<BlogPost>` rendering against `entry.data` (whatever Astro's
680
+ * passthrough collection schema accepted). Throws on validation
681
+ * failure with a `[blog-post]`-prefixed message that points to the
682
+ * offending file via the surrounding render call site.
683
+ *
684
+ * @param raw — the unvalidated frontmatter object Astro supplies
685
+ * (`entry.data` from `getEntry('blog', slug)` or `getCollection('blog')`).
686
+ * @param ctx — diagnostic context appended to the error message so
687
+ * the consumer can find the failing source file when SSG halts.
688
+ * Optional but recommended.
689
+ */
690
+ export interface ParseBlogPostFrontmatterContext {
691
+ /**
692
+ * The MDX file's path or slug. Echoed into the error message when
693
+ * validation fails so the operator can grep for it. Astro typically
694
+ * gives consumers `entry.id` (the slug + extension) — passing it
695
+ * through here is enough for an actionable error.
696
+ */
697
+ readonly source?: string;
698
+ }
699
+
700
+ export function parseBlogPostFrontmatter(
701
+ raw: unknown,
702
+ ctx: ParseBlogPostFrontmatterContext = {},
703
+ ): BlogPostFrontmatter {
704
+ const result = BlogPostFrontmatterSchema.safeParse(raw);
705
+ if (result.success) {
706
+ return result.data;
707
+ }
708
+ const sourceSuffix = ctx.source !== undefined ? ` (source="${ctx.source}")` : '';
709
+ /**
710
+ * Zod 4's `result.error.message` is the JSON-stringified `issues[]` array —
711
+ * long-form, it floods the Astro build log, and the path is what an operator
712
+ * needs to find the broken frontmatter field. `formatZodIssues` is the
713
+ * framework-canonical rendering (one `path: message` per entry); we only own
714
+ * the bullet prefix. Unbounded on purpose: every bad field in a post should
715
+ * be fixable from one build run.
716
+ */
717
+ const issueLines = formatZodIssues(result.error.issues).map((entry) => ` - ${entry}`);
718
+ throw new Error(
719
+ `[blog-post] Frontmatter failed BlogPostFrontmatterSchema validation${sourceSuffix}:\n${issueLines.join('\n')}`,
720
+ );
721
+ }
722
+ ```
723
+
724
+ ## `renderBlogPostHeadHtml` — per-post `<head>` renderer
725
+
726
+ Sibling of `renderWebsitePageHeadHtml`, but reads its title /
727
+ description / OG image / `article:*` metadata from the validated
728
+ `BlogPostFrontmatter` instead of the page manifest's
729
+ `metaLabelKeys`. Emits `og:type=article` + the `article:published_time`
730
+ / `article:author` / `article:tag` (one per tag) block.
731
+
732
+ ## Import Origins
733
+
734
+ - `@wildo-ai/saas-website`
735
+
736
+ ## Source Excerpts
737
+
738
+ ### Origin Package: `@wildo-ai/saas-website`
739
+
740
+ ```typescript
741
+ *
742
+ * `renderBlogPostHeadHtml(opts)` — sibling of `renderWebsitePageHeadHtml`
743
+ * that emits the SEO `<head>` block for an individual blog post,
744
+ * sourcing per-render copy from a validated `BlogPostFrontmatter`
745
+ * instead of the page manifest's `metaLabelKeys`.
746
+ *
747
+ * # Why a separate renderer (not an overload of the page-head renderer)
748
+ *
749
+ * The framework-mindset rule "every type / bucket / field must carry
750
+ * its semantic weight" pushes against overloading
751
+ * `renderWebsitePageHeadHtml` with a "blog-post mode" flag:
752
+ *
753
+ * - The two renderers have STRUCTURALLY different inputs.
754
+ * `renderWebsitePageHeadHtml` reads `manifest.metaLabelKeys.{titleKey,
755
+ * descriptionKey, ogImageUrl}` + the matching `labelPack` lookup;
756
+ * this renderer reads `frontmatter.{title, summary, coverImageUrl,
757
+ * publishedAt, authorRef, tags}` directly — no label-pack
758
+ * dependency at all (blog body copy is per-post, not
759
+ * per-locale-pack, by design).
760
+ * - The two renderers emit DIFFERENT meta surfaces.
761
+ * `og:type=website` vs. `og:type=article`; the article variant
762
+ * additionally emits `article:published_time`,
763
+ * `article:author`, and `article:tag` (one per `frontmatter.tags`
764
+ * entry). Folding both into one helper would require an
765
+ * `articleMeta?: { ... }` discriminated branch that carries no
766
+ * value when called from a non-blog page — exactly the kind of
767
+ * "convenience union" the framework rules forbid.
768
+ * - The blog-post route itself uses a parameterized `routePath`
769
+ * (`/blog/[slug]`) that needs the SLUG substituted at render time
770
+ * to produce the absolute canonical/hreflang URLs. Page-level
771
+ * routes are always literal — keeping the substitution in this
772
+ * renderer (rather than at the manifest layer) means the page
773
+ * manifest stays free of per-render concerns.
774
+ *
775
+ * Both renderers share the exact same hreflang/canonical/OG locale
776
+ * composition logic — duplicating ~30 lines of stable URL composition
777
+ * is the lesser evil compared to threading a generic options bag
778
+ * through both. If a third renderer ever lands (a "campaign-page" or
779
+ * "tag-page" head emitter, say), the right move is to extract a
780
+ * shared `composeHreflangAndCanonical(...)` helper at that point;
781
+ * doing it now would be premature against the YAGNI line.
782
+ *
783
+ * # The `routePath` argument
784
+ *
785
+ * The blog-post page manifest's `routePath` is `/blog/[slug]` (Astro
786
+ * route-parameter syntax). At render time the consumer's `[slug].astro`
787
+ * has already resolved the slug, so we accept the FULLY-SUBSTITUTED
788
+ * locale-neutral path (e.g. `/blog/why-context-beats-content`) here.
789
+ * `buildLocalizedRoutePath` then handles the locale-prefix decision,
790
+ * mirroring how `WebsiteInternalLink` and `renderWebsitePageHeadHtml`
791
+ * handle their own routes — the locale-prefix rule never lives in two
792
+ * places.
793
+ *
794
+ * # Failure modes
795
+ *
796
+ * Throws nothing — all required frontmatter fields are guaranteed by
797
+ * `parseBlogPostFrontmatter` upstream (same Zod 4 schema). The
798
+ * optional `coverImageUrl` is the only branch: when absent, the
799
+ * Twitter card kind degrades to `summary` (text-only) and `og:image`
800
+ * is omitted entirely.
801
+ */
802
+
803
+ export interface RenderBlogPostHeadHtmlOptions {
804
+ /**
805
+ * Composed `WebsiteSiteContext` — the renderer reads
806
+ * `websiteConfig.{defaultLocale, locales, publicOrigin}` for the
807
+ * URL/locale surface and `rootConfig.seo.{siteName}` for the
808
+ * brand fallback. `seo.defaultOgImageUrl` is intentionally NOT
809
+ * consulted: blog posts that ship without a `coverImageUrl` get a
810
+ * smaller-card degradation rather than a generic site-wide image
811
+ * (the default OG image is meaningful for marketing pages but
812
+ * misleading for blog posts).
813
+ */
814
+ siteContext: WebsiteSiteContext;
815
+ /**
816
+ * The locale Astro resolved (with default-locale fallback) for the
817
+ * current request. Drives the `<html lang>` value upstream + the
818
+ * `og:locale` line and the canonical URL's locale-prefix decision.
819
+ */
820
+ locale: AvailableLanguage;
821
+ /**
822
+ * The fully-substituted locale-neutral route path for the post —
823
+ * typically `/blog/<slug>` with `<slug>` already resolved by the
824
+ * consumer's `[slug].astro` `getStaticPaths()`. Passing the
825
+ * substituted path (rather than the parameterized one) keeps the
826
+ * renderer agnostic of the consumer's route-parameter naming.
827
+ */
828
+ routePath: string;
829
+ /**
830
+ * Validated frontmatter — the result of `parseBlogPostFrontmatter`.
831
+ * Carrying the parsed (branded) shape here means an unvalidated
832
+ * `entry.data` cannot reach this renderer accidentally (the
833
+ * branded-type signature would reject a raw `unknown`).
834
+ */
835
+ frontmatter: BlogPostFrontmatter;
836
+ /**
837
+ * AI-training opt-out (D-AG3) — when `true`, the renderer emits
838
+ * `<meta name="robots" content="noai, noimageai">`. The sibling
839
+ * `_headers` entry is produced by `renderBlogPostNoaiHeaders()`
840
+ * (one knob, two channels — see the page-head renderer's
841
+ * companion).
842
+ *
843
+ * **Why a renderer-level option, not a frontmatter field**: the
844
+ * blog-post frontmatter schema (`BlogPostFrontmatterSchema`)
845
+ * doesn't yet expose a per-post AI-opt-out knob — when it does,
846
+ * the consumer's `[slug].astro` will read it from the parsed
847
+ * frontmatter and pass it through here. Keeping the option at
848
+ * the renderer surface NOW means a third-party blog-post catalog
849
+ * (campaigns, customer stories) can opt out without authoring a
850
+ * new frontmatter schema first.
851
+ */
852
+ noaiOptOut?: boolean;
853
+ }
854
+
855
+ export interface BuildBlogPostStructuredDataPayloadOptions {
856
+ frontmatter: BlogPostFrontmatter;
857
+ canonicalUrl: string;
858
+ siteOrigin: string;
859
+ siteName: string;
860
+ locale: AvailableLanguage;
861
+ }
862
+
863
+ export function buildBlogPostStructuredDataPayload(
864
+ opts: BuildBlogPostStructuredDataPayloadOptions,
865
+ ): WebsiteStructuredDataPayload {
866
+ const { frontmatter, canonicalUrl, siteOrigin, siteName, locale } = opts;
867
+ return {
868
+ '@type': 'BlogPosting',
869
+ '@id': `${canonicalUrl}#blog-post`,
870
+ headline: frontmatter.title,
871
+ description: frontmatter.summary,
872
+ datePublished: frontmatter.publishedAt,
873
+ author: {
874
+ '@type': 'Person',
875
+ name: String(frontmatter.authorRef),
876
+ },
877
+ publisher: {
878
+ '@type': 'Organization',
879
+ name: siteName,
880
+ url: siteOrigin,
881
+ },
882
+ mainEntityOfPage: canonicalUrl,
883
+ url: canonicalUrl,
884
+ inLanguage: String(locale),
885
+ ...(frontmatter.coverImageUrl ? { image: frontmatter.coverImageUrl } : {}),
886
+ ...(frontmatter.tags.length > 0 ? { keywords: frontmatter.tags.join(', ') } : {}),
887
+ };
888
+ }
889
+
890
+ export function renderBlogPostHeadHtml(opts: RenderBlogPostHeadHtmlOptions): string {
891
+ const { siteContext, locale, routePath, frontmatter, noaiOptOut } = opts;
892
+ const { rootConfig, websiteConfig } = siteContext;
893
+
894
+ const title = frontmatter.title;
895
+ const description = frontmatter.summary;
896
+ const ogImageUrl = frontmatter.coverImageUrl;
897
+ const titleAttr = escapeHtmlAttribute(title);
898
+ const descriptionAttr = escapeHtmlAttribute(description);
899
+ const titleText = escapeHtmlText(title);
900
+
901
+ const siteOrigin = websiteConfig.publicOrigin;
902
+ const defaultLocale = websiteConfig.defaultLocale;
903
+ const currentLocaleStr = String(locale);
904
+
905
+ /**
906
+ * Same locale-prefix composition rule as `renderWebsitePageHeadHtml`
907
+ * — delegated to the shared `buildLocalizedRoutePath` helper so a
908
+ * future change to the prefix policy lands in ONE place and propagates
909
+ * consistently to internal links + page heads + blog-post heads.
910
+ */
911
+ function buildAbsoluteUrl(forLocale: AvailableLanguage): string {
912
+ const path = buildLocalizedRoutePath({
913
+ locale: forLocale,
914
+ defaultLocale,
915
+ routePath,
916
+ });
917
+ return `${siteOrigin}${path}`;
918
+ }
919
+
920
+ const canonicalUrl = buildAbsoluteUrl(locale);
921
+
922
+ const hreflangLines: string[] = [];
923
+ for (const entry of websiteConfig.locales) {
924
+ const localeStr = String(entry.locale);
925
+ hreflangLines.push(
926
+ `<link rel="alternate" hreflang="${escapeHtmlAttribute(localeStr)}" href="${escapeHtmlAttribute(buildAbsoluteUrl(entry.locale))}" />`,
927
+ );
928
+ }
929
+ hreflangLines.push(
930
+ `<link rel="alternate" hreflang="x-default" href="${escapeHtmlAttribute(buildAbsoluteUrl(defaultLocale))}" />`,
931
+ );
932
+
933
+ const ogImageLines: string[] = [];
934
+ if (ogImageUrl !== undefined) {
935
+ const ogImageAttr = escapeHtmlAttribute(ogImageUrl);
936
+ ogImageLines.push(
937
+ `<meta property="og:image" content="${ogImageAttr}" />`,
938
+ `<meta name="twitter:image" content="${ogImageAttr}" />`,
939
+ );
940
+ }
941
+ const twitterCardKind = ogImageUrl !== undefined ? 'summary_large_image' : 'summary';
942
+
943
+ const ogLocaleAlternateLines: string[] = [];
944
+ for (const entry of websiteConfig.locales) {
945
+ const localeStr = String(entry.locale);
946
+ if (localeStr === currentLocaleStr) continue;
947
+ ogLocaleAlternateLines.push(
948
+ `<meta property="og:locale:alternate" content="${escapeHtmlAttribute(localeStr)}" />`,
949
+ );
950
+ }
951
+
952
+ /**
953
+ * `og:article:*` block — the per-post metadata that distinguishes
954
+ * the blog-post head from the page head. The Open Graph "article"
955
+ * vertical defines:
956
+ * - `article:published_time` (ISO-8601 — already validated by
957
+ * 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).
961
+ * - `article:tag` (one tag per emission; the OG spec uses
962
+ * repeated `<meta property="article:tag">` lines, NOT a
963
+ * comma-joined list).
964
+ *
965
+ * `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.
969
+ */
970
+ const articleMetaLines: string[] = [
971
+ `<meta property="article:published_time" content="${escapeHtmlAttribute(frontmatter.publishedAt)}" />`,
972
+ `<meta property="article:author" content="${escapeHtmlAttribute(frontmatter.authorRef as unknown as string)}" />`,
973
+ ];
974
+ for (const tag of frontmatter.tags) {
975
+ articleMetaLines.push(
976
+ `<meta property="article:tag" content="${escapeHtmlAttribute(tag as unknown as string)}" />`,
977
+ );
978
+ }
979
+
980
+ const siteNameAttr = escapeHtmlAttribute(rootConfig.seo.siteName);
981
+ const canonicalAttr = escapeHtmlAttribute(canonicalUrl);
982
+ const ogLocaleAttr = escapeHtmlAttribute(currentLocaleStr);
983
+ const noaiMetaLines: string[] = [];
984
+ if (noaiOptOut === true) {
985
+ noaiMetaLines.push(`<meta name="robots" content="noai, noimageai" />`);
986
+ }
987
+
988
+ const structuredDataHtml = renderPageStructuredData({
989
+ pagePayloads: [
990
+ buildBlogPostStructuredDataPayload({
991
+ frontmatter,
992
+ canonicalUrl,
993
+ siteOrigin,
994
+ siteName: rootConfig.seo.siteName,
995
+ locale,
996
+ }),
997
+ ],
998
+ });
999
+
1000
+ return [
1001
+ `<title>${titleText}</title>`,
1002
+ `<meta name="description" content="${descriptionAttr}" />`,
1003
+ `<link rel="canonical" href="${canonicalAttr}" />`,
1004
+ `<meta property="og:title" content="${titleAttr}" />`,
1005
+ `<meta property="og:description" content="${descriptionAttr}" />`,
1006
+ `<meta property="og:type" content="article" />`,
1007
+ `<meta property="og:url" content="${canonicalAttr}" />`,
1008
+ `<meta property="og:site_name" content="${siteNameAttr}" />`,
1009
+ `<meta property="og:locale" content="${ogLocaleAttr}" />`,
1010
+ ...ogLocaleAlternateLines,
1011
+ ...ogImageLines,
1012
+ `<meta name="twitter:card" content="${twitterCardKind}" />`,
1013
+ `<meta name="twitter:title" content="${titleAttr}" />`,
1014
+ `<meta name="twitter:description" content="${descriptionAttr}" />`,
1015
+ ...articleMetaLines,
1016
+ ...noaiMetaLines,
1017
+ structuredDataHtml,
1018
+ ...hreflangLines,
1019
+ ].join('\n');
1020
+ }
1021
+ ```
1022
+
1023
+ ## `createWebsiteBlogPostBridgeIsland` — per-locale island factory
1024
+
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
1027
+ encapsulates the entire post tree (BlogPost + MDX body + embedded
1028
+ sections) inside ONE hydration boundary. Closes over the per-locale
1029
+ `slugToMdxBody` map (built from `import.meta.glob`) + the navigation
1030
+ chrome + the MDX-tag → component map; accepts only JSON-serializable
1031
+ primitives as island props.
1032
+
1033
+ ## Import Origins
1034
+
1035
+ - `@wildo-ai/saas-website`
1036
+
1037
+ ## Source Excerpts
1038
+
1039
+ ### Origin Package: `@wildo-ai/saas-website`
1040
+
1041
+ ```tsx
1042
+ *
1043
+ * `createWebsiteBlogPostBridgeIsland(deps)` — factory that returns the
1044
+ * React island a consumer's per-locale `*.bridge.tsx` module exports for
1045
+ * mounting blog post pages. **Sibling** of `createWebsitePageBridgeIsland`
1046
+ * but adapted to the dynamic-routing constraint of the marketing-blog
1047
+ * adapter (Phase 7, D-6 = Option A).
1048
+ *
1049
+ * # Why blog posts cannot reuse the page bridge factory
1050
+ *
1051
+ * Three structural differences between marketing pages and blog posts
1052
+ * forced this dedicated factory shape:
1053
+ *
1054
+ * 1. **Per-slug body resolution.** A marketing page (`landing`,
1055
+ * `pricing`, etc.) has ONE `PageComponent` known at bridge-module
1056
+ * load time — the page bridge closes over it. A blog post's body
1057
+ * is the compiled MDX module, which varies per slug. Closing the
1058
+ * 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").
1060
+ * Instead, the factory closes over a `slugToMdxBody: Record<string,
1061
+ * ComponentType>` map — typically built from
1062
+ * `import.meta.glob('./content/blog/<locale>/*.mdx', { eager: true })`
1063
+ * on the consumer side — and the island accepts the active `slug`
1064
+ * as a primitive (JSON-serializable) prop.
1065
+ *
1066
+ * 2. **Layout already wrapped by `<BlogPost>`.** The page bridge wraps
1067
+ * its `PageComponent` in `<WebsitePageLayout pageRef={…}>`. The
1068
+ * `<BlogPost>` renderer ALREADY wraps its tree in
1069
+ * `<WebsitePageLayout pageRef={BLOG_POST_PAGE_REF}>` (the framework
1070
+ * reserves the page ref for the entire blog surface — see
1071
+ * `BLOG_POST_PAGE_REF` JSDoc in `BlogPost.tsx`). Reusing the page
1072
+ * bridge would double-wrap the layout. This factory instead
1073
+ * provides the runtime context and yields directly to `<BlogPost>`,
1074
+ * which owns the layout boundary itself.
1075
+ *
1076
+ * 3. **Astro's React-children context-propagation gap.** Astro
1077
+ * renders React component children INDEPENDENTLY of the parent
1078
+ * component when the boundary is `.astro` ↔ `.tsx`, even on the
1079
+ * server side. This means
1080
+ * `<BlogPost client:load><Content /></BlogPost>` written in an
1081
+ * `.astro` file would NOT propagate the `<WebsiteMdxProvider>`
1082
+ * context to the React components embedded inside `<Content />`
1083
+ * (the embedded `<CTASection />` would render WITHOUT the engine's
1084
+ * MDX provider scope; the `mdxComponents` map would be ignored).
1085
+ * Confirmed via the Astro docs, `@astrojs/react` integration
1086
+ * readme, and the documented "Bridging two JSX runtimes" gotcha.
1087
+ *
1088
+ * The fix: the entire blog post tree (BlogPost + MDX body +
1089
+ * embedded section components) lives inside ONE React island. The
1090
+ * MDX module is imported as a React component via Astro's
1091
+ * `import.meta.glob`, and the bridge renders it as JSX children
1092
+ * of `<BlogPost>` from INSIDE the island — no `.astro` ↔ `.tsx`
1093
+ * boundary is crossed during the body render.
1094
+ *
1095
+ * # Why hydration is required (vs. pure SSR)
1096
+ *
1097
+ * The `WebsiteRuntimeContextProvider` + `<BlogPost>` tree could in
1098
+ * theory render on the server only (no `client:*` directive). But:
1099
+ *
1100
+ * - Embedded sections (`<CTASection />`) typically have their own
1101
+ * interactivity (analytics handlers, A/B variant flippers, etc.)
1102
+ * that need React event listeners to attach client-side.
1103
+ * - The framework's `useWebsiteLabel(...)` hook chain assumes a live
1104
+ * React render tree — a pure-SSR tree would freeze label resolution
1105
+ * at build time, but any future client-driven label override (e.g.
1106
+ * a debug-mode label inspector) would silently break.
1107
+ *
1108
+ * The factory therefore returns an island that the consumer's `.astro`
1109
+ * mounts with `client:load` (or `client:idle` for posts known to be
1110
+ * non-interactive). The hydration cost is bounded by the per-locale MDX
1111
+ * glob — see "Bundle scaling cliff" below.
1112
+ *
1113
+ * # Bundle scaling cliff (deferred trade-off)
1114
+ *
1115
+ * `import.meta.glob({ eager: true })` materializes EVERY post's
1116
+ * 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.
1120
+ * The factory's API is forward-compatible with `{ eager: false }`
1121
+ * (lazy loaders): swap the consumer's glob to lazy mode and the
1122
+ * `slugToMdxBody[slug]` lookup returns a `() => Promise<{ default:
1123
+ * ComponentType }>`; wrap in `React.lazy()` + `<Suspense>` and the
1124
+ * factory call site stays unchanged. The migration is a consumer-side
1125
+ * change, not an engine API break.
1126
+ *
1127
+ * # Authoring pattern
1128
+ *
1129
+ * **Per-locale bridge file** (consumer side, ONE per locale):
1130
+ *
1131
+ * ```tsx
1132
+ * // examples/<app>/website/src/pages-impl/blog-post-en.bridge.tsx
1133
+ * import type { ComponentType } from 'react';
1134
+ *
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', {
1147
+ * eager: true,
1148
+ * }) as Record<string, { default: ComponentType }>;
1149
+ *
1150
+ * const slugToMdxBody: Record<string, ComponentType> = {};
1151
+ * 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;
1155
+ * }
1156
+ *
1157
+ * export const BlogPostEnBridgeIsland =
1158
+ * createWebsiteBlogPostBridgeIsland({
1159
+ * slugToMdxBody,
1160
+ * navigation: WEBSITE_ROOT_CONFIG.navigation,
1161
+ * mdxComponents: BLOG_POST_MDX_COMPONENTS,
1162
+ * });
1163
+ * ```
1164
+ *
1165
+ * **Per-locale `[slug].astro` shell** (consumer side):
1166
+ *
1167
+ * ```astro
1168
+ * ---
1169
+ * import { getCollection } from 'astro:content';
1170
+ * import {
1171
+ * loadWebsitePageRuntime,
1172
+ * renderBlogPostHeadHtml,
1173
+ * renderWebsiteDesignTokensCss,
1174
+ * } from '@wildo-ai/saas-website/astro';
1175
+ * import { parseBlogPostFrontmatter } from '@wildo-ai/saas-website/mdx';
1176
+ * import { BlogPostEnBridgeIsland } from '@/pages-impl/blog-post-en.bridge';
1177
+ * import { BLOG_POST_PAGE_MANIFEST } from '@/pages-impl/blog-post.page';
1178
+ * import { WEBSITE_SITE_CONTEXT } from '@/website-site-context';
1179
+ *
1180
+ * export async function getStaticPaths() {
1181
+ * const posts = await getCollection('blog');
1182
+ * 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 } }));
1186
+ * }
1187
+ * const { entry } = Astro.props;
1188
+ *
1189
+ * const runtime = loadWebsitePageRuntime({
1190
+ * manifest: BLOG_POST_PAGE_MANIFEST,
1191
+ * siteContext: WEBSITE_SITE_CONTEXT,
1192
+ * labelPacksDir: './src/i18n',
1193
+ * astroLocale: Astro.currentLocale,
1194
+ * });
1195
+ * const frontmatter = parseBlogPostFrontmatter(entry.data, { source: entry.id });
1196
+ * const headHtml = renderBlogPostHeadHtml({
1197
+ * siteContext: WEBSITE_SITE_CONTEXT,
1198
+ * locale: runtime.locale,
1199
+ * routePath: `/blog/${frontmatter.slug}`,
1200
+ * frontmatter,
1201
+ * });
1202
+ * const designTokensCss = renderWebsiteDesignTokensCss(
1203
+ * WEBSITE_SITE_CONTEXT.rootConfig.designTokens,
1204
+ * );
1205
+ * ---
1206
+ * <!doctype html>
1207
+ * <html lang={runtime.locale}>
1208
+ * <head>
1209
+ * <meta charset="UTF-8" />
1210
+ * <meta name="viewport" content="width=device-width,initial-scale=1.0" />
1211
+ * <Fragment set:html={headHtml} />
1212
+ * <style set:html={designTokensCss}></style>
1213
+ * </head>
1214
+ * <body>
1215
+ * <BlogPostEnBridgeIsland
1216
+ * client:load
1217
+ * slug={frontmatter.slug}
1218
+ * rawFrontmatter={entry.data}
1219
+ * source={entry.id}
1220
+ * locale={runtime.locale}
1221
+ * defaultLocale={runtime.defaultLocale}
1222
+ * labelPack={runtime.labelPack}
1223
+ * designTokens={WEBSITE_SITE_CONTEXT.rootConfig.designTokens}
1224
+ * skipToMainContentLabelKey={
1225
+ * WEBSITE_SITE_CONTEXT.rootConfig.skipToMainContentLabelKey
1226
+ * }
1227
+ * />
1228
+ * </body>
1229
+ * </html>
1230
+ * ```
1231
+ *
1232
+ * # Boundary
1233
+ *
1234
+ * Strictly client-bundle-safe (re-exported from `mdx.ts` — NOT from
1235
+ * `astro-island.ts`, because this module hard-imports the MDX adapter
1236
+ * whose `@mdx-js/react` peer is optional; walked by the
1237
+ * bundle-isolation test). MUST stay clear of `node:*` and SSR-tier
1238
+ * specifiers.
1239
+ */
1240
+
1241
+ /**
1242
+ * Module-load-time dependencies — closed over inside the returned
1243
+ * island. NEVER cross the hydration boundary as serialized props.
1244
+ */
1245
+ export interface CreateWebsiteBlogPostBridgeIslandDeps {
1246
+ /**
1247
+ * Per-slug map of compiled MDX bodies (each entry is a React
1248
+ * component — the `.default` export of the MDX module). Typically
1249
+ * built from `import.meta.glob('./content/blog/<locale>/*.mdx',
1250
+ * { eager: true })` with the path-key normalized to the slug. Closed
1251
+ * over at module-load time so the entire MDX body graph for the
1252
+ * locale lands inside ONE React island bundle (D-6 Option A) — this
1253
+ * is the structural fix for Astro's React-children context-propagation
1254
+ * gap (see file preamble).
1255
+ *
1256
+ * The map is read by `slugToMdxBody[props.slug]` at island render
1257
+ * time. A missing slug throws a clear framework-owned error (rather than
1258
+ * rendering an empty body silently); the consumer's `getStaticPaths`
1259
+ * is responsible for not emitting routes for slugs absent from the
1260
+ * map.
1261
+ *
1262
+ * **Why `ComponentType<any>` and not a stricter generic**: matches
1263
+ * the upstream `@mdx-js/react` convention (`MDXContent` from
1264
+ * `mdx/types` is parameterized over an open `MDXProps` shape). MDX
1265
+ * compilation hands the body a compiler-managed props object that
1266
+ * the type system cannot narrow at the framework boundary; using
1267
+ * `<any>` here keeps the consumer's
1268
+ * `import.meta.glob(...) as Record<string, { default: ComponentType }>`
1269
+ * cast assignable without an additional wrap/unwrap. Same posture
1270
+ * as `WebsiteMdxComponentsMap` (intentional symmetry).
1271
+ */
1272
+ slugToMdxBody: Readonly<Record<string, ComponentType<any>>>;
1273
+ /**
1274
+ * Site-wide navigation slot bindings (header / footer components).
1275
+ * Closed over here for the same reason as the page bridge: both
1276
+ * fields are `ComponentType` refs that cannot survive Astro's
1277
+ * serialization boundary.
1278
+ */
1279
+ navigation: WebsiteNavigationConfig;
1280
+ /**
1281
+ * MDX-tag → React-component map forwarded into `<BlogPost>` and
1282
+ * scoped via `<WebsiteMdxProvider>`. Typically a small object
1283
+ * literal exporting the consumer-authored business sections that
1284
+ * blog posts can embed (`<CTASection />`, etc.). Closed over here
1285
+ * (rather than passed as an island prop) because the values are
1286
+ * `ComponentType` refs.
1287
+ */
1288
+ mdxComponents?: WebsiteMdxComponentsMap;
1289
+ }
1290
+
1291
+ /**
1292
+ * Hydration-boundary props — what the consumer's `.astro` page passes
1293
+ * to `<BlogPostEnBridgeIsland client:load ...{primitiveProps}/>`.
1294
+ * Every field is JSON-serializable.
1295
+ */
1296
+ export interface WebsiteBlogPostBridgeIslandProps {
1297
+ /**
1298
+ * Slug of the post being rendered. Used by the island to look up
1299
+ * the matching MDX body in `deps.slugToMdxBody`. Carried as a plain
1300
+ * string (not the branded `BlogPostSlug`) because Astro's
1301
+ * serialization boundary unwraps brands.
1302
+ */
1303
+ slug: string;
1304
+ /**
1305
+ * Raw frontmatter object Astro hands the page from `entry.data`.
1306
+ * Forwarded straight to `<BlogPost>` for strict Zod-4 validation.
1307
+ * The bridge does NOT re-validate (single validation surface, owned
1308
+ * by the renderer).
1309
+ */
1310
+ rawFrontmatter: unknown;
1311
+ /**
1312
+ * Diagnostic source identifier echoed into validation errors —
1313
+ * typically `entry.id` from Astro's content collection. Optional
1314
+ * but recommended for actionable error messages.
1315
+ */
1316
+ source?: string;
1317
+ /** The locale Astro resolved (with default-locale fallback). */
1318
+ locale: AvailableLanguage;
1319
+ /**
1320
+ * The site's default locale. Required for `WebsiteInternalLink`
1321
+ * locale-prefix logic (mirrors the page bridge's `defaultLocale`
1322
+ * island prop).
1323
+ */
1324
+ defaultLocale: AvailableLanguage;
1325
+ /** Already-loaded + already-shape-validated label pack. */
1326
+ labelPack: LabelPack;
1327
+ /** Design-token bundle from `WebsiteRootConfig.designTokens`. */
1328
+ designTokens: WebsiteDesignTokens;
1329
+ /**
1330
+ * Fully-composed label key the framework reads to render the
1331
+ * "Skip to main content" affordance. Mirrors
1332
+ * `WebsiteRootConfig.skipToMainContentLabelKey`. Carried as a
1333
+ * primitive island prop for the same reason as the page bridge.
1334
+ */
1335
+ skipToMainContentLabelKey: WebsiteLabelKey;
1336
+ /** Optional website-facing public providers materialized at build time. */
1337
+ frontendProviders?: FrontendProvidersBlock;
1338
+ }
1339
+
1340
+ const EMPTY_MDX_COMPONENTS: WebsiteMdxComponentsMap = Object.freeze({});
1341
+
1342
+ /**
1343
+ * Returns a FUNCTION component, not the wider `ComponentType` union. The island IS a function
1344
+ * component — Astro hydrates nothing else here — and the union is not callable, so declaring it
1345
+ * cost callers the ability to invoke the island directly (which the bridge suites do, to observe
1346
+ * the synchronous throw for an unregistered slug without routing it through React's reconciler
1347
+ * error path). `FunctionComponent` is assignable to `ComponentType`, so no consumer narrows.
1348
+ */
1349
+ export function createWebsiteBlogPostBridgeIsland(
1350
+ deps: CreateWebsiteBlogPostBridgeIslandDeps,
1351
+ ): FunctionComponent<WebsiteBlogPostBridgeIslandProps> {
1352
+ const {
1353
+ slugToMdxBody,
1354
+ navigation,
1355
+ mdxComponents = EMPTY_MDX_COMPONENTS,
1356
+ } = deps;
1357
+
1358
+ function WebsiteBlogPostBridgeIsland({
1359
+ slug,
1360
+ rawFrontmatter,
1361
+ source,
1362
+ locale,
1363
+ defaultLocale,
1364
+ labelPack,
1365
+ designTokens,
1366
+ skipToMainContentLabelKey,
1367
+ frontendProviders,
1368
+ }: WebsiteBlogPostBridgeIslandProps): ReactNode {
1369
+ const MdxBody = slugToMdxBody[slug];
1370
+ if (MdxBody === undefined) {
1371
+ /**
1372
+ * Loud failure — the consumer's `getStaticPaths` is supposed to
1373
+ * only emit routes for slugs present in the MDX glob. A missing
1374
+ * lookup means the glob and the collection are out of sync; the
1375
+ * operator needs an actionable error string with the offending
1376
+ * slug + the keys that ARE present (truncated to keep the build
1377
+ * log readable).
1378
+ */
1379
+ const knownKeys = Object.keys(slugToMdxBody);
1380
+ const known =
1381
+ knownKeys.length <= 5
1382
+ ? knownKeys.join(', ')
1383
+ : `${knownKeys.slice(0, 5).join(', ')}, … (${knownKeys.length} total)`;
1384
+ throw new Error(
1385
+ `[blog-post-bridge] No MDX body registered for slug="${slug}". ` +
1386
+ `The bridge factory's slugToMdxBody map only knows: ${known}. ` +
1387
+ `Verify the consumer's import.meta.glob('...content/blog/<locale>/*.mdx') ` +
1388
+ `pattern matches the source file naming.`,
1389
+ );
1390
+ }
1391
+
1392
+ const runtimeValue: WebsiteRuntimeContextValue = {
1393
+ locale,
1394
+ defaultLocale,
1395
+ labelPack,
1396
+ designTokens,
1397
+ navigation,
1398
+ skipToMainContentLabelKey,
1399
+ frontendProviderRegistry: createFrontendWebsiteProviderRegistry(frontendProviders),
1400
+ };
1401
+ return (
1402
+ <WebsiteRuntimeContextProvider value={runtimeValue}>
1403
+ <BlogPost
1404
+ rawFrontmatter={rawFrontmatter}
1405
+ source={source}
1406
+ mdxComponents={mdxComponents}
1407
+ >
1408
+ <MdxBody />
1409
+ </BlogPost>
1410
+ </WebsiteRuntimeContextProvider>
1411
+ );
1412
+ }
1413
+ WebsiteBlogPostBridgeIsland.displayName = 'WebsiteBlogPostBridgeIsland';
1414
+
1415
+ return WebsiteBlogPostBridgeIsland;
1416
+ }
1417
+
1418
+ /**
1419
+ * Re-export of the framework-reserved blog-post page ref. Consumers
1420
+ * authoring `BLOG_POST_PAGE_MANIFEST` need this constant to satisfy
1421
+ * the manifest's `ref` field; re-exporting it from the bridge module
1422
+ * means the consumer's per-locale bridge file can grab both symbols
1423
+ * from the one `@wildo-ai/saas-website/mdx` import it already has.
1424
+ */
1425
+ export { BLOG_POST_PAGE_REF };
1426
+ ```