@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
@@ -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`
@@ -94,7 +96,7 @@ metrics, `DataSeedRun` ledger queries) is covered by
94
96
  - Adding `__seed` overlay to user-authored data (non-seed) → the
95
97
  overlay is dispatcher-managed; never write it from app code
96
98
 
97
- ## The Six Authoring Decisions
99
+ ## The Seven Authoring Decisions
98
100
 
99
101
  ### Decision 1: Level — A vs B
100
102
 
@@ -121,6 +123,17 @@ specific resource row. The triggering row's `_id` is the natural
121
123
  > is a resource, not a deployment event). The same applies to any
122
124
  > "on creation of resource X" pattern.
123
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
+
124
137
  ### Decision 2: Mode — pick by re-run semantics
125
138
 
126
139
  | Mode | Re-run safe? | Touches existing rows? | Required fields | Pick when … |
@@ -177,9 +190,8 @@ Behavioral effects:
177
190
  - The seed's `entries[*].businessKey` is matched against this shape
178
191
  (single field → object with one key; composite → object with all
179
192
  keys present).
180
- - Cross-seed references via `dependsOn[]` resolve to `_id` at
181
- dispatch time, so renaming the business key never breaks foreign
182
- 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.
183
195
 
184
196
  ### Decision 4: Managed fields — what the seed *owns*
185
197
 
@@ -204,23 +216,7 @@ The dispatcher writes a `__seed` overlay onto each row recording
204
216
  which fields it owns and which version owned them — this is the
205
217
  runtime side of the contract; authors only declare `managedFields[]`.
206
218
 
207
- > **Note on overlay field names** (audit L1-7, post-Phase-7
208
- > close-out): the `__seed` overlay tracks **`managedSince`**
209
- > (the wall-clock `Date` at which the framework first stamped
210
- > the row — preserved across subsequent passes by
211
- > `buildDataSeedRowMetadataForUpsert`, and only re-set when the
212
- > row is created). It does NOT carry `mode`, `runId`, or
213
- > `seededAt` — earlier drafts
214
- > of this guide and some forum discussions referenced those
215
- > names as if they were persisted on the row. They are NOT:
216
- > `mode` lives on the seed definition (not the row), `runId`
217
- > lives on `DataSeedRun` (one row per pass, not per seeded
218
- > document), and `seededAt` was renamed to `managedSince`
219
- > early in the design to clarify the "first-stamp wall-clock"
220
- > semantic. Authors should never need to read or write any of
221
- > these — the overlay is dispatcher-private — but the naming
222
- > matters for tests and for the `data-seed-row-metadata.shared.schemas.ts`
223
- > source file.
219
+ The overlay's field names (`managedSince`; no `mode`, `runId` or `seededAt`): `references/seed-row-overlay.md`.
224
220
 
225
221
  ### Decision 5: Rename ledger — preserve identity across business-key changes
226
222
 
@@ -259,9 +255,25 @@ Factory-time invariants (rejected with actionable errors):
259
255
  A restricted seed is withheld at registration in every other environment, so no trigger, schedule
260
256
  or manual run reaches it there, and it is withheld when the deployment declares no environment at
261
257
  all. Never mix the two kinds in one seed: the restriction applies to every row the seed writes.
262
- For demonstration data, `ADDITIVE` at `ON_APP_INIT` with `existingRowTreatment: FILL_MISSING_DEFAULTS`
263
- is the usual shape — people edit sample rows while trying the application, and the default
264
- treatment would re-stamp them on every pass. `RuntimeEnvironment` comes from `@wildo-ai/saas-models`.
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.
265
277
 
266
278
  ## Workflow
267
279
 
@@ -361,7 +373,7 @@ import {
361
373
  DataSeedResourceLifecyclePhase,
362
374
  DataSeedScopeKind,
363
375
  DataSeedTriggerKind,
364
- } from '~wildo-backend-lib/data-seeding/models/data-seed.shared.schemas';
376
+ } from '@wildo-ai/saas-backend-lib/data-seeding-models';
365
377
 
366
378
  // ─────────────────────────────────────────────────────────────────────
367
379
  // Level-A example — UPGRADE on app version upgrade.
@@ -419,7 +431,11 @@ const systemEmailTemplatesSeed = createDataSeedDefinition({
419
431
  // Level-B example — ADDITIVE on Organization afterCreate.
420
432
  // "When an Organization is created, spawn its default Workspace once."
421
433
  // Computed `entry` lets the seed read the triggering row's `_id` and
422
- // 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
423
439
  // re-run: the dispatcher inspects `DataSeedRun` keyed on
424
440
  // `(seedKey, scopeKind, relatedId)` and skips on COMPLETED.
425
441
  //
@@ -431,15 +447,12 @@ const systemEmailTemplatesSeed = createDataSeedDefinition({
431
447
  // ─────────────────────────────────────────────────────────────────────
432
448
  const organizationDefaultWorkspaceSeed = createDataSeedDefinition({
433
449
  seedKey: 'tasks-manager:org-default-workspace',
434
- scope: {
435
- kind: DataSeedScopeKind.CUSTOM,
436
- relatedResourceType: 'organization',
437
- },
450
+ scope: { kind: DataSeedScopeKind.ORGANIZATION },
438
451
  resourceType: 'workspace',
439
452
  triggers: [
440
453
  {
441
454
  triggerKind: DataSeedTriggerKind.RESOURCE_LIFECYCLE,
442
- resourceType: 'organization',
455
+ resourceType: 'organizations',
443
456
  phase: DataSeedResourceLifecyclePhase.AFTER_CREATE,
444
457
  },
445
458
  ],
@@ -452,9 +465,9 @@ const organizationDefaultWorkspaceSeed = createDataSeedDefinition({
452
465
  // DOES project through it, and rejects an empty list) or `SYNC`. See
453
466
  // the `DataSeedMode` JSDoc for the full mode-by-mode contract.
454
467
  entry: ({ triggeringRow, executionContext }) => ({
455
- businessKey: { workspaceKey: 'default' },
468
+ // The workspace resource declares `businessKeySet(['organizationId', 'workspaceKey'])`.
469
+ businessKey: { organizationId: triggeringRow?._id, workspaceKey: 'default' },
456
470
  data: {
457
- organizationId: triggeringRow?._id,
458
471
  name: 'My Workspace',
459
472
  ownerId: executionContext.triggeredByUserId,
460
473
  },
@@ -490,6 +503,91 @@ const demoCustomersSeed = createDataSeedDefinition({
490
503
  export { demoCustomersSeed, organizationDefaultWorkspaceSeed, systemEmailTemplatesSeed };
491
504
  ```
492
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
+
493
591
  What earns its place in this block:
494
592
 
495
593
  - **Stable `seedKey` with module prefix** —
@@ -497,10 +595,9 @@ What earns its place in this block:
497
595
  `'tasks-manager:org-default-workspace'`. The colon segments are
498
596
  convention; the dispatcher only requires non-empty.
499
597
  - **Explicit `scope`** discriminated by `kind`. Level-A seeds for
500
- per-application data use `APPLICATION`. Level-B seeds tied to a
501
- resource row use `CUSTOM` with `relatedResourceType` (here
502
- `'organization'`), so the dispatcher knows to materialize one
503
- 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.
504
601
  - **Mode-appropriate fields**: UPGRADE ships `managedFields` +
505
602
  `migrators.fromVersion[1]` + `renames`. ADDITIVE has no
506
603
  `managedFields` because the writer bypasses that projection on
@@ -537,6 +634,10 @@ What is **not** in this block (and shouldn't be):
537
634
  - `references/framework-data-seeding-api.md` — `DataSeedMode` enum +
538
635
  `DataSeedDefinitionInput` interface (the canonical authoring
539
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
540
641
  - `references/data-seeding-mode-picker.md` — extended decision tree
541
642
  for Decision 2 (mode picker) with worked failure modes for each
542
643
  mode
@@ -554,6 +655,7 @@ What is **not** in this block (and shouldn't be):
554
655
  - [ ] `renames[*].field` is a business-key field on the resource
555
656
  - [ ] `renames[*].to` matches a declared `entries[*].businessKey[field]`
556
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`
557
659
  - [ ] Seed surfaced on the module's `BackendDomainModule.seeds?: DataSeedDefinition[]` slot
558
660
  (aggregated by `mergeBackendDomainModules` and threaded into the assembly's `dataSeeds`)
559
661
 
@@ -566,10 +668,19 @@ Run from the app root, substituting `<module>` and `<seed-key>`:
566
668
  | Seed file uses `createDataSeedDefinition` | `rg -n 'createDataSeedDefinition' backend-api/src/modules/<module>/` |
567
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>/` |
568
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) |
569
- | 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 |
570
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) |
571
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) |
572
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
+ ```
683
+
573
684
  The high-signal invariants are **"resource schema declares a
574
685
  business key"** combined with **"seed file uses
575
686
  `createDataSeedDefinition`"** — without the schema marker, the
@@ -585,6 +696,8 @@ with an actionable error.
585
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. |
586
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. |
587
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. |
588
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. |
589
702
 
590
703
  ## Red Flags
@@ -610,6 +723,8 @@ with an actionable error.
610
723
  production (its sample rows land beside real ones; catch with the demonstration-seed grep above)
611
724
  - `schedule.cron` declared on a LAZY seed (factory rejects — LAZY's
612
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)
613
728
 
614
729
  ## Related Skills
615
730
 
@@ -0,0 +1,67 @@
1
+ # Cross-seed row references — `referenceDataSeedRow`
2
+
3
+ Read this before a seed writes a foreign key to a row ANOTHER seed creates: a demonstration contact's
4
+ customer, a quote's customer, an invoice's job, a catalog item's category.
5
+
6
+ ## Why a reference, and not a value
7
+
8
+ The engine generates every seeded row's `_id`, so no seed can write another seed's row id as a
9
+ literal. `dependsOn` only ORDERS seeds — it passes no data — and a computed `entry()` receives the
10
+ triggering row and nothing else; it cannot look rows up. A reference is the one way to say "the
11
+ `_id` of THAT row":
12
+
13
+ ```ts
14
+ customerId: referenceDataSeedRow(demoCustomersSeed, { email: 'ana.martin@example.com' })
15
+ ```
16
+
17
+ The first argument is the target seed's DEFINITION (import it from the module that declares it), so
18
+ a typo is a compile error. The second is the target row's business key, as the target resource
19
+ declares it (`isBusinessKey()` / `businessKeySet([...])`). The engine replaces the reference with the
20
+ row's `_id` before the seed writes anything.
21
+
22
+ ## The rules
23
+
24
+ | # | Rule | Enforced by |
25
+ |---|------|-------------|
26
+ | 1 | The referenced seed is listed in the referring seed's `dependsOn`. That edge is what runs it first. | `createDataSeedDefinition` refuses a static entry; a computed `entry()` fails its run with a CONFIGURATION error |
27
+ | 2 | A seed referencing a seed restricted by `allowedApplicationEnvironments` (a demonstration seed) is restricted to environments that seed runs in. Elsewhere the referenced seed is withheld and its rows never exist. | `createDataSeedDefinition` (static) and the engine (computed) |
28
+ | 3 | A seed never references its own entries. References resolve before the seed writes, so its own rows are not there yet. Split the rows into two seeds. | the factory (static) and the engine (computed) |
29
+ | 4 | When both seeds have the same scope kind, leave the scope key out of the reference. The engine fills in the scope being seeded (`organizationId` on an organization `afterCreate`), and only when the target resource's business key contains that field. | the engine |
30
+ | 5 | A reference that names ANOTHER scope's id (`organizationId: 'org-2'` while seeding `org-1`) is refused, and so is a found row that belongs to another scope — which a target keyed without its scope field can return. Either would link one tenant's row to another's. | the engine, as an unresolved reference |
31
+ | 6 | The referenced row must exist. A reference in `data` that resolves to nothing fails THAT entry: it is reported on the run (`DataSeedRun.failureReport`, status PARTIAL) and not written, and the other entries are. A reference in `businessKey` that resolves to nothing fails the WHOLE run before anything is written, because the row's identity is unknown. | the engine |
32
+
33
+ Nothing is ever written with a `null` or a placeholder foreign key.
34
+
35
+ ## Where a reference may sit
36
+
37
+ - In static `entries` and in a computed `entry()`.
38
+ - In `data` and in `businessKey` — a junction row keyed by the two ids it joins puts both
39
+ references in its business key.
40
+ - Directly as a field value, or inside nested objects and arrays (`tagIds: [ref, ref]`).
41
+ - In every mode (`ADDITIVE`, `UPGRADE`, `SYNC`, `LAZY`) and on every trigger level, including manual
42
+ reruns.
43
+
44
+ ## Reading a failure
45
+
46
+ An unresolved reference names everything needed to fix it:
47
+
48
+ ```text
49
+ seed 'crm:demo-contacts' did not write this entry: a reference in its data resolves to no row.
50
+ data.customerId → seed 'crm:demo-customers' row {"email":"ana@example.com"}:
51
+ no 'customers' row has the business key {"email":"ana@example.com","organizationId":"…"}.
52
+ ```
53
+
54
+ Check, in order: that the referenced seed ran for this scope (it is in `dependsOn`, so it ran first
55
+ in the same pass unless it failed — its own run says so), and that one of its entries has exactly
56
+ this business key.
57
+
58
+ ## Not supported
59
+
60
+ - **A seed referencing its own rows** (a category tree in one seed). Split the levels into two seeds.
61
+ - **A reference across scope kinds whose target key holds the target's scope id** — an `ORGANIZATION`
62
+ seed naming an `APPLICATION`-scoped catalog row keyed `(applicationId, code)`. The scope id is filled
63
+ in only when both seeds have the same scope kind, and a static entry cannot write the application's
64
+ id, so such a reference never resolves. Seed the linking rows at the target's scope kind, or key the
65
+ target by fields that do not include its scope.
66
+ - **A reference resolved later**, once the target appears. A reference resolves when the referring
67
+ seed runs, and fails if the row is not there then. Order the seeds with `dependsOn`.