@wildo-ai/framework-knowledge 1.1.1 → 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
@@ -0,0 +1,192 @@
1
+ # File upload grant — the contract behind `…upload_grant.<field>` tools
2
+
3
+ Read this when an exposed CREATE or UPDATE carries a `z_file()` field and you need to know what an
4
+ agent receives from the derived upload-grant tool, what it does with it, and what bounds apply.
5
+
6
+ - Every exposed default CREATE / UPDATE whose request carries a user-uploadable file field ALSO
7
+ advertises `<resource>__<operation>.upload_grant.<fieldSegment>` (e.g.
8
+ `todos__create.upload_grant.attachments`). You author nothing for it — it is derived from the same
9
+ `mcp: { exposed: true }` opt-in and inherits the parent's gating.
10
+ - Calling it mints a single-use grant and returns the object below: `uploadCommand` for an agent that
11
+ can execute commands, `uploadPageUrl` for one that must hand a human a link (`null` on a headless
12
+ application). The token travels in the `uploadHeader`, never in the upload URL.
13
+ - The agent then reads the produced `fileId` (from the upload response, or from `statusUrl` when a
14
+ human uploaded) and passes it as the field's `fileId` / `fileIds` in the parent tool.
15
+
16
+ ## Import Origins
17
+
18
+ - `@wildo-ai/saas-models`
19
+
20
+ ## Source Excerpts
21
+
22
+ ### Origin Package: `@wildo-ai/saas-models`
23
+
24
+ ```typescript
25
+ *
26
+ * Lifetime bounds of an upload grant, in minutes. The ceiling is fixed by the framework and enforced
27
+ * when the grant is minted — a request above it is REFUSED, never clamped, so a caller that asked for
28
+ * two hours learns from an error that the bound is sixty minutes rather than from an expiry it did not
29
+ * expect. The bound is the framework's to own because the grant is designed to leave the trust
30
+ * boundary: it lands in an AI agent's transcript, a model provider's logs, a shell history.
31
+ */
32
+ export const FILE_UPLOAD_GRANT_DEFAULT_MINUTES = 15;
33
+ export const FILE_UPLOAD_GRANT_ABSOLUTE_MAX_MINUTES = 60;
34
+
35
+ /**
36
+ * Which write the grant is for. A grant minted on the CREATE upload route uploads a file that a
37
+ * later CREATE will reference; one minted on the UPDATE route (`…/{resourceId}/files/<field>`) is
38
+ * bound to that row. The two routes authorize differently, so a grant may not cross from one to the
39
+ * other — the upload middleware checks this against the route it is presented on.
40
+ */
41
+ export const FILE_UPLOAD_GRANT_OPERATIONS = [CoreResourceOperation.CREATE, CoreResourceOperation.UPDATE] as const;
42
+ export type FileUploadGrantOperation = (typeof FILE_UPLOAD_GRANT_OPERATIONS)[number];
43
+ /** Derived from `CoreResourceOperation` — the named source — rather than a second enum spelling the same two words. */
44
+ export const FileUploadGrantOperationSchema: z.ZodEnum<{ [K in FileUploadGrantOperation]: K }> = z.enum(FILE_UPLOAD_GRANT_OPERATIONS);
45
+
46
+ /**
47
+ * Lifecycle of a grant as the status read reports it. Derived from the token row — `isConsumed`,
48
+ * `expiresAt`, `revokedAt` — never stored, so it cannot drift from the row.
49
+ */
50
+ export enum FileUploadGrantState {
51
+ /** Minted, unexpired, unrevoked, not yet redeemed: an upload will be accepted. */
52
+ PENDING = 'pending',
53
+ /** Redeemed by exactly one upload. `file` names what it produced when the write-back succeeded. */
54
+ REDEEMED = 'redeemed',
55
+ /** Past `expiresAt` without being redeemed. Mint a new one. */
56
+ EXPIRED = 'expired',
57
+ /** Revoked by the minter or an administrator before redemption. */
58
+ REVOKED = 'revoked',
59
+ }
60
+ export const FileUploadGrantStateSchema: z.ZodEnum<typeof FileUploadGrantState> = z.enum(FileUploadGrantState);
61
+
62
+ /**
63
+ * The `metadata` a FILE_UPLOAD_GRANT token carries — the ROUTE binding, as opposed to the identity
64
+ * the typed token fields carry. The upload middleware reads this; the execution-context creator
65
+ * deliberately does not.
66
+ */
67
+ export const FileUploadGrantMetadataSchema: z.ZodObject<{
68
+ fieldName: z.ZodString;
69
+ operation: z.ZodEnum<{ [K in FileUploadGrantOperation]: K }>;
70
+ minter: z.ZodObject<{ entityType: z.ZodString; id: z.ZodString }>;
71
+ uploadUrl: z.ZodString;
72
+ producedFileId: z.ZodOptional<z.ZodString>;
73
+ }> = z.object({
74
+ /** The `z_file()` field the upload lands on, as authored (dotted for nested fields). */
75
+ fieldName: z.string().min(1),
76
+ operation: FileUploadGrantOperationSchema,
77
+ /**
78
+ * Who minted — recorded so the uploaded file is attributed to a PERSON or MACHINE, not to the
79
+ * grant. `entityType` is a `FileUploaderEntityType` value; kept as a string here because the
80
+ * uploader enum lives in `zod-decorators`, upstream of this package.
81
+ */
82
+ minter: z.object({ entityType: z.string().min(1), id: z.string().min(1) }),
83
+ /** The concrete upload URL the grant was minted for — recorded so the status read can hand it to the drop page. */
84
+ uploadUrl: z.string().url(),
85
+ /** Written after a successful redemption; absent until then. */
86
+ producedFileId: z.string().min(1).optional(),
87
+ });
88
+ export type FileUploadGrantMetadata = z.infer<typeof FileUploadGrantMetadataSchema>;
89
+
90
+ /**
91
+ * What a mint returns — identical on the REST door and the MCP tool. Two affordances for one
92
+ * token: `uploadCommand` for a caller that can execute, `uploadPageUrl` for one that must hand a
93
+ * human a link. The token appears in `uploadHeader.value` and inside both commands and the page URL;
94
+ * it is the credential and cannot be omitted. It never appears in any audit row.
95
+ */
96
+ export const FileUploadGrantSchema: z.ZodObject<{
97
+ grantId: z.ZodString;
98
+ state: z.ZodEnum<typeof FileUploadGrantState>;
99
+ expiresAt: z.ZodString;
100
+ singleUse: z.ZodLiteral<true>;
101
+ target: z.ZodObject<{
102
+ resourceType: z.ZodString;
103
+ fieldName: z.ZodString;
104
+ operation: z.ZodEnum<{ [K in FileUploadGrantOperation]: K }>;
105
+ resourceId: z.ZodNullable<z.ZodString>;
106
+ }>;
107
+ constraints: z.ZodObject<{
108
+ maxBytes: z.ZodNumber;
109
+ allowedMimeTypes: z.ZodArray<z.ZodString>;
110
+ }>;
111
+ uploadUrl: z.ZodString;
112
+ uploadHeader: z.ZodObject<{ name: z.ZodString; value: z.ZodString }>;
113
+ uploadCommand: z.ZodString;
114
+ uploadCommandPowerShell: z.ZodString;
115
+ uploadPageUrl: z.ZodNullable<z.ZodString>;
116
+ statusUrl: z.ZodString;
117
+ note: z.ZodString;
118
+ }> = z.object({
119
+ grantId: z.string().min(1),
120
+ state: FileUploadGrantStateSchema,
121
+ expiresAt: z.string().datetime(),
122
+ singleUse: z.literal(true),
123
+ target: z.object({
124
+ resourceType: z.string().min(1),
125
+ fieldName: z.string().min(1),
126
+ operation: FileUploadGrantOperationSchema,
127
+ resourceId: z.string().min(1).nullable(),
128
+ }),
129
+ /** From the field's own constraint resolver — the same one the upload enforces, so the two cannot disagree. */
130
+ constraints: z.object({
131
+ maxBytes: z.number().int().positive(),
132
+ /** Empty means every type is accepted. */
133
+ allowedMimeTypes: z.array(z.string()),
134
+ }),
135
+ uploadUrl: z.string().url(),
136
+ /** The credential travels in a HEADER on the curl form: paths are logged by every proxy, headers are not. */
137
+ uploadHeader: z.object({ name: z.string().min(1), value: z.string().min(1) }),
138
+ /** No `-f`: on a refusal the JSON error body is the only thing that tells the caller why. */
139
+ uploadCommand: z.string().min(1),
140
+ /** In PowerShell `curl` aliases Invoke-WebRequest, which does not understand `-F`; the real binary is `curl.exe`. */
141
+ uploadCommandPowerShell: z.string().min(1),
142
+ /** `null` when the application declares no frontend service — a headless API has no page to hand a human. */
143
+ uploadPageUrl: z.string().url().nullable(),
144
+ statusUrl: z.string().url(),
145
+ note: z.string().min(1),
146
+ });
147
+ export type FileUploadGrant = z.infer<typeof FileUploadGrantSchema>;
148
+
149
+ /**
150
+ * What the public status read returns. The token is the credential, so the read is unauthenticated
151
+ * and returns only what the drop page needs to render and the agent needs to learn the `fileId`:
152
+ * never the file's name (the status URL may be pasted around).
153
+ */
154
+ export const FileUploadGrantStatusSchema: z.ZodObject<{
155
+ grantId: z.ZodString;
156
+ state: z.ZodEnum<typeof FileUploadGrantState>;
157
+ expiresAt: z.ZodString;
158
+ target: z.ZodObject<{
159
+ resourceType: z.ZodString;
160
+ fieldName: z.ZodString;
161
+ operation: z.ZodEnum<{ [K in FileUploadGrantOperation]: K }>;
162
+ resourceId: z.ZodNullable<z.ZodString>;
163
+ }>;
164
+ constraints: z.ZodObject<{ maxBytes: z.ZodNumber; allowedMimeTypes: z.ZodArray<z.ZodString> }>;
165
+ uploadUrl: z.ZodString;
166
+ uploadHeaderName: z.ZodString;
167
+ file: z.ZodNullable<z.ZodObject<{ fileId: z.ZodString; status: z.ZodEnum<typeof FileStatus> }>>;
168
+ }> = z.object({
169
+ grantId: z.string().min(1),
170
+ state: FileUploadGrantStateSchema,
171
+ expiresAt: z.string().datetime(),
172
+ target: z.object({
173
+ resourceType: z.string().min(1),
174
+ fieldName: z.string().min(1),
175
+ operation: FileUploadGrantOperationSchema,
176
+ resourceId: z.string().min(1).nullable(),
177
+ }),
178
+ constraints: z.object({ maxBytes: z.number().int().positive(), allowedMimeTypes: z.array(z.string()) }),
179
+ uploadUrl: z.string().url(),
180
+ /** The page sets this header itself; the token it already holds is the value. */
181
+ uploadHeaderName: z.string().min(1),
182
+ /** `null` until redeemed, or when the post-redemption write-back failed (re-read the resource instead). */
183
+ file: z.object({ fileId: z.string().min(1), status: z.enum(FileStatus) }).nullable(),
184
+ });
185
+ export type FileUploadGrantStatus = z.infer<typeof FileUploadGrantStatusSchema>;
186
+
187
+ /** Body accepted by both mint doors. */
188
+ export const FileUploadGrantMintRequestSchema: z.ZodObject<{ expiresInMinutes: z.ZodOptional<z.ZodNumber> }> = z.object({
189
+ expiresInMinutes: z.number().int().min(1).max(FILE_UPLOAD_GRANT_ABSOLUTE_MAX_MINUTES).optional(),
190
+ }).strict();
191
+ export type FileUploadGrantMintRequest = z.infer<typeof FileUploadGrantMintRequestSchema>;
192
+ ```
@@ -77,11 +77,13 @@ export enum EngineCapability {
77
77
  * extraction into `AI_LLM` would have made one `selection[AI_LLM].primary` decide all three,
78
78
  * which is exactly the defect that split `AI_EMBEDDINGS` out of `AI_LLM`.
79
79
  *
80
- * ## Not to be confused with `DOCUMENT_GENERATION`
80
+ * ## Not to be confused with PDF GENERATION
81
81
  *
82
- * `DOCUMENT_GENERATION` is PDF *generation* — templates and data become bytes. This is the
83
- * opposite direction: bytes become text. The names are adjacent and the capabilities are
84
- * unrelated; nothing routes between them.
82
+ * PDF generation — templates and data become bytes — is the `pdfTemplates` surface, done
83
+ * in-process and with no provider slot of its own. This is the opposite direction: bytes become
84
+ * text. The two are unrelated and nothing routes between them. (There WAS an
85
+ * `EngineCapability.DOCUMENT_GENERATION` that this paragraph used to name; it was withdrawn
86
+ * because no provider capability could ever fill it.)
85
87
  *
86
88
  * ## Absence is benign, and that is load-bearing
87
89
  *
@@ -108,8 +110,26 @@ export enum EngineCapability {
108
110
  */
109
111
  AI_CODING_AGENT = 'AI_CODING_AGENT',
110
112
 
111
- DOCUMENT_GENERATION = 'DOCUMENT_GENERATION',
112
- ANTIVIRUS_SCANNING = 'ANTIVIRUS_SCANNING',
113
+ /*
114
+ * WITHDRAWN 2026-09-03: `DOCUMENT_GENERATION` and `ANTIVIRUS_SCANNING` were members here and are
115
+ * not any more. Neither could ever be filled — `PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY` had no
116
+ * entry pointing at either, so no provider capability token could claim the slot — while both were
117
+ * classified `SELECT_ONE`, which asserts that exactly one provider must be selected. Selecting one
118
+ * of zero candidates is not a resolution mode.
119
+ *
120
+ * Both capabilities are real and both are delivered elsewhere, which is why withdrawing the slots
121
+ * costs nothing: antivirus scanning is `InfraCapability.ANTIVIRUS_SCANNING`, fulfilled by ClamAV
122
+ * and consumed by `FileScanningBackendService`; PDF generation is the in-process `pdfTemplates`
123
+ * surface, with `InfraCapability.DOCUMENT_RENDERING` (Gotenberg) provisioned beside it. Neither
124
+ * has an external provider, and neither is planned to.
125
+ *
126
+ * Removing `ANTIVIRUS_SCANNING` also removes a collision: the identical spelling named an engine
127
+ * slot nothing could fill AND a live infra capability, in two packages, so a reader grepping the
128
+ * word landed in whichever they searched first.
129
+ *
130
+ * If a hosted AV or document-rendering vendor is ever adopted, the member comes back WITH its
131
+ * `PROVIDER_CAPABILITY_TO_ENGINE_CAPABILITY` entry and its own JSDoc in the same change.
132
+ */
113
133
 
114
134
  FRONTEND_ERROR_MONITORING = 'FRONTEND_ERROR_MONITORING',
115
135
  FRONTEND_PRODUCT_ANALYTICS = 'FRONTEND_PRODUCT_ANALYTICS',
@@ -211,8 +231,8 @@ independent choices. Vendors are not equally good at all three and their pricing
211
231
  a unit — OCR is billed per PAGE, embeddings per token — so fusing any two of them into one selection
212
232
  would force a procurement decision nobody wants to make.
213
233
 
214
- Not to be confused with `EngineCapability.DOCUMENT_GENERATION`, which is PDF *generation* and is the
215
- opposite direction. Nothing routes between them.
234
+ Not to be confused with PDF *generation*, which is the opposite direction and is handled by the
235
+ `pdfTemplates` surface rather than by a provider selection. Nothing routes between them.
216
236
 
217
237
  ### Selecting a provider is only HALF the wiring
218
238
 
@@ -52,6 +52,21 @@ export interface ForeignKeyStructuralParams {
52
52
  * (e.g. `referrerScopeType`). Without it, `polymorphicVariants` is rename-only.
53
53
  */
54
54
  polymorphicDiscriminatorField?: string;
55
+ /**
56
+ * EXPLICIT target resource type, for an FK whose FIELD NAME cannot resolve it.
57
+ *
58
+ * The frontend resolves a reference field's target through the field-name → resource map
59
+ * (enriched from relationships' `foreignKeyField`). That works only when the field is named for
60
+ * its target (`assignedToUserId`) or a relationship declares it — and relationship FK names are
61
+ * held to the `Id`/`Ids` convention. A field that references a resource under its OWN vocabulary
62
+ * (`icpRefs` inside a specification document, a rename-only FK) has no honest entry in that map;
63
+ * declaring the target here lets the reference display resolve, label and navigate it without
64
+ * bending the field's name or the map's uniqueness.
65
+ *
66
+ * Takes precedence over the field-name map; polymorphic variants (above) still win over both,
67
+ * because a per-record discriminator is more specific than any static declaration.
68
+ */
69
+ referencedResourceType?: string;
55
70
  }
56
71
  ```
57
72
 
@@ -82,6 +82,12 @@ export const StringDisplayMode = {
82
82
  * `TEXTAREA` — the edit side stays markdown SOURCE either way.
83
83
  */
84
84
  MARKDOWN: 'markdown',
85
+ /**
86
+ * A MACHINE IDENTIFIER — a slug, a ref, an addressable key (`success-criterion-…`). Rendered
87
+ * small, muted and monospace so it stays greppable and verbatim while RECEDING behind the prose
88
+ * it identifies. Use for values a reader needs to copy or trace, never to read as content.
89
+ */
90
+ IDENTIFIER: 'identifier',
85
91
  COLOR: 'color',
86
92
  LINK: 'link',
87
93
  EMAIL: 'email',
@@ -434,6 +434,26 @@ export const CardActionPlacementSchema = z.object({
434
434
  /** Authored 2-axis card action placement — inferred from {@link CardActionPlacementSchema}. */
435
435
  export type CardActionPlacement = z.infer<typeof CardActionPlacementSchema>;
436
436
 
437
+ /**
438
+ * Who paints the identity GLYPH on this operation's page header.
439
+ *
440
+ * The header band renders the resource's registry icon beside the identity line by default. A
441
+ * `layout.header` template that composes its own record-linked glyph (a per-row kind icon, a
442
+ * per-family symbol) would otherwise sit BESIDE the resource icon — two glyphs naming one thing.
443
+ *
444
+ * Declared at the OPERATION layer rather than detected from the template, deliberately: the
445
+ * resource icon renders before the template mounts, so detection could only suppress it after the
446
+ * fact — a glyph that flashes and vanishes on every load. Mirrors
447
+ * `SummaryTitlePlacement.TEMPLATE_OWNED`, the same contract one surface over: ceding a
448
+ * framework-owned element to the template is a declaration, not an inference.
449
+ */
450
+ export enum HeaderIconPlacement {
451
+ /** The framework renders the resource's registry icon (default). */
452
+ AUTO = 'auto',
453
+ /** The header template owns the glyph; the framework renders none. */
454
+ TEMPLATE_OWNED = 'template_owned',
455
+ }
456
+
437
457
  export const ResourceOperationFrontendConfigSchema = z.object({
438
458
  /**
439
459
  * The operation's frontend **surface** — see {@link ResourceOperationFrontendSurface}.
@@ -445,6 +465,8 @@ export const ResourceOperationFrontendConfigSchema = z.object({
445
465
  * Replaces the former `isAddressable` boolean — read via `isOperationAddressable()`.
446
466
  */
447
467
  surface: z.enum(ResourceOperationFrontendSurface),
468
+ /** Who paints the page header's identity glyph — see {@link HeaderIconPlacement}. Omitted = AUTO. */
469
+ headerIconPlacement: z.enum(HeaderIconPlacement).optional(),
448
470
  /**
449
471
  * How this operation's action is surfaced — see {@link ActionVisibility}. Omitted
450
472
  * (the common case) behaves as `ALWAYS`.
@@ -524,6 +546,30 @@ export const ResourceOperationFrontendConfigSchema = z.object({
524
546
  * without a date heading rather than being dropped.
525
547
  */
526
548
  temporalGroupField: z.string().optional(),
549
+ /**
550
+ * Group CARDS-mode rows into buckets by this ENUM field, rendering the
551
+ * enum value's own label as a heading between groups.
552
+ *
553
+ * Sibling of {@link temporalGroupField}, and deliberately NOT the same
554
+ * algorithm. Temporal grouping ADJACENT-MERGES in server order, because
555
+ * dates are open-ended and a page can legitimately revisit one. An enum is
556
+ * a CLOSED, ORDERED vocabulary, so its buckets are emitted in the enum's
557
+ * DECLARATION ORDER regardless of the order rows arrived in — the
558
+ * declaration is the authority for "which concern comes first", and a
559
+ * server sort cannot express it without a second, drifting copy of that
560
+ * order. Rows are therefore collected across the whole fetched page rather
561
+ * than merged adjacently, and no sort needs pairing with it.
562
+ *
563
+ * Headings resolve through `tResourceFieldEnumValue` — the SAME source the
564
+ * filters panel and the promoted quick-filter tabs use, so a bucket
565
+ * heading and its tab can never disagree.
566
+ *
567
+ * Ignored in TABLE mode (column sorting owns the ordering there). Rows
568
+ * whose value is absent, or outside the vocabulary, render in a trailing
569
+ * bucket with no heading rather than being dropped — the same fail-open
570
+ * the temporal grouping makes.
571
+ */
572
+ enumGroupField: z.string().optional(),
527
573
  /**
528
574
  * CARDS-mode arrangement — a single-column bordered LIST (default) or an
529
575
  * N-column responsive GRID. See {@link CardLayoutStyle}. `columns` (1–6) is
@@ -577,6 +623,49 @@ export const ResourceOperationFrontendConfigSchema = z.object({
577
623
  * into a description via the `.describe()` decorator.
578
624
  */
579
625
  hasDescription: z.boolean().optional(),
626
+ /**
627
+ * What happens to an ADJACENT zone (secondary / companion) this operation
628
+ * splits into, once that zone's last content is dismissed — overriding the
629
+ * zone's own `onEmpty` while this operation occupies primary.
630
+ *
631
+ * The zone-level `ZoneConfig.onEmpty` is one value for every destination that
632
+ * splits into that zone, and destinations legitimately disagree: a LIST wants
633
+ * the detail pane to stay put (`EMPTY_STATE`) so the layout does not reflow
634
+ * while a reviewer steps through rows, while a CANVAS wants its width back
635
+ * (`COLLAPSE`) the moment nothing is selected. Both share one secondary zone,
636
+ * so without this override one of them is always wrong.
637
+ *
638
+ * Declared on the SOURCE operation — the one occupying primary — not on the
639
+ * operation that lands in the pane: it answers "what should MY layout do when
640
+ * the detail closes", which is a property of the surface being returned to.
641
+ *
642
+ * Omitted (the common case) defers to the zone, which itself defaults to
643
+ * `ZoneEmptyBehavior.COLLAPSE`. Resolution order is destination → zone →
644
+ * COLLAPSE; see `resolveZoneEmptyBehavior`.
645
+ */
646
+ adjacentZoneOnEmpty: z.enum(ZoneEmptyBehavior).optional(),
647
+ /**
648
+ * How wide this destination's content may grow in the zone, in the framework's shared width
649
+ * vocabulary — the SAME `ResponsiveMaxWidth` a Surface, a `DisplayLayout` and a `FormLayout` use.
650
+ *
651
+ * Omitted (the common case) is `'content'`: capped and centred at `var(--content-max-width, 80rem)`,
652
+ * right for a form, a list or a detail page and wrong only for content whose value IS the space it
653
+ * occupies — a board, a wide table, a canvas — which declare `'none'`.
654
+ */
655
+ zoneContentMaxWidth: z.enum(RESPONSIVE_MAX_WIDTH_VALUES).optional(),
656
+ /**
657
+ * Whether this destination's content fills the zone's HEIGHT as well.
658
+ *
659
+ * `true` makes the zone's content boundary a definite-height flex column, so this view's root may use
660
+ * `flex-1 min-h-0` and resolve against something real. Without it a canvas has no intrinsic height
661
+ * and collapses to zero — which is why one had to hand-roll `h-[70vh]`, sizing against the WINDOW
662
+ * rather than the container it sits in. PRIMARY only: an adjacent zone scrolls, so a filling child
663
+ * and a scrolling parent contradict each other.
664
+ *
665
+ * Separate from the width above ON PURPOSE — see `zone-content-geometry.ts` for why the enum that
666
+ * fused them could not express a capped width with a definite height.
667
+ */
668
+ zoneContentFillsHeight: z.boolean().optional(),
580
669
  });
581
670
 
582
671
  /**
@@ -354,11 +354,42 @@ export interface ForeignKeyUIParams {
354
354
  // ARRAY UI
355
355
  //------------------------------------------------------------------------------------------------
356
356
 
357
+ /**
358
+ * List marker treatment for a PRIMITIVE array's display items.
359
+ *
360
+ * Its own enum rather than a new `DisplayDirection` member on purpose: direction answers "which
361
+ * axis do items flow on", marker style answers "does each item announce itself as one of several" —
362
+ * merging them would make `BULLETS × horizontal` an unrepresentable-but-meaningful combination and
363
+ * overload an enum that alignment code also reads.
364
+ */
365
+ export enum ArrayListStyle {
366
+ /** Bare stacked values — the historical default. */
367
+ PLAIN = 'plain',
368
+ /** A real bulleted list. For enumerations a reader SCANS — alternatives, consequences, principles — where bare stacked lines read as one run-on paragraph. */
369
+ BULLETS = 'bullets',
370
+ /**
371
+ * A RULED list: one hairline between entries, none above the first or below the last.
372
+ *
373
+ * For OBJECT entries a reader compares — an ICP after an ICP, a persona after a persona — where
374
+ * spacing alone stops saying where one ends. It is the alternative to framing each entry as a
375
+ * card, and the reason to prefer it is compounding chrome: inside a section that is already a
376
+ * bounded region, a card per entry is a third frame around content that has two. Unlike
377
+ * {@link ArrayListStyle.BULLETS}, which is for primitive lines, this is for entries.
378
+ */
379
+ SEPARATED = 'separated',
380
+ }
381
+
357
382
  export interface ArrayUIDisplayParams extends PrimitiveUIBaseDisplayParams {
358
383
  /** Direction for rendering items in display context. */
359
384
  displayMode?: DisplayDirection;
360
385
  /** Max items shown in display (rest truncated). */
361
386
  maxItems?: number;
387
+ /**
388
+ * Marker treatment for PRIMITIVE items (see {@link ArrayListStyle}). No effect on object arrays —
389
+ * their items are cards/rows, not list lines — and no effect on horizontal flow, where markers
390
+ * have no line to anchor to.
391
+ */
392
+ listStyle?: ArrayListStyle;
362
393
  }
363
394
 
364
395
  /**
@@ -449,6 +480,18 @@ export interface ObjectUIDisplayParams extends PrimitiveUIBaseDisplayParams {
449
480
  displayMode?: DisplayDirection;
450
481
  /** Max properties shown in display (rest truncated). */
451
482
  maxItems?: number;
483
+ /**
484
+ * The member that IS this object's headline when the object renders as a unit (a nested object
485
+ * block, an array item card): it renders FIRST, label hidden, with title emphasis; the remaining
486
+ * members follow in schema order.
487
+ *
488
+ * Explicit rather than detected: "the first string field" guesses wrong the moment a stable
489
+ * identifier precedes the human statement in the schema — exactly the shape ref-addressable
490
+ * entries have (`ref` first, `statement` second), where detection would headline the machine key.
491
+ * Names a member that does not exist → ignored, so a schema rename degrades to the old uniform
492
+ * rendering instead of crashing the display.
493
+ */
494
+ primaryField?: string;
452
495
  }
453
496
 
454
497
  export type ObjectUIEditParams = PrimitiveUIBaseEditParams;
@@ -22,6 +22,9 @@ export interface PrimitiveUIBaseDisplayParams {
22
22
  /** Chrome layout mode for the field wrapper in display context. */
23
23
  chromeMode?: ResponsiveAware<DisplayChromeMode>;
24
24
 
25
+ /** Label styling, orthogonal to `chromeMode` (which decides LAYOUT). See `DisplayLabelStyle`. */
26
+ labelStyle?: DisplayLabelStyle;
27
+
25
28
  /** Force-hide specific chrome sub-elements in display context. Plain object = all breakpoints. */
26
29
  forceHide?: ResponsiveAware<ForceHideDisplayConfig>;
27
30
 
@@ -85,7 +85,7 @@ concluding the rail is correct.
85
85
  Section and category names are generated into the `settings_hub.*` namespace
86
86
  from your placements. Re-run label generation after adding or removing a
87
87
  placement.
88
- // TODO CLI COMMAND: wildo i18n labels
88
+ Run `wildo generate labels`.
89
89
 
90
90
  ## References
91
91
 
@@ -253,6 +253,7 @@ export const specificationsCompanionExports: SpecificationsCompanionExports<
253
253
  * decisions remain private runtime state.
254
254
  */
255
255
  documentFactSpecification: applicationDocumentFactSpecification,
256
+ authoredDocumentFactSpecification: applicationAuthoredDocumentFactSpecification,
256
257
  /**
257
258
  * The accepted typed build plan (`build-plan` family, `BuildPlanTaskGraph`).
258
259
  * The bottom-up dispatch playbook's coding owner reads it from the verified
@@ -90,6 +90,9 @@ export interface SpecificationsCompanionExports<
90
90
  // a partial register is useful and its holes are REPORTED per provider against
91
91
  // the application's configured set, rather than blocking anything.
92
92
  TProcessorRegister = ApplicationProcessorRegister,
93
+ // Appended STRICTLY LAST: the human half of the document facts, in its own
94
+ // family, because the derived one is REGENERATED whole (#192).
95
+ TAuthoredDocumentFactSpecification = ApplicationAuthoredDocumentFactSpecification,
93
96
  > {
94
97
  resourceSpecifications: TResourceSpecifications;
95
98
  applicationBusinessSemanticsSnapshot?: TBusinessSemanticsSnapshot;
@@ -474,6 +477,23 @@ export interface SpecificationsCompanionExports<
474
477
  * Omitting it is honest: unresolved document facts remain visible gaps.
475
478
  */
476
479
  documentFactSpecification?: TDocumentFactSpecification;
480
+ /**
481
+ * Accepted application governed-document facts **only a human may establish** — a creator decision
482
+ * or a qualified review (`document-facts-authored`).
483
+ *
484
+ * The same shape as the slot above, and a separate family on purpose. `refinement.document-facts`
485
+ * rewrites the derived file whole, so a human decision sharing that file is destroyed on the next
486
+ * run with nothing to notice: there is no compare-and-swap here, deliberately
487
+ * (`.claude/rules/one-source-of-truth.md` Rule 0). Two families put the two writers out of each
488
+ * other's reach.
489
+ *
490
+ * No producer may write this family — it has no generation contract, and that absence is the design
491
+ * rather than an omission.
492
+ *
493
+ * A reader wanting "the application's facts" needs BOTH slots. `collectComplianceDocumentFactAvailability`
494
+ * is variadic for exactly that reason.
495
+ */
496
+ authoredDocumentFactSpecification?: TAuthoredDocumentFactSpecification;
477
497
  /**
478
498
  * WHO else processes this application's personal data — legal identity, processing region and the
479
499
  * processor's own subprocessors (issue #88).
@@ -84,15 +84,34 @@ export enum CodeDeclarationKind {
84
84
  }
85
85
 
86
86
  /**
87
- * Public-import-oriented symbol reference used by semantic specifications.
87
+ * Symbol reference used by semantic specifications to address one exported symbol.
88
88
  *
89
- * Downstream transposers/prompts should prefer these refs over file-path
90
- * guesses so generated code imports the right public symbol.
89
+ * Downstream transposers and prompts prefer these refs over file-path guesses, so a
90
+ * ref has to be honest about WHICH KIND of address it carries. Two facts are useful
91
+ * and they are not the same fact, so they have separate fields:
92
+ *
93
+ * - `importPath` is an IMPORT SPECIFIER — something a generated `import` statement
94
+ * can actually resolve, declared in the owning package's `package.json#exports`.
95
+ * - `filePathHint` is a LOCATION — where a maintainer opens the file. It is never
96
+ * rendered as something importable.
97
+ *
98
+ * Authoring a source path in `importPath` is the defect issue #150 records: it made
99
+ * the companion hand a coding agent an import specifier that cannot resolve, because
100
+ * an application package typically declares no export map entry for its internal
101
+ * modules. When in doubt, author `filePathHint` — a location that is merely useful
102
+ * is better than an address that is wrong.
91
103
  */
92
104
  export interface CodeSymbolRef {
93
105
  /** Package name to import from (for example `@wildo-ai/saas-models`). */
94
106
  packageName: string;
95
- /** Optional public subpath when the package root is not the import target. */
107
+ /**
108
+ * Optional PUBLIC SUBPATH, when the package root is not the import target.
109
+ *
110
+ * Must be a subpath the owning package declares in `package.json#exports`, so that
111
+ * `${packageName}/${importPath}` is a resolvable import specifier. If the symbol has
112
+ * no public door, leave this unset and author `filePathHint` instead — do NOT put a
113
+ * path inside `src/` here.
114
+ */
96
115
  importPath?: string;
97
116
  /** Literal exported symbol name. */
98
117
  exportName: string;
@@ -100,7 +119,14 @@ export interface CodeSymbolRef {
100
119
  symbolKind: CodeSymbolKind;
101
120
  /** More specific declaration family for code-generation handling. */
102
121
  declarationKind?: CodeDeclarationKind;
103
- /** Optional local-path hint for companion-side tooling/debugging. */
122
+ /**
123
+ * Optional MODULE LOCATION — where the symbol is defined inside the owning package,
124
+ * relative to that package's source root (for example
125
+ * `modules/tasks-manager/resources/tasks/tasks.ui-behavior`).
126
+ *
127
+ * This is a navigation aid, not an import target: it is rendered as a location and
128
+ * must never be concatenated onto `packageName` to build an import specifier.
129
+ */
104
130
  filePathHint?: string;
105
131
  /** Extra caveats or usage notes for downstream prompts. */
106
132
  notes?: string[];
@@ -2356,6 +2356,28 @@ export type ResourceSpecificationConfig<
2356
2356
  businessRole: string;
2357
2357
  /** How the resource evolves over time (lifecycle semantics). */
2358
2358
  lifecycleRole?: string;
2359
+ /**
2360
+ * Which part of the product this resource belongs to, WITHIN its owner.
2361
+ *
2362
+ * A second grouping axis under the one that already exists. An application's resources are grouped
2363
+ * by the module that registers them; the engine's are grouped by nothing, so every surface that
2364
+ * has to present them — the domain-model graph, `wildo context`, generated documentation, an
2365
+ * application-creation playbook — meets one flat set of 85 and either shows it undifferentiated or
2366
+ * invents a grouping of its own and drifts from the next surface that does the same.
2367
+ *
2368
+ * Typed `string` and OPEN on purpose. The engine's values are a closed vocabulary with a named
2369
+ * runtime source, {@link EngineResourceSubDomain} in this package's `engine` surface, and engine
2370
+ * specs must use it. An application's sub-domains are its own — this repository cannot enumerate
2371
+ * a vocabulary it does not own, and a union that tried would refuse every real application.
2372
+ *
2373
+ * Optional, and its absence means exactly "unclassified" rather than "belongs to a default". A
2374
+ * consumer grouping by it must carry a bucket for that and say so; silently folding unclassified
2375
+ * rows into a real group is how a grouping starts lying.
2376
+ *
2377
+ * Distinct from {@link ResourceSpecificationConfig.resourcePrimaryScope}, which answers WHO a row
2378
+ * belongs to. This answers what it is ABOUT, and one sub-domain spans several scopes.
2379
+ */
2380
+ subDomain?: string;
2359
2381
  /**
2360
2382
  * Intended READER of this resource's generated labels — the register the label
2361
2383
  * generator should adopt: {@link LabelAudience.END_USER} for consumer surfaces