@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,152 @@
1
+ # example.resource.status-lifecycle.quote
2
+
3
+
4
+ ## Usage Example
5
+
6
+ ```typescript
7
+ *
8
+ * A quote moves DRAFT → SENT → ACCEPTED or DECLINED. `z_money`, `CurrencySchema`, `CurrencyAllowed` and
9
+ * `DocumentSequenceScope` import from `@wildo-ai/zod-decorators`; everything else below from
10
+ * `@wildo-ai/saas-models` (and `zod`). The schema lives in `<resource>.schemas.ts`, the rest in
11
+ * `<resource>.resources-config.ts`.
12
+ *
13
+ * Four things make it a lifecycle rather than a field anyone edits:
14
+ * 1. `status` is `.excludeFromUpdate()`, so the generic UPDATE cannot move it at all.
15
+ * 2. Each transition is its own operation, `resourceOperationLike: UPDATE` with an empty
16
+ * `requestDto`: the target state is the server's decision, never the caller's.
17
+ * 3. `enabledCondition` says which state the transition starts from. The engine enforces it on the
18
+ * backend (and the UI hides the action), so SEND on an accepted quote is refused.
19
+ * 4. `basicPrefixOperation` returns ONLY the new state and its timestamp (spreading the current row
20
+ * would write every field back, overwriting a concurrent edit), and `authoritativeFields` names
21
+ * them. A key the prefix introduces is kept on the ordinary HTTP path anyway; the declaration is
22
+ * what keeps it when a caller reaches the service with that key already in its payload (an MCP
23
+ * tool, another service), where the strict re-parse would otherwise strip it.
24
+ * And UPDATE itself is enabled only while the quote is a DRAFT: SENT is LOCKED (no edits, yet ACCEPT and
25
+ * DECLINE still move it on) and ACCEPTED and DECLINED are FINAL (nothing moves them again).
26
+ *
27
+ * It is also a COMMERCIAL DOCUMENT, and these fields make it one:
28
+ * - `number` is allocated by the server at create, consecutive per organization and year (`Q-2026-00042`); a client
29
+ * never sends it, and the decorator makes it unique and server-only;
30
+ * - `currency` is the quote's one currency; every amount on it is a fiat `z_money()` in that currency;
31
+ * - `lines` are an array on the quote, so they freeze with it: the UPDATE that edits them is refused once it is SENT;
32
+ * - `total` is the server's: excluded from create and update, computed by a prefix on CREATE and UPDATE with
33
+ * `authoritativeFields: ['total']` from the lines and `discountPercent` (see the computed-total recipe), never typed
34
+ * by a person.
35
+ *
36
+ * Concurrency: the starting-state check runs before the write and is not a compare-and-swap. Two
37
+ * transitions from the same state arriving at the same moment (ACCEPT and DECLINE on one SENT quote)
38
+ * can both pass it, and the last write wins. Sequential calls are refused correctly. Closing the
39
+ * concurrent case is the engine's work (a transition whose write is conditional on its starting state),
40
+ * not something an application can declare today.
41
+ */
42
+ export enum Quote_Status {
43
+ DRAFT = 'DRAFT',
44
+ SENT = 'SENT',
45
+ ACCEPTED = 'ACCEPTED',
46
+ DECLINED = 'DECLINED',
47
+ }
48
+
49
+ export const Quote_Schema = z.object({
50
+ _id: z.string().min(1).isPrimaryKey(),
51
+ organizationId: z.string().min(1).isDBIndexed().isForeignKey().excludeFromUpdate(),
52
+ number: z.string().documentSequence({ format: 'Q-{YYYY}-{n:5}', scope: DocumentSequenceScope.ORGANIZATION }).isSummaryField(),
53
+ title: z.string().trim().min(1).max(200).isSummaryField(),
54
+ currency: CurrencySchema,
55
+ lines: z.array(z.object({
56
+ description: z.string().trim().min(1).max(500),
57
+ quantity: z.number().int().min(1),
58
+ unitPrice: z_money({ currenciesAllowed: [CurrencyAllowed.FIAT] }),
59
+ })).default([]),
60
+ discountPercent: z.number().min(0).max(100).default(0),
61
+ total: z_money({ currenciesAllowed: [CurrencyAllowed.FIAT] }).optional().isSummaryField().excludeFromCreate().excludeFromUpdate(),
62
+ status: z.enum(Quote_Status).default(Quote_Status.DRAFT).isSummaryField().excludeFromCreate().excludeFromUpdate(),
63
+ sentAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),
64
+ decidedAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),
65
+ });
66
+
67
+ /** In `<module>.relationships.ts`: the organization the quote belongs to (its primary scope). */
68
+ export const quote_ResourceRelationships: ResourceRelationship[] = [
69
+ createResourcesRelationship(
70
+ CoreResourceType.ORGANIZATIONS, 'quotes',
71
+ ResourceRelationshipCardinality.ONE, ResourceRelationshipCardinality.MANY,
72
+ { nature: RelationshipNature.COMPOSITION, isPrimaryScope: true, foreignKeyField: 'organizationId' },
73
+ ),
74
+ ];
75
+
76
+ export enum Quote_Operations {
77
+ SEND = 'send',
78
+ ACCEPT = 'accept',
79
+ DECLINE = 'decline',
80
+ }
81
+
82
+ type Quote_CoreOperations = CoreResourceOperation.READ | CoreResourceOperation.LIST | CoreResourceOperation.CREATE | CoreResourceOperation.UPDATE;
83
+
84
+ export const quote_ResourceConfiguration_InitializationFactory = (resourcesRelationships: ResourceRelationship[]) =>
85
+ createResourceConfiguration_Initialization<typeof Quote_Operations, Quote_CoreOperations, typeof Quote_Schema>({
86
+ mainSchema: Quote_Schema,
87
+ resourceIdentifier: 'quotes',
88
+ resourceFieldIdentifier: 'quoteId',
89
+ resourceRelationships: resourcesRelationships,
90
+ isSystemResource: false,
91
+ coreOperations: [CoreResourceOperation.READ, CoreResourceOperation.LIST, CoreResourceOperation.CREATE, CoreResourceOperation.UPDATE],
92
+ customOperation: Quote_Operations,
93
+ operationsConfiguration: {
94
+ [CoreResourceOperation.READ]: { variants: [{ variantType: ResourceOperationVariantType.API_CALL, isDefault: true, roles: [CORE_ORG_ROLES.ORG_MEMBER], riskLevel: ResourceOperationRiskLevel.LOW }] },
95
+ [CoreResourceOperation.LIST]: { variants: [{ variantType: ResourceOperationVariantType.API_CALL, isDefault: true, roles: [CORE_ORG_ROLES.ORG_MEMBER], riskLevel: ResourceOperationRiskLevel.LOW }] },
96
+ [CoreResourceOperation.CREATE]: { variants: [{ variantType: ResourceOperationVariantType.API_CALL, isDefault: true, roles: [CORE_ORG_ROLES.ORG_MEMBER], riskLevel: ResourceOperationRiskLevel.MEDIUM }] },
97
+ [CoreResourceOperation.UPDATE]: {
98
+ variants: [{
99
+ variantType: ResourceOperationVariantType.API_CALL,
100
+ isDefault: true,
101
+ roles: [CORE_ORG_ROLES.ORG_MEMBER],
102
+ riskLevel: ResourceOperationRiskLevel.MEDIUM,
103
+ // Frozen once sent: the content a customer received does not change under them.
104
+ enabledCondition: ({ currentObject }) => currentObject.status === Quote_Status.DRAFT,
105
+ }],
106
+ },
107
+ [Quote_Operations.SEND]: {
108
+ variants: [{
109
+ variantType: ResourceOperationVariantType.API_CALL,
110
+ isDefault: true,
111
+ roles: [CORE_ORG_ROLES.ORG_MEMBER],
112
+ // A decision a customer relies on: HIGH puts every transition in the audit trail.
113
+ riskLevel: ResourceOperationRiskLevel.HIGH,
114
+ resourceOperationLike: CoreResourceOperation.UPDATE,
115
+ requestDto: z.object({}),
116
+ enabledCondition: ({ currentObject }) => currentObject.status === Quote_Status.DRAFT,
117
+ basicPrefixOperation: () => ({ status: Quote_Status.SENT, sentAt: new Date() }),
118
+ authoritativeFields: ['status', 'sentAt'],
119
+ }],
120
+ },
121
+ [Quote_Operations.ACCEPT]: {
122
+ variants: [{
123
+ variantType: ResourceOperationVariantType.API_CALL,
124
+ isDefault: true,
125
+ roles: [CORE_ORG_ROLES.ORG_MEMBER],
126
+ // Only a sent quote can be accepted; accepting a draft is refused.
127
+ riskLevel: ResourceOperationRiskLevel.HIGH,
128
+ resourceOperationLike: CoreResourceOperation.UPDATE,
129
+ requestDto: z.object({}),
130
+ enabledCondition: ({ currentObject }) => currentObject.status === Quote_Status.SENT,
131
+ basicPrefixOperation: () => ({ status: Quote_Status.ACCEPTED, decidedAt: new Date() }),
132
+ authoritativeFields: ['status', 'decidedAt'],
133
+ }],
134
+ },
135
+ [Quote_Operations.DECLINE]: {
136
+ variants: [{
137
+ variantType: ResourceOperationVariantType.API_CALL,
138
+ isDefault: true,
139
+ roles: [CORE_ORG_ROLES.ORG_MEMBER],
140
+ // Starts from SENT like ACCEPT, so after either has run the other is refused. Two calls arriving at the
141
+ // same moment are not serialized: see the concurrency note above.
142
+ riskLevel: ResourceOperationRiskLevel.HIGH,
143
+ resourceOperationLike: CoreResourceOperation.UPDATE,
144
+ requestDto: z.object({}),
145
+ enabledCondition: ({ currentObject }) => currentObject.status === Quote_Status.SENT,
146
+ basicPrefixOperation: () => ({ status: Quote_Status.DECLINED, decidedAt: new Date() }),
147
+ authoritativeFields: ['status', 'decidedAt'],
148
+ }],
149
+ },
150
+ },
151
+ });
152
+ ```
@@ -0,0 +1,15 @@
1
+ # example.resource.ui-behavior.filter-presets
2
+
3
+
4
+ ## Usage Example
5
+
6
+ ```tsx
7
+ presetFilters: [
8
+ { ref: 'urgent', filters: { priority: Todos_Priority.URGENT } },
9
+ { ref: 'overdue', filters: { dueDate: { relativeRange: CollectionFilterPresetRelativeRange.BEFORE_TODAY } } },
10
+ { ref: 'due-this-week', filters: { dueDate: { relativeRange: CollectionFilterPresetRelativeRange.NEXT_7_DAYS } } },
11
+ { ref: 'mine', filters: { assignedToUserId: { contextValue: CollectionFilterPresetContextValue.CURRENT_USER } } },
12
+ { ref: 'created-today', filters: { createdAt: { relativeRange: CollectionFilterPresetRelativeRange.TODAY } } },
13
+ { ref: 'touched-this-week', filters: { updatedAt: { relativeRange: CollectionFilterPresetRelativeRange.LAST_7_DAYS } } },
14
+ ],
15
+ ```
@@ -74,8 +74,16 @@
74
74
  * tomorrow. It resolves against the viewer's own clock at the moment the pill is
75
75
  * pressed, and goes off by itself when the day rolls over.
76
76
  */
77
+ /*
78
+ * `overdue` and `due-this-week` are windows on the due date (#2511), and they combine with the status tabs:
79
+ * "Pending" plus "Overdue" is the list a person opens first. `mine` names the VIEWER, resolved from the session
80
+ * when the pill is clicked, so each person's "Mine" is their own todos; it is disabled for a viewer with no user.
81
+ */
77
82
  presetFilters: [
78
83
  { ref: 'urgent', filters: { priority: Todos_Priority.URGENT } },
84
+ { ref: 'overdue', filters: { dueDate: { relativeRange: CollectionFilterPresetRelativeRange.BEFORE_TODAY } } },
85
+ { ref: 'due-this-week', filters: { dueDate: { relativeRange: CollectionFilterPresetRelativeRange.NEXT_7_DAYS } } },
86
+ { ref: 'mine', filters: { assignedToUserId: { contextValue: CollectionFilterPresetContextValue.CURRENT_USER } } },
79
87
  { ref: 'created-today', filters: { createdAt: { relativeRange: CollectionFilterPresetRelativeRange.TODAY } } },
80
88
  { ref: 'touched-this-week', filters: { updatedAt: { relativeRange: CollectionFilterPresetRelativeRange.LAST_7_DAYS } } },
81
89
  ],
@@ -0,0 +1,13 @@
1
+ # example.views.app-level.home-definition
2
+
3
+
4
+ ## Usage Example
5
+
6
+ ```typescript
7
+ export const homeDefinitionFactory: FrontendConfigFactory_HomeDefinition = () => ({
8
+ // Application root ("/") renders the home dashboard, an application-level composite view, IN PLACE: the URL stays
9
+ // "/", and the composite remains addressable at its own `/composite/<ref>` route. Named by its ref constant, never
10
+ // a string literal, so a renamed view fails to compile here instead of opening on "view not found".
11
+ compositeViewReference: HOME_DASHBOARD_VIEW_REF,
12
+ });
13
+ ```
@@ -0,0 +1,83 @@
1
+ # example.views.chart-definition.shared
2
+
3
+
4
+ ## Usage Example
5
+
6
+ ```typescript
7
+ import type { ChartDefinition, ContextFilter } from '@wildo-ai/saas-models';
8
+ import {
9
+ AggregateFunction,
10
+ ChartType,
11
+ ComparisonOperator,
12
+ ContextFilterSource,
13
+ TimeGranularity,
14
+ } from '@wildo-ai/saas-models';
15
+
16
+ import { TasksManager_ResourceFieldIdentifier, TasksManager_ResourceType } from '../tasks-manager.resources-types';
17
+
18
+ /**
19
+ * Scopes every task chart to its MANDATORY parent todo.
20
+ *
21
+ * The chart embed posts `contextResourceIdentifiers` (resourceType-keyed) with
22
+ * the data request; the backend verifies READ access on the referenced parent
23
+ * and resolves this filter from that trusted map
24
+ * (`parentResource['todos']` → `tasks.todoId`, ObjectId-coerced). Without this
25
+ * filter the "parent todo's tasks" charts silently aggregate EVERY task the
26
+ * caller can see — the query executes fine, so the drift is invisible until
27
+ * someone compares numbers. The backend fails closed when the parent id is
28
+ * missing from the request, and the frontend only surfaces these charts on
29
+ * hosts whose context satisfies the declared MANDATORY parent requirement.
30
+ */
31
+ const parentTodoScopeFilter: ContextFilter = {
32
+ field: TasksManager_ResourceFieldIdentifier[TasksManager_ResourceType.TODOS],
33
+ operator: ComparisonOperator.EQ,
34
+ source: ContextFilterSource.PARENT_RESOURCE,
35
+ sourceField: TasksManager_ResourceType.TODOS,
36
+ };
37
+
38
+ /**
39
+ * `todo-task-status` chart — single source of truth.
40
+ *
41
+ * A resource-owned chart needs its `ChartDefinition` in TWO places:
42
+ * - the FRONTEND `chartViews[].chartDefinition` on the owning resource's
43
+ * ui-behavior (rendering / routing), and
44
+ * - the BACKEND chart registry (so `POST /charts/:chartRef/data` can execute
45
+ * the aggregation query) — fed via the backend module's `chartDefinitions`.
46
+ *
47
+ * `chartViews` is a frontend-only authoring surface the backend cannot import,
48
+ * so the shared `ChartDefinition` data contract is declared HERE in shared-lib
49
+ * and consumed by both layers. Declaring it twice would let the rendered chart
50
+ * and the executed query drift apart.
51
+ *
52
+ * Donut of the current parent todo's tasks, split by execution `status`.
53
+ */
54
+ export const todoTaskStatusChartDefinition: ChartDefinition = {
55
+ ref: 'todo-task-status',
56
+ chartType: ChartType.DONUT,
57
+ dataQuery: {
58
+ mainResourceType: TasksManager_ResourceType.TASKS,
59
+ contextFilters: [parentTodoScopeFilter],
60
+ dimensions: [
61
+ {
62
+ ref: 'status',
63
+ field: 'status',
64
+ },
65
+ ],
66
+ measures: [
67
+ {
68
+ ref: 'count',
69
+ field: '*',
70
+ aggregate: AggregateFunction.COUNT,
71
+ },
72
+ ],
73
+ },
74
+ series: [
75
+ {
76
+ ref: 'tasks-by-status',
77
+ name: 'Tasks by status',
78
+ measureRef: 'count',
79
+ splitByDimension: 'status',
80
+ },
81
+ ],
82
+ };
83
+ ```
@@ -12,8 +12,8 @@
12
12
  *
13
13
  * WHAT THE APPLICATION'S EXPERIENCE IS — which views it carries beyond a resource's own list and
14
14
  * read, how its shell and navigation are composed, which preset components its views reuse (#1493),
15
- * and the JOURNEY a new person takes through it: the milestones it recognises and the guidance that
16
- * gets them there.
15
+ * the JOURNEY a new person takes through it (the milestones it recognises and the guidance that
16
+ * gets them there), and its HOME: what a person sees first when they open it.
17
17
  *
18
18
  * ## Why this family exists
19
19
  *
@@ -212,9 +212,11 @@ export const ExperienceGuidancePlanSchema = z.strictObject({
212
212
  * A document is shown only where a view renders it with `EmbedOnboarding`, so one with no host is
213
213
  * declared and seen by nobody — and its build task would still land, because landing reads the
214
214
  * declaration. Naming the host puts the placement in the plan a person reviews and in the task's
215
- * objective. A planned view's ref, or the ref of a view the application already has — in EITHER case
216
- * a view of the SAME module: the document's build task writes only inside its module, so a host
217
- * elsewhere is one it could not edit. A flow is started by its trigger and has no host, so naming one
215
+ * objective. A view this plan plans — the plan is the application's complete view inventory, restated in
216
+ * full, so a view the application keeps is one it plans — and a view of the SAME module: the document's
217
+ * build task writes only inside its module, so a host elsewhere is one it could not edit. Written as the
218
+ * view's slug, it is stamped like the view (`view-…`). A host the plan does not plan drops the document
219
+ * when the plan lands, and the landing reports it (#2556); the rest of the plan lands. A flow is started by its trigger and has no host, so naming one
218
220
  * would claim a placement that does not exist.
219
221
  */
220
222
  hostViewRef: NonEmptyStringSchema.optional(),
@@ -230,12 +232,61 @@ export const ExperienceGuidancePlanSchema = z.strictObject({
230
232
  });
231
233
  export type ExperienceGuidancePlan = z.infer<typeof ExperienceGuidancePlanSchema>;
232
234
 
235
+ /**
236
+ * What a home IS, as the engine can render one: the app root `/` shows a composite view in place, or redirects to a
237
+ * resource operation (`homeDefinition` in the application's `global-views.config.ts`). Two kinds because those are the
238
+ * two the engine renders; a third would be a plan no configuration can realise.
239
+ */
240
+ export enum ExperienceHomeKind {
241
+ /**
242
+ * A planned `APPLICATION_VIEW`, shown in place at `/`. Only an application view: the root resolves
243
+ * `compositeViewReference` among the application-level composite views, where a view one resource owns
244
+ * (`RESOURCE_COMPOSITE_VIEW`) is not registered, so it would render "view not found".
245
+ */
246
+ VIEW = 'VIEW',
247
+ /** A resource operation (a LIST, a custom verb), reached through its default, non-bulk variant, that the root redirects to. */
248
+ RESOURCE_OPERATION = 'RESOURCE_OPERATION',
249
+ }
250
+
251
+ /**
252
+ * The application's HOME: what a person sees first when they open it. Without one, the application opens on the
253
+ * framework's default welcome page. It lives on the experience plan because the plan owns the views and the
254
+ * GLOBAL_VIEWS surface the home is authored on (`homeDefinitionFactory` in `frontend/src/config/global-views.config.ts`).
255
+ *
256
+ * Its coherence is reported, never a parse failure: a home naming a view the plan lacks is a finding
257
+ * (`HOME_NOT_RENDERABLE`), and the plan keeps its other views.
258
+ *
259
+ * @example
260
+ * home: { kind: ExperienceHomeKind.VIEW, viewRef: 'view-today', rationale: 'Field workers open today\'s jobs first.' }
261
+ */
262
+ export const ExperienceHomePlanSchema = z.discriminatedUnion('kind', [
263
+ z.strictObject({
264
+ kind: z.literal(ExperienceHomeKind.VIEW).systemEnum('ExperienceHomeKind'),
265
+ /** A planned view's ref (`view-…`). */
266
+ viewRef: NonEmptyStringSchema,
267
+ /** Why a person should land here first, in terms of the group that opens the application most. */
268
+ rationale: NonEmptyStringSchema,
269
+ }),
270
+ z.strictObject({
271
+ kind: z.literal(ExperienceHomeKind.RESOURCE_OPERATION).systemEnum('ExperienceHomeKind'),
272
+ moduleRef: SlugSchema,
273
+ resourceRef: SlugSchema,
274
+ /**
275
+ * The operation the root redirects to (`list`, `read`, a custom verb ref). The root matches it exactly against the
276
+ * resource's operations through the default, non-bulk variant; the GLOBAL_VIEWS task spells that out.
277
+ */
278
+ operation: NonEmptyStringSchema,
279
+ rationale: NonEmptyStringSchema,
280
+ }),
281
+ ]);
282
+ export type ExperienceHomePlan = z.infer<typeof ExperienceHomePlanSchema>;
283
+
233
284
  /**
234
285
  * THE experience-plan payload.
235
286
  *
236
287
  * **Artifact-family id: `experience-plan`.** Produced by `bottom_up.experience-plan`, consumed by
237
288
  * `bottom_up.build-decompose`, which emits one task per view, per configuration surface, per
238
- * milestone and per piece of guidance.
289
+ * milestone and per piece of guidance, and sets the decided home in its GLOBAL_VIEWS task.
239
290
  */
240
291
  export const ExperiencePlanSchema = z.object({
241
292
  version: z.enum(ExperiencePlanVersion).default(ExperiencePlanVersion.V1),
@@ -243,7 +294,7 @@ export const ExperiencePlanSchema = z.object({
243
294
  /**
244
295
  * The configuration surfaces this application composes. At least ONE, and it is always the same
245
296
  * one in practice: an application whose navigation and shell are left at the scaffold's defaults
246
- * has no home, no sidebar entry for its own modules and no palette of its own — which is the
297
+ * has no sidebar entry for its own modules, no arrangement of its own and no palette — which is the
247
298
  * "four typechecks and no product" state this lane exists to end.
248
299
  */
249
300
  configurations: z.array(ExperienceConfigurationPlanSchema).min(1),
@@ -251,6 +302,8 @@ export const ExperiencePlanSchema = z.object({
251
302
  milestones: z.array(ExperienceMilestonePlanSchema).default([]),
252
303
  /** The guidance that carries a new person to those moments. */
253
304
  guidance: z.array(ExperienceGuidancePlanSchema).default([]),
305
+ /** What a person sees first. Absent is reported (`NO_HOME`): the application then opens on the default page. */
306
+ home: ExperienceHomePlanSchema.optional(),
254
307
  }).superRefine((plan, context) => {
255
308
  const viewRefs = new Set<string>();
256
309
  plan.views.forEach((view, index) => {
@@ -526,7 +526,7 @@ function normalizeOutputLanguage(value: string | undefined): string | undefined
526
526
  const trimmed = value.trim();
527
527
  if (trimmed.length === 0) return undefined;
528
528
  if (trimmed.length > MAX_OUTPUT_LANGUAGE_LENGTH) {
529
- throw new Error(
529
+ throw new IntrospectionInputValidationError(
530
530
  `buildMarketContextBlock: \`outputLanguage\` is ${trimmed.length} chars long `
531
531
  + `(max ${MAX_OUTPUT_LANGUAGE_LENGTH}). Pass a BCP-47 tag (e.g. \`'fr'\`, \`'pt-BR'\`), `
532
532
  + `not a sentence — translation prose belongs in the LLM output, not the tag.`,
@@ -652,7 +652,7 @@ function detectMissingPositioningForIcp(snapshot: MarketSnapshot, issues: Market
652
652
  const positionedIcpRefs = new Set(snapshot.positionings.map(p => p.icpRef));
653
653
 
654
654
  for (const [iIdx, icp] of snapshot.icps.entries()) {
655
- if (icp.priority !== ICPPriority.CORE && icp.priority !== ICPPriority.EXPANSION) continue;
655
+ if (!TARGETED_ICP_PRIORITIES.has(icp.priority)) continue;
656
656
  if (positionedIcpRefs.has(icp.ref)) continue;
657
657
 
658
658
  issues.push({
@@ -105,6 +105,24 @@ export const PLACEMENT_SURFACE_EXPRESSIBLE_SUBJECT_KINDS: Readonly<Record<Placem
105
105
 
106
106
  const SlugSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);
107
107
 
108
+ /**
109
+ * The surfaces where a placement may be shown to some roles only: the LAUNCHER surfaces, whose entries carry
110
+ * `runtimeAvailability.visibleToRoles` in the application's configuration. The settings rail and the user dropdown hold
111
+ * settings destinations, which carry their own role gating, so an audience declared there is a decision no
112
+ * configuration realises.
113
+ */
114
+ export const PLACEMENT_AUDIENCE_SURFACES: readonly PlacementSurface[] = [
115
+ PlacementSurface.SIDEBAR,
116
+ PlacementSurface.COMMAND_MENU,
117
+ ];
118
+
119
+ /**
120
+ * Who a sidebar section or an entry is shown to: the application's role keys (an office-only "Invoices" section a
121
+ * field technician does not see). Absent means everyone, so an empty list is refused: one spelling per state.
122
+ * Navigation, not authorization: the target operation's own roles are what the backend enforces.
123
+ */
124
+ const PlacementAudienceRolesSchema = z.array(z.string().trim().min(1)).min(1);
125
+
108
126
  /**
109
127
  * A placement group's OWN key (`groupRef` on the group) — the same slug grammar as the other refs,
110
128
  * declared apart from the fields that POINT at a group (an address's `groupRef`).
@@ -149,6 +167,11 @@ export const PlacementGroupSchema = z.strictObject({
149
167
  purpose: NonEmptyStringSchema,
150
168
  /** Sort order among groups on its surface (lower = higher). */
151
169
  order: z.number().int().min(0),
170
+ /**
171
+ * The roles this group is shown to, when it is for one audience only (see `PlacementAudienceRolesSchema`). Only on a
172
+ * SIDEBAR group, where it becomes the section's `runtimeAvailability.visibleToRoles`; refused on a settings category.
173
+ */
174
+ visibleToRoles: PlacementAudienceRolesSchema.optional(),
152
175
  });
153
176
  export type PlacementGroup = z.infer<typeof PlacementGroupSchema>;
154
177
 
@@ -264,6 +287,11 @@ export const PlacementDecisionSchema = z.discriminatedUnion('disposition', [
264
287
  address: PlacementAddressSchema,
265
288
  /** Why this subject belongs at this address. One or two sentences, product-level. */
266
289
  rationale: NonEmptyStringSchema,
290
+ /**
291
+ * The roles this entry is shown to, when it is for one audience only. Only on a launcher surface
292
+ * (`PLACEMENT_AUDIENCE_SURFACES`), where it becomes the entry's `runtimeAvailability.visibleToRoles`.
293
+ */
294
+ visibleToRoles: PlacementAudienceRolesSchema.optional(),
267
295
  /** Required exactly when `origin` is REVISED — enforced below, on the decision itself. */
268
296
  supersedes: PlacementSupersededDecisionSchema.optional(),
269
297
  }),
@@ -298,6 +326,14 @@ export const PlacementDecisionSchema = z.discriminatedUnion('disposition', [
298
326
  path: ['supersedes'],
299
327
  });
300
328
  }
329
+ if (decision.disposition === PlacementDisposition.PLACED && decision.visibleToRoles !== undefined
330
+ && !PLACEMENT_AUDIENCE_SURFACES.includes(decision.address.surface)) {
331
+ context.addIssue({
332
+ code: 'custom',
333
+ message: `placement decision "${decision.decisionRef}" restricts its audience on ${decision.address.surface}, where entries are settings destinations with their own role gating — declare visibleToRoles only on a launcher surface (${PLACEMENT_AUDIENCE_SURFACES.join(', ')})`,
334
+ path: ['visibleToRoles'],
335
+ });
336
+ }
301
337
  if (decision.origin === PlacementDecisionOrigin.DELIBERATED && decision.supersedes !== undefined) {
302
338
  context.addIssue({
303
339
  code: 'custom',
@@ -345,6 +381,13 @@ export const PlacementPlanSchema = z.object({
345
381
  }).superRefine((plan, context) => {
346
382
  const groupKeys = new Set<string>();
347
383
  plan.groups.forEach((group, index) => {
384
+ if (group.visibleToRoles !== undefined && !PLACEMENT_AUDIENCE_SURFACES.includes(group.surface)) {
385
+ context.addIssue({
386
+ code: 'custom',
387
+ message: `placement group "${group.groupRef}" restricts its audience on ${group.surface}, whose categories carry no audience — declare visibleToRoles only on a SIDEBAR section`,
388
+ path: ['groups', index, 'visibleToRoles'],
389
+ });
390
+ }
348
391
  const key = `${group.surface}::${group.groupRef}`;
349
392
  if (groupKeys.has(key)) {
350
393
  context.addIssue({ code: 'custom', message: `duplicate placement group "${group.groupRef}" on surface ${group.surface}`, path: ['groups', index, 'groupRef'] });
@@ -26,9 +26,9 @@
26
26
  * reviewer can check the delivered capability against. Free prose at
27
27
  * scaffold depth (a Gherkin / typed-scenario model is a Phase-J2
28
28
  * concern).
29
- * - **`icpRefs`** / **`jobRefs`** — OPTIONAL flat cross-references into
29
+ * - **`icpRefs`** / **`jobRefs`** / **`painRefs`** — OPTIONAL flat cross-references into
30
30
  * the market family (which ICP segments the requirement serves, which
31
- * jobs-to-be-done it advances). Opaque strings by the `_core`
31
+ * jobs-to-be-done it advances, which market pains it relieves). Opaque strings by the `_core`
32
32
  * reference convention — the market ICP/Job schemas are NOT imported
33
33
  * (families stay decoupled; the catalog resolves the refs, and the
34
34
  * snapshot validator can cross-check them against a supplied set,
@@ -61,6 +61,12 @@ export const FunctionalRequirementConfigSchema = z.object({
61
61
  * advances. Flat opaque strings (see `icpRefs`).
62
62
  */
63
63
  jobRefs: z.array(NonEmptyStringSchema).optional(),
64
+ /**
65
+ * Optional cross-references to the market PAINS this requirement relieves (#2500). Flat opaque strings (see
66
+ * `icpRefs`). What lets "every high-severity pain is addressed or explicitly left out" be checked rather than hoped
67
+ * for: 005's market weighed missed follow-ups heavily and no requirement said so.
68
+ */
69
+ painRefs: z.array(NonEmptyStringSchema).optional(),
64
70
  /** Optional per-entity authoring provenance. */
65
71
  authored: RequirementsAuthoredMetadataSchema.optional(),
66
72
  /**
@@ -93,6 +93,8 @@ export const NonFunctionalRequirementConfigSchema = z.object({
93
93
  * supports. Flat opaque strings (see `icpRefs`).
94
94
  */
95
95
  jobRefs: z.array(NonEmptyStringSchema).optional(),
96
+ /** Optional cross-references to the market pains this quality relieves (#2500), as on a functional requirement. */
97
+ painRefs: z.array(NonEmptyStringSchema).optional(),
96
98
  /** Optional per-entity authoring provenance. */
97
99
  authored: RequirementsAuthoredMetadataSchema.optional(),
98
100
  });
@@ -28,7 +28,7 @@
28
28
  * discrimination is provided by the type aliases below without boxing
29
29
  * at runtime. This holds for BOTH the two intra-family ref shapes
30
30
  * (functional / non-functional) AND the cross-family `icpRefs` /
31
- * `jobRefs` that point into the market family — those are opaque
31
+ * `jobRefs` / `painRefs` that point into the market family — those are opaque
32
32
  * strings here (the catalog, not this family, resolves them, so the
33
33
  * market ICP/Job schemas are deliberately NOT imported — the families
34
34
  * stay decoupled).
@@ -21,6 +21,51 @@ export enum RequirementsSnapshotVersion {
21
21
  V1 = 'v1',
22
22
  }
23
23
 
24
+ /**
25
+ * A fact the product's creator STATED that the requirements deliberately do not turn into a requirement, with the
26
+ * reason.
27
+ *
28
+ * Every stated fact (a data class the product holds, a regulation that applies, a country it serves, a workflow stage,
29
+ * a user group, a scope boundary) is either carried by a requirement or listed here. Without this list, a fact the
30
+ * requirements leave out cannot be told apart from one nobody considered.
31
+ *
32
+ * Not a requirement: it carries no ref and nothing plans against it. Keep `statedFact` close to the creator's words,
33
+ * and make `reason` say why the product does not take it on (out of this horizon, left to another tool, contradicted by
34
+ * a later answer).
35
+ *
36
+ * @example
37
+ * excludedStatedFacts: [
38
+ * { statedFact: 'Invoices are issued from the product.', reason: 'Invoicing stays in the customer\'s accounting tool.' },
39
+ * ]
40
+ */
41
+ export const RequirementsExcludedStatedFactSchema = z.strictObject({
42
+ /** The creator's statement, quoted or closely paraphrased ("Quotes carry the customer's VAT identification number"). */
43
+ statedFact: z.string().trim().min(1),
44
+ /** Why no requirement carries it (out of this horizon, left to another tool, contradicted by a later answer). */
45
+ reason: z.string().trim().min(1),
46
+ });
47
+ export type RequirementsExcludedStatedFact = z.infer<typeof RequirementsExcludedStatedFactSchema>;
48
+
49
+ /**
50
+ * A market PAIN the requirements deliberately do not relieve, with the reason.
51
+ *
52
+ * Every high-severity pain of the targeted customers (severity 7 or more on a CORE or EXPANSION ICP, or on one of its
53
+ * personas) is either relieved by a requirement (`painRefs`) or listed here. Without the list, a pain the product chose
54
+ * not to take on cannot be told apart from one nobody read.
55
+ *
56
+ * @example
57
+ * excludedMarketPains: [
58
+ * { painRef: 'pain-missed-follow-ups', reason: 'Follow-up reminders are the next horizon; the first ships quoting.' },
59
+ * ]
60
+ */
61
+ export const RequirementsExcludedMarketPainSchema = z.strictObject({
62
+ /** The market pain's ref (`pain-…`). */
63
+ painRef: z.string().trim().min(1),
64
+ /** Why no requirement relieves it (a later horizon, outside the product, served by another tool). */
65
+ reason: z.string().trim().min(1),
66
+ });
67
+ export type RequirementsExcludedMarketPain = z.infer<typeof RequirementsExcludedMarketPainSchema>;
68
+
24
69
  /**
25
70
  * THE requirements-snapshot payload — a **single aggregate per product**
26
71
  * (market / vision-snapshot style), NOT a keyed entries map (assertions
@@ -54,10 +99,17 @@ export enum RequirementsSnapshotVersion {
54
99
  * `NonFunctionalRequirementKind` (incl. `COMPLIANCE`, the seam the
55
100
  * compliance-posture playbook (U10) reads alongside vision compliance
56
101
  * constraints).
102
+ * - **`excludedStatedFacts`** — facts the creator stated that no
103
+ * requirement carries, each with its reason (`default([])`). Not
104
+ * ref-addressable: an exclusion is a recorded decision, not something
105
+ * later steps plan against.
106
+ * - **`excludedMarketPains`** — high-severity market pains no requirement
107
+ * relieves, each with its reason (`default([])`), the pain-side twin of
108
+ * `excludedStatedFacts`.
57
109
  *
58
110
  * Authored entirely in English (like the vision / market families).
59
111
  * Authoring-consistency (duplicate refs, ref format, incompleteness,
60
- * staleness, dangling ICP/job cross-refs) is checked by
112
+ * staleness, dangling ICP/job/pain cross-refs) is checked by
61
113
  * `validateRequirementsSnapshot` (see
62
114
  * `requirements-snapshot-validation.ts`); Zod enforces only structural
63
115
  * validity here.
@@ -68,6 +120,10 @@ export const RequirementsSnapshotSchema = z.object({
68
120
  functional: z.array(FunctionalRequirementConfigSchema).default([]),
69
121
  /** Qualities the product must exhibit (incl. compliance). Ref-addressable. */
70
122
  nonFunctional: z.array(NonFunctionalRequirementConfigSchema).default([]),
123
+ /** Stated facts no requirement carries, each with why (#2499). */
124
+ excludedStatedFacts: z.array(RequirementsExcludedStatedFactSchema).default([]),
125
+ /** Market pains no requirement relieves, each with why (#2500). */
126
+ excludedMarketPains: z.array(RequirementsExcludedMarketPainSchema).default([]),
71
127
  });
72
128
  export type RequirementsSnapshot = z.infer<typeof RequirementsSnapshotSchema>;
73
129
  ```