@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,219 @@
1
+ # OpenAI Ads API reference
2
+
3
+ Paths in this reference are relative to `$OS_URL/ads/openai` unless shown in full.
4
+ This is the API boundary, not the lifecycle checklist. Follow the selected workflow
5
+ for artifact updates and completion conditions.
6
+
7
+ Use `$OS_URL/ads/openai/...` with `Authorization: Bearer $OS_API_KEY`.
8
+ Requires the `ads` scope. Management and conversion provider keys stay inside
9
+ Egbe infrastructure; never request them for the product or call OpenAI directly.
10
+ This workflow works from any product repository, without scaffold or stages.
11
+
12
+ Read `GET /ads/openai/account` first. Successful authentication does not prove
13
+ billing setup, approval to serve, or access to conversion setup. The API returns
14
+ account currency/timezone; this version supports USD accounts and daily budgets
15
+ only. OpenAPI at `$OS_URL/openapi.json` is the exact request schema.
16
+
17
+ ## Build and manage a campaign
18
+
19
+ Every mutation requires `Idempotency-Key`. Keep a stable key and the exact body
20
+ for each logical operation; reuse both after a timeout. An ambiguous create
21
+ returns a recovery error rather than blindly creating another object. Do not
22
+ use a new key to bypass it. Save returned IDs in the project's campaign records.
23
+
24
+ An unfinished mutation can return `openai_ads_operation_superseded` after a newer
25
+ command, or `openai_ads_provider_state_changed` after external drift. Do not
26
+ revive the old intent; read current state and reconcile with the latest authorized
27
+ request. `openai_ads_wallet_reservation_not_live` requires wallet/campaign review
28
+ before a newly authorized operation; retries do not renew expired reservations.
29
+
30
+ 1. Resolve the desired geography with `GET /ads/openai/locations?query=...`.
31
+ 2. `POST /ads/openai/campaigns`:
32
+
33
+ ```json
34
+ {"name":"Product launch","product_slug":"your-product","daily_budget_usd":25,
35
+ "bidding_type":"clicks","location_ids":["<id returned by locations>"],"status":"PAUSED"}
36
+ ```
37
+
38
+ Select `clicks`, `impressions` or `conversions` before creation. Strategy and
39
+ an oCPC optimization goal cannot be changed later. Conversion bidding
40
+ additionally requires an owned `conversion_event_setting_id` and provider
41
+ account access; ordinary traffic campaigns do not require tracking setup.
42
+ 3. `POST /ads/openai/uploads` with `{product_slug,image_url}` for a public image.
43
+ Use the returned `id` as `creative.file_id`. For a local image, first store it
44
+ with `POST /tools/ad-assets/upload` (`content_base64` up to about 512 KiB) or an
45
+ upload session (`POST /uploads`, `/uploads/{upload_id}/parts`,
46
+ `/uploads/{upload_id}/complete`) and use the returned `data.url` as `image_url`.
47
+ 4. `POST /ads/openai/ad-groups` with `{campaign_id,name,context_hints,bidding_config}`.
48
+ `bidding_config` contains `billing_event_type` (`click` or `impression`) and
49
+ `max_bid_micros`. For conversion bidding use `click`; the bid is CPA, while
50
+ billing is still per click. With impressions the bid is CPM. Money here is
51
+ integer micros in account currency, not dollars.
52
+ 5. `POST /ads/openai/ads` with `{ad_group_id,name,creative}`. The complete creative
53
+ is `{type:"chat_card",title,body,target_url,file_id}`: title 3–50 characters,
54
+ body 1–100 characters. Use a real product destination with stable campaign UTMs.
55
+ Read `/analytics/skill` for product attribution conventions. Keep captured
56
+ `oppref` intact; UTMs do not replace the provider click identifier.
57
+
58
+ Resources are created paused. GET `/campaigns/{id}`, `/ad-groups/{id}` and
59
+ `/ads/{id}` for readback, including provider ad review state. List the same
60
+ collections with `offset` and `limit`; only owned resources are returned.
61
+ Group `campaign_id` and ad `ad_group_id` are filled from the durable Registry
62
+ binding if omitted by the provider. `parent_binding_source` is `registry` in that
63
+ case, or `provider_verified_against_registry` when provider and Registry agree.
64
+ A conflicting parent returns `openai_ads_parent_binding_mismatch`, never a silent
65
+ overwrite. These fields are included in create/update readbacks too.
66
+
67
+ Edit existing resources with POST to their by-ID endpoint. Campaign updates
68
+ accept `name`, `daily_budget_usd`, `location_ids`; ad-group updates accept `name`,
69
+ `context_hints`, `bidding_config`; ad updates accept `name`, full `creative`.
70
+ Do not recreate an ad merely to change its copy.
71
+
72
+ ### Select campaign measurement goals without changing bidding
73
+
74
+ For an existing `clicks` or `impressions` campaign, POST `/campaigns/{id}` with:
75
+
76
+ ```json
77
+ {"conversion_event_setting_ids":["<owned signup setting>","<owned purchase setting>"]}
78
+ ```
79
+
80
+ This replaces the campaign's entire measurement selection; read the current IDs
81
+ first and preserve any still wanted. `[]` explicitly clears it; omission leaves
82
+ it unchanged. Egbe accepts up to 100 unique IDs (its bounded API limit, not a
83
+ claim about provider limits). Every setting and its source must belong to this
84
+ product/account, and the setting must be active. No settings are auto-attached.
85
+ Send only this field to keep bidding, budget, status and targeting unchanged;
86
+ the gateway verifies those invariants and the selected IDs in provider readback.
87
+ Use a recorded Idempotency-Key. A provider rejection or readback mismatch is not
88
+ successful attachment and does not authorize recreating or launching a campaign.
89
+ For `conversions` campaigns, the single optimization goal remains immutable.
90
+ See [official campaign update rules](https://developers.openai.com/ads/api-reference/campaigns#update-a-campaign).
91
+
92
+ When launch is authorized, keep the campaign paused while enabling the intended
93
+ children with `POST /ad-groups/{id}/status?status=active` and
94
+ `POST /ads/{id}/status?status=active`, then `POST /campaigns/{id}/launch`.
95
+ Launch reserves funds through the existing wallet. It does not promise delivery:
96
+ children, creative review, account/payment readiness and actual insights matter.
97
+ Pause using `/campaigns/{id}/pause`; child status also accepts `paused`.
98
+
99
+ Daily budget is an **average**, not a hard daily cap: with an unchanged budget,
100
+ provider spending can reach 2× per day and 7× over a full seven-day period.
101
+ The wallet reservation accounts for the possible daily maximum; it is not a
102
+ replacement for provider spend reconciliation or a guarantee of seven-day funds.
103
+ Provider market/bid restrictions may exceed the static schema minimum.
104
+ See the [minimum-budget note](../workflows/readiness.md#minimum-daily-budget) before
105
+ proposing a budget; a provider rejection during creation may reveal the current floor.
106
+
107
+ ## Read serving diagnostics
108
+
109
+ Add `include_serving_issues=true` to GET `/campaigns/{id}`, `/ad-groups/{id}`
110
+ or `/ads/{id}` to request the provider's `serving_issues` alongside the saved
111
+ resource. The same optional boolean works on all three collection GETs with
112
+ `offset` and `limit`; follow `next_offset` until null when inspecting the full
113
+ owned inventory. Omitting it or sending false keeps the usual read behavior.
114
+ Egbe translates it to the provider's `include[]=serving_issues`; do not send
115
+ raw provider query parameters to OS. These are read-only operations and need no
116
+ `Idempotency-Key` or provider credentials.
117
+
118
+ For a known ad, read its parent group and campaign too, using the returned
119
+ owned parent bindings. OS responses have the usual envelope: a single resource
120
+ is in `data`; a collection has rows in `data.data` and pagination in
121
+ `data.next_offset`. Preserve each resource ID, observed status/review state,
122
+ returned issue codes and fetch time. Codes can include `campaign_not_active`,
123
+ `ad_group_not_active`, `ad_in_review`, `review_not_approved` or
124
+ `landing_page_crawl_issue`, as well as account/payment/budget reasons. Keep
125
+ unrecognized codes as evidence rather than dropping them or guessing a remedy.
126
+
127
+ A returned empty list means no serving issues were reported for that read;
128
+ it does not guarantee delivery. An absent field means diagnostics are unknown,
129
+ and a failed request remains an error, not an empty list. Saved creative approval
130
+ and target URL describe that saved version: after a rejected URL update they do
131
+ not establish approval of the proposed destination. Serving diagnostics do not
132
+ provide a destination-domain review submission/status endpoint, review ETA or
133
+ proof that manual verification is required. Report those gaps explicitly.
134
+ See [official serving diagnostics](https://developers.openai.com/ads/troubleshooting#serving-issues).
135
+
136
+ ## Optional conversions
137
+
138
+ Use only when measurement or conversion optimization is part of the request.
139
+ For ordinary campaign creation, do not force this setup.
140
+
141
+ - `POST /conversion-sources` with `{product_slug,name}` creates a product-owned
142
+ web source. Save its `id` and returned `resource.pixel_id`.
143
+ - `POST /conversion-settings` with `{source_id,name,event_type}` creates a goal.
144
+ Supported events: `registration_completed`, `order_created`,
145
+ `subscription_created`, `trial_started`, `lead_created`.
146
+ - GET `/conversion-sources` and `/conversion-settings` for owned configuration.
147
+ Provider setup may return 403/404 when not enabled for the account. Report
148
+ that blocker; do not borrow another product's pixel or create new API keys.
149
+
150
+ For browser tracking, use the returned public Pixel ID and follow the official
151
+ [Pixel instructions](https://developers.openai.com/ads/measurement-pixel).
152
+ Respect measurement consent; automatic advanced matching must not collect data
153
+ before consent. No conversion API credential belongs in the browser.
154
+
155
+ Server delivery is `POST /conversion-events` with:
156
+
157
+ ```json
158
+ {"source_id":"<owned source id>","event_id":"<stable business event id>",
159
+ "event_type":"registration_completed","timestamp_ms":1788951369000,
160
+ "source_url":"https://your-product.example/signup/complete",
161
+ "measurement_consent":true,"oppref":"<captured original value>","validate_only":true}
162
+ ```
163
+
164
+ Use the real event time, not the sample. Capture `oppref` when present and the
165
+ Pixel's `__obref` cookie as optional `obref`, subject to consent. Omit unavailable
166
+ identifiers rather than inventing them. This release doesn't need raw email or
167
+ other customer PII. On payment events, optional `amount_minor` + `currency`
168
+ represent actual money (e.g. 2500 USD means $25), not micros. `plan_id` is optional
169
+ for subscription/trial events. Signup means successful account creation; purchase
170
+ means confirmed payment, not a Checkout redirect or trial start. Integrate with
171
+ the product's authoritative completion points; no automatic payment-gateway
172
+ conversion emission is provided by this release.
173
+
174
+ Start with `validate_only:true`, then send real events only when appropriate.
175
+ Reuse the same `event_id` as the browser Pixel's `event_id` for the same event
176
+ and source. API delivery dedupes by product/source/event identity, not just the
177
+ request key. GET `/conversion-events/{receipt_id}` reads delivery status.
178
+ Retries are caller-driven, bounded to five attempts with receipt backoff; there
179
+ is no hidden delivery worker. API acceptance does not prove attribution.
180
+
181
+ ## Reports
182
+
183
+ GET `/campaigns/{id}/results?start_time=<unix seconds>&end_time=<unix seconds>`.
184
+ The gateway rounds the start down and the end up to full hours in the ad account
185
+ timezone, capped at the latest completed hour (never a future boundary).
186
+ Do not send future timestamps.
187
+ Use the returned `start_time`/`end_time` as the effective reporting period;
188
+ the currently incomplete hour is picked up on a later read. A period with no
189
+ completed hour returns `503 openai_ads_report_not_available_yet`, not zero.
190
+ Follow `next_cursor` as `after` until `has_more` is false before summing pages.
191
+ Response includes currency, timezone, period, fetch time and data availability.
192
+ `metrics` uses shared names (impressions, clicks, spend_usd, fractional ctr,
193
+ cpc_usd, conversions) with `metrics_scope:"page"`. It covers only returned rows:
194
+ sum all pages before reporting totals and recompute ratios from totals. Missing
195
+ metrics remain null; non-USD money is not relabeled USD. Delivery reports leave
196
+ conversions null; use the separate attribution report when needed.
197
+ `no_rows`, numeric zero, and request failure are different outcomes. Provider
198
+ freshness is unknown unless explicitly reported. General insights are delivery
199
+ metrics; never relabel clicks or accepted server events as attributed conversions.
200
+
201
+ GET `/campaigns/{id}/conversion-results` with the same Unix period for attributed
202
+ campaign totals. `conversions` means click-through conversions; view-through is
203
+ separate and must not be added to it. Account availability can limit this report.
204
+ This is a campaign total, not a breakdown by event setting. If signup and purchase
205
+ are both selected, do not label the total as signups or purchases or infer unique
206
+ customers. The exposed report has no event-setting filter. Use product analytics
207
+ for separate funnel counts and distinguish those from OpenAI-attributed totals.
208
+
209
+ Safe report/account reads retry transient network errors, 429 and 5xx up to
210
+ three attempts with bounded backoff. Long `Retry-After` values defer recovery
211
+ to a later request; errors are not converted into zero metrics. Writes and
212
+ conversion submissions are not automatically replayed by this transport.
213
+ Wallet reconciliation retries on its normal schedule and settles only the
214
+ unaccounted cumulative spend, including spend missed during a failed read.
215
+
216
+ This capability has no raw passthrough, lifetime budgets, product feeds or custom
217
+ audiences. Provider contracts: [Campaigns](https://developers.openai.com/ads/api-reference/campaigns),
218
+ [OpenAPI](https://developers.openai.com/ads/openapi.json),
219
+ [Conversions API](https://developers.openai.com/ads/conversions-api).
@@ -0,0 +1,169 @@
1
+ # Campaign artifacts and continuation
2
+
3
+ All paths are relative to the actual product repository root, not the current
4
+ shell directory or an instance workspace. Reuse its existing `marketing/` tree.
5
+ Do not require PRD, scaffold, heartbeat or git remotes merely to manage a campaign.
6
+
7
+ ```text
8
+ egbe-docs/marketing/campaigns/openai/
9
+ channel-readiness.json
10
+ campaigns.json
11
+ <openai-campaign-slug>/
12
+ creatives.json
13
+ tracking.json
14
+ campaign-state.json
15
+ launch-readback.json
16
+ operations.json
17
+ change-log.md
18
+ monitoring/
19
+ check-<UTC-timestamp>.md
20
+ ```
21
+
22
+ Create files when their phase needs them, not empty placeholders for every future
23
+ phase. Store public creative assets beside `creatives.json` or link existing
24
+ repo-relative assets. No credentials, raw customer emails, click identifiers,
25
+ session cookies or customer conversion payloads belong in these artifacts.
26
+
27
+ Through the Egbe connector without a project folder, keep these records at the
28
+ same paths in Egbe's artifact store, as `egbe-os-quickstart` →
29
+ `references/artifact-sync.md` ("Through the Egbe connector") describes. Save a
30
+ write's request record there before sending the write.
31
+
32
+ ## Resolve exactly one campaign
33
+
34
+ `campaigns.json` example:
35
+
36
+ ```json
37
+ {
38
+ "channel": "openai",
39
+ "selected_campaign": "openai-discovery-001",
40
+ "campaigns": [{
41
+ "campaign_slug": "openai-discovery-001",
42
+ "campaign_path": "egbe-docs/marketing/campaigns/openai/openai-discovery-001",
43
+ "utm_campaign": "openai-discovery-001"
44
+ }]
45
+ }
46
+ ```
47
+
48
+ An explicit campaign ID/slug in the task wins over the selected pointer. Resolve
49
+ the ID against recorded state; zero/ambiguous matches require an OS owned-resource
50
+ read, not a guessed campaign or a new create. For an existing campaign with no
51
+ local history, reconstruct its factual IDs/readback and label unknown history.
52
+ Missing historical documents do not block reads or an authorized emergency pause.
53
+
54
+ Use one stable `openai-` slug for the folder and `utm_campaign`. Provider names
55
+ may include an OS recovery suffix: names are not IDs. Preserve supplied durable
56
+ `business_id`, `product_id`, `launch_id`, `experiment_id`, `variant_id` in the index
57
+ entry when provided by a promotion caller. Do not fabricate these for standalone
58
+ work or put scheduler/session/task IDs into the campaign domain contract.
59
+
60
+ ## Inputs and tracking
61
+
62
+ - `channel-readiness.json`: `{channel:"openai", product_slug, checked_at,
63
+ account:{id,currency_code,timezone}, blockers:[]}`; add observed payment,
64
+ delivery and conversion-setup availability, distinguishing unknown from false.
65
+ - The optional index `plan_path` may link a caller-provided instruction/configuration
66
+ document by repository-relative path. No particular document or format is required.
67
+ - `creatives.json`: `{ad_groups:[{slug,context_hints,bidding_config}],
68
+ ads:[{slug,ad_group_slug,title,body,target_url,asset_path}]}`. Slugs are local
69
+ planning identities; provider IDs go in campaign-state. Record asset provenance
70
+ and claim support as needed. This document is not an API payload.
71
+ - `tracking.json`: `{destination_url,utm:{source:"openai",medium:"paid_ai",
72
+ campaign:<slug>,content:<ad-slug>},tracking_state:"active|degraded|blocked",
73
+ analytics:{product_slug,campaign_attribution:"available|unavailable|unverified"},
74
+ conversions:{state:"not_configured|configured|verified|unavailable"}}`.
75
+ Record verification evidence and limits; `configured` does not mean attributed.
76
+ Each ad uses the same campaign UTM and its own stable `utm_content`.
77
+
78
+ ## Execution state versus evidence
79
+
80
+ `campaign-state.json` minimum after a campaign has been created or recovered:
81
+
82
+ ```json
83
+ {
84
+ "channel": "openai",
85
+ "campaign_slug": "openai-discovery-001",
86
+ "product_slug": "example-product",
87
+ "status": "paused",
88
+ "budget": {"daily_budget_usd": 25, "currency": "USD"},
89
+ "objects": {
90
+ "campaign_id": "cmpn_example",
91
+ "file_ids": ["file_example"],
92
+ "ad_groups": [{"id": "group_example", "campaign_id": "cmpn_example"}],
93
+ "ads": [{"id": "ad_example", "ad_group_id": "group_example", "file_id": "file_example"}]
94
+ },
95
+ "updated_at": "2026-09-09T12:00:00Z"
96
+ }
97
+ ```
98
+
99
+ This is a concise factual execution summary. Desired changes remain in requested
100
+ configuration and pending operations until read back. Use `status:"unknown"` after an
101
+ uncertain mutation; never claim paused/active from intent. Optional `blockers`,
102
+ `delivery_state`, `source_id`, `pixel_id`, `conversion_event_setting_id` and factual
103
+ launch/pause timestamps can be added. Keep source/goal bindings when configured.
104
+
105
+ `launch-readback.json` is a timestamped OS observation, not desired state:
106
+ `{observed_at,campaign:<GET data>,ad_groups:[<GET data>],ads:[<GET data>]}`.
107
+ Preserve provider fields, IDs, parent bindings, statuses, budget and destination.
108
+ Refresh this snapshot after relevant mutations; use change-log and monitoring
109
+ files for history. Read/list all owned children and filter by exact parent IDs to
110
+ detect unexpected children, not just the IDs already present in local state.
111
+
112
+ ## Durable operations and interrupted work
113
+
114
+ Before a management mutation, write/update `operations.json`:
115
+
116
+ ```json
117
+ {
118
+ "operations": [{
119
+ "operation_id": "create-campaign-1",
120
+ "method": "POST",
121
+ "path": "/ads/openai/campaigns",
122
+ "idempotency_key": "openai-discovery-001-create-1",
123
+ "payload": {"name":"openai-discovery-001","product_slug":"example-product","daily_budget_usd":25,"location_ids":["resolved-location-id"],"status":"PAUSED"},
124
+ "status": "prepared",
125
+ "result_ids": []
126
+ }]
127
+ }
128
+ ```
129
+
130
+ States: `prepared`, `unconfirmed`, `succeeded`, `failed`. Persist the exact method,
131
+ relative path (including query parameters), payload and key before sending. Update
132
+ the same entry after each attempt; keep IDs/readback even if later steps fail.
133
+ Timeout/disconnection is `unconfirmed`, not `failed`. Retry only with that exact
134
+ request/key. A changed desired operation gets a new entry/key only after resolving
135
+ the previous outcome. Provider response saying Egbe team reconciliation is required
136
+ is a stopping condition, not an invitation to generate another key. Do not launch
137
+ with unresolved prepared/unconfirmed management writes.
138
+
139
+ Do not journal customer conversion bodies here: runtime event IDs, consent,
140
+ retry state and delivery receipts belong in the product's protected server store.
141
+ `tracking.json` records the integration and verification, not per-customer data.
142
+
143
+ `change-log.md` is append-only: UTC timestamp, operation, reason/evidence,
144
+ authorization reference, before/after, IDs, result and any next recovery action.
145
+ Saved read-only observations include request bounds, returned bounds, fetch time,
146
+ sources, currency, metrics and availability/attribution gaps. Simple reads need
147
+ no new files or change-log entry.
148
+
149
+ ## Phase self-check
150
+
151
+ Run `scripts/validate-openai-artifacts.py --product-root <root> --phase <phase>`.
152
+ Use `--campaign <slug>` for an explicit campaign instead of the selected pointer.
153
+
154
+ | Phase | Required evidence |
155
+ |---|---|
156
+ | readiness | channel-readiness (may honestly contain blockers) |
157
+ | creative-assembly | campaign index and creatives; validate an index plan_path when supplied |
158
+ | tracking | index, tracking |
159
+ | build-paused | index, state, complete paused readback, creatives, tracking, operations, change-log |
160
+ | launch | same execution evidence, active intended path, no unresolved operations |
161
+ | edit | index, state/readback, operations and change-log; not a new build checklist |
162
+ | recovery | index, operations, change-log and partial factual state if an ID is known; missing children allowed |
163
+ | monitoring | index, state, saved timestamped observation; other historical files optional |
164
+ | pause | index, state/readback showing paused campaign, change-log |
165
+
166
+ The checker is local and read-only. It checks JSON, paths, IDs/parents, UTMs,
167
+ state/readback agreement, not live freshness, permissions, marketing merit or
168
+ whether an observation is true. A blocked but factual record is useful output;
169
+ passing structure alone never makes a blocked campaign launchable.
@@ -0,0 +1,40 @@
1
+ # Paused build and recovery
2
+
3
+ Read [artifacts](../runtime/artifacts.md) and [API operations](../runtime/api-reference.md).
4
+ For new or changed images also read [Chat-card production](../creative/chat-card.md).
5
+ This workflow creates/repairs only the authorized planned objects, all paused.
6
+ It does not activate them or expand the approved campaign scope.
7
+ Check the [minimum-budget note](readiness.md#minimum-daily-budget) before creation.
8
+
9
+ 1. Resolve the selected campaign, requested configuration, creatives, tracking and
10
+ recorded operations. If resuming, read existing owned objects before creating.
11
+ 2. Resolve outstanding `prepared/unconfirmed` operations with their saved exact
12
+ key and payload. Reconstruct missing local evidence from owned readbacks;
13
+ never reset the operation journal to escape a conflict.
14
+ 3. Create or reuse the paused campaign with the approved daily budget, geo IDs and
15
+ immutable bidding choice. Save the returned ID immediately. Provider name
16
+ suffixes are expected; keep the local slug and UTM stable.
17
+ 4. Upload/reuse the approved images; save file IDs. Create only missing planned
18
+ ad groups, then ads with those file IDs and tracked destinations. Journal every
19
+ write before sending and persist each successful result before the next write.
20
+ 5. Read campaign, children, budgets, creatives and destinations through OS. List
21
+ owned children with pagination and filter exact campaign/group parents to find
22
+ drift beyond recorded IDs. An extra active/unapproved object is not permission
23
+ to adopt or delete it silently.
24
+ Preserve `parent_binding_source`: `registry` is durable creation linkage, not
25
+ independent provider confirmation; `provider_verified_against_registry` means
26
+ both agree. Either supports the structural parent check. Conflicts are errors,
27
+ not fields the agent should repair in local evidence.
28
+ 6. Write the factual state, readback and change log. Run `--phase build-paused`
29
+ when the planned tree is complete; use `--phase recovery` for a partial result.
30
+
31
+ On partial failure preserve IDs, exact pending requests and successful observations.
32
+ Stop blind retries on unknown outcome; source/upload recovery may require Egbe team
33
+ reconciliation. An empty paused campaign is incomplete but does not spend; do not
34
+ create a replacement shell to make the task look successful. If an unexpected live
35
+ object can spend, apply an authorized safety pause and record it, or urgently request
36
+ founder action if pause is outside the task authority.
37
+
38
+ Done means the planned objects exist and have matching paused readback, not merely
39
+ a successful campaign-create response. Return incomplete work honestly with the
40
+ specific unfinished operation and its recovery instructions.
@@ -0,0 +1,40 @@
1
+ # Optional browser and server conversions
2
+
3
+ Read the conversion section of [API reference](../runtime/api-reference.md) for
4
+ the exact fields, supported event types, units, consent and delivery retries.
5
+ Ordinary traffic campaign build/launch does not require this workflow.
6
+
7
+ 1. Map the requested canonical product event to an OpenAI event
8
+ without confusing signup start with completed signup,
9
+ Checkout redirect with payment, or trial start with a purchase.
10
+ 2. Find the recorded owned source/pixel and goal. Reuse them when compatible;
11
+ do not create a new source per follow-up. For new setup, journal creation,
12
+ save IDs immediately and record account-access failures without borrowing
13
+ another product's pixel or requesting provider keys.
14
+ 3. Select campaign measurement explicitly. Creating source/event settings alone
15
+ does not attach them to an existing campaign. For `clicks`/`impressions`, use
16
+ the [measurement update](../runtime/api-reference.md#select-campaign-measurement-goals-without-changing-bidding)
17
+ to set the intended complete list, then save readback of its IDs and unchanged
18
+ bidding, budget and status. Do not switch to conversion bidding to add tracking.
19
+ For oCPC, select one optimization goal at creation; it cannot be changed later.
20
+ 4. Implement browser Pixel through official instructions when requested, with
21
+ consent. Implement server delivery through OS at the product's authoritative
22
+ outcome point, using its existing server storage for event identity, consent
23
+ and retries. Persist `oppref`/`obref` only as allowed; never put them in campaign
24
+ files. Preserve ordinary product events and existing app conventions.
25
+ 5. Browser and server for the same event share a stable business event ID.
26
+ Validate first with `validate_only:true`. Record configuration and redacted
27
+ verification evidence in tracking; protected runtime storage retains actual
28
+ event bodies, IDs and receipts. Delivery retry is bounded and caller-driven,
29
+ not provided by an invisible OS worker. Inspect receipts on uncertain responses.
30
+ 6. Separate integration verification, provider acceptance and attributed results.
31
+ A test delivery cannot prove an ad-attributed sale. If setup/report access is
32
+ unavailable, report that limit and keep an ordinary traffic campaign independent.
33
+ Campaign conversion totals are not event-specific signup/purchase counts.
34
+ Finish integration with evidence of source, event delivery and campaign selection;
35
+ confirm ad attribution separately when eligible traffic and reports are available.
36
+
37
+ Only select conversion bidding when explicitly intended and owned setup is suitable.
38
+ It must be chosen at campaign creation; measurement added to an existing traffic
39
+ campaign does not change bidding or authorize creating a replacement campaign.
40
+ Do not automatically generate customer events or send them without valid consent.
@@ -0,0 +1,24 @@
1
+ # Creative and targeting assembly
2
+
3
+ Use the requested context hints, destination, daily budget, bidding, copy and
4
+ assets. Resolve missing operation inputs before writing. For a copy edit,
5
+ preserve unaffected settings.
6
+
7
+ Read [Chat-card production](../creative/chat-card.md) for format/policy requirements
8
+ and the generate/upload/attach chain. Preserve the supplied assets and provenance.
9
+
10
+ The Ads API exposes no Google-style keyword planner, audience estimate or
11
+ search-term report. Context hints are inputs, not measured search demand.
12
+ Read the [minimum-budget note](readiness.md#minimum-daily-budget) before a build;
13
+ a provider constraint is not permission to increase the planned amount.
14
+
15
+ Record the chosen bidding type before building: strategy and an oCPC optimization
16
+ goal are immutable after creation. Conversion bidding needs verified owned setup.
17
+ Measurement selections for clicks/impressions campaigns can change separately
18
+ through [conversions](conversions.md); optional measurement is not a strategy change.
19
+
20
+ Assemble `creatives.json` with local ad-group/ad slugs, context hints, bid settings,
21
+ chat-card title/body, exact tracked destination and actual asset paths. These are
22
+ local assembly records, not raw API payloads. Verify language, limits and asset
23
+ bindings before upload. Keep assets available to the next agent; a draft alone
24
+ does not authorize upload, creation or launch.
@@ -0,0 +1,27 @@
1
+ # Launch an existing campaign
2
+
3
+ Read [artifacts](../runtime/artifacts.md), [API operations](../runtime/api-reference.md)
4
+ and [monitoring](monitoring.md). This workflow does not create missing objects.
5
+
6
+ Before activation:
7
+
8
+ - confirm explicit spending authority or the applicable product policy, with the
9
+ intended daily budget, bidding, geo, destination and allowed changes;
10
+ - verify current paused campaign and intended child IDs, review state, creative,
11
+ destinations and budgets against recorded evidence; resolve unknown writes;
12
+ - confirm account/payment readiness and tracking limitations; optional provider
13
+ conversions are required only if the chosen bidding/measurement needs them.
14
+
15
+ Journal each operation. While the campaign is paused, enable only intended ad
16
+ groups/ads via their status endpoints; intentionally excluded children remain paused.
17
+ Then call `/campaigns/{id}/launch`, which uses the wallet. Do not retry an insufficient
18
+ funds rejection by changing budgets or using a raw endpoint.
19
+
20
+ Read the tree again independently. Record `active` only as observed configuration,
21
+ not proof of impressions. Record pending review/account blockers separately. On
22
+ partial or unknown activation preserve the actual state and saved operation;
23
+ do not report a successful launch from the intended action alone.
24
+
25
+ Update state/readback/change-log and run `--phase launch`. Return campaign IDs,
26
+ observed configuration, actual daily budget, delivery readiness limits and any
27
+ unconfirmed operation. Launching does not schedule future checks or stops.
@@ -0,0 +1,54 @@
1
+ # Read results and edit a campaign
2
+
3
+ Read [artifacts](../runtime/artifacts.md) and [API reference](../runtime/api-reference.md).
4
+ An audit/monitor request is read-only unless it explicitly includes optimization
5
+ or a standing policy authorizes specific changes and safety stops.
6
+
7
+ ## Observe
8
+
9
+ Resolve exact campaign ID and read previous checks/change-log before acting.
10
+ Retrieve current campaign/child statuses and review/account blockers using the
11
+ [serving diagnostic reads](../runtime/api-reference.md#read-serving-diagnostics).
12
+ Read the affected campaign, groups and ads with `include_serving_issues=true`;
13
+ retain each returned code and distinguish missing diagnostics, an empty list
14
+ and a failed read. For a rejected destination change, compare the currently
15
+ saved URL/review state with the rejected request and preserve its error code.
16
+ Do not turn approval of an old creative into approval of the rejected URL or
17
+ promise a domain-review ETA. Diagnostics alone do not authorize a URL retry,
18
+ recreation, activation or budget/bid change. Then:
19
+
20
+ 1. Read `/campaigns/{id}/results` for the requested Unix time window. Follow all
21
+ pages before totals; preserve currency, timezone, window, fetched time and
22
+ `available/no_rows/error`. Do not add cumulative snapshots from overlapping
23
+ periods. Calculate CTR/CPC only from real counts and nonzero denominators.
24
+ 2. Read `/campaigns/{id}/conversion-results` only when needed and available.
25
+ Separate click-through from view-through; accepted CAPI receipts are not
26
+ attributed conversions. Do not manufacture per-ad or search-term breakdowns
27
+ from campaign-only results.
28
+ 3. Read `/analytics/<product_slug>/campaigns` and `/stats` with supported periods;
29
+ match the stable UTM campaign. Compare visits and applicable funnel events.
30
+ Label unmatched time windows or site-wide metrics rather than presenting them
31
+ as exact campaign outcomes.
32
+ 4. Check destination/tracking defects when evidence points there. Missing metrics
33
+ are not zero, and active configuration without impressions is not delivery.
34
+
35
+ ## Edit an existing campaign
36
+
37
+ For a direct instruction such as “change this ad's headline,” target the exact ad,
38
+ read its full creative and preserve unaffected image/body/URL fields. The API accepts
39
+ the full creative object; write it back to that ad, not a replacement campaign.
40
+ Use a new durable operation for the approved change; unknown outcomes retain its
41
+ key. Read back and record before/after plus rationale. Keep budget/targeting edits
42
+ inside approved bounds. Measurement selections on clicks/impressions campaigns
43
+ can be edited through the [conversions workflow](conversions.md) without changing
44
+ bidding. Immutable bidding/oCPC optimization-goal changes require a separately approved
45
+ new campaign, not a hidden workaround. Follow the API's pause-first requirement
46
+ when activating children; a pause/relaunch interruption also needs authorization.
47
+
48
+ ## Preserve observations
49
+
50
+ Return query/returned windows, fetch time, sources, currency, metrics, current
51
+ status and availability/attribution gaps. When durable observations are needed,
52
+ save them in `monitoring/check-<timestamp>.md`; `--phase monitoring` checks these
53
+ records. Simple reads need no new files. After a mutation append change-log,
54
+ refresh factual state/readback and use `--phase edit`.
@@ -0,0 +1,22 @@
1
+ # Pause delivery
2
+
3
+ For an authorized stop, resolve the exact campaign and call its pause endpoint
4
+ with a persisted idempotency key. Do not delay an urgent safety stop for missing
5
+ historical docs or validator errors. Do not archive/delete children or tracking
6
+ resources merely to pause delivery.
7
+
8
+ Independently read campaign status. Only then record factual `paused_at`; a planned
9
+ stop time or accepted request is not proof of pause. On error/timeout, preserve the
10
+ unconfirmed operation, report current exposure and follow the saved-key recovery
11
+ procedure. Child flags can remain active under a paused campaign; do not claim they
12
+ were individually paused if only the parent was stopped.
13
+
14
+ Update state/readback and change-log; run `--phase pause`. Pausing delivery does
15
+ not cancel external jobs, remove reporting access or make delayed results final.
16
+
17
+ Record the requested trigger/authority in the existing change-log, then append
18
+ the affected ID, actual confirmation time and readback after success. Preserve
19
+ the known cause for this run; later balance or deadline changes do not replace it.
20
+ If the provider exposes no cause, record it as unknown. A later relaunch does not
21
+ reuse the earlier stop timestamp. Return the confirmed stop state or the unresolved
22
+ operation; a failed pause or stopped monitoring alone is not a confirmed stop.
@@ -0,0 +1,37 @@
1
+ # Readiness
2
+
3
+ Read [API operations](../runtime/api-reference.md). This phase is read-only for
4
+ the ad account; it may write local readiness evidence.
5
+
6
+ 1. Identify the product, destination, requested operation and spending authority.
7
+ Resolve existing campaign IDs before checking their configuration.
8
+ 2. Read `/ads/openai/account`. Record currency/timezone and actual access. Key
9
+ configuration is not proof of payment setup, serving approval or conversion
10
+ setup access. Keep unknown capabilities unknown.
11
+ 3. Check destination availability, language and offer consistency. Check product
12
+ analytics through the [tracking workflow](tracking.md) when preparing a launch.
13
+ 4. Resolve geographies through `/ads/openai/locations`; preserve returned IDs and
14
+ rationale. Do not substitute country strings for provider IDs or invent access
15
+ to a keyword planner, audience estimate or competitor library.
16
+ 5. Reconcile any existing campaign before creating new objects. Verify the
17
+ approved daily amount against provider constraints without raising it silently.
18
+ For existing resources, use the [serving diagnostic reads](../runtime/api-reference.md#read-serving-diagnostics)
19
+ on the campaign, intended groups and ads. Record returned blockers and unknown
20
+ diagnostics separately from account authentication and destination availability.
21
+
22
+ ### Minimum daily budget
23
+
24
+ In the current shared account, a clicks campaign request on 2026-09-09 was rejected
25
+ below **$25/day**. Flag a lower requested budget; this is an observed
26
+ account/request constraint, not a guaranteed minimum for every account or bid type.
27
+ There is currently no minimum-budget discovery endpoint in Egbe OS. The applicable
28
+ minimum may only be disclosed by the provider when creating the authorized paused
29
+ campaign. Preserve that rejection as evidence, explain the minimum to the founder and
30
+ request approval before increasing the budget. Do not create disposable campaigns
31
+ to probe it. A changed, newly approved budget is a new journaled request; first
32
+ resolve any uncertain outcome of the previous request.
33
+
34
+ Write `channel-readiness.json`: observations with timestamps and blockers scoped
35
+ to build, launch or optional conversions. Lack of conversions need not block a
36
+ traffic campaign. Return what can proceed and what requires founder input;
37
+ do not create a throwaway campaign just to probe readiness.