@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,32 @@
1
+ # Product attribution
2
+
3
+ Read the live `/analytics/skill` and `/analytics/events`. Product events are canonical
4
+ Egbe events, not OpenAI event names. Useful funnel signals include `campaign-visit`,
5
+ `cta_click`, `signup_completed`, `activated` and `purchase` where applicable.
6
+
7
+ Use stable URLs with:
8
+
9
+ - `utm_source=openai`
10
+ - `utm_medium=paid_ai`
11
+ - `utm_campaign=<openai-campaign-slug>`
12
+ - `utm_content=<ad-slug>`
13
+
14
+ Do not encode user data or replace campaign slugs with orchestration IDs. Preserve
15
+ existing attribution when taking over a historical campaign: record its actual
16
+ UTMs and plan an explicit change rather than silently rewriting live URLs. The
17
+ portable checker uses the new-campaign convention for build/launch, not for audits.
18
+
19
+ Read `/analytics/<product_slug>/tracking` and available campaign/funnel reports.
20
+ Check that the actual destination loads product tracking; do not emit synthetic
21
+ business events to manufacture readiness. Do only bounded verification appropriate
22
+ to the requested integration, not a full unrelated product test.
23
+
24
+ Write `tracking.json` with destination, UTMs, analytics identity, evidence and
25
+ `active/degraded/blocked` state. If campaign-level slicing is unavailable, keep
26
+ site-wide signals separate; never assign all site purchases to this campaign.
27
+ Missing data is unavailable, not zero. Return the unavailable attribution fields
28
+ without substituting site-wide outcomes.
29
+
30
+ OpenAI Pixel/CAPI is optional: see [conversions](conversions.md). Captured `oppref`
31
+ and `obref` belong in consent-aware product runtime storage, not marketing docs.
32
+ Configured tracking, accepted events and attributed conversions are different facts.
@@ -0,0 +1,271 @@
1
+ #!/usr/bin/env python3
2
+ """Read-only, stdlib-only structural checks. No API calls or marketing verdicts."""
3
+ import argparse
4
+ from datetime import datetime
5
+ from decimal import Decimal, InvalidOperation
6
+ import json
7
+ from pathlib import Path
8
+ import re
9
+ from urllib.parse import parse_qs, urlsplit
10
+
11
+ PHASES = ('readiness', 'creative-assembly', 'tracking', 'build-paused', 'launch',
12
+ 'edit', 'recovery', 'monitoring', 'pause')
13
+ ID = re.compile(r'^[A-Za-z0-9_-]{1,160}$')
14
+ SLUG = re.compile(r'^openai-[a-z0-9]+(?:-[a-z0-9]+)*$')
15
+
16
+
17
+ def ref(value):
18
+ return value if isinstance(value, str) else ''
19
+
20
+
21
+ class Check:
22
+ def __init__(self, root):
23
+ self.root = Path(root).resolve()
24
+ self.errors = []
25
+
26
+ def fail(self, label, message):
27
+ self.errors.append(f'{label}: {message}')
28
+
29
+ def path(self, relative):
30
+ path = (self.root / relative).resolve()
31
+ if not path.is_relative_to(self.root):
32
+ self.fail(str(relative), 'path must stay inside the product repository')
33
+ return None
34
+ return path
35
+
36
+ def document(self, relative, required=True):
37
+ path = self.path(relative)
38
+ if path is None:
39
+ return {}
40
+ if not path.is_file() and not required:
41
+ return {}
42
+ try:
43
+ value = json.loads(path.read_text())
44
+ if not isinstance(value, dict):
45
+ raise ValueError('expected a JSON object')
46
+ return value
47
+ except (OSError, ValueError) as exc:
48
+ self.fail(str(relative), f'cannot read JSON object ({exc})')
49
+ return {}
50
+
51
+ def note(self, relative):
52
+ path = self.path(relative)
53
+ if path is not None and (not path.is_file() or not path.read_text().strip()):
54
+ self.fail(str(relative), 'write a nonempty evidence note; record unknowns explicitly')
55
+
56
+ def rows(self, doc, field, label):
57
+ rows = doc.get(field)
58
+ if not isinstance(rows, list) or any(not isinstance(row, dict) for row in rows):
59
+ self.fail(label, f'{field} must be an array of objects')
60
+ return []
61
+ return rows
62
+
63
+ def timestamp(self, value, label):
64
+ try:
65
+ parsed = datetime.fromisoformat(value.replace('Z', '+00:00'))
66
+ if parsed.tzinfo is None:
67
+ raise ValueError()
68
+ except (AttributeError, TypeError, ValueError):
69
+ self.fail(label, 'use an observed ISO timestamp with timezone')
70
+
71
+
72
+ def tracked_url(check, value, slug, label):
73
+ try:
74
+ url = urlsplit(value)
75
+ params = parse_qs(url.query)
76
+ if url.scheme not in ('http', 'https') or not url.netloc:
77
+ raise ValueError()
78
+ except (TypeError, ValueError, AttributeError):
79
+ check.fail(label, 'expected an absolute HTTP(S) destination URL')
80
+ return
81
+ for key, expected in (('utm_source', 'openai'), ('utm_medium', 'paid_ai'), ('utm_campaign', slug)):
82
+ if params.get(key) != [expected]:
83
+ check.fail(label, f'{key} must occur once and equal {expected}')
84
+ if len(params.get('utm_content', [])) != 1 or not params['utm_content'][0].strip():
85
+ check.fail(label, 'include one nonempty utm_content')
86
+
87
+
88
+ def unique_ids(check, rows, label):
89
+ result = {}
90
+ for row in rows:
91
+ value = row.get('id')
92
+ if not isinstance(value, str) or not ID.fullmatch(value):
93
+ check.fail(label, 'each object needs a valid provider id')
94
+ elif value in result:
95
+ check.fail(label, f'duplicate provider id {value}')
96
+ else:
97
+ result[value] = row
98
+ return result
99
+
100
+
101
+ def execution(check, folder, slug, phase):
102
+ state = check.document(folder / 'campaign-state.json', required=phase != 'recovery')
103
+ if phase == 'recovery' and not state:
104
+ # A create can be unconfirmed before any provider ID is known.
105
+ return
106
+ if state.get('channel') != 'openai' or state.get('campaign_slug') != slug:
107
+ check.fail('campaign-state.json', 'channel/slug must match the campaign index')
108
+ if not isinstance(state.get('product_slug'), str) or not state['product_slug'].strip():
109
+ check.fail('campaign-state.json', 'product_slug is required')
110
+ if state.get('status') not in ('paused', 'active', 'unknown', 'archived'):
111
+ check.fail('campaign-state.json', 'status must be observed paused/active/archived or unknown')
112
+ check.timestamp(state.get('updated_at'), 'campaign-state.json.updated_at')
113
+ objects = state.get('objects') if isinstance(state.get('objects'), dict) else {}
114
+ cid = objects.get('campaign_id')
115
+ if not isinstance(cid, str) or not ID.fullmatch(cid):
116
+ check.fail('campaign-state.json', 'objects.campaign_id must be a provider ID')
117
+ groups = unique_ids(check, check.rows(objects, 'ad_groups', 'objects'), 'objects.ad_groups')
118
+ ads = unique_ids(check, check.rows(objects, 'ads', 'objects'), 'objects.ads')
119
+ files = objects.get('file_ids', [])
120
+ if not isinstance(files, list) or any(not isinstance(v, str) or not ID.fullmatch(v) for v in files):
121
+ check.fail('objects.file_ids', 'expected provider file IDs')
122
+ files = []
123
+ for group in groups.values():
124
+ if group.get('campaign_id') != cid:
125
+ check.fail('objects.ad_groups', f'{group["id"]} references a different campaign')
126
+ for ad in ads.values():
127
+ if ref(ad.get('ad_group_id')) not in groups or ad.get('file_id') not in files:
128
+ check.fail('objects.ads', f'{ad["id"]} must reference a recorded group and file')
129
+ if phase in ('monitoring', 'recovery'):
130
+ return
131
+ rb = check.document(folder / 'launch-readback.json')
132
+ check.timestamp(rb.get('observed_at'), 'launch-readback.json.observed_at')
133
+ campaign = rb.get('campaign') if isinstance(rb.get('campaign'), dict) else {}
134
+ if campaign.get('id') != cid or campaign.get('status') != state.get('status'):
135
+ check.fail('launch-readback.json', 'campaign ID/status differs from state; read OS, do not invent agreement')
136
+ actual_groups = unique_ids(check, check.rows(rb, 'ad_groups', 'readback'), 'readback.ad_groups')
137
+ actual_ads = unique_ids(check, check.rows(rb, 'ads', 'readback'), 'readback.ads')
138
+ for value, observed in actual_groups.items():
139
+ if value not in groups or observed.get('campaign_id') != cid:
140
+ check.fail('readback.ad_groups', f'unexpected ID/parent for {value}')
141
+ for value, observed in actual_ads.items():
142
+ planned = ads.get(value, {})
143
+ creative = observed.get('creative') if isinstance(observed.get('creative'), dict) else {}
144
+ if value not in ads or observed.get('ad_group_id') != planned.get('ad_group_id'):
145
+ check.fail('readback.ads', f'unexpected ID/parent for {value}')
146
+ if creative.get('file_id') != planned.get('file_id'):
147
+ check.fail('readback.ads', f'file binding differs for {value}')
148
+ if phase in ('build-paused', 'launch'):
149
+ tracked_url(check, creative.get('target_url'), slug, f'readback ad {value}')
150
+ if phase in ('build-paused', 'launch'):
151
+ if not groups or not ads or set(groups) != set(actual_groups) or set(ads) != set(actual_ads):
152
+ check.fail('launch-readback.json', 'complete planned groups and ads must be observed')
153
+ budget = state.get('budget') if isinstance(state.get('budget'), dict) else {}
154
+ observed_budget = campaign.get('budget') if isinstance(campaign.get('budget'), dict) else {}
155
+ try:
156
+ amount = Decimal(str(budget.get('daily_budget_usd')))
157
+ if not amount.is_finite() or amount <= 0 or budget.get('currency') != 'USD':
158
+ raise ValueError()
159
+ if amount * 1_000_000 != observed_budget.get('daily_spend_limit_micros'):
160
+ check.fail('budget', 'daily USD budget differs from provider micros readback')
161
+ except (InvalidOperation, ValueError):
162
+ check.fail('budget', 'positive finite daily_budget_usd and USD currency required')
163
+ if phase == 'build-paused' and any(x.get('status') != 'paused' for x in [campaign, *actual_groups.values(), *actual_ads.values()]):
164
+ check.fail('build-paused', 'campaign and all planned children must be observed paused')
165
+ if phase == 'launch':
166
+ path = any(ad.get('status') == 'active' and actual_groups.get(ref(ad.get('ad_group_id')), {}).get('status') == 'active' for ad in actual_ads.values())
167
+ if campaign.get('status') != 'active' or not path:
168
+ check.fail('launch', 'expected observed active campaign → group → ad path; this is not proof of delivery')
169
+ if phase == 'pause' and campaign.get('status') != 'paused':
170
+ check.fail('pause', 'campaign must be observed paused; child flags need not be paused')
171
+
172
+
173
+ def operations(check, folder, phase):
174
+ doc = check.document(folder / 'operations.json')
175
+ keys, ids = set(), set()
176
+ for item in check.rows(doc, 'operations', 'operations.json'):
177
+ for field, seen in (('operation_id', ids), ('idempotency_key', keys)):
178
+ value = item.get(field)
179
+ if not isinstance(value, str) or not value.strip() or value in seen:
180
+ check.fail('operations.json', f'{field} must be nonempty and unique; update the existing entry on retries')
181
+ elif field == 'idempotency_key' and len(value) > 128:
182
+ check.fail('operations.json', 'idempotency_key exceeds API limit of 128')
183
+ else:
184
+ seen.add(value)
185
+ path = item.get('path')
186
+ if item.get('method') != 'POST' or not isinstance(path, str) or not path.startswith('/ads/openai/') or '/conversion-events' in path:
187
+ check.fail('operations.json', 'record management POST paths relative to OS; customer event bodies stay in server storage')
188
+ if not isinstance(item.get('payload'), dict):
189
+ check.fail('operations.json', 'payload must preserve the exact request object ({} for no body)')
190
+ status = item.get('status')
191
+ if status not in ('prepared', 'unconfirmed', 'succeeded', 'failed'):
192
+ check.fail('operations.json', 'invalid operation status')
193
+ if phase == 'launch' and status in ('prepared', 'unconfirmed'):
194
+ check.fail('operations.json', f'resolve {item.get("operation_id")} using its saved key before launch')
195
+
196
+
197
+ def validate(product_root, phase, campaign=None):
198
+ check = Check(product_root)
199
+ if phase not in PHASES:
200
+ check.fail('phase', 'unsupported operation check')
201
+ return check.errors
202
+ base = Path('egbe-docs/marketing/campaigns/openai')
203
+ if phase == 'readiness':
204
+ doc = check.document(base / 'channel-readiness.json')
205
+ if doc.get('channel') != 'openai' or not isinstance(doc.get('blockers'), list):
206
+ check.fail('channel-readiness.json', 'channel=openai and blockers array required (unknowns are allowed)')
207
+ check.timestamp(doc.get('checked_at'), 'readiness.checked_at')
208
+ return check.errors
209
+ index = check.document(base / 'campaigns.json')
210
+ entries = check.rows(index, 'campaigns', 'campaigns.json')
211
+ slug = campaign or index.get('selected_campaign')
212
+ if not isinstance(slug, str) or not SLUG.fullmatch(slug):
213
+ check.fail('campaigns.json', 'select one safe openai-<slug> campaign')
214
+ return check.errors
215
+ matches = [entry for entry in entries if entry.get('campaign_slug') == slug]
216
+ folder = base / slug
217
+ if index.get('channel') != 'openai' or len(matches) != 1:
218
+ check.fail('campaigns.json', 'channel=openai and exactly one matching campaign entry required')
219
+ return check.errors
220
+ if matches[0].get('campaign_path') != folder.as_posix() or matches[0].get('utm_campaign') != slug:
221
+ check.fail('campaigns.json', 'campaign_path/utm_campaign must match the selected folder slug')
222
+ plan_path = matches[0].get('plan_path')
223
+ if phase in ('creative-assembly', 'build-paused', 'launch') and plan_path is not None:
224
+ if not isinstance(plan_path, str) or not plan_path.strip() or Path(plan_path).is_absolute():
225
+ check.fail('campaigns.json', 'plan_path must be a nonempty repository-relative path')
226
+ else:
227
+ check.note(plan_path)
228
+ if phase in ('creative-assembly', 'build-paused', 'launch'):
229
+ creative = check.document(folder / 'creatives.json')
230
+ groups = check.rows(creative, 'ad_groups', 'creatives.json')
231
+ ads = check.rows(creative, 'ads', 'creatives.json')
232
+ group_slugs = [row.get('slug') for row in groups]
233
+ if not groups or not ads:
234
+ check.fail('creatives.json', 'at least one planned group and ad required')
235
+ for ad in ads:
236
+ if ad.get('ad_group_slug') not in group_slugs:
237
+ check.fail('creatives.json', 'ad_group_slug must reference a planned group')
238
+ if phase in ('tracking', 'build-paused', 'launch'):
239
+ tracking = check.document(folder / 'tracking.json')
240
+ tracked_url(check, tracking.get('destination_url'), slug, 'tracking.destination_url')
241
+ if tracking.get('tracking_state') not in ('active', 'degraded', 'blocked'):
242
+ check.fail('tracking.json', 'declare active/degraded/blocked, not inferred success')
243
+ if phase in ('build-paused', 'launch', 'edit', 'recovery', 'monitoring', 'pause'):
244
+ execution(check, folder, slug, phase)
245
+ if phase in ('build-paused', 'launch', 'edit', 'recovery'):
246
+ operations(check, folder, phase)
247
+ if phase in ('build-paused', 'launch', 'edit', 'recovery', 'pause'):
248
+ check.note(folder / 'change-log.md')
249
+ if phase == 'monitoring':
250
+ directory = check.path(folder / 'monitoring')
251
+ notes = list(directory.glob('check-*.md')) if directory else []
252
+ if not notes:
253
+ check.fail('monitoring', 'write a timestamped check-*.md evidence note')
254
+ for note in notes:
255
+ check.note(note.relative_to(check.root))
256
+ return check.errors
257
+
258
+
259
+ def main():
260
+ parser = argparse.ArgumentParser(description=__doc__)
261
+ parser.add_argument('--product-root', required=True)
262
+ parser.add_argument('--campaign')
263
+ parser.add_argument('--phase', choices=PHASES, required=True)
264
+ args = parser.parse_args()
265
+ errors = validate(args.product_root, args.phase, args.campaign)
266
+ print(json.dumps({'ok': not errors, 'phase': args.phase, 'errors': errors}, indent=2))
267
+ return bool(errors)
268
+
269
+
270
+ if __name__ == '__main__':
271
+ raise SystemExit(main())
@@ -0,0 +1,139 @@
1
+ ---
2
+ name: egbe-os-organic-trend-watch
3
+ description: Research TikTok and Instagram Reels evidence, compare formats and audience responses, and propose grounded creative adaptations for a product.
4
+ metadata:
5
+ egbe-when: "Offer when a new or existing product needs short-video evidence to assess an acquisition hypothesis or improve content."
6
+ egbe-visible: "true"
7
+ egbe-title: "Short-video research"
8
+ egbe-description: "Research TikTok and Instagram Reels examples and audience responses, then adapt useful ideas to your product."
9
+ egbe-category: "Marketing & growth"
10
+ ---
11
+
12
+ <!-- egbe-mcp-connection:v1 -->
13
+ This skill comes with the Egbe plugin. If this project has its own installed copy
14
+ of the skill, use that copy instead. Otherwise make every Egbe API call it
15
+ describes with the Egbe connector: `egbe_read` for GET and `egbe_write` for POST,
16
+ PUT, PATCH and DELETE (with `method`). Pass the API path (for example
17
+ `/me/limits`), query parameters in `query` and the JSON body in `body`. Leave out `OS_URL`, the Authorization header, `.env.local`,
18
+ `egbe-curl.py` and catalog update checks; the connection authenticates and
19
+ identifies the request. Also pass the `business` that `egbe_setup` returned.
20
+ Where this skill sends an `Idempotency-Key` header, pass the same value as
21
+ `idempotency_key` and reuse it when retrying. A result with a `continuation`
22
+ holds one part of a long body; read the next part with `egbe_read`, the same
23
+ `path` and `business`, and that `continuation`.
24
+ Read bundled files beside this `SKILL.md`. For published skill resources on
25
+ Egbe OS, use `egbe_skill`. Follow "Files downloaded on demand" for listed downloads.
26
+
27
+ Publishing works through the connector: commit the app's files with the JSON
28
+ commit requests in `egbe-os-git` ("Without a terminal") and deploy the returned
29
+ commit SHA; no git push or workspace setup is needed. A step that needs a local
30
+ project key or a bundled script, such as a local `npx convex deploy`, needs a
31
+ set-up project workspace. In a persistent
32
+ project workspace that is not set up yet, set it up as the `egbe-setup` skill's
33
+ project setup describes.
34
+ Without such a workspace, or if it refuses, tell the founder that this step needs
35
+ an agent with a set-up project folder, and continue with the rest of the work.
36
+
37
+ If the connector's tools (`egbe_read` and the other `egbe_*` tools) are not
38
+ available, the plugin's connector is not signed in for this agent. Tell
39
+ the founder how to connect it, as the `egbe-setup` skill describes, rather than
40
+ saying Egbe is unavailable.
41
+
42
+ The connector's tools work even where this environment's shell cannot reach
43
+ Egbe: their calls travel through this agent's connection, not through the
44
+ shell's network. A step that runs in the shell, such as a bundled script, a `git
45
+ push` to Egbe's Git endpoint or a deploy upload, needs the shell to reach the
46
+ Egbe host (`os.hz.egbe.dev`). If a proxy or allowlist refuses that request
47
+ before Egbe answers, for example HTTP 403 on CONNECT or curl status `000`, tell
48
+ the founder: they allow that host in this agent's network settings or continue
49
+ with an agent on their own computer. Code can also be published without the
50
+ shell by committing through the connector (`egbe-os-git`, "Without a terminal").
51
+ Until the shell step or that commit and its deploy succeed, do not report the
52
+ work as published: a preview in this agent or on this computer is not an Egbe
53
+ deployment.
54
+
55
+ Run a script bundled with this skill from the root of a project folder set up
56
+ for Egbe, with `OS_AGENT_NAME="<your agent name>"` set inline, such as `OpenCode`.
57
+ A script that calls Egbe reads `OS_URL`, `OS_API_KEY` and this agent's connection
58
+ ID from `.env.local` through Egbe's request helper, which comes with the plugin at
59
+ `../egbe-os-quickstart/scripts/egbe-curl.py` from this skill's folder. Where this
60
+ skill says a script needs `OS_URL` or `OS_API_KEY` in its environment, start it
61
+ through the helper, which loads `.env.local` without executing it:
62
+ `python3 <helper> --egbe-run <command>`, with the helper's absolute path. Where
63
+ this skill writes `<skills-directory>`, use the plugin's `skills` folder, which
64
+ holds this skill's folder.
65
+
66
+
67
+ # Organic Trend Watch
68
+
69
+ Answer a scoped research question using collected TikTok/Reels observations.
70
+ Compare what the sources actually show, explain uncertainty, and propose
71
+ product-relevant adaptations. This skill does not publish videos or measure
72
+ the product's resulting conversions. It can run independently or supply a
73
+ Product Market Research section; it is not a pre-PRD prerequisite.
74
+
75
+ ## Through the Egbe connector
76
+
77
+ Through the connector alone, you can collect a bounded sample with the Apify
78
+ routes in [provider-contract.md](references/provider-contract.md), saving each
79
+ run and dataset ID in Egbe's artifact store before reading results so a paid run
80
+ is resumed, not repeated, and answer from captions, metrics and comments. State
81
+ that frames and transcripts were not analyzed. The bundled runner, media
82
+ analyzer, renderer and finalizer, and so `analysis.json`, `result.md` and a
83
+ sealed `receipt.json`, need a set-up project workspace: in a persistent project
84
+ workspace not set up yet, call `egbe_local_setup`; otherwise tell the founder
85
+ which step needs it. Do not present a connector answer as a sealed result or a
86
+ PMR section.
87
+
88
+ ## Establish the assignment
89
+
90
+ Use the question, product/audience context and available evidence. Missing
91
+ market-research sections do not block direct use. Keep founder identity and
92
+ unrelated personal details out of provider inputs.
93
+
94
+ Use the product repository and `EGBE_RESEARCH_ID` (default `market`). Resolve
95
+ the installed skill separately from the mutable study directory:
96
+
97
+ ```bash
98
+ ORGANIC_TREND_SKILL_ROOT=/absolute/path/to/the-directory-containing-this-SKILL.md
99
+ WORKSPACE_ROOT=/absolute/path/to/the-product-repository
100
+ RUNTIME_ROOT="$WORKSPACE_ROOT/egbe-docs/research/market/work/organic_trend_watch"
101
+ ```
102
+
103
+ Keep execution artifacts below that study's `work/organic_trend_watch/`; replace
104
+ `market` in examples when using another study ID. Never work inside the installed
105
+ skill. Read [runtime-contract.md](references/runtime-contract.md) for context,
106
+ state and resume rules, then [collection-and-analysis.md](references/collection-and-analysis.md)
107
+ for the execution sequence.
108
+
109
+ ## Collect and interpret
110
+
111
+ Use `OS_URL` and `OS_API_KEY` through the bundled provider adapters. Read
112
+ [provider-contract.md](references/provider-contract.md) before paid collection.
113
+ Bound the requested source/sample scope to the assignment and available budget;
114
+ save asynchronous handles and resume them instead of duplicating paid runs.
115
+
116
+ Read [analysis-and-adaptation.md](references/analysis-and-adaptation.md) before
117
+ interpreting evidence. Captions, metrics, comments, transcripts and frames support
118
+ different claims. A caption is not a viewed opening frame; a high view count is
119
+ not proof that a format caused performance. Keep source claims distinct from
120
+ claims the product can substantiate.
121
+
122
+ The bundled media analyzer supplies content-bound receipts for visual/verbal
123
+ claims; [visual-analysis-prompt.md](references/visual-analysis-prompt.md) defines
124
+ its extraction scope. Missing media may leave useful caption, metric or comment
125
+ evidence. Record the gap rather than inventing an analysis or treating limited
126
+ coverage as complete.
127
+
128
+ ## Return a traceable result
129
+
130
+ Write `analysis.json` using [output-contract.md](references/output-contract.md).
131
+ The renderer produces `result.md`; the finalizer seals its evidence, coverage and
132
+ collection time in `receipt.json`. Do not hand-author either generated file.
133
+ Return the result and its limitations, with source-backed findings and feasible
134
+ adaptations where supported. Empty findings are valid when evidence is thin.
135
+
136
+ For PMR, return the validated result to its finalizer; do not edit the combined
137
+ report or publish a competing section. For direct use, present the same result
138
+ without requiring a PMR report. Business choices, launch plans and ongoing
139
+ evaluation remain outside this collection's receipt.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Organic Trend Watch"
3
+ short_description: "Research and adapt TikTok and Reels evidence"
4
+ default_prompt: "Use $egbe-os-organic-trend-watch to answer a short-video research question for this product using TikTok and Instagram Reels evidence."
@@ -0,0 +1,54 @@
1
+ # Research analysis and adaptation
2
+
3
+ Use the assignment to decide which observations matter. The following are
4
+ analytical lenses, not a required checklist for every video.
5
+
6
+ ## Compare evidence in context
7
+
8
+ Compare relevant examples, including contrary cases. Account size, audience,
9
+ publication time, distribution, sponsorship and missing metrics can explain
10
+ differences; descriptive ratios do not isolate a creative's causal effect.
11
+ Separate observed facts, plausible interpretations and unanswered questions.
12
+ Do not turn a selected sample into a claim about the whole platform.
13
+
14
+ Start each finding from exact source evidence, then group observations that
15
+ actually share the claimed mechanism. Explain what they have in common and the
16
+ limits of that comparison. Repetition alone does not establish generality or
17
+ success. No minimum number of sources turns an interpretation into a fact.
18
+
19
+ ## Inspect the parts relevant to the question
20
+
21
+ - **Opening and promise:** distinguish what can catch attention in the first
22
+ frame from the reason to keep watching. Check how the later material delivers
23
+ that promise. Support visual claims with inspected frames and spoken claims
24
+ with transcript evidence, not captions or engagement totals.
25
+ - **Demonstration and proof:** identify what is shown, what is merely asserted,
26
+ and how a source establishes credibility. Attribute its datasets, rankings,
27
+ testimonials and results to that source; they are not the product's proof.
28
+ - **Format, message and action:** describe the observable structure and intended
29
+ viewer action. Consider alternatives such as a demonstration, comparison,
30
+ explanation or recurring format only when they fit the evidence and product.
31
+ - **Sound and context:** consider how audio relates to the scene, audience and
32
+ meaning when evidence allows. A sound's age or one video's views do not prove
33
+ it is rising, saturated or responsible for performance.
34
+ - **Audience language:** distinguish comments about the intended buyer/problem
35
+ from jokes, creator affinity and unrelated topics. Quote or reference actual
36
+ comments; topic analogy is not buyer relevance. Visible commenters are a
37
+ selected sample, not a demand survey.
38
+
39
+ ## Propose grounded adaptations
40
+
41
+ Explain which source mechanism is useful for this product and why. Keep the
42
+ observed example separate from a drafted opening, promise or demonstration.
43
+ Adapt the mechanism rather than copying a creator's proprietary evidence or
44
+ promising their performance.
45
+
46
+ Consider the product's real assets, production effort, repeatability and audience
47
+ fit. When an idea depends on a customer result, dataset, footage or capability
48
+ that is not available, state that dependency or propose an honest alternative.
49
+ A series, character, comparison or list is an option—not a required format.
50
+
51
+ Return only adaptations justified by the assignment and sources. Avoid numerical
52
+ impact/difficulty scores, fixed idea quotas and universal creative rules without
53
+ evidence. The result informs the product's next decision; it does not itself
54
+ choose a business goal, authorize publishing or prove growth.
@@ -0,0 +1,117 @@
1
+ # Collection and analysis
2
+
3
+ Use the absolute roots from `SKILL.md`; script paths belong to the installed
4
+ skill and mutable paths to the product study.
5
+
6
+ ## 1. Initialize or resume
7
+
8
+ For direct use, initialize with the scoped question and product context:
9
+
10
+ ```bash
11
+ python3 "$ORGANIC_TREND_SKILL_ROOT/scripts/run-state.py" --runtime-root "$RUNTIME_ROOT" \
12
+ init --assignment "Compare demonstrations that explain this product's workflow" \
13
+ --product-context "The product, intended audience and relevant constraints" \
14
+ --discovery-limit-per-account 12 --lookback-days 21
15
+ ```
16
+
17
+ For an existing caller-provided `context.json`, validate it and run `init`
18
+ without replacing it. Inspect `status` before continuing:
19
+
20
+ ```bash
21
+ python3 "$ORGANIC_TREND_SKILL_ROOT/scripts/validate-context.py" --context "$RUNTIME_ROOT/context.json"
22
+ python3 "$ORGANIC_TREND_SKILL_ROOT/scripts/run-state.py" --runtime-root "$RUNTIME_ROOT" init
23
+ python3 "$ORGANIC_TREND_SKILL_ROOT/scripts/run-state.py" --runtime-root "$RUNTIME_ROOT" status
24
+ ```
25
+
26
+ Resume saved steps and matching provider handles. `init` does not refresh data
27
+ or authorize another paid collection. A changed assignment needs a new study;
28
+ an explicit refresh is separate from retrying. See `runtime-contract.md`.
29
+ Choose the per-account limit and lookback from the assignment and budget; the
30
+ flags above are examples, not a required sample. Omitted values default to 30/60.
31
+ Existing caller-provided context already owns these parameters; `init` does not
32
+ override them. `--max-analysis-videos` separately caps total selected observations.
33
+
34
+ ## 2. Identify and collect sources
35
+
36
+ Find public TikTok/Reels accounts relevant to the question. Competitors, adjacent
37
+ products, creators or partners may provide evidence; no account class is
38
+ mandatory. OS search may locate handles, not substitute for collected video data.
39
+
40
+ Write `raw/accounts.json` as `{"accounts":[...]}` using the schema in
41
+ `runtime-contract.md`. Mark discovery complete with `complete-step --step discovery`.
42
+ Build discovery inputs:
43
+
44
+ ```bash
45
+ python3 "$ORGANIC_TREND_SKILL_ROOT/scripts/build-provider-inputs.py" --runtime-root "$RUNTIME_ROOT" --mode discovery
46
+ ```
47
+
48
+ Read `provider-contract.md`, then run each applicable platform's canonical run:
49
+
50
+ ```bash
51
+ python3 "$ORGANIC_TREND_SKILL_ROOT/scripts/run-apify.py" \
52
+ --runtime-root "$RUNTIME_ROOT" --key tiktok-discovery \
53
+ --actor-id clockworks/tiktok-scraper --platform tiktok --kind discovery \
54
+ --input-file "$RUNTIME_ROOT/raw/tiktok-discovery-input.json" \
55
+ --accounts-file "$RUNTIME_ROOT/raw/accounts.json" --output raw/tiktok-discovery.json
56
+ ```
57
+
58
+ `--start-only` saves the handle before returning; repeat the same command to poll
59
+ and retrieve its dataset. Never replace a started run's input. Normalize once
60
+ to freeze the requested analysis sample after time-window filtering. Unknown-date
61
+ and out-of-window observations remain in raw/normalized evidence with explicit
62
+ counts, but do not enter account medians, selection, or paid enrichment.
63
+ If the question needs evidence not already
64
+ available from discovery, build `--mode enrichment` inputs and run the needed
65
+ batches within the collection budget. Otherwise continue with discovery evidence;
66
+ there is no mandatory extra paid call. Preserve needed but unavailable evidence
67
+ as gaps rather than broadening the conclusion. The runner maintains the raw manifest;
68
+ do not hand-author provenance or mark provider failures as successes. A terminal
69
+ failure may support a partial result alongside successful datasets; record its
70
+ gap as specified in `provider-contract.md`. Active/uncertain runs block sealing.
71
+
72
+ ```bash
73
+ python3 "$ORGANIC_TREND_SKILL_ROOT/scripts/normalize-videos.py" --runtime-root "$RUNTIME_ROOT"
74
+ ```
75
+
76
+ Normalize again if enrichment added evidence, without changing the frozen sample.
77
+ Mark `collection` and `normalization` complete once required discovery and all
78
+ started runs have settled. The same
79
+ `run-state.py ... complete-step --step <name>` command records each step; sealing
80
+ validates evidence and provider state, not just these progress flags.
81
+
82
+ ## 3. Inspect available evidence
83
+
84
+ When audiovisual evidence is needed, use the canonical preparation pipeline for
85
+ the selected observations to inspect. Skip media calls for questions fully
86
+ answered by available captions, metrics or comments:
87
+
88
+ ```bash
89
+ python3 "$ORGANIC_TREND_SKILL_ROOT/scripts/prepare-visual-evidence.py" \
90
+ --runtime-root "$RUNTIME_ROOT" --observation-id "$OBSERVATION_ID"
91
+ python3 "$ORGANIC_TREND_SKILL_ROOT/scripts/analyze-visual-evidence.py" \
92
+ --runtime-root "$RUNTIME_ROOT" --observation-id "$OBSERVATION_ID"
93
+ ```
94
+
95
+ Preparation records provider-media/frame provenance; the analyzer uses OS and
96
+ reuses matching content-bound receipts. Do not replace these receipts with
97
+ agent-written claims or another tool's output. Media failure remains a coverage
98
+ gap, not evidence of an unsuccessful creative. Captions, metrics and comments
99
+ can still support their own narrower findings.
100
+
101
+ Apply `analysis-and-adaptation.md` and write `analysis.json` per
102
+ `output-contract.md`. Include only analytical fields actually supported. Missing
103
+ selected observations remain explicit partial coverage, not fabricated entries.
104
+ Record missing evidence and contrary observations.
105
+ Mark `visual_analysis` and `synthesis` complete after validating that analysis.
106
+
107
+ ## 4. Render and seal
108
+
109
+ ```bash
110
+ python3 "$ORGANIC_TREND_SKILL_ROOT/scripts/render-result.py" --runtime-root "$RUNTIME_ROOT"
111
+ python3 "$ORGANIC_TREND_SKILL_ROOT/scripts/run-state.py" --runtime-root "$RUNTIME_ROOT" complete-step --step render
112
+ python3 "$ORGANIC_TREND_SKILL_ROOT/scripts/finalize-receipt.py" --runtime-root "$RUNTIME_ROOT"
113
+ python3 "$ORGANIC_TREND_SKILL_ROOT/scripts/validate-runtime.py" --workspace "$WORKSPACE_ROOT"
114
+ ```
115
+
116
+ Return `result.md` with its complete, partial or no-data coverage. A valid sealed
117
+ receipt certifies provenance, not universal research completeness or causality.