@wildo-ai/framework-knowledge 1.1.8 → 1.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (480) hide show
  1. package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
  2. package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
  3. package/dist/claude-marketplace/plugins/wildo/references/acceptance.md +11 -0
  4. package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +9 -2
  5. package/dist/claude-marketplace/plugins/wildo/references/creation-state.md +21 -0
  6. package/dist/claude-marketplace/plugins/wildo/references/derived-artifacts.md +121 -0
  7. package/dist/claude-marketplace/plugins/wildo/references/expert-personas-and-deliberations.md +26 -7
  8. package/dist/claude-marketplace/plugins/wildo/references/runs-judges-and-questions.md +31 -5
  9. package/dist/claude-marketplace/plugins/wildo/skills/accept/SKILL.md +4 -2
  10. package/dist/claude-marketplace/plugins/wildo/skills/answer/SKILL.md +29 -2
  11. package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +69 -24
  12. package/dist/claude-marketplace/plugins/wildo/skills/doctor/SKILL.md +10 -0
  13. package/dist/claude-marketplace/plugins/wildo/skills/run/SKILL.md +21 -5
  14. package/dist/claude-marketplace/plugins/wildo/skills/start/SKILL.md +31 -5
  15. package/dist/claude-marketplace/plugins/wildo/skills/status/SKILL.md +2 -0
  16. package/dist/claude-marketplace/plugins/wildo/skills/why/SKILL.md +20 -4
  17. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  18. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  19. package/dist/esm/framework-knowledge.definitions.js +95 -5
  20. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  21. package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
  22. package/dist/esm/index.d.ts.map +1 -1
  23. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +2 -2
  24. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -1
  25. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +2 -2
  26. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  27. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts +11 -11
  28. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts.map +1 -1
  29. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js +29 -22
  30. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js.map +1 -1
  31. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +41 -3
  32. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -1
  33. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +175 -14
  34. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
  35. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +1 -1
  36. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
  37. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +3 -3
  38. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
  39. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +1 -1
  40. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +1 -1
  41. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -1
  42. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts +8 -4
  43. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts.map +1 -1
  44. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js +13 -6
  45. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js.map +1 -1
  46. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +4 -2
  47. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
  48. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +90 -13
  49. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
  50. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts +4 -3
  51. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts.map +1 -1
  52. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js +4 -3
  53. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js.map +1 -1
  54. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +8 -0
  55. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
  56. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +12 -4
  57. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
  58. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +12 -3
  59. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
  60. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +8 -4
  61. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
  62. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts +4 -1
  63. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts.map +1 -1
  64. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js +2 -1
  65. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js.map +1 -1
  66. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts.map +1 -1
  67. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts.map +1 -1
  68. package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.d.ts.map +1 -1
  69. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts.map +1 -1
  70. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
  71. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +1 -1
  72. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -1
  73. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +13 -1
  74. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
  75. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts.map +1 -1
  76. package/dist/esm/playbooks/refinement.governance-document-candidate/playbook.definition.d.ts.map +1 -1
  77. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +25 -27
  78. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
  79. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +91 -43
  80. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
  81. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts +41 -0
  82. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts.map +1 -0
  83. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js +43 -0
  84. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js.map +1 -0
  85. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts +200 -0
  86. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts.map +1 -0
  87. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js +203 -0
  88. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js.map +1 -0
  89. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts +81 -0
  90. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts.map +1 -0
  91. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js +93 -0
  92. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js.map +1 -0
  93. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +3 -1
  94. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
  95. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +27 -18
  96. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
  97. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
  98. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts +11 -1
  99. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -1
  100. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js +11 -11
  101. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js.map +1 -1
  102. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +2 -0
  103. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -1
  104. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +3 -1
  105. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -1
  106. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  107. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +2 -0
  108. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
  109. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +3 -1
  110. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -1
  111. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -1
  112. package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts +5 -2
  113. package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts.map +1 -1
  114. package/dist/esm/playbooks/top_down.definition/playbook.definition.js +16 -4
  115. package/dist/esm/playbooks/top_down.definition/playbook.definition.js.map +1 -1
  116. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts +27 -6
  117. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts.map +1 -1
  118. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js +32 -12
  119. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js.map +1 -1
  120. package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.d.ts.map +1 -1
  121. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
  122. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  123. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -1
  124. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +2 -1
  125. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
  126. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +13 -5
  127. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
  128. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +7 -3
  129. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
  130. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +71 -2
  131. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
  132. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +2 -1
  133. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
  134. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +23 -8
  135. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
  136. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts +7 -1
  137. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts.map +1 -1
  138. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js +4 -2
  139. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js.map +1 -1
  140. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +9 -3
  141. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
  142. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +3 -3
  143. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -1
  144. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
  145. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +35 -2
  146. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
  147. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +41 -17
  148. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
  149. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  150. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  151. package/dist/knowledge/manifest.json +8 -8
  152. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +22 -7
  153. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +3 -3
  154. package/dist/knowledge/playbooks/bottom_up.build/method.md +17 -15
  155. package/dist/knowledge/playbooks/bottom_up.build/playbook.json +4 -3
  156. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-protocol.json +1 -1
  157. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-treatment.json +1 -1
  158. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +261 -34
  159. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +42 -4
  160. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +188 -59
  161. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +2 -2
  162. package/dist/knowledge/playbooks/bottom_up.build-scale/method.md +169 -276
  163. package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +2 -2
  164. package/dist/knowledge/playbooks/bottom_up.capability-composition/method.md +8 -1
  165. package/dist/knowledge/playbooks/bottom_up.capability-composition/playbook.json +1 -1
  166. package/dist/knowledge/playbooks/bottom_up.conception/method.md +3 -2
  167. package/dist/knowledge/playbooks/bottom_up.conception/playbook.json +11 -3
  168. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-protocol.json +1 -1
  169. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-treatment.json +1 -1
  170. package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +129 -17
  171. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +7 -4
  172. package/dist/knowledge/playbooks/bottom_up.experience-plan/method.md +28 -6
  173. package/dist/knowledge/playbooks/bottom_up.experience-plan/playbook.json +5 -4
  174. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +13 -5
  175. package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +50 -0
  176. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +16 -4
  177. package/dist/knowledge/playbooks/bottom_up.website-plan/method.md +19 -0
  178. package/dist/knowledge/playbooks/bottom_up.website-plan/playbook.json +5 -2
  179. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +7 -3
  180. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  181. package/dist/knowledge/playbooks/refinement.document-facts/method.md +8 -0
  182. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +3 -2
  183. package/dist/knowledge/playbooks/refinement.feature-contribution/method.md +5 -2
  184. package/dist/knowledge/playbooks/refinement.feature-contribution/playbook.json +1 -1
  185. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-protocol.json +1 -1
  186. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-treatment.json +1 -1
  187. package/dist/knowledge/playbooks/top_down.brand-identity/method.md +75 -37
  188. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +35 -38
  189. package/dist/knowledge/playbooks/top_down.brand-name-research/method.md +145 -0
  190. package/dist/knowledge/playbooks/top_down.brand-name-research/playbook.json +57 -0
  191. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-protocol.json +1 -0
  192. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-treatment.json +1 -0
  193. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/method.md +99 -0
  194. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/playbook.json +65 -0
  195. package/dist/knowledge/playbooks/top_down.brand-naming/method.md +56 -0
  196. package/dist/knowledge/playbooks/top_down.brand-naming/playbook.json +76 -0
  197. package/dist/knowledge/playbooks/top_down.business-model/evaluation-protocol.json +1 -1
  198. package/dist/knowledge/playbooks/top_down.business-model/evaluation-treatment.json +1 -1
  199. package/dist/knowledge/playbooks/top_down.business-model/method.md +60 -6
  200. package/dist/knowledge/playbooks/top_down.business-model/playbook.json +15 -10
  201. package/dist/knowledge/playbooks/top_down.capability-map/method.md +10 -9
  202. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +1 -1
  203. package/dist/knowledge/playbooks/top_down.compliance-analysis/playbook.json +30 -10
  204. package/dist/knowledge/playbooks/top_down.compliance-conception/playbook.json +3 -1
  205. package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +4 -1
  206. package/dist/knowledge/playbooks/top_down.definition/method.md +8 -3
  207. package/dist/knowledge/playbooks/top_down.definition/playbook.json +6 -4
  208. package/dist/knowledge/playbooks/top_down.expert-personas/playbook.json +16 -2
  209. package/dist/knowledge/playbooks/top_down.feature-drafts/method.md +5 -2
  210. package/dist/knowledge/playbooks/top_down.feature-drafts/playbook.json +1 -1
  211. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-protocol.json +1 -1
  212. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-treatment.json +1 -1
  213. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +26 -0
  214. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +4 -2
  215. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-protocol.json +1 -1
  216. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-treatment.json +1 -1
  217. package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +11 -1
  218. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-protocol.json +1 -1
  219. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-treatment.json +1 -1
  220. package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +84 -9
  221. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +6 -3
  222. package/dist/knowledge/playbooks/top_down.risk-register/method.md +21 -0
  223. package/dist/knowledge/playbooks/top_down.risk-register/playbook.json +8 -2
  224. package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +4 -2
  225. package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +29 -0
  226. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +58 -17
  227. package/dist/knowledge/references/brand.name-choice.config.md +144 -0
  228. package/dist/knowledge/references/brand.name-screening.config.md +308 -0
  229. package/dist/knowledge/references/build-plan.task-graph.config.md +119 -11
  230. package/dist/knowledge/references/business-model.pricing-plan.config.md +16 -0
  231. package/dist/knowledge/references/business-model.snapshot.config.md +64 -0
  232. package/dist/knowledge/references/business-model.snapshot.validation.md +68 -4
  233. package/dist/knowledge/references/capability-composition.config.md +67 -4
  234. package/dist/knowledge/references/companion.market.prompt-renderer.md +11 -6
  235. package/dist/knowledge/references/example.authorization.application-roles.office-and-field.md +44 -0
  236. package/dist/knowledge/references/example.backend.custom-operation.audit-event.md +81 -0
  237. package/dist/knowledge/references/example.backend.custom-operation.child-line-total.md +258 -0
  238. package/dist/knowledge/references/example.backend.custom-operation.computed-total.md +153 -0
  239. package/dist/knowledge/references/example.backend.custom-operation.create-related-resource.md +107 -0
  240. package/dist/knowledge/references/example.data-seeding.minimal.md +39 -10
  241. package/dist/knowledge/references/example.data-seeding.row-reference.md +80 -0
  242. package/dist/knowledge/references/example.email.template.minimal.md +1 -1
  243. package/dist/knowledge/references/example.resource.config-wiring.retention-policy-operations.md +74 -0
  244. package/dist/knowledge/references/example.resource.personal-data.free-text-field.md +19 -0
  245. package/dist/knowledge/references/example.resource.personal-data.person-without-account.md +27 -0
  246. package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +152 -0
  247. package/dist/knowledge/references/example.resource.ui-behavior.filter-presets.md +15 -0
  248. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -0
  249. package/dist/knowledge/references/example.views.app-level.home-definition.md +13 -0
  250. package/dist/knowledge/references/example.views.chart-definition.shared.md +83 -0
  251. package/dist/knowledge/references/experience-plan.config.md +60 -7
  252. package/dist/knowledge/references/market.context-block.builder.md +1 -1
  253. package/dist/knowledge/references/market.snapshot.validation.md +1 -1
  254. package/dist/knowledge/references/placement-plan.config.md +43 -0
  255. package/dist/knowledge/references/requirements.functional-requirement.config.md +8 -2
  256. package/dist/knowledge/references/requirements.non-functional-requirement.config.md +2 -0
  257. package/dist/knowledge/references/requirements.references.conventions.md +1 -1
  258. package/dist/knowledge/references/requirements.snapshot.config.md +57 -1
  259. package/dist/knowledge/references/requirements.snapshot.validation.md +35 -1
  260. package/dist/knowledge/references/saas.backend.audit-logs.log-event.md +63 -0
  261. package/dist/knowledge/references/saas.backend.document-sequence.issue-in-operation.md +60 -0
  262. package/dist/knowledge/references/saas.backend.document-sequence.raise-floor.md +156 -0
  263. package/dist/knowledge/references/saas.backend.email.send.md +77 -0
  264. package/dist/knowledge/references/saas.backend.notifications.operation-email-template-ref.md +60 -0
  265. package/dist/knowledge/references/saas.data-seeding.bootstrap-wiring.md +7 -1
  266. package/dist/knowledge/references/saas.data-seeding.computed-entry.md +43 -0
  267. package/dist/knowledge/references/saas.data-seeding.definition-input.md +14 -2
  268. package/dist/knowledge/references/saas.data-seeding.row-reference.md +93 -0
  269. package/dist/knowledge/references/saas.frontend.collection-filter-presets.md +124 -0
  270. package/dist/knowledge/references/saas.frontend.launcher.item-refs.md +316 -0
  271. package/dist/knowledge/references/saas.frontend.launcher.merge-rules.md +106 -0
  272. package/dist/knowledge/references/saas.frontend.launcher.runtime-availability.md +60 -0
  273. package/dist/knowledge/references/saas.frontend.resource-label-params.md +52 -0
  274. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +47 -18
  275. package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +4 -1
  276. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destination-roles.md +25 -0
  277. package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +2 -2
  278. package/dist/knowledge/references/saas.models.audit.trail-config.md +45 -0
  279. package/dist/knowledge/references/saas.models.notifications.user-notification-definition.md +5 -3
  280. package/dist/knowledge/references/saas.models.queue.scheduled-recovery.md +81 -2
  281. package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +26 -0
  282. package/dist/knowledge/references/saas.models.roles.definition.md +61 -0
  283. package/dist/knowledge/references/saas.models.roles.organization-defaults.md +97 -0
  284. package/dist/knowledge/references/saas.public-runtime.contract.md +26 -0
  285. package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +10 -0
  286. package/dist/knowledge/references/saas.website.astro.bridge.md +10 -0
  287. package/dist/knowledge/references/saas.website.astro.label-loader.md +12 -0
  288. package/dist/knowledge/references/saas.website.astro.llms-txt-server.md +14 -1
  289. package/dist/knowledge/references/saas.website.astro.site-context.md +13 -0
  290. package/dist/knowledge/references/saas.website.blog.bridge.md +4 -0
  291. package/dist/knowledge/references/saas.website.config.site-context-loader.md +3 -0
  292. package/dist/knowledge/references/saas.website.factories.define-section.md +4 -0
  293. package/dist/knowledge/references/saas.website.legal.public-document-links.md +76 -0
  294. package/dist/knowledge/references/saas.website.page-manifest.schema.md +12 -3
  295. package/dist/knowledge/references/saas.website.page-sections.component.md +72 -0
  296. package/dist/knowledge/references/saas.website.root-config.seo.md +2 -1
  297. package/dist/knowledge/references/saas.website.runtime.context.md +7 -0
  298. package/dist/knowledge/references/saas.website.sections.definition-schema.md +11 -0
  299. package/dist/knowledge/references/saas.website.seo.llms-txt-config.md +2 -0
  300. package/dist/knowledge/references/website-plan.config.md +26 -0
  301. package/dist/knowledge/references/zod.decorators.chainable-runtime.md +13 -0
  302. package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +7 -0
  303. package/dist/knowledge/references/zod.decorators.document-sequence.md +65 -0
  304. package/dist/knowledge/references/zod.decorators.schema-metadata.md +1 -0
  305. package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +21 -0
  306. package/dist/knowledge/references/zod.factories.bigdecimal.md +1 -0
  307. package/dist/knowledge/references/zod.factories.code.md +1 -0
  308. package/dist/knowledge/references/zod.factories.duration.md +1 -0
  309. package/dist/knowledge/references/zod.factories.money.md +1 -0
  310. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  311. package/dist/knowledge/registries/framework-topics.json +374 -1
  312. package/dist/knowledge/registries/playbooks.json +76 -28
  313. package/dist/knowledge/registries/source-tags.json +1513 -898
  314. package/dist/knowledge/rules/live-context-door.md +5 -2
  315. package/dist/knowledge/skills/INDEX.md +5 -2
  316. package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +16 -3
  317. package/dist/knowledge/skills/application-database-migrations/SKILL.md +14 -3
  318. package/dist/knowledge/skills/application-roles-authoring/SKILL.md +158 -0
  319. package/dist/knowledge/skills/application-roles-authoring/references/framework-application-roles-api.md +169 -0
  320. package/dist/knowledge/skills/application-roles-authoring/references/office-and-field-worked-example.md +63 -0
  321. package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +6 -1
  322. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +256 -9
  323. package/dist/knowledge/skills/backend-custom-operation/references/after-the-operation.md +42 -0
  324. package/dist/knowledge/skills/backend-custom-operation/references/framework-audit-log-event-api.md +220 -0
  325. package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +5 -0
  326. package/dist/knowledge/skills/brand-name-screening/SKILL.md +178 -0
  327. package/dist/knowledge/skills/brand-name-screening/references/framework-brand-name-screening-api.md +466 -0
  328. package/dist/knowledge/skills/brand-name-screening/references/screening-procedure.md +87 -0
  329. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +7 -3
  330. package/dist/knowledge/skills/config-app-shell/SKILL.md +58 -5
  331. package/dist/knowledge/skills/config-app-shell/references/framework-launcher-items-api.md +461 -0
  332. package/dist/knowledge/skills/config-app-shell/references/framework-launcher-visibility-api.md +80 -0
  333. package/dist/knowledge/skills/config-design-system/SKILL.md +28 -6
  334. package/dist/knowledge/skills/config-navigation/SKILL.md +14 -3
  335. package/dist/knowledge/skills/config-saas/SKILL.md +56 -15
  336. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +65 -2
  337. package/dist/knowledge/skills/config-saas/references/framework-audit-trail-config-api.md +62 -2
  338. package/dist/knowledge/skills/config-saas/references/framework-background-work-api.md +81 -2
  339. package/dist/knowledge/skills/config-saas-backend/SKILL.md +6 -1
  340. package/dist/knowledge/skills/configure-billing/SKILL.md +18 -4
  341. package/dist/knowledge/skills/email-add-template/SKILL.md +28 -6
  342. package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +1 -1
  343. package/dist/knowledge/skills/email-add-template/references/framework-email-send-api.md +128 -0
  344. package/dist/knowledge/skills/email-add-template/references/framework-operation-email-template-ref-api.md +99 -0
  345. package/dist/knowledge/skills/engine-component-registration/SKILL.md +6 -1
  346. package/dist/knowledge/skills/engine-product-definitions/SKILL.md +21 -8
  347. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +10 -2
  348. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +18 -4
  349. package/dist/knowledge/skills/frontend-component-catalog/SKILL.md +11 -3
  350. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +2 -1
  351. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +8 -0
  352. package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +19 -5
  353. package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +10 -2
  354. package/dist/knowledge/skills/inbound-channels/SKILL.md +2 -2
  355. package/dist/knowledge/skills/infra-environment-config/SKILL.md +6 -1
  356. package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +17 -2
  357. package/dist/knowledge/skills/local-environment-bootstrap/references/derived-artifact-currency.md +122 -0
  358. package/dist/knowledge/skills/local-environment-bootstrap/references/framework-upgrade-and-dependency-alignment.md +11 -0
  359. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +9 -2
  360. package/dist/knowledge/skills/market-add-feature-benefit/SKILL.md +10 -2
  361. package/dist/knowledge/skills/market-alternatives/SKILL.md +10 -2
  362. package/dist/knowledge/skills/market-authoring-overview/SKILL.md +10 -2
  363. package/dist/knowledge/skills/market-category/SKILL.md +21 -7
  364. package/dist/knowledge/skills/market-channels/SKILL.md +6 -1
  365. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +22 -4
  366. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +12 -2
  367. package/dist/knowledge/skills/market-generation-cli/SKILL.md +21 -11
  368. package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +11 -6
  369. package/dist/knowledge/skills/market-icp/SKILL.md +10 -2
  370. package/dist/knowledge/skills/market-jobs-pains-gains/SKILL.md +6 -1
  371. package/dist/knowledge/skills/market-message-templates-authoring/SKILL.md +6 -1
  372. package/dist/knowledge/skills/market-message-templates-authoring/references/framework-message-template-api.md +1 -1
  373. package/dist/knowledge/skills/market-persona/SKILL.md +14 -3
  374. package/dist/knowledge/skills/market-positioning-authoring/SKILL.md +6 -1
  375. package/dist/knowledge/skills/market-proof-and-objection/SKILL.md +10 -2
  376. package/dist/knowledge/skills/market-scoring-interpretation/SKILL.md +6 -1
  377. package/dist/knowledge/skills/market-snapshot-validation/SKILL.md +15 -4
  378. package/dist/knowledge/skills/market-snapshot-validation/references/framework-snapshot-validation-api.md +1 -1
  379. package/dist/knowledge/skills/market-tone-of-voice/SKILL.md +6 -1
  380. package/dist/knowledge/skills/model-cost-attribution/references/framework-work-unit-api.md +26 -0
  381. package/dist/knowledge/skills/module-companion-exports/SKILL.md +7 -1
  382. package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +10 -0
  383. package/dist/knowledge/skills/module-relationships/SKILL.md +37 -8
  384. package/dist/knowledge/skills/pdf-template-authoring/SKILL.md +4 -2
  385. package/dist/knowledge/skills/provider-address-lookup/SKILL.md +14 -3
  386. package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +6 -1
  387. package/dist/knowledge/skills/provider-operation-calls/SKILL.md +14 -3
  388. package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +10 -2
  389. package/dist/knowledge/skills/resource-add-field/SKILL.md +10 -2
  390. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +46 -17
  391. package/dist/knowledge/skills/resource-add-resource/SKILL.md +14 -2
  392. package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +26 -0
  393. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +29 -3
  394. package/dist/knowledge/skills/resource-config-wiring/references/framework-collection-operation-declarations.md +19 -4
  395. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +5 -2
  396. package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +103 -0
  397. package/dist/knowledge/skills/resource-config-wiring/references/framework-retention-policy-operations.md +135 -0
  398. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +26 -0
  399. package/dist/knowledge/skills/resource-config-wiring/references/framework-user-notifications-api.md +26 -7
  400. package/dist/knowledge/skills/resource-custom-view/SKILL.md +10 -2
  401. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +46 -17
  402. package/dist/knowledge/skills/resource-external-data/references/erasure-suppression.md +2 -2
  403. package/dist/knowledge/skills/resource-retention-binding/SKILL.md +5 -1
  404. package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +15 -1
  405. package/dist/knowledge/skills/resource-schema-authoring/references/computed-totals.md +569 -0
  406. package/dist/knowledge/skills/resource-schema-authoring/references/document-numbers.md +358 -0
  407. package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +8 -0
  408. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +21 -0
  409. package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +7 -2
  410. package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +13 -0
  411. package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +153 -0
  412. package/dist/knowledge/skills/resource-status-lifecycle/references/commercial-documents.md +46 -0
  413. package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +198 -0
  414. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +30 -4
  415. package/dist/knowledge/skills/resource-ui-behavior/references/framework-collection-filter-presets-api.md +157 -0
  416. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +101 -19
  417. package/dist/knowledge/skills/seeding-authoring/SKILL.md +202 -39
  418. package/dist/knowledge/skills/seeding-authoring/references/cross-seed-row-references.md +67 -0
  419. package/dist/knowledge/skills/seeding-authoring/references/framework-data-seeding-api.md +154 -4
  420. package/dist/knowledge/skills/seeding-authoring/references/seed-row-overlay.md +22 -0
  421. package/dist/knowledge/skills/seeding-operations/references/framework-data-seeding-operations-api.md +7 -1
  422. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +43 -0
  423. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +2 -2
  424. package/dist/knowledge/skills/spec-companion-exports/SKILL.md +6 -1
  425. package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +10 -0
  426. package/dist/knowledge/skills/spec-component-update/SKILL.md +10 -2
  427. package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +2 -2
  428. package/dist/knowledge/skills/spec-family-update/SKILL.md +71 -66
  429. package/dist/knowledge/skills/spec-family-update/references/family-spec-routing.md +1 -1
  430. package/dist/knowledge/skills/spec-resource-update/SKILL.md +30 -10
  431. package/dist/knowledge/skills/spec-resource-update/references/resource-spec-field-routing.md +28 -0
  432. package/dist/knowledge/skills/spec-update-after-change/SKILL.md +22 -5
  433. package/dist/knowledge/skills/views-add-composite-view/SKILL.md +6 -1
  434. package/dist/knowledge/skills/views-add-custom-view/SKILL.md +10 -2
  435. package/dist/knowledge/skills/views-app-level/SKILL.md +13 -3
  436. package/dist/knowledge/skills/views-app-level/references/application-home.md +56 -0
  437. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +221 -37
  438. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +22 -5
  439. package/dist/knowledge/skills/views-execution-authoring/SKILL.md +1 -1
  440. package/dist/knowledge/skills/website-anonymous-session/SKILL.md +32 -2
  441. package/dist/knowledge/skills/website-blog-authoring/SKILL.md +16 -3
  442. package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +4 -0
  443. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +7 -1
  444. package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +13 -1
  445. package/dist/knowledge/skills/website-factory-advanced/SKILL.md +14 -2
  446. package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +13 -1
  447. package/dist/knowledge/skills/website-layout-overrides/SKILL.md +6 -1
  448. package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +19 -1
  449. package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +55 -18
  450. package/dist/knowledge/skills/website-navigation-authoring/references/framework-public-document-links-api.md +98 -0
  451. package/dist/knowledge/skills/website-navigation-authoring/references/worked-examples-header-footer.md +8 -11
  452. package/dist/knowledge/skills/website-page-authoring/SKILL.md +100 -8
  453. package/dist/knowledge/skills/website-page-authoring/references/framework-site-context-loader-api.md +3 -0
  454. package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +6 -1
  455. package/dist/knowledge/skills/website-section-contact/SKILL.md +15 -0
  456. package/dist/knowledge/skills/website-section-contact/references/define-website-section-api.md +15 -0
  457. package/dist/knowledge/skills/website-section-cta/SKILL.md +15 -0
  458. package/dist/knowledge/skills/website-section-cta/references/define-website-section-api.md +15 -0
  459. package/dist/knowledge/skills/website-section-faq/SKILL.md +21 -1
  460. package/dist/knowledge/skills/website-section-faq/references/define-website-section-api.md +15 -0
  461. package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +21 -1
  462. package/dist/knowledge/skills/website-section-feature-benefit-summary/references/define-website-section-api.md +15 -0
  463. package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +25 -2
  464. package/dist/knowledge/skills/website-section-feature-detail/references/define-website-section-api.md +15 -0
  465. package/dist/knowledge/skills/website-section-footer-cta/SKILL.md +15 -0
  466. package/dist/knowledge/skills/website-section-footer-cta/references/define-website-section-api.md +15 -0
  467. package/dist/knowledge/skills/website-section-hero/SKILL.md +33 -10
  468. package/dist/knowledge/skills/website-section-hero/references/define-website-section-api.md +15 -0
  469. package/dist/knowledge/skills/website-section-pricing/SKILL.md +21 -1
  470. package/dist/knowledge/skills/website-section-pricing/references/define-website-section-api.md +15 -0
  471. package/dist/knowledge/skills/website-section-social-proof/SKILL.md +27 -2
  472. package/dist/knowledge/skills/website-section-social-proof/references/define-website-section-api.md +15 -0
  473. package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +16 -4
  474. package/dist/knowledge/skills/website-seo-aeo-geo/references/aeo-api.md +11 -0
  475. package/dist/knowledge/skills/website-seo-aeo-geo/references/geo-api.md +16 -1
  476. package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +2 -1
  477. package/dist/knowledge/topic-index.json +1590 -292
  478. package/dist/tsconfig.build.tsbuildinfo +1 -1
  479. package/dist/tsconfig.tsbuildinfo +1 -1
  480. package/package.json +4 -4
@@ -0,0 +1,93 @@
1
+ # saas.data-seeding.row-reference
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-backend-lib`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-backend-lib`
10
+
11
+ ```typescript
12
+ /**
13
+ * What a reference needs to know about the seed whose row it names. A whole `DataSeedDefinition` satisfies it — pass
14
+ * the target seed's definition, imported from the module that declares it.
15
+ */
16
+ export type DataSeedRowReferenceTarget = Pick<DataSeedDefinition, 'seedKey' | 'resourceType' | 'scope' | 'allowedApplicationEnvironments'>;
17
+
18
+ /**
19
+ * A reference to a row another seed writes, placed where a foreign-key VALUE goes in an entry's `businessKey` or
20
+ * `data` (directly, or inside a nested object or array). The engine replaces it with the row's `_id` before writing.
21
+ *
22
+ * Build it with {@link referenceDataSeedRow}; never construct one by hand.
23
+ */
24
+ export class DataSeedRowReference {
25
+ /** Brand read by {@link isDataSeedRowReference}. */
26
+ public readonly [DATA_SEED_ROW_REFERENCE_BRAND]: true = true;
27
+
28
+ /** @internal — use {@link referenceDataSeedRow}. */
29
+ public constructor(
30
+ /** The seed that writes the referenced row. Must be in the referring seed's `dependsOn`. */
31
+ public readonly target: DataSeedRowReferenceTarget,
32
+ /**
33
+ * The referenced row's business key, as the target resource declares it. The scope's own foreign key may be left
34
+ * out when both seeds share a scope kind; the engine fills it in from the scope being seeded.
35
+ */
36
+ public readonly businessKey: Readonly<Record<string, unknown>>,
37
+ ) {
38
+ Object.freeze(this);
39
+ }
40
+
41
+ /** What a log line or a JSON dump shows instead of an empty object (the brand is a symbol, which JSON drops). */
42
+ public toJSON(): string {
43
+ return describeDataSeedRowReference(this);
44
+ }
45
+ }
46
+
47
+ /**
48
+ * Reference the row a `dependsOn` seed writes, by that row's business key.
49
+ *
50
+ * @param target The seed that writes the row — its definition, as returned by `createDataSeedDefinition`.
51
+ * @param businessKey The row's business key. Leave out the scope foreign key (`organizationId`, `userId`, …) when the
52
+ * target seed has the same scope kind as the referring seed: the engine fills it from the scope being seeded.
53
+ * @throws Error when `target` has no `seedKey`, when `businessKey` is not a plain object, or when a business-key value
54
+ * is `undefined` or is itself a reference.
55
+ *
56
+ * @example
57
+ * ```ts
58
+ * import { referenceDataSeedRow } from '@wildo-ai/saas-backend-lib/data-seeding-models';
59
+ * import demoCustomersSeed from './crm.demo-customers.seed';
60
+ *
61
+ * // In a seed declaring dependsOn: [{ seedKey: demoCustomersSeed.seedKey }]
62
+ * data: { customerId: referenceDataSeedRow(demoCustomersSeed, { email: 'ana.martin@example.com' }) }
63
+ * ```
64
+ */
65
+ export function referenceDataSeedRow(
66
+ target: DataSeedRowReferenceTarget,
67
+ businessKey: Record<string, unknown>,
68
+ ): DataSeedRowReference {
69
+ if (target === null || typeof target !== 'object' || typeof target.seedKey !== 'string' || target.seedKey.length === 0) {
70
+ throw new Error('referenceDataSeedRow: `target` must be the referenced seed\'s definition (a value carrying its `seedKey`, `resourceType` and `scope`).');
71
+ }
72
+ if (!isPlainObject(businessKey)) {
73
+ throw new Error(`referenceDataSeedRow: the business key of a reference to seed '${target.seedKey}' must be a plain object.`);
74
+ }
75
+ for (const [field, value] of Object.entries(businessKey)) {
76
+ if (value === undefined) {
77
+ throw new Error(`referenceDataSeedRow: business-key field '${field}' of a reference to seed '${target.seedKey}' is undefined — a business key is identity; use null for a genuinely-nullable field.`);
78
+ }
79
+ if (containsDataSeedRowReference(value)) {
80
+ throw new Error(`referenceDataSeedRow: business-key field '${field}' of a reference to seed '${target.seedKey}' is itself a reference — a reference names its row by literal values.`);
81
+ }
82
+ }
83
+ return new DataSeedRowReference(
84
+ {
85
+ seedKey: target.seedKey,
86
+ resourceType: target.resourceType,
87
+ scope: target.scope,
88
+ ...(target.allowedApplicationEnvironments !== undefined ? { allowedApplicationEnvironments: target.allowedApplicationEnvironments } : {}),
89
+ },
90
+ Object.freeze({ ...businessKey }),
91
+ );
92
+ }
93
+ ```
@@ -0,0 +1,124 @@
1
+ # saas.frontend.collection-filter-presets
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-frontend-lib`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-frontend-lib`
10
+
11
+ ```typescript
12
+ */
13
+ /**
14
+ * A DATE WINDOW named relative to NOW, for a preset filter that must mean the same thing tomorrow.
15
+ *
16
+ * A preset is authored once and clicked forever, so "created today" cannot be an authored pair of
17
+ * instants — it has to be RESOLVED at the moment it is applied. The vocabulary is closed and small
18
+ * on purpose: each member is a window a person actually asks for, and each resolves to the
19
+ * `{ startDate, endDate }` pair the framework's date-range filter already carries end to end, so a
20
+ * preset needs no filter grammar of its own and no backend change.
21
+ *
22
+ * Resolution is in the VIEWER's timezone, which is the only one that makes "today" true for the
23
+ * person reading the screen. The backend compares instants, so the boundaries travel as absolute
24
+ * times and nothing downstream has to know a timezone was involved.
25
+ *
26
+ * Every window is whole local days and ends at the LAST instant of its last day, one millisecond before the next local
27
+ * midnight. The date-range filter's end bound is inclusive, and a date-only value (a due date picked in a calendar) is
28
+ * stored at the local midnight of the day it names, so ending at the next midnight would also match the day after.
29
+ */
30
+ export enum CollectionFilterPresetRelativeRange {
31
+ /** All of today, local: midnight this morning to the end of the day. */
32
+ TODAY = 'today',
33
+ /** All of yesterday, local. */
34
+ YESTERDAY = 'yesterday',
35
+ /** The last seven days INCLUDING today — the rolling week, not the last seven whole days. */
36
+ LAST_7_DAYS = 'last_7_days',
37
+ /** The last thirty days including today. */
38
+ LAST_30_DAYS = 'last_30_days',
39
+ /** The first of this calendar month through the end of today. */
40
+ THIS_MONTH = 'this_month',
41
+ /** The first of this calendar year through the end of today. */
42
+ THIS_YEAR = 'this_year',
43
+ /**
44
+ * Everything BEFORE today, local: what an "overdue" list shows on a due-date field. Ends at the last instant of
45
+ * yesterday, so a date-only value due TODAY is due, not overdue. A deadline with a time earlier today is in TODAY, not
46
+ * here: the window is whole days, like every other member, so the pill reads the same all day.
47
+ */
48
+ BEFORE_TODAY = 'before_today',
49
+ /** Today and the six days after it, local: "due this week" from today. */
50
+ NEXT_7_DAYS = 'next_7_days',
51
+ /** Today and the twenty-nine days after it, local. */
52
+ NEXT_30_DAYS = 'next_30_days',
53
+ }
54
+
55
+ /**
56
+ * A value a preset can only know once it is clicked, because it depends on WHO is looking. Resolved from the
57
+ * viewer's session at that moment, like a relative range is resolved from the clock, so "My jobs" means the person
58
+ * reading the list, whoever that is.
59
+ *
60
+ * A preset naming one is unavailable to a viewer the value cannot be resolved for (no signed-in user): the pill is
61
+ * disabled rather than applied without the field, which would show a different list under the same name.
62
+ */
63
+ export enum CollectionFilterPresetContextValue {
64
+ /** The signed-in user's id, for a reference field such as an assignee or owner. */
65
+ CURRENT_USER = 'current_user',
66
+ }
67
+
68
+ /**
69
+ * What a preset ASSIGNS to one filter field.
70
+ *
71
+ * Four kinds, split by WHEN the value is known:
72
+ *
73
+ * - a LITERAL (string, number, boolean) is fixed at authoring time and covers every enum value, id, number and flag,
74
+ * which is the whole of "filter to HIGH priority";
75
+ * - a RELATIVE RANGE (`{ relativeRange }`) is the temporal case, resolved when the pill is clicked, because an authored
76
+ * answer would be wrong by tomorrow;
77
+ * - a NUMERIC BOUND (`{ min?, max? }`) writes the same value the filter panel's own two number inputs do, and the
78
+ * backend applies it on every adapter. Both bounds are optional because "under 500" has no floor, and that is the
79
+ * commonest threshold anyone asks for;
80
+ * - a CONTEXT VALUE (`{ contextValue }`) is known only from who is looking, such as "assigned to me", and is resolved
81
+ * when the pill is clicked, so the same authored preset shows each viewer their own rows.
82
+ */
83
+ export const CollectionFilterPresetValueSchema = z.union([
84
+ z.string(),
85
+ z.number(),
86
+ z.boolean(),
87
+ z.object({ relativeRange: z.enum(CollectionFilterPresetRelativeRange) }),
88
+ z.object({ min: z.number().optional(), max: z.number().optional() }),
89
+ z.object({ contextValue: z.enum(CollectionFilterPresetContextValue) }),
90
+ ]);
91
+ export type CollectionFilterPresetValue = z.infer<typeof CollectionFilterPresetValueSchema>;
92
+
93
+ /**
94
+ * ONE named, one-click narrowing of a collection, rendered as a toggleable pill above the list.
95
+ *
96
+ * ## Why this is not `quickFilterField`
97
+ *
98
+ * They answer different questions and both are worth having. A quick-filter field promotes ONE enum
99
+ * and spends every one of its values on a TAB STRIP: the tabs are mutually exclusive and they read
100
+ * as "which slice of this collection am I looking at". A preset is ADDITIVE and crosses fields —
101
+ * "high priority", "created today", "unassigned" — and several can be on at once. Collapsing them
102
+ * would cost one of the two meanings.
103
+ *
104
+ * ## No state of its own
105
+ *
106
+ * A preset is a WRITE into the collection's existing filter values, and its ON/OFF is DERIVED by
107
+ * reading them back: it is active exactly when every key it assigns currently holds its value. So
108
+ * clearing a chip, editing the panel, or applying a second preset that touches the same field all
109
+ * update the pills for free, and there is no second copy of the filter state to keep in step.
110
+ */
111
+ export const CollectionFilterPresetSchema = z.object({
112
+ /**
113
+ * Stable identity — the i18n key segment and the pill's DOM hook. Author-owned and never shown:
114
+ * the words come from `resources.<type>.filterPresets.<ref>.label`.
115
+ */
116
+ ref: z.string().min(1),
117
+ /**
118
+ * The fields this preset assigns, and to what. Every key must be a filter field of the operation;
119
+ * a key that is not simply never matches, so the pill would read as permanently off.
120
+ */
121
+ filters: z.record(z.string(), CollectionFilterPresetValueSchema),
122
+ });
123
+ export type CollectionFilterPreset = z.infer<typeof CollectionFilterPresetSchema>;
124
+ ```
@@ -0,0 +1,316 @@
1
+ # saas.frontend.launcher.item-refs
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-frontend-lib`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-frontend-lib`
10
+
11
+ ```typescript
12
+ /**
13
+ * What kind of target a launcher item points to.
14
+ *
15
+ * This is a config-time concept — the resolution layer maps each kind to a
16
+ * navigation action. Different from `NavigationContentType` which is a runtime
17
+ * concept for zone content rendering. Both have `RESOURCE_OPERATION` but serve
18
+ * different axes: `LauncherItemTargetKind` = what a launcher item targets,
19
+ * `NavigationContentType` = what renders in a navigation zone.
20
+ */
21
+ export enum LauncherItemTargetKind {
22
+ /** Navigate to a resource operation (list, create, read, etc.). */
23
+ RESOURCE_OPERATION = 'resource_operation',
24
+ /** Navigate to an application-scoped special view. */
25
+ VIEW = 'view',
26
+ /** Navigate to a resource-scoped special view. */
27
+ RESOURCE_VIEW = 'resource_view',
28
+ /** Navigate to a framework-provided page (home, security settings, etc.). */
29
+ ENGINE_PAGE = 'engine_page',
30
+ /** Render a custom registered React component. */
31
+ CUSTOM_COMPONENT = 'custom_component',
32
+ /** Open the unified Settings Hub (overlay), optionally at a specific section. */
33
+ SETTINGS_SECTION = 'settings_section',
34
+ }
35
+ ```
36
+
37
+ ### Origin Package: `@wildo-ai/saas-frontend-lib`
38
+
39
+ ```typescript
40
+ /**
41
+ * What kind of content a sidebar section renders.
42
+ *
43
+ * This is the discriminant for the `SidebarSection` discriminated union.
44
+ * Each content kind has its own set of properties and rendering behavior.
45
+ */
46
+ export enum SidebarSectionContentKind {
47
+ /** Traditional navigation item list (tree, collapsible, inline create). */
48
+ NAVIGATION_LIST = 'navigation_list',
49
+ /** Filterable resource instance list — fetches from a bound operation. */
50
+ RESOURCE_BROWSER = 'resource_browser',
51
+ /** Guidance/onboarding widget — renders a registered guidance component. */
52
+ GUIDANCE_WIDGET = 'guidance_widget',
53
+ /** Arbitrary registered React component. */
54
+ CUSTOM_COMPONENT = 'custom_component',
55
+ }
56
+
57
+ // ════════════════════════════════════════════════════════════════
58
+ // LauncherItemRef — Discriminated Union
59
+ // ════════════════════════════════════════════════════════════════
60
+
61
+ /**
62
+ * Points to a resource operation (list, create, read, etc.).
63
+ * The resolution layer resolves this via the resource registry.
64
+ */
65
+ export interface ResourceOperationItemRef {
66
+ kind: LauncherItemTargetKind.RESOURCE_OPERATION;
67
+ resourceType: string;
68
+ operation: string;
69
+ operationVariant?: string;
70
+ }
71
+
72
+ /** Points to an application-scoped special view. */
73
+ export interface ViewItemRef {
74
+ kind: LauncherItemTargetKind.VIEW;
75
+ viewRef: string;
76
+ }
77
+
78
+ /** Points to a resource-scoped special view. */
79
+ export interface ResourceViewItemRef {
80
+ kind: LauncherItemTargetKind.RESOURCE_VIEW;
81
+ resourceType: string;
82
+ viewRef: string;
83
+ }
84
+
85
+ /** Points to a framework page (home, security settings). */
86
+ export interface EnginePageItemRef {
87
+ kind: LauncherItemTargetKind.ENGINE_PAGE;
88
+ pageRef: EnginePageRef;
89
+ }
90
+
91
+ /** Points to a registered component — engine or application (see `ComponentRegistryRef`). */
92
+ export interface CustomComponentItemRef {
93
+ kind: LauncherItemTargetKind.CUSTOM_COMPONENT;
94
+ /**
95
+ * The name a component is REGISTERED under — an engine `FrontendComponentType` member, or an
96
+ * application component a domain module binds in `componentRegistrations` (#549). Resolved through
97
+ * `ComponentRegistryService` under the default preset; a ref nothing is registered under is
98
+ * reported, never rendered as something plausible.
99
+ */
100
+ componentRef: string;
101
+ }
102
+
103
+ /**
104
+ * Opens the unified Settings Hub (overlay), optionally pre-selecting a section.
105
+ * Resolves to a `/settings` / `/settings/:sectionRef` URL navigation — the hub
106
+ * is URL-driven (`useSettingsHubRouterSync` reconstructs it), so every settings
107
+ * entry point converges on one destination.
108
+ */
109
+ export interface SettingsSectionItemRef {
110
+ kind: LauncherItemTargetKind.SETTINGS_SECTION;
111
+ /** Section to pre-open; omit to open the hub's default section. */
112
+ sectionRef?: string;
113
+ }
114
+
115
+ /**
116
+ * A launcher item reference — identifies WHAT a launcher item targets.
117
+ * Discriminated on `kind`. The resolution layer dispatches on this to
118
+ * produce a `ResolvedNavigationItem`.
119
+ */
120
+ export type LauncherItemRef =
121
+ | ResourceOperationItemRef
122
+ | ViewItemRef
123
+ | ResourceViewItemRef
124
+ | EnginePageItemRef
125
+ | CustomComponentItemRef
126
+ | SettingsSectionItemRef;
127
+
128
+ /**
129
+ * Toolbar items are navigation-only launcher refs.
130
+ * Custom-component materialization belongs to other app-level surfaces and is
131
+ * intentionally excluded from the global app-level toolbar contract.
132
+ */
133
+ export type ToolbarItemRef =
134
+ | ResourceOperationItemRef
135
+ | ViewItemRef
136
+ | ResourceViewItemRef
137
+ | EnginePageItemRef;
138
+
139
+ // ════════════════════════════════════════════════════════════════
140
+ // Per-Launcher Item Types
141
+ // ════════════════════════════════════════════════════════════════
142
+
143
+ /**
144
+ * A sidebar navigation item — extends `LauncherItemRef` with sidebar-specific
145
+ * display properties. Supports all launcher target kinds as targets.
146
+ */
147
+ export type SidebarItem = LauncherItemRef & {
148
+ displayPolicy?: SidebarItemDisplayPolicy;
149
+ /**
150
+ * Typed reference to a registered `NotificationBadgeDefinition` — its badge KEY,
151
+ * `<scope>:<identifier>`, built by `buildNotificationBadgeKey` /
152
+ * `notificationBadgeIdentityKey` from `@wildo-ai/saas-models`.
153
+ *
154
+ * The key, not the bare `identifier`: a definition is `(scope, identifier)`, so an identifier
155
+ * alone names a definition only while no second scope declares the same one. Matching on it made
156
+ * the second definition unreachable and gave it the first's count.
157
+ *
158
+ * The resolved definition supplies the display mode / tone / pulse, and the live count comes from
159
+ * `useNotificationBadges`, which indexes by the same key. Reported by `verify-launcher-content`
160
+ * when it resolves to nothing.
161
+ */
162
+ notificationBadgeRef?: string;
163
+ children?: SidebarItem[];
164
+ runtimeAvailability?: LauncherRuntimeAvailabilityConfig;
165
+ };
166
+
167
+ /** A command menu entry. */
168
+ export type CommandMenuCommand = LauncherItemRef & {
169
+ category?: string;
170
+ shortcut?: string;
171
+ /**
172
+ * OPTIONAL extra literal match terms, appended to the localized keyword set
173
+ * the palette already resolves for this command. These literals are NOT
174
+ * translated — reserve them for genuinely app-specific jargon that no
175
+ * localized label or operation-verb synonym covers (e.g. an internal codename
176
+ * like `"boards"` for a Todo-Lists list command).
177
+ *
178
+ * You do NOT need to author generic action verbs here: for a
179
+ * `RESOURCE_OPERATION` command the framework already folds in the LOCALIZED
180
+ * operation-verb synonyms (`components.APPLICATION_LEVEL_COMMAND_MENU.keywords*`,
181
+ * generated + translated by the labelling pipeline) keyed off the command's
182
+ * core operation semantic, and the record/command noun is covered by the
183
+ * command's already-localized label. So a French user finds "Create Todo" by
184
+ * typing "nouveau"/"créer" without any literal being authored here.
185
+ */
186
+ searchKeywords?: string[];
187
+ displayPolicy?: CommandMenuDisplayPolicy;
188
+ runtimeAvailability?: LauncherRuntimeAvailabilityConfig;
189
+ };
190
+ ```
191
+
192
+ ### Origin Package: `@wildo-ai/saas-frontend-lib`
193
+
194
+ ```typescript
195
+ /**
196
+ * Base properties shared by all sidebar section types.
197
+ * `ref` is `string`-typed — no framework enum, apps define their own refs.
198
+ */
199
+ export interface SidebarSectionBase {
200
+ contentKind: SidebarSectionContentKind;
201
+ /** Section reference — app-defined, used for i18n and configuration matching. */
202
+ ref: string;
203
+ /** Display label (i18n ref). If omitted, section renders without a header. */
204
+ label?: string;
205
+ /** Icon for the section header. */
206
+ icon?: string;
207
+ /** Whether the section header (label + icon) is rendered. Defaults to `true`. */
208
+ showLabel?: boolean;
209
+ /** Whether the section can be collapsed by the user. */
210
+ collapsible?: boolean;
211
+ /** Whether the section starts collapsed. */
212
+ defaultCollapsed?: boolean;
213
+ /**
214
+ * Mode refs this section is visible in. If omitted, visible in all modes.
215
+ * String-based — validated at startup against `appModes[].ref`.
216
+ * The section is hidden while the active mode is not one of them.
217
+ */
218
+ visibleInModes?: string[];
219
+ /**
220
+ * Function-based visibility condition for complex scope-dependent logic.
221
+ * Called with the current scope; the section is hidden when it returns false.
222
+ */
223
+ scopeCondition?: ScopeConditionFn;
224
+ /** Declarative availability evaluated by the app-shell layer: required capabilities and the roles shown to (`visibleToRoles`). */
225
+ runtimeAvailability?: LauncherRuntimeAvailabilityConfig;
226
+ }
227
+
228
+ /**
229
+ * Traditional navigation item list section.
230
+ * Supports tree hierarchy, inline create, drag-reorder (via behavior).
231
+ */
232
+ export interface SidebarSection_NavigationList extends SidebarSectionBase {
233
+ contentKind: SidebarSectionContentKind.NAVIGATION_LIST;
234
+ children: SidebarItem[];
235
+ behavior?: SidebarSectionBehavior;
236
+ /**
237
+ * Marks this section as the sidebar's PRIMARY navigation group — the app's
238
+ * top-level destinations (the "Home group"). Primary sections render at the
239
+ * top of the sidebar with no section header and never collapsible. When
240
+ * `SIDEBAR.homeDisplayMode` is `NAVIGATION_ITEM` (the default) the framework's
241
+ * Home row heads that same group, giving the Linear/Notion "Inbox / My Issues
242
+ * right under Home" shape; the other home modes surface home elsewhere and
243
+ * leave this group to the app's own destinations.
244
+ *
245
+ * This is a PLACEMENT/CHROME role, deliberately distinct from
246
+ * `SidebarSectionBehavior` (which describes where a section's ITEMS come
247
+ * from). Section ordering is engine policy and ignores declaration order for
248
+ * the special roles: primary section(s) first, then non-empty
249
+ * `SidebarSectionBehavior.FAVORITES` section(s), then the remaining sections
250
+ * in declared order. Modules can therefore contribute a primary section
251
+ * without the app config having to interleave it manually.
252
+ */
253
+ isPrimary?: boolean;
254
+ inlineCreate?: SidebarSectionInlineCreate;
255
+ inlineCreateResourceType?: string;
256
+ /** Field that receives the user's input during inline creation. Defaults to `'title'`. */
257
+ inlineCreateField?: string;
258
+ nested?: boolean;
259
+ maxNestingDepth?: number;
260
+ }
261
+
262
+ /**
263
+ * Filterable resource instance list section.
264
+ * Fetches data from a bound operation and displays resource instances.
265
+ */
266
+ export interface SidebarSection_ResourceBrowser extends SidebarSectionBase {
267
+ contentKind: SidebarSectionContentKind.RESOURCE_BROWSER;
268
+ /** Resource type to browse. */
269
+ resourceType: string;
270
+ /** Override the default LIST operation (optional — defaults to LIST). */
271
+ operation?: string;
272
+ /** Operation variant for filtered views. */
273
+ operationVariant?: string;
274
+ /**
275
+ * Operation used when the user clicks a listed instance.
276
+ * Defaults to READ when available; otherwise falls back to the bound operation.
277
+ */
278
+ navigateOperation?: string;
279
+ /** Variant for the click/navigation operation. */
280
+ navigateOperationVariant?: string;
281
+ /**
282
+ * Client-side filter predicate applied after fetching.
283
+ * Enables display restrictions (e.g., "starred only").
284
+ */
285
+ instanceFilter?: (instance: Record<string, unknown>) => boolean;
286
+ /**
287
+ * Custom click handler for resource instances.
288
+ * Default: navigate to instance via `NavigationUtils.resolveResourceUrl()`.
289
+ */
290
+ onInstanceClick?: (context: ResourceBrowserClickContext) => void;
291
+ }
292
+
293
+ /** Guidance/onboarding widget section. */
294
+ export interface SidebarSection_GuidanceWidget extends SidebarSectionBase {
295
+ contentKind: SidebarSectionContentKind.GUIDANCE_WIDGET;
296
+ /** Reference to a registered guidance component. */
297
+ guidanceRef: string;
298
+ }
299
+
300
+ /** Arbitrary custom component section. */
301
+ export interface SidebarSection_CustomComponent extends SidebarSectionBase {
302
+ contentKind: SidebarSectionContentKind.CUSTOM_COMPONENT;
303
+ /** The name a component is registered under — engine or application (see `ComponentRegistryRef`, #549). */
304
+ componentRef: string;
305
+ }
306
+
307
+ /**
308
+ * Discriminated union of all sidebar section types.
309
+ * Narrow on `contentKind` to access type-specific properties.
310
+ */
311
+ export type SidebarSection =
312
+ | SidebarSection_NavigationList
313
+ | SidebarSection_ResourceBrowser
314
+ | SidebarSection_GuidanceWidget
315
+ | SidebarSection_CustomComponent;
316
+ ```
@@ -0,0 +1,106 @@
1
+ # saas.frontend.launcher.merge-rules
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-frontend-lib`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-frontend-lib`
10
+
11
+ ```typescript
12
+ *
13
+ * Merges two `contentSections` arrays.
14
+ *
15
+ * **Merge key:** `ref`
16
+ * **Semantics:** App sections **replace** base sections on collision
17
+ * (full section replace, no item-level deep merge). Base-only sections
18
+ * preserved.
19
+ *
20
+ * @param base - Base sections array (e.g., from a kit preset)
21
+ * @param override - App-specific sections array (wins on collision)
22
+ * @returns Merged sections array
23
+ */
24
+ export function mergeSidebarSections(
25
+ base: SidebarSection[] | undefined,
26
+ override: SidebarSection[] | undefined,
27
+ ): SidebarSection[] {
28
+ if (!base && !override) return [];
29
+ if (!base) return warnOnDuplicateLauncherTargets([...(override ?? [])]);
30
+ if (!override) return warnOnDuplicateLauncherTargets([...(base ?? [])]);
31
+
32
+ return warnOnDuplicateLauncherTargets(mergeByKey(base, override, s => s.ref));
33
+ }
34
+ ```
35
+
36
+ ### Origin Package: `@wildo-ai/saas-frontend-lib`
37
+
38
+ ```typescript
39
+ /**
40
+ * Stable key for deduping launcher rows (sidebar children, command list, etc.).
41
+ *
42
+ * Two entries with the same key open the same target, so they are one entry. Every `kind` has its own key, and a
43
+ * settings command keys on its `sectionRef`, so commands opening different settings sections never collapse.
44
+ *
45
+ * Exhaustive over `LauncherItemTargetKind` on purpose. It used to end in a `default` that answered `'unknown'`, and
46
+ * `SETTINGS_SECTION` fell into it: every settings command then shared one key, so an application's `members` command
47
+ * collapsed into the engine's billing command and disappeared. A kind added to the enum is now a compile error here.
48
+ */
49
+ export function launcherItemRefKey(item: LauncherItemRef): string {
50
+ switch (item.kind) {
51
+ case LauncherItemTargetKind.RESOURCE_OPERATION:
52
+ return `resource_operation:${item.resourceType}:${item.operation}:${item.operationVariant ?? 'default'}`;
53
+ case LauncherItemTargetKind.VIEW:
54
+ return `${item.kind}:${item.viewRef}`;
55
+ case LauncherItemTargetKind.RESOURCE_VIEW:
56
+ return `${item.kind}:${item.resourceType}:${item.viewRef}`;
57
+ case LauncherItemTargetKind.ENGINE_PAGE:
58
+ return `engine_page:${item.pageRef}`;
59
+ case LauncherItemTargetKind.CUSTOM_COMPONENT:
60
+ return `custom_component:${item.componentRef}`;
61
+ case LauncherItemTargetKind.SETTINGS_SECTION:
62
+ // No section opens the hub at its landing; that is one destination, so it is one key.
63
+ return `settings_section:${item.sectionRef ?? ''}`;
64
+ default: {
65
+ const unhandled: never = item;
66
+ throw new Error(`launcherItemRefKey: unhandled launcher item kind ${JSON.stringify(unhandled)}`);
67
+ }
68
+ }
69
+ }
70
+
71
+ /**
72
+ * Appends sidebar navigation children to the `NAVIGATION_LIST` section with `sectionRef`.
73
+ * Skips items whose `launcherItemRefKey` already exists under that section (idempotent).
74
+ */
75
+ export function appendNavChildrenToSidebarSection(
76
+ sections: SidebarSection[] | undefined,
77
+ sectionRef: string,
78
+ items: SidebarItem[],
79
+ ): SidebarSection[] {
80
+ if (!sections?.length) return sections ?? [];
81
+ if (!items.length) return [...sections];
82
+
83
+ return sections.map(section => {
84
+ if (section.ref !== sectionRef || section.contentKind !== SidebarSectionContentKind.NAVIGATION_LIST) {
85
+ return section;
86
+ }
87
+ const nav = section as Extract<SidebarSection, { contentKind: SidebarSectionContentKind.NAVIGATION_LIST }>;
88
+ const existing = new Set(nav.children.map(launcherItemRefKey));
89
+ const toAdd = items.filter(i => !existing.has(launcherItemRefKey(i)));
90
+ if (toAdd.length === 0) return section;
91
+ return { ...nav, children: [...nav.children, ...toAdd] };
92
+ });
93
+ }
94
+
95
+ /**
96
+ * Merges command menu command arrays by `launcherItemRefKey` — override wins on collision.
97
+ */
98
+ export function mergeCommandMenuCommandLists(
99
+ base: CommandMenuCommand[] | undefined,
100
+ extra: CommandMenuCommand[] | undefined,
101
+ ): CommandMenuCommand[] {
102
+ if (!base?.length) return [...(extra ?? [])];
103
+ if (!extra?.length) return [...base];
104
+ return mergeByKey(base, extra, launcherItemRefKey);
105
+ }
106
+ ```