pi-cloudflare 0.1.0

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 (410) hide show
  1. package/LICENSE +674 -0
  2. package/README.md +67 -0
  3. package/bin/setup.mjs +103 -0
  4. package/dist/auth-flow.d.ts +15 -0
  5. package/dist/auth-flow.d.ts.map +1 -0
  6. package/dist/auth-flow.js +90 -0
  7. package/dist/auth-flow.js.map +1 -0
  8. package/dist/client.d.ts +18 -0
  9. package/dist/client.d.ts.map +1 -0
  10. package/dist/client.js +47 -0
  11. package/dist/client.js.map +1 -0
  12. package/dist/config.d.ts +13 -0
  13. package/dist/config.d.ts.map +1 -0
  14. package/dist/config.js +10 -0
  15. package/dist/config.js.map +1 -0
  16. package/dist/index.d.ts +24 -0
  17. package/dist/index.d.ts.map +1 -0
  18. package/dist/index.js +109 -0
  19. package/dist/index.js.map +1 -0
  20. package/dist/oauth.d.ts +44 -0
  21. package/dist/oauth.d.ts.map +1 -0
  22. package/dist/oauth.js +135 -0
  23. package/dist/oauth.js.map +1 -0
  24. package/dist/proxy.d.ts +29 -0
  25. package/dist/proxy.d.ts.map +1 -0
  26. package/dist/proxy.js +39 -0
  27. package/dist/proxy.js.map +1 -0
  28. package/dist/servers.d.ts +19 -0
  29. package/dist/servers.d.ts.map +1 -0
  30. package/dist/servers.js +40 -0
  31. package/dist/servers.js.map +1 -0
  32. package/dist/token-store.d.ts +23 -0
  33. package/dist/token-store.d.ts.map +1 -0
  34. package/dist/token-store.js +47 -0
  35. package/dist/token-store.js.map +1 -0
  36. package/package.json +67 -0
  37. package/skills/agents-sdk/SKILL.md +221 -0
  38. package/skills/agents-sdk/references/browse-the-web.md +63 -0
  39. package/skills/agents-sdk/references/callable.md +92 -0
  40. package/skills/agents-sdk/references/client-sdk.md +110 -0
  41. package/skills/agents-sdk/references/codemode.md +110 -0
  42. package/skills/agents-sdk/references/configuration.md +72 -0
  43. package/skills/agents-sdk/references/durable-execution.md +51 -0
  44. package/skills/agents-sdk/references/email.md +146 -0
  45. package/skills/agents-sdk/references/human-in-the-loop.md +67 -0
  46. package/skills/agents-sdk/references/mcp.md +188 -0
  47. package/skills/agents-sdk/references/observability.md +44 -0
  48. package/skills/agents-sdk/references/queue-retries.md +79 -0
  49. package/skills/agents-sdk/references/routing.md +75 -0
  50. package/skills/agents-sdk/references/server-driven-messages.md +63 -0
  51. package/skills/agents-sdk/references/state-scheduling.md +171 -0
  52. package/skills/agents-sdk/references/streaming-chat.md +198 -0
  53. package/skills/agents-sdk/references/think.md +112 -0
  54. package/skills/agents-sdk/references/voice.md +68 -0
  55. package/skills/agents-sdk/references/webhooks-push.md +86 -0
  56. package/skills/agents-sdk/references/workflows.md +132 -0
  57. package/skills/cloudflare/SKILL.md +248 -0
  58. package/skills/cloudflare/references/agents-sdk/README.md +89 -0
  59. package/skills/cloudflare/references/agents-sdk/api.md +190 -0
  60. package/skills/cloudflare/references/agents-sdk/configuration.md +182 -0
  61. package/skills/cloudflare/references/agents-sdk/gotchas.md +158 -0
  62. package/skills/cloudflare/references/agents-sdk/patterns.md +192 -0
  63. package/skills/cloudflare/references/ai-gateway/README.md +175 -0
  64. package/skills/cloudflare/references/ai-gateway/configuration.md +111 -0
  65. package/skills/cloudflare/references/ai-gateway/dynamic-routing.md +82 -0
  66. package/skills/cloudflare/references/ai-gateway/features.md +96 -0
  67. package/skills/cloudflare/references/ai-gateway/sdk-integration.md +114 -0
  68. package/skills/cloudflare/references/ai-gateway/troubleshooting.md +88 -0
  69. package/skills/cloudflare/references/ai-search/README.md +138 -0
  70. package/skills/cloudflare/references/ai-search/api.md +87 -0
  71. package/skills/cloudflare/references/ai-search/configuration.md +88 -0
  72. package/skills/cloudflare/references/ai-search/gotchas.md +81 -0
  73. package/skills/cloudflare/references/ai-search/patterns.md +85 -0
  74. package/skills/cloudflare/references/analytics-engine/README.md +94 -0
  75. package/skills/cloudflare/references/analytics-engine/api.md +112 -0
  76. package/skills/cloudflare/references/analytics-engine/configuration.md +112 -0
  77. package/skills/cloudflare/references/analytics-engine/gotchas.md +85 -0
  78. package/skills/cloudflare/references/analytics-engine/patterns.md +83 -0
  79. package/skills/cloudflare/references/api/README.md +66 -0
  80. package/skills/cloudflare/references/api/api.md +204 -0
  81. package/skills/cloudflare/references/api/configuration.md +160 -0
  82. package/skills/cloudflare/references/api/gotchas.md +225 -0
  83. package/skills/cloudflare/references/api/patterns.md +204 -0
  84. package/skills/cloudflare/references/api-shield/README.md +44 -0
  85. package/skills/cloudflare/references/api-shield/api.md +141 -0
  86. package/skills/cloudflare/references/api-shield/configuration.md +192 -0
  87. package/skills/cloudflare/references/api-shield/gotchas.md +125 -0
  88. package/skills/cloudflare/references/api-shield/patterns.md +180 -0
  89. package/skills/cloudflare/references/argo-smart-routing/README.md +90 -0
  90. package/skills/cloudflare/references/argo-smart-routing/api.md +240 -0
  91. package/skills/cloudflare/references/argo-smart-routing/configuration.md +197 -0
  92. package/skills/cloudflare/references/argo-smart-routing/gotchas.md +111 -0
  93. package/skills/cloudflare/references/argo-smart-routing/patterns.md +104 -0
  94. package/skills/cloudflare/references/artifacts/README.md +79 -0
  95. package/skills/cloudflare/references/artifacts/api.md +128 -0
  96. package/skills/cloudflare/references/artifacts/configuration.md +92 -0
  97. package/skills/cloudflare/references/bindings/README.md +122 -0
  98. package/skills/cloudflare/references/bindings/api.md +203 -0
  99. package/skills/cloudflare/references/bindings/configuration.md +188 -0
  100. package/skills/cloudflare/references/bindings/gotchas.md +208 -0
  101. package/skills/cloudflare/references/bindings/patterns.md +200 -0
  102. package/skills/cloudflare/references/bot-management/README.md +94 -0
  103. package/skills/cloudflare/references/bot-management/api.md +169 -0
  104. package/skills/cloudflare/references/bot-management/configuration.md +163 -0
  105. package/skills/cloudflare/references/bot-management/gotchas.md +114 -0
  106. package/skills/cloudflare/references/bot-management/patterns.md +182 -0
  107. package/skills/cloudflare/references/browser-rendering/README.md +78 -0
  108. package/skills/cloudflare/references/browser-rendering/api.md +108 -0
  109. package/skills/cloudflare/references/browser-rendering/configuration.md +78 -0
  110. package/skills/cloudflare/references/browser-rendering/gotchas.md +88 -0
  111. package/skills/cloudflare/references/browser-rendering/patterns.md +91 -0
  112. package/skills/cloudflare/references/c3/README.md +111 -0
  113. package/skills/cloudflare/references/c3/api.md +71 -0
  114. package/skills/cloudflare/references/c3/configuration.md +81 -0
  115. package/skills/cloudflare/references/c3/gotchas.md +92 -0
  116. package/skills/cloudflare/references/c3/patterns.md +82 -0
  117. package/skills/cloudflare/references/cache-reserve/README.md +147 -0
  118. package/skills/cloudflare/references/cache-reserve/api.md +194 -0
  119. package/skills/cloudflare/references/cache-reserve/configuration.md +169 -0
  120. package/skills/cloudflare/references/cache-reserve/gotchas.md +132 -0
  121. package/skills/cloudflare/references/cache-reserve/patterns.md +197 -0
  122. package/skills/cloudflare/references/containers/README.md +85 -0
  123. package/skills/cloudflare/references/containers/api.md +187 -0
  124. package/skills/cloudflare/references/containers/configuration.md +188 -0
  125. package/skills/cloudflare/references/containers/gotchas.md +178 -0
  126. package/skills/cloudflare/references/containers/patterns.md +202 -0
  127. package/skills/cloudflare/references/cron-triggers/README.md +99 -0
  128. package/skills/cloudflare/references/cron-triggers/api.md +196 -0
  129. package/skills/cloudflare/references/cron-triggers/configuration.md +180 -0
  130. package/skills/cloudflare/references/cron-triggers/gotchas.md +199 -0
  131. package/skills/cloudflare/references/cron-triggers/patterns.md +190 -0
  132. package/skills/cloudflare/references/d1/README.md +133 -0
  133. package/skills/cloudflare/references/d1/api.md +196 -0
  134. package/skills/cloudflare/references/d1/configuration.md +191 -0
  135. package/skills/cloudflare/references/d1/gotchas.md +98 -0
  136. package/skills/cloudflare/references/d1/patterns.md +189 -0
  137. package/skills/cloudflare/references/ddos/README.md +41 -0
  138. package/skills/cloudflare/references/ddos/api.md +164 -0
  139. package/skills/cloudflare/references/ddos/configuration.md +93 -0
  140. package/skills/cloudflare/references/ddos/gotchas.md +107 -0
  141. package/skills/cloudflare/references/ddos/patterns.md +174 -0
  142. package/skills/cloudflare/references/do-storage/README.md +75 -0
  143. package/skills/cloudflare/references/do-storage/api.md +102 -0
  144. package/skills/cloudflare/references/do-storage/configuration.md +112 -0
  145. package/skills/cloudflare/references/do-storage/gotchas.md +150 -0
  146. package/skills/cloudflare/references/do-storage/patterns.md +194 -0
  147. package/skills/cloudflare/references/do-storage/testing.md +183 -0
  148. package/skills/cloudflare/references/durable-objects/README.md +185 -0
  149. package/skills/cloudflare/references/durable-objects/api.md +187 -0
  150. package/skills/cloudflare/references/durable-objects/configuration.md +160 -0
  151. package/skills/cloudflare/references/durable-objects/gotchas.md +197 -0
  152. package/skills/cloudflare/references/durable-objects/patterns.md +201 -0
  153. package/skills/cloudflare/references/email-routing/README.md +89 -0
  154. package/skills/cloudflare/references/email-routing/api.md +195 -0
  155. package/skills/cloudflare/references/email-routing/configuration.md +186 -0
  156. package/skills/cloudflare/references/email-routing/gotchas.md +196 -0
  157. package/skills/cloudflare/references/email-routing/patterns.md +229 -0
  158. package/skills/cloudflare/references/email-workers/README.md +151 -0
  159. package/skills/cloudflare/references/email-workers/api.md +237 -0
  160. package/skills/cloudflare/references/email-workers/configuration.md +112 -0
  161. package/skills/cloudflare/references/email-workers/gotchas.md +125 -0
  162. package/skills/cloudflare/references/email-workers/patterns.md +102 -0
  163. package/skills/cloudflare/references/flagship/README.md +59 -0
  164. package/skills/cloudflare/references/flagship/api.md +390 -0
  165. package/skills/cloudflare/references/flagship/configuration.md +202 -0
  166. package/skills/cloudflare/references/flagship/gotchas.md +178 -0
  167. package/skills/cloudflare/references/flagship/patterns.md +469 -0
  168. package/skills/cloudflare/references/graphql-api/README.md +147 -0
  169. package/skills/cloudflare/references/graphql-api/api.md +175 -0
  170. package/skills/cloudflare/references/graphql-api/configuration.md +118 -0
  171. package/skills/cloudflare/references/graphql-api/gotchas.md +110 -0
  172. package/skills/cloudflare/references/graphql-api/patterns.md +225 -0
  173. package/skills/cloudflare/references/hyperdrive/README.md +82 -0
  174. package/skills/cloudflare/references/hyperdrive/api.md +143 -0
  175. package/skills/cloudflare/references/hyperdrive/configuration.md +159 -0
  176. package/skills/cloudflare/references/hyperdrive/gotchas.md +77 -0
  177. package/skills/cloudflare/references/hyperdrive/patterns.md +190 -0
  178. package/skills/cloudflare/references/images/README.md +61 -0
  179. package/skills/cloudflare/references/images/api.md +96 -0
  180. package/skills/cloudflare/references/images/configuration.md +211 -0
  181. package/skills/cloudflare/references/images/gotchas.md +99 -0
  182. package/skills/cloudflare/references/images/patterns.md +115 -0
  183. package/skills/cloudflare/references/kv/README.md +89 -0
  184. package/skills/cloudflare/references/kv/api.md +160 -0
  185. package/skills/cloudflare/references/kv/configuration.md +144 -0
  186. package/skills/cloudflare/references/kv/gotchas.md +131 -0
  187. package/skills/cloudflare/references/kv/patterns.md +196 -0
  188. package/skills/cloudflare/references/miniflare/README.md +105 -0
  189. package/skills/cloudflare/references/miniflare/api.md +187 -0
  190. package/skills/cloudflare/references/miniflare/configuration.md +173 -0
  191. package/skills/cloudflare/references/miniflare/gotchas.md +160 -0
  192. package/skills/cloudflare/references/miniflare/patterns.md +181 -0
  193. package/skills/cloudflare/references/network-interconnect/README.md +99 -0
  194. package/skills/cloudflare/references/network-interconnect/api.md +199 -0
  195. package/skills/cloudflare/references/network-interconnect/configuration.md +114 -0
  196. package/skills/cloudflare/references/network-interconnect/gotchas.md +165 -0
  197. package/skills/cloudflare/references/network-interconnect/patterns.md +166 -0
  198. package/skills/cloudflare/references/observability/README.md +88 -0
  199. package/skills/cloudflare/references/observability/api.md +164 -0
  200. package/skills/cloudflare/references/observability/configuration.md +169 -0
  201. package/skills/cloudflare/references/observability/gotchas.md +115 -0
  202. package/skills/cloudflare/references/observability/patterns.md +105 -0
  203. package/skills/cloudflare/references/pages/README.md +88 -0
  204. package/skills/cloudflare/references/pages/api.md +204 -0
  205. package/skills/cloudflare/references/pages/configuration.md +201 -0
  206. package/skills/cloudflare/references/pages/gotchas.md +203 -0
  207. package/skills/cloudflare/references/pages/patterns.md +204 -0
  208. package/skills/cloudflare/references/pages-functions/README.md +98 -0
  209. package/skills/cloudflare/references/pages-functions/api.md +143 -0
  210. package/skills/cloudflare/references/pages-functions/configuration.md +122 -0
  211. package/skills/cloudflare/references/pages-functions/gotchas.md +94 -0
  212. package/skills/cloudflare/references/pages-functions/patterns.md +137 -0
  213. package/skills/cloudflare/references/pipelines/README.md +90 -0
  214. package/skills/cloudflare/references/pipelines/api.md +124 -0
  215. package/skills/cloudflare/references/pipelines/configuration.md +155 -0
  216. package/skills/cloudflare/references/pipelines/gotchas.md +58 -0
  217. package/skills/cloudflare/references/pipelines/patterns.md +130 -0
  218. package/skills/cloudflare/references/pulumi/README.md +100 -0
  219. package/skills/cloudflare/references/pulumi/api.md +200 -0
  220. package/skills/cloudflare/references/pulumi/configuration.md +198 -0
  221. package/skills/cloudflare/references/pulumi/gotchas.md +181 -0
  222. package/skills/cloudflare/references/pulumi/patterns.md +191 -0
  223. package/skills/cloudflare/references/queues/README.md +96 -0
  224. package/skills/cloudflare/references/queues/api.md +206 -0
  225. package/skills/cloudflare/references/queues/configuration.md +144 -0
  226. package/skills/cloudflare/references/queues/gotchas.md +206 -0
  227. package/skills/cloudflare/references/queues/patterns.md +220 -0
  228. package/skills/cloudflare/references/r2/README.md +95 -0
  229. package/skills/cloudflare/references/r2/api.md +200 -0
  230. package/skills/cloudflare/references/r2/configuration.md +165 -0
  231. package/skills/cloudflare/references/r2/gotchas.md +190 -0
  232. package/skills/cloudflare/references/r2/patterns.md +193 -0
  233. package/skills/cloudflare/references/r2-data-catalog/README.md +75 -0
  234. package/skills/cloudflare/references/r2-data-catalog/api.md +122 -0
  235. package/skills/cloudflare/references/r2-data-catalog/configuration.md +98 -0
  236. package/skills/cloudflare/references/r2-data-catalog/gotchas.md +55 -0
  237. package/skills/cloudflare/references/r2-data-catalog/patterns.md +122 -0
  238. package/skills/cloudflare/references/r2-sql/README.md +64 -0
  239. package/skills/cloudflare/references/r2-sql/api.md +121 -0
  240. package/skills/cloudflare/references/r2-sql/configuration.md +50 -0
  241. package/skills/cloudflare/references/r2-sql/gotchas.md +39 -0
  242. package/skills/cloudflare/references/r2-sql/patterns.md +118 -0
  243. package/skills/cloudflare/references/realtime-sfu/README.md +65 -0
  244. package/skills/cloudflare/references/realtime-sfu/api.md +158 -0
  245. package/skills/cloudflare/references/realtime-sfu/configuration.md +137 -0
  246. package/skills/cloudflare/references/realtime-sfu/gotchas.md +133 -0
  247. package/skills/cloudflare/references/realtime-sfu/patterns.md +174 -0
  248. package/skills/cloudflare/references/realtimekit/README.md +113 -0
  249. package/skills/cloudflare/references/realtimekit/api.md +212 -0
  250. package/skills/cloudflare/references/realtimekit/configuration.md +203 -0
  251. package/skills/cloudflare/references/realtimekit/gotchas.md +169 -0
  252. package/skills/cloudflare/references/realtimekit/patterns.md +223 -0
  253. package/skills/cloudflare/references/sandbox/README.md +96 -0
  254. package/skills/cloudflare/references/sandbox/api.md +198 -0
  255. package/skills/cloudflare/references/sandbox/configuration.md +143 -0
  256. package/skills/cloudflare/references/sandbox/gotchas.md +194 -0
  257. package/skills/cloudflare/references/sandbox/patterns.md +201 -0
  258. package/skills/cloudflare/references/secrets-store/README.md +74 -0
  259. package/skills/cloudflare/references/secrets-store/api.md +200 -0
  260. package/skills/cloudflare/references/secrets-store/configuration.md +185 -0
  261. package/skills/cloudflare/references/secrets-store/gotchas.md +97 -0
  262. package/skills/cloudflare/references/secrets-store/patterns.md +207 -0
  263. package/skills/cloudflare/references/smart-placement/README.md +138 -0
  264. package/skills/cloudflare/references/smart-placement/api.md +183 -0
  265. package/skills/cloudflare/references/smart-placement/configuration.md +196 -0
  266. package/skills/cloudflare/references/smart-placement/gotchas.md +174 -0
  267. package/skills/cloudflare/references/smart-placement/patterns.md +183 -0
  268. package/skills/cloudflare/references/snippets/README.md +68 -0
  269. package/skills/cloudflare/references/snippets/api.md +198 -0
  270. package/skills/cloudflare/references/snippets/configuration.md +227 -0
  271. package/skills/cloudflare/references/snippets/gotchas.md +86 -0
  272. package/skills/cloudflare/references/snippets/patterns.md +135 -0
  273. package/skills/cloudflare/references/spectrum/README.md +52 -0
  274. package/skills/cloudflare/references/spectrum/api.md +181 -0
  275. package/skills/cloudflare/references/spectrum/configuration.md +194 -0
  276. package/skills/cloudflare/references/spectrum/gotchas.md +145 -0
  277. package/skills/cloudflare/references/spectrum/patterns.md +196 -0
  278. package/skills/cloudflare/references/static-assets/README.md +65 -0
  279. package/skills/cloudflare/references/static-assets/api.md +199 -0
  280. package/skills/cloudflare/references/static-assets/configuration.md +186 -0
  281. package/skills/cloudflare/references/static-assets/gotchas.md +162 -0
  282. package/skills/cloudflare/references/static-assets/patterns.md +189 -0
  283. package/skills/cloudflare/references/stream/README.md +114 -0
  284. package/skills/cloudflare/references/stream/api-live.md +195 -0
  285. package/skills/cloudflare/references/stream/api.md +199 -0
  286. package/skills/cloudflare/references/stream/configuration.md +141 -0
  287. package/skills/cloudflare/references/stream/gotchas.md +130 -0
  288. package/skills/cloudflare/references/stream/patterns.md +184 -0
  289. package/skills/cloudflare/references/tail-workers/README.md +89 -0
  290. package/skills/cloudflare/references/tail-workers/api.md +200 -0
  291. package/skills/cloudflare/references/tail-workers/configuration.md +176 -0
  292. package/skills/cloudflare/references/tail-workers/gotchas.md +192 -0
  293. package/skills/cloudflare/references/tail-workers/patterns.md +180 -0
  294. package/skills/cloudflare/references/terraform/README.md +102 -0
  295. package/skills/cloudflare/references/terraform/api.md +178 -0
  296. package/skills/cloudflare/references/terraform/configuration.md +197 -0
  297. package/skills/cloudflare/references/terraform/gotchas.md +150 -0
  298. package/skills/cloudflare/references/terraform/patterns.md +174 -0
  299. package/skills/cloudflare/references/tunnel/README.md +129 -0
  300. package/skills/cloudflare/references/tunnel/api.md +193 -0
  301. package/skills/cloudflare/references/tunnel/configuration.md +157 -0
  302. package/skills/cloudflare/references/tunnel/gotchas.md +147 -0
  303. package/skills/cloudflare/references/tunnel/networking.md +168 -0
  304. package/skills/cloudflare/references/tunnel/patterns.md +192 -0
  305. package/skills/cloudflare/references/turn/README.md +82 -0
  306. package/skills/cloudflare/references/turn/api.md +239 -0
  307. package/skills/cloudflare/references/turn/configuration.md +179 -0
  308. package/skills/cloudflare/references/turn/gotchas.md +231 -0
  309. package/skills/cloudflare/references/turn/patterns.md +213 -0
  310. package/skills/cloudflare/references/turnstile/README.md +99 -0
  311. package/skills/cloudflare/references/turnstile/api.md +240 -0
  312. package/skills/cloudflare/references/turnstile/configuration.md +222 -0
  313. package/skills/cloudflare/references/turnstile/gotchas.md +218 -0
  314. package/skills/cloudflare/references/turnstile/patterns.md +193 -0
  315. package/skills/cloudflare/references/vectorize/README.md +133 -0
  316. package/skills/cloudflare/references/vectorize/api.md +88 -0
  317. package/skills/cloudflare/references/vectorize/configuration.md +88 -0
  318. package/skills/cloudflare/references/vectorize/gotchas.md +76 -0
  319. package/skills/cloudflare/references/vectorize/patterns.md +90 -0
  320. package/skills/cloudflare/references/waf/README.md +113 -0
  321. package/skills/cloudflare/references/waf/api.md +202 -0
  322. package/skills/cloudflare/references/waf/configuration.md +203 -0
  323. package/skills/cloudflare/references/waf/gotchas.md +204 -0
  324. package/skills/cloudflare/references/waf/patterns.md +197 -0
  325. package/skills/cloudflare/references/web-analytics/README.md +141 -0
  326. package/skills/cloudflare/references/web-analytics/configuration.md +76 -0
  327. package/skills/cloudflare/references/web-analytics/gotchas.md +82 -0
  328. package/skills/cloudflare/references/web-analytics/integration.md +60 -0
  329. package/skills/cloudflare/references/web-analytics/patterns.md +91 -0
  330. package/skills/cloudflare/references/workerd/README.md +78 -0
  331. package/skills/cloudflare/references/workerd/api.md +185 -0
  332. package/skills/cloudflare/references/workerd/configuration.md +183 -0
  333. package/skills/cloudflare/references/workerd/gotchas.md +139 -0
  334. package/skills/cloudflare/references/workerd/patterns.md +192 -0
  335. package/skills/cloudflare/references/workers/README.md +108 -0
  336. package/skills/cloudflare/references/workers/api.md +195 -0
  337. package/skills/cloudflare/references/workers/configuration.md +185 -0
  338. package/skills/cloudflare/references/workers/frameworks.md +197 -0
  339. package/skills/cloudflare/references/workers/gotchas.md +137 -0
  340. package/skills/cloudflare/references/workers/patterns.md +198 -0
  341. package/skills/cloudflare/references/workers-ai/README.md +197 -0
  342. package/skills/cloudflare/references/workers-ai/api.md +112 -0
  343. package/skills/cloudflare/references/workers-ai/configuration.md +97 -0
  344. package/skills/cloudflare/references/workers-ai/gotchas.md +114 -0
  345. package/skills/cloudflare/references/workers-ai/patterns.md +120 -0
  346. package/skills/cloudflare/references/workers-for-platforms/README.md +89 -0
  347. package/skills/cloudflare/references/workers-for-platforms/api.md +196 -0
  348. package/skills/cloudflare/references/workers-for-platforms/configuration.md +167 -0
  349. package/skills/cloudflare/references/workers-for-platforms/gotchas.md +134 -0
  350. package/skills/cloudflare/references/workers-for-platforms/patterns.md +188 -0
  351. package/skills/cloudflare/references/workers-playground/README.md +127 -0
  352. package/skills/cloudflare/references/workers-playground/api.md +101 -0
  353. package/skills/cloudflare/references/workers-playground/configuration.md +163 -0
  354. package/skills/cloudflare/references/workers-playground/gotchas.md +88 -0
  355. package/skills/cloudflare/references/workers-playground/patterns.md +132 -0
  356. package/skills/cloudflare/references/workers-vpc/README.md +127 -0
  357. package/skills/cloudflare/references/workers-vpc/api.md +202 -0
  358. package/skills/cloudflare/references/workers-vpc/configuration.md +147 -0
  359. package/skills/cloudflare/references/workers-vpc/gotchas.md +167 -0
  360. package/skills/cloudflare/references/workers-vpc/patterns.md +209 -0
  361. package/skills/cloudflare/references/workflows/README.md +77 -0
  362. package/skills/cloudflare/references/workflows/api.md +218 -0
  363. package/skills/cloudflare/references/workflows/configuration.md +152 -0
  364. package/skills/cloudflare/references/workflows/gotchas.md +90 -0
  365. package/skills/cloudflare/references/workflows/patterns.md +175 -0
  366. package/skills/cloudflare/references/wrangler/README.md +135 -0
  367. package/skills/cloudflare/references/wrangler/api.md +188 -0
  368. package/skills/cloudflare/references/wrangler/configuration.md +197 -0
  369. package/skills/cloudflare/references/wrangler/gotchas.md +197 -0
  370. package/skills/cloudflare/references/wrangler/patterns.md +209 -0
  371. package/skills/cloudflare/references/zaraz/IMPLEMENTATION_SUMMARY.md +121 -0
  372. package/skills/cloudflare/references/zaraz/README.md +111 -0
  373. package/skills/cloudflare/references/zaraz/api.md +112 -0
  374. package/skills/cloudflare/references/zaraz/configuration.md +90 -0
  375. package/skills/cloudflare/references/zaraz/gotchas.md +81 -0
  376. package/skills/cloudflare/references/zaraz/patterns.md +74 -0
  377. package/skills/cloudflare-email-service/SKILL.md +103 -0
  378. package/skills/cloudflare-email-service/references/cli-and-mcp.md +125 -0
  379. package/skills/cloudflare-email-service/references/deliverability.md +285 -0
  380. package/skills/cloudflare-email-service/references/rest-api.md +184 -0
  381. package/skills/cloudflare-email-service/references/routing.md +199 -0
  382. package/skills/cloudflare-email-service/references/sending.md +252 -0
  383. package/skills/cloudflare-one/SKILL.md +176 -0
  384. package/skills/cloudflare-one-migrations/SKILL.md +110 -0
  385. package/skills/durable-objects/SKILL.md +186 -0
  386. package/skills/durable-objects/references/rules.md +295 -0
  387. package/skills/durable-objects/references/testing.md +264 -0
  388. package/skills/durable-objects/references/workers.md +346 -0
  389. package/skills/sandbox-migrate-to-next/SKILL.md +185 -0
  390. package/skills/sandbox-next/SKILL.md +91 -0
  391. package/skills/sandbox-next/references/api-quick-ref.md +94 -0
  392. package/skills/sandbox-next/references/examples.md +15 -0
  393. package/skills/sandbox-stable/SKILL.md +110 -0
  394. package/skills/turnstile-spin/README.md +51 -0
  395. package/skills/turnstile-spin/SKILL.md +330 -0
  396. package/skills/turnstile-spin/references/astro.md +199 -0
  397. package/skills/turnstile-spin/references/hugo.md +114 -0
  398. package/skills/turnstile-spin/references/nextjs-app.md +261 -0
  399. package/skills/turnstile-spin/references/nextjs-pages.md +82 -0
  400. package/skills/turnstile-spin/references/sveltekit.md +191 -0
  401. package/skills/turnstile-spin/references/vanilla-html.md +157 -0
  402. package/skills/turnstile-spin/scripts/auth-probe.sh +285 -0
  403. package/skills/turnstile-spin/scripts/persist-skill.sh +114 -0
  404. package/skills/turnstile-spin/scripts/validate.sh +137 -0
  405. package/skills/turnstile-spin/scripts/widget-create.sh +121 -0
  406. package/skills/turnstile-spin/tests/validation.md +62 -0
  407. package/skills/workers-best-practices/SKILL.md +127 -0
  408. package/skills/workers-best-practices/references/review.md +174 -0
  409. package/skills/workers-best-practices/references/rules.md +467 -0
  410. package/skills/wrangler/SKILL.md +922 -0
package/skills/cloudflare/references/turnstile/patterns.md ADDED
@@ -0,0 +1,193 @@
1
+ # Common Patterns
2
+
3
+ ## Form Integration
4
+
5
+ ### Basic Form (Implicit Rendering)
6
+
7
+ ```html
8
+ <!DOCTYPE html>
9
+ <html>
10
+ <head>
11
+ <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
12
+ </head>
13
+ <body>
14
+ <form action="/submit" method="POST">
15
+ <input type="email" name="email" required>
16
+ <div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
17
+ <button type="submit">Submit</button>
18
+ </form>
19
+ </body>
20
+ </html>
21
+ ```
22
+
23
+ ### Controlled Form (Explicit Rendering)
24
+
25
+ ```javascript
26
+ <script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"></script>
27
+ <script>
28
+ let widgetId = window.turnstile.render('#container', {
29
+ sitekey: 'YOUR_SITE_KEY',
30
+ callback: (token) => console.log('Token:', token)
31
+ });
32
+
33
+ form.addEventListener('submit', async (e) => {
34
+ e.preventDefault();
35
+ const token = window.turnstile.getResponse(widgetId);
36
+ if (!token) return;
37
+
38
+ const response = await fetch('/submit', {
39
+ method: 'POST',
40
+ body: JSON.stringify({ 'cf-turnstile-response': token })
41
+ });
42
+
43
+ if (!response.ok) window.turnstile.reset(widgetId);
44
+ });
45
+ </script>
46
+ ```
47
+
48
+ ## Framework Patterns
49
+
50
+ ### React
51
+
52
+ ```tsx
53
+ import { useState } from 'react';
54
+ import Turnstile from '@marsidev/react-turnstile';
55
+
56
+ export default function Form() {
57
+ const [token, setToken] = useState<string | null>(null);
58
+
59
+ return (
60
+ <form onSubmit={async (e) => {
61
+ e.preventDefault();
62
+ if (!token) return;
63
+ await fetch('/api/submit', {
64
+ method: 'POST',
65
+ body: JSON.stringify({ 'cf-turnstile-response': token })
66
+ });
67
+ }}>
68
+ <Turnstile siteKey="YOUR_SITE_KEY" onSuccess={setToken} />
69
+ <button disabled={!token}>Submit</button>
70
+ </form>
71
+ );
72
+ }
73
+ ```
74
+
75
+ ### Vue / Svelte
76
+
77
+ ```vue
78
+ <!-- Vue: npm install vue-turnstile -->
79
+ <VueTurnstile :site-key="SITE_KEY" @success="token = $event" />
80
+
81
+ <!-- Svelte: npm install svelte-turnstile -->
82
+ <Turnstile siteKey={SITE_KEY} on:turnstile-callback={(e) => token = e.detail.token} />
83
+ ```
84
+
85
+ ## Server Validation
86
+
87
+ ### Cloudflare Workers
88
+
89
+ ```typescript
90
+ interface Env {
91
+ TURNSTILE_SECRET: string;
92
+ }
93
+
94
+ export default {
95
+ async fetch(request: Request, env: Env): Promise<Response> {
96
+ if (request.method !== 'POST') {
97
+ return new Response('Method not allowed', { status: 405 });
98
+ }
99
+
100
+ const formData = await request.formData();
101
+ const token = formData.get('cf-turnstile-response');
102
+
103
+ if (!token) {
104
+ return new Response('Missing token', { status: 400 });
105
+ }
106
+
107
+ // Validate token
108
+ const ip = request.headers.get('CF-Connecting-IP');
109
+ const result = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
110
+ method: 'POST',
111
+ headers: { 'Content-Type': 'application/json' },
112
+ body: JSON.stringify({
113
+ secret: env.TURNSTILE_SECRET,
114
+ response: token,
115
+ remoteip: ip
116
+ })
117
+ });
118
+
119
+ const validation = await result.json();
120
+
121
+ if (!validation.success) {
122
+ return new Response('CAPTCHA validation failed', { status: 403 });
123
+ }
124
+
125
+ // Process form...
126
+ return new Response('Success');
127
+ }
128
+ };
129
+ ```
130
+
131
+ ### Pages Functions
132
+
133
+ ```typescript
134
+ // functions/submit.ts - same pattern as Workers, use ctx.env and ctx.request
135
+ export const onRequestPost: PagesFunction<{ TURNSTILE_SECRET: string }> = async (ctx) => {
136
+ const token = (await ctx.request.formData()).get('cf-turnstile-response');
137
+ // Validate with ctx.env.TURNSTILE_SECRET (same as Workers pattern above)
138
+ };
139
+ ```
140
+
141
+ ## Advanced Patterns
142
+
143
+ ### Pre-Clearance (Invisible)
144
+
145
+ ```html
146
+ <div id="turnstile-precheck"></div>
147
+ <form id="protected-form" style="display: none;">
148
+ <button type="submit">Submit</button>
149
+ </form>
150
+
151
+ <script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"></script>
152
+ <script>
153
+ let cachedToken = null;
154
+
155
+ window.onload = () => {
156
+ window.turnstile.render('#turnstile-precheck', {
157
+ sitekey: 'YOUR_SITE_KEY',
158
+ size: 'invisible',
159
+ callback: (token) => {
160
+ cachedToken = token;
161
+ document.getElementById('protected-form').style.display = 'block';
162
+ }
163
+ });
164
+ };
165
+ </script>
166
+ ```
167
+
168
+ ### Token Refresh on Expiry
169
+
170
+ ```javascript
171
+ let widgetId = window.turnstile.render('#container', {
172
+ sitekey: 'YOUR_SITE_KEY',
173
+ 'refresh-expired': 'manual',
174
+ 'expired-callback': () => {
175
+ console.log('Token expired, refreshing...');
176
+ window.turnstile.reset(widgetId);
177
+ }
178
+ });
179
+ ```
180
+
181
+ ## Testing
182
+
183
+ ### Environment-Based Keys
184
+
185
+ ```javascript
186
+ const SITE_KEY = process.env.NODE_ENV === 'production'
187
+ ? 'YOUR_PRODUCTION_SITE_KEY'
188
+ : '1x00000000000000000000AA'; // Always passes
189
+
190
+ const SECRET_KEY = process.env.NODE_ENV === 'production'
191
+ ? process.env.TURNSTILE_SECRET
192
+ : '1x0000000000000000000000000000000AA';
193
+ ```
package/skills/cloudflare/references/vectorize/README.md ADDED
@@ -0,0 +1,133 @@
1
+ # Cloudflare Vectorize
2
+
3
+ Globally distributed vector database for AI applications. Store and query vector embeddings for semantic search, recommendations, RAG, and classification.
4
+
5
+ **Status:** Generally Available (GA) | **Last Updated:** 2026-01-27
6
+
7
+ ## Quick Start
8
+
9
+ ```typescript
10
+ // 1. Create index
11
+ // npx wrangler vectorize create my-index --dimensions=768 --metric=cosine
12
+
13
+ // 2. Configure binding (wrangler.jsonc)
14
+ // { "vectorize": [{ "binding": "VECTORIZE", "index_name": "my-index" }] }
15
+
16
+ // 3. Query vectors
17
+ const matches = await env.VECTORIZE.query(queryVector, { topK: 5 });
18
+ ```
19
+
20
+ ## Key Features
21
+
22
+ - **10M vectors per index** (V2)
23
+ - Dimensions up to 1536 (32-bit float)
24
+ - Three distance metrics: cosine, euclidean, dot-product
25
+ - Metadata filtering (up to 10 indexes)
26
+ - Namespace support (50K namespaces paid, 1K free)
27
+ - Seamless Workers AI integration
28
+ - Global distribution
29
+
30
+ ## Reading Order
31
+
32
+ | Task | Files to Read |
33
+ |------|---------------|
34
+ | New to Vectorize | README only |
35
+ | Implement feature | README + api + patterns |
36
+ | Setup/configure | README + configuration |
37
+ | Debug issues | gotchas |
38
+ | Integrate with AI | README + patterns |
39
+ | RAG implementation | README + patterns |
40
+
41
+ ## File Guide
42
+
43
+ - **README.md** (this file): Overview, quick decisions
44
+ - **api.md**: Runtime API, types, operations (query/insert/upsert)
45
+ - **configuration.md**: Setup, CLI, metadata indexes
46
+ - **patterns.md**: RAG, Workers AI, OpenAI, LangChain, multi-tenant
47
+ - **gotchas.md**: Limits, pitfalls, troubleshooting
48
+
49
+ ## Distance Metric Selection
50
+
51
+ Choose based on your use case:
52
+
53
+ ```
54
+ What are you building?
55
+ ├─ Text/semantic search → cosine (most common)
56
+ ├─ Image similarity → euclidean
57
+ ├─ Recommendation system → dot-product
58
+ └─ Pre-normalized vectors → dot-product
59
+ ```
60
+
61
+ | Metric | Best For | Score Interpretation |
62
+ |--------|----------|---------------------|
63
+ | `cosine` | Text embeddings, semantic similarity | Higher = closer (1.0 = identical) |
64
+ | `euclidean` | Absolute distance, spatial data | Lower = closer (0.0 = identical) |
65
+ | `dot-product` | Recommendations, normalized vectors | Higher = closer |
66
+
67
+ **Note:** Index configuration is immutable. Cannot change dimensions or metric after creation.
68
+
69
+ ## Multi-Tenancy Strategy
70
+
71
+ ```
72
+ How many tenants?
73
+ ├─ < 50K tenants → Use namespaces (recommended)
74
+ │ ├─ Fastest (filter before vector search)
75
+ │ └─ Strict isolation
76
+ ├─ > 50K tenants → Use metadata filtering
77
+ │ ├─ Slower (post-filter after vector search)
78
+ │ └─ Requires metadata index
79
+ └─ Per-tenant indexes → Only if compliance mandated
80
+ └─ 50K index limit per account (paid plan)
81
+ ```
82
+
83
+ ## Common Workflows
84
+
85
+ ### Semantic Search
86
+
87
+ ```typescript
88
+ // 1. Generate embedding
89
+ const result = await env.AI.run("@cf/baai/bge-base-en-v1.5", { text: [query] });
90
+
91
+ // 2. Query Vectorize
92
+ const matches = await env.VECTORIZE.query(result.data[0], {
93
+ topK: 5,
94
+ returnMetadata: "indexed"
95
+ });
96
+ ```
97
+
98
+ ### RAG Pattern
99
+
100
+ ```typescript
101
+ // 1. Generate query embedding
102
+ const embedding = await env.AI.run("@cf/baai/bge-base-en-v1.5", { text: [query] });
103
+
104
+ // 2. Search Vectorize
105
+ const matches = await env.VECTORIZE.query(embedding.data[0], { topK: 5 });
106
+
107
+ // 3. Fetch full documents from R2/D1/KV
108
+ const docs = await Promise.all(matches.matches.map(m =>
109
+ env.R2.get(m.metadata.key).then(obj => obj?.text())
110
+ ));
111
+
112
+ // 4. Generate LLM response with context
113
+ const answer = await env.AI.run("@cf/meta/llama-3-8b-instruct", {
114
+ prompt: `Context: ${docs.join("\n\n")}\n\nQuestion: ${query}\n\nAnswer:`
115
+ });
116
+ ```
117
+
118
+ ## Critical Gotchas
119
+
120
+ See `gotchas.md` for details. Most important:
121
+
122
+ 1. **Async mutations**: Inserts take 5-10s to be queryable
123
+ 2. **500 batch limit**: Workers API enforces 500 vectors per call (undocumented)
124
+ 3. **Metadata truncation**: `"indexed"` returns first 64 bytes only
125
+ 4. **topK with metadata**: Max 20 (not 100) when using returnValues or returnMetadata: "all"
126
+ 5. **Metadata indexes first**: Must create before inserting vectors
127
+
128
+ ## Resources
129
+
130
+ - [Official Docs](https://developers.cloudflare.com/vectorize/)
131
+ - [Client API Reference](https://developers.cloudflare.com/vectorize/reference/client-api/)
132
+ - [Workers AI Models](https://developers.cloudflare.com/workers-ai/models/#text-embeddings)
133
+ - [Discord: #vectorize](https://discord.cloudflare.com)
package/skills/cloudflare/references/vectorize/api.md ADDED
@@ -0,0 +1,88 @@
1
+ # Vectorize API Reference
2
+
3
+ ## Types
4
+
5
+ ```typescript
6
+ interface VectorizeVector {
7
+ id: string; // Max 64 bytes
8
+ values: number[]; // Must match index dimensions
9
+ namespace?: string; // Optional partition (max 64 bytes)
10
+ metadata?: Record<string, any>; // Max 10 KiB
11
+ }
12
+ ```
13
+
14
+ ## Query
15
+
16
+ ```typescript
17
+ const matches = await env.VECTORIZE.query(queryVector, {
18
+ topK: 10, // Max 100 (or 20 with returnValues/returnMetadata:"all")
19
+ returnMetadata: "indexed", // "none" | "indexed" | "all"
20
+ returnValues: false,
21
+ namespace: "tenant-123",
22
+ filter: { category: "docs" }
23
+ });
24
+ // matches.matches[0] = { id, score, metadata? }
25
+ ```
26
+
27
+ **returnMetadata:** `"none"` (fastest) → `"indexed"` (recommended) → `"all"` (topK max 20)
28
+
29
+ **queryById (V2 only):** Search using existing vector as query.
30
+ ```typescript
31
+ await env.VECTORIZE.queryById("doc-123", { topK: 5 });
32
+ ```
33
+
34
+ ## Insert/Upsert
35
+
36
+ ```typescript
37
+ // Insert: ignores duplicates (keeps first)
38
+ await env.VECTORIZE.insert([{ id, values, metadata }]);
39
+
40
+ // Upsert: overwrites duplicates (keeps last)
41
+ await env.VECTORIZE.upsert([{ id, values, metadata }]);
42
+ ```
43
+
44
+ **Max 1,000 vectors per call (Workers) / 5,000 (HTTP API).** Queryable after 5-10 seconds.
45
+
46
+ ## Other Operations
47
+
48
+ ```typescript
49
+ // Get by IDs
50
+ const vectors = await env.VECTORIZE.getByIds(["id1", "id2"]);
51
+
52
+ // Delete (max 1000 IDs per call)
53
+ await env.VECTORIZE.deleteByIds(["id1", "id2"]);
54
+
55
+ // Index info
56
+ const info = await env.VECTORIZE.describe();
57
+ // { dimensions, metric, vectorCount }
58
+ ```
59
+
60
+ ## Filtering
61
+
62
+ Requires metadata index. Filter operators:
63
+
64
+ | Operator | Example |
65
+ |----------|---------|
66
+ | `$eq` (implicit) | `{ category: "docs" }` |
67
+ | `$ne` | `{ status: { $ne: "deleted" } }` |
68
+ | `$in` / `$nin` | `{ tag: { $in: ["sale"] } }` |
69
+ | `$lt`, `$lte`, `$gt`, `$gte` | `{ price: { $lt: 100 } }` |
70
+
71
+ **Constraints:** Max 2048 bytes, no dots/`$` in keys, values: string/number/boolean/null.
72
+
73
+ ## Performance
74
+
75
+ | Configuration | topK Limit | Speed |
76
+ |--------------|------------|-------|
77
+ | No metadata | 100 | Fastest |
78
+ | `returnMetadata: "indexed"` | 100 | Fast |
79
+ | `returnMetadata: "all"` | 20 | Slower |
80
+ | `returnValues: true` | 20 | Slower |
81
+
82
+ **Batch operations:** Always batch (1,000/call via Workers, 5,000 via HTTP API) for optimal throughput.
83
+
84
+ ```typescript
85
+ for (let i = 0; i < vectors.length; i += 1000) {
86
+ await env.VECTORIZE.upsert(vectors.slice(i, i + 1000));
87
+ }
88
+ ```
package/skills/cloudflare/references/vectorize/configuration.md ADDED
@@ -0,0 +1,88 @@
1
+ # Vectorize Configuration
2
+
3
+ ## Create Index
4
+
5
+ ```bash
6
+ npx wrangler vectorize create my-index --dimensions=768 --metric=cosine
7
+ ```
8
+
9
+ **⚠️ Dimensions and metric are immutable** - cannot change after creation.
10
+
11
+ ## Worker Binding
12
+
13
+ ```jsonc
14
+ // wrangler.jsonc
15
+ {
16
+ "vectorize": [
17
+ { "binding": "VECTORIZE", "index_name": "my-index" }
18
+ ]
19
+ }
20
+ ```
21
+
22
+ ```typescript
23
+ interface Env {
24
+ VECTORIZE: Vectorize;
25
+ }
26
+ ```
27
+
28
+ ## Metadata Indexes
29
+
30
+ **Must create BEFORE inserting vectors** - existing vectors not retroactively indexed.
31
+
32
+ ```bash
33
+ wrangler vectorize create-metadata-index my-index --property-name=category --type=string
34
+ wrangler vectorize create-metadata-index my-index --property-name=price --type=number
35
+ ```
36
+
37
+ | Type | Use For |
38
+ |------|---------|
39
+ | `string` | Categories, tags (first 64 bytes indexed) |
40
+ | `number` | Prices, timestamps |
41
+ | `boolean` | Flags |
42
+
43
+ ## CLI Commands
44
+
45
+ ```bash
46
+ # Index management
47
+ wrangler vectorize list
48
+ wrangler vectorize info <index-name>
49
+ wrangler vectorize delete <index-name>
50
+
51
+ # Vector operations
52
+ wrangler vectorize insert <index-name> --file=embeddings.ndjson
53
+ wrangler vectorize get <index-name> --ids=id1,id2
54
+ wrangler vectorize delete-by-ids <index-name> --ids=id1,id2
55
+
56
+ # Metadata indexes
57
+ wrangler vectorize list-metadata-index <index-name>
58
+ wrangler vectorize delete-metadata-index <index-name> --property-name=field
59
+ ```
60
+
61
+ ## Bulk Upload (NDJSON)
62
+
63
+ ```json
64
+ {"id": "1", "values": [0.1, 0.2, ...], "metadata": {"category": "docs"}}
65
+ {"id": "2", "values": [0.4, 0.5, ...], "namespace": "tenant-abc"}
66
+ ```
67
+
68
+ **Limits:** 5000 vectors per file, 100 MB max
69
+
70
+ ## Cardinality Best Practice
71
+
72
+ Bucket high-cardinality data:
73
+ ```typescript
74
+ // ❌ Millisecond timestamps
75
+ metadata: { timestamp: Date.now() }
76
+
77
+ // ✅ 5-minute buckets
78
+ metadata: { timestamp_bucket: Math.floor(Date.now() / 300000) * 300000 }
79
+ ```
80
+
81
+ ## Production Checklist
82
+
83
+ 1. Create index with correct dimensions
84
+ 2. Create metadata indexes FIRST
85
+ 3. Test bulk upload
86
+ 4. Configure bindings
87
+ 5. Deploy Worker
88
+ 6. Verify queries
package/skills/cloudflare/references/vectorize/gotchas.md ADDED
@@ -0,0 +1,76 @@
1
+ # Vectorize Gotchas
2
+
3
+ ## Critical Warnings
4
+
5
+ ### Async Mutations
6
+ Insert/upsert/delete return immediately but vectors aren't queryable for 5-10 seconds.
7
+
8
+ ### Batch Size Limit
9
+ **Workers API: 1,000 vectors max per call (HTTP API: 5,000).** Silently truncates if exceeded.
10
+
11
+ ```typescript
12
+ // ✅ Chunk into 1000 (Workers API limit; HTTP API allows 5000)
13
+ for (let i = 0; i < vectors.length; i += 1000) {
14
+ await env.VECTORIZE.upsert(vectors.slice(i, i + 1000));
15
+ }
16
+ ```
17
+
18
+ ### Metadata Truncation
19
+ `returnMetadata: "indexed"` returns only first 64 bytes of strings. Use `"all"` for complete metadata (but max topK drops to 20).
20
+
21
+ ### topK Limits
22
+
23
+ | returnMetadata | returnValues | Max topK |
24
+ |----------------|--------------|----------|
25
+ | `"none"` / `"indexed"` | `false` | 100 |
26
+ | `"all"` | any | **20** |
27
+ | any | `true` | **20** |
28
+
29
+ ### Metadata Indexes First
30
+ Create BEFORE inserting - existing vectors not retroactively indexed.
31
+
32
+ ```bash
33
+ # ✅ Create index FIRST
34
+ wrangler vectorize create-metadata-index my-index --property-name=category --type=string
35
+ wrangler vectorize insert my-index --file=data.ndjson
36
+ ```
37
+
38
+ ### Index Config Immutable
39
+ Cannot change dimensions/metric after creation. Must create new index and migrate.
40
+
41
+ ## Limits (V2)
42
+
43
+ | Resource | Limit |
44
+ |----------|-------|
45
+ | Vectors per index | 10,000,000 |
46
+ | Max dimensions | 1536 |
47
+ | Batch upsert (Workers / HTTP API) | **1,000 / 5,000** |
48
+ | Indexed string metadata | **64 bytes** |
49
+ | Metadata indexes | 10 |
50
+ | Namespaces | 50,000 (paid) / 1,000 (free) |
51
+
52
+ ## Common Mistakes
53
+
54
+ 1. **Wrong embedding shape:** Extract `result.data[0]` from Workers AI
55
+ 2. **Metadata index after data:** Re-upsert all vectors
56
+ 3. **Insert vs upsert:** `insert` ignores duplicates, `upsert` overwrites
57
+ 4. **Not batching:** Individual inserts ~1K/min, batched ~200K+/min
58
+
59
+ ## Troubleshooting
60
+
61
+ **No results?**
62
+ - Wait 5-10s after insert
63
+ - Check namespace spelling (case-sensitive)
64
+ - Verify metadata index exists
65
+ - Check dimension mismatch
66
+
67
+ **Metadata filter not working?**
68
+ - Index must exist before data insert
69
+ - Strings >64 bytes truncated
70
+ - Use dot notation for nested: `"product.category"`
71
+
72
+ ## Model Dimensions
73
+
74
+ - `@cf/baai/bge-small-en-v1.5`: 384
75
+ - `@cf/baai/bge-base-en-v1.5`: 768
76
+ - `@cf/baai/bge-large-en-v1.5`: 1024
package/skills/cloudflare/references/vectorize/patterns.md ADDED
@@ -0,0 +1,90 @@
1
+ # Vectorize Patterns
2
+
3
+ ## Workers AI Integration
4
+
5
+ ```typescript
6
+ // Generate embedding + query
7
+ const result = await env.AI.run("@cf/baai/bge-base-en-v1.5", { text: [query] });
8
+ const matches = await env.VECTORIZE.query(result.data[0], { topK: 5 }); // Pass data[0]!
9
+ ```
10
+
11
+ | Model | Dimensions |
12
+ |-------|------------|
13
+ | `@cf/baai/bge-small-en-v1.5` | 384 |
14
+ | `@cf/baai/bge-base-en-v1.5` | 768 (recommended) |
15
+ | `@cf/baai/bge-large-en-v1.5` | 1024 |
16
+
17
+ ## OpenAI Integration
18
+
19
+ ```typescript
20
+ const response = await openai.embeddings.create({ model: "text-embedding-ada-002", input: query });
21
+ const matches = await env.VECTORIZE.query(response.data[0].embedding, { topK: 5 });
22
+ ```
23
+
24
+ ## RAG Pattern
25
+
26
+ ```typescript
27
+ // 1. Embed query
28
+ const emb = await env.AI.run("@cf/baai/bge-base-en-v1.5", { text: [query] });
29
+
30
+ // 2. Search vectors
31
+ const matches = await env.VECTORIZE.query(emb.data[0], { topK: 5, returnMetadata: "indexed" });
32
+
33
+ // 3. Fetch full docs from R2/D1/KV
34
+ const docs = await Promise.all(matches.matches.map(m => env.R2.get(m.metadata.key).then(o => o?.text())));
35
+
36
+ // 4. Generate with context
37
+ const answer = await env.AI.run("@cf/meta/llama-3-8b-instruct", {
38
+ prompt: `Context:\n${docs.filter(Boolean).join("\n\n")}\n\nQuestion: ${query}\n\nAnswer:`
39
+ });
40
+ ```
41
+
42
+ ## Multi-Tenant
43
+
44
+ ### Namespaces (< 50K tenants, fastest)
45
+
46
+ ```typescript
47
+ await env.VECTORIZE.upsert([{ id: "1", values: emb, namespace: `tenant-${id}` }]);
48
+ await env.VECTORIZE.query(vec, { namespace: `tenant-${id}`, topK: 10 });
49
+ ```
50
+
51
+ ### Metadata Filter (> 50K tenants)
52
+
53
+ ```bash
54
+ wrangler vectorize create-metadata-index my-index --property-name=tenantId --type=string
55
+ ```
56
+
57
+ ```typescript
58
+ await env.VECTORIZE.upsert([{ id: "1", values: emb, metadata: { tenantId: id } }]);
59
+ await env.VECTORIZE.query(vec, { filter: { tenantId: id }, topK: 10 });
60
+ ```
61
+
62
+ ## Hybrid Search
63
+
64
+ ```typescript
65
+ const matches = await env.VECTORIZE.query(vec, {
66
+ topK: 20,
67
+ filter: {
68
+ category: { $in: ["tech", "science"] },
69
+ published: { $gte: lastMonthTimestamp }
70
+ }
71
+ });
72
+ ```
73
+
74
+ ## Batch Ingestion
75
+
76
+ ```typescript
77
+ const BATCH = 500;
78
+ for (let i = 0; i < vectors.length; i += BATCH) {
79
+ await env.VECTORIZE.upsert(vectors.slice(i, i + BATCH));
80
+ }
81
+ ```
82
+
83
+ ## Best Practices
84
+
85
+ 1. **Pass `data[0]`** not `data` or full response
86
+ 2. **Batch 500** vectors per upsert
87
+ 3. **Create metadata indexes** before inserting
88
+ 4. **Use namespaces** for tenant isolation (faster than filters)
89
+ 5. **`returnMetadata: "indexed"`** for best speed/data balance
90
+ 6. **Handle 5-10s mutation delay** in async operations