@egbe-ai/opencode 0.0.0-stage → 0.1.8

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 (479) hide show
  1. package/LICENSE +4 -0
  2. package/README.md +124 -2
  3. package/index.js +5 -0
  4. package/package.json +55 -4
  5. package/plugin.js +230 -0
  6. package/session-log.js +315 -0
  7. package/skills/.egbe-catalog/manifest.json +1 -0
  8. package/skills/egbe-os-analytics/SKILL.md +499 -0
  9. package/skills/egbe-os-analytics/canonical-events.v1.json +256 -0
  10. package/skills/egbe-os-analytics/references/session-funnel.md +130 -0
  11. package/skills/egbe-os-analytics/references/workflows/activation-tracking.md +147 -0
  12. package/skills/egbe-os-analytics/references/workflows/landing-click-tracking.md +209 -0
  13. package/skills/egbe-os-analytics/references/workflows/payment-lifecycle-tracking.md +122 -0
  14. package/skills/egbe-os-analytics/references/workflows/product-funnel-tracking.md +77 -0
  15. package/skills/egbe-os-analytics/references/workflows/signup-lifecycle-tracking.md +208 -0
  16. package/skills/egbe-os-analytics/scripts/umami_funnel.py +927 -0
  17. package/skills/egbe-os-apollo-lead-finder/SKILL.md +135 -0
  18. package/skills/egbe-os-apollo-lead-finder/references/operations.md +240 -0
  19. package/skills/egbe-os-apollo-lead-finder/scripts/enrich.js +6 -0
  20. package/skills/egbe-os-apollo-lead-finder/scripts/enrich.sh +4 -0
  21. package/skills/egbe-os-apollo-lead-finder/scripts/find-leads.js +6 -0
  22. package/skills/egbe-os-apollo-lead-finder/scripts/find-leads.sh +4 -0
  23. package/skills/egbe-os-apollo-lead-finder/scripts/lib/apollo-client.js +343 -0
  24. package/skills/egbe-os-apollo-lead-finder/scripts/lib/connection-identity.js +17 -0
  25. package/skills/egbe-os-apollo-lead-finder/scripts/lib/helpers.js +127 -0
  26. package/skills/egbe-os-apollo-lead-finder/scripts/lib/places-filters.js +217 -0
  27. package/skills/egbe-os-apollo-lead-finder/scripts/lib/sourcing.js +153 -0
  28. package/skills/egbe-os-apollo-lead-finder/scripts/places-leads.js +653 -0
  29. package/skills/egbe-os-apollo-lead-finder/scripts/places-leads.sh +4 -0
  30. package/skills/egbe-os-apollo-lead-finder/scripts/search.js +6 -0
  31. package/skills/egbe-os-apollo-lead-finder/scripts/search.sh +4 -0
  32. package/skills/egbe-os-campaign-landing-page/SKILL.md +95 -0
  33. package/skills/egbe-os-campaign-landing-page/agents/openai.yaml +4 -0
  34. package/skills/egbe-os-campaign-landing-page/references/leads-calendar-and-tracking.md +66 -0
  35. package/skills/egbe-os-campaign-landing-page/references/os-wiring.md +58 -0
  36. package/skills/egbe-os-campaign-landing-page/references/qa.md +40 -0
  37. package/skills/egbe-os-campaign-landing-page/references/routing.md +32 -0
  38. package/skills/egbe-os-db/SKILL.md +174 -0
  39. package/skills/egbe-os-deploy/SKILL.md +412 -0
  40. package/skills/egbe-os-design/SKILL.md +182 -0
  41. package/skills/egbe-os-design-landing-page/SKILL.md +117 -0
  42. package/skills/egbe-os-design-landing-page/agents/openai.yaml +4 -0
  43. package/skills/egbe-os-design-landing-page/assets/scaffold/.dockerignore +11 -0
  44. package/skills/egbe-os-design-landing-page/assets/scaffold/AGENTS.md +31 -0
  45. package/skills/egbe-os-design-landing-page/assets/scaffold/Dockerfile +21 -0
  46. package/skills/egbe-os-design-landing-page/assets/scaffold/eslint.config.mjs +18 -0
  47. package/skills/egbe-os-design-landing-page/assets/scaffold/next.config.ts +11 -0
  48. package/skills/egbe-os-design-landing-page/assets/scaffold/package.json +36 -0
  49. package/skills/egbe-os-design-landing-page/assets/scaffold/postcss.config.mjs +7 -0
  50. package/skills/egbe-os-design-landing-page/assets/scaffold/public/.gitkeep +1 -0
  51. package/skills/egbe-os-design-landing-page/assets/scaffold/sentry.edge.config.ts +13 -0
  52. package/skills/egbe-os-design-landing-page/assets/scaffold/sentry.server.config.ts +13 -0
  53. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/global-error.tsx +19 -0
  54. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/globals.css +22 -0
  55. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/layout.tsx +21 -0
  56. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/page.tsx +3 -0
  57. package/skills/egbe-os-design-landing-page/assets/scaffold/src/app/privacy/page.tsx +28 -0
  58. package/skills/egbe-os-design-landing-page/assets/scaffold/src/components/egbe-analytics.tsx +39 -0
  59. package/skills/egbe-os-design-landing-page/assets/scaffold/src/instrumentation-client.ts +15 -0
  60. package/skills/egbe-os-design-landing-page/assets/scaffold/src/instrumentation.ts +13 -0
  61. package/skills/egbe-os-design-landing-page/assets/scaffold/src/lib/egbe-observability.generated.ts +20 -0
  62. package/skills/egbe-os-design-landing-page/assets/scaffold/src/lib/utils.ts +6 -0
  63. package/skills/egbe-os-design-landing-page/assets/scaffold/tsconfig.json +34 -0
  64. package/skills/egbe-os-design-landing-page/references/application-preparation.md +44 -0
  65. package/skills/egbe-os-design-landing-page/references/page-inputs.md +22 -0
  66. package/skills/egbe-os-destination-readiness/SKILL.md +132 -0
  67. package/skills/egbe-os-destination-readiness/references/checks.md +130 -0
  68. package/skills/egbe-os-destination-readiness/references/network-requirements.md +34 -0
  69. package/skills/egbe-os-destination-readiness/references/report.md +116 -0
  70. package/skills/egbe-os-domains/SKILL.md +189 -0
  71. package/skills/egbe-os-errors/SKILL.md +259 -0
  72. package/skills/egbe-os-git/SKILL.md +275 -0
  73. package/skills/egbe-os-git/references/issues.md +33 -0
  74. package/skills/egbe-os-google-ads/SKILL.md +163 -0
  75. package/skills/egbe-os-google-ads/references/artifacts.md +133 -0
  76. package/skills/egbe-os-google-ads/references/campaigns.md +157 -0
  77. package/skills/egbe-os-google-ads/references/conversions.md +153 -0
  78. package/skills/egbe-os-google-ads/references/delivery.md +128 -0
  79. package/skills/egbe-os-google-ads/references/keyword-ideas.md +40 -0
  80. package/skills/egbe-os-google-ads/references/reporting.md +105 -0
  81. package/skills/egbe-os-google-ads/references/search-assets.md +219 -0
  82. package/skills/egbe-os-google-ads/references/server-conversions.md +119 -0
  83. package/skills/egbe-os-google-auth/SKILL.md +285 -0
  84. package/skills/egbe-os-google-auth/agents/openai.yaml +4 -0
  85. package/skills/egbe-os-gtm-knowledge/SKILL.md +151 -0
  86. package/skills/egbe-os-images/SKILL.md +163 -0
  87. package/skills/egbe-os-images/references/stock-images.md +21 -0
  88. package/skills/egbe-os-instantly-campaign-launcher/SKILL.md +127 -0
  89. package/skills/egbe-os-instantly-campaign-launcher/references/instantly-ops.md +260 -0
  90. package/skills/egbe-os-instantly-campaign-launcher/references/observation-and-scheduling.md +188 -0
  91. package/skills/egbe-os-instantly-campaign-launcher/references/reply-handling.md +116 -0
  92. package/skills/egbe-os-instantly-campaign-launcher/references/run-spec-template.json +65 -0
  93. package/skills/egbe-os-instantly-campaign-launcher/references/run-state.md +145 -0
  94. package/skills/egbe-os-instantly-campaign-launcher/scripts/conclude-campaign.js +158 -0
  95. package/skills/egbe-os-instantly-campaign-launcher/scripts/install-crons.js +956 -0
  96. package/skills/egbe-os-instantly-campaign-launcher/scripts/launch-campaign.js +2008 -0
  97. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/campaign-metrics.js +124 -0
  98. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/confirmed-opt-outs.js +208 -0
  99. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/connection-identity.js +17 -0
  100. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/create-once.js +23 -0
  101. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/gtm-identity.js +125 -0
  102. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/helpers.js +545 -0
  103. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/html-body.js +266 -0
  104. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/instantly-client.js +328 -0
  105. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/outreach-db.js +370 -0
  106. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/recipient-exclusion/index.js +86 -0
  107. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/replenish-test-harness.js +53 -0
  108. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/reply-queue.js +67 -0
  109. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/run-config.js +103 -0
  110. package/skills/egbe-os-instantly-campaign-launcher/scripts/lib/sender-selection.js +105 -0
  111. package/skills/egbe-os-instantly-campaign-launcher/scripts/monitor-campaign.js +607 -0
  112. package/skills/egbe-os-instantly-campaign-launcher/scripts/outreach-report.js +147 -0
  113. package/skills/egbe-os-instantly-campaign-launcher/scripts/replenish-leads.js +619 -0
  114. package/skills/egbe-os-instantly-campaign-launcher/scripts/reply-worker.js +258 -0
  115. package/skills/egbe-os-instantly-campaign-launcher/scripts/run-cron-job.js +32 -0
  116. package/skills/egbe-os-instantly-campaign-launcher/scripts/send-reply.js +260 -0
  117. package/skills/egbe-os-linkedin-ads/SKILL.md +114 -0
  118. package/skills/egbe-os-linkedin-ads/references/destination-requirements.md +30 -0
  119. package/skills/egbe-os-linkedin-ads/references/runtime/api-reference.md +154 -0
  120. package/skills/egbe-os-linkedin-ads/references/runtime/artifacts.md +63 -0
  121. package/skills/egbe-os-linkedin-ads/references/workflows/build-paused.md +44 -0
  122. package/skills/egbe-os-linkedin-ads/references/workflows/conversions.md +88 -0
  123. package/skills/egbe-os-linkedin-ads/references/workflows/launch-and-pause.md +49 -0
  124. package/skills/egbe-os-linkedin-ads/references/workflows/monitoring.md +35 -0
  125. package/skills/egbe-os-linkedin-ads/references/workflows/readiness.md +63 -0
  126. package/skills/egbe-os-linkedin-ads/references/workflows/targeting-and-creative.md +52 -0
  127. package/skills/egbe-os-llm/SKILL.md +160 -0
  128. package/skills/egbe-os-mail/SKILL.md +180 -0
  129. package/skills/egbe-os-me/SKILL.md +119 -0
  130. package/skills/egbe-os-meta-ads/SKILL.md +114 -0
  131. package/skills/egbe-os-meta-ads/references/creative/creative-specs.md +15 -0
  132. package/skills/egbe-os-meta-ads/references/creative/talking-head.md +35 -0
  133. package/skills/egbe-os-meta-ads/references/destination-requirements.md +30 -0
  134. package/skills/egbe-os-meta-ads/references/runtime/api-reference.md +436 -0
  135. package/skills/egbe-os-meta-ads/references/runtime/artifacts.md +51 -0
  136. package/skills/egbe-os-meta-ads/references/runtime/insights-reference.md +187 -0
  137. package/skills/egbe-os-meta-ads/references/runtime/pixel-install.md +196 -0
  138. package/skills/egbe-os-meta-ads/references/runtime/shared-analytics-attribution.md +16 -0
  139. package/skills/egbe-os-meta-ads/references/workflows/build-paused.md +36 -0
  140. package/skills/egbe-os-meta-ads/references/workflows/launch-ready.md +16 -0
  141. package/skills/egbe-os-meta-ads/references/workflows/launch.md +23 -0
  142. package/skills/egbe-os-meta-ads/references/workflows/monitoring.md +72 -0
  143. package/skills/egbe-os-meta-ads/references/workflows/pause.md +17 -0
  144. package/skills/egbe-os-meta-ads/references/workflows/recovery.md +23 -0
  145. package/skills/egbe-os-meta-ads/scripts/check-pixel.py +229 -0
  146. package/skills/egbe-os-meta-ads/scripts/validate-meta-artifacts.py +187 -0
  147. package/skills/egbe-os-notifications/SKILL.md +78 -0
  148. package/skills/egbe-os-openai-ads/SKILL.md +149 -0
  149. package/skills/egbe-os-openai-ads/references/creative/chat-card.md +51 -0
  150. package/skills/egbe-os-openai-ads/references/destination-requirements.md +29 -0
  151. package/skills/egbe-os-openai-ads/references/runtime/api-reference.md +219 -0
  152. package/skills/egbe-os-openai-ads/references/runtime/artifacts.md +169 -0
  153. package/skills/egbe-os-openai-ads/references/workflows/build-paused.md +40 -0
  154. package/skills/egbe-os-openai-ads/references/workflows/conversions.md +40 -0
  155. package/skills/egbe-os-openai-ads/references/workflows/creative-assembly.md +24 -0
  156. package/skills/egbe-os-openai-ads/references/workflows/launch.md +27 -0
  157. package/skills/egbe-os-openai-ads/references/workflows/monitoring.md +54 -0
  158. package/skills/egbe-os-openai-ads/references/workflows/pause.md +22 -0
  159. package/skills/egbe-os-openai-ads/references/workflows/readiness.md +37 -0
  160. package/skills/egbe-os-openai-ads/references/workflows/tracking.md +32 -0
  161. package/skills/egbe-os-openai-ads/scripts/validate-openai-artifacts.py +271 -0
  162. package/skills/egbe-os-organic-trend-watch/SKILL.md +139 -0
  163. package/skills/egbe-os-organic-trend-watch/agents/openai.yaml +4 -0
  164. package/skills/egbe-os-organic-trend-watch/references/analysis-and-adaptation.md +54 -0
  165. package/skills/egbe-os-organic-trend-watch/references/collection-and-analysis.md +117 -0
  166. package/skills/egbe-os-organic-trend-watch/references/output-contract.md +133 -0
  167. package/skills/egbe-os-organic-trend-watch/references/provider-contract.md +169 -0
  168. package/skills/egbe-os-organic-trend-watch/references/runtime-contract.md +204 -0
  169. package/skills/egbe-os-organic-trend-watch/references/visual-analysis-prompt.md +17 -0
  170. package/skills/egbe-os-organic-trend-watch/scripts/_analysis.py +612 -0
  171. package/skills/egbe-os-organic-trend-watch/scripts/_contract.py +1133 -0
  172. package/skills/egbe-os-organic-trend-watch/scripts/_provider_inputs.py +165 -0
  173. package/skills/egbe-os-organic-trend-watch/scripts/analyze-visual-evidence.py +315 -0
  174. package/skills/egbe-os-organic-trend-watch/scripts/build-provider-inputs.py +88 -0
  175. package/skills/egbe-os-organic-trend-watch/scripts/connection_identity.py +22 -0
  176. package/skills/egbe-os-organic-trend-watch/scripts/egbe_artifacts.py +24 -0
  177. package/skills/egbe-os-organic-trend-watch/scripts/finalize-receipt.py +106 -0
  178. package/skills/egbe-os-organic-trend-watch/scripts/normalize-videos.py +647 -0
  179. package/skills/egbe-os-organic-trend-watch/scripts/prepare-visual-evidence.py +324 -0
  180. package/skills/egbe-os-organic-trend-watch/scripts/render-result.py +30 -0
  181. package/skills/egbe-os-organic-trend-watch/scripts/run-apify.py +723 -0
  182. package/skills/egbe-os-organic-trend-watch/scripts/run-state.py +192 -0
  183. package/skills/egbe-os-organic-trend-watch/scripts/validate-context.py +27 -0
  184. package/skills/egbe-os-organic-trend-watch/scripts/validate-runtime.py +137 -0
  185. package/skills/egbe-os-payments/SKILL.md +215 -0
  186. package/skills/egbe-os-payments/agents/openai.yaml +4 -0
  187. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/.egbe/scaffolds/billing-nextjs-subscription.v1.json +5 -0
  188. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/AGENTS.append.md +13 -0
  189. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/db/migrations/1000_egbe_billing.sql +66 -0
  190. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/package.fragment.json +12 -0
  191. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/scripts/billing-sync.mjs +162 -0
  192. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/account/billing/error.tsx +11 -0
  193. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/account/billing/loading.tsx +8 -0
  194. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/account/billing/page.tsx +121 -0
  195. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/billing/checkout/route.ts +102 -0
  196. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/billing/portal/route.ts +54 -0
  197. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/billing/status/route.ts +22 -0
  198. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/app/api/payments/webhook/route.ts +65 -0
  199. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/components/egbe-billing/plan-badge.tsx +16 -0
  200. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/billing-sync.test.mjs +58 -0
  201. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/catalog.ts +82 -0
  202. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/checkout-payload.ts +47 -0
  203. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/foundation-contract.test.mjs +59 -0
  204. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/lifecycle.d.ts +16 -0
  205. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/lifecycle.mjs +82 -0
  206. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/lifecycle.test.mjs +94 -0
  207. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/os-client.ts +96 -0
  208. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/plans.json +17 -0
  209. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/repository.ts +325 -0
  210. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/signature.d.ts +6 -0
  211. package/skills/egbe-os-payments/assets/scaffolds/billing-nextjs-subscription/src/lib/egbe-billing/signature.mjs +22 -0
  212. package/skills/egbe-os-payments/references/contracts/plan-catalog.md +46 -0
  213. package/skills/egbe-os-payments/references/security/durable-verification.md +64 -0
  214. package/skills/egbe-os-payments/references/security/server-integration.md +26 -0
  215. package/skills/egbe-os-payments/references/security/webhook-and-entitlements.md +152 -0
  216. package/skills/egbe-os-payments/references/ux/billing-experience.md +47 -0
  217. package/skills/egbe-os-payments/references/workflows/account-billing.md +64 -0
  218. package/skills/egbe-os-payments/references/workflows/discounts-and-promotion-codes.md +265 -0
  219. package/skills/egbe-os-payments/references/workflows/one-time-purchase.md +75 -0
  220. package/skills/egbe-os-payments/references/workflows/product-checkout.md +355 -0
  221. package/skills/egbe-os-payments/references/workflows/subscription-lifecycle.md +55 -0
  222. package/skills/egbe-os-playbook/SKILL.md +79 -0
  223. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/email-outreach.md +91 -0
  224. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/google-search.md +40 -0
  225. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/linkedin.md +24 -0
  226. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/meta.md +23 -0
  227. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/openai.md +15 -0
  228. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/channels/reddit.md +56 -0
  229. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/choose-test.md +73 -0
  230. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/evaluate.md +91 -0
  231. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/market.md +96 -0
  232. package/skills/egbe-os-playbook/playbooks/market-and-acquisition/run-test.md +111 -0
  233. package/skills/egbe-os-playbook/playbooks/market-and-acquisition.md +56 -0
  234. package/skills/egbe-os-playbook/playbooks/product/business-loop.md +141 -0
  235. package/skills/egbe-os-playbook/playbooks/product/collaboration.md +26 -0
  236. package/skills/egbe-os-playbook/playbooks/product/deliver.md +75 -0
  237. package/skills/egbe-os-playbook/playbooks/product/diagnose.md +80 -0
  238. package/skills/egbe-os-playbook/playbooks/product/evaluate.md +67 -0
  239. package/skills/egbe-os-playbook/playbooks/product/experience.md +132 -0
  240. package/skills/egbe-os-playbook/playbooks/product/loop-examples.md +67 -0
  241. package/skills/egbe-os-playbook/playbooks/product/offer.md +65 -0
  242. package/skills/egbe-os-playbook/playbooks/product/value.md +91 -0
  243. package/skills/egbe-os-playbook/playbooks/product.md +67 -0
  244. package/skills/egbe-os-playbook/references/catalog.md +127 -0
  245. package/skills/egbe-os-playbook/references/changes.md +167 -0
  246. package/skills/egbe-os-playbook/scripts/playbook-changes.py +6 -0
  247. package/skills/egbe-os-playbook/scripts/playbook_changes/__init__.py +1 -0
  248. package/skills/egbe-os-playbook/scripts/playbook_changes/cli.py +57 -0
  249. package/skills/egbe-os-playbook/scripts/playbook_changes/operations.py +137 -0
  250. package/skills/egbe-os-playbook/scripts/playbook_changes/protocol.py +132 -0
  251. package/skills/egbe-os-playbook/scripts/playbook_changes/storage.py +180 -0
  252. package/skills/egbe-os-playbook/scripts/playbook_changes/transport.py +113 -0
  253. package/skills/egbe-os-product-auth/SKILL.md +151 -0
  254. package/skills/egbe-os-product-auth/agents/openai.yaml +4 -0
  255. package/skills/egbe-os-product-auth/assets/db/README.md +102 -0
  256. package/skills/egbe-os-product-auth/assets/db/create-validation-session.mjs +223 -0
  257. package/skills/egbe-os-product-auth/assets/db/migrate.mjs +64 -0
  258. package/skills/egbe-os-product-auth/assets/db/migrations/0001_auth.sql +33 -0
  259. package/skills/egbe-os-product-auth/assets/db/migrations/0002_auth_identities.sql +16 -0
  260. package/skills/egbe-os-product-auth/assets/scaffolds/product-auth-database/AGENTS.append.md +17 -0
  261. package/skills/egbe-os-product-auth/assets/scaffolds/product-auth-database/package.fragment.json +10 -0
  262. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/AGENTS.append.md +9 -0
  263. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/package.fragment.json +13 -0
  264. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/db.ts +31 -0
  265. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/identity.ts +94 -0
  266. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/index.ts +3 -0
  267. package/skills/egbe-os-product-auth/assets/scaffolds/product-nextjs-postgres/src/lib/egbe-product/session.ts +91 -0
  268. package/skills/egbe-os-product-auth/references/contracts/live-auth-interface.md +108 -0
  269. package/skills/egbe-os-product-auth/references/frameworks/nextjs.md +34 -0
  270. package/skills/egbe-os-product-auth/references/security/session-and-credentials.md +73 -0
  271. package/skills/egbe-os-product-auth/references/ux/auth-experience.md +58 -0
  272. package/skills/egbe-os-product-auth/references/workflows/account-recovery.md +22 -0
  273. package/skills/egbe-os-product-auth/references/workflows/build-auth.md +212 -0
  274. package/skills/egbe-os-product-auth/references/workflows/google.md +34 -0
  275. package/skills/egbe-os-product-auth/references/workflows/passwordless-email.md +65 -0
  276. package/skills/egbe-os-product-build/SKILL.md +111 -0
  277. package/skills/egbe-os-product-build/agents/openai.yaml +4 -0
  278. package/skills/egbe-os-product-build/references/capabilities.md +25 -0
  279. package/skills/egbe-os-product-build/references/engineering.md +72 -0
  280. package/skills/egbe-os-product-build/references/execution.md +55 -0
  281. package/skills/egbe-os-product-build/references/foundations.md +93 -0
  282. package/skills/egbe-os-product-build/references/interface-quality.md +32 -0
  283. package/skills/egbe-os-product-build/references/workflows/private-review-handoff.md +86 -0
  284. package/skills/egbe-os-product-build/scripts/scaffold.py +296 -0
  285. package/skills/egbe-os-product-demo-video/SKILL.md +118 -0
  286. package/skills/egbe-os-product-demo-video/references/recording.md +32 -0
  287. package/skills/egbe-os-product-market-research/SKILL.md +159 -0
  288. package/skills/egbe-os-product-market-research/agents/openai.yaml +4 -0
  289. package/skills/egbe-os-product-market-research/references/catalog.v1.json +177 -0
  290. package/skills/egbe-os-product-market-research/references/config/channel-footprint-sources.v1.json +99 -0
  291. package/skills/egbe-os-product-market-research/references/config/creative-taxonomy.v1.json +367 -0
  292. package/skills/egbe-os-product-market-research/references/contracts/creative-video.md +75 -0
  293. package/skills/egbe-os-product-market-research/references/contracts/funnel-teardown.md +235 -0
  294. package/skills/egbe-os-product-market-research/references/contracts/geography-comparison.md +71 -0
  295. package/skills/egbe-os-product-market-research/references/contracts/lifecycle-capture.md +119 -0
  296. package/skills/egbe-os-product-market-research/references/contracts/research-artifacts.md +520 -0
  297. package/skills/egbe-os-product-market-research/references/contracts/walk-mechanics.v2.json +18 -0
  298. package/skills/egbe-os-product-market-research/references/prompts/acquisition-channels.md +137 -0
  299. package/skills/egbe-os-product-market-research/references/prompts/acquisition-channels.user.md +4 -0
  300. package/skills/egbe-os-product-market-research/references/prompts/competitive-landscape.md +118 -0
  301. package/skills/egbe-os-product-market-research/references/prompts/competitive-landscape.user.md +4 -0
  302. package/skills/egbe-os-product-market-research/references/prompts/demand-validation.md +154 -0
  303. package/skills/egbe-os-product-market-research/references/prompts/demand-validation.user.md +4 -0
  304. package/skills/egbe-os-product-market-research/references/prompts/market-size-and-dynamics.md +100 -0
  305. package/skills/egbe-os-product-market-research/references/prompts/market-size-and-dynamics.user.md +4 -0
  306. package/skills/egbe-os-product-market-research/references/prompts/pricing-and-monetization.md +126 -0
  307. package/skills/egbe-os-product-market-research/references/prompts/pricing-and-monetization.user.md +4 -0
  308. package/skills/egbe-os-product-market-research/references/prompts/target-audience.md +98 -0
  309. package/skills/egbe-os-product-market-research/references/prompts/target-audience.user.md +4 -0
  310. package/skills/egbe-os-product-market-research/references/prompts/unit-economics.md +217 -0
  311. package/skills/egbe-os-product-market-research/references/prompts/unit-economics.user.md +4 -0
  312. package/skills/egbe-os-product-market-research/references/prompts/value-proposition.md +113 -0
  313. package/skills/egbe-os-product-market-research/references/prompts/value-proposition.user.md +4 -0
  314. package/skills/egbe-os-product-market-research/references/workflows/acquisition-channels.md +27 -0
  315. package/skills/egbe-os-product-market-research/references/workflows/channel-footprint.md +163 -0
  316. package/skills/egbe-os-product-market-research/references/workflows/community-demand.md +100 -0
  317. package/skills/egbe-os-product-market-research/references/workflows/competitive-landscape.md +27 -0
  318. package/skills/egbe-os-product-market-research/references/workflows/competitor-ads.md +82 -0
  319. package/skills/egbe-os-product-market-research/references/workflows/competitor-set.md +300 -0
  320. package/skills/egbe-os-product-market-research/references/workflows/creative-patterns.md +228 -0
  321. package/skills/egbe-os-product-market-research/references/workflows/demand-validation.md +27 -0
  322. package/skills/egbe-os-product-market-research/references/workflows/fleet-prior.md +80 -0
  323. package/skills/egbe-os-product-market-research/references/workflows/funnel-teardown.md +184 -0
  324. package/skills/egbe-os-product-market-research/references/workflows/geography-comparison.md +84 -0
  325. package/skills/egbe-os-product-market-research/references/workflows/keyword-economics.md +122 -0
  326. package/skills/egbe-os-product-market-research/references/workflows/lifecycle-capture.md +218 -0
  327. package/skills/egbe-os-product-market-research/references/workflows/local-research.md +55 -0
  328. package/skills/egbe-os-product-market-research/references/workflows/market-size-and-dynamics.md +27 -0
  329. package/skills/egbe-os-product-market-research/references/workflows/preview.md +175 -0
  330. package/skills/egbe-os-product-market-research/references/workflows/pricing-and-monetization.md +27 -0
  331. package/skills/egbe-os-product-market-research/references/workflows/recommendations.md +35 -0
  332. package/skills/egbe-os-product-market-research/references/workflows/review-mining.md +76 -0
  333. package/skills/egbe-os-product-market-research/references/workflows/target-audience.md +27 -0
  334. package/skills/egbe-os-product-market-research/references/workflows/tiktok-reels-market-trends.md +46 -0
  335. package/skills/egbe-os-product-market-research/references/workflows/unit-economics.md +27 -0
  336. package/skills/egbe-os-product-market-research/references/workflows/value-proposition.md +27 -0
  337. package/skills/egbe-os-product-market-research/scripts/build-organic-trend-context.py +167 -0
  338. package/skills/egbe-os-product-market-research/scripts/build-preview-context.py +91 -0
  339. package/skills/egbe-os-product-market-research/scripts/build-research-query.py +225 -0
  340. package/skills/egbe-os-product-market-research/scripts/channel-footprint-model.py +294 -0
  341. package/skills/egbe-os-product-market-research/scripts/connection_identity.py +22 -0
  342. package/skills/egbe-os-product-market-research/scripts/creative-model.py +364 -0
  343. package/skills/egbe-os-product-market-research/scripts/creative-selection.py +113 -0
  344. package/skills/egbe-os-product-market-research/scripts/creative-semantics.py +365 -0
  345. package/skills/egbe-os-product-market-research/scripts/creative-video.py +542 -0
  346. package/skills/egbe-os-product-market-research/scripts/egbe_artifacts.py +24 -0
  347. package/skills/egbe-os-product-market-research/scripts/finalize-organic-trend-watch.py +304 -0
  348. package/skills/egbe-os-product-market-research/scripts/funnel-email-review.py +97 -0
  349. package/skills/egbe-os-product-market-research/scripts/funnel-model.py +966 -0
  350. package/skills/egbe-os-product-market-research/scripts/funnel_features.py +50 -0
  351. package/skills/egbe-os-product-market-research/scripts/geography-comparison-contract.py +172 -0
  352. package/skills/egbe-os-product-market-research/scripts/geography-comparison.py +169 -0
  353. package/skills/egbe-os-product-market-research/scripts/keyword-forecast.py +61 -0
  354. package/skills/egbe-os-product-market-research/scripts/keyword-locale-publication.py +136 -0
  355. package/skills/egbe-os-product-market-research/scripts/lifecycle-start.py +190 -0
  356. package/skills/egbe-os-product-market-research/scripts/persist-research-report.py +63 -0
  357. package/skills/egbe-os-product-market-research/scripts/research-artifact-io.py +281 -0
  358. package/skills/egbe-os-product-market-research/scripts/research-evidence.py +496 -0
  359. package/skills/egbe-os-product-market-research/scripts/research-policy.py +33 -0
  360. package/skills/egbe-os-product-market-research/scripts/research-section-runtime.py +343 -0
  361. package/skills/egbe-os-product-market-research/scripts/research-section-workflow.py +288 -0
  362. package/skills/egbe-os-product-market-research/scripts/research_integrity.py +122 -0
  363. package/skills/egbe-os-product-market-research/scripts/review-research-completion.py +306 -0
  364. package/skills/egbe-os-product-market-research/scripts/run-acquisition-channels.py +72 -0
  365. package/skills/egbe-os-product-market-research/scripts/run-channel-footprint.py +2258 -0
  366. package/skills/egbe-os-product-market-research/scripts/run-community-demand.py +1603 -0
  367. package/skills/egbe-os-product-market-research/scripts/run-competitive-landscape.py +66 -0
  368. package/skills/egbe-os-product-market-research/scripts/run-competitor-ads.py +1156 -0
  369. package/skills/egbe-os-product-market-research/scripts/run-competitor-set.py +2514 -0
  370. package/skills/egbe-os-product-market-research/scripts/run-creative-patterns.py +2042 -0
  371. package/skills/egbe-os-product-market-research/scripts/run-demand-validation.py +72 -0
  372. package/skills/egbe-os-product-market-research/scripts/run-fleet-prior.py +652 -0
  373. package/skills/egbe-os-product-market-research/scripts/run-funnel-teardown.py +493 -0
  374. package/skills/egbe-os-product-market-research/scripts/run-keyword-economics.py +1443 -0
  375. package/skills/egbe-os-product-market-research/scripts/run-lifecycle-capture.py +1543 -0
  376. package/skills/egbe-os-product-market-research/scripts/run-market-size-and-dynamics.py +66 -0
  377. package/skills/egbe-os-product-market-research/scripts/run-os-research.py +311 -0
  378. package/skills/egbe-os-product-market-research/scripts/run-pricing-and-monetization.py +71 -0
  379. package/skills/egbe-os-product-market-research/scripts/run-review-mining.py +1051 -0
  380. package/skills/egbe-os-product-market-research/scripts/run-target-audience.py +66 -0
  381. package/skills/egbe-os-product-market-research/scripts/run-unit-economics.py +71 -0
  382. package/skills/egbe-os-product-market-research/scripts/run-value-proposition.py +67 -0
  383. package/skills/egbe-os-product-market-research/scripts/upsert-markdown-section.py +156 -0
  384. package/skills/egbe-os-product-market-research/scripts/walk-funnels.py +249 -0
  385. package/skills/egbe-os-product-market-research/scripts/write-preview.py +710 -0
  386. package/skills/egbe-os-product-market-research/scripts/write-recommendations.py +272 -0
  387. package/skills/egbe-os-product-report/SKILL.md +150 -0
  388. package/skills/egbe-os-product-report/references/artifacts.md +84 -0
  389. package/skills/egbe-os-product-report/references/brief.md +34 -0
  390. package/skills/egbe-os-product-report/references/daily.md +76 -0
  391. package/skills/egbe-os-product-report/references/sources.md +68 -0
  392. package/skills/egbe-os-product-routines/SKILL.md +166 -0
  393. package/skills/egbe-os-product-routines/references/catalog.md +22 -0
  394. package/skills/egbe-os-product-routines/references/continuation-check.md +41 -0
  395. package/skills/egbe-os-product-routines/references/product-reporting.md +163 -0
  396. package/skills/egbe-os-product-routines/references/run-preset.md +32 -0
  397. package/skills/egbe-os-quickstart/scripts/egbe-curl.py +357 -0
  398. package/skills/egbe-os-quiz-funnel/SKILL.md +152 -0
  399. package/skills/egbe-os-quiz-funnel/agents/openai.yaml +4 -0
  400. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-engine.d.mts +224 -0
  401. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-engine.mjs +652 -0
  402. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-engine.test.mjs +764 -0
  403. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-history.d.mts +31 -0
  404. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-history.mjs +87 -0
  405. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-history.test.mjs +265 -0
  406. package/skills/egbe-os-quiz-funnel/assets/engine/quiz-reference.test.mjs +254 -0
  407. package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/QUIZ.md +195 -0
  408. package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/quiz.json +421 -0
  409. package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/quiz.public.json +369 -0
  410. package/skills/egbe-os-quiz-funnel/assets/examples/egbe-docs/product/quizzes/books-checkup/validation.json +21 -0
  411. package/skills/egbe-os-quiz-funnel/assets/reference/index.html +26 -0
  412. package/skills/egbe-os-quiz-funnel/assets/reference/quiz-bootstrap.js +31 -0
  413. package/skills/egbe-os-quiz-funnel/assets/reference/quiz-early-actions.mjs +11 -0
  414. package/skills/egbe-os-quiz-funnel/assets/reference/quiz-first-screen.mjs +32 -0
  415. package/skills/egbe-os-quiz-funnel/assets/reference/quiz-page.mjs +480 -0
  416. package/skills/egbe-os-quiz-funnel/assets/reference/quiz.css +264 -0
  417. package/skills/egbe-os-quiz-funnel/references/competitor-teardown.md +159 -0
  418. package/skills/egbe-os-quiz-funnel/references/conversion-handoff.md +156 -0
  419. package/skills/egbe-os-quiz-funnel/references/implementation.md +207 -0
  420. package/skills/egbe-os-quiz-funnel/references/inputs.md +37 -0
  421. package/skills/egbe-os-quiz-funnel/references/measurement.md +122 -0
  422. package/skills/egbe-os-quiz-funnel/references/spec-contract.md +335 -0
  423. package/skills/egbe-os-quiz-funnel/references/verification.md +101 -0
  424. package/skills/egbe-os-quiz-funnel/references/walk-mechanics.v2.json +18 -0
  425. package/skills/egbe-os-quiz-funnel/scripts/compile-quiz-spec.py +1869 -0
  426. package/skills/egbe-os-quiz-funnel/scripts/prepare-research-identity.py +66 -0
  427. package/skills/egbe-os-reddit-ads/SKILL.md +121 -0
  428. package/skills/egbe-os-reddit-ads/assets/static-banners/bold-statement/schema.json +41 -0
  429. package/skills/egbe-os-reddit-ads/assets/static-banners/bold-statement/template.html +106 -0
  430. package/skills/egbe-os-reddit-ads/assets/static-banners/data-proof/schema.json +61 -0
  431. package/skills/egbe-os-reddit-ads/assets/static-banners/data-proof/template.html +151 -0
  432. package/skills/egbe-os-reddit-ads/assets/static-banners/honest-breakdown/schema.json +91 -0
  433. package/skills/egbe-os-reddit-ads/assets/static-banners/honest-breakdown/template.html +185 -0
  434. package/skills/egbe-os-reddit-ads/assets/static-banners/question-hook/schema.json +51 -0
  435. package/skills/egbe-os-reddit-ads/assets/static-banners/question-hook/template.html +121 -0
  436. package/skills/egbe-os-reddit-ads/assets/static-banners/reddit-post-style/schema.json +87 -0
  437. package/skills/egbe-os-reddit-ads/assets/static-banners/reddit-post-style/template.html +212 -0
  438. package/skills/egbe-os-reddit-ads/references/creative/html-to-png-pipeline.md +123 -0
  439. package/skills/egbe-os-reddit-ads/references/creative/static-banner-qa.md +12 -0
  440. package/skills/egbe-os-reddit-ads/references/creative/static-banner-system.md +16 -0
  441. package/skills/egbe-os-reddit-ads/references/destination-requirements.md +36 -0
  442. package/skills/egbe-os-reddit-ads/references/runtime/api-reference.md +435 -0
  443. package/skills/egbe-os-reddit-ads/references/runtime/artifacts.md +57 -0
  444. package/skills/egbe-os-reddit-ads/references/runtime/monitoring.md +64 -0
  445. package/skills/egbe-os-reddit-ads/references/runtime/pixel-and-tracking.md +49 -0
  446. package/skills/egbe-os-reddit-ads/references/runtime/policies.md +19 -0
  447. package/skills/egbe-os-reddit-ads/references/runtime/shared-analytics-attribution.md +14 -0
  448. package/skills/egbe-os-reddit-ads/references/workflows/build-paused.md +35 -0
  449. package/skills/egbe-os-reddit-ads/references/workflows/launch-ready.md +19 -0
  450. package/skills/egbe-os-reddit-ads/references/workflows/launch.md +32 -0
  451. package/skills/egbe-os-reddit-ads/references/workflows/readiness.md +9 -0
  452. package/skills/egbe-os-reddit-ads/scripts/capture-ad.sh +178 -0
  453. package/skills/egbe-os-reddit-ads/scripts/validate-reddit-artifacts.py +187 -0
  454. package/skills/egbe-os-report-ui/SKILL.md +133 -0
  455. package/skills/egbe-os-report-ui/assets/egbe-wordmark.svg +9 -0
  456. package/skills/egbe-os-report-ui/assets/examples/components.html +417 -0
  457. package/skills/egbe-os-report-ui/assets/examples/editorial.html +209 -0
  458. package/skills/egbe-os-report-ui/assets/scaffold.html +179 -0
  459. package/skills/egbe-os-report-ui/references/components.md +209 -0
  460. package/skills/egbe-os-research/SKILL.md +125 -0
  461. package/skills/egbe-os-saas-unit-economics/SKILL.md +188 -0
  462. package/skills/egbe-os-scrape/SKILL.md +160 -0
  463. package/skills/egbe-os-search/SKILL.md +182 -0
  464. package/skills/egbe-os-search/references/google-places.md +81 -0
  465. package/skills/egbe-os-support/SKILL.md +149 -0
  466. package/skills/egbe-os-telemetry/SKILL.md +344 -0
  467. package/skills/egbe-os-telemetry/references/harnesses/claude-code.md +97 -0
  468. package/skills/egbe-os-telemetry/references/harnesses/codex.md +22 -0
  469. package/skills/egbe-os-telemetry/references/harnesses/hermes.md +39 -0
  470. package/skills/egbe-os-telemetry/references/harnesses/openclaw.md +139 -0
  471. package/skills/egbe-os-telemetry/references/harnesses/opencode.md +28 -0
  472. package/skills/egbe-os-tools/SKILL.md +180 -0
  473. package/skills/egbe-os-tools/references/theona.md +26 -0
  474. package/skills/egbe-os-wallet/SKILL.md +181 -0
  475. package/skills/egbe-setup/EGBE.md +484 -0
  476. package/skills/egbe-setup/SKILL.md +116 -0
  477. package/skills/egbe-setup/references/project.md +80 -0
  478. package/state.js +37 -0
  479. package/update.js +361 -0
@@ -0,0 +1,612 @@
1
+ #!/usr/bin/env python3
2
+ """Validate qualitative analysis and render deterministic report-section body."""
3
+
4
+ from __future__ import annotations
5
+
6
+ from pathlib import Path
7
+ from typing import Any, Iterable
8
+
9
+ from _contract import (
10
+ ANALYSIS_CONTRACT_VERSION,
11
+ CANONICAL_PROVIDER_RUNS,
12
+ ContractError,
13
+ SCHEMA_VERSION,
14
+ TERMINAL_PROVIDER_FAILURE_STATUSES,
15
+ parse_rfc3339,
16
+ read_json,
17
+ load_visual_analysis_instructions,
18
+ load_run_state,
19
+ require_sha256,
20
+ require_string,
21
+ resolve_relative,
22
+ sha256_bytes,
23
+ sha256_file,
24
+ VISUAL_EVIDENCE_METHOD,
25
+ canonical_frame_seconds,
26
+ validate_visual_analysis_receipt,
27
+ visual_analysis_receipt_path,
28
+ validate_context,
29
+ )
30
+ from _provider_inputs import validate_collection_window
31
+
32
+
33
+ def _require_list(value: Any, field: str) -> list[Any]:
34
+ if not isinstance(value, list):
35
+ raise ContractError(f"{field} must be a list")
36
+ return value
37
+
38
+
39
+ def _require_refs(
40
+ value: Any,
41
+ field: str,
42
+ videos: dict[str, dict[str, Any]],
43
+ ) -> list[str]:
44
+ refs = _require_list(value, field)
45
+ if not refs or not all(isinstance(item, str) and item for item in refs):
46
+ raise ContractError(f"{field} must contain observation IDs")
47
+ if len(refs) != len(set(refs)):
48
+ raise ContractError(f"{field} contains duplicate observation IDs")
49
+ for ref in refs:
50
+ if ref not in videos:
51
+ raise ContractError(f"{field} references unknown observation {ref}")
52
+ return refs
53
+
54
+
55
+ def _validate_normalized(root: Path) -> tuple[dict[str, Any], dict[str, dict[str, Any]]]:
56
+ path = root / "normalized/videos.json"
57
+ value = read_json(path)
58
+ if value.get("schema_version") != SCHEMA_VERSION:
59
+ raise ContractError("normalized schema_version must be 1")
60
+ if value.get("analysis_contract_version") != ANALYSIS_CONTRACT_VERSION:
61
+ raise ContractError("normalized analysis contract version mismatch")
62
+ require_sha256(value.get("source_manifest_sha256"), "source_manifest_sha256")
63
+ if value["source_manifest_sha256"] != sha256_file(root / "raw/manifest.json"):
64
+ raise ContractError("normalized source_manifest_sha256 mismatch")
65
+ selection_source = value.get("selection_source")
66
+ if not isinstance(selection_source, dict) or selection_source.get("path") != "normalized/selection.json":
67
+ raise ContractError("normalized.selection_source must reference normalized/selection.json")
68
+ selection_path = resolve_relative(
69
+ root, selection_source.get("path"), "normalized.selection_source.path"
70
+ )
71
+ selection_hash = require_sha256(
72
+ selection_source.get("sha256"), "normalized.selection_source.sha256"
73
+ )
74
+ if not selection_path.is_file() or sha256_file(selection_path) != selection_hash:
75
+ raise ContractError("normalized selection source hash mismatch")
76
+ selection = read_json(selection_path)
77
+ window = validate_collection_window(
78
+ validate_context(root / "context.json"), load_run_state(root).get("collection_window")
79
+ )
80
+ if selection.get("collection_window") != window or value.get("collection_window") != window:
81
+ raise ContractError("normalized collection window differs from the frozen selection")
82
+ window_start = parse_rfc3339(window["oldest_post_date"] + "T00:00:00Z", "collection lower bound")
83
+ window_end = parse_rfc3339(window["reference_at"], "collection reference_at")
84
+ manifest = read_json(root / "raw/manifest.json")
85
+ expected_discovery_sources = sorted(
86
+ [
87
+ {"path": item["path"], "sha256": item["sha256"]}
88
+ for item in manifest.get("datasets", [])
89
+ if isinstance(item, dict) and item.get("kind") == "discovery"
90
+ ],
91
+ key=lambda item: item["path"],
92
+ )
93
+ if (
94
+ selection.get("schema_version") != SCHEMA_VERSION
95
+ or selection.get("collection_epoch") != manifest.get("collection_epoch")
96
+ or selection.get("discovery_sources") != expected_discovery_sources
97
+ ):
98
+ raise ContractError("frozen selection provenance is invalid")
99
+ parse_rfc3339(value.get("generated_at"), "normalized.generated_at")
100
+ rows = _require_list(value.get("videos"), "normalized.videos")
101
+ by_id: dict[str, dict[str, Any]] = {}
102
+ for index, item in enumerate(rows):
103
+ if not isinstance(item, dict):
104
+ raise ContractError(f"normalized.videos[{index}] must be an object")
105
+ observation_id = require_string(
106
+ item.get("observation_id"), f"normalized.videos[{index}].observation_id"
107
+ )
108
+ if observation_id in by_id:
109
+ raise ContractError(f"duplicate normalized observation: {observation_id}")
110
+ require_string(item.get("url"), f"normalized.videos[{index}].url")
111
+ if not isinstance(item.get("selected_for_analysis"), bool):
112
+ raise ContractError(
113
+ f"normalized.videos[{index}].selected_for_analysis must be boolean"
114
+ )
115
+ posted_at = (parse_rfc3339(item["posted_at"], "observation posted_at")
116
+ if item.get("posted_at") is not None else None)
117
+ expected_window_status = ("unknown_date" if posted_at is None else
118
+ "in_window" if window_start <= posted_at <= window_end
119
+ else "outside_window")
120
+ if item.get("time_window_status") != expected_window_status:
121
+ raise ContractError("normalized observation time-window status is invalid")
122
+ if item["selected_for_analysis"] and expected_window_status != "in_window":
123
+ raise ContractError("selected observation is outside the time-window sample")
124
+ evidence = item.get("evidence")
125
+ if not isinstance(evidence, dict):
126
+ raise ContractError(f"normalized.videos[{index}].evidence must be an object")
127
+ video_path = evidence.get("video_path")
128
+ if video_path is not None and not isinstance(video_path, str):
129
+ raise ContractError(
130
+ f"normalized.videos[{index}].evidence.video_path must be a string or null"
131
+ )
132
+ frame_paths = evidence.get("frame_paths")
133
+ if not isinstance(frame_paths, list) or not all(
134
+ isinstance(path, str) and path for path in frame_paths
135
+ ):
136
+ raise ContractError(
137
+ f"normalized.videos[{index}].evidence.frame_paths must be a list of paths"
138
+ )
139
+ local_refs = ([video_path] if video_path else []) + frame_paths
140
+ hashes = evidence.get("artifact_sha256")
141
+ if not isinstance(hashes, dict) or set(hashes) != set(local_refs):
142
+ raise ContractError(
143
+ f"normalized.videos[{index}].evidence.artifact_sha256 must cover exactly local evidence"
144
+ )
145
+ for relative in local_refs:
146
+ artifact = resolve_relative(
147
+ root,
148
+ relative,
149
+ f"normalized.videos[{index}].evidence artifact",
150
+ )
151
+ expected_hash = require_sha256(
152
+ hashes.get(relative),
153
+ f"normalized.videos[{index}].evidence.artifact_sha256[{relative}]",
154
+ )
155
+ if not artifact.is_file() or sha256_file(artifact) != expected_hash:
156
+ raise ContractError(
157
+ f"normalized.videos[{index}] local evidence hash mismatch: {relative}"
158
+ )
159
+ preparation = evidence.get("visual_preparation")
160
+ if local_refs:
161
+ if not isinstance(preparation, dict):
162
+ raise ContractError(
163
+ f"normalized.videos[{index}] local visual evidence has no provider preparation proof"
164
+ )
165
+ if set(preparation) != {
166
+ "method",
167
+ "source_media_url_sha256",
168
+ "video_path",
169
+ "frame_samples",
170
+ }:
171
+ raise ContractError(
172
+ f"normalized.videos[{index}] visual preparation shape is invalid"
173
+ )
174
+ if preparation.get("method") != VISUAL_EVIDENCE_METHOD:
175
+ raise ContractError(
176
+ f"normalized.videos[{index}] visual preparation method is invalid"
177
+ )
178
+ media_url = require_string(
179
+ evidence.get("media_url"),
180
+ f"normalized.videos[{index}].evidence.media_url",
181
+ )
182
+ expected_media_url_hash = sha256_bytes(media_url.encode("utf-8"))
183
+ if preparation.get("source_media_url_sha256") != expected_media_url_hash:
184
+ raise ContractError(
185
+ f"normalized.videos[{index}] visual preparation media URL hash mismatch"
186
+ )
187
+ if preparation.get("video_path") != video_path or video_path is None:
188
+ raise ContractError(
189
+ f"normalized.videos[{index}] visual preparation video path mismatch"
190
+ )
191
+ frame_samples = preparation.get("frame_samples")
192
+ if not isinstance(frame_samples, list) or not frame_samples:
193
+ raise ContractError(
194
+ f"normalized.videos[{index}] visual preparation frame samples are empty"
195
+ )
196
+ prepared_frame_paths: list[str] = []
197
+ prior_second = -1.0
198
+ for sample_index, sample in enumerate(frame_samples):
199
+ if not isinstance(sample, dict) or set(sample) != {"path", "second"}:
200
+ raise ContractError(
201
+ f"normalized.videos[{index}] frame sample {sample_index} is invalid"
202
+ )
203
+ path_value = require_string(
204
+ sample.get("path"),
205
+ f"normalized.videos[{index}].frame_samples[{sample_index}].path",
206
+ )
207
+ second = sample.get("second")
208
+ if (
209
+ not isinstance(second, (int, float))
210
+ or isinstance(second, bool)
211
+ or float(second)
212
+ not in set(
213
+ canonical_frame_seconds(
214
+ item.get("metrics", {}).get("duration_seconds")
215
+ )
216
+ )
217
+ or float(second) <= prior_second
218
+ ):
219
+ raise ContractError(
220
+ f"normalized.videos[{index}] frame sample timing is invalid"
221
+ )
222
+ prior_second = float(second)
223
+ prepared_frame_paths.append(path_value)
224
+ if prepared_frame_paths != frame_paths:
225
+ raise ContractError(
226
+ f"normalized.videos[{index}] visual preparation frame paths mismatch"
227
+ )
228
+ elif preparation is not None:
229
+ raise ContractError(
230
+ f"normalized.videos[{index}] has visual preparation without local evidence"
231
+ )
232
+ comments = _require_list(
233
+ item.get("comments"), f"normalized.videos[{index}].comments"
234
+ )
235
+ comment_ids: set[str] = set()
236
+ for comment_index, comment in enumerate(comments):
237
+ comment_field = f"normalized.videos[{index}].comments[{comment_index}]"
238
+ if not isinstance(comment, dict):
239
+ raise ContractError(f"{comment_field} must be an object")
240
+ if set(comment) != {"comment_id", "text", "likes"}:
241
+ raise ContractError(f"{comment_field} has an invalid shape")
242
+ comment_id = require_string(
243
+ comment.get("comment_id"), f"{comment_field}.comment_id"
244
+ )
245
+ require_string(comment.get("text"), f"{comment_field}.text")
246
+ if comment_id in comment_ids:
247
+ raise ContractError(
248
+ f"normalized.videos[{index}] contains duplicate comment IDs"
249
+ )
250
+ comment_ids.add(comment_id)
251
+ by_id[observation_id] = item
252
+ selection_gaps = _require_list(
253
+ value.get("selection_gaps"), "normalized.selection_gaps"
254
+ )
255
+ if selection_gaps != sorted(selection_gaps) or not all(
256
+ isinstance(item, str) and item.strip() for item in selection_gaps
257
+ ):
258
+ raise ContractError("normalized.selection_gaps must be sorted non-empty strings")
259
+ if selection.get("selection_gaps") != selection_gaps:
260
+ raise ContractError("normalized selection gaps differ from frozen selection")
261
+ selected_ids = sorted(
262
+ observation_id
263
+ for observation_id, item in by_id.items()
264
+ if item["selected_for_analysis"]
265
+ )
266
+ if selection.get("selected_observation_ids") != selected_ids:
267
+ raise ContractError("normalized selected observations differ from frozen selection")
268
+ return value, by_id
269
+
270
+
271
+ def _validate_axis(
272
+ axis: Any,
273
+ field: str,
274
+ normalized: dict[str, Any],
275
+ *,
276
+ hook: bool,
277
+ receipt: dict[str, Any],
278
+ ) -> None:
279
+ if not isinstance(axis, dict):
280
+ raise ContractError(f"{field} must be an object")
281
+ status = axis.get("status")
282
+ if status not in {"observed", "unavailable"}:
283
+ raise ContractError(f"{field}.status must be observed or unavailable")
284
+ text = axis.get("text")
285
+ refs = axis.get("evidence_refs")
286
+ if not isinstance(text, str) or not isinstance(refs, list) or not all(
287
+ isinstance(item, str) and item for item in refs
288
+ ):
289
+ raise ContractError(f"{field} text/evidence_refs are invalid")
290
+ if status == "unavailable":
291
+ if text.strip() or refs:
292
+ raise ContractError(f"{field} unavailable axes cannot contain claims")
293
+ return
294
+ if not text.strip() or not refs:
295
+ raise ContractError(f"{field} observed axis needs text and evidence")
296
+
297
+ evidence = normalized["evidence"]
298
+ frames = set(evidence.get("frame_paths") or [])
299
+ video_path = evidence.get("video_path")
300
+ visual_refs = frames | ({video_path} if isinstance(video_path, str) and video_path else set())
301
+ transcript_available = bool(evidence.get("transcript"))
302
+ receipt_refs = {
303
+ frame["ref"] for frame in receipt["analysis"]["frames"]
304
+ }
305
+ if receipt["transcript"]["status"] == "available":
306
+ receipt_refs.add("transcript")
307
+ for ref in refs:
308
+ if ref != "transcript" and ref not in visual_refs:
309
+ raise ContractError(f"{field} cites evidence not attached to its observation: {ref}")
310
+ if ref == "transcript" and not transcript_available:
311
+ raise ContractError(f"{field} cites a missing transcript")
312
+ if ref not in receipt_refs:
313
+ raise ContractError(f"{field} cites evidence absent from multimodal analysis")
314
+ if not hook:
315
+ if not visual_refs.intersection(refs):
316
+ raise ContractError(f"{field} requires frame evidence")
317
+ return
318
+
319
+ modality = axis.get("modality")
320
+ if modality not in {"visual", "verbal", "mixed"}:
321
+ raise ContractError(f"{field}.modality must be visual, verbal, or mixed")
322
+ if modality in {"visual", "mixed"} and not visual_refs.intersection(refs):
323
+ raise ContractError(f"{field} visual claim requires frame evidence")
324
+ if modality in {"verbal", "mixed"} and "transcript" not in refs:
325
+ raise ContractError(f"{field} verbal claim requires transcript evidence")
326
+
327
+
328
+ def _validate_proof_reference(
329
+ proof: Any,
330
+ field: str,
331
+ normalized: dict[str, Any],
332
+ receipt: dict[str, Any],
333
+ ) -> None:
334
+ if not isinstance(proof, dict):
335
+ raise ContractError(f"{field} must be an object")
336
+ status = proof.get("status")
337
+ if status not in {"observed", "unavailable"}:
338
+ raise ContractError(f"{field}.status must be observed or unavailable")
339
+ claim = proof.get("claim")
340
+ mechanism = proof.get("mechanism")
341
+ refs = proof.get("evidence_refs")
342
+ if not isinstance(claim, str) or not isinstance(mechanism, str):
343
+ raise ContractError(f"{field} claim/mechanism must be strings")
344
+ if not isinstance(refs, list) or not all(
345
+ isinstance(item, str) and item for item in refs
346
+ ):
347
+ raise ContractError(f"{field}.evidence_refs must be a list of strings")
348
+ if status == "unavailable":
349
+ if claim.strip() or mechanism.strip() or refs:
350
+ raise ContractError(f"{field} unavailable proof cannot contain claims")
351
+ return
352
+ if not claim.strip() or not mechanism.strip() or not refs:
353
+ raise ContractError(f"{field} observed proof needs claim, mechanism, and evidence")
354
+
355
+ evidence = normalized["evidence"]
356
+ frames = set(evidence.get("frame_paths") or [])
357
+ video_path = evidence.get("video_path")
358
+ attached_refs = frames | (
359
+ {video_path} if isinstance(video_path, str) and video_path else set()
360
+ )
361
+ if evidence.get("transcript"):
362
+ attached_refs.add("transcript")
363
+ if normalized.get("caption"):
364
+ attached_refs.add("caption")
365
+ if any(ref not in attached_refs for ref in refs):
366
+ raise ContractError(f"{field} cites evidence not attached to its observation")
367
+ receipt_refs = {
368
+ frame["ref"] for frame in receipt["analysis"]["frames"]
369
+ }
370
+ if receipt["transcript"]["status"] == "available":
371
+ receipt_refs.add("transcript")
372
+ if normalized.get("caption"):
373
+ receipt_refs.add("caption")
374
+ if any(ref not in receipt_refs for ref in refs):
375
+ raise ContractError(f"{field} cites evidence absent from multimodal analysis")
376
+
377
+
378
+ def _validate_evidence_statement(
379
+ value: Any,
380
+ field: str,
381
+ normalized: dict[str, Any],
382
+ receipt: dict[str, Any],
383
+ *,
384
+ allowed_modalities: set[str],
385
+ ) -> None:
386
+ if not isinstance(value, dict):
387
+ raise ContractError(f"{field} must be an object")
388
+ status = value.get("status")
389
+ text = value.get("text")
390
+ modality = value.get("modality")
391
+ refs = value.get("evidence_refs")
392
+ if status not in {"observed", "unavailable"}:
393
+ raise ContractError(f"{field}.status must be observed or unavailable")
394
+ if not isinstance(text, str) or not isinstance(refs, list) or not all(
395
+ isinstance(ref, str) and ref for ref in refs
396
+ ):
397
+ raise ContractError(f"{field} text/evidence_refs are invalid")
398
+ if status == "unavailable":
399
+ if text.strip() or modality is not None or refs:
400
+ raise ContractError(f"{field} unavailable statement cannot contain a claim")
401
+ return
402
+ if not text.strip() or not refs or len(refs) != len(set(refs)):
403
+ raise ContractError(f"{field} observed statement needs text and evidence")
404
+ if modality not in allowed_modalities:
405
+ raise ContractError(f"{field}.modality is invalid")
406
+
407
+ frame_refs = {frame["ref"] for frame in receipt["analysis"]["frames"]}
408
+ transcript_available = receipt["transcript"]["status"] == "available"
409
+ caption_available = bool(normalized.get("caption"))
410
+ allowed_refs = set(frame_refs)
411
+ if transcript_available:
412
+ allowed_refs.add("transcript")
413
+ if caption_available:
414
+ allowed_refs.add("caption")
415
+ if any(ref not in allowed_refs for ref in refs):
416
+ raise ContractError(f"{field} cites unavailable evidence")
417
+ has_visual = bool(set(refs) & frame_refs)
418
+ has_verbal = "transcript" in refs
419
+ has_caption = "caption" in refs
420
+ expected = {
421
+ "visual": (True, False, False),
422
+ "verbal": (False, True, False),
423
+ "mixed": (True, True, False),
424
+ "caption": (False, False, True),
425
+ }[modality]
426
+ if (has_visual, has_verbal, has_caption) != expected:
427
+ raise ContractError(f"{field} evidence refs do not match its modality")
428
+
429
+
430
+ def load_and_validate_analysis(root: Path) -> tuple[dict[str, Any], dict[str, dict[str, Any]]]:
431
+ normalized_payload, normalized = _validate_normalized(root)
432
+ analysis = read_json(root / "analysis.json")
433
+ if analysis.get("schema_version") != SCHEMA_VERSION:
434
+ raise ContractError("analysis.schema_version must be 1")
435
+ if analysis.get("analysis_contract_version") != ANALYSIS_CONTRACT_VERSION:
436
+ raise ContractError("analysis contract version mismatch")
437
+ require_sha256(analysis.get("source_normalized_sha256"), "source_normalized_sha256")
438
+ if analysis["source_normalized_sha256"] != sha256_file(root / "normalized/videos.json"):
439
+ raise ContractError("analysis source_normalized_sha256 mismatch")
440
+ parse_rfc3339(analysis.get("generated_at"), "analysis.generated_at")
441
+ require_string(analysis.get("summary"), "analysis.summary")
442
+ selected = {key for key, value in normalized.items() if value["selected_for_analysis"]}
443
+ analyzed: dict[str, dict[str, Any]] = {}
444
+ required_gaps = set(normalized_payload["selection_gaps"])
445
+ for key, run in load_run_state(root)["provider_runs"].items():
446
+ status = str(run.get("status", "")).upper() if isinstance(run, dict) else ""
447
+ if status == "SUCCEEDED":
448
+ continue
449
+ if status not in TERMINAL_PROVIDER_FAILURE_STATUSES:
450
+ raise ContractError(f"provider collection {key} is running or uncertain")
451
+ required_gaps.add(f"Provider collection {key} ended with {status}.")
452
+ instructions = load_visual_analysis_instructions()
453
+ for index, item in enumerate(_require_list(analysis.get("videos"), "analysis.videos")):
454
+ field = f"analysis.videos[{index}]"
455
+ if not isinstance(item, dict):
456
+ raise ContractError(f"{field} must be an object")
457
+ observation_id = require_string(item.get("observation_id"), f"{field}.observation_id")
458
+ if observation_id not in selected or observation_id in analyzed:
459
+ raise ContractError(f"{field} references unselected or duplicate observation")
460
+ source = normalized[observation_id]
461
+ if item.get("url") != source["url"]:
462
+ raise ContractError(f"{field}.url does not match normalized evidence")
463
+ receipt_path = visual_analysis_receipt_path(root, observation_id)
464
+ # Caption/metrics/comment analysis does not require a vision request.
465
+ receipt = {"analysis": {"frames": []}, "transcript": {"status": "unavailable"}}
466
+ if receipt_path.exists():
467
+ receipt = validate_visual_analysis_receipt(root, source, instructions=instructions)
468
+ if item.get("multimodal_receipt_sha256") != sha256_file(receipt_path):
469
+ raise ContractError(f"{field}.multimodal_receipt_sha256 mismatch")
470
+ required_gaps.update(receipt["analysis"]["gaps"])
471
+ elif "multimodal_receipt_sha256" in item:
472
+ raise ContractError(f"{field} references a missing multimodal receipt")
473
+ for axis in ("thumb_stop", "hook"):
474
+ if axis in item:
475
+ _validate_axis(item[axis], f"{field}.{axis}", source,
476
+ hook=axis == "hook", receipt=receipt)
477
+ if "proof_reference" in item:
478
+ _validate_proof_reference(item["proof_reference"], f"{field}.proof_reference", source, receipt)
479
+ for axis in ("format", "message", "cta"):
480
+ if axis in item:
481
+ _validate_evidence_statement(
482
+ item[axis], f"{field}.{axis}", source, receipt,
483
+ allowed_modalities={"visual", "verbal", "mixed", "caption"},
484
+ )
485
+ if "sound" in item and item["sound"] != source.get("sound"):
486
+ raise ContractError(f"{field}.sound must equal normalized sound metadata")
487
+ seen_comments: set[str] = set()
488
+ comments = {comment["comment_id"]: comment for comment in source["comments"]}
489
+ for number, insight in enumerate(_require_list(item.get("comment_analysis", []), f"{field}.comment_analysis")):
490
+ label = f"{field}.comment_analysis[{number}]"
491
+ if not isinstance(insight, dict) or not {"comment_id", "relevance", "reason"} <= set(insight) <= {"comment_id", "relevance", "reason", "insight"}:
492
+ raise ContractError(f"{label} has an invalid shape")
493
+ comment_id = require_string(insight.get("comment_id"), f"{label}.comment_id")
494
+ if comment_id not in comments or comment_id in seen_comments:
495
+ raise ContractError(f"{label} references absent or duplicate comment")
496
+ seen_comments.add(comment_id)
497
+ if insight.get("relevance") not in {"relevant", "uncertain", "irrelevant"}:
498
+ raise ContractError(f"{label}.relevance is invalid")
499
+ require_string(insight.get("reason"), f"{label}.reason")
500
+ if insight["relevance"] == "relevant":
501
+ require_string(insight.get("insight"), f"{label}.insight")
502
+ elif insight.get("insight") not in (None, ""):
503
+ raise ContractError(f"{label}.insight must be empty unless the comment is relevant")
504
+ analyzed[observation_id] = item
505
+ synthesis = analysis.get("synthesis")
506
+ if not isinstance(synthesis, dict) or set(synthesis) != {"findings", "adaptations"}:
507
+ raise ContractError("analysis.synthesis must contain findings and adaptations")
508
+ for index, finding in enumerate(_require_list(synthesis["findings"], "synthesis.findings")):
509
+ field = f"synthesis.findings[{index}]"
510
+ if not isinstance(finding, dict) or set(finding) != {"text", "supporting_evidence_refs"}:
511
+ raise ContractError(f"{field} has an invalid shape")
512
+ require_string(finding["text"], f"{field}.text")
513
+ refs = _require_list(finding["supporting_evidence_refs"], f"{field}.supporting_evidence_refs")
514
+ if not refs or not all(isinstance(ref, str) for ref in refs) or len(refs) != len(set(refs)):
515
+ raise ContractError(f"{field} needs unique evidence references")
516
+ for ref in refs:
517
+ observation_id, separator, axis = ref.rpartition("#")
518
+ if not separator or observation_id not in analyzed:
519
+ raise ContractError(f"{field} cites an unknown or unanalyzed observation")
520
+ source, row = normalized[observation_id], analyzed[observation_id]
521
+ if axis == "caption":
522
+ present = bool(source.get("caption"))
523
+ elif axis == "metrics":
524
+ present = any(value is not None for value in source.get("metrics", {}).values())
525
+ elif axis == "sound":
526
+ present = any(source.get("sound", {}).values())
527
+ elif axis.startswith("comment:"):
528
+ comment_id = axis.removeprefix("comment:")
529
+ present = any(comment["comment_id"] == comment_id for comment in source["comments"])
530
+ else:
531
+ present = axis in {"thumb_stop", "hook", "proof_reference", "format", "message", "cta"} and row.get(axis, {}).get("status") == "observed"
532
+ if not present:
533
+ raise ContractError(f"{field} cites unavailable or unobserved evidence: {ref}")
534
+ for index, adaptation in enumerate(_require_list(synthesis["adaptations"], "synthesis.adaptations")):
535
+ field = f"synthesis.adaptations[{index}]"
536
+ if not isinstance(adaptation, dict) or set(adaptation) != {"name", "text", "reason", "source_observation_ids"}:
537
+ raise ContractError(f"{field} has an invalid shape")
538
+ for name in ("name", "text", "reason"):
539
+ require_string(adaptation.get(name), f"{field}.{name}")
540
+ _require_refs(adaptation.get("source_observation_ids"), f"{field}.source_observation_ids", analyzed)
541
+ gaps = _require_list(analysis.get("evidence_gaps"), "analysis.evidence_gaps")
542
+ if not all(isinstance(gap, str) and gap.strip() for gap in gaps):
543
+ raise ContractError("analysis.evidence_gaps must contain non-empty strings")
544
+ if not required_gaps.issubset(gaps):
545
+ raise ContractError("analysis.evidence_gaps must preserve selection and media evidence gaps, including failed collection")
546
+ return analysis, normalized
547
+
548
+
549
+ def coverage(analysis: dict[str, Any], normalized: dict[str, dict[str, Any]]) -> dict[str, Any]:
550
+ selected = {key for key, item in normalized.items() if item["selected_for_analysis"]}
551
+ analyzed = {item["observation_id"] for item in analysis["videos"]}
552
+ gaps = list(analysis["evidence_gaps"])
553
+ failed_collection = bool(set(gaps) & {
554
+ f"Provider collection {key} ended with {status}."
555
+ for key in CANONICAL_PROVIDER_RUNS for status in TERMINAL_PROVIDER_FAILURE_STATUSES
556
+ })
557
+ gaps.extend(f"{observation_id}: selected observation was not analyzed"
558
+ for observation_id in sorted(selected - analyzed))
559
+ for item in analysis["videos"]:
560
+ for axis in ("thumb_stop", "hook", "proof_reference", "format", "message", "cta"):
561
+ if item.get(axis, {}).get("status") == "unavailable":
562
+ gaps.append(f"{item['observation_id']}: requested {axis.replace('_', ' ')} evidence unavailable")
563
+ if not normalized:
564
+ gaps.append("The collected provider results contain no matching observations.")
565
+ if not normalized and not failed_collection:
566
+ status = "no_data"
567
+ else:
568
+ status = "partial" if gaps else "complete"
569
+ return {
570
+ "status": status,
571
+ "collected_count": len(normalized),
572
+ "selected_count": len(selected),
573
+ "analyzed_count": len(analyzed),
574
+ "gaps": sorted(set(gaps)),
575
+ }
576
+
577
+
578
+ def _sources(refs: Iterable[str], normalized: dict[str, dict[str, Any]]) -> str:
579
+ return ", ".join(f"[@{normalized[ref]['account']['handle']}]({normalized[ref]['url']})"
580
+ for ref in refs)
581
+
582
+
583
+ def render_body(analysis: dict[str, Any], normalized: dict[str, dict[str, Any]]) -> str:
584
+ result_coverage = coverage(analysis, normalized)
585
+ lines = ["### Findings", "", analysis["summary"], ""]
586
+ for finding in analysis["synthesis"]["findings"]:
587
+ ids = list(dict.fromkeys(ref.rpartition("#")[0] for ref in finding["supporting_evidence_refs"]))
588
+ lines.append(f"- {finding['text']} Sources: {_sources(ids, normalized)}")
589
+ if analysis["synthesis"]["adaptations"]:
590
+ lines.extend(["", "### Possible adaptations", ""])
591
+ for item in analysis["synthesis"]["adaptations"]:
592
+ lines.extend([f"- **{item['name']}:** {item['text']}",
593
+ f" - Why: {item['reason']}",
594
+ f" - Source references: {_sources(item['source_observation_ids'], normalized)}"])
595
+ relevant_comments = [
596
+ (row["observation_id"], insight)
597
+ for row in analysis["videos"] for insight in row.get("comment_analysis", [])
598
+ if insight["relevance"] == "relevant"
599
+ ]
600
+ if relevant_comments:
601
+ lines.extend(["", "### Audience language", ""])
602
+ for observation_id, insight in relevant_comments:
603
+ source = normalized[observation_id]
604
+ comment = next(comment for comment in source["comments"] if comment["comment_id"] == insight["comment_id"])
605
+ lines.append(f"- “{comment['text']}” — {insight['insight']}. Source: {_sources([observation_id], normalized)}")
606
+ lines.extend(["", "### Evidence coverage", "",
607
+ f"Collected {result_coverage['collected_count']} observations; "
608
+ f"selected {result_coverage['selected_count']}; analyzed {result_coverage['analyzed_count']}.",
609
+ f"Coverage: {result_coverage['status']}."])
610
+ if result_coverage["gaps"]:
611
+ lines.extend(["", *[f"- {gap}" for gap in result_coverage["gaps"]]])
612
+ return "\n".join(lines).rstrip() + "\n"