@wildo-ai/framework-knowledge 1.1.2 → 1.1.3

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 (287) 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 +228 -6
  4. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  5. package/dist/esm/framework-knowledge.schemas.d.ts +1 -2
  6. package/dist/esm/framework-knowledge.schemas.d.ts.map +1 -1
  7. package/dist/esm/framework-knowledge.schemas.js.map +1 -1
  8. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +3 -4
  9. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts.map +1 -1
  10. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +4 -4
  11. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  12. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +3 -4
  13. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -1
  14. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +4 -4
  15. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -1
  16. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +0 -1
  17. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -1
  18. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +0 -1
  19. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -1
  20. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +0 -1
  21. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -1
  22. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +0 -1
  23. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -1
  24. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +1 -2
  25. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -1
  26. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +1 -2
  27. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -1
  28. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +2 -3
  29. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
  30. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +3 -3
  31. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
  32. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +1 -2
  33. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -1
  34. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +1 -2
  35. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -1
  36. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts +0 -1
  37. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -1
  38. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js +0 -1
  39. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js.map +1 -1
  40. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +0 -1
  41. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -1
  42. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +0 -1
  43. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -1
  44. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +0 -1
  45. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -1
  46. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +0 -1
  47. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -1
  48. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +0 -1
  49. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -1
  50. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +0 -1
  51. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -1
  52. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts +0 -1
  53. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -1
  54. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +0 -1
  55. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -1
  56. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts +0 -2
  57. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.d.ts.map +1 -1
  58. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js +2 -2
  59. package/dist/esm/playbooks/top_down.compliance-analysis/playbook.definition.js.map +1 -1
  60. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts +0 -1
  61. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.d.ts.map +1 -1
  62. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js +0 -1
  63. package/dist/esm/playbooks/top_down.compliance-conception/playbook.definition.js.map +1 -1
  64. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts +0 -1
  65. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  66. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js +0 -1
  67. package/dist/esm/playbooks/top_down.compliance-evidence-adequacy/playbook.definition.js.map +1 -1
  68. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +0 -1
  69. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -1
  70. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +0 -1
  71. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -1
  72. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts +0 -1
  73. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.d.ts.map +1 -1
  74. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js +0 -1
  75. package/dist/esm/playbooks/top_down.compliance-research/playbook.definition.js.map +1 -1
  76. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts +0 -2
  77. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -1
  78. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js +9 -4
  79. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js.map +1 -1
  80. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts +0 -1
  81. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -1
  82. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js +0 -1
  83. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js.map +1 -1
  84. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts +0 -1
  85. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -1
  86. package/dist/esm/playbooks/top_down.market-research/playbook.definition.js +0 -1
  87. package/dist/esm/playbooks/top_down.market-research/playbook.definition.js.map +1 -1
  88. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +0 -1
  89. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -1
  90. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +0 -1
  91. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -1
  92. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +0 -1
  93. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -1
  94. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +0 -1
  95. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -1
  96. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +0 -1
  97. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -1
  98. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +0 -1
  99. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -1
  100. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +0 -1
  101. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -1
  102. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +0 -1
  103. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -1
  104. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +0 -1
  105. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -1
  106. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +0 -1
  107. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -1
  108. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +0 -1
  109. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -1
  110. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +0 -1
  111. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -1
  112. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  113. package/dist/knowledge/manifest.json +8 -9
  114. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +13 -70
  115. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +11 -19
  116. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +5 -88
  117. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +15 -8
  118. package/dist/knowledge/playbooks/bottom_up.build-scale/method.md +4 -5
  119. package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +15 -8
  120. package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +4 -0
  121. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +8 -7
  122. package/dist/knowledge/playbooks/bottom_up.foundation/method.md +22 -49
  123. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +8 -17
  124. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +15 -780
  125. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +11 -11
  126. package/dist/knowledge/playbooks/refinement.document-facts/method.md +20 -141
  127. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +15 -10
  128. package/dist/knowledge/playbooks/top_down.brand-identity/method.md +3 -2
  129. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +16 -11
  130. package/dist/knowledge/playbooks/top_down.business-model/playbook.json +14 -6
  131. package/dist/knowledge/playbooks/top_down.capability-map/method.md +4 -2
  132. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +16 -7
  133. package/dist/knowledge/playbooks/top_down.compliance-posture/method.md +4 -21
  134. package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +65 -16
  135. package/dist/knowledge/playbooks/{top_down.market-snapshot-produce → top_down.market-analysis}/evaluation-protocol.json +1 -1
  136. package/dist/knowledge/playbooks/{top_down.market-snapshot-produce → top_down.market-analysis}/evaluation-treatment.json +1 -1
  137. package/dist/knowledge/playbooks/top_down.market-analysis/method.md +165 -51
  138. package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +43 -23
  139. package/dist/knowledge/playbooks/top_down.phase-gate/method.md +4 -8
  140. package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +7 -9
  141. package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +7 -9
  142. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +15 -7
  143. package/dist/knowledge/playbooks/top_down.scope-roadmap/method.md +3 -3
  144. package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +16 -11
  145. package/dist/knowledge/playbooks/top_down.value-proposition/method.md +4 -2
  146. package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +15 -7
  147. package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +2 -2
  148. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +16 -11
  149. package/dist/knowledge/references/build-plan.task-graph.config.md +1 -45
  150. package/dist/knowledge/references/companion.technical-doc.service.md +2 -102
  151. package/dist/knowledge/references/example.config.app-shell.full.md +5 -0
  152. package/dist/knowledge/references/example.module.companion-exports.full.md +0 -1
  153. package/dist/knowledge/references/example.provider.backend-module-shape.md +0 -7
  154. package/dist/knowledge/references/example.resource.add-resource.module-factory-map.md +1 -0
  155. package/dist/knowledge/references/platform.config.saas.md +0 -51
  156. package/dist/knowledge/references/presets.models.surface-policy.md +10 -19
  157. package/dist/knowledge/references/saas.external-data.admin-endpoints.md +48 -0
  158. package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +11 -31
  159. package/dist/knowledge/references/saas.frontend.app-level-component.vocabulary.md +1 -0
  160. package/dist/knowledge/references/saas.frontend.composite-view.authoring.md +0 -45
  161. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +0 -198
  162. package/dist/knowledge/references/saas.models.data-mode-read-list.md +0 -164
  163. package/dist/knowledge/references/saas.models.engine-capabilities.md +6 -26
  164. package/dist/knowledge/references/saas.models.http-api-binding.md +29 -3
  165. package/dist/knowledge/references/saas.models.provider-capabilities.md +3 -4
  166. package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +2 -4
  167. package/dist/knowledge/references/saas.models.resource-config.resource-configuration.md +0 -2
  168. package/dist/knowledge/references/saas.models.resource-config.resources-registry.md +0 -14
  169. package/dist/knowledge/references/saas.specifications.application-document-fact-specification.contract.md +31 -11
  170. package/dist/knowledge/references/saas.specifications.assurance-document-blueprint.contract.md +2 -32
  171. package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +6 -29
  172. package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +0 -56
  173. package/dist/knowledge/references/saas.specifications.resource-spec-config.md +0 -22
  174. package/dist/knowledge/references/zod.decorators.chainable-runtime.md +0 -26
  175. package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +0 -45
  176. package/dist/knowledge/references/zod.decorators.display-edit-modes.md +1 -7
  177. package/dist/knowledge/references/zod.decorators.field-spec-params.md +5 -31
  178. package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +1 -44
  179. package/dist/knowledge/references/zod.decorators.primitive-ui.md +0 -3
  180. package/dist/knowledge/references/zod.decorators.schema-metadata.md +0 -1
  181. package/dist/knowledge/references/zod.decorators.shared-structural-params.md +0 -15
  182. package/dist/knowledge/registries/assurance-authority-bases.json +2 -3
  183. package/dist/knowledge/registries/framework-topics.json +11 -146
  184. package/dist/knowledge/registries/playbooks.json +18 -154
  185. package/dist/knowledge/registries/source-tags.json +630 -883
  186. package/dist/knowledge/skills/INDEX.md +3 -4
  187. package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +1 -2
  188. package/dist/knowledge/skills/compliance-document-authoring/SKILL.md +2 -16
  189. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-governance.md +9 -31
  190. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +74 -252
  191. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-service-terms.md +8 -26
  192. package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-fact-specification-contract.md +53 -97
  193. package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +21 -84
  194. package/dist/knowledge/skills/config-app-shell/SKILL.md +9 -31
  195. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +12 -31
  196. package/dist/knowledge/skills/config-design-system/SKILL.md +1 -23
  197. package/dist/knowledge/skills/config-design-system/references/framework-surface-policy-api.md +10 -19
  198. package/dist/knowledge/skills/config-navigation/SKILL.md +2 -75
  199. package/dist/knowledge/skills/config-saas/SKILL.md +2 -19
  200. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +9 -30
  201. package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +0 -51
  202. package/dist/knowledge/skills/configure-billing/references/example-backend-provider-module-shape.md +0 -7
  203. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +1 -2
  204. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +3 -4
  205. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +0 -56
  206. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +0 -56
  207. package/dist/knowledge/skills/module-companion-exports/SKILL.md +0 -1
  208. package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +0 -56
  209. package/dist/knowledge/skills/resource-add-field/SKILL.md +3 -3
  210. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +0 -213
  211. package/dist/knowledge/skills/resource-add-resource/SKILL.md +1 -2
  212. package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +2 -4
  213. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +0 -15
  214. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +2 -224
  215. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +0 -198
  216. package/dist/knowledge/skills/resource-external-data/SKILL.md +2 -0
  217. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +29 -3
  218. package/dist/knowledge/skills/resource-external-data/references/framework-pipeline-admin-endpoints-api.md +70 -0
  219. package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +1 -22
  220. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +8 -28
  221. package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +0 -1
  222. package/dist/knowledge/skills/resource-schema-authoring/references/decorator-layer-map.md +0 -17
  223. package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +0 -46
  224. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +0 -15
  225. package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +0 -26
  226. package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +1 -7
  227. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +0 -198
  228. package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +1 -44
  229. package/dist/knowledge/skills/resource-ui-behavior/references/framework-primitive-ui-api.md +0 -3
  230. package/dist/knowledge/skills/spec-companion-exports/SKILL.md +0 -1
  231. package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +0 -56
  232. package/dist/knowledge/skills/spec-resource-update/references/framework-field-spec-params-api.md +5 -31
  233. package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +0 -22
  234. package/dist/knowledge/skills/views-composite-authoring/references/framework-composite-view-contracts-api.md +0 -45
  235. package/dist/knowledge/topic-index.json +220 -725
  236. package/dist/tsconfig.build.tsbuildinfo +1 -1
  237. package/dist/tsconfig.tsbuildinfo +1 -1
  238. package/package.json +4 -4
  239. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +0 -1
  240. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +0 -51
  241. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +0 -43
  242. package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +0 -185
  243. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +0 -64
  244. package/dist/knowledge/playbooks/top_down.compliance-analysis/method.md +0 -41
  245. package/dist/knowledge/playbooks/top_down.compliance-analysis/playbook.json +0 -100
  246. package/dist/knowledge/playbooks/top_down.compliance-conception/method.md +0 -117
  247. package/dist/knowledge/playbooks/top_down.compliance-conception/playbook.json +0 -86
  248. package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/method.md +0 -61
  249. package/dist/knowledge/playbooks/top_down.compliance-evidence-adequacy/playbook.json +0 -41
  250. package/dist/knowledge/playbooks/top_down.compliance-research/method.md +0 -76
  251. package/dist/knowledge/playbooks/top_down.compliance-research/playbook.json +0 -42
  252. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/method.md +0 -56
  253. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +0 -42
  254. package/dist/knowledge/playbooks/top_down.market-research/method.md +0 -68
  255. package/dist/knowledge/playbooks/top_down.market-research/playbook.json +0 -44
  256. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +0 -239
  257. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +0 -67
  258. package/dist/knowledge/references/placement-plan.config.md +0 -330
  259. package/dist/knowledge/references/saas.frontend.display-layout.reading-measure.md +0 -34
  260. package/dist/knowledge/references/saas.frontend.navigation.operation-override.md +0 -45
  261. package/dist/knowledge/references/saas.frontend.public-shell.identity-mode.md +0 -65
  262. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +0 -58
  263. package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +0 -118
  264. package/dist/knowledge/references/saas.models.file-upload-grant.md +0 -179
  265. package/dist/knowledge/references/saas.models.navigation.surface-vocabulary.md +0 -124
  266. package/dist/knowledge/references/saas.models.navigation.transition-vocabulary.md +0 -99
  267. package/dist/knowledge/references/saas.models.navigation.zone-declaration.md +0 -127
  268. package/dist/knowledge/references/saas.models.resource-config.operation-variant-client-timeout.md +0 -42
  269. package/dist/knowledge/references/saas.specifications.application-authored-document-fact-specification.contract.md +0 -29
  270. package/dist/knowledge/references/zod.decorators.data-categories.md +0 -197
  271. package/dist/knowledge/rules/resource-schema-awareness.md +0 -77
  272. package/dist/knowledge/skills/config-app-shell/references/framework-public-shell-identity-api.md +0 -124
  273. package/dist/knowledge/skills/config-design-system/references/loading-placeholder-authoring.md +0 -47
  274. package/dist/knowledge/skills/config-navigation/references/framework-content-width-api.md +0 -98
  275. package/dist/knowledge/skills/config-navigation/references/framework-navigation-operation-override-api.md +0 -54
  276. package/dist/knowledge/skills/config-navigation/references/framework-navigation-vocabulary-api.md +0 -232
  277. package/dist/knowledge/skills/config-navigation/references/framework-navigation-zone-declaration-api.md +0 -149
  278. package/dist/knowledge/skills/config-navigation/references/how-navigation-resolves.md +0 -114
  279. package/dist/knowledge/skills/config-navigation/references/navigation-configuration-map.md +0 -133
  280. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +0 -111
  281. package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +0 -622
  282. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-file-upload-grant-contract.md +0 -192
  283. package/dist/knowledge/skills/resource-schema-authoring/references/framework-personal-data-category-api.md +0 -245
  284. package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +0 -134
  285. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +0 -65
  286. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +0 -127
  287. /package/dist/knowledge/playbooks/{top_down.market-snapshot-produce → top_down.market-analysis}/structured-artifact-action.json +0 -0
@@ -1,232 +0,0 @@
1
- # The vocabularies a navigation layout is written in
2
-
3
- Read this first. A `NavigationLayout` is almost entirely these closed vocabularies, and every field in
4
- the layout schema is one of them — so the schema is unreadable without them.
5
-
6
- Two questions, two vocabularies:
7
-
8
- - **What HAPPENS** — the transition verbs. Six of them, and each one answers "where does the content go
9
- relative to where I am".
10
- - **WHERE and HOW it renders** — the zones, the content model, the responsive collapse modes, and the
11
- appearance a split or an overlay takes.
12
-
13
- ## Import Origins
14
-
15
- - `@wildo-ai/saas-models`
16
-
17
- ## Source Excerpts
18
-
19
- ### Origin Package: `@wildo-ai/saas-models`
20
-
21
- ```typescript
22
- */
23
- export enum NavigationTransition {
24
- /**
25
- * Content added to the zone's stack (single) or as a new tab (tabbed).
26
- * Back navigation pops the stack or switches to the previous tab.
27
- * URL adds a new path segment.
28
- */
29
- PUSH = 'push',
30
- /**
31
- * Content replaces the current content in the zone. No stack entry — the previous
32
- * content is gone from the zone's state (but remains in browser history).
33
- * URL replaces the current segment.
34
- */
35
- REPLACE = 'replace',
36
- /**
37
- * Content opens in an adjacent zone (secondary or companion).
38
- * Creates a side-by-side layout. The source zone's content remains visible.
39
- * Back navigation un-splits (closes the adjacent zone).
40
- * URL adds a split segment.
41
- */
42
- SPLIT = 'split',
43
- /**
44
- * Content opens in a floating layer above the entire layout (dialog, sheet, or drawer).
45
- * The underlying layout remains visible but non-interactive.
46
- * Back navigation or Escape dismisses the overlay.
47
- * URL adds an overlay param/hash.
48
- */
49
- OVERLAY = 'overlay',
50
- /**
51
- * Element-level transformation within the current view. A specific item in a
52
- * list/section transforms from one mode to another (read → edit); a CREATE
53
- * materializes a new element beside the existing ones. The parent view stays,
54
- * the zone stack is unchanged, and surrounding items remain visible.
55
- *
56
- * Fundamentally different from `replace` (which swaps the entire zone content).
57
- * `inplace` operates at the element level, not the zone level.
58
- *
59
- * No lifecycle modifiers (`persistent`/`ephemeral`) are valid on `inplace`.
60
- * No appearance to configure — the element transforms within its existing slot.
61
- *
62
- * **It is the one transition that does not place content in a zone**, which is
63
- * why the controller hands it to the element-level host
64
- * (`InPlaceOperationContext`) instead of resolving a target zone for it. That
65
- * host is provided by the COLLECTION the element belongs to, so a transition
66
- * resolving to `inplace` on a surface with no collection above it — a detail
67
- * page, a breadcrumb, a picker — degrades to an OVERLAY.
68
- *
69
- * **It is TRANSIENT: no URL, and a reload returns the view to rest.** Earlier
70
- * revisions of this comment promised a query param (`?editing=<childId>` /
71
- * `?creating=<resourceType>`) and none was ever written. It is not written now
72
- * either, and that is a decision rather than an omission: an inline row-edit is
73
- * a momentary state of a listing, not a place — no comparable admin framework
74
- * deep-links one, and anything that should survive a reload or a back button
75
- * wants `push`. `ResourceOperationActionPresentation.INLINE`, the per-operation
76
- * tier that selects the same host, is transient for the same reason.
77
- *
78
- * @example
79
- * // Click "edit" on a child in parent's inline section → item transforms to edit form
80
- * transitions: { [CoreResourceOperation.UPDATE]: NavigationTransition.INPLACE }
81
- *
82
- * // Click "add" in a relationship section → create form appears inline in the list
83
- * transitions: { [CoreResourceOperation.CREATE]: NavigationTransition.INPLACE }
84
- */
85
- INPLACE = 'inplace',
86
- /**
87
- * Escape the current context and open content at primary scope.
88
- * Abandons the current context: overlays close, companion/secondary dismiss.
89
- * The promoted content becomes the primary zone's top content.
90
- *
91
- * Use case: a link within an overlay should open as a full primary view,
92
- * or a nested detail in a companion zone should "pop out" to primary.
93
- *
94
- * Fundamentally different from `push` (which stays in the current zone) and
95
- * from `replace` (which replaces content within the same zone). `promote`
96
- * crosses zones and always targets primary.
97
- *
98
- * No lifecycle modifiers (`persistent`/`ephemeral`) are valid on `promote`.
99
- * No appearance to configure — content fills primary (same as push/replace).
100
- *
101
- * URL serialization: full URL change (promoted resource becomes the primary route).
102
- *
103
- * @example
104
- * // From an overlay, a link should open as primary (close overlay, show in primary)
105
- * transitions: { [CoreResourceOperation.READ]: NavigationTransition.PROMOTE }
106
- */
107
- PROMOTE = 'promote',
108
- }
109
- ```
110
-
111
- ## Import Origins
112
-
113
- - `@wildo-ai/saas-models`
114
-
115
- ## Source Excerpts
116
-
117
- ### Origin Package: `@wildo-ai/saas-models`
118
-
119
- ```typescript
120
- */
121
- export enum NavigationZoneName {
122
- /** Main content area. Lists, root-level reads, primary workspace. Always exists. */
123
- PRIMARY = 'primary',
124
- /**
125
- * First adjacent zone. Detail content in list-detail patterns.
126
- * Only exists if declared in config. Appears when a `split` transition targets it.
127
- * Typical use: showing item details alongside a list.
128
- */
129
- SECONDARY = 'secondary',
130
- /**
131
- * Persistent supplementary content. Reference panels, docs, notes, threads.
132
- * Only exists if declared in config. Usually hidden by default (`defaultVisible: false`).
133
- * Activated by `split` with `persistent: true` or explicit user toggle.
134
- * Typical use: Slack thread panel, VS Code terminal, documentation sidebar.
135
- */
136
- COMPANION = 'companion',
137
- }
138
-
139
- /**
140
- * How a zone manages multiple items. Orthogonal to transitions.
141
- *
142
- * The transition says "content arrives" — the content model says
143
- * "how does the zone accommodate it." Any zone can use any content model,
144
- * regardless of which transitions it supports.
145
- */
146
- export enum NavigationZoneContentModel {
147
- /**
148
- * Navigation stack: new content pushes on top, previous preserved underneath.
149
- * Only one item visible at a time. Back navigation pops the stack.
150
- * `replace` replaces the top without adding to the stack.
151
- * This is the default for all zones.
152
- */
153
- SINGLE = 'single',
154
- /**
155
- * Parallel tabs: `push` creates a new tab (or activates existing for the same resource).
156
- * Tab bar is visible, showing all open tabs. No depth stack within tabs.
157
- * `replace` replaces the active tab's content. Close is an explicit action (not back).
158
- * When no tabs remain, `onEmpty` behavior applies.
159
- */
160
- TABBED = 'tabbed',
161
- }
162
-
163
- /**
164
- * Responsive collapse behavior when viewport shrinks below a zone's breakpoint.
165
- *
166
- * Only applies to secondary and companion zones. Primary never collapses.
167
- * When viewport grows back past the breakpoint, collapsed content migrates
168
- * back to its original zone (content is preserved).
169
- */
170
- export enum ResponsiveCollapseMode {
171
- /**
172
- * Zone hides. Its content joins primary's navigation stack.
173
- * The user sees the content in-context within primary.
174
- * Back navigation pops back to primary's previous content.
175
- */
176
- PUSH = 'push',
177
- /**
178
- * Zone hides. Its content opens as an overlay on top of primary.
179
- * The user sees the content as a floating sheet/dialog.
180
- * Dismiss returns to the underlying primary content.
181
- */
182
- OVERLAY = 'overlay',
183
- }
184
- ```
185
-
186
- ### Origin Package: `@wildo-ai/saas-models`
187
-
188
- ```typescript
189
- *
190
- * Visual presentation for overlay transitions.
191
- * Determines how floating content renders above the layout.
192
- */
193
- export enum OverlayAppearance {
194
- /**
195
- * Centered modal dialog with backdrop.
196
- * Best for focused tasks: create forms, confirmations, destructive actions.
197
- * Blocks underlying content visually. Escape or backdrop click dismisses.
198
- */
199
- DIALOG = 'dialog',
200
- /**
201
- * Side or bottom drawer panel that slides in from an edge.
202
- * Best for contextual content that benefits from seeing the underlying layout.
203
- * Less disruptive than dialog. Common for detail views on mobile.
204
- */
205
- SHEET = 'sheet',
206
- /**
207
- * Vaul-backed mobile drawer.
208
- * Use when the navigation resolver should choose a drawer directly rather
209
- * than relying on a dialog appearance plus mobileShape policy.
210
- */
211
- DRAWER = 'drawer',
212
- }
213
-
214
- /**
215
- * Visual presentation for split transitions.
216
- * Determines how adjacent zone content renders alongside the source zone.
217
- */
218
- export enum SplitAppearance {
219
- /**
220
- * Standard vertical side panel.
221
- * Content appears beside the source zone with a resizable divider.
222
- * Most common for list-detail patterns.
223
- */
224
- PANEL = 'panel',
225
- /**
226
- * Horizontal drawer (bottom panel).
227
- * Content appears below the source zone.
228
- * Used for companion panels like terminals, output logs, reference docs.
229
- */
230
- DRAWER = 'drawer',
231
- }
232
- ```
@@ -1,149 +0,0 @@
1
- # Zone declaration — what one zone in a layout says about itself
2
-
3
- Read this when authoring or changing a `NavigationLayout`'s `zones` block: what a zone does when its
4
- last content is dismissed, how much of the zone a destination's content occupies, and the drag bounds
5
- and responsive behaviour declared alongside them.
6
-
7
- Read it especially before assuming a default. Three of these fields decide something only when a
8
- SECOND zone exists, so a single-zone layout gives no feedback about whether they were understood.
9
-
10
- ## Content width belongs to the ZONE, not to your template
11
-
12
- Every structural zone wraps its content in a boundary that caps at the page-content width
13
- (`--content-max-width`, 80rem by default) and centres anything wider. A detail pane is almost always
14
- narrower than that, so in practice the content FILLS the pane — "full width, up to a maximum" — and no
15
- component has to know how wide its pane is.
16
-
17
- **Do not cap your own view.** A template that applies its own `max-w-*` and `mx-auto` produces a narrow
18
- column floating inside a wide pane, and silently disagrees with the cap the zone already applies. If a
19
- surface genuinely needs to exceed the page-content width — a wide table, a board — declare
20
- `zoneContentMaxWidth: 'none'` on the operation or view instead.
21
-
22
- `zoneContentFillsHeight` fills the HEIGHT as well, and is for PRIMARY only. An adjacent zone scrolls, so a
23
- filling child there would cap at the pane's height and hide the rest; a canvas belongs in primary.
24
-
25
- ## Import Origins
26
-
27
- - `@wildo-ai/saas-models`
28
-
29
- ## Source Excerpts
30
-
31
- ### Origin Package: `@wildo-ai/saas-models`
32
-
33
- ```typescript
34
- *
35
- * What happens when a zone's last content is dismissed.
36
- * Only meaningful for secondary and companion zones (primary never empties,
37
- * overlay auto-dismisses by definition).
38
- */
39
- export enum ZoneEmptyBehavior {
40
- /**
41
- * Zone hides, adjacent zones expand to fill the space.
42
- * Example: closing the last detail → layout returns to list-only.
43
- * This is the default for all non-primary zones.
44
- */
45
- COLLAPSE = 'collapse',
46
- /**
47
- * Zone stays visible with an empty-state placeholder.
48
- * Example: "Select an item to view details" message. Keeps layout stable.
49
- * Useful when the user frequently toggles between items.
50
- */
51
- EMPTY_STATE = 'emptyState',
52
- }
53
- ```
54
-
55
- ### Origin Package: `@wildo-ai/saas-models`
56
-
57
- ```typescript
58
- *
59
- * How much of its zone a DESTINATION's content occupies.
60
- *
61
- * The primary zone caps and centres its content at `var(--content-max-width, 80rem)` and gives it no
62
- * definite-height ancestor. That is correct for almost everything a zone hosts — a form, a list, a
63
- * settings page stretched across a 2560px monitor is unreadable — and wrong for content whose whole
64
- * value is the space it occupies. Until this enum existed there was no way to tell the two apart, so
65
- * a canvas had to hand-roll a viewport fraction (`h-[70vh]`), which sizes against the WINDOW rather
66
- * than the container and therefore ignores whatever chrome sits above it.
67
- *
68
- * Declared per DESTINATION rather than per zone: the same primary zone hosts a list that wants the
69
- * cap, a detail page that caps itself, and a graph that wants neither.
70
- *
71
- * Width and height are separable on purpose. A wide data table wants the cap gone and its natural
72
- * height; collapsing both into one boolean would merge two meanings, and two independent booleans
73
- * would make "full height, still capped at 80rem" representable — a combination nothing wants and
74
- * someone would eventually author by accident.
75
- */
76
-
77
- /**
78
- * Full zone configuration.
79
- *
80
- * Each declared zone in the layout owns its complete behavior:
81
- * which transition fires for each operation, how content appears,
82
- * and how the zone responds to viewport changes.
83
- *
84
- * Note: `minWidth`, `maxWidth`, `defaultVisible`, `onEmpty`,
85
- * and `responsiveCollapse` are only meaningful for secondary and companion zones.
86
- * Primary never collapses, never empties, and takes remaining space.
87
- * Setting these on primary has no effect.
88
- */
89
- export const ZoneConfigSchema = z.object({
90
- /**
91
- * How this zone manages multiple items.
92
- * - `NavigationZoneContentModel.SINGLE` (default): stack-based navigation. One item visible, back pops.
93
- * - `NavigationZoneContentModel.TABBED`: parallel tabs. Tab bar visible, multiple items accessible.
94
- * @default NavigationZoneContentModel.SINGLE
95
- */
96
- contentModel: z.enum(NavigationZoneContentModel).default(NavigationZoneContentModel.SINGLE),
97
-
98
- /** Operation → transition mapping. Defines what happens for each user action in this zone. */
99
- transitions: ZoneTransitionsSchema,
100
-
101
- /** Transition → visual appearance. Only split and overlay have appearance choices. */
102
- appearance: ZoneAppearanceSchema.optional(),
103
-
104
- /**
105
- * Minimum pixel width when resizing. Constrains how far this side of the
106
- * split divider can be dragged. Only meaningful for secondary and companion zones.
107
- * Works in conjunction with `SplitConfigSchema.resizable`.
108
- */
109
- minWidth: z.number().positive().optional(),
110
-
111
- /**
112
- * Maximum pixel width when resizing. Constrains how far this side of the
113
- * split divider can be dragged. Only meaningful for secondary and companion zones.
114
- * Works in conjunction with `SplitConfigSchema.resizable`.
115
- */
116
- maxWidth: z.number().positive().optional(),
117
-
118
- /**
119
- * Whether this zone is visible on first render (before any transition targets it).
120
- * - Primary: always visible (this field is ignored).
121
- * - Secondary: defaults to `true` when `split.autoSplit` is `true`, `false` otherwise.
122
- * - Companion: defaults to `false` (hidden until a `split` transition targets it or user toggles).
123
- */
124
- defaultVisible: z.boolean().optional(),
125
-
126
- /**
127
- * What happens when this zone's last content is dismissed (stack empty, last tab closed).
128
- * - `ZoneEmptyBehavior.COLLAPSE` (default): zone hides, adjacent zones expand to fill.
129
- * - `ZoneEmptyBehavior.EMPTY_STATE`: zone stays visible with placeholder ("Select an item to view details").
130
- * Only meaningful for secondary and companion zones. Primary never empties.
131
- */
132
- onEmpty: z.enum(ZoneEmptyBehavior).optional(),
133
-
134
- /**
135
- * Responsive collapse rules: what happens when viewport shrinks below the zone's breakpoint.
136
- * Accepts a plain `ResponsiveCollapseMode` (all breakpoints) or viewport-discriminated object.
137
- * Only meaningful for secondary and companion zones. Primary never collapses.
138
- *
139
- * When viewport grows back past the breakpoint, collapsed content migrates back
140
- * to its original zone (content is preserved).
141
- *
142
- * @example
143
- * responsiveCollapse: ResponsiveCollapseMode.PUSH // always push into primary
144
- * responsiveCollapse: { [ViewportBreakpoint.VERT_TABLET]: ResponsiveCollapseMode.PUSH, [ViewportBreakpoint.MOBILE]: ResponsiveCollapseMode.OVERLAY } // tablet: push, mobile: overlay
145
- */
146
- responsiveCollapse: viewportDiscriminatedSchema(z.enum(ResponsiveCollapseMode)).optional(),
147
- });
148
- export type ZoneConfig = z.infer<typeof ZoneConfigSchema>;
149
- ```
@@ -1,114 +0,0 @@
1
- # How a navigation decision is actually made
2
-
3
- Everything below is the runtime's behaviour, not a convention. Read it before writing a layout, and
4
- again before concluding that a layout is being ignored.
5
-
6
- ## One event, five tiers, first answer wins
7
-
8
- Every navigation resolves to exactly one transition verb, chosen from the first tier that answers:
9
-
10
- 1. **The operation's own override** — `navigationOverrides` on a resource operation's frontend config.
11
- Matched on `fromZone` and `viewport`; first match wins. This is the EXCEPTION channel: one
12
- operation departing from the layout without the layout knowing.
13
- 2. **The action's presentation** — when an operation declares a presentation (`MODAL` → overlay), that
14
- is an alias over this same chain rather than a parallel mechanism.
15
- 3. **The viewport block** — `layout[MOBILE]` / `layout[VERT_TABLET]` transition overrides, for sweeping
16
- responsive behaviour.
17
- 4. **The SOURCE zone's transitions map** — the ordinary case. Note it is the zone you are navigating
18
- FROM that decides, never the destination.
19
- 5. **The framework fallback.**
20
-
21
- **A higher tier silently outranks a lower one.** If a layout change appears to do nothing, look UP the
22
- chain before doubting the layout: an operation-level override answers before any zone map does.
23
-
24
- ## Where each verb puts the content
25
-
26
- | verb | lands in | keeps the source visible |
27
- |---|---|---|
28
- | `push` / `replace` | the SAME zone | no — one item is visible at a time |
29
- | `split` | the first adjacent zone (secondary, else companion) | yes — this is the list-detail pattern |
30
- | `overlay` | the overlay layer | yes, visually; interactivity depends on the overlay's behaviour |
31
- | `promote` | PRIMARY, clearing secondary and companion | no — it abandons the current context deliberately |
32
- | `inplace` | nowhere — it transforms an element and changes no zone | |
33
-
34
- `split` needs an adjacent zone to exist in the layout. If none is declared it escalates to an overlay
35
- rather than failing, so a layout that "does not split" is usually a layout with one zone.
36
-
37
- ## The URL contract, which decides more than it looks like it does
38
-
39
- **Structural zones are URL-addressed. The overlay layer is not.**
40
-
41
- Content in primary, secondary or companion gets a browser URL when its operation is `ADDRESSABLE`, so
42
- it is linkable, survives a reload, and takes part in browser back and forward. Content in an overlay
43
- does not: it is a transient layer above the addressed surface.
44
-
45
- This is the trade behind choosing `overlay` for a detail. A sheet that floats over a canvas costs the
46
- selection its URL — the reader cannot link a colleague to it, and back does not step through
47
- selections. That may be the right trade; it should be a decision rather than a discovery.
48
-
49
- **Which zone owns the URL depends on what is in primary.** Beside a RESOURCE primary the detail owns
50
- it: a list's detail URL implies the list, so `/tasks/t1` reloads as list + detail. Beside anything
51
- else — a composite view, a custom view, a chart, an engine page — the PRIMARY keeps the URL and the
52
- detail rides as a `pane` query parameter: `/composite/board?section=runs&pane=%2Ftasks%2Ft1`. A reload
53
- restores both; browser back closes the pane; the host's own query params (`?section=`) keep working
54
- while the pane is open. Nothing to declare: the split transition on the zone is enough, and the
55
- composition is chosen from what primary holds at the moment of the click.
56
-
57
- **Query params that are not addresses are view state.** Route ownership compares destinations, not
58
- URL strings: a view that writes `?section=` or `?dataMode=` onto its own URL keeps its zone entry (no
59
- rebuild, no remount). Only the framework's context params (`composite_ctx_*`, `chart_ctx_*`,
60
- `execution_ctx_*`), a chart route's url-param values and `pane` are part of the address.
61
-
62
- ## What a layout declares that the runtime does NOT yet read
63
-
64
- Stated because the alternative is discovering it by watching nothing happen:
65
-
66
- - **`ZoneConfig.contentModel` is not read.** `TABBED` in particular is inert — the renderer carries an
67
- explicit "not yet implemented" note for tabbed zones. A layout selecting it gets `SINGLE` behaviour,
68
- including the shipped `NAVIGATION_LAYOUT_TABS` preset.
69
- - **`ZoneConfig.defaultVisible` is not read.**
70
- - **`SplitConfig.autoSplit` is not read.** A split layout does not pre-open its secondary zone; the
71
- zone appears when something targets it, and reappears on a deep link because URL restoration places
72
- the detail there and the list beside it.
73
- - **`NavigationLayout.maxDepth` is not read.** There is no depth ceiling; do not rely on one.
74
-
75
- Everything else in `ZoneConfig`, `SplitConfig` and `NavigationLayout` is live.
76
-
77
- ## Three behaviours that read backwards from their field names
78
-
79
- - **`orientation` names the DIVIDER.** `VERTICAL` is a vertical divider, so the panes sit SIDE BY SIDE;
80
- `HORIZONTAL` puts the second pane below. This is the opposite of what most panel libraries mean by
81
- "direction".
82
- - **`minWidth` is a floor only when the zone cannot collapse.** A collapsible pane treats a minimum as a
83
- SNAP THRESHOLD and closes past it. Declaring `minWidth` is what asks for a floor.
84
- - **`ratio` is a percentage and the bounds are pixels**, so they agree at one container width only.
85
- Below the crossover the opening size is clamped up to the floor rather than honouring the ratio.
86
-
87
- ## Content width is the ZONE's decision
88
-
89
- Every structural zone caps its content at the page-content width and centres anything wider; a detail
90
- pane is almost always narrower than that, so content fills it. A view that applies its own `max-w-*`
91
- and `mx-auto` fights this and produces a narrow column inside a wide pane. Declare
92
- `zoneContentMaxWidth: 'none'` if content must exceed the cap, and `zoneContentFillsHeight` — primary only — if it must fill the
93
- height too.
94
-
95
- ## An UNRESOLVED destination decides nothing
96
-
97
- `onEmpty` and `adjacentZoneOnEmpty` resolve from whatever occupies PRIMARY, and during a page or tab
98
- change there is a moment when primary's stack has not been reconciled from the URL yet. In that moment
99
- the destination override is absent — and an absent override is not a destination saying "collapse", it
100
- is a question nobody has answered.
101
-
102
- **The engine treats it as a question.** A zone reserves space when empty only once the destination is
103
- known; until then no structure changes. A zone that HAS content still shows it immediately — having
104
- content is a fact about the zone, not a decision owned by primary.
105
-
106
- The consequence for an application: `onEmpty: EMPTY_STATE` on a zone whose destinations override it
107
- with `COLLAPSE` no longer flashes a reserved pane on every navigation. Measured before the fix on a
108
- 2400px window: the primary content area went 2312 → 1294 → 2312 within ~25ms on each tab click, so the
109
- page jumped left and back.
110
-
111
- **You still want the zone-level value to be the one most destinations want.** The gate removes the
112
- flash, not the disagreement: every destination that overrides the zone still pays a real layout change
113
- when it resolves. If most of a layout's destinations collapse, declare `COLLAPSE` on the zone and let
114
- the list-style destinations declare `EMPTY_STATE`.
@@ -1,133 +0,0 @@
1
- # Everything an application can configure about navigation, and where to declare it
2
-
3
- Navigation is configured at FOUR levels, and choosing the wrong level is the most common mistake:
4
- a rule written at the layout level applies to the whole application, and one written on an operation
5
- applies to that operation only and outranks the layout.
6
-
7
- | level | file / surface | scope of what you declare |
8
- |---|---|---|
9
- | **Application layout** | `navigationLayout` in the frontend config | every zone, every operation, the whole app |
10
- | **Zone** | `layout.zones.<zone>` | one zone's behaviour, for every destination that uses it |
11
- | **Destination (view)** | a composite view's authoring config | one view's relationship to the zone it occupies |
12
- | **Destination (operation)** | `navigationOverrides` in `resourceUIBehavior(...).views` | one operation, resolved BEFORE the layout |
13
-
14
- Read `how-navigation-resolves.md` for the precedence between them. This file is the inventory.
15
-
16
- ---
17
-
18
- ## 1. Application layout — `navigationLayout`
19
-
20
- | field | what it decides | status |
21
- |---|---|---|
22
- | `zones.primary` | the always-present zone. Required. | live |
23
- | `zones.secondary` | the first adjacent zone. Declaring it is what makes `split` possible at all. | live |
24
- | `zones.companion` | a second adjacent zone for persistent side content. | live |
25
- | `appLevel.transitions` | what a SIDEBAR / command-palette / hotkey navigation does. App-level navigation is a layout reset. | live |
26
- | `appLevel.appearance` | appearance for app-level transitions. | live |
27
- | `fromOverlay.transitions` | what a navigation STARTED INSIDE an overlay does. | live |
28
- | `split` | inter-zone geometry — see §3. | live |
29
- | `backAffordanceOwner` | `SURFACE` (the back control sits in the surface's own header) or `SHELL` (one fixed control in the app shell). One application-wide decision, so the duplication is unrepresentable. | live |
30
- | `maxDepth` | intended as a depth ceiling. | **NOT READ** |
31
- | `[MOBILE]` / `[VERT_TABLET]` blocks | sweeping per-viewport transition overrides, merged over zone defaults. | live |
32
-
33
- ## 2. Zone — `layout.zones.<zone>`
34
-
35
- | field | what it decides | status |
36
- |---|---|---|
37
- | `transitions` | operation → verb, FROM this zone. The ordinary way navigation is configured. | live |
38
- | `appearance.split` / `appearance.overlay` | which shape a `split` or `overlay` from this zone takes (`PANEL`/`DRAWER`, `DIALOG`/`SHEET`/`DRAWER`). Viewport-discriminable. | live |
39
- | `onEmpty` | `COLLAPSE` (zone hides, neighbours expand) or `EMPTY_STATE` (zone stays with a placeholder). Adjacent zones only. | live |
40
- | `minWidth` / `maxWidth` | drag bounds in pixels. Only meaningful with `split.resizable`. **`minWidth` is a floor only because declaring it makes the zone non-collapsible** — see `how-navigation-resolves.md`. | live |
41
- | `responsiveCollapse` | below the breakpoint, does this zone's content `PUSH` into primary or `OVERLAY` on top. Viewport-discriminable. | live |
42
- | `contentModel` | `SINGLE` or `TABBED`. | **NOT READ** — `TABBED` is inert |
43
- | `defaultVisible` | intended as "visible before anything targets it". | **NOT READ** |
44
-
45
- ## 3. Split geometry — `layout.split` (and `split.companion`)
46
-
47
- | field | what it decides | status |
48
- |---|---|---|
49
- | `ratio` | `[primary, adjacent]` percentages at open. | live |
50
- | `orientation` | the DIVIDER's orientation: `VERTICAL` → side by side, `HORIZONTAL` → the second pane below. | live |
51
- | `resizable` | whether the divider can be dragged. **`false` also makes `minWidth`/`maxWidth` inert**, because a static split has no drag to bound. | live |
52
- | `companion` | the same three fields again, for the companion zone. | live |
53
- | `autoSplit` | intended as "pre-open the adjacent zone on first load". | **NOT READ** |
54
-
55
- ## 4. Destination — per view
56
-
57
- On a composite view's authoring config:
58
-
59
- | field | what it decides |
60
- |---|---|
61
- | `adjacentZoneOnEmpty` | overrides the ZONE's `onEmpty` while this view occupies primary. A list wants its detail pane to persist; a canvas wants its width back. One zone, two destinations that disagree. |
62
- | `zoneContentMaxWidth` | The width cap, in the shared `ResponsiveMaxWidth` vocabulary. Omitted is `'content'` (the page-content cap); `'none'` lets a board or wide table exceed it. |
63
- | `zoneContentFillsHeight` | Whether the content fills the zone's height too — for a canvas with no intrinsic height. PRIMARY only, because an adjacent zone scrolls. |
64
-
65
- ## 5. Destination — per operation
66
-
67
- In `resourceUIBehavior(...)`, on a `views` entry:
68
-
69
- | field | what it decides |
70
- |---|---|
71
- | `surface` | `ADDRESSABLE` (a routable page — required for a URL), `EMBEDDED` (renders inside a host, no route of its own), `API_ONLY` (headless). Navigation cannot address an operation that is not `ADDRESSABLE`. |
72
- | `navigationOverrides[]` | the EXCEPTION. `transition`, `appearance`, `overlayBehavior`, narrowed by `fromZone` and `viewport`. First match wins, resolved ahead of the zone's map. |
73
- | `adjacentZoneOnEmpty` / `zoneContentMaxWidth` / `zoneContentFillsHeight` | as §4, for a resource operation rather than a view. |
74
-
75
- ### Overlay behaviour — `navigationOverrides[].overlayBehavior`
76
-
77
- Three independent questions, and a companion panel needs all three answered:
78
-
79
- | field | default | set it to `false` when |
80
- |---|---|---|
81
- | `modal` | `true` | the reader must keep working the surface behind — a detail beside a live canvas |
82
- | `closeOnOutsideClick` | `true` | touching that surface must not dismiss. Required alongside `modal: false`: the primitive dismisses on outside pointer-down even when non-modal, so the first drag would close it |
83
- | `showBackdrop` | `true` | the surface behind must not look DISABLED. A dimmed canvas contradicts an interactive one |
84
-
85
- ## 6. Transition modifiers — `TransitionConfig`
86
-
87
- A transition is either a bare verb or an object with one modifier:
88
-
89
- | modifier | valid on | effect |
90
- |---|---|---|
91
- | `persistent` | `split` only | the zone survives the source navigating away, and targets COMPANION specifically rather than the default adjacent resolution. A thread panel that stays open across channels. |
92
- | `ephemeral` | `overlay` only | auto-closes when the source zone's stack changes. A quick-inspect preview that dismisses when another item is clicked. |
93
-
94
- `persistent` and `ephemeral` are mutually exclusive; `inplace` and `promote` accept neither.
95
-
96
- ---
97
-
98
- ## Width is a CHAIN of three caps — read `framework-content-width-api.md` before changing any of them
99
-
100
- A surface that will not fill the space it was given is almost always one of three caps, applied in
101
- sequence and owned by three different parties:
102
-
103
- | # | Cap | Declared by |
104
- |---|---|---|
105
- | 1 | the zone's content boundary (page-content width) | `zoneContentMaxWidth` on the destination |
106
- | 2 | the pane, in an adjacent zone | `ratio` / `minWidth` / `maxWidth`, plus the reader's drag |
107
- | 3 | the reading measure inside a layout root (~42rem) | `responsiveMaxWidth` on the display or form template |
108
-
109
- **Fixing the wrong one changes nothing visible**, because a tighter cap is still underneath — which is
110
- exactly how this was diagnosed three times before it was measured. Read the whole chain in the browser
111
- before deciding which level owns your case.
112
-
113
- One behaviour in the chain is a RULE rather than a declaration, because the application has already
114
- stated its intent: **a record surface's reading measure applies in PRIMARY and not in an adjacent
115
- zone.** An adjacent pane is already narrow by construction — cap 2 is the application's own statement
116
- of how wide it should be — so a further cap there cannot improve readability and only leaves a strip
117
- the reader cannot reclaim by dragging.
118
-
119
- And in every case: **do not set your own `max-w-*`.** It is a fourth cap, invisible to everything
120
- above, and it disagrees with the zone the moment a pane is resized.
121
-
122
- ## Choosing a level — the test
123
-
124
- Ask **who disagrees**.
125
-
126
- - Every destination behaves this way → the **zone**.
127
- - Every zone behaves this way → the **layout**.
128
- - One destination disagrees with the application it lives in → that **destination**.
129
- - It only differs on small screens → a **viewport** discriminator, at whichever level above.
130
-
131
- If the answer is "just this one view, and I cannot express it", that is the signal to reach for
132
- `navigationOverrides` — not for component state. A selection held in `useState` and rendered as a local
133
- panel looks identical and has no URL, no back, no zone semantics and no responsive collapse.