@wildo-ai/framework-knowledge 1.1.0

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 (922) hide show
  1. package/LICENSE +34 -0
  2. package/dist/esm/.builder.pid +9 -0
  3. package/dist/esm/framework-knowledge.definitions.d.ts +51 -0
  4. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -0
  5. package/dist/esm/framework-knowledge.definitions.js +1571 -0
  6. package/dist/esm/framework-knowledge.definitions.js.map +1 -0
  7. package/dist/esm/framework-knowledge.loader.d.ts +72 -0
  8. package/dist/esm/framework-knowledge.loader.d.ts.map +1 -0
  9. package/dist/esm/framework-knowledge.loader.js +258 -0
  10. package/dist/esm/framework-knowledge.loader.js.map +1 -0
  11. package/dist/esm/framework-knowledge.schemas.d.ts +236 -0
  12. package/dist/esm/framework-knowledge.schemas.d.ts.map +1 -0
  13. package/dist/esm/framework-knowledge.schemas.js +23 -0
  14. package/dist/esm/framework-knowledge.schemas.js.map +1 -0
  15. package/dist/esm/index.d.ts +4 -0
  16. package/dist/esm/index.d.ts.map +1 -0
  17. package/dist/esm/index.js +4 -0
  18. package/dist/esm/index.js.map +1 -0
  19. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts +53 -0
  20. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.d.ts.map +1 -0
  21. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js +56 -0
  22. package/dist/esm/playbooks/bottom_up.build-decompose/playbook.definition.js.map +1 -0
  23. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts +200 -0
  24. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.d.ts.map +1 -0
  25. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js +228 -0
  26. package/dist/esm/playbooks/bottom_up.build-dispatch/playbook.definition.js.map +1 -0
  27. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts +39 -0
  28. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.d.ts.map +1 -0
  29. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js +39 -0
  30. package/dist/esm/playbooks/bottom_up.build-scale/playbook.definition.js.map +1 -0
  31. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts +261 -0
  32. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.d.ts.map +1 -0
  33. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js +412 -0
  34. package/dist/esm/playbooks/bottom_up.domain-plan/playbook.definition.js.map +1 -0
  35. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +61 -0
  36. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -0
  37. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +65 -0
  38. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -0
  39. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts +53 -0
  40. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.d.ts.map +1 -0
  41. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js +54 -0
  42. package/dist/esm/playbooks/bottom_up.placement-plan/playbook.definition.js.map +1 -0
  43. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts +43 -0
  44. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.d.ts.map +1 -0
  45. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js +73 -0
  46. package/dist/esm/playbooks/refinement.compliance-document-candidate/playbook.definition.js.map +1 -0
  47. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts +53 -0
  48. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.d.ts.map +1 -0
  49. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js +114 -0
  50. package/dist/esm/playbooks/refinement.document-facts/playbook.definition.js.map +1 -0
  51. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts +95 -0
  52. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.d.ts.map +1 -0
  53. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js +102 -0
  54. package/dist/esm/playbooks/top_down.brand-identity/playbook.definition.js.map +1 -0
  55. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts +258 -0
  56. package/dist/esm/playbooks/top_down.business-model/playbook.definition.d.ts.map +1 -0
  57. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js +241 -0
  58. package/dist/esm/playbooks/top_down.business-model/playbook.definition.js.map +1 -0
  59. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts +241 -0
  60. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.d.ts.map +1 -0
  61. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js +202 -0
  62. package/dist/esm/playbooks/top_down.capability-map/playbook.definition.js.map +1 -0
  63. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts +82 -0
  64. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.d.ts.map +1 -0
  65. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js +89 -0
  66. package/dist/esm/playbooks/top_down.compliance-posture/playbook.definition.js.map +1 -0
  67. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts +56 -0
  68. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.d.ts.map +1 -0
  69. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js +76 -0
  70. package/dist/esm/playbooks/top_down.market-analysis/playbook.definition.js.map +1 -0
  71. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts +30 -0
  72. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.d.ts.map +1 -0
  73. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js +27 -0
  74. package/dist/esm/playbooks/top_down.market-evidence-adequacy/playbook.definition.js.map +1 -0
  75. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts +31 -0
  76. package/dist/esm/playbooks/top_down.market-research/playbook.definition.d.ts.map +1 -0
  77. package/dist/esm/playbooks/top_down.market-research/playbook.definition.js +26 -0
  78. package/dist/esm/playbooks/top_down.market-research/playbook.definition.js.map +1 -0
  79. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts +254 -0
  80. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.d.ts.map +1 -0
  81. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js +219 -0
  82. package/dist/esm/playbooks/top_down.market-snapshot-produce/playbook.definition.js.map +1 -0
  83. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts +180 -0
  84. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.d.ts.map +1 -0
  85. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js +302 -0
  86. package/dist/esm/playbooks/top_down.phase-gate/playbook.definition.js.map +1 -0
  87. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts +249 -0
  88. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.d.ts.map +1 -0
  89. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js +286 -0
  90. package/dist/esm/playbooks/top_down.requirements-definition/playbook.definition.js.map +1 -0
  91. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts +248 -0
  92. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.d.ts.map +1 -0
  93. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js +227 -0
  94. package/dist/esm/playbooks/top_down.scope-roadmap/playbook.definition.js.map +1 -0
  95. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts +45 -0
  96. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.d.ts.map +1 -0
  97. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js +48 -0
  98. package/dist/esm/playbooks/top_down.value-proposition/playbook.definition.js.map +1 -0
  99. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts +250 -0
  100. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.d.ts.map +1 -0
  101. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js +218 -0
  102. package/dist/esm/playbooks/top_down.vision-elicitation/playbook.definition.js.map +1 -0
  103. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -0
  104. package/dist/knowledge/manifest.json +45 -0
  105. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +407 -0
  106. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +69 -0
  107. package/dist/knowledge/playbooks/bottom_up.build-dispatch/evaluation-protocol.json +1 -0
  108. package/dist/knowledge/playbooks/bottom_up.build-dispatch/evaluation-treatment.json +1 -0
  109. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +556 -0
  110. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +47 -0
  111. package/dist/knowledge/playbooks/bottom_up.build-scale/method.md +344 -0
  112. package/dist/knowledge/playbooks/bottom_up.build-scale/playbook.json +43 -0
  113. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-protocol.json +1 -0
  114. package/dist/knowledge/playbooks/bottom_up.domain-plan/evaluation-treatment.json +1 -0
  115. package/dist/knowledge/playbooks/bottom_up.domain-plan/method.md +259 -0
  116. package/dist/knowledge/playbooks/bottom_up.domain-plan/playbook.json +83 -0
  117. package/dist/knowledge/playbooks/bottom_up.domain-plan/structured-artifact-action.json +1 -0
  118. package/dist/knowledge/playbooks/bottom_up.foundation/method.md +321 -0
  119. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +79 -0
  120. package/dist/knowledge/playbooks/bottom_up.placement-plan/method.md +185 -0
  121. package/dist/knowledge/playbooks/bottom_up.placement-plan/playbook.json +66 -0
  122. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +737 -0
  123. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +44 -0
  124. package/dist/knowledge/playbooks/refinement.document-facts/method.md +261 -0
  125. package/dist/knowledge/playbooks/refinement.document-facts/playbook.json +57 -0
  126. package/dist/knowledge/playbooks/top_down.brand-identity/method.md +151 -0
  127. package/dist/knowledge/playbooks/top_down.brand-identity/playbook.json +124 -0
  128. package/dist/knowledge/playbooks/top_down.business-model/evaluation-protocol.json +1 -0
  129. package/dist/knowledge/playbooks/top_down.business-model/evaluation-treatment.json +1 -0
  130. package/dist/knowledge/playbooks/top_down.business-model/method.md +128 -0
  131. package/dist/knowledge/playbooks/top_down.business-model/playbook.json +102 -0
  132. package/dist/knowledge/playbooks/top_down.business-model/structured-artifact-action.json +1 -0
  133. package/dist/knowledge/playbooks/top_down.capability-map/evaluation-protocol.json +1 -0
  134. package/dist/knowledge/playbooks/top_down.capability-map/evaluation-treatment.json +1 -0
  135. package/dist/knowledge/playbooks/top_down.capability-map/method.md +239 -0
  136. package/dist/knowledge/playbooks/top_down.capability-map/playbook.json +73 -0
  137. package/dist/knowledge/playbooks/top_down.capability-map/structured-artifact-action.json +1 -0
  138. package/dist/knowledge/playbooks/top_down.compliance-posture/method.md +177 -0
  139. package/dist/knowledge/playbooks/top_down.compliance-posture/playbook.json +95 -0
  140. package/dist/knowledge/playbooks/top_down.market-analysis/method.md +64 -0
  141. package/dist/knowledge/playbooks/top_down.market-analysis/playbook.json +49 -0
  142. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/method.md +56 -0
  143. package/dist/knowledge/playbooks/top_down.market-evidence-adequacy/playbook.json +40 -0
  144. package/dist/knowledge/playbooks/top_down.market-research/method.md +68 -0
  145. package/dist/knowledge/playbooks/top_down.market-research/playbook.json +42 -0
  146. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-protocol.json +1 -0
  147. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/evaluation-treatment.json +1 -0
  148. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/method.md +239 -0
  149. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/playbook.json +69 -0
  150. package/dist/knowledge/playbooks/top_down.market-snapshot-produce/structured-artifact-action.json +1 -0
  151. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-protocol.json +1 -0
  152. package/dist/knowledge/playbooks/top_down.phase-gate/evaluation-treatment.json +1 -0
  153. package/dist/knowledge/playbooks/top_down.phase-gate/method.md +96 -0
  154. package/dist/knowledge/playbooks/top_down.phase-gate/playbook.json +77 -0
  155. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-protocol.json +1 -0
  156. package/dist/knowledge/playbooks/top_down.requirements-definition/evaluation-treatment.json +1 -0
  157. package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +53 -0
  158. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +61 -0
  159. package/dist/knowledge/playbooks/top_down.requirements-definition/structured-artifact-action.json +1 -0
  160. package/dist/knowledge/playbooks/top_down.scope-roadmap/evaluation-protocol.json +1 -0
  161. package/dist/knowledge/playbooks/top_down.scope-roadmap/evaluation-treatment.json +1 -0
  162. package/dist/knowledge/playbooks/top_down.scope-roadmap/method.md +280 -0
  163. package/dist/knowledge/playbooks/top_down.scope-roadmap/playbook.json +87 -0
  164. package/dist/knowledge/playbooks/top_down.scope-roadmap/structured-artifact-action.json +1 -0
  165. package/dist/knowledge/playbooks/top_down.value-proposition/method.md +204 -0
  166. package/dist/knowledge/playbooks/top_down.value-proposition/playbook.json +54 -0
  167. package/dist/knowledge/playbooks/top_down.vision-elicitation/evaluation-protocol.json +1 -0
  168. package/dist/knowledge/playbooks/top_down.vision-elicitation/evaluation-treatment.json +1 -0
  169. package/dist/knowledge/playbooks/top_down.vision-elicitation/method.md +146 -0
  170. package/dist/knowledge/playbooks/top_down.vision-elicitation/playbook.json +120 -0
  171. package/dist/knowledge/playbooks/top_down.vision-elicitation/structured-artifact-action.json +1 -0
  172. package/dist/knowledge/references/application.database.migration-change-risk.md +28 -0
  173. package/dist/knowledge/references/assertions.authored-metadata.config.md +90 -0
  174. package/dist/knowledge/references/assertions.behaviors.wire-contracts.md +223 -0
  175. package/dist/knowledge/references/assertions.references.conventions.md +92 -0
  176. package/dist/knowledge/references/assertions.snapshot.validation.md +317 -0
  177. package/dist/knowledge/references/assertions.specification.config.md +287 -0
  178. package/dist/knowledge/references/brand.asset.config.md +167 -0
  179. package/dist/knowledge/references/brand.authored-metadata.config.md +51 -0
  180. package/dist/knowledge/references/brand.logo-direction.config.md +88 -0
  181. package/dist/knowledge/references/brand.name.config.md +46 -0
  182. package/dist/knowledge/references/brand.snapshot.config.md +76 -0
  183. package/dist/knowledge/references/brand.snapshot.validation.md +446 -0
  184. package/dist/knowledge/references/brand.visual-tone.config.md +56 -0
  185. package/dist/knowledge/references/build-plan.task-graph.config.md +198 -0
  186. package/dist/knowledge/references/business-model.authored-metadata.config.md +65 -0
  187. package/dist/knowledge/references/business-model.pricing-plan.config.md +122 -0
  188. package/dist/knowledge/references/business-model.references.conventions.md +99 -0
  189. package/dist/knowledge/references/business-model.snapshot.config.md +121 -0
  190. package/dist/knowledge/references/business-model.snapshot.validation.md +325 -0
  191. package/dist/knowledge/references/cli.market.generate-command.md +230 -0
  192. package/dist/knowledge/references/cli.market.utils.md +147 -0
  193. package/dist/knowledge/references/companion.introspection.behaviors.market.md +90 -0
  194. package/dist/knowledge/references/companion.introspection.handlers.market.md +42 -0
  195. package/dist/knowledge/references/companion.market.generation-service.md +270 -0
  196. package/dist/knowledge/references/companion.market.prompt-renderer.md +244 -0
  197. package/dist/knowledge/references/companion.technical-doc.service.md +809 -0
  198. package/dist/knowledge/references/engine.client-bundle.allow-list.md +125 -0
  199. package/dist/knowledge/references/engine.client-bundle.discipline.md +130 -0
  200. package/dist/knowledge/references/engine.client-bundle.external-connectors-public.discipline.md +55 -0
  201. package/dist/knowledge/references/engine.saas-technical-doc.config.md +215 -0
  202. package/dist/knowledge/references/engine.saas-website.config.md +331 -0
  203. package/dist/knowledge/references/example.authorization.unit-narrowing.declaration.md +24 -0
  204. package/dist/knowledge/references/example.backend.addon-wiring.module.md +55 -0
  205. package/dist/knowledge/references/example.backend.custom-operation.create-postfix.md +35 -0
  206. package/dist/knowledge/references/example.backend.operation.error-throw.md +17 -0
  207. package/dist/knowledge/references/example.config.app-shell.command-menu-items.md +63 -0
  208. package/dist/knowledge/references/example.config.app-shell.full.md +147 -0
  209. package/dist/knowledge/references/example.config.app-shell.hosted-components.md +45 -0
  210. package/dist/knowledge/references/example.config.app-shell.quick-switcher-fields.md +37 -0
  211. package/dist/knowledge/references/example.config.backend.billing-enable.md +20 -0
  212. package/dist/knowledge/references/example.config.backend.required-floors.md +46 -0
  213. package/dist/knowledge/references/example.config.design-system.full.md +162 -0
  214. package/dist/knowledge/references/example.config.navigation.full.md +71 -0
  215. package/dist/knowledge/references/example.config.provider.backend-scope-billing.md +27 -0
  216. package/dist/knowledge/references/example.data-seeding.minimal.md +114 -0
  217. package/dist/knowledge/references/example.email.template.minimal.md +54 -0
  218. package/dist/knowledge/references/example.engine.component-registration.lazy-load.md +16 -0
  219. package/dist/knowledge/references/example.engine.product-definitions.feature-and-profiles.md +146 -0
  220. package/dist/knowledge/references/example.flows-actors.chat-assistant.md +196 -0
  221. package/dist/knowledge/references/example.flows-actors.llm-agent-one-shot.md +174 -0
  222. package/dist/knowledge/references/example.i18n.label-generation.engine-barrel.md +15 -0
  223. package/dist/knowledge/references/example.infra.cdn.cloudflare.md +23 -0
  224. package/dist/knowledge/references/example.infra.cdn.generic.md +17 -0
  225. package/dist/knowledge/references/example.infra.environment-config.local.md +250 -0
  226. package/dist/knowledge/references/example.market.alternative.in-house-build.md +49 -0
  227. package/dist/knowledge/references/example.market.authored-metadata.md +32 -0
  228. package/dist/knowledge/references/example.market.buying-journey.core-icp.md +140 -0
  229. package/dist/knowledge/references/example.market.category.config.md +71 -0
  230. package/dist/knowledge/references/example.market.channel.community.md +39 -0
  231. package/dist/knowledge/references/example.market.feature-benefit.kano-threshold.md +67 -0
  232. package/dist/knowledge/references/example.market.feature-benefit.pain-reliever.md +65 -0
  233. package/dist/knowledge/references/example.market.icp.anti-target.md +47 -0
  234. package/dist/knowledge/references/example.market.icp.individual.md +82 -0
  235. package/dist/knowledge/references/example.market.icp.legal-entity-with-geographies.md +95 -0
  236. package/dist/knowledge/references/example.market.is-benefit-available.composition.md +40 -0
  237. package/dist/knowledge/references/example.market.job.emotional.md +27 -0
  238. package/dist/knowledge/references/example.market.job.functional.md +28 -0
  239. package/dist/knowledge/references/example.market.message-template.seeds.md +106 -0
  240. package/dist/knowledge/references/example.market.objection.pricing.md +39 -0
  241. package/dist/knowledge/references/example.market.persona.dmu-with-inheritance.md +62 -0
  242. package/dist/knowledge/references/example.market.persona.individual-self.md +51 -0
  243. package/dist/knowledge/references/example.market.positioning.per-icp.md +103 -0
  244. package/dist/knowledge/references/example.market.proof.metric.md +39 -0
  245. package/dist/knowledge/references/example.market.scoring.golden-case.md +46 -0
  246. package/dist/knowledge/references/example.market.scoring.no-coverage-zero.md +40 -0
  247. package/dist/knowledge/references/example.market.snapshot-validation.duplicate-journey-stage.md +36 -0
  248. package/dist/knowledge/references/example.market.snapshot-validation.errors-by-kind.md +55 -0
  249. package/dist/knowledge/references/example.market.snapshot-validation.objection-proof-benefit-mismatch.md +74 -0
  250. package/dist/knowledge/references/example.market.snapshot-validation.proof-without-support.md +32 -0
  251. package/dist/knowledge/references/example.market.snapshot-validation.threshold-without-job.md +44 -0
  252. package/dist/knowledge/references/example.market.snapshot.assembled.md +49 -0
  253. package/dist/knowledge/references/example.market.tone-of-voice.config.md +41 -0
  254. package/dist/knowledge/references/example.market.trigger.growth-milestone.md +43 -0
  255. package/dist/knowledge/references/example.module.companion-exports.full.md +142 -0
  256. package/dist/knowledge/references/example.module.registration.shared.md +16 -0
  257. package/dist/knowledge/references/example.module.relationships.actor-edge-back-to-scope-owner.md +47 -0
  258. package/dist/knowledge/references/example.module.relationships.discriminator.md +25 -0
  259. package/dist/knowledge/references/example.module.relationships.scope-membership-junction.md +25 -0
  260. package/dist/knowledge/references/example.provider.backend-module-shape.md +110 -0
  261. package/dist/knowledge/references/example.provider.contribution.backend-billing.md +12 -0
  262. package/dist/knowledge/references/example.provider.frontend-file-picker.contribution.md +30 -0
  263. package/dist/knowledge/references/example.provider.frontend-file-picker.module.md +21 -0
  264. package/dist/knowledge/references/example.rag.source-fields.declaration.md +83 -0
  265. package/dist/knowledge/references/example.rate-limit.custom-controller-surface.md +25 -0
  266. package/dist/knowledge/references/example.rate-limit.resource-operation-surface.md +24 -0
  267. package/dist/knowledge/references/example.resource.add-field.priority-enum.md +19 -0
  268. package/dist/knowledge/references/example.resource.add-resource.module-factory-map.md +21 -0
  269. package/dist/knowledge/references/example.resource.config-wiring.fk-relationship.md +33 -0
  270. package/dist/knowledge/references/example.resource.custom-view.read-host.md +28 -0
  271. package/dist/knowledge/references/example.resource.mcp-exposure.md +65 -0
  272. package/dist/knowledge/references/example.resource.reference-constraints.role-constrained.md +27 -0
  273. package/dist/knowledge/references/example.resource.ui-behavior.enum-badge.md +22 -0
  274. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +43 -0
  275. package/dist/knowledge/references/example.spec.composite-view.workspace.md +72 -0
  276. package/dist/knowledge/references/example.spec.feature.flag-with-codehandling.md +64 -0
  277. package/dist/knowledge/references/example.spec.frontend-component.prop-vocabulary.md +88 -0
  278. package/dist/knowledge/references/example.spec.resource.semantic-field.md +23 -0
  279. package/dist/knowledge/references/example.views.app-level.composite-views-config.md +19 -0
  280. package/dist/knowledge/references/example.views.chart-view.resource-owned.md +69 -0
  281. package/dist/knowledge/references/example.views.composite-view.host-embeds.md +31 -0
  282. package/dist/knowledge/references/example.views.composite-view.workspace.md +65 -0
  283. package/dist/knowledge/references/example.views.custom-view.execution-host.md +41 -0
  284. package/dist/knowledge/references/example.views.execution-view.resource-owned.md +25 -0
  285. package/dist/knowledge/references/external-connectors.app.frontend-provider-module.md +42 -0
  286. package/dist/knowledge/references/market.alternative.config.md +68 -0
  287. package/dist/knowledge/references/market.alternative.kind.md +32 -0
  288. package/dist/knowledge/references/market.authored-metadata.config.md +64 -0
  289. package/dist/knowledge/references/market.buying-journey.config.md +43 -0
  290. package/dist/knowledge/references/market.buying-journey.stage.md +33 -0
  291. package/dist/knowledge/references/market.category.config.md +63 -0
  292. package/dist/knowledge/references/market.channel.config.md +59 -0
  293. package/dist/knowledge/references/market.channel.kind.md +49 -0
  294. package/dist/knowledge/references/market.context-block.builder.md +544 -0
  295. package/dist/knowledge/references/market.context-block.response.md +57 -0
  296. package/dist/knowledge/references/market.feature-benefit.config.md +84 -0
  297. package/dist/knowledge/references/market.feature-benefit.kano.md +41 -0
  298. package/dist/knowledge/references/market.gain.config.md +50 -0
  299. package/dist/knowledge/references/market.generation.response.md +108 -0
  300. package/dist/knowledge/references/market.icp.config.md +162 -0
  301. package/dist/knowledge/references/market.icp.geographic-targeting.md +57 -0
  302. package/dist/knowledge/references/market.inherit-from.md +74 -0
  303. package/dist/knowledge/references/market.is-benefit-available.md +58 -0
  304. package/dist/knowledge/references/market.job.config.md +48 -0
  305. package/dist/knowledge/references/market.message-template.config.md +86 -0
  306. package/dist/knowledge/references/market.objection.config.md +56 -0
  307. package/dist/knowledge/references/market.objection.kind.md +34 -0
  308. package/dist/knowledge/references/market.pain.config.md +50 -0
  309. package/dist/knowledge/references/market.persona.config.md +64 -0
  310. package/dist/knowledge/references/market.positioning.config.md +84 -0
  311. package/dist/knowledge/references/market.proof.config.md +48 -0
  312. package/dist/knowledge/references/market.proof.kind.md +34 -0
  313. package/dist/knowledge/references/market.references.weighted-edges.md +105 -0
  314. package/dist/knowledge/references/market.scoring.fit.md +215 -0
  315. package/dist/knowledge/references/market.snapshot.config.md +34 -0
  316. package/dist/knowledge/references/market.snapshot.validation.md +1171 -0
  317. package/dist/knowledge/references/market.tone-of-voice.config.md +80 -0
  318. package/dist/knowledge/references/market.trigger.config.md +45 -0
  319. package/dist/knowledge/references/market.trigger.kind.md +35 -0
  320. package/dist/knowledge/references/placement-plan.config.md +330 -0
  321. package/dist/knowledge/references/platform.config.application-database.md +74 -0
  322. package/dist/knowledge/references/platform.config.application-modules.md +30 -0
  323. package/dist/knowledge/references/platform.config.backing-services.md +266 -0
  324. package/dist/knowledge/references/platform.config.cdn.md +167 -0
  325. package/dist/knowledge/references/platform.config.environment.deployment.md +263 -0
  326. package/dist/knowledge/references/platform.config.saas.md +405 -0
  327. package/dist/knowledge/references/presets.models.design-system.configuration.md +59 -0
  328. package/dist/knowledge/references/presets.models.design-system.source-config.md +72 -0
  329. package/dist/knowledge/references/presets.models.labelling.sections.md +64 -0
  330. package/dist/knowledge/references/presets.models.material.profile-contract.md +192 -0
  331. package/dist/knowledge/references/presets.models.material.runtime-policy.md +60 -0
  332. package/dist/knowledge/references/presets.models.surface-policy.defaults.md +613 -0
  333. package/dist/knowledge/references/presets.models.surface-policy.md +534 -0
  334. package/dist/knowledge/references/presets.models.surface-variant.md +56 -0
  335. package/dist/knowledge/references/requirements.authored-metadata.config.md +64 -0
  336. package/dist/knowledge/references/requirements.functional-requirement.config.md +68 -0
  337. package/dist/knowledge/references/requirements.non-functional-requirement.config.md +100 -0
  338. package/dist/knowledge/references/requirements.references.conventions.md +125 -0
  339. package/dist/knowledge/references/requirements.snapshot.config.md +73 -0
  340. package/dist/knowledge/references/requirements.snapshot.validation.md +333 -0
  341. package/dist/knowledge/references/roadmap.authored-metadata.config.md +64 -0
  342. package/dist/knowledge/references/roadmap.phase.config.md +149 -0
  343. package/dist/knowledge/references/roadmap.references.conventions.md +89 -0
  344. package/dist/knowledge/references/roadmap.snapshot.config.md +65 -0
  345. package/dist/knowledge/references/roadmap.snapshot.validation.md +325 -0
  346. package/dist/knowledge/references/saas.backend.app-config.backend-authored.md +32 -0
  347. package/dist/knowledge/references/saas.backend.application-initialization.assembly.md +38 -0
  348. package/dist/knowledge/references/saas.backend.billing.resolution-failure-reasons.md +45 -0
  349. package/dist/knowledge/references/saas.backend.custom-operation.authoritative-fields.md +53 -0
  350. package/dist/knowledge/references/saas.backend.custom-operation.transactional-core.md +120 -0
  351. package/dist/knowledge/references/saas.backend.domain-module.md +237 -0
  352. package/dist/knowledge/references/saas.backend.email-template.definition.md +69 -0
  353. package/dist/knowledge/references/saas.backend.flows-actors.a2a-agent-card.md +89 -0
  354. package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +118 -0
  355. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +82 -0
  356. package/dist/knowledge/references/saas.backend.flows-actors.invoke-agent.md +48 -0
  357. package/dist/knowledge/references/saas.backend.flows-actors.resource-read-tool.md +39 -0
  358. package/dist/knowledge/references/saas.backend.flows-actors.resource-write-tool.md +67 -0
  359. package/dist/knowledge/references/saas.backend.pdf-template.bindings.md +52 -0
  360. package/dist/knowledge/references/saas.backend.pdf-template.definition.md +113 -0
  361. package/dist/knowledge/references/saas.backend.rate-limit-service.check-policy.md +75 -0
  362. package/dist/knowledge/references/saas.backend.system-access-service.md +994 -0
  363. package/dist/knowledge/references/saas.data-seeding.admin-endpoints.md +59 -0
  364. package/dist/knowledge/references/saas.data-seeding.bootstrap-wiring.md +184 -0
  365. package/dist/knowledge/references/saas.data-seeding.definition-input.md +95 -0
  366. package/dist/knowledge/references/saas.data-seeding.modes.md +72 -0
  367. package/dist/knowledge/references/saas.data-seeding.run-ledger.md +198 -0
  368. package/dist/knowledge/references/saas.data-seeding.run-status.md +35 -0
  369. package/dist/knowledge/references/saas.data-seeding.schedule.md +91 -0
  370. package/dist/knowledge/references/saas.data-seeding.scope-iteration-strategy.md +46 -0
  371. package/dist/knowledge/references/saas.external-providers.backend-provider-registry.runtime-filter.md +55 -0
  372. package/dist/knowledge/references/saas.external-providers.document-extraction.applicability.md +26 -0
  373. package/dist/knowledge/references/saas.external-providers.embeddings.applicability.md +30 -0
  374. package/dist/knowledge/references/saas.external-providers.llm.model-configuration.md +124 -0
  375. package/dist/knowledge/references/saas.external-providers.llm.operation-key.md +49 -0
  376. package/dist/knowledge/references/saas.frontend.app-level-component.configuration.md +265 -0
  377. package/dist/knowledge/references/saas.frontend.app-level-component.vocabulary.md +148 -0
  378. package/dist/knowledge/references/saas.frontend.app-shell.hosted-components.md +145 -0
  379. package/dist/knowledge/references/saas.frontend.chart-view.inserted-declaration.md +80 -0
  380. package/dist/knowledge/references/saas.frontend.command-menu.omnibox.md +88 -0
  381. package/dist/knowledge/references/saas.frontend.command-menu.search-resource.md +109 -0
  382. package/dist/knowledge/references/saas.frontend.component-registration.entry.md +21 -0
  383. package/dist/knowledge/references/saas.frontend.composite-view.authoring.md +102 -0
  384. package/dist/knowledge/references/saas.frontend.composite-view.define-helper.md +31 -0
  385. package/dist/knowledge/references/saas.frontend.domain-module.md +31 -0
  386. package/dist/knowledge/references/saas.frontend.embedded-resource-descent.md +37 -0
  387. package/dist/knowledge/references/saas.frontend.execution-view.action-status-contract.md +172 -0
  388. package/dist/knowledge/references/saas.frontend.execution-view.action-status-contract.per-action-retry-loop.md +115 -0
  389. package/dist/knowledge/references/saas.frontend.execution-view.definition.md +172 -0
  390. package/dist/knowledge/references/saas.frontend.execution-view.dirty-bridge-contract.local-pane.md +109 -0
  391. package/dist/knowledge/references/saas.frontend.execution-view.dirty-bridge-contract.md +55 -0
  392. package/dist/knowledge/references/saas.frontend.execution-view.dirty-state-contract.md +151 -0
  393. package/dist/knowledge/references/saas.frontend.execution-view.failure-handling-contract.md +302 -0
  394. package/dist/knowledge/references/saas.frontend.execution-view.loading-aggregation.md +89 -0
  395. package/dist/knowledge/references/saas.frontend.execution-view.loading-aggregation.participation-prefetch.md +231 -0
  396. package/dist/knowledge/references/saas.frontend.execution-view.loading-aggregation.participation-prefetch.shell-data-hydrator.md +174 -0
  397. package/dist/knowledge/references/saas.frontend.execution-view.navigation-handling-and-embedding.md +96 -0
  398. package/dist/knowledge/references/saas.frontend.execution-view.navigation-handling-and-embedding.resolution.md +45 -0
  399. package/dist/knowledge/references/saas.frontend.execution-view.outcome-emission-contract.md +71 -0
  400. package/dist/knowledge/references/saas.frontend.execution-view.participation-and-anchor.md +80 -0
  401. package/dist/knowledge/references/saas.frontend.execution-view.three-zone-contract.md +147 -0
  402. package/dist/knowledge/references/saas.frontend.flows-actors-view.md +40 -0
  403. package/dist/knowledge/references/saas.frontend.form-fields.file-provider-constraints.md +80 -0
  404. package/dist/knowledge/references/saas.frontend.full-custom-view.definition.md +64 -0
  405. package/dist/knowledge/references/saas.frontend.inserted-view.identity-bindings-descriptor.md +149 -0
  406. package/dist/knowledge/references/saas.frontend.operation-key-and-resource-config-like.md +63 -0
  407. package/dist/knowledge/references/saas.frontend.quick-switcher.scope-field.md +102 -0
  408. package/dist/knowledge/references/saas.frontend.related-resource-embeds.md +86 -0
  409. package/dist/knowledge/references/saas.frontend.related-resource-preview.md +23 -0
  410. package/dist/knowledge/references/saas.frontend.related-resource-sections.md +28 -0
  411. package/dist/knowledge/references/saas.frontend.resource-header-title.md +43 -0
  412. package/dist/knowledge/references/saas.frontend.resource-layout-templates.md +215 -0
  413. package/dist/knowledge/references/saas.frontend.resource-operation-frontend-config.md +531 -0
  414. package/dist/knowledge/references/saas.frontend.resource-ui-behavior-config.md +210 -0
  415. package/dist/knowledge/references/saas.frontend.resource-ui-behavior-preset-map.md +39 -0
  416. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +58 -0
  417. package/dist/knowledge/references/saas.frontend.settings-hub.placement.md +118 -0
  418. package/dist/knowledge/references/saas.frontend.view-definition-scope.md +42 -0
  419. package/dist/knowledge/references/saas.market.generation-agent.md +104 -0
  420. package/dist/knowledge/references/saas.models.core-resource-operation.md +86 -0
  421. package/dist/knowledge/references/saas.models.data-mode-read-list.md +395 -0
  422. package/dist/knowledge/references/saas.models.engine-capabilities.md +114 -0
  423. package/dist/knowledge/references/saas.models.error-type.md +45 -0
  424. package/dist/knowledge/references/saas.models.external-data-pipeline.md +162 -0
  425. package/dist/knowledge/references/saas.models.feature-limit-semantic.md +51 -0
  426. package/dist/knowledge/references/saas.models.flows-actors.agent-configuration.md +127 -0
  427. package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +115 -0
  428. package/dist/knowledge/references/saas.models.flows-actors.agent-invocation.md +52 -0
  429. package/dist/knowledge/references/saas.models.flows-actors.agent-prompt-spec.md +188 -0
  430. package/dist/knowledge/references/saas.models.http-api-binding.md +237 -0
  431. package/dist/knowledge/references/saas.models.navigation.layout.md +149 -0
  432. package/dist/knowledge/references/saas.models.organization-unit-narrowing-containment.md +22 -0
  433. package/dist/knowledge/references/saas.models.organization-unit-narrowing-declaration.md +42 -0
  434. package/dist/knowledge/references/saas.models.polymorphism.optout-business-key.md +62 -0
  435. package/dist/knowledge/references/saas.models.polymorphism.variant-definition.md +74 -0
  436. package/dist/knowledge/references/saas.models.provider-capabilities.md +97 -0
  437. package/dist/knowledge/references/saas.models.rate-limit-configuration.md +67 -0
  438. package/dist/knowledge/references/saas.models.relationship-handling-contract.md +30 -0
  439. package/dist/knowledge/references/saas.models.relationship-handling-settings.md +62 -0
  440. package/dist/knowledge/references/saas.models.relationship-nature-and-models.md +112 -0
  441. package/dist/knowledge/references/saas.models.resource-config.builder-parameters.md +431 -0
  442. package/dist/knowledge/references/saas.models.resource-config.forwarded-label.md +88 -0
  443. package/dist/knowledge/references/saas.models.resource-config.operation-api-call.md +89 -0
  444. package/dist/knowledge/references/saas.models.resource-config.operation-base.md +79 -0
  445. package/dist/knowledge/references/saas.models.resource-config.operation-mcp-exposure.md +49 -0
  446. package/dist/knowledge/references/saas.models.resource-config.operation-path.md +27 -0
  447. package/dist/knowledge/references/saas.models.resource-config.operation-union.md +26 -0
  448. package/dist/knowledge/references/saas.models.resource-config.operation-variant-for-key.md +62 -0
  449. package/dist/knowledge/references/saas.models.resource-config.resource-configuration.md +124 -0
  450. package/dist/knowledge/references/saas.models.resource-config.resource-relationships-buckets.md +38 -0
  451. package/dist/knowledge/references/saas.models.resource-config.resources-registry.md +69 -0
  452. package/dist/knowledge/references/saas.models.resource-config.searchable-relation.md +89 -0
  453. package/dist/knowledge/references/saas.models.resource-config.system-access-policy.md +121 -0
  454. package/dist/knowledge/references/saas.models.resource-config.token-generation.md +145 -0
  455. package/dist/knowledge/references/saas.models.resource-field-identifier.md +25 -0
  456. package/dist/knowledge/references/saas.models.resource-operation-display-risk.md +77 -0
  457. package/dist/knowledge/references/saas.models.resource-operation-variant-runtime.md +58 -0
  458. package/dist/knowledge/references/saas.models.resource-primary-scope.md +36 -0
  459. package/dist/knowledge/references/saas.models.resource-relationship-access-scope.md +26 -0
  460. package/dist/knowledge/references/saas.models.resource-relationship-builder-parameters.md +100 -0
  461. package/dist/knowledge/references/saas.models.resource-relationship-cardinality.md +57 -0
  462. package/dist/knowledge/references/saas.models.resource-relationship-declaration.md +69 -0
  463. package/dist/knowledge/references/saas.models.resource-relationship-resolved-semantics.md +60 -0
  464. package/dist/knowledge/references/saas.models.resource-relationship-schema.md +172 -0
  465. package/dist/knowledge/references/saas.models.resource-server-instance.md +109 -0
  466. package/dist/knowledge/references/saas.models.resource-type.md +24 -0
  467. package/dist/knowledge/references/saas.models.schema-family-builder.md +242 -0
  468. package/dist/knowledge/references/saas.models.scope-membership.md +143 -0
  469. package/dist/knowledge/references/saas.models.shared-domain-module.md +36 -0
  470. package/dist/knowledge/references/saas.models.shared-saas-module.md +36 -0
  471. package/dist/knowledge/references/saas.public-runtime.contract.md +229 -0
  472. package/dist/knowledge/references/saas.rag.retrieval-bounds.md +106 -0
  473. package/dist/knowledge/references/saas.rag.retrieval-refusals.md +89 -0
  474. package/dist/knowledge/references/saas.rag.retrieval-request.md +130 -0
  475. package/dist/knowledge/references/saas.rag.retrieval-result.md +147 -0
  476. package/dist/knowledge/references/saas.rag.retrieval-scores.md +54 -0
  477. package/dist/knowledge/references/saas.specifications.application-document-fact-specification.contract.md +59 -0
  478. package/dist/knowledge/references/saas.specifications.application-document-publication.contract.md +74 -0
  479. package/dist/knowledge/references/saas.specifications.assurance-document-blueprint.contract.md +1158 -0
  480. package/dist/knowledge/references/saas.specifications.assurance-program.contract.md +2602 -0
  481. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.catalog-spec-shared.md +180 -0
  482. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.discriminated-union.md +138 -0
  483. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-aggregate-offer.md +46 -0
  484. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-aggregate-rating.md +47 -0
  485. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-article.md +49 -0
  486. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-blog-posting.md +62 -0
  487. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-breadcrumb-list.md +46 -0
  488. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-faq-page.md +51 -0
  489. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-offer.md +46 -0
  490. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-organization.md +48 -0
  491. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-product.md +59 -0
  492. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-review.md +46 -0
  493. package/dist/knowledge/references/saas.specifications.catalogs.schema-org.entity-website.md +46 -0
  494. package/dist/knowledge/references/saas.specifications.companion-exports.contract.md +530 -0
  495. package/dist/knowledge/references/saas.specifications.composite-view-specification.md +49 -0
  496. package/dist/knowledge/references/saas.specifications.error-message-specification.md +92 -0
  497. package/dist/knowledge/references/saas.specifications.family-specifications.md +109 -0
  498. package/dist/knowledge/references/saas.specifications.feature-specification.md +93 -0
  499. package/dist/knowledge/references/saas.specifications.frontend-component-spec-factory.md +113 -0
  500. package/dist/knowledge/references/saas.specifications.frontend-component-spec-model.md +366 -0
  501. package/dist/knowledge/references/saas.specifications.resource-frontend-configuration-aspect.md +41 -0
  502. package/dist/knowledge/references/saas.specifications.resource-operation-spec.md +1978 -0
  503. package/dist/knowledge/references/saas.specifications.resource-pdf-template-spec.md +58 -0
  504. package/dist/knowledge/references/saas.specifications.resource-spec-code-handling.md +49 -0
  505. package/dist/knowledge/references/saas.specifications.resource-spec-config.md +156 -0
  506. package/dist/knowledge/references/saas.specifications.resource-spec-factory.md +171 -0
  507. package/dist/knowledge/references/saas.specifications.resource-spec-frontend-config-type.md +54 -0
  508. package/dist/knowledge/references/saas.specifications.resource-spec-frontend-prose.md +171 -0
  509. package/dist/knowledge/references/saas.website.astro.bridge.md +262 -0
  510. package/dist/knowledge/references/saas.website.astro.head-renderer.md +271 -0
  511. package/dist/knowledge/references/saas.website.astro.headers-renderer.md +41 -0
  512. package/dist/knowledge/references/saas.website.astro.i18n-helper.md +121 -0
  513. package/dist/knowledge/references/saas.website.astro.label-key-collector.md +117 -0
  514. package/dist/knowledge/references/saas.website.astro.label-loader.md +377 -0
  515. package/dist/knowledge/references/saas.website.astro.llms-txt-server.md +46 -0
  516. package/dist/knowledge/references/saas.website.astro.pick-labels-for-page.md +90 -0
  517. package/dist/knowledge/references/saas.website.astro.robots-renderer.md +174 -0
  518. package/dist/knowledge/references/saas.website.astro.runtime-helper.md +187 -0
  519. package/dist/knowledge/references/saas.website.astro.site-context.md +141 -0
  520. package/dist/knowledge/references/saas.website.astro.sitemap-coverage.md +188 -0
  521. package/dist/knowledge/references/saas.website.astro.structured-data-renderer.md +174 -0
  522. package/dist/knowledge/references/saas.website.blog.bridge.md +396 -0
  523. package/dist/knowledge/references/saas.website.blog.collection-config.md +180 -0
  524. package/dist/knowledge/references/saas.website.blog.frontmatter.md +116 -0
  525. package/dist/knowledge/references/saas.website.blog.head-renderer.md +292 -0
  526. package/dist/knowledge/references/saas.website.blog.mdx-provider.md +100 -0
  527. package/dist/knowledge/references/saas.website.blog.post-renderer.md +291 -0
  528. package/dist/knowledge/references/saas.website.design-tokens.bundle.md +29 -0
  529. package/dist/knowledge/references/saas.website.design-tokens.colors.md +64 -0
  530. package/dist/knowledge/references/saas.website.design-tokens.radius.md +38 -0
  531. package/dist/knowledge/references/saas.website.factories.define-page-manifest.md +98 -0
  532. package/dist/knowledge/references/saas.website.factories.define-section.md +128 -0
  533. package/dist/knowledge/references/saas.website.label-keys.compose-helper.md +36 -0
  534. package/dist/knowledge/references/saas.website.label-keys.format.md +67 -0
  535. package/dist/knowledge/references/saas.website.label-pack.validator.md +206 -0
  536. package/dist/knowledge/references/saas.website.page-layout.component.md +217 -0
  537. package/dist/knowledge/references/saas.website.page-manifest.meta-label-keys.md +47 -0
  538. package/dist/knowledge/references/saas.website.page-manifest.route-path.md +49 -0
  539. package/dist/knowledge/references/saas.website.page-manifest.schema.md +186 -0
  540. package/dist/knowledge/references/saas.website.page-manifest.seo.md +46 -0
  541. package/dist/knowledge/references/saas.website.page.context.md +57 -0
  542. package/dist/knowledge/references/saas.website.primitives.button.md +123 -0
  543. package/dist/knowledge/references/saas.website.primitives.heading.md +103 -0
  544. package/dist/knowledge/references/saas.website.primitives.image.md +103 -0
  545. package/dist/knowledge/references/saas.website.primitives.internal-button.md +151 -0
  546. package/dist/knowledge/references/saas.website.primitives.internal-link.md +193 -0
  547. package/dist/knowledge/references/saas.website.primitives.link.md +78 -0
  548. package/dist/knowledge/references/saas.website.primitives.text.md +82 -0
  549. package/dist/knowledge/references/saas.website.refs.page.md +56 -0
  550. package/dist/knowledge/references/saas.website.refs.section.md +57 -0
  551. package/dist/knowledge/references/saas.website.root-config.navigation.md +37 -0
  552. package/dist/knowledge/references/saas.website.root-config.schema.md +192 -0
  553. package/dist/knowledge/references/saas.website.root-config.seo.md +98 -0
  554. package/dist/knowledge/references/saas.website.routing.localized-path.md +84 -0
  555. package/dist/knowledge/references/saas.website.runtime.context.md +174 -0
  556. package/dist/knowledge/references/saas.website.section.component.md +138 -0
  557. package/dist/knowledge/references/saas.website.section.context.md +63 -0
  558. package/dist/knowledge/references/saas.website.sections.category-enum.md +72 -0
  559. package/dist/knowledge/references/saas.website.sections.definition-schema.md +121 -0
  560. package/dist/knowledge/references/saas.website.seo.llms-txt-config.md +37 -0
  561. package/dist/knowledge/references/saas.website.seo.robots-config.md +106 -0
  562. package/dist/knowledge/references/saas.website.seo.sitemap-config.md +73 -0
  563. package/dist/knowledge/references/saas.website.structured-data.payload-shape.md +71 -0
  564. package/dist/knowledge/references/saas.website.use-label-by-key.hook.md +45 -0
  565. package/dist/knowledge/references/saas.website.use-label.hook.md +82 -0
  566. package/dist/knowledge/references/saas.website.use-page.hook.md +30 -0
  567. package/dist/knowledge/references/saas.website.use-runtime.hook.md +36 -0
  568. package/dist/knowledge/references/saas.website.use-section.hook.md +30 -0
  569. package/dist/knowledge/references/saas.website.use-tokens.hook.md +32 -0
  570. package/dist/knowledge/references/vision.authored-metadata.config.md +64 -0
  571. package/dist/knowledge/references/vision.constraint.config.md +66 -0
  572. package/dist/knowledge/references/vision.idea.config.md +45 -0
  573. package/dist/knowledge/references/vision.mission.config.md +46 -0
  574. package/dist/knowledge/references/vision.problem.config.md +51 -0
  575. package/dist/knowledge/references/vision.references.conventions.md +115 -0
  576. package/dist/knowledge/references/vision.snapshot.config.md +85 -0
  577. package/dist/knowledge/references/vision.snapshot.validation.md +226 -0
  578. package/dist/knowledge/references/vision.success-criterion.config.md +60 -0
  579. package/dist/knowledge/references/zod.decorators.chainable-runtime.md +550 -0
  580. package/dist/knowledge/references/zod.decorators.conditional-visibility.md +104 -0
  581. package/dist/knowledge/references/zod.decorators.data-categories.md +197 -0
  582. package/dist/knowledge/references/zod.decorators.decorator-vocabulary.md +436 -0
  583. package/dist/knowledge/references/zod.decorators.display-edit-modes.md +174 -0
  584. package/dist/knowledge/references/zod.decorators.enums.frontend-handling.md +101 -0
  585. package/dist/knowledge/references/zod.decorators.field-spec-params.md +317 -0
  586. package/dist/knowledge/references/zod.decorators.file-generation.md +36 -0
  587. package/dist/knowledge/references/zod.decorators.file-rag-source.md +56 -0
  588. package/dist/knowledge/references/zod.decorators.file-schema.md +319 -0
  589. package/dist/knowledge/references/zod.decorators.foreign-key-display-mode.md +83 -0
  590. package/dist/knowledge/references/zod.decorators.per-primitive-ui.md +459 -0
  591. package/dist/knowledge/references/zod.decorators.primitive-ui.md +123 -0
  592. package/dist/knowledge/references/zod.decorators.rag-source.md +164 -0
  593. package/dist/knowledge/references/zod.decorators.schema-metadata.md +122 -0
  594. package/dist/knowledge/references/zod.decorators.shared-structural-methods.md +152 -0
  595. package/dist/knowledge/references/zod.decorators.shared-structural-params.md +314 -0
  596. package/dist/knowledge/references/zod.decorators.structural-lifecycle-params.md +529 -0
  597. package/dist/knowledge/references/zod.factories.bigdecimal.md +155 -0
  598. package/dist/knowledge/references/zod.factories.code.md +127 -0
  599. package/dist/knowledge/references/zod.factories.duration.md +246 -0
  600. package/dist/knowledge/references/zod.factories.money.md +166 -0
  601. package/dist/knowledge/references/zod.factories.phone.md +88 -0
  602. package/dist/knowledge/references/zod.factories.range.md +174 -0
  603. package/dist/knowledge/registries/assurance-authority-bases.json +15 -0
  604. package/dist/knowledge/registries/framework-topics.json +5212 -0
  605. package/dist/knowledge/registries/playbooks.json +488 -0
  606. package/dist/knowledge/registries/source-tags.json +7664 -0
  607. package/dist/knowledge/rules/resource-schema-awareness.md +77 -0
  608. package/dist/knowledge/skills/INDEX.md +349 -0
  609. package/dist/knowledge/skills/application-consumer-documentation-authoring/SKILL.md +415 -0
  610. package/dist/knowledge/skills/application-consumer-documentation-authoring/examples/domain-use-case-and-admin-task.example.md +49 -0
  611. package/dist/knowledge/skills/application-consumer-documentation-authoring/references/source-and-ownership-routing.md +52 -0
  612. package/dist/knowledge/skills/application-database-migrations/SKILL.md +218 -0
  613. package/dist/knowledge/skills/application-database-migrations/references/framework-application-database-api.md +84 -0
  614. package/dist/knowledge/skills/application-database-migrations/references/framework-migration-change-risk-api.md +37 -0
  615. package/dist/knowledge/skills/application-database-migrations/references/migration-refusals.md +64 -0
  616. package/dist/knowledge/skills/application-database-migrations/references/postgresql-vs-mongodb-obligations.md +34 -0
  617. package/dist/knowledge/skills/authorization-unit-narrowing/SKILL.md +323 -0
  618. package/dist/knowledge/skills/authorization-unit-narrowing/references/framework-unit-narrowing-declaration-api.md +84 -0
  619. package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +324 -0
  620. package/dist/knowledge/skills/backend-addon-wiring/references/backend-di-routing.md +7 -0
  621. package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +276 -0
  622. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +374 -0
  623. package/dist/knowledge/skills/backend-custom-operation/references/framework-error-handling-api.md +118 -0
  624. package/dist/knowledge/skills/backend-custom-operation/references/framework-operation-base-and-path-api.md +107 -0
  625. package/dist/knowledge/skills/backend-custom-operation/references/framework-transactional-core-api.md +134 -0
  626. package/dist/knowledge/skills/backend-custom-operation/references/operation-file-conventions.md +10 -0
  627. package/dist/knowledge/skills/brand-logo-authoring/SKILL.md +192 -0
  628. package/dist/knowledge/skills/brand-logo-authoring/references/brand-authoring-decisions.md +55 -0
  629. package/dist/knowledge/skills/brand-logo-authoring/references/framework-brand-asset-api.md +184 -0
  630. package/dist/knowledge/skills/brand-logo-authoring/references/framework-brand-snapshot-api.md +279 -0
  631. package/dist/knowledge/skills/compliance-document-authoring/SKILL.md +346 -0
  632. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-governance.md +160 -0
  633. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +518 -0
  634. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-service-terms.md +158 -0
  635. package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-fact-specification-contract.md +95 -0
  636. package/dist/knowledge/skills/compliance-document-authoring/references/framework-application-document-publication-contract.md +100 -0
  637. package/dist/knowledge/skills/compliance-document-authoring/references/framework-assurance-document-blueprint-contract.md +1210 -0
  638. package/dist/knowledge/skills/compliance-document-authoring/references/framework-governed-document-after-drafting.md +40 -0
  639. package/dist/knowledge/skills/config-app-shell/SKILL.md +698 -0
  640. package/dist/knowledge/skills/config-app-shell/references/app-shell-surfaces.md +5 -0
  641. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-api.md +415 -0
  642. package/dist/knowledge/skills/config-app-shell/references/framework-app-shell-hosted-components-api.md +170 -0
  643. package/dist/knowledge/skills/config-app-shell/references/framework-command-menu-omnibox-api.md +212 -0
  644. package/dist/knowledge/skills/config-app-shell/references/framework-quick-switcher-scope-field-api.md +178 -0
  645. package/dist/knowledge/skills/config-design-system/SKILL.md +424 -0
  646. package/dist/knowledge/skills/config-design-system/references/design-system-file.md +10 -0
  647. package/dist/knowledge/skills/config-design-system/references/framework-design-system-configuration-api.md +77 -0
  648. package/dist/knowledge/skills/config-design-system/references/framework-material-profile-api.md +200 -0
  649. package/dist/knowledge/skills/config-design-system/references/framework-material-runtime-policy-api.md +68 -0
  650. package/dist/knowledge/skills/config-design-system/references/framework-surface-policy-api.md +1212 -0
  651. package/dist/knowledge/skills/config-design-system/references/surface-policy-authoring.md +92 -0
  652. package/dist/knowledge/skills/config-navigation/SKILL.md +249 -0
  653. package/dist/knowledge/skills/config-navigation/references/framework-navigation-layout-api.md +152 -0
  654. package/dist/knowledge/skills/config-navigation/references/navigation-zones.md +5 -0
  655. package/dist/knowledge/skills/config-saas/SKILL.md +209 -0
  656. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +221 -0
  657. package/dist/knowledge/skills/config-saas/references/framework-wildo-saas-config-api.md +408 -0
  658. package/dist/knowledge/skills/config-saas/references/saas-config-scope.md +9 -0
  659. package/dist/knowledge/skills/config-saas-backend/SKILL.md +183 -0
  660. package/dist/knowledge/skills/config-saas-backend/references/framework-backend-authored-config-api.md +40 -0
  661. package/dist/knowledge/skills/configure-billing/SKILL.md +261 -0
  662. package/dist/knowledge/skills/configure-billing/references/config-chain-and-failure-map.md +90 -0
  663. package/dist/knowledge/skills/configure-billing/references/example-backend-provider-module-shape.md +122 -0
  664. package/dist/knowledge/skills/configure-billing/references/example-provider-contribution-and-backend-config.md +48 -0
  665. package/dist/knowledge/skills/configure-billing/references/framework-backend-provider-reachability-api.md +69 -0
  666. package/dist/knowledge/skills/configure-billing/references/framework-billing-resolution-failure-api.md +57 -0
  667. package/dist/knowledge/skills/email-add-template/SKILL.md +439 -0
  668. package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +9 -0
  669. package/dist/knowledge/skills/email-add-template/references/framework-email-template-api.md +72 -0
  670. package/dist/knowledge/skills/email-definition-wiring/SKILL.md +62 -0
  671. package/dist/knowledge/skills/email-labels-authoring/SKILL.md +64 -0
  672. package/dist/knowledge/skills/email-template-authoring/SKILL.md +62 -0
  673. package/dist/knowledge/skills/engine-component-registration/SKILL.md +257 -0
  674. package/dist/knowledge/skills/engine-component-registration/references/component-registration-file.md +7 -0
  675. package/dist/knowledge/skills/engine-component-registration/references/framework-component-registration-api.md +24 -0
  676. package/dist/knowledge/skills/engine-product-definitions/SKILL.md +429 -0
  677. package/dist/knowledge/skills/engine-product-definitions/references/framework-engine-product-definitions-api.md +287 -0
  678. package/dist/knowledge/skills/engine-product-definitions/references/product-registry-scope.md +5 -0
  679. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +491 -0
  680. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +227 -0
  681. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-named-a2a-agents-contract.md +143 -0
  682. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +368 -0
  683. package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +226 -0
  684. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +208 -0
  685. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +286 -0
  686. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +376 -0
  687. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +262 -0
  688. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-invocation-api.md +130 -0
  689. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-prompt-spec-api.md +214 -0
  690. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-operation-and-model-api.md +195 -0
  691. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/operation-key-selection.md +60 -0
  692. package/dist/knowledge/skills/frontend-cdn-publish/SKILL.md +237 -0
  693. package/dist/knowledge/skills/frontend-cdn-publish/references/cloudflare-and-operator-setup.md +56 -0
  694. package/dist/knowledge/skills/frontend-cdn-publish/references/framework-cdn-config-api.md +176 -0
  695. package/dist/knowledge/skills/i18n-label-generation/SKILL.md +261 -0
  696. package/dist/knowledge/skills/i18n-label-generation/references/framework-labelling-sections-api.md +67 -0
  697. package/dist/knowledge/skills/i18n-label-generation/references/label-placement.md +7 -0
  698. package/dist/knowledge/skills/i18n-rerun-pipeline/SKILL.md +269 -0
  699. package/dist/knowledge/skills/i18n-rerun-pipeline/references/framework-labelling-sections-api.md +67 -0
  700. package/dist/knowledge/skills/i18n-rerun-pipeline/references/i18n-routing.md +9 -0
  701. package/dist/knowledge/skills/i18n-translation-rerun/SKILL.md +245 -0
  702. package/dist/knowledge/skills/i18n-translation-rerun/references/framework-labelling-sections-api.md +67 -0
  703. package/dist/knowledge/skills/i18n-translation-rerun/references/translation-workflow.md +17 -0
  704. package/dist/knowledge/skills/infra-environment-config/SKILL.md +646 -0
  705. package/dist/knowledge/skills/infra-environment-config/references/framework-application-database-api.md +77 -0
  706. package/dist/knowledge/skills/infra-environment-config/references/framework-backing-services-api.md +282 -0
  707. package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +265 -0
  708. package/dist/knowledge/skills/infra-environment-config/references/infra-config-files.md +7 -0
  709. package/dist/knowledge/skills/journey-approve/SKILL.md +43 -0
  710. package/dist/knowledge/skills/journey-bootstrap-scope/SKILL.md +42 -0
  711. package/dist/knowledge/skills/journey-next/SKILL.md +42 -0
  712. package/dist/knowledge/skills/journey-report/SKILL.md +43 -0
  713. package/dist/knowledge/skills/journey-run/SKILL.md +55 -0
  714. package/dist/knowledge/skills/journey-status/SKILL.md +50 -0
  715. package/dist/knowledge/skills/local-environment-bootstrap/SKILL.md +370 -0
  716. package/dist/knowledge/skills/local-environment-bootstrap/references/initialization-recovery-recipe.md +50 -0
  717. package/dist/knowledge/skills/local-environment-bootstrap/references/local-environment-troubleshooting.md +409 -0
  718. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +247 -0
  719. package/dist/knowledge/skills/market-add-feature-benefit/SKILL.md +474 -0
  720. package/dist/knowledge/skills/market-add-feature-benefit/references/framework-feature-benefit-api.md +139 -0
  721. package/dist/knowledge/skills/market-alternatives/SKILL.md +543 -0
  722. package/dist/knowledge/skills/market-authoring-overview/SKILL.md +354 -0
  723. package/dist/knowledge/skills/market-authoring-overview/references/framework-market-references-api.md +138 -0
  724. package/dist/knowledge/skills/market-authoring-overview/references/framework-market-snapshot-api.md +129 -0
  725. package/dist/knowledge/skills/market-category/SKILL.md +290 -0
  726. package/dist/knowledge/skills/market-channels/SKILL.md +361 -0
  727. package/dist/knowledge/skills/market-companion-prompt-enrichment/SKILL.md +2752 -0
  728. package/dist/knowledge/skills/market-companion-prompt-enrichment/references/framework-companion-behavior-api.md +2443 -0
  729. package/dist/knowledge/skills/market-generation-cli/SKILL.md +1484 -0
  730. package/dist/knowledge/skills/market-generation-cli/references/framework-market-generation-cli.md +1230 -0
  731. package/dist/knowledge/skills/market-icp/SKILL.md +625 -0
  732. package/dist/knowledge/skills/market-jobs-pains-gains/SKILL.md +352 -0
  733. package/dist/knowledge/skills/market-message-templates-authoring/SKILL.md +415 -0
  734. package/dist/knowledge/skills/market-message-templates-authoring/references/framework-message-template-api.md +1439 -0
  735. package/dist/knowledge/skills/market-persona/SKILL.md +407 -0
  736. package/dist/knowledge/skills/market-positioning-authoring/SKILL.md +392 -0
  737. package/dist/knowledge/skills/market-positioning-authoring/references/framework-positioning-api.md +97 -0
  738. package/dist/knowledge/skills/market-proof-and-objection/SKILL.md +665 -0
  739. package/dist/knowledge/skills/market-scoring-interpretation/SKILL.md +620 -0
  740. package/dist/knowledge/skills/market-scoring-interpretation/references/framework-scoring-api.md +291 -0
  741. package/dist/knowledge/skills/market-snapshot-validation/SKILL.md +1706 -0
  742. package/dist/knowledge/skills/market-snapshot-validation/references/framework-snapshot-validation-api.md +1228 -0
  743. package/dist/knowledge/skills/market-tone-of-voice/SKILL.md +260 -0
  744. package/dist/knowledge/skills/market-triggers-and-journey/SKILL.md +579 -0
  745. package/dist/knowledge/skills/module-companion-exports/SKILL.md +318 -0
  746. package/dist/knowledge/skills/module-companion-exports/references/companion-exports-by-package.md +544 -0
  747. package/dist/knowledge/skills/module-registration/SKILL.md +212 -0
  748. package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +366 -0
  749. package/dist/knowledge/skills/module-registration/references/registry-files.md +9 -0
  750. package/dist/knowledge/skills/module-relationships/SKILL.md +523 -0
  751. package/dist/knowledge/skills/module-relationships/references/cross-resource-fk-checklist.md +7 -0
  752. package/dist/knowledge/skills/module-relationships/references/framework-resource-relationship-authoring-api.md +738 -0
  753. package/dist/knowledge/skills/pdf-template-authoring/SKILL.md +174 -0
  754. package/dist/knowledge/skills/pdf-template-authoring/references/framework-pdf-template-api.md +203 -0
  755. package/dist/knowledge/skills/pdf-template-authoring/references/framework-pdf-template-spec-api.md +62 -0
  756. package/dist/knowledge/skills/provider-frontend-file-picker/SKILL.md +239 -0
  757. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-file-provider-constraints-api.md +90 -0
  758. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-module-api.md +50 -0
  759. package/dist/knowledge/skills/rate-limit-authoring/SKILL.md +652 -0
  760. package/dist/knowledge/skills/rate-limit-authoring/references/framework-rate-limit-policy-api.md +182 -0
  761. package/dist/knowledge/skills/rate-limit-authoring/references/scope-key-and-bucket-conventions.md +137 -0
  762. package/dist/knowledge/skills/resource-add-field/SKILL.md +272 -0
  763. package/dist/knowledge/skills/resource-add-field/examples/add-priority-field-to-todos.example.md +153 -0
  764. package/dist/knowledge/skills/resource-add-field/references/framework-field-cross-layer-api.md +845 -0
  765. package/dist/knowledge/skills/resource-add-module/SKILL.md +322 -0
  766. package/dist/knowledge/skills/resource-add-module/references/framework-new-module-wiring-api.md +67 -0
  767. package/dist/knowledge/skills/resource-add-module/references/module-scaffold-layout.md +15 -0
  768. package/dist/knowledge/skills/resource-add-resource/SKILL.md +222 -0
  769. package/dist/knowledge/skills/resource-add-resource/references/framework-new-resource-core-config-api.md +540 -0
  770. package/dist/knowledge/skills/resource-add-resource/references/scaffold-surfaces-checklist.md +25 -0
  771. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +370 -0
  772. package/dist/knowledge/skills/resource-config-wiring/references/config-change-routing.md +11 -0
  773. package/dist/knowledge/skills/resource-config-wiring/references/framework-personal-data-declaration-api.md +622 -0
  774. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-operation-scope-enums-api.md +248 -0
  775. package/dist/knowledge/skills/resource-config-wiring/references/framework-saas-models-resource-config-api.md +1769 -0
  776. package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +1209 -0
  777. package/dist/knowledge/skills/resource-custom-view/SKILL.md +228 -0
  778. package/dist/knowledge/skills/resource-custom-view/references/custom-view-contracts.md +693 -0
  779. package/dist/knowledge/skills/resource-external-data/SKILL.md +349 -0
  780. package/dist/knowledge/skills/resource-external-data/references/framework-external-data-pipeline-api.md +187 -0
  781. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +261 -0
  782. package/dist/knowledge/skills/resource-external-data/references/lane-selection.md +49 -0
  783. package/dist/knowledge/skills/resource-external-data/references/pipeline-destination-schema.md +43 -0
  784. package/dist/knowledge/skills/resource-mcp-tool-exposure/SKILL.md +308 -0
  785. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-named-mcp-servers-contract.md +166 -0
  786. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/framework-resource-mcp-exposure-contract.md +63 -0
  787. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-catalogue-withdrawal-and-verification.md +77 -0
  788. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-client-registration-postures.md +90 -0
  789. package/dist/knowledge/skills/resource-rag-source-fields/SKILL.md +424 -0
  790. package/dist/knowledge/skills/resource-rag-source-fields/references/corpus-field-selection.md +90 -0
  791. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-embeddings-capability-api.md +261 -0
  792. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-file-rag-source-api.md +117 -0
  793. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +597 -0
  794. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-source-decorator-api.md +181 -0
  795. package/dist/knowledge/skills/resource-schema-authoring/SKILL.md +318 -0
  796. package/dist/knowledge/skills/resource-schema-authoring/examples/add-enum-field-with-ui.example.md +132 -0
  797. package/dist/knowledge/skills/resource-schema-authoring/examples/basic-resource-schema.example.md +62 -0
  798. package/dist/knowledge/skills/resource-schema-authoring/references/decorator-layer-map.md +63 -0
  799. package/dist/knowledge/skills/resource-schema-authoring/references/field-type-selection.md +70 -0
  800. package/dist/knowledge/skills/resource-schema-authoring/references/framework-decorator-vocabulary-api.md +559 -0
  801. package/dist/knowledge/skills/resource-schema-authoring/references/framework-personal-data-category-api.md +245 -0
  802. package/dist/knowledge/skills/resource-schema-authoring/references/framework-polymorphic-resources-api.md +147 -0
  803. package/dist/knowledge/skills/resource-schema-authoring/references/framework-schema-family-api.md +247 -0
  804. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-decorator-methods-api.md +164 -0
  805. package/dist/knowledge/skills/resource-schema-authoring/references/framework-shared-structural-params-api.md +327 -0
  806. package/dist/knowledge/skills/resource-schema-authoring/references/framework-special-factories-api.md +1286 -0
  807. package/dist/knowledge/skills/resource-schema-authoring/references/framework-zod-lifecycle-and-chainable-api.md +1080 -0
  808. package/dist/knowledge/skills/resource-schema-authoring/references/polymorphic-per-scope-resources.md +75 -0
  809. package/dist/knowledge/skills/resource-schema-authoring/references/schema-variants-and-discriminators.md +62 -0
  810. package/dist/knowledge/skills/resource-schema-authoring/references/shared-layer-decorator-checklist.md +69 -0
  811. package/dist/knowledge/skills/resource-schema-authoring/references/special-factories.md +45 -0
  812. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +389 -0
  813. package/dist/knowledge/skills/resource-ui-behavior/references/framework-conditional-visibility-api.md +106 -0
  814. package/dist/knowledge/skills/resource-ui-behavior/references/framework-display-edit-modes-api.md +176 -0
  815. package/dist/knowledge/skills/resource-ui-behavior/references/framework-enum-frontend-handling-api.md +103 -0
  816. package/dist/knowledge/skills/resource-ui-behavior/references/framework-foreign-key-ui-api.md +97 -0
  817. package/dist/knowledge/skills/resource-ui-behavior/references/framework-frontend-resource-ui-contracts-api.md +839 -0
  818. package/dist/knowledge/skills/resource-ui-behavior/references/framework-per-primitive-ui-api.md +461 -0
  819. package/dist/knowledge/skills/resource-ui-behavior/references/framework-primitive-ui-api.md +125 -0
  820. package/dist/knowledge/skills/resource-ui-behavior/references/framework-related-resource-embeds-api.md +245 -0
  821. package/dist/knowledge/skills/resource-ui-behavior/references/framework-resource-layout-templates-api.md +302 -0
  822. package/dist/knowledge/skills/resource-ui-behavior/references/ui-layer-boundaries.md +13 -0
  823. package/dist/knowledge/skills/seeding-authoring/SKILL.md +569 -0
  824. package/dist/knowledge/skills/seeding-authoring/references/data-seeding-mode-picker.md +154 -0
  825. package/dist/knowledge/skills/seeding-authoring/references/framework-data-seeding-api.md +176 -0
  826. package/dist/knowledge/skills/seeding-operations/SKILL.md +505 -0
  827. package/dist/knowledge/skills/seeding-operations/references/data-seeding-admin-runbook.md +337 -0
  828. package/dist/knowledge/skills/seeding-operations/references/data-seeding-cron-scheduler.md +171 -0
  829. package/dist/knowledge/skills/seeding-operations/references/framework-data-seeding-operations-api.md +662 -0
  830. package/dist/knowledge/skills/settings-placement-authoring/SKILL.md +134 -0
  831. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +65 -0
  832. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-placement-api.md +127 -0
  833. package/dist/knowledge/skills/spec-catalog-authoring/SKILL.md +726 -0
  834. package/dist/knowledge/skills/spec-catalog-authoring/references/catalog-spec-pattern-overview.md +242 -0
  835. package/dist/knowledge/skills/spec-companion-exports/SKILL.md +362 -0
  836. package/dist/knowledge/skills/spec-companion-exports/references/companion-export-checklist.md +8 -0
  837. package/dist/knowledge/skills/spec-companion-exports/references/framework-companion-exports-contract-api.md +533 -0
  838. package/dist/knowledge/skills/spec-component-update/SKILL.md +315 -0
  839. package/dist/knowledge/skills/spec-component-update/references/component-spec-props.md +8 -0
  840. package/dist/knowledge/skills/spec-component-update/references/framework-frontend-component-spec-api.md +481 -0
  841. package/dist/knowledge/skills/spec-composite-view-update/SKILL.md +283 -0
  842. package/dist/knowledge/skills/spec-composite-view-update/references/composite-spec-sections.md +5 -0
  843. package/dist/knowledge/skills/spec-composite-view-update/references/framework-composite-view-specification-api.md +51 -0
  844. package/dist/knowledge/skills/spec-family-update/SKILL.md +300 -0
  845. package/dist/knowledge/skills/spec-family-update/references/family-spec-routing.md +13 -0
  846. package/dist/knowledge/skills/spec-family-update/references/framework-error-message-specifications-api.md +108 -0
  847. package/dist/knowledge/skills/spec-family-update/references/framework-family-specifications-api.md +111 -0
  848. package/dist/knowledge/skills/spec-feature-update/SKILL.md +306 -0
  849. package/dist/knowledge/skills/spec-feature-update/references/feature-spec-scope.md +5 -0
  850. package/dist/knowledge/skills/spec-feature-update/references/framework-feature-specification-api.md +95 -0
  851. package/dist/knowledge/skills/spec-resource-update/SKILL.md +220 -0
  852. package/dist/knowledge/skills/spec-resource-update/references/framework-field-spec-params-api.md +319 -0
  853. package/dist/knowledge/skills/spec-resource-update/references/framework-spec-resource-contracts-api.md +2610 -0
  854. package/dist/knowledge/skills/spec-resource-update/references/resource-spec-field-routing.md +12 -0
  855. package/dist/knowledge/skills/spec-update-after-change/SKILL.md +195 -0
  856. package/dist/knowledge/skills/spec-update-after-change/references/framework-spec-factory-api.md +173 -0
  857. package/dist/knowledge/skills/spec-update-after-change/references/spec-maintenance-by-surface.md +33 -0
  858. package/dist/knowledge/skills/spec-update-after-change/references/surface-to-spec-routing.md +14 -0
  859. package/dist/knowledge/skills/views-add-composite-view/SKILL.md +259 -0
  860. package/dist/knowledge/skills/views-add-composite-view/references/composite-view-routing.md +10 -0
  861. package/dist/knowledge/skills/views-add-composite-view/references/framework-inserted-view-identity-api.md +151 -0
  862. package/dist/knowledge/skills/views-add-custom-view/SKILL.md +225 -0
  863. package/dist/knowledge/skills/views-add-custom-view/references/custom-view-routing.md +10 -0
  864. package/dist/knowledge/skills/views-add-custom-view/references/framework-view-scope-and-full-custom-api.md +107 -0
  865. package/dist/knowledge/skills/views-app-level/SKILL.md +201 -0
  866. package/dist/knowledge/skills/views-app-level/references/app-level-views-routing.md +9 -0
  867. package/dist/knowledge/skills/views-app-level/references/framework-view-scope-and-full-custom-api.md +107 -0
  868. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +264 -0
  869. package/dist/knowledge/skills/views-chart-authoring/references/chart-view-checklist.md +7 -0
  870. package/dist/knowledge/skills/views-chart-authoring/references/framework-chart-view-contracts-api.md +82 -0
  871. package/dist/knowledge/skills/views-chart-authoring/references/framework-inserted-view-identity-api.md +152 -0
  872. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +302 -0
  873. package/dist/knowledge/skills/views-composite-authoring/references/composite-embedding-checklist.md +23 -0
  874. package/dist/knowledge/skills/views-composite-authoring/references/framework-composite-view-contracts-api.md +133 -0
  875. package/dist/knowledge/skills/views-composite-authoring/references/framework-inserted-view-identity-api.md +152 -0
  876. package/dist/knowledge/skills/views-execution-authoring/SKILL.md +209 -0
  877. package/dist/knowledge/skills/views-execution-authoring/references/execution-view-checklist.md +7 -0
  878. package/dist/knowledge/skills/views-execution-authoring/references/framework-execution-view-contracts-api.md +389 -0
  879. package/dist/knowledge/skills/views-execution-authoring/references/framework-inserted-view-identity-api.md +152 -0
  880. package/dist/knowledge/skills/website-anonymous-session/SKILL.md +444 -0
  881. package/dist/knowledge/skills/website-blog-authoring/SKILL.md +587 -0
  882. package/dist/knowledge/skills/website-blog-authoring/references/blog-adapter-api.md +1426 -0
  883. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +553 -0
  884. package/dist/knowledge/skills/website-bundle-discipline/references/example-website-button-override.md +52 -0
  885. package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +357 -0
  886. package/dist/knowledge/skills/website-consent-gate-overrides/SKILL.md +511 -0
  887. package/dist/knowledge/skills/website-factory-advanced/SKILL.md +376 -0
  888. package/dist/knowledge/skills/website-inbound-contact-forms/SKILL.md +304 -0
  889. package/dist/knowledge/skills/website-label-pack/SKILL.md +390 -0
  890. package/dist/knowledge/skills/website-layout-overrides/SKILL.md +461 -0
  891. package/dist/knowledge/skills/website-marketing-metadata-extension/SKILL.md +264 -0
  892. package/dist/knowledge/skills/website-navigation-authoring/SKILL.md +414 -0
  893. package/dist/knowledge/skills/website-navigation-authoring/references/worked-examples-header-footer.md +366 -0
  894. package/dist/knowledge/skills/website-page-authoring/SKILL.md +420 -0
  895. package/dist/knowledge/skills/website-page-variants/SKILL.md +256 -0
  896. package/dist/knowledge/skills/website-primitive-overrides/SKILL.md +302 -0
  897. package/dist/knowledge/skills/website-section-contact/SKILL.md +950 -0
  898. package/dist/knowledge/skills/website-section-contact/references/define-website-section-api.md +579 -0
  899. package/dist/knowledge/skills/website-section-cta/SKILL.md +822 -0
  900. package/dist/knowledge/skills/website-section-cta/references/define-website-section-api.md +579 -0
  901. package/dist/knowledge/skills/website-section-faq/SKILL.md +917 -0
  902. package/dist/knowledge/skills/website-section-faq/references/define-website-section-api.md +579 -0
  903. package/dist/knowledge/skills/website-section-feature-benefit-summary/SKILL.md +878 -0
  904. package/dist/knowledge/skills/website-section-feature-benefit-summary/references/define-website-section-api.md +579 -0
  905. package/dist/knowledge/skills/website-section-feature-detail/SKILL.md +895 -0
  906. package/dist/knowledge/skills/website-section-feature-detail/references/define-website-section-api.md +579 -0
  907. package/dist/knowledge/skills/website-section-footer-cta/SKILL.md +814 -0
  908. package/dist/knowledge/skills/website-section-footer-cta/references/define-website-section-api.md +579 -0
  909. package/dist/knowledge/skills/website-section-hero/SKILL.md +944 -0
  910. package/dist/knowledge/skills/website-section-hero/references/define-website-section-api.md +583 -0
  911. package/dist/knowledge/skills/website-section-pricing/SKILL.md +934 -0
  912. package/dist/knowledge/skills/website-section-pricing/references/define-website-section-api.md +579 -0
  913. package/dist/knowledge/skills/website-section-social-proof/SKILL.md +912 -0
  914. package/dist/knowledge/skills/website-section-social-proof/references/define-website-section-api.md +579 -0
  915. package/dist/knowledge/skills/website-seo-aeo-geo/SKILL.md +624 -0
  916. package/dist/knowledge/skills/website-seo-aeo-geo/references/aeo-api.md +633 -0
  917. package/dist/knowledge/skills/website-seo-aeo-geo/references/geo-api.md +193 -0
  918. package/dist/knowledge/skills/website-seo-aeo-geo/references/seo-api.md +790 -0
  919. package/dist/knowledge/topic-index.json +17510 -0
  920. package/dist/tsconfig.build.tsbuildinfo +1 -0
  921. package/dist/tsconfig.tsbuildinfo +1 -0
  922. package/package.json +49 -0
@@ -0,0 +1,2752 @@
1
+ ---
2
+ name: market-companion-prompt-enrichment
3
+ description: Render an English market-context block from the MarketSnapshot via the dev-companion's market-context-for-feature / market-context-for-icp behaviors. Consumed by editor agents ("edit feature X") and by the market-generation CLI (Phase 4.2). Use when the user says "what is the market context for feature X", "render the market block for an ICP", "wire prompt enrichment for the editor", "market-context-for-feature", "market-context-for-icp", or "use the market snapshot in a prompt".
4
+ ---
5
+
6
+ # Render the Market Context Block (Phase 4.1)
7
+
8
+ ### Target Application Framing
9
+
10
+ This knowledge is for configuring behavior in the target application.
11
+ Wildo is the framework surface being used, not the product being built.
12
+
13
+ Read and apply these patterns from the application-developer point of view:
14
+
15
+ - how the application should configure the relevant app-level file
16
+ - how the application should use framework-provided factories, enums, and helpers
17
+ - how the application should avoid mixing frontend, backend, and infrastructure concerns
18
+
19
+
20
+ ## Overview
21
+
22
+ `buildMarketContextBlock(input)` is the **pure, deterministic
23
+ renderer** that turns a `MarketSnapshot` plus an `intent`
24
+ (feature-scoped or ICP-scoped) into one English markdown block
25
+ suitable for direct paste into an LLM system prompt. Two dev-companion
26
+ introspection behaviors expose the renderer over the standard
27
+ companion HTTP/RPC surface:
28
+
29
+ | Behavior id | Intent kind | Required input |
30
+ |------------------------------|-----------------------|-----------------------------|
31
+ | `market-context-for-feature` | `{ kind: 'feature' }` | `featureRef: string` |
32
+ | `market-context-for-icp` | `{ kind: 'icp' }` | `icpRef: string` |
33
+
34
+ Both behaviors live in the `'market'` companion category and are
35
+ served by the `'specifications'` route (they consume only the
36
+ `marketSpecification` field on `SpecificationsCompanionExports`).
37
+
38
+ The block is **always English**. The optional `outputLanguage`
39
+ parameter appends a single "Output language" instruction at the end
40
+ of the block — the body itself is never translated. Translation
41
+ happens at LLM output time (D15 / §12 of the plan).
42
+
43
+ ## App Paths
44
+
45
+ Locate the surfaces this skill audits and the consumer call sites it points at:
46
+
47
+ | Surface | Glob (relative to app root) |
48
+ |---------|------------------------------|
49
+ | Companion exports (snapshot surface the renderer reads) | `specifications/src/companion-exports.ts` |
50
+ | Snapshot the renderer consumes | `specifications/src/market/**/*.ts` |
51
+ | Consumer call sites (CLIs / agents invoking the behaviors) | `frontend/src/**/*.ts` (sites that `companionPost('market-context-for-feature' \| 'market-context-for-icp')`) |
52
+
53
+ ## When to Use
54
+
55
+ - Wiring a `Cmd+K` style "edit feature X" editor agent that needs
56
+ the market truth for the feature it is editing (benefits in scope,
57
+ most-affected ICPs, anti-targets, preferred voice).
58
+ - Wiring the market-generation CLI (Phase 4.2) to fetch a per-ICP or
59
+ per-feature context block before pairing it with a
60
+ `MarketMessageTemplate` and an LLM call.
61
+ - Building a "show me the market context for X" debugging tool over
62
+ the companion HTTP surface (the rendered block doubles as a
63
+ human-readable diagnostic).
64
+
65
+ ## When NOT to Use
66
+
67
+ - Reading the raw `MarketSnapshot` for programmatic access — the
68
+ renderer is for prompt enrichment, not for snapshot inspection.
69
+ Consume the snapshot directly when you need typed access.
70
+ - Computing FIT scores — use `computeFeatureFitScoreForICP` /
71
+ `isBenefitAvailable`. The renderer only describes; it does not
72
+ score.
73
+ - Authoring the templates the market-generation CLI pairs the block
74
+ with — see `market-message-templates-authoring`.
75
+ - Generating localized prompts at authoring time — author English
76
+ only and pass `outputLanguage` to the renderer at call time.
77
+
78
+ ## Workflow
79
+
80
+ ### Step 1 — Decide the intent
81
+
82
+ Pick `feature` when the surrounding agent is editing or analysing
83
+ a specific feature (the block lists benefits delivered by that
84
+ feature, then the ICPs most affected). Pick `icp` when the surrounding
85
+ agent is producing per-ICP output (the block lists the ICP profile
86
+ plus benefits whose `importanceByICP[].weight >= 5` for that ICP).
87
+
88
+ The two intents share the same downstream sections (anti-target ICPs,
89
+ preferred voice, low-confidence open questions) so you only need one
90
+ call per LLM turn.
91
+
92
+ ### Step 2 — Call the companion via `companionPost`
93
+
94
+ The CLI side issues a standard `companionPost` request to either
95
+ behavior. The payload schema is:
96
+
97
+ ```ts
98
+ type MarketContextRequest =
99
+ | { featureRef: string; outputLanguage?: string } // market-context-for-feature
100
+ | { icpRef: string; outputLanguage?: string }; // market-context-for-icp
101
+ ```
102
+
103
+ The response is `{ block: string; trace: MarketContextBlockTrace }`.
104
+ The `trace` records the entities the renderer considered (benefits,
105
+ ICPs, voice) — surface it in CLI debug logs so authoring drift
106
+ ("why did benefit X not appear?") is diagnosable.
107
+
108
+ ### Step 3 — Pass the block into the LLM prompt verbatim
109
+
110
+ The block is markdown — paste it into the system / user message
111
+ verbatim. Do NOT post-process the markdown ("strip the headings"):
112
+ the section structure is what the LLM relies on to ground the
113
+ response. If you need a different shape, raise it upstream with the
114
+ framework; do not normalise on the consumer side.
115
+
116
+ ### Step 4 — Use `outputLanguage` for non-English output
117
+
118
+ Pass `outputLanguage: 'fr'` (or any BCP-47 tag) when the user wants
119
+ French / German / Spanish output. The renderer appends an "Output
120
+ language" instruction at the end; the LLM produces the final output
121
+ in that language. The block body stays English.
122
+
123
+ ## Behavior contract source
124
+
125
+ The pure renderer (`buildMarketContextBlock`):
126
+
127
+ ## Import Origins
128
+
129
+ - `@wildo-ai/dev-companion`
130
+
131
+ ## Source Excerpts
132
+
133
+ ### Origin Package: `@wildo-ai/dev-companion`
134
+
135
+ ```typescript
136
+ *
137
+ * Pure builder that renders an English "market context" prose block
138
+ * from a validated `MarketSnapshot`. The block is consumed by:
139
+ *
140
+ * - the dev-companion subprocess behaviors `market-context-for-feature`
141
+ * and `market-context-for-icp` (Phase 4.1);
142
+ * - the market generation CLI (`wildo market generate`) which
143
+ * concatenates the block with a `MarketMessageTemplate.promptTemplate`
144
+ * before sending to the LLM (Phase 4.2).
145
+ *
146
+ * **Pure function — no I/O, no DI, no runtime registry access, no
147
+ * mutation of the input snapshot.** The same `(snapshot, intent)`
148
+ * input always renders the same output (deterministic section order,
149
+ * deterministic ICP / benefit ordering by ref). This keeps the block
150
+ * trivial to snapshot-test and trivial to diff between snapshot
151
+ * versions.
152
+ *
153
+ * **English-only by contract (D15 / §12).** When `outputLanguage` is
154
+ * provided, the builder appends an "Output language" instruction line
155
+ * for the LLM, but does NOT translate any of the content above it.
156
+ * Translation happens at LLM-output time, never inside the spec.
157
+ *
158
+ * **Intent kinds:**
159
+ * - `{ kind: 'feature', featureRef }` — answers "I'm editing this
160
+ * feature, what is its market context?". Surfaces every benefit
161
+ * whose `deliveredByFeatureRefs[]` contains `featureRef`, the
162
+ * ICPs those benefits matter to, and the anti-target ICPs that
163
+ * would be repelled by them.
164
+ * - `{ kind: 'icp', icpRef }` — answers "I'm writing copy for this
165
+ * ICP, what's their world?". Surfaces the ICP's pains/gains/jobs,
166
+ * the benefits whose `importanceByICP[]` weights them at >= 5,
167
+ * and their preferred voice.
168
+ *
169
+ * **Section order (load-bearing — consumers may rely on it):**
170
+ * 1. `## Market context` header (with intent line)
171
+ * 2. `### Category`
172
+ * 3. `### Benefits in scope`
173
+ * 4. `### Most-affected ICPs`
174
+ * 5. `### Anti-target ICPs (do not pitch)`
175
+ * 6. `### Tone of voice`
176
+ * 7. `### Open questions / low-confidence entries` (skipped if empty)
177
+ * 8. `### Output language` (only when `outputLanguage` is set)
178
+ *
179
+ * Empty sections are kept (with an explicit `_(none)_` line) for
180
+ * sections 2–6 so the LLM sees the absence rather than silently
181
+ * inferring it. Section 7 is the lone exception — empty
182
+ * "low-confidence" lists carry no signal and are dropped.
183
+ */
184
+ export interface MarketContextBlockInput {
185
+ /** Validated `MarketSnapshot`. Caller is responsible for running
186
+ * `validateMarketSnapshot` first; this builder trusts the input. */
187
+ snapshot: MarketSnapshot;
188
+ intent:
189
+ | { kind: 'feature'; featureRef: string }
190
+ | { kind: 'icp'; icpRef: string };
191
+ /** Optional BCP-47 tag (e.g. `'fr'`, `'pt-BR'`). When set, the
192
+ * builder appends an "Output language" instruction; never
193
+ * translates the body. */
194
+ outputLanguage?: string;
195
+ }
196
+
197
+ /**
198
+ * Trace of the entities the builder considered. Useful for the CLI's
199
+ * `--explain` mode and for unit tests that assert "the builder
200
+ * picked the right ICP" without parsing prose.
201
+ *
202
+ * **Schema contract.** This interface is intentionally kept
203
+ * structurally compatible with the public `MarketContextBlockTraceSchema`
204
+ * contract exported by `@wildo-ai/saas-specifications`
205
+ * — the Phase-4.2 market generation CLI parses the companion HTTP
206
+ * response against that Zod schema. Any drift between this
207
+ * interface and that schema must be reflected on **both** sides
208
+ * (the schema is the cross-process contract; this interface is the
209
+ * local renderer typing).
210
+ */
211
+ export interface MarketContextBlockTrace {
212
+ /** Refs of every ICP whose section was rendered. Order matches
213
+ * the rendered output: feature intent → score-desc / priority /
214
+ * ref; icp intent → single requested ref or empty. */
215
+ icpsConsidered: string[];
216
+ /** Ordered (by ref) refs of every benefit whose section was rendered. */
217
+ benefitsConsidered: string[];
218
+ /** Ref of the tone of voice whose do/don't were rendered, or `null`. */
219
+ voiceUsed: string | null;
220
+ }
221
+
222
+ export interface MarketContextBlockResult {
223
+ /** English markdown prose, ready to concatenate with a template. */
224
+ block: string;
225
+ trace: MarketContextBlockTrace;
226
+ }
227
+
228
+ const ICP_PRIORITY_RANK: Record<ICPPriority, number> = {
229
+ [ICPPriority.CORE]: 0,
230
+ [ICPPriority.EXPANSION]: 1,
231
+ [ICPPriority.EXPLORATORY]: 2,
232
+ [ICPPriority.DEFERRED]: 3,
233
+ [ICPPriority.ANTI_TARGET]: 4,
234
+ };
235
+
236
+ /** Per-ICP fitness threshold for the `icp` intent's "Benefits in scope"
237
+ * section. Benefits with `importanceByICP[icp].weight >= 5` are
238
+ * considered relevant; below 5 the benefit is "noise" for that ICP. */
239
+ const ICP_BENEFIT_RELEVANCE_THRESHOLD = 5;
240
+
241
+ /** Maximum number of "Most-affected ICPs" lines rendered for the
242
+ * `feature` intent. Plan §10.2 caps at 3: the prompt should
243
+ * surface the *primary* audiences for a feature edit, not enumerate
244
+ * every ICP that mentioned it. The cap also keeps prompts short for
245
+ * snapshots with dozens of ICPs. */
246
+ const MAX_AFFECTED_ICPS_RENDERED = 3;
247
+
248
+ /** Defensive cap on the `outputLanguage` value rendered into the
249
+ * prompt. BCP-47 language tags are short by spec (the longest
250
+ * registered tag is well under 35 chars); a value longer than this
251
+ * is a misuse — most likely a caller pasted a paragraph instead of
252
+ * a tag. We refuse rather than silently embed garbage in the LLM
253
+ * prompt. The companion handlers also validate at the request
254
+ * boundary; this is a defense-in-depth guard for direct callers. */
255
+ const MAX_OUTPUT_LANGUAGE_LENGTH = 64;
256
+
257
+ export function buildMarketContextBlock(
258
+ input: MarketContextBlockInput,
259
+ ): MarketContextBlockResult {
260
+ const { snapshot, intent, outputLanguage } = input;
261
+
262
+ const icpsByRef = new Map(snapshot.icps.map(icp => [icp.ref, icp] as const));
263
+ const benefitsByRef = new Map(snapshot.benefits.map(b => [b.ref, b] as const));
264
+ const voicesByRef = new Map(snapshot.tonesOfVoice.map(v => [v.ref, v] as const));
265
+
266
+ const benefitsInScope = collectBenefitsInScope(snapshot, intent);
267
+ const affectedIcps = collectAffectedIcps(intent, benefitsInScope, icpsByRef);
268
+ const antiTargetIcps = snapshot.icps
269
+ .filter(icp => icp.priority === ICPPriority.ANTI_TARGET)
270
+ .slice()
271
+ .sort(compareByRef);
272
+
273
+ const voice = pickPreferredVoice({
274
+ intent,
275
+ icpsByRef,
276
+ affectedIcps,
277
+ voicesByRef,
278
+ });
279
+
280
+ const lowConfidenceEntries = collectLowConfidenceEntries({
281
+ intent,
282
+ snapshot,
283
+ benefitsInScope,
284
+ affectedIcps,
285
+ });
286
+
287
+ const lines: string[] = [];
288
+
289
+ lines.push(renderHeader(intent));
290
+ lines.push('');
291
+ lines.push(renderCategorySection(snapshot));
292
+ lines.push('');
293
+ lines.push(renderBenefitsSection(benefitsInScope));
294
+ lines.push('');
295
+ lines.push(renderAffectedIcpsSection(affectedIcps, intent, benefitsInScope));
296
+ lines.push('');
297
+ lines.push(renderAntiTargetSection(antiTargetIcps));
298
+ lines.push('');
299
+ lines.push(renderVoiceSection(voice));
300
+
301
+ if (lowConfidenceEntries.length > 0) {
302
+ lines.push('');
303
+ lines.push(renderLowConfidenceSection(lowConfidenceEntries));
304
+ }
305
+
306
+ const normalizedOutputLanguage = normalizeOutputLanguage(outputLanguage);
307
+ if (normalizedOutputLanguage) {
308
+ lines.push('');
309
+ lines.push(renderOutputLanguageSection(normalizedOutputLanguage));
310
+ }
311
+
312
+ return {
313
+ block: lines.join('\n'),
314
+ trace: {
315
+ icpsConsidered: affectedIcps.map(icp => icp.ref),
316
+ benefitsConsidered: benefitsInScope.map(b => b.ref),
317
+ voiceUsed: voice?.ref ?? null,
318
+ },
319
+ };
320
+ }
321
+
322
+ // ---------------------------------------------------------------------------
323
+ // Collection helpers
324
+ // ---------------------------------------------------------------------------
325
+
326
+ function collectBenefitsInScope(
327
+ snapshot: MarketSnapshot,
328
+ intent: MarketContextBlockInput['intent'],
329
+ ): FeatureBenefitConfig[] {
330
+ if (intent.kind === 'feature') {
331
+ return snapshot.benefits
332
+ .filter(b => b.deliveredByFeatureRefs.includes(intent.featureRef))
333
+ .slice()
334
+ .sort(compareByRef);
335
+ }
336
+
337
+ return snapshot.benefits
338
+ .filter(b =>
339
+ b.importanceByICP.some(
340
+ imp =>
341
+ imp.icpRef === intent.icpRef &&
342
+ imp.weight >= ICP_BENEFIT_RELEVANCE_THRESHOLD,
343
+ ),
344
+ )
345
+ .slice()
346
+ .sort(compareByRef);
347
+ }
348
+
349
+ /**
350
+ * Per-ICP score for the `feature` intent's `### Most-affected ICPs`
351
+ * ranking. Plan §10.2 calls for `weight × pain/gain degree`. Concretely:
352
+ *
353
+ * score(icp) = max over benefits-in-scope of (
354
+ * importanceByICP[icp].weight × max(degree across that benefit's
355
+ * relieves[] / creates[] / advances[] edges)
356
+ * )
357
+ *
358
+ * **Why max-of-max instead of a sum.** A benefit's degree edges are
359
+ * authored as "this benefit relieves pain X to degree 9" — they
360
+ * describe the **strength of one outcome**, not a list of outcomes
361
+ * to add up. Summing across edges would over-weight benefits with
362
+ * many shallow edges; summing across benefits would over-weight ICPs
363
+ * that appear on lots of mid-importance benefits. The signal we want
364
+ * for "most-affected ICPs" is "what is the strongest claim this
365
+ * feature lets us make for this ICP", which is a max-of-max.
366
+ *
367
+ * **Tie-breaks are deterministic** (rank → ref) so the rendered
368
+ * output is snapshot-stable.
369
+ */
370
+ function scoreIcpForFeatureIntent(
371
+ icpRef: string,
372
+ benefitsInScope: FeatureBenefitConfig[],
373
+ ): number {
374
+ let best = 0;
375
+ for (const benefit of benefitsInScope) {
376
+ const weight = benefit.importanceByICP.find(imp => imp.icpRef === icpRef)?.weight;
377
+ if (weight === undefined || weight <= 0) continue;
378
+ let bestDegree = 0;
379
+ for (const edge of benefit.relieves) bestDegree = Math.max(bestDegree, edge.degree);
380
+ for (const edge of benefit.creates) bestDegree = Math.max(bestDegree, edge.degree);
381
+ for (const edge of benefit.advances) bestDegree = Math.max(bestDegree, edge.degree);
382
+ // Benefits with no degree edges still carry weight signal — use 1
383
+ // as a neutral multiplier so a weight-only ranking still differentiates.
384
+ const benefitScore = weight * (bestDegree > 0 ? bestDegree : 1);
385
+ if (benefitScore > best) best = benefitScore;
386
+ }
387
+ return best;
388
+ }
389
+
390
+ function collectAffectedIcps(
391
+ intent: MarketContextBlockInput['intent'],
392
+ benefitsInScope: FeatureBenefitConfig[],
393
+ icpsByRef: Map<string, MarketICPConfig>,
394
+ ): MarketICPConfig[] {
395
+ if (intent.kind === 'icp') {
396
+ const icp = icpsByRef.get(intent.icpRef);
397
+ return icp ? [icp] : [];
398
+ }
399
+
400
+ const refs = new Set<string>();
401
+ for (const benefit of benefitsInScope) {
402
+ for (const imp of benefit.importanceByICP) {
403
+ refs.add(imp.icpRef);
404
+ }
405
+ }
406
+
407
+ type ScoredIcp = { icp: MarketICPConfig; score: number };
408
+ const scored: ScoredIcp[] = [];
409
+ for (const ref of refs) {
410
+ const icp = icpsByRef.get(ref);
411
+ if (!icp || icp.priority === ICPPriority.ANTI_TARGET) continue;
412
+ scored.push({ icp, score: scoreIcpForFeatureIntent(ref, benefitsInScope) });
413
+ }
414
+
415
+ // Primary sort: weighted score (descending). Ties: priority rank
416
+ // (CORE before EXPANSION before lower priorities). Final tie-break:
417
+ // ref (alphabetical) for snapshot-stable output.
418
+ scored.sort((a, b) => {
419
+ if (a.score !== b.score) return b.score - a.score;
420
+ const rankDelta = ICP_PRIORITY_RANK[a.icp.priority] - ICP_PRIORITY_RANK[b.icp.priority];
421
+ if (rankDelta !== 0) return rankDelta;
422
+ return compareByRef(a.icp, b.icp);
423
+ });
424
+
425
+ return scored.slice(0, MAX_AFFECTED_ICPS_RENDERED).map(entry => entry.icp);
426
+ }
427
+
428
+ function pickPreferredVoice(params: {
429
+ intent: MarketContextBlockInput['intent'];
430
+ icpsByRef: Map<string, MarketICPConfig>;
431
+ affectedIcps: MarketICPConfig[];
432
+ voicesByRef: Map<string, ToneOfVoiceConfig>;
433
+ }): ToneOfVoiceConfig | null {
434
+ const { intent, icpsByRef, affectedIcps, voicesByRef } = params;
435
+
436
+ if (intent.kind === 'icp') {
437
+ const icp = icpsByRef.get(intent.icpRef);
438
+ if (icp?.preferredVoiceRef) {
439
+ const voice = voicesByRef.get(icp.preferredVoiceRef);
440
+ if (voice) return voice;
441
+ }
442
+ }
443
+
444
+ for (const icp of affectedIcps) {
445
+ if (icp.preferredVoiceRef) {
446
+ const voice = voicesByRef.get(icp.preferredVoiceRef);
447
+ if (voice) return voice;
448
+ }
449
+ }
450
+
451
+ return null;
452
+ }
453
+
454
+ interface LowConfidenceEntry {
455
+ /** Dotted path inside the snapshot. */
456
+ path: string;
457
+ /** Display name of the entity (best-effort: `name` if present, else `ref`). */
458
+ label: string;
459
+ notes?: string;
460
+ }
461
+
462
+ function collectLowConfidenceEntries(params: {
463
+ intent: MarketContextBlockInput['intent'];
464
+ snapshot: MarketSnapshot;
465
+ benefitsInScope: FeatureBenefitConfig[];
466
+ affectedIcps: MarketICPConfig[];
467
+ }): LowConfidenceEntry[] {
468
+ const { intent, snapshot, benefitsInScope, affectedIcps } = params;
469
+ const entries: LowConfidenceEntry[] = [];
470
+
471
+ if (isLowConfidence(snapshot.category.authored)) {
472
+ entries.push({
473
+ path: 'category',
474
+ label: snapshot.category.name,
475
+ notes: snapshot.category.authored?.notes,
476
+ });
477
+ }
478
+
479
+ for (const icp of affectedIcps) {
480
+ if (isLowConfidence(icp.authored)) {
481
+ entries.push({
482
+ path: `icps[${snapshot.icps.indexOf(icp)}]`,
483
+ label: icp.name,
484
+ notes: icp.authored?.notes,
485
+ });
486
+ }
487
+ }
488
+
489
+ for (const benefit of benefitsInScope) {
490
+ if (isLowConfidence(benefit.authored)) {
491
+ entries.push({
492
+ path: `benefits[${snapshot.benefits.indexOf(benefit)}]`,
493
+ label: benefit.claim,
494
+ notes: benefit.authored?.notes,
495
+ });
496
+ }
497
+ }
498
+
499
+ // Personas: surface LOW-confidence personas whose `belongsToIcpRefs[]`
500
+ // intersects the **affected ICPs** for either intent kind. Under
501
+ // `icp` intent this is the requested ICP itself; under `feature`
502
+ // intent it's any ICP that the renderer surfaced under
503
+ // "Most-affected ICPs". Restricting to affected ICPs keeps the
504
+ // section signal-dense — we don't dump every LOW persona in the
505
+ // snapshot, only the ones the LLM is about to write copy for.
506
+ const affectedIcpRefs = new Set(affectedIcps.map(i => i.ref));
507
+ if (affectedIcpRefs.size > 0) {
508
+ for (const persona of snapshot.personas) {
509
+ if (!isLowConfidence(persona.authored)) continue;
510
+ if (!persona.belongsToIcpRefs.some(ref => affectedIcpRefs.has(ref))) continue;
511
+ entries.push({
512
+ path: `personas[${snapshot.personas.indexOf(persona)}]`,
513
+ label: persona.name,
514
+ notes: persona.authored?.notes,
515
+ });
516
+ }
517
+ }
518
+
519
+ return entries;
520
+ }
521
+
522
+ function isLowConfidence(authored: MarketAuthoredMetadata | undefined): boolean {
523
+ return authored?.confidence === AuthoredConfidence.LOW;
524
+ }
525
+
526
+ function compareByRef<T extends { ref: string }>(a: T, b: T): number {
527
+ return a.ref.localeCompare(b.ref);
528
+ }
529
+
530
+ // ---------------------------------------------------------------------------
531
+ // Render helpers
532
+ // ---------------------------------------------------------------------------
533
+
534
+ function renderHeader(intent: MarketContextBlockInput['intent']): string {
535
+ const intentLine =
536
+ intent.kind === 'feature'
537
+ ? `(intent: feature \`${intent.featureRef}\`)`
538
+ : `(intent: icp \`${intent.icpRef}\`)`;
539
+ return `## Market context ${intentLine}`;
540
+ }
541
+
542
+ function renderCategorySection(snapshot: MarketSnapshot): string {
543
+ const { name, definition } = snapshot.category;
544
+ return [
545
+ '### Category',
546
+ `- **Name:** ${name}`,
547
+ `- **Definition:** ${definition}`,
548
+ ].join('\n');
549
+ }
550
+
551
+ function renderBenefitsSection(benefits: FeatureBenefitConfig[]): string {
552
+ const lines = ['### Benefits in scope'];
553
+ if (benefits.length === 0) {
554
+ lines.push('_(none)_');
555
+ return lines.join('\n');
556
+ }
557
+ for (const benefit of benefits) {
558
+ const edges: string[] = [];
559
+ for (const e of benefit.relieves) {
560
+ edges.push(`relieves \`${e.painRef}\` (degree ${e.degree})`);
561
+ }
562
+ for (const e of benefit.creates) {
563
+ edges.push(`creates \`${e.gainRef}\` (degree ${e.degree})`);
564
+ }
565
+ for (const e of benefit.advances) {
566
+ edges.push(`advances \`${e.jobRef}\` (degree ${e.degree})`);
567
+ }
568
+ const edgeSummary = edges.length > 0 ? ` — ${edges.join('; ')}` : '';
569
+ lines.push(`- **${benefit.claim}** (\`${benefit.ref}\`, role ${benefit.role})${edgeSummary}`);
570
+ }
571
+ return lines.join('\n');
572
+ }
573
+
574
+ function renderAffectedIcpsSection(
575
+ icps: MarketICPConfig[],
576
+ intent: MarketContextBlockInput['intent'],
577
+ benefitsInScope: FeatureBenefitConfig[],
578
+ ): string {
579
+ const heading =
580
+ intent.kind === 'feature'
581
+ ? '### Most-affected ICPs'
582
+ : '### ICP profile';
583
+ const lines = [heading];
584
+ if (icps.length === 0) {
585
+ lines.push('_(none)_');
586
+ return lines.join('\n');
587
+ }
588
+
589
+ for (const icp of icps) {
590
+ const relevantImportance = benefitsInScope
591
+ .flatMap(b => b.importanceByICP)
592
+ .filter(imp => imp.icpRef === icp.ref);
593
+ const kanoSummary =
594
+ relevantImportance.length > 0
595
+ ? ` — kano: ${relevantImportance
596
+ .map(i => `${i.kanoCategory}@${i.weight}`)
597
+ .join(', ')}`
598
+ : '';
599
+ lines.push(
600
+ `- **${icp.name}** (\`${icp.ref}\`, priority ${icp.priority}, archetype ${icp.archetype})${kanoSummary}`,
601
+ );
602
+ }
603
+
604
+ return lines.join('\n');
605
+ }
606
+
607
+ function renderAntiTargetSection(icps: MarketICPConfig[]): string {
608
+ const lines = ['### Anti-target ICPs (do not pitch)'];
609
+ if (icps.length === 0) {
610
+ lines.push('_(none)_');
611
+ return lines.join('\n');
612
+ }
613
+ for (const icp of icps) {
614
+ lines.push(`- **${icp.name}** (\`${icp.ref}\`, archetype ${icp.archetype})`);
615
+ }
616
+ return lines.join('\n');
617
+ }
618
+
619
+ function renderVoiceSection(voice: ToneOfVoiceConfig | null): string {
620
+ const lines = ['### Tone of voice'];
621
+ if (!voice) {
622
+ lines.push('_(none — fall back to neutral)_');
623
+ return lines.join('\n');
624
+ }
625
+ lines.push(`- **${voice.name}** (\`${voice.ref}\`) — ${voice.description}`);
626
+ lines.push(`- **address:** ${voice.address}`);
627
+ lines.push(`- **do:** ${voice.doExamples.map(s => `"${s}"`).join('; ')}`);
628
+ lines.push(`- **don't:** ${voice.dontExamples.map(s => `"${s}"`).join('; ')}`);
629
+ return lines.join('\n');
630
+ }
631
+
632
+ function renderLowConfidenceSection(entries: LowConfidenceEntry[]): string {
633
+ const lines = ['### Open questions / low-confidence entries'];
634
+ for (const entry of entries) {
635
+ const noteSuffix = entry.notes ? ` — ${entry.notes}` : '';
636
+ lines.push(`- \`${entry.path}\` **${entry.label}**${noteSuffix}`);
637
+ }
638
+ return lines.join('\n');
639
+ }
640
+
641
+ /**
642
+ * Trim and validate an `outputLanguage` value before it lands inside
643
+ * the prompt. Returns `undefined` for missing / empty / whitespace-only
644
+ * inputs (so the section is skipped entirely). Throws for values
645
+ * longer than {@link MAX_OUTPUT_LANGUAGE_LENGTH} — that's a caller
646
+ * misuse (e.g. pasting a paragraph instead of a tag).
647
+ */
648
+ function normalizeOutputLanguage(value: string | undefined): string | undefined {
649
+ if (value === undefined) return undefined;
650
+ const trimmed = value.trim();
651
+ if (trimmed.length === 0) return undefined;
652
+ if (trimmed.length > MAX_OUTPUT_LANGUAGE_LENGTH) {
653
+ throw new Error(
654
+ `buildMarketContextBlock: \`outputLanguage\` is ${trimmed.length} chars long `
655
+ + `(max ${MAX_OUTPUT_LANGUAGE_LENGTH}). Pass a BCP-47 tag (e.g. \`'fr'\`, \`'pt-BR'\`), `
656
+ + `not a sentence — translation prose belongs in the LLM output, not the tag.`,
657
+ );
658
+ }
659
+ return trimmed;
660
+ }
661
+
662
+ function renderOutputLanguageSection(outputLanguage: string): string {
663
+ return [
664
+ '### Output language',
665
+ `Produce the final output in \`${outputLanguage}\`. The market context above is English on purpose — do not translate it; translate at output time only.`,
666
+ ].join('\n');
667
+ }
668
+ ```
669
+
670
+ The two introspection behavior definitions:
671
+
672
+ ## Import Origins
673
+
674
+ - `@wildo-ai/dev-companion`
675
+
676
+ ## Source Excerpts
677
+
678
+ ### Origin Package: `@wildo-ai/dev-companion`
679
+
680
+ ```typescript
681
+ */
682
+ 'market-context-for-feature': {
683
+ behaviorId: 'market-context-for-feature',
684
+ description:
685
+ 'Render an English market-context block for a feature ref — benefits in scope, '
686
+ + 'most-affected ICPs, anti-targets, preferred voice. Consumed by the dev companion '
687
+ + '"edit feature X" prompt enrichment and by the market generation CLI (Phase 4.2).',
688
+ category: 'market',
689
+ supportedServiceKinds: ['backend', 'frontend'],
690
+ routingByServiceKind: {
691
+ backend: {
692
+ target: 'specifications',
693
+ },
694
+ frontend: {
695
+ target: 'specifications',
696
+ },
697
+ },
698
+ execution: {
699
+ ...SHARED_EXECUTION_BOUNDARY,
700
+ materializationKind: 'json-snapshot',
701
+ },
702
+ },
703
+ 'market-context-for-icp': {
704
+ behaviorId: 'market-context-for-icp',
705
+ description:
706
+ 'Render an English market-context block for an ICP ref — relevant benefits, ICP profile, '
707
+ + 'anti-targets, preferred voice. Consumed by the market generation CLI when generating '
708
+ + 'per-ICP outputs (landing pages, emails, objection responses).',
709
+ category: 'market',
710
+ supportedServiceKinds: ['backend', 'frontend'],
711
+ routingByServiceKind: {
712
+ backend: {
713
+ target: 'specifications',
714
+ },
715
+ frontend: {
716
+ target: 'specifications',
717
+ },
718
+ },
719
+ execution: {
720
+ ...SHARED_EXECUTION_BOUNDARY,
721
+ materializationKind: 'json-snapshot',
722
+ },
723
+ },
724
+ /**
725
+ * Phase-4.2 market generation behavior. Materializes the **fully rendered
726
+ * prompt** for one `MarketMessageTemplate` ref + caller-supplied input
727
+ * refs (icp / feature / benefit / channel / objection / outputLanguage).
728
+ * The subprocess owns snapshot resolution + validation, template lookup,
729
+ * `requiredInputs` enforcement, context-block rendering, and Mustache
730
+ * substitution; the parent process consumes only the final prompt
731
+ * string before handing it to `AgentsBackendService.invokeAgent(...)`.
732
+ *
733
+ * The handler intentionally does NOT call the LLM itself — keeping the
734
+ * subprocess pure-and-deterministic preserves the "snapshot resolution
735
+ * happens in a child process, LLM happens in the parent" boundary
736
+ * established in Phase 4.1.
737
+ */
738
+ 'market-render-prompt': {
739
+ behaviorId: 'market-render-prompt',
740
+ description:
741
+ 'Render the full market generation prompt (English market-context block + Mustache-substituted '
742
+ + 'message template body) for one MarketMessageTemplate ref. Consumed by the dev-companion '
743
+ + '`/api/companion/market/generate` route, which feeds the prompt to AgentsBackendService.',
744
+ category: 'market',
745
+ supportedServiceKinds: ['backend', 'frontend'],
746
+ routingByServiceKind: {
747
+ backend: {
748
+ target: 'specifications',
749
+ },
750
+ frontend: {
751
+ target: 'specifications',
752
+ },
753
+ },
754
+ execution: {
755
+ ...SHARED_EXECUTION_BOUNDARY,
756
+ materializationKind: 'json-snapshot',
757
+ },
758
+ },
759
+ ```
760
+
761
+ The companion handlers wiring the behaviors to the renderer:
762
+
763
+ ## Import Origins
764
+
765
+ - `@wildo-ai/dev-companion`
766
+
767
+ ## Source Excerpts
768
+
769
+ ### Origin Package: `@wildo-ai/dev-companion`
770
+
771
+ ```typescript
772
+ */
773
+ 'market-context-for-feature': (input, context) => {
774
+ const { featureRef, outputLanguage } = parseMarketContextFeatureRequest(input);
775
+ const snapshot = resolveMarketSnapshot(context.moduleExports);
776
+ return buildMarketContextBlock({
777
+ snapshot,
778
+ intent: { kind: 'feature', featureRef },
779
+ outputLanguage,
780
+ });
781
+ },
782
+ 'market-context-for-icp': (input, context) => {
783
+ const { icpRef, outputLanguage } = parseMarketContextIcpRequest(input);
784
+ const snapshot = resolveMarketSnapshot(context.moduleExports);
785
+ return buildMarketContextBlock({
786
+ snapshot,
787
+ intent: { kind: 'icp', icpRef },
788
+ outputLanguage,
789
+ });
790
+ },
791
+ /**
792
+ * Phase-4.2 market generation handler. Reuses the same snapshot
793
+ * resolver as the two `market-context-*` handlers (so validation
794
+ * runs once per snapshot identity, with shared WARN dedup) and
795
+ * defers prompt assembly to the pure `renderMarketPrompt(...)`.
796
+ */
797
+ 'market-render-prompt': (input, context) => {
798
+ const request = parseMarketRenderPromptRequest(input);
799
+ const snapshot = resolveMarketSnapshot(context.moduleExports);
800
+ return renderMarketPrompt({ snapshot, request });
801
+ },
802
+ ```
803
+
804
+ The companion-exports surface that resolves the snapshot:
805
+
806
+ ## Import Origins
807
+
808
+ - `@wildo-ai/saas-specifications`
809
+
810
+ ## Source Excerpts
811
+
812
+ ### Origin Package: `@wildo-ai/saas-specifications`
813
+
814
+ ```typescript
815
+ *
816
+ * Typed companion export surface: registries of resource specs, definitions, and view specs the dev companion materializes.
817
+ */
818
+ export interface SpecificationsCompanionExports<
819
+ TResourceSpecifications = ResourceSpecification,
820
+ TBusinessSemanticsSnapshot = BusinessSemanticsSnapshot,
821
+ TFeatureSpecifications = FeatureSpecification,
822
+ TMilestoneSpecifications = MilestoneSpecification,
823
+ TProductSpecifications = ProductSpecification,
824
+ TRoleSpecifications = RoleSpecification,
825
+ TFrontendComponentSpecifications = FrontendComponentSpecification,
826
+ TCompositeViewSpecifications = CompositeViewSpecification,
827
+ TFullCustomViewSpecifications = FullCustomViewSpecification,
828
+ TFlowsActorsViewSpecifications = FlowsActorsViewSpecification,
829
+ TChartViewSpecifications = ChartViewSpecification,
830
+ TExecutionViewSpecifications = ExecutionViewSpecification,
831
+ TSystemEmailTemplateSpecifications = SystemEmailTemplateSpecification,
832
+ TOnboardingViewSpecifications = OnboardingViewSpecification,
833
+ TGuidanceFlowSpecifications = GuidanceFlowSpecification,
834
+ TDataSeedSpecifications = DataSeedSpecification,
835
+ TMarketSnapshot = MarketSnapshot,
836
+ TCatalogSpecifications = CatalogSpecifications,
837
+ // Appended LAST (not inserted mid-list): consumers pass these generics
838
+ // positionally (see the app companion-exports), so a new param must go at the
839
+ // end to avoid shifting existing ones onto the wrong types.
840
+ TSidebarSectionSpecifications = SidebarSectionSpecification,
841
+ TAssertionSpecifications = AssertionSpecificationSnapshot,
842
+ // ── app-creation meta-workflows C-4 definition families (U1–U4) — RESERVED SLOTS ──
843
+ // Four sibling `_core` families each register ONE companion-exports slot here,
844
+ // appended STRICTLY LAST in this FIXED order. Each session appends its generic
845
+ // param (below) AND its interface field (further down) AFTER the previous
846
+ // family's — NEVER re-order, NEVER insert mid-list. Consumers pass generics
847
+ // positionally, so re-ordering silently shifts every later app onto the wrong
848
+ // type. The reservation order (do not change):
849
+ // All four reserved families are now registered (U1–U4 done); the
850
+ // reserved-slots block below is fully filled and no further reservation
851
+ // follows. The final order (do not change):
852
+ // 1. vision (U1 — registered below)
853
+ // 2. requirements (U2 — registered below)
854
+ // 3. roadmap (U3 — registered below)
855
+ // 4. business-model-lite (U4 — registered below, LAST)
856
+ TVisionSnapshot = VisionSnapshot,
857
+ TRequirementsSnapshot = RequirementsSnapshot,
858
+ TRoadmapSnapshot = RoadmapSnapshot,
859
+ TBuildPlanTaskGraph = BuildPlanTaskGraph,
860
+ TPlacementPlan = PlacementPlan,
861
+ TDomainPlanOutputSet = DomainPlanOutputSet,
862
+ TBusinessModelLiteSnapshot = BusinessModelLiteSnapshot,
863
+ // Appended STRICTLY LAST (positional generics — never insert mid-list):
864
+ // the brand visual-identity definition family (`brand-brief`).
865
+ TBrandSnapshot = BrandSnapshot,
866
+ // Appended STRICTLY LAST: the expert-personas family (derived worker-persona
867
+ // charters — plural array, unlike the singleton snapshot families above).
868
+ TExpertPersonaCharters = ExpertPersonaCharter[],
869
+ // Appended STRICTLY LAST: accepted spec-first feature intent. This is
870
+ // deliberately distinct from `featureSpecifications`, whose entries already
871
+ // decorate runtime FeatureDefinitions and therefore represent a later stage.
872
+ TFeatureSpecificationDrafts = FeatureSpecificationDrafts,
873
+ // Appended STRICTLY LAST: accepted application compliance policy. The slot
874
+ // remains optional so applications that do not opt into `compliance-program`
875
+ // preserve their existing projection and family-head behavior.
876
+ TComplianceSpecification = AssuranceProgramSpecification,
877
+ // Appended STRICTLY LAST: the application's accepted public-document
878
+ // publication variants (`document-publication` family). Separate from
879
+ // `complianceSpecification` on purpose — see the field's JSDoc.
880
+ TDocumentPublicationSpecification = ApplicationDocumentPublicationSpecification,
881
+ // Appended STRICTLY LAST: accepted document facts that cannot be inferred
882
+ // from other semantic families. Raw decisions only; runtime grants,
883
+ // approvals and releases never enter companion exports.
884
+ TDocumentFactSpecification = ApplicationDocumentFactSpecification,
885
+ // Appended STRICTLY LAST: release-process selection is a separate accepted
886
+ // decision, never an implicit default of routing or document necessity.
887
+ TDocumentReleasePolicySpecification = ApplicationDocumentReleasePolicySpecification,
888
+ // Appended STRICTLY LAST: WHO else processes personal data, under what legal
889
+ // identity and where (issue #88). Optional, and the optionality is the design:
890
+ // a partial register is useful and its holes are REPORTED per provider against
891
+ // the application's configured set, rather than blocking anything.
892
+ TProcessorRegister = ApplicationProcessorRegister,
893
+ > {
894
+ resourceSpecifications: TResourceSpecifications;
895
+ applicationBusinessSemanticsSnapshot?: TBusinessSemanticsSnapshot;
896
+ /**
897
+ * Feature overlays exposed to the dev companion.
898
+ *
899
+ * **Required** (promoted 2026-04-22, carryforward #5 of the
900
+ * `non-view-specification-coverage` plan). The engine ships 7 explicit
901
+ * `CoreFeature` overlays plus an `EngineCapability`-derived programmatic
902
+ * module via `engineFeatureSpecifications`, so apps always have
903
+ * something to expose. Apps with no app-level feature overlays should
904
+ * pass `engineFeatureSpecifications` directly; apps with overlays
905
+ * should merge their own bi-scoped map on top using the same
906
+ * `buildFeatureSpecificationMap(...)` factory used by Your Application.
907
+ */
908
+ featureSpecifications: TFeatureSpecifications;
909
+ /**
910
+ * Milestone overlays exposed to the dev companion.
911
+ *
912
+ * **Required** (promoted 2026-04-22, carryforward #5). Engine ships
913
+ * zero milestone overlays today (apps own the catalog), but the
914
+ * required discipline forces apps to either pass an explicit
915
+ * `buildMilestoneSpecificationMap()` (empty or otherwise) or wire a
916
+ * real overlay registry — eliminating the silent "I forgot to wire
917
+ * this surface" failure mode the optional shape allowed.
918
+ */
919
+ milestoneSpecifications: TMilestoneSpecifications;
920
+ /**
921
+ * Product overlays exposed to the dev companion.
922
+ *
923
+ * **Required** (promoted 2026-04-22, carryforward #5). Same rationale
924
+ * as `milestoneSpecifications` — engine ships zero today, but the
925
+ * required shape eliminates the silent-omission failure mode.
926
+ */
927
+ productSpecifications: TProductSpecifications;
928
+ /**
929
+ * Role overlays exposed to the dev companion.
930
+ *
931
+ * **Required** (promoted 2026-04-22, carryforward #5). Engine ships
932
+ * 12 explicit core-role overlays via `engineRoleSpecifications` (one
933
+ * per `CORE_APP_ROLES.*` member), so apps always have something to
934
+ * expose. Apps with no app-level roles should pass
935
+ * `engineRoleSpecifications` directly.
936
+ */
937
+ roleSpecifications: TRoleSpecifications;
938
+ frontendComponentSpecifications?: TFrontendComponentSpecifications;
939
+ compositeViewSpecifications?: TCompositeViewSpecifications;
940
+ fullCustomViewSpecifications?: TFullCustomViewSpecifications;
941
+ flowsActorsViewSpecifications?: TFlowsActorsViewSpecifications;
942
+ chartViewSpecifications?: TChartViewSpecifications;
943
+ executionViewSpecifications?: TExecutionViewSpecifications;
944
+ /**
945
+ * Sidebar-section overlays exposed to the dev companion. Optional: sidebar
946
+ * sections are structural app-shell config with no prose of their own; an app
947
+ * that wants grounded sidebar labels authors a
948
+ * `buildSidebarSectionSpecificationMap(...)` here, otherwise the family falls
949
+ * back to keys-only generation.
950
+ */
951
+ sidebarSectionSpecifications?: TSidebarSectionSpecifications;
952
+ /**
953
+ * System-email template overlays exposed to the dev companion.
954
+ *
955
+ * **Required** because the engine ships 12 templates out of the box
956
+ * (`engineSystemEmailTemplateSpecifications`); apps therefore always have
957
+ * something to expose, and forgetting to wire this surface would silently
958
+ * lose the entire system-email companion family. Apps with no app-level
959
+ * templates should pass `engineSystemEmailTemplateSpecifications` directly.
960
+ */
961
+ systemEmailTemplateSpecifications: TSystemEmailTemplateSpecifications;
962
+ /**
963
+ * Onboarding-view overlays exposed to the dev companion.
964
+ *
965
+ * **Required** (promoted 2026-04-22, carryforward #5). Engine ships
966
+ * zero onboarding views by default, but the required shape eliminates
967
+ * the silent-omission failure mode. Apps with no app-level onboarding
968
+ * views should pass an empty `buildOnboardingViewSpecificationMap()`
969
+ * rather than omitting the field.
970
+ */
971
+ onboardingViewSpecifications: TOnboardingViewSpecifications;
972
+ /**
973
+ * Guidance-flow overlays exposed to the dev companion.
974
+ *
975
+ * **Required** (promoted 2026-04-22, carryforward #5). Same discipline
976
+ * as `onboardingViewSpecifications` — engine ships zero by default,
977
+ * but the required shape eliminates the silent-omission failure mode.
978
+ * Apps with no app-level guidance flows should pass an empty
979
+ * `buildGuidanceFlowSpecificationMap()` rather than omitting the field.
980
+ */
981
+ guidanceFlowSpecifications: TGuidanceFlowSpecifications;
982
+ /**
983
+ * Data-seeding overlays exposed to the dev companion.
984
+ *
985
+ * **Optional** in Phase 1 because the engine ships zero seeds yet — the
986
+ * `DataSeedRegistry` and the dispatcher land in Phase 2. Authoring a seed
987
+ * spec without the runtime declaration is allowed (the spec slice is
988
+ * useful as design documentation on its own); authoring a runtime seed
989
+ * without a spec is also allowed (no companion grounding, dispatcher
990
+ * still runs it). Once Phase 2 ships engine seeds this field will be
991
+ * promoted to required, mirroring `systemEmailTemplateSpecifications`.
992
+ *
993
+ * Apps with no app-level seeds should pass an empty
994
+ * `buildDataSeedSpecificationMap()` rather than omitting the field once
995
+ * Phase 2 lands.
996
+ */
997
+ dataSeedSpecifications?: TDataSeedSpecifications;
998
+ /**
999
+ * Application market specification — the English-authored marketing /
1000
+ * positioning truth (category, ICPs, personas, jobs/pains/gains, tones
1001
+ * of voice, benefits, positionings, message templates). Optional today
1002
+ * because not every example app authors a market snapshot yet; once it
1003
+ * graduates to required, app bootstraps should run
1004
+ * `validateMarketSnapshot` on the value before wiring it here.
1005
+ *
1006
+ * Authored entirely in English. Geographic targeting (the only
1007
+ * "localization" the slice models) lives inside
1008
+ * `MarketICP.profile.geographies`.
1009
+ */
1010
+ marketSpecification?: TMarketSnapshot;
1011
+ /**
1012
+ * Catalog specifications — declarations of EXTERNAL vocabularies the
1013
+ * framework reasons about (Schema.org JSON-LD today; future:
1014
+ * OpenAPI, RSS, JSON-Feed). Distinct from overlay specs above —
1015
+ * overlay specs decorate registry entries (resources, features,
1016
+ * views); catalog specs OWN the contract for an external
1017
+ * vocabulary's per-entity shape (required / optional / deprecated
1018
+ * field declarations).
1019
+ *
1020
+ * **Composition**: apps spread the engine catalog (e.g.
1021
+ * `ENGINE_SCHEMA_ORG_CATALOG`) and append app-side extensions /
1022
+ * overrides. The companion's catalog reconciliation runs against
1023
+ * this merged surface — emission sites in `@wildo-ai/saas-website`
1024
+ * sections (via `getStructuredData()`) are checked against the
1025
+ * merged `schemaOrg` catalog, with warnings on missing required
1026
+ * fields, deprecated-field usage, and (when wired) missing
1027
+ * recommended optionals. Catalog overrides (app entry redefining
1028
+ * an engine entry's `@type`) emit a `catalog-override` boot
1029
+ * warning.
1030
+ *
1031
+ * **Optional** in v1 because not every app emits structured data
1032
+ * yet. Apps wiring an engine catalog explicitly opt into
1033
+ * companion reconciliation by populating the matching slot.
1034
+ */
1035
+ catalogSpecifications?: TCatalogSpecifications;
1036
+ /**
1037
+ * Assertion surface — the authored layer of the dynamic Assertion
1038
+ * Surface (app-creation meta-workflows, master plan S1): statements
1039
+ * about the platform served via the companion `assertions-list` /
1040
+ * `assertions-resolve` / `assertions-reconcile` behaviors, with
1041
+ * status computed by reconcile rather than hand-maintained.
1042
+ *
1043
+ * **Optional** — the launch posture of every new family: not every
1044
+ * example app authors assertions yet, and the family must not break
1045
+ * existing companion exports on arrival. Once it graduates to
1046
+ * required, app bootstraps should run
1047
+ * `validateAssertionSpecificationSnapshot` on the value before
1048
+ * wiring it here (the behavior resolver validates on entry either
1049
+ * way, market-style).
1050
+ *
1051
+ * Lane discipline: entries carrying
1052
+ * `lane: AssertionLane.FRAMEWORK_DEV` are framework-development
1053
+ * knowledge (end-state platform bets authored in the dogfood app
1054
+ * during the framework-parallel era) and must NEVER compile into
1055
+ * shipped app knowledge — consumers filter on `lane` deliberately.
1056
+ */
1057
+ assertionSpecifications?: TAssertionSpecifications;
1058
+ // ── app-creation meta-workflows C-4 definition families (U1–U4) — FIELDS ──
1059
+ // One field per family, in the SAME fixed order as the generic params
1060
+ // above. All four are now registered (U1–U4 done); no reservation remains:
1061
+ // 1. visionSpecification (U1 — below)
1062
+ // 2. requirementsSpecification (U2 — below)
1063
+ // 3. roadmapSpecification (U3 — below)
1064
+ // 4. businessModelLiteSpecification (U4 — below, LAST)
1065
+ /**
1066
+ * Application **vision** specification — the foundational-intent truth
1067
+ * (idea, problem statement, mission, success criteria, constraints incl.
1068
+ * compliance) the app-creation top-down catalog reads/writes (C-4
1069
+ * definition families). A single aggregate per app (market-snapshot
1070
+ * style), validated by `validateVisionSnapshot`.
1071
+ *
1072
+ * **Optional** — the launch posture of every new family (market /
1073
+ * assertions parity): not every example app authors a vision snapshot
1074
+ * yet, and the family must not break existing companion exports on
1075
+ * arrival. Once it graduates to required, app bootstraps should run
1076
+ * `validateVisionSnapshot` on the value before wiring it here.
1077
+ */
1078
+ visionSpecification?: TVisionSnapshot;
1079
+ /**
1080
+ * Application **requirements** specification — the requirements-layer
1081
+ * truth (functional requirements + non-functional requirements, each
1082
+ * optionally cross-referencing market ICPs / jobs) the app-creation
1083
+ * top-down capability-map catalog reads/writes (C-4 definition
1084
+ * families). A single aggregate per app (market-snapshot style),
1085
+ * validated by `validateRequirementsSnapshot`.
1086
+ *
1087
+ * **Optional** — the launch posture of every new family (vision /
1088
+ * market / assertions parity): not every example app authors a
1089
+ * requirements snapshot yet, and the family must not break existing
1090
+ * companion exports on arrival. Once it graduates to required, app
1091
+ * bootstraps should run `validateRequirementsSnapshot` on the value
1092
+ * before wiring it here.
1093
+ */
1094
+ requirementsSpecification?: TRequirementsSnapshot;
1095
+ /**
1096
+ * Application **roadmap** specification — the delivery-roadmap truth (a
1097
+ * product's delivery plan as an ordered collection of releases/phases,
1098
+ * each optionally cross-referencing the requirements /
1099
+ * vision-success-criteria it delivers) the app-creation top-down
1100
+ * scope/roadmap catalog reads/writes (C-4 definition families). A single
1101
+ * aggregate per app (market-snapshot style), validated by
1102
+ * `validateRoadmapSnapshot`. Distinct from `milestoneSpecifications` (a
1103
+ * dated registry-overlay surface) — a roadmap phase is a planning
1104
+ * artifact, not a runtime milestone.
1105
+ *
1106
+ * **Optional** — the launch posture of every new family (vision /
1107
+ * requirements / market / assertions parity): not every example app
1108
+ * authors a roadmap snapshot yet, and the family must not break existing
1109
+ * companion exports on arrival. Once it graduates to required, app
1110
+ * bootstraps should run `validateRoadmapSnapshot` on the value before
1111
+ * wiring it here.
1112
+ */
1113
+ roadmapSpecification?: TRoadmapSnapshot;
1114
+ /**
1115
+ * Application **build-plan** specification — the ORDERED typed task graph
1116
+ * (`BuildPlanTaskGraph`, `_core/build-plan/`) that turns the accepted domain
1117
+ * plan into buildable units; produced by the build-decompose playbook and
1118
+ * consumed one READY task at a time by build-dispatch. Optional until an
1119
+ * application reaches the bottom-up phase; app bootstraps should run
1120
+ * `validateBuildPlanTaskGraph` on the value before wiring it here.
1121
+ */
1122
+ buildPlanSpecification?: TBuildPlanTaskGraph;
1123
+ /**
1124
+ * Application **placement** specification — WHERE every settings destination,
1125
+ * resource operation and app view sits in the shell, and WHY (`PlacementPlan`,
1126
+ * `_core/placement-plan/`).
1127
+ *
1128
+ * Produced by the `bottom_up.placement-plan` playbook as an expert-panel
1129
+ * DELIBERATION rather than a creator elicitation: the creator does not choose
1130
+ * placement, so each decision carries a `rationale` that answers "why is this
1131
+ * here?" without re-running the panel. Consumed by build-decompose, which
1132
+ * turns it into the coding tasks that author `settings-hub.config.ts` and
1133
+ * `app-shell.config.ts`.
1134
+ *
1135
+ * Optional until an application reaches the bottom-up phase; app bootstraps
1136
+ * should run `validatePlacementPlan` on the value before wiring it here.
1137
+ */
1138
+ placementPlanSpecification?: TPlacementPlan;
1139
+ /**
1140
+ * Application **domain-plan** specification — the atomic module decomposition
1141
+ * PLUS relationship drafts (`DomainPlanOutputSet`, `_core/domain-plan/`);
1142
+ * produced by the domain-plan playbook, decomposed by build-decompose.
1143
+ * Optional until an application reaches the bottom-up phase.
1144
+ */
1145
+ domainPlanSpecification?: TDomainPlanOutputSet;
1146
+ /**
1147
+ * Application **business-model-lite** specification — the lightweight
1148
+ * business-model truth (a coarse product-level revenue model + a pricing-
1149
+ * plan sketch, each plan optionally cross-referencing the market ICPs it
1150
+ * targets and the requirements it includes) the app-creation top-down
1151
+ * catalog reads/writes (C-4 definition families). A single aggregate per
1152
+ * app (market-snapshot style), validated by
1153
+ * `validateBusinessModelLiteSnapshot`. A PLANNING artifact — deliberately
1154
+ * NOT the live billing / Stripe product-catalog runtime (it models
1155
+ * pricing INTENT, never chargeable state). The `-lite` is the
1156
+ * scaffold-depth qualifier of the Phase-J1 increment; the artifact-family
1157
+ * id is `business-model`.
1158
+ *
1159
+ * **Optional** — the launch posture of every new family (vision /
1160
+ * requirements / roadmap / market / assertions parity): not every example
1161
+ * app authors a business-model snapshot yet, and the family must not break
1162
+ * existing companion exports on arrival. Once it graduates to required,
1163
+ * app bootstraps should run `validateBusinessModelLiteSnapshot` on the
1164
+ * value before wiring it here.
1165
+ */
1166
+ businessModelLiteSpecification?: TBusinessModelLiteSnapshot;
1167
+ /**
1168
+ * Application **brand** specification — the visual-identity brief (brand
1169
+ * name + logo direction + visual tone; `resolvedAssets` populated by the
1170
+ * companion logo step) the app-creation top-down `brand-identity` playbook
1171
+ * reads/writes. A single aggregate per app (vision-snapshot style),
1172
+ * validated by `validateBrandSnapshot`. Read by the companion
1173
+ * `brand-render-prompt` behavior to assemble the logo generation prompt;
1174
+ * the artifact-family id is `brand-brief`.
1175
+ *
1176
+ * **Optional** — the launch posture of every new family: not every example
1177
+ * app authors a brand snapshot yet, and the family must not break existing
1178
+ * companion exports on arrival.
1179
+ */
1180
+ brandSpecification?: TBrandSnapshot;
1181
+ /**
1182
+ * Application **expert-persona charters** — the DERIVED worker-persona
1183
+ * instances (`ExpertPersonaCharter[]`) of the framework's
1184
+ * `EXPERT_ROLE_TEMPLATES` (art-director, copy-chief, …), committed under
1185
+ * `specifications/src/personas/` by the companion's derive→accept flow
1186
+ * (and hand-editable thereafter; a human edit is recorded in `authored`).
1187
+ *
1188
+ * Consumed by the companion's `expert-persona-charters` introspection
1189
+ * behavior: the deliberation system builds each expert's agent from the
1190
+ * committed charter at startup, and the accept step reads the set for its
1191
+ * human-edit overwrite guard + `validateExpertPersonaCharters` run.
1192
+ *
1193
+ * PLURAL by design (unlike the singleton snapshot families above): an app
1194
+ * has one charter per role, several roles. Distinct from the market
1195
+ * family's `personas` (BUYER personas — who the app sells to); these are
1196
+ * WORKER personas (who does the creative work).
1197
+ *
1198
+ * **Optional** — the launch posture of every new family: not every example
1199
+ * app has derived charters yet, and the family must not break existing
1200
+ * companion exports on arrival. Apps with charters should export the
1201
+ * generated `appExpertPersonaCharters` aggregate from
1202
+ * `specifications/src/personas/`.
1203
+ */
1204
+ expertPersonaCharters?: TExpertPersonaCharters;
1205
+ /**
1206
+ * Accepted **feature drafts** produced by the top-down capability-map.
1207
+ *
1208
+ * Drafts carry product intent only: purpose, business role, lifecycle and
1209
+ * availability guidance. They deliberately exclude runtime-definition
1210
+ * provenance and executable scope. Phase-gate and domain-planning evidence
1211
+ * consume this member; `featureSpecifications` remains the separate
1212
+ * runtime-backed overlay surface used after capabilities are implemented.
1213
+ *
1214
+ * **Optional** at the aggregate contract boundary because applications that
1215
+ * have not entered the app-creation workflow may not have accepted drafts.
1216
+ * A treatment selecting the `feature-drafts` family fails closed when the
1217
+ * member is absent.
1218
+ */
1219
+ featureDraftsSpecification?: TFeatureSpecificationDrafts;
1220
+ /**
1221
+ * Accepted application **compliance program** policy.
1222
+ *
1223
+ * This is the configured application's reusable source/scope/objective,
1224
+ * implementation-choice, responsibility, gap/exception and documentation
1225
+ * truth. It deliberately excludes live organizations, assignees, reviewer
1226
+ * identities, evidence bytes and operating-effectiveness claims.
1227
+ *
1228
+ * **Optional** at launch. If the application declares the
1229
+ * `compliance-program` family, the semantic family authority requires this
1230
+ * member and validates it fail closed. Applications without that family must
1231
+ * not synthesize this value or receive positive compliance-program claims.
1232
+ */
1233
+ complianceSpecification?: TComplianceSpecification;
1234
+ /**
1235
+ * Accepted application **public-document publication variants**.
1236
+ *
1237
+ * The exact locale × jurisdiction combinations in which this application
1238
+ * publishes public governed documents. It is the ONLY source a governed
1239
+ * document candidate may take its locale and jurisdictions from: the
1240
+ * candidate host seals these bytes into a publication-variant authority
1241
+ * bound to the `document-publication` family's retained head, and refuses
1242
+ * any combination that is not an exact member.
1243
+ *
1244
+ * Distinct from `complianceSpecification` by design. The assurance program
1245
+ * decides which documents are required and who approves them; this slot
1246
+ * decides where and in which language they are published. Folding the two
1247
+ * would let a document requirement widen its own publication routing.
1248
+ *
1249
+ * **Optional** at the aggregate contract boundary. An application that
1250
+ * declares no `document-publication` family publishes no public governed
1251
+ * document, and candidate creation fails closed rather than defaulting to a
1252
+ * locale or jurisdiction nobody accepted.
1253
+ */
1254
+ documentPublicationSpecification?: TDocumentPublicationSpecification;
1255
+ /**
1256
+ * Accepted application selection of the human release lane for each exact
1257
+ * governed-document requirement. Optional at the aggregate boundary: an
1258
+ * application with no policy can still generate a working draft, but every
1259
+ * exposure attempt fails closed rather than assuming operator attestation or
1260
+ * qualified review.
1261
+ */
1262
+ documentReleasePolicySpecification?: TDocumentReleasePolicySpecification;
1263
+ /**
1264
+ * Accepted application **governed-document facts**.
1265
+ *
1266
+ * This optional slot carries raw application, creator-decision and
1267
+ * qualified-review fact declarations from the dedicated `document-facts`
1268
+ * specification family. The application-creation host validates the exact
1269
+ * accepted family head and seals derived contribution digests and validation
1270
+ * receipts; application code never authors those host identities.
1271
+ *
1272
+ * Reviewer authority grants, review decisions, candidates and immutable
1273
+ * releases are runtime/private custody and are forbidden from this slot.
1274
+ * Omitting it is honest: unresolved document facts remain visible gaps.
1275
+ */
1276
+ documentFactSpecification?: TDocumentFactSpecification;
1277
+ /**
1278
+ * WHO else processes this application's personal data — legal identity, processing region and the
1279
+ * processor's own subprocessors (issue #88).
1280
+ *
1281
+ * A configured provider already establishes THAT a third party is involved and what function it
1282
+ * performs. None of that is what a privacy notice's recipient statement needs, and an
1283
+ * international-transfer statement cannot be made at all without a region.
1284
+ *
1285
+ * Optional, and its holes are reported rather than blocking: the companion compares this register
1286
+ * against the application's CONFIGURED providers and names each one that is undeclared, so a partial
1287
+ * register is useful and an empty one still produces an actionable document. An absent entry means
1288
+ * nobody has established that processor's identity — never that the provider is unused.
1289
+ */
1290
+ processorRegister?: TProcessorRegister;
1291
+ /**
1292
+ * Accepted application-declared semantic causality between whole
1293
+ * specification-family states. This is not the registry's physical
1294
+ * dependency graph and not Actor/Flow execution order. The runtime resolves
1295
+ * these declarations only through the exact CURRENT accepted projection,
1296
+ * then may derive a rebuildable impact index; this export itself does not
1297
+ * authorize a journal write, review queue or application mutation.
1298
+ *
1299
+ * Optional because semantic impact is an advanced application-creation
1300
+ * capability. An application that declares the dedicated
1301
+ * `semantic-dependencies` family must provide this field; a resolver refuses
1302
+ * a missing or malformed value rather than infer dependencies from imports
1303
+ * or registry edges.
1304
+ */
1305
+ }
1306
+
1307
+ /**
1308
+ * Aggregate of every catalog vocabulary an app can wire on the
1309
+ * `catalogSpecifications` companion-exports slot.
1310
+ *
1311
+ * Each vocabulary is a flat array of validated entries (engine
1312
+ * + app entries merged at wiring time). The companion harness keys
1313
+ * each vocabulary by its discriminator (`@type` for Schema.org;
1314
+ * future vocabularies can use `operationId`, `kind`, etc.); app
1315
+ * entries silently override engine entries on collision and the
1316
+ * harness emits a `catalog-override` warning for each override at
1317
+ * boot.
1318
+ *
1319
+ * **Why an aggregate type and not per-slot fields**: every future
1320
+ * vocabulary lands as a sibling field on this single type rather
1321
+ * than as a new top-level companion-exports field. This keeps the
1322
+ * `SpecificationsCompanionExports` shape stable as the catalog
1323
+ * surface grows.
1324
+ */
1325
+ export interface CatalogSpecifications {
1326
+ /**
1327
+ * Schema.org JSON-LD vocabulary catalog. Compose with
1328
+ * `ENGINE_SCHEMA_ORG_CATALOG` (engine-shipped standard entries)
1329
+ * spread, then append app-side extensions / overrides.
1330
+ */
1331
+ schemaOrg?: readonly SchemaOrgCatalogEntryBase[];
1332
+ }
1333
+ ```
1334
+
1335
+ ## Worked Example (input/output triangulation)
1336
+
1337
+ The renderer's output (`buildMarketContextBlock(snapshot, opts)`)
1338
+ does not yet have a stable `example.market.context-block.rendered`
1339
+ anchor — the markdown block shape iterates each time a new
1340
+ introspection behavior ships, so freezing an output snippet would
1341
+ go stale. The pair below brackets the renderer:
1342
+
1343
+ **Input** — the assembled `MarketSnapshot` the renderer reads:
1344
+
1345
+
1346
+ ## Usage Example
1347
+
1348
+ ```typescript
1349
+ *
1350
+ * Canonical Phase-3 `MarketSnapshot` assembly. One snapshot per
1351
+ * application, single `category`, plus the registries the spec slice
1352
+ * carries today: ICPs, personas, jobs, pains, gains, tones of voice,
1353
+ * benefits, positionings, channels, alternatives, triggers, buying
1354
+ * journeys, proofs, objections, and the Phase-4 message templates
1355
+ * (mechanism-only seed pair — see `messaging/templates.ts`).
1356
+ *
1357
+ * `version: MarketSnapshotVersion.V2` is intentional — V2 means the
1358
+ * Phase-3 surface (Phase-1 + Phase-2 + the 6 graduated families).
1359
+ *
1360
+ * **Validation surface.** The snapshot is consumed by the dev
1361
+ * companion subprocess (Phase-4 market-context behaviors and the
1362
+ * Phase-4.2 market-generation CLI). `validateMarketSnapshot` runs at
1363
+ * the companion's snapshot resolver entry point (see
1364
+ * `resolveMarketSnapshot` in
1365
+ * `companion-introspection-behavior-handlers.ts`) the first time the
1366
+ * snapshot is touched per process: ERROR-severity issues throw a
1367
+ * structured error listing every issue and the behavior call fails;
1368
+ * WARN-severity issues are logged once via `console.warn`. The
1369
+ * backend container does not consume `marketSpecification` at runtime
1370
+ * today — market authoring is a companion-side concern (D15 / §10).
1371
+ */
1372
+ export const applicationMarketSnapshot: MarketSnapshot = {
1373
+ version: MarketSnapshotVersion.V2,
1374
+ category: applicationCategory,
1375
+ icps: applicationIcps,
1376
+ personas: applicationPersonas,
1377
+ jobs: applicationJobs,
1378
+ pains: applicationPains,
1379
+ gains: applicationGains,
1380
+ tonesOfVoice: applicationTonesOfVoice,
1381
+ benefits: applicationBenefits,
1382
+ positionings: applicationPositionings,
1383
+ channels: applicationChannels,
1384
+ alternatives: applicationAlternatives,
1385
+ triggers: applicationTriggers,
1386
+ buyingJourneys: applicationBuyingJourneys,
1387
+ proofs: applicationProofs,
1388
+ objections: applicationObjections,
1389
+ messageTemplates: applicationMessageTemplates,
1390
+ };
1391
+ ```
1392
+
1393
+ **Downstream consumer** — the `MarketMessageTemplate[]` the CLI
1394
+ pairs with the rendered block (placeholders here must satisfy the
1395
+ `MESSAGE_TEMPLATE_PLACEHOLDER_MISMATCH` validator against
1396
+ the block's contents):
1397
+
1398
+
1399
+ ## Usage Example
1400
+
1401
+ ```typescript
1402
+ *
1403
+ * Minimal application-owned message-template examples. They demonstrate how
1404
+ * a structured market fact set constrains an LLM request without pretending
1405
+ * that generated copy is already approved for publication. The examples:
1406
+ *
1407
+ * 1. Exercise the `MESSAGE_TEMPLATE_PLACEHOLDER_MISMATCH` validation rule.
1408
+ * 2. Provide one ICP-scoped landing-page template and one objection-response
1409
+ * email template for an application-managed generation workflow.
1410
+ * 3. Demonstrate the `{{output_language}}` runtime input: it is supplied by
1411
+ * the invocation context, not duplicated in `requiredInputs`.
1412
+ *
1413
+ * Recognised placeholder shapes (kept in sync with
1414
+ * `MarketMessageRequiredInput` ↔ `PLACEHOLDER_ENTITY_TO_REQUIRED_INPUT`
1415
+ * in the validated market snapshot):
1416
+ *
1417
+ * - `{{icp.name}}`, `{{icp.profile.geographies}}`, `{{icpRef}}`
1418
+ * → declares `MarketMessageRequiredInput.ICP_REF`.
1419
+ * - `{{benefit.claim}}`, `{{benefitRef}}`
1420
+ * → declares `MarketMessageRequiredInput.BENEFIT_REF`.
1421
+ * - `{{objection.claim}}`, `{{objectionRef}}`
1422
+ * → declares `MarketMessageRequiredInput.OBJECTION_REF`.
1423
+ * - `{{output_language}}` is invocation-supplied — never declared.
1424
+ */
1425
+
1426
+ /**
1427
+ * ICP-scoped landing-page hero. Consumed by the market-generation workflow to
1428
+ * render a per-ICP landing-page hero:
1429
+ * the LLM receives the `icp` and one in-scope `benefit`, plus the
1430
+ * ICP's `preferredVoiceRef`-resolved tone of voice context block.
1431
+ */
1432
+ export const tmplLandingIcpHero: MarketMessageTemplateConfig = {
1433
+ ref: 'tmpl-landing-icp-hero',
1434
+ name: 'Landing — ICP hero block',
1435
+ description:
1436
+ 'Single-paragraph hero for an ICP-scoped landing page, anchored on one '
1437
+ + 'in-scope benefit. Output is rendered in {{output_language}} by the '
1438
+ + 'market-generation CLI (--output-language flag).',
1439
+ outputKind: MarketMessageOutputKind.LANDING_PAGE,
1440
+ promptTemplate:
1441
+ 'Write a single hero paragraph (maximum 60 words) for the '
1442
+ + '{{icp.name}} landing page. Anchor the paragraph on the benefit '
1443
+ + '"{{benefit.claim}}" and lead with the outcome the ICP recognises '
1444
+ + 'from their own week, not from a feature list. Address the reader '
1445
+ + 'directly. Produce the output in {{output_language}}.',
1446
+ requiredInputs: [
1447
+ MarketMessageRequiredInput.ICP_REF,
1448
+ MarketMessageRequiredInput.BENEFIT_REF,
1449
+ ],
1450
+ preferredVoiceRef: 'voice-trusted-engineer',
1451
+ authored: {
1452
+ lastAuthoredAt: '2026-04-17T00:00:00Z',
1453
+ confidence: AuthoredConfidence.MEDIUM,
1454
+ reviewer: 'your-app@wildo.ai',
1455
+ notes:
1456
+ 'Phase-4.1 mechanism seed. Realistic per-ICP variants (indie-maker, '
1457
+ + 'small-team) land in Phase 4.2 once the CLI is wired.',
1458
+ },
1459
+ };
1460
+
1461
+ /**
1462
+ * Objection-response email. Consumed by the market-generation workflow to
1463
+ * draft a 1:1 sales / customer-success reply when a known objection is raised
1464
+ * — pairs the `objection` with the strongest related `benefit` and
1465
+ * the `icp` of the contact.
1466
+ */
1467
+ export const tmplObjectionResponseEmail: MarketMessageTemplateConfig = {
1468
+ ref: 'tmpl-objection-response-email',
1469
+ name: 'Email — objection response',
1470
+ description:
1471
+ 'Short reply email (≤120 words) addressing one named objection for an '
1472
+ + 'ICP, citing one related benefit. Output is rendered in '
1473
+ + '{{output_language}}.',
1474
+ outputKind: MarketMessageOutputKind.OBJECTION_RESPONSE,
1475
+ promptTemplate:
1476
+ 'Draft a reply email (≤120 words) for a {{icp.name}} contact who raised '
1477
+ + 'the objection "{{objection.claim}}". Acknowledge the concern in one '
1478
+ + 'sentence, then ground the response in the benefit '
1479
+ + '"{{benefit.claim}}". Close with one specific next action that does '
1480
+ + 'not require a demo. Produce the output in {{output_language}}.',
1481
+ requiredInputs: [
1482
+ MarketMessageRequiredInput.ICP_REF,
1483
+ MarketMessageRequiredInput.BENEFIT_REF,
1484
+ MarketMessageRequiredInput.OBJECTION_REF,
1485
+ ],
1486
+ preferredVoiceRef: 'voice-trusted-engineer',
1487
+ authored: {
1488
+ lastAuthoredAt: '2026-04-17T00:00:00Z',
1489
+ confidence: AuthoredConfidence.MEDIUM,
1490
+ reviewer: 'your-app@wildo.ai',
1491
+ notes:
1492
+ 'Phase-4.1 mechanism seed. Coverage by objection family expands in '
1493
+ + 'Phase 4.2 (per-objection variants) once the market-generation CLI ships.',
1494
+ },
1495
+ };
1496
+
1497
+ export const applicationMessageTemplates: MarketMessageTemplateConfig[] = [
1498
+ tmplLandingIcpHero,
1499
+ tmplObjectionResponseEmail,
1500
+ ];
1501
+ ```
1502
+
1503
+ To see the *actual* rendered block during development, run the CLI
1504
+ in `--explain` mode against any of the seed templates above —
1505
+ stdout shows the exact markdown block your prompt will receive.
1506
+ Promote to a single Tier A `example.market.context-block.rendered`
1507
+ anchor once the per-behavior block shape locks (tracked in the
1508
+ `market.context-block.builder` source-`REFERENCE` evolution).
1509
+
1510
+ ## Validator coupling
1511
+
1512
+ Templates paired with the rendered block are policed by
1513
+ `MESSAGE_TEMPLATE_PLACEHOLDER_MISMATCH` (validator §10.3 / 18th
1514
+ issue kind). Make sure the `MarketMessageTemplate` the CLI pairs
1515
+ with the block declares matching `requiredInputs[]` for every
1516
+ non-exempt placeholder it consumes — see
1517
+ `market-message-templates-authoring`.
1518
+
1519
+ ## Import Origins
1520
+
1521
+ - `@wildo-ai/saas-specifications`
1522
+
1523
+ ## Source Excerpts
1524
+
1525
+ ### Origin Package: `@wildo-ai/saas-specifications`
1526
+
1527
+ ```typescript
1528
+ *
1529
+ * Authoring-consistency validator for an assembled `MarketSnapshot`.
1530
+ *
1531
+ * The function is a **pure**, **typed** graph walker over the
1532
+ * snapshot — no Zod introspection, no LocalizedString visitor, no
1533
+ * runtime registry access. Each rule is implemented as a tiny
1534
+ * standalone detector composed by the top-level
1535
+ * `validateMarketSnapshot`.
1536
+ *
1537
+ * Rule table — currently 18 kinds:
1538
+ *
1539
+ * | Kind | Severity | Trigger |
1540
+ * |--------------------------------------------|------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
1541
+ * | `ORPHAN_REF` | ERROR | A `<entity>Ref` does not resolve inside the snapshot. Cross-family refs (`featureRefs`, `productRefs`) are skipped if no set is passed. |
1542
+ * | `MULTIPLE_THRESHOLDS_PER_ICP_JOB` | ERROR | An (icpRef, jobRef) cluster has more than one distinct benefit with `kanoCategory: THRESHOLD`. Deduped by benefit `ref`. |
1543
+ * | `THRESHOLD_BENEFIT_WITHOUT_JOB` | ERROR | A benefit declares any `kanoCategory: THRESHOLD` entry but `advances[]` is empty (no job to anchor the THRESHOLD claim against). |
1544
+ * | `EMPTY_BENEFIT_DELIVERED_BY` | ERROR | A `FeatureBenefit.deliveredByFeatureRefs[]` is empty (defence in depth — Zod also rejects). |
1545
+ * | `ICP_WITHOUT_PERSONA` | ERROR (LEGAL_ENTITY) / WARN (INDIVIDUAL) | A non-`ANTI_TARGET` ICP has no persona pointing at its `ref` via `belongsToIcpRefs`. |
1546
+ * | `INFLUENCE_CYCLE` | ERROR (self-loop) / WARN (multi-node) | Cycle in the ICP→ICP influence graph. Self-loops are always ERROR; non-trivial cycles are WARN (real GTM dynamics may include them). |
1547
+ * | `MISSING_POSITIONING_FOR_ICP` | ERROR | An ICP of priority `CORE` or `EXPANSION` has no `MarketPositioning`. Other priorities exempt. |
1548
+ * | `STALE_AUTHORED` | WARN | `lastAuthoredAt + reviewCadence < now`. No check when `reviewCadence` is undefined or `AS_NEEDED`. |
1549
+ * | `DUPLICATE_EDGE_PER_ENTITY` | WARN | Same target ref appears twice in the same edge list. Covers ICP/persona `pains/gains/jobs` (by edge ref) and benefit `importanceByICP` (by `icpRef`). |
1550
+ * | `INVALID_ANTI_TARGET_PURPOSE_MIX` | ERROR | `priority === ANTI_TARGET` and `purposeMix !== { adoption: 0, revenue: 0 }`. |
1551
+ * | `BUYING_GROUP_PERSONA_MISSING_DMU_ROLE` | ERROR | `personaScope === BUYING_GROUP_MEMBER` and `dmuRole` is undefined. |
1552
+ * | `BUYING_GROUP_BACKLINK_MISSING` | ERROR | An ICP's `buyingGroup[].personaRef` resolves to a persona whose `belongsToIcpRefs[]` does NOT include the ICP (asymmetric link). |
1553
+ * | `PROOF_WITHOUT_SUPPORT` | WARN | A `MarketProof` carries empty `supportsBenefitRefs[]` AND empty `supportsIcpRefs[]`. |
1554
+ * | `PROOF_KIND_PAYLOAD_MISMATCH` | WARN | A `MarketProof` carries a payload incoherent with its `proofKind` (`METRIC` without `metric`, `LOGO` with `metric`). |
1555
+ * | `DUPLICATE_JOURNEY_STAGE` | ERROR | A `MarketBuyingJourney` lists the same `BuyingJourneyStage` enum value more than once. |
1556
+ * | `DUPLICATE_BUYING_JOURNEY_FOR_ICP` | ERROR | Two `MarketBuyingJourney` entries point at the same `icpRef`. The model is "one journey per ICP". |
1557
+ * | `OBJECTION_PROOF_BENEFIT_MISMATCH` | WARN | An objection cites `proofRefs[]` whose union of `supportsBenefitRefs[]` ∪ `supportsIcpRefs[]` does not intersect `relatedBenefitRefs[]` ∪ `raisedByIcpRefs[]`. |
1558
+ * | `MESSAGE_TEMPLATE_PLACEHOLDER_MISMATCH` | WARN | A `MarketMessageTemplate` declares a `requiredInputs[]` entry that no `{{<entity>.*}}` / `{{<entity>Ref}}` placeholder consumes — or vice-versa. `{{output_language}}` is exempt (CLI-injected at render time). |
1559
+ *
1560
+ * Issue ordering inside `result.issues[]` is detector-order, then
1561
+ * snapshot-walk order. It is **not** a stable contract — callers
1562
+ * must group/sort by `kind` + `severity` themselves.
1563
+ *
1564
+ * Loaded by application registries at boot. Callers should:
1565
+ * - throw a `BusinessConfigError` (re-exported from
1566
+ * `@wildo-ai/saas-backend-lib`) when `result.ok === false`,
1567
+ * listing every ERROR-severity issue;
1568
+ * - log WARN-severity issues through the standard backend logger.
1569
+ *
1570
+ * The validator never mutates the snapshot.
1571
+ */
1572
+ export enum MarketSnapshotIssueKind {
1573
+ ORPHAN_REF = 'ORPHAN_REF',
1574
+ MULTIPLE_THRESHOLDS_PER_ICP_JOB = 'MULTIPLE_THRESHOLDS_PER_ICP_JOB',
1575
+ /**
1576
+ * A benefit declares any `kanoCategory: THRESHOLD` entry on
1577
+ * `importanceByICP[]` but its `advances[]` is empty. THRESHOLD is
1578
+ * defined as "table-stakes for a specific (icp, job)" — without a
1579
+ * job to anchor against, the THRESHOLD claim has no semantic
1580
+ * cluster and the `MULTIPLE_THRESHOLDS_PER_ICP_JOB` invariant is
1581
+ * structurally bypassed (ERROR).
1582
+ */
1583
+ THRESHOLD_BENEFIT_WITHOUT_JOB = 'THRESHOLD_BENEFIT_WITHOUT_JOB',
1584
+ EMPTY_BENEFIT_DELIVERED_BY = 'EMPTY_BENEFIT_DELIVERED_BY',
1585
+ ICP_WITHOUT_PERSONA = 'ICP_WITHOUT_PERSONA',
1586
+ INFLUENCE_CYCLE = 'INFLUENCE_CYCLE',
1587
+ MISSING_POSITIONING_FOR_ICP = 'MISSING_POSITIONING_FOR_ICP',
1588
+ STALE_AUTHORED = 'STALE_AUTHORED',
1589
+ /**
1590
+ * Same target ref appears more than once in the same per-entity
1591
+ * edge list. Currently covers:
1592
+ * - ICP and persona `pains[].painRef`, `gains[].gainRef`,
1593
+ * `jobs[].jobRef` — typically the result of an `inheritFrom()`
1594
+ * spread followed by a forgotten `.filter()` step;
1595
+ * - benefit `importanceByICP[].icpRef` — duplicate (benefit, icp)
1596
+ * pairs make per-ICP scoring non-deterministic.
1597
+ *
1598
+ * Severity is WARN — the snapshot still parses, but the duplicate
1599
+ * edge silently double-counts in downstream FIT scoring.
1600
+ */
1601
+ DUPLICATE_EDGE_PER_ENTITY = 'DUPLICATE_EDGE_PER_ENTITY',
1602
+ INVALID_ANTI_TARGET_PURPOSE_MIX = 'INVALID_ANTI_TARGET_PURPOSE_MIX',
1603
+ BUYING_GROUP_PERSONA_MISSING_DMU_ROLE = 'BUYING_GROUP_PERSONA_MISSING_DMU_ROLE',
1604
+ /**
1605
+ * An ICP's `buyingGroup[].personaRef` resolves to a persona, but
1606
+ * the persona's `belongsToIcpRefs[]` does not contain the ICP. The
1607
+ * link is asymmetric and downstream consumers (DMU rendering,
1608
+ * persona-by-ICP indexing) silently drop the persona. ERROR.
1609
+ */
1610
+ BUYING_GROUP_BACKLINK_MISSING = 'BUYING_GROUP_BACKLINK_MISSING',
1611
+ /** A proof entity that supports neither a benefit nor an ICP — has no place to land in copy (WARN). */
1612
+ PROOF_WITHOUT_SUPPORT = 'PROOF_WITHOUT_SUPPORT',
1613
+ /**
1614
+ * A `MarketProof` carries a payload incoherent with its
1615
+ * `proofKind`. The schema is permissive (both `attribution` and
1616
+ * `metric` are optional on every kind). This detector catches the
1617
+ * strongest mismatches as authoring drift (WARN — the spec parses,
1618
+ * but the proof renders badly):
1619
+ * - `METRIC` without a `metric` block;
1620
+ * - `LOGO` with a `metric` block.
1621
+ */
1622
+ PROOF_KIND_PAYLOAD_MISMATCH = 'PROOF_KIND_PAYLOAD_MISMATCH',
1623
+ /** Same `BuyingJourneyStage` enum value listed twice on a single journey (ERROR). */
1624
+ DUPLICATE_JOURNEY_STAGE = 'DUPLICATE_JOURNEY_STAGE',
1625
+ /** Two `MarketBuyingJourney` entries point at the same `icpRef`. The model is one journey per ICP (ERROR). */
1626
+ DUPLICATE_BUYING_JOURNEY_FOR_ICP = 'DUPLICATE_BUYING_JOURNEY_FOR_ICP',
1627
+ /** Objection's cited proofs do not back any of its `relatedBenefitRefs` or `raisedByIcpRefs` (WARN). */
1628
+ OBJECTION_PROOF_BENEFIT_MISMATCH = 'OBJECTION_PROOF_BENEFIT_MISMATCH',
1629
+ /**
1630
+ * A `MarketMessageTemplate` has a mismatch between its declared
1631
+ * `requiredInputs[]` and the `{{<entity>.*}}` / `{{<entity>Ref}}`
1632
+ * placeholders that actually appear inside `promptTemplate`.
1633
+ *
1634
+ * Two symmetric cases:
1635
+ * 1. Declared but unused — `requiredInputs` lists `icpRef` but the
1636
+ * body has no `{{icp.*}}` / `{{icpRef}}` reference. The CLI will
1637
+ * require the caller to pass the input but never substitute it.
1638
+ * 2. Used but undeclared — the body references `{{benefit.claim}}`
1639
+ * but `requiredInputs` does not include `benefitRef`. The CLI
1640
+ * will not enforce the input and the placeholder will render
1641
+ * literally (e.g. `{{benefit.claim}}`).
1642
+ *
1643
+ * The `{{output_language}}` placeholder is **exempt** from this
1644
+ * check: it is injected by the market generation CLI from the
1645
+ * `--output-language` flag, not from `requiredInputs[]`.
1646
+ *
1647
+ * WARN severity — the snapshot still parses and the template still
1648
+ * renders, but the output will be off-spec at runtime. Authors
1649
+ * should either prune the unused entry from `requiredInputs[]` or
1650
+ * add the missing placeholder / entry.
1651
+ */
1652
+ MESSAGE_TEMPLATE_PLACEHOLDER_MISMATCH = 'MESSAGE_TEMPLATE_PLACEHOLDER_MISMATCH',
1653
+ }
1654
+
1655
+ export type MarketSnapshotIssueSeverity = 'ERROR' | 'WARN';
1656
+
1657
+ export interface MarketSnapshotIssue {
1658
+ kind: MarketSnapshotIssueKind;
1659
+ /** Dotted path inside the snapshot (e.g. `'icps[0].pains[2].painRef'`). */
1660
+ path: string;
1661
+ message: string;
1662
+ severity: MarketSnapshotIssueSeverity;
1663
+ }
1664
+
1665
+ export interface MarketSnapshotValidationResult {
1666
+ /** `true` iff no issue has severity `ERROR`. */
1667
+ ok: boolean;
1668
+ issues: MarketSnapshotIssue[];
1669
+ }
1670
+
1671
+ export interface ValidateMarketSnapshotOptions {
1672
+ /**
1673
+ * Cross-family ref check for `FeatureBenefit.deliveredByFeatureRefs`.
1674
+ * Pass the application's full feature-spec key set; orphans are
1675
+ * reported as `ORPHAN_REF`. When omitted, the cross-family check is
1676
+ * SKIPPED (intra-snapshot orphans are still detected).
1677
+ */
1678
+ availableFeatureRefs?: ReadonlySet<string>;
1679
+ /**
1680
+ * Cross-family ref check for `MarketICP.recommendedProductRefs` /
1681
+ * `upsellPathProductRefs`. Same skip-when-omitted semantics.
1682
+ */
1683
+ availableProductRefs?: ReadonlySet<string>;
1684
+ /** Override "now" for `STALE_AUTHORED` checks (test affordance). Defaults to `new Date()`. */
1685
+ now?: Date;
1686
+ }
1687
+
1688
+ export function validateMarketSnapshot(
1689
+ snapshot: MarketSnapshot,
1690
+ options?: ValidateMarketSnapshotOptions,
1691
+ ): MarketSnapshotValidationResult {
1692
+ const issues: MarketSnapshotIssue[] = [];
1693
+
1694
+ detectOrphanRefs(snapshot, options, issues);
1695
+ detectThresholdBenefitsWithoutJob(snapshot, issues);
1696
+ detectMultipleThresholdsPerIcpJob(snapshot, issues);
1697
+ detectEmptyBenefitDeliveredBy(snapshot, issues);
1698
+ detectIcpWithoutPersona(snapshot, issues);
1699
+ detectInfluenceCycles(snapshot, issues);
1700
+ detectMissingPositioningForIcp(snapshot, issues);
1701
+ detectStaleAuthored(snapshot, options?.now ?? new Date(), issues);
1702
+ detectDuplicateEdgesPerEntity(snapshot, issues);
1703
+ detectInvalidAntiTargetPurposeMix(snapshot, issues);
1704
+ detectBuyingGroupPersonasMissingDmuRole(snapshot, issues);
1705
+ detectBuyingGroupBacklinkMissing(snapshot, issues);
1706
+ detectProofsWithoutSupport(snapshot, issues);
1707
+ detectProofKindPayloadMismatch(snapshot, issues);
1708
+ detectDuplicateJourneyStages(snapshot, issues);
1709
+ detectDuplicateBuyingJourneyForIcp(snapshot, issues);
1710
+ detectObjectionProofBenefitMismatch(snapshot, issues);
1711
+ detectMessageTemplatePlaceholderMismatch(snapshot, issues);
1712
+
1713
+ const ok = issues.every(i => i.severity !== 'ERROR');
1714
+ return { ok, issues };
1715
+ }
1716
+
1717
+ // ────────────────────────────────────────────────────────────────────
1718
+ // Detectors — one per rule, kept small and independently testable.
1719
+ // ────────────────────────────────────────────────────────────────────
1720
+
1721
+ function detectOrphanRefs(
1722
+ snapshot: MarketSnapshot,
1723
+ options: ValidateMarketSnapshotOptions | undefined,
1724
+ issues: MarketSnapshotIssue[],
1725
+ ): void {
1726
+ const icpRefs = new Set(snapshot.icps.map(i => i.ref));
1727
+ const personaRefs = new Set(snapshot.personas.map(p => p.ref));
1728
+ const jobRefs = new Set(snapshot.jobs.map(j => j.ref));
1729
+ const painRefs = new Set(snapshot.pains.map(p => p.ref));
1730
+ const gainRefs = new Set(snapshot.gains.map(g => g.ref));
1731
+ const voiceRefs = new Set(snapshot.tonesOfVoice.map(v => v.ref));
1732
+ const benefitRefs = new Set(snapshot.benefits.map(b => b.ref));
1733
+ const channelRefs = new Set(snapshot.channels.map(c => c.ref));
1734
+ const alternativeRefs = new Set(snapshot.alternatives.map(a => a.ref));
1735
+ const triggerRefs = new Set(snapshot.triggers.map(t => t.ref));
1736
+ const proofRefs = new Set(snapshot.proofs.map(p => p.ref));
1737
+ const objectionRefs = new Set(snapshot.objections.map(o => o.ref));
1738
+
1739
+ const reportOrphan = (path: string, ref: string, kind: string): void => {
1740
+ issues.push({
1741
+ kind: MarketSnapshotIssueKind.ORPHAN_REF,
1742
+ path,
1743
+ message: `${kind} ref "${ref}" at ${path} does not resolve inside the snapshot.`,
1744
+ severity: 'ERROR',
1745
+ });
1746
+ };
1747
+
1748
+ // ICP edges + cross-family + influences + voices + Phase-3 ref arrays.
1749
+ for (const [iIdx, icp] of snapshot.icps.entries()) {
1750
+ const basePath = `icps[${iIdx}]`;
1751
+
1752
+ icp.buyingGroup.forEach((entry, idx) => {
1753
+ if (!personaRefs.has(entry.personaRef)) {
1754
+ reportOrphan(`${basePath}.buyingGroup[${idx}].personaRef`, entry.personaRef, 'persona');
1755
+ }
1756
+ });
1757
+ icp.jobs.forEach((edge, idx) => {
1758
+ if (!jobRefs.has(edge.jobRef)) reportOrphan(`${basePath}.jobs[${idx}].jobRef`, edge.jobRef, 'job');
1759
+ });
1760
+ icp.pains.forEach((edge, idx) => {
1761
+ if (!painRefs.has(edge.painRef)) reportOrphan(`${basePath}.pains[${idx}].painRef`, edge.painRef, 'pain');
1762
+ });
1763
+ icp.gains.forEach((edge, idx) => {
1764
+ if (!gainRefs.has(edge.gainRef)) reportOrphan(`${basePath}.gains[${idx}].gainRef`, edge.gainRef, 'gain');
1765
+ });
1766
+ icp.influences.forEach((edge, idx) => {
1767
+ if (!icpRefs.has(edge.icpRef)) reportOrphan(`${basePath}.influences[${idx}].icpRef`, edge.icpRef, 'icp');
1768
+ });
1769
+ if (icp.preferredVoiceRef !== undefined && !voiceRefs.has(icp.preferredVoiceRef)) {
1770
+ reportOrphan(`${basePath}.preferredVoiceRef`, icp.preferredVoiceRef, 'voice');
1771
+ }
1772
+
1773
+ // Phase-3 ICP ref arrays (channels / triggers / alternatives /
1774
+ // proofs / objections). All are intra-snapshot — no caller-supplied
1775
+ // set required. Orphans here silently waste downstream targeting
1776
+ // (channel never reached, trigger never observed) so ERROR is the
1777
+ // right severity (D16).
1778
+ icp.channelRefs.forEach((ref, idx) => {
1779
+ if (!channelRefs.has(ref)) reportOrphan(`${basePath}.channelRefs[${idx}]`, ref, 'channel');
1780
+ });
1781
+ icp.triggerRefs.forEach((ref, idx) => {
1782
+ if (!triggerRefs.has(ref)) reportOrphan(`${basePath}.triggerRefs[${idx}]`, ref, 'trigger');
1783
+ });
1784
+ icp.alternativeRefs.forEach((ref, idx) => {
1785
+ if (!alternativeRefs.has(ref)) reportOrphan(`${basePath}.alternativeRefs[${idx}]`, ref, 'alternative');
1786
+ });
1787
+ icp.proofRefs.forEach((ref, idx) => {
1788
+ if (!proofRefs.has(ref)) reportOrphan(`${basePath}.proofRefs[${idx}]`, ref, 'proof');
1789
+ });
1790
+ icp.objectionRefs.forEach((ref, idx) => {
1791
+ if (!objectionRefs.has(ref)) reportOrphan(`${basePath}.objectionRefs[${idx}]`, ref, 'objection');
1792
+ });
1793
+
1794
+ if (options?.availableProductRefs !== undefined) {
1795
+ icp.recommendedProductRefs.forEach((ref, idx) => {
1796
+ if (!options.availableProductRefs!.has(ref)) {
1797
+ reportOrphan(`${basePath}.recommendedProductRefs[${idx}]`, ref, 'product');
1798
+ }
1799
+ });
1800
+ icp.upsellPathProductRefs.forEach((ref, idx) => {
1801
+ if (!options.availableProductRefs!.has(ref)) {
1802
+ reportOrphan(`${basePath}.upsellPathProductRefs[${idx}]`, ref, 'product');
1803
+ }
1804
+ });
1805
+ }
1806
+ }
1807
+
1808
+ // Persona edges + cross-family voice ref + parent ICP refs + Phase-3
1809
+ // channel refs.
1810
+ for (const [pIdx, persona] of snapshot.personas.entries()) {
1811
+ const basePath = `personas[${pIdx}]`;
1812
+
1813
+ persona.belongsToIcpRefs.forEach((ref, idx) => {
1814
+ if (!icpRefs.has(ref)) reportOrphan(`${basePath}.belongsToIcpRefs[${idx}]`, ref, 'icp');
1815
+ });
1816
+ persona.jobs.forEach((edge, idx) => {
1817
+ if (!jobRefs.has(edge.jobRef)) reportOrphan(`${basePath}.jobs[${idx}].jobRef`, edge.jobRef, 'job');
1818
+ });
1819
+ persona.pains.forEach((edge, idx) => {
1820
+ if (!painRefs.has(edge.painRef)) reportOrphan(`${basePath}.pains[${idx}].painRef`, edge.painRef, 'pain');
1821
+ });
1822
+ persona.gains.forEach((edge, idx) => {
1823
+ if (!gainRefs.has(edge.gainRef)) reportOrphan(`${basePath}.gains[${idx}].gainRef`, edge.gainRef, 'gain');
1824
+ });
1825
+ persona.channelRefs.forEach((ref, idx) => {
1826
+ if (!channelRefs.has(ref)) reportOrphan(`${basePath}.channelRefs[${idx}]`, ref, 'channel');
1827
+ });
1828
+ if (persona.preferredVoiceRef !== undefined && !voiceRefs.has(persona.preferredVoiceRef)) {
1829
+ reportOrphan(`${basePath}.preferredVoiceRef`, persona.preferredVoiceRef, 'voice');
1830
+ }
1831
+ }
1832
+
1833
+ // Benefits — pain/gain/job + ICP refs + cross-family feature refs +
1834
+ // Phase-3 proof / objection back-refs.
1835
+ for (const [bIdx, benefit] of snapshot.benefits.entries()) {
1836
+ const basePath = `benefits[${bIdx}]`;
1837
+
1838
+ benefit.relieves.forEach((edge, idx) => {
1839
+ if (!painRefs.has(edge.painRef)) {
1840
+ reportOrphan(`${basePath}.relieves[${idx}].painRef`, edge.painRef, 'pain');
1841
+ }
1842
+ });
1843
+ benefit.creates.forEach((edge, idx) => {
1844
+ if (!gainRefs.has(edge.gainRef)) {
1845
+ reportOrphan(`${basePath}.creates[${idx}].gainRef`, edge.gainRef, 'gain');
1846
+ }
1847
+ });
1848
+ benefit.advances.forEach((edge, idx) => {
1849
+ if (!jobRefs.has(edge.jobRef)) {
1850
+ reportOrphan(`${basePath}.advances[${idx}].jobRef`, edge.jobRef, 'job');
1851
+ }
1852
+ });
1853
+ benefit.importanceByICP.forEach((edge, idx) => {
1854
+ if (!icpRefs.has(edge.icpRef)) {
1855
+ reportOrphan(`${basePath}.importanceByICP[${idx}].icpRef`, edge.icpRef, 'icp');
1856
+ }
1857
+ });
1858
+ benefit.proofRefs.forEach((ref, idx) => {
1859
+ if (!proofRefs.has(ref)) reportOrphan(`${basePath}.proofRefs[${idx}]`, ref, 'proof');
1860
+ });
1861
+ benefit.addressesObjectionRefs.forEach((ref, idx) => {
1862
+ if (!objectionRefs.has(ref)) {
1863
+ reportOrphan(`${basePath}.addressesObjectionRefs[${idx}]`, ref, 'objection');
1864
+ }
1865
+ });
1866
+
1867
+ if (options?.availableFeatureRefs !== undefined) {
1868
+ benefit.deliveredByFeatureRefs.forEach((ref, idx) => {
1869
+ if (!options.availableFeatureRefs!.has(ref)) {
1870
+ reportOrphan(`${basePath}.deliveredByFeatureRefs[${idx}]`, ref, 'feature');
1871
+ }
1872
+ });
1873
+ }
1874
+ }
1875
+
1876
+ // Positionings — back to ICP + benefits + alternatives.
1877
+ for (const [pIdx, positioning] of snapshot.positionings.entries()) {
1878
+ const basePath = `positionings[${pIdx}]`;
1879
+
1880
+ if (!icpRefs.has(positioning.icpRef)) {
1881
+ reportOrphan(`${basePath}.icpRef`, positioning.icpRef, 'icp');
1882
+ }
1883
+ if (positioning.preferredVoiceRef !== undefined && !voiceRefs.has(positioning.preferredVoiceRef)) {
1884
+ reportOrphan(`${basePath}.preferredVoiceRef`, positioning.preferredVoiceRef, 'voice');
1885
+ }
1886
+ positioning.valuePillars.forEach((pillar, idx) => {
1887
+ pillar.backedByBenefitRefs.forEach((ref, j) => {
1888
+ if (!benefitRefs.has(ref)) {
1889
+ reportOrphan(`${basePath}.valuePillars[${idx}].backedByBenefitRefs[${j}]`, ref, 'benefit');
1890
+ }
1891
+ });
1892
+ });
1893
+ positioning.alternativesContrasted.forEach((entry, idx) => {
1894
+ if (!alternativeRefs.has(entry.alternativeRef)) {
1895
+ reportOrphan(
1896
+ `${basePath}.alternativesContrasted[${idx}].alternativeRef`,
1897
+ entry.alternativeRef,
1898
+ 'alternative',
1899
+ );
1900
+ }
1901
+ });
1902
+ }
1903
+
1904
+ // Triggers — affected ICPs + recommended channels.
1905
+ for (const [tIdx, trigger] of snapshot.triggers.entries()) {
1906
+ const basePath = `triggers[${tIdx}]`;
1907
+ trigger.affectedIcpRefs.forEach((ref, idx) => {
1908
+ if (!icpRefs.has(ref)) reportOrphan(`${basePath}.affectedIcpRefs[${idx}]`, ref, 'icp');
1909
+ });
1910
+ trigger.recommendedChannelRefs.forEach((ref, idx) => {
1911
+ if (!channelRefs.has(ref)) reportOrphan(`${basePath}.recommendedChannelRefs[${idx}]`, ref, 'channel');
1912
+ });
1913
+ }
1914
+
1915
+ // Buying journeys — back to ICP.
1916
+ for (const [jIdx, journey] of snapshot.buyingJourneys.entries()) {
1917
+ const basePath = `buyingJourneys[${jIdx}]`;
1918
+ if (!icpRefs.has(journey.icpRef)) {
1919
+ reportOrphan(`${basePath}.icpRef`, journey.icpRef, 'icp');
1920
+ }
1921
+ }
1922
+
1923
+ // Proofs — supports benefits + ICPs.
1924
+ for (const [pIdx, proof] of snapshot.proofs.entries()) {
1925
+ const basePath = `proofs[${pIdx}]`;
1926
+ proof.supportsBenefitRefs.forEach((ref, idx) => {
1927
+ if (!benefitRefs.has(ref)) reportOrphan(`${basePath}.supportsBenefitRefs[${idx}]`, ref, 'benefit');
1928
+ });
1929
+ proof.supportsIcpRefs.forEach((ref, idx) => {
1930
+ if (!icpRefs.has(ref)) reportOrphan(`${basePath}.supportsIcpRefs[${idx}]`, ref, 'icp');
1931
+ });
1932
+ }
1933
+
1934
+ // Objections — raised by ICPs + personas, cite proofs + related benefits.
1935
+ for (const [oIdx, objection] of snapshot.objections.entries()) {
1936
+ const basePath = `objections[${oIdx}]`;
1937
+ objection.raisedByIcpRefs.forEach((ref, idx) => {
1938
+ if (!icpRefs.has(ref)) reportOrphan(`${basePath}.raisedByIcpRefs[${idx}]`, ref, 'icp');
1939
+ });
1940
+ objection.raisedByPersonaRefs.forEach((ref, idx) => {
1941
+ if (!personaRefs.has(ref)) reportOrphan(`${basePath}.raisedByPersonaRefs[${idx}]`, ref, 'persona');
1942
+ });
1943
+ objection.proofRefs.forEach((ref, idx) => {
1944
+ if (!proofRefs.has(ref)) reportOrphan(`${basePath}.proofRefs[${idx}]`, ref, 'proof');
1945
+ });
1946
+ objection.relatedBenefitRefs.forEach((ref, idx) => {
1947
+ if (!benefitRefs.has(ref)) reportOrphan(`${basePath}.relatedBenefitRefs[${idx}]`, ref, 'benefit');
1948
+ });
1949
+ }
1950
+
1951
+ // Message templates — Phase-2 slot, Phase-4 fill. The preferred-voice
1952
+ // ref MUST resolve when authored, otherwise the market generation CLI
1953
+ // silently falls back to the default voice and produces off-brand
1954
+ // copy.
1955
+ for (const [tIdx, template] of snapshot.messageTemplates.entries()) {
1956
+ const basePath = `messageTemplates[${tIdx}]`;
1957
+ if (template.preferredVoiceRef !== undefined && !voiceRefs.has(template.preferredVoiceRef)) {
1958
+ reportOrphan(`${basePath}.preferredVoiceRef`, template.preferredVoiceRef, 'voice');
1959
+ }
1960
+ }
1961
+ }
1962
+
1963
+ /**
1964
+ * D4 invariant: at most ONE THRESHOLD-classified benefit per
1965
+ * `(icpRef, jobRef)` cluster. THRESHOLD means "table-stakes — without
1966
+ * it the offer is rejected", so two competing THRESHOLDs against the
1967
+ * same (icp, job) means we have two unrelated table-stakes claims for
1968
+ * the same outcome which is structurally undefined for the FIT scorer
1969
+ * (`market-scoring.ts`).
1970
+ *
1971
+ * The detector dedupes per benefit by tracking the SET of benefit
1972
+ * `ref`s per (icp, job) — repeated `advances[]` entries on the SAME
1973
+ * benefit (which is itself a `DUPLICATE_EDGE_PER_ENTITY` WARN) do not
1974
+ * double-count and therefore do not trigger a false-positive ERROR
1975
+ * here. Benefits with empty `advances[]` are caught by
1976
+ * `THRESHOLD_BENEFIT_WITHOUT_JOB` (ERROR) — they would otherwise
1977
+ * structurally bypass this rule by having no (icp, job) cluster to
1978
+ * be counted in.
1979
+ */
1980
+ function detectMultipleThresholdsPerIcpJob(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
1981
+ const benefitRefsByJobByIcp = new Map<string, Map<string, Set<string>>>();
1982
+
1983
+ for (const benefit of snapshot.benefits) {
1984
+ const icpRefsWithThreshold = new Set(
1985
+ benefit.importanceByICP
1986
+ .filter(e => e.kanoCategory === BenefitKanoCategory.THRESHOLD)
1987
+ .map(e => e.icpRef),
1988
+ );
1989
+ if (icpRefsWithThreshold.size === 0) continue;
1990
+
1991
+ const distinctJobRefs = new Set(benefit.advances.map(e => e.jobRef));
1992
+ if (distinctJobRefs.size === 0) continue; // caught by THRESHOLD_BENEFIT_WITHOUT_JOB
1993
+
1994
+ for (const icpRef of icpRefsWithThreshold) {
1995
+ const byJob = benefitRefsByJobByIcp.get(icpRef) ?? new Map<string, Set<string>>();
1996
+ for (const jobRef of distinctJobRefs) {
1997
+ const set = byJob.get(jobRef) ?? new Set<string>();
1998
+ set.add(benefit.ref);
1999
+ byJob.set(jobRef, set);
2000
+ }
2001
+ benefitRefsByJobByIcp.set(icpRef, byJob);
2002
+ }
2003
+ }
2004
+
2005
+ for (const [icpRef, byJob] of benefitRefsByJobByIcp.entries()) {
2006
+ for (const [jobRef, refsSet] of byJob.entries()) {
2007
+ if (refsSet.size > 1) {
2008
+ const refs = [...refsSet].join(', ');
2009
+ issues.push({
2010
+ kind: MarketSnapshotIssueKind.MULTIPLE_THRESHOLDS_PER_ICP_JOB,
2011
+ path: `benefits.importanceByICP[icp=${icpRef}].advances[job=${jobRef}]`,
2012
+ message: `ICP "${icpRef}" job "${jobRef}" has multiple THRESHOLD benefits (${refs}). Only one THRESHOLD per (icp, job) cluster is allowed.`,
2013
+ severity: 'ERROR',
2014
+ });
2015
+ }
2016
+ }
2017
+ }
2018
+ }
2019
+
2020
+ /**
2021
+ * Companion to `MULTIPLE_THRESHOLDS_PER_ICP_JOB`. THRESHOLD is defined
2022
+ * as a per-(ICP, job) classification — a benefit that declares any
2023
+ * `kanoCategory: THRESHOLD` entry on `importanceByICP[]` MUST also
2024
+ * advance at least one job, otherwise the invariant has no anchor and
2025
+ * the FIT scorer cannot place the table-stakes claim. ERROR.
2026
+ */
2027
+ function detectThresholdBenefitsWithoutJob(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
2028
+ for (const [bIdx, benefit] of snapshot.benefits.entries()) {
2029
+ const hasThreshold = benefit.importanceByICP.some(
2030
+ e => e.kanoCategory === BenefitKanoCategory.THRESHOLD,
2031
+ );
2032
+ if (!hasThreshold) continue;
2033
+ if (benefit.advances.length > 0) continue;
2034
+
2035
+ const thresholdIcpRefs = benefit.importanceByICP
2036
+ .filter(e => e.kanoCategory === BenefitKanoCategory.THRESHOLD)
2037
+ .map(e => e.icpRef)
2038
+ .join(', ');
2039
+ issues.push({
2040
+ kind: MarketSnapshotIssueKind.THRESHOLD_BENEFIT_WITHOUT_JOB,
2041
+ path: `benefits[${bIdx}].advances`,
2042
+ message: `Benefit "${benefit.ref}" is THRESHOLD for ICP(s) [${thresholdIcpRefs}] but advances[] is empty. THRESHOLD is a per-(icp, job) claim — add at least one BenefitAdvancesJob entry, or downgrade kanoCategory to PERFORMANCE/DELIGHTER.`,
2043
+ severity: 'ERROR',
2044
+ });
2045
+ }
2046
+ }
2047
+
2048
+ function detectEmptyBenefitDeliveredBy(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
2049
+ // The schema enforces `.min(1)`; this detector remains as a defence
2050
+ // in depth for callers that bypass parsing (legitimate scenario:
2051
+ // tests building snapshots with type-asserted fixtures).
2052
+ for (const [bIdx, benefit] of snapshot.benefits.entries()) {
2053
+ if (benefit.deliveredByFeatureRefs.length === 0) {
2054
+ issues.push({
2055
+ kind: MarketSnapshotIssueKind.EMPTY_BENEFIT_DELIVERED_BY,
2056
+ path: `benefits[${bIdx}].deliveredByFeatureRefs`,
2057
+ message: `Benefit "${benefit.ref}" has empty deliveredByFeatureRefs[]. A benefit must be delivered by at least one feature.`,
2058
+ severity: 'ERROR',
2059
+ });
2060
+ }
2061
+ }
2062
+ }
2063
+
2064
+ function detectIcpWithoutPersona(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
2065
+ const personaParents = new Set<string>();
2066
+ for (const persona of snapshot.personas) {
2067
+ for (const ref of persona.belongsToIcpRefs) personaParents.add(ref);
2068
+ }
2069
+
2070
+ for (const [iIdx, icp] of snapshot.icps.entries()) {
2071
+ if (icp.priority === ICPPriority.ANTI_TARGET) continue;
2072
+ if (personaParents.has(icp.ref)) continue;
2073
+
2074
+ const severity: MarketSnapshotIssueSeverity =
2075
+ icp.archetype === ICPArchetype.LEGAL_ENTITY ? 'ERROR' : 'WARN';
2076
+ issues.push({
2077
+ kind: MarketSnapshotIssueKind.ICP_WITHOUT_PERSONA,
2078
+ path: `icps[${iIdx}].ref`,
2079
+ message: `ICP "${icp.ref}" (archetype ${icp.archetype}) has no persona pointing at it. ${severity === 'ERROR' ? 'Required' : 'Recommended'} for ${icp.archetype}.`,
2080
+ severity,
2081
+ });
2082
+ }
2083
+ }
2084
+
2085
+ function detectInfluenceCycles(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
2086
+ // Self-loops first — always ERROR.
2087
+ for (const [iIdx, icp] of snapshot.icps.entries()) {
2088
+ icp.influences.forEach((edge, idx) => {
2089
+ if (edge.icpRef === icp.ref) {
2090
+ issues.push({
2091
+ kind: MarketSnapshotIssueKind.INFLUENCE_CYCLE,
2092
+ path: `icps[${iIdx}].influences[${idx}].icpRef`,
2093
+ message: `ICP "${icp.ref}" has a self-loop in influences[]. Self-loops are not allowed.`,
2094
+ severity: 'ERROR',
2095
+ });
2096
+ }
2097
+ });
2098
+ }
2099
+
2100
+ // Multi-node cycles — Tarjan-style SCC scan, report each cycle once.
2101
+ const adjacency = new Map<string, string[]>();
2102
+ for (const icp of snapshot.icps) {
2103
+ adjacency.set(
2104
+ icp.ref,
2105
+ icp.influences.filter(e => e.icpRef !== icp.ref).map(e => e.icpRef),
2106
+ );
2107
+ }
2108
+
2109
+ const seenCycles = new Set<string>();
2110
+ const visited = new Set<string>();
2111
+
2112
+ for (const startRef of adjacency.keys()) {
2113
+ if (visited.has(startRef)) continue;
2114
+ const stack: string[] = [];
2115
+ const onStack = new Set<string>();
2116
+
2117
+ const dfs = (node: string): void => {
2118
+ visited.add(node);
2119
+ stack.push(node);
2120
+ onStack.add(node);
2121
+
2122
+ for (const next of adjacency.get(node) ?? []) {
2123
+ if (!adjacency.has(next)) continue;
2124
+ if (!visited.has(next)) {
2125
+ dfs(next);
2126
+ } else if (onStack.has(next)) {
2127
+ const cycleStart = stack.indexOf(next);
2128
+ if (cycleStart >= 0) {
2129
+ const cycle = stack.slice(cycleStart);
2130
+ const key = [...cycle].sort().join('|');
2131
+ if (!seenCycles.has(key)) {
2132
+ seenCycles.add(key);
2133
+ issues.push({
2134
+ kind: MarketSnapshotIssueKind.INFLUENCE_CYCLE,
2135
+ path: `icps[*].influences`,
2136
+ message: `Influence cycle detected: ${cycle.join(' → ')} → ${next}. Cycles are accepted but emit a WARN.`,
2137
+ severity: 'WARN',
2138
+ });
2139
+ }
2140
+ }
2141
+ }
2142
+ }
2143
+
2144
+ stack.pop();
2145
+ onStack.delete(node);
2146
+ };
2147
+
2148
+ dfs(startRef);
2149
+ }
2150
+ }
2151
+
2152
+ function detectMissingPositioningForIcp(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
2153
+ const positionedIcpRefs = new Set(snapshot.positionings.map(p => p.icpRef));
2154
+
2155
+ for (const [iIdx, icp] of snapshot.icps.entries()) {
2156
+ if (icp.priority !== ICPPriority.CORE && icp.priority !== ICPPriority.EXPANSION) continue;
2157
+ if (positionedIcpRefs.has(icp.ref)) continue;
2158
+
2159
+ issues.push({
2160
+ kind: MarketSnapshotIssueKind.MISSING_POSITIONING_FOR_ICP,
2161
+ path: `icps[${iIdx}].ref`,
2162
+ message: `ICP "${icp.ref}" has priority ${icp.priority} but no MarketPositioning entry. CORE and EXPANSION ICPs must be positioned.`,
2163
+ severity: 'ERROR',
2164
+ });
2165
+ }
2166
+ }
2167
+
2168
+ const REVIEW_CADENCE_TO_DAYS: Record<ReviewCadence, number> = {
2169
+ [ReviewCadence.WEEKLY]: 7,
2170
+ [ReviewCadence.MONTHLY]: 31,
2171
+ [ReviewCadence.QUARTERLY]: 92,
2172
+ [ReviewCadence.YEARLY]: 366,
2173
+ [ReviewCadence.AS_NEEDED]: Number.POSITIVE_INFINITY,
2174
+ };
2175
+
2176
+ function detectStaleAuthored(
2177
+ snapshot: MarketSnapshot,
2178
+ now: Date,
2179
+ issues: MarketSnapshotIssue[],
2180
+ ): void {
2181
+ const checkAuthored = (authored: MarketAuthoredMetadata | undefined, path: string, ref: string): void => {
2182
+ if (authored?.reviewCadence === undefined) return;
2183
+ const days = REVIEW_CADENCE_TO_DAYS[authored.reviewCadence];
2184
+ if (!Number.isFinite(days)) return;
2185
+ const lastAuthored = new Date(authored.lastAuthoredAt).getTime();
2186
+ if (Number.isNaN(lastAuthored)) return;
2187
+ const ageMs = now.getTime() - lastAuthored;
2188
+ const ageDays = ageMs / (24 * 60 * 60 * 1000);
2189
+ if (ageDays > days) {
2190
+ issues.push({
2191
+ kind: MarketSnapshotIssueKind.STALE_AUTHORED,
2192
+ path,
2193
+ message: `Authored content for "${ref}" is ${Math.floor(ageDays)} days old (cadence ${authored.reviewCadence} ⇒ ${days}d). Re-author or remove the cadence.`,
2194
+ severity: 'WARN',
2195
+ });
2196
+ }
2197
+ };
2198
+
2199
+ snapshot.icps.forEach((icp, idx) => checkAuthored(icp.authored, `icps[${idx}].authored`, icp.ref));
2200
+ snapshot.personas.forEach((p, idx) => checkAuthored(p.authored, `personas[${idx}].authored`, p.ref));
2201
+ snapshot.jobs.forEach((j, idx) => checkAuthored(j.authored, `jobs[${idx}].authored`, j.ref));
2202
+ snapshot.pains.forEach((p, idx) => checkAuthored(p.authored, `pains[${idx}].authored`, p.ref));
2203
+ snapshot.gains.forEach((g, idx) => checkAuthored(g.authored, `gains[${idx}].authored`, g.ref));
2204
+ snapshot.tonesOfVoice.forEach((v, idx) => checkAuthored(v.authored, `tonesOfVoice[${idx}].authored`, v.ref));
2205
+ snapshot.benefits.forEach((b, idx) => checkAuthored(b.authored, `benefits[${idx}].authored`, b.ref));
2206
+ snapshot.positionings.forEach((p, idx) => checkAuthored(p.authored, `positionings[${idx}].authored`, p.ref));
2207
+ snapshot.messageTemplates.forEach((t, idx) => checkAuthored(t.authored, `messageTemplates[${idx}].authored`, t.ref));
2208
+ snapshot.channels.forEach((c, idx) => checkAuthored(c.authored, `channels[${idx}].authored`, c.ref));
2209
+ snapshot.alternatives.forEach((a, idx) => checkAuthored(a.authored, `alternatives[${idx}].authored`, a.ref));
2210
+ snapshot.triggers.forEach((t, idx) => checkAuthored(t.authored, `triggers[${idx}].authored`, t.ref));
2211
+ snapshot.buyingJourneys.forEach((j, idx) => checkAuthored(j.authored, `buyingJourneys[${idx}].authored`, j.ref));
2212
+ snapshot.proofs.forEach((p, idx) => checkAuthored(p.authored, `proofs[${idx}].authored`, p.ref));
2213
+ snapshot.objections.forEach((o, idx) => checkAuthored(o.authored, `objections[${idx}].authored`, o.ref));
2214
+ checkAuthored(snapshot.category.authored, 'category.authored', snapshot.category.ref);
2215
+ }
2216
+
2217
+ /**
2218
+ * Per-entity duplicate-edge detection.
2219
+ *
2220
+ * Scope (intentionally bounded — see `DUPLICATE_EDGE_PER_ENTITY` JSDoc
2221
+ * on the enum for the canonical list):
2222
+ * - ICP and persona `pains[].painRef` / `gains[].gainRef` /
2223
+ * `jobs[].jobRef`. Duplicates here are typically the result of an
2224
+ * `inheritFrom(parentIcp)` spread followed by a forgotten
2225
+ * `.filter()` step on the persona.
2226
+ * - Benefit `importanceByICP[].icpRef`. Duplicates make per-ICP
2227
+ * weighting non-deterministic in the FIT scorer (the last one wins
2228
+ * silently). We deliberately do NOT collapse the duplicates — we
2229
+ * surface them so authors fix the source instead of relying on
2230
+ * detector-side normalization.
2231
+ *
2232
+ * NOT covered (other detectors / schema constraints handle these):
2233
+ * - benefit `relieves` / `creates` / `advances` weighted edges — the
2234
+ * degree might legitimately differ across entries; future work.
2235
+ * - ICP `buyingGroup[].personaRef` — deduplication is enforced by
2236
+ * intent (a persona is in the group exactly once); future work.
2237
+ */
2238
+ function detectDuplicateEdgesPerEntity(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
2239
+ const reportDuplicates = (
2240
+ refs: string[],
2241
+ basePath: string,
2242
+ field: string,
2243
+ ownerRef: string,
2244
+ refSubpath: string = '',
2245
+ hint: string = 'Likely an inheritFrom() spread that wasn\'t deduplicated.',
2246
+ ): void => {
2247
+ const seen = new Set<string>();
2248
+ refs.forEach((ref, idx) => {
2249
+ if (seen.has(ref)) {
2250
+ issues.push({
2251
+ kind: MarketSnapshotIssueKind.DUPLICATE_EDGE_PER_ENTITY,
2252
+ path: `${basePath}.${field}[${idx}]${refSubpath}`,
2253
+ message: `${field} ref "${ref}" appears more than once on "${ownerRef}". ${hint}`,
2254
+ severity: 'WARN',
2255
+ });
2256
+ }
2257
+ seen.add(ref);
2258
+ });
2259
+ };
2260
+
2261
+ for (const [iIdx, icp] of snapshot.icps.entries()) {
2262
+ const basePath = `icps[${iIdx}]`;
2263
+ reportDuplicates(icp.pains.map(e => e.painRef), basePath, 'pains', icp.ref, '.painRef');
2264
+ reportDuplicates(icp.gains.map(e => e.gainRef), basePath, 'gains', icp.ref, '.gainRef');
2265
+ reportDuplicates(icp.jobs.map(e => e.jobRef), basePath, 'jobs', icp.ref, '.jobRef');
2266
+ }
2267
+ for (const [pIdx, persona] of snapshot.personas.entries()) {
2268
+ const basePath = `personas[${pIdx}]`;
2269
+ reportDuplicates(persona.pains.map(e => e.painRef), basePath, 'pains', persona.ref, '.painRef');
2270
+ reportDuplicates(persona.gains.map(e => e.gainRef), basePath, 'gains', persona.ref, '.gainRef');
2271
+ reportDuplicates(persona.jobs.map(e => e.jobRef), basePath, 'jobs', persona.ref, '.jobRef');
2272
+ }
2273
+ for (const [bIdx, benefit] of snapshot.benefits.entries()) {
2274
+ const basePath = `benefits[${bIdx}]`;
2275
+ reportDuplicates(
2276
+ benefit.importanceByICP.map(e => e.icpRef),
2277
+ basePath,
2278
+ 'importanceByICP',
2279
+ benefit.ref,
2280
+ '.icpRef',
2281
+ 'Each (benefit, icp) pair must appear at most once — duplicates make per-ICP weighting non-deterministic.',
2282
+ );
2283
+ }
2284
+ }
2285
+
2286
+ function detectInvalidAntiTargetPurposeMix(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
2287
+ for (const [iIdx, icp] of snapshot.icps.entries()) {
2288
+ if (icp.priority !== ICPPriority.ANTI_TARGET) continue;
2289
+ const isZero = icp.purposeMix.adoption === 0 && icp.purposeMix.revenue === 0;
2290
+ if (isZero) continue;
2291
+ issues.push({
2292
+ kind: MarketSnapshotIssueKind.INVALID_ANTI_TARGET_PURPOSE_MIX,
2293
+ path: `icps[${iIdx}].purposeMix`,
2294
+ message: `ICP "${icp.ref}" has priority ANTI_TARGET but purposeMix=${JSON.stringify(icp.purposeMix)}. ANTI_TARGET ICPs MUST carry { adoption: 0, revenue: 0 }.`,
2295
+ severity: 'ERROR',
2296
+ });
2297
+ }
2298
+ }
2299
+
2300
+ function detectBuyingGroupPersonasMissingDmuRole(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
2301
+ for (const [pIdx, persona] of snapshot.personas.entries()) {
2302
+ if (persona.personaScope !== PersonaScope.BUYING_GROUP_MEMBER) continue;
2303
+ if (persona.dmuRole !== undefined) continue;
2304
+ issues.push({
2305
+ kind: MarketSnapshotIssueKind.BUYING_GROUP_PERSONA_MISSING_DMU_ROLE,
2306
+ path: `personas[${pIdx}].dmuRole`,
2307
+ message: `Persona "${persona.ref}" has personaScope BUYING_GROUP_MEMBER but no dmuRole. DMU role is required for buying-group members.`,
2308
+ severity: 'ERROR',
2309
+ });
2310
+ }
2311
+ }
2312
+
2313
+ /**
2314
+ * The ICP→persona buying-group link MUST be symmetric: when an ICP
2315
+ * lists a persona in `buyingGroup[].personaRef`, the persona's
2316
+ * `belongsToIcpRefs[]` MUST contain the ICP. Asymmetric links cause
2317
+ * downstream consumers (DMU rendering, persona-by-ICP indexing,
2318
+ * market generation targeting) to silently drop the persona because
2319
+ * the `belongsToIcpRefs[]` index is the canonical traversal path.
2320
+ *
2321
+ * ERROR severity — this is a structural integrity bug, not authoring
2322
+ * polish: the snapshot will pass parse + intent but will silently
2323
+ * misbehave at runtime.
2324
+ *
2325
+ * Reverse direction (persona declares an ICP that does NOT list the
2326
+ * persona in its `buyingGroup[]`) is intentionally NOT reported here:
2327
+ * personas of `INDIVIDUAL_SELF` / `INDIVIDUAL_INFLUENCER` scope are
2328
+ * legitimately attached to ICPs that have no formal buying group.
2329
+ * The detector only runs the ICP→persona direction.
2330
+ */
2331
+ function detectBuyingGroupBacklinkMissing(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
2332
+ const personasByRef = new Map(snapshot.personas.map(p => [p.ref, p] as const));
2333
+
2334
+ for (const [iIdx, icp] of snapshot.icps.entries()) {
2335
+ icp.buyingGroup.forEach((entry, idx) => {
2336
+ const persona = personasByRef.get(entry.personaRef);
2337
+ if (persona === undefined) return; // orphan caught elsewhere
2338
+ if (persona.belongsToIcpRefs.includes(icp.ref)) return;
2339
+ issues.push({
2340
+ kind: MarketSnapshotIssueKind.BUYING_GROUP_BACKLINK_MISSING,
2341
+ path: `icps[${iIdx}].buyingGroup[${idx}].personaRef`,
2342
+ message: `ICP "${icp.ref}" lists persona "${persona.ref}" in buyingGroup[], but the persona's belongsToIcpRefs[] is ${JSON.stringify(persona.belongsToIcpRefs)} (does not include "${icp.ref}"). The link must be symmetric.`,
2343
+ severity: 'ERROR',
2344
+ });
2345
+ });
2346
+ }
2347
+ }
2348
+
2349
+ /**
2350
+ * Phase 3 — a `MarketProof` that supports neither a benefit nor an ICP
2351
+ * has no place to land in generated copy. WARN, not ERROR — the proof
2352
+ * may be in flight ("about to wire it up next") and should not block
2353
+ * boot.
2354
+ */
2355
+ function detectProofsWithoutSupport(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
2356
+ for (const [pIdx, proof] of snapshot.proofs.entries()) {
2357
+ if (proof.supportsBenefitRefs.length > 0 || proof.supportsIcpRefs.length > 0) continue;
2358
+ issues.push({
2359
+ kind: MarketSnapshotIssueKind.PROOF_WITHOUT_SUPPORT,
2360
+ path: `proofs[${pIdx}]`,
2361
+ message: `Proof "${proof.ref}" supports neither a benefit nor an ICP. Add at least one supportsBenefitRefs[] or supportsIcpRefs[] entry, or remove the proof.`,
2362
+ severity: 'WARN',
2363
+ });
2364
+ }
2365
+ }
2366
+
2367
+ /**
2368
+ * Phase 3 — proofKind/payload coherence (WARN). The schema is
2369
+ * intentionally permissive (both `attribution` and `metric` are
2370
+ * optional on every kind) so that authors can mix proof shapes
2371
+ * without fighting the type system. This detector flags the two
2372
+ * mismatches that are unambiguously authoring drift:
2373
+ *
2374
+ * 1. `METRIC` proof without a `metric` block — the structured
2375
+ * `value + unit + period` payload is what distinguishes a
2376
+ * `METRIC` proof from a `QUOTE` that happens to carry a number.
2377
+ * Without it the rendering layer cannot format the proof as a
2378
+ * metric (no value to surface, no unit to localize). Authors
2379
+ * should either add the `metric` block or downgrade the kind to
2380
+ * `QUOTE` / `CASE_STUDY`.
2381
+ * 2. `LOGO` proof with a `metric` block — a logo carries no
2382
+ * quantitative payload by definition, so a `metric` block on a
2383
+ * `LOGO` is a category error. Either move the metric to a
2384
+ * sibling `METRIC` proof or change the kind.
2385
+ *
2386
+ * All other kind/payload combinations are deliberately accepted:
2387
+ * a `QUOTE` may carry a `metric` (a quote that quantifies an
2388
+ * outcome), an `AWARD` may carry an `attribution` (the awarding
2389
+ * body), etc. Adding more rules here trades flexibility for
2390
+ * marginal signal — keep this conservative.
2391
+ */
2392
+ function detectProofKindPayloadMismatch(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
2393
+ for (const [pIdx, proof] of snapshot.proofs.entries()) {
2394
+ if (proof.proofKind === ProofKind.METRIC && proof.metric === undefined) {
2395
+ issues.push({
2396
+ kind: MarketSnapshotIssueKind.PROOF_KIND_PAYLOAD_MISMATCH,
2397
+ path: `proofs[${pIdx}].metric`,
2398
+ message: `Proof "${proof.ref}" is METRIC but carries no structured \`metric\` block (value + unit). Add the metric block or downgrade proofKind to QUOTE/CASE_STUDY.`,
2399
+ severity: 'WARN',
2400
+ });
2401
+ }
2402
+ if (proof.proofKind === ProofKind.LOGO && proof.metric !== undefined) {
2403
+ issues.push({
2404
+ kind: MarketSnapshotIssueKind.PROOF_KIND_PAYLOAD_MISMATCH,
2405
+ path: `proofs[${pIdx}].metric`,
2406
+ message: `Proof "${proof.ref}" is LOGO but carries a \`metric\` block. A logo has no quantitative payload — move the metric to a sibling METRIC proof or change the proofKind.`,
2407
+ severity: 'WARN',
2408
+ });
2409
+ }
2410
+ }
2411
+ }
2412
+
2413
+ /**
2414
+ * A `MarketBuyingJourney` listing the same `BuyingJourneyStage` enum
2415
+ * value more than once is a structural authoring bug (which entry
2416
+ * wins for prompt enrichment? non-deterministic). ERROR.
2417
+ */
2418
+ function detectDuplicateJourneyStages(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
2419
+ for (const [jIdx, journey] of snapshot.buyingJourneys.entries()) {
2420
+ const seenStages = new Set<string>();
2421
+ journey.stages.forEach((entry, idx) => {
2422
+ if (seenStages.has(entry.stage)) {
2423
+ issues.push({
2424
+ kind: MarketSnapshotIssueKind.DUPLICATE_JOURNEY_STAGE,
2425
+ path: `buyingJourneys[${jIdx}].stages[${idx}].stage`,
2426
+ message: `Buying journey "${journey.ref}" lists stage ${entry.stage} more than once. Each BuyingJourneyStage may appear at most once per journey.`,
2427
+ severity: 'ERROR',
2428
+ });
2429
+ }
2430
+ seenStages.add(entry.stage);
2431
+ });
2432
+ }
2433
+ }
2434
+
2435
+ /**
2436
+ * Two `MarketBuyingJourney` entries pointing at the same `icpRef` is
2437
+ * a structural authoring bug — the model is "one journey per ICP" and
2438
+ * downstream consumers (prompt enrichment, journey-by-ICP indexing)
2439
+ * will silently pick the first match. ERROR.
2440
+ */
2441
+ function detectDuplicateBuyingJourneyForIcp(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
2442
+ const seenIcpRefs = new Map<string, number>();
2443
+ snapshot.buyingJourneys.forEach((journey, idx) => {
2444
+ const previousIdx = seenIcpRefs.get(journey.icpRef);
2445
+ if (previousIdx !== undefined) {
2446
+ issues.push({
2447
+ kind: MarketSnapshotIssueKind.DUPLICATE_BUYING_JOURNEY_FOR_ICP,
2448
+ path: `buyingJourneys[${idx}].icpRef`,
2449
+ message: `Buying journey "${journey.ref}" targets ICP "${journey.icpRef}" but buyingJourneys[${previousIdx}] already targets the same ICP. The model is one journey per ICP — merge or remove one.`,
2450
+ severity: 'ERROR',
2451
+ });
2452
+ return;
2453
+ }
2454
+ seenIcpRefs.set(journey.icpRef, idx);
2455
+ });
2456
+ }
2457
+
2458
+ /**
2459
+ * Semantic check: an objection citing `proofRefs[]` should point at
2460
+ * proofs whose support set actually intersects the objection's claim.
2461
+ *
2462
+ * Both sides of the intersection are unioned to be permissive without
2463
+ * being toothless:
2464
+ * - Proof support side: `proof.supportsBenefitRefs[]` ∪
2465
+ * `proof.supportsIcpRefs[]`. A proof that supports the ICP raising
2466
+ * the objection (e.g. a `LOGO` proof for that ICP) is considered
2467
+ * to back the objection even if it doesn't directly back a specific
2468
+ * benefit — logos and case studies are rarely benefit-scoped.
2469
+ * - Objection target side: `objection.relatedBenefitRefs[]` ∪
2470
+ * `objection.raisedByIcpRefs[]`.
2471
+ *
2472
+ * WARN (authoring drift, not catastrophic — the spec parses, but the
2473
+ * cited proofs will not render as supporting evidence in any of the
2474
+ * downstream prompt blocks). Orphan refs are caught separately by
2475
+ * `detectOrphanRefs`.
2476
+ *
2477
+ * Skipped for objections where either side of the intersection is
2478
+ * empty (no proofs cited OR neither related benefits nor raising ICPs
2479
+ * authored — the check has no signal then).
2480
+ */
2481
+ function detectObjectionProofBenefitMismatch(snapshot: MarketSnapshot, issues: MarketSnapshotIssue[]): void {
2482
+ const proofsByRef = new Map(snapshot.proofs.map(p => [p.ref, p] as const));
2483
+
2484
+ for (const [oIdx, objection] of snapshot.objections.entries()) {
2485
+ if (objection.proofRefs.length === 0) continue;
2486
+ const objectionTargets = new Set<string>([
2487
+ ...objection.relatedBenefitRefs,
2488
+ ...objection.raisedByIcpRefs,
2489
+ ]);
2490
+ if (objectionTargets.size === 0) continue;
2491
+
2492
+ const supported = new Set<string>();
2493
+ for (const proofRef of objection.proofRefs) {
2494
+ const proof = proofsByRef.get(proofRef);
2495
+ if (proof === undefined) continue; // orphan caught elsewhere
2496
+ for (const benefitRef of proof.supportsBenefitRefs) supported.add(benefitRef);
2497
+ for (const icpRef of proof.supportsIcpRefs) supported.add(icpRef);
2498
+ }
2499
+
2500
+ const intersects = [...objectionTargets].some(ref => supported.has(ref));
2501
+ if (intersects) continue;
2502
+
2503
+ issues.push({
2504
+ kind: MarketSnapshotIssueKind.OBJECTION_PROOF_BENEFIT_MISMATCH,
2505
+ path: `objections[${oIdx}].proofRefs`,
2506
+ message: `Objection "${objection.ref}" cites proofRefs ${JSON.stringify(objection.proofRefs)} but none of them supports any benefit in relatedBenefitRefs ${JSON.stringify(objection.relatedBenefitRefs)} nor any ICP in raisedByIcpRefs ${JSON.stringify(objection.raisedByIcpRefs)}. The cited proofs do not back the objection.`,
2507
+ severity: 'WARN',
2508
+ });
2509
+ }
2510
+ }
2511
+
2512
+ /**
2513
+ * Maps a `MarketMessageRequiredInput` enum value to the placeholder
2514
+ * shapes inside `promptTemplate` that consume it. Each input matches
2515
+ * either the bare `{{<value>}}` token or any dotted-property descent
2516
+ * `{{<entityName>.path}}` (e.g. `icpRef` is consumed by `{{icpRef}}`,
2517
+ * `{{icp.name}}`, `{{icp.profile.geographies}}`).
2518
+ *
2519
+ * The `entityName` form is the camelCase root WITHOUT the trailing
2520
+ * `Ref` suffix — i.e. `icpRef` → entity name `icp`, `benefitRef` →
2521
+ * `benefit`. This matches the conventional Mustache shape authors use
2522
+ * in templates ("ICP context surfaces under `icp.*`").
2523
+ */
2524
+ const REQUIRED_INPUT_PLACEHOLDER_PATTERNS: Record<MarketMessageRequiredInput, RegExp> = {
2525
+ [MarketMessageRequiredInput.ICP_REF]: /\{\{\s*(?:icpRef|icp(?:\.[A-Za-z0-9_]+)+)\s*\}\}/,
2526
+ [MarketMessageRequiredInput.BENEFIT_REF]: /\{\{\s*(?:benefitRef|benefit(?:\.[A-Za-z0-9_]+)+)\s*\}\}/,
2527
+ [MarketMessageRequiredInput.CHANNEL_REF]: /\{\{\s*(?:channelRef|channel(?:\.[A-Za-z0-9_]+)+)\s*\}\}/,
2528
+ [MarketMessageRequiredInput.OBJECTION_REF]: /\{\{\s*(?:objectionRef|objection(?:\.[A-Za-z0-9_]+)+)\s*\}\}/,
2529
+ };
2530
+
2531
+ /**
2532
+ * Inverse of `REQUIRED_INPUT_PLACEHOLDER_PATTERNS` — given a Mustache
2533
+ * placeholder name extracted from a template body, return the
2534
+ * `MarketMessageRequiredInput` it consumes (or `undefined` if the
2535
+ * leading token is the exempt `{{output_language}}` / an unknown
2536
+ * camelCase root).
2537
+ *
2538
+ * Keyed on the **leading entity name** in two distinct shapes:
2539
+ * - the dotted-root entity (`icp` → consumed by `{{icp.name}}`,
2540
+ * `{{icp.profile.…}}`);
2541
+ * - the explicit `<entity>Ref` token (`icpRef` → consumed by
2542
+ * `{{icpRef}}`).
2543
+ *
2544
+ * The bare-entity token `{{icp}}` (no dot, no `Ref` suffix) is
2545
+ * intentionally NOT a recognized form here: Direction-1 of the
2546
+ * validator (declared → used) rejects it (the regex requires
2547
+ * `\{\{icpRef\}\}` OR `\{\{icp\.<segment>\}\}`), so accepting it in
2548
+ * Direction-2 would create an asymmetric false-positive WARN. The
2549
+ * detector enforces this in `isRecognizedPlaceholderToken(...)`
2550
+ * before consulting the map.
2551
+ */
2552
+ const PLACEHOLDER_ENTITY_TO_REQUIRED_INPUT: Record<string, MarketMessageRequiredInput> = {
2553
+ icp: MarketMessageRequiredInput.ICP_REF,
2554
+ icpRef: MarketMessageRequiredInput.ICP_REF,
2555
+ benefit: MarketMessageRequiredInput.BENEFIT_REF,
2556
+ benefitRef: MarketMessageRequiredInput.BENEFIT_REF,
2557
+ channel: MarketMessageRequiredInput.CHANNEL_REF,
2558
+ channelRef: MarketMessageRequiredInput.CHANNEL_REF,
2559
+ objection: MarketMessageRequiredInput.OBJECTION_REF,
2560
+ objectionRef: MarketMessageRequiredInput.OBJECTION_REF,
2561
+ };
2562
+
2563
+ /**
2564
+ * Returns the `MarketMessageRequiredInput` consumed by a Mustache
2565
+ * placeholder body (everything between `{{` and `}}` with whitespace
2566
+ * stripped), or `undefined` when the token does not consume any
2567
+ * required input.
2568
+ *
2569
+ * Symmetric with `REQUIRED_INPUT_PLACEHOLDER_PATTERNS`:
2570
+ * - dotted access (`icp.name`, `icp.profile.geographies`) → consumes
2571
+ * the dotted root's required input;
2572
+ * - explicit `<entity>Ref` (`icpRef`) → consumes the matching
2573
+ * required input;
2574
+ * - bare entity (`icp`) → DOES NOT consume — same as Direction-1.
2575
+ */
2576
+ function lookupConsumedRequiredInput(
2577
+ innerExpression: string,
2578
+ ): MarketMessageRequiredInput | undefined {
2579
+ const dotIndex = innerExpression.indexOf('.');
2580
+ if (dotIndex >= 0) {
2581
+ const dottedRoot = innerExpression.slice(0, dotIndex).trim();
2582
+ return PLACEHOLDER_ENTITY_TO_REQUIRED_INPUT[dottedRoot];
2583
+ }
2584
+ // No dot — only the explicit `<entity>Ref` form is recognized.
2585
+ if (!innerExpression.endsWith('Ref')) return undefined;
2586
+ return PLACEHOLDER_ENTITY_TO_REQUIRED_INPUT[innerExpression];
2587
+ }
2588
+
2589
+ /**
2590
+ * Mustache token names that are CLI-injected at render time and are
2591
+ * therefore NOT expected to appear in `requiredInputs[]`. Today only
2592
+ * `output_language` is in this set (substituted from the
2593
+ * `--output-language` flag), but the set
2594
+ * is structured to grow with future CLI-side affordances.
2595
+ */
2596
+ const PLACEHOLDER_ENTITY_EXEMPT_FROM_REQUIRED_INPUTS: ReadonlySet<string> = new Set([
2597
+ 'output_language',
2598
+ ]);
2599
+
2600
+ /**
2601
+ * Match every Mustache placeholder inside a template body. Captures
2602
+ * the inner expression with surrounding whitespace stripped so callers
2603
+ * can split on `.` to extract the leading entity name.
2604
+ *
2605
+ * Permissive on identifier shape — accepts kebab-free dot paths
2606
+ * (`icp.name`, `icp.profile.geographies`) and bare identifiers
2607
+ * (`icpRef`, `output_language`). Mustache section tokens
2608
+ * (`{{#...}}` / `{{^...}}` / `{{/...}}` / `{{!...}}`) are filtered
2609
+ * via the leading sigil check below.
2610
+ */
2611
+ const MUSTACHE_PLACEHOLDER_REGEX = /\{\{\s*([^}]+?)\s*\}\}/g;
2612
+
2613
+ /**
2614
+ * Phase-4 (§10.3 of the plan) — declared/used coherence check on
2615
+ * `MarketMessageTemplate.promptTemplate` ↔ `requiredInputs[]`.
2616
+ *
2617
+ * The detector is symmetric: it surfaces both directions of drift
2618
+ * (declared but never substituted; used in the body but never
2619
+ * declared) under the same `MESSAGE_TEMPLATE_PLACEHOLDER_MISMATCH`
2620
+ * kind. The message text disambiguates the direction so authors can
2621
+ * fix it from the report alone.
2622
+ *
2623
+ * The exempt token set ({{output_language}} today) is filtered before
2624
+ * the "used but not declared" pass — see
2625
+ * `PLACEHOLDER_ENTITY_EXEMPT_FROM_REQUIRED_INPUTS`. Unknown camelCase
2626
+ * roots (e.g. `{{persona.name}}` if persona ever becomes a placeholder
2627
+ * shape) are silently ignored — this detector covers ONLY the inputs
2628
+ * declared in `MarketMessageRequiredInput`. Adding a new required-input
2629
+ * shape requires extending both `PLACEHOLDER_ENTITY_TO_REQUIRED_INPUT`
2630
+ * and `REQUIRED_INPUT_PLACEHOLDER_PATTERNS` together.
2631
+ */
2632
+ function detectMessageTemplatePlaceholderMismatch(
2633
+ snapshot: MarketSnapshot,
2634
+ issues: MarketSnapshotIssue[],
2635
+ ): void {
2636
+ for (const [tIdx, template] of snapshot.messageTemplates.entries()) {
2637
+ const declaredInputs = new Set<MarketMessageRequiredInput>(template.requiredInputs ?? []);
2638
+
2639
+ // Direction 1: declared but the body has no consuming placeholder.
2640
+ for (const declared of declaredInputs) {
2641
+ const pattern = REQUIRED_INPUT_PLACEHOLDER_PATTERNS[declared];
2642
+ if (pattern.test(template.promptTemplate)) continue;
2643
+ issues.push({
2644
+ kind: MarketSnapshotIssueKind.MESSAGE_TEMPLATE_PLACEHOLDER_MISMATCH,
2645
+ path: `messageTemplates[${tIdx}].requiredInputs`,
2646
+ message:
2647
+ `Message template "${template.ref}" declares requiredInput "${declared}" but no `
2648
+ + `\`{{${declared.replace(/Ref$/, '')}.*}}\` / \`{{${declared}}}\` placeholder exists in promptTemplate. `
2649
+ + `Add the placeholder or prune the requiredInput entry.`,
2650
+ severity: 'WARN',
2651
+ });
2652
+ }
2653
+
2654
+ // Direction 2: body references a known input shape that is not declared.
2655
+ const referencedInputs = new Set<MarketMessageRequiredInput>();
2656
+ MUSTACHE_PLACEHOLDER_REGEX.lastIndex = 0;
2657
+ let match: RegExpExecArray | null;
2658
+ while ((match = MUSTACHE_PLACEHOLDER_REGEX.exec(template.promptTemplate)) !== null) {
2659
+ const inner = match[1] ?? '';
2660
+ // Skip Mustache section / inverted / closing / comment tokens.
2661
+ const firstChar = inner[0];
2662
+ if (firstChar === '#' || firstChar === '^' || firstChar === '/' || firstChar === '!') continue;
2663
+
2664
+ const leadingEntity = inner.split('.')[0]?.trim() ?? '';
2665
+ if (leadingEntity.length === 0) continue;
2666
+ if (PLACEHOLDER_ENTITY_EXEMPT_FROM_REQUIRED_INPUTS.has(leadingEntity)) continue;
2667
+
2668
+ const consumedInput = lookupConsumedRequiredInput(inner);
2669
+ if (consumedInput === undefined) continue; // unknown entity root — out of scope for this detector
2670
+ referencedInputs.add(consumedInput);
2671
+ }
2672
+
2673
+ for (const referenced of referencedInputs) {
2674
+ if (declaredInputs.has(referenced)) continue;
2675
+ issues.push({
2676
+ kind: MarketSnapshotIssueKind.MESSAGE_TEMPLATE_PLACEHOLDER_MISMATCH,
2677
+ path: `messageTemplates[${tIdx}].promptTemplate`,
2678
+ message:
2679
+ `Message template "${template.ref}" references \`{{${referenced.replace(/Ref$/, '')}.*}}\` / `
2680
+ + `\`{{${referenced}}}\` placeholders but does not declare "${referenced}" in requiredInputs[]. `
2681
+ + `Add the requiredInput entry or remove the placeholder.`,
2682
+ severity: 'WARN',
2683
+ });
2684
+ }
2685
+ }
2686
+ }
2687
+ ```
2688
+
2689
+ ## Verification
2690
+
2691
+ - [ ] CLI / agent calls the appropriate behavior
2692
+ (`market-context-for-feature` for "edit feature X",
2693
+ `market-context-for-icp` for per-ICP outputs)
2694
+ - [ ] `featureRef` / `icpRef` is non-empty (the handler throws
2695
+ otherwise)
2696
+ - [ ] `outputLanguage` is passed only when non-English output is
2697
+ desired (omit for English to keep the block clean)
2698
+ - [ ] The rendered `block` is pasted into the LLM message verbatim
2699
+ (no markdown stripping, no section reordering)
2700
+ - [ ] The `trace` is logged in debug mode so authoring drift is
2701
+ diagnosable
2702
+
2703
+ ### Grep invariants
2704
+
2705
+ | Invariant | Command |
2706
+ |--------------------------------------------------------------------|--------------------------------------------------------------------------|
2707
+ | Behavior IDs registered in the companion model | `rg -n "market-context-for-(feature\|icp)" --type ts` |
2708
+ | Handlers wired into the builtin handler map | `rg -n "buildMarketContextBlock\(" --type ts` |
2709
+ | Specifications companion exports `marketSpecification` | `rg -n "marketSpecification" --type ts \| rg "companion-exports"` |
2710
+
2711
+ ## Common Rationalizations
2712
+
2713
+ | Rationalization | Reality |
2714
+ |-----------------|---------|
2715
+ | "Read the snapshot directly in the CLI — skip the companion round-trip." | The companion is the canonical access point. CLIs that read the snapshot directly bypass companion-side wiring (the spec slice will move, the loader will gain caching, etc.) and produce stale prompts when those move. |
2716
+ | "Write a custom renderer per agent — `buildMarketContextBlock` is too generic." | The shared renderer is the contract. Custom renderers per agent drift over time and produce inconsistent grounding. Extend the renderer through a new `intent` kind proposed upstream if the existing two are not enough. |
2717
+ | "Translate the block before passing to the LLM." | The block is English by D15. The LLM is the translator. Translating the block before calling the LLM doubles the cost and corrupts the deterministic structure (heading-by-heading) the LLM relies on. |
2718
+ | "Drop `outputLanguage` — the LLM will infer the language from the user message." | Inference is unreliable for short user prompts. Explicit `outputLanguage` is one extra string and removes a class of subtle bugs. |
2719
+
2720
+ ## Red Flags
2721
+
2722
+ - A consumer that reads `marketSpecification` directly from the
2723
+ filesystem instead of going through the companion behavior
2724
+ - A consumer that calls `buildMarketContextBlock` with a literal
2725
+ snapshot it constructs in-process (the renderer is meant to run
2726
+ inside the companion subprocess, not on the CLI side, so the
2727
+ snapshot loader is exercised)
2728
+ - An agent that strips the block's markdown headings before passing
2729
+ to the LLM (loses the section grounding)
2730
+ - An agent that calls one behavior per LLM turn AND passes the
2731
+ rendered block in TWICE (the block is self-contained — paste once)
2732
+ - A consumer that ignores the `trace` field (the trace is the
2733
+ authoring-drift diagnostic; without it "why is X missing" is
2734
+ unanswerable)
2735
+
2736
+ ## References
2737
+
2738
+ - `references/framework-companion-behavior-api.md` —
2739
+ `CompanionIntrospectionBehaviorId` enum, the `'market'` category,
2740
+ the routing definitions for both behaviors.
2741
+
2742
+ ## Related Skills
2743
+
2744
+ - `market-message-templates-authoring` — the templates the rendered
2745
+ block is paired with at the LLM call site
2746
+ - `market-snapshot-validation` — owns the
2747
+ `MESSAGE_TEMPLATE_PLACEHOLDER_MISMATCH` rule that polices the
2748
+ template / placeholder coherence
2749
+ - `market-authoring-overview` — assembles the snapshot the renderer
2750
+ consumes
2751
+ - `module-companion-exports` — exposes the snapshot to the dev
2752
+ companion via `companion-exports.ts`