@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,192 @@
1
+ #!/usr/bin/env python3
2
+ """Manage resumable organic trend workflow state without hidden side effects."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import json
8
+ import shutil
9
+ import sys
10
+ from pathlib import Path
11
+
12
+ from _contract import (
13
+ CANONICAL_PROVIDER_RUNS,
14
+ ContractError,
15
+ STEPS,
16
+ SCHEMA_VERSION,
17
+ SECTION_ID,
18
+ TERMINAL_PROVIDER_FAILURE_STATUSES,
19
+ atomic_write_json,
20
+ collection_parameters,
21
+ load_run_state,
22
+ new_run_state,
23
+ save_run_state,
24
+ utc_now,
25
+ )
26
+
27
+
28
+ def _state_path(root: Path) -> Path:
29
+ return root / "run-state.json"
30
+
31
+
32
+ def _archive_and_reset(root: Path, label: str) -> None:
33
+ state = load_run_state(root)
34
+ unsafe = [
35
+ key for key, run in state["provider_runs"].items()
36
+ if not isinstance(run, dict)
37
+ or str(run.get("status", "")).upper()
38
+ not in TERMINAL_PROVIDER_FAILURE_STATUSES | {"SUCCEEDED"}
39
+ ]
40
+ if unsafe:
41
+ raise ContractError(
42
+ "cannot refresh running or uncertain provider handles: " + ", ".join(unsafe)
43
+ )
44
+ archive = root / "archive" / label
45
+ suffix = 1
46
+ while archive.exists():
47
+ archive = root / "archive" / f"{label}-{suffix}"
48
+ suffix += 1
49
+ archive.mkdir(parents=True)
50
+ shutil.copy2(root / "context.json", archive / "context.json")
51
+ for relative in (
52
+ "run-state.json",
53
+ "raw",
54
+ "normalized",
55
+ "analysis.json",
56
+ "result.md",
57
+ "receipt.json",
58
+ "media",
59
+ "frames",
60
+ "visual-analysis",
61
+ ):
62
+ source = root / relative
63
+ if source.exists():
64
+ shutil.move(str(source), str(archive / source.name))
65
+ state = new_run_state(root)
66
+ state["supersedes_archive"] = archive.relative_to(root).as_posix()
67
+ save_run_state(root, state)
68
+
69
+
70
+ def main() -> int:
71
+ parser = argparse.ArgumentParser()
72
+ parser.add_argument("--runtime-root", type=Path, required=True)
73
+ sub = parser.add_subparsers(dest="command", required=True)
74
+ init = sub.add_parser("init")
75
+ assignment = init.add_mutually_exclusive_group()
76
+ assignment.add_argument("--assignment")
77
+ assignment.add_argument("--assignment-file", type=Path)
78
+ init.add_argument("--product-context")
79
+ init.add_argument("--max-analysis-videos", type=int)
80
+ init.add_argument("--discovery-limit-per-account", type=int)
81
+ init.add_argument("--lookback-days", type=int)
82
+ sub.add_parser("refresh")
83
+ sub.add_parser("status")
84
+ for command in ("begin-step", "complete-step", "fail-step"):
85
+ command_parser = sub.add_parser(command)
86
+ command_parser.add_argument("--step", choices=STEPS, required=True)
87
+ if command == "fail-step":
88
+ command_parser.add_argument("--error", required=True)
89
+ restart = sub.add_parser("restart-failed-collection")
90
+ restart.add_argument("--key", choices=sorted(CANONICAL_PROVIDER_RUNS), required=True)
91
+ restart.add_argument("--run-id", required=True)
92
+ args = parser.parse_args()
93
+ root = args.runtime_root.resolve()
94
+
95
+ try:
96
+ if args.command == "init":
97
+ path = _state_path(root)
98
+ if args.assignment is not None or args.assignment_file is not None:
99
+ if (root / "context.json").exists() or path.exists():
100
+ raise ContractError("context already exists; resume it or use a new runtime root")
101
+ assignment_text = (
102
+ args.assignment_file.read_text(encoding="utf-8")
103
+ if args.assignment_file else args.assignment
104
+ )
105
+ context = {
106
+ "schema_version": SCHEMA_VERSION,
107
+ "section_id": SECTION_ID,
108
+ "assignment": assignment_text,
109
+ "product_context": args.product_context,
110
+ }
111
+ if args.max_analysis_videos is not None:
112
+ context["max_analysis_videos"] = args.max_analysis_videos
113
+ context["collection"] = collection_parameters({"collection": {
114
+ key: value for key, value in {
115
+ "discovery_limit_per_account": args.discovery_limit_per_account,
116
+ "lookback_days": args.lookback_days,
117
+ }.items() if value is not None
118
+ }})
119
+ # Validate before publishing any state.
120
+ if (not isinstance(assignment_text, str) or not assignment_text.strip()
121
+ or not args.product_context or not args.product_context.strip()):
122
+ raise ContractError("assignment and product context must be non-empty")
123
+ if (args.max_analysis_videos is not None
124
+ and not 1 <= args.max_analysis_videos <= 30):
125
+ raise ContractError("max analysis videos must be from 1 to 30 (adapter resource ceiling)")
126
+ atomic_write_json(root / "context.json", context)
127
+ elif any(value is not None for value in (
128
+ args.product_context, args.max_analysis_videos,
129
+ args.discovery_limit_per_account, args.lookback_days,
130
+ )):
131
+ raise ContractError("context flags require a new assignment; existing context is immutable")
132
+ if path.exists():
133
+ state = load_run_state(root)
134
+ else:
135
+ state = new_run_state(root)
136
+ save_run_state(root, state)
137
+ print(json.dumps(state, indent=2, sort_keys=True))
138
+ return 0
139
+
140
+ state = load_run_state(root)
141
+ if args.command == "refresh":
142
+ _archive_and_reset(root, "refresh-" + state["collection_epoch"][:12])
143
+ print(json.dumps(load_run_state(root), indent=2, sort_keys=True))
144
+ return 0
145
+ if args.command == "status":
146
+ print(json.dumps(state, indent=2, sort_keys=True))
147
+ return 0
148
+
149
+ if args.command == "restart-failed-collection":
150
+ run = state["provider_runs"].get(args.key)
151
+ if not isinstance(run, dict):
152
+ raise ContractError(f"no saved provider run for {args.key}")
153
+ if run.get("run_id") != args.run_id:
154
+ raise ContractError("saved provider run ID does not match --run-id")
155
+ status = str(run.get("status") or "").upper()
156
+ if status not in TERMINAL_PROVIDER_FAILURE_STATUSES:
157
+ raise ContractError(
158
+ f"provider run {args.key} is {status or 'unknown'}, not terminal"
159
+ )
160
+ safe_run_id = "".join(
161
+ character if character.isalnum() else "-"
162
+ for character in args.run_id[:12]
163
+ )
164
+ label = f"failed-{args.key}-{safe_run_id}"
165
+ _archive_and_reset(root, label)
166
+ print(json.dumps(load_run_state(root), indent=2, sort_keys=True))
167
+ return 0
168
+
169
+ if args.command in {"begin-step", "complete-step", "fail-step"}:
170
+ step = state["steps"].get(args.step)
171
+ if not isinstance(step, dict):
172
+ raise ContractError(f"run-state is missing step {args.step}")
173
+ if args.command == "begin-step":
174
+ step.update({"status": "running", "started_at": utc_now()})
175
+ step.pop("error", None)
176
+ elif args.command == "complete-step":
177
+ step.update({"status": "completed", "completed_at": utc_now()})
178
+ step.pop("error", None)
179
+ else:
180
+ step.update({"status": "failed", "failed_at": utc_now(), "error": args.error})
181
+ state["status"] = "failed"
182
+ save_run_state(root, state)
183
+ return 0
184
+
185
+ raise ContractError(f"unsupported run-state command: {args.command}")
186
+ except (ContractError, OSError) as exc:
187
+ print(f"organic trend run-state error: {exc}", file=sys.stderr)
188
+ return 1
189
+
190
+
191
+ if __name__ == "__main__":
192
+ raise SystemExit(main())
@@ -0,0 +1,27 @@
1
+ #!/usr/bin/env python3
2
+ """Validate caller-owned organic trend context."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import sys
8
+ from pathlib import Path
9
+
10
+ from _contract import ContractError, validate_context
11
+
12
+
13
+ def main() -> int:
14
+ parser = argparse.ArgumentParser()
15
+ parser.add_argument("--context", type=Path, required=True)
16
+ args = parser.parse_args()
17
+ try:
18
+ validate_context(args.context.resolve())
19
+ except ContractError as exc:
20
+ print(f"invalid organic trend context: {exc}", file=sys.stderr)
21
+ return 1
22
+ print("organic trend context is valid")
23
+ return 0
24
+
25
+
26
+ if __name__ == "__main__":
27
+ raise SystemExit(main())
@@ -0,0 +1,137 @@
1
+ #!/usr/bin/env python3
2
+ """Stable integration validator for organic trend runtime artifacts."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import re
8
+ import sys
9
+ from pathlib import Path
10
+ from typing import Any
11
+
12
+ from _analysis import coverage, load_and_validate_analysis, render_body
13
+ from _contract import (
14
+ ANALYSIS_CONTRACT_VERSION,
15
+ ContractError,
16
+ SCHEMA_VERSION,
17
+ SECTION_HEADING,
18
+ SECTION_ID,
19
+ parse_rfc3339,
20
+ read_json,
21
+ require_sha256,
22
+ resolve_relative,
23
+ runtime_root_from_workspace,
24
+ sha256_file,
25
+ load_run_state,
26
+ validate_collection_fresh,
27
+ validate_context,
28
+ validate_manifest_against_state,
29
+ validate_provider_run,
30
+ validate_raw_manifest,
31
+ )
32
+
33
+
34
+ ARTIFACT_PATHS = {
35
+ "raw_manifest": "raw/manifest.json",
36
+ "normalized_videos": "normalized/videos.json",
37
+ "analysis": "analysis.json",
38
+ "result": "result.md",
39
+ }
40
+
41
+
42
+ def _validate_ref(root: Path, value: Any, field: str, expected_path: str) -> None:
43
+ if not isinstance(value, dict):
44
+ raise ContractError(f"{field} must be an object")
45
+ if value.get("path") != expected_path:
46
+ raise ContractError(f"{field}.path must be {expected_path}")
47
+ expected_hash = require_sha256(value.get("sha256"), f"{field}.sha256")
48
+ path = resolve_relative(root, expected_path, f"{field}.path")
49
+ if not path.is_file() or sha256_file(path) != expected_hash:
50
+ raise ContractError(f"{field} hash mismatch")
51
+
52
+
53
+ def validate_runtime(root: Path) -> dict[str, Any]:
54
+ validate_context(root / "context.json")
55
+ manifest = validate_raw_manifest(root)
56
+ validate_collection_fresh(manifest)
57
+ state = load_run_state(root)
58
+ validate_manifest_against_state(root, manifest, state)
59
+ if state.get("status") != "completed" or any(
60
+ step.get("status") != "completed" for step in state["steps"].values()
61
+ ):
62
+ raise ContractError("run-state is not fully completed")
63
+ analysis, normalized = load_and_validate_analysis(root)
64
+ receipt = read_json(root / "receipt.json")
65
+ result_coverage = coverage(analysis, normalized)
66
+ if receipt.get("coverage") != result_coverage:
67
+ raise ContractError("receipt.coverage differs from the evidence")
68
+ expected_scalars = {
69
+ "schema_version": SCHEMA_VERSION,
70
+ "section_id": SECTION_ID,
71
+ "section_heading": SECTION_HEADING,
72
+ "analysis_contract_version": ANALYSIS_CONTRACT_VERSION,
73
+ "status": "completed" if result_coverage["status"] == "complete" else result_coverage["status"],
74
+ "collection_epoch": state["collection_epoch"],
75
+ }
76
+ for field, expected in expected_scalars.items():
77
+ if receipt.get(field) != expected:
78
+ raise ContractError(f"receipt.{field} must be {expected!r}")
79
+ collected = parse_rfc3339(receipt.get("collected_at"), "receipt.collected_at")
80
+ completed = parse_rfc3339(receipt.get("completed_at"), "receipt.completed_at")
81
+ if receipt.get("collected_at") != manifest.get("collection_completed_at"):
82
+ raise ContractError("receipt.collected_at must equal raw manifest completion time")
83
+ if completed < collected:
84
+ raise ContractError("receipt.completed_at precedes collected_at")
85
+ if state.get("completed_at") != receipt.get("completed_at"):
86
+ raise ContractError("run-state and receipt completion times differ")
87
+ _validate_ref(root, receipt.get("context"), "receipt.context", "context.json")
88
+ artifacts = receipt.get("artifacts")
89
+ if not isinstance(artifacts, dict) or set(artifacts) != set(ARTIFACT_PATHS):
90
+ raise ContractError("receipt.artifacts must contain exactly the four canonical artifacts")
91
+ for name, path in ARTIFACT_PATHS.items():
92
+ _validate_ref(root, artifacts.get(name), f"receipt.artifacts.{name}", path)
93
+
94
+ receipt_runs = receipt.get("provider_runs")
95
+ if not isinstance(receipt_runs, list) or not receipt_runs:
96
+ raise ContractError("receipt.provider_runs must be a non-empty list")
97
+ canonical_receipt_runs = [
98
+ validate_provider_run(item, f"receipt.provider_runs[{index}]")
99
+ for index, item in enumerate(receipt_runs)
100
+ ]
101
+ canonical_manifest_runs = [
102
+ validate_provider_run(item, f"manifest.provider_runs[{index}]")
103
+ for index, item in enumerate(manifest["provider_runs"])
104
+ ]
105
+ if canonical_receipt_runs != canonical_manifest_runs:
106
+ raise ContractError("receipt provider provenance differs from raw manifest")
107
+
108
+ expected_result = render_body(analysis, normalized)
109
+ try:
110
+ result = (root / "result.md").read_text(encoding="utf-8")
111
+ except (OSError, UnicodeDecodeError) as exc:
112
+ raise ContractError(f"cannot read result.md: {exc}") from exc
113
+ if result != expected_result:
114
+ raise ContractError("result.md differs from its deterministic rendering")
115
+ if re.search(r"(?m)^#{1,2}\s", result) or f"## {SECTION_HEADING}" in result:
116
+ raise ContractError("result.md must contain the section body without an H1/H2 wrapper")
117
+ return receipt
118
+
119
+
120
+ def main() -> int:
121
+ parser = argparse.ArgumentParser()
122
+ target = parser.add_mutually_exclusive_group(required=True)
123
+ target.add_argument("--workspace", type=Path)
124
+ target.add_argument("--runtime-root", type=Path)
125
+ args = parser.parse_args()
126
+ root = args.runtime_root.resolve() if args.runtime_root else runtime_root_from_workspace(args.workspace)
127
+ try:
128
+ validate_runtime(root)
129
+ except (ContractError, OSError) as exc:
130
+ print(f"invalid organic trend runtime: {exc}", file=sys.stderr)
131
+ return 1
132
+ print("organic trend runtime is valid")
133
+ return 0
134
+
135
+
136
+ if __name__ == "__main__":
137
+ raise SystemExit(main())
@@ -0,0 +1,215 @@
1
+ ---
2
+ name: egbe-os-payments
3
+ description: Build or repair Stripe checkout for one-time purchases or subscriptions, discounts, billing and entitlements.
4
+ metadata:
5
+ egbe-when: "Use for monetization work; offer when an agreed paid offer lacks a working payment flow."
6
+ egbe-visible: "true"
7
+ egbe-title: "Payments & subscriptions"
8
+ egbe-description: "Accept payments, offer subscriptions and promo codes, and let customers manage their billing."
9
+ egbe-category: "Payments & accounts"
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
+
56
+ # Payments
57
+
58
+ Build payments through Egbe OS, not through provider credentials or direct
59
+ payment-gateway routes. Base URL: `https://os.hz.egbe.dev`. Authenticate with
60
+ `Authorization: Bearer $OS_API_KEY`.
61
+
62
+ ## Through the Egbe connector
63
+
64
+ Through the connector you can read and create the provider catalog with the
65
+ `/payments` routes in the workflows below, and change and publish product code
66
+ with `egbe-os-git` ("Without a terminal") and `egbe-os-deploy`. `npm run
67
+ billing:sync` migrates the app database and stores the provider bindings in it,
68
+ and local test runs need the app's own environment. Both need a set-up project
69
+ workspace (in a persistent project workspace not set up yet, call
70
+ `egbe_local_setup`); otherwise tell the founder which step needs it. Do not
71
+ report checkout as working until it is verified on the deployed app.
72
+
73
+ ## Reuse the existing integration
74
+
75
+ Inspect the product repository and its `AGENTS.md`. When it contains
76
+ `EGBE:BILLING-FOUNDATION`, reuse the existing subscription foundation: plan
77
+ catalog, provider-binding sync, checkout attempt and endpoint, signed webhook
78
+ and lifecycle reducer, durable subscription state, entitlement helper, Billing
79
+ status and Portal endpoints, and neutral `/account/billing` surface. Do not
80
+ copy, replace, or rebuild that core. Complete only the product-specific catalog,
81
+ CTA/auth continuation, product enforcement or usage behavior, design and
82
+ navigation adaptation, analytics, and semantic verification. Repair integration
83
+ defects without creating competing billing state or bypassing its contracts.
84
+
85
+ For a repository without it, implement against the established application and
86
+ database conventions. The bundled `assets/scaffolds/billing-nextjs-subscription/`
87
+ is an optional starting point for a compatible new subscription integration,
88
+ not a one-time purchase engine. Do not overwrite working code or add a marker
89
+ without the implementation it describes.
90
+
91
+ Product Build's `references/foundations.md` documents the optional local scaffold
92
+ helper's `--subscriptions` selection, which previews and installs this foundation
93
+ and its required account/session pieces. Use it only for an accepted subscription
94
+ offer on a compatible stack; provider setup and product integration remain here.
95
+
96
+ ## Route The Work
97
+
98
+ - For customer purchase, buyer, or revenue reports, follow **Reporting customer
99
+ metrics** in the `egbe-os-analytics` skill (`GET /analytics/skill`).
100
+ - For catalog, provider setup, checkout, and pricing handoff,
101
+ read [references/workflows/product-checkout.md](references/workflows/product-checkout.md).
102
+ - For a one-time purchase and its delivery/access lifecycle, also read
103
+ [references/workflows/one-time-purchase.md](references/workflows/one-time-purchase.md).
104
+ - For coupons, customer-entered promotion codes, automatic Checkout discounts,
105
+ and discount operations, read
106
+ [references/workflows/discounts-and-promotion-codes.md](references/workflows/discounts-and-promotion-codes.md).
107
+ - For signed webhooks, normalized subscription state, and entitlements, read
108
+ [references/workflows/subscription-lifecycle.md](references/workflows/subscription-lifecycle.md).
109
+ - For the account billing page, user-menu plan state, and Customer Portal, read
110
+ [references/workflows/account-billing.md](references/workflows/account-billing.md).
111
+
112
+ Those workflows select the supporting contract, security, and UX references.
113
+ Read only the workflow relevant to the requested payment capability.
114
+
115
+ ## Platform Rules
116
+
117
+ - Use only `$OS_URL/payments/*`; never request Stripe keys or call Stripe or the
118
+ internal payment gateway directly.
119
+ - Use one app-owned plan catalog across landing pricing, checkout, billing UI,
120
+ and entitlements.
121
+ - Enable customer-entered promotion codes by default in new Checkout and
122
+ Payment Link implementations. Do not create a coupon or code implicitly;
123
+ follow the discounts workflow when the product needs provider resources or
124
+ an automatic discount.
125
+ - Treat provider state from `GET /payments/evidence` as Stripe readback and the
126
+ product database as the source of account entitlement state.
127
+ - Report checkout ready or done only after naming both verified validation
128
+ receipt outcomes and the `GET /payments/evidence` readback before and after
129
+ them; otherwise report readiness as unconfirmed.
130
+ - Treat working Auth as an upstream input. Reuse its private validation identity
131
+ and normal server-side session lookup for authenticated Billing work instead
132
+ of replaying signup, password, or email-link entry. Never add a public
133
+ test-login route or alternate Billing-only auth path.
134
+ - Send an `Idempotency-Key` on every provider create operation. Reuse the same
135
+ key when retrying the same logical operation.
136
+ - Keep provider ids, scoped keys, webhook secrets, customer ids, and checkout
137
+ creation on the server. Never expose them through `NEXT_PUBLIC_*` or browser
138
+ code.
139
+ - Use only the `OS_URL` and `OS_API_KEY` supplied to the current workload. The
140
+ Site Gateway injects the separate product identity; never mint, copy, rename,
141
+ or deploy a payments-specific OS key.
142
+ - A checkout return URL is navigation, not payment proof. Grant access only
143
+ after a signed live event is durably and idempotently applied.
144
+ - Reading account or billing state must not create a provider customer,
145
+ Checkout Session, or Customer Portal Session. Provider creates happen only
146
+ from an explicit user mutation and remain idempotent.
147
+ - Checkout and portal server actions implement the portable validate-only
148
+ request contract documented in their workflows. Probe requests reuse the
149
+ normal auth and binding path, return an opaque short-lived OS receipt, and
150
+ never fall through to provider create.
151
+ - Use the Egbe OS `egbe-os-analytics` skill as the sole source of payment event names,
152
+ payloads, attribution, and delivery rules.
153
+
154
+ ## Seller of record, payouts and refunds
155
+
156
+ Checkout runs on Egbe's shared payment account, not a provider account owned by
157
+ the founder or the product. Under the current
158
+ [Egbe commercial terms](https://egbe.ai/terms/), Egbe is the merchant of record
159
+ for these sales, so the Checkout page and the buyer's card statement can name
160
+ Egbe rather than the product.
161
+
162
+ - Read those terms for who sells and is paid, what reduces a payout, how a
163
+ buyer requests a refund and who issues it. Cite them instead of restating
164
+ amounts, windows or contacts from memory or from a direct-Stripe integration.
165
+ - Keep the product's Terms, pricing and checkout-adjacent copy consistent with
166
+ them. Where a buyer would otherwise meet an unexplained payee, say that Egbe
167
+ processes the payment and link those terms. Send order, billing and refund
168
+ requests to the contact the terms name. Never present the project mailbox or
169
+ the founder as the party that issues refunds; they remain the contact for the
170
+ product itself.
171
+ - Never tell a founder they can issue refunds or manage payouts in a
172
+ payment-provider dashboard. Egbe OS gives a project no refund or payout
173
+ operation and no provider credentials or dashboard. The product receives a
174
+ refund as a signed webhook event and records it. For a payout, point the
175
+ founder to the Payouts section of the Wallet page in their Egbe Dashboard,
176
+ which states how to request one; do not open a support ticket to ask.
177
+ - The accepted offer still decides what the product promises about refunds and
178
+ access, within those terms. It does not decide who executes a refund.
179
+ - When the terms do not answer a question the work depends on, report it as
180
+ unconfirmed and ask through the `egbe-os-support` skill; do not guess.
181
+
182
+ ## Discovery And Readback
183
+
184
+ ```bash
185
+ OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/payments/skill" -s
186
+ OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/payments/evidence" -s
187
+ ```
188
+
189
+ Evidence is scoped to the current instance and intentionally omits customer
190
+ email values. Use it to verify provider objects; do not copy it into a second
191
+ payment-state artifact.
192
+
193
+ This GET automatically retries only failures to establish the gateway connection:
194
+ at most four attempts with 0.5/1/2-second backoff, within one 55-second budget.
195
+ Each connection attempt is capped at five seconds or the smaller remaining budget.
196
+ HTTP errors and failures while reading a response are returned without automatic
197
+ replay. Payment writes do not inherit this retry behavior.
198
+
199
+ An error envelope means provider readiness is unconfirmed; it does not establish
200
+ that Stripe is unconfigured or that a charge failed. After recovery is exhausted,
201
+ a later read may recheck readiness. Preserve the intended integration and the
202
+ reported failure; do not replace unavailable evidence with empty records or
203
+ change credentials based on a transient connection error.
204
+
205
+ ## Missing product webhook recovery
206
+
207
+ Products stay active independently of their founder's agent runtime. When a
208
+ product webhook returns 404 or 405, Egbe records a deduplicated repair notice in
209
+ `GET /notifications` for local-agent projects. Read that notice, fix the signed
210
+ receiver, redeploy, and verify actual event delivery. Paid events continue to
211
+ return a retryable failure to Stripe until the product accepts them; an inbox
212
+ notice does not grant an entitlement or complete delivery. Expired checkout
213
+ notices may be acknowledged after the repair notice is durably recorded.
214
+ Retries share one unread notice; another failure after it is read reopens the
215
+ action. Marking a notice read does not resolve or repair the webhook.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Product Payments"
3
+ short_description: "Build secure checkout, discounts, and subscription billing"
4
+ default_prompt: "Use $egbe-os-payments to implement account-bound checkout, product-owned discounts and promotion codes, signed subscription lifecycle processing, entitlements, and billing UX through Egbe OS."
@@ -0,0 +1,5 @@
1
+ {
2
+ "id": "billing-nextjs-subscription.v1",
3
+ "requires_runtime_env": ["DATABASE_URL", "OS_URL", "OS_API_KEY", "EGBE_PAYMENT_WEBHOOK_SECRET"],
4
+ "webhook_path": "/api/payments/webhook"
5
+ }
@@ -0,0 +1,13 @@
1
+ # Billing foundation
2
+
3
+ This repository includes the subscription foundation; it is not a one-time purchase implementation.
4
+
5
+ - Do not recreate or replace `db/migrations/1000_egbe_billing.sql`, `src/lib/egbe-billing/*`, `/api/billing/*`, `/api/payments/webhook`, or the base `/account/billing` route.
6
+ - Fill `src/lib/egbe-billing/plans.json` from the accepted subscription offer. Keep provider IDs out of source; when provider setup is authorized, use `npm run billing:sync` to create/read back provider objects and persist bindings, not as a schema probe.
7
+ - Connect real paid CTA and signed-in continuation to `/api/billing/checkout`; adapt the neutral account Billing surface to the product design and add it to real account navigation.
8
+ - Keep customer-entered promotion codes enabled by default through the scaffold checkout payload. If product billing configuration selects one server-owned automatic coupon or promotion-code reference, pass that bounded reference and disable customer code entry; never create discount resources implicitly.
9
+ - A customer-restricted Promotion Code requires the exact persisted Stripe Customer on Checkout. Verify each recipient in authoritative product accounts, explicitly create and persist any missing Customer binding before Promotion Code creation, and pass that exact id to Checkout; never bind eligibility from a browser-supplied email.
10
+ - Use `hasEntitlement(accountId, capability)` at each real product enforcement point. Only when an accepted right is exhaustible, add its usage limits and atomic consumption in a product-owned migration; the scaffold does not infer quota rules.
11
+ - Keep `/api/payments/webhook` raw-body verification, duplicate transaction, pure reducer, and test-event no-side-effect boundary intact.
12
+ - Deploy through the active Egbe OS deployment mechanism and follow the `egbe-os-payments` skill's webhook-secret contract. Never place a provider or agent credential in product source or env.
13
+ - Verify checkout, lifecycle simulations, entitlement enforcement, Billing states, and Customer Portal through the normal authenticated product journey.
@@ -0,0 +1,66 @@
1
+ -- Canonical subscription foundation. Product-specific usage and quota tables
2
+ -- belong in later migrations.
3
+
4
+ create table if not exists billing_provider_bindings (
5
+ plan_key text primary key,
6
+ provider_product_id text not null unique,
7
+ provider_price_id text not null unique,
8
+ catalog_digest text not null,
9
+ synced_at timestamptz not null default now()
10
+ );
11
+
12
+ create table if not exists account_billing (
13
+ account_id uuid primary key references users(id) on delete cascade,
14
+ plan_key text not null default 'free',
15
+ subscription_status text not null default 'free',
16
+ provider_customer_id text unique,
17
+ provider_subscription_id text unique,
18
+ provider_price_id text,
19
+ current_period_end timestamptz,
20
+ cancel_at_period_end boolean not null default false,
21
+ last_event_id text,
22
+ last_event_created bigint not null default 0,
23
+ updated_at timestamptz not null default now(),
24
+ check (subscription_status in ('free', 'trialing', 'active', 'past_due', 'canceling', 'paused', 'canceled'))
25
+ );
26
+
27
+ create table if not exists billing_checkout_attempts (
28
+ id uuid primary key default gen_random_uuid(),
29
+ account_id uuid not null references users(id) on delete cascade,
30
+ plan_key text not null,
31
+ idempotency_key text not null unique default gen_random_uuid()::text,
32
+ return_path text not null,
33
+ attribution jsonb not null default '{}'::jsonb,
34
+ status text not null default 'pending',
35
+ provider_session_id text,
36
+ created_at timestamptz not null default now(),
37
+ updated_at timestamptz not null default now(),
38
+ check (status in ('pending', 'created', 'completed', 'abandoned', 'failed'))
39
+ );
40
+
41
+ create unique index if not exists billing_checkout_attempts_active_key
42
+ on billing_checkout_attempts (account_id, plan_key)
43
+ where status in ('pending', 'created');
44
+
45
+ create table if not exists processed_payment_events (
46
+ event_id text primary key,
47
+ event_type text not null,
48
+ event_created bigint not null,
49
+ account_id uuid references users(id) on delete set null,
50
+ processed_at timestamptz not null default now()
51
+ );
52
+
53
+ create table if not exists entitlement_grants (
54
+ id uuid primary key default gen_random_uuid(),
55
+ account_id uuid not null references users(id) on delete cascade,
56
+ capability text not null,
57
+ source text not null,
58
+ active_from timestamptz not null default now(),
59
+ active_until timestamptz,
60
+ revoked_at timestamptz,
61
+ created_at timestamptz not null default now(),
62
+ unique (account_id, capability, source)
63
+ );
64
+
65
+ create index if not exists entitlement_grants_account_capability_idx
66
+ on entitlement_grants (account_id, capability);