@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,496 @@
1
+ """Receipt-backed research inputs and bounded, provider-safe projections."""
2
+ from __future__ import annotations
3
+
4
+ import sys as _artifact_sys
5
+ from pathlib import Path as _ArtifactPath
6
+ _artifact_sys.path.insert(0, str(_ArtifactPath(__file__).resolve().parent))
7
+ from egbe_artifacts import artifact_path as _artifact_path
8
+
9
+ import hashlib
10
+ import importlib.util
11
+ import json
12
+ import re
13
+ import sys
14
+ from collections import defaultdict
15
+ from pathlib import Path
16
+
17
+ RUNTIME = Path(_artifact_path("egbe-docs/research/market/work"))
18
+ EVIDENCE = Path(_artifact_path("egbe-docs/research/market/evidence"))
19
+ MEASURED = {
20
+ "keyword_economics": "keyword-economics.json", "competitor_set": "competitors.json",
21
+ "channel_footprint": "channel-footprint.json", "creative_patterns": "creative-patterns.json",
22
+ "funnel_teardown": "funnel-teardown.json",
23
+ "lifecycle_capture": "lifecycle-capture.json", "competitor_ads": "competitor-ads.json",
24
+ "review_mining": "review-mining.json", "community_demand": "community-demand.json",
25
+ "fleet_prior": "fleet-prior.json",
26
+ }
27
+ INPUTS = {
28
+ "market_size_dynamics": ("keyword_economics", "community_demand"),
29
+ "target_audience": ("review_mining", "community_demand"),
30
+ "competitive_landscape": ("keyword_economics", "competitor_set", "competitor_ads", "review_mining"),
31
+ "value_proposition": ("review_mining", "community_demand", "competitor_ads", "funnel_teardown"),
32
+ "pricing_monetization": ("competitor_ads", "review_mining", "lifecycle_capture"),
33
+ "acquisition_channels": ("keyword_economics", "competitor_set", "channel_footprint", "creative_patterns", "funnel_teardown", "lifecycle_capture", "competitor_ads", "community_demand"),
34
+ "demand_validation": ("keyword_economics", "competitor_ads", "review_mining", "community_demand"),
35
+ "unit_economics": ("keyword_economics",),
36
+ }
37
+ # Only public measured facts. Fleet cases/private product context never pass here.
38
+ PUBLIC_FIELDS = frozenset({
39
+ "type", "keyword", "locale_key", "locale", "domain", "kind", "url", "source", "sources", "platform",
40
+ "search_volume", "cpc", "cpc_low", "cpc_high", "competition", "intent_signal", "free_edu_intent",
41
+ "paid_by", "title", "description", "text", "quote", "query", "stars", "rating", "price",
42
+ "pricing_mentions", "billing_pricing_complaint", "switched_reason", "reason", "tier", "found_via",
43
+ "excerpt", "date", "served_days", "status", "is_active", "presence_span_days",
44
+ "love_theme", "hate_theme", "switched_from", "verified", "reviewer_country", "company_segment_code",
45
+ "categories", "product_context", "has_dollar_amount", "created", "sample_url",
46
+ "serp_paid_appearances", "serp_organic_appearances", "score", "paid_results", "organic_results",
47
+ "paid_advertisers", "organic_top", "ads_count", "se_results_count", "response_status",
48
+ "observed_on", "retrieved_on", "published_at", "first_seen", "last_seen", "active_days",
49
+ "bid", "match", "average_cpc", "monthly_clicks_at_bid", "monthly_cost_at_bid",
50
+ "test_budget_usd", "est_clicks_within_test_budget", "simulated_keywords", "budget_covers_full_month",
51
+ # Competitor set rows: tiering outcome and discovery provenance.
52
+ "rank", "name", "competitor_tier", "icp_match", "jtbd_match", "decided_by", "source_count",
53
+ "serp_paid_hits", "serp_organic_hits", "search_hits", "overlap_intersections", "listed_for",
54
+ "retrieved", "candidates", "listicles", "spyfu_ppc_hits", "spyfu_common_keywords",
55
+ # Competitor set rows: the offer-led profile, composition and ad check.
56
+ "round", "query_kind", "provenance", "provenance_detail", "found_in", "brand_hits", "keyword_ads_hits",
57
+ "listicle_pages", "relationship_hits", "offer_url", "offer_class", "offer_match", "price_text", "price_usd",
58
+ "price_band", "duration", "buyer", "job", "operating", "marketplace", "evidence_urls", "comparable",
59
+ "ad_activity", "ad_evidence", "selection_group", "selection", "override_reason", "reviewed", "reason_code",
60
+ "profiled",
61
+ # Channel footprint rows: library presence, tags, traffic split, partner signals, history, ranking.
62
+ "channel", "label", "market_scope", "matched_ads", "active_ads", "oldest_days", "latest_seen", "formats",
63
+ "present", "verified_by", "note", "fetch_status", "http_status", "via", "gtm_containers", "tags_detected",
64
+ "channels_detected", "tools_reported", "paid_channel", "share_pct", "visits_monthly", "hits", "urls",
65
+ "unavailable", "first_archived", "months_with_snapshots_24m", "window_months", "detail",
66
+ "competitors_present", "competitors_total", "present_domains", "evidence_kinds", "active_ads_total",
67
+ "max_oldest_days", "avg_share_pct", "why", "formats_recent", "tag_managers", "linkedin_company",
68
+ "archived_host", "distinct_versions_24m", "months_archived_24m", "versions_capped",
69
+ "target_country", "countries", "relevance", "relevance_reason", "current_presence", "native_duration_available",
70
+ "duration_scope", "consideration_status", "needs_campaign_data", "observed_domains_by_role", "active_domains", "active_competitors", "days_since_last_delivery",
71
+ "sampling", "stopped_ads", "unknown_ads", "policy_sha256",
72
+ # Channel footprint SpyFu rows: modeled Google Ads spend per competitor.
73
+ "country", "found", "months_checked", "months_with_spend", "spending_now", "latest_month",
74
+ "latest_monthly_budget_usd", "latest_monthly_paid_clicks", "latest_paid_keywords",
75
+ "avg_monthly_budget_usd", "max_monthly_budget_usd", "est_monthly_budget_usd",
76
+ # Creative patterns rows, compact: patterns, labels and short excerpts, never full ad copy.
77
+ "creative_id", "headline", "cta_intent", "landing_host", "format_kind", "running_at_capture",
78
+ "longevity_status", "variants", "labels", "texts", "offer", "pattern_level", "pattern_key", "pattern_status",
79
+ "convergence", "recurring", "competitors", "dated_competitors", "running_competitors", "creatives",
80
+ "max_served_days", "examples", "creative_type", "format_detail", "message_family", "angles",
81
+ "members", "source_members", "semantic_context_sha256", "category_dictionary_sha256", "language", "language_status", "language_allowed",
82
+ # Funnel teardown rows: landing page facts, walked screens and funnel patterns (full page text never).
83
+ "campaign_id", "campaign_ids", "funnel_id", "funnel_ids", "walk_id", "walk_ref", "walk_refs", "path_id", "role",
84
+ "observation_status", "advertising_observation_status", "research_comparable", "research_comparable_campaign_ids", "running_refs", "dated_refs", "destination_refs", "observed_outcome", "partial", "unknown", "stop_reason", "features", "positions",
85
+ "email_review", "email_events", "funnel_types", "creative_links", "dated_convergence", "observed_convergence", "selected_campaigns_total", "known_campaigns_total", "campaigns_with", "unknown_campaigns", "share",
86
+ "cluster_id", "address", "host", "path", "origin", "discovered_as", "platforms", "running_creatives", "proven_creatives",
87
+ "creative_ids", "weight", "final_host", "final_path", "redirected", "redirected_off_site", "page_type", "rendered_client_side",
88
+ "headline_words", "meta_description", "primary_cta", "cta_labels", "forms", "form_fields", "asks_email", "asks_password",
89
+ "asks_phone", "amounts_mentioned", "free_mentions", "trust_signals", "viewport_meta", "word_count", "message_match",
90
+ "matched_terms", "walk_candidate", "walked_on", "viewport", "answers_used", "ends_in", "stopped_at", "screens", "screens_count",
91
+ "question_screens", "proof_screens", "loader_screens", "contact_request_at", "result_at", "result_before_contact",
92
+ "automatic_advance_share", "progress_indicator", "skip_control", "pattern", "walks_with", "walks_total",
93
+ # Lifecycle capture rows: subscriptions and harvested sequences; the alias and message ids stay private.
94
+ "entry_url", "entry_host", "subscribed_on", "confirmed", "unsubscribed_on", "harvested_on", "days_covered", "messages",
95
+ "messages_per_week", "first_message_day", "first_welcome_day", "is_welcome", "last_message_day", "median_gap_days", "confirmations", "offers", "first_offer_day",
96
+ "max_discount_percent", "deadlines", "nudges", "prices", "sender_domains", "unsubscribe_present", "subjects", "received_at",
97
+ "day_offset", "hour_utc", "sender_domain", "subject", "is_confirmation", "is_offer", "discount_percent", "listing_truncated",
98
+ "free_mention", "deadline", "unsubscribe_link", "links", "competitors_with",
99
+ })
100
+
101
+
102
+ def load_script(name: str):
103
+ spec = importlib.util.spec_from_file_location("pmr_" + name.replace("-", "_"), Path(__file__).with_name(name + ".py"))
104
+ module = importlib.util.module_from_spec(spec)
105
+ spec.loader.exec_module(module)
106
+ return module
107
+
108
+
109
+ def read_json(path: Path) -> dict:
110
+ value = json.loads(path.read_text())
111
+ if not isinstance(value, dict):
112
+ raise ValueError(f"Not a JSON object: {path.name}")
113
+ return value
114
+
115
+
116
+ def sha(path: Path) -> str:
117
+ return hashlib.sha256(path.read_bytes()).hexdigest()
118
+
119
+
120
+ def catalog() -> dict[str, dict]:
121
+ data = read_json(Path(__file__).parent.parent / "references/catalog.v1.json")
122
+ return {s["id"]: s for s in data["sections"]}
123
+
124
+
125
+ def report_body(workspace: Path, heading: str) -> str:
126
+ text = (workspace / _artifact_path("egbe-docs/research/market/full-report.md")).read_text()
127
+ offsets = load_script("upsert-markdown-section")._h2_offsets(text)
128
+ found = [(i, offset) for i, (name, offset) in enumerate(offsets) if name == heading]
129
+ if len(found) != 1:
130
+ raise ValueError("Missing or duplicate materialized report section")
131
+ index, start = found[0]
132
+ end = offsets[index + 1][1] if index + 1 < len(offsets) else len(text)
133
+ return text[start:end].split("\n", 1)[1].strip()
134
+
135
+
136
+ def _publication(state: dict) -> None:
137
+ if state.get("publication_mode") != "local":
138
+ raise ValueError("Missing local publication proof; finish publication, not recollection")
139
+
140
+
141
+ def _bound_file(workspace: Path, state: dict, path: Path, name: str) -> Path:
142
+ if state.get(name + "_path") != path.as_posix() or state.get(name + "_sha256") != sha(workspace / path):
143
+ raise ValueError(f"{name} path/hash mismatch; rerun the owning workflow")
144
+ return workspace / path
145
+
146
+
147
+ def _ai(workspace: Path, section: str, state: dict) -> tuple[str, dict]:
148
+ root = workspace / RUNTIME / section
149
+ if state.get("schema_version") != 3 or not state.get("job_id"):
150
+ raise ValueError("Unsupported AI receipt")
151
+ for field, filename in (("query", "query.md"), ("system_prompt", "system-prompt.md"), ("result", "result.md")):
152
+ if state.get(field + "_sha256") != sha(root / filename):
153
+ raise ValueError(f"AI {field} hash mismatch")
154
+ if state.get("result_path") != (RUNTIME / section / "result.md").as_posix():
155
+ raise ValueError("AI result path mismatch")
156
+ review = read_json(root / "completion-review.json")
157
+ if (review.get("schema_version") != 1 or review.get("section_id") != section
158
+ or any(review.get(k) != state.get(k) for k in ("job_id", "query_sha256", "system_prompt_sha256", "result_sha256"))
159
+ or review.get("classification") not in {"complete", "uncertain"}
160
+ or type(review.get("retry_count")) is not int or review["retry_count"] not in (0, 1)
161
+ or review.get("retry_exhausted") is not False):
162
+ raise ValueError("AI completion review is missing or no longer matches")
163
+ if state.get("input_provenance_sha256") != sha(root / "input-provenance.json"):
164
+ raise ValueError("AI input provenance does not match its receipt")
165
+ provenance = read_json(root / "input-provenance.json")
166
+ load_script("research-artifact-io").verify_context(workspace, section, provenance.get("research_context"))
167
+ if provenance.get("query_sha256") != state["query_sha256"]:
168
+ raise ValueError("AI input provenance is stale; rerun explicitly if new research is authorized")
169
+ for source, proof in provenance.get("measured_inputs", {}).items():
170
+ if proof.get("evidence_sha256") and (source not in MEASURED or sha(workspace / EVIDENCE / MEASURED[source]) != proof["evidence_sha256"]):
171
+ raise ValueError("Measured input changed since this AI result; review before explicitly rerunning")
172
+ if proof.get("status") == "completed" and inspect_section(workspace, source)["status"] != "completed":
173
+ raise ValueError("Measured input is no longer current/published; review before explicitly rerunning")
174
+ publication = read_json(root / "publication.json")
175
+ if publication.get("result_sha256") != state["result_sha256"]:
176
+ raise ValueError("AI result has not been published")
177
+ _publication(publication)
178
+ body = (root / "result.md").read_text().strip()
179
+ if not body or body.lower().startswith("unverified hypothesis:") or not re.search(r"https?://[^\s)>]+", body):
180
+ raise ValueError("AI result is not a sourced completed section")
181
+ return body, {"result_sha256": state["result_sha256"], "inputs": provenance}
182
+
183
+
184
+ def inspect_section(workspace: Path, section: str, *, require_materialized: bool = True) -> dict:
185
+ """Absence is pending, not zero evidence. Invalid receipts never prove completion."""
186
+ specs = catalog()
187
+ if section not in specs:
188
+ raise ValueError(f"Unknown research section: {section}")
189
+ root = workspace / RUNTIME / section
190
+ filename = "integration-receipt.json" if section == "organic_trend_watch" else "request.json"
191
+ if not (root / filename).exists():
192
+ return {"status": "pending", "reason": "No published receipt yet"}
193
+ try:
194
+ state = read_json(root / filename)
195
+ if state.get("status") in {"pending", "running", "submitted", "processing", "awaiting_relevance", "awaiting_collection", "awaiting_finalize", "needs_approval", "needs_email", "budget_exhausted", "submission_outcome_unknown"}:
196
+ return {"status": "pending", "reason": "Collection/publication still pending"}
197
+ valid_statuses = {"completed", "partial", "no_data"} if section == "organic_trend_watch" else {"completed"}
198
+ if state.get("status") not in valid_statuses or state.get("error") not in (None, ""):
199
+ raise ValueError("Workflow failed, incomplete or not published")
200
+ if section in MEASURED:
201
+ if state.get("schema_version") != 1 or state.get("section_id") != section:
202
+ raise ValueError("Wrong measured section receipt")
203
+ load_script("research-artifact-io").verify_context(workspace, section, state.get("research_context"))
204
+ _publication(state)
205
+ path = EVIDENCE / MEASURED[section]
206
+ data = read_json(_bound_file(workspace, state, path, "evidence"))
207
+ accepted_versions = (1, 2) if section in ("channel_footprint", "creative_patterns", "funnel_teardown") else (2,) if section == "keyword_economics" else (1,)
208
+ if data.get("section_id") != section or data.get("schema_version") not in accepted_versions:
209
+ raise ValueError("Unsupported evidence version; refresh the bundle and rerun this section")
210
+ if section == "competitor_set":
211
+ _bound_file(workspace, state, RUNTIME / section / "inputs.json", "inputs")
212
+ intake_name = state.get("intake_path")
213
+ if intake_name:
214
+ intake_path = workspace / intake_name
215
+ if intake_path.is_file() and sha(intake_path) != state.get("intake_sha256"):
216
+ raise ValueError("Declared competitor intake changed; review prior evidence applicability")
217
+ if section == "channel_footprint" and data.get("schema_version") == 2:
218
+ inputs = data.get("inputs") or {}
219
+ policy = inputs.get("effective_policy")
220
+ policy_loader = load_script("research-policy")
221
+ if not isinstance(policy, dict) or policy_loader.canonical_hash(policy) != inputs.get("policy_sha256"):
222
+ raise ValueError("Channel Footprint policy hash mismatch")
223
+ if state.get("policy_sha256") != inputs.get("policy_sha256"):
224
+ raise ValueError("Channel Footprint receipt policy mismatch")
225
+ intake_path = workspace / _artifact_path("egbe-docs/research/market/intake.json")
226
+ intake_sha256 = sha(intake_path) if intake_path.is_file() else None
227
+ if state.get("intake_sha256") != intake_sha256:
228
+ raise ValueError("Channel Footprint intake changed; collect/finalize the current countries and context")
229
+ competitor_sha256 = state.get("competitor_set_sha256")
230
+ if competitor_sha256 and competitor_sha256 != sha(workspace / EVIDENCE / MEASURED["competitor_set"]):
231
+ raise ValueError("Channel Footprint competitor decisions changed; refresh its context")
232
+ context_sha256 = policy_loader.canonical_hash({
233
+ "context_sha256": state["research_context"]["sha256"], "intake_sha256": intake_sha256,
234
+ "competitor_context": inputs.get("competitor_context") or {},
235
+ "product_domain": inputs.get("product_domain") or "", "target_countries": inputs.get("target_countries") or [],
236
+ })
237
+ if state.get("input_context_sha256") != context_sha256 or inputs.get("product_context_sha256") != context_sha256:
238
+ raise ValueError("Channel Footprint input context hash mismatch")
239
+ if section == "creative_patterns" and (data.get("inputs") or {}).get("collection_mode") == "channel_footprint_reuse":
240
+ footprint_path = workspace / EVIDENCE / MEASURED["channel_footprint"]
241
+ if state.get("channel_footprint_sha256") != sha(footprint_path):
242
+ raise ValueError("Creative Patterns source footprint changed; rerun with current relevance and market scope")
243
+ footprint = inspect_section(workspace, "channel_footprint")
244
+ if footprint["status"] != "completed":
245
+ raise ValueError("Creative Patterns source footprint is pending, stale or unverified")
246
+ policy_loader = load_script("research-policy")
247
+ if (data["inputs"].get("footprint_document_sha256") != policy_loader.canonical_hash(footprint["data"])
248
+ or data["inputs"].get("policy_sha256") != footprint["data"]["inputs"].get("policy_sha256")
249
+ or state.get("policy_sha256") != data["inputs"].get("policy_sha256")):
250
+ raise ValueError("Creative Patterns footprint/policy snapshot mismatch")
251
+ if section == "creative_patterns" and data.get("schema_version") == 2:
252
+ inputs = data.get("inputs") or {}
253
+ policy_loader = load_script("research-policy")
254
+ policy = inputs.get("effective_policy")
255
+ if not isinstance(policy, dict) or policy_loader.canonical_hash(policy) != inputs.get("policy_sha256") or state.get("policy_sha256") != inputs.get("policy_sha256"):
256
+ raise ValueError("Creative Patterns policy/receipt hash mismatch")
257
+ intake = workspace / _artifact_path("egbe-docs/research/market/intake.json")
258
+ if state.get("intake_sha256") != (sha(intake) if intake.is_file() else None):
259
+ raise ValueError("Creative Patterns intake changed; rebuild dependent labels and coverage")
260
+ taxonomy = Path(__file__).resolve().parent.parent / "references/config/creative-taxonomy.v1.json"
261
+ if inputs.get("taxonomy_sha256") != sha(taxonomy):
262
+ raise ValueError("Creative Patterns taxonomy changed; refresh derived evidence")
263
+ dictionary = data.get("angle_dictionary") or {}
264
+ dictionary_body = {k: v for k, v in dictionary.items() if k != "dictionary_sha256"}
265
+ if dictionary.get("context_sha256") != inputs.get("semantic_context_sha256") or policy_loader.canonical_hash(dictionary_body) != dictionary.get("dictionary_sha256"):
266
+ raise ValueError("Creative Patterns semantic dictionary hash mismatch")
267
+ if inputs.get("creative_selection_path"):
268
+ selection = load_script("creative-selection").read_selection(workspace, data)
269
+ if state.get("creative_selection_sha256") != inputs.get("creative_selection_sha256") or selection != data.get("selection"):
270
+ raise ValueError("Creative Patterns selected creative manifest/receipt mismatch")
271
+ if inputs.get("footprint_document_sha256") and inputs.get("collection_mode") != "channel_footprint_reuse":
272
+ footprint = read_json(workspace / EVIDENCE / MEASURED["channel_footprint"])
273
+ if policy_loader.canonical_hash(footprint) != inputs["footprint_document_sha256"] or inspect_section(workspace, "channel_footprint")["status"] != "completed":
274
+ raise ValueError("Creative Patterns Channel Footprint input changed or is no longer completed")
275
+ if section == "funnel_teardown" and data.get("schema_version") == 2:
276
+ load_script("research_integrity").validate_funnel_receipt(workspace, data, state)
277
+ for source in ("channel_footprint", "creative_patterns"):
278
+ if inspect_section(workspace, source)["status"] != "completed":
279
+ raise ValueError("Funnel upstream " + source + " is pending, stale or unverified")
280
+ if section == "lifecycle_capture":
281
+ load_script("research_integrity").validate_lifecycle_inputs(workspace, state)
282
+ if not isinstance(data.get("rows"), list) or any(not isinstance(row, dict) for row in data["rows"]):
283
+ raise ValueError("Evidence rows must be an array (empty is permitted)")
284
+ if section == "keyword_economics":
285
+ if not isinstance(data.get("locales"), list) or not data["locales"] or any(not isinstance(x, dict) or x.get("status") != "completed" for x in data["locales"]):
286
+ raise ValueError("Not every requested keyword locale completed")
287
+ for locale in data["locales"]:
288
+ key = locale["key"]
289
+ if not re.fullmatch(r"[0-9]+-[a-z]{2,3}(?:-[a-z]{2})?", key):
290
+ raise ValueError("Invalid locale key")
291
+ canonical = EVIDENCE / "keyword-economics" / f"{key}.json"
292
+ if locale.get("evidence_path") != canonical.as_posix() or sha(workspace / canonical) != locale.get("evidence_sha256"):
293
+ raise ValueError("Locale evidence hash mismatch")
294
+ attempt = read_json(root / "locales" / key / "request.json")
295
+ if attempt.get("status") != "completed" or attempt.get("research_context") != state["research_context"]:
296
+ raise ValueError("Locale refresh pending/failed/stale")
297
+ result = _bound_file(workspace, state, RUNTIME / section / "result.md", "result")
298
+ body = result.read_text().strip()
299
+ elif section == "organic_trend_watch":
300
+ if state.get("schema_version") != 1 or state.get("section_id") != section:
301
+ raise ValueError("Wrong Organic Trend integration receipt")
302
+ if state.get("context_sha256") != sha(root / "context.json"):
303
+ raise ValueError("Organic Trend input context changed")
304
+ source = read_json(root / "context.json").get("sources", {}).get("context")
305
+ if source:
306
+ source_path = workspace / source["path"]
307
+ if source_path.is_file() and sha(source_path) != source["source_sha256"]:
308
+ raise ValueError("Declared Organic context changed; review prior evidence applicability")
309
+ _publication(state)
310
+ for field, filename in (("skill_receipt", "receipt.json"), ("result", "result.md")):
311
+ ref = state[field]
312
+ if ref.get("path") != filename or ref.get("sha256") != sha(root / filename):
313
+ raise ValueError("Organic Trend integration hash mismatch")
314
+ skill_receipt = read_json(root / "receipt.json")
315
+ expected_coverage = {"completed": "complete", "partial": "partial", "no_data": "no_data"}
316
+ coverage = state.get("coverage")
317
+ if (not isinstance(coverage, dict)
318
+ or coverage.get("status") != expected_coverage[state["status"]]
319
+ or skill_receipt.get("status") != state["status"]
320
+ or skill_receipt.get("coverage") != coverage):
321
+ raise ValueError("Organic Trend coverage differs from its sealed receipt")
322
+ body = (root / "result.md").read_text().strip()
323
+ if hashlib.sha256(body.encode()).hexdigest() != state["report_section_sha256"]:
324
+ raise ValueError("Organic Trend section hash mismatch")
325
+ data = {"result_sha256": state["result"]["sha256"], "coverage": coverage}
326
+ elif section == "geography_comparison":
327
+ body, data = load_script("geography-comparison").inspect(workspace, state)
328
+ else:
329
+ body, data = _ai(workspace, section, state)
330
+ if require_materialized and report_body(workspace, specs[section]["heading"]) != body:
331
+ raise ValueError("Report section differs from its published result")
332
+ status = state["status"] if section == "organic_trend_watch" else "completed"
333
+ outcome = {"status": status, "data": data, "body": body, "receipt_sha256": sha(root / ("integration-receipt.json" if section == "organic_trend_watch" else filename))}
334
+ if status != "completed":
335
+ outcome["reason"] = "Organic research coverage is " + status + "; see source gaps"
336
+ return outcome
337
+ except (OSError, ValueError, KeyError, TypeError) as exc:
338
+ return {"status": "could_not_complete", "reason": str(exc)}
339
+
340
+
341
+ def fair_rows(rows: list[dict], limit: int) -> list[dict]:
342
+ """Round-robin per locale/type, including exclusions and contrary observations."""
343
+ groups = defaultdict(list)
344
+ for position, row in enumerate(rows):
345
+ groups[(row.get("locale_key", ""), row.get("type", ""))].append((position, row))
346
+ selected = []
347
+ while groups and len(selected) < limit:
348
+ for key in sorted(list(groups)):
349
+ position, row = groups[key].pop(0)
350
+ selected.append({**row, "evidence_row": position})
351
+ if not groups[key]:
352
+ del groups[key]
353
+ if len(selected) == limit:
354
+ break
355
+ return selected
356
+
357
+
358
+ def keyword_inputs(workspace: Path, *, consumer: str, row_type: str, field: str, cap: int, exclude=frozenset()) -> list[str]:
359
+ """Keyword Economics rows as optional inputs. `exclude` (domains the
360
+ completed Competitor Set rejected) is applied BEFORE the cap so a
361
+ rejected domain neither fills a slot nor appears in the provenance as
362
+ an input; the exclusions themselves are recorded there."""
363
+ outcome = inspect_section(workspace, "keyword_economics")
364
+ provenance_path = workspace / RUNTIME / consumer / "keyword-inputs.json"
365
+ io = load_script("research-artifact-io")
366
+ if outcome["status"] != "completed":
367
+ # This source only supplements explicit inputs; invalid data must not
368
+ # be reused or turn an independent workflow into a failed dependency.
369
+ io.write_json(provenance_path, {"schema_version": 1, "status": outcome["status"],
370
+ "reason": outcome["reason"], "source_sha256": None, "inputs": []})
371
+ print("Optional Keyword Economics inputs not used: " + outcome["reason"], file=sys.stderr)
372
+ return []
373
+ rows = [r for r in outcome["data"]["rows"] if r.get("type") == row_type and r.get(field)]
374
+ if row_type == "keyword":
375
+ rows = [r for r in rows if not r.get("free_edu_intent") and type(r.get("search_volume")) is int]
376
+ else:
377
+ rows = [r for r in rows if r.get("kind") == "candidate"]
378
+ excluded = {_normalized_domain(x) for x in exclude}
379
+ rejected = sorted({r[field] for r in rows if _normalized_domain(r[field]) in excluded}) if excluded else []
380
+ rows = [r for r in rows if _normalized_domain(r[field]) not in excluded]
381
+ metric = "search_volume" if row_type == "keyword" else "score"
382
+ rows.sort(key=lambda r: (-(r.get(metric) or 0), r[field]))
383
+ ordered = fair_rows(rows, len(rows))
384
+ chosen = list(dict.fromkeys(r[field] for r in ordered))[:cap]
385
+ provenance = {"schema_version": 1, "status": "completed",
386
+ "source_sha256": sha(workspace / EVIDENCE / MEASURED["keyword_economics"]),
387
+ "inputs": [{field: r[field], "locale_key": r["locale_key"], metric: r.get(metric)}
388
+ for r in rows if r[field] in chosen],
389
+ "excluded_by_competitor_set": rejected}
390
+ io.write_json(provenance_path, provenance)
391
+ return chosen
392
+
393
+
394
+ def _normalized_domain(value) -> str:
395
+ """Host-only, lowercase, without scheme, path, port, trailing dot or www."""
396
+ text = str(value or "").strip().lower()
397
+ if "//" in text:
398
+ text = text.split("//", 1)[1]
399
+ host = text.split("/", 1)[0].split("?", 1)[0].split("@")[-1].split(":", 1)[0].rstrip(".")
400
+ return host.removeprefix("www.")
401
+
402
+
403
+ def competitor_set_inputs(workspace: Path, *, consumer: str, cap: int) -> list[str]:
404
+ """Competitor domains of the completed Competitor Set, in rank order.
405
+
406
+ Like keyword inputs, this source only supplements explicit inputs:
407
+ pending, failed or invalid evidence is omitted with the reason recorded
408
+ in the consumer's `competitor-set-inputs.json`."""
409
+ outcome = inspect_section(workspace, "competitor_set")
410
+ provenance_path = workspace / RUNTIME / consumer / "competitor-set-inputs.json"
411
+ io = load_script("research-artifact-io")
412
+ if outcome["status"] != "completed":
413
+ io.write_json(provenance_path, {"schema_version": 1, "status": outcome["status"],
414
+ "reason": outcome["reason"], "source_sha256": None, "inputs": []})
415
+ print("Optional Competitor Set inputs not used: " + outcome["reason"], file=sys.stderr)
416
+ return []
417
+ rows = [r for r in outcome["data"]["rows"] if r.get("type") == "competitor" and r.get("domain")]
418
+ rows.sort(key=lambda r: (r["rank"] if type(r.get("rank")) is int else 10 ** 6, r["domain"]))
419
+ chosen = list(dict.fromkeys(r["domain"] for r in rows))[:cap]
420
+ provenance = {"schema_version": 1, "status": "completed",
421
+ "source_sha256": sha(workspace / EVIDENCE / MEASURED["competitor_set"]),
422
+ "inputs": [{"domain": r["domain"], "rank": r.get("rank"), "competitor_tier": r.get("competitor_tier")}
423
+ for r in rows if r["domain"] in chosen]}
424
+ io.write_json(provenance_path, provenance)
425
+ return chosen
426
+
427
+
428
+ def competitor_set_excluded_domains(workspace: Path) -> set[str]:
429
+ """Domains the completed Competitor Set rejected: agent exclusions,
430
+ directories, below-threshold candidates. Automatic fallbacks (Keyword
431
+ Economics) must not pull them back in; explicit founder inputs may.
432
+ Over-cap competitors are not exclusions. Empty when the section is not
433
+ completed."""
434
+ outcome = inspect_section(workspace, "competitor_set")
435
+ if outcome["status"] != "completed":
436
+ return set()
437
+ return {
438
+ _normalized_domain(r["domain"]) for r in outcome["data"]["rows"]
439
+ if r.get("type") == "excluded_candidate" and r.get("domain") and r.get("decided_by") != "cap"
440
+ }
441
+
442
+
443
+ def _bounded(value):
444
+ if isinstance(value, str):
445
+ return value[:600] + ("…[truncated]" if len(value) > 600 else "")
446
+ if isinstance(value, list):
447
+ return [_bounded(x) for x in value[:12]]
448
+ if isinstance(value, dict):
449
+ return {k: _bounded(v) for k, v in list(value.items())[:20]}
450
+ return value
451
+
452
+
453
+ def measured_context(workspace: Path, section: str) -> tuple[tuple, dict]:
454
+ context_path = workspace / RUNTIME / "preview-context.json"
455
+ selection = read_json(context_path) if context_path.exists() else None
456
+ outcomes = {s["id"]: s["status"] for s in selection["sections"]} if selection else {}
457
+ projections, manifest = [], {}
458
+ for source in INPUTS.get(section, ()):
459
+ selected_status = outcomes.get(source)
460
+ outcome = {"status": "not_selected"} if selected_status == "not_selected" else inspect_section(workspace, source)
461
+ if selected_status == "could_not_complete":
462
+ outcome = {"status": "could_not_complete", "reason": "Caller closed this selected section without completion"}
463
+ elif (outcome["status"] == "pending" and selection and selected_status is not None
464
+ and selection["selection_id"].startswith("local:")):
465
+ raise ValueError(f"Selected supporting research {source} is pending; finish or explicitly skip it before {section}")
466
+ elif outcome["status"] == "pending" and not selection:
467
+ outcome = {"status": "unknown", "reason": "No selection scope or completed receipt; no conclusion about demand"}
468
+ projected = {"section": source, "status": outcome["status"], "reason": outcome.get("reason")}
469
+ if outcome["status"] == "completed":
470
+ data = outcome["data"]
471
+ rows = data["rows"]
472
+ chosen = fair_rows(rows, 40)
473
+ projected.update({"source_path": (EVIDENCE / MEASURED[source]).as_posix(),
474
+ "evidence_sha256": sha(workspace / EVIDENCE / MEASURED[source]),
475
+ "receipt_sha256": outcome["receipt_sha256"],
476
+ "retrieved_on": data.get("retrieved_on"),
477
+ "locales": [{k: x.get(k) for k in ("key", "status", "locale", "retrieved_on", "evidence_sha256")}
478
+ for x in data.get("locales", [])],
479
+ "rows": [{k: _bounded(v) for k, v in r.items() if k in PUBLIC_FIELDS or k == "evidence_row"} for r in chosen],
480
+ "rows_total": len(rows), "rows_omitted": len(rows) - len(chosen),
481
+ "field_limits": {"text_characters": 600, "list_items": 12},
482
+ "forecast_coverage": [{"locale_key": x["key"], **{k: x.get("simulation", {}).get(k) for k in
483
+ ("kind", "requested_count", "submitted_count", "match", "bid", "forecast_period",
484
+ "response_status", "response_rows", "rationale", "source", "limitations")}}
485
+ for x in data.get("locales", [])],
486
+ "limitations": "Bounded observations, not TAM or proof of willingness to pay. "
487
+ "CPC is auction cost, not product pricing. Missing/null is not zero. "
488
+ "Geographies and alternative budget scenarios must not be summed."})
489
+ while len(json.dumps(projected, ensure_ascii=False)) > 16000 and projected["rows"]:
490
+ projected["rows"].pop()
491
+ projected["rows_omitted"] += 1
492
+ content = json.dumps(projected, sort_keys=True, ensure_ascii=False)
493
+ projections.append((f"Measured {source} (untrusted observations)", content))
494
+ manifest[source] = {"status": projected["status"], "projection_sha256": hashlib.sha256(content.encode()).hexdigest(),
495
+ "evidence_sha256": projected.get("evidence_sha256")}
496
+ return tuple(projections), manifest
@@ -0,0 +1,33 @@
1
+ #!/usr/bin/env python3
2
+ """Portable effective evidence settings owned by Product Market Research.
3
+
4
+ Other skill bundles consume the exported snapshot and its canonical hash;
5
+ they do not import this module from a sibling checkout.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import hashlib
10
+ import json
11
+ from pathlib import Path
12
+ from typing import Any
13
+
14
+
15
+ def canonical_hash(value: dict[str, Any]) -> str:
16
+ return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")).hexdigest()
17
+
18
+
19
+ def policy_from_taxonomy(taxonomy: dict[str, Any], direct_fallback_min=None) -> tuple[dict[str, Any], str]:
20
+ """Version the observation contract, never business-success thresholds."""
21
+ policy = {
22
+ "schema_version": 2,
23
+ "classification": "observations_only",
24
+ "activity": "native_status_only",
25
+ "duration": "native_delivery_scope",
26
+ }
27
+ return policy, canonical_hash(policy)
28
+
29
+
30
+ def load_policy(taxonomy_path: Path | None = None, sources_path: Path | None = None) -> tuple[dict[str, Any], str]:
31
+ root = Path(__file__).resolve().parent.parent
32
+ taxonomy = json.loads((taxonomy_path or root / "references/config/creative-taxonomy.v1.json").read_text(encoding="utf-8"))
33
+ return policy_from_taxonomy(taxonomy)