@wildo-ai/framework-knowledge 1.1.9 → 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 (376) 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/expert-personas-and-deliberations.md +26 -7
  5. package/dist/claude-marketplace/plugins/wildo/references/runs-judges-and-questions.md +4 -2
  6. package/dist/claude-marketplace/plugins/wildo/skills/accept/SKILL.md +4 -2
  7. package/dist/claude-marketplace/plugins/wildo/skills/why/SKILL.md +9 -3
  8. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  9. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  10. package/dist/esm/framework-knowledge.definitions.js +84 -4
  11. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  12. package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
  13. package/dist/esm/index.d.ts.map +1 -1
  14. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +1 -1
  15. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -1
  16. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +1 -1
  17. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  18. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts.map +1 -1
  19. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +39 -1
  20. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -1
  21. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +132 -20
  22. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
  23. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
  24. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts +8 -4
  25. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts.map +1 -1
  26. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js +13 -6
  27. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js.map +1 -1
  28. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +2 -1
  29. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
  30. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +85 -8
  31. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
  32. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts +4 -3
  33. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts.map +1 -1
  34. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js +4 -3
  35. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js.map +1 -1
  36. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +12 -3
  37. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
  38. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +8 -4
  39. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
  40. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts +4 -1
  41. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts.map +1 -1
  42. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js +2 -1
  43. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js.map +1 -1
  44. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts.map +1 -1
  45. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts.map +1 -1
  46. package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.d.ts.map +1 -1
  47. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts.map +1 -1
  48. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
  49. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +1 -1
  50. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -1
  51. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +13 -1
  52. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
  53. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts.map +1 -1
  54. package/dist/esm/playbooks/refinement.governance-document-candidate/playbook.definition.d.ts.map +1 -1
  55. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +2 -2
  56. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
  57. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +10 -4
  58. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
  59. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts +2 -1
  60. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts.map +1 -1
  61. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js +5 -3
  62. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js.map +1 -1
  63. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts +2 -1
  64. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts.map +1 -1
  65. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js +11 -9
  66. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js.map +1 -1
  67. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts +17 -3
  68. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts.map +1 -1
  69. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js +19 -2
  70. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js.map +1 -1
  71. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
  72. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
  73. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -1
  74. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -1
  75. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  76. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
  77. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -1
  78. package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts.map +1 -1
  79. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts +27 -6
  80. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts.map +1 -1
  81. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js +32 -12
  82. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js.map +1 -1
  83. package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.d.ts.map +1 -1
  84. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
  85. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  86. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -1
  87. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +2 -1
  88. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
  89. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +13 -5
  90. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
  91. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
  92. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +38 -3
  93. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
  94. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +2 -1
  95. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
  96. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +23 -8
  97. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
  98. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts.map +1 -1
  99. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
  100. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
  101. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
  102. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +11 -0
  103. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
  104. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  105. package/dist/knowledge/manifest.json +7 -7
  106. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +1 -1
  107. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-protocol.json +1 -1
  108. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-treatment.json +1 -1
  109. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +149 -11
  110. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +40 -2
  111. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +55 -0
  112. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +1 -1
  113. package/dist/knowledge/playbooks/bottom_up.conception/playbook.json +10 -2
  114. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-protocol.json +1 -1
  115. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-treatment.json +1 -1
  116. package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +107 -11
  117. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +4 -2
  118. package/dist/knowledge/playbooks/bottom_up.experience-plan/method.md +28 -6
  119. package/dist/knowledge/playbooks/bottom_up.experience-plan/playbook.json +5 -4
  120. package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +50 -0
  121. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +16 -4
  122. package/dist/knowledge/playbooks/bottom_up.website-plan/method.md +19 -0
  123. package/dist/knowledge/playbooks/bottom_up.website-plan/playbook.json +5 -2
  124. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +2 -1
  125. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  126. package/dist/knowledge/playbooks/refinement.document-facts/method.md +8 -0
  127. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +3 -2
  128. package/dist/knowledge/playbooks/refinement.feature-contribution/method.md +5 -2
  129. package/dist/knowledge/playbooks/refinement.feature-contribution/playbook.json +1 -1
  130. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-protocol.json +1 -1
  131. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-treatment.json +1 -1
  132. package/dist/knowledge/playbooks/top_down.brand-identity/method.md +7 -3
  133. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +3 -3
  134. package/dist/knowledge/playbooks/top_down.brand-name-research/method.md +56 -16
  135. package/dist/knowledge/playbooks/top_down.brand-name-research/playbook.json +6 -4
  136. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-protocol.json +1 -1
  137. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-treatment.json +1 -1
  138. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/method.md +30 -9
  139. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/playbook.json +5 -3
  140. package/dist/knowledge/playbooks/top_down.brand-naming/playbook.json +12 -1
  141. package/dist/knowledge/playbooks/top_down.capability-map/method.md +10 -9
  142. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +1 -1
  143. package/dist/knowledge/playbooks/top_down.expert-personas/playbook.json +16 -2
  144. package/dist/knowledge/playbooks/top_down.feature-drafts/method.md +5 -2
  145. package/dist/knowledge/playbooks/top_down.feature-drafts/playbook.json +1 -1
  146. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-protocol.json +1 -1
  147. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-treatment.json +1 -1
  148. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +26 -0
  149. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +4 -2
  150. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-protocol.json +1 -1
  151. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-treatment.json +1 -1
  152. package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +1 -1
  153. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-protocol.json +1 -1
  154. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-treatment.json +1 -1
  155. package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +84 -9
  156. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +6 -3
  157. package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +19 -0
  158. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +19 -1
  159. package/dist/knowledge/references/brand.name-choice.config.md +20 -3
  160. package/dist/knowledge/references/brand.name-screening.config.md +58 -3
  161. package/dist/knowledge/references/build-plan.task-graph.config.md +55 -0
  162. package/dist/knowledge/references/companion.market.prompt-renderer.md +11 -6
  163. package/dist/knowledge/references/example.authorization.application-roles.office-and-field.md +44 -0
  164. package/dist/knowledge/references/example.backend.custom-operation.audit-event.md +81 -0
  165. package/dist/knowledge/references/example.backend.custom-operation.child-line-total.md +258 -0
  166. package/dist/knowledge/references/example.backend.custom-operation.computed-total.md +153 -0
  167. package/dist/knowledge/references/example.backend.custom-operation.create-related-resource.md +107 -0
  168. package/dist/knowledge/references/example.data-seeding.minimal.md +10 -9
  169. package/dist/knowledge/references/example.data-seeding.row-reference.md +80 -0
  170. package/dist/knowledge/references/example.email.template.minimal.md +1 -1
  171. package/dist/knowledge/references/example.resource.config-wiring.retention-policy-operations.md +74 -0
  172. package/dist/knowledge/references/example.resource.personal-data.free-text-field.md +19 -0
  173. package/dist/knowledge/references/example.resource.personal-data.person-without-account.md +27 -0
  174. package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +152 -0
  175. package/dist/knowledge/references/example.resource.ui-behavior.filter-presets.md +15 -0
  176. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -0
  177. package/dist/knowledge/references/example.views.app-level.home-definition.md +13 -0
  178. package/dist/knowledge/references/example.views.chart-definition.shared.md +83 -0
  179. package/dist/knowledge/references/experience-plan.config.md +60 -7
  180. package/dist/knowledge/references/market.context-block.builder.md +1 -1
  181. package/dist/knowledge/references/placement-plan.config.md +43 -0
  182. package/dist/knowledge/references/requirements.functional-requirement.config.md +8 -2
  183. package/dist/knowledge/references/requirements.non-functional-requirement.config.md +2 -0
  184. package/dist/knowledge/references/requirements.references.conventions.md +1 -1
  185. package/dist/knowledge/references/requirements.snapshot.config.md +57 -1
  186. package/dist/knowledge/references/requirements.snapshot.validation.md +35 -1
  187. package/dist/knowledge/references/saas.backend.audit-logs.log-event.md +63 -0
  188. package/dist/knowledge/references/saas.backend.document-sequence.issue-in-operation.md +60 -0
  189. package/dist/knowledge/references/saas.backend.document-sequence.raise-floor.md +156 -0
  190. package/dist/knowledge/references/saas.backend.email.send.md +77 -0
  191. package/dist/knowledge/references/saas.backend.notifications.operation-email-template-ref.md +60 -0
  192. package/dist/knowledge/references/saas.data-seeding.computed-entry.md +43 -0
  193. package/dist/knowledge/references/saas.data-seeding.definition-input.md +8 -2
  194. package/dist/knowledge/references/saas.data-seeding.row-reference.md +93 -0
  195. package/dist/knowledge/references/saas.frontend.collection-filter-presets.md +124 -0
  196. package/dist/knowledge/references/saas.frontend.launcher.item-refs.md +316 -0
  197. package/dist/knowledge/references/saas.frontend.launcher.merge-rules.md +106 -0
  198. package/dist/knowledge/references/saas.frontend.launcher.runtime-availability.md +60 -0
  199. package/dist/knowledge/references/saas.frontend.resource-label-params.md +52 -0
  200. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +47 -18
  201. package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +4 -1
  202. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destination-roles.md +25 -0
  203. package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +2 -2
  204. package/dist/knowledge/references/saas.models.audit.trail-config.md +45 -0
  205. package/dist/knowledge/references/saas.models.notifications.user-notification-definition.md +5 -3
  206. package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +26 -0
  207. package/dist/knowledge/references/saas.models.roles.definition.md +61 -0
  208. package/dist/knowledge/references/saas.models.roles.organization-defaults.md +97 -0
  209. package/dist/knowledge/references/saas.public-runtime.contract.md +26 -0
  210. package/dist/knowledge/references/saas.website.astro.bridge.md +10 -0
  211. package/dist/knowledge/references/saas.website.astro.label-loader.md +3 -0
  212. package/dist/knowledge/references/saas.website.astro.llms-txt-server.md +14 -1
  213. package/dist/knowledge/references/saas.website.astro.site-context.md +13 -0
  214. package/dist/knowledge/references/saas.website.blog.bridge.md +4 -0
  215. package/dist/knowledge/references/saas.website.config.site-context-loader.md +3 -0
  216. package/dist/knowledge/references/saas.website.legal.public-document-links.md +76 -0
  217. package/dist/knowledge/references/saas.website.root-config.seo.md +2 -1
  218. package/dist/knowledge/references/saas.website.runtime.context.md +7 -0
  219. package/dist/knowledge/references/saas.website.seo.llms-txt-config.md +2 -0
  220. package/dist/knowledge/references/website-plan.config.md +26 -0
  221. package/dist/knowledge/references/zod.decorators.chainable-runtime.md +13 -0
  222. package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +7 -0
  223. package/dist/knowledge/references/zod.decorators.document-sequence.md +65 -0
  224. package/dist/knowledge/references/zod.decorators.schema-metadata.md +1 -0
  225. package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +21 -0
  226. package/dist/knowledge/references/zod.factories.bigdecimal.md +1 -0
  227. package/dist/knowledge/references/zod.factories.code.md +1 -0
  228. package/dist/knowledge/references/zod.factories.duration.md +1 -0
  229. package/dist/knowledge/references/zod.factories.money.md +1 -0
  230. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  231. package/dist/knowledge/registries/framework-topics.json +337 -1
  232. package/dist/knowledge/registries/playbooks.json +18 -18
  233. package/dist/knowledge/registries/source-tags.json +1435 -873
  234. package/dist/knowledge/rules/live-context-door.md +1 -1
  235. package/dist/knowledge/skills/INDEX.md +3 -1
  236. package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +16 -3
  237. package/dist/knowledge/skills/application-database-migrations/SKILL.md +14 -3
  238. package/dist/knowledge/skills/application-roles-authoring/SKILL.md +158 -0
  239. package/dist/knowledge/skills/application-roles-authoring/references/framework-application-roles-api.md +169 -0
  240. package/dist/knowledge/skills/application-roles-authoring/references/office-and-field-worked-example.md +63 -0
  241. package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +6 -1
  242. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +256 -9
  243. package/dist/knowledge/skills/backend-custom-operation/references/after-the-operation.md +42 -0
  244. package/dist/knowledge/skills/backend-custom-operation/references/framework-audit-log-event-api.md +220 -0
  245. package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +5 -0
  246. package/dist/knowledge/skills/brand-name-screening/SKILL.md +33 -9
  247. package/dist/knowledge/skills/brand-name-screening/references/framework-brand-name-screening-api.md +78 -6
  248. package/dist/knowledge/skills/brand-name-screening/references/screening-procedure.md +30 -8
  249. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +2 -1
  250. package/dist/knowledge/skills/config-app-shell/SKILL.md +58 -5
  251. package/dist/knowledge/skills/config-app-shell/references/framework-launcher-items-api.md +461 -0
  252. package/dist/knowledge/skills/config-app-shell/references/framework-launcher-visibility-api.md +80 -0
  253. package/dist/knowledge/skills/config-design-system/SKILL.md +28 -6
  254. package/dist/knowledge/skills/config-navigation/SKILL.md +14 -3
  255. package/dist/knowledge/skills/config-saas/SKILL.md +25 -11
  256. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +51 -1
  257. package/dist/knowledge/skills/config-saas/references/framework-audit-trail-config-api.md +62 -2
  258. package/dist/knowledge/skills/config-saas-backend/SKILL.md +6 -1
  259. package/dist/knowledge/skills/configure-billing/SKILL.md +18 -4
  260. package/dist/knowledge/skills/email-add-template/SKILL.md +27 -5
  261. package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +1 -1
  262. package/dist/knowledge/skills/email-add-template/references/framework-email-send-api.md +128 -0
  263. package/dist/knowledge/skills/email-add-template/references/framework-operation-email-template-ref-api.md +99 -0
  264. package/dist/knowledge/skills/engine-component-registration/SKILL.md +6 -1
  265. package/dist/knowledge/skills/engine-product-definitions/SKILL.md +21 -8
  266. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +10 -2
  267. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +18 -4
  268. package/dist/knowledge/skills/frontend-component-catalog/SKILL.md +11 -3
  269. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +2 -1
  270. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +8 -0
  271. package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +18 -4
  272. package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +10 -2
  273. package/dist/knowledge/skills/infra-environment-config/SKILL.md +6 -1
  274. package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +6 -1
  275. package/dist/knowledge/skills/market-add-feature-benefit/SKILL.md +10 -2
  276. package/dist/knowledge/skills/market-alternatives/SKILL.md +10 -2
  277. package/dist/knowledge/skills/market-authoring-overview/SKILL.md +10 -2
  278. package/dist/knowledge/skills/market-category/SKILL.md +21 -7
  279. package/dist/knowledge/skills/market-channels/SKILL.md +6 -1
  280. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +11 -3
  281. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +1 -1
  282. package/dist/knowledge/skills/market-generation-cli/SKILL.md +21 -11
  283. package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +11 -6
  284. package/dist/knowledge/skills/market-icp/SKILL.md +10 -2
  285. package/dist/knowledge/skills/market-jobs-pains-gains/SKILL.md +6 -1
  286. package/dist/knowledge/skills/market-message-templates-authoring/SKILL.md +6 -1
  287. package/dist/knowledge/skills/market-persona/SKILL.md +14 -3
  288. package/dist/knowledge/skills/market-positioning-authoring/SKILL.md +6 -1
  289. package/dist/knowledge/skills/market-proof-and-objection/SKILL.md +10 -2
  290. package/dist/knowledge/skills/market-scoring-interpretation/SKILL.md +6 -1
  291. package/dist/knowledge/skills/market-snapshot-validation/SKILL.md +14 -3
  292. package/dist/knowledge/skills/market-tone-of-voice/SKILL.md +6 -1
  293. package/dist/knowledge/skills/model-cost-attribution/references/framework-work-unit-api.md +26 -0
  294. package/dist/knowledge/skills/module-companion-exports/SKILL.md +7 -1
  295. package/dist/knowledge/skills/module-relationships/SKILL.md +31 -4
  296. package/dist/knowledge/skills/pdf-template-authoring/SKILL.md +4 -2
  297. package/dist/knowledge/skills/provider-address-lookup/SKILL.md +14 -3
  298. package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +6 -1
  299. package/dist/knowledge/skills/provider-operation-calls/SKILL.md +14 -3
  300. package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +10 -2
  301. package/dist/knowledge/skills/resource-add-field/SKILL.md +10 -2
  302. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +46 -17
  303. package/dist/knowledge/skills/resource-add-resource/SKILL.md +14 -2
  304. package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +26 -0
  305. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +29 -3
  306. package/dist/knowledge/skills/resource-config-wiring/references/framework-collection-operation-declarations.md +19 -4
  307. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +5 -2
  308. package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +103 -0
  309. package/dist/knowledge/skills/resource-config-wiring/references/framework-retention-policy-operations.md +135 -0
  310. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +26 -0
  311. package/dist/knowledge/skills/resource-config-wiring/references/framework-user-notifications-api.md +26 -7
  312. package/dist/knowledge/skills/resource-custom-view/SKILL.md +10 -2
  313. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +46 -17
  314. package/dist/knowledge/skills/resource-external-data/references/erasure-suppression.md +2 -2
  315. package/dist/knowledge/skills/resource-retention-binding/SKILL.md +5 -1
  316. package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +15 -1
  317. package/dist/knowledge/skills/resource-schema-authoring/references/computed-totals.md +569 -0
  318. package/dist/knowledge/skills/resource-schema-authoring/references/document-numbers.md +358 -0
  319. package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +8 -0
  320. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +21 -0
  321. package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +7 -2
  322. package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +13 -0
  323. package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +153 -0
  324. package/dist/knowledge/skills/resource-status-lifecycle/references/commercial-documents.md +46 -0
  325. package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +198 -0
  326. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +30 -4
  327. package/dist/knowledge/skills/resource-ui-behavior/references/framework-collection-filter-presets-api.md +157 -0
  328. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +101 -19
  329. package/dist/knowledge/skills/seeding-authoring/SKILL.md +155 -40
  330. package/dist/knowledge/skills/seeding-authoring/references/cross-seed-row-references.md +67 -0
  331. package/dist/knowledge/skills/seeding-authoring/references/framework-data-seeding-api.md +148 -4
  332. package/dist/knowledge/skills/seeding-authoring/references/seed-row-overlay.md +22 -0
  333. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +43 -0
  334. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +2 -2
  335. package/dist/knowledge/skills/spec-companion-exports/SKILL.md +6 -1
  336. package/dist/knowledge/skills/spec-component-update/SKILL.md +10 -2
  337. package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +2 -2
  338. package/dist/knowledge/skills/spec-family-update/SKILL.md +71 -66
  339. package/dist/knowledge/skills/spec-family-update/references/family-spec-routing.md +1 -1
  340. package/dist/knowledge/skills/spec-resource-update/SKILL.md +30 -10
  341. package/dist/knowledge/skills/spec-resource-update/references/resource-spec-field-routing.md +28 -0
  342. package/dist/knowledge/skills/spec-update-after-change/SKILL.md +22 -5
  343. package/dist/knowledge/skills/views-add-composite-view/SKILL.md +6 -1
  344. package/dist/knowledge/skills/views-add-custom-view/SKILL.md +10 -2
  345. package/dist/knowledge/skills/views-app-level/SKILL.md +13 -3
  346. package/dist/knowledge/skills/views-app-level/references/application-home.md +56 -0
  347. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +221 -37
  348. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +22 -5
  349. package/dist/knowledge/skills/views-execution-authoring/SKILL.md +1 -1
  350. package/dist/knowledge/skills/website-anonymous-session/SKILL.md +32 -2
  351. package/dist/knowledge/skills/website-blog-authoring/SKILL.md +16 -3
  352. package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +4 -0
  353. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +7 -1
  354. package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +13 -1
  355. package/dist/knowledge/skills/website-factory-advanced/SKILL.md +10 -2
  356. package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +13 -1
  357. package/dist/knowledge/skills/website-layout-overrides/SKILL.md +6 -1
  358. package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +19 -1
  359. package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +55 -18
  360. package/dist/knowledge/skills/website-navigation-authoring/references/framework-public-document-links-api.md +98 -0
  361. package/dist/knowledge/skills/website-navigation-authoring/references/worked-examples-header-footer.md +8 -11
  362. package/dist/knowledge/skills/website-page-authoring/SKILL.md +16 -5
  363. package/dist/knowledge/skills/website-page-authoring/references/framework-site-context-loader-api.md +3 -0
  364. package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +6 -1
  365. package/dist/knowledge/skills/website-section-faq/SKILL.md +6 -1
  366. package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +6 -1
  367. package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +10 -2
  368. package/dist/knowledge/skills/website-section-hero/SKILL.md +6 -1
  369. package/dist/knowledge/skills/website-section-pricing/SKILL.md +6 -1
  370. package/dist/knowledge/skills/website-section-social-proof/SKILL.md +12 -2
  371. package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +15 -3
  372. package/dist/knowledge/skills/website-seo-aeo-geo/references/geo-api.md +16 -1
  373. package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +2 -1
  374. package/dist/knowledge/topic-index.json +1441 -269
  375. package/dist/tsconfig.build.tsbuildinfo +1 -1
  376. package/package.json +4 -4
@@ -216,13 +216,13 @@ What is **not** in this block (and shouldn't be):
216
216
  - `references/framework-connection-target-credentials.md` — which third-party identity a provider call acts as, how a tenant supplies its OWN credential, and why nothing is ever substituted for a missing one
217
217
  - `references/framework-content-security-policy-api.md` — the `csp` block on any frontend: opt-in by absence, the generated artifact is the only one read, and why report-only without a collector does nothing
218
218
  - `references/framework-value-moments-api.md` — `analytics.valueMoments`: why `role` changes three things at once, and why a declared moment with analytics off is evaluated by nothing
219
- - `references/framework-audit-trail-config-api.md` — the `auditTrail` block: why `archiveAfterDays` is the opt-in and why setting it never shrinks the primary store
219
+ - `references/framework-audit-trail-config-api.md` — the `auditTrail` block: why `archiveAfterDays` is the opt-in and why setting it never shrinks the primary store, and how `applicationEventTypes` classifies and words the application's own audit event types
220
220
  - `references/framework-systems-of-record-api.md` — `systemsOfRecord`: declaring a deployment your application reads its OWN rows out of, why it is not a provider, and the three files its name, address and credential live in; an instance's `facetAugmentations` opts it into packages that ADD a partition or a credential kind to its vendor's facet — see `resource-external-data`'s `references/facet-augmentations.md`
221
221
  - `providers.packages` — the provider packages discovery does not walk by name (another scope's, or an own-scope one not named `provider-*`) that the application admits to discovery; listing activates nothing, and `wildo config sync` refuses a listing that admits nothing — see `provider-backend-package`'s `references/framework-provider-package-allow-list-api.md`
222
222
  - `references/saas-config-scope.md` — what belongs in root SaaS config
223
223
  - `references/framework-wildo-saas-config-api.md` — `WildoSaasConfigSchema` / inferred types
224
224
  - `references/framework-provider-capabilities-api.md` — engine slots and provider capability vocabulary, including durable email selection
225
- - `references/compliance-declarations.md` — the six compliance declarations, and why an ABSENT one is never a negative answer
225
+ - `references/compliance-declarations.md` — the six compliance declarations, why an ABSENT one is never a negative answer, and the legal notice (imprint) projected from the operator's identity
226
226
 
227
227
  ## Verification
228
228
 
@@ -247,19 +247,33 @@ Run from the app root:
247
247
 
248
248
  | Invariant | Command |
249
249
  |--------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
250
- | Modules listed in config | `rg -oN "^\s+'([a-z-]+)':\s*\{\s*$" wildo.saas.config.ts` |
251
- | Module folders on disk | `ls -1 shared-lib/src/modules/` |
252
- | **Module entries ↔ module folders agree** (must return empty) | `comm -3 <(rg -oN "^\s+'\K[a-z-]+(?='\s*:\s*\{)" wildo.saas.config.ts \| sort -u) <(ls -1 shared-lib/src/modules/ \| sort -u)` |
253
- | Minion / worker paths exist | `rg -oN "path:\s+'\K[^']+" wildo.saas.config.ts \| while read p; do test -d "$p" \|\| echo "MISSING: $p"; done` |
254
- | Each engine capability declares `enabled:` | `rg -n "EngineCapability\.[A-Z_]+\]:\s*\{" wildo.saas.config.ts \| wc -l` then `rg -c "enabled:" wildo.saas.config.ts` |
255
- | **No placeholder in a compliance declaration** (must return empty) | `rg -n "TODO\|TBD\|PLACEHOLDER\|example\.com\|Acme" wildo.saas.config.ts` |
250
+ | **Module entries ↔ module folders agree** (must return empty) | see the commands below the table |
251
+ | Minion / worker paths exist | see the commands below the table |
252
+ | Each engine capability declares `enabled:` | run the commands below the table, then `rg -c "enabled:" wildo.saas.config.ts` |
253
+ | **No placeholder in a compliance declaration** (must return empty) | see the commands below the table |
256
254
  | Which provider is selected for telemetry | `rg -n "OBSERVABILITY_TELEMETRY\]:\s*\{" -A2 wildo.saas.config.ts` |
257
255
  | **Which runtimes declare it** (compare against the runtimes that should be traceable) | `rg -n "^\s+<telemetryProviderRef>:\s*\{" wildo.saas.config.ts` |
258
256
  | **Stored config matches the file** (no stale slice reported) | `wildo config validate --domain declaration` |
259
257
 
260
- The third invariant (modules ↔ folders) is the high-signal one — a
261
- module declared in config without a matching folder breaks `pnpm dev`
262
- silently in some pipelines and blocks others on startup.
258
+ ```bash
259
+ # Module entries ↔ module folders agree (must return empty) — reads only the modules block (inline, or the
260
+ # `applicationModules` constant in the same file); a module's folder lives under each service it declares, so a
261
+ # frontend-only module has no shared-lib folder
262
+ comm -3 <(awk '/^ *(modules: |export const applicationModules = )\{/{f=1;d=0} f{if(d==1&&match($0,/^ *\047?[a-z][a-z0-9-]*\047? *: *\{/)){k=$0;sub(/^ *\047?/,"",k);sub(/\047? *:.*/,"",k);print k} d+=gsub(/\{/,"{")-gsub(/\}/,"}"); if(d<=0)exit}' wildo.saas.config.ts | sort -u) <(ls -1 shared-lib/src/modules frontend/src/modules backend-api/src/modules 2>/dev/null | grep -E '^[a-z][a-z0-9-]*$' | sort -u)
263
+
264
+ # Minion / worker paths exist
265
+ rg -P -oN "path:\s+'\K[^']+" wildo.saas.config.ts | while read p; do test -d "$p" || echo "MISSING: $p"; done
266
+
267
+ # Each engine capability declares `enabled:`
268
+ rg -n "EngineCapability\.[A-Z_]+\]:\s*\{" wildo.saas.config.ts | wc -l
269
+
270
+ # No placeholder in a compliance declaration (must return empty)
271
+ rg -n "TODO|TBD|PLACEHOLDER|example\.com|Acme" wildo.saas.config.ts
272
+ ```
273
+
274
+ The modules ↔ folders invariant is the high-signal one: it names a module
275
+ the config declares with no code under any service, and a module folder no
276
+ declaration names.
263
277
 
264
278
  The last two are a READ, not a pass/fail: substitute the ref the first
265
279
  returns into the second, then compare the runtimes it lists against the
@@ -2,7 +2,8 @@
2
2
 
3
3
  Six optional declarations sit in the root SaaS config alongside the composition keys. They answer a
4
4
  different question from the rest of the file — not *"what am I made of"* but *"what is legally true of
5
- this application"* — and a produced privacy notice or terms document quotes them.
5
+ this application"* — and a produced privacy notice or terms document quotes them. The application's legal
6
+ notice (imprint) is projected from `operatorComplianceIdentity` too; see the section on it below.
6
7
 
7
8
  Read this before adding or editing any of them.
8
9
 
@@ -86,6 +87,55 @@ obligations for one of the two populations.
86
87
  Art. 6(1) basis the processing rests on, are different questions. Declaring a gate does not make
87
88
  consent the basis for anything.
88
89
 
90
+ ## The legal notice (imprint) — owed where the operator is ESTABLISHED
91
+
92
+ A service provider established in the EU, the EEA, the UK or Switzerland must publish its identity where anyone can
93
+ reach it in one step (Directive 2000/31/EC Art. 5(1); in Germany § 5 DDG, the Impressum; in the UK the E-Commerce
94
+ Regulations 2002, reg. 6; in Switzerland UWG Art. 3 Abs. 1 Bst. s). Other countries' rules are not modelled, so for an
95
+ establishment elsewhere the framework publishes no notice: check your own law. The markets you sell into do not decide it:
96
+ an operator established in France owes one, an operator established only in the United States does not, whichever
97
+ countries either serves. So the application reads one field:
98
+
99
+ ```ts
100
+ operatorComplianceIdentity: {
101
+ establishmentJurisdiction: 'fr', // a jurisdiction code, the place the operator is established
102
+ legalEntityName: 'Wonder Software SAS',
103
+ registeredAddress: '1 rue de la Paix, 75002 Paris, France',
104
+ generalContact: { email: 'contact@wonder.example' }, // phone optional; NOT the privacy contact
105
+ // Declare these only where they apply to the operator:
106
+ legalForm: 'SAS',
107
+ authorizedRepresentatives: ['Jeanne Martin, Présidente'],
108
+ tradeRegister: { register: 'RCS Paris', registrationNumber: '123 456 789' },
109
+ vatIdentificationNumber: 'FR12123456789',
110
+ // supervisoryAuthority, regulatedProfession: only for an activity that needs them
111
+ // Germany (§ 5 DDG) also: shareCapital { amount, outstandingContributions? } only if you state your capital,
112
+ // economicIdentificationNumber if you have one, and inLiquidation: true while the company is being wound up.
113
+ },
114
+ ```
115
+
116
+ Then project it into the running application and keep it current:
117
+
118
+ ```bash
119
+ wildo config legal-notice # writes backend-api/src/legal-notice.generated.ts
120
+ wildo config legal-notice --check # fails when the module is out of date
121
+ wildo config validate # the legal-notice domain: current, and composed as compliance.legalNotice
122
+ ```
123
+
124
+ `saas-config.backend.ts` composes the generated constant as `compliance.legalNotice`. The application then serves
125
+ the notice at `/legal-notice`, and a marketing website built from the same config links it from its footer.
126
+ The website decides from `wildo.saas.config.ts` at build time, while the page reads the generated module. Re-run
127
+ `wildo config legal-notice` after every change to the identity, or the footer can link to a page that is out of date.
128
+ `wildo config validate` fails until you do.
129
+
130
+ - Owed: the operator's name, its geographic address and a direct contact. Each one left undeclared appears on the
131
+ page as **not yet declared** and in `wildo context launch-blockers`. Never type a placeholder in its place: the page
132
+ publishes it as fact.
133
+ - Conditional: legal form, representatives, share capital, trade register, VAT number, economic identification number,
134
+ supervisory authority, regulated profession, liquidation.
135
+ Only you know whether each applies, so the page shows the ones you declare and nothing marks the others.
136
+ - `establishmentJurisdiction` undeclared means **unknown**, never "not owed". The page says no notice is published, and
137
+ the launch list names the field until you declare it.
138
+
89
139
  ## `operatingJurisdictions` — and the warning you must not silence
90
140
 
91
141
  ```ts
@@ -1,7 +1,8 @@
1
1
  # Framework Audit-Trail Config API
2
2
 
3
- The `auditTrail` block on the shared application configuration — one operator-tunable field, and two
4
- ways to misread it.
3
+ The `auditTrail` block on the application configuration (authored in the backend configuration). Its fields
4
+ are listed in the contract at the end. This page covers the two that are easiest to misread: the archival horizon
5
+ and the application's own audit event types.
5
6
 
6
7
  ## `archiveAfterDays` is the opt-in, and it deletes nothing
7
8
 
@@ -26,6 +27,20 @@ is a smaller primary store, this is not the mechanism.
26
27
  - An application turning this on after it already has aged data seeds the archive with a one-off run
27
28
  at a wider look-back.
28
29
 
30
+ ## `applicationEventTypes` classifies YOUR event types, never the framework's
31
+
32
+ Every event type an operation records with `logEvent` that is not a framework type is the application's own. Declare
33
+ each one here, keyed by its exact `eventType` string, with a `category` and a `severity`. Rows of that type are then
34
+ recorded and routed to the SIEM with that classification, and the labelling pipeline plans its word
35
+ (`system_enums.CoreAuditableEventType.<eventType>`). An undeclared type is recorded as `data_access` / `info` and shown
36
+ by its raw value.
37
+
38
+ - Type the declaration as total over your event-type enum (`satisfies Record<Your_AuditEventType, …>`), so an event
39
+ type added without a classification fails to compile. The worked example in
40
+ `backend-custom-operation/references/framework-audit-log-event-api.md` does this.
41
+ - Naming a framework event type is refused at startup: the engine's classification of its own events is authoritative.
42
+ - The key must use only letters, digits, `_` and `-`, because it becomes the last segment of a label key.
43
+
29
44
  ## Audit-Trail Config
30
45
 
31
46
  ## Import Origins
@@ -117,6 +132,19 @@ export enum AuditApplicationReadAccess {
117
132
  INDEPENDENT_APPROVAL = 'independent-approval',
118
133
  }
119
134
 
135
+ /**
136
+ * How one of the application's OWN audit event types is classified: the activity it records and the attention it
137
+ * deserves. The same two vocabularies the engine uses for its event types.
138
+ */
139
+ export const ApplicationAuditEventTypeDeclarationSchema = z.strictObject({
140
+ /** What kind of activity the event records. A business event (an invoice issued, a quote sent) is `data_access`. */
141
+ category: z.enum(AuditEventCategory),
142
+ /** How much attention it deserves: `info` is evidence, `warning` is worth review, `critical` is meant for whoever handles security incidents. A SIEM destination's event filter is what routes on it. */
143
+ severity: z.enum(AuditEventSeverity),
144
+ });
145
+
146
+ export type ApplicationAuditEventTypeDeclaration = z.infer<typeof ApplicationAuditEventTypeDeclarationSchema>;
147
+
120
148
  export const AuditTrailConfigSchema = z.object({
121
149
  /**
122
150
  * Application audit viewer admission. Omitted means ROLE_BASED in every environment.
@@ -183,7 +211,39 @@ export const AuditTrailConfigSchema = z.object({
183
211
  * addresses are admitted, never whether the admitted address is the one connected to.
184
212
  */
185
213
  allowPrivateNetworkSiemCollectors: z.boolean().optional(),
214
+
215
+ /**
216
+ * The application's OWN audit event types — the `eventType` values it passes to `AuditLogsBackendService.logEvent`
217
+ * — each with its classification. Keyed by the exact `eventType` string.
218
+ *
219
+ * ── What declaring one changes ─────────────────────────────────────────────
220
+ * - Every row of that type is recorded with the declared `eventCategory` and `severity`, and the SIEM export
221
+ * routes and filters by them. An UNDECLARED application type is recorded as `data_access` / `info`, whatever
222
+ * the event is — a business-critical event is then indistinguishable from routine reads.
223
+ * - The labelling pipeline plans a word for it (`system_enums.CoreAuditableEventType.<eventType>`, the open
224
+ * vocabulary the audit row's `eventType` field names), so the audit views show "Quote issued" instead of
225
+ * `SALES_QUOTE_ISSUED`. Run label generation after adding one.
226
+ *
227
+ * ── What it cannot do ──────────────────────────────────────────────────────
228
+ * It cannot reclassify a FRAMEWORK event type: the engine's own classification is authoritative, and naming one of
229
+ * its event types here is refused at startup. The key must be usable as the last segment of a label key (letters,
230
+ * digits, `_`, `-`).
231
+ *
232
+ * Severity is a property of the event TYPE. A row's `riskLevel` (supplied per emission) is a separate signal and
233
+ * does not change it.
234
+ *
235
+ * @example
236
+ * auditTrail: {
237
+ * applicationEventTypes: {
238
+ * SALES_QUOTE_ISSUED: { category: AuditEventCategory.DATA_ACCESS, severity: AuditEventSeverity.WARNING },
239
+ * },
240
+ * }
241
+ */
242
+ applicationEventTypes: z.record(z.string().regex(LABEL_KEY_SEGMENT_PATTERN), ApplicationAuditEventTypeDeclarationSchema).optional(),
186
243
  });
187
244
 
245
+ /** The application's declared audit event types, keyed by `eventType` — see `AuditTrailConfig.applicationEventTypes`. */
246
+ export type ApplicationAuditEventTypes = NonNullable<AuditTrailConfig['applicationEventTypes']>;
247
+
188
248
  export type AuditTrailConfig = z.infer<typeof AuditTrailConfigSchema>;
189
249
  ```
@@ -215,7 +215,12 @@ it names the failure you get without the block:
215
215
  | The transactional From address is declared | `rg -n "from:" backend-api/src/saas-config.backend.ts` |
216
216
  | The document-acceptance posture is declared | `rg -n "governedDocumentAcceptanceMode" backend-api/src/saas-config.backend.ts` |
217
217
  | Declared identity-provider ranges are CIDR, never host names (inspect each entry) | `rg -n -A3 "federatedIdentityProviderPrivateNetworks" backend-api/src/saas-config.backend.ts` |
218
- | No platform-managed branch leaked in (MUST return zero) | `rg -n "jwt:\|endPoints\|mongodb\|publicKey" backend-api/src/saas-config.backend.ts` |
218
+ | No platform-managed branch leaked in (MUST return zero) | see the commands below the table |
219
+
220
+ ```bash
221
+ # No platform-managed branch leaked in (MUST return zero)
222
+ rg -n "jwt:|endPoints|mongodb|publicKey" backend-api/src/saas-config.backend.ts
223
+ ```
219
224
 
220
225
  ## Common Rationalizations
221
226
 
@@ -247,13 +247,27 @@ Run from the app root (substitute `<ref>` / `<env>`):
247
247
  |-----------|---------|
248
248
  | **Provider SDK installed** (must return a hit) | `rg -n '"stripe"' backend-api/package.json` |
249
249
  | Engine capability enabled | `rg -n "EngineCapability.BILLING.*enabled:\s*true" wildo.saas.config.ts` |
250
- | Billing block declares provider ref | `rg -n "billing:\s*\{" -A3 backend-api/src/saas-config.backend.ts \| rg "providerRef:"` |
251
- | **Ref authored in BACKEND scope** (must return a hit) | `rg -n "backend:\s*\{" -A80 wildo.saas.config.ts \| rg "<ref>:"` |
250
+ | Billing block declares provider ref | see the commands below the table |
251
+ | **Ref authored in BACKEND scope** (must return a hit) | see the commands below the table |
252
252
  | **No second declaration** (must return NOTHING for an engine-shipped or package-shipped provider) | `rg -n "<ref>" backend-api/src/provider-contributions.ts` |
253
- | Billing scope declares both protocols | `rg -n "'BILLING_PROVIDER'.*'WEBHOOK_ORIGINATOR'\|'WEBHOOK_ORIGINATOR'.*'BILLING_PROVIDER'" wildo.saas.config.ts` |
253
+ | Billing scope declares both protocols | see the commands below the table |
254
254
  | Secrets populated (both listed under `SET`, none under `NEEDED`) | `wildo secrets list --env <env>` |
255
255
  | **Ref materialized in the artifact** (must return a hit after sync) | `rg -n "<ref>" backend-api/src/generated/wildo-provider-runtime.generated.ts` |
256
- | **No frontend-scope billing entry** (must return NOTHING — billing has no browser part) | `rg -n "frontendServices:" -A60 wildo.saas.config.ts \| rg "<ref>:"` |
256
+ | **No frontend-scope billing entry** (must return NOTHING — billing has no browser part) | see the commands below the table |
257
+
258
+ ```bash
259
+ # Billing block declares provider ref
260
+ rg -n "billing:\s*\{" -A3 backend-api/src/saas-config.backend.ts | rg "providerRef:"
261
+
262
+ # Ref authored in BACKEND scope (must return a hit)
263
+ rg -n "backend:\s*\{" -A80 wildo.saas.config.ts | rg "<ref>:"
264
+
265
+ # Billing scope declares both protocols
266
+ rg -n "'BILLING_PROVIDER'.*'WEBHOOK_ORIGINATOR'|'WEBHOOK_ORIGINATOR'.*'BILLING_PROVIDER'" wildo.saas.config.ts
267
+
268
+ # No frontend-scope billing entry (must return NOTHING — billing has no browser part)
269
+ rg -n "frontendServices:" -A60 wildo.saas.config.ts | rg "<ref>:"
270
+ ```
257
271
 
258
272
  The high-signal pair: **"ref authored in BACKEND scope"** returning empty while
259
273
  **"no frontend-scope billing entry"** returns a hit is the exact billing crash-loop
@@ -184,7 +184,9 @@ co-location conventions.
184
184
  Inspect the existing backend module's `emailTemplateDefinitions` slot before choosing a layout. The current skeleton scans compiled email directories; an older application may maintain an explicit map. Preserve the actual ownership and registration path rather than adding a parallel map with a prescribed filename.
185
185
 
186
186
  - The scanner loads `template.js` default exports and co-located `labels.<locale>.js` named `labels` exports. Author their TypeScript sources and let the normal compiler publish them; a new `.tsx` file alone is not a loaded runtime template.
187
- - The scanner's `keyFromPath` owns the template ref. The skeleton maps `system/<name>` to `system.<name_with_underscores>` and `resources/<resource>/<operation>` to `email.<resource>.<operation>`. Module-specific scanners may choose other mappings. Match the existing sender's typed ref to that mapping; creating an enum with a different value does not rename the scanned ref.
187
+ - The scanner's `keyFromPath` owns the template ref. The skeleton maps `system/<name>` to `system.<name_with_underscores>`, and under `resources/` turns the path into the ref by replacing `/` with `.`. Module-specific scanners may choose other mappings. Match the existing sender's typed ref to that mapping; creating an enum with a different value does not rename the scanned ref.
188
+ - **An operation's email (a `userNotifications` EMAIL entry) has a derived ref:** `email.<resource>.<operation>[.<variantKey>].<target>[_<customNotificationRef>]`, so its directory is `resources/<resource>/<operation>[.<variantKey>].<target>[_<customNotificationRef>]/` — for example `resources/todos/change_status.admin.users-custom_notify-creator/`. The target segment is always there, and an operation with a keyed variant needs one template per variant. A missing one only WARNS at startup (it refuses only for a token-bearing operation), and the email is silently never sent. Read `references/framework-operation-email-template-ref-api.md` before naming the directory.
189
+ - **Declare before you code.** A non-user recipient at an address on the record is `recipientEmailField`; an email owed whatever the preferences is `alwaysDeliver: true`. Send from custom code with `EmailBackendService.send` only for an attachment, several or nested addresses, cc / bcc / threading, or a non-user's own language. Read `references/framework-email-send-api.md`.
188
190
  - Contribute the resulting map through the existing owning backend module. For an explicit map, add the imported definition and locale labels there; for a scanner, put the correctly exported files under the scanned directory. Do not manually edit generated definitions or add duplicate registrations.
189
191
  - Sender services resolve the typed ref through the framework email service; they do not import and render the template directly. Identity emails remain with their identity/engine owner; business-module emails remain with the owning business module.
190
192
 
@@ -249,7 +251,7 @@ import { EmailTemplateType } from '@wildo-ai/saas-models';
249
251
  import type {
250
252
  EmailTemplateDefinition,
251
253
  EmailTemplateProps,
252
- } from '~wildo-backend-lib/notifications/email/models/email-template-definition';
254
+ } from '@wildo-ai/saas-backend-lib';
253
255
 
254
256
  export interface MinimalExampleLabels {
255
257
  subject: string;
@@ -352,6 +354,8 @@ single self-contained reference shape for app developers.
352
354
  - `references/framework-email-attachments-and-limits.md` — `attachmentFileIds`, the framework's own size cap, and why a declared vendor list is not failover
353
355
  - `references/email-artifact-paths.md` — where files live (template, labels, registry, type enum)
354
356
  - `references/framework-email-template-api.md` — `EmailTemplateDefinition<TLabels>` + `EmailTemplateDefinitionsMap` types
357
+ - `references/framework-operation-email-template-ref-api.md` — the ref an operation's `userNotifications` email renders, and the directory it lives in, with worked cases (source-backed)
358
+ - `references/framework-email-send-api.md` — when a declaration cannot express the email, and `EmailBackendService.send`'s request, outcomes and retry rule (source-backed)
355
359
  - `i18n-rerun-pipeline/SKILL.md` — translation pipeline orchestrator (Step 6 trigger)
356
360
  - `backend-addon-wiring/SKILL.md` — the module-level `emailTemplateDefinitions` slot consumer (the registry feeds into this)
357
361
 
@@ -361,6 +365,7 @@ single self-contained reference shape for app developers.
361
365
  - [ ] Labels exist for **every** user-visible string (one key per string), satisfying the typed `TLabels` interface key-for-key
362
366
  - [ ] Labels files exist for every supported locale (parallel key sets across locales)
363
367
  - [ ] Compiled template and labels resolve under the owning module’s scanner/map, and its ref matches the sender’s typed id
368
+ - [ ] An operation email's directory carries the full derived ref (`<operation>[.<variantKey>].<target>[_<customNotificationRef>]`), one per keyed variant, and startup logs no unresolved operation email
364
369
  - [ ] Definition explicitly selects `EmailTemplateType.*` and the corresponding provider capability is configured
365
370
  - [ ] Definition is typed `EmailTemplateDefinition<TLabels>` (not `any`, not bare `EmailTemplateDefinition`)
366
371
  - [ ] `subject` / `body` JSX contains **no inline strings** (every string flows through `labels`)
@@ -382,12 +387,26 @@ Run from the app root. Replace `<email-root>` with the actual owning scanner dir
382
387
  | Subject / body read from `labels.` | `rg -n "labels\.[a-zA-Z]+" <email-root>/<template>/template.tsx` |
383
388
  | Locale files exist for every supported locale | `ls <email-root>/<template>/labels.*.ts` |
384
389
  | Other-locale files are the generated ones (must return empty) | `rg --files-without-match "DO NOT EDIT THIS FILE MANUALLY" <email-root>/<template>/labels.<locale>.ts` (run for each non-primary locale) |
385
- | Owning registry/scanner and ref mapping are present | `rg -n "scanEmailTemplateDirectory\|keyFromPath\|emailTemplateDefinitions" <registry-file>` (inspect the mapping; scanned templates need no per-template map entry) |
386
- | Per-locale label files share the same key set | `comm -23 <(rg -o '\\w+:' <email-root>/<template>/labels.<primary-locale>.ts \| sort -u) <(rg -o '\\w+:' <email-root>/<template>/labels.<locale>.ts \| sort -u)` (output should be empty) |
390
+ | Owning registry/scanner and ref mapping are present | see the commands below the table (inspect the mapping; scanned templates need no per-template map entry) |
391
+ | Per-locale label files share the same key set | see the commands below the table (output should be empty) |
387
392
  | Sender resolves template by typed id | `rg -n "EmailTemplateType\.[A-Z_]+" backend-api/src/modules/<module>/` |
388
393
  | **No inline JSX text in subject / body** (must return empty) | `rg -n ">[A-Za-z][^<{}]{2,}<" <email-root>/<template>/template.tsx` |
389
- | **No app SPA imports** in the template (must return empty) | `rg -n "from\s+['\"](app|frontend)/" <email-root>/<template>/template.tsx` |
394
+ | **No app SPA imports** in the template (must return empty) | see the commands below the table |
390
395
  | **No direct template import** in sender services (must return empty) | `rg -n "from\s+['\"].*notifications/email/<template>/template['\"]" backend-api/src/modules/<module>/` |
396
+ | **Every operation email resolves** (must return empty after a backend start) | `rg -n "does not resolve through the configured primary/fallback locale chain" <backend startup log>` |
397
+
398
+ ```bash
399
+ # No app SPA imports in the template (must return empty)
400
+ rg -n "from\s+['\"](app|frontend)/" <email-root>/<template>/template.tsx
401
+ ```
402
+
403
+ ```bash
404
+ # Owning registry/scanner and ref mapping are present
405
+ rg -n "scanEmailTemplateDirectory|keyFromPath|emailTemplateDefinitions" <registry-file>
406
+
407
+ # Per-locale label files share the same key set
408
+ comm -23 <(rg -o '\w+:' <email-root>/<template>/labels.<primary-locale>.ts | sort -u) <(rg -o '\w+:' <email-root>/<template>/labels.<locale>.ts | sort -u)
409
+ ```
391
410
 
392
411
  The high-signal invariants are **"No inline JSX text in subject /
393
412
  body"** combined with **"No direct template import in sender
@@ -428,6 +447,9 @@ second guarantees the registry is the integration seam.
428
447
  import in sender services** grep — must return empty)
429
448
  - Template imports from `frontend/` (catch with the **No app SPA
430
449
  imports** grep — must return empty)
450
+ - An operation email's template whose folder does not carry the full ref (no target segment, a missing variant) —
451
+ nothing renders it, startup only warns, and the email is silently never sent (catch with the **Every operation
452
+ email resolves** check)
431
453
  - Brand color / domain hard-coded in the body (template no longer
432
454
  renders correctly across environments)
433
455
  - New label keys committed without a translation rerun (Step 6
@@ -12,6 +12,6 @@ Locate the owning backend module's `emailTemplateDefinitions` contribution first
12
12
 
13
13
  The scanner starts beside its caller's `import.meta.url`, scans its configured `subdir` recursively and uses `keyFromPath` to derive refs. Its default extension is `.js`. It imports the template's default export and the labels module's named `labels` export (also accepts `default.labels`). It does not infer refs from a new enum or inspect an arbitrary TypeScript source folder.
14
14
 
15
- In the current skeleton, `backend-api/src/engine/email/email-template-definitions.ts` scans `system/` and `resources/`. `system/password-reset` becomes `system.password_reset`; `resources/tasks/create` becomes `email.tasks.create`. The engine backend module contributes the map. Business-module email definitions should follow their existing module-owned contribution rather than being moved into the engine merely to match this example.
15
+ In the current skeleton, `backend-api/src/engine/email/email-template-definitions.ts` scans `system/` and `resources/`. `system/password-reset` becomes `system.password_reset`; under `resources/`, `/` becomes `.`, so an operation email for `tasks` / `assign` / target `USER_SELF` lives in `resources/tasks/assign.user-self` and registers `email.tasks.assign.user-self` (the full rule: `references/framework-operation-email-template-ref-api.md`). The engine backend module contributes the map. Business-module email definitions should follow their existing module-owned contribution rather than being moved into the engine merely to match this example.
16
16
 
17
17
  For an explicit map, follow its existing `EmailTemplateDefinitionsMap` shape and preserve its labels wiring. For a scanner, adding a correctly named/default-exported template and named locale exports under its root is the registration input; no per-template manual entry is required. In either case, normal compilation/publication and module loading must make the ref visible. Match the sender's typed identifier to the derived ref and verify through preview. Never hand-edit compiled artifacts to make a missing source registration appear fixed.
@@ -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.