@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
@@ -96,14 +96,14 @@ navigation, design tokens.
96
96
 
97
97
  | Skill | Trigger phrases |
98
98
  | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
99
- | **`config-saas`** — edit `wildo.saas.config.ts` for modules, services, capabilities | "edit wildo.saas.config.ts", "add a module to SaaS config", "wire a new capability at root", "register a service at the app level" |
99
+ | **`config-saas`** — edit `wildo.saas.config.ts` for modules, services, capabilities, and the compliance declarations (operating entity, jurisdictions, retention, AI posture, client storage, provider choices) | "edit wildo.saas.config.ts", "add a module to SaaS config", "wire a new capability at root", "register a service at the app level", "record our legal entity", "declare which jurisdictions we operate in", "set the retention schedule", "who is the data controller" |
100
100
  | **`config-saas-backend`** — edit `saas-config.backend.ts`: auth posture, user types, passkey RP, email From, frontend-service login exposure | "change the password policy", "enable magic link / MFA / passkeys", "add a user type", "nobody can log in", "authentication_method_not_supported", "set the From address" |
101
101
  | **`configure-billing`** — enable billing / make a backend-reachable provider resolve across the 5-surface config chain | "enable billing", "turn on Stripe", "billing crash-loops the backend", "wire up subscriptions/checkout", "provider not reachable on the backend", "my provider is authored but the backend can't reach it" |
102
102
  | **`provider-frontend-file-picker`** — add or tune the frontend FILE PICKER provider (browser-bound module + contribution + scope; framework file fields resolve its constraints automatically) | "add a file picker", "let users attach files", "restrict uploads to PDFs", "raise the upload size limit", "file field accepts anything", "picker allows too many files", "wire a file upload provider" |
103
- | **`config-app-shell`** — configure menubar, sidebar, command menu (static commands + omnibox record search) and their labels | "edit the menubar", "change sidebar chrome", "enable the Cmd+K command menu", "add record search to the command palette", "make Cmd+K search todos", "turn on omnibox search", "command-bar label changes", "app shell label edits" |
103
+ | **`config-app-shell`** — configure menubar, sidebar, command menu (static commands + omnibox record search), their labels, and whether the PUBLIC (sign-in / sign-up) pages carry the application's identity | "edit the menubar", "change sidebar chrome", "enable the Cmd+K command menu", "add record search to the command palette", "make Cmd+K search todos", "turn on omnibox search", "command-bar label changes", "app shell label edits", "show our logo on the login page", "put the app name on the sign-in screen", "brand the sign-up page", "the login page does not say which product it is" |
104
104
  | **`settings-placement-authoring`** — author the application's Settings rail: which engine settings destinations are placed, in which category, in what order, under what name. The engine ships destinations and NO arrangement, so a section that is not placed does not appear | "add a settings section", "remove billing from settings", "reorder the settings tabs", "rename a settings section", "put SSO under a different group", "my settings section is not showing", "the settings menu opens the wrong page" |
105
105
  | **`config-navigation`** — configure navigation layout, zones, transitions, viewport behavior | "change navigation zones", "configure viewport behavior", "tweak nav transitions", "edit navigation layout" |
106
- | **`config-design-system`** — edit design system tokens, theme materials, refractive budget, surfaces, `surfacePolicies`, generated CSS | "edit design tokens", "change theme surfaces", "configure glass materials", "set refraction budget", "configure surface policy", "change SHELL main landmark behavior", "update CSS tokens output", "tweak design system config" |
106
+ | **`config-design-system`** — edit design system tokens, theme materials, refractive budget, surfaces, `surfacePolicies`, generated CSS, and the FIRST-PAINT theme behavior declared in `frontend/index.html` | "edit design tokens", "change theme surfaces", "configure glass materials", "set refraction budget", "configure surface policy", "change SHELL main landmark behavior", "update CSS tokens output", "tweak design system config", "the app flashes white before it loads", "dark mode is ignored on the login screen", "editing frontend/index.html", "add a favicon or meta tags to the app page" |
107
107
 
108
108
  ### Modules & Engine — registration, relationships, companion exports
109
109
 
@@ -64,7 +64,8 @@ Classify → author name → direct the mark → set the visual tone → verify.
64
64
 
65
65
  ### Step 1: Locate / create the brand snapshot
66
66
 
67
- // TODO CLI COMMAND: wildo context spec brand --template brand-all-information
67
+ Current landed value, live: `wildo context info specification-artifacts` (find the `brand-brief`
68
+ family row — landed state, validator verdict, rendered outline).
68
69
  Author (or open) `specifications/src/brand/index.ts` — the single
69
70
  `BrandSnapshot` instance, wired to the companion via the `brandSpecification`
70
71
  slot in `specifications/src/companion-exports.ts` (mirrors how
@@ -44,7 +44,11 @@ needs and no further.
44
44
 
45
45
  **Derives from** — the application's authored authentication configuration (methods enabled, MFA,
46
46
  password policy, lockout, step-up, session lifetimes), its access floors, its encryption of stored
47
- secrets, and the `ANTIVIRUS_SCANNING` engine capability where a provider is configured for it.
47
+ secrets, and its antivirus posture where the `ANTIVIRUS_SCANNING` INFRA capability is provisioned
48
+ (ClamAV, consumed by the engine's file-scanning service on upload). Note this reads the INFRA
49
+ capability, not an engine provider slot: the equally-named `EngineCapability.ANTIVIRUS_SCANNING` was
50
+ withdrawn because no provider could fill it, and a derived control statement must never rest on a
51
+ slot that cannot be configured.
48
52
 
49
53
  **Completeness** — `DERIVED`, bounded.
50
54
 
@@ -9,11 +9,32 @@ derive" until 2026-08-30, which described a host-computed projection layer that
9
9
  what read as an exception route is the only route, and a drafter who believed otherwise would wait
10
10
  for values nothing was going to produce.
11
11
 
12
- - Declare current facts in the `document-facts` specification family and expose it as
13
- `documentFactSpecification`.
14
- - `specificationRef` must use the `document-fact-specification:` namespace. Validated fail-closed.
15
- - Use the authority kind the blueprint question requires. A declared TypeScript module never upgrades
16
- a creator decision into qualified review, and never turns a human decision into runtime evidence.
12
+ ## There are TWO fact families, and which one you write to is decided for you
13
+
14
+ The two carry the same shape and differ in one thing: who may assert the fact. The type refuses the
15
+ other family's authorities, so choosing wrong is a compile-and-parse error rather than a silent
16
+ mistake.
17
+
18
+ | family | companion-exports slot | authority it accepts | who writes it |
19
+ |---|---|---|---|
20
+ | `document-facts` | `documentFactSpecification` | `APPLICATION_SPECIFICATION` only | the `refinement.document-facts` producer, which **regenerates the file whole** |
21
+ | `document-facts-authored` | `authoredDocumentFactSpecification` | `CREATOR_DECISION` or `QUALIFIED_REVIEW` | a person, or a host acting on a person's answers. No producer writes it |
22
+
23
+ **Never put a human decision in `document-facts`.** The producer rewrites that file on its next run,
24
+ so the decision is deleted and nothing notices — there is no compare-and-swap here, deliberately.
25
+ That is why the two are separate families rather than one file with a rule somebody has to remember.
26
+
27
+ **Never put a specification-answerable fact in `document-facts-authored`** either. A fact the accepted
28
+ specification can answer belongs in the derived family, where it is re-derived when the specification
29
+ moves; pinned under a human's name it freezes yesterday's answer.
30
+
31
+ A document reads BOTH. A fact declared in either satisfies a clause that cites it.
32
+
33
+ - `specificationRef` must use the `document-fact-specification:` namespace in both. Validated
34
+ fail-closed.
35
+ - Use the authority kind the blueprint question requires; the family then has to match it. A declared
36
+ TypeScript module never upgrades a creator decision into qualified review, and never turns a human
37
+ decision into runtime evidence.
17
38
  - Author fact value or explicit not-applicable rationale, governance scope, sensitivity and human
18
39
  decision metadata — and nothing else.
19
40
  - **Declarations must be unique AND lexically sorted by `declarationRef@declarationVersion`.** The
@@ -22,7 +43,7 @@ for values nothing was going to produce.
22
43
  - One current value for each fact version and governance scope. Replace it with a new
23
44
  declaration/specification version; do not retain two current values and hide the conflict.
24
45
  - Keep candidate reviews, approvals and releases out of the specification.
25
- - Omitting this family, or a declaration a document needs, leaves a visible blocking fact gap. Never
46
+ - Omitting either family, or a declaration a document needs, leaves a visible blocking fact gap. Never
26
47
  create an empty family or a placeholder value to make a candidate look configured — an invented
27
48
  value in a governed document is the one failure this whole lane exists to prevent.
28
49
 
@@ -46,9 +67,8 @@ than silent — it tells a reader the digest exists somewhere and that finding i
46
67
 
47
68
  ```typescript
48
69
  *
49
- * Accepted application declaration of governed-document facts that cannot be
50
- * inferred from framework code. Import from
51
- * `@wildo-ai/saas-specifications/application-creation`.
70
+ * Accepted application declaration of governed-document facts THE ACCEPTED SPECIFICATION ANSWERS.
71
+ * Import from `@wildo-ai/saas-specifications/application-creation`.
52
72
  *
53
73
  * This family carries raw decisions only. It never authors contribution
54
74
  * digests, accepted-head identities, validation receipts, reviewer grants,
@@ -62,34 +82,43 @@ than silent — it tells a reader the digest exists somewhere and that finding i
62
82
  * scope. Replacing a decision requires a new declaration/specification version
63
83
  * and normal specification-family acceptance; conflicting current values are
64
84
  * rejected at the authoring boundary instead of being hidden downstream.
85
+ *
86
+ * ## This file is REGENERATED, and that is why it accepts one authority kind
87
+ *
88
+ * `refinement.document-facts` rewrites it whole. Before #192 the same file also held the facts only a
89
+ * human may establish, so the next producer run silently deleted them — and there was no compare-and-
90
+ * swap to notice, by design (`.claude/rules/one-source-of-truth.md` Rule 0). The facts a human owns
91
+ * live in {@link ApplicationAuthoredDocumentFactSpecificationSchema}, in their own file, which no
92
+ * producer writes.
65
93
  */
66
- export const ApplicationDocumentFactSpecificationSchema = z
67
- .strictObject({
68
- schemaVersion: z.literal(1),
69
- specificationRef: AuthoredNamespacedRefSchema,
70
- specificationVersion: GovernedDocumentPositiveSafeIntegerSchema,
71
- declarations: z.array(ApplicationDocumentFactDeclarationSchema).min(1),
72
- })
73
- .superRefine((specification, context) => {
74
- if (!specification.specificationRef.startsWith("document-fact-specification:")) {
75
- context.addIssue({
76
- code: "custom",
77
- message: "specificationRef must use the document-fact-specification: namespace",
78
- path: ["specificationRef"],
79
- });
80
- }
81
- const declarationIdentities = specification.declarations.map((declaration) => `${declaration.declarationRef}@${declaration.declarationVersion}`);
82
- if (!valuesAreUnique(declarationIdentities) || !valuesAreLexicallySorted(declarationIdentities)) {
83
- context.addIssue({ code: "custom", message: "declarations must be unique and lexically sorted by identity", path: ["declarations"] });
84
- }
85
- const factScopeKeys = specification.declarations.map(applicationDocumentFactDeclarationScopeKey);
86
- if (!valuesAreUnique(factScopeKeys)) {
87
- context.addIssue({
88
- code: "custom",
89
- message: "a specification may declare only one current value for each fact version and governance scope",
90
- path: ["declarations"],
91
- });
92
- }
93
- });
94
+ export const ApplicationDocumentFactSpecificationSchema = buildDocumentFactSpecificationSchema(ApplicationDerivedDocumentFactDeclarationSchema);
94
95
  export type ApplicationDocumentFactSpecification = z.infer<typeof ApplicationDocumentFactSpecificationSchema>;
95
96
  ```
97
+
98
+ ## Import Origins
99
+
100
+ - `@wildo-ai/saas-specifications`
101
+
102
+ ## Source Excerpts
103
+
104
+ ### Origin Package: `@wildo-ai/saas-specifications`
105
+
106
+ ```typescript
107
+ *
108
+ * Accepted application declaration of governed-document facts ONLY A HUMAN MAY ESTABLISH — a creator's
109
+ * decision, or a qualified review. Import from
110
+ * `@wildo-ai/saas-specifications/application-creation`.
111
+ *
112
+ * Structurally identical to {@link ApplicationDocumentFactSpecificationSchema}: a declaration is a
113
+ * declaration whoever wrote it, and a document reading facts does not care which file one came from.
114
+ * The two are separate FAMILIES so that neither writer can destroy the other's half — the derived file
115
+ * is regenerated by a producer, this one is only ever edited by a person or by a host acting on a
116
+ * person's answers.
117
+ *
118
+ * Nothing in here may carry `APPLICATION_SPECIFICATION` authority. A fact the specification can answer
119
+ * belongs in the derived family, where it is re-derived when the specification moves; pinning it here
120
+ * would freeze yesterday's answer under a human's name.
121
+ */
122
+ export const ApplicationAuthoredDocumentFactSpecificationSchema = buildDocumentFactSpecificationSchema(ApplicationAuthoredDocumentFactDeclarationSchema);
123
+ export type ApplicationAuthoredDocumentFactSpecification = z.infer<typeof ApplicationAuthoredDocumentFactSpecificationSchema>;
124
+ ```
@@ -6,10 +6,11 @@ specifications. A blueprint says what a document must **address** — it is not
6
6
  rendering its clause purposes verbatim ships framework text as your operator's legal position.
7
7
 
8
8
  **You do not author a catalog, and the one you read is `schemaVersion: 2` / `catalogVersion: 5`.**
9
- Measured 2026-08-30 from the engine's only catalog. Its schema says newly authored catalogs use v3 /
10
- `catalogVersion` 6 and that v1/v2 are retained parse-only — so the engine has not yet moved its own
11
- catalog to the version its schema calls current, and both facts are worth knowing before you conclude
12
- that what you are reading is out of date. It is what the engine ships.
9
+ Measured 2026-08-30 from the engine's only catalog, and re-confirmed 2026-08-31. That is the current
10
+ and correct shape — not a lagging one. A v3 / `catalogVersion` 6 shape also exists in the schema, and
11
+ it is deliberately unadopted: nothing yet consumes what v3 adds, so moving the shipped catalog to it
12
+ would author content no reader reads. If you have seen v3 described elsewhere as "current", this
13
+ paragraph is the newer statement.
13
14
 
14
15
  What this page said until 2026-08-30 was "new authoring uses `schemaVersion: 2`", stated as YOUR
15
16
  instruction. That was wrong twice over: it named a version the schema had already retired, and it
@@ -24,7 +25,9 @@ From `catalogVersion` 5 onward each qualified-review policy binds reviewer quali
24
25
  review kind rather than carrying one flat policy; the retained versions must keep the historical flat
25
26
  shape, so the two are not interchangeable. `catalogVersion` 6 additionally requires
26
27
  `structuredValueContracts`, each selected by exactly one annex binding — which is why moving the
27
- shipped catalog forward is authoring work rather than a version bump.
28
+ shipped catalog forward is authoring work rather than a version bump, and part of why it has not been
29
+ done. None of this changes what you author: an application contributes declared facts and decisions,
30
+ never a catalog.
28
31
 
29
32
  Questions declare answer type, fact authority, sensitivity, not-applicable posture and semantic
30
33
  options. Sections own visible order. Clauses own drafting purpose, fact variables, monitored source
@@ -1091,7 +1094,28 @@ const AssuranceDocumentAuthorityCatalogV2BaseSchema = AssuranceDocumentAuthority
1091
1094
  });
1092
1095
  const AssuranceDocumentAuthorityCatalogV2Schema = AssuranceDocumentAuthorityCatalogV2BaseSchema.superRefine(refineAssuranceDocumentAuthorityCatalogBlueprints);
1093
1096
 
1094
- /** Current authoring branch: blueprint v2 plus a closed, exactly consumed structured-value-contract registry. */
1097
+ /**
1098
+ * Blueprint v2 plus a closed, exactly consumed structured-value-contract registry.
1099
+ *
1100
+ * ASPIRATIONAL, by decision — 2026-08-31, issue #148. The shape is designed, refined and tested, and
1101
+ * it has no instance and no consumer. Measured on that date, `structuredValueContracts` and
1102
+ * `annexBindings` appear in exactly two files: this one, and `assurance-document-structured-contract.schemas.test.ts`.
1103
+ * There is no producer, no reader, and no implementation behind
1104
+ * `AssuranceDocumentStructuredContentProcessorIdentitySchema` — nothing consumes an annex-bound
1105
+ * structured value. `AssuranceDocumentAuthorityCatalogV3Schema` itself is referenced twice, both in
1106
+ * this file: its declaration and the union member below.
1107
+ *
1108
+ * So moving the engine's six document definitions to v3 would mean authoring structured value
1109
+ * contracts that nothing reads, which `.claude/rules/application-creation-directive.md` forbids in
1110
+ * as many words: "If we write a log or record, something or someone actually reads it — otherwise we
1111
+ * do not write it." The migration was rejected on that ground, NOT on effort.
1112
+ *
1113
+ * WHAT WOULD CHANGE THE DECISION: a consumer for annex-bound structured values — something that
1114
+ * renders or validates a document annex from a `structuredValueContract` (a processor register or a
1115
+ * retention schedule as a machine-readable table rather than prose). Build that first; the catalog
1116
+ * migration is then mechanical and worth doing. Until then v2/catalogVersion 5 is the current, correct
1117
+ * and fully-refined shape, and v3 stays available for the author who has that consumer.
1118
+ */
1095
1119
  export const AssuranceDocumentAuthorityCatalogV3Schema = AssuranceDocumentAuthorityCatalogCommonSchema.extend({
1096
1120
  schemaVersion: z.literal(3),
1097
1121
  catalogVersion: z.literal(6),
@@ -1155,7 +1179,16 @@ export const AssuranceDocumentAuthorityCatalogV3Schema = AssuranceDocumentAuthor
1155
1179
  }
1156
1180
  });
1157
1181
 
1158
- /** Retained v1/v2 catalogs remain parse-only; every newly authored catalog uses v3/catalogVersion 6. */
1182
+ /**
1183
+ * All three versions are ACCEPTED for authoring. v3 is available, not mandated — see the note on
1184
+ * `AssuranceDocumentAuthorityCatalogV3Schema`.
1185
+ *
1186
+ * This comment used to read "Retained v1/v2 catalogs remain parse-only; every newly authored catalog
1187
+ * uses v3/catalogVersion 6." That was false in the only way that mattered: the repository's one
1188
+ * catalog — `createInitialAssuranceDocumentAuthorityCatalog()` — is v2/catalogVersion 5, so the
1189
+ * sentence declared the sole live instance non-authorable. A builder who read it, opened the catalog
1190
+ * and found v2 had no way to tell a stale document from a stale catalog (issue #148).
1191
+ */
1159
1192
  export const AssuranceDocumentAuthorityCatalogSchema = z.discriminatedUnion("schemaVersion", [
1160
1193
  AssuranceDocumentAuthorityCatalogV1Schema,
1161
1194
  AssuranceDocumentAuthorityCatalogV2Schema,
@@ -37,6 +37,7 @@ them.
37
37
  | Module command items| `frontend/src/modules/<module>/app-shell.module.frontend.ts` (`commandMenuItems` contribution)|
38
38
  | Module scope fields | `frontend/src/modules/<module>/app-shell.module.frontend.ts` (`quickSwitcherFields` contribution)|
39
39
  | Other app config | `frontend/src/config/*.config.ts` (navigation, design-system, global-views) |
40
+ | Public-page identity | `frontend/src/modules-registry.frontend.ts` (`publicShellIdentityMode` — NOT `app-shell.config.ts`) |
40
41
  | Translation labels | `frontend/src/i18n/`, `frontend/src/labels/` (depending on app convention) |
41
42
  | Hotkey bindings | Resolved by the engine from `[ApplicationLevelComponentType.HOTKEY]` + per-component `openShortcut` |
42
43
 
@@ -53,6 +54,7 @@ them.
53
54
  - Adjusting user dropdown sections / avatar display
54
55
  - Toggling deferred shell surfaces (activity bar, utility panel, control panel)
55
56
  - Changing responsive policy (sidebar burger threshold, etc.)
57
+ - Naming the application on its sign-in / registration pages (`publicShellIdentityMode`)
56
58
 
57
59
  ## When NOT to Use
58
60
 
@@ -135,6 +137,24 @@ dropdown rows, `presentation` for the closed control. Read
135
137
  for what the declaration wires for free (ambient scope, URL promotion,
136
138
  bi-directional mirroring, deselection).
137
139
 
140
+ ### Step 3d: Name the application on its public pages
141
+
142
+ Sign-in, registration and every other pre-authentication card can carry the
143
+ application's mark and name. It is opt-in and off by default.
144
+
145
+ It is one property, inside the existing `buildFrontendModuleConfigOverrides({ … })`
146
+ call in `frontend/src/modules-registry.frontend.ts`, beside `homeDefinition` and
147
+ `errorPageConfig`:
148
+
149
+ `publicShellIdentityMode: PublicShellIdentityMode.BRAND_HEADER` (imported from
150
+ `@wildo-ai/saas-frontend-lib`).
151
+
152
+ Two things to know before you reach for `appShellConfig` instead: this is not an
153
+ `ApplicationLevelComponentType` key and putting it there silently configures
154
+ nothing, and the mode is a PERMISSION rather than a promise that a logo exists —
155
+ an application with no generated brand shows its name alone. Read
156
+ `references/framework-public-shell-identity-api.md` for the full render matrix.
157
+
138
158
  ### Step 4: Labels
139
159
 
140
160
  Any new user-visible chrome string (command names, section titles,
@@ -225,7 +245,6 @@ export const appShellConfig : AppConfiguration_Frontend['appComponentsConfigurat
225
245
  responsiveBreakpoint: ViewportBreakpoint.MOBILE,
226
246
  responsivePolicy: SidebarResponsivePolicy.BURGER,
227
247
  defaultSection: 'main',
228
- showUncategorized: true,
229
248
  // HOME as the app's BRAND HEADER: the generated Your Application symbol + the
230
249
  // application display name, pinned above the search trigger and doubling as
231
250
  // the home button (so no separate "Home" row renders). The alternatives are
@@ -616,6 +635,7 @@ What earns its place:
616
635
  - `references/framework-command-menu-omnibox-api.md` — command-menu policy (`CommandBarPolicy`) + omnibox `searchResources` (`CommandMenuSearchResource`) contract
617
636
  - `references/framework-app-shell-hosted-components-api.md` — menubar/sidebar `hostedComponents` entry shape (`MenubarHostedComponent` / `SidebarHostedComponent`) + per-placement `triggerWidth`
618
637
  - `references/framework-quick-switcher-scope-field-api.md` — `quickSwitcherFields` entry shape (`QuickSwitcherScopeField`), the two independent presentation axes (`optionDisplayMode` / `presentation`), and what a scope declaration wires for free
638
+ - `references/framework-public-shell-identity-api.md` — naming the application on its public/auth cards: where the field goes, and what actually renders for each brand state
619
639
 
620
640
  ## Verification
621
641
 
@@ -645,6 +665,7 @@ Run from the app root:
645
665
  | Sidebar section refs are unique | `rg -oN "ref:\s+'\K[a-z-]+" frontend/src/config/app-shell.config.ts \| sort \| uniq -d` (must return empty) |
646
666
  | Command menu has an `openShortcut` | `rg -n "openShortcut:" frontend/src/config/app-shell.config.ts` |
647
667
  | Every `commands: []` entry resolves to a registered `commandId` | `rg -oN "commandId:\s+'\K[A-Z_.]+" frontend/src/config/app-shell.config.ts \| sort -u` then verify each appears in `frontend/src/commands/**/*.ts` (or the engine command registry) |
668
+ | `publicShellIdentityMode` is NOT in the shell config | `rg -n "publicShellIdentityMode" frontend/src/config/app-shell.config.ts` (must return empty; it belongs in `frontend/src/modules-registry.frontend.ts`) |
648
669
  | `searchResources` implies `policy: OMNIBOX` | `rg -n "searchResources:" frontend/src/config/app-shell.config.ts` — if it matches, `rg -n "CommandBarPolicy.OMNIBOX" frontend/src/config/app-shell.config.ts` must also match |
649
670
  | Module command items are typed launcher refs | `rg -n "kind:\s+LauncherItemTargetKind\." frontend/src/modules/*/app-shell.module.frontend.ts` (each `commandMenuItems` entry must be a typed `LauncherItemTargetKind`, never a string) |
650
671
  | Hosted-component placement uses the typed enum | `rg -n "placement:\s+(Horizontal\|Vertical)Placement\." frontend/src/config/app-shell.config.ts` (every `hostedComponents` entry that sets `placement` must use `HorizontalPlacement.*` in the menubar / `VerticalPlacement.*` in the sidebar) |
@@ -675,6 +696,8 @@ spec or navigation that targets the section.
675
696
  | "Add a clear button next to the switcher so users can deselect" | The control already renders a clear affordance inside its trigger whenever a value is selected. A sibling button reads as one more chrome icon in the cluster and names no owner. |
676
697
  | "The scope field must exist on the resource schema" | It need not. With no matching schema field the framework falls back to the target resource's primary key — which is why the option-rendering mode is declared on the FIELD and cannot come from a `.foreignKeyUI(...)` decorator. |
677
698
  | "`presentation: LABEL_ABOVE` will break the menubar's alignment" | The bar has no fixed height and centre-aligns its row: it grows to fit the tallest hosted control and shorter siblings re-centre. Pick `LABEL_ABOVE` when you want the label and accept a taller bar; `ICON_LED` when you want identity at one row height. |
699
+ | "`publicShellIdentityMode` is shell config, so it goes in `appShellConfig`." | It is not an `ApplicationLevelComponentType` key. Placed there it configures nothing and raises no error — those keys govern the AUTHENTICATED shell, which does not exist on a public page. It belongs in the `buildFrontendModuleConfigOverrides` call. |
700
+ | "We have no logo yet, so turning on the public identity would render a broken image." | The mode is a permission, not a promise. With no generated brand the card shows the name alone, and starts showing the mark by itself once one exists — nothing to revisit. |
678
701
 
679
702
  ## Red Flags
680
703
 
@@ -690,6 +713,7 @@ spec or navigation that targets the section.
690
713
  - A scope field's `resourceType` given as a string literal — it bypasses typecheck and silently names no registered resource, so the picker loads no options (catch with the **Scope-field resource types are typed** grep — must return empty).
691
714
  - `optionDisplayMode` / `presentation` given quoted strings instead of their enums (catch with the **Presentation axes use their typed enums** grep — every extracted value must be an enum member).
692
715
  - A hand-rolled "clear scope" button authored beside the switcher — duplicates the affordance the control already renders inside its trigger (catch with the **No hand-rolled clear button** verification item; grep the app for a scope-clear handler).
716
+ - `publicShellIdentityMode` appearing inside `frontend/src/config/app-shell.config.ts` — catch with the public-identity grep below
693
717
 
694
718
  ## Related Skills
695
719
 
@@ -223,10 +223,34 @@ export const AppLevelComponentConfigurationSchema = z.object({
223
223
  z.object({
224
224
  placement: z.union([ z.literal(HorizontalPlacement.START), z.literal(HorizontalPlacement.END)]),
225
225
  collapsible: z.boolean().default(true),
226
+ /**
227
+ * Does the sidebar start COLLAPSED (the icon rail) rather than expanded?
228
+ *
229
+ * This is the application's STARTING POSITION, not a lock: the rail
230
+ * collapse is a per-machine user preference persisted under
231
+ * `LOCAL_STORAGE_KEYS.SIDEBAR_COLLAPSED`, and a stored preference always
232
+ * wins. So this answers "what does a visitor with no preference yet
233
+ * see", which nothing could express before — the hydration fell back to
234
+ * `false`, making EXPANDED the only reachable default for every
235
+ * application.
236
+ *
237
+ * Pairs with the theme's `SidebarCompactLabelMode`: `ICON_AND_LABEL`
238
+ * renders a wrapping label under each icon in the collapsed rail, so a
239
+ * rail-first shell stays readable rather than becoming a column of
240
+ * unlabelled glyphs.
241
+ *
242
+ * OPTIONAL rather than `.default(false)` for the reason `homeDisplayMode`
243
+ * gives one line below: a Zod default makes the key REQUIRED in the
244
+ * inferred authoring type, forcing every preset and application config to
245
+ * restate an opinion it does not have. The framework default (expanded —
246
+ * the behavior every app had before this axis existed) is applied in
247
+ * `useSidebarBehavior`, which must resolve it there regardless because a
248
+ * sidebar authored as plain `true` never reaches this object branch.
249
+ */
250
+ defaultCollapsed: z.boolean().optional(),
226
251
  responsiveBreakpoint: z.enum(ViewportBreakpoint).default(ViewportBreakpoint.MOBILE),
227
252
  responsivePolicy: z.enum(SidebarResponsivePolicy).default(SidebarResponsivePolicy.BURGER),
228
253
  defaultSection: z.string().default("main"),
229
- showUncategorized: z.boolean().default(true),
230
254
  /**
231
255
  * How the sidebar surfaces HOME — hidden, the pinned brand header
232
256
  * (app symbol + name above the search trigger), or a "Home" navigation
@@ -0,0 +1,124 @@
1
+ # Public-page identity — naming the application on sign-in (source)
2
+
3
+ Read this when the application should say **whose** login screen it is: a mark
4
+ and/or the application name on the sign-in card. You are setting one field,
5
+ `publicShellIdentityMode`, and passing it to `buildFrontendModuleConfigOverrides`
6
+ in `frontend/src/modules-registry.frontend.ts`.
7
+
8
+ ## It is not an app-shell component key
9
+
10
+ Every other surface in this skill is keyed by `ApplicationLevelComponentType`
11
+ in `frontend/src/config/app-shell.config.ts`. This one is not, and reasoning by
12
+ analogy costs you a silent no-op: adding `publicShellIdentityMode` to
13
+ `appShellConfig` configures **nothing**, with no error.
14
+
15
+ The reason is that the two describe different runtimes. Those keys govern the
16
+ AUTHENTICATED shell — menubar, sidebar, status bar — and none of it exists yet
17
+ on a public page. So the field sits beside `navigationLayout`, `homeDefinition`
18
+ and `errorPageConfig`, which are the other whole-frontend decisions.
19
+
20
+ ## It covers every public card, not only login
21
+
22
+ One container renders them all, so the choice is made once and applies to
23
+ sign-in, registration, invitation acceptance, e-mail confirmation, password
24
+ reset, the MFA challenge, magic-link verification, enrollment, and the OAuth
25
+ consent / logged-out / logout-confirm screens.
26
+
27
+ That is deliberate rather than convenient: a brand on the login page and none
28
+ on the MFA challenge reads as two different products mid-authentication, which
29
+ is exactly when a person is deciding whether to trust the page.
30
+
31
+ ## The mode is a PERMISSION, never a promise that a logo exists
32
+
33
+ This is the part authors get wrong, because the field name sounds like it
34
+ renders something. What renders is decided from the brand DATA:
35
+
36
+ | What the application has | What the card shows |
37
+ |---|---|
38
+ | A `SYMBOL` mark and a name | the mark, with the name beneath it |
39
+ | A `WORDMARK` or `LOCKUP` mark | the **mark alone** — such a mark already contains the name, and printing the name beneath would show it twice |
40
+ | No generated brand yet | the **name alone** |
41
+ | A mark whose file cannot be loaded | the **name alone** — never a broken image |
42
+ | Neither a mark nor a name | nothing at all |
43
+
44
+ So turning this on is safe before a brand exists, and it does not need to be
45
+ revisited after one is generated — the same setting starts showing the mark on
46
+ its own.
47
+
48
+ ## Which identity it shows
49
+
50
+ The application's own: `appIdentity.displayName`, falling back to the technical
51
+ `appName`, plus the `brandAssets` the brand generation produced. Author the mark
52
+ through the brand brief (`brand-logo-authoring`) — there is nothing to configure
53
+ here to point at an asset, and no URL to paste.
54
+
55
+ ## Default, and when to turn it on
56
+
57
+ `HIDDEN` is the framework default, and an application that never mentions the
58
+ field behaves exactly as before. Prefer leaving it off until the application has
59
+ a name it is willing to show a stranger: with no brand and no `displayName`, the
60
+ card would print the technical `appName` over the sign-in form.
61
+
62
+ ## Import Origins
63
+
64
+ - `@wildo-ai/saas-frontend-lib`
65
+
66
+ ## Source Excerpts
67
+
68
+ ### Origin Package: `@wildo-ai/saas-frontend-lib`
69
+
70
+ ```typescript
71
+ *
72
+ * Whether the PUBLIC (unauthenticated) pages present the application's identity.
73
+ *
74
+ * Declare it beside your other frontend configuration and pass it to
75
+ * `buildFrontendModuleConfigOverrides` in `frontend/src/modules-registry.frontend.ts`, alongside
76
+ * `navigationLayout`, `homeDefinition` and `errorPageConfig`:
77
+ *
78
+ * ```ts
79
+ * import { PublicShellIdentityMode } from '@wildo-ai/saas-frontend-lib';
80
+ *
81
+ * frontendConfigOverrides: buildFrontendModuleConfigOverrides({
82
+ * // …navigationLayout, designSystemConfiguration, homeDefinition, errorPageConfig
83
+ * publicShellIdentityMode: PublicShellIdentityMode.BRAND_HEADER,
84
+ * }),
85
+ * ```
86
+ *
87
+ * It is NOT an `ApplicationLevelComponentType` key: it does not belong in
88
+ * `frontend/src/config/app-shell.config.ts`, and putting it there configures nothing at all. Those
89
+ * keys describe the AUTHENTICATED shell (menubar, sidebar, status bar); the pages this governs
90
+ * render before any of that exists.
91
+ *
92
+ * Login, registration, invitation acceptance, e-mail confirmation, password reset, the MFA
93
+ * challenge and the OAuth consent screens are the first thing a person ever sees of an application,
94
+ * and they are also the pages most likely to be reached from a link — an e-mail, a chat message, a
95
+ * bookmark — with no surrounding context saying what they belong to. Naming the surface there is
96
+ * conventional (Stripe, Linear, GitHub, Slack all do it) and it is the difference between "sign in"
97
+ * and "sign in to WHAT".
98
+ *
99
+ * OPT-IN, and {@link HIDDEN} is the framework default, for the same reason the sidebar's home mode
100
+ * defaults to a navigation row rather than a brand header: showing an identity assumes the surface
101
+ * HAS one worth showing, and an application that has generated no brand yet would get its technical
102
+ * `appName` printed over its login form. An application says when it is ready.
103
+ *
104
+ * Mirrors {@link SidebarHomeDisplayMode} deliberately — same question ("how is this product's
105
+ * identity surfaced here"), same answer shape, so an author who has met one already knows this one.
106
+ */
107
+ export enum PublicShellIdentityMode {
108
+ /**
109
+ * Public pages carry no identity. The framework default, and the behavior of every application
110
+ * that does not mention this field.
111
+ */
112
+ HIDDEN = 'hidden',
113
+ /**
114
+ * The identity at the top of the public card, above the form's own heading: the mark when one
115
+ * resolves, and the name.
116
+ *
117
+ * What actually renders is decided from the DATA, not from this mode — an application with no
118
+ * generated brand shows its name alone, and a brand whose mark is a wordmark or lockup shows the
119
+ * mark alone, because such a mark already contains the name. So this mode is a permission, never
120
+ * a promise that a logo exists.
121
+ */
122
+ BRAND_HEADER = 'brand_header',
123
+ }
124
+ ```
@@ -36,7 +36,7 @@ new top-level keys breaks the CSS generator.
36
36
  | Surface | Glob (relative to app root) |
37
37
  |---------------------|------------------------------------------------------------------------------------------|
38
38
  | Design system config | `frontend/src/config/design-system.config.ts` |
39
- | First-paint theme behavior | `frontend/index.html`, `frontend/src/browser-bootstrap/**/*theme*` |
39
+ | First-paint theme behavior | `frontend/index.html` (head script + style layer), `frontend/src/browser-bootstrap/app-shell-bootstrap.ts` |
40
40
  | Generated CSS | App-specific (typically `frontend/src/styles/design-tokens.css` or auto-injected) |
41
41
  | Component theme consumption | `frontend/src/components/**/*.tsx` (via Tailwind / CSS variables) |
42
42
  | Companion design-system snapshot | Re-extracted via `wildo dev design-tokens generate` / app's equivalent CLI |
@@ -104,6 +104,25 @@ own the palette. In `frontend/index.html`, use
104
104
  for the resolved mode. Never copy `oklch`, hex, or RGB token values into HTML
105
105
  or bootstrap TypeScript; duplicated tints drift when the design system changes.
106
106
 
107
+ **The resolver is the framework's, not yours.**
108
+ `frontend/src/browser-bootstrap/app-shell-bootstrap.ts` calls `initializeTheme()`
109
+ from `@wildo-ai/saas-frontend-lib/browser-bootstrap`, which reads the
110
+ `theme.preference` browser-storage value (`LIGHT` / `DARK` / `AUTO`, where an
111
+ explicit choice beats the operating system and anything else follows
112
+ `prefers-color-scheme`) and stamps `data-theme` plus the `dark` class on
113
+ `<html>`. Do not re-implement it locally and do not read that key yourself to
114
+ decide colors — the CSS already branches on what it stamped.
115
+
116
+ **Editing `frontend/index.html` — keep the head script where it is.** It is easy
117
+ to move or drop while adding a favicon, meta tags or an analytics snippet, and
118
+ the consequence is larger than a flicker: the mounted UI runtime that would
119
+ otherwise set the theme lives BELOW the application-config bootstrap, so the
120
+ loading screen and the initialization-error screen render above it. Without the
121
+ render-blocking head script those two paint LIGHT on a dark desktop — and when
122
+ the backend never answers, the error screen is the whole session rather than a
123
+ moment on the way to the app. Keep `blocking="render"` on the script tag, keep
124
+ it in `<head>`, and keep it ahead of the app entry script.
125
+
107
126
  ### Step 5: Configure material cost at the theme boundary
108
127
 
109
128
  When a theme uses structured materials, read
@@ -357,6 +376,7 @@ What is **not** in this block (and shouldn't be):
357
376
  - `references/framework-material-runtime-policy-api.md` — source-backed priority and aggregate document-budget contract
358
377
  - `references/surface-policy-authoring.md` — app-facing `surfacePolicies`, `SHELL` landmark opt-in/opt-out, active slot and selector-channel status
359
378
  - `references/framework-surface-policy-api.md` — source-backed Surface Policy family and default contracts
379
+ - `references/loading-placeholder-authoring.md` — the skeleton fill a theme must not choose freely, and why a collection repeats its silhouette
360
380
 
361
381
  ## Verification
362
382
 
@@ -382,6 +402,7 @@ Run from the app root:
382
402
  | Theme is declared | `rg -n "theme:\s+" frontend/src/config/design-system.config.ts` |
383
403
  | Every background token has a foreground pair (sample) | `rg -oN "'\K[a-z-]+(?=':)" frontend/src/config/design-system.config.ts \| rg -v "foreground" \| sort -u` |
384
404
  | **No string-literal hex / rgb in the config** (must return empty) | `rg -n "'#[0-9a-fA-F]{3,8}'" frontend/src/config/design-system.config.ts` |
405
+ | **The head theme bootstrap is present and render-blocking** | `rg -n 'blocking="render"' frontend/index.html` (must match; without it the loading and error screens paint light) |
385
406
  | **No duplicated first-paint palette literals** (must return empty) | `rg -n "oklch\\(|#[0-9a-fA-F]{3,8}|rgba?\\(" frontend/index.html frontend/src/browser-bootstrap` |
386
407
  | Generated CSS exists | `ls -1 frontend/src/styles/design-tokens.css 2>/dev/null \|\| ls -1 frontend/dist/design-tokens.css 2>/dev/null` |
387
408
  | Material profiles and aggregate policy stay theme-owned | `rg -n "materials:|materialRuntimePolicy:|priority:" frontend/src/config/design-system.config.ts` |
@@ -412,6 +433,7 @@ the file and silently loses tokens added in upgrades.
412
433
  - Missing `...DEFAULT_DESIGN_SYSTEM_SOURCE_CONFIG.<bucket>.<mode>` spread (catch with the **Default config is spread at each nested layer** grep — must match every nested `light` / `dark` block).
413
434
  - Hex / RGB color literal where `oklch` is expected (catch with the **No string-literal hex / rgb** grep — must return empty).
414
435
  - Concrete palette literals in `frontend/index.html` or the head bootstrap (catch with the **No duplicated first-paint palette literals** grep — must return empty).
436
+ - The head theme bootstrap moved out of `<head>`, stripped of `blocking="render"`, or removed while editing `frontend/index.html` (catch with the **head theme bootstrap is present and render-blocking** grep — must match).
415
437
  - New top-level key (`brand`, `extras`, etc.) outside the schema (catch by typecheck — `defineDesignSystemConfig` will reject).
416
438
  - Optical constants repeated in components instead of `theme.materials` (catch with the **Material profiles and aggregate policy stay theme-owned** grep and inspect any component-local hits).
417
439
  - Glass profiles without a semantic priority or a glass theme without one aggregate runtime policy (catch with the same material-policy grep and schema validation).
@@ -436,20 +436,29 @@ export interface A11yPolicy {
436
436
  * disable). When a finite tier is set the surface is also centered in its
437
437
  * container (`margin-inline: auto`).
438
438
  */
439
- export type ResponsiveMaxWidth =
440
- | 'full'
441
- | 'sm'
442
- | 'md'
443
- | 'lg'
444
- | 'xl'
439
+ export const RESPONSIVE_MAX_WIDTH_VALUES = [
440
+ 'full',
441
+ 'sm',
442
+ 'md',
443
+ 'lg',
444
+ 'xl',
445
445
  // Reading-measure cap (~42rem) for single-column FORM / field stacks (T4c),
446
446
  // so detail/settings forms stop stretching edge-to-edge inside a wide content
447
447
  // zone. Wider than the component tiers (`sm`–`xl`, dialog-scale) but far tighter
448
448
  // than `content`/`centered-readable`. Retune via `--measure-max-width`.
449
- | 'measure'
450
- | 'centered-readable'
451
- | 'content'
452
- | 'none';
449
+ 'measure',
450
+ 'centered-readable',
451
+ 'content',
452
+ 'none',
453
+ ] as const;
454
+
455
+ /**
456
+ * The RUNTIME source for the width vocabulary, so a schema that must validate a declared tier can
457
+ * name it instead of re-listing the members. It became necessary the moment width stopped being a
458
+ * surface-only concern: the zone content boundary, `DisplayLayout` and `FormLayout` all select a tier
459
+ * now, and a second hand-written list of the same nine values is a list that drifts.
460
+ */
461
+ export type ResponsiveMaxWidth = (typeof RESPONSIVE_MAX_WIDTH_VALUES)[number];
453
462
 
454
463
  export type MobileShape = 'inline' | 'drawer' | 'sheet';
455
464