@wildo-ai/framework-knowledge 1.1.9 → 1.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (376) hide show
  1. package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
  2. package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
  3. package/dist/claude-marketplace/plugins/wildo/references/acceptance.md +11 -0
  4. package/dist/claude-marketplace/plugins/wildo/references/expert-personas-and-deliberations.md +26 -7
  5. package/dist/claude-marketplace/plugins/wildo/references/runs-judges-and-questions.md +4 -2
  6. package/dist/claude-marketplace/plugins/wildo/skills/accept/SKILL.md +4 -2
  7. package/dist/claude-marketplace/plugins/wildo/skills/why/SKILL.md +9 -3
  8. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  9. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  10. package/dist/esm/framework-knowledge.definitions.js +84 -4
  11. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  12. package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
  13. package/dist/esm/index.d.ts.map +1 -1
  14. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +1 -1
  15. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -1
  16. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +1 -1
  17. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  18. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts.map +1 -1
  19. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +39 -1
  20. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -1
  21. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +132 -20
  22. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
  23. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
  24. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts +8 -4
  25. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts.map +1 -1
  26. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js +13 -6
  27. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js.map +1 -1
  28. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +2 -1
  29. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
  30. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +85 -8
  31. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
  32. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts +4 -3
  33. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts.map +1 -1
  34. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js +4 -3
  35. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js.map +1 -1
  36. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +12 -3
  37. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
  38. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +8 -4
  39. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
  40. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts +4 -1
  41. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts.map +1 -1
  42. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js +2 -1
  43. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js.map +1 -1
  44. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts.map +1 -1
  45. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts.map +1 -1
  46. package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.d.ts.map +1 -1
  47. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts.map +1 -1
  48. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
  49. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +1 -1
  50. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -1
  51. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +13 -1
  52. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
  53. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts.map +1 -1
  54. package/dist/esm/playbooks/refinement.governance-document-candidate/playbook.definition.d.ts.map +1 -1
  55. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +2 -2
  56. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
  57. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +10 -4
  58. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
  59. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts +2 -1
  60. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.d.ts.map +1 -1
  61. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js +5 -3
  62. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js.map +1 -1
  63. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts +2 -1
  64. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts.map +1 -1
  65. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js +11 -9
  66. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js.map +1 -1
  67. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts +17 -3
  68. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts.map +1 -1
  69. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js +19 -2
  70. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js.map +1 -1
  71. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
  72. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
  73. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -1
  74. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -1
  75. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  76. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
  77. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -1
  78. package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts.map +1 -1
  79. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts +27 -6
  80. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts.map +1 -1
  81. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js +32 -12
  82. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js.map +1 -1
  83. package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.d.ts.map +1 -1
  84. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
  85. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  86. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -1
  87. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +2 -1
  88. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
  89. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +13 -5
  90. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
  91. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
  92. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +38 -3
  93. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
  94. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +2 -1
  95. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
  96. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +23 -8
  97. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
  98. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts.map +1 -1
  99. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
  100. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
  101. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
  102. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +11 -0
  103. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
  104. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  105. package/dist/knowledge/manifest.json +7 -7
  106. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +1 -1
  107. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-protocol.json +1 -1
  108. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-treatment.json +1 -1
  109. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +149 -11
  110. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +40 -2
  111. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +55 -0
  112. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +1 -1
  113. package/dist/knowledge/playbooks/bottom_up.conception/playbook.json +10 -2
  114. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-protocol.json +1 -1
  115. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-treatment.json +1 -1
  116. package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +107 -11
  117. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +4 -2
  118. package/dist/knowledge/playbooks/bottom_up.experience-plan/method.md +28 -6
  119. package/dist/knowledge/playbooks/bottom_up.experience-plan/playbook.json +5 -4
  120. package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +50 -0
  121. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +16 -4
  122. package/dist/knowledge/playbooks/bottom_up.website-plan/method.md +19 -0
  123. package/dist/knowledge/playbooks/bottom_up.website-plan/playbook.json +5 -2
  124. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +2 -1
  125. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  126. package/dist/knowledge/playbooks/refinement.document-facts/method.md +8 -0
  127. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +3 -2
  128. package/dist/knowledge/playbooks/refinement.feature-contribution/method.md +5 -2
  129. package/dist/knowledge/playbooks/refinement.feature-contribution/playbook.json +1 -1
  130. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-protocol.json +1 -1
  131. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-treatment.json +1 -1
  132. package/dist/knowledge/playbooks/top_down.brand-identity/method.md +7 -3
  133. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +3 -3
  134. package/dist/knowledge/playbooks/top_down.brand-name-research/method.md +56 -16
  135. package/dist/knowledge/playbooks/top_down.brand-name-research/playbook.json +6 -4
  136. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-protocol.json +1 -1
  137. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-treatment.json +1 -1
  138. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/method.md +30 -9
  139. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/playbook.json +5 -3
  140. package/dist/knowledge/playbooks/top_down.brand-naming/playbook.json +12 -1
  141. package/dist/knowledge/playbooks/top_down.capability-map/method.md +10 -9
  142. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +1 -1
  143. package/dist/knowledge/playbooks/top_down.expert-personas/playbook.json +16 -2
  144. package/dist/knowledge/playbooks/top_down.feature-drafts/method.md +5 -2
  145. package/dist/knowledge/playbooks/top_down.feature-drafts/playbook.json +1 -1
  146. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-protocol.json +1 -1
  147. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-treatment.json +1 -1
  148. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +26 -0
  149. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +4 -2
  150. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-protocol.json +1 -1
  151. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-treatment.json +1 -1
  152. package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +1 -1
  153. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-protocol.json +1 -1
  154. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-treatment.json +1 -1
  155. package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +84 -9
  156. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +6 -3
  157. package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +19 -0
  158. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +19 -1
  159. package/dist/knowledge/references/brand.name-choice.config.md +20 -3
  160. package/dist/knowledge/references/brand.name-screening.config.md +58 -3
  161. package/dist/knowledge/references/build-plan.task-graph.config.md +55 -0
  162. package/dist/knowledge/references/companion.market.prompt-renderer.md +11 -6
  163. package/dist/knowledge/references/example.authorization.application-roles.office-and-field.md +44 -0
  164. package/dist/knowledge/references/example.backend.custom-operation.audit-event.md +81 -0
  165. package/dist/knowledge/references/example.backend.custom-operation.child-line-total.md +258 -0
  166. package/dist/knowledge/references/example.backend.custom-operation.computed-total.md +153 -0
  167. package/dist/knowledge/references/example.backend.custom-operation.create-related-resource.md +107 -0
  168. package/dist/knowledge/references/example.data-seeding.minimal.md +10 -9
  169. package/dist/knowledge/references/example.data-seeding.row-reference.md +80 -0
  170. package/dist/knowledge/references/example.email.template.minimal.md +1 -1
  171. package/dist/knowledge/references/example.resource.config-wiring.retention-policy-operations.md +74 -0
  172. package/dist/knowledge/references/example.resource.personal-data.free-text-field.md +19 -0
  173. package/dist/knowledge/references/example.resource.personal-data.person-without-account.md +27 -0
  174. package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +152 -0
  175. package/dist/knowledge/references/example.resource.ui-behavior.filter-presets.md +15 -0
  176. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -0
  177. package/dist/knowledge/references/example.views.app-level.home-definition.md +13 -0
  178. package/dist/knowledge/references/example.views.chart-definition.shared.md +83 -0
  179. package/dist/knowledge/references/experience-plan.config.md +60 -7
  180. package/dist/knowledge/references/market.context-block.builder.md +1 -1
  181. package/dist/knowledge/references/placement-plan.config.md +43 -0
  182. package/dist/knowledge/references/requirements.functional-requirement.config.md +8 -2
  183. package/dist/knowledge/references/requirements.non-functional-requirement.config.md +2 -0
  184. package/dist/knowledge/references/requirements.references.conventions.md +1 -1
  185. package/dist/knowledge/references/requirements.snapshot.config.md +57 -1
  186. package/dist/knowledge/references/requirements.snapshot.validation.md +35 -1
  187. package/dist/knowledge/references/saas.backend.audit-logs.log-event.md +63 -0
  188. package/dist/knowledge/references/saas.backend.document-sequence.issue-in-operation.md +60 -0
  189. package/dist/knowledge/references/saas.backend.document-sequence.raise-floor.md +156 -0
  190. package/dist/knowledge/references/saas.backend.email.send.md +77 -0
  191. package/dist/knowledge/references/saas.backend.notifications.operation-email-template-ref.md +60 -0
  192. package/dist/knowledge/references/saas.data-seeding.computed-entry.md +43 -0
  193. package/dist/knowledge/references/saas.data-seeding.definition-input.md +8 -2
  194. package/dist/knowledge/references/saas.data-seeding.row-reference.md +93 -0
  195. package/dist/knowledge/references/saas.frontend.collection-filter-presets.md +124 -0
  196. package/dist/knowledge/references/saas.frontend.launcher.item-refs.md +316 -0
  197. package/dist/knowledge/references/saas.frontend.launcher.merge-rules.md +106 -0
  198. package/dist/knowledge/references/saas.frontend.launcher.runtime-availability.md +60 -0
  199. package/dist/knowledge/references/saas.frontend.resource-label-params.md +52 -0
  200. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +47 -18
  201. package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +4 -1
  202. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destination-roles.md +25 -0
  203. package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +2 -2
  204. package/dist/knowledge/references/saas.models.audit.trail-config.md +45 -0
  205. package/dist/knowledge/references/saas.models.notifications.user-notification-definition.md +5 -3
  206. package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +26 -0
  207. package/dist/knowledge/references/saas.models.roles.definition.md +61 -0
  208. package/dist/knowledge/references/saas.models.roles.organization-defaults.md +97 -0
  209. package/dist/knowledge/references/saas.public-runtime.contract.md +26 -0
  210. package/dist/knowledge/references/saas.website.astro.bridge.md +10 -0
  211. package/dist/knowledge/references/saas.website.astro.label-loader.md +3 -0
  212. package/dist/knowledge/references/saas.website.astro.llms-txt-server.md +14 -1
  213. package/dist/knowledge/references/saas.website.astro.site-context.md +13 -0
  214. package/dist/knowledge/references/saas.website.blog.bridge.md +4 -0
  215. package/dist/knowledge/references/saas.website.config.site-context-loader.md +3 -0
  216. package/dist/knowledge/references/saas.website.legal.public-document-links.md +76 -0
  217. package/dist/knowledge/references/saas.website.root-config.seo.md +2 -1
  218. package/dist/knowledge/references/saas.website.runtime.context.md +7 -0
  219. package/dist/knowledge/references/saas.website.seo.llms-txt-config.md +2 -0
  220. package/dist/knowledge/references/website-plan.config.md +26 -0
  221. package/dist/knowledge/references/zod.decorators.chainable-runtime.md +13 -0
  222. package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +7 -0
  223. package/dist/knowledge/references/zod.decorators.document-sequence.md +65 -0
  224. package/dist/knowledge/references/zod.decorators.schema-metadata.md +1 -0
  225. package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +21 -0
  226. package/dist/knowledge/references/zod.factories.bigdecimal.md +1 -0
  227. package/dist/knowledge/references/zod.factories.code.md +1 -0
  228. package/dist/knowledge/references/zod.factories.duration.md +1 -0
  229. package/dist/knowledge/references/zod.factories.money.md +1 -0
  230. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  231. package/dist/knowledge/registries/framework-topics.json +337 -1
  232. package/dist/knowledge/registries/playbooks.json +18 -18
  233. package/dist/knowledge/registries/source-tags.json +1435 -873
  234. package/dist/knowledge/rules/live-context-door.md +1 -1
  235. package/dist/knowledge/skills/INDEX.md +3 -1
  236. package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +16 -3
  237. package/dist/knowledge/skills/application-database-migrations/SKILL.md +14 -3
  238. package/dist/knowledge/skills/application-roles-authoring/SKILL.md +158 -0
  239. package/dist/knowledge/skills/application-roles-authoring/references/framework-application-roles-api.md +169 -0
  240. package/dist/knowledge/skills/application-roles-authoring/references/office-and-field-worked-example.md +63 -0
  241. package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +6 -1
  242. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +256 -9
  243. package/dist/knowledge/skills/backend-custom-operation/references/after-the-operation.md +42 -0
  244. package/dist/knowledge/skills/backend-custom-operation/references/framework-audit-log-event-api.md +220 -0
  245. package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +5 -0
  246. package/dist/knowledge/skills/brand-name-screening/SKILL.md +33 -9
  247. package/dist/knowledge/skills/brand-name-screening/references/framework-brand-name-screening-api.md +78 -6
  248. package/dist/knowledge/skills/brand-name-screening/references/screening-procedure.md +30 -8
  249. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +2 -1
  250. package/dist/knowledge/skills/config-app-shell/SKILL.md +58 -5
  251. package/dist/knowledge/skills/config-app-shell/references/framework-launcher-items-api.md +461 -0
  252. package/dist/knowledge/skills/config-app-shell/references/framework-launcher-visibility-api.md +80 -0
  253. package/dist/knowledge/skills/config-design-system/SKILL.md +28 -6
  254. package/dist/knowledge/skills/config-navigation/SKILL.md +14 -3
  255. package/dist/knowledge/skills/config-saas/SKILL.md +25 -11
  256. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +51 -1
  257. package/dist/knowledge/skills/config-saas/references/framework-audit-trail-config-api.md +62 -2
  258. package/dist/knowledge/skills/config-saas-backend/SKILL.md +6 -1
  259. package/dist/knowledge/skills/configure-billing/SKILL.md +18 -4
  260. package/dist/knowledge/skills/email-add-template/SKILL.md +27 -5
  261. package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +1 -1
  262. package/dist/knowledge/skills/email-add-template/references/framework-email-send-api.md +128 -0
  263. package/dist/knowledge/skills/email-add-template/references/framework-operation-email-template-ref-api.md +99 -0
  264. package/dist/knowledge/skills/engine-component-registration/SKILL.md +6 -1
  265. package/dist/knowledge/skills/engine-product-definitions/SKILL.md +21 -8
  266. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +10 -2
  267. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +18 -4
  268. package/dist/knowledge/skills/frontend-component-catalog/SKILL.md +11 -3
  269. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +2 -1
  270. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +8 -0
  271. package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +18 -4
  272. package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +10 -2
  273. package/dist/knowledge/skills/infra-environment-config/SKILL.md +6 -1
  274. package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +6 -1
  275. package/dist/knowledge/skills/market-add-feature-benefit/SKILL.md +10 -2
  276. package/dist/knowledge/skills/market-alternatives/SKILL.md +10 -2
  277. package/dist/knowledge/skills/market-authoring-overview/SKILL.md +10 -2
  278. package/dist/knowledge/skills/market-category/SKILL.md +21 -7
  279. package/dist/knowledge/skills/market-channels/SKILL.md +6 -1
  280. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +11 -3
  281. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +1 -1
  282. package/dist/knowledge/skills/market-generation-cli/SKILL.md +21 -11
  283. package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +11 -6
  284. package/dist/knowledge/skills/market-icp/SKILL.md +10 -2
  285. package/dist/knowledge/skills/market-jobs-pains-gains/SKILL.md +6 -1
  286. package/dist/knowledge/skills/market-message-templates-authoring/SKILL.md +6 -1
  287. package/dist/knowledge/skills/market-persona/SKILL.md +14 -3
  288. package/dist/knowledge/skills/market-positioning-authoring/SKILL.md +6 -1
  289. package/dist/knowledge/skills/market-proof-and-objection/SKILL.md +10 -2
  290. package/dist/knowledge/skills/market-scoring-interpretation/SKILL.md +6 -1
  291. package/dist/knowledge/skills/market-snapshot-validation/SKILL.md +14 -3
  292. package/dist/knowledge/skills/market-tone-of-voice/SKILL.md +6 -1
  293. package/dist/knowledge/skills/model-cost-attribution/references/framework-work-unit-api.md +26 -0
  294. package/dist/knowledge/skills/module-companion-exports/SKILL.md +7 -1
  295. package/dist/knowledge/skills/module-relationships/SKILL.md +31 -4
  296. package/dist/knowledge/skills/pdf-template-authoring/SKILL.md +4 -2
  297. package/dist/knowledge/skills/provider-address-lookup/SKILL.md +14 -3
  298. package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +6 -1
  299. package/dist/knowledge/skills/provider-operation-calls/SKILL.md +14 -3
  300. package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +10 -2
  301. package/dist/knowledge/skills/resource-add-field/SKILL.md +10 -2
  302. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +46 -17
  303. package/dist/knowledge/skills/resource-add-resource/SKILL.md +14 -2
  304. package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +26 -0
  305. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +29 -3
  306. package/dist/knowledge/skills/resource-config-wiring/references/framework-collection-operation-declarations.md +19 -4
  307. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +5 -2
  308. package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +103 -0
  309. package/dist/knowledge/skills/resource-config-wiring/references/framework-retention-policy-operations.md +135 -0
  310. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +26 -0
  311. package/dist/knowledge/skills/resource-config-wiring/references/framework-user-notifications-api.md +26 -7
  312. package/dist/knowledge/skills/resource-custom-view/SKILL.md +10 -2
  313. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +46 -17
  314. package/dist/knowledge/skills/resource-external-data/references/erasure-suppression.md +2 -2
  315. package/dist/knowledge/skills/resource-retention-binding/SKILL.md +5 -1
  316. package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +15 -1
  317. package/dist/knowledge/skills/resource-schema-authoring/references/computed-totals.md +569 -0
  318. package/dist/knowledge/skills/resource-schema-authoring/references/document-numbers.md +358 -0
  319. package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +8 -0
  320. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +21 -0
  321. package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +7 -2
  322. package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +13 -0
  323. package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +153 -0
  324. package/dist/knowledge/skills/resource-status-lifecycle/references/commercial-documents.md +46 -0
  325. package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +198 -0
  326. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +30 -4
  327. package/dist/knowledge/skills/resource-ui-behavior/references/framework-collection-filter-presets-api.md +157 -0
  328. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +101 -19
  329. package/dist/knowledge/skills/seeding-authoring/SKILL.md +155 -40
  330. package/dist/knowledge/skills/seeding-authoring/references/cross-seed-row-references.md +67 -0
  331. package/dist/knowledge/skills/seeding-authoring/references/framework-data-seeding-api.md +148 -4
  332. package/dist/knowledge/skills/seeding-authoring/references/seed-row-overlay.md +22 -0
  333. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +43 -0
  334. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +2 -2
  335. package/dist/knowledge/skills/spec-companion-exports/SKILL.md +6 -1
  336. package/dist/knowledge/skills/spec-component-update/SKILL.md +10 -2
  337. package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +2 -2
  338. package/dist/knowledge/skills/spec-family-update/SKILL.md +71 -66
  339. package/dist/knowledge/skills/spec-family-update/references/family-spec-routing.md +1 -1
  340. package/dist/knowledge/skills/spec-resource-update/SKILL.md +30 -10
  341. package/dist/knowledge/skills/spec-resource-update/references/resource-spec-field-routing.md +28 -0
  342. package/dist/knowledge/skills/spec-update-after-change/SKILL.md +22 -5
  343. package/dist/knowledge/skills/views-add-composite-view/SKILL.md +6 -1
  344. package/dist/knowledge/skills/views-add-custom-view/SKILL.md +10 -2
  345. package/dist/knowledge/skills/views-app-level/SKILL.md +13 -3
  346. package/dist/knowledge/skills/views-app-level/references/application-home.md +56 -0
  347. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +221 -37
  348. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +22 -5
  349. package/dist/knowledge/skills/views-execution-authoring/SKILL.md +1 -1
  350. package/dist/knowledge/skills/website-anonymous-session/SKILL.md +32 -2
  351. package/dist/knowledge/skills/website-blog-authoring/SKILL.md +16 -3
  352. package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +4 -0
  353. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +7 -1
  354. package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +13 -1
  355. package/dist/knowledge/skills/website-factory-advanced/SKILL.md +10 -2
  356. package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +13 -1
  357. package/dist/knowledge/skills/website-layout-overrides/SKILL.md +6 -1
  358. package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +19 -1
  359. package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +55 -18
  360. package/dist/knowledge/skills/website-navigation-authoring/references/framework-public-document-links-api.md +98 -0
  361. package/dist/knowledge/skills/website-navigation-authoring/references/worked-examples-header-footer.md +8 -11
  362. package/dist/knowledge/skills/website-page-authoring/SKILL.md +16 -5
  363. package/dist/knowledge/skills/website-page-authoring/references/framework-site-context-loader-api.md +3 -0
  364. package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +6 -1
  365. package/dist/knowledge/skills/website-section-faq/SKILL.md +6 -1
  366. package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +6 -1
  367. package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +10 -2
  368. package/dist/knowledge/skills/website-section-hero/SKILL.md +6 -1
  369. package/dist/knowledge/skills/website-section-pricing/SKILL.md +6 -1
  370. package/dist/knowledge/skills/website-section-social-proof/SKILL.md +12 -2
  371. package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +15 -3
  372. package/dist/knowledge/skills/website-seo-aeo-geo/references/geo-api.md +16 -1
  373. package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +2 -1
  374. package/dist/knowledge/topic-index.json +1441 -269
  375. package/dist/tsconfig.build.tsbuildinfo +1 -1
  376. package/package.json +4 -4
@@ -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.`,
@@ -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
  ```
@@ -29,11 +29,12 @@
29
29
  * |-------------------------------|----------|--------------------------------------------------------------------------------|
30
30
  * | `INVALID_REF_FORMAT` | ERROR | A functional / non-functional ref fails its shared pattern (single source of truth with the Zod schema). Defence in depth for type-asserted fixtures. |
31
31
  * | `DUPLICATE_REF` | ERROR | Two functional (or two non-functional) requirements share a ref — the collection silently loses one entity to last-wins indexing. |
32
- * | `DUPLICATE_CROSS_REF` | WARN | The same `icpRefs` (or `jobRefs`) entry is listed more than once on ONE requirement — the repeat is noise the catalog silently dedupes (or double-counts in coverage). Intra-snapshot, so it runs UNCONDITIONALLY (no external set needed) — mirrors the assertions family's `DUPLICATE_PIN_REF`. |
32
+ * | `DUPLICATE_CROSS_REF` | WARN | The same `icpRefs` (or `jobRefs`, or `painRefs`) entry is listed more than once on ONE requirement — the repeat is noise the catalog silently dedupes (or double-counts in coverage). Intra-snapshot, so it runs UNCONDITIONALLY (no external set needed) — mirrors the assertions family's `DUPLICATE_PIN_REF`. |
33
33
  * | `NO_FUNCTIONAL_REQUIREMENTS` | WARN | `functional` empty — the requirements brief states no capability the product must provide. |
34
34
  * | `STALE_AUTHORED` | WARN | Any entity's `authored.lastAuthoredAt + reviewCadence < now`. No check when `reviewCadence` is undefined or `AS_NEEDED`. |
35
35
  * | `UNKNOWN_ICP_REF` | ERROR | An `icpRefs` entry does not resolve in `options.availableIcpRefs`. SKIPPED (fail-soft) when no set is passed — the families are decoupled and the catalog resolves refs. |
36
36
  * | `UNKNOWN_JOB_REF` | ERROR | A `jobRefs` entry does not resolve in `options.availableJobRefs`. SKIPPED (fail-soft) when no set is passed. |
37
+ * | `UNKNOWN_PAIN_REF` | ERROR | A `painRefs` entry or an excluded pain does not resolve in `options.availablePainRefs` (#2500). SKIPPED (fail-soft) when no set is passed. |
37
38
  *
38
39
  * Severity is a TS enum (project rule — enums over literal unions). The
39
40
  * validator never mutates the snapshot. Issue ordering is detector-order
@@ -78,6 +79,11 @@ export enum RequirementsSnapshotIssueKind {
78
79
  * ERROR when a set is supplied; SKIPPED (fail-soft) when it is not.
79
80
  */
80
81
  UNKNOWN_JOB_REF = 'unknown_job_ref',
82
+ /**
83
+ * A `painRefs` entry, or an `excludedMarketPains[].painRef`, does not resolve against the supplied pain-ref set
84
+ * (#2500). ERROR when a set is supplied; SKIPPED (fail-soft) when it is not.
85
+ */
86
+ UNKNOWN_PAIN_REF = 'unknown_pain_ref',
81
87
  }
82
88
 
83
89
  export enum RequirementsSnapshotIssueSeverity {
@@ -129,6 +135,11 @@ export interface ValidateRequirementsSnapshotOptions {
129
135
  * `availableIcpRefs`, reported as `UNKNOWN_JOB_REF`.
130
136
  */
131
137
  availableJobRefs?: ReadonlySet<string>;
138
+ /**
139
+ * Resolvable market pain refs (#2500). Same skip-when-omitted semantics as `availableIcpRefs`, reported as
140
+ * `UNKNOWN_PAIN_REF`, for a requirement's `painRefs` and for an excluded pain.
141
+ */
142
+ availablePainRefs?: ReadonlySet<string>;
132
143
  }
133
144
 
134
145
  /**
@@ -259,6 +270,7 @@ function detectDuplicateCrossRefs(
259
270
  ): void => {
260
271
  checkList(entry.icpRefs, entry, `${collection}[${index}].icpRefs`);
261
272
  checkList(entry.jobRefs, entry, `${collection}[${index}].jobRefs`);
273
+ checkList(entry.painRefs, entry, `${collection}[${index}].painRefs`);
262
274
  };
263
275
 
264
276
  snapshot.functional.forEach((entry, index) => checkEntity(entry, 'functional', index));
@@ -340,9 +352,31 @@ function detectUnknownCrossRefs(
340
352
  });
341
353
  });
342
354
  }
355
+ if (options?.availablePainRefs !== undefined) {
356
+ entry.painRefs?.forEach((painRef, refIndex) => {
357
+ if (options.availablePainRefs!.has(painRef)) return;
358
+ issues.push({
359
+ kind: RequirementsSnapshotIssueKind.UNKNOWN_PAIN_REF,
360
+ path: `${collection}[${index}].painRefs[${refIndex}]`,
361
+ message: `Pain ref "${painRef}" on requirement "${entry.ref}" does not resolve in the supplied pain-ref set.`,
362
+ severity: RequirementsSnapshotIssueSeverity.ERROR,
363
+ });
364
+ });
365
+ }
343
366
  };
344
367
 
345
368
  snapshot.functional.forEach((entry, index) => checkEntity(entry, 'functional', index));
346
369
  snapshot.nonFunctional.forEach((entry, index) => checkEntity(entry, 'nonFunctional', index));
370
+ if (options?.availablePainRefs !== undefined) {
371
+ (snapshot.excludedMarketPains ?? []).forEach((excluded, index) => {
372
+ if (options.availablePainRefs!.has(excluded.painRef)) return;
373
+ issues.push({
374
+ kind: RequirementsSnapshotIssueKind.UNKNOWN_PAIN_REF,
375
+ path: `excludedMarketPains[${index}].painRef`,
376
+ message: `Excluded pain "${excluded.painRef}" does not resolve in the supplied pain-ref set.`,
377
+ severity: RequirementsSnapshotIssueSeverity.ERROR,
378
+ });
379
+ });
380
+ }
347
381
  }
348
382
  ```
@@ -0,0 +1,63 @@
1
+ # saas.backend.audit-logs.log-event
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 an emitter hands to the audit pipeline: the event, minus everything the pipeline derives.
14
+ *
15
+ * You supply `eventType` (your own named vocabulary), `riskLevel`, `eventData` (a flat object of the facts a reviewer
16
+ * needs — ids and states, never secrets or free personal text), and the row's subjects: `userId` (the actor) and
17
+ * `organizationId` (the tenant the event is about). The row is built from what you pass, and an organization's audit
18
+ * view lists only rows carrying its id, so take both from the request: `executionContext.initiatorIds`.
19
+ *
20
+ * Derived, never supplied: `eventId`, `eventCategory`, `severity`, the timestamps, and the principal's kind and
21
+ * delegation (person, agent, machine, through which client) — read from the execution context you pass to `logEvent`.
22
+ * Those are omitted from this type and discarded at runtime.
23
+ */
24
+ export type AuditEventEmission = Omit<AuditableEvent, '_id' | 'eventId' | 'createdAt' | 'updatedAt' | 'eventCategory' | 'severity' | AuditRowAttributionField>;
25
+ ```
26
+
27
+ ### Origin Package: `@wildo-ai/saas-backend-lib`
28
+
29
+ ```typescript
30
+ /**
31
+ * Generic audit-event emitter: how application code records an event of its own.
32
+ *
33
+ * Reach it from a custom operation through the factory's container parameter, resolved on first use:
34
+ * `container.get<AuditLogsBackendService>(SAAS_SERVICE_TYPES.AuditLogsService)` (both from
35
+ * `@wildo-ai/saas-backend-lib`).
36
+ *
37
+ * Accepts any `eventType` string. The application classifies its OWN event types in its backend configuration,
38
+ * `auditTrail.applicationEventTypes: { [eventType]: { category, severity } }`; a declared type is recorded, and
39
+ * routed to the SIEM, with that classification, and the labelling pipeline plans a word for it. An undeclared one is
40
+ * recorded as `{ category: 'data_access', severity: 'info' }`. A framework event type keeps the engine's classification.
41
+ *
42
+ * Per-org SIEM dispatch fires ONLY when an authenticated request `ExecutionContext`
43
+ * (carrying an org) is passed as `requestExecutionContext` — never on the caller-supplied
44
+ * `organizationId` field, which says which tenant the row is ABOUT (tenant segregation).
45
+ *
46
+ * Errors are caught + logged but never thrown — audit emission is
47
+ * fire-and-forget; a logging failure must not affect the request
48
+ * that triggered it.
49
+ */
50
+ public async logEvent(
51
+ auditEvent: AuditEventEmission,
52
+ requestExecutionContext?: ExecutionContext<any>,
53
+ /**
54
+ * The principal, when the caller knows it better than any context it holds (automation, a machine door).
55
+ * It REPLACES the context's principal wholesale: kind, delegating client and machine credential. So never
56
+ * pass `userAuditPrincipal(id)` while holding a delegated or machine context; pass the context instead, or
57
+ * the row will call a delegated client's action the person's own.
58
+ */
59
+ principal?: AuditPrincipalFacts,
60
+ ): Promise<void> {
61
+ return this._createAuditLog(auditEvent, requestExecutionContext, undefined, undefined, undefined, undefined, principal);
62
+ }
63
+ ```
@@ -0,0 +1,60 @@
1
+ # saas.backend.document-sequence.issue-in-operation
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
+ * Number a row from inside the application's own operation: the EXPLICIT case, an invoice drafted without a number and
14
+ * numbered when an "issue" operation runs. It reserves the next number and writes it to the row (with any other fields
15
+ * you pass in `set`) in ONE transaction, and returns the number.
16
+ *
17
+ * Register the operation with `transactionalCore: true` and name the counters as a participant
18
+ * (`documentSequenceCounters: DOCUMENT_SEQUENCE_COUNTERS_RESOURCE_TYPE`), so the counter's increment joins the
19
+ * operation's transaction. The write only lands while the row's number is still empty: issuing an already-numbered row
20
+ * throws a CONFLICT, and the transaction rolls back, so no number is consumed. If anything else in the operation fails,
21
+ * the number is released the same way and the sequence stays gapless.
22
+ *
23
+ * Import from `@wildo-ai/saas-backend-lib`.
24
+ *
25
+ * @example
26
+ * const INVOICE_ISSUE_PARTICIPANTS = { invoices: AppResourceType.INVOICES, documentSequenceCounters: DOCUMENT_SEQUENCE_COUNTERS_RESOURCE_TYPE };
27
+ * // in the "issue" custom implementation, registered with transactionalCore: true and transactionParticipants: INVOICE_ISSUE_PARTICIPANTS
28
+ * const invoiceNumber = await issueDocumentSequenceNumberInOperation(utils, {
29
+ * resourceType: AppResourceType.INVOICES, fieldName: 'invoiceNumber', row: invoice,
30
+ * set: { status: InvoiceStatus.ISSUED, issuedAt: new Date() }, executionContext,
31
+ * });
32
+ */
33
+ export async function issueDocumentSequenceNumberInOperation(
34
+ utils: {
35
+ readonly repositoriesRegistry: RepositoriesRegistryHandlerBackendService;
36
+ readonly errorBuilder: ErrorBuilderBackendService;
37
+ readonly resourcesRegistry: { getResourceConfiguration(resourceType: string): { mainSchema: z.ZodTypeAny } };
38
+ readonly serviceOptions?: { readonly transaction?: RepositoryOptions['transaction'] };
39
+ },
40
+ input: {
41
+ readonly resourceType: string;
42
+ readonly fieldName: string;
43
+ readonly row: Record<string, unknown>;
44
+ readonly set?: Record<string, unknown>;
45
+ readonly executionContext: ExecutionContext<any>;
46
+ },
47
+ ): Promise<string> {
48
+ return issueDocumentSequenceNumber({
49
+ registry: utils.repositoriesRegistry,
50
+ errorBuilder: utils.errorBuilder,
51
+ resourceType: input.resourceType,
52
+ mainSchema: utils.resourcesRegistry.getResourceConfiguration(input.resourceType).mainSchema,
53
+ fieldName: input.fieldName,
54
+ row: input.row,
55
+ set: input.set,
56
+ executionContext: input.executionContext,
57
+ options: utils.serviceOptions?.transaction === undefined ? undefined : { transaction: utils.serviceOptions.transaction },
58
+ });
59
+ }
60
+ ```