@wildo-ai/framework-knowledge 1.1.0 → 1.1.2

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 (240) hide show
  1. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  2. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  3. package/dist/esm/framework-knowledge.definitions.js +43 -2
  4. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  5. package/dist/esm/framework-knowledge.loader.d.ts +19 -0
  6. package/dist/esm/framework-knowledge.loader.d.ts.map +1 -1
  7. package/dist/esm/framework-knowledge.loader.js +32 -0
  8. package/dist/esm/framework-knowledge.loader.js.map +1 -1
  9. package/dist/esm/framework-knowledge.schemas.d.ts +12 -0
  10. package/dist/esm/framework-knowledge.schemas.d.ts.map +1 -1
  11. package/dist/esm/framework-knowledge.schemas.js.map +1 -1
  12. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +46 -0
  13. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -0
  14. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +55 -0
  15. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -0
  16. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +4 -4
  17. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +3 -3
  18. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
  19. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +0 -3
  20. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
  21. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +0 -1
  22. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
  23. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +0 -3
  24. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -1
  25. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +0 -1
  26. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -1
  27. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +2 -7
  28. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
  29. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +0 -1
  30. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
  31. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +8 -3
  32. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
  33. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +22 -1
  34. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
  35. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +0 -3
  36. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
  37. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +0 -1
  38. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
  39. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts +4 -1
  40. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
  41. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js +4 -1
  42. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js.map +1 -1
  43. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +1 -1
  44. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +13 -13
  45. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
  46. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +3 -4
  47. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
  48. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +3 -3
  49. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
  50. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +2 -7
  51. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
  52. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +0 -1
  53. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
  54. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts +2 -7
  55. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
  56. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +0 -1
  57. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -1
  58. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts +54 -0
  59. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -0
  60. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js +127 -0
  61. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js.map +1 -0
  62. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +76 -0
  63. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -0
  64. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +92 -0
  65. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -0
  66. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts +30 -0
  67. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -0
  68. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js +29 -0
  69. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js.map +1 -0
  70. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +9 -44
  71. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
  72. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +4 -53
  73. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -1
  74. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts +31 -0
  75. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -0
  76. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js +26 -0
  77. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js.map +1 -0
  78. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts +2 -7
  79. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
  80. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js +0 -1
  81. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js.map +1 -1
  82. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +0 -8
  83. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
  84. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +0 -1
  85. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
  86. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +2 -7
  87. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
  88. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +0 -1
  89. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
  90. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +2 -7
  91. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
  92. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +0 -1
  93. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
  94. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +2 -7
  95. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
  96. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +5 -3
  97. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -1
  98. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +0 -3
  99. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
  100. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +0 -1
  101. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -1
  102. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +4 -5
  103. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
  104. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +25 -4
  105. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
  106. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  107. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -0
  108. package/dist/knowledge/manifest.json +8 -8
  109. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +51 -0
  110. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +43 -0
  111. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +27 -10
  112. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +8 -7
  113. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +6 -4
  114. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +4 -6
  115. package/dist/knowledge/playbooks/bottom_up.build-scale/method.md +5 -4
  116. package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +4 -6
  117. package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +0 -4
  118. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +4 -6
  119. package/dist/knowledge/playbooks/bottom_up.foundation/method.md +49 -22
  120. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +14 -6
  121. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +2 -4
  122. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +46 -1
  123. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +7 -3
  124. package/dist/knowledge/playbooks/refinement.document-facts/method.md +18 -4
  125. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +4 -2
  126. package/dist/knowledge/playbooks/top_down.brand-identity/method.md +2 -3
  127. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +8 -7
  128. package/dist/knowledge/playbooks/top_down.business-model/playbook.json +3 -5
  129. package/dist/knowledge/playbooks/top_down.capability-map/method.md +0 -2
  130. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +4 -6
  131. package/dist/knowledge/playbooks/top_down.compliance-analysis/method.md +41 -0
  132. package/dist/knowledge/playbooks/top_down.compliance-analysis/playbook.json +100 -0
  133. package/dist/knowledge/playbooks/top_down.compliance-conception/method.md +117 -0
  134. package/dist/knowledge/playbooks/top_down.compliance-conception/playbook.json +86 -0
  135. package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/method.md +61 -0
  136. package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/playbook.json +41 -0
  137. package/dist/knowledge/playbooks/top_down.compliance-posture/method.md +21 -4
  138. package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +14 -57
  139. package/dist/knowledge/playbooks/top_down.compliance-research/method.md +76 -0
  140. package/dist/knowledge/playbooks/top_down.compliance-research/playbook.json +42 -0
  141. package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +3 -5
  142. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +3 -1
  143. package/dist/knowledge/playbooks/top_down.market-research/playbook.json +3 -1
  144. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +3 -5
  145. package/dist/knowledge/playbooks/top_down.phase-gate/method.md +8 -4
  146. package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +4 -6
  147. package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +9 -7
  148. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +4 -6
  149. package/dist/knowledge/playbooks/top_down.scope-roadmap/method.md +2 -2
  150. package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +8 -7
  151. package/dist/knowledge/playbooks/top_down.value-proposition/method.md +0 -2
  152. package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +4 -6
  153. package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +2 -2
  154. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +8 -7
  155. package/dist/knowledge/references/companion.technical-doc.service.md +102 -2
  156. package/dist/knowledge/references/example.config.app-shell.full.md +0 -1
  157. package/dist/knowledge/references/example.module.companion-exports.full.md +1 -0
  158. package/dist/knowledge/references/platform.config.saas.md +1 -0
  159. package/dist/knowledge/references/presets.models.surface-policy.md +19 -10
  160. package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +25 -1
  161. package/dist/knowledge/references/saas.frontend.composite-view.authoring.md +45 -0
  162. package/dist/knowledge/references/saas.frontend.display-layout.reading-measure.md +34 -0
  163. package/dist/knowledge/references/saas.frontend.navigation.operation-override.md +45 -0
  164. package/dist/knowledge/references/saas.frontend.public-shell.identity-mode.md +65 -0
  165. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +89 -0
  166. package/dist/knowledge/references/saas.models.data-mode-read-list.md +31 -4
  167. package/dist/knowledge/references/saas.models.engine-capabilities.md +26 -6
  168. package/dist/knowledge/references/saas.models.file-upload-grant.md +179 -0
  169. package/dist/knowledge/references/saas.models.navigation.surface-vocabulary.md +124 -0
  170. package/dist/knowledge/references/saas.models.navigation.transition-vocabulary.md +99 -0
  171. package/dist/knowledge/references/saas.models.navigation.zone-declaration.md +127 -0
  172. package/dist/knowledge/references/saas.models.provider-capabilities.md +4 -3
  173. package/dist/knowledge/references/saas.models.resource-config.operation-variant-client-timeout.md +42 -0
  174. package/dist/knowledge/references/saas.specifications.application-authored-document-fact-specification.contract.md +29 -0
  175. package/dist/knowledge/references/saas.specifications.application-document-fact-specification.contract.md +11 -31
  176. package/dist/knowledge/references/saas.specifications.assurance-document-blueprint.contract.md +32 -2
  177. package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +29 -6
  178. package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +20 -0
  179. package/dist/knowledge/references/saas.specifications.resource-spec-config.md +22 -0
  180. package/dist/knowledge/references/zod.decorators.display-edit-modes.md +6 -0
  181. package/dist/knowledge/references/zod.decorators.field-spec-params.md +31 -5
  182. package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +43 -0
  183. package/dist/knowledge/references/zod.decorators.primitive-ui.md +3 -0
  184. package/dist/knowledge/references/zod.decorators.shared-structural-params.md +15 -0
  185. package/dist/knowledge/registries/assurance-authority-bases.json +3 -2
  186. package/dist/knowledge/registries/framework-topics.json +99 -1
  187. package/dist/knowledge/registries/playbooks.json +81 -8
  188. package/dist/knowledge/registries/source-tags.json +757 -588
  189. package/dist/knowledge/skills/INDEX.md +3 -3
  190. package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +2 -1
  191. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-governance.md +5 -1
  192. package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-fact-specification-contract.md +66 -37
  193. package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +40 -7
  194. package/dist/knowledge/skills/config-app-shell/SKILL.md +25 -1
  195. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +25 -1
  196. package/dist/knowledge/skills/config-app-shell/references/framework-public-shell-identity-api.md +124 -0
  197. package/dist/knowledge/skills/config-design-system/SKILL.md +23 -1
  198. package/dist/knowledge/skills/config-design-system/references/framework-surface-policy-api.md +19 -10
  199. package/dist/knowledge/skills/config-design-system/references/loading-placeholder-authoring.md +47 -0
  200. package/dist/knowledge/skills/config-navigation/SKILL.md +75 -2
  201. package/dist/knowledge/skills/config-navigation/references/framework-content-width-api.md +98 -0
  202. package/dist/knowledge/skills/config-navigation/references/framework-navigation-operation-override-api.md +54 -0
  203. package/dist/knowledge/skills/config-navigation/references/framework-navigation-vocabulary-api.md +232 -0
  204. package/dist/knowledge/skills/config-navigation/references/framework-navigation-zone-declaration-api.md +149 -0
  205. package/dist/knowledge/skills/config-navigation/references/how-navigation-resolves.md +114 -0
  206. package/dist/knowledge/skills/config-navigation/references/navigation-configuration-map.md +133 -0
  207. package/dist/knowledge/skills/config-saas/SKILL.md +19 -2
  208. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +111 -0
  209. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +30 -9
  210. package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +1 -0
  211. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +2 -1
  212. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +4 -3
  213. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +20 -0
  214. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +20 -0
  215. package/dist/knowledge/skills/module-companion-exports/SKILL.md +1 -0
  216. package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +20 -0
  217. package/dist/knowledge/skills/resource-add-field/SKILL.md +3 -3
  218. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +104 -0
  219. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +13 -0
  220. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +71 -4
  221. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +89 -0
  222. package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +22 -1
  223. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-file-upload-grant-contract.md +192 -0
  224. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +28 -8
  225. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +15 -0
  226. package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +6 -0
  227. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +89 -0
  228. package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +43 -0
  229. package/dist/knowledge/skills/resource-ui-behavior/references/framework-primitive-ui-api.md +3 -0
  230. package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +1 -1
  231. package/dist/knowledge/skills/spec-companion-exports/SKILL.md +1 -0
  232. package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +20 -0
  233. package/dist/knowledge/skills/spec-resource-update/references/framework-field-spec-params-api.md +31 -5
  234. package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +22 -0
  235. package/dist/knowledge/skills/views-composite-authoring/references/framework-composite-view-contracts-api.md +45 -0
  236. package/dist/knowledge/topic-index.json +504 -156
  237. package/dist/tsconfig.build.tsbuildinfo +1 -1
  238. package/dist/tsconfig.tsbuildinfo +1 -1
  239. package/package.json +4 -4
  240. package/dist/esm/.builder.pid +0 -9
@@ -143,6 +143,7 @@ export const WildoSaasConfigSchema = z.strictObject({
143
143
  * empty ARRAY is the different, positive answer — this surface sets nothing of its own.
144
144
  */
145
145
  clientStorage: ApplicationClientStorageInventorySchema.optional(),
146
+ operatingJurisdictions: ApplicationOperatingJurisdictionsSchema.optional(),
146
147
  operatorComplianceIdentity: ApplicationOperatorComplianceIdentitySchema.optional(),
147
148
  providerComplianceChoices: ApplicationProviderComplianceChoicesSchema.optional(),
148
149
 
@@ -73,7 +73,8 @@ File: `backend-api/src/modules/<module>/addons/flows-actors/*.ts`. The system mu
73
73
  be `kind: ACTOR` with an actor whose `executionMode` is `AGENTIC` and a bound
74
74
  `agentRef`. If it renders an in-app chat, it already qualifies — build it via
75
75
  `flows-actors-chat-assistant`. Verify what will be advertised:
76
- // TODO CLI COMMAND: wildo context flows-actors --a2a-exposable
76
+ (There is no live introspection query for A2A exposure yet — verify against the agent/flow
77
+ declarations in `shared-lib` themselves.)
77
78
 
78
79
  ### Step 2: Enable external auth (OIDC provider + OAuth client)
79
80
  External agents get a token from YOUR app's OIDC provider. For **user-delegated**
@@ -102,9 +102,10 @@ export interface A2A_AgentCard {
102
102
 
103
103
  ## The A2A task surface (`tasks/get` / `tasks/cancel`)
104
104
 
105
- Read this when an external agent needs to start work it will come back for. (A turn that
106
- pauses for human approval also becomes a task — but that pausing runtime is a LATER phase and
107
- is not live today, so nothing you build now can reach it.)
105
+ Read this when an external agent needs to start work it will come back for. A turn that pauses
106
+ for human approval also becomes a task: it reaches `input-required`, persists the decision it is
107
+ waiting on, and leaves that state once its execution moves on. Both paths into a task are live,
108
+ so an integration you build now can encounter either.
108
109
 
109
110
  The key thing to understand is **when a task exists at all** — most turns never create
110
111
  one, and that is deliberate rather than a gap.
@@ -890,6 +890,9 @@ export interface SpecificationsCompanionExports<
890
890
  // a partial register is useful and its holes are REPORTED per provider against
891
891
  // the application's configured set, rather than blocking anything.
892
892
  TProcessorRegister = ApplicationProcessorRegister,
893
+ // Appended STRICTLY LAST: the human half of the document facts, in its own
894
+ // family, because the derived one is REGENERATED whole (#192).
895
+ TAuthoredDocumentFactSpecification = ApplicationAuthoredDocumentFactSpecification,
893
896
  > {
894
897
  resourceSpecifications: TResourceSpecifications;
895
898
  applicationBusinessSemanticsSnapshot?: TBusinessSemanticsSnapshot;
@@ -1274,6 +1277,23 @@ export interface SpecificationsCompanionExports<
1274
1277
  * Omitting it is honest: unresolved document facts remain visible gaps.
1275
1278
  */
1276
1279
  documentFactSpecification?: TDocumentFactSpecification;
1280
+ /**
1281
+ * Accepted application governed-document facts **only a human may establish** — a creator decision
1282
+ * or a qualified review (`document-facts-authored`).
1283
+ *
1284
+ * The same shape as the slot above, and a separate family on purpose. `refinement.document-facts`
1285
+ * rewrites the derived file whole, so a human decision sharing that file is destroyed on the next
1286
+ * run with nothing to notice: there is no compare-and-swap here, deliberately
1287
+ * (`.claude/rules/one-source-of-truth.md` Rule 0). Two families put the two writers out of each
1288
+ * other's reach.
1289
+ *
1290
+ * No producer may write this family — it has no generation contract, and that absence is the design
1291
+ * rather than an omission.
1292
+ *
1293
+ * A reader wanting "the application's facts" needs BOTH slots. `collectComplianceDocumentFactAvailability`
1294
+ * is variadic for exactly that reason.
1295
+ */
1296
+ authoredDocumentFactSpecification?: TAuthoredDocumentFactSpecification;
1277
1297
  /**
1278
1298
  * WHO else processes this application's personal data — legal identity, processing region and the
1279
1299
  * processor's own subprocessors (issue #88).
@@ -796,6 +796,9 @@ export interface SpecificationsCompanionExports<
796
796
  // a partial register is useful and its holes are REPORTED per provider against
797
797
  // the application's configured set, rather than blocking anything.
798
798
  TProcessorRegister = ApplicationProcessorRegister,
799
+ // Appended STRICTLY LAST: the human half of the document facts, in its own
800
+ // family, because the derived one is REGENERATED whole (#192).
801
+ TAuthoredDocumentFactSpecification = ApplicationAuthoredDocumentFactSpecification,
799
802
  > {
800
803
  resourceSpecifications: TResourceSpecifications;
801
804
  applicationBusinessSemanticsSnapshot?: TBusinessSemanticsSnapshot;
@@ -1180,6 +1183,23 @@ export interface SpecificationsCompanionExports<
1180
1183
  * Omitting it is honest: unresolved document facts remain visible gaps.
1181
1184
  */
1182
1185
  documentFactSpecification?: TDocumentFactSpecification;
1186
+ /**
1187
+ * Accepted application governed-document facts **only a human may establish** — a creator decision
1188
+ * or a qualified review (`document-facts-authored`).
1189
+ *
1190
+ * The same shape as the slot above, and a separate family on purpose. `refinement.document-facts`
1191
+ * rewrites the derived file whole, so a human decision sharing that file is destroyed on the next
1192
+ * run with nothing to notice: there is no compare-and-swap here, deliberately
1193
+ * (`.claude/rules/one-source-of-truth.md` Rule 0). Two families put the two writers out of each
1194
+ * other's reach.
1195
+ *
1196
+ * No producer may write this family — it has no generation contract, and that absence is the design
1197
+ * rather than an omission.
1198
+ *
1199
+ * A reader wanting "the application's facts" needs BOTH slots. `collectComplianceDocumentFactAvailability`
1200
+ * is variadic for exactly that reason.
1201
+ */
1202
+ authoredDocumentFactSpecification?: TAuthoredDocumentFactSpecification;
1183
1203
  /**
1184
1204
  * WHO else processes this application's personal data — legal identity, processing region and the
1185
1205
  * processor's own subprocessors (issue #88).
@@ -212,6 +212,7 @@ export const specificationsCompanionExports: SpecificationsCompanionExports<
212
212
  * decisions remain private runtime state.
213
213
  */
214
214
  documentFactSpecification: applicationDocumentFactSpecification,
215
+ authoredDocumentFactSpecification: applicationAuthoredDocumentFactSpecification,
215
216
  /**
216
217
  * The accepted typed build plan (`build-plan` family, `BuildPlanTaskGraph`).
217
218
  * The bottom-up dispatch playbook's coding owner reads it from the verified
@@ -101,6 +101,9 @@ export interface SpecificationsCompanionExports<
101
101
  // a partial register is useful and its holes are REPORTED per provider against
102
102
  // the application's configured set, rather than blocking anything.
103
103
  TProcessorRegister = ApplicationProcessorRegister,
104
+ // Appended STRICTLY LAST: the human half of the document facts, in its own
105
+ // family, because the derived one is REGENERATED whole (#192).
106
+ TAuthoredDocumentFactSpecification = ApplicationAuthoredDocumentFactSpecification,
104
107
  > {
105
108
  resourceSpecifications: TResourceSpecifications;
106
109
  applicationBusinessSemanticsSnapshot?: TBusinessSemanticsSnapshot;
@@ -485,6 +488,23 @@ export interface SpecificationsCompanionExports<
485
488
  * Omitting it is honest: unresolved document facts remain visible gaps.
486
489
  */
487
490
  documentFactSpecification?: TDocumentFactSpecification;
491
+ /**
492
+ * Accepted application governed-document facts **only a human may establish** — a creator decision
493
+ * or a qualified review (`document-facts-authored`).
494
+ *
495
+ * The same shape as the slot above, and a separate family on purpose. `refinement.document-facts`
496
+ * rewrites the derived file whole, so a human decision sharing that file is destroyed on the next
497
+ * run with nothing to notice: there is no compare-and-swap here, deliberately
498
+ * (`.claude/rules/one-source-of-truth.md` Rule 0). Two families put the two writers out of each
499
+ * other's reach.
500
+ *
501
+ * No producer may write this family — it has no generation contract, and that absence is the design
502
+ * rather than an omission.
503
+ *
504
+ * A reader wanting "the application's facts" needs BOTH slots. `collectComplianceDocumentFactAvailability`
505
+ * is variadic for exactly that reason.
506
+ */
507
+ authoredDocumentFactSpecification?: TAuthoredDocumentFactSpecification;
488
508
  /**
489
509
  * WHO else processes this application's personal data — legal identity, processing region and the
490
510
  * processor's own subprocessors (issue #88).
@@ -38,7 +38,7 @@ Locate the surfaces that may need editing using these app-relative globs:
38
38
  | Frontend UI behavior | `frontend/src/modules/*/resources/*/*.ui-behavior.tsx` |
39
39
  | Specification | `specifications/src/modules/*/resources/*.resource.specification.ts` |
40
40
  | Backend (rare) | `backend-api/src/modules/*/resources/*/*.resource-handlers.ts` |
41
- | i18n labels | `frontend/src/i18n/**/*.json` (or whatever `wildo context` writes for the project) |
41
+ | i18n labels | `frontend/src/i18n/**/*.json` (list the keys currently needed: `wildo context info frontend-labels-needed-info`) |
42
42
 
43
43
  If the project diverges from this layout, find the resource by grepping
44
44
  for the `R.<RESOURCE>` enum value or for the existing field's
@@ -172,8 +172,8 @@ Minimum label impact:
172
172
  - `<resource>.<fieldName>.label`
173
173
  - `<resource>.<fieldName>.<enumValue>` for each enum value
174
174
 
175
- Use the existing project placement pattern or the future `wildo context` i18n
176
- commands when they are available.
175
+ Use the existing project placement pattern; `wildo context info frontend-labels-needed-info`
176
+ lists the label keys the frontend currently needs, with their placement metadata.
177
177
 
178
178
  ### Re-run Translation When Text Changes
179
179
 
@@ -41,6 +41,21 @@ export interface ForeignKeyStructuralParams {
41
41
  * (e.g. `referrerScopeType`). Without it, `polymorphicVariants` is rename-only.
42
42
  */
43
43
  polymorphicDiscriminatorField?: string;
44
+ /**
45
+ * EXPLICIT target resource type, for an FK whose FIELD NAME cannot resolve it.
46
+ *
47
+ * The frontend resolves a reference field's target through the field-name → resource map
48
+ * (enriched from relationships' `foreignKeyField`). That works only when the field is named for
49
+ * its target (`assignedToUserId`) or a relationship declares it — and relationship FK names are
50
+ * held to the `Id`/`Ids` convention. A field that references a resource under its OWN vocabulary
51
+ * (`icpRefs` inside a specification document, a rename-only FK) has no honest entry in that map;
52
+ * declaring the target here lets the reference display resolve, label and navigate it without
53
+ * bending the field's name or the map's uniqueness.
54
+ *
55
+ * Takes precedence over the field-name map; polymorphic variants (above) still win over both,
56
+ * because a per-record discriminator is more specific than any static declaration.
57
+ */
58
+ referencedResourceType?: string;
44
59
  }
45
60
  ```
46
61
 
@@ -685,6 +700,26 @@ export const CardActionPlacementSchema = z.object({
685
700
  /** Authored 2-axis card action placement — inferred from {@link CardActionPlacementSchema}. */
686
701
  export type CardActionPlacement = z.infer<typeof CardActionPlacementSchema>;
687
702
 
703
+ /**
704
+ * Who paints the identity GLYPH on this operation's page header.
705
+ *
706
+ * The header band renders the resource's registry icon beside the identity line by default. A
707
+ * `layout.header` template that composes its own record-linked glyph (a per-row kind icon, a
708
+ * per-family symbol) would otherwise sit BESIDE the resource icon — two glyphs naming one thing.
709
+ *
710
+ * Declared at the OPERATION layer rather than detected from the template, deliberately: the
711
+ * resource icon renders before the template mounts, so detection could only suppress it after the
712
+ * fact — a glyph that flashes and vanishes on every load. Mirrors
713
+ * `SummaryTitlePlacement.TEMPLATE_OWNED`, the same contract one surface over: ceding a
714
+ * framework-owned element to the template is a declaration, not an inference.
715
+ */
716
+ export enum HeaderIconPlacement {
717
+ /** The framework renders the resource's registry icon (default). */
718
+ AUTO = 'auto',
719
+ /** The header template owns the glyph; the framework renders none. */
720
+ TEMPLATE_OWNED = 'template_owned',
721
+ }
722
+
688
723
  export const ResourceOperationFrontendConfigSchema = z.object({
689
724
  /**
690
725
  * The operation's frontend **surface** — see {@link ResourceOperationFrontendSurface}.
@@ -696,6 +731,8 @@ export const ResourceOperationFrontendConfigSchema = z.object({
696
731
  * Replaces the former `isAddressable` boolean — read via `isOperationAddressable()`.
697
732
  */
698
733
  surface: z.enum(ResourceOperationFrontendSurface),
734
+ /** Who paints the page header's identity glyph — see {@link HeaderIconPlacement}. Omitted = AUTO. */
735
+ headerIconPlacement: z.enum(HeaderIconPlacement).optional(),
699
736
  /**
700
737
  * How this operation's action is surfaced — see {@link ActionVisibility}. Omitted
701
738
  * (the common case) behaves as `ALWAYS`.
@@ -775,6 +812,30 @@ export const ResourceOperationFrontendConfigSchema = z.object({
775
812
  * without a date heading rather than being dropped.
776
813
  */
777
814
  temporalGroupField: z.string().optional(),
815
+ /**
816
+ * Group CARDS-mode rows into buckets by this ENUM field, rendering the
817
+ * enum value's own label as a heading between groups.
818
+ *
819
+ * Sibling of {@link temporalGroupField}, and deliberately NOT the same
820
+ * algorithm. Temporal grouping ADJACENT-MERGES in server order, because
821
+ * dates are open-ended and a page can legitimately revisit one. An enum is
822
+ * a CLOSED, ORDERED vocabulary, so its buckets are emitted in the enum's
823
+ * DECLARATION ORDER regardless of the order rows arrived in — the
824
+ * declaration is the authority for "which concern comes first", and a
825
+ * server sort cannot express it without a second, drifting copy of that
826
+ * order. Rows are therefore collected across the whole fetched page rather
827
+ * than merged adjacently, and no sort needs pairing with it.
828
+ *
829
+ * Headings resolve through `tResourceFieldEnumValue` — the SAME source the
830
+ * filters panel and the promoted quick-filter tabs use, so a bucket
831
+ * heading and its tab can never disagree.
832
+ *
833
+ * Ignored in TABLE mode (column sorting owns the ordering there). Rows
834
+ * whose value is absent, or outside the vocabulary, render in a trailing
835
+ * bucket with no heading rather than being dropped — the same fail-open
836
+ * the temporal grouping makes.
837
+ */
838
+ enumGroupField: z.string().optional(),
778
839
  /**
779
840
  * CARDS-mode arrangement — a single-column bordered LIST (default) or an
780
841
  * N-column responsive GRID. See {@link CardLayoutStyle}. `columns` (1–6) is
@@ -828,6 +889,49 @@ export const ResourceOperationFrontendConfigSchema = z.object({
828
889
  * into a description via the `.describe()` decorator.
829
890
  */
830
891
  hasDescription: z.boolean().optional(),
892
+ /**
893
+ * What happens to an ADJACENT zone (secondary / companion) this operation
894
+ * splits into, once that zone's last content is dismissed — overriding the
895
+ * zone's own `onEmpty` while this operation occupies primary.
896
+ *
897
+ * The zone-level `ZoneConfig.onEmpty` is one value for every destination that
898
+ * splits into that zone, and destinations legitimately disagree: a LIST wants
899
+ * the detail pane to stay put (`EMPTY_STATE`) so the layout does not reflow
900
+ * while a reviewer steps through rows, while a CANVAS wants its width back
901
+ * (`COLLAPSE`) the moment nothing is selected. Both share one secondary zone,
902
+ * so without this override one of them is always wrong.
903
+ *
904
+ * Declared on the SOURCE operation — the one occupying primary — not on the
905
+ * operation that lands in the pane: it answers "what should MY layout do when
906
+ * the detail closes", which is a property of the surface being returned to.
907
+ *
908
+ * Omitted (the common case) defers to the zone, which itself defaults to
909
+ * `ZoneEmptyBehavior.COLLAPSE`. Resolution order is destination → zone →
910
+ * COLLAPSE; see `resolveZoneEmptyBehavior`.
911
+ */
912
+ adjacentZoneOnEmpty: z.enum(ZoneEmptyBehavior).optional(),
913
+ /**
914
+ * How wide this destination's content may grow in the zone, in the framework's shared width
915
+ * vocabulary — the SAME `ResponsiveMaxWidth` a Surface, a `DisplayLayout` and a `FormLayout` use.
916
+ *
917
+ * Omitted (the common case) is `'content'`: capped and centred at `var(--content-max-width, 80rem)`,
918
+ * right for a form, a list or a detail page and wrong only for content whose value IS the space it
919
+ * occupies — a board, a wide table, a canvas — which declare `'none'`.
920
+ */
921
+ zoneContentMaxWidth: z.enum(RESPONSIVE_MAX_WIDTH_VALUES).optional(),
922
+ /**
923
+ * Whether this destination's content fills the zone's HEIGHT as well.
924
+ *
925
+ * `true` makes the zone's content boundary a definite-height flex column, so this view's root may use
926
+ * `flex-1 min-h-0` and resolve against something real. Without it a canvas has no intrinsic height
927
+ * and collapses to zero — which is why one had to hand-roll `h-[70vh]`, sizing against the WINDOW
928
+ * rather than the container it sits in. PRIMARY only: an adjacent zone scrolls, so a filling child
929
+ * and a scrolling parent contradict each other.
930
+ *
931
+ * Separate from the width above ON PURPOSE — see `zone-content-geometry.ts` for why the enum that
932
+ * fused them could not express a capped width with a definite height.
933
+ */
934
+ zoneContentFillsHeight: z.boolean().optional(),
831
935
  });
832
936
 
833
937
  /**
@@ -102,6 +102,17 @@ sending its email, or send an email without a usable token. Delivery is
102
102
  best-effort—author an explicit product recovery operation such as RESEND when a
103
103
  missing email must be recoverable.
104
104
 
105
+ For a variant whose synchronous round trip legitimately outlives the frontend's
106
+ 30-second HTTP default — an operation that calls a model and waits, a blocking
107
+ generation, a long import — declare `clientRequestTimeoutMs` on that variant.
108
+ The frontend applies it as the per-request timeout on every dispatch shape.
109
+ Without it the request is aborted client-side while the server work succeeds:
110
+ the caller renders a network error and the operation-success refresh chain never
111
+ fires, so lists keep showing the pre-operation world. Do not hard-code timeouts
112
+ in consumer hooks instead — the variant is where the operation's own knowledge
113
+ of its duration belongs. Contract and a worked example:
114
+ `references/framework-saas-models-resource-config-api.md`.
115
+
105
116
  ### Step 5: Align with UI and spec
106
117
 
107
118
  After config changes, `resource-ui-behavior` may need operation view updates;
@@ -302,6 +313,7 @@ fields (derived from the schema, never caller-supplied). Distinct from `isSystem
302
313
  - [ ] Operations referenced from `*.ui-behavior.tsx` exist in `*.resources-config.ts`
303
314
  - [ ] Variants and discriminator wiring stays consistent with `createSchemaFamily` usage on the schema
304
315
  - [ ] Role constraints (`roles: [...]`) match the product intent for each variant
316
+ - [ ] Any variant whose synchronous work can outlive ~30s declares `clientRequestTimeoutMs` (catch with the timeout grep below)
305
317
  - [ ] `accessScopeStrategy` is set on every `REFERENCE` relationship (no implicit defaults relied upon)
306
318
  - [ ] `contextPolicy` overrides for `LIST`/`SEARCH` are explicit when the relationship is high-cardinality
307
319
  - [ ] Every relational `searchableFields` entry uses a `localField` that exists on this schema (and a `relatedJoinField` that exists on the related resource — defaults to `_id`)
@@ -319,6 +331,7 @@ Run from the app root and substitute the resource / FK field name:
319
331
  | Relationship is co-located in the module-level relationships file (not inside config) | `rg -n "createResourcesRelationship" shared-lib/src/modules/*/resources/<resource>/<resource>.resources-config.ts` |
320
332
  | Custom operation IDs in the UI exist in the resource config | `rg -n "operationLike:\\s*<Resource>_Operations\\." frontend/src/modules/*/resources/<resource>/<resource>.ui-behavior.tsx` |
321
333
  | Same custom operation IDs are defined in the resource config | `rg -n "<Resource>_Operations\\." shared-lib/src/modules/*/resources/<resource>/<resource>.resources-config.ts` |
334
+ | Long-running variants declare their client timeout | `rg -n "clientRequestTimeoutMs" shared-lib/src/modules/*/resources/<resource>/<resource>.resources-config.ts` (expect a hit for any variant that generates/imports synchronously) |
322
335
  | The two custom-operation lists agree | `comm -23 <(rg -oN "<Resource>_Operations\\.[A-Z_]+" frontend/src/modules/*/resources/<resource>/*.tsx \\| sort -u) <(rg -oN "<Resource>_Operations\\.[A-Z_]+" shared-lib/src/modules/*/resources/<resource>/*.ts \\| sort -u)` |
323
336
 
324
337
  The third grep MUST return zero matches — relationship declarations in
@@ -202,6 +202,28 @@ export enum IntrospectionTenancyStance {
202
202
  */
203
203
  APPLICATION_STRUCTURE = 'application-structure',
204
204
 
205
+ /**
206
+ * The rows are the DEVELOPMENT COMPANION'S OWN RUNTIME PROJECTIONS for the one application it
207
+ * serves — the playbook eligibility board, the build plan, the run write-register, the execution
208
+ * traces. Like `APPLICATION_STRUCTURE` they carry no tenant dimension and no scope predicate can
209
+ * apply; UNLIKE it, they are not derived from the application's source, and the tenancy stance is
210
+ * where that difference must stay visible (added 2026-09-01, creation-board resources plan):
211
+ *
212
+ * - `APPLICATION_STRUCTURE`'s public-read posture (`APP_PUBLIC` variants on the workbench's
213
+ * structural projections) rests on the rows being the application's OWN source, which anyone
214
+ * with the working tree can already read. That argument does NOT extend to runtime state, so a
215
+ * resource declaring this stance is expected to gate its variants on an authenticated role —
216
+ * never `APP_PUBLIC`.
217
+ * - Row-level tenant-anchor checks are bypassed for this stance exactly as for
218
+ * `APPLICATION_STRUCTURE` (the rows carry no anchor BY CONTRACT); authorization comes from the
219
+ * session and the operation's role gate.
220
+ *
221
+ * Fusing this into `APPLICATION_STRUCTURE` was rejected for the enum's own founding reason: an
222
+ * unstated distinction is indistinguishable from an overlooked one, and the next decision site
223
+ * keyed off the stance would inherit a claim nobody checked.
224
+ */
225
+ APPLICATION_RUNTIME = 'application-runtime',
226
+
205
227
  /**
206
228
  * The rows carry a tenant dimension and a scope predicate must be pushed into the source.
207
229
  *
@@ -298,10 +320,15 @@ export enum PersistenceAdapter {
298
320
  * "how rows are reached", and the mechanism behind it is a binding an author declares.
299
321
  *
300
322
  * Distinct from `HTTP_API`, deliberately, and not merely because the transport differs. Retrieval
301
- * is a SUBPROCESS that imports the target application's built modules; it costs seconds rather than
302
- * milliseconds, it requires that application's `dist` to exist, and its failure mode is a behavior
303
- * throwing rather than a row being absent. Collapsing the two would give one declaration whose
304
- * discriminator chooses between an HTTP call and a subprocess — two adapters wearing one name.
323
+ * is the COMPANION's decision per behavior (amended 2026-09-01): the app-import behaviors run a
324
+ * SUBPROCESS that imports the target application's built modules — seconds per read, requiring
325
+ * that application's `dist`, failing as a thrown behavior — while the creation-plane behaviors
326
+ * are IN-PROCESS projections of the companion's own runtime services (playbook eligibility,
327
+ * build plan, write register, traces). Both reach the engine through the same
328
+ * `IntrospectionResourceSourceBackendPort`; the adapter never encodes the mechanism, which is
329
+ * exactly why a behavior id is an engine-opaque string. Collapsing this into `HTTP_API` would
330
+ * still be wrong for the original reason: its failure mode is a source throwing rather than a
331
+ * row being absent, and nothing here is reached over a network API.
305
332
  *
306
333
  * ## What every adapter decision site must honor
307
334
  *
@@ -1125,6 +1152,46 @@ export type ResourceConfiguration_Operation_ApiCall<
1125
1152
 
1126
1153
  ### Origin Package: `@wildo-ai/saas-models`
1127
1154
 
1155
+ ```typescript
1156
+ *
1157
+ * Frontend HTTP timeout for THIS variant, in milliseconds — declare it on any operation whose
1158
+ * synchronous round trip legitimately outlives the frontend client's 30-second default (an
1159
+ * operation that calls a model and waits for the answer, a long import, a blocking generation).
1160
+ *
1161
+ * The frontend resources client applies it as the per-request timeout on every dispatch shape
1162
+ * (api-call, api-call-with-callback, search). An explicit caller-supplied
1163
+ * `RequestOptions.timeout` still wins; omitting the field keeps the client default.
1164
+ *
1165
+ * Why it matters: without it, a long-running operation's request is aborted CLIENT-side while
1166
+ * the server work succeeds — the caller renders a network error, and the operation-success
1167
+ * refresh chain never fires, so lists keep showing the pre-operation world. Declare the
1168
+ * expectation on the variant (the operation knows it is long-running); do not hard-code
1169
+ * timeouts in consumer hooks, which duplicates that knowledge at every call site.
1170
+ *
1171
+ * This is a TRANSPORT expectation only — not a UI/observability signal (that is `riskLevel`)
1172
+ * and not a server-side bound: the backend is free to answer sooner or be cut off by its own
1173
+ * limits.
1174
+ *
1175
+ * @example a custom operation that generates a document before answering
1176
+ * variants: [{
1177
+ * variantType: ResourceOperationVariantType.API_CALL,
1178
+ * roles: [CORE_ORG_ROLES.ORG_MEMBER],
1179
+ * riskLevel: ResourceOperationRiskLevel.MEDIUM,
1180
+ * clientRequestTimeoutMs: 300_000, // five minutes — the generation is synchronous
1181
+ * requestDto: GenerateReportRequest_Schema,
1182
+ * customResponseDto: GenerateReportOutcome_Schema,
1183
+ * }]
1184
+ */
1185
+ clientRequestTimeoutMs?: number;
1186
+ ```
1187
+ ## Import Origins
1188
+
1189
+ - `@wildo-ai/saas-models`
1190
+
1191
+ ## Source Excerpts
1192
+
1193
+ ### Origin Package: `@wildo-ai/saas-models`
1194
+
1128
1195
  ```typescript
1129
1196
  *
1130
1197
  * Variant builder type that distributes operation-specific fields based on the operation key.
@@ -383,6 +383,26 @@ export const CardActionPlacementSchema = z.object({
383
383
  /** Authored 2-axis card action placement — inferred from {@link CardActionPlacementSchema}. */
384
384
  export type CardActionPlacement = z.infer<typeof CardActionPlacementSchema>;
385
385
 
386
+ /**
387
+ * Who paints the identity GLYPH on this operation's page header.
388
+ *
389
+ * The header band renders the resource's registry icon beside the identity line by default. A
390
+ * `layout.header` template that composes its own record-linked glyph (a per-row kind icon, a
391
+ * per-family symbol) would otherwise sit BESIDE the resource icon — two glyphs naming one thing.
392
+ *
393
+ * Declared at the OPERATION layer rather than detected from the template, deliberately: the
394
+ * resource icon renders before the template mounts, so detection could only suppress it after the
395
+ * fact — a glyph that flashes and vanishes on every load. Mirrors
396
+ * `SummaryTitlePlacement.TEMPLATE_OWNED`, the same contract one surface over: ceding a
397
+ * framework-owned element to the template is a declaration, not an inference.
398
+ */
399
+ export enum HeaderIconPlacement {
400
+ /** The framework renders the resource's registry icon (default). */
401
+ AUTO = 'auto',
402
+ /** The header template owns the glyph; the framework renders none. */
403
+ TEMPLATE_OWNED = 'template_owned',
404
+ }
405
+
386
406
  export const ResourceOperationFrontendConfigSchema = z.object({
387
407
  /**
388
408
  * The operation's frontend **surface** — see {@link ResourceOperationFrontendSurface}.
@@ -394,6 +414,8 @@ export const ResourceOperationFrontendConfigSchema = z.object({
394
414
  * Replaces the former `isAddressable` boolean — read via `isOperationAddressable()`.
395
415
  */
396
416
  surface: z.enum(ResourceOperationFrontendSurface),
417
+ /** Who paints the page header's identity glyph — see {@link HeaderIconPlacement}. Omitted = AUTO. */
418
+ headerIconPlacement: z.enum(HeaderIconPlacement).optional(),
397
419
  /**
398
420
  * How this operation's action is surfaced — see {@link ActionVisibility}. Omitted
399
421
  * (the common case) behaves as `ALWAYS`.
@@ -473,6 +495,30 @@ export const ResourceOperationFrontendConfigSchema = z.object({
473
495
  * without a date heading rather than being dropped.
474
496
  */
475
497
  temporalGroupField: z.string().optional(),
498
+ /**
499
+ * Group CARDS-mode rows into buckets by this ENUM field, rendering the
500
+ * enum value's own label as a heading between groups.
501
+ *
502
+ * Sibling of {@link temporalGroupField}, and deliberately NOT the same
503
+ * algorithm. Temporal grouping ADJACENT-MERGES in server order, because
504
+ * dates are open-ended and a page can legitimately revisit one. An enum is
505
+ * a CLOSED, ORDERED vocabulary, so its buckets are emitted in the enum's
506
+ * DECLARATION ORDER regardless of the order rows arrived in — the
507
+ * declaration is the authority for "which concern comes first", and a
508
+ * server sort cannot express it without a second, drifting copy of that
509
+ * order. Rows are therefore collected across the whole fetched page rather
510
+ * than merged adjacently, and no sort needs pairing with it.
511
+ *
512
+ * Headings resolve through `tResourceFieldEnumValue` — the SAME source the
513
+ * filters panel and the promoted quick-filter tabs use, so a bucket
514
+ * heading and its tab can never disagree.
515
+ *
516
+ * Ignored in TABLE mode (column sorting owns the ordering there). Rows
517
+ * whose value is absent, or outside the vocabulary, render in a trailing
518
+ * bucket with no heading rather than being dropped — the same fail-open
519
+ * the temporal grouping makes.
520
+ */
521
+ enumGroupField: z.string().optional(),
476
522
  /**
477
523
  * CARDS-mode arrangement — a single-column bordered LIST (default) or an
478
524
  * N-column responsive GRID. See {@link CardLayoutStyle}. `columns` (1–6) is
@@ -526,6 +572,49 @@ export const ResourceOperationFrontendConfigSchema = z.object({
526
572
  * into a description via the `.describe()` decorator.
527
573
  */
528
574
  hasDescription: z.boolean().optional(),
575
+ /**
576
+ * What happens to an ADJACENT zone (secondary / companion) this operation
577
+ * splits into, once that zone's last content is dismissed — overriding the
578
+ * zone's own `onEmpty` while this operation occupies primary.
579
+ *
580
+ * The zone-level `ZoneConfig.onEmpty` is one value for every destination that
581
+ * splits into that zone, and destinations legitimately disagree: a LIST wants
582
+ * the detail pane to stay put (`EMPTY_STATE`) so the layout does not reflow
583
+ * while a reviewer steps through rows, while a CANVAS wants its width back
584
+ * (`COLLAPSE`) the moment nothing is selected. Both share one secondary zone,
585
+ * so without this override one of them is always wrong.
586
+ *
587
+ * Declared on the SOURCE operation — the one occupying primary — not on the
588
+ * operation that lands in the pane: it answers "what should MY layout do when
589
+ * the detail closes", which is a property of the surface being returned to.
590
+ *
591
+ * Omitted (the common case) defers to the zone, which itself defaults to
592
+ * `ZoneEmptyBehavior.COLLAPSE`. Resolution order is destination → zone →
593
+ * COLLAPSE; see `resolveZoneEmptyBehavior`.
594
+ */
595
+ adjacentZoneOnEmpty: z.enum(ZoneEmptyBehavior).optional(),
596
+ /**
597
+ * How wide this destination's content may grow in the zone, in the framework's shared width
598
+ * vocabulary — the SAME `ResponsiveMaxWidth` a Surface, a `DisplayLayout` and a `FormLayout` use.
599
+ *
600
+ * Omitted (the common case) is `'content'`: capped and centred at `var(--content-max-width, 80rem)`,
601
+ * right for a form, a list or a detail page and wrong only for content whose value IS the space it
602
+ * occupies — a board, a wide table, a canvas — which declare `'none'`.
603
+ */
604
+ zoneContentMaxWidth: z.enum(RESPONSIVE_MAX_WIDTH_VALUES).optional(),
605
+ /**
606
+ * Whether this destination's content fills the zone's HEIGHT as well.
607
+ *
608
+ * `true` makes the zone's content boundary a definite-height flex column, so this view's root may use
609
+ * `flex-1 min-h-0` and resolve against something real. Without it a canvas has no intrinsic height
610
+ * and collapses to zero — which is why one had to hand-roll `h-[70vh]`, sizing against the WINDOW
611
+ * rather than the container it sits in. PRIMARY only: an adjacent zone scrolls, so a filling child
612
+ * and a scrolling parent contradict each other.
613
+ *
614
+ * Separate from the width above ON PURPOSE — see `zone-content-geometry.ts` for why the enum that
615
+ * fused them could not express a capped width with a definite height.
616
+ */
617
+ zoneContentFillsHeight: z.boolean().optional(),
529
618
  });
530
619
 
531
620
  /**
@@ -72,7 +72,9 @@ File: `shared-lib/src/modules/<module>/resources/<resource>/*.resources-config.t
72
72
  `ORGANIZATION`- and `APPLICATION`-scoped resources are exposable — a machine token carries no
73
73
  `userId`, so USER_SELF / ANONYMOUS operations are unreachable and are never advertised even if
74
74
  you set `mcp.exposed`. Confirm the resource's `resourcePrimaryScope` before proceeding.
75
- // TODO CLI COMMAND: wildo context resources --mcp-exposable
75
+ Live resource inventory: `wildo context info resources-registry`. Confirm `resourcePrimaryScope`
76
+ in the resource's own configuration under `shared-lib/` — the registry snapshot lists the
77
+ resources; the scope declaration lives in the config.
76
78
 
77
79
  ### Step 2: Choose which operations to expose (and classify instance vs collection)
78
80
  Only **DEFAULT, non-bulk, URL-bearing** operations become tools (the standard `API_CALL`
@@ -90,6 +92,14 @@ tool description falls back to the resource specification's `purpose` / `whenToU
90
92
  synthesized default — so either author it here or keep the spec prose agent-ready (and
91
93
  reconciled: see `spec-resource-update`).
92
94
 
95
+ **File fields need nothing extra — but know what the agent sees.** An MCP tool call cannot carry
96
+ bytes, so a `z_file()` field advertises a `fileId` the agent has no way to invent. For every exposed
97
+ CREATE / UPDATE with a user-uploadable file field the engine ALSO advertises a derived tool,
98
+ `<resource>__<operation>.upload_grant.<field>`, that mints a single-use upload link, and it appends to
99
+ your operation's description where each field's id comes from. Do not describe the upload in your own
100
+ `description` — the engine's note is derived from the field and stays in step with it. See
101
+ `references/framework-file-upload-grant-contract.md`.
102
+
93
103
  ### Step 3b (OPTIONAL): Split the catalog across NAMED servers
94
104
  One `/mcp` serves ONE flat tool list, so when different consumers need different capability
95
105
  postures — a read-only support surface vs a destructive operations one — declare **named servers**
@@ -212,6 +222,9 @@ curl -X POST https://your-app.example.com/api/v1/mcp \
212
222
 
213
223
  - `references/framework-resource-mcp-exposure-contract.md` — source-backed: the `mcp`
214
224
  operation-config field (the opt-in contract, description fallback, scope constraints).
225
+ - `references/framework-file-upload-grant-contract.md` — source-backed: what the derived
226
+ `…upload_grant.<field>` tool returns and how an agent turns it into a `fileId`. Read when an exposed
227
+ CREATE / UPDATE carries a `z_file()` field.
215
228
  - `references/framework-named-mcp-servers-contract.md` — source-backed: declaring NAMED MCP
216
229
  servers (`resourceServerInstances`) when one catalog is not enough, and how per-server
217
230
  audiences make the split a real boundary. Read only if you need more than one MCP surface.
@@ -250,6 +263,10 @@ curl -X POST https://your-app.example.com/api/v1/mcp \
250
263
  Without it, the test passes identically when the whole resource was never exposed, and would keep
251
264
  passing if the withdrawal logic were deleted. Grep your own tests:
252
265
  `rg -n "not\.toContain\('.*__" ` — each hit needs a `toContain` for the same resource nearby.
266
+ - [ ] IF an exposed CREATE / UPDATE carries a `z_file()` field: `tools/list` shows the derived
267
+ `…upload_grant.<field>` tool beside it, and the parent's description ends with a `File fields:` note.
268
+ Grep the live catalogue: `rg "upload_grant\." <tools-list.json>` — one hit per uploadable field of
269
+ each exposed CREATE / UPDATE, none for a generated (PDF-template) field.
253
270
  - [ ] No operation carrying an `unimplementedAcknowledgement` is relied on as a tool. You do NOT
254
271
  need to retract its `mcp` block — the engine withdraws it — but do not build a workflow on a tool
255
272
  that will not be there.
@@ -293,6 +310,10 @@ curl -X POST https://your-app.example.com/api/v1/mcp \
293
310
  tool ships; catch with the `tools/list` diff in Verification.
294
311
  - **Building an agent workflow on a verb that carries an `unimplementedAcknowledgement`** — it is
295
312
  withdrawn, so the workflow's tool will simply not be there; catch with the acknowledgement row.
313
+ - **Describing a file upload in your own `mcp.description`, or expecting an agent to pass a
314
+ `fileId` it made up** — the engine derives an `…upload_grant.<field>` tool and appends the
315
+ `File fields:` note itself, and a fileId only ever comes from an upload; catch with the
316
+ `upload_grant.` grep on the live catalogue in Verification.
296
317
  - **Treating named servers as cosmetic grouping** — each is a distinct RFC 8707 resource server,
297
318
  so a token for one is REJECTED at another; that isolation is the reason to split, and it is
298
319
  why a ref rename invalidates already-minted tokens.