@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,412 @@
1
+ ---
2
+ name: egbe-os-deploy
3
+ description: Publish, update and diagnose apps on Egbe hosting, the default for connected businesses.
4
+ metadata:
5
+ egbe-when: "Use for website/app previews, publication, updates or deployment diagnosis."
6
+ egbe-visible: "true"
7
+ egbe-title: "Hosting & databases"
8
+ egbe-description: "Publish your application, attach a database and manage updates through Egbe hosting."
9
+ egbe-category: "Development & hosting"
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
+ # Deploy a web app
57
+
58
+ Egbe hosting is the default destination for authorized publishing in a connected
59
+ Egbe business. Another available tool, including ChatGPT Sites, is not a reason
60
+ to switch hosts. Follow an explicit founder choice of another host and preserve
61
+ an existing product's destination unless migration is authorized. Diagnose Egbe
62
+ failures and report concrete blockers rather than silently publishing elsewhere.
63
+
64
+ Before a first public release, ensure its product name and public identity were
65
+ selected by the founder or under explicit delegation. The first deploy also
66
+ claims a public alias from the slug. For unresolved personal choices or
67
+ hard-to-reverse changes such as replacing an established public identity or
68
+ destroying saved customer work, present options and a recommendation and wait for
69
+ selection or delegation. Return the decision to the caller if needed. Offer
70
+ delegation once or throughout this business, and reuse it without asking again;
71
+ routine authorized updates under existing decisions need no new checkpoint.
72
+
73
+ Give us a git repo; we build the `Dockerfile` and host it live. The live URL is
74
+ returned by `GET /deploy/<slug>` once the build finishes.
75
+
76
+ **Read `url`, not `host`.** Every response carries both: `host` is the canonical
77
+ `<slug>-<publicId>.n.egbe.app` address, and `url` is what you give a customer — your
78
+ `<name>.egbe.app` domain when you have one (your first deploy claims it for you) and the
79
+ canonical host otherwise. See the `domains` capability (`GET /domains/skill`) to choose
80
+ a name or move your one domain to another app.
81
+
82
+ Use the project's configured `OS_URL` and authenticate every call with
83
+ `Authorization: Bearer $OS_API_KEY`.
84
+
85
+ ## App requirements
86
+ - **Listen on `0.0.0.0`** on the port your `Dockerfile` `EXPOSE`s (the runtime
87
+ auto-detects it; default 8080). Don't bind to `127.0.0.1`.
88
+ - **Need a database? Pass `"db": true`** (see below) — do NOT try to reach an
89
+ external Postgres host. Your app runs on an isolated network and can only
90
+ reach a database provisioned for it on this platform.
91
+ - **Public product app? Use the `analytics` capability** to create/fetch the
92
+ analytics site and inject `GET /analytics/<slug>/tracking` config into the app
93
+ shell. The deploy skill does not define product event names; read
94
+ `GET /analytics/events` for the canonical funnel contract.
95
+
96
+ ## Saved customer work
97
+
98
+ For an app that promises to save customer work, a healthy deployment is not
99
+ proof of recovery. Before declaring that saved-work journey complete, exercise
100
+ its actual save and recovery path on the serving revision. Stateless landing
101
+ pages and read-only sites have no save requirement; do not invent one. Create meaningful work, change each important editable part (including
102
+ checkboxes, status, selections and quantities), save through the customer UI,
103
+ then reload and leave/return to the page. Compare the original values and
104
+ checked/unchecked state; recovering only the inputs is insufficient when the
105
+ saved result contains further customer edits.
106
+
107
+ Use storage appropriate to the promised lifetime. Explain browser-only saving
108
+ plainly; do not claim account or cross-device recovery from local browser data.
109
+ If the customer saves a file, verify its contents and reopen/import it through
110
+ the supported product journey instead. An exported checklist must reflect the
111
+ customer's actual choices. Do not claim a download works from its click alone.
112
+
113
+ Before updating an existing app, keep an original saved customer record or file
114
+ and verify it still recovers after the update. Preserve existing storage keys,
115
+ identities and values, or ship a migration. Cover any confirmed loss with a
116
+ regression test and recheck the actual customer UI. Report failures and observer
117
+ limits honestly; mocked integrations and HTTP 200 cannot establish recovery.
118
+
119
+ ## Need a database
120
+
121
+ Pass `"db": true` to the deploy call. We provision a Postgres co-located with
122
+ your app and inject its connection string as `DATABASE_URL` into the app's
123
+ environment — your code just reads `process.env.DATABASE_URL`. No host, user, or
124
+ password to manage.
125
+
126
+ ```bash
127
+ OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/deploy" -s -X POST \
128
+ -H 'Content-Type: application/json' \
129
+ -d '{"slug":"my-app","repo":"my-app","db":true}'
130
+ ```
131
+
132
+ Need the connection string yourself (e.g. to run migrations)? Provision/fetch it
133
+ directly:
134
+
135
+ ```bash
136
+ OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/deploy/my-app/db" -s -X POST # provision -> {databaseUrl,...}
137
+ OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/deploy/my-app/db" -s # fetch existing
138
+ ```
139
+
140
+ To inspect persisted data, export query results, or update/delete a record,
141
+ read `GET /db/skill`. It uses the same attached PostgreSQL database and your
142
+ existing `OS_API_KEY`; no app admin route or redeploy is required.
143
+ The database schema is shared by your account's apps.
144
+
145
+ ### Product schema contract
146
+
147
+ Provisioning a database only creates the database and role; it does not create app tables.
148
+ Every DB-backed route must ship an idempotent schema initializer or migration with the product code.
149
+
150
+ - Run the schema initializer before the first query in production, either during
151
+ startup or on the first request behind a concurrency-safe guard.
152
+ - Keep schema setup in the deployable product repo, not only in local notes or
153
+ one-off terminal history.
154
+ - Let routes degrade gracefully when optional demo, activation, onboarding, or
155
+ dashboard data is absent.
156
+ - Verify every DB-backed route listed in a product manifest `test_paths` or `activation_paths` after deploy.
157
+ - A deployed route that produces any unhandled server/runtime error is not
158
+ complete. Examples include `relation "<table>" does not exist`, database
159
+ query failures, and ORM or framework runtime errors.
160
+
161
+ ## Filesystem constraints (read this — it is the #1 cause of containers that won't start)
162
+
163
+ Your container runs with a **read-only root filesystem** and as a **non-root
164
+ user** for security. The only writable locations are these in-memory `tmpfs`
165
+ mounts (everything written there is lost on restart):
166
+
167
+ | Path | Size | Use for |
168
+ |--------------|-------|------------------------------------------|
169
+ | `/tmp` | 64 MB | scratch files |
170
+ | `/var/tmp` | 64 MB | scratch files |
171
+ | `/var/cache` | 128 MB| caches (nginx, build tools) |
172
+ | `/run` | 16 MB | pid/socket files |
173
+
174
+ Anything that tries to write **anywhere else** (e.g. SQLite in the app dir, a
175
+ framework writing `.next`/`.cache` at runtime, log files next to the binary)
176
+ will fail to start. Fixes:
177
+ - Point your app's cache/temp/log dirs at `/tmp` or `/var/cache` (env var or
178
+ config).
179
+ - Pre-build everything at image-build time so nothing is written at runtime.
180
+ - Store real data in attached PostgreSQL, never on the container disk.
181
+
182
+ ## Before declaring deployment blocked
183
+
184
+ A missing remote, a local `master` branch or absent Vercel/Netlify configuration
185
+ is normal setup. Read `/git/skill`, create/reuse the account's Forgejo repo and
186
+ push with native Git through `/git/http/<repo>.git` using the OS key. Preserve
187
+ current history and branch names. Prepare a root Dockerfile if missing and deploy
188
+ the full pushed SHA. Without a terminal, Git or shell access to Egbe, follow
189
+ "Publish without a terminal" below instead. Respect the founder's existing
190
+ authorization and budget; report only an observed redacted
191
+ auth/provisioning/network/build error. Verify status, deployed revision and
192
+ public URL after deploy.
193
+
194
+ ## Publish without a terminal
195
+
196
+ Through the Egbe connector alone (for example in claude.ai, Cowork or ChatGPT),
197
+ publishing is: create or reuse the repository, commit the app's files as JSON,
198
+ deploy the returned SHA.
199
+
200
+ 1. `POST /git/repos` (or reuse one from `GET /git/repos`).
201
+ 2. Commit the source, a root `Dockerfile` and `.dockerignore` with
202
+ `POST /git/repos/<owner>/<repo>/commits`, in batches for larger apps, as
203
+ `/git/skill` describes under "Without a terminal". To update an existing app,
204
+ read its files and head first with `GET /git/repos/<owner>/<repo>/tree` and
205
+ `/file`.
206
+ 3. `POST /deploy` with `"ref": "<sha from the commit result>"`, then check status,
207
+ logs and the public URL as below.
208
+
209
+ The Docker build runs on Egbe, so dependencies install there (`npm ci` in the
210
+ Dockerfile); commit `package-lock.json`, not `node_modules/`. A static site can
211
+ be a Dockerfile that serves its files as a non-root user on 8080, for example
212
+ from `nginxinc/nginx-unprivileged:alpine`. Use `"db": true` for a database. A
213
+ Convex app needs no terminal either: see "Convex apps" below.
214
+
215
+ ## Before you push or commit: .gitignore and .dockerignore
216
+
217
+ Exclude dependencies, build output and actual environment files in both
218
+ `.gitignore` and `.dockerignore`, for example:
219
+
220
+ ```gitignore
221
+ node_modules/
222
+ .next/
223
+ dist/
224
+ **/.env
225
+ **/.env.*
226
+ !**/.env.example
227
+ !**/.env.sample
228
+ !**/.env.template
229
+ *.log
230
+ ```
231
+
232
+ Example files must contain sanitized placeholders. Add `.git` to `.dockerignore`;
233
+ Docker does not inherit Git exclusions. Ignore rules do not remove tracked secrets:
234
+ if credentials were committed, remove them from tracked source and coordinate
235
+ rotation before publication. Let the Dockerfile install dependencies (`npm ci`).
236
+
237
+ Keep `/egbe-docs/**/.local/` Git-ignored. Add `/egbe-docs/` to
238
+ `.dockerignore` and exclude it from every non-Docker build/public-copy path.
239
+ For static sites, publish only the intended output directory, never the whole
240
+ project root.
241
+
242
+ ## Deploy
243
+
244
+ ```bash
245
+ OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/deploy" -s -X POST \
246
+ -H 'Content-Type: application/json' \
247
+ -d '{"slug":"my-app","business_name":"MyApp","repo":"my-app","ref":"<full-pushed-commit-SHA>","env":{"NODE_ENV":"production"}}'
248
+ ```
249
+
250
+ - `slug` — your app's name; the live URL is returned by `GET /deploy/<slug>`.
251
+ - `business_name` — include the chosen business name exactly as branded, preserving
252
+ spelling, spaces, acronyms and capitalization (for example, `FirstSignal` with
253
+ slug `firstsignal`). This saves the name for the Dashboard business dropdown,
254
+ header and settings. It initializes an unnamed business and preserves any
255
+ existing chosen name; use Dashboard settings to rename a business. Do not
256
+ derive the display name from the lowercase URL slug. Omit it only when no
257
+ business name has been chosen yet.
258
+ - `repo` — the git repo to deploy (your Forgejo repo).
259
+ - `ref` — branch, tag or commit (default `main`). For your configured Forgejo,
260
+ an unambiguous 4–39-character commit abbreviation is expanded to its full SHA
261
+ before building. Hex-shaped names prefer a branch, then a tag, then a commit
262
+ abbreviation; use `refs/heads/<name>` or `refs/tags/<name>` to choose explicitly.
263
+ External repositories use BuildKit's native branch/tag or full 40-character
264
+ commit SHA format; abbreviated commits are not supported there.
265
+ - `env` — optional runtime environment patch: supplied keys replace their saved
266
+ values; omitted keys are preserved. Omit `env` for a code-only redeploy. This
267
+ is not a replacement map or a way to remove an existing key.
268
+ - `db` — `true` to provision a co-located Postgres and inject `DATABASE_URL` (see above).
269
+ - `min_instances` — `1` to keep one instance running and avoid scale-to-zero cold starts.
270
+ The running instance consumes wallet resources continuously, including while idle. The
271
+ default is `0`; include `min_instances: 1` on every redeploy that should stay warm.
272
+
273
+ Returns `202` with the deploy info; the app builds in the background.
274
+
275
+ ### Build-time public configuration
276
+
277
+ `env` is applied to the running container, not to the Docker build. Frameworks
278
+ that inline public variables during compilation (such as Next.js
279
+ `NEXT_PUBLIC_*`) will not pick them up from runtime env alone. Fetch the public
280
+ configuration from its owning OS capability before building, then either place
281
+ those non-secret values in a versioned public config consumed by the build, or
282
+ serve them through an explicit runtime-config endpoint. Verify the resulting
283
+ browser requests on the serving revision. Agent keys and server credentials
284
+ must never enter that public config or the image build context.
285
+
286
+ For ad pixels, follow the relevant advertising skill's setup and event contract;
287
+ deploy does not install pixels or discover their IDs automatically.
288
+
289
+ Use `"db": true` when first creating a DB-backed app or when explicitly
290
+ repairing/provisioning its database attachment. On later redeploys, the platform
291
+ preserves the existing `DATABASE_URL` runtime env automatically. Do not fetch,
292
+ store, or pass `DATABASE_URL` yourself.
293
+
294
+ ## Check status, list, logs
295
+
296
+ ```bash
297
+ OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/deploy" -s # list your apps
298
+ OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/deploy/my-app" -s # status
299
+ OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/deploy/my-app/logs?lines=200" -s # logs
300
+ ```
301
+
302
+ `status` returns `{host, runtime, lastDeploy}`. To tell a healthy app from one
303
+ whose latest deploy silently failed, compare the two revision fields:
304
+
305
+ - `runtime.running` — the newest revision is Ready (also `healthStatus`).
306
+ - `runtime.serving` / `runtime.servingRevision` — whether *any* revision is
307
+ answering traffic, and which one.
308
+ - `runtime.latestRevision` / `runtime.latestRevisionLive` — the most recently
309
+ built revision and whether it is the one serving.
310
+ - `lastDeploy.outcome` — `succeeded` (newest revision is live), `not_live` (your
311
+ newest build failed readiness, so an **older** revision still serves — the host
312
+ returns 200 but it is stale), or `failed` (nothing is serving).
313
+
314
+ The `releases` history in deploy, list and status responses includes
315
+ `source_commit`: the full immutable Git ref submitted to BuildKit for that
316
+ release. It is `null` for historical releases and native branch/tag refs that
317
+ were not resolved to a full SHA. Deploy the full pushed SHA when verification
318
+ needs source correspondence. Match the release `id` to `lastDeploy.release`
319
+ and check the live revision outcome before associating it with a serving update;
320
+ history alone does not prove which revision serves. This is build-input
321
+ provenance, not a server-filesystem attestation or a substitute for deployed
322
+ behavior and configuration checks. Never infer missing provenance from the
323
+ current branch tip or backfill an old release.
324
+
325
+ So if `latestRevisionLive` is `false` / `outcome` is `not_live`, your last build
326
+ never went live even though the URL works — pull
327
+ `GET /deploy/<slug>/deploys/<deployId>` for the readiness failure and redeploy.
328
+
329
+ `logs` returns `{runtime, build, lines}` — `runtime` is the container's recent
330
+ stdout/stderr, `build` is the last build's output. Tail more with `?lines=N`
331
+ (1–1000, default 100). If the app scaled to zero, `runtime` says so — send it a
332
+ request to wake it, then retry.
333
+
334
+ Redeploy by calling `POST /deploy` again with the same `slug`.
335
+
336
+ ## Convex apps
337
+
338
+ A Convex app (Vite + React SPA with a self-hosted Convex backend) has no
339
+ Dockerfile. Each business has one Convex backend; its site is served from
340
+ `siteUrl` (and your `<name>.egbe.app` domain when attached).
341
+
342
+ ### 1. Provision the backend
343
+
344
+ `POST /deploy/<slug>/convex?async=true` returns `202` with a `jobId` at once
345
+ (the `Prefer: respond-async` header does the same). Poll
346
+ `GET /deploy/<slug>/convex/jobs/<jobId>` until `status` is `succeeded`
347
+ (usually under 4 minutes); `result` has `deploymentUrl` and `siteUrl`, not the
348
+ admin key. Without `async` the call waits for the backend and returns
349
+ `deploymentUrl`, `siteUrl` and `adminKey` in one response. Re-provisioning
350
+ returns the same backend.
351
+
352
+ Include the exact chosen business name in the optional JSON body:
353
+ `{"business_name":"FirstSignal"}`. It is saved independently of the URL slug;
354
+ existing chosen names are preserved.
355
+
356
+ ### 2a. Publish without a terminal
357
+
358
+ Commit the app through a commit session as in "Publish without a terminal"
359
+ (`package.json`, `package-lock.json`, `convex/`, `src/`, `index.html`; no
360
+ `node_modules/`, `dist/` or `.env*`), then:
361
+
362
+ ```bash
363
+ OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/deploy/my-app/convex/deploy" -s -X POST \
364
+ -H 'Content-Type: application/json' \
365
+ -d '{"repo":"my-app","ref":"<sha from the commit result>","build_env":{"VITE_SUPPORT_EMAIL":"support@my-app.egbe.app"}}'
366
+ ```
367
+
368
+ Egbe's build sandbox checks out `ref`, runs `npm ci`, `npx convex deploy -y`
369
+ against your backend, `npm run build` and
370
+ `npx @convex-dev/static-hosting upload -d dist`. The admin key stays inside
371
+ Egbe. The response is `202` with a `jobId`; poll
372
+ `GET /deploy/<slug>/convex/jobs/<jobId>` every ~15 seconds. Stages are
373
+ `preflight`, `convex-env`, `build-starting`, `building`; `succeeded` returns
374
+ `result.url` (the live address), `siteUrl`, `deploymentUrl`, `source_commit` and
375
+ the build log tail in `result.logs`. `failed` returns `stage`, `error` and `logs`
376
+ (for example a TypeScript or schema error from `convex deploy`): fix the code,
377
+ commit and start a new job. One Convex job runs per business at a time; a second
378
+ one gets `409 convex_job_in_progress` with the running job's poll URL.
379
+
380
+ - `env` — Convex backend environment variables (server-side, may be secrets),
381
+ set before `convex deploy` like `npx convex env set`. Supplied names replace
382
+ their values; omitted names are kept. `OS_URL` and `OS_API_KEY` are set by the
383
+ platform on every publish to the product's own credential, as for Docker
384
+ apps; your Convex actions read `process.env.OS_API_KEY`.
385
+ - `build_env` — public build-time values (for example `VITE_*`). They are
386
+ inlined into the browser bundle; never put a secret here. `VITE_CONVEX_URL`
387
+ is set to `deploymentUrl` for you. `CONVEX_*`, `EGBE_*`, `NODE_*`, `NPM_*`
388
+ and `OS_*` names are reserved.
389
+ - `dist` — build output directory to upload (default `dist`); `upload: false`
390
+ publishes the backend only.
391
+
392
+ Requirements: `package.json` and `package-lock.json` at the repository root,
393
+ `convex` and (for the upload) `@convex-dev/static-hosting` as dependencies,
394
+ a `build` script, and the static-hosting component set up in
395
+ `convex/convex.config.ts`, `convex/http.ts` and `convex/staticHosting.ts`.
396
+ Build-time public values must be passed in `build_env` (the sandbox has no
397
+ `.env` files). Verify the live URL in a browser after `succeeded`.
398
+
399
+ ### 2b. Publish from a terminal
400
+
401
+ With Node in a workspace, fetch the admin key with `GET /deploy/<slug>/convex`
402
+ and run the same steps yourself:
403
+
404
+ ```bash
405
+ export CONVEX_SELF_HOSTED_URL=<deploymentUrl> CONVEX_SELF_HOSTED_ADMIN_KEY=<adminKey>
406
+ npx convex deploy -y && npm run build && npx @convex-dev/static-hosting upload -d dist
407
+ ```
408
+
409
+ Keep the admin key out of the repository and logs; it contains a `|`, so quote
410
+ it in `.env` files. Both paths publish to the same backend.
411
+
412
+ To inspect Convex data, read `GET /db/skill` ("Convex").
@@ -0,0 +1,182 @@
1
+ ---
2
+ name: egbe-os-design
3
+ description: Search the design-reference catalog and retrieve concrete design systems for interface work.
4
+ metadata:
5
+ egbe-when: "Use for interface design; offer when inconsistent visuals need a coherent reference."
6
+ egbe-visible: "true"
7
+ egbe-title: "Design systems"
8
+ egbe-description: "Give your product a consistent visual language using reference design systems for typography, colors and components."
9
+ egbe-category: "Product & design"
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
+ # Design references
57
+
58
+ Search reference design systems from shipped product sites and retrieve their
59
+ concrete values and source attribution. The caller chooses the direction and
60
+ scope; a catalog reference is not a mandatory design or approval of a brand.
61
+
62
+ Authenticate with `Authorization: Bearer $OS_API_KEY`. Mirrored catalog reads,
63
+ facets, browsing and lexical search have no per-call charge. Semantic search
64
+ uses the caller's wallet-tracked `ai-api` credential: each semantic query pays
65
+ for its query embedding, and the caller that starts a cold or refreshed shared
66
+ corpus build also pays for embedding the roughly 1,300 catalog entries. A
67
+ restart, catalog update or embedding-model change can require that corpus
68
+ build again. Check `scorer` in the response; a lexical fallback does not erase
69
+ charges for embedding work already attempted.
70
+
71
+ ## Workflow
72
+
73
+ ```
74
+ GET /design/facets -> POST /design/styles/search -> GET /design/styles/{id}/design.md
75
+ ```
76
+
77
+ Save the returned markdown as `egbe-docs/product/design-reference.md` when using it
78
+ as source material. Keep it distinct from the accepted `product/design.md` direction;
79
+ preserve attribution and record the selected style ID/source with the task.
80
+
81
+ ## 1. See what the catalog actually contains
82
+
83
+ Search is **semantic** (embedding similarity — understands meaning, and other
84
+ languages) when your account has an ai-api credential, and **lexical** (token
85
+ overlap) otherwise. This is automatic; check the search response's `scorer`
86
+ field to see which one answered. For lexical queries specifically, invented
87
+ tags match nothing while words that exist in the catalog match well — start
88
+ here and reuse these values as query terms either way.
89
+
90
+ ```bash
91
+ OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/design/facets?theme=dark&limit=25" -s
92
+ ```
93
+
94
+ Returns ranked `fonts` (Inter, Geist Mono, DM Sans…), `colors` (Graphite, Paper
95
+ White, Ink Black…) and `themes` with counts.
96
+
97
+ ## 2. Search
98
+
99
+ ```bash
100
+ OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/design/styles/search" -s -X POST \
101
+ -H 'Content-Type: application/json' \
102
+ -d '{"query":"editorial serif on cream paper","theme":"light","limit":5}'
103
+ ```
104
+
105
+ Each hit carries `style_id`, `site_name`, `url`, `theme`, `north_star` (a
106
+ one-line description of the visual direction), `fonts`, `colors`,
107
+ `thumbnail_url` and `score`. With semantic search, describe surfaces, type and
108
+ mood in any language ("тёплый editorial минимализм на кремовой бумаге" works);
109
+ with lexical, stick to English words from the catalog's own vocabulary
110
+ ("near-black canvas, mono labels, one acid accent") rather than a business
111
+ category.
112
+
113
+ Browsing works too, when you already know the constraint:
114
+
115
+ ```bash
116
+ OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/design/styles?font=Geist&theme=dark&limit=10" -s
117
+ ```
118
+
119
+ ## 3. Take the design system
120
+
121
+ ```bash
122
+ mkdir -p egbe-docs/product
123
+ OS_AGENT_NAME="<your agent name>" python3 "<skills-directory>/egbe-os-quickstart/scripts/egbe-curl.py" --egbe-request "/design/styles/$STYLE_ID/design.md" -s \
124
+ | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["markdown"])' > egbe-docs/product/design-reference.md
125
+ ```
126
+
127
+ `GET /design/styles/{id}` returns the same content as JSON when you want to read
128
+ specific fields instead of the whole document:
129
+
130
+ - `colors` — hex + name + **role** ("the one chromatic button in the system")
131
+ - `surfaces` — elevation levels with the hex for each
132
+ - `typography` / `type_scale` — families, weights, sizes, letter-spacing per role
133
+ - `spacing` — page max width, section gap, element gap, card padding, radii
134
+ - `components` — spec text per component (button, card, nav, input…)
135
+ - `dos` / `donts` — the rules that keep a copy from looking like a knock-off
136
+ - `guides` — an "Agent Prompt Guide" with ready component prompts, when present
137
+ - `similar` — sibling styles with their `style_id`, for a second opinion
138
+
139
+ ## Errors
140
+
141
+ Unavailability is always `503` with a typed `data`: `error`, `reason`,
142
+ `retryable`, `retry_after_seconds` and the `mirror` status. An empty or
143
+ unavailable catalog is never returned as an empty `200` result.
144
+
145
+ - `data.error: "design_catalog_warming"` — the mirror is still being built on
146
+ a freshly started gateway (first walk is ~1 min). Retry after
147
+ `retry_after_seconds` (~30s); after that it is memory-fast and refreshes daily.
148
+ - `data.error: "design_catalog_unavailable"` — facets, search or browse cannot
149
+ be served: the upstream catalog failed and the gateway has no copy. The
150
+ message carries the upstream reason.
151
+ - `reason: "upstream_forbidden"`, `retryable: false` — the upstream refuses
152
+ access (HTTP 401/403). Do not retry. Continue without a catalog reference,
153
+ as below, and tell the user the design catalog is unavailable.
154
+ - Other reasons, `retryable: true` — retry after `retry_after_seconds` (~1 min)
155
+ at most 2–3 times, then continue without a catalog reference.
156
+ - `data.error: "design_style_unavailable"` — one style's detail or `design.md`
157
+ could not be fetched and was not cached. Try at most one other result, then
158
+ build from the search result's fonts and colours or continue without a
159
+ catalog reference.
160
+ - `422` — `style_id` must be a uuid from a search result.
161
+
162
+ Continuing without a catalog reference means: use the accepted
163
+ `product/design.md` direction, the user's brand or existing product UI, or
164
+ references the user supplies; otherwise make a deliberate, restrained choice of
165
+ one type pairing, a small named palette with roles and a spacing scale, and
166
+ record it as your own decision. Do not present it as a catalog reference, do
167
+ not invent a `style_id` or attribution, and do not block the build on the catalog.
168
+
169
+ When the upstream fails after a copy exists, the gateway keeps serving its last
170
+ good copy, including after a restart. `data.availability` in `GET /design`
171
+ reports `available`, `state` (`ready`, `stale`, `degraded`, `warming` or
172
+ `unavailable`) and `reason`; `degraded` means the copy could not be refreshed.
173
+ Search, browse and facets still work from it, and so do style detail and
174
+ `design.md` for styles the gateway fetched before.
175
+
176
+ Semantic search never returns an error of its own: no ai-api credential, a
177
+ still-building vector cache, or an embeddings-call failure all degrade silently
178
+ to the lexical result for that one request — `scorer` in the response tells you
179
+ which one you got.
180
+
181
+ Catalog content © Refero (`styles.refero.design`), mirrored unmodified and
182
+ attributed at the bottom of every downloaded design reference.