@wildo-ai/framework-knowledge 1.1.10 → 1.1.12

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 (1349) 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 +4 -0
  4. package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +25 -3
  5. package/dist/claude-marketplace/plugins/wildo/references/creation-state.md +40 -12
  6. package/dist/claude-marketplace/plugins/wildo/references/derived-artifacts.md +7 -5
  7. package/dist/claude-marketplace/plugins/wildo/references/runs-judges-and-questions.md +12 -0
  8. package/dist/claude-marketplace/plugins/wildo/skills/answer/SKILL.md +19 -2
  9. package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +33 -9
  10. package/dist/esm/framework-knowledge.definitions.d.ts +2 -3
  11. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  12. package/dist/esm/framework-knowledge.definitions.js +628 -107
  13. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  14. package/dist/esm/framework-knowledge.loader.js.map +1 -1
  15. package/dist/esm/framework-knowledge.research-provenance.d.ts +90 -0
  16. package/dist/esm/framework-knowledge.research-provenance.d.ts.map +1 -0
  17. package/dist/esm/framework-knowledge.research-provenance.js +140 -0
  18. package/dist/esm/framework-knowledge.research-provenance.js.map +1 -0
  19. package/dist/esm/framework-knowledge.schemas.d.ts.map +1 -1
  20. package/dist/esm/framework-knowledge.schemas.js.map +1 -1
  21. package/dist/esm/index.d.ts +2 -0
  22. package/dist/esm/index.d.ts.map +1 -1
  23. package/dist/esm/index.js +2 -0
  24. package/dist/esm/index.js.map +1 -1
  25. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +2 -3
  26. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -1
  27. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +4 -12
  28. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  29. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts.map +1 -1
  30. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js +12 -1
  31. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js.map +1 -1
  32. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +10 -4
  33. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -1
  34. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +82 -15
  35. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
  36. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +1 -5
  37. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
  38. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +4 -16
  39. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
  40. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -1
  41. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -1
  42. package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.d.ts +1 -1
  43. package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.d.ts.map +1 -1
  44. package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.js +1 -1
  45. package/dist/esm/playbooks/bottom_up.capability-composition/playbook.definition.js.map +1 -1
  46. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts +9 -5
  47. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.d.ts.map +1 -1
  48. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js +11 -7
  49. package/dist/esm/playbooks/bottom_up.conception/playbook.definition.js.map +1 -1
  50. package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.d.ts +1 -1
  51. package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.d.ts.map +1 -1
  52. package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.js +1 -1
  53. package/dist/esm/playbooks/bottom_up.documentation-plan/playbook.definition.js.map +1 -1
  54. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
  55. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +38 -14
  56. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
  57. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts +16 -8
  58. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.d.ts.map +1 -1
  59. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js +20 -8
  60. package/dist/esm/playbooks/bottom_up.experience-plan/playbook.definition.js.map +1 -1
  61. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +29 -3
  62. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
  63. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +80 -16
  64. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
  65. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts +2 -2
  66. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts.map +1 -1
  67. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js +7 -2
  68. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
  69. package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.d.ts +2 -2
  70. package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.d.ts.map +1 -1
  71. package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.js +2 -2
  72. package/dist/esm/playbooks/bottom_up.maturity-reading/playbook.definition.js.map +1 -1
  73. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +6 -2
  74. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
  75. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +4 -3
  76. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
  77. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts +26 -7
  78. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.d.ts.map +1 -1
  79. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js +23 -6
  80. package/dist/esm/playbooks/bottom_up.website-plan/playbook.definition.js.map +1 -1
  81. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts +45 -10
  82. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.d.ts.map +1 -1
  83. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.js +61 -21
  84. package/dist/esm/playbooks/cross_cutting.application-creation/playbook.definition.js.map +1 -1
  85. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts +4 -3
  86. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.d.ts.map +1 -1
  87. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.js +8 -5
  88. package/dist/esm/playbooks/cross_cutting.compliance/playbook.definition.js.map +1 -1
  89. package/dist/esm/playbooks/cross_cutting.feature-development/playbook.definition.js.map +1 -1
  90. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts +2 -2
  91. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.d.ts.map +1 -1
  92. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.js +7 -3
  93. package/dist/esm/playbooks/cross_cutting.refinement/playbook.definition.js.map +1 -1
  94. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts +1 -1
  95. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js +3 -3
  96. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js.map +1 -1
  97. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -1
  98. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +9 -7
  99. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
  100. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts +5 -0
  101. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.d.ts.map +1 -1
  102. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.js +9 -2
  103. package/dist/esm/playbooks/refinement.feature-contribution/playbook.definition.js.map +1 -1
  104. package/dist/esm/playbooks/refinement.governance-document-candidate/playbook.definition.js.map +1 -1
  105. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +5 -2
  106. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
  107. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +15 -5
  108. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
  109. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js +1 -1
  110. package/dist/esm/playbooks/top_down.brand-name-research/playbook.definition.js.map +1 -1
  111. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.d.ts.map +1 -1
  112. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js +6 -4
  113. package/dist/esm/playbooks/top_down.brand-name-screening-produce/playbook.definition.js.map +1 -1
  114. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts +3 -1
  115. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.d.ts.map +1 -1
  116. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js +4 -1
  117. package/dist/esm/playbooks/top_down.brand-naming/playbook.definition.js.map +1 -1
  118. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +10 -1
  119. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
  120. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +36 -13
  121. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
  122. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts +8 -2
  123. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
  124. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +7 -1
  125. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -1
  126. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts +4 -1
  127. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -1
  128. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js +34 -6
  129. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js.map +1 -1
  130. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +7 -3
  131. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -1
  132. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +6 -4
  133. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -1
  134. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js +2 -2
  135. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js.map +1 -1
  136. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +22 -10
  137. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
  138. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +39 -29
  139. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -1
  140. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js.map +1 -1
  141. package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts +8 -3
  142. package/dist/esm/playbooks/top_down.definition/playbook.definition.d.ts.map +1 -1
  143. package/dist/esm/playbooks/top_down.definition/playbook.definition.js +24 -9
  144. package/dist/esm/playbooks/top_down.definition/playbook.definition.js.map +1 -1
  145. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts +8 -2
  146. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.d.ts.map +1 -1
  147. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js +8 -2
  148. package/dist/esm/playbooks/top_down.expert-personas/playbook.definition.js.map +1 -1
  149. package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.js +1 -1
  150. package/dist/esm/playbooks/top_down.feature-drafts/playbook.definition.js.map +1 -1
  151. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js.map +1 -1
  152. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js +2 -2
  153. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js.map +1 -1
  154. package/dist/esm/playbooks/top_down.market-research/playbook.definition.js.map +1 -1
  155. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +1 -1
  156. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
  157. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
  158. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +13 -5
  159. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
  160. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +3 -7
  161. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
  162. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +12 -14
  163. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
  164. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts +3 -0
  165. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.d.ts.map +1 -1
  166. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js +2 -1
  167. package/dist/esm/playbooks/top_down.risk-register/playbook.definition.js.map +1 -1
  168. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +3 -1
  169. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
  170. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +2 -1
  171. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -1
  172. package/dist/esm/playbooks/top_down.service-method/playbook.definition.d.ts +98 -0
  173. package/dist/esm/playbooks/top_down.service-method/playbook.definition.d.ts.map +1 -0
  174. package/dist/esm/playbooks/top_down.service-method/playbook.definition.js +124 -0
  175. package/dist/esm/playbooks/top_down.service-method/playbook.definition.js.map +1 -0
  176. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +3 -1
  177. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
  178. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +4 -2
  179. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -1
  180. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +34 -1
  181. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
  182. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +39 -20
  183. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
  184. package/dist/esm/source-anchor-grammar.d.ts +70 -0
  185. package/dist/esm/source-anchor-grammar.d.ts.map +1 -0
  186. package/dist/esm/source-anchor-grammar.js +114 -0
  187. package/dist/esm/source-anchor-grammar.js.map +1 -0
  188. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  189. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  190. package/dist/knowledge/manifest.json +8 -8
  191. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +12 -0
  192. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +4 -4
  193. package/dist/knowledge/playbooks/bottom_up.build/method.md +12 -2
  194. package/dist/knowledge/playbooks/bottom_up.build/playbook.json +5 -3
  195. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-protocol.json +1 -1
  196. package/dist/knowledge/playbooks/bottom_up.build-decompose/evaluation-treatment.json +1 -1
  197. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +788 -49
  198. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +18 -4
  199. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +451 -16
  200. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +3 -6
  201. package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +1 -0
  202. package/dist/knowledge/playbooks/bottom_up.capability-composition/method.md +2 -2
  203. package/dist/knowledge/playbooks/bottom_up.capability-composition/playbook.json +3 -2
  204. package/dist/knowledge/playbooks/bottom_up.conception/method.md +12 -7
  205. package/dist/knowledge/playbooks/bottom_up.conception/playbook.json +4 -3
  206. package/dist/knowledge/playbooks/bottom_up.documentation-plan/method.md +2 -2
  207. package/dist/knowledge/playbooks/bottom_up.documentation-plan/playbook.json +2 -1
  208. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-protocol.json +1 -1
  209. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-treatment.json +1 -1
  210. package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +115 -2
  211. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +11 -4
  212. package/dist/knowledge/playbooks/bottom_up.experience-plan/method.md +71 -7
  213. package/dist/knowledge/playbooks/bottom_up.experience-plan/playbook.json +19 -6
  214. package/dist/knowledge/playbooks/bottom_up.foundation/method.md +126 -24
  215. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +51 -7
  216. package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +28 -9
  217. package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +5 -3
  218. package/dist/knowledge/playbooks/bottom_up.maturity-reading/method.md +10 -2
  219. package/dist/knowledge/playbooks/bottom_up.maturity-reading/playbook.json +4 -3
  220. package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +67 -5
  221. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +10 -3
  222. package/dist/knowledge/playbooks/bottom_up.website-plan/method.md +176 -22
  223. package/dist/knowledge/playbooks/bottom_up.website-plan/playbook.json +21 -3
  224. package/dist/knowledge/playbooks/cross_cutting.application-creation/method.md +27 -12
  225. package/dist/knowledge/playbooks/cross_cutting.application-creation/playbook.json +11 -5
  226. package/dist/knowledge/playbooks/cross_cutting.compliance/method.md +4 -4
  227. package/dist/knowledge/playbooks/cross_cutting.compliance/playbook.json +7 -2
  228. package/dist/knowledge/playbooks/cross_cutting.feature-development/playbook.json +1 -0
  229. package/dist/knowledge/playbooks/cross_cutting.refinement/method.md +6 -5
  230. package/dist/knowledge/playbooks/cross_cutting.refinement/playbook.json +5 -2
  231. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/evaluation-protocol.json +1 -1
  232. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/evaluation-treatment.json +1 -1
  233. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +153 -28
  234. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +3 -2
  235. package/dist/knowledge/playbooks/refinement.document-facts/method.md +36 -7
  236. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +6 -2
  237. package/dist/knowledge/playbooks/refinement.feature-contribution/playbook.json +9 -2
  238. package/dist/knowledge/playbooks/refinement.governance-document-candidate/method.md +8 -6
  239. package/dist/knowledge/playbooks/refinement.governance-document-candidate/playbook.json +2 -1
  240. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-protocol.json +1 -1
  241. package/dist/knowledge/playbooks/top_down.brand-identity/evaluation-treatment.json +1 -1
  242. package/dist/knowledge/playbooks/top_down.brand-identity/method.md +9 -2
  243. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +17 -5
  244. package/dist/knowledge/playbooks/top_down.brand-name-research/method.md +11 -4
  245. package/dist/knowledge/playbooks/top_down.brand-name-research/playbook.json +3 -2
  246. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-protocol.json +1 -1
  247. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/evaluation-treatment.json +1 -1
  248. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/method.md +16 -6
  249. package/dist/knowledge/playbooks/top_down.brand-name-screening-produce/playbook.json +3 -2
  250. package/dist/knowledge/playbooks/top_down.brand-naming/playbook.json +5 -1
  251. package/dist/knowledge/playbooks/top_down.business-model/evaluation-protocol.json +1 -1
  252. package/dist/knowledge/playbooks/top_down.business-model/evaluation-treatment.json +1 -1
  253. package/dist/knowledge/playbooks/top_down.business-model/method.md +49 -11
  254. package/dist/knowledge/playbooks/top_down.business-model/playbook.json +24 -8
  255. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +6 -2
  256. package/dist/knowledge/playbooks/top_down.compliance-analysis/method.md +1 -1
  257. package/dist/knowledge/playbooks/top_down.compliance-analysis/playbook.json +49 -14
  258. package/dist/knowledge/playbooks/top_down.compliance-conception/method.md +15 -5
  259. package/dist/knowledge/playbooks/top_down.compliance-conception/playbook.json +6 -2
  260. package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/method.md +20 -0
  261. package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/playbook.json +4 -3
  262. package/dist/knowledge/playbooks/top_down.compliance-posture/evaluation-protocol.json +1 -1
  263. package/dist/knowledge/playbooks/top_down.compliance-posture/evaluation-treatment.json +1 -1
  264. package/dist/knowledge/playbooks/top_down.compliance-posture/method.md +69 -65
  265. package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +11 -7
  266. package/dist/knowledge/playbooks/top_down.compliance-research/playbook.json +1 -0
  267. package/dist/knowledge/playbooks/top_down.definition/method.md +10 -3
  268. package/dist/knowledge/playbooks/top_down.definition/playbook.json +14 -5
  269. package/dist/knowledge/playbooks/top_down.expert-personas/method.md +10 -3
  270. package/dist/knowledge/playbooks/top_down.expert-personas/playbook.json +4 -3
  271. package/dist/knowledge/playbooks/top_down.feature-drafts/playbook.json +2 -1
  272. package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +1 -0
  273. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/method.md +4 -2
  274. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +4 -3
  275. package/dist/knowledge/playbooks/top_down.market-research/playbook.json +1 -0
  276. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +3 -0
  277. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +3 -2
  278. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-protocol.json +1 -1
  279. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-treatment.json +1 -1
  280. package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +1 -0
  281. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +10 -6
  282. package/dist/knowledge/playbooks/top_down.risk-register/method.md +8 -1
  283. package/dist/knowledge/playbooks/top_down.risk-register/playbook.json +5 -1
  284. package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +6 -1
  285. package/dist/knowledge/playbooks/top_down.service-method/method.md +216 -0
  286. package/dist/knowledge/playbooks/top_down.service-method/playbook.json +108 -0
  287. package/dist/knowledge/playbooks/top_down.value-proposition/method.md +5 -2
  288. package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +9 -3
  289. package/dist/knowledge/playbooks/top_down.vision-elicitation/evaluation-protocol.json +1 -1
  290. package/dist/knowledge/playbooks/top_down.vision-elicitation/evaluation-treatment.json +1 -1
  291. package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +21 -2
  292. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +63 -18
  293. package/dist/knowledge/references/acp.execution-profile.md +9 -1
  294. package/dist/knowledge/references/application-documentation-chapters.config.md +45 -10
  295. package/dist/knowledge/references/application-documentation-plan.config.md +2 -2
  296. package/dist/knowledge/references/application-maturity.config.md +28 -2
  297. package/dist/knowledge/references/backend.inbound-channels.attachment-adoption.md +57 -0
  298. package/dist/knowledge/references/backend.inbound-channels.handler-definition.md +65 -13
  299. package/dist/knowledge/references/backend.inbound-handlers.agents.md +10 -3
  300. package/dist/knowledge/references/backend.inbound-handlers.definition.md +463 -5
  301. package/dist/knowledge/references/backend.inbound-handlers.pipelines.md +62 -0
  302. package/dist/knowledge/references/blueprint.definition-contract.md +483 -0
  303. package/dist/knowledge/references/brand.name-screening.config.md +30 -3
  304. package/dist/knowledge/references/brand.visual-tone.config.md +26 -8
  305. package/dist/knowledge/references/build-plan.task-graph.config.md +438 -12
  306. package/dist/knowledge/references/business-model.pricing-plan.config.md +19 -9
  307. package/dist/knowledge/references/business-model.snapshot.config.md +29 -2
  308. package/dist/knowledge/references/business-model.snapshot.validation.md +29 -8
  309. package/dist/knowledge/references/capability-composition.config.md +4 -3
  310. package/dist/knowledge/references/cli.market.generate-command.md +2 -1
  311. package/dist/knowledge/references/companion.introspection.behaviors.market.md +3 -0
  312. package/dist/knowledge/references/companion.market.generation-service.md +46 -5
  313. package/dist/knowledge/references/companion.market.prompt-renderer.md +1 -1
  314. package/dist/knowledge/references/companion.technical-doc.service.md +342 -76
  315. package/dist/knowledge/references/domain-plan.record-partition.md +105 -0
  316. package/dist/knowledge/references/engine.client-bundle.allow-list.md +16 -0
  317. package/dist/knowledge/references/engine.saas-technical-doc.config.md +69 -15
  318. package/dist/knowledge/references/engine.saas-website.config.md +16 -44
  319. package/dist/knowledge/references/example.ai-use-declaration.agent.md +37 -0
  320. package/dist/knowledge/references/example.authorization.application-roles.office-and-field.md +10 -0
  321. package/dist/knowledge/references/{example.authorization.service-provider-organization-wide-access.md → example.authorization.relationship-organization-wide-access.md} +2 -2
  322. package/dist/knowledge/references/example.backend.addon-wiring.module.md +6 -0
  323. package/dist/knowledge/references/example.backend.custom-operation.child-line-total.md +4 -3
  324. package/dist/knowledge/references/example.backend.custom-operation.create-related-resource.md +22 -0
  325. package/dist/knowledge/references/example.backend.custom-operation.declared-refusal-code.md +41 -0
  326. package/dist/knowledge/references/example.backend.custom-operation.external-effect-reservation.md +107 -0
  327. package/dist/knowledge/references/example.blueprint.definition.internal-tool.md +47 -0
  328. package/dist/knowledge/references/example.config.app-shell.full.md +6 -3
  329. package/dist/knowledge/references/example.config.app-shell.hosted-components.md +4 -1
  330. package/dist/knowledge/references/example.config.backend.inbound-email.md +4 -2
  331. package/dist/knowledge/references/example.config.backend.required-floors.md +4 -2
  332. package/dist/knowledge/references/example.config.design-system.full.md +40 -116
  333. package/dist/knowledge/references/example.flows-actors.autonomous-agent.reviewed-write.md +10 -0
  334. package/dist/knowledge/references/example.flows-actors.chat-assistant.md +78 -19
  335. package/dist/knowledge/references/example.flows-actors.declared-flow.md +115 -0
  336. package/dist/knowledge/references/example.flows-actors.llm-agent-one-shot.md +12 -0
  337. package/dist/knowledge/references/example.inbound.email-channel-handler.md +10 -1
  338. package/dist/knowledge/references/example.infra.environment-config.local.md +34 -63
  339. package/dist/knowledge/references/example.layout-2d.registration.md +11 -0
  340. package/dist/knowledge/references/example.minion.contained-tick.md +1 -1
  341. package/dist/knowledge/references/example.module.companion-exports.full.md +1 -0
  342. package/dist/knowledge/references/example.module.relationships.actor-edge-back-to-scope-owner.md +35 -35
  343. package/dist/knowledge/references/example.module.relationships.scope-membership-junction.md +8 -10
  344. package/dist/knowledge/references/example.navigation.one-entry-per-concept.md +47 -0
  345. package/dist/knowledge/references/example.organization-identity.system-of-record-partitions.md +18 -0
  346. package/dist/knowledge/references/example.organizations.relationship-kinds.md +26 -0
  347. package/dist/knowledge/references/example.professional-qualifications.declaration.md +10 -0
  348. package/dist/knowledge/references/example.professional-qualifications.gate.md +25 -0
  349. package/dist/knowledge/references/example.provider.backend-module-shape.md +38 -4
  350. package/dist/knowledge/references/example.provider.frontend-facet.on-demand-sdk.md +41 -0
  351. package/dist/knowledge/references/example.provider.frontend-file-picker.contribution.md +4 -5
  352. package/dist/knowledge/references/example.rate-limit.resource-operation-surface.md +7 -5
  353. package/dist/knowledge/references/example.resource.add-resource.module-factory-map.md +0 -5
  354. package/dist/knowledge/references/example.resource.custom-view.backend-refusal.md +75 -0
  355. package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +8 -7
  356. package/dist/knowledge/references/example.resource.ui-behavior.enum-badge.md +23 -7
  357. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +87 -22
  358. package/dist/knowledge/references/example.resource.ui-behavior.record-template.md +80 -0
  359. package/dist/knowledge/references/example.resource.ui-behavior.surface-decision.md +20 -21
  360. package/dist/knowledge/references/example.resource.ui-behavior.workflow-record-page.md +212 -0
  361. package/dist/knowledge/references/example.spec.composite-view.workspace.md +10 -2
  362. package/dist/knowledge/references/example.subject-export.portability-archive.md +42 -0
  363. package/dist/knowledge/references/example.views.app-level.workflow-home.md +238 -0
  364. package/dist/knowledge/references/example.views.composite-view.workspace.md +10 -3
  365. package/dist/knowledge/references/example.website.blocks.section.md +20 -0
  366. package/dist/knowledge/references/example.website.blocks.site-choices.md +78 -0
  367. package/dist/knowledge/references/example.website.blocks.site-configs.md +155 -0
  368. package/dist/knowledge/references/example.website.demo.append.md +57 -0
  369. package/dist/knowledge/references/example.website.demo.approval.md +47 -0
  370. package/dist/knowledge/references/example.website.demo.celebrate.md +39 -0
  371. package/dist/knowledge/references/example.website.demo.complete-items.md +103 -0
  372. package/dist/knowledge/references/example.website.demo.connect.md +45 -0
  373. package/dist/knowledge/references/example.website.demo.dashboard.md +74 -0
  374. package/dist/knowledge/references/example.website.demo.query-answer.md +77 -0
  375. package/dist/knowledge/references/example.website.demo.status-lifecycle.md +71 -0
  376. package/dist/knowledge/references/example.website.demo.transform.md +43 -0
  377. package/dist/knowledge/references/example.website.page.manifest.md +2 -6
  378. package/dist/knowledge/references/example.website.pricing.audit-payloads.md +38 -0
  379. package/dist/knowledge/references/example.website.pricing.catalog-load.md +77 -0
  380. package/dist/knowledge/references/example.website.pricing.offers.md +43 -0
  381. package/dist/knowledge/references/example.website.pricing.plans-section.md +20 -0
  382. package/dist/knowledge/references/example.website.pricing.plans.md +88 -0
  383. package/dist/knowledge/references/example.website.section.bento.md +27 -0
  384. package/dist/knowledge/references/example.website.section.contact-form.md +15 -0
  385. package/dist/knowledge/references/example.website.section.factories.md +82 -0
  386. package/dist/knowledge/references/example.website.section.faq.md +17 -0
  387. package/dist/knowledge/references/example.website.section.footer-cta.md +13 -0
  388. package/dist/knowledge/references/example.website.section.hero.md +16 -0
  389. package/dist/knowledge/references/example.website.section.latest-posts.md +15 -0
  390. package/dist/knowledge/references/example.website.section.marquee.md +26 -0
  391. package/dist/knowledge/references/example.website.section.roadmap.md +25 -0
  392. package/dist/knowledge/references/example.website.section.site-block.md +43 -0
  393. package/dist/knowledge/references/example.website.section.solution-paths.md +17 -0
  394. package/dist/knowledge/references/example.website.section.stats.md +23 -0
  395. package/dist/knowledge/references/example.website.section.steps.md +15 -0
  396. package/dist/knowledge/references/example.website.showcase.tour.md +49 -0
  397. package/dist/knowledge/references/example.website.theme.composed.md +69 -0
  398. package/dist/knowledge/references/experience-plan.config.md +127 -1
  399. package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +8 -0
  400. package/dist/knowledge/references/external-connectors.frontend-provider-sdk-activation-mode.md +27 -0
  401. package/dist/knowledge/references/external-connectors.models.connection-target.md +99 -0
  402. package/dist/knowledge/references/external-connectors.models.file-storage-adapter.md +13 -0
  403. package/dist/knowledge/references/external-connectors.models.hook-inbound-endpoint.md +352 -0
  404. package/dist/knowledge/references/external-connectors.models.hook-signature-algorithms.md +168 -0
  405. package/dist/knowledge/references/external-connectors.models.hook-trigger-strategy.md +97 -0
  406. package/dist/knowledge/references/external-connectors.models.oauth2-audiences.md +72 -8
  407. package/dist/knowledge/references/external-connectors.models.oauth2-incremental-consent.md +235 -0
  408. package/dist/knowledge/references/external-connectors.models.rest-operation-contract.md +1272 -3
  409. package/dist/knowledge/references/external-connectors.models.subject-erasure-effect.md +105 -0
  410. package/dist/knowledge/references/external-connectors.private.provider-compliance-state-collector.md +36 -0
  411. package/dist/knowledge/references/external-connectors.private.provider-configuration-check.md +69 -0
  412. package/dist/knowledge/references/integration-plan.config.md +28 -8
  413. package/dist/knowledge/references/market.references.weighted-edges.md +14 -1
  414. package/dist/knowledge/references/minions.tick-contract.md +2 -2
  415. package/dist/knowledge/references/placement-plan.config.md +94 -13
  416. package/dist/knowledge/references/platform.config.backing-services.md +9 -11
  417. package/dist/knowledge/references/platform.config.environment.deployment.md +140 -7
  418. package/dist/knowledge/references/platform.config.infra-provider-resolution.md +3 -3
  419. package/dist/knowledge/references/platform.config.infrastructure-host.md +2 -1
  420. package/dist/knowledge/references/platform.config.platform-key-management.md +282 -0
  421. package/dist/knowledge/references/platform.config.saas.md +126 -32
  422. package/dist/knowledge/references/platform.key-management.vault-custody.md +78 -0
  423. package/dist/knowledge/references/presets.3d.frame-style-resolution.md +65 -0
  424. package/dist/knowledge/references/presets.3d.layout-contract.md +4 -30
  425. package/dist/knowledge/references/presets.3d.register-layout.md +14 -36
  426. package/dist/knowledge/references/presets.layouts-2d.authoring.md +157 -0
  427. package/dist/knowledge/references/presets.layouts-2d.register-layout.md +53 -0
  428. package/dist/knowledge/references/presets.layouts-2d.settings.md +53 -0
  429. package/dist/knowledge/references/presets.layouts-2d.vocabulary.md +41 -0
  430. package/dist/knowledge/references/presets.models.field-form-control-variant.md +32 -0
  431. package/dist/knowledge/references/presets.models.labelling.sections.md +39 -0
  432. package/dist/knowledge/references/presets.models.palette-contrast.md +183 -0
  433. package/dist/knowledge/references/presets.models.palette-derivation.md +93 -0
  434. package/dist/knowledge/references/presets.models.surface-policy.defaults.md +27 -0
  435. package/dist/knowledge/references/presets.models.surface-variant.md +11 -0
  436. package/dist/knowledge/references/presets.models.theme-contract.md +136 -0
  437. package/dist/knowledge/references/presets.models.theme-personality-lexicon.md +81 -0
  438. package/dist/knowledge/references/presets.models.theme-personality.md +159 -0
  439. package/dist/knowledge/references/presets.themes.compose-theme.md +47 -0
  440. package/dist/knowledge/references/requirements.non-functional-requirement.config.md +4 -4
  441. package/dist/knowledge/references/requirements.snapshot.config.md +2 -3
  442. package/dist/knowledge/references/roadmap.phase.config.md +2 -16
  443. package/dist/knowledge/references/saas.approval-seals.admin-endpoints.md +158 -0
  444. package/dist/knowledge/references/saas.backend.a2a.token-budget.md +85 -12
  445. package/dist/knowledge/references/saas.backend.actor-execution-continuation.md +179 -0
  446. package/dist/knowledge/references/saas.backend.app-config.backend-authored.md +5 -1
  447. package/dist/knowledge/references/saas.backend.application-initialization.assembly.md +3 -1
  448. package/dist/knowledge/references/saas.backend.authorization.role-ceiling.md +13 -1
  449. package/dist/knowledge/references/saas.backend.crypto-keys.application-keys.md +100 -0
  450. package/dist/knowledge/references/saas.backend.custom-operation.authoritative-fields.md +4 -1
  451. package/dist/knowledge/references/saas.backend.custom-operation.commit-outcome-read-back.md +208 -0
  452. package/dist/knowledge/references/saas.backend.custom-operation.core-write-precondition.md +38 -0
  453. package/dist/knowledge/references/saas.backend.custom-operation.external-effect-reservation.md +109 -0
  454. package/dist/knowledge/references/saas.backend.custom-operation.hook-transaction-posture.md +43 -0
  455. package/dist/knowledge/references/saas.backend.custom-operation.target-authority.md +33 -0
  456. package/dist/knowledge/references/saas.backend.custom-operation.transactional-core.md +131 -1
  457. package/dist/knowledge/references/saas.backend.document-sequence.issue-in-operation.md +1 -1
  458. package/dist/knowledge/references/saas.backend.document-sequence.raise-floor.md +62 -13
  459. package/dist/knowledge/references/saas.backend.domain-module.md +105 -1
  460. package/dist/knowledge/references/saas.backend.email-template.definition.md +34 -0
  461. package/dist/knowledge/references/saas.backend.email-template.words.md +98 -0
  462. package/dist/knowledge/references/saas.backend.email.send.md +7 -0
  463. package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +35 -4
  464. package/dist/knowledge/references/saas.backend.flows-actors.ask-person-tool.md +79 -0
  465. package/dist/knowledge/references/saas.backend.flows-actors.autonomous-agent-case-selector.md +71 -0
  466. package/dist/knowledge/references/saas.backend.flows-actors.autonomous-agent-declaration.md +21 -10
  467. package/dist/knowledge/references/saas.backend.flows-actors.autonomous-agent-schedule.md +11 -5
  468. package/dist/knowledge/references/saas.backend.flows-actors.chat-agent-declaration.md +51 -0
  469. package/dist/knowledge/references/saas.backend.flows-actors.chat-reply-handler.md +219 -0
  470. package/dist/knowledge/references/saas.backend.flows-actors.decision-notice-handler.md +239 -0
  471. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +661 -3
  472. package/dist/knowledge/references/saas.backend.flows-actors.invoke-agent.md +15 -2
  473. package/dist/knowledge/references/saas.backend.flows-actors.operation-approval-resolvers.md +50 -0
  474. package/dist/knowledge/references/saas.backend.flows-actors.present-records-tool.md +106 -0
  475. package/dist/knowledge/references/saas.backend.flows-actors.resource-read-tool.md +14 -1
  476. package/dist/knowledge/references/saas.backend.flows-actors.resource-write-tool.md +9 -4
  477. package/dist/knowledge/references/saas.backend.flows-actors.retrieval-tool.md +205 -0
  478. package/dist/knowledge/references/saas.backend.flows-actors.tool-dispatch-obligations.md +21 -5
  479. package/dist/knowledge/references/saas.backend.flows.start-flow-method.md +28 -0
  480. package/dist/knowledge/references/saas.backend.flows.start-flow.md +47 -0
  481. package/dist/knowledge/references/saas.backend.pdf-template.collection-definition.md +5 -3
  482. package/dist/knowledge/references/saas.backend.privacy.subject-export-archive.md +26 -0
  483. package/dist/knowledge/references/saas.backend.providers.connection-target-credential-resolution.md +21 -19
  484. package/dist/knowledge/references/saas.backend.providers.optional-runtime-peers.md +15 -25
  485. package/dist/knowledge/references/saas.backend.rate-limit-service.check-policy.md +3 -2
  486. package/dist/knowledge/references/saas.backend.submission-challenge.md +4 -0
  487. package/dist/knowledge/references/saas.backend.system-access-service.md +394 -104
  488. package/dist/knowledge/references/saas.config.content-security-policy.md +26 -10
  489. package/dist/knowledge/references/saas.data-seeding.definition-input.md +1 -1
  490. package/dist/knowledge/references/saas.data-seeding.modes.md +4 -1
  491. package/dist/knowledge/references/saas.data-seeding.row-reference.md +2 -4
  492. package/dist/knowledge/references/saas.data-seeding.run-ledger.md +3 -0
  493. package/dist/knowledge/references/saas.external-data.admin-endpoints.md +70 -3
  494. package/dist/knowledge/references/saas.external-providers.backend-provider-loader.md +6 -0
  495. package/dist/knowledge/references/saas.external-providers.backend-provider-registry.runtime-filter.md +2 -0
  496. package/dist/knowledge/references/saas.external-providers.llm.model-configuration.md +3 -0
  497. package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +10 -2
  498. package/dist/knowledge/references/saas.frontend.app-level-component.vocabulary.md +10 -16
  499. package/dist/knowledge/references/saas.frontend.app-shell.building-blocks.md +7 -3
  500. package/dist/knowledge/references/saas.frontend.app-shell.register-shell-layout.md +97 -0
  501. package/dist/knowledge/references/saas.frontend.app-shell.shell-layout-contract.md +60 -0
  502. package/dist/knowledge/references/saas.frontend.app-shell.shell-motion-contract.md +274 -0
  503. package/dist/knowledge/references/saas.frontend.app-shell.use-shell-motion.md +73 -0
  504. package/dist/knowledge/references/saas.frontend.brand-identity.md +6 -0
  505. package/dist/knowledge/references/saas.frontend.chart-dashboard-view.md +43 -0
  506. package/dist/knowledge/references/saas.frontend.chart-dashboard.md +130 -0
  507. package/dist/knowledge/references/saas.frontend.chart-view.inserted-declaration.md +13 -0
  508. package/dist/knowledge/references/saas.frontend.chart-view.resource-chart-data.md +8 -4
  509. package/dist/knowledge/references/saas.frontend.chat-sign-in-completion.md +99 -0
  510. package/dist/knowledge/references/saas.frontend.collection-filter-presets.md +92 -23
  511. package/dist/knowledge/references/saas.frontend.command-menu.search-resource.md +3 -3
  512. package/dist/knowledge/references/saas.frontend.display-layout.reading-measure.md +9 -3
  513. package/dist/knowledge/references/saas.frontend.domain-module.md +5 -0
  514. package/dist/knowledge/references/saas.frontend.embedded-resource-descent.md +2 -1
  515. package/dist/knowledge/references/saas.frontend.errors.backend-refusal.md +96 -0
  516. package/dist/knowledge/references/saas.frontend.execution-view.definition.md +57 -3
  517. package/dist/knowledge/references/saas.frontend.field-tiles.md +76 -0
  518. package/dist/knowledge/references/saas.frontend.flows-actors-view.md +10 -2
  519. package/dist/knowledge/references/saas.frontend.focus-indicator.md +119 -0
  520. package/dist/knowledge/references/saas.frontend.launcher.item-refs.md +14 -2
  521. package/dist/knowledge/references/saas.frontend.launcher.merge-rules.md +7 -4
  522. package/dist/knowledge/references/saas.frontend.launcher.runtime-availability.md +17 -16
  523. package/dist/knowledge/references/saas.frontend.linked-conversations-embed.md +3 -5
  524. package/dist/knowledge/references/saas.frontend.operation-key-and-resource-config-like.md +68 -1
  525. package/dist/knowledge/references/saas.frontend.providers.execute-operation.md +14 -24
  526. package/dist/knowledge/references/saas.frontend.record-page-parts.md +117 -0
  527. package/dist/knowledge/references/saas.frontend.related-resource-embeds.md +184 -5
  528. package/dist/knowledge/references/saas.frontend.related-resource-sections.md +6 -0
  529. package/dist/knowledge/references/saas.frontend.resource-header-title.md +98 -34
  530. package/dist/knowledge/references/saas.frontend.resource-label-params.md +3 -1
  531. package/dist/knowledge/references/saas.frontend.resource-layout-templates.md +59 -19
  532. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +344 -62
  533. package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +13 -8
  534. package/dist/knowledge/references/saas.frontend.section-stages.md +63 -0
  535. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +183 -32
  536. package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +72 -13
  537. package/dist/knowledge/references/saas.frontend.viewer-may-perform-operation.md +52 -0
  538. package/dist/knowledge/references/saas.models.agent-suspension.md +75 -0
  539. package/dist/knowledge/references/saas.models.agent-work-capture-settings.md +2 -2
  540. package/dist/knowledge/references/saas.models.agent-work-decision-contents-read.md +69 -0
  541. package/dist/knowledge/references/saas.models.agent-work-decision-surface.md +11 -2
  542. package/dist/knowledge/references/saas.models.agent-work-decision-vocabulary.md +20 -3
  543. package/dist/knowledge/references/saas.models.agent-work-output-review.md +3 -3
  544. package/dist/knowledge/references/saas.models.agent-work-override-rate.md +6 -5
  545. package/dist/knowledge/references/saas.models.agent-work-review-config.md +22 -4
  546. package/dist/knowledge/references/saas.models.analytics.value-moments.md +22 -0
  547. package/dist/knowledge/references/saas.models.application-agent-policy.md +28 -0
  548. package/dist/knowledge/references/saas.models.application-entry-points.md +45 -0
  549. package/dist/knowledge/references/saas.models.audit-trails.actor-attribution.md +21 -0
  550. package/dist/knowledge/references/saas.models.audit.trail-config.md +18 -5
  551. package/dist/knowledge/references/saas.models.auth.relationship-grantor-authentication.md +175 -0
  552. package/dist/knowledge/references/saas.models.authorization.administrative-continuity-codes.md +4 -4
  553. package/dist/knowledge/references/saas.models.chat-identity-link-host.md +38 -0
  554. package/dist/knowledge/references/saas.models.compliance.ai-use-classification.md +179 -0
  555. package/dist/knowledge/references/saas.models.compliance.ai-use-posture.md +121 -0
  556. package/dist/knowledge/references/saas.models.config.declared-type-renames.md +246 -0
  557. package/dist/knowledge/references/saas.models.config.organization-types.md +54 -74
  558. package/dist/knowledge/references/saas.models.conversation-threads.md +43 -6
  559. package/dist/knowledge/references/saas.models.crypto-keys.floors.md +32 -0
  560. package/dist/knowledge/references/saas.models.crypto-keys.key-management-config.md +130 -0
  561. package/dist/knowledge/references/saas.models.crypto-keys.local-provider.md +29 -0
  562. package/dist/knowledge/references/saas.models.crypto-keys.purpose-descriptor.md +442 -0
  563. package/dist/knowledge/references/saas.models.crypto-keys.purposes.md +91 -0
  564. package/dist/knowledge/references/saas.models.data-mode-read-list.md +24 -79
  565. package/dist/knowledge/references/saas.models.engine-capabilities.md +39 -2
  566. package/dist/knowledge/references/saas.models.engine-capabilities.required-provider-floor.md +3 -0
  567. package/dist/knowledge/references/saas.models.evaluation-dataset-export.md +16 -9
  568. package/dist/knowledge/references/saas.models.evaluation-export-authorization.md +23 -6
  569. package/dist/knowledge/references/saas.models.external-data-conflict-vocabulary.md +53 -0
  570. package/dist/knowledge/references/saas.models.external-data-pipeline.md +96 -26
  571. package/dist/knowledge/references/saas.models.flows-actors.agent-behavior-report-config.md +28 -0
  572. package/dist/knowledge/references/saas.models.flows-actors.agent-behavior-report.md +321 -0
  573. package/dist/knowledge/references/saas.models.flows-actors.agent-configuration.md +29 -0
  574. package/dist/knowledge/references/saas.models.flows-actors.agent-content-guardrails.md +150 -0
  575. package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +45 -0
  576. package/dist/knowledge/references/saas.models.flows-actors.agent-operation-record.md +154 -0
  577. package/dist/knowledge/references/saas.models.flows-actors.autonomous-agents-vocabulary.md +49 -7
  578. package/dist/knowledge/references/saas.models.flows-actors.chat-agents-vocabulary.md +26 -0
  579. package/dist/knowledge/references/saas.models.flows-actors.decision-card-wording.md +284 -0
  580. package/dist/knowledge/references/saas.models.flows-actors.decision-notice-recorded-cards.md +93 -0
  581. package/dist/knowledge/references/saas.models.flows-actors.human-decision-decider.md +70 -0
  582. package/dist/knowledge/references/saas.models.flows-actors.human-input-form.md +349 -0
  583. package/dist/knowledge/references/saas.models.flows-actors.operation-approval-pending.md +55 -0
  584. package/dist/knowledge/references/saas.models.flows-actors.operation-approval-requirement.md +93 -0
  585. package/dist/knowledge/references/saas.models.flows-actors.review-deadline-vocabulary.md +6 -0
  586. package/dist/knowledge/references/saas.models.flows-actors.review-deadlines-declaration.md +4 -3
  587. package/dist/knowledge/references/saas.models.flows.run-state.md +49 -0
  588. package/dist/knowledge/references/saas.models.flows.runnable-model.md +274 -0
  589. package/dist/knowledge/references/saas.models.frontend-on-demand-capability-contract.md +54 -0
  590. package/dist/knowledge/references/saas.models.guidance-flow.md +1 -1
  591. package/dist/knowledge/references/saas.models.http-api-binding.md +176 -50
  592. package/dist/knowledge/references/saas.models.http-api-binding.rest-write-operations.md +3 -3
  593. package/dist/knowledge/references/saas.models.http-api-population-filter.md +51 -0
  594. package/dist/knowledge/references/saas.models.human-decision-review-marker.md +1 -1
  595. package/dist/knowledge/references/saas.models.inbound-channels.md +75 -3
  596. package/dist/knowledge/references/saas.models.inbound-email-domains.md +5 -5
  597. package/dist/knowledge/references/saas.models.inbound-email.md +2 -2
  598. package/dist/knowledge/references/saas.models.m2m-webhook-events.md +73 -0
  599. package/dist/knowledge/references/saas.models.model-cost-accounting-config.md +1 -1
  600. package/dist/knowledge/references/saas.models.model-cost-summary.md +56 -20
  601. package/dist/knowledge/references/saas.models.notifications.targets.md +28 -3
  602. package/dist/knowledge/references/saas.models.notifications.user-notification-definition.md +259 -21
  603. package/dist/knowledge/references/saas.models.on-demand-provider-capabilities.md +28 -0
  604. package/dist/knowledge/references/saas.models.organization-agent-policy.md +43 -0
  605. package/dist/knowledge/references/saas.models.organization-assigned-rows-declaration.md +74 -0
  606. package/dist/knowledge/references/saas.models.organization-own-rows-declaration.md +51 -0
  607. package/dist/knowledge/references/saas.models.organization-unit-narrowing-containment.md +6 -6
  608. package/dist/knowledge/references/saas.models.organizations.application-owner-codes.md +9 -10
  609. package/dist/knowledge/references/saas.models.organizations.identity-declaration.md +201 -0
  610. package/dist/knowledge/references/saas.models.organizations.organization-relationships.md +933 -0
  611. package/dist/knowledge/references/saas.models.organizations.professional-qualification-kinds.md +46 -0
  612. package/dist/knowledge/references/saas.models.organizations.professional-qualifications.md +168 -0
  613. package/dist/knowledge/references/{saas.models.organizations.service-provider-capability-grants.md → saas.models.organizations.relationship-capability-grants.md} +56 -35
  614. package/dist/knowledge/references/saas.models.organizations.relationship-grantor-controls.md +62 -0
  615. package/dist/knowledge/references/saas.models.organizations.relationship-invitations.md +228 -0
  616. package/dist/knowledge/references/saas.models.organizations.relationship-kinds.md +291 -0
  617. package/dist/knowledge/references/saas.models.organizations.relationship-record-separation.md +114 -0
  618. package/dist/knowledge/references/saas.models.privacy.data-residency.md +676 -0
  619. package/dist/knowledge/references/saas.models.privacy.legal-holds.md +114 -7
  620. package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +73 -2
  621. package/dist/knowledge/references/saas.models.privacy.redaction-treatments.md +13 -14
  622. package/dist/knowledge/references/saas.models.privacy.retention-binding.md +84 -1
  623. package/dist/knowledge/references/saas.models.privacy.retention-enforcement-record.md +10 -0
  624. package/dist/knowledge/references/saas.models.privacy.retention-schedule.md +5 -3
  625. package/dist/knowledge/references/saas.models.privacy.subject-data-recipients.md +280 -40
  626. package/dist/knowledge/references/saas.models.privacy.subject-export.md +134 -0
  627. package/dist/knowledge/references/saas.models.provider-capabilities.md +38 -0
  628. package/dist/knowledge/references/saas.models.provider-usage-pricing-authority.md +50 -1
  629. package/dist/knowledge/references/saas.models.providers.capability-activation-policy.md +28 -0
  630. package/dist/knowledge/references/saas.models.providers.capability-resolution-mode.md +20 -6
  631. package/dist/knowledge/references/saas.models.providers.compliance-choice.md +52 -0
  632. package/dist/knowledge/references/saas.models.providers.execute-operation-request.md +25 -0
  633. package/dist/knowledge/references/saas.models.providers.processing-region-reach.md +132 -0
  634. package/dist/knowledge/references/saas.models.providers.processing-region-selection.md +139 -0
  635. package/dist/knowledge/references/saas.models.providers.scope-reauthorization.md +1 -1
  636. package/dist/knowledge/references/saas.models.queue.scheduled-recovery.md +13 -1
  637. package/dist/knowledge/references/saas.models.rate-limit-configuration.md +4 -4
  638. package/dist/knowledge/references/saas.models.representative-activity.md +69 -0
  639. package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +165 -44
  640. package/dist/knowledge/references/saas.models.resource-config.metered-usage-recording.md +24 -0
  641. package/dist/knowledge/references/saas.models.resource-config.operation-api-call.md +92 -11
  642. package/dist/knowledge/references/saas.models.resource-config.operation-auditable-event.md +4 -2
  643. package/dist/knowledge/references/saas.models.resource-config.operation-base.md +20 -3
  644. package/dist/knowledge/references/saas.models.resource-config.operation-bulk.md +37 -0
  645. package/dist/knowledge/references/saas.models.resource-config.operation-chat-command.md +39 -0
  646. package/dist/knowledge/references/saas.models.resource-config.operation-condition-parameters.md +56 -0
  647. package/dist/knowledge/references/saas.models.resource-config.operation-idempotency-key.md +16 -6
  648. package/dist/knowledge/references/saas.models.resource-config.operation-mcp-exposure.md +1 -1
  649. package/dist/knowledge/references/saas.models.resource-config.operation-required-qualifications.md +30 -0
  650. package/dist/knowledge/references/saas.models.resource-config.operation-scope-admissions.md +137 -2
  651. package/dist/knowledge/references/saas.models.resource-config.operation-submission-challenge.md +1 -1
  652. package/dist/knowledge/references/saas.models.resource-config.operation-union.md +0 -1
  653. package/dist/knowledge/references/saas.models.resource-config.operation-variant-client-timeout.md +1 -1
  654. package/dist/knowledge/references/saas.models.resource-config.record-label-fields.md +23 -0
  655. package/dist/knowledge/references/saas.models.resource-config.request-field-offers.md +104 -0
  656. package/dist/knowledge/references/saas.models.resource-config.required-features.md +20 -0
  657. package/dist/knowledge/references/saas.models.resource-config.resource-configuration.md +23 -16
  658. package/dist/knowledge/references/saas.models.resource-config.resources-registry.md +25 -3
  659. package/dist/knowledge/references/saas.models.resource-config.retention-policy.md +46 -0
  660. package/dist/knowledge/references/saas.models.resource-config.system-access-policy.md +32 -15
  661. package/dist/knowledge/references/saas.models.resource-config.system-managed-fields.md +2 -1
  662. package/dist/knowledge/references/saas.models.resource-config.token-generation.md +1 -1
  663. package/dist/knowledge/references/saas.models.resource-operation-display-risk.md +5 -4
  664. package/dist/knowledge/references/saas.models.resource-operation-variant-runtime.md +3 -2
  665. package/dist/knowledge/references/saas.models.resource-relationship-builder-parameters.md +6 -2
  666. package/dist/knowledge/references/saas.models.roadmap.phase-horizon.md +31 -0
  667. package/dist/knowledge/references/saas.models.roles.definition.md +12 -1
  668. package/dist/knowledge/references/saas.models.roles.organization-defaults.md +12 -6
  669. package/dist/knowledge/references/saas.models.schema-family-builder.md +32 -4
  670. package/dist/knowledge/references/saas.models.scope-membership.md +2 -2
  671. package/dist/knowledge/references/saas.models.system-of-record-actions.md +65 -1
  672. package/dist/knowledge/references/saas.models.system-of-record-capabilities.md +123 -0
  673. package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +19 -2
  674. package/dist/knowledge/references/saas.models.systems-of-record.md +110 -14
  675. package/dist/knowledge/references/saas.models.work-attribution-vocabulary.md +7 -3
  676. package/dist/knowledge/references/saas.models.work-unit-ref.md +17 -2
  677. package/dist/knowledge/references/saas.public-runtime.contract.md +75 -25
  678. package/dist/knowledge/references/saas.rag.retrieval-refusals.md +3 -2
  679. package/dist/knowledge/references/saas.specifications.assurance-control-markers.md +3 -2
  680. package/dist/knowledge/references/saas.specifications.assurance-document-blueprint.contract.md +13 -0
  681. package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +287 -17
  682. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.catalog-spec-shared.md +5 -4
  683. package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +30 -2
  684. package/dist/knowledge/references/saas.specifications.engine-resource-sub-domain.md +105 -0
  685. package/dist/knowledge/references/saas.specifications.governed-document-release.contract.md +22 -4
  686. package/dist/knowledge/references/saas.specifications.processor-register.md +10 -1
  687. package/dist/knowledge/references/saas.specifications.recipient-disclosures.md +111 -2
  688. package/dist/knowledge/references/saas.specifications.recipient-population.md +46 -0
  689. package/dist/knowledge/references/saas.specifications.resource-frontend-configuration-aspect.md +7 -0
  690. package/dist/knowledge/references/saas.specifications.resource-operation-spec.md +44 -5
  691. package/dist/knowledge/references/saas.specifications.resource-spec-config.md +21 -7
  692. package/dist/knowledge/references/saas.specifications.resource-spec-factory.md +113 -70
  693. package/dist/knowledge/references/saas.specifications.subject-data-recipients.md +136 -6
  694. package/dist/knowledge/references/saas.specifications.translation-glossary.md +80 -0
  695. package/dist/knowledge/references/saas.website.astro.bridge.md +51 -14
  696. package/dist/knowledge/references/saas.website.astro.head-renderer.md +63 -27
  697. package/dist/knowledge/references/saas.website.astro.i18n-helper.md +39 -10
  698. package/dist/knowledge/references/saas.website.astro.label-key-collector.md +12 -11
  699. package/dist/knowledge/references/saas.website.astro.label-loader.md +77 -14
  700. package/dist/knowledge/references/saas.website.astro.pick-labels-for-page.md +1 -2
  701. package/dist/knowledge/references/saas.website.astro.runtime-helper.md +49 -17
  702. package/dist/knowledge/references/saas.website.astro.site-context.md +17 -8
  703. package/dist/knowledge/references/saas.website.astro.structured-data-renderer.md +29 -8
  704. package/dist/knowledge/references/saas.website.blocks.actions.md +91 -0
  705. package/dist/knowledge/references/saas.website.blocks.band.md +41 -0
  706. package/dist/knowledge/references/saas.website.blocks.bento.md +70 -0
  707. package/dist/knowledge/references/saas.website.blocks.card-grid.md +115 -0
  708. package/dist/knowledge/references/saas.website.blocks.card.md +77 -0
  709. package/dist/knowledge/references/saas.website.blocks.cta-band.md +94 -0
  710. package/dist/knowledge/references/saas.website.blocks.define-block.md +123 -0
  711. package/dist/knowledge/references/saas.website.blocks.definitions.md +132 -0
  712. package/dist/knowledge/references/saas.website.blocks.faq.md +89 -0
  713. package/dist/knowledge/references/saas.website.blocks.feature-row.md +109 -0
  714. package/dist/knowledge/references/saas.website.blocks.hero.md +140 -0
  715. package/dist/knowledge/references/saas.website.blocks.intro.md +68 -0
  716. package/dist/knowledge/references/saas.website.blocks.latest-posts.md +104 -0
  717. package/dist/knowledge/references/saas.website.blocks.marquee.md +76 -0
  718. package/dist/knowledge/references/saas.website.blocks.pricing.md +395 -0
  719. package/dist/knowledge/references/saas.website.blocks.product-tour.md +158 -0
  720. package/dist/knowledge/references/saas.website.blocks.quote-cards.md +64 -0
  721. package/dist/knowledge/references/saas.website.blocks.roadmap.md +108 -0
  722. package/dist/knowledge/references/saas.website.blocks.section-slots.md +64 -0
  723. package/dist/knowledge/references/saas.website.blocks.solution-paths.md +71 -0
  724. package/dist/knowledge/references/saas.website.blocks.stats.md +183 -0
  725. package/dist/knowledge/references/saas.website.blocks.steps.md +69 -0
  726. package/dist/knowledge/references/saas.website.blocks.stylesheet.md +68 -0
  727. package/dist/knowledge/references/saas.website.blocks.tables.md +153 -0
  728. package/dist/knowledge/references/saas.website.blocks.vocabulary.md +227 -0
  729. package/dist/knowledge/references/saas.website.blog.bridge.md +98 -53
  730. package/dist/knowledge/references/saas.website.blog.collection-config.md +105 -49
  731. package/dist/knowledge/references/saas.website.blog.cover-resolver.md +93 -0
  732. package/dist/knowledge/references/saas.website.blog.frontmatter.md +106 -9
  733. package/dist/knowledge/references/saas.website.blog.head-renderer.md +37 -19
  734. package/dist/knowledge/references/saas.website.blog.index-builder.md +63 -0
  735. package/dist/knowledge/references/saas.website.blog.index.md +43 -0
  736. package/dist/knowledge/references/saas.website.blog.post-cover.md +38 -0
  737. package/dist/knowledge/references/saas.website.blog.post-renderer.md +115 -87
  738. package/dist/knowledge/references/saas.website.blog.react-mdx-integration.md +188 -0
  739. package/dist/knowledge/references/saas.website.blog.react-mdx-query.md +26 -0
  740. package/dist/knowledge/references/saas.website.blog.vocabulary-labels.md +113 -0
  741. package/dist/knowledge/references/saas.website.config.pricing-catalog-loader.md +5 -2
  742. package/dist/knowledge/references/saas.website.config.site-context-loader.md +26 -3
  743. package/dist/knowledge/references/saas.website.consent.banner.md +1 -1
  744. package/dist/knowledge/references/saas.website.consent.context.md +1 -1
  745. package/dist/knowledge/references/saas.website.design-tokens.bundle.md +28 -6
  746. package/dist/knowledge/references/saas.website.design-tokens.colors.md +7 -6
  747. package/dist/knowledge/references/saas.website.design-tokens.compose-function.md +35 -0
  748. package/dist/knowledge/references/saas.website.design-tokens.compose.md +76 -0
  749. package/dist/knowledge/references/saas.website.design-tokens.personality-derivation.md +22 -0
  750. package/dist/knowledge/references/saas.website.design-tokens.personality-lexicon.md +31 -0
  751. package/dist/knowledge/references/saas.website.design-tokens.personality.md +82 -0
  752. package/dist/knowledge/references/saas.website.design-tokens.product.md +122 -0
  753. package/dist/knowledge/references/saas.website.design-tokens.radius.md +12 -1
  754. package/dist/knowledge/references/saas.website.design-tokens.readers.md +58 -0
  755. package/dist/knowledge/references/saas.website.design-tokens.spacing.md +61 -0
  756. package/dist/knowledge/references/saas.website.design-tokens.surface-depth.md +60 -0
  757. package/dist/knowledge/references/saas.website.design-tokens.tones.md +75 -0
  758. package/dist/knowledge/references/saas.website.design-tokens.typography.md +115 -0
  759. package/dist/knowledge/references/saas.website.factories.define-page-manifest.md +23 -21
  760. package/dist/knowledge/references/saas.website.factories.define-section.md +36 -38
  761. package/dist/knowledge/references/saas.website.format.publication-date.md +26 -0
  762. package/dist/knowledge/references/saas.website.label-keys.compose-helper.md +1 -1
  763. package/dist/knowledge/references/saas.website.label-keys.format.md +4 -3
  764. package/dist/knowledge/references/saas.website.label-pack.validator.md +9 -8
  765. package/dist/knowledge/references/saas.website.labels.section-labels.md +34 -0
  766. package/dist/knowledge/references/saas.website.legal.public-document-links.md +19 -4
  767. package/dist/knowledge/references/saas.website.locale-switcher.label-keys.md +35 -0
  768. package/dist/knowledge/references/saas.website.menu.icons.md +123 -0
  769. package/dist/knowledge/references/saas.website.menu.label-keys.md +112 -0
  770. package/dist/knowledge/references/saas.website.menu.schema.md +92 -0
  771. package/dist/knowledge/references/saas.website.menu.vocabulary.md +79 -0
  772. package/dist/knowledge/references/saas.website.motion.demo-player.md +105 -0
  773. package/dist/knowledge/references/saas.website.motion.demo-scenario.md +460 -0
  774. package/dist/knowledge/references/saas.website.motion.demo.md +324 -0
  775. package/dist/knowledge/references/saas.website.motion.element-attributes.md +115 -0
  776. package/dist/knowledge/references/saas.website.motion.reveal-renditions.md +67 -0
  777. package/dist/knowledge/references/saas.website.motion.stylesheet.md +82 -0
  778. package/dist/knowledge/references/saas.website.motion.tempo-table.md +99 -0
  779. package/dist/knowledge/references/saas.website.motion.tokens.md +46 -0
  780. package/dist/knowledge/references/saas.website.motion.vocabulary.md +85 -0
  781. package/dist/knowledge/references/saas.website.page-layout.component.md +34 -8
  782. package/dist/knowledge/references/saas.website.page-manifest.meta-label-keys.md +4 -4
  783. package/dist/knowledge/references/saas.website.page-manifest.route-path.md +1 -1
  784. package/dist/knowledge/references/saas.website.page-manifest.schema.md +25 -29
  785. package/dist/knowledge/references/saas.website.page-manifest.seo.md +1 -1
  786. package/dist/knowledge/references/saas.website.page-navigation.md +44 -0
  787. package/dist/knowledge/references/saas.website.page.context.md +9 -2
  788. package/dist/knowledge/references/saas.website.primitives.button.md +6 -6
  789. package/dist/knowledge/references/saas.website.primitives.heading.md +17 -18
  790. package/dist/knowledge/references/saas.website.primitives.image.md +18 -15
  791. package/dist/knowledge/references/saas.website.primitives.internal-button.md +11 -12
  792. package/dist/knowledge/references/saas.website.primitives.internal-link.md +11 -35
  793. package/dist/knowledge/references/saas.website.primitives.link.md +22 -11
  794. package/dist/knowledge/references/saas.website.primitives.text.md +10 -8
  795. package/dist/knowledge/references/saas.website.product.atoms.md +366 -0
  796. package/dist/knowledge/references/saas.website.product.figures.md +320 -0
  797. package/dist/knowledge/references/saas.website.product.hooks.md +278 -0
  798. package/dist/knowledge/references/saas.website.product.panels.md +324 -0
  799. package/dist/knowledge/references/saas.website.product.stylesheet.md +1086 -0
  800. package/dist/knowledge/references/saas.website.refs.section.md +2 -2
  801. package/dist/knowledge/references/saas.website.root-config.schema.md +34 -17
  802. package/dist/knowledge/references/saas.website.routing.link-target.md +70 -0
  803. package/dist/knowledge/references/saas.website.routing.localized-path.md +15 -8
  804. package/dist/knowledge/references/saas.website.runtime.context.md +44 -17
  805. package/dist/knowledge/references/saas.website.section.component.md +21 -19
  806. package/dist/knowledge/references/saas.website.sections.category-enum.md +21 -2
  807. package/dist/knowledge/references/saas.website.sections.definition-schema.md +47 -39
  808. package/dist/knowledge/references/saas.website.site-footer.menu.md +47 -0
  809. package/dist/knowledge/references/saas.website.site-header.component.md +100 -0
  810. package/dist/knowledge/references/saas.website.site-header.scroll-behavior.md +26 -0
  811. package/dist/knowledge/references/saas.website.stacking.md +86 -0
  812. package/dist/knowledge/references/saas.website.structured-data.payload-shape.md +162 -0
  813. package/dist/knowledge/references/saas.website.use-blog-index.hook.md +27 -0
  814. package/dist/knowledge/references/saas.website.use-label.hook.md +6 -4
  815. package/dist/knowledge/references/service-method.config.md +303 -0
  816. package/dist/knowledge/references/vision.constraint.config.md +4 -2
  817. package/dist/knowledge/references/website-plan.config.md +544 -32
  818. package/dist/knowledge/references/website-plan.menu-placement.md +118 -0
  819. package/dist/knowledge/references/website-plan.page-kind-essentials.md +42 -0
  820. package/dist/knowledge/references/website-plan.page-routes.md +39 -0
  821. package/dist/knowledge/references/workers.node.worker-init-contract.md +4 -2
  822. package/dist/knowledge/references/zod.decorators.chainable-runtime.md +133 -9
  823. package/dist/knowledge/references/zod.decorators.chrome-modes.md +92 -0
  824. package/dist/knowledge/references/zod.decorators.data-categories.md +124 -34
  825. package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +99 -6
  826. package/dist/knowledge/references/zod.decorators.display-edit-modes.md +34 -1
  827. package/dist/knowledge/references/zod.decorators.enums.frontend-handling.md +41 -7
  828. package/dist/knowledge/references/zod.decorators.file-schema.md +10 -8
  829. package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +25 -9
  830. package/dist/knowledge/references/zod.decorators.primitive-ui.md +15 -3
  831. package/dist/knowledge/references/zod.decorators.rag-source.md +20 -20
  832. package/dist/knowledge/references/zod.decorators.schema-metadata.md +6 -0
  833. package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +52 -18
  834. package/dist/knowledge/references/zod.decorators.shared-structural-params.md +107 -5
  835. package/dist/knowledge/references/zod.decorators.structural-lifecycle-params.md +193 -9
  836. package/dist/knowledge/references/zod.factories.bigdecimal.md +17 -8
  837. package/dist/knowledge/references/zod.factories.code.md +18 -9
  838. package/dist/knowledge/references/zod.factories.duration.md +23 -14
  839. package/dist/knowledge/references/zod.factories.money.md +24 -15
  840. package/dist/knowledge/references/zod.factories.phone.md +23 -14
  841. package/dist/knowledge/references/zod.factories.range.md +5 -1
  842. package/dist/knowledge/references/zod.factories.year-month.md +79 -0
  843. package/dist/knowledge/registries/assurance-authority-bases.json +3 -3
  844. package/dist/knowledge/registries/framework-topics.json +5250 -2565
  845. package/dist/knowledge/registries/playbooks.json +88 -55
  846. package/dist/knowledge/registries/source-tags.json +9347 -4807
  847. package/dist/knowledge/rules/database-migration-obligation.md +10 -5
  848. package/dist/knowledge/rules/live-context-door.md +1 -1
  849. package/dist/knowledge/skills/INDEX.md +62 -33
  850. package/dist/knowledge/skills/agent-work-review/SKILL.md +86 -23
  851. package/dist/knowledge/skills/agent-work-review/references/framework-actor-execution-continuation-api.md +227 -0
  852. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-capture-settings-api.md +2 -2
  853. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-decision-contents-api.md +79 -0
  854. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-output-review-api.md +4 -4
  855. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-override-rate-api.md +6 -5
  856. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-review-config-api.md +22 -4
  857. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-review-marker-api.md +16 -4
  858. package/dist/knowledge/skills/agent-work-review/references/framework-agent-work-vocabulary-api.md +20 -3
  859. package/dist/knowledge/skills/agent-work-review/references/framework-evaluation-dataset-export-api.md +16 -9
  860. package/dist/knowledge/skills/agent-work-review/references/framework-evaluation-export-authorization-api.md +24 -7
  861. package/dist/knowledge/skills/agent-work-review/references/framework-human-input-form-api.md +376 -0
  862. package/dist/knowledge/skills/ai-use-declaration/SKILL.md +192 -0
  863. package/dist/knowledge/skills/ai-use-declaration/references/choosing-the-domain-and-class.md +73 -0
  864. package/dist/knowledge/skills/ai-use-declaration/references/framework-ai-use-classification-api.md +194 -0
  865. package/dist/knowledge/skills/ai-use-declaration/references/framework-ai-use-posture-api.md +136 -0
  866. package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +30 -19
  867. package/dist/knowledge/skills/application-consumer-documentation-authoring/references/framework-documentation-chapters-api.md +48 -13
  868. package/dist/knowledge/skills/application-consumer-documentation-authoring/references/source-and-ownership-routing.md +2 -2
  869. package/dist/knowledge/skills/application-database-migrations/SKILL.md +26 -9
  870. package/dist/knowledge/skills/application-database-migrations/references/postgresql-supported-surfaces.md +64 -0
  871. package/dist/knowledge/skills/application-database-migrations/references/postgresql-vs-mongodb-obligations.md +37 -1
  872. package/dist/knowledge/skills/application-roles-authoring/SKILL.md +28 -3
  873. package/dist/knowledge/skills/application-roles-authoring/references/framework-application-roles-api.md +24 -7
  874. package/dist/knowledge/skills/application-roles-authoring/references/office-and-field-worked-example.md +22 -1
  875. package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +168 -3
  876. package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-assigned-rows-declaration-api.md +92 -0
  877. package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-organization-identity-declaration-api.md +247 -0
  878. package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-own-rows-declaration-api.md +66 -0
  879. package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-unit-narrowing-declaration-api.md +6 -6
  880. package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +6 -0
  881. package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +108 -2
  882. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +81 -10
  883. package/dist/knowledge/skills/backend-custom-operation/references/after-the-operation.md +4 -1
  884. package/dist/knowledge/skills/backend-custom-operation/references/declared-refusal-codes.md +95 -0
  885. package/dist/knowledge/skills/backend-custom-operation/references/framework-assurance-control-markers.md +3 -2
  886. package/dist/knowledge/skills/backend-custom-operation/references/framework-audit-log-event-api.md +5 -2
  887. package/dist/knowledge/skills/backend-custom-operation/references/framework-core-write-precondition-api.md +73 -0
  888. package/dist/knowledge/skills/backend-custom-operation/references/framework-error-handling-api.md +5 -0
  889. package/dist/knowledge/skills/backend-custom-operation/references/framework-external-effect-reservation-api.md +276 -0
  890. package/dist/knowledge/skills/backend-custom-operation/references/framework-hook-transaction-posture-api.md +79 -0
  891. package/dist/knowledge/skills/backend-custom-operation/references/framework-operation-base-and-path-api.md +20 -3
  892. package/dist/knowledge/skills/backend-custom-operation/references/framework-target-authority-api.md +61 -0
  893. package/dist/knowledge/skills/backend-custom-operation/references/framework-transactional-core-api.md +368 -1
  894. package/dist/knowledge/skills/blueprint-authoring/SKILL.md +191 -0
  895. package/dist/knowledge/skills/blueprint-authoring/references/blueprint-content-kinds.md +29 -0
  896. package/dist/knowledge/skills/blueprint-authoring/references/framework-blueprint-definition-api.md +490 -0
  897. package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +127 -2
  898. package/dist/knowledge/skills/brand-logo-authoring/references/brand-authoring-decisions.md +15 -3
  899. package/dist/knowledge/skills/brand-logo-authoring/references/framework-brand-snapshot-api.md +26 -8
  900. package/dist/knowledge/skills/brand-logo-authoring/references/framework-style-word-lexicon-api.md +126 -0
  901. package/dist/knowledge/skills/brand-name-screening/SKILL.md +13 -2
  902. package/dist/knowledge/skills/brand-name-screening/references/framework-brand-name-screening-api.md +30 -3
  903. package/dist/knowledge/skills/chat-agent-conversations/SKILL.md +166 -0
  904. package/dist/knowledge/skills/chat-agent-conversations/references/framework-chat-conversations-api.md +307 -0
  905. package/dist/knowledge/skills/compliance-document-authoring/SKILL.md +2 -1
  906. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-governance.md +8 -6
  907. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +179 -37
  908. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-service-terms.md +4 -3
  909. package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +13 -0
  910. package/dist/knowledge/skills/compliance-document-authoring/references/framework-governed-document-after-drafting.md +48 -11
  911. package/dist/knowledge/skills/compliance-document-authoring/references/framework-processor-register-authoring.md +10 -1
  912. package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +896 -0
  913. package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +184 -4
  914. package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-population.md +46 -0
  915. package/dist/knowledge/skills/compliance-document-authoring/references/framework-subject-data-recipients.md +487 -61
  916. package/dist/knowledge/skills/config-app-shell/SKILL.md +62 -29
  917. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +20 -18
  918. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-building-blocks-api.md +7 -3
  919. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-hosted-components-api.md +13 -0
  920. package/dist/knowledge/skills/config-app-shell/references/framework-brand-identity-api.md +20 -0
  921. package/dist/knowledge/skills/config-app-shell/references/framework-command-menu-omnibox-api.md +3 -3
  922. package/dist/knowledge/skills/config-app-shell/references/framework-launcher-items-api.md +21 -6
  923. package/dist/knowledge/skills/config-app-shell/references/framework-launcher-visibility-api.md +24 -22
  924. package/dist/knowledge/skills/config-app-shell/references/framework-shell-layout-api.md +528 -0
  925. package/dist/knowledge/skills/config-design-system/SKILL.md +245 -162
  926. package/dist/knowledge/skills/config-design-system/references/design-system-file.md +5 -1
  927. package/dist/knowledge/skills/config-design-system/references/framework-focus-indicator-api.md +182 -0
  928. package/dist/knowledge/skills/config-design-system/references/framework-palette-contrast-api.md +195 -0
  929. package/dist/knowledge/skills/config-design-system/references/framework-palette-derivation-api.md +108 -0
  930. package/dist/knowledge/skills/config-design-system/references/framework-surface-policy-api.md +38 -0
  931. package/dist/knowledge/skills/config-design-system/references/framework-theme-composition-api.md +278 -0
  932. package/dist/knowledge/skills/config-design-system/references/theme-design-principles.md +202 -0
  933. package/dist/knowledge/skills/config-navigation/SKILL.md +2 -0
  934. package/dist/knowledge/skills/config-navigation/references/framework-content-width-api.md +16 -5
  935. package/dist/knowledge/skills/config-navigation/references/how-navigation-resolves.md +1 -1
  936. package/dist/knowledge/skills/config-navigation/references/navigation-configuration-map.md +12 -1
  937. package/dist/knowledge/skills/config-navigation/references/one-entry-per-concept.md +101 -0
  938. package/dist/knowledge/skills/config-saas/SKILL.md +4 -2
  939. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +51 -6
  940. package/dist/knowledge/skills/config-saas/references/framework-audit-trail-config-api.md +18 -5
  941. package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +333 -0
  942. package/dist/knowledge/skills/config-saas/references/framework-background-work-api.md +29 -1
  943. package/dist/knowledge/skills/config-saas/references/framework-capability-resolution-api.md +83 -11
  944. package/dist/knowledge/skills/config-saas/references/framework-connection-target-credentials.md +21 -19
  945. package/dist/knowledge/skills/config-saas/references/framework-content-security-policy-api.md +26 -10
  946. package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +1370 -0
  947. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +77 -2
  948. package/dist/knowledge/skills/config-saas/references/framework-systems-of-record-api.md +171 -26
  949. package/dist/knowledge/skills/config-saas/references/framework-value-moments-api.md +22 -0
  950. package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +126 -32
  951. package/dist/knowledge/skills/config-saas/references/saas-config-scope.md +1 -1
  952. package/dist/knowledge/skills/config-saas-backend/SKILL.md +16 -4
  953. package/dist/knowledge/skills/config-saas-backend/references/framework-application-owner-organization-codes-api.md +9 -10
  954. package/dist/knowledge/skills/config-saas-backend/references/framework-backend-authored-config-api.md +5 -1
  955. package/dist/knowledge/skills/config-saas-backend/references/framework-declared-type-renames-api.md +261 -0
  956. package/dist/knowledge/skills/config-saas-backend/references/framework-federated-identity-provider-private-networks-api.md +6 -4
  957. package/dist/knowledge/skills/config-saas-backend/references/framework-organization-types-api.md +167 -84
  958. package/dist/knowledge/skills/config-saas-backend/references/renaming-organization-and-user-types.md +69 -0
  959. package/dist/knowledge/skills/configure-billing/SKILL.md +20 -0
  960. package/dist/knowledge/skills/configure-billing/references/example-backend-provider-module-shape.md +38 -4
  961. package/dist/knowledge/skills/configure-billing/references/framework-backend-provider-reachability-api.md +2 -0
  962. package/dist/knowledge/skills/configure-billing/references/framework-metered-usage-recording-api.md +109 -0
  963. package/dist/knowledge/skills/configure-billing/references/framework-subscription-behavior-policy.md +4 -1
  964. package/dist/knowledge/skills/configure-coding-agent/references/framework-acp-execution-profile-api.md +18 -2
  965. package/dist/knowledge/skills/electronic-signature-deliverables/SKILL.md +131 -0
  966. package/dist/knowledge/skills/electronic-signature-deliverables/references/what-makes-a-request-signed.md +61 -0
  967. package/dist/knowledge/skills/email-add-template/SKILL.md +47 -6
  968. package/dist/knowledge/skills/email-add-template/references/framework-email-attachments-and-limits.md +11 -8
  969. package/dist/knowledge/skills/email-add-template/references/framework-email-send-api.md +10 -2
  970. package/dist/knowledge/skills/email-add-template/references/framework-email-template-api.md +134 -0
  971. package/dist/knowledge/skills/engine-product-definitions/references/framework-metered-usage-recording-api.md +28 -0
  972. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +102 -23
  973. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-a2a-token-budget-api.md +103 -14
  974. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +35 -4
  975. package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +98 -9
  976. package/dist/knowledge/skills/flows-actors-autonomous-agents/references/binding-and-review.md +71 -16
  977. package/dist/knowledge/skills/flows-actors-autonomous-agents/references/framework-autonomous-agent-api.md +160 -23
  978. package/dist/knowledge/skills/flows-actors-autonomous-agents/references/framework-inbound-agents-api.md +10 -3
  979. package/dist/knowledge/skills/flows-actors-autonomous-agents/references/tool-posture.md +14 -2
  980. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +298 -26
  981. package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +78 -19
  982. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-behavior-reports-api.md +455 -0
  983. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-content-guardrails-api.md +446 -0
  984. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-operation-record-api.md +208 -0
  985. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-suspension-api.md +174 -0
  986. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-ask-person-tool-api.md +121 -0
  987. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-audit-agent-attribution-api.md +21 -0
  988. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-decision-deadlines-api.md +10 -3
  989. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-realtime-catalog.md +69 -0
  990. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +695 -11
  991. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +124 -6
  992. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-model-spend-limits-api.md +276 -0
  993. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-present-records-tool-api.md +150 -0
  994. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-retrieval-tool-api.md +251 -0
  995. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-tool-dispatch-obligations-api.md +120 -16
  996. package/dist/knowledge/skills/flows-actors-declared-flow/SKILL.md +339 -0
  997. package/dist/knowledge/skills/flows-actors-declared-flow/references/framework-flow-model-api.md +283 -0
  998. package/dist/knowledge/skills/flows-actors-declared-flow/references/framework-start-flow-api.md +134 -0
  999. package/dist/knowledge/skills/flows-actors-declared-flow/references/step-kinds.md +16 -0
  1000. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +91 -5
  1001. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +78 -1
  1002. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-invocation-api.md +16 -3
  1003. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-operation-and-model-api.md +13 -6
  1004. package/dist/knowledge/skills/frontend-component-catalog/SKILL.md +5 -4
  1005. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +29 -19
  1006. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +166 -21
  1007. package/dist/knowledge/skills/guidance-onboarding-authoring/references/framework-guidance-flow-api.md +1 -1
  1008. package/dist/knowledge/skills/human-decision-notices/SKILL.md +150 -0
  1009. package/dist/knowledge/skills/human-decision-notices/references/framework-decision-card-wording-api.md +292 -0
  1010. package/dist/knowledge/skills/human-decision-notices/references/framework-decision-notice-handler-api.md +340 -0
  1011. package/dist/knowledge/skills/i18n-label-generation/SKILL.md +17 -1
  1012. package/dist/knowledge/skills/i18n-label-generation/references/framework-labelling-sections-api.md +39 -0
  1013. package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +1 -1
  1014. package/dist/knowledge/skills/i18n-rerun-pipeline/references/framework-labelling-sections-api.md +39 -0
  1015. package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +35 -3
  1016. package/dist/knowledge/skills/i18n-translation-rerun/references/framework-labelling-sections-api.md +39 -0
  1017. package/dist/knowledge/skills/i18n-translation-rerun/references/framework-translation-glossary-api.md +87 -0
  1018. package/dist/knowledge/skills/inbound-channels/SKILL.md +93 -13
  1019. package/dist/knowledge/skills/inbound-channels/references/email-channel.md +49 -4
  1020. package/dist/knowledge/skills/inbound-channels/references/framework-inbound-channel-api.md +245 -27
  1021. package/dist/knowledge/skills/inbound-channels/references/framework-inbound-email-api.md +8 -8
  1022. package/dist/knowledge/skills/inbound-channels/references/framework-inbound-handler-api.md +471 -6
  1023. package/dist/knowledge/skills/inbound-channels/references/framework-inbound-pipelines-api.md +73 -0
  1024. package/dist/knowledge/skills/inbound-channels/references/inbound-delivery-lifecycle.md +44 -5
  1025. package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +39 -16
  1026. package/dist/knowledge/skills/inbound-channels/references/sms-channel.md +93 -0
  1027. package/dist/knowledge/skills/infra-environment-config/SKILL.md +226 -73
  1028. package/dist/knowledge/skills/infra-environment-config/references/framework-backing-services-api.md +12 -14
  1029. package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +140 -7
  1030. package/dist/knowledge/skills/infra-environment-config/references/framework-infrastructure-host-api.md +2 -1
  1031. package/dist/knowledge/skills/infra-environment-config/references/framework-platform-key-management-api.md +370 -0
  1032. package/dist/knowledge/skills/layout-2d-adoption/SKILL.md +158 -0
  1033. package/dist/knowledge/skills/layout-2d-adoption/references/choosing-a-layout.md +43 -0
  1034. package/dist/knowledge/skills/layout-2d-adoption/references/framework-2d-layout-authoring-api.md +167 -0
  1035. package/dist/knowledge/skills/layout-2d-adoption/references/framework-2d-layout-registration-api.md +101 -0
  1036. package/dist/knowledge/skills/layout-2d-adoption/references/framework-2d-layout-settings-api.md +59 -0
  1037. package/dist/knowledge/skills/layout-2d-adoption/references/framework-shell-motion-api.md +415 -0
  1038. package/dist/knowledge/skills/layout-3d-adoption/SKILL.md +1 -0
  1039. package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-focal-plane-settings-api.md +16 -0
  1040. package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-frame-style-overrides-api.md +72 -0
  1041. package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-layout-contract-api.md +65 -32
  1042. package/dist/knowledge/skills/layout-3d-adoption/references/framework-3d-layout-registration-api.md +14 -36
  1043. package/dist/knowledge/skills/layout-3d-adoption/references/framework-shell-building-blocks-api.md +7 -3
  1044. package/dist/knowledge/skills/layout-3d-adoption/references/manual-adoption-and-removal.md +2 -2
  1045. package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +12 -9
  1046. package/dist/knowledge/skills/local-environment-bootstrap/references/derived-artifact-currency.md +7 -5
  1047. package/dist/knowledge/skills/local-environment-bootstrap/references/framework-upgrade-and-dependency-alignment.md +2 -2
  1048. package/dist/knowledge/skills/local-environment-bootstrap/references/local-environment-troubleshooting.md +18 -10
  1049. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +7 -7
  1050. package/dist/knowledge/skills/market-authoring-overview/references/framework-market-references-api.md +14 -1
  1051. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +33 -2
  1052. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +42 -2
  1053. package/dist/knowledge/skills/market-generation-cli/SKILL.md +49 -7
  1054. package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +63 -9
  1055. package/dist/knowledge/skills/minion-authoring/examples/contained-tick.example.md +1 -1
  1056. package/dist/knowledge/skills/minion-authoring/references/framework-minion-tick-contract.md +2 -2
  1057. package/dist/knowledge/skills/model-cost-attribution/SKILL.md +43 -11
  1058. package/dist/knowledge/skills/model-cost-attribution/references/framework-model-cost-pricing-api.md +58 -3
  1059. package/dist/knowledge/skills/model-cost-attribution/references/framework-model-cost-summary-api.md +57 -21
  1060. package/dist/knowledge/skills/model-cost-attribution/references/framework-work-attribution-api.md +7 -3
  1061. package/dist/knowledge/skills/model-cost-attribution/references/framework-work-unit-api.md +257 -46
  1062. package/dist/knowledge/skills/module-companion-exports/SKILL.md +1 -0
  1063. package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +30 -2
  1064. package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +110 -1
  1065. package/dist/knowledge/skills/module-relationships/SKILL.md +143 -119
  1066. package/dist/knowledge/skills/module-relationships/references/framework-resource-relationship-authoring-api.md +8 -4
  1067. package/dist/knowledge/skills/organization-relationships/SKILL.md +668 -0
  1068. package/dist/knowledge/skills/organization-relationships/references/framework-organization-relationships-api.md +1259 -0
  1069. package/dist/knowledge/skills/organization-relationships/references/framework-relationship-capability-grants-api.md +243 -0
  1070. package/dist/knowledge/skills/organization-relationships/references/framework-relationship-grantor-authentication-api.md +284 -0
  1071. package/dist/knowledge/skills/organization-relationships/references/framework-relationship-kinds-api.md +555 -0
  1072. package/dist/knowledge/skills/organization-relationships/references/framework-relationship-record-separation-api.md +163 -0
  1073. package/dist/knowledge/skills/organization-relationships/references/framework-representative-activity-api.md +149 -0
  1074. package/dist/knowledge/skills/pdf-template-authoring/references/framework-pdf-collection-template-api.md +5 -3
  1075. package/dist/knowledge/skills/professional-qualifications/SKILL.md +173 -0
  1076. package/dist/knowledge/skills/professional-qualifications/references/choosing-who-may-decide.md +53 -0
  1077. package/dist/knowledge/skills/professional-qualifications/references/framework-operation-approval-requirement-api.md +98 -0
  1078. package/dist/knowledge/skills/professional-qualifications/references/framework-operation-required-qualifications-api.md +39 -0
  1079. package/dist/knowledge/skills/professional-qualifications/references/framework-professional-qualifications-api.md +223 -0
  1080. package/dist/knowledge/skills/provider-address-lookup/SKILL.md +1 -1
  1081. package/dist/knowledge/skills/provider-address-lookup/references/framework-browser-operation-policy-api.md +3 -3
  1082. package/dist/knowledge/skills/provider-backend-package/SKILL.md +388 -11
  1083. package/dist/knowledge/skills/provider-backend-package/references/framework-optional-runtime-peers.md +31 -28
  1084. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-augmentation-api.md +16 -0
  1085. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-compliance-state-collector-api.md +96 -0
  1086. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-configuration-check-api.md +130 -0
  1087. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-file-storage-adapter-api.md +13 -0
  1088. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-inbound-endpoint-api.md +755 -0
  1089. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-incremental-consent-api.md +235 -0
  1090. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-loader-api.md +6 -0
  1091. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-processing-region-api.md +340 -0
  1092. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-shared-connection-api.md +72 -8
  1093. package/dist/knowledge/skills/provider-backend-package/references/framework-provider-subject-erasure-effect-api.md +222 -0
  1094. package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +9 -5
  1095. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +11 -2
  1096. package/dist/knowledge/skills/provider-frontend-module/SKILL.md +50 -5
  1097. package/dist/knowledge/skills/provider-frontend-module/references/framework-on-demand-capabilities-api.md +306 -0
  1098. package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +11 -3
  1099. package/dist/knowledge/skills/provider-operation-calls/SKILL.md +41 -15
  1100. package/dist/knowledge/skills/provider-operation-calls/references/browser-door-answers.md +56 -18
  1101. package/dist/knowledge/skills/provider-operation-calls/references/framework-browser-operation-policy-api.md +1 -1
  1102. package/dist/knowledge/skills/provider-operation-calls/references/framework-frontend-execute-operation-api.md +143 -25
  1103. package/dist/knowledge/skills/provider-operation-calls/references/framework-provider-operation-executor-api.md +6 -0
  1104. package/dist/knowledge/skills/provider-operation-calls/references/framework-provider-scope-reauthorization-api.md +9 -6
  1105. package/dist/knowledge/skills/provider-operation-calls/references/framework-rest-operation-contract-api.md +1275 -4
  1106. package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +71 -35
  1107. package/dist/knowledge/skills/rate-limit-authoring/references/framework-rate-limit-policy-api.md +27 -13
  1108. package/dist/knowledge/skills/resource-add-field/SKILL.md +7 -0
  1109. package/dist/knowledge/skills/resource-add-field/examples/add-priority-field-to-todos.example.md +32 -12
  1110. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +451 -67
  1111. package/dist/knowledge/skills/resource-add-resource/SKILL.md +57 -8
  1112. package/dist/knowledge/skills/resource-add-resource/references/framework-engine-api-reference-categories-api.md +119 -0
  1113. package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +165 -44
  1114. package/dist/knowledge/skills/resource-chat-commands/SKILL.md +138 -0
  1115. package/dist/knowledge/skills/resource-chat-commands/references/framework-resource-chat-command-contract.md +72 -0
  1116. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +171 -7
  1117. package/dist/knowledge/skills/resource-config-wiring/references/framework-administrative-continuity-codes-api.md +4 -4
  1118. package/dist/knowledge/skills/resource-config-wiring/references/framework-authority-audit-interpretation.md +17 -8
  1119. package/dist/knowledge/skills/resource-config-wiring/references/framework-collection-operation-declarations.md +8 -2
  1120. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-approval-api.md +371 -0
  1121. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +51 -7
  1122. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-bulk-api.md +163 -0
  1123. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-idempotency-key-api.md +66 -27
  1124. package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +200 -61
  1125. package/dist/knowledge/skills/resource-config-wiring/references/framework-request-field-offers-api.md +168 -0
  1126. package/dist/knowledge/skills/resource-config-wiring/references/framework-required-features-api.md +20 -0
  1127. package/dist/knowledge/skills/resource-config-wiring/references/framework-retention-policy-operations.md +8 -3
  1128. package/dist/knowledge/skills/resource-config-wiring/references/framework-role-ceiling-api.md +34 -10
  1129. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-operation-scope-enums-api.md +8 -6
  1130. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +351 -159
  1131. package/dist/knowledge/skills/resource-config-wiring/references/framework-scope-admissions-api.md +160 -2
  1132. package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +440 -119
  1133. package/dist/knowledge/skills/resource-config-wiring/references/framework-user-notifications-api.md +426 -32
  1134. package/dist/knowledge/skills/resource-config-wiring/references/framework-webhook-events-api.md +116 -0
  1135. package/dist/knowledge/skills/resource-custom-view/SKILL.md +126 -1
  1136. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +344 -62
  1137. package/dist/knowledge/skills/resource-custom-view/references/framework-backend-refusal-api.md +110 -0
  1138. package/dist/knowledge/skills/resource-external-data/SKILL.md +326 -76
  1139. package/dist/knowledge/skills/resource-external-data/references/bidirectional-pipelines.md +335 -0
  1140. package/dist/knowledge/skills/resource-external-data/references/declared-expressions.md +18 -6
  1141. package/dist/knowledge/skills/resource-external-data/references/erasure-suppression.md +71 -12
  1142. package/dist/knowledge/skills/resource-external-data/references/facet-augmentations.md +6 -0
  1143. package/dist/knowledge/skills/resource-external-data/references/framework-external-data-pipeline-api.md +96 -26
  1144. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +257 -57
  1145. package/dist/knowledge/skills/resource-external-data/references/framework-pipeline-admin-endpoints-api.md +111 -11
  1146. package/dist/knowledge/skills/resource-external-data/references/framework-system-of-record-capabilities-api.md +147 -0
  1147. package/dist/knowledge/skills/resource-external-data/references/incremental-extraction.md +30 -4
  1148. package/dist/knowledge/skills/resource-external-data/references/local-test-doubles.md +121 -0
  1149. package/dist/knowledge/skills/resource-external-data/references/odata-v2-sources.md +21 -9
  1150. package/dist/knowledge/skills/resource-external-data/references/outbound-pipelines.md +62 -15
  1151. package/dist/knowledge/skills/resource-external-data/references/partition-from-the-domain-plan.md +230 -0
  1152. package/dist/knowledge/skills/resource-external-data/references/presenting-a-copy-and-a-read-through.md +73 -0
  1153. package/dist/knowledge/skills/resource-external-data/references/provenance-cue.md +18 -2
  1154. package/dist/knowledge/skills/resource-external-data/references/rate-budgets-and-pacing.md +3 -1
  1155. package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +65 -18
  1156. package/dist/knowledge/skills/resource-external-data/references/remote-references.md +17 -7
  1157. package/dist/knowledge/skills/resource-external-data/references/requested-keys.md +104 -0
  1158. package/dist/knowledge/skills/resource-external-data/references/system-of-record-actions.md +77 -7
  1159. package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +25 -4
  1160. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-resource-mcp-exposure-contract.md +2 -2
  1161. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-catalogue-withdrawal-and-verification.md +1 -1
  1162. package/dist/knowledge/skills/resource-rag-source-fields/SKILL.md +18 -9
  1163. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +42 -3
  1164. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +29 -2
  1165. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-source-decorator-api.md +20 -20
  1166. package/dist/knowledge/skills/resource-retention-binding/SKILL.md +21 -3
  1167. package/dist/knowledge/skills/resource-retention-binding/references/framework-legal-holds-api.md +114 -7
  1168. package/dist/knowledge/skills/resource-retention-binding/references/framework-retention-binding-api.md +84 -1
  1169. package/dist/knowledge/skills/resource-retention-binding/references/framework-retention-enforcement-records-api.md +10 -0
  1170. package/dist/knowledge/skills/resource-retention-binding/references/framework-retention-schedule-api.md +5 -3
  1171. package/dist/knowledge/skills/resource-retention-binding/references/framework-statutory-retention-api.md +46 -0
  1172. package/dist/knowledge/skills/resource-retention-binding/references/start-point-decisions.md +14 -2
  1173. package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +27 -11
  1174. package/dist/knowledge/skills/resource-schema-authoring/examples/add-enum-field-with-ui.example.md +23 -7
  1175. package/dist/knowledge/skills/resource-schema-authoring/references/computed-totals.md +13 -8
  1176. package/dist/knowledge/skills/resource-schema-authoring/references/document-numbers.md +78 -17
  1177. package/dist/knowledge/skills/resource-schema-authoring/references/field-type-selection.md +4 -0
  1178. package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +105 -6
  1179. package/dist/knowledge/skills/resource-schema-authoring/references/framework-erasure-scrub-treatments-api.md +19 -22
  1180. package/dist/knowledge/skills/resource-schema-authoring/references/framework-personal-data-category-api.md +150 -35
  1181. package/dist/knowledge/skills/resource-schema-authoring/references/framework-schema-family-api.md +32 -4
  1182. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +58 -18
  1183. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +107 -5
  1184. package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +200 -69
  1185. package/dist/knowledge/skills/resource-schema-authoring/references/framework-system-managed-fields-api.md +2 -1
  1186. package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +326 -18
  1187. package/dist/knowledge/skills/resource-schema-authoring/references/shared-layer-decorator-checklist.md +7 -0
  1188. package/dist/knowledge/skills/resource-schema-authoring/references/special-factories.md +72 -0
  1189. package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +42 -2
  1190. package/dist/knowledge/skills/resource-status-lifecycle/references/framework-operation-condition-parameters-api.md +67 -0
  1191. package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +16 -12
  1192. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +219 -77
  1193. package/dist/knowledge/skills/resource-ui-behavior/references/framework-collection-filter-presets-api.md +105 -24
  1194. package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +131 -1
  1195. package/dist/knowledge/skills/resource-ui-behavior/references/framework-enum-frontend-handling-api.md +41 -7
  1196. package/dist/knowledge/skills/resource-ui-behavior/references/framework-field-tiles-api.md +114 -0
  1197. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +428 -72
  1198. package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +25 -9
  1199. package/dist/knowledge/skills/resource-ui-behavior/references/framework-primitive-ui-api.md +15 -3
  1200. package/dist/knowledge/skills/resource-ui-behavior/references/framework-record-page-parts-api.md +155 -0
  1201. package/dist/knowledge/skills/resource-ui-behavior/references/framework-related-resource-embeds-api.md +223 -6
  1202. package/dist/knowledge/skills/resource-ui-behavior/references/framework-resource-layout-templates-api.md +186 -65
  1203. package/dist/knowledge/skills/resource-ui-behavior/references/framework-section-stages-api.md +102 -0
  1204. package/dist/knowledge/skills/resource-ui-behavior/references/record-page-anatomy.md +138 -0
  1205. package/dist/knowledge/skills/resource-ui-behavior/references/surface-decisions.md +89 -32
  1206. package/dist/knowledge/skills/resource-ui-behavior/references/visual-quality-rubric.md +73 -0
  1207. package/dist/knowledge/skills/resource-ui-behavior/references/workflow-record-page.md +264 -0
  1208. package/dist/knowledge/skills/seeding-authoring/SKILL.md +24 -4
  1209. package/dist/knowledge/skills/seeding-authoring/references/cross-seed-row-references.md +12 -0
  1210. package/dist/knowledge/skills/seeding-authoring/references/data-seeding-mode-picker.md +16 -1
  1211. package/dist/knowledge/skills/seeding-authoring/references/framework-data-seeding-api.md +7 -6
  1212. package/dist/knowledge/skills/seeding-operations/references/data-seeding-admin-runbook.md +15 -8
  1213. package/dist/knowledge/skills/seeding-operations/references/framework-data-seeding-operations-api.md +3 -0
  1214. package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +48 -11
  1215. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +183 -32
  1216. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +72 -13
  1217. package/dist/knowledge/skills/spec-catalog-authoring/SKILL.md +5 -4
  1218. package/dist/knowledge/skills/spec-catalog-authoring/references/catalog-spec-pattern-overview.md +5 -4
  1219. package/dist/knowledge/skills/spec-companion-exports/SKILL.md +1 -0
  1220. package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +30 -2
  1221. package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +15 -7
  1222. package/dist/knowledge/skills/spec-resource-update/SKILL.md +26 -0
  1223. package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +186 -83
  1224. package/dist/knowledge/skills/spec-resource-update/references/workflow-record-page-specification.md +237 -0
  1225. package/dist/knowledge/skills/spec-update-after-change/references/framework-spec-factory-api.md +113 -70
  1226. package/dist/knowledge/skills/subject-data-export/SKILL.md +176 -0
  1227. package/dist/knowledge/skills/subject-data-export/references/file-content-exclusions.md +15 -0
  1228. package/dist/knowledge/skills/subject-data-export/references/framework-subject-export-api.md +142 -0
  1229. package/dist/knowledge/skills/subject-data-export/references/framework-subject-export-archive-api.md +33 -0
  1230. package/dist/knowledge/skills/views-add-composite-view/SKILL.md +14 -5
  1231. package/dist/knowledge/skills/views-add-custom-view/SKILL.md +10 -1
  1232. package/dist/knowledge/skills/views-add-custom-view/references/framework-focus-indicator-api.md +145 -0
  1233. package/dist/knowledge/skills/views-app-level/SKILL.md +3 -1
  1234. package/dist/knowledge/skills/views-app-level/references/workflow-home.md +373 -0
  1235. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +41 -5
  1236. package/dist/knowledge/skills/views-chart-authoring/references/framework-chart-view-contracts-api.md +13 -0
  1237. package/dist/knowledge/skills/views-chart-authoring/references/framework-resource-chart-data-api.md +9 -5
  1238. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +15 -4
  1239. package/dist/knowledge/skills/views-composite-authoring/references/framework-chart-dashboard-api.md +244 -0
  1240. package/dist/knowledge/skills/views-execution-authoring/SKILL.md +11 -2
  1241. package/dist/knowledge/skills/views-execution-authoring/references/framework-execution-view-contracts-api.md +57 -3
  1242. package/dist/knowledge/skills/website-anonymous-session/SKILL.md +61 -25
  1243. package/dist/knowledge/skills/website-blog-authoring/SKILL.md +253 -78
  1244. package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +1105 -222
  1245. package/dist/knowledge/skills/website-building-blocks/SKILL.md +337 -0
  1246. package/dist/knowledge/skills/website-building-blocks/references/framework-website-blocks-api.md +3050 -0
  1247. package/dist/knowledge/skills/website-building-blocks/references/framework-website-demo-examples.md +627 -0
  1248. package/dist/knowledge/skills/website-building-blocks/references/framework-website-product-kit-api.md +3309 -0
  1249. package/dist/knowledge/skills/website-building-blocks/references/website-visual-quality-rubric.md +75 -0
  1250. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +42 -19
  1251. package/dist/knowledge/skills/website-bundle-discipline/references/example-website-button-override.md +8 -12
  1252. package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +20 -5
  1253. package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +84 -28
  1254. package/dist/knowledge/skills/website-factory-advanced/SKILL.md +67 -64
  1255. package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +58 -23
  1256. package/dist/knowledge/skills/website-inbound-contact-forms/references/framework-submission-challenge-api.md +5 -1
  1257. package/dist/knowledge/skills/website-label-pack/SKILL.md +43 -21
  1258. package/dist/knowledge/skills/website-layout-overrides/SKILL.md +112 -77
  1259. package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +24 -13
  1260. package/dist/knowledge/skills/website-motion-design/SKILL.md +277 -0
  1261. package/dist/knowledge/skills/website-motion-design/references/framework-motion-api.md +1562 -0
  1262. package/dist/knowledge/skills/website-motion-design/references/industry-practice.md +28 -0
  1263. package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +255 -397
  1264. package/dist/knowledge/skills/website-navigation-authoring/references/framework-menu-api.md +712 -0
  1265. package/dist/knowledge/skills/website-navigation-authoring/references/framework-public-document-links-api.md +28 -6
  1266. package/dist/knowledge/skills/website-navigation-authoring/references/menu-keys-and-styling.md +151 -0
  1267. package/dist/knowledge/skills/website-navigation-authoring/references/worked-examples-header-footer.md +131 -326
  1268. package/dist/knowledge/skills/website-page-authoring/SKILL.md +160 -67
  1269. package/dist/knowledge/skills/website-page-authoring/references/framework-page-kinds-api.md +982 -0
  1270. package/dist/knowledge/skills/website-page-authoring/references/framework-site-context-loader-api.md +29 -5
  1271. package/dist/knowledge/skills/website-page-authoring/references/homepage-content-and-art-direction.md +19 -0
  1272. package/dist/knowledge/skills/website-page-authoring/references/page-kinds.md +118 -0
  1273. package/dist/knowledge/skills/website-page-variants/SKILL.md +70 -69
  1274. package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +48 -28
  1275. package/dist/knowledge/skills/website-section-comparison/SKILL.md +1171 -0
  1276. package/dist/knowledge/skills/website-section-comparison/references/define-website-section-api.md +679 -0
  1277. package/dist/knowledge/skills/website-section-comparison/references/framework-website-tables-api.md +487 -0
  1278. package/dist/knowledge/skills/website-section-contact/SKILL.md +409 -186
  1279. package/dist/knowledge/skills/website-section-contact/references/define-website-section-api.md +197 -119
  1280. package/dist/knowledge/skills/website-section-cta/SKILL.md +399 -235
  1281. package/dist/knowledge/skills/website-section-cta/references/define-website-section-api.md +197 -119
  1282. package/dist/knowledge/skills/website-section-faq/SKILL.md +562 -303
  1283. package/dist/knowledge/skills/website-section-faq/references/define-website-section-api.md +197 -119
  1284. package/dist/knowledge/skills/website-section-faq/references/framework-website-faq-api.md +489 -0
  1285. package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +648 -275
  1286. package/dist/knowledge/skills/website-section-feature-benefit-summary/references/define-website-section-api.md +197 -119
  1287. package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +573 -265
  1288. package/dist/knowledge/skills/website-section-feature-detail/references/define-website-section-api.md +197 -119
  1289. package/dist/knowledge/skills/website-section-footer-cta/SKILL.md +533 -234
  1290. package/dist/knowledge/skills/website-section-footer-cta/references/define-website-section-api.md +197 -119
  1291. package/dist/knowledge/skills/website-section-hero/SKILL.md +604 -333
  1292. package/dist/knowledge/skills/website-section-hero/references/define-website-section-api.md +198 -120
  1293. package/dist/knowledge/skills/website-section-how-it-works/SKILL.md +1150 -0
  1294. package/dist/knowledge/skills/website-section-how-it-works/references/define-website-section-api.md +679 -0
  1295. package/dist/knowledge/skills/website-section-how-it-works/references/framework-website-steps-api.md +337 -0
  1296. package/dist/knowledge/skills/website-section-integrations/SKILL.md +974 -0
  1297. package/dist/knowledge/skills/website-section-integrations/references/define-website-section-api.md +679 -0
  1298. package/dist/knowledge/skills/website-section-integrations/references/framework-website-marquee-api.md +825 -0
  1299. package/dist/knowledge/skills/website-section-latest-posts/SKILL.md +928 -0
  1300. package/dist/knowledge/skills/website-section-latest-posts/references/define-website-section-api.md +679 -0
  1301. package/dist/knowledge/skills/website-section-latest-posts/references/framework-website-latest-posts-api.md +465 -0
  1302. package/dist/knowledge/skills/website-section-pricing/SKILL.md +594 -379
  1303. package/dist/knowledge/skills/website-section-pricing/examples/pricing-offers.example.md +189 -0
  1304. package/dist/knowledge/skills/website-section-pricing/references/define-website-section-api.md +197 -119
  1305. package/dist/knowledge/skills/website-section-pricing/references/framework-pricing-catalog-api.md +5 -2
  1306. package/dist/knowledge/skills/website-section-pricing/references/framework-website-pricing-api.md +670 -0
  1307. package/dist/knowledge/skills/website-section-problem/SKILL.md +1150 -0
  1308. package/dist/knowledge/skills/website-section-problem/references/define-website-section-api.md +679 -0
  1309. package/dist/knowledge/skills/website-section-problem/references/framework-website-card-grid-api.md +664 -0
  1310. package/dist/knowledge/skills/website-section-product-showcase/SKILL.md +1322 -0
  1311. package/dist/knowledge/skills/website-section-product-showcase/references/define-website-section-api.md +679 -0
  1312. package/dist/knowledge/skills/website-section-product-showcase/references/framework-website-card-grid-api.md +533 -0
  1313. package/dist/knowledge/skills/website-section-product-showcase/references/framework-website-product-tour-api.md +917 -0
  1314. package/dist/knowledge/skills/website-section-roadmap/SKILL.md +1133 -0
  1315. package/dist/knowledge/skills/website-section-roadmap/references/define-website-section-api.md +679 -0
  1316. package/dist/knowledge/skills/website-section-roadmap/references/framework-website-roadmap-api.md +475 -0
  1317. package/dist/knowledge/skills/website-section-social-proof/SKILL.md +740 -316
  1318. package/dist/knowledge/skills/website-section-social-proof/references/define-website-section-api.md +197 -119
  1319. package/dist/knowledge/skills/website-section-social-proof/references/framework-website-quote-cards-api.md +623 -0
  1320. package/dist/knowledge/skills/website-section-solution-paths/SKILL.md +1057 -0
  1321. package/dist/knowledge/skills/website-section-solution-paths/references/define-website-section-api.md +679 -0
  1322. package/dist/knowledge/skills/website-section-solution-paths/references/framework-website-solution-paths-api.md +477 -0
  1323. package/dist/knowledge/skills/website-section-stats/SKILL.md +1086 -0
  1324. package/dist/knowledge/skills/website-section-stats/references/define-website-section-api.md +679 -0
  1325. package/dist/knowledge/skills/website-section-stats/references/framework-website-stats-api.md +517 -0
  1326. package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +183 -67
  1327. package/dist/knowledge/skills/website-seo-aeo-geo/references/aeo-api.md +576 -57
  1328. package/dist/knowledge/skills/website-seo-aeo-geo/references/geo-api.md +1 -1
  1329. package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +6 -94
  1330. package/dist/knowledge/skills/website-theme-authoring/SKILL.md +226 -0
  1331. package/dist/knowledge/skills/website-theme-authoring/references/framework-website-theme-api.md +893 -0
  1332. package/dist/knowledge/skills/worker-authoring/SKILL.md +4 -2
  1333. package/dist/knowledge/skills/worker-authoring/references/framework-worker-init-contract.md +4 -2
  1334. package/dist/knowledge/topic-index.json +17998 -8568
  1335. package/dist/tsconfig.build.tsbuildinfo +1 -1
  1336. package/package.json +6 -6
  1337. package/dist/knowledge/references/example.organizations.serves-as-provider.md +0 -12
  1338. package/dist/knowledge/references/saas.models.auth.service-provider-client-authentication.md +0 -169
  1339. package/dist/knowledge/references/saas.models.organizations.service-provider-activity-feed.md +0 -121
  1340. package/dist/knowledge/references/saas.models.organizations.service-provider-client-controls.md +0 -49
  1341. package/dist/knowledge/references/saas.models.organizations.service-provider-relationships.md +0 -567
  1342. package/dist/knowledge/references/saas.website.root-config.navigation.md +0 -37
  1343. package/dist/knowledge/skills/service-provider-relationships/SKILL.md +0 -455
  1344. package/dist/knowledge/skills/service-provider-relationships/references/framework-organization-types-api.md +0 -270
  1345. package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-activity-feed-api.md +0 -129
  1346. package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-capability-grants-api.md +0 -161
  1347. package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-client-authentication-api.md +0 -224
  1348. package/dist/knowledge/skills/service-provider-relationships/references/framework-service-provider-relationships-api.md +0 -576
  1349. package/dist/tsconfig.tsbuildinfo +0 -1
@@ -3,7 +3,9 @@
3
3
  Read this when authoring an operation by hand, or when an operation's answer is not JSON (a CSV
4
4
  export, an XML document, an empty 204) or its body is raw bytes.
5
5
 
6
- - `responseDecoding` decides how the answer is read, and sets the default `Accept` header.
6
+ - `responseDecoding` decides how the answer is read, and sets the default `Accept` header. `BINARY` needs
7
+ `binaryResponse` (a byte ceiling and the accepted media types) and takes no `outputSchema` or `resultPath`;
8
+ its output is `{ bytes, contentType }`.
7
9
  - `requestBody.encoding` decides how the input becomes the body; `TEXT` and `BINARY` need `contentType`.
8
10
  - `pathTemplate` is RELATIVE to the provider's base URL and must start with `/`. It is appended to the
9
11
  base URL, so a template such as `@host/x` or `.host/x` would move the request to another host; every
@@ -18,6 +20,539 @@ export, an XML document, an empty 204) or its body is raw bytes.
18
20
 
19
21
  ### Origin Package: `@wildo-ai/external-connectors-models`
20
22
 
23
+ ```typescript
24
+ /**
25
+ * The GraphQL document a provider operation sends (#3392), set as `ProviderRestOperation.graphql`.
26
+ *
27
+ * With it the operation is a GraphQL call: `method` must be `POST`, `pathTemplate` is the vendor's GraphQL endpoint
28
+ * (`/graphql`), and the operation's input IS the variables. So it may declare no `requestBody`, and no parameter fed by
29
+ * the input (a `constantValue` header or path parameter, such as a pinned API version, is allowed). `inputSchema`
30
+ * describes the variables, one top-level field per variable the document declares, and `inputOptions` work on them as on
31
+ * any input. `resultPath` and `outputSchema` read the answer's `data`, never the `{ data, errors }` envelope around it.
32
+ * `responseDecoding` stays JSON.
33
+ *
34
+ * Checked when the catalogue loads, at publish and on every call ({@link describeProviderRestOperationGraphqlDefects}).
35
+ *
36
+ * @example
37
+ * // GitHub: a repository's discussions, which GitHub serves through GraphQL only.
38
+ * {
39
+ * operationId: 'github_issues_list_discussions', domain: 'default', method: API_HttpMethod.POST, pathTemplate: '/graphql',
40
+ * classification: ExternalOperation_Classification.READ,
41
+ * graphql: {
42
+ * operationName: 'ListDiscussions',
43
+ * document: 'query ListDiscussions($owner: String!, $repo: String!, $first: Int!) { repository(owner: $owner, name: $repo) { discussions(first: $first) { nodes { number title } } } }',
44
+ * },
45
+ * inputSchema: z.strictObject({ owner: z.string(), repo: z.string(), first: z.number().int() }),
46
+ * resultPath: 'repository.discussions',
47
+ * }
48
+ */
49
+ export interface ProviderRestOperationGraphql {
50
+ /**
51
+ * The executable document, owned by the provider: exactly ONE operation (a `query` or a `mutation`, named
52
+ * {@link operationName}) and any fragments it uses. A `query` is a READ operation and a `mutation` a WRITE; a
53
+ * `subscription` is refused, since it is not answered over a single POST.
54
+ */
55
+ readonly document: string;
56
+ /** The operation's name in {@link document}, sent as `operationName`. */
57
+ readonly operationName: string;
58
+ /**
59
+ * Dot path, inside EACH error of the answer's `errors` list, to the vendor's machine-readable code (`extensions.code`
60
+ * by convention, where a vendor uses it). The specification standardizes no code, so absent, no code is read and the
61
+ * failure carries the vendor's messages only. A code is kept only when it is code-shaped, as every vendor code is.
62
+ */
63
+ readonly errorCodePath?: string;
64
+ /**
65
+ * The codes, read at {@link errorCodePath}, that mean the vendor refused the CREDENTIAL itself rather than the request
66
+ * (#3392): the stored credential is then recorded as rejected, as a REST vendor's
67
+ * `applicationOutcome.credentialRefusedErrorCodes` records it. A GraphQL vendor may name a dead or expired token inside
68
+ * a 200 (an error list beside or instead of `data`) or inside a 4xx carrying the same error list, and both are read.
69
+ * The failure itself is unchanged: the call fails with the vendor's code and is never retried.
70
+ *
71
+ * List only a code the vendor DOCUMENTS as a refused credential. A code for a resource the credential may not reach
72
+ * (`FORBIDDEN` on one repository), for a missing scope, or for a request sent with no credential at all, does not
73
+ * belong here: the credential still works, and recording it rejected would show a working connection as broken.
74
+ * Requires {@link errorCodePath}, without which no code is read and none could match.
75
+ *
76
+ * @example
77
+ * // monday.com answers a key it refuses with the error code `Unauthorized`, whose documented resolution is a valid key.
78
+ * // spec-cite: https://developer.monday.com/api-reference/docs/errors — the `Unauthorized` row (HTTP 401, resolution
79
+ * // "Input a valid API key."), fetched 2026-11-09.
80
+ * graphql: { operationName: 'CreateItem', document: CREATE_ITEM, errorCodePath: 'extensions.code', credentialRefusedErrorCodes: ['Unauthorized'] }
81
+ */
82
+ readonly credentialRefusedErrorCodes?: readonly string[];
83
+ /**
84
+ * Where a MUTATION's answer says the vendor refused it in the DATA rather than in `errors` (follow-up to #3392). Several
85
+ * GraphQL vendors answer a write they refused with a successful response whose payload carries the refusal: Shopify's
86
+ * `userErrors` list ("validation failures, such as invalid field values or business logic violations, that prevent the
87
+ * operation from completing"), Linear's `success: Boolean!`. Without it such an answer is returned as the result and a
88
+ * caller that does not read the payload takes a refused write for a done one; with it the call FAILS, carrying the
89
+ * vendor's messages, exactly as an `errors` entry does. See {@link ProviderGraphqlPayloadRefusal}.
90
+ * spec-cite: https://shopify.dev/docs/api/admin-graphql — the `UserError` description quoted above, fetched 2026-11-10.
91
+ *
92
+ * @example
93
+ * // Shopify: productCreate's userErrors, each `{ field, message }`.
94
+ * payloadRefusal: { kind: ProviderGraphqlPayloadRefusalKind.USER_ERRORS, path: 'productCreate.userErrors', messagePath: 'message', fieldPath: 'field' }
95
+ */
96
+ readonly payloadRefusal?: ProviderGraphqlPayloadRefusal;
97
+ }
98
+
99
+ /** How a mutation's payload states a refusal. See {@link ProviderRestOperationGraphql.payloadRefusal}. */
100
+ export enum ProviderGraphqlPayloadRefusalKind {
101
+ /** A list of the vendor's refusals (Shopify's `userErrors`): the write was refused when the list is not empty. */
102
+ USER_ERRORS = 'user_errors',
103
+ /** A boolean the vendor sets to `false` when it did not do the write (Linear's `success`). */
104
+ SUCCESS_FLAG = 'success_flag',
105
+ }
106
+
107
+ /**
108
+ * Where a mutation's payload states a refusal (follow-up to #3392). Every path is a dot path, `path` from the answer's
109
+ * `data` (as `resultPath` is), `messagePath`, `fieldPath` and `codePath` from inside each listed refusal.
110
+ *
111
+ * - {@link ProviderGraphqlPayloadRefusalKind.USER_ERRORS}: a non-empty list at `path` fails the call. Each entry's text at
112
+ * `messagePath` (`message` when absent) is kept, prefixed with the input field it names at `fieldPath` (a string or a
113
+ * list of path segments), and the first code-shaped value at `codePath` is the failure's code.
114
+ * - {@link ProviderGraphqlPayloadRefusalKind.SUCCESS_FLAG}: `false` at `path` fails the call.
115
+ *
116
+ * Anything else at `path` (an absent payload, `true`, an empty list) refuses nothing: the answer is read as it is.
117
+ */
118
+ export type ProviderGraphqlPayloadRefusal =
119
+ | {
120
+ readonly kind: ProviderGraphqlPayloadRefusalKind.USER_ERRORS;
121
+ readonly path: string;
122
+ readonly messagePath?: string;
123
+ readonly fieldPath?: string;
124
+ readonly codePath?: string;
125
+ }
126
+ | { readonly kind: ProviderGraphqlPayloadRefusalKind.SUCCESS_FLAG; readonly path: string };
127
+
128
+ /** What a GraphQL document's operation does. A `subscription` is not served over a single POST, so it is no member. */
129
+ export enum ProviderGraphqlOperationType {
130
+ /** Reads. The operation must be classified READ. */
131
+ QUERY = 'query',
132
+ /** Changes the vendor. The operation must be classified WRITE. */
133
+ MUTATION = 'mutation',
134
+ }
135
+
136
+ /**
137
+ * The `Accept` a GraphQL call sends: the GraphQL response media type first, `application/json` for a server that predates
138
+ * it (GraphQL over HTTP §4.2, quoted in this module's header).
139
+ * semantic-literal-boundary: the media types GraphQL over HTTP names, sent on the wire.
140
+ */
141
+ export const PROVIDER_GRAPHQL_ACCEPT_HEADER = 'application/graphql-response+json, application/json;q=0.9';
142
+
143
+ /** At most this many of the vendor's error messages are kept on a failure. */
144
+ export const PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGES = 10;
145
+ /** A kept error message is cut at this many characters. */
146
+ export const PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGE_LENGTH = 500;
147
+
148
+ /** One operation a document defines, as {@link readProviderGraphqlDocument} reads it. */
149
+ export interface ProviderGraphqlDocumentOperation {
150
+ /** `query`, `mutation` or `subscription`, as written (an anonymous `{ … }` is a query). */
151
+ readonly type: string;
152
+ /** Absent for an anonymous operation. */
153
+ readonly name?: string;
154
+ /** The variables it declares, without their `$`, in order. */
155
+ readonly variables: readonly string[];
156
+ }
157
+
158
+ /** What a document holds, or why it cannot be read. */
159
+ export interface ProviderGraphqlDocumentShape {
160
+ readonly operations: readonly ProviderGraphqlDocumentOperation[];
161
+ /** Set when the text is not a document of executable definitions. `operations` is then what was read before it. */
162
+ readonly defect?: string;
163
+ }
164
+
165
+ const GRAPHQL_NAME = /^[_A-Za-z][_0-9A-Za-z]*$/;
166
+ const GRAPHQL_PUNCTUATORS = new Set(['!', '$', '&', '(', ')', ':', '=', '@', '[', ']', '{', '|', '}']);
167
+
168
+ /**
169
+ * The tokens of a GraphQL document, with strings and comments dropped: enough to find its definitions and their
170
+ * variables. Not a validating parser: the vendor's server is the parser that decides, and this only has to see the
171
+ * document's outline. A block string (`"""…"""`) and a string (`"…"`, with `\` escapes) are skipped whole, so a brace or
172
+ * a `$` inside one is never read as structure. `undefined` for a string that never closes.
173
+ */
174
+ function tokenizeGraphqlDocument(document: string): string[] | undefined {
175
+ const tokens: string[] = [];
176
+ let index = 0;
177
+ while (index < document.length) {
178
+ const character = document[index]!;
179
+ if (character === '#') {
180
+ while (index < document.length && document[index] !== '\n' && document[index] !== '\r') index += 1;
181
+ continue;
182
+ }
183
+ if (character === '"') {
184
+ if (document.startsWith('"""', index)) {
185
+ const close = document.indexOf('"""', index + 3);
186
+ // A `\"""` inside a block string is an escaped delimiter, not its end.
187
+ let end = close;
188
+ while (end !== -1 && document[end - 1] === '\\') end = document.indexOf('"""', end + 3);
189
+ if (end === -1) return undefined;
190
+ index = end + 3;
191
+ } else {
192
+ index += 1;
193
+ while (index < document.length && document[index] !== '"') {
194
+ if (document[index] === '\n') return undefined;
195
+ index += document[index] === '\\' ? 2 : 1;
196
+ }
197
+ if (index >= document.length) return undefined;
198
+ index += 1;
199
+ }
200
+ tokens.push('"');
201
+ continue;
202
+ }
203
+ if (character === '.' && document.startsWith('...', index)) {
204
+ tokens.push('...');
205
+ index += 3;
206
+ continue;
207
+ }
208
+ if (GRAPHQL_PUNCTUATORS.has(character)) {
209
+ tokens.push(character);
210
+ index += 1;
211
+ continue;
212
+ }
213
+ if (/[_A-Za-z0-9.+-]/.test(character)) {
214
+ let end = index + 1;
215
+ while (end < document.length && /[_A-Za-z0-9.+-]/.test(document[end]!)) end += 1;
216
+ tokens.push(document.slice(index, end));
217
+ index = end;
218
+ continue;
219
+ }
220
+ // White space, commas (insignificant in GraphQL) and the byte order mark.
221
+ index += 1;
222
+ }
223
+ return tokens;
224
+ }
225
+
226
+ /**
227
+ * The executable definitions of a GraphQL document (#3392): each operation's type, name and declared variables. A
228
+ * fragment is skipped; a type-system definition (`type`, `schema`, …) is a defect, since a document sent to a server is
229
+ * executable only.
230
+ */
231
+ export function readProviderGraphqlDocument(document: string): ProviderGraphqlDocumentShape {
232
+ const tokens = tokenizeGraphqlDocument(document);
233
+ if (tokens === undefined) return { operations: [], defect: 'a string in it never closes' };
234
+ const operations: ProviderGraphqlDocumentOperation[] = [];
235
+ let index = 0;
236
+ /** Skips the balanced block opening at `index` (a `{` or a `(`), and answers the index after it, or -1. */
237
+ const skipBalanced = (open: string, close: string): number => {
238
+ let depth = 0;
239
+ for (let position = index; position < tokens.length; position += 1) {
240
+ if (tokens[position] === open) depth += 1;
241
+ else if (tokens[position] === close) {
242
+ depth -= 1;
243
+ if (depth === 0) return position + 1;
244
+ }
245
+ }
246
+ return -1;
247
+ };
248
+ while (index < tokens.length) {
249
+ const token = tokens[index]!;
250
+ if (token === '{') {
251
+ const after = skipBalanced('{', '}');
252
+ if (after === -1) return { operations, defect: 'a selection set never closes' };
253
+ operations.push({ type: 'query', variables: [] });
254
+ index = after;
255
+ continue;
256
+ }
257
+ if (token === 'query' || token === 'mutation' || token === 'subscription') {
258
+ index += 1;
259
+ const name = tokens[index] !== undefined && GRAPHQL_NAME.test(tokens[index]!) ? tokens[index] : undefined;
260
+ if (name !== undefined) index += 1;
261
+ const variables: string[] = [];
262
+ if (tokens[index] === '(') {
263
+ const after = skipBalanced('(', ')');
264
+ if (after === -1) return { operations, defect: `the variable definitions of ${name ?? 'an operation'} never close` };
265
+ // A definition is `$name :`; a default value is constant and holds no variable.
266
+ for (let position = index; position < after - 2; position += 1) {
267
+ if (tokens[position] === '$' && tokens[position + 2] === ':' && GRAPHQL_NAME.test(tokens[position + 1]!)) variables.push(tokens[position + 1]!);
268
+ }
269
+ index = after;
270
+ }
271
+ while (index < tokens.length && tokens[index] !== '{') index += 1;
272
+ if (index >= tokens.length) return { operations, defect: `${name ?? 'an operation'} has no selection set` };
273
+ const after = skipBalanced('{', '}');
274
+ if (after === -1) return { operations, defect: `the selection set of ${name ?? 'an operation'} never closes` };
275
+ operations.push({ type: token, ...(name === undefined ? {} : { name }), variables });
276
+ index = after;
277
+ continue;
278
+ }
279
+ if (token === 'fragment') {
280
+ while (index < tokens.length && tokens[index] !== '{') index += 1;
281
+ if (index >= tokens.length) return { operations, defect: 'a fragment has no selection set' };
282
+ const after = skipBalanced('{', '}');
283
+ if (after === -1) return { operations, defect: 'a fragment\'s selection set never closes' };
284
+ index = after;
285
+ continue;
286
+ }
287
+ return { operations, defect: `'${token}' begins no executable definition (an operation or a fragment)` };
288
+ }
289
+ return { operations };
290
+ }
291
+
292
+ /**
293
+ * The top-level fields an input schema declares, read through Zod's own definition (`_zod.def`) as the input-options
294
+ * check reads it, so a module built against another copy of Zod is read the same. Wrappers that keep the value's shape
295
+ * are seen through; a union declares what any of its options declares. `undefined` when the schema is not an object
296
+ * (or a union of objects), so its fields cannot be listed.
297
+ */
298
+ function inputSchemaTopLevelFields(schema: unknown): Set<string> | undefined {
299
+ let current: unknown = schema;
300
+ for (let depth = 0; depth < 64; depth += 1) {
301
+ const def = (current as { _zod?: { def?: Record<string, unknown> } } | undefined)?._zod?.def;
302
+ if (def === undefined) return undefined;
303
+ switch (def.type) {
304
+ case 'optional': case 'nullable': case 'default': case 'prefault': case 'readonly': case 'catch': case 'nonoptional':
305
+ current = def.innerType;
306
+ continue;
307
+ case 'pipe':
308
+ current = def.in;
309
+ continue;
310
+ case 'lazy':
311
+ current = typeof def.getter === 'function' ? (def.getter as () => unknown)() : undefined;
312
+ continue;
313
+ case 'object':
314
+ return new Set(Object.keys((def.shape as Record<string, unknown> | undefined) ?? {}));
315
+ case 'union': {
316
+ const fields = new Set<string>();
317
+ for (const option of Array.isArray(def.options) ? def.options : []) {
318
+ const optionFields = inputSchemaTopLevelFields(option);
319
+ if (optionFields === undefined) return undefined;
320
+ for (const field of optionFields) fields.add(field);
321
+ }
322
+ return fields;
323
+ }
324
+ default:
325
+ return undefined;
326
+ }
327
+ }
328
+ return undefined;
329
+ }
330
+
331
+ /**
332
+ * Why a GraphQL operation cannot be sent as declared, or an empty list (#3392). Empty for an operation without
333
+ * `graphql`. Checked where a catalogue loads (the operation executor, an augmentation merge), at `wildo registry publish`,
334
+ * and by the request compiler on every call, so the one rule refuses in every place:
335
+ *
336
+ * - the call is a POST with no `requestBody`, every parameter carries a `constantValue` (the input is the variables
337
+ * and nothing else), and the answer is read as JSON;
338
+ * - the document reads as exactly ONE operation, named `operationName`, beside any fragments;
339
+ * - a `query` is classified READ and a `mutation` WRITE; a `subscription` is refused;
340
+ * - each declared variable is a top-level field of `inputSchema`, and each top-level field is a declared variable, so no
341
+ * value a caller supplies is silently dropped (when `inputSchema` lists its fields; without one, the call refuses a
342
+ * value for a variable the document does not declare);
343
+ * - `errorCodePath` is a dot path;
344
+ * - each of `credentialRefusedErrorCodes` is code-shaped (a value of any other shape is never kept, so it could never
345
+ * match), and the list comes with an `errorCodePath` to read the code at;
346
+ * - a `payloadRefusal` belongs to a mutation, names a kind of its vocabulary, and reads every path as a dot path.
347
+ */
348
+ export function describeProviderRestOperationGraphqlDefects(
349
+ operation: Pick<
350
+ ProviderRestOperation,
351
+ 'operationId' | 'method' | 'classification' | 'parameters' | 'requestBody' | 'responseDecoding' | 'binaryResponse' | 'inputSchema' | 'graphql'
352
+ >,
353
+ ): string[] {
354
+ const graphql = operation.graphql;
355
+ if (graphql === undefined) return [];
356
+ const at = `GraphQL operation '${operation.operationId}'`;
357
+ const defects: string[] = [];
358
+ if (operation.method !== API_HttpMethod.POST) defects.push(`${at} is sent with ${operation.method}; a GraphQL call is a POST`);
359
+ if (operation.requestBody !== undefined) defects.push(`${at} declares a requestBody; its body is the document and its variables`);
360
+ for (const parameter of operation.parameters ?? []) {
361
+ if (parameter.constantValue === undefined) {
362
+ defects.push(`${at} declares the ${parameter.in} parameter '${parameter.name}' fed by the input; its input is the document's variables only, so a parameter must carry a constantValue`);
363
+ }
364
+ }
365
+ if (operation.responseDecoding !== undefined && operation.responseDecoding !== ProviderRestResponseDecoding.JSON) defects.push(`${at} reads its answer as ${operation.responseDecoding}; a GraphQL answer is JSON`);
366
+ if (operation.binaryResponse !== undefined) defects.push(`${at} declares binaryResponse; a GraphQL answer is JSON`);
367
+ if (!GRAPHQL_NAME.test(graphql.operationName)) defects.push(`${at} names the operation '${graphql.operationName}', which is not a GraphQL name`);
368
+ if (graphql.errorCodePath !== undefined && graphql.errorCodePath.split('.').some((segment) => segment.length === 0)) {
369
+ defects.push(`${at} reads its error code at '${graphql.errorCodePath}', which is not a dot path`);
370
+ }
371
+ const payloadRefusal = graphql.payloadRefusal;
372
+ if (payloadRefusal !== undefined) {
373
+ const kinds: readonly string[] = Object.values(ProviderGraphqlPayloadRefusalKind);
374
+ if (!kinds.includes(payloadRefusal.kind)) defects.push(`${at} declares the payload refusal kind ${JSON.stringify(payloadRefusal.kind)}, which is none of ${kinds.join(', ')}`);
375
+ const paths: [string, string | undefined][] = [['path', payloadRefusal.path]];
376
+ if (payloadRefusal.kind === ProviderGraphqlPayloadRefusalKind.USER_ERRORS) {
377
+ paths.push(['messagePath', payloadRefusal.messagePath], ['fieldPath', payloadRefusal.fieldPath], ['codePath', payloadRefusal.codePath]);
378
+ }
379
+ for (const [field, value] of paths) {
380
+ if (value === undefined && field !== 'path') continue;
381
+ if (typeof value !== 'string' || value.length === 0 || value.split('.').some((segment) => segment.length === 0)) {
382
+ defects.push(`${at} reads its payload refusal's ${field} at ${JSON.stringify(value)}, which is not a dot path`);
383
+ }
384
+ }
385
+ }
386
+ if (graphql.credentialRefusedErrorCodes !== undefined && graphql.errorCodePath === undefined) {
387
+ defects.push(`${at} lists credentialRefusedErrorCodes but no errorCodePath, so no code is read and none of them could ever match`);
388
+ }
389
+ for (const code of graphql.credentialRefusedErrorCodes ?? []) {
390
+ if (!PROVIDER_VENDOR_ERROR_CODE_SHAPE.test(code)) {
391
+ defects.push(`${at} lists the credential-refusal code '${code}', which is not code-shaped and would never match a code the transport keeps`);
392
+ }
393
+ }
394
+
395
+ const shape = readProviderGraphqlDocument(graphql.document);
396
+ if (shape.defect !== undefined) {
397
+ defects.push(`${at}: its document does not read as a GraphQL document (${shape.defect})`);
398
+ return defects;
399
+ }
400
+ const named = shape.operations.filter((candidate) => candidate.name === graphql.operationName);
401
+ if (named.length !== 1 || shape.operations.length !== 1) {
402
+ defects.push(
403
+ `${at}: its document must define exactly one operation, named '${graphql.operationName}', and it defines `
404
+ + `${shape.operations.length === 0 ? 'none' : shape.operations.map((candidate) => `${candidate.type} ${candidate.name ?? '(anonymous)'}`).join(', ')}`,
405
+ );
406
+ return defects;
407
+ }
408
+ const [definition] = named as [ProviderGraphqlDocumentOperation];
409
+ const expected = definition.type === ProviderGraphqlOperationType.QUERY ? ExternalOperation_Classification.READ
410
+ : definition.type === ProviderGraphqlOperationType.MUTATION ? ExternalOperation_Classification.WRITE
411
+ : undefined;
412
+ if (expected === undefined) defects.push(`${at} is a ${definition.type}, which is not answered over a single POST`);
413
+ // A refusal stated in a payload is a WRITE's: a query that answers data refused nothing.
414
+ if (graphql.payloadRefusal !== undefined && definition.type !== ProviderGraphqlOperationType.MUTATION) {
415
+ defects.push(`${at} is a ${definition.type} and declares a payload refusal, which only a mutation's payload states`);
416
+ }
417
+ else if (operation.classification !== expected) defects.push(`${at} is a ${definition.type} classified ${operation.classification}; a query is a READ and a mutation a WRITE`);
418
+
419
+ const fields = operation.inputSchema === undefined ? undefined : inputSchemaTopLevelFields(operation.inputSchema);
420
+ if (operation.inputSchema !== undefined && fields === undefined) {
421
+ defects.push(`${at} has an inputSchema that is not an object, and its input is the document's variables`);
422
+ }
423
+ if (fields !== undefined) {
424
+ for (const variable of definition.variables) {
425
+ if (!fields.has(variable)) defects.push(`${at} declares the variable '$${variable}', which its inputSchema does not declare`);
426
+ }
427
+ for (const field of fields) {
428
+ if (!definition.variables.includes(field)) defects.push(`${at}: its inputSchema declares '${field}', which is no variable of the document, so a value for it would never be sent`);
429
+ }
430
+ }
431
+ return defects;
432
+ }
433
+
434
+ /** The variables a GraphQL operation's document declares, or `undefined` when the document cannot be read. */
435
+ export function providerGraphqlOperationVariables(graphql: ProviderRestOperationGraphql): readonly string[] | undefined {
436
+ const shape = readProviderGraphqlDocument(graphql.document);
437
+ if (shape.defect !== undefined) return undefined;
438
+ return shape.operations.find((candidate) => candidate.name === graphql.operationName)?.variables;
439
+ }
440
+
441
+ /** What a GraphQL answer says about the call. See the table in this module's header. */
442
+ export enum ProviderGraphqlResponseOutcomeKind {
443
+ /** `data` is an object and no error was reported. */
444
+ SUCCEEDED = 'succeeded',
445
+ /** Errors, and no `data` entry: the request was refused before anything executed. Nothing was applied. */
446
+ REQUEST_ERROR = 'request_error',
447
+ /** Errors beside a `data` entry (null or partial): execution began and something failed. */
448
+ EXECUTION_ERROR = 'execution_error',
449
+ /** Neither a `data` object nor an error list: the answer does not state what happened. */
450
+ UNSTATED = 'unstated',
451
+ /**
452
+ * `data` and no `errors`, and the mutation's payload states the vendor refused it (its declared `payloadRefusal`): the
453
+ * write was not done, as the vendor says (follow-up to #3392).
454
+ */
455
+ PAYLOAD_REFUSED = 'payload_refused',
456
+ }
457
+
458
+ /** What {@link readProviderGraphqlResponse} read. */
459
+ export interface ProviderGraphqlResponseVerdict {
460
+ readonly kind: ProviderGraphqlResponseOutcomeKind;
461
+ /** On SUCCEEDED, the answer's `data` object: what the operation's `resultPath` and `outputSchema` read. */
462
+ readonly data?: Readonly<Record<string, unknown>>;
463
+ /**
464
+ * The vendor's error messages, in its order, at most {@link PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGES}, each cut at
465
+ * {@link PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGE_LENGTH} characters. Vendor prose: it may quote what the call sent, so it
466
+ * travels to the caller and is never written to a log or an audit row by the engine.
467
+ */
468
+ readonly errorMessages?: readonly string[];
469
+ /** The first code-shaped value at the operation's `errorCodePath` among the errors, when one is declared and found. */
470
+ readonly errorCode?: string;
471
+ }
472
+
473
+ /** The value at a dot path, read through own properties only (an array's index is an own property), or `undefined`. */
474
+ function readGraphqlDotPath(value: unknown, path: string): unknown {
475
+ let current: unknown = value;
476
+ for (const segment of path.split('.')) {
477
+ if (current === null || typeof current !== 'object' || !Object.hasOwn(current, segment)) return undefined;
478
+ current = (current as Record<string, unknown>)[segment];
479
+ }
480
+ return current;
481
+ }
482
+
483
+ function readGraphqlErrorCode(error: unknown, errorCodePath: string): string | undefined {
484
+ const current = readGraphqlDotPath(error, errorCodePath);
485
+ return typeof current === 'string' && PROVIDER_VENDOR_ERROR_CODE_SHAPE.test(current) ? current : undefined;
486
+ }
487
+
488
+ /** A vendor message as the verdict keeps it: cut at {@link PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGE_LENGTH}. */
489
+ function keptGraphqlMessage(message: string): string {
490
+ return message.length > PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGE_LENGTH ? `${message.slice(0, PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGE_LENGTH)}…` : message;
491
+ }
492
+
493
+ /**
494
+ * The refusal a mutation's payload states, read as its declaration says ({@link ProviderGraphqlPayloadRefusal}), or
495
+ * `undefined` when the payload refuses nothing.
496
+ */
497
+ function readGraphqlPayloadRefusal(
498
+ data: Readonly<Record<string, unknown>>,
499
+ refusal: ProviderGraphqlPayloadRefusal,
500
+ ): Pick<ProviderGraphqlResponseVerdict, 'errorMessages' | 'errorCode'> | undefined {
501
+ const stated = readGraphqlDotPath(data, refusal.path);
502
+ if (refusal.kind === ProviderGraphqlPayloadRefusalKind.SUCCESS_FLAG) {
503
+ return stated === false ? { errorMessages: [`the answer's ${refusal.path} is false: the vendor did not do the write`] } : undefined;
504
+ }
505
+ if (!Array.isArray(stated) || stated.length === 0) return undefined;
506
+ const errorMessages = stated.slice(0, PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGES).map((entry) => {
507
+ const message = readGraphqlDotPath(entry, refusal.messagePath ?? 'message');
508
+ const field = refusal.fieldPath === undefined ? undefined : readGraphqlDotPath(entry, refusal.fieldPath);
509
+ const fieldText = typeof field === 'string' ? field
510
+ : Array.isArray(field) && field.every((segment) => typeof segment === 'string' || typeof segment === 'number') ? field.join('.') : undefined;
511
+ const text = typeof message === 'string' ? message : 'the vendor refused the write without a message';
512
+ return keptGraphqlMessage(fieldText === undefined || fieldText.length === 0 ? text : `${fieldText}: ${text}`);
513
+ });
514
+ const errorCode = refusal.codePath === undefined ? undefined
515
+ : stated.map((entry) => readGraphqlErrorCode(entry, refusal.codePath!)).find((code) => code !== undefined);
516
+ return { errorMessages, ...(errorCode === undefined ? {} : { errorCode }) };
517
+ }
518
+
519
+ /**
520
+ * Reads a parsed GraphQL answer (#3392). The ONE reader: the engine's transport, for a 2xx and a non-2xx answer alike,
521
+ * and every test go through it. See the module header for the rule and its sources.
522
+ */
523
+ export function readProviderGraphqlResponse(
524
+ body: unknown,
525
+ errorCodePath?: string,
526
+ payloadRefusal?: ProviderGraphqlPayloadRefusal,
527
+ ): ProviderGraphqlResponseVerdict {
528
+ if (body === null || typeof body !== 'object' || Array.isArray(body)) return { kind: ProviderGraphqlResponseOutcomeKind.UNSTATED };
529
+ const answer = body as Record<string, unknown>;
530
+ const errors = Object.hasOwn(answer, 'errors') ? answer.errors : undefined;
531
+ if (errors !== undefined && errors !== null && !Array.isArray(errors)) return { kind: ProviderGraphqlResponseOutcomeKind.UNSTATED };
532
+ if (Array.isArray(errors) && errors.length > 0) {
533
+ const errorMessages = errors
534
+ .map((error) => (error !== null && typeof error === 'object' && typeof (error as { message?: unknown }).message === 'string' ? (error as { message: string }).message : undefined))
535
+ .filter((message): message is string => message !== undefined)
536
+ .slice(0, PROVIDER_GRAPHQL_MAXIMUM_ERROR_MESSAGES)
537
+ .map(keptGraphqlMessage);
538
+ const errorCode = errorCodePath === undefined ? undefined
539
+ : errors.map((error) => readGraphqlErrorCode(error, errorCodePath)).find((code) => code !== undefined);
540
+ return {
541
+ kind: Object.hasOwn(answer, 'data') ? ProviderGraphqlResponseOutcomeKind.EXECUTION_ERROR : ProviderGraphqlResponseOutcomeKind.REQUEST_ERROR,
542
+ errorMessages,
543
+ ...(errorCode === undefined ? {} : { errorCode }),
544
+ };
545
+ }
546
+ const data = Object.hasOwn(answer, 'data') ? answer.data : undefined;
547
+ if (data === null || typeof data !== 'object' || Array.isArray(data)) return { kind: ProviderGraphqlResponseOutcomeKind.UNSTATED };
548
+ const refused = payloadRefusal === undefined ? undefined : readGraphqlPayloadRefusal(data as Record<string, unknown>, payloadRefusal);
549
+ if (refused !== undefined) return { kind: ProviderGraphqlResponseOutcomeKind.PAYLOAD_REFUSED, ...refused };
550
+ return { kind: ProviderGraphqlResponseOutcomeKind.SUCCEEDED, data: data as Record<string, unknown> };
551
+ }
552
+ ```
553
+
554
+ ### Origin Package: `@wildo-ai/external-connectors-models`
555
+
21
556
  ```typescript
22
557
  /** Where a declared parameter rides on the wire. */
23
558
  export enum ProviderRestParameterLocation {
@@ -62,6 +597,21 @@ export enum ProviderRestResponseDecoding {
62
597
  TEXT = 'text',
63
598
  /** Read nothing — a write whose answer carries no information (a 204). The output is `undefined`. */
64
599
  NONE = 'none',
600
+ /**
601
+ * Keep the raw bytes — a signed PDF, an evidence container (#2910). Requires `binaryResponse` (a byte ceiling and the
602
+ * accepted media types); the output is `{ bytes, contentType }`. The bytes are the vendor's, unscanned: do not relay
603
+ * them to a person or write them as a file yourself. Keep one through `ProviderDocumentFileWriterBackendService`
604
+ * (`@wildo-ai/saas-backend-lib`, #2963), which stores it as a scanned file (`scan: REQUIRED`) whatever the caller asks.
605
+ */
606
+ BINARY = 'binary',
607
+ }
608
+
609
+ /** The bounds a {@link ProviderRestResponseDecoding.BINARY} answer is read under (#2910). Both mandatory. */
610
+ export interface ProviderRestBinaryResponse {
611
+ /** The most bytes the vendor's answer may hold. Enforced while streaming; a larger answer is refused, never truncated. */
612
+ readonly maxBytes: number;
613
+ /** Media types accepted (`application/pdf`), compared on the type alone, case-insensitively. */
614
+ readonly acceptedContentTypes: readonly string[];
65
615
  }
66
616
 
67
617
  /**
@@ -93,6 +643,27 @@ export interface ProviderRestOperationParameter {
93
643
  readonly required?: boolean;
94
644
  /** A literal value sent on every call — for a version pin or a fixed format selector. */
95
645
  readonly constantValue?: string;
646
+ /**
647
+ * PATH only (#2663): the value may hold several `/`-separated segments, each percent-encoded on its own, instead of
648
+ * one segment whose `/` is encoded. For a vendor that routes per region or tenant inside ONE origin: the Bot
649
+ * Connector's `serviceUrl` is `https://smba.trafficmanager.net/<region>/…`, and an operation's path begins with that
650
+ * region path. Empty segments, `.` and `..` are refused, so the value moves the path within the base origin and never
651
+ * above it; the origin itself cannot move, as for every path value.
652
+ */
653
+ readonly multiSegment?: true;
654
+ /**
655
+ * PATH only (#3397): the value is the CONNECTION's vendor-reported fact of this name, never the caller's input. Every
656
+ * QuickBooks path is `/v3/company/{realmId}/…`, and the company is the one the person connected, so asking each caller
657
+ * for it would let a call name a company its connection was not made for and leave every application re-typing it.
658
+ *
659
+ * The fact must be declared on the connection's OAuth2 contract with a
660
+ * {@link ProviderOAuth2ReportedAccountFact.pathSegmentPattern}; the access resolver re-admits the stored value on every
661
+ * call and hands it to the request compiler, which fills nothing else from it. A caller value under the same input
662
+ * name is refused rather than ignored, and the operation's `inputSchema` must not declare one
663
+ * ({@link describeProviderRestOperationConnectionFactDefects}). Exclusive with `from`, `constantValue` and
664
+ * `multiSegment`.
665
+ */
666
+ readonly connectionFact?: string;
96
667
  readonly description?: string;
97
668
  }
98
669
 
@@ -164,11 +735,146 @@ export interface ProviderRestOperationInputOptions {
164
735
  /** Dot-path, inside each listed item, to the text a person reads (`name`). Vendor content, never derived from the value. */
165
736
  readonly labelPath: string;
166
737
  /**
167
- * Inputs the options depend on: `{ <options-operation input field>: <this operation's input field> }`.
738
+ * Inputs the options depend on: `{ <options-operation input field>: <this operation's input field PATH> }`.
739
+ * The value side is a dot path into this operation's input, like the `inputOptions` key (#3399): Jira's issue
740
+ * types depend on `project.key`. The key side is a top-level field of the options operation's own input.
168
741
  * A choice that is not yet made is REFUSED by name rather than listed as empty — "no projects" and
169
742
  * "choose a workspace first" are different answers, and only one of them is true.
170
743
  */
171
744
  readonly dependsOn?: Readonly<Record<string, string>>;
745
+ /**
746
+ * Fixed values the options operation is called with, beside what `dependsOn` forwards (#3399): Jira lists only the
747
+ * projects a person may create in (`action: 'create'`), Box lists the root folder (`folder_id: '0'`). A field may
748
+ * not be both fixed and forwarded.
749
+ */
750
+ readonly input?: Readonly<Record<string, string | number | boolean>>;
751
+ /**
752
+ * Dot path, inside the options operation's output, to the listed items, when that output is an object rather than the
753
+ * list itself (#3399): QuickBooks answers a query as `{ Customer: [...] }`, Box a folder as `{ entries: [...] }`. An
754
+ * object without that path lists nothing, which is how QuickBooks answers a query with no rows; anything else at the
755
+ * path that is not a list is an unreadable answer. Absent, the output itself must be the list.
756
+ */
757
+ readonly itemsPath?: string;
758
+ /**
759
+ * Keeps only the listed items whose value at each dot path equals the given text (#3399): a folder's items are files,
760
+ * folders and web links, and only a folder can be a parent (`{ type: 'folder' }`). Absent, every item is a choice.
761
+ */
762
+ readonly itemWhere?: Readonly<Record<string, string>>;
763
+ }
764
+
765
+ /**
766
+ * The schema a dot path into an operation's input names, or `undefined` when a segment names no declared field (#3399).
767
+ *
768
+ * Walked through Zod's own definition (`_zod.def`), not `instanceof`: a provider module may be built against another
769
+ * copy of Zod than the host's. Wrappers that leave the value's shape alone (optional, nullable, default, prefault,
770
+ * readonly, catch, nonoptional, a pipe's input, a lazy getter) are seen through. A union names the field when any of its
771
+ * options declares it, as a discriminated body does. Only an object's DECLARED fields count: a loose object admits other
772
+ * keys at runtime, and a picker for a key nobody declared is the typo this check exists to refuse.
773
+ */
774
+ function providerRestInputSchemaAtPath(schema: unknown, segments: readonly string[]): unknown {
775
+ let current: unknown = schema;
776
+ for (let depth = 0; depth < 64; depth += 1) {
777
+ const def = (current as { _zod?: { def?: Record<string, unknown> } } | undefined)?._zod?.def;
778
+ if (def === undefined) return undefined;
779
+ switch (def.type) {
780
+ case 'optional': case 'nullable': case 'default': case 'prefault': case 'readonly': case 'catch': case 'nonoptional':
781
+ current = def.innerType;
782
+ continue;
783
+ case 'pipe':
784
+ current = def.in;
785
+ continue;
786
+ case 'lazy':
787
+ current = typeof def.getter === 'function' ? (def.getter as () => unknown)() : undefined;
788
+ continue;
789
+ case 'union': {
790
+ if (segments.length === 0) return current;
791
+ const options = Array.isArray(def.options) ? def.options : [];
792
+ return options.map((option) => providerRestInputSchemaAtPath(option, segments)).find((found) => found !== undefined);
793
+ }
794
+ case 'object': {
795
+ if (segments.length === 0) return current;
796
+ const shape = def.shape as Record<string, unknown> | undefined;
797
+ const [head, ...rest] = segments;
798
+ if (shape === undefined || head === undefined || !Object.hasOwn(shape, head)) return undefined;
799
+ return providerRestInputSchemaAtPath(shape[head], rest);
800
+ }
801
+ default:
802
+ return segments.length === 0 ? current : undefined;
803
+ }
804
+ }
805
+ return undefined;
806
+ }
807
+
808
+ /**
809
+ * Why an operation's `inputOptions` cannot be honoured, or an empty list (#3399). Each key, and each `dependsOn` value,
810
+ * is a dot path into the operation's input (`project.key`, `CustomerRef.value`; a top-level field is a one-segment
811
+ * path), and must name a field the operation's `inputSchema` declares. Checked where a catalogue loads (the operation
812
+ * executor, an augmentation or supplement merge) and at publish, so a mistyped path is refused once, by name, instead of
813
+ * offering a picker that fills nothing. An operation without an `inputSchema` passes its input through unvalidated and
814
+ * declares no fields, so there is nothing to check its paths against; only their shape is.
815
+ */
816
+ export function describeProviderRestOperationInputOptionsDefects(operation: Pick<ProviderRestOperation, 'operationId' | 'inputSchema' | 'inputOptions'>): string[] {
817
+ const defects: string[] = [];
818
+ const check = (path: string, role: string) => {
819
+ const segments = path.split('.');
820
+ if (segments.some((segment) => segment.length === 0)) {
821
+ defects.push(`operation '${operation.operationId}': ${role} '${path}' is not a dot path of field names`);
822
+ return;
823
+ }
824
+ if (operation.inputSchema !== undefined && providerRestInputSchemaAtPath(operation.inputSchema, segments) === undefined) {
825
+ defects.push(`operation '${operation.operationId}': ${role} '${path}' names no field of its inputSchema`);
826
+ }
827
+ };
828
+ for (const [inputPath, declaration] of Object.entries(operation.inputOptions ?? {})) {
829
+ check(inputPath, 'the inputOptions key');
830
+ for (const sourcePath of Object.values(declaration.dependsOn ?? {})) check(sourcePath, `the dependsOn of '${inputPath}'`);
831
+ for (const fixed of Object.keys(declaration.input ?? {})) {
832
+ if (Object.hasOwn(declaration.dependsOn ?? {}, fixed)) {
833
+ defects.push(`operation '${operation.operationId}': the options of '${inputPath}' both fix and forward '${fixed}'`);
834
+ }
835
+ }
836
+ for (const listPath of [declaration.itemsPath, ...Object.keys(declaration.itemWhere ?? {})]) {
837
+ if (listPath !== undefined && listPath.split('.').some((segment) => segment.length === 0)) {
838
+ defects.push(`operation '${operation.operationId}': the options of '${inputPath}' name '${listPath}', which is not a dot path`);
839
+ }
840
+ }
841
+ }
842
+ return defects;
843
+ }
844
+
845
+ /**
846
+ * Why an operation's {@link ProviderRestOperationParameter.connectionFact} parameters cannot be honoured, or an empty
847
+ * list (#3397). Each must be a PATH parameter the path template uses, fed by nothing else (no `from`, `constantValue` or
848
+ * `multiSegment`), and the operation's `inputSchema` must not declare a field of its name: a caller is never asked for a
849
+ * value the connection supplies, and one it sends anyway is refused at the call. With `reportedAccountFacts` (the
850
+ * connection's OAuth2 declaration), each named fact must also be declared there with a `pathSegmentPattern`; without
851
+ * it the request compiler refuses the call, so a module walk passes them to catch it before any call.
852
+ */
853
+ export function describeProviderRestOperationConnectionFactDefects(
854
+ operation: Pick<ProviderRestOperation, 'operationId' | 'pathTemplate' | 'parameters' | 'inputSchema'>,
855
+ reportedAccountFacts?: Readonly<Record<string, ProviderOAuth2ReportedAccountFact>>,
856
+ ): string[] {
857
+ const defects: string[] = [];
858
+ for (const parameter of operation.parameters ?? []) {
859
+ const factName = parameter.connectionFact;
860
+ if (factName === undefined) continue;
861
+ const at = `operation '${operation.operationId}': the parameter '${parameter.name}' filled from the connection fact '${factName}'`;
862
+ if (parameter.in !== ProviderRestParameterLocation.PATH) defects.push(`${at} is a ${parameter.in} parameter; only a PATH value may come from a connection fact`);
863
+ if (parameter.from !== undefined || parameter.constantValue !== undefined || parameter.multiSegment !== undefined) {
864
+ defects.push(`${at} also declares from, constantValue or multiSegment; its value comes from the connection alone`);
865
+ }
866
+ if (!operation.pathTemplate.includes(`{${parameter.name}}`)) defects.push(`${at} fills no '{${parameter.name}}' token of the path template`);
867
+ if (operation.inputSchema !== undefined && providerRestInputSchemaAtPath(operation.inputSchema, [parameter.name]) !== undefined) {
868
+ defects.push(`${at} is also declared by the inputSchema, which would ask callers for a value the connection supplies`);
869
+ }
870
+ if (reportedAccountFacts !== undefined) {
871
+ const fact = Object.hasOwn(reportedAccountFacts, factName) ? reportedAccountFacts[factName] : undefined;
872
+ if (fact?.pathSegmentPattern === undefined) {
873
+ defects.push(`${at}: the connection's OAuth2 contract declares no reported fact '${factName}' with a pathSegmentPattern`);
874
+ }
875
+ }
876
+ }
877
+ return defects;
172
878
  }
173
879
 
174
880
  /**
@@ -186,6 +892,19 @@ export interface ProviderRestOperation {
186
892
  readonly method: API_HttpMethod;
187
893
  /** Relative to the provider's base URL. `{token}` interpolates a PATH parameter of that name. */
188
894
  readonly pathTemplate: string;
895
+ /**
896
+ * The API host this operation is served on, when it is not the base URL's host (#2546): an exact lower-case DNS name,
897
+ * always https. The request is then `https://<host><pathTemplate>`; the base URL's path is not prepended, since it
898
+ * belongs to the base's host. Absent, which is the norm, the request is `<baseUrl><pathTemplate>`.
899
+ *
900
+ * Admitted only where the token the call already carries is valid: the connection's OAuth2 client declares
901
+ * `audiences`, and the audience that admits the base URL's host admits this host too. So no second token is minted
902
+ * and no token reaches a host outside its own resource ({@link describeProviderRestOperationHostDefect}). This is
903
+ * Google's shape: one grant serves every `*.googleapis.com` API, and a Gmail operation names `gmail.googleapis.com`
904
+ * on the one Google connection. Microsoft's Dataverse is not this shape: its token is a different audience's, so it
905
+ * stays a provider of its own sharing the connection.
906
+ */
907
+ readonly host?: string;
189
908
  readonly summary?: string;
190
909
  /**
191
910
  * Whether the operation MUTATES the vendor.
@@ -227,6 +946,8 @@ export interface ProviderRestOperation {
227
946
  * validates the string.
228
947
  */
229
948
  readonly responseDecoding?: ProviderRestResponseDecoding;
949
+ /** Required with `responseDecoding: BINARY`, refused with any other decoding (#2910). */
950
+ readonly binaryResponse?: ProviderRestBinaryResponse;
230
951
  /** Dot-path to the payload inside the response body. Absent = the body IS the payload. JSON answers only. */
231
952
  readonly resultPath?: string;
232
953
  readonly pagination?: ProviderRestOperationPagination;
@@ -257,10 +978,19 @@ export interface ProviderRestOperation {
257
978
  /** Narrows the provider's semantics for this one operation (a slow export, a tight endpoint). */
258
979
  readonly remoteCallSemantics?: Partial<ProviderRestCallSemantics>;
259
980
  /**
260
- * Where each input's choices come from, keyed by INPUT field name. Absent for an input a caller types.
261
- * See {@link ProviderRestOperationInputOptions}.
981
+ * Where each input's choices come from, keyed by a dot PATH into the input (#3399): `workspace` for a top-level
982
+ * field, `project.key` or `CustomerRef.value` for the value a vendor nests inside a reference object. Absent for an
983
+ * input a caller types. Every path must name a field of `inputSchema`
984
+ * ({@link describeProviderRestOperationInputOptionsDefects}). See {@link ProviderRestOperationInputOptions}.
262
985
  */
263
986
  readonly inputOptions?: Readonly<Record<string, ProviderRestOperationInputOptions>>;
987
+ /**
988
+ * Present for a GraphQL operation (#3392): the provider-owned document the call sends to `pathTemplate` (the vendor's
989
+ * GraphQL endpoint), with the operation's input as its variables. A 2xx answer carrying `errors` fails the call; the
990
+ * output is read from the answer's `data`. See {@link ProviderRestOperationGraphql} for what such an operation may and
991
+ * may not declare beside it.
992
+ */
993
+ readonly graphql?: ProviderRestOperationGraphql;
264
994
  /** Set when the vendor has deprecated it; the executor logs once per operation, never refuses. */
265
995
  readonly deprecated?: {
266
996
  readonly reason: string;
@@ -297,4 +1027,545 @@ export interface ProviderRestOperationContributor {
297
1027
  /** The installed version of that package, as `wildo config sync` read it from the manifest. */
298
1028
  readonly packageVersion: string;
299
1029
  }
1030
+
1031
+ /**
1032
+ * How a vendor states, INSIDE a successful HTTP answer, whether the call it answered succeeded (#2661).
1033
+ *
1034
+ * Most vendors say it with the status: a 4xx or 5xx is a failure, and the transport already treats it as one. Some
1035
+ * answer HTTP 200 for every call they could parse and put the verdict in the body. Slack's Web API is the case:
1036
+ * "All Web API responses contain a JSON object, which will always contain a top-level boolean property `ok` that
1037
+ * indicates success or failure", and "For failure results, the `error` property will contain a short machine-readable
1038
+ * error code".
1039
+ * spec-cite: https://docs.slack.dev/apis/web-api/ — "Evaluating responses", fetched 2026-10-06.
1040
+ *
1041
+ * Without this declaration such an answer reads as a success: `channel_not_found` is returned to the caller as if it
1042
+ * were a posted message, the call's audit row says it succeeded, and a revoked token stays "accepted" on the
1043
+ * credential. Declared on the provider's REST contract (`rest.applicationOutcome`), because the envelope is a fact
1044
+ * about the vendor's API, not about one operation.
1045
+ *
1046
+ * Read for JSON answers only: an operation declaring `TEXT` or `NONE` decoding (a file download) has no envelope.
1047
+ */
1048
+ export interface ProviderRestApplicationOutcome {
1049
+ /** Dot-path to the boolean the vendor sets `true` exactly when the call succeeded (Slack: `ok`). */
1050
+ readonly successFlagPath: string;
1051
+ /** Dot-path to the vendor's machine-readable error code on a failed call (Slack: `error`). */
1052
+ readonly errorCodePath: string;
1053
+ /**
1054
+ * The error codes that mean the vendor refused the CREDENTIAL itself, rather than the request: the stored
1055
+ * credential is then recorded as rejected, the way the vendor's answer said (Slack: `invalid_auth`,
1056
+ * `account_inactive`, `token_revoked`, `token_expired`). A code that means the caller sent no credential at all
1057
+ * (Slack's `not_authed`) does not belong here: that is our request's fault, not a dead credential.
1058
+ */
1059
+ readonly credentialRefusedErrorCodes?: readonly string[];
1060
+ }
1061
+
1062
+ /** What a successful HTTP answer said about the call, read through a {@link ProviderRestApplicationOutcome}. */
1063
+ export enum ProviderRestApplicationOutcomeKind {
1064
+ /** The success flag is `true`. */
1065
+ SUCCEEDED = 'succeeded',
1066
+ /** The success flag is `false`: the vendor refused the call, naming why at the error path when it could. */
1067
+ REFUSED = 'refused',
1068
+ /** The flag is absent or not a boolean: the answer does not carry the envelope its provider declares. */
1069
+ UNSTATED = 'unstated',
1070
+ }
1071
+
1072
+ /** The verdict a body carries. `errorCode` is kept only when it is a code-shaped string, never prose. */
1073
+ export type ProviderRestApplicationOutcomeVerdict =
1074
+ | { readonly kind: ProviderRestApplicationOutcomeKind.SUCCEEDED }
1075
+ | { readonly kind: ProviderRestApplicationOutcomeKind.REFUSED; readonly errorCode?: string }
1076
+ | { readonly kind: ProviderRestApplicationOutcomeKind.UNSTATED };
1077
+
1078
+ /**
1079
+ * A vendor error code as the engine may carry it: identifier characters only, at most 128. A value of any other shape
1080
+ * is dropped rather than carried, because it travels to audit rows, logs and API answers, and a vendor that puts a
1081
+ * sentence (or request data) where a code belongs must not have it repeated there.
1082
+ */
1083
+ export const PROVIDER_VENDOR_ERROR_CODE_SHAPE = /^[A-Za-z0-9_.:-]{1,128}$/;
1084
+
1085
+ /**
1086
+ * The defects of a declared outcome envelope, refused at boot: an empty path, and a credential-refusal code that is not
1087
+ * code-shaped, which the transport would never carry and so would never match (#2661 review L7).
1088
+ */
1089
+ export function describeProviderRestApplicationOutcomeDefects(outcome: ProviderRestApplicationOutcome): string[] {
1090
+ const defects: string[] = [];
1091
+ const path = /^[A-Za-z0-9_]+(\.[A-Za-z0-9_]+)*$/;
1092
+ if (!path.test(outcome.successFlagPath)) defects.push(`applicationOutcome.successFlagPath '${outcome.successFlagPath}' is not a dot-path`);
1093
+ if (!path.test(outcome.errorCodePath)) defects.push(`applicationOutcome.errorCodePath '${outcome.errorCodePath}' is not a dot-path`);
1094
+ for (const code of outcome.credentialRefusedErrorCodes ?? []) {
1095
+ if (!PROVIDER_VENDOR_ERROR_CODE_SHAPE.test(code)) {
1096
+ defects.push(`applicationOutcome.credentialRefusedErrorCodes names '${code}', which is not code-shaped and would never match a code the transport keeps`);
1097
+ }
1098
+ }
1099
+ return defects;
1100
+ }
1101
+
1102
+ /**
1103
+ * The placeholder a client-credentials token URL may carry for the tenant the credential belongs to:
1104
+ * `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token`. Filled from the connection's
1105
+ * {@link ProviderRestClientCredentials.tenantSecretRef} slot, never from a request.
1106
+ */
1107
+ export const PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER = '{tenant}';
1108
+
1109
+ /** A tenant value the token URL admits: a GUID or a DNS name. Nothing that can leave the URL's path segment. */
1110
+ export const PROVIDER_CLIENT_CREDENTIALS_TENANT_SHAPE = /^[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?$/;
1111
+
1112
+ /**
1113
+ * The placeholder that BEGINS a client-credentials token URL whose token endpoint is on the deployment's own vendor
1114
+ * instance (#3402): `{deploymentOrigin}/oauth2/v1/token`. Filled with the ORIGIN of the base URL the engine resolved for
1115
+ * the REST contract (from `baseUrlHostEnvVarName` or `baseUrlEnvVarName`), never from a connection or a request.
1116
+ *
1117
+ * Okta is the case: every org has its own host (`<org>.okta.com`, or a custom domain), and its org authorization server's
1118
+ * token endpoint is on that host. A fixed {@link ProviderRestClientCredentials.tokenHosts} list cannot admit a host only
1119
+ * the operator knows, and a `{tenant}` value would be a second, separately typed copy of the host the operations already
1120
+ * go to, which could disagree with it. Filling the token endpoint from the SAME resolved origin keeps them one value: the
1121
+ * client's assertion is sent to the host the operator named, and to nothing a person connecting could choose.
1122
+ *
1123
+ * spec-cite: Okta Developer, "Implement OAuth for Okta with a service app"
1124
+ * (https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/, fetched 2026-11-10) — the token
1125
+ * request is `POST https://{yourOktaDomain}/oauth2/v1/token`, and the assertion's `aud` is that URL.
1126
+ */
1127
+ export const PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER = '{deploymentOrigin}';
1128
+
1129
+ /** What a {@link ProviderClientCredentialsVerifiedFact} records: a value the person typed and the vendor accepted. */
1130
+ export enum ProviderClientCredentialsFactSource {
1131
+ /** The client id the token endpoint issued a token for: Microsoft's bot App ID. */
1132
+ CLIENT_ID = 'client_id',
1133
+ /** The tenant whose token endpoint issued it. */
1134
+ TENANT = 'tenant',
1135
+ }
1136
+
1137
+ /**
1138
+ * One fact a client-credentials connection records once the vendor has accepted its credential. See
1139
+ * {@link ProviderRestClientCredentials.verifiedAccountFacts}.
1140
+ */
1141
+ export interface ProviderClientCredentialsVerifiedFact {
1142
+ readonly source: ProviderClientCredentialsFactSource;
1143
+ /**
1144
+ * `true` when the inbound receiver routes deliveries to an organization by this fact: an organization's own Teams
1145
+ * bot, by its App ID (#2663). Such a fact may name ONE organization only, so a connect whose value another
1146
+ * organization's enabled connection holds is refused, as for a vendor-reported fact.
1147
+ */
1148
+ readonly routesInboundDeliveries?: true;
1149
+ /**
1150
+ * `true` when the vendor treats the value without case, as Microsoft does an App ID or a tenant id (both GUIDs): the
1151
+ * value is recorded LOWER-CASED, so a lookup by the vendor's own spelling (a token's `aud`) finds an id the
1152
+ * administrator typed in capitals (#2663). Never for a value the vendor compares exactly, which most client ids are.
1153
+ */
1154
+ readonly caseInsensitive?: true;
1155
+ }
1156
+
1157
+ /**
1158
+ * A REST provider whose access token is minted with the OAuth 2.0 client-credentials grant, from a client id and
1159
+ * secret the connection holds (#2663). The Bot Framework is the first: a Teams bot's App ID and secret, and for a
1160
+ * single-tenant bot the tenant it is registered in, mint a token for `https://api.botframework.com/.default`.
1161
+ *
1162
+ * Declared beside `oauth2` (#3398), it is the APPLICATION's own connection: Box's client-credentials grant and Zoom's
1163
+ * server-to-server OAuth renew the application's token while people and organizations connect through the exchange.
1164
+ * {@link providerClientCredentialsServesOwnerScope} says which door a connection takes.
1165
+ *
1166
+ * The token is minted per call when no unexpired one is cached, never stored, and attached where
1167
+ * {@link ProviderProtocolRuntimeContract}'s `apiKey` says, so (with no `oauth2` beside it) `apiKey.secretRef` names the
1168
+ * client's credential, its SECRET or its private key (#3402), the slot whose absence means "not configured". The
1169
+ * client id, credential and tenant are read from the connection: the
1170
+ * application's own environment for an APPLICATION connection, the organization's typed credential for an
1171
+ * ORGANIZATION one.
1172
+ *
1173
+ * The client id and tenant of an ORGANIZATION connection are typed by its administrator, so on their own they prove
1174
+ * nothing. They become evidence when the vendor accepts them: at connect the engine mints a token with the typed
1175
+ * values, refuses the connection when the vendor refuses, and records each {@link verifiedAccountFacts} entry as
1176
+ * `VERIFIED_BY_VENDOR`. A bot App ID then routes deliveries only to the organization that holds its secret.
1177
+ *
1178
+ * spec-cite: RFC 6749 §4.4 — the client credentials grant (`grant_type=client_credentials`, client authentication,
1179
+ * `scope`); Microsoft, "Authenticate requests with the Bot Connector API" — the single-tenant token request
1180
+ * `POST https://login.microsoftonline.com/MICROSOFT-TENANT-ID/oauth2/v2.0/token` with the scope
1181
+ * `https://api.botframework.com/.default`, fetched 2026-10-06.
1182
+ */
1183
+ export interface ProviderRestClientCredentials {
1184
+ /**
1185
+ * The https token endpoint. May carry {@link PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}, or BEGIN with
1186
+ * {@link PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} when the token endpoint is on the deployment's own
1187
+ * vendor instance (Okta's org, #3402).
1188
+ */
1189
+ readonly tokenUrl: string;
1190
+ /**
1191
+ * The hosts the token endpoint may be on once filled. The client secret is sent nowhere else. EMPTY exactly when the
1192
+ * token URL begins with {@link PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}: its host is the one the
1193
+ * operator named for the operations, and no fixed list can name it.
1194
+ */
1195
+ readonly tokenHosts: readonly string[];
1196
+ /**
1197
+ * The `scope` parameter, sent as written. Omitted, no `scope` is sent: RFC 6749 makes it optional, and Box, Zoom and
1198
+ * Salesforce grant the scopes configured on the app instead (#3398).
1199
+ * spec-cite: RFC 6749 §4.4.2 — `scope`: "OPTIONAL. The scope of the access request as described by Section 3.3."
1200
+ * Fetched 2026-10-06.
1201
+ */
1202
+ readonly scope?: string;
1203
+ /**
1204
+ * The `grant_type` sent. Omitted, `client_credentials` (RFC 6749 §4.4). See {@link ProviderClientCredentialsGrantType}.
1205
+ */
1206
+ readonly grantType?: ProviderClientCredentialsGrantType;
1207
+ /**
1208
+ * Further parameters of the token request a vendor requires, by name: a fixed value, or one read from a slot of the
1209
+ * connection (#3398). Box's client-credentials grant names the subject it authenticates as (`box_subject_type`,
1210
+ * `box_subject_id`); Zoom's server-to-server grant names the account (`account_id`). A parameter the grant itself
1211
+ * defines (`grant_type`, `client_id`, `client_secret`, `scope`, the client assertion) is refused here: each has its own
1212
+ * field. See {@link ProviderClientCredentialsTokenRequestParameter}.
1213
+ */
1214
+ readonly tokenRequestParameters?: Readonly<Record<string, ProviderClientCredentialsTokenRequestParameter>>;
1215
+ /**
1216
+ * How the client authenticates to the token endpoint. Omitted,
1217
+ * {@link ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_POST} with a client secret: the id and secret in the
1218
+ * body, as Microsoft's identity platform documents. {@link ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_BASIC}
1219
+ * sends them in the Basic header only (Zoom's server-to-server OAuth documents nothing else). With
1220
+ * {@link privateKeyJwt} the method is {@link ProviderOAuth2ClientAuthenticationMethod.PRIVATE_KEY_JWT}, implied when
1221
+ * omitted (#3402).
1222
+ */
1223
+ readonly tokenEndpointAuthMethod?: ProviderOAuth2ClientAuthenticationMethod;
1224
+ /** The slot holding the client id. */
1225
+ readonly clientIdSecretRef: string;
1226
+ /**
1227
+ * The slot holding the client secret. Exactly one of this and {@link privateKeyJwt} (#3402): a client authenticates
1228
+ * with a shared secret or with a key it alone holds, never both. The client's CREDENTIAL slot (this one, or the
1229
+ * private key's) equals the contract's `apiKey.secretRef` when the contract declares no `oauth2` (the slot whose
1230
+ * absence means "not configured"); beside `oauth2`, `apiKey.secretRef` is the slot of the people's and organizations'
1231
+ * minted tokens and this one serves the application alone.
1232
+ */
1233
+ readonly clientSecretSecretRef?: string;
1234
+ /**
1235
+ * The client authenticates with a JWT it signs with its own private key (`private_key_jwt`, #3402) instead of a
1236
+ * secret: Okta's OAuth service apps accept nothing else for the Management API. See
1237
+ * {@link ProviderClientCredentialsPrivateKeyJwt}.
1238
+ */
1239
+ readonly privateKeyJwt?: ProviderClientCredentialsPrivateKeyJwt;
1240
+ /** The slot filling {@link PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}. Required exactly when the token URL carries it. */
1241
+ readonly tenantSecretRef?: string;
1242
+ /** Facts an ORGANIZATION connection records once the vendor accepted its credential, keyed by fact name. */
1243
+ readonly verifiedAccountFacts?: Readonly<Record<string, ProviderClientCredentialsVerifiedFact>>;
1244
+ /** Seconds a token is kept when the answer states no `expires_in`. Omitted, it is not cached. */
1245
+ readonly tokenLifetimeFallbackSeconds?: number;
1246
+ }
1247
+
1248
+ /**
1249
+ * The `grant_type` a client-credentials token request sends. Narrower than `OAuth2_GrantType` on purpose: these are the
1250
+ * grants the client-credentials minter performs, each with nothing but the client's own credential and the declared
1251
+ * parameters, and a member joins in the change that implements it.
1252
+ */
1253
+ export enum ProviderClientCredentialsGrantType {
1254
+ /**
1255
+ * The OAuth 2.0 client-credentials grant: the default.
1256
+ * spec-cite: RFC 6749 §4.4.2 — `grant_type`: "REQUIRED. Value MUST be set to "client_credentials"." Fetched 2026-10-06.
1257
+ */
1258
+ CLIENT_CREDENTIALS = 'client_credentials',
1259
+ /**
1260
+ * Zoom's server-to-server OAuth: the same exchange (a client authenticated with Basic, one token back, no refresh
1261
+ * token) under Zoom's own grant name, with the account named in `account_id`.
1262
+ * spec-cite: https://developers.zoom.us/docs/internal-apps/s2s-oauth/ — "Use the `account_credentials` grant type to
1263
+ * generate an access token."; "Set up the body of the access token request using the `account_credentials`
1264
+ * `grant_type` and your `account_id`." Fetched 2026-11-09.
1265
+ */
1266
+ ACCOUNT_CREDENTIALS = 'account_credentials',
1267
+ }
1268
+
1269
+ /**
1270
+ * One further parameter of a client-credentials token request ({@link ProviderRestClientCredentials.tokenRequestParameters}):
1271
+ * a fixed `value` the module states (`box_subject_type: enterprise`), or a `secretRef` naming the connection slot that
1272
+ * holds it (Box's enterprise id, Zoom's account id), read like the client id: from the application's environment for
1273
+ * the application's connection, from the organization's credential for an organization's.
1274
+ */
1275
+ export type ProviderClientCredentialsTokenRequestParameter =
1276
+ | { readonly value: string; readonly secretRef?: never }
1277
+ | { readonly secretRef: string; readonly value?: never };
1278
+
1279
+ /**
1280
+ * The algorithms a client assertion is signed with (#3402). The JWS names (RFC 7518 §3.1) of the two asymmetric
1281
+ * families every vendor measured accepts: Okta lists "RS256, RS384, RS512, ES256, ES384, and ES512" for a service app's
1282
+ * key. A member joins when a vendor needs it.
1283
+ * spec-cite: RFC 7518 §3.1 — "RS256 | RSASSA-PKCS1-v1_5 using SHA-256" and "ES256 | ECDSA using P-256 and SHA-256";
1284
+ * https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/ — the supported algorithms. Both
1285
+ * fetched 2026-11-09.
1286
+ */
1287
+ export enum ProviderClientAssertionSigningAlgorithm {
1288
+ /** ECDSA on P-256 with SHA-256: a short key and signature, and the default to choose for a new key. */
1289
+ ES256 = 'ES256',
1290
+ /** RSASSA-PKCS1-v1_5 with SHA-256, for a vendor or key store that issues RSA keys. */
1291
+ RS256 = 'RS256',
1292
+ }
1293
+
1294
+ /** The longest a client assertion may live: Okta refuses one whose `exp` is more than an hour away. */
1295
+ export const PROVIDER_CLIENT_ASSERTION_MAXIMUM_LIFETIME_SECONDS = 3600;
1296
+
1297
+ /** How long a client assertion lives when the declaration says nothing: long enough for one request, and no more. */
1298
+ export const PROVIDER_CLIENT_ASSERTION_DEFAULT_LIFETIME_SECONDS = 300;
1299
+
1300
+ /**
1301
+ * `private_key_jwt` client authentication for a client-credentials token request (#3402). The client signs, per token
1302
+ * request, a JWT whose `iss` and `sub` are its client id, whose `aud` is the token endpoint it is sent to, with a short
1303
+ * `exp` and a fresh `jti`, and sends it as `client_assertion`.
1304
+ *
1305
+ * The private key is read from a slot of the connection, as an unencrypted PEM (PKCS#8, or an RSA PKCS#1 / EC key the
1306
+ * signer re-wraps), like a secret: the application's configured provider secrets for its own connection, an organization's sealed
1307
+ * credential row for an organization's.
1308
+ *
1309
+ * ## Why the platform keyring does not hold this key (decided 2026-11-10, #3402)
1310
+ *
1311
+ * The key layer (#2916) holds keys by PURPOSE, each signing the platform's own claims under its own `typ` and verified
1312
+ * from public halves the platform publishes. A client key is the opposite: its public half is REGISTERED BY THE OPERATOR
1313
+ * at the vendor (Okta's app, a Google service account), the vendor is its only verifier, and the vendor fixes the
1314
+ * algorithm (Okta's console and Google's uploaded keys are RSA, while the keyring signs ES256 only). A keyring rotation
1315
+ * would also silently break every connection whose vendor still holds the old public half. So custody signing for vendor
1316
+ * clients is a key purpose of its own (RS256 across the keyring providers, a public half handed to the operator, rotation
1317
+ * coordinated with the vendor registration), recorded on #2916, and not a missing step of this declaration.
1318
+ *
1319
+ * spec-cite: RFC 7523 §2.2 — "The value of the "client_assertion_type" is
1320
+ * "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"."; §3 — the JWT "MUST contain an "iss" (issuer) claim", for
1321
+ * client authentication "the subject MUST be the "client_id" of the OAuth client", an "aud" (audience) claim "containing
1322
+ * a value that identifies the authorization server", and an "exp" (expiration time) claim; OpenID Connect Core 1.0 §9,
1323
+ * `private_key_jwt` — `iss` and `sub` "MUST contain the client_id of the OAuth Client", "The Audience SHOULD be the URL
1324
+ * of the Authorization Server's Token Endpoint", `jti` REQUIRED: "These tokens MUST only be used once". Fetched
1325
+ * 2026-11-09 from https://www.rfc-editor.org/rfc/rfc7523 and https://openid.net/specs/openid-connect-core-1_0.html.
1326
+ */
1327
+ export interface ProviderClientCredentialsPrivateKeyJwt {
1328
+ /** The slot holding the client's private key: an unencrypted PEM, PKCS#8 (`-----BEGIN PRIVATE KEY-----`) or PKCS#1 / EC. */
1329
+ readonly privateKeySecretRef: string;
1330
+ /** The JWS algorithm the key signs with. Must match the key: an EC P-256 key for ES256, an RSA key for RS256. */
1331
+ readonly algorithm: ProviderClientAssertionSigningAlgorithm;
1332
+ /**
1333
+ * The slot holding the key id sent as the assertion's `kid` header, when the vendor locates the key by it (Okta
1334
+ * requires a `kid` on every key registered with the app). Omitted, no `kid` is sent.
1335
+ */
1336
+ readonly keyIdSecretRef?: string;
1337
+ /** Seconds until the assertion's `exp`. Omitted, {@link PROVIDER_CLIENT_ASSERTION_DEFAULT_LIFETIME_SECONDS}. */
1338
+ readonly assertionLifetimeSeconds?: number;
1339
+ }
1340
+
1341
+ /**
1342
+ * The slot of a client-credentials declaration's own CREDENTIAL: the client secret, or the private key (#3402).
1343
+ * `undefined` only for a declaration {@link describeProviderRestClientCredentialsDefects} refuses.
1344
+ */
1345
+ export function providerClientCredentialsCredentialSlot(credentials: ProviderRestClientCredentials): string | undefined {
1346
+ return credentials.clientSecretSecretRef ?? credentials.privateKeyJwt?.privateKeySecretRef;
1347
+ }
1348
+
1349
+ /**
1350
+ * The parameter names {@link ProviderRestClientCredentials.tokenRequestParameters} may not declare: each is written by
1351
+ * the grant itself (the grant type, the client's credential, the scope, a client assertion), so a second value would
1352
+ * either be ignored or override the declared one.
1353
+ */
1354
+ export const PROVIDER_CLIENT_CREDENTIALS_RESERVED_PARAMETER_NAMES: readonly string[] = [
1355
+ 'grant_type', 'client_id', 'client_secret', 'scope', 'client_assertion', 'client_assertion_type',
1356
+ ];
1357
+
1358
+ /**
1359
+ * Whether the client-credentials door of a REST contract serves a connection of this owner scope (#3398).
1360
+ *
1361
+ * Alone, it serves every admitted connection: the application's own (from its environment) and an organization's (from
1362
+ * the credential the organization typed, as a Teams bot). Beside `oauth2`, a person or an organization connects through
1363
+ * the authorization-code exchange, and the client-credentials grant serves the APPLICATION's own account only, so that
1364
+ * account renews itself instead of resting on a pasted token that expires within the hour.
1365
+ */
1366
+ export function providerClientCredentialsServesOwnerScope(
1367
+ contract: { readonly clientCredentials?: ProviderRestClientCredentials; readonly oauth2?: unknown },
1368
+ ownerScope: ExternalProvider_Connection_OwnerScope,
1369
+ ): boolean {
1370
+ if (contract.clientCredentials === undefined) return false;
1371
+ return contract.oauth2 === undefined || ownerScope === ExternalProvider_Connection_OwnerScope.APPLICATION;
1372
+ }
1373
+
1374
+ /**
1375
+ * The slot a connection of this owner scope AUTHENTICATES with, as the engine's REST access resolver reads it: the
1376
+ * client-credentials grant's own credential (its client secret or private key) when that door serves the owner scope
1377
+ * ({@link providerClientCredentialsServesOwnerScope}), else `apiKey.secretRef`, the stored or pasted token itself.
1378
+ *
1379
+ * For a contract declaring `clientCredentials` beside `oauth2` (Box, Zoom, #3398) the two differ by owner: the
1380
+ * application's own account mints from the server app's secret, while a person's connection reads its exchanged token
1381
+ * from `apiKey.secretRef`. A tool standing in for one connection (`wildo providers probe`, `connect`, the doctor's
1382
+ * configuration checks, all APPLICATION-owned) asks this instead of reading `apiKey.secretRef`, so it reads the slot the
1383
+ * engine would. `undefined` when the contract names neither.
1384
+ */
1385
+ export function providerRestConnectionCredentialSlot(
1386
+ contract: { readonly clientCredentials?: ProviderRestClientCredentials; readonly oauth2?: unknown; readonly apiKey?: { readonly secretRef?: string } },
1387
+ ownerScope: ExternalProvider_Connection_OwnerScope,
1388
+ ): string | undefined {
1389
+ return providerClientCredentialsServesOwnerScope(contract, ownerScope)
1390
+ ? providerClientCredentialsCredentialSlot(contract.clientCredentials!)
1391
+ : contract.apiKey?.secretRef;
1392
+ }
1393
+
1394
+ /**
1395
+ * Why a client-credentials declaration cannot be honoured, or an empty list. Checked where a provider is composed:
1396
+ * a token URL that is not https, a token host that is not a DNS name or that the URL is not on, a tenant placeholder
1397
+ * with no tenant slot (or the reverse), or any other placeholder in the URL.
1398
+ */
1399
+ export function describeProviderRestClientCredentialsDefects(credentials: ProviderRestClientCredentials): string[] {
1400
+ const defects: string[] = [];
1401
+ const hasTenant = credentials.tokenUrl.includes(PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER);
1402
+ // The deployment's origin forms the WHOLE origin or nothing (#3402): text before it, or anything but a path after it,
1403
+ // would compose a host the operator never named.
1404
+ const onDeploymentOrigin = credentials.tokenUrl.includes(PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER);
1405
+ if (onDeploymentOrigin && !credentials.tokenUrl.startsWith(`${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}/`)) {
1406
+ defects.push(`clientCredentials.tokenUrl carries ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} other than as its whole origin, followed by a path`);
1407
+ }
1408
+ if (onDeploymentOrigin && hasTenant) defects.push(`clientCredentials.tokenUrl carries both ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} and ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}; the token endpoint has one source`);
1409
+ const filled = credentials.tokenUrl
1410
+ .split(PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER).join('tenant.example')
1411
+ .split(PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER).join('https://deployment.example');
1412
+ if (/[{}]/.test(filled)) defects.push(`clientCredentials.tokenUrl '${credentials.tokenUrl}' carries a placeholder other than ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER} and ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}`);
1413
+ if (hasTenant && credentials.tenantSecretRef === undefined) defects.push(`clientCredentials.tokenUrl carries ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER} and no tenantSecretRef fills it`);
1414
+ if (!hasTenant && credentials.tenantSecretRef !== undefined) defects.push(`clientCredentials.tenantSecretRef '${credentials.tenantSecretRef}' fills nothing: the token URL carries no ${PROVIDER_CLIENT_CREDENTIALS_TENANT_PLACEHOLDER}`);
1415
+ const host = /^https:\/\/([^/:?#]+)(?::\d+)?\//.exec(filled)?.[1]?.toLowerCase();
1416
+ if (host === undefined) defects.push(`clientCredentials.tokenUrl '${credentials.tokenUrl}' is not an https URL with a path`);
1417
+ if (onDeploymentOrigin) {
1418
+ // The host is the deployment's, admitted where the engine resolves the operations' base URL; a fixed list would be
1419
+ // a second, unchecked statement of it.
1420
+ if (credentials.tokenHosts.length > 0) defects.push(`clientCredentials.tokenHosts names hosts beside ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}; the token host is the deployment's, so declare none`);
1421
+ } else {
1422
+ if (credentials.tokenHosts.length === 0) defects.push('clientCredentials.tokenHosts admits no host');
1423
+ for (const tokenHost of credentials.tokenHosts) {
1424
+ if (!PROVIDER_OAUTH2_DNS_NAME_PATTERN.test(tokenHost.toLowerCase())) defects.push(`clientCredentials.tokenHosts names '${tokenHost}', which is not a DNS name`);
1425
+ }
1426
+ if (host !== undefined && !credentials.tokenHosts.some((tokenHost) => tokenHost.toLowerCase() === host)) {
1427
+ defects.push(`clientCredentials.tokenUrl is on '${host}', which tokenHosts does not admit`);
1428
+ }
1429
+ }
1430
+ if (credentials.scope !== undefined && credentials.scope.trim() === '') defects.push('clientCredentials.scope is empty; omit it to send none');
1431
+ const grantTypes: readonly string[] = Object.values(ProviderClientCredentialsGrantType);
1432
+ if (credentials.grantType !== undefined && !grantTypes.includes(credentials.grantType)) {
1433
+ defects.push(`clientCredentials.grantType ${JSON.stringify(credentials.grantType)} is none of ${grantTypes.join(', ')}`);
1434
+ }
1435
+ // One credential: a secret or a private key (#3402), and the method agrees with which.
1436
+ if ((credentials.clientSecretSecretRef === undefined) === (credentials.privateKeyJwt === undefined)) {
1437
+ defects.push('clientCredentials declares exactly one of clientSecretSecretRef and privateKeyJwt');
1438
+ }
1439
+ const methods: readonly string[] = credentials.privateKeyJwt !== undefined
1440
+ ? [ProviderOAuth2ClientAuthenticationMethod.PRIVATE_KEY_JWT]
1441
+ : [ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_POST, ProviderOAuth2ClientAuthenticationMethod.CLIENT_SECRET_BASIC];
1442
+ if (credentials.tokenEndpointAuthMethod !== undefined && !methods.includes(credentials.tokenEndpointAuthMethod)) {
1443
+ defects.push(`clientCredentials.tokenEndpointAuthMethod ${JSON.stringify(credentials.tokenEndpointAuthMethod)} is none of ${methods.join(', ')} for ${credentials.privateKeyJwt !== undefined ? 'a private key' : 'a client secret'}`);
1444
+ }
1445
+ if (credentials.privateKeyJwt !== undefined) {
1446
+ const { privateKeySecretRef, algorithm, keyIdSecretRef, assertionLifetimeSeconds } = credentials.privateKeyJwt;
1447
+ const algorithms: readonly string[] = Object.values(ProviderClientAssertionSigningAlgorithm);
1448
+ if (privateKeySecretRef.trim() === '') defects.push('clientCredentials.privateKeyJwt.privateKeySecretRef names no slot');
1449
+ if (!algorithms.includes(algorithm)) defects.push(`clientCredentials.privateKeyJwt.algorithm ${JSON.stringify(algorithm)} is none of ${algorithms.join(', ')}`);
1450
+ if (keyIdSecretRef !== undefined && keyIdSecretRef.trim() === '') defects.push('clientCredentials.privateKeyJwt.keyIdSecretRef names no slot');
1451
+ if (assertionLifetimeSeconds !== undefined
1452
+ && !(Number.isInteger(assertionLifetimeSeconds) && assertionLifetimeSeconds > 0 && assertionLifetimeSeconds <= PROVIDER_CLIENT_ASSERTION_MAXIMUM_LIFETIME_SECONDS)) {
1453
+ defects.push(`clientCredentials.privateKeyJwt.assertionLifetimeSeconds is not a whole number of seconds from 1 to ${PROVIDER_CLIENT_ASSERTION_MAXIMUM_LIFETIME_SECONDS}`);
1454
+ }
1455
+ }
1456
+ for (const [name, parameter] of Object.entries(credentials.tokenRequestParameters ?? {})) {
1457
+ if (!/^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(name)) defects.push(`clientCredentials.tokenRequestParameters names '${name}', which is not a parameter name`);
1458
+ if (PROVIDER_CLIENT_CREDENTIALS_RESERVED_PARAMETER_NAMES.includes(name)) {
1459
+ defects.push(`clientCredentials.tokenRequestParameters names '${name}', which the grant itself sends; declare it in its own field`);
1460
+ }
1461
+ const hasValue = typeof parameter.value === 'string';
1462
+ const hasSlot = typeof parameter.secretRef === 'string';
1463
+ if (hasValue === hasSlot) defects.push(`clientCredentials.tokenRequestParameters '${name}' must declare exactly one of value and secretRef`);
1464
+ else if ((parameter.value ?? parameter.secretRef ?? '').trim() === '') defects.push(`clientCredentials.tokenRequestParameters '${name}' is empty`);
1465
+ }
1466
+ for (const [name, fact] of Object.entries(credentials.verifiedAccountFacts ?? {})) {
1467
+ if (!/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(name)) defects.push(`clientCredentials.verifiedAccountFacts names '${name}', which is not a fact name`);
1468
+ if (fact.source === ProviderClientCredentialsFactSource.TENANT && credentials.tenantSecretRef === undefined) {
1469
+ defects.push(`clientCredentials.verifiedAccountFacts '${name}' records the tenant, and no tenantSecretRef holds one`);
1470
+ }
1471
+ }
1472
+ if (credentials.tokenLifetimeFallbackSeconds !== undefined && !(credentials.tokenLifetimeFallbackSeconds > 0)) {
1473
+ defects.push('clientCredentials.tokenLifetimeFallbackSeconds is not a positive number');
1474
+ }
1475
+ return defects;
1476
+ }
1477
+
1478
+ /**
1479
+ * Why a REST contract's `clientCredentials` sits wrongly beside the contract's other authentication fields, or an empty
1480
+ * list (#2663, #3398). Checked where a provider is composed, beside {@link describeProviderRestClientCredentialsDefects}.
1481
+ *
1482
+ * - beside `requestSigning`: two ways to authenticate one call;
1483
+ * - alone, `apiKey.secretRef` must be the client secret's slot, the one whose absence means "not configured";
1484
+ * - beside `oauth2` the grant serves the APPLICATION's own account only ({@link providerClientCredentialsServesOwnerScope}),
1485
+ * so the module must admit that connection; `apiKey.secretRef` names the exchanged tokens' slot and may not be the
1486
+ * client secret's (a person's token would be read from it); and `verifiedAccountFacts`, which only an organization's
1487
+ * connection records, would record nothing.
1488
+ * - a token URL on {@link PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER} (#3402) needs a base URL the
1489
+ * DEPLOYMENT names (`baseUrlHostEnvVarName` or `baseUrlEnvVarName`), and may serve the APPLICATION's connection only:
1490
+ * the deployment's instance is the application's own (its Okta org), so an organization minting there would
1491
+ * authenticate against the application's vendor tenant, never its own.
1492
+ */
1493
+ export function describeProviderRestClientCredentialsPlacementDefects(
1494
+ contract: {
1495
+ readonly clientCredentials?: ProviderRestClientCredentials;
1496
+ readonly oauth2?: unknown;
1497
+ readonly requestSigning?: unknown;
1498
+ readonly apiKey: { readonly secretRef: string };
1499
+ readonly baseUrlHostEnvVarName?: string;
1500
+ readonly baseUrlEnvVarName?: string;
1501
+ },
1502
+ admitsApplicationConnection: boolean,
1503
+ /** Whether the module admits an ORGANIZATION or USER connection. Omitted, `false`. */
1504
+ admitsNonApplicationConnection = false,
1505
+ ): string[] {
1506
+ const credentials = contract.clientCredentials;
1507
+ if (credentials === undefined) return [];
1508
+ const defects: string[] = [];
1509
+ if (contract.requestSigning !== undefined) {
1510
+ defects.push('declares clientCredentials beside requestSigning; a call authenticates one way');
1511
+ }
1512
+ if (credentials.tokenUrl.includes(PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER)) {
1513
+ if (contract.baseUrlHostEnvVarName === undefined && contract.baseUrlEnvVarName === undefined) {
1514
+ defects.push(`clientCredentials.tokenUrl is on ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}, and the contract's base URL is not one the deployment names (baseUrlHostEnvVarName or baseUrlEnvVarName)`);
1515
+ }
1516
+ if (!admitsApplicationConnection) {
1517
+ defects.push(`clientCredentials.tokenUrl is on ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}, which serves the application's own connection only, and the module admits none`);
1518
+ }
1519
+ if (contract.oauth2 === undefined && admitsNonApplicationConnection) {
1520
+ defects.push(`clientCredentials.tokenUrl is on ${PROVIDER_CLIENT_CREDENTIALS_DEPLOYMENT_ORIGIN_PLACEHOLDER}, the application's own vendor instance, and the module admits an organization or user connection that would mint there`);
1521
+ }
1522
+ }
1523
+ const credentialSlot = providerClientCredentialsCredentialSlot(credentials);
1524
+ if (contract.oauth2 === undefined) {
1525
+ if (contract.apiKey.secretRef !== credentialSlot) {
1526
+ defects.push(`apiKey.secretRef '${contract.apiKey.secretRef}' is not the client's credential slot '${credentialSlot}' (its secret or private key); that is the slot whose absence means not configured`);
1527
+ }
1528
+ return defects;
1529
+ }
1530
+ if (!admitsApplicationConnection) defects.push('declares clientCredentials beside oauth2 and admits no APPLICATION connection, the only one that grant serves');
1531
+ if (contract.apiKey.secretRef === credentialSlot) {
1532
+ defects.push(`apiKey.secretRef '${contract.apiKey.secretRef}' is the client-credentials secret or key; beside oauth2 it names the slot of the exchanged access tokens`);
1533
+ }
1534
+ if (credentials.verifiedAccountFacts !== undefined) {
1535
+ defects.push('declares clientCredentials.verifiedAccountFacts beside oauth2; an organization connects through oauth2, so no client-credentials fact is ever recorded');
1536
+ }
1537
+ return defects;
1538
+ }
1539
+
1540
+ function readDotPath(body: unknown, path: string): unknown {
1541
+ let current: unknown = body;
1542
+ for (const segment of path.split('.')) {
1543
+ if (current === null || typeof current !== 'object' || !Object.hasOwn(current, segment)) return undefined;
1544
+ current = (current as Record<string, unknown>)[segment];
1545
+ }
1546
+ return current;
1547
+ }
1548
+
1549
+ /**
1550
+ * The vendor's error code at `errorCodePath` in a parsed answer, when it is code-shaped. Used for a refused 2xx and for
1551
+ * a non-2xx answer alike: a vendor that states its code in the body states it in the same place whatever the status.
1552
+ */
1553
+ export function readProviderVendorErrorCode(body: unknown, errorCodePath: string): string | undefined {
1554
+ const code = readDotPath(body, errorCodePath);
1555
+ return typeof code === 'string' && PROVIDER_VENDOR_ERROR_CODE_SHAPE.test(code) ? code : undefined;
1556
+ }
1557
+
1558
+ /** Reads the verdict a parsed JSON answer carries. The ONE reader: the transport and every test go through it. */
1559
+ export function readProviderRestApplicationOutcome(
1560
+ body: unknown,
1561
+ outcome: Pick<ProviderRestApplicationOutcome, 'successFlagPath' | 'errorCodePath'>,
1562
+ ): ProviderRestApplicationOutcomeVerdict {
1563
+ const flag = readDotPath(body, outcome.successFlagPath);
1564
+ if (flag === true) return { kind: ProviderRestApplicationOutcomeKind.SUCCEEDED };
1565
+ if (flag !== false) return { kind: ProviderRestApplicationOutcomeKind.UNSTATED };
1566
+ const errorCode = readProviderVendorErrorCode(body, outcome.errorCodePath);
1567
+ return errorCode === undefined
1568
+ ? { kind: ProviderRestApplicationOutcomeKind.REFUSED }
1569
+ : { kind: ProviderRestApplicationOutcomeKind.REFUSED, errorCode };
1570
+ }
300
1571
  ```