@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
@@ -1,6 +1,6 @@
1
1
  # Framework — frontend resource UI contracts (saas-frontend-lib)
2
2
 
3
- Source-backed excerpts for `OperationKey` / typed keys, per-operation frontend config, full `ResourceUIBehaviorConfig`, and the `ResourceUIBehavior` preset map.
3
+ Source-backed excerpts for `OperationKey` / typed keys, per-operation frontend config, full `ResourceUIBehaviorConfig`, the parameters a `getFrontendResourceLabel` function receives, and the `ResourceUIBehavior` preset map.
4
4
 
5
5
  ## Import Origins
6
6
 
@@ -116,6 +116,8 @@ export enum CollectionFilterPanelVisibility {
116
116
  HIDDEN = 'hidden',
117
117
  }
118
118
 
119
+ /**
120
+ */
119
121
  /**
120
122
  * A DATE WINDOW named relative to NOW, for a preset filter that must mean the same thing tomorrow.
121
123
  *
@@ -128,39 +130,63 @@ export enum CollectionFilterPanelVisibility {
128
130
  * Resolution is in the VIEWER's timezone, which is the only one that makes "today" true for the
129
131
  * person reading the screen. The backend compares instants, so the boundaries travel as absolute
130
132
  * times and nothing downstream has to know a timezone was involved.
133
+ *
134
+ * Every window is whole local days and ends at the LAST instant of its last day, one millisecond before the next local
135
+ * midnight. The date-range filter's end bound is inclusive, and a date-only value (a due date picked in a calendar) is
136
+ * stored at the local midnight of the day it names, so ending at the next midnight would also match the day after.
131
137
  */
132
138
  export enum CollectionFilterPresetRelativeRange {
133
- /** Midnight this morning until midnight tonight, local. */
139
+ /** All of today, local: midnight this morning to the end of the day. */
134
140
  TODAY = 'today',
135
- /** The same window, one day back. */
141
+ /** All of yesterday, local. */
136
142
  YESTERDAY = 'yesterday',
137
143
  /** The last seven days INCLUDING today — the rolling week, not the last seven whole days. */
138
144
  LAST_7_DAYS = 'last_7_days',
139
145
  /** The last thirty days including today. */
140
146
  LAST_30_DAYS = 'last_30_days',
141
- /** The first of this calendar month until now. */
147
+ /** The first of this calendar month through the end of today. */
142
148
  THIS_MONTH = 'this_month',
143
- /** The first of this calendar year until now. */
149
+ /** The first of this calendar year through the end of today. */
144
150
  THIS_YEAR = 'this_year',
151
+ /**
152
+ * Everything BEFORE today, local: what an "overdue" list shows on a due-date field. Ends at the last instant of
153
+ * yesterday, so a date-only value due TODAY is due, not overdue. A deadline with a time earlier today is in TODAY, not
154
+ * here: the window is whole days, like every other member, so the pill reads the same all day.
155
+ */
156
+ BEFORE_TODAY = 'before_today',
157
+ /** Today and the six days after it, local: "due this week" from today. */
158
+ NEXT_7_DAYS = 'next_7_days',
159
+ /** Today and the twenty-nine days after it, local. */
160
+ NEXT_30_DAYS = 'next_30_days',
145
161
  }
146
162
 
147
163
  /**
148
- * What a preset ASSIGNS to one filter field.
164
+ * A value a preset can only know once it is clicked, because it depends on WHO is looking. Resolved from the
165
+ * viewer's session at that moment, like a relative range is resolved from the clock, so "My jobs" means the person
166
+ * reading the list, whoever that is.
149
167
  *
150
- * Two members, and the split is between a value that is FIXED at authoring time and one that can
151
- * only be known when the pill is clicked. A literal covers every enum value, id, number and flag —
152
- * which is the whole of "filter to HIGH priority". A relative range covers the temporal case, whose
153
- * defining property is that an authored answer would be wrong by tomorrow.
168
+ * A preset naming one is unavailable to a viewer the value cannot be resolved for (no signed-in user): the pill is
169
+ * disabled rather than applied without the field, which would show a different list under the same name.
170
+ */
171
+ export enum CollectionFilterPresetContextValue {
172
+ /** The signed-in user's id, for a reference field such as an assignee or owner. */
173
+ CURRENT_USER = 'current_user',
174
+ }
175
+
176
+ /**
177
+ * What a preset ASSIGNS to one filter field.
154
178
  *
155
- * A NUMERIC BOUND is the third, and it is the one that needed the rest of the stack before it could
156
- * mean anything: the framework's collection filters carried a date range and scalars and no numeric
157
- * range, so a preset could have declared "cost below 500" and nothing between here and the database
158
- * would have honoured it. It is expressible now because `Resources_Filter_NumberRangeSchema`, the
159
- * controller's fail-closed value guard and the cross-adapter normalizer all learned the `{ min, max }`
160
- * vocabulary — a preset assigning one is writing the same value the filter panel's own two inputs do.
179
+ * Four kinds, split by WHEN the value is known:
161
180
  *
162
- * Both bounds optional, for the same reason the schema has them optional: "under 500" is a range
163
- * with no floor, and that is the commonest threshold anyone asks for.
181
+ * - a LITERAL (string, number, boolean) is fixed at authoring time and covers every enum value, id, number and flag,
182
+ * which is the whole of "filter to HIGH priority";
183
+ * - a RELATIVE RANGE (`{ relativeRange }`) is the temporal case, resolved when the pill is clicked, because an authored
184
+ * answer would be wrong by tomorrow;
185
+ * - a NUMERIC BOUND (`{ min?, max? }`) writes the same value the filter panel's own two number inputs do, and the
186
+ * backend applies it on every adapter. Both bounds are optional because "under 500" has no floor, and that is the
187
+ * commonest threshold anyone asks for;
188
+ * - a CONTEXT VALUE (`{ contextValue }`) is known only from who is looking, such as "assigned to me", and is resolved
189
+ * when the pill is clicked, so the same authored preset shows each viewer their own rows.
164
190
  */
165
191
  export const CollectionFilterPresetValueSchema = z.union([
166
192
  z.string(),
@@ -168,6 +194,7 @@ export const CollectionFilterPresetValueSchema = z.union([
168
194
  z.boolean(),
169
195
  z.object({ relativeRange: z.enum(CollectionFilterPresetRelativeRange) }),
170
196
  z.object({ min: z.number().optional(), max: z.number().optional() }),
197
+ z.object({ contextValue: z.enum(CollectionFilterPresetContextValue) }),
171
198
  ]);
172
199
  export type CollectionFilterPresetValue = z.infer<typeof CollectionFilterPresetValueSchema>;
173
200
 
@@ -731,6 +758,8 @@ export const ResourceOperationFrontendConfigSchema = z.object({
731
758
  * presetFilters: [
732
759
  * { ref: 'urgent', filters: { priority: 'high' } },
733
760
  * { ref: 'created-today', filters: { createdAt: { relativeRange: CollectionFilterPresetRelativeRange.TODAY } } },
761
+ * { ref: 'overdue', filters: { dueAt: { relativeRange: CollectionFilterPresetRelativeRange.BEFORE_TODAY }, status: 'open' } },
762
+ * { ref: 'mine', filters: { assigneeUserId: { contextValue: CollectionFilterPresetContextValue.CURRENT_USER } } },
734
763
  * ]
735
764
  */
736
765
  presetFilters: z.array(CollectionFilterPresetSchema).optional(),
@@ -1033,7 +1062,10 @@ export type ResourceUIBehaviorConfig<
1033
1062
  * Can be either:
1034
1063
  * - `string[]` — array of field paths to concatenate (each entry is a field
1035
1064
  * name on the summary record, including any server-resolved virtual field
1036
- * such as a `forwardedLabel`, e.g. `['instanceLabel']`).
1065
+ * such as a `forwardedLabel`, e.g. `['instanceLabel']`). The present,
1066
+ * non-empty values are trimmed and joined with ONE SPACE (`['firstName',
1067
+ * 'lastName']` → "Ada Lovelace"); for any other separator, or for words,
1068
+ * use the function form.
1037
1069
  * - `(params: ResourceUIBehaviorLabelParams) => string` — a function
1038
1070
  *
1039
1071
  * Used by `ResourceListItemRenderer` (rows) and `ResourceLayout_Header` (titles).
@@ -1134,6 +1166,56 @@ export type ResourceUIBehaviorConfig<
1134
1166
 
1135
1167
  ### Origin Package: `@wildo-ai/saas-frontend-lib`
1136
1168
 
1169
+ ```typescript
1170
+ *
1171
+ * Parameters passed to a `getFrontendResourceLabel` function: what a resource's ui-behavior receives when it names one
1172
+ * record (a list row, a page title, a reference chip). Import the type from `@wildo-ai/saas-frontend-lib`.
1173
+ *
1174
+ * Words in a label come from `t`, which takes a FULL key (`resources.<type>.…`). This resource's own `resources.<type>`
1175
+ * words are always loaded; a label that also needs words from ANOTHER label section declares it in
1176
+ * `instanceLabelSections`, or `t` renders the key itself wherever that section has not been loaded. Dates go through
1177
+ * `formatDate` / `formatDateTime`, never a hand-formatted string.
1178
+ *
1179
+ * Generic `TMainSchema` defaults to `z.ZodAny` — presets and records use the
1180
+ * default (giving `currentObject: any`), while app-level configs can narrow it
1181
+ * to a concrete schema for type-safe field access.
1182
+ *
1183
+ * @example
1184
+ * // An invoice named by its number and its issue date, in the viewer's date format.
1185
+ * getFrontendResourceLabel: ({ currentObject, formatDate }) => `${currentObject.number} · ${formatDate(currentObject.issuedAt)}`,
1186
+ */
1187
+ export type ResourceUIBehaviorLabelParams<TMainSchema extends z.ZodTypeAny = z.ZodAny> = {
1188
+ currentObject: z.infer<TMainSchema>;
1189
+ objectContext: any;
1190
+ initiatorUserContext?: any;
1191
+ t: (toTranslate: string, params?: Record<string, any>) => string;
1192
+ /**
1193
+ * Formats a date the way the viewer's regional preferences (date format, timezone) render one everywhere
1194
+ * else. A label built from a date must use it: a hand-formatted `YYYY-MM-DD` agreed with the record's own
1195
+ * card only for a viewer whose preference happened to be ISO, and a different timezone could shift the day.
1196
+ */
1197
+ formatDate: (value: Date | string | number) => string;
1198
+ /**
1199
+ * `formatDate` with the time of day, for a record whose name is an instant rather than a day — an audit
1200
+ * event, where many share a date and only the time tells them apart.
1201
+ */
1202
+ formatDateTime: (value: Date | string | number) => string;
1203
+ /**
1204
+ * The resource being named. One polymorphic behavior serves several resource types (an organization's and a
1205
+ * user's billing account share one callback), and a record with no name of its own is named by ITS resource's
1206
+ * words — which only the resource type can address in the label tree.
1207
+ */
1208
+ resourceType: string;
1209
+ };
1210
+ ```
1211
+ ## Import Origins
1212
+
1213
+ - `@wildo-ai/saas-frontend-lib`
1214
+
1215
+ ## Source Excerpts
1216
+
1217
+ ### Origin Package: `@wildo-ai/saas-frontend-lib`
1218
+
1137
1219
  ```typescript
1138
1220
  *
1139
1221
  * Complete frontend resource configuration preset for an application.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: seeding-authoring
3
- description: Author a `DataSeedDefinition` end-to-end — pick the right Level (A vs B), pick the right mode (LAZY / ADDITIVE / UPGRADE / SYNC) for the row's re-run semantics, declare a stable business key on the resource schema, declare which fields the seed *owns* via `managedFields`, and (for UPGRADE) ship a migrator + rename ledger so business-key relocations preserve identity. Use when the user says "seed system email templates", "give every new organization a default workspace", "add a default dashboard the first time a user opens the dashboards list", "ship a closed enum as DB rows synced from the declaration", "deploy version 2 of the welcome template without losing user customization", or any request that produces a new `createDataSeedDefinition({...})` call site.
3
+ description: Author a `DataSeedDefinition` end-to-end — pick the right Level (A vs B), pick the right mode (LAZY / ADDITIVE / UPGRADE / SYNC) for the row's re-run semantics, declare a stable business key on the resource schema, declare which fields the seed *owns* via `managedFields`, and (for UPGRADE) ship a migrator + rename ledger so business-key relocations preserve identity. Use when the user says "seed system email templates", "give every new organization a default workspace", "add a default dashboard the first time a user opens the dashboards list", "ship a closed enum as DB rows synced from the declaration", "deploy version 2 of the welcome template without losing user customization", "link the demo contacts to the demo customers", or any request that produces a new `createDataSeedDefinition({...})` call site.
4
4
  user-invocable: false
5
5
  ---
6
6
 
@@ -26,7 +26,7 @@ into the application's database. One factory entry point
26
26
  (`createDataSeedDefinition`) drives every seed; the authoring decisions
27
27
  live entirely in its single input object.
28
28
 
29
- Five decisions, ordered by blast-radius:
29
+ Seven decisions, ordered by blast-radius:
30
30
 
31
31
  1. **Level (A vs B)** — does this seed fire from an *application
32
32
  lifecycle* event (boot, version upgrade, scheduled refresh,
@@ -46,6 +46,8 @@ Five decisions, ordered by blast-radius:
46
46
  5. **Rename ledger** — when a business-key value changes at the
47
47
  declaration site, ship a `renames[]` entry so the next pass
48
48
  relocates existing rows instead of orphaning them.
49
+ 6. **Where may the rows exist?** — demonstration data never in production.
50
+ 7. **Links to another seed's rows** — `referenceDataSeedRow(...)`, with that seed in `dependsOn`.
49
51
 
50
52
  The framework rejects almost every authoring mistake at
51
53
  `createDataSeedDefinition(...)` invocation time: missing `onOrphan`
@@ -64,7 +66,7 @@ metrics, `DataSeedRun` ledger queries) is covered by
64
66
 
65
67
  | Surface | Glob (relative to app root) |
66
68
  |----------------------------|-------------------------------------------------------------------------------------------------------------------|
67
- | Seed declaration | `backend-api/src/modules/<module>/seeds/<seed-key>.seed.ts` (recommended: one file per seed; default-export the `DataSeedDefinition`. No factory-enforced naming yet — pick a stable convention per module.) |
69
+ | Seed declaration | `backend-api/src/modules/<module>/seeds/<seedKey with ':' as '.'>.seed.ts` — `crm:demo-customers` lives in `crm.demo-customers.seed.ts`. One file per seed. A build task that produces a seed is proven landed by THIS name and by the module importing it, so follow it exactly. |
68
70
  | Module seed aggregator | `backend-api/src/modules/<module>/seeds/index.ts` (recommended: default-export `DataSeedDefinition[]` so the backend module record can `seeds: <module>Seeds`) |
69
71
  | Resource schema (business key) | `shared-lib/src/modules/<module>/resources/<resource>/<resource>.schemas.ts` (`isBusinessKey()` / `businessKeySet([...])`) |
70
72
  | Module backend record | `backend-api/src/modules/<module>/index.ts` — `seeds?: DataSeedDefinition[]` slot on the typed `BackendDomainModule` (the wrapper exposed via `BackendOwnedModule.backendModule`). Aggregated by `mergeBackendDomainModules` and threaded through `ApplicationInitializationConfig.dataSeeds`. |
@@ -72,6 +74,8 @@ metrics, `DataSeedRun` ledger queries) is covered by
72
74
  ## When to Use
73
75
 
74
76
  - Adding a new seed (any mode, any level)
77
+ - Giving a freshly created application demonstration data — sample rows
78
+ that must never reach production (Decision 6)
75
79
  - Changing the business key on a seeded resource (must ship a
76
80
  `renames[]` entry on every seed targeting that resource)
77
81
  - Bumping `version` on a UPGRADE seed (must verify migrators cover
@@ -92,7 +96,7 @@ metrics, `DataSeedRun` ledger queries) is covered by
92
96
  - Adding `__seed` overlay to user-authored data (non-seed) → the
93
97
  overlay is dispatcher-managed; never write it from app code
94
98
 
95
- ## The Five Authoring Decisions
99
+ ## The Seven Authoring Decisions
96
100
 
97
101
  ### Decision 1: Level — A vs B
98
102
 
@@ -119,6 +123,17 @@ specific resource row. The triggering row's `_id` is the natural
119
123
  > is a resource, not a deployment event). The same applies to any
120
124
  > "on creation of resource X" pattern.
121
125
 
126
+ On any level, a per-scope seed keeps STATIC entries with `anchorEntriesToScopeForeignKey: true`:
127
+ leave the scope key (`organizationId`, …) out of the business key and the engine adds the id of the
128
+ scope row being seeded. Use a computed `entry()` only when VALUES depend on the triggering row. It returns
129
+ exactly one entry per call and has no way to skip a row: a row that should exist only when a condition holds is
130
+ created by an operation, not a seed.
131
+
132
+ **A seed write runs none of the resource's operation pipeline.** The engines write through the repository, so no
133
+ custom-implementation prefix or postfix runs, no `userNotifications` email is sent, and no operation audit row is
134
+ written; the run itself is recorded in the `DataSeedRun` ledger. So an entry carries every value a prefix would have
135
+ computed (a server-owned total, a derived status) itself, and a seeded row announces nothing to anyone.
136
+
122
137
  ### Decision 2: Mode — pick by re-run semantics
123
138
 
124
139
  | Mode | Re-run safe? | Touches existing rows? | Required fields | Pick when … |
@@ -175,9 +190,8 @@ Behavioral effects:
175
190
  - The seed's `entries[*].businessKey` is matched against this shape
176
191
  (single field → object with one key; composite → object with all
177
192
  keys present).
178
- - Cross-seed references via `dependsOn[]` resolve to `_id` at
179
- dispatch time, so renaming the business key never breaks foreign
180
- keys (the DB still references `_id`, immutable).
193
+ - `dependsOn[]` only ORDERS seeds. A link to another seed's row is a `referenceDataSeedRow` by THIS
194
+ business key (Decision 7); it stores the `_id`, and a reference still using a renamed key fails.
181
195
 
182
196
  ### Decision 4: Managed fields — what the seed *owns*
183
197
 
@@ -202,23 +216,7 @@ The dispatcher writes a `__seed` overlay onto each row recording
202
216
  which fields it owns and which version owned them — this is the
203
217
  runtime side of the contract; authors only declare `managedFields[]`.
204
218
 
205
- > **Note on overlay field names** (audit L1-7, post-Phase-7
206
- > close-out): the `__seed` overlay tracks **`managedSince`**
207
- > (the wall-clock `Date` at which the framework first stamped
208
- > the row — preserved across subsequent passes by
209
- > `buildDataSeedRowMetadataForUpsert`, and only re-set when the
210
- > row is created). It does NOT carry `mode`, `runId`, or
211
- > `seededAt` — earlier drafts
212
- > of this guide and some forum discussions referenced those
213
- > names as if they were persisted on the row. They are NOT:
214
- > `mode` lives on the seed definition (not the row), `runId`
215
- > lives on `DataSeedRun` (one row per pass, not per seeded
216
- > document), and `seededAt` was renamed to `managedSince`
217
- > early in the design to clarify the "first-stamp wall-clock"
218
- > semantic. Authors should never need to read or write any of
219
- > these — the overlay is dispatcher-private — but the naming
220
- > matters for tests and for the `data-seed-row-metadata.shared.schemas.ts`
221
- > source file.
219
+ The overlay's field names (`managedSince`; no `mode`, `runId` or `seededAt`): `references/seed-row-overlay.md`.
222
220
 
223
221
  ### Decision 5: Rename ledger — preserve identity across business-key changes
224
222
 
@@ -247,6 +245,36 @@ Factory-time invariants (rejected with actionable errors):
247
245
  - `rename.to` MUST appear as a declared business-key value in
248
246
  `entries[*].businessKey` (catches typos like `'welcome-emai'`).
249
247
 
248
+ ### Decision 6: Where may these rows exist? — reference vs demonstration
249
+
250
+ | Kind | What it is | `allowedApplicationEnvironments` |
251
+ |------|------------|----------------------------------|
252
+ | Reference data | rows the application needs to work: a closed list stored as rows, a default record | OMIT — every environment, production included |
253
+ | Demonstration data | sample rows that make a fresh application look lived-in (customers, projects) | DECLARE, without `RuntimeEnvironment.PRODUCTION` — e.g. development and staging |
254
+
255
+ A restricted seed is withheld at registration in every other environment, so no trigger, schedule
256
+ or manual run reaches it there, and it is withheld when the deployment declares no environment at
257
+ all. Never mix the two kinds in one seed: the restriction applies to every row the seed writes.
258
+ For demonstration data, `ADDITIVE` with `existingRowTreatment: FILL_MISSING_DEFAULTS` is the usual
259
+ shape — people edit sample rows while trying the application, and the default treatment would
260
+ re-stamp them on every pass. Pick the trigger by where the resource lives: an application-wide
261
+ resource seeds at `ON_APP_INIT` (`APPLICATION` scope); a resource that carries `organizationId`
262
+ seeds per organization on the `organizations` `afterCreate` trigger (`ORGANIZATION` scope), with
263
+ `anchorEntriesToScopeForeignKey: true` so each organization gets its own rows. Sample rows that
264
+ point at each other (a contact's customer, a quote's customer) use Decision 7.
265
+ `RuntimeEnvironment` comes from `@wildo-ai/saas-models`.
266
+
267
+ ### Decision 7: Rows that point at another seed's rows — `referenceDataSeedRow`
268
+
269
+ `dependsOn` orders seeds and passes nothing, the engine generates `_id`, and a computed `entry()`
270
+ cannot read rows. So a foreign key to a row another seed writes is a REFERENCE —
271
+ `customerId: referenceDataSeedRow(demoCustomersSeed, { email: 'ana@example.com' })` — which the
272
+ engine resolves to that row's `_id` before writing. List the referenced seed in `dependsOn` (the
273
+ factory refuses a static reference that is not). Nothing is ever written with a null or placeholder
274
+ key: an unresolved reference in `data` fails that entry, one in `businessKey` fails the whole run.
275
+ Read `references/cross-seed-row-references.md` (scope fill-in, environments, cross-tenant refusal)
276
+ before writing one.
277
+
250
278
  ## Workflow
251
279
 
252
280
  ### Step 1: Confirm the resource has a business key
@@ -337,13 +365,15 @@ dedicated example file co-located with the runtime contract:
337
365
  ## Usage Example
338
366
 
339
367
  ```typescript
368
+ import { RuntimeEnvironment } from '@wildo-ai/saas-models';
340
369
  import {
341
370
  createDataSeedDefinition,
371
+ DataSeedExistingRowTreatment,
342
372
  DataSeedMode,
343
373
  DataSeedResourceLifecyclePhase,
344
374
  DataSeedScopeKind,
345
375
  DataSeedTriggerKind,
346
- } from '~wildo-backend-lib/data-seeding/models/data-seed.shared.schemas';
376
+ } from '@wildo-ai/saas-backend-lib/data-seeding-models';
347
377
 
348
378
  // ─────────────────────────────────────────────────────────────────────
349
379
  // Level-A example — UPGRADE on app version upgrade.
@@ -401,7 +431,11 @@ const systemEmailTemplatesSeed = createDataSeedDefinition({
401
431
  // Level-B example — ADDITIVE on Organization afterCreate.
402
432
  // "When an Organization is created, spawn its default Workspace once."
403
433
  // Computed `entry` lets the seed read the triggering row's `_id` and
404
- // the audit `triggeredByUserId` for attribution. ADDITIVE is safe to
434
+ // the audit `triggeredByUserId` for attribution. The organization's id
435
+ // goes in the BUSINESS KEY: every organization has its own default
436
+ // workspace, so the organization is part of that row's identity (a key
437
+ // of `workspaceKey` alone would make every organization share one row).
438
+ // ADDITIVE is safe to
405
439
  // re-run: the dispatcher inspects `DataSeedRun` keyed on
406
440
  // `(seedKey, scopeKind, relatedId)` and skips on COMPLETED.
407
441
  //
@@ -413,15 +447,12 @@ const systemEmailTemplatesSeed = createDataSeedDefinition({
413
447
  // ─────────────────────────────────────────────────────────────────────
414
448
  const organizationDefaultWorkspaceSeed = createDataSeedDefinition({
415
449
  seedKey: 'tasks-manager:org-default-workspace',
416
- scope: {
417
- kind: DataSeedScopeKind.CUSTOM,
418
- relatedResourceType: 'organization',
419
- },
450
+ scope: { kind: DataSeedScopeKind.ORGANIZATION },
420
451
  resourceType: 'workspace',
421
452
  triggers: [
422
453
  {
423
454
  triggerKind: DataSeedTriggerKind.RESOURCE_LIFECYCLE,
424
- resourceType: 'organization',
455
+ resourceType: 'organizations',
425
456
  phase: DataSeedResourceLifecyclePhase.AFTER_CREATE,
426
457
  },
427
458
  ],
@@ -434,18 +465,129 @@ const organizationDefaultWorkspaceSeed = createDataSeedDefinition({
434
465
  // DOES project through it, and rejects an empty list) or `SYNC`. See
435
466
  // the `DataSeedMode` JSDoc for the full mode-by-mode contract.
436
467
  entry: ({ triggeringRow, executionContext }) => ({
437
- businessKey: { workspaceKey: 'default' },
468
+ // The workspace resource declares `businessKeySet(['organizationId', 'workspaceKey'])`.
469
+ businessKey: { organizationId: triggeringRow?._id, workspaceKey: 'default' },
438
470
  data: {
439
- organizationId: triggeringRow?._id,
440
471
  name: 'My Workspace',
441
472
  ownerId: executionContext.triggeredByUserId,
442
473
  },
443
474
  }),
444
475
  });
445
476
 
446
- export { organizationDefaultWorkspaceSeed, systemEmailTemplatesSeed };
477
+ // ─────────────────────────────────────────────────────────────────────
478
+ // Demonstration data — sample rows that make a freshly created application
479
+ // look lived-in, kept OUT of production by `allowedApplicationEnvironments`.
480
+ // Without it these customers would be inserted beside real ones the first
481
+ // time the application starts in production. A restricted seed is withheld
482
+ // at registration, so no trigger, schedule or manual run can reach it there.
483
+ //
484
+ // `FILL_MISSING_DEFAULTS`: a person edits demo rows while trying the app, and
485
+ // the default treatment would re-stamp the declared payload over their edits
486
+ // on every pass.
487
+ // ─────────────────────────────────────────────────────────────────────
488
+ const demoCustomersSeed = createDataSeedDefinition({
489
+ seedKey: 'crm:demo-customers',
490
+ scope: { kind: DataSeedScopeKind.APPLICATION },
491
+ resourceType: 'customer',
492
+ triggers: [{ triggerKind: DataSeedTriggerKind.ON_APP_INIT }],
493
+ mode: DataSeedMode.ADDITIVE,
494
+ version: 1,
495
+ existingRowTreatment: DataSeedExistingRowTreatment.FILL_MISSING_DEFAULTS,
496
+ allowedApplicationEnvironments: [RuntimeEnvironment.DEVELOPMENT, RuntimeEnvironment.STAGING],
497
+ entries: [
498
+ { businessKey: { email: 'ana.martin@example.com' }, data: { name: 'Ana Martin', company: 'Martin Renovations' } },
499
+ { businessKey: { email: 'luc.bernard@example.com' }, data: { name: 'Luc Bernard', company: 'Bernard Plumbing' } },
500
+ ],
501
+ });
502
+
503
+ export { demoCustomersSeed, organizationDefaultWorkspaceSeed, systemEmailTemplatesSeed };
447
504
  ```
448
505
 
506
+ Demonstration rows that point at each other (Decision 7) — per-organization demo customers, and
507
+ demo contacts each linked to one of them:
508
+
509
+
510
+ ## Usage Example
511
+
512
+ ```typescript
513
+ import { RuntimeEnvironment } from '@wildo-ai/saas-models';
514
+ import {
515
+ createDataSeedDefinition,
516
+ DataSeedExistingRowTreatment,
517
+ DataSeedMode,
518
+ DataSeedResourceLifecyclePhase,
519
+ DataSeedScopeKind,
520
+ DataSeedTriggerKind,
521
+ referenceDataSeedRow,
522
+ type DataSeedTrigger,
523
+ } from '@wildo-ai/saas-backend-lib/data-seeding-models';
524
+
525
+ // Every new organization gets its own sample rows; production never gets any.
526
+ const ON_ORGANIZATION_CREATED: DataSeedTrigger[] = [{
527
+ triggerKind: DataSeedTriggerKind.RESOURCE_LIFECYCLE,
528
+ resourceType: 'organizations',
529
+ phase: DataSeedResourceLifecyclePhase.AFTER_CREATE,
530
+ }];
531
+ const DEMONSTRATION_ONLY = [RuntimeEnvironment.DEVELOPMENT, RuntimeEnvironment.STAGING];
532
+
533
+ // ─────────────────────────────────────────────────────────────────────
534
+ // The referenced seed. Its resource's business key is
535
+ // `businessKeySet(['organizationId', 'email'])`; the entries name only
536
+ // `email`, and `anchorEntriesToScopeForeignKey` adds the organization.
537
+ // ─────────────────────────────────────────────────────────────────────
538
+ const demoCustomersSeed = createDataSeedDefinition({
539
+ seedKey: 'crm:demo-customers',
540
+ scope: { kind: DataSeedScopeKind.ORGANIZATION },
541
+ resourceType: 'customers',
542
+ triggers: ON_ORGANIZATION_CREATED,
543
+ mode: DataSeedMode.ADDITIVE,
544
+ version: 1,
545
+ existingRowTreatment: DataSeedExistingRowTreatment.FILL_MISSING_DEFAULTS,
546
+ allowedApplicationEnvironments: DEMONSTRATION_ONLY,
547
+ anchorEntriesToScopeForeignKey: true,
548
+ entries: [
549
+ { businessKey: { email: 'ana.martin@example.com' }, data: { name: 'Ana Martin' } },
550
+ { businessKey: { email: 'office@becker.example.com' }, data: { name: 'Becker Hausverwaltung GmbH' } },
551
+ ],
552
+ });
553
+
554
+ // ─────────────────────────────────────────────────────────────────────
555
+ // The referring seed. `customerId` is a REFERENCE, not a value: the
556
+ // engine replaces it with the customer row's `_id` before writing. The
557
+ // reference omits `organizationId` — both seeds are ORGANIZATION-scoped,
558
+ // so the engine fills in the organization being seeded. A contact whose
559
+ // customer row does not exist is reported on the run and not written.
560
+ // ─────────────────────────────────────────────────────────────────────
561
+ const demoContactsSeed = createDataSeedDefinition({
562
+ seedKey: 'crm:demo-contacts',
563
+ scope: { kind: DataSeedScopeKind.ORGANIZATION },
564
+ resourceType: 'contacts',
565
+ triggers: ON_ORGANIZATION_CREATED,
566
+ mode: DataSeedMode.ADDITIVE,
567
+ version: 1,
568
+ existingRowTreatment: DataSeedExistingRowTreatment.FILL_MISSING_DEFAULTS,
569
+ allowedApplicationEnvironments: DEMONSTRATION_ONLY,
570
+ anchorEntriesToScopeForeignKey: true,
571
+ // Required for every seed an entry references: it is what runs the customers first.
572
+ dependsOn: [{ seedKey: demoCustomersSeed.seedKey }],
573
+ entries: [
574
+ {
575
+ businessKey: { email: 'ana@martin.example.com' },
576
+ data: { firstName: 'Ana', customerId: referenceDataSeedRow(demoCustomersSeed, { email: 'ana.martin@example.com' }) },
577
+ },
578
+ {
579
+ businessKey: { email: 'jonas.becker@becker.example.com' },
580
+ data: { firstName: 'Jonas', customerId: referenceDataSeedRow(demoCustomersSeed, { email: 'office@becker.example.com' }) },
581
+ },
582
+ ],
583
+ });
584
+
585
+ export { demoContactsSeed, demoCustomersSeed };
586
+ ```
587
+
588
+ The contact seed lists the customer seed in `dependsOn` and references customers by `email` only:
589
+ both seeds are `ORGANIZATION`-scoped, so the engine adds the organization being seeded.
590
+
449
591
  What earns its place in this block:
450
592
 
451
593
  - **Stable `seedKey` with module prefix** —
@@ -453,10 +595,9 @@ What earns its place in this block:
453
595
  `'tasks-manager:org-default-workspace'`. The colon segments are
454
596
  convention; the dispatcher only requires non-empty.
455
597
  - **Explicit `scope`** discriminated by `kind`. Level-A seeds for
456
- per-application data use `APPLICATION`. Level-B seeds tied to a
457
- resource row use `CUSTOM` with `relatedResourceType` (here
458
- `'organization'`), so the dispatcher knows to materialize one
459
- pass per Organization row.
598
+ per-application data use `APPLICATION`; the Level-B organization seed
599
+ uses `ORGANIZATION` on the `organizations` trigger, and keys its row by
600
+ the organization so each one gets its own.
460
601
  - **Mode-appropriate fields**: UPGRADE ships `managedFields` +
461
602
  `migrators.fromVersion[1]` + `renames`. ADDITIVE has no
462
603
  `managedFields` because the writer bypasses that projection on
@@ -493,6 +634,10 @@ What is **not** in this block (and shouldn't be):
493
634
  - `references/framework-data-seeding-api.md` — `DataSeedMode` enum +
494
635
  `DataSeedDefinitionInput` interface (the canonical authoring
495
636
  surface — what every field means, what's required for each mode)
637
+ - `references/cross-seed-row-references.md` — every rule of
638
+ `referenceDataSeedRow` (Decision 7): ordering, scope fill-in, failure
639
+ classes, what is not supported
640
+ - `references/seed-row-overlay.md` — the `__seed` overlay's field names
496
641
  - `references/data-seeding-mode-picker.md` — extended decision tree
497
642
  for Decision 2 (mode picker) with worked failure modes for each
498
643
  mode
@@ -509,6 +654,8 @@ What is **not** in this block (and shouldn't be):
509
654
  - [ ] SYNC seeds declare `onOrphan` explicitly
510
655
  - [ ] `renames[*].field` is a business-key field on the resource
511
656
  - [ ] `renames[*].to` matches a declared `entries[*].businessKey[field]`
657
+ - [ ] A demonstration seed declares `allowedApplicationEnvironments` without `production`; a reference seed omits it
658
+ - [ ] A foreign key to another seed's row is a `referenceDataSeedRow(...)` (never unset or a placeholder) and that seed is in `dependsOn`
512
659
  - [ ] Seed surfaced on the module's `BackendDomainModule.seeds?: DataSeedDefinition[]` slot
513
660
  (aggregated by `mergeBackendDomainModules` and threaded into the assembly's `dataSeeds`)
514
661
 
@@ -521,8 +668,18 @@ Run from the app root, substituting `<module>` and `<seed-key>`:
521
668
  | Seed file uses `createDataSeedDefinition` | `rg -n 'createDataSeedDefinition' backend-api/src/modules/<module>/` |
522
669
  | Seed file imports the factory from the focused subpath | `rg -n "from '@wildo-ai/saas-backend-lib/data-seeding-models'" backend-api/src/modules/<module>/` |
523
670
  | Seed file does NOT import from the package root | `rg -n "from '@wildo-ai/saas-backend-lib'" backend-api/src/modules/<module>/seeds/` (must be empty for seed files) |
524
- | Resource schema declares a business key | `rg -n 'isBusinessKey\(\)\|businessKeySet\(' shared-lib/src/modules/<module>/resources/<resource>/<resource>.schemas.ts` |
671
+ | Resource schema declares a business key | see the commands below the table |
525
672
  | Module record wires `seeds` | `rg -n '\bseeds\s*:' backend-api/src/modules/<module>/index.ts` |
673
+ | A seed using references lists its `dependsOn` | see the commands below the table (must be empty) |
674
+ | Demonstration seeds are kept out of production | `rg --files-without-match 'allowedApplicationEnvironments' backend-api/src/modules/<module>/seeds/*demo*.seed.ts` (must be empty); `rg -n 'RuntimeEnvironment.PRODUCTION' backend-api/src/modules/<module>/seeds/*demo*.seed.ts` (must be empty) |
675
+
676
+ ```bash
677
+ # Resource schema declares a business key
678
+ rg -n 'isBusinessKey\(\)|businessKeySet\(' shared-lib/src/modules/<module>/resources/<resource>/<resource>.schemas.ts
679
+
680
+ # A seed using references lists its `dependsOn`
681
+ rg -l 'referenceDataSeedRow' backend-api/src/modules/<module>/seeds/ | xargs rg --files-without-match 'dependsOn'
682
+ ```
526
683
 
527
684
  The high-signal invariants are **"resource schema declares a
528
685
  business key"** combined with **"seed file uses
@@ -539,6 +696,8 @@ with an actionable error.
539
696
  | "I'll declare `triggers` AND `lazyAccess` to be safe" | Factory rejects (Phase 5 audit F-2/F-12/F-18: single declaration site). The auto-injection is the contract; double-declaring just creates divergence surface. |
540
697
  | "I'll default `onOrphan: REPORT` for SYNC" | The framework refuses to default destructive policies (D3). Each option (`DELETE` / `DEPRECATE` / `REPORT`) has a different operational blast-radius; the developer must pick deliberately per seed. |
541
698
  | "I'll rename the resource field directly without a `renames` entry" | Without the rename ledger, the next pass inserts a duplicate at the new business-key value and orphans the existing row (SYNC) or leaves it unowned (UPGRADE / ADDITIVE). Always ship the ledger entry in the same commit as the value change. |
699
+ | "The contact seed can't know the customer's `_id`, so I'll leave `customerId` unset" | Use `referenceDataSeedRow(customersSeed, { …businessKey })` and list the customer seed in `dependsOn`: the engine resolves it to the row's `_id`. An unset or placeholder foreign key is a demo that shows unlinked records. |
700
+ | "`dependsOn` resolves the link for me" | `dependsOn` only orders the seeds. Without a `referenceDataSeedRow` value nothing writes the foreign key. |
542
701
  | "I don't need `version` to bump for this UPGRADE" | UPGRADE re-applies `managedFields` only when `seedVersion < declared` — without bumping, existing rows skip the upgrade. Bump per material change. |
543
702
 
544
703
  ## Red Flags
@@ -560,8 +719,12 @@ with an actionable error.
560
719
  - Seed declared on a resource with cascade-delete relationships and
561
720
  no `onOrphan: REPORT` first pass to confirm the orphan set is
562
721
  empty
722
+ - A demonstration seed with no `allowedApplicationEnvironments`, or one that lists
723
+ production (its sample rows land beside real ones; catch with the demonstration-seed grep above)
563
724
  - `schedule.cron` declared on a LAZY seed (factory rejects — LAZY's
564
725
  contract is "first access creates the row, never re-applied")
726
+ - A demo seed whose foreign key to another seeded row is unset, `null` or hard-coded (Decision 7)
727
+ - `referenceDataSeedRow` in a seed without `dependsOn` (catch with the references grep above)
565
728
 
566
729
  ## Related Skills
567
730