@wildo-ai/framework-knowledge 1.1.8 → 1.1.10

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 (480) hide show
  1. package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
  2. package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
  3. package/dist/claude-marketplace/plugins/wildo/references/acceptance.md +11 -0
  4. package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +9 -2
  5. package/dist/claude-marketplace/plugins/wildo/references/creation-state.md +21 -0
  6. package/dist/claude-marketplace/plugins/wildo/references/derived-artifacts.md +121 -0
  7. package/dist/claude-marketplace/plugins/wildo/references/expert-personas-and-deliberations.md +26 -7
  8. package/dist/claude-marketplace/plugins/wildo/references/runs-judges-and-questions.md +31 -5
  9. package/dist/claude-marketplace/plugins/wildo/skills/accept/SKILL.md +4 -2
  10. package/dist/claude-marketplace/plugins/wildo/skills/answer/SKILL.md +29 -2
  11. package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +69 -24
  12. package/dist/claude-marketplace/plugins/wildo/skills/doctor/SKILL.md +10 -0
  13. package/dist/claude-marketplace/plugins/wildo/skills/run/SKILL.md +21 -5
  14. package/dist/claude-marketplace/plugins/wildo/skills/start/SKILL.md +31 -5
  15. package/dist/claude-marketplace/plugins/wildo/skills/status/SKILL.md +2 -0
  16. package/dist/claude-marketplace/plugins/wildo/skills/why/SKILL.md +20 -4
  17. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  18. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  19. package/dist/esm/framework-knowledge.definitions.js +95 -5
  20. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  21. package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
  22. package/dist/esm/index.d.ts.map +1 -1
  23. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +2 -2
  24. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -1
  25. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +2 -2
  26. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  27. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts +11 -11
  28. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts.map +1 -1
  29. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js +29 -22
  30. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js.map +1 -1
  31. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +41 -3
  32. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -1
  33. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +175 -14
  34. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
  35. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +1 -1
  36. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
  37. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +3 -3
  38. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
  39. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +1 -1
  40. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +1 -1
  41. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -1
  42. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts +8 -4
  43. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts.map +1 -1
  44. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js +13 -6
  45. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js.map +1 -1
  46. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +4 -2
  47. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
  48. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +90 -13
  49. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
  50. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts +4 -3
  51. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts.map +1 -1
  52. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js +4 -3
  53. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js.map +1 -1
  54. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +8 -0
  55. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
  56. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +12 -4
  57. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
  58. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +12 -3
  59. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
  60. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +8 -4
  61. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
  62. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts +4 -1
  63. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts.map +1 -1
  64. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js +2 -1
  65. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js.map +1 -1
  66. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts.map +1 -1
  67. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts.map +1 -1
  68. package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.d.ts.map +1 -1
  69. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts.map +1 -1
  70. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
  71. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +1 -1
  72. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -1
  73. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +13 -1
  74. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
  75. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts.map +1 -1
  76. package/dist/esm/playbooks/refinement.governance-document-candidate/playbook.definition.d.ts.map +1 -1
  77. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +25 -27
  78. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
  79. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +91 -43
  80. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
  81. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts +41 -0
  82. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts.map +1 -0
  83. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js +43 -0
  84. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js.map +1 -0
  85. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts +200 -0
  86. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts.map +1 -0
  87. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js +203 -0
  88. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js.map +1 -0
  89. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts +81 -0
  90. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts.map +1 -0
  91. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js +93 -0
  92. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js.map +1 -0
  93. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +3 -1
  94. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
  95. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +27 -18
  96. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
  97. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
  98. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts +11 -1
  99. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -1
  100. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js +11 -11
  101. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js.map +1 -1
  102. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +2 -0
  103. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -1
  104. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +3 -1
  105. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -1
  106. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  107. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +2 -0
  108. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
  109. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +3 -1
  110. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -1
  111. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -1
  112. package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts +5 -2
  113. package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts.map +1 -1
  114. package/dist/esm/playbooks/top_down.definition/playbook.definition.js +16 -4
  115. package/dist/esm/playbooks/top_down.definition/playbook.definition.js.map +1 -1
  116. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts +27 -6
  117. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts.map +1 -1
  118. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js +32 -12
  119. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js.map +1 -1
  120. package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.d.ts.map +1 -1
  121. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
  122. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  123. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -1
  124. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +2 -1
  125. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
  126. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +13 -5
  127. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
  128. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +7 -3
  129. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
  130. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +71 -2
  131. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
  132. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +2 -1
  133. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
  134. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +23 -8
  135. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
  136. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts +7 -1
  137. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts.map +1 -1
  138. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js +4 -2
  139. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js.map +1 -1
  140. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +9 -3
  141. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
  142. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +3 -3
  143. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -1
  144. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
  145. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +35 -2
  146. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
  147. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +41 -17
  148. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
  149. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  150. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  151. package/dist/knowledge/manifest.json +8 -8
  152. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +22 -7
  153. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +3 -3
  154. package/dist/knowledge/playbooks/bottom_up.build/method.md +17 -15
  155. package/dist/knowledge/playbooks/bottom_up.build/playbook.json +4 -3
  156. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-protocol.json +1 -1
  157. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-treatment.json +1 -1
  158. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +261 -34
  159. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +42 -4
  160. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +188 -59
  161. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +2 -2
  162. package/dist/knowledge/playbooks/bottom_up.build-scale/method.md +169 -276
  163. package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +2 -2
  164. package/dist/knowledge/playbooks/bottom_up.capability-composition/method.md +8 -1
  165. package/dist/knowledge/playbooks/bottom_up.capability-composition/playbook.json +1 -1
  166. package/dist/knowledge/playbooks/bottom_up.conception/method.md +3 -2
  167. package/dist/knowledge/playbooks/bottom_up.conception/playbook.json +11 -3
  168. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-protocol.json +1 -1
  169. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-treatment.json +1 -1
  170. package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +129 -17
  171. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +7 -4
  172. package/dist/knowledge/playbooks/bottom_up.experience-plan/method.md +28 -6
  173. package/dist/knowledge/playbooks/bottom_up.experience-plan/playbook.json +5 -4
  174. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +13 -5
  175. package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +50 -0
  176. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +16 -4
  177. package/dist/knowledge/playbooks/bottom_up.website-plan/method.md +19 -0
  178. package/dist/knowledge/playbooks/bottom_up.website-plan/playbook.json +5 -2
  179. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +7 -3
  180. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  181. package/dist/knowledge/playbooks/refinement.document-facts/method.md +8 -0
  182. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +3 -2
  183. package/dist/knowledge/playbooks/refinement.feature-contribution/method.md +5 -2
  184. package/dist/knowledge/playbooks/refinement.feature-contribution/playbook.json +1 -1
  185. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-protocol.json +1 -1
  186. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-treatment.json +1 -1
  187. package/dist/knowledge/playbooks/top_down.brand-identity/method.md +75 -37
  188. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +35 -38
  189. package/dist/knowledge/playbooks/top_down.brand-name-research/method.md +145 -0
  190. package/dist/knowledge/playbooks/top_down.brand-name-research/playbook.json +57 -0
  191. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-protocol.json +1 -0
  192. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-treatment.json +1 -0
  193. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/method.md +99 -0
  194. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/playbook.json +65 -0
  195. package/dist/knowledge/playbooks/top_down.brand-naming/method.md +56 -0
  196. package/dist/knowledge/playbooks/top_down.brand-naming/playbook.json +76 -0
  197. package/dist/knowledge/playbooks/top_down.business-model/evaluation-protocol.json +1 -1
  198. package/dist/knowledge/playbooks/top_down.business-model/evaluation-treatment.json +1 -1
  199. package/dist/knowledge/playbooks/top_down.business-model/method.md +60 -6
  200. package/dist/knowledge/playbooks/top_down.business-model/playbook.json +15 -10
  201. package/dist/knowledge/playbooks/top_down.capability-map/method.md +10 -9
  202. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +1 -1
  203. package/dist/knowledge/playbooks/top_down.compliance-analysis/playbook.json +30 -10
  204. package/dist/knowledge/playbooks/top_down.compliance-conception/playbook.json +3 -1
  205. package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +4 -1
  206. package/dist/knowledge/playbooks/top_down.definition/method.md +8 -3
  207. package/dist/knowledge/playbooks/top_down.definition/playbook.json +6 -4
  208. package/dist/knowledge/playbooks/top_down.expert-personas/playbook.json +16 -2
  209. package/dist/knowledge/playbooks/top_down.feature-drafts/method.md +5 -2
  210. package/dist/knowledge/playbooks/top_down.feature-drafts/playbook.json +1 -1
  211. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-protocol.json +1 -1
  212. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-treatment.json +1 -1
  213. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +26 -0
  214. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +4 -2
  215. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-protocol.json +1 -1
  216. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-treatment.json +1 -1
  217. package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +11 -1
  218. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-protocol.json +1 -1
  219. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-treatment.json +1 -1
  220. package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +84 -9
  221. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +6 -3
  222. package/dist/knowledge/playbooks/top_down.risk-register/method.md +21 -0
  223. package/dist/knowledge/playbooks/top_down.risk-register/playbook.json +8 -2
  224. package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +4 -2
  225. package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +29 -0
  226. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +58 -17
  227. package/dist/knowledge/references/brand.name-choice.config.md +144 -0
  228. package/dist/knowledge/references/brand.name-screening.config.md +308 -0
  229. package/dist/knowledge/references/build-plan.task-graph.config.md +119 -11
  230. package/dist/knowledge/references/business-model.pricing-plan.config.md +16 -0
  231. package/dist/knowledge/references/business-model.snapshot.config.md +64 -0
  232. package/dist/knowledge/references/business-model.snapshot.validation.md +68 -4
  233. package/dist/knowledge/references/capability-composition.config.md +67 -4
  234. package/dist/knowledge/references/companion.market.prompt-renderer.md +11 -6
  235. package/dist/knowledge/references/example.authorization.application-roles.office-and-field.md +44 -0
  236. package/dist/knowledge/references/example.backend.custom-operation.audit-event.md +81 -0
  237. package/dist/knowledge/references/example.backend.custom-operation.child-line-total.md +258 -0
  238. package/dist/knowledge/references/example.backend.custom-operation.computed-total.md +153 -0
  239. package/dist/knowledge/references/example.backend.custom-operation.create-related-resource.md +107 -0
  240. package/dist/knowledge/references/example.data-seeding.minimal.md +39 -10
  241. package/dist/knowledge/references/example.data-seeding.row-reference.md +80 -0
  242. package/dist/knowledge/references/example.email.template.minimal.md +1 -1
  243. package/dist/knowledge/references/example.resource.config-wiring.retention-policy-operations.md +74 -0
  244. package/dist/knowledge/references/example.resource.personal-data.free-text-field.md +19 -0
  245. package/dist/knowledge/references/example.resource.personal-data.person-without-account.md +27 -0
  246. package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +152 -0
  247. package/dist/knowledge/references/example.resource.ui-behavior.filter-presets.md +15 -0
  248. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -0
  249. package/dist/knowledge/references/example.views.app-level.home-definition.md +13 -0
  250. package/dist/knowledge/references/example.views.chart-definition.shared.md +83 -0
  251. package/dist/knowledge/references/experience-plan.config.md +60 -7
  252. package/dist/knowledge/references/market.context-block.builder.md +1 -1
  253. package/dist/knowledge/references/market.snapshot.validation.md +1 -1
  254. package/dist/knowledge/references/placement-plan.config.md +43 -0
  255. package/dist/knowledge/references/requirements.functional-requirement.config.md +8 -2
  256. package/dist/knowledge/references/requirements.non-functional-requirement.config.md +2 -0
  257. package/dist/knowledge/references/requirements.references.conventions.md +1 -1
  258. package/dist/knowledge/references/requirements.snapshot.config.md +57 -1
  259. package/dist/knowledge/references/requirements.snapshot.validation.md +35 -1
  260. package/dist/knowledge/references/saas.backend.audit-logs.log-event.md +63 -0
  261. package/dist/knowledge/references/saas.backend.document-sequence.issue-in-operation.md +60 -0
  262. package/dist/knowledge/references/saas.backend.document-sequence.raise-floor.md +156 -0
  263. package/dist/knowledge/references/saas.backend.email.send.md +77 -0
  264. package/dist/knowledge/references/saas.backend.notifications.operation-email-template-ref.md +60 -0
  265. package/dist/knowledge/references/saas.data-seeding.bootstrap-wiring.md +7 -1
  266. package/dist/knowledge/references/saas.data-seeding.computed-entry.md +43 -0
  267. package/dist/knowledge/references/saas.data-seeding.definition-input.md +14 -2
  268. package/dist/knowledge/references/saas.data-seeding.row-reference.md +93 -0
  269. package/dist/knowledge/references/saas.frontend.collection-filter-presets.md +124 -0
  270. package/dist/knowledge/references/saas.frontend.launcher.item-refs.md +316 -0
  271. package/dist/knowledge/references/saas.frontend.launcher.merge-rules.md +106 -0
  272. package/dist/knowledge/references/saas.frontend.launcher.runtime-availability.md +60 -0
  273. package/dist/knowledge/references/saas.frontend.resource-label-params.md +52 -0
  274. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +47 -18
  275. package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +4 -1
  276. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destination-roles.md +25 -0
  277. package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +2 -2
  278. package/dist/knowledge/references/saas.models.audit.trail-config.md +45 -0
  279. package/dist/knowledge/references/saas.models.notifications.user-notification-definition.md +5 -3
  280. package/dist/knowledge/references/saas.models.queue.scheduled-recovery.md +81 -2
  281. package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +26 -0
  282. package/dist/knowledge/references/saas.models.roles.definition.md +61 -0
  283. package/dist/knowledge/references/saas.models.roles.organization-defaults.md +97 -0
  284. package/dist/knowledge/references/saas.public-runtime.contract.md +26 -0
  285. package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +10 -0
  286. package/dist/knowledge/references/saas.website.astro.bridge.md +10 -0
  287. package/dist/knowledge/references/saas.website.astro.label-loader.md +12 -0
  288. package/dist/knowledge/references/saas.website.astro.llms-txt-server.md +14 -1
  289. package/dist/knowledge/references/saas.website.astro.site-context.md +13 -0
  290. package/dist/knowledge/references/saas.website.blog.bridge.md +4 -0
  291. package/dist/knowledge/references/saas.website.config.site-context-loader.md +3 -0
  292. package/dist/knowledge/references/saas.website.factories.define-section.md +4 -0
  293. package/dist/knowledge/references/saas.website.legal.public-document-links.md +76 -0
  294. package/dist/knowledge/references/saas.website.page-manifest.schema.md +12 -3
  295. package/dist/knowledge/references/saas.website.page-sections.component.md +72 -0
  296. package/dist/knowledge/references/saas.website.root-config.seo.md +2 -1
  297. package/dist/knowledge/references/saas.website.runtime.context.md +7 -0
  298. package/dist/knowledge/references/saas.website.sections.definition-schema.md +11 -0
  299. package/dist/knowledge/references/saas.website.seo.llms-txt-config.md +2 -0
  300. package/dist/knowledge/references/website-plan.config.md +26 -0
  301. package/dist/knowledge/references/zod.decorators.chainable-runtime.md +13 -0
  302. package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +7 -0
  303. package/dist/knowledge/references/zod.decorators.document-sequence.md +65 -0
  304. package/dist/knowledge/references/zod.decorators.schema-metadata.md +1 -0
  305. package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +21 -0
  306. package/dist/knowledge/references/zod.factories.bigdecimal.md +1 -0
  307. package/dist/knowledge/references/zod.factories.code.md +1 -0
  308. package/dist/knowledge/references/zod.factories.duration.md +1 -0
  309. package/dist/knowledge/references/zod.factories.money.md +1 -0
  310. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  311. package/dist/knowledge/registries/framework-topics.json +374 -1
  312. package/dist/knowledge/registries/playbooks.json +76 -28
  313. package/dist/knowledge/registries/source-tags.json +1513 -898
  314. package/dist/knowledge/rules/live-context-door.md +5 -2
  315. package/dist/knowledge/skills/INDEX.md +5 -2
  316. package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +16 -3
  317. package/dist/knowledge/skills/application-database-migrations/SKILL.md +14 -3
  318. package/dist/knowledge/skills/application-roles-authoring/SKILL.md +158 -0
  319. package/dist/knowledge/skills/application-roles-authoring/references/framework-application-roles-api.md +169 -0
  320. package/dist/knowledge/skills/application-roles-authoring/references/office-and-field-worked-example.md +63 -0
  321. package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +6 -1
  322. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +256 -9
  323. package/dist/knowledge/skills/backend-custom-operation/references/after-the-operation.md +42 -0
  324. package/dist/knowledge/skills/backend-custom-operation/references/framework-audit-log-event-api.md +220 -0
  325. package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +5 -0
  326. package/dist/knowledge/skills/brand-name-screening/SKILL.md +178 -0
  327. package/dist/knowledge/skills/brand-name-screening/references/framework-brand-name-screening-api.md +466 -0
  328. package/dist/knowledge/skills/brand-name-screening/references/screening-procedure.md +87 -0
  329. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +7 -3
  330. package/dist/knowledge/skills/config-app-shell/SKILL.md +58 -5
  331. package/dist/knowledge/skills/config-app-shell/references/framework-launcher-items-api.md +461 -0
  332. package/dist/knowledge/skills/config-app-shell/references/framework-launcher-visibility-api.md +80 -0
  333. package/dist/knowledge/skills/config-design-system/SKILL.md +28 -6
  334. package/dist/knowledge/skills/config-navigation/SKILL.md +14 -3
  335. package/dist/knowledge/skills/config-saas/SKILL.md +56 -15
  336. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +65 -2
  337. package/dist/knowledge/skills/config-saas/references/framework-audit-trail-config-api.md +62 -2
  338. package/dist/knowledge/skills/config-saas/references/framework-background-work-api.md +81 -2
  339. package/dist/knowledge/skills/config-saas-backend/SKILL.md +6 -1
  340. package/dist/knowledge/skills/configure-billing/SKILL.md +18 -4
  341. package/dist/knowledge/skills/email-add-template/SKILL.md +28 -6
  342. package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +1 -1
  343. package/dist/knowledge/skills/email-add-template/references/framework-email-send-api.md +128 -0
  344. package/dist/knowledge/skills/email-add-template/references/framework-operation-email-template-ref-api.md +99 -0
  345. package/dist/knowledge/skills/engine-component-registration/SKILL.md +6 -1
  346. package/dist/knowledge/skills/engine-product-definitions/SKILL.md +21 -8
  347. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +10 -2
  348. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +18 -4
  349. package/dist/knowledge/skills/frontend-component-catalog/SKILL.md +11 -3
  350. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +2 -1
  351. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +8 -0
  352. package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +19 -5
  353. package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +10 -2
  354. package/dist/knowledge/skills/inbound-channels/SKILL.md +2 -2
  355. package/dist/knowledge/skills/infra-environment-config/SKILL.md +6 -1
  356. package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +17 -2
  357. package/dist/knowledge/skills/local-environment-bootstrap/references/derived-artifact-currency.md +122 -0
  358. package/dist/knowledge/skills/local-environment-bootstrap/references/framework-upgrade-and-dependency-alignment.md +11 -0
  359. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +9 -2
  360. package/dist/knowledge/skills/market-add-feature-benefit/SKILL.md +10 -2
  361. package/dist/knowledge/skills/market-alternatives/SKILL.md +10 -2
  362. package/dist/knowledge/skills/market-authoring-overview/SKILL.md +10 -2
  363. package/dist/knowledge/skills/market-category/SKILL.md +21 -7
  364. package/dist/knowledge/skills/market-channels/SKILL.md +6 -1
  365. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +22 -4
  366. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +12 -2
  367. package/dist/knowledge/skills/market-generation-cli/SKILL.md +21 -11
  368. package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +11 -6
  369. package/dist/knowledge/skills/market-icp/SKILL.md +10 -2
  370. package/dist/knowledge/skills/market-jobs-pains-gains/SKILL.md +6 -1
  371. package/dist/knowledge/skills/market-message-templates-authoring/SKILL.md +6 -1
  372. package/dist/knowledge/skills/market-message-templates-authoring/references/framework-message-template-api.md +1 -1
  373. package/dist/knowledge/skills/market-persona/SKILL.md +14 -3
  374. package/dist/knowledge/skills/market-positioning-authoring/SKILL.md +6 -1
  375. package/dist/knowledge/skills/market-proof-and-objection/SKILL.md +10 -2
  376. package/dist/knowledge/skills/market-scoring-interpretation/SKILL.md +6 -1
  377. package/dist/knowledge/skills/market-snapshot-validation/SKILL.md +15 -4
  378. package/dist/knowledge/skills/market-snapshot-validation/references/framework-snapshot-validation-api.md +1 -1
  379. package/dist/knowledge/skills/market-tone-of-voice/SKILL.md +6 -1
  380. package/dist/knowledge/skills/model-cost-attribution/references/framework-work-unit-api.md +26 -0
  381. package/dist/knowledge/skills/module-companion-exports/SKILL.md +7 -1
  382. package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +10 -0
  383. package/dist/knowledge/skills/module-relationships/SKILL.md +37 -8
  384. package/dist/knowledge/skills/pdf-template-authoring/SKILL.md +4 -2
  385. package/dist/knowledge/skills/provider-address-lookup/SKILL.md +14 -3
  386. package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +6 -1
  387. package/dist/knowledge/skills/provider-operation-calls/SKILL.md +14 -3
  388. package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +10 -2
  389. package/dist/knowledge/skills/resource-add-field/SKILL.md +10 -2
  390. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +46 -17
  391. package/dist/knowledge/skills/resource-add-resource/SKILL.md +14 -2
  392. package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +26 -0
  393. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +29 -3
  394. package/dist/knowledge/skills/resource-config-wiring/references/framework-collection-operation-declarations.md +19 -4
  395. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +5 -2
  396. package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +103 -0
  397. package/dist/knowledge/skills/resource-config-wiring/references/framework-retention-policy-operations.md +135 -0
  398. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +26 -0
  399. package/dist/knowledge/skills/resource-config-wiring/references/framework-user-notifications-api.md +26 -7
  400. package/dist/knowledge/skills/resource-custom-view/SKILL.md +10 -2
  401. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +46 -17
  402. package/dist/knowledge/skills/resource-external-data/references/erasure-suppression.md +2 -2
  403. package/dist/knowledge/skills/resource-retention-binding/SKILL.md +5 -1
  404. package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +15 -1
  405. package/dist/knowledge/skills/resource-schema-authoring/references/computed-totals.md +569 -0
  406. package/dist/knowledge/skills/resource-schema-authoring/references/document-numbers.md +358 -0
  407. package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +8 -0
  408. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +21 -0
  409. package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +7 -2
  410. package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +13 -0
  411. package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +153 -0
  412. package/dist/knowledge/skills/resource-status-lifecycle/references/commercial-documents.md +46 -0
  413. package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +198 -0
  414. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +30 -4
  415. package/dist/knowledge/skills/resource-ui-behavior/references/framework-collection-filter-presets-api.md +157 -0
  416. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +101 -19
  417. package/dist/knowledge/skills/seeding-authoring/SKILL.md +202 -39
  418. package/dist/knowledge/skills/seeding-authoring/references/cross-seed-row-references.md +67 -0
  419. package/dist/knowledge/skills/seeding-authoring/references/framework-data-seeding-api.md +154 -4
  420. package/dist/knowledge/skills/seeding-authoring/references/seed-row-overlay.md +22 -0
  421. package/dist/knowledge/skills/seeding-operations/references/framework-data-seeding-operations-api.md +7 -1
  422. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +43 -0
  423. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +2 -2
  424. package/dist/knowledge/skills/spec-companion-exports/SKILL.md +6 -1
  425. package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +10 -0
  426. package/dist/knowledge/skills/spec-component-update/SKILL.md +10 -2
  427. package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +2 -2
  428. package/dist/knowledge/skills/spec-family-update/SKILL.md +71 -66
  429. package/dist/knowledge/skills/spec-family-update/references/family-spec-routing.md +1 -1
  430. package/dist/knowledge/skills/spec-resource-update/SKILL.md +30 -10
  431. package/dist/knowledge/skills/spec-resource-update/references/resource-spec-field-routing.md +28 -0
  432. package/dist/knowledge/skills/spec-update-after-change/SKILL.md +22 -5
  433. package/dist/knowledge/skills/views-add-composite-view/SKILL.md +6 -1
  434. package/dist/knowledge/skills/views-add-custom-view/SKILL.md +10 -2
  435. package/dist/knowledge/skills/views-app-level/SKILL.md +13 -3
  436. package/dist/knowledge/skills/views-app-level/references/application-home.md +56 -0
  437. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +221 -37
  438. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +22 -5
  439. package/dist/knowledge/skills/views-execution-authoring/SKILL.md +1 -1
  440. package/dist/knowledge/skills/website-anonymous-session/SKILL.md +32 -2
  441. package/dist/knowledge/skills/website-blog-authoring/SKILL.md +16 -3
  442. package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +4 -0
  443. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +7 -1
  444. package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +13 -1
  445. package/dist/knowledge/skills/website-factory-advanced/SKILL.md +14 -2
  446. package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +13 -1
  447. package/dist/knowledge/skills/website-layout-overrides/SKILL.md +6 -1
  448. package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +19 -1
  449. package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +55 -18
  450. package/dist/knowledge/skills/website-navigation-authoring/references/framework-public-document-links-api.md +98 -0
  451. package/dist/knowledge/skills/website-navigation-authoring/references/worked-examples-header-footer.md +8 -11
  452. package/dist/knowledge/skills/website-page-authoring/SKILL.md +100 -8
  453. package/dist/knowledge/skills/website-page-authoring/references/framework-site-context-loader-api.md +3 -0
  454. package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +6 -1
  455. package/dist/knowledge/skills/website-section-contact/SKILL.md +15 -0
  456. package/dist/knowledge/skills/website-section-contact/references/define-website-section-api.md +15 -0
  457. package/dist/knowledge/skills/website-section-cta/SKILL.md +15 -0
  458. package/dist/knowledge/skills/website-section-cta/references/define-website-section-api.md +15 -0
  459. package/dist/knowledge/skills/website-section-faq/SKILL.md +21 -1
  460. package/dist/knowledge/skills/website-section-faq/references/define-website-section-api.md +15 -0
  461. package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +21 -1
  462. package/dist/knowledge/skills/website-section-feature-benefit-summary/references/define-website-section-api.md +15 -0
  463. package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +25 -2
  464. package/dist/knowledge/skills/website-section-feature-detail/references/define-website-section-api.md +15 -0
  465. package/dist/knowledge/skills/website-section-footer-cta/SKILL.md +15 -0
  466. package/dist/knowledge/skills/website-section-footer-cta/references/define-website-section-api.md +15 -0
  467. package/dist/knowledge/skills/website-section-hero/SKILL.md +33 -10
  468. package/dist/knowledge/skills/website-section-hero/references/define-website-section-api.md +15 -0
  469. package/dist/knowledge/skills/website-section-pricing/SKILL.md +21 -1
  470. package/dist/knowledge/skills/website-section-pricing/references/define-website-section-api.md +15 -0
  471. package/dist/knowledge/skills/website-section-social-proof/SKILL.md +27 -2
  472. package/dist/knowledge/skills/website-section-social-proof/references/define-website-section-api.md +15 -0
  473. package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +16 -4
  474. package/dist/knowledge/skills/website-seo-aeo-geo/references/aeo-api.md +11 -0
  475. package/dist/knowledge/skills/website-seo-aeo-geo/references/geo-api.md +16 -1
  476. package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +2 -1
  477. package/dist/knowledge/topic-index.json +1590 -292
  478. package/dist/tsconfig.build.tsbuildinfo +1 -1
  479. package/dist/tsconfig.tsbuildinfo +1 -1
  480. package/package.json +4 -4
@@ -0,0 +1,128 @@
1
+ # Sending an email from custom code
2
+
3
+ Read this when an operation must send an email that a `userNotifications` declaration cannot express.
4
+
5
+ ## Declare it first
6
+
7
+ Most business emails are declarations (`resource-config-wiring`, `references/framework-user-notifications-api.md`),
8
+ including two that look as if they need code:
9
+
10
+ | the email | declare |
11
+ |---|---|
12
+ | to a user, or to users chosen by role or relationship | `userNotifications` with a `target` |
13
+ | to somebody who is not a user, at an address held on the record (a customer contact, a lead) | `recipientEmailField` naming that top-level field |
14
+ | that must reach the recipient whatever their preferences | `alwaysDeliver: true` on the entry |
15
+
16
+ A declaration is dispatched by the framework after commit, honours preferences unless told otherwise, and needs no
17
+ code. Send from code only when it cannot express the email:
18
+
19
+ - it carries an **attachment** (a declaration has none);
20
+ - it goes to **several addresses**, or an address in a **nested** field or a list;
21
+ - it needs **cc, bcc, reply-to or threading** headers (a reply in an existing conversation);
22
+ - a recipient who is **not a user** must be written to in **their own language** (`recipientEmailField` sends in the
23
+ application's default locale).
24
+
25
+ A direct send consults no preference. Reaching for it to get around a person's choice to switch an email off is the
26
+ one wrong use.
27
+
28
+ ## How
29
+
30
+ 1. Create the template like any other, under a scanned directory; `send` renders a REGISTERED template by its ref.
31
+ 2. In the custom operation, resolve the service from the factory's container on first use:
32
+ `container.get<EmailBackendService>(SAAS_SERVICE_TYPES.EmailService)`, both from `@wildo-ai/saas-backend-lib`.
33
+ 3. Call it where the change is durable (a postfix without `transactionalCore`, `atTheEnd` with it), so a rolled-back
34
+ operation sends nothing.
35
+ 4. **Wrap it.** `send` throws a typed configuration or validation error (an invalid recipient address, a template
36
+ ref that does not resolve, a configuration the email cannot be sent with). Thrown from `atTheEnd`, that error
37
+ reaches the caller AFTER the change committed, so catch it and decide: log it, or record that the email is owed.
38
+ 5. **Read `outcome`, not only `success`:**
39
+ - `success: false` with `outcome` `ACCEPTANCE_UNKNOWN`: the request reached the provider and the answer was lost.
40
+ The email MAY have been sent; a retry can send it twice.
41
+ - `success: false` with `rejectedRecipients`: the provider accepted the message for some recipients and refused
42
+ others.
43
+ - otherwise `success: false` means it was not sent, and `retryable` says whether trying again may help.
44
+ 6. **Retry with the same `submissionId`.** It names one logical email, so a provider that already accepted it can say
45
+ so instead of sending it twice. A retry that may happen in another process (a minion picking up the work later)
46
+ needs the `submissionId` stored on the row.
47
+
48
+ ## The request and the result
49
+
50
+ `send(request: EmailSendRequest): Promise<EmailSendResult>`. `locale` is an `AvailableLanguage` (from
51
+ `@wildo-ai/presets-components-models`); `context` is the template's variables; `outcome` is an `EmailSubmissionOutcome`, from
52
+ `@wildo-ai/saas-models`.
53
+
54
+ ## Import Origins
55
+
56
+ - `@wildo-ai/saas-backend-lib`
57
+
58
+ ## Source Excerpts
59
+
60
+ ### Origin Package: `@wildo-ai/saas-backend-lib`
61
+
62
+ ```typescript
63
+ /**
64
+ * What `EmailBackendService.send(request)` takes: one email, rendered from a REGISTERED template (`templateRef` is the
65
+ * scanned key, such as `email.quotes.issue.customer`) in one locale. Reach the service from a custom operation through
66
+ * the factory's container: `container.get<EmailBackendService>(SAAS_SERVICE_TYPES.EmailService)`.
67
+ *
68
+ * Unlike a `userNotifications` entry, a direct send consults no recipient preference: the caller decides that this
69
+ * person receives this email. Use it for an email the product owes regardless of preferences (a document the customer
70
+ * asked for); anything a person may switch off belongs in `userNotifications`.
71
+ */
72
+ export interface EmailSendRequest {
73
+ /**
74
+ * Stable identity of one logical provider submission. A caller that can
75
+ * retry across process/job boundaries must persist and reuse this value.
76
+ * Ephemeral callers may omit it and let the service allocate one.
77
+ */
78
+ submissionId?: string;
79
+ /** Template reference (e.g., "system.welcome_email") */
80
+ templateRef: string;
81
+ /** Locale for template selection */
82
+ locale: AvailableLanguage;
83
+ /** Email type for provider routing */
84
+ type: EmailTemplateType;
85
+ /** Primary recipient email(s) */
86
+ to: string | string[];
87
+ /** CC recipients (optional) */
88
+ cc?: string[];
89
+ /** BCC recipients (optional) */
90
+ bcc?: string[];
91
+ /** Reply-to address (optional) */
92
+ replyTo?: string;
93
+ /** From address (optional - uses provider default if not specified) */
94
+ from?: string;
95
+ /** Context for template rendering */
96
+ context: EmailTemplateContext;
97
+ /** File IDs for attachments (optional) */
98
+ attachmentFileIds?: string[];
99
+ /** Organization ID for org-scoped templates (optional) */
100
+ organizationId?: string;
101
+ /**
102
+ * Thread this email as a reply (#1630). Becomes exactly `Message-ID`, `In-Reply-To` and `References` —
103
+ * see {@link EmailThreadingHeaders} for why there is no general headers field.
104
+ */
105
+ threading?: EmailThreadingHeaders;
106
+ }
107
+
108
+ export interface EmailSendResult {
109
+ success: boolean;
110
+ /**
111
+ * Whether an at-least-once caller should retry. An acceptance-unknown retry
112
+ * can duplicate an externally visible email; provider-native idempotency is
113
+ * only an optional risk reduction.
114
+ */
115
+ retryable: boolean;
116
+ submissionId: string;
117
+ outcome: EmailSubmissionOutcome;
118
+ /** All honest provider receipts. Empty means no receipt was returned. */
119
+ providerMessageIds: string[];
120
+ /** Provider confirmed that this logical submission was already accepted. */
121
+ deduplicated?: boolean;
122
+ rejectedRecipients?: Array<{ email: string; reason?: string }>;
123
+ providerId?: string;
124
+ error?: string;
125
+ templateRef: string;
126
+ recipientCount: number;
127
+ }
128
+ ```
@@ -0,0 +1,99 @@
1
+ # The template an operation's email renders
2
+
3
+ Read this when a resource operation declares a `userNotifications` EMAIL entry and you are creating its template,
4
+ or when a startup warning says an operation email's template does not resolve.
5
+
6
+ ## The ref, and the directory it lives in
7
+
8
+ The framework derives the template ref from the operation and the notification entry:
9
+
10
+ `email.<resource>.<operation>[.<variantKey>].<target>[_<customNotificationRef>]`
11
+
12
+ - `<variantKey>` appears only for a variant that declares one. `userNotifications` is declared on the OPERATION and
13
+ the ref is derived per variant, so one EMAIL entry on an operation with a keyed variant needs one template per
14
+ variant: an operation with two EMAIL entries and two variants needs four folders (the last two rows below are two
15
+ of the four for `change_status`).
16
+ - `<target>` is the entry's `target`, lowercased with `_` turned into `-`: `USERS_CUSTOM` becomes `users-custom`.
17
+ - `_<customNotificationRef>` appears only when the entry names one, to tell two emails of the same target apart.
18
+
19
+ The scanner an application ships finds every directory holding a `template` file under the `resources/` directory beside it, at any
20
+ depth, and turns its path into a ref by replacing `/` with `.`. The applications keep one directory per template under
21
+ the resource, named with the rest of the ref, dots included:
22
+
23
+ | operation and entry | template directory |
24
+ |---|---|
25
+ | `tasks` · `assign` · target `USER_SELF` | `resources/tasks/assign.user-self/` |
26
+ | `todos` · `assign` · target `USERS_CUSTOM` | `resources/todos/assign.users-custom/` |
27
+ | `todos` · `change_status` · target `USERS_CUSTOM` · custom ref `notify-creator` | `resources/todos/change_status.users-custom_notify-creator/` |
28
+ | `todos` · `change_status` · variant `admin` · target `USERS_CUSTOM` · custom ref `notify-creator` | `resources/todos/change_status.admin.users-custom_notify-creator/` |
29
+
30
+ A nested spelling (`resources/todos/assign/users-custom/`) scans to the same ref, because `/` and `.` both become
31
+ `.`. Keep to one spelling per application, so a template is found where the next reader looks for it. What never
32
+ works is a directory named after the operation alone (`resources/todos/assign/`) when the entry has a target: the
33
+ target segment is always part of the ref.
34
+
35
+ Startup resolves every declared operation email through the locale chain and names the folder to create when one is
36
+ missing. It REFUSES to start only for an operation with `tokenGeneration` (the email carries the token its flow
37
+ needs). For any other operation it only WARNS, and the email is silently never sent, so read the startup warnings
38
+ after adding an entry: `does not resolve through the configured primary/fallback locale chain` names each missing one.
39
+
40
+ ## The derivation
41
+
42
+ ## Import Origins
43
+
44
+ - `@wildo-ai/saas-backend-lib`
45
+
46
+ ## Source Excerpts
47
+
48
+ ### Origin Package: `@wildo-ai/saas-backend-lib`
49
+
50
+ ```typescript
51
+ /**
52
+ * Canonical template identity for operation-authored email notifications: the template a `userNotifications` EMAIL
53
+ * entry renders.
54
+ *
55
+ * `email.<resource>.<operation>[.<variantKey>].<target>[_<customNotificationRef>]`, where `<target>` is the entry's
56
+ * `target` lowercased with `_` turned into `-` (an engine-internal entry without a target uses its `identifier`). The
57
+ * variant segment is present only for a variant that declares a `variantKey`, and `userNotifications` is declared on
58
+ * the OPERATION, so one entry on an operation with a keyed variant needs one template per variant.
59
+ *
60
+ * With the scanner an application ships (`keyFromPath` turns `/` into `.` under the `resources/` directory beside it), the template's
61
+ * directory is `resources/<resource>/<the rest of the ref, dotted>`: for `todos` / `change_status` / variant `admin` /
62
+ * target `USERS_CUSTOM` / custom ref `notify-assignee` it is
63
+ * `resources/todos/change_status.admin.users-custom_notify-assignee/`.
64
+ *
65
+ * Startup validation and runtime dispatch must use the same derivation;
66
+ * otherwise an application can boot against one template reference and fail
67
+ * only after a mutation commits because delivery derived another.
68
+ */
69
+ export function buildUserNotificationEmailTemplateRef(
70
+ operation: {
71
+ resourceIdentifier: string;
72
+ operationIdentifier: string;
73
+ variantKey?: string;
74
+ },
75
+ notification: {
76
+ identifier: string;
77
+ target?: string;
78
+ customNotificationRef?: string;
79
+ },
80
+ ): string {
81
+ const targetKebab =
82
+ (notification.target || notification.identifier)
83
+ .toLowerCase()
84
+ .replace(/_/g, '-');
85
+ const refParts = [
86
+ 'email',
87
+ operation.resourceIdentifier,
88
+ operation.operationIdentifier,
89
+ ];
90
+ if (operation.variantKey) {
91
+ refParts.push(operation.variantKey);
92
+ }
93
+ refParts.push(targetKebab);
94
+ const baseRef = refParts.join('.');
95
+ return notification.customNotificationRef
96
+ ? `${baseRef}_${notification.customNotificationRef}`
97
+ : baseRef;
98
+ }
99
+ ```
@@ -232,9 +232,14 @@ Run from the app root, substituting `<COMPONENT_REF_CONST>` and
232
232
  | `componentRef` is a top-level constant | `rg -n "^const\s+\w+_COMPONENT_REF\s*=\s*'" frontend/src/engine/component-registrations.frontend.ts` |
233
233
  | Constant is consumed (catch typos at consumer sites) | `rg -n "componentRef:\s+<COMPONENT_REF_CONST>" frontend/src/` |
234
234
  | **No string-literal `componentRef`** in registrations (must be empty) | `rg -n "componentRef:\s+'" frontend/src/engine/component-registrations.frontend.ts` |
235
- | Five framework-default registrars are invoked | `rg -n "registerDefault(Icons\|Presets\|Animations)\|registerBuiltinCommonEnums\|registerFrameworkLayouts" frontend/src/engine/component-registrations.frontend.ts` |
235
+ | Five framework-default registrars are invoked | see the commands below the table |
236
236
  | Lazy `loadComponent` uses `.js` suffix | `rg -n "await import\('\./.*\.js'\)" frontend/src/engine/component-registrations.frontend.ts` |
237
237
 
238
+ ```bash
239
+ # Five framework-default registrars are invoked
240
+ rg -n "registerDefault(Icons|Presets|Animations)|registerBuiltinCommonEnums|registerFrameworkLayouts" frontend/src/engine/component-registrations.frontend.ts
241
+ ```
242
+
238
243
  The high-signal invariant is **"`componentRef` is a top-level
239
244
  constant"** combined with the consumer grep — it's the only
240
245
  mechanism that catches typos at the consumer site at compile time.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: engine-product-definitions
3
- description: Author and maintain engine-level product definition registries — feature identifiers (`ApplicationFeature` enum), feature definitions (`CUSTOM_FEATURE_DEFINITIONS`), feature profiles (`FEATURE_PROFILES`), unavailability policy (`CUSTOM_UNAVAILABILITY_POLICY`), and the parallel role / milestone definition collections. Use when the user says "add a new feature flag", "define a tier profile", "wire an addon-prompt feature", "the feature shows but isn't gated", "add a milestone definition", "register a new role definition", or any change to the runtime product / feature / role / milestone taxonomy that complements the spec layer.
3
+ description: Author and maintain engine-level product definition registries — feature identifiers (`ApplicationFeature` enum), feature definitions (`CUSTOM_FEATURE_DEFINITIONS`), feature profiles (`FEATURE_PROFILES`), unavailability policy (`CUSTOM_UNAVAILABILITY_POLICY`), and the milestone definition collection (application roles are `application-roles-authoring`). Use when the user says "add a new feature flag", "define a tier profile", "wire an addon-prompt feature", "the feature shows but isn't gated", "add a milestone definition", or any change to the runtime product / feature / milestone taxonomy that complements the spec layer.
4
4
  user-invocable: false
5
5
  ---
6
6
 
@@ -47,7 +47,7 @@ roles / milestones the app ships.
47
47
  |--------------------------------------|--------------------------------------------------------------------------------------------|
48
48
  | Feature identifiers + definitions | `shared-lib/src/engine/features.ts` |
49
49
  | Milestone definitions | `shared-lib/src/engine/milestones.ts` |
50
- | Role definitions | `shared-lib/src/engine/roles.ts` (when present) |
50
+ | Role definitions | `shared-lib/src/engine/roles.ts` — see the `application-roles-authoring` skill |
51
51
  | Existing engine module contribution | `shared-lib/src/engine/index.ts` |
52
52
  | Spec parity | `specifications/src/engine/features/**/*.feature.specification.ts` (and family equivalents) |
53
53
  | Runtime consumer (backend) | operation variants declaring `requiredFeatures` |
@@ -68,16 +68,21 @@ roles / milestones the app ships.
68
68
  (`spec-feature-update` / `spec-family-update`)
69
69
  - Resource field semantics → `spec-resource-update`
70
70
  - Backend operation handler logic → `backend-custom-operation`
71
+ - Declaring or enforcing application roles → `application-roles-authoring`
71
72
  - Frontend component slot wiring → `engine-component-registration`
72
73
 
73
74
  ## Workflow
74
75
 
75
76
  ### Step 1: Pick the correct registry
76
77
 
77
- `features.ts` for feature flags / limits, `milestones.ts` for
78
- onboarding / progression milestones, `roles.ts` for app-defined
79
- roles. Each registry follows the same pattern: a typed identifier
80
- enum + a `CUSTOM_*_DEFINITIONS` array + supporting policy maps.
78
+ `features.ts` for feature flags / limits (a typed `ApplicationFeature`
79
+ enum + the `CUSTOM_FEATURE_DEFINITIONS` array + supporting policy maps),
80
+ `milestones.ts` for onboarding / progression milestones
81
+ (`CUSTOM_MILESTONE_DEFINITIONS`). Roles are NOT this pattern: an
82
+ app-defined role is an entry of the `CUSTOM_ROLES_CONFIGURATION`
83
+ record in `roles.ts`, keyed by the role name, and only does something
84
+ once it is offered on an organization type and named on operations —
85
+ follow `application-roles-authoring` for roles and skip the steps below.
81
86
 
82
87
  ### Step 2: Add the identifier to the typed enum
83
88
 
@@ -422,13 +427,21 @@ Run from the app root, substituting `<MEMBER>`:
422
427
  |---------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
423
428
  | Identifiers come from the typed enum | `rg -n "ApplicationFeature\." shared-lib/src/engine/features.ts` |
424
429
  | **No string-literal identifiers in definitions** (must be empty) | `rg -n "defineFeature\('[A-Z_]+'" shared-lib/src/engine/features.ts` |
425
- | Definitions use the typed builder | `rg -n "defineFeature\(\|defineLimitFeature\(" shared-lib/src/engine/features.ts` |
426
- | Every consumption CAP declares `limitSemantic: CEILING` (a cap left on the default FLOOR silently never engages) | `rg -n "defineLimitFeature\(" -A 6 shared-lib/src/engine/features.ts \| rg -n "FEATURES_UNLIMITED" -B 3 \| rg -n "limitSemantic"` |
430
+ | Definitions use the typed builder | see the commands below the table |
431
+ | Every consumption CAP declares `limitSemantic: CEILING` (a cap left on the default FLOOR silently never engages) | see the commands below the table |
427
432
  | Unavailability behavior uses typed enum | `rg -n "behavior:\s+FeatureUnavailabilityBehavior\." shared-lib/src/engine/features.ts` |
428
433
  | **No string-literal behavior** (must be empty) | `rg -n "behavior:\s+'" shared-lib/src/engine/features.ts` |
429
434
  | Profile entries reference enum members | `rg -n "ApplicationFeature\.<MEMBER>" shared-lib/src/engine/features.ts` |
430
435
  | Spec exists for new identifier | `rg -n "<MEMBER>" specifications/src/engine/features/` |
431
436
 
437
+ ```bash
438
+ # Definitions use the typed builder
439
+ rg -n "defineFeature\(|defineLimitFeature\(" shared-lib/src/engine/features.ts
440
+
441
+ # Every consumption CAP declares `limitSemantic: CEILING` (a cap left on the default FLOOR silently never engages)
442
+ rg -n "defineLimitFeature\(" -A 6 shared-lib/src/engine/features.ts | rg -n "FEATURES_UNLIMITED" -B 3 | rg -n "limitSemantic"
443
+ ```
444
+
432
445
  Verify identifier → definition → module registration → grant → backend enforcement → frontend presentation → specification. A declared or documented feature alone neither grants access nor protects an operation.
433
446
 
434
447
  ## Common Rationalizations
@@ -360,9 +360,17 @@ export const moduleBackend_FlowsActorsRegistry: {
360
360
 
361
361
  | Check | Command |
362
362
  |---|---|
363
- | functionRefs ↔ functionTools | `rg "functionRefs|resourceReadTool|functionRef:" backend-api/src/modules/*/addons/flows-actors` |
363
+ | functionRefs ↔ functionTools | see the commands below the table |
364
364
  | system is frontend-visible | `rg "visibility:\s*FlowActorSystem_Visibility.FRONTEND" backend-api/src/modules` |
365
- | view ↔ system ↔ launcher refs align | `rg "systemRef|viewRef:|ref:\s*'" frontend/src/modules/*/app-level-views frontend/src/modules/*/app-shell.module.frontend.ts` |
365
+ | view ↔ system ↔ launcher refs align | see the commands below the table |
366
+
367
+ ```bash
368
+ # functionRefs ↔ functionTools
369
+ rg "functionRefs|resourceReadTool|functionRef:" backend-api/src/modules/*/addons/flows-actors
370
+
371
+ # view ↔ system ↔ launcher refs align
372
+ rg "systemRef|viewRef:|ref:\s*'" frontend/src/modules/*/app-level-views frontend/src/modules/*/app-shell.module.frontend.ts
373
+ ```
366
374
 
367
375
  ## Common Rationalizations
368
376
 
@@ -327,10 +327,24 @@ Run from the app root, substituting `<module>`:
327
327
  | Agent is registered, not just declared | `rg -n "agents:\s*\[" backend-api/src/modules/<module>/addons/flows-actors` |
328
328
  | Operation key agrees across config + operationDefinition | `rg -n "operationKey:" backend-api/src/modules/<module>/addons/flows-actors` |
329
329
  | Every structured agent's callers pass a schema | `rg -n -U "GENERATE_STRUCTURED[\s\S]{0,400}schema:" backend-api/src` |
330
- | Output is unwrapped, not used bare | `rg -n "invokeAgent\(" -A 4 backend-api/src \| rg "\.output"` |
331
- | **No tools on a one-shot agent** (should be empty) | `rg -n -U "GENERATE_(TEXT\|STRUCTURED)[\s\S]{0,600}functionRefs" backend-api/src` |
332
- | **No hand-rolled provider SDK call** (should be empty) | `rg -n "@ai-sdk/\|new Anthropic\(\|new OpenAI\(" backend-api/src` |
333
- | **No API key read in app code** (should be empty) | `rg -n "ANTHROPIC_API_KEY\|OPENAI_API_KEY" backend-api/src` |
330
+ | Output is unwrapped, not used bare | see the commands below the table |
331
+ | **No tools on a one-shot agent** (should be empty) | see the commands below the table |
332
+ | **No hand-rolled provider SDK call** (should be empty) | see the commands below the table |
333
+ | **No API key read in app code** (should be empty) | see the commands below the table |
334
+
335
+ ```bash
336
+ # Output is unwrapped, not used bare
337
+ rg -n "invokeAgent\(" -A 4 backend-api/src | rg "\.output"
338
+
339
+ # No tools on a one-shot agent (should be empty)
340
+ rg -n -U "GENERATE_(TEXT|STRUCTURED)[\s\S]{0,600}functionRefs" backend-api/src
341
+
342
+ # No hand-rolled provider SDK call (should be empty)
343
+ rg -n "@ai-sdk/|new Anthropic\(|new OpenAI\(" backend-api/src
344
+
345
+ # No API key read in app code (should be empty)
346
+ rg -n "ANTHROPIC_API_KEY|OPENAI_API_KEY" backend-api/src
347
+ ```
334
348
 
335
349
  ## Common Rationalizations
336
350
 
@@ -169,10 +169,18 @@ Run from the app root, substituting `<View>` for the view's file:
169
169
  |---|---|
170
170
  | The view imports framework components | `rg -n "from '@wildo-ai/saas-frontend-lib'" <View>` |
171
171
  | No deep import into the frontend library | `rg -n "@wildo-ai/saas-frontend-lib/" <View>` |
172
- | No hand-written colour | `rg -n "#[0-9a-fA-F]{3,8}\b\|rgba?\(" <View>` |
173
- | No hand-written surface treatment | `rg -n "className=\"[^\"]*(border\|rounded\|shadow\|bg-)" <View>` |
172
+ | No hand-written colour | see the commands below the table |
173
+ | No hand-written surface treatment | see the commands below the table |
174
174
  | No unexplained `preset` pass-through | `rg -n "preset=" <View>` |
175
175
 
176
+ ```bash
177
+ # No hand-written colour
178
+ rg -n "#[0-9a-fA-F]{3,8}\b|rgba?\(" <View>
179
+
180
+ # No hand-written surface treatment
181
+ rg -n "className=\"[^\"]*(border|rounded|shadow|bg-)" <View>
182
+ ```
183
+
176
184
  The second through fifth greps should return zero matches in a finished view.
177
185
  The second is not a judgement call — a deep import into the library is forbidden
178
186
  outright; the rest are lines to re-check against step 5, not automatic defects.
@@ -219,7 +227,7 @@ once you have a candidate.
219
227
  - **Ai Elements / Meta** (7) — `AI_AgentCapabilities`, `AI_AgentCard`, `AI_AgentList`, `AI_AgentPromptSpec`, `AI_Context`, `AI_ModelSelector`, `AI_OpenInChat`
220
228
  - **Ai Elements / Shared** (2) — `AI_Loader`, `AI_Shimmer`
221
229
  - **Ai Elements / Trace** (5) — `AI_ChainOfThought`, `AI_Checkpoint`, `AI_InlineCitation`, `AI_Plan`, `AI_Reasoning`
222
- - **App** (10) — `AppLayout_ConsentGate`, `AppLayout_DocumentAcceptanceGate`, `AppLayout_ErrorBoundary`, `AppLayout_Home`, `AppLayout_MainContainer`, `AppLayout_RouterErrorBoundary`, `Files_UploadGrantDrop`, `PublicLayout_MainContainer`, `PublicLayout_StaticContentContainer`, `PublicLayout_Terms`
230
+ - **App** (11) — `AppLayout_ConsentGate`, `AppLayout_DocumentAcceptanceGate`, `AppLayout_ErrorBoundary`, `AppLayout_Home`, `AppLayout_MainContainer`, `AppLayout_RouterErrorBoundary`, `Files_UploadGrantDrop`, `PublicLayout_LegalNotice`, `PublicLayout_MainContainer`, `PublicLayout_StaticContentContainer`, `PublicLayout_Terms`
223
231
  - **Auth** (14) — `Auth_AuthCallback`, `Auth_ConfirmEmail`, `Auth_EnrollmentRequired`, `Auth_Invitation`, `Auth_MagicLinkVerify`, `Auth_Main`, `Auth_MfaChallenge`, `Auth_OAuthConsent`, `Auth_OAuthLoggedOut`, `Auth_OAuthLogoutConfirm`, `Auth_OneOffSession`, `Auth_OrganizationOnboarding`, `Auth_PasswordLost`, `Auth_Register`
224
232
  - **Billing** (6) — `BillingPortalLink`, `InvoiceHistory`, `PlanChangePreview`, `PricingTable`, `SubscriptionStatus`, `UsageDashboard`
225
233
  - **Data Display** (10) — `Avatar`, `Badge`, `DescriptionDetails`, `DescriptionList`, `DescriptionTerm`, `Duration`, `Identifier`, `Kbd`, `NotificationIndicator`, `Timeline`
@@ -114,7 +114,7 @@ an application reaches those through configuration, never through JSX.
114
114
  | `AI_Plan` | Card + collapsible composition for structured plans. | Use when agents emit explicit multi-step plans. | Avoid for unstructured prose-only replies. |
115
115
  | `AI_Reasoning` | Collapsible content area with streaming-friendly layout. | Use when showing model reasoning separate from final answer. | Avoid when reasoning must not be displayed. |
116
116
 
117
- ## App (10)
117
+ ## App (11)
118
118
 
119
119
  | Component | Renders | Use when | Avoid when |
120
120
  | --- | --- | --- | --- |
@@ -125,6 +125,7 @@ an application reaches those through configuration, never through JSX.
125
125
  | `AppLayout_MainContainer` | Root layout preset wiring `useAppShellLayout` with sidebar, toolbars, overlays, and loading gates. | Use as the top-level wrapper for signed-in SaaS experiences. | Avoid for marketing or auth-only public pages — use `PUBLIC_LAYOUTS_MAIN_CONTAINER`. |
126
126
  | `AppLayout_RouterErrorBoundary` | ErrorDisplay presets for 404/403/5xx, application crashes, and unknown failures. | Use at the router boundary wrapping navigable content. | Avoid for isolated component errors — use `APP_LAYOUTS_ERROR_BOUNDARY`. |
127
127
  | `Files_UploadGrantDrop` | Focused public shell — the target field and its constraints, one file chooser, one upload, then a terminal state (received, already used, expired, cancelled). | Reached only through a grant’s `uploadPageUrl`. It is the fallback for an assistant host that cannot perform the upload itself; a host that can run a command uses the grant’s curl example instead. | Never as a general upload surface — authenticated uploads go through the resource file fields, and nothing on this page is reachable without a grant token. |
128
+ | `PublicLayout_LegalNotice` | Public legal layout listing the legal name, establishment address and contact always, marking any of those three the operator has not declared yet, and listing legal form, representatives, trade register, VAT number, supervisory authority and regulated profession when declared; it states that no notice is published when the operator owes none. | Use on `/legal-notice`, the route the application router mounts from the public-documents atom and the marketing website links when the notice is owed. | Avoid for governed documents with releases (privacy notice, terms: use the public governed-document page) and for any text the operator did not declare: this page never drafts or invents a particular. |
128
129
  | `PublicLayout_MainContainer` | Minimal full-viewport wrapper driven by `usePublicShellLayout`. In card mode it may open the card with a brand header: the mark when one resolves, and the name — set from the TYPOGRAPHY.HEADING recipe, and not a heading element, since the card content owns the page heading. The login page may pass `organizationBranding` from identification; an explicit shell identity still wins. Tenant color is a decorative identity accent, not a replacement for accessible application theme tokens. Other public pages keep their defaults. | Use for auth flows, static marketing content, and other pre-app surfaces. | Avoid for authenticated app shells — use `APP_LAYOUTS_MAIN_CONTAINER`. |
129
130
  | `PublicLayout_StaticContentContainer` | Thin wrapper around centered content within the public shell. | Use for legal, help, or marketing pages that do not need auth chrome. | Avoid for authenticated app surfaces. |
130
131
  | `PublicLayout_Terms` | Public legal-document layout that shows release version and effective date for a release, a draft notice for an unreleased draft, and a "not yet established" note beneath any clause the document states is incomplete; it shows no partial content when nothing may be displayed, and withholds unapproved releases and drafts only when the application arms its governed-document approval gate (`compliance.governedDocumentApprovalGate`), the same switch every acceptance surface reads. | Use on `/privacy`, `/terms` and future stable-definition public document routes. | Avoid for authenticated governance records, off-site documents, or rendering a draft candidate directly — drafts reach this page only as projected public documents. |
@@ -3259,6 +3259,14 @@ import { ProgressionTrackerVariant } from '@wildo-ai/saas-models';
3259
3259
  <ProgressionMilestoneTracker variant={ProgressionTrackerVariant.DETAILED} className="w-full" />
3260
3260
  ```
3261
3261
 
3262
+ ## `PublicLayout_LegalNotice`
3263
+
3264
+ Public legal-notice (imprint) page at `/legal-notice`, rendering the operator identity particulars an information-society service provider established in the EU, the EEA, the UK or Switzerland must publish, from the application's `compliance.legalNotice` (projected from `operatorComplianceIdentity` by `wildo config legal-notice`).
3265
+
3266
+ **Composition**
3267
+
3268
+ - Preset implementation ships from `@wildo-ai/presets-components`; runtime resolution uses the component registry in `@wildo-ai/saas-frontend-lib`.
3269
+
3262
3270
  ## `PublicLayout_MainContainer`
3263
3271
 
3264
3272
  Public / unauthenticated layout container with optional centered card chrome, and — when the application opts in via `publicShellIdentityMode` — the surface identity at the top of that card.
@@ -217,13 +217,27 @@ Run from the app root, substituting `<source>` and `<target>`:
217
217
  | Invariant | Command |
218
218
  |--------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
219
219
  | Engine barrel uses the scanner (single owner) | `rg -n 'scanCustomLabelsDirectory' backend-api/src/engine/i18n/index.ts` |
220
- | At least one per-unit source-locale file exists | `rg --files backend-api/src/engine/i18n -g '*.<source>.ts' \| head` |
221
- | Per-unit count matches between source and target | `diff <(rg --files backend-api/src/engine/i18n -g '*.<source>.ts' \| sed 's/<source>/X/' \| sort) <(rg --files backend-api/src/engine/i18n -g '*.<target>.ts' \| sed 's/<target>/X/' \| sort)` |
222
- | Lock file is up-to-date with both locales | `rg -n '"localeCode":\s*"(<source>\|<target>)"' wildo-saas.lock.json` |
220
+ | At least one per-unit source-locale file exists | see the commands below the table |
221
+ | Per-unit count matches between source and target | see the commands below the table |
222
+ | Lock file is up-to-date with both locales | see the commands below the table |
223
223
  | **No empty values** in any per-unit file (must be empty) | `rg -n '":\s*""' backend-api/src/engine/i18n -g '*.ts'` |
224
224
  | **No hard-coded product strings** in JSX touched in this change | `rg -n ">[A-Z][a-z]+ [A-Z][a-z]" frontend/src/modules/<slug>/` |
225
- | Every per-unit file preserves the auto-generated header | `rg -L "DO NOT EDIT THIS FILE MANUALLY" backend-api/src/engine/i18n -g '*.ts'` (output should be empty) |
226
- | **No** monolithic `labels.<locale>.ts` (must be empty) | `rg --files backend-api/src/engine/i18n -g 'labels.*.ts' \| rg -v '/'` |
225
+ | Every per-unit file preserves the auto-generated header | `rg --files-without-match "DO NOT EDIT THIS FILE MANUALLY" backend-api/src/engine/i18n -g '*.ts'` (output should be empty) |
226
+ | **No** monolithic `labels.<locale>.ts` (must be empty) | see the commands below the table |
227
+
228
+ ```bash
229
+ # At least one per-unit source-locale file exists
230
+ rg --files backend-api/src/engine/i18n -g '*.<source>.ts' | head
231
+
232
+ # Per-unit count matches between source and target
233
+ diff <(rg --files backend-api/src/engine/i18n -g '*.<source>.ts' | sed 's/<source>/X/' | sort) <(rg --files backend-api/src/engine/i18n -g '*.<target>.ts' | sed 's/<target>/X/' | sort)
234
+
235
+ # Lock file is up-to-date with both locales
236
+ rg -n '"localeCode":\s*"(<source>|<target>)"' wildo-saas.lock.json
237
+
238
+ # No monolithic `labels.<locale>.ts` (must be empty)
239
+ rg --files backend-api/src/engine/i18n -g 'labels.*.ts' | rg -v '/'
240
+ ```
227
241
 
228
242
  The high-signal invariant is **"per-unit count matches between
229
243
  source and target"** combined with **"no empty values"** — drift
@@ -210,11 +210,19 @@ Run from the app root, substituting `<source>` and `<target>`:
210
210
 
211
211
  | Invariant | Command |
212
212
  |------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
213
- | At least one target-locale per-unit file exists | `rg --files backend-api/src/engine/i18n -g '*.<target>.ts' \| head` |
214
- | Source-locale per-unit count matches target-locale count | `diff <(rg --files backend-api/src/engine/i18n -g '*.<source>.ts' \| sed 's/<source>/X/' \| sort) <(rg --files backend-api/src/engine/i18n -g '*.<target>.ts' \| sed 's/<target>/X/' \| sort)` |
213
+ | At least one target-locale per-unit file exists | see the commands below the table |
214
+ | Source-locale per-unit count matches target-locale count | see the commands below the table |
215
215
  | Lock file tracks the target locale | `rg -n '"localeCode":\s*"<target>"' wildo-saas.lock.json` |
216
216
  | **No empty translated values** in target files (must be empty) | `rg -n '":\s*""' backend-api/src/engine/i18n -g '*.<target>.ts'` |
217
217
 
218
+ ```bash
219
+ # At least one target-locale per-unit file exists
220
+ rg --files backend-api/src/engine/i18n -g '*.<target>.ts' | head
221
+
222
+ # Source-locale per-unit count matches target-locale count
223
+ diff <(rg --files backend-api/src/engine/i18n -g '*.<source>.ts' | sed 's/<source>/X/' | sort) <(rg --files backend-api/src/engine/i18n -g '*.<target>.ts' | sed 's/<target>/X/' | sort)
224
+ ```
225
+
218
226
  The high-signal invariants are **"source per-unit count matches
219
227
  target per-unit count"** combined with **"no empty translated
220
228
  values"** — drift in either direction means the translation rerun
@@ -256,9 +256,9 @@ export const matterMailInboundHandler = defineInboundChannelHandler({
256
256
 
257
257
  - `rg "inboundHandlers:" backend-api/src/modules` — every handler file is registered somewhere.
258
258
  - `rg "APP_ADMIN_SUPER_ADMIN" backend-api/src/modules/*/inbound` — must return nothing.
259
- - `rg "HMAC_SHA256_HEADER" -l backend-api/src/modules/*/inbound | xargs rg -L "dedupKey"` — must return nothing.
259
+ - `rg "HMAC_SHA256_HEADER" -l backend-api/src/modules/*/inbound | xargs rg --files-without-match "dedupKey"` — must return nothing.
260
260
  - `rg -c "isDefault: true" backend-api/src/modules/*/inbound` — sums to one per channel.
261
- - `rg -l "defineInboundChannelHandler" backend-api/src/modules | xargs rg -L "minimumSenderAssurance"` — must return nothing.
261
+ - `rg -l "defineInboundChannelHandler" backend-api/src/modules | xargs rg --files-without-match "minimumSenderAssurance"` — must return nothing.
262
262
  - `rg -n "message\.(text|strippedReply)" backend-api/src/modules/*/inbound` — every read of the body; none may
263
263
  choose an organization, a record to write into, or a recipient.
264
264
 
@@ -890,11 +890,16 @@ Run from the app root, substituting `<env>`:
890
890
  | Typed `BackingServiceSource` enum used per backing service | `rg -n "source:\s*BackingServiceSource\." infrastructure/<env>/wildo.infra.*.config.ts` |
891
891
  | Every `MANAGED` declaration is MongoDB Atlas (anything else is refused) | `rg -n "BackingServiceSource\.MANAGED" infrastructure/*/wildo.infra.*.config.ts` — every hit must be `mongodb` with `provider: 'atlas'` |
892
892
  | Audit capability has an audit store in EVERY env (both sides must match) | `rg -n "COMPLIANCE_AUDIT_TRAIL" wildo.saas.config.ts` then `rg -ln "immudb:" infrastructure/*/wildo.infra.*.config.ts` |
893
- | **No secrets** in infra file (must be empty) | `rg -n "(password\|apiKey\|secret\|token):\s*['\"]" infrastructure/<env>/wildo.infra.*.config.ts` |
893
+ | **No secrets** in infra file (must be empty) | see the commands below the table |
894
894
  | Custom environment uses the remote filename | Inspect `infrastructure/<env>/wildo.infra.remote.config.ts` for every non-local ID. |
895
895
  | Optional local companion binding is deliberate | Inspect `devCompanion` when present; omission is schema-valid. |
896
896
  | Remote runtime mode is explicit | Inspect `runtimeEnvironment`; remote Kubernetes additionally requires `remoteProvider`. `deployment` is optional. |
897
897
 
898
+ ```bash
899
+ # No secrets in infra file (must be empty)
900
+ rg -n "(password|apiKey|secret|token):\s*['\"]" infrastructure/<env>/wildo.infra.*.config.ts
901
+ ```
902
+
898
903
  Validate the environment slug and its filename separately from the closed
899
904
  runtime/source enums. Keep secret values outside authored infrastructure.
900
905
 
@@ -97,6 +97,9 @@ deployed environment shares them).
97
97
  (added a backing service, changed a port, swapped a `BackingServiceSource`)
98
98
  - Generated artifacts are missing or stale and need regeneration
99
99
  (`config.json`, the compose file, `.env.wildo-platform`)
100
+ - A process refuses a generated file, or its error says to regenerate or to
101
+ run `wildo config sync` (provider runtime artifacts, CSP, compliance modules,
102
+ the lockfile) — read `references/derived-artifact-currency.md`
100
103
  - The user wants to rotate local credentials (rare; explicit opt-in)
101
104
  - Platform/application state is absent, partial, or inconsistent and must be
102
105
  repaired without deleting backing data (`wildo local init`)
@@ -143,7 +146,10 @@ the user's situation, including whether another application owns the running pla
143
146
 
144
147
  If the user is describing a symptom rather than an action ("the dev
145
148
  companion can't reach mongodb", "the stack won't start"), read
146
- `references/local-environment-troubleshooting.md` first to triage.
149
+ `references/local-environment-troubleshooting.md` first to triage. If the
150
+ symptom names a generated file, or says it was "generated before" a check or
151
+ a contract change, read `references/derived-artifact-currency.md` instead: the
152
+ fix is to regenerate that file, never to edit it or the code that refused it.
147
153
 
148
154
  A live `wildo local dev` owner blocks full initialization because convergence
149
155
  stops tracked processes and rewrites the shared platform generation. For a
@@ -383,6 +389,10 @@ What this loop does **not** do:
383
389
  (move the CLI and this application to a release, and what it owes afterwards),
384
390
  then `wildo align-deps`: why the second install is not optional, and the
385
391
  undeclared-peer trap that no repeated install can fix
392
+ - `references/derived-artifact-currency.md` — every derived artifact in the
393
+ application: where it lives, which command regenerates it, how to tell it is
394
+ current (and which ones nothing can check), and the refusal messages a stale
395
+ one produces
386
396
  - `references/local-environment-troubleshooting.md` — symptom-driven
387
397
  triage for the most common failure modes (missing manifest, missing
388
398
  config.json, arm64 image incompatibilities, docker-credential-helper
@@ -438,9 +448,14 @@ Run from the app root, substituting `<env>` (typically `local`):
438
448
  | Generated `config.json` rendered for the env | `ls .wildo-saas/infrastructure/environments/<env>/generated/config/config.json` |
439
449
  | Compose file declares every authored backing service (e.g. clamav) | `rg -n "^ clamav:" .wildo-saas/infrastructure/environments/<env>/docker-compose/docker-compose.wildo-platform.yml` |
440
450
  | **No empty `host:container` port mapping** in the compose (must be empty) | `rg -n "^\s+- \":\"" .wildo-saas/infrastructure/environments/<env>/docker-compose/docker-compose.wildo-platform.yml` |
441
- | **No secret values** in the authored infra config (must be empty) | `rg -n "(password\|apiKey\|secret\|token):\s*['\"]" infrastructure/<env>/wildo.infra.<env>.config.ts` |
451
+ | **No secret values** in the authored infra config (must be empty) | see the commands below the table |
442
452
  | `secrets.json` has not been re-written by an unintended sync | `git status --porcelain infrastructure/<env>/secrets/secrets.json` (should be empty unless you explicitly rotated) |
443
453
 
454
+ ```bash
455
+ # No secret values in the authored infra config (must be empty)
456
+ rg -n "(password|apiKey|secret|token):\s*['\"]" infrastructure/<env>/wildo.infra.<env>.config.ts
457
+ ```
458
+
444
459
  Compare the authored hosting choices, the selected environment's
445
460
  `backingServices` state and the generated workloads together. Each enabled
446
461
  self-hosted service should have its expected workload and resolved ports;